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

package/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';

package/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;
+}

package/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'};
+}

package/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();
+  });
+});

package/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;
+}