@timeax/form-palette 0.0.1

package/src/core/core-root.tsx

@@ -0,0 +1,72 @@
+// src/core/core-root.tsx
+
+import * as React from "react";
+
+import { useCore } from "@/core/hooks/use-core";
+import { ErrorStrip } from "@/core/errors/error-strip";
+import type { CoreContext, Dict } from "@/schema/core";
+
+export interface CoreRootProps
+    extends React.FormHTMLAttributes<HTMLFormElement> {
+    /**
+     * If true, the global ErrorStrip will not be rendered automatically.
+     */
+    noErrorStrip?: boolean;
+
+    /**
+     * Optional hook invoked after CoreRoot orchestrates the submit.
+     *
+     * - The native event is already `preventDefault()`-ed.
+     * - The adapter flow is triggered via `form.go(...)`.
+     * - Use this to tap into submit without breaking the core.
+     */
+    onSubmitForm?(
+        event: React.FormEvent<HTMLFormElement>,
+        form: CoreContext<Dict>
+    ): void | Promise<void>;
+}
+
+/**
+ * CoreRoot: actual <form> element wired to the core runtime.
+ *
+ * Responsibilities:
+ * - Own the native submit event and prevent full-page navigation.
+ * - Delegate submit orchestration to form.go().
+ * - Optionally render the global ErrorStrip at the top.
+ */
+export function CoreRoot(props: CoreRootProps) {
+    const { noErrorStrip, onSubmitForm, children, ...rest } = props;
+
+    const form = useCore<Dict>();
+
+    const handleSubmit = React.useCallback(
+        (event: React.FormEvent<HTMLFormElement>) => {
+            event.preventDefault();
+            if (form.props.activateButtonOnChange && !form.isDirty()) return;
+            // Core submit orchestration (adapter-specific behaviour lives inside).
+            form.go();
+
+            // Optional host-level hook.
+            if (onSubmitForm) {
+                void onSubmitForm(event, form);
+            }
+
+            // If the host provided a native onSubmit prop, call it too.
+            if (typeof rest.onSubmit === "function") {
+                rest.onSubmit(event);
+            }
+        },
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [form, onSubmitForm, rest.onSubmit]
+    );
+
+    // We intentionally override onSubmit so the core owns submit routing.
+    const { onSubmit: _ignored, ...passThrough } = rest;
+
+    return (
+        <form onSubmit={handleSubmit} {...passThrough}>
+            {!noErrorStrip && <ErrorStrip form={form} />}
+            {children}
+        </form>
+    );
+}

package/src/core/core-shell.tsx

@@ -0,0 +1,44 @@
+// src/core/core-shell.tsx
+
+import * as React from "react";
+
+import { CoreProvider } from "@/core/core-provider";
+import { CoreRoot, type CoreRootProps } from "@/core/core-root";
+
+import type { z } from "zod";
+import type { AdapterKey } from "@/schema/adapter";
+import type { CoreProps, Dict } from "@/schema/core";
+
+/**
+ * Combined provider + form-root wrapper.
+ *
+ * Usage:
+ *   <CoreShell adapter="local" schema={schema} formProps={{ className: "space-y-4" }}>
+ *     {...fields + buttons...}
+ *   </CoreShell>
+ */
+export interface CoreShellProps<
+    V extends Dict = Dict,
+    S extends z.ZodType | undefined = z.ZodType | undefined,
+    K extends AdapterKey = "local",
+> extends CoreProps<V, S, K> {
+    /**
+     * Props passed directly to the underlying <form> element via CoreRoot.
+     */
+    formProps?: CoreRootProps;
+    children?: React.ReactNode;
+}
+
+export function CoreShell<
+    V extends Dict,
+    S extends z.ZodType | undefined,
+    K extends AdapterKey = "local",
+>(props: CoreShellProps<V, S, K>) {
+    const { formProps, children, ...coreProps } = props;
+
+    return (
+        <CoreProvider<V, S, K> {...(coreProps as CoreProps<V, S, K>)}>
+            <CoreRoot {...(formProps ?? {})}>{children}</CoreRoot>
+        </CoreProvider>
+    );
+}

package/src/core/errors/error-strip.tsx

@@ -0,0 +1,71 @@
+// src/core/errors/error-strip.tsx
+
+import * as React from "react";
+
+import { useCore } from "@/core/hooks/use-core";
+import type { CoreContext, Dict } from "@/schema/core";
+
+export interface ErrorStripProps extends React.HTMLAttributes<HTMLElement> {
+    /**
+     * Optional explicit form context. If omitted, the strip will use
+     * the nearest CoreProvider via useCore().
+     */
+    form?: CoreContext<Dict>;
+
+    /**
+     * Optional explicit messages. If provided, these are used instead of
+     * form.getUncaught().
+     */
+    messages?: readonly string[];
+
+    /**
+     * Custom renderer for each message.
+     */
+    renderMessage?: (message: string, index: number) => React.ReactNode;
+
+    /**
+     * Wrapper element type. Defaults to "div".
+     */
+    as?: React.ElementType;
+
+    /**
+     * Props forwarded to the inner <ul> element.
+     */
+    listProps?: React.HTMLAttributes<HTMLUListElement>;
+}
+
+/**
+ * Simple global/uncaught error renderer.
+ *
+ * Reads messages from `form.getUncaught()` (unless `messages` is provided)
+ * and renders them as a list.
+ */
+export function ErrorStrip(props: ErrorStripProps) {
+    const {
+        form: formProp,
+        messages: messagesProp,
+        renderMessage,
+        as: As = "div",
+        listProps,
+        ...wrapperProps
+    } = props;
+
+    const ctxFromHook = useCore<Dict>();
+    const form = formProp ?? ctxFromHook;
+
+    const messages = messagesProp ?? form?.getUncaught?.() ?? [];
+
+    if (!messages.length) return null;
+
+    return (
+        <As {...wrapperProps}>
+            <ul {...listProps}>
+                {messages.map((msg, index) => (
+                    <li key={index}>
+                        {renderMessage ? renderMessage(msg, index) : msg}
+                    </li>
+                ))}
+            </ul>
+        </As>
+    );
+}

package/src/core/errors/index.ts

@@ -0,0 +1,2 @@
+export * from "./map-error-bag";
+export * from "./map-zod";

package/src/core/errors/map-error-bag.ts

@@ -0,0 +1,51 @@
+// src/core/errors/map-error-bag.ts
+
+export type ErrorBag = Record<string, string | string[] | undefined | null>;
+
+export type ErrorBagMapResult = {
+    /** Field-specific errors keyed by field name. */
+    fieldErrors: Record<string, string>;
+    /** Errors that could not be mapped to a specific field. */
+    uncaught: string[];
+};
+
+/**
+ * Map a generic "error bag" object into field errors + uncaught messages.
+ *
+ * Typical input:
+ *   {
+ *     name: "Name is required",
+ *     email: ["Email is invalid"],
+ *     message: "Something went wrong" // global
+ *   }
+ *
+ * Heuristics:
+ * - Keys like "message", "error", "_", "global" → treated as global/uncaught.
+ * - Everything else → treated as a field error.
+ * - Array values are joined with "\n".
+ */
+export function mapErrorBag(bag: ErrorBag): ErrorBagMapResult {
+    const fieldErrors: Record<string, string> = {};
+    const uncaught: string[] = [];
+
+    const GLOBAL_KEYS = new Set(["message", "error", "errors", "_", "global"]);
+
+    for (const [key, raw] of Object.entries(bag)) {
+        if (raw == null) continue;
+
+        const value = Array.isArray(raw)
+            ? raw.filter(Boolean).join("\n")
+            : String(raw);
+
+        if (!value) continue;
+
+        if (GLOBAL_KEYS.has(key)) {
+            uncaught.push(value);
+        } else {
+            const existing = fieldErrors[key];
+            fieldErrors[key] = existing ? `${existing}\n${value}` : value;
+        }
+    }
+
+    return { fieldErrors, uncaught };
+}

package/src/core/errors/map-zod.ts

@@ -0,0 +1,39 @@
+// src/core/errors/map-zod.ts
+import type { $ZodIssue, $ZodError } from "zod/v4/core";
+
+export type ZodErrorMapResult = {
+    /** Field-specific errors keyed by field name. */
+    fieldErrors: Record<string, string>;
+    /** Errors that could not be mapped to a specific field. */
+    uncaught: string[];
+};
+
+/**
+ * Map a ZodError into field-specific errors + uncaught messages.
+ *
+ * Heuristics:
+ * - If issue.path[0] is a string → treated as a field name.
+ * - Otherwise → message is pushed into `uncaught`.
+ *
+ * If a field has multiple issues, messages are joined with `\n`.
+ */
+export function mapZodError(error: $ZodError): ZodErrorMapResult {
+    const fieldErrors: Record<string, string> = {};
+    const uncaught: string[] = [];
+
+    for (const issue of error.issues as $ZodIssue[]) {
+        const path = issue.path;
+        const message = issue.message || "Validation error";
+
+        const first = path[0];
+
+        if (typeof first === "string" && first.length > 0) {
+            const existing = fieldErrors[first];
+            fieldErrors[first] = existing ? `${existing}\n${message}` : message;
+        } else {
+            uncaught.push(message);
+        }
+    }
+
+    return { fieldErrors, uncaught };
+}

package/src/core/hooks/use-button.ts

@@ -0,0 +1,220 @@
+// src/core/hooks/use-button.ts
+// noinspection JSUnusedGlobalSymbols
+
+import * as React from "react";
+
+import { useCoreContext } from "@/core/hooks/use-core-context";
+import type { CoreContext, Dict } from "@/schema/core";
+import type { ButtonRef } from "@/schema/field";
+
+export interface UseButtonOptions {
+    /**
+     * Logical name of the button.
+     *
+     * Used by the core to:
+     * - mark this as the "active" button before submit
+     * - toggle loading/disabled specifically for this button
+     */
+    name: string;
+
+    /**
+     * If true, clicking this button should trigger a submit:
+     *
+     * - form.setActiveButton(name)
+     * - form.go()
+     */
+    submit?: boolean;
+
+    /**
+     * Initial disabled state.
+     */
+    disabled?: boolean;
+
+    /**
+     * Optional click handler.
+     *
+     * This runs *in addition to* the submit behavior (if `submit` is true).
+     * You can call `event.preventDefault()` to prevent the auto-submit.
+     */
+    onClick?(
+        event: React.MouseEvent<HTMLButtonElement>,
+        form: CoreContext<Dict>
+    ): void | Promise<void>;
+}
+
+export interface UseButtonReturn {
+    /**
+     * Current loading state, controlled by the core (via adapters) and
+     * optionally by the host via setLoading.
+     */
+    loading: boolean;
+    setLoading(loading: boolean): void;
+
+    /**
+     * Current disabled state.
+     */
+    disabled: boolean;
+    setDisabled(disabled: boolean): void;
+
+    /**
+     * Ref for the underlying <button>.
+     */
+    ref: React.RefObject<HTMLButtonElement>;
+
+    /**
+     * Click handler wired to the core.
+     */
+    onClick(event: React.MouseEvent<HTMLButtonElement>): void;
+
+    /**
+     * Convenience bundle for spreading onto a <button>.
+     *
+     * Example:
+     *   const btn = useButton({ name: "save", submit: true });
+     *   return <button {...btn.buttonProps}>Save</button>;
+     */
+    buttonProps: {
+        ref: React.RefObject<HTMLButtonElement>;
+        disabled: boolean;
+        "data-loading"?: "true" | "false";
+        onClick(event: React.MouseEvent<HTMLButtonElement>): void;
+    };
+}
+
+/**
+ * useButton
+ *
+ * - Registers a ButtonRef with the core.
+ * - Cooperates with setActiveButton + adapter-based submit.
+ * - Handles loading/disabled toggling via the core's callbacks.
+ */
+export function useButton(options: UseButtonOptions): UseButtonReturn {
+    const form = useCoreContext<Dict>();
+
+    const { name, submit, disabled: disabledProp = false, onClick } = options;
+
+    const [loading, setLoadingState] = React.useState<boolean>(false);
+    const [disabled, setDisabledState] = React.useState<boolean>(
+        Boolean(disabledProp)
+    );
+
+    const ref = React.useRef<HTMLButtonElement>(null);
+
+    // Keep latest options for callbacks
+    const optsRef = React.useRef<UseButtonOptions>(options);
+    React.useEffect(() => {
+        optsRef.current = options;
+    }, [options]);
+
+    // Build the ButtonRef once
+    const buttonRef = React.useRef<ButtonRef | (ButtonRef & any) | null>(null);
+
+    if (!buttonRef.current) {
+        // @ts-ignore
+        const btn: ButtonRef & {
+            loading: boolean;
+            disabled: boolean;
+            setLoading?(v: boolean): void;
+            setDisabled?(v: boolean): void;
+            ref?: React.RefObject<HTMLButtonElement>;
+        } = {
+            name,
+            // Accessor for "loading" as required by ButtonRef
+            set loading(v: boolean) {
+                setLoadingState(v);
+            },
+            // Accessor for "disable" (note: interface uses `disable`, not `disabled`)
+            //@ts-ignore
+            set disable(v: boolean) {
+                setDisabledState(v);
+            },
+            // Extra properties used by CoreProvider via any-casts
+            get loading() {
+                return loading;
+            },
+            setDisabled(v: boolean) {
+                setDisabledState(v);
+            },
+            get disabled() {
+                return disabled;
+            },
+            ref,
+        };
+
+        // Also expose setLoading for CoreProvider's convenience
+        (btn as any).setLoading = (v: boolean) => {
+            setLoadingState(v);
+        };
+
+        buttonRef.current = btn;
+    }
+
+    // Keep mutable button properties in sync when name changes
+    React.useEffect(() => {
+        if (!buttonRef.current) return;
+        buttonRef.current.name = name;
+    }, [name]);
+
+    // Register this button with the core
+    React.useEffect(() => {
+        if (!buttonRef.current) return;
+
+        // Expose to the core runtime so submitWithAdapter can toggle loading.
+        (form as any).button = buttonRef.current;
+
+        return () => {
+            // On unmount, if the core still points to this button,
+            // we simply clear it.
+            const anyForm = form as any;
+            if (anyForm.button === buttonRef.current) {
+                anyForm.button = null;
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [form]);
+
+    const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+        const currentOpts = optsRef.current;
+        const shouldSubmit = !!currentOpts.submit;
+
+        // Host-level handler first
+        if (currentOpts.onClick) {
+            currentOpts.onClick(event, form);
+        }
+
+        if (event.defaultPrevented) {
+            return;
+        }
+
+        if (shouldSubmit) {
+            // Mark this as the active button for the submit cycle.
+            form.setActiveButton(currentOpts.name);
+
+            // Kick off the standard submit pipeline.
+            form.go();
+        }
+    };
+
+    const setLoading = (v: boolean) => {
+        setLoadingState(v);
+    };
+
+    const setDisabled = (v: boolean) => {
+        setDisabledState(v);
+    };
+
+    return {
+        loading,
+        setLoading,
+        disabled,
+        setDisabled,
+        ref,
+        onClick: handleClick,
+        buttonProps: {
+            ref,
+            disabled: disabled || loading,
+            "data-loading": loading ? "true" : "false",
+            onClick: handleClick,
+        },
+    };
+}

package/src/core/hooks/use-core-context.ts

@@ -0,0 +1,20 @@
+// src/core/hooks/use-core-context.ts
+import { useContext } from "react";
+import { CoreContextReact } from "@/core/context";
+import type { CoreContext, Dict } from "@/schema/core";
+
+/**
+ * Typed hook to access the current core/form context.
+ *
+ * Must be used inside a <CoreProvider>. If no provider is found,
+ * this will throw to make misuse obvious.
+ */
+export function useCoreContext<V extends Dict = Dict>(): CoreContext<V> {
+    const ctx = useContext(CoreContextReact);
+
+    if (!ctx) {
+        throw new Error("useCoreContext must be used within a <CoreProvider>.");
+    }
+
+    return ctx as CoreContext<V>;
+}

package/src/core/hooks/use-core.ts

@@ -0,0 +1,13 @@
+// src/core/hooks/use-core.ts
+import type { CoreContext, Dict } from "@/schema/core";
+import { useCoreContext } from "./use-core-context";
+
+/**
+ * Convenience alias for useCoreContext.
+ *
+ * This mirrors the legacy useForm hook: you get the full CoreContext,
+ * and can call core.values(), core.submit(), core.go(), etc.
+ */
+export function useCore<V extends Dict = Dict>(): CoreContext<V> {
+    return useCoreContext<V>();
+}