@timber-js/app 0.2.0-alpha.211 → 0.2.0-alpha.213

package/dist/client/index.js

@@ -8,7 +8,7 @@ import { t as getSsrData } from "../_chunks/ssr-data-nA3I70_n.js";
 import { t as getLinkCodec } from "../_chunks/codec-registry-oOUxugz3.js";
 import { i as useNavigationContext, n as useSegmentContext } from "../_chunks/segment-context-xtPUGfdq.js";
 import { n as useQueryStates } from "../_chunks/use-query-states-I3JMng6J.js";
-import React, { createContext, useActionState as useActionState$1, useContext, useRef, useState, useTransition } from "react";
+import React, { createContext, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
 /**
@@ -577,53 +577,14 @@ function useSelectedLayoutSegments(parallelRouteKey) {
 /**
 * Client-side form utilities for server actions.
 *
-* Exports a typed `useActionState` that understands the action builder's result shape.
-* Result is typed to:
-*   { data: T } | { validationErrors: Record<string, string[]> } | { serverError: { code, data? } } | null
-*
-* The action builder emits a function that satisfies both the direct call signature
-* and React's `(prevState, formData) => Promise<State>` contract.
+* Forms use React's own `useActionState`: an action built with
+* `createActionClient` already has the `(prevState, payload)` signature it
+* calls, and the result is typed from it. `parseFormErrors` reads the errors
+* out of that result.
 *
 * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
 */
 /**
-* Typed wrapper around React 19's `useActionState` that understands
-* the timber action builder's result shape.
-*
-* @param action - A server action created with createActionClient or a raw 'use server' function.
-* @param initialState - Initial state, typically `null`. Pass `getFormFlash()` for no-JS
-*   progressive enhancement — the flash seeds the initial state so the form has a
-*   single source of truth for both with-JS and no-JS paths.
-* @param permalink - Optional permalink for progressive enhancement (no-JS fallback URL).
-*
-* @example
-* ```tsx
-* 'use client'
-* import { useActionState } from '@timber-js/app/client'
-* import { createTodo } from './actions'
-*
-* export function NewTodoForm({ flash }) {
-*   const [result, action, isPending] = useActionState(createTodo, flash)
-*   return (
-*     <form action={action}>
-*       <input name="title" />
-*       {result?.validationErrors?.title && <p>{result.validationErrors.title}</p>}
-*       <button disabled={isPending}>Add</button>
-*     </form>
-*   )
-* }
-* ```
-*/
-function useActionState(action, initialState, permalink) {
-	const [result, formAction, isPending] = useActionState$1(action, initialState, permalink);
-	return [
-		result,
-		formAction,
-		isPending,
-		deriveFormErrors(result)
-	];
-}
-/**
 * Hook for calling a server action imperatively (not via a form).
 * Returns [execute, isPending] where execute accepts the input directly.
 *
@@ -638,20 +599,31 @@ function useActionState(action, initialState, permalink) {
 function useFormAction(action) {
 	const [isPending, startTransition] = useTransition();
 	const execute = (input) => {
-		return new Promise((resolve) => {
+		return new Promise((resolve, reject) => {
 			startTransition(async () => {
-				resolve(await action(input));
+				try {
+					resolve(await action(input));
+				} catch (error) {
+					reject(error);
+				}
 			});
 		});
 	};
 	return [execute, isPending];
 }
 /**
-* Derive FormErrorsResult from an action result.
-* Used internally by useActionState 4th tuple element.
-* @internal — exported for test access only.
+* Read the errors out of an action result — the state `useActionState`
+* returns. `_root` validation errors are form-level; every other key is a
+* field.
+*
+* @example
+* ```tsx
+* const [result, action, isPending] = useActionState(createTodo, null)
+* const errors = parseFormErrors(result)
+* errors.getFieldError('title') // first message for the field, or null
+* ```
 */
-function deriveFormErrors(result) {
+function parseFormErrors(result) {
 	const empty = {
 		fieldErrors: {},
 		formErrors: [],
@@ -680,6 +652,94 @@ function deriveFormErrors(result) {
 	};
 }
 //#endregion
+//#region src/client/use-form-field.ts
+/**
+* useFormField — state for a form field that needs JavaScript (a combobox, a
+* chip list, a row list), made to behave like a native uncontrolled input.
+*
+* React resets a form after its action settles, so a native field with a
+* `defaultValue` lands on whatever default the page now renders: the action's
+* `submittedValues`, or fresh page data after a redirect. State held in
+* `useState` misses that reset and keeps showing the pre-submit edit. This
+* hook shows `defaultValue` until the user edits, and drops the edit when the
+* form resets, so it lands where the native fields do.
+*
+* See design/08-forms-and-actions.md §"The Form Model".
+*/
+/**
+* State for a field that follows its form's reset.
+*
+* Returns `[value, setValue, ref]`. Attach `ref` to any element inside the
+* `<form>`, and render the value into the form data yourself (usually a
+* hidden input). `value` is `defaultValue` until `setValue` is called, and is
+* `defaultValue` again after the form resets, unless the form cancels its
+* `reset` event. An edit dispatches a bubbling `change` event from the `ref`
+* element after it commits, so a native `change` listener on the form sees it
+* as it sees a native input's (React's synthetic `onChange` reports only
+* inputs, selects and textareas). A reset and a new default fire none, as
+* they fire none for a native input.
+*
+* @example
+* ```tsx
+* // draft: the form's defaults, read from result?.submittedValues ?? pageData
+* const [tags, setTags, ref] = useFormField(draft.tags);
+* <div ref={ref}>
+*   <input type="hidden" name="tags" value={tags.join(',')} />
+*   <TagPicker value={tags} onChange={setTags} />
+* </div>
+* ```
+*/
+function useFormField(defaultValue) {
+	const [edit, setEdit] = useState(null);
+	const value = edit ? edit.value : defaultValue;
+	const defaultRef = useRef(defaultValue);
+	useLayoutEffect(() => {
+		defaultRef.current = defaultValue;
+	});
+	const pendingResets = useRef([]);
+	const takeResets = useCallback(() => {
+		const over = pendingResets.current.filter((e) => e.eventPhase === Event.NONE);
+		if (over.length === 0) return false;
+		pendingResets.current = pendingResets.current.filter((e) => !over.includes(e));
+		return over.some((e) => !e.defaultPrevented);
+	}, []);
+	const setValue = useCallback((next) => {
+		const wasReset = takeResets();
+		setEdit((latest) => {
+			const current = wasReset ? null : latest;
+			const base = current ? current.value : defaultRef.current;
+			const value = next instanceof Function ? next(base) : next;
+			return Object.is(value, base) ? current : { value };
+		});
+	}, [takeResets]);
+	const element = useRef(null);
+	const ref = useCallback((el) => {
+		element.current = el;
+		const form = el?.closest("form");
+		if (!form) return;
+		const onReset = (event) => {
+			pendingResets.current.push(event);
+			queueMicrotask(() => {
+				if (takeResets()) setEdit(null);
+			});
+		};
+		form.addEventListener("reset", onReset);
+		return () => {
+			element.current = null;
+			pendingResets.current = [];
+			form.removeEventListener("reset", onReset);
+		};
+	}, [takeResets]);
+	useEffect(() => {
+		if (edit) element.current?.dispatchEvent(new Event("change", { bubbles: true }));
+	}, [edit]);
+	return [
+		value,
+		setValue,
+		ref
+	];
+}
+//#endregion
 //#region src/client/params-context.ts
 /**
 * Segment params context — the one channel params use to reach the browser.
@@ -769,6 +829,6 @@ function useSegmentParams(segmentPath) {
 	return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);
 }
 //#endregion
-export { Link, LinkStatusContext, buildLinkProps, interpolateParams, mergePreservedSearchParams, replaceUrl, resolveHref, useActionState, useFormAction, useLinkStatus, usePathname, usePendingNavigation, useQueryStates, useRouter, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateNavigationHref as validateLinkHref };
+export { Link, LinkStatusContext, buildLinkProps, interpolateParams, mergePreservedSearchParams, parseFormErrors, replaceUrl, resolveHref, useFormAction, useFormField, useLinkStatus, usePathname, usePendingNavigation, useQueryStates, useRouter, useSegmentParams, useSelectedLayoutSegment, useSelectedLayoutSegments, validateNavigationHref as validateLinkHref };
 
 //# sourceMappingURL=index.js.map