ReviewOS

stacks/stx

useColorMode: an explicit darkClass:null / attribute:null in app.colorMode is dropped — pick() treats a boot-global null as unspecified

#1813
Closed glennmichael123 opened this 22 days ago · 1 comment
22 days ago

useColorMode's option resolution cannot express an explicit null coming from app.colorMode, which is the one path the pre-paint boot global exists to serve.

The code

packages/stx/src/signals.ts, inside useColorMode:

// Explicit-undefined checks rather than ||, so an explicit darkClass:null
// or attribute:null opts out instead of falling through to the default.
function pick(a, b, fallback) {
  if (a !== undefined) return a;
  if (b !== undefined && b !== null) return b;   // <-- rejects null
  return fallback;
}
var storageKey  = pick(options.storageKey,  boot && boot.storageKey,  'stx-color-mode');
var initialMode = pick(options.initialMode, boot && boot.initialMode, 'auto');
var darkClass   = pick(options.darkClass,   boot && boot.darkClass,   'dark');
var attribute   = pick(options.attribute,   boot && boot.attribute,   null);

a is the call-site option, b is window.__STX_COLOR_MODE__ (published from app.colorMode). The comment's promise — an explicit null opts out — holds for a and not for b. A null in the boot payload is treated as "unspecified" and falls through to fallback.

The asymmetry is easy to miss because it only bites where fallback is non-null:

  • attribute: null → fallback is null → looks like it works
  • darkClass: null → fallback is 'dark' → silently becomes 'dark'

Why it matters

The boot global exists precisely so a bare useColorMode() agrees with the app's config (the comment right above pick says so). But config is exactly the path that cannot say null. To opt out of the dark class you must repeat the option at every call site — which defeats the single-source arrangement the global was added for.

Repro

// config/ui.ts
app.colorMode = {
  storageKey: 'myapp_theme',
  attribute: 'data-theme',
  darkClass: null,          // "do not manage a class; my CSS selects on the attribute"
  initialMode: 'auto',
}
const cm = useColorMode()        // bare — the intended usage

Observed: the root element gets class="dark" added and removed as the mode changes. Expected: no class is touched; only data-theme changes.

Passing useColorMode({ darkClass: null }) at the call site works, confirming it is the b branch and not the config plumbing.

Verified in a real app: config/ui.ts sets darkClass: null, and the root element is still class-managed, because an auto-bundled useDark() calls through bare. The boot script itself serializes the value correctly ({"darkClass":null,…} is present in the emitted payload) — it is only pick that drops it.

Fix

The boot payload is generated by stx and always contains every key, so absence and explicit-null are already distinguishable — b !== undefined is sufficient:

function pick(a, b, fallback) {
  if (a !== undefined) return a;
  if (b !== undefined) return b;
  return fallback;
}

If a boot payload could legitimately carry null meaning "unset", the alternative is to omit those keys when serializing rather than emit null, so undefined remains the single "unspecified" signal on both branches.

Worth a test asserting darkClass: null in app.colorMode leaves classList untouched — that is the case that currently passes at the call site and fails through config.

  • #1794 / #1803 — the boot global and its ordering.
  • #1812 — the other pre-paint theme injector; both surfaced from the same audit.
22 days ago

Fixed in c49397762d, in both impls with parity tests.

Your diagnosis was exact, including why it hides: the asymmetry only bites where the fallback is non-null, so attribute: null looks like it works and darkClass: null silently becomes 'dark'.

One extra wrinkle worth recording. Simply relaxing pick isn't enough, because the call sites read boot && boot.storageKey — which yields undefined for an undefined boot but null for a null one, and a relaxed pick would then honour that as a deliberate opt-out. Reads now go through a helper that only consults the payload when it's actually an object.

The module-side composable had the same bug via ?? and is fixed too — its comment made the same promise ("?? not ||, so an explicit darkClass: null opts out") and, like the runtime's, it held for the call-site argument and not for the boot global.

Three parity tests per impl; both fail without the fix.

Sign in to comment on this issue.