@brandon_m_behring/book-scaffold-astro 4.25.2 → 4.26.0

package/src/lib/nav-href.ts

@@ -0,0 +1,100 @@
+/**
+ * src/lib/nav-href.ts — pure route-href resolver (#80 multi-book navigation).
+ *
+ * No `astro:content` import (mirrors chapter-sort.ts) so tsup can include it in
+ * the DTS bundle without dragging Astro virtual modules into the build graph.
+ * The nav components (Sidebar, ChapterNav, NavContent, …) call these helpers
+ * instead of hardcoding the single-book `/chapters/<id>/` URL shape — so ONE set
+ * of components serves both a single-book site (the default pattern) and a
+ * multi-book consumer whose chapters render at `/<book>/<slug>/`.
+ *
+ * Patterns are base-relative TOKEN STRINGS (a resolver *function* could not
+ * survive the book-config virtual module's `JSON.stringify`, so the config
+ * surface is a declarative string resolved here):
+ *   :id   → entry.id verbatim, slashes preserved          e.g. 'kg/01-intro'
+ *   :book → the entry's book name (see `bookField`), or '' e.g. 'kg'
+ *   :slug → entry.id with a leading '<book>/' stripped     e.g. '01-intro'
+ * BASE_URL is applied here, so patterns are written base-relative (lead '/').
+ *
+ * Defaults reproduce the single-book behavior BYTE-FOR-BYTE:
+ *   chapterRoute   = '/chapters/:id/'  → `${base}chapters/${id}/`
+ *   bookField      = 'book'   (academic/tools schemas have no `book` → bookOf
+ *                              returns null → "show all chapters", today's nav)
+ *   apparatusRoute = '/:route/'        → `${base}<route>/`
+ */
+
+/** Minimal shape the resolver needs from a chapter collection entry. */
+export interface ChapterLike {
+  id: string;
+  data: Record<string, unknown>;
+}
+
+/** Normalize a base URL to exactly one trailing slash (`''` → `'/'`). */
+function normBase(baseUrl: string): string {
+  return (baseUrl || '/').replace(/\/*$/, '/');
+}
+
+/** Replace `:book` / `:slug` / `:route` / `:id` tokens; `\b` keeps each token
+ *  whole, so order is irrelevant and `:id` never matches inside `:identifier`. */
+function fillTokens(pattern: string, tokens: Record<string, string>): string {
+  return pattern.replace(/:(book|slug|route|id)\b/g, (_m, k: string) => tokens[k] ?? '');
+}
+
+/**
+ * The entry's book name from `data[bookField]`, or `null` when absent/blank.
+ * Single-book schemas (academic/tools/minimal) have no such field → `null`,
+ * which callers read as "this is the only book — show every chapter".
+ */
+export function bookOf(entry: ChapterLike, bookField = 'book'): string | null {
+  const v = entry.data[bookField];
+  return typeof v === 'string' && v.length > 0 ? v : null;
+}
+
+/** `entry.id` with a leading `'<book>/'` stripped (multi-book) or unchanged. */
+export function slugOf(entry: ChapterLike, bookField = 'book'): string {
+  const book = bookOf(entry, bookField);
+  return book && entry.id.startsWith(`${book}/`) ? entry.id.slice(book.length + 1) : entry.id;
+}
+
+/** Resolve a chapter entry to a base-prefixed href via the `chapterRoute` pattern. */
+export function chapterHref(
+  entry: ChapterLike,
+  pattern = '/chapters/:id/',
+  baseUrl = '/',
+  bookField = 'book',
+): string {
+  const path = fillTokens(pattern, {
+    id: entry.id,
+    book: bookOf(entry, bookField) ?? '',
+    slug: slugOf(entry, bookField),
+  }).replace(/\/{2,}/g, '/').replace(/^\//, '');   // collapse empties (absent token) — never a protocol-relative //
+  return normBase(baseUrl) + path;
+}
+
+/**
+ * Resolve a per-book apparatus route (glossary / practice-exam / flashcards /
+ * answers) to a base-prefixed href via the `apparatusRoute` pattern.
+ */
+export function apparatusHref(
+  route: string,
+  book: string | null,
+  pattern = '/:route/',
+  baseUrl = '/',
+): string {
+  const path = fillTokens(pattern, { route, book: book ?? '' })
+    .replace(/\/{2,}/g, '/')   // F2 (#80): an absent :book must collapse, never yield a protocol-relative //
+    .replace(/^\//, '');
+  return normBase(baseUrl) + path;
+}
+
+/** Whether `entry` is the page at `currentPath` (trailing-slash tolerant). */
+export function isCurrentChapter(
+  entry: ChapterLike,
+  currentPath: string,
+  pattern = '/chapters/:id/',
+  baseUrl = '/',
+  bookField = 'book',
+): boolean {
+  const href = chapterHref(entry, pattern, baseUrl, bookField);
+  return currentPath === href || currentPath === href.replace(/\/$/, '');
+}

package/styles/callouts.css

@@ -192,7 +192,9 @@
   padding: 0 var(--space-2);
   border: 1px solid var(--callout-worked);
   border-radius: var(--radius-sm);
-  color: var(--callout-worked);
+  /* v4.26.0 (#80, a11y): chip TEXT uses the high-contrast heading color (the
+   * accent stays as the border) — the accent as small text failed WCAG-AA 4.5:1. */
+  color: var(--color-heading);
 }
 
 /* Gold — YouWillLearn (v4.1.0, #59). Reuses callout-insight (gold) hue;
@@ -233,7 +235,7 @@
   padding: 0 var(--space-2);
   border: 1px solid var(--callout-diagnostic);
   border-radius: var(--radius-sm);
-  color: var(--callout-diagnostic);
+  color: var(--color-heading);   /* a11y: accent as small text failed 4.5:1 (border keeps the hue) */
 }
 .callout-diagnostic .callout-routing {
   font-size: var(--text-sm);
@@ -247,7 +249,7 @@
   cursor: pointer;
   font-weight: 600;
   font-size: var(--text-sm);
-  color: var(--callout-diagnostic);
+  color: var(--color-text);   /* a11y: teal accent as text failed 4.5:1 */
 }
 
 /* PartReview (#111) — Part-level interleaved exercise-review aggregation.
@@ -575,6 +577,8 @@ figure.figure figcaption {
   letter-spacing: 0.04em;
   text-transform: uppercase;
 }
-.practice-tag[data-kind="official"]     { border-color: var(--callout-official); color: var(--callout-official); }
-.practice-tag[data-kind="convergence"]  { border-color: var(--callout-insight); color: var(--callout-insight); }
-.practice-tag[data-kind="practitioner"] { border-color: var(--callout-tip); color: var(--callout-tip); }
+/* a11y (v4.26.0, #80): hue via the border; text uses the body color (accent as
+ * small text fails WCAG-AA 4.5:1). */
+.practice-tag[data-kind="official"]     { border-color: var(--callout-official); color: var(--color-text); }
+.practice-tag[data-kind="convergence"]  { border-color: var(--callout-insight);  color: var(--color-text); }
+.practice-tag[data-kind="practitioner"] { border-color: var(--callout-tip);      color: var(--color-text); }

package/styles/layout.css

@@ -31,10 +31,15 @@
 }
 
 /* At 1024px+: pin sidebar to left, main content fills remainder. */
-@media (min-width: 64rem) {
+/* v4.26.0 (#80): the full 3-column (sidebar + Tufte gutter) needs room the
+ * sidebar steals, so it activates at 80rem (1280px) — below that the drawer is
+ * the chapter nav and content runs full-width (the gutter/section-map then fits
+ * in the whole viewport). This is where the gutter genuinely fits beside the
+ * sidebar with the trimmed measures. */
+@media (min-width: 80rem) {
   .layout-with-sidebar {
     display: grid;
-    grid-template-columns: 16rem 1fr;
+    grid-template-columns: 14rem 1fr;   /* trimmed so main+gutter fits beside it */
     grid-template-areas: 'sidebar main';
     min-height: 100vh;
   }
@@ -51,7 +56,7 @@
  * titles. */
 @media (min-width: 90rem) {
   .layout-with-sidebar {
-    grid-template-columns: 18rem 1fr;
+    grid-template-columns: 16rem 1fr;
   }
 }
 
@@ -218,3 +223,89 @@
 .prose[data-layout="wide"] {
   --measure-main: 80ch;
 }
+
+/* ===== Mobile/tablet nav drawer (v4.26.0, #80) =====
+ * Below the sidebar breakpoint (64rem) the left Sidebar is display:none — this
+ * is the navigation in that range: a hamburger in the chrome row toggles a
+ * slide-in drawer reusing NavContent (the same book-scoped nav source as the
+ * sidebar). No-JS baseline: `:target` opens it (the toggle is <a href="#nav-drawer">);
+ * the inline controller in Base.astro enhances it with focus-trap + ESC + body
+ * scroll-lock. Hidden at ≥64rem, where the persistent sidebar is the nav. The
+ * ≥64rem gutter-fit (sidenote/section-map overflow) is a separate fix. */
+@media (min-width: 80rem) {
+  .nav-toggle,
+  .nav-drawer {
+    display: none;
+  }
+}
+
+@media (max-width: 79.98rem) {
+  .nav-drawer {
+    position: fixed;
+    inset: 0;
+    z-index: var(--z-drawer, 30);
+    visibility: hidden;
+  }
+  .nav-drawer.is-open,
+  .nav-drawer:target {
+    visibility: visible;
+  }
+  .nav-drawer-backdrop {
+    position: absolute;
+    inset: 0;
+    border: 0;
+    background: rgba(0, 0, 0, 0.5);
+    opacity: 0;
+    transition: opacity 200ms ease;
+  }
+  .nav-drawer-panel {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    width: min(20rem, 85vw);
+    max-height: 100vh;
+    overflow-y: auto;
+    background: var(--color-bg-subtle);
+    border-right: 1px solid var(--color-border);
+    padding: var(--space-6) var(--space-5);
+    transform: translateX(-100%);
+    transition: transform 220ms ease;
+  }
+  .nav-drawer.is-open .nav-drawer-panel,
+  .nav-drawer:target .nav-drawer-panel {
+    transform: translateX(0);
+  }
+  .nav-drawer.is-open .nav-drawer-backdrop,
+  .nav-drawer:target .nav-drawer-backdrop {
+    opacity: 1;
+  }
+  .nav-drawer-dismiss {
+    position: absolute;
+    top: var(--space-3);
+    inset-inline-end: var(--space-3);
+    z-index: 1;
+  }
+}
+
+/* Body scroll-lock while the drawer is open (class toggled by the controller). */
+.nav-drawer-locked {
+  overflow: hidden;
+}
+
+/* ===== Gutter-fit (v4.26.0, #80) =====
+ * The Tufte right-gutter (.section-map scrollspy + .sidenote / .column-margin /
+ * .margin-figure floats) used to size its main+gutter measure against the FULL
+ * viewport, ignoring that a left sidebar steals 14–16rem — so the negative-margin
+ * float landed PAST the viewport at 1024px AND 1440px. The fix is in tokens.css:
+ * the `--measure-main` / `--measure-side` tiers are trimmed (60/20ch → 66/20ch →
+ * 78/24ch) and the sidebar to 14/16rem, so `main + gutter ≤ layout-main` (viewport
+ * − sidebar) at every desktop width. The gutter scrollspy now FITS beside the
+ * sidebar instead of overflowing — no suppression, no breakpoint games. Verified
+ * scrollWidth == clientWidth across the responsive audit harness. */
+
+@media (prefers-reduced-motion: reduce) {
+  .nav-drawer-panel,
+  .nav-drawer-backdrop {
+    transition: none;
+  }
+}

package/styles/section-map.css

@@ -30,7 +30,11 @@
   display: none !important;
 }
 
-@media (min-width: 64rem) {
+/* v4.26.0 (#80): the gutter scrollspy floats only alongside the sidebar (≥80rem,
+ * matching layout.css) — below that the drawer is the chapter nav and the in-flow
+ * collapsed ChapterTOC is the "on this page". This keeps the negative-margin gutter
+ * from overflowing the viewport in the cramped 64–80rem band (iPad-landscape). */
+@media (min-width: 80rem) {
   /* Sidenote-aware handshake (#151). The gutter map and <Sidenote>s float into
    * the SAME ~28ch right column (layout.css), so they cannot coexist there:
    *   - A chapter WITH sidenotes → the gutter belongs to the sidenotes; suppress

package/styles/tokens.css

@@ -106,8 +106,8 @@
    * the breakpoints are encoded as literal rem values in the media queries
    * (90rem ≈ 1440px, 120rem ≈ 1920px).
    */
-  --measure-main: 65ch;        /* default: laptop-friendly typographic measure */
-  --measure-side: 28ch;        /* right-margin sidenote column (desktop) */
+  --measure-main: 60ch;        /* default: main+gutter fits beside the sidebar at ≥64rem (v4.26.0, #80) */
+  --measure-side: 20ch;        /* right-margin sidenote / section-map column */
   --breakpoint-narrow: 48rem;  /* ~768px — mobile fold (sidenotes inline) */
   --breakpoint-wide: 90rem;    /* ~1440px — wide-desktop tier */
   --breakpoint-ultrawide: 120rem; /* ~1920px — ultrawide tier */
@@ -134,30 +134,34 @@
    * same visual language as prose callouts. Dark mode overrides below. */
   --astro-code-foreground:              var(--color-text);
   --astro-code-background:              var(--color-code-bg);
-  --astro-code-token-constant:          var(--warm-rose);
-  --astro-code-token-string:            var(--warm-green);
-  --astro-code-token-string-expression: var(--warm-green);
+  /* a11y (v4.26.0, #80): saturated accents fail 4.5:1 on the light code bg →
+   * darken (the dark-theme overrides below keep their lighter variants). */
+  --astro-code-token-constant:          color-mix(in srgb, var(--warm-rose) 60%, black);
+  --astro-code-token-string:            color-mix(in srgb, var(--warm-green) 55%, black);
+  --astro-code-token-string-expression: color-mix(in srgb, var(--warm-green) 55%, black);
   --astro-code-token-comment:           var(--color-text-muted);
-  --astro-code-token-keyword:           var(--warm-plum);
+  --astro-code-token-keyword:           color-mix(in srgb, var(--warm-plum) 60%, black);
   --astro-code-token-parameter:         var(--warm-blue);
-  --astro-code-token-function:          var(--warm-gold);
+  --astro-code-token-function:          color-mix(in srgb, var(--warm-gold) 55%, black);  /* a11y: warm-gold alone is 2.46:1 on the code bg (dark-mode override below) */
   --astro-code-token-punctuation:       var(--color-text-muted);
   --astro-code-token-link:              var(--color-link);
 }
 
-/* Tier 2: wide desktop (1440px+). Main 80ch, sidenote 24ch. */
+/* Tier 2: wide desktop (1440px+). v4.26.0 (#80): main 70ch + gutter 22ch keeps
+ * the main+gutter measure inside `layout-main` (viewport − 16rem sidebar) so the
+ * Tufte gutter/section-map fits beside the sidebar instead of overflowing. */
 @media (min-width: 90rem) {
   :root {
-    --measure-main: 80ch;
-    --measure-side: 24ch;
+    --measure-main: 66ch;
+    --measure-side: 20ch;
   }
 }
 
-/* Tier 3: ultrawide (1920px+). Main 90ch, sidenote 26ch. */
+/* Tier 3: ultrawide (1920px+). Room to widen both again and still fit. */
 @media (min-width: 120rem) {
   :root {
-    --measure-main: 90ch;
-    --measure-side: 26ch;
+    --measure-main: 78ch;
+    --measure-side: 24ch;
   }
 }
 

package/styles/typography.css

@@ -196,3 +196,19 @@ th {
   color: var(--warm-blue);
   font-style: italic;
 }
+
+/* ===== Narrow-viewport overflow guards (v4.26.0, #80) =====
+ * Defensive: stop a long INLINE-code identifier (e.g. a dotted module path) or a
+ * wide table from forcing horizontal PAGE scroll on a phone. `overflow-wrap:
+ * anywhere` only breaks when a token would otherwise overflow, so normal prose is
+ * untouched; fenced blocks are excluded (`:not(pre) > code`) so they keep their
+ * own `pre { overflow-x: auto }` inner scroll. Wide tables scroll within their own
+ * box (`display:block; overflow-x:auto`) instead of stretching the page. */
+:not(pre) > code {
+  overflow-wrap: anywhere;
+}
+.prose > table {
+  display: block;
+  overflow-x: auto;
+  max-width: 100%;
+}