@formspec/build 0.1.0-alpha.24 → 0.1.0-alpha.27

package/dist/build-beta.d.ts

@@ -27,9 +27,7 @@ import { AnyField } from '@formspec/core';
 import { ArrayField } from '@formspec/core';
 import { BooleanField } from '@formspec/core';
 import { BuiltinConstraintBroadeningRegistration } from '@formspec/core';
-import { BuiltinConstraintName } from '@formspec/core';
 import { Conditional } from '@formspec/core';
-import { ConstraintSemanticRole } from '@formspec/core';
 import { ConstraintTagRegistration } from '@formspec/core';
 import { CustomAnnotationRegistration } from '@formspec/core';
 import { CustomConstraintRegistration } from '@formspec/core';
@@ -38,10 +36,7 @@ import { DynamicEnumField } from '@formspec/core';
 import { DynamicSchemaField } from '@formspec/core';
 import { EnumOption } from '@formspec/core';
 import { EnumOptionValue } from '@formspec/core';
-import { ExtensionApplicableType } from '@formspec/core';
 import { ExtensionDefinition } from '@formspec/core';
-import { ExtensionPayloadValue } from '@formspec/core';
-import { ExtensionTypeKind } from '@formspec/core';
 import { FormElement } from '@formspec/core';
 import { FormSpec } from '@formspec/core';
 import { Group } from '@formspec/core';
@@ -49,7 +44,8 @@ import { NumberField } from '@formspec/core';
 import { ObjectField } from '@formspec/core';
 import { StaticEnumField } from '@formspec/core';
 import { TextField } from '@formspec/core';
-import { VocabularyKeywordRegistration } from '@formspec/core';
+import * as ts from 'typescript';
+import { z } from 'zod';
 
 export { AnyField }
 
@@ -142,19 +138,23 @@ export declare interface BuildResult {
 
 export { BuiltinConstraintBroadeningRegistration }
 
-export { BuiltinConstraintName }
-
 /**
  * A Categorization element (tab-based layout).
  *
  * @public
  */
 export declare interface Categorization {
+    /** Discriminator identifying a categorization layout. */
     readonly type: "Categorization";
+    /** Categories rendered as tabs or steps. */
     readonly elements: Category[];
+    /** Optional label for the overall categorization container. */
     readonly label?: string | undefined;
+    /** Optional rule controlling visibility or enablement. */
     readonly rule?: Rule | undefined;
+    /** Renderer-specific categorization options. */
     readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
     readonly [k: string]: unknown;
 }
 
@@ -164,18 +164,22 @@ export declare interface Categorization {
  * @public
  */
 export declare interface Category {
+    /** Discriminator identifying a category inside a categorization layout. */
     readonly type: "Category";
+    /** Category label shown in tabs or step navigation. */
     readonly label: string;
+    /** Child elements rendered inside the category. */
     readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
     readonly rule?: Rule | undefined;
+    /** Renderer-specific category options. */
     readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
     readonly [k: string]: unknown;
 }
 
 export { Conditional }
 
-export { ConstraintSemanticRole }
-
 export { ConstraintTagRegistration }
 
 /**
@@ -184,11 +188,17 @@ export { ConstraintTagRegistration }
  * @public
  */
 export declare interface ControlElement {
+    /** Discriminator identifying a JSON Forms control element. */
     readonly type: "Control";
+    /** JSON Pointer scope that this control binds to. */
     readonly scope: string;
+    /** Optional label override, or `false` to suppress the label. */
     readonly label?: string | false | undefined;
+    /** Optional rule controlling visibility or enablement. */
     readonly rule?: Rule | undefined;
+    /** Renderer-specific control options. */
     readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
     readonly [k: string]: unknown;
 }
 
@@ -224,16 +234,12 @@ export { EnumOptionValue }
 /**
  * JSON Schema with FormSpec extension properties for arbitrary `x-formspec-*` keys.
  *
- * @beta
+ * @public
  */
 export declare type ExtendedJSONSchema7 = JSONSchema7 & FormSpecSchemaExtensions;
 
-export { ExtensionApplicableType }
-
 export { ExtensionDefinition }
 
-export { ExtensionPayloadValue }
-
 /**
  * A registry of extensions that provides lookup by fully-qualified ID.
  *
@@ -293,8 +299,6 @@ export declare interface ExtensionRegistry {
     findAnnotation(annotationId: string): CustomAnnotationRegistration | undefined;
 }
 
-export { ExtensionTypeKind }
-
 export { FormElement }
 
 export { FormSpec }
@@ -302,7 +306,7 @@ export { FormSpec }
 /**
  * Extension properties for custom FormSpec constraint tags.
  *
- * @beta
+ * @public
  */
 export declare type FormSpecSchemaExtensions = Record<`x-formspec-${string}`, unknown>;
 
@@ -421,6 +425,34 @@ export declare function generateSchemas(options: GenerateSchemasOptions): Genera
  */
 export declare function generateSchemasFromClass(options: GenerateFromClassOptions): GenerateFromClassResult;
 
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program supplied by the caller.
+ *
+ * This low-level entry point lets downstream tooling reuse a host-owned
+ * `Program` for both FormSpec extraction and other TypeScript analysis.
+ *
+ * @param options - Host program, file path, type name, and optional schema generation options
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions): GenerateFromClassResult;
+
+/**
+ * Options for generating schemas from a named type inside an existing TypeScript program.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromProgramOptions extends StaticSchemaGenerationOptions {
+    /** Existing TypeScript program supplied by the caller. */
+    readonly program: ts.Program;
+    /** Path to the TypeScript source file */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze */
+    readonly typeName: string;
+}
+
 /**
  * Options for generating schemas from a named type (class, interface, or type alias).
  *
@@ -489,11 +521,17 @@ export { Group }
  * @public
  */
 export declare interface GroupLayout {
+    /** Discriminator identifying a labeled group container. */
     readonly type: "Group";
+    /** Group label shown by compatible renderers. */
     readonly label: string;
+    /** Child elements rendered inside the group. */
     readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
     readonly rule?: Rule | undefined;
+    /** Renderer-specific group options. */
     readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
     readonly [k: string]: unknown;
 }
 
@@ -503,10 +541,15 @@ export declare interface GroupLayout {
  * @public
  */
 export declare interface HorizontalLayout {
+    /** Discriminator identifying a horizontal layout container. */
     readonly type: "HorizontalLayout";
+    /** Child elements rendered side by side. */
     readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
     readonly rule?: Rule | undefined;
+    /** Renderer-specific layout options. */
     readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
     readonly [k: string]: unknown;
 }
 
@@ -519,74 +562,135 @@ export declare interface HorizontalLayout {
  * @public
  */
 export declare interface JsonSchema2020 {
+    /** Declared JSON Schema dialect URI for the document root. */
     $schema?: string;
+    /** Reference to another schema location. */
     $ref?: string;
+    /** Named reusable schema definitions keyed by definition name. */
     $defs?: Record<string, JsonSchema2020>;
+    /** JSON Schema type keyword for the current node. */
     type?: string;
+    /** Object properties keyed by property name. */
     properties?: Record<string, JsonSchema2020>;
+    /** Property names that must be present on object values. */
     required?: string[];
+    /** Item schema applied to array elements. */
     items?: JsonSchema2020;
+    /** Whether, or how, additional object properties are allowed. */
     additionalProperties?: boolean | JsonSchema2020;
+    /** Closed set of allowed scalar values. */
     enum?: readonly (string | number)[];
+    /** Literal value the instance must equal. */
     const?: unknown;
+    /** Schemas that must all validate successfully. */
     allOf?: readonly JsonSchema2020[];
+    /** Schemas of which exactly one should validate successfully. */
     oneOf?: readonly JsonSchema2020[];
+    /** Schemas of which at least one may validate successfully. */
     anyOf?: readonly JsonSchema2020[];
+    /** Inclusive numeric lower bound. */
     minimum?: number;
+    /** Inclusive numeric upper bound. */
     maximum?: number;
+    /** Exclusive numeric lower bound. */
     exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound. */
     exclusiveMaximum?: number;
+    /** Required numeric step interval. */
     multipleOf?: number;
+    /** Inclusive minimum string length. */
     minLength?: number;
+    /** Inclusive maximum string length. */
     maxLength?: number;
+    /** Inclusive minimum array length. */
     minItems?: number;
+    /** Inclusive maximum array length. */
     maxItems?: number;
+    /** Regular expression pattern applied to string values. */
     pattern?: string;
+    /** Whether array elements must be unique. */
     uniqueItems?: boolean;
+    /** Format hint for downstream validators and tooling. */
     format?: string;
+    /** Human-readable title for the schema node. */
     title?: string;
+    /** Human-readable description for the schema node. */
     description?: string;
+    /** Default value suggested for the schema node. */
     default?: unknown;
+    /** Whether the schema node is deprecated. */
     deprecated?: boolean;
+    /** Additional vendor-prefixed extension keywords. */
     [key: `x-${string}`]: unknown;
 }
 
 /**
  * A JSON Schema definition (legacy subset used by Zod validator and types.ts).
  *
- * @beta
+ * @public
  */
 export declare interface JSONSchema7 {
+    /** Declared JSON Schema dialect URI for the document root. */
     $schema?: string;
+    /** Stable identifier for the schema document or sub-schema. */
     $id?: string;
+    /** Reference to another schema location. */
     $ref?: string;
+    /** Human-readable title for the schema node. */
     title?: string;
+    /** Human-readable description for the schema node. */
     description?: string;
+    /** Whether the schema node is deprecated. */
     deprecated?: boolean;
+    /** JSON Schema type keyword for the current node. */
     type?: JSONSchemaType | JSONSchemaType[];
+    /** Inclusive minimum string length. */
     minLength?: number;
+    /** Inclusive maximum string length. */
     maxLength?: number;
+    /** Regular expression pattern applied to string values. */
     pattern?: string;
+    /** Inclusive numeric lower bound. */
     minimum?: number;
+    /** Inclusive numeric upper bound. */
     maximum?: number;
+    /** Exclusive numeric lower bound. */
     exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound. */
     exclusiveMaximum?: number;
+    /** Closed set of allowed scalar values. */
     enum?: readonly (string | number | boolean | null)[];
+    /** Literal value the instance must equal. */
     const?: string | number | boolean | null;
+    /** Object properties keyed by property name. */
     properties?: Record<string, JSONSchema7>;
+    /** Property names that must be present on object values. */
     required?: string[];
+    /** Whether, or how, additional object properties are allowed. */
     additionalProperties?: boolean | JSONSchema7;
+    /** Item schema or tuple schemas applied to array elements. */
     items?: JSONSchema7 | JSONSchema7[];
+    /** Inclusive minimum array length. */
     minItems?: number;
+    /** Inclusive maximum array length. */
     maxItems?: number;
+    /** Schemas that must all validate successfully. */
     allOf?: JSONSchema7[];
+    /** Schemas of which at least one may validate successfully. */
     anyOf?: JSONSchema7[];
+    /** Schemas of which exactly one should validate successfully. */
     oneOf?: JSONSchema7[];
+    /** Schema that must not validate successfully. */
     not?: JSONSchema7;
+    /** Conditional branch predicate schema. */
     if?: JSONSchema7;
+    /** Schema applied when the `if` branch matches. */
     then?: JSONSchema7;
+    /** Schema applied when the `if` branch does not match. */
     else?: JSONSchema7;
+    /** Format hint for downstream validators and tooling. */
     format?: string;
+    /** Default value suggested for the schema node. */
     default?: unknown;
     /**
      * Data source key for dynamic enum fields.
@@ -605,6 +709,13 @@ export declare interface JSONSchema7 {
     "x-formspec-schemaSource"?: string;
 }
 
+/**
+ * Zod schema for the legacy JSON Schema 7 subset used by `@formspec/build`.
+ *
+ * @public
+ */
+export declare const jsonSchema7Schema: z.ZodType<JSONSchema7>;
+
 /**
  * JSON Schema type definitions.
  *
@@ -613,7 +724,7 @@ export declare interface JSONSchema7 {
 /**
  * JSON Schema primitive types.
  *
- * @beta
+ * @public
  */
 export declare type JSONSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
 
@@ -623,10 +734,15 @@ export declare type JSONSchemaType = "string" | "number" | "integer" | "boolean"
  * @public
  */
 export declare interface LabelElement {
+    /** Discriminator identifying a static text label element. */
     readonly type: "Label";
+    /** Static text content rendered by the label element. */
     readonly text: string;
+    /** Optional rule controlling visibility or enablement. */
     readonly rule?: Rule | undefined;
+    /** Renderer-specific label options. */
     readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
     readonly [k: string]: unknown;
 }
 
@@ -652,7 +768,9 @@ export { ObjectField }
  * @public
  */
 export declare interface Rule {
+    /** UI effect to apply when the rule condition matches. */
     readonly effect: RuleEffect;
+    /** Predicate that controls when the UI effect applies. */
     readonly condition: SchemaBasedCondition;
 }
 
@@ -662,17 +780,29 @@ export declare interface Rule {
  * @public
  */
 export declare interface RuleConditionSchema {
+    /** Literal value the condition schema must equal. */
     const?: unknown;
+    /** Allowed values for the condition schema. */
     enum?: readonly unknown[];
+    /** JSON Schema type required by the condition schema. */
     type?: string;
+    /** Negated branch of the condition schema. */
     not?: RuleConditionSchema;
+    /** Inclusive numeric lower bound in the condition schema. */
     minimum?: number;
+    /** Inclusive numeric upper bound in the condition schema. */
     maximum?: number;
+    /** Exclusive numeric lower bound in the condition schema. */
     exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound in the condition schema. */
     exclusiveMaximum?: number;
+    /** Inclusive minimum string length in the condition schema. */
     minLength?: number;
+    /** Nested property conditions keyed by property name. */
     properties?: Record<string, RuleConditionSchema>;
+    /** Property names that must be present for the condition to match. */
     required?: string[];
+    /** Schemas that must all match for the condition to succeed. */
     allOf?: RuleConditionSchema[];
 }
 
@@ -697,7 +827,9 @@ export declare type RuleEffect = "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
  * @public
  */
 export declare interface SchemaBasedCondition {
+    /** JSON Pointer scope the rule evaluates against. */
     readonly scope: string;
+    /** JSON Schema fragment evaluated at the scoped location. */
     readonly schema: RuleConditionSchema;
 }
 
@@ -747,8 +879,11 @@ export declare type UISchemaElement = ControlElement | VerticalLayout | Horizont
  * @public
  */
 export declare interface UISchemaElementBase {
+    /** Discriminator for the concrete JSON Forms element type. */
     type: UISchemaElementType;
+    /** Optional rule controlling visibility or enablement. */
     rule?: Rule;
+    /** Renderer-specific options shared by UI schema elements. */
     options?: Record<string, unknown>;
 }
 
@@ -759,21 +894,31 @@ export declare interface UISchemaElementBase {
  */
 export declare type UISchemaElementType = "Control" | "VerticalLayout" | "HorizontalLayout" | "Group" | "Categorization" | "Category" | "Label";
 
+/**
+ * Zod schema for the root UI Schema (layout types only).
+ *
+ * @public
+ */
+export declare const uiSchemaSchema: z.ZodType<UISchema>;
+
 /**
  * A vertical layout element.
  *
  * @public
  */
 export declare interface VerticalLayout {
+    /** Discriminator identifying a vertical layout container. */
     readonly type: "VerticalLayout";
+    /** Child elements rendered in vertical order. */
     readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
     readonly rule?: Rule | undefined;
+    /** Renderer-specific layout options. */
     readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
     readonly [k: string]: unknown;
 }
 
-export { VocabularyKeywordRegistration }
-
 /**
  * Builds and writes both JSON Schema and UI Schema files to disk.
  *