formspec 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/formspec.d.ts

@@ -52,248 +52,1561 @@
  * @packageDocumentation
  */
 
-import { AnyField } from '@formspec/core';
-import { ArrayField } from '@formspec/core';
-import { BooleanField } from '@formspec/core';
-import { buildFormSchemas } from '@formspec/build';
-import { buildMixedAuthoringSchemas } from '@formspec/build';
-import { BuildMixedAuthoringSchemasOptions } from '@formspec/build';
-import { BuildResult } from '@formspec/build';
-import { BuildSchema } from '@formspec/dsl';
-import { Conditional } from '@formspec/core';
-import { ControlElement } from '@formspec/build';
-import { createInitialFieldState } from '@formspec/core';
-import { DataSourceOption } from '@formspec/core';
-import { DataSourceRegistry } from '@formspec/core';
-import { DataSourceValueType } from '@formspec/core';
-import { defineResolvers } from '@formspec/runtime';
-import { DynamicEnumField } from '@formspec/core';
-import { DynamicSchemaField } from '@formspec/core';
-import { EnumOption } from '@formspec/dsl';
-import { EnumOptionValue } from '@formspec/dsl';
-import { EqualsPredicate } from '@formspec/core';
-import { ExtractFields } from '@formspec/dsl';
-import { ExtractFieldsFromArray } from '@formspec/dsl';
-import { FetchOptionsResponse } from '@formspec/core';
-import { field } from '@formspec/dsl';
-import { FieldState } from '@formspec/core';
-import { FormElement } from '@formspec/core';
-import { FormSpec } from '@formspec/core';
-import { formspec } from '@formspec/dsl';
-import { FormSpecOptions } from '@formspec/dsl';
-import { formspecWithValidation } from '@formspec/dsl';
-import { FormState } from '@formspec/core';
-import { generateJsonSchema } from '@formspec/build';
-import { generateUiSchema } from '@formspec/build';
-import { Group } from '@formspec/core';
-import { group } from '@formspec/dsl';
-import { GroupLayout } from '@formspec/build';
-import { HorizontalLayout } from '@formspec/build';
-import { InferFieldValue } from '@formspec/dsl';
-import { InferFormSchema } from '@formspec/dsl';
-import { InferSchema } from '@formspec/dsl';
-import { is } from '@formspec/dsl';
-import { isArrayField } from '@formspec/core';
-import { isBooleanField } from '@formspec/core';
-import { isConditional } from '@formspec/core';
-import { isDynamicEnumField } from '@formspec/core';
-import { isDynamicSchemaField } from '@formspec/core';
-import { isField } from '@formspec/core';
-import { isGroup } from '@formspec/core';
-import { isNumberField } from '@formspec/core';
-import { isObjectField } from '@formspec/core';
-import { isStaticEnumField } from '@formspec/core';
-import { isTextField } from '@formspec/core';
-import { JsonSchema2020 } from '@formspec/build';
-import { JSONSchema7 } from '@formspec/build';
-import { JSONSchemaType } from '@formspec/build';
-import { logValidationIssues } from '@formspec/dsl';
-import { MixedAuthoringSchemas } from '@formspec/build';
-import { NumberField } from '@formspec/core';
-import { ObjectField } from '@formspec/core';
-import { Predicate } from '@formspec/core';
-import { Resolver } from '@formspec/runtime';
-import { ResolverMap } from '@formspec/runtime';
-import { ResolverRegistry } from '@formspec/runtime';
-import { Rule } from '@formspec/build';
-import { RuleEffect } from '@formspec/build';
-import { SchemaBasedCondition } from '@formspec/build';
-import { StaticEnumField } from '@formspec/core';
-import { TextField } from '@formspec/core';
-import { UISchema } from '@formspec/build';
-import { UISchemaElement } from '@formspec/build';
-import { UISchemaElementType } from '@formspec/build';
-import { validateForm } from '@formspec/dsl';
-import { ValidationIssue } from '@formspec/dsl';
-import { ValidationResult } from '@formspec/dsl';
-import { ValidationSeverity } from '@formspec/dsl';
-import { Validity } from '@formspec/core';
-import { VerticalLayout } from '@formspec/build';
-import { when } from '@formspec/dsl';
-import { writeSchemas } from '@formspec/build';
-import { WriteSchemasOptions } from '@formspec/build';
-import { WriteSchemasResult } from '@formspec/build';
+/**
+ * Union of all field types.
+ *
+ * @public
+ */
+export declare type AnyField = TextField<string> | NumberField<string> | BooleanField<string> | StaticEnumField<string, readonly EnumOptionValue[]> | DynamicEnumField<string, string> | DynamicSchemaField<string> | ArrayField<string, readonly FormElement[]> | ObjectField<string, readonly FormElement[]>;
 
-export { AnyField }
+/**
+ * Union of all field types.
+ *
+ * @public
+ */
+declare type AnyField_2 = TextField_2<string> | NumberField_2<string> | BooleanField_2<string> | StaticEnumField_2<string, readonly EnumOptionValue_2[]> | DynamicEnumField_2<string, string> | DynamicSchemaField_2<string> | ArrayField_2<string, readonly FormElement_2[]> | ObjectField_2<string, readonly FormElement_2[]>;
 
-export { ArrayField }
+/**
+ * An array field containing repeating items.
+ *
+ * Use this for lists of values (e.g., multiple addresses, line items).
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Items - The form elements that define each array item
+ *
+ * @public
+ */
+export declare interface ArrayField<N extends string, Items extends readonly FormElement[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an array field */
+    readonly _field: "array";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Form elements that define the schema for each array item */
+    readonly items: Items;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Minimum number of items required */
+    readonly minItems?: number;
+    /** Maximum number of items allowed */
+    readonly maxItems?: number;
+}
 
-export { BooleanField }
+/**
+ * An array field containing repeating items.
+ *
+ * Use this for lists of values (e.g., multiple addresses, line items).
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Items - The form elements that define each array item
+ *
+ * @public
+ */
+declare interface ArrayField_2<N extends string, Items extends readonly FormElement_2[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an array field */
+    readonly _field: "array";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Form elements that define the schema for each array item */
+    readonly items: Items;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Minimum number of items required */
+    readonly minItems?: number;
+    /** Maximum number of items allowed */
+    readonly maxItems?: number;
+}
 
-export { buildFormSchemas }
+/**
+ * A boolean checkbox field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+export declare interface BooleanField<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a boolean field */
+    readonly _field: "boolean";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
 
-export { buildMixedAuthoringSchemas }
+/**
+ * A boolean checkbox field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+declare interface BooleanField_2<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a boolean field */
+    readonly _field: "boolean";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
 
-export { BuildMixedAuthoringSchemasOptions }
+/**
+ * Builds both JSON Schema and UI Schema from a FormSpec.
+ *
+ * @public
+ */
+export declare function buildFormSchemas<E extends readonly FormElement[]>(form: FormSpec<E>, options?: BuildFormSchemasOptions): BuildResult;
 
-export { 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.
+ *
+ * @public
+ */
+export declare type BuildFormSchemasOptions = GenerateJsonSchemaOptions;
 
-export { BuildSchema }
+/**
+ * Result of building form schemas.
+ *
+ * @public
+ */
+export declare interface BuildResult {
+    /** JSON Schema 2020-12 for validation */
+    readonly jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering */
+    readonly uiSchema: UISchema;
+}
 
-export { Conditional }
+/**
+ * Builds a schema type from extracted fields.
+ *
+ * @public
+ */
+export declare type BuildSchema<Fields> = { [N in Fields extends { name: infer K extends string } ? K : never]: InferFieldValue<Extract<Fields, { name: N } & AnyField>> };
 
-export { ControlElement }
+/**
+ * A Categorization element (tab-based layout).
+ *
+ * @public
+ */
+export declare interface Categorization {
+    readonly type: "Categorization";
+    readonly elements: Category[];
+    readonly label?: string | undefined;
+    readonly rule?: Rule | undefined;
+    readonly options?: Record<string, unknown> | undefined;
+    readonly [k: string]: unknown;
+}
 
-export { createInitialFieldState }
+/**
+ * A Category element, used inside a Categorization layout.
+ *
+ * @public
+ */
+export declare interface Category {
+    readonly type: "Category";
+    readonly label: string;
+    readonly elements: UISchemaElement[];
+    readonly rule?: Rule | undefined;
+    readonly options?: Record<string, unknown> | undefined;
+    readonly [k: string]: unknown;
+}
 
-export { DataSourceOption }
+/**
+ * A conditional wrapper that shows/hides elements based on another field's value.
+ *
+ * @typeParam FieldName - The field to check
+ * @typeParam Value - The value that triggers the condition
+ * @typeParam Elements - Tuple of contained form elements
+ *
+ * @public
+ */
+export declare interface Conditional<FieldName extends string, Value, Elements extends readonly FormElement[]> {
+    /** Type discriminator - identifies this as a conditional element */
+    readonly _type: "conditional";
+    /** Name of the field whose value determines visibility */
+    readonly field: FieldName;
+    /** Value that triggers the condition (shows nested elements) */
+    readonly value: Value;
+    /** Form elements shown when condition is met */
+    readonly elements: Elements;
+}
 
-export { DataSourceRegistry }
+/**
+ * A conditional wrapper that shows/hides elements based on another field's value.
+ *
+ * @typeParam FieldName - The field to check
+ * @typeParam Value - The value that triggers the condition
+ * @typeParam Elements - Tuple of contained form elements
+ *
+ * @public
+ */
+declare interface Conditional_2<FieldName extends string, Value, Elements extends readonly FormElement_2[]> {
+    /** Type discriminator - identifies this as a conditional element */
+    readonly _type: "conditional";
+    /** Name of the field whose value determines visibility */
+    readonly field: FieldName;
+    /** Value that triggers the condition (shows nested elements) */
+    readonly value: Value;
+    /** Form elements shown when condition is met */
+    readonly elements: Elements;
+}
 
-export { DataSourceValueType }
+/**
+ * A Control element that binds to a JSON Schema property.
+ *
+ * @public
+ */
+export declare interface ControlElement {
+    readonly type: "Control";
+    readonly scope: string;
+    readonly label?: string | false | undefined;
+    readonly rule?: Rule | undefined;
+    readonly options?: Record<string, unknown> | undefined;
+    readonly [k: string]: unknown;
+}
 
-export { defineResolvers }
+/**
+ * Creates initial field state with default values.
+ *
+ * @typeParam T - The value type of the field
+ * @param value - The initial value for the field
+ * @returns Initial field state
+ *
+ * @public
+ */
+export declare function createInitialFieldState<T>(value: T): FieldState<T>;
 
-export { DynamicEnumField }
+/**
+ * A single option returned by a data source resolver.
+ *
+ * @typeParam T - The data type for additional option metadata
+ *
+ * @public
+ */
+export declare interface DataSourceOption<T = unknown> {
+    /** The value stored when this option is selected */
+    readonly value: string;
+    /** The display label for this option */
+    readonly label: string;
+    /** Optional additional data associated with this option */
+    readonly data?: T;
+}
 
-export { DynamicSchemaField }
+/**
+ * Registry for dynamic data sources.
+ *
+ * Extend this interface via module augmentation to register your data sources:
+ *
+ * @example
+ * ```typescript
+ * declare module "@formspec/core" {
+ *   interface DataSourceRegistry {
+ *     countries: { id: string; code: string; name: string };
+ *     templates: { id: string; name: string; category: string };
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface DataSourceRegistry {
+}
 
-export { EnumOption }
+/**
+ * Gets the value type for a registered data source.
+ *
+ * If the source has an `id` property, that becomes the value type.
+ * Otherwise, defaults to `string`.
+ *
+ * @public
+ */
+export declare type DataSourceValueType<Source extends string> = Source extends keyof DataSourceRegistry ? DataSourceRegistry[Source] extends {
+    id: infer ID;
+} ? ID : string : string;
 
-export { EnumOptionValue }
+/**
+ * Defines resolvers for a form's dynamic data sources.
+ *
+ * @public
+ */
+export declare function defineResolvers<E extends readonly FormElement[], Sources extends string = ResolverSourcesForForm<E>>(form: FormSpec<E>, resolvers: ResolverMap<Sources>): ResolverRegistry<Sources>;
 
-export { EqualsPredicate }
+/**
+ * A field with dynamic enum options (fetched from a data source at runtime).
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Source - The data source key (from DataSourceRegistry)
+ *
+ * @public
+ */
+export declare interface DynamicEnumField<N extends string, Source extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a dynamic enum field */
+    readonly _field: "dynamic_enum";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Data source key for fetching options at runtime */
+    readonly source: Source;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Field names whose values are needed to fetch options */
+    readonly params?: readonly string[];
+}
 
-export { ExtractFields }
+/**
+ * A field with dynamic enum options (fetched from a data source at runtime).
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Source - The data source key (from DataSourceRegistry)
+ *
+ * @public
+ */
+declare interface DynamicEnumField_2<N extends string, Source extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a dynamic enum field */
+    readonly _field: "dynamic_enum";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Data source key for fetching options at runtime */
+    readonly source: Source;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Field names whose values are needed to fetch options */
+    readonly params?: readonly string[];
+}
 
-export { ExtractFieldsFromArray }
+/**
+ * A field that loads its schema dynamically (e.g., from an extension).
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+export declare interface DynamicSchemaField<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a dynamic schema field */
+    readonly _field: "dynamic_schema";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Identifier for the schema source */
+    readonly schemaSource: string;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Field names whose values are needed to configure the schema */
+    readonly params?: readonly string[];
+}
 
-export { FetchOptionsResponse }
+/**
+ * A field that loads its schema dynamically (e.g., from an extension).
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+declare interface DynamicSchemaField_2<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a dynamic schema field */
+    readonly _field: "dynamic_schema";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Identifier for the schema source */
+    readonly schemaSource: string;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Field names whose values are needed to configure the schema */
+    readonly params?: readonly string[];
+}
 
-export { field }
+/**
+ * An enum option with a separate ID and display label.
+ *
+ * Use this when the stored value (id) should differ from the display text (label).
+ *
+ * @public
+ */
+export declare interface EnumOption {
+    readonly id: string;
+    readonly label: string;
+}
 
-export { FieldState }
+/**
+ * An enum option with a separate ID and display label.
+ *
+ * Use this when the stored value (id) should differ from the display text (label).
+ *
+ * @public
+ */
+declare interface EnumOption_2 {
+    readonly id: string;
+    readonly label: string;
+}
 
-export { FormElement }
+/**
+ * Valid enum option types: either plain strings or objects with id/label.
+ *
+ * @public
+ */
+export declare type EnumOptionValue = string | EnumOption;
+
+/**
+ * Valid enum option types: either plain strings or objects with id/label.
+ *
+ * @public
+ */
+declare type EnumOptionValue_2 = string | EnumOption_2;
+
+/**
+ * Predicate types for conditional logic.
+ *
+ * Predicates are used with `when()` to define conditions in a readable way.
+ */
+/**
+ * An equality predicate that checks if a field equals a specific value.
+ *
+ * @typeParam K - The field name to check
+ * @typeParam V - The value to compare against
+ *
+ * @public
+ */
+export declare interface EqualsPredicate<K extends string, V> {
+    /** Predicate type discriminator */
+    readonly _predicate: "equals";
+    /** Name of the field to check */
+    readonly field: K;
+    /** Value that the field must equal */
+    readonly value: V;
+}
+
+/**
+ * Extracts fields that are inside conditionals.
+ *
+ * @public
+ */
+export declare type ExtractConditionalFields<E> = E extends AnyField ? never : E extends Group<infer Elements> ? ExtractConditionalFieldsFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractFieldsFromArray<Elements> : never;
+
+/**
+ * Extracts conditional fields from an array of elements.
+ *
+ * @public
+ */
+export declare type ExtractConditionalFieldsFromArray<Elements> = Elements extends readonly [infer First, ...infer Rest] ? ExtractConditionalFields<First> | ExtractConditionalFieldsFromArray<Rest> : never;
+
+/**
+ * Extracts dynamic data-source names referenced by a single FormSpec element.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSources<E> = E extends DynamicEnumField<string, infer S> ? S : E extends Group<infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractDynamicSourcesFromArray<Elements> : never;
+
+/**
+ * Extracts dynamic data-source names referenced anywhere in an element array.
+ *
+ * @public
+ */
+export declare type ExtractDynamicSourcesFromArray<Elements> = Elements extends readonly [
+infer First,
+...infer Rest
+] ? ExtractDynamicSources<First> | ExtractDynamicSourcesFromArray<Rest> : never;
+
+/**
+ * Extracts all fields from a single element.
+ *
+ * @public
+ */
+export declare type ExtractFields<E> = E extends AnyField ? E : E extends Group<infer Elements> ? ExtractFieldsFromArray<Elements> : E extends Conditional<string, unknown, infer Elements> ? ExtractFieldsFromArray<Elements> : never;
+
+/**
+ * Extracts fields from an array of elements.
+ *
+ * @public
+ */
+export declare type ExtractFieldsFromArray<Elements> = Elements extends readonly [infer First, ...infer Rest] ? ExtractFields<First> | ExtractFieldsFromArray<Rest> : never;
+
+/**
+ * Extracts fields that are not inside conditionals.
+ *
+ * @public
+ */
+export declare type ExtractNonConditionalFields<E> = E extends AnyField ? E : E extends Group<infer Elements> ? ExtractNonConditionalFieldsFromArray<Elements> : E extends Conditional<string, unknown, infer _Elements> ? never : never;
+
+/**
+ * Extracts non-conditional fields from an array of elements.
+ *
+ * @public
+ */
+export declare type ExtractNonConditionalFieldsFromArray<Elements> = Elements extends readonly [infer First, ...infer Rest] ? ExtractNonConditionalFields<First> | ExtractNonConditionalFieldsFromArray<Rest> : never;
+
+/**
+ * Response from a data source resolver function.
+ *
+ * @typeParam T - The data type for option metadata
+ *
+ * @public
+ */
+export declare interface FetchOptionsResponse<T = unknown> {
+    /** The available options */
+    readonly options: readonly DataSourceOption<T>[];
+    /** Validity state of the fetch operation */
+    readonly validity: "valid" | "invalid" | "unknown";
+    /** Optional message (e.g., error description) */
+    readonly message?: string;
+}
+
+/**
+ * Field builder namespace containing functions to create each field type.
+ *
+ * @example
+ * ```typescript
+ * import { field } from "@formspec/dsl";
+ *
+ * field.text("name", { label: "Full Name" });
+ * field.number("age", { min: 0, max: 150 });
+ * field.enum("status", ["draft", "sent", "paid"]);
+ * field.dynamicEnum("country", "countries", { label: "Country" });
+ * ```
+ *
+ * @public
+ */
+export declare const field: {
+    /**
+     * Creates a text input field.
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Optional configuration for label, placeholder, etc.
+     * @returns A TextField descriptor
+     */
+    text: <const N extends string>(name: N, config?: Omit<TextField_2<N>, "_type" | "_field" | "name">) => TextField_2<N>;
+    /**
+     * Creates a numeric input field.
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Optional configuration for label, min, max, etc.
+     * @returns A NumberField descriptor
+     */
+    number: <const N extends string>(name: N, config?: Omit<NumberField_2<N>, "_type" | "_field" | "name">) => NumberField_2<N>;
+    /**
+     * Creates a boolean checkbox field.
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Optional configuration for label, etc.
+     * @returns A BooleanField descriptor
+     */
+    boolean: <const N extends string>(name: N, config?: Omit<BooleanField_2<N>, "_type" | "_field" | "name">) => BooleanField_2<N>;
+    /**
+     * Creates a field with static enum options (known at compile time).
+     *
+     * Literal types are automatically inferred - no `as const` needed:
+     * ```typescript
+     * field.enum("status", ["draft", "sent", "paid"])
+     * // Schema type: "draft" | "sent" | "paid"
+     * ```
+     *
+     * Options can be strings or objects with `id` and `label`:
+     * ```typescript
+     * field.enum("priority", [
+     *   { id: "low", label: "Low Priority" },
+     *   { id: "high", label: "High Priority" },
+     * ])
+     * ```
+     *
+     * **Note:** All options must be of the same type (all strings OR all objects).
+     * Mixing strings and objects will throw a runtime error.
+     *
+     * @param name - The field name (used as the schema key)
+     * @param options - Array of allowed string values or objects with `id` and `label` properties
+     * @param config - Optional configuration for label, etc.
+     * @returns A StaticEnumField descriptor
+     * @throws Error if options array contains mixed types (strings and objects)
+     */
+    enum: <const N extends string, const O extends readonly EnumOptionValue_2[]>(name: N, options: O, config?: Omit<StaticEnumField_2<N, O>, "_type" | "_field" | "name" | "options">) => StaticEnumField_2<N, O>;
+    /**
+     * Creates a field with dynamic enum options (fetched from a data source at runtime).
+     *
+     * The data source must be registered in DataSourceRegistry via module augmentation:
+     * ```typescript
+     * declare module "@formspec/core" {
+     *   interface DataSourceRegistry {
+     *     countries: { id: string; code: string; name: string };
+     *   }
+     * }
+     *
+     * field.dynamicEnum("country", "countries", { label: "Country" })
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param source - The data source key (must be in DataSourceRegistry)
+     * @param config - Optional configuration for label, params, etc.
+     * @returns A DynamicEnumField descriptor
+     */
+    dynamicEnum: <const N extends string, const Source extends string>(name: N, source: Source, config?: Omit<DynamicEnumField_2<N, Source>, "_type" | "_field" | "name" | "source">) => DynamicEnumField_2<N, Source>;
+    /**
+     * Creates a field that loads its schema dynamically (e.g., from an extension).
+     *
+     * @param name - The field name (used as the schema key)
+     * @param schemaSource - Identifier for the schema source
+     * @param config - Optional configuration for label, etc.
+     * @returns A DynamicSchemaField descriptor
+     */
+    dynamicSchema: <const N extends string>(name: N, schemaSource: string, config?: Omit<DynamicSchemaField_2<N>, "_type" | "_field" | "name" | "schemaSource">) => DynamicSchemaField_2<N>;
+    /**
+     * Creates an array field containing repeating items.
+     *
+     * Use this for lists of values (e.g., multiple addresses, line items).
+     *
+     * @example
+     * ```typescript
+     * field.array("addresses",
+     *   field.text("street", { label: "Street" }),
+     *   field.text("city", { label: "City" }),
+     *   field.text("zip", { label: "ZIP Code" }),
+     * )
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param items - The form elements that define each array item
+     * @returns An ArrayField descriptor
+     */
+    array: <const N extends string, const Items extends readonly FormElement_2[]>(name: N, ...items: Items) => ArrayField_2<N, Items>;
+    /**
+     * Creates an array field with additional configuration options.
+     *
+     * @example
+     * ```typescript
+     * field.arrayWithConfig("lineItems", {
+     *   label: "Line Items",
+     *   minItems: 1,
+     *   maxItems: 10,
+     * },
+     *   field.text("description"),
+     *   field.number("quantity"),
+     * )
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Configuration for label, minItems, maxItems, etc.
+     * @param items - The form elements that define each array item
+     * @returns An ArrayField descriptor
+     */
+    arrayWithConfig: <const N extends string, const Items extends readonly FormElement_2[]>(name: N, config: Omit<ArrayField_2<N, Items>, "_type" | "_field" | "name" | "items">, ...items: Items) => ArrayField_2<N, Items>;
+    /**
+     * Creates an object field containing nested properties.
+     *
+     * Use this for grouping related fields under a single key in the schema.
+     *
+     * @example
+     * ```typescript
+     * field.object("address",
+     *   field.text("street", { label: "Street" }),
+     *   field.text("city", { label: "City" }),
+     *   field.text("zip", { label: "ZIP Code" }),
+     * )
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param properties - The form elements that define the object's properties
+     * @returns An ObjectField descriptor
+     */
+    object: <const N extends string, const Properties extends readonly FormElement_2[]>(name: N, ...properties: Properties) => ObjectField_2<N, Properties>;
+    /**
+     * Creates an object field with additional configuration options.
+     *
+     * @example
+     * ```typescript
+     * field.objectWithConfig("billingAddress", { label: "Billing Address", required: true },
+     *   field.text("street"),
+     *   field.text("city"),
+     * )
+     * ```
+     *
+     * @param name - The field name (used as the schema key)
+     * @param config - Configuration for label, required, etc.
+     * @param properties - The form elements that define the object's properties
+     * @returns An ObjectField descriptor
+     */
+    objectWithConfig: <const N extends string, const Properties extends readonly FormElement_2[]>(name: N, config: Omit<ObjectField_2<N, Properties>, "_type" | "_field" | "name" | "properties">, ...properties: Properties) => ObjectField_2<N, Properties>;
+};
+
+/**
+ * Represents the runtime state of a single form field.
+ *
+ * @typeParam T - The value type of the field
+ *
+ * @public
+ */
+export declare interface FieldState<T> {
+    /** Current value of the field */
+    readonly value: T;
+    /** Whether the field has been modified by the user */
+    readonly dirty: boolean;
+    /** Whether the field has been focused and blurred */
+    readonly touched: boolean;
+    /** Current validity state */
+    readonly validity: Validity;
+    /** Validation error messages, if any */
+    readonly errors: readonly string[];
+}
+
+/**
+ * Utility type that flattens intersection types.
+ *
+ * @public
+ */
+export declare type FlattenIntersection<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * Union of all form element types (fields and structural elements).
+ *
+ * @public
+ */
+export declare type FormElement = AnyField | Group<readonly FormElement[]> | Conditional<string, unknown, readonly FormElement[]>;
+
+/**
+ * Union of all form element types (fields and structural elements).
+ *
+ * @public
+ */
+declare type FormElement_2 = AnyField_2 | Group_2<readonly FormElement_2[]> | Conditional_2<string, unknown, readonly FormElement_2[]>;
+
+/**
+ * A complete form specification.
+ *
+ * @typeParam Elements - Tuple of top-level form elements
+ *
+ * @public
+ */
+export declare interface FormSpec<Elements extends readonly FormElement[]> {
+    /** Top-level form elements */
+    readonly elements: Elements;
+}
+
+/**
+ * Creates a complete form specification.
+ *
+ * @public
+ */
+export declare function formspec<const Elements extends readonly FormElement[]>(...elements: Elements): FormSpec<Elements>;
+
+/**
+ * Options for creating a form specification.
+ *
+ * @public
+ */
+export declare interface FormSpecOptions {
+    /**
+     * Whether to validate the form structure.
+     * - `true` or `"warn"`: Validate and log warnings/errors to console
+     * - `"throw"`: Validate and throw an error if validation fails
+     * - `false`: Skip validation (default in production for performance)
+     *
+     * @defaultValue false
+     */
+    validate?: boolean | "warn" | "throw";
+    /**
+     * Optional name for the form (used in validation messages).
+     */
+    name?: string;
+}
+
+/**
+ * Creates a complete form specification with validation options.
+ *
+ * @public
+ */
+export declare function formspecWithValidation<const Elements extends readonly FormElement[]>(options: FormSpecOptions, ...elements: Elements): FormSpec<Elements>;
+
+/**
+ * Represents the runtime state of an entire form.
+ *
+ * @typeParam Schema - The form schema type (maps field names to value types)
+ *
+ * @public
+ */
+export declare interface FormState<Schema extends Record<string, unknown>> {
+    /** State for each field, keyed by field name */
+    readonly fields: {
+        readonly [K in keyof Schema]: FieldState<Schema[K]>;
+    };
+    /** Whether any field has been modified */
+    readonly dirty: boolean;
+    /** Whether the form is currently being submitted */
+    readonly submitting: boolean;
+    /** Overall form validity (derived from all field validities) */
+    readonly validity: Validity;
+}
+
+/**
+ * Generates a JSON Schema 2020-12 from a FormSpec.
+ *
+ * @public
+ */
+export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>, options?: GenerateJsonSchemaOptions): JsonSchema2020;
 
-export { FormSpec }
+/**
+ * Options for generating JSON Schema from a Chain DSL form.
+ *
+ * @public
+ */
+export declare interface GenerateJsonSchemaOptions {
+    /**
+     * Vendor prefix for emitted extension keywords.
+     * @defaultValue "x-formspec"
+     */
+    readonly vendorPrefix?: string | undefined;
+}
 
-export { formspec }
+/**
+ * Generates a UI schema from a FormSpec.
+ *
+ * @public
+ */
+export declare function generateUiSchema<E extends readonly FormElement[]>(form: FormSpec<E>): UISchema;
 
-export { FormSpecOptions }
+/**
+ * A visual grouping of form elements.
+ *
+ * Groups provide visual organization and can be rendered as fieldsets or sections.
+ *
+ * @typeParam Elements - Tuple of contained form elements
+ *
+ * @public
+ */
+export declare interface Group<Elements extends readonly FormElement[]> {
+    /** Type discriminator - identifies this as a group element */
+    readonly _type: "group";
+    /** Display label for the group */
+    readonly label: string;
+    /** Form elements contained within this group */
+    readonly elements: Elements;
+}
 
-export { formspecWithValidation }
+/**
+ * Creates a visual group of form elements.
+ *
+ * @public
+ */
+export declare function group<const Elements extends readonly FormElement[]>(label: string, ...elements: Elements): Group<Elements>;
 
-export { FormState }
+/**
+ * A visual grouping of form elements.
+ *
+ * Groups provide visual organization and can be rendered as fieldsets or sections.
+ *
+ * @typeParam Elements - Tuple of contained form elements
+ *
+ * @public
+ */
+declare interface Group_2<Elements extends readonly FormElement_2[]> {
+    /** Type discriminator - identifies this as a group element */
+    readonly _type: "group";
+    /** Display label for the group */
+    readonly label: string;
+    /** Form elements contained within this group */
+    readonly elements: Elements;
+}
 
-export { generateJsonSchema }
+/**
+ * A group element with a label.
+ *
+ * @public
+ */
+export declare interface GroupLayout {
+    readonly type: "Group";
+    readonly label: string;
+    readonly elements: UISchemaElement[];
+    readonly rule?: Rule | undefined;
+    readonly options?: Record<string, unknown> | undefined;
+    readonly [k: string]: unknown;
+}
 
-export { generateUiSchema }
+/**
+ * A horizontal layout element.
+ *
+ * @public
+ */
+export declare interface HorizontalLayout {
+    readonly type: "HorizontalLayout";
+    readonly elements: UISchemaElement[];
+    readonly rule?: Rule | undefined;
+    readonly options?: Record<string, unknown> | undefined;
+    readonly [k: string]: unknown;
+}
 
-export { Group }
+/**
+ * Infers the value type from a single field.
+ *
+ * @public
+ */
+export declare type InferFieldValue<F> = F extends TextField<string> ? string : F extends NumberField<string> ? number : F extends BooleanField<string> ? boolean : F extends StaticEnumField<string, infer O extends readonly EnumOptionValue[]> ? O extends readonly EnumOption[] ? O[number]["id"] : O extends readonly string[] ? O[number] : never : F extends DynamicEnumField<string, infer Source> ? DataSourceValueType<Source> : F extends DynamicSchemaField<string> ? Record<string, unknown> : F extends ArrayField<string, infer Items extends readonly FormElement[]> ? InferSchema<Items>[] : F extends ObjectField<string, infer Properties extends readonly FormElement[]> ? InferSchema<Properties> : never;
 
-export { group }
+/**
+ * Infers the schema type from a FormSpec.
+ *
+ * @public
+ */
+export declare type InferFormSchema<F extends FormSpec<readonly FormElement[]>> = F extends FormSpec<infer Elements> ? InferSchema<Elements> : never;
 
-export { GroupLayout }
+/**
+ * Infers the schema type from an array of form elements.
+ *
+ * @public
+ */
+export declare type InferSchema<Elements extends readonly FormElement[]> = FlattenIntersection<BuildSchema<ExtractNonConditionalFieldsFromArray<Elements>> & Partial<BuildSchema<ExtractConditionalFieldsFromArray<Elements>>>>;
 
-export { HorizontalLayout }
+/**
+ * Creates an equality predicate that checks if a field equals a specific value.
+ *
+ * @public
+ */
+export declare function is<const K extends string, const V>(field: K, value: V): EqualsPredicate<K, V>;
 
-export { InferFieldValue }
+/**
+ * Narrows a `FormElement` to an array field.
+ *
+ * @public
+ */
+export declare function isArrayField(element: FormElement): element is ArrayField<string, readonly FormElement[]>;
 
-export { InferFormSchema }
+/**
+ * Narrows a `FormElement` to a boolean checkbox field.
+ *
+ * @public
+ */
+export declare function isBooleanField(element: FormElement): element is BooleanField<string>;
 
-export { InferSchema }
+/**
+ * Narrows a `FormElement` to a conditional wrapper.
+ *
+ * @public
+ */
+export declare function isConditional(element: FormElement): element is Conditional<string, unknown, readonly FormElement[]>;
 
-export { is }
+/**
+ * Narrows a `FormElement` to a dynamic enum field.
+ *
+ * @public
+ */
+export declare function isDynamicEnumField(element: FormElement): element is DynamicEnumField<string, string>;
 
-export { isArrayField }
+/**
+ * Narrows a `FormElement` to a dynamic schema field.
+ *
+ * @public
+ */
+export declare function isDynamicSchemaField(element: FormElement): element is DynamicSchemaField<string>;
 
-export { isBooleanField }
+/**
+ * Narrows a `FormElement` to any field type.
+ *
+ * @public
+ */
+export declare function isField(element: FormElement): element is AnyField;
 
-export { isConditional }
+/**
+ * Narrows a `FormElement` to a visual group.
+ *
+ * @public
+ */
+export declare function isGroup(element: FormElement): element is Group<readonly FormElement[]>;
 
-export { isDynamicEnumField }
+/**
+ * Narrows a `FormElement` to a numeric input field.
+ *
+ * @public
+ */
+export declare function isNumberField(element: FormElement): element is NumberField<string>;
 
-export { isDynamicSchemaField }
+/**
+ * Narrows a `FormElement` to an object field.
+ *
+ * @public
+ */
+export declare function isObjectField(element: FormElement): element is ObjectField<string, readonly FormElement[]>;
 
-export { isField }
+/**
+ * Narrows a `FormElement` to a static enum field.
+ *
+ * @public
+ */
+export declare function isStaticEnumField(element: FormElement): element is StaticEnumField<string, readonly EnumOptionValue[]>;
 
-export { isGroup }
+/**
+ * Narrows a `FormElement` to a text input field.
+ *
+ * @public
+ */
+export declare function isTextField(element: FormElement): element is TextField<string>;
 
-export { isNumberField }
+/**
+ * A JSON Schema 2020-12 document, sub-schema, or keyword collection.
+ *
+ * This interface covers the subset of JSON Schema 2020-12 that this generator
+ * emits, plus an index signature for custom `x-formspec-*` extension keywords.
+ *
+ * @public
+ */
+export declare interface JsonSchema2020 {
+    $schema?: string;
+    $ref?: string;
+    $defs?: Record<string, JsonSchema2020>;
+    type?: string;
+    properties?: Record<string, JsonSchema2020>;
+    required?: string[];
+    items?: JsonSchema2020;
+    additionalProperties?: boolean | JsonSchema2020;
+    enum?: readonly (string | number)[];
+    const?: unknown;
+    allOf?: readonly JsonSchema2020[];
+    oneOf?: readonly JsonSchema2020[];
+    anyOf?: readonly JsonSchema2020[];
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    pattern?: string;
+    uniqueItems?: boolean;
+    format?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    deprecated?: boolean;
+    [key: `x-${string}`]: unknown;
+}
 
-export { isObjectField }
+/**
+ * A Label element for displaying static text.
+ *
+ * @public
+ */
+export declare interface LabelElement {
+    readonly type: "Label";
+    readonly text: string;
+    readonly rule?: Rule | undefined;
+    readonly options?: Record<string, unknown> | undefined;
+    readonly [k: string]: unknown;
+}
 
-export { isStaticEnumField }
+/**
+ * Logs validation issues to the console.
+ *
+ * @param result - The validation result to log
+ * @param formName - Optional name for the form (for better error messages)
+ *
+ * @public
+ */
+export declare function logValidationIssues(result: ValidationResult, formName?: string): void;
 
-export { isTextField }
+/**
+ * A numeric input field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+export declare interface NumberField<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a number field */
+    readonly _field: "number";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Minimum allowed value */
+    readonly min?: number;
+    /** Maximum allowed value */
+    readonly max?: number;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Value must be a multiple of this number (use 1 for integer semantics) */
+    readonly multipleOf?: number;
+}
 
-export { JsonSchema2020 }
+/**
+ * A numeric input field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+declare interface NumberField_2<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a number field */
+    readonly _field: "number";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Minimum allowed value */
+    readonly min?: number;
+    /** Maximum allowed value */
+    readonly max?: number;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Value must be a multiple of this number (use 1 for integer semantics) */
+    readonly multipleOf?: number;
+}
 
-export { JSONSchema7 }
+/**
+ * An object field containing nested properties.
+ *
+ * Use this for grouping related fields under a single key in the schema.
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Properties - The form elements that define the object's properties
+ *
+ * @public
+ */
+export declare interface ObjectField<N extends string, Properties extends readonly FormElement[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an object field */
+    readonly _field: "object";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Form elements that define the properties of this object */
+    readonly properties: Properties;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
 
-export { JSONSchemaType }
+/**
+ * An object field containing nested properties.
+ *
+ * Use this for grouping related fields under a single key in the schema.
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Properties - The form elements that define the object's properties
+ *
+ * @public
+ */
+declare interface ObjectField_2<N extends string, Properties extends readonly FormElement_2[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an object field */
+    readonly _field: "object";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Form elements that define the properties of this object */
+    readonly properties: Properties;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
 
-export { logValidationIssues }
+/**
+ * Union of all predicate types.
+ *
+ * Currently only supports equality, but can be extended with:
+ * - `OneOfPredicate` - field value is one of several options
+ * - `NotPredicate` - negation of another predicate
+ * - `AndPredicate` / `OrPredicate` - logical combinations
+ *
+ * @public
+ */
+export declare type Predicate<K extends string = string, V = unknown> = EqualsPredicate<K, V>;
 
-export { MixedAuthoringSchemas }
+/**
+ * A resolver function that fetches options for a data source.
+ *
+ * @typeParam Source - The data source key from DataSourceRegistry
+ * @typeParam T - The data type for options (from DataSourceRegistry)
+ *
+ * @public
+ */
+export declare type Resolver<Source extends keyof DataSourceRegistry, T = DataSourceRegistry[Source]> = (params?: Record<string, unknown>) => Promise<FetchOptionsResponse<T>>;
 
-export { NumberField }
+/**
+ * Map of resolver functions for a form's dynamic data sources.
+ *
+ * @public
+ */
+export declare type ResolverMap<Sources extends string> = {
+    [S in Sources]: S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+};
 
-export { ObjectField }
+/**
+ * A resolver registry that provides type-safe access to resolvers.
+ *
+ * @public
+ */
+export declare interface ResolverRegistry<Sources extends string> {
+    /**
+     * Gets a resolver by data source name.
+     */
+    get<S extends Sources>(source: S): S extends keyof DataSourceRegistry ? Resolver<S> : (params?: Record<string, unknown>) => Promise<FetchOptionsResponse>;
+    /**
+     * Checks if a resolver exists for a data source.
+     */
+    has(source: string): boolean;
+    /**
+     * Gets all registered data source names.
+     */
+    sources(): Sources[];
+}
 
-export { Predicate }
+/**
+ * Derives the resolver source-key union for a FormSpec element array.
+ *
+ * @public
+ */
+export declare type ResolverSourcesForForm<E extends readonly FormElement[]> = ExtractDynamicSourcesFromArray<E> & string;
 
-export { Resolver }
+/**
+ * Rule for conditional element visibility/enablement.
+ *
+ * @public
+ */
+export declare interface Rule {
+    readonly effect: RuleEffect;
+    readonly condition: SchemaBasedCondition;
+}
 
-export { ResolverMap }
+/**
+ * JSON Schema subset used in rule conditions.
+ *
+ * @public
+ */
+export declare interface RuleConditionSchema {
+    const?: unknown;
+    enum?: readonly unknown[];
+    type?: string;
+    not?: RuleConditionSchema;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    minLength?: number;
+    properties?: Record<string, RuleConditionSchema>;
+    required?: string[];
+    allOf?: RuleConditionSchema[];
+}
 
-export { ResolverRegistry }
+/**
+ * JSON Forms UI Schema type definitions.
+ *
+ * These are the consumer-facing TypeScript shapes. Runtime validation remains
+ * defined separately in `./schema.ts`.
+ *
+ * See: https://jsonforms.io/docs/uischema/
+ */
+/**
+ * Rule effect types for conditional visibility.
+ *
+ * @public
+ */
+export declare type RuleEffect = "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
 
-export { Rule }
+/**
+ * Condition for a rule.
+ *
+ * @public
+ */
+export declare interface SchemaBasedCondition {
+    readonly scope: string;
+    readonly schema: RuleConditionSchema;
+}
 
-export { RuleEffect }
+/**
+ * A field with static enum options (known at compile time).
+ *
+ * Options can be plain strings or objects with `id` and `label` properties.
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam O - Tuple of option values (strings or EnumOption objects)
+ *
+ * @public
+ */
+export declare interface StaticEnumField<N extends string, O extends readonly EnumOptionValue[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an enum field */
+    readonly _field: "enum";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Array of allowed option values */
+    readonly options: O;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
 
-export { SchemaBasedCondition }
+/**
+ * A field with static enum options (known at compile time).
+ *
+ * Options can be plain strings or objects with `id` and `label` properties.
+ *
+ * @typeParam N - The field name (string literal type)
+ * @typeParam O - Tuple of option values (strings or EnumOption objects)
+ *
+ * @public
+ */
+declare interface StaticEnumField_2<N extends string, O extends readonly EnumOptionValue_2[]> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as an enum field */
+    readonly _field: "enum";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Array of allowed option values */
+    readonly options: O;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+}
 
-export { StaticEnumField }
+/**
+ * Form element type definitions.
+ *
+ * These types define the structure of form specifications.
+ * The structure IS the definition - nesting implies layout and conditional logic.
+ */
+/**
+ * A text input field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+export declare interface TextField<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a text field */
+    readonly _field: "text";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Placeholder text shown when field is empty */
+    readonly placeholder?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Minimum string length */
+    readonly minLength?: number;
+    /** Maximum string length */
+    readonly maxLength?: number;
+    /** Regular expression pattern the value must match */
+    readonly pattern?: string;
+}
 
-export { TextField }
+/**
+ * Form element type definitions.
+ *
+ * These types define the structure of form specifications.
+ * The structure IS the definition - nesting implies layout and conditional logic.
+ */
+/**
+ * A text input field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
+ */
+declare interface TextField_2<N extends string> {
+    /** Type discriminator for form elements */
+    readonly _type: "field";
+    /** Field type discriminator - identifies this as a text field */
+    readonly _field: "text";
+    /** Unique field identifier used as the schema key */
+    readonly name: N;
+    /** Display label for the field */
+    readonly label?: string;
+    /** Placeholder text shown when field is empty */
+    readonly placeholder?: string;
+    /** Whether this field is required for form submission */
+    readonly required?: boolean;
+    /** Minimum string length */
+    readonly minLength?: number;
+    /** Maximum string length */
+    readonly maxLength?: number;
+    /** Regular expression pattern the value must match */
+    readonly pattern?: string;
+}
 
-export { UISchema }
+/**
+ * Root UI Schema (always a layout — not a Control, Category, or Label).
+ *
+ * @public
+ */
+export declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout | Categorization;
 
-export { UISchemaElement }
+/**
+ * Union of all UI Schema element types.
+ *
+ * @public
+ */
+export declare type UISchemaElement = ControlElement | VerticalLayout | HorizontalLayout | GroupLayout | Categorization | Category | LabelElement;
 
-export { UISchemaElementType }
+/**
+ * UI Schema element types.
+ *
+ * @public
+ */
+export declare type UISchemaElementType = "Control" | "VerticalLayout" | "HorizontalLayout" | "Group" | "Categorization" | "Category" | "Label";
 
-export { validateForm }
+/**
+ * Validates a form specification for common issues.
+ *
+ * Checks for:
+ * - Duplicate field names at the root level (warning)
+ * - References to non-existent fields in conditionals (error)
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(
+ *   field.text("name"),
+ *   field.text("name"), // Duplicate!
+ *   when("nonExistent", "value", // Reference to non-existent field!
+ *     field.text("extra"),
+ *   ),
+ * );
+ *
+ * const result = validateForm(form.elements);
+ * // result.valid === false
+ * // result.issues contains duplicate and reference errors
+ * ```
+ *
+ * @param elements - The form elements to validate
+ * @returns Validation result with any issues found
+ *
+ * @public
+ */
+export declare function validateForm(elements: readonly FormElement_2[]): ValidationResult;
 
-export { ValidationIssue }
+/**
+ * A validation issue found in a form specification.
+ *
+ * @public
+ */
+export declare interface ValidationIssue {
+    /** Severity of the issue */
+    severity: ValidationSeverity;
+    /** Human-readable message describing the issue */
+    message: string;
+    /** Path to the element with the issue (e.g., "group.fieldName") */
+    path: string;
+}
 
-export { ValidationResult }
+/**
+ * Result of validating a form specification.
+ *
+ * @public
+ */
+export declare interface ValidationResult {
+    /** Whether the form is valid (no errors, warnings are ok) */
+    valid: boolean;
+    /** List of validation issues found */
+    issues: ValidationIssue[];
+}
 
-export { ValidationSeverity }
+/**
+ * Validation issue severity levels.
+ *
+ * @public
+ */
+export declare type ValidationSeverity = "error" | "warning";
 
-export { Validity }
+/**
+ * Represents the validity state of a field or form.
+ *
+ * - `"valid"` - All validations pass
+ * - `"invalid"` - One or more validations failed
+ * - `"unknown"` - Validation state not yet determined (e.g., async validation pending)
+ *
+ * @public
+ */
+export declare type Validity = "valid" | "invalid" | "unknown";
 
-export { VerticalLayout }
+/**
+ * A vertical layout element.
+ *
+ * @public
+ */
+export declare interface VerticalLayout {
+    readonly type: "VerticalLayout";
+    readonly elements: UISchemaElement[];
+    readonly rule?: Rule | undefined;
+    readonly options?: Record<string, unknown> | undefined;
+    readonly [k: string]: unknown;
+}
 
-export { when }
+/**
+ * Creates a conditional wrapper that shows elements based on a predicate.
+ *
+ * @public
+ */
+export declare function when<const K extends string, const V, const Elements extends readonly FormElement[]>(predicate: Predicate<K, V>, ...elements: Elements): Conditional<K, V, Elements>;
 
-export { writeSchemas }
+/**
+ * Builds and writes both JSON Schema and UI Schema files to disk.
+ *
+ * @public
+ */
+export declare function writeSchemas<E extends readonly FormElement[]>(form: FormSpec<E>, options: WriteSchemasOptions): WriteSchemasResult;
 
-export { WriteSchemasOptions }
+/**
+ * Options for writing schemas to disk.
+ *
+ * @public
+ */
+export declare interface WriteSchemasOptions extends GenerateJsonSchemaOptions {
+    /** Output directory for the schema files */
+    readonly outDir: string;
+    /** Base name for the output files (without extension). Defaults to "schema" */
+    readonly name?: string;
+    /** Number of spaces for JSON indentation. Defaults to 2 */
+    readonly indent?: number;
+}
 
-export { WriteSchemasResult }
+/**
+ * Result of writing schemas to disk.
+ *
+ * @public
+ */
+export declare interface WriteSchemasResult {
+    /** Path to the generated JSON Schema file */
+    readonly jsonSchemaPath: string;
+    /** Path to the generated UI Schema file */
+    readonly uiSchemaPath: string;
+}
 
 export { }