@astryxdesign/cli 0.1.6-canary.1b61ba6 → 0.1.6-canary.1d64659

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/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/themes/neutral/neutralTheme.ts

@@ -39,19 +39,19 @@ import {neutralIconRegistry} from './icons';
 const neutralSyntax = defineSyntaxTheme({
   name: 'xds-neutral',
   tokens: {
-    keyword: ['#700084', '#efa8ff'], // purple T30/T80
-    string: ['#005600', '#a6d2a2'], // green (sat T30 / pastel T80)
-    comment: ['#737373', '#a3a3a3'], // neutral
-    number: ['#6e3500', '#ffb37f'], // orange
-    function: ['#00458c', '#a0caff'], // blue T30/T80 H=255
-    type: ['#700084', '#efa8ff'], // purple
-    variable: ['#171717', '#e5e5e5'], // near-black / near-white
-    operator: ['#737373', '#a3a3a3'], // neutral
-    constant: ['#6e3500', '#ffb37f'], // orange
-    tag: ['#89001a', '#ffaeaa'], // red
-    attribute: ['#584400', '#eec12f'], // yellow
-    property: ['#005348', '#83dac9'], // teal
-    punctuation: ['#a3a3a3', '#525252'], // neutral
+    keyword: ['#700084', '#efa8ff'],    // purple T30/T80
+    string: ['#005600', '#a6d2a2'],     // green (sat T30 / pastel T80)
+    comment: ['#737373', '#a3a3a3'],    // neutral
+    number: ['#6e3500', '#ffb37f'],     // orange
+    function: ['#00458c', '#a0caff'],   // blue T30/T80 H=255
+    type: ['#700084', '#efa8ff'],       // purple
+    variable: ['#171717', '#e5e5e5'],   // near-black / near-white
+    operator: ['#737373', '#a3a3a3'],   // neutral
+    constant: ['#6e3500', '#ffb37f'],   // orange
+    tag: ['#89001a', '#ffaeaa'],        // red
+    attribute: ['#584400', '#eec12f'],  // yellow
+    property: ['#005348', '#83dac9'],   // teal
+    punctuation: ['#a3a3a3', '#525252'],// neutral
     background: ['#fafafa', '#0a0a0a'],
   },
 });
@@ -127,39 +127,39 @@ export const neutralTheme = defineTheme({
     // All values use the OKLCH Neutral tonal palette (chroma=0).
     // =========================================================================
     '--color-background-surface': ['#ffffff', '#262626'],
-    '--color-background-body': ['#f1f1f1', '#1b1b1b'],
-    '--color-background-card': ['#ffffff', '#1b1b1b'],
+    '--color-background-body':    ['#f1f1f1', '#1b1b1b'],
+    '--color-background-card':    ['#ffffff', '#1b1b1b'],
     '--color-background-popover': ['#ffffff', '#1b1b1b'],
-    '--color-background-muted': ['#f1f1f1', '#1b1b1b'],
+    '--color-background-muted':   ['#f1f1f1', '#1b1b1b'],
 
     // Accent + neutral surface tints (sit alongside backgrounds)
-    '--color-accent': ['#262626', '#ebebeb'],
+    '--color-accent':       ['#262626', '#ebebeb'],
     '--color-accent-muted': ['#f1f1f1', '#262626'],
-    '--color-neutral': ['#0000000F', '#FFFFFF1A'],
+    '--color-neutral':      ['#0000000F', '#FFFFFF1A'],
 
     // Overlays (modal scrims, hover/pressed tints)
-    '--color-overlay': ['#00000080', '#000000CC'],
-    '--color-overlay-hover': ['#0000000D', '#FFFFFF0D'],
+    '--color-overlay':         ['#00000080', '#000000CC'],
+    '--color-overlay-hover':   ['#0000000D', '#FFFFFF0D'],
     '--color-overlay-pressed': ['#0000001A', '#FFFFFF1A'],
 
     // Text
-    '--color-text-primary': ['#171717', '#fafafa'],
+    '--color-text-primary':   ['#171717', '#fafafa'],
     '--color-text-secondary': ['#737373', '#a3a3a3'],
-    '--color-text-disabled': ['#a3a3a3', '#525252'],
-    '--color-text-accent': ['#262626', '#ebebeb'],
-    '--color-on-dark': '#ffffff',
-    '--color-on-light': '#171717',
+    '--color-text-disabled':  ['#a3a3a3', '#525252'],
+    '--color-text-accent':    ['#262626', '#ebebeb'],
+    '--color-on-dark':    '#ffffff',
+    '--color-on-light':   '#171717',
     // Contrast: neutral accent is near-black (L) / near-white (D)
-    '--color-on-accent': ['#ffffff', '#171717'],
+    '--color-on-accent':  ['#ffffff', '#171717'],
     '--color-on-success': ['#ffffff', '#171717'],
-    '--color-on-error': ['#ffffff', '#171717'],
+    '--color-on-error':   ['#ffffff', '#171717'],
     '--color-on-warning': '#171717',
 
     // Icon
-    '--color-icon-accent': ['#262626', '#ebebeb'],
-    '--color-icon-primary': ['#171717', '#fafafa'],
+    '--color-icon-accent':    ['#262626', '#ebebeb'],
+    '--color-icon-primary':   ['#171717', '#fafafa'],
     '--color-icon-secondary': ['#737373', '#a3a3a3'],
-    '--color-icon-disabled': ['#a3a3a3', '#525252'],
+    '--color-icon-disabled':  ['#a3a3a3', '#525252'],
 
     // Status / Sentiment — dark mode follows the issue #2150 rubric:
     //
@@ -372,8 +372,8 @@ export const neutralTheme = defineTheme({
     // =========================================================================
     button: {
       'variant:destructive': {
-        backgroundColor: 'var(--color-error-muted)', // locked pastel red bg
-        color: 'var(--color-error)', // locked T30 red — matches banner/input error text
+        backgroundColor: 'var(--color-error-muted)',  // locked pastel red bg
+        color: 'var(--color-error)',                  // locked T30 red — matches banner/input error text
       },
     },
 
@@ -482,37 +482,6 @@ export const neutralTheme = defineTheme({
       },
     },
 
-    // =========================================================================
-    // StatusDot — fill uses the SAME vivid stops as the filled semantic Badge
-    // (and ProgressBar), so a dot and its badge read as one status language.
-    //
-    // The default component maps each variant to a raw semantic token
-    // (--color-success / --color-error / --color-warning / --color-icon-
-    // secondary), which in light mode are the dark T30/T40 stops meant to
-    // sit as TEXT on a pastel surface — as a solid dot they read muddy
-    // (dark green / maroon / brown). Redirect them to the badge fills.
-    //
-    //   success → badge success bg  (green T45 / dark-ramp T60)
-    //   warning → badge warning bg  (yellow T85, same hex both modes)
-    //   error   → badge error bg    (red T55 / dark-ramp T60)
-    //   accent  → badge info bg     (blue T50 / dark-ramp T60) — the
-    //             StatusDot "accent" is the info/attention color, so it
-    //             pairs with the info badge rather than --color-accent
-    //             (near-black #262626, the darkest offender).
-    //
-    // `neutral` is intentionally NOT overridden: the neutral badge bg is a
-    // near-invisible light gray (--color-background-gray #e5e5e5 / 10% white
-    // wash), fine as a large pill but unreadable as an 8px dot. It keeps the
-    // component default's visible mid-gray (--color-icon-secondary), which is
-    // not among the "too dark" cases.
-    // =========================================================================
-    statusdot: {
-      'variant:success': {backgroundColor: 'light-dark(#198100, #64af4c)'},
-      'variant:warning': {backgroundColor: '#ffce2f'},
-      'variant:error': {backgroundColor: 'light-dark(#e33f4a, #ff705d)'},
-      'variant:accent': {backgroundColor: 'light-dark(#0074e2, #6d9cfe)'},
-    },
-
     // =========================================================================
     // Banner — sits on a hue-tinted surface with colored text/icon:
     //   Light: pastel T90 bg (pulled from --color-{X}-muted / --color-background-blue)

package/docs/integration-authoring.md

@@ -1,105 +0,0 @@
-# Authoring an Astryx Integration
-
-> **Status:** working notes. This should eventually move to the public wiki
-> alongside the rest of the integration-authoring guidance; it lives here for
-> now so it ships and is versioned with the CLI.
-
-An **Integration** is an npm package that contributes components, templates, and/or
-codemods to a consumer's design-system workflow. Consumers install the 3rd party
-package, add a line to their astryx.config file:
-
-```js
-import {createConfig} from '@astryxdesign/cli/config';
-
-export default createConfig({
-  integrations: ['@acme/astryx-widgets'],
-  ...
-});
-```
-
-Then the integration's components and templates will be surfaced alongside Astryx
-components in the Astryx CLI.
-
-```sh
-astryx component AcmeCarousel --props
-astryx component --list --package @acme/astryx-widgets
-```
-
-## The Integration File
-
-In order to register your package as an Astryx Integration, create an
-`astryx.integration.{ts,mjs,js}` file as a sibling to your `package.json`. This file
-tells Astryx where to find your components, templates, codemods, etc.
-
-```js
-// astryx.integration.{ts,mjs,js}
-import {createIntegration} from '@astryxdesign/cli/integration';
-
-export default createIntegration({
-  components: './components',
-  templates: './templates',
-  codemods: './codemods',
-  issuesUrl: 'https://github.com/acme/widgets/issues',
-});
-```
-
-## Components
-
-Your components themselves may be exported from your library as you see fit (consumers
-will still import them from your package) but Astryx CLI will look for a .doc.{ts,mjs,js}
-file with the same stem e.g. `AcmeCarousel.tsx` and `AcmeCarousel.doc.ts`.
-
-```js
-// AcmeCarousel.doc.ts
-import {createComponentDoc} from '@astryxdesign/cli/doc';
-
-export default createComponentDoc({
-  name: 'AcmeCarousel',
-  description: '...',
-  ...
-});
-```
-
-## Templates
-
-Templates are typically not exported from the package directly, but instead accessed
-via the Astryx CLI. Consumers can look through your templates and materialize them
-into their apps.
-
-You define a template with the `createPageTemplate` (for full pages) or `createBlockTemplate`
-(for smaller chunks). e.g. `AcmeLandingPage.tsx`, `AcmeLandingPage.template.ts`
-
-```js
-// AcmeLandingPage.template.ts
-import {createPageTemplate} from '@astryxdesign/cli/template';
-
-export default createPageTemplate({
-  ...
-});
-```
-
-Note that, since the CLI needs access to the template source code, you need to make sure
-that it is included in your published package. This will also allow us to render previews
-of templates in the future by bundling your template into a doc site build.
-
-Typically, this is done via the package.json `exports` key.
-
-```jsonc
-{
-  "exports": {
-    // ...
-    "./templates/*.tsx": "./templates/*.tsx",
-  },
-}
-```
-
-In order to verify that it's working, you can test importing the template component like this:
-
-```ts
-import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');
-```
-
-Import **with the `.tsx` extension** — an extensionless specifier won't resolve
-under `moduleResolution: bundler`. The extensionful `"./templates/*.tsx"` export
-above is what lets that import type-check without consumers enabling
-`allowImportingTsExtensions`.