An open source design system that's fully customizable and agent ready
TypeScript
unify prose fields into usage object on ComponentDoc (#1399)
Joey805729004675
diff --git a/packages/cli/src/api/component.mjs b/packages/cli/src/api/component.mjsindex 7b7d2c7df0..22794e6fd6 100644--- a/packages/cli/src/api/component.mjs+++ b/packages/cli/src/api/component.mjs@@ -77,7 +77,7 @@ export async function component(name, options = {}) {if (readme && readme.endsWith('.doc.mjs')) {try {const docs = await loadDocs(readme, {zh, lang});- entries.push({name: comp, description: docs.description, import: resolveImportPath(coreDir, comp)});+ entries.push({name: comp, description: docs.usage?.description || docs.description || '', import: resolveImportPath(coreDir, comp)});} catch {entries.push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});}@@ -102,7 +102,7 @@ export async function component(name, options = {}) {if (readme && readme.endsWith('.doc.mjs')) {try {const docs = await loadDocs(readme, {zh, lang});- result[cat].push({name: comp, description: docs.description, import: resolveImportPath(coreDir, comp)});+ result[cat].push({name: comp, description: docs.usage?.description || docs.description || '', import: resolveImportPath(coreDir, comp)});} catch {result[cat].push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});}diff --git a/packages/cli/src/api/discover.mjs b/packages/cli/src/api/discover.mjsindex c75d618632..d3be04d32b 100644--- a/packages/cli/src/api/discover.mjs+++ b/packages/cli/src/api/discover.mjs@@ -11,11 +11,10 @@ import {XDSError} from './error.mjs';function validateDocs(docs) {if (!docs || typeof docs !== 'object') return 'docs export is missing or not an object';if (typeof docs.name !== 'string' || !docs.name) return 'docs.name is missing or not a string';- if (typeof docs.description !== 'string') return 'docs.description is missing or not a string';+ if (!docs.usage || typeof docs.usage.description !== 'string') return 'docs.usage.description is missing or not a string';if (docs.props && !Array.isArray(docs.props)) return 'docs.props must be an array';if (docs.components && !Array.isArray(docs.components)) return 'docs.components must be an array';- if (docs.examples && !Array.isArray(docs.examples)) return 'docs.examples must be an array';- if (docs.features && !Array.isArray(docs.features)) return 'docs.features must be an array';+ if (docs.usage?.features && !Array.isArray(docs.usage.features)) return 'docs.usage.features must be an array';return null;}diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjsindex a140e1631f..e208fbad87 100644--- a/packages/cli/src/lib/component-format.mjs+++ b/packages/cli/src/lib/component-format.mjs@@ -106,31 +106,24 @@ export function formatFull(docs, options = {}) {const sections = [];sections.push(`# ${docs.name}\n`);- sections.push(docs.description + '\n');+ const desc = docs.usage?.description || docs.description || '';+ sections.push(desc + '\n');- if (docs.usage) {- sections.push('## Usage\n');- if (docs.usage.summary) {- sections.push(docs.usage.summary + '\n');- }- if (docs.usage.content) {- sections.push(docs.usage.content + '\n');- }- if (docs.usage.anatomy?.length) {- sections.push('### Anatomy\n');- sections.push('| Element | Required | Description |');- sections.push('|---------|----------|-------------|');- for (const el of docs.usage.anatomy) {- const req = el.required ? 'Yes' : 'No';- sections.push(`| ${el.name} | ${req} | ${el.description} |`);- }- sections.push('');+ if (docs.usage?.anatomy?.length) {+ sections.push('## Anatomy\n');+ sections.push('| Element | Required | Description |');+ sections.push('|---------|----------|-------------|');+ for (const el of docs.usage.anatomy) {+ const req = el.required ? 'Yes' : 'No';+ sections.push(`| ${el.name} | ${req} | ${el.description} |`);}+ sections.push('');}- if (docs.features?.length) {+ const features = docs.usage?.features || docs.features;+ if (features?.length) {sections.push('## Features\n');- sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');+ sections.push(features.map(f => `- ${f}`).join('\n') + '\n');}// Single component props@@ -251,19 +244,16 @@ export function formatFull(docs, options = {}) {}}- if (docs.accessibility?.length) {+ const a11y = docs.usage?.accessibility || docs.accessibility;+ if (a11y?.length) {sections.push('## Accessibility\n');- sections.push(docs.accessibility.map(a => `- ${a}`).join('\n') + '\n');+ sections.push(a11y.map(a => `- ${a}`).join('\n') + '\n');}- if (docs.keyboard) {- sections.push('## Keyboard\n');- sections.push(docs.keyboard + '\n');- }-- if (docs.notes?.length) {+ const notes = docs.usage?.notes || docs.notes;+ if (notes?.length) {sections.push('## Notes\n');- sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');+ sections.push(notes.map(n => `- ${n}`).join('\n') + '\n');}return sections.join('\n');@@ -271,7 +261,7 @@ export function formatFull(docs, options = {}) {/*** Format compact docs for LLM consumption (replaces extractCompact + ensureImportStatement).- * Includes: import, features, props, limited examples, keyboard, notes.+ * Includes: import, features, props, keyboard, notes.*/export function formatCompact(docs, componentName, importHint) {const displayName = componentName.startsWith('XDS')@@ -281,11 +271,9 @@ export function formatCompact(docs, componentName, importHint) {const sections = [];sections.push(`# ${docs.name}\n`);- sections.push(docs.description + '\n');+ const desc = docs.usage?.description || docs.description || '';+ sections.push(desc + '\n');- if (docs.usage?.summary) {- sections.push(docs.usage.summary + '\n');- }if (docs.usage?.anatomy?.length) {sections.push('Anatomy: ' + docs.usage.anatomy.map(el => {const req = el.required ? '' : ' (optional)';@@ -293,15 +281,15 @@ export function formatCompact(docs, componentName, importHint) {}).join(', ') + '\n');}- // Import statementif (importHint) {sections.push('## Import\n');sections.push(`\`\`\`tsx\nimport { ${displayName} } from '${importHint}';\n\`\`\`\n`);}- if (docs.features?.length) {+ const features = docs.usage?.features || docs.features;+ if (features?.length) {sections.push('## Features\n');- sections.push(docs.features.map(f => `- ${f}`).join('\n') + '\n');+ sections.push(features.map(f => `- ${f}`).join('\n') + '\n');}// Props@@ -328,14 +316,10 @@ export function formatCompact(docs, componentName, importHint) {}}- if (docs.keyboard) {- sections.push('## Keyboard\n');- sections.push(docs.keyboard + '\n');- }-- if (docs.notes?.length) {+ const compactNotes = docs.usage?.notes || docs.notes;+ if (compactNotes?.length) {sections.push('## Notes\n');- sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');+ sections.push(compactNotes.map(n => `- ${n}`).join('\n') + '\n');}// CSS custom properties (compact includes these for theme consumers)@@ -368,7 +352,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {// Find the right props and examples for this componentlet props = [];- let description = docs.description;+ let description = docs.usage?.description || docs.description || '';let examples = docs.examples || [];if ('props' in docs) {diff --git a/packages/cli/src/lib/component-loader.mjs b/packages/cli/src/lib/component-loader.mjsindex 7da3df958d..0151f63be2 100644--- a/packages/cli/src/lib/component-loader.mjs+++ b/packages/cli/src/lib/component-loader.mjs@@ -8,11 +8,24 @@ function mergeTranslation(docs, translation) {if (!translation) return docs;const merged = {...docs};- if (translation.description) merged.description = translation.description;- if (translation.features) merged.features = translation.features;- if (translation.notes) merged.notes = translation.notes;- if (translation.accessibility) merged.accessibility = translation.accessibility;- if (translation.keyboard) merged.keyboard = translation.keyboard;++ // Merge prose into usage (new unified format)+ if (merged.usage) {+ merged.usage = {...merged.usage};+ if (translation.description) merged.usage.description = translation.description;+ if (translation.features) merged.usage.features = translation.features;+ if (translation.notes) merged.usage.notes = translation.notes;+ if (translation.accessibility) merged.usage.accessibility = translation.accessibility;+ if (translation.keyboard) {+ merged.usage.accessibility = [+ ...(merged.usage.accessibility || []).filter(a => !a.startsWith('Keyboard:')),+ `Keyboard: ${translation.keyboard}`,+ ];+ }+ }++ // Legacy top-level fields (for docsZh that are full ComponentDoc clones)+ if (translation.description && !merged.usage) merged.description = translation.description;// Merge prop descriptions for single-component docsif (translation.propDescriptions && merged.props) {diff --git a/packages/cli/src/lib/string-utils.mjs b/packages/cli/src/lib/string-utils.mjsindex 8ccb7f5c19..b261cc1f63 100644--- a/packages/cli/src/lib/string-utils.mjs+++ b/packages/cli/src/lib/string-utils.mjs@@ -155,8 +155,9 @@ export async function searchComponents(needle, coreDir, components) {}// Description search (whole word boundary)- if (docs.description && term.length >= 3) {- const descLower = docs.description.toLowerCase();+ const searchDesc = docs.usage?.description || docs.description;+ if (searchDesc && term.length >= 3) {+ const descLower = searchDesc.toLowerCase();const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');const re = new RegExp('\\b' + escaped + '\\b');if (re.test(descLower)) {@@ -165,8 +166,9 @@ export async function searchComponents(needle, coreDir, components) {}// Feature search (whole word boundary)- if (docs.features && Array.isArray(docs.features) && term.length >= 3) {- for (const feat of docs.features) {+ const searchFeatures = docs.usage?.features || docs.features;+ if (searchFeatures && Array.isArray(searchFeatures) && term.length >= 3) {+ for (const feat of searchFeatures) {const featLower = feat.toLowerCase();const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');const re = new RegExp('\\b' + escaped + '\\b');diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjsindex ded8cc43d3..81c3932019 100644--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs@@ -2,8 +2,6 @@export const docs = {name: 'AlertDialog',- description:- 'Confirmation dialog for destructive or irreversible actions. Uses role="alertdialog" with required title, description, and cancel/action buttons.',keywords: ['alert','alertdialog',@@ -14,14 +12,20 @@ export const docs = {'modal','dialog',],- features: [- 'ARIA alertdialog: Uses role="alertdialog" with aria-labelledby and aria-describedby',- 'No backdrop dismiss: Cannot be closed by clicking outside the dialog',- 'Escape = Cancel: Pressing Escape triggers the cancel action',- 'Built-in buttons: Ghost cancel and configurable action button rendered internally',- 'Action does not auto-close: Supports async operations with loading states',- 'Imperative API: useXDSImperativeAlertDialog for fire-and-forget usage',- ],+ usage: {+ description:+ 'Confirmation dialog for destructive or irreversible actions. Uses role="alertdialog" with required title, description, and cancel/action buttons.',+ features: [+ 'No backdrop dismiss: Cannot be closed by clicking outside the dialog',+ 'Built-in buttons: Ghost cancel and configurable action button rendered internally',+ 'Action does not auto-close: Supports async operations with loading states',+ 'Imperative API: useXDSImperativeAlertDialog for fire-and-forget usage',+ ],+ accessibility: [+ 'Uses role="alertdialog" with aria-labelledby and aria-describedby',+ 'Keyboard: Escape triggers the cancel 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.'},diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjsindex a7f9148b70..26f6daa46f 100644--- a/packages/core/src/AppShell/AppShell.doc.mjs+++ b/packages/core/src/AppShell/AppShell.doc.mjs@@ -2,18 +2,33 @@export const docs = {name: 'AppShell',- description:- 'Application-level layout shell providing header, side navigation, and main content area — composes XDSLayout internally and replaces the XDSPage + XDSPageLayout pattern.',keywords: ["appshell","layout","scaffold","sidebar","sidenav","topnav","header","navigation","dashboard","shell","page","frame"],- features: [- 'Two navigation slots: topNav (horizontal bar) and sideNav (vertical sidebar)',- 'Two height modes: fill (viewport-height, independent scroll containers) and auto (page-scroll with sticky nav)',- 'Controlled and uncontrolled sideNav collapse with responsive auto-collapse via mobileNav breakpoint',- 'Mobile: collapsed sideNav renders as an overlay with backdrop',- 'Composes XDSLayout internally for automatic padding collapse, scroll containment, and slot awareness',- 'Semantic HTML: <main> with role="main", SideNav with role="navigation", skip-to-content link',- 'Escape key closes mobile sideNav overlay',- ],+ usage: {+ description:+ 'Application-level layout shell providing header, side navigation, and main content area. Composes XDSLayout internally and replaces the XDSPage + XDSPageLayout pattern.',+ features: [+ 'Two navigation slots: topNav (horizontal bar) and sideNav (vertical sidebar)',+ 'Two height modes: fill (viewport-height, independent scroll containers) and auto (page-scroll with sticky nav)',+ 'Controlled and uncontrolled sideNav collapse with responsive auto-collapse via mobileNav breakpoint',+ 'Mobile: collapsed sideNav renders as an overlay with backdrop',+ 'Composes XDSLayout internally for automatic padding collapse, scroll containment, and slot awareness',+ ],+ accessibility: [+ 'Semantic HTML via XDSLayout slots — each slot maps to a proper landmark element.',+ '<main> content area has role="main" for landmark navigation.',+ 'SideNav has role="navigation" with aria-label="Application navigation".',+ 'Skip-to-content link is visually hidden but shown on focus for keyboard users.',+ 'Keyboard: Escape key closes the mobile sideNav overlay.',+ ],+ notes: [+ 'When a TopNav is present, omit XDSSideNavHeading from the SideNav — the TopNav already provides app identity. Adding both would double the identity.',+ 'When there is no TopNav, include XDSSideNavHeading inside the SideNav so the app name and logo are present.',+ 'XDSAppShell composes XDSLayout internally: topNav + banner map to XDSLayoutHeader, sideNav maps to XDSLayoutPanel, and children map to XDSLayoutContent.',+ 'SideNav collapse animations currently snap open/closed; ViewTransitions support is planned.',+ 'In "auto" height mode, TopNav gets position: sticky; top: 0 and SideNav gets position: sticky; top: <header-height>.',+ 'In "fill" height mode, the shell fills 100dvh, TopNav is pinned at the top, and both the SideNav and content area have independent scroll containers.',+ ],+ },props: [{name: 'children',@@ -87,51 +102,46 @@ export const docs = {'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',},],- accessibility: [- 'Semantic HTML via XDSLayout slots — each slot maps to a proper landmark element.',- '<main> content area has role="main" for landmark navigation.',- 'SideNav has role="navigation" with aria-label="Application navigation".',- 'Skip-to-content link is visually hidden but shown on focus for keyboard users.',- 'Escape key closes the mobile sideNav overlay.',- ],theming: {targets: [{className: 'xds-app-shell', visualProps: ['variant', 'height']},],},- notes: [- 'When a TopNav is present, omit XDSSideNavHeading from the SideNav — the TopNav already provides app identity. Adding both would double the identity.',- 'When there is no TopNav, include XDSSideNavHeading inside the SideNav so the app name and logo are present.',- 'XDSAppShell composes XDSLayout internally: topNav + banner map to XDSLayoutHeader, sideNav maps to XDSLayoutPanel, and children map to XDSLayoutContent.',- 'SideNav collapse animations currently snap open/closed; ViewTransitions support is planned.',- 'In "auto" height mode, TopNav gets position: sticky; top: 0 and SideNav gets position: sticky; top: <header-height>.',- 'In "fill" height mode, the shell fills 100dvh, TopNav is pinned at the top, and both the SideNav and content area have independent scroll containers.',- ],- usage: {- summary: 'Application-level layout shell providing header, side navigation, and main content area.',- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'AppShell',- description:- '应用级布局外壳,提供顶部导航栏、侧边导航栏和主内容区域——内部组合使用 XDSLayout,替代 XDSPage + XDSPageLayout 模式。',- features: [- '两个导航插槽:topNav(水平导航栏)和 sideNav(垂直侧边栏)',- '两种高度模式:fill(视口高度,独立滚动容器)和 auto(页面滚动,导航栏吸顶)',- '受控和非受控的 sideNav 折叠,通过 mobileNav breakpoint 支持响应式自动折叠',- '移动端:折叠的 sideNav 以带遮罩层的浮层形式展示',- '内部组合使用 XDSLayout,自动处理内边距折叠、滚动容器和插槽感知',- '语义化 HTML:<main> 带 role="main",SideNav 带 role="navigation",跳转到内容链接',- 'Escape 键关闭移动端 sideNav 浮层',- ],+ usage: {+ description:+ '应用级布局外壳,提供顶部导航栏、侧边导航栏和主内容区域——内部组合使用 XDSLayout,替代 XDSPage + XDSPageLayout 模式。',+ features: [+ '两个导航插槽:topNav(水平导航栏)和 sideNav(垂直侧边栏)',+ '两种高度模式:fill(视口高度,独立滚动容器)和 auto(页面滚动,导航栏吸顶)',+ '受控和非受控的 sideNav 折叠,通过 mobileNav breakpoint 支持响应式自动折叠',+ '移动端:折叠的 sideNav 以带遮罩层的浮层形式展示',+ '内部组合使用 XDSLayout,自动处理内边距折叠、滚动容器和插槽感知',+ '语义化 HTML:<main> 带 role="main",SideNav 带 role="navigation",跳转到内容链接',+ 'Escape 键关闭移动端 sideNav 浮层',+ ],+ accessibility: [+ '通过 XDSLayout 插槽实现语义化 HTML——每个插槽对应一个合适的地标元素。',+ '<main> 内容区域具有 role="main",用于地标导航。',+ 'SideNav 具有 role="navigation" 和 aria-label="Application navigation"。',+ '跳转到内容链接在视觉上隐藏,但在键盘聚焦时显示,方便键盘用户使用。',+ 'Escape 键关闭移动端 sideNav 浮层。',+ ],+ notes: [+ '当存在 TopNav 时,请勿在 SideNav 中使用 XDSSideNavHeading——TopNav 已提供了应用标识。同时使用两者会导致标识重复。',+ '当没有 TopNav 时,请在 SideNav 中添加 XDSSideNavHeading,以确保应用名称和图标可见。',+ 'XDSAppShell 内部组合使用 XDSLayout:topNav + banner 映射到 XDSLayoutHeader,sideNav 映射到 XDSLayoutPanel,children 映射到 XDSLayoutContent。',+ 'SideNav 折叠动画目前为瞬间切换;计划支持 ViewTransitions。',+ '在 "auto" 高度模式下,TopNav 使用 position: sticky; top: 0,SideNav 使用 position: sticky; top: <header-height>。',+ '在 "fill" 高度模式下,外壳填满 100dvh,TopNav 固定在顶部,SideNav 和内容区域各有独立的滚动容器。',+ ],+ },props: [- {- name: 'children',- type: 'ReactNode',- description: '主内容区域,渲染在 <main> 元素内部。',- },+ {name: 'children', type: 'ReactNode', description: '主内容区域,渲染在 <main> 元素内部。'},{name: 'contentPadding',type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',@@ -139,28 +149,10 @@ export const docsZh = {'主内容区域的内边距。根据页面主要内容模式设置:4(16px)适用于表单/设置/文本页面,0 适用于仪表盘/地图/表格。可通过 XDSSection 覆盖个别区域。',default: '0',},- {- name: 'topNav',- type: 'ReactNode',- description: '顶部导航插槽,通常为 XDSTopNav。',- },- {- name: 'sideNav',- type: 'ReactNode',- description: '侧边导航插槽,通常为 XDSSideNav。',- },- {- name: 'mobileNav',- type: 'ReactNode',- description:- '移动端导航配置。接受 false(禁用)、配置对象(调整自动行为)或 ReactNode(完全自定义抽屉)。',- },- {- name: 'banner',- type: 'ReactNode',- description:- '横幅插槽,用于全局公告,放置在 topNav 上方。',- },+ {name: 'topNav', type: 'ReactNode', description: '顶部导航插槽,通常为 XDSTopNav。'},+ {name: 'sideNav', type: 'ReactNode', description: '侧边导航插槽,通常为 XDSSideNav。'},+ {name: 'mobileNav', type: 'ReactNode', description: '移动端导航配置。接受 false(禁用)、配置对象(调整自动行为)或 ReactNode(完全自定义抽屉)。'},+ {name: 'banner', type: 'ReactNode', description: '横幅插槽,用于全局公告,放置在 topNav 上方。'},{name: 'height',type: "'fill' | 'auto'",@@ -168,35 +160,16 @@ export const docsZh = {"高度行为:'fill' 使外壳填满视口(100dvh),各区域拥有独立的滚动容器;'auto' 使外壳随内容增长,导航使用 sticky 定位。",default: "'fill'",},- {- name: 'isSideNavCollapsed',- type: 'boolean',- description: 'sideNav 是否折叠(受控模式)。',- },- {- name: 'defaultIsSideNavCollapsed',- type: 'boolean',- description: '非受控模式下的初始折叠状态。',- default: 'false',- },- {- name: 'onSideNavCollapsedChange',- type: '(isCollapsed: boolean) => void',- description: 'sideNav 折叠状态变化时触发的回调。',- },+ {name: 'isSideNavCollapsed', type: 'boolean', description: 'sideNav 是否折叠(受控模式)。'},+ {name: 'defaultIsSideNavCollapsed', type: 'boolean', description: '非受控模式下的初始折叠状态。', default: 'false'},+ {name: 'onSideNavCollapsedChange', type: '(isCollapsed: boolean) => void', description: 'sideNav 折叠状态变化时触发的回调。'},{name: 'sideNavBreakpoint',type: "'sm' | 'md' | 'lg' | 'none'",- description:- '视口宽度断点,低于该断点时 sideNav 自动折叠。使用 "none" 禁用响应式折叠。',+ description: '视口宽度断点,低于该断点时 sideNav 自动折叠。使用 "none" 禁用响应式折叠。',default: "'md'",},- {- name: 'sideNavWidth',- type: 'number',- description: 'sideNav 面板的宽度(像素)。',- default: '260',- },+ {name: 'sideNavWidth', type: 'number', description: 'sideNav 面板的宽度(像素)。', default: '260'},{name: 'variant',type: "'wash' | 'surface' | 'section' | 'elevated'",@@ -211,26 +184,17 @@ export const docsZh = {'用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,不能是 style={{}} 形式的内联样式对象。',},],- accessibility: [- '通过 XDSLayout 插槽实现语义化 HTML——每个插槽对应一个合适的地标元素。',- '<main> 内容区域具有 role="main",用于地标导航。',- 'SideNav 具有 role="navigation" 和 aria-label="Application navigation"。',- '跳转到内容链接在视觉上隐藏,但在键盘聚焦时显示,方便键盘用户使用。',- 'Escape 键关闭移动端 sideNav 浮层。',- ],theming: {targets: [- {className: 'xds-app-shell', visualProps: ['variant', 'height']},+ {+ className: 'xds-app-shell',+ visualProps: [+ 'variant',+ 'height',+ ],+ },],},- notes: [- '当存在 TopNav 时,请勿在 SideNav 中使用 XDSSideNavHeading——TopNav 已提供了应用标识。同时使用两者会导致标识重复。',- '当没有 TopNav 时,请在 SideNav 中添加 XDSSideNavHeading,以确保应用名称和图标可见。',- 'XDSAppShell 内部组合使用 XDSLayout:topNav + banner 映射到 XDSLayoutHeader,sideNav 映射到 XDSLayoutPanel,children 映射到 XDSLayoutContent。',- 'SideNav 折叠动画目前为瞬间切换;计划支持 ViewTransitions。',- '在 "auto" 高度模式下,TopNav 使用 position: sticky; top: 0,SideNav 使用 position: sticky; top: <header-height>。',- '在 "fill" 高度模式下,外壳填满 100dvh,TopNav 固定在顶部,SideNav 和内容区域各有独立的滚动容器。',- ],};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjsindex 316239a38a..4bbaba566c 100644--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs@@ -2,12 +2,16 @@export const docs = {name: 'AspectRatio',- description: 'Maintains a specific aspect ratio for its children.', keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],- features: [- 'Accepts any numeric ratio expressed as width/height (e.g. 16/9, 4/3, 1)',- 'Children are positioned absolutely to fill the container',- 'Supports theming via the aspectRatio component key',- ],+ keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],+ usage: {+ description:+ 'Maintains a specific aspect ratio for its children, useful for responsive media containers like embedded videos and images.',+ features: [+ 'Accepts any numeric ratio expressed as width/height (e.g. 16/9, 4/3, 1)',+ 'Children are positioned absolutely to fill the container',+ 'Supports theming via the aspectRatio component key',+ ],+ },props: [{name: 'ratio',@@ -33,33 +37,22 @@ export const docs = {{className: 'xds-aspect-ratio'},],},- usage: {- summary: 'Maintains a specific aspect ratio for its children, useful for responsive media containers.',- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'AspectRatio',- description: '为子元素保持特定的宽高比。',- features: [- '接受任何以宽/高表示的数字比例(例如 16/9、4/3、1)',- '子元素通过绝对定位填充容器',- '通过 aspectRatio 组件键支持主题定制',- ],+ usage: {+ description: '为子元素保持特定的宽高比。',+ features: [+ '接受任何以宽/高表示的数字比例(例如 16/9、4/3、1)',+ '子元素通过绝对定位填充容器',+ '通过 aspectRatio 组件键支持主题定制',+ ],+ },props: [- {- name: 'ratio',- type: 'number',- description: '宽高比,以宽/高表示(例如 16/9、1)。',- required: true,- },- {- name: 'children',- type: 'ReactNode',- description: '通过绝对定位填充容器的内容。',- required: true,- },+ {name: 'ratio', type: 'number', description: '宽高比,以宽/高表示(例如 16/9、1)。', required: true},+ {name: 'children', type: 'ReactNode', description: '通过绝对定位填充容器的内容。', required: true},{name: 'xstyle',type: 'StyleXStyles',diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjsindex add513ed8f..98901b6ef6 100644--- a/packages/core/src/Avatar/Avatar.doc.mjs+++ b/packages/core/src/Avatar/Avatar.doc.mjs@@ -2,33 +2,37 @@export const docs = {name: 'Avatar',- description:- 'Avatar component for displaying user profile pictures with fallback support.',keywords: ["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],- features: [- 'Image loading: Primary and fallback image sources',- 'Initials fallback: Auto-generates initials from user name',- 'Default icon: Generic person icon when no image or name provided',- 'Sizes: tiny (20px), xsmall (24px), small (36px), medium (48px), large (128px), plus numeric pixel values',- 'Status slot: Corner position for status indicators or badges',- 'Size-aware status dot: Built-in XDSAvatarStatusDot that scales proportionally with avatar size',- 'Accessible: Proper role and aria-label support',- ],+ usage: {+ description:+ 'Displays a user profile picture with automatic fallback to initials when no image is available. Use to represent a user or entity visually alongside user information.',+ features: [+ 'Image loading: Primary and fallback image sources',+ 'Initials fallback: Auto-generates initials from user name',+ 'Default icon: Generic person icon when no image or name provided',+ 'Sizes: tiny (20px), xsmall (24px), small (36px), medium (48px), large (128px), plus numeric pixel values',+ 'Status slot: Corner position for status indicators or badges',+ 'Size-aware status dot: Built-in XDSAvatarStatusDot that scales proportionally with avatar size',+ ],+ accessibility: [+ 'Proper role and aria-label support',+ ],+ notes: [+ 'Always circular shape (border-radius: 50%)',+ 'Uses color.deemphasized and color.textSecondary for fallback background',+ 'Initials extracted from first and last word of name',+ 'XDSAvatarSizeContext provides the resolved numeric size to sub-components',+ 'Status dot uses CIRCLE_EDGE_OFFSET_RATIO for positioning at the 45° point on the circle edge',+ 'Fallback cascade: (1) src loads → show image; (2) src fails → try fallbackSrc; (3) fallbackSrc fails/missing → show initials from name; (4) no name → show generic person icon',+ 'Status dot size tiers: avatar ≤ 36px → 8px dot with 1px border; avatar 40–72px → 16px dot with 2px border; avatar ≥ 96px → 24px dot with 4px border',+ ],+ },theming: {targets: [{className: 'xds-avatar', visualProps: ['size']},{className: 'xds-avatar-status-dot', visualProps: ['variant']},],},- notes: [- 'Always circular shape (border-radius: 50%)',- 'Uses color.deemphasized and color.textSecondary for fallback background',- 'Initials extracted from first and last word of name',- 'XDSAvatarSizeContext provides the resolved numeric size to sub-components',- 'Status dot uses CIRCLE_EDGE_OFFSET_RATIO for positioning at the 45° point on the circle edge',- 'Fallback cascade: (1) src loads → show image; (2) src fails → try fallbackSrc; (3) fallbackSrc fails/missing → show initials from name; (4) no name → show generic person icon',- 'Status dot size tiers: avatar ≤ 36px → 8px dot with 1px border; avatar 40–72px → 16px dot with 2px border; avatar ≥ 96px → 24px dot with 4px border',- ],components: [{name: 'XDSAvatar',@@ -91,105 +95,68 @@ export const docs = {],},],- usage: {- summary: 'Displays a user profile picture with automatic fallback to initials when no image is available.',- content: `## When to use--- Representing a user or entity visually.-- Showing a profile image alongside user information.-- Displaying a fallback when no image is provided.`,- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Avatar',- description:- '头像组件,用于显示用户头像图片,支持降级回退。',- features: [- '图片加载:主图片源和备用图片源',- '首字母回退:根据用户姓名自动生成首字母缩写',- '默认图标:未提供图片或姓名时显示通用人物图标',- '尺寸:tiny(20px)、xsmall(24px)、small(36px)、medium(48px)、large(128px),以及自定义数值像素',- '状态插槽:角落位置用于状态指示器或徽章',- '尺寸感知状态点:内置 XDSAvatarStatusDot,随头像尺寸等比缩放',- '无障碍:支持正确的 role 和 aria-label',- ],+ usage: {+ description: '头像组件,用于显示用户头像图片,支持降级回退。',+ features: [+ '图片加载:主图片源和备用图片源',+ '首字母回退:根据用户姓名自动生成首字母缩写',+ '默认图标:未提供图片或姓名时显示通用人物图标',+ '尺寸:tiny(20px)、xsmall(24px)、small(36px)、medium(48px)、large(128px),以及自定义数值像素',+ '状态插槽:角落位置用于状态指示器或徽章',+ '尺寸感知状态点:内置 XDSAvatarStatusDot,随头像尺寸等比缩放',+ '无障碍:支持正确的 role 和 aria-label',+ ],+ notes: [+ '始终为圆形(border-radius: 50%)',+ '回退背景使用 color.deemphasized 和 color.textSecondary',+ '首字母从姓名的第一个和最后一个单词中提取',+ 'XDSAvatarSizeContext 向子组件提供解析后的数值尺寸',+ '状态点使用 CIRCLE_EDGE_OFFSET_RATIO 定位在圆形边缘的 45° 位置',+ '回退级联:(1) src 加载成功 → 显示图片;(2) src 加载失败 → 尝试 fallbackSrc;(3) fallbackSrc 失败/缺失 → 显示姓名首字母;(4) 无姓名 → 显示通用人物图标',+ '状态点尺寸层级:头像 ≤ 36px → 8px 点 + 1px 边框;头像 40–72px → 16px 点 + 2px 边框;头像 ≥ 96px → 24px 点 + 4px 边框',+ ],+ },theming: {targets: [- {className: 'xds-avatar', visualProps: ['size']},- {className: 'xds-avatar-status-dot', visualProps: ['variant']},+ {+ className: 'xds-avatar',+ visualProps: [+ 'size',+ ],+ },+ {+ className: 'xds-avatar-status-dot',+ visualProps: [+ 'variant',+ ],+ },],},- notes: [- '始终为圆形(border-radius: 50%)',- '回退背景使用 color.deemphasized 和 color.textSecondary',- '首字母从姓名的第一个和最后一个单词中提取',- 'XDSAvatarSizeContext 向子组件提供解析后的数值尺寸',- '状态点使用 CIRCLE_EDGE_OFFSET_RATIO 定位在圆形边缘的 45° 位置',- '回退级联:(1) src 加载成功 → 显示图片;(2) src 加载失败 → 尝试 fallbackSrc;(3) fallbackSrc 失败/缺失 → 显示姓名首字母;(4) 无姓名 → 显示通用人物图标',- '状态点尺寸层级:头像 ≤ 36px → 8px 点 + 1px 边框;头像 40–72px → 16px 点 + 2px 边框;头像 ≥ 96px → 24px 点 + 4px 边框',- ],components: [{name: 'XDSAvatar',- description:- '显示用户头像,支持图片、首字母回退和可选的状态指示器。',+ 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: 'XDSAvatarSize',- description: '头像尺寸(命名值或数值像素值)。',- default: "'small'",- },- {- name: 'status',- type: 'ReactNode',- description: '角落内容,用于状态指示器。',- },+ {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: 'XDSAvatarSize', description: '头像尺寸(命名值或数值像素值)。', default: "'small'"},+ {name: 'status', type: 'ReactNode', description: '角落内容,用于状态指示器。'},],},{name: 'XDSAvatarStatusDot',- description:- '尺寸感知的状态指示点,从上下文中读取头像尺寸并等比缩放。',+ description: '尺寸感知的状态指示点,从上下文中读取头像尺寸并等比缩放。',props: [- {- name: 'variant',- type: "'positive' | 'neutral' | 'negative'",- description: '状态点的语义颜色变体。',- default: "'positive'",- },- {- name: 'label',- type: 'string',- description: '屏幕阅读器的无障碍标签。',- },- {- name: 'icon',- type: 'ReactNode',- description: '居中显示在状态点内的图标(tiny 尺寸时隐藏)。',- },+ {name: 'variant', type: "'positive' | 'neutral' | 'negative'", description: '状态点的语义颜色变体。', default: "'positive'"},+ {name: 'label', type: 'string', description: '屏幕阅读器的无障碍标签。'},+ {name: 'icon', type: 'ReactNode', description: '居中显示在状态点内的图标(tiny 尺寸时隐藏)。'},],},],diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjsindex cc5cfe02a2..14682a27ff 100644--- a/packages/core/src/Badge/Badge.doc.mjs+++ b/packages/core/src/Badge/Badge.doc.mjs@@ -2,8 +2,6 @@export const docs = {name: 'Badge',- description:- 'A badge component for displaying status indicators, counts, or labels.',keywords: ["badge","tag","chip","label","status","indicator","count","counter","pill","notification","marker"],props: [{@@ -30,45 +28,8 @@ export const docs = {],},usage: {- summary: 'Badges display system or categorical information, helping users quickly identify the state of a system, process, or entity, or group items into meaningful categories.',- content: `## When to use--Badges provide users with clear information about the current or upcoming state of a system, process, or categorization, enabling users to take necessary actions.--There are two types of badges:--- **System status**: Indicate the current, dynamic state of a system, process, or entity. Use semantic colors to convey critical information (e.g., error, warning, success, or active states).-- **Categorical**: Group objects, processes, or entities into static categories. Use non-semantic colors to provide visual distinction without implying criticality.--## When NOT to use--- Don't use badges as filters. Use interactive filters or tabs instead.-- Don't use badges to highlight or draw attention to text. Use plain text for information that doesn't require scanning.--## Best practices--### Color usage--- Do: Use semantic (system status) colors to convey statuses such as active, success, error, or warning.-- Don't: Use categorical colors for system status, as they may not draw enough attention.-- Do: Use non-semantic colors to categorize information.-- Don't: Use system status colors for categorization.-- Do: Use color to draw attention to badges that require user action. Use the default badge color for non-actionable items.-- Don't: Overuse color.--### Icons and labels--- Do: Always pair icons with a clear label.-- Don't: Use icon-only badges, as they can be ambiguous.-- Do: Use concise labels (fewer than 3 words).-- Don't: Use more than 3 words in a badge.--## Placement--- **Headers**: Provide additional context in page or section headers.-- **List items**: Annotate items within lists.-- **Tables**: Highlight specific rows or cells.-- **Tabs and menus**: Annotate tabs or menu items.`,+ description:+ 'Badges display system or categorical information such as status indicators, counts, or labels. Use semantic color variants (neutral, info, success, warning, error) for system status and non-semantic colors for categorization. Always pair icons with labels and keep labels concise.',anatomy: [{name: 'Icon', required: false, description: 'A visual indicator that helps users identify the type of badge.'},{name: 'Label', required: true, description: 'A text or numerical label that provides additional context.'},@@ -79,29 +40,26 @@ There are two types of badges:/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Badge',- description:- '用于显示状态指示器、计数或标签的徽章组件。',+ usage: {description: '用于显示状态指示器、计数或标签的徽章组件。'},props: [{name: 'variant',- type: "'neutral' | 'info' | 'success' | 'warning' | 'error' | 'blue' | 'cyan' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'",+ type:+ "'neutral' | 'info' | 'success' | 'warning' | 'error' | 'blue' | 'cyan' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'",description: '视觉样式变体。语义变体使用实色背景,非语义颜色变体使用浅色背景配彩色文字。',default: "'neutral'",},- {- name: 'label',- type: 'ReactNode',- description: '徽章文本内容。',- },- {- name: 'icon',- type: 'ReactNode',- description: '可选的前置图标。',- },+ {name: 'label', type: 'ReactNode', description: '徽章文本内容。'},+ {name: 'icon', type: 'ReactNode', description: '可选的前置图标。'},],theming: {targets: [- {className: 'xds-badge', visualProps: ['variant']},+ {+ className: 'xds-badge',+ visualProps: [+ 'variant',+ ],+ },],},};diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjsindex 33e0ec1f7b..e25572c73a 100644--- a/packages/core/src/Banner/Banner.doc.mjs+++ b/packages/core/src/Banner/Banner.doc.mjs@@ -2,20 +2,40 @@export const docs = {name: 'Banner',- description:- 'Persistent status notification for info, warning, error, or success messages.',-keywords: ["banner","alert","notification","callout","notice","status","message","info","warning","error","success","toast"],- features: [- 'Two-part layout: colored status header with icon, title, description, action buttons, and optional dismiss; optional card-background content area below',- 'When no children are provided, only the colored header renders',- 'Self-managed dismiss state — banner hides itself on dismiss without requiring external state wiring',- 'onDismiss callback fires alongside the internal state change for logging or backend sync',- 'Default status icons from @heroicons/react/24/solid: InformationCircleIcon (info), ExclamationTriangleIcon (warning), XCircleIcon (error), CheckCircleIcon (success)',- 'Status colors: info uses --color-accent-muted, warning uses --color-warning-muted, error uses --color-error-muted, success uses --color-success-muted',- 'Card container (default): has border-radius with optional card content area below the colored header',- 'Section container: no border-radius, full-width for page-level banners',- ],+ usage: {+ description:+ 'Persistent status notification that displays a prominent message and related actions. Communicates critical or non-critical information for info, warning, error, or success scenarios. Keep titles and descriptions to 1–2 lines and default to the collapsed state.',+ features: [+ 'Two-part layout: colored status header with icon, title, description, action buttons, and optional dismiss; optional card-background content area below',+ 'When no children are provided, only the colored header renders',+ 'Self-managed dismiss state — banner hides itself on dismiss without requiring external state wiring',+ 'onDismiss callback fires alongside the internal state change for logging or backend sync',+ 'Card container (default): has border-radius with optional card content area below the colored header',+ 'Section container: no border-radius, full-width for page-level banners',+ ],+ accessibility: [+ 'Uses role="alert" for error and warning statuses',+ 'Uses role="status" for info and success statuses',+ 'Dismiss button has aria-label="Dismiss"',+ 'Status icon is aria-hidden="true" — status is conveyed by the ARIA role instead',+ ],+ notes: [+ 'Default status icons from @heroicons/react/24/solid: InformationCircleIcon (info), ExclamationTriangleIcon (warning), XCircleIcon (error), CheckCircleIcon (success)',+ 'Status colors: info uses --color-accent-muted, warning uses --color-warning-muted, error uses --color-error-muted, success uses --color-success-muted',+ 'Banner uses `status` as its extensible theming axis. Custom statuses via `defineTheme` components: `status:neutral`.',+ 'Collapsible support is planned: the content area will support collapsing via useXDSCollapsible (issue #187)',+ ],+ anatomy: [+ {name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},+ {name: 'Heading', required: false, description: 'Required if no description is provided.'},+ {name: 'Description', required: false, description: 'Required if no heading is provided.'},+ {name: 'Action Button', required: false, description: 'Actionable button related to the banner message.'},+ {name: 'Expand/Collapse Button', required: false, description: 'Toggles additional banner content.'},+ {name: 'Dismissible Button', required: false, description: 'Dismisses the banner. Not available for critical banners.'},+ {name: 'Flex Space', required: false, description: 'Additional space for supplementary info.'},+ ],+ },props: [{@@ -79,13 +99,6 @@ export const docs = {},],- accessibility: [- 'Uses role="alert" for error and warning statuses',- 'Uses role="status" for info and success statuses',- 'Dismiss button has aria-label="Dismiss"',- 'Status icon is aria-hidden="true" — status is conveyed by the ARIA role instead',- ],-theming: {targets: [{className: 'xds-banner', visualProps: ['container', 'status']},@@ -95,107 +108,44 @@ export const docs = {{name: '--banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)'},],},- notes: [- 'Banner uses `status` as its extensible theming axis. Custom statuses via `defineTheme` components: `status:neutral`.',- 'Collapsible support is planned: the content area will support collapsing via useXDSCollapsible (issue #187)',- ],- usage: {- summary: 'Displays a prominent message and related actions to communicate critical or non-critical information.',- content: `## When to use--- To communicate critical or non-critical information at the top of a page, below headers, or in card format.--## Best practices--- Do: Display the action on both the banner and the page.-- Do: Keep titles and descriptions to 1\u20132 lines.-- Do: Default to the collapsed state.-- Don't: Replace user actions on the page \u2014 banners are temporary.-- Don't: Add lengthy content.-- Don't: Use expanded as the default state.`,- anatomy: [- {name: 'Icon', required: true, description: 'Visual indicator for the banner type.'},- {name: 'Heading', required: false, description: 'Required if no description is provided.'},- {name: 'Description', required: false, description: 'Required if no heading is provided.'},- {name: 'Action Button', required: false, description: 'Actionable button related to the banner message.'},- {name: 'Expand/Collapse Button', required: false, description: 'Toggles additional banner content.'},- {name: 'Dismissible Button', required: false, description: 'Dismisses the banner. Not available for critical banners.'},- {name: 'Flex Space', required: false, description: 'Additional space for supplementary info.'},- ],- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Banner',- description:- '持久性状态通知,用于展示信息、警告、错误或成功消息。',-- features: [- '双区域布局:带图标、标题、描述、操作按钮和可选关闭按钮的彩色状态头部;下方可选的卡片背景内容区',- '未提供 children 时,仅渲染彩色头部',- '自管理关闭状态——横幅在关闭时自动隐藏,无需外部状态管理',- 'onDismiss 回调在内部状态变更的同时触发,用于日志记录或后端同步',- '默认状态图标来自 @heroicons/react/24/solid:InformationCircleIcon(info)、ExclamationTriangleIcon(warning)、XCircleIcon(error)、CheckCircleIcon(success)',- '状态颜色:info 使用 --color-accent-muted,warning 使用 --color-warning-muted,error 使用 --color-error-muted,success 使用 --color-success-muted',- 'Card 变体(默认):带圆角,彩色头部下方可选卡片内容区',- 'Section 变体:无圆角,全宽,适用于页面级横幅',- ],-+ usage: {+ description: '持久性状态通知,用于展示信息、警告、错误或成功消息。',+ features: [+ '双区域布局:带图标、标题、描述、操作按钮和可选关闭按钮的彩色状态头部;下方可选的卡片背景内容区',+ '未提供 children 时,仅渲染彩色头部',+ '自管理关闭状态——横幅在关闭时自动隐藏,无需外部状态管理',+ 'onDismiss 回调在内部状态变更的同时触发,用于日志记录或后端同步',+ '默认状态图标来自 @heroicons/react/24/solid:InformationCircleIcon(info)、ExclamationTriangleIcon(warning)、XCircleIcon(error)、CheckCircleIcon(success)',+ '状态颜色:info 使用 --color-accent-muted,warning 使用 --color-warning-muted,error 使用 --color-error-muted,success 使用 --color-success-muted',+ 'Card 变体(默认):带圆角,彩色头部下方可选卡片内容区',+ 'Section 变体:无圆角,全宽,适用于页面级横幅',+ ],+ accessibility: [+ '错误和警告状态使用 role="alert"',+ '信息和成功状态使用 role="status"',+ '关闭按钮带有 aria-label="Dismiss"',+ '状态图标设置为 aria-hidden="true"——状态信息通过 ARIA role 传达',+ ],+ notes: [+ 'Banner 使用 `status` 作为可扩展的主题轴。通过 defineTheme components 添加自定义状态:`status:neutral`。',+ '折叠支持已规划:内容区将通过 useXDSCollapsible 支持折叠(issue #187)',+ ],+ },props: [- {- name: 'status',- type: "'info' | 'warning' | 'error' | 'success'",- description: '状态类型,控制图标和颜色。',- required: true,- },- {- name: 'title',- type: 'ReactNode',- description: '显示在头部的标题文本或 ReactNode。',- required: true,- },- {- name: 'description',- type: 'ReactNode',- description: '渲染在头部标题下方的描述文本。',- },- {- name: 'icon',- type: 'ReactNode',- description: '覆盖默认的状态图标。',- },- {- name: 'isDismissable',- type: 'boolean',- description: '横幅是否可被用户关闭。',- default: 'false',- },- {- name: 'onDismiss',- type: '() => void',- description:- '点击关闭按钮时调用;无论是否提供此回调,横幅都会自动隐藏。',- },- {- name: 'endContent',- type: 'ReactNode',- description:- '渲染在头部区域末端对齐的操作内容,通常是按钮或链接。',- },- {- name: 'container',- type: "'card' | 'section'",- description:- '视觉变体:card 带圆角;section 无圆角全宽,适用于页面级场景。',- default: "'card'",- },- {- name: 'children',- type: 'ReactNode',- description:- '渲染在彩色头部下方卡片背景区域的内容。',- },+ {name: 'status', type: "'info' | 'warning' | 'error' | 'success'", description: '状态类型,控制图标和颜色。', required: true},+ {name: 'title', type: 'ReactNode', description: '显示在头部的标题文本或 ReactNode。', required: true},+ {name: 'description', type: 'ReactNode', description: '渲染在头部标题下方的描述文本。'},+ {name: 'icon', type: 'ReactNode', description: '覆盖默认的状态图标。'},+ {name: 'isDismissable', type: 'boolean', description: '横幅是否可被用户关闭。', default: 'false'},+ {name: 'onDismiss', type: '() => void', description: '点击关闭按钮时调用;无论是否提供此回调,横幅都会自动隐藏。'},+ {name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容,通常是按钮或链接。'},+ {name: 'container', type: "'card' | 'section'", description: '视觉变体:card 带圆角;section 无圆角全宽,适用于页面级场景。', default: "'card'"},+ {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。'},{name: 'xstyle',type: 'StyleXStyles',@@ -203,27 +153,26 @@ export const docsZh = {'用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',},],-- accessibility: [- '错误和警告状态使用 role="alert"',- '信息和成功状态使用 role="status"',- '关闭按钮带有 aria-label="Dismiss"',- '状态图标设置为 aria-hidden="true"——状态信息通过 ARIA role 传达',- ],-theming: {targets: [- {className: 'xds-banner', visualProps: ['container', 'status']},- {className: 'xds-banner-icon', visualProps: ['status']},+ {+ className: 'xds-banner',+ visualProps: [+ 'container',+ 'status',+ ],+ },+ {+ className: 'xds-banner-icon',+ visualProps: [+ 'status',+ ],+ },],vars: [{name: '--banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)'},],},- notes: [- 'Banner 使用 `status` 作为可扩展的主题轴。通过 defineTheme components 添加自定义状态:`status:neutral`。',- '折叠支持已规划:内容区将通过 useXDSCollapsible 支持折叠(issue #187)',- ],};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjsindex ee5aa22096..c5be3998be 100644--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs@@ -2,29 +2,30 @@export const docs = {name: 'Breadcrumbs',- description: 'A navigation breadcrumb trail with semantic HTML.', keywords: ["breadcrumbs","breadcrumb","navigation","nav","crumbs","trail","path","hierarchy","wayfinding","steps"],- features: [- 'Renders a <nav> landmark with an ordered list of breadcrumb items',- 'Configurable separator between items (defaults to /)',- 'Two visual variants: default and supporting (smaller, secondary text)',- 'Current page item is marked with aria-current="page"',- 'Separators are hidden from assistive technology via aria-hidden',- 'Supports icons before item labels via startIcon',- 'Auto-detects the last child as the current page when no isCurrent is set',- ],+ keywords: ["breadcrumbs","breadcrumb","navigation","nav","crumbs","trail","path","hierarchy","wayfinding","steps"],+ usage: {+ description:+ 'A secondary navigation trail with semantic HTML that orients the user within a content hierarchy. Use to show the user\'s position relative to the product architecture and enable quick back-and-forth navigation.',+ features: [+ 'Configurable separator between items (defaults to /)',+ 'Two visual variants: default and supporting (smaller, secondary text)',+ 'Supports icons before item labels via startIcon',+ 'Auto-detects the last child as the current page when no isCurrent is set',+ ],+ accessibility: [+ 'Container renders as a <nav aria-label> landmark; the label defaults to "Breadcrumb" and is customizable via the label prop',+ 'Items are placed inside an <ol> with individual <li> wrappers for correct list semantics',+ 'The current page item receives aria-current="page"',+ 'Separators are rendered with aria-hidden="true" so screen readers skip them',+ 'Auto-detects the last child as the current item when no isCurrent prop is explicitly set',+ ],+ },theming: {targets: [{className: 'xds-breadcrumb-item'},{className: 'xds-breadcrumbs', visualProps: ['variant']},],},- accessibility: [- 'Container renders as a <nav aria-label> landmark; the label defaults to "Breadcrumb" and is customizable via the label prop',- 'Items are placed inside an <ol> with individual <li> wrappers for correct list semantics',- 'The current page item receives aria-current="page"',- 'Separators are rendered with aria-hidden="true" so screen readers skip them',- 'Auto-detects the last child as the current item when no isCurrent prop is explicitly set',- ],components: [{name: 'XDSBreadcrumbs',@@ -107,74 +108,50 @@ export const docs = {],},],- usage: {- summary: 'A secondary form of navigation that orients the user within a hierarchy.',- content: `## When to use--- To show the user's position relative to the product architecture.-- To enable quick back-and-forth navigation.-- To organize content hierarchy of 2 or more levels.`,- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Breadcrumbs',- description: '带语义化 HTML 的导航面包屑路径。',- features: [- '渲染包含有序面包屑项列表的 <nav> 地标元素',- '可配置项目间的分隔符(默认为 /)',- '两种视觉变体:default 和 supporting(更小,次要文本样式)',- '当前页面项标记为 aria-current="page"',- '分隔符通过 aria-hidden 对辅助技术隐藏',- '通过 startIcon 支持在项目标签前显示图标',- '未设置 isCurrent 时自动检测最后一个子元素为当前页面',- ],+ usage: {+ description: '带语义化 HTML 的导航面包屑路径。',+ features: [+ '渲染包含有序面包屑项列表的 <nav> 地标元素',+ '可配置项目间的分隔符(默认为 /)',+ '两种视觉变体:default 和 supporting(更小,次要文本样式)',+ '当前页面项标记为 aria-current="page"',+ '分隔符通过 aria-hidden 对辅助技术隐藏',+ '通过 startIcon 支持在项目标签前显示图标',+ '未设置 isCurrent 时自动检测最后一个子元素为当前页面',+ ],+ accessibility: [+ '容器渲染为 <nav aria-label> 地标元素;标签默认为 "Breadcrumb",可通过 label 属性自定义',+ '项目放置在 <ol> 内,每个项目用 <li> 包裹以确保正确的列表语义',+ '当前页面项接收 aria-current="page"',+ '分隔符使用 aria-hidden="true" 渲染,屏幕阅读器会跳过它们',+ '未显式设置 isCurrent 属性时,自动检测最后一个子元素为当前项',+ ],+ },theming: {targets: [{className: 'xds-breadcrumb-item'},- {className: 'xds-breadcrumbs', visualProps: ['variant']},+ {+ className: 'xds-breadcrumbs',+ visualProps: [+ 'variant',+ ],+ },],},- accessibility: [- '容器渲染为 <nav aria-label> 地标元素;标签默认为 "Breadcrumb",可通过 label 属性自定义',- '项目放置在 <ol> 内,每个项目用 <li> 包裹以确保正确的列表语义',- '当前页面项接收 aria-current="page"',- '分隔符使用 aria-hidden="true" 渲染,屏幕阅读器会跳过它们',- '未显式设置 isCurrent 属性时,自动检测最后一个子元素为当前项',- ],components: [{name: 'XDSBreadcrumbs',- description:- '导航容器,渲染包含有序面包屑项列表的 <nav> 元素。',+ 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: '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',@@ -185,44 +162,14 @@ export const docsZh = {},{name: 'XDSBreadcrumbItem',- description:- '单个面包屑项,提供 href 时渲染为链接,当前页面渲染为纯文本。',+ 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 设置的默认值。仅适用于非当前项。',- },+ {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 设置的默认值。仅适用于非当前项。'},],},],diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjsindex 092963ab1f..3ec0828277 100644--- a/packages/core/src/Button/Button.doc.mjs+++ b/packages/core/src/Button/Button.doc.mjs@@ -2,21 +2,50 @@export const docs = {name: 'Button',- description:- 'XDSButton component with multiple variants, sizes, and isLoading state support.',keywords: ["button","btn","cta","submit","action","loading","primary","secondary","ghost","destructive","danger"],- features: [- "Variants: 'primary', 'secondary', 'ghost', 'destructive'",- 'Sizes: sm (28px), md (32px), lg (36px)',- 'Loading state: Shows spinner, disables interaction, announces via live region',- 'Focus visible: Accessible focus outline with variant-specific colors',- 'Hover/active states: Uses overlay colors via backgroundImage for consistent layering',- 'Reduced motion: Respects prefers-reduced-motion for transitions',- 'Tooltip + disabled: Uses aria-disabled instead of native disabled so the button stays focusable for keyboard tooltip access',- 'Form integration: type, name, value, form props for native form submission',- 'Async actions: onClickAction with automatic loading state via useTransition',- ],++ usage: {+ description:+ 'Buttons provide visual cues for actions and events, allowing users to commit actions and navigate a page flow. XDSButton supports primary, secondary, ghost, and destructive variants across three sizes, with built-in loading states and async action handling. Use secondary for most actions, reserve primary for a single emphasized action per layout, and destructive for deletion with confirmation.',+ features: [+ "Variants: 'primary', 'secondary', 'ghost', 'destructive'",+ 'Sizes: sm (28px), md (32px), lg (36px)',+ 'Loading state: Shows spinner, disables interaction, announces via live region',+ 'Focus visible: Accessible focus outline with variant-specific colors',+ 'Reduced motion: Respects prefers-reduced-motion for transitions',+ 'Tooltip + disabled: Uses aria-disabled instead of native disabled so the button stays focusable for keyboard tooltip access',+ 'Form integration: type, name, value, form props for native form submission',+ 'Async actions: onClickAction with automatic loading state via useTransition',+ ],+ accessibility: [+ 'Renders a native <button> element for correct semantics and keyboard support',+ 'Icon-only buttons (isIconOnly={true}) set aria-label from the label prop',+ 'Loading state sets aria-busy and announces "Loading" via a role="status" live region',+ 'Content is hidden from assistive tech during loading via aria-hidden',+ 'When tooltip is present and button is disabled, uses aria-disabled instead of native disabled to keep the button focusable for keyboard tooltip access',+ 'Warns in development when icon-only buttons have an empty label (WCAG 4.1.2)',+ 'aria-label, aria-busy, and aria-disabled are placed after ...props spread to prevent clobbering',+ 'Keyboard: Enter/Space activates the button; Tab/Shift+Tab moves focus in and out',+ ],+ notes: [+ 'XDSButtonVariant type is derived from the variants StyleX object using keyof typeof variants.',+ 'Hover/active states use backgroundImage with linear-gradient to layer overlay colors on top of the base background.',+ 'Destructive variant uses colorTokens.negative for its focus outline color.',+ 'endContent is wrapped in a <span> with color: inherit so icons/badges match the button text color across all variants.',+ 'When isIconOnly is true, the button renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon — SVG components, emoji, or text.',+ 'endContent is ignored when isIconOnly is true to preserve the square aspect ratio.',+ 'onClick fires before onClickAction; calling preventDefault in onClick prevents onClickAction from running.',+ 'type defaults to "button" (not "submit") to prevent accidental form submission.',+ 'Disabled background gradient is cleared (backgroundImage: none) to prevent hover tint leaking through opacity.',+ ],+ anatomy: [+ {name: 'Icon', required: false, description: 'A leading icon that visually represents the meaning of the button label.'},+ {name: 'Label', required: true, description: 'A text label describing the button action. Required for accessibility.'},+ {name: 'End content', required: false, description: 'Trailing content that provides affordance to the type of action performed. Recommended when the expected action is non-obvious.'},+ {name: 'Spinner', required: false, description: 'Indicates a loading state when the button action is not immediate.'},+ ],+ },props: [{@@ -114,16 +143,6 @@ export const docs = {'Async click handler. Shows loading state while the returned promise is pending.',},],- accessibility: [- 'Renders a native <button> element for correct semantics and keyboard support',- 'Icon-only buttons (isIconOnly={true}) set aria-label from the label prop',- 'Loading state sets aria-busy and announces "Loading" via a role="status" live region',- 'Content is hidden from assistive tech during loading via aria-hidden',- 'When tooltip is present and button is disabled, uses aria-disabled instead of native disabled to keep the button focusable for keyboard tooltip access',- 'Warns in development when icon-only buttons have an empty label (WCAG 4.1.2)',- 'aria-label, aria-busy, and aria-disabled are placed after ...props spread to prevent clobbering',- ],- keyboard: 'Enter/Space activates the button; Tab/Shift+Tab moves focus in and out',theming: {targets: [{className: 'xds-button', visualProps: ['size', 'variant']},@@ -136,178 +155,93 @@ export const docs = {{name: '--button-icon-only-aspect', description: 'Aspect ratio for icon-only buttons', default: '1 / 1'},],},- notes: [- 'XDSButtonVariant type is derived from the variants StyleX object using keyof typeof variants.',- 'Hover/active states use backgroundImage with linear-gradient to layer overlay colors on top of the base background.',- 'Destructive variant uses colorTokens.negative for its focus outline color.',- 'endContent is wrapped in a <span> with color: inherit so icons/badges match the button text color across all variants.',- 'When isIconOnly is true, the button renders as a perfect square (aspectRatio: 1/1), and label is used as aria-label (not rendered visually). Works with any ReactNode as the icon — SVG components, emoji, or text.',- 'endContent is ignored when isIconOnly is true to preserve the square aspect ratio.',- 'Prefer XDSButton over <div onClick> or <span onClick> for accessibility — it provides keyboard navigation, focus management, and screen reader support.',- 'Icon-only buttons are suitable for toolbars, action grids, and compact controls.',- 'onClick fires before onClickAction; calling preventDefault in onClick prevents onClickAction from running.',- 'type defaults to "button" (not "submit") to prevent accidental form submission.',- 'Disabled background gradient is cleared (backgroundImage: none) to prevent hover tint leaking through opacity.',- ],- usage: {- summary: 'Buttons provide visual cues for actions and events, allowing users to commit actions and navigate a page flow.',- content: `## When to use--- Submit a form.-- Start a new task or action.-- Trigger a new UI element to appear on the page.--## Variants--- **Secondary**: The standard button for most actions.-- **Ghost**: Use when you need to limit the visual prominence of a button.-- **Primary**: Use to draw emphasis to the primary action. A layout should only contain a single primary button.-- **Destructive**: Use when the resulting action is the deletion of an object. Destructive buttons should trigger a confirmation dialog before the action is completed.--## Best practices--Do:-- Convey clear action hierarchy: each surface should only have one primary button. Most buttons should use the secondary or ghost variant.-- Use sentence case and no punctuation for labels.-- Provide the logical next step in a task.-- Use only one call-to-action per button.-- Use an informative tone. Don't editorialize in a button.--Don't:-- Overuse primary buttons. Overusing colored buttons creates visual confusion and undermines page hierarchy.-- Use all uppercase or all lowercase text.-- Mix sizes in a single row.-- Add custom gradients, drop shadows, or custom padding.`,- anatomy: [- {name: 'Icon', required: false, description: 'A leading icon that visually represents the meaning of the button label.'},- {name: 'Label', required: true, description: 'A text label describing the button action. Required for accessibility.'},- {name: 'End content', required: false, description: 'Trailing content that provides affordance to the type of action performed. Recommended when the expected action is non-obvious.'},- {name: 'Spinner', required: false, description: 'Indicates a loading state when the button action is not immediate.'},- ],- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Button',- description:- 'XDSButton 组件,支持多种变体、尺寸和加载状态。',-- features: [- "变体:'primary'、'secondary'、'ghost'、'destructive'",- '尺寸:sm(28px)、md(32px)、lg(36px)',- '加载状态:显示加载旋转器,禁用交互,通过实时区域播报',- '焦点可见:带有变体特定颜色的无障碍焦点轮廓',- '悬停/激活状态:通过 backgroundImage 使用叠加颜色,实现一致的层级效果',- '减少动画:尊重 prefers-reduced-motion',- '工具提示 + 禁用:使用 aria-disabled 代替原生 disabled,使按钮保持可聚焦以供键盘访问工具提示',- '表单集成:type、name、value、form 属性支持原生表单提交',- '异步操作:onClickAction 通过 useTransition 自动显示加载状态',- ],-+ usage: {+ description: 'XDSButton 组件,支持多种变体、尺寸和加载状态。',+ features: [+ "变体:'primary'、'secondary'、'ghost'、'destructive'",+ '尺寸:sm(28px)、md(32px)、lg(36px)',+ '加载状态:显示加载旋转器,禁用交互,通过实时区域播报',+ '焦点可见:带有变体特定颜色的无障碍焦点轮廓',+ '悬停/激活状态:通过 backgroundImage 使用叠加颜色,实现一致的层级效果',+ '减少动画:尊重 prefers-reduced-motion',+ '工具提示 + 禁用:使用 aria-disabled 代替原生 disabled,使按钮保持可聚焦以供键盘访问工具提示',+ '表单集成:type、name、value、form 属性支持原生表单提交',+ '异步操作:onClickAction 通过 useTransition 自动显示加载状态',+ ],+ accessibility: [+ '渲染原生 <button> 元素以确保正确的语义和键盘支持',+ '纯图标按钮(icon 无 children)从 label 属性设置 aria-label',+ '加载状态设置 aria-busy 并通过 role="status" 实时区域播报"Loading"',+ '加载期间通过 aria-hidden 对辅助技术隐藏内容',+ '当存在工具提示且按钮禁用时,使用 aria-disabled 代替原生 disabled 以保持键盘可聚焦',+ '开发环境下,纯图标按钮标签为空时发出警告(WCAG 4.1.2)',+ 'aria-label、aria-busy、aria-disabled 放置在 ...props 展开之后以防止覆盖',+ 'Keyboard: Enter/Space 激活按钮;Tab/Shift+Tab 移入和移出焦点',+ ],+ notes: [+ 'XDSButtonVariant 类型通过 keyof typeof variants 从 variants StyleX 对象派生。',+ '悬停/激活状态使用 backgroundImage 和 linear-gradient 在基础背景上叠加覆盖颜色。',+ 'destructive 变体使用 colorTokens.negative 作为焦点轮廓颜色。',+ 'endContent 包裹在带有 color: inherit 的 <span> 中,使图标/徽章在所有变体中匹配按钮文本颜色。',+ '仅提供 icon 而不提供 children 时,按钮变为纯图标模式:渲染为正方形(aspectRatio: 1/1),label 用作 aria-label(不可视渲染)。支持任何 ReactNode 作为图标——SVG 组件、emoji 或文本。',+ '纯图标按钮(提供 icon 但不提供 children 时)会忽略 endContent,以保持正方形的宽高比。',+ '为了无障碍性,优先使用 XDSButton 而非 <div onClick> 或 <span onClick>——它提供键盘导航、焦点管理和屏幕阅读器支持。',+ '纯图标按钮适用于工具栏、操作网格和紧凑控件。',+ 'onClick 在 onClickAction 之前触发;在 onClick 中调用 preventDefault 会阻止 onClickAction 运行。',+ 'type 默认为 "button"(非 "submit")以防止意外的表单提交。',+ '禁用状态清除背景渐变(backgroundImage: none)以防止悬停色调通过不透明度泄漏。',+ ],+ },props: [- {- name: 'label',- type: 'string',- description:- '无障碍标签;纯图标按钮时用作 aria-label。',- required: true,- },+ {name: 'label', type: 'string', description: '无障碍标签;纯图标按钮时用作 aria-label。', required: true},{name: 'variant',type: "'primary' | 'secondary' | 'ghost' | 'destructive'",description: '视觉样式变体。',default: "'secondary'",},- {- name: 'size',- type: "'sm' | 'md' | 'lg'",- description: '尺寸变体。',- default: "'md'",- },- {- name: 'type',- type: "'button' | 'submit' | 'reset'",- description: 'HTML 按钮类型属性。',- default: "'button'",- },- {- name: 'name',- type: 'string',- description: '表单提交的 HTML name 属性。',- },- {- name: 'value',- type: 'string | number | readonly string[]',- description: '表单提交的 HTML value 属性。',- },- {- name: 'form',- type: 'string',- description: '通过 ID 将按钮与表单元素关联。',- },- {- name: 'isLoading',- type: 'boolean',- description: '显示加载旋转器并禁用交互。通过实时区域播报"Loading"。',- default: 'false',- },+ {name: 'size', type: "'sm' | 'md' | 'lg'", description: '尺寸变体。', default: "'md'"},+ {name: 'type', type: "'button' | 'submit' | 'reset'", description: 'HTML 按钮类型属性。', default: "'button'"},+ {name: 'name', type: 'string', description: '表单提交的 HTML name 属性。'},+ {name: 'value', type: 'string | number | readonly string[]', description: '表单提交的 HTML value 属性。'},+ {name: 'form', type: 'string', description: '通过 ID 将按钮与表单元素关联。'},+ {name: 'isLoading', type: 'boolean', description: '显示加载旋转器并禁用交互。通过实时区域播报"Loading"。', default: 'false'},{name: 'isDisabled',type: 'boolean',description: '禁用按钮。存在工具提示时,使用 aria-disabled 代替原生 disabled 以保持可聚焦。',default: 'false',},- {- name: 'icon',- type: 'ReactNode',- description:- '图标元素。仅提供 icon 而不提供 children 时,按钮渲染为正方形的纯图标按钮。',- },- {- name: 'children',- type: 'ReactNode',- description:- '按钮内容。与 icon 同时提供时,文本渲染在图标旁边。',- },+ {name: 'icon', type: 'ReactNode', description: '图标元素。仅提供 icon 而不提供 children 时,按钮渲染为正方形的纯图标按钮。'},+ {name: 'children', type: 'ReactNode', description: '按钮内容。与 icon 同时提供时,文本渲染在图标旁边。'},{name: 'endContent',type: 'ReactElement<XDSIconProps> | ReactElement<XDSBadgeProps>',description:'标签后方渲染的尾部图标或徽章。仅接受 <XDSIcon> 或 <XDSBadge>。纯图标按钮时忽略。颜色继承自按钮变体。',},- {- name: 'tooltip',- type: 'string',- description: '悬停时显示的提示文本。',- },- {- name: 'onClick',- type: '(e: MouseEvent) => void',- description:- '标准点击处理函数(从 ButtonHTMLAttributes 透传)。',- },+ {name: 'tooltip', type: 'string', description: '悬停时显示的提示文本。'},+ {name: 'onClick', type: '(e: MouseEvent) => void', description: '标准点击处理函数(从 ButtonHTMLAttributes 透传)。'},{name: 'onClickAction',type: '(e: MouseEvent) => void | Promise<void>',- description:- '异步点击处理函数。返回的 Promise 处于 pending 状态时显示加载状态。',+ description: '异步点击处理函数。返回的 Promise 处于 pending 状态时显示加载状态。',},],-- accessibility: [- '渲染原生 <button> 元素以确保正确的语义和键盘支持',- '纯图标按钮(icon 无 children)从 label 属性设置 aria-label',- '加载状态设置 aria-busy 并通过 role="status" 实时区域播报"Loading"',- '加载期间通过 aria-hidden 对辅助技术隐藏内容',- '当存在工具提示且按钮禁用时,使用 aria-disabled 代替原生 disabled 以保持键盘可聚焦',- '开发环境下,纯图标按钮标签为空时发出警告(WCAG 4.1.2)',- 'aria-label、aria-busy、aria-disabled 放置在 ...props 展开之后以防止覆盖',- ],- keyboard: 'Enter/Space 激活按钮;Tab/Shift+Tab 移入和移出焦点',theming: {targets: [- {className: 'xds-button', visualProps: ['size', 'variant']},+ {+ className: 'xds-button',+ visualProps: [+ 'size',+ 'variant',+ ],+ },],vars: [{name: '--button-radius', description: '圆角半径', default: 'var(--radius-element)'},@@ -317,19 +251,6 @@ export const docsZh = {{name: '--button-icon-only-aspect', description: '纯图标按钮的宽高比', default: '1 / 1'},],},- notes: [- 'XDSButtonVariant 类型通过 keyof typeof variants 从 variants StyleX 对象派生。',- '悬停/激活状态使用 backgroundImage 和 linear-gradient 在基础背景上叠加覆盖颜色。',- 'destructive 变体使用 colorTokens.negative 作为焦点轮廓颜色。',- 'endContent 包裹在带有 color: inherit 的 <span> 中,使图标/徽章在所有变体中匹配按钮文本颜色。',- '仅提供 icon 而不提供 children 时,按钮变为纯图标模式:渲染为正方形(aspectRatio: 1/1),label 用作 aria-label(不可视渲染)。支持任何 ReactNode 作为图标——SVG 组件、emoji 或文本。',- '纯图标按钮(提供 icon 但不提供 children 时)会忽略 endContent,以保持正方形的宽高比。',- '为了无障碍性,优先使用 XDSButton 而非 <div onClick> 或 <span onClick>——它提供键盘导航、焦点管理和屏幕阅读器支持。',- '纯图标按钮适用于工具栏、操作网格和紧凑控件。',- 'onClick 在 onClickAction 之前触发;在 onClick 中调用 preventDefault 会阻止 onClickAction 运行。',- 'type 默认为 "button"(非 "submit")以防止意外的表单提交。',- '禁用状态清除背景渐变(backgroundImage: none)以防止悬停色调通过不透明度泄漏。',- ],};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjsindex 6f225c1c56..555cde647b 100644--- a/packages/core/src/Calendar/Calendar.doc.mjs+++ b/packages/core/src/Calendar/Calendar.doc.mjs@@ -2,23 +2,38 @@export const docs = {name: 'Calendar',- description:- 'XDSCalendar component for date selection with single and range modes.',keywords: ["calendar","datepicker","date picker","rangepicker","date range","monthview","daypicker"],- features: [- "Selection Modes: 'single' (default) and 'range'",- 'Multi-Month Display: Show 1 or 2 months side by side',- 'Date Constraints: min, max, and custom dateConstraints functions',- 'Locale Options: weekStartsOn for configurable first day of week',- 'Week Numbers: Optional ISO week number column',- 'Controlled/Uncontrolled: Supports both patterns via value/defaultValue',- 'Keyboard: Escape cancels in-progress range selection',- 'A11y: day name headers use role="columnheader", day buttons expose data-date attribute',- 'A11y: outside days are aria-disabled and not clickable even when visible',- 'A11y: selected date receives roving tabindex priority over today',- 'Nav buttons auto-disable when min/max boundary is within the current month',- 'Motion: day cell transitions respect prefers-reduced-motion',- ],+ usage: {+ description:+ 'A calendar component for date selection supporting single and range selection modes with customizable constraints and locale options.',+ features: [+ "Selection Modes: 'single' (default) and 'range'",+ 'Multi-Month Display: Show 1 or 2 months side by side',+ 'Date Constraints: min, max, and custom dateConstraints functions',+ 'Locale Options: weekStartsOn for configurable first day of week',+ 'Week Numbers: Optional ISO week number column',+ 'Controlled/Uncontrolled: Supports both patterns via value/defaultValue',+ 'Nav buttons auto-disable when min/max boundary is within the current month',+ ],+ accessibility: [+ 'Keyboard: Escape cancels in-progress range selection',+ 'Day name headers use role="columnheader", day buttons expose data-date attribute',+ 'Outside days are aria-disabled and not clickable even when visible',+ 'Selected date receives roving tabindex priority over today',+ 'Day cell transitions respect prefers-reduced-motion',+ ],+ notes: [+ 'ISODateString type: `${number}${number}${number}${number}-${number}${number}-${number}${number}`',+ 'DayOfWeek type: 0 | 1 | 2 | 3 | 4 | 5 | 6',+ 'DateRange interface: { start: ISODateString; end: ISODateString }',+ 'Day buttons render a data-date="YYYY-MM-DD" attribute for testing and scripting',+ 'Roving tabindex priority: selected date > today > first enabled day',+ 'In range mode, pressing Escape resets the pending start date without firing onChange',+ 'Previous/next month buttons become disabled when the current view contains the min or max date',+ 'Outside days (adjacent month) are rendered with aria-disabled="true" and ignore clicks',+ 'Day cell transitions are suppressed under @media (prefers-reduced-motion: reduce)',+ ],+ },props: [{name: 'mode',@@ -103,136 +118,74 @@ export const docs = {{className: 'xds-calendar-day', states: ['selected', 'today', 'disabled', 'in-range']},],},- notes: [- 'ISODateString type: `${number}${number}${number}${number}-${number}${number}-${number}${number}`',- 'DayOfWeek type: 0 | 1 | 2 | 3 | 4 | 5 | 6',- 'DateRange interface: { start: ISODateString; end: ISODateString }',- 'Day buttons render a data-date="YYYY-MM-DD" attribute for testing and scripting',- 'Roving tabindex priority: selected date > today > first enabled day',- 'In range mode, pressing Escape resets the pending start date without firing onChange',- 'Previous/next month buttons become disabled when the current view contains the min or max date',- 'Outside days (adjacent month) are rendered with aria-disabled="true" and ignore clicks',- 'Day cell transitions are suppressed under @media (prefers-reduced-motion: reduce)',- ],- usage: {- summary: 'A calendar component for date selection supporting single and range selection modes.',- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Calendar',- description:- 'XDSCalendar 日历组件,支持单选和范围选择模式的日期选取。',- features: [- "选择模式:'single'(默认)和 'range'",- '多月显示:并排显示 1 或 2 个月份',- '日期约束:min、max 和自定义 dateConstraints 函数',- '区域选项:weekStartsOn 可配置每周的起始日',- '周数:可选的 ISO 周数列',- '受控/非受控:通过 value/defaultValue 支持两种模式',- '键盘:Escape 取消正在进行的范围选择',- '无障碍:星期名称使用 role="columnheader",日期按钮暴露 data-date 属性',- '无障碍:外部日期设为 aria-disabled 且不可点击',- '无障碍:选中日期获得漫游 tabindex 优先级',- '导航按钮在 min/max 边界所在月份时自动禁用',- '动效:日期单元格过渡遵循 prefers-reduced-motion',- ],+ usage: {+ description: 'XDSCalendar 日历组件,支持单选和范围选择模式的日期选取。',+ features: [+ "选择模式:'single'(默认)和 'range'",+ '多月显示:并排显示 1 或 2 个月份',+ '日期约束:min、max 和自定义 dateConstraints 函数',+ '区域选项:weekStartsOn 可配置每周的起始日',+ '周数:可选的 ISO 周数列',+ '受控/非受控:通过 value/defaultValue 支持两种模式',+ '键盘:Escape 取消正在进行的范围选择',+ '无障碍:星期名称使用 role="columnheader",日期按钮暴露 data-date 属性',+ '无障碍:外部日期设为 aria-disabled 且不可点击',+ '无障碍:选中日期获得漫游 tabindex 优先级',+ '导航按钮在 min/max 边界所在月份时自动禁用',+ '动效:日期单元格过渡遵循 prefers-reduced-motion',+ ],+ notes: [+ 'ISODateString 类型:`${number}${number}${number}${number}-${number}${number}-${number}${number}`',+ 'DayOfWeek 类型:0 | 1 | 2 | 3 | 4 | 5 | 6',+ 'DateRange 接口:{ start: ISODateString; end: ISODateString }',+ '日期按钮渲染 data-date="YYYY-MM-DD" 属性,用于测试和脚本',+ '漫游 tabindex 优先级:选中日期 > 今天 > 第一个启用日期',+ '范围模式下按 Escape 重置待选起始日期,不触发 onChange',+ '上/下月按钮在当前视图包含 min 或 max 日期时禁用',+ '外部日期(相邻月份)以 aria-disabled="true" 渲染且忽略点击',+ '日期单元格过渡在 @media (prefers-reduced-motion: reduce) 下被抑制',+ ],+ },props: [- {- name: 'mode',- type: "'single' | 'range'",- description: '选择模式。',- default: "'single'",- },- {- name: 'value',- type: 'ISODateString | DateRange',- description: '受控选中值。',- },- {- name: 'defaultValue',- type: 'ISODateString | DateRange',- description: '非受控默认值。',- },- {- name: 'onChange',- type: 'Function',- description: '选择回调函数。',- },- {- name: 'numberOfMonths',- type: '1 | 2',- description: '显示的月份数量。',- default: '1',- },- {- name: 'min',- type: 'ISODateString',- description: '可选择的最早日期。',- },- {- name: 'max',- type: 'ISODateString',- description: '可选择的最晚日期。',- },- {- name: 'dateConstraints',- type: 'Array<(date: Date) => boolean>',- description: '自定义约束函数。',- },- {- name: 'focusDate',- type: 'ISODateString',- description: '受控可见月份。',- },- {- name: 'onFocusDateChange',- type: '(focusDate: ISODateString) => void',- description: '导航回调函数。',- },- {- name: 'hasOutsideDays',- type: 'boolean',- description: '显示相邻月份的日期。',- default: 'true',- },- {- name: 'hasWeekNumbers',- type: 'boolean',- description: '显示 ISO 周数。',- default: 'false',- },- {- name: 'hasVariableRowCount',- type: 'boolean',- description: '可变行数与固定 6 行网格。',- default: 'false',- },- {- name: 'weekStartsOn',- type: '0 | 1 | 2 | 3 | 4 | 5 | 6',- description: '每周起始日(0=周日)。',- default: '0',- },+ {name: 'mode', type: "'single' | 'range'", description: '选择模式。', default: "'single'"},+ {name: 'value', type: 'ISODateString | DateRange', description: '受控选中值。'},+ {name: 'defaultValue', type: 'ISODateString | DateRange', description: '非受控默认值。'},+ {name: 'onChange', type: 'Function', description: '选择回调函数。'},+ {name: 'numberOfMonths', type: '1 | 2', description: '显示的月份数量。', default: '1'},+ {name: 'min', type: 'ISODateString', description: '可选择的最早日期。'},+ {name: 'max', type: 'ISODateString', description: '可选择的最晚日期。'},+ {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数。'},+ {name: 'focusDate', type: 'ISODateString', description: '受控可见月份。'},+ {name: 'onFocusDateChange', type: '(focusDate: ISODateString) => void', description: '导航回调函数。'},+ {name: 'hasOutsideDays', type: 'boolean', description: '显示相邻月份的日期。', default: 'true'},+ {name: 'hasWeekNumbers', type: 'boolean', description: '显示 ISO 周数。', default: 'false'},+ {name: 'hasVariableRowCount', type: 'boolean', description: '可变行数与固定 6 行网格。', default: 'false'},+ {name: 'weekStartsOn', type: '0 | 1 | 2 | 3 | 4 | 5 | 6', description: '每周起始日(0=周日)。', default: '0'},],theming: {targets: [- {className: 'xds-calendar', visualProps: ['mode']},- {className: 'xds-calendar-day', states: ['selected', 'today', 'disabled', 'in-range']},+ {+ className: 'xds-calendar',+ visualProps: [+ 'mode',+ ],+ },+ {+ className: 'xds-calendar-day',+ states: [+ 'selected',+ 'today',+ 'disabled',+ 'in-range',+ ],+ },],},- notes: [- 'ISODateString 类型:`${number}${number}${number}${number}-${number}${number}-${number}${number}`',- 'DayOfWeek 类型:0 | 1 | 2 | 3 | 4 | 5 | 6',- 'DateRange 接口:{ start: ISODateString; end: ISODateString }',- '日期按钮渲染 data-date="YYYY-MM-DD" 属性,用于测试和脚本',- '漫游 tabindex 优先级:选中日期 > 今天 > 第一个启用日期',- '范围模式下按 Escape 重置待选起始日期,不触发 onChange',- '上/下月按钮在当前视图包含 min 或 max 日期时禁用',- '外部日期(相邻月份)以 aria-disabled="true" 渲染且忽略点击',- '日期单元格过渡在 @media (prefers-reduced-motion: reduce) 下被抑制',- ],};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex cb774f6369..3e5e6a9348 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/src/Card/Card.doc.mjs@@ -2,16 +2,27 @@export const docs = {name: 'Card',- description: 'Card container component with shadow and themed styling.',keywords: ["card","surface","panel","container","elevated","shadow","box","paper","tile","well"],- features: [- 'Top-level container for elevated content',- 'Provides card-specific appearance: background, shadow, and border-radius',- 'Sets CSS variables for child layout components',- 'Supports `padding={0}` for edge-to-edge content',- 'Composable with XDSLayout, XDSCollapsible, and XDSCollapsibleGroup',- 'Background color variants: default, muted, and 10 non-semantic palette colors',- ],+ usage: {+ description:+ 'Card container that groups related information inside elevated containers for visual organization. Use when explicit grouping is needed — prefer sections as the default and escalate to cards only when stronger visual distinction is required.',+ features: [+ 'Top-level container for elevated content',+ 'Provides card-specific appearance: background, shadow, and border-radius',+ 'Supports `padding={0}` for edge-to-edge content',+ 'Composable with XDSLayout, XDSCollapsible, and XDSCollapsibleGroup',+ 'Background color variants: default, muted, and 10 non-semantic palette colors',+ ],+ notes: [+ 'Sets CSS variables for child layout components',+ 'Card elevation adapts automatically based on the background surface.',+ ],+ anatomy: [+ {name: 'Card Header', required: false, description: 'Displays a title and optional end content.'},+ {name: 'Card Body', required: true, description: 'Accepts any content.'},+ {name: 'Card Footer', required: false, description: 'Contains actions.'},+ ],+ },props: [{name: 'width',@@ -69,72 +80,28 @@ export const docs = {},],},- usage: {- summary: 'Groups similar information inside containers for visual organization.',- content: `## When to use--- When explicit grouping of related information is needed.-- When browsing and scanning content is frequent.--## Best practices--- Do: Use whitespace, type scale, and dividers with cards.-- Do: Prioritize sections as the default; use cards only for stronger visual distinction.-- Don't: Exclusively use cards, as it diminishes visual hierarchy.-- Don't: Use cards for primary content unless stronger visual separation is needed.-- Start with sections; escalate to cards only when additional distinction is required.-- Card elevation adapts automatically based on the background surface.`,- anatomy: [- {name: 'Card Header', required: false, description: 'Displays a title and optional end content.'},- {name: 'Card Body', required: true, description: 'Accepts any content.'},- {name: 'Card Footer', required: false, description: 'Contains actions.'},- ],- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Card',- description: '具有阴影和主题样式的卡片容器组件。',- features: [- '用于承载内容的顶层容器',- '提供卡片特有的外观:背景、阴影和圆角',- '为子布局组件设置 CSS 变量',- '支持 `padding={0}` 实现边到边内容',- '可与 XDSLayout、XDSCollapsible 和 XDSCollapsibleGroup 组合使用',- ],+ usage: {+ description: '具有阴影和主题样式的卡片容器组件。',+ features: [+ '用于承载内容的顶层容器',+ '提供卡片特有的外观:背景、阴影和圆角',+ '为子布局组件设置 CSS 变量',+ '支持 `padding={0}` 实现边到边内容',+ '可与 XDSLayout、XDSCollapsible 和 XDSCollapsibleGroup 组合使用',+ ],+ },props: [- {- name: 'width',- type: 'SizeValue',- description: '卡片宽度(数字 = 像素,字符串 = 按原样使用)。',- },- {- name: 'height',- type: 'SizeValue',- description: '卡片高度(数字 = 像素,字符串 = 按原样使用)。',- },- {- name: 'maxWidth',- type: 'SizeValue',- description: '卡片最大宽度。',- },- {- name: 'minHeight',- type: 'SizeValue',- description: '卡片最小高度。',- },- {- name: 'children',- type: 'ReactNode',- description: '在卡片内部渲染的内容。',- },- {- name: 'padding',- type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',- description: '使用间距比例的内边距。',- default: '4',- },+ {name: 'width', type: 'SizeValue', description: '卡片宽度(数字 = 像素,字符串 = 按原样使用)。'},+ {name: 'height', type: 'SizeValue', description: '卡片高度(数字 = 像素,字符串 = 按原样使用)。'},+ {name: 'maxWidth', type: 'SizeValue', description: '卡片最大宽度。'},+ {name: 'minHeight', type: 'SizeValue', description: '卡片最小高度。'},+ {name: 'children', type: 'ReactNode', description: '在卡片内部渲染的内容。'},+ {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: '使用间距比例的内边距。', default: '4'},],theming: {container: true,diff --git a/packages/core/src/Carousel/Carousel.doc.mjs b/packages/core/src/Carousel/Carousel.doc.mjsindex 8eda9f50c8..5423b746be 100644--- a/packages/core/src/Carousel/Carousel.doc.mjs+++ b/packages/core/src/Carousel/Carousel.doc.mjs@@ -2,18 +2,29 @@export const docs = {name: 'Carousel',- description:- 'Horizontal scroll container with fade-edge overflow indication, optional navigation buttons, and scroll-snap support.',keywords: ['carousel', 'slider', 'scroll', 'gallery', 'filmstrip', 'swiper', 'horizontal', 'overflow', 'snap'],- features: [- 'Overflow Detection: Gradient fades appear at edges when content overflows, signaling more items',- 'Navigation Buttons: Prev/next buttons appear on hover (desktop only) via XDSLayer top-layer rendering',- 'Scroll Snap: Optional snap-to-item behavior for precise item alignment',- 'Gap Scale: Configurable item spacing using the spacing token scale (0 to 4)',- 'Scale Animation: Items scale down slightly when entering/exiting the viewport via scroll-driven animation',- 'Accessible: role="region" with aria-roledescription="carousel" and configurable aria-label',- 'Reduced Motion: Respects prefers-reduced-motion for scroll behavior and entry animations',- ],+ usage: {+ description:+ 'Horizontal scroll container with fade-edge overflow indication, optional navigation buttons, and scroll-snap support.',+ features: [+ 'Overflow Detection: Gradient fades appear at edges when content overflows, signaling more items',+ 'Navigation Buttons: Prev/next buttons appear on hover (desktop only) via XDSLayer top-layer rendering',+ 'Scroll Snap: Optional snap-to-item behavior for precise item alignment',+ 'Gap Scale: Configurable item spacing using the spacing token scale (0 to 4)',+ 'Scale Animation: Items scale down slightly when entering/exiting the viewport via scroll-driven animation',+ ],+ accessibility: [+ 'Root element uses role="region" with aria-roledescription="carousel" for screen reader context.',+ 'Navigation buttons have accessible labels ("Scroll left", "Scroll right").',+ 'Scroll behavior and scale animations respect prefers-reduced-motion.',+ ],+ notes: [+ 'Navigation buttons render on the top layer via XDSLayer, so they escape parent overflow clipping.',+ 'The fade-edge effect uses CSS mask-image gradients that transition smoothly.',+ 'Each child is wrapped in a flex-shrink:0 container with scroll-snap-align:start when snap is enabled.',+ 'Items use scroll-driven animation (animationTimeline: view(inline)) for the scale effect.',+ ],+ },props: [{name: 'children', type: 'ReactNode', description: 'Carousel items rendered in a horizontal scroll container.', required: true},{name: 'gap', type: "0 | 0.5 | 1 | 1.5 | 2 | 3 | 4", description: 'Gap between items using the spacing token scale.', default: '1'},@@ -31,31 +42,33 @@ export const docs = {{className: 'xds-carousel'},],},- accessibility: [- 'Root element uses role="region" with aria-roledescription="carousel" for screen reader context.',- 'Navigation buttons have accessible labels ("Scroll left", "Scroll right").',- 'Scroll behavior and scale animations respect prefers-reduced-motion.',- ],- notes: [- 'Navigation buttons render on the top layer via XDSLayer, so they escape parent overflow clipping.',- 'The fade-edge effect uses CSS mask-image gradients that transition smoothly.',- 'Each child is wrapped in a flex-shrink:0 container with scroll-snap-align:start when snap is enabled.',- 'Items use scroll-driven animation (animationTimeline: view(inline)) for the scale effect.',- ],};/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description: '水平滚动容器,具有渐变边缘溢出指示、可选导航按钮和滚动吸附支持。',- features: [- '溢出检测:当内容溢出时,边缘出现渐变淡化效果,提示还有更多项目',- '导航按钮:鼠标悬停时显示上一个/下一个按钮(仅桌面端),通过 XDSLayer 顶层渲染',- '滚动吸附:可选的吸附到项目行为,实现精确的项目对齐',- '间距比例:使用间距令牌比例(0 到 4)配置项目间距',- '缩放动画:项目在进入/离开视口时通过滚动驱动动画略微缩小',- '无障碍:role="region",带 aria-roledescription="carousel" 和可配置的 aria-label',- '减少动效:尊重 prefers-reduced-motion 的滚动行为和入场动画',- ],+ usage: {+ description: '水平滚动容器,具有渐变边缘溢出指示、可选导航按钮和滚动吸附支持。',+ features: [+ '溢出检测:当内容溢出时,边缘出现渐变淡化效果,提示还有更多项目',+ '导航按钮:鼠标悬停时显示上一个/下一个按钮(仅桌面端),通过 XDSLayer 顶层渲染',+ '滚动吸附:可选的吸附到项目行为,实现精确的项目对齐',+ '间距比例:使用间距令牌比例(0 到 4)配置项目间距',+ '缩放动画:项目在进入/离开视口时通过滚动驱动动画略微缩小',+ '无障碍:role="region",带 aria-roledescription="carousel" 和可配置的 aria-label',+ '减少动效:尊重 prefers-reduced-motion 的滚动行为和入场动画',+ ],+ accessibility: [+ '根元素使用 role="region" 和 aria-roledescription="carousel",为屏幕阅读器提供上下文。',+ '导航按钮具有无障碍标签("向左滚动"、"向右滚动")。',+ '滚动行为和缩放动画尊重 prefers-reduced-motion。',+ ],+ notes: [+ '导航按钮通过 XDSLayer 在顶层渲染,因此它们可以逃离父级溢出裁剪。',+ '渐变边缘效果使用 CSS mask-image 渐变,过渡平滑。',+ '启用吸附时,每个子元素被包裹在 flex-shrink:0 容器中,带有 scroll-snap-align:start。',+ '项目使用滚动驱动动画(animationTimeline: view(inline))实现缩放效果。',+ ],+ },propDescriptions: {children: '在水平滚动容器中渲染的轮播项目。',gap: '使用间距令牌比例的项目间距。',@@ -63,17 +76,6 @@ export const docsZh = {hasSnap: '启用滚动吸附,使每个子元素吸附到起始边缘。','aria-label': '轮播区域的无障碍标签。',},- accessibility: [- '根元素使用 role="region" 和 aria-roledescription="carousel",为屏幕阅读器提供上下文。',- '导航按钮具有无障碍标签("向左滚动"、"向右滚动")。',- '滚动行为和缩放动画尊重 prefers-reduced-motion。',- ],- notes: [- '导航按钮通过 XDSLayer 在顶层渲染,因此它们可以逃离父级溢出裁剪。',- '渐变边缘效果使用 CSS mask-image 渐变,过渡平滑。',- '启用吸附时,每个子元素被包裹在 flex-shrink:0 容器中,带有 scroll-snap-align:start。',- '项目使用滚动驱动动画(animationTimeline: view(inline))实现缩放效果。',- ],};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjsindex a5d75c40e2..5a1097c46d 100644--- a/packages/core/src/Center/Center.doc.mjs+++ b/packages/core/src/Center/Center.doc.mjs@@ -2,13 +2,7 @@export const docs = {name: 'Center',- description: 'Centers children horizontally and/or vertically using flexbox.',keywords: ["center","centered","centering","align","alignment","justify","flexbox","middle"],- features: [- 'Supports centering on both axes, horizontal only, or vertical only',- 'Inline-flex mode for centering inline content such as text and icons',- 'Accepts explicit width and height to size the container',- ],props: [{name: 'axis',@@ -50,47 +44,32 @@ export const docs = {],},usage: {- summary: 'Centers children horizontally and/or vertically using flexbox.',+ description: 'Centers children horizontally and/or vertically using flexbox.',+ features: [+ 'Supports centering on both axes, horizontal only, or vertical only',+ 'Inline-flex mode for centering inline content such as text and icons',+ 'Accepts explicit width and height to size the container',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Center',- description: '使用 flexbox 将子元素水平和/或垂直居中。',- features: [- '支持双轴居中、仅水平居中或仅垂直居中',- '内联 flex 模式,用于居中文本和图标等内联内容',- '接受显式的宽度和高度来设置容器尺寸',- ],+ usage: {+ description: '使用 flexbox 将子元素水平和/或垂直居中。',+ features: [+ '支持双轴居中、仅水平居中或仅垂直居中',+ '内联 flex 模式,用于居中文本和图标等内联内容',+ '接受显式的宽度和高度来设置容器尺寸',+ ],+ },props: [- {- name: 'axis',- type: "'both' | 'horizontal' | 'vertical'",- description: '居中的方向。',- default: "'both'",- },- {- name: 'width',- type: 'number | string',- description: '容器宽度(px 或 CSS 值)。',- },- {- name: 'height',- type: 'number | string',- description: '容器高度(px 或 CSS 值)。',- },- {- name: 'isInline',- type: 'boolean',- description: '使用 inline-flex(适用于文本/图标)。',- default: 'false',- },- {- name: 'children',- type: 'ReactNode',- description: '要居中的内容。',- },+ {name: 'axis', type: "'both' | 'horizontal' | 'vertical'", description: '居中的方向。', default: "'both'"},+ {name: 'width', type: 'number | string', description: '容器宽度(px 或 CSS 值)。'},+ {name: 'height', type: 'number | string', description: '容器高度(px 或 CSS 值)。'},+ {name: 'isInline', type: 'boolean', description: '使用 inline-flex(适用于文本/图标)。', default: 'false'},+ {name: 'children', type: 'ReactNode', description: '要居中的内容。'},{name: 'xstyle',type: 'StyleXStyles',@@ -100,7 +79,12 @@ export const docsZh = {],theming: {targets: [- {className: 'xds-center', visualProps: ['axis']},+ {+ className: 'xds-center',+ visualProps: [+ 'axis',+ ],+ },],},};diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjsindex 2c0c241834..155b7ec7ce 100644--- a/packages/core/src/Chat/Chat.doc.mjs+++ b/packages/core/src/Chat/Chat.doc.mjs@@ -2,29 +2,7 @@export const docs = {name: 'Chat',- description:- 'Chat components for AI chat interfaces. Layout (MessageList, Message, Bubble, SystemMessage) + Composer (Composer, ComposerInput with trigger menus, ComposerAttachments).',keywords: ['chat', 'message', 'bubble', 'conversation', 'ai', 'assistant', 'thread', 'system-message', 'composer', 'mention', 'trigger', 'typeahead', 'token', 'imperative', 'tokenized-text'],- features: [- 'Composition model — MessageList > Message > Bubble',- 'Sender-aware styling (user, assistant, system) via context',- 'Auto-scroll with "New messages" indicator',- 'Infinite scroll via onScrollToTopAction with useTransition',- 'Density variants: compact, balanced, spacious (flows via context)',- 'System messages with optional divider variant for date separators',- 'Free-form children — not all content needs a bubble',- 'Timestamp display: hover or header',- 'Message status indicators (sending, sent, delivered, read, error)',- 'role="log" with aria-live="polite" for accessibility',- 'Composer layout shell with named semantic slots',- 'ContentEditable input with @ mention and / command trigger menus',- 'Imperative handle on ComposerInput for programmatic token/text insertion',- 'Tokenized text rendering in message bubbles via XDSChatTokenizedText',- 'XDSSearchSource integration — reuses Typeahead search sources',- 'Concentric radius — inner elements follow outer shell curvature',- 'Themeable via --composer-radius and --composer-padding CSS vars',- 'Extractable send/stop button (XDSChatSendButton) with automatic composer context',- ],theming: {targets: [{className: 'xds-chat-layout', visualProps: ['density']},@@ -184,7 +162,27 @@ export const docs = {},],usage: {- summary: 'Chat components for building AI chat interfaces, including message lists, message bubbles, a composer, and a layout shell.',+ description: 'Chat components for building AI chat interfaces. Provides layout primitives (MessageList, Message, Bubble, SystemMessage) and a composer with trigger menus and attachments for constructing full chat experiences.',+ features: [+ 'Composition model — MessageList > Message > Bubble',+ 'Sender-aware styling (user, assistant, system) via context',+ 'Auto-scroll with "New messages" indicator',+ 'Infinite scroll via onScrollToTopAction with useTransition',+ 'Density variants: compact, balanced, spacious (flows via context)',+ 'System messages with optional divider variant for date separators',+ 'Free-form children — not all content needs a bubble',+ 'Timestamp display: hover or header',+ 'Message status indicators (sending, sent, delivered, read, error)',+ 'role="log" with aria-live="polite" for accessibility',+ 'Composer layout shell with named semantic slots',+ 'ContentEditable input with @ mention and / command trigger menus',+ 'Imperative handle on ComposerInput for programmatic token/text insertion',+ 'Tokenized text rendering in message bubbles via XDSChatTokenizedText',+ 'XDSSearchSource integration — reuses Typeahead search sources',+ 'Concentric radius — inner elements follow outer shell curvature',+ 'Themeable via --composer-radius and --composer-padding CSS vars',+ 'Extractable send/stop button (XDSChatSendButton) with automatic composer context',+ ],},};@@ -215,28 +213,30 @@ docs.components.push(chatLayoutScrollButtonComponent);/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description:- 'AI 聊天界面组件。布局(MessageList、Message、Bubble、SystemMessage)+ 编写器(Composer、ComposerInput 触发菜单、ComposerAttachments)。',- features: [- '组合模型 — MessageList > Message > Bubble',- '根据发送者自动调整样式(user、assistant、system),通过上下文传递',- '自动滚动,带有"新消息"指示器',- '通过 onScrollToTopAction 和 useTransition 实现无限滚动',- '密度变体:compact、balanced、spacious(通过上下文传递)',- '系统消息,可选分割线变体用于日期分隔',- '自由子元素 — 并非所有内容都需要气泡包裹',- '时间戳显示:悬停或标题',- '消息状态指示器(sending、sent、delivered、read、error)',- 'role="log" 配合 aria-live="polite" 实现无障碍访问',- '编写器布局外壳,具有命名语义插槽',- 'ContentEditable 输入框,支持 @ 提及和 / 命令触发菜单',- 'ComposerInput 命令式句柄,支持编程式插入标记/文本',- '通过 XDSChatTokenizedText 在消息气泡中渲染标记文本',- 'XDSSearchSource 集成 — 复用 Typeahead 搜索源',- '同心圆角 — 内部元素跟随外部外壳曲率',- '通过 --composer-radius 和 --composer-padding CSS 变量实现主题化',- '可提取的发送/停止按钮(XDSChatSendButton),自动读取编写器上下文',- ],+ usage: {+ description:+ 'AI 聊天界面组件。布局(MessageList、Message、Bubble、SystemMessage)+ 编写器(Composer、ComposerInput 触发菜单、ComposerAttachments)。',+ features: [+ '组合模型 — MessageList > Message > Bubble',+ '根据发送者自动调整样式(user、assistant、system),通过上下文传递',+ '自动滚动,带有"新消息"指示器',+ '通过 onScrollToTopAction 和 useTransition 实现无限滚动',+ '密度变体:compact、balanced、spacious(通过上下文传递)',+ '系统消息,可选分割线变体用于日期分隔',+ '自由子元素 — 并非所有内容都需要气泡包裹',+ '时间戳显示:悬停或标题',+ '消息状态指示器(sending、sent、delivered、read、error)',+ 'role="log" 配合 aria-live="polite" 实现无障碍访问',+ '编写器布局外壳,具有命名语义插槽',+ 'ContentEditable 输入框,支持 @ 提及和 / 命令触发菜单',+ 'ComposerInput 命令式句柄,支持编程式插入标记/文本',+ '通过 XDSChatTokenizedText 在消息气泡中渲染标记文本',+ 'XDSSearchSource 集成 — 复用 Typeahead 搜索源',+ '同心圆角 — 内部元素跟随外部外壳曲率',+ '通过 --composer-radius 和 --composer-padding CSS 变量实现主题化',+ '可提取的发送/停止按钮(XDSChatSendButton),自动读取编写器上下文',+ ],+ },components: [{name: 'XDSChatMessageList',@@ -274,20 +274,12 @@ export const docsZh = {{name: 'XDSChatMessageMetadata',description: '可组合的消息元数据行。渲染时间戳、页脚内容和发送状态。用户消息方向反转。',- propDescriptions: {- timestamp: '时间戳内容 — 字符串或 XDSTimestamp 组件。',- footer: '页脚内容 — 模型信息、反应按钮、复制按钮。',- status: '消息发送状态。显示图标和标签。',- },+ propDescriptions: {timestamp: '时间戳内容 — 字符串或 XDSTimestamp 组件。', footer: '页脚内容 — 模型信息、反应按钮、复制按钮。', status: '消息发送状态。显示图标和标签。'},},{name: 'XDSChatSystemMessage',description: '居中的系统/通知消息,用于日期分隔、状态更新和非发送者内容。',- propDescriptions: {- children: '系统消息内容。',- variant: '视觉变体。divider 在两侧添加水平线(内部使用 XDSDivider)。',- icon: '文本前渲染的图标。通常是 XDSIcon。',- },+ propDescriptions: {children: '系统消息内容。', variant: '视觉变体。divider 在两侧添加水平线(内部使用 XDSDivider)。', icon: '文本前渲染的图标。通常是 XDSIcon。'},},{name: 'XDSChatComposer',@@ -314,7 +306,8 @@ export const docsZh = {},{name: 'XDSChatComposerInput',- description: '基于 ContentEditable 的富文本输入,支持触发菜单(@ 提及、/ 命令)、内联标记、序列化、消息历史和粘贴/拖放文件处理。提供命令式句柄用于编程式控制。',+ description:+ '基于 ContentEditable 的富文本输入,支持触发菜单(@ 提及、/ 命令)、内联标记、序列化、消息历史和粘贴/拖放文件处理。提供命令式句柄用于编程式控制。',propDescriptions: {ref: '命令式句柄引用,暴露 insertToken、insertText、focus 和 getValue。',value: '受控值。',@@ -334,14 +327,12 @@ export const docsZh = {{name: 'XDSChatComposerAttachments',description: '编写器内附件项目的弹性换行容器。',- propDescriptions: {- children: '要渲染的附件项目。',- count: '附件总数。超过可见子元素时显示折叠/展开切换。',- },+ propDescriptions: {children: '要渲染的附件项目。', count: '附件总数。超过可见子元素时显示折叠/展开切换。'},},{name: 'XDSChatSendButton',- description: '编写器的圆形发送/停止切换按钮。默认从 XDSChatComposerContext 读取状态,在 XDSChatComposer 内自动工作。所有上下文值均可通过 props 覆盖以用于独立使用。',+ description:+ '编写器的圆形发送/停止切换按钮。默认从 XDSChatComposerContext 读取状态,在 XDSChatComposer 内自动工作。所有上下文值均可通过 props 覆盖以用于独立使用。',propDescriptions: {isStreaming: '助手是否正在流式响应。默认使用上下文值。',isDisabled: '发送按钮是否禁用。默认使用上下文的 !canSend。',@@ -355,9 +346,11 @@ export const docsZh = {},{name: 'XDSChatToolCalls',- description: '显示 LLM 响应中的工具/函数调用。接受与 LLM API 返回形状匹配的 calls 数组。单个调用内联渲染;多个调用显示可折叠摘要。',+ description:+ '显示 LLM 响应中的工具/函数调用。接受与 LLM API 返回形状匹配的 calls 数组。单个调用内联渲染;多个调用显示可折叠摘要。',propDescriptions: {- calls: '工具调用数据数组。每项包含 name、status、target、duration、node、additions、deletions、stats、resultDetail。',+ calls:+ '工具调用数据数组。每项包含 name、status、target、duration、node、additions、deletions、stats、resultDetail。',label: '组的自定义摘要标签。省略时从数量自动生成。',isExpanded: '受控展开状态。',defaultIsExpanded: '默认展开状态(非受控)。',@@ -365,12 +358,10 @@ export const docsZh = {},},{-name: 'XDSChatTokenizedText',- description: '渲染带有标记模式的文本,将匹配的模式替换为内联 XDSBadge 组件。在 XDSChatMessageBubble 内使用,以徽章样式显示 @提及或其他标记。',- propDescriptions: {- children: '包含标记模式的消息文本。',- tokens: '标记定义。每个包含 pattern(匹配字符串)、label(显示文本)和可选 variant。',- },+ name: 'XDSChatTokenizedText',+ description:+ '渲染带有标记模式的文本,将匹配的模式替换为内联 XDSBadge 组件。在 XDSChatMessageBubble 内使用,以徽章样式显示 @提及或其他标记。',+ propDescriptions: {children: '包含标记模式的消息文本。', tokens: '标记定义。每个包含 pattern(匹配字符串)、label(显示文本)和可选 variant。'},},{name: 'XDSChatLayout',@@ -386,11 +377,7 @@ name: 'XDSChatTokenizedText',{name: 'XDSChatLayoutScrollButton',description: '可组合的滚动到底部按钮。可见时淡入,提供标签时展开。',- propDescriptions: {- isVisible: '按钮是否可见。',- label: '可选标签 — 展开按钮(如"新消息")。',- onClick: '点击处理器。',- },+ propDescriptions: {isVisible: '按钮是否可见。', label: '可选标签 — 展开按钮(如"新消息")。', onClick: '点击处理器。'},},],};diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjsindex c045695ab9..e7f6ce19ab 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs@@ -2,20 +2,7 @@export const docs = {name: 'CheckboxInput',- description: 'A checkbox input component for toggling boolean values.',keywords: ["checkbox","check","toggle","tick","indeterminate","boolean","tristate"],- features: [- 'Accessible — always includes a label (can be visually hidden)',- 'Indeterminate state — supports indeterminate for "select all" patterns',- 'Descriptions — optional description text below the label',- 'Sizes — sm (compact) and md (default)',- 'Async actions — onChangeAction with optimistic updates and loading spinner',- 'Status messages — error, warning, success validation feedback',- 'Optional/required indicators — label suffix with field state',- 'Label icons — optional icon before label text',- 'Disabled state — full support for disabled state styling',- 'Reduced motion — respects prefers-reduced-motion',- ],props: [{name: 'ref',@@ -117,122 +104,76 @@ export const docs = {{className: 'xds-checkbox'},],},- notes: [- 'Uses a hidden native <input type="checkbox"> for accessibility with a custom visual checkbox overlay.',- 'The visual checkbox responds to hover, focus, and checked states via ancestor selectors (stylex.when.ancestor).',- 'Label is clickable and properly associated with the input via htmlFor/id.',- 'Focus outline uses the standard XDS focus ring token.',- 'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling.',- ],usage: {- summary: 'A checkbox input for toggling boolean values.',- content: `## When to use--- Toggling a single boolean setting.-- Selecting multiple options from a set (use CheckboxList for groups).`,+ description: 'A checkbox input for toggling boolean values. Use for toggling a single boolean setting, or select multiple options from a set with CheckboxList for groups.',+ features: [+ 'Accessible — always includes a label (can be visually hidden)',+ 'Indeterminate state — supports indeterminate for "select all" patterns',+ 'Descriptions — optional description text below the label',+ 'Sizes — sm (compact) and md (default)',+ 'Async actions — onChangeAction with optimistic updates and loading spinner',+ 'Status messages — error, warning, success validation feedback',+ 'Optional/required indicators — label suffix with field state',+ 'Label icons — optional icon before label text',+ 'Disabled state — full support for disabled state styling',+ 'Reduced motion — respects prefers-reduced-motion',+ ],+ notes: [+ 'Uses a hidden native <input type="checkbox"> for accessibility with a custom visual checkbox overlay.',+ 'The visual checkbox responds to hover, focus, and checked states via ancestor selectors (stylex.when.ancestor).',+ 'Label is clickable and properly associated with the input via htmlFor/id.',+ 'Focus outline uses the standard XDS focus ring token.',+ 'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'CheckboxInput',- description: '复选框输入组件,用于切换布尔值。',- features: [- '无障碍——始终包含标签(可视觉隐藏)',- '不确定状态——支持"全选"模式的不确定状态',- '描述——标签下方可选的描述文本',- '尺寸——sm(紧凑)和 md(默认)',- '异步操作——onChangeAction 带乐观更新和加载旋转器',- '状态消息——错误、警告、成功验证反馈',- '可选/必填指示器——带字段状态的标签后缀',- '标签图标——标签文本前可选图标',- '禁用状态——完整支持禁用状态样式',- '减少动画——尊重 prefers-reduced-motion',- ],+ usage: {+ description: '复选框输入组件,用于切换布尔值。',+ features: [+ '无障碍——始终包含标签(可视觉隐藏)',+ '不确定状态——支持"全选"模式的不确定状态',+ '描述——标签下方可选的描述文本',+ '尺寸——sm(紧凑)和 md(默认)',+ '异步操作——onChangeAction 带乐观更新和加载旋转器',+ '状态消息——错误、警告、成功验证反馈',+ '可选/必填指示器——带字段状态的标签后缀',+ '标签图标——标签文本前可选图标',+ '禁用状态——完整支持禁用状态样式',+ '减少动画——尊重 prefers-reduced-motion',+ ],+ notes: [+ '使用隐藏的原生 <input type="checkbox"> 确保无障碍性,并覆盖自定义视觉复选框。',+ '视觉复选框通过祖先选择器(stylex.when.ancestor)响应悬停、焦点和选中状态。',+ '标签可点击,并通过 htmlFor/id 与输入框正确关联。',+ '焦点轮廓使用标准的 XDS 焦点环令牌。',+ '忙碌状态(加载中或异步操作等待中)期间阻止交互,防止重复切换。',+ ],+ },props: [- {- name: 'ref',- type: 'React.Ref<HTMLInputElement>',- description: '转发至底层 <input> 元素的 ref。',- },- {- name: 'label',- type: 'string',- description: '复选框的标签文本(始终为无障碍性而渲染)。',- required: true,- },- {- name: 'isLabelHidden',- type: 'boolean',- description: '是否视觉隐藏标签(屏幕阅读器仍可访问)。',- default: 'false',- },- {- name: 'description',- type: 'string',- description: '显示在标签下方的描述文本。',- },- {- name: 'value',- type: "boolean | 'indeterminate'",- description: '复选框是否为选中、未选中或不确定状态。',- required: true,- },- {- name: 'onChange',- type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void',- description: '复选框状态变更时触发的回调。',- },+ {name: 'ref', type: 'React.Ref<HTMLInputElement>', description: '转发至底层 <input> 元素的 ref。'},+ {name: 'label', type: 'string', description: '复选框的标签文本(始终为无障碍性而渲染)。', required: true},+ {name: 'isLabelHidden', type: 'boolean', description: '是否视觉隐藏标签(屏幕阅读器仍可访问)。', default: 'false'},+ {name: 'description', type: 'string', description: '显示在标签下方的描述文本。'},+ {name: 'value', type: "boolean | 'indeterminate'", description: '复选框是否为选中、未选中或不确定状态。', required: true},+ {name: 'onChange', type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void', description: '复选框状态变更时触发的回调。'},{name: 'onChangeAction',- type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',+ type:+ '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',description: '异步变更操作。在 onChange 之后触发(未被阻止时)。等待期间显示加载旋转器。',},- {- name: 'isLoading',- type: 'boolean',- description: '复选框是否处于加载状态。显示旋转器并阻止交互。',- default: 'false',- },- {- name: 'isDisabled',- type: 'boolean',- description: '复选框是否禁用。',- default: 'false',- },- {- name: 'isOptional',- type: 'boolean',- description: '字段是否可选。与 isRequired 互斥。',- default: 'false',- },- {- name: 'isRequired',- type: 'boolean',- description: '复选框是否必填。与 isOptional 互斥。',- default: 'false',- },- {- name: 'size',- type: "'sm' | 'md'",- description: '复选框尺寸。sm 用于紧凑布局,md 为默认。',- default: "'md'",- },- {- name: 'onFocus',- type: '(e: FocusEvent<HTMLInputElement>) => void',- description: '复选框获得焦点时触发的回调。',- },- {- name: 'onBlur',- type: '(e: FocusEvent<HTMLInputElement>) => void',- description: '复选框失去焦点时触发的回调。',- },- {- name: 'labelIcon',- type: 'XDSIconType',- description: '标签文本前显示的图标。',- },+ {name: 'isLoading', type: 'boolean', description: '复选框是否处于加载状态。显示旋转器并阻止交互。', default: 'false'},+ {name: 'isDisabled', type: 'boolean', description: '复选框是否禁用。', default: 'false'},+ {name: 'isOptional', type: 'boolean', description: '字段是否可选。与 isRequired 互斥。', default: 'false'},+ {name: 'isRequired', type: 'boolean', description: '复选框是否必填。与 isOptional 互斥。', default: 'false'},+ {name: 'size', type: "'sm' | 'md'", description: '复选框尺寸。sm 用于紧凑布局,md 为默认。', default: "'md'"},+ {name: 'onFocus', type: '(e: FocusEvent<HTMLInputElement>) => void', description: '复选框获得焦点时触发的回调。'},+ {name: 'onBlur', type: '(e: FocusEvent<HTMLInputElement>) => void', description: '复选框失去焦点时触发的回调。'},+ {name: 'labelIcon', type: 'XDSIconType', description: '标签文本前显示的图标。'},{name: 'status',type: "{ type: 'error' | 'warning' | 'success', message: string }",@@ -241,17 +182,15 @@ export const docsZh = {],theming: {targets: [- {className: 'xds-checkbox-input', visualProps: ['size']},+ {+ className: 'xds-checkbox-input',+ visualProps: [+ 'size',+ ],+ },{className: 'xds-checkbox'},],},- notes: [- '使用隐藏的原生 <input type="checkbox"> 确保无障碍性,并覆盖自定义视觉复选框。',- '视觉复选框通过祖先选择器(stylex.when.ancestor)响应悬停、焦点和选中状态。',- '标签可点击,并通过 htmlFor/id 与输入框正确关联。',- '焦点轮廓使用标准的 XDS 焦点环令牌。',- '忙碌状态(加载中或异步操作等待中)期间阻止交互,防止重复切换。',- ],};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjsindex e80210896f..c688625170 100644--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs@@ -2,31 +2,7 @@export const docs = {name: 'CheckboxList',- description:- 'A checkbox group component for multi-value selection from a list of options. Supports collection mode (parent-managed state) and standalone mode (per-item state).', keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],- features: [- 'Accessible — uses native <input type="checkbox"> with proper ARIA attributes',- 'Collection mode — parent manages selected values as string[], items derive checked state',- 'Standalone mode — individual items use isChecked/onCheck for independent control',- 'Density — compact, balanced, spacious via XDSList integration',- 'Dividers — optional border dividers between items',- 'Indeterminate — supports three-state checkbox (true, false, indeterminate) in standalone mode',- 'Descriptions — optional secondary text per item',- 'End content — slot for badges, actions, or other content after the label',- 'Disabled state — supports disabling the entire group or individual items',- 'Async actions — onChangeAction with optimistic updates and busy state',- 'Full-row click — clicking anywhere on the row toggles the checkbox',- 'Field integration — uses XDSField for label, description, and status messaging',- ],- notes: [- 'XDSCheckboxList composes XDSField (label, description, status) and XDSList (density, dividers)',- 'XDSCheckboxListItem can be used inside XDSCheckboxList (collection mode) or XDSList (standalone mode)',- 'In collection mode, XDSCheckboxListItem requires a `value` prop — throws if missing',- 'Uses XDSCheckboxInput internally with isLabelHidden for the checkbox visual',- 'Full-row click target with guard against interactive endContent children',- 'Async actions use useOptimistic + useTransition for immediate visual feedback',- 'Density maps to checkbox size: compact → sm, balanced/spacious → md',- ],+ keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],components: [{name: 'XDSCheckboxList',@@ -154,172 +130,93 @@ export const docs = {},],usage: {- summary: 'A checkbox group for multi-value selection from a list of options.',- content: `## When to use--- Users need to select multiple options from a set.-- All options should be visible at once.--## When NOT to use--- Only one option can be selected (use RadioList instead).-- The option list is very long (consider MultiSelector instead).`,+ description: 'A checkbox group for multi-value selection from a list of options. Use when users need to select multiple visible options from a set. For single selection use RadioList; for long option lists consider MultiSelector.',+ features: [+ 'Accessible — uses native <input type="checkbox"> with proper ARIA attributes',+ 'Collection mode — parent manages selected values as string[], items derive checked state',+ 'Standalone mode — individual items use isChecked/onCheck for independent control',+ 'Density — compact, balanced, spacious via XDSList integration',+ 'Dividers — optional border dividers between items',+ 'Indeterminate — supports three-state checkbox (true, false, indeterminate) in standalone mode',+ 'Descriptions — optional secondary text per item',+ 'End content — slot for badges, actions, or other content after the label',+ 'Disabled state — supports disabling the entire group or individual items',+ 'Async actions — onChangeAction with optimistic updates and busy state',+ 'Full-row click — clicking anywhere on the row toggles the checkbox',+ 'Field integration — uses XDSField for label, description, and status messaging',+ ],+ notes: [+ 'XDSCheckboxList composes XDSField (label, description, status) and XDSList (density, dividers)',+ 'XDSCheckboxListItem can be used inside XDSCheckboxList (collection mode) or XDSList (standalone mode)',+ 'In collection mode, XDSCheckboxListItem requires a `value` prop — throws if missing',+ 'Uses XDSCheckboxInput internally with isLabelHidden for the checkbox visual',+ 'Full-row click target with guard against interactive endContent children',+ 'Async actions use useOptimistic + useTransition for immediate visual feedback',+ 'Density maps to checkbox size: compact → sm, balanced/spacious → md',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'CheckboxList',- description:- '用于从选项列表中进行多值选择的复选框组组件。支持集合模式(父组件管理状态)和独立模式(逐项状态)。',- features: [- '无障碍 - 使用原生 <input type="checkbox">,配合正确的 ARIA 属性',- '集合模式 - 父组件将选中值管理为 string[],子项派生选中状态',- '独立模式 - 各项使用 isChecked/onCheck 进行独立控制',- '密度 - 通过 XDSList 集成支持紧凑、平衡、宽敞三种密度',- '分隔线 - 列表项之间的可选边框分隔线',- '不确定状态 - 独立模式下支持三态复选框(true、false、indeterminate)',- '描述 - 每个选项可选的辅助文本',- '尾部内容 - 标签后的徽章、操作或其他内容插槽',- '禁用状态 - 支持禁用整个组或单个选项',- '异步操作 - onChangeAction 配合乐观更新和忙碌状态',- '全行点击 - 点击行中任意位置均可切换复选框',- '字段集成 - 使用 XDSField 提供标签、描述和状态消息',- ],-- notes: [- 'XDSCheckboxList 组合 XDSField(标签、描述、状态)和 XDSList(密度、分隔线)',- 'XDSCheckboxListItem 可在 XDSCheckboxList(集合模式)或 XDSList(独立模式)内使用',- '在集合模式下,XDSCheckboxListItem 需要 `value` 属性——缺失时会抛出错误',- '内部使用带 isLabelHidden 的 XDSCheckboxInput 作为复选框视觉元素',- '全行点击目标,带有对交互式尾部内容子元素的防护',- '异步操作使用 useOptimistic + useTransition 实现即时视觉反馈',- '密度映射到复选框尺寸:compact → sm,balanced/spacious → md',- ],+ usage: {+ description: '用于从选项列表中进行多值选择的复选框组组件。支持集合模式(父组件管理状态)和独立模式(逐项状态)。',+ features: [+ '无障碍 - 使用原生 <input type="checkbox">,配合正确的 ARIA 属性',+ '集合模式 - 父组件将选中值管理为 string[],子项派生选中状态',+ '独立模式 - 各项使用 isChecked/onCheck 进行独立控制',+ '密度 - 通过 XDSList 集成支持紧凑、平衡、宽敞三种密度',+ '分隔线 - 列表项之间的可选边框分隔线',+ '不确定状态 - 独立模式下支持三态复选框(true、false、indeterminate)',+ '描述 - 每个选项可选的辅助文本',+ '尾部内容 - 标签后的徽章、操作或其他内容插槽',+ '禁用状态 - 支持禁用整个组或单个选项',+ '异步操作 - onChangeAction 配合乐观更新和忙碌状态',+ '全行点击 - 点击行中任意位置均可切换复选框',+ '字段集成 - 使用 XDSField 提供标签、描述和状态消息',+ ],+ notes: [+ 'XDSCheckboxList 组合 XDSField(标签、描述、状态)和 XDSList(密度、分隔线)',+ 'XDSCheckboxListItem 可在 XDSCheckboxList(集合模式)或 XDSList(独立模式)内使用',+ '在集合模式下,XDSCheckboxListItem 需要 `value` 属性——缺失时会抛出错误',+ '内部使用带 isLabelHidden 的 XDSCheckboxInput 作为复选框视觉元素',+ '全行点击目标,带有对交互式尾部内容子元素的防护',+ '异步操作使用 useOptimistic + useTransition 实现即时视觉反馈',+ '密度映射到复选框尺寸:compact → sm,balanced/spacious → md',+ ],+ },components: [{name: 'XDSCheckboxList',- description:- '复选框组容器,集成字段功能,支持标签、描述和状态。',+ 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: 'onChangeAction',- 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: '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: 'onChangeAction', 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',- description:- '单个复选框选项,包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',+ 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: '直接选中处理器(仅独立模式)。',- },+ {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: '直接选中处理器(仅独立模式)。'},],},],diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjsindex fda4def997..6b66154a20 100644--- a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs+++ b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs@@ -1,23 +1,10 @@/** @type {import('../docs-types').ComponentDoc} */export const docs = {name: 'CodeBlock',- description:- 'Syntax-highlighted code block using the CSS Custom Highlight API for zero-DOM-overhead coloring, with span-based fallback. XDSCode renders inline code within prose.',keywords: ['code', 'syntax', 'highlight', 'snippet', 'prism', 'shiki','pre', 'monospace', 'codeblock', 'inline',],- features: [- "CSS Custom Highlight API: zero-DOM-overhead syntax coloring; spans fallback for unsupported browsers",- "Line numbers: optional gutter via hasLineNumbers",- "Line highlighting: 1-indexed lines via highlightLines",- "Copy button: built-in with onCopy callback",- "Header: optional title + language label",- "Sizes: sm and md",- "Wrapping: isWrapped toggles long-line wrapping vs horizontal scroll",- "Languages: TypeScript, JavaScript, CSS, HTML, JSON, plaintext (default)",- "XDSCode: inline code element with monospace styling for use inside prose",- ],components: [{name: 'XDSCodeBlock',@@ -61,48 +48,66 @@ export const docs = {{className: 'xds-codeblock', visualProps: ['size', 'language']},],},- accessibility: [- 'XDSCodeBlock renders as <pre> with nested <code> for correct semantic markup.',- 'Copy button has an accessible label and uses aria-live to announce copy success.',- 'Line numbers are aria-hidden to avoid screen reader noise.',- 'Title and language label are visible text in the header, not tooltips.',- ],- notes: [- 'Uses CSS Custom Highlight API (CSS.highlights) when available; falls back to span-based rendering automatically.',- 'Tokenization is async -- initial render shows unstyled code, highlights applied on next paint.',- 'SYNC_TOKENIZE_THRESHOLD: short code strings tokenized synchronously to avoid async flash.',- 'Custom tokenizers support unsupported languages -- pass {type, start, end}[] token array.',- 'Token types map to xds-token-{type} CSS classes for custom syntax theme overrides.',- ],+ usage: {+ description:+ 'CodeBlock provides syntax-highlighted code display using the CSS Custom Highlight API for zero-DOM-overhead coloring, with a span-based fallback for unsupported browsers. XDSCode renders inline code within prose with monospace styling.',+ features: [+ 'CSS Custom Highlight API: zero-DOM-overhead syntax coloring; spans fallback for unsupported browsers',+ 'Line numbers: optional gutter via hasLineNumbers',+ 'Line highlighting: 1-indexed lines via highlightLines',+ 'Copy button: built-in with onCopy callback',+ 'Header: optional title + language label',+ 'Sizes: sm and md',+ 'Wrapping: isWrapped toggles long-line wrapping vs horizontal scroll',+ 'Languages: TypeScript, JavaScript, CSS, HTML, JSON, plaintext (default)',+ 'XDSCode: inline code element with monospace styling for use inside prose',+ ],+ accessibility: [+ 'XDSCodeBlock renders as <pre> with nested <code> for correct semantic markup.',+ 'Copy button has an accessible label and uses aria-live to announce copy success.',+ 'Line numbers are aria-hidden to avoid screen reader noise.',+ 'Title and language label are visible text in the header, not tooltips.',+ ],+ notes: [+ 'Uses CSS Custom Highlight API (CSS.highlights) when available; falls back to span-based rendering automatically.',+ 'Tokenization is async -- initial render shows unstyled code, highlights applied on next paint.',+ 'SYNC_TOKENIZE_THRESHOLD: short code strings tokenized synchronously to avoid async flash.',+ 'Custom tokenizers support unsupported languages -- pass {type, start, end}[] token array.',+ 'Token types map to xds-token-{type} CSS classes for custom syntax theme overrides.',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description: '使用 CSS Custom Highlight API 实现零 DOM 开销语法高亮的代码块,不支持时回退到基于 span 的渲染。XDSCode 用于在正文中渲染内联代码。',- features: [- 'CSS Custom Highlight API:零 DOM 开销语法高亮;不支持浏览器时回退到 span',- '行号:通过 hasLineNumbers 显示可选的行号栏',- '行高亮:通过 highlightLines 指定 1-indexed 的高亮行',- '复制按钮:内置,支持 onCopy 回调',- '标题栏:可选的标题和语言标签',- '尺寸:sm 和 md 两种',- '换行:isWrapped 切换长行换行与水平滚动',- '语言:TypeScript、JavaScript、CSS、HTML、JSON、plaintext(默认)',- 'XDSCode:用于正文中内联代码的等宽字体样式元素',- ],- accessibility: [- 'XDSCodeBlock 渲染为带嵌套 <code> 的 <pre>,具有正确的语义标记。',- '复制按钮有无障碍标签,并使用 aria-live 播报复制成功。',- '行号设置 aria-hidden 以避免屏幕阅读器噪音。',- '标题和语言标签是标题栏中的可见文本,而非工具提示。',- ],- notes: [- '可用时使用 CSS Custom Highlight API(CSS.highlights),自动回退到基于 span 的渲染。',- '分词是异步的——初始渲染显示未高亮代码,下一帧应用高亮。',- 'SYNC_TOKENIZE_THRESHOLD:短代码字符串同步分词以避免异步闪烁。',- '自定义分词器支持内置不支持的语言——传入 {type, start, end}[] token 数组。',- 'Token 类型映射到 xds-token-{type} CSS 类,支持自定义语法主题覆盖。',- ],+ usage: {+ description:+ '使用 CSS Custom Highlight API 实现零 DOM 开销语法高亮的代码块,不支持时回退到基于 span 的渲染。XDSCode 用于在正文中渲染内联代码。',+ features: [+ 'CSS Custom Highlight API:零 DOM 开销语法高亮;不支持浏览器时回退到 span',+ '行号:通过 hasLineNumbers 显示可选的行号栏',+ '行高亮:通过 highlightLines 指定 1-indexed 的高亮行',+ '复制按钮:内置,支持 onCopy 回调',+ '标题栏:可选的标题和语言标签',+ '尺寸:sm 和 md 两种',+ '换行:isWrapped 切换长行换行与水平滚动',+ '语言:TypeScript、JavaScript、CSS、HTML、JSON、plaintext(默认)',+ 'XDSCode:用于正文中内联代码的等宽字体样式元素',+ ],+ accessibility: [+ 'XDSCodeBlock 渲染为带嵌套 <code> 的 <pre>,具有正确的语义标记。',+ '复制按钮有无障碍标签,并使用 aria-live 播报复制成功。',+ '行号设置 aria-hidden 以避免屏幕阅读器噪音。',+ '标题和语言标签是标题栏中的可见文本,而非工具提示。',+ ],+ notes: [+ '可用时使用 CSS Custom Highlight API(CSS.highlights),自动回退到基于 span 的渲染。',+ '分词是异步的——初始渲染显示未高亮代码,下一帧应用高亮。',+ 'SYNC_TOKENIZE_THRESHOLD:短代码字符串同步分词以避免异步闪烁。',+ '自定义分词器支持内置不支持的语言——传入 {type, start, end}[] token 数组。',+ 'Token 类型映射到 xds-token-{type} CSS 类,支持自定义语法主题覆盖。',+ ],+ },components: [{name: 'XDSCodeBlock',diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjsindex 6e1de87340..ec7feb4a1e 100644--- a/packages/core/src/Collapsible/Collapsible.doc.mjs+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs@@ -2,33 +2,12 @@export const docs = {name: 'Collapsible',- description: 'Collapsible content primitive and group coordination.',keywords: ["accordion","collapse","expandable","disclosure","toggle","panel","foldable","expander","expand"],- features: [- 'XDSCollapsible makes any content collapsible — a trigger toggles visibility of the content area',- 'Handles state management, accessibility (aria-expanded, keyboard activation), and a chevron indicator',- 'Supports uncontrolled (defaultIsOpen), controlled (isOpen / onOpenChange), and group-coordinated modes',- 'XDSCollapsibleGroup coordinates multiple XDSCollapsible instances so only one (single mode) or multiple (multiple mode) can be open at a time',- 'XDSCollapsibleGroup renders no wrapper DOM element',- 'When inside a group, XDSCollapsible defers open/close state to the group context via the value prop',- ],- keyboard:- 'Enter or Space activates the trigger button to toggle open/close state.',- accessibility: [- 'Trigger renders as a <button> with aria-expanded reflecting the current open state',- 'A chevron indicator provides a visual affordance for the expanded/collapsed state',- ],theming: {targets: [{className: 'xds-collapsible'},],},- notes: [- 'XDSCollapsible manages its own open/close state by default (uncontrolled)',- 'When nested inside an XDSCollapsibleGroup with a matching value prop, it defers to the group context',- 'XDSCollapsibleGroup provides context with isOpen(value) and toggle(value) methods',- 'The group renders no wrapper DOM — layout is the responsibility of the consumer (e.g. XDSVStack)',- ],components: [{name: 'XDSCollapsible',@@ -106,82 +85,71 @@ export const docs = {},],usage: {- summary: 'Contains information that may need additional space to display.',- content: `## When to use--- Presenting additional information for items in a list.-- Content that can be hidden to save space and revealed on demand.`,+ description: 'A collapsible content primitive for revealing and hiding content on demand. Use to present additional information in lists or to hide content that can be revealed when needed.',+ features: [+ 'XDSCollapsible makes any content collapsible — a trigger toggles visibility of the content area',+ 'Handles state management, accessibility (aria-expanded, keyboard activation), and a chevron indicator',+ 'Supports uncontrolled (defaultIsOpen), controlled (isOpen / onOpenChange), and group-coordinated modes',+ 'XDSCollapsibleGroup coordinates multiple XDSCollapsible instances so only one (single mode) or multiple (multiple mode) can be open at a time',+ 'XDSCollapsibleGroup renders no wrapper DOM element',+ 'When inside a group, XDSCollapsible defers open/close state to the group context via the value prop',+ ],+ accessibility: [+ 'Trigger renders as a <button> with aria-expanded reflecting the current open state',+ 'A chevron indicator provides a visual affordance for the expanded/collapsed state',+ 'Keyboard: Enter or Space activates the trigger button to toggle open/close state',+ ],+ notes: [+ 'XDSCollapsible manages its own open/close state by default (uncontrolled)',+ 'When nested inside an XDSCollapsibleGroup with a matching value prop, it defers to the group context',+ 'XDSCollapsibleGroup provides context with isOpen(value) and toggle(value) methods',+ 'The group renders no wrapper DOM — layout is the responsibility of the consumer (e.g. XDSVStack)',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Collapsible',- description: '可折叠内容原语和分组协调。',- features: [- 'XDSCollapsible 使任何内容可折叠——触发器切换内容区域的可见性',- '处理状态管理、无障碍(aria-expanded、键盘激活)和折叠指示器',- '支持非受控(defaultIsOpen)、受控(isOpen / onOpenChange)和分组协调模式',- 'XDSCollapsibleGroup 协调多个 XDSCollapsible 实例,使同一时间只有一个(single 模式)或多个(multiple 模式)可以展开',- 'XDSCollapsibleGroup 不渲染包裹 DOM 元素',- '在分组内时,XDSCollapsible 通过 value 属性将展开/收起状态委托给分组上下文',- ],- keyboard:- 'Enter 或 Space 激活触发按钮以切换展开/收起状态。',- accessibility: [- '触发器渲染为带有 aria-expanded 的 <button>,反映当前展开状态',- '折叠指示器为展开/收起状态提供视觉提示',- ],+ usage: {+ description: '可折叠内容原语和分组协调。',+ features: [+ 'XDSCollapsible 使任何内容可折叠——触发器切换内容区域的可见性',+ '处理状态管理、无障碍(aria-expanded、键盘激活)和折叠指示器',+ '支持非受控(defaultIsOpen)、受控(isOpen / onOpenChange)和分组协调模式',+ 'XDSCollapsibleGroup 协调多个 XDSCollapsible 实例,使同一时间只有一个(single 模式)或多个(multiple 模式)可以展开',+ 'XDSCollapsibleGroup 不渲染包裹 DOM 元素',+ '在分组内时,XDSCollapsible 通过 value 属性将展开/收起状态委托给分组上下文',+ ],+ accessibility: [+ '触发器渲染为带有 aria-expanded 的 <button>,反映当前展开状态',+ '折叠指示器为展开/收起状态提供视觉提示',+ 'Keyboard: Enter 或 Space 激活触发按钮以切换展开/收起状态。',+ ],+ notes: [+ 'XDSCollapsible 默认自行管理展开/收起状态(非受控)',+ '嵌套在具有匹配 value 属性的 XDSCollapsibleGroup 内时,委托给分组上下文',+ 'XDSCollapsibleGroup 通过 isOpen(value) 和 toggle(value) 方法提供上下文',+ '分组不渲染包裹 DOM——布局由使用者负责(如 XDSVStack)',+ ],+ },theming: {targets: [{className: 'xds-collapsible'},],},- notes: [- 'XDSCollapsible 默认自行管理展开/收起状态(非受控)',- '嵌套在具有匹配 value 属性的 XDSCollapsibleGroup 内时,委托给分组上下文',- 'XDSCollapsibleGroup 通过 isOpen(value) 和 toggle(value) 方法提供上下文',- '分组不渲染包裹 DOM——布局由使用者负责(如 XDSVStack)',- ],components: [{name: 'XDSCollapsible',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: '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 内时为必填。'},],},{@@ -189,34 +157,11 @@ export const docsZh = {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,- },+ {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},],},],diff --git a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjsindex 97991dcdbc..3e8120d7c1 100644--- a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs+++ b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs@@ -1,8 +1,6 @@/** @type {import('../docs-types').ComponentDoc} */export const docs = {name: 'CommandPalette',- description:- 'A searchSource-driven command palette dialog. Provide a search source and get filtering, keyboard navigation, grouping, and selection. Uses the same XDSSearchSource interface as XDSTypeahead.',keywords: ['command','spotlight',@@ -16,16 +14,6 @@ export const docs = {'dialog','navigation',],- features: [- 'searchSource: same XDSSearchSource interface as XDSTypeahead — static, async, or hybrid',- 'Auto-grouping: items with auxiliaryData.group are auto-grouped in default rendering',- 'createStaticSource: utility for static lists with optional keyword matching',- 'Async support: spinner shows in input while search resolves',- 'Keyboard navigation: arrow keys, Enter to select, Escape to close',- 'Picker mode: value/onValueChange for persistent selection',- 'Composable: XDSCommandPaletteInput, XDSCommandPaletteList, XDSCommandPaletteGroup, XDSCommandPaletteItem, XDSCommandPaletteFooter, XDSCommandPaletteEmpty',- 'renderItem: custom per-item render while preserving auto-grouping',- ],components: [{name: 'XDSCommandPalette',@@ -298,56 +286,70 @@ export const docs = {{className: 'xds-command-palette-list'},],},- accessibility: [- 'Dialog uses XDSDialog — native <dialog> with showModal() for correct modal ARIA semantics.',- 'Input renders as a search input with combobox role, aria-expanded, and aria-controls pointing to the list.',- 'List renders as role="listbox" with aria-label.',- 'Items render as role="option" with aria-selected.',- 'Keyboard navigation uses useCombobox from XDSSelector for consistent arrow key, Home/End, Enter, and Escape behavior.',- 'Spinner in input uses role="status" to announce loading to screen readers.',- ],- keyboard:- 'Arrow Up/Down: navigate items; Enter: select highlighted item; Escape: close palette; Tab: moves focus to footer actions',- notes: [- 'Uses XDSSearchSource interface — the same as XDSTypeahead. Any source compatible with XDSTypeahead works here.',- 'createStaticSource supports keyword-based matching in addition to substring matching.',- 'Auto-grouping reads auxiliaryData.group from each item — no extra config needed.',- 'Picker mode (value/onValueChange) keeps the palette open and tracks a persistent selection.',- 'The isBusy signal from searchSource drives the spinner in XDSCommandPaletteInput automatically.',- ],+ usage: {+ description:+ 'CommandPalette is a searchSource-driven command palette dialog that provides filtering, keyboard navigation, grouping, and selection. It uses the same XDSSearchSource interface as XDSTypeahead, supporting static, async, or hybrid data sources.',+ features: [+ 'searchSource: same XDSSearchSource interface as XDSTypeahead — static, async, or hybrid',+ 'Auto-grouping: items with auxiliaryData.group are auto-grouped in default rendering',+ 'createStaticSource: utility for static lists with optional keyword matching',+ 'Async support: spinner shows in input while search resolves',+ 'Keyboard navigation: arrow keys, Enter to select, Escape to close',+ 'Picker mode: value/onValueChange for persistent selection',+ 'Composable: XDSCommandPaletteInput, XDSCommandPaletteList, XDSCommandPaletteGroup, XDSCommandPaletteItem, XDSCommandPaletteFooter, XDSCommandPaletteEmpty',+ 'renderItem: custom per-item render while preserving auto-grouping',+ ],+ accessibility: [+ 'Dialog uses XDSDialog — native <dialog> with showModal() for correct modal ARIA semantics.',+ 'Input renders as a search input with combobox role, aria-expanded, and aria-controls pointing to the list.',+ 'List renders as role="listbox" with aria-label.',+ 'Items render as role="option" with aria-selected.',+ 'Keyboard navigation uses useCombobox from XDSSelector for consistent arrow key, Home/End, Enter, and Escape behavior.',+ 'Spinner in input uses role="status" to announce loading to screen readers.',+ 'Keyboard: Arrow Up/Down navigate items; Enter selects highlighted item; Escape closes palette; Tab moves focus to footer actions.',+ ],+ notes: [+ 'Uses XDSSearchSource interface — the same as XDSTypeahead. Any source compatible with XDSTypeahead works here.',+ 'createStaticSource supports keyword-based matching in addition to substring matching.',+ 'Auto-grouping reads auxiliaryData.group from each item — no extra config needed.',+ 'Picker mode (value/onValueChange) keeps the palette open and tracks a persistent selection.',+ 'The isBusy signal from searchSource drives the spinner in XDSCommandPaletteInput automatically.',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description:- '由 searchSource 驱动的命令面板对话框。提供搜索源,即可获得过滤、键盘导航、分组和选择功能。与 XDSTypeahead 使用相同的 XDSSearchSource 接口。',- features: [- 'searchSource:与 XDSTypeahead 相同的 XDSSearchSource 接口——静态、异步或混合',- '自动分组:auxiliaryData.group 中的项目在默认渲染中自动分组',- 'createStaticSource:用于静态列表的工具函数,支持关键词匹配',- '异步支持:搜索解析时在输入框中显示加载指示器',- '键盘导航:方向键、Enter 选择、Escape 关闭',- '选择器模式:通过 value/onValueChange 实现持久选择',- '可组合:XDSCommandPaletteInput、XDSCommandPaletteList、XDSCommandPaletteGroup 等子组件',- 'renderItem:自定义每个条目的渲染,同时保留自动分组',- ],- accessibility: [- '对话框使用 XDSDialog——原生 <dialog> 配合 showModal() 实现正确的模态 ARIA 语义。',- '输入框渲染为搜索输入,具有 combobox 角色、aria-expanded 和指向列表的 aria-controls。',- '列表渲染为 role="listbox",带有 aria-label。',- '条目渲染为 role="option",带有 aria-selected。',- '键盘导航使用 XDSSelector 的 useCombobox,确保方向键、Home/End、Enter 和 Escape 行为一致。',- '输入框中的加载指示器使用 role="status" 向屏幕阅读器播报加载状态。',- ],- keyboard:- '上下方向键:导航条目;Enter:选择高亮条目;Escape:关闭面板;Tab:移动焦点到页脚操作',- notes: [- '使用 XDSSearchSource 接口——与 XDSTypeahead 相同。任何与 XDSTypeahead 兼容的源都可以在此使用。',- 'createStaticSource 除子字符串匹配外还支持关键词匹配。',- '自动分组读取每个条目的 auxiliaryData.group——无需额外配置。',- '选择器模式(value/onValueChange)保持面板打开并跟踪持久选择。',- '来自 searchSource 的 isBusy 信号自动驱动 XDSCommandPaletteInput 中的加载指示器。',- ],+ usage: {+ description:+ '由 searchSource 驱动的命令面板对话框。提供搜索源,即可获得过滤、键盘导航、分组和选择功能。与 XDSTypeahead 使用相同的 XDSSearchSource 接口。',+ features: [+ 'searchSource:与 XDSTypeahead 相同的 XDSSearchSource 接口——静态、异步或混合',+ '自动分组:auxiliaryData.group 中的项目在默认渲染中自动分组',+ 'createStaticSource:用于静态列表的工具函数,支持关键词匹配',+ '异步支持:搜索解析时在输入框中显示加载指示器',+ '键盘导航:方向键、Enter 选择、Escape 关闭',+ '选择器模式:通过 value/onValueChange 实现持久选择',+ '可组合:XDSCommandPaletteInput、XDSCommandPaletteList、XDSCommandPaletteGroup 等子组件',+ 'renderItem:自定义每个条目的渲染,同时保留自动分组',+ ],+ accessibility: [+ '对话框使用 XDSDialog——原生 <dialog> 配合 showModal() 实现正确的模态 ARIA 语义。',+ '输入框渲染为搜索输入,具有 combobox 角色、aria-expanded 和指向列表的 aria-controls。',+ '列表渲染为 role="listbox",带有 aria-label。',+ '条目渲染为 role="option",带有 aria-selected。',+ '键盘导航使用 XDSSelector 的 useCombobox,确保方向键、Home/End、Enter 和 Escape 行为一致。',+ '输入框中的加载指示器使用 role="status" 向屏幕阅读器播报加载状态。',+ 'Keyboard: 上下方向键:导航条目;Enter:选择高亮条目;Escape:关闭面板;Tab:移动焦点到页脚操作',+ ],+ notes: [+ '使用 XDSSearchSource 接口——与 XDSTypeahead 相同。任何与 XDSTypeahead 兼容的源都可以在此使用。',+ 'createStaticSource 除子字符串匹配外还支持关键词匹配。',+ '自动分组读取每个条目的 auxiliaryData.group——无需额外配置。',+ '选择器模式(value/onValueChange)保持面板打开并跟踪持久选择。',+ '来自 searchSource 的 isBusy 信号自动驱动 XDSCommandPaletteInput 中的加载指示器。',+ ],+ },components: [{name: 'XDSCommandPalette',@@ -383,11 +385,7 @@ export const docsZh = {{name: 'XDSCommandPaletteList',description: '可滚动的结果容器。作为 listbox 渲染以符合 ARIA 规范。',- propDescriptions: {- children: '条目、分组和空状态。',- label: 'listbox 的无障碍标签。',- xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',- },+ propDescriptions: {children: '条目、分组和空状态。', label: 'listbox 的无障碍标签。', xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。'},},{name: 'XDSCommandPaletteItem',@@ -405,26 +403,17 @@ export const docsZh = {{name: 'XDSCommandPaletteGroup',description: '带标题标签的视觉分组。放置在 XDSCommandPaletteList 内。',- propDescriptions: {- heading: '分组标题文本。',- children: 'XDSCommandPaletteItem 子元素。',- xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',- },+ propDescriptions: {heading: '分组标题文本。', children: 'XDSCommandPaletteItem 子元素。', xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。'},},{name: 'XDSCommandPaletteFooter',description: '显示键盘导航提示的页脚。未提供子元素时渲染默认方向键/Enter/Escape 提示。',- propDescriptions: {- children: '自定义页脚内容。省略时通过 XDSKbd 渲染默认键盘提示。',- xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',- },+ propDescriptions: {children: '自定义页脚内容。省略时通过 XDSKbd 渲染默认键盘提示。', xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。'},},{name: 'XDSCommandPaletteEmpty',description: '结果区域的空状态展示。由 XDSCommandPalette 在无结果和无查询状态下自动渲染。',- propDescriptions: {- children: '要显示的消息或内容。',- },+ propDescriptions: {children: '要显示的消息或内容。'},},],};diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsindex 6e62f92680..83c6a22bdd 100644--- a/packages/core/src/DateInput/DateInput.doc.mjs+++ b/packages/core/src/DateInput/DateInput.doc.mjs@@ -2,17 +2,7 @@export const docs = {name: 'DateInput',- description:- 'XDSDateInput component combining a text input with a calendar popover for date selection.',keywords: ["dateinput","datepicker","datefield","calendar","dateselect","dateentry","datechooser"],- features: [- 'Text Input — manual date entry with flexible parsing (supports various formats)',- 'Calendar Popover — click icon or use keyboard to open calendar picker',- 'Date Constraints — min, max, and custom dateConstraints functions',- 'Status Indicators — error, warning, and success states with messages',- 'Accessibility — full keyboard navigation, focus trapping, screen reader support',- 'Field Integration — built on XDSField for consistent label, description, and validation states',- ],props: [{name: 'label',@@ -136,141 +126,75 @@ export const docs = {'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',},],- keyboard:- 'Tab moves between input and calendar icon button; Enter/Space on icon opens/closes the calendar; Escape closes the calendar popover; Arrow keys navigate between days; Page Up/Down navigate between months.',- notes: [- 'The text input accepts multiple date formats: ISO (2026-01-28), US (01/28/2026, 1/28/2026), and written (Jan 28, 2026 / January 28 2026).',- 'Invalid input reverts to the previous valid value on blur.',- ],theming: {targets: [{className: 'xds-date-input', visualProps: ['size']},],},usage: {- summary: 'Field formatted for users to input a date.',- content: `## When to use--- User needs to input a date (e.g. scheduling events, form submissions).`,+ description: 'A date input field combining a text input with a calendar popover for date selection. Use when users need to input a date, such as scheduling events or form submissions.',+ features: [+ 'Text Input — manual date entry with flexible parsing (supports various formats)',+ 'Calendar Popover — click icon or use keyboard to open calendar picker',+ 'Date Constraints — min, max, and custom dateConstraints functions',+ 'Status Indicators — error, warning, and success states with messages',+ 'Accessibility — full keyboard navigation, focus trapping, screen reader support',+ 'Field Integration — built on XDSField for consistent label, description, and validation states',+ ],+ accessibility: [+ 'Keyboard: Tab moves between input and calendar icon button; Enter/Space on icon opens/closes the calendar; Escape closes the calendar popover; Arrow keys navigate between days; Page Up/Down navigate between months',+ ],+ notes: [+ 'The text input accepts multiple date formats: ISO (2026-01-28), US (01/28/2026, 1/28/2026), and written (Jan 28, 2026 / January 28 2026).',+ 'Invalid input reverts to the previous valid value on blur.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'DateInput',- description:- 'XDSDateInput 日期输入组件,将文本输入与日历弹出层结合用于日期选择。',- features: [- '文本输入——手动输入日期,支持灵活的格式解析(支持多种格式)',- '日历弹出层——点击图标或使用键盘打开日历选择器',- '日期约束——min、max 和自定义 dateConstraints 函数',- '状态指示器——错误、警告和成功状态及消息',- '无障碍——完整的键盘导航、焦点捕获、屏幕阅读器支持',- '字段集成——基于 XDSField 构建,提供一致的标签、描述和验证状态',- ],+ usage: {+ description: 'XDSDateInput 日期输入组件,将文本输入与日历弹出层结合用于日期选择。',+ features: [+ '文本输入——手动输入日期,支持灵活的格式解析(支持多种格式)',+ '日历弹出层——点击图标或使用键盘打开日历选择器',+ '日期约束——min、max 和自定义 dateConstraints 函数',+ '状态指示器——错误、警告和成功状态及消息',+ '无障碍——完整的键盘导航、焦点捕获、屏幕阅读器支持',+ '字段集成——基于 XDSField 构建,提供一致的标签、描述和验证状态',+ ],+ accessibility: [+ 'Keyboard: Tab 在输入框和日历图标按钮间移动;Enter/Space 点击图标打开/关闭日历;Escape 关闭日历弹出层;方向键在日期间导航;Page Up/Down 在月份间导航。',+ ],+ notes: [+ '文本输入接受多种日期格式:ISO(2026-01-28)、美式(01/28/2026、1/28/2026)和书面格式(Jan 28, 2026 / January 28 2026)。',+ '无效输入在失焦时恢复为上一个有效值。',+ ],+ },props: [- {- name: 'label',- type: 'string',- description: '标签文本。',- required: true,- },- {- name: 'isLabelHidden',- type: 'boolean',- description: '视觉隐藏标签。',- default: 'false',- },- {- name: 'description',- type: 'string',- description: '显示在标签下方的辅助文本。',- },- {- name: 'isOptional',- type: 'boolean',- description: '在标签旁显示"(optional)"指示器。',- default: 'false',- },- {- name: 'isRequired',- type: 'boolean',- description: '将字段标记为必填。',- default: 'false',- },- {- name: 'isDisabled',- type: 'boolean',- description: '禁用输入框和日历。',- default: 'false',- },- {- name: 'value',- type: 'ISODateString',- description: '选中的日期,YYYY-MM-DD 格式。',- },- {- name: 'onChange',- type: '(value: ISODateString | undefined) => void',- description: '选中日期变更时调用的回调。',- },+ {name: 'label', type: 'string', description: '标签文本。', required: true},+ {name: 'isLabelHidden', type: 'boolean', description: '视觉隐藏标签。', default: 'false'},+ {name: 'description', type: 'string', description: '显示在标签下方的辅助文本。'},+ {name: 'isOptional', type: 'boolean', description: '在标签旁显示"(optional)"指示器。', default: 'false'},+ {name: 'isRequired', type: 'boolean', description: '将字段标记为必填。', default: 'false'},+ {name: 'isDisabled', type: 'boolean', description: '禁用输入框和日历。', default: 'false'},+ {name: 'value', type: 'ISODateString', description: '选中的日期,YYYY-MM-DD 格式。'},+ {name: 'onChange', type: '(value: ISODateString | undefined) => void', description: '选中日期变更时调用的回调。'},{name: 'onChangeAction',type: '(value: ISODateString | undefined) => void | Promise<void>',description: '在 onChange 之后触发的异步操作。通过 useTransition 驱动乐观更新。',},- {- name: 'isLoading',- type: 'boolean',- description: '输入框是否处于加载状态。禁用交互并显示加载指示器。',- default: 'false',- },- {- name: 'min',- type: 'ISODateString',- description: '可选择的最早日期(YYYY-MM-DD)。',- },- {- name: 'max',- type: 'ISODateString',- description: '可选择的最晚日期(YYYY-MM-DD)。',- },- {- name: 'dateConstraints',- type: 'Array<(date: Date) => boolean>',- description:- '自定义约束函数数组,用于禁用特定日期。',- },- {- name: 'placeholder',- type: 'string',- description: '文本输入框中显示的占位符文本。',- default: "'Select a date'",- },- {- name: 'size',- type: "'sm' | 'md' | 'lg'",- description: '输入控件的尺寸。',- default: "'md'",- },- {- name: 'status',- type: 'XDSInputStatus',- description:- '错误、警告或成功状态的状态指示对象,附带消息。',- },- {- name: 'labelTooltip',- type: 'string',- description: '通过标签末尾的信息图标显示的提示文本。',- },- {- name: 'numberOfMonths',- type: '1 | 2',- description:- '日历弹出层中同时显示的月份数量。',- default: '1',- },+ {name: 'isLoading', type: 'boolean', description: '输入框是否处于加载状态。禁用交互并显示加载指示器。', default: 'false'},+ {name: 'min', type: 'ISODateString', description: '可选择的最早日期(YYYY-MM-DD)。'},+ {name: 'max', type: 'ISODateString', description: '可选择的最晚日期(YYYY-MM-DD)。'},+ {name: 'dateConstraints', type: 'Array<(date: Date) => boolean>', description: '自定义约束函数数组,用于禁用特定日期。'},+ {name: 'placeholder', type: 'string', description: '文本输入框中显示的占位符文本。', default: "'Select a date'"},+ {name: 'size', type: "'sm' | 'md' | 'lg'", description: '输入控件的尺寸。', default: "'md'"},+ {name: 'status', type: 'XDSInputStatus', description: '错误、警告或成功状态的状态指示对象,附带消息。'},+ {name: 'labelTooltip', type: 'string', description: '通过标签末尾的信息图标显示的提示文本。'},+ {name: 'numberOfMonths', type: '1 | 2', description: '日历弹出层中同时显示的月份数量。', default: '1'},{name: 'xstyle',type: 'StyleXStyles',@@ -278,15 +202,14 @@ export const docsZh = {'用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',},],- keyboard:- 'Tab 在输入框和日历图标按钮间移动;Enter/Space 点击图标打开/关闭日历;Escape 关闭日历弹出层;方向键在日期间导航;Page Up/Down 在月份间导航。',- notes: [- '文本输入接受多种日期格式:ISO(2026-01-28)、美式(01/28/2026、1/28/2026)和书面格式(Jan 28, 2026 / January 28 2026)。',- '无效输入在失焦时恢复为上一个有效值。',- ],theming: {targets: [- {className: 'xds-date-input', visualProps: ['size']},+ {+ className: 'xds-date-input',+ visualProps: [+ 'size',+ ],+ },],},};diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex 507ccdc436..39ac3dec25 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -2,17 +2,7 @@export const docs = {name: 'Dialog',- description:- 'Modal dialog using the native <dialog> element with automatic focus trapping, backdrop, and purpose-based dismissal control.', keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap"],- features: [- "Native <dialog>: Uses the browser's built-in modal behavior via showModal()",- 'Automatic focus trap: Focus is trapped within the dialog when open (browser-native)',- 'Backdrop: Native ::backdrop pseudo-element with blur effect',- 'Variants: standard (configurable dimensions) and fullscreen (full viewport)',- 'Purpose-based dismissal: required, form, and info control Escape key and backdrop-click behavior',- 'Custom positioning: Static position support via the position prop',- 'Accessible: Proper ARIA attributes and keyboard navigation',- ],+ keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap"],theming: {container: true,targets: [@@ -30,20 +20,6 @@ export const docs = {},],},- keyboard:- 'Escape closes the dialog (unless purpose="required"); focus is trapped inside the dialog while open.',- accessibility: [- 'Uses the native <dialog> element with showModal() for correct ARIA modal semantics.',- 'Focus is automatically trapped by the browser when using showModal().',- 'XDSDialogHeader title receives focus when the dialog opens.',- ],- notes: [- 'Height is unset (grows with content) and constrained by the maxHeight prop.',- 'When variant="fullscreen", the width, maxHeight, and position props are ignored.',- 'For form purpose, backdrop click is only allowed before the user has interacted with the dialog.',- 'Purpose=required disables both Escape key and backdrop click; purpose=form disables backdrop click after interaction; purpose=info (default) allows both.',- 'XDSDialog is designed to be used with XDSLayout as its child.',- ],components: [{name: 'XDSDialog',@@ -143,23 +119,29 @@ export const docs = {},],usage: {- summary: 'A top-level dialog that communicates important information and pauses the user\'s workflow.',- content: `## When to use--- Pause a user's workflow to communicate top-level information.-- Guide users through multi-step workflows.-- Surface information that requires acknowledgement.-- Present confirmations before destructive actions.--## Best practices--- Do: Include a back arrow for two-view dialogs.-- Do: Include a step count indicator for dialogs with 3 or more views.-- Don't: Remove all dismissal behaviors.-- Use sentence case for dialog content.-- Match the call-to-action label to the dialog headline.-- Number steps in multi-step dialogs.-- Dismissal types: informational (all exit methods), form (disable click-outside), required (only footer buttons).`,+ description: "A modal dialog that communicates important information and pauses the user's workflow. Built on the native <dialog> element with automatic focus trapping, backdrop, and purpose-based dismissal control. Use for multi-step workflows, confirmations before destructive actions, or information requiring acknowledgement.",+ features: [+ "Native <dialog>: Uses the browser's built-in modal behavior via showModal()",+ 'Automatic focus trap: Focus is trapped within the dialog when open (browser-native)',+ 'Backdrop: Native ::backdrop pseudo-element with blur effect',+ 'Variants: standard (configurable dimensions) and fullscreen (full viewport)',+ 'Purpose-based dismissal: required, form, and info control Escape key and backdrop-click behavior',+ 'Custom positioning: Static position support via the position prop',+ 'Accessible: Proper ARIA attributes and keyboard navigation',+ ],+ accessibility: [+ 'Uses the native <dialog> element with showModal() for correct ARIA modal semantics.',+ 'Focus is automatically trapped by the browser when using showModal().',+ 'XDSDialogHeader title receives focus when the dialog opens.',+ 'Keyboard: Escape closes the dialog (unless purpose="required"); focus is trapped inside the dialog while open.',+ ],+ notes: [+ 'Height is unset (grows with content) and constrained by the maxHeight prop.',+ 'When variant="fullscreen", the width, maxHeight, and position props are ignored.',+ 'For form purpose, backdrop click is only allowed before the user has interacted with the dialog.',+ 'Purpose=required disables both Escape key and backdrop click; purpose=form disables backdrop click after interaction; purpose=info (default) allows both.',+ 'XDSDialog is designed to be used with XDSLayout as its child.',+ ],anatomy: [{name: 'Body', required: true, description: 'The main content area of the dialog.'},{name: 'Header', required: true, description: 'Contains the title, actions, and close button.'},@@ -173,17 +155,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Dialog',- description:- '使用原生 <dialog> 元素的模态对话框,支持自动焦点捕获、遮罩层和基于用途的关闭控制。',- features: [- '原生 <dialog>:通过 showModal() 使用浏览器内置的模态行为',- '自动焦点捕获:对话框打开时焦点被限制在内部(浏览器原生支持)',- '遮罩层:原生 ::backdrop 伪元素,带模糊效果',- '变体:standard(可配置尺寸)和 fullscreen(全视口)',- '基于用途的关闭控制:required、form 和 info 控制 Escape 键和遮罩层点击行为',- '自定义定位:通过 position 属性支持静态定位',- '无障碍:正确的 ARIA 属性和键盘导航',- ],theming: {container: true,targets: [@@ -201,20 +172,6 @@ export const docsZh = {},],},- keyboard:- 'Escape 关闭对话框(purpose="required" 时除外);对话框打开时焦点被限制在内部。',- accessibility: [- '使用原生 <dialog> 元素配合 showModal() 以获得正确的 ARIA 模态语义。',- '使用 showModal() 时,浏览器会自动捕获焦点。',- '对话框打开时,XDSDialogHeader 的标题会获得焦点。',- ],- notes: [- '高度未设置(随内容增长),受 maxHeight 属性约束。',- '当 variant="fullscreen" 时,width、maxHeight 和 position 属性会被忽略。',- '对于 form 用途,仅在用户与对话框交互之前允许点击遮罩层关闭。',- 'purpose=required 禁用 Escape 键和遮罩层点击;purpose=form 在交互后禁用遮罩层点击;purpose=info(默认)两者都允许。',- 'XDSDialog 设计为与 XDSLayout 配合使用作为其子组件。',- ],components: [{name: 'XDSDialog',@@ -314,6 +271,32 @@ export const docsZh = {],},],+ usage: {+ description:+ '使用原生 <dialog> 元素的模态对话框,支持自动焦点捕获、遮罩层和基于用途的关闭控制。',+ features: [+ '原生 <dialog>:通过 showModal() 使用浏览器内置的模态行为',+ '自动焦点捕获:对话框打开时焦点被限制在内部(浏览器原生支持)',+ '遮罩层:原生 ::backdrop 伪元素,带模糊效果',+ '变体:standard(可配置尺寸)和 fullscreen(全视口)',+ '基于用途的关闭控制:required、form 和 info 控制 Escape 键和遮罩层点击行为',+ '自定义定位:通过 position 属性支持静态定位',+ '无障碍:正确的 ARIA 属性和键盘导航',+ ],+ accessibility: [+ '使用原生 <dialog> 元素配合 showModal() 以获得正确的 ARIA 模态语义。',+ '使用 showModal() 时,浏览器会自动捕获焦点。',+ '对话框打开时,XDSDialogHeader 的标题会获得焦点。',+ 'Keyboard: Escape 关闭对话框(purpose="required" 时除外);对话框打开时焦点被限制在内部。',+ ],+ notes: [+ '高度未设置(随内容增长),受 maxHeight 属性约束。',+ '当 variant="fullscreen" 时,width、maxHeight 和 position 属性会被忽略。',+ '对于 form 用途,仅在用户与对话框交互之前允许点击遮罩层关闭。',+ 'purpose=required 禁用 Escape 键和遮罩层点击;purpose=form 在交互后禁用遮罩层点击;purpose=info(默认)两者都允许。',+ 'XDSDialog 设计为与 XDSLayout 配合使用作为其子组件。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjsindex eb6fc24ae2..514f052b2b 100644--- a/packages/core/src/Divider/Divider.doc.mjs+++ b/packages/core/src/Divider/Divider.doc.mjs@@ -4,15 +4,7 @@export const docs = {name: 'Divider',- description: 'Visual separator with optional label, using XDS design tokens.',keywords: ["divider","separator","hr","rule","line","border","spacer","horizontal rule"],- features: [- 'Supports horizontal and vertical orientations',- 'Optional label centered on the divider line',- 'Subtle and strong visual weight variants',- 'Full-bleed mode extends the divider to container edges via negative margins',- 'Themeable via className — target .xds-divider with variant and orientation classes',- ],props: [{name: 'orientation',@@ -51,38 +43,20 @@ export const docs = {],},usage: {- summary: 'Separates different pieces of content.',- content: `## When to use--- Standard level: subtle hairlines to demote sections or regions.-- Emphasized level: critical visual lines for chart axes or input borders.-- High contrast level: strong visual separation.--## When NOT to use--- Emphasized dividers for sectional distinction \u2014 use standard instead.-- Standard dividers for critical content boundaries \u2014 use emphasized instead.--## Best practices--- Do: Use standard dividers for demoting sections and regions.-- Do: Use emphasized dividers for interactive element boundaries.-- Don't: Use emphasized dividers for sectional distinction.-- Don't: Use standard dividers for critical content boundaries.`,+ description: 'A visual separator for dividing content sections. Use subtle dividers to demote sections, emphasized dividers for interactive element boundaries, and strong dividers for high-contrast separation.',+ features: [+ 'Supports horizontal and vertical orientations',+ 'Optional label centered on the divider line',+ 'Subtle and strong visual weight variants',+ 'Full-bleed mode extends the divider to container edges via negative margins',+ 'Themeable via className — target .xds-divider with variant and orientation classes',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Divider',- description: '带有可选标签的视觉分隔线,使用 XDS 设计令牌。',- features: [- '支持水平和垂直方向',- '可选标签居中显示在分隔线上',- '柔和和加强两种视觉粗细变体',- '全出血模式通过负边距将分隔线延伸至容器边缘',- '可通过 className 进行主题定制 — 使用变体和方向类定位 .xds-divider',- ],props: [{name: 'orientation',@@ -119,6 +93,16 @@ export const docsZh = {{className: 'xds-divider', visualProps: ['orientation', 'variant']},],},+ usage: {+ description: '带有可选标签的视觉分隔线,使用 XDS 设计令牌。',+ features: [+ '支持水平和垂直方向',+ '可选标签居中显示在分隔线上',+ '柔和和加强两种视觉粗细变体',+ '全出血模式通过负边距将分隔线延伸至容器边缘',+ '可通过 className 进行主题定制 — 使用变体和方向类定位 .xds-divider',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjsindex 7d4bff8f17..b0ed782a83 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs@@ -2,18 +2,7 @@export const docs = {name: 'DropdownMenu',- description:- 'A dropdown menu component for displaying actionable items in a popup menu.', keywords: ["dropdown","menu","popover","select","actions","contextmenu","overflow","kebab","menubutton"],- features: [- 'Button customization: Customize the trigger button via the `button` prop (supports all XDSButton props)',- 'Data-driven items: Pass items via the `items` prop with support for sections and dividers',- 'Controlled/Uncontrolled: Supports both controlled (`isMenuOpen`/`onOpenChange`) and uncontrolled modes',- 'Custom menu width: Override default width (matches button) via `menuWidth` prop',- 'Sections: Group related items with optional headers using `XDSDropdownMenuSection`',- 'Keyboard navigation: Full keyboard support (Arrow keys, Home, End, Enter, Space, Escape)',- 'Accessibility: Proper ARIA roles (menu, menuitem) and attributes',- 'Custom rendering: Optional `children` render function with `XDSDropdownMenuItem` helper',- ],+ keywords: ["dropdown","menu","popover","select","actions","contextmenu","overflow","kebab","menubutton"],theming: {targets: [{className: 'xds-dropdown-menu'},@@ -24,19 +13,6 @@ export const docs = {{name: '--dropdown-padding', description: 'Inner padding of the menu popup', default: 'var(--spacing-1)'},],},- keyboard:- 'Arrow keys navigate items, Home/End jump to first/last, Enter/Space select, Escape closes the menu',- accessibility: [- 'Uses proper ARIA roles: `menu` on the popup container, `menuitem` on each item',- 'Focus returns to the trigger button when the menu closes',- 'Keyboard navigation automatically skips disabled items',- ],- notes: [- 'Uses `useXDSLayer` with `mode: "context"` for CSS anchor positioning',- 'Uses `XDSButton` internally — chevron is passed via `endContent` and auto-hidden when `isIconOnly` is true',- 'Items are tracked via the `items` prop to enable keyboard navigation',- 'Light dismiss is enabled by default (clicking outside closes menu)',- ],components: [{name: 'XDSDropdownMenu',@@ -195,29 +171,35 @@ export const docs = {},],usage: {- summary: 'Shows options for actions in a dropdown list.',- content: `## When to use--- To present different action options as a next step in a process.-- As sub-navigation to guide users to a next destination.`,+ description: 'A dropdown menu for displaying actionable items in a popup. Use to present action options as a next step in a process or as sub-navigation to guide users to a destination.',+ features: [+ 'Button customization: Customize the trigger button via the `button` prop (supports all XDSButton props)',+ 'Data-driven items: Pass items via the `items` prop with support for sections and dividers',+ 'Controlled/Uncontrolled: Supports both controlled (`isMenuOpen`/`onOpenChange`) and uncontrolled modes',+ 'Custom menu width: Override default width (matches button) via `menuWidth` prop',+ 'Sections: Group related items with optional headers using `XDSDropdownMenuSection`',+ 'Keyboard navigation: Full keyboard support (Arrow keys, Home, End, Enter, Space, Escape)',+ 'Accessibility: Proper ARIA roles (menu, menuitem) and attributes',+ 'Custom rendering: Optional `children` render function with `XDSDropdownMenuItem` helper',+ ],+ accessibility: [+ 'Uses proper ARIA roles: `menu` on the popup container, `menuitem` on each item',+ 'Focus returns to the trigger button when the menu closes',+ 'Keyboard navigation automatically skips disabled items',+ 'Keyboard: Arrow keys navigate items, Home/End jump to first/last, Enter/Space select, Escape closes the menu',+ ],+ notes: [+ 'Uses `useXDSLayer` with `mode: "context"` for CSS anchor positioning',+ 'Uses `XDSButton` internally — chevron is passed via `endContent` and auto-hidden when `isIconOnly` is true',+ 'Items are tracked via the `items` prop to enable keyboard navigation',+ 'Light dismiss is enabled by default (clicking outside closes menu)',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'DropdownMenu',- description:- '用于在弹出菜单中显示可操作项的下拉菜单组件。',- features: [- '按钮自定义:通过 `button` 属性自定义触发按钮(支持所有 XDSButton 属性)',- '数据驱动项:通过 `items` 属性传递菜单项,支持分组和分隔线',- '受控/非受控:同时支持受控(`isMenuOpen`/`onOpenChange`)和非受控模式',- '自定义菜单宽度:通过 `menuWidth` 属性覆盖默认宽度(默认与按钮同宽)',- '分组:使用 `XDSDropdownMenuSection` 将相关项分组并显示可选标题',- '键盘导航:完整的键盘支持(方向键、Home、End、Enter、Space、Escape)',- '无障碍:正确的 ARIA 角色(menu、menuitem)和属性',- '自定义渲染:可选的 `children` 渲染函数,配合 `XDSDropdownMenuItem` 辅助组件',- ],theming: {targets: [{className: 'xds-dropdown-menu'},@@ -228,19 +210,6 @@ export const docsZh = {{name: '--dropdown-padding', description: 'Inner padding of the menu popup', default: 'var(--spacing-1)'},],},- keyboard:- '方向键导航菜单项,Home/End 跳转到首项/末项,Enter/Space 选择,Escape 关闭菜单',- accessibility: [- '使用正确的 ARIA 角色:弹出容器上使用 `menu`,每个菜单项使用 `menuitem`',- '菜单关闭时焦点返回到触发按钮',- '键盘导航自动跳过禁用的菜单项',- ],- notes: [- '使用 `useXDSLayer` 配合 `mode: "context"` 进行 CSS 锚点定位',- '内部使用 `XDSButton`——chevron 通过 `endContent` 传递,图标按钮自动隐藏',- '通过 `items` 属性跟踪菜单项以启用键盘导航',- '默认启用轻量关闭(点击外部关闭菜单)',- ],components: [{name: 'XDSDropdownMenu',@@ -399,6 +368,32 @@ export const docsZh = {],},],+ usage: {+ description:+ '用于在弹出菜单中显示可操作项的下拉菜单组件。',+ features: [+ '按钮自定义:通过 `button` 属性自定义触发按钮(支持所有 XDSButton 属性)',+ '数据驱动项:通过 `items` 属性传递菜单项,支持分组和分隔线',+ '受控/非受控:同时支持受控(`isMenuOpen`/`onOpenChange`)和非受控模式',+ '自定义菜单宽度:通过 `menuWidth` 属性覆盖默认宽度(默认与按钮同宽)',+ '分组:使用 `XDSDropdownMenuSection` 将相关项分组并显示可选标题',+ '键盘导航:完整的键盘支持(方向键、Home、End、Enter、Space、Escape)',+ '无障碍:正确的 ARIA 角色(menu、menuitem)和属性',+ '自定义渲染:可选的 `children` 渲染函数,配合 `XDSDropdownMenuItem` 辅助组件',+ ],+ accessibility: [+ '使用正确的 ARIA 角色:弹出容器上使用 `menu`,每个菜单项使用 `menuitem`',+ '菜单关闭时焦点返回到触发按钮',+ '键盘导航自动跳过禁用的菜单项',+ 'Keyboard: 方向键导航菜单项,Home/End 跳转到首项/末项,Enter/Space 选择,Escape 关闭菜单',+ ],+ notes: [+ '使用 `useXDSLayer` 配合 `mode: "context"` 进行 CSS 锚点定位',+ '内部使用 `XDSButton`——chevron 通过 `endContent` 传递,图标按钮自动隐藏',+ '通过 `items` 属性跟踪菜单项以启用键盘导航',+ '默认启用轻量关闭(点击外部关闭菜单)',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjsindex d7292f35e8..40efcddafc 100644--- a/packages/core/src/EmptyState/EmptyState.doc.mjs+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs@@ -2,18 +2,7 @@export const docs = {name: 'EmptyState',- description:- 'An empty state placeholder for content areas with no data. Displays an icon or illustration, title, optional description, and action buttons.',keywords: ["emptystate","empty","placeholder","nodata","blank","noresults","illustration","blankslate"],- features: [- 'Uses role="status" so screen readers announce the empty state automatically',- 'Icon slot renders as decorative (aria-hidden="true") — no extra labeling needed',- 'Title renders as a heading element (h1-h6, default h3) for correct document outline',- 'Actions are laid out horizontally by default and stack vertically in compact mode',- 'Compact variant reduces spacing for constrained content areas',- 'Accepts xstyle, className, and style props for custom container adjustments',- 'Forwarded ref lands on the root <div> container',- ],props: [{name: 'title',@@ -66,24 +55,22 @@ export const docs = {{className: 'xds-emptystate'},],},- accessibility: [- 'Container uses role="status" to announce the empty state content to screen readers.',- 'Icon wrapper has aria-hidden="true" so decorative icons are ignored by assistive technology.',- 'Title renders as a heading element (h1-h6 via headingLevel prop, default h3), keeping it in the document heading outline.',- ],usage: {- summary: 'Provides guidance and context when there is no data to display.',- content: `## When to use--- Null states when no content exists yet.-- Failed loading states.-- When search or filter results return nothing.--## Best practices--- Do: Be clear and direct with messaging.-- Do: Use simple language and provide context.-- Do: Offer a next step so users know how to proceed.`,+ description: 'An empty state placeholder that provides guidance and context when there is no data to display. Use for null states, failed loading states, or when search and filter results return nothing. Be clear with messaging and offer a next step so users know how to proceed.',+ features: [+ 'Uses role="status" so screen readers announce the empty state automatically',+ 'Icon slot renders as decorative (aria-hidden="true") — no extra labeling needed',+ 'Title renders as a heading element (h1-h6, default h3) for correct document outline',+ 'Actions are laid out horizontally by default and stack vertically in compact mode',+ 'Compact variant reduces spacing for constrained content areas',+ 'Accepts xstyle, className, and style props for custom container adjustments',+ 'Forwarded ref lands on the root <div> container',+ ],+ accessibility: [+ 'Container uses role="status" to announce the empty state content to screen readers.',+ 'Icon wrapper has aria-hidden="true" so decorative icons are ignored by assistive technology.',+ 'Title renders as a heading element (h1-h6 via headingLevel prop, default h3), keeping it in the document heading outline.',+ ],anatomy: [{name: 'Illustration', required: false, description: 'Visual cue that reinforces the empty state context.'},{name: 'Title', required: true, description: 'Primary message explaining the empty state.'},@@ -96,17 +83,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'EmptyState',- description:- '用于无数据内容区域的空状态占位组件。显示图标或插图、标题、可选描述和操作按钮。',- features: [- '使用 role="status",屏幕阅读器会自动播报空状态内容',- '图标插槽渲染为装饰性元素(aria-hidden="true"),无需额外标注',- '标题渲染为标题元素(h1-h6,默认 h3),保持正确的文档大纲',- '操作按钮默认水平排列,紧凑模式下垂直堆叠',- '紧凑变体减少间距,适用于空间受限的内容区域',- '接受 xstyle、className 和 style 属性用于自定义容器调整',- '转发的 ref 指向根 <div> 容器',- ],props: [{name: 'title',@@ -159,11 +135,24 @@ export const docsZh = {{className: 'xds-emptystate'},],},- accessibility: [- '容器使用 role="status" 向屏幕阅读器播报空状态内容。',- '图标包装器具有 aria-hidden="true",使装饰性图标被辅助技术忽略。',- '标题渲染为标题元素(通过 headingLevel 属性设置 h1-h6,默认 h3),保持在文档标题大纲中。',- ],+ usage: {+ description:+ '用于无数据内容区域的空状态占位组件。显示图标或插图、标题、可选描述和操作按钮。',+ features: [+ '使用 role="status",屏幕阅读器会自动播报空状态内容',+ '图标插槽渲染为装饰性元素(aria-hidden="true"),无需额外标注',+ '标题渲染为标题元素(h1-h6,默认 h3),保持正确的文档大纲',+ '操作按钮默认水平排列,紧凑模式下垂直堆叠',+ '紧凑变体减少间距,适用于空间受限的内容区域',+ '接受 xstyle、className 和 style 属性用于自定义容器调整',+ '转发的 ref 指向根 <div> 容器',+ ],+ accessibility: [+ '容器使用 role="status" 向屏幕阅读器播报空状态内容。',+ '图标包装器具有 aria-hidden="true",使装饰性图标被辅助技术忽略。',+ '标题渲染为标题元素(通过 headingLevel 属性设置 h1-h6,默认 h3),保持在文档标题大纲中。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjsindex 0ba008abf9..354167af91 100644--- a/packages/core/src/Field/Field.doc.mjs+++ b/packages/core/src/Field/Field.doc.mjs@@ -2,19 +2,7 @@export const docs = {name: 'Field',- description:- 'A form field wrapper component that provides label, description, and optional/required indicators.',keywords: ["field","formfield","formgroup","formcontrol","label","input","required","optional","helpertext","hint"],- features: [- 'Label Support — required label for accessibility (can be visually hidden)',- 'Description — optional description text displayed between the label and input',- 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',- 'Label Tooltip — optional info icon with tooltip at end of label',- 'Disabled State — propagates disabled styling to label',- 'Status Messages — attached/detached validation feedback with role="status" and aria-live="polite"',- 'Accessible — label properly associated with input via htmlFor/id',- 'Styled with StyleX — uses XDS design tokens for consistent styling',- ],theming: {targets: [{className: 'xds-field'},@@ -25,17 +13,6 @@ export const docs = {{name: '--input-radius', description: 'Border radius of input fields', default: 'var(--radius-element)'},],},- notes: [- 'Parent components are responsible for generating IDs (using the useId hook).',- 'Label is always rendered for accessibility; use isLabelHidden to hide visually.',- 'Hidden label uses a CSS technique that remains accessible to screen readers.',- 'Description is rendered when provided; if descriptionID is also provided, the description element gets that ID for aria-describedby association.',- 'isOptional and isRequired are mutually exclusive; setting both will show "Optional" (dev warning emitted).',- 'Optional/Required text appears on the same line as the label.',- 'Status messages use role="status" and aria-live="polite" for screen reader announcements.',- 'Use statusVariant="attached" (default) for bordered inputs; "detached" for checkboxes, switches, sliders.',- 'isDisabled propagates disabled styling to the label (color + cursor).',- ],components: [{name: 'XDSField',@@ -236,28 +213,34 @@ export const docs = {},],usage: {- summary: 'A form field wrapper that provides label, description, and optional/required indicators around an input.',- content: `## When to use--- Wrapping input components in forms to provide consistent labels, descriptions, and validation states.`,+ description: 'A form field wrapper that provides label, description, and optional/required indicators around an input. Use to wrap input components in forms for consistent labels, descriptions, and validation states.',+ features: [+ 'Label Support — required label for accessibility (can be visually hidden)',+ 'Description — optional description text displayed between the label and input',+ 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',+ 'Label Tooltip — optional info icon with tooltip at end of label',+ 'Disabled State — propagates disabled styling to label',+ 'Status Messages — attached/detached validation feedback with role="status" and aria-live="polite"',+ 'Accessible — label properly associated with input via htmlFor/id',+ 'Styled with StyleX — uses XDS design tokens for consistent styling',+ ],+ notes: [+ 'Parent components are responsible for generating IDs (using the useId hook).',+ 'Label is always rendered for accessibility; use isLabelHidden to hide visually.',+ 'Hidden label uses a CSS technique that remains accessible to screen readers.',+ 'Description is rendered when provided; if descriptionID is also provided, the description element gets that ID for aria-describedby association.',+ 'isOptional and isRequired are mutually exclusive; setting both will show "Optional" (dev warning emitted).',+ 'Optional/Required text appears on the same line as the label.',+ 'Status messages use role="status" and aria-live="polite" for screen reader announcements.',+ 'Use statusVariant="attached" (default) for bordered inputs; "detached" for checkboxes, switches, sliders.',+ 'isDisabled propagates disabled styling to the label (color + cursor).',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Field',- description:- '表单字段包装组件,提供标签、描述以及可选/必填指示器。',- features: [- '标签支持 - 必需的标签用于无障碍访问(可视觉隐藏)',- '描述 - 可选的描述文本,显示在标签和输入框之间',- '可选/必填指示器 - 显示"Optional"或"Required"文本,带圆点分隔符',- '标签工具提示 - 可选的信息图标,在标签末尾显示工具提示',- '禁用状态 - 将禁用样式传递给标签',- '状态消息 - attached/detached 验证反馈,带 role="status" 和 aria-live="polite"',- '无障碍 - 通过 htmlFor/id 将标签与输入框正确关联',- '使用 StyleX 样式 - 使用 XDS 设计令牌实现一致的样式',- ],theming: {targets: [{className: 'xds-field'},@@ -268,17 +251,6 @@ export const docsZh = {{name: '--input-radius', description: 'Border radius of input fields', default: 'var(--radius-element)'},],},- notes: [- '父组件负责生成 ID(使用 useId hook)。',- '标签始终渲染以确保无障碍访问;使用 isLabelHidden 进行视觉隐藏。',- '隐藏标签使用 CSS 技术,屏幕阅读器仍可访问。',- '提供 description 时会渲染描述文本;如果同时提供 descriptionID,描述元素会获得该 ID 用于 aria-describedby 关联。',- 'isOptional 和 isRequired 互斥;同时设置两者将显示"Optional"(开发模式下发出警告)。',- '可选/必填文本与标签显示在同一行。',- '状态消息使用 role="status" 和 aria-live="polite" 进行屏幕阅读器播报。',- '使用 statusVariant="attached"(默认)用于带边框的输入框;"detached" 用于复选框、开关、滑块。',- 'isDisabled 将禁用样式传递给标签(颜色 + 光标)。',- ],components: [{name: 'XDSField',@@ -479,6 +451,31 @@ export const docsZh = {],},],+ usage: {+ description:+ '表单字段包装组件,提供标签、描述以及可选/必填指示器。',+ features: [+ '标签支持 - 必需的标签用于无障碍访问(可视觉隐藏)',+ '描述 - 可选的描述文本,显示在标签和输入框之间',+ '可选/必填指示器 - 显示"Optional"或"Required"文本,带圆点分隔符',+ '标签工具提示 - 可选的信息图标,在标签末尾显示工具提示',+ '禁用状态 - 将禁用样式传递给标签',+ '状态消息 - attached/detached 验证反馈,带 role="status" 和 aria-live="polite"',+ '无障碍 - 通过 htmlFor/id 将标签与输入框正确关联',+ '使用 StyleX 样式 - 使用 XDS 设计令牌实现一致的样式',+ ],+ notes: [+ '父组件负责生成 ID(使用 useId hook)。',+ '标签始终渲染以确保无障碍访问;使用 isLabelHidden 进行视觉隐藏。',+ '隐藏标签使用 CSS 技术,屏幕阅读器仍可访问。',+ '提供 description 时会渲染描述文本;如果同时提供 descriptionID,描述元素会获得该 ID 用于 aria-describedby 关联。',+ 'isOptional 和 isRequired 互斥;同时设置两者将显示"Optional"(开发模式下发出警告)。',+ '可选/必填文本与标签显示在同一行。',+ '状态消息使用 role="status" 和 aria-live="polite" 进行屏幕阅读器播报。',+ '使用 statusVariant="attached"(默认)用于带边框的输入框;"detached" 用于复选框、开关、滑块。',+ 'isDisabled 将禁用样式传递给标签(颜色 + 光标)。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjsindex 0a2fc87bf4..6852748a20 100644--- a/packages/core/src/FormLayout/FormLayout.doc.mjs+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs@@ -2,8 +2,6 @@export const docs = {name: 'FormLayout',- description:- 'A spatial layout container for arranging form fields with consistent spacing and direction.',keywords: ["formlayout","form","fieldset","formgroup","formcontainer","fields","vertical","horizontal"],props: [{@@ -26,49 +24,25 @@ export const docs = {'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',},],- features: [- "Three layout modes: 'vertical' (default), 'horizontal', and 'horizontal-labels'",- 'Direction context via XDSFormLayoutContext — children can read the current layout direction',- 'Responsive: horizontal-labels collapses to vertical on narrow viewports (<=480px)',- 'Nestable: inner FormLayout overrides context for its children',- 'Purely spatial: does not manage form state or render <form> — form submission is separate',- ],theming: {targets: [{className: 'xds-form-layout', visualProps: ['direction']},],},- notes: [- 'Renders a <div>, not a <form>. Use a separate <form> element and connect submit buttons via the HTML form attribute.',- 'XDSFormLayoutContext provides { direction } to children. Import from @xds/core/FormLayout to read layout direction in custom components.',- 'Also accepts standard HTML div attributes (id, role, aria-*, etc.) via rest props.',- ],usage: {- summary: 'Wraps input components to collect structured user input with validation and confirmation.',- content: `## When to use--- Sign-in flows.-- Creating or editing objects.-- Submitting orders.-- Changing settings.--## When NOT to use--- One-off confirmations.-- Quick inline tweaks.-- Navigation or search.--## Best practices--- Do: Use a single column layout.-- Don't: Use a multi-column layout.-- Do: Keep text width between 50\u201380 characters.-- Don't: Position multiple fields across rows (except related short fields like city/state/zip).-- Prefer labels over placeholders for input fields.-- Validate input early to surface errors as soon as possible.-- Minimize the number of fields to reduce user effort.-- Use top-aligned labels for step-by-step flows (wizards).-- Use left-aligned labels for scanning-heavy layouts (settings).`,+ description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Wraps input components to collect structured user input with validation and confirmation. Best suited for sign-in flows, creating or editing objects, and settings — prefer single column layouts with top-aligned labels for step-by-step flows.',+ features: [+ "Three layout modes: 'vertical' (default), 'horizontal', and 'horizontal-labels'",+ 'Direction context via XDSFormLayoutContext — children can read the current layout direction',+ 'Responsive: horizontal-labels collapses to vertical on narrow viewports (<=480px)',+ 'Nestable: inner FormLayout overrides context for its children',+ 'Purely spatial: does not manage form state or render <form> — form submission is separate',+ ],+ notes: [+ 'Renders a <div>, not a <form>. Use a separate <form> element and connect submit buttons via the HTML form attribute.',+ 'XDSFormLayoutContext provides { direction } to children. Import from @xds/core/FormLayout to read layout direction in custom components.',+ 'Also accepts standard HTML div attributes (id, role, aria-*, etc.) via rest props.',+ ],anatomy: [{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},{name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},@@ -80,8 +54,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'FormLayout',- description:- '用于以一致的间距和方向排列表单字段的空间布局容器。',props: [{name: 'direction',@@ -103,23 +75,27 @@ export const docsZh = {'用于布局自定义(外边距、定位、尺寸)的 StyleX 样式。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',},],- features: [- '三种布局模式:\'vertical\'(默认)、\'horizontal\' 和 \'horizontal-labels\'',- '通过 XDSFormLayoutContext 提供方向上下文 - 子组件可以读取当前布局方向',- '响应式:horizontal-labels 在窄视口(<=480px)时折叠为垂直布局',- '可嵌套:内部 FormLayout 会为其子组件覆盖上下文',- '纯空间布局:不管理表单状态或渲染 <form> - 表单提交是独立的',- ],theming: {targets: [{className: 'xds-form-layout', visualProps: ['direction']},],},- notes: [- '渲染 <div> 而非 <form>。使用单独的 <form> 元素,并通过 HTML form 属性连接提交按钮。',- 'XDSFormLayoutContext 向子组件提供 { direction }。从 @xds/core/FormLayout 导入以在自定义组件中读取布局方向。',- '还通过 rest props 接受标准 HTML div 属性(id、role、aria-* 等)。',- ],+ usage: {+ description:+ '用于以一致的间距和方向排列表单字段的空间布局容器。',+ features: [+ '三种布局模式:\'vertical\'(默认)、\'horizontal\' 和 \'horizontal-labels\'',+ '通过 XDSFormLayoutContext 提供方向上下文 - 子组件可以读取当前布局方向',+ '响应式:horizontal-labels 在窄视口(<=480px)时折叠为垂直布局',+ '可嵌套:内部 FormLayout 会为其子组件覆盖上下文',+ '纯空间布局:不管理表单状态或渲染 <form> - 表单提交是独立的',+ ],+ notes: [+ '渲染 <div> 而非 <form>。使用单独的 <form> 元素,并通过 HTML form 属性连接提交按钮。',+ 'XDSFormLayoutContext 向子组件提供 { direction }。从 @xds/core/FormLayout 导入以在自定义组件中读取布局方向。',+ '还通过 rest props 接受标准 HTML div 属性(id、role、aria-* 等)。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjsindex 87eae9e9b1..391ed80686 100644--- a/packages/core/src/Grid/Grid.doc.mjs+++ b/packages/core/src/Grid/Grid.doc.mjs@@ -2,25 +2,28 @@export const docs = {name: 'Grid',- description: 'CSS Grid-based layout with responsive auto-fit support.', keywords: ["grid","columns","responsive","auto-fit","masonry","tiles","row","col","simplegrid"],- features: [- 'Fixed-column grids via the `columns` prop',- 'Responsive auto-fit columns via `minChildWidth` — items wrap based on available space',- 'Combine `minChildWidth` and `columns` to cap the maximum number of columns',- 'Gap tokens via `SpacingScale` values for `gap`, `rowGap`, and `columnGap`',- 'Vertical and horizontal item alignment via `align` and `justify`',- 'XDSGridSpan lets individual items span multiple columns or rows',- 'Theming support — override root styles via the `grid` component key',- ],+ keywords: ["grid","columns","responsive","auto-fit","masonry","tiles","row","col","simplegrid"],+ usage: {+ description:+ 'CSS Grid-based layout with responsive auto-fit support. Use for any grid layout instead of manual CSS grid — it handles gap tokens and works with any column count.',+ features: [+ 'Fixed-column grids via the `columns` prop',+ 'Responsive auto-fit columns via `minChildWidth` — items wrap based on available space',+ 'Combine `minChildWidth` and `columns` to cap the maximum number of columns',+ 'Gap tokens via `SpacingScale` values for `gap`, `rowGap`, and `columnGap`',+ 'Vertical and horizontal item alignment via `align` and `justify`',+ 'XDSGridSpan lets individual items span multiple columns or rows',+ ],+ notes: [+ 'Use XDSGrid for any grid layout instead of manual CSS grid (`display: "grid"`, `gridTemplateColumns`). It handles gap tokens and works with any column count.',+ ],+ },theming: {targets: [{className: 'xds-grid', visualProps: ['align', 'columns', 'gap', 'justify']},{className: 'xds-grid-span'},],},- notes: [- 'Use XDSGrid for any grid layout instead of manual CSS grid (`display: "grid"`, `gridTemplateColumns`). It handles gap tokens and works with any column count.',- ],components: [{name: 'XDSGrid',@@ -108,33 +111,17 @@ export const docs = {],},],- usage: {- summary: 'CSS Grid-based layout with responsive auto-fit support.',- },};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Grid',- description: '基于 CSS Grid 的布局组件,支持响应式自动适配。',- features: [- '通过 `columns` 属性实现固定列网格',- '通过 `minChildWidth` 实现响应式自动适配列 - 项目根据可用空间自动换行',- '组合 `minChildWidth` 和 `columns` 来限制最大列数',- '通过 `SpacingScale` 值为 `gap`、`rowGap` 和 `columnGap` 设置间距令牌',- '通过 `align` 和 `justify` 实现垂直和水平项对齐',- 'XDSGridSpan 允许单个项跨越多列或多行',- '主题支持 - 通过 `grid` 组件键覆盖根样式',- ],theming: {targets: [{className: 'xds-grid', visualProps: ['align', 'columns', 'gap', 'justify']},{className: 'xds-grid-span'},],},- notes: [- '对于任何网格布局,请使用 XDSGrid 代替手动 CSS grid(`display: "grid"`、`gridTemplateColumns`)。它处理间距令牌并支持任意列数。',- ],components: [{name: 'XDSGrid',@@ -223,6 +210,21 @@ export const docsZh = {],},],+ usage: {+ description: '基于 CSS Grid 的布局组件,支持响应式自动适配。',+ features: [+ '通过 `columns` 属性实现固定列网格',+ '通过 `minChildWidth` 实现响应式自动适配列 - 项目根据可用空间自动换行',+ '组合 `minChildWidth` 和 `columns` 来限制最大列数',+ '通过 `SpacingScale` 值为 `gap`、`rowGap` 和 `columnGap` 设置间距令牌',+ '通过 `align` 和 `justify` 实现垂直和水平项对齐',+ 'XDSGridSpan 允许单个项跨越多列或多行',+ '主题支持 - 通过 `grid` 组件键覆盖根样式',+ ],+ notes: [+ '对于任何网格布局,请使用 XDSGrid 代替手动 CSS grid(`display: "grid"`、`gridTemplateColumns`)。它处理间距令牌并支持任意列数。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex 0b0299b8d9..a2fc5930fd 100644--- a/packages/core/src/HoverCard/HoverCard.doc.mjs+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs@@ -2,29 +2,7 @@export const docs = {name: 'HoverCard',- description:- 'A hover/focus triggered overlay for displaying rich, interactive content anchored to a trigger element.', keywords: ["hovercard","hover card","popover","tooltip","preview card","flyout","overlay","hover popup"],- features: [- 'CSS Anchor Positioning for automatic placement relative to trigger elements',- 'Popover API for top-layer rendering — no React portals needed',- 'Hover triggers with configurable show and hide delays',- 'Focus triggers with auto-detection for focusable elements',- 'Stay-open behavior when mouse/focus moves into the hover card',- 'display:contents wrapper preserves children refs',- 'Hover indication (dashed underline) for text-only triggers',- ],- notes: [- 'useXDSHoverCard returns a describedBy id — pass it as aria-describedby on the trigger for screen reader support.',- 'When composing multiple aria-describedby sources, merge them with a utility: ids.filter(Boolean).join(" ") || undefined.',- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',- ],- accessibility: [- 'Links the hover card content to the trigger via aria-describedby.',- 'When composing multiple aria-describedby sources, merge them with a utility.',- 'Escape key dismisses the hover card and returns focus to the trigger.',- ],- keyboard:- 'Escape closes the hover card. Focus triggers show/hide based on the focusTrigger option.',+ keywords: ["hovercard","hover card","popover","tooltip","preview card","flyout","overlay","hover popup"],theming: {targets: [{className: 'xds-hovercard'},@@ -154,26 +132,27 @@ export const docs = {},],usage: {- summary: 'Interactive cards providing additional information on hover.',- content: `## When to use--- Non-critical supplementary information.-- Progressive disclosure of details.-- Non-interruptive education or onboarding.-- Rich content with media (images, icons, text pairings).--## When NOT to use--- Plain text hints \u2014 use Tooltip instead.-- Dropdown menus \u2014 use Popover instead.-- Page content grouping \u2014 use Card instead.-- Arbitrary or frequently changing content.--## Best practices--- Do: Use thoughtfully and situationally.-- Don't: Use on arbitrary or frequently changing content.-- Place hover card 4px from the context element.`,+ description:+ 'A hover/focus triggered overlay for displaying rich, interactive content anchored to a trigger element. Use hover cards for non-critical supplementary information, progressive disclosure, or non-interruptive education \u2014 for plain text hints use Tooltip, for menus use Popover.',+ features: [+ 'CSS Anchor Positioning for automatic placement relative to trigger elements',+ 'Popover API for top-layer rendering \u2014 no React portals needed',+ 'Hover triggers with configurable show and hide delays',+ 'Focus triggers with auto-detection for focusable elements',+ 'Stay-open behavior when mouse/focus moves into the hover card',+ 'Hover indication (dashed underline) for text-only triggers',+ ],+ accessibility: [+ 'Links the hover card content to the trigger via aria-describedby.',+ 'When composing multiple aria-describedby sources, merge them with a utility.',+ 'Keyboard: Escape dismisses the hover card and returns focus to the trigger; focus events trigger show/hide based on the focusTrigger option.',+ ],+ notes: [+ 'useXDSHoverCard returns a describedBy id \u2014 pass it as aria-describedby on the trigger for screen reader support.',+ 'When composing multiple aria-describedby sources, merge them with a utility: ids.filter(Boolean).join(" ") || undefined.',+ 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',+ 'display:contents wrapper preserves children refs.',+ ],anatomy: [{name: 'Header', required: false, description: 'Eyebrow header with optional copy and close buttons.'},{name: 'Body', required: true, description: 'Text pairings, icons, and media content.'},@@ -185,29 +164,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'HoverCard',- description:- '悬停/聚焦触发的浮层,用于显示锚定到触发元素的富交互内容。',- features: [- 'CSS 锚点定位:相对于触发元素自动放置',- 'Popover API 实现顶层渲染,无需 React 传送门',- '悬停触发:可配置显示和隐藏延迟',- '聚焦触发:自动检测可聚焦元素',- '鼠标/焦点移入悬浮卡片时保持打开',- 'display:contents 包装器保留子元素 ref',- '悬停指示(虚线下划线)用于纯文本触发器',- ],- notes: [- 'useXDSHoverCard 返回一个 describedBy id,将其作为 aria-describedby 传递给触发器以支持屏幕阅读器。',- '当组合多个 aria-describedby 来源时,使用工具函数合并:ids.filter(Boolean).join(" ") || undefined。',- 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',- ],- accessibility: [- '通过 aria-describedby 将悬浮卡片内容关联到触发器。',- '当组合多个 aria-describedby 来源时,使用工具函数合并。',- '按 Escape 键关闭悬浮卡片并将焦点返回到触发器。',- ],- keyboard:- 'Escape 关闭悬浮卡片。焦点触发器根据 focusTrigger 选项控制显示/隐藏。',theming: {targets: [{className: 'xds-hovercard'},@@ -337,6 +293,30 @@ export const docsZh = {],},],+ usage: {+ description:+ '悬停/聚焦触发的浮层,用于显示锚定到触发元素的富交互内容。',+ features: [+ 'CSS 锚点定位:相对于触发元素自动放置',+ 'Popover API 实现顶层渲染,无需 React 传送门',+ '悬停触发:可配置显示和隐藏延迟',+ '聚焦触发:自动检测可聚焦元素',+ '鼠标/焦点移入悬浮卡片时保持打开',+ 'display:contents 包装器保留子元素 ref',+ '悬停指示(虚线下划线)用于纯文本触发器',+ ],+ accessibility: [+ '通过 aria-describedby 将悬浮卡片内容关联到触发器。',+ '当组合多个 aria-describedby 来源时,使用工具函数合并。',+ '按 Escape 键关闭悬浮卡片并将焦点返回到触发器。',+ 'Keyboard: Escape 关闭悬浮卡片。焦点触发器根据 focusTrigger 选项控制显示/隐藏。',+ ],+ notes: [+ 'useXDSHoverCard 返回一个 describedBy id,将其作为 aria-describedby 传递给触发器以支持屏幕阅读器。',+ '当组合多个 aria-describedby 来源时,使用工具函数合并:ids.filter(Boolean).join(" ") || undefined。',+ 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjsindex e8abff38d6..a771aae59d 100644--- a/packages/core/src/Icon/Icon.doc.mjs+++ b/packages/core/src/Icon/Icon.doc.mjs@@ -2,18 +2,7 @@export const docs = {name: 'Icon',- description:- 'Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.',keywords: ["icon","svg","glyph","symbol","pictogram","graphic","vector"],- features: [- "Semantic Icon Names: Use names like 'close' or 'chevronDown' — resolved from the theme's icon registry",- 'Direct Icon Components: Pass any SVG icon component (heroicons, lucide, etc.) directly',- "Theme-Adaptable: Semantic icons automatically match the active theme's icon set",- 'Built-in Fallbacks: 12 lightweight inline SVGs (~1.4KB) ensure icons render without a theme',- 'Theme Colors: Color variants mapped to XDS icon color tokens',- 'Consistent Sizing: Four size options aligned with common UI patterns',- 'Accessible: Icons are hidden from screen readers by default (aria-hidden)',- ],props: [{name: 'icon',@@ -39,39 +28,37 @@ export const docs = {{className: 'xds-icon', visualProps: ['color', 'size']},],},- accessibility: [- 'Icons are hidden from screen readers by default via aria-hidden="true" since icons are typically decorative.',- 'For meaningful icons, set aria-hidden={false}, role="img", and aria-label to provide accessible context.',- ],- notes: [- 'When icon is a semantic name string, resolution order is: (1) theme registry — if an XDSTheme is active and provides an icon for that name, it is used; (2) built-in fallback — otherwise, a lightweight inline SVG is rendered. Components always render visually complete, even without a theme. Themes can override any or all icons; the registry accepts partial overrides.',- 'When icon is a component, additional SVG props (like aria-label, role) are passed through to the underlying SVG element.',- 'flexShrink: 0 prevents icons from shrinking in flex containers.',- 'String mode wraps the resolved icon in a <span> with fontSize-based sizing so 1em-based registry icons scale correctly.',- 'Component mode passes stylex.props directly to the SVG element for zero-overhead styling.',- 'Semantic icon names and their usages — close (CloseButton, TimeInput): ✕ close/dismiss; chevronDown (DropdownMenu, Selector, TabMenu): ▾ expand/dropdown; chevronLeft (Calendar): ‹ previous; chevronRight (Calendar): › next; check (Selector, TabMenu): ✓ selected item; checkCircle (Input status): ✓○ success; xCircle (Input status): ✕○ error; warning (Input status): △! warning; info (FieldLabel): ⓘ information tooltip; calendar (DateInput): 📅 date picker; clock (TimeInput): 🕐 time picker; externalLink (Link): ↗ opens in new window.',- 'Color token mappings — primary: --color-icon-primary (default); secondary: --color-icon-secondary (de-emphasized); tertiary: --color-icon-secondary (subtle/background); disabled: --color-icon-disabled (disabled state); accent: --color-accent (interactive/actionable); positive: --color-success (success/confirmation); negative: --color-error (error/destructive); warning: --color-warning (caution/attention); inherit: currentColor (inherits from parent text color).',- 'Size dimensions — xsm: 12x12px (dense UI, badges, indicators); sm: 16x16px (inline with text, compact UI); md: 20x20px (default, buttons, inputs); lg: 24x24px (emphasis, standalone icons).',- ],usage: {- summary: 'Renders icons with XDS design system colors and sizes.',+ description:+ 'Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.',+ features: [+ "Semantic Icon Names: Use names like 'close' or 'chevronDown' — resolved from the theme's icon registry",+ 'Direct Icon Components: Pass any SVG icon component (heroicons, lucide, etc.) directly',+ "Theme-Adaptable: Semantic icons automatically match the active theme's icon set",+ 'Built-in Fallbacks: 12 lightweight inline SVGs (~1.4KB) ensure icons render without a theme',+ 'Theme Colors: Color variants mapped to XDS icon color tokens',+ 'Consistent Sizing: Four size options aligned with common UI patterns',+ ],+ accessibility: [+ 'Icons are hidden from screen readers by default via aria-hidden="true" since icons are typically decorative.',+ 'For meaningful icons, set aria-hidden={false}, role="img", and aria-label to provide accessible context.',+ ],+ notes: [+ 'When icon is a semantic name string, resolution order is: (1) theme registry — if an XDSTheme is active and provides an icon for that name, it is used; (2) built-in fallback — otherwise, a lightweight inline SVG is rendered. Components always render visually complete, even without a theme. Themes can override any or all icons; the registry accepts partial overrides.',+ 'When icon is a component, additional SVG props (like aria-label, role) are passed through to the underlying SVG element.',+ 'flexShrink: 0 prevents icons from shrinking in flex containers.',+ 'String mode wraps the resolved icon in a <span> with fontSize-based sizing so 1em-based registry icons scale correctly.',+ 'Component mode passes stylex.props directly to the SVG element for zero-overhead styling.',+ 'Semantic icon names and their usages — close (CloseButton, TimeInput): ✕ close/dismiss; chevronDown (DropdownMenu, Selector, TabMenu): ▾ expand/dropdown; chevronLeft (Calendar): ‹ previous; chevronRight (Calendar): › next; check (Selector, TabMenu): ✓ selected item; checkCircle (Input status): ✓○ success; xCircle (Input status): ✕○ error; warning (Input status): △! warning; info (FieldLabel): ⓘ information tooltip; calendar (DateInput): 📅 date picker; clock (TimeInput): 🕐 time picker; externalLink (Link): ↗ opens in new window.',+ 'Color token mappings — primary: --color-icon-primary (default); secondary: --color-icon-secondary (de-emphasized); tertiary: --color-icon-secondary (subtle/background); disabled: --color-icon-disabled (disabled state); accent: --color-accent (interactive/actionable); positive: --color-success (success/confirmation); negative: --color-error (error/destructive); warning: --color-warning (caution/attention); inherit: currentColor (inherits from parent text color).',+ 'Size dimensions — xsm: 12x12px (dense UI, badges, indicators); sm: 16x16px (inline with text, compact UI); md: 20x20px (default, buttons, inputs); lg: 24x24px (emphasis, standalone icons).',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Icon',- description:- '使用 XDS 设计系统颜色和尺寸渲染图标。支持直接使用 SVG 图标组件和语义图标名称(可自动适配当前主题)。',- features: [- "语义图标名称:使用 'close' 或 'chevronDown' 等名称,从主题的图标注册表中解析",- '直接图标组件:直接传入任何 SVG 图标组件(heroicons、lucide 等)',- '主题适配:语义图标自动匹配当前活动主题的图标集',- '内置回退:12 个轻量级内联 SVG(约 1.4KB)确保在无主题时也能正常渲染',- '主题颜色:颜色变体映射到 XDS 图标颜色令牌',- '一致的尺寸:四种尺寸选项,与常见 UI 模式对齐',- '无障碍:图标默认对屏幕阅读器隐藏(aria-hidden)',- ],props: [{name: 'icon',@@ -97,20 +84,33 @@ export const docsZh = {{className: 'xds-icon', visualProps: ['color', 'size']},],},- accessibility: [- '图标默认通过 aria-hidden="true" 对屏幕阅读器隐藏,因为图标通常是装饰性的。',- '对于有意义的图标,设置 aria-hidden={false}、role="img" 和 aria-label 以提供无障碍上下文。',- ],- notes: [- '当 icon 为语义名称字符串时,解析顺序为:(1) 主题注册表——如果 XDSTheme 处于活动状态并为该名称提供了图标,则使用该图标;(2) 内置回退——否则渲染轻量级内联 SVG。组件始终能完整渲染,即使没有主题。主题可以覆盖任意或所有图标;注册表接受部分覆盖。',- '当 icon 为组件时,额外的 SVG 属性(如 aria-label、role)会透传到底层 SVG 元素。',- 'flexShrink: 0 防止图标在 flex 容器中被压缩。',- '字符串模式将解析后的图标包装在 <span> 中,使用基于 fontSize 的尺寸,使基于 1em 的注册表图标正确缩放。',- '组件模式将 stylex.props 直接传递给 SVG 元素,实现零开销样式。',- '语义图标名称及其用途——close(CloseButton、TimeInput):✕ 关闭/消除;chevronDown(DropdownMenu、Selector、TabMenu):▾ 展开/下拉;chevronLeft(Calendar):‹ 上一个;chevronRight(Calendar):› 下一个;check(Selector、TabMenu):✓ 已选项;checkCircle(Input 状态):✓○ 成功;xCircle(Input 状态):✕○ 错误;warning(Input 状态):△! 警告;info(FieldLabel):ⓘ 信息提示;calendar(DateInput):📅 日期选择器;clock(TimeInput):🕐 时间选择器;externalLink(Link):↗ 在新窗口中打开。',- '颜色令牌映射——primary:--color-icon-primary(默认);secondary:--color-icon-secondary(弱化);tertiary:--color-icon-secondary(微妙/背景);disabled:--color-icon-disabled(禁用状态);accent:--color-accent(交互/可操作);positive:--color-success(成功/确认);negative:--color-error(错误/危险);warning:--color-warning(警告/注意);inherit:currentColor(继承父文本颜色)。',- '尺寸规格——xsm:12x12px(密集 UI、徽章、指示器);sm:16x16px(与文本内联、紧凑 UI);md:20x20px(默认,按钮、输入框);lg:24x24px(强调、独立图标)。',- ],+ usage: {+ description:+ '使用 XDS 设计系统颜色和尺寸渲染图标。支持直接使用 SVG 图标组件和语义图标名称(可自动适配当前主题)。',+ features: [+ "语义图标名称:使用 'close' 或 'chevronDown' 等名称,从主题的图标注册表中解析",+ '直接图标组件:直接传入任何 SVG 图标组件(heroicons、lucide 等)',+ '主题适配:语义图标自动匹配当前活动主题的图标集',+ '内置回退:12 个轻量级内联 SVG(约 1.4KB)确保在无主题时也能正常渲染',+ '主题颜色:颜色变体映射到 XDS 图标颜色令牌',+ '一致的尺寸:四种尺寸选项,与常见 UI 模式对齐',+ '无障碍:图标默认对屏幕阅读器隐藏(aria-hidden)',+ ],+ accessibility: [+ '图标默认通过 aria-hidden="true" 对屏幕阅读器隐藏,因为图标通常是装饰性的。',+ '对于有意义的图标,设置 aria-hidden={false}、role="img" 和 aria-label 以提供无障碍上下文。',+ ],+ notes: [+ '当 icon 为语义名称字符串时,解析顺序为:(1) 主题注册表——如果 XDSTheme 处于活动状态并为该名称提供了图标,则使用该图标;(2) 内置回退——否则渲染轻量级内联 SVG。组件始终能完整渲染,即使没有主题。主题可以覆盖任意或所有图标;注册表接受部分覆盖。',+ '当 icon 为组件时,额外的 SVG 属性(如 aria-label、role)会透传到底层 SVG 元素。',+ 'flexShrink: 0 防止图标在 flex 容器中被压缩。',+ '字符串模式将解析后的图标包装在 <span> 中,使用基于 fontSize 的尺寸,使基于 1em 的注册表图标正确缩放。',+ '组件模式将 stylex.props 直接传递给 SVG 元素,实现零开销样式。',+ '语义图标名称及其用途——close(CloseButton、TimeInput):✕ 关闭/消除;chevronDown(DropdownMenu、Selector、TabMenu):▾ 展开/下拉;chevronLeft(Calendar):‹ 上一个;chevronRight(Calendar):› 下一个;check(Selector、TabMenu):✓ 已选项;checkCircle(Input 状态):✓○ 成功;xCircle(Input 状态):✕○ 错误;warning(Input 状态):△! 警告;info(FieldLabel):ⓘ 信息提示;calendar(DateInput):📅 日期选择器;clock(TimeInput):🕐 时间选择器;externalLink(Link):↗ 在新窗口中打开。',+ '颜色令牌映射——primary:--color-icon-primary(默认);secondary:--color-icon-secondary(弱化);tertiary:--color-icon-secondary(微妙/背景);disabled:--color-icon-disabled(禁用状态);accent:--color-accent(交互/可操作);positive:--color-success(成功/确认);negative:--color-error(错误/危险);warning:--color-warning(警告/注意);inherit:currentColor(继承父文本颜色)。',+ '尺寸规格——xsm:12x12px(密集 UI、徽章、指示器);sm:16x16px(与文本内联、紧凑 UI);md:20x20px(默认,按钮、输入框);lg:24x24px(强调、独立图标)。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjsindex 0b3a336fc3..0018c8ceab 100644--- a/packages/core/src/IconButton/IconButton.doc.mjs+++ b/packages/core/src/IconButton/IconButton.doc.mjs@@ -2,17 +2,7 @@export const docs = {name: 'IconButton',- description:- 'An icon-only button. Thin wrapper around XDSButton with isIconOnly always true.',-keywords: ['icon-button', 'icon', 'button', 'toolbar', 'action', 'compact'],- features: [- 'Composition wrapper — delegates all behavior to XDSButton with isIconOnly=true',- 'Explicit component name — greppable, codemod-safe, import-level detection',- 'Same variants, sizes, and states as XDSButton',- 'label prop becomes aria-label for accessibility',- 'icon prop is required (enforced by TypeScript)',- ],props: [{@@ -69,15 +59,24 @@ export const docs = {},],- notes: [- 'Prefer XDSIconButton over <XDSButton isIconOnly> for explicit intent',- 'The label prop is always used as aria-label — required for accessibility',- 'children and endContent are not accepted (omitted from props type)',- 'All other XDSButton props (variant, size, onClick, etc.) are forwarded',- ],-- accessibility: [- 'Uses aria-label from the label prop for screen reader accessibility',- 'Same keyboard and screen reader behavior as XDSButton with isIconOnly',- ],+ usage: {+ description:+ 'An icon-only button that wraps XDSButton with isIconOnly always true. Use when an action can be clearly represented by a single icon without visible text.',+ features: [+ 'Composition wrapper — delegates all behavior to XDSButton with isIconOnly=true',+ 'Same variants, sizes, and states as XDSButton',+ 'label prop becomes aria-label for accessibility',+ 'icon prop is required (enforced by TypeScript)',+ ],+ accessibility: [+ 'Uses aria-label from the label prop for screen reader accessibility.',+ 'Same keyboard and screen reader behavior as XDSButton with isIconOnly.',+ ],+ notes: [+ 'Prefer XDSIconButton over <XDSButton isIconOnly> for explicit intent.',+ 'Explicit component name — greppable, codemod-safe, import-level detection.',+ 'children and endContent are not accepted (omitted from props type).',+ 'All other XDSButton props (variant, size, onClick, etc.) are forwarded.',+ ],+ },};diff --git a/packages/core/src/Kbd/Kbd.doc.mjs b/packages/core/src/Kbd/Kbd.doc.mjsindex ccb411ab00..3c7d408e81 100644--- a/packages/core/src/Kbd/Kbd.doc.mjs+++ b/packages/core/src/Kbd/Kbd.doc.mjs@@ -2,15 +2,7 @@export const docs = {name: 'Kbd',- description:- 'Displays a keyboard shortcut as styled <kbd> elements. Use in tooltips, menus, and documentation to show key combinations.',keywords: ["kbd","keyboard","shortcut","hotkey","keybinding","keystroke","keycombo","modifier","accelerator"],- features: [- 'Key parsing — splits "mod+k" into individual styled <kbd> elements',- 'Modifier symbols — maps mod/ctrl/alt/shift/enter/backspace/escape/arrows to platform symbols',- 'Inline display — renders as inline-flex for use inside text, tooltips, and menus',- 'Accessible — aria-hidden="true" since shortcuts are supplementary to visible labels',- ],props: [{name: 'keys',@@ -41,35 +33,30 @@ export const docs = {theming: {targets: [{className: 'xds-kbd'}],},- accessibility: [- 'Renders with aria-hidden="true" — keyboard shortcuts are visual hints, not primary content',- 'Uses semantic <kbd> elements for each key',- ],- keyboard: 'Not interactive — purely presentational',- notes: [- 'Fixed 20px height with min-width 20px per key badge',- 'Uses --color-background-body background and --color-text-secondary text color',- 'Key display symbols follow macOS conventions (⌘, ⌥, ⇧, ⌃)',- ],usage: {- summary: 'Displays a keyboard shortcut as styled key elements.',- content: `## When to use--- Showing keyboard shortcuts in tooltips, menus, and documentation.`,+ description:+ 'Displays a keyboard shortcut as styled <kbd> elements. Use in tooltips, menus, and documentation to show key combinations.',+ features: [+ 'Key parsing — splits "mod+k" into individual styled <kbd> elements',+ 'Modifier symbols — maps mod/ctrl/alt/shift/enter/backspace/escape/arrows to platform symbols',+ 'Inline display — renders as inline-flex for use inside text, tooltips, and menus',+ ],+ accessibility: [+ 'Renders with aria-hidden="true" — keyboard shortcuts are visual hints, not primary content.',+ 'Uses semantic <kbd> elements for each key.',+ 'Keyboard: Not interactive — purely presentational.',+ ],+ notes: [+ 'Fixed 20px height with min-width 20px per key badge.',+ 'Uses --color-background-body background and --color-text-secondary text color.',+ 'Key display symbols follow macOS conventions (⌘, ⌥, ⇧, ⌃).',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Kbd',- description:- '将键盘快捷键显示为样式化的 <kbd> 元素。适用于工具提示、菜单和文档中展示按键组合。',- features: [- '按键解析 — 将 "mod+k" 拆分为独立的样式化 <kbd> 元素',- '修饰符符号 — 将 mod/ctrl/alt/shift/enter/backspace/escape/箭头键映射为平台符号',- '内联显示 — 以 inline-flex 方式渲染,适用于文本、工具提示和菜单中',- '无障碍 — 使用 aria-hidden="true",因为快捷键是可见标签的补充信息',- ],props: [{name: 'keys',@@ -100,16 +87,26 @@ export const docsZh = {theming: {targets: [{className: 'xds-kbd'}],},- accessibility: [- '使用 aria-hidden="true" 渲染 — 键盘快捷键是视觉提示,不是主要内容',- '每个按键使用语义化的 <kbd> 元素',- ],- keyboard: '非交互式 — 纯展示用途',- notes: [- '固定 20px 高度,每个按键徽章最小宽度 20px',- '使用 --color-background-body 背景色和 --color-text-secondary 文字颜色',- '按键显示符号遵循 macOS 惯例(⌘、⌥、⇧、⌃)',- ],+ usage: {+ description:+ '将键盘快捷键显示为样式化的 <kbd> 元素。适用于工具提示、菜单和文档中展示按键组合。',+ features: [+ '按键解析 — 将 "mod+k" 拆分为独立的样式化 <kbd> 元素',+ '修饰符符号 — 将 mod/ctrl/alt/shift/enter/backspace/escape/箭头键映射为平台符号',+ '内联显示 — 以 inline-flex 方式渲染,适用于文本、工具提示和菜单中',+ '无障碍 — 使用 aria-hidden="true",因为快捷键是可见标签的补充信息',+ ],+ accessibility: [+ '使用 aria-hidden="true" 渲染 — 键盘快捷键是视觉提示,不是主要内容',+ '每个按键使用语义化的 <kbd> 元素',+ 'Keyboard: 非交互式 — 纯展示用途',+ ],+ notes: [+ '固定 20px 高度,每个按键徽章最小宽度 20px',+ '使用 --color-background-body 背景色和 --color-text-secondary 文字颜色',+ '按键显示符号遵循 macOS 惯例(⌘、⌥、⇧、⌃)',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjsindex 0b9bf929a7..b86c781b7c 100644--- a/packages/core/src/Layer/Layer.doc.mjs+++ b/packages/core/src/Layer/Layer.doc.mjs@@ -2,28 +2,7 @@export const docs = {name: 'Layer',- description:- 'Core hook for overlay positioning using CSS Anchor Positioning and the Popover API — no React portals needed. Popover, HoverCard, and Tooltip build on this foundation and live in their own directories.',keywords: ["layer","overlay","popover","positioning","anchor","floating","dropdown","popper","popup","portal"],- features: [- 'CSS Anchor Positioning for automatic placement relative to trigger elements',- 'Popover API for top-layer rendering — no React portals needed',- 'Type-safe mode system: context mode (anchor positioning) and fixed mode (manual coordinates)',- 'TypeScript enforces correct render props per mode at compile time',- 'Graceful degradation in Firefox: Popover API works, anchor positioning degrades acceptably',- 'Full support in Chrome and Safari',- ],- notes: [- 'CSS Anchor Positioning is fully supported in Chrome and Safari. Firefox supports the Popover API but not anchor positioning — this is an acceptable degradation.',- 'useXDSLayer context mode: pass a ref to the trigger element, then call render(children, { placement?, alignment? }). Fixed mode: call show() to display, then render(children, { x, y }) with required coordinates.',- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',- 'For click-triggered popovers, use XDSPopover (in @xds/core/Popover). For hover overlays, use XDSHoverCard (in @xds/core/HoverCard). For tooltips, use XDSTooltip (in @xds/core/Tooltip).',- ],- accessibility: [- 'The Layer hook provides the positioning and visibility foundation. ARIA patterns are implemented by the higher-level components (XDSPopover, XDSHoverCard, XDSTooltip).',- ],- keyboard:- 'Escape closes any open layer.',components: [{name: 'useXDSLayer',@@ -56,34 +35,32 @@ export const docs = {], },],usage: {- summary: 'Core hook for overlay positioning using CSS Anchor Positioning and the Popover API.',+ description:+ 'Core hook for overlay positioning using CSS Anchor Positioning and the Popover API — no React portals needed. Popover, HoverCard, and Tooltip build on this foundation.',+ features: [+ 'CSS Anchor Positioning for automatic placement relative to trigger elements',+ 'Popover API for top-layer rendering — no React portals needed',+ 'Type-safe mode system: context mode (anchor positioning) and fixed mode (manual coordinates)',+ 'TypeScript enforces correct render props per mode at compile time',+ 'Graceful degradation in Firefox: Popover API works, anchor positioning degrades acceptably',+ 'Full support in Chrome and Safari',+ ],+ accessibility: [+ 'The Layer hook provides the positioning and visibility foundation. ARIA patterns are implemented by the higher-level components (XDSPopover, XDSHoverCard, XDSTooltip).',+ 'Keyboard: Escape closes any open layer.',+ ],+ notes: [+ 'CSS Anchor Positioning is fully supported in Chrome and Safari. Firefox supports the Popover API but not anchor positioning — this is an acceptable degradation.',+ 'useXDSLayer context mode: pass a ref to the trigger element, then call render(children, { placement?, alignment? }). Fixed mode: call show() to display, then render(children, { x, y }) with required coordinates.',+ 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',+ 'For click-triggered popovers, use XDSPopover (in @xds/core/Popover). For hover overlays, use XDSHoverCard (in @xds/core/HoverCard). For tooltips, use XDSTooltip (in @xds/core/Tooltip).',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Layer',- description:- '使用 CSS 锚点定位和 Popover API 实现覆盖层定位的核心 Hook,无需 React Portal。Popover、HoverCard 和 Tooltip 基于此构建,各自位于独立目录中。',- features: [- 'CSS 锚点定位:自动相对于触发元素进行放置',- 'Popover API 实现顶层渲染,无需 React Portal',- '类型安全的模式系统:上下文模式(锚点定位)和固定模式(手动坐标)',- 'TypeScript 在编译时为每种模式强制执行正确的渲染属性',- 'Firefox 中优雅降级:Popover API 可用,锚点定位可接受地降级',- '完全支持 Chrome 和 Safari',- ],- notes: [- 'CSS 锚点定位在 Chrome 和 Safari 中完全支持。Firefox 支持 Popover API 但不支持锚点定位,这是一种可接受的降级。',- 'useXDSLayer 上下文模式:将 ref 传递给触发元素,然后调用 render(children, { placement?, alignment? })。固定模式:调用 show() 显示,然后使用必需的坐标调用 render(children, { x, y })。',- 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',- '对于点击触发的弹出层,使用 XDSPopover(位于 @xds/core/Popover)。对于悬停覆盖层,使用 XDSHoverCard(位于 @xds/core/HoverCard)。对于工具提示,使用 XDSTooltip(位于 @xds/core/Tooltip)。',- ],- accessibility: [- 'Layer Hook 提供定位和可见性基础。ARIA 模式由更高级别的组件(XDSPopover、XDSHoverCard、XDSTooltip)实现。',- ],- keyboard:- 'Escape 键关闭任何打开的层。',components: [{name: 'useXDSLayer',@@ -116,6 +93,28 @@ export const docsZh = {],},],+ usage: {+ description:+ '使用 CSS 锚点定位和 Popover API 实现覆盖层定位的核心 Hook,无需 React Portal。Popover、HoverCard 和 Tooltip 基于此构建,各自位于独立目录中。',+ features: [+ 'CSS 锚点定位:自动相对于触发元素进行放置',+ 'Popover API 实现顶层渲染,无需 React Portal',+ '类型安全的模式系统:上下文模式(锚点定位)和固定模式(手动坐标)',+ 'TypeScript 在编译时为每种模式强制执行正确的渲染属性',+ 'Firefox 中优雅降级:Popover API 可用,锚点定位可接受地降级',+ '完全支持 Chrome 和 Safari',+ ],+ accessibility: [+ 'Layer Hook 提供定位和可见性基础。ARIA 模式由更高级别的组件(XDSPopover、XDSHoverCard、XDSTooltip)实现。',+ 'Keyboard: Escape 键关闭任何打开的层。',+ ],+ notes: [+ 'CSS 锚点定位在 Chrome 和 Safari 中完全支持。Firefox 支持 Popover API 但不支持锚点定位,这是一种可接受的降级。',+ 'useXDSLayer 上下文模式:将 ref 传递给触发元素,然后调用 render(children, { placement?, alignment? })。固定模式:调用 show() 显示,然后使用必需的坐标调用 render(children, { x, y })。',+ 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',+ '对于点击触发的弹出层,使用 XDSPopover(位于 @xds/core/Popover)。对于悬停覆盖层,使用 XDSHoverCard(位于 @xds/core/HoverCard)。对于工具提示,使用 XDSTooltip(位于 @xds/core/Tooltip)。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjsindex b69dffeb14..fce17635b6 100644--- a/packages/core/src/Layout/Layout.doc.mjs+++ b/packages/core/src/Layout/Layout.doc.mjs@@ -2,18 +2,7 @@export const docs = {name: 'Layout',- description:- 'Composable utilities and components for building structured layouts with a container/content separation pattern.',keywords: ["layout","container","content","flex","box","wrapper","scaffold","page","shell"],- features: [- 'Primitive + higher-order architecture — XDSLayoutContainer is a primitive; XDSCard, XDSSection are higher-order',- 'Directional padding via CSS variables — inner/outer, horizontal/vertical padding control',- 'Context-aware defaults — components detect their slot and self-adjust',- 'Automatic RTL support — uses CSS logical properties',- 'XDSLayout provides a page shell with header, sidebar(s), content, and footer slots',- 'XDSHStack and XDSVStack for simple stacking layouts',- 'XDSStackItem for fill/alignment control within stacks',- ],theming: {targets: [{className: 'xds-layout', visualProps: ['height']},@@ -23,12 +12,6 @@ export const docs = {{className: 'xds-layout-panel'},],},- notes: [- 'Use XDSLayout for page shells and app layouts — any UI with a header bar, sidebar navigation, scrollable content area, or action footer. Do not use for simple stacking (use XDSVStack/XDSHStack instead).',- 'XDSLayoutContainer sets CSS variables that child components read: --layout-padding-outer-x (outer horizontal padding), --layout-padding-outer-y (outer vertical padding), --layout-padding-inner-x (inner horizontal padding used by Header, Footer, Content, Panel), --layout-padding-inner-y (inner vertical padding used by Header, Footer, Content, Panel).',- 'Architecture layers from top to bottom: Higher-Order Components (XDSCard, XDSSection), Layout Structure (XDSLayout + XDSLayoutHeader/Footer/Content/Panel), Primitive (XDSLayoutContainer sets CSS variables), Layout Utilities (XDSHStack, XDSVStack, stack(), stackItem()).',- 'All layout utilities and components are exported from @xds/core/Layout.',- ],components: [{name: 'XDSLayout',@@ -228,24 +211,28 @@ export const docs = {},],usage: {- summary: 'Composable utilities for building structured layouts with container and content separation.',+ description:+ 'Composable utilities and components for building structured layouts with a container/content separation pattern. Use XDSLayout for page shells with header, sidebar(s), content, and footer slots — for simple stacking, use XDSHStack/XDSVStack instead.',+ features: [+ 'Primitive + higher-order architecture — XDSLayoutContainer is a primitive; XDSCard, XDSSection are higher-order',+ 'Directional padding via CSS variables — inner/outer, horizontal/vertical padding control',+ 'Context-aware defaults — components detect their slot and self-adjust',+ 'Automatic RTL support — uses CSS logical properties',+ 'XDSLayout provides a page shell with header, sidebar(s), content, and footer slots',+ 'XDSHStack and XDSVStack for simple stacking layouts',+ 'XDSStackItem for fill/alignment control within stacks',+ ],+ notes: [+ 'XDSLayoutContainer sets CSS variables that child components read: --layout-padding-outer-x (outer horizontal padding), --layout-padding-outer-y (outer vertical padding), --layout-padding-inner-x (inner horizontal padding used by Header, Footer, Content, Panel), --layout-padding-inner-y (inner vertical padding used by Header, Footer, Content, Panel).',+ 'Architecture layers from top to bottom: Higher-Order Components (XDSCard, XDSSection), Layout Structure (XDSLayout + XDSLayoutHeader/Footer/Content/Panel), Primitive (XDSLayoutContainer sets CSS variables), Layout Utilities (XDSHStack, XDSVStack, stack(), stackItem()).',+ 'All layout utilities and components are exported from @xds/core/Layout.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Layout',- description:- '用于构建结构化布局的可组合工具和组件,采用容器/内容分离模式。',- features: [- '基础 + 高阶架构:XDSLayoutContainer 是基础组件;XDSCard、XDSSection 是高阶组件',- '通过 CSS 变量实现方向性内边距控制:内/外、水平/垂直内边距',- '上下文感知默认值:组件检测其所在插槽并自动调整',- '自动 RTL 支持:使用 CSS 逻辑属性',- 'XDSLayout 提供带有页眉、侧边栏、内容和页脚插槽的页面外壳',- 'XDSHStack 和 XDSVStack 用于简单的堆叠布局',- 'XDSStackItem 用于堆叠中的填充/对齐控制',- ],theming: {targets: [{className: 'xds-layout', visualProps: ['height']},@@ -255,12 +242,6 @@ export const docsZh = {{className: 'xds-layout-panel'},],},- notes: [- '使用 XDSLayout 构建页面外壳和应用布局,适用于任何带有页眉栏、侧边栏导航、可滚动内容区域或操作页脚的 UI。不要用于简单堆叠(请改用 XDSVStack/XDSHStack)。',- 'XDSLayoutContainer 设置子组件读取的 CSS 变量:--layout-padding-outer-x(外部水平内边距)、--layout-padding-outer-y(外部垂直内边距)、--layout-padding-inner-x(Header、Footer、Content、Panel 使用的内部水平内边距)、--layout-padding-inner-y(Header、Footer、Content、Panel 使用的内部垂直内边距)。',- '从上到下的架构层级:高阶组件(XDSCard、XDSSection)、布局结构(XDSLayout + XDSLayoutHeader/Footer/Content/Panel)、基础层(XDSLayoutContainer 设置 CSS 变量)、布局工具(XDSHStack、XDSVStack、stack()、stackItem())。',- '所有布局工具和组件均从 @xds/core/Layout 导出。',- ],components: [{name: 'XDSLayout',@@ -460,6 +441,25 @@ export const docsZh = {props: [],},],+ usage: {+ description:+ '用于构建结构化布局的可组合工具和组件,采用容器/内容分离模式。',+ features: [+ '基础 + 高阶架构:XDSLayoutContainer 是基础组件;XDSCard、XDSSection 是高阶组件',+ '通过 CSS 变量实现方向性内边距控制:内/外、水平/垂直内边距',+ '上下文感知默认值:组件检测其所在插槽并自动调整',+ '自动 RTL 支持:使用 CSS 逻辑属性',+ 'XDSLayout 提供带有页眉、侧边栏、内容和页脚插槽的页面外壳',+ 'XDSHStack 和 XDSVStack 用于简单的堆叠布局',+ 'XDSStackItem 用于堆叠中的填充/对齐控制',+ ],+ notes: [+ '使用 XDSLayout 构建页面外壳和应用布局,适用于任何带有页眉栏、侧边栏导航、可滚动内容区域或操作页脚的 UI。不要用于简单堆叠(请改用 XDSVStack/XDSHStack)。',+ 'XDSLayoutContainer 设置子组件读取的 CSS 变量:--layout-padding-outer-x(外部水平内边距)、--layout-padding-outer-y(外部垂直内边距)、--layout-padding-inner-x(Header、Footer、Content、Panel 使用的内部水平内边距)、--layout-padding-inner-y(Header、Footer、Content、Panel 使用的内部垂直内边距)。',+ '从上到下的架构层级:高阶组件(XDSCard、XDSSection)、布局结构(XDSLayout + XDSLayoutHeader/Footer/Content/Panel)、基础层(XDSLayoutContainer 设置 CSS 变量)、布局工具(XDSHStack、XDSVStack、stack()、stackItem())。',+ '所有布局工具和组件均从 @xds/core/Layout 导出。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjsindex 34d3db41b4..f91d60d94b 100644--- a/packages/core/src/Link/Link.doc.mjs+++ b/packages/core/src/Link/Link.doc.mjs@@ -2,37 +2,12 @@export const docs = {name: 'Link',- description:- 'XDSLink component for styled anchor links with multiple variants and features, plus polymorphic link infrastructure for rendering custom link components (Next.js Link, React Router Link, etc.).',keywords: ["link","anchor","href","hyperlink","navigation","url","external","textlink"],- features: [- "Color control: Uses XDSText color prop ('active' default, 'secondary', 'inherit', etc.)",- 'External links: Opens in new tab with external link icon',- 'Tooltip support: Display tooltip text on hover',- 'Underline control: Always show underline or only on hover',- 'Inline support: Inherits parent font styles when used within text',- 'Standalone mode: Applies base font sizing for independent links',- 'Disabled state: Visual and interaction disabled',- 'Focus visible: Accessible focus outline',- 'Polymorphic link: Render as a custom component via `as` prop or XDSLinkProvider',- ],theming: {targets: [{className: 'xds-link', visualProps: ['color']},],},- notes: [- 'By default, links inherit font family, size, line-height, and weight from parent elements',- 'Use isStandalone prop when the link is not inline within other text content',- 'isExternalLink automatically sets target="_blank" and rel="noopener noreferrer" for security',- 'Disabled state uses aria-disabled and pointer-events: none for accessibility',- 'Tooltip wraps the link in XDSTooltip component when provided',- 'XDSLinkComponentType is React.ElementType, allowing both string tags ("a") and custom components',- 'XDSLinkContext is separated from XDSLinkProvider (mirrors ThemeContext/XDSTheme pattern) so consumers can import the context without the full provider',- 'XDSLinkProvider memoizes its context value to prevent unnecessary re-renders',- 'Polymorphic link resolution order: (1) per-component as prop (highest priority), (2) XDSLinkProvider context, (3) native <a> element (default)',- 'All XDS components that render links (XDSLink, XDSTopNavItem, XDSSideNavItem, XDSBreadcrumbItem, XDSTab) support rendering as a custom link component',- ],components: [{name: 'XDSLink',@@ -122,22 +97,31 @@ export const docs = {},],usage: {- summary: 'Clickable element that leads to a new destination or performs an action.',- content: `## When to use--- To embed actions inline on a page.-- To provide a path to more information.--## When NOT to use--- Don't use to trigger dropdown menus.-- Don't use icon-only links without a visible label.--## Best practices--- Do: Write descriptive link text and front-load key information.-- Do: Keep link text concise.-- Do: Include context about the destination for "Learn more" links.`,+ description:+ 'Styled anchor link with multiple variants, external link support, and polymorphic rendering for custom link components (Next.js Link, React Router Link). Use for inline text navigation or standalone actions — write descriptive, concise link text and avoid icon-only links without a visible label.',+ features: [+ "Color control: Uses XDSText color prop ('active' default, 'secondary', 'inherit', etc.)",+ 'External links: Opens in new tab with external link icon',+ 'Tooltip support: Display tooltip text on hover',+ 'Underline control: Always show underline or only on hover',+ 'Inline support: Inherits parent font styles when used within text',+ 'Standalone mode: Applies base font sizing for independent links',+ 'Disabled state: Visual and interaction disabled',+ 'Focus visible: Accessible focus outline',+ 'Polymorphic link: Render as a custom component via `as` prop or XDSLinkProvider',+ ],+ notes: [+ 'By default, links inherit font family, size, line-height, and weight from parent elements.',+ 'Use isStandalone prop when the link is not inline within other text content.',+ 'isExternalLink automatically sets target="_blank" and rel="noopener noreferrer" for security.',+ 'Disabled state uses aria-disabled and pointer-events: none for accessibility.',+ 'Tooltip wraps the link in XDSTooltip component when provided.',+ 'XDSLinkComponentType is React.ElementType, allowing both string tags ("a") and custom components.',+ 'XDSLinkContext is separated from XDSLinkProvider (mirrors ThemeContext/XDSTheme pattern) so consumers can import the context without the full provider.',+ 'XDSLinkProvider memoizes its context value to prevent unnecessary re-renders.',+ 'Polymorphic link resolution order: (1) per-component as prop (highest priority), (2) XDSLinkProvider context, (3) native <a> element (default).',+ 'All XDS components that render links (XDSLink, XDSTopNavItem, XDSSideNavItem, XDSBreadcrumbItem, XDSTab) support rendering as a custom link component.',+ ],anatomy: [{name: 'Label', required: true, description: 'The visible text of the link.'},{name: 'Right icon', required: false, description: 'Icon placed after the label to indicate an action affordance.'},@@ -149,36 +133,11 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Link',- description:- 'XDSLink 组件,用于创建带有多种变体和功能的样式化锚点链接,以及用于渲染自定义链接组件(Next.js Link、React Router Link 等)的多态链接基础设施。',- features: [- "颜色控制:使用 XDSText 的 color 属性(默认 'active'、'secondary'、'inherit' 等)",- '外部链接:在新标签页中打开,带有外部链接图标',- '工具提示支持:悬停时显示提示文本',- '下划线控制:始终显示下划线或仅在悬停时显示',- '内联支持:在文本中使用时继承父级字体样式',- '独立模式:为独立链接应用基础字体大小',- '禁用状态:视觉和交互均被禁用',- '焦点可见:无障碍焦点轮廓',- '多态链接:通过 `as` 属性或 XDSLinkProvider 渲染为自定义组件',- ],theming: {targets: [{className: 'xds-link', visualProps: ['color']},],},- notes: [- '默认情况下,链接从父元素继承字体族、大小、行高和字重',- '当链接不在其他文本内容中内联使用时,使用 isStandalone 属性',- 'isExternalLink 自动设置 target="_blank" 和 rel="noopener noreferrer" 以确保安全',- '禁用状态使用 aria-disabled 和 pointer-events: none 以确保无障碍性',- '提供 tooltip 时,链接会被包裹在 XDSTooltip 组件中',- 'XDSLinkComponentType 是 React.ElementType,允许字符串标签("a")和自定义组件',- 'XDSLinkContext 与 XDSLinkProvider 分离(与 ThemeContext/XDSTheme 模式一致),以便消费者可以在不引入完整 Provider 的情况下导入上下文',- 'XDSLinkProvider 对其上下文值进行缓存以防止不必要的重新渲染',- '多态链接解析顺序:(1)单组件 as 属性(最高优先级),(2)XDSLinkProvider 上下文,(3)原生 <a> 元素(默认)',- '所有渲染链接的 XDS 组件(XDSLink、XDSTopNavItem、XDSSideNavItem、XDSBreadcrumbItem、XDSTab)都支持渲染为自定义链接组件',- ],components: [{name: 'XDSLink',@@ -268,6 +227,33 @@ export const docsZh = {],},],+ usage: {+ description:+ 'XDSLink 组件,用于创建带有多种变体和功能的样式化锚点链接,以及用于渲染自定义链接组件(Next.js Link、React Router Link 等)的多态链接基础设施。',+ features: [+ "颜色控制:使用 XDSText 的 color 属性(默认 'active'、'secondary'、'inherit' 等)",+ '外部链接:在新标签页中打开,带有外部链接图标',+ '工具提示支持:悬停时显示提示文本',+ '下划线控制:始终显示下划线或仅在悬停时显示',+ '内联支持:在文本中使用时继承父级字体样式',+ '独立模式:为独立链接应用基础字体大小',+ '禁用状态:视觉和交互均被禁用',+ '焦点可见:无障碍焦点轮廓',+ '多态链接:通过 `as` 属性或 XDSLinkProvider 渲染为自定义组件',+ ],+ notes: [+ '默认情况下,链接从父元素继承字体族、大小、行高和字重',+ '当链接不在其他文本内容中内联使用时,使用 isStandalone 属性',+ 'isExternalLink 自动设置 target="_blank" 和 rel="noopener noreferrer" 以确保安全',+ '禁用状态使用 aria-disabled 和 pointer-events: none 以确保无障碍性',+ '提供 tooltip 时,链接会被包裹在 XDSTooltip 组件中',+ 'XDSLinkComponentType 是 React.ElementType,允许字符串标签("a")和自定义组件',+ 'XDSLinkContext 与 XDSLinkProvider 分离(与 ThemeContext/XDSTheme 模式一致),以便消费者可以在不引入完整 Provider 的情况下导入上下文',+ 'XDSLinkProvider 对其上下文值进行缓存以防止不必要的重新渲染',+ '多态链接解析顺序:(1)单组件 as 属性(最高优先级),(2)XDSLinkProvider 上下文,(3)原生 <a> 元素(默认)',+ '所有渲染链接的 XDS 组件(XDSLink、XDSTopNavItem、XDSSideNavItem、XDSBreadcrumbItem、XDSTab)都支持渲染为自定义链接组件',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjsindex d8ef244c20..1843b103b5 100644--- a/packages/core/src/List/List.doc.mjs+++ b/packages/core/src/List/List.doc.mjs@@ -2,37 +2,13 @@export const docs = {name: 'List',- description:- 'Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model: XDSList wraps XDSListItem sub-components.',keywords: ["list","listitem","listbox","menu","collection","items","ul","navlist"],- features: [- 'Composition model — XDSList wraps XDSListItem sub-components',- 'Density variants: compact, balanced, spacious',- 'Optional dividers between items',- 'Optional header associated via aria-labelledby',- 'List marker styles: none, disc, decimal (renders <ol>), circle',- 'Interactive items via invisible button or anchor pattern',- 'Start and end content slots (icon, avatar, badge, chevron)',- ],- accessibility: [- 'Semantic <ul> / <ol> with <li> elements',- 'role="list" added when listStyle=\'none\' (Safari fix for list semantics removed by CSS list-style:none)',- 'aria-labelledby links the header element to the list',- 'aria-selected on selected items',- 'aria-disabled on disabled items',- 'Dividers are aria-hidden="true"',- 'Interactive items are keyboard-focusable via Tab',- ],theming: {targets: [{className: 'xds-list', visualProps: ['density', 'listStyle']},{className: 'xds-list-item'},],},- notes: [- 'Invisible button pattern: when onClick is provided, an invisible <button> wraps the label + description for accessibility. The <li> is the visual container with hover/press styles. startContent and endContent are siblings to the button (not inside it). Container click fires onClick unless the click originated from an interactive child. :focus-within on the container shows the focus outline.',- 'When href is provided instead of onClick, the same invisible pattern uses an <a> element.',- ],components: [{name: 'XDSList',@@ -136,16 +112,30 @@ export const docs = {},],usage: {- summary: 'Organizes information or interactive elements.',- content: `## When to use--- To organize text, media, charts, or actions.-- To create subgroups of parallel information.-- When items need add, edit, delete, or expand operations.--## Best practices--- Do: Place lists within a container such as a card or dialog.`,+ description:+ 'Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model where XDSList wraps XDSListItem sub-components. Place lists within a container such as a card or dialog.',+ features: [+ 'Composition model — XDSList wraps XDSListItem sub-components',+ 'Density variants: compact, balanced, spacious',+ 'Optional dividers between items',+ 'Optional header associated via aria-labelledby',+ 'List marker styles: none, disc, decimal (renders <ol>), circle',+ 'Interactive items via invisible button or anchor pattern',+ 'Start and end content slots (icon, avatar, badge, chevron)',+ ],+ accessibility: [+ 'Semantic <ul> / <ol> with <li> elements.',+ 'role="list" added when listStyle=\'none\' (Safari fix for list semantics removed by CSS list-style:none).',+ 'aria-labelledby links the header element to the list.',+ 'aria-selected on selected items.',+ 'aria-disabled on disabled items.',+ 'Dividers are aria-hidden="true".',+ 'Interactive items are keyboard-focusable via Tab.',+ ],+ notes: [+ 'Invisible button pattern: when onClick is provided, an invisible <button> wraps the label + description for accessibility. The <li> is the visual container with hover/press styles. startContent and endContent are siblings to the button (not inside it). Container click fires onClick unless the click originated from an interactive child. :focus-within on the container shows the focus outline.',+ 'When href is provided instead of onClick, the same invisible pattern uses an <a> element.',+ ],anatomy: [{name: 'List title', required: true, description: 'Heading that labels the list.'},{name: 'Description', required: false, description: 'Supplementary text below the title.'},@@ -157,36 +147,12 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'List',- description:- '用于渲染项目集合的垂直列表组件,提供一致的间距、分割线和标记样式。采用组合模式:XDSList 包裹 XDSListItem 子组件。',- features: [- '组合模式 — XDSList 包裹 XDSListItem 子组件',- '密度变体:紧凑、均衡、宽松',- '可选的项目间分割线',- '可选的标题,通过 aria-labelledby 关联',- '列表标记样式:无、实心圆点、数字(渲染 <ol>)、空心圆',- '通过隐形按钮或锚点模式实现可交互项目',- '起始和结束内容插槽(图标、头像、徽章、箭头)',- ],- accessibility: [- '语义化 <ul> / <ol> 配合 <li> 元素',- '当 listStyle=\'none\' 时添加 role="list"(Safari 修复:CSS list-style:none 会移除列表语义)',- 'aria-labelledby 将标题元素与列表关联',- '选中项目上设置 aria-selected',- '禁用项目上设置 aria-disabled',- '分割线设置 aria-hidden="true"',- '可交互项目通过 Tab 键可获取焦点',- ],theming: {targets: [{className: 'xds-list', visualProps: ['density', 'listStyle']},{className: 'xds-list-item'},],},- notes: [- '隐形按钮模式:当提供 onClick 时,一个不可见的 <button> 包裹标签和描述以确保无障碍访问。<li> 作为带有悬停/按下样式的视觉容器。startContent 和 endContent 是按钮的兄弟元素(不在按钮内部)。容器点击触发 onClick,除非点击来源于可交互子元素。容器上的 :focus-within 显示焦点轮廓。',- '当提供 href 而非 onClick 时,相同的隐形模式使用 <a> 元素。',- ],components: [{name: 'XDSList',@@ -290,6 +256,32 @@ export const docsZh = {],},],+ usage: {+ description:+ '用于渲染项目集合的垂直列表组件,提供一致的间距、分割线和标记样式。采用组合模式:XDSList 包裹 XDSListItem 子组件。',+ features: [+ '组合模式 — XDSList 包裹 XDSListItem 子组件',+ '密度变体:紧凑、均衡、宽松',+ '可选的项目间分割线',+ '可选的标题,通过 aria-labelledby 关联',+ '列表标记样式:无、实心圆点、数字(渲染 <ol>)、空心圆',+ '通过隐形按钮或锚点模式实现可交互项目',+ '起始和结束内容插槽(图标、头像、徽章、箭头)',+ ],+ accessibility: [+ '语义化 <ul> / <ol> 配合 <li> 元素',+ '当 listStyle=\'none\' 时添加 role="list"(Safari 修复:CSS list-style:none 会移除列表语义)',+ 'aria-labelledby 将标题元素与列表关联',+ '选中项目上设置 aria-selected',+ '禁用项目上设置 aria-disabled',+ '分割线设置 aria-hidden="true"',+ '可交互项目通过 Tab 键可获取焦点',+ ],+ notes: [+ '隐形按钮模式:当提供 onClick 时,一个不可见的 <button> 包裹标签和描述以确保无障碍访问。<li> 作为带有悬停/按下样式的视觉容器。startContent 和 endContent 是按钮的兄弟元素(不在按钮内部)。容器点击触发 onClick,除非点击来源于可交互子元素。容器上的 :focus-within 显示焦点轮廓。',+ '当提供 href 而非 onClick 时,相同的隐形模式使用 <a> 元素。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjsindex f1af9572f2..c1552ebcc5 100644--- a/packages/core/src/Markdown/Markdown.doc.mjs+++ b/packages/core/src/Markdown/Markdown.doc.mjs@@ -2,8 +2,6 @@export const docs = {name: 'Markdown',- description:- 'Renders a markdown string as XDS components. Supports headings, paragraphs, bold, italic, code, lists, tables, links, images, blockquotes, horizontal rules, and task lists. Handles streaming text with a smooth fade-in animation.',keywords: ['markdown','rich text',@@ -15,18 +13,6 @@ export const docs = {'md','markdown renderer',],- features: [- 'Zero dependencies — built-in markdown parser, no external library',- 'Streaming mode — smooth fade-in animation for chunk-by-chunk text delivery',- 'XDS integration — uses XDSList, XDSCodeBlock, XDSCode, and XDSCheckboxList for semantic output',- 'Heading level shift — headingLevelStart maps # to any h1-h6 level for page hierarchy',- 'Link interception — onLinkClick handler can intercept or prevent link navigation',- "Density — default and compact spacing modes",- "Task lists — GitHub Flavored Markdown checkboxes rendered via XDSCheckboxList in isReadOnly mode",- 'Tables — rendered as accessible HTML tables with XDS typography',- 'Citation chips — sources prop renders [id] and 【id】 markers as linked chips with label or number style',- 'Content width — contentWidth constrains prose to a readable width while tables and code blocks expand to the full container',- ],props: [{name: 'children',@@ -115,34 +101,33 @@ export const docs = {{className: 'xds-markdown', visualProps: ['density']},],},- accessibility: [- 'Root element uses role="document" to establish a document landmark for screen readers.',- 'Lists are rendered as semantic <ul>/<ol> elements.',- 'Tables include proper <thead>/<tbody> with alignment attributes.',- 'Task list checkboxes are rendered via XDSCheckboxList with isReadOnly.',- 'Code blocks use XDSCodeBlock with appropriate ARIA attributes.',- ],usage: {- summary: 'Renders a markdown string as XDS-styled components.',+ description:+ 'Renders a markdown string as XDS-styled components, supporting headings, paragraphs, bold, italic, code, lists, tables, links, images, blockquotes, horizontal rules, and task lists. Handles streaming text delivery with a smooth fade-in animation.',+ features: [+ 'Zero dependencies — built-in markdown parser, no external library',+ 'Streaming mode — smooth fade-in animation for chunk-by-chunk text delivery',+ 'XDS integration — uses XDSList, XDSCodeBlock, XDSCode, and XDSCheckboxList for semantic output',+ 'Heading level shift — headingLevelStart maps # to any h1-h6 level for page hierarchy',+ 'Link interception — onLinkClick handler can intercept or prevent link navigation',+ 'Density — default and compact spacing modes',+ 'Task lists — GitHub Flavored Markdown checkboxes rendered via XDSCheckboxList in isReadOnly mode',+ 'Tables — rendered as accessible HTML tables with XDS typography',+ 'Citation chips — sources prop renders [id] and 【id】 markers as linked chips with label or number style',+ 'Content width — contentWidth constrains prose to a readable width while tables and code blocks expand to the full container',+ ],+ accessibility: [+ 'Root element uses role="document" to establish a document landmark for screen readers.',+ 'Lists are rendered as semantic <ul>/<ol> elements.',+ 'Tables include proper <thead>/<tbody> with alignment attributes.',+ 'Task list checkboxes are rendered via XDSCheckboxList with isReadOnly.',+ 'Code blocks use XDSCodeBlock with appropriate ARIA attributes.',+ ],},};export const docsZh = {name: 'Markdown',- description:- '将 Markdown 字符串渲染为 XDS 组件。支持标题、段落、粗体、斜体、代码、列表、表格、链接、图片、引用块、水平线和任务列表。支持流式文本的逐字符淡入动画。',- features: [- '零依赖 — 内置 Markdown 解析器,无需外部库',- '流式模式 — 逐块文本渲染时平滑淡入动画',- 'XDS 集成 — 使用 XDSList、XDSCodeBlock、XDSCode 和 XDSCheckboxList 输出语义内容',- '标题级别偏移 — headingLevelStart 将 # 映射到任意 h1-h6 级别',- '链接拦截 — onLinkClick 可拦截或阻止链接导航',- '密度 — 默认和紧凑间距模式',- '任务列表 — GitHub 风格 Markdown 复选框通过 XDSCheckboxList 以只读模式渲染',- '表格 — 渲染为带 XDS 排版的语义 HTML 表格',- '引用标签 — sources 属性将 [id] 和 【id】 标记渲染为带链接的标签或编号徽章',- '内容宽度 — contentWidth 将正文限制在可读宽度内,表格和代码块扩展到完整容器宽度',- ],props: [{name: 'children',@@ -228,13 +213,29 @@ export const docsZh = {{className: 'xds-markdown', visualProps: ['density']},],},- accessibility: [- '根元素使用 role="document" 为屏幕阅读器建立文档地标。',- '列表渲染为语义化 <ul>/<ol> 元素。',- '表格包含带对齐属性的 <thead>/<tbody>。',- '任务列表复选框通过 XDSCheckboxList 以 isReadOnly 模式渲染。',- '代码块使用 XDSCodeBlock 并附带适当的 ARIA 属性。',- ],+ usage: {+ description:+ '将 Markdown 字符串渲染为 XDS 组件。支持标题、段落、粗体、斜体、代码、列表、表格、链接、图片、引用块、水平线和任务列表。支持流式文本的逐字符淡入动画。',+ features: [+ '零依赖 — 内置 Markdown 解析器,无需外部库',+ '流式模式 — 逐块文本渲染时平滑淡入动画',+ 'XDS 集成 — 使用 XDSList、XDSCodeBlock、XDSCode 和 XDSCheckboxList 输出语义内容',+ '标题级别偏移 — headingLevelStart 将 # 映射到任意 h1-h6 级别',+ '链接拦截 — onLinkClick 可拦截或阻止链接导航',+ '密度 — 默认和紧凑间距模式',+ '任务列表 — GitHub 风格 Markdown 复选框通过 XDSCheckboxList 以只读模式渲染',+ '表格 — 渲染为带 XDS 排版的语义 HTML 表格',+ '引用标签 — sources 属性将 [id] 和 【id】 标记渲染为带链接的标签或编号徽章',+ '内容宽度 — contentWidth 将正文限制在可读宽度内,表格和代码块扩展到完整容器宽度',+ ],+ accessibility: [+ '根元素使用 role="document" 为屏幕阅读器建立文档地标。',+ '列表渲染为语义化 <ul>/<ol> 元素。',+ '表格包含带对齐属性的 <thead>/<tbody>。',+ '任务列表复选框通过 XDSCheckboxList 以 isReadOnly 模式渲染。',+ '代码块使用 XDSCodeBlock 并附带适当的 ARIA 属性。',+ ],+ },};export const docsDense = {diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjsindex e8f3cd8929..256613ffbe 100644--- a/packages/core/src/MetadataList/MetadataList.doc.mjs+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs@@ -2,23 +2,7 @@export const docs = {name: 'MetadataList',- description:- 'A read-only labeled list for displaying key-value metadata. Semantic equivalent of HTML <dl>/<dt>/<dd> with layout control, column modes, and consistent styling. Uses a composition model: XDSMetadataList wraps XDSMetadataListItem sub-components.', keywords: ["metadata","description","definition","keyvalue","properties","details","attributes","summary"],- features: [- 'Composition model — XDSMetadataList wraps XDSMetadataListItem sub-components',- 'Column modes: single, multi (auto-fill), or fixed number',- 'Label positioning: start (side-by-side) or top (stacked)',- 'Horizontal orientation with flex-wrap',- 'Show more / show less toggle when items exceed maxNumOfItems',- 'Optional title heading above the list',- 'Optional icon before label text',- 'Semantic <dl>/<dt>/<dd> HTML structure',- ],- accessibility: [- 'Semantic <dl> with <dt>/<dd> pairs',- 'aria-controls links the show more/less button to the list',- 'aria-expanded indicates whether the list is fully expanded',- ],+ keywords: ["metadata","description","definition","keyvalue","properties","details","attributes","summary"],theming: {targets: [{@@ -103,20 +87,23 @@ export const docs = {},],usage: {- summary: 'An editable list of key-value pairs providing a comprehensive overview of an object\'s attributes.',- content: `## When to use--- Display and edit key-value pairs for object attributes.-- Use edit mode for inline editing.-- Use disclosure to collapse/expand sections.--## When NOT to use--- For extensive form input, use forms instead.--## Best practices--- Default to collapsed state showing the top 6 items.`,+ description:+ 'A labeled list for displaying key-value metadata, providing a comprehensive overview of an object\'s attributes. Uses semantic HTML <dl>/<dt>/<dd> with layout control, column modes, and consistent styling via a composition model of XDSMetadataList and XDSMetadataListItem sub-components.',+ features: [+ 'Composition model — XDSMetadataList wraps XDSMetadataListItem sub-components',+ 'Column modes: single, multi (auto-fill), or fixed number',+ 'Label positioning: start (side-by-side) or top (stacked)',+ 'Horizontal orientation with flex-wrap',+ 'Show more / show less toggle when items exceed maxNumOfItems',+ 'Optional title heading above the list',+ 'Optional icon before label text',+ 'Semantic <dl>/<dt>/<dd> HTML structure',+ ],+ accessibility: [+ 'Semantic <dl> with <dt>/<dd> pairs',+ 'aria-controls links the show more/less button to the list',+ 'aria-expanded indicates whether the list is fully expanded',+ ],anatomy: [{name: 'Title', required: false, description: 'Optional title for the metadata list.'},{name: 'Label', required: true, description: 'The key label for each metadata entry.'},@@ -128,22 +115,6 @@ export const docs = {/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description: '以标签/值对显示组件元数据,支持列布局、折叠和方向变体。',- features: [- '组合模型——XDSMetadataList 包裹 XDSMetadataListItem 子组件',- '列模式:单列、多列(自动填充)或固定数量',- '标签位置:start(并排)或 top(堆叠)',- '水平方向,带 flex-wrap',- '当项目超出 maxNumOfItems 时显示更多/更少切换',- '可选标题插槽',- '标签文本前可选图标',- '语义化 HTML:带 <dt>/<dd> 对的 <dl>',- ],- accessibility: [- '语义化 <dl>,带 <dt>/<dd> 对',- 'aria-controls 将显示更多/更少按钮链接到列表',- 'aria-expanded 指示列表是否完全展开',- ],components: [{name: 'XDSMetadataList',@@ -168,6 +139,24 @@ export const docsZh = {},},],+ usage: {+ description: '以标签/值对显示组件元数据,支持列布局、折叠和方向变体。',+ features: [+ '组合模型——XDSMetadataList 包裹 XDSMetadataListItem 子组件',+ '列模式:单列、多列(自动填充)或固定数量',+ '标签位置:start(并排)或 top(堆叠)',+ '水平方向,带 flex-wrap',+ '当项目超出 maxNumOfItems 时显示更多/更少切换',+ '可选标题插槽',+ '标签文本前可选图标',+ '语义化 HTML:带 <dt>/<dd> 对的 <dl>',+ ],+ accessibility: [+ '语义化 <dl>,带 <dt>/<dd> 对',+ 'aria-controls 将显示更多/更少按钮链接到列表',+ 'aria-expanded 指示列表是否完全展开',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjsindex 82f6c5e3f3..8201015ba7 100644--- a/packages/core/src/MobileNav/MobileNav.doc.mjs+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs@@ -2,8 +2,6 @@export const docs = {name: 'MobileNav',- description:- 'Slide-out drawer overlay for mobile navigation. The mobile counterpart to XDSSideNav — accepts the same children (XDSSideNavSection, XDSSideNavItem, or any ReactNode).',keywords: ["mobilenav","drawer","sidebar","navigation","hamburger","menu","offcanvas","slideout","navdrawer"],props: [{@@ -46,40 +44,35 @@ export const docs = {default: "'start'",},],- features: [- 'Native <dialog> element with showModal() for top-layer rendering — no z-index stacking issues',- 'Animated slide-in from start or end edge with backdrop fade',- 'Shares children with XDSSideNav — extract nav sections into a variable and render in both',- 'RTL-aware: automatically mirrors slide direction for right-to-left layouts',- 'Respects prefers-reduced-motion: reduces animation duration',- ],- accessibility: [- 'Uses native <dialog> with showModal() for correct ARIA modal semantics.',- "aria-label set to title or 'Navigation' as fallback.",- 'Focus trapping provided by showModal() (browser-native).',- 'Escape key closes via native cancel event.',- 'Backdrop click closes the drawer.',- 'Body scroll locked while modal is open.',- ],- keyboard:- 'Escape closes the drawer; Tab/Shift+Tab cycles focus within the drawer (browser-native focus trapping)',theming: {targets: [{className: 'xds-mobile-nav', visualProps: ['side']},],},usage: {- summary: 'Slide-out drawer overlay for mobile navigation, the mobile counterpart to SideNav.',- content: `## When to use--- Providing navigation on mobile viewports where a persistent side nav is not practical.`,+ description:+ 'Slide-out drawer overlay for mobile navigation, the mobile counterpart to XDSSideNav. Accepts the same children (XDSSideNavSection, XDSSideNavItem, or any ReactNode), providing navigation on mobile viewports where a persistent side nav is not practical.',+ features: [+ 'Native <dialog> element with showModal() for top-layer rendering — no z-index stacking issues',+ 'Animated slide-in from start or end edge with backdrop fade',+ 'Shares children with XDSSideNav — extract nav sections into a variable and render in both',+ 'RTL-aware: automatically mirrors slide direction for right-to-left layouts',+ 'Respects prefers-reduced-motion: reduces animation duration',+ ],+ accessibility: [+ 'Uses native <dialog> with showModal() for correct ARIA modal semantics.',+ "aria-label set to title or 'Navigation' as fallback.",+ 'Focus trapping provided by showModal() (browser-native).',+ 'Escape key closes via native cancel event.',+ 'Backdrop click closes the drawer.',+ 'Body scroll locked while modal is open.',+ 'Keyboard: Escape closes the drawer; Tab/Shift+Tab cycles focus within the drawer (browser-native focus trapping).',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'MobileNav',- description:- '用于移动端导航的滑出式抽屉覆盖层。作为 XDSSideNav 的移动端对应组件,接受相同的子元素(XDSSideNavSection、XDSSideNavItem 或任何 ReactNode)。',props: [{name: 'isOpen',@@ -121,28 +114,31 @@ export const docsZh = {default: "'start'",},],- features: [- '原生 <dialog> 元素配合 showModal() 实现顶层渲染,无 z-index 层叠问题',- '从起始边缘或结束边缘滑入动画,配合背景遮罩淡入效果',- '与 XDSSideNav 共享子元素,将导航区块提取为变量即可在两者中渲染',- 'RTL 感知:自动镜像滑动方向以适配从右到左的布局',- '遵循 prefers-reduced-motion:减少动画持续时间',- ],- accessibility: [- '使用原生 <dialog> 配合 showModal() 以获得正确的 ARIA 模态语义。',- "aria-label 设置为标题,回退值为 'Navigation'。",- 'showModal() 提供焦点捕获(浏览器原生)。',- '通过原生 cancel 事件,按 Escape 键关闭。',- '点击背景遮罩关闭抽屉。',- '模态框打开时锁定页面滚动。',- ],- keyboard:- 'Escape 关闭抽屉;Tab/Shift+Tab 在抽屉内循环切换焦点(浏览器原生焦点捕获)',theming: {targets: [{className: 'xds-mobile-nav', visualProps: ['side']},],},+ usage: {+ description:+ '用于移动端导航的滑出式抽屉覆盖层。作为 XDSSideNav 的移动端对应组件,接受相同的子元素(XDSSideNavSection、XDSSideNavItem 或任何 ReactNode)。',+ features: [+ '原生 <dialog> 元素配合 showModal() 实现顶层渲染,无 z-index 层叠问题',+ '从起始边缘或结束边缘滑入动画,配合背景遮罩淡入效果',+ '与 XDSSideNav 共享子元素,将导航区块提取为变量即可在两者中渲染',+ 'RTL 感知:自动镜像滑动方向以适配从右到左的布局',+ '遵循 prefers-reduced-motion:减少动画持续时间',+ ],+ accessibility: [+ '使用原生 <dialog> 配合 showModal() 以获得正确的 ARIA 模态语义。',+ "aria-label 设置为标题,回退值为 'Navigation'。",+ 'showModal() 提供焦点捕获(浏览器原生)。',+ '通过原生 cancel 事件,按 Escape 键关闭。',+ '点击背景遮罩关闭抽屉。',+ '模态框打开时锁定页面滚动。',+ 'Keyboard: Escape 关闭抽屉;Tab/Shift+Tab 在抽屉内循环切换焦点(浏览器原生焦点捕获)',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjsindex 9590a2ba65..25cdf8f73b 100644--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs@@ -2,8 +2,7 @@export const docs = {name: 'MoreMenu',- description:- 'Overflow menu with a three-dot icon trigger. A convenience wrapper that composes an icon-only XDSButton with a dropdown menu, eliminating the boilerplate of wiring up state management, positioning, and accessibility attributes.', keywords: ["moremenu","overflow","kebab","dotmenu","threedot","ellipsis","dropdown","contextmenu","actionmenu"],+ keywords: ["moremenu","overflow","kebab","dotmenu","threedot","ellipsis","dropdown","contextmenu","actionmenu"],props: [{name: 'items',@@ -56,44 +55,37 @@ export const docs = {'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',},],- features: [- "Zero-config defaults: three-dot icon, 'More options' label, ghost variant — just pass items",- 'Data-driven items: same items prop as XDSDropdownMenu (items, dividers, sections)',- 'Icon-only trigger: always renders as a square icon button with aria-label',- 'Tooltip: shows label on hover, hidden when menu is open',- 'Custom rendering: optional children render function for custom item content',- ],theming: {targets: [{className: 'xds-more-menu'},],},- accessibility: [- 'Proper ARIA roles: menu and menuitem on dropdown elements.',- 'Trigger button has aria-haspopup="menu" and aria-expanded.',- 'aria-activedescendant tracks the highlighted menu item.',- 'Disabled items have aria-disabled set.',- 'Sections use role="group" with aria-label.',- ],- keyboard:- 'Arrow keys navigate items; Home/End jump to first/last; Enter/Space select highlighted item; Escape closes menu',- notes: [- 'For full control over trigger rendering or menu content, compose XDSButton + useXDSLayer + XDSDropdownMenuItem directly.',- 'Use XDSMoreMenu for icon-only overflow actions in tight spaces (table rows, card headers). Use XDSDropdownMenu for labeled trigger buttons with chevrons.',- ],usage: {- summary: 'Overflow menu with a three-dot icon trigger for secondary actions.',- content: `## When to use--- Presenting secondary or overflow actions in a compact space.-- Actions that don't warrant their own visible button.`,+ description:+ 'Overflow menu with a three-dot icon trigger for presenting secondary or overflow actions in a compact space. A convenience wrapper that composes an icon-only XDSButton with a dropdown menu, eliminating the boilerplate of wiring up state management, positioning, and accessibility attributes.',+ features: [+ "Zero-config defaults: three-dot icon, 'More options' label, ghost variant — just pass items",+ 'Data-driven items: same items prop as XDSDropdownMenu (items, dividers, sections)',+ 'Icon-only trigger: always renders as a square icon button with aria-label',+ 'Tooltip: shows label on hover, hidden when menu is open',+ 'Custom rendering: optional children render function for custom item content',+ ],+ accessibility: [+ 'Proper ARIA roles: menu and menuitem on dropdown elements.',+ 'Trigger button has aria-haspopup="menu" and aria-expanded.',+ 'aria-activedescendant tracks the highlighted menu item.',+ 'Disabled items have aria-disabled set.',+ 'Sections use role="group" with aria-label.',+ 'Keyboard: Arrow keys navigate items; Home/End jump to first/last; Enter/Space select highlighted item; Escape closes menu.',+ ],+ notes: [+ 'For full control over trigger rendering or menu content, compose XDSButton + useXDSLayer + XDSDropdownMenuItem directly.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'MoreMenu',- description:- '带有三点图标触发器的溢出菜单。一个便捷的包装组件,将仅图标的 XDSButton 与下拉菜单组合在一起,省去了手动连接状态管理、定位和无障碍属性的模板代码。',props: [{name: 'items',@@ -146,31 +138,34 @@ export const docsZh = {'用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,不能是内联样式对象如 style={{}}。',},],- features: [- "零配置默认值:三点图标、'More options' 标签、ghost 变体,只需传入 items",- '数据驱动的菜单项:与 XDSDropdownMenu 相同的 items 属性(项目、分割线、分组)',- '仅图标触发器:始终渲染为带 aria-label 的方形图标按钮',- '工具提示:悬停时显示标签,菜单打开时隐藏',- '自定义渲染:可选的 children 渲染函数用于自定义项目内容',- ],theming: {targets: [{className: 'xds-more-menu'},],},- accessibility: [- '正确的 ARIA 角色:下拉元素上设置 menu 和 menuitem。',- '触发按钮设置了 aria-haspopup="menu" 和 aria-expanded。',- 'aria-activedescendant 跟踪高亮的菜单项。',- '禁用项目设置了 aria-disabled。',- '分组使用 role="group" 配合 aria-label。',- ],- keyboard:- '方向键导航项目;Home/End 跳转到第一项/最后一项;Enter/Space 选择高亮项目;Escape 关闭菜单',- notes: [- '如需完全控制触发器渲染或菜单内容,请直接组合 XDSButton + useXDSLayer + XDSDropdownMenuItem。',- '在紧凑空间(表格行、卡片标题)中使用 XDSMoreMenu 作为仅图标的溢出操作。使用 XDSDropdownMenu 作为带标签和箭头的触发按钮。',- ],+ usage: {+ description:+ '带有三点图标触发器的溢出菜单。一个便捷的包装组件,将仅图标的 XDSButton 与下拉菜单组合在一起,省去了手动连接状态管理、定位和无障碍属性的模板代码。',+ features: [+ "零配置默认值:三点图标、'More options' 标签、ghost 变体,只需传入 items",+ '数据驱动的菜单项:与 XDSDropdownMenu 相同的 items 属性(项目、分割线、分组)',+ '仅图标触发器:始终渲染为带 aria-label 的方形图标按钮',+ '工具提示:悬停时显示标签,菜单打开时隐藏',+ '自定义渲染:可选的 children 渲染函数用于自定义项目内容',+ ],+ accessibility: [+ '正确的 ARIA 角色:下拉元素上设置 menu 和 menuitem。',+ '触发按钮设置了 aria-haspopup="menu" 和 aria-expanded。',+ 'aria-activedescendant 跟踪高亮的菜单项。',+ '禁用项目设置了 aria-disabled。',+ '分组使用 role="group" 配合 aria-label。',+ 'Keyboard: 方向键导航项目;Home/End 跳转到第一项/最后一项;Enter/Space 选择高亮项目;Escape 关闭菜单',+ ],+ notes: [+ '如需完全控制触发器渲染或菜单内容,请直接组合 XDSButton + useXDSLayer + XDSDropdownMenuItem。',+ '在紧凑空间(表格行、卡片标题)中使用 XDSMoreMenu 作为仅图标的溢出操作。使用 XDSDropdownMenu 作为带标签和箭头的触发按钮。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjsindex c235ae482c..3df11f35ae 100644--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs@@ -2,29 +2,7 @@export const docs = {name: 'MultiSelector',- description:- 'Multi-select dropdown with checkboxes for choosing multiple items from a list. For small, finite sets like column toggles or filter facets — not a replacement for XDSTokenizer.', keywords: ['multiselect', 'checkbox', 'dropdown', 'multi', 'picker', 'checklist', 'facet', 'filter', 'select'],- features: [- 'Checkbox-based multi-select — dropdown stays open on toggle',- 'Supports string items, object items with optional icon and disabled state, dividers, and labeled sections',- 'Optional select-all with indeterminate state',- 'Optional search filtering',- 'Three trigger display modes: count, labels, badges',- 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',- 'Size variants: sm, md, lg',- 'Full keyboard navigation with typeahead support',- 'Accessible — role="combobox" trigger, role="listbox" with aria-multiselectable, real checkbox inputs',- ],- keyboard:- '↑↓ navigate, Enter/Space toggle, Escape close, Home/End jump, A-Z typeahead (when search not shown).',- accessibility: [- 'Uses role="combobox" on the trigger button.',- 'Dropdown listbox uses aria-multiselectable="true".',- 'Each option uses role="option" with aria-selected.',- 'Real XDSCheckboxInput for each item — no fake checkboxes.',- 'Select-all checkbox rendered outside role="listbox".',- 'Search input uses role="searchbox" with aria-controls.',- ],+ keywords: ['multiselect', 'checkbox', 'dropdown', 'multi', 'picker', 'checklist', 'facet', 'filter', 'select'],theming: {targets: [{className: 'xds-multi-selector', visualProps: ['size', 'status']},@@ -162,37 +140,33 @@ export const docs = {], },],usage: {- summary: 'Multi-select dropdown with checkboxes for choosing multiple items from a list.',- content: `## When to use--- Users need to select multiple values from a dropdown list.-- For small, finite sets of options use CheckboxList instead.`,+ description:+ 'Multi-select dropdown with checkboxes for choosing multiple items from a list. Designed for small, finite sets like column toggles or filter facets — not a replacement for XDSTokenizer.',+ features: [+ 'Checkbox-based multi-select — dropdown stays open on toggle',+ 'Supports string items, object items with optional icon and disabled state, dividers, and labeled sections',+ 'Optional select-all with indeterminate state',+ 'Optional search filtering',+ 'Three trigger display modes: count, labels, badges',+ 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',+ 'Size variants: sm, md, lg',+ 'Full keyboard navigation with typeahead support',+ 'Accessible — role="combobox" trigger, role="listbox" with aria-multiselectable, real checkbox inputs',+ ],+ accessibility: [+ 'Uses role="combobox" on the trigger button.',+ 'Dropdown listbox uses aria-multiselectable="true".',+ 'Each option uses role="option" with aria-selected.',+ 'Real XDSCheckboxInput for each item — no fake checkboxes.',+ 'Select-all checkbox rendered outside role="listbox".',+ 'Search input uses role="searchbox" with aria-controls.',+ 'Keyboard: ↑↓ navigate; Enter/Space toggle; Escape close; Home/End jump; A-Z typeahead (when search not shown).',+ ],},};/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description: '带复选框的多选下拉框,用于从列表中选择多项。适用于列切换或筛选条件等小型有限集合,不适用于替代 XDSTokenizer。',- features: [- '基于复选框的多选——切换时下拉框保持打开',- '支持字符串项、带可选图标和禁用状态的对象项、分隔线和标签分组',- '可选全选,带不确定状态',- '可选搜索过滤',- '三种触发显示模式:计数、标签、徽章',- '集成 XDS 字段规范:label、description、isRequired、isOptional、isLabelHidden、status',- '尺寸变体:sm、md、lg',- '完整键盘导航,支持预输入',- '无障碍访问——role="combobox" 触发器,带 aria-multiselectable 的 role="listbox",真实复选框输入',- ],- keyboard: '↑↓ 导航,Enter/空格切换,Escape 关闭,Home/End 跳转,A-Z 预输入(不显示搜索时)。',- accessibility: [- '触发按钮使用 role="combobox"。',- '下拉列表框使用 aria-multiselectable="true"。',- '每个选项使用带 aria-selected 的 role="option"。',- '每项使用真实的 XDSCheckboxInput——无假复选框。',- '全选复选框渲染在 role="listbox" 之外。',- '搜索输入使用带 aria-controls 的 role="searchbox"。',- ],components: [{name: 'XDSMultiSelector',@@ -223,6 +197,29 @@ export const docsZh = {},},],+ usage: {+ description: '带复选框的多选下拉框,用于从列表中选择多项。适用于列切换或筛选条件等小型有限集合,不适用于替代 XDSTokenizer。',+ features: [+ '基于复选框的多选——切换时下拉框保持打开',+ '支持字符串项、带可选图标和禁用状态的对象项、分隔线和标签分组',+ '可选全选,带不确定状态',+ '可选搜索过滤',+ '三种触发显示模式:计数、标签、徽章',+ '集成 XDS 字段规范:label、description、isRequired、isOptional、isLabelHidden、status',+ '尺寸变体:sm、md、lg',+ '完整键盘导航,支持预输入',+ '无障碍访问——role="combobox" 触发器,带 aria-multiselectable 的 role="listbox",真实复选框输入',+ ],+ accessibility: [+ '触发按钮使用 role="combobox"。',+ '下拉列表框使用 aria-multiselectable="true"。',+ '每个选项使用带 aria-selected 的 role="option"。',+ '每项使用真实的 XDSCheckboxInput——无假复选框。',+ '全选复选框渲染在 role="listbox" 之外。',+ '搜索输入使用带 aria-controls 的 role="searchbox"。',+ 'Keyboard: ↑↓ 导航,Enter/空格切换,Escape 关闭,Home/End 跳转,A-Z 预输入(不显示搜索时)。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjsindex db6c4207b1..fdcaed6599 100644--- a/packages/core/src/NavIcon/NavIcon.doc.mjs+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs@@ -2,14 +2,7 @@export const docs = {name: 'NavIcon',- description:- 'Circular icon container with accent background for navigation headers.',keywords: ["navicon","iconbutton","toolbar icon","appbar icon","nav button"],- features: [- 'Shared — used in both XDSTopNavHeading and XDSPageNavHeader',- 'Accent background — uses --color-accent with --color-on-accent contrast',- 'Fixed size — renders at the medium (--size-element-md) design token size',- ],props: [{name: 'icon',@@ -25,20 +18,19 @@ export const docs = {],},usage: {- summary: 'Circular icon container with accent background for navigation headers.',+ description:+ 'Circular icon container with accent background for navigation headers.',+ features: [+ 'Shared — used in both XDSTopNavHeading and XDSPageNavHeader',+ 'Accent background — uses --color-accent with --color-on-accent contrast',+ 'Fixed size — renders at the medium (--size-element-md) design token size',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'NavIcon',- description:- '用于导航头部的带强调色背景的圆形图标容器。',- features: [- '共享 — 同时用于 XDSTopNavHeading 和 XDSPageNavHeader',- '强调色背景 — 使用 --color-accent 配合 --color-on-accent 对比色',- '固定尺寸 — 以中等尺寸 (--size-element-md) 设计令牌渲染',- ],props: [{name: 'icon',@@ -53,6 +45,15 @@ export const docsZh = {{className: 'xds-navicon'},],},+ usage: {+ description:+ '用于导航头部的带强调色背景的圆形图标容器。',+ features: [+ '共享 — 同时用于 XDSTopNavHeading 和 XDSPageNavHeader',+ '强调色背景 — 使用 --color-accent 配合 --color-on-accent 对比色',+ '固定尺寸 — 以中等尺寸 (--size-element-md) 设计令牌渲染',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjsindex d7b67a54b6..b443af40e0 100644--- a/packages/core/src/NumberInput/NumberInput.doc.mjs+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs@@ -2,25 +2,7 @@export const docs = {name: 'NumberInput',- description:- 'A number input component for collecting numeric user input with validation.', keywords: ["numberinput","numberfield","stepper","spinner","counter","increment","decrement","quantity","numberpicker"],- features: [- 'Label Support — required label for accessibility (can be visually hidden)',- 'Description — optional description text displayed between the label and input',- 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',- 'Label Tooltip — optional info icon with tooltip at end of label',- 'Label Icon — optional icon before the label text',- 'Accessible — label properly associated with input via htmlFor/id',- 'Styled with StyleX — uses XDS design tokens for consistent styling',- 'Size Variants — three sizes (sm, md, lg) for different contexts',- 'Status Handling — error, warning, and success states with messages',- 'Number Constraints — support for min, max, and step attributes',- 'Validated onChange — only calls onChange when the entered value passes validation',- 'Units Display — optional units suffix (e.g., "%" or "GB")',- 'Integer Mode — option to restrict to integers only',- 'Native Controls — uses type="number" for browser step controls',- 'Event Callbacks — onFocus, onBlur, and onEnter handlers',- ],+ keywords: ["numberinput","numberfield","stepper","spinner","counter","increment","decrement","quantity","numberpicker"],props: [{name: 'label',@@ -172,28 +154,37 @@ export const docs = {{className: 'xds-number-input', visualProps: ['size']},],},- accessibility: [- 'Label is always rendered and associated with the input via htmlFor/id using the useId hook.',- 'Use isLabelHidden to hide the label visually while keeping it accessible to screen readers via a CSS technique.',- 'Wraps XDSField for consistent label, description, and optional/required indicator handling.',- ],- notes: [- 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" is shown.',- 'Uses type="number" to enable native browser step controls (up/down arrows).',- 'Validated onChange: only calls onChange when the entered value is a valid number that passes min/max/integer constraints.',- 'Uses internal pending state to allow free-form typing while validating on commit.',- 'Units are displayed as a lighter grey suffix after the input value.',- ],usage: {- summary: 'Enables users to enter or edit numeric values with validation support.',- content: `## When to use--- Numeric input within forms.--## Best practices--- Size the input to reflect expected content length.-- Validation states: error (blocking), warning (non-blocking), success (confirmation).`,+ description:+ 'A number input component for collecting and editing numeric values with validation support. Use within forms with support for min/max/step constraints, units display, and error/warning/success validation states.',+ features: [+ 'Label Support — required label for accessibility (can be visually hidden)',+ 'Description — optional description text displayed between the label and input',+ 'Optional/Required Indicators — display "Optional" or "Required" text with bullet separator',+ 'Label Tooltip — optional info icon with tooltip at end of label',+ 'Label Icon — optional icon before the label text',+ 'Accessible — label properly associated with input via htmlFor/id',+ 'Size Variants — three sizes (sm, md, lg) for different contexts',+ 'Status Handling — error, warning, and success states with messages',+ 'Number Constraints — support for min, max, and step attributes',+ 'Validated onChange — only calls onChange when the entered value passes validation',+ 'Units Display — optional units suffix (e.g., "%" or "GB")',+ 'Integer Mode — option to restrict to integers only',+ 'Native Controls — uses type="number" for browser step controls',+ 'Event Callbacks — onFocus, onBlur, and onEnter handlers',+ ],+ accessibility: [+ 'Label is always rendered and associated with the input via htmlFor/id using the useId hook.',+ 'Use isLabelHidden to hide the label visually while keeping it accessible to screen readers via a CSS technique.',+ 'Wraps XDSField for consistent label, description, and optional/required indicator handling.',+ ],+ notes: [+ 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" is shown.',+ 'Uses type="number" to enable native browser step controls (up/down arrows).',+ 'Validated onChange: only calls onChange when the entered value is a valid number that passes min/max/integer constraints.',+ 'Uses internal pending state to allow free-form typing while validating on commit.',+ 'Units are displayed as a lighter grey suffix after the input value.',+ ],anatomy: [{name: 'Label', required: true, description: 'The label for the number input.'},{name: 'Description', required: false, description: 'Additional description text below the label.'},@@ -207,25 +198,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'NumberInput',- description:- '用于收集带验证的数字用户输入的数字输入组件。',- features: [- '标签支持 - 必需的标签用于无障碍访问(可视觉隐藏)',- '描述 - 可选的描述文本,显示在标签和输入框之间',- '可选/必填指示器 - 显示"Optional"或"Required"文本,带圆点分隔符',- '标签工具提示 - 可选的信息图标,在标签末尾显示工具提示',- '标签图标 - 可选的标签文本前图标',- '无障碍 - 通过 htmlFor/id 将标签与输入框正确关联',- '使用 StyleX 样式 - 使用 XDS 设计令牌实现一致的样式',- '尺寸变体 - 三种尺寸(sm、md、lg)适用于不同场景',- '状态处理 - 错误、警告和成功状态及消息',- '数值约束 - 支持 min、max 和 step 属性',- '验证性 onChange - 仅在输入值通过验证时调用 onChange',- '单位显示 - 可选的单位后缀(例如"%"或"GB")',- '整数模式 - 可选择仅限整数输入',- '原生控件 - 使用 type="number" 获取浏览器步进控件',- '事件回调 - onFocus、onBlur 和 onEnter 处理器',- ],props: [{name: 'label',@@ -376,18 +348,39 @@ export const docsZh = {{className: 'xds-number-input', visualProps: ['size']},],},- accessibility: [- '标签始终渲染,并通过 useId hook 使用 htmlFor/id 与输入框关联。',- '使用 isLabelHidden 视觉隐藏标签,同时通过 CSS 技术保持屏幕阅读器可访问。',- '包装 XDSField 以实现一致的标签、描述和可选/必填指示器处理。',- ],- notes: [- 'isOptional 和 isRequired 互斥;同时设置两者将显示"Optional"。',- '使用 type="number" 启用浏览器原生步进控件(上/下箭头)。',- '验证性 onChange:仅在输入值为通过 min/max/整数约束的有效数字时调用 onChange。',- '使用内部待定状态以允许自由输入,同时在提交时进行验证。',- '单位以浅灰色后缀显示在输入值之后。',- ],+ usage: {+ description:+ '用于收集带验证的数字用户输入的数字输入组件。',+ features: [+ '标签支持 - 必需的标签用于无障碍访问(可视觉隐藏)',+ '描述 - 可选的描述文本,显示在标签和输入框之间',+ '可选/必填指示器 - 显示"Optional"或"Required"文本,带圆点分隔符',+ '标签工具提示 - 可选的信息图标,在标签末尾显示工具提示',+ '标签图标 - 可选的标签文本前图标',+ '无障碍 - 通过 htmlFor/id 将标签与输入框正确关联',+ '使用 StyleX 样式 - 使用 XDS 设计令牌实现一致的样式',+ '尺寸变体 - 三种尺寸(sm、md、lg)适用于不同场景',+ '状态处理 - 错误、警告和成功状态及消息',+ '数值约束 - 支持 min、max 和 step 属性',+ '验证性 onChange - 仅在输入值通过验证时调用 onChange',+ '单位显示 - 可选的单位后缀(例如"%"或"GB")',+ '整数模式 - 可选择仅限整数输入',+ '原生控件 - 使用 type="number" 获取浏览器步进控件',+ '事件回调 - onFocus、onBlur 和 onEnter 处理器',+ ],+ accessibility: [+ '标签始终渲染,并通过 useId hook 使用 htmlFor/id 与输入框关联。',+ '使用 isLabelHidden 视觉隐藏标签,同时通过 CSS 技术保持屏幕阅读器可访问。',+ '包装 XDSField 以实现一致的标签、描述和可选/必填指示器处理。',+ ],+ notes: [+ 'isOptional 和 isRequired 互斥;同时设置两者将显示"Optional"。',+ '使用 type="number" 启用浏览器原生步进控件(上/下箭头)。',+ '验证性 onChange:仅在输入值为通过 min/max/整数约束的有效数字时调用 onChange。',+ '使用内部待定状态以允许自由输入,同时在提交时进行验证。',+ '单位以浅灰色后缀显示在输入值之后。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/OverflowList/OverflowList.doc.mjs b/packages/core/src/OverflowList/OverflowList.doc.mjsindex 39a0bce4ff..4a1c9a457e 100644--- a/packages/core/src/OverflowList/OverflowList.doc.mjs+++ b/packages/core/src/OverflowList/OverflowList.doc.mjs@@ -2,8 +2,7 @@export const docs = {name: 'OverflowList',- description:- 'Horizontal list that hides items that overflow the available width and shows a custom indicator. Uses a hidden measurement container to avoid layout flicker.', keywords: [+ keywords: ['overflow','truncate','collapse',@@ -15,14 +14,6 @@ export const docs = {'clamp','responsive',],- features: [- "Hides items that don't fit in the container width",- 'Custom overflow indicator via overflowRenderer — receives the list of hidden items',- 'Indicator space reserved via hidden measurement — no manual width needed',- 'Collapse from start or end',- 'Minimum visible items guarantee',- 'observeParent behavior for content-sized containers alongside siblings',- ],props: [{name: 'children',@@ -74,36 +65,34 @@ export const docs = {{className: 'xds-overflow-list'},],},- accessibility: [- 'The hidden measurement container is aria-hidden and inert — it does not appear in the accessibility tree.',- 'The visible container renders a plain div with no implicit role. Add aria-label if the list has semantic meaning.',- 'When using overflowRenderer with a dropdown, ensure the trigger has a meaningful label (e.g., "+3 more actions").',- ],- notes: [- 'Overflow detection uses ResizeObserver on the container or its parent, depending on the behavior prop.',- 'The overflowRenderer is rendered in a hidden measurement container at full item count to reserve the correct space before any items are hidden.',- 'Items are measured in the hidden container without visible paint — switching from hidden to visible is instant with no layout shift.',- "For collapseFrom='start', items are hidden from the beginning and the overflow indicator appears at the start.",- 'Use minVisibleItems to guarantee at least N items are always visible regardless of available space.',- ],usage: {- summary: 'Horizontal list that hides items exceeding the available width and shows an overflow indicator.',+ description:+ 'Horizontal list that hides items exceeding the available width and shows a custom overflow indicator. Uses a hidden measurement container to avoid layout flicker.',+ features: [+ "Hides items that don't fit in the container width",+ 'Custom overflow indicator via overflowRenderer — receives the list of hidden items',+ 'Indicator space reserved via hidden measurement — no manual width needed',+ 'Collapse from start or end',+ 'Minimum visible items guarantee',+ 'observeParent behavior for content-sized containers alongside siblings',+ ],+ accessibility: [+ 'The hidden measurement container is aria-hidden and inert — it does not appear in the accessibility tree.',+ 'The visible container renders a plain div with no implicit role. Add aria-label if the list has semantic meaning.',+ 'When using overflowRenderer with a dropdown, ensure the trigger has a meaningful label (e.g., "+3 more actions").',+ ],+ notes: [+ 'Overflow detection uses ResizeObserver on the container or its parent, depending on the behavior prop.',+ 'The overflowRenderer is rendered in a hidden measurement container at full item count to reserve the correct space before any items are hidden.',+ 'Items are measured in the hidden container without visible paint — switching from hidden to visible is instant with no layout shift.',+ "For collapseFrom='start', items are hidden from the beginning and the overflow indicator appears at the start.",+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'OverflowList',- description:- '横向列表,当宽度不足时隐藏超出的项目并显示自定义指示器。使用隐藏的测量容器避免布局抖动。',- features: [- '隐藏超出容器宽度的项目',- '通过 overflowRenderer 自定义溢出指示器 — 接收隐藏项目列表',- '通过隐藏测量预留指示器空间 — 无需手动指定宽度',- '从起始或末尾折叠',- '保证最小可见项目数',- '支持 observeParent 模式,用于与兄弟元素并排的内容尺寸容器',- ],props: [{name: 'children',@@ -150,18 +139,30 @@ export const docsZh = {'用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须使用 stylex.create() 的值,而非内联样式对象。',},],- accessibility: [- '隐藏的测量容器设置了 aria-hidden 和 inert — 不出现在无障碍树中。',- '可见容器渲染为普通 div,无隐式角色。如果列表有语义含义,请添加 aria-label。',- '使用下拉菜单作为 overflowRenderer 时,确保触发按钮有有意义的标签(如"+3 个更多操作")。',- ],- notes: [- '溢出检测使用 ResizeObserver 监听容器或其父元素,具体取决于 behavior 属性。',- 'overflowRenderer 在隐藏测量容器中以完整项目数渲染,以在隐藏任何项目前预留正确的空间。',- '项目在隐藏容器中测量,无可见渲染 — 从隐藏切换到可见是即时的,无布局偏移。',- "使用 collapseFrom='start' 时,项目从起始处隐藏,溢出指示器出现在起始位置。",- '使用 minVisibleItems 保证无论可用空间多少,始终显示至少 N 个项目。',- ],+ usage: {+ description:+ '横向列表,当宽度不足时隐藏超出的项目并显示自定义指示器。使用隐藏的测量容器避免布局抖动。',+ features: [+ '隐藏超出容器宽度的项目',+ '通过 overflowRenderer 自定义溢出指示器 — 接收隐藏项目列表',+ '通过隐藏测量预留指示器空间 — 无需手动指定宽度',+ '从起始或末尾折叠',+ '保证最小可见项目数',+ '支持 observeParent 模式,用于与兄弟元素并排的内容尺寸容器',+ ],+ accessibility: [+ '隐藏的测量容器设置了 aria-hidden 和 inert — 不出现在无障碍树中。',+ '可见容器渲染为普通 div,无隐式角色。如果列表有语义含义,请添加 aria-label。',+ '使用下拉菜单作为 overflowRenderer 时,确保触发按钮有有意义的标签(如"+3 个更多操作")。',+ ],+ notes: [+ '溢出检测使用 ResizeObserver 监听容器或其父元素,具体取决于 behavior 属性。',+ 'overflowRenderer 在隐藏测量容器中以完整项目数渲染,以在隐藏任何项目前预留正确的空间。',+ '项目在隐藏容器中测量,无可见渲染 — 从隐藏切换到可见是即时的,无布局偏移。',+ "使用 collapseFrom='start' 时,项目从起始处隐藏,溢出指示器出现在起始位置。",+ '使用 minVisibleItems 保证无论可用空间多少,始终显示至少 N 个项目。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjsindex f0246c03d1..6f0ef89948 100644--- a/packages/core/src/Pagination/Pagination.doc.mjs+++ b/packages/core/src/Pagination/Pagination.doc.mjs@@ -2,8 +2,7 @@export const docs = {name: 'Pagination',- description:- 'Standalone pagination controls for navigating through pages of content. Supports multiple display variants and works with known totals or cursor-based pagination.', keywords: ["pagination","pager","paginator","pagenavigation","paging","paginate","pages","pagecontrol"],+ keywords: ["pagination","pager","paginator","pagenavigation","paging","paginate","pages","pagecontrol"],props: [{name: 'page',@@ -98,49 +97,43 @@ export const docs = {'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',},],- features: [- "Five display variants: 'pages', 'count', 'compact', 'dots', 'none'",- 'Offset and cursor-based pagination: provide totalItems/totalPages for known totals, or hasMore for cursor-based',- 'Page size selector: shows a dropdown when pageSizeOptions is provided',- 'Ellipsis truncation for page numbers via generatePageRange utility',- 'React transitions: onChangeAction uses useTransition for built-in loading state',- "Sizes: 'sm' and 'md'",- ],- accessibility: [- 'Root is <nav> with configurable aria-label.',- 'Current page button has aria-current="page".',- 'Prev/next buttons have descriptive aria-label.',- 'Ellipsis elements are aria-hidden.',- 'All interactive elements are keyboard accessible.',- ],theming: {targets: [{className: 'xds-pagination', visualProps: ['size', 'variant']},{className: 'xds-pagination-dot', visualProps: ['size'], states: ['active']},],},- notes: [- "Page number buttons use XDSButton (variant='ghost' for inactive, variant='primary' for active) for theming and swizzle compatibility.",- "Prev/next buttons use XDSButton with variant='ghost' and icon-only mode.",- 'Dot indicators use xds-pagination-dot className with size and active state classes for theme targeting.',- 'Returns null when totalItems <= 0 or totalPages <= 0.',- 'Also exports generatePageRange utility for computing visible page numbers with ellipsis.',- ],usage: {- summary: 'Communicates the number of elements that can be loaded within a given context.',- content: `## When to use--- Showing current position within a paginated set.-- Accessing previous and next items.-- Selecting a specific page from a range.`,+ description:+ 'Standalone pagination controls for navigating through pages of content. Communicates the number of elements that can be loaded within a given context, supporting multiple display variants and working with known totals or cursor-based pagination.',+ features: [+ "Five display variants: 'pages', 'count', 'compact', 'dots', 'none'",+ 'Offset and cursor-based pagination: provide totalItems/totalPages for known totals, or hasMore for cursor-based',+ 'Page size selector: shows a dropdown when pageSizeOptions is provided',+ 'Ellipsis truncation for page numbers via generatePageRange utility',+ 'React transitions: onChangeAction uses useTransition for built-in loading state',+ "Sizes: 'sm' and 'md'",+ ],+ accessibility: [+ 'Root is <nav> with configurable aria-label.',+ 'Current page button has aria-current="page".',+ 'Prev/next buttons have descriptive aria-label.',+ 'Ellipsis elements are aria-hidden.',+ 'All interactive elements are keyboard accessible.',+ ],+ notes: [+ "Page number buttons use XDSButton (variant='ghost' for inactive, variant='primary' for active) for theming and swizzle compatibility.",+ "Prev/next buttons use XDSButton with variant='ghost' and icon-only mode.",+ 'Dot indicators use xds-pagination-dot className with size and active state classes for theme targeting.',+ 'Returns null when totalItems <= 0 or totalPages <= 0.',+ 'Also exports generatePageRange utility for computing visible page numbers with ellipsis.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Pagination',- description:- '用于在内容页面之间导航的独立分页控件。支持多种显示变体,适用于已知总数或基于游标的分页。',props: [{name: 'page',@@ -235,34 +228,38 @@ export const docsZh = {'用于布局自定义(外边距、定位、尺寸)的 StyleX 样式。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',},],- features: [- "五种显示变体:'pages'、'count'、'compact'、'dots'、'none'",- '偏移量和游标分页:提供 totalItems/totalPages 用于已知总数,或 hasMore 用于游标分页',- '每页大小选择器:提供 pageSizeOptions 时显示下拉菜单',- '通过 generatePageRange 工具函数实现页码省略号截断',- 'React transitions:onChangeAction 使用 useTransition 实现内置加载状态',- "尺寸:'sm' 和 'md'",- ],- accessibility: [- '根元素为 <nav>,带可配置的 aria-label。',- '当前页按钮具有 aria-current="page"。',- '上一页/下一页按钮具有描述性的 aria-label。',- '省略号元素为 aria-hidden。',- '所有交互元素均支持键盘访问。',- ],theming: {targets: [{className: 'xds-pagination', visualProps: ['size', 'variant']},{className: 'xds-pagination-dot', visualProps: ['size'], states: ['active']},],},- notes: [- "页码按钮使用 XDSButton(非活动状态 variant='ghost',活动状态 variant='primary')以兼容主题和 swizzle。",- "上一页/下一页按钮使用 XDSButton,variant='ghost' 且仅图标模式。",- '点指示器使用 xds-pagination-dot 类名,带有 size 和 active 状态类以支持主题定位。',- '当 totalItems <= 0 或 totalPages <= 0 时返回 null。',- '还导出 generatePageRange 工具函数,用于计算带省略号的可见页码。',- ],+ usage: {+ description:+ '用于在内容页面之间导航的独立分页控件。支持多种显示变体,适用于已知总数或基于游标的分页。',+ features: [+ "五种显示变体:'pages'、'count'、'compact'、'dots'、'none'",+ '偏移量和游标分页:提供 totalItems/totalPages 用于已知总数,或 hasMore 用于游标分页',+ '每页大小选择器:提供 pageSizeOptions 时显示下拉菜单',+ '通过 generatePageRange 工具函数实现页码省略号截断',+ 'React transitions:onChangeAction 使用 useTransition 实现内置加载状态',+ "尺寸:'sm' 和 'md'",+ ],+ accessibility: [+ '根元素为 <nav>,带可配置的 aria-label。',+ '当前页按钮具有 aria-current="page"。',+ '上一页/下一页按钮具有描述性的 aria-label。',+ '省略号元素为 aria-hidden。',+ '所有交互元素均支持键盘访问。',+ ],+ notes: [+ "页码按钮使用 XDSButton(非活动状态 variant='ghost',活动状态 variant='primary')以兼容主题和 swizzle。",+ "上一页/下一页按钮使用 XDSButton,variant='ghost' 且仅图标模式。",+ '点指示器使用 xds-pagination-dot 类名,带有 size 和 active 状态类以支持主题定位。',+ '当 totalItems <= 0 或 totalPages <= 0 时返回 null。',+ '还导出 generatePageRange 工具函数,用于计算带省略号的可见页码。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjsindex 99a80fc542..ff7a5236cb 100644--- a/packages/core/src/Popover/Popover.doc.mjs+++ b/packages/core/src/Popover/Popover.doc.mjs@@ -2,31 +2,7 @@export const docs = {name: 'Popover',- description:- 'A click-triggered popover for displaying interactive content anchored to a trigger element, implementing the button + dialog ARIA pattern.', keywords: ["popover","popup","dropdown","tooltip","overlay","flyout","callout","popper","anchor","floating","bubble"],- features: [- 'CSS Anchor Positioning for automatic placement relative to trigger elements',- 'Popover API for top-layer rendering — no React portals needed',- 'Controlled and uncontrolled modes',- 'Light dismiss support (click outside or Escape to close)',- 'Focus trap inside open popovers',- 'ARIA button + dialog pattern applied automatically to trigger elements',- 'Sibling mode via anchorRef for external trigger elements',- 'Stable anchor wrapper immune to pressed-state transforms',- ],- notes: [- 'XDSPopover locates the trigger button inside children by searching for <button> or [role="button"] — the child tree must contain one. It applies click/keydown handlers and aria-haspopup, aria-expanded, aria-controls automatically.',- 'XDSPopover uses an inline-flex anchor wrapper so that pressed-state transforms on the trigger (e.g. :active scale) do not shift the anchor position and cause popover jitter.',- 'In sibling mode (anchorRef prop), XDSPopover attaches to an external ref rather than wrapping children — useful when the trigger and overlay are not parent/child.',- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',- ],- accessibility: [- 'Implements the button + dialog ARIA pattern: aria-haspopup, aria-expanded, and aria-controls are set on the trigger button automatically.',- 'Traps focus inside the popover dialog while it is open.',- 'Supports keyboard activation for role="button" elements (Enter and Space) in addition to native <button> click synthesis.',- ],- keyboard:- 'Escape closes the popover. Enter/Space open the popover when the trigger has focus. Focus is trapped inside an open popover.',+ keywords: ["popover","popup","dropdown","tooltip","overlay","flyout","callout","popper","anchor","floating","bubble"],components: [{name: 'XDSPopover',@@ -164,26 +140,30 @@ export const docs = {],},usage: {- summary: 'A floating card toggled open on click for secondary actions or supplementary information.',- content: `## When to use--- Secondary menu options.-- Customizable settings panels.-- Filtering options.-- Supplementary information that does not warrant a full dialog.--## When NOT to use--- Static content display (use Card instead).-- Hover-triggered previews (use HoverCard instead).-- Brief helper text (use Tooltip instead).-- Complex flows requiring full focus (use Dialog instead).--## Best practices--- Do: Use a clear trigger element such as a button or link.-- Don't: Confuse with Tooltip \u2014 Popovers are click-triggered and contain richer content.-- Include a close button in the header for easy dismissal.`,+ description:+ 'A click-triggered popover for displaying interactive content anchored to a trigger element, implementing the button + dialog ARIA pattern. Use for secondary actions or supplementary information that does not warrant a full dialog — for hover-triggered previews use HoverCard, and for brief helper text use Tooltip.',+ features: [+ 'CSS Anchor Positioning for automatic placement relative to trigger elements',+ 'Popover API for top-layer rendering — no React portals needed',+ 'Controlled and uncontrolled modes',+ 'Light dismiss support (click outside or Escape to close)',+ 'Focus trap inside open popovers',+ 'ARIA button + dialog pattern applied automatically to trigger elements',+ 'Sibling mode via anchorRef for external trigger elements',+ 'Stable anchor wrapper immune to pressed-state transforms',+ ],+ accessibility: [+ 'Implements the button + dialog ARIA pattern: aria-haspopup, aria-expanded, and aria-controls are set on the trigger button automatically.',+ 'Traps focus inside the popover dialog while it is open.',+ 'Supports keyboard activation for role="button" elements (Enter and Space) in addition to native <button> click synthesis.',+ 'Keyboard: Escape closes the popover; Enter/Space open the popover when the trigger has focus; focus is trapped inside an open popover.',+ ],+ notes: [+ 'XDSPopover locates the trigger button inside children by searching for <button> or [role="button"] — the child tree must contain one. It applies click/keydown handlers and aria-haspopup, aria-expanded, aria-controls automatically.',+ 'XDSPopover uses an inline-flex anchor wrapper so that pressed-state transforms on the trigger (e.g. :active scale) do not shift the anchor position and cause popover jitter.',+ 'In sibling mode (anchorRef prop), XDSPopover attaches to an external ref rather than wrapping children — useful when the trigger and overlay are not parent/child.',+ 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',+ ],anatomy: [{name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},{name: 'Body', required: true, description: 'Main content area of the popover.'},@@ -195,31 +175,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Popover',- description:- '一个点击触发的弹出框,用于显示锚定到触发元素的交互式内容,实现了按钮 + 对话框的 ARIA 模式。',- features: [- '使用 CSS 锚点定位,相对于触发元素自动放置',- '使用 Popover API 进行顶层渲染——无需 React 传送门',- '受控和非受控模式',- '轻量关闭支持(点击外部或按 Escape 关闭)',- '在打开的弹出框内捕获焦点',- 'ARIA 按钮 + 对话框模式自动应用于触发元素',- '通过 anchorRef 实现兄弟模式,用于外部触发元素',- '稳定的锚点包装器,不受按压状态变换的影响',- ],- notes: [- 'XDSPopover 通过搜索 <button> 或 [role="button"] 来定位子元素中的触发按钮——子树中必须包含一个。它会自动应用 click/keydown 处理程序以及 aria-haspopup、aria-expanded、aria-controls 属性。',- 'XDSPopover 使用 inline-flex 锚点包装器,以确保触发器上的按压状态变换(如 :active scale)不会偏移锚点位置并导致弹出框抖动。',- '在兄弟模式下(anchorRef 属性),XDSPopover 附加到外部 ref 而不是包裹子元素——适用于触发器和浮层不是父子关系的情况。',- 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',- ],- accessibility: [- '实现了按钮 + 对话框的 ARIA 模式:aria-haspopup、aria-expanded 和 aria-controls 会自动设置在触发按钮上。',- '在弹出框对话框打开时,焦点被捕获在其内部。',- '支持 role="button" 元素的键盘激活(Enter 和 Space),以及原生 <button> 的点击合成。',- ],- keyboard:- 'Escape 关闭弹出框。当触发器获得焦点时,Enter/Space 打开弹出框。焦点被捕获在打开的弹出框内。',components: [{name: 'XDSPopover',@@ -352,6 +307,32 @@ export const docsZh = {{name: '--popover-radius', description: 'Border radius of the popover', default: 'var(--radius-element)'},],},+ usage: {+ description:+ '一个点击触发的弹出框,用于显示锚定到触发元素的交互式内容,实现了按钮 + 对话框的 ARIA 模式。',+ features: [+ '使用 CSS 锚点定位,相对于触发元素自动放置',+ '使用 Popover API 进行顶层渲染——无需 React 传送门',+ '受控和非受控模式',+ '轻量关闭支持(点击外部或按 Escape 关闭)',+ '在打开的弹出框内捕获焦点',+ 'ARIA 按钮 + 对话框模式自动应用于触发元素',+ '通过 anchorRef 实现兄弟模式,用于外部触发元素',+ '稳定的锚点包装器,不受按压状态变换的影响',+ ],+ accessibility: [+ '实现了按钮 + 对话框的 ARIA 模式:aria-haspopup、aria-expanded 和 aria-controls 会自动设置在触发按钮上。',+ '在弹出框对话框打开时,焦点被捕获在其内部。',+ '支持 role="button" 元素的键盘激活(Enter 和 Space),以及原生 <button> 的点击合成。',+ 'Keyboard: Escape 关闭弹出框。当触发器获得焦点时,Enter/Space 打开弹出框。焦点被捕获在打开的弹出框内。',+ ],+ notes: [+ 'XDSPopover 通过搜索 <button> 或 [role="button"] 来定位子元素中的触发按钮——子树中必须包含一个。它会自动应用 click/keydown 处理程序以及 aria-haspopup、aria-expanded、aria-controls 属性。',+ 'XDSPopover 使用 inline-flex 锚点包装器,以确保触发器上的按压状态变换(如 :active scale)不会偏移锚点位置并导致弹出框抖动。',+ '在兄弟模式下(anchorRef 属性),XDSPopover 附加到外部 ref 而不是包裹子元素——适用于触发器和浮层不是父子关系的情况。',+ 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjsindex 9b1c170496..f064ba986b 100644--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs@@ -2,8 +2,7 @@export const docs = {name: 'PowerSearch',- description:- 'Structured filter bar where each token represents a filter (field + operator + value). Users select fields from a typeahead dropdown, configure operators and values in an edit popover, and manage filters as removable tokens.', keywords: ["powersearch","search","searchbar","filter","filterbar","faceted","querybuilder","structured","omnibar"],+ keywords: ["powersearch","search","searchbar","filter","filterbar","faceted","querybuilder","structured","omnibar"],props: [{name: 'config',@@ -116,32 +115,24 @@ export const docs = {'StyleX styles for layout customization. Must be a stylex.create() value.',},],- features: [- 'Typeahead field selection with search and aliases',- 'Edit popover with field, operator, and value selectors',- 'Support for 13 value types: string, integer, float, enum, date, time, and more',- 'Token-based display with click-to-edit and remove',- 'Imperative API for focus/blur control via ref',- 'Read-only mode for displaying filters without editing',- ],- accessibility: [- 'Built on XDSTokenizer which provides combobox pattern with aria-expanded and aria-autocomplete.',- 'Filter tokens have accessible labels with field name, operator, and value.',- 'Edit popover uses XDSPopover with focus trapping and light dismiss.',- 'Clear all button has accessible label.',- ],- keyboard:- 'Type to search fields; Enter to select; Click token to edit; Backspace on empty input removes last filter; Escape closes popover',usage: {- summary: 'Structured filter bar where each token represents a filter with field, operator, and value.',- content: `## When to use--- Complex filtering across multiple dimensions.-- Users need to build and combine filter criteria.--## When NOT to use--- Simple single-field search (use a text input instead).`,+ description:+ 'Structured filter bar where each token represents a filter (field + operator + value). Users select fields from a typeahead dropdown, configure operators and values in an edit popover, and manage filters as removable tokens. Use for complex multi-dimensional filtering; for simple single-field search, use a text input instead.',+ features: [+ 'Typeahead field selection with search and aliases',+ 'Edit popover with field, operator, and value selectors',+ 'Support for 13 value types: string, integer, float, enum, date, time, and more',+ 'Token-based display with click-to-edit and remove',+ 'Imperative API for focus/blur control via ref',+ 'Read-only mode for displaying filters without editing',+ ],+ accessibility: [+ 'Built on XDSTokenizer which provides combobox pattern with aria-expanded and aria-autocomplete.',+ 'Filter tokens have accessible labels with field name, operator, and value.',+ 'Edit popover uses XDSPopover with focus trapping and light dismiss.',+ 'Clear all button has accessible label.',+ 'Keyboard: Type to search fields; Enter to select; Click token to edit; Backspace on empty input removes last filter; Escape closes popover.',+ ],},};@@ -154,8 +145,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'PowerSearch',- description:- '结构化过滤栏,每个令牌代表一个过滤器(字段 + 运算符 + 值)。用户从预输入下拉菜单中选择字段,在编辑弹出窗口中配置运算符和值,并将过滤器作为可移除的令牌进行管理。',props: [{name: 'config',@@ -262,22 +251,25 @@ export const docsZh = {description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。',},],- features: [- '预输入字段选择,支持搜索和别名',- '编辑弹出窗口,包含字段、运算符和值选择器',- '支持 13 种值类型:字符串、整数、浮点数、枚举、日期、时间等',- '令牌式显示,支持点击编辑和移除',- '通过 ref 提供命令式 API 控制聚焦/失焦',- '只读模式,显示过滤器但不允许编辑',- ],- accessibility: [- '基于 XDSTokenizer 构建,提供 combobox 模式,包含 aria-expanded 和 aria-autocomplete。',- '过滤器令牌具有包含字段名、运算符和值的无障碍标签。',- '编辑弹出窗口使用 XDSPopover,支持焦点捕获和轻量关闭。',- '清除全部按钮具有无障碍标签。',- ],- keyboard:- '输入搜索字段;回车选择;点击令牌编辑;空输入时退格删除最后一个过滤器;Escape 关闭弹出窗口',+ usage: {+ description:+ '结构化过滤栏,每个令牌代表一个过滤器(字段 + 运算符 + 值)。用户从预输入下拉菜单中选择字段,在编辑弹出窗口中配置运算符和值,并将过滤器作为可移除的令牌进行管理。',+ features: [+ '预输入字段选择,支持搜索和别名',+ '编辑弹出窗口,包含字段、运算符和值选择器',+ '支持 13 种值类型:字符串、整数、浮点数、枚举、日期、时间等',+ '令牌式显示,支持点击编辑和移除',+ '通过 ref 提供命令式 API 控制聚焦/失焦',+ '只读模式,显示过滤器但不允许编辑',+ ],+ accessibility: [+ '基于 XDSTokenizer 构建,提供 combobox 模式,包含 aria-expanded 和 aria-autocomplete。',+ '过滤器令牌具有包含字段名、运算符和值的无障碍标签。',+ '编辑弹出窗口使用 XDSPopover,支持焦点捕获和轻量关闭。',+ '清除全部按钮具有无障碍标签。',+ 'Keyboard: 输入搜索字段;回车选择;点击令牌编辑;空输入时退格删除最后一个过滤器;Escape 关闭弹出窗口',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjsindex 57ba45ac33..d9a024f20c 100644--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs@@ -2,19 +2,7 @@export const docs = {name: 'ProgressBar',- description:- 'A progress bar for displaying determinate or indeterminate progress.', keywords: ["progressbar","progress","loader","loading","linear","determinate","indeterminate","meter"],- features: [- 'Determinate mode uses role="meter" with aria-valuenow, aria-valuemin, and aria-valuemax',- 'Indeterminate mode uses role="progressbar" without value attributes',- 'Label is always connected via aria-labelledby',- 'aria-valuetext provides human-readable value description (determinate only)',- 'Indeterminate animation respects prefers-reduced-motion',- 'Supports four semantic color variants: accent, positive, warning, negative',- 'Single track height: 8px',- 'Supports custom value label formatter via formatValueLabel',- 'Compose additional labels, status icons, and descriptions outside the component — ProgressBar is intentionally minimal',- ],+ keywords: ["progressbar","progress","loader","loading","linear","determinate","indeterminate","meter"],props: [{name: 'label',@@ -77,41 +65,31 @@ export const docs = {{className: 'xds-progressbar-fill', visualProps: ['variant']},],},- notes: [- 'ProgressBar is intentionally minimal — it handles the meter/track and an optional value label. For additional context like descriptions, status icons, or custom label placements, compose them alongside the bar using layout components.',- 'Do not add props for label placement, progress descriptions, or embedded icons. These are composition concerns, not meter concerns.',- ],- accessibility: [- 'Determinate: uses role="meter" with aria-valuenow, aria-valuemin, aria-valuemax',- 'Indeterminate: uses role="progressbar" without value attributes',- 'Label is always connected via aria-labelledby',- 'aria-valuetext provides human-readable value description (determinate only)',- 'Indeterminate animation respects prefers-reduced-motion',- ],usage: {- summary: 'Displays determinate or indeterminate progress of a process.',- content: `## When to use--- Showing completion progress of a known-length operation.-- Indicating an indeterminate loading state with a known container size.`,+ description:+ 'A progress bar for displaying determinate or indeterminate progress of a process. Use for showing completion progress of known-length operations or indicating indeterminate loading states with a known container size.',+ features: [+ 'Supports four semantic color variants: accent, positive, warning, negative',+ 'Supports custom value label formatter via formatValueLabel',+ ],+ accessibility: [+ 'Determinate: uses role="meter" with aria-valuenow, aria-valuemin, aria-valuemax',+ 'Indeterminate: uses role="progressbar" without value attributes',+ 'Label is always connected via aria-labelledby',+ 'aria-valuetext provides human-readable value description (determinate only)',+ 'Indeterminate animation respects prefers-reduced-motion',+ ],+ notes: [+ 'ProgressBar is intentionally minimal — it handles the meter/track and an optional value label. For additional context like descriptions, status icons, or custom label placements, compose them alongside the bar using layout components.',+ 'Do not add props for label placement, progress descriptions, or embedded icons. These are composition concerns, not meter concerns.',+ 'Single track height: 8px',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'ProgressBar',- description:- '用于显示确定或不确定进度的进度条组件。',- features: [- '确定模式使用 role="meter",配合 aria-valuenow、aria-valuemin 和 aria-valuemax',- '不确定模式使用 role="progressbar",不包含值属性',- '标签始终通过 aria-labelledby 关联',- 'aria-valuetext 提供人类可读的值描述(仅限确定模式)',- '不确定动画遵循 prefers-reduced-motion 偏好设置',- '支持四种语义颜色变体:accent、positive、warning、negative',- '单一轨道高度:8px',- '支持通过 formatValueLabel 自定义值标签格式化器',- ],props: [{name: 'label',@@ -174,13 +152,27 @@ export const docsZh = {{className: 'xds-progressbar-fill', visualProps: ['variant']},],},- accessibility: [- '确定模式:使用 role="meter",配合 aria-valuenow、aria-valuemin、aria-valuemax',- '不确定模式:使用 role="progressbar",不包含值属性',- '标签始终通过 aria-labelledby 关联',- 'aria-valuetext 提供人类可读的值描述(仅限确定模式)',- '不确定动画遵循 prefers-reduced-motion 偏好设置',- ],+ usage: {+ description:+ '用于显示确定或不确定进度的进度条组件。',+ features: [+ '确定模式使用 role="meter",配合 aria-valuenow、aria-valuemin 和 aria-valuemax',+ '不确定模式使用 role="progressbar",不包含值属性',+ '标签始终通过 aria-labelledby 关联',+ 'aria-valuetext 提供人类可读的值描述(仅限确定模式)',+ '不确定动画遵循 prefers-reduced-motion 偏好设置',+ '支持四种语义颜色变体:accent、positive、warning、negative',+ '单一轨道高度:8px',+ '支持通过 formatValueLabel 自定义值标签格式化器',+ ],+ accessibility: [+ '确定模式:使用 role="meter",配合 aria-valuenow、aria-valuemin、aria-valuemax',+ '不确定模式:使用 role="progressbar",不包含值属性',+ '标签始终通过 aria-labelledby 关联',+ 'aria-valuetext 提供人类可读的值描述(仅限确定模式)',+ '不确定动画遵循 prefers-reduced-motion 偏好设置',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjsindex e945100fbc..db206384a5 100644--- a/packages/core/src/RadioList/RadioList.doc.mjs+++ b/packages/core/src/RadioList/RadioList.doc.mjs@@ -2,17 +2,7 @@export const docs = {name: 'RadioList',- description:- 'A radio group component for single-value selection from a list of options.', keywords: ["radiolist","radio","radiogroup","radiobutton","optionlist","singlechoice","choicelist"],- features: [- 'Accessible — uses native <input type="radio"> with proper role="radiogroup" and ARIA attributes',- 'Orientation — supports vertical and horizontal layouts',- 'Sizes — sm (18px radio, 20px wrapper) and md (22px radio, 24px wrapper)',- 'Descriptions — optional description text per item',- 'Custom content — startContent and endContent slots on each item',- 'Disabled state — supports disabling the entire group or individual items',- 'Field integration — uses XDSField for label, description, required/optional, and status messaging',- ],+ keywords: ["radiolist","radio","radiogroup","radiobutton","optionlist","singlechoice","choicelist"],theming: {targets: [{className: 'xds-radio-list', visualProps: ['orientation', 'size']},@@ -21,14 +11,6 @@ export const docs = {{className: 'xds-radio-dot', visualProps: ['size']},],},- notes: [- 'XDSRadioList creates a RadioListContext that provides name, value, onChange, isDisabled, isRequired, size, and status to child items',- 'XDSRadioListItem must be used within an XDSRadioList — throws if context is missing',- 'Uses a hidden native <input type="radio"> with a custom visual overlay for consistent styling',- 'Focus outline uses the standard XDS focus outline token with 2px offset',- 'Hover states use color-mix() for consistent overlay tinting',- 'Size variants match CheckboxInput dimensions for visual consistency',- ],components: [{name: 'XDSRadioList',@@ -161,21 +143,27 @@ export const docs = {},],usage: {- summary: 'Allows a user to make a single selection from a list of options.',- content: `## When to use--- Presenting a limited set of options where only one can be selected.-- Making the single-selection constraint visually clear to users.--## When NOT to use--- Multiple selections are needed (use CheckboxList instead).-- The option list is very long (consider Selector instead).--## Best practices--- Do: Use a vertical list when labels are long or need detailed descriptions.-- Do: Use a horizontal input group for compact side-by-side comparison of short options.`,+ description:+ 'A radio group component for single-value selection from a list of options. Use when presenting a limited set of mutually exclusive choices where only one can be selected. For multiple selections use CheckboxList; for long option lists consider Selector.',+ features: [+ 'Supports vertical and horizontal layouts',+ 'Size variants: sm (18px radio, 20px wrapper) and md (22px radio, 24px wrapper)',+ 'Optional description text per item',+ 'startContent and endContent slots on each item',+ 'Supports disabling the entire group or individual items',+ 'Field integration via XDSField for label, description, required/optional, and status messaging',+ ],+ accessibility: [+ 'Uses native <input type="radio"> with proper role="radiogroup" and ARIA attributes',+ ],+ notes: [+ 'XDSRadioList creates a RadioListContext that provides name, value, onChange, isDisabled, isRequired, size, and status to child items',+ 'XDSRadioListItem must be used within an XDSRadioList — throws if context is missing',+ 'Uses a hidden native <input type="radio"> with a custom visual overlay for consistent styling',+ 'Focus outline uses the standard XDS focus outline token with 2px offset',+ 'Hover states use color-mix() for consistent overlay tinting',+ 'Size variants match CheckboxInput dimensions for visual consistency',+ ],anatomy: [{name: 'Header', required: false, description: 'Optional heading above the radio list.'},{name: 'Children', required: true, description: 'The radio list items rendered as selectable options.'},@@ -187,17 +175,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'RadioList',- description:- '用于从选项列表中进行单值选择的单选按钮组组件。',- features: [- '无障碍 - 使用原生 <input type="radio">,配合正确的 role="radiogroup" 和 ARIA 属性',- '方向 - 支持垂直和水平布局',- '尺寸 - sm(18px 单选按钮,20px 容器)和 md(22px 单选按钮,24px 容器)',- '描述 - 每个选项可选的描述文本',- '自定义内容 - 每个选项上的 startContent 和 endContent 插槽',- '禁用状态 - 支持禁用整个组或单个选项',- '字段集成 - 使用 XDSField 提供标签、描述、必填/可选和状态消息',- ],theming: {targets: [{className: 'xds-radio-list', visualProps: ['orientation', 'size']},@@ -206,14 +183,6 @@ export const docsZh = {{className: 'xds-radio-dot', visualProps: ['size']},],},- notes: [- 'XDSRadioList 创建一个 RadioListContext,向子项提供 name、value、onChange、isDisabled、isRequired、size 和 status',- 'XDSRadioListItem 必须在 XDSRadioList 内部使用——如果缺少上下文会抛出错误',- '使用隐藏的原生 <input type="radio"> 配合自定义视觉覆盖层以保持样式一致性',- '焦点轮廓使用标准 XDS 焦点轮廓令牌,偏移量为 2px',- '悬停状态使用 color-mix() 实现一致的覆盖层着色',- '尺寸变体与 CheckboxInput 的尺寸匹配,保持视觉一致性',- ],components: [{name: 'XDSRadioList',@@ -346,6 +315,27 @@ export const docsZh = {],},],+ usage: {+ description:+ '用于从选项列表中进行单值选择的单选按钮组组件。',+ features: [+ '无障碍 - 使用原生 <input type="radio">,配合正确的 role="radiogroup" 和 ARIA 属性',+ '方向 - 支持垂直和水平布局',+ '尺寸 - sm(18px 单选按钮,20px 容器)和 md(22px 单选按钮,24px 容器)',+ '描述 - 每个选项可选的描述文本',+ '自定义内容 - 每个选项上的 startContent 和 endContent 插槽',+ '禁用状态 - 支持禁用整个组或单个选项',+ '字段集成 - 使用 XDSField 提供标签、描述、必填/可选和状态消息',+ ],+ notes: [+ 'XDSRadioList 创建一个 RadioListContext,向子项提供 name、value、onChange、isDisabled、isRequired、size 和 status',+ 'XDSRadioListItem 必须在 XDSRadioList 内部使用——如果缺少上下文会抛出错误',+ '使用隐藏的原生 <input type="radio"> 配合自定义视觉覆盖层以保持样式一致性',+ '焦点轮廓使用标准 XDS 焦点轮廓令牌,偏移量为 2px',+ '悬停状态使用 color-mix() 实现一致的覆盖层着色',+ '尺寸变体与 CheckboxInput 的尺寸匹配,保持视觉一致性',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjsindex 4f9e4f607f..1181460aea 100644--- a/packages/core/src/Section/Section.doc.mjs+++ b/packages/core/src/Section/Section.doc.mjs@@ -2,16 +2,7 @@export const docs = {name: 'Section',- description:- 'Container with background variants for creating visually distinct regions that automatically escape parent container padding for edge-to-edge fills.',keywords: ["section","panel","container","group","fieldset","region","block"],- features: [- 'Background variants: section, transparent, and wash',- 'Automatically escapes parent container padding for edge-to-edge fills',- 'Supports divider borders on any combination of sides (top, bottom, start, end)',- 'Flexible sizing via SizeValue for width, height, maxWidth, and minHeight',- 'Supports `padding={0}` for edge-to-edge content',- ],props: [{name: 'variant',@@ -78,26 +69,21 @@ export const docs = {],},usage: {- summary: 'Container for creating visually distinct regions on a page.',- content: `## When to use--- Chunking information into groups using whitespace, dividers, or type scale.-- Prefer sections over cards as the default page structure; use cards only when stronger visual distinction is needed.`,+ description:+ 'Container with background variants for creating visually distinct regions on a page. Automatically escapes parent container padding for edge-to-edge fills. Prefer sections over cards as the default page structure; use cards only when stronger visual distinction is needed.',+ features: [+ 'Background variants: section, transparent, and wash',+ 'Automatically escapes parent container padding for edge-to-edge fills',+ 'Supports divider borders on any combination of sides (top, bottom, start, end)',+ 'Flexible sizing via SizeValue for width, height, maxWidth, and minHeight',+ 'Supports `padding={0}` for edge-to-edge content',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Section',- description:- '带有背景变体的容器,用于创建视觉上可区分的区域,自动突破父容器内边距实现全宽填充。',- features: [- '背景变体:section、transparent 和 wash',- '自动突破父容器内边距实现全宽填充',- '支持在任意边的组合上设置分隔线边框(top、bottom、start、end)',- '通过 SizeValue 灵活设置宽度、高度、最大宽度和最小高度',- '支持 `padding={0}` 实现全宽内容',- ],props: [{name: 'variant',@@ -163,6 +149,17 @@ export const docsZh = {},],},+ usage: {+ description:+ '带有背景变体的容器,用于创建视觉上可区分的区域,自动突破父容器内边距实现全宽填充。',+ features: [+ '背景变体:section、transparent 和 wash',+ '自动突破父容器内边距实现全宽填充',+ '支持在任意边的组合上设置分隔线边框(top、bottom、start、end)',+ '通过 SizeValue 灵活设置宽度、高度、最大宽度和最小高度',+ '支持 `padding={0}` 实现全宽内容',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjsindex 8f860dc1e1..42225f8ad5 100644--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs@@ -2,44 +2,13 @@export const docs = {name: 'SegmentedControl',- description:- 'Segmented button group for single selection with radio group semantics. Visually resembles a tab bar but controls a value, not a view.', keywords: ['radio', 'tabs', 'toggle', 'toggle-group', 'pill', 'button-group', 'switch', 'segment', 'control'],- features: [- 'Context-based communication: XDSSegmentedControlContext passes value/onChange/size/isDisabled from parent to children',- 'Radio group semantics: role="radiogroup" with role="radio" items and aria-checked',- 'Roving tabindex: only the selected item is tabbable (tabIndex=0), others are tabIndex=-1',- 'Keyboard navigation: ArrowLeft/ArrowRight navigate + select, Home/End jump to first/last, wraps around',- 'Animated indicator: selected item has a raised surface background with box-shadow',- 'Icon + label or icon-only items (isLabelHidden hides label visually, keeps it as aria-label)',- 'Size variants: sm (compact for toolbars), md (default), lg (larger touch targets)',- 'Disabled state: entire group or individual items via aria-disabled (maintains focusability)',- 'Hover state: unselected items show overlay on hover with @media (hover: hover) guard',- ],+ keywords: ['radio', 'tabs', 'toggle', 'toggle-group', 'pill', 'button-group', 'switch', 'segment', 'control'],theming: {targets: [{className: 'xds-segmented-control', visualProps: ['size']},{className: 'xds-segmented-control-item'},],},- accessibility: [- 'Container has role="radiogroup" with aria-label from the label prop (never rendered visually)',- 'Items have role="radio" with aria-checked indicating selection state',- 'Roving tabindex: selected item has tabIndex=0, others have tabIndex=-1',- 'Arrow keys navigate and select simultaneously (radio group pattern)',- 'Disabled items use aria-disabled (not native disabled) to maintain focusability',- 'Icon-only items use isLabelHidden — label becomes aria-label',- ],- keyboard:- 'ArrowRight/ArrowLeft navigate and select (wrapping). Home/End jump to first/last item. Only the selected item is in the tab order.',- notes: [- 'Controlled-only — no uncontrolled mode in v1',- 'Horizontal-only — no vertical orientation in v1',- 'Deselection not allowed (radio semantics — always one selected)',- 'Uses aria-disabled instead of native disabled to maintain keyboard focusability',- 'Keyboard navigation skips disabled items',- 'Track background uses --color-neutral, selected indicator uses --color-background-surface with --shadow-low',- 'label prop on XDSSegmentedControl is aria-only (like XDSTabList aria-label), never rendered visually',- ],components: [{name: 'XDSSegmentedControl',@@ -130,53 +99,39 @@ export const docs = {},],usage: {- summary: 'Segmented button group for single selection with radio group semantics.',- content: `## When to use--- Switching between a small set of mutually exclusive views or modes.-- When all options should be visible at once.--## When NOT to use--- For two-state toggles (use ToggleButton instead).-- For navigation between pages (use Tabs instead).`,+ description:+ 'Segmented button group for single selection with radio group semantics. Visually resembles a tab bar but controls a value, not a view. Use for switching between a small set of mutually exclusive views or modes when all options should be visible at once. For two-state toggles, use ToggleButton; for page navigation, use Tabs.',+ features: [+ 'Animated indicator with raised surface background and box-shadow',+ 'Icon + label or icon-only items (isLabelHidden hides label visually, keeps it as aria-label)',+ 'Size variants: sm (compact for toolbars), md (default), lg (larger touch targets)',+ 'Disabled state: entire group or individual items via aria-disabled (maintains focusability)',+ ],+ accessibility: [+ 'Container has role="radiogroup" with aria-label from the label prop (never rendered visually)',+ 'Items have role="radio" with aria-checked indicating selection state',+ 'Roving tabindex: selected item has tabIndex=0, others have tabIndex=-1',+ 'Arrow keys navigate and select simultaneously (radio group pattern)',+ 'Disabled items use aria-disabled (not native disabled) to maintain focusability',+ 'Icon-only items use isLabelHidden — label becomes aria-label',+ 'Keyboard: ArrowRight/ArrowLeft navigate and select (wrapping); Home/End jump to first/last item; only the selected item is in the tab order.',+ ],+ notes: [+ 'Controlled-only — no uncontrolled mode in v1',+ 'Horizontal-only — no vertical orientation in v1',+ 'Deselection not allowed (radio semantics — always one selected)',+ 'Uses aria-disabled instead of native disabled to maintain keyboard focusability',+ 'Keyboard navigation skips disabled items',+ 'Track background uses --color-neutral, selected indicator uses --color-background-surface with --shadow-low',+ 'label prop on XDSSegmentedControl is aria-only (like XDSTabList aria-label), never rendered visually',+ 'Context-based communication: XDSSegmentedControlContext passes value/onChange/size/isDisabled from parent to children',+ 'Hover state: unselected items show overlay on hover with @media (hover: hover) guard',+ ],},};/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description:- '分段按钮组,用于单选,具有单选组语义。外观类似标签栏,但控制的是值而非视图。',- features: [- '基于上下文通信:XDSSegmentedControlContext 将 value/onChange/size/isDisabled 从父组件传递给子组件',- '单选组语义:role="radiogroup" 配合 role="radio" 子项和 aria-checked',- '漫游焦点:仅选中项可通过 Tab 访问(tabIndex=0),其余为 tabIndex=-1',- '键盘导航:ArrowLeft/ArrowRight 导航并选中,Home/End 跳转到首尾,循环切换',- '动画指示器:选中项具有带 box-shadow 的凸起表面背景',- '图标+文本或纯图标项(isLabelHidden 隐藏文本,保留为 aria-label)',- '尺寸变体:sm(紧凑,适用于工具栏)、md(默认)、lg(更大触摸目标)',- '禁用状态:可禁用整组或单个项,使用 aria-disabled 保持可聚焦性',- '悬停状态:未选中项悬停时显示覆盖层,使用 @media (hover: hover) 保护',- ],- accessibility: [- '容器具有 role="radiogroup",aria-label 来自 label 属性(不会渲染为可见内容)',- '子项具有 role="radio",aria-checked 表示选中状态',- '漫游焦点:选中项 tabIndex=0,其余 tabIndex=-1',- '方向键同时导航和选中(单选组模式)',- '禁用项使用 aria-disabled(非原生 disabled)以保持可聚焦性',- '纯图标项使用 isLabelHidden,label 变为 aria-label',- ],- keyboard:- 'ArrowRight/ArrowLeft 导航并选中(循环)。Home/End 跳转到首尾项。仅选中项在 Tab 顺序中。',- notes: [- '仅受控模式,v1 无非受控模式',- '仅水平方向,v1 无垂直方向',- '不允许取消选中(单选语义,始终有一项选中)',- '使用 aria-disabled 替代原生 disabled 以保持键盘可聚焦性',- '键盘导航会跳过禁用项',- '轨道背景使用 --color-neutral,选中指示器使用 --color-background-surface 配合 --shadow-low',- 'XDSSegmentedControl 的 label 属性仅用于 aria(类似 XDSTabList 的 aria-label),不会渲染为可见内容',- ],components: [{name: 'XDSSegmentedControl',@@ -205,6 +160,39 @@ export const docsZh = {},},],+ usage: {+ description:+ '分段按钮组,用于单选,具有单选组语义。外观类似标签栏,但控制的是值而非视图。',+ features: [+ '基于上下文通信:XDSSegmentedControlContext 将 value/onChange/size/isDisabled 从父组件传递给子组件',+ '单选组语义:role="radiogroup" 配合 role="radio" 子项和 aria-checked',+ '漫游焦点:仅选中项可通过 Tab 访问(tabIndex=0),其余为 tabIndex=-1',+ '键盘导航:ArrowLeft/ArrowRight 导航并选中,Home/End 跳转到首尾,循环切换',+ '动画指示器:选中项具有带 box-shadow 的凸起表面背景',+ '图标+文本或纯图标项(isLabelHidden 隐藏文本,保留为 aria-label)',+ '尺寸变体:sm(紧凑,适用于工具栏)、md(默认)、lg(更大触摸目标)',+ '禁用状态:可禁用整组或单个项,使用 aria-disabled 保持可聚焦性',+ '悬停状态:未选中项悬停时显示覆盖层,使用 @media (hover: hover) 保护',+ ],+ accessibility: [+ '容器具有 role="radiogroup",aria-label 来自 label 属性(不会渲染为可见内容)',+ '子项具有 role="radio",aria-checked 表示选中状态',+ '漫游焦点:选中项 tabIndex=0,其余 tabIndex=-1',+ '方向键同时导航和选中(单选组模式)',+ '禁用项使用 aria-disabled(非原生 disabled)以保持可聚焦性',+ '纯图标项使用 isLabelHidden,label 变为 aria-label',+ 'Keyboard: ArrowRight/ArrowLeft 导航并选中(循环)。Home/End 跳转到首尾项。仅选中项在 Tab 顺序中。',+ ],+ notes: [+ '仅受控模式,v1 无非受控模式',+ '仅水平方向,v1 无垂直方向',+ '不允许取消选中(单选语义,始终有一项选中)',+ '使用 aria-disabled 替代原生 disabled 以保持键盘可聚焦性',+ '键盘导航会跳过禁用项',+ '轨道背景使用 --color-neutral,选中指示器使用 --color-background-surface 配合 --shadow-low',+ 'XDSSegmentedControl 的 label 属性仅用于 aria(类似 XDSTabList 的 aria-label),不会渲染为可见内容',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjsindex e1e5215ce7..b5a594c562 100644--- a/packages/core/src/Selector/Selector.doc.mjs+++ b/packages/core/src/Selector/Selector.doc.mjs@@ -2,24 +2,7 @@export const docs = {name: 'Selector',- description:- 'Dropdown selector for choosing from a list of options. Follows XDS input conventions with label, status, and field props.', keywords: ["selector","select","dropdown","combobox","picker","listbox","chooser","autocomplete","option","selectmenu"],- features: [- 'Supports string items (auto-converted to {value, label}), object items with optional icon and disabled state, dividers, and labeled sections',- 'Custom item rendering via children render prop and XDSSelectorItem helper',- 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',- 'Size variants: sm, md, lg',- 'Full keyboard navigation with typeahead support',- 'Accessible — role="combobox" trigger, role="listbox" dropdown, role="group" for sections, aria-activedescendant for focus',- ],- keyboard:- '↑↓ navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.',- accessibility: [- 'Uses role="combobox" on the trigger button.',- 'Dropdown uses role="listbox".',- 'Section groups use role="group".',- 'aria-activedescendant tracks the focused option.',- ],+ keywords: ["selector","select","dropdown","combobox","picker","listbox","chooser","autocomplete","option","selectmenu"],theming: {targets: [{className: 'xds-selector', visualProps: ['size', 'status']},@@ -141,23 +124,21 @@ export const docs = {},],usage: {- summary: 'Gives users a choice between multiple items within a dropdown list.',- content: `## When to use--- Presenting 3\u201320 options in forms or settings.-- Capturing or assigning a value from a predefined list.-- For 20+ options, use a searchable Selector variant.--## When NOT to use--- Triggering actions (use Dropdown Menu instead).-- Selecting with a default action (use Split Button instead).--## Best practices--- Do: Use to capture or assign values in forms, wizards, or settings.-- Don't: Use for triggering actions \u2014 use Dropdown Menu instead.-- Supports error, success, warning, and disabled states.`,+ description:+ 'Dropdown selector for choosing from a list of options, following XDS input conventions with label, status, and field props. Use for presenting 3\u201320 options in forms or settings; for 20+ options, use a searchable variant. Do not use for triggering actions \u2014 use Dropdown Menu instead.',+ features: [+ 'Supports string items (auto-converted to {value, label}), object items with optional icon and disabled state, dividers, and labeled sections',+ 'Custom item rendering via children render prop and XDSSelectorItem helper',+ 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',+ 'Size variants: sm, md, lg',+ ],+ accessibility: [+ 'Uses role="combobox" on the trigger button.',+ 'Dropdown uses role="listbox".',+ 'Section groups use role="group".',+ 'aria-activedescendant tracks the focused option.',+ 'Keyboard: \u2191\u2193 navigate, Enter/Space select, Escape close, Home/End jump, A-Z typeahead.',+ ],anatomy: [{name: 'Label', required: false, description: 'Text label displayed above the selector.'},{name: 'Placeholder', required: false, description: 'Hint text shown when no value is selected.'},@@ -172,24 +153,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Selector',- description:- '用于从选项列表中进行选择的下拉选择器。遵循 XDS 输入规范,支持标签、状态和字段属性。',- features: [- '支持字符串选项(自动转换为 {value, label})、带可选图标和禁用状态的对象选项、分隔线和带标签的分组',- '通过 children 渲染函数和 XDSSelectorItem 辅助组件实现自定义选项渲染',- '集成 XDS 字段规范:label、description、isRequired、isOptional、isLabelHidden、status',- '尺寸变体:sm、md、lg',- '完整的键盘导航,支持输入快速定位',- '无障碍 - 触发器使用 role="combobox",下拉菜单使用 role="listbox",分组使用 role="group",焦点追踪使用 aria-activedescendant',- ],- keyboard:- '↑↓ 导航,Enter/Space 选择,Escape 关闭,Home/End 跳转,A-Z 输入快速定位。',- accessibility: [- '触发按钮使用 role="combobox"。',- '下拉菜单使用 role="listbox"。',- '分组使用 role="group"。',- 'aria-activedescendant 追踪当前聚焦的选项。',- ],theming: {targets: [{className: 'xds-selector', visualProps: ['size', 'status']},@@ -309,6 +272,25 @@ export const docsZh = {],},],+ usage: {+ description:+ '用于从选项列表中进行选择的下拉选择器。遵循 XDS 输入规范,支持标签、状态和字段属性。',+ features: [+ '支持字符串选项(自动转换为 {value, label})、带可选图标和禁用状态的对象选项、分隔线和带标签的分组',+ '通过 children 渲染函数和 XDSSelectorItem 辅助组件实现自定义选项渲染',+ '集成 XDS 字段规范:label、description、isRequired、isOptional、isLabelHidden、status',+ '尺寸变体:sm、md、lg',+ '完整的键盘导航,支持输入快速定位',+ '无障碍 - 触发器使用 role="combobox",下拉菜单使用 role="listbox",分组使用 role="group",焦点追踪使用 aria-activedescendant',+ ],+ accessibility: [+ '触发按钮使用 role="combobox"。',+ '下拉菜单使用 role="listbox"。',+ '分组使用 role="group"。',+ 'aria-activedescendant 追踪当前聚焦的选项。',+ 'Keyboard: ↑↓ 导航,Enter/Space 选择,Escape 关闭,Home/End 跳转,A-Z 输入快速定位。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjsindex 08e051aedb..f106dc2418 100644--- a/packages/core/src/SideNav/SideNav.doc.mjs+++ b/packages/core/src/SideNav/SideNav.doc.mjs@@ -2,29 +2,7 @@export const docs = {name: 'SideNav',- description:- 'Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and collapsible sidebar.',keywords: ["sidenav","sidebar","navigation","drawer","menu","nav","aside","sidemenu","navmenu","sider","treeview"],- features: [- 'Five-zone layout: header, topContent, children (scrollable), footer, footerIcons',- 'Smart header interaction boundary logic — links and menu trigger coexist without overlap',- 'Nested items via children on XDSSideNavItem',- 'Selected state with optional alternate icon for filled/outline variants',- 'Section grouping with optional title, subtitle, and end content',- 'Collapsible sidebar via collapsible prop — collapses to icon-only toolbar, uncontrolled or controlled',- 'Accessible — nav landmark, aria-current="page", role="group" with aria-labelledby on sections',- 'Keyboard navigable — Tab through items, Enter/Space to activate',- 'Resizable sidebar via resizable prop — drag handle at inline-end edge, pointer-based resize with min/max constraints',- 'Heading text overflow detection with tooltip — shows full text on hover when heading, superheading, or subheading is truncated by ellipsis',- 'Header end content slot — headerEndContent prop on XDSSideNavHeading for badges, status indicators, or action buttons at the trailing edge of the heading row',- ],- accessibility: [- '<nav aria-label="Side navigation"> wraps the entire component',- 'aria-current="page" is applied to the selected item',- 'Sections use role="group" with aria-labelledby pointing to the section title',- 'isHeaderHidden visually hides the section title while keeping it accessible to screen readers',- ],- keyboard: 'Tab through items, Enter/Space to activate links',theming: {targets: [{className: 'xds-side-nav', visualProps: ['mode']},@@ -33,14 +11,7 @@ export const docs = {{className: 'xds-side-nav-section'},],},- notes: [- 'When used inside XDSAppShell alongside XDSTopNav, omit XDSSideNavHeading — the TopNav already provides app identity and including the header would duplicate it.',- 'Without a TopNav, include XDSSideNavHeading to provide app identity.',- 'Header interaction model: headingHref only → whole header is one link; headingHref + superheadingHref, no menu → each text is an independent link; menu only, no hrefs → whole header is the popover trigger; menu + hrefs → links are independent <a> elements, chevron/remaining area is the popover trigger.',- 'Depends on useXDSPopover for the header menu popover and XDSIcon for rendering icon components in nav items.',- 'XDSSideNavCollapseButton renders as an icon-only ghost button by default. Place it in footerIcons, header, or outside the sidenav (pass sideNavRef).',- 'useXDSSideNavCollapse hook exposes { isCollapsed, toggle, isCollapsible } for custom collapse controls.',- ], components: [+ components: [{name: 'XDSSideNav',description:@@ -267,24 +238,34 @@ export const docs = {},],usage: {- summary: 'Navigation system helping users find and browse information. Left nav is the default recommendation.',- content: `## When to use--- 5 or more navigation items.-- Customizable navigation structure.-- Complex grouping of navigation items.-- Secondary item actions needed.-- Collapsible navigation sections.--## When NOT to use--- Filter-primary tools (use tabs or filter buttons instead).-- Housing wide components that need more horizontal space.--## Best practices--- Do: Use descriptive names for navigation items.-- Don't: Use navigation to filter content \u2014 use tabs or filter buttons instead.`,+ description:+ 'Sidebar navigation component for application pages, supporting sections, nested items, selected state, icons, and collapsible sidebar. Left nav is the default recommendation for 5+ navigation items or complex grouping. Do not use for filter-primary tools \u2014 use tabs or filter buttons instead.',+ features: [+ 'Five-zone layout: header, topContent, children (scrollable), footer, footerIcons',+ 'Smart header interaction boundary logic \u2014 links and menu trigger coexist without overlap',+ 'Nested items via children on XDSSideNavItem',+ 'Selected state with optional alternate icon for filled/outline variants',+ 'Section grouping with optional title, subtitle, and end content',+ 'Collapsible sidebar via collapsible prop \u2014 collapses to icon-only toolbar, uncontrolled or controlled',+ 'Resizable sidebar via resizable prop \u2014 drag handle at inline-end edge, pointer-based resize with min/max constraints',+ 'Heading text overflow detection with tooltip \u2014 shows full text on hover when truncated',+ 'Header end content slot for badges, status indicators, or action buttons',+ ],+ accessibility: [+ '<nav aria-label="Side navigation"> wraps the entire component',+ 'aria-current="page" is applied to the selected item',+ 'Sections use role="group" with aria-labelledby pointing to the section title',+ 'isHeaderHidden visually hides the section title while keeping it accessible to screen readers',+ 'Keyboard: Tab through items, Enter/Space to activate links',+ ],+ notes: [+ 'When used inside XDSAppShell alongside XDSTopNav, omit XDSSideNavHeading \u2014 the TopNav already provides app identity and including the header would duplicate it.',+ 'Without a TopNav, include XDSSideNavHeading to provide app identity.',+ 'Header interaction model: headingHref only \u2192 whole header is one link; headingHref + superheadingHref, no menu \u2192 each text is an independent link; menu only, no hrefs \u2192 whole header is the popover trigger; menu + hrefs \u2192 links are independent <a> elements, chevron/remaining area is the popover trigger.',+ 'Depends on useXDSPopover for the header menu popover and XDSIcon for rendering icon components in nav items.',+ 'XDSSideNavCollapseButton renders as an icon-only ghost button by default. Place it in footerIcons, header, or outside the sidenav (pass sideNavRef).',+ 'useXDSSideNavCollapse hook exposes { isCollapsed, toggle, isCollapsible } for custom collapse controls.',+ ],anatomy: [{name: 'Product icon and name', required: false, description: 'Branding area at the top of the nav.'},{name: 'Navigation items', required: true, description: 'Sections and groups of navigable links.'},@@ -296,25 +277,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'SideNav',- description:- '应用页面的侧边栏导航组件。支持分组、嵌套项、选中状态、图标和可折叠侧边栏。',- features: [- '五区域布局:header、topContent、children(可滚动)、footer、footerIcons',- '智能头部交互边界逻辑——链接和菜单触发器共存而不重叠',- '通过 XDSSideNavItem 的 children 实现嵌套项',- '选中状态支持可选的替代图标,用于填充/轮廓变体',- '分组支持可选的标题、副标题和尾部内容',- '通过 collapsible 属性支持可折叠侧边栏——折叠为仅图标工具栏,支持非受控和受控模式',- '无障碍 - nav 地标、aria-current="page"、分组使用 role="group" 配合 aria-labelledby',- '键盘可导航 - Tab 切换项目,Enter/Space 激活',- ],- accessibility: [- '<nav aria-label="Side navigation"> 包裹整个组件',- 'aria-current="page" 应用于选中项',- '分组使用 role="group",aria-labelledby 指向分组标题',- 'isHeaderHidden 在视觉上隐藏分组标题,同时保持屏幕阅读器可访问',- ],- keyboard: 'Tab 切换项目,Enter/Space 激活链接',theming: {targets: [{className: 'xds-side-nav', visualProps: ['mode']},@@ -323,14 +285,6 @@ export const docsZh = {{className: 'xds-side-nav-section'},],},- notes: [- '在 XDSAppShell 中与 XDSTopNav 一起使用时,省略 XDSSideNavHeading——TopNav 已提供应用标识,包含头部会导致重复。',- '没有 TopNav 时,包含 XDSSideNavHeading 以提供应用标识。',- '头部交互模型:仅 headingHref → 整个头部是一个链接;headingHref + superheadingHref,无菜单 → 每段文本是独立链接;仅菜单,无 href → 整个头部是弹出框触发器;菜单 + href → 链接是独立的 <a> 元素,箭头/剩余区域是弹出框触发器。',- '依赖 useXDSPopover 实现头部菜单弹出框,依赖 XDSIcon 在导航项中渲染图标组件。',- 'XDSSideNavCollapseButton 默认渲染为仅图标的 ghost 按钮。可放置在 footerIcons、header 中,或侧边栏外部(传入 sideNavRef)。',- 'useXDSSideNavCollapse hook 暴露 { isCollapsed, toggle, isCollapsible },用于自定义折叠控件。',- ],components: [{name: 'XDSSideNav',@@ -558,6 +512,35 @@ export const docsZh = {],},],+ usage: {+ description:+ '应用页面的侧边栏导航组件。支持分组、嵌套项、选中状态、图标和可折叠侧边栏。',+ features: [+ '五区域布局:header、topContent、children(可滚动)、footer、footerIcons',+ '智能头部交互边界逻辑——链接和菜单触发器共存而不重叠',+ '通过 XDSSideNavItem 的 children 实现嵌套项',+ '选中状态支持可选的替代图标,用于填充/轮廓变体',+ '分组支持可选的标题、副标题和尾部内容',+ '通过 collapsible 属性支持可折叠侧边栏——折叠为仅图标工具栏,支持非受控和受控模式',+ '无障碍 - nav 地标、aria-current="page"、分组使用 role="group" 配合 aria-labelledby',+ '键盘可导航 - Tab 切换项目,Enter/Space 激活',+ ],+ accessibility: [+ '<nav aria-label="Side navigation"> 包裹整个组件',+ 'aria-current="page" 应用于选中项',+ '分组使用 role="group",aria-labelledby 指向分组标题',+ 'isHeaderHidden 在视觉上隐藏分组标题,同时保持屏幕阅读器可访问',+ 'Keyboard: Tab 切换项目,Enter/Space 激活链接',+ ],+ notes: [+ '在 XDSAppShell 中与 XDSTopNav 一起使用时,省略 XDSSideNavHeading——TopNav 已提供应用标识,包含头部会导致重复。',+ '没有 TopNav 时,包含 XDSSideNavHeading 以提供应用标识。',+ '头部交互模型:仅 headingHref → 整个头部是一个链接;headingHref + superheadingHref,无菜单 → 每段文本是独立链接;仅菜单,无 href → 整个头部是弹出框触发器;菜单 + href → 链接是独立的 <a> 元素,箭头/剩余区域是弹出框触发器。',+ '依赖 useXDSPopover 实现头部菜单弹出框,依赖 XDSIcon 在导航项中渲染图标组件。',+ 'XDSSideNavCollapseButton 默认渲染为仅图标的 ghost 按钮。可放置在 footerIcons、header 中,或侧边栏外部(传入 sideNavRef)。',+ 'useXDSSideNavCollapse hook 暴露 { isCollapsed, toggle, isCollapsible },用于自定义折叠控件。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Skeleton/Skeleton.doc.mjs b/packages/core/src/Skeleton/Skeleton.doc.mjsindex db16a4b36f..3539d38616 100644--- a/packages/core/src/Skeleton/Skeleton.doc.mjs+++ b/packages/core/src/Skeleton/Skeleton.doc.mjs@@ -2,16 +2,7 @@export const docs = {name: 'Skeleton',- description:- 'A placeholder loading component that displays an animated pulsing effect while content is loading.',keywords: ["skeleton","placeholder","loading","shimmer","pulse","loader","bone","ghost","preloader"],- features: [- 'Pulsing Animation: Smooth opacity animation using stepped timing for a subtle shimmer effect',- 'Staggered Animation: Sequential skeletons can be staggered to create a wave effect',- 'High Contrast Support: Automatically adjusts for users with prefers-contrast: more',- 'Flexible Sizing: Width and height props accept pixels or any CSS value',- 'Token-aligned Radius: Border radius options map directly to design tokens',- ],props: [{name: 'width',@@ -43,38 +34,29 @@ export const docs = {{className: 'xds-skeleton'},],},- notes: [- 'Uses steps(10, end) timing function for a subtle shimmer effect.',- 'Animation alternates between 0.25 and 1.0 opacity.',- 'Background color comes from the glimmer token, with glimmerHighContrast for accessibility.',- 'Numeric dimensions are converted to pixels; strings are passed through as-is.',- 'Animation timing constants: DELAY_TIME (1000ms) initial delay before animation starts, FADE_TIME (1000ms) duration of one opacity cycle, STAGGER_TIME (100ms) delay increment between sequential elements.',- ],usage: {- summary: 'A placeholder loading component that displays an animated pulsing effect while content is loading.',- content: `## When to use--- Content of known size is loading.-- Building skeleton screens that match the layout of the content being loaded.--## When NOT to use--- Content dimensions are unknown (use Spinner instead).`,+ description:+ 'A placeholder loading component that displays an animated pulsing effect while content is loading. Use when content of known size is loading to build skeleton screens matching the layout. For unknown content dimensions, use Spinner instead.',+ features: [+ 'Smooth opacity animation using stepped timing for a subtle shimmer effect',+ 'Sequential skeletons can be staggered to create a wave effect',+ 'High contrast support: automatically adjusts for prefers-contrast: more',+ 'Flexible sizing: width and height accept pixels or any CSS value',+ 'Token-aligned radius: border radius options map directly to design tokens',+ ],+ notes: [+ 'Uses steps(10, end) timing function for a subtle shimmer effect.',+ 'Animation alternates between 0.25 and 1.0 opacity.',+ 'Background color comes from the glimmer token, with glimmerHighContrast for accessibility.',+ 'Numeric dimensions are converted to pixels; strings are passed through as-is.',+ 'Animation timing constants: DELAY_TIME (1000ms) initial delay before animation starts, FADE_TIME (1000ms) duration of one opacity cycle, STAGGER_TIME (100ms) delay increment between sequential elements.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Skeleton',- description:- '占位加载组件,在内容加载时显示动画脉冲效果。',- features: [- '脉冲动画:使用分步计时的平滑透明度动画,呈现细腻的闪烁效果',- '交错动画:连续的骨架屏可以交错排列以创建波浪效果',- '高对比度支持:自动适配 prefers-contrast: more 用户偏好',- '灵活尺寸:宽度和高度属性接受像素值或任意 CSS 值',- '令牌对齐圆角:边框圆角选项直接映射到设计令牌',- ],props: [{name: 'width',@@ -107,13 +89,24 @@ export const docsZh = {{className: 'xds-skeleton'},],},- notes: [- '使用 steps(10, end) 计时函数实现细腻的闪烁效果。',- '动画在 0.25 和 1.0 透明度之间交替。',- '背景颜色来自 glimmer 令牌,无障碍场景使用 glimmerHighContrast。',- '数字类型的尺寸会转换为像素值;字符串类型按原样传递。',- '动画时序常量:DELAY_TIME(1000ms)动画开始前的初始延迟,FADE_TIME(1000ms)一个透明度循环的持续时间,STAGGER_TIME(100ms)连续元素之间的延迟增量。',- ],+ usage: {+ description:+ '占位加载组件,在内容加载时显示动画脉冲效果。',+ features: [+ '脉冲动画:使用分步计时的平滑透明度动画,呈现细腻的闪烁效果',+ '交错动画:连续的骨架屏可以交错排列以创建波浪效果',+ '高对比度支持:自动适配 prefers-contrast: more 用户偏好',+ '灵活尺寸:宽度和高度属性接受像素值或任意 CSS 值',+ '令牌对齐圆角:边框圆角选项直接映射到设计令牌',+ ],+ notes: [+ '使用 steps(10, end) 计时函数实现细腻的闪烁效果。',+ '动画在 0.25 和 1.0 透明度之间交替。',+ '背景颜色来自 glimmer 令牌,无障碍场景使用 glimmerHighContrast。',+ '数字类型的尺寸会转换为像素值;字符串类型按原样传递。',+ '动画时序常量:DELAY_TIME(1000ms)动画开始前的初始延迟,FADE_TIME(1000ms)一个透明度循环的持续时间,STAGGER_TIME(100ms)连续元素之间的延迟增量。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjsindex 66d365d831..77674d744a 100644--- a/packages/core/src/Slider/Slider.doc.mjs+++ b/packages/core/src/Slider/Slider.doc.mjs@@ -2,19 +2,8 @@export const docs = {name: 'Slider',- description:- 'A slider component for selecting numeric values or ranges with full keyboard and pointer support.', keywords: ["slider","range","slidebar","trackbar","scrubber","knob","thumb","rangeslider"],- features: [- 'Single & range modes: Pass a `number` for single thumb, `[number, number]` for range',- 'Orientation: Supports `horizontal` and `vertical` layouts',- 'Value display: Tooltip (default), inline text, or none',- 'Tick marks: Optional marks at specified positions with labels',- 'Keyboard navigation: Arrow keys, Page Up/Down, Home/End',- 'Drag interaction: Pointer capture for smooth dragging',- 'Custom formatting: `formatValue` function for display and `aria-valuetext`',- 'Field integration: Uses `XDSField` for label, description, required/optional, and status messaging',- 'Accessible: Uses `role="slider"` with full ARIA attributes',- ], props: [+ keywords: ["slider","range","slidebar","trackbar","scrubber","knob","thumb","rangeslider"],+ props: [{name: 'label',type: 'string',@@ -140,45 +129,37 @@ export const docs = {{className: 'xds-slider-thumb', visualProps: ['orientation'], states: ['disabled']},],},- accessibility: [- 'Uses `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` on each thumb.',- 'The label is always rendered in the DOM for accessibility even when `isLabelHidden` is true.',- 'Tooltip display uses `XDSTooltip` with `delay={0}` and `focusTrigger="always"` so value is always visible on focus.',- ],- keyboard:- 'Arrow keys ±1 step, Page Up/Down ±10 steps, Home/End jump to min/max.',- notes: [- 'The ref is merged with an internal `trackRef` used for pointer position calculations.',- 'Pointer capture is used during drag for smooth interaction even when the cursor leaves the track.',- '`snapToStep` rounds to the nearest valid step value; `clamp` enforces min/max bounds.',- 'In range mode, the closest thumb to the click position is selected automatically.',- '`minStepsBetweenThumbs` enforces a minimum gap between range thumbs.',- 'Vertical orientation inverts the Y axis so that bottom = min and top = max.',- ],usage: {- summary: 'Allows a user to select a single number within a fixed range.',- content: `## When to use--- To help users explore and select a number within a constrained range.`,+ description:+ 'A slider component for selecting numeric values or ranges with full keyboard and pointer support. Use to help users explore and select a number within a constrained range.',+ features: [+ 'Single and range modes: pass a number for single thumb, [number, number] for range',+ 'Supports horizontal and vertical layouts',+ 'Value display: tooltip (default), inline text, or none',+ 'Tick marks at specified positions with optional labels',+ 'Custom value formatting via formatValue for display and aria-valuetext',+ 'Field integration via XDSField for label, description, required/optional, and status messaging',+ ],+ accessibility: [+ 'Uses `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` on each thumb.',+ 'The label is always rendered in the DOM for accessibility even when `isLabelHidden` is true.',+ 'Tooltip display uses `XDSTooltip` with `delay={0}` and `focusTrigger="always"` so value is always visible on focus.',+ 'Keyboard: Arrow keys \u00b11 step, Page Up/Down \u00b110 steps, Home/End jump to min/max.',+ ],+ notes: [+ 'The ref is merged with an internal `trackRef` used for pointer position calculations.',+ 'Pointer capture is used during drag for smooth interaction even when the cursor leaves the track.',+ '`snapToStep` rounds to the nearest valid step value; `clamp` enforces min/max bounds.',+ 'In range mode, the closest thumb to the click position is selected automatically.',+ '`minStepsBetweenThumbs` enforces a minimum gap between range thumbs.',+ 'Vertical orientation inverts the Y axis so that bottom = min and top = max.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Slider',- description:- '用于选择数值或范围的滑块组件,支持完整的键盘和指针交互。',- features: [- '单值和范围模式:传入 `number` 用于单滑块,`[number, number]` 用于范围',- '方向:支持 `horizontal` 和 `vertical` 布局',- '值显示:工具提示(默认)、内联文本或无',- '刻度标记:在指定位置的可选标记,带标签',- '键盘导航:方向键、Page Up/Down、Home/End',- '拖拽交互:指针捕获实现平滑拖拽',- '自定义格式化:`formatValue` 函数用于显示和 `aria-valuetext`',- '字段集成:使用 `XDSField` 提供标签、描述、必填/可选和状态消息',- '无障碍:使用 `role="slider"` 配合完整的 ARIA 属性',- ],props: [{name: 'label',@@ -305,21 +286,35 @@ export const docsZh = {{className: 'xds-slider-thumb', visualProps: ['orientation'], states: ['disabled']},],},- accessibility: [- '每个滑块使用 `role="slider"`,配合 `aria-valuenow`、`aria-valuemin`、`aria-valuemax` 和 `aria-valuetext`。',- '即使 `isLabelHidden` 为 true,标签也始终在 DOM 中渲染以确保无障碍可访问性。',- '工具提示显示使用 `XDSTooltip`,配合 `delay={0}` 和 `focusTrigger="always"`,使值在聚焦时始终可见。',- ],- keyboard:- '方向键 ±1 步,Page Up/Down ±10 步,Home/End 跳转到最小值/最大值。',- notes: [- 'ref 与内部的 `trackRef` 合并,用于指针位置计算。',- '拖拽期间使用指针捕获,即使光标离开轨道也能平滑交互。',- '`snapToStep` 四舍五入到最近的有效步进值;`clamp` 强制执行最小/最大值边界。',- '在范围模式下,自动选择距离点击位置最近的滑块。',- '`minStepsBetweenThumbs` 强制范围滑块之间保持最小间距。',- '垂直方向反转 Y 轴,使底部为最小值,顶部为最大值。',- ],+ usage: {+ description:+ '用于选择数值或范围的滑块组件,支持完整的键盘和指针交互。',+ features: [+ '单值和范围模式:传入 `number` 用于单滑块,`[number, number]` 用于范围',+ '方向:支持 `horizontal` 和 `vertical` 布局',+ '值显示:工具提示(默认)、内联文本或无',+ '刻度标记:在指定位置的可选标记,带标签',+ '键盘导航:方向键、Page Up/Down、Home/End',+ '拖拽交互:指针捕获实现平滑拖拽',+ '自定义格式化:`formatValue` 函数用于显示和 `aria-valuetext`',+ '字段集成:使用 `XDSField` 提供标签、描述、必填/可选和状态消息',+ '无障碍:使用 `role="slider"` 配合完整的 ARIA 属性',+ ],+ accessibility: [+ '每个滑块使用 `role="slider"`,配合 `aria-valuenow`、`aria-valuemin`、`aria-valuemax` 和 `aria-valuetext`。',+ '即使 `isLabelHidden` 为 true,标签也始终在 DOM 中渲染以确保无障碍可访问性。',+ '工具提示显示使用 `XDSTooltip`,配合 `delay={0}` 和 `focusTrigger="always"`,使值在聚焦时始终可见。',+ 'Keyboard: 方向键 ±1 步,Page Up/Down ±10 步,Home/End 跳转到最小值/最大值。',+ ],+ notes: [+ 'ref 与内部的 `trackRef` 合并,用于指针位置计算。',+ '拖拽期间使用指针捕获,即使光标离开轨道也能平滑交互。',+ '`snapToStep` 四舍五入到最近的有效步进值;`clamp` 强制执行最小/最大值边界。',+ '在范围模式下,自动选择距离点击位置最近的滑块。',+ '`minStepsBetweenThumbs` 强制范围滑块之间保持最小间距。',+ '垂直方向反转 Y 轴,使底部为最小值,顶部为最大值。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjsindex 338560afa7..a1e0838c99 100644--- a/packages/core/src/Spinner/Spinner.doc.mjs+++ b/packages/core/src/Spinner/Spinner.doc.mjs@@ -2,16 +2,7 @@export const docs = {name: 'Spinner',- description:- 'An animated loading indicator with optional visible label.',keywords: ["spinner","loader","loading","circular","progress","spin","activity","busy","indeterminate"],- features: [- 'Canvas Animation: Lightweight canvas-based spinner with smooth 360° rotation',- 'Size Variants: Three sizes (sm, md, lg) matching existing inline spinners',- 'Shade Support: Default shade for light backgrounds, onMedia for dark/accent backgrounds',- 'Label: Optional visible label (string or ReactNode) displayed below spinner',- 'Accessible: role="status" with aria-label; defaults to label text or "Loading"',- ],props: [{name: 'size',@@ -49,39 +40,31 @@ export const docs = {{className: 'xds-spinner', visualProps: ['size', 'shade']},],},- notes: [- 'Uses CSS border technique: three visible borders + one transparent for the gap.',- 'Animation: rotate(360deg) at 0.75s linear infinite.',- 'Color inherits from currentColor, controlled by shade styles using theme tokens.',- 'Element is a <span> with display: inline-block for inline composability.',- 'XDSSpinner is intentionally minimal — compose with layout and text components for full loading states.',- 'Size reference: sm = 10×10px / 3px border, md = 14×14px / 3px border, lg = 18×18px / 3px border.',- ],usage: {- summary: 'An animated loading indicator for indeterminate wait states.',- content: `## When to use--- Indicating an ongoing process with unknown duration.-- Inline loading states within buttons or other components.--## When NOT to use--- Content of known size is loading (use Skeleton instead).`,+ description:+ 'An animated loading indicator for indeterminate wait states with an optional visible label. Use for indicating ongoing processes with unknown duration or inline loading states within buttons and other components. For content of known size, use Skeleton instead.',+ features: [+ 'Three sizes (sm, md, lg) matching existing inline spinners',+ 'Shade support: default for light backgrounds, onMedia for dark/accent backgrounds',+ 'Optional visible label (string or ReactNode) displayed below spinner',+ ],+ accessibility: [+ 'Uses role="status" with aria-label; defaults to label text or "Loading"',+ ],+ notes: [+ 'Uses CSS border technique: three visible borders + one transparent for the gap.',+ 'Animation: rotate(360deg) at 0.75s linear infinite.',+ 'Color inherits from currentColor, controlled by shade styles using theme tokens.',+ 'Element is a <span> with display: inline-block for inline composability.',+ 'XDSSpinner is intentionally minimal — compose with layout and text components for full loading states.',+ 'Size reference: sm = 10×10px / 3px border, md = 14×14px / 3px border, lg = 18×18px / 3px border.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Spinner',- description:- '带有可选可见标签的动画加载指示器。',- features: [- 'Canvas 动画:基于 Canvas 的轻量级旋转器,平滑 360° 旋转',- '尺寸变体:三种尺寸(sm、md、lg),与现有内联旋转器匹配',- '色调支持:默认色调用于浅色背景,onMedia 用于深色/强调色背景',- '标签:可选可见标签(字符串或 ReactNode),显示在旋转器下方',- '无障碍:role="status" 与 aria-label;默认为标签文本或 "Loading"',- ],props: [{name: 'size',@@ -118,14 +101,25 @@ export const docsZh = {{className: 'xds-spinner', visualProps: ['size', 'shade']},],},- notes: [- '使用 CSS 边框技术:三条可见边框 + 一条透明边框形成缺口。',- '动画:rotate(360deg),0.75s linear infinite。',- '颜色继承自 currentColor,通过使用主题令牌的色调样式控制。',- '元素是一个 <span>,设置 display: inline-block 以支持内联组合。',- 'XDSSpinner 设计上保持最小化——与布局和文本组件组合以实现完整的加载状态。',- '尺寸参考:sm = 10×10px / 3px 边框,md = 14×14px / 3px 边框,lg = 18×18px / 3px 边框。',- ],+ usage: {+ description:+ '带有可选可见标签的动画加载指示器。',+ features: [+ 'Canvas 动画:基于 Canvas 的轻量级旋转器,平滑 360° 旋转',+ '尺寸变体:三种尺寸(sm、md、lg),与现有内联旋转器匹配',+ '色调支持:默认色调用于浅色背景,onMedia 用于深色/强调色背景',+ '标签:可选可见标签(字符串或 ReactNode),显示在旋转器下方',+ '无障碍:role="status" 与 aria-label;默认为标签文本或 "Loading"',+ ],+ notes: [+ '使用 CSS 边框技术:三条可见边框 + 一条透明边框形成缺口。',+ '动画:rotate(360deg),0.75s linear infinite。',+ '颜色继承自 currentColor,通过使用主题令牌的色调样式控制。',+ '元素是一个 <span>,设置 display: inline-block 以支持内联组合。',+ 'XDSSpinner 设计上保持最小化——与布局和文本组件组合以实现完整的加载状态。',+ '尺寸参考:sm = 10×10px / 3px 边框,md = 14×14px / 3px 边框,lg = 18×18px / 3px 边框。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjsindex cc769d31de..6f3ea3b0e4 100644--- a/packages/core/src/Stack/Stack.doc.mjs+++ b/packages/core/src/Stack/Stack.doc.mjs@@ -2,25 +2,13 @@export const docs = {name: 'Stack',- description:- 'Stack layout primitives for arranging items in horizontal or vertical sequences using flexbox-based layout with themed spacing tokens.', keywords: ["stack","hstack","vstack","flexbox","flex","spacing","gap","horizontal","vertical","row","column"],- features: [- 'Horizontal (XDSHStack) and vertical (XDSVStack) stacking',- 'Themed spacing via gap tokens from the design system spacing scale',- 'Individual item control via XDSStackItem',- 'Polymorphic rendering support via the element prop',- 'Low-level StyleX utilities (stack, stackItem) for advanced use cases',- ], theming: {+ keywords: ["stack","hstack","vstack","flexbox","flex","spacing","gap","horizontal","vertical","row","column"],+ theming: {targets: [{className: 'xds-stack', visualProps: ['direction', 'gap', 'wrap']},{className: 'xds-stack-item', visualProps: ['size']},],},- notes: [- "Import from '@xds/core/Layout': XDSHStack, XDSVStack, XDSStackItem, stack, stackItem.",- 'The gap prop accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',- 'stack and stackItem are low-level StyleX utilities for advanced cases where the component API is insufficient.',- ],components: [{name: 'XDSHStack',@@ -182,33 +170,32 @@ export const docs = {},],usage: {- summary: 'Layout primitives for arranging items in horizontal or vertical sequences using flexbox.',+ description:+ 'Stack provides layout primitives for arranging items in horizontal or vertical sequences. It uses flexbox-based layout with themed spacing tokens from the design system.',+ features: [+ 'Horizontal (XDSHStack) and vertical (XDSVStack) stacking',+ 'Themed spacing via gap tokens from the design system spacing scale',+ 'Individual item control via XDSStackItem',+ 'Polymorphic rendering support via the element prop',+ 'Low-level StyleX utilities (stack, stackItem) for advanced use cases',+ ],+ notes: [+ "Import from '@xds/core/Layout': XDSHStack, XDSVStack, XDSStackItem, stack, stackItem.",+ 'The gap prop accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.',+ 'stack and stackItem are low-level StyleX utilities for advanced cases where the component API is insufficient.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Stack',- description:- '堆叠布局原语,使用基于 flexbox 的布局和主题化间距令牌,将元素排列为水平或垂直序列。',- features: [- '水平(XDSHStack)和垂直(XDSVStack)堆叠',- '通过设计系统间距比例中的 gap 令牌实现主题化间距',- '通过 XDSStackItem 实现单个元素的控制',- '通过 element 属性支持多态渲染',- '底层 StyleX 工具函数(stack、stackItem)用于高级用例',- ],theming: {targets: [{className: 'xds-stack', visualProps: ['direction', 'gap', 'wrap']},{className: 'xds-stack-item', visualProps: ['size']},],},- notes: [- "从 '@xds/core/Layout' 导入:XDSHStack、XDSVStack、XDSStackItem、stack、stackItem。",- 'gap 属性接受数值间距步进:0、0.5、1、1.5、2、3、4、5、6、8、10。',- 'stack 和 stackItem 是底层 StyleX 工具函数,用于组件 API 无法满足需求的高级场景。',- ],components: [{name: 'XDSHStack',@@ -370,6 +357,22 @@ export const docsZh = {],},],+ usage: {+ description:+ '堆叠布局原语,使用基于 flexbox 的布局和主题化间距令牌,将元素排列为水平或垂直序列。',+ features: [+ '水平(XDSHStack)和垂直(XDSVStack)堆叠',+ '通过设计系统间距比例中的 gap 令牌实现主题化间距',+ '通过 XDSStackItem 实现单个元素的控制',+ '通过 element 属性支持多态渲染',+ '底层 StyleX 工具函数(stack、stackItem)用于高级用例',+ ],+ notes: [+ "从 '@xds/core/Layout' 导入:XDSHStack、XDSVStack、XDSStackItem、stack、stackItem。",+ 'gap 属性接受数值间距步进:0、0.5、1、1.5、2、3、4、5、6、8、10。',+ 'stack 和 stackItem 是底层 StyleX 工具函数,用于组件 API 无法满足需求的高级场景。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjsindex fe6b277bd5..afacaeda3f 100644--- a/packages/core/src/StatusDot/StatusDot.doc.mjs+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs@@ -2,16 +2,7 @@export const docs = {name: 'StatusDot',- description:- 'A small colored dot indicator for status display (online/offline, severity, etc).',keywords: ["statusdot","dot","indicator","status","signal","presence","availability","online","pip"],- features: [- 'Five semantic color variants: positive, warning, negative, info, neutral',- 'Single size: 8px',- 'Optional pulse animation that respects prefers-reduced-motion',- 'Accessible — renders as <span role="img" aria-label={label}> for screen reader support',- 'Not focusable (decorative indicator)',- ],props: [{name: 'variant',@@ -38,42 +29,31 @@ export const docs = {description:'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',},- ], theming: {+ ],+ theming: {targets: [{className: 'xds-statusdot', visualProps: ['variant']},],},- accessibility: [- 'Renders as <span role="img" aria-label={label}> for screen reader support.',- 'Not focusable — intended as a decorative indicator only.',- 'isPulsing animation respects prefers-reduced-motion: reduce.',- ],usage: {- summary: 'A small dot indicating status through semantic colors, often paired with a text label.',- content: `## When to use--- Indicating status with semantic colors (e.g. active, inactive, warning, error).-- Pairing with text labels to provide visual status cues.--## Best practices--- Do: Pair with a text label to ensure the status is accessible and clear.-- Don't: Rely on color alone \u2014 always provide a text label for context.`,+ description:+ 'StatusDot is a small colored dot indicator for displaying status through semantic colors such as online/offline or severity levels. Pair it with a text label to ensure the status is accessible, as color alone should not convey meaning.',+ features: [+ 'Five semantic color variants: positive, warning, negative, info, neutral',+ 'Single size: 8px',+ 'Optional pulse animation that respects prefers-reduced-motion',+ ],+ accessibility: [+ 'Renders as <span role="img" aria-label={label}> for screen reader support.',+ 'Not focusable — intended as a decorative indicator only.',+ 'isPulsing animation respects prefers-reduced-motion: reduce.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'StatusDot',- description:- '用于状态展示的小型彩色圆点指示器(在线/离线、严重程度等)。',- features: [- '五种语义颜色变体:positive(正面)、warning(警告)、negative(负面)、info(信息)、neutral(中性)',- '两种尺寸:sm(8px)和 md(10px)',- '可选的脉冲动画,尊重 prefers-reduced-motion 设置',- '无障碍支持 — 渲染为 <span role="img" aria-label={label}> 以支持屏幕阅读器',- '不可聚焦(装饰性指示器)',- ],props: [{name: 'variant',@@ -106,11 +86,22 @@ export const docsZh = {{className: 'xds-statusdot', visualProps: ['variant']},],},- accessibility: [- '渲染为 <span role="img" aria-label={label}> 以支持屏幕阅读器。',- '不可聚焦 — 仅作为装饰性指示器使用。',- 'isPulsing 动画尊重 prefers-reduced-motion: reduce 设置。',- ],+ usage: {+ description:+ '用于状态展示的小型彩色圆点指示器(在线/离线、严重程度等)。',+ features: [+ '五种语义颜色变体:positive(正面)、warning(警告)、negative(负面)、info(信息)、neutral(中性)',+ '两种尺寸:sm(8px)和 md(10px)',+ '可选的脉冲动画,尊重 prefers-reduced-motion 设置',+ '无障碍支持 — 渲染为 <span role="img" aria-label={label}> 以支持屏幕阅读器',+ '不可聚焦(装饰性指示器)',+ ],+ accessibility: [+ '渲染为 <span role="img" aria-label={label}> 以支持屏幕阅读器。',+ '不可聚焦 — 仅作为装饰性指示器使用。',+ 'isPulsing 动画尊重 prefers-reduced-motion: reduce 设置。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjsindex d57bcd781a..8b177086e6 100644--- a/packages/core/src/Switch/Switch.doc.mjs+++ b/packages/core/src/Switch/Switch.doc.mjs@@ -2,21 +2,8 @@export const docs = {name: 'Switch',- description:- 'A toggle switch component for boolean values with integrated label support.',keywords: ["switch","toggle","onoff","flipswitch","boolean","toggleswitch"],- features: [- 'Boolean toggle — fixed 40x24px track with animated 16px (off) / 20px (on) thumb',- 'Label integration — uses XDSFieldLabel for accessible labels with optional tooltip and icon',- 'Label position — label can appear before or after the switch via labelPosition',- 'Label spacing — supports spread layout to push label and switch to opposite ends',- 'Description — optional description text displayed below the label',- 'Optional/required indicators — visual markers for field status',- 'Status messages — error, warning, success, or info message boxes below the switch',- 'Async action support — onChangeAction with optimistic UI and built-in loading spinner',- 'Accessibility — native checkbox with role="switch", aria-describedby, aria-invalid, aria-busy',- 'Reduced motion — respects prefers-reduced-motion for track and thumb transitions',- ], props: [+ props: [{name: 'ref',type: 'React.Ref<HTMLInputElement>',@@ -134,52 +121,43 @@ export const docs = {{className: 'xds-switch-field', visualProps: ['labelPosition', 'labelSpacing']},],},- accessibility: [- 'Renders a native <input type="checkbox" role="switch"> for correct switch semantics',- 'Label is always associated via htmlFor/id even when visually hidden',- 'Description text is linked via aria-describedby on the input element',- 'Status messages are linked via aria-describedby; aria-invalid is set when status type is "error"',- 'aria-busy is set during async onChangeAction execution',- ],- keyboard: 'Space toggles the switch; Tab/Shift+Tab moves focus in and out',- notes: [- 'Fixed dimensions: 40px width, 24px height, 16px thumb (off), 20px thumb (on)',- 'Track and thumb use CSS transitions for background-color, transform, width, and height',- 'Hover tints are applied via stylex.when.ancestor with a @media (hover: hover) guard',- 'onChangeAction uses React useTransition and useOptimistic for seamless async toggling',- 'labelPosition="start" with labelSpacing="spread" produces a settings panel style layout',- 'Follows the same patterns as XDSCheckboxInput for structural consistency',- 'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling',- 'Track and thumb transitions respect prefers-reduced-motion (0s duration when reduced motion preferred)',- ],usage: {- summary: 'Conveys a binary on/off state that takes effect immediately.',- content: `## When to use--- Settings that take effect immediately upon toggling.--## When NOT to use--- When changes require a separate submit step \u2014 use a checkbox instead.`,+ description:+ 'A toggle switch component for boolean values with integrated label support that conveys an on/off state taking effect immediately. Use for settings that apply instantly upon toggling; for changes requiring a separate submit step, use a checkbox instead.',+ features: [+ 'Boolean toggle with animated thumb for visual on/off states',+ 'Label integration — uses XDSFieldLabel for accessible labels with optional tooltip and icon',+ 'Label position — label can appear before or after the switch via labelPosition',+ 'Label spacing — supports spread layout to push label and switch to opposite ends',+ 'Description — optional description text displayed below the label',+ 'Optional/required indicators — visual markers for field status',+ 'Status messages — error, warning, success, or info message boxes below the switch',+ 'Async action support — onChangeAction with optimistic UI and built-in loading spinner',+ 'Reduced motion — respects prefers-reduced-motion for track and thumb transitions',+ ],+ accessibility: [+ 'Renders a native <input type="checkbox" role="switch"> for correct switch semantics',+ 'Label is always associated via htmlFor/id even when visually hidden',+ 'Description text is linked via aria-describedby on the input element',+ 'Status messages are linked via aria-describedby; aria-invalid is set when status type is "error"',+ 'aria-busy is set during async onChangeAction execution',+ 'Keyboard: Space toggles the switch; Tab/Shift+Tab moves focus in and out',+ ],+ notes: [+ 'Fixed dimensions: 40px width, 24px height, 16px thumb (off), 20px thumb (on)',+ 'Track and thumb use CSS transitions for background-color, transform, width, and height',+ 'Hover tints are applied via stylex.when.ancestor with a @media (hover: hover) guard',+ 'onChangeAction uses React useTransition and useOptimistic for seamless async toggling',+ 'Follows the same patterns as XDSCheckboxInput for structural consistency',+ 'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling',+ 'Track and thumb transitions respect prefers-reduced-motion (0s duration when reduced motion preferred)',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Switch',- description:- '用于布尔值的开关切换组件,集成标签支持。',- features: [- '布尔值切换 — 固定 40x24px 轨道,带动画效果的 16px(关闭)/ 20px(开启)滑块',- '标签集成 — 使用 XDSFieldLabel 实现无障碍标签,支持可选的工具提示和图标',- '标签位置 — 通过 labelPosition 可将标签放置在开关前面或后面',- '标签间距 — 支持分散布局,将标签和开关推到容器两端',- '描述 — 可选的描述文本,显示在标签下方',- '可选/必填指示器 — 字段状态的可视标记',- '状态消息 — 开关下方的错误、警告、成功或信息消息框',- '异步操作支持 — onChangeAction 支持乐观 UI 和内置加载旋转器',- '无障碍 — 原生复选框,具有 role="switch"、aria-describedby、aria-invalid、aria-busy',- ],props: [{name: 'ref',@@ -298,22 +276,37 @@ export const docsZh = {{className: 'xds-switch-field', visualProps: ['labelPosition', 'labelSpacing']},],},- accessibility: [- '渲染原生 <input type="checkbox" role="switch"> 以确保正确的开关语义',- '标签始终通过 htmlFor/id 关联,即使视觉上被隐藏',- '描述文本通过输入元素上的 aria-describedby 关联',- '状态消息通过 aria-describedby 关联;当状态类型为 "error" 时设置 aria-invalid',- '异步 onChangeAction 执行期间设置 aria-busy',- ],- keyboard: '空格键切换开关;Tab/Shift+Tab 移入和移出焦点',- notes: [- '固定尺寸:40px 宽,24px 高,16px 滑块(关闭),20px 滑块(开启)',- '轨道和滑块使用 CSS 过渡实现 background-color、transform、width 和 height 的动画',- '悬停色调通过 stylex.when.ancestor 应用,带有 @media (hover: hover) 守卫',- 'onChangeAction 使用 React useTransition 和 useOptimistic 实现无缝异步切换',- 'labelPosition="start" 配合 labelSpacing="spread" 生成设置面板样式的布局',- '遵循与 XDSCheckboxInput 相同的模式以保持结构一致性',- ],+ usage: {+ description:+ '用于布尔值的开关切换组件,集成标签支持。',+ features: [+ '布尔值切换 — 固定 40x24px 轨道,带动画效果的 16px(关闭)/ 20px(开启)滑块',+ '标签集成 — 使用 XDSFieldLabel 实现无障碍标签,支持可选的工具提示和图标',+ '标签位置 — 通过 labelPosition 可将标签放置在开关前面或后面',+ '标签间距 — 支持分散布局,将标签和开关推到容器两端',+ '描述 — 可选的描述文本,显示在标签下方',+ '可选/必填指示器 — 字段状态的可视标记',+ '状态消息 — 开关下方的错误、警告、成功或信息消息框',+ '异步操作支持 — onChangeAction 支持乐观 UI 和内置加载旋转器',+ '无障碍 — 原生复选框,具有 role="switch"、aria-describedby、aria-invalid、aria-busy',+ ],+ accessibility: [+ '渲染原生 <input type="checkbox" role="switch"> 以确保正确的开关语义',+ '标签始终通过 htmlFor/id 关联,即使视觉上被隐藏',+ '描述文本通过输入元素上的 aria-describedby 关联',+ '状态消息通过 aria-describedby 关联;当状态类型为 "error" 时设置 aria-invalid',+ '异步 onChangeAction 执行期间设置 aria-busy',+ 'Keyboard: 空格键切换开关;Tab/Shift+Tab 移入和移出焦点',+ ],+ notes: [+ '固定尺寸:40px 宽,24px 高,16px 滑块(关闭),20px 滑块(开启)',+ '轨道和滑块使用 CSS 过渡实现 background-color、transform、width 和 height 的动画',+ '悬停色调通过 stylex.when.ancestor 应用,带有 @media (hover: hover) 守卫',+ 'onChangeAction 使用 React useTransition 和 useOptimistic 实现无缝异步切换',+ 'labelPosition="start" 配合 labelSpacing="spread" 生成设置面板样式的布局',+ '遵循与 XDSCheckboxInput 相同的模式以保持结构一致性',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjsindex d158d37427..338da7b775 100644--- a/packages/core/src/TabList/TabList.doc.mjs+++ b/packages/core/src/TabList/TabList.doc.mjs@@ -2,19 +2,8 @@export const docs = {name: 'TabList',- description:- 'Tab navigation components with overflow menu support, rendering as a semantic nav landmark with button or anchor tab items.', keywords: ["tabs","tabbar","tabstrip","navigation","tabpanel","tabgroup","segmented","navtabs","tab"],- features: [- 'Context-based communication: XDSTabListContext passes value/onChange/size from XDSTabList to children',- 'Single-responsibility XDSTab: renders as <button> or <a> (when href is provided) in the nav',- 'Overflow menu: XDSTabMenu accepts an options prop and renders menu items internally from the dropdown',- "Dynamic trigger label: menu trigger shows the selected option's label when one is active",- "Menu heading: dropdown includes an XDSDivider with the menu's label as a separator heading",- 'Selection indicator: selected menu items show a checkmark icon (matching XDSSelector pattern)',- 'Keyboard navigation: Tab between items, ArrowUp/Down in menu, Home/End, Escape closes menu (via useListFocus)',- 'Hover state: unselected tabs show a gray underline on hover; no background hover overlay',- 'Accessibility: nav landmark, aria-current="page" on selected tabs, role="menu" + aria-label on dropdown, aria-controls connecting trigger to menu, role="menuitem" for items, role="separator" for heading divider',- ], theming: {+ keywords: ["tabs","tabbar","tabstrip","navigation","tabpanel","tabgroup","segmented","navtabs","tab"],+ theming: {targets: [{className: 'xds-tab-list', visualProps: ['size']},{className: 'xds-tab', states: ['selected']},@@ -24,27 +13,6 @@ export const docs = {{className: 'xds-tab-menu-item'},],},- accessibility: [- 'XDSTabList renders as a <nav> landmark with aria-label="Tabs"',- 'XDSTab renders as <button> or <a> — uses navigation pattern, not role="tab"',- 'Selected XDSTab has aria-current="page"',- 'XDSTabMenu trigger has aria-haspopup="menu", aria-expanded, and aria-controls pointing to the menu element',- 'XDSTabMenu dropdown has role="menu" and aria-label matching the label prop',- 'XDSTabMenu heading divider has role="separator"',- 'XDSTabMenu items have role="menuitem" and aria-current="true" when selected',- ],- keyboard:- 'Tab moves focus between tab items; within the XDSTabMenu dropdown: ArrowUp/ArrowDown navigate items (wrapping), Home/End jump to first/last item, Escape closes the menu.',- notes: [- 'XDSTab renders as <button> by default and as <a> when href is provided',- 'XDSTabMenu renders menu items internally from the options prop — no child composition',- 'Trigger label derives from options.find(o => o.value === ctx.value)?.label ?? label',- 'Menu trigger underline scopes to the label text span only, not the chevron icon',- 'Icons on menu items render via XDSIcon with size="sm" and color="secondary"',- 'Selected menu items show a CheckIcon checkmark (matching XDSSelector pattern)',- 'hasDivider on XDSTabList controls the bottom border (default: off)',- 'Size uses sizeVars tokens for tab heights (sm/md/lg)',- ],components: [{name: 'XDSTabList',@@ -160,15 +128,37 @@ export const docs = {},],usage: {- summary: 'Organizes content into tabbed sections for quick access to categorized information.',- content: `## When to use--- To organize large amounts of content into categories accessible above the fold.--## Best practices--- Two styles are available: underlined tabs and header tabs.-- Tab items overflow into a "more" menu when horizontal space is limited.`,+ description:+ 'TabList provides tab navigation with overflow menu support, organizing content into tabbed sections for quick access to categorized information. It renders as a semantic nav landmark with button or anchor tab items, and overflows into a "more" menu when horizontal space is limited.',+ features: [+ 'Single-responsibility XDSTab: renders as <button> or <a> (when href is provided) in the nav',+ 'Overflow menu: XDSTabMenu accepts an options prop and renders menu items internally from the dropdown',+ "Dynamic trigger label: menu trigger shows the selected option's label when one is active",+ "Menu heading: dropdown includes an XDSDivider with the menu's label as a separator heading",+ 'Selection indicator: selected menu items show a checkmark icon (matching XDSSelector pattern)',+ 'Hover state: unselected tabs show a gray underline on hover; no background hover overlay',+ ],+ accessibility: [+ 'XDSTabList renders as a <nav> landmark with aria-label="Tabs"',+ 'XDSTab renders as <button> or <a> — uses navigation pattern, not role="tab"',+ 'Selected XDSTab has aria-current="page"',+ 'XDSTabMenu trigger has aria-haspopup="menu", aria-expanded, and aria-controls pointing to the menu element',+ 'XDSTabMenu dropdown has role="menu" and aria-label matching the label prop',+ 'XDSTabMenu heading divider has role="separator"',+ 'XDSTabMenu items have role="menuitem" and aria-current="true" when selected',+ 'Keyboard: Tab moves focus between tab items; within XDSTabMenu dropdown: ArrowUp/ArrowDown navigate items (wrapping), Home/End jump to first/last item, Escape closes the menu',+ ],+ notes: [+ 'XDSTabListContext passes value/onChange/size from XDSTabList to children',+ 'XDSTab renders as <button> by default and as <a> when href is provided',+ 'XDSTabMenu renders menu items internally from the options prop — no child composition',+ 'Trigger label derives from options.find(o => o.value === ctx.value)?.label ?? label',+ 'Menu trigger underline scopes to the label text span only, not the chevron icon',+ 'Icons on menu items render via XDSIcon with size="sm" and color="secondary"',+ 'Selected menu items show a CheckIcon checkmark (matching XDSSelector pattern)',+ 'hasDivider on XDSTabList controls the bottom border (default: off)',+ 'Size uses sizeVars tokens for tab heights (sm/md/lg)',+ ],anatomy: [{name: 'Left Content', required: false, description: 'Most important area; hugs content width.'},{name: 'Center-Fill Content', required: false, description: 'Stretches to fill available space.'},@@ -180,19 +170,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'TabList',- description:- '支持溢出菜单的标签页导航组件,渲染为语义化的 nav 地标元素,包含按钮或锚点标签项。',- features: [- '基于上下文通信:XDSTabListContext 将 value/onChange/size 从 XDSTabList 传递给子组件',- '单一职责的 XDSTab:在 nav 中渲染为 <button> 或 <a>(当提供 href 时)',- '溢出菜单:XDSTabMenu 接受 options 属性,并从下拉菜单内部渲染菜单项',- '动态触发器标签:当某个选项处于选中状态时,菜单触发器显示该选项的标签',- '菜单标题:下拉菜单包含一个以菜单标签作为分隔标题的 XDSDivider',- '选中指示器:选中的菜单项显示勾选图标(与 XDSSelector 模式一致)',- '键盘导航:Tab 键在项目间移动焦点,ArrowUp/ArrowDown 在菜单中导航,Home/End 跳转,Escape 关闭菜单(通过 useListFocus 实现)',- '悬停状态:未选中的标签在悬停时显示灰色下划线;无背景悬停遮罩',- '无障碍:nav 地标元素,选中标签上的 aria-current="page",下拉菜单的 role="menu" + aria-label,aria-controls 连接触发器与菜单,菜单项的 role="menuitem",标题分隔线的 role="separator"',- ],theming: {targets: [{className: 'xds-tab-list', visualProps: ['size']},@@ -203,27 +180,6 @@ export const docsZh = {{className: 'xds-tab-menu-item'},],},- accessibility: [- 'XDSTabList 渲染为带有 aria-label="Tabs" 的 <nav> 地标元素',- 'XDSTab 渲染为 <button> 或 <a> — 使用导航模式,而非 role="tab"',- '选中的 XDSTab 具有 aria-current="page"',- 'XDSTabMenu 触发器具有 aria-haspopup="menu"、aria-expanded 和指向菜单元素的 aria-controls',- 'XDSTabMenu 下拉菜单具有 role="menu" 和与 label 属性匹配的 aria-label',- 'XDSTabMenu 标题分隔线具有 role="separator"',- 'XDSTabMenu 菜单项具有 role="menuitem",选中时具有 aria-current="true"',- ],- keyboard:- 'Tab 键在标签项之间移动焦点;在 XDSTabMenu 下拉菜单中:ArrowUp/ArrowDown 导航菜单项(循环),Home/End 跳转到第一项/最后一项,Escape 关闭菜单。',- notes: [- 'XDSTab 默认渲染为 <button>,当提供 href 时渲染为 <a>',- 'XDSTabMenu 通过 options 属性在内部渲染菜单项 — 不使用子组件组合',- '触发器标签来源于 options.find(o => o.value === ctx.value)?.label ?? label',- '菜单触发器下划线仅作用于标签文本范围,不包含箭头图标',- '菜单项上的图标通过 XDSIcon 渲染,尺寸为 "sm",颜色为 "secondary"',- '选中的菜单项显示 CheckIcon 勾选标记(与 XDSSelector 模式一致)',- 'XDSTabList 上的 hasDivider 控制底部边框(默认关闭)',- 'Size 使用 sizeVars 令牌控制标签高度(sm/md/lg)',- ],components: [{name: 'XDSTabList',@@ -339,6 +295,41 @@ export const docsZh = {],},],+ usage: {+ description:+ '支持溢出菜单的标签页导航组件,渲染为语义化的 nav 地标元素,包含按钮或锚点标签项。',+ features: [+ '基于上下文通信:XDSTabListContext 将 value/onChange/size 从 XDSTabList 传递给子组件',+ '单一职责的 XDSTab:在 nav 中渲染为 <button> 或 <a>(当提供 href 时)',+ '溢出菜单:XDSTabMenu 接受 options 属性,并从下拉菜单内部渲染菜单项',+ '动态触发器标签:当某个选项处于选中状态时,菜单触发器显示该选项的标签',+ '菜单标题:下拉菜单包含一个以菜单标签作为分隔标题的 XDSDivider',+ '选中指示器:选中的菜单项显示勾选图标(与 XDSSelector 模式一致)',+ '键盘导航:Tab 键在项目间移动焦点,ArrowUp/ArrowDown 在菜单中导航,Home/End 跳转,Escape 关闭菜单(通过 useListFocus 实现)',+ '悬停状态:未选中的标签在悬停时显示灰色下划线;无背景悬停遮罩',+ '无障碍:nav 地标元素,选中标签上的 aria-current="page",下拉菜单的 role="menu" + aria-label,aria-controls 连接触发器与菜单,菜单项的 role="menuitem",标题分隔线的 role="separator"',+ ],+ accessibility: [+ 'XDSTabList 渲染为带有 aria-label="Tabs" 的 <nav> 地标元素',+ 'XDSTab 渲染为 <button> 或 <a> — 使用导航模式,而非 role="tab"',+ '选中的 XDSTab 具有 aria-current="page"',+ 'XDSTabMenu 触发器具有 aria-haspopup="menu"、aria-expanded 和指向菜单元素的 aria-controls',+ 'XDSTabMenu 下拉菜单具有 role="menu" 和与 label 属性匹配的 aria-label',+ 'XDSTabMenu 标题分隔线具有 role="separator"',+ 'XDSTabMenu 菜单项具有 role="menuitem",选中时具有 aria-current="true"',+ 'Keyboard: Tab 键在标签项之间移动焦点;在 XDSTabMenu 下拉菜单中:ArrowUp/ArrowDown 导航菜单项(循环),Home/End 跳转到第一项/最后一项,Escape 关闭菜单。',+ ],+ notes: [+ 'XDSTab 默认渲染为 <button>,当提供 href 时渲染为 <a>',+ 'XDSTabMenu 通过 options 属性在内部渲染菜单项 — 不使用子组件组合',+ '触发器标签来源于 options.find(o => o.value === ctx.value)?.label ?? label',+ '菜单触发器下划线仅作用于标签文本范围,不包含箭头图标',+ '菜单项上的图标通过 XDSIcon 渲染,尺寸为 "sm",颜色为 "secondary"',+ '选中的菜单项显示 CheckIcon 勾选标记(与 XDSSelector 模式一致)',+ 'XDSTabList 上的 hasDivider 控制底部边框(默认关闭)',+ 'Size 使用 sizeVars 令牌控制标签高度(sm/md/lg)',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjsindex fd80533576..8ed8be128d 100644--- a/packages/core/src/Table/Table.doc.mjs+++ b/packages/core/src/Table/Table.doc.mjs@@ -2,27 +2,8 @@export const docs = {name: 'Table',- description:- 'Data-driven table with rich cell content via renderCell. Compose cells with XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives. XDSBaseTable provides the unstyled structural core with a composable plugin pipeline.', keywords: ["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],- features: [- 'Data-driven rendering — pass data + columns, rows render automatically',- 'Rich cell content via renderCell — compose XDS components (XDSBadge, XDSStatusDot, XDSText, XDSAvatar) inside table cells',- 'Children mode — compose XDSTableRow/XDSTableCell directly for manual layouts',- 'Plugin system — extend table behavior with composable transform plugins',- 'Density variants: compact, balanced, spacious',- 'Divider styles: rows, columns, grid, none',- 'Column alignment: start (default), center, end — per-column via align prop',- 'Row vertical alignment: middle (default), top, bottom — table-level via verticalAlign prop',- 'Striped even rows and hover highlight via XDSTableContext',- 'Selection via useXDSTableSelectionState + useXDSTableSelection — checkboxes, select-all, disabled row handling',- 'Sorting via useXDSTableSortable — single or multi-column sort with header indicators',- 'Pagination via useXDSTablePagination — client-side, server-side, or cursor-based with auto-rendered controls',- 'Column visibility via useXDSTableColumnSettings — toggle, reorder, and reset columns with XDSMultiSelector integration',- 'Column resize via useXDSTableColumnResize — drag-to-resize column headers with min/max constraints and proportional-preserving behavior',- 'Body rows memoized with custom comparison — only changed rows re-render',- 'Auto-generated columns from data object keys when columns prop is omitted',- 'Themeable via className — target .xds-base-table, .xds-table-row, .xds-table-cell, .xds-table-header-cell',- ], theming: {+ keywords: ["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],+ theming: {targets: [{className: 'xds-base-table'},{className: 'xds-table-row'},@@ -30,22 +11,6 @@ export const docs = {{className: 'xds-table-header-cell'},],},- accessibility: [- 'Selection plugin sets aria-selected on selected body rows',- 'Select-all and per-row checkboxes use visually hidden labels ("Select all rows", "Select row") via isLabelHidden',- 'Non-selectable rows (getIsItemSelectable returns false) render no checkbox',- 'Disabled rows (getIsItemEnabled returns false) render a disabled checkbox',- ],- notes: [- 'Two-layer design: XDSBaseTable provides unstyled structure and the plugin pipeline; XDSTable wraps it with XDSTableContext and styled sub-components.',- 'Styling is owned by components (XDSTableRow, XDSTableCell, XDSTableHeaderCell), not by plugins — each reads XDSTableContext to apply density, dividers, striped, and hover styles.',- 'XDSTable accepts plugins as a named Record<string, TablePlugin<T>> and converts to an ordered array internally; XDSBaseTable accepts an ordered array directly.',- 'The selection plugin uses useSyncExternalStore so only the row whose selection state changed re-renders. useXDSTableSelectionState manages the selection set and handles disabled/selectable row filtering for select-all automatically.',- 'useXDSTableColumnResize — drag-to-resize column headers. Proportional columns preserve their ratio when neighboring columns are resized. Pass columnWidths state and onColumnResizeEnd to control width persistence. Use minWidth/maxWidth for per-resize constraints.',- 'Body rows are memoized via React.memo with a custom comparison. For optimal performance, define columns outside the component or memoize them to avoid triggering full re-renders.',- 'Columns can be auto-generated from data keys using generateColumns(); column widths are expressed as proportional (fr-like) or fixed pixel values via the proportional() and pixel() helpers.',- 'tableProps on XDSBaseTable passes additional HTML attributes directly to the <table> element.',- ],components: [{name: 'XDSTable',@@ -443,23 +408,42 @@ export const docs = {},],usage: {- summary: 'Displays information with consistent data dimensionality in a grid format.',- content: `## When to use--- Simple tables for read-only data display.-- Data tables with column controls.-- Complex tables with control toolbars and detail panes.--## When NOT to use--- Consider lists or card-lists for simpler or inconsistent data.--## Best practices--- Do: Use row activation to show details in a side panel.-- Don't: Use row expansion for details (breaks column alignment).-- Layout presets: space-optimized (40px rows), balanced (56px default), content-optimized (dynamic height).-- Cell types: Content (main with media), Text, Value (right-aligned numbers), Status (dot + label).`,+ description:+ 'Table is a data-driven grid for displaying information with consistent data dimensionality. It supports rich cell content via renderCell, composing XDS components like XDSBadge, XDSStatusDot, and XDSAvatar inside cells. XDSBaseTable provides the unstyled structural core with a composable plugin pipeline for selection, sorting, pagination, and column management. Use lists or card-lists instead for simpler or inconsistent data.',+ features: [+ 'Data-driven rendering — pass data + columns, rows render automatically',+ 'Rich cell content via renderCell — compose XDS components (XDSBadge, XDSStatusDot, XDSText, XDSAvatar) inside table cells',+ 'Children mode — compose XDSTableRow/XDSTableCell directly for manual layouts',+ 'Plugin system — extend table behavior with composable transform plugins',+ 'Density variants: compact, balanced, spacious',+ 'Divider styles: rows, columns, grid, none',+ 'Column alignment: start (default), center, end — per-column via align prop',+ 'Row vertical alignment: middle (default), top, bottom — table-level via verticalAlign prop',+ 'Striped even rows and hover highlight via XDSTableContext',+ 'Selection via useXDSTableSelectionState + useXDSTableSelection — checkboxes, select-all, disabled row handling',+ 'Sorting via useXDSTableSortable — single or multi-column sort with header indicators',+ 'Pagination via useXDSTablePagination — client-side, server-side, or cursor-based with auto-rendered controls',+ 'Column visibility via useXDSTableColumnSettings — toggle, reorder, and reset columns with XDSMultiSelector integration',+ 'Column resize via useXDSTableColumnResize — drag-to-resize column headers with min/max constraints and proportional-preserving behavior',+ 'Auto-generated columns from data object keys when columns prop is omitted',+ 'Themeable via className — target .xds-base-table, .xds-table-row, .xds-table-cell, .xds-table-header-cell',+ ],+ accessibility: [+ 'Selection plugin sets aria-selected on selected body rows',+ 'Select-all and per-row checkboxes use visually hidden labels ("Select all rows", "Select row") via isLabelHidden',+ 'Non-selectable rows (getIsItemSelectable returns false) render no checkbox',+ 'Disabled rows (getIsItemEnabled returns false) render a disabled checkbox',+ ],+ notes: [+ 'Two-layer design: XDSBaseTable provides unstyled structure and the plugin pipeline; XDSTable wraps it with XDSTableContext and styled sub-components.',+ 'Styling is owned by components (XDSTableRow, XDSTableCell, XDSTableHeaderCell), not by plugins — each reads XDSTableContext to apply density, dividers, striped, and hover styles.',+ 'XDSTable accepts plugins as a named Record<string, TablePlugin<T>> and converts to an ordered array internally; XDSBaseTable accepts an ordered array directly.',+ 'The selection plugin uses useSyncExternalStore so only the row whose selection state changed re-renders. useXDSTableSelectionState manages the selection set and handles disabled/selectable row filtering for select-all automatically.',+ 'useXDSTableColumnResize — drag-to-resize column headers. Proportional columns preserve their ratio when neighboring columns are resized. Pass columnWidths state and onColumnResizeEnd to control width persistence. Use minWidth/maxWidth for per-resize constraints.',+ 'Body rows are memoized via React.memo with a custom comparison. For optimal performance, define columns outside the component or memoize them to avoid triggering full re-renders.',+ 'Columns can be auto-generated from data keys using generateColumns(); column widths are expressed as proportional (fr-like) or fixed pixel values via the proportional() and pixel() helpers.',+ 'tableProps on XDSBaseTable passes additional HTML attributes directly to the <table> element.',+ ],anatomy: [{name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},{name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},@@ -474,25 +458,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Table',- description:- '数据驱动的表格,通过 renderCell 实现丰富的单元格内容。使用 XDSBadge、XDSStatusDot、XDSText、XDSAvatar 和布局基础组件组合单元格。XDSBaseTable 提供无样式的结构核心,配合可组合的插件管道。',- features: [- '数据驱动渲染 — 传入数据和列定义,行自动渲染',- '通过 renderCell 实现丰富的单元格内容 — 在表格单元格中组合 XDS 组件(XDSBadge、XDSStatusDot、XDSText、XDSAvatar)',- '子元素模式 — 直接组合 XDSTableRow/XDSTableCell 实现手动布局',- '插件系统 — 通过可组合的转换插件扩展表格行为',- '密度变体:紧凑、均衡、宽松',- '分隔线样式:行、列、网格、无',- '通过 XDSTableContext 实现偶数行条纹和悬停高亮',- '通过 useXDSTableSelection 实现选择功能 — 复选框、全选、aria-selected',- '通过 useXDSTableSortable 实现排序 — 单列或多列排序,表头指示器',- '通过 useXDSTablePagination 实现分页 — 客户端、服务器端或游标分页,自动渲染控件',- '通过 useXDSTableColumnSettings 实现列可见性 — 切换、排序和重置列',- '通过 useXDSTableColumnResize 实现列调整 — 拖拽表头调整宽度,支持最小/最大约束和等比例调整',- '主体行使用自定义比较进行记忆化 — 仅重新渲染更改的行',- '省略 columns 属性时,自动从数据对象键生成列',- '通过 className 实现主题化 — 目标选择器:.xds-base-table、.xds-table-row、.xds-table-cell、.xds-table-header-cell',- ],theming: {targets: [{className: 'xds-base-table'},@@ -501,22 +466,6 @@ export const docsZh = {{className: 'xds-table-header-cell'},],},- accessibility: [- '选择插件在选中的主体行上设置 aria-selected',- '全选和每行复选框通过 isLabelHidden 使用视觉隐藏标签("Select all rows"、"Select row")',- '不可选择的行(getIsItemSelectable 返回 false)不渲染复选框',- '禁用的行(getIsItemEnabled 返回 false)渲染禁用状态的复选框',- ],- notes: [- '双层设计:XDSBaseTable 提供无样式结构和插件管道;XDSTable 使用 XDSTableContext 和带样式的子组件对其进行包装。',- '样式由组件(XDSTableRow、XDSTableCell、XDSTableHeaderCell)控制,而非插件 — 每个组件读取 XDSTableContext 来应用密度、分隔线、条纹和悬停样式。',- 'XDSTable 接受命名的 Record<string, TablePlugin<T>> 格式的插件,并在内部转换为有序数组;XDSBaseTable 直接接受有序数组。',- '选择插件使用 React Context,使 SelectAllCheckbox 和 SelectionRowCheckbox 独立于行内容重新渲染 — 仅当选择状态变化时更新 context 值。',- 'useXDSTableColumnResize — 拖拽表头调整列宽。比例列在调整相邻列时保持比例。传入 columnWidths 状态和 onColumnResizeEnd 控制宽度持久化。使用 minWidth/maxWidth 设置每次调整的约束范围。',- '主体行通过带有自定义比较的 React.memo 进行记忆化。为获得最佳性能,请在组件外部定义列或对其进行记忆化,以避免触发全量重新渲染。',- '可以使用 generateColumns() 从数据键自动生成列;列宽使用 proportional() 和 pixel() 辅助函数表达为比例值(类似 fr)或固定像素值。',- 'XDSBaseTable 上的 tableProps 将额外的 HTML 属性直接传递给 <table> 元素。',- ],components: [{name: 'XDSTable',@@ -829,6 +778,43 @@ export const docsZh = {],},],+ usage: {+ description:+ '数据驱动的表格,通过 renderCell 实现丰富的单元格内容。使用 XDSBadge、XDSStatusDot、XDSText、XDSAvatar 和布局基础组件组合单元格。XDSBaseTable 提供无样式的结构核心,配合可组合的插件管道。',+ features: [+ '数据驱动渲染 — 传入数据和列定义,行自动渲染',+ '通过 renderCell 实现丰富的单元格内容 — 在表格单元格中组合 XDS 组件(XDSBadge、XDSStatusDot、XDSText、XDSAvatar)',+ '子元素模式 — 直接组合 XDSTableRow/XDSTableCell 实现手动布局',+ '插件系统 — 通过可组合的转换插件扩展表格行为',+ '密度变体:紧凑、均衡、宽松',+ '分隔线样式:行、列、网格、无',+ '通过 XDSTableContext 实现偶数行条纹和悬停高亮',+ '通过 useXDSTableSelection 实现选择功能 — 复选框、全选、aria-selected',+ '通过 useXDSTableSortable 实现排序 — 单列或多列排序,表头指示器',+ '通过 useXDSTablePagination 实现分页 — 客户端、服务器端或游标分页,自动渲染控件',+ '通过 useXDSTableColumnSettings 实现列可见性 — 切换、排序和重置列',+ '通过 useXDSTableColumnResize 实现列调整 — 拖拽表头调整宽度,支持最小/最大约束和等比例调整',+ '主体行使用自定义比较进行记忆化 — 仅重新渲染更改的行',+ '省略 columns 属性时,自动从数据对象键生成列',+ '通过 className 实现主题化 — 目标选择器:.xds-base-table、.xds-table-row、.xds-table-cell、.xds-table-header-cell',+ ],+ accessibility: [+ '选择插件在选中的主体行上设置 aria-selected',+ '全选和每行复选框通过 isLabelHidden 使用视觉隐藏标签("Select all rows"、"Select row")',+ '不可选择的行(getIsItemSelectable 返回 false)不渲染复选框',+ '禁用的行(getIsItemEnabled 返回 false)渲染禁用状态的复选框',+ ],+ notes: [+ '双层设计:XDSBaseTable 提供无样式结构和插件管道;XDSTable 使用 XDSTableContext 和带样式的子组件对其进行包装。',+ '样式由组件(XDSTableRow、XDSTableCell、XDSTableHeaderCell)控制,而非插件 — 每个组件读取 XDSTableContext 来应用密度、分隔线、条纹和悬停样式。',+ 'XDSTable 接受命名的 Record<string, TablePlugin<T>> 格式的插件,并在内部转换为有序数组;XDSBaseTable 直接接受有序数组。',+ '选择插件使用 React Context,使 SelectAllCheckbox 和 SelectionRowCheckbox 独立于行内容重新渲染 — 仅当选择状态变化时更新 context 值。',+ 'useXDSTableColumnResize — 拖拽表头调整列宽。比例列在调整相邻列时保持比例。传入 columnWidths 状态和 onColumnResizeEnd 控制宽度持久化。使用 minWidth/maxWidth 设置每次调整的约束范围。',+ '主体行通过带有自定义比较的 React.memo 进行记忆化。为获得最佳性能,请在组件外部定义列或对其进行记忆化,以避免触发全量重新渲染。',+ '可以使用 generateColumns() 从数据键自动生成列;列宽使用 proportional() 和 pixel() 辅助函数表达为比例值(类似 fr)或固定像素值。',+ 'XDSBaseTable 上的 tableProps 将额外的 HTML 属性直接传递给 <table> 元素。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjsindex e1556058ad..181ef0263c 100644--- a/packages/core/src/Text/Text.doc.mjs+++ b/packages/core/src/Text/Text.doc.mjs@@ -2,27 +2,13 @@export const docs = {name: 'Text',- description:- 'Typography components for the XDS design system, including semantic body text, headings, and a wrapper for applying typography styles to native HTML.',- keywords: ["text","typography","label","paragraph","heading","caption","font","body","subtitle"], features: [- 'Semantic text types (body, large, label, supporting, code) driven by theme tokens',- 'Headings use native h1–h6 elements with optional aria-level override for decoupled visual vs document hierarchy',- 'Line-clamp truncation with automatic overflow-detecting tooltip',- 'Optical alignment (text-box-trim / capsize) for precise vertical rhythm',- 'Tabular number support for aligned numeric data',- 'All typography driven by CSS custom properties — fully themeable per-component',- ],+ keywords: ["text","typography","label","paragraph","heading","caption","font","body","subtitle"],theming: {targets: [{className: 'xds-heading', visualProps: ['level', 'color']},{className: 'xds-text', visualProps: ['type', 'color']},],},- accessibility: [- 'XDSHeading renders the correct semantic h1–h6 element based on the `level` prop.',- 'When `accessibilityLevel` differs from `level`, `aria-level` is set so screen readers announce the correct document outline position while preserving the visual style.',- 'Truncated text sets a native `title` attribute as a fallback, and also lazily renders an XDSTooltip for sighted keyboard users.',- ],components: [{name: 'XDSText',@@ -213,34 +199,33 @@ export const docs = {},],usage: {- summary: 'Typography components for body text, headings, and semantic text rendering.',+ description:+ 'Text provides typography components for the XDS design system, including semantic body text via XDSText, headings via XDSHeading, and a wrapper for applying typography styles to native HTML.',+ features: [+ 'Semantic text types (body, large, label, supporting, code) driven by theme tokens',+ 'Headings use native h1–h6 elements with optional aria-level override for decoupled visual vs document hierarchy',+ 'Line-clamp truncation with automatic overflow-detecting tooltip',+ 'Optical alignment (text-box-trim / capsize) for precise vertical rhythm',+ 'Tabular number support for aligned numeric data',+ 'All typography driven by CSS custom properties — fully themeable per-component',+ ],+ accessibility: [+ 'XDSHeading renders the correct semantic h1–h6 element based on the `level` prop.',+ 'When `accessibilityLevel` differs from `level`, `aria-level` is set so screen readers announce the correct document outline position while preserving the visual style.',+ 'Truncated text sets a native `title` attribute as a fallback, and also lazily renders an XDSTooltip for sighted keyboard users.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Text',- description:- 'XDS 设计系统的排版组件,包括语义化正文文本、标题以及将排版样式应用于原生 HTML 的包装器。',- features: [- '语义化文本类型(body、large、label、supporting、code),由主题令牌驱动',- '标题使用原生 h1–h6 元素,支持可选的 aria-level 覆盖,实现视觉层级与文档层级的解耦',- '行截断,带自动溢出检测工具提示',- '光学对齐(text-box-trim / capsize),实现精确的垂直节奏',- '表格数字支持,用于对齐的数值数据',- '所有排版由 CSS 自定义属性驱动 — 每个组件均可完全主题化',- ],theming: {targets: [{className: 'xds-heading', visualProps: ['level', 'color']},{className: 'xds-text', visualProps: ['type', 'color']},],},- accessibility: [- 'XDSHeading 根据 `level` 属性渲染正确的语义化 h1–h6 元素。',- '当 `accessibilityLevel` 与 `level` 不同时,会设置 `aria-level`,使屏幕阅读器播报正确的文档大纲位置,同时保留视觉样式。',- '截断文本设置原生 `title` 属性作为后备方案,并为有视力的键盘用户延迟渲染 XDSTooltip。',- ],components: [{name: 'XDSText',@@ -431,6 +416,23 @@ export const docsZh = {],},],+ usage: {+ description:+ 'XDS 设计系统的排版组件,包括语义化正文文本、标题以及将排版样式应用于原生 HTML 的包装器。',+ features: [+ '语义化文本类型(body、large、label、supporting、code),由主题令牌驱动',+ '标题使用原生 h1–h6 元素,支持可选的 aria-level 覆盖,实现视觉层级与文档层级的解耦',+ '行截断,带自动溢出检测工具提示',+ '光学对齐(text-box-trim / capsize),实现精确的垂直节奏',+ '表格数字支持,用于对齐的数值数据',+ '所有排版由 CSS 自定义属性驱动 — 每个组件均可完全主题化',+ ],+ accessibility: [+ 'XDSHeading 根据 `level` 属性渲染正确的语义化 h1–h6 元素。',+ '当 `accessibilityLevel` 与 `level` 不同时,会设置 `aria-level`,使屏幕阅读器播报正确的文档大纲位置,同时保留视觉样式。',+ '截断文本设置原生 `title` 属性作为后备方案,并为有视力的键盘用户延迟渲染 XDSTooltip。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjsindex 006eeb2ee6..19f77f9b14 100644--- a/packages/core/src/TextArea/TextArea.doc.mjs+++ b/packages/core/src/TextArea/TextArea.doc.mjs@@ -2,24 +2,8 @@export const docs = {name: 'TextArea',- description:- 'A multi-line text input component for collecting longer user input.', keywords: ["textarea","textfield","multiline","comment","message","autoresize","autosize","charlimit"],- features: [- 'Label support — required label for accessibility, can be visually hidden',- 'Description — optional text displayed between the label and textarea',- 'Optional/Required indicators — displays "Optional" or "Required" text with bullet separator',- 'Status variants — warning, error, and success states with colored borders and icons',- 'Character counter — displays current/max length when maxLength is set (does not enforce natively)',- 'Start icon — optional icon rendered inside the leading edge of the input',- 'Label tooltip — optional info icon with tooltip at the end of the label',- 'Loading state — shows a spinner and uses optimistic updates via useOptimistic',- 'Async action support — onChangeAction fires after onChange inside a React transition',- 'Disabled state — visual opacity and cursor changes, no interaction',- 'Accessible — label associated via htmlFor/id, aria-describedby, aria-required, aria-invalid, aria-busy',- 'Resizable — vertical resize enabled by default',- 'Spell check — browser spell checking enabled by default, configurable',- 'Reduced motion — respects prefers-reduced-motion for input wrapper transitions',- ], props: [+ keywords: ["textarea","textfield","multiline","comment","message","autoresize","autosize","charlimit"],+ props: [{name: 'ref',type: 'React.Ref<HTMLTextAreaElement>',@@ -169,58 +153,47 @@ export const docs = {{className: 'xds-textarea'},],},- accessibility: [- 'Label is always rendered in the DOM; use isLabelHidden to hide it visually while keeping it accessible.',- 'The textarea id is generated via useId and linked to its label via htmlFor, ensuring correct label association.',- 'aria-describedby is set to the description and/or status message IDs when those elements are present.',- 'aria-required="true" is set when isRequired is true.',- 'aria-invalid="true" is set when status.type is "error".',- 'aria-busy is set while an optimistic update or loading state is active.',- ],- notes: [- 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" takes precedence.',- 'The component uses useOptimistic for instant UI feedback when onChangeAction returns a Promise.',- 'Textarea has vertical resize enabled via CSS.',- 'Wraps XDSField for consistent label, description, and status message layout.',- 'The character counter uses optimisticValue and turns red when it exceeds maxLength.',- 'Interaction is blocked during busy state (loading or pending async action) to prevent double-input.',- 'Character counter is connected to the textarea via aria-describedby and uses aria-live="polite" for screen reader announcements.',- ],usage: {- summary: 'A multi-line text input for collecting longer user input.',- content: `## When to use--- Users need to enter multiple lines of text.-- Comments, descriptions, or longer-form content entry.--## When NOT to use--- Single-line input (use TextInput instead).-- Rich text with formatting (use a rich text editor instead).`,+ description:+ 'TextArea is a multi-line text input for collecting longer user input such as comments, descriptions, or longer-form content. Use TextInput instead for single-line input, or a rich text editor for formatted content.',+ features: [+ 'Label support — required label for accessibility, can be visually hidden',+ 'Description — optional text displayed between the label and textarea',+ 'Optional/Required indicators — displays "Optional" or "Required" text with bullet separator',+ 'Status variants — warning, error, and success states with colored borders and icons',+ 'Character counter — displays current/max length when maxLength is set (does not enforce natively)',+ 'Start icon — optional icon rendered inside the leading edge of the input',+ 'Label tooltip — optional info icon with tooltip at the end of the label',+ 'Loading state — shows a spinner and uses optimistic updates via useOptimistic',+ 'Async action support — onChangeAction fires after onChange inside a React transition',+ 'Disabled state — visual opacity and cursor changes, no interaction',+ 'Resizable — vertical resize enabled by default',+ 'Spell check — browser spell checking enabled by default, configurable',+ 'Reduced motion — respects prefers-reduced-motion for input wrapper transitions',+ ],+ accessibility: [+ 'Label is always rendered in the DOM; use isLabelHidden to hide it visually while keeping it accessible.',+ 'The textarea id is generated via useId and linked to its label via htmlFor, ensuring correct label association.',+ 'aria-describedby is set to the description and/or status message IDs when those elements are present.',+ 'aria-required="true" is set when isRequired is true.',+ 'aria-invalid="true" is set when status.type is "error".',+ 'aria-busy is set while an optimistic update or loading state is active.',+ ],+ notes: [+ 'isOptional and isRequired are mutually exclusive; if both are set, "Optional" takes precedence.',+ 'The component uses useOptimistic for instant UI feedback when onChangeAction returns a Promise.',+ 'Textarea has vertical resize enabled via CSS.',+ 'Wraps XDSField for consistent label, description, and status message layout.',+ 'The character counter uses optimisticValue and turns red when it exceeds maxLength.',+ 'Interaction is blocked during busy state (loading or pending async action) to prevent double-input.',+ 'Character counter is connected to the textarea via aria-describedby and uses aria-live="polite" for screen reader announcements.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'TextArea',- description:- '用于收集较长用户输入的多行文本输入组件。',- features: [- '标签支持 — 必需的无障碍标签,可视觉隐藏',- '描述 — 显示在标签和文本域之间的可选文本',- '可选/必填指示器 — 显示带圆点分隔符的"可选"或"必填"文本',- '状态变体 — 警告、错误和成功状态,带彩色边框和图标',- '字符计数器 — 设置 maxLength 时显示当前/最大长度(不原生强制限制)',- '起始图标 — 在输入框前端内部渲染的可选图标',- '标签工具提示 — 标签末尾带工具提示的可选信息图标',- '加载状态 — 显示旋转器并通过 useOptimistic 使用乐观更新',- '异步操作支持 — onChangeAction 在 React transition 内于 onChange 之后触发',- '禁用状态 — 视觉透明度和光标变化,无交互',- '无障碍 — 标签通过 htmlFor/id 关联,aria-describedby、aria-required、aria-invalid、aria-busy',- '可调整大小 — 默认启用垂直调整大小',- '拼写检查 — 默认启用浏览器拼写检查,可配置',- '减少动画 — 尊重 prefers-reduced-motion 输入包装过渡',- ],props: [{name: 'ref',@@ -370,23 +343,43 @@ export const docsZh = {{className: 'xds-textarea'},],},- accessibility: [- '标签始终在 DOM 中渲染;使用 isLabelHidden 视觉上隐藏它,同时保持无障碍性。',- '文本域 id 通过 useId 生成并通过 htmlFor 与其标签关联,确保正确的标签关联。',- '当描述和/或状态消息元素存在时,aria-describedby 设置为相应的 ID。',- '当 isRequired 为 true 时,设置 aria-required="true"。',- '当 status.type 为 "error" 时,设置 aria-invalid="true"。',- '乐观更新或加载状态活跃期间设置 aria-busy。',- ],- notes: [- 'isOptional 和 isRequired 互斥;如果同时设置,"可选"优先。',- '当 onChangeAction 返回 Promise 时,组件使用 useOptimistic 实现即时 UI 反馈。',- '文本域通过 CSS 启用垂直调整大小。',- '包装 XDSField 以实现一致的标签、描述和状态消息布局。',- '字符计数器使用 optimisticValue,超出 maxLength 时变为红色。',- '忙碌状态(加载中或异步操作等待中)期间阻止交互,防止重复输入。',- '字符计数器通过 aria-describedby 连接到文本域,并使用 aria-live="polite" 进行屏幕阅读器公告。',- ],+ usage: {+ description:+ '用于收集较长用户输入的多行文本输入组件。',+ features: [+ '标签支持 — 必需的无障碍标签,可视觉隐藏',+ '描述 — 显示在标签和文本域之间的可选文本',+ '可选/必填指示器 — 显示带圆点分隔符的"可选"或"必填"文本',+ '状态变体 — 警告、错误和成功状态,带彩色边框和图标',+ '字符计数器 — 设置 maxLength 时显示当前/最大长度(不原生强制限制)',+ '起始图标 — 在输入框前端内部渲染的可选图标',+ '标签工具提示 — 标签末尾带工具提示的可选信息图标',+ '加载状态 — 显示旋转器并通过 useOptimistic 使用乐观更新',+ '异步操作支持 — onChangeAction 在 React transition 内于 onChange 之后触发',+ '禁用状态 — 视觉透明度和光标变化,无交互',+ '无障碍 — 标签通过 htmlFor/id 关联,aria-describedby、aria-required、aria-invalid、aria-busy',+ '可调整大小 — 默认启用垂直调整大小',+ '拼写检查 — 默认启用浏览器拼写检查,可配置',+ '减少动画 — 尊重 prefers-reduced-motion 输入包装过渡',+ ],+ accessibility: [+ '标签始终在 DOM 中渲染;使用 isLabelHidden 视觉上隐藏它,同时保持无障碍性。',+ '文本域 id 通过 useId 生成并通过 htmlFor 与其标签关联,确保正确的标签关联。',+ '当描述和/或状态消息元素存在时,aria-describedby 设置为相应的 ID。',+ '当 isRequired 为 true 时,设置 aria-required="true"。',+ '当 status.type 为 "error" 时,设置 aria-invalid="true"。',+ '乐观更新或加载状态活跃期间设置 aria-busy。',+ ],+ notes: [+ 'isOptional 和 isRequired 互斥;如果同时设置,"可选"优先。',+ '当 onChangeAction 返回 Promise 时,组件使用 useOptimistic 实现即时 UI 反馈。',+ '文本域通过 CSS 启用垂直调整大小。',+ '包装 XDSField 以实现一致的标签、描述和状态消息布局。',+ '字符计数器使用 optimisticValue,超出 maxLength 时变为红色。',+ '忙碌状态(加载中或异步操作等待中)期间阻止交互,防止重复输入。',+ '字符计数器通过 aria-describedby 连接到文本域,并使用 aria-live="polite" 进行屏幕阅读器公告。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjsindex 2ab07005b6..4e121872dc 100644--- a/packages/core/src/TextInput/TextInput.doc.mjs+++ b/packages/core/src/TextInput/TextInput.doc.mjs@@ -2,20 +2,8 @@export const docs = {name: 'TextInput',- description:- 'A text input component for collecting user text input, with label, description, validation status, and optional/required indicators.', keywords: ["textinput","textfield","input","search","clearable","prefix","suffix","adornment","validation"],- features: [- 'Label support — required label for accessibility (can be visually hidden)',- 'Description — optional text displayed between the label and input',- 'Optional/Required indicators — "Optional" or "Required" text with bullet separator',- 'Label tooltip — optional info icon with tooltip at the end of the label',- 'Validation status — error, warning, and success states with colored borders and icons',- 'Start icon — optional icon displayed at the start of the input',- 'Loading state — shows a spinner and sets aria-busy while an async action is pending',- 'Disabled state — visually dims the input and prevents interaction',- 'Accessible — label is always associated with the input via htmlFor/id; sets aria-invalid, aria-required, aria-busy, and aria-describedby as appropriate',- 'Styled with StyleX — uses XDS design tokens for consistent styling',- ], props: [+ keywords: ["textinput","textfield","input","search","clearable","prefix","suffix","adornment","validation"],+ props: [{name: 'type',type: "'text' | 'password' | 'email'",@@ -141,30 +129,33 @@ export const docs = {{className: 'xds-text-input', visualProps: ['size']},],},- accessibility: [- 'Label is always rendered and associated with the input via htmlFor/id (using useId). Use isLabelHidden to hide it visually while keeping it accessible to screen readers.',- 'aria-describedby is set automatically when description or a status message is present.',- 'aria-invalid="true" is set when status.type is "error".',- 'aria-required="true" is set when isRequired is true.',- 'aria-busy is set while an optimistic update or isLoading is active.',- ],- notes: [- 'isOptional and isRequired are mutually exclusive — if both are set, "Optional" is shown.',- 'onChangeAction fires after onChange inside a React transition, enabling useOptimistic for an instant UI update while the async work completes.',- 'The component wraps XDSField for label, description, and optional/required rendering.',- 'The size prop supports "sm", "md", and "lg".',- ],usage: {- summary: 'Enables users to enter or edit text or numeric values.',- content: `## When to use--- Short-form and long-form text entries.--## Best practices--- Do: Size the input to reflect the expected content length.-- Do: Use validation messaging for required fields.-- Validation states: error (blocking), warning (non-blocking), success (confirmation).`,+ description:+ 'TextInput enables users to enter or edit short-form text values with built-in label, description, validation status, and optional/required indicators. Size the input to reflect the expected content length and use validation messaging for required fields.',+ features: [+ 'Label support — required label for accessibility (can be visually hidden)',+ 'Description — optional text displayed between the label and input',+ 'Optional/Required indicators — "Optional" or "Required" text with bullet separator',+ 'Label tooltip — optional info icon with tooltip at the end of the label',+ 'Validation status — error, warning, and success states with colored borders and icons',+ 'Start icon — optional icon displayed at the start of the input',+ 'Loading state — shows a spinner and sets aria-busy while an async action is pending',+ 'Disabled state — visually dims the input and prevents interaction',+ 'Styled with StyleX — uses XDS design tokens for consistent styling',+ ],+ accessibility: [+ 'Label is always rendered and associated with the input via htmlFor/id (using useId). Use isLabelHidden to hide it visually while keeping it accessible to screen readers.',+ 'aria-describedby is set automatically when description or a status message is present.',+ 'aria-invalid="true" is set when status.type is "error".',+ 'aria-required="true" is set when isRequired is true.',+ 'aria-busy is set while an optimistic update or isLoading is active.',+ ],+ notes: [+ 'isOptional and isRequired are mutually exclusive — if both are set, "Optional" is shown.',+ 'onChangeAction fires after onChange inside a React transition, enabling useOptimistic for an instant UI update while the async work completes.',+ 'The component wraps XDSField for label, description, and optional/required rendering.',+ 'The size prop supports "sm", "md", and "lg".',+ ],anatomy: [{name: 'Label', required: true, description: 'Text that identifies the input field.'},{name: 'Description', required: false, description: 'Helper text providing additional context.'},@@ -178,20 +169,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'TextInput',- description:- '用于收集用户文本输入的文本输入组件,带有标签、描述、验证状态和可选/必填指示器。',- features: [- '标签支持 — 必需的无障碍标签(可视觉隐藏)',- '描述 — 显示在标签和输入框之间的可选文本',- '可选/必填指示器 — 带圆点分隔符的"可选"或"必填"文本',- '标签工具提示 — 标签末尾带工具提示的可选信息图标',- '验证状态 — 错误、警告和成功状态,带彩色边框和图标',- '起始图标 — 显示在输入框起始位置的可选图标',- '加载状态 — 异步操作挂起时显示旋转器并设置 aria-busy',- '禁用状态 — 视觉上使输入框变暗并阻止交互',- '无障碍 — 标签始终通过 htmlFor/id 与输入框关联;根据需要设置 aria-invalid、aria-required、aria-busy 和 aria-describedby',- '使用 StyleX 样式化 — 使用 XDS 设计令牌实现一致的样式',- ],props: [{name: 'type',@@ -316,19 +293,35 @@ export const docsZh = {{className: 'xds-text-input', visualProps: ['size']},],},- accessibility: [- '标签始终渲染并通过 htmlFor/id(使用 useId)与输入框关联。使用 isLabelHidden 视觉上隐藏它,同时保持屏幕阅读器的无障碍性。',- '当描述或状态消息存在时,自动设置 aria-describedby。',- '当 status.type 为 "error" 时,设置 aria-invalid="true"。',- '当 isRequired 为 true 时,设置 aria-required="true"。',- '乐观更新或 isLoading 活跃期间设置 aria-busy。',- ],- notes: [- 'isOptional 和 isRequired 互斥 — 如果同时设置,显示"可选"。',- 'onChangeAction 在 React transition 内于 onChange 之后触发,启用 useOptimistic 以在异步工作完成时实现即时 UI 更新。',- '组件包装 XDSField 以实现标签、描述和可选/必填的渲染。',- 'size 属性支持 "sm"、"md" 和 "lg"。',- ],+ usage: {+ description:+ '用于收集用户文本输入的文本输入组件,带有标签、描述、验证状态和可选/必填指示器。',+ features: [+ '标签支持 — 必需的无障碍标签(可视觉隐藏)',+ '描述 — 显示在标签和输入框之间的可选文本',+ '可选/必填指示器 — 带圆点分隔符的"可选"或"必填"文本',+ '标签工具提示 — 标签末尾带工具提示的可选信息图标',+ '验证状态 — 错误、警告和成功状态,带彩色边框和图标',+ '起始图标 — 显示在输入框起始位置的可选图标',+ '加载状态 — 异步操作挂起时显示旋转器并设置 aria-busy',+ '禁用状态 — 视觉上使输入框变暗并阻止交互',+ '无障碍 — 标签始终通过 htmlFor/id 与输入框关联;根据需要设置 aria-invalid、aria-required、aria-busy 和 aria-describedby',+ '使用 StyleX 样式化 — 使用 XDS 设计令牌实现一致的样式',+ ],+ accessibility: [+ '标签始终渲染并通过 htmlFor/id(使用 useId)与输入框关联。使用 isLabelHidden 视觉上隐藏它,同时保持屏幕阅读器的无障碍性。',+ '当描述或状态消息存在时,自动设置 aria-describedby。',+ '当 status.type 为 "error" 时,设置 aria-invalid="true"。',+ '当 isRequired 为 true 时,设置 aria-required="true"。',+ '乐观更新或 isLoading 活跃期间设置 aria-busy。',+ ],+ notes: [+ 'isOptional 和 isRequired 互斥 — 如果同时设置,显示"可选"。',+ 'onChangeAction 在 React transition 内于 onChange 之后触发,启用 useOptimistic 以在异步工作完成时实现即时 UI 更新。',+ '组件包装 XDSField 以实现标签、描述和可选/必填的渲染。',+ 'size 属性支持 "sm"、"md" 和 "lg"。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Thumbnail/Thumbnail.doc.mjs b/packages/core/src/Thumbnail/Thumbnail.doc.mjsindex 47ceae342c..1a812fd9bb 100644--- a/packages/core/src/Thumbnail/Thumbnail.doc.mjs+++ b/packages/core/src/Thumbnail/Thumbnail.doc.mjs@@ -2,21 +2,7 @@export const docs = {name: 'Thumbnail',- description:- 'A square preview card for image attachments. Shows a skeleton shimmer while uploading, the image on success, or a placeholder icon when no source is provided.',keywords: ["thumbnail","attachment","preview","image","upload","dismiss","remove","loading"],- features: [- 'Square 1:1 aspect ratio via CSS aspect-ratio',- 'Skeleton shimmer during upload (isLoading)',- 'Upload overlay with spinner when isLoading + src',- 'Image preview with object-fit: cover',- 'APCA-based luminance detection for adaptive remove button contrast',- 'Concentric radius: button radius derived from container radius minus inset',- 'Hover shadow on interactive thumbnails (onClick)',- 'Label shown as tooltip on hover, used as aria-label',- 'Placeholder icon when no src',- 'Disabled state blocks all interactions and reduces opacity',- ],props: [{name: 'src',@@ -80,29 +66,33 @@ export const docs = {{className: 'xds-thumbnail'},],},- accessibility: [- 'label prop provides aria-label for the thumbnail and its remove button.',- 'onClick renders as a button for keyboard and screen reader access.',- 'Remove button uses aria-label derived from the label prop.',- ],+ usage: {+ description:+ 'Thumbnail is a square preview card for image attachments. It shows a skeleton shimmer while uploading, the image on success, or a placeholder icon when no source is provided.',+ features: [+ 'Square 1:1 aspect ratio via CSS aspect-ratio',+ 'Skeleton shimmer during upload (isLoading)',+ 'Upload overlay with spinner when isLoading + src',+ 'Image preview with object-fit: cover',+ 'Hover shadow on interactive thumbnails (onClick)',+ 'Label shown as tooltip on hover, used as aria-label',+ 'Placeholder icon when no src',+ 'Disabled state blocks all interactions and reduces opacity',+ ],+ accessibility: [+ 'label prop provides aria-label for the thumbnail and its remove button.',+ 'onClick renders as a button for keyboard and screen reader access.',+ 'Remove button uses aria-label derived from the label prop.',+ ],+ notes: [+ 'APCA-based luminance detection for adaptive remove button contrast.',+ 'Concentric radius: button radius derived from container radius minus inset.',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description:- '图片附件的方形预览卡片。上传时显示骨架屏动画,成功时显示图片,无图片源时显示占位图标。',- features: [- '通过 CSS aspect-ratio 实现 1:1 正方形比例',- '上传时骨架屏闪烁效果(isLoading)',- 'isLoading + src 时显示上传覆盖层和加载指示器',- '通过 object-fit: cover 预览图片',- '基于 APCA 亮度检测的自适应移除按钮对比度',- '同心圆角:按钮圆角由容器圆角减去内边距推导',- '可交互缩略图(onClick)的悬停阴影',- '标签作为悬停提示工具和 aria-label 显示',- '无 src 时显示占位图标',- '禁用状态阻止所有交互并降低不透明度',- ],propDescriptions: {src: '图片源 URL。',alt: '图片的替代文本。',@@ -116,11 +106,27 @@ export const docsZh = {style: '根元素的内联样式。建议使用 xstyle。','data-testid': '用于自动化测试框架的测试选择器。',},- accessibility: [- 'label 属性为缩略图及其移除按钮提供 aria-label。',- 'onClick 渲染为按钮以支持键盘和屏幕阅读器访问。',- '移除按钮使用从 label 属性推导的 aria-label。',- ],+ usage: {+ description:+ '图片附件的方形预览卡片。上传时显示骨架屏动画,成功时显示图片,无图片源时显示占位图标。',+ features: [+ '通过 CSS aspect-ratio 实现 1:1 正方形比例',+ '上传时骨架屏闪烁效果(isLoading)',+ 'isLoading + src 时显示上传覆盖层和加载指示器',+ '通过 object-fit: cover 预览图片',+ '基于 APCA 亮度检测的自适应移除按钮对比度',+ '同心圆角:按钮圆角由容器圆角减去内边距推导',+ '可交互缩略图(onClick)的悬停阴影',+ '标签作为悬停提示工具和 aria-label 显示',+ '无 src 时显示占位图标',+ '禁用状态阻止所有交互并降低不透明度',+ ],+ accessibility: [+ 'label 属性为缩略图及其移除按钮提供 aria-label。',+ 'onClick 渲染为按钮以支持键盘和屏幕阅读器访问。',+ '移除按钮使用从 label 属性推导的 aria-label。',+ ],+ },};export const docsDense = {diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjsindex 465c9b8493..8c70239598 100644--- a/packages/core/src/TimeInput/TimeInput.doc.mjs+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs@@ -2,19 +2,8 @@export const docs = {name: 'TimeInput',- description:- 'Time input with free-text entry, text parsing, and arrow-key navigation.',keywords: ["timeinput","timepicker","time","clock","hour","minute","ampm","timeselect","timefield"],- features: [- 'Accepts free-text time entry and parses common formats (e.g. "2:30 PM", "14:30")',- 'Supports 12-hour and 24-hour display formats',- 'Arrow-up / arrow-down adjust the time by a configurable minute increment',- 'Optional seconds display via hasSeconds',- 'Optional clear button via hasClear',- 'Min / max range constraints reject out-of-range values',- 'Async action support via onChangeAction with optimistic UI and loading spinner',- 'Accessible — label, description, and status message are wired to aria-describedby; aria-required and aria-invalid reflect field state',- ], props: [+ props: [{name: 'label',type: 'string',@@ -147,45 +136,39 @@ export const docs = {'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',},],- accessibility: [- 'The visible label is associated with the input via htmlFor / id.',- 'isLabelHidden visually hides the label while keeping it in the accessibility tree.',- 'description and status.message are linked to the input via aria-describedby.',- 'aria-required is set when isRequired is true.',- 'aria-invalid is set when status.type is "error".',- 'aria-busy reflects the loading / optimistic-pending state.',- 'The clear button has an explicit aria-label of "Clear time".',- ],- keyboard:- 'ArrowUp / ArrowDown adjust the current time by the configured increment in minutes. Typing a time string in common formats (e.g. "2:30 PM", "14:30") is parsed on blur. Pressing the clear button returns focus to the input.',theming: {targets: [{className: 'xds-time-input', visualProps: ['size']},],},usage: {- summary: 'Field formatted for users to input a time.',- content: `## When to use--- When the user needs to input a time, such as in scheduling or form fields.`,+ description:+ 'TimeInput is a time input field with free-text entry, text parsing, and arrow-key navigation. Use it when users need to input a time, such as in scheduling or form fields.',+ features: [+ 'Accepts free-text time entry and parses common formats (e.g. "2:30 PM", "14:30")',+ 'Supports 12-hour and 24-hour display formats',+ 'Arrow-up / arrow-down adjust the time by a configurable minute increment',+ 'Optional seconds display via hasSeconds',+ 'Optional clear button via hasClear',+ 'Min / max range constraints reject out-of-range values',+ 'Async action support via onChangeAction with optimistic UI and loading spinner',+ ],+ accessibility: [+ 'The visible label is associated with the input via htmlFor / id.',+ 'isLabelHidden visually hides the label while keeping it in the accessibility tree.',+ 'description and status.message are linked to the input via aria-describedby.',+ 'aria-required is set when isRequired is true.',+ 'aria-invalid is set when status.type is "error".',+ 'aria-busy reflects the loading / optimistic-pending state.',+ 'The clear button has an explicit aria-label of "Clear time".',+ 'Keyboard: ArrowUp/ArrowDown adjust the current time by the configured increment in minutes; typing a time string in common formats is parsed on blur; pressing the clear button returns focus to the input.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'TimeInput',- description:- '支持自由文本输入、文本解析和方向键导航的时间输入组件。',- features: [- '接受自由文本时间输入并解析常见格式(例如 "2:30 PM"、"14:30")',- '支持 12 小时和 24 小时显示格式',- '上/下方向键按可配置的分钟增量调整时间',- '通过 hasSeconds 可选显示秒',- '通过 hasClear 可选清除按钮',- '最小/最大范围约束拒绝超出范围的值',- '通过 onChangeAction 支持异步操作,带乐观 UI 和加载旋转器',- '无障碍 — 标签、描述和状态消息通过 aria-describedby 关联;aria-required 和 aria-invalid 反映字段状态',- ],props: [{name: 'label',@@ -319,22 +302,35 @@ export const docsZh = {'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',},],- accessibility: [- '可见标签通过 htmlFor / id 与输入框关联。',- 'isLabelHidden 视觉上隐藏标签,同时保持在无障碍树中。',- 'description 和 status.message 通过 aria-describedby 与输入框关联。',- '当 isRequired 为 true 时设置 aria-required。',- '当 status.type 为 "error" 时设置 aria-invalid。',- 'aria-busy 反映加载/乐观更新挂起状态。',- '清除按钮具有明确的 aria-label "Clear time"。',- ],- keyboard:- '上/下方向键按配置的分钟增量调整当前时间。以常见格式(例如 "2:30 PM"、"14:30")输入时间字符串会在失焦时解析。按清除按钮将焦点返回到输入框。',theming: {targets: [{className: 'xds-time-input', visualProps: ['size']},],},+ usage: {+ description:+ '支持自由文本输入、文本解析和方向键导航的时间输入组件。',+ features: [+ '接受自由文本时间输入并解析常见格式(例如 "2:30 PM"、"14:30")',+ '支持 12 小时和 24 小时显示格式',+ '上/下方向键按可配置的分钟增量调整时间',+ '通过 hasSeconds 可选显示秒',+ '通过 hasClear 可选清除按钮',+ '最小/最大范围约束拒绝超出范围的值',+ '通过 onChangeAction 支持异步操作,带乐观 UI 和加载旋转器',+ '无障碍 — 标签、描述和状态消息通过 aria-describedby 关联;aria-required 和 aria-invalid 反映字段状态',+ ],+ accessibility: [+ '可见标签通过 htmlFor / id 与输入框关联。',+ 'isLabelHidden 视觉上隐藏标签,同时保持在无障碍树中。',+ 'description 和 status.message 通过 aria-describedby 与输入框关联。',+ '当 isRequired 为 true 时设置 aria-required。',+ '当 status.type 为 "error" 时设置 aria-invalid。',+ 'aria-busy 反映加载/乐观更新挂起状态。',+ '清除按钮具有明确的 aria-label "Clear time"。',+ 'Keyboard: 上/下方向键按配置的分钟增量调整当前时间。以常见格式(例如 "2:30 PM"、"14:30")输入时间字符串会在失焦时解析。按清除按钮将焦点返回到输入框。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjsindex f06a06f2c7..8ad7002f8b 100644--- a/packages/core/src/Timestamp/Timestamp.doc.mjs+++ b/packages/core/src/Timestamp/Timestamp.doc.mjs@@ -2,8 +2,7 @@export const docs = {name: 'Timestamp',- description:- 'Displays a formatted timestamp as human-readable text with optional tooltip and live updates. Renders via XDSText for consistent typography.', keywords: ['date', 'time', 'datetime', 'relative', 'ago', 'clock', 'format', 'duration'],+ keywords: ['date', 'time', 'datetime', 'relative', 'ago', 'clock', 'format', 'duration'],props: [{name: 'value',@@ -70,37 +69,27 @@ export const docs = {description: 'Font weight override.',},],- features: [- "Formats: 'relative', 'date', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time', 'auto'",- 'Live updates: opt-in timer that adjusts frequency based on age',- 'Tooltip: shows full date/time on hover for relative timestamps',- 'Semantic HTML: renders <time> with ISO 8601 datetime attribute',- 'Typography: delegates to XDSText for consistent sizing and color',- "System formats: ISO-style dates/times for databases and logs",- ], theming: {+ theming: {targets: [{className: 'xds-timestamp', visualProps: ['type', 'color']},],},- accessibility: [- 'Renders as <time datetime="..."> with ISO 8601 datetime attribute for machines.',- 'Sets aria-label with full absolute time when displaying relative format.',- 'Tooltip is keyboard accessible via focus.',- ],usage: {- summary: 'Displays the absolute or relative date and time of an event or its duration.',- content: `## When to use--- Showing an exact date and time (absolute format).-- Indicating freshness with an "ago" format (relative).-- Displaying event duration.--## Best practices--- Do: Choose a format that fits the context (absolute for precision, relative for recency).-- Do: Ensure consistent timestamp formatting within the same view.-- Do: Use a single time unit for table column displays.-- Do: Provide tooltips with additional detail such as timezone or full date.`,+ description:+ 'Timestamp displays a formatted timestamp as human-readable text with optional tooltip and live updates, rendering via XDSText for consistent typography. Choose a format that fits the context — absolute for precision, relative for recency — and ensure consistent formatting within the same view.',+ features: [+ "Formats: 'relative', 'date', 'date_time', 'time', 'system_date', 'system_date_time', 'system_time', 'auto'",+ 'Live updates: opt-in timer that adjusts frequency based on age',+ 'Tooltip: shows full date/time on hover for relative timestamps',+ 'Semantic HTML: renders <time> with ISO 8601 datetime attribute',+ 'Typography: delegates to XDSText for consistent sizing and color',+ "System formats: ISO-style dates/times for databases and logs",+ ],+ accessibility: [+ 'Renders as <time datetime="..."> with ISO 8601 datetime attribute for machines.',+ 'Sets aria-label with full absolute time when displaying relative format.',+ 'Tooltip is keyboard accessible via focus.',+ ],anatomy: [{name: 'Time or Duration Value', required: true, description: 'The displayed time, date, or duration text.'},{name: 'Hover Indication', required: false, description: 'Visual cue indicating additional detail is available on hover.'},@@ -111,20 +100,6 @@ export const docs = {/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description: '以人类可读文本显示格式化时间戳,可选工具提示和实时更新。',- features: [- "格式:'relative'、'date'、'date_time'、'time'、'system_date'、'system_date_time'、'system_time'、'auto'",- '实时更新:根据时间戳年龄自适应频率的计时器',- '工具提示:悬停时显示相对时间戳的完整日期/时间',- '语义化 HTML:使用 ISO 8601 datetime 属性渲染 <time>',- '排版:委托给 XDSText 以保持一致的大小和颜色',- "系统格式:数据库和日志的 ISO 风格日期/时间",- ],- accessibility: [- '作为带有 ISO 8601 datetime 属性的 <time datetime="..."> 渲染,供机器读取。',- '显示相对格式时,设置带有完整绝对时间的 aria-label。',- '工具提示可通过焦点访问键盘。',- ],propDescriptions: {value: '要显示的日期/时间。接受 Unix 时间戳(秒)或 ISO 8601 字符串。',format: "显示格式。'relative' 显示 '2小时前','date' 显示日期,'auto' 根据时间近远自动切换。",@@ -137,6 +112,22 @@ export const docsZh = {color: '文字颜色。',weight: '字体粗细覆盖。',},+ usage: {+ description: '以人类可读文本显示格式化时间戳,可选工具提示和实时更新。',+ features: [+ "格式:'relative'、'date'、'date_time'、'time'、'system_date'、'system_date_time'、'system_time'、'auto'",+ '实时更新:根据时间戳年龄自适应频率的计时器',+ '工具提示:悬停时显示相对时间戳的完整日期/时间',+ '语义化 HTML:使用 ISO 8601 datetime 属性渲染 <time>',+ '排版:委托给 XDSText 以保持一致的大小和颜色',+ "系统格式:数据库和日志的 ISO 风格日期/时间",+ ],+ accessibility: [+ '作为带有 ISO 8601 datetime 属性的 <time datetime="..."> 渲染,供机器读取。',+ '显示相对格式时,设置带有完整绝对时间的 aria-label。',+ '工具提示可通过焦点访问键盘。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjsindex 6cd46fa413..17d6250148 100644--- a/packages/core/src/Toast/Toast.doc.mjs+++ b/packages/core/src/Toast/Toast.doc.mjs@@ -2,22 +2,7 @@export const docs = {name: 'Toast',- description:- 'Toast notification system with auto-dismiss, stacking, deduplication, and smooth animations. Uses XDSMediaTheme for inverted surface theming.',-keywords: ["toast","notification","snackbar","alert","message","feedback","status"],- features: [- "Types: 'info' (default), 'error'",- 'Auto-dismiss: info toasts dismiss after 5s, error toasts persist',- 'Pause on hover/focus: timer pauses during interaction',- 'Stacking: multiple toasts stack with smooth enter/exit animations',- 'Deduplication: uniqueID with ignore or overwrite collision behavior',- 'Programmatic dismiss: show() returns a dismiss function',- 'End content slot: trailing actions (buttons, links)',- 'Fallback viewport: works without a provider via document.body fallback',- 'Inverted surface: uses XDSMediaTheme for correct colors on dark/light backgrounds',- 'Accessible: role=status/alert, aria-live=polite/assertive',- ],props: [{@@ -71,18 +56,22 @@ export const docs = {},usage: {- summary: 'Transient notification that appears briefly to confirm an action or surface non-critical information.',- content: `## When to use--- Confirming a completed action (e.g., "Saved successfully").-- Surfacing non-critical, time-sensitive information.-- Providing undo opportunities for reversible actions.--## When NOT to use--- Critical information that requires user action (use Banner instead).-- Persistent messages (use Banner instead).-- Validation errors on form fields (use Field status instead).`,+ description:+ 'Toast is a transient notification that appears briefly to confirm actions or surface non-critical information, such as save confirmations or undo opportunities. It provides auto-dismiss, stacking, deduplication, and smooth animations with inverted surface theming via XDSMediaTheme. For critical information requiring user action or persistent messages, use Banner instead.',+ features: [+ "Types: 'info' (default), 'error'",+ 'Auto-dismiss: info toasts dismiss after 5s, error toasts persist',+ 'Pause on hover/focus: timer pauses during interaction',+ 'Stacking: multiple toasts stack with smooth enter/exit animations',+ 'Deduplication: uniqueID with ignore or overwrite collision behavior',+ 'Programmatic dismiss: show() returns a dismiss function',+ 'End content slot: trailing actions (buttons, links)',+ 'Fallback viewport: works without a provider via document.body fallback',+ 'Inverted surface: uses XDSMediaTheme for correct colors on dark/light backgrounds',+ ],+ accessibility: [+ 'Uses role=status for info toasts and role=alert for error toasts, with aria-live=polite and aria-live=assertive respectively.',+ ],},};@@ -94,20 +83,6 @@ export const docs = {/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description:- 'Toast 通知系统,支持自动关闭、堆叠、去重和平滑动画。使用 XDSMediaTheme 进行反转表面主题。',- features: [- "类型:'info'(默认)、'error'",- '自动关闭:info toast 5秒后关闭,error toast 持续显示',- '悬停/聚焦暂停:交互时计时器暂停',- '堆叠:多个 toast 以平滑进出动画堆叠',- '去重:uniqueID 支持 ignore 或 overwrite 碰撞行为',- '程序化关闭:show() 返回关闭函数',- '尾部内容插槽:尾随操作(按钮、链接)',- '回退视口:无需 provider,通过 document.body 回退',- '反转表面:使用 XDSMediaTheme 在深色/浅色背景上显示正确颜色',- '无障碍:role=status/alert,aria-live=polite/assertive',- ],propDescriptions: {body: '主要消息内容。',type: 'Toast 类型,控制背景颜色。error toast 持续显示直到关闭。',@@ -119,18 +94,22 @@ export const docsZh = {onHide: '当 toast 被移除时触发的回调。',},usage: {- summary: '短暂通知,出现片刻以确认操作或显示非关键信息。',- content: `## 何时使用--- 确认已完成的操作(如"保存成功")。-- 显示非关键的时效性信息。-- 为可逆操作提供撤销机会。--## 何时不使用--- 需要用户操作的关键信息(使用 Banner)。-- 持久性消息(使用 Banner)。-- 表单字段验证错误(使用 Field 状态)。`,+ description:+ '短暂通知,出现片刻以确认操作或显示非关键信息(如保存确认或撤销机会)。支持自动关闭、堆叠、去重和平滑动画,使用 XDSMediaTheme 进行反转表面主题。对于需要用户操作的关键信息或持久性消息,请使用 Banner。',+ features: [+ "类型:'info'(默认)、'error'",+ '自动关闭:info toast 5秒后关闭,error toast 持续显示',+ '悬停/聚焦暂停:交互时计时器暂停',+ '堆叠:多个 toast 以平滑进出动画堆叠',+ '去重:uniqueID 支持 ignore 或 overwrite 碰撞行为',+ '程序化关闭:show() 返回关闭函数',+ '尾部内容插槽:尾随操作(按钮、链接)',+ '回退视口:无需 provider,通过 document.body 回退',+ '反转表面:使用 XDSMediaTheme 在深色/浅色背景上显示正确颜色',+ ],+ accessibility: [+ 'info toast 使用 role=status 和 aria-live=polite,error toast 使用 role=alert 和 aria-live=assertive。',+ ],},};diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjsindex 4a0064d983..e31a6e99e0 100644--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs@@ -2,29 +2,13 @@export const docs = {name: 'ToggleButton',- description:- 'A button that toggles between pressed and unpressed states, with optional icon swap and group integration for single or multi-select behavior.',keywords: ["toggle","togglebutton","pressed","toolbar","formatting","segmented","button-group","exclusive","multi-select"],- features: [- 'Controlled toggle via isPressed/onPressedChange',- 'Icon swap between pressed and unpressed states via pressedIcon',- 'Font weight emphasis on press with width reservation to prevent layout shift',- 'Async action support via onPressedChangeAction with loading spinner',- 'Group integration via XDSToggleButtonGroup for single or multi-select',- 'Discriminated union on type: single (string | null) or multiple (string[])',- 'Horizontal and vertical group orientation',- 'Built on XDSButton with all its size, disabled, and tooltip support',- ],theming: {targets: [{className: 'xds-toggle-button-group'},],},- accessibility: [- 'Uses aria-pressed on the toggle button for screen reader state announcement.',- 'Group uses role="group" with aria-label from the label prop.',- ],- keyboard: 'Space/Enter toggles pressed state; Tab moves between buttons in a group', components: [+ components: [{name: 'XDSToggleButton',description: 'A button that toggles between pressed and unpressed states. Thin wrapper over XDSButton with controlled toggle pattern, icon swap, and font weight emphasis.',@@ -61,39 +45,28 @@ export const docs = {},],usage: {- summary: 'A button that switches between two persistent states, typically active and inactive.',- content: `## When to use--- When an action has two persistent states and can be undone.-- Use a group of toggle buttons for multiple independent two-state actions.-- Use a toggle button group for 3 or more mutually exclusive states.--## Best practices--- Do: Convey state through color change, bolded text, or a filled icon.-- Do: Keep the label the same between states.`,+ description:+ 'ToggleButton is a button that switches between two persistent states (active/inactive), with optional icon swap and group integration for single or multi-select behavior. Use a group of toggle buttons for multiple independent two-state actions, or a toggle button group for mutually exclusive states. Convey state through color change, bolded text, or a filled icon, and keep the label the same between states.',+ features: [+ 'Controlled toggle via isPressed/onPressedChange',+ 'Icon swap between pressed and unpressed states via pressedIcon',+ 'Font weight emphasis on press with width reservation to prevent layout shift',+ 'Async action support via onPressedChangeAction with loading spinner',+ 'Group integration via XDSToggleButtonGroup for single or multi-select',+ 'Discriminated union on type: single (string | null) or multiple (string[])',+ 'Horizontal and vertical group orientation',+ 'Built on XDSButton with all its size, disabled, and tooltip support',+ ],+ accessibility: [+ 'Uses aria-pressed on the toggle button for screen reader state announcement.',+ 'Group uses role="group" with aria-label from the label prop.',+ 'Keyboard: Space/Enter toggles pressed state; Tab moves between buttons in a group.',+ ],},};/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description:- '在按下和未按下状态之间切换的按钮,支持图标切换和分组集成,用于单选或多选行为。',- features: [- '通过 isPressed/onPressedChange 实现受控切换',- '通过 pressedIcon 在按下和未按下状态之间切换图标',- '按下时字重加粗,并预留宽度防止布局偏移',- '通过 onPressedChangeAction 支持异步操作,显示加载动画',- '通过 XDSToggleButtonGroup 实现分组集成,支持单选或多选',- 'type 判别联合类型:single (string | null) 或 multiple (string[])',- '支持水平和垂直方向的分组布局',- '基于 XDSButton 构建,继承其尺寸、禁用和提示功能',- ],- accessibility: [- '使用 aria-pressed 向屏幕阅读器宣告切换按钮状态。',- '分组使用 role="group" 并通过 label 属性设置 aria-label。',- ],- keyboard: 'Space/Enter 切换按下状态;Tab 在分组中的按钮间移动焦点',components: [{name: 'XDSToggleButton',@@ -131,6 +104,25 @@ export const docsZh = {},},],+ usage: {+ description:+ '在按下和未按下状态之间切换的按钮,支持图标切换和分组集成,用于单选或多选行为。',+ features: [+ '通过 isPressed/onPressedChange 实现受控切换',+ '通过 pressedIcon 在按下和未按下状态之间切换图标',+ '按下时字重加粗,并预留宽度防止布局偏移',+ '通过 onPressedChangeAction 支持异步操作,显示加载动画',+ '通过 XDSToggleButtonGroup 实现分组集成,支持单选或多选',+ 'type 判别联合类型:single (string | null) 或 multiple (string[])',+ '支持水平和垂直方向的分组布局',+ '基于 XDSButton 构建,继承其尺寸、禁用和提示功能',+ ],+ accessibility: [+ '使用 aria-pressed 向屏幕阅读器宣告切换按钮状态。',+ '分组使用 role="group" 并通过 label 属性设置 aria-label。',+ 'Keyboard: Space/Enter 切换按下状态;Tab 在分组中的按钮间移动焦点',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjsindex b3569e4031..e3ad22f93f 100644--- a/packages/core/src/Token/Token.doc.mjs+++ b/packages/core/src/Token/Token.doc.mjs@@ -2,18 +2,7 @@export const docs = {name: 'Token',- description:- 'A chip/tag component for displaying entities inline. Renders as a <span> by default, <a> when href is provided, or a <span> with an invisible <button> inside when onClick is provided.',keywords: ["token","chip","tag","pill","label","removable","dismissible","filter chip","closable"],- features: [- 'Polymorphic — renders as <span>, <a>, or interactive <span>+<button> based on props',- 'Invisible button pattern for onClick preserves real button semantics while allowing focus-within outline on the full token',- 'Remove button with expanded 14px hit-area tap target via ::after pseudo-element',- 'Eleven color variants including a neutral default',- 'Leading icon and trailing endContent slots',- 'Label can be visually hidden while remaining accessible to screen readers',- 'Disabled state reduces opacity and blocks pointer events',- ],props: [{name: 'label',@@ -93,26 +82,26 @@ export const docs = {{className: 'xds-token', visualProps: ['color', 'size']},],},- accessibility: [- 'When isLabelHidden is true, the label is clipped visually but exposed via aria-label on the root element so screen readers still announce it.',- 'The description prop maps to aria-description on the root element for supplementary context.',- 'When onClick is provided, the clickable content is wrapped in a real <button> so keyboard users can activate it with Enter or Space.',- 'The remove button has an automatic aria-label of "Remove <label>" and an expanded touch target via a ::after pseudo-element.',- 'When href is provided, aria-disabled is set on the <a> element when isDisabled is true.',- ],- keyboard:- 'Tab focuses the token (or its inner button when onClick is used). Enter/Space activate a clickable token or the remove button. Remove button is reachable as a separate Tab stop.',usage: {- summary: 'Displays entities inline for tags or names.',- content: `## When to use--- Concise metadata display.-- Icon with colored background indicator.-- Combined icon, text, and number representation.--## When NOT to use--- Static indicators without interaction \u2014 use Badge instead (Badge is 20px, Token is 28px).`,+ description:+ 'Token is a chip/tag component for displaying entities inline, rendering as a <span> by default, <a> when href is provided, or a <span> with an invisible <button> when onClick is used. It is ideal for concise metadata display such as tags, names, or colored indicators. For static indicators without interaction, use Badge instead.',+ features: [+ 'Polymorphic — renders as <span>, <a>, or interactive <span>+<button> based on props',+ 'Invisible button pattern for onClick preserves real button semantics while allowing focus-within outline on the full token',+ 'Remove button with expanded 14px hit-area tap target via ::after pseudo-element',+ 'Eleven color variants including a neutral default',+ 'Leading icon and trailing endContent slots',+ 'Label can be visually hidden while remaining accessible to screen readers',+ 'Disabled state reduces opacity and blocks pointer events',+ ],+ accessibility: [+ 'When isLabelHidden is true, the label is clipped visually but exposed via aria-label on the root element so screen readers still announce it.',+ 'The description prop maps to aria-description on the root element for supplementary context.',+ 'When onClick is provided, the clickable content is wrapped in a real <button> so keyboard users can activate it with Enter or Space.',+ 'The remove button has an automatic aria-label of "Remove <label>" and an expanded touch target via a ::after pseudo-element.',+ 'When href is provided, aria-disabled is set on the <a> element when isDisabled is true.',+ 'Keyboard: Tab focuses the token (or its inner button when onClick is used); Enter/Space activate a clickable token or the remove button; Remove button is reachable as a separate Tab stop.',+ ],anatomy: [{name: 'Color', required: false, description: 'Background color indicator.'},{name: 'Label', required: true, description: 'Text label for the token.'},@@ -126,17 +115,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Token',- description:- '用于内联显示实体的标签/标记组件。默认渲染为 <span>,提供 href 时渲染为 <a>,提供 onClick 时渲染为包含不可见 <button> 的 <span>。',- features: [- '多态渲染 — 根据属性渲染为 <span>、<a> 或交互式 <span>+<button>',- '不可见按钮模式用于 onClick,保留真实按钮语义,同时允许 focus-within 轮廓显示在整个标记上',- '移除按钮通过 ::after 伪元素扩展了 14px 的点击目标区域',- '十一种颜色变体,包括中性默认色',- '前置图标和尾部 endContent 插槽',- '标签可以视觉隐藏,同时保持对屏幕阅读器的可访问性',- '禁用状态降低透明度并阻止指针事件',- ],props: [{name: 'label',@@ -217,15 +195,27 @@ export const docsZh = {{className: 'xds-token', visualProps: ['color', 'size']},],},- accessibility: [- '当 isLabelHidden 为 true 时,标签在视觉上被裁剪,但通过根元素上的 aria-label 暴露给屏幕阅读器,使其仍然可以播报。',- 'description 属性映射到根元素上的 aria-description,用于提供补充上下文。',- '当提供 onClick 时,可点击内容被包裹在真实的 <button> 中,使键盘用户可以通过 Enter 或 Space 激活。',- '移除按钮自动具有 "Remove <label>" 的 aria-label,并通过 ::after 伪元素扩展触摸目标。',- '当提供 href 时,如果 isDisabled 为 true,则在 <a> 元素上设置 aria-disabled。',- ],- keyboard:- 'Tab 聚焦标记(或使用 onClick 时聚焦其内部按钮)。Enter/Space 激活可点击标记或移除按钮。移除按钮作为单独的 Tab 停靠点可达。',+ usage: {+ description:+ '用于内联显示实体的标签/标记组件。默认渲染为 <span>,提供 href 时渲染为 <a>,提供 onClick 时渲染为包含不可见 <button> 的 <span>。',+ features: [+ '多态渲染 — 根据属性渲染为 <span>、<a> 或交互式 <span>+<button>',+ '不可见按钮模式用于 onClick,保留真实按钮语义,同时允许 focus-within 轮廓显示在整个标记上',+ '移除按钮通过 ::after 伪元素扩展了 14px 的点击目标区域',+ '十一种颜色变体,包括中性默认色',+ '前置图标和尾部 endContent 插槽',+ '标签可以视觉隐藏,同时保持对屏幕阅读器的可访问性',+ '禁用状态降低透明度并阻止指针事件',+ ],+ accessibility: [+ '当 isLabelHidden 为 true 时,标签在视觉上被裁剪,但通过根元素上的 aria-label 暴露给屏幕阅读器,使其仍然可以播报。',+ 'description 属性映射到根元素上的 aria-description,用于提供补充上下文。',+ '当提供 onClick 时,可点击内容被包裹在真实的 <button> 中,使键盘用户可以通过 Enter 或 Space 激活。',+ '移除按钮自动具有 "Remove <label>" 的 aria-label,并通过 ::after 伪元素扩展触摸目标。',+ '当提供 href 时,如果 isDisabled 为 true,则在 <a> 元素上设置 aria-disabled。',+ 'Keyboard: Tab 聚焦标记(或使用 onClick 时聚焦其内部按钮)。Enter/Space 激活可点击标记或移除按钮。移除按钮作为单独的 Tab 停靠点可达。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjsindex fa07bd25ee..6df33c9116 100644--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs@@ -2,8 +2,7 @@export const docs = {name: 'Tokenizer',- description:- 'Multi-select typeahead with token chips for selected items. Composes XDSBaseTypeahead for search and XDSToken for chips.', keywords: ["tokenizer","multiselect","multi-select","chips","tags","combobox","autocomplete","taginput","chipinput"],+ keywords: ["tokenizer","multiselect","multi-select","chips","tags","combobox","autocomplete","taginput","chipinput"],props: [{name: 'label',@@ -162,48 +161,38 @@ export const docs = {description:'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',},- ], features: [- 'Token chips for each selected item with remove buttons',- 'Filtered search that automatically excludes already-selected items',- 'Max entries to limit number of selections — input hides when limit is reached',- 'Clear all button for bulk removal of all tokens',- 'Custom token and item rendering via renderToken and renderItem',- 'Backspace on empty input removes the last token',- "Change metadata: onChange receives a second argument with type ('add' | 'create' | 'remove' | 'reorder')",- 'Free-text token creation via hasCreate prop — shows a "Create" option in the dropdown for new values',],theming: {targets: [{className: 'xds-tokenizer', visualProps: ['size']},],},- accessibility: [- 'Wrapped in XDSField for label, description, and status message association.',- 'Token container has role="group" with aria-label.',- 'Clear all button has aria-label="Clear all".',- 'Combobox pattern provided by XDSBaseTypeahead with aria-expanded and aria-autocomplete.',- ],- keyboard:- 'Backspace on empty input removes last token; Arrow keys navigate dropdown; Enter selects highlighted item; Escape closes dropdown',usage: {- summary: 'Converts text into tokens, enabling users to filter content and make selections.',- content: `## When to use--- Convert plain text into tokens for metadata.-- Predict entries from a data source.-- Allow users to create custom entries.--## Best practices--- Don't: Apply colored backgrounds to tokens within a tokenizer.`,+ description:+ 'Tokenizer is a multi-select typeahead that converts text into token chips for selected items, enabling users to filter content and make selections from a data source. It composes XDSBaseTypeahead for search and XDSToken for chips. Avoid applying colored backgrounds to tokens within a tokenizer.',+ features: [+ 'Token chips for each selected item with remove buttons',+ 'Filtered search that automatically excludes already-selected items',+ 'Max entries to limit number of selections — input hides when limit is reached',+ 'Clear all button for bulk removal of all tokens',+ 'Custom token and item rendering via renderToken and renderItem',+ 'Backspace on empty input removes the last token',+ "Change metadata: onChange receives a second argument with type ('add' | 'create' | 'remove' | 'reorder')",+ 'Free-text token creation via hasCreate prop — shows a "Create" option in the dropdown for new values',+ ],+ accessibility: [+ 'Wrapped in XDSField for label, description, and status message association.',+ 'Token container has role="group" with aria-label.',+ 'Clear all button has aria-label="Clear all".',+ 'Combobox pattern provided by XDSBaseTypeahead with aria-expanded and aria-autocomplete.',+ 'Keyboard: Backspace on empty input removes last token; Arrow keys navigate dropdown; Enter selects highlighted item; Escape closes dropdown.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Tokenizer',- description:- '带有标记芯片的多选预输入组件,用于显示已选项目。组合使用 XDSBaseTypeahead 进行搜索和 XDSToken 显示芯片。',props: [{name: 'label',@@ -356,29 +345,32 @@ export const docsZh = {'用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值 — 不能是内联样式对象如 style={{}}。',},],- features: [- '每个已选项目显示带移除按钮的标记芯片',- '过滤搜索自动排除已选项目',- '最大条目数限制选择数量 — 达到限制时输入框隐藏',- '全部清除按钮用于批量移除所有标记',- '通过 renderToken 和 renderItem 自定义标记和项目渲染',- '在空输入框上按退格键移除最后一个标记',- "变更元数据:onChange 接收第二个参数,包含类型('add' | 'create' | 'remove' | 'reorder')",- '通过 hasCreate 属性支持自由文本令牌创建 — 在下拉列表中为新值显示 "Create" 选项',- ],theming: {targets: [{className: 'xds-tokenizer', visualProps: ['size']},],},- accessibility: [- '包裹在 XDSField 中,用于标签、描述和状态消息的关联。',- '标记容器具有 role="group" 和 aria-label。',- '全部清除按钮具有 aria-label="Clear all"。',- 'XDSBaseTypeahead 提供组合框模式,包含 aria-expanded 和 aria-autocomplete。',- ],- keyboard:- '在空输入框上按退格键移除最后一个标记;方向键导航下拉列表;Enter 选择高亮项目;Escape 关闭下拉列表',+ usage: {+ description:+ '带有标记芯片的多选预输入组件,用于显示已选项目。组合使用 XDSBaseTypeahead 进行搜索和 XDSToken 显示芯片。',+ features: [+ '每个已选项目显示带移除按钮的标记芯片',+ '过滤搜索自动排除已选项目',+ '最大条目数限制选择数量 — 达到限制时输入框隐藏',+ '全部清除按钮用于批量移除所有标记',+ '通过 renderToken 和 renderItem 自定义标记和项目渲染',+ '在空输入框上按退格键移除最后一个标记',+ "变更元数据:onChange 接收第二个参数,包含类型('add' | 'create' | 'remove' | 'reorder')",+ '通过 hasCreate 属性支持自由文本令牌创建 — 在下拉列表中为新值显示 "Create" 选项',+ ],+ accessibility: [+ '包裹在 XDSField 中,用于标签、描述和状态消息的关联。',+ '标记容器具有 role="group" 和 aria-label。',+ '全部清除按钮具有 aria-label="Clear all"。',+ 'XDSBaseTypeahead 提供组合框模式,包含 aria-expanded 和 aria-autocomplete。',+ 'Keyboard: 在空输入框上按退格键移除最后一个标记;方向键导航下拉列表;Enter 选择高亮项目;Escape 关闭下拉列表',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Toolbar/Toolbar.doc.mjs b/packages/core/src/Toolbar/Toolbar.doc.mjsindex 538c2838ff..fcf21bed00 100644--- a/packages/core/src/Toolbar/Toolbar.doc.mjs+++ b/packages/core/src/Toolbar/Toolbar.doc.mjs@@ -2,41 +2,12 @@export const docs = {name: 'Toolbar',- description:- 'General-purpose toolbar with start, center, and end content slots. Built on XDSSection with roving tabindex keyboard navigation.',keywords: ['toolbar', 'nav', 'bar', 'actions', 'buttonbar', 'header', 'footer', 'action-bar', 'control-bar'],- features: [- 'Slot-based layout — startContent, centerContent, and endContent for flexible organization',- 'Three-column centering — centerContent switches to CSS grid (1fr auto 1fr) for true centering',- 'Roving tabindex — arrow key navigation via useListFocus with orientation support',- 'Density variants — default (40px) and compact (32px) minimum heights',- 'Configurable gap — spacing scale gap between items within each slot',- 'Built on XDSSection — inherits variant, theming, and nesting behavior',- 'Composable overflow — use XDSOverflowList within slots for responsive collapsing',- ], theming: {+ theming: {targets: [{className: 'xds-toolbar', states: ['density']},],},- accessibility: [- 'Inner element renders role="toolbar" with aria-label from label prop',- 'aria-orientation reflects the orientation prop (horizontal or vertical)',- 'Roving tabindex via useListFocus — arrow keys move focus between focusable items (buttons, inputs, [tabindex="0"])',- 'Home/End keys jump to first/last focusable item',- 'Horizontal orientation: ArrowLeft/ArrowRight navigate; Vertical orientation: ArrowUp/ArrowDown navigate',- ],- keyboard:- 'ArrowLeft/ArrowRight (horizontal) or ArrowUp/ArrowDown (vertical) to move between items; Home/End for first/last item',- notes: [- 'Built on XDSSection — variant prop controls background (default: transparent)',- 'Two-slot layout (no centerContent): flex row with space-between',- 'Three-slot layout (with centerContent): CSS grid 1fr auto 1fr for true centering',- 'startContent only: fills width; endContent only: aligns to end',- 'centerContent has min-width:0 and overflow:hidden for graceful truncation',- 'No built-in overflow — compose with XDSOverflowList for responsive collapsing',- 'Density controls minimum height — compact: 32px, default: 40px',- 'Gap prop controls spacing between items within slots (default: --spacing-2 / 8px)',- ],components: [{name: 'XDSToolbar',@@ -99,46 +70,39 @@ export const docs = {], },],usage: {- summary: 'General-purpose toolbar with start, center, and end content slots.',- content: `## When to use--- Grouping related actions or controls in a horizontal bar.-- Providing contextual actions above content areas like tables or editors.`,+ description:+ 'Toolbar is a general-purpose container with start, center, and end content slots for grouping related actions or controls in a horizontal bar. Built on XDSSection with roving tabindex keyboard navigation, it is ideal for providing contextual actions above content areas like tables or editors.',+ features: [+ 'Slot-based layout — startContent, centerContent, and endContent for flexible organization',+ 'Three-column centering — centerContent switches to CSS grid (1fr auto 1fr) for true centering',+ 'Roving tabindex — arrow key navigation via useListFocus with orientation support',+ 'Density variants — default (40px) and compact (32px) minimum heights',+ 'Configurable gap — spacing scale gap between items within each slot',+ 'Built on XDSSection — inherits variant, theming, and nesting behavior',+ 'Composable overflow — use XDSOverflowList within slots for responsive collapsing',+ ],+ accessibility: [+ 'Inner element renders role="toolbar" with aria-label from label prop.',+ 'aria-orientation reflects the orientation prop (horizontal or vertical).',+ 'Roving tabindex via useListFocus — arrow keys move focus between focusable items (buttons, inputs, [tabindex="0"]).',+ 'Home/End keys jump to first/last focusable item.',+ 'Keyboard: ArrowLeft/ArrowRight (horizontal) or ArrowUp/ArrowDown (vertical) to move between items; Home/End for first/last item.',+ ],+ notes: [+ 'Built on XDSSection — variant prop controls background (default: transparent)',+ 'Two-slot layout (no centerContent): flex row with space-between',+ 'Three-slot layout (with centerContent): CSS grid 1fr auto 1fr for true centering',+ 'startContent only: fills width; endContent only: aligns to end',+ 'centerContent has min-width:0 and overflow:hidden for graceful truncation',+ 'No built-in overflow — compose with XDSOverflowList for responsive collapsing',+ 'Density controls minimum height — compact: 32px, default: 40px',+ 'Gap prop controls spacing between items within slots (default: --spacing-2 / 8px)',+ ],},};/** @type {import('../docs-types').TranslationDoc} */export const docsZh = {- description:- '通用工具栏,提供起始、居中和结束内容插槽。基于 XDSSection 构建,支持循环 Tab 键盘导航。',- features: [- '插槽式布局 — startContent、centerContent 和 endContent 灵活组织',- '三列居中 — centerContent 切换为 CSS grid(1fr auto 1fr)实现真正居中',- '循环 Tab — 通过 useListFocus 实现方向键导航',- '密度变体 — default(40px)和 compact(32px)最小高度',- '可配置间距 — 使用间距尺度设置插槽内项目间距',- '基于 XDSSection — 继承变体、主题化和嵌套行为',- '可组合溢出 — 在插槽中使用 XDSOverflowList 实现响应式折叠',- ],- accessibility: [- '内部元素渲染 role="toolbar",从 label 属性设置 aria-label',- 'aria-orientation 反映 orientation 属性(horizontal 或 vertical)',- '通过 useListFocus 实现循环 Tab — 方向键在可聚焦项之间移动焦点',- 'Home/End 键跳转到第一个/最后一个可聚焦项',- '水平方向:ArrowLeft/ArrowRight 导航;垂直方向:ArrowUp/ArrowDown 导航',- ],- keyboard:- 'ArrowLeft/ArrowRight(水平)或 ArrowUp/ArrowDown(垂直)移动项目;Home/End 跳转首/末项',- notes: [- '基于 XDSSection — variant 属性控制背景(默认:transparent)',- '两插槽布局(无 centerContent):flex 行 + space-between',- '三插槽布局(有 centerContent):CSS grid 1fr auto 1fr 实现真正居中',- 'startContent 独占:填充宽度;endContent 独占:靠右对齐',- 'centerContent 设置 min-width:0 和 overflow:hidden 以优雅截断',- '无内置溢出 — 组合 XDSOverflowList 实现响应式折叠',- '密度控制最小高度 — compact: 32px,default: 40px',- 'gap 属性控制插槽内项目间距(默认:--spacing-2 / 8px)',- ],components: [{name: 'XDSToolbar',@@ -156,6 +120,37 @@ export const docsZh = {},},],+ usage: {+ description:+ '通用工具栏,提供起始、居中和结束内容插槽。基于 XDSSection 构建,支持循环 Tab 键盘导航。',+ features: [+ '插槽式布局 — startContent、centerContent 和 endContent 灵活组织',+ '三列居中 — centerContent 切换为 CSS grid(1fr auto 1fr)实现真正居中',+ '循环 Tab — 通过 useListFocus 实现方向键导航',+ '密度变体 — default(40px)和 compact(32px)最小高度',+ '可配置间距 — 使用间距尺度设置插槽内项目间距',+ '基于 XDSSection — 继承变体、主题化和嵌套行为',+ '可组合溢出 — 在插槽中使用 XDSOverflowList 实现响应式折叠',+ ],+ accessibility: [+ '内部元素渲染 role="toolbar",从 label 属性设置 aria-label',+ 'aria-orientation 反映 orientation 属性(horizontal 或 vertical)',+ '通过 useListFocus 实现循环 Tab — 方向键在可聚焦项之间移动焦点',+ 'Home/End 键跳转到第一个/最后一个可聚焦项',+ '水平方向:ArrowLeft/ArrowRight 导航;垂直方向:ArrowUp/ArrowDown 导航',+ 'Keyboard: ArrowLeft/ArrowRight(水平)或 ArrowUp/ArrowDown(垂直)移动项目;Home/End 跳转首/末项',+ ],+ notes: [+ '基于 XDSSection — variant 属性控制背景(默认:transparent)',+ '两插槽布局(无 centerContent):flex 行 + space-between',+ '三插槽布局(有 centerContent):CSS grid 1fr auto 1fr 实现真正居中',+ 'startContent 独占:填充宽度;endContent 独占:靠右对齐',+ 'centerContent 设置 min-width:0 和 overflow:hidden 以优雅截断',+ '无内置溢出 — 组合 XDSOverflowList 实现响应式折叠',+ '密度控制最小高度 — compact: 32px,default: 40px',+ 'gap 属性控制插槽内项目间距(默认:--spacing-2 / 8px)',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjsindex 80ddc77dbb..43b16e8d38 100644--- a/packages/core/src/Tooltip/Tooltip.doc.mjs+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs@@ -2,32 +2,8 @@export const docs = {name: 'Tooltip',- description:- 'A hover/focus triggered tooltip for displaying short, non-interactive text anchored to a trigger element.',keywords: ["tooltip","hint","infotip","title","hover","flyout","balloon","helpertext"],- features: [- 'CSS Anchor Positioning for automatic placement relative to trigger elements',- 'Popover API for top-layer rendering — no React portals needed',- 'Hover triggers with configurable show and hide delays',- 'Focus triggers with auto-detection for focusable elements',- 'Inverted color palette (dark background, light text) for high contrast',- 'display:contents wrapper preserves children refs',- 'Hover indication (dashed underline) for text-only triggers',- 'Sibling mode via anchorRef for external trigger elements',- ],- notes: [- 'Unlike HoverCard, tooltips don\'t stay open when hovering the tooltip content.',- 'Tooltips have shorter delays and use inverted colors for high contrast.',- 'Tooltips are for short, non-interactive text. For interactive content, use XDSHoverCard or XDSPopover.',- 'In sibling mode (anchorRef prop), XDSTooltip attaches to an external ref rather than wrapping children.',- 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',- ],- accessibility: [- 'Links the tooltip content to the trigger via aria-describedby.',- 'When composing multiple aria-describedby sources, merge them with a utility.',- ],- keyboard:- 'Focus on the trigger shows the tooltip. Blur hides it.', components: [+ components: [{name: 'XDSTooltip',description:@@ -157,53 +133,36 @@ export const docs = {],},usage: {- summary: 'Non-interactive hints that provide additional information in the context of a specific UI element.',- content: `## When to use--- Progressive disclosure of non-interactive content.-- Non-interruptive education.-- Show full text for truncated labels.--## When NOT to use--- For interactive content, use HoverCard instead.--## Best practices--- Limit tooltip content to approximately 140 characters.-- Place tooltip 8px from the context element.-- Supported placements: above, below, left, right.`,+ description:+ 'Tooltip provides non-interactive hints that display additional information in the context of a specific UI element, triggered by hover or focus. It is ideal for progressive disclosure, non-interruptive education, or showing full text for truncated labels. For interactive content, use HoverCard instead; limit tooltip content to approximately 140 characters.',+ features: [+ 'CSS Anchor Positioning for automatic placement relative to trigger elements',+ 'Popover API for top-layer rendering — no React portals needed',+ 'Hover triggers with configurable show and hide delays',+ 'Focus triggers with auto-detection for focusable elements',+ 'Inverted color palette (dark background, light text) for high contrast',+ 'display:contents wrapper preserves children refs',+ 'Hover indication (dashed underline) for text-only triggers',+ 'Sibling mode via anchorRef for external trigger elements',+ ],+ accessibility: [+ 'Links the tooltip content to the trigger via aria-describedby.',+ 'When composing multiple aria-describedby sources, merge them with a utility.',+ 'Keyboard: Focus on the trigger shows the tooltip; blur hides it.',+ ],+ notes: [+ 'Unlike HoverCard, tooltips don\'t stay open when hovering the tooltip content.',+ 'Tooltips have shorter delays and use inverted colors for high contrast.',+ 'Tooltips are for short, non-interactive text. For interactive content, use XDSHoverCard or XDSPopover.',+ 'In sibling mode (anchorRef prop), XDSTooltip attaches to an external ref rather than wrapping children.',+ 'LayerPlacement values: above | below | start | end. LayerAlignment values: start | center | end.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Tooltip',- description:- '悬停/聚焦触发的工具提示,用于显示锚定在触发元素上的简短、非交互式文本。',- features: [- 'CSS 锚点定位,自动相对于触发元素放置',- 'Popover API 实现顶层渲染 — 无需 React 传送门',- '悬停触发,支持可配置的显示和隐藏延迟',- '聚焦触发,自动检测可聚焦元素',- '反转色调(深色背景、浅色文字)以实现高对比度',- 'display:contents 包装器保留子元素引用',- '悬停指示(虚线下划线)用于纯文本触发器',- '通过 anchorRef 的兄弟模式用于外部触发元素',- ],- notes: [- '与 HoverCard 不同,悬停工具提示内容时工具提示不会保持打开状态。',- '工具提示具有更短的延迟,并使用反转颜色以实现高对比度。',- '工具提示用于简短的非交互式文本。对于交互式内容,请使用 XDSHoverCard 或 XDSPopover。',- '在兄弟模式下(anchorRef 属性),XDSTooltip 附加到外部引用而不是包裹子元素。',- 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',- ],- accessibility: [- '通过 aria-describedby 将工具提示内容链接到触发器。',- '当组合多个 aria-describedby 来源时,使用工具函数合并它们。',- ],- keyboard:- '聚焦触发器显示工具提示。失焦隐藏工具提示。',components: [{name: 'XDSTooltip',@@ -334,6 +293,32 @@ export const docsZh = {{className: 'xds-tooltip'},],},+ usage: {+ description:+ '悬停/聚焦触发的工具提示,用于显示锚定在触发元素上的简短、非交互式文本。',+ features: [+ 'CSS 锚点定位,自动相对于触发元素放置',+ 'Popover API 实现顶层渲染 — 无需 React 传送门',+ '悬停触发,支持可配置的显示和隐藏延迟',+ '聚焦触发,自动检测可聚焦元素',+ '反转色调(深色背景、浅色文字)以实现高对比度',+ 'display:contents 包装器保留子元素引用',+ '悬停指示(虚线下划线)用于纯文本触发器',+ '通过 anchorRef 的兄弟模式用于外部触发元素',+ ],+ accessibility: [+ '通过 aria-describedby 将工具提示内容链接到触发器。',+ '当组合多个 aria-describedby 来源时,使用工具函数合并它们。',+ 'Keyboard: 聚焦触发器显示工具提示。失焦隐藏工具提示。',+ ],+ notes: [+ '与 HoverCard 不同,悬停工具提示内容时工具提示不会保持打开状态。',+ '工具提示具有更短的延迟,并使用反转颜色以实现高对比度。',+ '工具提示用于简短的非交互式文本。对于交互式内容,请使用 XDSHoverCard 或 XDSPopover。',+ '在兄弟模式下(anchorRef 属性),XDSTooltip 附加到外部引用而不是包裹子元素。',+ 'LayerPlacement 值:above | below | start | end。LayerAlignment 值:start | center | end。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjsindex 591849f461..aadacecdba 100644--- a/packages/core/src/TopNav/TopNav.doc.mjs+++ b/packages/core/src/TopNav/TopNav.doc.mjs@@ -2,17 +2,8 @@export const docs = {name: 'TopNav',- description:- 'Top navigation bar component for application headers with slot-based layout and companion nav item components.',keywords: ["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],- features: [- 'Slot-based layout — heading, startContent, centerContent, and endContent slots for flexible organization',- 'Three-column centering — when centerContent is provided, switches to CSS grid (1fr auto 1fr) for true horizontal centering',- 'Companion components — XDSTopNavHeading, XDSTopNavItem, XDSTopNavMenu, XDSTopNavMegaMenu',- 'Accessible — uses role="navigation" with aria-label, aria-current="page" on selected items',- 'Themeable via className — target .xds-top-nav and sub-component classes',- 'Link customization — XDSTopNavItem accepts an as prop to swap the anchor element (e.g. for React Router)',- ], theming: {+ theming: {targets: [{className: 'xds-top-nav', states: ['mode']},{className: 'xds-top-nav-item', states: ['mode']},@@ -23,26 +14,6 @@ export const docs = {{className: 'xds-top-nav-menu'},],},- accessibility: [- 'XDSTopNav renders a <nav> element with role="navigation" and aria-label set from the label prop',- 'XDSTopNavItem sets aria-current="page" when isSelected is true',- 'XDSTopNavItem sets aria-label when isIconOnly is true, keeping the item accessible.',- 'XDSTopNavItem sets aria-disabled and tabIndex=-1 when isDisabled is true',- 'XDSTopNavMenu sets aria-haspopup="true" on the trigger button',- 'XDSTopNavMegaMenu sets aria-haspopup="true" and aria-expanded on the trigger button',- 'XDSTopNavMegaMenu menu items are unreachable by keyboard (tabIndex=-1) when the panel is closed',- 'Escape key closes the XDSTopNavMegaMenu panel',- ],- keyboard:- 'Tab to navigate between items; Escape closes XDSTopNavMegaMenu panels',- notes: [- 'Default height is 48px (--spacing-12) with 16px horizontal padding',- 'Without centerContent: heading and startContent grow to push endContent right (flex layout)',- 'With centerContent: switches to CSS grid (gridTemplateColumns: 1fr auto 1fr) — the right column is always rendered even when endContent is absent to maintain the three-column structure',- 'Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself',- 'Dividers are controlled by the layout system (e.g. XDSLayoutHeader hasDivider), not TopNav',- 'XDSTopNavMegaMenu panels position relative to the nearest positioned ancestor — wrap XDSTopNav in a container with position: relative for correct full-width behavior',- ],components: [{name: 'XDSTopNav',@@ -327,19 +298,34 @@ export const docs = {},],usage: {- summary: 'Horizontal navigation bar for product-level navigation.',- content: `## When to use--- 5 or fewer nav items that should always be visible.-- Items don't require icons.-- Minimal navigation paired with controls or filters.-- Can combine with side nav for ecosystem tools.--## When NOT to use--- Complex navigation hierarchies.-- Products without clear ownership.-- Don't use to filter content \u2014 use tabs or filter buttons instead.`,+ description:+ 'TopNav is a horizontal navigation bar for product-level navigation in application headers, featuring a slot-based layout with heading, startContent, centerContent, and endContent slots, plus companion nav item and menu components. Use for 5 or fewer always-visible nav items or minimal navigation paired with controls. Do not use for complex navigation hierarchies or to filter content—use tabs or filter buttons instead.',+ features: [+ 'Slot-based layout — heading, startContent, centerContent, and endContent slots for flexible organization',+ 'Three-column centering — when centerContent is provided, switches to CSS grid (1fr auto 1fr) for true horizontal centering',+ 'Companion components — XDSTopNavHeading, XDSTopNavItem, XDSTopNavMenu, XDSTopNavMegaMenu',+ 'Themeable via className — target .xds-top-nav and sub-component classes',+ 'Link customization — XDSTopNavItem accepts an as prop to swap the anchor element (e.g. for React Router)',+ ],+ accessibility: [+ 'XDSTopNav renders a <nav> element with role="navigation" and aria-label set from the label prop.',+ 'XDSTopNavItem sets aria-current="page" when isSelected is true.',+ 'XDSTopNavItem sets aria-label when isIconOnly is true, keeping the item accessible.',+ 'XDSTopNavItem sets aria-disabled and tabIndex=-1 when isDisabled is true.',+ 'XDSTopNavMenu sets aria-haspopup="true" on the trigger button.',+ 'XDSTopNavMegaMenu sets aria-haspopup="true" and aria-expanded on the trigger button.',+ 'XDSTopNavMegaMenu menu items are unreachable by keyboard (tabIndex=-1) when the panel is closed.',+ 'Escape key closes the XDSTopNavMegaMenu panel.',+ 'Keyboard: Tab to navigate between items; Escape closes XDSTopNavMegaMenu panels.',+ ],+ notes: [+ 'Default height is 48px (--spacing-12) with 16px horizontal padding',+ 'Without centerContent: heading and startContent grow to push endContent right (flex layout)',+ 'With centerContent: switches to CSS grid (gridTemplateColumns: 1fr auto 1fr) — the right column is always rendered even when endContent is absent to maintain the three-column structure',+ 'Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself',+ 'Dividers are controlled by the layout system (e.g. XDSLayoutHeader hasDivider), not TopNav',+ 'XDSTopNavMegaMenu panels position relative to the nearest positioned ancestor — wrap XDSTopNav in a container with position: relative for correct full-width behavior',+ ],anatomy: [{name: 'Product icon and name', required: true, description: 'Identifies the product in the navigation bar.'},{name: 'Navigation items', required: true, description: 'Primary links for product-level destinations.'},@@ -352,16 +338,6 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'TopNav',- description:- '应用程序头部的顶部导航栏组件,采用插槽式布局和配套的导航项组件。',- features: [- '插槽式布局 — heading、startContent、centerContent 和 endContent 插槽实现灵活组织',- '三列居中 — 提供 centerContent 时,切换为 CSS grid(1fr auto 1fr)实现真正的水平居中',- '配套组件 — XDSTopNavHeading、XDSTopNavItem、XDSTopNavMenu、XDSTopNavMegaMenu',- '无障碍 — 使用 role="navigation" 和 aria-label,选中项设置 aria-current="page"',- '通过 className 支持主题化 — 可定位 .xds-top-nav 和子组件类',- '链接自定义 — XDSTopNavItem 接受 as 属性来替换锚点元素(例如用于 React Router)',- ],theming: {targets: [{className: 'xds-top-nav', states: ['mode']},@@ -373,26 +349,6 @@ export const docsZh = {{className: 'xds-top-nav-menu'},],},- accessibility: [- 'XDSTopNav 渲染一个 <nav> 元素,包含 role="navigation" 和从 label 属性设置的 aria-label',- '当 isSelected 为 true 时,XDSTopNavItem 设置 aria-current="page"',- 'XDSTopNavItem 为仅图标项设置 aria-label(当提供图标且没有子元素或可见标签文本时)',- '当 isDisabled 为 true 时,XDSTopNavItem 设置 aria-disabled 和 tabIndex=-1',- 'XDSTopNavMenu 在触发按钮上设置 aria-haspopup="true"',- 'XDSTopNavMegaMenu 在触发按钮上设置 aria-haspopup="true" 和 aria-expanded',- '当面板关闭时,XDSTopNavMegaMenu 菜单项对键盘不可达(tabIndex=-1)',- 'Escape 键关闭 XDSTopNavMegaMenu 面板',- ],- keyboard:- 'Tab 在项目之间导航;Escape 关闭 XDSTopNavMegaMenu 面板',- notes: [- '默认高度为 48px(--spacing-12),水平内边距 16px',- '无 centerContent 时:heading 和 startContent 增长以将 endContent 推向右侧(flex 布局)',- '有 centerContent 时:切换为 CSS grid(gridTemplateColumns: 1fr auto 1fr)— 即使 endContent 不存在,右列也始终渲染以维持三列结构',- '定位(sticky/fixed)由布局系统处理(例如 XDSAppShell),而非 TopNav 本身',- '分隔线由布局系统控制(例如 XDSLayoutHeader hasDivider),而非 TopNav',- 'XDSTopNavMegaMenu 面板相对于最近的定位祖先定位 — 将 XDSTopNav 包裹在具有 position: relative 的容器中以获得正确的全宽行为',- ],components: [{name: 'XDSTopNav',@@ -670,6 +626,37 @@ export const docsZh = {],},],+ usage: {+ description:+ '应用程序头部的顶部导航栏组件,采用插槽式布局和配套的导航项组件。',+ features: [+ '插槽式布局 — heading、startContent、centerContent 和 endContent 插槽实现灵活组织',+ '三列居中 — 提供 centerContent 时,切换为 CSS grid(1fr auto 1fr)实现真正的水平居中',+ '配套组件 — XDSTopNavHeading、XDSTopNavItem、XDSTopNavMenu、XDSTopNavMegaMenu',+ '无障碍 — 使用 role="navigation" 和 aria-label,选中项设置 aria-current="page"',+ '通过 className 支持主题化 — 可定位 .xds-top-nav 和子组件类',+ '链接自定义 — XDSTopNavItem 接受 as 属性来替换锚点元素(例如用于 React Router)',+ ],+ accessibility: [+ 'XDSTopNav 渲染一个 <nav> 元素,包含 role="navigation" 和从 label 属性设置的 aria-label',+ '当 isSelected 为 true 时,XDSTopNavItem 设置 aria-current="page"',+ 'XDSTopNavItem 为仅图标项设置 aria-label(当提供图标且没有子元素或可见标签文本时)',+ '当 isDisabled 为 true 时,XDSTopNavItem 设置 aria-disabled 和 tabIndex=-1',+ 'XDSTopNavMenu 在触发按钮上设置 aria-haspopup="true"',+ 'XDSTopNavMegaMenu 在触发按钮上设置 aria-haspopup="true" 和 aria-expanded',+ '当面板关闭时,XDSTopNavMegaMenu 菜单项对键盘不可达(tabIndex=-1)',+ 'Escape 键关闭 XDSTopNavMegaMenu 面板',+ 'Keyboard: Tab 在项目之间导航;Escape 关闭 XDSTopNavMegaMenu 面板',+ ],+ notes: [+ '默认高度为 48px(--spacing-12),水平内边距 16px',+ '无 centerContent 时:heading 和 startContent 增长以将 endContent 推向右侧(flex 布局)',+ '有 centerContent 时:切换为 CSS grid(gridTemplateColumns: 1fr auto 1fr)— 即使 endContent 不存在,右列也始终渲染以维持三列结构',+ '定位(sticky/fixed)由布局系统处理(例如 XDSAppShell),而非 TopNav 本身',+ '分隔线由布局系统控制(例如 XDSLayoutHeader hasDivider),而非 TopNav',+ 'XDSTopNavMegaMenu 面板相对于最近的定位祖先定位 — 将 XDSTopNav 包裹在具有 position: relative 的容器中以获得正确的全宽行为',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjsindex 3752a0271d..0e63aa11c3 100644--- a/packages/core/src/TreeList/TreeList.doc.mjs+++ b/packages/core/src/TreeList/TreeList.doc.mjs@@ -2,38 +2,13 @@export const docs = {name: 'TreeList',- description:- 'Data-driven tree list component for rendering hierarchical data with expand/collapse, branch lines, and interactive items. Uses a flat items array with recursive children — no composition, no cloneElement.', keywords: ['tree', 'hierarchy', 'nested', 'accordion', 'folder', 'expand', 'collapse', 'treeview', 'outline'],- features: [- 'Data-driven API — items array with recursive children',- 'Internal expansion state — seed via isExpanded on each item',- 'Branch connector lines with center/top alignment',- 'Density variants: compact, balanced, spacious',- 'Interactive items via invisible button or anchor pattern',- 'Start and end content slots (icon, avatar, badge)',- 'Optional header associated via aria-labelledby',- 'No context for positional data — computed at render time',- ], accessibility: [- 'Semantic <ul role="tree"> with <li role="treeitem"> elements',- '<ul role="group"> for nested children',- 'aria-expanded on items with children',- 'aria-labelledby links the header element to the tree',- 'aria-selected on selected items',- 'aria-disabled on disabled items',- 'Chevron toggle button with aria-label="Toggle children"',- 'Interactive items are keyboard-focusable via Tab',- ],+ keywords: ['tree', 'hierarchy', 'nested', 'accordion', 'folder', 'expand', 'collapse', 'treeview', 'outline'],theming: {targets: [{className: 'xds-tree-list', visualProps: ['density']},{className: 'xds-tree-list-item', states: ['selected', 'disabled']},],},- notes: [- 'Data-driven pattern: Unlike XDSList which uses children composition, XDSTreeList accepts an items array. This avoids cloneElement and enables the component to compute positional data (nestedLevel, isLast, ancestorsIsLast) at render time.',- 'Expansion control: Expansion state is managed internally. Seed initial state by setting isExpanded: true on individual items in the data.',- 'Performance: React reconciliation via key={id} means expanding a node only causes DOM updates in that subtree. Siblings with stable keys and same props are skipped by React.',- ],components: [{name: 'XDSTreeList',@@ -68,12 +43,33 @@ export const docs = {},],usage: {- summary: 'Displays hierarchical information with expandable and collapsible nodes.',- content: `## When to use--- For file system navigators.-- For visualizing hierarchical data.-- When expand/collapse interactions are needed.`,+ description:+ 'TreeList is a data-driven component for displaying hierarchical information with expandable and collapsible nodes. It uses a flat items array with recursive children for rendering hierarchical data with branch lines and interactive items—no composition, no cloneElement. Use for file system navigators or visualizing hierarchical data.',+ features: [+ 'Data-driven API — items array with recursive children',+ 'Internal expansion state — seed via isExpanded on each item',+ 'Branch connector lines with center/top alignment',+ 'Density variants: compact, balanced, spacious',+ 'Interactive items via invisible button or anchor pattern',+ 'Start and end content slots (icon, avatar, badge)',+ 'Optional header associated via aria-labelledby',+ 'No context for positional data — computed at render time',+ ],+ accessibility: [+ 'Semantic <ul role="tree"> with <li role="treeitem"> elements',+ '<ul role="group"> for nested children',+ 'aria-expanded on items with children',+ 'aria-labelledby links the header element to the tree',+ 'aria-selected on selected items',+ 'aria-disabled on disabled items',+ 'Chevron toggle button with aria-label="Toggle children"',+ 'Interactive items are keyboard-focusable via Tab',+ ],+ notes: [+ 'Data-driven pattern: Unlike XDSList which uses children composition, XDSTreeList accepts an items array. This avoids cloneElement and enables the component to compute positional data (nestedLevel, isLast, ancestorsIsLast) at render time.',+ 'Expansion control: Expansion state is managed internally. Seed initial state by setting isExpanded: true on individual items in the data.',+ 'Performance: React reconciliation via key={id} means expanding a node only causes DOM updates in that subtree. Siblings with stable keys and same props are skipped by React.',+ ],},};@@ -86,39 +82,12 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'TreeList',- description:- '数据驱动的树列表组件,用于渲染层级数据,支持展开/折叠、分支线条和交互式项目。使用扁平 items 数组配合递归 children,无需组合模式,无需 cloneElement。',- features: [- '数据驱动 API — items 数组配合递归 children',- '内部展开状态 — 通过每项的 isExpanded 设置初始值',- '分支连接线,支持居中/顶部对齐',- '密度变体:compact、balanced、spacious',- '交互式项目,通过不可见按钮或锚点模式',- '起始和结束内容插槽(图标、头像、徽章)',- '可选标题,通过 aria-labelledby 关联',- '无需位置数据上下文 — 渲染时计算',- ],- accessibility: [- '语义化 <ul role="tree"> 配合 <li role="treeitem"> 元素',- '嵌套子项使用 <ul role="group">',- '有子项的元素设置 aria-expanded',- 'aria-labelledby 将标题元素与树关联',- '选中项设置 aria-selected',- '禁用项设置 aria-disabled',- '折叠切换按钮带有 aria-label="Toggle children"',- '交互式项目可通过 Tab 键获得焦点',- ],theming: {targets: [{className: 'xds-tree-list', visualProps: ['density']},{className: 'xds-tree-list-item', states: ['selected', 'disabled']},],},- notes: [- '数据驱动模式:与使用 children 组合的 XDSList 不同,XDSTreeList 接受 items 数组。这避免了 cloneElement,使组件能在渲染时计算位置数据(nestedLevel、isLast、ancestorsIsLast)。',- '展开控制:展开状态在内部管理。通过在数据中设置 isExpanded: true 来设定初始状态。',- '性能:通过 key={id} 进行 React 协调意味着展开节点只会导致该子树的 DOM 更新。具有稳定 key 和相同 props 的兄弟节点会被 React 跳过。',- ],components: [{name: 'XDSTreeList',@@ -153,6 +122,35 @@ export const docsZh = {],},],+ usage: {+ description:+ '数据驱动的树列表组件,用于渲染层级数据,支持展开/折叠、分支线条和交互式项目。使用扁平 items 数组配合递归 children,无需组合模式,无需 cloneElement。',+ features: [+ '数据驱动 API — items 数组配合递归 children',+ '内部展开状态 — 通过每项的 isExpanded 设置初始值',+ '分支连接线,支持居中/顶部对齐',+ '密度变体:compact、balanced、spacious',+ '交互式项目,通过不可见按钮或锚点模式',+ '起始和结束内容插槽(图标、头像、徽章)',+ '可选标题,通过 aria-labelledby 关联',+ '无需位置数据上下文 — 渲染时计算',+ ],+ accessibility: [+ '语义化 <ul role="tree"> 配合 <li role="treeitem"> 元素',+ '嵌套子项使用 <ul role="group">',+ '有子项的元素设置 aria-expanded',+ 'aria-labelledby 将标题元素与树关联',+ '选中项设置 aria-selected',+ '禁用项设置 aria-disabled',+ '折叠切换按钮带有 aria-label="Toggle children"',+ '交互式项目可通过 Tab 键获得焦点',+ ],+ notes: [+ '数据驱动模式:与使用 children 组合的 XDSList 不同,XDSTreeList 接受 items 数组。这避免了 cloneElement,使组件能在渲染时计算位置数据(nestedLevel、isLast、ancestorsIsLast)。',+ '展开控制:展开状态在内部管理。通过在数据中设置 isExpanded: true 来设定初始状态。',+ '性能:通过 key={id} 进行 React 协调意味着展开节点只会导致该子树的 DOM 更新。具有稳定 key 和相同 props 的兄弟节点会被 React 跳过。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjsindex 1efdf1ed92..65fe3bf24f 100644--- a/packages/core/src/Typeahead/Typeahead.doc.mjs+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs@@ -2,17 +2,8 @@export const docs = {name: 'Typeahead',- description:- 'Searchable dropdown components for single-item selection with keyboard navigation. Supports async and sync search via a searchSource interface.',keywords: ["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],- features: [- 'Async and sync search via a searchSource interface with search() and bootstrap() methods',- 'Bootstrap results shown on focus before typing (via hasEntriesOnFocus)',- 'Edit mode: clicking selected token enters edit mode with text pre-populated and selected',- 'Combobox ARIA pattern for full accessibility',- 'Debounced search with configurable delay (default 150ms, set to 0 for synchronous sources)',- 'Two-layer architecture: XDSBaseTypeahead provides the engine, XDSTypeahead adds field chrome',- ], components: [+ components: [{name: 'XDSTypeahead',description:@@ -300,16 +291,6 @@ export const docs = {],},],- accessibility: [- 'Uses combobox ARIA pattern with role="combobox", aria-expanded, aria-autocomplete="list".',- 'Dropdown uses role="listbox" with role="option" on each item.',- 'aria-activedescendant tracks the highlighted option.',- 'Selected item has aria-selected="true".',- 'Loading state has role="status" with aria-label="Loading".',- 'XDSTypeahead wraps in XDSField for label and description association.',- ],- keyboard:- 'Arrow keys navigate dropdown items; Enter selects highlighted item; Escape closes dropdown or restores previous value in edit mode; Home/End jump to first/last item',theming: {targets: [{className: 'xds-typeahead', visualProps: ['status']},@@ -317,39 +298,38 @@ export const docs = {{className: 'xds-typeahead-item'},],},- notes: [- 'XDSSearchSource requires items to implement XDSSearchableItem ({ id: string; label: string; [key: string]: unknown }).',- 'Edit mode in XDSTypeahead: clicking the selected token removes it visually, populates the input with the label text, and selects all. Blurring without selecting restores the original token.',- 'XDSBaseTypeahead renders only the <input> and dropdown popover — consumers provide their own wrapper.',- 'If item has an element property, XDSTypeaheadItem renders it directly instead of the standard layout.',- ],usage: {- summary: 'Searchable dropdown for single-item selection with keyboard navigation and async data support.',- content: `## When to use--- Selecting a single item from a large or dynamic dataset.-- Users benefit from search-as-you-type to find options.--## When NOT to use--- A small, fixed list of options (use Selector instead).-- Multiple selections needed (use Tokenizer instead).`,+ description:+ 'Typeahead is a searchable dropdown for single-item selection with keyboard navigation and async/sync data support via a searchSource interface. Use when selecting from a large or dynamic dataset where search-as-you-type helps users find options. For small fixed lists, use Selector instead; for multiple selections, use Tokenizer.',+ features: [+ 'Async and sync search via a searchSource interface with search() and bootstrap() methods',+ 'Bootstrap results shown on focus before typing (via hasEntriesOnFocus)',+ 'Edit mode: clicking selected token enters edit mode with text pre-populated and selected',+ 'Combobox ARIA pattern for full accessibility',+ 'Debounced search with configurable delay (default 150ms, set to 0 for synchronous sources)',+ 'Two-layer architecture: XDSBaseTypeahead provides the engine, XDSTypeahead adds field chrome',+ ],+ accessibility: [+ 'Uses combobox ARIA pattern with role="combobox", aria-expanded, aria-autocomplete="list".',+ 'Dropdown uses role="listbox" with role="option" on each item.',+ 'aria-activedescendant tracks the highlighted option.',+ 'Selected item has aria-selected="true".',+ 'Loading state has role="status" with aria-label="Loading".',+ 'XDSTypeahead wraps in XDSField for label and description association.',+ 'Keyboard: Arrow keys navigate dropdown items; Enter selects highlighted item; Escape closes dropdown or restores previous value in edit mode; Home/End jump to first/last item.',+ ],+ notes: [+ 'XDSSearchSource requires items to implement XDSSearchableItem ({ id: string; label: string; [key: string]: unknown }).',+ 'Edit mode in XDSTypeahead: clicking the selected token removes it visually, populates the input with the label text, and selects all. Blurring without selecting restores the original token.',+ 'XDSBaseTypeahead renders only the <input> and dropdown popover — consumers provide their own wrapper.',+ 'If item has an element property, XDSTypeaheadItem renders it directly instead of the standard layout.',+ ],},};/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Typeahead',- description:- '可搜索的下拉组件,用于单项选择并支持键盘导航。通过 searchSource 接口支持异步和同步搜索。',- features: [- '通过 searchSource 接口支持异步和同步搜索,包含 search() 和 bootstrap() 方法',- '聚焦时在输入前显示引导结果(通过 hasEntriesOnFocus)',- '编辑模式:点击已选标记进入编辑模式,文本已预填并选中',- '组合框 ARIA 模式,实现完整的无障碍支持',- '防抖搜索,延迟可配置(默认 150ms,同步数据源设置为 0)',- '双层架构:XDSBaseTypeahead 提供引擎,XDSTypeahead 添加字段外观',- ],components: [{name: 'XDSTypeahead',@@ -639,16 +619,6 @@ export const docsZh = {],},],- accessibility: [- '使用组合框 ARIA 模式,包含 role="combobox"、aria-expanded、aria-autocomplete="list"。',- '下拉列表使用 role="listbox",每个项使用 role="option"。',- 'aria-activedescendant 追踪高亮选项。',- '选中项具有 aria-selected="true"。',- '加载状态具有 role="status" 和 aria-label="Loading"。',- 'XDSTypeahead 包裹在 XDSField 中,用于标签和描述的关联。',- ],- keyboard:- '方向键导航下拉列表项目;Enter 选择高亮项目;Escape 关闭下拉列表或在编辑模式中恢复之前的值;Home/End 跳转到第一个/最后一个项目',theming: {targets: [{className: 'xds-typeahead', visualProps: ['status']},@@ -656,12 +626,33 @@ export const docsZh = {{className: 'xds-typeahead-item'},],},- notes: [- 'XDSSearchSource 要求项目实现 XDSSearchableItem({ id: string; label: string; [key: string]: unknown })。',- 'XDSTypeahead 中的编辑模式:点击已选标记会视觉移除它,将标签文本填入输入框并全选。在未选择的情况下失焦会恢复原始标记。',- 'XDSBaseTypeahead 仅渲染 <input> 和下拉弹出框 — 使用者需提供自己的包装器。',- '如果项目具有 element 属性,XDSTypeaheadItem 会直接渲染它而不是标准布局。',- ],+ usage: {+ description:+ '可搜索的下拉组件,用于单项选择并支持键盘导航。通过 searchSource 接口支持异步和同步搜索。',+ features: [+ '通过 searchSource 接口支持异步和同步搜索,包含 search() 和 bootstrap() 方法',+ '聚焦时在输入前显示引导结果(通过 hasEntriesOnFocus)',+ '编辑模式:点击已选标记进入编辑模式,文本已预填并选中',+ '组合框 ARIA 模式,实现完整的无障碍支持',+ '防抖搜索,延迟可配置(默认 150ms,同步数据源设置为 0)',+ '双层架构:XDSBaseTypeahead 提供引擎,XDSTypeahead 添加字段外观',+ ],+ accessibility: [+ '使用组合框 ARIA 模式,包含 role="combobox"、aria-expanded、aria-autocomplete="list"。',+ '下拉列表使用 role="listbox",每个项使用 role="option"。',+ 'aria-activedescendant 追踪高亮选项。',+ '选中项具有 aria-selected="true"。',+ '加载状态具有 role="status" 和 aria-label="Loading"。',+ 'XDSTypeahead 包裹在 XDSField 中,用于标签和描述的关联。',+ 'Keyboard: 方向键导航下拉列表项目;Enter 选择高亮项目;Escape 关闭下拉列表或在编辑模式中恢复之前的值;Home/End 跳转到第一个/最后一个项目',+ ],+ notes: [+ 'XDSSearchSource 要求项目实现 XDSSearchableItem({ id: string; label: string; [key: string]: unknown })。',+ 'XDSTypeahead 中的编辑模式:点击已选标记会视觉移除它,将标签文本填入输入框并全选。在未选择的情况下失焦会恢复原始标记。',+ 'XDSBaseTypeahead 仅渲染 <input> 和下拉弹出框 — 使用者需提供自己的包装器。',+ '如果项目具有 element 属性,XDSTypeaheadItem 会直接渲染它而不是标准布局。',+ ],+ },};/** @type {import('../docs-types').TranslationDoc} */diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex 030d49efd5..49cbebc317 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -160,31 +160,32 @@ export interface AnatomyElement {}/**- * Usage guidance for a component — when to use it, when not to,- * and the visual anatomy of its parts.+ * Unified documentation for a component — what it is, what it can do,+ * accessibility, implementation notes, and visual anatomy.*- * `summary` is a design-oriented overview (vs. the developer-focused `description`).- * `content` is freeform markdown for usage guidance — authors can structure it- * however they like (when to use, when not to, do/don't, migration notes, etc.).- * `anatomy` is a structured breakdown of the component's visual elements.+ * All prose about a component lives here. The only fields that stay on+ * BaseDoc are `name`, `keywords`, and `theming` (identity/discovery/styling).*/export interface UsageDoc {- /** Design-oriented summary of the component's purpose and role in the UI.- * More conceptual than `description` — explains *what problem* the component- * solves rather than *what API* it exposes.- * e.g. `"Buttons communicate calls to action and allow users to interact- * with pages in a variety of ways."` */- summary?: string;- /** Freeform markdown covering usage guidance. Use markdown headers and lists- * to organize content. Common sections include "When to use", "When NOT to use",- * but authors are free to structure this however makes sense.- *- * @example- * ```- * `## When to use\n- To trigger an action\n- To navigate when the action is primary\n\n## When NOT to use\n- For navigation — use Link instead`- * ```- */- content?: string;+ /** What the component is and when to use it. 1-3 sentences combining+ * the developer summary with design guidance.+ * e.g. `"Buttons provide visual cues for actions and events. XDSButton+ * supports primary, secondary, ghost, and destructive variants with+ * built-in loading states. Use secondary for most actions, reserve+ * primary for a single emphasized action per layout."` */+ description: string;+ /** Key capabilities as short bullet points. Each string is one feature.+ * Focus on what the component CAN DO, not how it's implemented.+ * e.g. `"Variants: 'primary', 'secondary', 'ghost', 'destructive'"` */+ features?: string[];+ /** Accessibility notes including keyboard interaction. Each string is+ * one self-contained note. Keyboard bindings use the format+ * `"Keyboard: Enter/Space activates; Tab/Shift+Tab moves focus"`.+ * e.g. `"Uses native <dialog> with showModal() for correct ARIA modal semantics."` */+ accessibility?: string[];+ /** Technical implementation notes — architecture decisions, performance+ * considerations, caveats. Only internal details, not usage guidance. */+ notes?: string[];/** Structural/visual anatomy of the component. Each entry describes one* element that makes up the component (icon slot, label, container, etc.).* Order entries in the visual reading order (leading → trailing, top → bottom). */@@ -199,22 +200,12 @@ interface BaseDoc {/** Directory name without the XDS prefix, PascalCase.* e.g. `"Button"`, `"Table"`, `"TextInput"`, `"AppShell"` */name: string;- /** One-sentence summary of the component or component group.- * Be specific enough to differentiate from similar components.- * e.g. `"Data-driven table with rich cell content via renderCell."` */- description: string;/** Search keywords for CLI discovery. Terms a developer might type when* looking for this component: synonyms, related UI concepts, and common* names from other design systems (MUI, Chakra, Radix, shadcn).* Lowercase only. Used by `xds component <term>` for fuzzy matching.* e.g. `['accordion', 'expand', 'toggle', 'disclosure']` for Collapsible */keywords?: string[];- /** Key capabilities as short bullet points. Each string is one feature.- * Strongly recommended even though optional — all existing components- * include this field. Use "Category: details" format.- * e.g. `"Variants: 'primary', 'secondary', 'ghost', 'destructive'"`,- * `"Single & range modes: pass a number or [number, number]"` */- features?: string[];/** Theming configuration. Documents the stable CSS class names* rendered by this component that themes can target via `@scope`* selectors in `defineTheme`. */@@ -235,25 +226,9 @@ interface BaseDoc {* internal variables must not be listed here. */cssProperties?: CSSPropertyDoc[];};- /** Accessibility notes — ARIA patterns, screen reader behavior.- * Each string is one self-contained, declarative note.- * e.g. `"Uses native <dialog> with showModal() for correct ARIA modal semantics."`,- * `"Selection plugin sets aria-selected on selected body rows"` */- accessibility?: string[];- /** Keyboard interaction summary as a single string. Separate bindings- * with semicolons or commas. Use key names like `Arrow keys`, `Enter/Space`,- * `Escape`, `Tab/Shift+Tab`, `Home/End`.- * e.g. `"Space toggles the switch; Tab/Shift+Tab moves focus in and out"` */- keyboard?: string;- /** Additional technical notes — architecture decisions, performance- * considerations, implementation details, caveats. Each string is one- * self-contained note. Do not duplicate information from `features`,- * `accessibility`, or `keyboard`. */- notes?: string[];- /** Design-oriented usage guidance: when to use this component, when not to,- * and the visual anatomy of its parts. Complements the developer-focused- * fields (`description`, `features`, `props`). */- usage?: UsageDoc;+ /** All component documentation — description, features, accessibility,+ * implementation notes, and visual anatomy. */+ usage: UsageDoc;}/**@@ -313,8 +288,9 @@ export type ComponentDoc = SingleComponentDoc | MultiComponentDoc;* ```*/export interface TranslationDoc {- /** Compressed/translated component description. */- description: string;+ /** Compressed/translated component description.+ * Can also be provided via usage.description. */+ description?: string;/** Compressed/translated feature strings. Must match docs.features length and order. */features?: string[];/** Compressed/translated note strings. Must match docs.notes length and order. */@@ -325,9 +301,12 @@ export interface TranslationDoc {keyboard?: string;/** Prop descriptions keyed by prop name. Only include props that have descriptions. */propDescriptions?: Record<string, string>;- /** Translated/compressed usage overlay. Only summary and content are translated;- * anatomy element names are stable identifiers and stay as-is from the base doc. */+ /** Translated/compressed usage overlay. Mirrors UsageDoc fields. */usage?: {+ description?: string;+ features?: string[];+ accessibility?: string[];+ notes?: string[];summary?: string;content?: string;};