@astryxdesign/cli 0.1.6-canary.e8d4c3f → 0.1.6-canary.eb23da7

package/src/lib/component-loader.mjs

@@ -7,7 +7,7 @@
 import {pathToFileURL} from 'node:url';
 import {importUserModule} from './module-loader.mjs';
 import {formatZodError} from './config-schema.mjs';
-import {ComponentDocSchema} from '../schemas/doc-schema.mjs';
+import {ComponentDocSchema} from '../doc.mjs';
 
 /**
  * Load a component doc through the shared load/validation boundary.
@@ -144,64 +144,15 @@ export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {
 
   const translation = mod[translationKey];
 
-  // A full ComponentDoc-shaped translation (legacy docsZh shape) used to be
-  // returned wholesale. That made it a REPLACEMENT, not an overlay: any prop
-  // the translation had not caught up with simply ceased to exist —
-  // `component Button --zh` silently omitted `isInterruptible` and
-  // `isIconOnly`. A reader of the translated docs cannot discover a prop that
-  // is not there. Overlay it instead, so an untranslated prop falls back to
-  // its English entry. (Same principle as the reference-doc overlays, #2182.)
+  // If the translation is a full ComponentDoc (legacy docsZh shape), return it directly
   if (translation.props || translation.components?.some(c => c.props)) {
-    return overlayComponentDoc(docs, translation);
+    return translation;
   }
 
   // Otherwise it's a TranslationDoc — merge it onto docs
   return mergeTranslation(docs, translation);
 }
 
-/**
- * Overlay a full-ComponentDoc-shaped translation onto the English doc.
- *
- * Base order and completeness win; the translation supplies text for the
- * entries it covers. Props are matched by name, never by position, so a
- * translation that is missing entries (or lists them in another order) can no
- * longer drop or misattribute one.
- *
- * @param {any} docs Base (English) component doc.
- * @param {any} translation Translated doc, possibly covering only some props.
- * @returns {any} Merged doc with every base prop present.
- */
-function overlayComponentDoc(docs, translation) {
-  /** Merge one prop list: keep base entries and order, translate what's covered. */
-  const overlayProps = (baseProps, tProps) => {
-    if (!baseProps) return baseProps;
-    const byName = new Map((tProps ?? []).map(p => [p.name, p]));
-    return baseProps.map(prop => {
-      const t = byName.get(prop.name);
-      // Take the translated text, but never let it drop the prop's contract
-      // (type/default/required stay authoritative from the English doc).
-      return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;
-    });
-  };
-
-  const merged = {...docs, ...translation};
-
-  merged.props = overlayProps(docs.props, translation.props);
-
-  if (docs.components) {
-    const tByName = new Map(
-      (translation.components ?? []).map(c => [c.name, c]),
-    );
-    merged.components = docs.components.map(base => {
-      const t = tByName.get(base.name);
-      if (!t) return base;
-      return {...base, ...t, props: overlayProps(base.props, t.props)};
-    });
-  }
-
-  return merged;
-}
-
 /**
  * Find the doc file for a component, checking both top-level
  * and nested directories. Prefers {Name}.doc.mjs, then README.md

package/src/lib/hook-format.mjs

@@ -11,7 +11,6 @@
 
 import {discoverHooks, findHookDoc} from './hook-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
-import {mdCell} from './component-format.mjs';
 
 /**
  * Build a signature string from hook docs.
@@ -52,11 +51,9 @@ function formatParamsTable(params) {
   lines.push('| Param | Type | Default | Description |');
   lines.push('|-------|------|---------|-------------|');
   for (const p of params) {
-    const def = p.default ? `\`${mdCell(p.default)}\`` : '\u2014';
+    const def = p.default ? `\`${p.default}\`` : '\u2014';
     const req = p.required ? ' **(required)**' : '';
-    lines.push(
-      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
-    );
+    lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
   }
   return lines.join('\n');
 }
@@ -70,9 +67,7 @@ function formatReturnsTable(returns) {
   lines.push('| Field | Type | Description |');
   lines.push('|-------|------|-------------|');
   for (const r of returns) {
-    lines.push(
-      `| \`${mdCell(r.name)}\` | \`${mdCell(r.type)}\` | ${mdCell(r.description)} |`,
-    );
+    lines.push(`| \`${r.name}\` | \`${r.type}\` | ${r.description} |`);
   }
   return lines.join('\n');
 }

package/src/template.mjs

@@ -1,15 +1,73 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Static template authoring API (public `@astryxdesign/cli/template`).
+ * @file Static template authoring API.
  *
- * The `createPageTemplate`/`createBlockTemplate` authoring helpers now live in
- * `@astryxdesign/core/authoring` and are re-exported here so existing
- * `@astryxdesign/cli/template` imports keep working. The Zod load-boundary
- * schemas live in `./schemas/template-schema.mjs` (core-free) and are
- * re-exported here for back-compat; internal hot-path code imports them from
- * the schema module directly so it never depends on core's built `dist/`.
+ * Helpers for authoring Astryx page/block template docs. Like
+ * `createConfig`/`createIntegration`, these are tiny runtime identity helpers
+ * whose real value is the exported TypeScript surface from
+ * `@astryxdesign/cli/template`. They inject the discriminant `type` so a
+ * discovered doc always knows whether it is a page or a block. They do NOT
+ * validate — validation happens at the load boundary, where integration
+ * template discovery runs the module's default export through
+ * {@link TemplateEnvelopeSchema} (see `loadModuleWithSchema`).
  */
 
-export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
-export {BaseTemplateSchema, TemplateEnvelopeSchema} from './schemas/template-schema.mjs';
+import {z} from 'zod';
+
+const PreviewSchema = z
+  .object({
+    image: z.string().optional(),
+    aspectRatio: z.string().optional(),
+  })
+  .strict();
+
+/**
+ * Shared authored-template shape. `type` is injected by the create* helpers,
+ * so authors never write it. Inline source/sourceFile are intentionally NOT
+ * part of v1 — a template's source is the required same-stem sibling file.
+ * Exported so integration template discovery can validate the stamped result.
+ */
+export const BaseTemplateSchema = z
+  .object({
+    name: z.string().min(1, 'name is required'),
+    description: z.string().min(1, 'description is required'),
+    category: z.string().optional(),
+    componentsUsed: z.array(z.string()).optional(),
+    preview: PreviewSchema.optional(),
+  })
+  .strict();
+
+/**
+ * The metadata envelope integration template discovery validates: a stamped
+ * template doc. This is the LOAD-boundary contract — a hand-written plain
+ * object that matches this shape is accepted (discovery does not check "was it
+ * made by the factory", only the shape).
+ */
+export const TemplateEnvelopeSchema = BaseTemplateSchema.extend({
+  type: z.enum(['page', 'block']),
+});
+
+/**
+ * Author an Astryx page template doc. Stamp-only: returns the def with
+ * `type: 'page'` injected. Validation happens at the load boundary.
+ *
+ * @template {import('./types/template-api').AstryxPageTemplateInput} T
+ * @param {T} def
+ * @returns {T & {type: 'page'}}
+ */
+export function createPageTemplate(def) {
+  return /** @type {T & {type: 'page'}} */ ({...def, type: 'page'});
+}
+
+/**
+ * Author an Astryx block template doc. Stamp-only: returns the def with
+ * `type: 'block'` injected. Validation happens at the load boundary.
+ *
+ * @template {import('./types/template-api').AstryxBlockTemplateInput} T
+ * @param {T} def
+ * @returns {T & {type: 'block'}}
+ */
+export function createBlockTemplate(def) {
+  return /** @type {T & {type: 'block'}} */ ({...def, type: 'block'});
+}

package/src/types/config.d.ts

@@ -1,15 +1,70 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * The config-authoring surface moved to `@astryxdesign/core/config` so an app's
- * config file gets type feedback without depending on the CLI. Re-exported here
- * so existing `@astryxdesign/cli/config` type imports keep resolving.
+ * A command to run as part of a post-codemod hook. Returned by a hook's
+ * `buildCommand` and executed via `execFile` after codemods write files.
  */
-export type {
-  PostCodemodCommand,
-  PostCodemodHook,
-  XleComponent,
-  AstryxConfig,
-} from '@astryxdesign/core/config';
-
-export {createConfig} from '@astryxdesign/core/config';
+export interface PostCodemodCommand {
+  command: string;
+  args?: string[];
+  options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+  };
+}
+
+/**
+ * A post-codemod hook. `buildCommand` receives the package directory and the
+ * list of files changed by codemods, and returns the command to run (or a
+ * nullish value to skip).
+ */
+export type PostCodemodHook = {
+  name?: string;
+  buildCommand: (ctx: {
+    packageDir: string;
+    files: string[];
+  }) =>
+    | PostCodemodCommand
+    | null
+    | undefined
+    | Promise<PostCodemodCommand | null | undefined>;
+};
+
+/** A component XLE layout expressions can reference by name via `{hint}`. */
+export interface XleComponent {
+  /** Import specifier the component is imported from, e.g. '@/components/KpiCard'. */
+  from: string;
+  /** Optional human description shown in tooling. */
+  description?: string;
+  /** Import as the module's default export instead of a named export. Defaults to false. */
+  default?: boolean;
+}
+
+/** User config exported from astryx.config.{ts,mjs,js}. */
+export interface AstryxConfig {
+  /** Integration package names to load. */
+  integrations?: string[];
+  /** Where to file issues/feedback for this project. */
+  issuesUrl?: string;
+  /** Lifecycle hooks. */
+  hooks?: {
+    postCodemod?: PostCodemodHook[];
+  };
+  /**
+   * EXPERIMENTAL — shape may change and is not part of the stable config
+   * contract. Provisional home for features still being proven out.
+   */
+  experimental?: {
+    /** Experimental XLE (layout expression) configuration. */
+    xle?: {
+      /**
+       * Register app-local components so XLE layout expressions can
+       * reference them by name via {hint}. Keyed by component name.
+       */
+      components?: Record<string, XleComponent>;
+    };
+  };
+}
+
+export declare function createConfig<T extends AstryxConfig>(config: T): T;

package/src/types/doc.d.ts

@@ -1,23 +1,139 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * The doc-authoring surface moved to `@astryxdesign/core/authoring`. Re-exported
- * here so existing `@astryxdesign/cli/doc` type imports keep resolving. The Zod
- * load-boundary schemas remain in the CLI (see `src/doc.mjs`).
+ * Authoring surface for Astryx docs, exported from `@astryxdesign/cli/doc`.
+ *
+ * A doc lives in a `{Name}.doc.{ts,mjs,js}` file. Authors default-export a
+ * factory result (`createComponentDoc`/`createFunctionDoc`/`createDoc`) —
+ * preferred — or, for the current loose docs, name-export `docs`. The doc's
+ * shape is validated at the load boundary against `ComponentDocSchema` (see
+ * `doc.mjs`), which accepts BOTH the new stamped formats and the legacy loose
+ * shape.
+ *
+ * The factories inject the `type` discriminant, so authors never write it. The
+ * inputs are kept as broad records so authoring never fails to typecheck when a
+ * richer core type surface is not resolvable; the precise per-field guidance
+ * lives on the doc types in `@astryxdesign/core/docs-types`.
  */
-export type {
-  AstryxBaseDocInput,
-  AstryxPropInput,
-  AstryxParamInput,
-  AstryxReturnInput,
-  AstryxComponentDocInput,
-  AstryxFunctionDocInput,
-  AstryxGenericDocInput,
-  AstryxComponentDoc,
-} from '@astryxdesign/core/authoring';
-
-export {
-  createComponentDoc,
-  createFunctionDoc,
-  createDoc,
-} from '@astryxdesign/core/authoring';
+
+/**
+ * Fields shared by every doc kind (component + function + generic).
+ *
+ * `group` vs `parent` are distinct:
+ *   - `group` is a FLAT sidebar bucket label; many docs can share it and it is
+ *     NOT an inheritance key.
+ *   - `parent` is a DIRECTED inheritance/composition pointer — a doc naming the
+ *     doc it belongs to (e.g. a sub-component naming its parent component). The
+ *     legacy `subComponentOf` field is a synonym.
+ *
+ * `relatedDocs` is a single flat curated cross-reference list; it replaces the
+ * legacy split `relatedComponents` + `relatedHooks`.
+ */
+export interface AstryxBaseDocInput {
+  /** Name of the documented unit, without any prefix, PascalCase. Required. */
+  name: string;
+  /** Human-readable display name for gallery/sidebar. */
+  displayName?: string;
+  /** Short description. */
+  description?: string;
+  /** Usage documentation (description, best practices, anatomy, slotElements). */
+  usage?: unknown;
+  /** Flat sidebar grouping label (not an inheritance key). */
+  group?: string;
+  /** Overview-page functional category. */
+  category?: string;
+  /** CLI fuzzy-search keywords. */
+  keywords?: string[];
+  /** Directed inheritance/composition pointer to the doc this belongs to. */
+  parent?: string;
+  /** Flat curated cross-reference list of related doc names. */
+  relatedDocs?: string[];
+  /** Hide the whole doc from human-facing UI (stays importable/discoverable). */
+  hidden?: boolean;
+  /** Exclude from the categorized overview page (kept in sidebar/CLI). */
+  isHiddenFromOverview?: boolean;
+  /** Any additional fields the rich doc surface carries. */
+  [key: string]: unknown;
+}
+
+/** A single documented prop (mirrors `PropDoc` from core docs-types). */
+export interface AstryxPropInput {
+  name: string;
+  type: string;
+  description: string;
+  default?: string;
+  required?: boolean;
+  [key: string]: unknown;
+}
+
+/** A single documented param (mirrors `HookParamDoc`). */
+export interface AstryxParamInput {
+  name: string;
+  type: string;
+  description: string;
+  default?: string;
+  required?: boolean;
+  [key: string]: unknown;
+}
+
+/** A single documented return field (mirrors `HookReturnDoc`). */
+export interface AstryxReturnInput {
+  name: string;
+  type: string;
+  description: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Input accepted by {@link createComponentDoc}. A component (or a family). The
+ * `type` discriminant is injected by the factory. `anatomy`/`slotElements` live
+ * inside `usage`; `importPath` is DERIVED (never authored).
+ */
+export interface AstryxComponentDocInput extends AstryxBaseDocInput {
+  /** All public props for the component. */
+  props: AstryxPropInput[];
+  /** Theming/selector-surface metadata. */
+  theming?: unknown;
+  /** Interactive-preview playground configuration. */
+  playground?: unknown;
+  /** Short code examples rendered after the props table. */
+  examples?: unknown[];
+}
+
+/**
+ * Input accepted by {@link createFunctionDoc}. Covers any function, including
+ * hooks: an inputs (`params`) + outputs (`returns`) surface. The `type`
+ * discriminant is injected by the factory; `importPath` is DERIVED.
+ */
+export interface AstryxFunctionDocInput extends AstryxBaseDocInput {
+  /** Function/hook parameters or options-object fields. */
+  params: AstryxParamInput[];
+  /** Return value documentation. One entry per field (or a single primitive). */
+  returns: AstryxReturnInput[];
+}
+
+/**
+ * Input accepted by {@link createDoc}. A generic reference/topic doc — just the
+ * shared base. The `type` discriminant is injected by the factory.
+ */
+export type AstryxGenericDocInput = AstryxBaseDocInput;
+
+/**
+ * Back-compat alias. Previously `createDoc` accepted a broad component-doc
+ * record; the union of the three input kinds preserves that permissiveness for
+ * any code referring to the old name.
+ */
+export type AstryxComponentDoc =
+  AstryxComponentDocInput | AstryxFunctionDocInput | AstryxGenericDocInput;
+
+export declare function createComponentDoc<T extends AstryxComponentDocInput>(
+  def: T,
+): T & {type: 'component'};
+
+export declare function createFunctionDoc<T extends AstryxFunctionDocInput>(
+  def: T,
+): T & {type: 'function'};
+
+export declare function createDoc<T extends AstryxGenericDocInput>(
+  def: T,
+): T & {type: 'generic'};

package/src/types/integration.d.ts

@@ -1,14 +1,21 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * The integration-manifest authoring surface moved to
- * `@astryxdesign/core/authoring`. `AstryxIntegration` and `createIntegration`
- * are re-exported here so existing `@astryxdesign/cli/integration` type imports
- * keep resolving. `AstryxIntegrationIssue` stays in the CLI — it is an internal
- * validation type, not part of the authoring surface.
+ * Integration manifest exported from a conventional root manifest file
+ * (astryx.integration.{ts,mjs,js}) sibling to the integration package's
+ * package.json. Identity (name/version) comes from the package's
+ * package.json, not from the manifest.
  */
-export type {AstryxIntegration} from '@astryxdesign/core/authoring';
-export {createIntegration} from '@astryxdesign/core/authoring';
+export interface AstryxIntegration {
+  /** Relative path to the components/docs root (resolved to absolute). */
+  components?: string;
+  /** Relative path to the templates root (resolved to absolute). */
+  templates?: string;
+  /** Relative path to the codemods root (resolved to absolute). */
+  codemods?: string;
+  /** Where to file issues/feedback for this integration. */
+  issuesUrl?: string;
+}
 
 /** An issue surfaced by an integration. */
 export interface AstryxIntegrationIssue {
@@ -16,3 +23,7 @@ export interface AstryxIntegrationIssue {
   severity: 'warning' | 'error';
   message: string;
 }
+
+export declare function createIntegration<T extends AstryxIntegration>(
+  integration: T,
+): T;

package/src/types/template-api.d.ts

@@ -1,18 +1,54 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * The template-authoring surface moved to `@astryxdesign/core/authoring`.
- * Re-exported here so existing `@astryxdesign/cli/template` type imports keep
- * resolving.
+ * Authoring surface for Astryx static templates, exported from
+ * `@astryxdesign/cli/template`.
+ *
+ * A template doc lives in a `<id>.doc.{ts,mjs,js}` file with a required
+ * same-stem sibling source file (`<id>.tsx`). The doc's `type` (page or
+ * block) — injected by the create* helpers — decides how the template is
+ * scaffolded; there is no `/pages` vs `/blocks` directory requirement.
  */
-export type {
-  AstryxTemplatePreview,
-  AstryxTemplateInput,
-  AstryxPageTemplateInput,
-  AstryxBlockTemplateInput,
-  AstryxPageTemplate,
-  AstryxBlockTemplate,
-  AstryxTemplate,
-} from '@astryxdesign/core/authoring';
-
-export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
+
+/** Optional preview metadata for a template (used by docs surfaces). */
+export interface AstryxTemplatePreview {
+  /** Path or URL to a preview image. */
+  image?: string;
+  /** CSS aspect-ratio hint for the preview, e.g. "16 / 9". */
+  aspectRatio?: string;
+}
+
+/** Fields common to page and block template docs (without the `type` tag). */
+export interface AstryxTemplateInput {
+  /** Human-readable template name. Required. */
+  name: string;
+  /** One-line description of what the template provides. Required. */
+  description: string;
+  /** Optional grouping/category label. */
+  category?: string;
+  /** Component display names the template composes. */
+  componentsUsed?: string[];
+  /** Optional preview metadata. */
+  preview?: AstryxTemplatePreview;
+}
+
+/** Input accepted by {@link createPageTemplate} (no `type` field). */
+export type AstryxPageTemplateInput = AstryxTemplateInput;
+/** Input accepted by {@link createBlockTemplate} (no `type` field). */
+export type AstryxBlockTemplateInput = AstryxTemplateInput;
+
+/** A validated page template doc. */
+export type AstryxPageTemplate = AstryxTemplateInput & {type: 'page'};
+/** A validated block template doc. */
+export type AstryxBlockTemplate = AstryxTemplateInput & {type: 'block'};
+
+/** A validated template doc (page or block). */
+export type AstryxTemplate = AstryxPageTemplate | AstryxBlockTemplate;
+
+export declare function createPageTemplate<T extends AstryxPageTemplateInput>(
+  def: T,
+): T & {type: 'page'};
+
+export declare function createBlockTemplate<T extends AstryxBlockTemplateInput>(
+  def: T,
+): T & {type: 'block'};

package/templates/pages/ide/page.tsx

@@ -69,8 +69,8 @@ const styles: Record<string, CSSProperties> = {
   propertyActions: {
     marginTop: 'auto',
   },
-  terminalPanel: {
-    flexShrink: 0,
+  terminalArea: {
+    height: '100%',
     overflow: 'hidden',
   },
 };
@@ -301,40 +301,46 @@ export default function ResizableWorkspacePage() {
                           label="Resize terminal"
                         />
                         {!bottomPanel.isCollapsed && (
-                          <Stack
-                            direction="vertical"
-                            height={bottomPanel.size}
-                            style={styles.terminalPanel}>
-                            <TabList
-                              value={activeTermTab}
-                              onChange={val => setActiveTermTab(val)}
-                              size="sm"
-                              hasDivider={false}
-                              style={styles.tabListPadding}>
-                              <Tab label="Terminal" value="terminal" />
-                              <Tab label="Problems" value="problems" />
-                              <Tab label="Output" value="output" />
-                              <Tab label="Debug" value="debug" />
-                            </TabList>
-                            <StackItem
-                              size="fill"
-                              style={styles.terminalWrapper}>
-                              <CodeBlock
-                                code={TERMINAL_OUTPUT}
-                                language="bash"
-                                container="section"
-                                hasLanguageLabel={false}
-                                hasCopyButton={false}
+                          <div
+                            style={{
+                              height: bottomPanel.size,
+                              flexShrink: 0,
+                              overflow: 'hidden',
+                            }}>
+                            <Stack
+                              direction="vertical"
+                              style={styles.contentFill}>
+                              <TabList
+                                value={activeTermTab}
+                                onChange={val => setActiveTermTab(val)}
                                 size="sm"
-                                style={{
-                                  width: '100%',
-                                  height: '100%',
-                                  borderWidth: 0,
-                                  borderRadius: 0,
-                                }}
-                              />
-                            </StackItem>
-                          </Stack>
+                                hasDivider={false}
+                                style={styles.tabListPadding}>
+                                <Tab label="Terminal" value="terminal" />
+                                <Tab label="Problems" value="problems" />
+                                <Tab label="Output" value="output" />
+                                <Tab label="Debug" value="debug" />
+                              </TabList>
+                              <StackItem
+                                size="fill"
+                                style={styles.terminalWrapper}>
+                                <CodeBlock
+                                  code={TERMINAL_OUTPUT}
+                                  language="bash"
+                                  container="section"
+                                  hasLanguageLabel={false}
+                                  hasCopyButton={false}
+                                  size="sm"
+                                  style={{
+                                    width: '100%',
+                                    height: '100%',
+                                    borderWidth: 0,
+                                    borderRadius: 0,
+                                  }}
+                                />
+                              </StackItem>
+                            </Stack>
+                          </div>
                         )}
                       </Stack>
                     </LayoutContent>