@formspec/build 0.1.0-alpha.14 → 0.1.0-alpha.16

package/dist/build.d.ts

@@ -23,8 +23,14 @@
  * @packageDocumentation
  */
 
+import type { CustomAnnotationRegistration } from '@formspec/core';
+import type { CustomConstraintRegistration } from '@formspec/core';
+import type { CustomTypeRegistration } from '@formspec/core';
+import type { ExtensionDefinition } from '@formspec/core';
 import type { FormElement } from '@formspec/core';
+import type { FormIR } from '@formspec/core';
 import type { FormSpec } from '@formspec/core';
+import type { JsonValue } from '@formspec/core';
 import { z } from 'zod';
 
 /**
@@ -54,7 +60,41 @@ import { z } from 'zod';
  * @param form - The FormSpec to build schemas from
  * @returns Object containing both jsonSchema and uiSchema
  */
-export declare function buildFormSchemas<E extends readonly FormElement[]>(form: FormSpec<E>): BuildResult;
+export declare function buildFormSchemas<E extends readonly FormElement[]>(form: FormSpec<E>, options?: BuildFormSchemasOptions): BuildResult;
+
+/**
+ * Options for building schemas from a FormSpec.
+ *
+ * Currently identical to `GenerateJsonSchemaOptions`. Defined separately so the
+ * Chain DSL surface can grow independently in the future if needed.
+ */
+export declare type BuildFormSchemasOptions = GenerateJsonSchemaOptions;
+
+/**
+ * Builds JSON Schema and UI Schema from a TSDoc-derived model with ChainDSL
+ * field overlays.
+ *
+ * Overlays are matched by field name. The static model wins for structure,
+ * ordering, and constraints; ChainDSL overlays may contribute dynamic runtime
+ * field metadata such as dynamic enum or dynamic schema keywords, and may fill
+ * in missing annotations.
+ */
+export declare function buildMixedAuthoringSchemas(options: BuildMixedAuthoringSchemasOptions): MixedAuthoringSchemas;
+
+/**
+ * Options for generating mixed-authoring schemas.
+ *
+ * The `typeName` can resolve to a class, interface, or object type alias, just
+ * like `generateSchemas()`.
+ */
+export declare interface BuildMixedAuthoringSchemasOptions extends GenerateJsonSchemaFromIROptions {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the class, interface, or type alias to analyze. */
+    readonly typeName: string;
+    /** ChainDSL overlays to apply to the static model. Groups and conditionals are flattened by field name. */
+    readonly overlays: FormSpec<readonly FormElement[]>;
+}
 
 /**
  * Result of building form schemas.
@@ -204,10 +244,56 @@ export declare const controlSchema: z.ZodObject<{
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.ZodTypeAny, "passthrough">>;
 
+/**
+ * Creates an extension registry from a list of extension definitions.
+ *
+ * The registry indexes all types, constraints, and annotations by their
+ * fully-qualified IDs (`<extensionId>/<name>`) for O(1) lookup during
+ * generation and validation.
+ *
+ * @param extensions - The extension definitions to register.
+ * @returns An {@link ExtensionRegistry} instance.
+ * @throws If duplicate type/constraint/annotation IDs are detected across extensions.
+ */
+export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): ExtensionRegistry;
+
 /** JSON Schema with FormSpec extension properties for arbitrary x-formspec-* keys. */
 export declare type ExtendedJSONSchema7 = JSONSchema7 & FormSpecSchemaExtensions;
 
-/** Extension properties for custom FormSpec decorators. */
+/**
+ * A registry of extensions that provides lookup by fully-qualified ID.
+ *
+ * Type IDs follow the format: `<extensionId>/<typeName>`
+ * Constraint IDs follow the format: `<extensionId>/<constraintName>`
+ * Annotation IDs follow the format: `<extensionId>/<annotationName>`
+ */
+export declare interface ExtensionRegistry {
+    /** The extensions registered in this registry (in registration order). */
+    readonly extensions: readonly ExtensionDefinition[];
+    /**
+     * Look up a custom type registration by its fully-qualified type ID.
+     *
+     * @param typeId - The fully-qualified type ID (e.g., "x-stripe/monetary/Decimal").
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    findType(typeId: string): CustomTypeRegistration | undefined;
+    /**
+     * Look up a custom constraint registration by its fully-qualified constraint ID.
+     *
+     * @param constraintId - The fully-qualified constraint ID.
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    findConstraint(constraintId: string): CustomConstraintRegistration | undefined;
+    /**
+     * Look up a custom annotation registration by its fully-qualified annotation ID.
+     *
+     * @param annotationId - The fully-qualified annotation ID.
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    findAnnotation(annotationId: string): CustomAnnotationRegistration | undefined;
+}
+
+/** Extension properties for custom FormSpec constraint tags. */
 export declare type FormSpecSchemaExtensions = Record<`x-formspec-${string}`, unknown>;
 
 /**
@@ -258,7 +344,74 @@ export declare interface GenerateFromClassResult {
  * @param form - The FormSpec to convert
  * @returns A JSON Schema 2020-12 object
  */
-export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>): JsonSchema2020;
+export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>, options?: GenerateJsonSchemaOptions): JsonSchema2020;
+
+/**
+ * Generates a JSON Schema 2020-12 object from a canonical FormIR.
+ *
+ * Groups and conditionals are flattened — they influence UI layout but do not
+ * affect the data schema. All fields appear at the level they would occupy in
+ * the output data.
+ *
+ * Named types in the `typeRegistry` are emitted as `$defs` entries and
+ * referenced via `$ref` (per PP7 — high-fidelity output).
+ *
+ * @example
+ * ```typescript
+ * import { canonicalizeDSL } from "./canonicalize/index.js";
+ * import { generateJsonSchemaFromIR } from "./json-schema/ir-generator.js";
+ * import { formspec, field } from "@formspec/dsl";
+ *
+ * const form = formspec(
+ *   field.text("name", { label: "Name", required: true }),
+ *   field.number("age", { min: 0 }),
+ * );
+ * const ir = canonicalizeDSL(form);
+ * const schema = generateJsonSchemaFromIR(ir);
+ * // {
+ * //   $schema: "https://json-schema.org/draft/2020-12/schema",
+ * //   type: "object",
+ * //   properties: {
+ * //     name: { type: "string", title: "Name" },
+ * //     age:  { type: "number", minimum: 0 }
+ * //   },
+ * //   required: ["name"]
+ * // }
+ * ```
+ *
+ * Advanced API — most consumers should use `generateJsonSchema()` or
+ * `buildFormSchemas()`, which canonicalize form definitions automatically.
+ * Callers of this function are responsible for providing pre-canonicalized IR.
+ *
+ * @param ir - The canonical FormIR produced by a canonicalizer
+ * @returns A plain JSON-serializable JSON Schema 2020-12 object
+ */
+export declare function generateJsonSchemaFromIR(ir: FormIR, options?: GenerateJsonSchemaFromIROptions): JsonSchema2020;
+
+/**
+ * Options for generating JSON Schema from a canonical FormIR.
+ */
+export declare interface GenerateJsonSchemaFromIROptions {
+    /**
+     * Registry used to resolve custom types, constraints, and annotations.
+     *
+     * JSON Schema generation throws when custom IR nodes are present without a
+     * matching registration in this registry.
+     */
+    readonly extensionRegistry?: ExtensionRegistry | undefined;
+    /**
+     * Vendor prefix passed to extension `toJsonSchema` hooks.
+     * @defaultValue "x-formspec"
+     */
+    readonly vendorPrefix?: string | undefined;
+}
+
+/**
+ * Options for generating JSON Schema from a Chain DSL form.
+ *
+ * These options are forwarded to the IR-based JSON Schema generator.
+ */
+export declare type GenerateJsonSchemaOptions = GenerateJsonSchemaFromIROptions;
 
 /**
  * Generates JSON Schema and UI Schema from a named TypeScript
@@ -410,9 +563,9 @@ export declare interface JsonSchema2020 {
     properties?: Record<string, JsonSchema2020>;
     required?: string[];
     items?: JsonSchema2020;
-    additionalProperties?: boolean;
+    additionalProperties?: boolean | JsonSchema2020;
     enum?: readonly (string | number)[];
-    const?: string | number | boolean | null;
+    const?: JsonValue;
     allOf?: readonly JsonSchema2020[];
     oneOf?: readonly JsonSchema2020[];
     anyOf?: readonly JsonSchema2020[];
@@ -427,6 +580,7 @@ export declare interface JsonSchema2020 {
     maxItems?: number;
     pattern?: string;
     uniqueItems?: boolean;
+    format?: string;
     title?: string;
     description?: string;
     default?: unknown;
@@ -600,6 +754,16 @@ export declare const labelElementSchema: z.ZodObject<{
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.ZodTypeAny, "passthrough">>;
 
+/**
+ * Result of generating schemas from a mixed-authoring composition.
+ */
+export declare interface MixedAuthoringSchemas {
+    /** JSON Schema 2020-12 for validation. */
+    readonly jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering. */
+    readonly uiSchema: UISchema;
+}
+
 /**
  * Rule for conditional element visibility/enablement.
  */
@@ -784,7 +948,7 @@ export declare function writeSchemas<E extends readonly FormElement[]>(form: For
 /**
  * Options for writing schemas to disk.
  */
-export declare interface WriteSchemasOptions {
+export declare interface WriteSchemasOptions extends GenerateJsonSchemaFromIROptions {
     /** Output directory for the schema files */
     readonly outDir: string;
     /** Base name for the output files (without extension). Defaults to "schema" */

package/dist/canonicalize/tsdoc-canonicalizer.d.ts

@@ -1,7 +1,7 @@
 /**
  * TSDoc canonicalizer — assembles an {@link IRClassAnalysis} into a canonical
  * {@link FormIR}, applying layout metadata from `@Group` and `@ShowWhen`
- * decorators.
+ * TSDoc tags.
  *
  * The analysis functions in `class-analyzer.ts` produce `FieldNode[]`,
  * `fieldLayouts`, and `typeRegistry` directly. This canonicalizer uses
@@ -22,8 +22,8 @@ export interface TSDocSource {
  * `analyzeInterfaceToIR`, or `analyzeTypeAliasToIR`) into a canonical
  * {@link FormIR}.
  *
- * Fields with `@Group` decorators are grouped into `GroupLayoutNode` elements.
- * Fields with `@ShowWhen` decorators are wrapped in `ConditionalLayoutNode` elements.
+ * Fields with `@Group` TSDoc tags are grouped into `GroupLayoutNode` elements.
+ * Fields with `@ShowWhen` TSDoc tags are wrapped in `ConditionalLayoutNode` elements.
  * When both are present, the conditional wraps the field inside the group.
  *
  * @param analysis - IR analysis result (fields are already FieldNode[])

package/dist/canonicalize/tsdoc-canonicalizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tsdoc-canonicalizer.d.ts","sourceRoot":"","sources":["../../src/canonicalize/tsdoc-canonicalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,MAAM,EAMP,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,+BAA+B,CAAC;AAE1F;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAmBzF"}
+{"version":3,"file":"tsdoc-canonicalizer.d.ts","sourceRoot":"","sources":["../../src/canonicalize/tsdoc-canonicalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,MAAM,EAMP,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,+BAA+B,CAAC;AAE1F;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAqBzF"}