An open source design system that's fully customizable and agent ready
TypeScript
docs: break nav groups, add hidden component support (#1657)
Cindy Zhang09805a25c0ba
diff --git a/packages/cli/src/lib/component-discovery.mjs b/packages/cli/src/lib/component-discovery.mjsindex ec56da0d60..8e1d8ed6b8 100644--- a/packages/cli/src/lib/component-discovery.mjs+++ b/packages/cli/src/lib/component-discovery.mjs@@ -11,29 +11,32 @@ const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);// Only matches at shallow indentation (≤ 4 spaces from line start) to avoid// picking up nested `group:` fields inside prop descriptions.const GROUP_RE = /(?:^|\n) {0,4}group:\s*['"]([^'"]+)['"]/;-const INTERNAL_COMPONENTS_RE = /(?:^|\n) {0,4}internalComponents:\s*\[([^\]]*)\]/;+const HIDDEN_COMPONENTS_RE = /(?:^|\n) {0,4}hiddenComponents:\s*\[([^\]]*)\]/;+const HIDDEN_RE = /(?:^|\n) {0,4}hidden:\s*true/;/**- * Read the `group` and `internalComponents` fields from a+ * Read the `group`, `hiddenComponents`, and `hidden` fields from a* component's .doc.mjs file (synchronous).*/function readDocMeta(docPath) {try {const content = fs.readFileSync(docPath, 'utf-8');const groupMatch = GROUP_RE.exec(content);- const internalCompsMatch = INTERNAL_COMPONENTS_RE.exec(content);+ const hiddenCompsMatch = HIDDEN_COMPONENTS_RE.exec(content);const hiddenSet = new Set();- if (internalCompsMatch) {- for (const m of internalCompsMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {+ if (hiddenCompsMatch) {+ for (const m of hiddenCompsMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {hiddenSet.add(m[1]);}}+ const hidden = HIDDEN_RE.test(content);return {group: groupMatch ? groupMatch[1] : null,- internalComponents: hiddenSet,+ hiddenComponents: hiddenSet,+ hidden,};} catch {- return {group: null, internalComponents: new Set()};+ return {group: null, hiddenComponents: new Set(), hidden: false};}}@@ -83,13 +86,16 @@ export function discoverComponents(coreDir) {if (!fs.existsSync(docFile)) {docFile = path.join(dirPath, `XDS${entry.name}.doc.mjs`);}- const {group, internalComponents} = fs.existsSync(docFile)+ const {group, hiddenComponents, hidden} = fs.existsSync(docFile)? readDocMeta(docFile)- : {group: null, internalComponents: new Set()};+ : {group: null, hiddenComponents: new Set(), hidden: false};++ // Skip entire directory if the doc is marked hidden+ if (hidden) continue;for (const fileName of xdsFiles) {const componentName = fileName.replace(/^XDS/, '').replace(/\.tsx$/, '');- if (internalComponents.has(componentName)) continue;+ if (hiddenComponents.has(componentName)) continue;// Check for a per-component doc file that overrides the directory grouplet compGroup = group;diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjsindex f1e0bb5bd1..70f5a5c252 100644--- a/packages/core/src/MobileNav/MobileNav.doc.mjs+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'MobileNav',- group: 'Navigation',+ group: 'MobileNav',keywords: ["mobilenav","drawer","sidebar","navigation","hamburger","menu","offcanvas","slideout","navdrawer"],props: [{diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjsindex 6e9bce8f12..b1891ed7cd 100644--- a/packages/core/src/NavIcon/NavIcon.doc.mjs+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'NavIcon',- group: 'Navigation',+ hidden: true,keywords: ["navicon","iconbutton","toolbar icon","appbar icon","nav button"],props: [{diff --git a/packages/core/src/NavMenu/NavMenu.doc.mjs b/packages/core/src/NavMenu/NavMenu.doc.mjsindex 0d1d36da14..6495e40cb6 100644--- a/packages/core/src/NavMenu/NavMenu.doc.mjs+++ b/packages/core/src/NavMenu/NavMenu.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'NavMenu',- group: 'Navigation',+ hidden: true,keywords: ['nav', 'menu', 'navigation', 'menu-item'],usage: {description: 'Menu item used within navigation components like SideNav and TopNav.',diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjsindex 81f5624ba4..1ad9d0ae8e 100644--- a/packages/core/src/SideNav/SideNav.doc.mjs+++ b/packages/core/src/SideNav/SideNav.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'SideNav',- group: 'Navigation',+ group: 'SideNav',keywords: ["sidenav","sidebar","navigation","drawer","menu","nav","aside","sidemenu","navmenu","sider","treeview"],theming: {targets: [diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjsindex cd69a36404..e20a265e1c 100644--- a/packages/core/src/Toast/Toast.doc.mjs+++ b/packages/core/src/Toast/Toast.doc.mjs@@ -3,7 +3,7 @@export const docs = {name: 'Toast',group: 'Toast',- internalComponents: ['ToastViewport'],+ hiddenComponents: ['ToastViewport'],keywords: ["toast","notification","snackbar","alert","message","feedback","status"],props: [diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjsindex b6c302d63b..cce626132a 100644--- a/packages/core/src/TopNav/TopNav.doc.mjs+++ b/packages/core/src/TopNav/TopNav.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'TopNav',- group: 'Navigation',+ group: 'TopNav',keywords: ["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],theming: {targets: [diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex a3bfb87c50..adc7a60891 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -268,9 +268,18 @@ interface BaseDoc {* Lowercase only. Used by `xds component <term>` for fuzzy matching.* e.g. `['accordion', 'expand', 'toggle', 'disclosure']` for Collapsible */keywords?: string[];- /** Sub-component names to hide from discovery. Use when the directory's- * doc covers a group but some XDS*.tsx files are internal. */- internalComponents?: string[];+ /** Sub-component names to hide from human-facing UI (CLI listings,+ * docs catalogs). The components stay public and importable — agents+ * and tooling can still discover them via source. Use when the+ * directory's doc covers a group but some XDS*.tsx files shouldn't+ * appear in the catalog. */+ hiddenComponents?: string[];+ /** Hide this entire component from human-facing UI (CLI listings,+ * docs catalogs). The component stays public and importable — agents+ * and tooling can still discover it via source. Use for shared+ * primitives (NavIcon, NavMenu) that only make sense in the context+ * of their parent compositions. */+ hidden?: boolean;/** Optional group for sidebar/docs organization.* Components without a group appear flat in alphabetical order.* Groups cluster related components that are always used together@@ -290,7 +299,9 @@ interface BaseDoc {| 'Layout'| 'List'| 'MetadataList'- | 'Navigation'+ | 'MobileNav'+ | 'SideNav'+ | 'TopNav'| 'RadioList'| 'SegmentedControl'| 'Selector'