@timeax/form-palette 0.0.1

package/src/schema/core.ts

@@ -0,0 +1,429 @@
+// src/schema/core.ts
+// noinspection JSUnusedGlobalSymbols,GrazieInspection
+
+import type React from "react";
+import type { z } from "zod";
+
+import type {
+    Method,
+    AdapterResult,
+    AdapterKey,
+    AdapterSubmit,
+} from "./adapter";
+import type { ButtonRef, Field } from "./field";
+import { FieldRegistry } from "@/core/registry/field-registry";
+
+/**
+ * Generic dictionary type used throughout the core.
+ *
+ * This matches the legacy Dict<T> from the old types.ts.
+ */
+export type Dict<T = unknown> = Record<string, T>;
+
+/**
+ * If a Zod schema is present, infer the values from that schema;
+ * otherwise use the fallback V type. Ensured to be a Dict so it
+ * can safely be used as CoreContext's generic argument.
+ */
+export type InferFromSchema<S, V extends Dict> = S extends z.ZodType
+    ? z.infer<S> & Dict
+    : V;
+
+/**
+ * Event object passed to onSubmit, matching the legacy SubmitEvent
+ * but kept transport-agnostic. The host decides how route/method/xhr
+ * are interpreted and which adapter is used.
+ *
+ * @template TValues Shape of the outbound data for this submit event.
+ */
+export type SubmitEvent<TValues extends Dict> = {
+    /**
+     * Prevent the default submit behavior.
+     *
+     * In practice this prevents the core from continuing with its
+     * normal submit/prepare flow.
+     */
+    preventDefault(): void;
+
+    /**
+     * Mutate the outbound data just before it is used.
+     *
+     * The callback may return a new data object or mutate in-place.
+     */
+    editData(cb: (data: TValues) => TValues | void): void;
+
+    /**
+     * Override the route/URL for this submission only.
+     *
+     * The core itself does not enforce any semantics here; the host
+     * is expected to interpret this when wiring submissions.
+     */
+    setRoute(route: string): void;
+
+    /**
+     * Override the HTTP method for this submission only.
+     */
+    setMethod(method: Method): void;
+
+    /**
+     * The button that triggered this submit, if any.
+     */
+    button?: ButtonRef;
+
+    /**
+     * The current outbound data snapshot (after any internal merges).
+     */
+    readonly formData: TValues;
+
+    /**
+     * The core context associated with this submit event.
+     */
+    form: CoreContext<TValues>;
+
+    /**
+     * If set to false, the core will abort the submit flow after
+     * this handler returns.
+     */
+    continue: boolean;
+};
+
+/**
+ * Shared base props for the core runtime, matching the spirit of
+ * the legacy BaseProps, but transport-agnostic.
+ *
+ * @template V Shape of the underlying value map (pre-schema).
+ * @template S Optional Zod schema type.
+ */
+export type BaseProps<V extends Dict, S extends z.ZodType | undefined> = {
+    /**
+     * Field names that should be ignored when building diffs or snapshots.
+     * Useful for excluding secrets like passwords from logs.
+     */
+    exceptions?: string[];
+
+    /**
+     * Whether the core should persist values to the provided valueBag.
+     */
+    persist?: boolean;
+
+    /**
+     * Optional logical name for the core instance.
+     */
+    name?: string;
+
+    /**
+     * If true, a button may be automatically marked as "active" when
+     * certain changes occur.
+     */
+    activateButtonOnChange?: boolean;
+
+    /**
+     * Called whenever a field changes.
+     *
+     * current is the field that changed; options carries any
+     * variant-specific metadata.
+     */
+    onChange?(
+        form: CoreContext<InferFromSchema<S, V>>,
+        current: Field,
+        options: Dict
+    ): void;
+
+    /**
+     * Called when the overall values snapshot is considered "updated".
+     */
+    onUpdate?(values: InferFromSchema<S, V>): void;
+
+    /**
+     * If true, onChange may run before certain internal updates.
+     */
+    changeBefore?: boolean;
+
+    /**
+     * Optional ref to the core context instance, for imperative access.
+     */
+    formRef?: React.MutableRefObject<CoreContext<InferFromSchema<S, V>> | null>;
+
+    /**
+     * Initial value bag for hydration / persistence.
+     */
+    valueBag?: InferFromSchema<S, V>;
+
+    /**
+     * Optional hook used to transform a single value as it is being
+     * persisted or fed into the core.
+     */
+    valueFeed?: <K extends keyof InferFromSchema<S, V>>(
+        name: K,
+        value: InferFromSchema<S, V>[K],
+        form: CoreContext<InferFromSchema<S, V>>
+    ) => InferFromSchema<S, V>[K] | undefined;
+
+    /**
+     * Called at the end of certain flows (legacy "finish" hook).
+     *
+     * Receives the core context so you can read values, errors, etc.
+     */
+    onFinish?(form: CoreContext<InferFromSchema<S, V>>): void;
+
+    /**
+     * Called after the core initializes.
+     */
+    init?(form: CoreContext<InferFromSchema<S, V>>): void;
+
+    /**
+     * Intercepts the submit event before the core proceeds.
+     *
+     * You can:
+     * - mutate data,
+     * - change route/method/xhr flags,
+     * - abort by setting e.continue = false.
+     */
+    onSubmit?<T extends Dict = InferFromSchema<S, V>>(
+        e: SubmitEvent<T>
+    ): Promise<void> | void;
+
+    /**
+     * Optional Zod schema used for validation and value inference.
+     */
+    schema?: S;
+};
+
+/**
+ * Public core props, adapter-centric.
+ *
+ * - The library defines a built-in 'local' adapter flavour.
+ *   AdapterSubmit<'local'> is `{ data: unknown }`.
+ * - Hosts can extend the Adapters interface (schema/adapter.ts) to add
+ *   their own adapter flavours (axios, inertia, etc.) and then use
+ *   those keys here.
+ *
+ * @template V Shape of the underlying value map (pre-schema).
+ * @template S Optional Zod schema type.
+ * @template K Adapter key; defaults to 'local'.
+ */
+export interface CoreProps<
+    V extends Dict,
+    S extends z.ZodType | undefined,
+    K extends AdapterKey = "local",
+> extends BaseProps<V, S> {
+    /**
+     * Which adapter flavour this core instance should use.
+     *
+     * - 'local' (default) → library-defined local submission (no URL/method semantics).
+     * - extended keys      → host-defined adapters via Adapters augmentation.
+     */
+    adapter?: K;
+
+    /**
+     * Called after a submission completes. The payload type is derived from
+     * the selected adapter key via the adapter registry:
+     *
+     *   AdapterSubmit<'local'> → { data: unknown }
+     *   AdapterSubmit<'axios'> → host-defined type, etc.
+     */
+    onSubmitted?(
+        form: CoreContext<InferFromSchema<S, V>>,
+        payload: AdapterSubmit<K>,
+        resolve?: () => void
+    ): void | Promise<void>;
+}
+
+/**
+ * Backwards-compatible alias for legacy naming, if you want it.
+ */
+export type FormProps<
+    V extends Dict,
+    S extends z.ZodType | undefined,
+    K extends AdapterKey = "local",
+> = CoreProps<V, S, K>;
+
+/**
+ * Result of a submit operation: values + validity flag.
+ */
+export type ValuesResult<V extends Dict> = { values: V; valid: boolean };
+
+/**
+ * Query API for fields, similar to DOM helpers but scoped
+ * to the current form instance.
+ *
+ * "id" here refers to the field's groupId.
+ */
+export interface InputStore {
+    /** All registered inputs (with at least one identifier). */
+    all(): Field[];
+
+    /** All inputs that have a non-empty name. */
+    getAllNamed(): Field[];
+
+    /** All inputs that have a bindId. */
+    getAllBound(): Field[];
+
+    /** All inputs that have a groupId. */
+    getAllGrouped(): Field[];
+
+    /** First field matching an exact name. */
+    getByName(name: string): Field | undefined;
+
+    /** All fields matching an exact name. */
+    getAllByName(name: string): Field[];
+
+    /** First field with this groupId. */
+    getById(id: string): Field | undefined;
+
+    /** All fields with this groupId. */
+    getAllById(id: string): Field[];
+
+    /** First bound field with this bindId (prefers mounted fields). */
+    getByBind(id: string): Field | undefined;
+
+    /** All fields that share this bindId. */
+    getAllByBind(id: string): Field[];
+}
+
+/**
+ * Core runtime context, renamed from the legacy FormContext.
+ *
+ * @template V Shape of the values object produced by this core instance.
+ */
+export interface CoreContext<V extends Dict> {
+    /**
+     * Compute the current values snapshot from registered fields.
+     */
+    values(): V;
+
+    /**
+     * Run validation and return the values + validity flag.
+     */
+    submit(): ValuesResult<V>;
+
+    /**
+     * Lookup a field by its binding id.
+     */
+    getBind(id: string): Field | undefined;
+
+    /**
+     * Run validation across fields.
+     *
+     * @param report If true, fields should update their own error states.
+     * @returns true if all fields are valid, false otherwise.
+     */
+    validate(report?: boolean): boolean;
+
+    /**
+     * Register a new field with the core.
+     */
+    addField(field: Field): void;
+
+    /**
+     * Generic internal bucket for arbitrary metadata.
+     */
+    bucket: Dict;
+
+    /**
+     * Set a single field error or map an error bag.
+     */
+    error(name: string, msg: string): void;
+    error(bag: Record<string, string>): void;
+
+    /**
+     * Re-run button control logic (which button is active/disabled etc.).
+     */
+    controlButton(): void;
+
+    /**
+     * Prepare an adapter-backed request.
+     *
+     * This mirrors the legacy prepare method:
+     * - Builds a payload from values + extra.
+     * - May run validation / beforeSubmit hooks.
+     * - Returns an adapter result or undefined if aborted.
+     *
+     * The concrete adapter wiring is the host's responsibility.
+     */
+    prepare(
+        type: Method,
+        route: string,
+        extra?: Partial<V>,
+        ignoreForm?: boolean,
+        autoErr?: boolean
+    ): Promise<AdapterResult<any> | undefined>;
+
+    /**
+     * Persist values to a provided data object, optionally transforming
+     * values via the feed function.
+     */
+    persist(
+        data: Partial<V>,
+        feed?: (name: string, value: unknown, original: unknown) => unknown
+    ): void;
+
+    /**
+     * Imperatively set a single value by field name.
+     */
+    setValue(name: string, value: unknown): void;
+
+    /**
+     * Kick off a submit flow using optional extra data.
+     */
+    go(data?: Partial<V>, ignoreForm?: boolean): void;
+
+    /**
+     * Reset specific inputs by name.
+     */
+    reset(inputs: string[]): void;
+
+    /**
+     * Register the current active button.
+     */
+    set button(v: ButtonRef);
+
+    /**
+     * Force a submit regardless of validation state.
+     */
+    forceSubmit(): Promise<void>;
+
+    /**
+     * All registered fields.
+     */
+    readonly fields: Field[];
+
+    /**
+     * Effective core props at runtime, excluding internal-only fields.
+     *
+     * Note: the adapter key parameter is erased here (set to any) because
+     * the runtime does not need the specific key for structural typing;
+     * hosts can still use more precise generics at the component level.
+     */
+    readonly props: Omit<
+        CoreProps<V, z.ZodType | undefined, any>,
+        "formRef" | "valueBag"
+    >;
+
+    /**
+     * Mark a button as active by name.
+     */
+    setActiveButton(name: string): void;
+
+    /**
+     * Return uncaught messages (errors that could not be mapped to a field).
+     *
+     * Typically used by an error strip component.
+     */
+
+    getUncaught(): readonly string[];
+    /**
+     * Field-query "DOM" for this form.
+     *
+     * Example:
+     *   const email = form.inputs.getByName("email");
+     *   const phoneFields = form.inputs.getAllById("phone-group");
+     *   const bound = form.inputs.getByBind("shipping");
+     */
+    inputs: Omit<FieldRegistry, "add" | "remove">;
+
+    /**
+     * Checks if the form values have changed
+     */
+    isDirty(): boolean
+}

package/src/schema/field.ts

@@ -0,0 +1,224 @@
+// src/schema/field.ts
+// noinspection GrazieInspection
+
+import type { RefObject } from "react";
+
+/**
+ * Imperative handle for a submit button registered with the core.
+ *
+ * This mirrors the legacy `ButtonRef` interface, but is aligned with the
+ * current CoreProvider implementation:
+ *
+ * - The core will try `setLoading(v)` / `setDisabled(v)` if available.
+ * - Otherwise, it will fall back to setting `loading` / `disabled` props.
+ */
+export interface ButtonRef {
+    /**
+     * Logical name of the button.
+     *
+     * Used by the core runtime to track the "active" button
+     * and to map behaviours to a specific action.
+     */
+    name: string;
+
+    /**
+     * Loading flag. The core may read or assign this directly if
+     * no setter is provided.
+     */
+    loading?: boolean;
+
+    /**
+     * Disabled flag. The core may read or assign this directly if
+     * no setter is provided.
+     */
+    disabled?: boolean;
+
+    /**
+     * Optional setter used by the core to toggle loading.
+     */
+    setLoading?(v: boolean): void;
+
+    /**
+     * Optional setter used by the core to toggle disabled state.
+     */
+    setDisabled?(v: boolean): void;
+}
+
+/**
+ * Runtime representation of a single field registered with the core.
+ *
+ * This is a direct, type-safe evolution of the legacy `Field` interface
+ * from the old `types.ts`, updated to match the new core + binder flow.
+ */
+export interface Field {
+    /**
+     * Primary field name, used in values, error bags, and schema mapping.
+     *
+     * May be omitted for purely bound/virtual fields that participate in
+     * binder flows but are not directly part of the value bag.
+     */
+    name?: string;
+
+    /**
+     * Internal binding identifier.
+     *
+     * Used by "bound" helpers (observe-bound-field, wait-for-bound-field)
+     * to locate shared/aliased fields without going through the name.
+     */
+    bindId?: string;
+
+    /**
+     * Optional explicit binding identifier.
+     * Use to bind to a specific field in a nested object that has bindId
+     */
+    bind?: string;
+
+    /**
+     * Ref to the underlying DOM element used for focus/scroll operations.
+     *
+     * Implementations typically point this at the outer wrapper of the field.
+     */
+    ref?: RefObject<HTMLElement> | null;
+
+    /**
+     * Whether this field is required.
+     *
+     * Variant-level and schema-level validation may use this.
+     */
+    required?: boolean;
+
+    /**
+     * Current error message for the field.
+     *
+     * Undefined or empty string means "no error".
+     */
+    error?: string;
+
+    /**
+     * Current value of the field, as seen by the core runtime.
+     *
+     * For formatted inputs, this may be the formatted representation.
+     */
+    value?: unknown;
+
+    /**
+     * Initial/default value for the field.
+     *
+     * This is typically the "un-touched" value coming from props or
+     * from a persisted value bag.
+     */
+    defaultValue?: unknown;
+
+    /**
+     * Original, unformatted value as first seen by the core.
+     *
+     * This allows callers to compare "what changed" relative to the
+     * original snapshot, independent of any display formatting.
+     */
+    originalValue?: unknown;
+
+    /**
+     * Whether this field is currently performing an async operation
+     * (e.g. remote validation).
+     */
+    loading?: boolean;
+
+    /**
+     * Optional group identifier used to group related fields together
+     * (e.g. radio groups, segmented inputs).
+     */
+    groupId?: string;
+
+    /**
+     * Optional alias for this field.
+     *
+     * Aliases allow mapping server error bags or schema keys that do
+     * not strictly match the `name` property.
+     */
+    alias?: string;
+
+    /**
+     * Marks this field as the "main" one in a group.
+     *
+     * Used by some variants/layouts to determine which field drives
+     * overall group state.
+     */
+    main?: boolean;
+
+    /**
+     * If true, this field will be ignored when building values or
+     * running certain validation flows.
+     */
+    ignore?: boolean;
+
+    /**
+     * Stable unique key (distinct from `name` and `bindId`).
+     *
+     * Used internally by registries and React lists.
+     */
+    key?: string;
+
+    /**
+     * Shared key for fields that share their value (e.g. custom views
+     * over the same underlying data).
+     *
+     * This is used by the core when building nested objects, e.g.:
+     *   shared = "profile", name = "first_name"
+     *   ⇒ values.profile.first_name
+     */
+    shared?: string;
+
+    // ─────────────────────────────────────────────────────────
+    // Behaviour hooks (implemented by InputField / variants)
+    // ─────────────────────────────────────────────────────────
+
+    /**
+     * Run validation for this field.
+     *
+     * @param report If true, the field should update its own error state;
+     *               if false, it may simply return whether it is valid.
+     * @returns `true` if the field is currently valid, `false` otherwise.
+     */
+    validate?(report?: boolean): boolean;
+
+    /**
+     * Optional hook used by the core or higher-level utilities to retrieve
+     * the current value of the field.
+     *
+     * If omitted, the core will fall back to the `value` property.
+     */
+    getValue?(): unknown;
+
+    /**
+     * Optional hook used by the core or higher-level utilities to update
+     * the current value of the field.
+     *
+     * If omitted, the core will fall back to mutating the `value` property.
+     */
+    setValue?(value: unknown): void;
+
+    /**
+     * Optional hook used by the core to reset the field back to its
+     * default/original value.
+     */
+    reset?(): void;
+
+    /**
+     * Optional hook used by the core to set or clear the field error.
+     *
+     * If omitted, the core will fall back to assigning the `error` property.
+     */
+    setError?(message?: string): void;
+
+    /**
+     * Optional hook called whenever the field value changes.
+     *
+     * Used by binder utilities to propagate changes across bound fields.
+     *
+     * @param value   New value.
+     * @param old     Previous value.
+     * @param source  Source tag responsible for the change
+     *                (e.g. "variant", "util", "paste", "programmatic").
+     */
+    onChange?(value: unknown, old: unknown, source: string): void;
+}