@k8ordo/form

入力欄の種類

入力欄の種類は、スキーマの型で決まります。型ごとに、スキーマを書いてinputを入力欄に渡せるようになります。

このページの内容

スキーマと入力欄の対応

ts
z.string()                        → type="text"
z.email() / z.url()               → type="email" / type="url"
z.iso.date() / z.iso.time()       → type="date" / type="time"
z.iso.datetime({ local: true })   → type="datetime-local"
z.coerce.number()                 → type="number"
z.boolean() / z.literal(true)     → type="checkbox"
z.stringbool()                    → type="checkbox" value="true"
z.file()                          → type="file"
z.enum([…])                       → <select>
z.array(z.enum([…]))              → type="checkbox"
z.uuid()                          → type="text"

field()が返すinputには、スキーマに応じた属性が入ります。多くの場合は、そのまま入力欄に展開します。ラジオボタンと複数選択では、下の節のとおり一部だけを渡します。

z.enum()とz.array(z.enum())のinputにはtypeが入りません。前者は<select>に展開し、後者は選択肢ごとのチェックボックスにします。ここに無い型(z.uuid()など)は、テキストの入力欄になります。

文字列

ts
z.object({
  handle: z.string().min(3).max(20).regex(/^[a-z0-9_]+$/),
});

// handle.input
// { name: 'handle', type: 'text', required: true,
//   minLength: 3, maxLength: 20, pattern: '^[a-z0-9_]+$' }

z.string()はテキストの入力欄になります。.min()はminlength、.max()はmaxlength、.regex()はpatternの属性になります。

z.email()はtype="email"、z.url()はtype="url"になり、書式はブラウザが確かめます。

警告

落とし穴

空のテキスト欄は""を送ります。.optional()を付けていても、.min(1)があれば空欄のままでは通りません。

空欄を許すときは、""を受け付けるスキーマにします。

ts
bio: z.string().min(1).optional(),
bio: z.string().max(200),

日付と時刻

ts
z.object({
  day: z.iso.date(),
  start: z.iso.time(),
  doors: z.iso.datetime({ local: true }),
});

z.isoの書式は、ブラウザの日付や時刻の入力欄になります。値はISO形式の文字列のまま受け取ります。

Dateとして受け取るにはz.coerce.date()を使います。この場合はテキストの入力欄になります。z.date()は文字列を受け付けないので、formFieldsがフォームが送信できる値がありませんというエラーにします。

数値

ts
z.object({
  seats: z.coerce.number().int().min(1).max(500),
  price: z.coerce.number().multipleOf(0.01).optional(),
});

// seats.input → { type: 'number', required: true, step: 1, min: 1, max: 500 }
// price.input → { type: 'number', step: 0.01 }

数値の入力欄はz.coerce.number()で書きます。type="number"になり、.min()と.max()はminとmaxの属性になります。

stepは、.int()があれば1に、.multipleOf()があればその値になります。どちらも無ければanyになり、小数も入力できます。

空の数値欄は何も送らず、0にもなりません。空欄を許すなら.optional()を付けます。

警告

落とし穴

z.number()は使えません。フォームが送る値はいつも文字列なので、どの入力も通りません。formFieldsがz.coerce.number() を使ってくださいというエラーにします。

選択肢から1つ

tsx
const format = form.field('format');

<select {...format.input}>
  <option value="">Choose a format</option>
  <option value="talk">Talk</option>
  <option value="workshop">Workshop</option>
</select>

z.enum()のinputは<select>に展開します。先頭に値が空の選択肢を置くと、requiredは「どれかを選ぶ」という意味になります。

.optional()を付けると、空の選択肢のままでも送信できます。

ラジオボタン

tsx
const format = form.field('format');

{['talk', 'workshop'].map((option) => (
  <label key={option}>
    <input
      defaultChecked={state.values?.format === option}
      name={format.input.name}
      required={format.input.required}
      type="radio"
      value={option}
    />
    {option}
  </label>
))}

ラジオボタンには、inputのnameとrequiredを渡します。前回の選択はstate.valuesを見て、選択肢ごとにdefaultCheckedで戻します。

@k8ordo/uiのRadioとRadioCardは、inputをそのまま展開できます。使い方はフォームを見てください。

警告

落とし穴

ラジオボタンにinputをそのまま展開しないでください。送信のあとはinputのdefaultValueに前回の値が入り、各ラジオボタンのvalueとぶつかります。

チェックボックス

ts
z.object({
  newsletter: z.boolean(),
  terms: z.literal(true, 'Agree to the terms to continue'),
});

z.boolean()はチェックボックスになります。チェックが無いときはfalseを受け取るので、必須の欄にはなりません。

規約への同意のように、チェックを必須にするときはz.literal(true)を使います。

文字列のチェックボックス

ts
z.object({
  inStock: z.stringbool().default(false),
});

// inStock.input → { name: 'inStock', type: 'checkbox', value: 'true' }

z.stringbool()のチェックボックスは、チェックされるとinput.valueの文字列を送ります。既定では"true"です。値がURLに残るGETのフォームで使います。

チェックが無いときは何も送らないので、.default(false)か.optional()を付けます。.default(true)は、formFieldsがfalse を送れませんというエラーにします。

複数選択

tsx
const tags = form.field('tags');
const checked = state.values?.tags;

{['react', 'css', 'a11y'].map((option) => (
  <label key={option}>
    <input
      defaultChecked={Array.isArray(checked) && checked.includes(option)}
      name={tags.input.name}
      type="checkbox"
      value={option}
    />
    {option}
  </label>
))}

z.array(z.enum())は、同じnameを持つチェックボックスの集まりになります。チェックされた値を配列で受け取り、1つも無ければ[]です。

.min(2)のような下限はHTMLの属性にならないので、ブラウザでは確かめません。ブラウザでも確かめるには、複数の入力欄の検証のminCheckedを宣言します。

ファイル

ts
z.object({
  slides: z.file().mime(['application/pdf']).max(10_000_000),
});

// slides.input → { name: 'slides', type: 'file', required: true,
//                  accept: 'application/pdf' }

z.file()はファイルの入力欄になり、.mime()はacceptの属性になります。

acceptはファイルを選ぶときの候補を絞るだけで、ブラウザは選ばれたファイルの種類を確かめません。種類と大きさは、サーバーだけで検証します。

送信に失敗しても、選んだファイルは入力欄に戻りません。ブラウザはファイルの入力欄に値を設定できないためです。

パスワード

ts
password: z.string().min(8).meta({ input: 'password' }),

スキーマにinput: "password"のメタ情報を付けると、type="password"の入力欄になります。

送信に失敗しても、入力されていた値はstate.valuesに含まれません。

情報

メモ

zod/miniには.meta()が無いので、.check(z.meta(…))で付けます。

ts
password: z.string().check(z.minLength(8), z.meta({ input: 'password' })),
k8ordo

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