@apliteni/apliteni-ui 0.51.0 → 0.53.0

package/README.md

@@ -170,6 +170,9 @@ See Storybook's **Button / Busy Transition** for the live vanilla example.
 
 ## Theming
 
+React pages can use [ThemeToggle and its pre-paint script](react/README.md#themetoggle)
+to save dark, light or auto choices. Auto resolves to dark or light on the root.
+
 Theme is a `data-theme="dark|light"` attribute on `<html>`; accent is an orthogonal
 `data-accent` on top:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -441,6 +441,40 @@ function SaveButton() {
 <Toast><SaveButton /></Toast>
 ```
 
+## ThemeToggle
+
+ThemeToggle uses the existing topbar button. It shows the current theme and the
+action that will happen next. Add `labelled` to display the current theme beside
+the button.
+
+```tsx
+import { ThemeToggle, THEME_INIT_SCRIPT } from '@apliteni/apliteni-ui/react';
+
+<ThemeToggle />
+<ThemeToggle labelled />
+```
+
+### Contract
+
+| Surface | Contract |
+| --- | --- |
+| Props | `ThemeToggleProps` has one optional prop: `labelled?: boolean`, default `false`. There are no controlled-value or callback props. |
+| Choices | Each press cycles `dark` → `light` → `auto` → `dark`. Auto shows a monitor icon and keeps its own label even when the resolved theme changes. |
+| Storage | Explicit choices use localStorage key `apliteni-strategy-theme`. Existing `dark` and `light` values work without migration. `auto`, missing values and unknown values follow the OS; mounting does not rewrite storage. |
+| DOM | On mount, the control sets `data-theme-choice` to dark, light or auto and `data-theme` to dark or light on `html`. Auto resolves to light when `(prefers-color-scheme: light)` matches, otherwise dark. An existing `data-theme-choice` takes precedence on mount; unknown attribute values become auto. |
+| Updates | Mounted controls follow OS changes in auto mode and storage changes from other tabs. A press dispatches a plain `apliteni-theme-choice` event on `window`, with no payload; read the root attributes for the choice and resolved theme. OS and storage updates do not dispatch that event. |
+| Storage failure | The button still works and retains its choice on the current page. Persistence across reloads requires working storage. |
+| Before paint | `THEME_INIT_SCRIPT: string` reads the same stored values and sets only `data-theme`. It neither writes storage nor subscribes to OS changes; mounted controls handle later updates. Server rendering starts with the Auto label and does not set root attributes. |
+
+Place `THEME_INIT_SCRIPT` in an inline `<head>` script before styles load so the theme
+is set before the first paint. Allow this script through your Content Security Policy
+with a nonce or hash. The component applies the preference when React mounts, but it
+cannot change an earlier paint.
+
+```tsx
+<script nonce={nonce} dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
+```
+
 ## AppShell
 
 AppShell includes the kit’s rail and top band. Pass the current router pathname so the longest matching section path becomes active. Spread the props from `renderLink` onto your router link. The rail’s folded state is saved in a shared cookie. On phones, the bar shows up to four sections. If there are more, it shows three sections and a More sheet. Provide no more than one primary page action. The palette defaults to section links; pass `palette` to add custom commands. Import both the kit CSS and React CSS.

package/react/dist/index.css

@@ -593,3 +593,10 @@
     display: none;
   }
 }
+
+/* src/ThemeToggle.css */
+.ui-theme-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-3);
+}

package/react/dist/index.d.ts

@@ -597,7 +597,15 @@ type EmptyStateProps = {
 };
 declare function EmptyState({ variant, title, sub, icon, art, actions }: EmptyStateProps): react.JSX.Element;
 
+/** Place in a head script before styles load to apply the theme before first paint. */
+declare const THEME_INIT_SCRIPT = "(()=>{let t;try{t=localStorage.getItem('apliteni-strategy-theme')}catch{}document.documentElement.setAttribute('data-theme',t==='dark'||t==='light'?t:window.matchMedia?.('(prefers-color-scheme: light)').matches?'light':'dark')})()";
+type ThemeToggleProps = {
+    /** Show the current theme beside the icon. */
+    labelled?: boolean;
+};
+declare function ThemeToggle({ labelled }: ThemeToggleProps): react.JSX.Element;
+
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, RowIdentity, type RowIdentityProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, Timeline, type TimelineEvent, type TimelineProps, Toast, type ToastNotice, type ToastProps, sortTableRows, useToast };
+export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, RowIdentity, type RowIdentityProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineProps, Toast, type ToastNotice, type ToastProps, sortTableRows, useToast };

package/react/dist/index.js

@@ -51,7 +51,7 @@ var cx = (...a) => a.filter(Boolean).join(" ");
 var Button = forwardRef(function Button2({
   variant = "secondary",
   size = "md",
-  icon: icon5,
+  icon: icon6,
   iconRight,
   iconOnly,
   block,
@@ -107,7 +107,7 @@ var Button = forwardRef(function Button2({
     iconOnly && "ui-btn--icon"
   );
   const labelled = rest["aria-label"] != null || rest["aria-labelledby"] != null;
-  const fallback = typeof children === "string" && children.trim() ? children.trim() : icon5;
+  const fallback = typeof children === "string" && children.trim() ? children.trim() : icon6;
   const named = iconOnly && !labelled && fallback ? { "aria-label": fallback, title: rest.title ?? fallback } : {};
   return /* @__PURE__ */ jsxs(
     "button",
@@ -141,7 +141,7 @@ var Button = forwardRef(function Button2({
         if (!blockKey(event)) onKeyUp?.(event);
       },
       children: [
-        icon5 && /* @__PURE__ */ jsx2(Icon, { name: icon5 }),
+        icon6 && /* @__PURE__ */ jsx2(Icon, { name: icon6 }),
         !iconOnly && renderedChildren != null && /* @__PURE__ */ jsx2("span", { className: "ui-btn__label-slot", children: /* @__PURE__ */ jsx2("span", { className: "ui-btn__label", ref: labelRef, children: renderedChildren }) }),
         iconRight && /* @__PURE__ */ jsx2(Icon, { name: iconRight }),
         busy && /* @__PURE__ */ jsxs("span", { className: "ui-btn__dots", "aria-hidden": "true", children: [
@@ -177,9 +177,9 @@ function Card({ title, sub, level = 2, children }) {
 // src/primitives/Callout.tsx
 import { calloutIcons, icon as kitIcon } from "@apliteni/apliteni-ui";
 import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
-function Callout({ variant, icon: icon5 = calloutIcons[variant ?? "neutral"], children, actions }) {
+function Callout({ variant, icon: icon6 = calloutIcons[variant ?? "neutral"], children, actions }) {
   return /* @__PURE__ */ jsxs3("div", { className: `ui-callout${variant && variant !== "neutral" ? ` ui-callout--${variant}` : ""}`, role: variant === "danger" ? "alert" : void 0, children: [
-    /* @__PURE__ */ jsx5("span", { className: "ui-callout__icon", dangerouslySetInnerHTML: { __html: kitIcon(icon5) } }),
+    /* @__PURE__ */ jsx5("span", { className: "ui-callout__icon", dangerouslySetInnerHTML: { __html: kitIcon(icon6) } }),
     /* @__PURE__ */ jsxs3("div", { className: "ui-callout__body", children: [
       children,
       actions != null && /* @__PURE__ */ jsx5("div", { className: "ui-toolbar ui-callout__actions", children: actions })
@@ -1213,12 +1213,12 @@ function Denied({
   title = "You don\u2019t have access",
   sub,
   need,
-  icon: icon5 = "lock",
+  icon: icon6 = "lock",
   className,
   children
 }) {
   return /* @__PURE__ */ jsxs11("div", { className: cx4("ui-denied", className), children: [
-    /* @__PURE__ */ jsx13("div", { className: "ui-denied__seal", children: /* @__PURE__ */ jsx13(Icon, { name: icon5 }) }),
+    /* @__PURE__ */ jsx13("div", { className: "ui-denied__seal", children: /* @__PURE__ */ jsx13(Icon, { name: icon6 }) }),
     /* @__PURE__ */ jsx13("div", { className: "ui-denied__title", children: title }),
     sub && /* @__PURE__ */ jsx13("div", { className: "ui-denied__sub", children: sub }),
     need && /* @__PURE__ */ jsxs11("div", { className: "ui-denied__need", children: [
@@ -2321,11 +2321,11 @@ var cases = {
   "not-found": { title: "We can't find that page", sub: "Check the address or return to the home page.", icon: "folder" },
   "not-yet-built": { title: "This ships later", sub: "This screen is not available yet. Check back later.", icon: "clock" }
 };
-function EmptyState({ variant = "first-run", title, sub, icon: icon5, art, actions }) {
+function EmptyState({ variant = "first-run", title, sub, icon: icon6, art, actions }) {
   const preset = cases[variant];
   const heading = title ?? preset.title;
   const guidance = sub ?? preset.sub;
-  const glyph = icon5 ?? preset.icon;
+  const glyph = icon6 ?? preset.icon;
   return /* @__PURE__ */ jsxs22("div", { className: "ui-empty", children: [
     art ? typeof art === "string" ? /* @__PURE__ */ jsx26("div", { className: "ui-empty__art", dangerouslySetInnerHTML: { __html: /<svg/.test(art) ? art : illo(art) } }) : /* @__PURE__ */ jsx26("div", { className: "ui-empty__art", "aria-hidden": "true", children: art }) : glyph ? /* @__PURE__ */ jsx26("div", { className: "ui-empty__icon", dangerouslySetInnerHTML: { __html: kitIcon2(glyph) } }) : null,
     heading && /* @__PURE__ */ jsx26("div", { className: "ui-empty__title", children: heading }),
@@ -2334,6 +2334,77 @@ function EmptyState({ variant = "first-run", title, sub, icon: icon5, art, actio
   ] });
 }
 
+// src/ThemeToggle.tsx
+import { useSyncExternalStore } from "react";
+import { icon as icon5 } from "@apliteni/apliteni-ui";
+import { jsx as jsx27, jsxs as jsxs23 } from "react/jsx-runtime";
+var STORAGE_KEY = "apliteni-strategy-theme";
+var CHOICE_EVENT = "apliteni-theme-choice";
+var THEME_INIT_SCRIPT = `(()=>{let t;try{t=localStorage.getItem('apliteni-strategy-theme')}catch{}document.documentElement.setAttribute('data-theme',t==='dark'||t==='light'?t:window.matchMedia?.('(prefers-color-scheme: light)').matches?'light':'dark')})()`;
+function storedTheme() {
+  try {
+    const value = localStorage.getItem(STORAGE_KEY);
+    return value === "dark" || value === "light" || value === "auto" ? value : null;
+  } catch {
+    return snapshot();
+  }
+}
+function snapshot() {
+  const choice = document.documentElement.getAttribute("data-theme-choice");
+  return choice === "dark" || choice === "light" ? choice : "auto";
+}
+function subscribe(notify) {
+  const root = document.documentElement;
+  const media = window.matchMedia?.("(prefers-color-scheme: light)");
+  const applyPreference = (choice) => {
+    root.setAttribute("data-theme-choice", choice);
+    root.setAttribute("data-theme", choice === "auto" ? media?.matches ? "light" : "dark" : choice);
+  };
+  const onSystem = () => {
+    if (snapshot() === "auto") applyPreference("auto");
+  };
+  const onChoice = () => notify();
+  const onStorage = (event) => {
+    if (event.key !== null && event.key !== STORAGE_KEY) return;
+    applyPreference(storedTheme() ?? "auto");
+  };
+  const observer = new MutationObserver(notify);
+  observer.observe(root, { attributes: true, attributeFilter: ["data-theme", "data-theme-choice"] });
+  applyPreference(root.hasAttribute("data-theme-choice") ? snapshot() : storedTheme() ?? "auto");
+  media?.addEventListener("change", onSystem);
+  window.addEventListener(CHOICE_EVENT, onChoice);
+  window.addEventListener("storage", onStorage);
+  return () => {
+    observer.disconnect();
+    media?.removeEventListener("change", onSystem);
+    window.removeEventListener(CHOICE_EVENT, onChoice);
+    window.removeEventListener("storage", onStorage);
+  };
+}
+function ThemeToggle({ labelled = false }) {
+  const theme = useSyncExternalStore(subscribe, snapshot, () => "auto");
+  const next = theme === "dark" ? "light" : theme === "light" ? "auto" : "dark";
+  const label = theme === "auto" ? "Auto" : theme === "light" ? "Light" : "Dark";
+  const name = `Theme: ${label}. Switch to ${next}.`;
+  const toggle = () => {
+    document.documentElement.setAttribute("data-theme-choice", next);
+    document.documentElement.setAttribute("data-theme", next === "auto" ? window.matchMedia?.("(prefers-color-scheme: light)").matches ? "light" : "dark" : next);
+    try {
+      localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+    }
+    window.dispatchEvent(new Event(CHOICE_EVENT));
+  };
+  const button = /* @__PURE__ */ jsx27("button", { type: "button", className: "toggle", "aria-label": name, title: name, onClick: toggle, children: /* @__PURE__ */ jsx27("span", { className: "ic", "aria-hidden": "true", dangerouslySetInnerHTML: { __html: icon5(theme === "auto" ? "monitor" : theme === "light" ? "sun" : "moon") } }) });
+  return labelled ? /* @__PURE__ */ jsxs23("span", { className: "ui-theme-toggle", children: [
+    button,
+    /* @__PURE__ */ jsxs23("span", { children: [
+      label,
+      " theme"
+    ] })
+  ] }) : button;
+}
+
 // src/index.ts
 var PAGE_SIZES = KIT_PAGE_SIZES;
 var DEFAULT_PAGE_SIZE3 = KIT_DEFAULT_PAGE_SIZE;
@@ -2370,9 +2441,11 @@ export {
   SkeletonTable,
   Snippet,
   StatBand,
+  THEME_INIT_SCRIPT,
   Tabs,
   TextArea,
   TextField,
+  ThemeToggle,
   Timeline,
   Toast,
   sortTableRows,

package/src/components/topbar.js

@@ -8,22 +8,10 @@ import { accountMenuNav, initials, toMenuTuple } from './account-nav.js';
 import { trustedAttr, trustedUrl } from '../html.js';
 const THEME_KEY = 'apliteni-strategy-theme';
 
-// A stateful control in this kit reports the state it is IN, never the state a
-// click would produce — the same reading as segmented()'s aria-pressed, the
-// Deck/Text switch's aria-current, and the accent chips. So: moon while dark,
-// sun while light. Storybook's own toolbar toggle (.storybook/theme-toggle.jsx)
-// reads the same way, and topbar stories render directly beneath it.
-export const themeIcon = (t) => (t === 'light' ? sun : moon);
-
-// The name carries both the state and what the click does, which is why there
-// is no aria-pressed and no role="switch": dark and light are peers, not on and
-// off, and an ARIA state on top of this name would announce the theme twice.
-// The button is icon-only, so `title` is the only sighted reading of the same
-// fact and carries the identical string — nothing for WCAG 2.5.3 to disagree
-// with. Both are rewritten by applyTheme on every flip; a name that is right
-// once and never again tells a screen-reader user nothing.
-export const themeName = (t) =>
-  (t === 'light' ? 'Theme: Light. Switch to dark.' : 'Theme: Dark. Switch to light.');
+// The icon and name show the saved choice, including automatic mode.
+export const themeIcon = (t) => t === 'auto' ? icon('monitor') : t === 'light' ? sun : moon;
+export const themeName = (t) => t === 'auto' ? 'Theme: Auto. Switch to dark.' :
+  t === 'light' ? 'Theme: Light. Switch to auto.' : 'Theme: Dark. Switch to light.';
 
 export function themeToggle(theme = 'dark') {
   // Single icon-only switch. Icon and name are pre-filled for `theme` so the
@@ -113,7 +101,9 @@ export function topbar({
 
 // ---- Behaviours (call once after markup mounts) --------------------------
 export function applyTheme(t, root = document.documentElement) {
-  root.setAttribute('data-theme', t);
+  const media = root.ownerDocument.defaultView.matchMedia?.('(prefers-color-scheme: light)');
+  root.setAttribute('data-theme-choice', t);
+  root.setAttribute('data-theme', t === 'auto' ? (media?.matches ? 'light' : 'dark') : t);
   const name = themeName(t);
   root.querySelectorAll('[data-theme-toggle]').forEach((btn) => {
     const ic = btn.querySelector('[data-theme-icon]');
@@ -124,6 +114,8 @@ export function applyTheme(t, root = document.documentElement) {
     btn.setAttribute('title', name);
   });
   try { localStorage.setItem(THEME_KEY, t); } catch (e) { /* no-op */ }
+  const view = root.ownerDocument.defaultView;
+  view.dispatchEvent(new view.Event('apliteni-theme-choice'));
 }
 
 const ACCENT_KEY = 'apliteni-strategy-accent';
@@ -135,14 +127,55 @@ export function applyAccent(name, root = document.documentElement) {
   try { localStorage.setItem(ACCENT_KEY, name || 'default'); } catch (e) { /* no-op */ }
 }
 
+const themeListeners = new WeakMap();
+
 export function wireTopbar(root = document) {
-  // Theme toggle
-  root.querySelectorAll('[data-theme-toggle]').forEach((btn) => {
-    const html = document.documentElement;
-    const cur = html.getAttribute('data-theme') || 'dark';
-    applyTheme(cur, html);
-    btn.addEventListener('click', () => applyTheme(html.getAttribute('data-theme') === 'dark' ? 'light' : 'dark', html));
-  });
+  const html = document.documentElement;
+  const buttons = root.querySelectorAll('[data-theme-toggle]');
+  if (buttons.length) {
+    let choice = html.getAttribute('data-theme-choice') || 'auto';
+    try { choice = localStorage.getItem(THEME_KEY) || choice; } catch { /* Use the page choice. */ }
+    if (!['dark', 'light', 'auto'].includes(choice)) choice = 'auto';
+    applyTheme(choice, html);
+    const media = html.ownerDocument.defaultView.matchMedia?.('(prefers-color-scheme: light)');
+    themeListeners.get(html)?.();
+    const onSystem = () => {
+      if (html.getAttribute('data-theme-choice') === 'auto') {
+        html.setAttribute('data-theme', media?.matches ? 'light' : 'dark');
+      }
+    };
+    media?.addEventListener('change', onSystem);
+    const updateButtons = () => {
+      const choice = html.getAttribute('data-theme-choice') || 'auto';
+      html.querySelectorAll('[data-theme-toggle]').forEach((btn) => {
+        btn.setAttribute('aria-label', themeName(choice));
+        btn.setAttribute('title', themeName(choice));
+        const glyph = btn.querySelector('[data-theme-icon]');
+        if (glyph) glyph.innerHTML = themeIcon(choice);
+      });
+    };
+    const observer = new html.ownerDocument.defaultView.MutationObserver(updateButtons);
+    observer.observe(html, { attributes: true, attributeFilter: ['data-theme-choice'] });
+    const view = html.ownerDocument.defaultView;
+    const onStorage = (event) => {
+      if (event.key !== null && event.key !== THEME_KEY) return;
+      let saved;
+      try { saved = localStorage.getItem(THEME_KEY); } catch { return; }
+      applyTheme(saved === 'dark' || saved === 'light' ? saved : 'auto', html);
+    };
+    view.addEventListener('storage', onStorage);
+    themeListeners.set(html, () => {
+      media?.removeEventListener('change', onSystem);
+      view.removeEventListener('storage', onStorage);
+      observer.disconnect();
+    });
+    buttons.forEach((btn) => {
+      btn.onclick = () => {
+        const current = html.getAttribute('data-theme-choice');
+        applyTheme(current === 'dark' ? 'light' : current === 'light' ? 'auto' : 'dark', html);
+      };
+    });
+  }
   // Deck/Text view switch (.dtsw) — switch the active pill on click
   root.querySelectorAll('.dtsw').forEach((sw) => {
     sw.addEventListener('click', (e) => {

package/src/styles/topbar.css

@@ -86,7 +86,7 @@
     border-color var(--dur-fast) var(--ease);
 }
 .toggle:hover { transform: translateY(-1px); border-color: var(--border-strong); }
-.toggle .ic { width: 17px; height: 17px; display: inline-block; color: var(--accent); }
+.toggle .ic { width: 17px; height: 17px; display: inline-block; color: var(--text); }
 .toggle .ic svg { display: block; width: 100%; height: 100%; stroke-width: 2.2; }
 
 /* Version switcher */