luxen-ui 0.18.3 → 0.19.0

package/dist/color-scheme.js

@@ -0,0 +1,203 @@
+/**
+ * Page-level light/dark state, shared by every control that shows or changes it.
+ *
+ * Deliberately not an element: the scheme is one value per document, and a
+ * document can hold several controls for it — a header button, a menu row, a
+ * settings page. Whichever one the user touches, all of them have to agree, so
+ * the state belongs to the page rather than to any of them.
+ *
+ * The model is the one argued in Lea Verou's *Dark mode toggles should be a
+ * two-state switch* (2026): three values — an explicit `light`, an explicit
+ * `dark`, or no preference at all — but only two ever shown. That falls out of
+ * two rules, both implemented here:
+ *
+ * 1. An override is stored **only when it differs from the OS preference**.
+ *    Choosing the scheme the OS already reports removes the override instead,
+ *    handing control back to the system. So a user on a dark OS who switches to
+ *    light and back is following the system again, not pinned to dark — and
+ *    "system" stays reachable without a third button.
+ * 2. The stored value is read **only when the user acts**. If the OS flips while
+ *    an explicit override exists, the override survives: the user asked for it,
+ *    and nothing they did says otherwise.
+ *
+ * SSR-safe: nothing here touches `window`, `document` or `localStorage` at
+ * module scope, and listeners are attached lazily on the first subscription.
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _ColorSchemeStore_instances, _ColorSchemeStore_session, _ColorSchemeStore_listeners, _ColorSchemeStore_media, _ColorSchemeStore_last, _ColorSchemeStore_lastOverridden, _ColorSchemeStore_onOsChange, _ColorSchemeStore_onStorageChange, _ColorSchemeStore_override_get, _ColorSchemeStore_applyToRoot, _ColorSchemeStore_notify, _ColorSchemeStore_bind, _ColorSchemeStore_unbind;
+/*
+ * Defaults live as module-level bindings, not class fields, so that
+ * `luxen-ui/vite-plugin` can bake a project's `luxen.config.mjs` values in at
+ * build time by rewriting these two initialisers — the same mechanism it uses
+ * for `_elementPrefix` / `_cssPrefix` in `registry.ts`. `configure()` stays the
+ * runtime path for anything the build cannot know.
+ */
+let _storageKey = 'luxen-color-scheme';
+let _apply = false;
+const DARK_QUERY = '(prefers-color-scheme: dark)';
+/** The OS-level preference. `light` when the query is unsupported. */
+function osScheme() {
+    return globalThis.matchMedia?.(DARK_QUERY).matches ? 'dark' : 'light';
+}
+function readStored(key) {
+    if (!key)
+        return null;
+    try {
+        const value = localStorage.getItem(key);
+        return value === 'light' || value === 'dark' ? value : null;
+    }
+    catch {
+        // Safari private mode, disabled storage, sandboxed iframe.
+        return null;
+    }
+}
+class ColorSchemeStore {
+    constructor() {
+        _ColorSchemeStore_instances.add(this);
+        /**
+         * In-memory copy of the override, used when persistence is off or when the
+         * browser refuses to write. Without it a blocked write would leave every
+         * control unable to move at all.
+         */
+        _ColorSchemeStore_session.set(this, null);
+        _ColorSchemeStore_listeners.set(this, new Set());
+        _ColorSchemeStore_media.set(this, null);
+        _ColorSchemeStore_last.set(this, null);
+        _ColorSchemeStore_lastOverridden.set(this, false);
+        _ColorSchemeStore_onOsChange.set(this, () => __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_notify).call(this));
+        _ColorSchemeStore_onStorageChange.set(this, (event) => {
+            // `key === null` means the whole store was cleared.
+            if (event.key !== null && event.key !== _storageKey)
+                return;
+            // Another tab is the authority now: drop this page's session copy so a
+            // release made over there is not undone by a stale local value.
+            if (_storageKey)
+                __classPrivateFieldSet(this, _ColorSchemeStore_session, null, "f");
+            __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_notify).call(this);
+        });
+    }
+    /** The scheme actually in effect: a stored override, else the OS preference. */
+    get current() {
+        return __classPrivateFieldGet(this, _ColorSchemeStore_instances, "a", _ColorSchemeStore_override_get) ?? osScheme();
+    }
+    /** Whether an override is in place, rather than the OS preference being followed. */
+    get overridden() {
+        return __classPrivateFieldGet(this, _ColorSchemeStore_instances, "a", _ColorSchemeStore_override_get) !== null;
+    }
+    /**
+     * Choose a scheme. Rule 1 lives here: the override is written only when it
+     * disagrees with the OS, and released when it agrees.
+     */
+    set(next) {
+        const release = next === osScheme();
+        if (_storageKey) {
+            try {
+                if (release)
+                    localStorage.removeItem(_storageKey);
+                else
+                    localStorage.setItem(_storageKey, next);
+                // Storage took it, so it is the single authority — drop any session copy
+                // left over from a period when it was unavailable.
+                __classPrivateFieldSet(this, _ColorSchemeStore_session, null, "f");
+                __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_applyToRoot).call(this);
+                __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_notify).call(this);
+                return;
+            }
+            catch {
+                // Refused — fall through to memory.
+            }
+        }
+        __classPrivateFieldSet(this, _ColorSchemeStore_session, release ? null : next, "f");
+        __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_applyToRoot).call(this);
+        __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_notify).call(this);
+    }
+    /** Flip to the other scheme. Returns the scheme now in effect. */
+    toggle() {
+        this.set(this.current === 'dark' ? 'light' : 'dark');
+        return this.current;
+    }
+    /**
+     * Observe the effective scheme. The listener is called **immediately with the
+     * current value**, then on a user change, on an OS change with no override in
+     * place, and on a change made in another tab. Returns an unsubscribe function;
+     * the last unsubscribe releases the listeners.
+     *
+     * The immediate call is deliberate. A subscriber's job is almost always to
+     * mirror the scheme somewhere — an `aria-pressed`, a `checked`, a class — and
+     * a change-only contract leaves that mirror wrong until the first change,
+     * which is a bug nobody sees until a screen reader hits it. Callers that only
+     * want transitions can ignore the first call.
+     */
+    subscribe(listener) {
+        __classPrivateFieldGet(this, _ColorSchemeStore_listeners, "f").add(listener);
+        __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_bind).call(this);
+        listener(this.current, this.overridden);
+        return () => {
+            __classPrivateFieldGet(this, _ColorSchemeStore_listeners, "f").delete(listener);
+            if (__classPrivateFieldGet(this, _ColorSchemeStore_listeners, "f").size === 0)
+                __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_unbind).call(this);
+        };
+    }
+    /** Set the storage key and whether the store writes `color-scheme` on `<html>`. */
+    configure(config) {
+        if (config.storageKey !== undefined)
+            _storageKey = config.storageKey;
+        if (config.apply !== undefined) {
+            const wasApplying = _apply === 'root';
+            _apply = config.apply;
+            // Leave no trace when application is switched off.
+            if (wasApplying && config.apply === false) {
+                globalThis.document?.documentElement.style.removeProperty('color-scheme');
+            }
+        }
+        __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_applyToRoot).call(this);
+        __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_notify).call(this);
+    }
+}
+_ColorSchemeStore_session = new WeakMap(), _ColorSchemeStore_listeners = new WeakMap(), _ColorSchemeStore_media = new WeakMap(), _ColorSchemeStore_last = new WeakMap(), _ColorSchemeStore_lastOverridden = new WeakMap(), _ColorSchemeStore_onOsChange = new WeakMap(), _ColorSchemeStore_onStorageChange = new WeakMap(), _ColorSchemeStore_instances = new WeakSet(), _ColorSchemeStore_override_get = function _ColorSchemeStore_override_get() {
+    return readStored(_storageKey) ?? __classPrivateFieldGet(this, _ColorSchemeStore_session, "f");
+}, _ColorSchemeStore_applyToRoot = function _ColorSchemeStore_applyToRoot() {
+    if (_apply !== 'root')
+        return;
+    const root = globalThis.document?.documentElement;
+    if (root)
+        root.style.colorScheme = __classPrivateFieldGet(this, _ColorSchemeStore_instances, "a", _ColorSchemeStore_override_get) ?? 'light dark';
+}, _ColorSchemeStore_notify = function _ColorSchemeStore_notify() {
+    const next = this.current;
+    const overridden = this.overridden;
+    // Both halves of the payload are compared, not just the scheme: releasing an
+    // override that already agreed with the OS leaves `current` untouched while
+    // `overridden` flips, and a subscriber mirroring it — a "following the
+    // system" badge, a tri-state settings control — would never hear about it.
+    if (next === __classPrivateFieldGet(this, _ColorSchemeStore_last, "f") && overridden === __classPrivateFieldGet(this, _ColorSchemeStore_lastOverridden, "f"))
+        return;
+    __classPrivateFieldSet(this, _ColorSchemeStore_last, next, "f");
+    __classPrivateFieldSet(this, _ColorSchemeStore_lastOverridden, overridden, "f");
+    for (const listener of __classPrivateFieldGet(this, _ColorSchemeStore_listeners, "f"))
+        listener(next, overridden);
+}, _ColorSchemeStore_bind = function _ColorSchemeStore_bind() {
+    if (__classPrivateFieldGet(this, _ColorSchemeStore_media, "f"))
+        return;
+    __classPrivateFieldSet(this, _ColorSchemeStore_media, globalThis.matchMedia?.(DARK_QUERY) ?? null, "f");
+    __classPrivateFieldGet(this, _ColorSchemeStore_media, "f")?.addEventListener('change', __classPrivateFieldGet(this, _ColorSchemeStore_onOsChange, "f"));
+    globalThis.addEventListener?.('storage', __classPrivateFieldGet(this, _ColorSchemeStore_onStorageChange, "f"));
+    __classPrivateFieldSet(this, _ColorSchemeStore_last, this.current, "f");
+    __classPrivateFieldSet(this, _ColorSchemeStore_lastOverridden, this.overridden, "f");
+    __classPrivateFieldGet(this, _ColorSchemeStore_instances, "m", _ColorSchemeStore_applyToRoot).call(this);
+}, _ColorSchemeStore_unbind = function _ColorSchemeStore_unbind() {
+    __classPrivateFieldGet(this, _ColorSchemeStore_media, "f")?.removeEventListener('change', __classPrivateFieldGet(this, _ColorSchemeStore_onOsChange, "f"));
+    __classPrivateFieldSet(this, _ColorSchemeStore_media, null, "f");
+    globalThis.removeEventListener?.('storage', __classPrivateFieldGet(this, _ColorSchemeStore_onStorageChange, "f"));
+};
+/** The document's light/dark state. One instance per page. */
+export const colorScheme = new ColorSchemeStore();

package/dist/config.d.ts

@@ -43,6 +43,24 @@ export interface LuxenEmitTypesConfig {
     /** Overwrite the file even when it exists. Default `false`. */
     force?: boolean;
 }
+/** Build-time defaults for the `luxen-ui/color-scheme` store. */
+export interface LuxenColorSchemeConfig {
+    /**
+     * `localStorage` key holding the light/dark override. Default
+     * `'luxen-color-scheme'`. Set to `''` to disable persistence entirely.
+     *
+     * Change it here and the before-first-paint snippet in your `<head>` has to
+     * read the same key — that snippet runs before any module and cannot be
+     * rewritten by the build.
+     */
+    storageKey?: string;
+    /**
+     * Have the store write `color-scheme` on `<html>` itself. Default `false`,
+     * because most applications already own a color-mode story; `'root'` is the
+     * batteries-included path for a plain page.
+     */
+    apply?: 'root' | false;
+}
 /**
  * Shape of `luxen.config.mjs`. Both the Vite plugin and the CLI read this
  * file; each tool ignores the fields that don't apply to it.
@@ -66,6 +84,11 @@ export interface LuxenConfig {
     cssImportPath?: string;
     /** npm specifier used in `import` examples in `references/`. Default `'luxen-ui'`. */
     jsImportPath?: string;
+    /**
+     * Defaults for `luxen-ui/color-scheme`, baked in at build time so a project
+     * never has to call `colorScheme.configure()` from its entry point.
+     */
+    colorScheme?: LuxenColorSchemeConfig;
     /**
      * Emit a prefix-aware `.d.ts` for `HTMLElementTagNameMap` (and optionally
      * Vue's `GlobalComponents`). Pass a path string for the default behaviour,

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/html/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mDAAmD;AACnD,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE1C,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC3C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAE1B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEhE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/html/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mDAAmD;AACnD,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE1C,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC3C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAE1B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB;;;OAGG;IACH,WAAW,CAAC,EAAE,sBAAsB,CAAC;IAGrC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,oBAAoB,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEhE"}

package/dist/custom-elements.json

@@ -2205,6 +2205,121 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/html/elements/color-scheme-icon/color-scheme-icon.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "ColorSchemeIcon",
+          "cssProperties": [
+            {
+              "description": "Width and height of the glyph.",
+              "name": "--size",
+              "default": "1em"
+            },
+            {
+              "description": "Glyph color.",
+              "name": "--color",
+              "default": "currentColor"
+            }
+          ],
+          "cssParts": [
+            {
+              "description": "The root `<svg>`, for overriding the morph's timing or tilt.",
+              "name": "base"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "scheme",
+              "type": {
+                "text": "ColorScheme | undefined"
+              },
+              "description": "Which glyph to show. Leave it unset and the icon follows the page's scheme\n(`colorScheme.current` — a stored override, else the OS preference), so it\nstays in step with every other control without wiring. Set it to pin the\nglyph, for a legend or a preview that must not move.",
+              "attribute": "scheme",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Accessible label. When set, the glyph becomes meaningful (`role=\"img\"`);\nwhen absent it is decorative and hidden from assistive tech — the right\ndefault inside a row or button that already carries the name.",
+              "attribute": "label"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "scheme",
+              "type": {
+                "text": "ColorScheme | undefined"
+              },
+              "description": "Which glyph to show. Leave it unset and the icon follows the page's scheme\n(`colorScheme.current` — a stored override, else the OS preference), so it\nstays in step with every other control without wiring. Set it to pin the\nglyph, for a legend or a preview that must not move.",
+              "fieldName": "scheme"
+            },
+            {
+              "name": "label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Accessible label. When set, the glyph becomes meaningful (`role=\"img\"`);\nwhen absent it is decorative and hidden from assistive tech — the right\ndefault inside a row or button that already carries the name.",
+              "fieldName": "label"
+            }
+          ],
+          "superclass": {
+            "name": "LuxenElement",
+            "module": "/src/html/shared/luxen-element.js"
+          },
+          "tagName": "l-color-scheme-icon",
+          "customElement": true,
+          "summary": "A sun that morphs into a moon. Purely presentational: it shows a\ncolor scheme, it does not choose or store one.\n\nThe two glyphs are a single shape — the disc grows, a mask slides in to carve\nthe crescent, and the rays retract in a ripple — so the change reads as one\nobject turning rather than two icons swapping. That is why this is authored\nSVG rather than an `<l-icon>`: an Iconify icon is opaque, and you cannot grow\none into another or animate a mask inside it.\n\nUse it wherever a scheme needs a glyph and the surrounding element is already\nthe control — a `menuitemcheckbox` row, a button, a legend. With no `scheme`\nit follows the page's scheme from `luxen-ui/color-scheme`, so it needs no\nwiring; set `scheme` to pin it.",
+          "examples": [
+            {
+              "title": "In a menu row, where the row is the control",
+              "language": "html",
+              "code": "```html\n<l-dropdown-item type=\"checkbox\" checked>\n<l-color-scheme-icon slot=\"prefix\" scheme=\"dark\"></l-color-scheme-icon>\nDark theme\n</l-dropdown-item>\n```"
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ColorScheme",
+          "declaration": {
+            "name": "ColorScheme",
+            "module": "src/html/elements/color-scheme-icon/color-scheme-icon.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ColorSchemeIcon",
+          "declaration": {
+            "name": "ColorSchemeIcon",
+            "module": "src/html/elements/color-scheme-icon/color-scheme-icon.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/html/elements/color-scheme-icon/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "module": "src/html/elements/color-scheme-icon/color-scheme-icon.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/html/elements/combobox/combobox.ts",
@@ -3706,7 +3821,7 @@
               "name": ""
             },
             {
-              "description": "Leading content (e.g. icon).",
+              "description": "Leading content (e.g. icon). A `type=\"checkbox\"` item ignores it unless `check-placement=\"end\"` frees the leading column.",
               "name": "prefix"
             },
             {
@@ -3783,6 +3898,17 @@
               "attribute": "submenu-open",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "checkPlacement",
+              "type": {
+                "text": "'start' | 'end'"
+              },
+              "default": "'start'",
+              "description": "Which side of a `type=\"checkbox\"` item carries the check mark. `start` (the\ndefault) puts it in the leading column, where it takes the place of any\n`prefix`. `end` moves it to the trailing edge, freeing that column so the\nitem can show its own icon alongside the state.",
+              "attribute": "check-placement",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "hasSubmenu",
@@ -3877,6 +4003,15 @@
               "default": "false",
               "description": "Whether this item's submenu is open. Managed by the parent `l-dropdown`.",
               "fieldName": "submenuOpen"
+            },
+            {
+              "name": "check-placement",
+              "type": {
+                "text": "'start' | 'end'"
+              },
+              "default": "'start'",
+              "description": "Which side of a `type=\"checkbox\"` item carries the check mark. `start` (the\ndefault) puts it in the leading column, where it takes the place of any\n`prefix`. `end` moves it to the trailing edge, freeing that column so the\nitem can show its own icon alongside the state.",
+              "fieldName": "checkPlacement"
             }
           ],
           "superclass": {

package/dist/elements/color-scheme-icon/color-scheme-icon.css

@@ -0,0 +1,98 @@
+/* Sun ↔ moon, morphed rather than swapped.
+
+   The two glyphs are one shape: a disc that grows, a mask circle that slides in
+   to bite a crescent out of it, and eight ray dots that collapse to nothing.
+   Nothing is added or removed between the states — which is the whole reason
+   this is authored SVG and not an `<l-icon>`. An Iconify icon is an opaque
+   document fetched from a set: you can cross-fade two of them, but you cannot
+   grow one into the other or animate a mask inside it.
+
+   Shadow DOM is doing real work here beyond encapsulation: the mask needs an
+   `id`, and ids are global in light DOM. Two icons on one page would collide and
+   the second would render through the first's mask. A shadow root scopes them
+   per instance for free. */
+
+:host {
+  --size: 1em;
+  --color: currentColor;
+
+  flex: none;
+  display: inline-flex;
+  inline-size: var(--size);
+  block-size: var(--size);
+  color: var(--color);
+}
+
+svg {
+  inline-size: 100%;
+  block-size: 100%;
+  fill: currentColor;
+  /* The tilt is what sells the transition: the glyph turns as it changes, so the
+     eye reads one object moving instead of two states cross-fading. */
+  rotate: 0deg;
+  transition: rotate 500ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+/* Every animated part scales about its own centre. `fill-box` is what makes
+   `center` mean the shape's own box rather than the whole viewBox. */
+.disc,
+.ray,
+.biter {
+  transform-box: fill-box;
+  transform-origin: center;
+}
+
+.disc {
+  /* Sun-sized. The dark state grows it to the full radius; the mask then takes
+     the bite that turns it into a crescent. */
+  scale: 0.56;
+  transition: scale 500ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.biter {
+  /* Parked far enough out that it clears the sun entirely. The clearance must be
+     computed against the disc's *authored* r=9, not the 5.04 the sun appears to
+     be: masking happens in the element's own user space, before its `scale` is
+     applied, so the mask sees the full-size circle. 16px on both axes puts the
+     centres 22.6 apart against a 9+11 sum — the earlier 13px looked ample and
+     still bit a notch out of the sun's upper right.
+     It slides in rather than fading, so the crescent is carved, never dissolved. */
+  translate: 16px -16px;
+  transition: translate 500ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.ray {
+  scale: 1;
+  transition: scale 300ms cubic-bezier(0.34, 1.56, 0.64, 1);
+  /* Staggered from the index each ray carries, so they retract and return as a
+     ripple around the disc instead of blinking in unison. */
+  transition-delay: calc(var(--i) * 18ms);
+}
+
+:host([data-scheme='dark']) {
+  svg {
+    rotate: 40deg;
+  }
+
+  .disc {
+    scale: 1;
+  }
+
+  .biter {
+    translate: 5px -5px;
+  }
+
+  .ray {
+    scale: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  svg,
+  .disc,
+  .biter,
+  .ray {
+    transition-duration: 0ms;
+    transition-delay: 0ms;
+  }
+}

package/dist/elements/color-scheme-icon/color-scheme-icon.d.ts

@@ -0,0 +1,55 @@
+import { type ColorScheme } from '../../color-scheme.js';
+import { LuxenElement } from '../../shared/luxen-element.js';
+export type { ColorScheme };
+/**
+ * @summary A sun that morphs into a moon. Purely presentational: it shows a
+ * color scheme, it does not choose or store one.
+ *
+ * The two glyphs are a single shape — the disc grows, a mask slides in to carve
+ * the crescent, and the rays retract in a ripple — so the change reads as one
+ * object turning rather than two icons swapping. That is why this is authored
+ * SVG rather than an `<l-icon>`: an Iconify icon is opaque, and you cannot grow
+ * one into another or animate a mask inside it.
+ *
+ * Use it wherever a scheme needs a glyph and the surrounding element is already
+ * the control — a `menuitemcheckbox` row, a button, a legend. With no `scheme`
+ * it follows the page's scheme from `luxen-ui/color-scheme`, so it needs no
+ * wiring; set `scheme` to pin it.
+ *
+ * @example In a menu row, where the row is the control
+ * ```html
+ * <l-dropdown-item type="checkbox" checked>
+ *   <l-color-scheme-icon slot="prefix" scheme="dark"></l-color-scheme-icon>
+ *   Dark theme
+ * </l-dropdown-item>
+ * ```
+ *
+ * @cssproperty [--size=1em] - Width and height of the glyph.
+ * @cssproperty [--color=currentColor] - Glyph color.
+ *
+ * @csspart base - The root `<svg>`, for overriding the morph's timing or tilt.
+ *
+ * @customElement l-color-scheme-icon
+ */
+export declare class ColorSchemeIcon extends LuxenElement {
+    static styles: import("lit").CSSResult[];
+    /**
+     * Which glyph to show. Leave it unset and the icon follows the page's scheme
+     * (`colorScheme.current` — a stored override, else the OS preference), so it
+     * stays in step with every other control without wiring. Set it to pin the
+     * glyph, for a legend or a preview that must not move.
+     */
+    scheme?: ColorScheme;
+    /**
+     * Accessible label. When set, the glyph becomes meaningful (`role="img"`);
+     * when absent it is decorative and hidden from assistive tech — the right
+     * default inside a row or button that already carries the name.
+     */
+    label?: string;
+    private _unsubscribe?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+//# sourceMappingURL=color-scheme-icon.d.ts.map

package/dist/elements/color-scheme-icon/color-scheme-icon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-scheme-icon.d.ts","sourceRoot":"","sources":["../../../src/html/elements/color-scheme-icon/color-scheme-icon.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAM7D,YAAY,EAAE,WAAW,EAAE,CAAC;AAY5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,OAAgB,MAAM,4BAAwB;IAE9C;;;;;OAKG;IAEH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;OAIG;IAEH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,OAAO,CAAC,YAAY,CAAC,CAAa;IAEzB,iBAAiB;IAOjB,oBAAoB;IAMpB,UAAU;IAsBV,MAAM;CA+ChB"}