@formspec/constraints 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/constraints-beta.d.ts

@@ -0,0 +1,914 @@
+/**
+ * \@formspec/constraints
+ *
+ * Constraint validation for FormSpec - restrict features based on target
+ * environment capabilities.
+ *
+ * This package provides:
+ * - Type definitions for constraint configuration
+ * - YAML/TypeScript config file loading
+ * - Core validation logic for FormSpec elements
+ * - JSON Schema for .formspec.yml validation
+ *
+ * @example
+ * ```ts
+ * import { loadConfig, validateFormSpecElements } from '@formspec/constraints';
+ * import { formspec, field } from '@formspec/dsl';
+ *
+ * // Load constraints from .formspec.yml
+ * const { config } = await loadConfig();
+ *
+ * // Create a form
+ * const form = formspec(
+ *   field.text("name"),
+ *   field.dynamicEnum("country", "countries"),
+ * );
+ *
+ * // Validate against constraints
+ * const result = validateFormSpecElements(form.elements, { constraints: config });
+ *
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.issues);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * 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[]>;
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Complete constraint configuration for a FormSpec project.
+ *
+ * @public
+ */
+export declare interface ConstraintConfig {
+    /** Field type constraints */
+    fieldTypes?: FieldTypeConstraints;
+    /** Layout and structure constraints */
+    layout?: LayoutConstraints;
+    /** UI Schema feature constraints */
+    uiSchema?: UISchemaConstraints;
+    /** Field configuration option constraints */
+    fieldOptions?: FieldOptionConstraints;
+    /** Control options constraints */
+    controlOptions?: ControlOptionConstraints;
+}
+
+/**
+ * Control options constraints - control which JSONForms Control.options are allowed.
+ * These are renderer-specific options that may not be universally supported.
+ *
+ * @public
+ */
+export declare interface ControlOptionConstraints {
+    /** format - renderer format hint (e.g., "radio", "textarea") */
+    format?: Severity;
+    /** readonly - read-only mode */
+    readonly?: Severity;
+    /** multi - multi-select for enums */
+    multi?: Severity;
+    /** showUnfocusedDescription - show description when unfocused */
+    showUnfocusedDescription?: Severity;
+    /** hideRequiredAsterisk - hide required indicator */
+    hideRequiredAsterisk?: Severity;
+    /** Custom control options (extensible dictionary) */
+    custom?: Record<string, Severity>;
+}
+
+/**
+ * Default FormSpec configuration.
+ *
+ * @beta
+ */
+export declare const DEFAULT_CONFIG: FormSpecConfig;
+
+/**
+ * Default constraint configuration that allows all features.
+ * All constraints default to "off" (allowed).
+ *
+ * @beta
+ */
+export declare const DEFAULT_CONSTRAINTS: ResolvedConstraintConfig;
+
+/**
+ * Creates a constraint configuration directly from an object.
+ * Useful for programmatic configuration without YAML.
+ *
+ * @param config - Partial constraint configuration
+ * @returns Complete configuration with defaults applied
+ *
+ * @example
+ * ```ts
+ * const config = defineConstraints({
+ *   fieldTypes: {
+ *     dynamicEnum: 'error',
+ *     dynamicSchema: 'error',
+ *   },
+ *   layout: {
+ *     group: 'error',
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function defineConstraints(config: ConstraintConfig): ResolvedConstraintConfig;
+
+/**
+ * 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[];
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Valid enum option types: either plain strings or objects with id/label.
+ *
+ * @public
+ */
+export declare type EnumOptionValue = string | EnumOption;
+
+/**
+ * Extracts which options are present on a field object.
+ * Works with FormSpec field types.
+ *
+ * @param field - A field object with potential options
+ * @returns Array of present option names
+ *
+ * @beta
+ */
+export declare function extractFieldOptions(field: Record<string, unknown>): FieldOption[];
+
+/**
+ * Known field options that can be validated.
+ *
+ * @beta
+ */
+export declare type FieldOption = "label" | "placeholder" | "required" | "minValue" | "maxValue" | "minItems" | "maxItems";
+
+/**
+ * Field configuration option constraints - control which field options are allowed.
+ *
+ * @public
+ */
+export declare interface FieldOptionConstraints {
+    /** label - field label text */
+    label?: Severity;
+    /** placeholder - input placeholder text */
+    placeholder?: Severity;
+    /** required - whether field is required */
+    required?: Severity;
+    /** minValue - minimum value for numbers */
+    minValue?: Severity;
+    /** maxValue - maximum value for numbers */
+    maxValue?: Severity;
+    /** minItems - minimum array length */
+    minItems?: Severity;
+    /** maxItems - maximum array length */
+    maxItems?: Severity;
+}
+
+/**
+ * Context for field option validation.
+ *
+ * @beta
+ */
+export declare interface FieldOptionsContext {
+    /** The field name */
+    fieldName: string;
+    /** Which options are present on this field */
+    presentOptions: FieldOption[];
+    /** Path to this field */
+    path?: string;
+}
+
+/**
+ * Field type constraints - control which field types are allowed.
+ * Fine-grained control over each DSL field builder.
+ *
+ * @public
+ */
+export declare interface FieldTypeConstraints {
+    /** field.text() - basic text input */
+    text?: Severity;
+    /** field.number() - numeric input */
+    number?: Severity;
+    /** field.boolean() - checkbox/toggle */
+    boolean?: Severity;
+    /** field.enum() with literal options */
+    staticEnum?: Severity;
+    /** field.dynamicEnum() - runtime-fetched options */
+    dynamicEnum?: Severity;
+    /** field.dynamicSchema() - runtime-fetched schema */
+    dynamicSchema?: Severity;
+    /** field.array() / field.arrayWithConfig() */
+    array?: Severity;
+    /** field.object() / field.objectWithConfig() */
+    object?: Severity;
+}
+
+/**
+ * Context for field type validation.
+ *
+ * @beta
+ */
+export declare interface FieldTypeContext {
+    /** The _field discriminator value (e.g., "text", "number", "enum") */
+    fieldType: string;
+    /** The field name */
+    fieldName: string;
+    /** Optional path for nested fields */
+    path?: string;
+}
+
+/**
+ * Union of all form element types (fields and structural elements).
+ *
+ * @public
+ */
+export declare type FormElement = AnyField | Group<readonly FormElement[]> | Conditional<string, unknown, readonly FormElement[]>;
+
+/**
+ * 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;
+}
+
+/**
+ * Top-level FormSpec configuration file structure.
+ * The .formspec.yml file uses this structure.
+ *
+ * @public
+ */
+export declare interface FormSpecConfig {
+    /** Constraint configuration */
+    constraints?: ConstraintConfig;
+}
+
+/**
+ * Options for validating FormSpec elements.
+ *
+ * @public
+ */
+export declare interface FormSpecValidationOptions {
+    /** Constraint configuration (will be merged with defaults) */
+    constraints?: ConstraintConfig;
+}
+
+/**
+ * Gets the severity level for a field option.
+ *
+ * @param option - The option to check
+ * @param constraints - Field option constraints
+ * @returns Severity level, or "off" if not constrained
+ *
+ * @beta
+ */
+export declare function getFieldOptionSeverity(option: FieldOption, constraints: FieldOptionConstraints): Severity;
+
+/**
+ * Gets the severity level for a field type.
+ *
+ * @param fieldType - The _field discriminator value
+ * @param constraints - Field type constraints
+ * @returns Severity level, or "off" if not constrained
+ *
+ * @beta
+ */
+export declare function getFieldTypeSeverity(fieldType: string, constraints: FieldTypeConstraints): Severity;
+
+/**
+ * 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;
+}
+
+/**
+ * Checks if a specific field option is allowed.
+ *
+ * @param option - The option to check
+ * @param constraints - Field option constraints
+ * @returns true if allowed, false if disallowed
+ *
+ * @beta
+ */
+export declare function isFieldOptionAllowed(option: FieldOption, constraints: FieldOptionConstraints): boolean;
+
+/**
+ * Checks if a field type is allowed by the constraints.
+ * Useful for quick checks without generating issues.
+ *
+ * @param fieldType - The _field discriminator value
+ * @param constraints - Field type constraints
+ * @returns true if allowed, false if disallowed
+ *
+ * @beta
+ */
+export declare function isFieldTypeAllowed(fieldType: string, constraints: FieldTypeConstraints): boolean;
+
+/**
+ * Checks if a layout type is allowed by the constraints.
+ *
+ * @param layoutType - The type of layout element
+ * @param constraints - Layout constraints
+ * @returns true if allowed, false if disallowed
+ *
+ * @beta
+ */
+export declare function isLayoutTypeAllowed(layoutType: "group" | "conditional", constraints: LayoutConstraints): boolean;
+
+/**
+ * Checks if a nesting depth is allowed.
+ *
+ * @param depth - Current nesting depth
+ * @param constraints - Layout constraints
+ * @returns true if allowed, false if exceeds limit
+ *
+ * @beta
+ */
+export declare function isNestingDepthAllowed(depth: number, constraints: LayoutConstraints): boolean;
+
+/**
+ * Layout and structure constraints - control grouping, conditionals, nesting.
+ *
+ * @public
+ */
+export declare interface LayoutConstraints {
+    /** group() - visual grouping of fields */
+    group?: Severity;
+    /** when() - conditional field visibility */
+    conditionals?: Severity;
+    /** Maximum nesting depth for objects/arrays (0 = flat only) */
+    maxNestingDepth?: number;
+}
+
+/**
+ * Context for layout validation.
+ *
+ * @beta
+ */
+export declare interface LayoutContext {
+    /** The type of layout element ("group" | "conditional") */
+    layoutType: "group" | "conditional";
+    /** Optional label for the element (for groups) */
+    label?: string;
+    /** Current nesting depth */
+    depth: number;
+    /** Path to this element */
+    path?: string;
+}
+
+/**
+ * JSONForms layout type constraints.
+ *
+ * @public
+ */
+export declare interface LayoutTypeConstraints {
+    /** VerticalLayout - stack elements vertically */
+    VerticalLayout?: Severity;
+    /** HorizontalLayout - arrange elements horizontally */
+    HorizontalLayout?: Severity;
+    /** Group - visual grouping with label */
+    Group?: Severity;
+    /** Categorization - tabbed/wizard interface */
+    Categorization?: Severity;
+    /** Category - individual tab/step in Categorization */
+    Category?: Severity;
+}
+
+/**
+ * Loads FormSpec constraint configuration from a .formspec.yml file.
+ *
+ * @param options - Options for loading configuration
+ * @returns The loaded configuration with defaults applied
+ *
+ * @example
+ * ```ts
+ * // Load from current directory (searches for .formspec.yml)
+ * const result = await loadConfig();
+ *
+ * // Load from specific directory
+ * const result = await loadConfig({ cwd: '/path/to/project' });
+ *
+ * // Load from specific file
+ * const result = await loadConfig({ configPath: '/path/to/config.yml' });
+ * ```
+ *
+ * @public
+ */
+export declare function loadConfig(options?: LoadConfigOptions): Promise<LoadConfigResult>;
+
+/**
+ * Synchronously loads config from a pre-parsed YAML string.
+ * Useful for testing or when config is already available.
+ *
+ * @param yamlContent - The YAML content to parse
+ * @returns The parsed and merged configuration
+ *
+ * @public
+ */
+export declare function loadConfigFromString(yamlContent: string): ResolvedConstraintConfig;
+
+/**
+ * Options for loading configuration.
+ *
+ * @public
+ */
+export declare interface LoadConfigOptions {
+    /**
+     * The directory to search for config files.
+     * Defaults to process.cwd().
+     */
+    cwd?: string;
+    /**
+     * Explicit path to a config file.
+     * If provided, skips searching for default config file names.
+     */
+    configPath?: string;
+    /**
+     * Whether to search parent directories for config files.
+     * Defaults to true.
+     */
+    searchParents?: boolean;
+}
+
+/**
+ * Result of loading configuration.
+ *
+ * @public
+ */
+export declare interface LoadConfigResult {
+    /** The loaded and merged configuration */
+    config: ResolvedConstraintConfig;
+    /** The path to the config file that was loaded (if any) */
+    configPath: string | null;
+    /** Whether a config file was found */
+    found: boolean;
+}
+
+/**
+ * Merges user constraints with defaults, filling in any missing values.
+ *
+ * @beta
+ */
+export declare function mergeWithDefaults(config: ConstraintConfig | undefined): ResolvedConstraintConfig;
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Fully resolved constraint configuration with all properties required.
+ * This is the type returned by mergeWithDefaults().
+ *
+ * @public
+ */
+export declare interface ResolvedConstraintConfig {
+    fieldTypes: Required<FieldTypeConstraints>;
+    layout: Required<LayoutConstraints>;
+    uiSchema: ResolvedUISchemaConstraints;
+    fieldOptions: Required<FieldOptionConstraints>;
+    controlOptions: Required<ControlOptionConstraints>;
+}
+
+/**
+ * Fully resolved rule constraints with all properties required.
+ *
+ * @public
+ */
+export declare interface ResolvedRuleConstraints {
+    enabled: Severity;
+    effects: Required<RuleEffectConstraints>;
+}
+
+/**
+ * Fully resolved UI schema constraints with all properties required.
+ *
+ * @public
+ */
+export declare interface ResolvedUISchemaConstraints {
+    layouts: Required<LayoutTypeConstraints>;
+    rules: ResolvedRuleConstraints;
+}
+
+/**
+ * JSONForms rule constraints.
+ *
+ * @public
+ */
+export declare interface RuleConstraints {
+    /** Whether rules are enabled at all */
+    enabled?: Severity;
+    /** Fine-grained control over rule effects */
+    effects?: RuleEffectConstraints;
+}
+
+/**
+ * JSONForms rule effect constraints.
+ *
+ * @public
+ */
+export declare interface RuleEffectConstraints {
+    /** SHOW - show element when condition is true */
+    SHOW?: Severity;
+    /** HIDE - hide element when condition is true */
+    HIDE?: Severity;
+    /** ENABLE - enable element when condition is true */
+    ENABLE?: Severity;
+    /** DISABLE - disable element when condition is true */
+    DISABLE?: Severity;
+}
+
+/**
+ * Severity level for constraint violations.
+ * - "error": Violation fails validation
+ * - "warn": Violation emits warning but passes
+ * - "off": Feature is allowed (no violation)
+ *
+ * @public
+ */
+export declare type Severity = "error" | "warn" | "off";
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * UI Schema feature constraints - control JSONForms-specific features.
+ *
+ * @public
+ */
+export declare interface UISchemaConstraints {
+    /** Layout type constraints */
+    layouts?: LayoutTypeConstraints;
+    /** Rule (conditional) constraints */
+    rules?: RuleConstraints;
+}
+
+/**
+ * Validates field options against constraints.
+ *
+ * @param context - Information about the field and its options
+ * @param constraints - Field option constraints
+ * @returns Array of validation issues (empty if valid)
+ *
+ * @beta
+ */
+export declare function validateFieldOptions(context: FieldOptionsContext, constraints: FieldOptionConstraints): ValidationIssue[];
+
+/**
+ * Validates a field type against constraints.
+ *
+ * @param context - Information about the field being validated
+ * @param constraints - Field type constraints
+ * @returns Array of validation issues (empty if valid)
+ *
+ * @beta
+ */
+export declare function validateFieldTypes(context: FieldTypeContext, constraints: FieldTypeConstraints): ValidationIssue[];
+
+/**
+ * Validates a complete FormSpec against constraints.
+ *
+ * @param formSpec - The FormSpec to validate
+ * @param options - Validation options including constraints
+ * @returns Validation result with all issues found
+ *
+ * @public
+ */
+export declare function validateFormSpec(formSpec: FormSpec<readonly FormElement[]>, options?: FormSpecValidationOptions): ValidationResult;
+
+/**
+ * Validates FormSpec elements against constraints.
+ *
+ * This is the main entry point for validating a form specification
+ * against a constraint configuration. It walks through all elements
+ * and checks each one against the configured constraints.
+ *
+ * @param elements - FormSpec elements to validate
+ * @param options - Validation options including constraints
+ * @returns Validation result with all issues found
+ *
+ * @example
+ * ```ts
+ * import { formspec, field, group } from '@formspec/dsl';
+ * import { validateFormSpecElements, defineConstraints } from '@formspec/constraints';
+ *
+ * const form = formspec(
+ *   group("Contact",
+ *     field.text("name"),
+ *     field.dynamicEnum("country", "countries"),
+ *   ),
+ * );
+ *
+ * const result = validateFormSpecElements(form.elements, {
+ *   constraints: {
+ *     fieldTypes: { dynamicEnum: 'error' },
+ *     layout: { group: 'error' },
+ *   },
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.issues);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function validateFormSpecElements(elements: readonly FormElement[], options?: FormSpecValidationOptions): ValidationResult;
+
+/**
+ * Validates a layout element against constraints.
+ *
+ * @param context - Information about the layout element
+ * @param constraints - Layout constraints
+ * @returns Array of validation issues (empty if valid)
+ *
+ * @beta
+ */
+export declare function validateLayout(context: LayoutContext, constraints: LayoutConstraints): ValidationIssue[];
+
+/**
+ * A single validation issue found during constraint checking.
+ *
+ * @public
+ */
+export declare interface ValidationIssue {
+    /** Unique code identifying the issue type */
+    code: string;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Severity level of this issue */
+    severity: "error" | "warning";
+    /** Which constraint category this issue belongs to */
+    category: "fieldTypes" | "layout" | "uiSchema" | "fieldOptions" | "controlOptions";
+    /** JSON pointer or field path to the issue location */
+    path?: string;
+    /** Name of the affected field (if applicable) */
+    fieldName?: string;
+    /** Type of the affected field (if applicable) */
+    fieldType?: string;
+}
+
+/**
+ * Result of validating a FormSpec or schema against constraints.
+ *
+ * @public
+ */
+export declare interface ValidationResult {
+    /** Whether validation passed (no errors, warnings OK) */
+    valid: boolean;
+    /** List of all issues found */
+    issues: ValidationIssue[];
+}
+
+export { }