Skip to content

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

TypeScript

feat(core): host authoring factories in core (config + authoring subpaths) (#4058)

EJ Hammond896bdb1399fd
diff --git a/.changeset/authoring-factories-in-core.md b/.changeset/authoring-factories-in-core.md
new file mode 100644
index 0000000000..3b539af61a
--- /dev/null
+++ b/.changeset/authoring-factories-in-core.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[feat] Export the authoring factories from `@astryxdesign/core`: `createConfig` at `@astryxdesign/core/config` and `createIntegration`/`createPageTemplate`/`createBlockTemplate`/`createComponentDoc`/`createFunctionDoc`/`createDoc` at `@astryxdesign/core/authoring`. Authoring a config or integration no longer requires depending on the CLI. Existing `@astryxdesign/cli/*` imports keep working via re-export.
+
+@ejhammond
diff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjs
index c85cc6734e..558de67caf 100644
--- a/packages/cli/src/api/template.mjs
+++ b/packages/cli/src/api/template.mjs
@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import {createJiti} from 'jiti';
import {loadModuleWithSchema} from '../lib/module-loader.mjs';
-import {TemplateEnvelopeSchema} from '../template.mjs';
+import {TemplateEnvelopeSchema} from '../schemas/template-schema.mjs';
import {CLI_ROOT, discoverExternalPackages} from '../utils/paths.mjs';
import {
assertWithin,
diff --git a/packages/cli/src/config.mjs b/packages/cli/src/config.mjs
index 4e7074d5a3..dfbe01a502 100644
--- a/packages/cli/src/config.mjs
+++ b/packages/cli/src/config.mjs
@@ -1,18 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * Type-preserving helper for the Astryx config file.
- *
- * This is an intentionally tiny runtime identity function: it returns its
- * argument unchanged. Its value is the exported TypeScript surface from
- * `@astryxdesign/cli/config`, so config files get editor/type feedback without
- * coupling to CLI internals. Validation is NOT performed here — it happens at
- * the load boundary (see `loadModuleWithSchema` + `AstryxConfigSchema`).
- *
- * @template {import('./types/config').AstryxConfig} T
- * @param {T} config
- * @returns {T}
+ * Re-export of the config-authoring helper, which now lives in
+ * `@astryxdesign/core/config` so an app's config file gets type feedback
+ * without depending on the CLI. Kept here so existing
+ * `@astryxdesign/cli/config` imports continue to work unchanged.
*/
-export function createConfig(config) {
- return config;
-}
+export {createConfig} from '@astryxdesign/core/config';
diff --git a/packages/cli/src/doc.mjs b/packages/cli/src/doc.mjs
index 0207917a12..134f0ed828 100644
--- a/packages/cli/src/doc.mjs
+++ b/packages/cli/src/doc.mjs
@@ -1,271 +1,27 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Public doc-authoring API.
+ * @file Doc-authoring API (public `@astryxdesign/cli/doc`).
*
- * 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 (mirroring how
- * `createPageTemplate`/`createBlockTemplate` stamp `type`):
- *
- * - `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.
- *
- * Like `createConfig`/`createIntegration`/`createBlockTemplate`, these factories
- * do NOT validate. Validation happens at the LOAD boundary, where doc discovery
- * runs the loaded value through {@link ComponentDocSchema}. That schema handles
- * BOTH the new stamped formats and the legacy loose `export const docs = {...}`
- * shape, so existing docs keep loading unchanged (a later PR migrates them).
- */
-
-import {z} from 'zod';
-
-/**
- * A single documented prop. Mirrors `PropDoc` from
- * `@astryxdesign/core/docs-types`. Only `name`, `type`, and `description` are
- * required; everything else is optional. Extra fields (e.g. `slotElements`)
- * pass through so the schema does not have to track every evolution of the
- * rich playground/element surface.
- */
-const PropSchema = z
- .object({
- name: z.string().min(1, 'prop name is required'),
- type: z.string().min(1, 'prop type is required'),
- description: z.string(),
- default: z.string().optional(),
- required: z.boolean().optional(),
- })
- .passthrough();
-
-/** A single documented function/hook parameter (mirrors `HookParamDoc`). */
-const ParamSchema = z
- .object({
- name: z.string().min(1, 'param name is required'),
- type: z.string().min(1, 'param type is required'),
- description: z.string(),
- default: z.string().optional(),
- required: z.boolean().optional(),
- })
- .passthrough();
-
-/** A single documented function/hook return field (mirrors `HookReturnDoc`). */
-const ReturnSchema = z
- .object({
- name: z.string().min(1, 'return name is required'),
- type: z.string().min(1, 'return type is required'),
- description: z.string(),
- })
- .passthrough();
-
-/**
- * Fields shared by every doc kind. Deliberately permissive on the rich blobs
- * (usage/theming/playground) — those are large and still evolving, so they are
- * `z.unknown()` passthrough rather than enumerated.
- *
- * `group` vs `parent` are distinct concepts and intentionally separate fields:
- * - `group` is a FLAT sidebar bucket label. Many docs can share a group; 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; both map to the same concept.
- *
- * `relatedDocs` is a single flat curated cross-reference list. It replaces the
- * legacy split `relatedComponents` + `relatedHooks`; a downstream reader can
- * merge the legacy pair into it.
- */
-const BaseDocFields = {
- /** Name of the documented unit, without any prefix. Required. */
- name: z.string().min(1, 'name is required'),
- /** Human-readable display name for gallery/sidebar. */
- displayName: z.string().optional(),
- /** One-line/short description. */
- description: z.string().optional(),
- /** Usage documentation (description, best practices, anatomy, slotElements). */
- usage: z.unknown().optional(),
- /** Flat sidebar grouping label (not an inheritance key). */
- group: z.string().optional(),
- /** Overview-page functional category. */
- category: z.string().optional(),
- /** CLI fuzzy-search keywords. */
- keywords: z.array(z.string()).optional(),
- /** Directed inheritance/composition pointer to the doc this belongs to. */
- parent: z.string().optional(),
- /** Flat curated cross-reference list of related doc names. */
- relatedDocs: z.array(z.string()).optional(),
- /** Hide the whole doc from human-facing UI (stays importable/discoverable). */
- hidden: z.boolean().optional(),
- /** Exclude from the categorized overview page (kept in sidebar/CLI). */
- isHiddenFromOverview: z.boolean().optional(),
-};
-
-/**
- * New-format schema for a stamped component doc (`type: 'component'`). The
- * top-level component keys are enumerated, but nested blobs stay loose so real
- * docs are not rejected. `.passthrough()` keeps unknown top-level fields
- * (translations, element descriptors, ...) flowing through.
- */
-export const ComponentDocKindSchema = z
- .object({
- ...BaseDocFields,
- type: z.literal('component'),
- props: z.array(PropSchema),
- theming: z.unknown().optional(),
- playground: z.unknown().optional(),
- examples: z.array(z.unknown()).optional(),
- })
- .passthrough();
-
-/**
- * New-format schema for a stamped function doc (`type: 'function'`). Covers any
- * function, including hooks: an inputs (`params`) + outputs (`returns`) surface.
+ * The `createComponentDoc`/`createFunctionDoc`/`createDoc` authoring helpers now
+ * live in `@astryxdesign/core/authoring` and are re-exported here so existing
+ * `@astryxdesign/cli/doc` imports keep working. The Zod load-boundary schemas
+ * live in `./schemas/doc-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/`.
*/
-export const FunctionDocKindSchema = z
- .object({
- ...BaseDocFields,
- type: z.literal('function'),
- params: z.array(ParamSchema),
- returns: z.array(ReturnSchema),
- })
- .passthrough();
-/**
- * New-format schema for a stamped generic doc (`type: 'generic'`) — reference
- * and topic docs. Just the shared base plus the discriminant.
- */
-export const GenericDocKindSchema = z
- .object({
- ...BaseDocFields,
- type: z.literal('generic'),
- })
- .passthrough();
+export {
+ createComponentDoc,
+ createFunctionDoc,
+ createDoc,
+} from '@astryxdesign/core/authoring';
-/**
- * The stamped-doc contract: one of the three new per-kind schemas, discriminated
- * by the injected `type`. Used when a loaded doc carries a `type` field.
- */
-export const StampedDocSchema = z.discriminatedUnion('type', [
+export {
ComponentDocKindSchema,
FunctionDocKindSchema,
GenericDocKindSchema,
-]);
-
-// ── Legacy loose format (unchanged, kept for back-compat) ─────────────
-//
-// The pre-factory docs are authored as a loose, untyped object with no `type`
-// discriminant and validated by shape. Enumerated top-level fields observed
-// across the existing loose docs:
-// name, displayName, description, group, category, keywords,
-// isHiddenFromOverview, hidden, hiddenComponents, usage, props, components,
-// subComponentOf, playground, theming, examples, params, returns,
-// relatedComponents, relatedHooks, relatedDocs, parent, importPath.
-
-const LegacyBaseDocSchema = z.object({
- name: z.string().min(1, 'name is required'),
- displayName: z.string().optional(),
- description: z.string().optional(),
- group: z.string().optional(),
- category: z.string().optional(),
- keywords: z.array(z.string()).optional(),
- isHiddenFromOverview: z.boolean().optional(),
- hidden: z.boolean().optional(),
- hiddenComponents: z.array(z.string()).optional(),
- usage: z.unknown().optional(),
- playground: z.unknown().optional(),
- theming: z.unknown().optional(),
- examples: z.array(z.unknown()).optional(),
- showcase: z.unknown().optional(),
- // `parent` and legacy `subComponentOf` are synonyms; both accepted here so a
- // parent-based doc that omits a stamped `type` still validates.
- parent: z.string().optional(),
- relatedDocs: z.array(z.string()).optional(),
- relatedComponents: z.array(z.string()).optional(),
- relatedHooks: z.array(z.string()).optional(),
-});
-
-/** Legacy: directory exporting a single primary component (props inline). */
-const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({
- props: z.array(PropSchema),
-}).passthrough();
-
-/** Legacy: directory exporting multiple components (props on each entry). */
-const LegacyMultiComponentDocSchema = LegacyBaseDocSchema.extend({
- components: z.array(z.unknown()),
-}).passthrough();
-
-/** Legacy: a standalone hook doc — inputs (`params`) + outputs (`returns`). */
-const LegacyHookDocSchema = LegacyBaseDocSchema.extend({
- params: z.array(ParamSchema),
- returns: z.array(ReturnSchema),
-}).passthrough();
-
-/** Legacy: a sub-component doc parented via `subComponentOf`. */
-const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({
- subComponentOf: z.string().min(1, 'subComponentOf is required'),
- description: z.string(),
- props: z.array(PropSchema),
-}).passthrough();
-
-/**
- * The permissive legacy union. `subComponentOf` is listed first so a doc that
- * carries both `subComponentOf` and `props` is validated as a sub-component
- * (the more specific shape); hook (`params`/`returns`) before multi/single.
- */
-export const LegacyDocSchema = z.union([
- LegacySubComponentDocSchema,
- LegacyHookDocSchema,
- LegacyMultiComponentDocSchema,
- LegacySingleComponentDocSchema,
-]);
-
-/**
- * The LOAD-boundary contract for a doc. Handles BOTH formats:
- * - NEW: a stamped doc (`type: 'component' | 'function' | 'generic'`,
- * produced by the factories below) is validated against the matching
- * per-kind schema in {@link StampedDocSchema}.
- * - OLD: a loose, unstamped doc is validated against the permissive
- * {@link LegacyDocSchema} union (the three legacy shapes + standalone hook).
- *
- * Discovery validates the SHAPE, not "was it made by the factory". This PR does
- * NOT migrate real docs; a later PR does. Both formats normalize into the same
- * internal shape consumers already expect.
- */
-export const ComponentDocSchema = z.union([StampedDocSchema, LegacyDocSchema]);
-
-/**
- * Author a component doc. Stamp-only: returns the def with `type: 'component'`
- * injected. Validation happens at the load boundary.
- *
- * @template {import('./types/doc').AstryxComponentDocInput} T
- * @param {T} def
- * @returns {T & {type: 'component'}}
- */
-export function createComponentDoc(def) {
- return /** @type {T & {type: 'component'}} */ ({...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
- * load boundary.
- *
- * @template {import('./types/doc').AstryxFunctionDocInput} T
- * @param {T} def
- * @returns {T & {type: 'function'}}
- */
-export function createFunctionDoc(def) {
- return /** @type {T & {type: 'function'}} */ ({...def, type: 'function'});
-}
-
-/**
- * Author a generic reference/topic doc. Stamp-only: returns the def with
- * `type: 'generic'` injected. Validation happens at the load boundary.
- *
- * @template {import('./types/doc').AstryxGenericDocInput} T
- * @param {T} def
- * @returns {T & {type: 'generic'}}
- */
-export function createDoc(def) {
- return /** @type {T & {type: 'generic'}} */ ({...def, type: 'generic'});
-}
+ StampedDocSchema,
+ LegacyDocSchema,
+ ComponentDocSchema,
+} from './schemas/doc-schema.mjs';
diff --git a/packages/cli/src/integration.mjs b/packages/cli/src/integration.mjs
index a5761c6c99..a96ac2b009 100644
--- a/packages/cli/src/integration.mjs
+++ b/packages/cli/src/integration.mjs
@@ -1,19 +1,8 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * Type-preserving helper for an Astryx integration manifest.
- *
- * This is an intentionally tiny runtime identity function: it returns its
- * argument unchanged. Its value is the exported TypeScript surface from
- * `@astryxdesign/cli/integration`, so manifests get editor/type feedback
- * without coupling to CLI internals. Validation is NOT performed here — it
- * happens at the load boundary (see `loadModuleWithSchema` +
- * `AstryxIntegrationSchema`).
- *
- * @template {import('./types/integration').AstryxIntegration} T
- * @param {T} integration
- * @returns {T}
+ * Re-export of the integration-authoring helper, which now lives in
+ * `@astryxdesign/core/authoring`. Kept here so existing
+ * `@astryxdesign/cli/integration` imports continue to work unchanged.
*/
-export function createIntegration(integration) {
- return integration;
-}
+export {createIntegration} from '@astryxdesign/core/authoring';
diff --git a/packages/cli/src/lib/component-loader.mjs b/packages/cli/src/lib/component-loader.mjs
index 032a1d3f23..38b42eed8b 100644
--- a/packages/cli/src/lib/component-loader.mjs
+++ b/packages/cli/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 '../doc.mjs';
+import {ComponentDocSchema} from '../schemas/doc-schema.mjs';
/**
* Load a component doc through the shared load/validation boundary.
diff --git a/packages/cli/src/schemas/doc-schema.mjs b/packages/cli/src/schemas/doc-schema.mjs
new file mode 100644
index 0000000000..09dcc6bebd
--- /dev/null
+++ b/packages/cli/src/schemas/doc-schema.mjs
@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Doc load-boundary schemas.
+ *
+ * The Zod schemas doc discovery runs a loaded doc value through (see
+ * `loadComponentDoc`). {@link ComponentDocSchema} accepts BOTH the new stamped
+ * formats and the legacy loose `export const docs = {...}` shape, so existing
+ * docs keep loading unchanged. Kept free of any `@astryxdesign/core` import so
+ * the hot path that loads them (doc discovery, `astryx init`) does not require
+ * core's built `dist/`. The authoring factories live in
+ * `@astryxdesign/core/authoring` and are re-exported from `../doc.mjs` for the
+ * public `@astryxdesign/cli/doc` surface.
+ */
+
+import {z} from 'zod';
+
+/**
+ * A single documented prop. Mirrors `PropDoc` from
+ * `@astryxdesign/core/docs-types`. Only `name`, `type`, and `description` are
+ * required; everything else is optional. Extra fields (e.g. `slotElements`)
+ * pass through so the schema does not have to track every evolution of the
+ * rich playground/element surface.
+ */
+const PropSchema = z
+ .object({
+ name: z.string().min(1, 'prop name is required'),
+ type: z.string().min(1, 'prop type is required'),
+ description: z.string(),
+ default: z.string().optional(),
+ required: z.boolean().optional(),
+ })
+ .passthrough();
+
+/** A single documented function/hook parameter (mirrors `HookParamDoc`). */
+const ParamSchema = z
+ .object({
+ name: z.string().min(1, 'param name is required'),
+ type: z.string().min(1, 'param type is required'),
+ description: z.string(),
+ default: z.string().optional(),
+ required: z.boolean().optional(),
+ })
+ .passthrough();
+
+/** A single documented function/hook return field (mirrors `HookReturnDoc`). */
+const ReturnSchema = z
+ .object({
+ name: z.string().min(1, 'return name is required'),
+ type: z.string().min(1, 'return type is required'),
+ description: z.string(),
+ })
+ .passthrough();
+
+/**
+ * Fields shared by every doc kind. Deliberately permissive on the rich blobs
+ * (usage/theming/playground) — those are large and still evolving, so they are
+ * `z.unknown()` passthrough rather than enumerated.
+ *
+ * `group` vs `parent` are distinct concepts and intentionally separate fields:
+ * - `group` is a FLAT sidebar bucket label. Many docs can share a group; 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; both map to the same concept.
+ *
+ * `relatedDocs` is a single flat curated cross-reference list. It replaces the
+ * legacy split `relatedComponents` + `relatedHooks`; a downstream reader can
+ * merge the legacy pair into it.
+ */
+const BaseDocFields = {
+ /** Name of the documented unit, without any prefix. Required. */
+ name: z.string().min(1, 'name is required'),
+ /** Human-readable display name for gallery/sidebar. */
+ displayName: z.string().optional(),
+ /** One-line/short description. */
+ description: z.string().optional(),
+ /** Usage documentation (description, best practices, anatomy, slotElements). */
+ usage: z.unknown().optional(),
+ /** Flat sidebar grouping label (not an inheritance key). */
+ group: z.string().optional(),
+ /** Overview-page functional category. */
+ category: z.string().optional(),
+ /** CLI fuzzy-search keywords. */
+ keywords: z.array(z.string()).optional(),
+ /** Directed inheritance/composition pointer to the doc this belongs to. */
+ parent: z.string().optional(),
+ /** Flat curated cross-reference list of related doc names. */
+ relatedDocs: z.array(z.string()).optional(),
+ /** Hide the whole doc from human-facing UI (stays importable/discoverable). */
+ hidden: z.boolean().optional(),
+ /** Exclude from the categorized overview page (kept in sidebar/CLI). */
+ isHiddenFromOverview: z.boolean().optional(),
+};
+
+/**
+ * New-format schema for a stamped component doc (`type: 'component'`). The
+ * top-level component keys are enumerated, but nested blobs stay loose so real
+ * docs are not rejected. `.passthrough()` keeps unknown top-level fields
+ * (translations, element descriptors, ...) flowing through.
+ */
+export const ComponentDocKindSchema = z
+ .object({
+ ...BaseDocFields,
+ type: z.literal('component'),
+ props: z.array(PropSchema),
+ theming: z.unknown().optional(),
+ playground: z.unknown().optional(),
+ examples: z.array(z.unknown()).optional(),
+ })
+ .passthrough();
+
+/**
+ * New-format schema for a stamped function doc (`type: 'function'`). Covers any
+ * function, including hooks: an inputs (`params`) + outputs (`returns`) surface.
+ */
+export const FunctionDocKindSchema = z
+ .object({
+ ...BaseDocFields,
+ type: z.literal('function'),
+ params: z.array(ParamSchema),
+ returns: z.array(ReturnSchema),
+ })
+ .passthrough();
+
+/**
+ * New-format schema for a stamped generic doc (`type: 'generic'`) — reference
+ * and topic docs. Just the shared base plus the discriminant.
+ */
+export const GenericDocKindSchema = z
+ .object({
+ ...BaseDocFields,
+ type: z.literal('generic'),
+ })
+ .passthrough();
+
+/**
+ * The stamped-doc contract: one of the three new per-kind schemas, discriminated
+ * by the injected `type`. Used when a loaded doc carries a `type` field.
+ */
+export const StampedDocSchema = z.discriminatedUnion('type', [
+ ComponentDocKindSchema,
+ FunctionDocKindSchema,
+ GenericDocKindSchema,
+]);
+
+// ── Legacy loose format (unchanged, kept for back-compat) ─────────────
+//
+// The pre-factory docs are authored as a loose, untyped object with no `type`
+// discriminant and validated by shape. Enumerated top-level fields observed
+// across the existing loose docs:
+// name, displayName, description, group, category, keywords,
+// isHiddenFromOverview, hidden, hiddenComponents, usage, props, components,
+// subComponentOf, playground, theming, examples, params, returns,
+// relatedComponents, relatedHooks, relatedDocs, parent, importPath.
+
+const LegacyBaseDocSchema = z.object({
+ name: z.string().min(1, 'name is required'),
+ displayName: z.string().optional(),
+ description: z.string().optional(),
+ group: z.string().optional(),
+ category: z.string().optional(),
+ keywords: z.array(z.string()).optional(),
+ isHiddenFromOverview: z.boolean().optional(),
+ hidden: z.boolean().optional(),
+ hiddenComponents: z.array(z.string()).optional(),
+ usage: z.unknown().optional(),
+ playground: z.unknown().optional(),
+ theming: z.unknown().optional(),
+ examples: z.array(z.unknown()).optional(),
+ showcase: z.unknown().optional(),
+ // `parent` and legacy `subComponentOf` are synonyms; both accepted here so a
+ // parent-based doc that omits a stamped `type` still validates.
+ parent: z.string().optional(),
+ relatedDocs: z.array(z.string()).optional(),
+ relatedComponents: z.array(z.string()).optional(),
+ relatedHooks: z.array(z.string()).optional(),
+});
+
+/** Legacy: directory exporting a single primary component (props inline). */
+const LegacySingleComponentDocSchema = LegacyBaseDocSchema.extend({
+ props: z.array(PropSchema),
+}).passthrough();
+
+/** Legacy: directory exporting multiple components (props on each entry). */
+const LegacyMultiComponentDocSchema = LegacyBaseDocSchema.extend({
+ components: z.array(z.unknown()),
+}).passthrough();
+
+/** Legacy: a standalone hook doc — inputs (`params`) + outputs (`returns`). */
+const LegacyHookDocSchema = LegacyBaseDocSchema.extend({
+ params: z.array(ParamSchema),
+ returns: z.array(ReturnSchema),
+}).passthrough();
+
+/** Legacy: a sub-component doc parented via `subComponentOf`. */
+const LegacySubComponentDocSchema = LegacyBaseDocSchema.extend({
+ subComponentOf: z.string().min(1, 'subComponentOf is required'),
+ description: z.string(),
+ props: z.array(PropSchema),
+}).passthrough();
+
+/**
+ * The permissive legacy union. `subComponentOf` is listed first so a doc that
+ * carries both `subComponentOf` and `props` is validated as a sub-component
+ * (the more specific shape); hook (`params`/`returns`) before multi/single.
+ */
+export const LegacyDocSchema = z.union([
+ LegacySubComponentDocSchema,
+ LegacyHookDocSchema,
+ LegacyMultiComponentDocSchema,
+ LegacySingleComponentDocSchema,
+]);
+
+/**
+ * The LOAD-boundary contract for a doc. Handles BOTH formats:
+ * - NEW: a stamped doc (`type: 'component' | 'function' | 'generic'`,
+ * produced by the factories) is validated against the matching per-kind
+ * schema in {@link StampedDocSchema}.
+ * - OLD: a loose, unstamped doc is validated against the permissive
+ * {@link LegacyDocSchema} union (the three legacy shapes + standalone hook).
+ *
+ * Discovery validates the SHAPE, not "was it made by the factory". Both formats
+ * normalize into the same internal shape consumers already expect.
+ */
+export const ComponentDocSchema = z.union([StampedDocSchema, LegacyDocSchema]);
diff --git a/packages/cli/src/schemas/template-schema.mjs b/packages/cli/src/schemas/template-schema.mjs
new file mode 100644
index 0000000000..b0910326d1
--- /dev/null
+++ b/packages/cli/src/schemas/template-schema.mjs
@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Template load-boundary schemas.
+ *
+ * The Zod schemas that integration template discovery runs a module's default
+ * export through (see `loadModuleWithSchema`). Kept free of any
+ * `@astryxdesign/core` import so the hot path that loads them (template
+ * discovery, `astryx init`) does not require core's built `dist/`. The
+ * authoring factories live in `@astryxdesign/core/authoring` and are re-exported
+ * from `../template.mjs` for the public `@astryxdesign/cli/template` surface.
+ */
+
+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']),
+});
diff --git a/packages/cli/src/template.mjs b/packages/cli/src/template.mjs
index f9d726369a..e8d9c40aa1 100644
--- a/packages/cli/src/template.mjs
+++ b/packages/cli/src/template.mjs
@@ -1,73 +1,15 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Static template authoring API.
+ * @file Static template authoring API (public `@astryxdesign/cli/template`).
*
- * 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`).
+ * 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/`.
*/
-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'});
-}
+export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
+export {BaseTemplateSchema, TemplateEnvelopeSchema} from './schemas/template-schema.mjs';
diff --git a/packages/cli/src/types/config.d.ts b/packages/cli/src/types/config.d.ts
index 9618248582..687a0601fc 100644
--- a/packages/cli/src/types/config.d.ts
+++ b/packages/cli/src/types/config.d.ts
@@ -1,70 +1,15 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * 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.
+ * 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.
*/
-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;
+export type {
+ PostCodemodCommand,
+ PostCodemodHook,
+ XleComponent,
+ AstryxConfig,
+} from '@astryxdesign/core/config';
+
+export {createConfig} from '@astryxdesign/core/config';
diff --git a/packages/cli/src/types/doc.d.ts b/packages/cli/src/types/doc.d.ts
index bcd3dbf949..9be9c5cf98 100644
--- a/packages/cli/src/types/doc.d.ts
+++ b/packages/cli/src/types/doc.d.ts
@@ -1,139 +1,23 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * 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`.
+ * 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`).
*/
-
-/**
- * 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'};
+export type {
+ AstryxBaseDocInput,
+ AstryxPropInput,
+ AstryxParamInput,
+ AstryxReturnInput,
+ AstryxComponentDocInput,
+ AstryxFunctionDocInput,
+ AstryxGenericDocInput,
+ AstryxComponentDoc,
+} from '@astryxdesign/core/authoring';
+
+export {
+ createComponentDoc,
+ createFunctionDoc,
+ createDoc,
+} from '@astryxdesign/core/authoring';
diff --git a/packages/cli/src/types/integration.d.ts b/packages/cli/src/types/integration.d.ts
index ec1d61b60c..4545cce18d 100644
--- a/packages/cli/src/types/integration.d.ts
+++ b/packages/cli/src/types/integration.d.ts
@@ -1,21 +1,14 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * 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.
+ * 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.
*/
-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;
-}
+export type {AstryxIntegration} from '@astryxdesign/core/authoring';
+export {createIntegration} from '@astryxdesign/core/authoring';
/** An issue surfaced by an integration. */
export interface AstryxIntegrationIssue {
@@ -23,7 +16,3 @@ export interface AstryxIntegrationIssue {
severity: 'warning' | 'error';
message: string;
}
-
-export declare function createIntegration<T extends AstryxIntegration>(
- integration: T,
-): T;
diff --git a/packages/cli/src/types/template-api.d.ts b/packages/cli/src/types/template-api.d.ts
index 0cb83d1a4d..85264febcf 100644
--- a/packages/cli/src/types/template-api.d.ts
+++ b/packages/cli/src/types/template-api.d.ts
@@ -1,54 +1,18 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * 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.
+ * The template-authoring surface moved to `@astryxdesign/core/authoring`.
+ * Re-exported here so existing `@astryxdesign/cli/template` type imports keep
+ * resolving.
*/
-
-/** 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'};
+export type {
+ AstryxTemplatePreview,
+ AstryxTemplateInput,
+ AstryxPageTemplateInput,
+ AstryxBlockTemplateInput,
+ AstryxPageTemplate,
+ AstryxBlockTemplate,
+ AstryxTemplate,
+} from '@astryxdesign/core/authoring';
+
+export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
diff --git a/packages/cli/tsconfig.json-api.json b/packages/cli/tsconfig.json-api.json
index dad96e200a..6e221c7425 100644
--- a/packages/cli/tsconfig.json-api.json
+++ b/packages/cli/tsconfig.json-api.json
@@ -5,7 +5,8 @@
"allowJs": true,
"checkJs": true,
"noEmit": true,
- "types": ["node"]
+ "types": ["node"],
+ "customConditions": ["source"]
},
"include": [
"src/types/**/*.d.ts",
diff --git a/packages/core/package.json b/packages/core/package.json
index d39335a707..0ecd50b0a6 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -59,6 +59,16 @@
"types": "./dist/naming.d.ts",
"default": "./dist/naming.js"
},
+ "./config": {
+ "source": "./src/config.ts",
+ "types": "./dist/config.d.ts",
+ "default": "./dist/config.js"
+ },
+ "./authoring": {
+ "source": "./src/authoring/index.ts",
+ "types": "./dist/authoring/index.d.ts",
+ "default": "./dist/authoring/index.js"
+ },
"./theme/tokens": {
"source": "./src/theme/tokens.ts",
"types": "./dist/theme/tokens.d.ts",
diff --git a/packages/core/src/authoring/doc.ts b/packages/core/src/authoring/doc.ts
new file mode 100644
index 0000000000..ef217628cc
--- /dev/null
+++ b/packages/core/src/authoring/doc.ts
@@ -0,0 +1,166 @@
+// 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`.
+ */
+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 function createComponentDoc<T extends AstryxComponentDocInput>(
+ def: T,
+): T & {type: 'component'} {
+ 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<T extends AstryxFunctionDocInput>(
+ def: T,
+): T & {type: 'function'} {
+ 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<T extends AstryxGenericDocInput>(
+ def: T,
+): T & {type: 'generic'} {
+ return {...def, type: 'generic'};
+}
diff --git a/packages/core/src/authoring/index.test.ts b/packages/core/src/authoring/index.test.ts
new file mode 100644
index 0000000000..201c42f01c
--- /dev/null
+++ b/packages/core/src/authoring/index.test.ts
@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+ createIntegration,
+ createPageTemplate,
+ createBlockTemplate,
+ createComponentDoc,
+ createFunctionDoc,
+ createDoc,
+} from './index';
+
+describe('authoring factories', () => {
+ it('createIntegration returns its argument unchanged', () => {
+ const input = {components: './c', templates: './t'};
+ expect(createIntegration(input)).toBe(input);
+ });
+
+ it('createPageTemplate / createBlockTemplate stamp the template type', () => {
+ expect(createPageTemplate({name: 'P', description: 'd'}).type).toBe('page');
+ expect(createBlockTemplate({name: 'B', description: 'd'}).type).toBe(
+ 'block',
+ );
+ });
+
+ it('createPageTemplate preserves authored fields', () => {
+ const t = createPageTemplate({name: 'P', description: 'd', category: 'x'});
+ expect(t).toMatchObject({
+ name: 'P',
+ description: 'd',
+ category: 'x',
+ type: 'page',
+ });
+ });
+
+ it('doc factories stamp the doc kind', () => {
+ expect(createComponentDoc({name: 'Button', props: []}).type).toBe(
+ 'component',
+ );
+ expect(
+ createFunctionDoc({name: 'useX', params: [], returns: []}).type,
+ ).toBe('function');
+ expect(createDoc({name: 'Topic'}).type).toBe('generic');
+ });
+
+ it('doc factories do not mutate the input object', () => {
+ const input = {name: 'Button', props: []};
+ const out = createComponentDoc(input);
+ expect(out).not.toBe(input);
+ expect(input).not.toHaveProperty('type');
+ });
+});
diff --git a/packages/core/src/authoring/index.ts b/packages/core/src/authoring/index.ts
new file mode 100644
index 0000000000..04941121f5
--- /dev/null
+++ b/packages/core/src/authoring/index.ts
@@ -0,0 +1,50 @@
+// 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';
+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';
diff --git a/packages/core/src/authoring/integration.ts b/packages/core/src/authoring/integration.ts
new file mode 100644
index 0000000000..45b9ce5acc
--- /dev/null
+++ b/packages/core/src/authoring/integration.ts
@@ -0,0 +1,42 @@
+// 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.
+ */
+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 function createIntegration<T extends AstryxIntegration>(
+ integration: T,
+): T {
+ return integration;
+}
diff --git a/packages/core/src/authoring/template.ts b/packages/core/src/authoring/template.ts
new file mode 100644
index 0000000000..53ec8594be
--- /dev/null
+++ b/packages/core/src/authoring/template.ts
@@ -0,0 +1,74 @@
+// 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). */
+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 function createPageTemplate<T extends AstryxPageTemplateInput>(
+ def: T,
+): T & {type: 'page'} {
+ 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<T extends AstryxBlockTemplateInput>(
+ def: T,
+): T & {type: 'block'} {
+ return {...def, type: 'block'};
+}
diff --git a/packages/core/src/config.test.ts b/packages/core/src/config.test.ts
new file mode 100644
index 0000000000..c87b3e58f4
--- /dev/null
+++ b/packages/core/src/config.test.ts
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {createConfig} from './config';
+
+describe('createConfig', () => {
+ it('returns its argument unchanged (identity)', () => {
+ const input = {integrations: ['@acme/astryx'], issuesUrl: 'https://x'};
+ expect(createConfig(input)).toBe(input);
+ });
+
+ it('does not stamp a discriminant', () => {
+ const cfg = createConfig({integrations: []}) as Record<string, unknown>;
+ expect(cfg.type).toBeUndefined();
+ });
+});
diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
new file mode 100644
index 0000000000..6b8ccec2d1
--- /dev/null
+++ b/packages/core/src/config.ts
@@ -0,0 +1,92 @@
+// 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.
+ */
+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 function createConfig<T extends AstryxConfig>(config: T): T {
+ return config;
+}
diff --git a/scripts/sync-exports.js b/scripts/sync-exports.js
index 808ddd2aae..408d4b627e 100644
--- a/scripts/sync-exports.js
+++ b/scripts/sync-exports.js
@@ -68,6 +68,16 @@ const STATIC_EXPORTS = {
types: './dist/naming.d.ts',
default: './dist/naming.js',
},
+ './config': {
+ source: './src/config.ts',
+ types: './dist/config.d.ts',
+ default: './dist/config.js',
+ },
+ './authoring': {
+ source: './src/authoring/index.ts',
+ types: './dist/authoring/index.d.ts',
+ default: './dist/authoring/index.js',
+ },
'./theme/tokens': {
source: './src/theme/tokens.ts',
types: './dist/theme/tokens.d.ts',