starlight-theme-bejamas 0.1.18 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # starlight-theme-bejamas
 
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies [[`d8abe23`](https://github.com/bejamas/ui/commit/d8abe237f179cc6a5be73823a134a6221c62cca5)]:
+  - @bejamas/semantic-icons@0.2.0
+
+## 0.2.2
+
+### Patch Changes
+
+- [#159](https://github.com/bejamas/ui/pull/159) [`d9fb503`](https://github.com/bejamas/ui/commit/d9fb50331b2692cad08f1653611b952312e6d7fe) Thanks [@Tadzik-2](https://github.com/Tadzik-2)! - Point sidebar group carets down when collapsed and up when expanded.
+
+## 0.2.1
+
+### Patch Changes
+
+- [#143](https://github.com/bejamas/ui/pull/143) [`94b6e69`](https://github.com/bejamas/ui/commit/94b6e698d22920f974d263709828cb9cfaa1bce5) Thanks [@Tadzik-2](https://github.com/Tadzik-2)! - Publish semantic icons publicly and validate packed release manifests so the theme installs without workspace protocol or private runtime dependencies.
+
+- Updated dependencies [[`94b6e69`](https://github.com/bejamas/ui/commit/94b6e698d22920f974d263709828cb9cfaa1bce5)]:
+  - @bejamas/semantic-icons@0.1.1
+
+## 0.2.0
+
+### Minor Changes
+
+- [#102](https://github.com/bejamas/ui/pull/102) [`25987b8`](https://github.com/bejamas/ui/commit/25987b872d38280dfe47f820019f86c1cb00eb6d) Thanks [@thomkrupa](https://github.com/thomkrupa)! - Improve the Starlight Bejamas theme runtime and expose the shared theme-choice helpers for consumers that need to integrate with theme state directly.
+  - Unify light, dark, and auto theme choice handling across the theme picker, page chrome, and preview surfaces so theme state stays in sync more reliably.
+  - Refresh browser theme-color metadata and the active theme stylesheet more consistently when theme state or presets change.
+  - Sync semantic icon updates as part of the theme runtime so icon-library changes propagate cleanly with preset-driven theme updates.
+  - Export `starlight-theme-bejamas/lib/theme-choice` as a public entrypoint for consumers that want to read, apply, or react to the shared theme-choice state.
+
 ## 0.1.18
 
 ### Patch Changes

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "starlight-theme-bejamas",
   "author": "Bejamas",
-  "version": "0.1.18",
+  "version": "0.2.3",
   "license": "MIT",
   "description": "A Starlight theme using bejamas/ui",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./config": "./src/config.ts",
+    "./lib/theme-choice": "./src/lib/theme-choice.ts",
     "./styles/theme.css": "./src/styles/theme.css",
     "./overrides/Header.astro": "./src/overrides/Header.astro",
     "./overrides/PageFrame.astro": "./src/overrides/PageFrame.astro",
@@ -37,13 +38,13 @@
   },
   "bugs": "https://github.com/bejamas/ui/issues",
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.33.0",
-    "astro": ">=5.5.0"
+    "@astrojs/starlight": "^0.42.3",
+    "astro": "^7.3.4"
   },
   "dependencies": {
-    "@expressive-code/plugin-line-numbers": "^0.41.3",
-    "@fontsource-variable/inter": "^5.2.8",
-    "@fontsource/inter": "^5.2.8",
-    "@lucide/astro": "^0.545.0"
+    "@bejamas/semantic-icons": "0.2.0",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource/inter": "^5.3.0",
+    "@lucide/astro": "^1.47.0"
   }
 }

package/src/config.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+
+import { StarlightThemeBejamasConfigSchema } from "./config";
+
+describe("starlight-theme-bejamas config schema", () => {
+  test("parses nav and component maps under zod v4", () => {
+    const result = StarlightThemeBejamasConfigSchema.safeParse({
+      nav: [
+        {
+          label: {
+            en: "Docs",
+            fr: "Documentation",
+          },
+          href: "/docs/introduction",
+          attrs: {
+            rel: "prefetch",
+            "data-track": "docs-link",
+          },
+        },
+      ],
+      components: {
+        ThemeSelect: "./src/components/ThemeSwitcher.astro",
+        PageTitle: "./src/components/PageTitle.astro",
+      },
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) {
+      throw result.error;
+    }
+
+    expect(result.data.nav?.[0]?.label).toEqual({
+      en: "Docs",
+      fr: "Documentation",
+    });
+    expect(result.data.components?.ThemeSelect).toBe(
+      "./src/components/ThemeSwitcher.astro",
+    );
+  });
+});

package/src/config.ts

@@ -3,7 +3,8 @@ import type { HTMLAttributes } from "astro/types";
 import { z } from "astro/zod";
 
 const linkHTMLAttributesSchema = z.record(
-  z.union([z.string(), z.number(), z.boolean(), z.undefined()])
+  z.string(),
+  z.union([z.string(), z.number(), z.boolean(), z.undefined()]),
 ) as z.Schema<
   Omit<HTMLAttributes<"a">, keyof AstroBuiltinAttributes | "children">
 >;
@@ -25,7 +26,7 @@ const navLinkSchema = z.object({
    * The value can be a string, or for multilingual sites, an object with values for each different locale. When using
    * the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN).
    */
-  label: z.union([z.string(), z.record(z.string())]),
+  label: z.union([z.string(), z.record(z.string(), z.string())]),
   /**
    * The link to the topic’s content which an be a relative link to local files or the full URL of an external page.
    *
@@ -39,7 +40,7 @@ const navLinkSchema = z.object({
 
 export const StarlightThemeBejamasConfigSchema = z.object({
   nav: z.array(navLinkSchema).optional(),
-  components: z.record(z.string()).optional(),
+  components: z.record(z.string(), z.string()).optional(),
 });
 
 export type StarlightThemeBejamasUserConfig = z.input<

package/src/global.d.ts

@@ -1,12 +1,14 @@
 declare global {
   interface Window {
     StarlightThemeProvider?: {
-      updatePickers: (theme?: string) => void;
+      refreshThemeColors?: (theme?: string) => void;
+      updatePickers?: (theme?: string) => void;
     };
   }
 
   const StarlightThemeProvider: {
-    updatePickers: (theme?: string) => void;
+    refreshThemeColors?: (theme?: string) => void;
+    updatePickers?: (theme?: string) => void;
   };
 
   namespace App {

package/src/index.ts

@@ -11,7 +11,6 @@ import {
   type StarlightThemeBejamasUserConfig,
 } from "./config";
 import { vitePluginStarlightThemeBejamas } from "./lib/vite";
-// import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
 
 export default function starlightThemeBejamas(
   userConfig: StarlightThemeBejamasUserConfig,
@@ -48,12 +47,6 @@ export default function starlightThemeBejamas(
             ? {}
             : starlightConfig.expressiveCode;
 
-        // starlightConfig.plugins?.push(
-        //   pluginLineNumbers({
-        //     showLineNumbers: true,
-        //   }),
-        // );
-
         const componentOverrides: typeof config.components = {};
 
         type OverridableComponent =

package/src/lib/theme-choice.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "bun:test";
+import {
+  STARLIGHT_THEME_STORAGE_KEY,
+  THEME_TOGGLE_CHANGED_EVENT,
+  applyThemeModeToRoot,
+  buildThemeChoiceBootstrapInlineScript,
+  getThemeChoiceFromRoot,
+  getThemeModeFromRoot,
+  loadStoredThemeChoice,
+  parseStoredThemeChoice,
+  resolveThemeMode,
+  setThemeChoice,
+  storeThemeChoice,
+  syncThemeChoiceControls,
+} from "./theme-choice";
+
+function createThemeRoot() {
+  const classes = new Set<string>();
+
+  return {
+    classes,
+    root: {
+      dataset: {} as Record<string, string | undefined>,
+      classList: {
+        add: (...tokens: string[]) => {
+          for (const token of tokens) {
+            classes.add(token);
+          }
+        },
+        remove: (...tokens: string[]) => {
+          for (const token of tokens) {
+            classes.delete(token);
+          }
+        },
+        contains: (token: string) => classes.has(token),
+      },
+    },
+  };
+}
+
+describe("theme choice runtime", () => {
+  it("parses only supported stored theme choices", () => {
+    expect(parseStoredThemeChoice("light")).toBe("light");
+    expect(parseStoredThemeChoice("dark")).toBe("dark");
+    expect(parseStoredThemeChoice("auto")).toBe("auto");
+    expect(parseStoredThemeChoice("")).toBe("auto");
+    expect(parseStoredThemeChoice("system")).toBe("auto");
+    expect(parseStoredThemeChoice(undefined)).toBe("auto");
+  });
+
+  it("loads the stored theme choice from localStorage-compatible storage", () => {
+    expect(
+      loadStoredThemeChoice({
+        getItem: (key) =>
+          key === STARLIGHT_THEME_STORAGE_KEY ? "dark" : null,
+      }),
+    ).toBe("dark");
+
+    expect(
+      loadStoredThemeChoice({
+        getItem: () => "unexpected",
+      }),
+    ).toBe("auto");
+
+    expect(
+      loadStoredThemeChoice({
+        getItem: () => {
+          throw new Error("storage unavailable");
+        },
+      }),
+    ).toBe("auto");
+  });
+
+  it("resolves auto against the preferred color scheme", () => {
+    expect(resolveThemeMode("light", false)).toBe("light");
+    expect(resolveThemeMode("dark", true)).toBe("dark");
+    expect(resolveThemeMode("auto", true)).toBe("light");
+    expect(resolveThemeMode("auto", false)).toBe("dark");
+  });
+
+  it("applies theme attributes and class state to the target root", () => {
+    const { root, classes } = createThemeRoot();
+
+    classes.add("dark");
+    applyThemeModeToRoot(root, "auto", "light");
+
+    expect(root.dataset.theme).toBe("light");
+    expect(root.dataset.themeChoice).toBe("auto");
+    expect(classes.has("light")).toBe(true);
+    expect(classes.has("dark")).toBe(false);
+  });
+
+  it("stores explicit theme choices and clears auto to the empty localStorage value", () => {
+    const stored = new Map<string, string>();
+    const storage = {
+      setItem: (key: string, value: string) => {
+        stored.set(key, value);
+      },
+    };
+
+    storeThemeChoice(storage, "dark");
+    storeThemeChoice(storage, "auto");
+
+    expect(stored.get(STARLIGHT_THEME_STORAGE_KEY)).toBe("");
+  });
+
+  it("reads theme choice and effective mode from the document root", () => {
+    const { root, classes } = createThemeRoot();
+
+    root.dataset.themeChoice = "auto";
+    root.dataset.theme = "";
+    classes.add("dark");
+
+    expect(getThemeChoiceFromRoot(root)).toBe("auto");
+    expect(getThemeModeFromRoot(root, "light")).toBe("dark");
+  });
+
+  it("syncs tabs-based and legacy select-based controls to the requested choice", () => {
+    let tabsValue = "";
+    let selectValue = "";
+    const nativeSelect = { value: "" };
+    const tabsRoot = {
+      dataset: {} as Record<string, string | undefined>,
+      dispatchEvent: (event: Event) => {
+        tabsValue =
+          (event as CustomEvent<{ value?: string }>).detail?.value ?? "";
+        return true;
+      },
+    };
+    const selectRoot = {
+      dataset: {} as Record<string, string | undefined>,
+      dispatchEvent: (event: Event) => {
+        selectValue =
+          (event as CustomEvent<{ value?: string }>).detail?.value ?? "";
+        return true;
+      },
+    };
+    const picker = {
+      querySelector: (selector: string) => {
+        if (selector === '[data-slot="tabs"][data-theme-choice-tabs]') {
+          return tabsRoot;
+        }
+
+        if (selector === "select") {
+          return nativeSelect;
+        }
+
+        if (selector === '#starlight-theme-select, [data-slot="select"]') {
+          return selectRoot;
+        }
+
+        return null;
+      },
+      querySelectorAll: () => [] as unknown as NodeListOf<Element>,
+    };
+    const root = {
+      querySelectorAll: (selector: string) => {
+        if (selector === "starlight-theme-select") {
+          return [picker] as unknown as NodeListOf<Element>;
+        }
+
+        if (selector === '[data-slot="tabs"][data-theme-choice-tabs]') {
+          return [tabsRoot] as unknown as NodeListOf<Element>;
+        }
+
+        return [] as unknown as NodeListOf<Element>;
+      },
+    };
+
+    syncThemeChoiceControls("light", root as unknown as ParentNode);
+
+    expect(tabsRoot.dataset.defaultValue).toBe("light");
+    expect(tabsRoot.dataset.value).toBe("light");
+    expect(tabsValue).toBe("light");
+    expect(nativeSelect.value).toBe("light");
+    expect(selectRoot.dataset.defaultValue).toBe("light");
+    expect(selectRoot.dataset.value).toBe("light");
+    expect(selectValue).toBe("light");
+  });
+
+  it("applies the shared global theme choice path including storage, controls, and event dispatch", () => {
+    const { root, classes } = createThemeRoot();
+    const stored = new Map<string, string>();
+    const dispatched: Array<{ theme: string; themeChoice: string }> = [];
+    let tabsValue = "";
+    const tabsRoot = {
+      dataset: {} as Record<string, string | undefined>,
+      dispatchEvent: (event: Event) => {
+        tabsValue =
+          (event as CustomEvent<{ value?: string }>).detail?.value ?? "";
+        return true;
+      },
+    };
+    const controlsRoot = {
+      querySelectorAll: (selector: string) => {
+        if (selector === '[data-slot="tabs"][data-theme-choice-tabs]') {
+          return [tabsRoot] as unknown as NodeListOf<Element>;
+        }
+
+        return [] as unknown as NodeListOf<Element>;
+      },
+    };
+    const dispatchTarget = {
+      dispatchEvent: (event: Event) => {
+        const customEvent = event as CustomEvent<{
+          theme?: string;
+          themeChoice?: string;
+        }>;
+
+        if (event.type === THEME_TOGGLE_CHANGED_EVENT) {
+          dispatched.push({
+            theme: customEvent.detail?.theme ?? "",
+            themeChoice: customEvent.detail?.themeChoice ?? "",
+          });
+        }
+
+        return true;
+      },
+    };
+
+    const effectiveTheme = setThemeChoice("dark", {
+      root,
+      prefersLight: true,
+      storage: {
+        setItem: (key, value) => {
+          stored.set(key, value);
+        },
+      },
+      controlsRoot: controlsRoot as unknown as ParentNode,
+      dispatchTarget: dispatchTarget as unknown as EventTarget,
+    });
+
+    expect(effectiveTheme).toBe("dark");
+    expect(root.dataset.themeChoice).toBe("dark");
+    expect(root.dataset.theme).toBe("dark");
+    expect(classes.has("dark")).toBe(true);
+    expect(stored.get(STARLIGHT_THEME_STORAGE_KEY)).toBe("dark");
+    expect(tabsValue).toBe("dark");
+    expect(dispatched).toEqual([{ theme: "dark", themeChoice: "dark" }]);
+  });
+
+  it("builds an inline bootstrap script that owns root state and control sync", () => {
+    const script = buildThemeChoiceBootstrapInlineScript();
+
+    expect(script).toContain(STARLIGHT_THEME_STORAGE_KEY);
+    expect(script).toContain("dataset.themeChoice");
+    expect(script).toContain('[data-slot="tabs"][data-theme-choice-tabs]');
+    expect(script).toContain(THEME_TOGGLE_CHANGED_EVENT);
+    expect(script).toContain("prefers-color-scheme: light");
+  });
+});