パンくずの定義元は BreadcrumbSegment[] で、各段は name、href、current を持つ。現在地にも URL を保持し、画面では現在地をリンクにせず文字として描く(部品は @koyori-app/ui-vue の Breadcrumb)。AppBreadcrumbs は配列を描画するだけで、ルートや API 応答から段を組み直さない。
段の種類と行き先
段の組み立て方はページの種類で決まる。種類は lib/breadcrumbs.ts の breadcrumbRoute がパス名から引く。
| 種類 | 対象ページ | 段 |
|---|---|---|
static |
/、/settings/profile、/settings/security、/settings/tokens、/settings/apps |
画面名だけの一段 |
home |
/{tenant}、my-tasks、calendar、users/{user_id} |
ホーム > 画面名(/{tenant} はホームのみ) |
tenant |
settings、settings/members、projects/new |
ホーム > 画面名 |
project |
プロジェクトの tasks、settings、reviews、labels、docs |
ホーム > プロジェクト名 > 画面名(tasks は画面名なし) |
document |
docs/{file_id} |
ホーム > プロジェクト名 > ドキュメント > ドキュメント名 |
task |
tasks/{KEY-N} |
ホーム > プロジェクト名 > 親タスク名 > タスク名(親が無ければ親の段なし) |
ホームは現在のテナントの /{tenant} へ移動する。プロジェクト名はそのプロジェクトのタスク一覧 /{tenant}/projects/{projectKey}/tasks へ、親は同じプロジェクト内のタスク詳細へ移動する。タスク一覧の既定の表示形式は List で、別のボード用ルートは無い。
Guest には tenant 種類の段を出さない。テナント全体の設定と作成の権限が無く、案内先を開けないためである。
親子関係が二段以上深くても、直近の親だけを表示する。
名前の取得元
段の名前は、ページが取得済みの応答から読む。出所は次のとおりである。
| 段 | 取得元 |
|---|---|
| テナント | 既存のテナント一覧 |
| プロジェクト名 | プロジェクト一覧 |
| タスク名 | 詳細応答 |
| 親の名前と連番 | サブタスク欄が取得する relations 応答 |
| ドキュメント名 | 詳細画面が取得するファイルのメタデータ |
useBreadcrumbs は QueryCache の通知を購読して同じキーの状態を読むだけで、独自の query observer や通信を作らない。そのため、パンくずのための API は無い。テナントとプロジェクトは現在のルートのパラメータで毎回照合する。
未登録のページ
共通レイアウトのルートは breadcrumbRoute に列挙する。未登録のページとエラーページでは配列を空にし、パンくずの nav を描かない。直前のページの段を引き継ぐ状態を持たないので、登録し忘れても別のタスク名を表示することは無い。
現在 breadcrumbRoute に登録していないページは、サインイン前のページ(/signin など)に加えて /settings/preferences、/settings/theme、/settings/experiments、/{tenant}/gantt である。これらのページにパンくずは出ない。
取得中と失敗時
名前の取得中は骨組みを表示する。ヘッダー内の領域は配列が空のときも高さを保つ。
テナント、プロジェクト、タスク、ドキュメントのいずれかの取得に失敗すると段をすべて落とし、ページ本体のエラー処理には影響させない。親の取得だけが失敗した場合は親の段だけを落とす。現在の親 UUID と一致しない古い relations 応答は使わない。
長い名前と狭い画面
長い名前も省略せず全文を表示する。狭い画面でも全段を一列に保ち、パンくずのリスト内を横スクロールさせて、ページ全体の横幅を広げない。
BreadcrumbList への変換
toBreadcrumbList(segments, origin) は配列を変更しない純関数である。規則は次のとおりである。
originは呼び出し側が明示し、http と https のみ受け付ける- 末尾以外の URL を絶対 URL に変換する
positionは 1 から連番にし、末尾のitemは省く- 画面に表示する配列と同じ
nameを使う
未実装と既知の制限
公開プロジェクトのページが無いので、toBreadcrumbList はテスト以外から呼び出さず、HTML に構造化データを埋め込まない。将来公開ページを用意するときは、そのページの公開可否と origin を決めてから利用する。HTML へ埋め込む場合の script 用エスケープは、このオブジェクトへの変換とは別に実装する必要がある。
決定の記録
| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-09-09 | 親は直近の 1 段だけを表示する | 祖先を順に取得する通信を増やさず、直近の親へ移動を繰り返せば上位へ辿れる |
