@riebeckite/plugin-color-mode 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright Rerurate_514
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,166 @@
+# @riebeckite/plugin-color-mode
+
+Light / dark / system color-mode switching for Riebeckite sites. The control
+writes to `data-theme` on `<html>` at runtime, exactly the attribute the
+themes' CSS uses to pick a palette — so it works with every built-in theme and
+needs no JavaScript in the theme itself.
+
+[日本語](./README_ja.md)
+
+## Overview
+
+Themes derive their palette from three CSS states (see
+[theme-system.md](../../../docs/en/theme-system.md)):
+
+- `:root` — light
+- `:root[data-theme="dark"]` — dark
+- `@media (prefers-color-scheme: dark) { :root:not([data-theme]) }` — follow the OS ("system")
+
+The plugin is a thin runtime switch over that contract:
+
+- `ColorModeScript` — a one-line inline script for `<head>` that applies the
+  saved mode **before first paint**, preventing a flash of the wrong theme.
+- `ColorModeToggle` — a segmented control with light / dark / system buttons.
+- `initColorMode` — the client entry that binds the buttons, persists the
+  choice in `localStorage` and keeps the document in sync.
+
+`colorModePlugin()` itself only registers the stylesheet and the client entry;
+everything else is delivered through the two components you render in your site
+shell.
+
+## Usage
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { colorModePlugin } from "@riebeckite/plugin-color-mode";
+
+export default defineConfig({
+  // ...
+  plugins: [colorModePlugin()],
+});
+```
+
+`colorModePlugin()` bundles `style.css` and declares `initColorMode` as a client
+entry.
+
+### Render the components
+
+```tsx
+import { ColorModeScript, ColorModeToggle } from "@riebeckite/plugin-color-mode";
+
+// ...in your renderer
+return (
+  <html {...themeAttributes()}>
+    <head>
+      <ColorModeScript />
+      {/* stylesheets, ... */}
+    </head>
+    <body>
+      <header>
+        <ColorModeToggle />
+      </header>
+      {children}
+    </body>
+  </html>
+);
+```
+
+`<ColorModeScript />` must be rendered in `<head>` ahead of the stylesheets so
+the mode is set before CSS is applied. `<ColorModeToggle />` can go anywhere;
+positions in headers and navbars are typical.
+
+### Props
+
+`ColorModeScript`
+
+| Prop | Description |
+| ---- | ----------- |
+| `storageKey` | localStorage key to read from. Defaults to `riebeckite-color-mode`. |
+
+`ColorModeToggle`
+
+| Prop | Description |
+| ---- | ----------- |
+| `storageKey` | localStorage key to persist under. Defaults to `riebeckite-color-mode`. |
+| `modes` | Modes to offer, in order. Defaults to `["light", "dark", "system"]`. |
+| `labels` | Per-mode `aria-label` overrides: `{ light?, dark?, system? }`. |
+| `label` | Group `aria-label`. Defaults to `"Color mode"`. |
+
+Anything you configure here must be reflected on both components if you change
+the storage key.
+
+## How the mode is decided
+
+1. On first paint, `ColorModeScript` applies the persisted value if it is a
+   valid mode (`light`, `dark` or `system`); otherwise it leaves the
+   `data-theme` the server already emitted (from your theme's `colorMode`).
+2. On load, `initColorMode` repeats the same logic and syncs the buttons'
+   `aria-pressed` state.
+3. Clicking a button persists the choice and re-applies it immediately.
+   `"system"` **removes** the `data-theme` attribute, so the OS preference CSS
+   takes over.
+
+Since themes are presentation-only, the SSRed `data-theme` comes from your
+theme's `colorMode`. The plugin only overrides it when the visitor has chosen
+otherwise.
+
+## CSS hooks
+
+| Hook | Purpose |
+| ---- | ------- |
+| `rr-color-mode` | Root container of the toggle. |
+| `rr-color-mode__button` | A single mode button. |
+| `rr-color-mode__icon` | The inline SVG icon. |
+
+The stylesheet uses `--rb-color-*` tokens, so the control follows the active
+theme. The root is `display: none` until `initColorMode` (or the inline script)
+sets `data-rb-color-mode="ready"` on `<html>`: with JavaScript disabled the
+control never appears.
+
+## Accessibility
+
+- The container is a `<fieldset>` whose `<legend>` names the group (rendered
+  visually hidden).
+- Each button is `type="button"` with an `aria-label` naming its mode; the
+  active one carries `aria-pressed="true"` set by the runtime.
+- Icons are decorative (`aria-hidden`); labels come from the buttons.
+- Transitions are disabled under `prefers-reduced-motion`.
+
+## Events
+
+`initColorMode` dispatches a `CustomEvent` on `document`:
+
+```ts
+document.addEventListener("riebeckite:color-mode", (event) => {
+  event.detail.mode; // "light" | "dark" | "system"
+});
+```
+
+Nothing consumes it yet. It exists so integrations (for example re-rendering
+diagrams) can follow mode changes in the future.
+
+## Limitations
+
+- Diagram plugins (`d2`, `mermaid`, `vega-lite`) read `data-theme` once at
+  initialization. After switching modes they keep their previous palette until
+  the page is reloaded. Listening for `riebeckite:color-mode` is the hook for a
+  future re-render.
+- The inline script is subject to Content-Security-Policy. If your `script-src`
+  forbids inline scripts, allow it by nonce or hash.
+- `localStorage` access is wrapped in `try/catch`; when storage is unavailable
+  the switch still works for the current page but is not persisted.
+- Multiple toggles on one page should share the same `storageKey`.
+
+## Exports
+
+- `colorModePlugin()` — plugin factory
+- `ColorModeToggle` — the switch component
+- `ColorModeScript` — the before-paint inline script component
+- `initColorMode` — browser init (also exported by `@riebeckite/plugin-color-mode/client`)
+- Constants: `COLOR_MODES`, `COLOR_MODE_STORAGE_KEY`, `COLOR_MODE_EVENT` (and friends)
+- Type: `ColorMode`
+
+## See also
+
+- [Theme system](../../../docs/en/theme-system.md)
+- [`@riebeckite/plugin-ux`](../ux/README.md)

package/README_ja.md

@@ -0,0 +1,136 @@
+# @riebeckite/plugin-color-mode
+
+Riebeckite サイト向けのライト / ダーク / システム連動のカラーモード切替プラグインです。実行時に `<html>` の `data-theme` 属性へ書き込みます。これはテーマが配色を選ぶのに使う属性そのものなので、組み込みの全テーマで動作し、テーマ側に JavaScript は一切必要ありません。
+
+[English](./README.md)
+
+## 概要
+
+テーマの配色は次の 3 つの CSS 状態で決まります（[theme-system.md](../../../docs/ja/theme-system.md) 参照）:
+
+- `:root` — ライト
+- `:root[data-theme="dark"]` — ダーク
+- `@media (prefers-color-scheme: dark) { :root:not([data-theme]) }` — OS に追随（system）
+
+プラグインはこの契約に対する薄い実行時スイッチです:
+
+- `ColorModeScript` — `<head>` に置く 1 行のインラインスクリプト。**最初の描画の前に**保存済みモードを適用し、テーマのちらつき（FOUC）を防ぎます。
+- `ColorModeToggle` — ライト / ダーク / システムのセグメント型コントロール。
+- `initColorMode` — クライアントエントリ。ボタンの結線、`localStorage` への保存、ドキュメントの状態同期を行います。
+
+`colorModePlugin()` はスタイルシートとクライアントエントリの登録だけを行います。UI はサイトシェルで描画する 2 つのコンポーネントから届きます。
+
+## 使い方
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+import { colorModePlugin } from "@riebeckite/plugin-color-mode";
+
+export default defineConfig({
+  // ...
+  plugins: [colorModePlugin()],
+});
+```
+
+`colorModePlugin()` は `style.css` をバンドルし、`initColorMode` をクライアントエントリとして宣言します。
+
+### コンポーネントの描画
+
+```tsx
+import { ColorModeScript, ColorModeToggle } from "@riebeckite/plugin-color-mode";
+
+// ...レンダラー内
+return (
+  <html {...themeAttributes()}>
+    <head>
+      <ColorModeScript />
+      {/* スタイルシート, ... */}
+    </head>
+    <body>
+      <header>
+        <ColorModeToggle />
+      </header>
+      {children}
+    </body>
+  </html>
+);
+```
+
+`<ColorModeScript />` は CSS が適用される前にモードが確定するよう、スタイルシートより先に `<head>` へ置いてください。`<ColorModeToggle />` はヘッダーやナビバーなど任意の場所に配置できます。
+
+### Props
+
+`ColorModeScript`
+
+| Prop | 説明 |
+| ---- | ---- |
+| `storageKey` | 読み取り元の localStorage キー。既定値は `riebeckite-color-mode`。 |
+
+`ColorModeToggle`
+
+| Prop | 説明 |
+| ---- | ---- |
+| `storageKey` | 保存先の localStorage キー。既定値は `riebeckite-color-mode`。 |
+| `modes` | 表示するモード（順序付き）。既定値は `["light", "dark", "system"]`。 |
+| `labels` | モードごとの `aria-label` 上書き: `{ light?, dark?, system? }`。 |
+| `label` | グループの先頭に置く可視非表示の `<legend>` として使われます。既定値は `"Color mode"`。 |
+
+ストレージキーを変更する場合は、両コンポーネントで同じ値を指定してください。
+
+## モードの決定方法
+
+1. `ColorModeScript` が最初の描画時に保存値を適用します。値が有効なモード（`light` / `dark` / `system`）の場合のみ上書きし、それ以外はサーバーが出力した `data-theme`（テーマの `colorMode` 由来）をそのまま残します。
+2. 読み込み時に `initColorMode` が同じ判定を行い、ボタンの `aria-pressed` を同期します。
+3. ボタンを押すと選択を保存して即時に再適用します。`"system"` は `data-theme` 属性を**削除**し、OS の設定 CSS に委ねます。
+
+テーマは表示のみを担当するため、SSR 時の `data-theme` はテーマの `colorMode` から生成されます。プラグインは訪問者が別のモードを選んだときだけ上書きします。
+
+## CSS フック
+
+| フック | 用途 |
+| ---- | ---- |
+| `rr-color-mode` | トグルのルートコンテナ。 |
+| `rr-color-mode__button` | 個々のモードボタン。 |
+| `rr-color-mode__icon` | インライン SVG アイコン。 |
+
+スタイルシートは `--rb-color-*` トークンを使うため、アクティブなテーマに追従します。ルートは `display: none` で、`initColorMode`（またはインラインスクリプト）が `<html>` に `data-rb-color-mode="ready"` を付けるまで非表示です。JavaScript が無効なページではコントロールそのものが現れません。
+
+## アクセシビリティ
+
+- コンテナは `<fieldset>` で、グループ名は可視非表示の `<legend>`（`label` props）が提供します。
+- 各ボタンは `type="button"` でモード名の `aria-label` を持ち、アクティブなボタンには実行時設定の `aria-pressed="true"` が付きます。
+- アイコンは装飾（`aria-hidden`）。ラベルはボタンから提供されます。
+- `prefers-reduced-motion` ではトランジションを無効化します。
+
+## イベント
+
+`initColorMode` は `document` 上で `CustomEvent` を発火します:
+
+```ts
+document.addEventListener("riebeckite:color-mode", (event) => {
+  event.detail.mode; // "light" | "dark" | "system"
+});
+```
+
+現時点で消費するものはありません。図の再描画などの連携のための拡張ポイントです。
+
+## 制約
+
+- 図関連プラグイン（`d2` / `mermaid` / `vega-lite`）は初期化時にしか `data-theme` を読みません。モード切替後、リロードまでは前の配色のままです。将来の再描画のためのフックが `riebeckite:color-mode` イベントです。
+- インラインスクリプトは Content-Security-Policy の影響を受けます。`script-src` がインラインを禁止している場合は nonce や hash で許可してください。
+- `localStorage` へのアクセスは `try/catch` で保護しています。ストレージが使えない環境でも、そのページでは切替が機能します（永続化のみされません）。
+- 1 ページに複数のトグルを置く場合は、同じ `storageKey` を共有してください。
+
+## Exports
+
+- `colorModePlugin()` — プラグインファクトリ
+- `ColorModeToggle` — 切替コンポーネント
+- `ColorModeScript` — 描画前インラインスクリプトのコンポーネント
+- `initColorMode` — ブラウザ初期化関数（`@riebeckite/plugin-color-mode/client` からも export）
+- 定数: `COLOR_MODES` / `COLOR_MODE_STORAGE_KEY` / `COLOR_MODE_EVENT` ほか
+- 型: `ColorMode`
+
+## 関連
+
+- [テーマシステム](../../../docs/ja/theme-system.md)
+- [`@riebeckite/plugin-ux`](../ux/README_ja.md)

package/dist/client.d.ts

@@ -0,0 +1 @@
+export { initColorMode } from "./src/init.js";

package/dist/client.js

@@ -0,0 +1,100 @@
+// src/constants.ts
+var COLOR_MODES = ["light", "dark", "system"];
+var COLOR_MODE_STORAGE_KEY = "riebeckite-color-mode";
+var COLOR_MODE_ROOT_ATTRIBUTE = "data-color-mode-root";
+var COLOR_MODE_STORAGE_KEY_ATTRIBUTE = "data-color-mode-storage-key";
+var COLOR_MODE_BUTTON_ATTRIBUTE = "data-color-mode";
+var COLOR_MODE_READY_ATTRIBUTE = "data-rb-color-mode";
+var COLOR_MODE_EVENT = "riebeckite:color-mode";
+
+// src/init.ts
+var started = false;
+function initColorMode() {
+  if (started) return;
+  started = true;
+  const run = () => {
+    const roots = Array.from(
+      document.querySelectorAll(`[${COLOR_MODE_ROOT_ATTRIBUTE}]`)
+    );
+    apply(getCurrentMode(roots));
+    if (roots.length === 0) return;
+    for (const root of roots) {
+      const storageKey = readStorageKey(root);
+      for (const button of root.querySelectorAll(
+        `[${COLOR_MODE_BUTTON_ATTRIBUTE}]`
+      )) {
+        button.addEventListener("click", () => {
+          const mode = parseColorMode(
+            button.getAttribute(COLOR_MODE_BUTTON_ATTRIBUTE)
+          );
+          if (mode === null) return;
+          writeStoredMode(storageKey, mode);
+          apply(mode);
+        });
+      }
+    }
+    const storageKeys = new Set(roots.map(readStorageKey));
+    window.addEventListener("storage", (event) => {
+      if (event.key !== null && storageKeys.has(event.key)) {
+        apply(getCurrentMode(roots));
+      }
+    });
+  };
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", run, { once: true });
+  } else {
+    run();
+  }
+}
+function apply(mode) {
+  const element = document.documentElement;
+  if (mode === "system") {
+    element.removeAttribute("data-theme");
+  } else {
+    element.setAttribute("data-theme", mode);
+  }
+  element.setAttribute(COLOR_MODE_READY_ATTRIBUTE, "ready");
+  for (const button of document.querySelectorAll(
+    `[${COLOR_MODE_BUTTON_ATTRIBUTE}]`
+  )) {
+    button.setAttribute(
+      "aria-pressed",
+      button.getAttribute(COLOR_MODE_BUTTON_ATTRIBUTE) === mode ? "true" : "false"
+    );
+  }
+  document.dispatchEvent(
+    new CustomEvent(COLOR_MODE_EVENT, {
+      detail: { mode }
+    })
+  );
+}
+function getCurrentMode(roots) {
+  for (const root of roots) {
+    const stored = readStoredMode(readStorageKey(root));
+    if (stored !== null) return stored;
+  }
+  const theme = document.documentElement.getAttribute("data-theme");
+  return theme === "light" || theme === "dark" ? theme : "system";
+}
+function readStorageKey(root) {
+  return root.getAttribute(COLOR_MODE_STORAGE_KEY_ATTRIBUTE) ?? COLOR_MODE_STORAGE_KEY;
+}
+function readStoredMode(storageKey) {
+  try {
+    return parseColorMode(window.localStorage.getItem(storageKey));
+  } catch {
+    return null;
+  }
+}
+function writeStoredMode(storageKey, mode) {
+  try {
+    window.localStorage.setItem(storageKey, mode);
+  } catch {
+  }
+}
+function parseColorMode(value) {
+  return COLOR_MODES.includes(value ?? "") ? value : null;
+}
+export {
+  initColorMode
+};

package/dist/components/color-mode-script.d.ts

@@ -0,0 +1,10 @@
+export type ColorModeScriptProps = {
+    /** localStorage key to read the persisted choice from. Defaults to the plugin default. */
+    readonly storageKey?: string;
+};
+/**
+ * Inline script (and its `data-rb-color-mode="ready"` marker) that applies the
+ * persisted color mode before first paint, preventing a flash of the wrong
+ * theme. Render in `<head>`, ahead of the stylesheets.
+ */
+export default function ColorModeScript({ storageKey, }: ColorModeScriptProps): import("hono/jsx/jsx-dev-runtime").JSX.Element;

package/dist/components/color-mode-toggle.d.ts

@@ -0,0 +1,17 @@
+import { type ColorMode } from "../src/constants.js";
+export type ColorModeToggleProps = {
+    /** localStorage key to persist the choice under. Defaults to the plugin default. */
+    readonly storageKey?: string;
+    /** Modes to offer, in order. Defaults to `["light", "dark", "system"]`. */
+    readonly modes?: readonly ColorMode[];
+    /** Per-mode `aria-label` overrides. */
+    readonly labels?: Readonly<Partial<Record<ColorMode, string>>>;
+    /** Group label, used as the `<legend>`. */
+    readonly label?: string;
+};
+/**
+ * Server-rendered control to switch between light, dark and system color
+ * modes. The active state is applied by `initColorMode` at runtime; until the
+ * client runs the control is hidden by the stylesheet.
+ */
+export default function ColorModeToggle({ storageKey, modes, labels, label, }: ColorModeToggleProps): import("hono/jsx/jsx-dev-runtime").JSX.Element;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { default as ColorModeScript } from "./components/color-mode-script.js";
+export { default as ColorModeToggle } from "./components/color-mode-toggle.js";
+export { COLOR_MODE_BUTTON_ATTRIBUTE, COLOR_MODE_EVENT, COLOR_MODE_READY_ATTRIBUTE, COLOR_MODE_ROOT_ATTRIBUTE, COLOR_MODE_STORAGE_KEY, COLOR_MODE_STORAGE_KEY_ATTRIBUTE, COLOR_MODES, type ColorMode, } from "./src/constants.js";
+export { initColorMode } from "./src/init.js";
+/**
+ * Registers the color-mode plugin: bundles the toggle stylesheet and declares
+ * `initColorMode` as the browser entry point that wires up toggling at runtime.
+ */
+export declare function colorModePlugin(): import("@riebeckite/core").RiebeckitePlugin<unknown>;

package/dist/index.js

@@ -0,0 +1,202 @@
+// index.ts
+import {
+  createClientEntry,
+  createStyleAsset,
+  definePlugin
+} from "@riebeckite/core";
+
+// src/constants.ts
+var COLOR_MODES = ["light", "dark", "system"];
+var COLOR_MODE_STORAGE_KEY = "riebeckite-color-mode";
+var COLOR_MODE_ROOT_ATTRIBUTE = "data-color-mode-root";
+var COLOR_MODE_STORAGE_KEY_ATTRIBUTE = "data-color-mode-storage-key";
+var COLOR_MODE_BUTTON_ATTRIBUTE = "data-color-mode";
+var COLOR_MODE_READY_ATTRIBUTE = "data-rb-color-mode";
+var COLOR_MODE_EVENT = "riebeckite:color-mode";
+
+// components/color-mode-script.tsx
+import { jsx } from "hono/jsx/jsx-runtime";
+function ColorModeScript({
+  storageKey = COLOR_MODE_STORAGE_KEY
+}) {
+  const key = JSON.stringify(storageKey);
+  const ready = JSON.stringify(COLOR_MODE_READY_ATTRIBUTE);
+  const source = `(function(){var d=document.documentElement;var m=null;try{m=localStorage.getItem(${key})}catch(e){m=null}if(m==="light"||m==="dark"){d.setAttribute("data-theme",m)}else if(m==="system"){d.removeAttribute("data-theme")}d.setAttribute(${ready},"ready")})();`;
+  return /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: source } });
+}
+
+// components/color-mode-toggle.tsx
+import { Fragment, jsx as jsx2, jsxs } from "hono/jsx/jsx-runtime";
+var DEFAULT_LABELS = {
+  light: "Light",
+  dark: "Dark",
+  system: "System"
+};
+function ColorModeToggle({
+  storageKey = COLOR_MODE_STORAGE_KEY,
+  modes = COLOR_MODES,
+  labels = {},
+  label = "Color mode"
+}) {
+  return /* @__PURE__ */ jsxs(
+    "fieldset",
+    {
+      class: "rr-color-mode",
+      "data-color-mode-root": true,
+      "data-color-mode-storage-key": storageKey,
+      children: [
+        /* @__PURE__ */ jsx2("legend", { class: "rr-color-mode__legend", children: label }),
+        modes.map((mode) => /* @__PURE__ */ jsx2(
+          "button",
+          {
+            type: "button",
+            class: "rr-color-mode__button",
+            "data-color-mode": mode,
+            "aria-label": labels[mode] ?? DEFAULT_LABELS[mode],
+            children: /* @__PURE__ */ jsx2(
+              "svg",
+              {
+                class: "rr-color-mode__icon",
+                viewBox: "0 0 24 24",
+                width: "16",
+                height: "16",
+                fill: "none",
+                stroke: "currentColor",
+                "aria-hidden": "true",
+                children: iconShape(mode)
+              }
+            )
+          },
+          mode
+        ))
+      ]
+    }
+  );
+}
+function iconShape(mode) {
+  switch (mode) {
+    case "light":
+      return /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx2("circle", { cx: "12", cy: "12", r: "4" }),
+        /* @__PURE__ */ jsx2("path", { d: "M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41" })
+      ] });
+    case "dark":
+      return /* @__PURE__ */ jsx2("path", { d: "M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" });
+    case "system":
+      return /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx2("rect", { x: "2", y: "3", width: "20", height: "14", rx: "2" }),
+        /* @__PURE__ */ jsx2("path", { d: "M8 21h8M12 17v4" })
+      ] });
+  }
+}
+
+// src/init.ts
+var started = false;
+function initColorMode() {
+  if (started) return;
+  started = true;
+  const run = () => {
+    const roots = Array.from(
+      document.querySelectorAll(`[${COLOR_MODE_ROOT_ATTRIBUTE}]`)
+    );
+    apply(getCurrentMode(roots));
+    if (roots.length === 0) return;
+    for (const root of roots) {
+      const storageKey = readStorageKey(root);
+      for (const button of root.querySelectorAll(
+        `[${COLOR_MODE_BUTTON_ATTRIBUTE}]`
+      )) {
+        button.addEventListener("click", () => {
+          const mode = parseColorMode(
+            button.getAttribute(COLOR_MODE_BUTTON_ATTRIBUTE)
+          );
+          if (mode === null) return;
+          writeStoredMode(storageKey, mode);
+          apply(mode);
+        });
+      }
+    }
+    const storageKeys = new Set(roots.map(readStorageKey));
+    window.addEventListener("storage", (event) => {
+      if (event.key !== null && storageKeys.has(event.key)) {
+        apply(getCurrentMode(roots));
+      }
+    });
+  };
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", run, { once: true });
+  } else {
+    run();
+  }
+}
+function apply(mode) {
+  const element = document.documentElement;
+  if (mode === "system") {
+    element.removeAttribute("data-theme");
+  } else {
+    element.setAttribute("data-theme", mode);
+  }
+  element.setAttribute(COLOR_MODE_READY_ATTRIBUTE, "ready");
+  for (const button of document.querySelectorAll(
+    `[${COLOR_MODE_BUTTON_ATTRIBUTE}]`
+  )) {
+    button.setAttribute(
+      "aria-pressed",
+      button.getAttribute(COLOR_MODE_BUTTON_ATTRIBUTE) === mode ? "true" : "false"
+    );
+  }
+  document.dispatchEvent(
+    new CustomEvent(COLOR_MODE_EVENT, {
+      detail: { mode }
+    })
+  );
+}
+function getCurrentMode(roots) {
+  for (const root of roots) {
+    const stored = readStoredMode(readStorageKey(root));
+    if (stored !== null) return stored;
+  }
+  const theme = document.documentElement.getAttribute("data-theme");
+  return theme === "light" || theme === "dark" ? theme : "system";
+}
+function readStorageKey(root) {
+  return root.getAttribute(COLOR_MODE_STORAGE_KEY_ATTRIBUTE) ?? COLOR_MODE_STORAGE_KEY;
+}
+function readStoredMode(storageKey) {
+  try {
+    return parseColorMode(window.localStorage.getItem(storageKey));
+  } catch {
+    return null;
+  }
+}
+function writeStoredMode(storageKey, mode) {
+  try {
+    window.localStorage.setItem(storageKey, mode);
+  } catch {
+  }
+}
+function parseColorMode(value) {
+  return COLOR_MODES.includes(value ?? "") ? value : null;
+}
+
+// index.ts
+function colorModePlugin() {
+  return definePlugin({
+    name: "color-mode",
+    assets: [createStyleAsset("color-mode")],
+    clientEntries: [createClientEntry("color-mode", "initColorMode")]
+  });
+}
+export {
+  COLOR_MODES,
+  COLOR_MODE_BUTTON_ATTRIBUTE,
+  COLOR_MODE_EVENT,
+  COLOR_MODE_READY_ATTRIBUTE,
+  COLOR_MODE_ROOT_ATTRIBUTE,
+  COLOR_MODE_STORAGE_KEY,
+  COLOR_MODE_STORAGE_KEY_ATTRIBUTE,
+  ColorModeScript,
+  ColorModeToggle,
+  colorModePlugin,
+  initColorMode
+};

package/dist/src/constants.d.ts

@@ -0,0 +1,23 @@
+/** The modes a site can be in. */
+export declare const COLOR_MODES: readonly ["light", "dark", "system"];
+export type ColorMode = (typeof COLOR_MODES)[number];
+/** Default `localStorage` key used to persist the selected mode. */
+export declare const COLOR_MODE_STORAGE_KEY = "riebeckite-color-mode";
+/** Attribute on the root element rendered by `ColorModeToggle`. */
+export declare const COLOR_MODE_ROOT_ATTRIBUTE = "data-color-mode-root";
+/** Per-root override for the storage key. */
+export declare const COLOR_MODE_STORAGE_KEY_ATTRIBUTE = "data-color-mode-storage-key";
+/** Attribute on each mode button. */
+export declare const COLOR_MODE_BUTTON_ATTRIBUTE = "data-color-mode";
+/**
+ * Attribute set on `<html>` once the runtime is ready. The stylesheet keeps
+ * the toggle hidden until this is present, so pages with JavaScript disabled
+ * never show a non-functional control.
+ */
+export declare const COLOR_MODE_READY_ATTRIBUTE = "data-rb-color-mode";
+/**
+ * `CustomEvent` dispatched on `document` whenever the mode changes, with
+ * `{ detail: { mode } }`. Present for integrations (for example, re-rendering
+ * diagrams that read `data-theme`); nothing consumes it today.
+ */
+export declare const COLOR_MODE_EVENT = "riebeckite:color-mode";

package/dist/src/init.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Wires up color-mode toggling on the page: applies the persisted mode and
+ * binds every `ColorModeToggle` root. Safe to call more than once and a no-op
+ * when the DOM is already initialized.
+ */
+export declare function initColorMode(): void;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@riebeckite/plugin-color-mode",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "source": "./client.ts",
+      "default": "./dist/client.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "dependencies": {
+    "hono": "^4.12.25",
+    "@riebeckite/core": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist",
+    "style.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/color-mode"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Light / dark / system color-mode switching for Riebeckite.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "theme",
+    "color-mode",
+    "dark-mode"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": [
+    "./style.css"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs"
+  }
+}

package/style.css

@@ -0,0 +1,84 @@
+@layer components {
+  .rr-color-mode {
+    --rr-color-mode-ink: var(--rb-color-ink);
+    --rr-color-mode-muted: var(--rb-color-muted);
+    --rr-color-mode-surface: var(--rb-color-surface);
+    --rr-color-mode-surface-hover: var(--rb-color-surface-hover);
+    --rr-color-mode-border: var(--rb-color-border);
+
+    display: none;
+    align-items: center;
+    gap: 0.25rem;
+    margin: 0;
+    min-width: 0;
+    padding: 0.2rem;
+    border: 1px solid var(--rr-color-mode-border);
+    border-radius: 999px;
+  }
+
+  /* The legend names the group for assistive technology only. */
+  .rr-color-mode__legend {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* The control only appears once the runtime marked the page as ready, so
+     pages with JavaScript disabled never show a non-functional switch. */
+  html[data-rb-color-mode="ready"] .rr-color-mode {
+    display: inline-flex;
+  }
+
+  .rr-color-mode__button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2rem;
+    height: 2rem;
+    padding: 0;
+    color: var(--rr-color-mode-muted);
+    background: transparent;
+    border: 0;
+    border-radius: 999px;
+    cursor: pointer;
+    transition:
+      background-color 120ms linear,
+      color 120ms linear;
+  }
+
+  .rr-color-mode__button:hover {
+    color: var(--rr-color-mode-ink);
+    background: var(--rr-color-mode-surface-hover);
+  }
+
+  .rr-color-mode__button[aria-pressed="true"] {
+    color: var(--rr-color-mode-ink);
+    background: var(--rr-color-mode-surface);
+    box-shadow: inset 0 0 0 1px var(--rr-color-mode-border);
+  }
+
+  .rr-color-mode__icon {
+    display: block;
+    width: 1rem;
+    height: 1rem;
+  }
+
+  .rr-color-mode__icon path,
+  .rr-color-mode__icon circle,
+  .rr-color-mode__icon rect {
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .rr-color-mode__button {
+      transition: none;
+    }
+  }
+}