@writedocs/generator 0.1.0

package/src/scripts/sidebar-scroll.ts

@@ -0,0 +1,65 @@
+// ClientRouter swaps <body> (and everything in it) on every navigation -
+// [...slug].astro re-renders Sidebar.astro/NavTree.astro fresh per page,
+// since the active-link highlight and each collapsible group's open/closed
+// state are computed server-side from the *new* URL (see NavTree.astro's
+// own comment on `open = isActive || navTreeContainsSlug(...)`). That's
+// exactly the behavior a reader wants for highlighting/auto-expanding the
+// right branch - but it also means .wd-sidebar is a brand-new DOM node on
+// every navigation, with its own independent scroll position (it's
+// `overflow-y: auto`, not the window) starting back at 0, same as a full
+// page reload would. For a page nested deep in a long nav tree, that reads
+// as the sidebar "jumping back to the top" on every click - disorienting,
+// since the reader loses their place in the tree they were navigating.
+// This module carries the old sidebar's scroll offset across the swap and
+// re-applies it to the new one, without touching anything about how the
+// highlight/expand state itself is computed (that server-rendered-per-page
+// behavior stays exactly as it is - only the scroll position is preserved).
+//
+// A module-scoped variable (not sessionStorage) is enough: this script's
+// own module graph is loaded once and never re-evaluated by a ClientRouter
+// swap (only <body>'s content is replaced), so the value naturally
+// survives from one navigation to the next without needing to serialize it
+// anywhere. It deliberately does NOT survive a real full-page reload
+// (Cmd+R/F5) - resetting to the top on an actual reload is ordinary,
+// expected browser behavior, not something this needs to fight.
+let savedScrollTop: number | null = null;
+
+/** The sidebar rendered inline in the page (inside `.wd-sidebar-col`, for
+ *  desktop widths) and the identical copy reused inside MobileMenu.astro's
+ *  own drawer both carry the same `.wd-sidebar` class and both always
+ *  exist in the DOM at once (see MobileMenu.astro's own comment) - a media
+ *  query just hides whichever one isn't the current layout's. Picking
+ *  "whichever one actually has a real layout box" is enough to find the
+ *  one the reader could actually see and scroll, without needing to ask
+ *  which layout mode is active. Returns null on a page with no sidebar at
+ *  all (`mode: custom`/`blank`, see BaseLayout.astro) - both copies are
+ *  simply absent there. */
+function visibleSidebar(): HTMLElement | null {
+  const candidates = document.querySelectorAll<HTMLElement>('.wd-sidebar');
+  for (const el of candidates) {
+    if (el.offsetWidth > 0 || el.offsetHeight > 0) return el;
+  }
+  return null;
+}
+
+/** Reads the current scroll offset right before ClientRouter tears down
+ *  the old page's DOM - `astro:before-swap` is the last moment the old
+ *  `.wd-sidebar` is still attached and its `scrollTop` still means
+ *  anything. */
+export function saveSidebarScroll() {
+  const sidebar = visibleSidebar();
+  savedScrollTop = sidebar ? sidebar.scrollTop : null;
+}
+
+/** Re-applies the saved offset onto the new page's own `.wd-sidebar`.
+ *  Bound to `astro:after-swap` (fires synchronously right after the swap,
+ *  before the browser's next paint - see BaseLayout.astro's own
+ *  `wdApplyStoredPreferences` for the identical timing rationale) rather
+ *  than the later `astro:page-load`, so the sidebar never visibly flashes
+ *  at the top before jumping to the preserved position. */
+export function restoreSidebarScroll() {
+  if (savedScrollTop === null) return;
+  const sidebar = visibleSidebar();
+  if (sidebar) sidebar.scrollTop = savedScrollTop;
+  savedScrollTop = null;
+}

package/src/scripts/theme-toggle.ts

@@ -0,0 +1,35 @@
+// Wires up every `.wd-theme-toggle` button on the page - not just the
+// first. The real topbar (TopBar.astro) and the mobile drawer's own header
+// (MobileMenu.astro) each render their own copy of this button, so both
+// stay in sync for free: [data-theme] on <html>, not per-button JS state,
+// is what actually drives which icon each button shows - they just need
+// the same click handler, independently guarded (per button, via
+// dataset.wdInit) so a re-run (e.g. astro:page-load on a client-side nav,
+// or simply being imported and called by more than one component) never
+// double-binds any single button.
+export function initThemeToggle(root: ParentNode) {
+  const btns = root.querySelectorAll<HTMLButtonElement>('.wd-theme-toggle');
+  btns.forEach((btn) => {
+    if (btn.dataset.wdInit) return;
+    btn.dataset.wdInit = 'true';
+    btn.addEventListener('click', () => {
+      const next = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
+      document.documentElement.dataset.theme = next;
+      try {
+        localStorage.setItem('wd-theme', next);
+      } catch (e) {
+        // localStorage unavailable (private browsing, etc.) - theme still
+        // applies for the current page, just won't persist.
+      }
+      // Mermaid diagrams are rendered to static SVG once (baked with
+      // whichever theme was active at render time), unlike Shiki code
+      // blocks which swap colors live via CSS custom properties - so a
+      // theme change needs to trigger an actual re-render, not just a CSS
+      // update. [...slug].astro's initMermaid() (article content, not this
+      // file) listens for this rather than living here itself, since the
+      // diagrams themselves are article content and this file has no
+      // reason to know mermaid exists.
+      document.dispatchEvent(new CustomEvent('wd:theme-change', { detail: { theme: next } }));
+    });
+  });
+}

package/src/scripts/topbar-offset.ts

@@ -0,0 +1,141 @@
+// The sticky topbar's actual rendered height varies - one row vs two (the
+// tabs/global-dropdowns row only exists when there's something to put in
+// it - see TopBar.astro's own `showSecondRow`), and `topbar.links`
+// wrapping onto its own row below ~860px (topbar.css). Every place that
+// needs to offset content below this sticky chrome - heading
+// `scroll-margin-top` ([...slug].astro), and the sidebar/TOC/API-
+// reference-panel's own sticky `top`/`max-height` (Sidebar.astro,
+// TableOfContents.astro, ApiReferencePanel.astro) - used to hardcode a
+// single `5rem` guess that only ever matched the simplest case (one
+// topbar row): silently wrong - a heading landing partly under the
+// topbar on an anchor jump, or a sliver of dead space/slight overlap on
+// the sticky columns - the moment a site's topbar grew a second row.
+// This measures the real thing instead and exposes it as
+// `--wd-topbar-offset` on <html>, which every one of those hardcoded
+// values now reads from via `var(--wd-topbar-offset, 5rem)` - `5rem`
+// stays as that var()'s own fallback, for the brief instant before this
+// script's first measurement runs.
+//
+// writedocs.json's dismissible `banner` (BaseLayout.astro, above the topbar)
+// isn't `position: sticky` itself - it scrolls away normally, unlike
+// `.wd-topbar` (`position: sticky; top: 0`) right below it. Measuring
+// just the topbar's own height used to be enough on the (wrong)
+// assumption that nothing reads this offset until scroll has already
+// carried the banner out of view - true for the heading
+// `scroll-margin-top` case (a scroll-into-view only settles once
+// something has actually been scrolled), but not for the sidebar/TOC/
+// API-reference-panel's sticky `max-height` (Sidebar.astro,
+// TableOfContents.astro, ApiReferencePanel.astro), which reads this
+// offset immediately on page load, banner and all - a tall enough column
+// there would overflow the viewport by exactly the banner's own height
+// until the reader scrolled past it. Reading the topbar's own *bottom*
+// edge (`getBoundingClientRect().bottom`) instead of its height fixes
+// this for free, with no separate banner-specific case to maintain: while
+// the banner is still in normal flow above the not-yet-stuck topbar, that
+// bottom edge already equals banner height + topbar height; once scroll
+// has carried the banner away and the topbar is genuinely stuck at
+// `top: 0`, it settles back to exactly the topbar's own height - the
+// same value this used to hardcode from `.height` alone. The only added
+// cost is that this now needs to be re-measured on scroll too, not just
+// resize (below), since it changes continuously while the banner is
+// still scrolling past.
+
+function applyOffset(topbar: HTMLElement) {
+  let bottom = topbar.getBoundingClientRect().bottom;
+  // .wd-shell (BaseLayout.astro) carries its own padding-top - breathing
+  // room between the topbar and the three columns below it (base.css).
+  // The sidebar/TOC/API-reference-panel's sticky top/max-height (the
+  // main reason this function exists - see the file-level comment) needs
+  // this folded in too: those columns' *natural*, not-yet-stuck flow
+  // position starts at the bottom of that padding, not at the topbar's
+  // own bottom edge alone, so a max-height computed from the smaller
+  // value left them tall enough to overshoot the viewport by exactly
+  // this padding - same shape of bug as the banner one above, just a
+  // fixed ~12px instead of a scrolling one. Folding it in here (instead
+  // of, say, only in Sidebar/TableOfContents/ApiReferencePanel's own
+  // CSS) keeps every reader of this one variable consistent, at the cost
+  // of very slightly over-padding the scroll-margin-top use case above -
+  // an extra dozen pixels of clearance above a jumped-to heading is
+  // unnoticeable; overflowing the viewport is not.
+  const shell = document.querySelector<HTMLElement>('.wd-shell');
+  if (shell) {
+    const shellPaddingTop = parseFloat(getComputedStyle(shell).paddingTop);
+    if (!Number.isNaN(shellPaddingTop)) bottom += shellPaddingTop;
+  }
+  // A zero (or negative, impossible but defensive) reading means the
+  // topbar hasn't actually been laid out yet - leave the CSS var()
+  // fallback in place rather than pin a bogus 0px offset that would
+  // itself need correcting a moment later.
+  if (bottom > 0) {
+    document.documentElement.style.setProperty('--wd-topbar-offset', `${bottom}px`);
+  }
+}
+
+/** Corrects the browser's own initial scroll-to-fragment jump. The
+ *  browser scrolls a same-page #hash target into view as part of initial
+ *  navigation - which can happen before this deferred module script ever
+ *  runs, using whatever `scroll-margin-top` is in the CSS at that moment
+ *  (the `5rem` fallback, not yet the real measured value once a site's
+ *  topbar is taller than that). Re-running `scrollIntoView()` here -
+ *  after `--wd-topbar-offset` is already set correctly - repeats that
+ *  same browser-native, scroll-margin-aware scroll with the right value,
+ *  once. `behavior: 'auto'` (this codebase never sets a global
+ *  `scroll-behavior: smooth` that would turn this into a visible
+ *  animation) - this corrects a wrong landing spot, it isn't itself a
+ *  user-facing scroll action. */
+function correctInitialHashScroll() {
+  if (!location.hash) return;
+  let target: HTMLElement | null;
+  try {
+    target = document.getElementById(decodeURIComponent(location.hash.slice(1)));
+  } catch {
+    return; // malformed %-escape in the hash - nothing sane to scroll to
+  }
+  target?.scrollIntoView({ block: 'start', behavior: 'auto' });
+}
+
+// Module-scoped rather than per-call: only one topbar is ever live at a
+// time, so each astro:page-load re-run should replace the previous
+// ResizeObserver (and scroll listener, below) entirely, not accumulate a
+// new one on top of the last - the dataset.wdInit-guard pattern this
+// codebase uses elsewhere doesn't apply here, since that pattern is for
+// re-binding listeners onto elements that might persist across a re-run,
+// and the topbar itself never does (ClientRouter swaps <body> - see
+// BaseLayout's own comment on swapRootAttributes()). The scroll listener
+// is bound to `window`, which *does* persist across that swap unlike the
+// topbar element the ResizeObserver watches - left unremoved, every
+// navigation would add one more, all still firing on every future scroll.
+let observer: ResizeObserver | null = null;
+let scrollHandler: (() => void) | null = null;
+
+export function initTopbarOffset() {
+  observer?.disconnect();
+  if (scrollHandler) window.removeEventListener('scroll', scrollHandler);
+
+  const topbar = document.querySelector<HTMLElement>('.wd-topbar');
+  if (!topbar) return; // mode: blank pages render no topbar at all
+
+  applyOffset(topbar);
+  correctInitialHashScroll();
+
+  // Font loading or topbar.links wrapping on window resize can both
+  // change the topbar's real height after this first measurement.
+  observer = new ResizeObserver(() => applyOffset(topbar));
+  observer.observe(topbar);
+
+  // Keeps the offset correct while a banner (if any) scrolls past above
+  // the not-yet-stuck topbar (see applyOffset's own comment on reading
+  // .bottom instead of .height) - rAF-throttled to one measurement per
+  // frame rather than one per scroll event, same as any other scroll-
+  // driven layout read.
+  let ticking = false;
+  scrollHandler = () => {
+    if (ticking) return;
+    ticking = true;
+    requestAnimationFrame(() => {
+      applyOffset(topbar);
+      ticking = false;
+    });
+  };
+  window.addEventListener('scroll', scrollHandler, { passive: true });
+}

package/src/styles/global.css

@@ -0,0 +1,18 @@
+/* Wires Tailwind's utility classes into every writedocs build. Nothing in
+   writedocs' own components (BaseLayout, NavTree, Sidebar, Card, etc.)
+   uses Tailwind - they keep their existing scoped <style> blocks built
+   on the --wd-* CSS variables, since those already support per-site
+   writedocs.json theming (colors, dark mode) at render time. This import
+   just makes Tailwind's utilities available for custom/future content,
+   e.g. hand-authored MDX.
+
+   Deliberately importing theme + utilities only, NOT the full
+   "tailwindcss" entrypoint - that also pulls in Tailwind's preflight
+   (a browser-default CSS reset), which sets h1-h6's font-size/
+   font-weight to `inherit`. MDX content headings here rely on the
+   browser's own default heading styles (nothing in this codebase sets
+   them explicitly), so preflight was silently collapsing every
+   heading down to plain paragraph text. Skipping it keeps utility
+   classes available with zero effect on existing unstyled elements. */
+@import "tailwindcss/theme.css";
+@import "tailwindcss/utilities.css";