@k8ordo/form 0.1.0

package/docs/GUIDE.md

@@ -0,0 +1,362 @@
+# @k8ordo/form
+
+One zod schema produces the HTML constraint attributes, the messages, and the
+server-side validation. The DOM holds the values; React state holds only what
+the DOM cannot express.
+
+Like every k8ordo package it assumes React 19 and Server Components, uses only
+what has reached Baseline newly available, and ships no polyfills or legacy
+fallbacks.
+
+## zod, or zod/mini
+
+The conversion is taken from zod's shared core, so a schema written with either
+entry works. `zod/mini` is the same validator with a much smaller surface — if
+the schema module is also imported somewhere on the client, that is the one to
+reach for.
+
+```
+zod        63 kB gzipped
+zod/mini   10 kB gzipped
+```
+
+Nothing in this package notices which one you chose. Note that under this
+design the schema is imported only by server code — the Server Component that
+derives the fields, and the Server Action that parses the submission — so zod
+does not reach the browser either way. Reach for `zod/mini` when something on
+the client imports the schema module anyway.
+
+## The shape of it
+
+```
+server    formFields(schema)  →  { title: { input, messages }, … }   plain data
+            ↓ props (zod does not cross)
+client    useForm(fields, state)  →  attributes to spread, message to show
+            ↓ submit
+server    parseForm(schema, formData)  →  typed data, or per-field errors
+```
+
+`formFields` runs on the server — in a Server Component or at module scope. Its
+result is JSON, so it crosses the RSC boundary as props and zod never enters the
+client bundle.
+
+## Writing a form
+
+```ts
+// schema.ts
+export const talkSchema = z.object({
+  title: z.string().min(1).max(120),
+  eventUrl: z.url(),
+  blogId: z.coerce.number().int().positive(),
+});
+```
+
+Type conversion stays in the schema. `parseForm` handles what only it can —
+an unchecked checkbox arrives as a missing key, a repeated name arrives as
+several entries, everything is a string — and `z.coerce` handles `'42'` → `42`.
+That way the schema keeps describing what it actually validates.
+
+```tsx
+// page.tsx — Server Component
+const talkFields = formFields(talkSchema); // module scope: derived once
+
+export default function Page() {
+  return <TalkForm action={createTalk} fields={talkFields} />;
+}
+```
+
+`useForm` takes the whole result — fields, arrays, rules, and the `dropped`
+report travel together.
+
+```tsx
+// talk-form.tsx
+'use client';
+
+export const TalkForm = ({ action, fields }: TalkFormProps) => {
+  const [state, formAction] = useActionState(action, {});
+  const form = useForm(fields, state);
+  const title = form.field('title');
+
+  return (
+    <form {...form.props} action={formAction}>
+      <input {...title.input} />
+      {title.error !== undefined && <p>{title.error}</p>}
+    </form>
+  );
+};
+```
+
+`form.props` attaches to the `<form>` and nowhere else. There is no per-field
+registration to forget.
+
+```ts
+// actions.ts
+'use 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');
+}
+```
+
+## What it guarantees
+
+**The wording cannot drift.** Client messages are obtained by running the
+schema against a probe value, so the text shown next to the input is the text
+zod itself produces. A custom `min(1, '…')` reaches both sides.
+
+**`required` means the same thing on both sides.** JSON Schema's `required`
+means "the key is present", but a form always submits something for every
+control — an empty text field as `''`, an unchecked checkbox as `false` once
+parsed. The attribute is emitted only when the schema rejects that empty
+submission, so the two sides always agree: a plain `z.boolean()` checkbox is
+not required, while `z.literal(true, '…')` — a consent box — is, and shows
+zod's own wording.
+
+**Nothing is dropped in silence.** Checks HTML cannot express — `refine`,
+cross-field rules, an exclusive bound on a float, a regex whose flags or
+anchoring the `pattern` attribute would silently reinterpret, a
+`z.iso.datetime()` no `datetime-local` control can ever satisfy — are returned
+in `dropped`. They still run on the server; you are told they do not run on
+the client.
+
+**A schema this package cannot express fails at derive time.** `z.record`,
+tuples, a repeat nested inside a repeat, nullable objects, keys containing
+`.` or brackets — `formFields` throws with the reason, instead of deriving a
+form that would silently misparse what the person typed.
+
+**A missing name is loud.** If the schema has a field that never arrived in the
+FormData, `parseForm` throws instead of reporting it as a validation failure.
+Forgetting to spread `input` is a wiring mistake, not something the person
+filling in the form did. The one exception is an enum field: a radio group
+with nothing selected submits no entry at all — a state the person can reach —
+so it comes back as that field's validation error instead.
+
+**Native validation survives without JavaScript.** `noValidate` is applied
+from JavaScript on mount, never rendered into the markup. With scripts
+disabled or not yet loaded, the browser's own checks stay on; once the hook is
+live, it takes over the message path and the server stays the arbiter.
+
+**Secrets are never echoed.** `parseForm` returns the submitted values so a
+retry without JavaScript keeps the input. Fields marked as passwords are
+excluded automatically, and typed as `password` in the markup:
+
+```ts
+z.string().min(8).meta({ input: 'password' }); // zod
+globalRegistry.add(password, { input: 'password' }); // zod or zod/mini
+```
+
+`.meta()` is shorthand for the registry and is not available on `zod/mini`;
+the registry route works with either.
+
+**`isDirty` costs one boolean.** `form.isDirty` compares each control — text,
+checkbox, `<select>`, a `HiddenValue` — with the value it was rendered with,
+read straight from the DOM; adding or removing a row counts too. It flips at
+most twice, so it never becomes a per-keystroke re-render.
+
+## Nested objects and repeated rows
+
+A nested field is addressed by its dotted path, which is also the `name` the
+browser submits.
+
+```tsx
+const email = form.field('user.email'); // name="user.email"
+```
+
+A repeated group is reached through `array()`. React state holds only the
+identity of each row — the values stay in the DOM, so adding or removing a row
+never copies anything into React.
+
+```tsx
+const items = form.array('items');
+
+{
+  items.rows.map((row) => (
+    <div key={row.key}>
+      <input {...row.field('name').input} /> {/* name="items[0].name" */}
+      {items.canRemove && (
+        <button onClick={row.remove} type="button">
+          削除
+        </button>
+      )}
+    </div>
+  ));
+}
+{
+  items.canAdd && (
+    <button onClick={items.add} type="button">
+      追加
+    </button>
+  );
+}
+```
+
+`canAdd` and `canRemove` come from the schema's `.min()` / `.max()`, so the
+buttons disappear at exactly the bounds the server enforces. For an array of
+scalars (`z.array(z.string())`) the item has a single unnamed field:
+`row.field()`.
+
+`parseForm` reports how many rows arrived in `state.rows`, so a retry without
+JavaScript rebuilds the same number of rows. Row counts are read from the
+submitted names but never trusted beyond the schema's `.max()` (or a hard
+ceiling), so a forged index cannot make the server allocate.
+
+A nested object behind `.optional()` / `.default()` keeps its fields — the
+wrapper is peeled the same way on both sides. A repeat nested inside a repeat
+has no unambiguous name; it is a compile error and a derive-time throw.
+
+## Checkbox groups
+
+An array of enums is a fixed option set the person picks several of — one
+name shared by every box, not repeated rows. It derives as a single field:
+
+```tsx
+const prefs = z.object({ tags: z.array(z.enum(['a', 'b', 'c'])).min(2) });
+
+const tags = form.field('tags');
+
+{
+  ['a', 'b', 'c'].map((option) => (
+    <input key={option} type="checkbox" value={option} {...tags.input} />
+  ));
+}
+```
+
+`parseForm` reads every checked box under the shared name — none checked is
+`[]`, never a wiring error. The `.min(2)` cannot become an HTML attribute (on
+a group, `required` would mean "check every box"), so it is reported in
+`dropped`; declare `minChecked('tags', 2, '…')` to run the same bound in the
+browser. On a no-JS retry the group echoes as an array, so restoring is:
+
+```tsx
+defaultChecked={Array.isArray(state.values?.tags) && state.values.tags.includes(option)}
+```
+
+## Paths are checked at compile time
+
+`formFields` derives the set of valid paths from the schema type, so a typo is
+a build error rather than something you find by clicking. Rules are typed
+against the same paths.
+
+```tsx
+form.field('titel'); // error: not a field in the schema
+form.field('items'); // error: an array of objects, reached through array()
+form.array('user'); // error: an object, not an array
+form.array('tags'); // error: a checkbox group is a field
+defineForm(schema, [sameAs('confrim', 'password', '…')]); // error: typo
+```
+
+## Checks HTML has no attribute for
+
+Password confirmation, "tick at least two", "required only when rejected" —
+none of these map to a constraint attribute, and a `.refine()` cannot cross to
+the client because it is a function. Declare them next to the schema instead:
+
+```ts
+export const signup = defineForm(
+  z.object({
+    password: z.string().min(8),
+    confirm: z.string(),
+  }),
+  [sameAs('confirm', 'password', 'パスワードが一致しません')],
+);
+```
+
+Pass the definition where you passed the schema — `formFields(signup)` and
+`parseForm(signup, formData)`. The rules are plain data, so they travel with
+the fields, and **both sides run the same evaluator**: the browser against the
+live form, the server against the submission. There is no second
+implementation to drift from the first.
+
+On the client a breach is applied with `setCustomValidity`, so it is
+indistinguishable from a built-in check — `:user-invalid` matches and the
+message arrives through the same path as every other one.
+
+Available: `sameAs`, `minChecked`, `requiredWhen`. Anything else stays a
+`.refine()`, runs on the server, and is listed in `dropped`.
+
+## Asking the server about one field
+
+Whether a name is already taken is something only the server knows. `useAsyncCheck`
+runs on blur, keeps the newest answer when replies arrive out of order, and
+applies the result with `setCustomValidity` — so the answer shows up through the
+same path as every other message. A blur that leaves the value unchanged does
+not ask again, and emptying the field clears the last answer with it.
+
+```tsx
+const slug = form.field('slug');
+const taken = useAsyncCheck(checkSlugAvailable); // a Server Action
+
+<input {...slug.input} {...taken.props} />;
+<button disabled={taken.isChecking} type="submit">
+  保存
+</button>;
+```
+
+## Components that submit nothing
+
+A rich text editor or a third-party combobox renders no `<input name>`, so
+FormData never sees it. Park its value in a hidden input rather than pulling it
+into React state and pushing it back out at submit:
+
+```tsx
+<Editor onChange={setBody} value={body} />
+<HiddenValue name="body" value={body} />
+```
+
+This is all `Controller` does in react-hook-form, and it is the one place that
+binding silently breaks there. Here the value is in the form, so it submits
+whether or not anything else works. `HiddenValue` is a component rather than a
+props helper because React updates a controlled value without any DOM event —
+the component announces each change with one, so cross-field rules and
+`isDirty` hear it like any keystroke.
+
+## Multi-step forms
+
+Keep every step mounted and hide the ones you are not on. The values stay in
+the DOM, so moving between steps costs nothing and losing a step is impossible:
+
+```tsx
+<div hidden={step !== 1} ref={stepOne}>
+  {/* … */}
+</div>
+```
+
+Validate one step before advancing by checking only the controls inside that
+step's container — the hidden steps are not filled in yet, so checking the
+whole form would always fail:
+
+```tsx
+const stepIsValid = [
+  ...(stepOne.current?.querySelectorAll('input, select, textarea') ?? []),
+].every((control) => (control as HTMLInputElement).checkValidity());
+```
+
+Without JavaScript this degrades to one long form that submits in a single
+request — which is the correct behaviour, not a broken one.
+
+## What it does not do yet
+
+- Input masking. Rewriting `el.value` on input works with the DOM as the source
+  of truth, but managing the caret is a separate problem from wiring a form.
+
+## Working with @k8ordo/ui
+
+`@k8ordo/form` does not depend on `@k8ordo/ui`. Attributes go to the input;
+`FormControl` gets only what it uses, and generates the `id` and `aria-*`
+links itself.
+
+```tsx
+const title = form.field('title');
+
+<FormControl
+  errorText={title.error}
+  invalid={title.invalid}
+  label="タイトル"
+  required={title.required}
+  renderInput={(props) => <TextField {...props} {...title.input} />}
+/>;
+```

package/docs/llms.txt

@@ -0,0 +1,32 @@
+# @k8ordo/form
+
+> Derive HTML constraint attributes, error messages, and server-side validation
+> from one zod schema. The DOM holds the values; React state holds only what the
+> DOM cannot express. Forms work with JavaScript disabled or not yet loaded.
+>
+> Like every k8ordo package it assumes React 19 and Server Components, uses only
+> what has reached Baseline newly available, and ships no polyfills or legacy
+> fallbacks.
+
+When installed via npm, these docs live under `node_modules/@k8ordo/form/docs/`.
+
+## Guide
+
+- [Design Guide](GUIDE.md): the server/client split, writing a form end to end,
+  what the package guarantees, what it does not do yet, and how it pairs with
+  `@k8ordo/ui` without depending on it.
+
+## Entry points
+
+- `@k8ordo/form` — client. `useForm(fields, state)` takes the whole
+  `formFields` result and returns props for the `<form>` element, a
+  `field(path)` accessor giving input attributes, the current error, and
+  `invalid` / `required`, an `array(path)` accessor for repeated rows, and
+  `isDirty`. Also `useAsyncCheck` for server-answered per-field checks and
+  `HiddenValue` for components that render no input of their own.
+- `@k8ordo/form/server` — server. `formFields(schema)` derives serializable
+  fields plus a `dropped` list of checks HTML cannot express, and throws on a
+  schema no form can represent; `parseForm(schema, formData)` validates a
+  submission and returns typed data or per-field errors with the submitted
+  values. `defineForm(schema, rules)` attaches cross-field rules (`sameAs`,
+  `minChecked`, `requiredWhen`) typed against the schema's paths.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@k8ordo/form",
+  "version": "0.1.0",
+  "description": "Derive HTML constraint attributes and per-field errors from one zod schema. Works without JavaScript.",
+  "keywords": [
+    "constraint-validation",
+    "form",
+    "progressive-enhancement",
+    "react",
+    "server-actions",
+    "zod"
+  ],
+  "homepage": "https://ordo.k8o.me",
+  "license": "MIT",
+  "author": "k8o <kosakanoki@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k35o/k8ordo.git"
+  },
+  "files": [
+    "dist/**",
+    "docs/**"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.mts",
+      "default": "./dist/server.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.18",
+    "@vitejs/plugin-react": "6.0.5",
+    "@vitest/browser-playwright": "4.1.10",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "7.0.2",
+    "vite": "8.2.1",
+    "vite-plus": "0.2.9",
+    "vitest": "4.1.10",
+    "vitest-browser-react": "2.2.0",
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@types/react": ">=19.2.18",
+    "react": ">=19.2.6",
+    "react-dom": ">=19.2.6",
+    "typescript": ">=7.0.2",
+    "zod": "^4.4.3"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit",
+    "check": "vp check",
+    "check:write": "vp check --fix"
+  }
+}