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.mjsindex 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 componentdiff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 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 firstdiff --git a/apps/docsite/src/components/component-detail/HookSignature.tsx b/apps/docsite/src/components/component-detail/HookSignature.tsxindex 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.mjsindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.tsindex 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.mjsnew file mode 100644index 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.'},+ ],+ },+};