@voltro/client 0.50.1 → 0.52.0

package/dist/index.d.ts

@@ -961,6 +961,22 @@ export declare type FilterKind = 'text' | 'select' | 'multi-select' | 'number-ra
  *  input field → one FilterDescriptor. Pure. */
 export declare const filtersFromSchema: (schema: Schema.Schema.Any) => ReadonlyArray<FilterDescriptor>;
 
+/** DOM id of the JSON script the 422 re-render embeds (survives the
+ *  `interactive:'none'` strip — it is neither `type="module"` nor `src`). */
+export declare const FORM_FLASH_SCRIPT_ID = "__voltro_form_flash__";
+
+/** Hidden field carrying the form's instance key (multi-form pages). */
+export declare const FORM_KEY_FIELD = "__voltro_form";
+
+/** URL prefix the web listener mounts the no-JS endpoint under. */
+export declare const FORM_PATH_PREFIX = "/form/";
+
+/** Hidden field carrying the declared success-redirect path. */
+export declare const FORM_REDIRECT_FIELD = "__voltro_redirect";
+
+/** The path a native `<AutoForm>` POST goes to. */
+export declare const formActionPath: (mutationTag: string) => string;
+
 export declare interface FormBinding<Input, Output> {
     /** Ordered, render-agnostic field list derived from the input schema. */
     readonly fields: ReadonlyArray<FieldDescriptor>;
@@ -972,6 +988,9 @@ export declare interface FormBinding<Input, Output> {
     readonly pending: boolean;
     /** The mutation's typed failure, if the last submit threw. */
     readonly submitError: unknown | undefined;
+    /** A form-level (non-field) error carried in from a failed no-JS POST —
+     *  the RPC refused after valid input. Cleared by the next submit/reset. */
+    readonly formError: string | undefined;
     readonly data: Output | undefined;
     readonly setValue: (name: string, value: unknown) => void;
     readonly setValues: (patch: Partial<Input>) => void;
@@ -981,6 +1000,50 @@ export declare interface FormBinding<Input, Output> {
     readonly submit: () => Promise<Output | undefined>;
 }
 
+/**
+ * Convert posted form entries into the input object the mutation's schema
+ * decodes — the shape `validateFields` (and the RPC payload) expects.
+ *
+ * Mapping rules (the documented contract):
+ * - **checkbox/switch**: present → `true`, absent → `false`. A native POST
+ *   omits an unchecked checkbox entirely, so absence is data, not a gap.
+ * - **number**: `Number(raw)`; `''` → the field is omitted (`undefined`), so
+ *   an optional number stays absent and a required one reports "missing"
+ *   instead of silently becoming `0`.
+ * - **date/datetime**: the string passes through (the schema's encoded side);
+ *   `''` → omitted, same reasoning as number.
+ * - **arrays** (multi-select): `getAll` semantics — every entry under the key,
+ *   items converted per the array's item type (number items → `Number`).
+ * - **unknown keys are dropped**: only names the schema declares are mapped,
+ *   so protocol fields (`__voltro_form`, …) never reach the input object —
+ *   the server rejects undeclared fields, and a hidden bookkeeping field must
+ *   not turn every no-JS submit into a validation error.
+ */
+export declare const formDataToInput: (schema: Schema.Schema.Any, entries: Iterable<FormEntry>) => Record<string, unknown>;
+
+/** One posted entry. File entries must be filtered out by the caller —
+ *  uploads are a declared limit of the no-JS path. */
+export declare type FormEntry = readonly [name: string, value: string];
+
+/**
+ * The error/values payload a failed no-JS form POST carries back into the
+ * 422 re-render. Keyed by `formKey` so a page with several forms re-fills
+ * only the one that was submitted. The SSR render passes it through the
+ * server-request context; the client reads the same payload back off the
+ * `#__voltro_form_flash__` JSON script, so a late-hydrating page shows the
+ * identical state (no mismatch, no vanished errors).
+ */
+export declare interface FormFlashPayload {
+    /** The submitted form's key — `<AutoForm formKey>` or its mutation tag. */
+    readonly formKey: string;
+    /** The mapped input values as posted (pre-decode), to re-fill the fields. */
+    readonly values: Readonly<Record<string, unknown>>;
+    /** First error per field — the `validateFields` shape. */
+    readonly errors: Readonly<Record<string, string>>;
+    /** A non-field error (the RPC refused after valid input: guard, server). */
+    readonly formError?: string;
+}
+
 export declare interface FrameworkRuntimes {
     /** Look up an api handle (runtime + cache) by name. Throws if no such api was mounted. */
     readonly get: (name: string) => ApiHandle;
@@ -1010,6 +1073,32 @@ export declare const getMutationNotifier: () => MutationNotifier | undefined;
 /** Read the current feed. Newest-first; up to MAX_MUTATIONS entries. */
 export declare const getMutations: () => ReadonlyArray<MutationEvent>;
 
+/**
+ * A process-wide singleton React context, pinned on the global symbol registry.
+ *
+ * WHY this exists: the SSG prerender (`voltro build`) loads the framework
+ * through TWO separate module instances — the renderer comes in via Vite's
+ * `ssrLoadModule('@voltro/web/ssr')` (Vite-transformed) while a page's own
+ * framework import is externalised to Node — so a plain `createContext()`
+ * in a shared module is evaluated twice and yields two DISTINCT context
+ * objects. The `<Router>` provider then holds one while the page's
+ * `useLocation()` reads the other, which throws "Router hooks must be used
+ * inside <Router>." The same duplicate-instance hazard shows up wherever a
+ * deployment ends up with two copies of a package (the classic dual-package
+ * hazard, monorepo hoisting quirks, separate SSR vs client bundles).
+ *
+ * Resolving every context through `Symbol.for(...)` on `globalThis` makes all
+ * module copies share ONE instance, so provider and consumer can never diverge.
+ * A duplicated copy of THIS helper is harmless — both copies hit the same
+ * global registry entry.
+ *
+ * Lives in @voltro/client (the lowest React-carrying package) so both
+ * @voltro/web and @voltro/ui reach it without a cycle; the key prefix keeps
+ * its historical spelling on purpose — a mixed dist/src world must resolve
+ * to the same registry entries.
+ */
+export declare const globalContext: <T>(key: string, initial: T) => Context<T>;
+
 /** Is this the framework's `Unauthenticated`? Matched on `_tag`, the wire
  *  contract, rather than on an instance — the error crosses a package boundary
  *  and may be re-created by the decoder. */
@@ -1832,6 +1921,29 @@ export declare type SequenceResult<Ctx> = {
     }>;
 };
 
+export declare const ServerRequestContext: Context<ServerRequestContextValue | null>;
+
+export declare interface ServerRequestContextValue {
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Raw request URL as it came off the wire (path + query). Useful
+     *  for SSR pages that need to read `?q=…` style search params
+     *  without touching anything client-only. Empty string for build-
+     *  time SSG renders where there is no incoming request. */
+    readonly url: string;
+    /** Present ONLY on the 422 re-render of a failed no-JS form POST:
+     *  the submitted values + field errors, keyed by formKey. Travels on
+     *  the EXISTING request context deliberately — a dedicated provider
+     *  would add a fiber fork the client boot does not have, and every
+     *  ancestor arity difference shifts every useId in the app. */
+    readonly formFlash?: FormFlashPayload;
+}
+
+export declare const ServerRequestProvider: ({ value, children, }: {
+    readonly value: ServerRequestContextValue;
+    readonly children: ReactNode;
+}) => ReactNode;
+
 /** Register (or clear) the app-wide notifier that `notify:` routes to. Call once
  *  at boot, next to your toast provider. */
 export declare const setMutationNotifier: (notifier: MutationNotifier | undefined) => void;
@@ -3048,8 +3160,27 @@ export declare interface UseFormBindingOptions<Input> {
     readonly schema?: Schema.Schema.Any;
     /** Initial field values. */
     readonly defaults?: Partial<Input>;
+    /** The failed no-JS POST's payload for THIS form (`useFormFlash` from
+     *  @voltro/web resolves it, SSR and client alike). When present it seeds
+     *  the initial values + field errors, so the 422 re-render shows the
+     *  submitted state server-side and hydrates to the identical state. */
+    readonly flash?: FormFlashPayload | undefined;
 }
 
+/**
+ * The failed-no-JS-POST payload for ONE form, or `undefined`.
+ *
+ * On the server (the 422 re-render) it comes off the request context; on the
+ * client it is read back from the `#__voltro_form_flash__` JSON script the
+ * same response embedded. Both carry the SAME payload, so a page that loads
+ * its bundle after a native submit hydrates to exactly the server-rendered
+ * state — errors visible, values filled, no mismatch.
+ *
+ * Keyed: only the form whose `formKey` was submitted receives the payload —
+ * two `<AutoForm>`s on one page re-fill only the one that POSTed.
+ */
+export declare const useFormFlash: (formKey: string) => FormFlashPayload | undefined;
+
 /** The field shape a `<AutoForm mutation=…>` will render — from the mutation's
  *  input Schema. Use it to render a matching skeleton while anything the form
  *  depends on is still loading. */
@@ -3198,6 +3329,8 @@ export declare interface UseSequenceResult {
     readonly failedStep: string | undefined;
 }
 
+export declare const useServerRequest: () => ServerRequestContextValue | null;
+
 export declare function useSubscription<T = unknown>(apiName: string, rpcTag: string, input: Readonly<Record<string, unknown>>, options: SubscriptionOptions<T> & {
     readonly initialSnapshot: T;
 }): SubscriptionStateWithFallback<T>;