入力を数ステップに分ける

長い入力をウィザード形式にする。

長い入力を数ステップに分けるときは type: wizard にして、form の代わりに steps を書く。

page:
  type: wizard
  id: customer_wizard
  title: 顧客登録
  repository: customerRepository
  key: id
  steps:
    - id: basic
      title: 基本情報
      description: まず会社の基本情報を入力してください。
      layout: { columns: 2 }
      fields:
        - { field: code, label: コード, type: text, required: true }
        - { field: name, label: 会社名, type: text, required: true }
    - id: contact
      title: 連絡先
      description: 請求書の送付先になります。
      fields:
        - { field: email, label: メール, type: text, required: true,
            validators: [ { type: email } ] }

ステップは書いた順に進む。title がステップの見出し、description はその下に出る説明文（省略可）。

検証は「そのステップだけ」

「次へ」を押したときに検証されるのは、いま表示しているステップの項目だけ。後のステップの必須項目が空でも次に進める。

保存は最後のステップで1回だけ。 途中で離脱すれば何も保存されない。逆に言えば、途中の状態を残したい要求（下書き保存）には向かない。

ステップを丸ごと飛ばす

前の入力によって、そもそも聞かなくていいステップがある。ステップに visibleWhen を書くと、条件に合わないときは丸ごと飛ばす。

- id: billing
  title: 請求先
  visibleWhen: { field: kind, operator: equals, value: corporate }
  fields:
    - { field: billTo, label: 請求先名, type: text, required: true }

条件の書き方は項目やセクションの visibleWhen と同じ（all / any / not も使える）。見ているのはそこまでに入力した値なので、条件に使う項目は前のステップに置く。

飛ばしたステップは**「次へ」でも「戻る」でも通らない**し、上の歩数表示にも出ない。そして大事なのはこちら ── 隠れているステップの必須は、保存を止めない。「個人」を選んだ人に、誰にも見えない請求先の必須で保存できない画面を見せることにならない（画面にはどこが悪いかも出ないので、これは直しようがない詰まり方になる）。

同じ規則を2か所に書いていないからそうなる。ステップは内部ではセクションとして扱われるので、visibleWhen はそのままセクションの条件になり、「隠れているセクションの項目は検証しない」がそのまま効く。

条件で全部のステップが隠れるように書くこともできてしまう。そのときは1枚目を黙って出すのではなく「出せるステップがありません」と言って止まる（条件が効いていないように見えるほうが困る）。

いつウィザードにするか

form で足りるならウィザードにしない。ステップに分けるのは次のようなときだけ。

• 入力項目が多く、1画面に並べると利用者が諦める（20項目を超えるあたりから）
• 前の入力によって後で聞くことが変わる（区分を選んでから、その区分の項目だけ聞く）
• 入力の順番に業務上の意味がある

逆に、項目が10個程度なら1画面のほうが速い。ステップは「戻って直す」のが面倒なので、分けるほど親切とは限らない。

確認ステップを作る

最後に確認用のステップを置くと、保存前に見直せる。入力欄を並べ直すのではなく、計算項目で読み取り表示にするのが手軽。

- id: confirm
  title: 確認
  description: 内容を確認して保存してください。
  fields:
    - { field: summary, label: 登録内容,
        computed: { op: concat, fields: [code, name], separator: " / " } }

ステップの中は普通のフォームと同じ

fields に書けるものは form のセクションと同じ。型、必須、検証、正規化、条件表示、計算項目、明細（subTable）まで全部使える。layout もステップごとに変えられる。

セクションで区切ることはできない（ステップそのものがセクションの役割を果たす）。1ステップに詰め込みたくなったら、ステップを分ける。

key は1件を特定するため

key（既定は id）は、保存したレコードを識別するための項目。新規登録専用のウィザードでも、保存後にそのレコードを指すために使われる。

書けるキー

キー	書く場所	型	必須	既定値	有効なページ種別	説明
steps	wizardPage	array → wizardStep	必須	—	wizard	Steps, walked in declaration order.
description	wizardStep	string	任意	—	wizard	Optional explanatory text.

この表は spec/reference.json から生成している（JSON Schema が正）。手元では npx -p @hatake-fw/api hatake reference <キー名> で同じものが引ける。

近い例

例は丸ごと写して直すのが一番速い。以下は CI で検証済み（そのまま動く形）。

ファイル	種別	画面	どういうときに使うか
customer_wizard.yaml	wizard	顧客登録	項目が多いので入力をステップに分けて、1ステップずつ検証したい

よくある間違い

wizard 以外に steps を書く

なぜ駄目か steps は wizard だけのキー。逆に wizard は form を持たない（steps が section の役をする）。

こう直す 入力をステップに分けたいなら type: wizard にして、steps に id と title を持つステップを並べる。

間違い

page:
  type: form
  id: customer_wizard
  title: 顧客登録
  repository: customerRepository
  steps:
    - { id: basic, title: 基本情報 }

正しい

page:
  type: wizard
  id: customer_wizard
  title: 顧客登録
  repository: customerRepository
  steps:
    - id: basic
      title: 基本情報
      fields:
        - { field: code, label: コード, required: true }

spec/pitfalls.json から生成。各項目は CI で検証済み（間違いは本当に落ち、正しい方は本当に通る）。手元では npx -p @hatake-fw/api hatake pitfalls <キー名>。