fix: clarify TS Docs for better DX

[taefi]

Fixes #2936

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.60%. Comparing base (6df5776) to head (05bc716).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3076   +/-   ##
=======================================
  Coverage   92.60%   92.60%           
=======================================
  Files          85       85           
  Lines        3164     3164           
  Branches      775      775           
=======================================
  Hits         2930     2930           
  Misses        183      183           
  Partials       51       51           

Flag	Coverage Δ
unittests	92.60% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[cromoteca]

I'd prefer to rollback this change as types are to be preferred to interfaces.

[taefi]

I know about the general preference of types over interfaces, but I explained the motivation for this change internally, here: https://vaadin.slack.com/archives/C01EJJNMAC9/p1736339840532009

[cromoteca]

IDEs can definitely propose types, so it must be a glitch in your own IDE. Or maybe the solution is the export you added in index.ts. But I'd still like to keep it as a type.