@astryxdesign/core 0.1.5 → 0.1.6-canary.02f2602

package/dist/authoring/doc.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @file doc.ts
+ * @input A component/function/generic doc object (without the `type` tag).
+ * @output Type-preserving `createComponentDoc`/`createFunctionDoc`/`createDoc`
+ *   helpers plus the doc-authoring TypeScript surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * A doc describes a documentable unit of the design system so the CLI and docs
+ * surfaces can list, search, and render it. There are three kinds, each a tiny
+ * runtime identity helper that stamps a `type` discriminant:
+ *
+ *   - `createComponentDoc` -> `type: 'component'` — a component (or a family).
+ *   - `createFunctionDoc`  -> `type: 'function'`  — any function, including
+ *      hooks: an "inputs + outputs" surface (`params` + `returns`).
+ *   - `createDoc`          -> `type: 'generic'`   — reference/topic docs.
+ *
+ * These factories do NOT validate. Validation happens at the CLI load boundary,
+ * where doc discovery runs the loaded value through a schema that accepts BOTH
+ * the stamped formats and the legacy loose `export const docs = {...}` shape.
+ */
+/**
+ * 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;
+/**
+ * Author a component doc. Stamp-only: returns the def with `type: 'component'`
+ * injected. Validation happens at the CLI load boundary.
+ */
+export declare function createComponentDoc<T extends AstryxComponentDocInput>(def: T): T & {
+    type: 'component';
+};
+/**
+ * Author a function doc (covers any function, including hooks). Stamp-only:
+ * returns the def with `type: 'function'` injected. Validation happens at the
+ * CLI load boundary.
+ */
+export declare function createFunctionDoc<T extends AstryxFunctionDocInput>(def: T): T & {
+    type: 'function';
+};
+/**
+ * Author a generic reference/topic doc. Stamp-only: returns the def with
+ * `type: 'generic'` injected. Validation happens at the CLI load boundary.
+ */
+export declare function createDoc<T extends AstryxGenericDocInput>(def: T): T & {
+    type: 'generic';
+};
+//# sourceMappingURL=doc.d.ts.map

package/dist/authoring/doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/authoring/doc.ts"],"names":[],"mappings":"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"}

package/dist/authoring/doc.js

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file doc.ts
+ * @input A component/function/generic doc object (without the `type` tag).
+ * @output Type-preserving `createComponentDoc`/`createFunctionDoc`/`createDoc`
+ *   helpers plus the doc-authoring TypeScript surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * A doc describes a documentable unit of the design system so the CLI and docs
+ * surfaces can list, search, and render it. There are three kinds, each a tiny
+ * runtime identity helper that stamps a `type` discriminant:
+ *
+ *   - `createComponentDoc` -> `type: 'component'` — a component (or a family).
+ *   - `createFunctionDoc`  -> `type: 'function'`  — any function, including
+ *      hooks: an "inputs + outputs" surface (`params` + `returns`).
+ *   - `createDoc`          -> `type: 'generic'`   — reference/topic docs.
+ *
+ * These factories do NOT validate. Validation happens at the CLI load boundary,
+ * where doc discovery runs the loaded value through a schema that accepts BOTH
+ * the stamped formats and the legacy loose `export const docs = {...}` shape.
+ */
+
+/**
+ * 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`.
+ */
+
+/** A single documented prop (mirrors `PropDoc` from core docs-types). */
+
+/** A single documented param (mirrors `HookParamDoc`). */
+
+/** A single documented return field (mirrors `HookReturnDoc`). */
+
+/**
+ * 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).
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * Input accepted by {@link createDoc}. A generic reference/topic doc — just the
+ * shared base. The `type` discriminant is injected by the factory.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * Author a component doc. Stamp-only: returns the def with `type: 'component'`
+ * injected. Validation happens at the CLI load boundary.
+ */
+export function createComponentDoc(def) {
+  return {
+    ...def,
+    type: 'component'
+  };
+}
+
+/**
+ * Author a function doc (covers any function, including hooks). Stamp-only:
+ * returns the def with `type: 'function'` injected. Validation happens at the
+ * CLI load boundary.
+ */
+export function createFunctionDoc(def) {
+  return {
+    ...def,
+    type: 'function'
+  };
+}
+
+/**
+ * Author a generic reference/topic doc. Stamp-only: returns the def with
+ * `type: 'generic'` injected. Validation happens at the CLI load boundary.
+ */
+export function createDoc(def) {
+  return {
+    ...def,
+    type: 'generic'
+  };
+}

package/dist/authoring/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file index.ts
+ * @input None (barrel).
+ * @output The Astryx integration-authoring surface: the stamp-only factories an
+ *   integration package uses to describe what it contributes (integrations,
+ *   templates, docs), plus their TypeScript input/output types.
+ * @position Producer-facing authoring surface, exported as
+ *   `@astryxdesign/core/authoring`.
+ *
+ * ## Why these live in core
+ *
+ * These factories are tiny, zero-runtime-dependency identity functions whose
+ * value is their TypeScript surface. Hosting them in `@astryxdesign/core` (the
+ * base of the dependency graph) means core's own docs can adopt them without a
+ * core -> cli -> core cycle, and integration authors get the types without a
+ * hard dependency on the CLI. The CLI re-exports every factory from its
+ * existing subpaths (`@astryxdesign/cli/integration|template|doc`) for
+ * back-compat; the CLI keeps the Zod validation schemas at its load boundary.
+ *
+ * `createConfig` is intentionally NOT here — it is a consumer surface (every app
+ * with an `astryx.config`), exported separately as `@astryxdesign/core/config`.
+ */
+export { createIntegration } from './integration';
+export type { AstryxIntegration } from './integration';
+export { createPageTemplate, createBlockTemplate } from './template';
+export type { AstryxTemplatePreview, AstryxTemplateInput, AstryxPageTemplateInput, AstryxBlockTemplateInput, AstryxPageTemplate, AstryxBlockTemplate, AstryxTemplate, } from './template';
+export { createComponentDoc, createFunctionDoc, createDoc } from './doc';
+export type { AstryxBaseDocInput, AstryxPropInput, AstryxParamInput, AstryxReturnInput, AstryxComponentDocInput, AstryxFunctionDocInput, AstryxGenericDocInput, AstryxComponentDoc, } from './doc';
+//# sourceMappingURL=index.d.ts.map

package/dist/authoring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/authoring/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAChD,YAAY,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAErD,OAAO,EAAC,kBAAkB,EAAE,mBAAmB,EAAC,MAAM,YAAY,CAAC;AACnE,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AACvE,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,OAAO,CAAC"}

package/dist/authoring/index.js

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input None (barrel).
+ * @output The Astryx integration-authoring surface: the stamp-only factories an
+ *   integration package uses to describe what it contributes (integrations,
+ *   templates, docs), plus their TypeScript input/output types.
+ * @position Producer-facing authoring surface, exported as
+ *   `@astryxdesign/core/authoring`.
+ *
+ * ## Why these live in core
+ *
+ * These factories are tiny, zero-runtime-dependency identity functions whose
+ * value is their TypeScript surface. Hosting them in `@astryxdesign/core` (the
+ * base of the dependency graph) means core's own docs can adopt them without a
+ * core -> cli -> core cycle, and integration authors get the types without a
+ * hard dependency on the CLI. The CLI re-exports every factory from its
+ * existing subpaths (`@astryxdesign/cli/integration|template|doc`) for
+ * back-compat; the CLI keeps the Zod validation schemas at its load boundary.
+ *
+ * `createConfig` is intentionally NOT here — it is a consumer surface (every app
+ * with an `astryx.config`), exported separately as `@astryxdesign/core/config`.
+ */
+
+export { createIntegration } from "./integration.js";
+export { createPageTemplate, createBlockTemplate } from "./template.js";
+export { createComponentDoc, createFunctionDoc, createDoc } from "./doc.js";

package/dist/authoring/integration.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file integration.ts
+ * @input An integration package's manifest object.
+ * @output A type-preserving `createIntegration` helper plus the
+ *   `AstryxIntegration` manifest surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * `createIntegration` is an intentionally tiny runtime identity function: it
+ * returns its argument unchanged. Validation is NOT performed here — it happens
+ * at the CLI load boundary.
+ */
+/**
+ * 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 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;
+}
+/**
+ * Type-preserving helper for an Astryx integration manifest. Returns its
+ * argument unchanged; the value is the exported TypeScript surface. Validation
+ * happens at the CLI load boundary.
+ */
+export declare function createIntegration<T extends AstryxIntegration>(integration: T): T;
+//# sourceMappingURL=integration.d.ts.map

package/dist/authoring/integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.d.ts","sourceRoot":"","sources":["../../src/authoring/integration.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,iBAAiB,EAC3D,WAAW,EAAE,CAAC,GACb,CAAC,CAEH"}

package/dist/authoring/integration.js

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file integration.ts
+ * @input An integration package's manifest object.
+ * @output A type-preserving `createIntegration` helper plus the
+ *   `AstryxIntegration` manifest surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * `createIntegration` is an intentionally tiny runtime identity function: it
+ * returns its argument unchanged. Validation is NOT performed here — it happens
+ * at the CLI load boundary.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * Type-preserving helper for an Astryx integration manifest. Returns its
+ * argument unchanged; the value is the exported TypeScript surface. Validation
+ * happens at the CLI load boundary.
+ */
+export function createIntegration(integration) {
+  return integration;
+}

package/dist/authoring/template.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file template.ts
+ * @input A page/block template doc object (without the `type` tag).
+ * @output Type-preserving `createPageTemplate`/`createBlockTemplate` helpers
+ *   plus the authored-template TypeScript surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * 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.
+ *
+ * These are tiny runtime identity helpers that inject the `type` discriminant.
+ * They do NOT validate — validation happens at the CLI load boundary, where
+ * integration template discovery runs the module's default export through the
+ * template envelope schema.
+ */
+/** 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;
+/**
+ * Author an Astryx page template doc. Stamp-only: returns the def with
+ * `type: 'page'` injected. Validation happens at the CLI load boundary.
+ */
+export declare function createPageTemplate<T extends AstryxPageTemplateInput>(def: T): T & {
+    type: 'page';
+};
+/**
+ * Author an Astryx block template doc. Stamp-only: returns the def with
+ * `type: 'block'` injected. Validation happens at the CLI load boundary.
+ */
+export declare function createBlockTemplate<T extends AstryxBlockTemplateInput>(def: T): T & {
+    type: 'block';
+};
+//# sourceMappingURL=template.d.ts.map

package/dist/authoring/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/authoring/template.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iCAAiC;IACjC,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,sEAAsE;AACtE,MAAM,MAAM,uBAAuB,GAAG,mBAAmB,CAAC;AAC1D,uEAAuE;AACvE,MAAM,MAAM,wBAAwB,GAAG,mBAAmB,CAAC;AAE3D,qCAAqC;AACrC,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC;AACtE,sCAAsC;AACtC,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,CAAC;AAExE,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,uBAAuB,EAClE,GAAG,EAAE,CAAC,GACL,CAAC,GAAG;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAEpB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,wBAAwB,EACpE,GAAG,EAAE,CAAC,GACL,CAAC,GAAG;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,CAErB"}

package/dist/authoring/template.js

@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file template.ts
+ * @input A page/block template doc object (without the `type` tag).
+ * @output Type-preserving `createPageTemplate`/`createBlockTemplate` helpers
+ *   plus the authored-template TypeScript surface.
+ * @position Integration-author authoring surface. See `./index.ts` for why
+ *   these authoring factories live in `@astryxdesign/core`.
+ *
+ * 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.
+ *
+ * These are tiny runtime identity helpers that inject the `type` discriminant.
+ * They do NOT validate — validation happens at the CLI load boundary, where
+ * integration template discovery runs the module's default export through the
+ * template envelope schema.
+ */
+
+/** Optional preview metadata for a template (used by docs surfaces). */
+
+/** Fields common to page and block template docs (without the `type` tag). */
+
+/** Input accepted by {@link createPageTemplate} (no `type` field). */
+
+/** Input accepted by {@link createBlockTemplate} (no `type` field). */
+
+/** A validated page template doc. */
+
+/** A validated block template doc. */
+
+/** A validated template doc (page or block). */
+
+/**
+ * Author an Astryx page template doc. Stamp-only: returns the def with
+ * `type: 'page'` injected. Validation happens at the CLI load boundary.
+ */
+export function createPageTemplate(def) {
+  return {
+    ...def,
+    type: 'page'
+  };
+}
+
+/**
+ * Author an Astryx block template doc. Stamp-only: returns the def with
+ * `type: 'block'` injected. Validation happens at the CLI load boundary.
+ */
+export function createBlockTemplate(def) {
+  return {
+    ...def,
+    type: 'block'
+  };
+}

package/dist/config.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file config.ts
+ * @input An app's Astryx config object.
+ * @output A type-preserving `createConfig` helper plus the `AstryxConfig`
+ *   surface authors write in `astryx.config.{ts,mjs,js}`.
+ * @position Consumer-facing authoring surface. Lives in `@astryxdesign/core`
+ *   (not the CLI) so an app's config file gets editor/type feedback without
+ *   taking a dependency on the CLI. The CLI re-exports this from
+ *   `@astryxdesign/cli/config` for back-compat.
+ *
+ * `createConfig` is an intentionally tiny runtime identity function: it returns
+ * its argument unchanged. Its value is the exported TypeScript surface.
+ * Validation is NOT performed here — it happens at the CLI load boundary.
+ */
+/**
+ * A command to run as part of a post-codemod hook. Returned by a hook's
+ * `buildCommand` and executed after codemods write files.
+ */
+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>;
+        };
+    };
+}
+/**
+ * Type-preserving helper for the Astryx config file. Returns its argument
+ * unchanged; the value is the exported TypeScript surface so config files get
+ * editor/type feedback. Validation happens at the CLI load boundary.
+ */
+export declare function createConfig<T extends AstryxConfig>(config: T): T;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,CAAC,GAAG,EAAE;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,EAAE,CAAC;KACjB,KACG,kBAAkB,GAClB,IAAI,GACJ,SAAS,GACT,OAAO,CAAC,kBAAkB,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACpD,CAAC;AAEF,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,KAAK,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;KACjC,CAAC;IACF;;;OAGG;IACH,YAAY,CAAC,EAAE;QACb,0DAA0D;QAC1D,GAAG,CAAC,EAAE;YACJ;;;eAGG;YACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;SAC3C,CAAC;KACH,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEjE"}

package/dist/config.js

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file config.ts
+ * @input An app's Astryx config object.
+ * @output A type-preserving `createConfig` helper plus the `AstryxConfig`
+ *   surface authors write in `astryx.config.{ts,mjs,js}`.
+ * @position Consumer-facing authoring surface. Lives in `@astryxdesign/core`
+ *   (not the CLI) so an app's config file gets editor/type feedback without
+ *   taking a dependency on the CLI. The CLI re-exports this from
+ *   `@astryxdesign/cli/config` for back-compat.
+ *
+ * `createConfig` is an intentionally tiny runtime identity function: it returns
+ * its argument unchanged. Its value is the exported TypeScript surface.
+ * Validation is NOT performed here — it happens at the CLI load boundary.
+ */
+
+/**
+ * A command to run as part of a post-codemod hook. Returned by a hook's
+ * `buildCommand` and executed after codemods write files.
+ */
+
+/**
+ * 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).
+ */
+
+/** A component XLE layout expressions can reference by name via `{hint}`. */
+
+/** User config exported from astryx.config.{ts,mjs,js}. */
+
+/**
+ * Type-preserving helper for the Astryx config file. Returns its argument
+ * unchanged; the value is the exported TypeScript surface so config files get
+ * editor/type feedback. Validation happens at the CLI load boundary.
+ */
+export function createConfig(config) {
+  return config;
+}