Files
pages/docs/design/navigation-home-sidebar.md
T
Anya Tokugawa 0964fdc5b7
Build and publish container images / images (push) Successful in 10m56s
Release container images / release (push) Successful in 18s
feat: adapt home appearance to wallpaper colors
2026-11-07 22:51:56 +09:00

12 KiB

Home layouts and navigation sidebar

実装済みのトップページ

配色テーマ(Index、Railgun、Nanoha等)とレイアウトを分離する。 /-/sys/config?panel=home でドメインごとに設定する。

home_layout 表示
classic(既定) 従来のトップバーと home_path のページ。未指定時はルート一覧
search トップバーなし、画面中央にWiki名と検索欄
directory トップバーなし、中央上部に検索欄、その下にブックマーク

すべてのトップページ検索は scope=/。これは現在のドメイン全体であり、 他ドメイン横断検索ではない。/ で /top を表示しても検索対象は /。 /top 自体に直接アクセスした場合は通常のViewerとして /top 配下検索を維持する。 既存のパス検索を使用し、全文検索エンジンの追加はこの変更に含めない。

home_bookmarks はJSONの [{label,href}] をドメイン設定に保存する。 管理UIは panel=bookmarks の行編集式マネージャーとし、名前とPath/URLを指定する。 従来のJSONは互換維持し、指定方法を表す kind を任意追加する。 最大64件。HTTP(S)とルート相対パスのみ許可し、ローカルのリンクは表示時に 現在の閲覧権限を確認する。個人ブックマークとは区別する。 home_path の内容はclassicでのみ表示し、レイアウト切替で元ページを変更しない。 検索型でもアカウントメニューとCity Mapのポップアップは右上から開ける。

実装済みの壁紙とPath Picker

ドメイン設定の home_wallpaper_path は、単一の画像Page Pathまたは仮想フォルダの Pathを受け取る。画像の場合は固定表示し、フォルダの場合は直下にある image/* のPageだけを候補としてリクエストごとに暗号学的乱数で1件選ぶ。 再帰走査はせず、本文の読み込みやプレビュー生成も行わない。候補とRaw配信の双方に 現在の閲覧権限を適用し、非公開画像の存在を匿名トップページへ漏らさない。 HTMLは候補がある場合だけ private, no-cache とし、画像本体の通常キャッシュは維持する。

home_wallpaper_opacity は0–100の整数で、表示時に0–1へ変換する。画像は装飾目的の 空alt、固定配置、object-fit: cover とし、Classic、Search、Directory、home_path、 Diary/Blogトップに共通適用する。コンテンツは独立した上位stacking layerに置く。

設定画面のPath欄は共通 GET /_/api/v1/path-picker を利用する。APIはDomainと現在の Principalで直下の子だけを認可し、最大250件、private, no-store で返す。 any、file、folder、image、image-or-folder の型を持ち、UIは対象input IDと modeをdata属性で指定する。これにより今後のストレージ、アダプタ、City設定でも 任意HTMLや専用ファイルブラウザを増やさず同じPickerを再利用できる。

実装済みの壁紙連動配色

壁紙の色調からアクセントとグラス面の配色を生成し、トップ画面 / とその上で開く ダイアログにだけ適用する。通常のViewer、Editor、設定画面、ログイン画面の配色は 変更しない。iframe内に独立して表示されるビューにも配色は継承しない。

設定は /-/sys/config?panel=home またはトップ画面右下の歯車から行う。既存のトップ 画面設定と同じ管理権限を必要とし、ドメイン共通で保存する。歯車のダイアログでは その場でプレビューし、キャンセル・ESCで保存前の状態に戻す。

項目 値と既定値
壁紙との色連動 off、accent、surface。既定は surface(背景も連動)
色の反映量 0–100。既定は35。0では元のテーマを維持
明暗 preserve(既定、現在のテーマを維持)、auto(表示時の壁紙の明るさから判定)

home_wallpaper_palette に {"mode":"surface","strength":35,"brightness":"preserve"} の形式で保存する。明暗の自動判定は背景も連動する場合だけ有効。グラスの透明度は 既存の home_glass_transparency で独立して調整する。警告・エラー等の意味を持つ色は 上書きしない。壁紙がない場合、画像が壊れている場合、Canvasから色を読めない場合、 強制カラーモードの場合は元のテーマを維持する。

表示済みの画像を64×64へ縮小し、初回描画後のアイドル時間に平均色と彩度を重み付け したアクセント候補を抽出する。追加の画像取得、サーバでの画像解析、定期ジョブは不要。 画像表示URLは選択したリビジョンに固定し、抽出結果をDomain UUIDと画像SHA256の組で sessionStorageに最大24件保存する。キャッシュにはRGB値と透明部分の割合だけを保存し、 画像本体は保存しない。ストレージが使えない場合は表示中の画像から抽出する。

文字・リンクは推定したグラス背景とのコントラストを補正する。ただし画像の局所的な 明暗までは保証しないため、細かい柄で読みにくい場合は透明度を下げるか色連動をオフにする。 既存テーマを切り替えた際は新しいテーマを基準に再計算し、オフにするとそのテーマに戻る。

回帰テストは node --test static/js/home-palette-core.test.cjs と TestHomePalette*。 PAGESWIKI_BROWSER_TEST=1 でブラウザテストを有効化すると、一時DBと合成画像を使い、 保存・キャンセル・再読み込み時のキャッシュ利用・テーマ切替・画面幅を通して検証する。

サイドバー詳細設計(実装待ち)

管理画面のグループ化されたサイドバーは Configuration panels に従い実装済み。 以下はViewer等の共通ナビゲーションサイドバーの設計である。

Viewer、Browser、Treeで共通のナビゲーションコンポーネントを導入する。 Browserの既存サイドバーは現在独自実装であるため、共通化時に置換する。 Editorの編集幅と検索型トップページの中央配置を維持するため、これらの画面では 初期状態を閉じる。City Mapポップアップ内にはサイドバーを表示しない。

表示要素の順序は次のとおり。

  1. 現在のドメイン名、全体検索、Homeへのリンク。
  2. 管理者設定の共通ブックマーク。今回の home_bookmarks を共通データとして使う。
  3. 現在のパスを起点とするディレクトリツリー。パンくずで上位へ移動できる。
  4. City Mapへの入口と、そのパスに対応するQuartier / Street / Spot。
  5. 将来の個人ブックマーク、最近閲覧・編集したページ。Activity機能のAPIに接続する。

DOMは共通partialと独立したCSS/JavaScriptへ分離する。配色は既存テーマ変数を使用。 PCでは左側の幅可変ペイン(初期16rem、12–28rem)、小画面ではオーバーレイとする。 開閉ボタンは aria-expanded / aria-controls を更新し、オーバーレイはESCで閉じ、 トリガーへフォーカスを戻す。非表示状態で本文のグリッド幅を残さない。

ユーザの幅・開閉・展開状態は (Domain UUID, Principal UUID, root Path, UI version) 単位で端末に保存する。ページ名・本文・API応答はlocalStorageに保存しない。 ログアウト・アカウント切替時は読み込み中リクエストとメモリ上の一覧を破棄する。

サイドバー用データ取得契約(実装待ち)

GET /_/api/v1/navigation/children?path=/docs&limit=100&cursor=... を追加する。 直接の子のみを返し、path, label, is_directory, has_children, object_uuid(ある場合), next_cursor を含める。曖昧なPageと仮想フォルダの 二重行は作らず、同じパスに本文と子がある状態を表現する。

サーバ側はDomain/Principalの現行権限を適用し、子の存在フラグも閲覧可能な子から 算出する。隠しページの件数を返さない。上限200、パス順のカーソル方式とし、 権限チェック後にページを構成する。認可はバッチ化し、共有キャッシュには 認可済み結果を無条件で入れない。応答は private, no-store から開始する。

初期描画ではサイドバーの枠と現在のパスだけを描画する。展開時に子を取得し、 同時リクエスト数を2に制限する。画面遷移時はAbortControllerで中止する。 プレビュー生成、全文取得、全Domainツリー取得はこのAPIの仕事に含めない。 将来の大規模ツリーは直接の親パス索引/派生ディレクトリテーブルを導入し、 Path mutationと同一トランザクションで更新する。

実装済みのTree View

/v/tree は従来どおりルート、/v/tree/{path} は指定パス配下だけを表示する。 SQLで範囲を絞り、同名接頭辞(/docs2)、大文字小文字の違い、別Domain、 % / _ を含むパスが混ざらない。/u 名前空間の除外と行単位の認可を維持する。 パンくず、フォルダ行の配下リンク、アップロード先が現在のルートを引き継ぐ。 全展開を初期状態とし、折りたたみ状態をホストと表示ルートごとに保存する。 サイドバーと共通化する段階で保存キーにDomain/Principal UUIDを追加する。

Browser初回表示の調査・是正

2026-09-13の読み取り調査で data/pages.db は944 Paths、1,614 Revisions。 EXPLAIN QUERY PLAN は最新リビジョン取得に全走査と一時ソートを示していた。 既存DBで revision_metadata_v1 が適用済みの場合、後から同じマイグレーションに 追加されたインデックス作成が省略されることを確認した。

是正内容:

  • Hack Nerd Font v3.2.1を同梱し、Browser/TreeのCDNフォント依存を除去。 font-display: swap で初回の文字表示をフォント取得完了まで待たせない。
  • 完了済みマイグレーションでも idx_revisions_object_created を確認・作成。
  • BrowserのSQLを、配下全体の全Revisionを順位付けする方式から、まず直下の 子を集約し、表示するファイルだけ最新Revisionを検索する方式へ変更。
  • 文書を持つフォルダの重複行を統合。表示する文書のサイズはDocument Storeの statを優先し、SQL互換本文では文字数ではなくバイト数を使用。
  • テンプレートの言語・タイムゾーン設定を1描画につき1回取得する。

合成データ(500 Pages、20 Revisions/Page、4KiB/Revision)での BenchmarkBrowserNestedHistory は旧SQL約96.6ms、新処理約0.74ms。 これはローカルのSQL中心の比較で、実環境の初回表示全体の速度保証ではない。 再実行: go test ./internal/store -run '^$' -bench BenchmarkBrowserNestedHistory。

反映後の実DBでは最新Revision検索が USING COVERING INDEX idx_revisions_object_created (object_uuid=?) に変わったことを確認した。 app/app2のhealthは200、設定済みHost pages.anya.jp でローカルTTFと トップページCSSの200配信を確認。トップページ3形式と配下TreeのHTMLは 一時DBを用いたHTTPハンドラテストで検証している。

残課題: 直下の子の集約は配下Pathsの走査を伴う。大規模化には派生ディレクトリ索引、 ページング、認可のバッチ化が必要。一般Browserの子件数は権限別に計算する設計へ 改める。これらは上記サイドバーAPIと同じ取得層にまとめる。