An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): discover showcases from external packages (#1920)
Cindy Zhange0ed4fc11f21
diff --git a/packages/cli/src/api/component.mjs b/packages/cli/src/api/component.mjsindex 15b7e17b2a..ea2e2fe583 100644--- a/packages/cli/src/api/component.mjs+++ b/packages/cli/src/api/component.mjs@@ -192,7 +192,7 @@ export async function component(name, options = {}) {}if (showcase) {- const match = await findShowcase(dirName);+ const match = await findShowcase(dirName, cwd);if (!match) {throw new XDSError(`No showcase found for "${name}"`);}diff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjsindex abb3f35f7b..0072351ff1 100644--- a/packages/cli/src/api/template.mjs+++ b/packages/cli/src/api/template.mjs@@ -4,7 +4,7 @@import * as fs from 'node:fs';import * as path from 'node:path';-import {CLI_ROOT} from '../utils/paths.mjs';+import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';import {XDSError} from './error.mjs';import {loadConfig} from '../lib/config.mjs';@@ -91,16 +91,67 @@ async function discoverBlocks() {return blocks;}+/**+ * Discover blocks from external packages that declare `xds.blocks`.+ * Same shape as discoverBlocks() output.+ *+ * @param {string} [cwd]+ */+async function discoverExternalBlocks(cwd = process.cwd()) {+ const externals = discoverExternalPackages(cwd);+ const blocks = [];++ for (const ext of externals) {+ if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;+ const docFiles = findDocFiles(ext.blocksDir, /\.doc\.mjs$/);+ for (const docPath of docFiles) {+ const basename = path.basename(docPath, '.doc.mjs');+ const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');+ if (!fs.existsSync(tsxPath)) continue;+ const doc = await loadDocModule(docPath);+ const relPath = path.relative(ext.blocksDir, path.dirname(docPath));+ blocks.push({+ type: 'block',+ dirName: basename,+ name: doc?.name || basename,+ description: doc?.description || '',+ isReady: doc?.isReady ?? true,+ aspectRatio: doc?.aspectRatio ?? 1,+ componentsUsed: doc?.componentsUsed ?? [],+ isShowcase: doc?.isShowcase ?? false,+ filePath: tsxPath,+ docPath,+ category: relPath,+ package: ext.name,+ });+ }+ }++ return blocks;+}++/**+ * Discover all blocks — core + external packages.+ * @param {string} [cwd]+ */+async function discoverAllBlocks(cwd = process.cwd()) {+ const [core, external] = await Promise.all([+ discoverBlocks(),+ discoverExternalBlocks(cwd),+ ]);+ return [...core, ...external];+}+async function discoverAll() {const [pages, blocks] = await Promise.all([discoverPages(),- discoverBlocks(),+ discoverAllBlocks(),]);return [...pages, ...blocks].sort((a, b) => a.name.localeCompare(b.name));}-export async function findRelatedBlocks(componentName) {- const blocks = await discoverBlocks();+export async function findRelatedBlocks(componentName, cwd) {+ const blocks = await discoverAllBlocks(cwd);return blocks.filter(b =>b.componentsUsed.some(c =>c.toLowerCase() === componentName.toLowerCase(),@@ -108,8 +159,8 @@ export async function findRelatedBlocks(componentName) {);}-export async function findShowcase(componentName) {- const blocks = await discoverBlocks();+export async function findShowcase(componentName, cwd) {+ const blocks = await discoverAllBlocks(cwd);const lc = componentName.toLowerCase();const showcases = blocks.filter(b => b.isShowcase);diff --git a/packages/cli/src/commands/external-showcase.test.mjs b/packages/cli/src/commands/external-showcase.test.mjsnew file mode 100644index 0000000000..7d8f6fc9e7--- /dev/null+++ b/packages/cli/src/commands/external-showcase.test.mjs@@ -0,0 +1,119 @@+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 {findShowcase, findRelatedBlocks} from '../api/template.mjs';++// These tests verify that findShowcase and findRelatedBlocks can discover+// blocks from external packages that declare xds.blocks in package.json.++let tmpDir;++function createFixture() {+ // Symlink real core package (needed for findCoreDir)+ const realCoreDir = path.resolve(import.meta.dirname, '..', '..', '..', 'core');+ const coreDir = path.join(tmpDir, 'packages', 'core');+ fs.mkdirSync(path.dirname(coreDir), {recursive: true});+ fs.symlinkSync(realCoreDir, coreDir);++ // External package with blocks+ const extDir = path.join(tmpDir, 'node_modules', '@test', 'ext');+ const blocksDir = path.join(extDir, 'blocks', 'components');++ // Employee showcase+ const employeeDir = path.join(blocksDir, 'Employee');+ fs.mkdirSync(employeeDir, {recursive: true});+ fs.writeFileSync(path.join(employeeDir, 'EmployeeShowcase.doc.mjs'), `+export const doc = {+ type: 'block',+ name: 'Employee — Profile Card',+ description: 'Employee profile card with hover preview.',+ isReady: true,+ isShowcase: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['Employee'],+};+`);+ fs.writeFileSync(path.join(employeeDir, 'EmployeeShowcase.tsx'),+ "'use client';\nexport default function EmployeeShowcase() { return <div>Employee</div>; }");++ // Diff showcase + example+ const diffDir = path.join(blocksDir, 'Diff');+ fs.mkdirSync(diffDir, {recursive: true});+ fs.writeFileSync(path.join(diffDir, 'DiffShowcase.doc.mjs'), `+export const doc = {+ type: 'block',+ name: 'Diff — Link with Hover Card',+ description: 'Diff link with automatic hover card preview.',+ isReady: true,+ isShowcase: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['Diff'],+};+`);+ fs.writeFileSync(path.join(diffDir, 'DiffShowcase.tsx'),+ "'use client';\nexport default function DiffShowcase() { return <div>Diff</div>; }");+ fs.writeFileSync(path.join(diffDir, 'DiffStatusBadges.doc.mjs'), `+export const doc = {+ type: 'block',+ name: 'Diff — Status Badges',+ description: 'Shows diff status badge variants.',+ isReady: true,+ aspectRatio: 1,+ componentsUsed: ['Diff', 'Badge'],+};+`);+ fs.writeFileSync(path.join(diffDir, 'DiffStatusBadges.tsx'),+ "'use client';\nexport default function DiffStatusBadges() { return <div>Diff</div>; }");++ fs.writeFileSync(path.join(extDir, 'package.json'), JSON.stringify({+ name: '@test/ext',+ xds: {docs: './src', category: 'Common', blocks: './blocks/components'},+ }));++ // Need src dir for docs (even if empty) since discoverExternalPackages checks it+ fs.mkdirSync(path.join(extDir, 'src'), {recursive: true});+}++beforeEach(() => {+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'xds-showcase-test-'));+ createFixture();+});++afterEach(() => {+ fs.rmSync(tmpDir, {recursive: true, force: true});+});++describe('findShowcase() with external packages', () => {+ it('finds showcase from external package by directory name', async () => {+ const result = await findShowcase('Employee', tmpDir);+ expect(result).not.toBeNull();+ expect(result.name).toBe('Employee — Profile Card');+ expect(result.filePath).toContain('EmployeeShowcase.tsx');+ });++ it('finds showcase from external package by componentsUsed', async () => {+ const result = await findShowcase('Diff', tmpDir);+ expect(result).not.toBeNull();+ expect(result.name).toBe('Diff — Link with Hover Card');+ });++ it('returns null for component with no showcase', async () => {+ const result = await findShowcase('NonExistent', tmpDir);+ expect(result).toBeNull();+ });+});++describe('findRelatedBlocks() with external packages', () => {+ it('finds related blocks from external package', async () => {+ const result = await findRelatedBlocks('Diff', tmpDir);+ expect(result).toHaveLength(2);+ const names = result.map(b => b.dirName).sort();+ expect(names).toEqual(['DiffShowcase', 'DiffStatusBadges']);+ });++ it('finds cross-package component references', async () => {+ const result = await findRelatedBlocks('Badge', tmpDir);+ expect(result.some(b => b.dirName === 'DiffStatusBadges')).toBe(true);+ });+});diff --git a/packages/cli/src/utils/paths.mjs b/packages/cli/src/utils/paths.mjsindex 4077248294..c8a47d9316 100644--- a/packages/cli/src/utils/paths.mjs+++ b/packages/cli/src/utils/paths.mjs@@ -71,9 +71,9 @@ export function findProjectRoot(startDir = process.cwd()) {* Discover external XDS-compatible packages from node_modules.* Scans for packages with an "xds" field in their package.json:*- * { "xds": { "docs": "./src", "category": "Common" } }+ * { "xds": { "docs": "./src", "category": "Common", "blocks": "./blocks/components" } }*- * Returns array of { name, category, docsDir }.+ * Returns array of { name, category, docsDir, blocksDir }.*/export function discoverExternalPackages(startDir = process.cwd()) {const externals = [];@@ -121,6 +121,9 @@ export function discoverExternalPackages(startDir = process.cwd()) {name: pkg.name,category: pkg.xds.category || pkg.name,docsDir: path.resolve(fullPath, pkg.xds.docs),+ blocksDir: pkg.xds.blocks+ ? path.resolve(fullPath, pkg.xds.blocks)+ : null,});}} catch {diff --git a/packages/cli/src/utils/paths.test.mjs b/packages/cli/src/utils/paths.test.mjsindex e9bfdcebe7..e82c0a03c0 100644--- a/packages/cli/src/utils/paths.test.mjs+++ b/packages/cli/src/utils/paths.test.mjs@@ -83,6 +83,7 @@ describe('discoverExternalPackages', () => {name: 'xds-charts',category: 'Data Viz',docsDir: path.join(extDir, 'src'),+ blocksDir: null,},]);});@@ -105,6 +106,7 @@ describe('discoverExternalPackages', () => {name: '@acme/xds-widgets',category: 'Widgets',docsDir: path.join(scopedDir, 'lib'),+ blocksDir: null,},]);});