Skip to content

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

TypeScript

docs: add keywords, zh/dense translations, and Typeahead theming targets (#1091)

Joeyf77a689034e8
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index 5f3b806278..8f0771265b 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -158,3 +158,91 @@ 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',
+ description: '带列布局、方向和折叠支持的元数据项容器。',
+ propDescriptions: {
+ children: '元数据项(XDSMetadataListItem 组件)。',
+ columns: '列布局模式。',
+ label: '标签显示配置。position 控制标签位置,width 设置自定义标签列宽。',
+ maxNumOfItems: '折叠前显示的最大项目数。',
+ orientation: '布局方向。水平模式使用 flex-wrap 流式排列。',
+ title: '列表上方的可选标题。',
+ xstyle: '布局自定义的 StyleX 样式,必须是 stylex.create() 值。',
+ },
+ },
+ {
+ name: 'XDSMetadataListItem',
+ description: 'XDSMetadataList 中的单个带标签元数据值。',
+ propDescriptions: {
+ children: '此元数据项的内容值。',
+ label: '此元数据项的标签文本。',
+ icon: '标签文本前渲染的图标。',
+ },
+ },
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'label/value metadata display; column layout, collapse, orientation variants',
+ features: [
+ 'composition: XDSMetadataList wraps XDSMetadataListItem',
+ 'columns: single, multi (auto-fill), fixed count',
+ 'label position: start (side-by-side) or top (stacked)',
+ 'horizontal orientation w/ flex-wrap',
+ 'show more/less toggle when items exceed maxNumOfItems',
+ 'optional title slot',
+ 'optional icon before label',
+ 'semantic: <dl> w/ <dt>/<dd> pairs',
+ ],
+ accessibility: [
+ 'semantic <dl> w/ <dt>/<dd>',
+ 'aria-controls links show more/less to list',
+ 'aria-expanded indicates expand state',
+ ],
+ components: [
+ {
+ name: 'XDSMetadataList',
+ description: 'metadata container w/ column layout+collapse',
+ propDescriptions: {
+ children: 'XDSMetadataListItem children',
+ columns: 'column mode: single, multi, or fixed count',
+ label: 'label config: position (start/top) + width',
+ maxNumOfItems: 'max items before collapse',
+ orientation: 'vertical or horizontal (flex-wrap)',
+ title: 'optional heading above list',
+ xstyle: 'StyleX layout styles; stylex.create() only',
+ },
+ },
+ {
+ name: 'XDSMetadataListItem',
+ description: 'single labeled value in XDSMetadataList',
+ propDescriptions: {
+ children: 'value content',
+ label: 'label text',
+ icon: 'icon before label',
+ },
+ },
+ ],
+};
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 3e66a29717..b78e4572bb 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -4,6 +4,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',
@@ -235,3 +236,113 @@ export const docs = {
},
],
};
+
+/** @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',
+ description: '带复选框的多选下拉框,用于从列表中选择多项。',
+ propDescriptions: {
+ label: '无障碍标签文本。',
+ options: '项目数组——字符串、带 value/label/icon/disabled 的对象、分隔线或分组。',
+ value: '当前选中的值。',
+ onChange: '选择变化时触发的回调。',
+ onChangeAction: '变化时的异步操作,在 onChange 之后触发。',
+ placeholder: '未选择值时显示的占位文本。',
+ size: '选择器的尺寸变体。',
+ triggerDisplay: '在触发器中显示选中项的方式。',
+ maxBadges: '显示"+N"之前的最大徽章数。仅适用于 triggerDisplay="badges"。',
+ hasSelectAll: '是否显示全选复选框。',
+ selectAllLabel: '全选复选框的标签。',
+ hasSearch: '是否显示用于过滤选项的搜索输入。',
+ searchPlaceholder: '搜索输入的占位文本。',
+ isDisabled: '禁用选择器。',
+ isLabelHidden: '视觉上隐藏标签同时保持其可访问性。',
+ description: '标签下方显示的辅助文本。',
+ isOptional: '将字段标记为可选。',
+ isRequired: '将字段标记为必填。',
+ isLoading: '在触发器中显示加载旋转器。',
+ status: '带可选消息的验证状态。',
+ children: '每个选项的自定义渲染函数。',
+ xstyle: '布局自定义的 StyleX 样式,必须是 stylex.create() 值。',
+ },
+ },
+ ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'checkbox multi-select dropdown for finite sets like column toggles or filter facets',
+ features: [
+ 'checkbox multi-select; dropdown stays open on toggle',
+ 'strings, objects w/ icon+disabled, dividers, sections',
+ 'optional select-all w/ indeterminate state',
+ 'optional search filtering',
+ 'trigger modes: count, labels, badges',
+ 'XDS field: label, description, isRequired, isOptional, isLabelHidden, status',
+ 'sizes: sm, md, lg',
+ 'full keyboard nav w/ typeahead',
+ 'a11y: role="combobox" trigger, listbox w/ aria-multiselectable, real checkboxes',
+ ],
+ keyboard: '↑↓ nav, Enter/Space toggle, Escape close, Home/End jump, A-Z typeahead (no search).',
+ accessibility: [
+ 'role="combobox" on trigger.',
+ 'aria-multiselectable="true" on listbox.',
+ 'role="option" w/ aria-selected per option.',
+ 'real XDSCheckboxInput per item.',
+ 'select-all outside role="listbox".',
+ 'role="searchbox" w/ aria-controls on search.',
+ ],
+ components: [
+ {
+ name: 'XDSMultiSelector',
+ description: 'checkbox multi-select dropdown',
+ propDescriptions: {
+ label: 'a11y label',
+ options: 'items: strings, objects w/ value/label/icon/disabled, dividers, sections',
+ value: 'selected values',
+ onChange: 'callback on selection change',
+ onChangeAction: 'async; fires after onChange',
+ placeholder: 'text when nothing selected',
+ size: 'size variant',
+ triggerDisplay: 'how to show selected in trigger',
+ maxBadges: 'max badges before "+N"; badges mode only',
+ hasSelectAll: 'show select-all checkbox',
+ selectAllLabel: 'select-all label',
+ hasSearch: 'show search input',
+ searchPlaceholder: 'search placeholder',
+ isDisabled: 'disables selector',
+ isLabelHidden: 'visually hides label',
+ description: 'helper text below label',
+ isOptional: 'marks optional',
+ isRequired: 'marks required',
+ isLoading: 'spinner in trigger',
+ status: 'validation status w/ optional message',
+ children: 'custom render fn per option',
+ xstyle: 'StyleX layout styles; stylex.create() only',
+ },
+ },
+ ],
+};
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index 6eeef59397..c6e641c1a6 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -4,6 +4,7 @@ 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',
diff --git a/packages/core/src/Timestamp/Timestamp.doc.mjs b/packages/core/src/Timestamp/Timestamp.doc.mjs
index c791d759df..0d5856d81e 100644
--- a/packages/core/src/Timestamp/Timestamp.doc.mjs
+++ b/packages/core/src/Timestamp/Timestamp.doc.mjs
@@ -4,6 +4,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'],
props: [
{
name: 'value',
@@ -120,6 +121,36 @@ 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' 根据时间近远自动切换。",
+ autoThreshold: "auto 格式从相对时间切换到 date_time 的阈值秒数。",
+ hasTooltip: '悬停时是否显示包含完整日期/时间的工具提示(相对时间模式)。',
+ isTimezoneShown: '是否附加时区缩写。',
+ isLive: '相对时间是否实时更新。',
+ type: '来自 XDSText 的语义文本类型。',
+ size: '显式字体大小覆盖。',
+ color: '文字颜色。',
+ weight: '字体粗细覆盖。',
+ },
+};
+
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description: 'formatted timestamp display with relative/absolute/auto modes via XDSText',
diff --git a/packages/core/src/Toolbar/Toolbar.doc.mjs b/packages/core/src/Toolbar/Toolbar.doc.mjs
index eb36e02058..f69a712665 100644
--- a/packages/core/src/Toolbar/Toolbar.doc.mjs
+++ b/packages/core/src/Toolbar/Toolbar.doc.mjs
@@ -4,6 +4,7 @@ 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',
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index 52436c0464..27df14f0db 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -4,6 +4,7 @@ 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',
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index beb3f0c624..3a3082844c 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -405,6 +405,8 @@ export const docs = {
'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']},
+ {className: 'xds-typeahead-dropdown'},
{className: 'xds-typeahead-item'},
],
},
@@ -821,6 +823,8 @@ export const docsZh = {
'方向键导航下拉列表项目;Enter 选择高亮项目;Escape 关闭下拉列表或在编辑模式中恢复之前的值;Home/End 跳转到第一个/最后一个项目',
theming: {
targets: [
+ {className: 'xds-typeahead', visualProps: ['status']},
+ {className: 'xds-typeahead-dropdown'},
{className: 'xds-typeahead-item'},
],
},