Skip to content

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.mjs
new file mode 100644
index 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.json
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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.mjs
index 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.mjs
index 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.mjs
index 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.js
index 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',
};
/**