Skip to content

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

TypeScript

refactor(cli): split layout into api/layout leaf shape (#4478)

Joey08c99b8f01db
diff --git a/.changeset/cli-layout-leaves.md b/.changeset/cli-layout-leaves.md
new file mode 100644
index 0000000000..6fa66b1751
--- /dev/null
+++ b/.changeset/cli-layout-leaves.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[refactor] CLI: layout reorganized into the api/layout leaf shape — a shared `_adapter.mjs` (`analyze`/`loadBlocks`/`formatIssue` over `lib/xle`) with thin `expand/`, `check/`, and `grammar/` leaves, plus a `layout.mjs` barrel. `api/index.mjs` and the CLI are unchanged (they import via the barrel). Pure reorg: `layout expand`/`check`/`grammar` `--json` envelopes and human output are byte-identical.
+@josephfarina
diff --git a/.github/scripts/api-cli-parity-test.mjs b/.github/scripts/api-cli-parity-test.mjs
index f3f12f82bf..f147cc5351 100644
--- a/.github/scripts/api-cli-parity-test.mjs
+++ b/.github/scripts/api-cli-parity-test.mjs
@@ -200,11 +200,14 @@ if (firstTemplate) {
add('template nonexistent', ['template', 'nonexistent99'],
() => apiCall(api.template, 'nonexistent99'));
-// Theme add — list + error paths (read-only; never scaffolds files here).
+// Theme list + add error path (read-only; never scaffolds files here).
+// `theme list` / `theme add --list` are served by the dedicated themeList()
+// leaf (the CLI routes the --list affordance there); themeAdd() now only
+// scaffolds a named slug and throws on a missing/unknown one.
add('theme list', ['theme', 'list'],
- () => apiCall(api.themeAdd, undefined, {list: true, cwd: ROOT}));
+ () => apiCall(api.themeList));
add('theme add --list', ['theme', 'add', '--list'],
- () => apiCall(api.themeAdd, undefined, {list: true, cwd: ROOT}));
+ () => apiCall(api.themeList));
add('theme add nonexistent', ['theme', 'add', 'nonexistent99'],
() => apiCall(api.themeAdd, 'nonexistent99', {cwd: ROOT}));
diff --git a/packages/cli/api/layout/_adapter.mjs b/packages/cli/api/layout/_adapter.mjs
new file mode 100644
index 0000000000..4f670530dd
--- /dev/null
+++ b/packages/cli/api/layout/_adapter.mjs
@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Shared analysis layer for the `layout` command's expand/check leaves.
+ *
+ * Loads the block catalog (template blocks + app-registered components), builds
+ * the branch registry, and parses+validates a layout expression into a doc +
+ * issues. Both the expand and check leaves sit on `analyze`; neither parses or
+ * validates directly. (The grammar leaf needs none of this — it only reads the
+ * registry alias table.)
+ *
+ * @input expression string (+ options)
+ * @output analyze() -> {doc, registry, blocks, errors, warnings}; formatIssue()
+ * @position api — shared core over lib/xle; leaves in expand/ + check/ project it
+ */
+
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {parse, XLEParseError} from '../../lib/xle/parse.mjs';
+import {validate} from '../../lib/xle/validate.mjs';
+import {buildRegistry} from '../../lib/xle/registry.mjs';
+import {discoverTemplates} from '../template/template.mjs';
+import {Project} from '../../lib/project.mjs';
+
+/**
+ * @typedef {object} LayoutBlock
+ * @property {string} dirName
+ * @property {string} name
+ * @property {'template'|'component'} kind
+ * @property {string} [type]
+ * @property {string} [description]
+ * @property {string} [category]
+ * @property {string} [importPath]
+ * @property {string} [filePath]
+ * @property {boolean} [isDefault]
+ */
+
+/**
+ * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus
+ * any app-registered local components from astryx.config.mjs
+ * `experimental.xle.components` (imported by name). App components are how XLE
+ * reaches domain pieces — the KpiCard/chart/drawer set that the
+ * @astryxdesign/core registry can't see.
+ *
+ * @param {string} cwd
+ * @returns {Promise<LayoutBlock[]>}
+ */
+async function loadBlocks(cwd) {
+ /** @type {LayoutBlock[]} */
+ const blocks = [];
+ try {
+ const all = await discoverTemplates(cwd);
+ for (const t of all) if (t.type === 'block') blocks.push({...t, kind: 'template'});
+ } catch {
+ // discovery is best-effort
+ }
+ try {
+ const project = await Project.load(cwd);
+ /** @type {Record<string, {from?: string, description?: string, default?: boolean}>} */
+ const components = project.config.experimental?.xle?.components ?? {};
+ for (const [name, spec] of Object.entries(components)) {
+ const importPath = spec.from;
+ if (!importPath) continue;
+ blocks.push({
+ type: 'block',
+ kind: 'component',
+ dirName: name,
+ name,
+ description: spec.description ?? '',
+ category: 'app',
+ importPath,
+ isDefault: Boolean(spec.default),
+ });
+ }
+ } catch {
+ // config is optional
+ }
+ return blocks;
+}
+
+/** @param {import('../../lib/xle/xle-ast').RawIssue} issue */
+export function formatIssue(issue) {
+ const where = issue.line != null ? `line ${issue.line}: ` : '';
+ return `${where}${issue.message}`;
+}
+
+/**
+ * Parse + validate, throwing structured XDSErrors on failure.
+ * Returns {doc, registry, blocks, warnings}.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ */
+export async function analyze(expression, {form = 'auto', loose = false, cwd = process.cwd()} = {}) {
+ const registry = /** @type {import('../../lib/xle/xle-ast').Registry} */ (
+ /** @type {unknown} */ (await buildRegistry({cwd}))
+ );
+ const blocks = await loadBlocks(cwd);
+
+ /** @type {import('../../lib/xle/xle-ast').XLEDoc} */
+ let doc;
+ try {
+ doc = parse(expression, {form});
+ } catch (e) {
+ if (e instanceof XLEParseError) {
+ throw new AstryxError(
+ `Layout expression syntax error at line ${e.line}, col ${e.col}: ${e.message}`,
+ undefined,
+ ERROR_CODES.ERR_LAYOUT_PARSE,
+ );
+ }
+ throw e;
+ }
+
+ const {errors, warnings} = validate(doc, registry, blocks, {loose});
+ return {doc, registry, blocks, errors, warnings};
+}
diff --git a/packages/cli/api/layout/check/check.mjs b/packages/cli/api/layout/check/check.mjs
new file mode 100644
index 0000000000..5fa0bd7133
--- /dev/null
+++ b/packages/cli/api/layout/check/check.mjs
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout check` leaf — validate a layout expression without
+ * expanding, echoing both canonical surfaces (compact + outline). Resolution +
+ * validation come from ../_adapter.mjs (analyze); this leaf projects the
+ * `layout.check` envelope.
+ *
+ * @input expression string (+ options)
+ * @output {type:'layout.check', data}
+ * @position api — leaf over ../_adapter.mjs + lib/xle/print
+ */
+
+import {toCompact, toOutline} from '../../../lib/xle/print.mjs';
+import {analyze, formatIssue} from '../_adapter.mjs';
+
+/**
+ * `astryx layout check "<expr>" [--form compact|outline]`
+ * Validates without expanding; echoes both canonical surfaces.
+ *
+ * @param {string} expression
+ * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
+ * @returns {Promise<import('../../../types/layout').LayoutCheckResponse>}
+ */
+export async function layoutCheck(expression, options = {}) {
+ const {form = 'auto', loose = false, cwd = process.cwd()} = options;
+ const {doc, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+ return {
+ type: 'layout.check',
+ data: {
+ valid: errors.length === 0,
+ form: doc.form,
+ errors: errors.map(e => ({...e, formatted: formatIssue(e)})),
+ warnings: warnings.map(formatIssue),
+ compact: toCompact(doc),
+ outline: toOutline(doc),
+ },
+ };
+}
diff --git a/packages/cli/api/layout/expand/expand.mjs b/packages/cli/api/layout/expand/expand.mjs
new file mode 100644
index 0000000000..16d854db2f
--- /dev/null
+++ b/packages/cli/api/layout/expand/expand.mjs
@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout expand` leaf — expand a validated layout expression into
+ * XDS TSX (optionally written to disk). Resolution + validation come from
+ * ../_adapter.mjs (analyze); this leaf owns block-module assembly, code
+ * generation, and the path-safe write, and projects the `layout.expand` envelope.
+ *
+ * @input expression string (+ options)
+ * @output {type:'layout.expand', data}
+ * @position api — leaf over ../_adapter.mjs + lib/xle/expand
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../lib/error-codes.mjs';
+import {assertWithin, isFilePathArg, PathSafetyError} from '../../../utils/path-safety.mjs';
+import {detectForm} from '../../../lib/xle/parse.mjs';
+import {expand} from '../../../lib/xle/expand.mjs';
+import {stripTemplateAssetRefs} from '../../template/template.mjs';
+import {analyze, formatIssue} from '../_adapter.mjs';
+
+/** @param {string} name */
+const normKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/**
+ * Collect the block names referenced by {hints} anywhere in the doc.
+ * @param {import('../../../lib/xle/xle-ast').XLEDoc} doc
+ */
+function collectHintNames(doc) {
+ /** @type {Set<string>} */
+ const names = new Set();
+ /** @param {import('../../../lib/xle/xle-ast').XLEItem} node */
+ const visitNode = (node) => {
+ if (!node || node.kind === 'group') {
+ (node?.children || []).forEach(visit);
+ return;
+ }
+ if (node.hint?.block) names.add(node.hint.block.name);
+ for (const slot of node.slots || []) {
+ const value = slot.value;
+ if (value && typeof value === 'object' && 'hint' in value && value.hint?.block) {
+ names.add(value.hint.block.name);
+ }
+ if (value && typeof value === 'object' && 'subexpr' in value) {
+ (value.subexpr || []).forEach(visit);
+ }
+ }
+ (node.children || []).forEach(visit);
+ };
+ /** @param {import('../../../lib/xle/xle-ast').XLEItem} item */
+ const visit = (item) => (item?.kind === 'group' ? item.children.forEach(visit) : visitNode(item));
+ doc.roots.forEach(visit);
+ doc.overlays.forEach(visit);
+ return names;
+}
+
+/**
+ * Build the blockModules map expand() needs: import-mode for app components,
+ * splice-mode (reading + asset-stripping the block source) for template blocks.
+ * Only blocks actually referenced are read.
+ *
+ * @param {import('../../../lib/xle/xle-ast').XLEDoc} doc
+ * @param {import('../_adapter.mjs').LayoutBlock[]} blocks
+ * @returns {Map<string, import('../../../lib/xle/xle-ast').BlockModule>}
+ */
+function buildBlockModules(doc, blocks) {
+ const referenced = collectHintNames(doc);
+ if (referenced.size === 0) return new Map();
+ const byKey = new Map(blocks.map(b => [normKey(b.dirName), b]));
+ /** @type {Map<string, import('../../../lib/xle/xle-ast').BlockModule>} */
+ const modules = new Map();
+ for (const name of referenced) {
+ const block = byKey.get(normKey(name));
+ if (!block) continue;
+ if (block.kind === 'component') {
+ modules.set(name, /** @type {import('../../../lib/xle/xle-ast').BlockModule} */ (/** @type {unknown} */ ({mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault})));
+ } else if (block.filePath && fs.existsSync(block.filePath)) {
+ modules.set(name, /** @type {import('../../../lib/xle/xle-ast').BlockModule} */ ({mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))}));
+ }
+ }
+ return modules;
+}
+
+/**
+ * `astryx layout expand "<expr>" [path]`
+ *
+ * @param {string} expression
+ * @param {object} [options]
+ * @param {string} [options.targetPath] - write TSX here (validated against cwd)
+ * @param {'compact'|'outline'|'auto'} [options.form]
+ * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings
+ * @param {string} [options.name] - generated component name
+ * @param {string} [options.cwd]
+ * @returns {Promise<import('../../../types/layout').LayoutExpandResponse>}
+ */
+export async function layoutExpand(expression, options = {}) {
+ const {targetPath, form = 'auto', loose = false, name, cwd = process.cwd()} = options;
+ const {doc, registry, blocks, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+ if (errors.length > 0) {
+ throw new AstryxError(
+ `Layout expression is invalid:\n` + errors.map(e => ` - ${formatIssue(e)}`).join('\n'),
+ errors.flatMap(e => (e.suggestions || []).map(s => ({name: s, reason: 'did you mean this?'}))),
+ ERROR_CODES.ERR_LAYOUT_INVALID,
+ );
+ }
+
+ const componentName = name || 'GeneratedLayout';
+ if (!/^[A-Z][A-Za-z0-9]*$/.test(componentName)) {
+ throw new AstryxError(
+ `--name must be a PascalCase component name, got '${componentName}'`,
+ undefined,
+ ERROR_CODES.ERR_INVALID_ARGUMENT,
+ );
+ }
+ const blockModules = buildBlockModules(doc, blocks);
+ const result = expand(doc, registry, {componentName, blockModules});
+
+ let written = null;
+ if (targetPath) {
+ let resolved;
+ try {
+ resolved = assertWithin(targetPath, cwd, {label: 'layout target path'});
+ } catch (err) {
+ if (err instanceof PathSafetyError) {
+ throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+ }
+ throw err;
+ }
+ const filePath = isFilePathArg(targetPath)
+ ? resolved
+ : path.join(resolved, `${componentName}.tsx`);
+ fs.mkdirSync(path.dirname(filePath), {recursive: true});
+ fs.writeFileSync(filePath, result.code);
+ written = path.relative(cwd, filePath);
+ }
+
+ return {
+ type: 'layout.expand',
+ data: {
+ form: form === 'auto' ? detectForm(expression) : form,
+ code: result.code,
+ componentsUsed: result.componentsUsed,
+ states: result.states,
+ todos: result.todos,
+ blocksReferenced: [...blockModules.entries()].map(([name, m]) => ({name, mode: m.mode})),
+ warnings: warnings.map(formatIssue),
+ written,
+ },
+ };
+}
diff --git a/packages/cli/api/layout/grammar/grammar.mjs b/packages/cli/api/layout/grammar/grammar.mjs
new file mode 100644
index 0000000000..fe8bb17a63
--- /dev/null
+++ b/packages/cli/api/layout/grammar/grammar.mjs
@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout grammar` leaf — the agent cheatsheet, with the alias
+ * table generated from this branch's registry (never hand-maintained). Reads
+ * only the registry; shares nothing with expand/check, so it has no adapter.
+ *
+ * @output {type:'layout.grammar', data}
+ * @position api — leaf over lib/xle/registry
+ */
+
+import {buildRegistry, ALIAS_TABLE} from '../../../lib/xle/registry.mjs';
+
+/**
+ * `astryx layout grammar` — the agent cheatsheet, with the alias table
+ * generated from this branch's registry (never hand-maintained).
+ *
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('../../../types/layout').LayoutGrammarResponse>}
+ */
+export async function layoutGrammar(options = {}) {
+ const {cwd = process.cwd()} = options;
+ const registry = await buildRegistry({cwd});
+
+ /** @type {string[]} */
+ const aliasLines = [];
+ /** @type {Map<string, string[]>} */
+ const byTarget = new Map();
+ for (const [alias, target] of registry.aliases) {
+ if (!byTarget.has(target)) byTarget.set(target, []);
+ byTarget.get(target)?.push(alias);
+ }
+ for (const [target, aliases] of [...byTarget.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+ aliasLines.push(`${aliases.join('/')}=${target}`);
+ }
+
+ const text = `XLE/XLO — XDS layout expressions (branch-generated; aliases reflect this install)
+
+WORKFLOW
+ astryx layout check "<expr>" validate; echoes canonical compact + outline forms
+ astryx layout expand "<expr>" [path] emit validated TSX (path optional; --name <Pascal>)
+ Errors carry line/col + suggestions. Fix and resubmit; nothing is guessed.
+
+TWO SURFACES, ONE LANGUAGE (autodetected; --form to force)
+ compact: A[cp6 @topNav=TN] > L > LC > S[p6] > (C{card-callout}*4) + T
+ outline: indentation = nesting · same-indent = siblings · "repeat N:" block = (...)*N
+ slot lines: topNav: TN (or a block: topNav:\\n TN ...)
+
+NODE ANATOMY Name#id.enum"payload"[attrs]{hint}*N > children
+ .enum unique enum value of any prop: Bd.success Tx.lg B.primary
+ "payload" primary text prop (label/title/heading) or text child: TI"Email" B"Save"
+ {hint} kebab-case template/component reference (see TEMPLATE REFERENCING) — NEVER text
+ *N / xN repeat (use $ for the counter: Tk"item-$"*3)
+ trailing ! initial selection for scaffolded state: Tab"Overview"!
+
+ATTRS [...] (outline: bare tokens after the name, no brackets)
+ fused p6 g4 c4 w240 h2 cp2 mw960 rg2 cg2 (per-component: padding lives on Card/Section/AppShell.cp — p6 on AppShell/Layout/VStack errors with a correction)
+ key=value t=email href='/x' c{min:340} dv=[top,bottom] — keys validated per component
+ flags req opt dis striped hover divider … (isX/hasX props) · negate: !scroll
+ align j= main axis, a= cross axis — expander picks hAlign/vAlign per stack direction
+ slots @slotName=Node | @slotName=(sub > expr) | @slotName='text' | @slotName=#id
+ trigger opens=#id (a plain attr, no @ — binds an onClick that opens the overlay)
+ fill on a stack child → wraps in <StackItem size="fill">
+
+TEMPLATE REFERENCING ({hint} pulls in real content — this is how XLE reaches past the @astryxdesign/core shell)
+ C{card-callout} splice a template block (astryx template --list --type block):
+ the block is co-defined once in the file, referenced, imports merged
+ {kpi-card} standalone reference (no wrapper element) — place a component directly
+ {kpi-card}*4 repeat a reference; the definition/import is emitted once
+ app components register local ones in astryx.config.mjs to import them by name:
+ export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}}}}}
+ then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)
+
+STRUCTURE THE EXPANDER HANDLES
+ Layout > LH + LC + LF + LP children auto-route into header/content/footer/start slots
+ T > (TR>THC*4) + (TR>TC*4)*6 rows partition into TableHeader/TableBody automatically
+ TabList/inputs required value+onChange scaffold typed useState automatically
+ overlays compact: tree ;; Dlg#confirm[...] · outline: overlays: section
+ trigger: B"Delete"[opens=#confirm]
+
+ALIASES (full component names always valid; XDS prefix optional)
+ ${aliasLines.join(' ')}
+`;
+
+ return {type: 'layout.grammar', data: {text, aliases: Object.fromEntries(registry.aliases)}};
+}
+
+export {ALIAS_TABLE};
diff --git a/packages/cli/api/layout/layout.mjs b/packages/cli/api/layout/layout.mjs
index bf0b8074ba..cbc291cead 100644
--- a/packages/cli/api/layout/layout.mjs
+++ b/packages/cli/api/layout/layout.mjs
@@ -1,351 +1,17 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Programmatic API for the layout command (XLE/XLO).
+ * @file `layout` command barrel — re-exports the expand/check/grammar leaves so
+ * the CLI (cli/commands/layout.mjs) and scripted callers import from one place.
+ * Each leaf is also importable directly (e.g. api/layout/expand/expand.mjs). The
+ * shared analysis core lives in ./_adapter.mjs. `layout` has real subcommands,
+ * so there is no flag-dispatch here — the CLI calls the leaf it wants.
*
- * `astryx layout` turns token-compressed layout expressions into validated
- * XDS TSX. Two input surfaces — compact (Emmet-derived XLE) and outline
- * (indentation-based XLO) — share one AST, one validator, and one
- * expander. See the research: pastes P2376666892 (spec) and P2376717669
- * (outline surface).
- *
- * @input expression string (+ options)
+ * @input layout expressions (+ options), per leaf
* @output {type, data} envelopes: layout.expand / layout.check / layout.grammar
- * @position api — pure orchestration over lib/xle; command wrapper in commands/layout.mjs
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {AstryxError} from '../error.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
-import {assertWithin, isFilePathArg, PathSafetyError} from '../../utils/path-safety.mjs';
-import {parse, detectForm, XLEParseError} from '../../lib/xle/parse.mjs';
-import {validate} from '../../lib/xle/validate.mjs';
-import {expand} from '../../lib/xle/expand.mjs';
-import {toCompact, toOutline} from '../../lib/xle/print.mjs';
-import {buildRegistry, ALIAS_TABLE} from '../../lib/xle/registry.mjs';
-import {discoverTemplates, stripTemplateAssetRefs} from '../template/template.mjs';
-import {Project} from '../../lib/project.mjs';
-
-/**
- * @typedef {object} LayoutBlock
- * @property {string} dirName
- * @property {string} name
- * @property {'template'|'component'} kind
- * @property {string} [type]
- * @property {string} [description]
- * @property {string} [category]
- * @property {string} [importPath]
- * @property {string} [filePath]
- * @property {boolean} [isDefault]
- */
-
-/**
- * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus
- * any app-registered local components from astryx.config.mjs
- * `experimental.xle.components` (imported by name). App components are how XLE
- * reaches domain pieces — the KpiCard/chart/drawer set that the
- * @astryxdesign/core registry can't see.
- *
- * @param {string} cwd
- * @returns {Promise<LayoutBlock[]>}
- */
-async function loadBlocks(cwd) {
- /** @type {LayoutBlock[]} */
- const blocks = [];
- try {
- const all = await discoverTemplates(cwd);
- for (const t of all) if (t.type === 'block') blocks.push({...t, kind: 'template'});
- } catch {
- // discovery is best-effort
- }
- try {
- const project = await Project.load(cwd);
- /** @type {Record<string, {from?: string, description?: string, default?: boolean}>} */
- const components = project.config.experimental?.xle?.components ?? {};
- for (const [name, spec] of Object.entries(components)) {
- const importPath = spec.from;
- if (!importPath) continue;
- blocks.push({
- type: 'block',
- kind: 'component',
- dirName: name,
- name,
- description: spec.description ?? '',
- category: 'app',
- importPath,
- isDefault: Boolean(spec.default),
- });
- }
- } catch {
- // config is optional
- }
- return blocks;
-}
-
-/** @param {string} name */
-const normKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
-
-/**
- * Collect the block names referenced by {hints} anywhere in the doc.
- * @param {import('../../lib/xle/xle-ast').XLEDoc} doc
+ * @position api — command barrel over the expand/check/grammar leaves
*/
-function collectHintNames(doc) {
- /** @type {Set<string>} */
- const names = new Set();
- /** @param {import('../../lib/xle/xle-ast').XLEItem} node */
- const visitNode = (node) => {
- if (!node || node.kind === 'group') {
- (node?.children || []).forEach(visit);
- return;
- }
- if (node.hint?.block) names.add(node.hint.block.name);
- for (const slot of node.slots || []) {
- const value = slot.value;
- if (value && typeof value === 'object' && 'hint' in value && value.hint?.block) {
- names.add(value.hint.block.name);
- }
- if (value && typeof value === 'object' && 'subexpr' in value) {
- (value.subexpr || []).forEach(visit);
- }
- }
- (node.children || []).forEach(visit);
- };
- /** @param {import('../../lib/xle/xle-ast').XLEItem} item */
- const visit = (item) => (item?.kind === 'group' ? item.children.forEach(visit) : visitNode(item));
- doc.roots.forEach(visit);
- doc.overlays.forEach(visit);
- return names;
-}
-
-/**
- * Build the blockModules map expand() needs: import-mode for app components,
- * splice-mode (reading + asset-stripping the block source) for template blocks.
- * Only blocks actually referenced are read.
- *
- * @param {import('../../lib/xle/xle-ast').XLEDoc} doc
- * @param {LayoutBlock[]} blocks
- * @returns {Map<string, import('../../lib/xle/xle-ast').BlockModule>}
- */
-function buildBlockModules(doc, blocks) {
- const referenced = collectHintNames(doc);
- if (referenced.size === 0) return new Map();
- const byKey = new Map(blocks.map(b => [normKey(b.dirName), b]));
- /** @type {Map<string, import('../../lib/xle/xle-ast').BlockModule>} */
- const modules = new Map();
- for (const name of referenced) {
- const block = byKey.get(normKey(name));
- if (!block) continue;
- if (block.kind === 'component') {
- modules.set(name, /** @type {import('../../lib/xle/xle-ast').BlockModule} */ (/** @type {unknown} */ ({mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault})));
- } else if (block.filePath && fs.existsSync(block.filePath)) {
- modules.set(name, /** @type {import('../../lib/xle/xle-ast').BlockModule} */ ({mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))}));
- }
- }
- return modules;
-}
-
-/** @param {import('../../lib/xle/xle-ast').RawIssue} issue */
-function formatIssue(issue) {
- const where = issue.line != null ? `line ${issue.line}: ` : '';
- return `${where}${issue.message}`;
-}
-
-/**
- * Parse + validate, throwing structured XDSErrors on failure.
- * Returns {doc, registry, blocks, warnings}.
- *
- * @param {string} expression
- * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
- */
-async function analyze(expression, {form = 'auto', loose = false, cwd = process.cwd()} = {}) {
- const registry = /** @type {import('../../lib/xle/xle-ast').Registry} */ (
- /** @type {unknown} */ (await buildRegistry({cwd}))
- );
- const blocks = await loadBlocks(cwd);
-
- /** @type {import('../../lib/xle/xle-ast').XLEDoc} */
- let doc;
- try {
- doc = parse(expression, {form});
- } catch (e) {
- if (e instanceof XLEParseError) {
- throw new AstryxError(
- `Layout expression syntax error at line ${e.line}, col ${e.col}: ${e.message}`,
- undefined,
- ERROR_CODES.ERR_LAYOUT_PARSE,
- );
- }
- throw e;
- }
-
- const {errors, warnings} = validate(doc, registry, blocks, {loose});
- return {doc, registry, blocks, errors, warnings};
-}
-
-/**
- * `astryx layout expand "<expr>" [path]`
- *
- * @param {string} expression
- * @param {object} [options]
- * @param {string} [options.targetPath] - write TSX here (validated against cwd)
- * @param {'compact'|'outline'|'auto'} [options.form]
- * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings
- * @param {string} [options.name] - generated component name
- * @param {string} [options.cwd]
- */
-export async function layoutExpand(expression, options = {}) {
- const {targetPath, form = 'auto', loose = false, name, cwd = process.cwd()} = options;
- const {doc, registry, blocks, errors, warnings} = await analyze(expression, {form, loose, cwd});
-
- if (errors.length > 0) {
- throw new AstryxError(
- `Layout expression is invalid:\n` + errors.map(e => ` - ${formatIssue(e)}`).join('\n'),
- errors.flatMap(e => (e.suggestions || []).map(s => ({name: s, reason: 'did you mean this?'}))),
- ERROR_CODES.ERR_LAYOUT_INVALID,
- );
- }
-
- const componentName = name || 'GeneratedLayout';
- if (!/^[A-Z][A-Za-z0-9]*$/.test(componentName)) {
- throw new AstryxError(
- `--name must be a PascalCase component name, got '${componentName}'`,
- undefined,
- ERROR_CODES.ERR_INVALID_ARGUMENT,
- );
- }
- const blockModules = buildBlockModules(doc, blocks);
- const result = expand(doc, registry, {componentName, blockModules});
-
- let written = null;
- if (targetPath) {
- let resolved;
- try {
- resolved = assertWithin(targetPath, cwd, {label: 'layout target path'});
- } catch (err) {
- if (err instanceof PathSafetyError) {
- throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
- }
- throw err;
- }
- const filePath = isFilePathArg(targetPath)
- ? resolved
- : path.join(resolved, `${componentName}.tsx`);
- fs.mkdirSync(path.dirname(filePath), {recursive: true});
- fs.writeFileSync(filePath, result.code);
- written = path.relative(cwd, filePath);
- }
-
- return {
- type: 'layout.expand',
- data: {
- form: form === 'auto' ? detectForm(expression) : form,
- code: result.code,
- componentsUsed: result.componentsUsed,
- states: result.states,
- todos: result.todos,
- blocksReferenced: [...blockModules.entries()].map(([name, m]) => ({name, mode: m.mode})),
- warnings: warnings.map(formatIssue),
- written,
- },
- };
-}
-
-/**
- * `astryx layout check "<expr>" [--form compact|outline]`
- * Validates without expanding; echoes both canonical surfaces.
- *
- * @param {string} expression
- * @param {{form?: 'compact'|'outline'|'auto', loose?: boolean, cwd?: string}} [options]
- */
-export async function layoutCheck(expression, options = {}) {
- const {form = 'auto', loose = false, cwd = process.cwd()} = options;
- const {doc, errors, warnings} = await analyze(expression, {form, loose, cwd});
-
- return {
- type: 'layout.check',
- data: {
- valid: errors.length === 0,
- form: doc.form,
- errors: errors.map(e => ({...e, formatted: formatIssue(e)})),
- warnings: warnings.map(formatIssue),
- compact: toCompact(doc),
- outline: toOutline(doc),
- },
- };
-}
-
-/**
- * `astryx layout grammar` — the agent cheatsheet, with the alias table
- * generated from this branch's registry (never hand-maintained).
- *
- * @param {{cwd?: string}} [options]
- */
-export async function layoutGrammar(options = {}) {
- const {cwd = process.cwd()} = options;
- const registry = await buildRegistry({cwd});
-
- /** @type {string[]} */
- const aliasLines = [];
- /** @type {Map<string, string[]>} */
- const byTarget = new Map();
- for (const [alias, target] of registry.aliases) {
- if (!byTarget.has(target)) byTarget.set(target, []);
- byTarget.get(target)?.push(alias);
- }
- for (const [target, aliases] of [...byTarget.entries()].sort(([a], [b]) => a.localeCompare(b))) {
- aliasLines.push(`${aliases.join('/')}=${target}`);
- }
-
- const text = `XLE/XLO — XDS layout expressions (branch-generated; aliases reflect this install)
-
-WORKFLOW
- astryx layout check "<expr>" validate; echoes canonical compact + outline forms
- astryx layout expand "<expr>" [path] emit validated TSX (path optional; --name <Pascal>)
- Errors carry line/col + suggestions. Fix and resubmit; nothing is guessed.
-
-TWO SURFACES, ONE LANGUAGE (autodetected; --form to force)
- compact: A[cp6 @topNav=TN] > L > LC > S[p6] > (C{card-callout}*4) + T
- outline: indentation = nesting · same-indent = siblings · "repeat N:" block = (...)*N
- slot lines: topNav: TN (or a block: topNav:\\n TN ...)
-
-NODE ANATOMY Name#id.enum"payload"[attrs]{hint}*N > children
- .enum unique enum value of any prop: Bd.success Tx.lg B.primary
- "payload" primary text prop (label/title/heading) or text child: TI"Email" B"Save"
- {hint} kebab-case template/component reference (see TEMPLATE REFERENCING) — NEVER text
- *N / xN repeat (use $ for the counter: Tk"item-$"*3)
- trailing ! initial selection for scaffolded state: Tab"Overview"!
-
-ATTRS [...] (outline: bare tokens after the name, no brackets)
- fused p6 g4 c4 w240 h2 cp2 mw960 rg2 cg2 (per-component: padding lives on Card/Section/AppShell.cp — p6 on AppShell/Layout/VStack errors with a correction)
- key=value t=email href='/x' c{min:340} dv=[top,bottom] — keys validated per component
- flags req opt dis striped hover divider … (isX/hasX props) · negate: !scroll
- align j= main axis, a= cross axis — expander picks hAlign/vAlign per stack direction
- slots @slotName=Node | @slotName=(sub > expr) | @slotName='text' | @slotName=#id
- trigger opens=#id (a plain attr, no @ — binds an onClick that opens the overlay)
- fill on a stack child → wraps in <StackItem size="fill">
-
-TEMPLATE REFERENCING ({hint} pulls in real content — this is how XLE reaches past the @astryxdesign/core shell)
- C{card-callout} splice a template block (astryx template --list --type block):
- the block is co-defined once in the file, referenced, imports merged
- {kpi-card} standalone reference (no wrapper element) — place a component directly
- {kpi-card}*4 repeat a reference; the definition/import is emitted once
- app components register local ones in astryx.config.mjs to import them by name:
- export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}}}}}
- then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)
-
-STRUCTURE THE EXPANDER HANDLES
- Layout > LH + LC + LF + LP children auto-route into header/content/footer/start slots
- T > (TR>THC*4) + (TR>TC*4)*6 rows partition into TableHeader/TableBody automatically
- TabList/inputs required value+onChange scaffold typed useState automatically
- overlays compact: tree ;; Dlg#confirm[...] · outline: overlays: section
- trigger: B"Delete"[opens=#confirm]
-
-ALIASES (full component names always valid; XDS prefix optional)
- ${aliasLines.join(' ')}
-`;
-
- return {type: 'layout.grammar', data: {text, aliases: Object.fromEntries(registry.aliases)}};
-}
-export {ALIAS_TABLE};
+export {layoutExpand} from './expand/expand.mjs';
+export {layoutCheck} from './check/check.mjs';
+export {layoutGrammar, ALIAS_TABLE} from './grammar/grammar.mjs';