Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(cli): support external library component discovery (#563)

Joey16dddcf6bb77
diff --git a/packages/cli/src/commands/component.test.mjs b/packages/cli/src/commands/component.test.mjs
index 110619873a..fccedd8309 100644
--- a/packages/cli/src/commands/component.test.mjs
+++ b/packages/cli/src/commands/component.test.mjs
@@ -4,6 +4,8 @@ import * as path from 'node:path';
import * as os from 'node:os';
import {
discoverComponents,
+ discoverExternalComponents,
+ findExternalComponentDoc,
cleanReadme,
extractCompact,
extractProps,
@@ -391,3 +393,115 @@ describe('extractProps', () => {
expect(result).toMatch(/\n$/);
});
});
+
+describe('discoverExternalComponents', () => {
+ it('finds .doc.mjs files in the docs directory', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ const compDir = path.join(docsDir, 'Employee');
+ fs.mkdirSync(compDir, {recursive: true});
+ fs.writeFileSync(path.join(compDir, 'EmployeeHoverCard.doc.mjs'), '');
+ fs.writeFileSync(path.join(compDir, 'EmployeeLink.doc.mjs'), '');
+
+ const result = discoverExternalComponents(docsDir);
+ expect(result).toEqual(['EmployeeHoverCard', 'EmployeeLink']);
+ });
+
+ it('scans nested directories recursively', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ const deepDir = path.join(docsDir, 'a', 'b', 'c');
+ fs.mkdirSync(deepDir, {recursive: true});
+ fs.writeFileSync(path.join(deepDir, 'DeepComponent.doc.mjs'), '');
+
+ const result = discoverExternalComponents(docsDir);
+ expect(result).toEqual(['DeepComponent']);
+ });
+
+ it('ignores non-.doc.mjs files', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ fs.mkdirSync(docsDir, {recursive: true});
+ fs.writeFileSync(path.join(docsDir, 'Foo.doc.mjs'), '');
+ fs.writeFileSync(path.join(docsDir, 'Foo.tsx'), '');
+ fs.writeFileSync(path.join(docsDir, 'README.md'), '');
+ fs.writeFileSync(path.join(docsDir, 'index.mjs'), '');
+
+ const result = discoverExternalComponents(docsDir);
+ expect(result).toEqual(['Foo']);
+ });
+
+ it('skips node_modules and __tests__ directories', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ const nmDir = path.join(docsDir, 'node_modules', 'dep');
+ const testDir = path.join(docsDir, '__tests__');
+ fs.mkdirSync(nmDir, {recursive: true});
+ fs.mkdirSync(testDir, {recursive: true});
+ fs.writeFileSync(path.join(nmDir, 'Hidden.doc.mjs'), '');
+ fs.writeFileSync(path.join(testDir, 'TestOnly.doc.mjs'), '');
+ fs.writeFileSync(path.join(docsDir, 'Visible.doc.mjs'), '');
+
+ const result = discoverExternalComponents(docsDir);
+ expect(result).toEqual(['Visible']);
+ });
+
+ it('returns empty array for nonexistent directory', () => {
+ const result = discoverExternalComponents(path.join(tmpDir, 'nope'));
+ expect(result).toEqual([]);
+ });
+
+ it('returns sorted results', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ fs.mkdirSync(docsDir, {recursive: true});
+ fs.writeFileSync(path.join(docsDir, 'Zebra.doc.mjs'), '');
+ fs.writeFileSync(path.join(docsDir, 'Alpha.doc.mjs'), '');
+ fs.writeFileSync(path.join(docsDir, 'Middle.doc.mjs'), '');
+
+ const result = discoverExternalComponents(docsDir);
+ expect(result).toEqual(['Alpha', 'Middle', 'Zebra']);
+ });
+});
+
+describe('findExternalComponentDoc', () => {
+ it('finds a doc file by component name', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ const compDir = path.join(docsDir, 'Employee');
+ fs.mkdirSync(compDir, {recursive: true});
+ const docPath = path.join(compDir, 'EmployeeHoverCard.doc.mjs');
+ fs.writeFileSync(docPath, '');
+
+ const result = findExternalComponentDoc(docsDir, 'EmployeeHoverCard');
+ expect(result).toBe(docPath);
+ });
+
+ it('searches nested directories', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ const deepDir = path.join(docsDir, 'nested', 'deep');
+ fs.mkdirSync(deepDir, {recursive: true});
+ const docPath = path.join(deepDir, 'DeepThing.doc.mjs');
+ fs.writeFileSync(docPath, '');
+
+ const result = findExternalComponentDoc(docsDir, 'DeepThing');
+ expect(result).toBe(docPath);
+ });
+
+ it('returns null when component not found', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ fs.mkdirSync(docsDir, {recursive: true});
+
+ const result = findExternalComponentDoc(docsDir, 'NonExistent');
+ expect(result).toBeNull();
+ });
+
+ it('returns null for nonexistent directory', () => {
+ const result = findExternalComponentDoc(path.join(tmpDir, 'nope'), 'Foo');
+ expect(result).toBeNull();
+ });
+
+ it('skips node_modules and __tests__', () => {
+ const docsDir = path.join(tmpDir, 'src');
+ const nmDir = path.join(docsDir, 'node_modules', 'dep');
+ fs.mkdirSync(nmDir, {recursive: true});
+ fs.writeFileSync(path.join(nmDir, 'Hidden.doc.mjs'), '');
+
+ const result = findExternalComponentDoc(docsDir, 'Hidden');
+ expect(result).toBeNull();
+ });
+});
diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjs
index 14fef2b7b2..88c08ccf72 100644
--- a/packages/cli/src/commands/component/index.mjs
+++ b/packages/cli/src/commands/component/index.mjs
@@ -6,11 +6,13 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
-import {findCoreDir} from '../../utils/paths.mjs';
+import {findCoreDir, discoverExternalPackages} from '../../utils/paths.mjs';
import {
discoverComponents,
+ discoverExternalComponents,
findComponentReadme,
findComponentSource,
+ findExternalComponentDoc,
resolveImportPath,
} from '../../lib/component-discovery.mjs';
import {loadDocs} from '../../lib/component-loader.mjs';
@@ -119,6 +121,19 @@ export function registerComponent(program) {
}
console.log('');
}
+ // Show external packages
+ const externals = discoverExternalPackages(process.cwd());
+ for (const ext of externals) {
+ const extComponents = discoverExternalComponents(ext.docsDir);
+ if (extComponents.length > 0) {
+ console.log(`${ext.category} (${ext.name}):`);
+ for (const comp of extComponents) {
+ console.log(` ${comp}`);
+ }
+ console.log('');
+ }
+ }
+
console.log('Usage: npx xds component <name>');
console.log('');
}
@@ -141,6 +156,20 @@ export function registerComponent(program) {
let readmePath = findComponentReadme(coreDir, dirName);
let resolvedName = dirName;
+ let fromExternal = null;
+
+ // If not found in core, check external packages
+ if (!readmePath) {
+ const externals = discoverExternalPackages(process.cwd());
+ for (const ext of externals) {
+ const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);
+ if (extDocPath) {
+ readmePath = extDocPath;
+ fromExternal = ext;
+ break;
+ }
+ }
+ }
if (!readmePath) {
// Try fuzzy matching
@@ -171,7 +200,7 @@ export function registerComponent(program) {
if (readmePath.endsWith('.doc.mjs')) {
const docs = await loadDocs(readmePath, {zh, dense, lang});
- const importHint = resolveImportPath(coreDir, resolvedName);
+ const importHint = fromExternal ? fromExternal.name : resolveImportPath(coreDir, resolvedName);
if (options.props) {
console.log(formatProps(docs, resolvedName));
} else if (detail === 'brief') {
@@ -201,7 +230,8 @@ export function registerComponent(program) {
// Re-export lib functions for backward compatibility
// (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)
-export {discoverComponents, findComponentReadme, findComponentSource, resolveImportPath} from '../../lib/component-discovery.mjs';
+export {discoverComponents, discoverExternalComponents, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../lib/component-discovery.mjs';
+export {discoverExternalPackages} from '../../utils/paths.mjs';
export {loadDocs} from '../../lib/component-loader.mjs';
export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
export {cleanReadme, extractCompact, extractBrief, ensureImportStatement, extractProps} from '../../lib/component-legacy.mjs';
diff --git a/packages/cli/src/lib/component-discovery.mjs b/packages/cli/src/lib/component-discovery.mjs
index 0c39c2f934..f3bc88aa81 100644
--- a/packages/cli/src/lib/component-discovery.mjs
+++ b/packages/cli/src/lib/component-discovery.mjs
@@ -228,6 +228,59 @@ export function resolveImportPath(coreDir, componentName) {
return '@xds/core';
}
+// ── External package discovery ───────────────────────────────────────
+
+/**
+ * Discover components from an external package's docs directory.
+ * Scans for *.doc.mjs files and returns their names.
+ */
+export function discoverExternalComponents(docsDir) {
+ if (!fs.existsSync(docsDir)) return [];
+ const components = [];
+
+ function scanDir(dirPath) {
+ const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+ for (const entry of entries) {
+ if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+ const fullPath = path.join(dirPath, entry.name);
+ if (entry.isDirectory()) {
+ scanDir(fullPath);
+ } else if (entry.name.endsWith('.doc.mjs')) {
+ components.push(entry.name.replace('.doc.mjs', ''));
+ }
+ }
+ }
+
+ scanDir(docsDir);
+ return components.sort();
+}
+
+/**
+ * Find a component's doc file in an external package's docs directory.
+ * Returns the path to {Name}.doc.mjs or null.
+ */
+export function findExternalComponentDoc(docsDir, name) {
+ if (!fs.existsSync(docsDir)) return null;
+ const target = `${name}.doc.mjs`;
+
+ function scanDir(dirPath) {
+ const entries = fs.readdirSync(dirPath, {withFileTypes: true});
+ for (const entry of entries) {
+ if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+ const fullPath = path.join(dirPath, entry.name);
+ if (entry.isDirectory()) {
+ const found = scanDir(fullPath);
+ if (found) return found;
+ } else if (entry.name === target) {
+ return fullPath;
+ }
+ }
+ return null;
+ }
+
+ return scanDir(docsDir);
+}
+
// ── Legacy markdown-parsing functions ────────────────────────────────
// These are kept for backward compatibility with existing tests.
// The CLI action handler uses the new format functions below instead.
diff --git a/packages/cli/src/utils/paths.mjs b/packages/cli/src/utils/paths.mjs
index 2c5d4ee7f6..4077248294 100644
--- a/packages/cli/src/utils/paths.mjs
+++ b/packages/cli/src/utils/paths.mjs
@@ -67,6 +67,72 @@ export function findProjectRoot(startDir = process.cwd()) {
return null;
}
+/**
+ * Discover external XDS-compatible packages from node_modules.
+ * Scans for packages with an "xds" field in their package.json:
+ *
+ * { "xds": { "docs": "./src", "category": "Common" } }
+ *
+ * Returns array of { name, category, docsDir }.
+ */
+export function discoverExternalPackages(startDir = process.cwd()) {
+ const externals = [];
+ let dir = startDir;
+
+ // Walk up to find node_modules
+ let nodeModulesDir = null;
+ for (let i = 0; i < 5; i++) {
+ const candidate = path.join(dir, 'node_modules');
+ if (fs.existsSync(candidate)) {
+ nodeModulesDir = candidate;
+ break;
+ }
+ const parent = path.dirname(dir);
+ if (parent === dir) break;
+ dir = parent;
+ }
+
+ if (!nodeModulesDir) return externals;
+
+ const scanDir = (searchDir) => {
+ if (!fs.existsSync(searchDir)) return;
+ const entries = fs.readdirSync(searchDir, {withFileTypes: true});
+
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ if (entry.name.startsWith('.') || entry.name === '.bin') continue;
+
+ const fullPath = path.join(searchDir, entry.name);
+
+ // Recurse into scoped packages (@org/*)
+ if (entry.name.startsWith('@')) {
+ scanDir(fullPath);
+ continue;
+ }
+
+ const pkgJsonPath = path.join(fullPath, 'package.json');
+ if (!fs.existsSync(pkgJsonPath)) continue;
+
+ try {
+ const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+ if (pkg.name === '@xds/core') continue;
+ if (pkg.xds && pkg.xds.docs) {
+ externals.push({
+ name: pkg.name,
+ category: pkg.xds.category || pkg.name,
+ docsDir: path.resolve(fullPath, pkg.xds.docs),
+ });
+ }
+ } catch {
+ // skip invalid JSON
+ }
+ }
+ };
+
+ scanDir(nodeModulesDir);
+ return externals;
+}
+
/**
* List available component directories in packages/core/src.
* Returns directory names that contain XDS*.tsx files.
diff --git a/packages/cli/src/utils/paths.test.mjs b/packages/cli/src/utils/paths.test.mjs
index aa4d616423..e9bfdcebe7 100644
--- a/packages/cli/src/utils/paths.test.mjs
+++ b/packages/cli/src/utils/paths.test.mjs
@@ -2,7 +2,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import * as os from 'node:os';
-import {findCoreDir, findProjectRoot, listComponents} from './paths.mjs';
+import {findCoreDir, findProjectRoot, listComponents, discoverExternalPackages} from './paths.mjs';
let tmpDir;
@@ -64,6 +64,132 @@ describe('findProjectRoot', () => {
});
});
+describe('discoverExternalPackages', () => {
+ it('finds packages with an "xds" field in package.json', () => {
+ const nm = path.join(tmpDir, 'node_modules');
+ const extDir = path.join(nm, 'xds-charts');
+ fs.mkdirSync(extDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(extDir, 'package.json'),
+ JSON.stringify({
+ name: 'xds-charts',
+ xds: {docs: './src', category: 'Data Viz'},
+ }),
+ );
+
+ const result = discoverExternalPackages(tmpDir);
+ expect(result).toEqual([
+ {
+ name: 'xds-charts',
+ category: 'Data Viz',
+ docsDir: path.join(extDir, 'src'),
+ },
+ ]);
+ });
+
+ it('handles scoped packages (@org/pkg)', () => {
+ const nm = path.join(tmpDir, 'node_modules');
+ const scopedDir = path.join(nm, '@acme', 'xds-widgets');
+ fs.mkdirSync(scopedDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(scopedDir, 'package.json'),
+ JSON.stringify({
+ name: '@acme/xds-widgets',
+ xds: {docs: './lib', category: 'Widgets'},
+ }),
+ );
+
+ const result = discoverExternalPackages(tmpDir);
+ expect(result).toEqual([
+ {
+ name: '@acme/xds-widgets',
+ category: 'Widgets',
+ docsDir: path.join(scopedDir, 'lib'),
+ },
+ ]);
+ });
+
+ it('skips @xds/core', () => {
+ const nm = path.join(tmpDir, 'node_modules');
+ const coreDir = path.join(nm, '@xds', 'core');
+ fs.mkdirSync(coreDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(coreDir, 'package.json'),
+ JSON.stringify({
+ name: '@xds/core',
+ xds: {docs: './src'},
+ }),
+ );
+
+ const result = discoverExternalPackages(tmpDir);
+ expect(result).toEqual([]);
+ });
+
+ it('skips packages without "xds" field', () => {
+ const nm = path.join(tmpDir, 'node_modules');
+ const extDir = path.join(nm, 'some-lib');
+ fs.mkdirSync(extDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(extDir, 'package.json'),
+ JSON.stringify({name: 'some-lib'}),
+ );
+
+ const result = discoverExternalPackages(tmpDir);
+ expect(result).toEqual([]);
+ });
+
+ it('defaults category to package name when not specified', () => {
+ const nm = path.join(tmpDir, 'node_modules');
+ const extDir = path.join(nm, 'my-components');
+ fs.mkdirSync(extDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(extDir, 'package.json'),
+ JSON.stringify({
+ name: 'my-components',
+ xds: {docs: './docs'},
+ }),
+ );
+
+ const result = discoverExternalPackages(tmpDir);
+ expect(result[0].category).toBe('my-components');
+ });
+
+ it('returns empty array when no node_modules found', () => {
+ const result = discoverExternalPackages(tmpDir);
+ expect(result).toEqual([]);
+ });
+
+ it('walks up directories to find node_modules', () => {
+ const nm = path.join(tmpDir, 'node_modules');
+ const extDir = path.join(nm, 'xds-ext');
+ fs.mkdirSync(extDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(extDir, 'package.json'),
+ JSON.stringify({
+ name: 'xds-ext',
+ xds: {docs: './src'},
+ }),
+ );
+
+ const nested = path.join(tmpDir, 'packages', 'app');
+ fs.mkdirSync(nested, {recursive: true});
+
+ const result = discoverExternalPackages(nested);
+ expect(result).toHaveLength(1);
+ expect(result[0].name).toBe('xds-ext');
+ });
+
+ it('handles invalid JSON in package.json gracefully', () => {
+ const nm = path.join(tmpDir, 'node_modules');
+ const extDir = path.join(nm, 'bad-json');
+ fs.mkdirSync(extDir, {recursive: true});
+ fs.writeFileSync(path.join(extDir, 'package.json'), '{not valid json!!!');
+
+ const result = discoverExternalPackages(tmpDir);
+ expect(result).toEqual([]);
+ });
+});
+
describe('listComponents', () => {
it('returns sorted component directory names, skipping hooks/theme/utils', () => {
const srcDir = path.join(tmpDir, 'src');
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index da7cdbd7a0..60c74d50a1 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -111,3 +111,17 @@ export * from './utils';
// Theme
export * from './theme';
+
+// Doc types — for external library authors writing .doc.mjs files
+export type {
+ ComponentDoc,
+ SingleComponentDoc,
+ MultiComponentDoc,
+ PropDoc,
+ Example,
+ ComponentEntry,
+ ThemingTarget,
+ CSSPropertyDoc,
+ ComponentVar,
+ TranslationDoc,
+} from './docs-types';