@k8ordo/form 0.1.1 → 1.0.0

package/README.md

@@ -1,8 +1,8 @@
 # @k8ordo/form
 
 Derive HTML constraint attributes, error messages, and server-side validation
-from one zod schema — forms whose two sides cannot disagree, because the client
-side is derived, never written. Works with JavaScript disabled or not yet
+from one zod schema — the client side is derived, never written, so there is no
+second copy of a constraint to drift. Works with JavaScript disabled or not yet
 loaded.
 
 Like every [k8ordo](https://ordo.k8o.me) package it assumes React 19 and Server
@@ -22,16 +22,20 @@ pnpm add @k8ordo/form zod
 
 ## Peer Dependencies
 
-| Package        | Version  | Needed for                    |
-| -------------- | -------- | ----------------------------- |
-| `react`        | ≥19.2.6  | `useForm` and Server Actions  |
-| `react-dom`    | ≥19.2.6  | rendering                     |
-| `zod`          | ^4.4.3   | the schema (`zod/mini` works) |
-| `typescript`   | ≥7.0.2   | the shipped type declarations |
-| `@types/react` | ≥19.2.18 | the shipped type declarations |
+<!-- peers -->
+
+| Package        | Version | Required | Needed for                    |
+| -------------- | ------- | -------- | ----------------------------- |
+| `react`        | ≥19.3.0 | yes      | `useForm` and Server Actions  |
+| `react-dom`    | ≥19.3.0 | yes      | rendering                     |
+| `zod`          | ^4.4.3  | yes      | the schema (`zod/mini` works) |
+| `typescript`   | ≥7.0.0  | optional | the shipped type declarations |
+| `@types/react` | ≥19.3.0 | optional | the shipped type declarations |
+
+<!-- /peers -->
 
 zod never reaches the browser: the schema is read on the server and crosses the
-RSC boundary as plain data. The client entry is ~2.7 kB gzipped.
+RSC boundary as plain data. The client entry is ~2.8 kB gzipped.
 
 ## Quick Start
 
@@ -39,7 +43,7 @@ One schema drives everything — the attributes, the messages, and the
 server-side validation:
 
 ```ts
-// schema.ts
+// src/lib/schema.ts
 export const talkSchema = z.object({
   title: z.string().min(1, 'タイトルを入力してください').max(120),
   eventUrl: z.url(),
@@ -47,7 +51,7 @@ export const talkSchema = z.object({
 ```
 
 ```tsx
-// page.tsx — Server Component
+// src/routes/talks/new/page.tsx — Server Component
 import { formFields } from '@k8ordo/form/server';
 
 const talkFields = formFields(talkSchema); // derived once, plain data
@@ -58,7 +62,7 @@ export default function Page() {
 ```
 
 ```tsx
-// talk-form.tsx
+// src/components/talk-form.tsx
 'use client';
 import { useForm } from '@k8ordo/form';
 
@@ -78,29 +82,33 @@ export const TalkForm = ({ action, fields }: TalkFormProps) => {
 ```
 
 ```ts
-// actions.ts
+// src/lib/actions.ts
 'use server';
 import { parseForm } from '@k8ordo/form/server';
+import { href } from '@k8ordo/framework';
+import { redirect } from '@k8ordo/framework/server';
 
 export async function createTalk(_prev: FormState, formData: FormData) {
   const parsed = parseForm(talkSchema, formData);
   if (!parsed.success) return parsed.state;
   await insertTalk(parsed.data); // typed
-  redirect('/talks');
+  redirect(href('/talks'));
 }
 ```
 
 The [design guide](docs/GUIDE.md) covers the rest: nested objects and repeated
 rows, checkbox groups, cross-field rules typed against the schema's paths,
 async per-field checks, components that render no input of their own, and what
-the package guarantees (nothing dropped in silence, native validation kept
-without JavaScript, secrets never echoed).
-
-A check HTML cannot express — a `refine`, a regex the `pattern` attribute
-would reinterpret — is returned in `dropped` (typed as `DroppedCheck`, exported
-from both entries) and, outside production, logged once per schema with
-`console.warn`, so it is seen without anyone remembering to read it. It still
-runs on the server.
+the package guarantees (checks the client skips are reported, native
+validation kept without JavaScript, secrets never echoed).
+
+A check HTML cannot express — a `refine` on the schema as a whole, a regex the
+`pattern` attribute would reinterpret, several regexes on one string, a
+`.mime()` that `accept` only suggests — is returned in `dropped` (typed as
+`DroppedCheck`, exported from both entries) and, outside production, logged
+once per schema with `console.warn`, so it is seen without anyone remembering
+to read it. It still runs on the server. Not reported yet: a `refine` on a
+single field, a nested object, or a row.
 
 ## AI Agent Documentation
 

package/dist/async-check.d.mts

@@ -8,7 +8,7 @@
  * the same message path as every built-in check instead of opening a second
  * one.
  */
-type AsyncCheck = {
+export type AsyncCheck = {
   /** Attach to the input this check guards. */
   props: {
     onBlur: () => void;
@@ -17,6 +17,5 @@ type AsyncCheck = {
   /** True while an answer is outstanding, for disabling submit. */
   isChecking: boolean;
 };
-declare const useAsyncCheck: (check: (value: string) => Promise<string | undefined>) => AsyncCheck;
-//#endregion
-export { AsyncCheck, useAsyncCheck };
+export declare const useAsyncCheck: (check: (value: string) => Promise<string | undefined>) => AsyncCheck;
+//#endregion

package/dist/derive/attributes.d.mts

@@ -1,7 +1,7 @@
 import { DroppedCheck, FieldInput } from "../types.mjs";
 //#region src/derive/attributes.d.ts
 /** The subset of JSON Schema that `z.toJSONSchema` emits for a leaf field. */
-type LeafSchema = {
+export type LeafSchema = {
   type?: string;
   format?: string;
   pattern?: string;
@@ -13,20 +13,55 @@ type LeafSchema = {
   exclusiveMaximum?: number;
   multipleOf?: number;
   enum?: unknown[];
-  anyOf?: unknown[];
+  contentMediaType?: string;
+  anyOf?: LeafSchema[];
+  /** Where zod puts a string's patterns once there is more than one. */
+  allOf?: LeafSchema[];
+};
+/**
+ * Which control a leaf becomes, at the resolution the submission cares about.
+ * `attributesFor` needs the finer distinctions (`email` vs `url`); the walk and
+ * the parse need only this. The walk settles it once per leaf, and both read it
+ * from there, which is what keeps the three from disagreeing about what an
+ * untouched control submits.
+ *
+ * チェックボックスは、スキーマが何を読むかで 2 つに分かれる。`checkbox` は
+ * チェックの有無を真偽値で（`z.boolean()`）、`string-checkbox` は送られた
+ * 文字列か何も無いかを（`z.stringbool()`）読む。JSON Schema ではどちらも
+ * boolean なので、分けられるのは walk だけ。
+ */
+export type ControlKind = 'checkbox' | 'choice' | 'file' | 'number' | 'string-checkbox' | 'text';
+export declare const controlKindOf: (schema: LeafSchema) => ControlKind;
+/**
+ * What the control hands the schema when nobody fills it in. A text field
+ * always submits `''` and an unchecked checkbox parses to `false`, but a
+ * number, a file and a choice have no such value: an empty numeric field is not
+ * 0, an unfilled file input is not a zero-byte file, and a select left on its
+ * placeholder has chosen nothing — just like a radio group with no selection,
+ * which submits no entry at all (as does an unchecked `string-checkbox`).
+ * Reading them as "nothing was entered" is what keeps `required` honest —
+ * `z.coerce.number()` turns `''` into 0, so probing with `''` would say an
+ * empty field is acceptable and then let a blank submission through as a
+ * number the person never typed.
+ */
+export declare const emptySubmissionOf: (kind: ControlKind) => unknown;
+/** Whether a JSON Schema `format` names what a control submits, not a refinement of it. */
+export declare const namesAControl: (format: string) => boolean;
+/** What the JSON Schema has already lost, recovered from the zod side when it can be. */
+export type PatternHints = {
+  /** Flags of the RegExp behind a lone `pattern`. */
+  flags?: string;
+  /** Source of the regex the format itself carries, as opposed to one stacked on it. */
+  ofFormat?: string;
 };
 /**
  * Turn one leaf JSON Schema into input attributes, collecting whatever HTML
  * cannot express. Anything not representable is returned rather than dropped,
  * so the caller can report it instead of leaving the author to discover at
  * runtime that a check never ran on the client.
- *
- * `patternFlags` are the flags of the source RegExp when the caller could
- * recover it — the JSON Schema string has already lost them.
  */
-declare const attributesFor: (name: string, schema: LeafSchema, required: boolean, patternFlags?: string) => {
+export declare const attributesFor: (name: string, schema: LeafSchema, required: boolean, hints?: PatternHints) => {
   input: FieldInput;
   dropped: DroppedCheck[];
 };
-//#endregion
-export { LeafSchema, attributesFor };
+//#endregion

package/dist/derive/attributes.mjs

@@ -1,4 +1,27 @@
 //#region src/derive/attributes.ts
+const controlKindOf = (schema) => {
+	if (schema.format === "binary") return "file";
+	if (schema.enum !== void 0) return "choice";
+	if (schema.type === "boolean") return "checkbox";
+	if (schema.type === "integer" || schema.type === "number") return "number";
+	return "text";
+};
+/**
+* What the control hands the schema when nobody fills it in. A text field
+* always submits `''` and an unchecked checkbox parses to `false`, but a
+* number, a file and a choice have no such value: an empty numeric field is not
+* 0, an unfilled file input is not a zero-byte file, and a select left on its
+* placeholder has chosen nothing — just like a radio group with no selection,
+* which submits no entry at all (as does an unchecked `string-checkbox`).
+* Reading them as "nothing was entered" is what keeps `required` honest —
+* `z.coerce.number()` turns `''` into 0, so probing with `''` would say an
+* empty field is acceptable and then let a blank submission through as a
+* number the person never typed.
+*/
+const emptySubmissionOf = (kind) => {
+	if (kind === "checkbox") return false;
+	return kind === "text" ? "" : void 0;
+};
 /**
 * `.int()` carries JavaScript's safe-integer range into the schema. Emitting it
 * as `max` would put 9007199254740991 in the markup, which tells a reader
@@ -44,19 +67,37 @@ const patternVerdict = (source, flags) => {
 		}
 	})() ? void 0 : "ブラウザは pattern を v フラグで解釈し、コンパイルできない正規表現は黙って無視します";
 };
+/** Whether a JSON Schema `format` names what a control submits, not a refinement of it. */
+const namesAControl = (format) => Object.hasOwn(FORMAT_TO_INPUT_TYPE, format);
 /**
 * Turn one leaf JSON Schema into input attributes, collecting whatever HTML
 * cannot express. Anything not representable is returned rather than dropped,
 * so the caller can report it instead of leaving the author to discover at
 * runtime that a check never ran on the client.
-*
-* `patternFlags` are the flags of the source RegExp when the caller could
-* recover it — the JSON Schema string has already lost them.
 */
-const attributesFor = (name, schema, required, patternFlags) => {
+const attributesFor = (name, schema, required, hints = {}) => {
 	const input = { name };
 	const dropped = [];
 	if (required) input.required = true;
+	if (controlKindOf(schema) === "file") {
+		input.type = "file";
+		const accept = [schema.contentMediaType, ...(schema.anyOf ?? []).map((branch) => branch.contentMediaType)].filter((type) => type !== void 0);
+		if (accept.length > 0) {
+			input.accept = accept.join(",");
+			dropped.push({
+				field: name,
+				reason: "accept はファイル選択ダイアログの候補を絞るだけで、ブラウザは選ばれたファイルの MIME タイプを検査しません"
+			});
+		}
+		if (schema.minLength !== void 0 || schema.maxLength !== void 0) dropped.push({
+			field: name,
+			reason: "ファイルサイズの制限に対応する HTML 属性はありません（minlength / maxlength は type=\"file\" では無視されます）"
+		});
+		return {
+			input,
+			dropped
+		};
+	}
 	if (schema.anyOf !== void 0) {
 		input.type = "text";
 		dropped.push({
@@ -103,23 +144,37 @@ const attributesFor = (name, schema, required, patternFlags) => {
 			dropped
 		};
 	}
+	if (schema.type !== "string") {
+		input.type = "text";
+		dropped.push({
+			field: name,
+			reason: "スキーマから制約を読み取れないため（transform / pipe / custom など）、type=\"text\" 以外は何も導出できません。ブラウザ側では何も検査されません"
+		});
+		return {
+			input,
+			dropped
+		};
+	}
 	input.type = schema.format === void 0 ? "text" : FORMAT_TO_INPUT_TYPE[schema.format] ?? "text";
 	if (isFiniteNumber(schema.minLength) && schema.minLength > 0) input.minLength = schema.minLength;
 	if (isFiniteNumber(schema.maxLength)) input.maxLength = schema.maxLength;
-	if (schema.pattern !== void 0) {
-		if (TYPES_WITHOUT_PATTERN.has(input.type)) {
-			if (input.type !== "date" && input.type !== "datetime-local") dropped.push({
-				field: name,
-				reason: `pattern は type="${input.type}" では無視されます`
-			});
-		} else {
-			const verdict = patternVerdict(schema.pattern, patternFlags);
-			if (verdict === void 0) input.pattern = schema.pattern;
-			else dropped.push({
-				field: name,
-				reason: verdict
-			});
-		}
+	const patterns = schema.pattern === void 0 ? (schema.allOf ?? []).flatMap((branch) => branch.pattern === void 0 ? [] : [branch.pattern]) : [schema.pattern];
+	if (TYPES_WITHOUT_PATTERN.has(input.type)) {
+		if (patterns.filter((pattern) => !((input.type === "date" || input.type === "datetime-local") && pattern === hints.ofFormat)).length > 0) dropped.push({
+			field: name,
+			reason: `pattern は type="${input.type}" では無視されます`
+		});
+	} else if (patterns.length > 1) dropped.push({
+		field: name,
+		reason: `HTML の pattern は 1 つしか持てないため、重ねた ${String(patterns.length)} 個の正規表現はブラウザでは検査されません`
+	});
+	else if (patterns[0] !== void 0) {
+		const verdict = patternVerdict(patterns[0], hints.flags);
+		if (verdict === void 0) input.pattern = patterns[0];
+		else dropped.push({
+			field: name,
+			reason: verdict
+		});
 	}
 	return {
 		input,
@@ -127,4 +182,4 @@ const attributesFor = (name, schema, required, patternFlags) => {
 	};
 };
 //#endregion
-export { attributesFor };
+export { attributesFor, controlKindOf, emptySubmissionOf, namesAControl };

package/dist/derive/form-fields.d.mts

@@ -1,5 +1,5 @@
 import { FormFields } from "../types.mjs";
-import { ArrayPathsOf, FieldPathsOf } from "../paths.mjs";
+import { ArrayPathsOf, FieldPathsOf, StringCheckboxPathsOf } from "../paths.mjs";
 import { ObjectSchema } from "../schema/object-schema.mjs";
 import { FormDefinition } from "../rules/define-form.mjs";
 //#region src/derive/form-fields.d.ts
@@ -8,8 +8,9 @@ import { FormDefinition } from "../rules/define-form.mjs";
  *
  * Call this on the server — in a Server Component or at module scope. The
  * result is plain data, so it crosses to the client as props and zod never
- * enters the bundle.
+ * enters the bundle. Messages are read when it runs — zod's, and a rule's
+ * function message — so when one follows the request (its locale, say), call
+ * it during the render, not at module scope.
  */
-declare const formFields: <Schema extends ObjectSchema>(input: FormDefinition<Schema> | Schema) => FormFields<FieldPathsOf<Schema>, ArrayPathsOf<Schema>>;
-//#endregion
-export { formFields };
+export declare const formFields: <Schema extends ObjectSchema>(input: FormDefinition<Schema> | Schema) => FormFields<FieldPathsOf<Schema>, ArrayPathsOf<Schema>, StringCheckboxPathsOf<Schema>>;
+//#endregion

package/dist/derive/form-fields.mjs

@@ -1,26 +1,40 @@
+import { deriveRule } from "../rules/rules.mjs";
 import { asDefinition } from "../rules/define-form.mjs";
 import { asProbe } from "../schema/object-schema.mjs";
-import { schemaMap } from "../schema/walk.mjs";
-import { attributesFor } from "./attributes.mjs";
+import { attributesFor, emptySubmissionOf, namesAControl } from "./attributes.mjs";
+import { schemaMap, unwrap } from "../schema/walk.mjs";
 import { messagesFor } from "./messages.mjs";
 //#region src/derive/form-fields.ts
 const objectLevelCheckCount = (schema) => schema._zod?.def?.checks?.length ?? 0;
 /**
-* Recover the flags of the RegExp behind a JSON Schema `pattern` string. The
-* JSON string has already lost them, and whether the browser may see the
-* pattern depends on them (an `i` flag has no HTML equivalent).
+* The string formats a leaf declares — its own (`z.email()`) first, then the
+* ones its checks add (`.regex()`, `.lowercase()`) — each with the RegExp
+* behind it. The JSON Schema cannot stand in: its `pattern` strings have lost
+* their flags (an `i` has no HTML equivalent), and a later check overwrites
+* the `format` keyword (`z.url().lowercase()` says `lowercase`) or erases it
+* (`.regex()`).
 */
-const patternFlags = (schema, source) => {
-	const def = schema._zod?.def;
-	if (def?.pattern?.source === source) return def.pattern.flags;
-	for (const check of def?.checks ?? []) {
-		const candidate = check._zod?.def?.pattern;
-		if (candidate?.source === source) return candidate.flags;
-	}
+const stringFormatsOf = (schema) => {
+	const def = unwrap(schema)._zod?.def;
+	return [def, ...(def?.checks ?? []).map((check) => check._zod?.def)].filter((entry) => entry?.format !== void 0);
+};
+/** zod's own name for a format is not always the JSON Schema one. */
+const ZOD_FORMAT_TO_JSON_FORMAT = {
+	datetime: "date-time",
+	guid: "uuid",
+	url: "uri"
 };
+const jsonFormatOf = (format) => ZOD_FORMAT_TO_JSON_FORMAT[format] ?? format;
 /** What a `datetime-local` control actually submits: no seconds, no zone. */
 const DATETIME_LOCAL_PROBE = "2000-01-01T00:00";
 /**
+* Whether the date-time format itself turns away what a `datetime-local`
+* control submits. Only the format's own issue counts: a regex stacked on it
+* that fails the probe is a check the control ignores, not a shape the control
+* cannot produce.
+*/
+const refusesDatetimeLocal = (schema) => asProbe(schema).safeParse(DATETIME_LOCAL_PROBE).error?.issues.some((issue) => issue.code === "invalid_format" && issue.format === "datetime") ?? false;
+/**
 * Schemas whose `dropped` list has already been reported. `formFields` is not
 * memoized, so a schema derived in every request would otherwise warn on
 * every request; keyed by the schema object, an HMR re-evaluation still gets
@@ -49,7 +63,9 @@ const warnDropped = (schema, dropped) => {
 *
 * Call this on the server — in a Server Component or at module scope. The
 * result is plain data, so it crosses to the client as props and zod never
-* enters the bundle.
+* enters the bundle. Messages are read when it runs — zod's, and a rule's
+* function message — so when one follows the request (its locale, say), call
+* it during the render, not at module scope.
 */
 const formFields = (input) => {
 	const { schema, rules } = asDefinition(input);
@@ -64,23 +80,39 @@ const formFields = (input) => {
 		item: {}
 	};
 	for (const leaf of map.leaves) {
-		const attributes = attributesFor(leaf.name, leaf.json, leaf.required, leaf.json.pattern === void 0 ? void 0 : patternFlags(leaf.zod, leaf.json.pattern));
-		const secret = leaf.json.input === "password";
-		if (secret) attributes.input.type = "password";
-		if (attributes.input.type === "datetime-local" && !asProbe(leaf.zod).safeParse(DATETIME_LOCAL_PROBE).success) {
-			attributes.input.type = "text";
-			attributes.dropped.push({
+		const formats = stringFormatsOf(leaf.zod);
+		const own = leaf.json.type === "string" ? formats.find((entry) => namesAControl(jsonFormatOf(entry.format))) : void 0;
+		let format = own === void 0 ? leaf.json.format : jsonFormatOf(own.format);
+		const formatDropped = [];
+		if (format === "date-time" && refusesDatetimeLocal(leaf.zod)) {
+			format = void 0;
+			formatDropped.push({
 				field: leaf.name,
-				reason: "z.iso.datetime() はタイムゾーンを要求しますが、datetime-local はタイムゾーンを送信できません。type=\"text\" に落とします（local: true なら datetime-local が使えます）"
+				reason: `この日時書式は datetime-local が送信する形（${DATETIME_LOCAL_PROBE} のように秒もタイムゾーンも付かない）を受け付けないため、type="text" に落とします（z.iso.datetime({ local: true }) なら datetime-local が使えます）`
 			});
 		}
+		const { pattern } = leaf.json;
+		const attributes = attributesFor(leaf.name, {
+			...leaf.json,
+			format
+		}, leaf.required, {
+			flags: pattern === void 0 ? void 0 : formats.find((entry) => entry.pattern?.source === pattern)?.pattern?.flags,
+			ofFormat: format === void 0 ? void 0 : own?.pattern?.source
+		});
+		attributes.dropped.unshift(...formatDropped);
+		const secret = leaf.json.input === "password";
+		if (secret) attributes.input.type = "password";
+		const fieldInput = leaf.checkedValue === void 0 ? attributes.input : {
+			...attributes.input,
+			value: leaf.checkedValue
+		};
 		if (leaf.group !== void 0 && (leaf.group.minItems !== void 0 || leaf.group.maxItems !== void 0)) dropped.push({
 			field: leaf.path,
 			reason: "チェックボックス群の個数制限に対応する HTML 属性はありません。クライアントでも検査するには minChecked を使ってください"
 		});
 		const derived = {
-			input: attributes.input,
-			messages: messagesFor(leaf.zod, attributes.input, leaf.required),
+			input: fieldInput,
+			messages: messagesFor(leaf.zod, fieldInput, leaf.required, emptySubmissionOf(leaf.kind)),
 			secret
 		};
 		const array = leaf.arrayPath === null ? void 0 : arrays[leaf.arrayPath];
@@ -100,7 +132,7 @@ const formFields = (input) => {
 	return {
 		fields,
 		arrays,
-		rules,
+		rules: rules.map((rule) => deriveRule(rule)),
 		dropped
 	};
 };

package/dist/derive/messages.d.mts

@@ -7,6 +7,5 @@ import { $ZodType } from "zod/v4/core";
  * flag — the browser's own wording is never used, since it is locale-dependent
  * and cannot be controlled.
  */
-declare const messagesFor: (schema: $ZodType, input: FieldInput, required: boolean) => Partial<Record<ValidityFlag, string>>;
-//#endregion
-export { messagesFor };
+export declare const messagesFor: (schema: $ZodType, input: FieldInput, required: boolean, emptySubmission: unknown) => Partial<Record<ValidityFlag, string>>;
+//#endregion

package/dist/derive/messages.mjs

@@ -1,19 +1,16 @@
 import { asProbe } from "../schema/object-schema.mjs";
 //#region src/derive/messages.ts
 const repeat = (length) => "a".repeat(Math.max(length, 0));
-const probesFor = (input, required) => {
+const probesFor = (input, required, emptySubmission) => {
 	const probes = [];
-	if (required) probes.push(input.type === "checkbox" ? {
+	if (required) probes.push({
 		flag: "valueMissing",
-		value: false,
-		codes: ["invalid_value", "invalid_type"]
-	} : {
-		flag: "valueMissing",
-		value: "",
+		value: emptySubmission,
 		codes: [
 			"too_small",
-			"invalid_type",
-			"invalid_format"
+			"invalid_value",
+			"invalid_format",
+			"invalid_type"
 		]
 	});
 	if (input.minLength !== void 0) probes.push({
@@ -66,9 +63,9 @@ const probesFor = (input, required) => {
 * flag — the browser's own wording is never used, since it is locale-dependent
 * and cannot be controlled.
 */
-const messagesFor = (schema, input, required) => {
+const messagesFor = (schema, input, required, emptySubmission) => {
 	const messages = {};
-	for (const probe of probesFor(input, required)) {
+	for (const probe of probesFor(input, required, emptySubmission)) {
 		const result = asProbe(schema).safeParse(probe.value);
 		if (result.success) continue;
 		const issue = probe.codes.map((code) => result.error.issues.find((candidate) => candidate.code === code)).find((found) => found !== void 0) ?? result.error.issues[0];

package/dist/hidden-value.d.mts

@@ -8,18 +8,14 @@ import { FC } from "react";
  * pulling its value into React state and fighting it back out at submit, park
  * the value in a hidden input and let the form collect it like any other.
  *
- * This is the whole of what `Controller` exists to do in react-hook-form, and
- * it is the one place that binding silently breaks there.
- *
  * A component rather than a props helper for two reasons the form cannot see
  * from outside: React updates a controlled value without any DOM event, so a
  * change here has to be announced with one for rules and `isDirty` to notice;
- * and a controlled input's defaultValue tracks its value, so the first
- * render's value is snapshotted into `data-initial` as the dirtiness baseline.
+ * and a controlled input's defaultValue tracks its value, so the value it
+ * mounted with is burned into `data-initial` as the dirtiness baseline.
  */
-declare const HiddenValue: FC<{
+export declare const HiddenValue: FC<{
   name: string;
   value: string;
 }>;
-//#endregion
-export { HiddenValue };
+//#endregion

package/dist/hidden-value.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/hidden-value.tsx
 /**
@@ -10,29 +10,28 @@ import { jsx } from "react/jsx-runtime";
 * pulling its value into React state and fighting it back out at submit, park
 * the value in a hidden input and let the form collect it like any other.
 *
-* This is the whole of what `Controller` exists to do in react-hook-form, and
-* it is the one place that binding silently breaks there.
-*
 * A component rather than a props helper for two reasons the form cannot see
 * from outside: React updates a controlled value without any DOM event, so a
 * change here has to be announced with one for rules and `isDirty` to notice;
-* and a controlled input's defaultValue tracks its value, so the first
-* render's value is snapshotted into `data-initial` as the dirtiness baseline.
+* and a controlled input's defaultValue tracks its value, so the value it
+* mounted with is burned into `data-initial` as the dirtiness baseline.
 */
 const HiddenValue = ({ name, value }) => {
 	const node = useRef(null);
-	const initial = useRef(value);
 	const last = useRef(value);
+	const attach = useCallback((element) => {
+		node.current = element;
+		if (element !== null) element.dataset.initial = element.value;
+	}, []);
 	useEffect(() => {
 		if (last.current === value) return;
 		last.current = value;
 		node.current?.dispatchEvent(new Event("input", { bubbles: true }));
 	}, [value]);
 	return /* @__PURE__ */ jsx("input", {
-		"data-initial": initial.current,
 		name,
 		readOnly: true,
-		ref: node,
+		ref: attach,
 		type: "hidden",
 		value
 	});

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { AsyncCheck, useAsyncCheck } from "./async-check.mjs";
-import { Rule } from "./rules/rules.mjs";
-import { DerivedArray, DerivedField, DroppedCheck, FieldInput, FormFields, FormState, ValidityFlag } from "./types.mjs";
+import { DerivedRule, Rule, RuleMessage } from "./rules/rules.mjs";
+import { DerivedArray, DerivedField, DroppedCheck, FieldInput, FormFields, FormState, StringCheckboxInput, ValidityFlag } from "./types.mjs";
 import { HiddenValue } from "./hidden-value.mjs";
-import { ArrayView, FieldView, RowView, UseFormReturn, useForm } from "./use-form.mjs";
-export { type ArrayView, type AsyncCheck, type DerivedArray, type DerivedField, type DroppedCheck, type FieldInput, type FieldView, type FormFields, type FormState, HiddenValue, type RowView, type Rule, type UseFormReturn, type ValidityFlag, useAsyncCheck, useForm };
+import { ArrayView, FieldView, FormErrorView, RowView, UseFormReturn, useForm } from "./use-form.mjs";
+export { type ArrayView, type AsyncCheck, type DerivedArray, type DerivedField, type DerivedRule, type DroppedCheck, type FieldInput, type FieldView, type FormErrorView, type FormFields, type FormState, HiddenValue, type RowView, type Rule, type RuleMessage, type StringCheckboxInput, type UseFormReturn, type ValidityFlag, useAsyncCheck, useForm };

package/dist/parse/parse-form.d.mts

@@ -3,7 +3,7 @@ import { ObjectSchema } from "../schema/object-schema.mjs";
 import { FormDefinition } from "../rules/define-form.mjs";
 import { output } from "zod/v4/core";
 //#region src/parse/parse-form.d.ts
-type ParseResult<Output> = {
+export type ParseResult<Output> = {
   success: true;
   data: Output;
   state: FormState;
@@ -21,6 +21,5 @@ type ParseResult<Output> = {
  * schema's job via `z.coerce`, so the schema keeps describing what it
  * actually validates.
  */
-declare const parseForm: <Shape extends ObjectSchema>(input: FormDefinition<Shape> | Shape, formData: FormData) => ParseResult<output<Shape>>;
-//#endregion
-export { ParseResult, parseForm };
+export declare const parseForm: <Shape extends ObjectSchema>(input: FormDefinition<Shape> | Shape, formData: FormData) => ParseResult<output<Shape>>;
+//#endregion