Theme Script

# Brok UI: Theme Script (`theme-script`)

A head tag pair that applies the stored light, dark or system theme before the first paint: a color-scheme meta and a blocking same-origin script, so dark mode never flashes light and a strict script-src 'self' policy needs no nonce.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add theme-script
```

## Usage

```blade
{{-- In an app the theme script goes in <head>, before @vite. Here it sits next
     to the theme switcher it pairs with: choose Dark, reload the frame, and the
     first paint is already dark. --}}
<div class="flex flex-col items-start gap-4">
    <x-ui.theme-script />
    <x-ui.theme-switcher />
    <p class="max-w-sm text-sm text-muted-foreground">{{ __('Choose Dark, then reload: the stored theme is applied before the page paints, so there is no light flash.') }}</p>
</div>
```

## Props

- `src` (string|null, default `null`) — URL of the boot script; null uses asset('vendor/brok/theme-boot.js'), where ui:add installs it. Set it when the app serves public assets from a CDN or a versioned path.
- `nonce` (string|null, default `null`) — Not needed for script-src 'self'. When the app's policy uses nonces, pass it (for example :nonce="Vite::cspNonce()") and it is set on the script tag. Other attributes are forwarded to the script tag as well.

## Use when

- Use to document, inspect, and apply design-system decisions consistently across teams and AI tooling.
- The app offers dark mode (theme-switcher) and a full page load must not paint light first.
- The Content-Security-Policy allows only same-origin scripts (script-src 'self'), so an inline boot script is not an option.

## Avoid when

- Do not present token-level controls to end users who only need product functionality.
- The app has no dark mode, or forces one theme with a fixed class on <html>; then there is nothing to restore before paint.
- The theme comes only from theme-customizer, which keeps its own storage key; this script reads the theme-switcher key.
- The page runs no script at all, for example an OAuth sign-in or consent page under default-src 'none': set data-theme="system" on <html> instead, and the tokens follow prefers-color-scheme without a script (see the theming docs). To keep the stored choice there, allow this script with a nonce (:nonce plus script-src 'nonce-…').

## Anti-patterns

- Exposing implementation tokens as product settings

## Rules

- Use the `<brok:theme-script>` tag (or `<x-ui.theme-script>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/theme-script
- Registry JSON (files, props, contract): https://brokui.dev/r/open/theme-script.json

/**
 * Theme boot: applies the stored light / dark / system choice before the first
 * paint, so a dark page never flashes light on a full page load.
 *
 * A classic, blocking script (no module, no Alpine) that `<x-ui.theme-script>`
 * loads from `public/vendor/brok/theme-boot.js` in `<head>`, before the
 * stylesheet. It is a file, not an inline script, so it runs under a strict
 * Content-Security-Policy (`script-src 'self'`, no nonce, no 'unsafe-inline').
 *
 * The rule is the same as theme-switcher.js (the two files cannot import each
 * other, and ThemeScriptTest fails when they drift):
 *   - localStorage key "theme" holds 'light', 'dark' or 'system';
 *   - 'system', a missing or an unknown value follows
 *     matchMedia('(prefers-color-scheme: dark)');
 *   - `.dark` is toggled on <html> and `style.colorScheme` is set to match.
 *
 * All localStorage access is wrapped in try/catch, so blocked storage (private
 * mode, file://) falls back to the system preference instead of throwing.
 *
 * Note: this file is plain JS served by the registry — no Blade syntax allowed.
 */
(function () {
    let value = null;

    try {
        const v = window.localStorage.getItem('theme');
        value = v === 'light' || v === 'dark' || v === 'system' ? v : null;
    } catch (e) {
        value = null;
    }

    const mode = value ?? 'system';
    const prefersDark = typeof window.matchMedia === 'function'
        && window.matchMedia('(prefers-color-scheme: dark)').matches;
    const dark = mode === 'dark' || (mode === 'system' && prefersDark);
    const root = document.documentElement;

    root.classList.toggle('dark', dark);
    root.style.colorScheme = dark ? 'dark' : 'light';
})();