Skip to content

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

TypeScript

feat(cli): template --list compositions + --skeleton spatial reference (#1132)

Cindy Zhang00b06f7c6337
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index 114e4119b5..7f7fac19b9 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -129,7 +129,7 @@ export function generateCompressedIndex(version, {coreDir, zh = false, lang, run
}
}
- // Templates from live discovery
+ // Templates — list shows compositions, skeleton shows spatial structure
const templatesDir = path.join(CLI_ROOT, 'templates');
if (fs.existsSync(templatesDir)) {
const templates = fs.readdirSync(templatesDir, {withFileTypes: true})
@@ -137,7 +137,9 @@ export function generateCompressedIndex(version, {coreDir, zh = false, lang, run
.map(e => e.name)
.sort();
if (templates.length > 0) {
- lines.push(`${run} template <name> [path] scaffold page (${templates.join(', ')})`);
+ lines.push(`${run} template --list layout recipes with component compositions`);
+ lines.push(`${run} template <name> --skeleton spatial reference (padding, gap, nesting)`);
+ lines.push(`${run} template <name> [path] scaffold page from template`);
}
}
diff --git a/packages/cli/src/commands/template.mjs b/packages/cli/src/commands/template.mjs
index e91134704f..0ef192123d 100644
--- a/packages/cli/src/commands/template.mjs
+++ b/packages/cli/src/commands/template.mjs
@@ -4,12 +4,17 @@
* Copies template files from packages/cli/templates/{name}/ to a target path.
* Template metadata comes from template.doc.mjs files (TemplateDoc type).
* Templates without a doc file fall back to directory name only.
+ *
+ * --list: Show all templates with component compositions
+ * --skeleton: Show layout skeleton with spatial annotations (padding, gap)
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import {CLI_ROOT} from '../utils/paths.mjs';
+// ── Template discovery ───────────────────────────────────────────────
+
async function loadTemplateDoc(templateDir) {
const docPath = path.join(templateDir, 'template.doc.mjs');
if (!fs.existsSync(docPath)) return null;
@@ -49,38 +54,243 @@ export function listTemplates() {
.sort();
}
+// ── Component extraction ─────────────────────────────────────────────
+
+/**
+ * Extract distinguishing XDS component names from a template's page.tsx.
+ * Filters out ubiquitous components (Text, Button, HStack, etc.) to show
+ * only the structural components that define the template's composition.
+ */
+function extractComponents(pagePath) {
+ const src = fs.readFileSync(pagePath, 'utf-8');
+ const UBIQUITOUS = new Set([
+ 'Text', 'Heading', 'Button', 'HStack', 'VStack', 'Link',
+ 'StackItem', 'Icon',
+ ]);
+ return [...new Set(
+ (src.match(/XDS[A-Z]\w+/g) || [])
+ .map(n => n.replace(/^XDS/, ''))
+ .filter(n => !['Theme', 'ThemeProvider'].includes(n))
+ .filter(n => !UBIQUITOUS.has(n))
+ .map(n => n.replace(/(Item|Section|Header|Content|Footer|Panel|Heading|CollapseButton|Column|Sortable|Selection|Group|Source)$/, ''))
+ .filter(Boolean),
+ )].sort();
+}
+
+// ── Skeleton extraction ──────────────────────────────────────────────
+
+/**
+ * Extract a layout skeleton from template source code.
+ * Shows the XDS component nesting tree with spatial props
+ * (padding, gap, contentPadding, hasDivider, maxWidth, etc.).
+ *
+ * Structural components (Layout, AppShell, Card, Grid, Section, List, Table,
+ * TabList, Toolbar) are always shown with full nesting. Leaf content
+ * components (Text, Heading, Button, Badge, etc.) are collapsed to single
+ * lines to keep the skeleton focused on spatial structure.
+ */
+function extractSkeleton(source) {
+ const lines = source.split('\n');
+ const out = [];
+ let depth = 0;
+ let capturing = false;
+ let inDefaultExport = false;
+ const MAX_LINES = 35;
+
+ const STRUCTURAL = new Set([
+ 'AppShell', 'Layout', 'LayoutHeader', 'LayoutContent', 'LayoutPanel',
+ 'LayoutFooter', 'Card', 'Section', 'Grid', 'GridSpan', 'List',
+ 'Table', 'TabList', 'Toolbar', 'SideNav', 'TopNav', 'Dialog',
+ 'FormLayout', 'Center',
+ ]);
+
+ const depthStack = [];
+
+ for (let i = 0; i < lines.length; i++) {
+ const t = lines[i].trim();
+
+ if (t.match(/^export\s+default\s+function/)) {
+ inDefaultExport = true;
+ continue;
+ }
+ if (inDefaultExport && t.match(/^return\s*\(/)) {
+ capturing = true;
+ continue;
+ }
+ if (!capturing) continue;
+ if (out.length >= MAX_LINES) {
+ if (!out[out.length - 1]?.includes('...')) out.push(' '.repeat(depth) + '...');
+ continue;
+ }
+
+ // XDS opening tag
+ const openMatch = t.match(/^<(XDS\w+)/);
+ if (openMatch && !t.startsWith('</')) {
+ const comp = openMatch[1].replace(/^XDS/, '');
+ const isStructural = STRUCTURAL.has(comp);
+
+ // Gather spatial props
+ let tagText = '';
+ for (let j = i; j < Math.min(i + 12, lines.length); j++) {
+ tagText += ' ' + lines[j];
+ if (lines[j].includes('>')) break;
+ }
+
+ const props = [];
+ const propRegex = /\b(padding|contentPadding|gap|rowGap|columnGap|columns|minChildWidth|hasDivider|defaultHasDividers|variant|density|role|height|width|maxWidth)\s*[=]\s*\{?\s*['"]?([^}'"\s,/>]+)/g;
+ let m;
+ while ((m = propRegex.exec(tagText)) !== null) {
+ const val = m[2];
+ if (val === 'true') props.push(m[1]);
+ else if (/^\d+$/.test(val)) props.push(`${m[1]}={${val}}`);
+ else props.push(`${m[1]}="${val}"`);
+ }
+
+ const hasSpatialProps = props.length > 0;
+ const propStr = hasSpatialProps ? ' ' + props.join(' ') : '';
+ const isVStack = comp === 'VStack' || comp === 'HStack';
+ const isSelfClosing = tagText.match(new RegExp('<' + openMatch[1] + '[^>]*/>', 's'));
+
+ // VStack/HStack: only show if they have gap props
+ if (isVStack && !hasSpatialProps) continue;
+
+ if (isSelfClosing) {
+ out.push(' '.repeat(depth) + `<${comp}${propStr} />`);
+ } else if (isStructural || (isVStack && hasSpatialProps)) {
+ out.push(' '.repeat(depth) + `<${comp}${propStr}>`);
+ depthStack.push(comp);
+ depth++;
+ } else {
+ out.push(' '.repeat(depth) + `<${comp}${propStr} />`);
+ }
+ continue;
+ }
+
+ // Closing tag
+ const closeMatch = t.match(/^<\/(XDS\w+)>/);
+ if (closeMatch) {
+ const comp = closeMatch[1].replace(/^XDS/, '');
+ if (depthStack.length > 0 && depthStack[depthStack.length - 1] === comp) {
+ depthStack.pop();
+ depth = Math.max(0, depth - 1);
+ out.push(' '.repeat(depth) + `</${comp}>`);
+ }
+ continue;
+ }
+
+ // Slot props
+ const slotMatch = t.match(/^(header|content|footer|start|end|sideNav|topNav)\s*=\s*\{/);
+ if (slotMatch) {
+ out.push(' '.repeat(depth) + `/* ${slotMatch[1]}: */`);
+ continue;
+ }
+
+ // Wrapper divs with spatial styles
+ if (t.startsWith('<div') && (t.includes('padding') || t.includes('maxWidth') || t.includes('gap:'))) {
+ const styleProps = [];
+ const divText = lines.slice(i, Math.min(i + 5, lines.length)).join(' ');
+ const pp = divText.match(/padding[^:]*:\s*['"]?([^'"},)]+)/);
+ const mw = divText.match(/maxWidth:\s*(\d+)/);
+ const gp = divText.match(/gap:\s*(\d+)/);
+ const mg = divText.match(/margin:\s*['"]([^'"]+)['"]/);
+ const mi = divText.match(/marginInline:\s*['"]([^'"]+)['"]/);
+ if (pp) styleProps.push(`padding: ${pp[1].trim()}`);
+ if (mw) styleProps.push(`maxWidth: ${mw[1]}`);
+ if (gp) styleProps.push(`gap: ${gp[1]}`);
+ if (mg) styleProps.push(`margin: ${mg[1]}`);
+ if (mi) styleProps.push(`marginInline: ${mi[1]}`);
+ if (styleProps.length > 0) {
+ out.push(' '.repeat(depth) + `/* div: ${styleProps.join(', ')} */`);
+ }
+ }
+ }
+
+ return out.filter(l => l.trim()).join('\n');
+}
+
+// ── Command ──────────────────────────────────────────────────────────
+
export function registerTemplate(program) {
program
.command('template [name] [path]')
.description('Inject a page template')
- .option('--list', 'List available templates')
+ .option('--list', 'List available templates with component compositions')
+ .option(
+ '--skeleton',
+ 'Show layout skeleton with spatial annotations (padding, gap, nesting)',
+ )
.action(async (name, targetPath, options) => {
+ const templatesDir = path.join(CLI_ROOT, 'templates');
const templates = await discoverTemplates();
const templateNames = templates.map(t => t.dirName);
- if (options.list || !name) {
+ // --list: show all templates with compositions
+ if (options.list || (!name && !options.skeleton)) {
console.log('\nAvailable templates:\n');
for (const t of templates) {
const status = t.isReady ? '' : ' (WIP)';
- const desc = t.description ? ` — ${t.description}` : '';
- console.log(` ${t.dirName}${status}${desc}`);
+ const pagePath = path.join(templatesDir, t.dirName, 'page.tsx');
+ const comps = fs.existsSync(pagePath)
+ ? extractComponents(pagePath)
+ : [];
+ const compStr =
+ comps.length > 0 ? ` [${comps.join(', ')}]` : '';
+
+ console.log(` ${t.dirName}${status}`);
+ if (t.description) console.log(` ${t.description}`);
+ if (compStr) console.log(` ${compStr}`);
}
- console.log('\nUsage: xds template <name> [target-path]\n');
- console.log('Example: xds template blank ./src/pages/home\n');
+ console.log('\nUsage:');
+ console.log(' xds template <name> [target-path] Scaffold page');
+ console.log(
+ ' xds template <name> --skeleton Layout reference\n',
+ );
return;
}
- if (!templateNames.includes(name)) {
+ // Validate template name
+ if (name && !templateNames.includes(name)) {
console.error(`Error: Unknown template "${name}".`);
console.error(`Available: ${templateNames.join(', ')}`);
process.exit(1);
}
+ // --skeleton: show layout skeleton for a specific template
+ if (options.skeleton) {
+ if (!name) {
+ console.error(
+ 'Error: Specify a template name. Usage: xds template <name> --skeleton',
+ );
+ console.error(`Available: ${templateNames.join(', ')}`);
+ process.exit(1);
+ }
+
+ const pagePath = path.join(templatesDir, name, 'page.tsx');
+ if (!fs.existsSync(pagePath)) {
+ console.error(`Error: No page.tsx found for template "${name}".`);
+ process.exit(1);
+ }
+
+ const src = fs.readFileSync(pagePath, 'utf-8');
+ const skeleton = extractSkeleton(src);
+ const comps = extractComponents(pagePath);
+
+ const doc = await loadTemplateDoc(path.join(templatesDir, name));
+ const desc = doc?.description || '';
+
+ console.log(`\n# ${name}${desc ? ' — ' + desc : ''}`);
+ console.log(`# Components: ${comps.join(', ')}\n`);
+ console.log(skeleton);
+ console.log('');
+ return;
+ }
+
+ // Default: scaffold the template
const outputDir = path.resolve(
process.cwd(),
targetPath || `./src/pages/${name}`,
);
- const templateDir = path.join(CLI_ROOT, 'templates', name);
+ const templateDir = path.join(templatesDir, name);
fs.mkdirSync(outputDir, {recursive: true});