@k8ordo/form

仕組み

@k8ordo/formが入力の検証をいつ、どこで行うかと、保証することとしないことが分かります。

このページの内容

スキーマの使われ方

text
server   formFields(schema)       → { fields, arrays, rules, dropped }
           ↓ props (JSON)
client   useForm(fields, state)   → props for <form>, input for each field
           ↓ submit
server   parseForm(schema, data)  → typed data, or errors per field

スキーマを読むのはformFieldsとparseFormで、どちらもサーバーで動きます。スキーマについてブラウザが受け取るのは、formFieldsが返したJSONだけです。

スキーマをimportするのがサーバーのコードだけなら、zodはブラウザのバンドルに入りません。その場合、zodとzod/miniのどちらで書いてもバンドルの大きさは変わりません。

ブラウザで出す文言は、formFieldsを呼んだときに決まってJSONに入ります。リクエストの言語に合わせる呼び方はエラーの表示にあります。

入力値とstate

入力した値はReactのstateに入れず、入力欄から直接読みます。stateに入れるのは、DOMでは表せない次の5つだけです。

  • 検証に失敗した入力欄に出す文言
  • サーバーが返したエラーのうち、まだ直していないもの
  • 繰り返し行のそれぞれを見分けるキー
  • 変更の有無を表す1つの真偽値(DOMから読む)
  • 行の追加や削除を判定するための、描画時の行数

値をstateに入れないので、キーを押すたびに再描画されることはありません。ブラウザのリセットも、アクションのあとにReactが行うリセットも、そのまま働きます。

JavaScriptが無いとき

requiredやminLengthなどの制約は、サーバーが描画するHTMLの属性に含まれます。JavaScriptが無い環境や読み込み前でも、ブラウザが入力を確かめます。

JavaScriptが読み込まれると、useFormがフォームにnoValidateを付け、同じ検証をzodの文言で行います。noValidateはHTMLには書かず、マウント時に付けます。

送信に失敗したときは、送信した値が入力欄のdefaultValueとして描画し直されます。JavaScriptが無い環境でも、入力した内容は残ります。

文言の取り出し方

formFieldsは、検証の種類ごとに、その検証だけが失敗する値をスキーマに渡します。返ってきたエラーの文言を、ブラウザで出す文言として保存します。

そのため、min(1, '…')のように自分で付けた文言も、ブラウザとサーバーで同じになります。

requiredの決まり方

ts
z.object({ bio: z.string() });
// bio: { name: 'bio', type: 'text' }

z.object({ title: z.string().min(1) });
// title: { name: 'title', required: true, type: 'text', minLength: 1 }

z.object({ age: z.coerce.number().optional() });
// age: { name: 'age', type: 'number', step: 'any' }

JSON Schemaのrequiredは「キーがある」という意味で、入力欄が空かどうかは表しません。そこでformFieldsは、入力欄が空のときの送信内容がスキーマに合うかどうかでrequiredを決めます。

上の例で印を付けた行のとおり、空の文字列を受け付けるbioと、空のままでよいageにはrequiredが付きません。parseFormも同じ値をスキーマに渡すので、ブラウザとサーバーの判断がそろいます。

空のときに入力欄が送る値の一覧はスキーマの対応にあります。

ブラウザで確かめない検証

スキーマ全体に付けた.refine()や、フラグ付きの正規表現は、HTMLの属性で表せません。formFieldsはこうした検証をdroppedに並べて返します。どの検証が載るかはスキーマの対応にあります。

本番環境以外では、スキーマごとに1回、console.warnでも一覧を出します。どの検証もサーバーでは必ず行われます。

defineFormで宣言したルールはdroppedに載らず、ブラウザとサーバーが同じ処理で確かめます。宣言の仕方は複数の入力欄の検証にあります。

エラーになるスキーマ

ファイル以外の送信値は文字列なので、z.number()やz.date()ではどの入力もスキーマに合いません。z.recordやタプルのように、送信する名前が決まらない形もあります。

formFieldsとparseFormは、こうしたスキーマを受け取った時点でエラーになります。通らないフォームや、入力を読み違えるフォームを作らないためです。

エラーになるスキーマの一覧はスキーマの対応にあります。

保証すること

  • ブラウザで動くuseFormは、zodもスキーマも読み込みません。
  • キーを押すたびにフォームが再描画されることはありません。
  • JavaScriptが無くても、制約の属性に合わない送信はブラウザで止まります。
  • 送信に失敗すると、送信した値が入力欄に戻ります。input: "password"を付けたフィールドの値は戻しません。
  • ブラウザで出す文言は、同じ検証でサーバーが返す文言と同じです。
  • 空の入力欄について、ブラウザのrequiredとparseFormは同じ判断をします。
  • スキーマ全体に付けた.refine()やフラグ付きの正規表現のように、HTMLの属性で表せない検証はdroppedに載ります。parseFormは、それも含めてすべての検証をサーバーで行います。
  • 表せないスキーマは、formFieldsとparseFormを呼んだ時点でエラーになります。

保証しないこと

  • droppedに載った検証は、ブラウザでは確かめません。
  • JavaScriptが読み込まれるまでは、ルールを確かめません。エラーはブラウザ自身の文言で知らせます。
  • 1つのフィールドや入れ子のオブジェクト、配列の行に付けた.refine()は、droppedに載りません。
  • @k8ordo/uiのNumberFieldが出す範囲のエラーは、zodの文言ではありません。
  • 選んだファイルは、送信に失敗すると入力欄に戻りません。
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。