Skip to content

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

TypeScript

docs(nightwatch): full audit of all 56 component docs (#630)

Joey052bf791dd0d
diff --git a/packages/core/src/HoverCard/useXDSHoverCard.tsx b/packages/core/src/HoverCard/useXDSHoverCard.tsx
index 32f48ed027..dbe967470b 100644
--- a/packages/core/src/HoverCard/useXDSHoverCard.tsx
+++ b/packages/core/src/HoverCard/useXDSHoverCard.tsx
@@ -223,17 +223,11 @@ function isFocusable(element: HTMLElement): boolean {
*
* @example
* ```
- * // Simple case: use combined ref
* const hoverCard = useXDSHoverCard({ placement: 'above' });
- *
* <XDSButton ref={hoverCard.ref} aria-describedby={hoverCard.describedBy}>
* Hover me
* </XDSButton>
- *
* {hoverCard.renderHoverCard(<ProfileCard user={user} />)}
- *
- * // Separate refs when position and interaction differ (e.g., display:contents wrapper)
- * // Use positionRef for anchor, interactionRef for event listeners
* ```
*/
export function useXDSHoverCard(
diff --git a/packages/core/src/Popover/useXDSPopover.tsx b/packages/core/src/Popover/useXDSPopover.tsx
index 8d4631c132..cf2b8f56d7 100644
--- a/packages/core/src/Popover/useXDSPopover.tsx
+++ b/packages/core/src/Popover/useXDSPopover.tsx
@@ -232,18 +232,15 @@ export interface UseXDSPopoverReturn {
* onHide: () => inputRef.current?.focus(),
* closeButtonLabel: 'Close calendar',
* });
- *
* return (
* <>
* <input ref={inputRef} />
* <button
* ref={popover.triggerRef}
* onClick={popover.toggle}
- * {...popover.triggerProps}
- * >
+ * {...popover.triggerProps}>
* Open Calendar
* </button>
- *
* {popover.render(
* <Calendar />,
* { placement: 'below', alignment: 'start' }
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index f08cc54939..90116b38c3 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -195,6 +195,202 @@ const [filters, setFilters] = useState([]);
'Type to search fields; Enter to select; Click token to edit; Backspace on empty input removes last filter; Escape closes popover',
};
+// -------------------------------------------------------
+// Auto-generated translations below. Do not edit manually.
+// Regenerate with the dense compression protocol.
+// See .context/decisions/dense-compression-protocol.md
+// -------------------------------------------------------
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+ name: 'PowerSearch',
+ description:
+ '结构化过滤栏,每个令牌代表一个过滤器(字段 + 运算符 + 值)。用户从预输入下拉菜单中选择字段,在编辑弹出窗口中配置运算符和值,并将过滤器作为可移除的令牌进行管理。',
+ props: [
+ {
+ name: 'config',
+ type: 'PowerSearchConfig',
+ description: '定义可用字段、运算符及其值类型的配置。',
+ required: true,
+ },
+ {
+ name: 'filters',
+ type: 'ReadonlyArray<PowerSearchFilter>',
+ description: '当前活跃的过滤器。',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(filters: ReadonlyArray<PowerSearchFilter>, changeType: PowerSearchChangeType, index: number) => void',
+ description:
+ "当过滤器变更时调用。changeType 为 'add'、'edit' 或 'remove'。index 为受影响的过滤器位置。",
+ required: true,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: '搜索输入框的无障碍标签。',
+ default: "'Search'",
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: '视觉上隐藏标签,同时保持无障碍性。',
+ default: 'true',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: '未选择过滤器时显示的占位文本。',
+ default: "'Search...'",
+ },
+ {
+ name: 'hasAutoFocus',
+ type: 'boolean',
+ description: '挂载时自动聚焦输入框。',
+ default: 'false',
+ },
+ {
+ name: 'hasClear',
+ type: 'boolean',
+ description: '显示清除全部按钮以移除所有过滤器。',
+ default: 'true',
+ },
+ {
+ name: 'isReadOnly',
+ type: 'boolean',
+ description: '阻止添加、编辑或移除过滤器。',
+ default: 'false',
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: '禁用整个组件。',
+ default: 'false',
+ },
+ {
+ name: 'status',
+ type: 'XDSInputStatus',
+ description: '带有类型和可选消息的验证状态对象。',
+ },
+ {
+ name: 'maxTokenLength',
+ type: 'number',
+ description: '令牌中过滤器值显示的最大字符长度。',
+ default: '40',
+ },
+ {
+ name: 'popoverSaveButtonLabel',
+ type: 'string',
+ description: '编辑弹出窗口中保存按钮的标签。',
+ default: "'Apply'",
+ },
+ {
+ name: 'timezoneID',
+ type: 'string',
+ description: '用于日期格式化的时区 ID(例如 "America/New_York")。',
+ },
+ {
+ name: 'ref',
+ type: 'Ref<XDSPowerSearchHandle>',
+ description: '提供 focusTypeahead() 和 blurTypeahead() 方法的命令式句柄。',
+ },
+ {
+ name: 'endContent',
+ type: 'ReactNode',
+ description: '显示在输入行末尾的内容。适用于操作按钮或其他控件。',
+ },
+ {
+ name: 'resultCount',
+ type: 'number | string',
+ description:
+ '匹配当前过滤器的结果数量。数字类型时格式化为"N results"。字符串类型时按原样显示。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。',
+ },
+ ],
+ examples: [
+ {
+ label: '枚举过滤器的基本用法',
+ code: `const config = {
+ name: 'TaskSearch',
+ fields: [
+ {
+ key: 'status',
+ label: 'Status',
+ operators: [
+ {
+ key: 'is',
+ label: 'is',
+ value: {
+ type: 'enum',
+ values: [
+ { value: 'open', label: 'Open' },
+ { value: 'closed', label: 'Closed' },
+ ],
+ },
+ },
+ ],
+ },
+ {
+ key: 'title',
+ label: 'Title',
+ operators: [
+ {
+ key: 'contains',
+ label: 'contains',
+ value: { type: 'string' },
+ },
+ ],
+ },
+ ],
+};
+
+const [filters, setFilters] = useState([]);
+<XDSPowerSearch
+ config={config}
+ filters={filters}
+ onChange={(newFilters) => setFilters(newFilters)}
+/>`,
+ },
+ {
+ label: '带初始过滤器',
+ code: `const [filters, setFilters] = useState([
+ { field: 'status', operator: 'is', value: { type: 'enum', value: 'open' } },
+]);
+
+<XDSPowerSearch
+ config={config}
+ filters={filters}
+ onChange={(newFilters, changeType, index) => {
+ setFilters(newFilters);
+ console.log(changeType, 'at index', index);
+ }}
+ placeholder="Add filters..."
+/>`,
+ },
+ ],
+ features: [
+ '预输入字段选择,支持搜索和别名',
+ '编辑弹出窗口,包含字段、运算符和值选择器',
+ '支持 13 种值类型:字符串、整数、浮点数、枚举、日期、时间等',
+ '令牌式显示,支持点击编辑和移除',
+ '通过 ref 提供命令式 API 控制聚焦/失焦',
+ '只读模式,显示过滤器但不允许编辑',
+ ],
+ accessibility: [
+ '基于 XDSTokenizer 构建,提供 combobox 模式,包含 aria-expanded 和 aria-autocomplete。',
+ '过滤器令牌具有包含字段名、运算符和值的无障碍标签。',
+ '编辑弹出窗口使用 XDSPopover,支持焦点捕获和轻量关闭。',
+ '清除全部按钮具有无障碍标签。',
+ ],
+ keyboard:
+ '输入搜索字段;回车选择;点击令牌编辑;空输入时退格删除最后一个过滤器;Escape 关闭弹出窗口',
+};
+
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description:
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index 9d1f2a371b..f139743396 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -178,11 +178,6 @@ export const docs = {
'HTML name attribute for the textarea element, useful for form submissions.',
},
],
- theming: {
- targets: [
- {className: 'xds-text-input', visualProps: ['size']},
- ],
- },
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.',
@@ -379,11 +374,6 @@ export const docsZh = {
'文本域元素的 HTML name 属性,用于表单提交。',
},
],
- theming: {
- targets: [
- {className: 'xds-text-input', visualProps: ['size']},
- ],
- },
accessibility: [
'标签始终在 DOM 中渲染;使用 isLabelHidden 视觉上隐藏它,同时保持无障碍性。',
'文本域 id 通过 useId 生成并通过 htmlFor 与其标签关联,确保正确的标签关联。',
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 8aa235364e..a2da68700e 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -192,11 +192,6 @@ export const docs = {
'Tooltip text rendered as an info icon at the end of the label row.',
},
],
- theming: {
- targets: [
- {className: 'xds-date-input', visualProps: ['size']},
- ],
- },
accessibility: [
'The visible label is associated with the input via htmlFor / id.',
'isLabelHidden visually hides the label while keeping it in the accessibility tree.',
@@ -403,11 +398,6 @@ export const docsZh = {
'在标签行末尾以信息图标形式渲染的工具提示文本。',
},
],
- theming: {
- targets: [
- {className: 'xds-date-input', visualProps: ['size']},
- ],
- },
accessibility: [
'可见标签通过 htmlFor / id 与输入框关联。',
'isLabelHidden 视觉上隐藏标签,同时保持在无障碍树中。',
diff --git a/packages/core/src/Tooltip/useXDSTooltip.tsx b/packages/core/src/Tooltip/useXDSTooltip.tsx
index dc64898cc6..71fe960e85 100644
--- a/packages/core/src/Tooltip/useXDSTooltip.tsx
+++ b/packages/core/src/Tooltip/useXDSTooltip.tsx
@@ -225,11 +225,9 @@ function isFocusable(element: HTMLElement): boolean {
* @example
* ```
* const tooltip = useXDSTooltip({ placement: 'above' });
- *
* <XDSButton ref={tooltip.ref} aria-describedby={tooltip.describedBy}>
* Hover me
* </XDSButton>
- *
* {tooltip.renderTooltip('Helpful tooltip text')}
* ```
*/
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index a5aab9ec04..aa7aa43b90 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -119,6 +119,7 @@ export const docs = {
{className: 'xds-top-nav-item'},
{className: 'xds-top-nav-heading'},
{className: 'xds-top-nav-mega-menu'},
+ {className: 'xds-top-nav-menu'},
],
},
accessibility: [
@@ -603,6 +604,7 @@ export const docsZh = {
{className: 'xds-top-nav-item'},
{className: 'xds-top-nav-heading'},
{className: 'xds-top-nav-mega-menu'},
+ {className: 'xds-top-nav-menu'},
],
},
accessibility: [
@@ -619,7 +621,6 @@ export const docsZh = {
'Tab 在项目之间导航;Escape 关闭 XDSTopNavMegaMenu 面板',
notes: [
'默认高度为 48px(--spacing-12),水平内边距 16px',
- '使用 --color-navbar 令牌作为背景色(默认为白色)',
'无 centerContent 时:heading 和 startContent 增长以将 endContent 推向右侧(flex 布局)',
'有 centerContent 时:切换为 CSS grid(gridTemplateColumns: 1fr auto 1fr)— 即使 endContent 不存在,右列也始终渲染以维持三列结构',
'定位(sticky/fixed)由布局系统处理(例如 XDSAppShell),而非 TopNav 本身',
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index b4ab9d603e..879c4b353b 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -117,3 +117,177 @@ export const docs = {
},
],
};
+
+// -------------------------------------------------------
+// Auto-generated translations below. Do not edit manually.
+// Regenerate with the dense compression protocol.
+// See .context/decisions/dense-compression-protocol.md
+// -------------------------------------------------------
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+ name: 'TreeList',
+ description:
+ '数据驱动的树列表组件,用于渲染层级数据,支持展开/折叠、分支线条和交互式项目。使用扁平 items 数组配合递归 children,无需组合模式,无需 cloneElement。',
+ features: [
+ '数据驱动 API — items 数组配合递归 children',
+ '内部展开状态 — 通过每项的 isExpanded 设置初始值',
+ '分支连接线,支持居中/顶部对齐',
+ '密度变体:compact、balanced、spacious',
+ '交互式项目,通过不可见按钮或锚点模式',
+ '起始和结束内容插槽(图标、头像、徽章)',
+ '可选标题,通过 aria-labelledby 关联',
+ '无需位置数据上下文 — 渲染时计算',
+ ],
+ examples: [
+ {
+ label: '基本树',
+ code: `<XDSTreeList
+ items={[
+ { id: 'src', label: 'src', isExpanded: true, children: [
+ { id: 'app', label: 'App.tsx' },
+ { id: 'index', label: 'index.tsx' },
+ ]},
+ { id: 'pkg', label: 'package.json' },
+ ]}
+/>`,
+ },
+ {
+ label: '带图标和标题',
+ code: `<XDSTreeList
+ header={<strong>Project Files</strong>}
+ density="compact"
+ items={[
+ { id: 'src', label: 'src', isExpanded: true, startContent: <FolderIcon />, children: [
+ { id: 'app', label: 'App.tsx', startContent: <FileIcon /> },
+ ]},
+ ]}
+/>`,
+ },
+ {
+ label: '交互式项目',
+ code: `<XDSTreeList
+ items={[
+ { id: 'settings', label: 'Settings', onClick: () => navigate('/settings') },
+ { id: 'docs', label: 'Docs', href: '/docs', target: '_blank' },
+ ]}
+/>`,
+ },
+ ],
+ 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']},
+ ],
+ },
+ notes: [
+ '数据驱动模式:与使用 children 组合的 XDSList 不同,XDSTreeList 接受 items 数组。这避免了 cloneElement,使组件能在渲染时计算位置数据(nestedLevel、isLast、ancestorsIsLast)。',
+ '展开控制:展开状态在内部管理。通过在数据中设置 isExpanded: true 来设定初始状态。',
+ '性能:通过 key={id} 进行 React 协调意味着展开节点只会导致该子树的 DOM 更新。具有稳定 key 和相同 props 的兄弟节点会被 React 跳过。',
+ ],
+ components: [
+ {
+ name: 'XDSTreeList',
+ description:
+ '树列表容器。接受 items 数据和渲染配置。展开状态在内部管理。',
+ examples: [
+ {
+ label: '基本树',
+ code: `<XDSTreeList
+ items={[
+ { id: 'src', label: 'src', isExpanded: true, children: [
+ { id: 'app', label: 'App.tsx' },
+ ]},
+ { id: 'pkg', label: 'package.json' },
+ ]}
+/>`,
+ },
+ ],
+ props: [
+ {
+ name: 'items',
+ type: 'XDSTreeListItemData[]',
+ description:
+ '递归树项数据。每项有 id、label、可选 children 数组和可选 isExpanded 布尔值用于设置初始状态。',
+ required: true,
+ },
+ {
+ name: 'density',
+ type: "'compact' | 'balanced' | 'spacious'",
+ description: '项目的间距密度。',
+ default: "'balanced'",
+ },
+ {
+ name: 'header',
+ type: 'ReactNode',
+ description:
+ '标题内容,通过 aria-labelledby 与树关联。',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ '用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。',
+ },
+ ],
+ },
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description:
+ 'Data-driven tree list for hierarchical data w/ expand/collapse, branch lines, interactive items. Flat items array w/ recursive children, no composition, no cloneElement.',
+ features: [
+ 'Data-driven API; items array w/ recursive children',
+ 'Internal expansion state; seed via isExpanded per item',
+ 'Branch connector lines w/ center/top alignment',
+ 'Density variants: compact, balanced, spacious',
+ 'Interactive items via invisible button or anchor pattern',
+ 'Start + end content slots (icon, avatar, badge)',
+ 'Optional header via aria-labelledby',
+ 'No context for positional data; computed at render time',
+ ],
+ accessibility: [
+ 'Semantic <ul role="tree"> w/ <li role="treeitem">',
+ '<ul role="group"> for nested children',
+ 'aria-expanded on items w/ children',
+ 'aria-labelledby links header to tree',
+ 'aria-selected on selected items',
+ 'aria-disabled on disabled items',
+ 'Chevron toggle btn w/ aria-label="Toggle children"',
+ 'Interactive items keyboard-focusable via Tab',
+ ],
+ notes: [
+ 'Data-driven: accepts items array (not children composition), avoids cloneElement, computes positional data at render time.',
+ 'Expansion managed internally. Seed initial state via isExpanded: true on items.',
+ 'Perf: key={id} reconciliation means expanding node only updates that subtree.',
+ ],
+ propDescriptions: {
+ items: 'Recursive tree item data w/ id, label, optional children + isExpanded.',
+ density: 'Spacing density for items.',
+ header: 'Header content, linked to tree via aria-labelledby.',
+ xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
+ },
+ components: [
+ {
+ name: 'XDSTreeList',
+ description: 'Tree list container. Accepts items data + rendering config. Expansion managed internally.',
+ propDescriptions: {
+ items: 'Recursive tree item data w/ id, label, optional children + isExpanded.',
+ density: 'Spacing density for items.',
+ header: 'Header content, linked to tree via aria-labelledby.',
+ xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
+ },
+ },
+ ],
+};