Require routing param for controlled pagination

[zamoore]

📌 Summary

If merged, this PR will require that consumers of our pagination components (
Hds::Pagination::Compact & Hds::Pagination::Numbered) provide at least 1 routing argument
(@model, @models, or @route) when routing is controlled externally.

🛠️ Detailed description

• Added new assertions in component constructors that ensure the above
• Added some discriminated union types to the pagination type definitions that make it more clear when certain arguments are required.

Questions

• How to we communicate this required-if behavior to the user in the docs? Is what we have enough?
• The discriminated union types seem to work in TS not with Glint. (IE, if I try to instantiate a pagination component with @onPageChange but omit routing params, I get no TS errors, but if I try to create an object with the same type in the component file, I get the expected errors.

🔗 External links

Jira ticket: HDS-3439

---

👀 Component checklist

• Percy was checked for any visual regression
• A changelog entry was added via Changesets if needed (see templates here)

💬 Please consider using conventional comments when reviewing this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	Sep 13, 2024 4:31pm
hds-website	✅ Ready (Inspect)	Visit Preview	Sep 13, 2024 4:31pm

[shleewhite]

Looks good! Just a couple nit comments.

[alex-ju]

Looks good overall. Clearer type abstractions! Aside from the warning I would also update the Component API section stating when route/model/models is required.

Would this change also apply to replace or only relevant to route/model/models?

How to we communicate this required-if behavior to the user in the docs? Is what we have enough?

I believe the warning and flagging this in the component API section is the best we can do for now

The discriminated union types seem to work in TS not with Glint. (IE, if I try to instantiate a pagination component with @onPageChange but omit routing params, I get no TS errors, but if I try to create an object with the same type in the component file, I get the expected errors.

I've been running into this as well. I don't have a solution at the moment, hopefully the documentation will help.

[zamoore]

@alex-ju

Would this change also apply to replace or only relevant to route/model/models?

I don't believe that providing the replace argument should be required in any scenario. It should always be optional.