@theredhead/lucid-forms 0.1.0

package/types/theredhead-lucid-forms.d.ts

@@ -0,0 +1,1138 @@
+import * as _angular_core from '@angular/core';
+import { WritableSignal, Signal, Type, InjectionToken, EnvironmentProviders } from '@angular/core';
+import { TextAdapter, SelectOption } from '@theredhead/lucid-kit';
+import * as i1 from '@theredhead/lucid-foundation';
+
+/**
+ * Operators available for field/group conditions.
+ *
+ * These compare the **live** value of a referenced field against
+ * a target value to determine visibility or enabled state.
+ */
+type ConditionOperator = "equals" | "notEquals" | "contains" | "notContains" | "empty" | "notEmpty" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual" | "in" | "notIn";
+/**
+ * A single condition that controls whether a field or group is
+ * visible / enabled, based on the live value of another field.
+ *
+ * Conditions are JSON-serializable so a form schema can be stored
+ * as pure JSON and restored later.
+ *
+ * @example
+ * ```json
+ * { "field": "country", "operator": "equals", "value": "NL" }
+ * ```
+ */
+interface FieldCondition {
+    /** ID of the field whose value is evaluated. */
+    readonly field: string;
+    /** Comparison operator. */
+    readonly operator: ConditionOperator;
+    /**
+     * Target value to compare against. Omitted for unary operators
+     * like `"empty"` and `"notEmpty"`.
+     */
+    readonly value?: unknown;
+}
+/**
+ * Logical combination of multiple conditions.
+ *
+ * When `mode` is `"every"` (default), **all** conditions must pass.
+ * When `mode` is `"some"`, **at least one** must pass.
+ */
+interface ConditionGroup {
+    /** How to combine the conditions. Defaults to `"every"`. */
+    readonly mode?: "every" | "some";
+    /** The individual conditions to evaluate. */
+    readonly conditions: readonly FieldCondition[];
+}
+/**
+ * Either a single condition or a group of conditions.
+ * Used for both visibility and enabled state.
+ */
+type Condition = FieldCondition | ConditionGroup;
+/**
+ * Check whether a `Condition` is a `ConditionGroup` (has nested
+ * `conditions` array) rather than a single `FieldCondition`.
+ */
+declare function isConditionGroup(c: Condition): c is ConditionGroup;
+
+/**
+ * Built-in validation rule identifiers.
+ *
+ * The form engine ships validators for each of these. Custom
+ * validators can extend this set via the `"custom"` type.
+ */
+type ValidationRuleType = "required" | "minLength" | "maxLength" | "min" | "max" | "pattern" | "email" | "custom";
+/**
+ * A single validation rule, JSON-serializable.
+ *
+ * @example
+ * ```json
+ * { "type": "required", "message": "This field is required." }
+ * { "type": "minLength", "params": { "min": 3 }, "message": "At least 3 characters." }
+ * { "type": "pattern", "params": { "pattern": "^[A-Z]" }, "message": "Must start with uppercase." }
+ * ```
+ */
+interface ValidationRule {
+    /** The validator to apply. */
+    readonly type: ValidationRuleType;
+    /**
+     * Additional parameters for the validator. The shape depends on
+     * the `type`:
+     *
+     * | Type        | Params                        |
+     * |-------------|-------------------------------|
+     * | required    | —                             |
+     * | minLength   | `{ min: number }`             |
+     * | maxLength   | `{ max: number }`             |
+     * | min         | `{ min: number }`             |
+     * | max         | `{ max: number }`             |
+     * | pattern     | `{ pattern: string }`         |
+     * | email       | —                             |
+     * | custom      | `{ validatorId: string, … }`  |
+     */
+    readonly params?: Readonly<Record<string, unknown>>;
+    /** Human-readable error message shown when the rule fails. */
+    readonly message?: string;
+}
+/**
+ * A single validation error produced by the validation engine.
+ */
+interface ValidationError {
+    /** The rule type that failed. */
+    readonly type: string;
+    /** Human-readable error message. */
+    readonly message: string;
+}
+/**
+ * Complete validation result for a single field.
+ */
+interface ValidationResult {
+    /** Whether all rules passed. */
+    readonly valid: boolean;
+    /** Errors for every failed rule (empty when valid). */
+    readonly errors: readonly ValidationError[];
+}
+
+/**
+ * An option for select / radio / autocomplete fields.
+ *
+ * @example
+ * ```json
+ * { "label": "Netherlands", "value": "NL" }
+ * ```
+ */
+interface FormFieldOption {
+    readonly label: string;
+    readonly value: unknown;
+    /** Whether the option is disabled. */
+    readonly disabled?: boolean;
+}
+/**
+ * Definition of a single form field. Fully JSON-serializable.
+ *
+ * The `component` key is resolved at runtime through the
+ * {@link FormFieldRegistry} to an actual Angular component that
+ * exposes a two-way `value` (or mapped model) signal.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "email",
+ *   "title": "E-mail address",
+ *   "component": "text",
+ *   "config": { "type": "email", "placeholder": "you@example.com" },
+ *   "validation": [
+ *     { "type": "required", "message": "E-mail is required." },
+ *     { "type": "email", "message": "Enter a valid e-mail address." }
+ *   ]
+ * }
+ * ```
+ */
+interface FormFieldDefinition {
+    /** Unique ID — used as the key in the form values object. */
+    readonly id: string;
+    /** Human-readable label shown above the field. */
+    readonly title: string;
+    /** Optional helper text shown below the field. */
+    readonly description?: string;
+    /**
+     * Registry key that maps to an Angular component.
+     *
+     * Built-in keys: `"text"`, `"select"`, `"checkbox"`, `"toggle"`,
+     * `"radio"`, `"autocomplete"`, `"date"`, `"time"`, `"datetime"`,
+     * `"color"`, `"slider"`, `"richtext"`, `"file"`.
+     */
+    readonly component: string;
+    /**
+     * Arbitrary key–value config forwarded as inputs to the
+     * resolved component. Keys must match the component's `input()`
+     * signal names.
+     */
+    readonly config?: Readonly<Record<string, unknown>>;
+    /**
+     * Options for select, radio, and autocomplete fields.
+     * Passed to the component's `options` or equivalent input.
+     */
+    readonly options?: readonly FormFieldOption[];
+    /** Validation rules evaluated by the form engine. */
+    readonly validation?: readonly ValidationRule[];
+    /**
+     * When set, the field is only visible if the condition is met.
+     * Hidden fields are excluded from the output JSON.
+     */
+    readonly visibleWhen?: Condition;
+    /**
+     * When set, the field is disabled (non-interactive) unless the
+     * condition is met.
+     */
+    readonly enabledWhen?: Condition;
+    /** Default value used when the form is first created. */
+    readonly defaultValue?: unknown;
+}
+/**
+ * A named group of fields. Rendered as a fieldset / section, or
+ * as a single step in wizard mode.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "personal",
+ *   "title": "Personal information",
+ *   "fields": [
+ *     { "id": "firstName", "title": "First name", "component": "text" },
+ *     { "id": "lastName",  "title": "Last name",  "component": "text" }
+ *   ]
+ * }
+ * ```
+ */
+interface FormGroupDefinition {
+    /** Unique ID for the group. */
+    readonly id: string;
+    /** Group heading. */
+    readonly title?: string;
+    /** Optional description shown below the heading. */
+    readonly description?: string;
+    /** Ordered list of fields in this group. */
+    readonly fields: readonly FormFieldDefinition[];
+    /** Condition controlling group visibility. */
+    readonly visibleWhen?: Condition;
+    /** Condition controlling group enabled state. */
+    readonly enabledWhen?: Condition;
+}
+/**
+ * Top-level form schema. This is the JSON document that fully
+ * describes a form — its structure, fields, validation, and
+ * conditional logic.
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "contact",
+ *   "title": "Contact form",
+ *   "groups": [
+ *     {
+ *       "id": "main",
+ *       "title": "Your details",
+ *       "fields": [
+ *         { "id": "name", "title": "Name", "component": "text" },
+ *         { "id": "email", "title": "E-mail", "component": "text",
+ *           "config": { "type": "email" } }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+interface FormSchema {
+    /** Unique form identifier. */
+    readonly id: string;
+    /** Form title (rendered as a heading). */
+    readonly title?: string;
+    /** Optional description shown below the title. */
+    readonly description?: string;
+    /** Ordered list of field groups. */
+    readonly groups: readonly FormGroupDefinition[];
+}
+/**
+ * The plain-object output produced by the form engine.
+ *
+ * Keys are field IDs, values are the current field values.
+ * Only visible fields are included.
+ */
+type FormValues = Record<string, unknown>;
+/**
+ * Known flair component keys. Flair items are purely presentational
+ * elements that do not collect user input.
+ */
+declare const FLAIR_COMPONENTS: readonly ["flair:richtext", "flair:image", "flair:media"];
+/** A flair component key. */
+type FlairComponent = (typeof FLAIR_COMPONENTS)[number];
+/**
+ * Returns `true` if the given component key is a flair (non-data)
+ * component.
+ */
+declare function isFlairComponent(component: string): component is FlairComponent;
+
+/**
+ * Signature for a custom validator function.
+ *
+ * Returns `null` when valid, or a `ValidationError` on failure.
+ */
+type ValidatorFn = (value: unknown, params: Readonly<Record<string, unknown>>) => ValidationError | null;
+/**
+ * Register a custom validator that can be referenced by
+ * `{ type: "custom", params: { validatorId: "myId" } }` in a
+ * form schema.
+ */
+declare function registerCustomValidator(id: string, fn: ValidatorFn): void;
+/**
+ * Validate a value against an array of rules and return a
+ * {@link ValidationResult}.
+ */
+declare function validate(rules: readonly ValidationRule[], value: unknown): ValidationResult;
+
+/**
+ * Evaluate a {@link Condition} (single or group) against the
+ * current form values.
+ *
+ * @returns `true` when the condition is satisfied.
+ */
+declare function evaluateCondition(condition: Condition, values: FormValues): boolean;
+
+/**
+ * Runtime state for a single field managed by the form engine.
+ */
+interface FieldState {
+    /** The field definition from the schema. */
+    readonly definition: FormFieldDefinition;
+    /** Current value (writable signal). */
+    readonly value: WritableSignal<unknown>;
+    /** Whether the field is currently visible. */
+    readonly visible: Signal<boolean>;
+    /** Whether the field is currently enabled (interactive). */
+    readonly enabled: Signal<boolean>;
+    /** Live validation result. */
+    readonly validation: Signal<ValidationResult>;
+    /** Whether the field has been interacted with. */
+    readonly touched: WritableSignal<boolean>;
+    /** Whether the field has been changed from its default. */
+    readonly dirty: Signal<boolean>;
+}
+/**
+ * Runtime state for a field group.
+ */
+interface GroupState {
+    /** The group definition from the schema. */
+    readonly definition: FormGroupDefinition;
+    /** Runtime states for every field in this group. */
+    readonly fields: readonly FieldState[];
+    /** Whether the group is currently visible. */
+    readonly visible: Signal<boolean>;
+    /** Whether the group is currently enabled. */
+    readonly enabled: Signal<boolean>;
+    /** Whether every visible field in the group is valid. */
+    readonly valid: Signal<boolean>;
+}
+/**
+ * Signal-based form engine. Takes a {@link FormSchema}, creates
+ * reactive state for every field and group, evaluates conditions,
+ * runs validation, and produces a JSON output object.
+ *
+ * The engine is framework-agnostic (no Angular DI required) — it
+ * operates purely on signals and plain objects.
+ *
+ * @example
+ * ```ts
+ * const engine = new FormEngine(schema);
+ * engine.setValue("email", "test@example.com");
+ * console.log(engine.values());   // { email: "test@example.com", … }
+ * console.log(engine.valid());    // true / false
+ * ```
+ */
+declare class FormEngine {
+    readonly schema: FormSchema;
+    /** All field states indexed by field ID. */
+    private readonly fieldMap;
+    /** Ordered group states. */
+    readonly groups: readonly GroupState[];
+    /** Live snapshot of all field values (including hidden fields). */
+    readonly values: Signal<FormValues>;
+    /** Whether every visible field passes validation. */
+    readonly valid: Signal<boolean>;
+    /** Whether any field has been interacted with. */
+    readonly touched: Signal<boolean>;
+    /** Whether any field value differs from its default. */
+    readonly dirty: Signal<boolean>;
+    constructor(schema: FormSchema);
+    /**
+     * Get the {@link FieldState} for a field by ID.
+     * Throws if the field is not found.
+     */
+    getField(id: string): FieldState;
+    /** Set the value of a single field by ID. */
+    setValue(id: string, value: unknown): void;
+    /** Mark a field as touched. */
+    markTouched(id: string): void;
+    /** Mark all fields as touched (e.g. on submit attempt). */
+    markAllTouched(): void;
+    /**
+     * Reset the form to its initial default values and clear
+     * touched/dirty state.
+     */
+    reset(): void;
+    /**
+     * Produce the JSON output — a plain object containing only
+     * **visible** field values.
+     */
+    output(): Signal<FormValues>;
+    private buildGroupState;
+    private buildFieldState;
+    /**
+     * Read all current field values reactively. When called inside a
+     * `computed()`, it tracks every field's value signal so the
+     * computed re-evaluates whenever any field changes.
+     */
+    private readFieldValues;
+    /**
+     * Produce a sensible default value for a given component type so
+     * fields without explicit `defaultValue` still have a typed zero.
+     */
+    private defaultForComponent;
+}
+
+/**
+ * Transforms a raw config value (typically a JSON-serializable string
+ * or number) into the runtime value expected by the component input.
+ *
+ * Used by {@link FormFieldRegistration.configTransforms} to bridge
+ * JSON-friendly config keys to complex runtime objects.
+ */
+interface ConfigTransform {
+    /** The actual component input name to set. */
+    readonly inputKey: string;
+    /** Convert the raw config value to the runtime input value. */
+    readonly transform: (value: unknown) => unknown;
+}
+/**
+ * Describes how a component is integrated into the form system.
+ */
+interface FormFieldRegistration {
+    /**
+     * The Angular component class to instantiate.
+     * Must be a standalone component.
+     */
+    readonly component: Type<unknown>;
+    /**
+     * Name of the model signal used for two-way value binding.
+     *
+     * Most ui-kit components use `"value"`. Exceptions:
+     * - `UICheckbox` → `"checked"`
+     * - `UIFileUpload` → `"files"`
+     */
+    readonly modelProperty: string;
+    /**
+     * Static inputs to apply by default (e.g. `{ type: "email" }`).
+     * Merged with (overridden by) the field definition's `config`.
+     */
+    readonly defaultConfig?: Readonly<Record<string, unknown>>;
+    /**
+     * Optional map from config keys to {@link ConfigTransform} entries.
+     *
+     * When a config key appears in this map, the raw JSON value is
+     * passed through the transform and set on the component input
+     * specified by `inputKey` instead of the config key itself.
+     *
+     * @example
+     * ```ts
+     * configTransforms: {
+     *   textAdapter: {
+     *     inputKey: 'adapter',
+     *     transform: (key) => resolveTextAdapter(key as string),
+     *   },
+     * }
+     * ```
+     */
+    readonly configTransforms?: Readonly<Record<string, ConfigTransform>>;
+}
+/**
+ * Multi-provider token that collects field registrations from
+ * across the application.
+ */
+declare const FORM_FIELD_REGISTRATIONS: InjectionToken<ReadonlyMap<string, FormFieldRegistration>>;
+/**
+ * Register one or more field types for use in form schemas.
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * import { provideFormFields } from '@theredhead/lucid-forms';
+ * import { UIInput, UISelect, UICheckbox } from '@theredhead/lucid-kit';
+ *
+ * export const appConfig = {
+ *   providers: [
+ *     provideFormFields({
+ *       text:     { component: UIInput,    modelProperty: 'value' },
+ *       select:   { component: UISelect,   modelProperty: 'value' },
+ *       checkbox: { component: UICheckbox, modelProperty: 'checked' },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+declare function provideFormFields(fields: Readonly<Record<string, FormFieldRegistration>>): EnvironmentProviders;
+/**
+ * Injectable service that resolves a component key (e.g. `"text"`)
+ * to a {@link FormFieldRegistration}.
+ *
+ * It merges all maps provided via `FORM_FIELD_REGISTRATIONS`.
+ */
+declare class FormFieldRegistry {
+    private readonly maps;
+    private merged;
+    private getMerged;
+    /** Resolve a component key to its registration, or `null`. */
+    resolve(key: string): FormFieldRegistration | null;
+    /** All registered keys. */
+    keys(): string[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FormFieldRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<FormFieldRegistry>;
+}
+
+/**
+ * Built-in field registrations that map common component keys
+ * to `@theredhead/lucid-kit` components.
+ *
+ * | Key             | Component           | Model property |
+ * |-----------------|---------------------|----------------|
+ * | `"text"`        | `UIInput`           | `value`        |
+ * | `"select"`      | `UIDropdownList`    | `value`        |
+ * | `"checkbox"`    | `UICheckbox`        | `checked`      |
+ * | `"toggle"`      | `UIToggle`          | `value`        |
+ * | `"radio"`       | `UIRadioGroup`      | `value`        |
+ * | `"autocomplete"`| `UIAutocomplete`    | `value`        |
+ * | `"date"`        | `UIInput` + `DateInputAdapter`  | `value` |
+ * | `"time"`        | `UIInput` + `TimeTextAdapter`   | `value` |
+ * | `"datetime"`    | `UIInput` + `DateInputAdapter`  | `value` |
+ * | `"color"`       | `UIColorPicker`     | `value`        |
+ * | `"slider"`      | `UISlider`          | `value`        |
+ * | `"richtext"`    | `UIRichTextEditor`  | `value`        |
+ * | `"file"`        | `UIFileUpload`      | `files`        |
+ * | `"flair:richtext"` | `UIRichTextView`   | `content`       |
+ * | `"flair:image"` | `UIImage`           | `src`          |
+ * | `"flair:media"` | `UIMediaPlayer`     | `source`       |
+ */
+declare const BUILT_IN_FIELDS: Readonly<Record<string, FormFieldRegistration>>;
+/**
+ * Convenience provider that registers all built-in
+ * `@theredhead/lucid-kit` field types.
+ *
+ * @example
+ * ```ts
+ * import { provideBuiltInFormFields } from '@theredhead/lucid-forms';
+ *
+ * export const appConfig = {
+ *   providers: [provideBuiltInFormFields()],
+ * };
+ * ```
+ */
+declare function provideBuiltInFormFields(): EnvironmentProviders;
+
+/**
+ * All available text adapter keys, in display order.
+ */
+declare const TEXT_ADAPTER_KEYS: readonly string[];
+/**
+ * Resolve a text adapter key to a {@link TextAdapter} instance.
+ *
+ * Returns `undefined` for empty/unknown keys.
+ *
+ * @param key Adapter key (e.g. `"email"`, `"phone"`, `"money"`).
+ */
+declare function resolveTextAdapter(key: unknown): TextAdapter | undefined;
+
+/**
+ * The result of an export operation.
+ *
+ * Contains the generated content as a string together with metadata
+ * about the suggested file name and MIME type.
+ */
+interface ExportResult {
+    /** MIME type for the exported content (e.g. `"application/json"`, `"text/typescript"`). */
+    readonly mimeType: string;
+    /** Suggested file name for the exported artefact. */
+    readonly fileName: string;
+    /** The exported content as a string. */
+    readonly content: string;
+}
+/**
+ * Strategy interface for exporting a {@link FormSchema} into a
+ * specific format.
+ *
+ * Implementations must be plain classes — no Angular DI required.
+ *
+ * @example
+ * ```ts
+ * class MyExportStrategy implements ExportStrategy {
+ *   readonly label = 'My Format';
+ *   readonly description = 'Export as My Format.';
+ *
+ *   export(schema: FormSchema): ExportResult {
+ *     return {
+ *       mimeType: 'text/plain',
+ *       fileName: 'form.txt',
+ *       content: JSON.stringify(schema),
+ *     };
+ *   }
+ * }
+ * ```
+ */
+interface ExportStrategy {
+    /** Human-readable label displayed in the export format selector. */
+    readonly label: string;
+    /** Short description of the export format. */
+    readonly description: string;
+    /** Generate an {@link ExportResult} from the given schema. */
+    export(schema: FormSchema): ExportResult;
+}
+
+/**
+ * Exports a {@link FormSchema} as a formatted JSON file.
+ *
+ * The output is a standard JSON document — identical to
+ * `JSON.stringify(schema, null, 2)`.
+ */
+declare class JsonExportStrategy implements ExportStrategy {
+    readonly label = "JSON Schema";
+    readonly description = "Export the form schema as a JSON file.";
+    export(schema: FormSchema): ExportResult;
+}
+
+/**
+ * Exports a {@link FormSchema} as a standalone Angular component
+ * with a fully declarative HTML template.
+ *
+ * The generated `.component.ts` file contains:
+ *
+ * - A typed `<Title>FormValues` interface with one property per field
+ * - Individual `signal()` fields for two-way binding
+ * - A `computed()` `formValues` signal that assembles the full typed object
+ * - A template that directly uses `@theredhead/lucid-kit` components
+ *   (`<ui-input>`, `<ui-select>`, …) — no `FormEngine` or `<ui-form>`
+ *
+ * The component is almost entirely declarative: the TypeScript class
+ * is just signals and a single computed.
+ */
+declare class AngularComponentExportStrategy implements ExportStrategy {
+    readonly label = "Angular Component";
+    readonly description = "Standalone Angular component with declarative template.";
+    export(schema: FormSchema): ExportResult;
+    /** @internal Build the import statements. */
+    private buildImports;
+    /** @internal Build the values interface. */
+    private buildInterface;
+    /** @internal Build the full @Component class. */
+    private buildComponent;
+    /** @internal Build the HTML template with fieldsets and components. */
+    private buildTemplate;
+    /** @internal Build the class body: signals, options, computed. */
+    private buildClassBody;
+}
+
+/**
+ * Renders a single form field by dynamically creating the component
+ * registered for the field's `component` key and wiring up two-way
+ * value binding, config inputs, and validation display.
+ *
+ * This component is used internally by {@link UIFormGroup} and
+ * {@link UIForm}. It can also be used standalone for custom layouts.
+ *
+ * @example
+ * ```html
+ * <ui-form-field [state]="fieldState" />
+ * ```
+ */
+declare class UIFormField {
+    /** The field state managed by the {@link FormEngine}. */
+    readonly state: _angular_core.InputSignal<FieldState>;
+    private readonly registry;
+    private readonly log;
+    private readonly outlet;
+    /** @internal Show errors only when the field has been touched. */
+    protected readonly showErrors: _angular_core.Signal<boolean>;
+    /** @internal Whether this field is a flair (non-data) component. */
+    protected readonly isFlair: _angular_core.Signal<boolean>;
+    /** @internal Whether the field has a `required` validation rule. */
+    protected readonly isRequired: _angular_core.Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<UIFormField, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UIFormField, "ui-form-field", never, { "state": { "alias": "state"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.UISurface; inputs: { "surfaceType": "surfaceType"; }; outputs: {}; }]>;
+}
+
+/**
+ * Renders a group of form fields as a visual section (fieldset).
+ *
+ * In sequential (non-wizard) mode every group is displayed
+ * vertically. In wizard mode, {@link UIFormWizard} controls which
+ * group is visible.
+ *
+ * @example
+ * ```html
+ * <ui-form-group [state]="groupState" />
+ * ```
+ */
+declare class UIFormGroup {
+    /** The group state managed by the {@link FormEngine}. */
+    readonly state: _angular_core.InputSignal<GroupState>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<UIFormGroup, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UIFormGroup, "ui-form-group", never, { "state": { "alias": "state"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.UISurface; inputs: { "surfaceType": "surfaceType"; }; outputs: {}; }]>;
+}
+
+/**
+ * Top-level form component that renders all groups sequentially.
+ *
+ * Takes a {@link FormEngine} instance and displays every group's
+ * fields in order, with validation and conditional visibility.
+ *
+ * @example
+ * ```html
+ * <ui-form [engine]="engine" (formSubmit)="onSubmit($event)" />
+ * ```
+ */
+declare class UIForm {
+    /** The form engine instance that drives this form. */
+    readonly engine: _angular_core.InputSignal<FormEngine>;
+    /** Label for the submit button. Defaults to `"Submit"`. */
+    readonly submitLabel: _angular_core.InputSignal<string>;
+    /** Whether to show the built-in submit button. Defaults to `true`. */
+    readonly showSubmit: _angular_core.InputSignal<boolean>;
+    /** Minimum width (in pixels) for form field controls. Defaults to `200`. */
+    readonly fieldMinWidth: _angular_core.InputSignal<number>;
+    /** Emitted when the submit button is clicked and the form is valid. */
+    readonly formSubmit: _angular_core.OutputEmitterRef<FormValues>;
+    /** @internal */
+    protected readonly isValid: _angular_core.Signal<boolean>;
+    /** @internal — collects all invalid visible fields for the summary. */
+    protected readonly validationSummary: _angular_core.Signal<{
+        fieldId: string;
+        title: string;
+        errors: string[];
+    }[]>;
+    /** @internal */
+    protected onSubmit(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<UIForm, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UIForm, "ui-form", never, { "engine": { "alias": "engine"; "required": true; "isSignal": true; }; "submitLabel": { "alias": "submitLabel"; "required": false; "isSignal": true; }; "showSubmit": { "alias": "showSubmit"; "required": false; "isSignal": true; }; "fieldMinWidth": { "alias": "fieldMinWidth"; "required": false; "isSignal": true; }; }, { "formSubmit": "formSubmit"; }, never, never, true, [{ directive: typeof i1.UISurface; inputs: { "surfaceType": "surfaceType"; }; outputs: {}; }]>;
+}
+
+/**
+ * Renders a {@link FormEngine}'s groups as wizard steps — one group
+ * at a time with previous / next / submit navigation.
+ *
+ * Only visible groups are included as steps. The wizard validates
+ * the current step before allowing navigation to the next.
+ *
+ * @example
+ * ```html
+ * <ui-form-wizard
+ *   [engine]="engine"
+ *   (formSubmit)="onSubmit($event)"
+ * />
+ * ```
+ */
+declare class UIFormWizard {
+    /** The form engine instance that drives this wizard. */
+    readonly engine: _angular_core.InputSignal<FormEngine>;
+    /** Label for the "Next" button. */
+    readonly nextLabel: _angular_core.InputSignal<string>;
+    /** Label for the "Previous" button. */
+    readonly prevLabel: _angular_core.InputSignal<string>;
+    /** Label for the "Submit" button (last step). */
+    readonly submitLabel: _angular_core.InputSignal<string>;
+    /** Minimum width (in pixels) for form field controls. Defaults to `200`. */
+    readonly fieldMinWidth: _angular_core.InputSignal<number>;
+    /** Emitted when the form is submitted (last step, valid). */
+    readonly formSubmit: _angular_core.OutputEmitterRef<FormValues>;
+    /** Current step index. */
+    protected readonly currentIndex: _angular_core.WritableSignal<number>;
+    /** Only visible groups are wizard steps. */
+    protected readonly visibleGroups: _angular_core.Signal<GroupState[]>;
+    /** The currently displayed group state. */
+    protected readonly currentGroup: _angular_core.Signal<GroupState | null>;
+    /** Whether the current step is the last one. */
+    protected readonly isLastStep: _angular_core.Signal<boolean>;
+    /** Whether the current step's fields are all valid. */
+    protected readonly currentStepValid: _angular_core.Signal<boolean>;
+    /** Navigate to the next step (marks current fields touched). */
+    next(): void;
+    /** Navigate to the previous step. */
+    prev(): void;
+    /** Jump to a specific step. */
+    goTo(index: number): void;
+    /** @internal Submit handler. */
+    protected onSubmit(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<UIFormWizard, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UIFormWizard, "ui-form-wizard", never, { "engine": { "alias": "engine"; "required": true; "isSignal": true; }; "nextLabel": { "alias": "nextLabel"; "required": false; "isSignal": true; }; "prevLabel": { "alias": "prevLabel"; "required": false; "isSignal": true; }; "submitLabel": { "alias": "submitLabel"; "required": false; "isSignal": true; }; "fieldMinWidth": { "alias": "fieldMinWidth"; "required": false; "isSignal": true; }; }, { "formSubmit": "formSubmit"; }, never, never, true, [{ directive: typeof i1.UISurface; inputs: { "surfaceType": "surfaceType"; }; outputs: {}; }]>;
+}
+
+/**
+ * Mutable counterpart of {@link FormFieldDefinition} used
+ * exclusively inside the designer. Signal-driven so every
+ * property change is immediately reflected in the live preview
+ * and schema output.
+ */
+interface MutableFieldDefinition {
+    readonly uid: string;
+    readonly id: WritableSignal<string>;
+    readonly title: WritableSignal<string>;
+    readonly description: WritableSignal<string>;
+    readonly component: WritableSignal<string>;
+    readonly config: WritableSignal<Record<string, unknown>>;
+    readonly options: WritableSignal<FormFieldOption[]>;
+    readonly validation: WritableSignal<ValidationRule[]>;
+    readonly visibleWhen: WritableSignal<Condition | null>;
+    readonly enabledWhen: WritableSignal<Condition | null>;
+    readonly defaultValue: WritableSignal<unknown>;
+}
+/**
+ * Mutable counterpart of {@link FormGroupDefinition}.
+ */
+interface MutableGroupDefinition {
+    readonly uid: string;
+    readonly id: WritableSignal<string>;
+    readonly title: WritableSignal<string>;
+    readonly description: WritableSignal<string>;
+    readonly fields: WritableSignal<MutableFieldDefinition[]>;
+    readonly visibleWhen: WritableSignal<Condition | null>;
+    readonly enabledWhen: WritableSignal<Condition | null>;
+}
+/** What kind of item is currently selected in the designer. */
+type DesignerSelectionKind = "field" | "group" | "form";
+/**
+ * Describes the currently selected item in the designer canvas.
+ */
+interface DesignerSelection {
+    readonly kind: DesignerSelectionKind;
+    readonly groupUid: string | null;
+    readonly fieldUid: string | null;
+}
+/**
+ * Signal-based engine that maintains the mutable designer state
+ * and produces a readonly {@link FormSchema} snapshot on demand.
+ *
+ * All mutations go through public methods so the UI stays in sync
+ * via Angular's signal-based change detection.
+ *
+ * @example
+ * ```ts
+ * const engine = new FormDesignerEngine();
+ * engine.addGroup();
+ * engine.addField(engine.groups()[0].uid, 'text');
+ * const schema = engine.schema();
+ * ```
+ */
+declare class FormDesignerEngine {
+    /** Form ID. */
+    readonly formId: WritableSignal<string>;
+    /** Form title. */
+    readonly formTitle: WritableSignal<string>;
+    /** Form description. */
+    readonly formDescription: WritableSignal<string>;
+    /** Ordered list of mutable group definitions. */
+    readonly groups: WritableSignal<MutableGroupDefinition[]>;
+    /** Currently selected item in the canvas. */
+    readonly selection: WritableSignal<DesignerSelection | null>;
+    /** The currently selected mutable field (convenience). */
+    readonly selectedField: Signal<MutableFieldDefinition | null>;
+    /** The currently selected mutable group (convenience). */
+    readonly selectedGroup: Signal<MutableGroupDefinition | null>;
+    /**
+     * Produces a readonly {@link FormSchema} snapshot from the current
+     * mutable state. Fully JSON-serializable.
+     */
+    readonly schema: Signal<FormSchema>;
+    /** Add a new empty group at the end. Returns the new group's uid. */
+    addGroup(): string;
+    /** Remove a group by uid. Clears selection if it pointed at the group. */
+    removeGroup(uid: string): void;
+    /** Move a group to a new index. */
+    moveGroup(uid: string, newIndex: number): void;
+    /**
+     * Add a new field to a group. Returns the new field's uid.
+     *
+     * @param groupUid — Target group
+     * @param component — Field component key (e.g. `"text"`, `"select"`)
+     * @param atIndex — Optional insertion index (appends if omitted)
+     */
+    addField(groupUid: string, component: string, atIndex?: number): string;
+    /** Remove a field by uid from its containing group. */
+    removeField(groupUid: string, fieldUid: string): void;
+    /** Move a field to a new position within its group, or to another group. */
+    moveField(sourceGroupUid: string, fieldUid: string, targetGroupUid: string, targetIndex: number): void;
+    /** Duplicate a field within its group (inserted right after the original). */
+    duplicateField(groupUid: string, fieldUid: string): string | null;
+    /** Select a field for editing in the inspector. */
+    selectField(groupUid: string, fieldUid: string): void;
+    /** Select a group for editing in the inspector. */
+    selectGroup(groupUid: string): void;
+    /** Select the form-level properties for editing. */
+    selectForm(): void;
+    /** Clear the selection. */
+    clearSelection(): void;
+    /**
+     * Load an existing {@link FormSchema} into the designer,
+     * replacing all current state.
+     */
+    loadSchema(schema: FormSchema): void;
+    /**
+     * Produce a pretty-printed JSON string of the current schema.
+     */
+    toJSON(): string;
+    private createMutableField;
+    private createMutableGroup;
+    private buildSchema;
+    /**
+     * Generate a sensible default label from a component key.
+     */
+    private labelForComponent;
+}
+
+/**
+ * Metadata for a draggable field type shown in the palette.
+ */
+interface PaletteFieldType {
+    /** Registry component key (e.g. `"text"`, `"select"`). */
+    readonly key: string;
+    /** Display label. */
+    readonly label: string;
+    /** Short description shown on hover. */
+    readonly description: string;
+    /** SVG icon content from the `UIIcons` registry. */
+    readonly icon: string;
+}
+/**
+ * Palette sidebar that lists available field types. Clicking or
+ * dragging a type emits the component key so the parent can add
+ * it to the canvas.
+ *
+ * @example
+ * ```html
+ * <ui-field-palette (fieldRequested)="onAddField($event)" />
+ * ```
+ */
+declare class UIFieldPalette {
+    /** Emitted when the user clicks a field type to add it. */
+    readonly fieldRequested: _angular_core.OutputEmitterRef<string>;
+    /** @internal Available field types. */
+    protected readonly fieldTypes: readonly PaletteFieldType[];
+    /** @internal Available flair types. */
+    protected readonly flairTypes: readonly PaletteFieldType[];
+    /** @internal */
+    protected onDragStart(event: DragEvent, key: string): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<UIFieldPalette, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UIFieldPalette, "ui-field-palette", never, {}, { "fieldRequested": "fieldRequested"; }, never, never, true, [{ directive: typeof i1.UISurface; inputs: { "surfaceType": "surfaceType"; }; outputs: {}; }]>;
+}
+
+/**
+ * The central canvas of the form designer. Displays all groups
+ * and their fields as interactive cards that can be selected,
+ * reordered, and deleted.
+ *
+ * @example
+ * ```html
+ * <ui-designer-canvas [engine]="engine" />
+ * ```
+ */
+declare class UIDesignerCanvas {
+    /** The designer engine driving this canvas. */
+    readonly engine: _angular_core.InputSignal<FormDesignerEngine>;
+    /** Emitted when "Add field" is clicked on a group (passes group uid). */
+    readonly addFieldRequest: _angular_core.OutputEmitterRef<string>;
+    /** @internal Icon references exposed to the template. */
+    protected readonly icons: {
+        readonly ChevronUp: "<path d=\"m18 15-6-6-6 6\" />";
+        readonly ChevronDown: "<path d=\"m6 9 6 6 6-6\" />";
+        readonly Copy: "<rect width=\"14\" height=\"14\" x=\"8\" y=\"8\" rx=\"2\" ry=\"2\" /><path d=\"M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2\" />";
+        readonly X: "<path d=\"M18 6 6 18\" /><path d=\"m6 6 12 12\" />";
+    };
+    /** @internal Whether a component key is a flair type. */
+    protected readonly isFlair: typeof isFlairComponent;
+    /** @internal */
+    protected moveGroupUp(event: Event, uid: string, index: number): void;
+    /** @internal */
+    protected moveGroupDown(event: Event, uid: string, index: number): void;
+    /** @internal */
+    protected removeGroup(event: Event, uid: string): void;
+    /** @internal */
+    protected moveFieldUp(event: Event, groupUid: string, fieldUid: string, index: number): void;
+    /** @internal */
+    protected moveFieldDown(event: Event, groupUid: string, fieldUid: string, index: number): void;
+    /** @internal */
+    protected duplicateField(event: Event, groupUid: string, fieldUid: string): void;
+    /** @internal */
+    protected removeField(event: Event, groupUid: string, fieldUid: string): void;
+    /** @internal */
+    protected onDragOver(event: DragEvent): void;
+    /** @internal */
+    protected onDropField(event: DragEvent, group: MutableGroupDefinition): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<UIDesignerCanvas, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UIDesignerCanvas, "ui-designer-canvas", never, { "engine": { "alias": "engine"; "required": true; "isSignal": true; }; }, { "addFieldRequest": "addFieldRequest"; }, never, never, true, [{ directive: typeof i1.UISurface; inputs: { "surfaceType": "surfaceType"; }; outputs: {}; }]>;
+}
+
+/**
+ * Describes a single config property that the property inspector
+ * renders as a structured form control.
+ */
+interface ConfigPropertySchema {
+    /** The config key name (e.g. `"type"`, `"multiline"`). */
+    readonly key: string;
+    /** Human-readable label shown in the inspector. */
+    readonly label: string;
+    /** The editor to use. */
+    readonly editor: "text" | "number" | "boolean" | "select" | "richtext";
+    /**
+     * For `"select"` editors — the list of allowed values.
+     * Each entry is either a plain string (used as both label and value)
+     * or a `{ label, value }` pair.
+     */
+    readonly options?: readonly (string | {
+        label: string;
+        value: string;
+    })[];
+    /** Default value when the property is not set. */
+    readonly defaultValue?: unknown;
+    /** Optional short hint shown as placeholder text. */
+    readonly placeholder?: string;
+    /**
+     * When provided, the property is only shown in the inspector if this
+     * predicate returns `true` for the current config values.
+     */
+    readonly visibleWhen?: (config: Record<string, unknown>) => boolean;
+}
+
+/**
+ * Property inspector panel for editing the properties of the
+ * currently selected field, group, or form.
+ *
+ * @example
+ * ```html
+ * <ui-property-inspector [engine]="engine" />
+ * ```
+ */
+declare class UIPropertyInspector {
+    /** The designer engine driving this inspector. */
+    readonly engine: _angular_core.InputSignal<FormDesignerEngine>;
+    /** @internal */
+    protected readonly componentOptions: SelectOption[];
+    /** @internal */
+    protected readonly validationTypeOptions: SelectOption[];
+    /** @internal */
+    protected readonly configError: _angular_core.WritableSignal<string>;
+    /** @internal X icon for remove buttons. */
+    protected readonly iconX: "<path d=\"M18 6 6 18\" /><path d=\"m6 6 12 12\" />";
+    /** @internal Edit icon for the rich text button. */
+    protected readonly iconEdit: "<path d=\"M12 4v16\" /><path d=\"M4 7V5a1 1 0 0 1 1-1h14a1 1 0 0 1 1 1v2\" /><path d=\"M9 20h6\" />";
+    private readonly modalService;
+    /** @internal Extract input value from a DOM event. */
+    protected inputValue(event: Event): string;
+    /** @internal Whether the field type supports options. */
+    protected showOptions(field: MutableFieldDefinition): boolean;
+    /** @internal Whether the field is a flair (non-data) component. */
+    protected isFieldFlair(field: MutableFieldDefinition): boolean;
+    /** @internal */
+    protected addOption(field: MutableFieldDefinition): void;
+    /** @internal */
+    protected removeOption(field: MutableFieldDefinition, index: number): void;
+    /** @internal */
+    protected updateOption(field: MutableFieldDefinition, index: number, key: "label" | "value", value: string): void;
+    /** @internal */
+    protected addValidationRule(field: MutableFieldDefinition): void;
+    /** @internal */
+    protected removeValidationRule(field: MutableFieldDefinition, index: number): void;
+    /** @internal */
+    protected updateValidationRule(field: MutableFieldDefinition, index: number, key: string, value: string): void;
+    /** @internal */
+    protected ruleHasParam(type: string): boolean;
+    /** @internal */
+    protected paramPlaceholder(type: string): string;
+    /** @internal */
+    protected ruleParamValue(rule: ValidationRule): string;
+    /** @internal */
+    protected updateValidationParam(field: MutableFieldDefinition, index: number, type: string, value: string): void;
+    /** @internal Returns the config property schemas for the field's component. */
+    protected configSchemaFor(field: MutableFieldDefinition): readonly ConfigPropertySchema[];
+    /** @internal Read a single config value. */
+    protected configValue(field: MutableFieldDefinition, key: string): unknown;
+    /** @internal Set a string config value (removes key if empty). */
+    protected setConfigValue(field: MutableFieldDefinition, key: string, value: string): void;
+    /** @internal Set a numeric config value (removes key if empty/NaN). */
+    protected setConfigNumber(field: MutableFieldDefinition, key: string, raw: string): void;
+    /** @internal Set a boolean config value. */
+    protected setConfigBoolean(field: MutableFieldDefinition, key: string, checked: boolean): void;
+    /** @internal Normalize select options to SelectOption[] with empty option. */
+    protected configSelectOptions(prop: ConfigPropertySchema): SelectOption[];
+    /** @internal Open a richtext editor dialog for the given config key. */
+    protected openRichTextEditor(field: MutableFieldDefinition, key: string): void;
+    /** @internal Whether the field has config keys not covered by the schema. */
+    protected hasExtraConfig(field: MutableFieldDefinition): boolean;
+    /** @internal JSON string of config keys NOT in the structured schema. */
+    protected extraConfigJSON(field: MutableFieldDefinition): string;
+    /** @internal Parse and merge extra config JSON back into the field. */
+    protected onExtraConfigChange(field: MutableFieldDefinition, event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<UIPropertyInspector, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UIPropertyInspector, "ui-property-inspector", never, { "engine": { "alias": "engine"; "required": true; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.UISurface; inputs: { "surfaceType": "surfaceType"; }; outputs: {}; }]>;
+}
+
+/**
+ * Full-featured form designer that lets users visually build
+ * a {@link FormSchema} via a palette + canvas + inspector layout.
+ *
+ * Includes a live preview panel that renders the designed form
+ * using {@link UIForm} and {@link FormEngine}.
+ *
+ * @example
+ * ```html
+ * <ui-form-designer
+ *   [schema]="existingSchema"
+ *   (schemaChange)="onSave($event)"
+ * />
+ * ```
+ */
+declare class UIFormDesigner {
+    /**
+     * Optional initial schema to load into the designer.
+     * When set, the designer engine imports it on init.
+     */
+    readonly schema: _angular_core.InputSignal<FormSchema | null>;
+    /** Emitted when the user clicks "Export" — always emits the raw schema. */
+    readonly schemaChange: _angular_core.OutputEmitterRef<FormSchema>;
+    /** @internal Icon SVG for the copy button. */
+    protected readonly copyIcon: "<rect width=\"14\" height=\"14\" x=\"8\" y=\"8\" rx=\"2\" ry=\"2\" /><path d=\"M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2\" />";
+    /** @internal Active tab: design, preview, or json. */
+    protected readonly activeTab: _angular_core.WritableSignal<"json" | "design" | "preview">;
+    /** @internal The designer engine instance. */
+    protected readonly designerEngine: FormDesignerEngine;
+    /**
+     * @internal Preview engine — rebuilt whenever the schema changes.
+     * Returns null if the schema has no groups/fields.
+     */
+    protected readonly previewEngine: _angular_core.Signal<FormEngine | null>;
+    /** @internal Live output from the preview engine. */
+    protected readonly previewOutput: _angular_core.Signal<FormValues | null>;
+    /** @internal The group uid to add a field to when palette is clicked. */
+    private lastGroupUid;
+    constructor();
+    /** @internal Handle palette field click — add to first or last-used group. */
+    protected onFieldRequested(componentKey: string): void;
+    /** @internal Handle "Add field" click within a specific group. */
+    protected onAddFieldToGroup(groupUid: string): void;
+    /** @internal Copy the current JSON schema to the clipboard. */
+    protected onCopyJson(): void;
+    /** @internal Show submitted values in a native dialog. */
+    protected onPreviewSubmit(values: FormValues): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<UIFormDesigner, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<UIFormDesigner, "ui-form-designer", never, { "schema": { "alias": "schema"; "required": false; "isSignal": true; }; }, { "schemaChange": "schemaChange"; }, never, never, true, [{ directive: typeof i1.UISurface; inputs: { "surfaceType": "surfaceType"; }; outputs: {}; }]>;
+}
+
+export { AngularComponentExportStrategy, BUILT_IN_FIELDS, FLAIR_COMPONENTS, FORM_FIELD_REGISTRATIONS, FormDesignerEngine, FormEngine, FormFieldRegistry, JsonExportStrategy, TEXT_ADAPTER_KEYS, UIDesignerCanvas, UIFieldPalette, UIForm, UIFormDesigner, UIFormField, UIFormGroup, UIFormWizard, UIPropertyInspector, evaluateCondition, isConditionGroup, isFlairComponent, provideBuiltInFormFields, provideFormFields, registerCustomValidator, resolveTextAdapter, validate };
+export type { Condition, ConditionGroup, ConditionOperator, ConfigTransform, DesignerSelection, DesignerSelectionKind, ExportResult, ExportStrategy, FieldCondition, FieldState, FlairComponent, FormFieldDefinition, FormFieldOption, FormFieldRegistration, FormGroupDefinition, FormSchema, FormValues, GroupState, MutableFieldDefinition, MutableGroupDefinition, PaletteFieldType, ValidationError, ValidationResult, ValidationRule, ValidationRuleType, ValidatorFn };
+//# sourceMappingURL=theredhead-lucid-forms.d.ts.map