✨ table-controls: factor out duplicated code via new usePersistentState hook + misc cleanup + add initial documentation (DOCS.md and JSDoc comments)

[mturley]

Before this is merged, the DOCS.md file is easier to read by directly viewing the markdown-rendered file on my fork.

This PR got larger than I anticipated... my goal was to write thorough JSDoc comments and combine the state providers with usePersistentState, but as I documented things I wanted to change I decided to just go ahead and change them. My sincere apologies for my self-indulgence and the size of the PR. When you pull on one thread, there's always another. and another...

• Adds a comprehensive write-up of the rationale, use, and technical details of the table-control hooks and components in DOCS.md.
• Adds JSDoc comments to all files in table-controls for hooks, components and helpers as well as arguments/options and return values of each of these.
• Adds @deprecated JSDoc comments to the old useLegacyFilterState, useLegacySortState and useLegacyPaginationState hooks with explanations.
• Refactors a number of things:
  • On main currently, each of the use[Feature]State hooks is separated into two almost identical hooks use[Feature]State and use[Feature]UrlParams which call useState or useUrlParams directly. This is a lot of duplicated code, including some duplicated business logic. This PR creates the usePersistentState hook which is a replacement for React.useState that can conditionally persist the state to URL params, localStorage or sessionStorage. This allows us to combine each feature's two state hooks into one use[Feature]State hook which takes a persistTo argument for configuring the state storage location.
  • There are a number of miscellaneous changes to polish the type definitions and ways types are used across the implementation, including inheriting certain types from others in a maintainable way. This could probably use some continued attention after this PR but it is an improvement.
  • The file structure and naming conventions across all features have been adjusted/renamed/refactored to be consistent.
  • The useTableControlProps hook was not fully separated along feature concerns. Some feature-specific code that was in there is moved to a use[Feature]PropHelpers function, and other older get[Feature]Props or use[Feature]Props functions are refactored to share this naming convention.
  • The features of the hooks are now opt-in and enabled with boolean is[Feature]Enabled arguments passed to either useTableControlState or useLocalTableControls. Using the utility type DiscriminatedArgs and the power of TypeScript discriminated unions, any feature-specific args for the hooks are only required by TypeScript if that is[Feature]Enabled arg is true. This ensures the consumer doesn't forget anything when enabling and configuring features (for example, enabling the sort feature and forgetting to specify sortableColumns used to cause sorting to silently fail and now raises a type error).
  • I am likely forgetting stuff, this PR went on way too long. Sorry again about that.

[codecov]

Codecov Report

Attention: 269 lines in your changes are missing coverage. Please review.

Comparison is base (abafafa) 40.72% compared to head (9e0146f) 40.31%.

❗ Current head 9e0146f differs from pull request most recent head 06546cb. Consider uploading reports for the commit 06546cb to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1355      +/-   ##
==========================================
- Coverage   40.72%   40.31%   -0.41%     
==========================================
  Files         139      143       +4     
  Lines        4469     4524      +55     
  Branches     1069     1108      +39     
==========================================
+ Hits         1820     1824       +4     
- Misses       2554     2603      +49     
- Partials       95       97       +2     

Flag	Coverage Δ
client	40.31% <19.70%> (-0.41%)	⬇️
server	∅ <ø> (∅)

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

Files	Coverage Δ
client/src/app/Constants.ts	100.00% <100.00%> (ø)
.../src/app/hooks/table-controls/active-item/index.ts	100.00% <100.00%> (ø)
...nt/src/app/hooks/table-controls/expansion/index.ts	100.00% <100.00%> (ø)
...le-controls/filtering/getFilterHubRequestParams.ts	10.93% <ø> (ø)
...nt/src/app/hooks/table-controls/filtering/index.ts	100.00% <100.00%> (ø)
...rc/app/hooks/table-controls/getHubRequestParams.ts	41.66% <ø> (ø)
client/src/app/hooks/table-controls/index.ts	100.00% <100.00%> (ø)
...ntrols/pagination/getPaginationHubRequestParams.ts	16.66% <ø> (ø)
...t/src/app/hooks/table-controls/pagination/index.ts	100.00% <100.00%> (ø)
.../table-controls/sorting/getSortHubRequestParams.ts	18.18% <ø> (ø)
... and 28 more

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

[ibolton336]

Looking great @mturley. Thanks for all of the hard work on this. The docs are going to be a lifesaver.