Page MenuHomePhabricator

Document Codex Composables
Open, In Progress, LowPublic2 Estimated Story Points


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.

ComposableDescriptionDiscussionAdd docs?
useComputedDirectionReturns the directionality of an element based on its surrounding contextIs there an equivalent/existing mw util for this?Yes
useComputedDisabledDetermines if an element should be disabled based on its disabled prop and a provided disabled valueInternal/Codex-specificNo
useComputedLanguageReturns the lang of an element based on its surrounding contextIs there an equivalent/existing mw util for this?Yes
useFieldDataReturns computed disabled, status, and id for form field inputsInternal/Codex-specificNo
useFloatingMenuImplements FloatingUI for positioning (and eventually sizing/flipping) of overlays like menus and popupsIt 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??
useGeneratedIdReturns an ID for use in HTML templates with optional prefixUseful, but we plan on re-implementing this a different wayNot now; do as part of T309669
useIconOnlyButtonThrows a warning if a button is icon-only and has no accessible labelProbably only useful in a library like CodexNo
useIntersectionObserverUses IntersectionObserver to return a boolean ref that provides the current intersection status of the provided template refCould 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
useLabelCheckerThrows a warning if the component has no default slot contents or specific aria attributesInternal/Codex-specificNo
useModelWrapperReturns 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-modelUseful outside of Codex, also probably provided in VueUseAlready documented
useResizeObserverReturns a ref with width and height properties of a template refCould 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
useSlotContentsReturns an array of flattened slot contentsCould be useful outside of CodexYes
useSplitAttributesPasses most attributes bound to the component to a child element, like an inputOnly useful for reusable components. Could be used in a future MediaWiki component library?Not for now
useWarnOncePosts a warning message only once after the component is mountedProbably not useful outside of CodexNo

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

Event Timeline

AnneT removed AnneT as the assignee of this task.Mar 9 2022, 11:00 PM
STH renamed this task from Document Codex composables to [Ready for Development] Document Codex composables.Apr 15 2022, 9:32 PM
STH renamed this task from [Ready for Development] Document Codex composables to Document Codex Composables.Apr 26 2022, 12:07 AM
STH triaged this task as Low priority.
Catrope raised the priority of this task from Low to High.Sep 12 2022, 8:30 AM
Catrope moved this task from Backlog to Up Next on the Design-Systems-Team board.
ldelench_wmf set the point value for this task to 3.Sep 19 2022, 3:36 PM
ldelench_wmf lowered the priority of this task from High to Medium.Oct 24 2022, 4:38 PM
ldelench_wmf lowered the priority of this task from Medium to Low.Nov 7 2022, 5:31 PM
ldelench_wmf moved this task from Up Next to Backlog on the Design-Systems-Team board.

All in favor of auto-generated documentation but I decided to start with some manually generated docs for this in T334497 until the auto-generation mechanisms are in place.

AnneT updated the task description. (Show Details)

Change 961479 had a related patch set uploaded (by LWatson; author: LWatson):

[design/codex@main] docs: Document Codex Composables

Volker_E changed the task status from Open to In Progress.Fri, Sep 29, 11:46 PM