@k8ordo/form 0.1.0 → 1.0.0

package/docs/llms.txt

@@ -16,17 +16,68 @@ When installed via npm, these docs live under `node_modules/@k8ordo/form/docs/`.
   what the package guarantees, what it does not do yet, and how it pairs with
   `@k8ordo/ui` without depending on it.
 
+## Not supported
+
+`z.array(z.file())` derives repeated single-file rows, not one `multiple` input.
+Constraints behind a `.transform()` (or a `.pipe()` whose output JSON Schema
+cannot describe) are not derived: the field becomes a bare text input and is
+listed in `dropped`. There is no input masking. A schema no control could
+satisfy is refused at derive time rather than left to fail on every
+submission: `z.number()` and `z.literal(1)` (use `z.coerce.number()`),
+`z.date()`, and `z.bigint()`; so is a `z.stringbool().default(true)` checkbox,
+which could never submit `false`. A `z.custom()` that rejects strings cannot be refused at derive
+time: it derives as a text input, is listed in `dropped`, and fails on the
+server. Of `.refine()` / `.superRefine()` checks, `dropped` counts only the ones
+on the schema as a whole, not those on a single field, a nested object, or a
+row. Rules cannot target fields inside repeated rows.
+
 ## Entry points
 
-- `@k8ordo/form` — client. `useForm(fields, state)` takes the whole
-  `formFields` result and returns props for the `<form>` element, a
+- `@k8ordo/form` — client. `useForm(fields, state?)` takes the whole
+  `formFields` result (and the action's state, when there is one) and
+  returns props for the `<form>` element — which also hear a reset, React's
+  own after every form action included — 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.
+  `invalid` / `required`, an `array(path)` accessor for repeated rows (its
+  `error` is the array's own message, with `errorProps` to let focus land on
+  it), `formError` (the message no field owns, with the props that let focus
+  land on it), and `isDirty`. On submit it checks every field — untouched ones
+  and the rules included — and stops a failing submission, a GET form with no
+  action as much as one with (a `formNoValidate` button skips the check);
+  after a submission stopped here or failed on the server, focus moves to the
+  first failure in document order, and a first failure the hook has no
+  message for (a control outside the schema) is reported by the browser
+  itself through `reportValidity()`. Also `useAsyncCheck` for server-answered
+  per-field checks and `HiddenValue` for components that render no input of
+  their own. The types
+  of the `formFields` result (`FormFields`, `DerivedField`, `DerivedArray`,
+  `DroppedCheck`, `FieldInput`, `StringCheckboxInput`, `ValidityFlag`, `Rule`,
+  `DerivedRule`, `RuleMessage`) are exported here as
+  well, since the result crosses to the client as a prop, and so are
+  `FormState` and the return types (`UseFormReturn`, `FieldView`, `ArrayView`,
+  `RowView`, `FormErrorView`, `AsyncCheck`).
+- `@k8ordo/form/server` — server. `formFields(schemaOrDefinition)` derives
+  serializable fields plus a `dropped` list of checks HTML cannot express
+  (outside production the list is also logged once per schema with
+  `console.warn`), and throws on a schema no form can represent (including a
+  leaf that could never accept a submitted string, such as `z.number()`);
+  `parseForm(schemaOrDefinition, formData)` validates a submission and returns
+  typed data or per-field errors with the submitted values. An untouched
+  control reaches the schema as what it actually submits: `''` for text,
+  `false` for a checkbox, and nothing at all for a number, a
+  `z.coerce.bigint()`, a file, a choice (a radio group with none selected, a
+  `<select>` on a `value=""` placeholder), or a `z.stringbool()` checkbox —
+  which, checked, submits the `value` derived from the schema's own spelling of
+  `true`, the same string `@k8ordo/state` writes into a URL — so `z.coerce.number()` cannot read a
+  blank field as 0 and `z.enum([…]).optional()` can be left empty. A checkbox
+  group always echoes as an array.
+  `defineForm(schema, rules)` attaches cross-field rules (`sameAs`,
+  `minChecked`, `requiredWhen`) typed against the schema's paths; a rule's
+  message is a string or a function called when the rule is reported
+  (`formFields` calls it while deriving, so a rule crosses to the client as a
+  `DerivedRule` with the text in it; `parseForm` calls it when the rule
+  breaks), which keeps a localized definition at module scope. Types:
+  `ParseResult`, `FormDefinition`, `Rule`, `RuleMessage`, `FormState`, and the
+  `formFields` result's `FormFields`, `DerivedField`, `DerivedArray`,
+  `DerivedRule`, `DroppedCheck`, `FieldInput`, `StringCheckboxInput`,
+  `ValidityFlag`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8ordo/form",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Derive HTML constraint attributes and per-field errors from one zod schema. Works without JavaScript.",
   "keywords": [
     "constraint-validation",
@@ -11,6 +11,9 @@
     "zod"
   ],
   "homepage": "https://ordo.k8o.me",
+  "bugs": {
+    "url": "https://github.com/k35o/k8ordo/issues"
+  },
   "license": "MIT",
   "author": "k8o <kosakanoki@gmail.com>",
   "repository": {
@@ -39,23 +42,26 @@
     "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",
+    "@arethetypeswrong/cli": "0.18.5",
+    "@k8ordo/state": "^1.0.0",
+    "@types/react": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "@vitest/browser-playwright": "5.0.3",
+    "publint": "0.3.25",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "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"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0",
+    "vitest": "5.0.3",
+    "vitest-browser-react": "2.3.0",
+    "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@types/react": ">=19.2.18",
-    "react": ">=19.2.6",
-    "react-dom": ">=19.2.6",
-    "typescript": ">=7.0.2",
+    "@types/react": ">=19.3.0",
+    "react": ">=19.3.0",
+    "react-dom": ">=19.3.0",
+    "typescript": ">=7.0.0",
     "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
@@ -71,6 +77,7 @@
     "test": "vp test",
     "typecheck": "tsc --noEmit",
     "check": "vp check",
-    "check:write": "vp check --fix"
+    "check:write": "vp check --fix",
+    "check:package": "publint && attw --pack . --profile esm-only"
   }
 }