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

package/dist/constraints.d.ts

@@ -35,11 +35,86 @@
  * @packageDocumentation
  */
 
-import type { FormElement } from '@formspec/core';
-import type { FormSpec } from '@formspec/core';
+/**
+ * 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 */
@@ -57,6 +132,8 @@ export declare interface ConstraintConfig {
 /**
  * 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") */
@@ -73,16 +150,9 @@ export declare interface ControlOptionConstraints {
     custom?: Record<string, Severity>;
 }
 
-/**
- * Default FormSpec configuration.
- */
-export declare const DEFAULT_CONFIG: FormSpecConfig;
+/* Excluded from this release type: DEFAULT_CONFIG */
 
-/**
- * Default constraint configuration that allows all features.
- * All constraints default to "off" (allowed).
- */
-export declare const DEFAULT_CONSTRAINTS: ResolvedConstraintConfig;
+/* Excluded from this release type: DEFAULT_CONSTRAINTS */
 
 /**
  * Creates a constraint configuration directly from an object.
@@ -103,25 +173,87 @@ export declare const DEFAULT_CONSTRAINTS: ResolvedConstraintConfig;
  *   },
  * });
  * ```
+ *
+ * @public
  */
 export declare function defineConstraints(config: ConstraintConfig): ResolvedConstraintConfig;
 
 /**
- * Extracts which options are present on a field object.
- * Works with FormSpec field types.
+ * 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).
  *
- * @param field - A field object with potential options
- * @returns Array of present option names
+ * @public
  */
-export declare function extractFieldOptions(field: Record<string, unknown>): FieldOption[];
+export declare interface EnumOption {
+    readonly id: string;
+    readonly label: string;
+}
 
 /**
- * Known field options that can be validated.
+ * Valid enum option types: either plain strings or objects with id/label.
+ *
+ * @public
  */
-export declare type FieldOption = "label" | "placeholder" | "required" | "minValue" | "maxValue" | "minItems" | "maxItems";
+export declare type EnumOptionValue = string | EnumOption;
+
+/* Excluded from this release type: extractFieldOptions */
+
+/* Excluded from this release type: FieldOption */
 
 /**
  * Field configuration option constraints - control which field options are allowed.
+ *
+ * @public
  */
 export declare interface FieldOptionConstraints {
     /** label - field label text */
@@ -140,21 +272,13 @@ export declare interface FieldOptionConstraints {
     maxItems?: Severity;
 }
 
-/**
- * Context for field option validation.
- */
-export declare interface FieldOptionsContext {
-    /** The field name */
-    fieldName: string;
-    /** Which options are present on this field */
-    presentOptions: FieldOption[];
-    /** Path to this field */
-    path?: string;
-}
+/* Excluded from this release type: FieldOptionsContext */
 
 /**
  * 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 */
@@ -175,21 +299,32 @@ export declare interface FieldTypeConstraints {
     object?: Severity;
 }
 
+/* Excluded from this release type: FieldTypeContext */
+
+/**
+ * Union of all form element types (fields and structural elements).
+ *
+ * @public
+ */
+export declare type FormElement = AnyField | Group<readonly FormElement[]> | Conditional<string, unknown, readonly FormElement[]>;
+
 /**
- * Context for field type validation.
+ * A complete form specification.
+ *
+ * @typeParam Elements - Tuple of top-level form elements
+ *
+ * @public
  */
-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;
+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 */
@@ -198,69 +333,48 @@ export declare interface FormSpecConfig {
 
 /**
  * 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
- */
-export declare function getFieldOptionSeverity(option: FieldOption, constraints: FieldOptionConstraints): Severity;
+/* Excluded from this release type: getFieldOptionSeverity */
 
-/**
- * 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
- */
-export declare function getFieldTypeSeverity(fieldType: string, constraints: FieldTypeConstraints): Severity;
+/* Excluded from this release type: getFieldTypeSeverity */
 
 /**
- * Checks if a specific field option is allowed.
+ * A visual grouping of form elements.
  *
- * @param option - The option to check
- * @param constraints - Field option constraints
- * @returns true if allowed, false if disallowed
- */
-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.
+ * Groups provide visual organization and can be rendered as fieldsets or sections.
  *
- * @param fieldType - The _field discriminator value
- * @param constraints - Field type constraints
- * @returns true if allowed, false if disallowed
- */
-export declare function isFieldTypeAllowed(fieldType: string, constraints: FieldTypeConstraints): boolean;
-
-/**
- * Checks if a layout type is allowed by the constraints.
+ * @typeParam Elements - Tuple of contained form elements
  *
- * @param layoutType - The type of layout element
- * @param constraints - Layout constraints
- * @returns true if allowed, false if disallowed
+ * @public
  */
-export declare function isLayoutTypeAllowed(layoutType: "group" | "conditional", constraints: LayoutConstraints): boolean;
+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 nesting depth is allowed.
- *
- * @param depth - Current nesting depth
- * @param constraints - Layout constraints
- * @returns true if allowed, false if exceeds limit
- */
-export declare function isNestingDepthAllowed(depth: number, constraints: LayoutConstraints): boolean;
+/* Excluded from this release type: isFieldOptionAllowed */
+
+/* Excluded from this release type: isFieldTypeAllowed */
+
+/* Excluded from this release type: isLayoutTypeAllowed */
+
+/* Excluded from this release type: isNestingDepthAllowed */
 
 /**
  * Layout and structure constraints - control grouping, conditionals, nesting.
+ *
+ * @public
  */
 export declare interface LayoutConstraints {
     /** group() - visual grouping of fields */
@@ -271,22 +385,12 @@ export declare interface LayoutConstraints {
     maxNestingDepth?: number;
 }
 
-/**
- * Context for layout validation.
- */
-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;
-}
+/* Excluded from this release type: LayoutContext */
 
 /**
  * JSONForms layout type constraints.
+ *
+ * @public
  */
 export declare interface LayoutTypeConstraints {
     /** VerticalLayout - stack elements vertically */
@@ -318,6 +422,8 @@ export declare interface LayoutTypeConstraints {
  * // Load from specific file
  * const result = await loadConfig({ configPath: '/path/to/config.yml' });
  * ```
+ *
+ * @public
  */
 export declare function loadConfig(options?: LoadConfigOptions): Promise<LoadConfigResult>;
 
@@ -327,11 +433,15 @@ export declare function loadConfig(options?: LoadConfigOptions): Promise<LoadCon
  *
  * @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 {
     /**
@@ -353,6 +463,8 @@ export declare interface LoadConfigOptions {
 
 /**
  * Result of loading configuration.
+ *
+ * @public
  */
 export declare interface LoadConfigResult {
     /** The loaded and merged configuration */
@@ -363,14 +475,64 @@ export declare interface LoadConfigResult {
     found: boolean;
 }
 
+/* Excluded from this release type: mergeWithDefaults */
+
 /**
- * Merges user constraints with defaults, filling in any missing values.
+ * A numeric input field.
+ *
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
  */
-export declare function mergeWithDefaults(config: ConstraintConfig | undefined): ResolvedConstraintConfig;
+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>;
@@ -382,6 +544,8 @@ export declare interface ResolvedConstraintConfig {
 
 /**
  * Fully resolved rule constraints with all properties required.
+ *
+ * @public
  */
 export declare interface ResolvedRuleConstraints {
     enabled: Severity;
@@ -390,6 +554,8 @@ export declare interface ResolvedRuleConstraints {
 
 /**
  * Fully resolved UI schema constraints with all properties required.
+ *
+ * @public
  */
 export declare interface ResolvedUISchemaConstraints {
     layouts: Required<LayoutTypeConstraints>;
@@ -398,6 +564,8 @@ export declare interface ResolvedUISchemaConstraints {
 
 /**
  * JSONForms rule constraints.
+ *
+ * @public
  */
 export declare interface RuleConstraints {
     /** Whether rules are enabled at all */
@@ -408,6 +576,8 @@ export declare interface RuleConstraints {
 
 /**
  * JSONForms rule effect constraints.
+ *
+ * @public
  */
 export declare interface RuleEffectConstraints {
     /** SHOW - show element when condition is true */
@@ -425,36 +595,85 @@ export declare interface RuleEffectConstraints {
  * - "error": Violation fails validation
  * - "warn": Violation emits warning but passes
  * - "off": Feature is allowed (no violation)
+ *
+ * @public
  */
 export declare type Severity = "error" | "warn" | "off";
 
 /**
- * UI Schema feature constraints - control JSONForms-specific features.
+ * 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 UISchemaConstraints {
-    /** Layout type constraints */
-    layouts?: LayoutTypeConstraints;
-    /** Rule (conditional) constraints */
-    rules?: RuleConstraints;
+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;
 }
 
 /**
- * Validates field options against constraints.
+ * 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.
  *
- * @param context - Information about the field and its options
- * @param constraints - Field option constraints
- * @returns Array of validation issues (empty if valid)
+ * @typeParam N - The field name (string literal type)
+ *
+ * @public
  */
-export declare function validateFieldOptions(context: FieldOptionsContext, constraints: FieldOptionConstraints): ValidationIssue[];
+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;
+}
 
 /**
- * Validates a field type against constraints.
+ * UI Schema feature constraints - control JSONForms-specific features.
  *
- * @param context - Information about the field being validated
- * @param constraints - Field type constraints
- * @returns Array of validation issues (empty if valid)
+ * @public
  */
-export declare function validateFieldTypes(context: FieldTypeContext, constraints: FieldTypeConstraints): ValidationIssue[];
+export declare interface UISchemaConstraints {
+    /** Layout type constraints */
+    layouts?: LayoutTypeConstraints;
+    /** Rule (conditional) constraints */
+    rules?: RuleConstraints;
+}
+
+/* Excluded from this release type: validateFieldOptions */
+
+/* Excluded from this release type: validateFieldTypes */
 
 /**
  * Validates a complete FormSpec against constraints.
@@ -462,6 +681,8 @@ export declare function validateFieldTypes(context: FieldTypeContext, constraint
  * @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;
 
@@ -499,20 +720,17 @@ export declare function validateFormSpec(formSpec: FormSpec<readonly FormElement
  *   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)
- */
-export declare function validateLayout(context: LayoutContext, constraints: LayoutConstraints): ValidationIssue[];
+/* Excluded from this release type: validateLayout */
 
 /**
  * A single validation issue found during constraint checking.
+ *
+ * @public
  */
 export declare interface ValidationIssue {
     /** Unique code identifying the issue type */
@@ -533,6 +751,8 @@ export declare interface ValidationIssue {
 
 /**
  * Result of validating a FormSpec or schema against constraints.
+ *
+ * @public
  */
 export declare interface ValidationResult {
     /** Whether validation passed (no errors, warnings OK) */

package/dist/defaults.d.ts

@@ -2,14 +2,20 @@ import type { ConstraintConfig, FormSpecConfig, ResolvedConstraintConfig } from
 /**
  * Default constraint configuration that allows all features.
  * All constraints default to "off" (allowed).
+ *
+ * @beta
  */
 export declare const DEFAULT_CONSTRAINTS: ResolvedConstraintConfig;
 /**
  * Default FormSpec configuration.
+ *
+ * @beta
  */
 export declare const DEFAULT_CONFIG: FormSpecConfig;
 /**
  * Merges user constraints with defaults, filling in any missing values.
+ *
+ * @beta
  */
 export declare function mergeWithDefaults(config: ConstraintConfig | undefined): ResolvedConstraintConfig;
 //# sourceMappingURL=defaults.d.ts.map