@tenphi/renderer 0.25.2 → 0.25.4

package/dist/components/MainContent.styles.js

@@ -10,6 +10,9 @@ export const MainContentRoot = defineComponent("MainContent", {
   styles: {
     "@property": TASTY_SPACING_PROPERTIES,
     padding: "0 0 5rem",
+    // A focus target for the skip link and page swaps, not a control. Clicking
+    // its text focuses it, so keyboard scrolling would otherwise show a ring.
+    outline: "none",
     // Layout spacing is a default; generated Markdown owns prose spacing.
     ContentSpacing: {
       $: ":where(Panel > Container) > * + *",

package/dist/components/Pagination.styles.js

@@ -22,7 +22,7 @@ export const PaginationRoot = defineComponent("Pagination", {
       gap: "$gap",
       inlineSize: "100%",
       padding: "($gap * 2)",
-      border: "#clear",
+      border: true,
       color: "#text-soft",
       fill: "#surface-2",
       shadow: "none",

package/dist/components/Sidebar.styles.js

@@ -158,7 +158,9 @@ export const SidebarRoot = defineComponent("Sidebar", {
       $: "ul > li + li",
       blockMargin: {
         "": null,
-        "@own(top-level)": "0 start",
+        // States add no specificity, so leave sections to GroupSpacing rather
+        // than depending on the order of the two rules.
+        "@own(top-level & !section)": "0 start",
       },
     },
     GroupSpacing: {
@@ -252,6 +254,9 @@ export const SidebarRoot = defineComponent("Sidebar", {
         '@own((:hover | :focus-visible) & ![aria-current="page"])':
           "#surface-2-hover",
       },
+      // Lift the focus ring above the next item's fill.
+      position: { "": null, "@own(:focus-visible)": "relative" },
+      zIndex: { "": null, "@own(:focus-visible)": "1" },
     },
     SummaryMarker: {
       $: "cookbook-sidebar summary::marker, summary::-webkit-details-marker",

package/dist/components/appearance-bootstrap.js

@@ -1,21 +1,29 @@
 // Kept dependency-free for the page shell's synchronous, pre-paint script.
+// Reads the documented storage contract in appearance-preferences.ts.
 (() => {
   const root = globalThis.document.documentElement;
+  let appearance = {};
   try {
-    const scheme = globalThis.localStorage.getItem("cookbook-theme");
-    if (scheme === "light" || scheme === "dark") root.dataset.theme = scheme;
-    else delete root.dataset.theme;
-  } catch {
-    // Without storage, the document's system appearance rules remain active.
-  }
-  try {
-    const appearance = JSON.parse(
-      globalThis.localStorage.getItem("cookbook-appearance") ?? "{}",
-    );
-    if (appearance?.contrast === "normal" || appearance?.contrast === "more")
-      root.dataset.contrast = appearance.contrast;
-    else delete root.dataset.contrast;
+    appearance =
+      JSON.parse(
+        globalThis.localStorage.getItem("cookbook-appearance") ?? "{}",
+      ) ?? {};
   } catch {
     // Malformed or unavailable storage must not prevent the first paint.
   }
+  let theme = appearance.theme;
+  if (theme === undefined) {
+    try {
+      // A scheme saved before the appearance object held it.
+      theme = globalThis.localStorage.getItem("cookbook-theme");
+    } catch {
+      // Without storage, the document's system appearance rules remain active.
+    }
+  }
+  if (theme === "light" || theme === "dark") root.dataset.theme = theme;
+  else delete root.dataset.theme;
+  const contrast = appearance.contrast;
+  if (contrast === "normal" || contrast === "more")
+    root.dataset.contrast = contrast;
+  else delete root.dataset.contrast;
 })();

package/dist/components/appearance-preferences.test.ts

@@ -7,71 +7,104 @@ function storage(values: Record<string, string> = {}) {
     setItem: (key: string, value: string) => {
       values[key] = value;
     },
+    removeItem: (key: string) => {
+      delete values[key];
+    },
   };
 }
 
 describe("appearance preferences", () => {
-  it("restores existing independent scheme and contrast choices", () => {
+  it("restores independent theme and contrast choices from one object", () => {
     const saved = storage({
-      "cookbook-theme": "dark",
-      "cookbook-appearance": JSON.stringify({ contrast: "more" }),
+      "cookbook-appearance": JSON.stringify({
+        theme: "dark",
+        contrast: "more",
+      }),
     });
     expect(loadPreferences(saved)).toEqual({
-      scheme: "dark",
+      theme: "dark",
       contrast: "more",
     });
-    storePreferences({ scheme: "light", contrast: "more" }, saved);
+    storePreferences({ theme: "light", contrast: "more" }, saved);
     expect(loadPreferences(saved)).toEqual({
-      scheme: "light",
+      theme: "light",
       contrast: "more",
     });
-    storePreferences({ scheme: "light", contrast: "normal" }, saved);
-    expect(loadPreferences(saved)).toEqual({
-      scheme: "light",
+    storePreferences({ theme: "light", contrast: "normal" }, saved);
+    expect(JSON.parse(saved.getItem("cookbook-appearance")!)).toEqual({
+      theme: "light",
       contrast: "normal",
     });
   });
 
-  it("persists Auto using Cookbook storage without losing other preferences", () => {
+  it("persists system choices without losing other fields", () => {
     const saved = storage({
       "cookbook-appearance": JSON.stringify({ contrast: "more", other: true }),
     });
-    storePreferences({ scheme: "auto", contrast: "system" }, saved);
-    expect(saved.getItem("cookbook-theme")).toBe("");
+    storePreferences({ theme: "system", contrast: "system" }, saved);
     expect(JSON.parse(saved.getItem("cookbook-appearance")!)).toEqual({
+      theme: "system",
       contrast: "system",
       other: true,
     });
     expect(loadPreferences(saved)).toEqual({
-      scheme: "auto",
+      theme: "system",
       contrast: "system",
     });
   });
 
+  it("reads a scheme saved under the legacy key and removes it on save", () => {
+    const saved = storage({
+      "cookbook-theme": "dark",
+      "cookbook-appearance": JSON.stringify({ contrast: "more" }),
+    });
+    expect(loadPreferences(saved)).toEqual({
+      theme: "dark",
+      contrast: "more",
+    });
+    storePreferences(loadPreferences(saved), saved);
+    expect(saved.getItem("cookbook-theme")).toBeNull();
+    expect(JSON.parse(saved.getItem("cookbook-appearance")!)).toEqual({
+      theme: "dark",
+      contrast: "more",
+    });
+  });
+
+  it("prefers the object's theme over the legacy key", () => {
+    const saved = storage({
+      "cookbook-theme": "dark",
+      "cookbook-appearance": JSON.stringify({ theme: "system" }),
+    });
+    expect(loadPreferences(saved).theme).toBe("system");
+  });
+
   it.each(["{broken", "null", "[]", '"more"', '{"contrast":"invalid"}'])(
-    "recovers from malformed contrast data: %s",
+    "recovers from malformed appearance data: %s",
     (value) => {
-      const saved = storage({
-        "cookbook-theme": "light",
-        "cookbook-appearance": value,
-      });
+      const saved = storage({ "cookbook-appearance": value });
       expect(loadPreferences(saved)).toEqual({
-        scheme: "light",
+        theme: "system",
         contrast: "system",
       });
-      storePreferences({ scheme: "dark", contrast: "more" }, saved);
+      storePreferences({ theme: "dark", contrast: "more" }, saved);
       expect(loadPreferences(saved)).toEqual({
-        scheme: "dark",
+        theme: "dark",
         contrast: "more",
       });
     },
   );
 
   it("uses system defaults for unknown values or unavailable storage", () => {
-    expect(loadPreferences(storage({ "cookbook-theme": "invalid" }))).toEqual({
-      scheme: "auto",
-      contrast: "system",
-    });
+    expect(
+      loadPreferences(
+        storage({
+          "cookbook-appearance": JSON.stringify({
+            theme: "invalid",
+            contrast: "invalid",
+          }),
+        }),
+      ),
+    ).toEqual({ theme: "system", contrast: "system" });
     const unavailable = {
       getItem: () => {
         throw new Error("Storage unavailable");
@@ -79,13 +112,16 @@ describe("appearance preferences", () => {
       setItem: () => {
         throw new Error("Storage unavailable");
       },
+      removeItem: () => {
+        throw new Error("Storage unavailable");
+      },
     };
     expect(loadPreferences(unavailable)).toEqual({
-      scheme: "auto",
+      theme: "system",
       contrast: "system",
     });
     expect(() =>
-      storePreferences({ scheme: "dark", contrast: "more" }, unavailable),
+      storePreferences({ theme: "dark", contrast: "more" }, unavailable),
     ).not.toThrow();
   });
 });

package/dist/components/appearance-preferences.ts

@@ -1,19 +1,25 @@
-type Scheme = "light" | "dark" | "auto";
+// `cookbook-appearance` is a documented contract that other apps on the same
+// origin read and write (docs/theme-and-components.md, "Reader appearance").
+// Keep its key and value format compatible; appearance-bootstrap.js reads it too.
+export const APPEARANCE_KEY = "cookbook-appearance";
+// The color scheme used to live in its own key. It is still read when the
+// object has no `theme`, and removed on the next save.
+export const LEGACY_THEME_KEY = "cookbook-theme";
+
+type Theme = "light" | "dark" | "system";
 type Contrast = "normal" | "more" | "system";
-type Preferences = { scheme: Scheme; contrast: Contrast };
-type PreferenceStorage = Pick<Storage, "getItem" | "setItem">;
+type Preferences = { theme: Theme; contrast: Contrast };
+type PreferenceStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
 
-export const parseScheme = (value: unknown): Scheme =>
-  value === "light" || value === "dark" ? value : "auto";
+export const parseTheme = (value: unknown): Theme =>
+  value === "light" || value === "dark" ? value : "system";
 
 export const parseContrast = (value: unknown): Contrast =>
   value === "normal" || value === "more" ? value : "system";
 
 function storedAppearance(storage: PreferenceStorage): Record<string, unknown> {
   try {
-    const value: unknown = JSON.parse(
-      storage.getItem("cookbook-appearance") ?? "{}",
-    );
+    const value: unknown = JSON.parse(storage.getItem(APPEARANCE_KEY) ?? "{}");
     return value && typeof value === "object" && !Array.isArray(value)
       ? (value as Record<string, unknown>)
       : {};
@@ -23,11 +29,14 @@ function storedAppearance(storage: PreferenceStorage): Record<string, unknown> {
 }
 
 export function loadPreferences(storage?: PreferenceStorage): Preferences {
-  const preferences: Preferences = { scheme: "auto", contrast: "system" };
+  const preferences: Preferences = { theme: "system", contrast: "system" };
   try {
     storage ??= localStorage;
-    preferences.scheme = parseScheme(storage.getItem("cookbook-theme"));
-    preferences.contrast = parseContrast(storedAppearance(storage).contrast);
+    const stored = storedAppearance(storage);
+    preferences.theme = parseTheme(
+      "theme" in stored ? stored.theme : storage.getItem(LEGACY_THEME_KEY),
+    );
+    preferences.contrast = parseContrast(stored.contrast);
   } catch {
     // System defaults work even when browser storage is unavailable.
   }
@@ -41,16 +50,14 @@ export function storePreferences(
   try {
     storage ??= localStorage;
     storage.setItem(
-      "cookbook-theme",
-      value.scheme === "auto" ? "" : value.scheme,
-    );
-    storage.setItem(
-      "cookbook-appearance",
+      APPEARANCE_KEY,
       JSON.stringify({
         ...storedAppearance(storage),
+        theme: value.theme,
         contrast: value.contrast,
       }),
     );
+    storage.removeItem(LEGACY_THEME_KEY);
   } catch {
     // The current page still updates when preferences cannot be persisted.
   }

package/dist/overrides/ThemeSelect.astro

@@ -11,7 +11,11 @@ const id = `appearance-${crypto.randomUUID()}`;
 const schemes = [
   { value: "light", label: Astro.locals.t("themeSelect.light"), icon: "sun" },
   { value: "dark", label: Astro.locals.t("themeSelect.dark"), icon: "moon" },
-  { value: "auto", label: Astro.locals.t("themeSelect.auto"), icon: "laptop" },
+  {
+    value: "system",
+    label: Astro.locals.t("themeSelect.auto"),
+    icon: "laptop",
+  },
 ] as const;
 const contrasts = [
   { value: "normal", label: ui.normalContrast, icon: "normal" },
@@ -46,7 +50,7 @@ const contrasts = [
               name={`${id}-scheme`}
               value={value}
               data-appearance-scheme
-              checked={value === "auto"}
+              checked={value === "system"}
             />
             <Icon name={icon} />
             <span>{label}</span>
@@ -83,9 +87,11 @@ const contrasts = [
 
 <script>
   import {
+    APPEARANCE_KEY,
+    LEGACY_THEME_KEY,
     loadPreferences,
     storePreferences,
-    parseScheme,
+    parseTheme,
     parseContrast,
   } from "../components/appearance-preferences.js";
   import { initializePopoverMotion } from "../client/popover-motion.js";
@@ -95,11 +101,11 @@ const contrasts = [
 
   function applyPreferences(): void {
     document.documentElement.dataset.theme =
-      current.scheme === "auto"
+      current.theme === "system"
         ? systemScheme.matches
           ? "light"
           : "dark"
-        : current.scheme;
+        : current.theme;
     if (current.contrast === "system") {
       delete document.documentElement.dataset.contrast;
     } else {
@@ -108,7 +114,7 @@ const contrasts = [
     document
       .querySelectorAll<HTMLInputElement>("[data-appearance-scheme]")
       .forEach((input) => {
-        input.checked = input.value === current.scheme;
+        input.checked = input.value === current.theme;
       });
     document
       .querySelectorAll<HTMLInputElement>("[data-appearance-contrast]")
@@ -118,12 +124,13 @@ const contrasts = [
   }
 
   systemScheme.addEventListener("change", () => {
-    if (current.scheme === "auto") applyPreferences();
+    if (current.theme === "system") applyPreferences();
   });
   window.addEventListener("storage", (event) => {
     if (
       !event.key ||
-      ["cookbook-theme", "cookbook-appearance"].includes(event.key)
+      event.key === APPEARANCE_KEY ||
+      event.key === LEGACY_THEME_KEY
     ) {
       current = loadPreferences();
       applyPreferences();
@@ -139,7 +146,7 @@ const contrasts = [
         const input = event.target;
         if (!(input instanceof HTMLInputElement)) return;
         if (input.hasAttribute("data-appearance-scheme")) {
-          current.scheme = parseScheme(input.value);
+          current.theme = parseTheme(input.value);
         } else if (input.hasAttribute("data-appearance-contrast")) {
           current.contrast = parseContrast(input.value);
         } else return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/renderer",
-  "version": "0.25.2",
+  "version": "0.25.4",
   "description": "Astro renderer and Tasty theme for Cookbook",
   "type": "module",
   "sideEffects": [
@@ -61,7 +61,7 @@
     "@fontsource-variable/jetbrains-mono": "^5.3.0",
     "@fontsource-variable/onest": "^5.3.0",
     "@pagefind/default-ui": "1.5.2",
-    "@tenphi/docs": "0.25.2",
+    "@tenphi/docs": "0.25.4",
     "@tenphi/eslint-plugin-tasty": "1.6.0",
     "@tenphi/glaze": "2.0.1",
     "@tenphi/tasty": "3.9.10",