@lilydesignsystem/web-components-theme-picker 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `<lily-theme-picker>` — Lily Design System HTML helper.
+ *
+ * See `./spec/index.md` for the canonical contract. This file implements
+ * the custom-element class but does NOT register it. The `index.ts`
+ * barrel registers it on import.
+ *
+ * The control is an icon button that opens a dropdown listbox
+ * (WAI-ARIA APG listbox pattern). It is not a native `<select>`.
+ */
+/**
+ * Default button icon: a bundled SVG (contrast/half-circle), not a
+ * Unicode character. Reversed 2026-09-16 from the font-dependent-glyph
+ * convention (was U+25D1 CIRCLE WITH RIGHT HALF BLACK, exported as
+ * `CIRCLE_WITH_RIGHT_HALF_BLACK` — removed, not renamed, since there is
+ * no longer a single swappable character value). A bundled outline SVG
+ * renders identically across every font stack and platform. `viewBox="0
+ * 0 16 16"`, stroke-based (`stroke-width="1.6"`, round caps/joins) to
+ * match the other four picker icons as one visual family. Override via
+ * `renderButtonContent()`, same as before.
+ */
+/** Change-event detail dispatched on every applied theme. */
+type ThemePickerChangeDetail = {
+    theme: string;
+};
+/** Mirrors the observed attributes / properties for typing convenience. */
+type ThemePickerProps = {
+    label: string;
+    themesUrl: string;
+    themes: string[];
+    value?: string;
+    defaultValue?: string;
+    storageKey?: string;
+    detectFromSystem?: boolean;
+    name?: string;
+    extension?: string;
+    themeLabels?: Record<string, string>;
+    target?: HTMLElement | null;
+    class?: string;
+};
+/**
+ * Resolve a theme slug to its display label: each hyphen-separated
+ * word title-cased, so a slug like
+ * "united-kingdom-national-health-service-england-for-patients"
+ * renders as "United Kingdom National Health Service England For
+ * Patients" rather than a half-capitalised hyphenated string.
+ *
+ * Mirrors `localeName` in locale-picker. The element's `labelFor`
+ * delegates here after consulting `theme-labels`, so there is exactly
+ * one implementation of the title-casing rule.
+ */
+declare function themeName(theme: string): string;
+/**
+ * Resolve the OS colour-scheme preference to a supported theme slug.
+ * Mirrors `matchNavigatorLanguage` in locale-picker.
+ *
+ * Returns `""` when the preferred scheme is not present in `themes`,
+ * or when `matchMedia` is unavailable — the SSR case, and also jsdom,
+ * which does not implement `matchMedia` either. The guard is required,
+ * not optional.
+ */
+declare function matchSystemTheme(themes: readonly string[]): string;
+/** Normalise the themes directory URL to end with exactly one `/`. */
+declare function normalizeThemesUrl(themesUrl: string): string;
+/** Construct the href for a given theme slug. */
+declare function themeHref(themesUrl: string, slug: string, extension: string): string;
+/** Stable per-instance id prefix; SSR-safe (no Math.random / Date.now). */
+declare function nextThemePickerId(): string;
+/** Custom-element class implementing `<lily-theme-picker>`. */
+declare class ThemePicker extends HTMLElement {
+    #private;
+    static get observedAttributes(): string[];
+    get label(): string;
+    set label(v: string);
+    get themesUrl(): string;
+    set themesUrl(v: string);
+    get themes(): string[];
+    set themes(v: string[]);
+    get value(): string;
+    set value(v: string);
+    get defaultValue(): string;
+    set defaultValue(v: string);
+    get storageKey(): string;
+    set storageKey(v: string);
+    /**
+     * Resolve `prefers-color-scheme` to a supported theme on first
+     * visit. Mirrors `detectFromNavigator` in locale-picker, including
+     * the boolean-attribute convention: absent → false, present →
+     * true, present and equal to "false" → false.
+     */
+    get detectFromSystem(): boolean;
+    set detectFromSystem(v: boolean);
+    get name(): string;
+    set name(v: string);
+    get extension(): string;
+    set extension(v: string);
+    get themeLabels(): Record<string, string>;
+    set themeLabels(v: Record<string, string>);
+    get target(): HTMLElement | null;
+    set target(v: HTMLElement | null);
+    /** Is the listbox open? Read-only; use `openList()` / `closeList()`. */
+    get open(): boolean;
+    /** id of the rendered `<ul role="listbox">`. */
+    get listId(): string;
+    /** id of the rendered option at `index`. */
+    optionId(index: number): string;
+    /**
+     * Build the content of the button. The default is a bundled SVG icon
+     * (contrast/half-circle) wrapped in `aria-hidden="true"` so the
+     * accessible name comes from the button's `aria-label` alone.
+     *
+     * This is the HTML-helper equivalent of the Svelte/React/Vue
+     * `children` snippet: it replaces the icon inside the button, and
+     * has `this.value`, `this.open`, and `this.labelFor(...)` available.
+     * Subclasses may override it. Whatever it returns is placed inside
+     * the button; the button's own aria wiring is not the subclass's to
+     * change. See `docs/custom-rendering.md`.
+     */
+    renderButtonContent(): Node;
+    /** Resolve a slug to its display label. Public for subclasses. */
+    labelFor(theme: string): string;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    disconnectedCallback(): void;
+    /** Open the listbox. `startIndex` overrides the active option. */
+    openList(startIndex?: number): void;
+    /** Close the listbox. Returns focus to the button unless `refocus` is false. */
+    closeList(refocus?: boolean): void;
+}
+
+export { ThemePicker, type ThemePickerChangeDetail, type ThemePickerProps, matchSystemTheme, nextThemePickerId, normalizeThemesUrl, themeHref, themeName };

package/dist/index.js

@@ -0,0 +1,567 @@
+// lily-design-system-web-components-theme-picker/theme-picker.ts
+var SVG_NS = "http://www.w3.org/2000/svg";
+function themeName(theme) {
+  return theme.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function matchSystemTheme(themes) {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "";
+  }
+  const wanted = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  return themes.includes(wanted) ? wanted : "";
+}
+function normalizeThemesUrl(themesUrl) {
+  return themesUrl.endsWith("/") ? themesUrl : themesUrl + "/";
+}
+function themeHref(themesUrl, slug, extension) {
+  return normalizeThemesUrl(themesUrl) + slug + extension;
+}
+var uid = 0;
+function nextThemePickerId() {
+  uid += 1;
+  return `theme-picker-${uid}`;
+}
+var ThemePicker = class extends HTMLElement {
+  static get observedAttributes() {
+    return [
+      "label",
+      "themes-url",
+      "themes",
+      "value",
+      "default-value",
+      "storage-key",
+      "detect-from-system",
+      "name",
+      "extension",
+      "theme-labels",
+      "class"
+    ];
+  }
+  // Backing storage for properties.
+  #themes = [];
+  #themeLabels = {};
+  #target = null;
+  #initialised = false;
+  // Rendered-DOM references. Null until #render() has run.
+  #rootEl = null;
+  #inputEl = null;
+  #buttonEl = null;
+  #listEl = null;
+  #optionEls = [];
+  // Listbox state.
+  #open = false;
+  #activeIndex = -1;
+  // Stable ids for the button/listbox aria wiring.
+  #baseId = nextThemePickerId();
+  // Typeahead buffer: APG listbox behaviour. Reset after a pause.
+  #typeahead = "";
+  #typeaheadTimer;
+  #onDocumentClick = (event) => {
+    if (!this.#open) return;
+    if (!event.composedPath().includes(this)) this.closeList(false);
+  };
+  // ---- Property accessors ----
+  get label() {
+    return this.getAttribute("label") ?? "";
+  }
+  set label(v) {
+    this.setAttribute("label", v);
+  }
+  get themesUrl() {
+    return this.getAttribute("themes-url") ?? "";
+  }
+  set themesUrl(v) {
+    this.setAttribute("themes-url", v);
+  }
+  get themes() {
+    return [...this.#themes];
+  }
+  set themes(v) {
+    this.#themes = Array.isArray(v) ? v.slice() : [];
+    const csv = this.#themes.join(",");
+    if (this.getAttribute("themes") !== csv) {
+      this.setAttribute("themes", csv);
+      return;
+    }
+    this.#render();
+  }
+  get value() {
+    return this.getAttribute("value") ?? "";
+  }
+  set value(v) {
+    if (v) this.setAttribute("value", v);
+    else this.removeAttribute("value");
+  }
+  get defaultValue() {
+    return this.getAttribute("default-value") ?? "";
+  }
+  set defaultValue(v) {
+    if (v) this.setAttribute("default-value", v);
+    else this.removeAttribute("default-value");
+  }
+  get storageKey() {
+    return this.getAttribute("storage-key") ?? "";
+  }
+  set storageKey(v) {
+    if (v) this.setAttribute("storage-key", v);
+    else this.removeAttribute("storage-key");
+  }
+  /**
+   * Resolve `prefers-color-scheme` to a supported theme on first
+   * visit. Mirrors `detectFromNavigator` in locale-picker, including
+   * the boolean-attribute convention: absent → false, present →
+   * true, present and equal to "false" → false.
+   */
+  get detectFromSystem() {
+    const v = this.getAttribute("detect-from-system");
+    return v !== null && v !== "false";
+  }
+  set detectFromSystem(v) {
+    if (v) this.setAttribute("detect-from-system", "");
+    else this.removeAttribute("detect-from-system");
+  }
+  get name() {
+    return this.getAttribute("name") ?? "theme";
+  }
+  set name(v) {
+    if (v) this.setAttribute("name", v);
+    else this.removeAttribute("name");
+  }
+  get extension() {
+    return this.getAttribute("extension") ?? ".css";
+  }
+  set extension(v) {
+    if (v) this.setAttribute("extension", v);
+    else this.removeAttribute("extension");
+  }
+  get themeLabels() {
+    return { ...this.#themeLabels };
+  }
+  set themeLabels(v) {
+    this.#themeLabels = v && typeof v === "object" ? { ...v } : {};
+    const json = JSON.stringify(this.#themeLabels);
+    if (this.getAttribute("theme-labels") !== json) {
+      this.setAttribute("theme-labels", json);
+      return;
+    }
+    this.#render();
+  }
+  get target() {
+    return this.#target;
+  }
+  set target(v) {
+    this.#target = v ?? null;
+  }
+  /** Is the listbox open? Read-only; use `openList()` / `closeList()`. */
+  get open() {
+    return this.#open;
+  }
+  /** id of the rendered `<ul role="listbox">`. */
+  get listId() {
+    return `${this.#baseId}-list`;
+  }
+  /** id of the rendered option at `index`. */
+  optionId(index) {
+    return `${this.#baseId}-option-${index}`;
+  }
+  // ---- Public, overridable rendering hook ----
+  /**
+   * Build the content of the button. The default is a bundled SVG icon
+   * (contrast/half-circle) wrapped in `aria-hidden="true"` so the
+   * accessible name comes from the button's `aria-label` alone.
+   *
+   * This is the HTML-helper equivalent of the Svelte/React/Vue
+   * `children` snippet: it replaces the icon inside the button, and
+   * has `this.value`, `this.open`, and `this.labelFor(...)` available.
+   * Subclasses may override it. Whatever it returns is placed inside
+   * the button; the button's own aria wiring is not the subclass's to
+   * change. See `docs/custom-rendering.md`.
+   */
+  renderButtonContent() {
+    const svg = document.createElementNS(SVG_NS, "svg");
+    svg.setAttribute("class", "theme-picker-icon");
+    svg.setAttribute("viewBox", "0 0 16 16");
+    svg.setAttribute("width", "1.05rem");
+    svg.setAttribute("height", "1.05rem");
+    svg.setAttribute("aria-hidden", "true");
+    svg.setAttribute("fill", "none");
+    svg.setAttribute("stroke", "currentColor");
+    svg.setAttribute("stroke-width", "1.6");
+    svg.setAttribute("stroke-linecap", "round");
+    svg.setAttribute("stroke-linejoin", "round");
+    const circle = document.createElementNS(SVG_NS, "circle");
+    circle.setAttribute("cx", "8");
+    circle.setAttribute("cy", "8");
+    circle.setAttribute("r", "6");
+    svg.appendChild(circle);
+    const path = document.createElementNS(SVG_NS, "path");
+    path.setAttribute("d", "M8 2a6 6 0 0 1 0 12z");
+    path.setAttribute("fill", "currentColor");
+    path.setAttribute("stroke", "none");
+    svg.appendChild(path);
+    return svg;
+  }
+  /** Resolve a slug to its display label. Public for subclasses. */
+  labelFor(theme) {
+    if (theme in this.#themeLabels) return this.#themeLabels[theme];
+    return themeName(theme);
+  }
+  // ---- Lifecycle ----
+  connectedCallback() {
+    const themesAttr = this.getAttribute("themes");
+    if (themesAttr !== null && this.#themes.length === 0) {
+      this.#themes = parseCsv(themesAttr);
+    }
+    const labelsAttr = this.getAttribute("theme-labels");
+    if (labelsAttr !== null && Object.keys(this.#themeLabels).length === 0) {
+      this.#themeLabels = parseJsonObject(labelsAttr);
+    }
+    if (!this.#initialised) {
+      this.#initialised = true;
+      this.#resolveInitialValue();
+    }
+    this.#render();
+    document.addEventListener("click", this.#onDocumentClick);
+    if (this.value) this.#applyTheme(this.value);
+  }
+  attributeChangedCallback(name, _old, value) {
+    switch (name) {
+      case "themes":
+        this.#themes = value === null ? [] : parseCsv(value);
+        this.#render();
+        break;
+      case "theme-labels":
+        this.#themeLabels = value === null ? {} : parseJsonObject(value);
+        this.#render();
+        break;
+      case "value":
+        this.#syncState();
+        if (this.isConnected && value) this.#applyTheme(value);
+        break;
+      case "label":
+      case "name":
+      case "class":
+        this.#render();
+        break;
+      // themes-url / default-value / storage-key / extension don't
+      // need a re-render; they affect the next apply.
+      default:
+        break;
+    }
+  }
+  disconnectedCallback() {
+    document.removeEventListener("click", this.#onDocumentClick);
+    clearTimeout(this.#typeaheadTimer);
+    this.#appliedValue = "";
+    const sameName = document.querySelectorAll(
+      `theme-picker[name="${this.name}"]`
+    );
+    if (sameName.length === 0) {
+      const link = document.head.querySelector(
+        `link[data-lily-theme-picker="${this.name}"]`
+      );
+      link?.remove();
+    }
+  }
+  // ---- Behaviour ----
+  #resolveInitialValue() {
+    let initial = this.value;
+    if (!initial && this.storageKey) {
+      try {
+        initial = localStorage.getItem(this.storageKey) ?? "";
+      } catch {
+      }
+    }
+    if (!initial && this.detectFromSystem) {
+      initial = matchSystemTheme(this.#themes);
+    }
+    if (!initial) {
+      initial = this.defaultValue || (this.#themes.includes("light") ? "light" : this.#themes[0]) || "";
+    }
+    if (initial && initial !== this.value) {
+      this.setAttribute("value", initial);
+    }
+  }
+  #getManagedLink() {
+    const selector = `link[data-lily-theme-picker="${this.name}"]`;
+    let link = document.head.querySelector(selector);
+    if (!link) {
+      link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.setAttribute("data-lily-theme-picker", this.name);
+      document.head.appendChild(link);
+    }
+    return link;
+  }
+  // The theme the DOM currently carries. Applying is idempotent: a
+  // theme already applied is a no-op. `attributeChangedCallback` fires
+  // on every `setAttribute("value", …)`, unchanged value included, so
+  // without this a consumer whose `themechange` listener mirrors the value
+  // back onto the element re-enters apply forever.
+  #appliedValue = "";
+  #applyTheme(slug) {
+    if (typeof document === "undefined" || !slug) return;
+    if (slug === this.#appliedValue) return;
+    this.#appliedValue = slug;
+    this.#getManagedLink().href = themeHref(
+      this.themesUrl,
+      slug,
+      this.extension
+    );
+    (this.#target ?? document.documentElement).setAttribute("data-theme", slug);
+    if (this.storageKey) {
+      try {
+        localStorage.setItem(this.storageKey, slug);
+      } catch {
+      }
+    }
+    this.dispatchEvent(
+      new CustomEvent("themechange", {
+        detail: { theme: slug },
+        bubbles: true,
+        composed: true
+      })
+    );
+  }
+  // ---- Open / close ----
+  /** Open the listbox. `startIndex` overrides the active option. */
+  openList(startIndex) {
+    const selected = this.#themes.indexOf(this.value);
+    this.#activeIndex = this.#themes.length === 0 ? -1 : startIndex ?? (selected >= 0 ? selected : 0);
+    this.#open = true;
+    this.#syncState();
+    this.#listEl?.focus({ preventScroll: true });
+    this.#scrollActiveIntoView();
+  }
+  /** Close the listbox. Returns focus to the button unless `refocus` is false. */
+  closeList(refocus = true) {
+    if (!this.#open) return;
+    this.#open = false;
+    this.#activeIndex = -1;
+    this.#syncState();
+    if (refocus) this.#buttonEl?.focus({ preventScroll: true });
+  }
+  #choose(index) {
+    const slug = this.#themes[index];
+    if (slug) this.value = slug;
+    this.closeList();
+  }
+  #scrollActiveIntoView() {
+    if (this.#activeIndex < 0) return;
+    this.#optionEls[this.#activeIndex]?.scrollIntoView?.({ block: "nearest" });
+  }
+  #moveActive(delta) {
+    if (this.#themes.length === 0) return;
+    this.#activeIndex = Math.min(
+      Math.max(this.#activeIndex + delta, 0),
+      this.#themes.length - 1
+    );
+    this.#syncState();
+    this.#scrollActiveIntoView();
+  }
+  #setActive(index) {
+    this.#activeIndex = index;
+    this.#syncState();
+    this.#scrollActiveIntoView();
+  }
+  #runTypeahead(char) {
+    const lower = char.toLowerCase();
+    const sameCharRun = this.#typeahead === "" || [...this.#typeahead].every((c) => c === lower);
+    this.#typeahead += lower;
+    clearTimeout(this.#typeaheadTimer);
+    this.#typeaheadTimer = setTimeout(() => {
+      this.#typeahead = "";
+    }, 500);
+    const query = sameCharRun ? lower : this.#typeahead;
+    const anchor = this.#activeIndex < 0 ? 0 : this.#activeIndex;
+    const start = sameCharRun ? anchor + 1 : anchor;
+    for (let n = 0; n < this.#themes.length; n++) {
+      const i = (start + n) % this.#themes.length;
+      if (this.labelFor(this.#themes[i]).toLowerCase().startsWith(query)) {
+        this.#setActive(i);
+        return;
+      }
+    }
+  }
+  #onButtonKeydown = (event) => {
+    switch (event.key) {
+      case "ArrowDown":
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        this.openList();
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.openList(this.#themes.length - 1);
+        break;
+    }
+  };
+  #onListKeydown = (event) => {
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        this.#moveActive(1);
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.#moveActive(-1);
+        break;
+      case "Home":
+        event.preventDefault();
+        this.#setActive(0);
+        break;
+      case "End":
+        event.preventDefault();
+        this.#setActive(this.#themes.length - 1);
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        if (this.#activeIndex >= 0) this.#choose(this.#activeIndex);
+        break;
+      case "Escape":
+        event.preventDefault();
+        this.closeList();
+        break;
+      case "PageUp":
+        event.preventDefault();
+        this.#moveActive(-10);
+        break;
+      case "PageDown":
+        event.preventDefault();
+        this.#moveActive(10);
+        break;
+      case "Tab":
+        this.#buttonEl?.focus?.({ preventScroll: true });
+        this.closeList(false);
+        break;
+      default:
+        if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
+          this.#runTypeahead(event.key);
+        }
+    }
+  };
+  #onRootFocusOut = (event) => {
+    const next = event.relatedTarget;
+    if (next && this.#rootEl?.contains(next)) return;
+    queueMicrotask(() => {
+      const active = document.activeElement;
+      if (active && this.#rootEl?.contains(active)) return;
+      this.closeList(false);
+    });
+  };
+  // ---- Rendering ----
+  /**
+   * Update every state-carrying attribute without rebuilding the DOM:
+   * `aria-expanded`, `hidden`, `aria-activedescendant`, per-option
+   * `aria-selected` / `data-active`, and the hidden input's value.
+   */
+  #syncState() {
+    if (!this.#rootEl) return;
+    const value = this.value;
+    if (this.#inputEl) this.#inputEl.value = value;
+    if (this.#buttonEl) {
+      this.#buttonEl.setAttribute("aria-expanded", String(this.#open));
+      this.#buttonEl.replaceChildren(this.renderButtonContent());
+    }
+    if (this.#listEl) {
+      if (this.#open) this.#listEl.removeAttribute("hidden");
+      else this.#listEl.setAttribute("hidden", "");
+      if (this.#open && this.#activeIndex >= 0) {
+        this.#listEl.setAttribute(
+          "aria-activedescendant",
+          this.optionId(this.#activeIndex)
+        );
+      } else {
+        this.#listEl.removeAttribute("aria-activedescendant");
+      }
+    }
+    this.#optionEls.forEach((option, i) => {
+      option.setAttribute("aria-selected", String(this.#themes[i] === value));
+      if (i === this.#activeIndex) option.setAttribute("data-active", "");
+      else option.removeAttribute("data-active");
+    });
+  }
+  #render() {
+    if (!this.isConnected) return;
+    this.#open = false;
+    this.#activeIndex = -1;
+    const extraClass = this.getAttribute("class") ?? "";
+    const root = document.createElement("div");
+    root.className = `theme-picker ${extraClass}`.trim();
+    root.addEventListener("focusout", this.#onRootFocusOut);
+    const input = document.createElement("input");
+    input.type = "hidden";
+    input.name = this.name;
+    input.value = this.value;
+    root.appendChild(input);
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "theme-picker-button";
+    button.setAttribute("aria-label", this.label);
+    button.setAttribute("aria-haspopup", "listbox");
+    button.setAttribute("aria-expanded", "false");
+    button.setAttribute("aria-controls", this.listId);
+    button.appendChild(this.renderButtonContent());
+    button.addEventListener("click", () => {
+      if (this.#open) this.closeList();
+      else this.openList();
+    });
+    button.addEventListener("keydown", this.#onButtonKeydown);
+    root.appendChild(button);
+    const list = document.createElement("ul");
+    list.className = "theme-picker-list";
+    list.id = this.listId;
+    list.setAttribute("role", "listbox");
+    list.setAttribute("aria-label", this.label);
+    list.setAttribute("tabindex", "-1");
+    list.setAttribute("hidden", "");
+    list.addEventListener("keydown", this.#onListKeydown);
+    const optionEls = [];
+    this.#themes.forEach((theme, i) => {
+      const option = document.createElement("li");
+      option.className = "theme-picker-option";
+      option.id = this.optionId(i);
+      option.setAttribute("role", "option");
+      option.setAttribute("aria-selected", String(theme === this.value));
+      option.textContent = this.labelFor(theme);
+      option.addEventListener("click", () => this.#choose(i));
+      list.appendChild(option);
+      optionEls.push(option);
+    });
+    root.appendChild(list);
+    this.#rootEl = root;
+    this.#inputEl = input;
+    this.#buttonEl = button;
+    this.#listEl = list;
+    this.#optionEls = optionEls;
+    this.replaceChildren(root);
+  }
+};
+function parseCsv(s) {
+  return s.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+}
+function parseJsonObject(s) {
+  try {
+    const v = JSON.parse(s);
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      return v;
+    }
+  } catch {
+  }
+  return {};
+}
+
+// lily-design-system-web-components-theme-picker/index.ts
+if (typeof customElements !== "undefined" && !customElements.get("lily-theme-picker")) {
+  customElements.define("lily-theme-picker", ThemePicker);
+}
+export {
+  ThemePicker,
+  matchSystemTheme,
+  nextThemePickerId,
+  normalizeThemesUrl,
+  themeHref,
+  themeName
+};

package/index.md

@@ -0,0 +1,654 @@
+# `<lily-theme-picker>` (HTML helper)
+
+A reusable, headless vanilla HTML/JS theme picker that **loads themes
+dynamically at runtime** from a developer-specified directory,
+packaged as a **web component (custom element)**.
+
+The control is an **icon button that opens a dropdown listbox**
+(WAI-ARIA APG listbox pattern) — not a native `<select>`.
+
+The single source of truth is [spec/index.md](./spec/index.md). This file is the
+comprehensive user guide. For topic deep-dives see
+[docs/](./docs/) and for working code see [examples/](./examples/).
+
+## Table of contents
+
+- [Why this exists](#why-this-exists)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Rendered markup](#rendered-markup)
+- [Styling is required](#styling-is-required)
+- [How it works](#how-it-works)
+- [Keyboard](#keyboard)
+- [Default theme](#default-theme)
+- [Attributes](#attributes)
+- [JS properties](#js-properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Custom button rendering](#custom-button-rendering)
+- [Persistence](#persistence)
+- [Accessibility](#accessibility)
+- [SSR and static-site generation](#ssr-and-static-site-generation)
+- [Preloading for zero-flicker switching](#preloading-for-zero-flicker-switching)
+- [Multiple selects in one page](#multiple-selects-in-one-page)
+- [Recipes](#recipes)
+- [Troubleshooting](#troubleshooting)
+- [Testing](#testing)
+
+## Why this exists
+
+Most theme pickers couple selection, persistence, and styling into one
+opinionated widget. This one splits the contract cleanly:
+
+- **Authors** drop theme CSS files (e.g. `light.css`, `dark.css`) into
+  a directory served by the app.
+- **This element** owns selection, dynamic loading, persistence, and
+  accessibility.
+- **Consumers** own every visual decision via the `theme-picker`
+  class hooks — including the dropdown's positioning.
+
+The result is a small reusable widget that works in any HTML host
+(static HTML, Eleventy, Astro, Hugo, plain Vite, any framework that
+emits HTML) and against any theme catalog — Lily™'s 45 reference
+themes (DaisyUI-inspired, NHS-aligned, and public-sector / vendor
+reference themes), or your own bespoke set.
+
+The element is a direct port of the Svelte canonical
+`@lilydesignsystem/svelte-theme-picker`. APIs and behaviour match;
+only the framework idioms differ. The change-notification path uses
+a bubbling `CustomEvent` instead of Svelte's prop callback.
+
+## Install
+
+The directory is published as a folder-style import. Consumers either
+copy it into their project or wire it as a workspace dependency. The
+only runtime dependency is the browser DOM.
+
+```ts
+// One side-effect import registers <lily-theme-picker> globally:
+import "./lily-design-system-web-components-theme-picker";
+
+// Or grab the class + helpers + types:
+import {
+  ThemePicker,
+  normalizeThemesUrl,
+  themeHref,
+  nextThemePickerId,
+  type ThemePickerProps,
+  type ThemePickerChangeDetail,
+} from "./lily-design-system-web-components-theme-picker";
+```
+
+The barrel guards registration with
+`customElements.get("lily-theme-picker")` so re-imports and SSR contexts
+don't throw.
+
+## Quick start
+
+1. Drop theme CSS files into a directory served by your app, e.g.
+   `public/assets/themes/light.css`,
+   `public/assets/themes/dark.css`. Each theme scopes its tokens to
+   `:root[data-theme="<slug>"]` (the convention every Lily theme
+   uses).
+2. Place the custom element in your markup. On `connectedCallback`
+   it renders an icon button plus a hidden dropdown listbox holding
+   one option per theme.
+3. **Add the positioning CSS.** The package ships no CSS, so the
+   dropdown renders in flow until you position it. This is not
+   optional — see [Styling is required](#styling-is-required).
+
+```html
+<script type="module" src="/dist/theme-picker.js"></script>
+
+<style>
+  /* The minimum: make the dropdown float over the page. */
+  .theme-picker {
+    position: relative;
+  }
+  .theme-picker-list {
+    position: absolute;
+    inset-block-start: 100%;
+    inset-inline-start: 0;
+    z-index: 10;
+  }
+  .theme-picker-option[data-active] {
+    background: #eee;
+  }
+  .theme-picker-option[aria-selected="true"] {
+    font-weight: 600;
+  }
+</style>
+
+<lily-theme-picker
+  label="Theme"
+  themes-url="/assets/themes/"
+  themes="light,dark,abyss"
+  storage-key="lily-theme"
+></lily-theme-picker>
+
+<p class="theme-picker-status" aria-live="polite">Active theme: Light</p>
+
+<script type="module">
+  await customElements.whenDefined("theme-picker");
+
+  const select = document.querySelector("theme-picker");
+  const status = document.querySelector(".theme-picker-status");
+
+  select.addEventListener("themechange", (e) => {
+    status.textContent = `Active theme: ${select.labelFor(e.detail.theme)}`;
+  });
+</script>
+```
+
+**The status line is part of the pattern, not an optional extra.**
+The closed control is an icon button — it shows an icon and nothing
+else — so this line is the only place the current selection is
+displayed and announced. `aria-live="polite"` speaks on each change
+and stays silent on first paint, which is why the initial text is
+authored in the markup rather than written by JS on startup. Making
+it visible (rather than `sr-only`) serves sighted and
+cognitive-accessibility users too. `labelFor()` is a public method
+on the element, so the line picks up `theme-labels` overrides and
+translations for free. See
+[`docs/accessibility.md`](./docs/accessibility.md) for the full
+rationale and the visually-hidden variant.
+
+When the user selects `dark`, the element:
+
+- swaps a managed `<link rel="stylesheet">` in `<head>` to
+  `/assets/themes/dark.css`,
+- sets `data-theme="dark"` on `<html>`,
+- writes `"dark"` to `localStorage["lily-theme"]`,
+- dispatches `new CustomEvent("themechange", { detail: { theme: "dark" }, bubbles: true, composed: true })`.
+
+## Rendered markup
+
+The element renders this into its light DOM:
+
+```html
+<lily-theme-picker
+  label="Theme"
+  themes-url="/assets/themes/"
+  themes="light,dark,abyss"
+>
+  <div class="theme-picker">
+    <input type="hidden" name="theme" value="light" />
+    <button
+      type="button"
+      class="theme-picker-button"
+      aria-label="Theme"
+      aria-haspopup="listbox"
+      aria-expanded="false"
+      aria-controls="theme-picker-1-list"
+    >
+      <svg class="theme-picker-icon" viewBox="0 0 16 16" width="1.05rem" height="1.05rem" aria-hidden="true">…</svg>
+    </button>
+    <ul
+      class="theme-picker-list"
+      id="theme-picker-1-list"
+      role="listbox"
+      aria-label="Theme"
+      tabindex="-1"
+      hidden
+    >
+      <li
+        class="theme-picker-option"
+        id="theme-picker-1-option-0"
+        role="option"
+        aria-selected="true"
+        data-active
+      >
+        Light
+      </li>
+      <li
+        class="theme-picker-option"
+        id="theme-picker-1-option-1"
+        role="option"
+        aria-selected="false"
+      >
+        Dark
+      </li>
+      <li
+        class="theme-picker-option"
+        id="theme-picker-1-option-2"
+        role="option"
+        aria-selected="false"
+      >
+        Abyss
+      </li>
+    </ul>
+  </div>
+</lily-theme-picker>
+```
+
+Points worth knowing:
+
+- The **icon** is a bundled SVG (half-filled circle), not a Unicode
+  character — reversed 2026-09-16. It is `aria-hidden="true"`, so the
+  accessible name comes from the button's `aria-label` alone.
+- The **hidden `<input>`** preserves form participation and carries
+  `name` — a listbox is not a form control.
+- **`aria-activedescendant`** appears on the `<ul>` only while open,
+  pointing at the active option's id.
+- **`data-active` is not `aria-selected`.** `data-active` marks the
+  keyboard-highlighted option (where `Enter` would land);
+  `aria-selected` marks the chosen one. They often differ while the
+  list is open, and consumer CSS should style them differently.
+- **ids** come from a module-level counter, so they are unique per
+  instance, stable across runs, and SSR-safe.
+
+Read the selection from `el.value` or the `themechange` detail. The
+active theme is not visible anywhere while the list is closed, which
+is why the [Quick start](#quick-start) pairs the element with a
+status region by default; see [Accessibility](#accessibility).
+
+## Styling is required
+
+The package ships **no CSS at all**, and that includes positioning.
+The element renders the dropdown as an ordinary `<ul>` and toggles
+its `hidden` attribute; it sets no `position`, no `z-index`, and no
+offsets.
+
+So out of the box the list appears _below the button in normal
+flow_, pushing subsequent content down when it opens. That is
+expected, not a bug. The minimum fix:
+
+```css
+.theme-picker {
+  position: relative;
+}
+
+.theme-picker-list {
+  position: absolute;
+  inset-block-start: 100%;
+  inset-inline-start: 0;
+  z-index: 10;
+}
+```
+
+One trap to know about: if you set any `display` value on
+`.theme-picker-list`, it overrides the user-agent
+`[hidden] { display: none }` rule and the closed list stays visible.
+Re-assert `.theme-picker-list[hidden] { display: none }` after your
+rule, or scope yours with `:not([hidden])`.
+
+Full hook list, state selectors, and a complete worked example:
+[`docs/styling.md`](./docs/styling.md).
+
+## How it works
+
+On every theme change the select performs four steps, in order:
+
+1. **Locate or create** a managed
+   `<link rel="stylesheet" data-lily-theme-picker="{name}">` in
+   `document.head`.
+2. **Swap the href** to `${themesUrl}${slug}${extension}` so the new
+   theme's CSS is fetched and applied. The previous theme's CSS is
+   unloaded when the href changes.
+3. **Set `data-theme="{slug}"`** on the resolved target element
+   (defaults to `document.documentElement`). Theme CSS files match
+   this attribute via their `:root[data-theme="…"]` selector.
+4. **Persist + notify**: if `storage-key` is set, write to
+   `localStorage` (silently swallowing private-mode errors); then
+   dispatch `themechange` with the slug in `event.detail.theme`.
+
+All four steps are SSR-safe — the element only mutates the DOM inside
+`connectedCallback` and `attributeChangedCallback`, which never run
+in Node.
+
+## Keyboard
+
+The control implements the WAI-ARIA APG listbox pattern in
+JavaScript; none of this comes from the platform.
+
+On the button:
+
+| Key               | Action                                                          |
+| ----------------- | --------------------------------------------------------------- |
+| `ArrowDown`       | Open the list with the selected option active (else the first). |
+| `Enter` / `Space` | Same as `ArrowDown`.                                            |
+| `ArrowUp`         | Open the list with the **last** option active.                  |
+
+Opening moves focus to the `<ul>`. On the list:
+
+| Key                     | Action                                                        |
+| ----------------------- | ------------------------------------------------------------- |
+| `ArrowDown` / `ArrowUp` | Move the active option; clamps at both ends (no wrapping).    |
+| `Home` / `End`          | Jump to the first / last option.                              |
+| `Enter` / `Space`       | Select the active option, apply, close, refocus the button.   |
+| `Escape`                | Close and refocus the button without changing the theme.      |
+| `PageUp` / `PageDown`   | Move the active option by ten; clamps at both ends.           |
+| `Tab`                   | Move focus to the button, then close — so the default Tab proceeds from the picker's position. |
+| printable character     | Typeahead over the option labels; buffer resets after 500 ms. A repeated character cycles through its matches; differing characters refine from the active option. |
+
+Focus sits on the `<ul>` while open, never on an `<li>` — the
+highlighted option is conveyed by `aria-activedescendant`. That is
+why consumer CSS must style `.theme-picker-option[data-active]`
+rather than `:focus`.
+
+Clicking outside the control, or moving focus out of it, closes the
+list.
+
+## Default theme
+
+The default theme is `"light"` whenever `"light"` appears in your
+`themes` list. The full resolution order on first
+`connectedCallback` is:
+
+1. `value` attribute (if non-empty)
+2. `localStorage[storage-key]` (if `storage-key` is set and readable)
+3. `matchSystemTheme(themes)` (if `detect-from-system` is set) —
+   `prefers-color-scheme` mapped to the `"dark"` / `"light"` slug, or
+   `""` when that slug is absent or `matchMedia` is unavailable
+4. `default-value` attribute
+5. `"light"` (if present in `themes`)
+6. `themes[0]`
+7. `""` — nothing is applied; the select waits for user interaction
+
+The control never displays the word `"default"`. Option labels
+default to the title-cased slug, per hyphen-separated word
+(`"light"` → `"Light"`, `"high-contrast"` → `"High Contrast"`);
+override with `theme-labels` (JSON-encoded object).
+
+## Attributes
+
+The complete table is in [spec/index.md §4.1](./spec/index.md#41-observed-attributes).
+Highlights:
+
+| Attribute            | Type          | Required | Notes                                                                                                        |
+| -------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
+| `label`              | string        | yes      | `aria-label` on the button and the listbox. The control is icon-only, so this is the entire accessible name. |
+| `themes-url`         | string        | yes      | Trailing `/` is auto-added.                                                                                  |
+| `themes`             | string (CSV)  | yes      | Available slugs, e.g. `"light,dark"`.                                                                        |
+| `value`              | string        | no       | Currently selected slug.                                                                                     |
+| `default-value`      | string        | no       | Initial when nothing else applies.                                                                           |
+| `storage-key`        | string        | no       | `localStorage` persistence.                                                                                  |
+| `detect-from-system` | boolean attr  | no       | Resolve `prefers-color-scheme` on first visit. Mirrors locale-picker's `detect-from-navigator`.             |
+| `name`               | string        | no       | Hidden `<input>` `name` and managed-`<link>` discriminator; defaults to `"theme"`.                           |
+| `extension`          | string        | no       | Defaults to `".css"`.                                                                                        |
+| `theme-labels`       | string (JSON) | no       | `{ "light": "Bright" }` overrides.                                                                           |
+| `class`              | string        | no       | Extra class on the rendered root `<div>`.                                                                    |
+
+There is no `placeholder` attribute; it was removed along with the
+native `<select>`.
+
+See [docs/attributes-reference.md](./docs/attributes-reference.md) for
+a field-by-field reference.
+
+## JS properties
+
+Every observed attribute mirrors a JS property of the same name (in
+camelCase):
+
+| Property              | Type                     | Notes                                               |
+| --------------------- | ------------------------ | --------------------------------------------------- |
+| `el.label`            | `string`                 | round-trips with `label` attribute                  |
+| `el.themesUrl`        | `string`                 | round-trips with `themes-url`                       |
+| `el.themes`           | `string[]`               | CSV-encoded in the `themes` attribute               |
+| `el.value`            | `string`                 | round-trips with `value`                            |
+| `el.defaultValue`     | `string`                 | round-trips with `default-value`                    |
+| `el.storageKey`       | `string`                 | round-trips with `storage-key`                      |
+| `el.detectFromSystem` | `boolean`                | round-trips with `detect-from-system` (presence)    |
+| `el.name`             | `string`                 | round-trips with `name`                             |
+| `el.extension`        | `string`                 | round-trips with `extension`                        |
+| `el.themeLabels`      | `Record<string, string>` | JSON-encoded in `theme-labels`                      |
+| `el.target`           | `HTMLElement \| null`    | no attribute form (HTMLElement is not serialisable) |
+
+Array / object properties accept the native form:
+
+```ts
+const select = document.querySelector("theme-picker") as ThemePicker;
+select.themes = ["light", "dark", "abyss"];
+select.themeLabels = { light: "Bright", dark: "Midnight" };
+```
+
+## Methods
+
+Beyond the attribute mirrors, the element exposes the listbox state
+and a small imperative API:
+
+| Member                     | Type      | Notes                                                                               |
+| -------------------------- | --------- | ----------------------------------------------------------------------------------- |
+| `el.open`                  | `boolean` | Read-only. Whether the listbox is open.                                             |
+| `el.listId`                | `string`  | Read-only. id of the rendered `<ul role="listbox">`.                                |
+| `el.optionId(index)`       | `string`  | id of the rendered option at `index`.                                               |
+| `el.openList(startIndex?)` | `void`    | Open the list; `startIndex` overrides the active option. Moves focus to the `<ul>`. |
+| `el.closeList(refocus?)`   | `void`    | Close the list. Returns focus to the button unless `refocus` is `false`.            |
+| `el.labelFor(slug)`        | `string`  | Display label for a slug — applies `theme-labels`, else title-cases.                |
+| `el.renderButtonContent()` | `Node`    | Overridable hook building the button's content.                                     |
+
+```ts
+const select = document.querySelector<ThemePicker>("theme-picker")!;
+
+select.openList(); // open on the selected option
+select.closeList(false); // close without moving focus
+select.labelFor("light"); // → "Light"
+```
+
+## Events
+
+| Event         | Detail              | Bubbles | Composed | When                                  |
+| ------------- | ------------------- | ------- | -------- | ------------------------------------- |
+| `themechange` | `{ theme: string }` | yes     | yes      | After the select applies a new theme. |
+
+```ts
+const select = document.querySelector("theme-picker")!;
+select.addEventListener("themechange", (e) => {
+  const { theme } = (e as CustomEvent<{ theme: string }>).detail;
+  console.log("theme is now", theme);
+});
+```
+
+Because the event bubbles, event delegation works too:
+
+```ts
+document.body.addEventListener("themechange", handleThemeChange);
+```
+
+## Custom button rendering
+
+The Web Components helpers don't expose Vue scoped slots or Svelte snippets —
+`<slot>` is Shadow DOM only, and these helpers commit to light DOM.
+The equivalent of the other frameworks' `children` is an overridable
+method, **`renderButtonContent()`**. Whatever `Node` it returns
+replaces the default icon inside the button:
+
+```ts
+import { ThemePicker } from "./lily-design-system-web-components-theme-picker";
+
+class MyThemePicker extends ThemePicker {
+  renderButtonContent(): Node {
+    const span = document.createElement("span");
+    span.textContent = this.labelFor(this.value); // ChildArgs.value + labelFor
+    span.dataset.open = String(this.open); // ChildArgs.open
+    return span;
+  }
+}
+
+customElements.define("my-theme-picker", MyThemePicker);
+```
+
+`this.value`, `this.open`, and `this.labelFor(...)` stand in for the
+`ChildArgs` the other frameworks pass. The base class still builds
+the button and the listbox, so all the aria wiring and the whole
+keyboard contract keep working — **this is the recommended
+customisation path**, and the only one that cannot break
+accessibility.
+
+A subclass that needs a fundamentally different structure has to
+post-process after `super.connectedCallback()` (`#render()` is a
+private field and cannot be overridden), and in doing so takes over
+the entire accessibility contract.
+
+Working example: [`examples/09-custom-rendering.html`](./examples/09-custom-rendering.html).
+Topic guide, both tiers, and the invariants:
+[`docs/custom-rendering.md`](./docs/custom-rendering.md).
+
+## Persistence
+
+Pass a `storage-key` to persist the active slug to `localStorage`.
+On a fresh mount the select reads back the stored slug as part of
+the initial-value resolution (§ Default theme).
+
+Errors writing to or reading from `localStorage` (private mode,
+quota, disabled storage) are silently swallowed — the select
+continues to work in-memory.
+
+If you need cookie-based persistence (so SSR can read the theme
+before first paint), see [`docs/ssr.md`](./docs/ssr.md) and the
+[`examples/eleventy-cookie/`](./examples/eleventy-cookie/) recipe.
+
+## Accessibility
+
+- The control implements the WAI-ARIA APG listbox pattern: a
+  `<button aria-haspopup="listbox">` paired with a
+  `<ul role="listbox">`, with `aria-label={label}` on both.
+- The full keyboard contract is implemented in JS — see
+  [Keyboard](#keyboard).
+- The active state is exposed via `aria-selected`, `data-theme` on
+  the root, the host's `value`, and the hidden input. No colour-only
+  meaning is required.
+- WCAG 2.2 AAA is the target; visible focus styling is the
+  consumer's CSS responsibility — style
+  `.theme-picker-list:focus-visible` too, since focus moves to the
+  `<ul>` while the list is open.
+
+**Two tradeoffs to know about**, both documented in full in
+[`docs/accessibility.md`](./docs/accessibility.md):
+
+1. **Icon-only control.** `aria-label` is the entire accessible
+   name. A vague `label` makes the control unusable to
+   screen-reader users, and the absence of a visible label means the
+   control fails WCAG 2.5.3 Label in Name unless you add one.
+2. **A custom listbox is weaker than a native `<select>`.** The old
+   native control got combobox semantics, platform keyboard
+   behaviour, mobile OS pickers, and typeahead for free, all
+   battle-tested in every AT. An APG listbox with
+   `aria-activedescendant` has more variable support across screen
+   readers and mobile browsers, and no native mobile picker.
+
+(The old platform-dependent-glyph-rendering tradeoff no longer
+applies: the default icon is a bundled SVG, not a Unicode character
+— reversed 2026-09-16. Override `renderButtonContent()` with your own
+SVG when a different appearance is needed.)
+
+Because the closed button shows only an icon, the active theme is
+not visible or announced anywhere unless you surface it. The status
+region shown in [Quick start](#quick-start) is the **default
+pattern** — ship it unless you have a specific reason not to.
+
+Topic guide: [`docs/accessibility.md`](./docs/accessibility.md).
+
+## SSR and static-site generation
+
+The element compiles cleanly under static-site generators (Eleventy,
+Astro, Hugo, Jekyll). On the server no lifecycle hook runs and no
+DOM is touched; the SSG emits the literal `<lily-theme-picker>` tag, and
+the browser upgrades it after the JS loads.
+
+For zero-flicker static rendering, resolve the theme at build time
+(or via cookie for dynamic SSR) and pre-render two things:
+
+- `<html data-theme="…">` in the document shell
+- a matching `<link rel="stylesheet">` for the chosen theme
+
+Then pass the resolved value as the `value` attribute on the host so
+the select doesn't re-resolve from storage and clobber the inlined
+attribute.
+
+See [`docs/ssr.md`](./docs/ssr.md) and
+[`examples/eleventy-cookie/`](./examples/eleventy-cookie/).
+
+## Preloading for zero-flicker switching
+
+By default the select swaps one `<link>` href, so the active theme
+is fetched on demand. To switch instantly between themes, preload
+them all yourself:
+
+```html
+<link rel="stylesheet" href="/assets/themes/light.css" />
+<link rel="stylesheet" href="/assets/themes/dark.css" />
+<link rel="stylesheet" href="/assets/themes/abyss.css" />
+```
+
+The select still mutates `data-theme`, and since every theme's CSS
+is scoped to `:root[data-theme="…"]`, the active rules switch
+instantly with the attribute change — no network round-trip.
+
+Topic guide: [`docs/preloading.md`](./docs/preloading.md). Working
+example: [`examples/05-preloaded.html`](./examples/05-preloaded.html).
+
+## Multiple selects in one page
+
+Pass a distinct `name` attribute to each control. The `name` is used
+as both the hidden `<input>`'s `name` and the discriminator on the
+managed `<link>` element (`data-lily-theme-picker="{name}"`). Option
+and list ids are unique per instance automatically.
+
+Example: [`examples/03-multiple-selects.html`](./examples/03-multiple-selects.html).
+
+## Recipes
+
+Quick cookbook in [`docs/recipes.md`](./docs/recipes.md):
+
+- Following the OS colour scheme via `prefers-color-scheme`.
+- Reading a theme cookie in Eleventy before render.
+- Migrating from a `localStorage`-only select to a cookie-backed one.
+- Positioning the dropdown, and putting the theme name on the button.
+- Opening / closing the list from your own code.
+- Loading themes from a CDN.
+
+## Troubleshooting
+
+See [`docs/troubleshooting.md`](./docs/troubleshooting.md). Common
+pitfalls:
+
+- **The dropdown pushes the page down.** The package ships no CSS.
+  Give the root `position: relative` and the list
+  `position: absolute`.
+- **The dropdown never hides.** A `display` rule on
+  `.theme-picker-list` beats the UA's `[hidden] { display: none }`.
+  Re-assert it, or scope your rule with `:not([hidden])`.
+- **CSS does not switch.** Check that each theme file scopes its
+  rules to `:root[data-theme="<slug>"]` (not `:root` alone).
+- **404 on theme href.** Check the file is served from `themes-url`
+  and uses the configured `extension` (defaults to `.css`).
+- **Flash of default theme.** Pass a build-time-resolved `value`
+  attribute and inline `<html data-theme>` in the SSG output.
+- **Theme does not persist.** Confirm `storage-key` is set and that
+  `localStorage` is available (not blocked by private mode).
+
+## Testing
+
+```sh
+pnpm test
+```
+
+Runs the vitest + jsdom suite that exercises every numbered
+acceptance criterion in
+[spec/index.md §7](./spec/index.md#7-testing-acceptance-criteria).
+
+## Files in this directory
+
+| File                    | Purpose                                          |
+| ----------------------- | ------------------------------------------------ |
+| `spec/index.md`         | Single source of truth — API, behaviour, tests.  |
+| `AGENTS.md`             | Fast-index pointer; loads the AGENTS bundle.     |
+| `AGENTS/`               | Topic-by-topic agent files.                      |
+| `CLAUDE.md`             | `@AGENTS.md`.                                    |
+| `theme-picker.ts`      | The custom-element class.                        |
+| `theme-picker.test.ts` | vitest suite covering every spec §7 item.        |
+| `index.ts`              | Barrel + side-effectful `customElements.define`. |
+| `index.md`              | This file.                                       |
+| `docs/`                 | Deep-dive topic guides.                          |
+| `examples/`             | Runnable `.html` files.                          |
+| `CHANGELOG.md`          | Version history.                                 |
+
+## License
+
+MIT or Apache-2.0 or GPL-2.0 or GPL-3.0 or BSD-3-Clause. Contact
+joel@joelparkerhenderson.com for other terms.
+
+---
+
+Lily™ and Lily Design System™ are trademarks.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@lilydesignsystem/web-components-theme-picker",
+  "version": "0.1.0",
+  "engines": {
+    "node": "=26"
+  },
+  "description": "Lily Design System - HTML custom element theme picker",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "index.md",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "cd .. && npm run build"
+  },
+  "keywords": [
+    "lily",
+    "design",
+    "system",
+    "html",
+    "theme",
+    "picker"
+  ],
+  "author": "Joel Parker Henderson <joel@joelparkerhenderson.com>",
+  "license": "MIT OR Apache-2.0 OR GPL-2.0-only OR GPL-3.0-only OR BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LilyDesignSystem/lily-design-system-web-components-helpers.git",
+    "directory": "lily-design-system-web-components-theme-picker"
+  },
+  "homepage": "https://lilydesignsystem.com/",
+  "bugs": {
+    "url": "https://github.com/LilyDesignSystem/lily-design-system/issues"
+  }
+}