@k8ordo/color-scheme

仕組み

@k8ordo/color-schemeが配色の決定とdarkクラスの付け外しをいつ、どこで行うかと、保証することとしないことが分かります。

このページの内容

配色を決める規則

scheme.ts
const resolve = (
  preference: ColorScheme | undefined,
  defaultPreference: ColorSchemePreference,
  systemDark: boolean,
): ColorScheme => {
  const chosen =
    preference ??
    (defaultPreference === 'system' ? undefined : defaultPreference);
  return chosen ?? (systemDark ? 'dark' : 'light');
};

配色は次の順に決まります。

  1. 訪問者が'light'か'dark'を選んでいれば、その配色になります。
  2. 選んでいなければ、プロバイダのdefaultPreferenceを見ます。'light'か'dark'なら、その配色になります。
  3. 既定値も'system'なら、(prefers-color-scheme: dark)に一致するかどうかで決まります。

保存した値がJSONのオブジェクトでないときや、preferenceが'light'でも'dark'でもないときは、「選んでいない」として読みます。ほかのフィールドは読みません。

「選んでいない」は、初めて訪れたときのOSの設定を保存したものではありません。既定値が'system'なら、選んでいない訪問者はあとでOSの設定を変えてもそれに従います。

スクリプトとプロバイダ

js
(() => {
  const s = (() => {
    try {
      const v = JSON.parse(
        localStorage.getItem('k8ordo-state:color-scheme'),
      );
      return v !== null && typeof v === 'object' && !Array.isArray(v)
        ? v
        : null;
    } catch {
      return null;
    }
  })();
  const v = s && s.preference;
  const p = v === 'dark' || v === 'light' ? v : 'system';
`defaultPreference`の値がここに入る
  if (
    p === 'dark' ||
    (p !== 'light' &&
      matchMedia('(prefers-color-scheme: dark)').matches)
  )
    document.documentElement.classList.add('dark');
})();

上は、defaultPreferenceが'system'のときにHTMLに書かれるインラインスクリプトを整形したコードです。同じ規則を、最初の描画の前はこのスクリプトが使い、ハイドレーションのあとはプロバイダが使います。

Reactが動くのはJavaScriptを読み込んだあとで、ブラウザはその前に描画を始めることがあります。プロバイダのeffectだけでクラスを付けると、ダークを選んだ訪問者にライトの画面が一瞬見えます。

スクリプトではスキーマを使えないので、保存した値は手で確かめます。結果は、ストアがスキーマで読んだときと同じです。保存した値を読む式はcolorSchemeState.inlineRead()が作り、キーと値の形は@k8ordo/stateの定義から取ります。

スクリプトの位置

html
<head>
  <meta charset="utf-8" />
  <script>(() => { … })()</script>
どのスタイルシートよりも前
  <link rel="stylesheet" href="/assets/index.css" />
</head>

ブラウザは、HTMLを読み進めて<script>に着いた時点でそれを実行します。ただし、前にスタイルシートがあると、その読み込みが終わるまで待ちます。待つ間にブラウザが描画すると、ダークの訪問者にもライトの画面が見えます。

ColorSchemeScriptを<head>に置くのは、どのスタイルシートよりも前で実行するためです。Reactは、持ち上げたスタイルシートを<head>の中でレイアウトの子より前に書きます。@k8ordo/frameworkは、<head>のインラインスクリプトをそのスタイルシートの前へ移します。上は、そうして送られる<head>です。

ハイドレーションのとき、Reactはこの<script>要素をそのまま引き継ぎ、もう一度は実行しません。

ハイドレーションの描画

provider.tsx
const useReadsStore = (): boolean =>
  useSyncExternalStore(
    subscribeNever,
    () => true,
    () => false,
  );

useEffect(() => {
  if (!readsStore) return;
  document.documentElement.classList.toggle(
    DARK_CLASS,
    scheme === 'dark',
  );
}, [readsStore, scheme]);

サーバーではlocalStorageもmatchMediaも使えません。そのためプロバイダは、何も保存されておらずOSはライトだとして描画します。ブラウザでの最初の描画、つまりハイドレーションの描画も、サーバーと同じ値を読みます。

この値をそのまま<html>に書くと、スクリプトが付けたクラスを外してしまいます。そこでuseReadsStoreはハイドレーションの描画でfalseを返し、その描画ではeffectがクラスを書きません。そのすぐあとの描画からはtrueを返します。ストアとOSの設定もその描画から読むので、クラスを書く描画はスクリプトと同じ配色になります。

Reactのハイドレーションも<html>の属性を書き戻しません。schemeから描画したマークアップでサーバーの値を表示しない方法は、切り替えボタンのページにあります。

ハイドレーション後の更新

ハイドレーションのあと、クラスを書くのはプロバイダだけです。保存した値かOSの設定が変わるたびに、規則で決め直します。schemeが変わると、effectが<html>のdarkを付け外しします。

  • 訪問者が選んだとき:setPreferenceがストアを更新し、新しい値は次の描画に反映されます。localStorageへの書き込みは、同じタスクの終わりにまとめて行われます。
  • OSの設定が変わったとき:プロバイダはmatchMedia('(prefers-color-scheme: dark)')のchangeを購読しています。
  • 別のタブで変わったとき:@k8ordo/stateのローカル状態は、このキーと、localStorage.clear()で発火するstorageイベントを購読しています。
Playground

入力と結果のデモ

このページがいま読んでいる入力と、プロバイダが出した結果です。

材料

matchMedia('(prefers-color-scheme: dark)').matches
ブラウザで読みます
localStorage.getItem('k8ordo-state:color-scheme')
ブラウザで読みます
useAppState(colorSchemeState)
ブラウザで読みます

結果

useColorScheme().preference
ブラウザで読みます
useColorScheme().scheme
ブラウザで読みます
document.documentElement.classList.contains('dark')
ブラウザで読みます

試してみる

  1. ヘッダーにある配色の切り替えボタンを押すと、localStorage.getItemとuseAppStateの行が変わり、結果の3行も変わります。
  2. 「システムに戻す」を押すと、localStorage.getItemの行は'{}'になり、preferenceはsystemになります。保存した値は消えず、{}が残ります。
  3. その状態でOSの外観の設定を切り替えると、matchMediaの行と、結果のschemeとクラスの行が変わります。このサイトのプロバイダにdefaultPreferenceは渡していないので、既定値は'system'です。
  4. このサイトを別のタブで開いて配色を切り替えると、こちらのタブの行もその場で変わります。

保証すること

  • インラインスクリプトがスタイルシートより前で実行できれば、ページは<html>のdarkクラスが決まった配色どおりになってから描画されます。
  • スクリプトとプロバイダは、同じ保存した値から同じ規則で配色を決めます。スキーマに合わない値は、どちらも「選んでいない」として読みます。
  • ハイドレーションの描画は<html>に書き込みません。スクリプトが付けたクラスは、ハイドレーションで外れません。
  • themeColorを渡すと、スクリプトはtheme-colorのmetaをクラスと同時に書きます。その色は、ハイドレーションのあとも画面の配色と同じです。
  • 何も選んでいない訪問者には既定値が適用されます。既定値が'system'なら、ページを開いたままでもOSの設定の変更に従います。
  • localStorageに書き込むのは、setPreferenceを呼んだときだけです。既定値も、初めて訪れたときのOSの設定も保存しません。
  • 別のタブで選んだ配色や、別のタブで消したlocalStorageは、このタブにも反映されます。

保証しないこと

  • サーバーは訪問者の配色を推測しません。Cookieもヘッダーも読まず、既定値から描画します。
  • schemeから描画したマークアップは、ハイドレーションが終わるまでサーバーで描画したときの値のままです。
  • CSPがインラインスクリプトを止めると、ハイドレーションまで<html>にdarkクラスは付きません。theme-colorのmetaは書かれないままです。nonceかハッシュは、アプリがポリシーに書きます。
  • スクリプトをスタイルシートより前に置くのは、HTMLを書く側です。@k8ordo/frameworkはそうしますが、ほかの仕組みでは送られるHTMLで確かめます。
  • ColorSchemeScriptとプロバイダに同じdefaultPreferenceを渡したかは確かめません。違うと、何も選んでいない訪問者の配色がハイドレーションのあとで切り替わります。
  • プロバイダが2つあると、それぞれがクラスを書きます。defaultPreferenceが違えば、配色が食い違います。
  • 同じタブでlocalStorage.setItemを直接呼んだ値は、再読み込みまで反映されません。storageイベントは書き込んだタブでは発火しません。
  • 書くのは<html>のdarkクラスと、themeColorを渡したときのtheme-colorのmetaだけです。ページの色とCSSのcolor-schemeプロパティは設定せず、prefers-contrastとforced-colorsも保存しません。
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。