ヘッダー右側アイテム

サイトヘッダー右側のクラスタ(検索・テーマ・言語切替など)をデータ駆動の配列で構成する。

ヘッダーの右側 — 検索、テーマ切替、言語スイッチャー、バージョンスイッチャー、GitHub リンク、Design Token / AI Chat トリガー — は settings.headerRightItems という 1 つの配列からレンダリングされます。各エントリは discriminated union で、配列の順番どおりに描画されます。

デフォルト設定

export const settings = {
  // ...
  githubUrl: "https://github.com/zudolab/zudo-doc",
  headerRightItems: [
    { type: "trigger", trigger: "design-token-panel" },
    { type: "trigger", trigger: "ai-chat" },
    { type: "component", component: "version-switcher" },
    { type: "component", component: "github-link" },
    { type: "component", component: "theme-toggle" },
    { type: "component", component: "language-switcher" },
  ],
};

組込みの Search コンポーネントは常にクラスタ末尾に描画され、この配列では構成しません。

アイテム種別

component

組み込みの UI 要素を参照します。対応する機能フラグが無効なら自動的にスキップされます。

{ type: "component", component: "github-link" }

機能を無効化すればエントリは黙って除外されるので、配列に残したままでも問題ありません。

trigger

組み込みのモーダルやパネルを開きます。

{ type: "trigger", trigger: "ai-chat" }

design-token-panel トリガーボタンは window に toggle-design-token-panel カスタムイベントをディスパッチします。zdtpパネル（@takazudo/zdtp）はこのイベントをネイティブに受け取るため、追加の配線は不要です。

link

任意の外部/内部リンクをアイコン付きで描画します。

{
  type: "link",
  href: "https://discord.example",
  ariaLabel: "Discord",
  icon: "github", // 現在同梱されているアイコンは "github" のみ
}

外部 URL は自動的に新しいタブで開きます。

html

任意のマークアップを差し込むためのエスケープハッチです。

{ type: "html", html: '<span class="text-caption">beta</span>' }

文字列がそのまま出力されるため、使いどころは限定してください。

カスタマイズ例

GitHub アイコンをあなたのリポジトリへ向ける

トップレベルの githubUrl を書き換えるだけで済みます。github-link コンポーネントはこの値を読むので、配列側に URL を書き足す必要はありません。

export const settings = {
  githubUrl: "https://github.com/your-org/your-repo",
};

githubUrl: false を指定すると、配列を編集せずにアイコンだけ消せます。

アイテムを外す

機能フラグでの非表示ではなく、配列から該当エントリを削除してください。たとえば AI chat トリガーを隠すなら:

headerRightItems: [
  { type: "trigger", trigger: "design-token-panel" },
  // { type: "trigger", trigger: "ai-chat" },  // 削除
  { type: "component", component: "version-switcher" },
  { type: "component", component: "github-link" },
  { type: "component", component: "theme-toggle" },
  { type: "component", component: "language-switcher" },
],

カスタムリンクを追加する

headerRightItems: [
  // ...既存のアイテム
  {
    type: "link",
    href: "https://discord.gg/your-server",
    ariaLabel: "Discord",
    icon: "github", // 他アイコン同梱までの暫定
  },
],

テーマ切替のカスタマイズ

組み込みの theme-toggle コンポーネントでたいていのサイトは事足ります。それでも、トグルを独自の場所に配置したい、自前の island ラッパーに組み込みたい、あるいは @takazudo/zudo-doc/theme バレル(React 解決の落とし穴があります — 後述)を避けたいといった理由で、プロジェクト内に 自前の ThemeToggle を持ち続ける場合があります。いずれの場合も、ローカルにコンポーネントを手でコピーするのではなく、専用の @takazudo/zudo-doc/theme-toggle サブパスから ThemeToggle をインポートしてください。

import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";

エクスポートされる ThemeToggle は、自前の <button> と組み込みの太陽/月アイコンを描画し、受け取るプロップは defaultMode("light" または "dark")の 1 つだけです。好きな場所に配置してその周りに UI を組み合わせることはできますが、ボタンのマークアップとアイコンは固定です — インポートはパッケージのトグルを再利用する(そして後述の衝突を避ける)ためのものであって、見た目を変えるためのものではありません。本当に異なるトグルのマークアップやアイコンが必要な場合は、自前のコンポーネントを作り、パッケージの island マーカーを主張しないように ThemeToggle 以外の名前を付けてください。

なぜパッケージの island をインポートするのか

zfb は(0.1.0-next.39 以降)npm の dist/ に同梱された "use client" モジュールをスキャンします。@takazudo/zudo-doc はスキャナから見える ThemeToggle island を同梱しています。同じ名前のローカル ThemeToggle を手でコピーすると、zfb は ThemeToggle という island マーカーを主張するコンポーネントを 2 つ 検出し、ビルドのたびに衝突警告を出します:

⚠ island marker name collision: "ThemeToggle" is produced by two different source files —
keeping <consumer>/src/components/theme-toggle.tsx and dropping
<pkg>/@takazudo/zudo-doc/dist/theme-toggle/index.js. ...

この警告は無害です — ローカルのコンポーネントが勝ち、正しくハイドレートされます — が、ノイズになりますし、「片方を残し、片方を捨てる」という解決はスキャン順に依存します。パッケージから ThemeToggle をインポートすれば同じマーカーに登録されるため、衝突するものがなくなり、手書きコピーの保守負担からも解放されます。

並び順

配列に書いた順にレンダリングされます。クラスタは右寄せなので、最初のエントリがナビ寄り、末尾のエントリがビューポート端寄りに配置されます。