An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): refine component group names (#1712)
Kenton Quatman4c825a1f82a4
diff --git a/packages/core/groups.doc.mjs b/packages/core/groups.doc.mjsnew file mode 100644index 0000000000..38071f1083--- /dev/null+++ b/packages/core/groups.doc.mjs@@ -0,0 +1,55 @@+/** @type {import('./src/docs-types').GroupDoc} */++/**+ * @file Group metadata for component categories that are not themselves components.+ *+ * Groups like "Checkbox" and "Layout" are category labels that cluster+ * related components. This file defines the canonical component for each+ * group — the one the docsite links to when a user clicks the group name.+ *+ * Groups whose name matches a component (Avatar, Button, Dialog, etc.)+ * don't need an entry here — the component is the canonical representative.+ *+ * Import: `import {GROUP_DOCS} from '@xds/core/groups.doc.mjs'`+ * Or dynamically: `const {GROUP_DOCS} = await import('@xds/core/groups.doc.mjs')`+ */++/** @type {Record<string, import('./src/docs-types').GroupDoc>} */+export const GROUP_DOCS = {+ Chat: {+ name: 'Chat',+ canonical: 'ChatMessageList',+ description:+ 'Conversational messaging primitives for building chat UIs, AI assistants, and threaded conversations.',+ },+ Checkbox: {+ name: 'Checkbox',+ canonical: 'CheckboxList',+ description:+ 'Selection controls for choosing one or more options from a set.',+ },+ Layout: {+ name: 'Layout',+ canonical: 'Stack',+ description:+ 'Structural primitives for arranging and spacing content on a page.',+ },+ Radio: {+ name: 'Radio',+ canonical: 'RadioList',+ description:+ 'Selection controls for choosing exactly one option from a set.',+ },+ Tabs: {+ name: 'Tabs',+ canonical: 'TabList',+ description:+ 'Tabbed navigation for switching between content views without a page reload.',+ },+ Utilities: {+ name: 'Utilities',+ canonical: 'Theme',+ description:+ 'Providers and configuration components for theming, routing, and rendering context.',+ },+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex 8b6ca2176c..3612c952cf 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -44,6 +44,7 @@"require": "./dist/theme/syntax/index.js"},"./docs.mjs": "./docs.mjs",+ "./groups.doc.mjs": "./groups.doc.mjs","./AlertDialog": {"source": "./src/AlertDialog/index.ts","types": "./dist/AlertDialog/index.d.ts",@@ -523,6 +524,7 @@"dist","src","docs.mjs",+ "groups.doc.mjs","README.md"],"scripts": {diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjsindex 0a79e0ce06..1bd72c6802 100644--- a/packages/core/src/Center/Center.doc.mjs+++ b/packages/core/src/Center/Center.doc.mjs@@ -2,6 +2,7 @@export const docs = {name: 'Center',+ group: 'Layout',keywords: ["center","centered","centering","align","alignment","justify","flexbox","middle"],props: [{diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjsindex 35c42d1fcd..567dfc5c6f 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs@@ -2,6 +2,7 @@export const docs = {name: 'CheckboxInput',+ group: 'Checkbox',keywords: ["checkbox","check","toggle","tick","indeterminate","boolean","tristate"],props: [{diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjsindex 744a24329a..c07ac792fb 100644--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'CheckboxList',- group: 'CheckboxList',+ group: 'Checkbox',keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],components: [{diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjsindex b4de3846a0..eda8e57e26 100644--- a/packages/core/src/FormLayout/FormLayout.doc.mjs+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs@@ -2,6 +2,7 @@export const docs = {name: 'FormLayout',+ group: 'Layout',keywords: ["formlayout","form","fieldset","formgroup","formcontainer","fields","vertical","horizontal"],props: [{diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjsindex 896a1971e3..c3439a4498 100644--- a/packages/core/src/Grid/Grid.doc.mjs+++ b/packages/core/src/Grid/Grid.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'Grid',- group: 'Grid',+ group: 'Layout',keywords: ["grid","columns","responsive","auto-fill","auto-fit","masonry","tiles","row","col","simplegrid","responsive grid","card grid"],usage: {description:@@ -115,7 +115,7 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Grid',- group: 'Grid',+ group: 'Layout',theming: {targets: [{className: 'xds-grid', visualProps: ['align', 'columns', 'gap', 'justify']},diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjsindex 215e73f130..3fe7d4f2fd 100644--- a/packages/core/src/Layer/Layer.doc.mjs+++ b/packages/core/src/Layer/Layer.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'Layer',- group: 'Utility',+ group: 'Utilities',keywords: ["layer","overlay","popover","positioning","anchor","floating","dropdown","popper","popup","portal"],components: [{diff --git a/packages/core/src/Link/LinkProvider.doc.mjs b/packages/core/src/Link/LinkProvider.doc.mjsindex 6569074d6d..0d67b1cca3 100644--- a/packages/core/src/Link/LinkProvider.doc.mjs+++ b/packages/core/src/Link/LinkProvider.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'LinkProvider',- group: 'Utility',+ group: 'Utilities',keywords: ['link', 'provider', 'router', 'nextjs', 'client-side-routing'],usage: {description: 'Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjsindex 75fbb39a8b..94c2c22bdb 100644--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs@@ -2,6 +2,7 @@export const docs = {name: 'MultiSelector',+ group: 'Selector',keywords: ['multiselect', 'checkbox', 'dropdown', 'multi', 'picker', 'checklist', 'facet', 'filter', 'select'],theming: {targets: [diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjsindex 120e2cebd4..54a6116380 100644--- a/packages/core/src/RadioList/RadioList.doc.mjs+++ b/packages/core/src/RadioList/RadioList.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'RadioList',- group: 'RadioList',+ group: 'Radio',keywords: ["radiolist","radio","radiogroup","radiobutton","optionlist","singlechoice","choicelist"],theming: {targets: [diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjsindex 327c2d7622..71d1609c0a 100644--- a/packages/core/src/Section/Section.doc.mjs+++ b/packages/core/src/Section/Section.doc.mjs@@ -2,6 +2,7 @@export const docs = {name: 'Section',+ group: 'Layout',keywords: ["section","panel","container","group","fieldset","region","block"],props: [{diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjsindex 4e6372fc0e..18bbe4962b 100644--- a/packages/core/src/Stack/Stack.doc.mjs+++ b/packages/core/src/Stack/Stack.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'Stack',- group: 'Stack',+ group: 'Layout',keywords: ["stack","hstack","vstack","flexbox","flex","spacing","gap","horizontal","vertical","row","column"],theming: {targets: [@@ -214,7 +214,7 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'Stack',- group: 'Stack',+ group: 'Layout',theming: {targets: [{className: 'xds-stack', visualProps: ['direction', 'gap', 'wrap']},diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjsindex 6dc0ef69d1..e13dad10c3 100644--- a/packages/core/src/TabList/TabList.doc.mjs+++ b/packages/core/src/TabList/TabList.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'TabList',- group: 'TabList',+ group: 'Tabs',keywords: ["tabs","tabbar","tabstrip","navigation","tabpanel","tabgroup","segmented","navtabs","tab"],theming: {targets: [@@ -148,7 +148,7 @@ export const docs = {/** @type {import('../docs-types').ComponentDoc} */export const docsZh = {name: 'TabList',- group: 'TabList',+ group: 'Tabs',theming: {targets: [{className: 'xds-tab-list', visualProps: ['size']},diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex adc7a60891..d246120c04 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -289,29 +289,27 @@ interface BaseDoc {| 'Breadcrumbs'| 'Button'| 'Chat'- | 'CheckboxList'+ | 'Checkbox'| 'Collapsible'| 'CommandPalette'| 'Dialog'| 'DropdownMenu'| 'Field'- | 'Grid'| 'Layout'| 'List'| 'MetadataList'| 'MobileNav'- | 'SideNav'- | 'TopNav'- | 'RadioList'+ | 'Radio'| 'SegmentedControl'| 'Selector'- | 'Stack'- | 'TabList'+ | 'SideNav'| 'Table'+ | 'Tabs'| 'Toast'+ | 'TopNav'| 'TreeList'| 'Typeahead'- | 'Utility';+ | 'Utilities';/** Theming configuration. Documents the stable CSS class names* rendered by this component that themes can target via `@scope`* selectors in `defineTheme`. */@@ -536,3 +534,37 @@ export interface BlockTemplateDoc extends BaseTemplateDoc {}export type TemplateDoc = PageTemplateDoc | BlockTemplateDoc;++// =============================================================================+// Group Documentation Types+// =============================================================================++/**+ * Metadata for a component group that is NOT itself a component.+ *+ * Some groups (e.g. 'Checkbox', 'Layout', 'Tabs') are category labels —+ * they cluster related components but have no corresponding XDS*.tsx file.+ * This metadata tells the docsite and CLI which component to treat as the+ * canonical entry point for the group.+ *+ * Groups whose name IS a component (e.g. 'Avatar', 'Button', 'Dialog')+ * don't need an entry here — the component IS the canonical representative.+ *+ * @example+ * ```+ * { name: 'Checkbox', canonical: 'CheckboxList', description: 'Selection controls for choosing one or more options from a set.' }+ * { name: 'Layout', canonical: 'Stack', description: 'Structural primitives for page and content layout.' }+ * ```+ */+export interface GroupDoc {+ /** Group name — must match one of the `group` union values on BaseDoc. */+ name: string;+ /** The canonical component for this group — the one the docsite links+ * to when a user clicks the group name. Should be the most commonly+ * used or most representative component in the group.+ * e.g. `'CheckboxList'` for the Checkbox group. */+ canonical: string;+ /** One-sentence description of what this group of components does.+ * Shown in the sidebar, catalog, or group landing page. */+ description: string;+}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex ec7a46be39..b0efdb2fbd 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -157,4 +157,5 @@ export type {ComponentVar,DerivedVar,TranslationDoc,+ GroupDoc,} from './docs-types';diff --git a/packages/core/src/theme/MediaTheme.doc.mjs b/packages/core/src/theme/MediaTheme.doc.mjsindex 1c57fdd260..497aac2756 100644--- a/packages/core/src/theme/MediaTheme.doc.mjs+++ b/packages/core/src/theme/MediaTheme.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'MediaTheme',- group: 'Utility',+ group: 'Utilities',keywords: ['theme', 'dark-mode', 'light-mode', 'media', 'prefers-color-scheme'],usage: {description: 'Applies a theme that adapts to the system light/dark preference via prefers-color-scheme.',diff --git a/packages/core/src/theme/SyntaxTheme.doc.mjs b/packages/core/src/theme/SyntaxTheme.doc.mjsindex 667492202a..3ffc70fc19 100644--- a/packages/core/src/theme/SyntaxTheme.doc.mjs+++ b/packages/core/src/theme/SyntaxTheme.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'SyntaxTheme',- group: 'Utility',+ group: 'Utilities',keywords: ['syntax', 'highlighting', 'code', 'theme'],usage: {description: 'Applies syntax highlighting colors to XDSCodeBlock components.',diff --git a/packages/core/src/theme/XDSTheme.doc.mjs b/packages/core/src/theme/XDSTheme.doc.mjsindex edd27e8588..79d62faaf8 100644--- a/packages/core/src/theme/XDSTheme.doc.mjs+++ b/packages/core/src/theme/XDSTheme.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'Theme',- group: 'Utility',+ group: 'Utilities',keywords: ['theme', 'theming', 'provider', 'color-scheme'],usage: {description: 'Wraps a subtree with a specific XDS theme. Use at the app root or around sections that need a different visual treatment.',diff --git a/scripts/sync-exports.js b/scripts/sync-exports.jsindex cc37e3a8e1..2c80cdb554 100644--- a/scripts/sync-exports.js+++ b/scripts/sync-exports.js@@ -74,6 +74,7 @@ const STATIC_EXPORTS = {require: './dist/theme/syntax/index.js',},'./docs.mjs': './docs.mjs',+ './groups.doc.mjs': './groups.doc.mjs',};/**