diff --git a/client/src/app/hooks/table-controls/DOCS.md b/client/src/app/hooks/table-controls/DOCS.md index 8873ab68f9..967964afe0 100644 --- a/client/src/app/hooks/table-controls/DOCS.md +++ b/client/src/app/hooks/table-controls/DOCS.md @@ -12,7 +12,7 @@ The table-controls hooks and components provide a pattern where state logic can - Featureful tables should be easy to implement with code that is short and readable without sacrificing composability and refactorability. - The consumer should be able to override any and all props manually on any element of the table. If there is a future need for table state to be used for rendering in a way we don't currently anticipate, that should not be blocked by this abstraction. -- Client-paginated and server-paginated tables should be similar to implement and share reusable. If a table needs to be converted between client logic and server logic, that should be relatively easy. +- Client-paginated and server-paginated tables should be similar to implement and share reusable code. If a table needs to be converted between client logic and server logic, that should be relatively easy. - There should not be a concept of a "row object" because rows are presentational details and defining them as a separate model from the API data causes unnecessary complexity. See [Item Objects, Not Row Objects](#item-objects-not-row-objects). - Strict TypeScript types with generics inferred from parameters should be used to provide a safe and convenient development experience without having to repeat type annotations all over the page-level code. - All features should be optional and fall back to reasonable defaults if their options are omitted. @@ -26,7 +26,7 @@ Note that filtering, sorting and pagination are special because they must be per The state used by these features can be stored either in React state (provided by `use[Feature]State` hooks) or in the browser's URL query parameters (provided by `use[Feature]UrlParams` hooks). If URL params are used, the user's current filters, sort, pagination state, expanded/active rows and more are preserved when reloading the browser, using the browser Back and Forward buttons, or loading a bookmark. -> ⚠️ TECH DEBT NOTE: This URL param behavior is currently all-or-nothing if you're using the higher-level hooks and not available when using the shorthand hook `useLocalTableControls`. This is because the generic hook for manipulating URL params (`useUrlParams`) cannot be used conditionally. We may want to refactor this later such that we have a hook like `useStateOrUrlParams` and make URL params opt-in on a feature-by-feature basis. This would also mean we could combine the `useTableControlState` and `useTableControlUrlParams` which currently are interchangeable, as well as combine each set of `use[Feature]State` and `use[Feature]UrlParams` hooks. See [Hooks and Helper Functions](#hooks-and-helper-functions). +> ⚠️ TECH DEBT NOTE: This URL param behavior is currently all-or-nothing if you're using the higher-level hooks and not available when using the shorthand hook `useLocalTableControls`. This is because the generic hook for manipulating URL params (`useUrlParams`) cannot be used conditionally. We may want to refactor this later such that we have a hook like `useStateOrUrlParams` and make URL params opt-in on a feature-by-feature basis. This would also mean we could combine `useTableControlState` and `useTableControlUrlParams` which currently are interchangeable, as well as combine each set of `use[Feature]State` and `use[Feature]UrlParams` hooks. See [Hooks and Helper Functions](#hooks-and-helper-functions). All of the hooks and helpers described in this section are used internally by the higher-level hooks and helpers, and do not need to be used directly (see [Hooks and Helper Functions](#hooks-and-helper-functions) and [Usage](#usage)).