@k8ordo/form

エラーの表示

ブラウザの検証で見つかったエラーも、サーバーが返したエラーも、同じfield()のerrorで読みます。エラーをどこに表示するかと、送信に失敗したときにフォーカスがどこへ移るかが分かります。

このページの内容

入力欄のエラー

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

<label htmlFor="title">Title</label>
<input {...title.input} aria-describedby="title-error" id="title" />
{title.error !== undefined && <p id="title-error">{title.error}</p>}
`error`があるときだけ表示する

field()が返す値のうち、errorにはその欄のエラーの文言が入ります。invalidは、エラーがあるかどうかです。

エラーが出るのは、入力欄から離れたときと送信したときです。入力中に新しいエラーは出ません。表示中のエラーは、正しい値に直すと消えます。

サーバーが返したエラーは、その欄を編集するまで残ります。ブラウザの検証で見つかったエラーがあれば、そちらが優先されます。

文言の変更

ts
z.object({
  title: z.string().min(1, 'Enter a title').max(120, 'Keep it to 120 characters'),
});

表示される文言は、zodのエラーメッセージです。文言を変えるときは、スキーマに書きます。

ブラウザの検証もサーバーの検証も同じスキーマから文言を読むので、どちらで見つかっても同じ文言になります。

文言の翻訳

src/routes/[locale]/talks/new/page.tsx
import { titleMissing } from '../../../../messages/talk';

const talkSchema = z.object({
  title: z.string().min(1, { error: () => titleMissing() }),
});

export default function NewTalkPage() {
  const talkFields = formFields(talkSchema);
  return <TalkForm action={createTalk} fields={talkFields} />;
}

文言は、文字列にせず関数のままzodに渡します。zodはエラーを報告するときに関数を呼ぶので、そのときのロケールの文言になります。titleMissingのような文言の書き方は文言を見てください。

defineFormのルールにも、requiredWhen('reason', 'status', 'rejected', reasonRequired)のように関数を渡せます。

警告

落とし穴

formFieldsは、描画の中で呼びます。モジュールのトップレベルで呼ぶと、最初に読み込んだときのロケールで文言が固定されます。

Server ActionでparseFormを呼ぶときのロケールの決まり方は今のロケールを見てください。

失敗した欄へのフォーカス

送信に失敗すると、ページで最初に失敗した入力欄へフォーカスが移ります。このために書くコードはありません。

「最初」は、ページに並んでいる順です。スキーマに書いたキーの順ではありません。

警告

落とし穴

自分で組み立てたstateを返すときは、新しいtokenを入れます。tokenが同じだと、同じ内容の失敗が2回続いたときに同じ結果とみなされ、フォーカスが移りません。

フォーム全体のエラー

tsx
<form {...form.props} action={formAction}>
  {form.formError.message !== undefined && (
    <p {...form.formError.props}>{form.formError.message}</p>
`id`と`tabIndex={-1}`が付く
  )}
  {/* fields */}
</form>

どの入力欄にも属さないエラーは、form.formErrorに入ります。pathを指定せずにスキーマ全体に付けた.refine()のエラーがその例です。

表示する要素にはformError.propsを展開します。要素がフォーカスを受け取れるようになるので、フォーカスが移るとスクリーンリーダーがエラーを読み上げます。

表示する場所は、入力欄より上にします。入力欄も失敗したときは先にこちらへフォーカスが移り、Tabキーで入力欄へ進めます。

サーバーで見つかる失敗

actions.ts
export async function createTalk(
  _prev: FormState,
  formData: FormData,
) {
  const parsed = parseForm(talkSchema, formData);
  if (!parsed.success) return parsed.state;

  if (await titleExists(parsed.data.title)) {
    return {
      ...parsed.state,
      errors: { title: 'A talk with this title already exists' },
入力欄の名前をキーにして文言を足す
    };
  }

  await saveTalk(parsed.data);
  redirect(href('/talks'));
}

タイトルがすでに使われている、といった失敗はデータベースを見るまで分かりません。parseFormを通ったあとに見つけた失敗は、parsed.stateにエラーを足して返します。

parsed.stateには、入力された値と新しいtokenが入っています。値は入力欄に戻ります。

Playground

エラーのデモ

ハンドルとパスワードを登録するフォームで、文言はすべてページのスキーマから作っています。

試してみる

  1. ハンドルにabと入力して欄から離れると、3文字以上にするよう求めるエラーが出ます。
  2. 確認用のパスワードを違う値にすると、一致しないというエラーが出ます。
  3. 空の欄を残したまま「登録」を押すと、最初に失敗した欄へフォーカスが移ります。
k8ordo

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