An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): dense translations for hooks (loader support + 18 hook docsDense) (#2641)
Joey1aa230370bfd
diff --git a/packages/cli/src/lib/component-loader.mjs b/packages/cli/src/lib/component-loader.mjsindex 672b8d39b9..848a4cc7d0 100644--- a/packages/cli/src/lib/component-loader.mjs+++ b/packages/cli/src/lib/component-loader.mjs@@ -6,7 +6,7 @@import {pathToFileURL} from 'node:url';-function mergeTranslation(docs, translation) {+export function mergeTranslation(docs, translation) {if (!translation) return docs;const merged = {...docs};@@ -30,6 +30,26 @@ function mergeTranslation(docs, translation) {});}+ // Merge hook param descriptions (HookTranslationDoc). Params are an array of+ // {name, type, description, required}; override description by name where the+ // translation has an entry. Names may include dots (e.g. 'options.isActive');+ // the lookup is keyed by the exact param name.+ if (translation.paramDescriptions && merged.params) {+ merged.params = merged.params.map(param => {+ const desc = translation.paramDescriptions[param.name];+ return desc != null ? {...param, description: desc} : param;+ });+ }++ // Merge hook return descriptions (HookTranslationDoc). Returns are an array+ // of {name, type, description}; override description by name where present.+ if (translation.returnDescriptions && merged.returns) {+ merged.returns = merged.returns.map(ret => {+ const desc = translation.returnDescriptions[ret.name];+ return desc != null ? {...ret, description: desc} : ret;+ });+ }+// Merge sub-component translationsif (translation.components && merged.components) {merged.components = merged.components.map((comp, i) => {diff --git a/packages/cli/src/lib/component-loader.test.mjs b/packages/cli/src/lib/component-loader.test.mjsnew file mode 100644index 0000000000..a6d2479eb9--- /dev/null+++ b/packages/cli/src/lib/component-loader.test.mjs@@ -0,0 +1,107 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Tests for mergeTranslation — overlaying translation docs onto base docs.+ *+ * Covers the hook param/return description merge (HookTranslationDoc) added so+ * dense translations of hook params/returns are actually consumed, plus a+ * regression guard for the existing component prop-description merge.+ */++import {describe, it, expect} from 'vitest';+import {mergeTranslation} from './component-loader.mjs';++/** Minimal HookDoc-shaped fixture with params + returns. */+function hookDocs() {+ return {+ name: 'useFocusTrap',+ usage: {description: 'English description.'},+ params: [+ {name: 'options', type: 'UseFocusTrapOptions', description: 'Config object.', required: true},+ {name: 'options.isActive', type: 'boolean', description: 'Whether active.', required: true},+ {name: 'options.onEscape', type: '() => void', description: 'Escape callback.', required: false},+ ],+ returns: [+ {name: 'containerRef', type: 'React.RefObject<HTMLElement | null>', description: 'Ref to attach.'},+ {name: 'focusFirst', type: '() => void', description: 'Focuses first element.'},+ ],+ };+}++describe('mergeTranslation — hook param/return descriptions', () => {+ it('overrides param and return descriptions by name, preserving other fields', () => {+ const merged = mergeTranslation(hookDocs(), {+ paramDescriptions: {+ options: 'Cfg.',+ 'options.onEscape': 'Esc cb.',+ },+ returnDescriptions: {+ containerRef: 'Attach ref.',+ },+ });++ // Translated params get the compressed description.+ const options = merged.params.find(p => p.name === 'options');+ expect(options.description).toBe('Cfg.');+ expect(options.type).toBe('UseFocusTrapOptions');+ expect(options.required).toBe(true);++ // Untranslated param keeps original description.+ const isActive = merged.params.find(p => p.name === 'options.isActive');+ expect(isActive.description).toBe('Whether active.');+ expect(isActive.required).toBe(true);++ // Translated return.+ const containerRef = merged.returns.find(r => r.name === 'containerRef');+ expect(containerRef.description).toBe('Attach ref.');+ expect(containerRef.type).toBe('React.RefObject<HTMLElement | null>');++ // Untranslated return unchanged.+ const focusFirst = merged.returns.find(r => r.name === 'focusFirst');+ expect(focusFirst.description).toBe('Focuses first element.');+ });++ it('overrides a nested (dotted) param name correctly', () => {+ const merged = mergeTranslation(hookDocs(), {+ paramDescriptions: {'options.isActive': 'Active?'},+ });++ const isActive = merged.params.find(p => p.name === 'options.isActive');+ expect(isActive.description).toBe('Active?');+ expect(isActive.type).toBe('boolean');++ // Sibling params untouched.+ expect(merged.params.find(p => p.name === 'options').description).toBe('Config object.');+ });++ it('leaves params/returns untouched when translation has no param/return descriptions', () => {+ const base = hookDocs();+ const merged = mergeTranslation(base, {usage: {description: 'Dense desc.'}});++ expect(merged.params).toEqual(base.params);+ expect(merged.returns).toEqual(base.returns);+ expect(merged.usage.description).toBe('Dense desc.');+ });+});++describe('mergeTranslation — component prop descriptions (regression)', () => {+ it('overrides prop descriptions by name, leaving others unchanged', () => {+ const docs = {+ name: 'Button',+ usage: {description: 'English.'},+ props: [+ {name: 'variant', type: 'string', description: 'The variant.'},+ {name: 'disabled', type: 'boolean', description: 'Disabled state.'},+ ],+ };++ const merged = mergeTranslation(docs, {+ usage: {description: 'Dense.'},+ propDescriptions: {variant: 'Vrnt.'},+ });++ expect(merged.usage.description).toBe('Dense.');+ expect(merged.props.find(p => p.name === 'variant').description).toBe('Vrnt.');+ expect(merged.props.find(p => p.name === 'disabled').description).toBe('Disabled state.');+ });+});diff --git a/packages/core/src/Collapsible/useXDSCollapsible.doc.mjs b/packages/core/src/Collapsible/useXDSCollapsible.doc.mjsindex 18bc9195b8..9a45695503 100644--- a/packages/core/src/Collapsible/useXDSCollapsible.doc.mjs+++ b/packages/core/src/Collapsible/useXDSCollapsible.doc.mjs@@ -48,3 +48,25 @@ export const docs = {importPath: '@xds/core/Collapsible',category: 'interaction',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description: 'Encapsulates collapsible state machine. 3 modes: group-controlled (inside XDSCollapsibleGroup), controlled (isOpen + onOpenChange), uncontrolled (self-managed w/ defaultIsOpen). Used internally by XDSCard + XDSSection.',+ paramDescriptions: {+ isCollapsible: 'enable collapsible behavior. true = self-managed (starts open). Pass config object for controlled mode / custom defaults.',+ value: 'unique id within XDSCollapsibleGroup. When present + inside group, state managed by group.',+ },+ returnDescriptions: {+ isEnabled: 'whether collapsible behavior active.',+ isOpen: 'whether content currently expanded.',+ toggle: 'toggle open/closed. Dispatches to group, controlled callback / internal state.',+ },+ usage: {+ description: 'Encapsulates collapsible state machine. 3 modes: group-controlled (inside XDSCollapsibleGroup), controlled (isOpen + onOpenChange), uncontrolled (self-managed w/ defaultIsOpen). Used internally by XDSCard + XDSSection.',+ bestPractices: [+ {guidance: true, description: 'Use directly when building custom collapsible components needing XDS collapsible behavior w/o XDSCollapsible wrapper.'},+ {guidance: true, description: 'For accordion behavior, wrap items in XDSCollapsibleGroup + pass unique value props.'},+ {guidance: false, description: 'Implement your own open/close state when useXDSCollapsible already provides it — hook handles group coordination automatically.'},+ ],+ },+};diff --git a/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs b/packages/core/src/HoverCard/useXDSHoverCard.doc.mjsindex 70bdd913f9..14b1643427 100644--- a/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs+++ b/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs@@ -67,3 +67,28 @@ export const docs = {importPath: '@xds/core/HoverCard',category: 'interaction',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description: 'Headless hook for hover-triggered floating cards. Builds on useXDSLayer w/ hover/focus intent detection, delay, safe-triangle hover zones. Use for rich previews on hover w/o building interaction logic.',+ paramDescriptions: {+ content: 'content for hover card. Can be render function receiving layer props.',+ placement: 'position relative to trigger.',+ alignment: 'alignment along placement axis.',+ delayMs: 'delay before showing hover card on hover.',+ onShow: 'callback fired when hover card becomes visible.',+ onHide: 'callback fired when hover card hidden.',+ },+ returnDescriptions: {+ triggerProps: 'props to spread on trigger element (ref, event handlers).',+ layerNode: 'hover card layer to render (include in JSX output).',+ },+ usage: {+ description: 'Headless hook for hover-triggered floating cards. Builds on useXDSLayer w/ hover/focus intent detection, delay, safe-triangle hover zones. Use for rich previews on hover w/o building interaction logic.',+ bestPractices: [+ {guidance: true, description: 'Use for rich content previews (user profiles, link previews) that benefit from hover interaction.'},+ {guidance: true, description: 'Prefer XDSHoverCard component for standard cases — use hook when you need full control over rendering.'},+ {guidance: false, description: 'Use for simple text hints — use XDSTooltip / useXDSTooltip instead.'},+ ],+ },+};diff --git a/packages/core/src/Popover/useXDSPopover.doc.mjs b/packages/core/src/Popover/useXDSPopover.doc.mjsindex de3f92c695..85e24fc794 100644--- a/packages/core/src/Popover/useXDSPopover.doc.mjs+++ b/packages/core/src/Popover/useXDSPopover.doc.mjs@@ -93,3 +93,33 @@ export const docs = {importPath: '@xds/core/Popover',category: 'interaction',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description: 'Headless hook for click-triggered popovers w/ focus trapping. Combines useXDSLayer w/ useFocusTrap for dialog-like popover behavior. Use for interactive floating content needing keyboard navigation.',+ paramDescriptions: {+ content: 'content for popover. Can be render function receiving layer props.',+ placement: 'position relative to trigger.',+ alignment: 'alignment along placement axis.',+ hasLightDismiss: 'whether clicking outside dismisses popover.',+ hasSurface: 'whether to apply default popover surface styles (background, shadow, radius).',+ onShow: 'callback fired when popover becomes visible.',+ onHide: 'callback fired when popover hidden.',+ xstyle: 'StyleX styles for popover surface (margins, sizing). Must be stylex.create() value — not inline style object. Note: for styles interacting w/ :popover-open, pass xstyle via render() call props instead.',+ },+ returnDescriptions: {+ triggerProps: 'props to spread on trigger element (ref, aria-expanded, event handlers).',+ layerNode: 'popover layer to render (include in JSX output).',+ isOpen: 'whether popover currently visible.',+ show: 'imperatively show popover.',+ hide: 'imperatively hide popover.',+ },+ usage: {+ description: 'Headless hook for click-triggered popovers w/ focus trapping. Combines useXDSLayer w/ useFocusTrap for dialog-like popover behavior. Use for interactive floating content needing keyboard navigation.',+ bestPractices: [+ {guidance: true, description: 'Use for interactive content (forms, menus, pickers) needing focus trapping + light dismiss.'},+ {guidance: true, description: 'Prefer XDSPopover component for standard trigger-content pairs — use hook for custom trigger patterns.'},+ {guidance: false, description: 'Use for non-interactive hover previews — use useXDSHoverCard / useXDSTooltip instead.'},+ ],+ },+};diff --git a/packages/core/src/Resizable/useXDSResizable.doc.mjs b/packages/core/src/Resizable/useXDSResizable.doc.mjsindex 1bb1c817ce..c1c1bb5684 100644--- a/packages/core/src/Resizable/useXDSResizable.doc.mjs+++ b/packages/core/src/Resizable/useXDSResizable.doc.mjs@@ -86,3 +86,32 @@ export const docs = {importPath: '@xds/core/Resizable',category: 'layout',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description: 'Adds drag-to-resize behavior to layout regions. Supports single-/multi-region configs w/ snap points, collapsible panels, localStorage persistence, cascade resize ordering.',+ paramDescriptions: {+ defaultSize: 'initial size in px / percentage string (e.g. "20%").',+ minSizePx: 'min size in px.',+ maxSizePx: 'max size in px.',+ collapsible: 'whether dragging below collapsed threshold collapses region to zero.',+ snaps: 'px values to snap to during drag.',+ autoSaveId: 'key for localStorage persistence of size across sessions.',+ },+ returnDescriptions: {+ size: 'current size in px.',+ isCollapsed: 'whether region currently collapsed.',+ collapse: 'programmatically collapse region.',+ expand: 'expand from collapsed state.',+ resize: 'resize to specific px value.',+ props: 'props to spread on resizable component / pass to XDSResizeHandle.',+ },+ usage: {+ description: 'Adds drag-to-resize behavior to layout regions. Supports single-/multi-region configs w/ snap points, collapsible panels, localStorage persistence, cascade resize ordering.',+ bestPractices: [+ {guidance: true, description: 'Use w/ XDSLayout / XDSAppShell sidebar for resizable navigation panels.'},+ {guidance: true, description: 'Set autoSaveId to persist user-chosen sizes across page reloads.'},+ {guidance: false, description: 'Set minSizePx too small — content becomes unreadable. Prefer collapsible for panels that can hide entirely.'},+ ],+ },+};diff --git a/packages/core/src/Toast/useXDSToast.doc.mjs b/packages/core/src/Toast/useXDSToast.doc.mjsindex fe2f5a40c1..1ae89b29e2 100644--- a/packages/core/src/Toast/useXDSToast.doc.mjs+++ b/packages/core/src/Toast/useXDSToast.doc.mjs@@ -30,3 +30,20 @@ export const docs = {importPath: '@xds/core/Toast',category: 'interaction',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ XDSLayerProvider / self-mounts fallback viewport.',+ returnDescriptions: {+ showToast: 'show toast notification. Returns dismiss function. Options: body (ReactNode), type ("info" | "error"), isAutoHide, autoHideDuration, endContent, uniqueID, collisionBehavior.',+ },+ usage: {+ description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ XDSLayerProvider / self-mounts fallback viewport.',+ bestPractices: [+ {guidance: true, description: 'Use for transient success/error feedback not requiring user action.'},+ {guidance: true, description: 'Set uniqueID to deduplicate toasts from rapid user actions.'},+ {guidance: false, description: 'Use for critical errors requiring acknowledgment — use AlertDialog instead.'},+ {guidance: false, description: 'Call useXDSToast in same component that renders XDSLayerProvider — must be called from child component inside provider.'},+ ],+ },+};diff --git a/packages/core/src/Tooltip/useXDSTooltip.doc.mjs b/packages/core/src/Tooltip/useXDSTooltip.doc.mjsindex c242e8ff4e..ab06e16ca7 100644--- a/packages/core/src/Tooltip/useXDSTooltip.doc.mjs+++ b/packages/core/src/Tooltip/useXDSTooltip.doc.mjs@@ -57,3 +57,26 @@ export const docs = {importPath: '@xds/core/Tooltip',category: 'interaction',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description: 'Headless hook for hover/focus-triggered tooltips. Builds on useXDSLayer w/ hover intent, delay, accessible aria-describedby linking. Use for custom trigger elements needing tooltip behavior.',+ paramDescriptions: {+ content: 'text / content for tooltip.',+ placement: 'position relative to trigger.',+ alignment: 'alignment along placement axis.',+ delayMs: 'delay before showing tooltip on hover.',+ },+ returnDescriptions: {+ triggerProps: 'props to spread on trigger element (ref, aria-describedby, event handlers).',+ layerNode: 'tooltip layer to render (include in JSX output).',+ },+ usage: {+ description: 'Headless hook for hover/focus-triggered tooltips. Builds on useXDSLayer w/ hover intent, delay, accessible aria-describedby linking. Use for custom trigger elements needing tooltip behavior.',+ bestPractices: [+ {guidance: true, description: 'Use for brief text labels describing a UI element — icon buttons, truncated text, abbreviations.'},+ {guidance: true, description: 'Prefer XDSTooltip component for standard wrapping — use hook when trigger is not a simple child.'},+ {guidance: false, description: 'Put interactive content (links, buttons) inside tooltips — use Popover / HoverCard instead.'},+ ],+ },+};diff --git a/packages/core/src/hooks/useClickableContainer.doc.mjs b/packages/core/src/hooks/useClickableContainer.doc.mjsindex 132560d5c5..f6c85c1e79 100644--- a/packages/core/src/hooks/useClickableContainer.doc.mjs+++ b/packages/core/src/hooks/useClickableContainer.doc.mjs@@ -76,3 +76,31 @@ export const docs = {importPath: '@xds/core/hooks',category: 'interaction',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Makes container element clickable while preserving nested interactive element behavior. Solves "nested interactive elements" problem: when card is clickable but contains buttons/links, clicking those must NOT trigger card\'s action. Detects interactive ancestors between click target + container, ignores text selections. Supports href navigation (incl. middle-click + Ctrl/Cmd+click for new tabs).',+ paramDescriptions: {+ options: 'config for clickable container.',+ 'options.containerRef': 'ref to outer container element.',+ 'options.interactiveRef': 'ref to primary interactive element inside (link, button). If no onClick / href provided, clicks proxied to this element.',+ 'options.onClick': 'click handler fired when container surface (not nested interactive element) clicked.',+ 'options.href': 'navigation URL. When provided, clicking container navigates to it.',+ 'options.target': "link target (e.g. '_blank'). Used w/ href for navigation behavior.",+ 'options.disabled': 'whether container disabled.',+ },+ returnDescriptions: {+ onClick: 'click handler for container element.',+ onMouseUp: 'mouse up handler for container (handles middle-click navigation for href).',+ },+ usage: {+ description:+ 'Makes container element clickable while preserving nested interactive element behavior. Solves "nested interactive elements" problem: when card is clickable but contains buttons/links, clicking those must NOT trigger card\'s action. Detects interactive ancestors between click target + container, ignores text selections. Supports href navigation (incl. middle-click + Ctrl/Cmd+click for new tabs).',+ bestPractices: [+ { guidance: true, description: 'Attach both onClick + onMouseUp to container element for full click handling incl. middle-click.' },+ { guidance: true, description: 'Use inside XDSClickableCard / XDSSelectableCard for standard card interaction pattern.' },+ { guidance: false, description: 'Use when entire container is single interactive element — just use <button> / <a> directly.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useEntryAnimation.doc.mjs b/packages/core/src/hooks/useEntryAnimation.doc.mjsindex 352739a2ca..22c2c5b664 100644--- a/packages/core/src/hooks/useEntryAnimation.doc.mjs+++ b/packages/core/src/hooks/useEntryAnimation.doc.mjs@@ -35,3 +35,24 @@ export const docs = {importPath: '@xds/core/hooks',category: 'animation',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint — elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client" — does not support SSR.',+ paramDescriptions: {+ preset: 'animation preset applied on mount.',+ },+ returnDescriptions: {+ entryStyle: 'StyleX style object for entry animation / null if element rendered on initial page load (no animation needed).',+ },+ usage: {+ description:+ 'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint — elements rendered on page load not animated. Uses XDS motion tokens (duration, easing) for consistent timing. Requires "use client" — does not support SSR.',+ bestPractices: [+ { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, expanding sections.' },+ { guidance: true, description: 'Spread returned style into stylex.props() alongside other styles.' },+ { guidance: false, description: 'Use for elements that should be visible on initial page load — they will not animate.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useFocusTrap.doc.mjs b/packages/core/src/hooks/useFocusTrap.doc.mjsindex c9cb1e18c2..380a764f42 100644--- a/packages/core/src/hooks/useFocusTrap.doc.mjs+++ b/packages/core/src/hooks/useFocusTrap.doc.mjs@@ -51,3 +51,27 @@ export const docs = {importPath: '@xds/core/hooks',category: 'focus',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted — use light-dismiss handler for that.',+ paramDescriptions: {+ options: 'config for focus trap.',+ 'options.isActive': 'whether focus trap currently active.',+ 'options.onEscape': 'callback when Escape key pressed inside trapped container.',+ },+ returnDescriptions: {+ containerRef: 'ref to attach to container element that should trap focus.',+ focusFirst: 'focuses first focusable element inside container.',+ },+ usage: {+ description:+ 'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted — use light-dismiss handler for that.',+ bestPractices: [+ { guidance: true, description: 'Call focusFirst() when opening dialog/modal to move focus into trapped region.' },+ { guidance: true, description: 'Provide onEscape callback to close dialog when Escape pressed.' },+ { guidance: false, description: 'Use on non-modal content like tooltips / dropdowns — those need light-dismiss, not focus trapping.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useGridFocus.doc.mjs b/packages/core/src/hooks/useGridFocus.doc.mjsindex 8ff1ddb675..d39f5d7938 100644--- a/packages/core/src/hooks/useGridFocus.doc.mjs+++ b/packages/core/src/hooks/useGridFocus.doc.mjs@@ -91,3 +91,34 @@ export const docs = {importPath: '@xds/core/hooks',category: 'focus',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow seamless cross-grid navigation.',+ paramDescriptions: {+ options: 'config for grid focus behavior.',+ 'options.columns': '# columns in grid. Used for up/down navigation (moves by this many cells).',+ 'options.cellSelector': 'selector for focusable cells in grid.',+ 'options.onNavigateBefore': 'callback when navigation would go before first cell. Receives column index + offset (1 for horizontal, columns for vertical).',+ 'options.onNavigateAfter': 'callback when navigation would go after last cell. Receives column index + offset.',+ 'options.onPageUp': 'callback for Page Up key (e.g. navigate to previous month in calendars).',+ 'options.onPageDown': 'callback for Page Down key (e.g. navigate to next month in calendars).',+ },+ returnDescriptions: {+ gridRef: 'ref to attach to grid container element.',+ handleKeyDown: 'key down handler for grid container.',+ focusCell: 'focus specific cell by index (clamped to valid range).',+ focusFirst: 'focus first focusable cell in grid.',+ focusLast: 'focus last focusable cell in grid.',+ },+ usage: {+ description:+ 'Manages keyboard navigation within 2D grid following WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, Page Up/Down for custom callbacks (e.g. month navigation in calendars). Boundary navigation callbacks allow seamless cross-grid navigation.',+ bestPractices: [+ { guidance: true, description: 'Use for calendar date grids — wire onPageUp/onPageDown to month navigation + onNavigateBefore/onNavigateAfter for cross-month arrow key navigation.' },+ { guidance: true, description: 'Attach both gridRef + handleKeyDown to grid container element.' },+ { guidance: false, description: 'Use for simple linear lists — prefer useListFocus for 1D navigation.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useImageMode.doc.mjs b/packages/core/src/hooks/useImageMode.doc.mjsindex 4107c9e4f6..44ad0e1052 100644--- a/packages/core/src/hooks/useImageMode.doc.mjs+++ b/packages/core/src/hooks/useImageMode.doc.mjs@@ -60,3 +60,28 @@ export const docs = {importPath: '@xds/core/hooks',category: 'media',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path — no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',+ paramDescriptions: {+ src: 'image source URL to analyze. When null/undefined, returns fallback value.',+ options: 'optional config for image analysis.',+ 'options.region': 'region to sample within image using normalized 0-1 coordinates ({ x, y, width, height }). Defaults to full image.',+ 'options.threshold': 'luminance threshold for dark/light split. Below = dark, above = light.',+ 'options.fallback': 'fallback value while loading / on error.',+ },+ returnDescriptions: {+ mode: 'detected luminance mode of image. Returns null while loading / if src null/undefined.',+ },+ usage: {+ description:+ 'Detects whether image is predominantly dark / light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, esp. on saturated colors. Runs entirely off paint path — no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading + falls back gracefully on CORS / network errors.',+ bestPractices: [+ { guidance: true, description: 'Pair w/ XDSMediaTheme to automatically adapt text color over dynamic background images.' },+ { guidance: true, description: 'Use region option to sample only area where text overlays will appear for more accurate results.' },+ { guidance: false, description: 'Use for images that change rapidly (e.g. video frames) — each src change triggers new fetch + analysis.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useInputContainer.doc.mjs b/packages/core/src/hooks/useInputContainer.doc.mjsindex 81a7cfe3f5..948d3a92d2 100644--- a/packages/core/src/hooks/useInputContainer.doc.mjs+++ b/packages/core/src/hooks/useInputContainer.doc.mjs@@ -58,3 +58,28 @@ export const docs = {importPath: '@xds/core/hooks',category: 'interaction',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Makes input container wrapper clickable, delegating focus to inner input/textarea when user clicks non-interactive areas (icons, padding, status indicators). Built on useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) handled safely — clicking them does NOT steal focus from input. Automatically detects input type: text-like inputs receive .focus(), other types (checkbox, radio, file) receive .click().',+ paramDescriptions: {+ options: 'config for input container.',+ 'options.containerRef': 'ref to outer container/wrapper element.',+ 'options.inputRef': 'ref to inner input / textarea element.',+ 'options.disabled': 'whether input disabled.',+ },+ returnDescriptions: {+ onClick: 'click handler for container wrapper.',+ onMouseUp: 'mouse up handler for container wrapper.',+ },+ usage: {+ description:+ 'Makes input container wrapper clickable, delegating focus to inner input/textarea when user clicks non-interactive areas (icons, padding, status indicators). Built on useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) handled safely — clicking them does NOT steal focus from input. Automatically detects input type: text-like inputs receive .focus(), other types (checkbox, radio, file) receive .click().',+ bestPractices: [+ { guidance: true, description: 'Use inside input wrapper components (XDSTextInput, XDSNumberInput, XDSTimeInput, XDSTextArea) to make full container area clickable.' },+ { guidance: true, description: 'Attach both onClick + onMouseUp to wrapper div for full interaction handling.' },+ { guidance: false, description: 'Use on bare inputs w/o wrapper — no benefit if input already fills full clickable area.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useListFocus.doc.mjs b/packages/core/src/hooks/useListFocus.doc.mjsindex 61063529a5..6bcff0aa36 100644--- a/packages/core/src/hooks/useListFocus.doc.mjs+++ b/packages/core/src/hooks/useListFocus.doc.mjs@@ -35,7 +35,7 @@ export const docs = {{name: 'options.orientation',type: "'horizontal' | 'vertical'",- description: "Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown.",+ description: "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown.",default: "'vertical'",required: false,},@@ -81,3 +81,32 @@ export const docs = {importPath: '@xds/core/hooks',category: 'focus',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Manages keyboard navigation within linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical / horizontal), Home/End for boundaries, optional wrap-around, Escape to close. Suitable for dropdown menus, toolbars, any 1D focusable list.',+ paramDescriptions: {+ options: 'config for list focus behavior. All fields optional.',+ 'options.itemSelector': 'selector for focusable items in list.',+ 'options.wrap': 'whether arrow navigation wraps around at ends.',+ 'options.onEscape': 'callback when Escape key pressed (e.g. close menu).',+ 'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown.",+ },+ returnDescriptions: {+ listRef: 'ref to attach to list container element.',+ handleKeyDown: 'key down handler for list container.',+ focusItem: 'focus specific item by index (clamped to valid range).',+ focusFirst: 'focus first focusable item in list.',+ focusLast: 'focus last focusable item in list.',+ },+ usage: {+ description:+ 'Manages keyboard navigation within linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical / horizontal), Home/End for boundaries, optional wrap-around, Escape to close. Suitable for dropdown menus, toolbars, any 1D focusable list.',+ bestPractices: [+ { guidance: true, description: "Set orientation to 'horizontal' for toolbars + tab bars, 'vertical' for dropdown menus." },+ { guidance: true, description: 'Provide onEscape callback for menus/dropdowns to return focus to trigger.' },+ { guidance: false, description: 'Use for 2D grid navigation — prefer useGridFocus for grids + calendars.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useMediaQuery.doc.mjs b/packages/core/src/hooks/useMediaQuery.doc.mjsindex 1f1d259bc3..1777eab0ed 100644--- a/packages/core/src/hooks/useMediaQuery.doc.mjs+++ b/packages/core/src/hooks/useMediaQuery.doc.mjs@@ -33,3 +33,22 @@ export const docs = {importPath: '@xds/core/hooks',category: 'media',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility.',+ paramDescriptions: {+ query: 'CSS media query string to evaluate.',+ },+ returnDescriptions: {+ matches: 'whether media query currently matches. Always false on first render (SSR-safe).',+ },+ usage: {+ description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility.',+ bestPractices: [+ { guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },+ { guidance: true, description: 'Prefer XDS responsive tokens + component props over manual breakpoint logic when possible.' },+ { guidance: false, description: 'Use for server-rendered content that must match on first paint — hook always returns false initially.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useOverflow.doc.mjs b/packages/core/src/hooks/useOverflow.doc.mjsindex 1f0899b61f..02f4b40366 100644--- a/packages/core/src/hooks/useOverflow.doc.mjs+++ b/packages/core/src/hooks/useOverflow.doc.mjs@@ -35,7 +35,7 @@ export const docs = {{name: 'options.collapseFrom',type: "'start' | 'end'",- description: 'Which end to collapse items from.',+ description: 'which end to collapse items from.',default: "'end'",required: false,},@@ -83,3 +83,32 @@ export const docs = {importPath: '@xds/core/hooks',category: 'layout',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Measures children rendered in hidden container to determine how many fit in available width w/o flickering. Uses ResizeObserver to react to container size changes. Measurement container should hold all items plus optional overflow indicator element (identified by data-overflow-indicator attribute).',+ paramDescriptions: {+ itemCount: 'total # items to measure for overflow.',+ options: 'config for overflow behavior.',+ 'options.gap': 'gap between items in px. Used in width calculations.',+ 'options.minVisibleItems': "min # items to always show, even if they don't fit.",+ 'options.collapseFrom': 'which end to collapse items from.',+ 'options.behavior': "which element to observe for overflow calculations. 'observeParent' uses container's parent element width, allowing visible container to remain content-sized.",+ },+ returnDescriptions: {+ containerRef: 'ref callback for visible container element.',+ measureRef: 'ref callback for hidden measurement container holding all items.',+ visibleCount: '# items that fit in visible container.',+ hasOverflow: 'whether any items overflowing (visibleCount < itemCount).',+ },+ usage: {+ description:+ 'Measures children rendered in hidden container to determine how many fit in available width w/o flickering. Uses ResizeObserver to react to container size changes. Measurement container should hold all items plus optional overflow indicator element (identified by data-overflow-indicator attribute).',+ bestPractices: [+ { guidance: true, description: 'Render all items into measureRef container (hidden) + only first visibleCount items into containerRef container (visible).' },+ { guidance: true, description: 'Include overflow indicator (e.g. "+N more" button) as last child of measurement container w/ data-overflow-indicator attribute.' },+ { guidance: false, description: 'Use for vertical overflow — this hook measures horizontal width only.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useScrollLock.doc.mjs b/packages/core/src/hooks/useScrollLock.doc.mjsindex 37e8c9d8cd..4bbe702907 100644--- a/packages/core/src/hooks/useScrollLock.doc.mjs+++ b/packages/core/src/hooks/useScrollLock.doc.mjs@@ -9,7 +9,7 @@ export const docs = {{name: 'isLocked',type: 'boolean',- description: 'Whether body scroll should be locked.',+ description: 'whether body scroll should be locked.',required: true,},],@@ -28,3 +28,21 @@ export const docs = {importPath: '@xds/core/hooks',category: 'layout',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked.',+ paramDescriptions: {+ isLocked: 'whether body scroll should be locked.',+ },+ usage: {+ description:+ 'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked.',+ bestPractices: [+ { guidance: true, description: 'Use when opening full-screen modals / dialogs to prevent background content from scrolling.' },+ { guidance: true, description: 'Pass same boolean that controls dialog visibility (e.g. isOpen) as isLocked parameter.' },+ { guidance: false, description: 'Use for non-modal overlays like popovers / tooltips — users should be able to scroll away from those.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useScrollOverflow.doc.mjs b/packages/core/src/hooks/useScrollOverflow.doc.mjsindex 393920bf61..e81633a663 100644--- a/packages/core/src/hooks/useScrollOverflow.doc.mjs+++ b/packages/core/src/hooks/useScrollOverflow.doc.mjs@@ -42,3 +42,24 @@ export const docs = {importPath: '@xds/core/hooks',category: 'layout',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Tracks scroll overflow state for horizontally scrollable container. Returns ref callback + state booleans that update as user scrolls / container resizes. Uses scroll event listeners + ResizeObserver for reactive updates. Tolerance of 1px applied to avoid sub-pixel false positives.',+ returnDescriptions: {+ scrollRef: 'ref callback for horizontally scrollable container element.',+ overflowStart: 'whether content overflows start edge (left in LTR, right in RTL).',+ overflowEnd: 'whether content overflows end edge (right in LTR, left in RTL).',+ hasOverflow: 'whether container has any scroll overflow at all (scrollWidth > clientWidth).',+ },+ usage: {+ description:+ 'Tracks scroll overflow state for horizontally scrollable container. Returns ref callback + state booleans that update as user scrolls / container resizes. Uses scroll event listeners + ResizeObserver for reactive updates. Tolerance of 1px applied to avoid sub-pixel false positives.',+ bestPractices: [+ { guidance: true, description: 'Use to show/hide scroll navigation buttons / fade edges on carousels + horizontal lists.' },+ { guidance: true, description: 'Apply scrollRef to container w/ overflow-x: auto / overflow-x: scroll.' },+ { guidance: false, description: 'Use for vertical scroll tracking — this hook only measures horizontal overflow.' },+ ],+ },+};diff --git a/packages/core/src/hooks/useXDSStreamingText.doc.mjs b/packages/core/src/hooks/useXDSStreamingText.doc.mjsindex 0f826f8c56..92f984ffdd 100644--- a/packages/core/src/hooks/useXDSStreamingText.doc.mjs+++ b/packages/core/src/hooks/useXDSStreamingText.doc.mjs@@ -54,3 +54,28 @@ export const docs = {importPath: '@xds/core/hooks',category: 'streaming',};++/** @type {import('../docs-types').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from XDS motion tokens via useXDSTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',+ paramDescriptions: {+ targetText: 'full target text to reveal. As new chunks arrive, update this value w/ accumulated text.',+ isStreaming: 'whether text currently being streamed. When false, hook returns full targetText immediately.',+ options: 'optional config for streaming behavior.',+ 'options.speed': "speed preset for text reveal. 'natural' is steady ~2 chars/frame, 'fast' scales w/ backlog ~4 chars/frame, 'instant' returns full text w/ no animation.",+ },+ returnDescriptions: {+ displayedText: 'portion of targetText to render. Grows steadily toward full targetText during streaming / equals targetText when not streaming.',+ },+ usage: {+ description:+ 'Smooths bursty streamed text into steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word + syntax boundaries to avoid slicing mid-markdown / mid-word, preventing visual glitches w/ markdown renderers. Animation timing derives from XDS motion tokens via useXDSTheme when available, w/ sensible fallbacks outside theme provider. Snaps to full text when isStreaming becomes false.',+ bestPractices: [+ { guidance: true, description: 'Pass accumulated text (not individual chunks) as targetText — hook handles incremental reveal internally.' },+ { guidance: true, description: 'Set isStreaming to false when stream completes to snap to final text.' },+ { guidance: true, description: "Use speed='instant' for non-animated contexts like search results / when reduced motion preferred." },+ { guidance: false, description: 'Use for static text that does not change — hook adds unnecessary overhead for non-streaming content.' },+ ],+ },+};