Skip to content

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.mjs
index 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 translations
if (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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.' },
+ ],
+ },
+};