TokenDashboard

静的トークンダッシュボードの Preact props、スタイルシート、既定値の扱いとプレビューの制約。

TokenDashboard は @takazudo/zdtp/dashboard が公開する Preact コンポーネントです。 タブデータを受け取り、ブラウザーのグローバル変数、パネルの初期化、ストレージへのアクセス、 hydration を必要とせず、読み取り専用の一覧をレンダリングします。

エクスポートと props

実行時の名前付きエクスポートは TokenDashboard です。 公開する型も同じサブパスから import できます。

import type {
  TokenDashboardProps,
  DashboardMode,
  DashboardInclude,
  DashboardChrome,
  DashboardPreviewKind,
  TabConfig,
  TierConfig,
  TierItem,
} from '@takazudo/zdtp/dashboard';

@takazudo/zdtp/dashboard/styles.css をホストの静的 CSS 処理で一度読み込みます。 ダッシュボードの JavaScript は CSS の副作用 import を持ちません。 この CSS は @takazudo/zdtp/styles.css と独立しており、ダッシュボードだけのページに パネル用スタイルシートは不要です。Preact が必要です。React アダプターや HTML 書き出し関数・CLI は提供しません。

命令的なクライアント API（未リリース）

@takazudo/zdtp/dashboard/client は同期関数の mountTokenDashboard(host, props) と TokenDashboardProps、 TokenDashboardHandle 型を公開します。ハンドルの dispose() は何度呼んでも安全です。 ホスト側の ref が所有する専用の空要素を渡します。要素と属性はホストが保持し、 初回マウント時に無関係の子要素があればエラーになります。同じ要素への再マウントは 以前の表示を置き換え、古いハンドルは新しい表示を削除できません。別々の要素は独立します。

import '@takazudo/zdtp/dashboard/styles.css';
import { mountTokenDashboard, type TokenDashboardProps } from '@takazudo/zdtp/dashboard/client';
import { tokenTabs } from './token-tabs';

export function setupDashboard(host: HTMLElement) {
  // host はホスト側フレームワークの ref が渡す空の要素。
  const props: TokenDashboardProps = { tabs: tokenTabs, mode: 'host', chrome: 'host' };
  const dashboard = mountTokenDashboard(host, props);
  return () => dashboard.dispose(); // ホスト側の破棄時に呼ぶ。
}

遅延 import を使う場合、破棄済みの ref に読み込み完了後のマウントを行わないよう ホスト側でキャンセルします。

export function setupLazyDashboard(host: HTMLElement, props: TokenDashboardProps) {
  let cancelled = false;
  let dashboard: import('@takazudo/zdtp/dashboard/client').TokenDashboardHandle | undefined;
  void import('@takazudo/zdtp/dashboard/client').then(({ mountTokenDashboard }) => {
    if (!cancelled) dashboard = mountTokenDashboard(host, props);
  });
  return () => { cancelled = true; dashboard?.dispose(); };
}

静的な Preact エントリーは引き続き Node SSR とクライアント JavaScript 不要の HTML に 利用できます。公開 CSS はどちらのエントリーでも明示的に読み込んでください。

Chrome の入力と派生値

スタイルシートは、継承される 4 つの色入力を公開しています。ページ全体とは異なる ダッシュボードの外観にする場合は、ラッパーまたは個別のダッシュボードへ設定します。

ダッシュボードはこの 4 つの名前を継承値として宣言するため、祖先からの上書きが コンポーネントの既定値に隠れません。--zdtp-dashboard-bg と --zdtp-dashboard-fg は light-dark() でライト／ダークの組を選びます。ミュート色と ボーダーはその組の color-mix() から派生し、ミュートの前景混合率は 58%、ボーダーは ライト 16%／ダーク 22% です。カード背景はライト背景へ白を 20%、ダーク背景へ黒を 8% 混ぜます。診断、フォーカス、定規、バー、サンプル、チェッカーボードの色も light-dark() とこれらの Chrome 入力からスタイルシート内で派生します。 ダッシュボードのルートは透明なので、周囲の面はホストページが決めます。

モード依存性と行リージョン

モード依存性は個々の行に属し、宣言された参照を通じてすべての参照先へ伝播します。 ダッシュボードはトップレベルの light-dark(light, dark) 値に対して splitLightDark() という 1 つのパーサーだけを使います。検出の優先順位は次のとおりです。

1. item.modes があれば、それを使います。

2. 次にセマンティックな { literal: { light, dark } } 上書きを使います。

3. 次に item.default のトップレベル light-dark(a, b) を解析します。

4. モード依存の行を参照する行もモード依存になります。

指定した mode に対応する側を表示します。mode="host" ではペアを light-dark(light, dark) のまま保持し、継承したスキームからブラウザーに側を選ばせます。 不正な式やネストした式はモードペアとして扱わず、宣言された値を保持してどちらの側も推測しません。

依存性の判定は行ごとなので、1 つのティアに両方の種類を置けます。空でない各タブと ティアは行単位で分割され、モード依存リージョンが先に置かれ、mode を見本へ使います。 モード非依存リージョンは後ろに置かれ、chrome を使います。各リージョン内では、元の タブ・ティア・行の順序を保持します。include="mode-dependent" または include="mode-independent" は、この表示分割の片方だけを選びます。絞り込み後も参照に 必要な非表示の宣言は削除されず、件数と診断は表示中の行を示します。

宣言された値

入力の契約は、実行中・保存済みのパネル状態ではなく宣言された既定値です。 アイテムの既定値、選択モードの colorExtras.semanticDefaults、 ベースロール行用の明示的な colorExtras.baseDefaults を使います。 名前付きスキームのプリセットやエディターの初期化処理は適用しません。 ピル付きの既定値も item.default を保持します。

参照は、宣言されたアイテム ID と実際の cssVar 名を基に解決します。 参照ティアやタブをまたぐカラーランプも対象です。各行には宣言元の値と CSS・参照先の テキストを残します。参照先の欠落・曖昧さ、変数の重複、循環、安全に扱えない値も 一覧から消さず、誤解を招くプレビューの代わりに診断を表示します。 Notes だけのタブは省略し、Notes HTML は挿入しません。順序は入力のタブ・ティア・アイテムに従います。

プレビューの種類とコンテキスト

DashboardPreviewKind は 'bar' | 'size' | 'line-height' | 'family' | 'weight' | 'radius' | 'duration' | 'color' | 'shadow' | 'text' です。 previewOverrides[cssVar]、TierConfig.preview の順に指定を使い、どちらもなければ カラーエディターの行には色サンプル、それ以外にはテキストを表示します。 duration と text は、アニメーションや視覚サンプルを付けずに値を表示します。 行間サンプルでは、previewBase が指すフォントサイズトークンを解決できる場合に使用します。

枠・背景・ラベルなどの外観は chrome に従います。既定値の 'light' はライト表示、 'dark' はダーク表示に固定します。'host' はホストで実際に使われる color-scheme を 継承するため、ホスト側で祖先要素に color-scheme を設定してください。 ダッシュボード自身はメディアクエリーを使わないので、アプリで明示的に切り替えた設定が OS の設定より優先されます。

トークンの見本は mode に応じた独自の color-scheme を持ち、既知の変数も プレビュー一覧の内側で宣言します。chrome を変えても、モード別の既定値や見本の カラースキームは変わりません。ダッシュボードの枠やラベルには専用の CSS カスタム プロパティを使い、一覧のトークンは参照しません。:root へのホスト変数の書き込みや パネル変更の購読も行いません。

CSS の式は保持し、あらゆる CSS プロパティの文法として計算・検証するものではありません。 単位、フォント、ビューポートなどのレイアウトコンテキストはブラウザーが提供します。 外部変数の依存先が不足している場合は、サンプルを表示せず診断を表示します。 安全に扱えないリソース参照の式はプレビューせず、URL・マスク用アセットも読み込みません。 テキストは Preact がエスケープします。

一部のデータを埋め込む場合は、参照先のティアも含めてください。 通常の静的 Preact レンダリングを使えば、クライアント JavaScript を必要としない出力を作れます。 hydration するかどうかはホスト側で選択できます。

組み合わせのレシピ

1 つの一覧を周囲のページに従わせるには、chrome と mode の両方を host にします。 ホストは祖先要素に color-scheme を設定する必要があります。

<TokenDashboard
  tabs={tokenTabs}
  chrome="host"
  mode="host"
  title="ページに従うトークン"
  id="page-following"
/>

3 インスタンスのリファレンスでは、依存行を固定モードごとに 1 回ずつ、独立行を全体で 1 回レンダリングします。これにより各モードのスナップショットでモード依存行を確認しながら、 独立した一覧の重複を避けられます。

<TokenDashboard tabs={tokenTabs} include="mode-dependent" mode="light" title="ライト依存トークン" id="tokens-light" />
<TokenDashboard tabs={tokenTabs} include="mode-dependent" mode="dark" title="ダーク依存トークン" id="tokens-dark" />
<TokenDashboard tabs={tokenTabs} include="mode-independent" chrome="host" title="共有トークン" id="tokens-shared" />

各インスタンスは 1 つのローカルな宣言スコープを持ちます。ページ内リンクが必要な場合は インスタンスごとに異なる id を指定してください。ID は自動生成されません。4 つの Chrome 入力を、ラッパーによって 1 つのインスタンスだけへ上書きすることもできます。

<div style="--zdtp-dashboard-light-bg: #fff7ed; --zdtp-dashboard-light-fg: #7c2d12; --zdtp-dashboard-dark-bg: #1c1917; --zdtp-dashboard-dark-fg: #fed7aa">
  <TokenDashboard tabs={tokenTabs} chrome="host" mode="host" title="暖色の Chrome" />
</div>

ダッシュボード内部の buildDashboardModel ヘルパーで両方の設定を扱う場合は、現在オプション オブジェクトを使えます。buildDashboardModel(tabs, { mode: 'dark', include: 'mode-dependent' }) の形式です。互換性のため、位置引数の buildDashboardModel(tabs, 'dark') オーバーロードも 残っています。内部統合の新しいコードでは include を明示できるオプション形式を使ってください。 これはパッケージの独立した dashboard export ではありません。

余白・色・タイポグラフィのレイアウト

余白 (bar) は、原点を揃えた定規付きの横長行で表示します。非負の px・rem、 単位なしのゼロ、解決できるローカル変数への直接のエイリアスを実寸で表示します。 目盛りは 8 CSS px 間隔、大目盛りは 64 CSS px 間隔です。rem の大きさは ホストのルートフォントサイズに基づきブラウザーが決めるため、固定の換算は行いません。 大きな値は縮小・上限設定せず、フォーカス可能な定規の内側でスクロールします。 ゼロの幅はゼロです。負の値、em、割合、calc() などの未対応の式は宣言を残し、 定規を表示できない理由を示します。参照先の欠落は診断も残します。

セマンティックでも参照ティアでもなく、元のアイテムがすべて色のティアは、 個別の色見本を連ねたパレットとして表示します。ラベルと値を含めて宣言順を保ち、 狭いコンテナーでは横スクロールします。名前からグループを推測したり、中間色を 生成したりしません。セマンティック・参照ティアは独立した色見本のままです。 変数ごとのプレビュー上書きも優先し、異なる表示が混在しても各トークンの位置と順序を保ちます。

size、family、weight、line-height は、高さが内容に応じて伸びる横長の 複数行見本を使います。ただし、パレット内の上書きでは元の色見本の位置を保ちます。 基準は 18px・行間 1.6 で、見本ごとに対象のプロパティだけを 変更します。行間見本では、解決できる previewBase をフォントサイズに使えます。 フォントはローカルで利用可能なものと CSS のフォールバックを使い、自動ダウンロードしません。

previewText は、インスタンス内のタイポグラフィ見本に共通する静的な文章です。 既定値は長めの英語・日本語の文章です。改行と空白を保持し、テキストをエスケープします。 明示的な空文字列は空のままです。長文は折り返し、非常に大きな文字は縮小せず 見本内でスクロールできます。組み込みの文章編集機能やパネル状態との同期はありません。