Skip to content

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.mjs
index 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 group
let compGroup = group;
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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'