@resistdesign/voltra 3.0.0-alpha.5 → 3.0.0-alpha.50

package/app/forms/Engine.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @packageDocumentation
+ *
+ * Core engine logic for managing form state.
+ */
+import type { TypeInfo } from "../../common/TypeParsing/TypeInfo";
+import { TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import { type FieldValueValidatorMap } from "../../common/TypeParsing/Validation";
+import type { FormController, FormValues } from "./types";
+/**
+ * Hook that derives form state and field controllers from type metadata.
+ *
+ * @param initialValues - Initial form values.
+ * @param typeInfo - Type metadata for the form.
+ * @param options - Optional behavior overrides.
+ * @returns Form controller with state, fields, and validation helpers.
+ */
+export declare const useFormEngine: (initialValues: FormValues | undefined, typeInfo: TypeInfo, options?: {
+    /** Operation to evaluate when deriving field state. */
+    operation?: TypeOperation;
+    /** Optional custom validators keyed by field name. */
+    customValidatorMap?: FieldValueValidatorMap;
+}) => FormController;

package/app/forms/UI.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @packageDocumentation
+ *
+ * Shared AutoForm UI components driven by renderer suites.
+ */
+import type { ReactElement } from "react";
+import { FC } from "react";
+import type { TypeInfo, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import type { AutoFieldProps, CustomTypeActionPayload, CustomValidatorMap, FormController, FormValues, RelationActionPayload, TranslateValidationErrorCode } from "./types";
+import type { ResolvedSuite } from "./core/types";
+/**
+ * Renderer contract used by shared AutoForm components.
+ */
+export interface AutoFormRenderer {
+    /** Suite-backed field component for each field controller. */
+    AutoField: FC<AutoFieldProps>;
+    /** Resolved suite that provides primitives for container controls. */
+    suite: ResolvedSuite<ReactElement>;
+}
+/**
+ * Props for the shared AutoFormView component.
+ */
+export interface AutoFormViewProps {
+    /** Prepared controller that supplies field state. */
+    controller: FormController;
+    /** Submit handler invoked with validated form values. */
+    onSubmit: (values: FormValues) => void;
+    /** Renderer containing AutoField and suite primitives. */
+    renderer: AutoFormRenderer;
+    /** Disable the submit button when true. */
+    submitDisabled?: boolean;
+    /** Optional relation action handler for reference fields. */
+    onRelationAction?: (payload: RelationActionPayload) => void;
+    /** Optional custom type action handler. */
+    onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+    /** Optional translator for validation error descriptors. */
+    translateValidationErrorCode?: TranslateValidationErrorCode;
+}
+/**
+ * Render a form UI from a prepared form controller.
+ *
+ * @param props - View props including controller and callbacks.
+ * @returns Rendered form view.
+ */
+export declare const AutoFormView: FC<AutoFormViewProps>;
+/**
+ * Props for the shared AutoForm component.
+ */
+export interface AutoFormProps {
+    /** Type metadata used to build the form. */
+    typeInfo: TypeInfo;
+    /** Submit handler invoked with validated form values. */
+    onSubmit: (values: FormValues) => void;
+    /** Renderer containing AutoField and suite primitives. */
+    renderer: AutoFormRenderer;
+    /** Optional initial values applied before defaults. */
+    initialValues?: FormValues;
+    /** Optional change handler invoked when values update. */
+    onValuesChange?: (values: FormValues) => void;
+    /** Optional relation action handler for reference fields. */
+    onRelationAction?: (payload: RelationActionPayload) => void;
+    /** Optional custom type action handler. */
+    onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+    /** Optional operation override for field state. */
+    operation?: TypeOperation;
+    /** Disable the submit button when true. */
+    submitDisabled?: boolean;
+    /** Optional translator for validation error descriptors. */
+    translateValidationErrorCode?: TranslateValidationErrorCode;
+    /** Optional custom validators keyed by field name. */
+    customValidatorMap?: CustomValidatorMap;
+}
+/**
+ * Default translation from error descriptors to readable messages.
+ */
+export declare const defaultTranslateValidationErrorCode: TranslateValidationErrorCode;
+/**
+ * Build a controller from type metadata and render an auto form.
+ *
+ * @param props - Auto form props including type info and callbacks.
+ * @returns Rendered form bound to a new controller.
+ */
+export declare const AutoForm: FC<AutoFormProps>;

package/app/forms/core/createAutoField.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @packageDocumentation
+ *
+ * Factory for AutoField that delegates rendering to a resolved suite.
+ */
+import { type FC, type ReactElement } from "react";
+import type { TypeInfoField } from "../../../common/TypeParsing/TypeInfo";
+import { type ErrorDescriptor, type ArrayItemErrorMap } from "../../../common/TypeParsing/Validation";
+import type { CustomTypeActionPayload, FieldValue, RelationActionPayload, ResolvedSuite } from "./types";
+/**
+ * Input props for AutoField render delegation.
+ */
+export type AutoFieldInput = {
+    /** Type info describing the field to render. */
+    field: TypeInfoField;
+    /** Key that identifies the field in the form values. */
+    fieldKey: string;
+    /** Current value for the field. */
+    value: FieldValue | undefined;
+    /** Change handler for the field value. */
+    onChange: (value: FieldValue) => void;
+    /** Optional error descriptor to display under the field. */
+    error?: ErrorDescriptor;
+    /** Optional value-level errors for the field. */
+    errors?: ErrorDescriptor[];
+    /** Optional per-index errors for array fields. */
+    arrayItemErrorMap?: ArrayItemErrorMap;
+    /** Optional translator for validation error descriptors. */
+    translateValidationErrorCode?: (error: ErrorDescriptor) => string;
+    /** Disables the field UI when true. */
+    disabled?: boolean;
+    /** Optional callback for relation actions. */
+    onRelationAction?: (payload: RelationActionPayload) => void;
+    /** Optional callback for custom type actions. */
+    onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+};
+/**
+ * Create an AutoField renderer that delegates to a resolved suite.
+ *
+ * @param suite - Resolved component suite.
+ * @returns AutoField renderer function.
+ */
+export declare const createAutoField: <RenderOutput = ReactElement>(suite: ResolvedSuite<RenderOutput>) => FC<AutoFieldInput>;

package/app/forms/core/createFormRenderer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @packageDocumentation
+ *
+ * Factory for building form renderers backed by component suites.
+ */
+import type { ReactElement } from "react";
+import type { ResolvedSuite, ComponentSuite } from "./types";
+import { type AutoFieldInput } from "./createAutoField";
+/**
+ * Build form renderers backed by resolved component suites.
+ *
+ * @param options - Suite configuration.
+ * @returns Renderer helpers tied to resolved suites.
+ */
+export declare const createFormRenderer: <RenderOutput = ReactElement>(options: {
+    fallbackSuite: ComponentSuite<RenderOutput>;
+    suite?: ComponentSuite<RenderOutput>;
+}) => {
+    AutoField: import("react").FC<AutoFieldInput>;
+    suite: ResolvedSuite<RenderOutput>;
+};
+/**
+ * Props for AutoField produced by {@link createFormRenderer}.
+ */
+export type AutoFieldRendererProps = AutoFieldInput;

package/app/forms/core/getFieldKind.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @packageDocumentation
+ *
+ * Resolve the field kind used for renderer selection.
+ */
+import type { TypeInfoField } from "../../../common/TypeParsing/TypeInfo";
+import type { FieldKind } from "./types";
+/**
+ * Derive a {@link FieldKind} from type info metadata.
+ *
+ * @param field - Field metadata to evaluate.
+ * @returns Field kind for renderer selection.
+ */
+export declare const getFieldKind: (field: TypeInfoField) => FieldKind;

package/app/forms/core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @packageDocumentation
+ *
+ * Core, platform-agnostic form types and helpers.
+ */
+export * from "./types";
+export * from "./getFieldKind";
+export * from "./resolveSuite";
+export * from "./createAutoField";
+export * from "./createFormRenderer";
+export * from "./mergeSuites";

package/app/forms/core/mergeSuites.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @packageDocumentation
+ *
+ * Helpers for composing component suites.
+ */
+import type { ReactElement } from "react";
+import type { ComponentSuite, FieldKind, FieldRenderer } from "./types";
+/**
+ * Deep-merge component suites, allowing overrides for renderers and primitives.
+ *
+ * @param base - Base suite to extend.
+ * @param overrides - Partial suite overrides.
+ * @returns Merged suite.
+ */
+export declare const mergeSuites: <RenderOutput = ReactElement>(base: ComponentSuite<RenderOutput>, overrides: ComponentSuite<RenderOutput>) => ComponentSuite<RenderOutput>;
+/**
+ * Convenience helper to override a single renderer.
+ *
+ * @param kind - Field kind to override.
+ * @param renderer - Replacement renderer.
+ * @returns Suite with renderer override.
+ */
+export declare const withRendererOverride: <RenderOutput = ReactElement>(kind: FieldKind, renderer: FieldRenderer<RenderOutput>) => ComponentSuite<RenderOutput>;

package/app/forms/core/resolveSuite.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @packageDocumentation
+ *
+ * Resolve a component suite by merging overrides with fallback defaults.
+ */
+import type { ReactElement } from "react";
+import type { ComponentSuite, ResolvedSuite } from "./types";
+/**
+ * Merge a fallback suite with overrides and ensure completeness.
+ *
+ * @param overrides - Partial suite to apply on top of fallback.
+ * @param fallback - Default suite providing full coverage.
+ * @returns Fully resolved suite with all renderers present.
+ */
+export declare const resolveSuite: <RenderOutput = ReactElement>(overrides: ComponentSuite<RenderOutput> | undefined, fallback: ComponentSuite<RenderOutput>) => ResolvedSuite<RenderOutput>;

package/app/forms/core/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @packageDocumentation
+ *
+ * Core, platform-agnostic types for form rendering.
+ */
+import type { ComponentType, ReactElement } from "react";
+import type { LiteralValue, TypeInfoDataItem, TypeInfoField } from "../../../common/TypeParsing/TypeInfo";
+import type { ArrayItemErrorMap, ErrorDescriptor } from "../../../common/TypeParsing/Validation";
+import type { ItemRelationshipInfoType } from "../../../common/ItemRelationshipInfoTypes";
+/**
+ * Supported field kinds for renderer selection.
+ */
+export type FieldKind = "string" | "number" | "boolean" | "enum_select" | "array" | "relation_single" | "relation_array" | "custom_single" | "custom_array";
+/**
+ * Value type for a single form field.
+ */
+export type FieldValue = TypeInfoDataItem[keyof TypeInfoDataItem];
+/**
+ * Constraints extracted from TypeInfo field tags.
+ */
+type FieldConstraints = NonNullable<TypeInfoField["tags"]>["constraints"];
+/**
+ * Supported relation actions emitted by fields.
+ */
+export type RelationAction = "open" | "add" | "edit" | "remove";
+/**
+ * Payload for relation action callbacks.
+ */
+export type RelationActionPayload = {
+    /** Relation action to perform. */
+    action: RelationAction;
+    /** Field key that initiated the action. */
+    fieldKey: string;
+    /** Field metadata for the relation. */
+    field: TypeInfoField;
+    /** Current relation value for the field. */
+    value: ItemRelationshipInfoType | ItemRelationshipInfoType[] | undefined;
+    /** Whether relation selection should use full paging. */
+    fullPaging?: boolean;
+    /** Index when acting on an array item. */
+    index?: number;
+    /** Change handler to update the relation value. */
+    onChange: (value: FieldValue) => void;
+};
+/**
+ * Supported actions for custom type handlers.
+ */
+export type CustomTypeAction = "open" | "add" | "edit" | "remove";
+/**
+ * Payload for custom type action callbacks.
+ */
+export type CustomTypeActionPayload = {
+    /** Custom type action to perform. */
+    action: CustomTypeAction;
+    /** Field key that initiated the action. */
+    fieldKey: string;
+    /** Field metadata for the custom type. */
+    field: TypeInfoField;
+    /** Custom type identifier. */
+    customType: string;
+    /** Current value for the custom type. */
+    value: FieldValue | undefined;
+    /** Index when acting on an array item. */
+    index?: number;
+    /** Change handler to update the custom value. */
+    onChange: (value: FieldValue) => void;
+};
+/**
+ * Context passed to field renderers.
+ */
+export type FieldRenderContext<RenderOutput = unknown> = {
+    /** Type info describing the field to render. */
+    field: TypeInfoField;
+    /** Key that identifies the field in the form values. */
+    fieldKey: string;
+    /** Display label for the field. */
+    label: string;
+    /** True when the field must be provided. */
+    required: boolean;
+    /** True when the field UI should be disabled. */
+    disabled: boolean;
+    /** Optional error descriptor to display under the field. */
+    error?: ErrorDescriptor;
+    /** Optional value-level errors for the field. */
+    errors?: ErrorDescriptor[];
+    /** Optional per-index errors for array fields. */
+    arrayItemErrorMap?: ArrayItemErrorMap;
+    /** Translate an error descriptor to a user-facing message. */
+    translateValidationErrorCode: (error: ErrorDescriptor) => string;
+    /** Current value for the field. */
+    value: FieldValue | undefined;
+    /** Change handler for the field value. */
+    onChange: (value: FieldValue) => void;
+    /** Optional validation and UI constraints. */
+    constraints?: FieldConstraints;
+    /** Optional format hint for the field. */
+    format?: string;
+    /** Allowed literal values for the field. */
+    possibleValues?: LiteralValue[];
+    /** Whether custom entries are allowed for selectable values. */
+    allowCustomSelection?: boolean;
+    /** Optional custom type identifier. */
+    customType?: string;
+    /** Optional callback for relation actions. */
+    onRelationAction?: (payload: RelationActionPayload) => void;
+    /** Optional callback for custom type actions. */
+    onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+    /** Render any field with the same dispatch rules as the parent AutoField call. */
+    renderField: (input: {
+        field: TypeInfoField;
+        fieldKey: string;
+        value: FieldValue | undefined;
+        onChange: (value: FieldValue) => void;
+        error?: ErrorDescriptor;
+        errors?: ErrorDescriptor[];
+        arrayItemErrorMap?: ArrayItemErrorMap;
+        translateValidationErrorCode?: (error: ErrorDescriptor) => string;
+        disabled?: boolean;
+        onRelationAction?: (payload: RelationActionPayload) => void;
+        onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+    }) => RenderOutput;
+};
+/**
+ * Renderer component for a single field kind.
+ */
+export type FieldRenderer<RenderOutput = ReactElement> = ComponentType<FieldRenderContext<RenderOutput>>;
+/**
+ * Optional primitive component contract for suites.
+ */
+export type PrimitiveComponent<Props, RenderOutput = ReactElement> = (props: Props) => RenderOutput;
+/**
+ * Primitive components that suites may override.
+ */
+export type PrimitiveComponents<RenderOutput = ReactElement> = {
+    /** Root container for the form view. */
+    FormRoot: PrimitiveComponent<{
+        children: RenderOutput;
+        onSubmit?: () => void;
+    }, RenderOutput>;
+    /** Wrapper for grouped field content. */
+    FieldWrapper: PrimitiveComponent<{
+        children: RenderOutput;
+    }, RenderOutput>;
+    /** Inline error message renderer. */
+    ErrorMessage: PrimitiveComponent<{
+        children: RenderOutput;
+    }, RenderOutput>;
+    /** Field label renderer. */
+    Label: PrimitiveComponent<{
+        children: RenderOutput;
+        htmlFor?: string;
+    }, RenderOutput>;
+    /** Button renderer. */
+    Button: PrimitiveComponent<{
+        children: RenderOutput;
+        disabled?: boolean;
+        type?: "button" | "submit";
+        onClick?: () => void;
+        "data-signifier"?: string;
+    }, RenderOutput>;
+};
+/**
+ * Suite definition with optional renderers/primitives.
+ */
+export type ComponentSuite<RenderOutput = ReactElement> = {
+    /** Field renderers keyed by kind. */
+    renderers: Partial<Record<FieldKind, FieldRenderer<RenderOutput>>>;
+    /** Optional primitive component overrides. */
+    primitives?: Partial<PrimitiveComponents<RenderOutput>>;
+};
+/**
+ * Fully resolved suite with required renderers.
+ */
+export type ResolvedSuite<RenderOutput = ReactElement> = {
+    /** Field renderers keyed by kind. */
+    renderers: Record<FieldKind, FieldRenderer<RenderOutput>>;
+    /** Optional primitive component overrides. */
+    primitives?: Partial<PrimitiveComponents<RenderOutput>>;
+};
+export {};

package/app/forms/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @packageDocumentation
+ *
+ * Form generation module.
+ */
+export * from "./types";
+export * from "./core";
+export * from "./Engine";
+export * from "./UI";

package/app/forms/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @packageDocumentation
+ *
+ * Types for the form generation system.
+ */
+import type { TypeInfo, TypeInfoDataItem, TypeInfoField, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import type { ArrayErrorDescriptorCollection, ArrayItemErrorMap, ErrorDescriptor, FieldValueValidatorMap, TypeInfoValidationResults } from "../../common/TypeParsing/Validation";
+import type { CustomTypeActionPayload, RelationActionPayload } from "./core/types";
+export * from "./core/types";
+/**
+ * Translates validation error descriptors into UI messages.
+ */
+export type TranslateValidationErrorCode = (error: ErrorDescriptor) => string;
+/**
+ * Optional custom field validators keyed by field name.
+ */
+export type CustomValidatorMap = FieldValueValidatorMap;
+/**
+ * Loose map of form values keyed by field.
+ */
+export type FormValues = Partial<TypeInfoDataItem>;
+/**
+ * Value type for a single form field.
+ */
+export type FormValue = TypeInfoDataItem[keyof TypeInfoDataItem];
+/**
+ * Constraints extracted from TypeInfo field tags.
+ */
+type FieldConstraints = NonNullable<TypeInfoField["tags"]>["constraints"];
+/**
+ * Props for primitive input components.
+ */
+export interface PrimitiveInputProps<T = unknown> {
+    /** Current value for the input. */
+    value: T;
+    /** Callback invoked when the value changes. */
+    onChange: (value: T) => void;
+    /** Optional DOM id applied to the input. */
+    id?: string;
+    /** Placeholder text shown when the input is empty. */
+    placeholder?: string;
+    /** Disables the input when true. */
+    disabled?: boolean;
+    /** Flags the input as invalid for styling. */
+    hasError?: boolean;
+}
+/**
+ * Props for the AutoField component.
+ */
+export interface AutoFieldProps {
+    /** Type info describing the field to render. */
+    field: TypeInfoField;
+    /** Key that identifies the field in the form values. */
+    fieldKey: string;
+    /** Current value for the field. */
+    value: FormValue | undefined;
+    /** Change handler for the field value. */
+    onChange: (value: FormValue) => void;
+    /** Optional primary error descriptor for convenience/backward compatibility. */
+    error?: ErrorDescriptor;
+    /** Optional list of value-level errors for the field. */
+    errors?: ErrorDescriptor[];
+    /** Optional per-index errors for array fields. */
+    arrayItemErrorMap?: ArrayItemErrorMap;
+    /** Optional translator from error descriptor to user-facing message. */
+    translateValidationErrorCode?: TranslateValidationErrorCode;
+    /** Disables the field UI when true. */
+    disabled?: boolean;
+    /** Optional callback for relation actions. */
+    onRelationAction?: (payload: RelationActionPayload) => void;
+    /** Optional callback for custom type actions. */
+    onCustomTypeAction?: (payload: CustomTypeActionPayload) => void;
+}
+/**
+ * Controller metadata for a single field instance.
+ */
+export type FormFieldController = {
+    /** Field key as defined in the TypeInfo map. */
+    key: string;
+    /** Field metadata from the type info. */
+    field: TypeInfoField;
+    /** Display label for the field. */
+    label: string;
+    /** True when the field must be provided. */
+    required: boolean;
+    /** True when the field UI should be disabled. */
+    disabled: boolean;
+    /** True when the field should be hidden from view. */
+    hidden: boolean;
+    /** True when the field is the primary identifier. */
+    primary: boolean;
+    /** Optional format hint for the field. */
+    format?: string;
+    /** Optional validation and UI constraints. */
+    constraints?: FieldConstraints;
+    /** Current value for the field. */
+    value: FormValue | undefined;
+    /** Change handler for the field value. */
+    onChange: (value: FormValue) => void;
+    /** Optional primary error descriptor for the field. */
+    error?: ErrorDescriptor;
+    /** Optional list of value-level errors for the field. */
+    errors?: ErrorDescriptor[];
+    /** Optional per-index errors for array fields. */
+    arrayItemErrorMap?: ArrayItemErrorMap;
+};
+/**
+ * Validation errors keyed by field and represented as descriptors/codes.
+ */
+export type FormErrorMap = Record<string, (ErrorDescriptor | ArrayErrorDescriptorCollection)[]>;
+/**
+ * Input map used to set form errors, accepting descriptors or raw codes.
+ */
+export type FormErrorInputMap = Record<string, ErrorDescriptor | string | ErrorDescriptor[] | ArrayItemErrorMap | (ErrorDescriptor | ArrayErrorDescriptorCollection)[]>;
+/**
+ * Controller for a form instance and its fields.
+ */
+export type FormController = {
+    /** Type metadata used to build the form. */
+    typeInfo: TypeInfo;
+    /** Optional type-level tags from the metadata. */
+    typeTags?: TypeInfo["tags"];
+    /** Active operation driving field state. */
+    operation: TypeOperation;
+    /** Current form values keyed by field. */
+    values: FormValues;
+    /** Validation errors keyed by field. */
+    errors: FormErrorMap;
+    /** Derived controllers for each field. */
+    fields: FormFieldController[];
+    /** Update a field value by key. */
+    setFieldValue: (key: string, value: FormValue) => void;
+    /** Validate the form and return success. */
+    validate: () => TypeInfoValidationResults;
+    /** Override form errors with a provided map. */
+    setErrors: (errors: FormErrorInputMap) => void;
+};

package/app/helpers/styled.d.ts

@@ -0,0 +1,3 @@
+export * from "styled-components";
+declare const styled: any;
+export default styled;