We're using composables, which are functions that supply some kind of useful behavior to components, to house reusable bits of code that can be not only shared across the Codex library, but are exported for use by library users. Just as we're documenting components, we should document these composables on the VitePress site.
We have a "composables" section of the site under "toolkit" that currently contains docs for one composable, useModelWrapper. We considered trying to automatically generate docs based on the comments in the composable file, but decided that manually writing docs was more lightweight.
Composables to include
Not all composables are that useful to Codex users - we should decide which we want to include.
| Composable | Description | Discussion | Add docs? |
| useComputedDirection | Returns the directionality of an element based on its surrounding context | Is there an equivalent/existing mw util for this? | Yes |
| useComputedDisabled | Determines if an element should be disabled based on its disabled prop and a provided disabled value | Internal/Codex-specific | No |
| useComputedLanguage | Returns the lang of an element based on its surrounding context | Is there an equivalent/existing mw util for this? | Yes |
| useFieldData | Returns computed disabled, status, and id for form field inputs | Internal/Codex-specific | No |
| useFloatingMenu | Implements FloatingUI for positioning (and eventually sizing/flipping) of overlays like menus and popups | It has some Codex-specific settings. That said, it could help anyone implementing a custom menu component. Also - do we want folks using this outside of Codex? | ? |
| useGeneratedId | Returns an ID for use in HTML templates with optional prefix | Useful, but we plan on re-implementing this a different way | Not now; do as part of T309669 |
| useIconOnlyButton | Throws a warning if a button is icon-only and has no accessible label | Probably only useful in a library like Codex | No |
| useIntersectionObserver | Uses IntersectionObserver to return a boolean ref that provides the current intersection status of the provided template ref | Could be useful outside of Codex. Might be better to have a library in MediaWiki of Codex-agnostic composables, or VueUse? | Consider documenting for now, maybe replace with VueUse later |
| useLabelChecker | Throws a warning if the component has no default slot contents or specific aria attributes | Internal/Codex-specific | No |
| useModelWrapper | Returns a computed property that wraps a value provided with v-model and updates it on change; enabling binding of a v-model prop to an input in the template via v-model | Useful outside of Codex, also probably provided in VueUse | Already documented |
| useResizeObserver | Returns a ref with width and height properties of a template ref | Could be useful outside of Codex. Could extend the composable to return more data, or use the VueUse version. | Consider documenting for now, maybe replace with VueUse later |
| useSlotContents | Returns an array of flattened slot contents | Could be useful outside of Codex | Yes |
| useSplitAttributes | Passes most attributes bound to the component to a child element, like an input | Only useful for reusable components. Could be used in a future MediaWiki component library? | Not for now |
| useWarnOnce | Posts a warning message only once after the component is mounted | Probably not useful outside of Codex | No |
Full list of composables to document:
- useComputedDirection
- useComputedLanguage
- (maybe) useFloatingMenu
- useIntersectionObserver
- useResizeObserver
- useSlotContents
Acceptance criteria
- Composables are clearly and helpfully documented on the VitePress site