@k8ordo/form

クライアントAPI

Client Componentで使う、@k8ordo/formのフックとコンポーネント、型の一覧です。サーバーで呼ぶ関数は「サーバーAPI」のページにあります。

このページの内容

useForm

import元 @k8ordo/form

formFieldsが作った入力欄の情報を、<form>とその中の入力欄に結び付けます。

ts
useForm(fields: FormFields, state?: FormState): UseFormReturn

引数

fieldsFormFields
Server ComponentでformFieldsを呼んだ結果。propsで受け取ったものをそのまま渡します。
stateFormState
Server Actionが返したFormState。useActionStateが返す1つ目の値です。アクションの無いGETのフォームでは省きます。

戻り値

UseFormReturn — <form>に展開するpropsと、入力欄ごとの表示を返す関数。

フィールド

props{ onSubmit, onBlur, onInput, onReset, ref }
<form>に展開するイベントハンドラとref。ほかの要素には付けません。
field(path) => FieldView
パスを渡すと、その入力欄のFieldViewを返します。入れ子のフィールドはuser.emailのようにドットでつなぎます。
array(path) => ArrayView
繰り返し行の配列のパスを渡すと、そのArrayViewを返します。
formErrorFormErrorView
どの入力欄にも属さないエラーと、それを表示する要素に展開するprops。
isDirtyboolean
どれかの入力欄の値が描画したときから変わっていればtrue。行の追加や削除も含みます。
revalidate(control) => void
入力欄の検証の結果を読み直し、入力欄から離れたときと同じように文言を表示します。useAsyncCheckに渡します。

注意

  • 入力された値はReactのstateに保存せず、DOMから読みます。キー入力のたびに再描画されることはありません。
  • 展開したあとに自分のonSubmitを書くと、props.onSubmitが上書きされます。自分の処理の中からform.props.onSubmit(event)を呼んでください。
  • noValidateはマウント時にJavaScriptで付け、サーバーが返すHTMLには含めません。JavaScriptを読み込むまでは、ブラウザが入力を検証します。
  • 新しいstateを受け取ると、エラーのある箇所のうち画面上で最初のものへフォーカスを移します。対象は、検証に失敗した入力欄と、formErrorや配列のエラーを表示する要素です。stateは中身とtokenで見分けるので、手で作るときはtokenも変えます。
talk-form.tsx
const [state, formAction] = useActionState(createTalk, {});
const form = useForm(fields, state);
const title = form.field('title');

<form {...form.props} action={formAction}>
  <input {...title.input} />
  {title.error !== undefined && <p>{title.error}</p>}
</form>

作り方の流れははじめるを見てください。エラーの表示はエラーの表示を見てください。

FieldView

import元 @k8ordo/form

form.field()が返す、1つの入力欄の表示に使う値です。

ts
type FieldView = {
  input: FieldInput;
  error: string | undefined;
  invalid: boolean;
  required: boolean;
};

フィールド

inputFieldInput
入力欄に展開する属性。nameやtype、requiredなどです。送信に失敗したあとは、送った値がdefaultValueに入ります。
errorstring | undefined
いま表示するエラー文言。ブラウザの検証かサーバーの検証の結果です。無ければundefinedです。
invalidboolean
errorがあるときにtrue。aria-invalidなどに渡します。
requiredboolean
スキーマが空の送信を受け付けないときにtrue。ラベルに必須の印を付けるのに使います。

注意

  • サーバーのエラーは、その入力欄を書き換えるまで残ります。ブラウザの検証のエラーがあれば、そちらを優先します。
  • z.stringbool()の入力欄だけは、inputにvalueが入ります。チェックしたときに送る文字列です。

ArrayView

import元 @k8ordo/form

form.array()が返す、繰り返し行の表示に使う値です。

ts
type ArrayView = {
  rows: RowView[];
  add: () => void;
  canAdd: boolean;
  canRemove: boolean;
  error: string | undefined;
  errorProps: { id: string; tabIndex: -1 };
};

フィールド

rowsRowView[]
いま表示している行。1行ずつがRowViewです。
add() => void
末尾に行を1つ追加します。
canAddboolean
行数がスキーマの.max()より少なければtrue。
canRemoveboolean
行数がスキーマの.min()より多ければtrue。
errorstring | undefined
配列そのもののエラー。行数が.min()や.max()に合わないときに入ります。行の入力欄には表示されません。
errorProps{ id: string; tabIndex: -1 }
errorを表示する要素に展開するidとtabIndex={-1}。送信に失敗したとき、この要素にフォーカスを移せるようにします。
order-form.tsx
const items = form.array('items');

{items.rows.map((row) => (
  <div key={row.key}>
    <input {...row.field('name').input} />
    {items.canRemove && (
      <button onClick={row.remove} type="button">
        Remove
      </button>
    )}
  </div>
))}
{items.canAdd && (
  <button onClick={items.add} type="button">
    Add a row
  </button>
)}

RowView

import元 @k8ordo/form

繰り返し行の1行です。

ts
type RowView = {
  key: string;
  index: number;
  field: (itemKey?: string) => FieldView;
  remove: () => void;
};

フィールド

keystring
行を見分ける値で、keyに渡します。行を削除しても、ほかの行のkeyは変わりません。
indexnumber
いまの位置。0から数えます。
field(itemKey?: string) => FieldView
行の中の入力欄のキーを渡すと、そのFieldViewを返します。nameはitems[0].nameの形になります。文字列などの配列では引数を省きます。
remove() => void
この行を削除します。

注意

  • 行の中のキーは、パスと違って型で確かめません。書き間違えると、描画したときにエラー[@k8ordo/form] 配列 'items' に 'nmae' がありません。になります。

FormErrorView

import元 @k8ordo/form

form.formErrorの型です。スキーマ全体の.refine()のエラーのように、どの入力欄にも属さないエラーを持ちます。

ts
type FormErrorView = {
  message: string | undefined;
  props: { id: string; tabIndex: -1 };
};

フィールド

messagestring | undefined
state.formErrorの文言。無ければundefined。
props{ id: string; tabIndex: -1 }
文言を表示する要素に展開するidとtabIndex={-1}。送信に失敗したとき、この要素にフォーカスを移せるようにします。

useAsyncCheck

import元 @k8ordo/form

入力欄から離れたときに、その値をサーバーに問い合わせます。名前がすでに使われていないかなど、サーバーにしか分からない検証に使います。

ts
useAsyncCheck(
  check: (value: string) => Promise<string | undefined>,
  revalidate: UseFormReturn['revalidate'],
): AsyncCheck

引数

check(value: string) => Promise<string | undefined>
値を受け取り、表示する文言を返す関数。問題が無ければundefinedを返します。Server Actionをそのまま渡せます。
revalidateUseFormReturn['revalidate']
useFormが返すrevalidate。結果を受け取ったら、これで入力欄の文言を表示します。

戻り値

AsyncCheck — 入力欄に展開するpropsと、問い合わせの途中かどうか。

フィールド

props{ onBlur, ref }
入力欄に展開するonBlurとref。field().inputと並べて展開します。
isCheckingboolean
結果を待っている間はtrue。送信ボタンを無効にするのに使います。

注意

  • 返された文言はsetCustomValidityで入力欄に設定され、ほかのエラーと同じくerrorに入ります。
  • 結果が前後して返っても、最後に問い合わせた値の結果だけを使います。最後に結果を受け取った値のまま入力欄を離れても、問い合わせ直しません。
  • 入力欄を空にして離れると、前の結果は消えます。関数が失敗したときは何も付けず、送信後のサーバーの検証に任せます。失敗したときのエラーはreportErrorでブラウザに報告します。
slug-field.tsx
const slug = form.field('slug');
const taken = useAsyncCheck(checkSlugAvailable, form.revalidate);

<input {...slug.input} {...taken.props} />
<button disabled={taken.isChecking} type="submit">Save</button>

HiddenValue

import元 @k8ordo/form

<input name>を描画しないコンポーネントの値を、フォームの送信に含めます。リッチテキストエディタなどに使います。

ts
<HiddenValue name={string} value={string} />

引数

namestring
送信するときの名前。スキーマでのパスと同じにします。
valuestring
送信する値。コンポーネントのstateをそのまま渡します。

注意

  • 値が変わるたびにinputイベントを発火するので、複数の入力欄にまたがるルールやisDirtyがキー入力と同じように反応します。
  • リセットしても値は戻りません。値は呼び出し側のstateなので、そちらも戻してください。
post-form.tsx
<Editor onChange={setBody} value={body} />
<HiddenValue name="body" value={body} />

FormFields

import元 @k8ordo/form

formFieldsが返し、useFormが受け取る値の型です。中身はJSONなので、Server Componentからpropsで渡せます。

ts
type FormFields<FieldPath, ArrayPath, StringCheckboxPath> = {
  fields: Record<FieldPath, DerivedField>;
  arrays: Record<ArrayPath, DerivedArray>;
  rules: DerivedRule[];
  dropped: DroppedCheck[];
};

フィールド

fieldsRecord<FieldPath, DerivedField>
パスごとのフィールドの情報。入力欄の属性と、検証ごとの文言を持ちます。
arraysRecord<ArrayPath, DerivedArray>
パスごとの繰り返し行の情報。行数の上限と下限、1行分の入力欄を持ちます。
rulesDerivedRule[]
defineFormで宣言した、複数の入力欄にまたがるルール。文言はformFieldsを呼んだ時点で決まっています。
droppedDroppedCheck[]
ブラウザでは確かめない検証の一覧。HTMLの属性で表せないものが入ります。サーバーでは確かめます。

注意

  • 型引数は3つです。フィールドのパスと配列のパス、z.stringbool()のフィールドのパスです。formFieldsの戻り値から推論されるので、ふつうは書きません。
  • @k8ordo/formと@k8ordo/form/serverのどちらからもimportできます。
k8ordo

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