@timmo001/docs-kit 0.2.0 → 0.3.0

package/README.md

@@ -21,7 +21,7 @@ The `blume` export needs the `blume` version in `peerDependencies`.
 
 `docsConfig` returns a full Blume config from the site details. Pass anything
 else Blume accepts alongside them; it overrides the default it replaces, and
-`navigation` and `seo` merge one level deep.
+`markdown`, `navigation` and `seo` merge one level deep.
 
 ```ts
 import { docsConfig } from "@timmo001/docs-kit/blume";
@@ -46,6 +46,8 @@ The defaults:
   with the title as the logo text.
 - Content in `src/content/docs`, last-modified dates from git and external links
   opening in a new tab.
+- GitHub's high-contrast code themes, since the default ones miss WCAG AA on
+  comments and keywords. Set `markdown.code.theme` to change them.
 - Cloudflare deployment to `https://<site>`.
 - `llms.txt`, the MCP endpoint at `/mcp`, WebMCP and agent readability on. Ask
   AI and page feedback off.
@@ -98,12 +100,35 @@ Glazing, Survey, Slate, Bridge or Snag:
 @import "@timmo001/docs-kit/blume/themes/bridge.css";
 ```
 
-It sets Blume's colours, radius and fonts from the theme in light and dark, so
-leave `theme.accent` out of `blume.config.ts`. The fonts are stacks, so load
-the theme's font files in `theme.css` too, for example with
+It sets Blume's colors, radius and fonts from the theme in light, dark and
+Darker, so leave `theme.accent` out of `blume.config.ts`. The fonts are stacks,
+so load the theme's font files in `theme.css` too, for example with
 `@import "@fontsource-variable/inter";`. Use Base until the app has a theme of
 its own.
 
+`HeaderSearch` adds a mode picker next to Blume's light and dark toggle, with
+Light, Dark and Darker. To let readers pick the theme as well, import every
+theme after the site's default and pass the themes to `HeaderSearch` from a
+wrapper component:
+
+```css
+@import "@timmo001/docs-kit/blume/themes/base.css";
+@import "@timmo001/docs-kit/blume/themes/all.css";
+```
+
+```astro
+---
+import HeaderSearch from "@timmo001/docs-kit/blume/header-search.astro";
+
+const themes = [
+  { id: "base", name: "Base" },
+  { id: "bridge", name: "Bridge" },
+];
+---
+
+<HeaderSearch {...Astro.props} themes={themes} defaultTheme="base" />
+```
+
 Set these in `theme.css` to change the banner:
 
 ```css

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/docs-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared branding, layout and config for timmo001 documentation sites",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,7 @@
     "./blume": "./src/blume/index.ts",
     "./blume/header-search.astro": "./src/blume/header-search.astro",
     "./blume/home-banner.astro": "./src/blume/home-banner.astro",
+    "./blume/theme-picker.astro": "./src/blume/theme-picker.astro",
     "./blume/theme.css": "./src/blume/theme.css",
     "./blume/themes/*.css": "./src/blume/themes/*.css",
     "./package.json": "./package.json"
@@ -38,6 +39,8 @@
     "format:check": "prettier --check ."
   },
   "dependencies": {
+    "@timmo001/groundwork-tokens": "0.3.0",
+    "@timmo001/groundwork-ui": "0.3.0",
     "sharp": "0.35.5"
   },
   "peerDependencies": {

package/src/blume/config.ts

@@ -17,12 +17,14 @@ export interface DocsConfigOptions extends Omit<
 /**
  * Build a Blume config with the shared defaults: light and dark logos from
  * `public/`, Cloudflare deployment, agent surfaces on, Ask AI and feedback off,
- * and generated share cards. Any option given here wins over the default it
- * replaces; `navigation` and `seo` merge one level deep.
+ * high-contrast code themes and generated share cards. Any option given here
+ * wins over the default it replaces; `markdown`, `navigation` and `seo` merge
+ * one level deep.
  */
 export const docsConfig = ({
   site,
   github,
+  markdown,
   navigation,
   seo,
   ...config
@@ -38,9 +40,6 @@ export const docsConfig = ({
   content: {
     root: "src/content/docs",
   },
-  markdown: {
-    externalLinks: true,
-  },
   ai: {
     assistant: {
       enabled: false,
@@ -71,6 +70,20 @@ export const docsConfig = ({
     dir: "docs",
     ...github,
   },
+  // The high-contrast GitHub themes, since the default ones miss WCAG AA on
+  // comments and keywords
+  markdown: {
+    externalLinks: true,
+    ...markdown,
+    code: {
+      ...markdown?.code,
+      theme: {
+        dark: "github-dark-high-contrast",
+        light: "github-light-high-contrast",
+        ...markdown?.code?.theme,
+      },
+    },
+  },
   navigation: {
     repo: true,
     ...navigation,

package/src/blume/header-search.astro

@@ -2,13 +2,21 @@
 import Search from "blume/components/layout/Search.astro";
 import { SOCIAL_ICONS } from "blume/components/layout/footer-socials.ts";
 import data from "blume:data";
+import ThemePicker from "./theme-picker.astro";
+
+/**
+ * `themes` and `defaultTheme` go to the theme picker; everything else Blume
+ * passes goes to its search.
+ */
+const { themes, defaultTheme, ...searchProps } = Astro.props;
 
 const repoUrl = data.config.repoUrl;
 
 const github = SOCIAL_ICONS.github;
 ---
 
-<Search {...Astro.props} />
+<Search {...searchProps} />
+<ThemePicker themes={themes} defaultTheme={defaultTheme} />
 {
   repoUrl && (
     <a

package/src/blume/home-banner.astro

@@ -32,7 +32,7 @@ const description = page.description ?? data.config.description;
 <style>
   /* Set --home-banner-logo-size, --home-banner-height,
      --home-banner-background or --home-banner-background-dark in the site's
-     theme.css to resize or recolour the banner. */
+     theme.css to resize or recolor the banner. */
   .home-banner {
     position: relative;
     overflow: hidden;

package/src/blume/theme-picker.astro

@@ -0,0 +1,226 @@
+---
+/**
+ * Picks the color mode, Darker included, and optionally the Groundwork
+ * theme. Blume's own toggle still switches light and dark; this keeps in step
+ * with it. Theme choices need `@timmo001/docs-kit/blume/themes/all.css`.
+ * The controls are Groundwork's `gw-select` and `gw-segmented`, styled by the
+ * Groundwork theme tokens imported here.
+ */
+import "@timmo001/groundwork-tokens/themes.css";
+
+interface Props {
+  /** Themes to offer, in order. Leave out to offer the mode only. */
+  themes?: readonly { id: string; name: string }[];
+  /** The theme the site's own `theme.css` imports, shown when none is picked. */
+  defaultTheme?: string;
+}
+
+const { themes = [], defaultTheme = "base" } = Astro.props;
+
+// MDI's sunny, waning crescent and night icons
+const modes = [
+  {
+    value: "light",
+    label: "Light",
+    icon: "M12,7A5,5 0 0,1 17,12A5,5 0 0,1 12,17A5,5 0 0,1 7,12A5,5 0 0,1 12,7M12,9A3,3 0 0,0 9,12A3,3 0 0,0 12,15A3,3 0 0,0 15,12A3,3 0 0,0 12,9M12,2L14.39,5.42C13.65,5.15 12.84,5 12,5C11.16,5 10.35,5.15 9.61,5.42L12,2M3.34,7L7.5,6.65C6.9,7.16 6.36,7.78 5.94,8.5C5.5,9.24 5.25,10 5.11,10.79L3.34,7M3.36,17L5.12,13.23C5.26,14 5.53,14.78 5.95,15.5C6.37,16.24 6.91,16.86 7.5,17.37L3.36,17M20.65,7L18.88,10.79C18.74,10 18.47,9.23 18.05,8.5C17.63,7.78 17.1,7.15 16.5,6.64L20.65,7M20.64,17L16.5,17.36C17.09,16.85 17.62,16.22 18.04,15.5C18.46,14.77 18.73,14 18.87,13.21L20.64,17M12,22L9.59,18.56C10.33,18.83 11.14,19 12,19C12.82,19 13.63,18.83 14.37,18.56L12,22Z",
+  },
+  {
+    value: "dark",
+    label: "Dark",
+    icon: "M2 12A10 10 0 0 0 15 21.54A10 10 0 0 1 15 2.46A10 10 0 0 0 2 12Z",
+  },
+  {
+    value: "darker",
+    label: "Darker",
+    icon: "M17.75,4.09L15.22,6.03L16.13,9.09L13.5,7.28L10.87,9.09L11.78,6.03L9.25,4.09L12.44,4L13.5,1L14.56,4L17.75,4.09M21.25,11L19.61,12.25L20.2,14.23L18.5,13.06L16.8,14.23L17.39,12.25L15.75,11L17.81,10.95L18.5,9L19.19,10.95L21.25,11M18.97,15.95C19.8,15.87 20.69,17.05 20.16,17.8C19.84,18.25 19.5,18.67 19.08,19.07C15.17,23 8.84,23 4.94,19.07C1.03,15.17 1.03,8.83 4.94,4.93C5.34,4.53 5.76,4.17 6.21,3.85C6.96,3.32 8.14,4.21 8.06,5.04C7.79,7.9 8.75,10.87 10.95,13.06C13.14,15.26 16.1,16.22 18.97,15.95M17.33,17.97C14.5,17.81 11.7,16.64 9.53,14.5C7.36,12.31 6.2,9.5 6.04,6.68C3.23,9.82 3.34,14.64 6.35,17.66C9.37,20.67 14.19,20.78 17.33,17.97Z",
+  },
+];
+---
+
+<script is:inline>
+  (() => {
+    const root = document.documentElement;
+
+    const read = (key) => {
+      try {
+        return localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    };
+
+    const apply = () => {
+      const theme = read("gw-docs-theme");
+
+      if (theme) root.dataset.gwDocsTheme = theme;
+      else delete root.dataset.gwDocsTheme;
+
+      if (read("gw-darker") === "1" && root.dataset.theme === "dark") {
+        root.setAttribute("data-gw-darker", "");
+      } else {
+        root.removeAttribute("data-gw-darker");
+      }
+    };
+
+    apply();
+    document.addEventListener("astro:after-swap", apply);
+  })();
+</script>
+
+<div
+  class="gw-theme-picker"
+  data-gw-theme-picker
+  data-default-theme={defaultTheme}
+  data-gw-theme={defaultTheme}
+>
+  {
+    themes.length > 0 && (
+      <gw-select
+        data-gw-theme-select
+        label="Theme"
+        inline-label
+        search="never"
+        options={JSON.stringify(themes.map((theme) => ({ value: theme.id, label: theme.name })))}
+      />
+    )
+  }
+  <gw-segmented
+    data-gw-mode-select
+    label="Color mode"
+    labels="hide"
+    options={JSON.stringify(modes)}></gw-segmented>
+</div>
+
+<script>
+  import { GwSegmented } from "@timmo001/groundwork-ui/gw-segmented.ts";
+  import { GwSelect } from "@timmo001/groundwork-ui/gw-select.ts";
+
+  const root = document.documentElement;
+
+  const save = (key: string, value: string | null) => {
+    try {
+      if (value === null) localStorage.removeItem(key);
+      else localStorage.setItem(key, value);
+    } catch {
+      // Storage can be blocked; the choice then lasts for the page.
+    }
+  };
+
+  const currentMode = () =>
+    root.dataset.theme !== "dark"
+      ? "light"
+      : root.hasAttribute("data-gw-darker")
+        ? "darker"
+        : "dark";
+
+  const sync = () => {
+    for (const picker of document.querySelectorAll("div[data-gw-theme-picker]")) {
+      if (!(picker instanceof HTMLElement)) continue;
+
+      const theme = root.dataset.gwDocsTheme ?? picker.dataset.defaultTheme ?? "";
+      const mode = currentMode();
+
+      // The controls are Groundwork components, so the picker carries the
+      // page's theme and mode for them to follow
+      picker.dataset.gwTheme = theme;
+      picker.dataset.gwMode = mode;
+
+      for (const control of picker.querySelectorAll("gw-select, gw-segmented")) {
+        if (control instanceof GwSegmented) control.value = mode;
+        else if (control instanceof GwSelect) control.value = theme;
+      }
+    }
+  };
+
+  document.addEventListener("change", (event) => {
+    const target = event.target;
+
+    if (!(target instanceof GwSelect || target instanceof GwSegmented)) return;
+
+    // Theme and mode change the whole page, so they crossfade where the
+    // browser has View Transitions and motion isn't reduced.
+    const transition = (change: () => void) => {
+      const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+      if (document.startViewTransition === undefined || reduced) change();
+      else document.startViewTransition(change).ready.catch(() => undefined);
+    };
+
+    if (target.matches("[data-gw-mode-select]")) {
+      const dark = target.value !== "light";
+      const value = target.value;
+
+      transition(() => {
+        root.dataset.theme = dark ? "dark" : "light";
+        root.toggleAttribute("data-gw-darker", value === "darker");
+      });
+
+      save("blume-theme", dark ? "dark" : "light");
+      save("gw-darker", value === "darker" ? "1" : null);
+    }
+
+    if (target.matches("[data-gw-theme-select]")) {
+      const value = target.value;
+
+      transition(() => {
+        root.dataset.gwDocsTheme = value;
+      });
+
+      save("gw-docs-theme", value);
+    }
+  });
+
+  // Blume's toggle flips data-theme; going light ends Darker.
+  new MutationObserver(() => {
+    if (root.dataset.theme !== "dark" && root.hasAttribute("data-gw-darker")) {
+      root.removeAttribute("data-gw-darker");
+      save("gw-darker", null);
+    }
+
+    sync();
+  }).observe(root, {
+    attributes: true,
+    attributeFilter: ["data-theme", "data-gw-darker", "data-gw-docs-theme"],
+  });
+
+  sync();
+
+  document.addEventListener("astro:after-swap", sync);
+</script>
+
+<style>
+  /* Gaps leave room for the focus ring, which sits outside each control */
+  .gw-theme-picker {
+    display: inline-flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: 0.625rem;
+    margin-inline: 0.25rem;
+  }
+
+  /* Keep the room the controls take once they upgrade, so the header
+     doesn't move */
+  .gw-theme-picker:has(:not(:defined)) {
+    min-inline-size: 16.75rem;
+    min-block-size: 2.5rem;
+  }
+
+  /* The picker's mode toggle replaces Blume's own light and dark button */
+  :global([data-blume-header]:has(.gw-theme-picker) [data-blume-theme-toggle]) {
+    display: none;
+  }
+
+  /* The components draw on Groundwork's surface, so the header's own
+     background shows through instead */
+  .gw-theme-picker {
+    background: transparent;
+    color: inherit;
+  }
+
+  /* Phones keep the header to one row, so the select shows only its value */
+  @media (max-width: 40rem) {
+    .gw-theme-picker :global(.gw-select-inline-label) {
+      display: none;
+    }
+  }
+</style>

package/src/blume/theme.css

@@ -12,7 +12,7 @@
 }
 
 /* Keep the "On this page" rail beside the content instead of at the far right
-   edge: centre the content and rail, with equal space either side. The content
+   edge: center the content and rail, with equal space either side. The content
    column is the content width plus main's 2.5rem padding either side.
    home-banner.astro works out its full-width bleed from these columns. */
 @media (min-width: 80rem) {