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

package/dist/constraints.d.ts

@@ -35,8 +35,81 @@
  * @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.
@@ -77,20 +150,9 @@ export declare interface ControlOptionConstraints {
     custom?: Record<string, Severity>;
 }
 
-/**
- * Default FormSpec configuration.
- *
- * @public
- */
-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).
- *
- * @public
- */
-export declare const DEFAULT_CONSTRAINTS: ResolvedConstraintConfig;
+/* Excluded from this release type: DEFAULT_CONSTRAINTS */
 
 /**
  * Creates a constraint configuration directly from an object.
@@ -117,22 +179,78 @@ export declare const DEFAULT_CONSTRAINTS: ResolvedConstraintConfig;
 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).
  *
- * @param field - A field object with potential options
- * @returns Array of present option names
+ * @typeParam N - The field name (string literal type)
+ * @typeParam Source - The data source key (from DataSourceRegistry)
  *
  * @public
  */
-export declare function extractFieldOptions(field: Record<string, unknown>): FieldOption[];
+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[];
+}
 
 /**
- * Known field options that can be validated.
+ * A field that loads its schema dynamically (e.g., from an extension).
+ *
+ * @typeParam N - The field name (string literal type)
  *
  * @public
  */
-export declare type FieldOption = "label" | "placeholder" | "required" | "minValue" | "maxValue" | "minItems" | "maxItems";
+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 {
+    /** Stored enum value written into submitted data. */
+    readonly id: string;
+    /** Human-readable label shown to end users. */
+    readonly label: string;
+}
+
+/**
+ * Valid enum option types: either plain strings or objects with id/label.
+ *
+ * @public
+ */
+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.
@@ -156,19 +274,7 @@ export declare interface FieldOptionConstraints {
     maxItems?: Severity;
 }
 
-/**
- * Context for field option validation.
- *
- * @public
- */
-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.
@@ -195,18 +301,25 @@ export declare interface FieldTypeConstraints {
     object?: Severity;
 }
 
+/* Excluded from this release type: FieldTypeContext */
+
 /**
- * Context for field type validation.
+ * Union of all form element types (fields and structural 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 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;
 }
 
 /**
@@ -230,72 +343,35 @@ export declare interface FormSpecValidationOptions {
     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
- *
- * @public
- */
-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
- *
- * @public
- */
-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
+ * Groups provide visual organization and can be rendered as fieldsets or sections.
  *
- * @public
- */
-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
+ * @typeParam Elements - Tuple of contained form elements
  *
  * @public
  */
-export declare function isFieldTypeAllowed(fieldType: string, constraints: FieldTypeConstraints): 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 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
- *
- * @public
- */
-export declare function isLayoutTypeAllowed(layoutType: "group" | "conditional", constraints: LayoutConstraints): boolean;
+/* Excluded from this release type: isFieldOptionAllowed */
 
-/**
- * Checks if a nesting depth is allowed.
- *
- * @param depth - Current nesting depth
- * @param constraints - Layout constraints
- * @returns true if allowed, false if exceeds limit
- *
- * @public
- */
-export declare function isNestingDepthAllowed(depth: number, constraints: LayoutConstraints): boolean;
+/* 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.
@@ -311,21 +387,7 @@ export declare interface LayoutConstraints {
     maxNestingDepth?: number;
 }
 
-/**
- * Context for layout validation.
- *
- * @public
- */
-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.
@@ -415,12 +477,58 @@ export declare interface LoadConfigResult {
     found: boolean;
 }
 
+/* Excluded from this release type: mergeWithDefaults */
+
+/**
+ * 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;
+}
+
 /**
- * Merges user constraints with defaults, filling in any missing values.
+ * 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 function mergeWithDefaults(config: ConstraintConfig | undefined): ResolvedConstraintConfig;
+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.
@@ -429,10 +537,15 @@ export declare function mergeWithDefaults(config: ConstraintConfig | undefined):
  * @public
  */
 export declare interface ResolvedConstraintConfig {
+    /** Effective field-builder policy after defaults and overrides are merged. */
     fieldTypes: Required<FieldTypeConstraints>;
+    /** Effective nesting and grouping policy after defaults are applied. */
     layout: Required<LayoutConstraints>;
+    /** Effective UI-schema policy after defaults and overrides are merged. */
     uiSchema: ResolvedUISchemaConstraints;
+    /** Effective policy for field-level builder options. */
     fieldOptions: Required<FieldOptionConstraints>;
+    /** Effective policy for renderer-specific control options. */
     controlOptions: Required<ControlOptionConstraints>;
 }
 
@@ -442,7 +555,9 @@ export declare interface ResolvedConstraintConfig {
  * @public
  */
 export declare interface ResolvedRuleConstraints {
+    /** Effective severity controlling whether UI schema rules are allowed. */
     enabled: Severity;
+    /** Effective severity for each supported JSON Forms rule effect. */
     effects: Required<RuleEffectConstraints>;
 }
 
@@ -452,7 +567,9 @@ export declare interface ResolvedRuleConstraints {
  * @public
  */
 export declare interface ResolvedUISchemaConstraints {
+    /** Effective severities for each supported JSON Forms layout type. */
     layouts: Required<LayoutTypeConstraints>;
+    /** Effective rule policy after defaults have been applied. */
     rules: ResolvedRuleConstraints;
 }
 
@@ -495,38 +612,79 @@ export declare interface RuleEffectConstraints {
 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.
- *
- * @param context - Information about the field being validated
- * @param constraints - Field type constraints
- * @returns Array of validation issues (empty if valid)
+ * UI Schema feature constraints - control JSONForms-specific features.
  *
  * @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.
@@ -578,16 +736,7 @@ export declare function validateFormSpec(formSpec: FormSpec<readonly FormElement
  */
 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)
- *
- * @public
- */
-export declare function validateLayout(context: LayoutContext, constraints: LayoutConstraints): ValidationIssue[];
+/* Excluded from this release type: validateLayout */
 
 /**
  * A single validation issue found during constraint checking.

package/dist/defaults.d.ts

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