Skip to content

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

TypeScript

refactor(docs): one .doc.mjs per component — pipeline + Chat family (#2650)

Joey0a39b0bb5371
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 9c6775d401..273bf32753 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -350,16 +350,31 @@ async function generateComponentRegistry() {
const docFiles = fs.readdirSync(dirPath).filter(f => f.endsWith('.doc.mjs'));
if (docFiles.length === 0) continue;
- // First pass: find the primary component doc name for this directory
- // (used to parent standalone hook docs that share the directory)
+ // First pass: find the primary component doc for this directory. Used to
+ // (a) parent standalone hook docs that share the directory, and
+ // (b) let sibling sub-component docs (subComponentOf) inherit family
+ // fields (group, category, keywords, theming, importPath, ...).
let dirPrimaryDoc = null;
+ let dirPrimaryMeta = null;
for (const df of docFiles) {
const dfPath = path.join(dirPath, df);
try {
const mod = await import(pathToFileURL(dfPath).href);
const d = mod.docs;
- if (d && (d.components || d.props) && !d.params) {
+ if (d && (d.components || d.props) && !d.params && !d.subComponentOf) {
dirPrimaryDoc = d.name || null;
+ dirPrimaryMeta = {
+ name: d.name || null,
+ group: d.group || null,
+ category: d.category || null,
+ keywords: d.keywords || [],
+ hidden: d.hidden ?? false,
+ isHiddenFromOverview: d.isHiddenFromOverview ?? false,
+ topDescription: d.usage?.description || d.description || '',
+ usage: d.usage ? sanitizeForJson(d.usage) : null,
+ theming: d.theming ? sanitizeForJson(d.theming) : null,
+ playground: d.playground ? sanitizeForJson(d.playground) : null,
+ };
break;
}
} catch { /* ignore */ }
@@ -388,12 +403,118 @@ async function generateComponentRegistry() {
const theming = doc.theming ? sanitizeForJson(doc.theming) : null;
const playground = doc.playground ? sanitizeForJson(doc.playground) : null;
- if (doc.components && doc.components.length > 0) {
+ if (doc.subComponentOf) {
+ // Extracted sub-component: lives in its parent's directory in its own
+ // .doc.mjs file. Inherits family fields (group, category, keywords,
+ // theming, playground, importPath) from the directory's primary doc;
+ // owns its name, description, props, and usage. Produces a registry
+ // entry identical to the legacy inline `components[]` expansion.
+ const parentMeta = dirPrimaryMeta || {};
+ const subName = (doc.name || '').replace(/^XDS/, '');
+ if (subName) {
+ const isHookEntry =
+ subName.startsWith('use') ||
+ Array.isArray(doc.params) ||
+ Array.isArray(doc.returns);
+ pendingSubComponents.push({
+ name: subName,
+ displayName: requireDisplayName(
+ doc.displayName,
+ `${pkg.name}: subcomponent ${subName} (parent ${doc.subComponentOf})`,
+ ),
+ moduleName: subName.startsWith('use') ? subName : `XDS${subName}`,
+ directory: entry.name,
+ importPath: resolveImportPathForPkg(pkg.dir, entry.name),
+ group: parentMeta.group ?? group,
+ category: parentMeta.category ?? category,
+ isHiddenFromOverview:
+ doc.isHiddenFromOverview ?? parentMeta.isHiddenFromOverview ?? false,
+ description: doc.description || parentMeta.topDescription || '',
+ keywords: parentMeta.keywords ?? keywords,
+ hidden: parentMeta.hidden ?? hidden,
+ parentDoc: doc.subComponentOf,
+ props: isHookEntry
+ ? []
+ : Array.isArray(doc.props)
+ ? sanitizeForJson(doc.props)
+ : [],
+ usage: doc.usage
+ ? sanitizeForJson(doc.usage)
+ : isHookEntry && doc.description
+ ? {description: doc.description}
+ : parentMeta.usage ?? null,
+ theming: isHookEntry
+ ? null
+ : doc.theming
+ ? sanitizeForJson(doc.theming)
+ : parentMeta.theming ?? null,
+ params: isHookEntry
+ ? Array.isArray(doc.params)
+ ? sanitizeForJson(doc.params)
+ : Array.isArray(doc.props)
+ ? sanitizeForJson(doc.props)
+ : []
+ : null,
+ returns: isHookEntry
+ ? Array.isArray(doc.returns)
+ ? sanitizeForJson(doc.returns)
+ : []
+ : null,
+ relatedComponents: isHookEntry
+ ? doc.relatedComponents || [doc.subComponentOf]
+ : null,
+ relatedHooks: isHookEntry ? doc.relatedHooks || null : null,
+ playground: isHookEntry ? null : parentMeta.playground ?? null,
+ });
+ }
+ } else if (doc.components && doc.components.length > 0) {
+ // A family parent that also documents its own component surface (it has
+ // top-level props) is emitted as its own entry. Abstract families with
+ // no top-level props (e.g. Chat) contribute only their sub-components.
+ if (Array.isArray(doc.props) && doc.props.length > 0) {
+ const name = doc.name || docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');
+ standaloneNames.add(name);
+ components.push({
+ name,
+ displayName: requireDisplayName(
+ doc.displayName,
+ `${pkg.name}: component ${name}`,
+ ),
+ moduleName: name.startsWith('use') ? name : `XDS${name}`,
+ directory: entry.name,
+ importPath: resolveImportPathForPkg(pkg.dir, entry.name),
+ group,
+ category,
+ isHiddenFromOverview,
+ description: doc.description || topDescription,
+ keywords,
+ hidden,
+ parentDoc: name,
+ props: sanitizeForJson(doc.props),
+ usage,
+ theming,
+ params: null,
+ returns: null,
+ relatedComponents: null,
+ relatedHooks: null,
+ playground,
+ });
+ }
for (const sub of doc.components) {
const rawSubName = sub.name || '';
const subName = rawSubName.replace(/^XDS/, '');
if (!subName) continue;
- const isHookEntry = rawSubName.startsWith('use') || subName.startsWith('use') || Array.isArray(sub.params);
+ const isHookEntry =
+ rawSubName.startsWith('use') ||
+ subName.startsWith('use') ||
+ Array.isArray(sub.params);
+ // Name-only entries are cross-link references to sub-components that
+ // have been extracted into their own sibling .doc.mjs files. Their
+ // content is emitted from those files (subComponentOf branch); skip
+ // here to avoid double emission.
+ const isNameOnlyRef =
+ Object.keys(sub).length === 1 && sub.name != null;
+ if (isNameOnlyRef) continue;
// Sub-entries whose name differs from the doc name are
// sub-components — hide them from the overview page.
const isSubEntry = subName !== doc.name;
diff --git a/packages/cli/src/commands/component-resolution.test.mjs b/packages/cli/src/commands/component-resolution.test.mjs
index cf60dbe5a6..3e68b97f5c 100644
--- a/packages/cli/src/commands/component-resolution.test.mjs
+++ b/packages/cli/src/commands/component-resolution.test.mjs
@@ -49,11 +49,14 @@ describe('component() sub-component scoping', () => {
expect(result.data.name).not.toBe('TabList');
});
- // Non-regression: asking for the parent still returns the full doc
+ // Non-regression: asking for the parent still returns the full doc, with its
+ // family listed as name-only cross-links (sub-component content now lives in
+ // each sub-component's own .doc.mjs file).
it('component("CodeBlock") still returns full CodeBlock doc', async () => {
const result = await component('CodeBlock', CWD);
expect(result.data.name).toBe('CodeBlock');
- expect(result.data.components.length).toBeGreaterThan(1);
+ expect(result.data.components.length).toBeGreaterThanOrEqual(1);
+ expect(result.data.components.every(c => typeof c.name === 'string')).toBe(true);
});
it('component("Stack") still returns full Stack doc', async () => {
diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
index a41b4d19c0..f723faa44f 100644
--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
@@ -38,38 +38,76 @@ export const docs = {
actionLabel: 'Delete',
},
},
- components: [
+ description: 'A modal dialog that asks the user to confirm a destructive action.',
+ props: [
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ required: true,
+ description: 'Whether the dialog is open.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => unknown',
+ required: true,
+ description: 'Visibility change callback.',
+ },
+ {
+ name: 'title',
+ type: 'string',
+ required: true,
+ description: 'Dialog title. Linked via aria-labelledby.',
+ },
{
- name: 'XDSAlertDialog',
- isHiddenFromOverview: true,
- displayName: 'Alert Dialog',
- description: 'A modal dialog that asks the user to confirm a destructive action.',
- props: [
- {name: 'isOpen', type: 'boolean', required: true, description: 'Whether the dialog is open.'},
- {name: 'onOpenChange', type: '(isOpen: boolean) => unknown', required: true, description: 'Visibility change callback.'},
- {name: 'title', type: 'string', required: true, description: 'Dialog title. Linked via aria-labelledby.'},
- {name: 'description', type: 'string', required: true, description: 'Consequence description. Linked via aria-describedby.'},
- {name: 'actionLabel', type: 'string', required: true, description: 'Action button label.'},
- {name: 'onAction', type: '() => unknown', required: true, description: 'Called when action button is clicked. Does NOT auto-close.'},
- {name: 'cancelLabel', type: 'string', default: "'Cancel'", description: 'Cancel button label.'},
- {name: 'actionVariant', type: 'XDSButtonVariant', default: "'destructive'", description: 'Action button variant.'},
- {name: 'isActionLoading', type: 'boolean', description: 'Shows loading spinner on the action button.'},
- {name: 'width', type: 'number | string', default: '400', description: 'Dialog width.'},
- {name: 'isInline', type: 'boolean', default: 'false', description: 'Renders alert dialog content inline without modal behavior. For documentation previews and showcases only.'},
- ],
+ name: 'description',
+ type: 'string',
+ required: true,
+ description: 'Consequence description. Linked via aria-describedby.',
},
{
- 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.',
- 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.'},
- {name: 'element', type: 'ReactNode', description: 'The dialog element; render this in your JSX tree.'},
- ],
+ name: 'actionLabel',
+ type: 'string',
+ required: true,
+ description: 'Action button label.',
},
+ {
+ name: 'onAction',
+ type: '() => unknown',
+ required: true,
+ description: 'Called when action button is clicked. Does NOT auto-close.',
+ },
+ {
+ name: 'cancelLabel',
+ type: 'string',
+ default: "'Cancel'",
+ description: 'Cancel button label.',
+ },
+ {
+ name: 'actionVariant',
+ type: 'XDSButtonVariant',
+ default: "'destructive'",
+ description: 'Action button variant.',
+ },
+ {
+ name: 'isActionLoading',
+ type: 'boolean',
+ description: 'Shows loading spinner on the action button.',
+ },
+ {
+ name: 'width',
+ type: 'number | string',
+ default: '400',
+ description: 'Dialog width.',
+ },
+ {
+ name: 'isInline',
+ type: 'boolean',
+ default: 'false',
+ description: 'Renders alert dialog content inline without modal behavior. For documentation previews and showcases only.',
+ },
+ ],
+ components: [
+ {name: 'useXDSImperativeAlertDialog'},
],
};
@@ -85,33 +123,4 @@ export const docsDense = {
{guidance: false, description: 'Use AlertDialog for non-destructive actions; use standard Dialog instead.'},
],
},
- components: [
- {
- name: 'XDSAlertDialog',
- description: 'Modal dialog confirming destructive action.',
- propDescriptions: {
- isOpen: 'dialog open? **(required)**',
- onOpenChange: 'visibility change callback **(required)**',
- title: 'dialog title; linked via aria-labelledby **(required)**',
- description: 'consequence description; linked via aria-describedby **(required)**',
- actionLabel: 'action button label **(required)**',
- onAction: 'fires on action click; does NOT auto-close **(required)**',
- cancelLabel: 'cancel button label',
- actionVariant: 'action button variant',
- isActionLoading: 'shows loading spinner on action button',
- width: 'dialog width',
- isInline: 'renders content inline w/o modal behavior; docs previews/showcases only',
- },
- },
- {
- name: 'useXDSImperativeAlertDialog',
- description: 'Hook to show alert dialog w/o managing open state. Call alert.show(options) to open, alert.hide() to close; render alert.element in JSX tree.',
- propDescriptions: {
- show: 'show dialog w/ options; same as XDSAlertDialog props minus isOpen/onOpenChange',
- hide: 'hide dialog',
- isOpen: 'dialog currently open?',
- element: 'dialog element; render in JSX tree',
- },
- },
- ],
};
diff --git a/packages/core/src/AlertDialog/useXDSImperativeAlertDialog.doc.mjs b/packages/core/src/AlertDialog/useXDSImperativeAlertDialog.doc.mjs
new file mode 100644
index 0000000000..1c3a0baecd
--- /dev/null
+++ b/packages/core/src/AlertDialog/useXDSImperativeAlertDialog.doc.mjs
@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSImperativeAlertDialog',
+ subComponentOf: 'AlertDialog',
+ 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: [
+ {
+ 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.',
+ },
+ {
+ name: 'element',
+ type: 'ReactNode',
+ description: 'The dialog element — render this in your JSX tree.',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSImperativeAlertDialog',
+ description: 'Hook to show alert dialog w/o managing open state. Call alert.show(options) to open, alert.hide() to close; render alert.element in JSX tree.',
+ propDescriptions: {
+ show: 'show dialog w/ options; same as XDSAlertDialog props minus isOpen/onOpenChange',
+ hide: 'hide dialog',
+ isOpen: 'dialog currently open?',
+ element: 'dialog element — render in JSX tree',
+ },
+};
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index e00e96486a..bbb262c58d 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -31,80 +31,55 @@ export const docs = {
{className: 'xds-avatar-status-dot', visualProps: ['variant']},
],
},
- components: [
+ description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
+ props: [
{
- name: 'XDSAvatar',
- displayName: 'Avatar',
- description:
- 'Displays a user avatar with image, initials fallback, and optional status indicator.',
- props: [
- {
- name: 'src',
- type: 'string',
- description: 'Primary image source URL.',
- },
- {
- name: 'fallbackSrc',
- type: 'string',
- description: 'Fallback image when primary fails.',
- },
- {
- name: 'name',
- type: 'string',
- description: 'User name for initials and alt text.',
- },
- {
- name: 'alt',
- type: 'string',
- description: 'Alt text (falls back to name).',
- },
- {
- name: 'size',
- type: "'tiny' | 'xsmall' | 'small' | 'medium' | 'large' | number",
- description: "Avatar size. Named sizes: 'tiny' (20px), 'xsmall' (24px), 'small' (36px), 'medium' (48px), 'large' (72px). Also accepts specific pixel values (16, 20, 24, 32, 36, 40, 48, 60, 64, 72, 80, 96, 120).",
- default: "'small'",
- },
- {
- name: 'status',
- type: 'ReactNode',
- description: 'Corner content for status indicators.',
- slotElements: [{__element: 'XDSStatusDot', props: {variant: 'online'}}],
- },
- ], },
+ name: 'src',
+ type: 'string',
+ description: 'Primary image source URL.',
+ },
{
- name: 'XDSAvatarStatusDot',
- isHiddenFromOverview: true,
- displayName: 'Avatar Status Dot',
- description:
- 'Size-aware status indicator dot that reads avatar size from context and scales proportionally.',
- props: [
- {
- name: 'variant',
- type: "'success' | 'neutral' | 'error'",
- description: 'Semantic color variant of the dot.',
- default: "'success'",
- },
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label for screen readers.',
- },
+ name: 'fallbackSrc',
+ type: 'string',
+ description: 'Fallback image when primary fails.',
+ },
+ {
+ name: 'name',
+ type: 'string',
+ description: 'User name for initials and alt text.',
+ },
+ {
+ name: 'alt',
+ type: 'string',
+ description: 'Alt text (falls back to name).',
+ },
+ {
+ name: 'size',
+ type: 'XDSAvatarSize',
+ description: 'Avatar size (named or numeric pixel value).',
+ default: "'small'",
+ },
+ {
+ name: 'status',
+ type: 'ReactNode',
+ description: 'Corner content for status indicators.',
+ slotElements: [
{
- name: 'icon',
- type: 'ReactNode',
- description: 'Icon centered inside the dot (hidden at tiny sizes).',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
+ __element: 'XDSStatusDot',
+ props: {
+ variant: 'online',
+ },
},
],
},
],
+ components: [
+ {name: 'XDSAvatarStatusDot'},
+ ],
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Avatar',
- displayName: 'Avatar',
- group: 'Avatar',
usage: {
description:
'Avatar displays a user or entity\'s profile picture with automatic fallback to initials or a default icon. Use it alongside user information to visually represent people, teams, or entities throughout the interface.',
@@ -115,48 +90,6 @@ export const docsZh = {
{guidance: false, description: 'Override the circular shape. Avatars are always round to maintain visual consistency across the system.'},
],
},
- theming: {
- targets: [
- {
- className: 'xds-avatar',
- visualProps: [
- 'size',
- ],
- },
- {
- className: 'xds-avatar-status-dot',
- visualProps: [
- 'variant',
- ],
- },
- ],
- },
- components: [
- {
- name: 'XDSAvatar',
- displayName: 'Avatar',
- description: '显示用户头像,支持图片、首字母回退和可选的状态指示器。',
- props: [
- {name: 'src', type: 'string', description: '主图片源 URL。'},
- {name: 'fallbackSrc', type: 'string', description: '主图片加载失败时的备用图片。'},
- {name: 'name', type: 'string', description: '用户姓名,用于生成首字母和替代文本。'},
- {name: 'alt', type: 'string', description: '替代文本(未提供时回退到 name)。'},
- {name: 'size', type: "'tiny' | 'xsmall' | 'small' | 'medium' | 'large' | number", description: "头像尺寸。命名值:'tiny' (20px)、'xsmall' (24px)、'small' (36px)、'medium' (48px)、'large' (72px)。也接受具体像素值。", default: "'small'"},
- {name: 'status', type: 'ReactNode', description: '角落内容,用于状态指示器。'},
- ],
- },
- {
- name: 'XDSAvatarStatusDot',
- isHiddenFromOverview: true,
- displayName: 'Avatar Status Dot',
- description: '尺寸感知的状态指示点,从上下文中读取头像尺寸并等比缩放。',
- props: [
- {name: 'variant', type: "'success' | 'neutral' | 'error'", description: '状态点的语义颜色变体。', default: "'success'"},
- {name: 'label', type: 'string', description: '屏幕阅读器的无障碍标签。'},
- {name: 'icon', type: 'ReactNode', description: '居中显示在状态点内的图标(tiny 尺寸时隐藏)。'},
- ],
- },
- ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -173,31 +106,4 @@ export const docsDense = {
{guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
],
},
- components: [
- {
- name: 'XDSAvatar',
- displayName: 'Avatar',
- description: 'user avatar w/ image, initials fallback, optional status indicator',
- propDescriptions: {
- src: 'primary image URL',
- fallbackSrc: 'fallback image on primary fail',
- name: 'user name for initials+alt text',
- displayName: 'user name for initials+alt text',
- alt: 'alt text (falls back to name)',
- size: 'avatar size (named or numeric px)',
- status: 'corner content for status indicators',
- },
- },
- {
- name: 'XDSAvatarStatusDot',
- isHiddenFromOverview: true,
- displayName: 'Avatar Status Dot',
- description: 'size-aware status dot, reads avatar size from context + scales proportionally',
- propDescriptions: {
- variant: 'semantic color variant',
- label: 'accessible label for screen readers',
- icon: 'icon centered in dot (hidden at tiny sizes)',
- },
- },
- ],
};
diff --git a/packages/core/src/Avatar/AvatarStatusDot.doc.mjs b/packages/core/src/Avatar/AvatarStatusDot.doc.mjs
new file mode 100644
index 0000000000..b7809e5013
--- /dev/null
+++ b/packages/core/src/Avatar/AvatarStatusDot.doc.mjs
@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'AvatarStatusDot',
+ subComponentOf: 'Avatar',
+ displayName: 'Avatar Status Dot',
+ isHiddenFromOverview: true,
+ description: 'Size-aware status indicator dot that reads avatar size from context and scales proportionally.',
+ props: [
+ {
+ name: 'variant',
+ type: "'success' | 'neutral' | 'error'",
+ description: 'Semantic color variant of the dot.',
+ default: "'success'",
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for screen readers.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon centered inside the dot (hidden at tiny sizes).',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'AvatarStatusDot',
+ isHiddenFromOverview: true,
+ displayName: 'Avatar Status Dot',
+ description: '尺寸感知的状态指示点,从上下文中读取头像尺寸并等比缩放。',
+ props: [
+ {
+ name: 'variant',
+ type: "'success' | 'neutral' | 'error'",
+ description: '状态点的语义颜色变体。',
+ default: "'success'",
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '屏幕阅读器的无障碍标签。',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: '居中显示在状态点内的图标(tiny 尺寸时隐藏)。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'AvatarStatusDot',
+ isHiddenFromOverview: true,
+ displayName: 'Avatar Status Dot',
+ description: 'size-aware status dot, reads avatar size from context + scales proportionally',
+ propDescriptions: {
+ variant: 'semantic color variant',
+ label: 'accessible label for screen readers',
+ icon: 'icon centered in dot (hidden at tiny sizes)',
+ },
+};
diff --git a/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs b/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
index 4d088e100c..468a8898a3 100644
--- a/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
+++ b/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
@@ -26,29 +26,47 @@ export const docs = {
{className: 'xds-avatar-group', visualProps: ['size']},
],
},
- components: [
+ description: 'Stacked avatar display with overlapping layout and optional overflow indicator. Children are XDSAvatar elements.',
+ props: [
{
- name: 'XDSAvatarGroup',
- displayName: 'Avatar Group',
- description: 'Stacked avatar display with overlapping layout and optional overflow indicator. Children are XDSAvatar elements.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'XDSAvatar children, optionally followed by one XDSAvatarGroupOverflow. Consumers handle slicing to the desired visible count.', required: true, slotElements: [{__element: 'XDSAvatar', props: {name: 'User'}}]},
- {name: 'size', type: 'XDSAvatarSize', description: 'Size applied to all avatars via context.', default: "'small'"},
- {name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
- {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization.'},
- {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSAvatar children, optionally followed by one XDSAvatarGroupOverflow. Consumers handle slicing to the desired visible count.',
+ required: true,
+ slotElements: [
+ {
+ __element: 'XDSAvatar',
+ props: {
+ name: 'User',
+ },
+ },
],
},
{
- name: 'XDSAvatarGroupOverflow',
- isHiddenFromOverview: true,
- displayName: 'Avatar Group Overflow',
- description: 'Slot for custom overflow content inside XDSAvatarGroup. Replaces the default "+N" indicator when present.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'Custom overflow content (button, popover trigger, etc.).', required: true},
- ],
+ name: 'size',
+ type: 'XDSAvatarSize',
+ description: 'Size applied to all avatars via context.',
+ default: "'small'",
+ },
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLDivElement>',
+ description: 'Ref forwarded to the root element.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization.',
+ },
+ {
+ name: 'data-testid',
+ type: 'string',
+ description: 'Test selector for automated testing frameworks.',
},
],
+ components: [
+ {name: 'XDSAvatarGroupOverflow'},
+ ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -63,30 +81,6 @@ export const docsZh = {
{guidance: false, description: '不要嵌套 AvatarGroup,使用单个组包含所有头像。'},
],
},
- components: [
- {
- name: 'XDSAvatarGroup',
- displayName: 'Avatar Group',
- description: '重叠布局的堆叠头像显示,带可选溢出指示器。子元素为 XDSAvatar。',
- propDescriptions: {
- children: 'XDSAvatar 子元素,可选地后跟一个 XDSAvatarGroupOverflow。',
- max: '溢出指示器出现前显示的最大头像数。',
- size: '应用于所有头像的大小。',
- ref: '转发到根元素的引用。',
- xstyle: 'StyleX 样式,用于布局自定义。',
- 'data-testid': '自动化测试的选择器。',
- },
- },
- {
- name: 'XDSAvatarGroupOverflow',
- isHiddenFromOverview: true,
- displayName: 'Avatar Group Overflow',
- description: 'XDSAvatarGroup 内的自定义溢出内容插槽。存在时替换默认的 "+N" 指示器。',
- propDescriptions: {
- children: '自定义溢出内容(按钮、弹出触发器等)。',
- },
- },
- ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -102,28 +96,4 @@ export const docsDense = {
{guidance: false, description: "Don't nest AvatarGroups."},
],
},
- components: [
- {
- name: 'XDSAvatarGroup',
- displayName: 'Avatar Group',
- description: 'overlapping avatar row w/ max truncation',
- propDescriptions: {
- children: 'XDSAvatar children + optional XDSAvatarGroupOverflow',
- max: 'max avatars before overflow',
- size: 'size for all avatars',
- ref: 'ref to root element',
- xstyle: 'StyleX layout styles',
- 'data-testid': 'test selector',
- },
- },
- {
- name: 'XDSAvatarGroupOverflow',
- isHiddenFromOverview: true,
- displayName: 'Avatar Group Overflow',
- description: 'custom overflow slot, replaces default +N',
- propDescriptions: {
- children: 'custom overflow content',
- },
- },
- ],
};
diff --git a/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs b/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs
new file mode 100644
index 0000000000..f66facae43
--- /dev/null
+++ b/packages/core/src/AvatarGroup/AvatarGroupOverflow.doc.mjs
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'AvatarGroupOverflow',
+ subComponentOf: 'AvatarGroup',
+ displayName: 'Avatar Group Overflow',
+ isHiddenFromOverview: true,
+ description: 'Slot for custom overflow content inside XDSAvatarGroup. Replaces the default "+N" indicator when present.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Custom overflow content (button, popover trigger, etc.).',
+ required: true,
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'AvatarGroupOverflow',
+ isHiddenFromOverview: true,
+ displayName: 'Avatar Group Overflow',
+ description: 'XDSAvatarGroup 内的自定义溢出内容插槽。存在时替换默认的 "+N" 指示器。',
+ propDescriptions: {
+ children: '自定义溢出内容(按钮、弹出触发器等)。',
+ },
+};
+
+export const docsDense = {
+ name: 'AvatarGroupOverflow',
+ isHiddenFromOverview: true,
+ displayName: 'Avatar Group Overflow',
+ description: 'custom overflow slot, replaces default +N',
+ propDescriptions: {
+ children: 'custom overflow content',
+ },
+};
diff --git a/packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs b/packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs
new file mode 100644
index 0000000000..d6c53241eb
--- /dev/null
+++ b/packages/core/src/Breadcrumbs/BreadcrumbItem.doc.mjs
@@ -0,0 +1,110 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'BreadcrumbItem',
+ subComponentOf: 'Breadcrumbs',
+ displayName: 'Breadcrumb Item',
+ isHiddenFromOverview: true,
+ description: 'Individual breadcrumb item that renders as a link when href is provided, or as plain text for the current page.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Label content for the breadcrumb item.',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'URL the breadcrumb links to; omit for non-navigable items.',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: 'Click handler for the breadcrumb item.',
+ },
+ {
+ name: 'isCurrent',
+ type: 'boolean',
+ description: 'Marks this item as the current page, applying aria-current="page".',
+ default: 'false',
+ },
+ {
+ name: 'startIcon',
+ type: 'ReactNode',
+ description: 'Icon rendered before the item label.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: 'Custom link component to render instead of <a>. Overrides the provider-level default from XDSLinkProvider. Only applies to non-current items.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'BreadcrumbItem',
+ isHiddenFromOverview: true,
+ displayName: 'Breadcrumb Item',
+ description: '单个面包屑项,提供 href 时渲染为链接,当前页面渲染为纯文本。',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '面包屑项的标签内容。',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: '面包屑链接的 URL;不可导航的项目请省略。',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: '面包屑项的点击处理函数。',
+ },
+ {
+ name: 'isCurrent',
+ type: 'boolean',
+ description: '将此项标记为当前页面,应用 aria-current="page"。',
+ default: 'false',
+ },
+ {
+ name: 'startIcon',
+ type: 'ReactNode',
+ description: '在项目标签前渲染的图标。',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: '自定义链接组件,代替 <a> 渲染。覆盖 XDSLinkProvider 设置的默认值。仅适用于非当前项。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'BreadcrumbItem',
+ isHiddenFromOverview: true,
+ displayName: 'Breadcrumb Item',
+ description: 'individual breadcrumb; link w/ href, plain text for current page',
+ propDescriptions: {
+ children: 'label content',
+ href: 'link URL; omit for non-navigable items',
+ onClick: 'click handler',
+ isCurrent: 'marks current page w/ aria-current="page"',
+ startIcon: 'icon before label',
+ as: 'custom link component; overrides XDSLinkProvider default',
+ },
+};
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index 390ebe61a0..2128ede71c 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -33,101 +33,63 @@ export const docs = {
{className: 'xds-breadcrumbs', visualProps: ['variant']},
],
},
- components: [
+ description: 'Navigation container that renders a <nav> with an ordered list of breadcrumb items.',
+ props: [
{
- name: 'XDSBreadcrumbs',
- displayName: 'Breadcrumbs',
- description:
- 'Navigation container that renders a <nav> with an ordered list of breadcrumb items.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'XDSBreadcrumbItem elements to render inside the breadcrumb trail.',
- slotElements: [{__element: 'XDSBreadcrumbItem', props: {href: '#'}, children: 'Page'}],
- required: true,
- },
- {
- name: 'separator',
- type: 'ReactNode',
- description: 'Separator rendered between breadcrumb items.',
- default: "'/'",
- slotElements: [{__element: 'XDSIcon', props: {icon: 'chevronRight', size: 'sm'}}],
- },
- {
- name: 'variant',
- type: "'default' | 'supporting'",
- description:
- 'Visual variant; supporting is smaller with secondary text styling.',
- default: "'default'",
- },
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSBreadcrumbItem elements to render inside the breadcrumb trail.',
+ slotElements: [
{
- name: 'label',
- type: 'string',
- description: 'Accessible label for the nav landmark (aria-label).',
- default: "'Breadcrumb'",
+ __element: 'XDSBreadcrumbItem',
+ props: {
+ href: '#',
+ },
+ children: 'Page',
},
- {
- 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={{}}.',
- },
- ], },
+ ],
+ required: true,
+ },
{
- name: 'XDSBreadcrumbItem',
- isHiddenFromOverview: true,
- displayName: 'Breadcrumb Item',
- description:
- 'Individual breadcrumb item that renders as a link when href is provided, or as plain text for the current page.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Label content for the breadcrumb item.',
- required: true,
- },
- {
- name: 'href',
- type: 'string',
- description:
- 'URL the breadcrumb links to; omit for non-navigable items.',
- },
- {
- name: 'onClick',
- type: '(e: MouseEvent) => void',
- description: 'Click handler for the breadcrumb item.',
- },
- {
- name: 'isCurrent',
- type: 'boolean',
- description:
- 'Marks this item as the current page, applying aria-current="page".',
- default: 'false',
- },
- {
- name: 'startIcon',
- type: 'ReactNode',
- description: 'Icon rendered before the item label.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
+ name: 'separator',
+ type: 'ReactNode',
+ description: 'Separator rendered between breadcrumb items.',
+ default: "'/'",
+ slotElements: [
{
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- 'Custom link component to render instead of <a>. Overrides the provider-level default from XDSLinkProvider. Only applies to non-current items.',
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronRight',
+ size: 'sm',
+ },
},
],
},
+ {
+ name: 'variant',
+ type: "'default' | 'supporting'",
+ description: 'Visual variant — supporting is smaller with secondary text styling.',
+ default: "'default'",
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the nav landmark (aria-label).',
+ default: "'Breadcrumb'",
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+ components: [
+ {name: 'XDSBreadcrumbItem'},
],
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Breadcrumbs',
- displayName: 'Breadcrumbs',
- group: 'Breadcrumbs',
usage: {
description:
'Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.',
@@ -141,50 +103,6 @@ export const docsZh = {
{guidance: false, description: 'Let the trail grow beyond 5 levels. If you need more, consider simplifying the page hierarchy instead.'},
],
},
- theming: {
- targets: [
- {className: 'xds-breadcrumb-item'},
- {
- className: 'xds-breadcrumbs',
- visualProps: [
- 'variant',
- ],
- },
- ],
- },
- components: [
- {
- name: 'XDSBreadcrumbs',
- displayName: 'Breadcrumbs',
- description: '导航容器,渲染包含有序面包屑项列表的 <nav> 元素。',
- props: [
- {name: 'children', type: 'ReactNode', description: '在面包屑路径内渲染的 XDSBreadcrumbItem 元素。', required: true},
- {name: 'separator', type: 'ReactNode', description: '面包屑项之间渲染的分隔符。', default: "'/'"},
- {name: 'variant', type: "'default' | 'supporting'", description: '视觉变体:supporting 更小,使用次要文本样式。', default: "'default'"},
- {name: 'label', type: 'string', description: 'nav 地标的无障碍标签(aria-label)。', default: "'Breadcrumb'"},
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSBreadcrumbItem',
- isHiddenFromOverview: true,
- displayName: 'Breadcrumb Item',
- description: '单个面包屑项,提供 href 时渲染为链接,当前页面渲染为纯文本。',
- props: [
- {name: 'children', type: 'ReactNode', description: '面包屑项的标签内容。', required: true},
- {name: 'href', type: 'string', description: '面包屑链接的 URL;不可导航的项目请省略。'},
- {name: 'onClick', type: '(e: MouseEvent) => void', description: '面包屑项的点击处理函数。'},
- {name: 'isCurrent', type: 'boolean', description: '将此项标记为当前页面,应用 aria-current="page"。', default: 'false'},
- {name: 'startIcon', type: 'ReactNode', description: '在项目标签前渲染的图标。'},
- {name: 'as', type: 'XDSLinkComponentType', description: '自定义链接组件,代替 <a> 渲染。覆盖 XDSLinkProvider 设置的默认值。仅适用于非当前项。'},
- ],
- },
- ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -203,32 +121,4 @@ export const docsDense = {
{guidance: false, description: 'Let the trail exceed 5 levels; simplify the hierarchy instead.'},
],
},
- components: [
- {
- name: 'XDSBreadcrumbs',
- displayName: 'Breadcrumbs',
- description: 'nav container rendering <nav> w/ ordered breadcrumb list',
- propDescriptions: {
- children: 'XDSBreadcrumbItem elements in breadcrumb trail',
- separator: 'separator between items',
- variant: 'supporting=smaller w/ secondary text styling',
- label: 'nav landmark aria-label',
- xstyle: 'StyleX layout customization via stylex.create()',
- },
- },
- {
- name: 'XDSBreadcrumbItem',
- isHiddenFromOverview: true,
- displayName: 'Breadcrumb Item',
- description: 'individual breadcrumb; link w/ href, plain text for current page',
- propDescriptions: {
- children: 'label content',
- href: 'link URL; omit for non-navigable items',
- onClick: 'click handler',
- isCurrent: 'marks current page w/ aria-current="page"',
- startIcon: 'icon before label',
- as: 'custom link component; overrides XDSLinkProvider default',
- },
- },
- ],
};
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 96586cf89e..aa94c23f2f 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -7,6 +7,9 @@ export const docs = {
displayName: 'Chat',
group: 'Chat',
category: 'Chat',
+ // XDSChatPastedTextToken is an internal helper (not exported from index.ts).
+ // Hide it from the component listing so it doesn't surface as an undocumented entry.
+ hiddenComponents: ['ChatPastedTextToken'],
keywords: ['chat', 'message', 'bubble', 'conversation', 'ai', 'assistant', 'thread', 'system-message', 'composer', 'mention', 'trigger', 'typeahead', 'token', 'imperative', 'tokenized-text'],
theming: {
targets: [
@@ -38,203 +41,20 @@ export const docs = {
],
},
components: [
- {
- name: 'XDSChatMessageList',
- isHiddenFromOverview: true,
- displayName: 'Chat Message List',
- description: 'Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn\'t full.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'Message elements, typically XDSChatMessage or XDSChatSystemMessage.', required: true},
- {name: 'emptyState', type: 'ReactNode', description: 'Content shown when the list has no messages.',
- slotElements: [{__element: 'XDSEmptyState', props: {title: 'No items', description: 'Nothing to show.'}}],
- },
- {name: 'scrollToTopAction', type: '() => Promise<void>', description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition; shows a spinner at the top while pending.'},
- {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density; flows to child messages via context.', default: "'balanced'"},
- {name: 'gap', type: 'SpacingStep', description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.'},
- ],
- },
- {
- name: 'XDSChatMessage',
- displayName: 'Chat Message',
- description: 'Sender context wrapper that handles avatar, name, metadata, and alignment based on sender role.',
- props: [
- {name: 'sender', type: "'user' | 'assistant' | 'system'", description: 'Who sent this message; controls alignment and layout.', required: true},
- {name: 'children', type: 'ReactNode', description: 'Free-form content: bubbles, asset lists, tool calls, images.', required: true},
- {name: 'avatar', type: 'ReactNode', description: 'Avatar element rendered beside the message. Typically XDSAvatar.',
- slotElements: [{__element: 'XDSAvatar', props: {name: 'User', size: 'sm'}}],
- },
- {name: 'name', type: 'ReactNode', description: 'Sender name rendered above the message body. Use when the first child is raw content (not a bubble). If the first child is a bubble, put the name on the bubble\'s `name` prop instead.'},
- {name: 'metadata', type: 'ReactNode', description: 'Metadata rendered below the message body. Use when the last child is raw content (not a bubble). If the last child is a bubble, put metadata on the bubble\'s `metadata` prop instead.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Metadata'}],
- },
- {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density. Inherited from list context if not set.'},
- ],
- },
- {
- name: 'XDSChatMessageBubble',
- isHiddenFromOverview: true,
- displayName: 'Chat Message Bubble',
- description: 'Styled content container, the chat "bubble." Reads sender from parent XDSChatMessage context to auto-style the background. Use filled for standard messages and ghost when content needs alignment without a visible boundary. Supports name/metadata slots aligned with bubble padding, and multi-bubble grouping via the group prop for consecutive messages from the same sender.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'Bubble content: text, XDSMarkdown, or any ReactNode.', required: true},
- {name: 'variant', type: "'filled' | 'ghost'", description: "Visual variant. 'filled' renders sender-colored background (default). 'ghost' renders transparent background but keeps padding for alignment.", default: "'filled'"},
- {name: 'name', type: 'ReactNode', description: "Sender name rendered above the bubble, aligned with bubble text padding. Use on the first bubble in a message. If the first content is raw (no bubble), use XDSChatMessage's `name` prop instead."},
- {name: 'metadata', type: 'ReactNode', description: "Metadata content rendered below the bubble, aligned with bubble text padding. Use on the last bubble in a message. If the last content is raw (no bubble), use XDSChatMessage's `metadata` prop instead.",
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Metadata'}],
- },
- {name: 'group', type: "'first' | 'middle' | 'last'", description: 'Position within a multi-bubble group. Controls corner radius reduction on the sender side. Leave unset for standalone bubbles (full radius).'},
- ],
- },
- {
- name: 'XDSChatMessageMetadata',
- displayName: 'Chat Message Metadata',
- description: 'Composable metadata row for chat messages. Renders timestamp, footer content, and delivery status in a single row. Direction reverses for user sender. Renders nothing if all props are empty.',
- props: [
- {name: 'timestamp', type: 'ReactNode', description: 'Timestamp content: a string or XDSTimestamp component.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Just now'}],
- },
- {name: 'footer', type: 'ReactNode', description: 'Footer content: model info, reaction buttons, copy button.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Footer content'}],
- },
- {name: 'status', type: "'sending' | 'sent' | 'delivered' | 'read' | 'error'", description: 'Message delivery status. Shows icon + label.'},
- ],
- },
- {
- name: 'XDSChatSystemMessage',
- displayName: 'Chat System Message',
- description: 'Centered system message for non-sender content like date separators, membership changes, and status notices. It is not a chat bubble; it has no avatar, no alignment, and no sender context. Use the divider variant for temporal breaks and default for inline status updates.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'System message content: a short, factual string like a date, a join/leave notice, or a status change.', required: true},
- {name: 'variant', type: "'default' | 'divider'", description: "Visual variant. 'default' renders centered text. 'divider' adds horizontal lines on each side via XDSDivider. Use for date separators and section breaks.", default: "'default'"},
- {name: 'icon', type: 'ReactNode', description: 'Leading icon that reinforces the message type. Wrap in XDSIcon for consistent sizing. Use for membership changes, encryption notices, or AI activity.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- ],
- },
- {
- name: 'XDSChatComposer',
- displayName: 'Chat Composer',
- description: 'Layout shell for a chat composer. Arranges named slots (drawer, header, input, footer, send) with page-radius container, hover/focus shadows, and concentric inner radius for child elements.',
- props: [
- {name: 'onSubmit', type: '(value: string) => void', description: 'Called when the user submits a message.', required: true},
- {name: 'onStop', type: '() => void', description: 'Called when the user requests to stop generation.'},
- {name: 'isStopShown', type: 'boolean', description: 'Whether the stop button is shown instead of the send button.', default: 'false'},
- {name: 'value', type: 'string', description: 'Controlled input value.'},
- {name: 'onChange', type: '(value: string) => void', description: 'Change handler for controlled mode.'},
- {name: 'placeholder', type: 'string', description: 'Placeholder text shown when the input is empty.', default: "'Type a message\u2026'"},
- {name: 'isDisabled', type: 'boolean', description: 'Disables the composer.', default: 'false'},
- {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density.', default: "'balanced'"},
- {name: 'drawer', type: 'ReactNode', description: 'Slot: collapsible drawer above the input for attachments, context chips, etc. Use XDSChatComposerDrawer.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Drawer content'}],
- },
- {name: 'headerActions', type: 'ReactNode', description: 'Slot: left-aligned header actions (attach, mention buttons). Use icon-only size="sm" buttons.',
- slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
- },
- {name: 'headerContext', type: 'ReactNode', description: 'Slot: right-aligned contextual info in the header (context window usage, XDSProgressBar, supporting text).',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Context'}],
- },
- {name: 'input', type: 'ReactNode', description: 'Slot: custom input element. Replaces the default textarea. Use XDSChatComposerInput for trigger menus.',
- slotElements: [{__element: 'XDSTextInput', props: {label: 'Input', placeholder: 'Type here...'}}],
- },
- {name: 'footerActions', type: 'ReactNode', description: 'Slot: left-aligned footer actions (model selector, etc).',
- slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
- },
- {name: 'sendActions', type: 'ReactNode', description: 'Slot: actions to the left of the send button.',
- slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
- },
- {name: 'sendButton', type: 'ReactNode', description: 'Slot: custom send button. Replaces the default send/stop button.',
- slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
- },
- {name: 'status', type: "{ type: 'error' | 'warning'; message?: string }", description: 'Status message rendered below (or above) the composer.'},
- {name: 'statusPosition', type: "'top' | 'bottom'", description: 'Where to render the status.', default: "'bottom'"},
- ],
- },
- {
- name: 'XDSChatComposerInput',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Input',
- description: 'Rich text input for the chat composer. Supports trigger menus (type @ or / to open a typeahead), inline tokens rendered as badges, message history recall with ArrowUp/Down, paste/drop file handling, and a 16px touch-device font-size floor to prevent iOS input zoom. Pass it to XDSChatComposer\'s input slot when you need more than a plain textarea.',
- props: [
- {name: 'handleRef', type: 'React.Ref<XDSChatComposerInputHandle>', description: 'Imperative handle for programmatic control: insertToken, insertText, focus, and getValue.'},
- {name: 'value', type: 'string', description: 'Controlled input value. Pair with onChange for two-way binding.'},
- {name: 'onChange', type: '(value: string) => void', description: 'Called when the input value changes. The serialized string includes token placeholders.'},
- {name: 'placeholder', type: 'string', description: 'Placeholder text shown when the input is empty.', default: "'Type a message\u2026'"},
- {name: 'maxRows', type: 'number', description: 'Maximum visible rows before the input scrolls. Use a lower value in compact layouts.', default: '8'},
- {name: 'triggers', type: 'XDSChatComposerTrigger[]', description: 'Trigger definitions for typeahead menus. Each trigger specifies a character (@ or /), a search source, and an onSelect handler that returns the token to insert.'},
- {name: 'debounceMs', type: 'number', description: 'Debounce delay for async search sources to avoid excessive network requests.', default: '150'},
- {name: 'hasHistory', type: 'boolean', description: 'Enable ArrowUp/Down to recall previously submitted messages.', default: 'true'},
- {name: 'label', type: 'string', description: 'Accessible label announced by screen readers.', default: "'Message input'"},
- {name: 'isDisabled', type: 'boolean', description: 'Disables the input. Use during streaming or when a prerequisite is unmet.', default: 'false'},
- {name: 'onPaste', type: '(event, text) => void', description: 'Called when text is pasted. Use to intercept or transform pasted content.'},
- {name: 'onFiles', type: '(files: File[]) => void', description: 'Called when files are pasted or dropped onto the input. Use to handle attachments.'},
- {name: 'onSubmit', type: '(value: string) => void', description: 'Called when the user presses Enter without Shift. The serialized value includes token placeholders.'},
- ],
- },
- {
- name: 'XDSChatComposerDrawer',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Drawer',
- description: 'Collapsible drawer panel that sits above the chat input inside XDSChatComposer. Pass it to the composer\'s `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle: collapsed state shows a badge and label, expanded state shows all children.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'Content to render inside the drawer: tokens, chips, previews, or any React elements.', required: true},
- {name: 'count', type: 'number', description: 'Total item count shown in the collapsed badge. When provided, the drawer gains a collapse/expand toggle.'},
- {name: 'label', type: 'string', description: 'Label shown next to the count in collapsed state.', default: "'Items'"},
- {name: 'isCollapsed', type: 'boolean', description: 'Controlled collapsed state. Use with `onCollapsedChange` for external control.'},
- {name: 'defaultIsCollapsed', type: 'boolean', description: 'Initial collapsed state for uncontrolled usage.', default: 'false'},
- {name: 'onCollapsedChange', type: '(isCollapsed: boolean) => void', description: 'Callback fired when the user toggles the drawer.'},
- ],
- },
- {
- name: 'XDSChatSendButton',
- isHiddenFromOverview: true,
- displayName: 'Chat Send Button',
- description: 'Circular send/stop toggle button for the chat composer. Place it inside XDSChatComposer where it reads context automatically; no wiring needed. When streaming starts, the button switches from a primary send icon to a secondary stop icon. Override any context value via props for standalone or custom usage.',
- props: [
- {name: 'isStopShown', type: 'boolean', description: 'Whether the stop button is shown. Defaults to context value.'},
- {name: 'isDisabled', type: 'boolean', description: 'Whether the send button is disabled. Defaults to !canSend from context.'},
- {name: 'onSend', type: '() => void', description: 'Called when the user clicks send. Defaults to context onSubmit.'},
- {name: 'onStop', type: '() => void', description: 'Called when the user clicks stop during streaming. Defaults to context onStop.'},
- {name: 'sendIcon', type: 'ReactNode', description: 'Custom icon for the send state. Defaults to arrowUp from icon registry.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {name: 'stopIcon', type: 'ReactNode', description: 'Custom icon for the stop state. Defaults to stop from icon registry.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {name: 'size', type: "'sm' | 'md'", description: 'Button size.', default: "'md'"},
- {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={{}}.'},
- ],
- },
- {
- name: 'XDSChatToolCalls',
- displayName: 'Chat Tool Calls',
- description: 'Displays tool/function call invocations from an LLM response. Accepts a `calls` array matching the shape LLM APIs return. Single call renders inline; multiple calls get a collapsible summary with the latest call visible at the surface.',
- props: [
- {name: 'calls', type: 'XDSChatToolCallItem[]', description: 'Array of tool call data. Each item has name, status, target, duration, node, additions, deletions, stats, resultDetail.', required: true},
- {name: 'label', type: 'string', description: 'Custom summary label for groups. Auto-generated from count if omitted.'},
- {name: 'isExpanded', type: 'boolean', description: 'Controlled expanded state.'},
- {name: 'defaultIsExpanded', type: 'boolean', description: 'Default expanded state (uncontrolled).', default: 'false'},
- {name: 'onExpandedChange', type: '(isExpanded: boolean) => void', description: 'Callback when expanded state changes.'},
- ],
- },
- {
- name: 'XDSChatTokenizedText',
- isHiddenFromOverview: true,
- displayName: 'Chat Tokenized Text',
- description: 'Renders a text string with token patterns replaced by inline XDSBadge components. Wrap any message body inside XDSChatMessageBubble to turn raw @mentions, #tags, or /commands into styled badges. When no tokens match or none are provided, the text renders as-is, so you can use ChatTokenizedText unconditionally on every message.',
- props: [
- {name: 'children', type: 'string', description: 'The plain text message containing serialized token values. Patterns matching a token\'s value are replaced with badge components inline.', required: true},
- {name: 'tokens', type: 'XDSChatComposerToken[]', description: 'Token definitions: same type returned by trigger onSelect. Each token has a value (the string to match), label (display text), and optional variant and icon. Uses the same type as the composer input, so token definitions work for both input and display.'},
- ],
- },
- {
- name: 'XDSChatComposerTokenElement',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Token Element',
- description: 'Renders a single token chip outside the contentEditable input. Wraps a badge config or custom render function in the correct data-xds-token span so the token serializes properly and stays visually consistent with tokens inside the composer.',
- props: [
- {name: 'token', type: 'XDSChatComposerToken', description: 'The token to render. Pass a badge config ({ value, label, variant?, icon? }) for the common case, or a custom render ({ value, render }) for full control.', required: true},
- ],
- },
+ {name: 'XDSChatMessageList'},
+ {name: 'XDSChatMessage'},
+ {name: 'XDSChatMessageBubble'},
+ {name: 'XDSChatMessageMetadata'},
+ {name: 'XDSChatSystemMessage'},
+ {name: 'XDSChatComposer'},
+ {name: 'XDSChatComposerInput'},
+ {name: 'XDSChatComposerDrawer'},
+ {name: 'XDSChatSendButton'},
+ {name: 'XDSChatToolCalls'},
+ {name: 'XDSChatTokenizedText'},
+ {name: 'XDSChatComposerTokenElement'},
+ {name: 'XDSChatLayout'},
+ {name: 'XDSChatLayoutScrollButton'},
],
usage: {
description: 'XDSChatMessageList is the scrollable container for chat messages. It renders children in a flex column with role="log" for accessibility, provides density context to child messages, and supports infinite scroll for loading older messages. Use it inside XDSChatLayout for full-page chat with auto-scroll and composer docking, or standalone for embedded message panels.',
@@ -268,55 +88,6 @@ export const docs = {
},
};
-// Append XDSChatLayout and XDSChatLayoutScrollButton to all doc variants
-const chatLayoutComponent = {
- name: 'XDSChatLayout',
- displayName: 'Chat Layout',
- description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Adapts density (compact/balanced/spacious) automatically via container width observation. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body.',
- usage: {
- description: 'XDSChatLayout is the layout shell for full-page chat interfaces. It renders messages in normal page flow and docks the composer to the bottom with a frosted glass blur layer. Density adapts automatically via container width observation. Use it to wrap XDSChatMessageList and XDSChatComposer for a complete chat experience with built-in auto-scroll and a scroll-to-bottom button.',
- bestPractices: [
- { guidance: true, description: 'Pass XDSChatMessageList as children and XDSChatComposer as the composer prop for a complete chat interface.' },
- { guidance: true, description: 'Provide an emptyState so new conversations show a prompt instead of a blank screen.' },
- { guidance: true, description: 'Use scrollRef when the chat is embedded in a page where a parent element handles scrolling.' },
- { guidance: false, description: 'Don\'t apply a fixed height on the layout; let it fill its container with flex: 1.' },
- { guidance: false, description: 'Don\'t render multiple ChatLayout instances in the same scroll container; each expects to own its scroll context.' },
- ],
- anatomy: [
- { name: 'Message area', required: true, description: 'Scrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.' },
- { name: 'Frosted glass dock', required: true, description: 'Sticky or fixed container at the bottom with a backdrop-blur layer. Houses the scroll button and composer.' },
- { name: 'Scroll-to-bottom button', required: false, description: 'Appears when the user scrolls up or new messages arrive. Defaults to XDSChatLayoutScrollButton; pass null to hide or a custom element to override.' },
- { name: 'Composer', required: true, description: 'The input area for sending messages, typically XDSChatComposer. Docked at the bottom inside the frosted glass layer.' },
- { name: 'Empty state', required: false, description: 'Centered placeholder shown when no messages exist. Use XDSEmptyState for a consistent look.' },
- ],
- },
- props: [
- {name: 'children', type: 'ReactNode', description: 'Message content, typically XDSChatMessageList. Flows naturally in the page and scrolls with the container.', required: true},
- {name: 'composer', type: 'ReactNode', description: 'Composer element, typically XDSChatComposer. Fixed to the bottom with a frosted glass dock.', required: true,
- slotElements: [{__element: 'XDSTextInput', props: {label: 'Input', placeholder: 'Type here...'}}],
- },
- {name: 'emptyState', type: 'ReactNode', description: 'Content shown when children is empty. Centered vertically in the message area.',
- slotElements: [{__element: 'XDSEmptyState', props: {title: 'No items', description: 'Nothing to show.'}}],
- },
- {name: 'scrollButton', type: 'ReactNode | null', description: 'Scroll-to-bottom button rendered above the composer. Defaults to XDSChatLayoutScrollButton with auto-scroll integration. Pass null to hide.'},
- {name: 'scrollRef', type: 'React.RefObject<HTMLElement | null>', description: 'External scroll container ref. When provided, auto-scroll and scroll-to-bottom target this element instead of the layout root. Use when the chat is embedded in a page where a parent element or the document body scrolls.'},
- ],
-};
-docs.components.push(chatLayoutComponent);
-
-const chatLayoutScrollButtonComponent = {
- name: 'XDSChatLayoutScrollButton',
- isHiddenFromOverview: true,
- displayName: 'Chat Layout Scroll Button',
- description: 'Floating scroll-to-bottom button that appears when the user scrolls away from the latest messages. It fades in as a compact icon button and expands to show a label when new messages arrive. XDSChatLayout renders this by default; pass a custom element to the scrollButton prop to override, or null to hide it entirely.',
- props: [
- {name: 'isVisible', type: 'boolean', description: 'Whether the button is visible. Bind to a scroll-position check so the button only appears when the user has scrolled up.', required: true},
- {name: 'label', type: 'string', description: 'Optional label that expands the button (e.g. "New messages"). Use to signal unread content below the fold.'},
- {name: 'onClick', type: '() => void', description: 'Click handler; typically scrolls to bottom and dismisses the new message indicator.', required: true},
- ],
-};
-docs.components.push(chatLayoutScrollButtonComponent);
-
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
usage: {
@@ -344,177 +115,6 @@ export const docsZh = {
{ name: 'Empty state', required: false, description: 'Centered placeholder shown when no messages exist. Use XDSEmptyState for a consistent look.' },
],
},
- components: [
- {
- name: 'XDSChatMessageList',
- isHiddenFromOverview: true,
- displayName: 'Chat Message List',
- description: '消息展示容器,支持密度上下文和无限滚动。自动滚动由 XDSChatLayout 管理。',
- propDescriptions: {
- children: '消息元素,通常是 XDSChatMessage 或 XDSChatSystemMessage。',
- emptyState: '列表无消息时显示的内容。',
- scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
- density: '视觉密度,通过上下文传递给子消息。',
- gap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',
- },
- },
- {
- name: 'XDSChatMessage',
- displayName: 'Chat Message',
- description: '发送者上下文包装器,根据发送者角色处理头像、名称、元数据和对齐方式。',
- propDescriptions: {
- sender: '消息发送者,控制对齐和布局。',
- children: '自由内容:气泡、资源列表、工具调用、图片。',
- avatar: '消息旁边渲染的头像元素。通常是 XDSAvatar。',
- name: '消息正文上方渲染的发送者名称。当第一个子元素不是气泡时使用。',
- metadata: '消息正文下方渲染的元数据。当最后一个子元素不是气泡时使用。',
- density: '视觉密度。未设置时从列表上下文继承。',
- },
- },
- {
- name: 'XDSChatMessageBubble',
- isHiddenFromOverview: true,
- displayName: 'Chat Message Bubble',
- description: '样式化的气泡容器,从父上下文读取发送者信息进行自动样式化。支持 name/metadata 插槽、多气泡分组和透明变体。',
- propDescriptions: {
- children: '气泡内容:文本、XDSMarkdown 或任何 ReactNode。',
- variant: "视觉变体。'filled' 渲染发送者颜色背景,'ghost' 渲染透明背景但保持填充对齐。",
- name: '气泡上方渲染的发送者名称,与气泡文本内边距对齐。用于消息中的第一个气泡。',
- metadata: '气泡下方渲染的元数据内容,与气泡文本内边距对齐。用于消息中的最后一个气泡。',
- group: '多气泡组中的位置。控制发送者侧的圆角缩减。',
- },
- },
- {
- name: 'XDSChatMessageMetadata',
- displayName: 'Chat Message Metadata',
- description: '可组合的消息元数据行。渲染时间戳、页脚内容和发送状态。用户消息方向反转。',
- propDescriptions: {timestamp: '时间戳内容:字符串或 XDSTimestamp 组件。', footer: '页脚内容:模型信息、反应按钮、复制按钮。', status: '消息发送状态。显示图标和标签。'},
- },
- {
- name: 'XDSChatSystemMessage',
- displayName: 'Chat System Message',
- description: '居中的系统消息,用于日期分隔、成员变更和状态通知等非发送者内容。没有头像、对齐或气泡。使用 divider 变体做时间分隔,default 做内联状态更新。',
- propDescriptions: {children: '系统消息内容:简短的事实性文本,如日期、加入/离开通知或状态变更。', variant: "视觉变体。'default' 渲染居中文本。'divider' 通过 XDSDivider 在两侧添加水平线,用于日期分隔和段落分隔。", icon: '增强消息类型辨识度的前置图标。使用 XDSIcon 包裹以获得一致的尺寸。'},
- },
- {
- name: 'XDSChatComposer',
- displayName: 'Chat Composer',
- description: '聊天编写器布局外壳。排列命名插槽(附件、标题栏、输入、页脚、发送),带有页面圆角容器和同心内圆角。',
- propDescriptions: {
- onSubmit: '用户提交消息时调用。',
- onStop: '用户请求停止生成时调用。',
- isStopShown: '是否显示停止按钮。',
- value: '受控输入值。',
- onChange: '受控模式的输入值变更时调用。序列化字符串包含标记占位符。',
- placeholder: '输入为空时显示的占位文本。',
- isDisabled: '禁用编写器。',
- density: '视觉密度。',
- drawer: '插槽:输入上方的可折叠抽屉,用于附件、上下文标签等。使用 XDSChatComposerDrawer。',
- headerActions: '插槽:标题左侧操作按钮(附件、提及按钮)。使用仅图标 size="sm" 按钮。',
- headerContext: '插槽:标题右侧上下文信息(上下文窗口使用情况、XDSProgressBar、辅助文本)。',
- input: '插槽:自定义输入元素。替换默认文本区域。使用 XDSChatComposerInput 实现触发菜单。',
- footerActions: '插槽:左对齐的页脚操作(模型选择器等)。',
- sendActions: '插槽:发送按钮左侧的操作。',
- sendButton: '插槽:自定义发送按钮。替换默认的发送/停止按钮。',
- status: '编写器下方(或上方)的状态消息。',
- statusPosition: '状态渲染位置。',
- },
- },
- {
- name: 'XDSChatComposerInput',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Input',
- description:
- '聊天编写器的富文本输入。支持触发菜单(输入 @ 或 / 打开 typeahead)、内联标记徽章、ArrowUp/Down 消息历史回溯、粘贴/拖放文件处理,并在触控设备上将字体大小保持至少 16px 以避免 iOS 输入缩放。当需要普通文本区域以外的功能时,传入 XDSChatComposer 的 input 插槽。',
- propDescriptions: {
- handleRef: '命令式句柄,用于编程式控制:insertToken、insertText、focus 和 getValue。',
- value: '受控输入值。与 onChange 配对实现双向绑定。',
- onChange: '输入值变更时调用。序列化字符串包含标记占位符。',
- placeholder: '输入为空时显示的占位文本。',
- maxRows: '滚动前的最大可见行数。紧凑布局中使用较小值。',
- triggers: '菜单的触发定义。每个触发器指定字符(@ 或 /)、搜索源和返回要插入标记的 onSelect 处理器。',
- debounceMs: '异步搜索源的去抖动延迟,避免过多网络请求。',
- hasHistory: '启用 ArrowUp/Down 回溯之前提交的消息。',
- label: '屏幕阅读器播报的无障碍标签。',
- isDisabled: '禁用输入。在流式输出期间或前置条件未满足时使用。',
- onPaste: '粘贴文本时调用。用于拦截或转换粘贴内容。',
- onFiles: '粘贴或拖放文件到输入时调用。用于处理附件。',
- onSubmit: '用户不按 Shift 按 Enter 时调用。序列化值包含标记占位符。',
- },
- },
- {
- name: 'XDSChatComposerDrawer',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Drawer',
- description: '位于聊天输入上方的可折叠抽屉面板。传入 XDSChatComposer 的 `drawer` 插槽,用于显示附件、上下文标签或预览内容。提供 `count` 时启用折叠切换。',
- propDescriptions: {children: '抽屉内渲染的内容:标记、标签、预览或任何 React 元素。', count: '折叠徽章中显示的总数。提供时,抽屉获得折叠/展开切换。', label: '折叠状态下显示在数量旁边的标签。', isCollapsed: '受控折叠状态。与 onCollapsedChange 一起使用。', defaultIsCollapsed: '非受控模式的初始折叠状态。', onCollapsedChange: '用户切换抽屉时触发的回调。'},
- },
- {
- name: 'XDSChatSendButton',
- isHiddenFromOverview: true,
- displayName: 'Chat Send Button',
- description:
- '编写器的圆形发送/停止切换按钮。默认从 XDSChatComposerContext 读取状态,在 XDSChatComposer 内自动工作。所有上下文值均可通过 props 覆盖以用于独立使用。',
- propDescriptions: {
- isStopShown: '是否显示停止按钮。默认使用上下文值。',
- isDisabled: '发送按钮是否禁用。默认使用上下文的 !canSend。',
- onSend: '用户点击发送时调用。默认使用上下文的 onSubmit。',
- onStop: '流式响应期间用户点击停止时调用。默认使用上下文的 onStop。',
- sendIcon: '发送状态的自定义图标。默认使用图标注册表的 arrowUp。',
- stopIcon: '停止状态的自定义图标。默认使用图标注册表的 stop。',
- size: '按钮大小。',
- xstyle: '额外的 StyleX 样式。',
- },
- },
- {
- name: 'XDSChatToolCalls',
- displayName: 'Chat Tool Calls',
- description:
- '显示 LLM 响应中的工具/函数调用。接受与 LLM API 返回形状匹配的 calls 数组。单个调用内联渲染;多个调用显示可折叠摘要。',
- propDescriptions: {
- calls:
- '工具调用数据数组。每项包含 name、status、target、duration、node、additions、deletions、stats、resultDetail。',
- label: '组的自定义摘要标签。省略时从数量自动生成。',
- isExpanded: '受控展开状态。',
- defaultIsExpanded: '默认展开状态(非受控)。',
- onExpandedChange: '展开状态变更时的回调。',
- },
- },
- {
- name: 'XDSChatTokenizedText',
- isHiddenFromOverview: true,
- displayName: 'Chat Tokenized Text',
- description:
- '渲染带有标记模式的文本,将匹配的模式替换为内联 XDSBadge 组件。在 XDSChatMessageBubble 内使用,将 @提及、#标签或 /命令显示为样式化徽章。未提供标记时以纯文本渲染,因此可以无条件使用。',
- propDescriptions: {children: '包含序列化标记值的纯文本消息。匹配标记值的模式将被替换为内联徽章组件。', tokens: '标记定义:与触发器 onSelect 返回的类型相同。每个包含 value(匹配字符串)、label(显示文本)以及可选的 variant 和 icon。'},
- },
- {
- name: 'XDSChatComposerTokenElement',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Token Element',
- description: '在 contentEditable 外部渲染标记芯片。',
- propDescriptions: {token: '徽章配置或自定义渲染。'},
- },
- {
- name: 'XDSChatLayout',
- displayName: 'Chat Layout',
- description: '完整聊天界面的布局外壳。消息在页面中自然流动,编写器固定在底部,带有毛玻璃效果。通过容器宽度自动适配密度。',
- propDescriptions: {
- children: '消息内容:通常是 XDSChatMessageList。在页面中自然流动。',
- composer: '编写器元素:通常是 XDSChatComposer。固定在底部,带有毛玻璃底座。',
- emptyState: '子元素为空时显示的内容。',
- scrollButton: '编写器上方的滚动到底部按钮。默认使用 XDSChatLayoutScrollButton。传入 null 隐藏。',
- scrollRef: '外部滚动容器引用。提供时,自动滚动和滚动到底部将目标指向此元素。',
- },
- },
- {
- name: 'XDSChatLayoutScrollButton',
- isHiddenFromOverview: true,
- displayName: 'Chat Layout Scroll Button',
- description: '可组合的滚动到底部按钮。可见时淡入,提供标签时展开。',
- propDescriptions: {isVisible: '按钮是否可见。', label: '可选标签:展开按钮(如"新消息")。', onClick: '点击处理器。'},
- },
- ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -539,194 +139,4 @@ export const docsDense = {
{ guidance: false, description: 'Metadata/names on both bubble and wrapper: pick one.' },
],
},
- components: [
- {
- name: 'XDSChatMessageList',
- isHiddenFromOverview: true,
- displayName: 'Chat Message List',
- description: 'presentational msg container w/ density context + infinite scroll; auto-scroll owned by XDSChatLayout',
- propDescriptions: {
- children: 'msg elements (XDSChatMessage or XDSChatSystemMessage)',
- emptyState: 'content when no msgs',
- scrollToTopAction: 'async action at scroll top; load older msgs',
- density: 'visual density; flows to children via context',
- gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
- },
- },
- {
- name: 'XDSChatMessage',
- displayName: 'Chat Message',
- description: 'sender context wrapper; handles avatar+name+metadata+alignment by sender role',
- propDescriptions: {
- sender: 'who sent; controls alignment+layout',
- children: 'free-form: bubbles, assets, tool calls, images',
- avatar: 'avatar element beside msg; typically XDSAvatar',
- name: 'sender name above body; use when first child is raw (not bubble)',
- displayName: 'sender name above body; use when first child is raw (not bubble)',
- metadata: 'metadata below body; use when last child is raw (not bubble)',
- density: 'visual density; inherited from list context if unset',
- },
- },
- {
- name: 'XDSChatMessageBubble',
- isHiddenFromOverview: true,
- displayName: 'Chat Message Bubble',
- description: 'styled bubble container; reads sender from context; supports name/metadata slots, group corners, ghost variant',
- propDescriptions: {
- children: 'bubble content: text, XDSMarkdown, any ReactNode',
- variant: "filled (sender bg) or ghost (transparent, keeps padding)",
- name: 'sender name above bubble, aligned w/ bubble padding',
- displayName: 'sender name above bubble, aligned w/ bubble padding',
- metadata: 'metadata below bubble, aligned w/ bubble padding',
- group: "position in multi-bubble group; controls corner radius reduction",
- },
- },
- {
- name: 'XDSChatMessageMetadata',
- displayName: 'Chat Message Metadata',
- description: 'composable metadata row; renders timestamp · footer · status; reverses for user sender',
- propDescriptions: {
- timestamp: 'timestamp content; string or XDSTimestamp',
- footer: 'footer content; model info, reaction btns, copy btn',
- status: 'delivery status; shows icon+label',
- },
- },
- {
- name: 'XDSChatSystemMessage',
- displayName: 'Chat System Message',
- description: 'centered non-sender msg; divider variant for date breaks, default for status notices; supports leading icon',
- propDescriptions: {
- children: 'short factual text: date, join/leave, status change',
- variant: "default=centered text, divider=horizontal lines via XDSDivider for date/section breaks",
- icon: 'leading icon reinforcing msg type; wrap in XDSIcon',
- },
- },
- {
- name: 'XDSChatComposer',
- displayName: 'Chat Composer',
- description: 'composer layout shell; named slots (drawer/header/input/footer/send) w/ page-radius + concentric inner radius',
- propDescriptions: {
- onSubmit: 'submit msg handler',
- onStop: 'stop generation handler',
- isStopShown: 'whether the stop button is shown',
- value: 'controlled input value',
- onChange: 'controlled change handler',
- placeholder: 'placeholder when empty',
- isDisabled: 'disabled; use during streaming or unmet prereqs',
- density: 'visual density',
- drawer: 'slot: collapsible drawer above input for attachments, context chips, etc.; use XDSChatComposerDrawer',
- headerActions: 'slot: left header actions (attach, mention); icon-only sm buttons',
- headerContext: 'slot: right header context info (window usage, XDSProgressBar, text)',
- input: 'slot: custom input; replaces default textarea; use XDSChatComposerInput for triggers',
- footerActions: 'slot: left footer actions (model selector etc)',
- sendActions: 'slot: actions left of send btn',
- sendButton: 'slot: custom send btn; replaces default',
- status: 'status msg below/above composer',
- statusPosition: 'status render position',
- },
- },
- {
- name: 'XDSChatComposerInput',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Input',
- description: 'rich input for composer; trigger menus (@/commands), inline tokens, msg history, paste/drop files, 16px touch font-size floor to prevent iOS zoom. Use in XDSChatComposer input slot when you need more than plain textarea.',
- propDescriptions: {
- handleRef: 'imperative handle (insertToken/insertText/focus/getValue)',
- value: 'controlled value; pair w/ onChange for two-way binding',
- onChange: 'value change handler; serialized string includes token placeholders',
- placeholder: 'placeholder when empty',
- maxRows: 'max visible rows before scroll; lower for compact layouts',
- triggers: 'typeahead trigger defs; character(@/)+searchSource+onSelect returning token',
- debounceMs: 'debounce for async search to avoid excess requests',
- hasHistory: 'ArrowUp/Down to recall previous submissions',
- label: 'a11y label for screen readers',
- isDisabled: 'disabled; use during streaming or unmet prereqs',
- onPaste: 'paste handler; intercept/transform pasted content',
- onFiles: 'file paste/drop handler; use for attachments',
- onSubmit: 'Enter w/o Shift handler; serialized value includes token placeholders',
- },
- },
- {
- name: 'XDSChatComposerDrawer',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Drawer',
- description: 'collapsible drawer above chat input; pass to composer `drawer` slot for attachments, context chips, previews. `count` enables collapse toggle',
- propDescriptions: {
- children: 'drawer content: tokens, chips, previews, any React elements',
- count: 'total count for collapsed badge; enables collapse/expand toggle',
- label: 'collapsed label next to count badge',
- isCollapsed: 'controlled collapsed state',
- defaultIsCollapsed: 'initial collapsed state (uncontrolled)',
- onCollapsedChange: 'callback on collapse toggle',
- },
- },
- {
- name: 'XDSChatSendButton',
- isHiddenFromOverview: true,
- displayName: 'Chat Send Button',
- description: 'circular send/stop toggle btn for composer; reads XDSChatComposerContext; all context vals overridable via props',
- propDescriptions: {
- isStopShown: 'stop button visibility; defaults to context',
- isDisabled: 'disabled; defaults to !canSend from context',
- onSend: 'send click handler; defaults to context onSubmit',
- onStop: 'stop click handler; defaults to context onStop',
- sendIcon: 'custom send icon; default arrowUp from registry',
- stopIcon: 'custom stop icon; default stop from registry',
- size: 'btn size',
- xstyle: 'additional StyleX styles',
- },
- },
- {
- name: 'XDSChatToolCalls',
- displayName: 'Chat Tool Calls',
- description: 'tool/function call display from LLM response; single=inline, multiple=collapsible summary',
- propDescriptions: {
- calls: 'tool call data array; name+status+target+duration+node+additions+deletions+resultDetail',
- label: 'custom summary label; auto from count if omitted',
- isExpanded: 'controlled expanded state',
- defaultIsExpanded: 'default expanded state (uncontrolled)',
- onExpandedChange: 'expanded state change callback',
- },
- },
- {
- name: 'XDSChatTokenizedText',
- isHiddenFromOverview: true,
- displayName: 'Chat Tokenized Text',
- description: 'renders text w/ token patterns replaced by inline badges; use in bubble for @mentions, #tags, /commands; degrades to plain text when no tokens match',
- propDescriptions: {
- children: 'plain text msg w/ serialized token values; matching patterns become inline badges',
- tokens: 'token defs (same type as composer input): value+label+variant+icon',
- },
- },
- {
- name: 'XDSChatComposerTokenElement',
- isHiddenFromOverview: true,
- displayName: 'Chat Composer Token Element',
- description: 'token chip outside contentEditable; badge config or custom render in data-xds-token span',
- propDescriptions: {token: 'badge config or custom render'},
- },
- {
- name: 'XDSChatLayout',
- displayName: 'Chat Layout',
- description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; auto density via container width; scrollRef delegates to parent/body',
- propDescriptions: {
- children: 'msg content; typically XDSChatMessageList',
- composer: 'composer element; typically XDSChatComposer; fixed bottom w/ frosted glass',
- emptyState: 'content when children empty',
- scrollButton: 'scroll-to-bottom btn; defaults to XDSChatLayoutScrollButton; pass null to hide',
- scrollRef: 'external scroll container ref; targets parent/body instead of layout root',
- },
- },
- {
- name: 'XDSChatLayoutScrollButton',
- isHiddenFromOverview: true,
- displayName: 'Chat Layout Scroll Button',
- description: 'floating scroll-to-bottom btn; fades in when scrolled up, expands w/ label for new msgs. Default in XDSChatLayout; override via scrollButton prop.',
- propDescriptions: {
- isVisible: 'btn visibility; bind to scroll-position check',
- label: 'optional label; expands btn (e.g. "New messages")',
- onClick: 'click handler',
- },
- },
- ],
};
diff --git a/packages/core/src/Chat/ChatComposer.doc.mjs b/packages/core/src/Chat/ChatComposer.doc.mjs
new file mode 100644
index 0000000000..90487a078b
--- /dev/null
+++ b/packages/core/src/Chat/ChatComposer.doc.mjs
@@ -0,0 +1,220 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatComposer',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Composer',
+ description: 'Layout shell for a chat composer. Arranges named slots (drawer, header, input, footer, send) with page-radius container, hover/focus shadows, and concentric inner radius for child elements.',
+ props: [
+ {
+ name: 'onSubmit',
+ type: '(value: string) => void',
+ description: 'Called when the user submits a message.',
+ required: true,
+ },
+ {
+ name: 'onStop',
+ type: '() => void',
+ description: 'Called when the user requests to stop generation.',
+ },
+ {
+ name: 'isStopShown',
+ type: 'boolean',
+ description: 'Whether the stop button is shown instead of the send button.',
+ default: 'false',
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Controlled input value.',
+ },
+ {
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Change handler for controlled mode.',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text shown when the input is empty.',
+ default: "'Type a message…'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the composer.',
+ default: 'false',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Visual density.',
+ default: "'balanced'",
+ },
+ {
+ name: 'drawer',
+ type: 'ReactNode',
+ description: 'Slot: collapsible drawer above the input — attachments, context chips, etc. Use XDSChatComposerDrawer.',
+ slotElements: [
+ {
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Drawer content',
+ },
+ ],
+ },
+ {
+ name: 'headerActions',
+ type: 'ReactNode',
+ description: 'Slot: left-aligned header actions (attach, mention buttons). Use icon-only size="sm" buttons.',
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {
+ label: 'Action',
+ variant: 'ghost',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'headerContext',
+ type: 'ReactNode',
+ description: 'Slot: right-aligned contextual info in the header (context window usage, XDSProgressBar, supporting text).',
+ slotElements: [
+ {
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Context',
+ },
+ ],
+ },
+ {
+ name: 'input',
+ type: 'ReactNode',
+ description: 'Slot: custom input element. Replaces the default textarea. Use XDSChatComposerInput for trigger menus.',
+ slotElements: [
+ {
+ __element: 'XDSTextInput',
+ props: {
+ label: 'Input',
+ placeholder: 'Type here...',
+ },
+ },
+ ],
+ },
+ {
+ name: 'footerActions',
+ type: 'ReactNode',
+ description: 'Slot: left-aligned footer actions (model selector, etc).',
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {
+ label: 'Action',
+ variant: 'ghost',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'sendActions',
+ type: 'ReactNode',
+ description: 'Slot: actions to the left of the send button.',
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {
+ label: 'Action',
+ variant: 'ghost',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'sendButton',
+ type: 'ReactNode',
+ description: 'Slot: custom send button. Replaces the default send/stop button.',
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {
+ label: 'Action',
+ variant: 'ghost',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'status',
+ type: "{ type: 'error' | 'warning'; message?: string }",
+ description: 'Status message rendered below (or above) the composer.',
+ },
+ {
+ name: 'statusPosition',
+ type: "'top' | 'bottom'",
+ description: 'Where to render the status.',
+ default: "'bottom'",
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatComposer',
+ displayName: 'Chat Composer',
+ description: '聊天编写器布局外壳。排列命名插槽(附件、标题栏、输入、页脚、发送),带有页面圆角容器和同心内圆角。',
+ propDescriptions: {
+ onSubmit: '用户提交消息时调用。',
+ onStop: '用户请求停止生成时调用。',
+ isStopShown: '是否显示停止按钮。',
+ value: '受控输入值。',
+ onChange: '受控模式的输入值变更时调用。序列化字符串包含标记占位符。',
+ placeholder: '输入为空时显示的占位文本。',
+ isDisabled: '禁用编写器。',
+ density: '视觉密度。',
+ drawer: '插槽:输入上方的可折叠抽屉——附件、上下文标签等。使用 XDSChatComposerDrawer。',
+ headerActions: '插槽:标题左侧操作按钮(附件、提及按钮)。使用仅图标 size="sm" 按钮。',
+ headerContext: '插槽:标题右侧上下文信息(上下文窗口使用情况、XDSProgressBar、辅助文本)。',
+ input: '插槽:自定义输入元素。替换默认文本区域。使用 XDSChatComposerInput 实现触发菜单。',
+ footerActions: '插槽:左对齐的页脚操作(模型选择器等)。',
+ sendActions: '插槽:发送按钮左侧的操作。',
+ sendButton: '插槽:自定义发送按钮。替换默认的发送/停止按钮。',
+ status: '编写器下方(或上方)的状态消息。',
+ statusPosition: '状态渲染位置。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatComposer',
+ displayName: 'Chat Composer',
+ description: 'composer layout shell; named slots (drawer/header/input/footer/send) w/ page-radius + concentric inner radius',
+ propDescriptions: {
+ onSubmit: 'submit msg handler',
+ onStop: 'stop generation handler',
+ isStopShown: 'whether the stop button is shown',
+ value: 'controlled input value',
+ onChange: 'controlled change handler',
+ placeholder: 'placeholder when empty',
+ isDisabled: 'disabled; use during streaming or unmet prereqs',
+ density: 'visual density',
+ drawer: 'slot: collapsible drawer above input — attachments, context chips, etc.; use XDSChatComposerDrawer',
+ headerActions: 'slot: left header actions (attach, mention); icon-only sm buttons',
+ headerContext: 'slot: right header context info (window usage, XDSProgressBar, text)',
+ input: 'slot: custom input; replaces default textarea; use XDSChatComposerInput for triggers',
+ footerActions: 'slot: left footer actions (model selector etc)',
+ sendActions: 'slot: actions left of send btn',
+ sendButton: 'slot: custom send btn; replaces default',
+ status: 'status msg below/above composer',
+ statusPosition: 'status render position',
+ },
+};
diff --git a/packages/core/src/Chat/ChatComposerDrawer.doc.mjs b/packages/core/src/Chat/ChatComposerDrawer.doc.mjs
new file mode 100644
index 0000000000..5c7e969090
--- /dev/null
+++ b/packages/core/src/Chat/ChatComposerDrawer.doc.mjs
@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatComposerDrawer',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Composer Drawer',
+ isHiddenFromOverview: true,
+ description: "Collapsible drawer panel that sits above the chat input inside XDSChatComposer. Pass it to the composer's `drawer` slot to show attachments, context chips, or any supplementary content. When `count` is provided the drawer gains a collapse toggle — collapsed state shows a badge and label, expanded state shows all children.",
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content to render inside the drawer — tokens, chips, previews, or any React elements.',
+ required: true,
+ },
+ {
+ name: 'count',
+ type: 'number',
+ description: 'Total item count shown in the collapsed badge. When provided, the drawer gains a collapse/expand toggle.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label shown next to the count in collapsed state.',
+ default: "'Items'",
+ },
+ {
+ name: 'isCollapsed',
+ type: 'boolean',
+ description: 'Controlled collapsed state. Use with `onCollapsedChange` for external control.',
+ },
+ {
+ name: 'defaultIsCollapsed',
+ type: 'boolean',
+ description: 'Initial collapsed state for uncontrolled usage.',
+ default: 'false',
+ },
+ {
+ name: 'onCollapsedChange',
+ type: '(isCollapsed: boolean) => void',
+ description: 'Callback fired when the user toggles the drawer.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatComposerDrawer',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Composer Drawer',
+ description: '位于聊天输入上方的可折叠抽屉面板。传入 XDSChatComposer 的 `drawer` 插槽,用于显示附件、上下文标签或预览内容。提供 `count` 时启用折叠切换。',
+ propDescriptions: {
+ children: '抽屉内渲染的内容——标记、标签、预览或任何 React 元素。',
+ count: '折叠徽章中显示的总数。提供时,抽屉获得折叠/展开切换。',
+ label: '折叠状态下显示在数量旁边的标签。',
+ isCollapsed: '受控折叠状态。与 onCollapsedChange 一起使用。',
+ defaultIsCollapsed: '非受控模式的初始折叠状态。',
+ onCollapsedChange: '用户切换抽屉时触发的回调。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatComposerDrawer',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Composer Drawer',
+ description: 'collapsible drawer above chat input; pass to composer `drawer` slot for attachments, context chips, previews. `count` enables collapse toggle',
+ propDescriptions: {
+ children: 'drawer content — tokens, chips, previews, any React elements',
+ count: 'total count for collapsed badge; enables collapse/expand toggle',
+ label: 'collapsed label next to count badge',
+ isCollapsed: 'controlled collapsed state',
+ defaultIsCollapsed: 'initial collapsed state (uncontrolled)',
+ onCollapsedChange: 'callback on collapse toggle',
+ },
+};
diff --git a/packages/core/src/Chat/ChatComposerInput.doc.mjs b/packages/core/src/Chat/ChatComposerInput.doc.mjs
new file mode 100644
index 0000000000..3c2c41ddad
--- /dev/null
+++ b/packages/core/src/Chat/ChatComposerInput.doc.mjs
@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatComposerInput',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Composer Input',
+ isHiddenFromOverview: true,
+ description: "Rich text input for the chat composer. Supports trigger menus (type @ or / to open a typeahead), inline tokens rendered as badges, message history recall with ArrowUp/Down, paste/drop file handling, and a 16px touch-device font-size floor to prevent iOS input zoom. Pass it to XDSChatComposer's input slot when you need more than a plain textarea.",
+ props: [
+ {
+ name: 'handleRef',
+ type: 'React.Ref<XDSChatComposerInputHandle>',
+ description: 'Imperative handle for programmatic control — insertToken, insertText, focus, and getValue.',
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Controlled input value. Pair with onChange for two-way binding.',
+ },
+ {
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Called when the input value changes. The serialized string includes token placeholders.',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text shown when the input is empty.',
+ default: "'Type a message…'",
+ },
+ {
+ name: 'maxRows',
+ type: 'number',
+ description: 'Maximum visible rows before the input scrolls. Use a lower value in compact layouts.',
+ default: '8',
+ },
+ {
+ name: 'triggers',
+ type: 'XDSChatComposerTrigger[]',
+ description: 'Trigger definitions for typeahead menus. Each trigger specifies a character (@ or /), a search source, and an onSelect handler that returns the token to insert.',
+ },
+ {
+ name: 'debounceMs',
+ type: 'number',
+ description: 'Debounce delay for async search sources to avoid excessive network requests.',
+ default: '150',
+ },
+ {
+ name: 'hasHistory',
+ type: 'boolean',
+ description: 'Enable ArrowUp/Down to recall previously submitted messages.',
+ default: 'true',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label announced by screen readers.',
+ default: "'Message input'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the input. Use during streaming or when a prerequisite is unmet.',
+ default: 'false',
+ },
+ {
+ name: 'onPaste',
+ type: '(event, text) => void',
+ description: 'Called when text is pasted. Use to intercept or transform pasted content.',
+ },
+ {
+ name: 'onFiles',
+ type: '(files: File[]) => void',
+ description: 'Called when files are pasted or dropped onto the input. Use to handle attachments.',
+ },
+ {
+ name: 'onSubmit',
+ type: '(value: string) => void',
+ description: 'Called when the user presses Enter without Shift. The serialized value includes token placeholders.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatComposerInput',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Composer Input',
+ description: '聊天编写器的富文本输入。支持触发菜单(输入 @ 或 / 打开 typeahead)、内联标记徽章、ArrowUp/Down 消息历史回溯、粘贴/拖放文件处理,并在触控设备上将字体大小保持至少 16px 以避免 iOS 输入缩放。当需要普通文本区域以外的功能时,传入 XDSChatComposer 的 input 插槽。',
+ propDescriptions: {
+ handleRef: '命令式句柄,用于编程式控制 — insertToken、insertText、focus 和 getValue。',
+ value: '受控输入值。与 onChange 配对实现双向绑定。',
+ onChange: '输入值变更时调用。序列化字符串包含标记占位符。',
+ placeholder: '输入为空时显示的占位文本。',
+ maxRows: '滚动前的最大可见行数。紧凑布局中使用较小值。',
+ triggers: '菜单的触发定义。每个触发器指定字符(@ 或 /)、搜索源和返回要插入标记的 onSelect 处理器。',
+ debounceMs: '异步搜索源的去抖动延迟,避免过多网络请求。',
+ hasHistory: '启用 ArrowUp/Down 回溯之前提交的消息。',
+ label: '屏幕阅读器播报的无障碍标签。',
+ isDisabled: '禁用输入。在流式输出期间或前置条件未满足时使用。',
+ onPaste: '粘贴文本时调用。用于拦截或转换粘贴内容。',
+ onFiles: '粘贴或拖放文件到输入时调用。用于处理附件。',
+ onSubmit: '用户不按 Shift 按 Enter 时调用。序列化值包含标记占位符。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatComposerInput',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Composer Input',
+ description: 'rich input for composer; trigger menus (@/commands), inline tokens, msg history, paste/drop files, 16px touch font-size floor to prevent iOS zoom. Use in XDSChatComposer input slot when you need more than plain textarea.',
+ propDescriptions: {
+ handleRef: 'imperative handle (insertToken/insertText/focus/getValue)',
+ value: 'controlled value; pair w/ onChange for two-way binding',
+ onChange: 'value change handler; serialized string includes token placeholders',
+ placeholder: 'placeholder when empty',
+ maxRows: 'max visible rows before scroll; lower for compact layouts',
+ triggers: 'typeahead trigger defs; character(@/)+searchSource+onSelect returning token',
+ debounceMs: 'debounce for async search to avoid excess requests',
+ hasHistory: 'ArrowUp/Down to recall previous submissions',
+ label: 'a11y label for screen readers',
+ isDisabled: 'disabled; use during streaming or unmet prereqs',
+ onPaste: 'paste handler; intercept/transform pasted content',
+ onFiles: 'file paste/drop handler; use for attachments',
+ onSubmit: 'Enter w/o Shift handler; serialized value includes token placeholders',
+ },
+};
diff --git a/packages/core/src/Chat/ChatComposerTokenElement.doc.mjs b/packages/core/src/Chat/ChatComposerTokenElement.doc.mjs
new file mode 100644
index 0000000000..d5cc01b824
--- /dev/null
+++ b/packages/core/src/Chat/ChatComposerTokenElement.doc.mjs
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatComposerTokenElement',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Composer Token Element',
+ isHiddenFromOverview: true,
+ description: 'Renders a single token chip outside the contentEditable input. Wraps a badge config or custom render function in the correct data-xds-token span so the token serializes properly and stays visually consistent with tokens inside the composer.',
+ props: [
+ {
+ name: 'token',
+ type: 'XDSChatComposerToken',
+ description: 'The token to render. Pass a badge config ({ value, label, variant?, icon? }) for the common case, or a custom render ({ value, render }) for full control.',
+ required: true,
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatComposerTokenElement',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Composer Token Element',
+ description: '在 contentEditable 外部渲染标记芯片。',
+ propDescriptions: {
+ token: '徽章配置或自定义渲染。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatComposerTokenElement',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Composer Token Element',
+ description: 'token chip outside contentEditable; badge config or custom render in data-xds-token span',
+ propDescriptions: {
+ token: 'badge config or custom render',
+ },
+};
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
new file mode 100644
index 0000000000..ef3b9121a2
--- /dev/null
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatLayout',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Layout',
+ description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Adapts density (compact/balanced/spacious) automatically via container width observation. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Message content — typically XDSChatMessageList. Flows naturally in the page and scrolls with the container.',
+ required: true,
+ },
+ {
+ name: 'composer',
+ type: 'ReactNode',
+ description: 'Composer element — typically XDSChatComposer. Fixed to the bottom with a frosted glass dock.',
+ required: true,
+ slotElements: [
+ {
+ __element: 'XDSTextInput',
+ props: {
+ label: 'Input',
+ placeholder: 'Type here...',
+ },
+ },
+ ],
+ },
+ {
+ name: 'emptyState',
+ type: 'ReactNode',
+ description: 'Content shown when children is empty. Centered vertically in the message area.',
+ slotElements: [
+ {
+ __element: 'XDSEmptyState',
+ props: {
+ title: 'No items',
+ description: 'Nothing to show.',
+ },
+ },
+ ],
+ },
+ {
+ name: 'scrollButton',
+ type: 'ReactNode | null',
+ description: 'Scroll-to-bottom button rendered above the composer. Defaults to XDSChatLayoutScrollButton with auto-scroll integration. Pass null to hide.',
+ },
+ {
+ name: 'scrollRef',
+ type: 'React.RefObject<HTMLElement | null>',
+ description: 'External scroll container ref. When provided, auto-scroll and scroll-to-bottom target this element instead of the layout root. Use when the chat is embedded in a page where a parent element or the document body scrolls.',
+ },
+ ],
+ usage: {
+ description: 'XDSChatLayout is the layout shell for full-page chat interfaces. It renders messages in normal page flow and docks the composer to the bottom with a frosted glass blur layer. Density adapts automatically via container width observation. Use it to wrap XDSChatMessageList and XDSChatComposer for a complete chat experience with built-in auto-scroll and a scroll-to-bottom button.',
+ bestPractices: [
+ {
+ guidance: true,
+ description: 'Pass XDSChatMessageList as children and XDSChatComposer as the composer prop for a complete chat interface.',
+ },
+ {
+ guidance: true,
+ description: 'Provide an emptyState so new conversations show a prompt instead of a blank screen.',
+ },
+ {
+ guidance: true,
+ description: 'Use scrollRef when the chat is embedded in a page where a parent element handles scrolling.',
+ },
+ {
+ guidance: false,
+ description: "Don't apply a fixed height on the layout — let it fill its container with flex: 1.",
+ },
+ {
+ guidance: false,
+ description: "Don't render multiple ChatLayout instances in the same scroll container — each expects to own its scroll context.",
+ },
+ ],
+ anatomy: [
+ {
+ name: 'Message area',
+ required: true,
+ description: 'Scrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.',
+ },
+ {
+ name: 'Frosted glass dock',
+ required: true,
+ description: 'Sticky or fixed container at the bottom with a backdrop-blur layer. Houses the scroll button and composer.',
+ },
+ {
+ name: 'Scroll-to-bottom button',
+ required: false,
+ description: 'Appears when the user scrolls up or new messages arrive. Defaults to XDSChatLayoutScrollButton; pass null to hide or a custom element to override.',
+ },
+ {
+ name: 'Composer',
+ required: true,
+ description: 'The input area for sending messages, typically XDSChatComposer. Docked at the bottom inside the frosted glass layer.',
+ },
+ {
+ name: 'Empty state',
+ required: false,
+ description: 'Centered placeholder shown when no messages exist. Use XDSEmptyState for a consistent look.',
+ },
+ ],
+ },
+};
+
+export const docsZh = {
+ name: 'ChatLayout',
+ displayName: 'Chat Layout',
+ description: '完整聊天界面的布局外壳。消息在页面中自然流动,编写器固定在底部,带有毛玻璃效果。通过容器宽度自动适配密度。',
+ propDescriptions: {
+ children: '消息内容 — 通常是 XDSChatMessageList。在页面中自然流动。',
+ composer: '编写器元素 — 通常是 XDSChatComposer。固定在底部,带有毛玻璃底座。',
+ emptyState: '子元素为空时显示的内容。',
+ scrollButton: '编写器上方的滚动到底部按钮。默认使用 XDSChatLayoutScrollButton。传入 null 隐藏。',
+ scrollRef: '外部滚动容器引用。提供时,自动滚动和滚动到底部将目标指向此元素。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatLayout',
+ displayName: 'Chat Layout',
+ description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; auto density via container width; scrollRef delegates to parent/body',
+ propDescriptions: {
+ children: 'msg content; typically XDSChatMessageList',
+ composer: 'composer element; typically XDSChatComposer; fixed bottom w/ frosted glass',
+ emptyState: 'content when children empty',
+ scrollButton: 'scroll-to-bottom btn; defaults to XDSChatLayoutScrollButton; pass null to hide',
+ scrollRef: 'external scroll container ref; targets parent/body instead of layout root',
+ },
+};
diff --git a/packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs b/packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs
new file mode 100644
index 0000000000..02b6a2238a
--- /dev/null
+++ b/packages/core/src/Chat/ChatLayoutScrollButton.doc.mjs
@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatLayoutScrollButton',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Layout Scroll Button',
+ isHiddenFromOverview: true,
+ description: 'Floating scroll-to-bottom button that appears when the user scrolls away from the latest messages. It fades in as a compact icon button and expands to show a label when new messages arrive. XDSChatLayout renders this by default — pass a custom element to the scrollButton prop to override, or null to hide it entirely.',
+ props: [
+ {
+ name: 'isVisible',
+ type: 'boolean',
+ description: 'Whether the button is visible. Bind to a scroll-position check so the button only appears when the user has scrolled up.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Optional label that expands the button (e.g. "New messages"). Use to signal unread content below the fold.',
+ },
+ {
+ name: 'onClick',
+ type: '() => void',
+ description: 'Click handler — typically scrolls to bottom and dismisses the new message indicator.',
+ required: true,
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatLayoutScrollButton',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Layout Scroll Button',
+ description: '可组合的滚动到底部按钮。可见时淡入,提供标签时展开。',
+ propDescriptions: {
+ isVisible: '按钮是否可见。',
+ label: '可选标签 — 展开按钮(如"新消息")。',
+ onClick: '点击处理器。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatLayoutScrollButton',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Layout Scroll Button',
+ description: 'floating scroll-to-bottom btn; fades in when scrolled up, expands w/ label for new msgs. Default in XDSChatLayout; override via scrollButton prop.',
+ propDescriptions: {
+ isVisible: 'btn visibility — bind to scroll-position check',
+ label: 'optional label; expands btn (e.g. "New messages")',
+ onClick: 'click handler',
+ },
+};
diff --git a/packages/core/src/Chat/ChatMessage.doc.mjs b/packages/core/src/Chat/ChatMessage.doc.mjs
new file mode 100644
index 0000000000..ea045b324a
--- /dev/null
+++ b/packages/core/src/Chat/ChatMessage.doc.mjs
@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatMessage',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Message',
+ description: 'Sender context wrapper — handles avatar, name, metadata, and alignment based on sender role.',
+ props: [
+ {
+ name: 'sender',
+ type: "'user' | 'assistant' | 'system'",
+ description: 'Who sent this message — controls alignment and layout.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Free-form content: bubbles, asset lists, tool calls, images.',
+ required: true,
+ },
+ {
+ name: 'avatar',
+ type: 'ReactNode',
+ description: 'Avatar element rendered beside the message. Typically XDSAvatar.',
+ slotElements: [
+ {
+ __element: 'XDSAvatar',
+ props: {
+ name: 'User',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'name',
+ type: 'ReactNode',
+ description: "Sender name rendered above the message body. Use when the first child is raw content (not a bubble). If the first child is a bubble, put the name on the bubble's `name` prop instead.",
+ },
+ {
+ name: 'metadata',
+ type: 'ReactNode',
+ description: "Metadata rendered below the message body. Use when the last child is raw content (not a bubble). If the last child is a bubble, put metadata on the bubble's `metadata` prop instead.",
+ slotElements: [
+ {
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Metadata',
+ },
+ ],
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Visual density. Inherited from list context if not set.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatMessage',
+ displayName: 'Chat Message',
+ description: '发送者上下文包装器,根据发送者角色处理头像、名称、元数据和对齐方式。',
+ propDescriptions: {
+ sender: '消息发送者,控制对齐和布局。',
+ children: '自由内容:气泡、资源列表、工具调用、图片。',
+ avatar: '消息旁边渲染的头像元素。通常是 XDSAvatar。',
+ name: '消息正文上方渲染的发送者名称。当第一个子元素不是气泡时使用。',
+ metadata: '消息正文下方渲染的元数据。当最后一个子元素不是气泡时使用。',
+ density: '视觉密度。未设置时从列表上下文继承。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatMessage',
+ displayName: 'Chat Message',
+ description: 'sender context wrapper; handles avatar+name+metadata+alignment by sender role',
+ propDescriptions: {
+ sender: 'who sent; controls alignment+layout',
+ children: 'free-form: bubbles, assets, tool calls, images',
+ avatar: 'avatar element beside msg; typically XDSAvatar',
+ name: 'sender name above body; use when first child is raw (not bubble)',
+ displayName: 'sender name above body; use when first child is raw (not bubble)',
+ metadata: 'metadata below body; use when last child is raw (not bubble)',
+ density: 'visual density; inherited from list context if unset',
+ },
+};
diff --git a/packages/core/src/Chat/ChatMessageBubble.doc.mjs b/packages/core/src/Chat/ChatMessageBubble.doc.mjs
new file mode 100644
index 0000000000..5810a14c75
--- /dev/null
+++ b/packages/core/src/Chat/ChatMessageBubble.doc.mjs
@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatMessageBubble',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Message Bubble',
+ isHiddenFromOverview: true,
+ description: 'Styled content container — the chat “bubble.” Reads sender from parent XDSChatMessage context to auto-style the background. Use filled for standard messages and ghost when content needs alignment without a visible boundary. Supports name/metadata slots aligned with bubble padding, and multi-bubble grouping via the group prop for consecutive messages from the same sender.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Bubble content — text, XDSMarkdown, or any ReactNode.',
+ required: true,
+ },
+ {
+ name: 'variant',
+ type: "'filled' | 'ghost'",
+ description: "Visual variant. 'filled' renders sender-colored background (default). 'ghost' renders transparent background but keeps padding for alignment.",
+ default: "'filled'",
+ },
+ {
+ name: 'name',
+ type: 'ReactNode',
+ description: "Sender name rendered above the bubble, aligned with bubble text padding. Use on the first bubble in a message. If the first content is raw (no bubble), use XDSChatMessage's `name` prop instead.",
+ },
+ {
+ name: 'metadata',
+ type: 'ReactNode',
+ description: "Metadata content rendered below the bubble, aligned with bubble text padding. Use on the last bubble in a message. If the last content is raw (no bubble), use XDSChatMessage's `metadata` prop instead.",
+ slotElements: [
+ {
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Metadata',
+ },
+ ],
+ },
+ {
+ name: 'group',
+ type: "'first' | 'middle' | 'last'",
+ description: 'Position within a multi-bubble group. Controls corner radius reduction on the sender side. Leave unset for standalone bubbles (full radius).',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatMessageBubble',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Message Bubble',
+ description: '样式化的气泡容器,从父上下文读取发送者信息进行自动样式化。支持 name/metadata 插槽、多气泡分组和透明变体。',
+ propDescriptions: {
+ children: '气泡内容:文本、XDSMarkdown 或任何 ReactNode。',
+ variant: "视觉变体。'filled' 渲染发送者颜色背景,'ghost' 渲染透明背景但保持填充对齐。",
+ name: '气泡上方渲染的发送者名称,与气泡文本内边距对齐。用于消息中的第一个气泡。',
+ metadata: '气泡下方渲染的元数据内容,与气泡文本内边距对齐。用于消息中的最后一个气泡。',
+ group: '多气泡组中的位置。控制发送者侧的圆角缩减。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatMessageBubble',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Message Bubble',
+ description: 'styled bubble container; reads sender from context; supports name/metadata slots, group corners, ghost variant',
+ propDescriptions: {
+ children: 'bubble content: text, XDSMarkdown, any ReactNode',
+ variant: 'filled (sender bg) or ghost (transparent, keeps padding)',
+ name: 'sender name above bubble, aligned w/ bubble padding',
+ displayName: 'sender name above bubble, aligned w/ bubble padding',
+ metadata: 'metadata below bubble, aligned w/ bubble padding',
+ group: 'position in multi-bubble group; controls corner radius reduction',
+ },
+};
diff --git a/packages/core/src/Chat/ChatMessageList.doc.mjs b/packages/core/src/Chat/ChatMessageList.doc.mjs
new file mode 100644
index 0000000000..00ca9a8c7c
--- /dev/null
+++ b/packages/core/src/Chat/ChatMessageList.doc.mjs
@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatMessageList',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Message List',
+ isHiddenFromOverview: true,
+ description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full.`,
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Message elements — typically XDSChatMessage or XDSChatSystemMessage.',
+ required: true,
+ },
+ {
+ name: 'emptyState',
+ type: 'ReactNode',
+ description: 'Content shown when the list has no messages.',
+ slotElements: [
+ {
+ __element: 'XDSEmptyState',
+ props: {
+ title: 'No items',
+ description: 'Nothing to show.',
+ },
+ },
+ ],
+ },
+ {
+ name: 'scrollToTopAction',
+ type: '() => Promise<void>',
+ description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition — shows a spinner at the top while pending.',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Visual density — flows to child messages via context.',
+ default: "'balanced'",
+ },
+ {
+ name: 'gap',
+ type: 'SpacingStep',
+ description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatMessageList',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Message List',
+ description: '消息展示容器,支持密度上下文和无限滚动。自动滚动由 XDSChatLayout 管理。',
+ propDescriptions: {
+ children: '消息元素,通常是 XDSChatMessage 或 XDSChatSystemMessage。',
+ emptyState: '列表无消息时显示的内容。',
+ scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
+ density: '视觉密度,通过上下文传递给子消息。',
+ gap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatMessageList',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Message List',
+ description: 'presentational msg container w/ density context + infinite scroll; auto-scroll owned by XDSChatLayout',
+ propDescriptions: {
+ children: 'msg elements (XDSChatMessage or XDSChatSystemMessage)',
+ emptyState: 'content when no msgs',
+ scrollToTopAction: 'async action at scroll top; load older msgs',
+ density: 'visual density; flows to children via context',
+ gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
+ },
+};
diff --git a/packages/core/src/Chat/ChatMessageMetadata.doc.mjs b/packages/core/src/Chat/ChatMessageMetadata.doc.mjs
new file mode 100644
index 0000000000..98fdfc7887
--- /dev/null
+++ b/packages/core/src/Chat/ChatMessageMetadata.doc.mjs
@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatMessageMetadata',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Message Metadata',
+ description: 'Composable metadata row for chat messages. Renders timestamp, footer content, and delivery status in a single row. Direction reverses for user sender. Renders nothing if all props are empty.',
+ props: [
+ {
+ name: 'timestamp',
+ type: 'ReactNode',
+ description: 'Timestamp content — a string or XDSTimestamp component.',
+ slotElements: [
+ {
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Just now',
+ },
+ ],
+ },
+ {
+ name: 'footer',
+ type: 'ReactNode',
+ description: 'Footer content — model info, reaction buttons, copy button.',
+ slotElements: [
+ {
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Footer content',
+ },
+ ],
+ },
+ {
+ name: 'status',
+ type: "'sending' | 'sent' | 'delivered' | 'read' | 'error'",
+ description: 'Message delivery status. Shows icon + label.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatMessageMetadata',
+ displayName: 'Chat Message Metadata',
+ description: '可组合的消息元数据行。渲染时间戳、页脚内容和发送状态。用户消息方向反转。',
+ propDescriptions: {
+ timestamp: '时间戳内容 — 字符串或 XDSTimestamp 组件。',
+ footer: '页脚内容 — 模型信息、反应按钮、复制按钮。',
+ status: '消息发送状态。显示图标和标签。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatMessageMetadata',
+ displayName: 'Chat Message Metadata',
+ description: 'composable metadata row; renders timestamp · footer · status; reverses for user sender',
+ propDescriptions: {
+ timestamp: 'timestamp content; string or XDSTimestamp',
+ footer: 'footer content; model info, reaction btns, copy btn',
+ status: 'delivery status; shows icon+label',
+ },
+};
diff --git a/packages/core/src/Chat/ChatSendButton.doc.mjs b/packages/core/src/Chat/ChatSendButton.doc.mjs
new file mode 100644
index 0000000000..35b33dfe4d
--- /dev/null
+++ b/packages/core/src/Chat/ChatSendButton.doc.mjs
@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatSendButton',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Send Button',
+ isHiddenFromOverview: true,
+ description: 'Circular send/stop toggle button for the chat composer. Place it inside XDSChatComposer where it reads context automatically — no wiring needed. When streaming starts, the button switches from a primary send icon to a secondary stop icon. Override any context value via props for standalone or custom usage.',
+ props: [
+ {
+ name: 'isStopShown',
+ type: 'boolean',
+ description: 'Whether the stop button is shown. Defaults to context value.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the send button is disabled. Defaults to !canSend from context.',
+ },
+ {
+ name: 'onSend',
+ type: '() => void',
+ description: 'Called when the user clicks send. Defaults to context onSubmit.',
+ },
+ {
+ name: 'onStop',
+ type: '() => void',
+ description: 'Called when the user clicks stop during streaming. Defaults to context onStop.',
+ },
+ {
+ name: 'sendIcon',
+ type: 'ReactNode',
+ description: 'Custom icon for the send state. Defaults to arrowUp from icon registry.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'stopIcon',
+ type: 'ReactNode',
+ description: 'Custom icon for the stop state. Defaults to stop from icon registry.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Button size.',
+ default: "'md'",
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatSendButton',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Send Button',
+ description: '编写器的圆形发送/停止切换按钮。默认从 XDSChatComposerContext 读取状态,在 XDSChatComposer 内自动工作。所有上下文值均可通过 props 覆盖以用于独立使用。',
+ propDescriptions: {
+ isStopShown: '是否显示停止按钮。默认使用上下文值。',
+ isDisabled: '发送按钮是否禁用。默认使用上下文的 !canSend。',
+ onSend: '用户点击发送时调用。默认使用上下文的 onSubmit。',
+ onStop: '流式响应期间用户点击停止时调用。默认使用上下文的 onStop。',
+ sendIcon: '发送状态的自定义图标。默认使用图标注册表的 arrowUp。',
+ stopIcon: '停止状态的自定义图标。默认使用图标注册表的 stop。',
+ size: '按钮大小。',
+ xstyle: '额外的 StyleX 样式。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatSendButton',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Send Button',
+ description: 'circular send/stop toggle btn for composer; reads XDSChatComposerContext; all context vals overridable via props',
+ propDescriptions: {
+ isStopShown: 'stop button visibility; defaults to context',
+ isDisabled: 'disabled; defaults to !canSend from context',
+ onSend: 'send click handler; defaults to context onSubmit',
+ onStop: 'stop click handler; defaults to context onStop',
+ sendIcon: 'custom send icon; default arrowUp from registry',
+ stopIcon: 'custom stop icon; default stop from registry',
+ size: 'btn size',
+ xstyle: 'additional StyleX styles',
+ },
+};
diff --git a/packages/core/src/Chat/ChatSystemMessage.doc.mjs b/packages/core/src/Chat/ChatSystemMessage.doc.mjs
new file mode 100644
index 0000000000..6cfbfbb656
--- /dev/null
+++ b/packages/core/src/Chat/ChatSystemMessage.doc.mjs
@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatSystemMessage',
+ subComponentOf: 'Chat',
+ displayName: 'Chat System Message',
+ description: 'Centered system message for non-sender content like date separators, membership changes, and status notices. It is not a chat bubble — it has no avatar, no alignment, and no sender context. Use the divider variant for temporal breaks and default for inline status updates.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'System message content — a short, factual string like a date, a join/leave notice, or a status change.',
+ required: true,
+ },
+ {
+ name: 'variant',
+ type: "'default' | 'divider'",
+ description: "Visual variant. 'default' renders centered text. 'divider' adds horizontal lines on each side via XDSDivider — use for date separators and section breaks.",
+ default: "'default'",
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Leading icon that reinforces the message type. Wrap in XDSIcon for consistent sizing. Use for membership changes, encryption notices, or AI activity.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatSystemMessage',
+ displayName: 'Chat System Message',
+ description: '居中的系统消息,用于日期分隔、成员变更和状态通知等非发送者内容。没有头像、对齐或气泡。使用 divider 变体做时间分隔,default 做内联状态更新。',
+ propDescriptions: {
+ children: '系统消息内容 — 简短的事实性文本,如日期、加入/离开通知或状态变更。',
+ variant: "视觉变体。'default' 渲染居中文本。'divider' 通过 XDSDivider 在两侧添加水平线 — 用于日期分隔和段落分隔。",
+ icon: '增强消息类型辨识度的前置图标。使用 XDSIcon 包裹以获得一致的尺寸。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatSystemMessage',
+ displayName: 'Chat System Message',
+ description: 'centered non-sender msg; divider variant for date breaks, default for status notices; supports leading icon',
+ propDescriptions: {
+ children: 'short factual text: date, join/leave, status change',
+ variant: 'default=centered text, divider=horizontal lines via XDSDivider for date/section breaks',
+ icon: 'leading icon reinforcing msg type; wrap in XDSIcon',
+ },
+};
diff --git a/packages/core/src/Chat/ChatTokenizedText.doc.mjs b/packages/core/src/Chat/ChatTokenizedText.doc.mjs
new file mode 100644
index 0000000000..b1d4be37ee
--- /dev/null
+++ b/packages/core/src/Chat/ChatTokenizedText.doc.mjs
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ChatTokenizedText',
+ subComponentOf: 'Chat',
+ displayName: 'Chat Tokenized Text',
+ isHiddenFromOverview: true,
+ description: 'Renders a text string with token patterns replaced by inline XDSBadge components. Wrap any message body inside XDSChatMessageBubble to turn raw @mentions, #tags, or /commands into styled badges. When no tokens match or none are provided, the text renders as-is — so you can use ChatTokenizedText unconditionally on every message.',
+ props: [
+ {
+ name: 'children',
+ type: 'string',
+ description: "The plain text message containing serialized token values. Patterns matching a token's value are replaced with badge components inline.",
+ required: true,
+ },
+ {
+ name: 'tokens',
+ type: 'XDSChatComposerToken[]',
+ description: 'Token definitions — same type returned by trigger onSelect. Each token has a value (the string to match), label (display text), and optional variant and icon. Uses the same type as the composer input, so token definitions work for both input and display.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ChatTokenizedText',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Tokenized Text',
+ description: '渲染带有标记模式的文本,将匹配的模式替换为内联 XDSBadge 组件。在 XDSChatMessageBubble 内使用,将 @提及、#标签或 /命令显示为样式化徽章。未提供标记时以纯文本渲染,因此可以无条件使用。',
+ propDescriptions: {
+ children: '包含序列化标记值的纯文本消息。匹配标记值的模式将被替换为内联徽章组件。',
+ tokens: '标记定义 — 与触发器 onSelect 返回的类型相同。每个包含 value(匹配字符串)、label(显示文本)以及可选的 variant 和 icon。',
+ },
+};
+
+export const docsDense = {
+ name: 'ChatTokenizedText',
+ isHiddenFromOverview: true,
+ displayName: 'Chat Tokenized Text',
+ description: 'renders text w/ token patterns replaced by inline badges; use in bubble for @mentions, #tags, /commands; degrades to plain text when no tokens match',
+ propDescriptions: {
+ children: 'plain text msg w/ serialized token values; matching patterns become inline badges',
+ tokens: 'token defs (same type as composer input): value+label+variant+icon',
+ },
+};
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index 3f6b887670..bfbff62111 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -9,141 +9,93 @@ export const docs = {
category: 'Data Input',
isHiddenFromOverview: true,
keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],
- components: [
+ description: 'Checkbox group container with field integration for label, description, and status.',
+ props: [
{
- name: 'XDSCheckboxList',
- isHiddenFromOverview: true,
- displayName: 'Checkbox List',
- description:
- 'Checkbox group container with field integration for label, description, and status.', props: [
- {
- name: 'label',
- type: 'string',
- description:
- 'Label text for the checkbox group (always rendered for accessibility).',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'XDSCheckboxListItem elements.',
- slotElements: [{__element: 'XDSCheckboxListItem', props: {label: 'Option', value: 'option'}}],
- required: true,
- },
- {
- name: 'value',
- type: 'string[]',
- description: 'The currently selected values (collection mode).',
- },
- {
- name: 'onChange',
- type: '(values: string[]) => void',
- description: 'Callback fired when the selected values change.',
- },
- {
- name: 'changeAction',
- type: '(values: string[]) => void | Promise<void>',
- description: 'Async action on change with optimistic updates.',
- },
- {
- name: 'isLoading',
- type: 'boolean',
- description: 'External loading state.',
- default: 'false',
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: 'Whether to visually hide the label.',
- default: 'false',
- },
- {
- name: 'description',
- type: 'string',
- description: 'Description text displayed below the label.',
- },
- {
- name: 'density',
- type: "'compact' | 'balanced' | 'spacious'",
- description: 'Spacing density for list items.',
- default: "'balanced'",
- },
- {
- name: 'hasDividers',
- type: 'boolean',
- description: 'Whether to show dividers between items.',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether all checkbox items are disabled.',
- default: 'false',
- },
- {
- name: 'status',
- type: 'XDSInputStatus',
- description: 'Status indicator ({ type, message }).',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
- },
- ],
+ name: 'label',
+ type: 'string',
+ description: 'Label text for the checkbox group (always rendered for accessibility).',
+ required: true,
},
{
- name: 'XDSCheckboxListItem',
- isHiddenFromOverview: true,
- displayName: 'Checkbox List Item',
- description:
- 'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside XDSCheckboxList) or standalone mode (inside XDSList).',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Primary text label for the item.',
- required: true,
- },
- {
- name: 'value',
- type: 'string',
- description: 'Identity key (required inside XDSCheckboxList).',
- },
- {
- name: 'description',
- type: 'string',
- description: 'Secondary text below the label.',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description: 'Content rendered after the label area.',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
- },
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSCheckboxListItem elements.',
+ slotElements: [
{
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether this individual item is disabled.',
- default: 'false',
- },
- {
- name: 'isChecked',
- type: "boolean | 'indeterminate'",
- description: 'Direct checked state (standalone mode only).',
- },
- {
- name: 'onCheck',
- type: '(checked: boolean) => void',
- description: 'Direct check handler (standalone mode only).',
+ __element: 'XDSCheckboxListItem',
+ props: {
+ label: 'Option',
+ value: 'option',
+ },
},
],
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string[]',
+ description: 'The currently selected values (collection mode).',
+ },
+ {
+ name: 'onChange',
+ type: '(values: string[]) => void',
+ description: 'Callback fired when the selected values change.',
+ },
+ {
+ name: 'changeAction',
+ type: '(values: string[]) => void | Promise<void>',
+ description: 'Async action on change with optimistic updates.',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: 'External loading state.',
+ default: 'false',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Whether to visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Spacing density for list items.',
+ default: "'balanced'",
+ },
+ {
+ name: 'hasDividers',
+ type: 'boolean',
+ description: 'Whether to show dividers between items.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether all checkbox items are disabled.',
+ default: 'false',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description: 'Status indicator ({ type, message }).',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
},
],
+ components: [
+ {name: 'XDSCheckboxListItem'},
+ ],
usage: {
description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
bestPractices: [
@@ -156,10 +108,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'CheckboxList',
- displayName: 'Checkbox List',
usage: {
description: 'CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.',
bestPractices: [
@@ -170,44 +120,6 @@ export const docsZh = {
{ guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
],
},
- components: [
- {
- name: 'XDSCheckboxList',
- isHiddenFromOverview: true,
- displayName: 'Checkbox List',
- description: '复选框组容器,集成字段功能,支持标签、描述和状态。',
- props: [
- {name: 'label', type: 'string', description: '复选框组的标签文本(始终渲染以确保无障碍可访问性)。', required: true},
- {name: 'children', type: 'ReactNode', description: 'XDSCheckboxListItem 元素。', required: true},
- {name: 'value', type: 'string[]', description: '当前选中的值(集合模式)。'},
- {name: 'onChange', type: '(values: string[]) => void', description: '选中值变更时触发的回调函数。'},
- {name: 'changeAction', type: '(values: string[]) => void | Promise<void>', description: '变更时的异步操作,配合乐观更新。'},
- {name: 'isLoading', type: 'boolean', description: '外部加载状态。', default: 'false'},
- {name: 'isLabelHidden', type: 'boolean', description: '是否在视觉上隐藏标签。', default: 'false'},
- {name: 'description', type: 'string', description: '显示在标签下方的描述文本。'},
- {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: '列表项的间距密度。', default: "'balanced'"},
- {name: 'hasDividers', type: 'boolean', description: '是否在选项之间显示分隔线。', default: 'false'},
- {name: 'isDisabled', type: 'boolean', description: '是否禁用所有复选框选项。', default: 'false'},
- {name: 'status', type: 'XDSInputStatus', description: '状态指示器({ type, message })。'},
- {name: 'xstyle', type: 'StyleXStyles', description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。'},
- ],
- },
- {
- name: 'XDSCheckboxListItem',
- isHiddenFromOverview: true,
- displayName: 'Checkbox List Item',
- description: '单个复选框选项,包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',
- props: [
- {name: 'label', type: 'string', description: '选项的主要文本标签。', required: true},
- {name: 'value', type: 'string', description: '标识键(在 XDSCheckboxList 内为必填)。'},
- {name: 'description', type: 'string', description: '标签下方的辅助文本。'},
- {name: 'endContent', type: 'ReactNode', description: '在标签区域后渲染的内容。'},
- {name: 'isDisabled', type: 'boolean', description: '是否禁用此单个选项。', default: 'false'},
- {name: 'isChecked', type: "boolean | 'indeterminate'", description: '直接选中状态(仅独立模式)。'},
- {name: 'onCheck', type: '(checked: boolean) => void', description: '直接选中处理器(仅独立模式)。'},
- ],
- },
- ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -224,44 +136,4 @@ export const docsDense = {
{ guidance: false, description: 'Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.' },
],
},
- components: [
- {
- name: 'XDSCheckboxList',
- isHiddenFromOverview: true,
- displayName: 'Checkbox List',
- description:
- 'Checkbox group container w/ field integration for label, description, status.',
- propDescriptions: {
- label: 'Label text for checkbox group (always rendered for accessibility).',
- children: 'XDSCheckboxListItem elements.',
- value: 'Currently selected values (collection mode).',
- onChange: 'Callback fired when selected values change.',
- changeAction: 'Async action on change w/ optimistic updates.',
- isLoading: 'External loading state.',
- isLabelHidden: 'Whether to visually hide label.',
- description: 'Description text below label.',
- density: 'Spacing density for list items.',
- hasDividers: 'Whether to show dividers between items.',
- isDisabled: 'Whether all checkbox items disabled.',
- status: 'Status indicator ({ type, message }).',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSCheckboxListItem',
- isHiddenFromOverview: true,
- displayName: 'Checkbox List Item',
- description:
- 'Individual checkbox item w/ label, description, end content slot.',
- propDescriptions: {
- label: 'Primary text label for item.',
- value: 'Identity key (required inside XDSCheckboxList).',
- description: 'Secondary text below label.',
- endContent: 'Content rendered after label area.',
- isDisabled: 'Whether this individual item disabled.',
- isChecked: 'Direct checked state (standalone mode only).',
- onCheck: 'Direct check handler (standalone mode only).',
- },
- },
- ],
};
diff --git a/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs
new file mode 100644
index 0000000000..e55fbc1f3f
--- /dev/null
+++ b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs
@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CheckboxListItem',
+ subComponentOf: 'CheckboxList',
+ displayName: 'Checkbox List Item',
+ isHiddenFromOverview: true,
+ description: 'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside XDSCheckboxList) or standalone mode (inside XDSList).',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Primary text label for the item.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Identity key (required inside XDSCheckboxList).',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Secondary text below the label.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Content rendered after the label area.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
+ },
+ {
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
+ },
+ ],
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether this individual item is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isChecked',
+ type: "boolean | 'indeterminate'",
+ description: 'Direct checked state (standalone mode only).',
+ },
+ {
+ name: 'onCheck',
+ type: '(checked: boolean) => void',
+ description: 'Direct check handler (standalone mode only).',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'CheckboxListItem',
+ isHiddenFromOverview: true,
+ displayName: 'Checkbox List Item',
+ description: '单个复选框选项,包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '选项的主要文本标签。',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: '标识键(在 XDSCheckboxList 内为必填)。',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: '标签下方的辅助文本。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '在标签区域后渲染的内容。',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '是否禁用此单个选项。',
+ default: 'false',
+ },
+ {
+ name: 'isChecked',
+ type: "boolean | 'indeterminate'",
+ description: '直接选中状态(仅独立模式)。',
+ },
+ {
+ name: 'onCheck',
+ type: '(checked: boolean) => void',
+ description: '直接选中处理器(仅独立模式)。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'CheckboxListItem',
+ isHiddenFromOverview: true,
+ displayName: 'Checkbox List Item',
+ description: 'Individual checkbox item w/ label, description, end content slot.',
+ propDescriptions: {
+ label: 'Primary text label for item.',
+ value: 'Identity key (required inside XDSCheckboxList).',
+ description: 'Secondary text below label.',
+ endContent: 'Content rendered after label area.',
+ isDisabled: 'Whether this individual item disabled.',
+ isChecked: 'Direct checked state (standalone mode only).',
+ onCheck: 'Direct check handler (standalone mode only).',
+ },
+};
diff --git a/packages/core/src/CodeBlock/Code.doc.mjs b/packages/core/src/CodeBlock/Code.doc.mjs
new file mode 100644
index 0000000000..a194df7151
--- /dev/null
+++ b/packages/core/src/CodeBlock/Code.doc.mjs
@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Code',
+ subComponentOf: 'CodeBlock',
+ displayName: 'Code',
+ description: 'Inline code element. Renders a styled <code> with monospace font and muted background. For fenced blocks, use XDSCodeBlock.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Code content.',
+ required: true,
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'CSS class name for the root element. Prefer xstyle for styling.',
+ },
+ {
+ name: 'style',
+ type: 'CSSProperties',
+ description: 'Inline styles. Prefer xstyle for StyleX-optimized styling.',
+ },
+ {
+ name: 'data-testid',
+ type: 'string',
+ description: 'Test selector for automated testing frameworks.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'Code',
+ displayName: 'Code',
+ description: '内联代码元素。渲染带等宽字体和低调背景的 <code>。如需围栏代码块,请使用 XDSCodeBlock。',
+ propDescriptions: {
+ children: '代码内容。',
+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
+ className: '根元素的 CSS 类名。优先使用 xstyle。',
+ style: '内联样式。优先使用 xstyle。',
+ "data-testid": '自动化测试框架的测试选择器。',
+ },
+};
+
+export const docsDense = {
+ name: 'Code',
+ displayName: 'Code',
+ description: 'inline code element; styled <code> w/ monospace+muted bg; for prose',
+ propDescriptions: {
+ children: 'code content',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ className: 'CSS class for root; prefer xstyle',
+ style: 'inline styles; prefer xstyle',
+ "data-testid": 'test selector',
+ },
+};
diff --git a/packages/core/src/CodeBlock/CodeBlock.doc.mjs b/packages/core/src/CodeBlock/CodeBlock.doc.mjs
index 53424c4ced..e8ed806470 100644
--- a/packages/core/src/CodeBlock/CodeBlock.doc.mjs
+++ b/packages/core/src/CodeBlock/CodeBlock.doc.mjs
@@ -9,46 +9,122 @@ export const docs = {
'code', 'syntax', 'highlight', 'snippet', 'prism', 'shiki',
'pre', 'monospace', 'codeblock', 'inline',
],
- components: [
+ description: 'Fenced code block with syntax highlighting. Use for multi-line code snippets.',
+ props: [
+ {
+ name: 'code',
+ type: 'string',
+ description: 'The code string to display.',
+ required: true,
+ },
+ {
+ name: 'language',
+ type: 'string',
+ description: 'Language for syntax highlighting. Use "plaintext" to disable.',
+ default: "'plaintext'",
+ },
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Filename or label shown in the header bar.',
+ },
+ {
+ name: 'hasLanguageLabel',
+ type: 'boolean',
+ description: 'Show the language name in the header bar. Hidden when language is "plaintext".',
+ default: 'true',
+ },
+ {
+ name: 'hasLineNumbers',
+ type: 'boolean',
+ description: 'Show a line number gutter.',
+ default: 'false',
+ },
+ {
+ name: 'highlightLines',
+ type: 'number[]',
+ description: '1-indexed line numbers to highlight.',
+ },
+ {
+ name: 'hasCopyButton',
+ type: 'boolean',
+ description: 'Show a copy-to-clipboard button.',
+ default: 'true',
+ },
+ {
+ name: 'onCopy',
+ type: '() => void',
+ description: 'Callback after the code is copied.',
+ },
+ {
+ name: 'isWrapped',
+ type: 'boolean',
+ description: 'Wrap long lines instead of enabling horizontal scroll.',
+ default: 'false',
+ },
+ {
+ name: 'maxHeight',
+ type: 'number | string',
+ description: 'Max height before the block scrolls vertically.',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Text size variant.',
+ default: "'md'",
+ },
+ {
+ name: 'width',
+ type: 'string',
+ description: "Width of the code block. Any CSS width value. 'fit-content' (default) shrinks to longest line. '100%' fills parent width.",
+ default: "'fit-content'",
+ },
{
- name: 'XDSCodeBlock',
- displayName: 'Code Block',
- description: 'Fenced code block with syntax highlighting. Use for multi-line code snippets.',
- props: [
- {name: 'code', type: 'string', description: 'The code string to display.', required: true},
- {name: 'language', type: 'string', description: 'Language for syntax highlighting. Use "plaintext" to disable.', default: "'plaintext'"},
- {name: 'title', type: 'string', description: 'Filename or label shown in the header bar.'},
- {name: 'hasLanguageLabel', type: 'boolean', description: 'Show the language name in the header bar. Hidden when language is "plaintext".', default: 'true'},
- {name: 'hasLineNumbers', type: 'boolean', description: 'Show a line number gutter.', default: 'false'},
- {name: 'highlightLines', type: 'number[]', description: '1-indexed line numbers to highlight.'},
- {name: 'hasCopyButton', type: 'boolean', description: 'Show a copy-to-clipboard button.', default: 'true'},
- {name: 'onCopy', type: '() => void', description: 'Callback after the code is copied.'},
- {name: 'isWrapped', type: 'boolean', description: 'Wrap long lines instead of enabling horizontal scroll.', default: 'false'},
- {name: 'maxHeight', type: 'number | string', description: 'Max height before the block scrolls vertically.'},
- {name: 'size', type: "'sm' | 'md'", description: 'Text size variant.', default: "'md'"},
- {name: 'width', type: "string", description: "Width of the code block. Any CSS width value. 'fit-content' (default) shrinks to longest line. '100%' fills parent width.", default: "'fit-content'"},
- {name: 'container', type: "'card' | 'section'", description: "Container presentation style. 'card' (default): border and radius with the muted syntax background for a standalone card look. 'section': no border or radius and a transparent background so the block blends into the card or panel it's embedded in.", default: "'card'"},
- {name: 'tokenizer', type: '(code: string, language: string) => Array<{type: string; start: number; end: number}>', description: 'Custom tokenizer override for unsupported languages.'},
- {name: 'isCollapsible', type: 'boolean', description: 'Allow collapsing the code body into just the header bar. Starts expanded; the header becomes clickable to toggle. Only shows the toggle when the code exceeds collapsibleThreshold lines.', default: 'false'},
- {name: 'collapsibleThreshold', type: 'number', description: 'Minimum number of lines before the collapse toggle appears. Below this threshold the code block renders normally even when isCollapsible is true.', default: '10'},
- {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},
- {name: 'className', type: 'string', description: 'CSS class name for the root element. Prefer xstyle for styling.'},
- {name: 'style', type: 'CSSProperties', description: 'Inline styles. Prefer xstyle for StyleX-optimized styling.'},
- {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
- ],
- },
- {
- name: 'XDSCode',
- displayName: 'Code',
- description: 'Inline code element. Renders a styled <code> with monospace font and muted background. For fenced blocks, use XDSCodeBlock.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'Code content.', required: true},
- {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},
- {name: 'className', type: 'string', description: 'CSS class name for the root element. Prefer xstyle for styling.'},
- {name: 'style', type: 'CSSProperties', description: 'Inline styles. Prefer xstyle for StyleX-optimized styling.'},
- {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
- ],
+ name: 'container',
+ type: "'card' | 'section'",
+ description: "Container presentation style. 'card' (default): border and radius with the muted syntax background for a standalone card look. 'section': no border or radius and a transparent background so the block blends into the card or panel it's embedded in.",
+ default: "'card'",
},
+ {
+ name: 'tokenizer',
+ type: '(code: string, language: string) => Array<{type: string; start: number; end: number}>',
+ description: 'Custom tokenizer override for unsupported languages.',
+ },
+ {
+ name: 'isCollapsible',
+ type: 'boolean',
+ description: 'Allow collapsing the code body into just the header bar. Starts expanded; the header becomes clickable to toggle. Only shows the toggle when the code exceeds collapsibleThreshold lines.',
+ default: 'false',
+ },
+ {
+ name: 'collapsibleThreshold',
+ type: 'number',
+ description: 'Minimum number of lines before the collapse toggle appears. Below this threshold the code block renders normally even when isCollapsible is true.',
+ default: '10',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'CSS class name for the root element. Prefer xstyle for styling.',
+ },
+ {
+ name: 'style',
+ type: 'CSSProperties',
+ description: 'Inline styles. Prefer xstyle for StyleX-optimized styling.',
+ },
+ {
+ name: 'data-testid',
+ type: 'string',
+ description: 'Test selector for automated testing frameworks.',
+ },
+ ],
+ components: [
+ {name: 'XDSCode'},
],
playground: {
defaults: {
@@ -93,47 +169,6 @@ export const docsZh = {
{ guidance: false, description: 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.' },
],
},
- components: [
- {
- name: 'XDSCodeBlock',
- displayName: 'Code Block',
- description: '带语法高亮的围栏代码块。用于多行代码片段。',
- propDescriptions: {
- code: '要显示的代码字符串。',
- language: '语法高亮语言。使用 "plaintext" 禁用高亮。',
- title: '在标题栏中显示的文件名或标签。',
- hasLanguageLabel: '在标题栏中显示语言名称。language 为 "plaintext" 时隐藏。',
- hasLineNumbers: '显示行号栏。',
- highlightLines: '需要高亮的 1-indexed 行号。',
- hasCopyButton: '显示复制到剪贴板按钮。',
- onCopy: '代码复制后的回调函数。',
- isWrapped: '换行显示长行,而非启用水平滚动。',
- maxHeight: '代码块垂直滚动前的最大高度。',
- size: '文字大小变体。',
- width: "代码块宽度。接受任何CSS宽度值。'fit-content'(默认)适应最长行宽度;'100%' 填满父容器宽度。",
- container: "容器展示样式。'card'(默认)=带边框和圆角及柔和背景;'section'=无边框圆角且背景透明,融入所嵌入的卡片或面板。",
- tokenizer: '用于不支持语言的自定义分词器。',
- isCollapsible: '允许将代码折叠为仅标题栏。当代码超过 collapsibleThreshold 行时显示切换按钮。',
- collapsibleThreshold: '折叠切换出现前的最小行数。低于此阈值时即使 isCollapsible 为 true 也正常渲染。',
- xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
- className: '根元素的 CSS 类名。优先使用 xstyle。',
- style: '内联样式。优先使用 xstyle。',
- 'data-testid': '自动化测试框架的测试选择器。',
- },
- },
- {
- name: 'XDSCode',
- displayName: 'Code',
- description: '内联代码元素。渲染带等宽字体和低调背景的 <code>。如需围栏代码块,请使用 XDSCodeBlock。',
- propDescriptions: {
- children: '代码内容。',
- xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
- className: '根元素的 CSS 类名。优先使用 xstyle。',
- style: '内联样式。优先使用 xstyle。',
- 'data-testid': '自动化测试框架的测试选择器。',
- },
- },
- ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -149,45 +184,4 @@ export const docsDense = {
{guidance: false, description: 'Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively.'},
],
},
- components: [
- {
- name: 'XDSCodeBlock',
- displayName: 'Code Block',
- description: 'fenced code block w/ syntax highlighting; for multi-line snippets',
- propDescriptions: {
- code: 'code string to display',
- language: 'highlight language; "plaintext" disables',
- title: 'filename/label in header bar',
- hasLanguageLabel: 'show language name in header; hidden for "plaintext"',
- hasLineNumbers: 'show line number gutter',
- highlightLines: '1-indexed lines to highlight',
- hasCopyButton: 'show copy button',
- onCopy: 'callback after copy',
- isWrapped: 'wrap long lines vs h-scroll',
- maxHeight: 'max height before vertical scroll',
- size: 'text size variant',
- width: "any CSS width value; fit-content (default) or 100% to fill parent",
- container: "card=border+radius+muted bg (default); section=no border/radius, transparent bg (embed in cards)",
- tokenizer: 'custom tokenizer for unsupported languages',
- isCollapsible: 'Collapse code to header bar. Toggle appears when lines > collapsibleThreshold. Default: false.',
- collapsibleThreshold: 'Min lines before collapse toggle shows. Default: 10.',
- xstyle: 'StyleX layout styles; must be stylex.create() value',
- className: 'CSS class for root; prefer xstyle',
- style: 'inline styles; prefer xstyle',
- 'data-testid': 'test selector',
- },
- },
- {
- name: 'XDSCode',
- displayName: 'Code',
- description: 'inline code element; styled <code> w/ monospace+muted bg; for prose',
- propDescriptions: {
- children: 'code content',
- xstyle: 'StyleX layout styles; must be stylex.create() value',
- className: 'CSS class for root; prefer xstyle',
- style: 'inline styles; prefer xstyle',
- 'data-testid': 'test selector',
- },
- },
- ],
};
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index faa57301a9..efaae99f5c 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -19,86 +19,52 @@ export const docs = {
{className: 'xds-collapsible'},
],
},
- components: [
+ description: 'A primitive that makes any content collapsible — a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.',
+ props: [
{
- name: 'XDSCollapsible',
- displayName: 'Collapsible',
- description:
- 'A primitive that makes any content collapsible: a trigger button toggles visibility of the content area, managing its own state or deferring to a parent XDSCollapsibleGroup.',
- props: [
- {
- name: 'trigger',
- type: 'ReactNode',
- description: 'Content shown in the trigger area (always visible).',
- required: true,
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Trigger'}],
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Content that collapses and expands.',
- },
- {
- name: 'defaultIsOpen',
- type: 'boolean',
- description: 'Default open state (uncontrolled).',
- default: 'true',
- },
+ name: 'trigger',
+ type: 'ReactNode',
+ description: 'Content shown in the trigger area (always visible).',
+ required: true,
+ slotElements: [
{
- name: 'isOpen',
- type: 'boolean',
- description: 'Controlled open state.',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description: 'Callback invoked when the open state changes.',
- },
- {
- name: 'value',
- type: 'string',
- description:
- 'Identifier used for group coordination. Required when placed inside an XDSCollapsibleGroup.',
- },
- ], },
- {
- name: 'XDSCollapsibleGroup',
- isHiddenFromOverview: true,
- displayName: 'Collapsible Group',
- description:
- 'Coordinates multiple XDSCollapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element.',
- props: [
- {
- name: 'type',
- type: "'single' | 'multiple'",
- description: 'Whether one or many items can be open simultaneously.',
- default: "'single'",
- },
- {
- name: 'defaultValue',
- type: 'string | string[]',
- description:
- 'Default open item(s) for uncontrolled usage. Use a string for single mode and an array for multiple mode.',
- },
- {
- name: 'value',
- type: 'string | string[]',
- description: 'Controlled open item(s).',
- },
- {
- name: 'onChange',
- type: '(value: string | string[]) => void',
- description: 'Callback invoked when the set of open items changes.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'XDSCollapsible instances to coordinate.',
- required: true,
- slotElements: [{__element: 'XDSCollapsible', props: {trigger: 'Section'}, children: 'Content'}],
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Trigger',
},
],
},
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content that collapses and expands.',
+ },
+ {
+ name: 'defaultIsOpen',
+ type: 'boolean',
+ description: 'Default open state (uncontrolled).',
+ default: 'true',
+ },
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Controlled open state.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback invoked when the open state changes.',
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Identifier used for group coordination. Required when placed inside an XDSCollapsibleGroup.',
+ },
+ ],
+ components: [
+ {name: 'XDSCollapsibleGroup'},
],
usage: {
description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in XDSCollapsibleGroup for accordion behavior. For custom collapsible components, use the `useXDSCollapsible` hook directly (`xds hook useXDSCollapsible`).',
@@ -119,11 +85,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Collapsible',
- displayName: 'Collapsible',
- group: 'Collapsible',
usage: {
description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in XDSCollapsibleGroup for accordion behavior.',
bestPractices: [
@@ -136,41 +99,6 @@ export const docsZh = {
{ guidance: false, description: 'Use a collapsible for a single short paragraph; just show the text directly instead.' },
],
},
- theming: {
- targets: [
- {className: 'xds-collapsible'},
- ],
- },
- components: [
- {
- name: 'XDSCollapsible',
- displayName: 'Collapsible',
- description:
- '使任何内容可折叠的原语——触发按钮切换内容区域的可见性,自行管理状态或委托给父级 XDSCollapsibleGroup。',
- props: [
- {name: 'trigger', type: 'ReactNode', description: '触发区域中显示的内容(始终可见)。', required: true},
- {name: 'children', type: 'ReactNode', description: '可折叠和展开的内容。'},
- {name: 'defaultIsOpen', type: 'boolean', description: '默认展开状态(非受控)。', default: 'true'},
- {name: 'isOpen', type: 'boolean', description: '受控展开状态。'},
- {name: 'onOpenChange', type: '(isOpen: boolean) => void', description: '展开状态变更时调用的回调。'},
- {name: 'value', type: 'string', description: '用于分组协调的标识符。放置在 XDSCollapsibleGroup 内时为必填。'},
- ],
- },
- {
- name: 'XDSCollapsibleGroup',
- isHiddenFromOverview: true,
- displayName: 'Collapsible Group',
- description:
- '协调多个 XDSCollapsible 实例,使同一时间只有一个(single 模式)或任意数量(multiple 模式)可以展开。不渲染包裹 DOM 元素。',
- props: [
- {name: 'type', type: "'single' | 'multiple'", description: '是否允许同时展开一个或多个项目。', default: "'single'"},
- {name: 'defaultValue', type: 'string | string[]', description: '非受控模式下默认展开的项目。single 模式使用字符串,multiple 模式使用数组。'},
- {name: 'value', type: 'string | string[]', description: '受控展开的项目。'},
- {name: 'onChange', type: '(value: string | string[]) => void', description: '展开项目集合变更时调用的回调。'},
- {name: 'children', type: 'ReactNode', description: '需要协调的 XDSCollapsible 实例。', required: true},
- ],
- },
- ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -188,32 +116,4 @@ export const docsDense = {
{ guidance: false, description: 'Use a collapsible for a single short paragraph; just show the text directly instead.' },
],
},
- components: [
- {
- name: 'XDSCollapsible',
- displayName: 'Collapsible',
- description: 'makes content collapsible; trigger toggles visibility, manages own state or defers to parent group',
- propDescriptions: {
- trigger: 'content in trigger area (always visible)',
- children: 'content that collapses+expands',
- defaultIsOpen: 'default open state (uncontrolled)',
- isOpen: 'controlled open state',
- onOpenChange: 'callback on open state change',
- value: 'ID for group coordination; required inside XDSCollapsibleGroup',
- },
- },
- {
- name: 'XDSCollapsibleGroup',
- isHiddenFromOverview: true,
- displayName: 'Collapsible Group',
- description: 'coordinates multiple XDSCollapsible instances; single or multiple open. no wrapper DOM.',
- propDescriptions: {
- type: 'one or many items open simultaneously',
- defaultValue: 'default open item(s) (uncontrolled); string for single, array for multiple',
- value: 'controlled open item(s)',
- onChange: 'callback on open items change',
- children: 'XDSCollapsible instances to coordinate',
- },
- },
- ],
};
diff --git a/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs b/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs
new file mode 100644
index 0000000000..21a1ddb43b
--- /dev/null
+++ b/packages/core/src/Collapsible/CollapsibleGroup.doc.mjs
@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CollapsibleGroup',
+ subComponentOf: 'Collapsible',
+ displayName: 'Collapsible Group',
+ isHiddenFromOverview: true,
+ description: 'Coordinates multiple XDSCollapsible instances so only one (single mode) or any number (multiple mode) can be open at a time. Renders no wrapper DOM element.',
+ props: [
+ {
+ name: 'type',
+ type: "'single' | 'multiple'",
+ description: 'Whether one or many items can be open simultaneously.',
+ default: "'single'",
+ },
+ {
+ name: 'defaultValue',
+ type: 'string | string[]',
+ description: 'Default open item(s) for uncontrolled usage. Use a string for single mode and an array for multiple mode.',
+ },
+ {
+ name: 'value',
+ type: 'string | string[]',
+ description: 'Controlled open item(s).',
+ },
+ {
+ name: 'onChange',
+ type: '(value: string | string[]) => void',
+ description: 'Callback invoked when the set of open items changes.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSCollapsible instances to coordinate.',
+ required: true,
+ slotElements: [
+ {
+ __element: 'XDSCollapsible',
+ props: {
+ trigger: 'Section',
+ },
+ children: 'Content',
+ },
+ ],
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'CollapsibleGroup',
+ isHiddenFromOverview: true,
+ displayName: 'Collapsible Group',
+ description: '协调多个 XDSCollapsible 实例,使同一时间只有一个(single 模式)或任意数量(multiple 模式)可以展开。不渲染包裹 DOM 元素。',
+ props: [
+ {
+ name: 'type',
+ type: "'single' | 'multiple'",
+ description: '是否允许同时展开一个或多个项目。',
+ default: "'single'",
+ },
+ {
+ name: 'defaultValue',
+ type: 'string | string[]',
+ description: '非受控模式下默认展开的项目。single 模式使用字符串,multiple 模式使用数组。',
+ },
+ {
+ name: 'value',
+ type: 'string | string[]',
+ description: '受控展开的项目。',
+ },
+ {
+ name: 'onChange',
+ type: '(value: string | string[]) => void',
+ description: '展开项目集合变更时调用的回调。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '需要协调的 XDSCollapsible 实例。',
+ required: true,
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'CollapsibleGroup',
+ isHiddenFromOverview: true,
+ displayName: 'Collapsible Group',
+ description: 'coordinates multiple XDSCollapsible instances; single or multiple open. no wrapper DOM.',
+ propDescriptions: {
+ type: 'one or many items open simultaneously',
+ defaultValue: 'default open item(s) (uncontrolled); string for single, array for multiple',
+ value: 'controlled open item(s)',
+ onChange: 'callback on open items change',
+ children: 'XDSCollapsible instances to coordinate',
+ },
+};
diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
index 081fd18d19..2e2916c56d 100644
--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs
+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
@@ -19,294 +19,116 @@ export const docs = {
'dialog',
'navigation',
],
- components: [
+ description: 'Root component. Manages open state, search, keyboard navigation, and composition slots.',
+ props: [
{
- name: 'XDSCommandPalette',
- displayName: 'Command Palette',
- description:
- 'Root component. Manages open state, search, keyboard navigation, and composition slots.',
- props: [
- {
- name: 'isOpen',
- type: 'boolean',
- description: 'Whether the command palette dialog is visible.',
- required: true,
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description: 'Called when the palette visibility changes.',
- required: true,
- },
- {
- name: 'searchSource',
- type: 'XDSSearchSource<T>',
- description:
- 'Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.',
- required: true,
- },
- {
- name: 'input',
- type: 'ReactNode',
- description:
- 'Input slot. Defaults to XDSCommandPaletteInput with standard behavior.',
- default: '<XDSCommandPaletteInput />',
- slotElements: [{__element: 'XDSTextInput', props: {label: 'Input', placeholder: 'Type here...'}}],
- },
- {
- name: 'footer',
- type: 'ReactNode',
- description:
- 'Footer slot. Defaults to XDSCommandPaletteFooter showing keyboard hints.',
- default: '<XDSCommandPaletteFooter />',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Footer content'}],
- },
- {
- name: 'renderItem',
- type: '(item: T, isSelected: boolean) => ReactNode',
- description:
- 'Per-item render function. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.',
- },
- {
- name: 'emptySearchText',
- type: 'ReactNode',
- description: 'Content shown when a search query returns no results.',
- default: "'No results'",
- },
- {
- name: 'emptyBootstrapText',
- type: 'ReactNode',
- description:
- 'Content shown when there is no search query and bootstrap() returns nothing.',
- default: "'Type to search'",
- },
- {
- name: 'value',
- type: 'string',
- description: 'Controlled selected value for picker mode.',
- },
- {
- name: 'onValueChange',
- type: '(value: string) => void',
- description: 'Called when the selected value changes in picker mode.',
- },
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label for the command palette dialog.',
- default: "'Command palette'",
- },
- {
- name: 'width',
- type: 'number | string',
- description: 'Width of the dialog.',
- default: '640',
- },
- {
- name: 'maxHeight',
- type: 'number | string',
- description: 'Maximum height of the dialog.',
- default: '480',
- },
- {
- name: 'isInline',
- type: 'boolean',
- description: 'Renders command palette content inline without modal behavior. Automatically disables auto-focus on the input. For documentation previews and showcases only.',
- default: 'false',
- },
- ],
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Whether the command palette dialog is visible.',
+ required: true,
},
{
- name: 'XDSCommandPaletteInput',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Input',
- description:
- 'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside XDSCommandPalette.',
- props: [
- {
- name: 'placeholder',
- type: 'string',
- description: 'Placeholder text for the input.',
- default: "'Search...'",
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: 'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
- default: 'true',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- 'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
- },
- {
- name: 'value',
- type: 'string',
- description:
- 'Search value. When omitted inside XDSCommandPalette, reads from context.',
- },
- {
- name: 'onValueChange',
- type: '(value: string) => void',
- description:
- 'Called when search value changes. When omitted inside XDSCommandPalette, writes to context.',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
- },
- ],
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Called when the palette visibility changes.',
+ required: true,
},
{
- name: 'XDSCommandPaletteList',
- isHiddenFromOverview: true,
- displayName: 'Command Palette List',
- description:
- 'Scrollable results container. Renders as a listbox for ARIA. Contains XDSCommandPaletteItem and XDSCommandPaletteGroup children.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Items, groups, and empty states.',
- required: true,
- },
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label for the listbox.',
- default: "'Commands'",
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
- },
- ],
+ name: 'searchSource',
+ type: 'XDSSearchSource<T>',
+ description: 'Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.',
+ required: true,
},
{
- name: 'XDSCommandPaletteItem',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Item',
- description:
- 'A selectable item. Accepts arbitrary children for full rendering control. Registers with context for keyboard navigation when inside XDSCommandPalette.',
- props: [
- {
- name: 'value',
- type: 'string',
- description: 'Unique value for identification and selection.',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Item content: render icons, descriptions, keyboard shortcuts, etc.',
- required: true,
- },
- {
- name: 'onSelect',
- type: '(value: string) => void',
- description: 'Called when this item is selected via click or Enter.',
- },
- {
- name: 'isHighlighted',
- type: 'boolean',
- description:
- 'Whether this item has keyboard focus. Derived from context when inside XDSCommandPalette.',
- default: 'false',
- },
- {
- name: 'isSelected',
- type: 'boolean',
- description: 'Whether this item is selected in picker mode.',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether the item is non-interactive.',
- default: 'false',
- },
+ name: 'input',
+ type: 'ReactNode',
+ description: 'Input slot. Defaults to XDSCommandPaletteInput with standard behavior.',
+ default: '<XDSCommandPaletteInput />',
+ slotElements: [
{
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ __element: 'XDSTextInput',
+ props: {
+ label: 'Input',
+ placeholder: 'Type here...',
+ },
},
],
},
{
- name: 'XDSCommandPaletteGroup',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Group',
- description: 'Visual grouping with a heading label. Place inside XDSCommandPaletteList.',
- props: [
- {
- name: 'heading',
- type: 'string',
- description: 'Group heading text.',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'XDSCommandPaletteItem children.',
- required: true,
- },
+ name: 'footer',
+ type: 'ReactNode',
+ description: 'Footer slot. Defaults to XDSCommandPaletteFooter showing keyboard hints.',
+ default: '<XDSCommandPaletteFooter />',
+ slotElements: [
{
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Footer content',
},
],
},
{
- name: 'XDSCommandPaletteFooter',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Footer',
- description:
- 'Footer showing keyboard navigation hints. Renders default arrow/Enter/Escape hints when no children are provided.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Custom footer content. When omitted, renders default keyboard hints via XDSKbd.',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
- },
- ],
+ name: 'renderItem',
+ type: '(item: T, isSelected: boolean) => ReactNode',
+ description: 'Per-item render function. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.',
},
{
- name: 'XDSCommandPaletteEmpty',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Empty',
- description:
- 'Empty state display for the results area. Rendered automatically by XDSCommandPalette for no-results and no-query states.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Message or content to display.',
- required: true,
- },
- ],
+ name: 'emptySearchText',
+ type: 'ReactNode',
+ description: 'Content shown when a search query returns no results.',
+ default: "'No results'",
+ },
+ {
+ name: 'emptyBootstrapText',
+ type: 'ReactNode',
+ description: 'Content shown when there is no search query and bootstrap() returns nothing.',
+ default: "'Type to search'",
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Controlled selected value for picker mode.',
+ },
+ {
+ name: 'onValueChange',
+ type: '(value: string) => void',
+ description: 'Called when the selected value changes in picker mode.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the command palette dialog.',
+ default: "'Command palette'",
+ },
+ {
+ name: 'width',
+ type: 'number | string',
+ description: 'Width of the dialog.',
+ default: '640',
+ },
+ {
+ name: 'maxHeight',
+ type: 'number | string',
+ description: 'Maximum height of the dialog.',
+ default: '480',
+ },
+ {
+ name: 'isInline',
+ type: 'boolean',
+ description: 'Renders command palette content inline without modal behavior. Automatically disables auto-focus on the input. For documentation previews and showcases only.',
+ default: 'false',
},
],
+ components: [
+ {name: 'XDSCommandPaletteInput'},
+ {name: 'XDSCommandPaletteList'},
+ {name: 'XDSCommandPaletteItem'},
+ {name: 'XDSCommandPaletteGroup'},
+ {name: 'XDSCommandPaletteFooter'},
+ {name: 'XDSCommandPaletteEmpty'},
+ ],
theming: {
targets: [
{className: 'xds-command-palette-footer'},
@@ -338,86 +160,6 @@ export const docsZh = {
{ guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },
],
},
- components: [
- {
- name: 'XDSCommandPalette',
- displayName: 'Command Palette',
- description: '根组件。管理打开状态、搜索、键盘导航和组合插槽。',
- propDescriptions: {
- isOpen: '命令面板对话框是否可见。',
- onOpenChange: '面板可见性变化时调用。',
- searchSource: '通过 search(query) 和 bootstrap() 提供条目的搜索源。',
- input: '输入插槽。默认为 XDSCommandPaletteInput。',
- footer: '页脚插槽。默认为 XDSCommandPaletteFooter 显示键盘提示。',
- renderItem: '每个条目的渲染函数。保留 auxiliaryData.group 自动分组。',
- emptySearchText: '搜索查询无结果时显示的内容。',
- emptyBootstrapText: '无搜索词且 bootstrap() 返回空时显示的内容。',
- value: '选择器模式下的受控选中值。',
- onValueChange: '选择器模式下选中值变化时调用。',
- label: '命令面板对话框的无障碍标签。',
- width: '对话框宽度。',
- maxHeight: '对话框最大高度。',
- isInline: '以内联方式渲染命令面板内容,不带模态行为。自动禁用输入框自动聚焦。仅用于文档预览和展示。',
- },
- },
- {
- name: 'XDSCommandPaletteInput',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Input',
- description: '搜索输入插槽。挂载时自动聚焦。在 XDSCommandPalette 内使用时连接到上下文。',
- propDescriptions: {
- placeholder: '输入框的占位文本。',
- hasAutoFocus: '挂载时自动聚焦输入框。内联命令面板中自动禁用。',
- endContent: '渲染在输入框末尾的内容,位于加载指示器之后。',
- value: '搜索值。在 XDSCommandPalette 内省略时从上下文读取。',
- onValueChange: '搜索值变化时调用。在 XDSCommandPalette 内省略时写入上下文。',
- xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
- },
- },
- {
- name: 'XDSCommandPaletteList',
- isHiddenFromOverview: true,
- displayName: 'Command Palette List',
- description: '可滚动的结果容器。作为 listbox 渲染以符合 ARIA 规范。',
- propDescriptions: {children: '条目、分组和空状态。', label: 'listbox 的无障碍标签。', xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。'},
- },
- {
- name: 'XDSCommandPaletteItem',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Item',
- description: '可选择的条目。接受任意子元素以实现完整的渲染控制。',
- propDescriptions: {
- value: '用于标识和选择的唯一值。',
- children: '条目内容——渲染图标、描述、键盘快捷键等。',
- onSelect: '通过点击或 Enter 选择此条目时调用。',
- isHighlighted: '此条目是否具有键盘焦点。在 XDSCommandPalette 内从上下文派生。',
- isSelected: '此条目在选择器模式下是否被选中。',
- isDisabled: '条目是否为非交互状态。',
- xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
- },
- },
- {
- name: 'XDSCommandPaletteGroup',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Group',
- description: '带标题标签的视觉分组。放置在 XDSCommandPaletteList 内。',
- propDescriptions: {heading: '分组标题文本。', children: 'XDSCommandPaletteItem 子元素。', xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。'},
- },
- {
- name: 'XDSCommandPaletteFooter',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Footer',
- description: '显示键盘导航提示的页脚。未提供子元素时渲染默认方向键/Enter/Escape 提示。',
- propDescriptions: {children: '自定义页脚内容。省略时通过 XDSKbd 渲染默认键盘提示。', xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。'},
- },
- {
- name: 'XDSCommandPaletteEmpty',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Empty',
- description: '结果区域的空状态展示。由 XDSCommandPalette 在无结果和无查询状态下自动渲染。',
- propDescriptions: {children: '要显示的消息或内容。'},
- },
- ],
};
/** @type {import('../docs-types').TranslationDoc} */
@@ -433,97 +175,4 @@ export const docsDense = {
{ guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },
],
},
- components: [
- {
- name: 'XDSCommandPalette',
- displayName: 'Command Palette',
- description: 'root; manages open state, search, keyboard nav, composition slots',
- propDescriptions: {
- isOpen: 'dialog visible',
- onOpenChange: 'called on visibility change',
- searchSource: 'provides items via search(query)+bootstrap()',
- input: 'input slot; default=XDSCommandPaletteInput',
- footer: 'footer slot; default=XDSCommandPaletteFooter w/ kbd hints',
- renderItem: 'per-item render fn; auto-grouping preserved',
- emptySearchText: 'shown when query returns no results',
- emptyBootstrapText: 'shown when no query+bootstrap() empty',
- value: 'controlled selected value for picker mode',
- onValueChange: 'called on selected value change',
- label: 'a11y label for dialog',
- width: 'dialog width',
- maxHeight: 'dialog max height',
- isInline: 'inline rendering for docs previews, no modal behavior, auto-disables input focus',
- },
- },
- {
- name: 'XDSCommandPaletteInput',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Input',
- description: 'search input; auto-focus on mount; wires to context inside XDSCommandPalette',
- propDescriptions: {
- placeholder: 'input placeholder text',
- hasAutoFocus: 'auto-focus on mount; auto-disabled in inline mode',
- endContent: 'trailing content after spinner',
- value: 'search value; reads context when omitted inside palette',
- onValueChange: 'called on change; writes context when omitted inside palette',
- xstyle: 'StyleX layout styles; must be stylex.create() value',
- },
- },
- {
- name: 'XDSCommandPaletteList',
- isHiddenFromOverview: true,
- displayName: 'Command Palette List',
- description: 'scrollable results container; role=listbox',
- propDescriptions: {
- children: 'items, groups, empty states',
- label: 'a11y label for listbox',
- xstyle: 'StyleX layout styles; must be stylex.create() value',
- },
- },
- {
- name: 'XDSCommandPaletteItem',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Item',
- description: 'selectable item; arbitrary children; registers w/ context for kbd nav',
- propDescriptions: {
- value: 'unique id for selection',
- children: 'item content: icons, descriptions, shortcuts',
- onSelect: 'called on click or Enter',
- isHighlighted: 'keyboard focus; derived from context inside palette',
- isSelected: 'selected in picker mode',
- isDisabled: 'non-interactive',
- xstyle: 'StyleX layout styles; must be stylex.create() value',
- },
- },
- {
- name: 'XDSCommandPaletteGroup',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Group',
- description: 'group w/ heading label; inside XDSCommandPaletteList',
- propDescriptions: {
- heading: 'group heading text',
- children: 'XDSCommandPaletteItem children',
- xstyle: 'StyleX layout styles; must be stylex.create() value',
- },
- },
- {
- name: 'XDSCommandPaletteFooter',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Footer',
- description: 'footer w/ kbd hints; default=arrow/Enter/Escape hints via XDSKbd',
- propDescriptions: {
- children: 'custom content; default renders kbd hints',
- xstyle: 'StyleX layout styles; must be stylex.create() value',
- },
- },
- {
- name: 'XDSCommandPaletteEmpty',
- isHiddenFromOverview: true,
- displayName: 'Command Palette Empty',
- description: 'empty state; auto-rendered by palette for no-results+no-query states',
- propDescriptions: {
- children: 'message or content to display',
- },
- },
- ],
};
diff --git a/packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs
new file mode 100644
index 0000000000..b62963b57f
--- /dev/null
+++ b/packages/core/src/CommandPalette/CommandPaletteEmpty.doc.mjs
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CommandPaletteEmpty',
+ subComponentOf: 'CommandPalette',
+ displayName: 'Command Palette Empty',
+ isHiddenFromOverview: true,
+ description: 'Empty state display for the results area. Rendered automatically by XDSCommandPalette for no-results and no-query states.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Message or content to display.',
+ required: true,
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'CommandPaletteEmpty',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Empty',
+ description: '结果区域的空状态展示。由 XDSCommandPalette 在无结果和无查询状态下自动渲染。',
+ propDescriptions: {
+ children: '要显示的消息或内容。',
+ },
+};
+
+export const docsDense = {
+ name: 'CommandPaletteEmpty',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Empty',
+ description: 'empty state; auto-rendered by palette for no-results+no-query states',
+ propDescriptions: {
+ children: 'message or content to display',
+ },
+};
diff --git a/packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs
new file mode 100644
index 0000000000..3b9f047fa0
--- /dev/null
+++ b/packages/core/src/CommandPalette/CommandPaletteFooter.doc.mjs
@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CommandPaletteFooter',
+ subComponentOf: 'CommandPalette',
+ displayName: 'Command Palette Footer',
+ isHiddenFromOverview: true,
+ description: 'Footer showing keyboard navigation hints. Renders default arrow/Enter/Escape hints when no children are provided.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Custom footer content. When omitted, renders default keyboard hints via XDSKbd.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'CommandPaletteFooter',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Footer',
+ description: '显示键盘导航提示的页脚。未提供子元素时渲染默认方向键/Enter/Escape 提示。',
+ propDescriptions: {
+ children: '自定义页脚内容。省略时通过 XDSKbd 渲染默认键盘提示。',
+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
+ },
+};
+
+export const docsDense = {
+ name: 'CommandPaletteFooter',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Footer',
+ description: 'footer w/ kbd hints; default=arrow/Enter/Escape hints via XDSKbd',
+ propDescriptions: {
+ children: 'custom content; default renders kbd hints',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ },
+};
diff --git a/packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs
new file mode 100644
index 0000000000..ee8350b9d9
--- /dev/null
+++ b/packages/core/src/CommandPalette/CommandPaletteGroup.doc.mjs
@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CommandPaletteGroup',
+ subComponentOf: 'CommandPalette',
+ displayName: 'Command Palette Group',
+ isHiddenFromOverview: true,
+ description: 'Visual grouping with a heading label. Place inside XDSCommandPaletteList.',
+ props: [
+ {
+ name: 'heading',
+ type: 'string',
+ description: 'Group heading text.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSCommandPaletteItem children.',
+ required: true,
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'CommandPaletteGroup',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Group',
+ description: '带标题标签的视觉分组。放置在 XDSCommandPaletteList 内。',
+ propDescriptions: {
+ heading: '分组标题文本。',
+ children: 'XDSCommandPaletteItem 子元素。',
+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
+ },
+};
+
+export const docsDense = {
+ name: 'CommandPaletteGroup',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Group',
+ description: 'group w/ heading label; inside XDSCommandPaletteList',
+ propDescriptions: {
+ heading: 'group heading text',
+ children: 'XDSCommandPaletteItem children',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ },
+};
diff --git a/packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs
new file mode 100644
index 0000000000..b5a133218f
--- /dev/null
+++ b/packages/core/src/CommandPalette/CommandPaletteInput.doc.mjs
@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CommandPaletteInput',
+ subComponentOf: 'CommandPalette',
+ displayName: 'Command Palette Input',
+ isHiddenFromOverview: true,
+ description: 'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside XDSCommandPalette.',
+ props: [
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text for the input.',
+ default: "'Search...'",
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
+ default: 'true',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
+ },
+ {
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
+ },
+ ],
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Search value. When omitted inside XDSCommandPalette, reads from context.',
+ },
+ {
+ name: 'onValueChange',
+ type: '(value: string) => void',
+ description: 'Called when search value changes. When omitted inside XDSCommandPalette, writes to context.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'CommandPaletteInput',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Input',
+ description: '搜索输入插槽。挂载时自动聚焦。在 XDSCommandPalette 内使用时连接到上下文。',
+ propDescriptions: {
+ placeholder: '输入框的占位文本。',
+ hasAutoFocus: '挂载时自动聚焦输入框。内联命令面板中自动禁用。',
+ endContent: '渲染在输入框末尾的内容,位于加载指示器之后。',
+ value: '搜索值。在 XDSCommandPalette 内省略时从上下文读取。',
+ onValueChange: '搜索值变化时调用。在 XDSCommandPalette 内省略时写入上下文。',
+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
+ },
+};
+
+export const docsDense = {
+ name: 'CommandPaletteInput',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Input',
+ description: 'search input; auto-focus on mount; wires to context inside XDSCommandPalette',
+ propDescriptions: {
+ placeholder: 'input placeholder text',
+ hasAutoFocus: 'auto-focus on mount; auto-disabled in inline mode',
+ endContent: 'trailing content after spinner',
+ value: 'search value; reads context when omitted inside palette',
+ onValueChange: 'called on change; writes context when omitted inside palette',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ },
+};
diff --git a/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs
new file mode 100644
index 0000000000..c3ed3071b3
--- /dev/null
+++ b/packages/core/src/CommandPalette/CommandPaletteItem.doc.mjs
@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CommandPaletteItem',
+ subComponentOf: 'CommandPalette',
+ displayName: 'Command Palette Item',
+ isHiddenFromOverview: true,
+ description: 'A selectable item. Accepts arbitrary children for full rendering control. Registers with context for keyboard navigation when inside XDSCommandPalette.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Unique value for identification and selection.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Item content — render icons, descriptions, keyboard shortcuts, etc.',
+ required: true,
+ },
+ {
+ name: 'onSelect',
+ type: '(value: string) => void',
+ description: 'Called when this item is selected via click or Enter.',
+ },
+ {
+ name: 'isHighlighted',
+ type: 'boolean',
+ description: 'Whether this item has keyboard focus. Derived from context when inside XDSCommandPalette.',
+ default: 'false',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: 'Whether this item is selected in picker mode.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the item is non-interactive.',
+ default: 'false',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'CommandPaletteItem',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Item',
+ description: '可选择的条目。接受任意子元素以实现完整的渲染控制。',
+ propDescriptions: {
+ value: '用于标识和选择的唯一值。',
+ children: '条目内容——渲染图标、描述、键盘快捷键等。',
+ onSelect: '通过点击或 Enter 选择此条目时调用。',
+ isHighlighted: '此条目是否具有键盘焦点。在 XDSCommandPalette 内从上下文派生。',
+ isSelected: '此条目在选择器模式下是否被选中。',
+ isDisabled: '条目是否为非交互状态。',
+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
+ },
+};
+
+export const docsDense = {
+ name: 'CommandPaletteItem',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette Item',
+ description: 'selectable item; arbitrary children; registers w/ context for kbd nav',
+ propDescriptions: {
+ value: 'unique id for selection',
+ children: 'item content — icons, descriptions, shortcuts',
+ onSelect: 'called on click or Enter',
+ isHighlighted: 'keyboard focus; derived from context inside palette',
+ isSelected: 'selected in picker mode',
+ isDisabled: 'non-interactive',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ },
+};
diff --git a/packages/core/src/CommandPalette/CommandPaletteList.doc.mjs b/packages/core/src/CommandPalette/CommandPaletteList.doc.mjs
new file mode 100644
index 0000000000..a0dbb03b5d
--- /dev/null
+++ b/packages/core/src/CommandPalette/CommandPaletteList.doc.mjs
@@ -0,0 +1,54 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CommandPaletteList',
+ subComponentOf: 'CommandPalette',
+ displayName: 'Command Palette List',
+ isHiddenFromOverview: true,
+ description: 'Scrollable results container. Renders as a listbox for ARIA. Contains XDSCommandPaletteItem and XDSCommandPaletteGroup children.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Items, groups, and empty states.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the listbox.',
+ default: "'Commands'",
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'CommandPaletteList',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette List',
+ description: '可滚动的结果容器。作为 listbox 渲染以符合 ARIA 规范。',
+ propDescriptions: {
+ children: '条目、分组和空状态。',
+ label: 'listbox 的无障碍标签。',
+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
+ },
+};
+
+export const docsDense = {
+ name: 'CommandPaletteList',
+ isHiddenFromOverview: true,
+ displayName: 'Command Palette List',
+ description: 'scrollable results container; role=listbox',
+ propDescriptions: {
+ children: 'items, groups, empty states',
+ label: 'a11y label for listbox',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ },
+};
diff --git a/packages/core/src/ContextMenu/ContextMenu.doc.mjs b/packages/core/src/ContextMenu/ContextMenu.doc.mjs
index a409ee660c..1e4b34315e 100644
--- a/packages/core/src/ContextMenu/ContextMenu.doc.mjs
+++ b/packages/core/src/ContextMenu/ContextMenu.doc.mjs
@@ -21,94 +21,53 @@ export const docs = {
{property: 'padding', vars: ['--_dropdown-menu-padding']},
],
},
- components: [
+ description: 'A context menu that appears on right-click at the cursor position. Wraps trigger content as children.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'The trigger area — right-click on this content to open the menu.',
+ required: true,
+ },
+ {
+ name: 'items',
+ type: 'XDSContextMenuOption[]',
+ description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?}`, a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
+ required: true,
+ },
+ {
+ name: 'menuContent',
+ type: 'ReactNode',
+ description: 'Custom JSX menu content for compound mode. Use instead of items for dynamic or stateful menus.',
+ },
+ {
+ name: 'menuWidth',
+ type: 'number | string',
+ description: 'Custom menu width.',
+ default: "'160px'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size of menu items — controls padding density.',
+ default: "'md'",
+ },
{
- name: 'XDSContextMenu',
- displayName: 'Context Menu',
- description:
- 'A context menu that appears on right-click at the cursor position. Wraps trigger content as children.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'The trigger area: right-click on this content to open the menu.',
- required: true,
- },
- {
- name: 'items',
- type: 'XDSContextMenuOption[]',
- description:
- 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?}`, a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
- required: true,
- },
- {
- name: 'menuContent',
- type: 'ReactNode',
- description: 'Custom JSX menu content for compound mode. Use instead of items for dynamic or stateful menus.',
- },
- {
- name: 'menuWidth',
- type: 'number | string',
- description: 'Custom menu width.',
- default: "'160px'",
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: 'Size of menu items: controls padding density.',
- default: "'md'",
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases.',
- default: 'true',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'When true, right-click shows the native browser context menu instead.',
- default: 'false',
- },
- ],
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases.',
+ default: 'true',
},
{
- name: 'XDSContextMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Context Menu Item',
- description:
- 'Menu item component for compound mode. Re-exported from XDSDropdownMenuItem for discoverability.',
- props: [
- {
- name: 'icon',
- type: 'XDSIconType',
- description: 'Icon to display before the label.',
- },
- {
- name: 'label',
- type: 'ReactNode',
- description: 'Primary label text.',
- },
- {
- name: 'description',
- type: 'ReactNode',
- description: 'Secondary description text displayed below the label.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Additional content rendered after the label and description.',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description: 'StyleX styles for layout customization.',
- },
- ],
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'When true, right-click shows the native browser context menu instead.',
+ default: 'false',
},
],
+ components: [
+ {name: 'XDSContextMenuItem'},
+ ],
usage: {
description: 'A right-click context menu that appears at the cursor position. Use to provide contextual actions for specific elements or regions without cluttering the UI with visible buttons.',
bestPractices: [
@@ -121,109 +80,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'ContextMenu',
- displayName: 'Context Menu',
- theming: {
- targets: [
- {className: 'xds-context-menu'},
- ],
- vars: [
- {name: '--_dropdown-menu-radius', description: '菜单弹出层的圆角', default: 'var(--radius-container)', private: true},
- {name: '--_dropdown-menu-padding', description: '菜单弹出层的内边距', default: 'var(--spacing-1)', private: true},
- ],
- derived: [
- {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},
- {property: 'padding', vars: ['--_dropdown-menu-padding']},
- ],
- },
- components: [
- {
- name: 'XDSContextMenu',
- displayName: 'Context Menu',
- description:
- '右键点击时在光标位置出现的上下文菜单。将触发内容作为子元素包裹。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '触发区域:右键点击此内容以打开菜单。',
- required: true,
- },
- {
- name: 'items',
- type: 'XDSContextMenuOption[]',
- description:
- '菜单项数组。每项为:操作项 `{label, onClick?, icon?, isDisabled?}`、分隔线 `{type: "divider"}`、或分组 `{type: "section", title?, items: [...操作项]}`。',
- required: true,
- },
- {
- name: 'menuContent',
- type: 'ReactNode',
- description: '复合模式的自定义 JSX 菜单内容。',
- },
- {
- name: 'menuWidth',
- type: 'number | string',
- description: '自定义菜单宽度。',
- default: "'160px'",
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: '菜单项大小:控制内边距密度。',
- default: "'md'",
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: '菜单打开时是否自动聚焦第一个菜单项。',
- default: 'true',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '为 true 时,右键显示浏览器原生上下文菜单。',
- default: 'false',
- },
- ],
- },
- {
- name: 'XDSContextMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Context Menu Item',
- description:
- '复合模式的菜单项组件。从 XDSDropdownMenuItem 重新导出以便发现。',
- props: [
- {
- name: 'icon',
- type: 'XDSIconType',
- description: '显示在标签前的图标。',
- },
- {
- name: 'label',
- type: 'ReactNode',
- description: '主标签文本。',
- },
- {
- name: 'description',
- type: 'ReactNode',
- description: '显示在标签下方的次要描述文本。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '在标签和描述之后渲染的附加内容。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description: '根容器的 StyleX 样式。',
- },
- ],
- },
- ],
usage: {
description: '右键点击时在光标位置出现的上下文菜单。用于为特定元素或区域提供上下文操作,而不使 UI 杂乱。',
bestPractices: [
@@ -249,33 +107,4 @@ export const docsDense = {
{ guidance: false, description: 'Place more than 10–12 items without grouping.' },
],
},
- components: [
- {
- name: 'XDSContextMenu',
- displayName: 'Context Menu',
- description: 'right-click trigger + fixed-position popup menu',
- propDescriptions: {
- children: 'trigger area: right-click to open menu',
- items: 'array of menu entries: action item {label, onClick?, icon?, isDisabled?}, divider {type: "divider"}, or section {type: "section", title?, items: [...]}',
- menuContent: 'custom JSX menu content (compound mode)',
- menuWidth: 'custom menu width',
- size: 'menu item size (sm/md/lg)',
- hasAutoFocus: 'auto-focus first item on open; false for showcases',
- isDisabled: 'when true, shows native context menu instead',
- },
- },
- {
- name: 'XDSContextMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Context Menu Item',
- description: 're-exported XDSDropdownMenuItem for compound mode',
- propDescriptions: {
- icon: 'icon before label',
- label: 'primary label text',
- description: 'secondary text below label',
- children: 'additional content after label+description',
- xstyle: 'StyleX styles for root container',
- },
- },
- ],
};
diff --git a/packages/core/src/ContextMenu/ContextMenuItem.doc.mjs b/packages/core/src/ContextMenu/ContextMenuItem.doc.mjs
new file mode 100644
index 0000000000..55a1e3e643
--- /dev/null
+++ b/packages/core/src/ContextMenu/ContextMenuItem.doc.mjs
@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ContextMenuItem',
+ subComponentOf: 'ContextMenu',
+ displayName: 'Context Menu Item',
+ isHiddenFromOverview: true,
+ description: 'Menu item component for compound mode. Re-exported from XDSDropdownMenuItem for discoverability.',
+ props: [
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: 'Icon to display before the label.',
+ },
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: 'Primary label text.',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: 'Secondary description text displayed below the label.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Additional content rendered after the label and description.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ContextMenuItem',
+ isHiddenFromOverview: true,
+ displayName: 'Context Menu Item',
+ description: '复合模式的菜单项组件。从 XDSDropdownMenuItem 重新导出以便发现。',
+ props: [
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: '显示在标签前的图标。',
+ },
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: '主标签文本。',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: '显示在标签下方的次要描述文本。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '在标签和描述之后渲染的附加内容。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: '根容器的 StyleX 样式。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'ContextMenuItem',
+ isHiddenFromOverview: true,
+ displayName: 'Context Menu Item',
+ description: 're-exported XDSDropdownMenuItem for compound mode',
+ propDescriptions: {
+ icon: 'icon before label',
+ label: 'primary label text',
+ description: 'secondary text below label',
+ children: 'additional content after label+description',
+ xstyle: 'StyleX styles for root container',
+ },
+};
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index ac6cbd9cb3..32b8bb29aa 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -35,132 +35,65 @@ export const docs = {
{property: 'padding', expand: 'container'},
],
},
- components: [
+ description: 'Modal dialog using the native <dialog> element.',
+ props: [
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ description: 'Whether the dialog is open (required).',
+ required: true,
+ },
{
- name: 'XDSDialog',
- displayName: 'Dialog',
- description: 'Modal dialog using the native <dialog> element.',
- props: [
- {
- name: 'isOpen',
- type: 'boolean',
- description: 'Whether the dialog is open (required).',
- required: true,
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => unknown',
- description: 'Callback when dialog visibility changes (required).',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Dialog content.',
- required: true,
- },
- {
- name: 'width',
- type: 'number | string',
- description: 'Width of the dialog in pixels or any CSS value.',
- default: '400',
- },
- {
- name: 'maxHeight',
- type: 'number | string',
- description: 'Maximum height of the dialog.',
- default: "'75vh'",
- },
- {
- name: 'position',
- type: 'XDSDialogPosition',
- description:
- 'Static position for the dialog; centered by default when omitted.',
- },
- {
- name: 'variant',
- type: "'standard' | 'fullscreen'",
- description:
- 'Dialog variant: fullscreen expands to fill the entire viewport.',
- default: "'standard'",
- },
- {
- name: 'purpose',
- type: "'required' | 'form' | 'info'",
- description:
- 'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',
- default: "'info'",
- },
- {
- name: 'isInline',
- type: 'boolean',
- description:
- 'Renders dialog content inline without the <dialog> element, backdrop, modal behavior, or dialog autofocus. For documentation previews and showcases only.',
- default: 'false',
- },
- ], },
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => unknown',
+ description: 'Callback when dialog visibility changes (required).',
+ required: true,
+ },
{
- name: 'XDSDialogHeader',
- isHiddenFromOverview: true,
- displayName: 'Dialog Header',
- description:
- 'Header for dialogs with a title, optional subtitle, close button, and start/end content slots.',
- props: [
- {
- name: 'title',
- type: 'string',
- description: 'Dialog title (receives focus on open in modal dialogs; suppressed for inline previews).',
- },
- {
- name: 'subtitle',
- type: 'string',
- description: 'Subtitle below the title.',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => unknown',
- description:
- 'Close button callback (no button if omitted).',
- },
- {
- name: 'startContent',
- type: 'ReactNode',
- description:
- 'Content before the title (e.g., a back button).',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- 'Content after the title, before close button.',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description: 'Adds border at the bottom edge.',
- default: 'true',
- },
- ],
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Dialog content.',
+ required: true,
},
{
- 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.',
- 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.'},
- ],
+ name: 'width',
+ type: 'number | string',
+ description: 'Width of the dialog in pixels or any CSS value.',
+ default: '400',
},
+ {
+ name: 'maxHeight',
+ type: 'number | string',
+ description: 'Maximum height of the dialog.',
+ default: "'75vh'",
+ },
+ {
+ name: 'position',
+ type: 'XDSDialogPosition',
+ description: 'Static position for the dialog; centered by default when omitted.',
+ },
+ {
+ name: 'variant',
+ type: "'standard' | 'fullscreen'",
+ description: 'Dialog variant — fullscreen expands to fill the entire viewport.',
+ default: "'standard'",
+ },
+ {
+ name: 'purpose',
+ type: "'required' | 'form' | 'info'",
+ description: 'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',
+ default: "'info'",
+ },
+ {
+ name: 'isInline',
+ type: 'boolean',
+ description: 'Renders dialog content inline without the <dialog> element, backdrop, or modal behavior. For documentation previews and showcases only.',
+ default: 'false',
+ },
+ ],
+ components: [
+ {name: 'XDSDialogHeader'},
+ {name: 'useXDSImperativeDialog'},
],
usage: {
description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.\n\nFor cases where you want to show a dialog without managing open state, use the `useXDSImperativeDialog` hook: call `dialog.show(content)` and render `dialog.element` in your tree.',
@@ -182,125 +115,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Dialog',
- displayName: 'Dialog',
- theming: {
- container: true,
- targets: [
- {className: 'xds-dialog', visualProps: ['variant']},
- ],
- vars: [
- {name: '--_dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)', private: true},
- ],
- derived: [
- {property: 'borderRadius', vars: ['--_dialog-radius']},
- {property: 'padding', expand: 'container'},
- ],
- },
- components: [
- {
- name: 'XDSDialog',
- displayName: 'Dialog',
- description: '使用原生 <dialog> 元素的模态对话框。',
- props: [
- {
- name: 'isOpen',
- type: 'boolean',
- description: '对话框是否打开(必填)。',
- required: true,
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => unknown',
- description: '对话框可见性变化时的回调(必填)。',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '对话框内容。',
- required: true,
- },
- {
- name: 'width',
- type: 'number | string',
- description: '对话框的宽度,单位为像素或任意 CSS 值。',
- default: '400',
- },
- {
- name: 'maxHeight',
- type: 'number | string',
- description: '对话框的最大高度。',
- default: "'75vh'",
- },
- {
- name: 'position',
- type: 'XDSDialogPosition',
- description:
- '对话框的静态定位;省略时默认居中。',
- },
- {
- name: 'variant',
- type: "'standard' | 'fullscreen'",
- description:
- '对话框变体 - fullscreen 会扩展至填满整个视口。',
- default: "'standard'",
- },
- {
- name: 'purpose',
- type: "'required' | 'form' | 'info'",
- description:
- '控制关闭行为:required 禁用 Escape 和遮罩层点击;form 在交互后禁用遮罩层点击;info 两者都允许。',
- default: "'info'",
- },
- ],
- },
- {
- name: 'XDSDialogHeader',
- isHiddenFromOverview: true,
- displayName: 'Dialog Header',
- description:
- '对话框头部,包含标题、可选副标题、关闭按钮以及首尾内容插槽。',
- props: [
- {
- name: 'title',
- type: 'string',
- description: '对话框标题(打开时获得焦点)。',
- },
- {
- name: 'subtitle',
- type: 'string',
- description: '标题下方的副标题。',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => unknown',
- description:
- '关闭按钮的回调(省略时不显示按钮)。',
- },
- {
- name: 'startContent',
- type: 'ReactNode',
- description:
- '标题之前的内容(例如返回按钮)。',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- '标题之后、关闭按钮之前的内容。',
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description: '在底部边缘添加分隔线。',
- default: 'true',
- },
- ],
- },
- ],
usage: {
description: 'Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.',
bestPractices: [
@@ -336,46 +152,4 @@ export const docsDense = {
{ guidance: false, description: 'Use the fullscreen variant for simple confirmations; it\'s meant for complex content like editors or long forms.' },
],
},
- components: [
- {
- name: 'XDSDialog',
- displayName: 'Dialog',
- description: 'modal dialog using native <dialog>',
- propDescriptions: {
- isOpen: 'dialog open state',
- onOpenChange: 'callback on visibility change',
- children: 'dialog content',
- width: 'dialog width (px or CSS)',
- maxHeight: 'max dialog height',
- position: 'static position; centered by default',
- variant: 'standard or fullscreen (fills viewport)',
- purpose: 'dismissal behavior: required=no dismiss; form=no backdrop after interaction; info=both allowed',
- isInline: 'inline docs/showcase rendering; no <dialog>, backdrop, modal behavior, or dialog autofocus',
- },
- },
- {
- name: 'XDSDialogHeader',
- isHiddenFromOverview: true,
- displayName: 'Dialog Header',
- description: 'dialog header w/ title, optional subtitle, close button, start/end content slots',
- propDescriptions: {
- title: 'dialog title (receives focus on open in modal dialogs; suppressed inline)',
- subtitle: 'subtitle below title',
- onOpenChange: 'close button callback (omit=no button)',
- startContent: 'content before title (e.g. back button)',
- endContent: 'content after title, before close button',
- hasDivider: 'bottom border',
- },
- },
- {
- name: 'useXDSImperativeDialog',
- description: 'hook to show a dialog w/o managing open state; call dialog.show(content, options) to open + dialog.hide() to close; render dialog.element in your JSX tree',
- propDescriptions: {
- show: 'show the dialog with given content; options = XDSDialog props minus isOpen/onOpenChange/children',
- hide: 'hide the dialog',
- isOpen: 'whether the dialog is currently open',
- element: 'the dialog element: render this in your JSX tree',
- },
- },
- ],
};
diff --git a/packages/core/src/Dialog/DialogHeader.doc.mjs b/packages/core/src/Dialog/DialogHeader.doc.mjs
new file mode 100644
index 0000000000..529ac50b2c
--- /dev/null
+++ b/packages/core/src/Dialog/DialogHeader.doc.mjs
@@ -0,0 +1,123 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'DialogHeader',
+ subComponentOf: 'Dialog',
+ displayName: 'Dialog Header',
+ isHiddenFromOverview: true,
+ description: 'Header for dialogs with a title, optional subtitle, close button, and start/end content slots.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Dialog title (receives focus on open).',
+ },
+ {
+ name: 'subtitle',
+ type: 'string',
+ description: 'Subtitle below the title.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => unknown',
+ description: 'Close button callback (no button if omitted).',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description: 'Content before the title (e.g., a back button).',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Content after the title, before close button.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
+ },
+ {
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
+ },
+ ],
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Adds border at the bottom edge.',
+ default: 'true',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'DialogHeader',
+ isHiddenFromOverview: true,
+ displayName: 'Dialog Header',
+ description: '对话框头部,包含标题、可选副标题、关闭按钮以及首尾内容插槽。',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: '对话框标题(打开时获得焦点)。',
+ },
+ {
+ name: 'subtitle',
+ type: 'string',
+ description: '标题下方的副标题。',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => unknown',
+ description: '关闭按钮的回调(省略时不显示按钮)。',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description: '标题之前的内容(例如返回按钮)。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '标题之后、关闭按钮之前的内容。',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: '在底部边缘添加分隔线。',
+ default: 'true',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'DialogHeader',
+ isHiddenFromOverview: true,
+ displayName: 'Dialog Header',
+ description: 'dialog header w/ title, optional subtitle, close button, start/end content slots',
+ propDescriptions: {
+ title: 'dialog title (receives focus on open)',
+ subtitle: 'subtitle below title',
+ onOpenChange: 'close button callback (omit=no button)',
+ startContent: 'content before title (e.g. back button)',
+ endContent: 'content after title, before close button',
+ hasDivider: 'bottom border',
+ },
+};
diff --git a/packages/core/src/Dialog/useXDSImperativeDialog.doc.mjs b/packages/core/src/Dialog/useXDSImperativeDialog.doc.mjs
new file mode 100644
index 0000000000..42c852fa51
--- /dev/null
+++ b/packages/core/src/Dialog/useXDSImperativeDialog.doc.mjs
@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSImperativeDialog',
+ subComponentOf: 'Dialog',
+ 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.',
+ },
+ {
+ 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.',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSImperativeDialog',
+ description: 'hook to show a dialog w/o managing open state; call dialog.show(content, options) to open + dialog.hide() to close; render dialog.element in your JSX tree',
+ propDescriptions: {
+ show: 'show the dialog with given content; options = XDSDialog props minus isOpen/onOpenChange/children',
+ hide: 'hide the dialog',
+ isOpen: 'whether the dialog is currently open',
+ element: 'the dialog element — render this in your JSX tree',
+ },
+};
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index e997e67607..95340245c6 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -22,109 +22,61 @@ export const docs = {
{property: 'padding', vars: ['--_dropdown-menu-padding']},
],
},
- components: [
+ description: 'Main dropdown menu component with a trigger button and popup item list.',
+ props: [
+ {
+ name: 'button',
+ type: 'XDSDropdownMenuButtonProps',
+ description: 'Props for the trigger button (XDSButton props except onClick).',
+ default: "{ label: 'Menu' }",
+ },
+ {
+ name: 'items',
+ type: 'XDSDropdownMenuOption[]',
+ description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?}`, a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
+ required: true,
+ },
+ {
+ name: 'isMenuOpen',
+ type: 'boolean',
+ description: 'Controlled open state for the menu.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback fired when the open state changes.',
+ },
+ {
+ name: 'menuWidth',
+ type: 'number | string',
+ description: 'Custom menu width; defaults to matching the trigger button width.',
+ },
+ {
+ name: 'onClick',
+ type: '() => void',
+ description: 'Callback fired when the trigger button is clicked.',
+ },
+ {
+ name: 'hasChevron',
+ type: 'boolean',
+ description: 'Whether to show a chevron icon on the trigger button. Set to false for icon-only triggers.',
+ default: 'true',
+ },
{
- name: 'XDSDropdownMenu',
- displayName: 'Dropdown Menu',
- description:
- 'Main dropdown menu component with a trigger button and popup item list.',
- props: [
- {
- name: 'button',
- type: 'XDSDropdownMenuButtonProps',
- description:
- 'Props for the trigger button (XDSButton props except onClick).',
- default: "{ label: 'Menu' }",
- },
- {
- name: 'items',
- type: 'XDSDropdownMenuOption[]',
- description:
- 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?}`, a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
- required: true,
- },
- {
- name: 'isMenuOpen',
- type: 'boolean',
- description: 'Controlled open state for the menu.',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description: 'Callback fired when the open state changes.',
- },
- {
- name: 'menuWidth',
- type: 'number | string',
- description:
- 'Custom menu width; defaults to matching the trigger button width.',
- },
- {
- name: 'placement',
- type: "'above' | 'below' | 'start' | 'end'",
- description:
- 'Menu placement relative to the trigger. Defaults below; the layer automatically flips when there is not enough viewport space.',
- default: "'below'",
- },
- {
- name: 'onClick',
- type: '() => void',
- description: 'Callback fired when the trigger button is clicked.',
- },
- {
- name: 'hasChevron',
- type: 'boolean',
- description: 'Whether to show a chevron icon on the trigger button. Set to false for icon-only triggers.',
- default: 'true',
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases or documentation previews.',
- default: 'true',
- },
- {
- name: 'children',
- type: '(item: XDSDropdownMenuItemData) => ReactNode',
- description: 'Custom render function for each item in the list.',
- },
- ], },
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases or documentation previews.',
+ default: 'true',
+ },
{
- name: 'XDSDropdownMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Dropdown Menu Item',
- description:
- 'Helper component for custom item rendering with consistent styling.',
- props: [
- {
- name: 'icon',
- type: 'XDSIconType',
- description: 'Icon to display before the label. See `npx xds docs icons` for valid semantic names.',
- },
- {
- name: 'label',
- type: 'ReactNode',
- description: 'Primary label text.',
- },
- {
- name: 'description',
- type: 'ReactNode',
- description: 'Secondary description text displayed below the label.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Additional content rendered after the label and description.',
- },
- {
- 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={{}}.',
- },
- ],
+ name: 'children',
+ type: '(item: XDSDropdownMenuItemData) => ReactNode',
+ description: 'Custom render function for each item in the list.',
},
],
+ components: [
+ {name: 'XDSDropdownMenuItem'},
+ ],
usage: {
description: 'A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface.',
bestPractices: [
@@ -136,128 +88,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'DropdownMenu',
- displayName: 'Dropdown Menu',
- theming: {
- targets: [
- {className: 'xds-dropdown-menu'},
- {className: 'xds-dropdown-menu-item'},
- ],
- vars: [
- {name: '--_dropdown-menu-radius', description: 'Border radius of the menu popup', default: 'var(--radius-element)', private: true},
- {name: '--_dropdown-menu-padding', description: 'Inner padding of the menu popup', default: 'var(--spacing-1)', private: true},
- ],
- derived: [
- {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},
- {property: 'padding', vars: ['--_dropdown-menu-padding']},
- ],
- },
- components: [
- {
- name: 'XDSDropdownMenu',
- displayName: 'Dropdown Menu',
- description:
- '主下拉菜单组件,包含触发按钮和弹出项列表。',
- props: [
- {
- name: 'button',
- type: 'XDSDropdownMenuButtonProps',
- description:
- '触发按钮的属性(XDSButton 属性,不含 onClick)。',
- default: "{ label: 'Menu' }",
- },
- {
- name: 'items',
- type: 'XDSDropdownMenuOption[]',
- description:
- '菜单项数组。每项为:操作项 `{label, onClick?, icon?, isDisabled?}`、分隔线 `{type: "divider"}`、或分组 `{type: "section", title?, items: [...操作项]}`。',
- required: true,
- },
- {
- name: 'isMenuOpen',
- type: 'boolean',
- description: '菜单的受控打开状态。',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description: '打开状态变化时触发的回调。',
- },
- {
- name: 'menuWidth',
- type: 'number | string',
- description:
- '自定义菜单宽度;默认与触发按钮同宽。',
- },
- {
- name: 'placement',
- type: "'above' | 'below' | 'start' | 'end'",
- description:
- '菜单相对于触发器的位置。默认在下方;当视口空间不足时图层会自动翻转。',
- default: "'below'",
- },
- {
- name: 'onClick',
- type: '() => void',
- description: '点击触发按钮时触发的回调。',
- },
- {
- name: 'hasChevron',
- type: 'boolean',
- description: '是否在触发按钮上显示展开箭头。仅图标触发器设为 false。',
- default: 'true',
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: '菜单打开时是否自动聚焦第一个菜单项。内联展示或文档预览设为 false。',
- default: 'true',
- },
- {
- name: 'children',
- type: '(item: XDSDropdownMenuItemData) => ReactNode',
- description: '列表中每个项的自定义渲染函数。',
- },
- ],
- },
- {
- name: 'XDSDropdownMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Dropdown Menu Item',
- description:
- '用于自定义项渲染的辅助组件,提供一致的样式。',
- props: [
- {
- name: 'icon',
- type: 'XDSIconType',
- description: '显示在标签前的图标。',
- },
- {
- name: 'label',
- type: 'ReactNode',
- description: '主标签文本。',
- },
- {
- name: 'description',
- type: 'ReactNode',
- description: '显示在标签下方的次要描述文本。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- '在标签和描述之后渲染的附加内容。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description: '根容器的 StyleX 样式。',
- },
- ],
- },
- ],
usage: {
description: 'A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface.',
bestPractices: [
@@ -281,36 +113,4 @@ export const docsDense = {
{ guidance: false, description: 'Place more than 10–12 items in a single menu without grouping them into sections.' },
],
},
- components: [
- {
- name: 'XDSDropdownMenu',
- displayName: 'Dropdown Menu',
- description: 'trigger button + popup item list',
- propDescriptions: {
- button: 'trigger button props (XDSButton props except onClick)',
- items: 'array of menu entries: action item {label, onClick?, icon?, isDisabled?}, divider {type: "divider"}, or section {type: "section", title?, items: [...]}',
- isMenuOpen: 'controlled open state',
- onOpenChange: 'callback on open state change',
- menuWidth: 'custom menu width; default matches trigger button',
- placement: 'menu placement relative to trigger; default below with viewport auto-flip',
- onClick: 'trigger button click callback',
- hasChevron: 'show chevron on trigger; false for icon-only triggers',
- hasAutoFocus: 'auto-focus first item on open; false for showcases',
- children: 'custom render fn per item',
- },
- },
- {
- name: 'XDSDropdownMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Dropdown Menu Item',
- description: 'helper for custom item rendering w/ consistent styling',
- propDescriptions: {
- icon: 'icon before label',
- label: 'primary label text',
- description: 'secondary text below label',
- children: 'additional content after label+description',
- xstyle: 'StyleX styles for root container',
- },
- },
- ],
};
diff --git a/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
new file mode 100644
index 0000000000..3fff805dde
--- /dev/null
+++ b/packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'DropdownMenuItem',
+ subComponentOf: 'DropdownMenu',
+ displayName: 'Dropdown Menu Item',
+ isHiddenFromOverview: true,
+ description: 'Helper component for custom item rendering with consistent styling.',
+ props: [
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: 'Icon to display before the label. See `npx xds docs icons` for valid semantic names.',
+ },
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: 'Primary label text.',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: 'Secondary description text displayed below the label.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Additional content rendered after the label and description.',
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'DropdownMenuItem',
+ isHiddenFromOverview: true,
+ displayName: 'Dropdown Menu Item',
+ description: '用于自定义项渲染的辅助组件,提供一致的样式。',
+ props: [
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: '显示在标签前的图标。',
+ },
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: '主标签文本。',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: '显示在标签下方的次要描述文本。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '在标签和描述之后渲染的附加内容。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: '根容器的 StyleX 样式。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'DropdownMenuItem',
+ isHiddenFromOverview: true,
+ displayName: 'Dropdown Menu Item',
+ description: 'helper for custom item rendering w/ consistent styling',
+ propDescriptions: {
+ icon: 'icon before label',
+ label: 'primary label text',
+ description: 'secondary text below label',
+ children: 'additional content after label+description',
+ xstyle: 'StyleX styles for root container',
+ },
+};
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index 15bcc768cb..ebaa617df3 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -27,210 +27,106 @@ export const docs = {
{property: 'borderRadius', vars: ['--_field-radius']},
],
},
- components: [
+ description: 'Form field wrapper that provides label, description, and optional/required indicators.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for the field (always rendered for accessibility).',
+ required: true,
+ },
+ {
+ name: 'inputID',
+ type: 'string',
+ description: 'ID for the input element (used for the label htmlFor attribute).',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'The input or control to render.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hide the label (still accessible to screen readers).',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the associated input is disabled. Propagates disabled styling to the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed between the label and input.',
+ },
+ {
+ name: 'descriptionID',
+ type: 'string',
+ description: 'ID for the description element (use for aria-describedby on the input).',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Whether the field is optional (mutually exclusive with isRequired).',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Whether the field is required (mutually exclusive with isOptional).',
+ default: 'false',
+ },
+ {
+ name: 'labelIcon',
+ type: 'XDSIconType',
+ description: 'Icon to display before the label text. See `npx xds docs icons` for valid semantic names.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text to display in an info icon at the end of the label.',
+ },
+ {
+ name: 'status',
+ type: 'XDSFieldStatus',
+ description: 'Status indicator with type and optional message. When message is set, displays a colored status box.',
+ },
+ {
+ name: 'statusVariant',
+ type: "'attached' | 'detached'",
+ description: 'How the status message renders relative to the input. Attached overlaps the input border; detached floats below.',
+ default: "'attached'",
+ },
+ {
+ name: 'ref',
+ type: 'React.Ref<HTMLDivElement>',
+ description: 'Ref forwarded to the root element.',
+ },
{
- name: 'XDSField',
- displayName: 'Field',
- description:
- 'Form field wrapper that provides label, description, and optional/required indicators.', props: [
- {
- name: 'label',
- type: 'string',
- description:
- 'Label text for the field (always rendered for accessibility).',
- required: true,
- },
- {
- name: 'inputID',
- type: 'string',
- description:
- 'ID for the input element (used for the label htmlFor attribute).',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'The input or control to render.',
- required: true,
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description:
- 'Visually hide the label (still accessible to screen readers).',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description:
- 'Whether the associated input is disabled. Propagates disabled styling to the label.',
- default: 'false',
- },
- {
- name: 'description',
- type: 'string',
- description:
- 'Description text displayed between the label and input.',
- },
- {
- name: 'descriptionID',
- type: 'string',
- description:
- 'ID for the description element (use for aria-describedby on the input).',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description:
- 'Whether the field is optional (mutually exclusive with isRequired).',
- default: 'false',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description:
- 'Whether the field is required (mutually exclusive with isOptional).',
- default: 'false',
- },
- {
- name: 'labelIcon',
- type: 'XDSIconType',
- description: 'Icon to display before the label text. See `npx xds docs icons` for valid semantic names.',
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description:
- 'Tooltip text to display in an info icon at the end of the label.',
- },
- {
- name: 'status',
- type: 'XDSFieldStatus',
- description:
- 'Status indicator with type and optional message. When message is set, displays a colored status box.',
- },
- {
- name: 'statusVariant',
- type: "'attached' | 'detached'",
- description:
- 'How the status message renders relative to the input. Attached overlaps the input border; detached floats below.',
- default: "'attached'",
- },
- {
- name: 'ref',
- type: 'React.Ref<HTMLDivElement>',
- description: 'Ref forwarded to the root element.',
- },
- {
- 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={{}}.',
- },
- {
- name: 'className',
- type: 'string',
- description:
- 'CSS class name(s) appended to the root element. Prefer xstyle for StyleX deduplication.',
- },
- {
- name: 'style',
- type: 'React.CSSProperties',
- description:
- 'Inline styles applied to the root element. Takes priority over StyleX inline styles.',
- },
- ],
+ 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={{}}.',
},
{
- name: 'XDSFieldLabel',
- isHiddenFromOverview: true,
- displayName: 'Field Label',
- description:
- 'Standalone label component with optional/required indicators and tooltip support.',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Label text.',
- required: true,
- },
- {
- name: 'inputID',
- type: 'string',
- description: 'ID of the input this label is for.',
- required: true,
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: 'Visually hide the label.',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether the associated input is disabled.',
- default: 'false',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description: 'Show "Optional" indicator.',
- default: 'false',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description: 'Show "Required" indicator.',
- default: 'false',
- },
- {
- name: 'labelIcon',
- type: 'XDSIconType',
- description: 'Icon before the label text. See `npx xds docs icons` for valid semantic names.',
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description: 'Tooltip text for info icon at end of label.',
- },
- ],
+ name: 'className',
+ type: 'string',
+ description: 'CSS class name(s) appended to the root element. Prefer xstyle for StyleX deduplication.',
},
{
- name: 'XDSFieldStatus',
- isHiddenFromOverview: true,
- displayName: 'Field Status',
- description:
- 'Status message component for form field validation feedback.',
- props: [
- {
- name: 'type',
- type: "'error' | 'warning' | 'success'",
- description: 'Status type.',
- required: true,
- },
- {
- name: 'message',
- type: 'string',
- description: 'Status message text.',
- required: true,
- },
- {
- name: 'id',
- type: 'string',
- description: 'ID for aria-describedby association.',
- },
- {
- name: 'variant',
- type: "'attached' | 'detached'",
- description:
- 'Visual variant: attached overlaps the input, detached floats below.',
- default: "'attached'",
- },
- ],
+ name: 'style',
+ type: 'React.CSSProperties',
+ description: 'Inline styles applied to the root element. Takes priority over StyleX inline styles.',
},
],
+ components: [
+ {name: 'XDSFieldLabel'},
+ {name: 'XDSFieldStatus'},
+ ],
usage: {
description: 'Field wraps any input control with a label, description, and validation status. Use it to build accessible forms with consistent labeling, optional/required indicators, and inline error, warning, or success feedback.',
bestPractices: [
@@ -252,228 +148,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Field',
- displayName: 'Field',
- theming: {
- targets: [
- {className: 'xds-field'},
- {className: 'xds-field-label'},
- {className: 'xds-field-status', visualProps: ['type', 'variant']},
- ],
- vars: [
- {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},
- ],
- derived: [
- {property: 'borderRadius', vars: ['--_field-radius']},
- ],
- },
- components: [
- {
- name: 'XDSField',
- displayName: 'Field',
- description:
- '表单字段包装器,提供标签、描述以及可选/必填指示器。',
- props: [
- {
- name: 'label',
- type: 'string',
- description:
- '字段的标签文本(始终渲染以确保无障碍访问)。',
- required: true,
- },
- {
- name: 'inputID',
- type: 'string',
- description:
- '输入元素的 ID(用于标签的 htmlFor 属性)。',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '要渲染的输入框或控件。',
- required: true,
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description:
- '视觉隐藏标签(屏幕阅读器仍可访问)。',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description:
- '关联的输入框是否禁用。将禁用样式传递给标签。',
- default: 'false',
- },
- {
- name: 'description',
- type: 'string',
- description:
- '显示在标签和输入框之间的描述文本。',
- },
- {
- name: 'descriptionID',
- type: 'string',
- description:
- '描述元素的 ID(用于输入框的 aria-describedby)。',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description:
- '字段是否可选(与 isRequired 互斥)。',
- default: 'false',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description:
- '字段是否必填(与 isOptional 互斥)。',
- default: 'false',
- },
- {
- name: 'labelIcon',
- type: 'XDSIconType',
- description: '显示在标签文本前的图标。',
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description:
- '在标签末尾的信息图标中显示的工具提示文本。',
- },
- {
- name: 'status',
- type: 'XDSFieldStatus',
- description:
- '状态指示器,包含类型和可选消息。设置消息时显示彩色状态框。',
- },
- {
- name: 'statusVariant',
- type: "'attached' | 'detached'",
- description:
- '状态消息相对于输入框的渲染方式。attached 覆盖输入框边框;detached 浮动在下方。',
- default: "'attached'",
- },
- {
- name: 'ref',
- type: 'React.Ref<HTMLDivElement>',
- description: '转发到根元素的 ref。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义(外边距、定位、尺寸)的 StyleX 样式。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- {
- name: 'className',
- type: 'string',
- description:
- '附加到根元素的 CSS 类名。优先使用 xstyle 以获得 StyleX 样式去重。',
- },
- {
- name: 'style',
- type: 'React.CSSProperties',
- description:
- '应用到根元素的内联样式。优先于 StyleX 内联样式。',
- },
- ],
- },
- {
- name: 'XDSFieldLabel',
- isHiddenFromOverview: true,
- displayName: 'Field Label',
- description:
- '独立的标签组件,支持可选/必填指示器和工具提示。',
- props: [
- {
- name: 'label',
- type: 'string',
- description: '标签文本。',
- required: true,
- },
- {
- name: 'inputID',
- type: 'string',
- description: '此标签关联的输入框 ID。',
- required: true,
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: '视觉隐藏标签。',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '关联的输入框是否禁用。',
- default: 'false',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description: '显示"Optional"指示器。',
- default: 'false',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description: '显示"Required"指示器。',
- default: 'false',
- },
- {
- name: 'labelIcon',
- type: 'XDSIconType',
- description: '标签文本前的图标。',
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description: '标签末尾信息图标的工具提示文本。',
- },
- ],
- },
- {
- name: 'XDSFieldStatus',
- isHiddenFromOverview: true,
- displayName: 'Field Status',
- description:
- '用于表单字段验证反馈的状态消息组件。',
- props: [
- {
- name: 'type',
- type: "'error' | 'warning' | 'success'",
- description: '状态类型。',
- required: true,
- },
- {
- name: 'message',
- type: 'string',
- description: '状态消息文本。',
- required: true,
- },
- {
- name: 'id',
- type: 'string',
- description: '用于 aria-describedby 关联的 ID。',
- },
- {
- name: 'variant',
- type: "'attached' | 'detached'",
- description:
- '视觉变体 - attached 覆盖在输入框上,detached 浮动在下方。',
- default: "'attached'",
- },
- ],
- },
- ],
usage: {
description: 'Field wraps any input control with a label, description, and validation status. Use it to build accessible forms with consistent labeling, optional/required indicators, and inline error, warning, or success feedback.',
bestPractices: [
@@ -502,58 +178,4 @@ export const docsDense = {
{ guidance: false, description: 'Hide the label without providing an alternative way for user to understand the field purpose.' },
],
},
- components: [
- {
- name: 'XDSField',
- displayName: 'Field',
- description: 'Form field wrapper w/ label, description + optional/required indicators.',
- propDescriptions: {
- label: 'Label text for field (always rendered for a11y).',
- inputID: 'Input element ID (used for label htmlFor).',
- children: 'Input or control to render.',
- isLabelHidden: 'Visually hide label (still accessible to screen readers).',
- isDisabled: 'Associated input disabled. Propagates disabled styling to label.',
- description: 'Description text between label + input.',
- descriptionID: 'ID for description element (use for aria-describedby on input).',
- isOptional: 'Field optional (mutually exclusive w/ isRequired).',
- isRequired: 'Field required (mutually exclusive w/ isOptional).',
- labelIcon: 'Icon before label text.',
- labelTooltip: 'Tooltip text in info icon at end of label.',
- status: 'Status indicator w/ type + optional message. Shows colored status box.',
- statusVariant: 'Status render mode; attached overlaps input, detached floats below.',
- ref: 'Ref forwarded to root element.',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
- className: 'CSS class name(s) appended to root element.',
- style: 'Inline styles applied to root element.',
- },
- },
- {
- name: 'XDSFieldLabel',
- isHiddenFromOverview: true,
- displayName: 'Field Label',
- description: 'Standalone label w/ optional/required indicators + tooltip support.',
- propDescriptions: {
- label: 'Label text.',
- inputID: 'ID of input this label is for.',
- isLabelHidden: 'Visually hide label.',
- isDisabled: 'Associated input disabled.',
- isOptional: 'Show "Optional" indicator.',
- isRequired: 'Show "Required" indicator.',
- labelIcon: 'Icon before label text.',
- labelTooltip: 'Tooltip text for info icon at end of label.',
- },
- },
- {
- name: 'XDSFieldStatus',
- isHiddenFromOverview: true,
- displayName: 'Field Status',
- description: 'Status message for form field validation feedback.',
- propDescriptions: {
- type: 'Status type.',
- message: 'Status message text.',
- id: 'ID for aria-describedby association.',
- variant: 'Visual variant; attached overlaps input, detached floats below.',
- },
- },
- ],
};
diff --git a/packages/core/src/Field/FieldLabel.doc.mjs b/packages/core/src/Field/FieldLabel.doc.mjs
new file mode 100644
index 0000000000..fba918c981
--- /dev/null
+++ b/packages/core/src/Field/FieldLabel.doc.mjs
@@ -0,0 +1,131 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'FieldLabel',
+ subComponentOf: 'Field',
+ displayName: 'Field Label',
+ isHiddenFromOverview: true,
+ description: 'Standalone label component with optional/required indicators and tooltip support.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text.',
+ required: true,
+ },
+ {
+ name: 'inputID',
+ type: 'string',
+ description: 'ID of the input this label is for.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the associated input is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Show "Optional" indicator.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Show "Required" indicator.',
+ default: 'false',
+ },
+ {
+ name: 'labelIcon',
+ type: 'XDSIconType',
+ description: 'Icon before the label text. See `npx xds docs icons` for valid semantic names.',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text for info icon at end of label.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'FieldLabel',
+ isHiddenFromOverview: true,
+ displayName: 'Field Label',
+ description: '独立的标签组件,支持可选/必填指示器和工具提示。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '标签文本。',
+ required: true,
+ },
+ {
+ name: 'inputID',
+ type: 'string',
+ description: '此标签关联的输入框 ID。',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: '视觉隐藏标签。',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '关联的输入框是否禁用。',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: '显示"Optional"指示器。',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: '显示"Required"指示器。',
+ default: 'false',
+ },
+ {
+ name: 'labelIcon',
+ type: 'XDSIconType',
+ description: '标签文本前的图标。',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: '标签末尾信息图标的工具提示文本。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'FieldLabel',
+ isHiddenFromOverview: true,
+ displayName: 'Field Label',
+ description: 'Standalone label w/ optional/required indicators + tooltip support.',
+ propDescriptions: {
+ label: 'Label text.',
+ inputID: 'ID of input this label is for.',
+ isLabelHidden: 'Visually hide label.',
+ isDisabled: 'Associated input disabled.',
+ isOptional: 'Show "Optional" indicator.',
+ isRequired: 'Show "Required" indicator.',
+ labelIcon: 'Icon before label text.',
+ labelTooltip: 'Tooltip text for info icon at end of label.',
+ },
+};
diff --git a/packages/core/src/Field/FieldStatus.doc.mjs b/packages/core/src/Field/FieldStatus.doc.mjs
new file mode 100644
index 0000000000..f9eb5b48bc
--- /dev/null
+++ b/packages/core/src/Field/FieldStatus.doc.mjs
@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'FieldStatus',
+ subComponentOf: 'Field',
+ displayName: 'Field Status',
+ isHiddenFromOverview: true,
+ description: 'Status message component for form field validation feedback.',
+ props: [
+ {
+ name: 'type',
+ type: "'error' | 'warning' | 'success'",
+ description: 'Status type.',
+ required: true,
+ },
+ {
+ name: 'message',
+ type: 'string',
+ description: 'Status message text.',
+ required: true,
+ },
+ {
+ name: 'id',
+ type: 'string',
+ description: 'ID for aria-describedby association.',
+ },
+ {
+ name: 'variant',
+ type: "'attached' | 'detached'",
+ description: 'Visual variant — attached overlaps the input, detached floats below.',
+ default: "'attached'",
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'FieldStatus',
+ isHiddenFromOverview: true,
+ displayName: 'Field Status',
+ description: '用于表单字段验证反馈的状态消息组件。',
+ props: [
+ {
+ name: 'type',
+ type: "'error' | 'warning' | 'success'",
+ description: '状态类型。',
+ required: true,
+ },
+ {
+ name: 'message',
+ type: 'string',
+ description: '状态消息文本。',
+ required: true,
+ },
+ {
+ name: 'id',
+ type: 'string',
+ description: '用于 aria-describedby 关联的 ID。',
+ },
+ {
+ name: 'variant',
+ type: "'attached' | 'detached'",
+ description: '视觉变体 - attached 覆盖在输入框上,detached 浮动在下方。',
+ default: "'attached'",
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'FieldStatus',
+ isHiddenFromOverview: true,
+ displayName: 'Field Status',
+ description: 'Status message for form field validation feedback.',
+ propDescriptions: {
+ type: 'Status type.',
+ message: 'Status message text.',
+ id: 'ID for aria-describedby association.',
+ variant: 'Visual variant; attached overlaps input, detached floats below.',
+ },
+};
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index aaaf4cafb3..0b30ae5138 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -25,202 +25,73 @@ export const docs = {
{className: 'xds-grid-span'},
],
},
- components: [
+ description: 'Grid container with fixed or responsive columns.',
+ props: [
{
- name: 'XDSGrid',
- displayName: 'Grid',
- description: 'Grid container with fixed or responsive columns.',
- props: [
- {
- name: 'columns',
- type: "number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}",
- description:
- 'Column configuration. Use a number for fixed columns (e.g. `columns={3}`). Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.',
- },
- {
- name: 'minChildWidth',
- type: 'number',
- description:
- 'Deprecated; use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.',
- },
- {
- name: 'width',
- type: 'number | string',
- description: 'Container width.',
- },
- {
- name: 'height',
- type: 'number | string',
- description: 'Container height.',
- },
- {
- name: 'gap',
- type: 'SpacingStep',
- description: 'Spacing between all items.',
- },
- {
- name: 'rowGap',
- type: 'SpacingStep',
- description: 'Row spacing; overrides `gap` for the row axis.',
- },
- {
- name: 'columnGap',
- type: 'SpacingStep',
- description: 'Column spacing; overrides `gap` for the column axis.',
- },
- {
- name: 'align',
- type: 'GridAlignment',
- description: 'Vertical alignment of items.',
- default: "'stretch'",
- },
- {
- name: 'justify',
- type: 'GridAlignment',
- description: 'Horizontal alignment of items.',
- default: "'stretch'",
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Grid content.',
- },
- {
- 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={{}}.',
- },
- ],
+ name: 'columns',
+ type: "number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}",
+ description: 'Column configuration. Use a number for fixed columns (e.g. `columns={3}`). Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.',
},
{
- name: 'XDSGridSpan',
- isHiddenFromOverview: true,
- displayName: 'Grid Span',
- description: 'Grid item that spans multiple columns or rows.',
- props: [
- {
- name: 'columns',
- type: "number | 'full'",
- description: "Columns to span; use `'full'` to span the entire row.",
- },
- {
- name: 'rows',
- type: 'number',
- description: 'Rows to span.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Content.',
- },
- ],
+ name: 'minChildWidth',
+ type: 'number',
+ description: 'Deprecated — use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.',
+ },
+ {
+ name: 'width',
+ type: 'number | string',
+ description: 'Container width.',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: 'Container height.',
+ },
+ {
+ name: 'gap',
+ type: 'SpacingStep',
+ description: 'Spacing between all items.',
},
- ],
-};
-
-/** @type {import('../docs-types').ComponentDoc} */
-export const docsZh = {
- name: 'Grid',
- displayName: 'Grid',
- group: 'Layout',
- theming: {
- targets: [
- {className: 'xds-grid', visualProps: ['align', 'columns', 'gap', 'justify']},
- {className: 'xds-grid-span'},
- ],
- },
- components: [
{
- name: 'XDSGrid',
- displayName: 'Grid',
- description: '支持固定列或响应式列的网格容器。',
- props: [
- {
- name: 'columns',
- type: "number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}",
- description:
- '列配置。使用数字表示固定列(如 `columns={3}`)。使用对象表示响应式列:`minWidth` 设置最小列宽(px),`repeat` 控制轨道行为(`"fill"` 保留空轨道保持一致宽度,`"fit"` 折叠空轨道使项目拉伸;默认为 `"fill"`),`max` 限制最大列数。',
- },
- {
- name: 'minChildWidth',
- type: 'number',
- description: '已弃用,请使用 `columns={{minWidth: 280}}` 代替。',
- },
- {
- name: 'width',
- type: 'number | string',
- description: '容器宽度。',
- },
- {
- name: 'height',
- type: 'number | string',
- description: '容器高度。',
- },
- {
- name: 'gap',
- type: 'SpacingStep',
- description: '所有项目之间的间距。',
- },
- {
- name: 'rowGap',
- type: 'SpacingStep',
- description: '行间距;覆盖行轴方向的 `gap`。',
- },
- {
- name: 'columnGap',
- type: 'SpacingStep',
- description: '列间距;覆盖列轴方向的 `gap`。',
- },
- {
- name: 'align',
- type: 'GridAlignment',
- description: '项目的垂直对齐方式。',
- default: "'stretch'",
- },
- {
- name: 'justify',
- type: 'GridAlignment',
- description: '项目的水平对齐方式。',
- default: "'stretch'",
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '网格内容。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义(外边距、定位、尺寸)的 StyleX 样式。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
+ name: 'rowGap',
+ type: 'SpacingStep',
+ description: 'Row spacing; overrides `gap` for the row axis.',
},
{
- name: 'XDSGridSpan',
- isHiddenFromOverview: true,
- displayName: 'Grid Span',
- description: '可跨越多列或多行的网格项。',
- props: [
- {
- name: 'columns',
- type: "number | 'full'",
- description: "要跨越的列数;使用 `'full'` 跨越整行。",
- },
- {
- name: 'rows',
- type: 'number',
- description: '要跨越的行数。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '内容。',
- },
- ],
+ name: 'columnGap',
+ type: 'SpacingStep',
+ description: 'Column spacing; overrides `gap` for the column axis.',
+ },
+ {
+ name: 'align',
+ type: 'GridAlignment',
+ description: 'Vertical alignment of items.',
+ default: "'stretch'",
+ },
+ {
+ name: 'justify',
+ type: 'GridAlignment',
+ description: 'Horizontal alignment of items.',
+ default: "'stretch'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Grid content.',
+ },
+ {
+ 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={{}}.',
},
],
+ components: [
+ {name: 'XDSGridSpan'},
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsZh = {
usage: {
description:
'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
@@ -247,37 +118,4 @@ export const docsDense = {
{ guidance: false, description: 'Use XDSHStack with wrapping for grids; use Grid instead.' },
],
},
-
-
- components: [
- {
- name: 'XDSGrid',
- displayName: 'Grid',
- description: 'Grid container w/ fixed or responsive columns.',
- propDescriptions: {
- columns: "Column config. Number for fixed cols. Object {minWidth, max?, repeat?} for responsive. repeat: 'fill' (default, consistent widths) or 'fit' (stretch).",
- minChildWidth: 'Deprecated; use columns={{minWidth}} instead.',
- width: 'Container width.',
- height: 'Container height.',
- gap: 'Spacing between all items.',
- rowGap: 'Row spacing; overrides gap for row axis.',
- columnGap: 'Column spacing; overrides gap for column axis.',
- align: 'Vertical alignment of items.',
- justify: 'Horizontal alignment of items.',
- children: 'Grid content.',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSGridSpan',
- isHiddenFromOverview: true,
- displayName: 'Grid Span',
- description: 'Grid item spanning multiple columns/rows.',
- propDescriptions: {
- columns: "Columns to span; 'full' spans entire row.",
- rows: 'Rows to span.',
- children: 'Content.',
- },
- },
- ],
};
diff --git a/packages/core/src/Grid/GridSpan.doc.mjs b/packages/core/src/Grid/GridSpan.doc.mjs
new file mode 100644
index 0000000000..11ac332461
--- /dev/null
+++ b/packages/core/src/Grid/GridSpan.doc.mjs
@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'GridSpan',
+ subComponentOf: 'Grid',
+ displayName: 'Grid Span',
+ isHiddenFromOverview: true,
+ description: 'Grid item that spans multiple columns or rows.',
+ props: [
+ {
+ name: 'columns',
+ type: "number | 'full'",
+ description: "Columns to span; use `'full'` to span the entire row.",
+ },
+ {
+ name: 'rows',
+ type: 'number',
+ description: 'Rows to span.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'GridSpan',
+ isHiddenFromOverview: true,
+ displayName: 'Grid Span',
+ description: '可跨越多列或多行的网格项。',
+ props: [
+ {
+ name: 'columns',
+ type: "number | 'full'",
+ description: "要跨越的列数;使用 `'full'` 跨越整行。",
+ },
+ {
+ name: 'rows',
+ type: 'number',
+ description: '要跨越的行数。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '内容。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'GridSpan',
+ isHiddenFromOverview: true,
+ displayName: 'Grid Span',
+ description: 'Grid item spanning multiple columns/rows.',
+ propDescriptions: {
+ columns: "Columns to span; 'full' spans entire row.",
+ rows: 'Rows to span.',
+ children: 'Content.',
+ },
+};
diff --git a/packages/core/src/InputGroup/InputGroup.doc.mjs b/packages/core/src/InputGroup/InputGroup.doc.mjs
index 4d27d18ec7..0e4f22b985 100644
--- a/packages/core/src/InputGroup/InputGroup.doc.mjs
+++ b/packages/core/src/InputGroup/InputGroup.doc.mjs
@@ -14,38 +14,78 @@ export const docs = {
{className: 'xds-input-group', visualProps: ['size', 'status']},
],
},
- components: [
+ description: 'Groups an input with prefix/suffix addons in a visually connected container with shared border and focus ring.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Input and XDSInputGroupText children.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the group.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Helper text between label and input group.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disable the entire group.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Show "(optional)" indicator.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Mark the field as required.',
+ default: 'false',
+ },
{
- name: 'XDSInputGroup',
- displayName: 'Input Group',
- description: 'Groups an input with prefix/suffix addons in a visually connected container with shared border and focus ring.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'Input and XDSInputGroupText children.', required: true},
- {name: 'label', type: 'string', description: 'Accessible label for the group.', required: true},
- {name: 'isLabelHidden', type: 'boolean', description: 'Visually hide the label.', default: 'false'},
- {name: 'description', type: 'string', description: 'Helper text between label and input group.'},
- {name: 'isDisabled', type: 'boolean', description: 'Disable the entire group.', default: 'false'},
- {name: 'isOptional', type: 'boolean', description: 'Show "(optional)" indicator.', default: 'false'},
- {name: 'isRequired', type: 'boolean', description: 'Mark the field as required.', default: 'false'},
- {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Default size for inputs in the group.', default: "'md'"},
- {name: 'status', type: 'XDSInputStatus', description: 'Status indicator applied to the group border.'},
- {name: 'labelTooltip', type: 'string', description: 'Tooltip text at the end of the label.'},
- {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization.'},
- {name: 'data-testid', type: 'string', description: 'Test selector.'},
- ],
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Default size for inputs in the group.',
+ default: "'md'",
},
{
- name: 'XDSInputGroupText',
- isHiddenFromOverview: true,
- displayName: 'Input Group Text',
- description: 'A prefix or suffix text element rendered inside XDSInputGroup. Displays text or icons.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'Text or icon content.', required: true},
- {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for customization.'},
- {name: 'className', type: 'string', description: 'CSS class name(s).'},
- {name: 'style', type: 'React.CSSProperties', description: 'Inline styles.'},
- ],
+ name: 'status',
+ type: 'XDSInputStatus',
+ description: 'Status indicator applied to the group border.',
},
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text at the end of the label.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization.',
+ },
+ {
+ name: 'data-testid',
+ type: 'string',
+ description: 'Test selector.',
+ },
+ ],
+ components: [
+ {name: 'XDSInputGroupText'},
],
usage: {
description: 'InputGroup connects an input with prefix/suffix addons in a single visual unit. Use it for URL fields, currency inputs, search fields with action buttons, or any input that needs contextual decorations.',
@@ -79,37 +119,4 @@ export const docsDense = {
{guidance: false, description: 'Don\'t use InputGroup for unrelated inputs; it\'s for a single input with decorations.'},
],
},
- components: [
- {
- name: 'XDSInputGroup',
- displayName: 'Input Group',
- description: 'connected input+addon container w/ shared border, focus ring',
- propDescriptions: {
- children: 'input + addon children',
- label: 'a11y label',
- isLabelHidden: 'visually hide label',
- description: 'helper text',
- isDisabled: 'disable group',
- isOptional: 'show "(optional)"',
- isRequired: 'mark required',
- size: 'default input size',
- status: 'error/warning/success border',
- labelTooltip: 'tooltip at label end',
- xstyle: 'StyleX layout styles',
- 'data-testid': 'test selector',
- },
- },
- {
- name: 'XDSInputGroupText',
- isHiddenFromOverview: true,
- displayName: 'Input Group Text',
- description: 'prefix/suffix text/icon element',
- propDescriptions: {
- children: 'text or icon content',
- xstyle: 'StyleX styles',
- className: 'CSS class name(s)',
- style: 'inline styles',
- },
- },
- ],
};
diff --git a/packages/core/src/InputGroup/InputGroupText.doc.mjs b/packages/core/src/InputGroup/InputGroupText.doc.mjs
new file mode 100644
index 0000000000..02599f900e
--- /dev/null
+++ b/packages/core/src/InputGroup/InputGroupText.doc.mjs
@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'InputGroupText',
+ subComponentOf: 'InputGroup',
+ displayName: 'Input Group Text',
+ isHiddenFromOverview: true,
+ description: 'A prefix or suffix text element rendered inside XDSInputGroup. Displays text or icons.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Text or icon content.',
+ required: true,
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for customization.',
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'CSS class name(s).',
+ },
+ {
+ name: 'style',
+ type: 'React.CSSProperties',
+ description: 'Inline styles.',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'InputGroupText',
+ isHiddenFromOverview: true,
+ displayName: 'Input Group Text',
+ description: 'prefix/suffix text/icon element',
+ propDescriptions: {
+ children: 'text or icon content',
+ xstyle: 'StyleX styles',
+ className: 'CSS class name(s)',
+ style: 'inline styles',
+ },
+};
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index c886d4d3a9..6ef8294340 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -24,220 +24,83 @@ export const docs = {
{className: 'xds-layout-panel'},
],
},
- components: [
+ description: 'Page shell with header, sidebar(s), content, and footer slots for building full app layouts.',
+ props: [
{
- name: 'XDSLayout',
- displayName: 'Layout',
- description:
- 'Page shell with header, sidebar(s), content, and footer slots for building full app layouts.',
- props: [
- {
- name: 'content',
- type: 'ReactNode',
- description: 'Main content area (center).',
- slotElements: [{__element: 'XDSLayoutContent', props: {}, children: 'Content'}],
- },
- {
- name: 'header',
- type: 'ReactNode',
- description: 'Header slot.',
- slotElements: [{__element: 'XDSLayoutHeader', props: {}, children: 'Header'}],
- },
- {
- name: 'footer',
- type: 'ReactNode',
- description: 'Footer slot.',
- slotElements: [{__element: 'XDSLayoutFooter', props: {}, children: 'Footer'}],
- },
- {
- name: 'start',
- type: 'ReactNode',
- description: 'Start panel (left in LTR).',
- slotElements: [{__element: 'XDSLayoutPanel', props: {}, children: 'Panel'}],
- },
- {
- name: 'end',
- type: 'ReactNode',
- description: 'End panel (right in LTR).',
- slotElements: [{__element: 'XDSLayoutPanel', props: {}, children: 'Panel'}],
- },
+ name: 'content',
+ type: 'ReactNode',
+ description: 'Main content area (center).',
+ slotElements: [
{
- name: 'height',
- type: "'fill' | 'auto'",
- description:
- 'Height behavior: fill the container or grow with content.',
- default: "'fill'",
+ __element: 'XDSLayoutContent',
+ props: {},
+ children: 'Content',
},
- ], },
+ ],
+ },
{
- name: 'XDSLayoutHeader',
- isHiddenFromOverview: true,
- displayName: 'Layout Header',
- description: 'Top bar for page titles, app bars, and toolbars.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Header content.',
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description: 'Border at bottom edge.',
- default: 'false',
- },
- {
- name: 'height',
- type: 'number | string',
- description: 'Header height.',
- },
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label for the landmark element.',
- },
+ name: 'header',
+ type: 'ReactNode',
+ description: 'Header slot.',
+ slotElements: [
{
- name: 'role',
- type: 'AriaRole',
- description: 'ARIA landmark role.',
+ __element: 'XDSLayoutHeader',
+ props: {},
+ children: 'Header',
},
],
},
{
- name: 'XDSLayoutContent',
- isHiddenFromOverview: true,
- displayName: 'Layout Content',
- description: 'Scrollable main content area.',
- props: [
+ name: 'footer',
+ type: 'ReactNode',
+ description: 'Footer slot.',
+ slotElements: [
{
- name: 'children',
- type: 'ReactNode',
- description: 'Content.',
- },
- {
- name: 'isScrollable',
- type: 'boolean',
- description: 'Enable scrollable overflow.',
- default: 'true',
- },
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label for the landmark element.',
- },
- {
- name: 'role',
- type: 'AriaRole',
- description: 'ARIA landmark role.',
+ __element: 'XDSLayoutFooter',
+ props: {},
+ children: 'Footer',
},
],
},
{
- name: 'XDSLayoutFooter',
- isHiddenFromOverview: true,
- displayName: 'Layout Footer',
- description: 'Bottom bar for action bars, pagination, and status bars.',
- props: [
+ name: 'start',
+ type: 'ReactNode',
+ description: 'Start panel (left in LTR).',
+ slotElements: [
{
- name: 'children',
- type: 'ReactNode',
- description: 'Footer content.',
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description: 'Border at top edge.',
- default: 'false',
- },
- {
- name: 'height',
- type: 'number | string',
- description: 'Footer height.',
- },
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label for the landmark element.',
- },
- {
- name: 'role',
- type: 'AriaRole',
- description: 'ARIA landmark role.',
+ __element: 'XDSLayoutPanel',
+ props: {},
+ children: 'Panel',
},
],
},
{
- name: 'XDSLayoutPanel',
- isHiddenFromOverview: true,
- displayName: 'Layout Panel',
- description: 'Sidebar for navigation, settings, or inspector panels.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Panel content.',
- },
+ name: 'end',
+ type: 'ReactNode',
+ description: 'End panel (right in LTR).',
+ slotElements: [
{
- name: 'hasDivider',
- type: 'boolean',
- description: 'Border on the appropriate edge.',
- default: 'false',
- },
- {
- name: 'isScrollable',
- type: 'boolean',
- description: 'Enable scrollable overflow.',
- default: 'true',
- },
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label for the landmark element.',
- },
- {
- name: 'role',
- type: 'AriaRole',
- description: 'ARIA landmark role.',
+ __element: 'XDSLayoutPanel',
+ props: {},
+ children: 'Panel',
},
],
},
{
- name: 'XDSCard',
- displayName: 'Card',
- description:
- 'Card with shadow and themed styling, built on XDSLayoutContainer.',
- props: [],
- },
- {
- name: 'XDSSection',
- displayName: 'Section',
- description:
- 'Section with background variants (section, transparent, muted), built on XDSLayoutContainer.',
- props: [],
- },
- {
- name: 'XDSHStack',
- isHiddenFromOverview: true,
- displayName: 'H Stack',
- description: 'Horizontal stack that arranges children left-to-right.',
- props: [],
- },
- {
- name: 'XDSVStack',
- isHiddenFromOverview: true,
- displayName: 'V Stack',
- description: 'Vertical stack that arranges children top-to-bottom.',
- props: [],
- },
- {
- name: 'XDSStackItem',
- isHiddenFromOverview: true,
- displayName: 'Stack Item',
- description:
- 'Stack item with fill and alignment control for use inside XDSHStack or XDSVStack.',
- props: [],
+ name: 'height',
+ type: "'fill' | 'auto'",
+ description: 'Height behavior — fill the container or grow with content.',
+ default: "'fill'",
},
],
+ components: [
+ {name: 'XDSLayoutHeader'},
+ {name: 'XDSLayoutContent'},
+ {name: 'XDSLayoutFooter'},
+ {name: 'XDSLayoutPanel'},
+ {name: 'XDSCard'},
+ {name: 'XDSSection'},
+ ],
usage: {
description:
'Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use XDSLayout for full app layouts and XDSHStack/XDSVStack for simple directional stacking.',
@@ -250,229 +113,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Layout',
- displayName: 'Layout',
- theming: {
- targets: [
- {className: 'xds-layout', visualProps: ['height']},
- {className: 'xds-layout-content'},
- {className: 'xds-layout-footer'},
- {className: 'xds-layout-header'},
- {className: 'xds-layout-panel'},
- ],
- },
- components: [
- {
- name: 'XDSLayout',
- displayName: 'Layout',
- description:
- '带有页眉、侧边栏、内容和页脚插槽的页面外壳,用于构建完整的应用布局。',
- props: [
- {
- name: 'content',
- type: 'ReactNode',
- description: '主内容区域(居中)。',
- },
- {
- name: 'header',
- type: 'ReactNode',
- description: '页眉插槽。',
- },
- {
- name: 'footer',
- type: 'ReactNode',
- description: '页脚插槽。',
- },
- {
- name: 'start',
- type: 'ReactNode',
- description: '起始面板(LTR 模式下为左侧)。',
- },
- {
- name: 'end',
- type: 'ReactNode',
- description: '结束面板(LTR 模式下为右侧)。',
- },
- {
- name: 'height',
- type: "'fill' | 'auto'",
- description:
- '高度行为:填充容器或随内容增长。',
- default: "'fill'",
- },
- ],
- },
- {
- name: 'XDSLayoutHeader',
- isHiddenFromOverview: true,
- displayName: 'Layout Header',
- description: '用于页面标题、应用栏和工具栏的顶部栏。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '页眉内容。',
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description: '底部边缘的边框。',
- default: 'false',
- },
- {
- name: 'height',
- type: 'number | string',
- description: '页眉高度。',
- },
- {
- name: 'label',
- type: 'string',
- description: '地标元素的无障碍标签。',
- },
- {
- name: 'role',
- type: 'AriaRole',
- description: 'ARIA 地标角色。',
- },
- ],
- },
- {
- name: 'XDSLayoutContent',
- isHiddenFromOverview: true,
- displayName: 'Layout Content',
- description: '可滚动的主内容区域。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '内容。',
- },
- {
- name: 'isScrollable',
- type: 'boolean',
- description: '启用可滚动溢出。',
- default: 'true',
- },
- {
- name: 'label',
- type: 'string',
- description: '地标元素的无障碍标签。',
- },
- {
- name: 'role',
- type: 'AriaRole',
- description: 'ARIA 地标角色。',
- },
- ],
- },
- {
- name: 'XDSLayoutFooter',
- isHiddenFromOverview: true,
- displayName: 'Layout Footer',
- description: '用于操作栏、分页和状态栏的底部栏。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '页脚内容。',
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description: '顶部边缘的边框。',
- default: 'false',
- },
- {
- name: 'height',
- type: 'number | string',
- description: '页脚高度。',
- },
- {
- name: 'label',
- type: 'string',
- description: '地标元素的无障碍标签。',
- },
- {
- name: 'role',
- type: 'AriaRole',
- description: 'ARIA 地标角色。',
- },
- ],
- },
- {
- name: 'XDSLayoutPanel',
- isHiddenFromOverview: true,
- displayName: 'Layout Panel',
- description: '用于导航、设置或检查器面板的侧边栏。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '面板内容。',
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description: '相应边缘的边框。',
- default: 'false',
- },
- {
- name: 'isScrollable',
- type: 'boolean',
- description: '启用可滚动溢出。',
- default: 'true',
- },
- {
- name: 'label',
- type: 'string',
- description: '地标元素的无障碍标签。',
- },
- {
- name: 'role',
- type: 'AriaRole',
- description: 'ARIA 地标角色。',
- },
- ],
- },
- {
- name: 'XDSCard',
- displayName: 'Card',
- description:
- '基于 XDSLayoutContainer 构建的带有阴影和主题样式的卡片。',
- props: [],
- },
- {
- name: 'XDSSection',
- displayName: 'Section',
- description:
- '基于 XDSLayoutContainer 构建的带有背景变体(section、transparent、muted)的区块。',
- props: [],
- },
- {
- name: 'XDSHStack',
- isHiddenFromOverview: true,
- displayName: 'H Stack',
- description: '将子元素从左到右排列的水平堆叠。',
- props: [],
- },
- {
- name: 'XDSVStack',
- isHiddenFromOverview: true,
- displayName: 'V Stack',
- description: '将子元素从上到下排列的垂直堆叠。',
- props: [],
- },
- {
- name: 'XDSStackItem',
- isHiddenFromOverview: true,
- displayName: 'Stack Item',
- description:
- '用于 XDSHStack 或 XDSVStack 内部的堆叠项,支持填充和对齐控制。',
- props: [],
- },
- ],
usage: {
description:
'Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use XDSLayout for full app layouts and XDSHStack/XDSVStack for simple directional stacking.',
@@ -499,102 +141,4 @@ export const docsDense = {
{ guidance: false, description: 'Nest multiple XDSLayout components; use one per page shell and compose content within its slots.' },
],
},
- components: [
- {
- name: 'XDSLayout',
- displayName: 'Layout',
- description:
- 'Page shell w/ header, sidebar(s), content, footer slots for full app layouts.',
- propDescriptions: {
- content: 'Main content area (center).',
- header: 'Header slot.',
- footer: 'Footer slot.',
- start: 'Start panel (left in LTR).',
- end: 'End panel (right in LTR).',
- height: 'Height behavior; fill container or grow w/ content.',
- },
- },
- {
- name: 'XDSLayoutHeader',
- isHiddenFromOverview: true,
- displayName: 'Layout Header',
- description: 'Top bar for page titles, app bars, toolbars.',
- propDescriptions: {
- children: 'Header content.',
- hasDivider: 'Border at bottom edge.',
- height: 'Header height.',
- label: 'Accessible label for landmark element.',
- role: 'ARIA landmark role.',
- },
- },
- {
- name: 'XDSLayoutContent',
- isHiddenFromOverview: true,
- displayName: 'Layout Content',
- description: 'Scrollable main content area.',
- propDescriptions: {
- children: 'Content.',
- isScrollable: 'Enable scrollable overflow.',
- label: 'Accessible label for landmark element.',
- role: 'ARIA landmark role.',
- },
- },
- {
- name: 'XDSLayoutFooter',
- isHiddenFromOverview: true,
- displayName: 'Layout Footer',
- description: 'Bottom bar for action bars, pagination, status bars.',
- propDescriptions: {
- children: 'Footer content.',
- hasDivider: 'Border at top edge.',
- height: 'Footer height.',
- label: 'Accessible label for landmark element.',
- role: 'ARIA landmark role.',
- },
- },
- {
- name: 'XDSLayoutPanel',
- isHiddenFromOverview: true,
- displayName: 'Layout Panel',
- description: 'Sidebar for navigation, settings, inspector panels.',
- propDescriptions: {
- children: 'Panel content.',
- hasDivider: 'Border on appropriate edge.',
- isScrollable: 'Enable scrollable overflow.',
- label: 'Accessible label for landmark element.',
- role: 'ARIA landmark role.',
- },
- },
- {
- name: 'XDSCard',
- displayName: 'Card',
- description:
- 'Card w/ shadow + themed styling, built on XDSLayoutContainer.',
- },
- {
- name: 'XDSSection',
- displayName: 'Section',
- description:
- 'Section w/ background variants (section, transparent, muted), built on XDSLayoutContainer.',
- },
- {
- name: 'XDSHStack',
- isHiddenFromOverview: true,
- displayName: 'H Stack',
- description: 'Horizontal stack arranging children left-to-right.',
- },
- {
- name: 'XDSVStack',
- isHiddenFromOverview: true,
- displayName: 'V Stack',
- description: 'Vertical stack arranging children top-to-bottom.',
- },
- {
- name: 'XDSStackItem',
- isHiddenFromOverview: true,
- displayName: 'Stack Item',
- description:
- 'Stack item w/ fill + alignment control inside XDSHStack or XDSVStack.',
- },
- ],
};
diff --git a/packages/core/src/Layout/LayoutContent.doc.mjs b/packages/core/src/Layout/LayoutContent.doc.mjs
new file mode 100644
index 0000000000..6f38c5cec0
--- /dev/null
+++ b/packages/core/src/Layout/LayoutContent.doc.mjs
@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'LayoutContent',
+ subComponentOf: 'Layout',
+ displayName: 'Layout Content',
+ isHiddenFromOverview: true,
+ description: 'Scrollable main content area.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content.',
+ },
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description: 'Enable scrollable overflow.',
+ default: 'true',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the landmark element.',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA landmark role.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'LayoutContent',
+ isHiddenFromOverview: true,
+ displayName: 'Layout Content',
+ description: '可滚动的主内容区域。',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '内容。',
+ },
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description: '启用可滚动溢出。',
+ default: 'true',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '地标元素的无障碍标签。',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA 地标角色。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'LayoutContent',
+ isHiddenFromOverview: true,
+ displayName: 'Layout Content',
+ description: 'Scrollable main content area.',
+ propDescriptions: {
+ children: 'Content.',
+ isScrollable: 'Enable scrollable overflow.',
+ label: 'Accessible label for landmark element.',
+ role: 'ARIA landmark role.',
+ },
+};
diff --git a/packages/core/src/Layout/LayoutFooter.doc.mjs b/packages/core/src/Layout/LayoutFooter.doc.mjs
new file mode 100644
index 0000000000..67e147a3a1
--- /dev/null
+++ b/packages/core/src/Layout/LayoutFooter.doc.mjs
@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'LayoutFooter',
+ subComponentOf: 'Layout',
+ displayName: 'Layout Footer',
+ isHiddenFromOverview: true,
+ description: 'Bottom bar for action bars, pagination, and status bars.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Footer content.',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Border at top edge.',
+ default: 'false',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: 'Footer height.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the landmark element.',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA landmark role.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'LayoutFooter',
+ isHiddenFromOverview: true,
+ displayName: 'Layout Footer',
+ description: '用于操作栏、分页和状态栏的底部栏。',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '页脚内容。',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: '顶部边缘的边框。',
+ default: 'false',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: '页脚高度。',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '地标元素的无障碍标签。',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA 地标角色。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'LayoutFooter',
+ isHiddenFromOverview: true,
+ displayName: 'Layout Footer',
+ description: 'Bottom bar for action bars, pagination, status bars.',
+ propDescriptions: {
+ children: 'Footer content.',
+ hasDivider: 'Border at top edge.',
+ height: 'Footer height.',
+ label: 'Accessible label for landmark element.',
+ role: 'ARIA landmark role.',
+ },
+};
diff --git a/packages/core/src/Layout/LayoutHeader.doc.mjs b/packages/core/src/Layout/LayoutHeader.doc.mjs
new file mode 100644
index 0000000000..27694a5989
--- /dev/null
+++ b/packages/core/src/Layout/LayoutHeader.doc.mjs
@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'LayoutHeader',
+ subComponentOf: 'Layout',
+ displayName: 'Layout Header',
+ isHiddenFromOverview: true,
+ description: 'Top bar for page titles, app bars, and toolbars.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Header content.',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Border at bottom edge.',
+ default: 'false',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: 'Header height.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the landmark element.',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA landmark role.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'LayoutHeader',
+ isHiddenFromOverview: true,
+ displayName: 'Layout Header',
+ description: '用于页面标题、应用栏和工具栏的顶部栏。',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '页眉内容。',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: '底部边缘的边框。',
+ default: 'false',
+ },
+ {
+ name: 'height',
+ type: 'number | string',
+ description: '页眉高度。',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '地标元素的无障碍标签。',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA 地标角色。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'LayoutHeader',
+ isHiddenFromOverview: true,
+ displayName: 'Layout Header',
+ description: 'Top bar for page titles, app bars, toolbars.',
+ propDescriptions: {
+ children: 'Header content.',
+ hasDivider: 'Border at bottom edge.',
+ height: 'Header height.',
+ label: 'Accessible label for landmark element.',
+ role: 'ARIA landmark role.',
+ },
+};
diff --git a/packages/core/src/Layout/LayoutPanel.doc.mjs b/packages/core/src/Layout/LayoutPanel.doc.mjs
new file mode 100644
index 0000000000..074faa70dd
--- /dev/null
+++ b/packages/core/src/Layout/LayoutPanel.doc.mjs
@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'LayoutPanel',
+ subComponentOf: 'Layout',
+ displayName: 'Layout Panel',
+ isHiddenFromOverview: true,
+ description: 'Sidebar for navigation, settings, or inspector panels.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Panel content.',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Border on the appropriate edge.',
+ default: 'false',
+ },
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description: 'Enable scrollable overflow.',
+ default: 'true',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the landmark element.',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA landmark role.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'LayoutPanel',
+ isHiddenFromOverview: true,
+ displayName: 'Layout Panel',
+ description: '用于导航、设置或检查器面板的侧边栏。',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '面板内容。',
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: '相应边缘的边框。',
+ default: 'false',
+ },
+ {
+ name: 'isScrollable',
+ type: 'boolean',
+ description: '启用可滚动溢出。',
+ default: 'true',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '地标元素的无障碍标签。',
+ },
+ {
+ name: 'role',
+ type: 'AriaRole',
+ description: 'ARIA 地标角色。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'LayoutPanel',
+ isHiddenFromOverview: true,
+ displayName: 'Layout Panel',
+ description: 'Sidebar for navigation, settings, inspector panels.',
+ propDescriptions: {
+ children: 'Panel content.',
+ hasDivider: 'Border on appropriate edge.',
+ isScrollable: 'Enable scrollable overflow.',
+ label: 'Accessible label for landmark element.',
+ role: 'ARIA landmark role.',
+ },
+};
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index 39cbd75cc2..14533cfb4f 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -14,123 +14,61 @@ export const docs = {
{className: 'xds-list-item'},
],
},
- components: [
+ description: 'List container with density, dividers, and header support.',
+ props: [
{
- name: 'XDSList',
- displayName: 'List',
- description: 'List container with density, dividers, and header support.', props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'List items (XDSListItem components).',
- slotElements: [{__element: 'XDSListItem', props: {label: 'List item'}}],
- },
- {
- name: 'density',
- type: "'compact' | 'balanced' | 'spacious'",
- description: 'Spacing density for items.',
- default: "'balanced'",
- },
- {
- name: 'hasDividers',
- type: 'boolean',
- description: 'Show dividers between items.',
- default: 'false',
- },
- {
- name: 'header',
- type: 'ReactNode',
- description:
- 'Header content, associated with the list via aria-labelledby.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Header'}],
- },
+ name: 'children',
+ type: 'ReactNode',
+ description: 'List items (XDSListItem components).',
+ slotElements: [
{
- name: 'listStyle',
- type: "'none' | 'disc' | 'decimal' | 'circle'",
- description:
- "List marker style. 'decimal' renders an <ol> element instead of <ul>.",
- default: "'none'",
- },
- {
- 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={{}}.',
+ __element: 'XDSListItem',
+ props: {
+ label: 'List item',
+ },
},
],
},
{
- name: 'XDSListItem',
- isHiddenFromOverview: true,
- displayName: 'List Item',
- description:
- 'List item with label, description, start/end content slots, and interactive patterns.',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Primary text.',
- required: true,
- },
- {
- name: 'description',
- type: 'ReactNode',
- description:
- 'Secondary content below the label. A plain string gets single-line truncation automatically; a ReactNode lets child components control their own wrapping and line-clamp behavior.',
- },
- {
- name: 'startContent',
- type: 'ReactNode',
- description:
- 'Content rendered before the label area (e.g. icon, avatar).',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- 'Content rendered after the label area (e.g. badge, chevron).',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
- },
- {
- name: 'onClick',
- type: '(e: MouseEvent) => void',
- description: 'Click handler; enables the invisible button pattern.',
- },
- {
- name: 'href',
- type: 'string',
- description: 'Link URL; enables the invisible anchor pattern.',
- },
- {
- name: 'target',
- type: 'string',
- description:
- 'Link target attribute, only applicable when href is provided. target="_blank" automatically adds noopener noreferrer.',
- },
- {
- name: 'rel',
- type: 'string',
- description:
- 'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Disabled state; sets aria-disabled on the item.',
- default: 'false',
- },
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Spacing density for items.',
+ default: "'balanced'",
+ },
+ {
+ name: 'hasDividers',
+ type: 'boolean',
+ description: 'Show dividers between items.',
+ default: 'false',
+ },
+ {
+ name: 'header',
+ type: 'ReactNode',
+ description: 'Header content, associated with the list via aria-labelledby.',
+ slotElements: [
{
- name: 'isSelected',
- type: 'boolean',
- description: 'Selected state; sets aria-selected on the item.',
- default: 'false',
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Header',
},
],
},
+ {
+ name: 'listStyle',
+ type: "'none' | 'disc' | 'decimal' | 'circle'",
+ description: "List marker style. 'decimal' renders an <ol> element instead of <ul>.",
+ default: "'none'",
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+ components: [
+ {name: 'XDSListItem'},
],
usage: {
description:
@@ -150,129 +88,8 @@ export const docs = {
],
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'List',
- displayName: 'List',
- group: 'List',
- theming: {
- targets: [
- {className: 'xds-list', visualProps: ['density', 'listStyle']},
- {className: 'xds-list-item'},
- ],
- },
- components: [
- {
- name: 'XDSList',
- displayName: 'List',
- description: '列表容器,支持密度、分割线和标题。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '列表项(XDSListItem 组件)。',
- },
- {
- name: 'density',
- type: "'compact' | 'balanced' | 'spacious'",
- description: '项目的间距密度。',
- default: "'balanced'",
- },
- {
- name: 'hasDividers',
- type: 'boolean',
- description: '在项目之间显示分割线。',
- default: 'false',
- },
- {
- name: 'header',
- type: 'ReactNode',
- description:
- '标题内容,通过 aria-labelledby 与列表关联。',
- },
- {
- name: 'listStyle',
- type: "'none' | 'disc' | 'decimal' | 'circle'",
- description:
- "列表标记样式。'decimal' 渲染 <ol> 元素而非 <ul>。",
- default: "'none'",
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,不能是内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSListItem',
- isHiddenFromOverview: true,
- displayName: 'List Item',
- description:
- '列表项,包含标签、描述、起始/结束内容插槽和交互模式。',
- props: [
- {
- name: 'label',
- type: 'string',
- description: '主要文本。',
- required: true,
- },
- {
- name: 'description',
- type: 'ReactNode',
- description:
- '标签下方的次要内容。纯字符串会自动应用单行截断;ReactNode 允许子组件自行控制换行和多行截断行为。',
- },
- {
- name: 'startContent',
- type: 'ReactNode',
- description:
- '在标签区域之前渲染的内容(如图标、头像)。',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- '在标签区域之后渲染的内容(如徽章、箭头)。',
- },
- {
- name: 'onClick',
- type: '(e: MouseEvent) => void',
- description: '点击处理函数;启用隐形按钮模式。',
- },
- {
- name: 'href',
- type: 'string',
- description: '链接 URL;启用隐形锚点模式。',
- },
- {
- name: 'target',
- type: 'string',
- description:
- '链接 target 属性,仅在提供 href 时适用。target="_blank" 会自动添加 noopener noreferrer。',
- },
- {
- name: 'rel',
- type: 'string',
- description:
- '链接关系标记。target="_blank" 会自动合并 noopener noreferrer。',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '禁用状态;在项目上设置 aria-disabled。',
- default: 'false',
- },
- {
- name: 'isSelected',
- type: 'boolean',
- description: '选中状态;在项目上设置 aria-selected。',
- default: 'false',
- },
- ],
- },
- ],
usage: {
description:
'A vertical collection of items with consistent spacing, dividers, and optional markers. Supports headers, icons, avatars, badges, and interactive items with click or link behavior. Use it to display ordered or unordered groups of related content.',
@@ -313,41 +130,4 @@ export const docsDense = {
{name: 'Item description', required: false, description: 'Additional detail for an individual list item.'},
],
},
- components: [
- {
- name: 'XDSList',
- displayName: 'List',
- description: 'List container w/ density, dividers, header support.',
- propDescriptions: {
- children: 'List items (XDSListItem components).',
- density: 'Spacing density for items.',
- hasDividers: 'Show dividers between items.',
- header: 'Header content, associated w/ list via aria-labelledby.',
- listStyle:
- "List marker style. 'decimal' renders <ol> instead of <ul>.",
- xstyle:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSListItem',
- isHiddenFromOverview: true,
- displayName: 'List Item',
- description:
- 'List item w/ label, description, start/end content slots, interactive patterns.',
- propDescriptions: {
- label: 'Primary text.',
- description: 'Secondary text below label.',
- startContent: 'Content before label area (e.g. icon, avatar).',
- endContent: 'Content after label area (e.g. badge, chevron).',
- onClick: 'Click handler; enables invisible button pattern.',
- href: 'Link URL; enables invisible anchor pattern.',
- target:
- 'Link target attribute, only when href provided. target="_blank" auto-adds noopener noreferrer.',
- rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',
- isDisabled: 'Disabled state; sets aria-disabled.',
- isSelected: 'Selected state; sets aria-selected.',
- },
- },
- ],
};
diff --git a/packages/core/src/List/ListItem.doc.mjs b/packages/core/src/List/ListItem.doc.mjs
new file mode 100644
index 0000000000..f80316e883
--- /dev/null
+++ b/packages/core/src/List/ListItem.doc.mjs
@@ -0,0 +1,171 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ListItem',
+ subComponentOf: 'List',
+ displayName: 'List Item',
+ isHiddenFromOverview: true,
+ description: 'List item with label, description, start/end content slots, and interactive patterns.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Primary text.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: 'Secondary content below the label. A plain string gets single-line truncation automatically; a ReactNode lets child components control their own wrapping and line-clamp behavior.',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description: 'Content rendered before the label area (e.g. icon, avatar).',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Content rendered after the label area (e.g. badge, chevron).',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
+ },
+ {
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
+ },
+ ],
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: 'Click handler; enables the invisible button pattern.',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'Link URL; enables the invisible anchor pattern.',
+ },
+ {
+ name: 'target',
+ type: 'string',
+ description: 'Link target attribute, only applicable when href is provided. target="_blank" automatically adds noopener noreferrer.',
+ },
+ {
+ name: 'rel',
+ type: 'string',
+ description: 'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disabled state; sets aria-disabled on the item.',
+ default: 'false',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: 'Selected state; sets aria-selected on the item.',
+ default: 'false',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ListItem',
+ isHiddenFromOverview: true,
+ displayName: 'List Item',
+ description: '列表项,包含标签、描述、起始/结束内容插槽和交互模式。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '主要文本。',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: '标签下方的次要内容。纯字符串会自动应用单行截断;ReactNode 允许子组件自行控制换行和多行截断行为。',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description: '在标签区域之前渲染的内容(如图标、头像)。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '在标签区域之后渲染的内容(如徽章、箭头)。',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: '点击处理函数;启用隐形按钮模式。',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: '链接 URL;启用隐形锚点模式。',
+ },
+ {
+ name: 'target',
+ type: 'string',
+ description: '链接 target 属性,仅在提供 href 时适用。target="_blank" 会自动添加 noopener noreferrer。',
+ },
+ {
+ name: 'rel',
+ type: 'string',
+ description: '链接关系标记。target="_blank" 会自动合并 noopener noreferrer。',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '禁用状态;在项目上设置 aria-disabled。',
+ default: 'false',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: '选中状态;在项目上设置 aria-selected。',
+ default: 'false',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'ListItem',
+ isHiddenFromOverview: true,
+ displayName: 'List Item',
+ description: 'List item w/ label, description, start/end content slots, interactive patterns.',
+ propDescriptions: {
+ label: 'Primary text.',
+ description: 'Secondary text below label.',
+ startContent: 'Content before label area (e.g. icon, avatar).',
+ endContent: 'Content after label area (e.g. badge, chevron).',
+ onClick: 'Click handler; enables invisible button pattern.',
+ href: 'Link URL; enables invisible anchor pattern.',
+ target: 'Link target attribute, only when href provided. target="_blank" auto-adds noopener noreferrer.',
+ rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',
+ isDisabled: 'Disabled state; sets aria-disabled.',
+ isSelected: 'Selected state; sets aria-selected.',
+ },
+};
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index 0218888e3c..9b41ad2b17 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -17,85 +17,60 @@ export const docs = {
{className: 'xds-metadata-list-item'},
],
},
- components: [
+ description: 'Container for metadata items with column layout, orientation, and collapse support.',
+ props: [
{
- name: 'XDSMetadataList',
- displayName: 'Metadata List',
- description:
- 'Container for metadata items with column layout, orientation, and collapse support.', props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Metadata items (XDSMetadataListItem components).',
- slotElements: [{__element: 'XDSMetadataListItem', props: {label: 'Key'}, children: 'Value'}],
- required: true,
- },
- {
- name: 'columns',
- type: "'multi' | 'single' | number",
- description: 'Column layout mode.',
- default: "'single'",
- },
- {
- name: 'label',
- type: "{ position?: 'start' | 'top', width?: number | string }",
- description:
- "Label display configuration. position controls label placement, width sets a custom label column width. Defaults to { position: 'top' } for multi-column layouts.",
- default: "{ position: 'start' } (single-column) / { position: 'top' } (multi-column)",
- },
- {
- name: 'maxNumOfItems',
- type: 'number',
- description:
- 'Maximum items to show before collapsing with a show more/less toggle.',
- },
- {
- name: 'orientation',
- type: "'vertical' | 'horizontal'",
- description:
- 'Layout orientation. Horizontal mode flows items in a row with flex-wrap.',
- default: "'vertical'",
- },
- {
- name: 'title',
- type: 'ReactNode',
- description: 'Optional title or heading above the list.',
- },
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Metadata items (XDSMetadataListItem components).',
+ slotElements: [
{
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ __element: 'XDSMetadataListItem',
+ props: {
+ label: 'Key',
+ },
+ children: 'Value',
},
],
+ required: true,
},
{
- name: 'XDSMetadataListItem',
- isHiddenFromOverview: true,
- displayName: 'Metadata List Item',
- description: 'A single labeled metadata value within an XDSMetadataList.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Content value for this metadata item.',
- required: true,
- },
- {
- name: 'label',
- type: 'string',
- description: 'Label text for this metadata item.',
- required: true,
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: 'Icon rendered before the label text.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- ],
+ name: 'columns',
+ type: "'multi' | 'single' | number",
+ description: 'Column layout mode.',
+ default: "'single'",
+ },
+ {
+ name: 'label',
+ type: "{ position?: 'start' | 'top', width?: number | string }",
+ description: "Label display configuration. position controls label placement, width sets a custom label column width. Defaults to { position: 'top' } for multi-column layouts.",
+ default: "{ position: 'start' } (single-column) / { position: 'top' } (multi-column)",
+ },
+ {
+ name: 'maxNumOfItems',
+ type: 'number',
+ description: 'Maximum items to show before collapsing with a show more/less toggle.',
+ },
+ {
+ name: 'orientation',
+ type: "'vertical' | 'horizontal'",
+ description: 'Layout orientation. Horizontal mode flows items in a row with flex-wrap.',
+ default: "'vertical'",
+ },
+ {
+ name: 'title',
+ type: 'ReactNode',
+ description: 'Optional title or heading above the list.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
},
],
+ components: [
+ {name: 'XDSMetadataListItem'},
+ ],
usage: {
description:
'MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.',
@@ -116,33 +91,6 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- components: [
- {
- name: 'XDSMetadataList',
- displayName: 'Metadata List',
- description: '带列布局、方向和折叠支持的元数据项容器。',
- propDescriptions: {
- children: '元数据项(XDSMetadataListItem 组件)。',
- columns: '列布局模式。',
- label: '标签显示配置。position 控制标签位置,width 设置自定义标签列宽。',
- maxNumOfItems: '折叠前显示的最大项目数。',
- orientation: '布局方向。水平模式使用 flex-wrap 流式排列。',
- title: '列表上方的可选标题。',
- xstyle: '布局自定义的 StyleX 样式,必须是 stylex.create() 值。',
- },
- },
- {
- name: 'XDSMetadataListItem',
- isHiddenFromOverview: true,
- displayName: 'Metadata List Item',
- description: 'XDSMetadataList 中的单个带标签元数据值。',
- propDescriptions: {
- children: '此元数据项的内容值。',
- label: '此元数据项的标签文本。',
- icon: '标签文本前渲染的图标。',
- },
- },
- ],
usage: {
description:
'MetadataList displays key-value pairs for object attributes like quality, condition, and status, in a structured layout. Use it for detail panels, settings summaries, and record information.',
@@ -180,31 +128,4 @@ export const docsDense = {
{name: 'Disclosure', required: false, description: 'Collapse/expand control for the list.'},
],
},
- components: [
- {
- name: 'XDSMetadataList',
- displayName: 'Metadata List',
- description: 'metadata container w/ column layout+collapse',
- propDescriptions: {
- children: 'XDSMetadataListItem children',
- columns: 'column mode: single, multi, or fixed count',
- label: 'label config: position (start/top) + width',
- maxNumOfItems: 'max items before collapse',
- orientation: 'vertical or horizontal (flex-wrap)',
- title: 'optional heading above list',
- xstyle: 'StyleX layout styles; stylex.create() only',
- },
- },
- {
- name: 'XDSMetadataListItem',
- isHiddenFromOverview: true,
- displayName: 'Metadata List Item',
- description: 'single labeled value in XDSMetadataList',
- propDescriptions: {
- children: 'value content',
- label: 'label text',
- icon: 'icon before label',
- },
- },
- ],
};
diff --git a/packages/core/src/MetadataList/MetadataListItem.doc.mjs b/packages/core/src/MetadataList/MetadataListItem.doc.mjs
new file mode 100644
index 0000000000..24861beb10
--- /dev/null
+++ b/packages/core/src/MetadataList/MetadataListItem.doc.mjs
@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'MetadataListItem',
+ subComponentOf: 'MetadataList',
+ displayName: 'Metadata List Item',
+ isHiddenFromOverview: true,
+ description: 'A single labeled metadata value within an XDSMetadataList.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content value for this metadata item.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for this metadata item.',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon rendered before the label text.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'MetadataListItem',
+ isHiddenFromOverview: true,
+ displayName: 'Metadata List Item',
+ description: 'XDSMetadataList 中的单个带标签元数据值。',
+ propDescriptions: {
+ children: '此元数据项的内容值。',
+ label: '此元数据项的标签文本。',
+ icon: '标签文本前渲染的图标。',
+ },
+};
+
+export const docsDense = {
+ name: 'MetadataListItem',
+ isHiddenFromOverview: true,
+ displayName: 'Metadata List Item',
+ description: 'single labeled value in XDSMetadataList',
+ propDescriptions: {
+ children: 'value content',
+ label: 'label text',
+ icon: 'icon before label',
+ },
+};
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index a57d846e73..cd514f2e7f 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -16,145 +16,100 @@ export const docs = {
{className: 'xds-radio-dot', visualProps: ['size']},
],
},
- components: [
+ description: 'Radio group container with field integration for label, description, and status.',
+ props: [
{
- name: 'XDSRadioList',
- displayName: 'Radio List',
- description:
- 'Radio group container with field integration for label, description, and status.', props: [
- {
- name: 'label',
- type: 'string',
- description:
- 'Label text for the radio group (always rendered for accessibility).',
- required: true,
- },
- {
- name: 'value',
- type: 'string',
- description: 'The currently selected value.',
- required: true,
- },
- {
- name: 'onChange',
- type: '(value: string) => void',
- description: 'Callback fired when the selected value changes.',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'XDSRadioListItem elements.',
- slotElements: [{__element: 'XDSRadioListItem', props: {label: 'Option', value: 'option'}}],
- required: true,
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: 'Whether to visually hide the label.',
- default: 'false',
- },
- {
- name: 'description',
- type: 'string',
- description: 'Description text displayed below the label.',
- },
- {
- name: 'orientation',
- type: "'vertical' | 'horizontal'",
- description: 'Layout direction of the radio items.',
- default: "'vertical'",
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether all radio items are disabled.',
- default: 'false',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description: 'Whether the radio group is required.',
- default: 'false',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description:
- 'Whether the field is optional (mutually exclusive with isRequired).',
- default: 'false',
- },
- {
- name: 'status',
- type: 'XDSInputStatus',
- description: 'Status indicator ({ type, message }).',
- },
- {
- name: 'size',
- type: "'sm' | 'md'",
- description: 'Size of the radio controls.',
- default: "'md'",
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description: 'Tooltip text for an info icon next to the label.',
- },
- {
- 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={{}}.',
- },
- ],
+ name: 'label',
+ type: 'string',
+ description: 'Label text for the radio group (always rendered for accessibility).',
+ required: true,
},
{
- name: 'XDSRadioListItem',
- isHiddenFromOverview: true,
- displayName: 'Radio List Item',
- description:
- 'Individual radio item with label, description, and content slots.',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Label text for the radio item.',
- required: true,
- },
- {
- name: 'value',
- type: 'string',
- description: 'Value of this radio item.',
- required: true,
- },
- {
- name: 'description',
- type: 'string',
- description: 'Description text displayed below the label.',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether this individual radio item is disabled.',
- default: 'false',
- },
- {
- name: 'startContent',
- type: 'ReactNode',
- description: 'Content to render before the radio circle.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
+ name: 'value',
+ type: 'string',
+ description: 'The currently selected value.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Callback fired when the selected value changes.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSRadioListItem elements.',
+ slotElements: [
{
- name: 'endContent',
- type: 'ReactNode',
- description: 'Content to render after the label.',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
+ __element: 'XDSRadioListItem',
+ props: {
+ label: 'Option',
+ value: 'option',
+ },
},
],
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Whether to visually hide the label.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'orientation',
+ type: "'vertical' | 'horizontal'",
+ description: 'Layout direction of the radio items.',
+ default: "'vertical'",
},
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether all radio items are disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Whether the radio group is required.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Whether the field is optional (mutually exclusive with isRequired).',
+ default: 'false',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description: 'Status indicator ({ type, message }).',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md'",
+ description: 'Size of the radio controls.',
+ default: "'md'",
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text for an info icon next to the label.',
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+ components: [
+ {name: 'XDSRadioListItem'},
],
usage: {
description:
@@ -175,153 +130,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'RadioList',
- displayName: 'Radio List',
- theming: {
- targets: [
- {className: 'xds-radio-list', visualProps: ['orientation', 'size']},
- {className: 'xds-radio-list-item'},
- {className: 'xds-radio', visualProps: ['size'], states: ['checked', 'disabled']},
- {className: 'xds-radio-dot', visualProps: ['size']},
- ],
- },
- components: [
- {
- name: 'XDSRadioList',
- displayName: 'Radio List',
- description:
- '单选按钮组容器,集成字段功能,支持标签、描述和状态。',
- props: [
- {
- name: 'label',
- type: 'string',
- description:
- '单选按钮组的标签文本(始终渲染以确保无障碍可访问性)。',
- required: true,
- },
- {
- name: 'value',
- type: 'string',
- description: '当前选中的值。',
- required: true,
- },
- {
- name: 'onChange',
- type: '(value: string) => void',
- description: '选中值变更时触发的回调函数。',
- required: true,
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'XDSRadioListItem 元素。',
- required: true,
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: '是否在视觉上隐藏标签。',
- default: 'false',
- },
- {
- name: 'description',
- type: 'string',
- description: '显示在标签下方的描述文本。',
- },
- {
- name: 'orientation',
- type: "'vertical' | 'horizontal'",
- description: '单选选项的布局方向。',
- default: "'vertical'",
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '是否禁用所有单选选项。',
- default: 'false',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description: '单选按钮组是否为必填。',
- default: 'false',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description:
- '字段是否为可选(与 isRequired 互斥)。',
- default: 'false',
- },
- {
- name: 'status',
- type: 'XDSInputStatus',
- description: '状态指示器({ type, message })。',
- },
- {
- name: 'size',
- type: "'sm' | 'md'",
- description: '单选控件的尺寸。',
- default: "'md'",
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description: '标签旁信息图标的提示文本。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSRadioListItem',
- isHiddenFromOverview: true,
- displayName: 'Radio List Item',
- description:
- '单个单选选项,包含标签、描述和内容插槽。',
- props: [
- {
- name: 'label',
- type: 'string',
- description: '单选选项的标签文本。',
- required: true,
- },
- {
- name: 'value',
- type: 'string',
- description: '此单选选项的值。',
- required: true,
- },
- {
- name: 'description',
- type: 'string',
- description: '显示在标签下方的描述文本。',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '是否禁用此单个单选选项。',
- default: 'false',
- },
- {
- name: 'startContent',
- type: 'ReactNode',
- description: '在单选圆圈前渲染的内容。',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description: '在标签后渲染的内容。',
- },
- ],
- },
- ],
usage: {
description:
'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',
@@ -362,43 +172,4 @@ export const docsDense = {
{name: 'Label/Value', required: true, description: 'The text label and associated value for each radio item.'},
],
},
- components: [
- {
- name: 'XDSRadioList',
- displayName: 'Radio List',
- description:
- 'Radio group container w/ field integration for label, description, status.',
- propDescriptions: {
- label: 'Label text for radio group (always rendered for accessibility).',
- value: 'Currently selected value.',
- onChange: 'Callback fired when selected value changes.',
- children: 'XDSRadioListItem elements.',
- isLabelHidden: 'Whether to visually hide label.',
- description: 'Description text below label.',
- orientation: 'Layout direction of radio items.',
- isDisabled: 'Whether all radio items disabled.',
- isRequired: 'Whether radio group required.',
- isOptional: 'Whether field optional (mutually exclusive w/ isRequired).',
- status: 'Status indicator ({ type, message }).',
- size: 'Size of radio controls.',
- labelTooltip: 'Tooltip text for info icon next to label.',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSRadioListItem',
- isHiddenFromOverview: true,
- displayName: 'Radio List Item',
- description:
- 'Individual radio item w/ label, description, content slots.',
- propDescriptions: {
- label: 'Label text for radio item.',
- value: 'Value of this radio item.',
- description: 'Description text below label.',
- isDisabled: 'Whether this individual radio item disabled.',
- startContent: 'Content rendered before radio circle.',
- endContent: 'Content rendered after label.',
- },
- },
- ],
};
diff --git a/packages/core/src/RadioList/RadioListItem.doc.mjs b/packages/core/src/RadioList/RadioListItem.doc.mjs
new file mode 100644
index 0000000000..0c765790bd
--- /dev/null
+++ b/packages/core/src/RadioList/RadioListItem.doc.mjs
@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'RadioListItem',
+ subComponentOf: 'RadioList',
+ displayName: 'Radio List Item',
+ isHiddenFromOverview: true,
+ description: 'Individual radio item with label, description, and content slots.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for the radio item.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Value of this radio item.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether this individual radio item is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description: 'Content to render before the radio circle.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Content to render after the label.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
+ },
+ {
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
+ },
+ ],
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'RadioListItem',
+ isHiddenFromOverview: true,
+ displayName: 'Radio List Item',
+ description: '单个单选选项,包含标签、描述和内容插槽。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '单选选项的标签文本。',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: '此单选选项的值。',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: '显示在标签下方的描述文本。',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '是否禁用此单个单选选项。',
+ default: 'false',
+ },
+ {
+ name: 'startContent',
+ type: 'ReactNode',
+ description: '在单选圆圈前渲染的内容。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '在标签后渲染的内容。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'RadioListItem',
+ isHiddenFromOverview: true,
+ displayName: 'Radio List Item',
+ description: 'Individual radio item w/ label, description, content slots.',
+ propDescriptions: {
+ label: 'Label text for radio item.',
+ value: 'Value of this radio item.',
+ description: 'Description text below label.',
+ isDisabled: 'Whether this individual radio item disabled.',
+ startContent: 'Content rendered before radio circle.',
+ endContent: 'Content rendered after label.',
+ },
+};
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index 6c345175d0..242dd511b6 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -27,105 +27,67 @@ export const docs = {
{property: 'padding', vars: ['--_segmented-control-padding']},
],
},
- components: [
+ description: 'Container wrapper providing context (value, onChange, size, isDisabled) to XDSSegmentedControlItem children.',
+ props: [
{
- name: 'XDSSegmentedControl',
- displayName: 'Segmented Control',
- description:
- 'Container wrapper providing context (value, onChange, size, isDisabled) to XDSSegmentedControlItem children.',
- props: [
- {
- name: 'value',
- type: 'string',
- description: 'The currently selected value (controlled).',
- required: true,
- },
- {
- name: 'onChange',
- type: '(value: string) => void',
- description: 'Callback fired when a segment is selected.',
- required: true,
- },
- {
- name: 'label',
- type: 'string',
- description:
- 'Accessible label for the radio group (used as aria-label, never rendered visually).',
- required: true,
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: 'Size variant for the control.',
- default: "'md'",
- },
- {
- name: 'layout',
- type: "'hug' | 'fill'",
- description: 'Layout mode. hug (default) sizes segments to content; fill stretches them equally to fill the container.',
- default: "'hug'",
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether the entire control is disabled.',
- default: 'false',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'XDSSegmentedControlItem children.',
- slotElements: [{__element: 'XDSSegmentedControlItem', props: {label: 'Option', value: 'option'}}],
- required: true,
- },
- {
- 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={{}}.',
- },
- ], },
+ name: 'value',
+ type: 'string',
+ description: 'The currently selected value (controlled).',
+ required: true,
+ },
{
- name: 'XDSSegmentedControlItem',
- isHiddenFromOverview: true,
- displayName: 'Segmented Control Item',
- description:
- 'Individual segment item rendering as a radio button within the segmented control.',
- props: [
- {
- name: 'value',
- type: 'string',
- description:
- 'Unique value for this segment, matched against the parent value.',
- required: true,
- },
- {
- name: 'label',
- type: 'string',
- description:
- 'Accessible label for this segment. Rendered as visible text unless isLabelHidden is true.',
- required: true,
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description:
- 'Whether the label is visually hidden. When true, only the icon is displayed and label is used as aria-label.',
- default: 'false',
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: 'Icon element displayed before the label.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Callback fired when a segment is selected.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the radio group (used as aria-label, never rendered visually).',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant for the control.',
+ default: "'md'",
+ },
+ {
+ name: 'layout',
+ type: "'hug' | 'fill'",
+ description: 'Layout mode. hug (default) sizes segments to content; fill stretches them equally to fill the container.',
+ default: "'hug'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the entire control is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSSegmentedControlItem children.',
+ slotElements: [
{
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether this individual item is disabled.',
- default: 'false',
+ __element: 'XDSSegmentedControlItem',
+ props: {
+ label: 'Option',
+ value: 'option',
+ },
},
],
+ required: true,
},
+ {
+ 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={{}}.',
+ },
+ ],
+ components: [
+ {name: 'XDSSegmentedControlItem'},
],
usage: {
description:
@@ -141,38 +103,6 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- components: [
- {
- name: 'XDSSegmentedControl',
- displayName: 'Segmented Control',
- description:
- '容器包装组件,通过上下文向 XDSSegmentedControlItem 子组件提供 value、onChange、size、isDisabled。',
- propDescriptions: {
- value: '当前选中值(受控)。',
- onChange: '选中分段时触发的回调。',
- label: '单选组的无障碍标签(用作 aria-label,不会渲染为可见内容)。',
- size: '控件的尺寸变体。',
- layout: '布局模式。hug(默认)根据内容调整分段宽度;fill 将分段等宽拉伸以填满容器。',
- isDisabled: '是否禁用整个控件。',
- children: 'XDSSegmentedControlItem 子组件。',
- xstyle: '容器的额外 StyleX 样式。',
- },
- },
- {
- name: 'XDSSegmentedControlItem',
- isHiddenFromOverview: true,
- displayName: 'Segmented Control Item',
- description:
- '单个分段项,在分段控件中渲染为单选按钮。',
- propDescriptions: {
- value: '该分段的唯一值,与父组件的 value 匹配。',
- label: '该分段的无障碍标签。除非 isLabelHidden 为 true,否则渲染为可见文本。',
- isLabelHidden: '是否在视觉上隐藏标签。为 true 时仅显示图标,label 用作 aria-label。',
- icon: '显示在标签前的图标元素。',
- isDisabled: '是否禁用该单个项。',
- },
- },
- ],
usage: {
description:
'A segmented button group that allows users to make a single selection from a small set of mutually exclusive options. Use SegmentedControl when all options should be visible at once and the selection controls a value or mode, not page navigation.',
@@ -207,34 +137,4 @@ export const docsDense = {
children: 'XDSSegmentedControlItem children',
xstyle: 'additional StyleX styles for container',
},
- components: [
- {
- name: 'XDSSegmentedControl',
- displayName: 'Segmented Control',
- description: 'container; provides context (value/onChange/size/layout/isDisabled) to children',
- propDescriptions: {
- value: 'selected value (controlled)',
- onChange: 'selection callback',
- label: 'aria-label for radio group (not rendered)',
- size: 'size variant',
- layout: 'hug (default) sizes to content; fill stretches equally',
- isDisabled: 'disables entire control',
- children: 'XDSSegmentedControlItem children',
- xstyle: 'extra StyleX styles',
- },
- },
- {
- name: 'XDSSegmentedControlItem',
- isHiddenFromOverview: true,
- displayName: 'Segmented Control Item',
- description: 'individual segment; renders as radio button in control',
- propDescriptions: {
- value: 'unique segment value; matched against parent',
- label: 'segment label; visible unless isLabelHidden',
- isLabelHidden: 'hides label visually; label becomes aria-label',
- icon: 'icon before label',
- isDisabled: 'disables this item',
- },
- },
- ],
};
diff --git a/packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs
new file mode 100644
index 0000000000..0b5479a299
--- /dev/null
+++ b/packages/core/src/SegmentedControl/SegmentedControlItem.doc.mjs
@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SegmentedControlItem',
+ subComponentOf: 'SegmentedControl',
+ displayName: 'Segmented Control Item',
+ isHiddenFromOverview: true,
+ description: 'Individual segment item rendering as a radio button within the segmented control.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Unique value for this segment, matched against the parent value.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for this segment. Rendered as visible text unless isLabelHidden is true.',
+ required: true,
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Whether the label is visually hidden. When true, only the icon is displayed and label is used as aria-label.',
+ default: 'false',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon element displayed before the label.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether this individual item is disabled.',
+ default: 'false',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'SegmentedControlItem',
+ isHiddenFromOverview: true,
+ displayName: 'Segmented Control Item',
+ description: '单个分段项,在分段控件中渲染为单选按钮。',
+ propDescriptions: {
+ value: '该分段的唯一值,与父组件的 value 匹配。',
+ label: '该分段的无障碍标签。除非 isLabelHidden 为 true,否则渲染为可见文本。',
+ isLabelHidden: '是否在视觉上隐藏标签。为 true 时仅显示图标,label 用作 aria-label。',
+ icon: '显示在标签前的图标元素。',
+ isDisabled: '是否禁用该单个项。',
+ },
+};
+
+export const docsDense = {
+ name: 'SegmentedControlItem',
+ isHiddenFromOverview: true,
+ displayName: 'Segmented Control Item',
+ description: 'individual segment; renders as radio button in control',
+ propDescriptions: {
+ value: 'unique segment value; matched against parent',
+ label: 'segment label; visible unless isLabelHidden',
+ isLabelHidden: 'hides label visually; label becomes aria-label',
+ icon: 'icon before label',
+ isDisabled: 'disables this item',
+ },
+};
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index b87cfaa45f..62b545a629 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -14,141 +14,104 @@ export const docs = {
{className: 'xds-selector-option'},
],
},
- components: [
+ description: 'Dropdown selector for choosing from a list of options.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for accessibility.',
+ required: true,
+ },
+ {
+ name: 'options',
+ type: 'XDSSelectorOption[]',
+ description: 'Array of items — strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Currently selected value.',
+ },
+ {
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Callback fired when the selection changes.',
+ },
+ {
+ name: 'hasClear',
+ type: 'boolean',
+ description: 'Shows a clear (×) button when a value is selected. When true, onChange also accepts null to signal the user cleared the selection.',
+ default: 'false',
+ },
+ {
+ name: 'hasSearch',
+ type: 'boolean',
+ description: 'Whether to show a search input for filtering options.',
+ default: 'false',
+ },
+ {
+ name: 'searchPlaceholder',
+ type: 'string',
+ description: 'Placeholder text for the search input.',
+ default: "'Search...'",
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text shown when no value is selected.',
+ default: "'Select...'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant for the selector.',
+ default: "'md'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the selector.',
+ },
{
- name: 'XDSSelector',
- displayName: 'Selector',
- description: 'Dropdown selector for choosing from a list of options.',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Label text for accessibility.',
- required: true,
- },
- {
- name: 'options',
- type: 'XDSSelectorOption[]',
- description:
- 'Array of items: strings, objects with value/label/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, items}).',
- required: true,
- },
- {
- name: 'value',
- type: 'string',
- description: 'Currently selected value.',
- },
- {
- name: 'onChange',
- type: '(value: string) => void',
- description: 'Callback fired when the selection changes.',
- },
- {
- name: 'hasClear',
- type: 'boolean',
- description:
- 'Shows a clear (\u00d7) button when a value is selected. When true, onChange also accepts null to signal the user cleared the selection.',
- default: 'false',
- },
- {
- name: 'hasSearch',
- type: 'boolean',
- description: 'Whether to show a search input for filtering options.',
- default: 'false',
- },
- {
- name: 'searchPlaceholder',
- type: 'string',
- description: 'Placeholder text for the search input.',
- default: "'Search...'",
- },
- {
- name: 'placement',
- type: "'above' | 'below' | 'start' | 'end'",
- description:
- 'Dropdown placement relative to the trigger. Omit for the default selector behavior: align the selected item over the trigger and clamp the menu to the viewport. Set a value to use explicit layer positioning.',
- },
- {
- name: 'placeholder',
- type: 'string',
- description: 'Placeholder text shown when no value is selected.',
- default: "'Select...'",
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: 'Size variant for the selector.',
- default: "'md'",
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Disables the selector.',
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: 'Visually hides the label while keeping it accessible.',
- },
- {
- name: 'description',
- type: 'string',
- description: 'Helper text displayed below the label.',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description: 'Marks the field as optional.',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description: 'Marks the field as required.',
- },
- {
- name: 'status',
- type: "{type: 'error' | 'warning' | 'success', message?: string}",
- description: 'Validation status with an optional message.',
- },
- {
- name: 'children',
- type: '(item: XDSSelectorOptionData) => ReactNode',
- description: 'Custom render function for each item in the dropdown.',
- },
- {
- 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={{}}.',
- },
- ],
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hides the label while keeping it accessible.',
},
{
- name: 'XDSSelectorOption',
- isHiddenFromOverview: true,
- displayName: 'Selector Option',
- description:
- 'Helper component for custom item rendering inside an XDSSelector children render prop.',
- props: [
- {
- name: 'label',
- type: 'ReactNode',
- description: 'Primary label text for the item.',
- required: true,
- },
- {
- name: 'icon',
- type: 'XDSIconType',
- description: 'Icon displayed before the label. See `npx xds docs icons` for valid semantic names.',
- },
- {
- name: 'description',
- type: 'ReactNode',
- description: 'Secondary description text displayed below the label.',
- },
- ],
+ name: 'description',
+ type: 'string',
+ description: 'Helper text displayed below the label.',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Marks the field as optional.',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Marks the field as required.',
+ },
+ {
+ name: 'status',
+ type: "{type: 'error' | 'warning' | 'success', message?: string}",
+ description: 'Validation status with an optional message.',
+ },
+ {
+ name: 'children',
+ type: '(item: XDSSelectorOptionData) => ReactNode',
+ description: 'Custom render function for each item in the dropdown.',
+ },
+ {
+ 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={{}}.',
},
],
+ components: [
+ {name: 'XDSSelectorOption'},
+ ],
usage: {
description:
'A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options.',
@@ -173,150 +136,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Selector',
- displayName: 'Selector',
- theming: {
- targets: [
- {className: 'xds-selector', visualProps: ['size', 'status']},
- {className: 'xds-selector-option'},
- ],
- },
- components: [
- {
- name: 'XDSSelector',
- displayName: 'Selector',
- description: '用于从选项列表中进行选择的下拉选择器。',
- props: [
- {
- name: 'label',
- type: 'string',
- description: '无障碍标签文本。',
- required: true,
- },
- {
- name: 'options',
- type: 'XDSSelectorOption[]',
- description:
- '选项数组 - 字符串、带 value/label/icon/disabled 的对象、分隔线({type: "divider"})或分组({type: "section", title, items})。',
- required: true,
- },
- {
- name: 'value',
- type: 'string',
- description: '当前选中的值。',
- },
- {
- name: 'onChange',
- type: '(value: string) => void',
- description: '选择变更时触发的回调函数。',
- },
- {
- name: 'hasClear',
- type: 'boolean',
- description: '选中值时显示清除 (×) 按鈕。启用后,onChange 还接受 null 表示用户已清除选择。',
- default: 'false',
- },
- {
- name: 'hasSearch',
- type: 'boolean',
- description: '是否显示用于过滤选项的搜索输入。',
- default: 'false',
- },
- {
- name: 'searchPlaceholder',
- type: 'string',
- description: '搜索输入的占位文本。',
- default: "'Search...'",
- },
- {
- name: 'placement',
- type: "'above' | 'below' | 'start' | 'end'",
- description:
- '下拉层相对于触发器的位置。省略时使用选择器默认行为:将已选项对齐到触发器上并限制在视口内。设置后使用显式图层定位。',
- },
- {
- name: 'placeholder',
- type: 'string',
- description: '未选择值时显示的占位文本。',
- default: "'Select...'",
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: '选择器的尺寸变体。',
- default: "'md'",
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '禁用选择器。',
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: '视觉上隐藏标签,同时保持无障碍可访问性。',
- },
- {
- name: 'description',
- type: 'string',
- description: '显示在标签下方的辅助文本。',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description: '将字段标记为可选。',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description: '将字段标记为必填。',
- },
- {
- name: 'status',
- type: "{type: 'error' | 'warning' | 'success', message?: string}",
- description: '验证状态,附带可选消息。',
- },
- {
- name: 'children',
- type: '(item: XDSSelectorOptionData) => ReactNode',
- description: '下拉菜单中每个选项的自定义渲染函数。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSSelectorOption',
- isHiddenFromOverview: true,
- displayName: 'Selector Option',
- description:
- '用于在 XDSSelector 的 children 渲染函数中自定义选项渲染的辅助组件。',
- props: [
- {
- name: 'label',
- type: 'ReactNode',
- description: '选项的主标签文本。',
- required: true,
- },
- {
- name: 'icon',
- type: 'XDSIconType',
- description: '显示在标签前的图标。',
- },
- {
- name: 'description',
- type: 'ReactNode',
- description: '显示在标签下方的次要描述文本。',
- },
- ],
- },
- ],
usage: {
description:
'A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options.',
@@ -365,43 +186,4 @@ export const docsDense = {
{name: 'List', required: true, description: 'The dropdown list of selectable options.'},
],
},
- components: [
- {
- name: 'XDSSelector',
- displayName: 'Selector',
- description: 'Dropdown selector for choosing from list of options.',
- propDescriptions: {
- label: 'Label text for accessibility.',
- options: 'Array of items; strings, objects w/ value/label/icon/disabled, dividers ({type: "divider"}), sections ({type: "section", title, items}).',
- value: 'Currently selected value.',
- onChange: 'Callback fired when selection changes.',
- hasClear: 'Shows clear button when value selected. onChange also accepts null on clear.',
- hasSearch: 'Shows search input for filtering options.',
- searchPlaceholder: 'Placeholder text for search input.',
- placement: 'Dropdown placement. Omit for selected-item overlay clamped to viewport; set value for explicit layer positioning.',
- placeholder: 'Placeholder text when no value selected.',
- size: 'Size variant for selector.',
- isDisabled: 'Disables selector.',
- isLabelHidden: 'Visually hides label while keeping accessible.',
- description: 'Helper text below label.',
- isOptional: 'Marks field optional.',
- isRequired: 'Marks field required.',
- status: 'Validation status w/ optional message.',
- children: 'Custom render function for each dropdown item.',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSSelectorOption',
- isHiddenFromOverview: true,
- displayName: 'Selector Option',
- description:
- 'Helper component for custom item rendering inside XDSSelector children render prop.',
- propDescriptions: {
- label: 'Primary label text for item.',
- icon: 'Icon displayed before label.',
- description: 'Secondary description text below label.',
- },
- },
- ],
};
diff --git a/packages/core/src/Selector/SelectorOption.doc.mjs b/packages/core/src/Selector/SelectorOption.doc.mjs
new file mode 100644
index 0000000000..b7c33ad280
--- /dev/null
+++ b/packages/core/src/Selector/SelectorOption.doc.mjs
@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SelectorOption',
+ subComponentOf: 'Selector',
+ displayName: 'Selector Option',
+ isHiddenFromOverview: true,
+ description: 'Helper component for custom item rendering inside an XDSSelector children render prop.',
+ props: [
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: 'Primary label text for the item.',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: 'Icon displayed before the label. See `npx xds docs icons` for valid semantic names.',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: 'Secondary description text displayed below the label.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'SelectorOption',
+ isHiddenFromOverview: true,
+ displayName: 'Selector Option',
+ description: '用于在 XDSSelector 的 children 渲染函数中自定义选项渲染的辅助组件。',
+ props: [
+ {
+ name: 'label',
+ type: 'ReactNode',
+ description: '选项的主标签文本。',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: '显示在标签前的图标。',
+ },
+ {
+ name: 'description',
+ type: 'ReactNode',
+ description: '显示在标签下方的次要描述文本。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'SelectorOption',
+ isHiddenFromOverview: true,
+ displayName: 'Selector Option',
+ description: 'Helper component for custom item rendering inside XDSSelector children render prop.',
+ propDescriptions: {
+ label: 'Primary label text for item.',
+ icon: 'Icon displayed before label.',
+ description: 'Secondary description text below label.',
+ },
+};
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index 6edb31a5d2..8c96463d3d 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -25,270 +25,99 @@ export const docs = {
{className: 'xds-side-nav-section'},
],
},
- components: [
+ description: 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.',
+ props: [
{
- name: 'XDSSideNav',
- displayName: 'Side Nav',
- description:
- 'Container with five zones: header, topContent, children (scrollable), footer, and footerIcons. Supports collapsible mode.',
- props: [
- {
- name: 'header',
- type: 'ReactNode',
- description: 'Header area (typically XDSSideNavHeading). Sticky.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Header'}],
- },
- {
- name: 'topContent',
- type: 'ReactNode',
- description: 'Content below the header, e.g., a create button.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Top content'}],
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Navigation sections and items. Scrollable.',
- slotElements: [{__element: 'XDSSideNavItem', props: {label: 'Nav Item'}}],
- },
- {
- name: 'footer',
- type: 'ReactNode',
- description: 'Footer area above the icon bar.',
- slotElements: [{__element: 'XDSText', props: {type: 'body'}, children: 'Footer content'}],
- },
- {
- name: 'footerIcons',
- type: 'ReactNode',
- description: 'Footer icon bar.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'collapsible',
- type: "boolean | { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void; hasButton?: boolean; buttonLabel?: string }",
- description:
- 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).',
- default: 'false',
- },
- {
- name: 'handleRef',
- type: 'Ref<XDSSideNavImperativeCollapseHandle>',
- description:
- 'Imperative collapse handle for XDSSideNavCollapseButton instances rendered outside this SideNav. Separate from `ref`, which continues to expose the root HTMLElement.',
- },
+ name: 'header',
+ type: 'ReactNode',
+ description: 'Header area (typically XDSSideNavHeading). Sticky.',
+ slotElements: [
{
- 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={{}}.',
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Header',
},
- ], },
+ ],
+ },
{
- name: 'XDSSideNavHeading',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Heading',
- description:
- 'Product/suite/account heading with smart interaction boundary logic for links and a menu popover.',
- props: [
- {
- name: 'heading',
- type: 'string',
- description: 'Product/app name.',
- required: true,
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: 'Product/app icon.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
+ name: 'topContent',
+ type: 'ReactNode',
+ description: 'Content below the header, e.g., a create button.',
+ slotElements: [
{
- name: 'headingHref',
- type: 'string',
- description: 'Link for the heading.',
- },
- {
- name: 'superheading',
- type: 'string',
- description: 'Text above the heading.',
- },
- {
- name: 'superheadingHref',
- type: 'string',
- description: 'Link for the superheading.',
- },
- {
- name: 'subheading',
- type: 'string',
- description: 'Text below the heading.',
- },
- {
- name: 'subheadingHref',
- type: 'string',
- description: 'Link for the subheading.',
- },
- {
- name: 'menu',
- type: 'ReactNode',
- description: 'Menu content rendered inside a popover.',
- slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
- },
- {
- name: 'headerEndContent',
- type: 'ReactNode',
- description: 'Content rendered at the trailing edge of the heading row, between text and chevron. Useful for badges, status indicators, or compact action buttons. Hidden when collapsed.',
- slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Top content',
},
],
},
{
- name: 'XDSSideNavItem',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Item',
- description:
- 'Navigation item with icon, selected state, optional end content, and nesting support via children.',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Item label.',
- required: true,
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description: 'Custom link component.',
- },
- {
- name: 'icon',
- type: 'XDSIconType',
- description: 'Icon displayed in the outline (unselected) variant. See `npx xds docs icons` for valid semantic names.',
- },
- {
- name: 'selectedIcon',
- type: 'XDSIconType',
- description:
- 'Icon displayed when the item is selected (filled variant). See `npx xds docs icons` for valid semantic names.',
- },
- {
- name: 'isSelected',
- type: 'boolean',
- description: 'Marks this item as the current page.',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Disabled state.',
- default: 'false',
- },
- {
- name: 'href',
- type: 'string',
- description: 'Navigation URL.',
- },
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Navigation sections and items. Scrollable.',
+ slotElements: [
{
- name: 'onClick',
- type: '(e: MouseEvent) => void',
- description: 'Click handler.',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description: 'Right-side content such as badges or counts.',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Sub-items for nesting.',
- slotElements: [{__element: 'XDSSideNavItem', props: {label: 'Sub Item'}}],
- },
- {
- name: 'collapsible',
- type: 'boolean | { defaultIsCollapsed?: boolean, isCollapsed?: boolean, onCollapsedChange?: (isCollapsed: boolean) => void }',
- description: 'Enables collapse behavior for items with children. Pass true for uncontrolled (starts expanded), or an object for controlled mode.',
- default: 'false',
+ __element: 'XDSSideNavItem',
+ props: {
+ label: 'Nav Item',
+ },
},
],
},
{
- name: 'XDSSideNavSection',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Section',
- description:
- 'Section grouping with an optional title, subtitle, and end content.',
- props: [
- {
- name: 'title',
- type: 'string',
- description: 'Section title.',
- required: true,
- },
- {
- name: 'subtitle',
- type: 'string',
- description: 'Section subtitle.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Section items.',
- slotElements: [{__element: 'XDSSideNavItem', props: {label: 'Item'}}],
- },
+ name: 'footer',
+ type: 'ReactNode',
+ description: 'Footer area above the icon bar.',
+ slotElements: [
{
- name: 'endContent',
- type: 'ReactNode',
- description: 'Right-side content in the section header.',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
- },
- {
- name: 'isHeaderHidden',
- type: 'boolean',
- description:
- 'Visually hides the section header while keeping it accessible to screen readers.',
- default: 'false',
- },
- {
- 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={{}}.',
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ },
+ children: 'Footer content',
},
],
},
{
- name: 'XDSSideNavCollapseButton',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Collapse Button',
- description:
- 'Toggle button for sidenav collapse. Place inside XDSSideNav (reads context automatically) or outside (pass handleRef). Renders as an icon-only ghost button by default.',
- props: [
- {
- name: 'handleRef',
- type: 'RefObject<XDSSideNavImperativeCollapseHandle | null>',
- description:
- 'Imperative collapse handle from XDSSideNav. Only needed when the button is rendered outside the sidenav.',
- },
+ name: 'footerIcons',
+ type: 'ReactNode',
+ description: 'Footer icon bar.',
+ slotElements: [
{
- name: 'label',
- type: 'string',
- description:
- 'Custom button label. When provided, renders as a text button with chevron. When omitted, renders icon-only.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Custom button content. Overrides the default chevron icon and label.',
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
},
],
},
+ {
+ name: 'collapsible',
+ type: 'boolean | { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void; hasButton?: boolean; buttonLabel?: string }',
+ description: 'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).',
+ default: 'false',
+ },
+ {
+ name: 'handleRef',
+ type: 'Ref<XDSSideNavImperativeCollapseHandle>',
+ description: 'Imperative collapse handle for XDSSideNavCollapseButton instances rendered outside this SideNav. Separate from `ref`, which continues to expose the root HTMLElement.',
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+ components: [
+ {name: 'XDSSideNavHeading'},
+ {name: 'XDSSideNavItem'},
+ {name: 'XDSSideNavSection'},
+ {name: 'XDSSideNavCollapseButton'},
],
usage: {
description:
@@ -307,260 +136,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'SideNav',
- displayName: 'Side Nav',
- theming: {
- targets: [
- {className: 'xds-side-nav', visualProps: ['mode']},
- {className: 'xds-side-nav-heading'},
- {className: 'xds-side-nav-item'},
- {className: 'xds-side-nav-section'},
- ],
- },
- components: [
- {
- name: 'XDSSideNav',
- displayName: 'Side Nav',
- description:
- '包含五个区域的容器:header、topContent、children(可滚动)、footer 和 footerIcons。',
- props: [
- {
- name: 'header',
- type: 'ReactNode',
- description: '头部区域(通常为 XDSSideNavHeading)。固定定位。',
- },
- {
- name: 'topContent',
- type: 'ReactNode',
- description: '头部下方的内容,例如创建按钮。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '导航分组和项目。可滚动。',
- },
- {
- name: 'footer',
- type: 'ReactNode',
- description: '图标栏上方的底部区域。',
- },
- {
- name: 'footerIcons',
- type: 'ReactNode',
- description: '底部图标栏。',
- },
- {
- name: 'collapsible',
- type: "boolean | { defaultIsCollapsed?: boolean; isCollapsed?: boolean; onCollapsedChange?: (isCollapsed: boolean) => void; hasButton?: boolean; buttonLabel?: string }",
- description:
- '启用折叠行为。true 表示非受控模式并带默认切换按钮,或传入对象进行受控模式和高级配置(defaultIsCollapsed、isCollapsed + onCollapsedChange、hasButton、buttonLabel)。',
- default: 'false',
- },
- {
- name: 'handleRef',
- type: 'Ref<XDSSideNavImperativeCollapseHandle>',
- description:
- '供渲染在 SideNav 外部的 XDSSideNavCollapseButton 使用的命令式折叠句柄。与 `ref` 分离,`ref` 仍然指向根 HTMLElement。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSSideNavHeading',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Heading',
- description:
- '产品/套件/账户头部,具有智能交互边界逻辑,支持链接和菜单弹出框。',
- props: [
- {
- name: 'heading',
- type: 'string',
- description: '产品/应用名称。',
- required: true,
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: '产品/应用图标。',
- },
- {
- name: 'headingHref',
- type: 'string',
- description: '标题的链接。',
- },
- {
- name: 'superheading',
- type: 'string',
- description: '标题上方的文本。',
- },
- {
- name: 'superheadingHref',
- type: 'string',
- description: '上方标题的链接。',
- },
- {
- name: 'subheading',
- type: 'string',
- description: '标题下方的文本。',
- },
- {
- name: 'subheadingHref',
- type: 'string',
- description: '下方标题的链接。',
- },
- {
- name: 'menu',
- type: 'ReactNode',
- description: '在弹出框内渲染的菜单内容。',
- },
- {
- name: 'headerEndContent',
- type: 'ReactNode',
- description: '在标题行尾部渲染的内容,位于文本和箭头之间。适用于徽章、状态指示器或紧凑操作按钮。折叠时隐藏。',
- },
- ],
- },
- {
- name: 'XDSSideNavItem',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Item',
- description:
- '导航项,支持图标、选中状态、可选尾部内容,以及通过 children 实现嵌套。',
- props: [
- {
- name: 'label',
- type: 'string',
- description: '项目标签。',
- required: true,
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description: '自定义链接组件。',
- },
- {
- name: 'icon',
- type: 'XDSIconType',
- description: '轮廓(未选中)变体中显示的图标。',
- },
- {
- name: 'selectedIcon',
- type: 'XDSIconType',
- description:
- '选中时显示的图标(填充变体)。',
- },
- {
- name: 'isSelected',
- type: 'boolean',
- description: '将此项标记为当前页面。',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '禁用状态。',
- default: 'false',
- },
- {
- name: 'href',
- type: 'string',
- description: '导航 URL。',
- },
- {
- name: 'onClick',
- type: '(e: MouseEvent) => void',
- description: '点击处理函数。',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description: '右侧内容,如徽章或计数。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '用于嵌套的子项。',
- },
- {
- name: 'collapsible',
- type: 'boolean | { defaultIsCollapsed?: boolean, isCollapsed?: boolean, onCollapsedChange?: (isCollapsed: boolean) => void }',
- description: '启用带子项的折叠行为。传 true 为非受控模式(默认展开),或传对象用于受控模式。',
- default: 'false',
- },
- ],
- },
- {
- name: 'XDSSideNavSection',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Section',
- description:
- '分组,支持可选的标题、副标题和尾部内容。',
- props: [
- {
- name: 'title',
- type: 'string',
- description: '分组标题。',
- required: true,
- },
- {
- name: 'subtitle',
- type: 'string',
- description: '分组副标题。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '分组项目。',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description: '分组头部的右侧内容。',
- },
- {
- name: 'isHeaderHidden',
- type: 'boolean',
- description:
- '视觉上隐藏分组头部,同时保持屏幕阅读器可访问。',
- default: 'false',
- },
- ],
- },
- {
- name: 'XDSSideNavCollapseButton',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Collapse Button',
- description:
- '侧边栏折叠切换按钮。放置在 XDSSideNav 内部(自动读取上下文)或外部(传入 handleRef)。默认渲染为仅图标的 ghost 按钮。',
- props: [
- {
- name: 'handleRef',
- type: 'RefObject<XDSSideNavImperativeCollapseHandle | null>',
- description:
- '来自 XDSSideNav 的命令式折叠句柄。仅在按钮渲染在侧边栏外部时需要。',
- },
- {
- name: 'label',
- type: 'string',
- description:
- '自定义按钮标签。提供时渲染为带箭头的文本按钮。省略时渲染为仅图标按钮。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- '自定义按钮内容。覆盖默认的箭头图标和标签。',
- },
- ],
- },
- ],
usage: {
description:
'A sidebar navigation component for organizing application pages with sections, nested items, and icons. Use SideNav as the primary navigation when an app has 5 or more destinations or requires hierarchical grouping.',
@@ -595,87 +172,4 @@ export const docsDense = {
{name: 'Collapse/expand toggle', required: false, description: 'Toggle to collapse or expand the side nav.'},
],
},
- components: [
- {
- name: 'XDSSideNav',
- displayName: 'Side Nav',
- description:
- 'Container w/ five zones: header, topContent, children (scrollable), footer, footerIcons. Supports collapsible mode.',
- propDescriptions: {
- header: 'Header area (typically XDSSideNavHeading). Sticky.',
- topContent: 'Content below header, e.g. create button.',
- children: 'Navigation sections + items. Scrollable.',
- footer: 'Footer area above icon bar.',
- footerIcons: 'Footer icon bar.',
- collapsible: 'Enables collapse behavior. true for uncontrolled w/ default toggle, or object for controlled mode (defaultIsCollapsed, isCollapsed+onCollapsedChange, hasButton, buttonLabel).',
- handleRef: 'Imperative collapse handle for XDSSideNavCollapseButton outside this SideNav. `ref` still exposes the root HTMLElement.',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSSideNavHeading',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Heading',
- description:
- 'Product/suite/account heading w/ smart interaction boundary logic for links + menu popover.',
- propDescriptions: {
- heading: 'Product/app name.',
- icon: 'Product/app icon.',
- headingHref: 'Link for heading.',
- superheading: 'Text above heading.',
- superheadingHref: 'Link for superheading.',
- subheading: 'Text below heading.',
- subheadingHref: 'Link for subheading.',
- menu: 'Menu content rendered inside popover.',
- headerEndContent: 'Content at trailing edge of heading row. For badges, status indicators, action buttons. Hidden when collapsed.',
- },
- },
- {
- name: 'XDSSideNavItem',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Item',
- description:
- 'Navigation item w/ icon, selected state, optional end content, nesting via children.',
- propDescriptions: {
- label: 'Item label.',
- as: 'Custom link component.',
- icon: 'Icon displayed in outline (unselected) variant.',
- selectedIcon: 'Icon displayed when item selected (filled variant).',
- isSelected: 'Marks this item as current page.',
- isDisabled: 'Disabled state.',
- href: 'Navigation URL.',
- onClick: 'Click handler.',
- endContent: 'Right-side content such as badges or counts.',
- children: 'Sub-items for nesting.',
- collapsible: 'Enables collapse for items w/ children. true=uncontrolled, object=controlled mode.',
- },
- },
- {
- name: 'XDSSideNavSection',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Section',
- description:
- 'Section grouping w/ optional title, subtitle, end content.',
- propDescriptions: {
- title: 'Section title.',
- subtitle: 'Section subtitle.',
- children: 'Section items.',
- endContent: 'Right-side content in section header.',
- isHeaderHidden: 'Visually hides section header while keeping accessible to screen readers.',
- xstyle: 'StyleX styles for layout customization.',
- },
- },
- {
- name: 'XDSSideNavCollapseButton',
- isHiddenFromOverview: true,
- displayName: 'Side Nav Collapse Button',
- description:
- 'Toggle button for sidenav collapse. Place inside XDSSideNav (reads context) or outside (pass handleRef). Icon-only ghost button by default.',
- propDescriptions: {
- handleRef: 'Imperative collapse handle from XDSSideNav. Only needed when button rendered outside sidenav.',
- label: 'Custom label. Text button w/ chevron when provided, icon-only when omitted.',
- children: 'Custom content. Overrides default chevron icon + label.',
- },
- },
- ],
};
diff --git a/packages/core/src/SideNav/SideNavCollapseButton.doc.mjs b/packages/core/src/SideNav/SideNavCollapseButton.doc.mjs
new file mode 100644
index 0000000000..a6269b2add
--- /dev/null
+++ b/packages/core/src/SideNav/SideNavCollapseButton.doc.mjs
@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SideNavCollapseButton',
+ subComponentOf: 'SideNav',
+ displayName: 'Side Nav Collapse Button',
+ isHiddenFromOverview: true,
+ description: 'Toggle button for sidenav collapse. Place inside XDSSideNav (reads context automatically) or outside (pass handleRef). Renders as an icon-only ghost button by default.',
+ props: [
+ {
+ name: 'handleRef',
+ type: 'RefObject<XDSSideNavImperativeCollapseHandle | null>',
+ description: 'Imperative collapse handle from XDSSideNav. Only needed when the button is rendered outside the sidenav.',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Custom button label. When provided, renders as a text button with chevron. When omitted, renders icon-only.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Custom button content. Overrides the default chevron icon and label.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'SideNavCollapseButton',
+ isHiddenFromOverview: true,
+ displayName: 'Side Nav Collapse Button',
+ description: '侧边栏折叠切换按钮。放置在 XDSSideNav 内部(自动读取上下文)或外部(传入 handleRef)。默认渲染为仅图标的 ghost 按钮。',
+ props: [
+ {
+ name: 'handleRef',
+ type: 'RefObject<XDSSideNavImperativeCollapseHandle | null>',
+ description: '来自 XDSSideNav 的命令式折叠句柄。仅在按钮渲染在侧边栏外部时需要。',
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '自定义按钮标签。提供时渲染为带箭头的文本按钮。省略时渲染为仅图标按钮。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '自定义按钮内容。覆盖默认的箭头图标和标签。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'SideNavCollapseButton',
+ isHiddenFromOverview: true,
+ displayName: 'Side Nav Collapse Button',
+ description: 'Toggle button for sidenav collapse. Place inside XDSSideNav (reads context) or outside (pass handleRef). Icon-only ghost button by default.',
+ propDescriptions: {
+ handleRef: 'Imperative collapse handle from XDSSideNav. Only needed when button rendered outside sidenav.',
+ label: 'Custom label. Text button w/ chevron when provided, icon-only when omitted.',
+ children: 'Custom content. Overrides default chevron icon + label.',
+ },
+};
diff --git a/packages/core/src/SideNav/SideNavHeading.doc.mjs b/packages/core/src/SideNav/SideNavHeading.doc.mjs
new file mode 100644
index 0000000000..65ed3279f1
--- /dev/null
+++ b/packages/core/src/SideNav/SideNavHeading.doc.mjs
@@ -0,0 +1,161 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SideNavHeading',
+ subComponentOf: 'SideNav',
+ displayName: 'Side Nav Heading',
+ isHiddenFromOverview: true,
+ description: 'Product/suite/account heading with smart interaction boundary logic for links and a menu popover.',
+ props: [
+ {
+ name: 'heading',
+ type: 'string',
+ description: 'Product/app name.',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Product/app icon.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'headingHref',
+ type: 'string',
+ description: 'Link for the heading.',
+ },
+ {
+ name: 'superheading',
+ type: 'string',
+ description: 'Text above the heading.',
+ },
+ {
+ name: 'superheadingHref',
+ type: 'string',
+ description: 'Link for the superheading.',
+ },
+ {
+ name: 'subheading',
+ type: 'string',
+ description: 'Text below the heading.',
+ },
+ {
+ name: 'subheadingHref',
+ type: 'string',
+ description: 'Link for the subheading.',
+ },
+ {
+ name: 'menu',
+ type: 'ReactNode',
+ description: 'Menu content rendered inside a popover.',
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {
+ label: 'Action',
+ variant: 'ghost',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'headerEndContent',
+ type: 'ReactNode',
+ description: 'Content rendered at the trailing edge of the heading row, between text and chevron. Useful for badges, status indicators, or compact action buttons. Hidden when collapsed.',
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {
+ label: 'Action',
+ variant: 'ghost',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'SideNavHeading',
+ isHiddenFromOverview: true,
+ displayName: 'Side Nav Heading',
+ description: '产品/套件/账户头部,具有智能交互边界逻辑,支持链接和菜单弹出框。',
+ props: [
+ {
+ name: 'heading',
+ type: 'string',
+ description: '产品/应用名称。',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: '产品/应用图标。',
+ },
+ {
+ name: 'headingHref',
+ type: 'string',
+ description: '标题的链接。',
+ },
+ {
+ name: 'superheading',
+ type: 'string',
+ description: '标题上方的文本。',
+ },
+ {
+ name: 'superheadingHref',
+ type: 'string',
+ description: '上方标题的链接。',
+ },
+ {
+ name: 'subheading',
+ type: 'string',
+ description: '标题下方的文本。',
+ },
+ {
+ name: 'subheadingHref',
+ type: 'string',
+ description: '下方标题的链接。',
+ },
+ {
+ name: 'menu',
+ type: 'ReactNode',
+ description: '在弹出框内渲染的菜单内容。',
+ },
+ {
+ name: 'headerEndContent',
+ type: 'ReactNode',
+ description: '在标题行尾部渲染的内容,位于文本和箭头之间。适用于徽章、状态指示器或紧凑操作按钮。折叠时隐藏。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'SideNavHeading',
+ isHiddenFromOverview: true,
+ displayName: 'Side Nav Heading',
+ description: 'Product/suite/account heading w/ smart interaction boundary logic for links + menu popover.',
+ propDescriptions: {
+ heading: 'Product/app name.',
+ icon: 'Product/app icon.',
+ headingHref: 'Link for heading.',
+ superheading: 'Text above heading.',
+ superheadingHref: 'Link for superheading.',
+ subheading: 'Text below heading.',
+ subheadingHref: 'Link for subheading.',
+ menu: 'Menu content rendered inside popover.',
+ headerEndContent: 'Content at trailing edge of heading row. For badges, status indicators, action buttons. Hidden when collapsed.',
+ },
+};
diff --git a/packages/core/src/SideNav/SideNavItem.doc.mjs b/packages/core/src/SideNav/SideNavItem.doc.mjs
new file mode 100644
index 0000000000..ec7825b7d1
--- /dev/null
+++ b/packages/core/src/SideNav/SideNavItem.doc.mjs
@@ -0,0 +1,183 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SideNavItem',
+ subComponentOf: 'SideNav',
+ displayName: 'Side Nav Item',
+ isHiddenFromOverview: true,
+ description: 'Navigation item with icon, selected state, optional end content, and nesting support via children.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Item label.',
+ required: true,
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: 'Custom link component.',
+ },
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: 'Icon displayed in the outline (unselected) variant. See `npx xds docs icons` for valid semantic names.',
+ },
+ {
+ name: 'selectedIcon',
+ type: 'XDSIconType',
+ description: 'Icon displayed when the item is selected (filled variant). See `npx xds docs icons` for valid semantic names.',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: 'Marks this item as the current page.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disabled state.',
+ default: 'false',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'Navigation URL.',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: 'Click handler.',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Right-side content such as badges or counts.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
+ },
+ {
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
+ },
+ ],
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Sub-items for nesting.',
+ slotElements: [
+ {
+ __element: 'XDSSideNavItem',
+ props: {
+ label: 'Sub Item',
+ },
+ },
+ ],
+ },
+ {
+ name: 'collapsible',
+ type: 'boolean | { defaultIsCollapsed?: boolean, isCollapsed?: boolean, onCollapsedChange?: (isCollapsed: boolean) => void }',
+ description: 'Enables collapse behavior for items with children. Pass true for uncontrolled (starts expanded), or an object for controlled mode.',
+ default: 'false',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'SideNavItem',
+ isHiddenFromOverview: true,
+ displayName: 'Side Nav Item',
+ description: '导航项,支持图标、选中状态、可选尾部内容,以及通过 children 实现嵌套。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '项目标签。',
+ required: true,
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: '自定义链接组件。',
+ },
+ {
+ name: 'icon',
+ type: 'XDSIconType',
+ description: '轮廓(未选中)变体中显示的图标。',
+ },
+ {
+ name: 'selectedIcon',
+ type: 'XDSIconType',
+ description: '选中时显示的图标(填充变体)。',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: '将此项标记为当前页面。',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '禁用状态。',
+ default: 'false',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: '导航 URL。',
+ },
+ {
+ name: 'onClick',
+ type: '(e: MouseEvent) => void',
+ description: '点击处理函数。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '右侧内容,如徽章或计数。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '用于嵌套的子项。',
+ },
+ {
+ name: 'collapsible',
+ type: 'boolean | { defaultIsCollapsed?: boolean, isCollapsed?: boolean, onCollapsedChange?: (isCollapsed: boolean) => void }',
+ description: '启用带子项的折叠行为。传 true 为非受控模式(默认展开),或传对象用于受控模式。',
+ default: 'false',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'SideNavItem',
+ isHiddenFromOverview: true,
+ displayName: 'Side Nav Item',
+ description: 'Navigation item w/ icon, selected state, optional end content, nesting via children.',
+ propDescriptions: {
+ label: 'Item label.',
+ as: 'Custom link component.',
+ icon: 'Icon displayed in outline (unselected) variant.',
+ selectedIcon: 'Icon displayed when item selected (filled variant).',
+ isSelected: 'Marks this item as current page.',
+ isDisabled: 'Disabled state.',
+ href: 'Navigation URL.',
+ onClick: 'Click handler.',
+ endContent: 'Right-side content such as badges or counts.',
+ children: 'Sub-items for nesting.',
+ collapsible: 'Enables collapse for items w/ children. true=uncontrolled, object=controlled mode.',
+ },
+};
diff --git a/packages/core/src/SideNav/SideNavSection.doc.mjs b/packages/core/src/SideNav/SideNavSection.doc.mjs
new file mode 100644
index 0000000000..d9100590f2
--- /dev/null
+++ b/packages/core/src/SideNav/SideNavSection.doc.mjs
@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SideNavSection',
+ subComponentOf: 'SideNav',
+ displayName: 'Side Nav Section',
+ isHiddenFromOverview: true,
+ description: 'Section grouping with an optional title, subtitle, and end content.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Section title.',
+ required: true,
+ },
+ {
+ name: 'subtitle',
+ type: 'string',
+ description: 'Section subtitle.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Section items.',
+ slotElements: [
+ {
+ __element: 'XDSSideNavItem',
+ props: {
+ label: 'Item',
+ },
+ },
+ ],
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Right-side content in the section header.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
+ },
+ {
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
+ },
+ ],
+ },
+ {
+ name: 'isHeaderHidden',
+ type: 'boolean',
+ description: 'Visually hides the section header while keeping it accessible to screen readers.',
+ default: 'false',
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'SideNavSection',
+ isHiddenFromOverview: true,
+ displayName: 'Side Nav Section',
+ description: '分组,支持可选的标题、副标题和尾部内容。',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: '分组标题。',
+ required: true,
+ },
+ {
+ name: 'subtitle',
+ type: 'string',
+ description: '分组副标题。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '分组项目。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '分组头部的右侧内容。',
+ },
+ {
+ name: 'isHeaderHidden',
+ type: 'boolean',
+ description: '视觉上隐藏分组头部,同时保持屏幕阅读器可访问。',
+ default: 'false',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'SideNavSection',
+ isHiddenFromOverview: true,
+ displayName: 'Side Nav Section',
+ description: 'Section grouping w/ optional title, subtitle, end content.',
+ propDescriptions: {
+ title: 'Section title.',
+ subtitle: 'Section subtitle.',
+ children: 'Section items.',
+ endContent: 'Right-side content in section header.',
+ isHeaderHidden: 'Visually hides section header while keeping accessible to screen readers.',
+ xstyle: 'StyleX styles for layout customization.',
+ },
+};
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index ee61421426..23c800001d 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -18,7 +18,7 @@ export const docs = {
{
name: 'XDSHStack',
isHiddenFromOverview: true,
- displayName: 'XDSH Stack',
+ displayName: 'H Stack',
description:
'Horizontal stack for arranging items left-to-right. Supports polymorphic rendering.',
props: [
@@ -86,7 +86,7 @@ export const docs = {
{
name: 'XDSVStack',
isHiddenFromOverview: true,
- displayName: 'XDSV Stack',
+ displayName: 'V Stack',
description:
'Vertical stack for arranging items top-to-bottom. Supports polymorphic rendering.',
props: [
@@ -206,7 +206,7 @@ export const docsZh = {
{
name: 'XDSHStack',
isHiddenFromOverview: true,
- displayName: 'XDSH Stack',
+ displayName: 'H Stack',
description:
'水平堆叠组件,将元素从左到右排列。支持多态渲染。',
props: [
@@ -275,7 +275,7 @@ export const docsZh = {
{
name: 'XDSVStack',
isHiddenFromOverview: true,
- displayName: 'XDSV Stack',
+ displayName: 'V Stack',
description:
'垂直堆叠组件,将元素从上到下排列。支持多态渲染。',
props: [
@@ -396,7 +396,7 @@ export const docsDense = {
{
name: 'XDSHStack',
isHiddenFromOverview: true,
- displayName: 'XDSH Stack',
+ displayName: 'H Stack',
description: 'Horizontal stack; left-to-right, polymorphic rendering.',
propDescriptions: {
gap: 'Numeric spacing step for gap: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',
@@ -415,7 +415,7 @@ export const docsDense = {
{
name: 'XDSVStack',
isHiddenFromOverview: true,
- displayName: 'XDSV Stack',
+ displayName: 'V Stack',
description: 'Vertical stack; top-to-bottom, polymorphic rendering.',
propDescriptions: {
gap: 'Numeric spacing step for gap: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',
diff --git a/packages/core/src/TabList/Tab.doc.mjs b/packages/core/src/TabList/Tab.doc.mjs
new file mode 100644
index 0000000000..1aa7e166ba
--- /dev/null
+++ b/packages/core/src/TabList/Tab.doc.mjs
@@ -0,0 +1,156 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Tab',
+ subComponentOf: 'TabList',
+ displayName: 'Tab',
+ isHiddenFromOverview: true,
+ description: 'Individual tab item that renders as a button or an anchor link, with selected-state styling and optional icons.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Unique value for this tab, matched against XDSTabListContext.value.',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Visible label text for this tab.',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'URL to navigate to; when provided, the tab renders as an anchor element.',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: 'Custom component to render instead of <a> for link tabs. Overrides the XDSLinkProvider default. Only applies when href is provided.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon element shown when the tab is not selected.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'selectedIcon',
+ type: 'ReactNode',
+ description: 'Icon element shown when the tab is selected; falls back to icon if not provided.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'checkCircle',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'Content rendered after the label, such as a badge count or status dot.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
+ },
+ {
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
+ },
+ ],
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'Tab',
+ isHiddenFromOverview: true,
+ displayName: 'Tab',
+ description: '单个标签项,渲染为按钮或锚点链接,具有选中状态样式和可选图标。',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description: '此标签的唯一值,与 XDSTabListContext.value 进行匹配。',
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '此标签的可见标签文本。',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: '要导航到的 URL;提供时,标签渲染为锚点元素。',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: '用于替代 <a> 渲染链接标签的自定义组件。覆盖 XDSLinkProvider 的默认值。仅在提供 href 时生效。',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: '标签未选中时显示的图标元素。',
+ },
+ {
+ name: 'selectedIcon',
+ type: 'ReactNode',
+ description: '标签选中时显示的图标元素;未提供时回退到 icon。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '在标签文本之后渲染的内容,例如徽章计数或状态点。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'Tab',
+ isHiddenFromOverview: true,
+ displayName: 'Tab',
+ description: 'Individual tab; renders as button or anchor w/ selected-state styling + optional icons.',
+ propDescriptions: {
+ value: 'Unique value matched against XDSTabListContext.value.',
+ label: 'Visible label text.',
+ href: 'URL; renders as <a> when provided.',
+ as: 'Custom link component overriding XDSLinkProvider; only w/ href.',
+ icon: 'Icon shown when not selected.',
+ selectedIcon: 'Icon shown when selected; falls back to icon.',
+ endContent: 'Content after the label (badge, status dot, etc.).',
+ xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
+ },
+};
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index 27b8912fd0..63d9067111 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -23,137 +23,56 @@ export const docs = {
{className: 'xds-tab-menu-item'},
],
},
- components: [
+ description: 'Nav wrapper that provides XDSTabListContext (value, onChange, size) to XDSTab and XDSTabMenu children.',
+ props: [
{
- name: 'XDSTabList',
- displayName: 'Tab List',
- description:
- 'Nav wrapper that provides XDSTabListContext (value, onChange, size) to XDSTab and XDSTabMenu children.',
- props: [
- {
- name: 'value',
- type: 'string',
- description: 'The currently selected tab value.',
- required: true,
- },
- {
- name: 'onChange',
- type: '(value: string) => void',
- description: 'Callback fired when a tab is selected.',
- required: true,
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: 'Size variant applied to all child tabs.',
- default: "'md'",
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description:
- 'Whether to show a bottom border divider under the tab list.',
- default: 'false',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'XDSTab and XDSTabMenu items to render inside the nav.',
- slotElements: [{__element: 'XDSTab', props: {label: 'Tab', value: 'tab'}}],
- required: true,
- },
- {
- 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={{}}.',
- },
- ], },
+ name: 'value',
+ type: 'string',
+ description: 'The currently selected tab value.',
+ required: true,
+ },
{
- name: 'XDSTab',
- isHiddenFromOverview: true,
- displayName: 'Tab',
- description:
- 'Individual tab item that renders as a button or an anchor link, with selected-state styling and optional icons.',
- props: [
- {
- name: 'value',
- type: 'string',
- description:
- 'Unique value for this tab, matched against XDSTabListContext.value.',
- required: true,
- },
- {
- name: 'label',
- type: 'string',
- description: 'Visible label text for this tab.',
- required: true,
- },
- {
- name: 'href',
- type: 'string',
- description:
- 'URL to navigate to; when provided, the tab renders as an anchor element.',
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- 'Custom component to render instead of <a> for link tabs. Overrides the XDSLinkProvider default. Only applies when href is provided.',
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: 'Icon element shown when the tab is not selected.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'selectedIcon',
- type: 'ReactNode',
- description:
- 'Icon element shown when the tab is selected; falls back to icon if not provided.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'checkCircle', size: 'sm'}}],
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- 'Content rendered after the label, such as a badge count or status dot.',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
- },
- {
- 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={{}}.',
- },
- ],
+ name: 'onChange',
+ type: '(value: string) => void',
+ description: 'Callback fired when a tab is selected.',
+ required: true,
},
{
- name: 'XDSTabMenu',
- isHiddenFromOverview: true,
- displayName: 'Tab Menu',
- description:
- "Overflow menu trigger that opens a dropdown of additional tab options, showing the selected option's label as the trigger text.",
- props: [
- {
- name: 'label',
- type: 'string',
- description:
- 'Label for the trigger button (shown when no option is selected) and the dropdown heading divider.',
- required: true,
- },
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant applied to all child tabs.',
+ default: "'md'",
+ },
+ {
+ name: 'hasDivider',
+ type: 'boolean',
+ description: 'Whether to show a bottom border divider under the tab list.',
+ default: 'false',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSTab and XDSTabMenu items to render inside the nav.',
+ slotElements: [
{
- name: 'options',
- type: 'XDSTabMenuOption[]',
- description: 'Array of menu options rendered in the dropdown.',
- required: true,
+ __element: 'XDSTab',
+ props: {
+ label: 'Tab',
+ value: 'tab',
+ },
},
],
+ required: true,
},
+ {
+ 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={{}}.',
+ },
+ ],
+ components: [
+ {name: 'XDSTab'},
+ {name: 'XDSTabMenu'},
],
usage: {
description:
@@ -174,147 +93,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'TabList',
- displayName: 'Tab List',
- group: 'Tabs',
- theming: {
- targets: [
- {className: 'xds-tab-list', visualProps: ['size']},
- {className: 'xds-tab', states: ['selected']},
- {className: 'xds-tab-indicator', states: ['selected']},
- {className: 'xds-tab-menu'},
- {className: 'xds-tab-menu-dropdown'},
- {className: 'xds-tab-menu-item'},
- ],
- },
- components: [
- {
- name: 'XDSTabList',
- displayName: 'Tab List',
- description:
- '导航容器,为 XDSTab 和 XDSTabMenu 子组件提供 XDSTabListContext(value、onChange、size)。',
- props: [
- {
- name: 'value',
- type: 'string',
- description: '当前选中的标签值。',
- required: true,
- },
- {
- name: 'onChange',
- type: '(value: string) => void',
- description: '选中标签时触发的回调函数。',
- required: true,
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: '应用于所有子标签的尺寸变体。',
- default: "'md'",
- },
- {
- name: 'hasDivider',
- type: 'boolean',
- description:
- '是否在标签列表下方显示底部边框分隔线。',
- default: 'false',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '在 nav 内渲染的 XDSTab 和 XDSTabMenu 项。',
- required: true,
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSTab',
- isHiddenFromOverview: true,
- displayName: 'Tab',
- description:
- '单个标签项,渲染为按钮或锚点链接,具有选中状态样式和可选图标。',
- props: [
- {
- name: 'value',
- type: 'string',
- description:
- '此标签的唯一值,与 XDSTabListContext.value 进行匹配。',
- required: true,
- },
- {
- name: 'label',
- type: 'string',
- description: '此标签的可见标签文本。',
- required: true,
- },
- {
- name: 'href',
- type: 'string',
- description:
- '要导航到的 URL;提供时,标签渲染为锚点元素。',
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- '用于替代 <a> 渲染链接标签的自定义组件。覆盖 XDSLinkProvider 的默认值。仅在提供 href 时生效。',
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: '标签未选中时显示的图标元素。',
- },
- {
- name: 'selectedIcon',
- type: 'ReactNode',
- description:
- '标签选中时显示的图标元素;未提供时回退到 icon。',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- '在标签文本之后渲染的内容,例如徽章计数或状态点。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSTabMenu',
- isHiddenFromOverview: true,
- displayName: 'Tab Menu',
- description:
- '溢出菜单触发器,打开包含额外标签选项的下拉菜单,将选中选项的标签显示为触发器文本。',
- props: [
- {
- name: 'label',
- type: 'string',
- description:
- '触发器按钮的标签(无选项选中时显示)以及下拉菜单标题分隔线的文本。',
- required: true,
- },
- {
- name: 'options',
- type: 'XDSTabMenuOption[]',
- description: '在下拉菜单中渲染的菜单选项数组。',
- required: true,
- },
- ],
- },
- ],
usage: {
description:
'TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in "more" menu.',
@@ -354,45 +134,4 @@ export const docsDense = {
{name: 'Right Content', required: false, description: 'Hugs content width.'},
],
},
- components: [
- {
- name: 'XDSTabList',
- displayName: 'Tab List',
- description: 'Nav wrapper providing XDSTabListContext (value, onChange, size) to children.',
- propDescriptions: {
- value: 'Currently selected tab value.',
- onChange: 'Fired when tab is selected.',
- size: 'Size variant applied to all child tabs.',
- hasDivider: 'Show bottom border divider under tab list.',
- children: 'XDSTab + XDSTabMenu items inside nav.',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
- },
- },
- {
- name: 'XDSTab',
- isHiddenFromOverview: true,
- displayName: 'Tab',
- description: 'Individual tab; renders as button or anchor w/ selected-state styling + optional icons.',
- propDescriptions: {
- value: 'Unique value matched against XDSTabListContext.value.',
- label: 'Visible label text.',
- href: 'URL; renders as <a> when provided.',
- as: 'Custom link component overriding XDSLinkProvider; only w/ href.',
- icon: 'Icon shown when not selected.',
- selectedIcon: 'Icon shown when selected; falls back to icon.',
- endContent: 'Content after the label (badge, status dot, etc.).',
- xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
- },
- },
- {
- name: 'XDSTabMenu',
- isHiddenFromOverview: true,
- displayName: 'Tab Menu',
- description: "Overflow menu trigger; dropdown of extra tab options, shows selected option's label as trigger text.",
- propDescriptions: {
- label: 'Trigger text (when no option selected) + dropdown heading.',
- options: 'Menu options array rendered in dropdown.',
- },
- },
- ],
};
\ No newline at end of file
diff --git a/packages/core/src/TabList/TabMenu.doc.mjs b/packages/core/src/TabList/TabMenu.doc.mjs
new file mode 100644
index 0000000000..da04777549
--- /dev/null
+++ b/packages/core/src/TabList/TabMenu.doc.mjs
@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TabMenu',
+ subComponentOf: 'TabList',
+ displayName: 'Tab Menu',
+ isHiddenFromOverview: true,
+ description: "Overflow menu trigger that opens a dropdown of additional tab options, showing the selected option's label as the trigger text.",
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label for the trigger button (shown when no option is selected) and the dropdown heading divider.',
+ required: true,
+ },
+ {
+ name: 'options',
+ type: 'XDSTabMenuOption[]',
+ description: 'Array of menu options rendered in the dropdown.',
+ required: true,
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TabMenu',
+ isHiddenFromOverview: true,
+ displayName: 'Tab Menu',
+ description: '溢出菜单触发器,打开包含额外标签选项的下拉菜单,将选中选项的标签显示为触发器文本。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '触发器按钮的标签(无选项选中时显示)以及下拉菜单标题分隔线的文本。',
+ required: true,
+ },
+ {
+ name: 'options',
+ type: 'XDSTabMenuOption[]',
+ description: '在下拉菜单中渲染的菜单选项数组。',
+ required: true,
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TabMenu',
+ isHiddenFromOverview: true,
+ displayName: 'Tab Menu',
+ description: "Overflow menu trigger; dropdown of extra tab options, shows selected option's label as trigger text.",
+ propDescriptions: {
+ label: 'Trigger text (when no option selected) + dropdown heading.',
+ options: 'Menu options array rendered in dropdown.',
+ },
+};
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 3562478d1a..8b3b07591f 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -30,238 +30,75 @@ export const docs = {
{className: 'xds-table-header-cell'},
],
},
- components: [
- {
- name: 'XDSTable',
- displayName: 'Table',
- description:
- 'Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support. T must extend Record<string, unknown>.',
- props: [
- {
- name: 'data',
- type: 'T[]',
- description: 'Array of data items to render as rows. T must extend Record<string, unknown> (use `interface MyRow extends Record<string, unknown>` for custom types).',
- },
- {
- name: 'columns',
- type: 'XDSTableColumn<T>[]',
- description:
- 'Column definitions: each column has {key, header, width?, align?, renderCell?}. The `header` field sets the column heading text. If omitted, columns are auto-generated from data object keys.',
- },
- {
- name: 'idKey',
- type: '(keyof T & string) | ((item: T) => string | number)',
- description:
- 'Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.',
- },
- {
- name: 'density',
- type: "'compact' | 'balanced' | 'spacious'",
- description: 'Row density controlling cell padding and font size.',
- default: "'balanced'",
- },
- {
- name: 'dividers',
- type: "'rows' | 'columns' | 'grid' | 'none'",
- description: 'Divider style rendered between cells.',
- default: "'rows'",
- },
- {
- name: 'isStriped',
- type: 'boolean',
- description: 'Applies a background wash to even-numbered rows.',
- default: 'false',
- },
- {
- name: 'hasHover',
- type: 'boolean',
- description:
- 'Applies a hover highlight background to rows on pointer devices.',
- default: 'false',
- },
- {
- name: 'plugins',
- type: 'Record<string, TablePlugin<T>>',
- description:
- 'Named plugins that extend table behavior via the transform pipeline. Converted to an ordered array internally.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Children mode: render XDSTableRow/XDSTableCell directly instead of using data-driven rendering.',
- },
- {
- 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={{}}.',
- },
- ], },
+ description: 'Styled, data-driven table with density, dividers, hover highlight, striped rows, and named plugin support. T must extend Record<string, unknown>.',
+ props: [
{
- name: 'XDSTableRow',
- isHiddenFromOverview: true,
- displayName: 'Table Row',
- description:
- '<tr> wrapper that reads XDSTableContext to apply striped, hover, and divider styles when used inside XDSTable.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Row cell elements.',
- required: true,
- },
- ],
+ name: 'data',
+ type: 'T[]',
+ description: 'Array of data items to render as rows. T must extend Record<string, unknown> (use `interface MyRow extends Record<string, unknown>` for custom types).',
},
{
- name: 'XDSTableCell',
- isHiddenFromOverview: true,
- displayName: 'Table Cell',
- description:
- '<td> wrapper that reads XDSTableContext to apply density padding, font size, and divider borders when used inside XDSTable.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Cell content.',
- },
- ],
+ name: 'columns',
+ type: 'XDSTableColumn<T>[]',
+ description: 'Column definitions — each column has {key, header, width?, align?, renderCell?}. The `header` field sets the column heading text. If omitted, columns are auto-generated from data object keys.',
},
{
- name: 'XDSTableHeaderCell',
- isHiddenFromOverview: true,
- displayName: 'Table Header Cell',
- description:
- '<th> wrapper that reads XDSTableContext to apply density padding, semibold weight, secondary text color, and divider borders when used inside XDSTable.',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Header cell content.',
- },
- ],
+ name: 'idKey',
+ type: '(keyof T & string) | ((item: T) => string | number)',
+ description: 'Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted.',
},
{
- name: 'useXDSTableSelection',
- 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.',
- 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.'},
- ],
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: 'Row density controlling cell padding and font size.',
+ default: "'balanced'",
},
{
- name: 'useXDSTableSelectionState',
- 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.',
- 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.'},
- ],
+ name: 'dividers',
+ type: "'rows' | 'columns' | 'grid' | 'none'",
+ description: 'Divider style rendered between cells.',
+ default: "'rows'",
},
{
- name: 'useXDSTableSortable',
- 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.',
- 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.'},
- ],
+ name: 'isStriped',
+ type: 'boolean',
+ description: 'Applies a background wash to even-numbered rows.',
+ default: 'false',
},
{
- name: 'useXDSTablePagination',
- 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.',
- 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: 'hasHover',
+ type: 'boolean',
+ description: 'Applies a hover highlight background to rows on pointer devices.',
+ default: 'false',
},
{
- name: 'useXDSTableColumnSettings',
- displayName: 'useXDSTableColumnSettings',
- description:
- '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.'},
- ],
+ name: 'plugins',
+ type: 'Record<string, TablePlugin<T>>',
+ description: 'Named plugins that extend table behavior via the transform pipeline. Converted to an ordered array internally.',
},
{
- name: 'useXDSTableFiltering',
- 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, 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.'},
- ],
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Children mode — render XDSTableRow/XDSTableCell directly instead of using data-driven rendering.',
},
{
- name: 'useXDSTableFilterState',
- isHiddenFromOverview: true,
- displayName: 'useXDSTableFilterState',
- description:
- '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.'},
- ],
+ 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={{}}.',
},
],
+ components: [
+ {name: 'XDSTableRow'},
+ {name: 'XDSTableCell'},
+ {name: 'XDSTableHeaderCell'},
+ {name: 'useXDSTableSelection'},
+ {name: 'useXDSTableSelectionState'},
+ {name: 'useXDSTableSortable'},
+ {name: 'useXDSTablePagination'},
+ {name: 'useXDSTableColumnSettings'},
+ {name: 'useXDSTableFiltering'},
+ {name: 'useXDSTableFilterState'},
+ ],
usage: {
description:
'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
@@ -284,335 +121,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Table',
- displayName: 'Table',
- group: 'Table',
- theming: {
- targets: [
- {className: 'xds-base-table'},
- {className: 'xds-table-row'},
- {className: 'xds-table-cell'},
- {className: 'xds-table-header-cell'},
- ],
- },
- components: [
- {
- name: 'XDSTable',
- displayName: 'Table',
- description:
- '带样式的数据驱动表格,支持密度、分隔线、悬停高亮、条纹行和命名插件。T 需 extends Record<string, unknown>。',
- props: [
- {
- name: 'data',
- type: 'T[]',
- description: '要渲染为行的数据项数组。T 需 extends Record<string, unknown>。',
- },
- {
- name: 'columns',
- type: 'XDSTableColumn<T>[]',
- description:
- '列定义:每列含 {key, header, width?, align?, renderCell?}。header 设置列标题文本。省略时自动从数据键生成。',
- },
- {
- name: 'idKey',
- type: '(keyof T & string) | ((item: T) => string | number)',
- description:
- '用于 React 协调的行键。传入属性名称字符串或函数。省略时回退到行索引。',
- },
- {
- name: 'density',
- type: "'compact' | 'balanced' | 'spacious'",
- description: '行密度,控制单元格内边距和字体大小。',
- default: "'balanced'",
- },
- {
- name: 'dividers',
- type: "'rows' | 'columns' | 'grid' | 'none'",
- description: '单元格之间渲染的分隔线样式。',
- default: "'rows'",
- },
- {
- name: 'isStriped',
- type: 'boolean',
- description: '为偶数行应用背景底色。',
- default: 'false',
- },
- {
- name: 'hasHover',
- type: 'boolean',
- description:
- '在指针设备上为行应用悬停高亮背景。',
- default: 'false',
- },
- {
- name: 'plugins',
- type: 'Record<string, TablePlugin<T>>',
- description:
- '通过转换管道扩展表格行为的命名插件。在内部转换为有序数组。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- '子元素模式:直接渲染 XDSTableRow/XDSTableCell,而非使用数据驱动渲染。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSTableRow',
- isHiddenFromOverview: true,
- displayName: 'Table Row',
- description:
- '<tr> 包装器,读取 XDSTableContext 以在 XDSTable 内部使用时应用条纹、悬停和分隔线样式。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '行单元格元素。',
- required: true,
- },
- ],
- },
- {
- name: 'XDSTableCell',
- isHiddenFromOverview: true,
- displayName: 'Table Cell',
- description:
- '<td> 包装器,读取 XDSTableContext 以在 XDSTable 内部使用时应用密度内边距、字体大小和分隔线边框。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '单元格内容。',
- },
- ],
- },
- {
- name: 'XDSTableHeaderCell',
- isHiddenFromOverview: true,
- displayName: 'Table Header Cell',
- description:
- '<th> 包装器,读取 XDSTableContext 以在 XDSTable 内部使用时应用密度内边距、半粗字重、次要文本颜色和分隔线边框。',
- props: [
- {
- name: 'children',
- type: 'ReactNode',
- description: '表头单元格内容。',
- },
- ],
- },
- {
- name: 'useXDSTableSelection',
- displayName: 'useXDSTableSelection',
- description:
- '返回 TablePlugin 的 Hook,实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
- props: [
- {
- name: 'getIsItemSelected',
- type: '(item: T) => boolean',
- description: '返回给定项是否当前被选中。',
- required: true,
- },
- {
- name: 'onSelectItem',
- type: '(event: {item: T; isSelected: boolean}) => void',
- description:
- '当行复选框被切换时调用。isSelected 为新的期望状态。',
- required: true,
- },
- {
- name: 'onSelectAll',
- type: '(event: {isAllSelected: boolean}) => void',
- description: '当全选表头复选框被切换时调用。',
- required: true,
- },
- {
- name: 'getIsAllSelected',
- type: '() => boolean',
- description:
- '返回所有可选择项是否当前都被选中。',
- required: true,
- },
- {
- name: 'getIsIndeterminate',
- type: '() => boolean',
- description:
- '返回选择是否为部分选中(部分但非全部)。将全选复选框渲染为不确定状态。',
- },
- {
- name: 'getIsItemSelectable',
- type: '(item: T) => boolean',
- description:
- '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
- default: '() => true',
- },
- {
- name: 'getIsItemEnabled',
- type: '(item: T) => boolean',
- description:
- '返回行复选框是否可交互。禁用的行显示禁用状态的复选框。',
- default: '() => true',
- },
- ],
- },
- {
- name: 'useXDSTableSortable',
- displayName: 'useXDSTableSortable',
- description:
- '无头多列排序插件。用户拥有排序状态并提供回调。Shift+点击启用二级排序列。排序指示器自动渲染在表头单元格中。',
- props: [
- {
- name: 'sort',
- type: 'XDSTableSortState<TSortKey>',
- description:
- '当前排序状态。{sortKey, direction} 条目的有序数组。第一个条目是主排序。',
- required: true,
- },
- {
- name: 'onSortChange',
- type: '(sort: XDSTableSortState<TSortKey>) => void',
- description:
- '用户点击表头单元格更改排序时调用。',
- required: true,
- },
- {
- name: 'allowUnsortedState',
- type: 'boolean',
- description:
- '允许循环回到未排序状态。为 true 时:升序、降序、未排序。为 false 时:升序、降序、升序。',
- default: 'false',
- },
- {
- name: 'isMultiSortEnabled',
- type: 'boolean',
- description:
- '通过 Shift+点击启用多列排序。普通点击仍替换整个排序状态。',
- default: 'false',
- },
- ],
- },
- {
- name: 'useXDSTablePagination',
- displayName: 'useXDSTablePagination',
- description:
- '无头分页插件。支持客户端切片、服务器端分页和游标分页。自动渲染 XDSPagination 控件。',
- props: [
- {
- name: 'page',
- type: 'number',
- description: '当前页码(从 1 开始)。',
- required: true,
- },
- {
- name: 'onPageChange',
- type: '(page: number) => void',
- description: '页面更改时调用。',
- required: true,
- },
- {
- name: 'totalItems',
- type: 'number',
- description:
- '所有页面的总项目数。用于计算总页数。',
- },
- {
- name: 'pageSize',
- type: 'number',
- description: '每页项目数。',
- default: '10',
- },
- {
- name: 'variant',
- type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
- description: '分页控件的视觉变体。',
- default: "'pages'",
- },
- {
- name: 'position',
- type: "'below' | 'above' | 'both' | 'none'",
- description: '分页控件相对于表格的渲染位置。',
- default: "'below'",
- },
- ],
- },
- {
- name: 'useXDSTableColumnSettings',
- displayName: 'useXDSTableColumnSettings',
- description:
- '无头列可见性和排序管理。提供筛选后的列、切换帮助方法和 XDSMultiSelector 选项。',
- props: [
- {
- name: 'columns',
- type: 'XDSColumnSettingsOption[]',
- description:
- '所有可用列及其设置 UI 的元数据。每个条目包含 key、label、可选的 isAlwaysVisible 和 group。',
- required: true,
- },
- {
- name: 'activeColumnKeys',
- type: 'string[]',
- description:
- '当前活动的列键,按显示顺序排列。',
- required: true,
- },
- {
- name: 'onChangeActiveColumnKeys',
- type: '(keys: string[]) => void',
- description: '活动列更改时调用。',
- required: true,
- },
- ],
- },
- {
- name: 'useXDSTableFiltering',
- isHiddenFromOverview: true,
- displayName: 'useXDSTableFiltering',
- description:
- '表格筛选插件,添加内联列过滤器(弹出式或内联控件)。与 useXDSTableFilterState 配合使用管理状态。',
- props: [
- {
- name: 'filters',
- type: 'XDSTableFilterState',
- description: '当前筛选状态:列键到筛选值的映射。',
- required: true,
- },
- {
- name: 'onFilterChange',
- type: '(columnKey: string, value: XDSTableFilterValue | null) => void',
- description: '用户更改筛选值时调用。null 清除筛选。',
- required: true,
- },
- {
- name: 'variant',
- type: "'popover' | 'inline'",
- description: '筛选控件的显示变体。',
- default: "'popover'",
- },
- ],
- },
- {
- name: 'useXDSTableFilterState',
- isHiddenFromOverview: true,
- displayName: 'useXDSTableFilterState',
- description:
- '表格筛选的受管状态 hook。返回当前筛选映射和 onChange 处理程序。将结果直接传递给 useXDSTableFiltering。',
- props: [
- {
- name: 'initialState',
- type: 'XDSTableFilterState',
- description: '可选的初始筛选状态映射。',
- },
- ],
- },
- ],
usage: {
description:
'Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.',
@@ -656,132 +166,4 @@ export const docsDense = {
{name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
],
},
- components: [
- {
- name: 'XDSTable',
- displayName: 'Table',
- description: 'Styled data-driven table w/ density, dividers, hover, striped rows, named plugin support.',
- propDescriptions: {
- data: 'Array of data items to render as rows. T must extend Record<string, unknown>.',
- columns: 'Column defs {key, header, width?, align?, renderCell?}; auto-generated from data keys if omitted.',
- idKey: 'Row key for React reconciliation; property name or fn. Falls back to index.',
- density: 'Row density controlling cell padding + font size.',
- dividers: 'Divider style between cells.',
- isStriped: 'Background wash on even rows.',
- hasHover: 'Hover highlight on pointer devices.',
- plugins: 'Named plugins extending behavior via transform pipeline; converted to ordered array.',
- children: 'Children mode; render XDSTableRow/XDSTableCell directly.',
- xstyle: 'StyleX layout styles; must be stylex.create() value.',
- },
- },
- {
- name: 'XDSTableRow',
- isHiddenFromOverview: true,
- displayName: 'Table Row',
- description: '<tr> wrapper; reads XDSTableContext for striped/hover/divider styles.',
- propDescriptions: {
- children: 'Row cell elements.',
- },
- },
- {
- name: 'XDSTableCell',
- isHiddenFromOverview: true,
- displayName: 'Table Cell',
- description: '<td> wrapper; reads XDSTableContext for density padding, font size, divider borders.',
- propDescriptions: {
- children: 'Cell content.',
- },
- },
- {
- name: 'XDSTableHeaderCell',
- isHiddenFromOverview: true,
- displayName: 'Table Header Cell',
- description: '<th> wrapper; reads XDSTableContext for density padding, semibold weight, secondary color, dividers.',
- propDescriptions: {
- children: 'Header cell content.',
- },
- },
- {
- name: 'useXDSTableSelection',
- displayName: 'useXDSTableSelection',
- description: 'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
- propDescriptions: {
- getIsItemSelected: 'Returns whether item is selected.',
- onSelectItem: 'Called on row checkbox toggle; isSelected = new desired state.',
- onSelectAll: 'Called on select-all header checkbox toggle.',
- getIsAllSelected: 'Returns whether all selectable items are selected.',
- getIsIndeterminate: 'Returns partial selection state; renders indeterminate checkbox.',
- getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows render nothing.',
- getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
- },
- },
- {
- name: 'useXDSTableSelectionState',
- displayName: 'useXDSTableSelectionState',
- description: 'State companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically: disabled rows frozen (state preserved across select-all/deselect-all), non-selectable rows excluded.',
- propDescriptions: {
- data: 'Full data array rendered in table. **(required)**',
- idKey: 'Key extractor: property name or fn returning unique string ID. **(required)**',
- selectedKeys: 'Controlled set of selected item IDs. **(required)**',
- setSelectedKeys: 'Setter for controlled selected keys. **(required)**',
- getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows excluded from select-all. Defaults to () => true.',
- getIsItemEnabled: 'Returns whether row checkbox is interactive. Disabled rows frozen; select-all preserves their state. Defaults to () => true.',
- },
- },
- {
- name: 'useXDSTableSortable',
- displayName: 'useXDSTableSortable',
- description: 'Headless multi-sort plugin. Consumer owns sort state + callback. Shift+click for secondary sort. Sort indicators auto-render in header cells.',
- propDescriptions: {
- sort: 'Current sort state; ordered array of {sortKey, direction} entries.',
- onSortChange: 'Called on header click to change sort.',
- allowUnsortedState: 'Allow cycling to unsorted. true: asc>desc>unsorted. false: asc>desc>asc.',
- isMultiSortEnabled: 'Enable multi-sort via Shift+click. Regular click replaces sort state.',
- },
- },
- {
- name: 'useXDSTablePagination',
- displayName: 'useXDSTablePagination',
- description: 'Headless pagination plugin. Client-side slicing, server-side, or cursor-based. Auto-renders XDSPagination above/below/both.',
- propDescriptions: {
- page: 'Current page (1-based).',
- onPageChange: 'Called on page change.',
- totalItems: 'Total items across all pages.',
- pageSize: 'Items per page. Default 10.',
- variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",
- position: "Render position: 'below'|'above'|'both'|'none'.",
- },
- },
- {
- name: 'useXDSTableColumnSettings',
- displayName: 'useXDSTableColumnSettings',
- description: 'Headless column visibility/ordering. Provides filtered columns, toggle helpers, XDSMultiSelector options.',
- propDescriptions: {
- columns: 'All available columns w/ metadata (key, label, isAlwaysVisible, group).',
- activeColumnKeys: 'Active column keys in display order.',
- onChangeActiveColumnKeys: 'Called on column toggle/reorder.',
- defaultColumnKeys: 'Default column set for reset. Omit = show all.',
- },
- },
- {
- name: 'useXDSTableFiltering',
- isHiddenFromOverview: true,
- displayName: 'useXDSTableFiltering',
- description: 'Table filtering plugin: inline column filters (popover/inline). Pairs w/ useXDSTableFilterState.',
- propDescriptions: {
- filters: 'Current filter state map (columnKey → value).',
- onFilterChange: 'Called on filter change. null clears.',
- variant: 'Filter control display variant.',
- },
- },
- {
- name: 'useXDSTableFilterState',
- isHiddenFromOverview: true,
- displayName: 'useXDSTableFilterState',
- description: 'Managed filter state hook. Returns filter map + onChange handler for useXDSTableFiltering.',
- propDescriptions: {
- initialState: 'Optional initial filter state map.',
- },
- },
- ],
};
\ No newline at end of file
diff --git a/packages/core/src/Table/TableCell.doc.mjs b/packages/core/src/Table/TableCell.doc.mjs
new file mode 100644
index 0000000000..a510e01224
--- /dev/null
+++ b/packages/core/src/Table/TableCell.doc.mjs
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TableCell',
+ subComponentOf: 'Table',
+ displayName: 'Table Cell',
+ isHiddenFromOverview: true,
+ description: '<td> wrapper that reads XDSTableContext to apply density padding, font size, and divider borders when used inside XDSTable.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Cell content.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TableCell',
+ isHiddenFromOverview: true,
+ displayName: 'Table Cell',
+ description: '<td> 包装器,读取 XDSTableContext 以在 XDSTable 内部使用时应用密度内边距、字体大小和分隔线边框。',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '单元格内容。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TableCell',
+ isHiddenFromOverview: true,
+ displayName: 'Table Cell',
+ description: '<td> wrapper; reads XDSTableContext for density padding, font size, divider borders.',
+ propDescriptions: {
+ children: 'Cell content.',
+ },
+};
diff --git a/packages/core/src/Table/TableHeaderCell.doc.mjs b/packages/core/src/Table/TableHeaderCell.doc.mjs
new file mode 100644
index 0000000000..fc3b3da496
--- /dev/null
+++ b/packages/core/src/Table/TableHeaderCell.doc.mjs
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TableHeaderCell',
+ subComponentOf: 'Table',
+ displayName: 'Table Header Cell',
+ isHiddenFromOverview: true,
+ description: '<th> wrapper that reads XDSTableContext to apply density padding, semibold weight, secondary text color, and divider borders when used inside XDSTable.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Header cell content.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TableHeaderCell',
+ isHiddenFromOverview: true,
+ displayName: 'Table Header Cell',
+ description: '<th> 包装器,读取 XDSTableContext 以在 XDSTable 内部使用时应用密度内边距、半粗字重、次要文本颜色和分隔线边框。',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '表头单元格内容。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TableHeaderCell',
+ isHiddenFromOverview: true,
+ displayName: 'Table Header Cell',
+ description: '<th> wrapper; reads XDSTableContext for density padding, semibold weight, secondary color, dividers.',
+ propDescriptions: {
+ children: 'Header cell content.',
+ },
+};
diff --git a/packages/core/src/Table/TableRow.doc.mjs b/packages/core/src/Table/TableRow.doc.mjs
new file mode 100644
index 0000000000..fe09c07bfb
--- /dev/null
+++ b/packages/core/src/Table/TableRow.doc.mjs
@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TableRow',
+ subComponentOf: 'Table',
+ displayName: 'Table Row',
+ isHiddenFromOverview: true,
+ description: '<tr> wrapper that reads XDSTableContext to apply striped, hover, and divider styles when used inside XDSTable.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Row cell elements.',
+ required: true,
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TableRow',
+ isHiddenFromOverview: true,
+ displayName: 'Table Row',
+ description: '<tr> 包装器,读取 XDSTableContext 以在 XDSTable 内部使用时应用条纹、悬停和分隔线样式。',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '行单元格元素。',
+ required: true,
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TableRow',
+ isHiddenFromOverview: true,
+ displayName: 'Table Row',
+ description: '<tr> wrapper; reads XDSTableContext for striped/hover/divider styles.',
+ propDescriptions: {
+ children: 'Row cell elements.',
+ },
+};
diff --git a/packages/core/src/Table/useXDSTableColumnSettings.doc.mjs b/packages/core/src/Table/useXDSTableColumnSettings.doc.mjs
new file mode 100644
index 0000000000..f2121e4b09
--- /dev/null
+++ b/packages/core/src/Table/useXDSTableColumnSettings.doc.mjs
@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSTableColumnSettings',
+ subComponentOf: 'Table',
+ 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.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'useXDSTableColumnSettings',
+ displayName: 'useXDSTableColumnSettings',
+ description: '无头列可见性和排序管理。提供筛选后的列、切换帮助方法和 XDSMultiSelector 选项。',
+ props: [
+ {
+ name: 'columns',
+ type: 'XDSColumnSettingsOption[]',
+ description: '所有可用列及其设置 UI 的元数据。每个条目包含 key、label、可选的 isAlwaysVisible 和 group。',
+ required: true,
+ },
+ {
+ name: 'activeColumnKeys',
+ type: 'string[]',
+ description: '当前活动的列键,按显示顺序排列。',
+ required: true,
+ },
+ {
+ name: 'onChangeActiveColumnKeys',
+ type: '(keys: string[]) => void',
+ description: '活动列更改时调用。',
+ required: true,
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSTableColumnSettings',
+ displayName: 'useXDSTableColumnSettings',
+ description: 'Headless column visibility/ordering. Provides filtered columns, toggle helpers, XDSMultiSelector options.',
+ propDescriptions: {
+ columns: 'All available columns w/ metadata (key, label, isAlwaysVisible, group).',
+ activeColumnKeys: 'Active column keys in display order.',
+ onChangeActiveColumnKeys: 'Called on column toggle/reorder.',
+ defaultColumnKeys: 'Default column set for reset. Omit = show all.',
+ },
+};
diff --git a/packages/core/src/Table/useXDSTableFilterState.doc.mjs b/packages/core/src/Table/useXDSTableFilterState.doc.mjs
new file mode 100644
index 0000000000..6b1c24742d
--- /dev/null
+++ b/packages/core/src/Table/useXDSTableFilterState.doc.mjs
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSTableFilterState',
+ subComponentOf: 'Table',
+ displayName: 'useXDSTableFilterState',
+ isHiddenFromOverview: true,
+ 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.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'useXDSTableFilterState',
+ isHiddenFromOverview: true,
+ displayName: 'useXDSTableFilterState',
+ description: '表格筛选的受管状态 hook。返回当前筛选映射和 onChange 处理程序。将结果直接传递给 useXDSTableFiltering。',
+ props: [
+ {
+ name: 'initialState',
+ type: 'XDSTableFilterState',
+ description: '可选的初始筛选状态映射。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSTableFilterState',
+ isHiddenFromOverview: true,
+ displayName: 'useXDSTableFilterState',
+ description: 'Managed filter state hook. Returns filter map + onChange handler for useXDSTableFiltering.',
+ propDescriptions: {
+ initialState: 'Optional initial filter state map.',
+ },
+};
diff --git a/packages/core/src/Table/useXDSTableFiltering.doc.mjs b/packages/core/src/Table/useXDSTableFiltering.doc.mjs
new file mode 100644
index 0000000000..b5d859a760
--- /dev/null
+++ b/packages/core/src/Table/useXDSTableFiltering.doc.mjs
@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSTableFiltering',
+ subComponentOf: 'Table',
+ displayName: 'useXDSTableFiltering',
+ isHiddenFromOverview: true,
+ 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'",
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'useXDSTableFiltering',
+ isHiddenFromOverview: true,
+ displayName: 'useXDSTableFiltering',
+ description: '表格筛选插件,添加内联列过滤器(弹出式或内联控件)。与 useXDSTableFilterState 配合使用管理状态。',
+ props: [
+ {
+ name: 'filters',
+ type: 'XDSTableFilterState',
+ description: '当前筛选状态——列键到筛选值的映射。',
+ required: true,
+ },
+ {
+ name: 'onFilterChange',
+ type: '(columnKey: string, value: XDSTableFilterValue | null) => void',
+ description: '用户更改筛选值时调用。null 清除筛选。',
+ required: true,
+ },
+ {
+ name: 'variant',
+ type: "'popover' | 'inline'",
+ description: '筛选控件的显示变体。',
+ default: "'popover'",
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSTableFiltering',
+ isHiddenFromOverview: true,
+ displayName: 'useXDSTableFiltering',
+ description: 'Table filtering plugin — inline column filters (popover/inline). Pairs w/ useXDSTableFilterState.',
+ propDescriptions: {
+ filters: 'Current filter state map (columnKey → value).',
+ onFilterChange: 'Called on filter change. null clears.',
+ variant: 'Filter control display variant.',
+ },
+};
diff --git a/packages/core/src/Table/useXDSTablePagination.doc.mjs b/packages/core/src/Table/useXDSTablePagination.doc.mjs
new file mode 100644
index 0000000000..5bdf7d8cf4
--- /dev/null
+++ b/packages/core/src/Table/useXDSTablePagination.doc.mjs
@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSTablePagination',
+ subComponentOf: 'Table',
+ 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'",
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'useXDSTablePagination',
+ displayName: 'useXDSTablePagination',
+ description: '无头分页插件。支持客户端切片、服务器端分页和游标分页。自动渲染 XDSPagination 控件。',
+ props: [
+ {
+ name: 'page',
+ type: 'number',
+ description: '当前页码(从 1 开始)。',
+ required: true,
+ },
+ {
+ name: 'onPageChange',
+ type: '(page: number) => void',
+ description: '页面更改时调用。',
+ required: true,
+ },
+ {
+ name: 'totalItems',
+ type: 'number',
+ description: '所有页面的总项目数。用于计算总页数。',
+ },
+ {
+ name: 'pageSize',
+ type: 'number',
+ description: '每页项目数。',
+ default: '10',
+ },
+ {
+ name: 'variant',
+ type: "'pages' | 'count' | 'compact' | 'dots' | 'none'",
+ description: '分页控件的视觉变体。',
+ default: "'pages'",
+ },
+ {
+ name: 'position',
+ type: "'below' | 'above' | 'both' | 'none'",
+ description: '分页控件相对于表格的渲染位置。',
+ default: "'below'",
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSTablePagination',
+ displayName: 'useXDSTablePagination',
+ description: 'Headless pagination plugin. Client-side slicing, server-side, or cursor-based. Auto-renders XDSPagination above/below/both.',
+ propDescriptions: {
+ page: 'Current page (1-based).',
+ onPageChange: 'Called on page change.',
+ totalItems: 'Total items across all pages.',
+ pageSize: 'Items per page. Default 10.',
+ variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",
+ position: "Render position: 'below'|'above'|'both'|'none'.",
+ },
+};
diff --git a/packages/core/src/Table/useXDSTableSelection.doc.mjs b/packages/core/src/Table/useXDSTableSelection.doc.mjs
new file mode 100644
index 0000000000..12b50781d3
--- /dev/null
+++ b/packages/core/src/Table/useXDSTableSelection.doc.mjs
@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSTableSelection',
+ subComponentOf: 'Table',
+ 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',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'useXDSTableSelection',
+ displayName: 'useXDSTableSelection',
+ description: '返回 TablePlugin 的 Hook,实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
+ props: [
+ {
+ name: 'getIsItemSelected',
+ type: '(item: T) => boolean',
+ description: '返回给定项是否当前被选中。',
+ required: true,
+ },
+ {
+ name: 'onSelectItem',
+ type: '(event: {item: T; isSelected: boolean}) => void',
+ description: '当行复选框被切换时调用。isSelected 为新的期望状态。',
+ required: true,
+ },
+ {
+ name: 'onSelectAll',
+ type: '(event: {isAllSelected: boolean}) => void',
+ description: '当全选表头复选框被切换时调用。',
+ required: true,
+ },
+ {
+ name: 'getIsAllSelected',
+ type: '() => boolean',
+ description: '返回所有可选择项是否当前都被选中。',
+ required: true,
+ },
+ {
+ name: 'getIsIndeterminate',
+ type: '() => boolean',
+ description: '返回选择是否为部分选中(部分但非全部)。将全选复选框渲染为不确定状态。',
+ },
+ {
+ name: 'getIsItemSelectable',
+ type: '(item: T) => boolean',
+ description: '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
+ default: '() => true',
+ },
+ {
+ name: 'getIsItemEnabled',
+ type: '(item: T) => boolean',
+ description: '返回行复选框是否可交互。禁用的行显示禁用状态的复选框。',
+ default: '() => true',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSTableSelection',
+ displayName: 'useXDSTableSelection',
+ description: 'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
+ propDescriptions: {
+ getIsItemSelected: 'Returns whether item is selected.',
+ onSelectItem: 'Called on row checkbox toggle; isSelected = new desired state.',
+ onSelectAll: 'Called on select-all header checkbox toggle.',
+ getIsAllSelected: 'Returns whether all selectable items are selected.',
+ getIsIndeterminate: 'Returns partial selection state; renders indeterminate checkbox.',
+ getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows render nothing.',
+ getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
+ },
+};
diff --git a/packages/core/src/Table/useXDSTableSelectionState.doc.mjs b/packages/core/src/Table/useXDSTableSelectionState.doc.mjs
new file mode 100644
index 0000000000..2b690ae180
--- /dev/null
+++ b/packages/core/src/Table/useXDSTableSelectionState.doc.mjs
@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSTableSelectionState',
+ subComponentOf: 'Table',
+ 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',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSTableSelectionState',
+ displayName: 'useXDSTableSelectionState',
+ description: 'State companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically — disabled rows frozen (state preserved across select-all/deselect-all), non-selectable rows excluded.',
+ propDescriptions: {
+ data: 'Full data array rendered in table. **(required)**',
+ idKey: 'Key extractor — property name or fn returning unique string ID. **(required)**',
+ selectedKeys: 'Controlled set of selected item IDs. **(required)**',
+ setSelectedKeys: 'Setter for controlled selected keys. **(required)**',
+ getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows excluded from select-all. Defaults to () => true.',
+ getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows frozen — select-all preserves their state. Defaults to () => true.',
+ },
+};
diff --git a/packages/core/src/Table/useXDSTableSortable.doc.mjs b/packages/core/src/Table/useXDSTableSortable.doc.mjs
new file mode 100644
index 0000000000..0f27bd472d
--- /dev/null
+++ b/packages/core/src/Table/useXDSTableSortable.doc.mjs
@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'useXDSTableSortable',
+ subComponentOf: 'Table',
+ 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',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'useXDSTableSortable',
+ displayName: 'useXDSTableSortable',
+ description: '无头多列排序插件。用户拥有排序状态并提供回调。Shift+点击启用二级排序列。排序指示器自动渲染在表头单元格中。',
+ props: [
+ {
+ name: 'sort',
+ type: 'XDSTableSortState<TSortKey>',
+ description: '当前排序状态。{sortKey, direction} 条目的有序数组。第一个条目是主排序。',
+ required: true,
+ },
+ {
+ name: 'onSortChange',
+ type: '(sort: XDSTableSortState<TSortKey>) => void',
+ description: '用户点击表头单元格更改排序时调用。',
+ required: true,
+ },
+ {
+ name: 'allowUnsortedState',
+ type: 'boolean',
+ description: '允许循环回到未排序状态。为 true 时:升序、降序、未排序。为 false 时:升序、降序、升序。',
+ default: 'false',
+ },
+ {
+ name: 'isMultiSortEnabled',
+ type: 'boolean',
+ description: '通过 Shift+点击启用多列排序。普通点击仍替换整个排序状态。',
+ default: 'false',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'useXDSTableSortable',
+ displayName: 'useXDSTableSortable',
+ description: 'Headless multi-sort plugin. Consumer owns sort state + callback. Shift+click for secondary sort. Sort indicators auto-render in header cells.',
+ propDescriptions: {
+ sort: 'Current sort state; ordered array of {sortKey, direction} entries.',
+ onSortChange: 'Called on header click to change sort.',
+ allowUnsortedState: 'Allow cycling to unsorted. true: asc>desc>unsorted. false: asc>desc>asc.',
+ isMultiSortEnabled: 'Enable multi-sort via Shift+click. Regular click replaces sort state.',
+ },
+};
diff --git a/packages/core/src/Text/Heading.doc.mjs b/packages/core/src/Text/Heading.doc.mjs
new file mode 100644
index 0000000000..7e341f22cb
--- /dev/null
+++ b/packages/core/src/Text/Heading.doc.mjs
@@ -0,0 +1,187 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Heading',
+ subComponentOf: 'Text',
+ displayName: 'Heading',
+ description: 'Semantic heading component that renders h1–h6 elements with themed styling, themed sizing via type scale tokens, and line-clamp truncation.',
+ props: [
+ {
+ name: 'level',
+ type: '1 | 2 | 3 | 4 | 5 | 6',
+ description: 'Heading level. Determines the semantic HTML element (h1–h6) and the visual styling from the theme (unless `type` is set).',
+ required: true,
+ },
+ {
+ name: 'type',
+ type: "'display-1' | 'display-2' | 'display-3'",
+ description: 'Display type variant. Overrides the visual styling from `level` with display-scale sizing (larger, lighter weight, tighter line-height). The `level` still determines the HTML element for accessibility. Use for hero banners, marketing headlines, and data callouts.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Heading content.',
+ required: true,
+ },
+ {
+ name: 'accessibilityLevel',
+ type: '1 | 2 | 3 | 4 | 5 | 6',
+ description: 'Accessibility level override. When set and different from `level`, applies `aria-level` so the document outline differs from the visual style.',
+ },
+ {
+ name: 'color',
+ type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+ description: 'Text color.',
+ default: "'primary'",
+ },
+ {
+ name: 'display',
+ type: "'inline' | 'block'",
+ description: "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
+ default: "'block'",
+ },
+ {
+ name: 'maxLines',
+ type: 'number',
+ description: 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
+ default: '0',
+ },
+ {
+ name: 'hasTruncateTooltip',
+ type: 'boolean | LayerPlacement',
+ description: 'Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.',
+ default: 'true',
+ },
+ {
+ name: 'wordBreak',
+ type: "'break-word' | 'break-all'",
+ description: "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
+ },
+ {
+ name: 'textWrap',
+ type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
+ description: 'Text wrapping behavior.',
+ },
+ {
+ name: 'hasCapsize',
+ type: 'boolean',
+ description: 'Enable optical alignment using text-box-trim. Forces block display.',
+ default: 'false',
+ },
+ {
+ name: 'hasStrikethrough',
+ type: 'boolean',
+ description: 'Apply strikethrough text decoration.',
+ default: 'false',
+ },
+ {
+ name: 'id',
+ type: 'string',
+ description: 'HTML id attribute.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'Heading',
+ displayName: 'Heading',
+ description: '语义化标题组件,渲染带主题样式的 h1–h6 元素,支持可选的编辑风格比例和行截断。',
+ props: [
+ {
+ name: 'level',
+ type: '1 | 2 | 3 | 4 | 5 | 6',
+ description: '标题级别。决定语义 HTML 元素(h1–h6)和来自主题的样式(除非设置了 `type`)。',
+ required: true,
+ },
+ {
+ name: 'type',
+ type: "'display-1' | 'display-2' | 'display-3'",
+ description: '展示类型变体。用展示级别的大小(更大、更轻的字重、更紧的行高)覆盖来自 `level` 的视觉样式。`level` 仍然决定用于无障碍的 HTML 元素。用于英雄横幅、营销标题和数据提示。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '标题内容。',
+ required: true,
+ },
+ {
+ name: 'accessibilityLevel',
+ type: '1 | 2 | 3 | 4 | 5 | 6',
+ description: '无障碍级别覆盖。当设置且与 `level` 不同时,应用 `aria-level` 使文档大纲与视觉样式不同。',
+ },
+ {
+ name: 'color',
+ type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+ description: '文本颜色。',
+ default: "'primary'",
+ },
+ {
+ name: 'display',
+ type: "'inline' | 'block'",
+ description: "显示类型。当 maxLines > 0 或 hasCapsize 为 true 时,会静默覆盖为 'block'。",
+ default: "'block'",
+ },
+ {
+ name: 'maxLines',
+ type: 'number',
+ description: '截断前的最大行数。0 表示不截断。设置后,如果内容被截断,悬停时会显示工具提示。',
+ default: '0',
+ },
+ {
+ name: 'hasTruncateTooltip',
+ type: 'boolean | LayerPlacement',
+ description: '控制截断文本的工具提示行为。true 在默认位置显示工具提示,false 禁用它,或者 LayerPlacement 字符串设置特定位置。',
+ default: 'true',
+ },
+ {
+ name: 'wordBreak',
+ type: "'break-word' | 'break-all'",
+ description: "截断时的断词行为。单行截断默认为 'break-all',其他情况默认为 'break-word'。",
+ },
+ {
+ name: 'textWrap',
+ type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
+ description: '文本换行行为。',
+ },
+ {
+ name: 'hasCapsize',
+ type: 'boolean',
+ description: '使用 text-box-trim 启用光学对齐。强制块级显示。',
+ default: 'false',
+ },
+ {
+ name: 'hasStrikethrough',
+ type: 'boolean',
+ description: '应用删除线文本装饰。',
+ default: 'false',
+ },
+ {
+ name: 'id',
+ type: 'string',
+ description: 'HTML id 属性。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'Heading',
+ displayName: 'Heading',
+ description: 'Semantic h1–6 w/ themed styling, themed sizing via type scale tokens, line-clamp truncation.',
+ propDescriptions: {
+ level: 'Heading level; determines HTML element + styling from theme (unless type is set).',
+ type: 'Display variant (display-1/2/3); overrides visual styling from level with display-scale sizing.',
+ children: 'Heading content.',
+ accessibilityLevel: 'aria-level override when different from level for document outline.',
+ color: 'Text color.',
+ display: "Display type; overridden to 'block' when maxLines>0 or hasCapsize.",
+ maxLines: 'Max lines before truncation; 0=none. Shows tooltip if truncated.',
+ hasTruncateTooltip: 'Tooltip for truncated text; true=default position, false=disabled, or LayerPlacement.',
+ wordBreak: "Word break behavior; defaults 'break-all' for single-line, 'break-word' otherwise.",
+ textWrap: 'Text wrapping behavior.',
+ hasCapsize: 'Optical alignment via text-box-trim; forces block display.',
+ hasStrikethrough: 'Strikethrough text decoration.',
+ id: 'HTML id attribute.',
+ },
+};
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index 24e3f1f811..18a552195c 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -19,202 +19,100 @@ export const docs = {
{className: 'xds-text', visualProps: ['type', 'color']},
],
},
- components: [
+ description: 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.',
+ props: [
+ {
+ name: 'type',
+ type: "'body' | 'large' | 'label' | 'supporting' | 'code'",
+ description: 'Semantic text type. Determines size, weight, and line-height from the theme.',
+ default: "'body'",
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Text content.',
+ required: true,
+ },
+ {
+ name: 'size',
+ type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
+ description: 'Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.',
+ },
+ {
+ name: 'color',
+ type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
+ description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",
+ },
+ {
+ name: 'weight',
+ type: "'normal' | 'medium' | 'semibold' | 'bold'",
+ description: 'Font weight override.',
+ },
+ {
+ name: 'display',
+ type: "'inline' | 'block'",
+ description: "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
+ default: "'inline'",
+ },
+ {
+ name: 'as',
+ type: "'span' | 'p' | 'div' | 'label'",
+ description: 'HTML element to render.',
+ default: "'span'",
+ },
+ {
+ name: 'maxLines',
+ type: 'number',
+ description: 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
+ default: '0',
+ },
+ {
+ name: 'hasTruncateTooltip',
+ type: 'boolean | LayerPlacement',
+ description: 'Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.',
+ default: 'true',
+ },
+ {
+ name: 'wordBreak',
+ type: "'break-word' | 'break-all'",
+ description: "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
+ },
+ {
+ name: 'textWrap',
+ type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
+ description: 'Text wrapping behavior.',
+ },
+ {
+ name: 'hasCapsize',
+ type: 'boolean',
+ description: 'Enable optical alignment using text-box-trim. Forces block display.',
+ default: 'false',
+ },
+ {
+ name: 'hasStrikethrough',
+ type: 'boolean',
+ description: 'Apply strikethrough text decoration.',
+ default: 'false',
+ },
{
- name: 'XDSText',
- displayName: 'Text',
- description:
- 'Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.', props: [
- {
- name: 'type',
- type: "'body' | 'large' | 'label' | 'supporting' | 'code'",
- description:
- 'Semantic text type. Determines size, weight, and line-height from the theme.',
- default: "'body'",
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Text content.',
- required: true,
- },
- {
- name: 'size',
- type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
- description:
- 'Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone.',
- },
- {
- name: 'color',
- type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
- description:
- "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",
- },
- {
- name: 'weight',
- type: "'normal' | 'medium' | 'semibold' | 'bold'",
- description: 'Font weight override.',
- },
- {
- name: 'display',
- type: "'inline' | 'block'",
- description:
- "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
- default: "'inline'",
- },
- {
- name: 'as',
- type: "'span' | 'p' | 'div' | 'label'",
- description: 'HTML element to render.',
- default: "'span'",
- },
- {
- name: 'maxLines',
- type: 'number',
- description:
- 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
- default: '0',
- },
- {
- name: 'hasTruncateTooltip',
- type: 'boolean | LayerPlacement',
- description:
- 'Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.',
- default: 'true',
- },
- {
- name: 'wordBreak',
- type: "'break-word' | 'break-all'",
- description:
- "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
- },
- {
- name: 'textWrap',
- type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
- description: 'Text wrapping behavior.',
- },
- {
- name: 'hasCapsize',
- type: 'boolean',
- description:
- 'Enable optical alignment using text-box-trim. Forces block display.',
- default: 'false',
- },
- {
- name: 'hasStrikethrough',
- type: 'boolean',
- description: 'Apply strikethrough text decoration.',
- default: 'false',
- },
- {
- name: 'hasTabularNumbers',
- type: 'boolean',
- description:
- 'Use tabular (monospace) numbers for aligned numeric data.',
- default: 'false',
- },
- {
- name: 'id',
- type: 'string',
- description: 'HTML id attribute.',
- },
- {
- 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={{}}.',
- },
- ],
+ name: 'hasTabularNumbers',
+ type: 'boolean',
+ description: 'Use tabular (monospace) numbers for aligned numeric data.',
+ default: 'false',
},
{
- name: 'XDSHeading',
- displayName: 'Heading',
- description:
- 'Semantic heading component that renders h1–h6 elements with themed styling, themed sizing via type scale tokens, and line-clamp truncation.',
- props: [
- {
- name: 'level',
- type: '1 | 2 | 3 | 4 | 5 | 6',
- description:
- 'Heading level. Determines the semantic HTML element (h1–h6) and the visual styling from the theme (unless `type` is set).',
- required: true,
- },
- {
- name: 'type',
- type: "'display-1' | 'display-2' | 'display-3'",
- description:
- 'Display type variant. Overrides the visual styling from `level` with display-scale sizing (larger, lighter weight, tighter line-height). The `level` still determines the HTML element for accessibility. Use for hero banners, marketing headlines, and data callouts.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Heading content.',
- required: true,
- },
- {
- name: 'accessibilityLevel',
- type: '1 | 2 | 3 | 4 | 5 | 6',
- description:
- 'Accessibility level override. When set and different from `level`, applies `aria-level` so the document outline differs from the visual style.',
- },
- {
- name: 'color',
- type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
- description: 'Text color.',
- default: "'primary'",
- },
- {
- name: 'display',
- type: "'inline' | 'block'",
- description:
- "Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.",
- default: "'block'",
- },
- {
- name: 'maxLines',
- type: 'number',
- description:
- 'Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.',
- default: '0',
- },
- {
- name: 'hasTruncateTooltip',
- type: 'boolean | LayerPlacement',
- description:
- 'Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.',
- default: 'true',
- },
- {
- name: 'wordBreak',
- type: "'break-word' | 'break-all'",
- description:
- "Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise.",
- },
- {
- name: 'textWrap',
- type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
- description: 'Text wrapping behavior.',
- },
- {
- name: 'hasCapsize',
- type: 'boolean',
- description:
- 'Enable optical alignment using text-box-trim. Forces block display.',
- default: 'false',
- },
- {
- name: 'hasStrikethrough',
- type: 'boolean',
- description: 'Apply strikethrough text decoration.',
- default: 'false',
- },
- {
- name: 'id',
- type: 'string',
- description: 'HTML id attribute.',
- },
- ],
+ name: 'id',
+ type: 'string',
+ description: 'HTML id attribute.',
},
+ {
+ 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={{}}.',
+ },
+ ],
+ components: [
+ {name: 'XDSHeading'},
],
usage: {
description:
@@ -231,214 +129,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Text',
- displayName: 'Text',
- theming: {
- targets: [
- {className: 'xds-heading', visualProps: ['level', 'color']},
- {className: 'xds-text', visualProps: ['type', 'color']},
- ],
- },
- components: [
- {
- name: 'XDSText',
- displayName: 'Text',
- description:
- '语义化正文文本组件,使用来自主题的基于类型的样式渲染文本,支持可选的截断、装饰和布局属性。',
- props: [
- {
- name: 'type',
- type: "'body' | 'large' | 'label' | 'supporting' | 'code'",
- description:
- '语义化文本类型。从主题中确定大小、字重和行高。',
- default: "'body'",
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '文本内容。',
- required: true,
- },
- {
- name: 'size',
- type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
- description:
- '显式字体大小覆盖。覆盖来自 `type` 的大小但保留其他类型属性。建议单独使用 `type`。',
- },
- {
- name: 'color',
- type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
- description:
- "文本颜色。'supporting' 类型默认为 'secondary',其他类型默认为 'primary'。",
- },
- {
- name: 'weight',
- type: "'normal' | 'medium' | 'semibold' | 'bold'",
- description: '字重覆盖。',
- },
- {
- name: 'display',
- type: "'inline' | 'block'",
- description:
- "显示类型。当 maxLines > 0 或 hasCapsize 为 true 时,会静默覆盖为 'block'。",
- default: "'inline'",
- },
- {
- name: 'as',
- type: "'span' | 'p' | 'div' | 'label'",
- description: '要渲染的 HTML 元素。',
- default: "'span'",
- },
- {
- name: 'maxLines',
- type: 'number',
- description:
- '截断前的最大行数。0 表示不截断。设置后,如果内容被截断,悬停时会显示工具提示。',
- default: '0',
- },
- {
- name: 'hasTruncateTooltip',
- type: 'boolean | LayerPlacement',
- description:
- '控制截断文本的工具提示行为。true 在默认位置显示工具提示,false 禁用它,或者 LayerPlacement 字符串设置特定位置。',
- default: 'true',
- },
- {
- name: 'wordBreak',
- type: "'break-word' | 'break-all'",
- description:
- "截断时的断词行为。单行截断默认为 'break-all',其他情况默认为 'break-word'。",
- },
- {
- name: 'textWrap',
- type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
- description: '文本换行行为。',
- },
- {
- name: 'hasCapsize',
- type: 'boolean',
- description:
- '使用 text-box-trim 启用光学对齐。强制块级显示。',
- default: 'false',
- },
- {
- name: 'hasStrikethrough',
- type: 'boolean',
- description: '应用删除线文本装饰。',
- default: 'false',
- },
- {
- name: 'hasTabularNumbers',
- type: 'boolean',
- description:
- '使用表格(等宽)数字以实现对齐的数值数据。',
- default: 'false',
- },
- {
- name: 'id',
- type: 'string',
- description: 'HTML id 属性。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSHeading',
- displayName: 'Heading',
- description:
- '语义化标题组件,渲染带主题样式的 h1–h6 元素,支持可选的编辑风格比例和行截断。',
- props: [
- {
- name: 'level',
- type: '1 | 2 | 3 | 4 | 5 | 6',
- description:
- '标题级别。决定语义 HTML 元素(h1–h6)和来自主题的样式(除非设置了 `type`)。',
- required: true,
- },
- {
- name: 'type',
- type: "'display-1' | 'display-2' | 'display-3'",
- description:
- '展示类型变体。用展示级别的大小(更大、更轻的字重、更紧的行高)覆盖来自 `level` 的视觉样式。`level` 仍然决定用于无障碍的 HTML 元素。用于英雄横幅、营销标题和数据提示。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '标题内容。',
- required: true,
- },
- {
- name: 'accessibilityLevel',
- type: '1 | 2 | 3 | 4 | 5 | 6',
- description:
- '无障碍级别覆盖。当设置且与 `level` 不同时,应用 `aria-level` 使文档大纲与视觉样式不同。',
- },
- {
- name: 'color',
- type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'",
- description: '文本颜色。',
- default: "'primary'",
- },
- {
- name: 'display',
- type: "'inline' | 'block'",
- description:
- "显示类型。当 maxLines > 0 或 hasCapsize 为 true 时,会静默覆盖为 'block'。",
- default: "'block'",
- },
- {
- name: 'maxLines',
- type: 'number',
- description:
- '截断前的最大行数。0 表示不截断。设置后,如果内容被截断,悬停时会显示工具提示。',
- default: '0',
- },
- {
- name: 'hasTruncateTooltip',
- type: 'boolean | LayerPlacement',
- description:
- '控制截断文本的工具提示行为。true 在默认位置显示工具提示,false 禁用它,或者 LayerPlacement 字符串设置特定位置。',
- default: 'true',
- },
- {
- name: 'wordBreak',
- type: "'break-word' | 'break-all'",
- description:
- "截断时的断词行为。单行截断默认为 'break-all',其他情况默认为 'break-word'。",
- },
- {
- name: 'textWrap',
- type: "'wrap' | 'nowrap' | 'balance' | 'pretty'",
- description: '文本换行行为。',
- },
- {
- name: 'hasCapsize',
- type: 'boolean',
- description:
- '使用 text-box-trim 启用光学对齐。强制块级显示。',
- default: 'false',
- },
- {
- name: 'hasStrikethrough',
- type: 'boolean',
- description: '应用删除线文本装饰。',
- default: 'false',
- },
- {
- name: 'id',
- type: 'string',
- description: 'HTML id 属性。',
- },
- ],
- },
- ],
usage: {
description:
'Text renders styled body text and headings from the theme. Use XDSText with a semantic type for body copy, labels, and captions, and XDSHeading for section titles that output the correct h1\u2013h6 element.',
@@ -470,50 +162,4 @@ export const docsDense = {
{ guidance: false, description: 'Raw <p>/<h1>/<span> \u2014 use XDSText/XDSHeading for theme tokens.' },
],
},
- components: [
- {
- name: 'XDSText',
- displayName: 'Text',
- description: 'Semantic body text w/ type-based theme styling, optional truncation, decoration, layout props.',
- propDescriptions: {
- type: 'Semantic text type; determines size, weight, line-height from theme.',
- children: 'Text content.',
- size: 'Explicit font size override; overrides type size but preserves other properties. Prefer type alone.',
- color: "Text color; defaults 'secondary' for supporting, 'primary' for others.",
- weight: 'Font weight override.',
- display: "Display type; overridden to 'block' when maxLines>0 or hasCapsize.",
- as: 'HTML element to render.',
- maxLines: 'Max lines before truncation; 0=none. Shows tooltip if truncated.',
- hasTruncateTooltip: 'Tooltip for truncated text; true=default position, false=disabled, or LayerPlacement.',
- wordBreak: "Word break behavior; defaults 'break-all' for single-line, 'break-word' otherwise.",
- textWrap: 'Text wrapping behavior.',
- hasCapsize: 'Optical alignment via text-box-trim; forces block display.',
- hasStrikethrough: 'Strikethrough text decoration.',
- hasTabularNumbers: 'Tabular (monospace) numbers for aligned data.',
- id: 'HTML id attribute.',
- xstyle: 'StyleX layout styles; must be stylex.create() value.',
- },
- },
- {
- name: 'XDSHeading',
- displayName: 'Heading',
- description: 'Semantic h1\u20136 w/ themed styling, themed sizing via type scale tokens, line-clamp truncation.',
- propDescriptions: {
- level: 'Heading level; determines HTML element + styling from theme (unless type is set).',
- type: "Display variant (display-1/2/3); overrides visual styling from level with display-scale sizing.",
- children: 'Heading content.',
- accessibilityLevel: 'aria-level override when different from level for document outline.',
-
- color: 'Text color.',
- display: "Display type; overridden to 'block' when maxLines>0 or hasCapsize.",
- maxLines: 'Max lines before truncation; 0=none. Shows tooltip if truncated.',
- hasTruncateTooltip: 'Tooltip for truncated text; true=default position, false=disabled, or LayerPlacement.',
- wordBreak: "Word break behavior; defaults 'break-all' for single-line, 'break-word' otherwise.",
- textWrap: 'Text wrapping behavior.',
- hasCapsize: 'Optical alignment via text-box-trim; forces block display.',
- hasStrikethrough: 'Strikethrough text decoration.',
- id: 'HTML id attribute.',
- },
- },
- ],
};
\ No newline at end of file
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index 167240b11f..ea9243ad45 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -19,47 +19,98 @@ export const docs = {
{className: 'xds-toggle-button-group'},
],
},
- components: [
+ description: 'A button that toggles between pressed and unpressed states. Thin wrapper over XDSButton with controlled toggle pattern, icon swap, and font weight emphasis.',
+ props: [
{
- name: 'XDSToggleButton',
- displayName: 'Toggle Button',
- description: 'A button that toggles between pressed and unpressed states. Thin wrapper over XDSButton with controlled toggle pattern, icon swap, and font weight emphasis.',
- props: [
- {name: 'label', type: 'string', description: 'Accessible label for the button. Used as visible text, or as aria-label for icon-only buttons.', required: true},
- {name: 'isPressed', type: 'boolean', description: 'Whether the button is currently pressed. Ignored when inside a group.'},
- {name: 'onPressedChange', type: '(isPressed: boolean) => void', description: 'Called when pressed state should change. Ignored when inside a group.'},
- {name: 'pressedChangeAction', type: '(isPressed: boolean) => Promise<void>', description: 'Async action handler for API-backed toggles. Shows loading spinner while pending.'},
- {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Button size. Defaults to group size when inside a group.', default: "'md'"},
- {name: 'isDisabled', type: 'boolean', description: 'Whether the button is disabled.', default: 'false'},
- {name: 'isLoading', type: 'boolean', description: 'Whether the button shows a loading spinner.', default: 'false'},
- {name: 'icon', type: 'ReactNode', description: 'Icon element. When provided without children, button becomes icon-only with tooltip from label.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {name: 'pressedIcon', type: 'ReactNode', description: 'Icon shown when pressed. Falls back to icon if not provided.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the button. Used as visible text, or as aria-label for icon-only buttons.',
+ required: true,
+ },
+ {
+ name: 'isPressed',
+ type: 'boolean',
+ description: 'Whether the button is currently pressed. Ignored when inside a group.',
+ },
+ {
+ name: 'onPressedChange',
+ type: '(isPressed: boolean) => void',
+ description: 'Called when pressed state should change. Ignored when inside a group.',
+ },
+ {
+ name: 'pressedChangeAction',
+ type: '(isPressed: boolean) => Promise<void>',
+ description: 'Async action handler for API-backed toggles. Shows loading spinner while pending.',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Button size. Defaults to group size when inside a group.',
+ default: "'md'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the button is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: 'Whether the button shows a loading spinner.',
+ default: 'false',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon element. When provided without children, button becomes icon-only with tooltip from label.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
},
- {name: 'children', type: 'ReactNode', description: 'Visible content. If omitted with icon, button becomes icon-only.'},
- {name: 'tooltip', type: 'string', description: 'Tooltip text shown on hover.'},
- {name: 'value', type: 'string', description: 'Value identifier when used inside XDSToggleButtonGroup. Required in groups.'},
- {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
- ], },
+ ],
+ },
{
- name: 'XDSToggleButtonGroup',
- displayName: 'Toggle Button Group',
- description: 'Groups toggle buttons for exclusive (single) or multi-select behavior. Uses discriminated union on type for type-safe value/onChange.',
- props: [
- {name: 'children', type: 'ReactNode', description: 'XDSToggleButton children.', required: true, slotElements: [{__element: 'XDSToggleButton', props: {label: 'Option', value: 'option'}}]},
- {name: 'label', type: 'string', description: 'Accessible label for the group (aria-label).', required: true},
- {name: 'type', type: "'single' | 'multiple'", description: 'Selection mode. Single allows one active button, multiple allows many.', default: "'single'"},
- {name: 'value', type: 'string | null | string[]', description: 'Currently selected value(s). Type depends on selection mode.', required: true},
- {name: 'onChange', type: '(value: string | null | string[]) => void', description: 'Called when selection changes.', required: true},
- {name: 'orientation', type: "'horizontal' | 'vertical'", description: 'Layout direction of the button group.', default: "'horizontal'"},
- {name: 'size', type: "'sm' | 'md' | 'lg'", description: 'Default size for buttons in the group. Individual buttons can override.', default: "'md'"},
- {name: 'isDisabled', type: 'boolean', description: 'Whether all buttons in the group are disabled.', default: 'false'},
- {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.'},
- {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},
+ name: 'pressedIcon',
+ type: 'ReactNode',
+ description: 'Icon shown when pressed. Falls back to icon if not provided.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
],
},
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Visible content. If omitted with icon, button becomes icon-only.',
+ },
+ {
+ name: 'tooltip',
+ type: 'string',
+ description: 'Tooltip text shown on hover.',
+ },
+ {
+ name: 'value',
+ type: 'string',
+ description: 'Value identifier when used inside XDSToggleButtonGroup. Required in groups.',
+ },
+ {
+ name: 'data-testid',
+ type: 'string',
+ description: 'Test selector for automated testing frameworks.',
+ },
+ ],
+ components: [
+ {name: 'XDSToggleButtonGroup'},
],
usage: {
description:
@@ -83,45 +134,6 @@ export const docs = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- components: [
- {
- name: 'XDSToggleButton',
- displayName: 'Toggle Button',
- description: '在按下和未按下状态之间切换的按钮。XDSButton 的轻量封装,添加受控切换模式、图标切换和字重加粗。',
- propDescriptions: {
- label: '按钮的无障碍标签。作为可见文本或仅图标按钮的 aria-label。',
- isPressed: '按钮是否处于按下状态。在分组内时被忽略。',
- onPressedChange: '按下状态变更时的回调。在分组内时被忽略。',
- pressedChangeAction: 'API 调用的异步操作处理器。等待期间显示加载动画。',
- size: '按钮尺寸。在分组内时默认使用分组尺寸。',
- isDisabled: '按钮是否禁用。',
- isLoading: '按钮是否显示加载动画。',
- icon: '图标元素。无 children 时按钮变为仅图标模式。',
- pressedIcon: '按下时显示的图标。未提供时回退到 icon。',
- children: '可见内容。与 icon 同时省略时按钮变为仅图标模式。',
- tooltip: '悬停时显示的提示文本。',
- value: '在 XDSToggleButtonGroup 内使用的值标识符。',
- 'data-testid': '自动化测试的选择器。',
- },
- },
- {
- name: 'XDSToggleButtonGroup',
- displayName: 'Toggle Button Group',
- description: '将切换按钮分组,支持单选或多选行为。通过 type 判别联合类型实现类型安全。',
- propDescriptions: {
- children: 'XDSToggleButton 子元素。',
- label: '分组的无障碍标签 (aria-label)。',
- type: '选择模式。single 允许单个激活,multiple 允许多个。',
- value: '当前选中的值。类型取决于选择模式。',
- onChange: '选择变更时的回调。',
- orientation: '按钮组的布局方向。',
- size: '分组内按钮的默认尺寸。单个按钮可覆盖。',
- isDisabled: '分组内所有按钮是否禁用。',
- xstyle: 'StyleX 样式,用于布局自定义。必须是 stylex.create() 的值。',
- 'data-testid': '自动化测试的选择器。',
- },
- },
- ],
usage: {
description:
'ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.',
@@ -157,43 +169,4 @@ export const docsDense = {
{guidance: false, description: "Don't use ToggleButton for persistent settings; use Switch instead."},
],
},
- components: [
- {
- name: 'XDSToggleButton',
- displayName: 'Toggle Button',
- description: 'toggle btn w/ controlled pattern, icon swap, font weight emphasis; wraps XDSButton',
- propDescriptions: {
- label: 'a11y label; visible text or aria-label for icon-only',
- isPressed: 'pressed state; ignored in group',
- onPressedChange: 'pressed state change cb; ignored in group',
- pressedChangeAction: 'async toggle handler w/ loading spinner',
- size: 'btn size; defaults to group size in group',
- isDisabled: 'disabled state',
- isLoading: 'shows loading spinner',
- icon: 'icon element; icon-only mode w/o children',
- pressedIcon: 'pressed icon; falls back to icon',
- children: 'visible content; omit w/ icon for icon-only',
- tooltip: 'hover tooltip text',
- value: 'value id for group usage',
- 'data-testid': 'test selector',
- },
- },
- {
- name: 'XDSToggleButtonGroup',
- displayName: 'Toggle Button Group',
- description: 'groups toggle btns for exclusive/multi-select; discriminated union on type',
- propDescriptions: {
- children: 'XDSToggleButton children',
- label: 'a11y label (aria-label)',
- type: 'selection mode: single or multiple',
- value: 'selected value(s); type depends on mode',
- onChange: 'selection change cb',
- orientation: 'layout direction',
- size: 'default btn size; individual btns override',
- isDisabled: 'all btns disabled',
- xstyle: 'StyleX layout styles; must be stylex.create() value',
- 'data-testid': 'test selector',
- },
- },
- ],
};
diff --git a/packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs b/packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs
new file mode 100644
index 0000000000..0d517e11a3
--- /dev/null
+++ b/packages/core/src/ToggleButton/ToggleButtonGroup.doc.mjs
@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'ToggleButtonGroup',
+ subComponentOf: 'ToggleButton',
+ displayName: 'Toggle Button Group',
+ description: 'Groups toggle buttons for exclusive (single) or multi-select behavior. Uses discriminated union on type for type-safe value/onChange.',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'XDSToggleButton children.',
+ required: true,
+ slotElements: [
+ {
+ __element: 'XDSToggleButton',
+ props: {
+ label: 'Option',
+ value: 'option',
+ },
+ },
+ ],
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the group (aria-label).',
+ required: true,
+ },
+ {
+ name: 'type',
+ type: "'single' | 'multiple'",
+ description: 'Selection mode. Single allows one active button, multiple allows many.',
+ default: "'single'",
+ },
+ {
+ name: 'value',
+ type: 'string | null | string[]',
+ description: 'Currently selected value(s). Type depends on selection mode.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: string | null | string[]) => void',
+ description: 'Called when selection changes.',
+ required: true,
+ },
+ {
+ name: 'orientation',
+ type: "'horizontal' | 'vertical'",
+ description: 'Layout direction of the button group.',
+ default: "'horizontal'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Default size for buttons in the group. Individual buttons can override.',
+ default: "'md'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether all buttons in the group are disabled.',
+ default: 'false',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.',
+ },
+ {
+ name: 'data-testid',
+ type: 'string',
+ description: 'Test selector for automated testing frameworks.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'ToggleButtonGroup',
+ displayName: 'Toggle Button Group',
+ description: '将切换按钮分组,支持单选或多选行为。通过 type 判别联合类型实现类型安全。',
+ propDescriptions: {
+ children: 'XDSToggleButton 子元素。',
+ label: '分组的无障碍标签 (aria-label)。',
+ type: '选择模式。single 允许单个激活,multiple 允许多个。',
+ value: '当前选中的值。类型取决于选择模式。',
+ onChange: '选择变更时的回调。',
+ orientation: '按钮组的布局方向。',
+ size: '分组内按钮的默认尺寸。单个按钮可覆盖。',
+ isDisabled: '分组内所有按钮是否禁用。',
+ xstyle: 'StyleX 样式,用于布局自定义。必须是 stylex.create() 的值。',
+ "data-testid": '自动化测试的选择器。',
+ },
+};
+
+export const docsDense = {
+ name: 'ToggleButtonGroup',
+ displayName: 'Toggle Button Group',
+ description: 'groups toggle btns for exclusive/multi-select; discriminated union on type',
+ propDescriptions: {
+ children: 'XDSToggleButton children',
+ label: 'a11y label (aria-label)',
+ type: 'selection mode: single or multiple',
+ value: 'selected value(s); type depends on mode',
+ onChange: 'selection change cb',
+ orientation: 'layout direction',
+ size: 'default btn size; individual btns override',
+ isDisabled: 'all btns disabled',
+ xstyle: 'StyleX layout styles; must be stylex.create() value',
+ "data-testid": 'test selector',
+ },
+};
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index 90c97a204d..f9cbba85ab 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -25,374 +25,105 @@ export const docs = {
{className: 'xds-top-nav-menu'},
],
},
- components: [
- {
- name: 'XDSTopNav',
- displayName: 'Top Nav',
- description: 'Main navigation bar container with slot-based layout. Children are accepted as an alias for startContent.',
- props: [
- {
- name: 'heading',
- type: 'ReactNode',
- description:
- 'Heading slot content (logo, brand), positioned at the left edge of the nav bar.',
- slotElements: [{__element: 'XDSText', props: {type: 'body', weight: 'bold'}, children: 'Heading'}],
- },
- {
- name: 'startContent',
- type: 'ReactNode',
- description:
- 'Start content slot for navigation items or breadcrumbs, positioned after the heading, left-aligned.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Alias for startContent. Prefer startContent when composing with heading, centerContent, or endContent; children keeps the common React nav-item pattern from silently dropping items.',
- slotElements: [{__element: 'XDSTopNavItem', props: {label: 'Home', href: '#'}}],
- },
- {
- name: 'centerContent',
- type: 'ReactNode',
- description:
- 'Center content slot (tabs, search bar, primary navigation). When provided, switches the layout to a three-column CSS grid for true horizontal centering.',
- slotElements: [{__element: 'XDSText', props: {type: 'body', weight: 'bold'}, children: 'Center'}],
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- 'End content slot for search, icons, or user profile, positioned at the right edge.',
- slotElements: [
- {__element: 'XDSIcon', props: {icon: 'chevronDown', size: 'sm'}},
- {__element: 'XDSBadge', props: {label: '3'}},
- ],
- },
- {
- name: 'label',
- type: 'string',
- description:
- 'Accessible label for the navigation landmark, applied as aria-label on the <nav> element.',
- },
- {
- 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={{}}.',
- },
- ], },
+ description: 'Main navigation bar container with slot-based layout. Children are accepted as an alias for startContent.',
+ props: [
{
- name: 'XDSTopNavHeading',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Heading',
- description:
- 'Product/suite/account heading for the XDSTopNav heading slot. Supports smart interaction boundary logic: logo, heading text, superheading/subheading with independent links, and an optional menu popover with automatic chevron indicator.',
- props: [
- {
- name: 'logo',
- type: 'ReactNode',
- description:
- 'Logo element to display before the heading text. Can be an image, XDSNavIcon, or any ReactNode.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'heading',
- type: 'string',
- description: 'Product/app name displayed as the primary heading text.',
- },
- {
- name: 'headingHref',
- type: 'string',
- description:
- 'Link for the heading text (e.g. product home). When no menu is present and this is the only href, the whole heading becomes one clickable link.',
- },
- {
- name: 'href',
- type: 'string',
- description:
- 'Deprecated: use headingHref instead. URL to navigate to when clicked.',
- },
- {
- name: 'superheading',
- type: 'string',
- description:
- 'Text above the heading (e.g. suite name). Rendered in a smaller secondary style.',
- },
- {
- name: 'superheadingHref',
- type: 'string',
- description:
- 'Link for the superheading text (e.g. suite home). When provided alongside a menu, renders as an independent inline link.',
- },
- {
- name: 'subheading',
- type: 'string',
- description:
- 'Text below the heading (e.g. account context). Rendered in a smaller secondary style.',
- },
- {
- name: 'subheadingHref',
- type: 'string',
- description:
- 'Link for the subheading text. When provided alongside a menu, renders as an independent inline link.',
- },
- {
- name: 'headerEndContent',
- type: 'ReactNode',
- description:
- 'Content rendered at the trailing edge of the heading row (e.g. a badge or status indicator).',
- slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
- },
- {
- name: 'menu',
- type: 'ReactNode',
- description:
- 'Menu content shown in a popover dropdown. When provided, a chevron indicator appears automatically. Interaction boundary is determined by the presence of hrefs: no hrefs means the whole header is the trigger; with hrefs, links are independent and the chevron area is the trigger.',
- slotElements: [{__element: 'XDSButton', props: {label: 'Action', variant: 'ghost', size: 'sm'}}],
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- 'Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props.',
- },
+ name: 'heading',
+ type: 'ReactNode',
+ description: 'Heading slot content (logo, brand) — positioned at the left edge of the nav bar.',
+ slotElements: [
{
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ weight: 'bold',
+ },
+ children: 'Heading',
},
],
},
{
- name: 'XDSTopNavItem',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Item',
- description:
- 'Navigation link item for use in XDSTopNav startContent; renders as an anchor with hover and selected states.',
- props: [
- {
- name: 'label',
- type: 'string',
- description:
- 'Accessible label for the nav item. Rendered as visible text by default. When isIconOnly is true, used as aria-label instead.',
- required: true,
- },
- {
- name: 'href',
- type: 'string',
- description: 'Navigation target URL.',
- },
- {
- name: 'isSelected',
- type: 'boolean',
- description:
- 'Whether this nav item is currently selected. Sets aria-current="page" and applies highlighted styles.',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description:
- 'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',
- default: 'false',
- },
+ name: 'startContent',
+ type: 'ReactNode',
+ description: 'Start content slot for navigation items or breadcrumbs — positioned after the heading, left-aligned.',
+ slotElements: [
{
- name: 'isIconOnly',
- type: 'boolean',
- description:
- 'Renders the item as a square icon-only element. When true, label becomes the aria-label and visible text is hidden. Requires icon to be set.',
- default: 'false',
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description:
- 'Optional icon to display before the label.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'Custom content to render instead of the label text.',
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- 'Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props.',
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
},
],
},
{
- name: 'XDSTopNavMenu',
- displayName: 'Top Nav Menu',
- description:
- 'Navigation item that displays a hover-triggered popover menu with rich items containing an icon, title, and optional description.',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Visible label for the trigger button.',
- required: true,
- },
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Alias for startContent. Prefer startContent when composing with heading, centerContent, or endContent; children keeps the common React nav-item pattern from silently dropping items.',
+ slotElements: [
{
- name: 'items',
- type: 'XDSTopNavMenuItemData[]',
- description: 'Menu items to display in the hover popover.',
- required: true,
- },
- {
- name: 'delay',
- type: 'number',
- description:
- 'Delay in milliseconds before showing the menu on hover.',
- default: '150',
- },
- {
- name: 'hideDelay',
- type: 'number',
- description:
- 'Delay in milliseconds before hiding the menu after the mouse leaves.',
- default: '200',
+ __element: 'XDSTopNavItem',
+ props: {
+ label: 'Home',
+ href: '#',
+ },
},
],
},
{
- name: 'XDSTopNavMegaMenu',
- displayName: 'Top Nav Mega Menu',
- description:
- 'Navigation item that displays a full-width mega menu panel on hover. Uses a slots API with items and featured props. XDSTopNavMegaMenuItem renders itself in both desktop and mobile drawer modes. Supports inline collapsible drawer via render mode context.',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Visible label for the trigger button.',
- required: true,
- },
- {
- name: 'items',
- type: 'ReactNode',
- description: 'Menu items slot: typically XDSTopNavMegaMenuItem components, but accepts any ReactNode.',
- slotElements: [{__element: 'XDSTopNavItem', props: {label: 'Item', href: '#'}}],
- },
+ name: 'centerContent',
+ type: 'ReactNode',
+ description: 'Center content slot (tabs, search bar, primary navigation) — when provided, switches the layout to a three-column CSS grid for true horizontal centering.',
+ slotElements: [
{
- name: 'featured',
- type: 'ReactNode',
- description: 'Featured content slot: rendered in the right panel on desktop, below items in the mobile drawer.',
- slotElements: [{__element: 'XDSCard', props: {padding: 4}, children: 'Featured content'}],
- },
- {
- name: 'delay',
- type: 'number',
- description:
- 'Delay in milliseconds before showing the menu on hover.',
- default: '150',
- },
- {
- name: 'hideDelay',
- type: 'number',
- description:
- 'Delay in milliseconds before hiding the menu after the mouse leaves.',
- default: '250',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description:
- 'Callback fired when the mega menu opens or closes. Useful for coordinating wrapper styles.',
+ __element: 'XDSText',
+ props: {
+ type: 'body',
+ weight: 'bold',
+ },
+ children: 'Center',
},
],
},
{
- name: 'XDSTopNavMegaMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Mega Menu Item',
- description:
- 'An individual item inside an XDSTopNavMegaMenu. Renders itself in both desktop (popover grid) and mobile drawer modes via render mode context.',
- props: [
- {
- name: 'title',
- type: 'string',
- description: 'Display title for the menu item.',
- required: true,
- },
+ name: 'endContent',
+ type: 'ReactNode',
+ description: 'End content slot for search, icons, or user profile — positioned at the right edge.',
+ slotElements: [
{
- name: 'description',
- type: 'string',
- description: 'Optional description text displayed below the title.',
+ __element: 'XDSIcon',
+ props: {
+ icon: 'chevronDown',
+ size: 'sm',
+ },
},
{
- name: 'icon',
- type: 'ReactNode',
- description: 'Optional icon element displayed to the left.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'href',
- type: 'string',
- description: 'URL to navigate to when clicked.',
- },
- {
- name: 'onClick',
- type: '() => void',
- description: 'Callback when item is clicked.',
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- 'Custom component to render instead of <a> for link items. Overrides the provider-level default set by XDSLinkProvider.',
+ __element: 'XDSBadge',
+ props: {
+ label: '3',
+ },
},
],
},
{
- name: 'XDSTopNavMegaMenuFeaturedCard',
- displayName: 'Top Nav Mega Menu Featured Card',
- description:
- 'Standard featured card for the XDSTopNavMegaMenu featured slot. Provides a consistent card with optional image, title, description, and CTA link.',
- props: [
- {
- name: 'title',
- type: 'string',
- description: 'Card title.',
- required: true,
- },
- {
- name: 'description',
- type: 'string',
- description: 'Description text below the title.',
- },
- {
- name: 'image',
- type: 'string',
- description: 'Optional image URL displayed above the body.',
- },
- {
- name: 'imageAlt',
- type: 'string',
- description: 'Alt text for the image.',
- },
- {
- name: 'linkLabel',
- type: 'string',
- description: 'CTA link text.',
- },
- {
- name: 'linkHref',
- type: 'string',
- description: 'CTA link URL.',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Custom content rendered below the standard body.',
- },
- ],
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the navigation landmark, applied as aria-label on the <nav> element.',
+ },
+ {
+ 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={{}}.',
},
],
+ components: [
+ {name: 'XDSTopNavHeading'},
+ {name: 'XDSTopNavItem'},
+ {name: 'XDSTopNavMenu'},
+ {name: 'XDSTopNavMegaMenu'},
+ {name: 'XDSTopNavMegaMenuItem'},
+ {name: 'XDSTopNavMegaMenuFeaturedCard'},
+ ],
usage: {
description:
'TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.',
@@ -411,368 +142,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'TopNav',
- displayName: 'Top Nav',
- theming: {
- targets: [
- {className: 'xds-top-nav', states: ['mode']},
- {className: 'xds-top-nav-item', states: ['mode']},
- {className: 'xds-top-nav-heading'},
- {className: 'xds-top-nav-mega-menu', states: ['mode']},
- {className: 'xds-top-nav-mega-menu-item', states: ['mode']},
- {className: 'xds-top-nav-mega-menu-featured-card'},
- {className: 'xds-top-nav-menu'},
- ],
- },
- components: [
- {
- name: 'XDSTopNav',
- displayName: 'Top Nav',
- description: '采用插槽式布局的主导航栏容器。children 可作为 startContent 的别名。',
- props: [
- {
- name: 'heading',
- type: 'ReactNode',
- description:
- '标题插槽内容(标志、品牌),位于导航栏的左边缘。',
- },
- {
- name: 'startContent',
- type: 'ReactNode',
- description:
- '起始内容插槽,用于导航项或面包屑,位于标题之后,左对齐。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- 'startContent 的别名。与 heading、centerContent 或 endContent 组合时优先使用 startContent;children 可避免常见 React 导航项写法被静默丢弃。',
- },
- {
- name: 'centerContent',
- type: 'ReactNode',
- description:
- '居中内容插槽(标签页、搜索栏、主导航)。提供时,布局切换为三列 CSS grid 以实现真正的水平居中。',
- },
- {
- name: 'endContent',
- type: 'ReactNode',
- description:
- '末尾内容插槽,用于搜索、图标或用户头像,位于右边缘。',
- },
- {
- name: 'label',
- type: 'string',
- description:
- '导航地标的无障碍标签,作为 aria-label 应用于 <nav> 元素。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,不能是内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSTopNavHeading',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Heading',
- description:
- 'XDSTopNav 标题插槽的产品/套件/账户标题组件。支持智能交互边界逻辑:标志、标题文本、独立链接的上标题/下标题,以及带自动箭头指示器的可选菜单弹出层。',
- props: [
- {
- name: 'logo',
- type: 'ReactNode',
- description:
- '在标题文本前显示的标志元素。可以是图片、XDSNavIcon 或任何 ReactNode。',
- },
- {
- name: 'heading',
- type: 'string',
- description: '作为主标题文本显示的产品/应用名称。',
- },
- {
- name: 'headingHref',
- type: 'string',
- description:
- '标题文本的链接(如产品首页)。当没有菜单且这是唯一的 href 时,整个标题变为一个可点击链接。',
- },
- {
- name: 'href',
- type: 'string',
- description:
- '已弃用:请使用 headingHref。点击时导航到的 URL。',
- },
- {
- name: 'superheading',
- type: 'string',
- description:
- '标题上方的文本(如套件名称)。以较小的次要样式渲染。',
- },
- {
- name: 'superheadingHref',
- type: 'string',
- description:
- '上标题文本的链接(如套件首页)。与菜单一起提供时,渲染为独立的内联链接。',
- },
- {
- name: 'subheading',
- type: 'string',
- description:
- '标题下方的文本(如账户上下文)。以较小的次要样式渲染。',
- },
- {
- name: 'subheadingHref',
- type: 'string',
- description:
- '下标题文本的链接。与菜单一起提供时,渲染为独立的内联链接。',
- },
- {
- name: 'headerEndContent',
- type: 'ReactNode',
- description:
- '在标题行尾部渲染的内容(如徽章或状态指示器)。',
- },
- {
- name: 'menu',
- type: 'ReactNode',
- description:
- '在弹出层下拉菜单中显示的菜单内容。提供时自动显示箭头指示器。交互边界由 href 的存在决定:没有 href 时整个标题为触发器;有 href 时链接独立,箭头区域为触发器。',
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- '用于替代 <a> 的自定义链接组件。覆盖 XDSLinkProvider 设置的默认组件。必须接受 href、className、style 和 children 属性。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
- },
- ],
- },
- {
- name: 'XDSTopNavItem',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Item',
- description:
- '用于 XDSTopNav startContent 的导航链接项,渲染为具有悬停和选中状态的锚点。',
- props: [
- {
- name: 'label',
- type: 'string',
- description:
- '导航项的无障碍标签。用作可见文本,或作为仅图标项的 aria-label。',
- required: true,
- },
- {
- name: 'href',
- type: 'string',
- description: '导航目标 URL。',
- },
- {
- name: 'isSelected',
- type: 'boolean',
- description:
- '此导航项是否为当前选中状态。设置 aria-current="page" 并应用高亮样式。',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description:
- '导航项是否被禁用。设置 aria-disabled 并阻止交互。',
- default: 'false',
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description:
- '在标签前显示的可选图标。如果在没有子元素的情况下提供,项目变为仅图标模式。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description:
- '替代标签文本渲染的自定义内容。省略且提供了图标时,项目变为仅图标模式。',
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- '替代 <a> 渲染的自定义组件。覆盖 XDSLinkProvider 设置的提供者级别默认值。必须接受 href、className、style 和 children 属性。',
- },
- ],
- },
- {
- name: 'XDSTopNavMenu',
- displayName: 'Top Nav Menu',
- description:
- '导航项,在悬停时显示弹出菜单,包含带图标、标题和可选描述的丰富菜单项。',
- props: [
- {
- name: 'label',
- type: 'string',
- description: '触发按钮的可见标签。',
- required: true,
- },
- {
- name: 'items',
- type: 'XDSTopNavMenuItemData[]',
- description: '在悬停弹出框中显示的菜单项。',
- required: true,
- },
- {
- name: 'delay',
- type: 'number',
- description:
- '悬停时显示菜单前的延迟(毫秒)。',
- default: '150',
- },
- {
- name: 'hideDelay',
- type: 'number',
- description:
- '鼠标离开后隐藏菜单的延迟(毫秒)。',
- default: '200',
- },
- ],
- },
- {
- name: 'XDSTopNavMegaMenu',
- displayName: 'Top Nav Mega Menu',
- description:
- '导航项,在悬停时显示全宽超级菜单面板。使用插槽 API(items 和 featured)。XDSTopNavMegaMenuItem 在桌面和移动抽屉模式中自行渲染。',
- props: [
- {
- name: 'label',
- type: 'string',
- description: '触发按钮的可见标签。',
- required: true,
- },
- {
- name: 'items',
- type: 'ReactNode',
- description: '菜单项插槽:通常为 XDSTopNavMegaMenuItem 组件,但接受任何 ReactNode。',
- },
- {
- name: 'featured',
- type: 'ReactNode',
- description: '特色内容插槽:桌面端显示在右侧面板,移动抽屉中显示在项目下方。',
- },
- {
- name: 'delay',
- type: 'number',
- description:
- '悬停时显示菜单前的延迟(毫秒)。',
- default: '150',
- },
- {
- name: 'hideDelay',
- type: 'number',
- description:
- '鼠标离开后隐藏菜单的延迟(毫秒)。',
- default: '250',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description:
- '超级菜单打开或关闭时触发的回调。用于协调包装器样式。',
- },
- ],
- },
- {
- name: 'XDSTopNavMegaMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Mega Menu Item',
- description:
- '超级菜单中的单个项目。在桌面端(弹出层网格)和移动抽屉模式中都会自行渲染。',
- props: [
- {
- name: 'title',
- type: 'string',
- description: '菜单项的显示标题。',
- required: true,
- },
- {
- name: 'description',
- type: 'string',
- description: '标题下方的可选描述文本。',
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: '左侧显示的可选图标元素。',
- },
- {
- name: 'href',
- type: 'string',
- description: '点击时导航的 URL。',
- },
- {
- name: 'onClick',
- type: '() => void',
- description: '点击项目时的回调。',
- },
- {
- name: 'as',
- type: 'XDSLinkComponentType',
- description:
- '用于替代 <a> 的自定义链接组件。覆盖 XDSLinkProvider 设置的默认组件。',
- },
- ],
- },
- {
- name: 'XDSTopNavMegaMenuFeaturedCard',
- displayName: 'Top Nav Mega Menu Featured Card',
- description:
- '超级菜单 featured 插槽的标准特色卡片。提供带可选图片、标题、描述和 CTA 链接的一致卡片。',
- props: [
- {
- name: 'title',
- type: 'string',
- description: '卡片标题。',
- required: true,
- },
- {
- name: 'description',
- type: 'string',
- description: '标题下方的描述文本。',
- },
- {
- name: 'image',
- type: 'string',
- description: '正文上方显示的可选图片 URL。',
- },
- {
- name: 'imageAlt',
- type: 'string',
- description: '图片的替代文本。',
- },
- {
- name: 'linkLabel',
- type: 'string',
- description: 'CTA 链接文本。',
- },
- {
- name: 'linkHref',
- type: 'string',
- description: 'CTA 链接 URL。',
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: '标准正文下方渲染的自定义内容。',
- },
- ],
- },
- ],
usage: {
description:
'TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.',
@@ -810,107 +181,4 @@ export const docsDense = {
{name: 'Flex area', required: false, description: 'Flexible region for search, primary action buttons, or other controls.'},
],
},
- components: [
- {
- name: 'XDSTopNav',
- displayName: 'Top Nav',
- description: 'Main nav bar container w/ slot-based layout; children alias startContent.',
- propDescriptions: {
- heading: 'Heading slot (logo, brand) at left edge.',
- startContent: 'Nav items/breadcrumbs after heading, left-aligned.',
- children: 'Alias for startContent; prefer startContent with other slots.',
- centerContent: 'Center slot (tabs, search); switches to 3-column CSS grid for true centering.',
- endContent: 'Search/icons/profile at right edge.',
- label: 'A11y label for nav landmark, aria-label on <nav>.',
- xstyle: 'StyleX layout styles (margins, positioning). Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSTopNavHeading',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Heading',
- description: 'Product/suite heading for XDSTopNav; logo+heading text w/ smart interaction boundaries, optional menu popover, superheading/subheading w/ independent links.',
- propDescriptions: {
- logo: 'Logo before heading text. Image, XDSNavIcon, or ReactNode.',
- heading: 'Product/app name.',
- headingHref: 'Link for heading (product home). Only href + no menu → whole heading is link.',
- href: 'Deprecated: use headingHref.',
- superheading: 'Text above heading (suite name). Smaller secondary style.',
- superheadingHref: 'Link for superheading. Independent inline link when menu present.',
- subheading: 'Text below heading (account context). Smaller secondary style.',
- subheadingHref: 'Link for subheading. Independent inline link when menu present.',
- headerEndContent: 'Trailing edge content (badge, status indicator).',
- menu: 'Popover dropdown content. Shows chevron auto. No hrefs → whole header triggers; with hrefs → chevron area triggers.',
- as: 'Custom link component. Overrides XDSLinkProvider default. Must accept href, className, style, children.',
- xstyle: 'StyleX layout styles. Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSTopNavItem',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Item',
- description: 'Nav link for XDSTopNav startContent; renders as anchor w/ hover+selected states.',
- propDescriptions: {
- label: 'Visible text or aria-label when isIconOnly is true.',
- href: 'Navigation URL.',
- isSelected: 'Sets aria-current="page"+highlighted styles.',
- isDisabled: 'Sets aria-disabled, prevents interaction.',
- icon: 'Icon before label.',
- children: 'Custom content instead of label text.',
- as: 'Custom link component. Overrides XDSLinkProvider default. Must accept href, className, style, children.',
- },
- },
- {
- name: 'XDSTopNavMenu',
- displayName: 'Top Nav Menu',
- description: 'Nav item w/ hover-triggered popover menu containing rich items w/ icon, title, optional description.',
- propDescriptions: {
- label: 'Trigger button visible label.',
- items: 'Menu items in hover popover.',
- delay: 'Show delay ms on hover.',
- hideDelay: 'Hide delay ms after mouse leaves.',
- },
- },
- {
- name: 'XDSTopNavMegaMenu',
- displayName: 'Top Nav Mega Menu',
- description: 'Nav item w/ full-width mega menu panel on hover. Slots API w/ items+featured ReactNode props. Mobile drawer inline collapsible.',
- propDescriptions: {
- label: 'Trigger button visible label.',
- items: 'Menu items slot: typically XDSTopNavMegaMenuItem, accepts any ReactNode.',
- featured: 'Featured content slot: right panel desktop, below items in drawer.',
- delay: 'Show delay ms on hover.',
- hideDelay: 'Hide delay ms after mouse leaves.',
- onOpenChange: 'Fired on open/close. For coordinating wrapper styles.',
- },
- },
- {
- name: 'XDSTopNavMegaMenuItem',
- isHiddenFromOverview: true,
- displayName: 'Top Nav Mega Menu Item',
- description: 'Individual mega menu item. Renders in desktop popover grid + mobile drawer modes via context.',
- propDescriptions: {
- title: 'Display title.',
- description: 'Description below title.',
- icon: 'Left icon element.',
- href: 'Navigation URL.',
- onClick: 'Click callback.',
- as: 'Custom link component, overrides XDSLinkProvider default.',
- },
- },
- {
- name: 'XDSTopNavMegaMenuFeaturedCard',
- displayName: 'Top Nav Mega Menu Featured Card',
- description: 'Standard featured card for mega menu featured slot. Optional image, title, description, CTA link.',
- propDescriptions: {
- title: 'Card title.',
- description: 'Description below title.',
- image: 'Image URL above body.',
- imageAlt: 'Image alt text.',
- linkLabel: 'CTA link text.',
- linkHref: 'CTA link URL.',
- children: 'Custom content below standard body.',
- },
- },
- ],
};
diff --git a/packages/core/src/TopNav/TopNavHeading.doc.mjs b/packages/core/src/TopNav/TopNavHeading.doc.mjs
new file mode 100644
index 0000000000..0ea537587e
--- /dev/null
+++ b/packages/core/src/TopNav/TopNavHeading.doc.mjs
@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TopNavHeading',
+ subComponentOf: 'TopNav',
+ displayName: 'Top Nav Heading',
+ isHiddenFromOverview: true,
+ description: 'Product/suite/account heading for the XDSTopNav heading slot. Supports smart interaction boundary logic: logo, heading text, superheading/subheading with independent links, and an optional menu popover with automatic chevron indicator.',
+ props: [
+ {
+ name: 'logo',
+ type: 'ReactNode',
+ description: 'Logo element to display before the heading text. Can be an image, XDSNavIcon, or any ReactNode.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'heading',
+ type: 'string',
+ description: 'Product/app name displayed as the primary heading text.',
+ },
+ {
+ name: 'headingHref',
+ type: 'string',
+ description: 'Link for the heading text (e.g. product home). When no menu is present and this is the only href, the whole heading becomes one clickable link.',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'Deprecated — use headingHref instead. URL to navigate to when clicked.',
+ },
+ {
+ name: 'superheading',
+ type: 'string',
+ description: 'Text above the heading (e.g. suite name). Rendered in a smaller secondary style.',
+ },
+ {
+ name: 'superheadingHref',
+ type: 'string',
+ description: 'Link for the superheading text (e.g. suite home). When provided alongside a menu, renders as an independent inline link.',
+ },
+ {
+ name: 'subheading',
+ type: 'string',
+ description: 'Text below the heading (e.g. account context). Rendered in a smaller secondary style.',
+ },
+ {
+ name: 'subheadingHref',
+ type: 'string',
+ description: 'Link for the subheading text. When provided alongside a menu, renders as an independent inline link.',
+ },
+ {
+ name: 'headerEndContent',
+ type: 'ReactNode',
+ description: 'Content rendered at the trailing edge of the heading row (e.g. a badge or status indicator).',
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {
+ label: 'Action',
+ variant: 'ghost',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'menu',
+ type: 'ReactNode',
+ description: 'Menu content shown in a popover dropdown. When provided, a chevron indicator appears automatically. Interaction boundary is determined by the presence of hrefs: no hrefs means the whole header is the trigger; with hrefs, links are independent and the chevron area is the trigger.',
+ slotElements: [
+ {
+ __element: 'XDSButton',
+ props: {
+ label: 'Action',
+ variant: 'ghost',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: 'Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TopNavHeading',
+ isHiddenFromOverview: true,
+ displayName: 'Top Nav Heading',
+ description: 'XDSTopNav 标题插槽的产品/套件/账户标题组件。支持智能交互边界逻辑:标志、标题文本、独立链接的上标题/下标题,以及带自动箭头指示器的可选菜单弹出层。',
+ props: [
+ {
+ name: 'logo',
+ type: 'ReactNode',
+ description: '在标题文本前显示的标志元素。可以是图片、XDSNavIcon 或任何 ReactNode。',
+ },
+ {
+ name: 'heading',
+ type: 'string',
+ description: '作为主标题文本显示的产品/应用名称。',
+ },
+ {
+ name: 'headingHref',
+ type: 'string',
+ description: '标题文本的链接(如产品首页)。当没有菜单且这是唯一的 href 时,整个标题变为一个可点击链接。',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: '已弃用 — 请使用 headingHref。点击时导航到的 URL。',
+ },
+ {
+ name: 'superheading',
+ type: 'string',
+ description: '标题上方的文本(如套件名称)。以较小的次要样式渲染。',
+ },
+ {
+ name: 'superheadingHref',
+ type: 'string',
+ description: '上标题文本的链接(如套件首页)。与菜单一起提供时,渲染为独立的内联链接。',
+ },
+ {
+ name: 'subheading',
+ type: 'string',
+ description: '标题下方的文本(如账户上下文)。以较小的次要样式渲染。',
+ },
+ {
+ name: 'subheadingHref',
+ type: 'string',
+ description: '下标题文本的链接。与菜单一起提供时,渲染为独立的内联链接。',
+ },
+ {
+ name: 'headerEndContent',
+ type: 'ReactNode',
+ description: '在标题行尾部渲染的内容(如徽章或状态指示器)。',
+ },
+ {
+ name: 'menu',
+ type: 'ReactNode',
+ description: '在弹出层下拉菜单中显示的菜单内容。提供时自动显示箭头指示器。交互边界由 href 的存在决定:没有 href 时整个标题为触发器;有 href 时链接独立,箭头区域为触发器。',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: '用于替代 <a> 的自定义链接组件。覆盖 XDSLinkProvider 设置的默认组件。必须接受 href、className、style 和 children 属性。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TopNavHeading',
+ isHiddenFromOverview: true,
+ displayName: 'Top Nav Heading',
+ description: 'Product/suite heading for XDSTopNav; logo+heading text w/ smart interaction boundaries, optional menu popover, superheading/subheading w/ independent links.',
+ propDescriptions: {
+ logo: 'Logo before heading text. Image, XDSNavIcon, or ReactNode.',
+ heading: 'Product/app name.',
+ headingHref: 'Link for heading (product home). Only href + no menu → whole heading is link.',
+ href: 'Deprecated — use headingHref.',
+ superheading: 'Text above heading (suite name). Smaller secondary style.',
+ superheadingHref: 'Link for superheading. Independent inline link when menu present.',
+ subheading: 'Text below heading (account context). Smaller secondary style.',
+ subheadingHref: 'Link for subheading. Independent inline link when menu present.',
+ headerEndContent: 'Trailing edge content (badge, status indicator).',
+ menu: 'Popover dropdown content. Shows chevron auto. No hrefs → whole header triggers; with hrefs → chevron area triggers.',
+ as: 'Custom link component. Overrides XDSLinkProvider default. Must accept href, className, style, children.',
+ xstyle: 'StyleX layout styles. Must be stylex.create() value.',
+ },
+};
diff --git a/packages/core/src/TopNav/TopNavItem.doc.mjs b/packages/core/src/TopNav/TopNavItem.doc.mjs
new file mode 100644
index 0000000000..4691e7836a
--- /dev/null
+++ b/packages/core/src/TopNav/TopNavItem.doc.mjs
@@ -0,0 +1,129 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TopNavItem',
+ subComponentOf: 'TopNav',
+ displayName: 'Top Nav Item',
+ isHiddenFromOverview: true,
+ description: 'Navigation link item for use in XDSTopNav startContent — renders as an anchor with hover and selected states.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the nav item. Rendered as visible text by default. When isIconOnly is true, used as aria-label instead.',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'Navigation target URL.',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: 'Whether this nav item is currently selected. Sets aria-current="page" and applies highlighted styles.',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the nav item is disabled. Sets aria-disabled and prevents interaction.',
+ default: 'false',
+ },
+ {
+ name: 'isIconOnly',
+ type: 'boolean',
+ description: 'Renders the item as a square icon-only element. When true, label becomes the aria-label and visible text is hidden. Requires icon to be set.',
+ default: 'false',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Optional icon to display before the label.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Custom content to render instead of the label text.',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: 'Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TopNavItem',
+ isHiddenFromOverview: true,
+ displayName: 'Top Nav Item',
+ description: '用于 XDSTopNav startContent 的导航链接项 — 渲染为具有悬停和选中状态的锚点。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '导航项的无障碍标签。用作可见文本,或作为仅图标项的 aria-label。',
+ required: true,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: '导航目标 URL。',
+ },
+ {
+ name: 'isSelected',
+ type: 'boolean',
+ description: '此导航项是否为当前选中状态。设置 aria-current="page" 并应用高亮样式。',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '导航项是否被禁用。设置 aria-disabled 并阻止交互。',
+ default: 'false',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: '在标签前显示的可选图标。如果在没有子元素的情况下提供,项目变为仅图标模式。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '替代标签文本渲染的自定义内容。省略且提供了图标时,项目变为仅图标模式。',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: '替代 <a> 渲染的自定义组件。覆盖 XDSLinkProvider 设置的提供者级别默认值。必须接受 href、className、style 和 children 属性。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TopNavItem',
+ isHiddenFromOverview: true,
+ displayName: 'Top Nav Item',
+ description: 'Nav link for XDSTopNav startContent; renders as anchor w/ hover+selected states.',
+ propDescriptions: {
+ label: 'Visible text or aria-label when isIconOnly is true.',
+ href: 'Navigation URL.',
+ isSelected: 'Sets aria-current="page"+highlighted styles.',
+ isDisabled: 'Sets aria-disabled, prevents interaction.',
+ icon: 'Icon before label.',
+ children: 'Custom content instead of label text.',
+ as: 'Custom link component. Overrides XDSLinkProvider default. Must accept href, className, style, children.',
+ },
+};
diff --git a/packages/core/src/TopNav/TopNavMegaMenu.doc.mjs b/packages/core/src/TopNav/TopNavMegaMenu.doc.mjs
new file mode 100644
index 0000000000..e0130fbf85
--- /dev/null
+++ b/packages/core/src/TopNav/TopNavMegaMenu.doc.mjs
@@ -0,0 +1,118 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TopNavMegaMenu',
+ subComponentOf: 'TopNav',
+ displayName: 'Top Nav Mega Menu',
+ description: 'Navigation item that displays a full-width mega menu panel on hover. Uses a slots API with items and featured props. XDSTopNavMegaMenuItem renders itself in both desktop and mobile drawer modes. Supports inline collapsible drawer via render mode context.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Visible label for the trigger button.',
+ required: true,
+ },
+ {
+ name: 'items',
+ type: 'ReactNode',
+ description: 'Menu items slot — typically XDSTopNavMegaMenuItem components, but accepts any ReactNode.',
+ slotElements: [
+ {
+ __element: 'XDSTopNavItem',
+ props: {
+ label: 'Item',
+ href: '#',
+ },
+ },
+ ],
+ },
+ {
+ name: 'featured',
+ type: 'ReactNode',
+ description: 'Featured content slot — rendered in the right panel on desktop, below items in the mobile drawer.',
+ slotElements: [
+ {
+ __element: 'XDSCard',
+ props: {
+ padding: 4,
+ },
+ children: 'Featured content',
+ },
+ ],
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description: 'Delay in milliseconds before showing the menu on hover.',
+ default: '150',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description: 'Delay in milliseconds before hiding the menu after the mouse leaves.',
+ default: '250',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback fired when the mega menu opens or closes. Useful for coordinating wrapper styles.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TopNavMegaMenu',
+ displayName: 'Top Nav Mega Menu',
+ description: '导航项,在悬停时显示全宽超级菜单面板。使用插槽 API(items 和 featured)。XDSTopNavMegaMenuItem 在桌面和移动抽屉模式中自行渲染。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '触发按钮的可见标签。',
+ required: true,
+ },
+ {
+ name: 'items',
+ type: 'ReactNode',
+ description: '菜单项插槽 — 通常为 XDSTopNavMegaMenuItem 组件,但接受任何 ReactNode。',
+ },
+ {
+ name: 'featured',
+ type: 'ReactNode',
+ description: '特色内容插槽 — 桌面端显示在右侧面板,移动抽屉中显示在项目下方。',
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description: '悬停时显示菜单前的延迟(毫秒)。',
+ default: '150',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description: '鼠标离开后隐藏菜单的延迟(毫秒)。',
+ default: '250',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: '超级菜单打开或关闭时触发的回调。用于协调包装器样式。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TopNavMegaMenu',
+ displayName: 'Top Nav Mega Menu',
+ description: 'Nav item w/ full-width mega menu panel on hover. Slots API w/ items+featured ReactNode props. Mobile drawer inline collapsible.',
+ propDescriptions: {
+ label: 'Trigger button visible label.',
+ items: 'Menu items slot — typically XDSTopNavMegaMenuItem, accepts any ReactNode.',
+ featured: 'Featured content slot — right panel desktop, below items in drawer.',
+ delay: 'Show delay ms on hover.',
+ hideDelay: 'Hide delay ms after mouse leaves.',
+ onOpenChange: 'Fired on open/close. For coordinating wrapper styles.',
+ },
+};
diff --git a/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs b/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs
new file mode 100644
index 0000000000..93149a1f22
--- /dev/null
+++ b/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs
@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TopNavMegaMenuFeaturedCard',
+ subComponentOf: 'TopNav',
+ displayName: 'Top Nav Mega Menu Featured Card',
+ description: 'Standard featured card for the XDSTopNavMegaMenu featured slot. Provides a consistent card with optional image, title, description, and CTA link.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Card title.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text below the title.',
+ },
+ {
+ name: 'image',
+ type: 'string',
+ description: 'Optional image URL displayed above the body.',
+ },
+ {
+ name: 'imageAlt',
+ type: 'string',
+ description: 'Alt text for the image.',
+ },
+ {
+ name: 'linkLabel',
+ type: 'string',
+ description: 'CTA link text.',
+ },
+ {
+ name: 'linkHref',
+ type: 'string',
+ description: 'CTA link URL.',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Custom content rendered below the standard body.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TopNavMegaMenuFeaturedCard',
+ displayName: 'Top Nav Mega Menu Featured Card',
+ description: '超级菜单 featured 插槽的标准特色卡片。提供带可选图片、标题、描述和 CTA 链接的一致卡片。',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: '卡片标题。',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: '标题下方的描述文本。',
+ },
+ {
+ name: 'image',
+ type: 'string',
+ description: '正文上方显示的可选图片 URL。',
+ },
+ {
+ name: 'imageAlt',
+ type: 'string',
+ description: '图片的替代文本。',
+ },
+ {
+ name: 'linkLabel',
+ type: 'string',
+ description: 'CTA 链接文本。',
+ },
+ {
+ name: 'linkHref',
+ type: 'string',
+ description: 'CTA 链接 URL。',
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '标准正文下方渲染的自定义内容。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TopNavMegaMenuFeaturedCard',
+ displayName: 'Top Nav Mega Menu Featured Card',
+ description: 'Standard featured card for mega menu featured slot. Optional image, title, description, CTA link.',
+ propDescriptions: {
+ title: 'Card title.',
+ description: 'Description below title.',
+ image: 'Image URL above body.',
+ imageAlt: 'Image alt text.',
+ linkLabel: 'CTA link text.',
+ linkHref: 'CTA link URL.',
+ children: 'Custom content below standard body.',
+ },
+};
diff --git a/packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs b/packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs
new file mode 100644
index 0000000000..47a313564d
--- /dev/null
+++ b/packages/core/src/TopNav/TopNavMegaMenuItem.doc.mjs
@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TopNavMegaMenuItem',
+ subComponentOf: 'TopNav',
+ displayName: 'Top Nav Mega Menu Item',
+ isHiddenFromOverview: true,
+ description: 'An individual item inside an XDSTopNavMegaMenu. Renders itself in both desktop (popover grid) and mobile drawer modes via render mode context.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'Display title for the menu item.',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Optional description text displayed below the title.',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Optional icon element displayed to the left.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'URL to navigate to when clicked.',
+ },
+ {
+ name: 'onClick',
+ type: '() => void',
+ description: 'Callback when item is clicked.',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: 'Custom component to render instead of <a> for link items. Overrides the provider-level default set by XDSLinkProvider.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TopNavMegaMenuItem',
+ isHiddenFromOverview: true,
+ displayName: 'Top Nav Mega Menu Item',
+ description: '超级菜单中的单个项目。在桌面端(弹出层网格)和移动抽屉模式中都会自行渲染。',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: '菜单项的显示标题。',
+ required: true,
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: '标题下方的可选描述文本。',
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: '左侧显示的可选图标元素。',
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: '点击时导航的 URL。',
+ },
+ {
+ name: 'onClick',
+ type: '() => void',
+ description: '点击项目时的回调。',
+ },
+ {
+ name: 'as',
+ type: 'XDSLinkComponentType',
+ description: '用于替代 <a> 的自定义链接组件。覆盖 XDSLinkProvider 设置的默认组件。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TopNavMegaMenuItem',
+ isHiddenFromOverview: true,
+ displayName: 'Top Nav Mega Menu Item',
+ description: 'Individual mega menu item. Renders in desktop popover grid + mobile drawer modes via context.',
+ propDescriptions: {
+ title: 'Display title.',
+ description: 'Description below title.',
+ icon: 'Left icon element.',
+ href: 'Navigation URL.',
+ onClick: 'Click callback.',
+ as: 'Custom link component, overrides XDSLinkProvider default.',
+ },
+};
diff --git a/packages/core/src/TopNav/TopNavMenu.doc.mjs b/packages/core/src/TopNav/TopNavMenu.doc.mjs
new file mode 100644
index 0000000000..17be75b770
--- /dev/null
+++ b/packages/core/src/TopNav/TopNavMenu.doc.mjs
@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TopNavMenu',
+ subComponentOf: 'TopNav',
+ displayName: 'Top Nav Menu',
+ description: 'Navigation item that displays a hover-triggered popover menu with rich items containing an icon, title, and optional description.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Visible label for the trigger button.',
+ required: true,
+ },
+ {
+ name: 'items',
+ type: 'XDSTopNavMenuItemData[]',
+ description: 'Menu items to display in the hover popover.',
+ required: true,
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description: 'Delay in milliseconds before showing the menu on hover.',
+ default: '150',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description: 'Delay in milliseconds before hiding the menu after the mouse leaves.',
+ default: '200',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TopNavMenu',
+ displayName: 'Top Nav Menu',
+ description: '导航项,在悬停时显示弹出菜单,包含带图标、标题和可选描述的丰富菜单项。',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: '触发按钮的可见标签。',
+ required: true,
+ },
+ {
+ name: 'items',
+ type: 'XDSTopNavMenuItemData[]',
+ description: '在悬停弹出框中显示的菜单项。',
+ required: true,
+ },
+ {
+ name: 'delay',
+ type: 'number',
+ description: '悬停时显示菜单前的延迟(毫秒)。',
+ default: '150',
+ },
+ {
+ name: 'hideDelay',
+ type: 'number',
+ description: '鼠标离开后隐藏菜单的延迟(毫秒)。',
+ default: '200',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TopNavMenu',
+ displayName: 'Top Nav Menu',
+ description: 'Nav item w/ hover-triggered popover menu containing rich items w/ icon, title, optional description.',
+ propDescriptions: {
+ label: 'Trigger button visible label.',
+ items: 'Menu items in hover popover.',
+ delay: 'Show delay ms on hover.',
+ hideDelay: 'Hide delay ms after mouse leaves.',
+ },
+};
diff --git a/packages/core/src/Typeahead/BaseTypeahead.doc.mjs b/packages/core/src/Typeahead/BaseTypeahead.doc.mjs
new file mode 100644
index 0000000000..29f7b64c2e
--- /dev/null
+++ b/packages/core/src/Typeahead/BaseTypeahead.doc.mjs
@@ -0,0 +1,249 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'BaseTypeahead',
+ subComponentOf: 'Typeahead',
+ displayName: 'Base Typeahead',
+ isHiddenFromOverview: true,
+ description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by XDSTypeahead and XDSTokenizer for custom compositions.',
+ props: [
+ {
+ name: 'searchSource',
+ type: 'XDSSearchSource<T>',
+ description: 'Data source providing search and bootstrap methods.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'T | null',
+ description: 'Currently selected item.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(item: T | null) => void',
+ description: 'Called when the selection changes.',
+ required: true,
+ },
+ {
+ name: 'renderItem',
+ type: '(item: T) => ReactNode',
+ description: 'Custom render function for dropdown items.',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Input placeholder text.',
+ default: "'Search...'",
+ },
+ {
+ name: 'hasEntriesOnFocus',
+ type: 'boolean',
+ description: 'Show bootstrap results on focus before typing.',
+ default: 'false',
+ },
+ {
+ name: 'maxMenuItems',
+ type: 'number',
+ description: 'Maximum dropdown items to display.',
+ default: '10',
+ },
+ {
+ name: 'emptySearchResultsText',
+ type: 'string',
+ description: 'Text shown when search returns no results.',
+ default: "'No results found'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether the input is disabled.',
+ default: 'false',
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Auto-focus the input on mount.',
+ default: 'false',
+ },
+ {
+ name: 'debounceMs',
+ type: 'number',
+ description: 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
+ default: '150',
+ },
+ {
+ name: 'anchorRef',
+ type: 'RefObject<HTMLElement | null>',
+ description: 'Ref to the anchor element for dropdown positioning. If not provided, the input itself is used.',
+ },
+ {
+ name: 'inputXStyle',
+ type: 'StyleXStyles',
+ description: 'Additional StyleX styles for the input element.',
+ },
+ {
+ name: 'onKeyDown',
+ type: '(e: React.KeyboardEvent<HTMLInputElement>) => void',
+ description: 'Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling.',
+ },
+ {
+ name: 'onChangeQuery',
+ type: '(query: string) => void',
+ description: 'Callback fired when the search query text changes.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback when the dropdown opens or closes.',
+ },
+ {
+ name: 'inputId',
+ type: 'string',
+ description: 'ID for the input element (for label association).',
+ },
+ {
+ name: 'ariaDescribedBy',
+ type: 'string',
+ description: 'Additional aria-describedby IDs.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'BaseTypeahead',
+ isHiddenFromOverview: true,
+ displayName: 'Base Typeahead',
+ description: '无样式的组合框引擎,提供输入、搜索、键盘导航和下拉列表。无包装 div,无边框样式,无标记渲染。由 XDSTypeahead 和 XDSTokenizer 用于自定义组合。',
+ props: [
+ {
+ name: 'searchSource',
+ type: 'XDSSearchSource<T>',
+ description: '提供搜索和引导方法的数据源。',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'T | null',
+ description: '当前选中的项目。',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(item: T | null) => void',
+ description: '选择变更时调用。',
+ required: true,
+ },
+ {
+ name: 'renderItem',
+ type: '(item: T) => ReactNode',
+ description: '下拉列表项的自定义渲染函数。',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: '输入框占位文本。',
+ default: "'Search...'",
+ },
+ {
+ name: 'hasEntriesOnFocus',
+ type: 'boolean',
+ description: '聚焦时在输入前显示引导结果。',
+ default: 'false',
+ },
+ {
+ name: 'maxMenuItems',
+ type: 'number',
+ description: '下拉列表显示的最大项目数。',
+ default: '10',
+ },
+ {
+ name: 'emptySearchResultsText',
+ type: 'string',
+ description: '搜索无结果时显示的文本。',
+ default: "'No results found'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '输入框是否被禁用。',
+ default: 'false',
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: '挂载时自动聚焦输入框。',
+ default: 'false',
+ },
+ {
+ name: 'debounceMs',
+ type: 'number',
+ description: '触发搜索前的防抖延迟(毫秒)。同步数据源设置为 0。',
+ default: '150',
+ },
+ {
+ name: 'anchorRef',
+ type: 'RefObject<HTMLElement | null>',
+ description: '用于下拉列表定位的锚点元素引用。未提供时使用输入框本身。',
+ },
+ {
+ name: 'inputXStyle',
+ type: 'StyleXStyles',
+ description: '输入元素的附加 StyleX 样式。',
+ },
+ {
+ name: 'onKeyDown',
+ type: '(e: React.KeyboardEvent<HTMLInputElement>) => void',
+ description: '在内部键盘导航之前调用的附加 keydown 处理函数。调用 e.preventDefault() 可跳过内部处理。',
+ },
+ {
+ name: 'onChangeQuery',
+ type: '(query: string) => void',
+ description: '搜索查询文本变更时触发的回调。',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: '下拉列表打开或关闭时的回调。',
+ },
+ {
+ name: 'inputId',
+ type: 'string',
+ description: '输入元素的 ID(用于标签关联)。',
+ },
+ {
+ name: 'ariaDescribedBy',
+ type: 'string',
+ description: '附加的 aria-describedby ID。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'BaseTypeahead',
+ isHiddenFromOverview: true,
+ displayName: 'Base Typeahead',
+ description: 'Unstyled combobox engine; input+search+keyboard nav+dropdown. No wrapper/border/token. Used by XDSTypeahead+XDSTokenizer.',
+ propDescriptions: {
+ searchSource: 'Data source w/ search+bootstrap methods.',
+ value: 'Currently selected item.',
+ onChange: 'Fired on selection change.',
+ renderItem: 'Custom dropdown item render.',
+ placeholder: 'Input placeholder.',
+ hasEntriesOnFocus: 'Bootstrap results on focus.',
+ maxMenuItems: 'Max dropdown items.',
+ emptySearchResultsText: 'Text when no results.',
+ isDisabled: 'Whether input disabled.',
+ hasAutoFocus: 'Auto-focus on mount.',
+ debounceMs: 'Search debounce ms. 0 for sync.',
+ anchorRef: 'Anchor for dropdown positioning. Defaults to input.',
+ inputXStyle: 'Additional StyleX styles for input.',
+ onKeyDown: 'Keydown before internal nav. preventDefault() skips internal handling.',
+ onChangeQuery: 'Fired on query text change.',
+ onOpenChange: 'Fired on dropdown open/close.',
+ inputId: 'Input ID for label association.',
+ ariaDescribedBy: 'Additional aria-describedby IDs.',
+ },
+};
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index e7f2247ceb..78c9a3d883 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -8,298 +8,142 @@ export const docs = {
group: 'Typeahead',
category: 'Data Input',
keywords: ["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],
- components: [
+ description: 'Styled typeahead with label, description, validation, and all field features. Wraps XDSBaseTypeahead with XDSField for the primary use case.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Accessible label for the input.',
+ required: true,
+ },
+ {
+ name: 'searchSource',
+ type: 'XDSSearchSource<T>',
+ description: 'Data source providing search and bootstrap methods for populating the dropdown.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'T | null',
+ description: 'Currently selected item, or null if nothing is selected.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(item: T | null) => void',
+ description: 'Called when the selection changes.',
+ required: true,
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Input placeholder text.',
+ },
+ {
+ name: 'hasEntriesOnFocus',
+ type: 'boolean',
+ description: 'Show bootstrap results on focus before typing.',
+ default: 'false',
+ },
+ {
+ name: 'hasClear',
+ type: 'boolean',
+ description: 'Show clear button to deselect the current value.',
+ default: 'true',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the input.',
+ default: 'false',
+ },
+ {
+ name: 'maxMenuItems',
+ type: 'number',
+ description: 'Maximum number of dropdown items to display.',
+ default: '10',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description: 'Validation status object with type and message for error/warning/success states.',
+ },
+ {
+ name: 'renderItem',
+ type: '(item: T) => ReactNode',
+ description: 'Custom render function for dropdown items. Default renders XDSTypeaheadItem.',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hides the label while keeping it accessible.',
+ default: 'false',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Helper text displayed below the label.',
+ },
{
- name: 'XDSTypeahead',
- displayName: 'Typeahead',
- description:
- 'Styled typeahead with label, description, validation, and all field features. Wraps XDSBaseTypeahead with XDSField for the primary use case.',
- props: [
- {
- name: 'label',
- type: 'string',
- description: 'Accessible label for the input.',
- required: true,
- },
- {
- name: 'searchSource',
- type: 'XDSSearchSource<T>',
- description:
- 'Data source providing search and bootstrap methods for populating the dropdown.',
- required: true,
- },
- {
- name: 'value',
- type: 'T | null',
- description:
- 'Currently selected item, or null if nothing is selected.',
- required: true,
- },
- {
- name: 'onChange',
- type: '(item: T | null) => void',
- description: 'Called when the selection changes.',
- required: true,
- },
- {
- name: 'placeholder',
- type: 'string',
- description: 'Input placeholder text.',
- },
- {
- name: 'hasEntriesOnFocus',
- type: 'boolean',
- description: 'Show bootstrap results on focus before typing.',
- default: 'false',
- },
- {
- name: 'hasClear',
- type: 'boolean',
- description: 'Show clear button to deselect the current value.',
- default: 'true',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Disables the input.',
- default: 'false',
- },
- {
- name: 'maxMenuItems',
- type: 'number',
- description: 'Maximum number of dropdown items to display.',
- default: '10',
- },
- {
- name: 'status',
- type: 'XDSInputStatus',
- description:
- 'Validation status object with type and message for error/warning/success states.',
- },
- {
- name: 'renderItem',
- type: '(item: T) => ReactNode',
- description:
- 'Custom render function for dropdown items. Default renders XDSTypeaheadItem.',
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: 'Visually hides the label while keeping it accessible.',
- default: 'false',
- },
- {
- name: 'description',
- type: 'string',
- description: 'Helper text displayed below the label.',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description: 'Marks the field as required.',
- default: 'false',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description: 'Shows an optional indicator on the label.',
- default: 'false',
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description: 'Tooltip text shown on the label.',
- },
- {
- name: 'emptySearchResultsText',
- type: 'string',
- description: 'Text shown when search returns no results.',
- default: "'No results found'",
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: 'Auto-focus the input on mount.',
- default: 'false',
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: 'Input and token size.',
- default: "'md'",
- },
- {
- name: 'debounceMs',
- type: 'number',
- description:
- 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
- default: '150',
- },
- {
- name: 'onChangeQuery',
- type: '(query: string) => void',
- description: 'Callback fired when the search query text changes.',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description: 'Callback when the dropdown opens or closes.',
- },
- {
- 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={{}}.',
- },
- ], },
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Marks the field as required.',
+ default: 'false',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Shows an optional indicator on the label.',
+ default: 'false',
+ },
+ {
+ name: 'labelTooltip',
+ type: 'string',
+ description: 'Tooltip text shown on the label.',
+ },
+ {
+ name: 'emptySearchResultsText',
+ type: 'string',
+ description: 'Text shown when search returns no results.',
+ default: "'No results found'",
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: 'Auto-focus the input on mount.',
+ default: 'false',
+ },
{
- name: 'XDSBaseTypeahead',
- isHiddenFromOverview: true,
- displayName: 'Base Typeahead',
- description:
- 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by XDSTypeahead and XDSTokenizer for custom compositions.',
- props: [
- {
- name: 'searchSource',
- type: 'XDSSearchSource<T>',
- description: 'Data source providing search and bootstrap methods.',
- required: true,
- },
- {
- name: 'value',
- type: 'T | null',
- description: 'Currently selected item.',
- required: true,
- },
- {
- name: 'onChange',
- type: '(item: T | null) => void',
- description: 'Called when the selection changes.',
- required: true,
- },
- {
- name: 'renderItem',
- type: '(item: T) => ReactNode',
- description: 'Custom render function for dropdown items.',
- },
- {
- name: 'placeholder',
- type: 'string',
- description: 'Input placeholder text.',
- default: "'Search...'",
- },
- {
- name: 'hasEntriesOnFocus',
- type: 'boolean',
- description: 'Show bootstrap results on focus before typing.',
- default: 'false',
- },
- {
- name: 'maxMenuItems',
- type: 'number',
- description: 'Maximum dropdown items to display.',
- default: '10',
- },
- {
- name: 'emptySearchResultsText',
- type: 'string',
- description: 'Text shown when search returns no results.',
- default: "'No results found'",
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether the input is disabled.',
- default: 'false',
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: 'Auto-focus the input on mount.',
- default: 'false',
- },
- {
- name: 'debounceMs',
- type: 'number',
- description:
- 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
- default: '150',
- },
- {
- name: 'anchorRef',
- type: 'RefObject<HTMLElement | null>',
- description:
- 'Ref to the anchor element for dropdown positioning. If not provided, the input itself is used.',
- },
- {
- name: 'inputXStyle',
- type: 'StyleXStyles',
- description: 'Additional StyleX styles for the input element.',
- },
- {
- name: 'onKeyDown',
- type: '(e: React.KeyboardEvent<HTMLInputElement>) => void',
- description:
- 'Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling.',
- },
- {
- name: 'onChangeQuery',
- type: '(query: string) => void',
- description: 'Callback fired when the search query text changes.',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description: 'Callback when the dropdown opens or closes.',
- },
- {
- name: 'inputId',
- type: 'string',
- description: 'ID for the input element (for label association).',
- },
- {
- name: 'ariaDescribedBy',
- type: 'string',
- description: 'Additional aria-describedby IDs.',
- },
- ],
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Input and token size.',
+ default: "'md'",
},
{
- name: 'XDSTypeaheadItem',
- displayName: 'Typeahead Item',
- description:
- 'Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.',
- props: [
- {
- name: 'item',
- type: 'XDSSearchableItem',
- description: 'The search result item to render.',
- required: true,
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: 'Icon or avatar to display before the label.',
- slotElements: [{__element: 'XDSIcon', props: {icon: 'check', size: 'sm'}}],
- },
- {
- name: 'description',
- type: 'string',
- description: 'Description text displayed below the label.',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: 'Whether this item is visually disabled.',
- default: 'false',
- },
- {
- name: 'group',
- type: 'string',
- description: 'Group label for grouping items visually.',
- },
- ],
+ name: 'debounceMs',
+ type: 'number',
+ description: 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
+ default: '150',
},
+ {
+ name: 'onChangeQuery',
+ type: '(query: string) => void',
+ description: 'Callback fired when the search query text changes.',
+ },
+ {
+ name: 'onOpenChange',
+ type: '(isOpen: boolean) => void',
+ description: 'Callback when the dropdown opens or closes.',
+ },
+ {
+ 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={{}}.',
+ },
+ ],
+ components: [
+ {name: 'XDSBaseTypeahead'},
+ {name: 'XDSTypeaheadItem'},
],
theming: {
targets: [
@@ -322,310 +166,8 @@ export const docs = {
},
};
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
- name: 'Typeahead',
- displayName: 'Typeahead',
- components: [
- {
- name: 'XDSTypeahead',
- displayName: 'Typeahead',
- description:
- '带有标签、描述、验证和所有字段功能的样式化预输入组件。使用 XDSField 包裹 XDSBaseTypeahead,适用于主要用例。',
- props: [
- {
- name: 'label',
- type: 'string',
- description: '输入框的无障碍标签。',
- required: true,
- },
- {
- name: 'searchSource',
- type: 'XDSSearchSource<T>',
- description:
- '提供搜索和引导方法的数据源,用于填充下拉列表。',
- required: true,
- },
- {
- name: 'value',
- type: 'T | null',
- description:
- '当前选中的项目,未选择时为 null。',
- required: true,
- },
- {
- name: 'onChange',
- type: '(item: T | null) => void',
- description: '选择变更时调用。',
- required: true,
- },
- {
- name: 'placeholder',
- type: 'string',
- description: '输入框占位文本。',
- },
- {
- name: 'hasEntriesOnFocus',
- type: 'boolean',
- description: '聚焦时在输入前显示引导结果。',
- default: 'false',
- },
- {
- name: 'hasClear',
- type: 'boolean',
- description: '显示清除按钮以取消选择当前值。',
- default: 'true',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '禁用输入框。',
- default: 'false',
- },
- {
- name: 'maxMenuItems',
- type: 'number',
- description: '下拉列表显示的最大项目数。',
- default: '10',
- },
- {
- name: 'status',
- type: 'XDSInputStatus',
- description:
- '验证状态对象,包含类型和消息,用于错误/警告/成功状态。',
- },
- {
- name: 'renderItem',
- type: '(item: T) => ReactNode',
- description:
- '下拉列表项的自定义渲染函数。默认渲染 XDSTypeaheadItem。',
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description: '视觉隐藏标签,同时保持其可访问性。',
- default: 'false',
- },
- {
- name: 'description',
- type: 'string',
- description: '显示在标签下方的辅助文本。',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description: '将字段标记为必填。',
- default: 'false',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description: '在标签上显示可选指示器。',
- default: 'false',
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description: '标签上显示的工具提示文本。',
- },
- {
- name: 'emptySearchResultsText',
- type: 'string',
- description: '搜索无结果时显示的文本。',
- default: "'No results found'",
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: '挂载时自动聚焦输入框。',
- default: 'false',
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: '输入框和标记的尺寸。',
- default: "'md'",
- },
- {
- name: 'debounceMs',
- type: 'number',
- description:
- '触发搜索前的防抖延迟(毫秒)。同步数据源设置为 0。',
- default: '150',
- },
- {
- name: 'onChangeQuery',
- type: '(query: string) => void',
- description: '搜索查询文本变更时触发的回调。',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description: '下拉列表打开或关闭时的回调。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,不能是内联样式对象如 style={{}}。',
- },
- ],
- },
- {
- name: 'XDSBaseTypeahead',
- isHiddenFromOverview: true,
- displayName: 'Base Typeahead',
- description:
- '无样式的组合框引擎,提供输入、搜索、键盘导航和下拉列表。无包装 div,无边框样式,无标记渲染。由 XDSTypeahead 和 XDSTokenizer 用于自定义组合。',
- props: [
- {
- name: 'searchSource',
- type: 'XDSSearchSource<T>',
- description: '提供搜索和引导方法的数据源。',
- required: true,
- },
- {
- name: 'value',
- type: 'T | null',
- description: '当前选中的项目。',
- required: true,
- },
- {
- name: 'onChange',
- type: '(item: T | null) => void',
- description: '选择变更时调用。',
- required: true,
- },
- {
- name: 'renderItem',
- type: '(item: T) => ReactNode',
- description: '下拉列表项的自定义渲染函数。',
- },
- {
- name: 'placeholder',
- type: 'string',
- description: '输入框占位文本。',
- default: "'Search...'",
- },
- {
- name: 'hasEntriesOnFocus',
- type: 'boolean',
- description: '聚焦时在输入前显示引导结果。',
- default: 'false',
- },
- {
- name: 'maxMenuItems',
- type: 'number',
- description: '下拉列表显示的最大项目数。',
- default: '10',
- },
- {
- name: 'emptySearchResultsText',
- type: 'string',
- description: '搜索无结果时显示的文本。',
- default: "'No results found'",
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '输入框是否被禁用。',
- default: 'false',
- },
- {
- name: 'hasAutoFocus',
- type: 'boolean',
- description: '挂载时自动聚焦输入框。',
- default: 'false',
- },
- {
- name: 'debounceMs',
- type: 'number',
- description:
- '触发搜索前的防抖延迟(毫秒)。同步数据源设置为 0。',
- default: '150',
- },
- {
- name: 'anchorRef',
- type: 'RefObject<HTMLElement | null>',
- description:
- '用于下拉列表定位的锚点元素引用。未提供时使用输入框本身。',
- },
- {
- name: 'inputXStyle',
- type: 'StyleXStyles',
- description: '输入元素的附加 StyleX 样式。',
- },
- {
- name: 'onKeyDown',
- type: '(e: React.KeyboardEvent<HTMLInputElement>) => void',
- description:
- '在内部键盘导航之前调用的附加 keydown 处理函数。调用 e.preventDefault() 可跳过内部处理。',
- },
- {
- name: 'onChangeQuery',
- type: '(query: string) => void',
- description: '搜索查询文本变更时触发的回调。',
- },
- {
- name: 'onOpenChange',
- type: '(isOpen: boolean) => void',
- description: '下拉列表打开或关闭时的回调。',
- },
- {
- name: 'inputId',
- type: 'string',
- description: '输入元素的 ID(用于标签关联)。',
- },
- {
- name: 'ariaDescribedBy',
- type: 'string',
- description: '附加的 aria-describedby ID。',
- },
- ],
- },
- {
- name: 'XDSTypeaheadItem',
- displayName: 'Typeahead Item',
- description:
- '预输入结果的默认下拉项渲染器。显示标签以及可选的图标、描述和头像。导出供自定义 renderItem 实现使用。',
- props: [
- {
- name: 'item',
- type: 'XDSSearchableItem',
- description: '要渲染的搜索结果项。',
- required: true,
- },
- {
- name: 'icon',
- type: 'ReactNode',
- description: '在标签前显示的图标或头像。',
- },
- {
- name: 'description',
- type: 'string',
- description: '显示在标签下方的描述文本。',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '此项是否在视觉上被禁用。',
- default: 'false',
- },
- {
- name: 'group',
- type: 'string',
- description: '用于视觉分组的分组标签。',
- },
- ],
- },
- ],
- theming: {
- targets: [
- {className: 'xds-typeahead', visualProps: ['status']},
- {className: 'xds-typeahead-dropdown'},
- {className: 'xds-typeahead-item'},
- ],
- },
usage: {
description:
'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
@@ -655,74 +197,4 @@ export const docsDense = {
{guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
- components: [
- {
- name: 'XDSTypeahead',
- displayName: 'Typeahead',
- description: 'Styled typeahead w/ label, description, validation. Wraps XDSBaseTypeahead+XDSField.',
- propDescriptions: {
- label: 'Accessible label for input.',
- searchSource: 'Data source w/ search+bootstrap methods for populating dropdown.',
- value: 'Selected item or null.',
- onChange: 'Fired on selection change.',
- placeholder: 'Input placeholder text.',
- hasEntriesOnFocus: 'Show bootstrap results on focus before typing.',
- hasClear: 'Clear button to deselect current value.',
- isDisabled: 'Disables input.',
- maxMenuItems: 'Max dropdown items to display.',
- status: 'Validation status w/ type+message for error/warning/success.',
- renderItem: 'Custom dropdown item render. Default renders XDSTypeaheadItem.',
- isLabelHidden: 'Visually hides label; keeps a11y.',
- description: 'Helper text below label.',
- isRequired: 'Marks field required.',
- isOptional: 'Shows optional indicator on label.',
- labelTooltip: 'Tooltip on label.',
- emptySearchResultsText: 'Text when search returns no results.',
- hasAutoFocus: 'Auto-focus input on mount.',
- size: 'Input+token size.',
- debounceMs: 'Search debounce ms. 0 for sync.',
- onChangeQuery: 'Fired on search query text change.',
- onOpenChange: 'Fired on dropdown open/close.',
- xstyle: 'StyleX layout styles. Must be stylex.create() value.',
- },
- },
- {
- name: 'XDSBaseTypeahead',
- isHiddenFromOverview: true,
- displayName: 'Base Typeahead',
- description: 'Unstyled combobox engine; input+search+keyboard nav+dropdown. No wrapper/border/token. Used by XDSTypeahead+XDSTokenizer.',
- propDescriptions: {
- searchSource: 'Data source w/ search+bootstrap methods.',
- value: 'Currently selected item.',
- onChange: 'Fired on selection change.',
- renderItem: 'Custom dropdown item render.',
- placeholder: 'Input placeholder.',
- hasEntriesOnFocus: 'Bootstrap results on focus.',
- maxMenuItems: 'Max dropdown items.',
- emptySearchResultsText: 'Text when no results.',
- isDisabled: 'Whether input disabled.',
- hasAutoFocus: 'Auto-focus on mount.',
- debounceMs: 'Search debounce ms. 0 for sync.',
- anchorRef: 'Anchor for dropdown positioning. Defaults to input.',
- inputXStyle: 'Additional StyleX styles for input.',
- onKeyDown: 'Keydown before internal nav. preventDefault() skips internal handling.',
- onChangeQuery: 'Fired on query text change.',
- onOpenChange: 'Fired on dropdown open/close.',
- inputId: 'Input ID for label association.',
- ariaDescribedBy: 'Additional aria-describedby IDs.',
- },
- },
- {
- name: 'XDSTypeaheadItem',
- displayName: 'Typeahead Item',
- description: 'Default dropdown item renderer. Label w/ optional icon, description, avatar. Exported for custom renderItem.',
- propDescriptions: {
- item: 'Search result item to render.',
- icon: 'Icon/avatar before label.',
- description: 'Text below label.',
- isDisabled: 'Visually disabled.',
- group: 'Group label for visual grouping.',
- },
- },
- ],
};
diff --git a/packages/core/src/Typeahead/TypeaheadItem.doc.mjs b/packages/core/src/Typeahead/TypeaheadItem.doc.mjs
new file mode 100644
index 0000000000..f4a527ab2a
--- /dev/null
+++ b/packages/core/src/Typeahead/TypeaheadItem.doc.mjs
@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'TypeaheadItem',
+ subComponentOf: 'Typeahead',
+ displayName: 'Typeahead Item',
+ description: 'Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.',
+ props: [
+ {
+ name: 'item',
+ type: 'XDSSearchableItem',
+ description: 'The search result item to render.',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: 'Icon or avatar to display before the label.',
+ slotElements: [
+ {
+ __element: 'XDSIcon',
+ props: {
+ icon: 'check',
+ size: 'sm',
+ },
+ },
+ ],
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Description text displayed below the label.',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Whether this item is visually disabled.',
+ default: 'false',
+ },
+ {
+ name: 'group',
+ type: 'string',
+ description: 'Group label for grouping items visually.',
+ },
+ ],
+};
+
+export const docsZh = {
+ name: 'TypeaheadItem',
+ displayName: 'Typeahead Item',
+ description: '预输入结果的默认下拉项渲染器。显示标签以及可选的图标、描述和头像。导出供自定义 renderItem 实现使用。',
+ props: [
+ {
+ name: 'item',
+ type: 'XDSSearchableItem',
+ description: '要渲染的搜索结果项。',
+ required: true,
+ },
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description: '在标签前显示的图标或头像。',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: '显示在标签下方的描述文本。',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '此项是否在视觉上被禁用。',
+ default: 'false',
+ },
+ {
+ name: 'group',
+ type: 'string',
+ description: '用于视觉分组的分组标签。',
+ },
+ ],
+};
+
+export const docsDense = {
+ name: 'TypeaheadItem',
+ displayName: 'Typeahead Item',
+ description: 'Default dropdown item renderer. Label w/ optional icon, description, avatar. Exported for custom renderItem.',
+ propDescriptions: {
+ item: 'Search result item to render.',
+ icon: 'Icon/avatar before label.',
+ description: 'Text below label.',
+ isDisabled: 'Visually disabled.',
+ group: 'Group label for visual grouping.',
+ },
+};
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index 02491b6519..3d0fb4da50 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -507,16 +507,60 @@ export interface SingleComponentDoc extends BaseDoc {
props: PropDoc[];
}
+/**
+ * A cross-link reference to a sub-component that lives in its own sibling
+ * `{Name}.doc.mjs` file (see {@link SubComponentDoc}). The parent's
+ * `components` array lists these names so the family stays discoverable;
+ * the entry's content is emitted from the sub-component's own file, not here.
+ */
+export interface ComponentRef {
+ /** Full export name including XDS prefix, e.g. `"XDSChatComposer"`. Must
+ * match the `name` field of the referenced sub-component's own doc. */
+ name: string;
+}
+
/**
* Documentation for a directory that exports multiple public components.
* Props live on each entry in `components`.
*
* Use this when the directory has multiple `XDS*.tsx` files
* (e.g. Table, Dialog, TabList, TopNav, Layout).
+ *
+ * Each `components` entry is either a full {@link ComponentEntry} (inline
+ * sub-component) or a name-only {@link ComponentRef} pointing at a sibling
+ * `{Name}.doc.mjs` file. The two styles can be mixed during migration.
*/
export interface MultiComponentDoc extends BaseDoc {
- /** Each public component/hook exported from this directory. */
- components: ComponentEntry[];
+ /** Each public component/hook exported from this directory — either an
+ * inline entry or a name-only reference to a sibling sub-component doc. */
+ components: (ComponentEntry | ComponentRef)[];
+}
+
+/**
+ * Documentation for a single sub-component that lives in its own
+ * `{Name}.doc.mjs` file inside its parent's directory. Identified by the
+ * `subComponentOf` field, which names the parent component.
+ *
+ * A sub-component owns its `description`, `props`, and (optionally) its own
+ * `usage`. Family-level fields (`group`, `category`, `keywords`, `theming`,
+ * `playground`) are inherited from the directory's primary doc unless
+ * overridden here. The generated registry entry is identical to the legacy
+ * inline `components[]` expansion — this is purely a file-structure change.
+ */
+export interface SubComponentDoc extends Omit<BaseDoc, 'usage'> {
+ /** Name of the parent component this sub-component belongs to, matching the
+ * parent doc's `name` (e.g. `"Chat"`). Marks this file as a sub-component
+ * doc so the pipeline parents and inherits family fields correctly. */
+ subComponentOf: string;
+ /** One-sentence description of what this sub-component does and its role
+ * within the parent composition. */
+ description: string;
+ /** All public props for this sub-component. */
+ props: PropDoc[];
+ /** Usage is optional for sub-components — when omitted, the registry entry
+ * carries the sub-component's own props/description with no usage prose
+ * (it is NOT inherited from the parent, which was the #2602 bug). */
+ usage?: UsageDoc;
}
/**
@@ -529,8 +573,13 @@ export interface MultiComponentDoc extends BaseDoc {
*
* Use SingleComponentDoc (with `props`) for single-component directories.
* Use MultiComponentDoc (with `components`) for multi-component directories.
+ * Use SubComponentDoc (with `subComponentOf`) for a sub-component that lives
+ * in its own file inside its parent's directory.
*/
-export type ComponentDoc = SingleComponentDoc | MultiComponentDoc;
+export type ComponentDoc =
+ | SingleComponentDoc
+ | MultiComponentDoc
+ | SubComponentDoc;
/**
* Translation overlay for component documentation.