Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): document hook parameters and examples (#2750)

Cindy Zhangc36a3dc29a0b
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index b64dd8e245..9c6775d401 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -309,6 +309,13 @@ function sanitizeForJson(obj) {
}));
}
+function extractStringArrayField(content, field) {
+ const re = new RegExp(`${field}:\\s*\\[([^\\]]*)\\]`);
+ const match = re.exec(content);
+ if (!match) return [];
+ return [...match[1].matchAll(/['"]([^'"]+)['"]/g)].map(m => m[1]);
+}
+
async function generateComponentRegistry() {
console.log('Generating component registry...');
@@ -383,16 +390,35 @@ async function generateComponentRegistry() {
if (doc.components && doc.components.length > 0) {
for (const sub of doc.components) {
- const subName = (sub.name || '').replace(/^XDS/, '');
+ const rawSubName = sub.name || '';
+ const subName = rawSubName.replace(/^XDS/, '');
if (!subName) continue;
+ const isHookEntry = rawSubName.startsWith('use') || subName.startsWith('use') || Array.isArray(sub.params);
// Sub-entries whose name differs from the doc name are
// sub-components — hide them from the overview page.
const isSubEntry = subName !== doc.name;
// Each sub-component may have its own usage; fall back to
// the parent doc's usage only when the sub doesn't define one.
+ // Hook entries should read as hook docs, not as the parent component,
+ // so use the hook description as the usage summary when no explicit
+ // usage block is authored.
const subUsage = sub.usage
? sanitizeForJson(sub.usage)
- : usage;
+ : isHookEntry && sub.description
+ ? {description: sub.description}
+ : usage;
+ const params = isHookEntry
+ ? Array.isArray(sub.params)
+ ? sanitizeForJson(sub.params)
+ : Array.isArray(sub.props)
+ ? sanitizeForJson(sub.props)
+ : []
+ : null;
+ const returns = isHookEntry
+ ? Array.isArray(sub.returns)
+ ? sanitizeForJson(sub.returns)
+ : []
+ : null;
pendingSubComponents.push({
name: subName,
displayName: requireDisplayName(
@@ -409,14 +435,20 @@ async function generateComponentRegistry() {
keywords,
hidden,
parentDoc: doc.name,
- props: Array.isArray(sub.props) ? sanitizeForJson(sub.props) : [],
+ props: isHookEntry
+ ? []
+ : Array.isArray(sub.props)
+ ? sanitizeForJson(sub.props)
+ : [],
usage: subUsage,
- theming,
- params: null,
- returns: null,
- relatedComponents: null,
- relatedHooks: null,
- playground,
+ theming: isHookEntry ? null : theming,
+ params,
+ returns,
+ relatedComponents: isHookEntry
+ ? sub.relatedComponents || (doc.name ? [doc.name] : null)
+ : null,
+ relatedHooks: isHookEntry ? sub.relatedHooks || null : null,
+ playground: isHookEntry ? null : playground,
});
}
} else if (doc.params) {
@@ -1152,7 +1184,7 @@ function generateShowcaseRegistry() {
for (const docPath of docFiles) {
const content = fs.readFileSync(docPath, 'utf-8');
- if (!/isShowcase:\s*true/.test(content)) continue;
+ const isShowcase = /isShowcase:\s*true/.test(content);
const efMatch = content.match(/exampleFor:\s*['"]([^'"]+)['"]/);
if (!efMatch) continue;
@@ -1162,11 +1194,25 @@ function generateShowcaseRegistry() {
const tsxSrc = path.join(path.dirname(docPath), basename + '.tsx');
if (!fs.existsSync(tsxSrc)) continue;
- // Copy the TSX file into generated/showcases/
- const destFile = `${basename}.tsx`;
- fs.copyFileSync(tsxSrc, path.join(SHOWCASE_OUT, destFile));
+ const alsoShowcaseFor = extractStringArrayField(content, 'alsoShowcaseFor');
+
+ if (isShowcase) {
+ // Copy the TSX file into generated/showcases/
+ const destFile = `${basename}.tsx`;
+ fs.copyFileSync(tsxSrc, path.join(SHOWCASE_OUT, destFile));
+ entries.push({exampleFor, basename, destFile});
+ }
+
+ // Blocks can opt into serving as the visual showcase for additional
+ // component or hook pages. This is explicit metadata instead of source
+ // inspection so authors control where examples appear.
+ for (const target of alsoShowcaseFor) {
+ const aliasBasename = `${basename}__${target}`;
+ const destFile = `${aliasBasename}.tsx`;
+ fs.copyFileSync(tsxSrc, path.join(SHOWCASE_OUT, destFile));
+ entries.push({exampleFor: target, basename: aliasBasename, destFile});
+ }
- entries.push({exampleFor, basename, destFile});
}
// Deduplicate: one showcase per component (first wins)
@@ -1215,8 +1261,7 @@ function generateExampleRegistry() {
for (const docPath of docFiles) {
const content = fs.readFileSync(docPath, 'utf-8');
- // Skip showcases — they have their own registry
- if (/isShowcase:\s*true/.test(content)) continue;
+ const isShowcase = /isShowcase:\s*true/.test(content);
const efMatch = content.match(/exampleFor:\s*['"]([^'"]+)['"]/);
if (!efMatch) continue;
@@ -1230,18 +1275,37 @@ function generateExampleRegistry() {
const nameMatch = content.match(/name:\s*['"]([^'"]+)['"]/);
const description = extractQuotedField(content, 'description');
- fs.copyFileSync(tsxSrc, path.join(EXAMPLES_OUT, `${basename}.tsx`));
-
let source = '';
try { source = fs.readFileSync(tsxSrc, 'utf-8'); } catch { /* ignore */ }
- entries.push({
- exampleFor,
- basename,
- name: nameMatch?.[1] || basename,
- description: description || '',
- source,
- });
+ const alsoExampleFor = extractStringArrayField(content, 'alsoExampleFor');
+
+ if (!isShowcase) {
+ fs.copyFileSync(tsxSrc, path.join(EXAMPLES_OUT, `${basename}.tsx`));
+ entries.push({
+ exampleFor,
+ basename,
+ name: nameMatch?.[1] || basename,
+ description: description || '',
+ source,
+ });
+ }
+
+ // Blocks can explicitly appear as examples for additional component or
+ // hook pages. This supports component examples doubling as hook examples
+ // without inferring intent from the TSX source.
+ for (const target of alsoExampleFor) {
+ const aliasBasename = `${basename}__${target}`;
+ fs.copyFileSync(tsxSrc, path.join(EXAMPLES_OUT, `${aliasBasename}.tsx`));
+ entries.push({
+ exampleFor: target,
+ basename: aliasBasename,
+ name: nameMatch?.[1] || basename,
+ description: description || `Example using ${target}.`,
+ source,
+ });
+ }
+
}
// Group by component
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.ts
index 4c344017c5..6144dbf9b1 100644
--- a/apps/docsite/src/__tests__/data-extraction.test.ts
+++ b/apps/docsite/src/__tests__/data-extraction.test.ts
@@ -215,6 +215,20 @@ describe('componentRegistry', () => {
}
});
+ it('renders useXDS hook pages as hook docs with examples', () => {
+ const core = components['@xds/core'];
+ const hooks = core.filter(c => c.name.startsWith('useXDS'));
+ expect(hooks.length).toBeGreaterThan(15);
+ expect(hooks.map(h => h.name)).toContain('useXDSTheme');
+
+ for (const hook of hooks) {
+ expect(hook.params).not.toBeNull();
+ expect(hook.returns).not.toBeNull();
+ expect(hook.props).toHaveLength(0);
+ expect(exampleRegistry[hook.name]?.length ?? 0).toBeGreaterThan(0);
+ }
+ });
+
it('discovers theme utilities (not skipped)', () => {
const core = components['@xds/core'];
const themeUtils = core.filter(c => c.directory === 'theme');
@@ -610,16 +624,15 @@ describe('exampleRegistry', () => {
expect(files.every(f => f.endsWith('.tsx'))).toBe(true);
});
- it('does not include showcases', () => {
- // Every example in the registry should NOT be a showcase
- // (showcases have their own registry)
- // Showcase names typically don't have a dash separator
- // but more importantly, the generator filters isShowcase: true
- // Just verify count makes sense: examples + showcases ≈ total blocks
+ it('does not include showcases as primary component examples', () => {
+ // Hook pages can reuse authored component examples/showcases through
+ // explicit block metadata. Count unique authored example sources so those
+ // hook aliases don't make the registry look larger than the block set.
const showcaseCount = Object.keys(showcaseRegistry).length;
- const exampleCount = Object.values(exampleRegistry).flat().length;
- expect(exampleCount + showcaseCount).toBeLessThanOrEqual(blockCount);
- expect(exampleCount).toBeGreaterThan(showcaseCount);
+ const examples = Object.values(exampleRegistry).flat();
+ const uniqueExampleSourceCount = new Set(examples.map(e => e.source)).size;
+ expect(uniqueExampleSourceCount).toBeLessThanOrEqual(blockCount);
+ expect(examples.length).toBeGreaterThan(showcaseCount);
});
// Regression: the description extractor used to truncate at the first
diff --git a/apps/docsite/src/components/component-detail/HookSignature.tsx b/apps/docsite/src/components/component-detail/HookSignature.tsx
index 06c006204c..a0b20785ec 100644
--- a/apps/docsite/src/components/component-detail/HookSignature.tsx
+++ b/apps/docsite/src/components/component-detail/HookSignature.tsx
@@ -101,9 +101,12 @@ export function HookSignature({params, returns}: HookSignatureProps) {
{
key: 'name',
header: 'Param',
- width: pixel(160),
+ width: pixel(240),
renderCell: (item: Record<string, unknown>) => (
- <XDSHStack gap={1} vAlign="center">
+ <XDSHStack
+ gap={1}
+ vAlign="center"
+ style={{whiteSpace: 'nowrap'}}>
<XDSText type="code" weight="bold">
{item.name as string}
</XDSText>
@@ -150,9 +153,12 @@ export function HookSignature({params, returns}: HookSignatureProps) {
{
key: 'name',
header: 'Field',
- width: pixel(160),
+ width: pixel(220),
renderCell: (item: Record<string, unknown>) => (
- <XDSText type="code" weight="bold">
+ <XDSText
+ type="code"
+ weight="bold"
+ style={{whiteSpace: 'nowrap'}}>
{item.name as string}
</XDSText>
),
diff --git a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogDeleteConfirmation.doc.mjs b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogDeleteConfirmation.doc.mjs
index e3540cf4d8..5e3bd2a9a5 100644
--- a/packages/cli/templates/blocks/components/AlertDialog/AlertDialogDeleteConfirmation.doc.mjs
+++ b/packages/cli/templates/blocks/components/AlertDialog/AlertDialogDeleteConfirmation.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'AlertDialog',
+ alsoExampleFor: ['useXDSImperativeAlertDialog'],
+ alsoShowcaseFor: ['useXDSImperativeAlertDialog'],
name: 'AlertDialog — Delete',
displayName: 'AlertDialog — Delete',
description:
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleHookUsage.doc.mjs b/packages/cli/templates/blocks/components/Collapsible/CollapsibleHookUsage.doc.mjs
new file mode 100644
index 0000000000..3b43a974c1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useXDSCollapsible',
+ name: 'useXDSCollapsible — Custom Disclosure',
+ displayName: 'useXDSCollapsible — Custom Disclosure',
+ description:
+ 'Custom disclosure UI built directly with useXDSCollapsible for headless open/close state.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Collapsible', 'Button', 'Card', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleHookUsage.tsx b/packages/cli/templates/blocks/components/Collapsible/CollapsibleHookUsage.tsx
new file mode 100644
index 0000000000..d8406911ec
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleHookUsage.tsx
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useId} from 'react';
+import {useXDSCollapsible} from '@xds/core/Collapsible';
+import {XDSButton} from '@xds/core/Button';
+import {XDSCard} from '@xds/core/Card';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function CollapsibleHookUsage() {
+ const detailsId = useId();
+ const disclosure = useXDSCollapsible({
+ isCollapsible: {defaultIsOpen: true},
+ value: 'release-notes',
+ });
+
+ return (
+ <XDSCard width={360} padding={4}>
+ <XDSVStack gap={3}>
+ <XDSText type="body" weight="bold">
+ Release checklist
+ </XDSText>
+ <XDSButton
+ label={disclosure.isOpen ? 'Hide details' : 'Show details'}
+ variant="secondary"
+ aria-controls={detailsId}
+ aria-expanded={disclosure.isOpen}
+ onClick={disclosure.toggle}
+ />
+ {disclosure.isOpen && (
+ <div
+ id={detailsId}
+ role="region"
+ aria-label="Release checklist details">
+ <XDSText type="body" color="secondary">
+ Review docs, run visual checks, and confirm keyboard behavior
+ before shipping the component update.
+ </XDSText>
+ </div>
+ )}
+ </XDSVStack>
+ </XDSCard>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Collapsible/CollapsibleShowcase.doc.mjs b/packages/cli/templates/blocks/components/Collapsible/CollapsibleShowcase.doc.mjs
index cbe58e1670..ed776703c3 100644
--- a/packages/cli/templates/blocks/components/Collapsible/CollapsibleShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/Collapsible/CollapsibleShowcase.doc.mjs
@@ -4,6 +4,7 @@
export const doc = {
type: 'block',
exampleFor: 'Collapsible',
+ alsoShowcaseFor: ['useXDSCollapsible'],
name: 'Collapsible',
displayName: 'Collapsible',
description:
diff --git a/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.doc.mjs
index 0d328f3c5a..677be85bac 100644
--- a/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.doc.mjs
+++ b/packages/cli/templates/blocks/components/Dialog/DialogConfirmationDialog.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'Dialog',
+ alsoExampleFor: ['useXDSImperativeDialog'],
+ alsoShowcaseFor: ['useXDSImperativeDialog'],
name: 'Dialog — Confirmation',
displayName: 'Dialog — Confirmation',
description:
diff --git a/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.doc.mjs
index cd90b4b580..104ccb9084 100644
--- a/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.doc.mjs
+++ b/packages/cli/templates/blocks/components/Dialog/DialogFormDialog.doc.mjs
@@ -4,6 +4,7 @@
export const doc = {
type: 'block',
exampleFor: 'Dialog',
+ alsoExampleFor: ['useXDSImperativeDialog'],
name: 'Dialog — Form',
displayName: 'Dialog — Form',
description:
diff --git a/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.doc.mjs
index bc2ec62d83..9a9fdd6ac5 100644
--- a/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.doc.mjs
+++ b/packages/cli/templates/blocks/components/Dialog/DialogScrollingContent.doc.mjs
@@ -4,6 +4,7 @@
export const doc = {
type: 'block',
exampleFor: 'Dialog',
+ alsoExampleFor: ['useXDSImperativeDialog'],
name: 'Dialog — Scrollable',
displayName: 'Dialog — Scrollable',
description:
diff --git a/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.doc.mjs b/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.doc.mjs
index aecf2ad5f2..aa8b4bf90b 100644
--- a/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.doc.mjs
+++ b/packages/cli/templates/blocks/components/Dialog/DialogWithSubtitle.doc.mjs
@@ -4,6 +4,7 @@
export const doc = {
type: 'block',
exampleFor: 'Dialog',
+ alsoExampleFor: ['useXDSImperativeDialog'],
name: 'Dialog — Required',
displayName: 'Dialog — Required',
description:
diff --git a/packages/cli/templates/blocks/components/Hooks/useXDSStreamingTextHookUsage.doc.mjs b/packages/cli/templates/blocks/components/Hooks/useXDSStreamingTextHookUsage.doc.mjs
new file mode 100644
index 0000000000..5e9471c55d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Hooks/useXDSStreamingTextHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useXDSStreamingText',
+ name: 'useXDSStreamingText — Streaming Response',
+ displayName: 'useXDSStreamingText — Streaming Response',
+ description:
+ 'Smooth bursty generated text into a steady reveal with useXDSStreamingText.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Card', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Hooks/useXDSStreamingTextHookUsage.tsx b/packages/cli/templates/blocks/components/Hooks/useXDSStreamingTextHookUsage.tsx
new file mode 100644
index 0000000000..81959570bc
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Hooks/useXDSStreamingTextHookUsage.tsx
@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useXDSStreamingText} from '@xds/core/hooks';
+import {XDSCard} from '@xds/core/Card';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const response =
+ 'XDS hooks keep behavior reusable while components keep visuals consistent.';
+
+export default function UseXDSStreamingTextHookUsage() {
+ const displayedText = useXDSStreamingText(response, false, {
+ speed: 'fast',
+ });
+
+ return (
+ <XDSCard width={420} padding={4}>
+ <XDSVStack gap={2}>
+ <XDSText type="body" weight="bold">
+ Assistant response
+ </XDSText>
+ <XDSText type="body">{displayedText}</XDSText>
+ <XDSText type="supporting" color="secondary">
+ Complete
+ </XDSText>
+ </XDSVStack>
+ </XDSCard>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookUsage.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardHookUsage.doc.mjs
new file mode 100644
index 0000000000..b1ec20db73
--- /dev/null
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useXDSHoverCard',
+ name: 'useXDSHoverCard — Profile Preview',
+ displayName: 'useXDSHoverCard — Profile Preview',
+ description:
+ 'Custom profile preview using useXDSHoverCard with direct trigger and render control.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['HoverCard', 'Button', 'Text', 'Layout', 'Center'],
+};
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardHookUsage.tsx b/packages/cli/templates/blocks/components/HoverCard/HoverCardHookUsage.tsx
new file mode 100644
index 0000000000..8bca539bd7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardHookUsage.tsx
@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useXDSHoverCard} from '@xds/core/HoverCard';
+import {XDSButton} from '@xds/core/Button';
+import {XDSCenter} from '@xds/core/Center';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function HoverCardHookUsage() {
+ const hoverCard = useXDSHoverCard({
+ placement: 'below',
+ delay: 100,
+ isDefaultOpen: true,
+ });
+
+ return (
+ <XDSCenter height={220}>
+ <XDSButton
+ label="Hover profile"
+ ref={hoverCard.ref}
+ aria-describedby={hoverCard.describedBy}
+ />
+ {hoverCard.renderHoverCard(
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Alex Morgan
+ </XDSText>
+ <XDSText type="body" color="secondary">
+ Staff designer · Product systems
+ </XDSText>
+ <XDSText type="body" color="secondary">
+ Owns interaction patterns for overlays and navigation.
+ </XDSText>
+ </XDSVStack>,
+ {placement: 'below', alignment: 'center'},
+ )}
+ </XDSCenter>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.doc.mjs b/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.doc.mjs
index 7b57170185..94baadddb3 100644
--- a/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/HoverCard/HoverCardShowcase.doc.mjs
@@ -4,6 +4,7 @@
export const doc = {
type: 'block',
exampleFor: 'HoverCard',
+ alsoShowcaseFor: ['useXDSHoverCard'],
name: 'HoverCard',
displayName: 'Hover Card',
description:
diff --git a/packages/cli/templates/blocks/components/Layer/LayerHookUsage.doc.mjs b/packages/cli/templates/blocks/components/Layer/LayerHookUsage.doc.mjs
new file mode 100644
index 0000000000..8c2332f680
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Layer/LayerHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useXDSLayer',
+ name: 'useXDSLayer — Anchored Layer',
+ displayName: 'useXDSLayer — Anchored Layer',
+ description:
+ 'Low-level anchored overlay rendered with useXDSLayer and a custom surface.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Layer', 'Button', 'Card', 'Text', 'Layout', 'Center'],
+};
diff --git a/packages/cli/templates/blocks/components/Layer/LayerHookUsage.tsx b/packages/cli/templates/blocks/components/Layer/LayerHookUsage.tsx
new file mode 100644
index 0000000000..a83294192c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Layer/LayerHookUsage.tsx
@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useXDSLayer} from '@xds/core/Layer';
+import {XDSButton} from '@xds/core/Button';
+import {XDSCard} from '@xds/core/Card';
+import {XDSCenter} from '@xds/core/Center';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function LayerHookUsage() {
+ const layer = useXDSLayer({mode: 'context', lightDismiss: true});
+
+ return (
+ <XDSCenter height={220}>
+ <XDSButton
+ label={layer.isOpen ? 'Hide layer' : 'Show layer'}
+ ref={layer.ref}
+ onClick={layer.isOpen ? layer.hide : layer.show}
+ />
+ {layer.render(
+ <XDSCard padding={3}>
+ <XDSVStack gap={1}>
+ <XDSText type="body" weight="bold">
+ Anchored content
+ </XDSText>
+ <XDSText type="body" color="secondary">
+ useXDSLayer provides positioning; you own semantics and surface.
+ </XDSText>
+ </XDSVStack>
+ </XDSCard>,
+ {placement: 'below', alignment: 'center'},
+ )}
+ </XDSCenter>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Popover/PopoverHookUsage.doc.mjs b/packages/cli/templates/blocks/components/Popover/PopoverHookUsage.doc.mjs
new file mode 100644
index 0000000000..c049b2de5a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Popover/PopoverHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useXDSPopover',
+ name: 'useXDSPopover — Quick Actions',
+ displayName: 'useXDSPopover — Quick Actions',
+ description:
+ 'Custom quick-actions popover using useXDSPopover for trigger refs, ARIA attributes, and focus trapping.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Popover', 'Button', 'Text', 'Layout', 'Center'],
+};
diff --git a/packages/cli/templates/blocks/components/Popover/PopoverHookUsage.tsx b/packages/cli/templates/blocks/components/Popover/PopoverHookUsage.tsx
new file mode 100644
index 0000000000..932a92f9d1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Popover/PopoverHookUsage.tsx
@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useXDSPopover} from '@xds/core/Popover';
+import {XDSButton} from '@xds/core/Button';
+import {XDSCard} from '@xds/core/Card';
+import {XDSCenter} from '@xds/core/Center';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function PopoverHookUsage() {
+ const popover = useXDSPopover({dialogLabel: 'Quick actions'});
+
+ return (
+ <XDSCenter height={240}>
+ <XDSButton
+ label="Open actions"
+ ref={popover.triggerRef}
+ onClick={popover.toggle}
+ {...popover.triggerProps}
+ />
+ {popover.render(
+ <XDSCard width={220} padding={3} variant="transparent">
+ <XDSVStack gap={2}>
+ <XDSText type="body" weight="bold">
+ Quick actions
+ </XDSText>
+ <XDSButton label="Create task" size="sm" />
+ <XDSButton label="Share report" variant="secondary" size="sm" />
+ </XDSVStack>
+ </XDSCard>,
+ {placement: 'below', alignment: 'center'},
+ )}
+ </XDSCenter>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Popover/PopoverShowcase.doc.mjs b/packages/cli/templates/blocks/components/Popover/PopoverShowcase.doc.mjs
index 7d216d020b..39eaf97087 100644
--- a/packages/cli/templates/blocks/components/Popover/PopoverShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/Popover/PopoverShowcase.doc.mjs
@@ -4,6 +4,7 @@
export const doc = {
type: 'block',
exampleFor: 'Popover',
+ alsoShowcaseFor: ['useXDSPopover'],
name: 'Popover',
displayName: 'Popover',
isReady: true,
diff --git a/packages/cli/templates/blocks/components/Resizable/ResizableShowcase.doc.mjs b/packages/cli/templates/blocks/components/Resizable/ResizableShowcase.doc.mjs
index d0ea65d889..fe175734d3 100644
--- a/packages/cli/templates/blocks/components/Resizable/ResizableShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/Resizable/ResizableShowcase.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'Resizable',
+ alsoExampleFor: ['useXDSResizable'],
+ alsoShowcaseFor: ['useXDSResizable'],
name: 'Resizable',
displayName: 'Resizable',
description:
diff --git a/packages/cli/templates/blocks/components/Table/TableColumnSettingsTable.doc.mjs b/packages/cli/templates/blocks/components/Table/TableColumnSettingsTable.doc.mjs
index 698b268724..225342dfe4 100644
--- a/packages/cli/templates/blocks/components/Table/TableColumnSettingsTable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Table/TableColumnSettingsTable.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'Table',
+ alsoExampleFor: ['useXDSTableColumnSettings'],
+ alsoShowcaseFor: ['useXDSTableColumnSettings'],
name: 'Table — Column Settings',
displayName: 'Table — Column Settings',
description:
diff --git a/packages/cli/templates/blocks/components/Table/TableFilterableTable.doc.mjs b/packages/cli/templates/blocks/components/Table/TableFilterableTable.doc.mjs
index 3e7f281145..390de5b16f 100644
--- a/packages/cli/templates/blocks/components/Table/TableFilterableTable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Table/TableFilterableTable.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'Table',
+ alsoExampleFor: ['useXDSTableFiltering', 'useXDSTableFilterState'],
+ alsoShowcaseFor: ['useXDSTableFiltering', 'useXDSTableFilterState'],
name: 'Table — Popover Filters',
displayName: 'Table — Popover Filters',
description:
diff --git a/packages/cli/templates/blocks/components/Table/TableInlineFilterTable.doc.mjs b/packages/cli/templates/blocks/components/Table/TableInlineFilterTable.doc.mjs
index 97554d8ef3..ad76d7eb6e 100644
--- a/packages/cli/templates/blocks/components/Table/TableInlineFilterTable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Table/TableInlineFilterTable.doc.mjs
@@ -4,6 +4,7 @@
export const doc = {
type: 'block',
exampleFor: 'Table',
+ alsoExampleFor: ['useXDSTableFiltering', 'useXDSTableFilterState'],
name: 'Table — Inline Filters',
displayName: 'Table — Inline Filters',
description:
diff --git a/packages/cli/templates/blocks/components/Table/TablePaginatedTable.doc.mjs b/packages/cli/templates/blocks/components/Table/TablePaginatedTable.doc.mjs
index 95a8f4a382..93874f276f 100644
--- a/packages/cli/templates/blocks/components/Table/TablePaginatedTable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Table/TablePaginatedTable.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'Table',
+ alsoExampleFor: ['useXDSTablePagination'],
+ alsoShowcaseFor: ['useXDSTablePagination'],
name: 'Table — Paginated Data',
displayName: 'Table — Paginated Data',
description:
diff --git a/packages/cli/templates/blocks/components/Table/TableSelectableTable.doc.mjs b/packages/cli/templates/blocks/components/Table/TableSelectableTable.doc.mjs
index d6b266b452..f764d80548 100644
--- a/packages/cli/templates/blocks/components/Table/TableSelectableTable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Table/TableSelectableTable.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'Table',
+ alsoExampleFor: ['useXDSTableSelection', 'useXDSTableSelectionState'],
+ alsoShowcaseFor: ['useXDSTableSelection', 'useXDSTableSelectionState'],
name: 'Table — Row Selection',
displayName: 'Table — Row Selection',
description:
diff --git a/packages/cli/templates/blocks/components/Table/TableSortableTable.doc.mjs b/packages/cli/templates/blocks/components/Table/TableSortableTable.doc.mjs
index 2c22c2ceae..c9d39bac82 100644
--- a/packages/cli/templates/blocks/components/Table/TableSortableTable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Table/TableSortableTable.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'Table',
+ alsoExampleFor: ['useXDSTableSortable'],
+ alsoShowcaseFor: ['useXDSTableSortable'],
name: 'Table — Sortable Columns',
displayName: 'Table — Sortable Columns',
description:
diff --git a/packages/cli/templates/blocks/components/Theme/useXDSThemeHookUsage.doc.mjs b/packages/cli/templates/blocks/components/Theme/useXDSThemeHookUsage.doc.mjs
new file mode 100644
index 0000000000..7462705593
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Theme/useXDSThemeHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useXDSTheme',
+ name: 'useXDSTheme — Token Values',
+ displayName: 'useXDSTheme — Token Values',
+ description:
+ 'Read resolved theme token values with useXDSTheme for non-CSS consumers like SVG charts.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Theme', 'Card', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Theme/useXDSThemeHookUsage.tsx b/packages/cli/templates/blocks/components/Theme/useXDSThemeHookUsage.tsx
new file mode 100644
index 0000000000..232b8a148c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Theme/useXDSThemeHookUsage.tsx
@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useXDSTheme} from '@xds/core/theme';
+import {XDSCard} from '@xds/core/Card';
+import {XDSHStack, XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function UseXDSThemeHookUsage() {
+ const {name, mode, token} = useXDSTheme();
+ const accent = token('--color-accent');
+ const muted = token('--color-accent-muted');
+ const text = token('--color-text-primary');
+
+ return (
+ <XDSCard width={360} padding={4}>
+ <XDSVStack gap={3}>
+ <XDSText type="body" weight="bold">
+ {name} · {mode}
+ </XDSText>
+ <svg width="300" height="120" role="img" aria-label="Themed bar chart">
+ <rect x="24" y="20" width="64" height="80" rx="8" fill={accent} />
+ <rect x="118" y="48" width="64" height="52" rx="8" fill={muted} />
+ <rect
+ x="212"
+ y="32"
+ width="64"
+ height="68"
+ rx="8"
+ fill={accent}
+ opacity="0.72"
+ />
+ <text x="24" y="114" fill={text} fontSize="12">
+ Resolved token values
+ </text>
+ </svg>
+ <XDSHStack gap={2}>
+ <XDSText type="code">--color-accent</XDSText>
+ <XDSText type="code" color="secondary">
+ {accent}
+ </XDSText>
+ </XDSHStack>
+ </XDSVStack>
+ </XDSCard>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs b/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs
index 72994b8b23..7b0080b900 100644
--- a/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/Toast/ToastShowcase.doc.mjs
@@ -4,8 +4,12 @@
export const doc = {
type: 'block',
exampleFor: 'Toast',
+ alsoExampleFor: ['useXDSToast'],
+ alsoShowcaseFor: ['useXDSToast'],
name: 'Toast',
displayName: 'Toast',
+ description:
+ 'Imperative toast notifications triggered with useXDSToast and rendered in the toast viewport.',
isReady: true,
aspectRatio: 16 / 9,
isShowcase: true,
diff --git a/packages/cli/templates/blocks/components/Tooltip/TooltipHookUsage.doc.mjs b/packages/cli/templates/blocks/components/Tooltip/TooltipHookUsage.doc.mjs
index a4f0b299b1..35ec56bbcd 100644
--- a/packages/cli/templates/blocks/components/Tooltip/TooltipHookUsage.doc.mjs
+++ b/packages/cli/templates/blocks/components/Tooltip/TooltipHookUsage.doc.mjs
@@ -4,6 +4,8 @@
export const doc = {
type: 'block',
exampleFor: 'Tooltip',
+ alsoExampleFor: ['useXDSTooltip'],
+ alsoShowcaseFor: ['useXDSTooltip'],
name: 'Tooltip — Hook Usage',
displayName: 'Tooltip — Hook Usage',
description:
diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
index eef7822f0b..298bdbcd0b 100644
--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
@@ -62,7 +62,8 @@ export const docs = {
name: 'useXDSImperativeAlertDialog',
displayName: 'useXDSImperativeAlertDialog',
description: 'Hook for showing an alert dialog without managing open state. Call alert.show(options) to open and alert.hide() to close. Render alert.element in your JSX tree.',
- props: [
+ params: [],
+ returns: [
{name: 'show', type: '(options: AlertDialogOptions) => void', description: 'Show the alert dialog with the given options. Options are the same as XDSAlertDialog props minus isOpen/onOpenChange.'},
{name: 'hide', type: '() => void', description: 'Hide the alert dialog.'},
{name: 'isOpen', type: 'boolean', description: 'Whether the dialog is currently open.'},
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index 94b90fe750..9e04007617 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -151,8 +151,11 @@ export const docs = {
name: 'useXDSImperativeDialog',
displayName: 'useXDSImperativeDialog',
description: 'Hook for showing a dialog without managing open state. Call dialog.show(content, options) to open and dialog.hide() to close. Render dialog.element in your JSX tree.',
- props: [
- {name: 'show', type: '(content: ReactNode, options?: DialogOptions) => void', description: 'Show the dialog with the given content. Options are the same as XDSDialog props minus isOpen/onOpenChange/children.'},
+ params: [
+ {name: 'defaultOptions', type: 'DialogOptions', description: 'Default XDSDialog props to apply to every dialog shown by this hook, minus isOpen/onOpenChange/children.'},
+ ],
+ returns: [
+ {name: 'show', type: '(content: ReactNode, options?: DialogOptions) => void', description: 'Show the dialog with the given content. Options override or extend defaultOptions for this show call.'},
{name: 'hide', type: '() => void', description: 'Hide the dialog.'},
{name: 'isOpen', type: 'boolean', description: 'Whether the dialog is currently open.'},
{name: 'element', type: 'ReactNode', description: 'The dialog element — render this in your JSX tree.'},
diff --git a/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs b/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
index 14b1643427..50faf739b4 100644
--- a/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/useXDSHoverCard.doc.mjs
@@ -7,58 +7,32 @@ export const docs = {
group: 'HoverCard',
keywords: ['hovercard', 'hover', 'preview', 'card', 'tooltip', 'popup', 'floating', 'anchor'],
params: [
- {
- name: 'content',
- type: 'ReactNode | ((props: ContextRenderProps) => ReactNode)',
- description: 'Content to display in the hover card. Can be a render function receiving layer props.',
- required: true,
- },
- {
- name: 'placement',
- type: 'LayerPlacement',
- description: 'Position relative to the trigger.',
- default: "'below'",
- },
- {
- name: 'alignment',
- type: 'LayerAlignment',
- description: 'Alignment along the placement axis.',
- default: "'center'",
- },
- {
- name: 'delayMs',
- type: 'number',
- description: 'Delay before showing the hover card on hover.',
- default: '300',
- },
- {
- name: 'onShow',
- type: '() => void',
- description: 'Callback fired when the hover card becomes visible.',
- },
- {
- name: 'onHide',
- type: '() => void',
- description: 'Callback fired when the hover card is hidden.',
- },
+ {name: 'placement', type: 'LayerPlacement', description: 'Position relative to the trigger.', default: "'above'"},
+ {name: 'alignment', type: 'LayerAlignment', description: 'Alignment along the placement axis.', default: "'center'"},
+ {name: 'delay', type: 'number', description: 'Delay before showing the hover card on hover, in milliseconds.', default: '300'},
+ {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '200'},
+ {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
+ {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
+ {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
+ {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the hover card should be shown on mount.', default: 'false'},
+ {name: 'onShow', type: '() => void', description: 'Callback fired when the hover card becomes visible.'},
+ {name: 'onHide', type: '() => void', description: 'Callback fired when the hover card is hidden.'},
],
returns: [
- {
- name: 'triggerProps',
- type: 'object',
- description: 'Props to spread on the trigger element (ref, event handlers).',
- },
- {
- name: 'layerNode',
- type: 'ReactNode',
- description: 'The hover card layer to render (include in JSX output).',
- },
+ {name: 'ref', type: 'RefCallback<HTMLElement>', description: 'Combined ref that sets both position and interaction on the same trigger element.'},
+ {name: 'positionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the positioning anchor element. Use when position and interaction live on different elements.'},
+ {name: 'interactionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns.'},
+ {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
+ {name: 'describedBy', type: 'string', description: 'ID to compose into aria-describedby on the trigger.'},
+ {name: 'renderHoverCard', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for the anchor-positioned hover card content.'},
+ {name: 'show', type: '() => void', description: 'Imperatively show the hover card immediately.'},
+ {name: 'hide', type: '() => void', description: 'Imperatively hide the hover card immediately.'},
],
usage: {
- description: 'Headless hook for hover-triggered floating cards. Builds on useXDSLayer with hover/focus intent detection, delay, and safe triangle hover zones. Use for rich previews on hover without building the interaction logic.',
+ description: 'Headless hook for hover-triggered floating cards. Builds on useXDSLayer with hover/focus intent detection, configurable delays, safe hover behavior, and accessible aria-describedby linking. Use for rich previews on hover when you need full control over the trigger or rendered content.',
bestPractices: [
- {guidance: true, description: 'Use for rich content previews (user profiles, link previews) that benefit from hover interaction.'},
- {guidance: true, description: 'Prefer the XDSHoverCard component for standard cases — use the hook when you need full control over rendering.'},
+ {guidance: true, description: 'Use for rich content previews such as user profiles, entity summaries, and link previews.'},
+ {guidance: true, description: 'Prefer the XDSHoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.'},
{guidance: false, description: 'Use for simple text hints — use XDSTooltip or useXDSTooltip instead.'},
],
},
@@ -70,24 +44,34 @@ export const docs = {
/** @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.',
+ description: 'Headless hover-triggered floating cards. Builds on useXDSLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
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.',
+ delay: 'show delay in ms.',
+ hideDelay: 'hide delay after mouse/focus leave in ms.',
+ focusTrigger: 'when focus opens hover card; auto = naturally focusable elements only.',
+ isEnabled: 'whether hover/focus triggers are enabled.',
+ isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
+ isDefaultOpen: 'show on mount.',
+ onShow: 'fires when hover card becomes visible.',
+ onHide: 'fires when hover card hides.',
},
returnDescriptions: {
- triggerProps: 'props to spread on trigger element (ref, event handlers).',
- layerNode: 'hover card layer to render (include in JSX output).',
+ ref: 'combined position + interaction ref.',
+ positionRef: 'position anchor ref.',
+ interactionRef: 'hover/focus interaction ref.',
+ anchorId: 'CSS anchor name.',
+ describedBy: 'ID for aria-describedby.',
+ renderHoverCard: 'renders anchor-positioned hover card content.',
+ show: 'show immediately.',
+ hide: 'hide immediately.',
},
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.',
+ description: 'Headless hover-triggered floating cards. Builds on useXDSLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
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: true, description: 'Use for rich previews: profiles, entity summaries, link previews.'},
+ {guidance: true, description: 'Prefer XDSHoverCard for standard trigger-content pairs; use hook for custom trigger patterns.'},
{guidance: false, description: 'Use for simple text hints — use XDSTooltip / useXDSTooltip instead.'},
],
},
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
index 9b28510c3f..0135ff44ac 100644
--- a/packages/core/src/Layer/Layer.doc.mjs
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -1,63 +1,97 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/** @type {import('../docs-types').ComponentDoc} */
-
export const docs = {
- name: 'useXDSLayer',
- displayName: 'useXDSLayer',
+ name: 'Layer',
+ displayName: 'Layer',
group: 'Utilities',
- keywords: ["layer","overlay","popover","positioning","anchor","floating","dropdown","popper","popup","portal"],
- props: [
- {
- name: 'mode',
- type: "'context' | 'fixed'",
- description:
- 'Positioning strategy: context uses CSS anchor positioning relative to a trigger ref; fixed uses explicit x/y coordinates.',
- required: true,
- },
- {
- name: 'onShow',
- type: '() => void',
- description: 'Callback fired when the layer becomes visible.',
- },
- {
- name: 'onHide',
- type: '() => void',
- description: 'Callback fired when the layer is hidden.',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
- },
+ category: 'Utility',
+ keywords: [
+ 'layer',
+ 'overlay',
+ 'popover',
+ 'positioning',
+ 'anchor',
+ 'floating',
+ 'dropdown',
+ 'popper',
+ 'popup',
+ 'portal',
],
usage: {
description:
- 'Layer is a core positioning hook for rendering overlay content using CSS Anchor Positioning and the Popover API. Use it as the foundation for building popovers, hover cards, and tooltips without React portals.',
+ 'Layer utilities provide the app-level provider used by overlay systems. Use XDSLayerProvider at the app root for toast/layer configuration; use higher-level Popover, HoverCard, or Tooltip APIs for most overlay UI.',
bestPractices: [
- { guidance: true, description: 'Use context mode for anchor-positioned overlays relative to a trigger element, and fixed mode for manually positioned overlays at specific coordinates.' },
- { guidance: true, description: 'Build on higher-level components like Popover, HoverCard, and Tooltip instead of using Layer directly for common overlay patterns.' },
- { guidance: false, description: 'Implement ARIA patterns directly in a Layer — leave accessibility semantics to the higher-level components that build on it.' },
+ {
+ guidance: true,
+ description:
+ 'Use XDSLayerProvider once near the app root when you need shared toast/layer configuration.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Build on higher-level components like Popover, HoverCard, and Tooltip for common overlay patterns.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Add nested XDSLayerProvider instances — nested providers are ignored and add unnecessary tree depth.',
+ },
],
},
+ components: [
+ {
+ name: 'XDSLayerProvider',
+ displayName: 'Layer Provider',
+ description:
+ 'App-level provider for layer systems such as toast viewports and imperative modals. Nested providers pass through.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Application subtree that can use the shared layer context.',
+ required: true,
+ },
+ {
+ name: 'toast',
+ type: 'LayerToastConfig',
+ description:
+ 'Toast viewport configuration. Controls position, maxVisible, and inset for toasts shown through useXDSToast.',
+ },
+ ],
+ },
+ ],
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'Core positioning hook rendering overlay content via CSS Anchor Positioning + Popover API. Foundation for popovers/hover cards/tooltips w/o React portals.',
usage: {
description:
- 'Layer is core positioning hook for overlay content via CSS Anchor Positioning + Popover API. Use as foundation for popovers, hover cards, tooltips w/o React portals.',
+ 'App-level provider for overlay systems. Use XDSLayerProvider at app root for toast/layer config; use Popover/HoverCard/Tooltip for most overlay UI.',
bestPractices: [
- { guidance: true, description: 'Use context mode for anchor-positioned overlays relative to trigger element; fixed mode for manually positioned overlays at specific coordinates.' },
- { guidance: true, description: 'Build on higher-level components (Popover, HoverCard, Tooltip) instead of using Layer directly for common overlay patterns.' },
- { guidance: false, description: 'Implement ARIA patterns directly in Layer — leave accessibility semantics to higher-level components that build on it.' },
+ {
+ guidance: true,
+ description:
+ 'Use XDSLayerProvider once near app root for shared toast/layer config.',
+ },
+ {
+ guidance: true,
+ description: 'Use Popover/HoverCard/Tooltip for common overlay patterns.',
+ },
+ {
+ guidance: false,
+ description: 'Add nested XDSLayerProvider instances.',
+ },
],
},
- propDescriptions: {
- mode: 'positioning strategy: context = CSS anchor positioning relative to trigger ref; fixed = explicit x/y coords **(required)**',
- onShow: 'fires when layer becomes visible',
- onHide: 'fires when layer hidden',
- },
+ components: [
+ {
+ name: 'XDSLayerProvider',
+ description: 'App-level provider for toast/layer systems.',
+ propDescriptions: {
+ children: 'application subtree using shared layer context **(required)**',
+ toast: 'toast viewport config: position, maxVisible, inset',
+ },
+ },
+ ],
};
diff --git a/packages/core/src/Layer/useXDSLayer.doc.mjs b/packages/core/src/Layer/useXDSLayer.doc.mjs
new file mode 100644
index 0000000000..2510c6bab2
--- /dev/null
+++ b/packages/core/src/Layer/useXDSLayer.doc.mjs
@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+ name: 'useXDSLayer',
+ displayName: 'useXDSLayer',
+ group: 'Utilities',
+ keywords: [
+ 'layer',
+ 'overlay',
+ 'popover',
+ 'positioning',
+ 'anchor',
+ 'floating',
+ 'dropdown',
+ 'popper',
+ 'popup',
+ 'portal',
+ ],
+ params: [
+ {
+ name: 'mode',
+ type: "'context' | 'fixed'",
+ description:
+ 'Positioning strategy: context uses CSS anchor positioning relative to a trigger ref; fixed uses explicit x/y coordinates.',
+ required: true,
+ },
+ {
+ name: 'onShow',
+ type: '() => void',
+ description: 'Callback fired when the layer becomes visible.',
+ },
+ {
+ name: 'onHide',
+ type: '() => void',
+ description: 'Callback fired when the layer is hidden.',
+ },
+ {
+ name: 'lightDismiss',
+ type: 'boolean',
+ description:
+ 'Whether clicking outside should dismiss the layer using native popover light-dismiss behavior.',
+ default: 'false',
+ },
+ ],
+ returns: [
+ {
+ name: 'ref',
+ type: 'RefCallback<HTMLElement> | undefined',
+ description: 'Trigger ref for context mode. Undefined in fixed mode.',
+ },
+ {
+ name: 'anchorId',
+ type: 'string',
+ description: 'CSS anchor name for context mode positioning.',
+ },
+ {
+ name: 'show',
+ type: '() => void',
+ description: 'Imperatively show the layer.',
+ },
+ {
+ name: 'hide',
+ type: '() => void',
+ description: 'Imperatively hide the layer.',
+ },
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Whether the layer is currently open.',
+ },
+ {
+ name: 'id',
+ type: 'string',
+ description: 'Unique ID for aria-describedby or other ARIA relationships.',
+ },
+ {
+ name: 'render',
+ type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
+ description:
+ 'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode.',
+ },
+ ],
+ usage: {
+ description:
+ 'Core positioning hook for rendering overlay content using CSS Anchor Positioning and the Popover API. Use it as the foundation for custom popovers, hover cards, tooltips, and fixed-position layers when higher-level components are not enough.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Use context mode for anchor-positioned overlays relative to a trigger element, and fixed mode for manually positioned overlays at specific coordinates.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Build on higher-level components like Popover, HoverCard, and Tooltip for common overlay patterns.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Implement ARIA patterns directly in a Layer unless you also own the full accessibility behavior.',
+ },
+ ],
+ },
+ relatedComponents: ['LayerProvider', 'Popover', 'HoverCard', 'Tooltip'],
+ relatedHooks: ['useXDSPopover', 'useXDSHoverCard', 'useXDSTooltip'],
+ importPath: '@xds/core/Layer',
+ category: 'interaction',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+ description:
+ 'Core positioning hook for overlay content via CSS Anchor Positioning + Popover API. Foundation for custom popovers, hover cards, tooltips, fixed-position layers.',
+ paramDescriptions: {
+ mode: 'positioning strategy: context = CSS anchor relative to trigger; fixed = explicit x/y coords. **(required)**',
+ onShow: 'fires when layer becomes visible.',
+ onHide: 'fires when layer hides.',
+ lightDismiss: 'whether native outside-click light-dismiss is enabled.',
+ },
+ returnDescriptions: {
+ ref: 'trigger ref for context mode; undefined in fixed mode.',
+ anchorId: 'CSS anchor name.',
+ show: 'show layer.',
+ hide: 'hide layer.',
+ isOpen: 'whether layer is open.',
+ id: 'unique ARIA id.',
+ render: 'renders popover element; pass placement/alignment or x/y.',
+ },
+ usage: {
+ description:
+ 'Core positioning hook for overlay content via CSS Anchor Positioning + Popover API. Foundation for custom popovers, hover cards, tooltips, fixed-position layers.',
+ bestPractices: [
+ {
+ guidance: true,
+ description: 'Use context mode for trigger-anchored overlays; fixed mode for explicit coordinates.',
+ },
+ {
+ guidance: true,
+ description: 'Build on Popover/HoverCard/Tooltip for common overlay patterns.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Implement ARIA directly in Layer unless you own full accessibility behavior.',
+ },
+ ],
+ },
+};
diff --git a/packages/core/src/Popover/useXDSPopover.doc.mjs b/packages/core/src/Popover/useXDSPopover.doc.mjs
index 85e24fc794..d3d2c1dd49 100644
--- a/packages/core/src/Popover/useXDSPopover.doc.mjs
+++ b/packages/core/src/Popover/useXDSPopover.doc.mjs
@@ -7,84 +7,33 @@ export const docs = {
group: 'Popover',
keywords: ['popover', 'popup', 'dropdown', 'floating', 'anchor', 'dialog', 'overlay', 'flyout'],
params: [
- {
- name: 'content',
- type: 'ReactNode | ((props: ContextRenderProps) => ReactNode)',
- description: 'Content to display in the popover. Can be a render function receiving layer props.',
- required: true,
- },
- {
- name: 'placement',
- type: 'LayerPlacement',
- description: 'Position relative to the trigger.',
- default: "'below'",
- },
- {
- name: 'alignment',
- type: 'LayerAlignment',
- description: 'Alignment along the placement axis.',
- default: "'start'",
- },
- {
- name: 'hasLightDismiss',
- type: 'boolean',
- description: 'Whether clicking outside dismisses the popover.',
- default: 'true',
- },
- {
- name: 'hasSurface',
- type: 'boolean',
- description: 'Whether to apply the default popover surface styles (background, shadow, radius).',
- default: 'true',
- },
- {
- name: 'onShow',
- type: '() => void',
- description: 'Callback fired when the popover becomes visible.',
- },
- {
- name: 'onHide',
- type: '() => void',
- description: 'Callback fired when the popover is hidden.',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description: 'StyleX styles for the popover surface (margins, sizing). Must be a stylex.create() value — not an inline style object. Note: for styles that interact with :popover-open, pass xstyle via the render() call props instead.',
- },
+ {name: 'onShow', type: '() => void', description: 'Callback fired when the popover becomes visible.'},
+ {name: 'onHide', type: '() => void', description: 'Callback fired when the popover is hidden. Use this to return focus to the trigger when needed.'},
+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles applied to the popover content wrapper, after the default surface styles.'},
+ {name: 'hasLightDismiss', type: 'boolean', description: 'Whether clicking outside dismisses the popover.', default: 'true'},
+ {name: 'hasAutoFocus', type: 'boolean', description: 'Whether to automatically focus the first focusable element when opened.', default: 'true'},
+ {name: 'hasCloseButton', type: 'boolean', description: 'Whether to include a hidden close button that appears for keyboard users.', default: 'true'},
+ {name: 'closeButtonLabel', type: 'string', description: 'Accessible label for the hidden close button.', default: "'Close popover'"},
+ {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog. Provide one when there is no visible title.'},
+ {name: 'hasSurface', type: 'boolean', description: 'Whether to apply the default popover surface background, radius, and shadow.', default: 'true'},
],
returns: [
- {
- name: 'triggerProps',
- type: 'object',
- description: 'Props to spread on the trigger element (ref, aria-expanded, event handlers).',
- },
- {
- name: 'layerNode',
- type: 'ReactNode',
- description: 'The popover layer to render (include in JSX output).',
- },
- {
- name: 'isOpen',
- type: 'boolean',
- description: 'Whether the popover is currently visible.',
- },
- {
- name: 'show',
- type: '() => void',
- description: 'Imperatively show the popover.',
- },
- {
- name: 'hide',
- type: '() => void',
- description: 'Imperatively hide the popover.',
- },
+ {name: 'triggerRef', type: '(el: HTMLElement | null) => void', description: 'Ref callback to attach to the trigger element for CSS anchor positioning.'},
+ {name: 'contentRef', type: 'RefObject<HTMLDivElement | null>', description: 'Ref for the popover content container used by focus trapping.'},
+ {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
+ {name: 'show', type: '(options?: {skipAutoFocus?: boolean}) => void', description: 'Imperatively show the popover. skipAutoFocus preserves current focus for input-triggered popovers.'},
+ {name: 'hide', type: '() => void', description: 'Imperatively hide the popover.'},
+ {name: 'toggle', type: '() => void', description: 'Toggle the popover open or closed.'},
+ {name: 'isOpen', type: 'boolean', description: 'Whether the popover is currently open.'},
+ {name: 'id', type: 'string', description: 'Unique ID for aria-describedby or aria-controls.'},
+ {name: 'render', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for anchor-positioned popover content. Pass placement and alignment here.'},
+ {name: 'triggerProps', type: '{aria-haspopup: "dialog"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element.'},
],
usage: {
- description: 'Headless hook for click-triggered popovers with focus trapping. Combines useXDSLayer with useFocusTrap for dialog-like popover behavior. Use for interactive floating content that needs keyboard navigation.',
+ description: 'Headless hook for click-triggered popovers with focus trapping. Combines useXDSLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Use for custom interactive floating content that needs keyboard navigation.',
bestPractices: [
- {guidance: true, description: 'Use for interactive content (forms, menus, pickers) that needs focus trapping and light dismiss.'},
- {guidance: true, description: 'Prefer the XDSPopover component for standard trigger-content pairs — use the hook for custom trigger patterns.'},
+ {guidance: true, description: 'Use for interactive content such as menus, pickers, forms, and command panels that need focus management.'},
+ {guidance: true, description: 'Prefer the XDSPopover component for standard trigger-content pairs; use the hook for custom trigger patterns.'},
{guidance: false, description: 'Use for non-interactive hover previews — use useXDSHoverCard or useXDSTooltip instead.'},
],
},
@@ -96,29 +45,35 @@ export const docs = {
/** @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.',
+ description: 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Use for custom interactive floating content needing keyboard nav.',
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.',
+ onShow: 'fires when popover becomes visible.',
+ onHide: 'fires when popover hides; use to return focus when needed.',
+ xstyle: 'StyleX styles for content wrapper, after default surface.',
+ hasLightDismiss: 'whether outside click dismisses popover.',
+ hasAutoFocus: 'whether first focusable element receives focus on open.',
+ hasCloseButton: 'whether hidden keyboard close button is included.',
+ closeButtonLabel: 'label for hidden close button.',
+ dialogLabel: 'accessible label for popover dialog.',
+ hasSurface: 'apply default surface background/radius/shadow.',
},
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.',
+ triggerRef: 'trigger ref for CSS anchor positioning.',
+ contentRef: 'content container ref for focus trap.',
+ anchorId: 'CSS anchor name.',
+ show: 'show popover; skipAutoFocus preserves current focus.',
+ hide: 'hide popover.',
+ toggle: 'toggle open/closed.',
+ isOpen: 'whether currently open.',
+ id: 'unique ARIA id.',
+ render: 'renders anchor-positioned popover content.',
+ triggerProps: 'ARIA attrs for trigger.',
},
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.',
+ description: 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Use for custom interactive floating content needing keyboard nav.',
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: true, description: 'Use for menus, pickers, forms, command panels needing focus management.'},
+ {guidance: true, description: 'Prefer XDSPopover 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/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index c61dd2fcd3..bf57896df2 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -146,53 +146,17 @@ export const docs = {
displayName: 'useXDSTableSelection',
description:
'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
- props: [
- {
- name: 'getIsItemSelected',
- type: '(item: T) => boolean',
- description: 'Returns whether the given item is currently selected.',
- required: true,
- },
- {
- name: 'onSelectItem',
- type: '(event: {item: T; isSelected: boolean}) => void',
- description:
- 'Called when a row checkbox is toggled. isSelected is the new desired state.',
- required: true,
- },
- {
- name: 'onSelectAll',
- type: '(event: {isAllSelected: boolean}) => void',
- description: 'Called when the select-all header checkbox is toggled.',
- required: true,
- },
- {
- name: 'getIsAllSelected',
- type: '() => boolean',
- description:
- 'Returns whether all selectable items are currently selected.',
- required: true,
- },
- {
- name: 'getIsIndeterminate',
- type: '() => boolean',
- description:
- 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
- },
- {
- name: 'getIsItemSelectable',
- type: '(item: T) => boolean',
- description:
- 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
- default: '() => true',
- },
- {
- name: 'getIsItemEnabled',
- type: '(item: T) => boolean',
- description:
- 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
- default: '() => true',
- },
+ params: [
+ {name: 'getIsItemSelected', type: '(item: T) => boolean', description: 'Returns whether the given item is currently selected.', required: true},
+ {name: 'onSelectItem', type: '(event: {item: T; isSelected: boolean}) => void', description: 'Called when a row checkbox is toggled. isSelected is the new desired state.', required: true},
+ {name: 'onSelectAll', type: '(event: {isAllSelected: boolean}) => void', description: 'Called when the select-all header checkbox is toggled.', required: true},
+ {name: 'getIsAllSelected', type: '() => boolean', description: 'Returns whether all selectable items are currently selected.', required: true},
+ {name: 'getIsIndeterminate', type: '() => boolean', description: 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.'},
+ {name: 'getIsItemSelectable', type: '(item: T) => boolean', description: 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.', default: '() => true'},
+ {name: 'getIsItemEnabled', type: '(item: T) => boolean', description: 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.', default: '() => true'},
+ ],
+ returns: [
+ {name: 'value', type: 'TablePlugin<T>', description: 'Selection plugin to pass to XDSTable plugins. It prepends the checkbox column and applies selected row state.'},
],
},
{
@@ -200,46 +164,16 @@ export const docs = {
displayName: 'useXDSTableSelectionState',
description:
'State management companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically — disabled rows are frozen (preserved across select-all/deselect-all), non-selectable rows are excluded.',
- props: [
- {
- name: 'data',
- type: 'T[]',
- description: 'The full data array rendered in the table.',
- required: true,
- },
- {
- name: 'idKey',
- type: '(keyof T & string) | ((item: T) => string)',
- description:
- 'Key extractor — property name or function returning a unique string ID.',
- required: true,
- },
- {
- name: 'selectedKeys',
- type: 'Set<string>',
- description: 'Controlled set of selected item IDs.',
- required: true,
- },
- {
- name: 'setSelectedKeys',
- type: 'Dispatch<SetStateAction<Set<string>>>',
- description: 'Setter for the controlled selected keys.',
- required: true,
- },
- {
- name: 'getIsItemSelectable',
- type: '(item: T) => boolean',
- description:
- 'Should this row show a checkbox? Non-selectable rows are excluded from select-all.',
- default: '() => true',
- },
- {
- name: 'getIsItemEnabled',
- type: '(item: T) => boolean',
- description:
- 'Is this row checkbox interactive? Disabled rows are frozen — select-all preserves their state.',
- default: '() => true',
- },
+ params: [
+ {name: 'data', type: 'T[]', description: 'The data array currently rendered in the table. Select-all operates on this array.', required: true},
+ {name: 'idKey', type: '(keyof T & string) | ((item: T) => string)', description: 'Key extractor — property name or function returning a unique string ID.', required: true},
+ {name: 'selectedKeys', type: 'Set<string>', description: 'Controlled set of selected item IDs.', required: true},
+ {name: 'setSelectedKeys', type: 'Dispatch<SetStateAction<Set<string>>>', description: 'Setter for the controlled selected keys.', required: true},
+ {name: 'getIsItemSelectable', type: '(item: T) => boolean', description: 'Should this row show a checkbox? Non-selectable rows are excluded from select-all.', default: '() => true'},
+ {name: 'getIsItemEnabled', type: '(item: T) => boolean', description: 'Is this row checkbox interactive? Disabled rows are frozen — select-all preserves their state.', default: '() => true'},
+ ],
+ returns: [
+ {name: 'selectionConfig', type: 'UseXDSTableSelectionConfig<T>', description: 'Ready-to-use config object to pass directly to useXDSTableSelection.'},
],
},
{
@@ -247,35 +181,14 @@ export const docs = {
displayName: 'useXDSTableSortable',
description:
'Headless multi-sort plugin for XDSTable. The consumer owns sort state and provides a callback. Shift+click enables secondary sort columns. Sort indicators render in header cells automatically.',
- props: [
- {
- name: 'sort',
- type: 'XDSTableSortState<TSortKey>',
- description:
- 'Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.',
- required: true,
- },
- {
- name: 'onSortChange',
- type: '(sort: XDSTableSortState<TSortKey>) => void',
- description:
- 'Called when the user clicks a header cell to change sort.',
- required: true,
- },
- {
- name: 'allowUnsortedState',
- type: 'boolean',
- description:
- 'Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.',
- default: 'false',
- },
- {
- name: 'isMultiSortEnabled',
- type: 'boolean',
- description:
- 'Enable multi-sort via Shift+click. Regular click still replaces the entire sort state.',
- default: 'false',
- },
+ params: [
+ {name: 'sort', type: 'XDSTableSortState<TSortKey>', description: 'Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.', required: true},
+ {name: 'onSortChange', type: '(sort: XDSTableSortState<TSortKey>) => void', description: 'Called when the user clicks a header cell to change sort.', required: true},
+ {name: 'allowUnsortedState', type: 'boolean', description: 'Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.', default: 'true'},
+ {name: 'isMultiSortEnabled', type: 'boolean', description: 'Enable multi-sort via Shift+click. Regular click still replaces the entire sort state.', default: 'false'},
+ ],
+ returns: [
+ {name: 'value', type: 'TablePlugin<T>', description: 'Sorting plugin to pass to XDSTable plugins. It augments sortable header cells with buttons, indicators, and aria-sort.'},
],
},
{
@@ -283,110 +196,38 @@ export const docs = {
displayName: 'useXDSTablePagination',
description:
'Headless pagination plugin for XDSTable. Supports client-side slicing, server-side pagination, and cursor-based pagination. Renders XDSPagination controls automatically above, below, or both.',
- props: [
- {
- name: 'page',
- type: 'number',
- description: 'Current page number (1-based).',
- required: true,
- },
- {
- name: 'onPageChange',
- type: '(page: number) => void',
- description: 'Called when the page changes.',
- required: true,
- },
- {
- name: 'totalItems',
- type: 'number',
- description:
- 'Total number of items across all pages. Used to calculate total page count.',
- },
- {
- name: 'totalPages',
- type: 'number',
- description:
- 'Total number of pages. Use when you know the page count but not item count.',
- },
- {
- name: 'hasMore',
- type: 'boolean',
- description:
- 'Whether more pages exist. Use for cursor-based pagination where the total is unknown.',
- },
- {
- name: 'pageSize',
- type: 'number',
- description: 'Number of items per page.',
- default: '10',
- },
- {
- name: 'onPageSizeChange',
- type: '(pageSize: number) => void',
- description:
- 'Called when the user changes the page size. Shows a page size dropdown when provided with pageSizeOptions.',
- },
- {
- name: 'pageSizeOptions',
- type: 'number[]',
- description:
- 'Available page size options. Shows a page size selector when provided.',
- },
- {
- name: 'variant',
- type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
- description: 'Visual variant for the pagination controls.',
- default: "'pages'",
- },
- {
- name: 'position',
- type: "'below' | 'above' | 'both' | 'none'",
- description:
- 'Where to render pagination controls relative to the table.',
- default: "'below'",
- },
- {
- name: 'align',
- type: "'start' | 'center' | 'end'",
- description:
- 'Horizontal alignment of the pagination controls.',
- default: "'center'",
- },
+ params: [
+ {name: 'page', type: 'number', description: 'Current page number (1-based).', required: true},
+ {name: 'onPageChange', type: '(page: number) => void', description: 'Called when the page changes.', required: true},
+ {name: 'totalItems', type: 'number', description: 'Total number of items across all pages. Used to calculate total page count.'},
+ {name: 'totalPages', type: 'number', description: 'Total number of pages. Use when you know the page count but not item count.'},
+ {name: 'hasMore', type: 'boolean', description: 'Whether more pages exist. Use for cursor-based pagination where the total is unknown.'},
+ {name: 'pageSize', type: 'number', description: 'Number of items per page.', default: '10'},
+ {name: 'onPageSizeChange', type: '(pageSize: number) => void', description: 'Called when the user changes the page size. Shows a page size dropdown when provided with pageSizeOptions.'},
+ {name: 'pageSizeOptions', type: 'number[]', description: 'Available page size options. Shows a page size selector when provided.'},
+ {name: 'variant', type: "'pages' | 'count' | 'compact' | 'dots' | 'none'", description: 'Visual variant for the pagination controls.', default: "'pages'"},
+ {name: 'size', type: "'sm' | 'md'", description: 'Size of the pagination controls.', default: "'md'"},
+ {name: 'position', type: "'below' | 'above' | 'both' | 'none'", description: 'Where to render pagination controls relative to the table.', default: "'below'"},
+ {name: 'align', type: "'start' | 'center' | 'end'", description: 'Horizontal alignment of the pagination controls.', default: "'center'"},
+ {name: 'label', type: 'string', description: 'Accessible label for the pagination nav landmark.', default: "'Table pagination'"},
+ ],
+ returns: [
+ {name: 'value', type: 'TablePlugin<T>', description: 'Pagination plugin to pass to XDSTable plugins. It renders pagination controls around the table.'},
],
},
{
name: 'useXDSTableColumnSettings',
displayName: 'useXDSTableColumnSettings',
description:
- 'Headless column visibility and ordering management for XDSTable. Provides filtered columns, toggle helpers, and pre-built XDSMultiSelector options for a column picker UI.',
- props: [
- {
- name: 'columns',
- type: 'XDSColumnSettingsOption[]',
- description:
- 'All available columns with metadata for the settings UI. Each entry has key, label, optional isAlwaysVisible and group.',
- required: true,
- },
- {
- name: 'activeColumnKeys',
- type: 'string[]',
- description:
- 'Currently active column keys, in display order. Only columns with keys in this array are shown.',
- required: true,
- },
- {
- name: 'onChangeActiveColumnKeys',
- type: '(keys: string[]) => void',
- description:
- 'Called when active columns change (toggle, reorder).',
- required: true,
- },
- {
- name: 'defaultColumnKeys',
- type: 'string[]',
- description:
- 'Default column set for "Reset to default". When omitted, reset shows all columns.',
- },
+ 'Headless column visibility and ordering plugin for XDSTable. It filters and reorders the table columns from a controlled active-column key list.',
+ params: [
+ {name: 'columns', type: 'ReadonlyArray<XDSColumnSettingsOption<TColumnKey>>', description: 'All available columns with metadata for the settings UI. Each entry has key, label, optional isAlwaysVisible and group.', required: true},
+ {name: 'activeColumnKeys', type: 'ReadonlyArray<TColumnKey>', description: 'Currently active column keys, in display order. Only columns with keys in this array are shown.', required: true},
+ {name: 'onChangeActiveColumnKeys', type: '(keys: ReadonlyArray<TColumnKey>) => void', description: 'Called when active columns change (toggle, reorder).', required: true},
+ {name: 'defaultColumnKeys', type: 'ReadonlyArray<TColumnKey>', description: 'Default column set for Reset to default. When omitted, reset shows all columns.'},
+ ],
+ returns: [
+ {name: 'value', type: 'TablePlugin<T>', description: 'Column settings plugin to pass to XDSTable plugins. It filters and orders columns by activeColumnKeys.'},
],
},
{
@@ -394,29 +235,15 @@ export const docs = {
isHiddenFromOverview: true,
displayName: 'useXDSTableFiltering',
description:
- 'Table plugin that adds inline column filters with popover or inline controls. Pairs with useXDSTableFilterState for managed state. Supports text, select, multi-select, date, and number filter types via PowerSearch field definitions.',
- props: [
- {
- name: 'filters',
- type: 'XDSTableFilterState',
- description:
- 'Current filter state — map from column key to filter value.',
- required: true,
- },
- {
- name: 'onFilterChange',
- type: '(columnKey: string, value: XDSTableFilterValue | null) => void',
- description:
- 'Called when the user changes a filter value. null clears the filter.',
- required: true,
- },
- {
- name: 'variant',
- type: "'popover' | 'inline'",
- description:
- 'Display variant for filter controls.',
- default: "'popover'",
- },
+ 'Table plugin that adds inline column filters with popover or inline controls. Pairs with useXDSTableFilterState for managed state. Supports text, select, multi-select, date, time, number, and tokenizer filter types via PowerSearch field definitions.',
+ params: [
+ {name: 'filters', type: 'XDSTableFilterState', description: 'Current filter state — map from column key to filter value.', required: true},
+ {name: 'onFilterChange', type: '(columnKey: string, value: XDSTableFilterValue | null) => void', description: 'Called when the user changes a filter value. null clears the filter.', required: true},
+ {name: 'variant', type: "'popover' | 'inline' | 'inline-compact'", description: 'Display variant for filter controls.', default: "'popover'"},
+ {name: 'searchConfig', type: 'PowerSearchConfig', description: 'PowerSearch field definitions used to resolve each column filter to the correct control type.', required: true},
+ ],
+ returns: [
+ {name: 'value', type: 'TablePlugin<T>', description: 'Filtering plugin to pass to XDSTable plugins. It renders filter controls in header cells.'},
],
},
{
@@ -424,14 +251,14 @@ export const docs = {
isHiddenFromOverview: true,
displayName: 'useXDSTableFilterState',
description:
- 'Managed state hook for table filtering. Returns the current filter map and an onChange handler. Pass the result directly to useXDSTableFiltering.',
- props: [
- {
- name: 'initialState',
- type: 'XDSTableFilterState',
- description:
- 'Optional initial filter state map.',
- },
+ 'Managed state hook for table filtering. Returns the current filter map, a typed onChange handler, and a clearAll helper. Pass filters and onFilterChange directly to useXDSTableFiltering.',
+ params: [
+ {name: 'initialState', type: 'XDSTableFilterState', description: 'Optional initial filter state map.'},
+ ],
+ returns: [
+ {name: 'filters', type: 'XDSTableFilterState', description: 'Current filter state map. Pass to useXDSTableFiltering.'},
+ {name: 'onFilterChange', type: '(key: string, value: XDSTableFilterValue | null) => void', description: 'Filter change handler. Pass to useXDSTableFiltering.'},
+ {name: 'clearAll', type: '() => void', description: 'Reset all filters to an empty state.'},
],
},
],
diff --git a/packages/core/src/Tooltip/useXDSTooltip.doc.mjs b/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
index ab06e16ca7..a10117282d 100644
--- a/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
+++ b/packages/core/src/Tooltip/useXDSTooltip.doc.mjs
@@ -7,49 +7,31 @@ export const docs = {
group: 'Tooltip',
keywords: ['tooltip', 'hint', 'label', 'hover', 'info', 'title', 'floating'],
params: [
- {
- name: 'content',
- type: 'ReactNode',
- description: 'Text or content to display in the tooltip.',
- required: true,
- },
- {
- name: 'placement',
- type: 'LayerPlacement',
- description: 'Position relative to the trigger.',
- default: "'above'",
- },
- {
- name: 'alignment',
- type: 'LayerAlignment',
- description: 'Alignment along the placement axis.',
- default: "'center'",
- },
- {
- name: 'delayMs',
- type: 'number',
- description: 'Delay before showing the tooltip on hover.',
- default: '300',
- },
+ {name: 'placement', type: 'LayerPlacement', description: 'Position relative to the trigger.', default: "'above'"},
+ {name: 'alignment', type: 'LayerAlignment', description: 'Alignment along the placement axis.', default: "'center'"},
+ {name: 'delay', type: 'number', description: 'Delay before showing on hover, in milliseconds.', default: '200'},
+ {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '0'},
+ {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the tooltip. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
+ {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
+ {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
+ {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the tooltip should be shown on mount.', default: 'false'},
+ {name: 'onShow', type: '() => void', description: 'Callback fired when the tooltip becomes visible.'},
+ {name: 'onHide', type: '() => void', description: 'Callback fired when the tooltip is hidden.'},
],
returns: [
- {
- name: 'triggerProps',
- type: 'object',
- description: 'Props to spread on the trigger element (ref, aria-describedby, event handlers).',
- },
- {
- name: 'layerNode',
- type: 'ReactNode',
- description: 'The tooltip layer to render (include in JSX output).',
- },
+ {name: 'ref', type: 'RefCallback<HTMLElement>', description: 'Combined ref that sets both position and interaction on the same trigger element.'},
+ {name: 'positionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the positioning anchor element.'},
+ {name: 'interactionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the hover/focus interaction element.'},
+ {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
+ {name: 'describedBy', type: 'string', description: 'ID to compose into aria-describedby on the trigger.'},
+ {name: 'renderTooltip', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for the anchor-positioned tooltip content.'},
],
usage: {
- description: 'Headless hook for hover/focus-triggered tooltips. Builds on useXDSLayer with hover intent, delay, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior.',
+ description: 'Headless hook for hover/focus-triggered tooltips. Builds on useXDSLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.',
bestPractices: [
- {guidance: true, description: 'Use for brief text labels that describe a UI element — icon buttons, truncated text, abbreviations.'},
- {guidance: true, description: 'Prefer the XDSTooltip component for standard wrapping — use the hook when the trigger is not a simple child.'},
- {guidance: false, description: 'Put interactive content (links, buttons) inside tooltips — use Popover or HoverCard instead.'},
+ {guidance: true, description: 'Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.'},
+ {guidance: true, description: 'Prefer the XDSTooltip component for standard wrapping; use the hook when the trigger is not a simple child.'},
+ {guidance: false, description: 'Put interactive content inside tooltips — use Popover or HoverCard instead.'},
],
},
relatedComponents: ['Tooltip', 'HoverCard', 'Popover'],
@@ -60,23 +42,33 @@ export const docs = {
/** @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.',
+ description: 'Headless hover/focus tooltip hook. Builds on useXDSLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
paramDescriptions: {
- content: 'text / content for tooltip.',
placement: 'position relative to trigger.',
alignment: 'alignment along placement axis.',
- delayMs: 'delay before showing tooltip on hover.',
+ delay: 'show delay in ms.',
+ hideDelay: 'hide delay after mouse/focus leave in ms.',
+ focusTrigger: 'when focus opens tooltip; auto = naturally focusable elements only.',
+ isEnabled: 'whether hover/focus triggers are enabled.',
+ isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
+ isDefaultOpen: 'show on mount.',
+ onShow: 'fires when tooltip becomes visible.',
+ onHide: 'fires when tooltip hides.',
},
returnDescriptions: {
- triggerProps: 'props to spread on trigger element (ref, aria-describedby, event handlers).',
- layerNode: 'tooltip layer to render (include in JSX output).',
+ ref: 'combined position + interaction ref.',
+ positionRef: 'position anchor ref.',
+ interactionRef: 'hover/focus interaction ref.',
+ anchorId: 'CSS anchor name.',
+ describedBy: 'ID for aria-describedby.',
+ renderTooltip: 'renders anchor-positioned tooltip content.',
},
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.',
+ description: 'Headless hover/focus tooltip hook. Builds on useXDSLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
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.'},
+ {guidance: true, description: 'Use for brief text labels describing icon buttons, truncated text, abbreviations, compact controls.'},
+ {guidance: true, description: 'Prefer XDSTooltip for standard wrapping; use hook when trigger is not simple child.'},
+ {guidance: false, description: 'Put interactive content in tooltips — use Popover / HoverCard instead.'},
],
},
};
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index 48bd2c5502..02491b6519 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -180,9 +180,11 @@ export interface ComponentVar {
* directory exports multiple public components (e.g. Table exports XDSTable,
* XDSBaseTable, XDSTableRow, XDSTableCell, XDSTableHeaderCell).
*
- * Also use for hooks with config objects (e.g. useXDSTableSelection) —
- * treat config options as "props". Order components with the primary/most-used
- * component first.
+ * Also use for hooks that are part of a component API (e.g.
+ * useXDSTableSelection). For hook entries, document arguments in `params`
+ * and return fields in `returns` so the docsite renders a Parameters / Returns
+ * signature instead of an interactive Properties playground. Order components
+ * with the primary/most-used component first.
*/
export interface ComponentEntry {
/** Full export name including XDS prefix. e.g. `"XDSTableRow"`,
@@ -195,8 +197,18 @@ export interface ComponentEntry {
/** One-sentence description of what this specific component does.
* For sub-components, explain the role within the parent composition. */
description: string;
- /** All public props for this component. */
- props: PropDoc[];
+ /** All public props for this component. Omit for hook entries. */
+ props?: PropDoc[];
+ /** Hook parameters or options object fields. Use for `use*` entries. */
+ params?: HookParamDoc[];
+ /** Hook return value fields. Use for `use*` entries. */
+ returns?: HookReturnDoc[];
+ /** Usage documentation for this specific component or hook. */
+ usage?: UsageDoc;
+ /** Components this hook is commonly used with. */
+ relatedComponents?: string[];
+ /** Other hooks this hook is commonly used with. */
+ relatedHooks?: string[];
/** Short code examples rendered by the CLI after the props table. */
examples?: ExampleDoc[];
/** When true, this sub-component is excluded from the overview page. */
@@ -844,6 +856,14 @@ export interface BlockTemplateDoc extends BaseTemplateDoc {
* Matches the component's doc name (e.g. 'Button', 'Dialog', 'Stack').
* Used by the docsite to show relevant examples on component detail pages. */
exampleFor: string;
+ /** Additional component or hook doc pages whose Examples section should
+ * include this block. Use when a component example is also the canonical
+ * usage example for one of that component's hooks. */
+ alsoExampleFor?: string[];
+ /** Additional component or hook doc pages whose hero showcase should reuse
+ * this block. Unlike `isShowcase`, this does not make the block the primary
+ * showcase for `exampleFor`; it only creates explicit secondary placements. */
+ alsoShowcaseFor?: string[];
/** Width-to-height ratio for preview containers (e.g. 16/9, 1, 3/4). */
aspectRatio: number;
/** Scale factor for the block preview (default 1). */
diff --git a/packages/core/src/theme/useXDSTheme.doc.mjs b/packages/core/src/theme/useXDSTheme.doc.mjs
new file mode 100644
index 0000000000..0aaf7a9098
--- /dev/null
+++ b/packages/core/src/theme/useXDSTheme.doc.mjs
@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+ name: 'useXDSTheme',
+ displayName: 'useXDSTheme',
+ group: 'Utilities',
+ category: 'Utility',
+ keywords: ['theme', 'tokens', 'color', 'mode', 'dark', 'light', 'provider', 'data visualization', 'canvas', 'svg'],
+ params: [],
+ returns: [
+ {name: 'name', type: 'string', description: 'Name of the nearest XDS theme, or default when no provider is present.'},
+ {name: 'mode', type: "'light' | 'dark'", description: 'Resolved effective color mode. system mode is resolved to light or dark.'},
+ {name: 'token', type: '(name: string) => string', description: 'Resolve a single design token to its concrete CSS value for the current mode.'},
+ {name: 'tokens', type: 'Record<string, string>', description: 'All tokens resolved for the current mode, including defaults and theme overrides.'},
+ ],
+ usage: {
+ description: 'Programmatic access to resolved XDS theme tokens. Use it for non-CSS consumers like SVG, canvas, Vega, D3, or chart libraries that need concrete values instead of CSS custom property references.',
+ bestPractices: [
+ {guidance: true, description: 'Use token(name) when integrating theme colors into SVG, canvas, or chart configuration objects.'},
+ {guidance: true, description: 'Prefer CSS variables or StyleX tokens for ordinary component styling; use this hook when values must be read in JavaScript.'},
+ {guidance: false, description: 'Hardcode light/dark colors in data visualizations — resolve them through the current theme instead.'},
+ ],
+ },
+ relatedComponents: ['Theme'],
+ relatedHooks: ['useMediaQuery'],
+ importPath: '@xds/core/theme',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+ description: 'Programmatic access to resolved XDS theme tokens for SVG/canvas/charts needing concrete values instead of CSS vars.',
+ returnDescriptions: {
+ name: 'nearest XDS theme name or default.',
+ mode: 'resolved light/dark mode.',
+ token: 'resolve one design token to concrete CSS value.',
+ tokens: 'all resolved tokens for current mode.',
+ },
+ usage: {
+ description: 'Programmatic access to resolved XDS theme tokens for SVG/canvas/charts needing concrete values instead of CSS vars.',
+ bestPractices: [
+ {guidance: true, description: 'Use token(name) for SVG/canvas/chart config theme colors.'},
+ {guidance: true, description: 'Prefer CSS vars / StyleX tokens for ordinary styling; use hook when JS needs values.'},
+ {guidance: false, description: 'Hardcode light/dark chart colors — resolve from current theme.'},
+ ],
+ },
+};