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.tsxindex 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.tsxindex 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.mjsindex 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.mjsindex 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.mjsindex 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.tsxindex 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.mjsindex 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.mjsindex 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.',+ },+ },+ ],+};