@timeax/form-palette 0.0.1

package/src/adapters/index.ts

@@ -0,0 +1,91 @@
+// src/adapters/index.ts
+
+import axios from "axios";
+import { registerAdapter } from "@/core/adapter-registry";
+import type { AdapterKey } from "@/schema/adapter";
+
+import { createAxiosAdapter } from "./axios";
+import { createInertiaAdapter } from "./inertia";
+
+// Re-export core adapter types + helpers so hosts can import from a single place.
+export * from "@/schema/adapter";
+export * from "@/core/adapter-registry";
+
+// Re-export the concrete factories for hosts that want manual wiring.
+export { createAxiosAdapter, createInertiaAdapter };
+
+/**
+ * Register the Axios adapter under the "axios" key.
+ *
+ * This performs a basic runtime check to make sure Axios is present.
+ * If Axios isn't available or doesn't look like a proper Axios instance,
+ * an error is thrown.
+ */
+export function registerAxiosAdapter(): void {
+   // Basic sanity check – if this fails, something is wrong with the axios import.
+   if (!axios || typeof axios.request !== "function") {
+      throw new Error(
+         "[form-palette] Axios does not appear to be available. " +
+         "Make sure 'axios' is installed and resolvable before calling registerAxiosAdapter()."
+      );
+   }
+
+   registerAdapter<"axios">("axios", createAxiosAdapter);
+}
+
+/**
+ * Register the Inertia adapter under the "inertia" key.
+ *
+ * This explicitly tests that '@inertiajs/react' can be imported and that
+ * it exposes a router with a .visit() method. If not, an error is thrown.
+ *
+ * Note:
+ * - This function is async because it uses dynamic import.
+ * - Call it at bootstrap time and await it:
+ *
+ *     await registerInertiaAdapter();
+ */
+export async function registerInertiaAdapter(): Promise<void> {
+   try {
+      const mod: any = await import("@inertiajs/react");
+      const router = mod?.router ?? mod?.Inertia;
+
+      if (!router || typeof router.visit !== "function") {
+         throw new Error(
+            "[form-palette] '@inertiajs/react' was imported, " +
+            "but no router with a .visit() method was found."
+         );
+      }
+   } catch (error) {
+      throw new Error(
+         "[form-palette] Failed to import '@inertiajs/react'. " +
+         "Cannot register the 'inertia' adapter. " +
+         "Make sure '@inertiajs/react' is installed and resolvable."
+      );
+   }
+
+   registerAdapter<"inertia">("inertia", createInertiaAdapter);
+}
+
+/**
+ * Optional helper: convenience registration for known adapter keys.
+ *
+ * This is purely ergonomic; you can also call registerAxiosAdapter /
+ * registerInertiaAdapter directly.
+ */
+export async function registerKnownAdapter(key: AdapterKey): Promise<void> {
+   switch (key) {
+      case "axios":
+         registerAxiosAdapter();
+         return;
+      case "inertia":
+         await registerInertiaAdapter();
+         return;
+      default:
+         // For now, we only special-case axios/inertia here.
+         // Other adapters can be registered by calling registerAdapter() directly.
+         throw new Error(
+            `[form-palette] registerKnownAdapter: adapter "${key}" is not handled here.`
+         );
+   }
+}

package/src/adapters/inertia.ts

@@ -0,0 +1,187 @@
+import { VisitOptions, Page } from './../../../../node_modules/@inertiajs/core/types/types.d';
+// src/adapters/inertia.ts
+import type {
+   NamedAdapterFactory,
+   NamedAdapterConfig,
+   AdapterResult,
+   AdapterOk,
+   AdapterError,
+} from "@/schema/adapter";
+
+// (Adapters augmentation is above in the same file)
+
+/**
+ * Lazy-load the Inertia router from '@inertiajs/react'.
+ *
+ * This keeps '@inertiajs/react' out of the main bundle until an
+ * Inertia adapter is actually used.
+ */
+async function loadInertiaRouter() {
+   const mod: any = await import("@inertiajs/react");
+   const router = mod?.router ?? mod?.Inertia;
+
+   if (!router || typeof router.visit !== "function") {
+      throw new Error(
+         "[form-palette] Inertia router not found in @inertiajs/react"
+      );
+   }
+
+   return router as {
+      visit: (url: string, options?: VisitOptions) => void;
+   };
+}
+
+/**
+ * Shape raw Inertia errors into something with `.errors`
+ * so Form Palette's autoErr branch can pick them up.
+ */
+function normalizeInertiaError(
+   raw: unknown
+): { errors: Record<string, string | string[]> } | unknown {
+   if (
+      raw &&
+      typeof raw === "object" &&
+      "errors" in (raw as any) &&
+      typeof (raw as any).errors === "object"
+   ) {
+      // Already in { errors: {...} } shape
+      return raw as any;
+   }
+
+   if (
+      raw &&
+      typeof raw === "object" &&
+      !("errors" in (raw as any))
+   ) {
+      // Inertia usually passes the error bag directly to onError.
+      return { errors: raw as Record<string, string | string[]> };
+   }
+
+   return raw;
+}
+
+export const createInertiaAdapter: NamedAdapterFactory<"inertia"> = (
+   config: NamedAdapterConfig<"inertia">
+): AdapterResult<AdapterOk<"inertia">> => {
+   const { method, url, data, callbacks } = config;
+
+   const upperMethod = method.toUpperCase() as VisitOptions["method"];
+
+   /**
+    * Build VisitOptions with callbacks wired to AdapterCallbacks
+    * + optional Promise resolve/reject.
+    */
+   function buildOptions(
+      resolve?: (value: AdapterOk<"inertia">) => void,
+      reject?: (reason: AdapterError<"inertia">) => void,
+      extraOptions?: unknown
+   ): VisitOptions {
+      const merged: VisitOptions = {
+         method: upperMethod,
+         //@ts-ignore
+         data,
+         onSuccess: (page: Page) => {
+            callbacks?.onSuccess?.(page as AdapterOk<"inertia">);
+            resolve?.(page as AdapterOk<"inertia">);
+         },
+         onError: (rawErrors: any) => {
+            const payload = normalizeInertiaError(rawErrors);
+            callbacks?.onError?.(payload as AdapterError<"inertia">);
+            reject?.(payload as AdapterError<"inertia">);
+         },
+         onFinish: () => {
+            callbacks?.onFinish?.();
+         },
+         ...(extraOptions as VisitOptions | undefined),
+      };
+
+      return merged;
+   }
+
+   function submit(options?: unknown): void {
+      // Fire-and-forget; we still propagate callbacks and finish.
+      (async () => {
+         let finished = false;
+         const finish = () => {
+            if (finished) return;
+            finished = true;
+            callbacks?.onFinish?.();
+         };
+
+         try {
+            const router = await loadInertiaRouter();
+            const visitOptions = buildOptions(undefined, undefined, options);
+            // NOTE: buildOptions already wires onFinish, so we
+            // call finish() only if the lazy import itself fails.
+            router.visit(url, visitOptions);
+         } catch (error) {
+            const payload = normalizeInertiaError(error);
+            callbacks?.onError?.(payload as AdapterError<"inertia">);
+            finish();
+         }
+      })();
+   }
+
+   function send(options?: unknown): Promise<AdapterOk<"inertia">> {
+      return new Promise(async (resolve, reject) => {
+         let finished = false;
+         const finish = () => {
+            if (finished) return;
+            finished = true;
+            callbacks?.onFinish?.();
+         };
+
+         try {
+            const router = await loadInertiaRouter();
+            const visitOptions = buildOptions(
+               (page) => {
+                  // buildOptions' onFinish will call onFinish();
+                  resolve(page);
+               },
+               (err) => {
+                  reject(err);
+               },
+               options
+            );
+            router.visit(url, visitOptions);
+         } catch (error) {
+            const payload = normalizeInertiaError(error);
+            callbacks?.onError?.(payload as AdapterError<"inertia">);
+            finish();
+            reject(payload as AdapterError<"inertia">);
+         }
+      });
+   }
+
+   function run(options?: unknown): Promise<AdapterOk<"inertia">> {
+      // Same as send(), so the core can safely `await adapter.run()`
+      // if it wants, or ignore the promise if it doesn't care.
+      return send(options);
+   }
+
+   return {
+      submit,
+      send,
+      run,
+   };
+};
+
+declare module "@/schema/adapter" {
+   interface Adapters {
+      inertia: {
+         /**
+          * What adapter.send() resolves with for Inertia.
+          * This is the Page object passed to onSuccess.
+          */
+         ok: Page<any>;
+
+         /**
+          * What callbacks.onError receives for Inertia.
+          *
+          * We shape this as `{ errors: ErrorBag }` so Form Palette's
+          * autoErr branch can see `.errors`.
+          */
+         err: { errors: Record<string, string | string[]> } | unknown;
+      };
+   }
+}

package/src/core/adapter-registry.ts

@@ -0,0 +1,87 @@
+// src/core/adapter-registry.ts
+
+import { AdapterKey, AdapterOk, NamedAdapterFactory } from "@/schema/adapter";
+
+/**
+ * Internal registry of adapter factories.
+ *
+ * We keep it simple: a plain JS object keyed by AdapterKey.
+ */
+const registry: Partial<
+    Record<AdapterKey, NamedAdapterFactory<AdapterKey, any>>
+> = {};
+
+/**
+ * Built-in 'local' adapter.
+ *
+ * Semantics:
+ * - send(options?) resolves to `{ data: Body }`
+ * - submit/run do nothing by default (no side effects)
+ *
+ * The core will typically call onSubmitted with the result of send().
+ */
+export const localAdapter: NamedAdapterFactory<"local", any> = (config) => {
+    return {
+        submit() {
+            // no-op; core is responsible for calling onSubmitted
+            // using send() if it chooses to.
+        },
+        async send() {
+            const result: AdapterOk<"local"> = { data: config.data };
+
+            if (config.callbacks?.onSuccess) {
+                config.callbacks.onSuccess(result);
+            }
+
+            if (config.callbacks?.onFinish) {
+                config.callbacks.onFinish();
+            }
+
+            return result;
+        },
+        run() {
+            // By default, run behaves like submit (no-op),
+            // but hosts can choose to always call send() instead.
+            this.submit();
+        },
+    };
+};
+
+/**
+ * Initialise registry with the built-in 'local' adapter.
+ */
+registry.local = localAdapter as NamedAdapterFactory<AdapterKey, any>;
+
+/**
+ * Register or override an adapter factory for a given key.
+ *
+ * Hosts can call this at bootstrap time, e.g.:
+ *
+ *   registerAdapter<'axios'>('axios', axiosAdapter);
+ */
+export function registerAdapter<K extends AdapterKey, Body = any>(
+    key: K,
+    factory: NamedAdapterFactory<K, Body>
+): void {
+    registry[key] = factory as NamedAdapterFactory<AdapterKey, any>;
+}
+
+/**
+ * Lookup an adapter factory by key.
+ *
+ * If no adapter is found for the given key, this returns undefined.
+ */
+export function getAdapter<K extends AdapterKey>(
+    key: K
+): NamedAdapterFactory<K, any> | undefined {
+    const factory = registry[key];
+
+    return factory as NamedAdapterFactory<K, any> | undefined;
+}
+
+/**
+ * Check whether an adapter is registered for the given key.
+ */
+export function hasAdapter(key: AdapterKey): boolean {
+    return typeof registry[key] === "function";
+}

package/src/core/bound/bind-host.ts

@@ -0,0 +1,14 @@
+// src/core/bound/bind-host.ts (or inline in binder-registry.ts)
+import type { Dict, CoreContext } from "@/schema/core";
+import type { Field } from "@/schema/field";
+
+/**
+ * Minimal surface needed for bound helpers.
+ *
+ * CoreContext already satisfies this, and FieldRegistry can be made to
+ * satisfy it as well (via getBind).
+ */
+export interface BindHost<V extends Dict = Dict> {
+    getBind(id: string): Field | undefined;
+    controlButton?(): void;
+}

package/src/core/bound/observe-bound-field.ts

@@ -0,0 +1,172 @@
+// src/core/bound/observe-bound-field.ts
+
+import type { Dict } from "@/schema/core";
+import type { Field } from "@/schema/field";
+import type { BindHost } from "@/core/bound/bind-host";
+
+/** Get the live bound field (if mounted and present). */
+export function getBoundField<V extends Dict>(
+    host: BindHost<V>,
+    bindId: string
+): Field | undefined {
+    return host.getBind(bindId);
+}
+
+export function hasBoundField<V extends Dict>(
+    host: BindHost<V>,
+    bindId: string
+): boolean {
+    return !!getBoundField(host, bindId);
+}
+
+export function readBoundValue<T = unknown, V extends Dict = Dict>(
+    host: BindHost<V>,
+    bindId: string
+): T | undefined {
+    return getBoundField(host, bindId)?.value as T | undefined;
+}
+
+export function setBoundValue<T = unknown, V extends Dict = Dict>(
+    host: BindHost<V>,
+    bindId: string,
+    value: T,
+    variant: string = "util"
+): boolean {
+    const f = getBoundField(host, bindId);
+    if (!f) return false;
+
+    (f as any).value = value as unknown;
+
+    // optional: dirty/enable logic if host supports it
+    try {
+        host.controlButton?.();
+    } catch {
+        // ignore
+    }
+
+    (f as any).onChange?.(value, undefined, variant);
+    return true;
+}
+
+export function setBoundError<V extends Dict>(
+    _host: BindHost<V>, // host not strictly needed here
+    bindId: string,
+    msg: string
+): boolean {
+    const f = _host.getBind(bindId);
+    if (!f) return false;
+    (f as any).error = msg ?? "";
+    return true;
+}
+
+export function validateBoundField<V extends Dict>(
+    host: BindHost<V>,
+    bindId: string,
+    report = true
+): boolean {
+    const f = getBoundField(host, bindId);
+    if (!f) return false;
+    return !!(f as any).validate?.(report);
+}
+
+/**
+ * Observe a bound field for value/error + liveness.
+ */
+export function observeBoundField<T = unknown, V extends Dict = Dict>(
+    host: BindHost<V>,
+    bindId: string,
+    handler: (evt: {
+        exists: boolean;
+        field?: Field;
+        value?: T;
+        error?: string;
+    }) => void,
+    pollMs = 300
+): () => void {
+    let current: Field | undefined = getBoundField(host, bindId);
+    let restoreOnChange: Field["onChange"] | undefined;
+
+    const fire = () => {
+        if (!current) {
+            handler({ exists: false });
+            return;
+        }
+
+        handler({
+            exists: true,
+            field: current,
+            value: (current as any).value as T,
+            error: (current as any).error,
+        });
+    };
+
+    const wire = () => {
+        const f = getBoundField(host, bindId);
+
+        if (f === current) return;
+
+        if (current && restoreOnChange) {
+            (current as any).onChange = restoreOnChange;
+            restoreOnChange = undefined;
+        }
+
+        current = f;
+
+        if (current) {
+            restoreOnChange = (current as any).onChange;
+            (current as any).onChange = (
+                next: unknown,
+                prev: unknown,
+                variant: string
+            ) => {
+                restoreOnChange?.(next, prev, variant);
+                handler({
+                    exists: true,
+                    field: current,
+                    value: next as T,
+                    error: (current as any).error,
+                });
+            };
+        }
+
+        fire();
+    };
+
+    // initial
+    wire();
+
+    let intervalId: number | undefined;
+    if (typeof window !== "undefined") {
+        intervalId = window.setInterval(wire, pollMs);
+    }
+
+    let mo: MutationObserver | undefined;
+    if (
+        typeof MutationObserver !== "undefined" &&
+        typeof document !== "undefined"
+    ) {
+        try {
+            mo = new MutationObserver(wire);
+            mo.observe(document.body, {
+                childList: true,
+                subtree: true,
+            });
+        } catch {
+            // ignore
+        }
+    }
+
+    return () => {
+        if (typeof window !== "undefined" && typeof intervalId === "number") {
+            window.clearInterval(intervalId);
+        }
+        if (mo) {
+            mo.disconnect();
+            mo = undefined;
+        }
+        if (current && restoreOnChange) {
+            (current as any).onChange = restoreOnChange;
+            restoreOnChange = undefined;
+        }
+    };
+}

package/src/core/bound/wait-for-bound-field.ts

@@ -0,0 +1,57 @@
+// src/core/bound/wait-for-bound-field.ts
+
+import type { Dict } from "@/schema/core";
+import type { Field } from "@/schema/field";
+import type { BindHost } from "@/core/bound/bind-host";
+import {
+    getBoundField,
+    observeBoundField,
+} from "@/core/bound/observe-bound-field";
+
+export function waitForBoundField<V extends Dict>(
+    host: BindHost<V>,
+    bindId: string,
+    timeoutMs = 5000
+): Promise<Field> {
+    const existing = getBoundField(host, bindId);
+    if (existing) return Promise.resolve(existing);
+
+    return new Promise<Field>((resolve, reject) => {
+        let settled = false;
+
+        const settleResolve = (field: Field) => {
+            if (settled) return;
+            settled = true;
+            stop();
+            clearTimeout(to);
+            resolve(field);
+        };
+
+        const settleReject = (error: Error) => {
+            if (settled) return;
+            settled = true;
+            stop();
+            clearTimeout(to);
+            reject(error);
+        };
+
+        const stop = observeBoundField(
+            host,
+            bindId,
+            (e) => {
+                if (e.exists && e.field) {
+                    settleResolve(e.field);
+                }
+            },
+            150
+        );
+
+        const to = setTimeout(() => {
+            settleReject(
+                new Error(
+                    `waitForBoundField('${bindId}') timed out after ${timeoutMs}ms`
+                )
+            );
+        }, timeoutMs);
+    });
+}

package/src/core/context.ts

@@ -0,0 +1,23 @@
+// src/core/context.ts
+import React from "react";
+import type { CoreContext, Dict } from "@/schema/core";
+
+/**
+ * Non-generic alias for the core context type used at runtime.
+ *
+ * We store CoreContext<Dict> in React context and let
+ * caller-side hooks (useCore, useCoreContext, etc.) cast
+ * to a more specific generic shape when needed.
+ */
+export type AnyCoreContext = CoreContext<Dict>;
+
+/**
+ * React context carrying the current form/core instance.
+ *
+ * - Provider is set up in core-provider.tsx.
+ * - Consumers should generally use the typed hook in
+ *   hooks/use-core-context.ts instead of reading this directly.
+ */
+export const CoreContextReact = React.createContext<AnyCoreContext | null>(
+    null
+);