@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/app/forms/Engine.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @packageDocumentation
+ *
+ * Core engine logic for managing form state.
+ */
+import type { TypeInfo } from "../../common/TypeParsing/TypeInfo";
+import { TypeOperation } from "../../common/TypeParsing/TypeInfo";
+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;
+}) => FormController;

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

@@ -0,0 +1,35 @@
+/**
+ * @packageDocumentation
+ *
+ * Factory for AutoField that delegates rendering to a resolved suite.
+ */
+import type { TypeInfoField } from "../../../common/TypeParsing/TypeInfo";
+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 message to display under the field. */
+    error?: 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 = unknown>(suite: ResolvedSuite<RenderOutput>) => (props: AutoFieldInput) => RenderOutput;

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

@@ -0,0 +1,24 @@
+/**
+ * @packageDocumentation
+ *
+ * Factory for building form renderers backed by component suites.
+ */
+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 = unknown>(options: {
+    fallbackSuite: ComponentSuite<RenderOutput>;
+    suite?: ComponentSuite<RenderOutput>;
+}) => {
+    AutoField: (props: AutoFieldInput) => RenderOutput;
+    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,22 @@
+/**
+ * @packageDocumentation
+ *
+ * Helpers for composing component suites.
+ */
+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 = unknown>(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 = unknown>(kind: FieldKind, renderer: FieldRenderer<RenderOutput>) => ComponentSuite<RenderOutput>;

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

@@ -0,0 +1,14 @@
+/**
+ * @packageDocumentation
+ *
+ * Resolve a component suite by merging overrides with fallback defaults.
+ */
+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 = unknown>(overrides: ComponentSuite<RenderOutput> | undefined, fallback: ComponentSuite<RenderOutput>) => ResolvedSuite<RenderOutput>;

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

@@ -0,0 +1,153 @@
+/**
+ * @packageDocumentation
+ *
+ * Core, platform-agnostic types for form rendering.
+ */
+import type { LiteralValue, TypeInfoDataItem, TypeInfoField } from "../../../common/TypeParsing/TypeInfo";
+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 = {
+    /** 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 message to display under the field. */
+    error?: 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;
+};
+/**
+ * Renderer function for a single field kind.
+ */
+export type FieldRenderer<RenderOutput = unknown> = (context: FieldRenderContext) => RenderOutput;
+/**
+ * Optional primitive component contract for suites.
+ */
+export type PrimitiveComponent<Props, RenderOutput = unknown> = (props: Props) => RenderOutput;
+/**
+ * Primitive components that suites may override.
+ */
+export type PrimitiveComponents<RenderOutput = unknown> = {
+    /** 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 = unknown> = {
+    /** 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 = unknown> = {
+    /** 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 type { ComponentSuite, FieldKind, FieldRenderContext, FieldRenderer, FieldValue, PrimitiveComponent, PrimitiveComponents, ResolvedSuite, } from "./core";
+export { createAutoField, createFormRenderer, getFieldKind, mergeSuites, resolveSuite, withRendererOverride, } from "./core";
+export * from "./Engine";

package/app/forms/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @packageDocumentation
+ *
+ * Types for the form generation system.
+ */
+import type { TypeInfo, TypeInfoDataItem, TypeInfoField, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import type { ItemRelationshipInfoType } from "../../common/ItemRelationshipInfoTypes";
+/**
+ * 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 error message to display under the field. */
+    error?: 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;
+}
+/**
+ * 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 error message for the field. */
+    error?: string;
+};
+/**
+ * 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: Record<string, string>;
+    /** 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: () => boolean;
+    /** Override form errors with a provided map. */
+    setErrors: (errors: Record<string, string>) => void;
+};
+/**
+ * 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: FormValue) => 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: FormValue | undefined;
+    /** Index when acting on an array item. */
+    index?: number;
+    /** Change handler to update the custom value. */
+    onChange: (value: FormValue) => void;
+};
+export {};

package/app/helpers/styled.d.ts

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

package/app/index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @packageDocumentation
+ *
+ * Build front-end applications with React and TypeScript utilities, including
+ * layout/state helpers and form generation support.
+ *
+ * Import from the app subpath only:
+ * ```ts
+ * import {
+ *   createFormRenderer,
+ *   useApplicationStateLoader,
+ *   useApplicationStateValueStructure,
+ *   type RemoteProcedureCall,
+ * } from "@resistdesign/voltra/app";
+ * ```
+ *
+ * @see {@link useApplicationStateValueStructure} and
+ * {@link useApplicationStateLoader} for good starting points.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   useApplicationStateLoader,
+ *   useApplicationStateValueStructure,
+ *   type RemoteProcedureCall,
+ * } from "@resistdesign/voltra/app";
+ * import { useCallback } from "react";
+ *
+ * const APP_STATE_IDENTIFIERS = {
+ *   LOGIN: {
+ *     USERNAME: {},
+ *     PASSWORD: {},
+ *     LOGGED_IN: {},
+ *   },
+ * };
+ *
+ * const LOGIN_SERVICE_CONFIG = {
+ *   protocol: "https",
+ *   domain: "example.com",
+ *   basePath: "/api",
+ * };
+ *
+ * const LOGIN_RPC: RemoteProcedureCall = {
+ *   serviceConfig: LOGIN_SERVICE_CONFIG,
+ *   path: "/login",
+ *   args: [],
+ * };
+ *
+ * export const LoginController = () => {
+ *   const {
+ *     valueStructure: {
+ *       username: username = "",
+ *       password: password = "",
+ *       loggedIn: loggedIn = false,
+ *     },
+ *     onChangeStructure: {
+ *       username: setUsername,
+ *       password: setPassword,
+ *       loggedIn: setLoggedIn,
+ *     },
+ *   } = useApplicationStateValueStructure<{
+ *     username: string;
+ *     password: string;
+ *     loggedIn: boolean;
+ *   }>({
+ *     username: APP_STATE_IDENTIFIERS.LOGIN.USERNAME,
+ *     password: APP_STATE_IDENTIFIERS.LOGIN.PASSWORD,
+ *     loggedIn: APP_STATE_IDENTIFIERS.LOGIN.LOGGED_IN,
+ *   });
+ *
+ *   const { loading: loadingLogin, makeRemoteProcedureCall } =
+ *     useApplicationStateLoader({
+ *       identifier: APP_STATE_IDENTIFIERS.LOGIN.LOGGED_IN,
+ *       remoteProcedureCall: LOGIN_RPC,
+ *       manual: true,
+ *     });
+ *
+ *   const onSubmit = useCallback(() => {
+ *     makeRemoteProcedureCall(username, password);
+ *   }, [username, password, makeRemoteProcedureCall]);
+ *
+ *   return { username, password, loggedIn, setUsername, setPassword, onSubmit, loadingLogin };
+ * };
+ * ```
+ *
+ * See also: `@resistdesign/voltra/web` and `@resistdesign/voltra/native` for
+ * runtime-specific UI helpers.
+ */
+/**
+ * @category app
+ * @group State and Services
+ */
+export * from "./utils";
+/**
+ * @category app
+ * @group Forms
+ */
+export * from "./forms";