An open source design system that's fully customizable and agent ready
TypeScript
fix(docs): remove source paths from READMEs and ensure CLI compact docs include imports (#310)
Cindy Zhanged71298cac56
diff --git a/packages/cli/src/commands/component.mjs b/packages/cli/src/commands/component.mjsindex 0e17458204..76f09522f6 100644--- a/packages/cli/src/commands/component.mjs+++ b/packages/cli/src/commands/component.mjs@@ -411,7 +411,7 @@ export function findClosestComponents(name, components, maxDistance = 3) {* label: string (required) · isLoading isDisabled icon tooltip children* <XDSButton variant="primary" onClick={fn}>Save</XDSButton>*/-export function extractBrief(content, componentName) {+export function extractBrief(content, componentName, importHint) {const displayName = componentName.startsWith('XDS')? componentName: `XDS${componentName}`;@@ -575,7 +575,7 @@ export function extractBrief(content, componentName) {signatureProps.length > 0? `${displayName}(${signatureProps.join(', ')})`: displayName;- output.push(sigStr);+ output.push(importHint ? `${sigStr} ← from '${importHint}'` : sigStr);// Description (shortened)if (description) {@@ -613,7 +613,8 @@ export function extractBriefAll(coreDir) {const readmePath = findComponentReadme(coreDir, comp);if (readmePath) {const content = fs.readFileSync(readmePath, 'utf-8');- output.push(extractBrief(content, comp));+ const importPath = resolveImportPath(coreDir, comp);+ output.push(extractBrief(content, comp, importPath));} else {output.push(`XDS${comp}\n (no docs)\n`);}@@ -623,6 +624,72 @@ export function extractBriefAll(coreDir) {return output.join('\n');}+/**+ * Resolve the import path for a component.+ * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.+ */+export function resolveImportPath(coreDir, componentName) {+ const srcDir = path.join(coreDir, 'src');+ const sourcePath = findComponentSource(coreDir, componentName);+ if (!sourcePath) return '@xds/core';++ // Get the top-level directory under src/ from the source path+ const relToSrc = path.relative(srcDir, sourcePath);+ const topDir = relToSrc.split(path.sep)[0];++ // Check package.json exports for ./${topDir}+ const pkgPath = path.join(coreDir, 'package.json');+ if (fs.existsSync(pkgPath)) {+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));+ if (pkg.exports && pkg.exports[`./${topDir}`]) {+ return `@xds/core/${topDir}`;+ }+ }++ return '@xds/core';+}++/**+ * Ensure compact output includes an import statement.+ * If the output already contains `from '@xds/core`, returns as-is.+ * Otherwise, injects an ## Import section after the title/description,+ * before the first ## section.+ */+export function ensureImportStatement(compactOutput, componentName, coreDir) {+ // Already has an Import section — return as-is+ if (/^## Import$/m.test(compactOutput)) {+ return compactOutput;+ }++ const displayName = componentName.startsWith('XDS')+ ? componentName+ : `XDS${componentName}`;++ const importPath = resolveImportPath(coreDir, componentName);+ const importBlock = `## Import\n\n\`\`\`tsx\nimport { ${displayName} } from '${importPath}';\n\`\`\`\n`;++ // Find the first ## section and inject before it+ const lines = compactOutput.split('\n');+ const output = [];+ let injected = false;++ for (let i = 0; i < lines.length; i++) {+ if (!injected && lines[i].startsWith('## ')) {+ output.push(importBlock);+ injected = true;+ }+ output.push(lines[i]);+ }++ // If no ## section found, append at the end+ if (!injected) {+ output.push('');+ output.push(importBlock);+ }++ return output.join('\n');+}+/*** Extract only the Props section(s) from a README.* Useful for quick reference and LLM context.@@ -782,7 +849,8 @@ export function registerComponent(program) {} else if (options.brief) {console.log(extractBrief(content, resolvedName));} else if (options.compact) {- console.log(extractCompact(content, resolvedName));+ const compact = extractCompact(content, resolvedName);+ console.log(ensureImportStatement(compact, resolvedName, coreDir));} else {console.log(cleanReadme(content, resolvedName));}diff --git a/packages/core/src/AppShell/README.md b/packages/core/src/AppShell/README.mdindex 0258a61f93..9f06c5c1d4 100644--- a/packages/core/src/AppShell/README.md+++ b/packages/core/src/AppShell/README.md@@ -1,4 +1,4 @@-# /packages/core/src/AppShell+# AppShellApplication-level layout shell component.diff --git a/packages/core/src/Avatar/README.md b/packages/core/src/Avatar/README.mdindex e1b516b190..363716e836 100644--- a/packages/core/src/Avatar/README.md+++ b/packages/core/src/Avatar/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Avatar+# AvatarAvatar component for displaying user profile pictures with fallback support.diff --git a/packages/core/src/Button/README.md b/packages/core/src/Button/README.mdindex a9b084ee70..76b6190216 100644--- a/packages/core/src/Button/README.md+++ b/packages/core/src/Button/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Button+# ButtonXDSButton component with multiple variants, sizes, and isLoading state support.diff --git a/packages/core/src/Calendar/README.md b/packages/core/src/Calendar/README.mdindex 7df7ce42fc..ab8da5fd70 100644--- a/packages/core/src/Calendar/README.md+++ b/packages/core/src/Calendar/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Calendar+# CalendarXDSCalendar component for date selection with single and range modes.diff --git a/packages/core/src/Card/README.md b/packages/core/src/Card/README.mdindex a8981275c8..1dae5871e1 100644--- a/packages/core/src/Card/README.md+++ b/packages/core/src/Card/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Card+# CardCard container component with elevation and themed styling.diff --git a/packages/core/src/CheckboxInput/README.md b/packages/core/src/CheckboxInput/README.mdindex 9a796d5622..b590ed4f53 100644--- a/packages/core/src/CheckboxInput/README.md+++ b/packages/core/src/CheckboxInput/README.md@@ -1,4 +1,4 @@-# /packages/core/src/CheckboxInput+# CheckboxInputA checkbox input component for toggling boolean values.diff --git a/packages/core/src/Collapsible/README.md b/packages/core/src/Collapsible/README.mdindex c501a9ff41..ff82c15d28 100644--- a/packages/core/src/Collapsible/README.md+++ b/packages/core/src/Collapsible/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Collapsible+# CollapsibleCollapsible content primitive and group coordination.diff --git a/packages/core/src/DateInput/README.md b/packages/core/src/DateInput/README.mdindex 535409d3c1..2d9c003e80 100644--- a/packages/core/src/DateInput/README.md+++ b/packages/core/src/DateInput/README.md@@ -1,4 +1,4 @@-# /packages/core/src/DateInput+# DateInputXDSDateInput component combining a text input with a calendar popover for date selection.diff --git a/packages/core/src/Dialog/README.md b/packages/core/src/Dialog/README.mdindex 00f05962bb..777fc052bb 100644--- a/packages/core/src/Dialog/README.md+++ b/packages/core/src/Dialog/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Dialog+# DialogXDSDialog component using the native `<dialog>` element for modal dialogs.diff --git a/packages/core/src/DropdownMenu/README.md b/packages/core/src/DropdownMenu/README.mdindex 5fb96f8897..1546742d9d 100644--- a/packages/core/src/DropdownMenu/README.md+++ b/packages/core/src/DropdownMenu/README.md@@ -1,4 +1,4 @@-# /packages/core/src/DropdownMenu+# DropdownMenuA dropdown menu component for displaying actionable items in a popup menu.diff --git a/packages/core/src/Field/README.md b/packages/core/src/Field/README.mdindex 9c0dd7e916..8b52b267e8 100644--- a/packages/core/src/Field/README.md+++ b/packages/core/src/Field/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Field+# FieldA form field wrapper component that provides label and description.diff --git a/packages/core/src/Icon/README.md b/packages/core/src/Icon/README.mdindex 767535fda0..f7ad785c62 100644--- a/packages/core/src/Icon/README.md+++ b/packages/core/src/Icon/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Icon+# IconRenders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.diff --git a/packages/core/src/Layer/README.md b/packages/core/src/Layer/README.mdindex cb6656bfa9..4e11873a05 100644--- a/packages/core/src/Layer/README.md+++ b/packages/core/src/Layer/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Layer+# LayerLayer components for overlay content using modern browser APIs.diff --git a/packages/core/src/Layout/README.md b/packages/core/src/Layout/README.mdindex da104f0d81..c708666828 100644--- a/packages/core/src/Layout/README.md+++ b/packages/core/src/Layout/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Layout+# LayoutXDS Layout System - composable utilities and components for building structured layouts.@@ -125,13 +125,13 @@ See [Container/README.md](./Container/README.md) for full documentation.Use XDSLayout for page shells and app layouts — any UI with a header bar, sidebar navigation,scrollable content area, or action footer. Don't use for simple stacking (use XDSVStack/XDSHStack).-| Component | Description |-| ------------------ | ------------------------------------------------------------------------- |-| `XDSLayout` | Page shell with header, sidebar(s), content, and footer slots |-| `XDSLayoutHeader` | Top bar — page titles, app bars, toolbars |-| `XDSLayoutFooter` | Bottom bar — action bars, pagination, status bars |-| `XDSLayoutContent` | Scrollable main content area |-| `XDSLayoutPanel` | Sidebar — navigation panels, settings sidebars, detail/inspector panels |+| Component | Description |+| ------------------ | ----------------------------------------------------------------------- |+| `XDSLayout` | Page shell with header, sidebar(s), content, and footer slots |+| `XDSLayoutHeader` | Top bar — page titles, app bars, toolbars |+| `XDSLayoutFooter` | Bottom bar — action bars, pagination, status bars |+| `XDSLayoutContent` | Scrollable main content area |+| `XDSLayoutPanel` | Sidebar — navigation panels, settings sidebars, detail/inspector panels |See [XDSLayout/README.md](./XDSLayout/README.md) for full documentation.diff --git a/packages/core/src/Link/README.md b/packages/core/src/Link/README.mdindex 9daac5f99f..8e9790140e 100644--- a/packages/core/src/Link/README.md+++ b/packages/core/src/Link/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Link+# LinkXDSLink component for styled anchor links with multiple variants and features.diff --git a/packages/core/src/NumberInput/README.md b/packages/core/src/NumberInput/README.mdindex de9b39c3da..1c63d11f7c 100644--- a/packages/core/src/NumberInput/README.md+++ b/packages/core/src/NumberInput/README.md@@ -1,4 +1,4 @@-# /packages/core/src/NumberInput+# NumberInputA number input component for collecting numeric user input with validation.diff --git a/packages/core/src/RadioList/README.md b/packages/core/src/RadioList/README.mdindex 4beeab9906..063396dc6d 100644--- a/packages/core/src/RadioList/README.md+++ b/packages/core/src/RadioList/README.md@@ -1,4 +1,4 @@-# /packages/core/src/RadioList+# RadioListA radio group component for single-value selection from a list of options.diff --git a/packages/core/src/Section/README.md b/packages/core/src/Section/README.mdindex 4b40de5ee0..0eaa8d5365 100644--- a/packages/core/src/Section/README.md+++ b/packages/core/src/Section/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Section+# SectionSection container component with background variants.diff --git a/packages/core/src/Skeleton/README.md b/packages/core/src/Skeleton/README.mdindex de6e362b6e..3710a87f95 100644--- a/packages/core/src/Skeleton/README.md+++ b/packages/core/src/Skeleton/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Skeleton+# SkeletonA placeholder loading component that displays an animated pulsing effect while content is loading.diff --git a/packages/core/src/Slider/README.md b/packages/core/src/Slider/README.mdindex 78f88e6c4d..ae05add1df 100644--- a/packages/core/src/Slider/README.md+++ b/packages/core/src/Slider/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Slider+# SliderA slider component for selecting numeric values or ranges with full keyboard and pointer support.diff --git a/packages/core/src/Spinner/README.md b/packages/core/src/Spinner/README.mdindex 23ce7862e2..c3ee269865 100644--- a/packages/core/src/Spinner/README.md+++ b/packages/core/src/Spinner/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Spinner+# SpinnerA pure spinner component for indicating loading state. No layout, no text — just the spinning indicator.diff --git a/packages/core/src/Stack/README.md b/packages/core/src/Stack/README.mdindex fc49bcc2fd..7e3b31cdc9 100644--- a/packages/core/src/Stack/README.md+++ b/packages/core/src/Stack/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Layout/Stack+# StackStack layout primitives for arranging items in horizontal or vertical sequences.diff --git a/packages/core/src/Switch/README.md b/packages/core/src/Switch/README.mdindex 444dca677a..4cf1a4c051 100644--- a/packages/core/src/Switch/README.md+++ b/packages/core/src/Switch/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Switch+# SwitchA toggle switch component for boolean values with integrated label support.diff --git a/packages/core/src/TabList/README.md b/packages/core/src/TabList/README.mdindex 044fedeab3..f4dca080dd 100644--- a/packages/core/src/TabList/README.md+++ b/packages/core/src/TabList/README.md@@ -1,4 +1,4 @@-# /packages/core/src/TabList+# TabListXDSTabList component for tab navigation with overflow menu support.diff --git a/packages/core/src/Table/README.md b/packages/core/src/Table/README.mdindex 9aab068adc..e06099582c 100644--- a/packages/core/src/Table/README.md+++ b/packages/core/src/Table/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Table+# TableTable components for the XDS design system.@@ -158,11 +158,6 @@ The selection plugin uses React Context so that `SelectAllCheckbox` and `SelectiBody rows are memoized via `React.memo` with a custom comparison function. When a single data item changes, only that row re-renders — unchanged rows are skipped. For this to work optimally, consumers should define `columns` outside the component or memoize them.-## Related Files--- `/packages/core/src/theme/tokens.stylex.ts` — Design tokens used by table component styling-- `/packages/core/src/CheckboxInput/` — Checkbox component used by selection plugin-## ThemingThemes can override `Table` styles via `ComponentStyles`:diff --git a/packages/core/src/Text/README.md b/packages/core/src/Text/README.mdindex b1379c1a06..ac92229c3e 100644--- a/packages/core/src/Text/README.md+++ b/packages/core/src/Text/README.md@@ -1,4 +1,4 @@-# /packages/core/src/Text+# TextTypography components for the XDS design system.@@ -61,8 +61,3 @@ function Article() {);}```--## Related Files--- `/packages/core/src/typography.css` — CSS stylesheet for native element styling-- `/packages/core/src/theme/types.ts` — Type definitions for `ProseElement` and component stylesdiff --git a/packages/core/src/TextArea/README.md b/packages/core/src/TextArea/README.mdindex f8d871479d..20b5ad963b 100644--- a/packages/core/src/TextArea/README.md+++ b/packages/core/src/TextArea/README.md@@ -1,4 +1,4 @@-# /packages/core/src/TextArea+# TextAreaA multi-line text input component for collecting longer user input.diff --git a/packages/core/src/TextInput/README.md b/packages/core/src/TextInput/README.mdindex a657566e08..f1b96791b4 100644--- a/packages/core/src/TextInput/README.md+++ b/packages/core/src/TextInput/README.md@@ -1,4 +1,4 @@-# /packages/core/src/TextInput+# TextInputA text input component for collecting user text input.diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.mdindex 0b3b2c650e..92104d9b3e 100644--- a/packages/core/src/TopNav/README.md+++ b/packages/core/src/TopNav/README.md@@ -1,4 +1,4 @@-# /packages/core/src/TopNav+# TopNavTop navigation bar component for application headers.diff --git a/packages/core/src/theme/README.md b/packages/core/src/theme/README.mdindex 4745516c94..3655be2385 100644--- a/packages/core/src/theme/README.md+++ b/packages/core/src/theme/README.md@@ -1,4 +1,4 @@-# /packages/core/src/theme+# themeXDS theme provider and design tokens.