loco_motion-rails 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46e6960770e08d768c1d294265dda365243b1e1869de61b67ded52be177614ef
-  data.tar.gz: 25859b6e5e9d269ed378fd5ee5241efd579094f5305e9875d5b5c06f9b2e2165
+  metadata.gz: 7f562576e236a298243e3c154e468e081c58471ba23b86e6dbc1486084c72db2
+  data.tar.gz: d3958a2260cee9c7d3529e64c4b7252c4921d4368143c9176e58f8545d7e2392
 SHA512:
-  metadata.gz: 32795ba20a4769bd55d2cd917ac78030b28832bfc6d90186eade88311e2043c1d40a76c4fd15b856fc109edf07c3268c81d52763c3cb43087189ee779b0f513d
-  data.tar.gz: 365d268fed487d7728bc5b1f229403fbadf05ceaae9141efab23f5837b2eebac5dcbcbc83a5d8dcdb2baad3c78a03fee5e7d65125f32d8c65ca4d8dc05c5b0d8
+  metadata.gz: 5e07962f154fe394cab75b5da4d9f973e8ccf99de55969ac40ab2d0562cdf7ca7c87367774c4f2e490b196a905ef4b35c6c70956c5f4147de5052174e164ed76
+  data.tar.gz: 99ada80a6c6237bdc8c315b26e7c45236753f794383e3bad1d2d0035c555e3486b23bb035fc36647f29b1e55b834e33d85967c53c6bb638bffe4e58ee80af0e0

data/README.md

@@ -13,6 +13,7 @@ ViewComponent, TailwindCSS, DaisyUI and more!
 - [Current Status](#current-status)
 - [Installation](#installation)
 - [Using Components](#using-components)
+- [Linting Component Usage](#linting-component-usage)
 - [Guides](#guides)
 - [Documentation & Demo](#documentation--demo)
 - [Developing](#developing)
@@ -70,7 +71,7 @@ Add the gem to your `Gemfile` and run `bundle`:
 
 ```ruby
 # Gemfile
-gem "loco_motion-rails", "~> 0.7.3", require: "loco_motion"
+gem "loco_motion-rails", "~> 0.8.0", require: "loco_motion"
 ```
 
 Some components also need a JavaScript package (for their Stimulus controllers)
@@ -104,6 +105,75 @@ For the full set of available components, parts, slots, and live examples, see
 the [demo site](https://loco-motion.profoundry.us/) and the
 [API documentation](#documentation--demo).
 
+## Linting Component Usage
+
+LocoMotion ships a [haml_lint](https://github.com/sds/haml-lint) rule that flags
+views hand-rolling DaisyUI markup instead of calling the helper that owns it —
+`.card` where `daisy_card` belongs. Views compose components; components own
+markup.
+
+Wire it up for whichever template language you use — both read the same derived
+map, so HAML and ERB are held to identical rules.
+
+**HAML** — add `haml_lint` to your bundle, then `.haml-lint.yml`:
+
+```yaml
+require:
+  - loco_motion/lint/haml_lint/component_usage
+
+linters:
+  LocoMotionComponentUsage:
+    enabled: true
+```
+
+```bash
+bundle exec haml-lint --include-linter LocoMotionComponentUsage app/views
+```
+
+**ERB** — add `erb_lint` to your bundle. It loads custom linters from a
+directory rather than a config key, so create `.erb_linters/loco_motion.rb`:
+
+```ruby
+require "loco_motion/lint/erb_lint/component_usage"
+```
+
+Then `.erb_lint.yml`:
+
+```yaml
+linters:
+  LocoMotionComponentUsage:
+    enabled: true
+```
+
+```bash
+bundle exec erb_lint --lint-all --enable-linters LocoMotionComponentUsage
+```
+
+Either way the output names the helper to reach for:
+
+```
+app/views/orders/show.html.haml:12 [W] LocoMotionComponentUsage: `.card` is
+  LocoMotion's daisy_card — call the helper instead of hand-rolling the markup
+```
+
+The class list is **derived** from the component registry and each component's
+own `add_css` declaration, so it tracks the library automatically — a component
+added in a release is covered by that release. Tailwind utilities (`flex`,
+`p-4`, `hover:*`) and DaisyUI modifiers (`btn-primary`) are never flagged;
+`css:` remains the sanctioned way to pass those to a helper.
+
+Suppress a deliberate exception the usual haml_lint way:
+
+```haml
+-# haml-lint:disable LocoMotionComponentUsage
+.card.custom-thing
+-# haml-lint:enable LocoMotionComponentUsage
+```
+
+Adopting this on an existing codebase will surface a backlog. `haml-lint
+--auto-gen-config` writes a TODO file that excludes today's offenders so new
+views are held to the rule while the backlog drains.
+
 ## Guides
 
 These optional guides cover the broader LocoMotion philosophies and a
@@ -139,18 +209,20 @@ for the time being, the latest documentation is available at the links below.
 To work on LocoMotion, first clone the repository and make sure you have Docker
 installed and running on your machine.
 
-Next, create a `.env.local` file with the following contents, making sure to
-replace the Unsplash keys with real ones (you can create your own account or ask
-Topher for his keys).
+Next, create a `docs/demo/.env.local` file with the following contents, making
+sure to replace the Unsplash keys with real ones (you can create your own
+account or ask Topher for his keys). The demo boots fine without them — only the
+example pages that pull sample photos will fail.
 
 ```.env
-# .env.local
+# docs/demo/.env.local
 UNSPLASH_ACCESS_KEY="<< INSERT ACCESS KEY >>"
 UNSPLASH_SECRET_KEY="<< INSERT SECRET KEY >>"
 ```
 
-You should then be able to run `just rebuild` in the project directory and then
-`just all-quick` to start the services.
+You should then be able to run `just build` in the project directory and then
+`just all-fast` to start the services. (`just rebuild` also works, but it passes
+`--no-cache`, which is wasted effort on a fresh clone with an empty cache.)
 
 > [!NOTE]
 >
@@ -165,7 +237,7 @@ You should then be able to run `just rebuild` in the project directory and then
 > See https://github.com/profoundry-us/loco_motion-buildpack for more info.
 
 From here, you can access the demo site at http://localhost:3000 and the YARD
-docs at http://localhost:8808/docs/yard
+docs at http://localhost:8808
 
 You can type `just demo-shell` to open a shell inside the demo Docker container,
 or `just loco-shell` to get a shell inside the gem's Docker container.

data/app/assets/stylesheets/loco.css

@@ -28,11 +28,48 @@
 @custom-variant where (:where(&));
 
 /*
- * `dark` variant — make `dark:` utilities respond to both an OS-level dark
- * preference and a DaisyUI ThemeController set to a dark theme, so manual theme
- * switching and system preference stay in sync.
+ * `dark` variant — make `dark:` utilities follow the app's actual theme, not
+ * just the OS preference. In priority order, `dark:` styles apply when:
+ *
+ *   1. `data-color-scheme="dark"` is set on an ancestor. LocoMotion's
+ *      ThemeController stamps this on `<html>` from the active theme's own
+ *      `color-scheme` declaration, so *any* dark DaisyUI theme (`night`,
+ *      `synthwave`, a custom theme, …) enables `dark:` utilities — no
+ *      hardcoded names.
+ *   2. `data-theme="dark"` is set on an ancestor — the name-based fallback
+ *      for apps that manage `data-theme` themselves without stamping a
+ *      scheme.
+ *   3. A checked `.theme-controller` input with `value="dark"` is present —
+ *      kept for pure-CSS/no-JS DaisyUI theme switching, where the theme
+ *      changes without `data-theme` ever being set.
+ *   4. The OS prefers dark (`prefers-color-scheme`) — the no-choice-saved
+ *      fallback, suppressed when any theme other than `dark` is explicitly
+ *      applied via `data-theme`, or when the stamped scheme is `light`
+ *      (mirrors DaisyUI's `--default` / `--prefersdark` semantics: an
+ *      explicit choice always wins).
+ *
+ * Note: without the scheme stamping (1), the fallbacks key on the theme
+ * *name* `dark`. Apps not running LocoMotion's ThemeController should either
+ * restyle the built-in `dark` theme (`@plugin "daisyui/theme" { name:
+ * "dark"; prefersdark: true; ... }`), stamp `data-color-scheme` themselves,
+ * or define their own `dark` variant.
  */
-@custom-variant dark (@media (prefers-color-scheme: dark), :root:has(input.theme-controller[value=dark]:checked) &);
+@custom-variant dark {
+  &:where([data-color-scheme="dark"], [data-color-scheme="dark"] *) {
+    @slot;
+  }
+  &:where([data-theme="dark"], [data-theme="dark"] *) {
+    @slot;
+  }
+  :root:has(input.theme-controller[value="dark"]:checked) & {
+    @slot;
+  }
+  @media (prefers-color-scheme: dark) {
+    &:not(:where([data-theme]:not([data-theme="dark"]), [data-theme]:not([data-theme="dark"]) *, [data-color-scheme="light"], [data-color-scheme="light"] *)) {
+      @slot;
+    }
+  }
+}
 
 /*
  * Reveal tooltips on keyboard focus when the `tooltip` class is applied

data/app/components/daisy/actions/theme_controller.js

@@ -4,15 +4,41 @@
  * A Stimulus controller that manages theme selection and persistence.
  * It handles theme switching, localStorage persistence, and synchronization
  * across multiple theme selectors on the same page.
+ *
+ * Themes are stored in two preference SLOTS — day and night — so users can
+ * keep a preferred theme for each. Either slot may hold ANY theme (some
+ * people run a dark theme during the day):
+ *
+ *   - `savedLightTheme` / `savedDarkTheme` — the theme saved in the day /
+ *     night slot. Classic switchers file a pick under the slot matching the
+ *     theme's own `color-scheme` declaration; slot-scoped pickers (the
+ *     `setSchemeTheme` action) file it under THEIR slot regardless.
+ *   - `savedLightScheme` / `savedDarkScheme` — the actual `color-scheme`
+ *     of the theme in each slot, cached at save time so the pre-paint
+ *     script can stamp it before any CSS loads.
+ *   - `savedThemeMode` — which slot is active: `"light"` or `"dark"` pin
+ *     that slot, while `"system"` follows the OS preference live, swapping
+ *     between the two saved themes as the OS switches.
+ *   - The legacy single `savedTheme` key is migrated on connect.
+ *
+ * Whenever a theme is applied, the DISPLAYED theme's own scheme is stamped
+ * on `<html>` as `data-color-scheme`, which drives the `dark:` Tailwind
+ * variant shipped in loco.css — so `dark:` utilities follow the theme
+ * actually showing, even a dark theme sitting in the day slot. The active
+ * slot is stamped as `data-theme-mode`.
  */
 import { Controller } from "@hotwired/stimulus"
 
 export default class extends Controller {
   /**
    * Called when the controller is connected to the DOM.
-   * Sets the initial theme input state and sets up event listeners.
+   * Migrates legacy storage, stamps the active color scheme, sets the
+   * initial theme input state, and sets up event listeners.
    */
   connect() {
+    this.migrateLegacyStorage()
+    this.stampScheme()
+    this.stampMode(this.safeStorageGet('savedThemeMode'))
     this.setInput()
 
     // Setup a custom listener to watch for changes on the page in case the
@@ -26,6 +52,11 @@ export default class extends Controller {
     // enough to save the theme and keep every other selector in sync.
     this.inputChangeListener = this.handleInputChange.bind(this)
     this.element.addEventListener('change', this.inputChangeListener)
+
+    // In "system" mode the active theme follows the OS preference live.
+    this.mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+    this.mediaChangeListener = this.mediaChanged.bind(this)
+    this.mediaQuery.addEventListener('change', this.mediaChangeListener)
   }
 
   /**
@@ -35,6 +66,7 @@ export default class extends Controller {
   disconnect() {
     window.removeEventListener('localstorage-update', this.storageChangeListener)
     this.element.removeEventListener('change', this.inputChangeListener)
+    this.mediaQuery.removeEventListener('change', this.mediaChangeListener)
   }
 
   /**
@@ -45,17 +77,44 @@ export default class extends Controller {
    */
   setInput() {
     const theme = this.getCurrentTheme()
-    const inputs = this.element.querySelectorAll('input.theme-controller')
+    const inputs = this.element.querySelectorAll('input.theme-controller, input[data-loco-theme-scheme]')
 
     inputs.forEach((input) => {
-      input.checked = input.value === theme
+      const scheme = input.dataset.locoThemeScheme
+
+      if (scheme) {
+        // Scheme-scoped picker radios show their SLOT's saved theme
+        // (falling back to the built-in theme of the same name), not the
+        // theme currently applied to the page.
+        const saved = this.safeStorageGet(scheme === 'dark' ? 'savedDarkTheme' : 'savedLightTheme')
+
+        input.checked = input.value === (saved || scheme)
+      } else {
+        input.checked = input.value === theme
+      }
+    })
+
+    // "Match system appearance" toggles reflect the saved mode, and
+    // "Night mode" toggles reflect the scheme actually showing (so they
+    // read correctly in system mode too).
+    const synced = this.safeStorageGet('savedThemeMode') === 'system'
+    const resolved = this.resolveTheme()
+    const activeScheme = (resolved && resolved.scheme) || this.computedScheme()
+
+    this.element.querySelectorAll('input[data-loco-theme-mode-toggle]').forEach((toggle) => {
+      toggle.checked = synced
+    })
+
+    this.element.querySelectorAll('input[data-loco-theme-night-toggle]').forEach((toggle) => {
+      toggle.checked = activeScheme === 'dark'
     })
   }
 
   /**
-   * Clears the user's theme preference from localStorage.
-   * Removes the saved theme and dispatches an event to notify other controllers.
-   * Also removes the data-theme attribute from the document element.
+   * Clears the user's theme preferences from localStorage.
+   * Removes every saved theme key and dispatches an event to notify other
+   * controllers. Also removes the `data-theme` and `data-color-scheme`
+   * attributes from the document element.
    *
    * @param {Event} event - The triggering click event
    */
@@ -71,15 +130,21 @@ export default class extends Controller {
       }
     }
 
-    // Remove the savedTheme from local storage
+    // Remove every saved theme key from local storage
     this.safeStorageRemove("savedTheme")
+    this.safeStorageRemove("savedThemeMode")
+    this.safeStorageRemove("savedLightTheme")
+    this.safeStorageRemove("savedDarkTheme")
+    this.safeStorageRemove("savedLightScheme")
+    this.safeStorageRemove("savedDarkScheme")
 
-    // Remove the data-theme attribute from the document element
+    // Remove the theme attributes from the document element
     document.documentElement.removeAttribute('data-theme')
+    document.documentElement.removeAttribute('data-color-scheme')
+    document.documentElement.removeAttribute('data-theme-mode')
 
     // Fire off an update
-    const updateEvent = new CustomEvent('localstorage-update', { detail: { key: 'savedTheme', newValue: null } })
-    window.dispatchEvent(updateEvent)
+    this.broadcast(null)
   }
 
   /**
@@ -106,6 +171,94 @@ export default class extends Controller {
     event.preventDefault()
   }
 
+  /**
+   * Changes how the active color scheme is chosen. Expects a Stimulus action
+   * param, e.g. `data-loco-theme-mode-param="system"`:
+   *
+   *   - `"light"` / `"dark"` — pin that scheme; its saved theme (or the
+   *     built-in `light`/`dark` theme when none is saved) applies.
+   *   - `"system"` — follow the OS preference live, swapping between the
+   *     saved light and dark themes as the OS switches.
+   *
+   * @param {Event} event - The triggering event with a `mode` param
+   */
+  setMode(event) {
+    const mode = event && event.params && event.params.mode
+
+    if (!mode) return
+
+    this.safeStorageSet('savedThemeMode', mode)
+    this.stampMode(mode)
+    this.applyResolvedTheme()
+
+    if (event.preventDefault) event.preventDefault()
+  }
+
+  /**
+   * Applies a theme into a SPECIFIC preference slot — the action behind
+   * slot-scoped pickers (a "Day theme" / "Night theme" dropdown pair).
+   * Expects a Stimulus action param naming the slot, e.g.
+   * `data-loco-theme-scheme-param="light"`. Unlike a classic switcher pick
+   * (which files the theme under its own color-scheme), the pick lands in
+   * the picker's slot even when the theme's scheme differs — a dark theme
+   * can be someone's daytime choice. The pick applies immediately and pins
+   * its slot.
+   *
+   * Like {setTheme}, the action can sit on a wrapper element containing an
+   * `<input>` or on the input itself.
+   *
+   * @param {Event} event - The triggering click event with a `scheme` param
+   */
+  setSchemeTheme(event) {
+    const slot = event && event.params && event.params.scheme
+    const target = event.currentTarget
+    const input = target.matches && target.matches('input')
+      ? target
+      : target.querySelector('input')
+
+    if (input && slot) {
+      this.applyTheme(input.value, slot)
+    }
+
+    event.preventDefault()
+  }
+
+  /**
+   * Backs the "Night mode" toggle (see the component's
+   * `build_night_toggle`). Checking it pins the dark scheme — the saved
+   * night theme applies immediately, no OS setting required — and
+   * unchecking pins light. Either direction is an explicit choice, so it
+   * leaves `system` mode.
+   *
+   * @param {Event} event - The change event from the toggle's checkbox
+   */
+  toggleNightMode(event) {
+    const mode = event.currentTarget.checked ? 'dark' : 'light'
+
+    this.safeStorageSet('savedThemeMode', mode)
+    this.stampMode(mode)
+    this.applyResolvedTheme()
+  }
+
+  /**
+   * Backs the "Match system appearance" toggle (see the component's
+   * `build_system_toggle`). Checking it enters `system` mode; unchecking it
+   * pins whichever scheme is currently showing, so the visible theme does
+   * not change when sync turns off.
+   *
+   * @param {Event} event - The change event from the toggle's checkbox
+   */
+  toggleSystemMode(event) {
+    const resolved = this.resolveTheme()
+    const mode = event.currentTarget.checked
+      ? 'system'
+      : ((resolved && resolved.scheme) || this.computedScheme())
+
+    this.safeStorageSet('savedThemeMode', mode)
+    this.stampMode(mode)
+    this.applyResolvedTheme()
+  }
+
   /**
    * Handles `change` events bubbling up from any theme-controller input within
    * this controller. Persists and broadcasts the newly selected theme so every
@@ -126,14 +279,79 @@ export default class extends Controller {
    * Persists the given theme, applies it to the document, and notifies every
    * other theme controller on the page so they can sync their inputs.
    *
+   * Without a `slot`, the theme is saved as the preference for the scheme
+   * it belongs to (read from its own computed `color-scheme`) — classic
+   * switcher behavior. With a `slot` (from a day / night picker), it lands
+   * in that slot regardless of its own scheme. Either way the slot's actual
+   * scheme is cached for the pre-paint script, the mode pins to the slot,
+   * and `data-color-scheme` reflects the DISPLAYED theme's own scheme so
+   * `dark:` utilities stay truthful.
+   *
    * @param {string} value - The theme name to apply
+   * @param {?string} slot - The preference slot to fill (`"light"` /
+   *   `"dark"`); defaults to the theme's own scheme
    */
-  applyTheme(value) {
-    this.safeStorageSet("savedTheme", value)
+  applyTheme(value, slot = null) {
     document.documentElement.setAttribute('data-theme', value)
 
-    const updateEvent = new CustomEvent('localstorage-update', { detail: { key: 'savedTheme', newValue: value } })
-    window.dispatchEvent(updateEvent)
+    const scheme = this.schemeForTheme(value)
+    const targetSlot = slot || scheme
+
+    this.safeStorageSet(targetSlot === 'dark' ? 'savedDarkTheme' : 'savedLightTheme', value)
+    this.safeStorageSet(targetSlot === 'dark' ? 'savedDarkScheme' : 'savedLightScheme', scheme)
+    this.safeStorageSet('savedThemeMode', targetSlot)
+    this.safeStorageRemove('savedTheme')
+
+    document.documentElement.setAttribute('data-color-scheme', scheme)
+    this.stampMode(targetSlot)
+
+    this.broadcast(value)
+  }
+
+  /**
+   * Resolves the active theme from the saved mode + per-scheme preferences
+   * and applies it: sets `data-theme`, stamps `data-color-scheme`, and
+   * broadcasts so all selectors re-sync. Used when the mode or the OS
+   * preference changes.
+   */
+  applyResolvedTheme() {
+    const resolved = this.resolveTheme()
+
+    if (!resolved) return
+
+    document.documentElement.setAttribute('data-theme', resolved.theme)
+
+    // Stamp the DISPLAYED theme's own scheme, not the slot name — the day
+    // slot can legitimately hold a dark theme. Prefer the scheme cached at
+    // save time (it works even when the theme's CSS isn't loaded); probe
+    // the stylesheet only as a fallback.
+    const cached = this.safeStorageGet(resolved.scheme === 'dark' ? 'savedDarkScheme' : 'savedLightScheme')
+
+    document.documentElement.setAttribute('data-color-scheme', cached || this.schemeForTheme(resolved.theme))
+
+    this.broadcast(resolved.theme)
+  }
+
+  /**
+   * Resolves which theme and scheme should be active from localStorage.
+   *
+   * @returns {?{theme: string, scheme: string}} The resolved theme and
+   *   scheme, or null when no mode is saved (no explicit choice yet)
+   */
+  resolveTheme() {
+    const mode = this.safeStorageGet('savedThemeMode')
+
+    if (!mode) return null
+
+    const scheme = mode === 'system'
+      ? (this.mediaQuery && this.mediaQuery.matches ? 'dark' : 'light')
+      : mode
+    const saved = this.safeStorageGet(scheme === 'dark' ? 'savedDarkTheme' : 'savedLightTheme')
+
+    // With no saved preference for the scheme, fall back to the built-in
+    // theme of the same name — DaisyUI always defines `light` and `dark`,
+    // and downstream apps restyle those names rather than renaming them.
+    return { theme: saved || scheme, scheme }
   }
 
   /**
@@ -149,15 +367,122 @@ export default class extends Controller {
    * @returns {?string} The current theme name, or null if none can be determined
    */
   getCurrentTheme() {
-    const savedTheme = this.safeStorageGet('savedTheme')
+    const resolved = this.resolveTheme()
 
-    if (savedTheme) {
-      return savedTheme
+    if (resolved) {
+      return resolved.theme
     }
 
     return document.documentElement.getAttribute('data-theme')
   }
 
+  /**
+   * Migrates the legacy single `savedTheme` key to the per-scheme model by
+   * re-applying it through `applyTheme`, which classifies the theme by its
+   * own `color-scheme`, saves it into the matching slot, pins the mode, and
+   * removes the legacy key.
+   */
+  migrateLegacyStorage() {
+    const legacy = this.safeStorageGet('savedTheme')
+
+    if (legacy && !this.safeStorageGet('savedThemeMode')) {
+      this.applyTheme(legacy)
+    }
+  }
+
+  /**
+   * Stamps `data-color-scheme` on the document element from the active
+   * theme's computed `color-scheme` when an explicit theme is applied but no
+   * scheme is stamped yet (e.g. a server-rendered `data-theme`).
+   */
+  stampScheme() {
+    const root = document.documentElement
+
+    if (root.getAttribute('data-theme') && !root.getAttribute('data-color-scheme')) {
+      root.setAttribute('data-color-scheme', this.computedScheme())
+    }
+  }
+
+  /**
+   * Stamps the saved theme mode on `<html>` as `data-theme-mode` so UI can
+   * reflect the active mode with pure CSS — e.g. the switcher dropdown's
+   * "Sync with system" checkmark uses a
+   * `[[data-theme-mode=system]_&]:visible` variant. Removes the attribute
+   * when no mode is saved.
+   *
+   * @param {?string} mode - `"light"`, `"dark"`, `"system"`, or null
+   */
+  stampMode(mode) {
+    if (mode) {
+      document.documentElement.setAttribute('data-theme-mode', mode)
+    } else {
+      document.documentElement.removeAttribute('data-theme-mode')
+    }
+  }
+
+  /**
+   * Reads the active theme's own scheme from the document element's computed
+   * `color-scheme` — every DaisyUI theme declares `color-scheme: light` or
+   * `color-scheme: dark`.
+   *
+   * @returns {string} `"dark"` or `"light"`
+   */
+  computedScheme() {
+    const value = getComputedStyle(document.documentElement).colorScheme || ''
+
+    return value.includes('dark') && !value.includes('light') ? 'dark' : 'light'
+  }
+
+  /**
+   * Classifies a specific theme by probing its own `color-scheme`
+   * declaration on a scratch element.
+   *
+   * Reading the ROOT's computed value at apply time is unreliable: DaisyUI
+   * theme blocks also match `:root:has(input.theme-controller:checked)`,
+   * which outranks `[data-theme]` in the cascade — so until the page's
+   * radios re-sync, the PREVIOUS theme's checked radio can misclassify the
+   * theme being applied (e.g. synthwave filed as a light preference). The
+   * probe carries only `data-theme`, so only the theme's own declaration
+   * can match it.
+   *
+   * @param {string} value - The theme name to classify
+   * @returns {string} `"dark"` or `"light"`
+   */
+  schemeForTheme(value) {
+    const probe = document.createElement('div')
+
+    probe.setAttribute('data-theme', value)
+    probe.style.display = 'none'
+    document.documentElement.appendChild(probe)
+
+    const scheme = getComputedStyle(probe).colorScheme || ''
+
+    probe.remove()
+
+    return scheme.includes('dark') && !scheme.includes('light') ? 'dark' : 'light'
+  }
+
+  /**
+   * Responds to OS color-scheme changes. Only relevant in `"system"` mode,
+   * where the active theme swaps between the saved light and dark themes.
+   */
+  mediaChanged() {
+    if (this.safeStorageGet('savedThemeMode') === 'system') {
+      this.applyResolvedTheme()
+    }
+  }
+
+  /**
+   * Notifies every theme controller on the page (including this one) that
+   * the theme changed so they can re-sync their inputs.
+   *
+   * @param {?string} value - The newly applied theme name, or null on clear
+   */
+  broadcast(value) {
+    const updateEvent = new CustomEvent('localstorage-update', { detail: { key: 'savedTheme', newValue: value } })
+    window.dispatchEvent(updateEvent)
+  }
+
   /**
    * Safely reads a value from localStorage. Access can throw in some
    * environments (e.g. Safari private browsing), so failures are swallowed