Theming

トークン駆動のダーク/ライトテーマ切り替えです。リロード不要です。

トークン

src/styles/tokens.ts: getThemeTokens(theme) / deriveSurfaceTokens(bg, text)。少数の固定されたベーストークン(背景、テキスト、アクセント)に加え、bgをtextに向けて混ぜることで導出されるサーフェス/ボーダートークンです。新しい色相を導入することは決してありません。

リロードなしで適用する

src/styles/apply-theme.ts: 結果として得られるCSSカスタムプロパティと<html>上のdata-theme属性を書き込みます。テーマの切り替えは変数の値を変えるだけで、コンポーネントツリーの再描画は発生しません。

Zustand store

src/state/theme-store.ts: 選択されたテーマをlocalStorageに永続化し、最初の描画より前に同期的に適用するZustandストアです(誤ったテーマのちらつきはありません)。

Document Model

何かがコンポーネントに届く前に、生のOpenAPIドキュメントはメモリ上のモデル(tagGroups → endpoints)へ正規化されます。純粋なTypeScriptとして実装され、独立してテストされており、Reactへの依存はありません。4つの責務があります。

  • normalize.ts: @apidevtools/swagger-parserを介してすべての$refを参照解決し、宣言された順序を保ったままタグごとにエンドポイントをグループ化します。
  • cap-depth.ts: 「Copy OpenAPI」ボタンのために、参照解決済み(かつ循環している可能性のある)スキーマをJSON.stringifyに対して安全にします。
  • example.ts / schema-tree.ts: 同じスキーマから、型トークン付きのサンプルペイロードとナビゲート可能なスキーマツリーを、偽のデータを捏造することなく構築します。
  • filter.ts: サイドバーが使うクライアントサイド検索です。

スキーマを走査するすべての関数(flattenSchema、schemaToTreeNodes、extractValidationRules)は、数値の深さ上限ではなくオブジェクトの同一性によって訪問済みノードを追跡します。そのため、真に再帰的なDTOはN回展開したりクラッシュしたりせず、(circular reference) / ↩ circularという単一のマーカーを描画します。