@writedocs/generator 0.8.0 → 0.9.0

package/src/pages/[...slug].md.ts

@@ -2,7 +2,7 @@ import { getCollection, type CollectionEntry } from 'astro:content';
 import fs from 'node:fs';
 import path from 'node:path';
 import type { APIRoute } from 'astro';
-import { loadDocsConfig, normalizeEntryId, findAllPages } from '../lib/config';
+import { loadDocsConfig, normalizeEntryId, findAllPages, contextMenuOptions } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
 import { markdownForAgents } from '../lib/agent-markdown.js';
 
@@ -11,10 +11,10 @@ import { markdownForAgents } from '../lib/agent-markdown.js';
 // /guides/foo/ -> /guides/foo.md), serving its untouched MDX/Markdown
 // source instead of rendered HTML - what the "Copy page"/"View as
 // Markdown" menu (CopyPageMenu.astro, wired in from [...slug].astro)
-// links to, and what an LLM fetching that URL directly gets. Gated
-// entirely behind writedocs.json's `contextMenu` field being present (see
-// contextMenuSchema in lib/config.ts) - a site that hasn't opted in gets
-// no .md routes at all, not just a hidden menu.
+// links to, and what an LLM fetching that URL directly gets. On by
+// default, like the menu; writedocs.json `"contextMenu": false` (see
+// contextMenuOptions() in lib/config-schema.ts) leaves out the .md routes
+// too, not just the menu.
 //
 // A literal ".md" filename suffix rather than a `[...slug]` capture
 // covering it: naming the file `[...slug].md.ts` makes Astro treat ".md"
@@ -33,9 +33,9 @@ type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
 export async function getStaticPaths() {
   const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
   const config = loadDocsConfig(contentDir);
-  // No writedocs.json `contextMenu` - feature is off entirely, including these
-  // routes (not just the menu UI - see the file-level comment above).
-  if (!config.contextMenu) return [];
+  // `"contextMenu": false` - the feature is off entirely, these routes
+  // included (not just the menu UI - see the file-level comment above).
+  if (contextMenuOptions(config.contextMenu).length === 0) return [];
 
   const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
   const hasPages = findAllPages(contentDir).length > 0;

package/src/scripts/dropdowns.ts

@@ -4,56 +4,91 @@
 // written for the topbar's own switcher/tab dropdowns, but the same
 // `.wd-dropdown`/`.wd-dropdown-trigger`/`.wd-dropdown-menu`/
 // `.wd-dropdown-menu-panel` shape is now reused by TopBar.astro (switchers,
-// tabs, the small-screen topbar.links ellipsis) and CopyPageMenu.astro, and
-// exported from here so any future component - MobileMenu.astro included,
-// even though it doesn't render any `.wd-dropdown` markup today - can import
-// and call it too without needing to know whether some other component
-// already has.
+// tabs, the small-screen topbar.links ellipsis), CopyPageMenu.astro and
+// ApiLangSelect.astro, and exported from here so any of them can call it
+// without needing to know whether some other component already has.
 //
-// That "might get called more than once per page" scenario is exactly why
-// the two `document`-level listeners at the bottom are behind their own
-// module-level guard, separate from the existing per-trigger
-// `dataset.wdInit` guard: querying `.wd-dropdown` from more than one
-// component's own `<script>` (each already idempotent per-trigger) would,
-// without this, still add a fresh pair of document click/keydown listeners
-// on every single call - harmless individually, but wasteful if it keeps
-// happening across repeated calls (e.g. once per component that imports
-// this, or once per `astro:page-load` firing from more than one place).
+// These are show/hide buttons for a list of links (the W3C's "disclosure"
+// pattern for navigation), not ARIA menus: the button says whether it's
+// open (aria-expanded), the options are ordinary links and buttons that
+// Tab reaches. For the keyboard, on top of that: Down/Up open the list and
+// move between its options (Home/End jump to the ends); Escape closes it
+// and puts focus back on its button; tabbing out of it closes it.
+//
+// The document-level listeners are bound once per page load, and act on
+// whichever dropdowns are open at the time - so they keep working for the
+// ones a client-side navigation brings in.
 let globalListenersBound = false;
 
-export function initDropdowns(root: ParentNode) {
-  const dropdowns = Array.from(root.querySelectorAll<HTMLElement>('.wd-dropdown'));
-  if (dropdowns.length === 0) return;
+const triggerOf = (dropdown: Element) => dropdown.querySelector<HTMLElement>('.wd-dropdown-trigger');
+const optionsOf = (dropdown: Element) =>
+  Array.from(dropdown.querySelectorAll<HTMLElement>('.wd-dropdown-menu a[href], .wd-dropdown-menu button'));
 
-  const closeAll = () => {
-    dropdowns.forEach((d) => {
-      d.classList.remove('open');
-      d.querySelector('.wd-dropdown-trigger')?.setAttribute('aria-expanded', 'false');
-    });
-  };
+function open(dropdown: Element) {
+  closeAll(dropdown);
+  dropdown.classList.add('open');
+  triggerOf(dropdown)?.setAttribute('aria-expanded', 'true');
+}
 
-  dropdowns.forEach((dropdown) => {
-    const trigger = dropdown.querySelector<HTMLButtonElement>('.wd-dropdown-trigger');
+function close(dropdown: Element) {
+  dropdown.classList.remove('open');
+  triggerOf(dropdown)?.setAttribute('aria-expanded', 'false');
+  // Focus on an option that just got hidden would drop to the top of the
+  // page - it goes back to the button instead.
+  const focused = document.activeElement;
+  if (focused && focused !== triggerOf(dropdown) && dropdown.contains(focused)) triggerOf(dropdown)?.focus();
+}
+
+function closeAll(except?: Element) {
+  document.querySelectorAll('.wd-dropdown.open').forEach((d) => {
+    if (d !== except) close(d);
+  });
+}
+
+export function initDropdowns(root: ParentNode) {
+  root.querySelectorAll<HTMLElement>('.wd-dropdown').forEach((dropdown) => {
+    const trigger = triggerOf(dropdown);
     if (!trigger || trigger.dataset.wdInit) return;
     trigger.dataset.wdInit = 'true';
+
     trigger.addEventListener('click', (e) => {
       e.stopPropagation();
-      const isOpen = dropdown.classList.contains('open');
-      closeAll();
-      if (!isOpen) {
-        dropdown.classList.add('open');
-        trigger.setAttribute('aria-expanded', 'true');
+      if (dropdown.classList.contains('open')) close(dropdown);
+      else open(dropdown);
+    });
+
+    dropdown.addEventListener('keydown', (e) => {
+      if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) return;
+      const options = optionsOf(dropdown);
+      if (options.length === 0) return;
+      e.preventDefault();
+      if (!dropdown.classList.contains('open')) open(dropdown);
+      const at = options.indexOf(document.activeElement as HTMLElement);
+      let next: number;
+      if (e.key === 'Home') next = 0;
+      else if (e.key === 'End') next = options.length - 1;
+      else if (at === -1) next = e.key === 'ArrowUp' ? options.length - 1 : 0;
+      else next = Math.min(Math.max(at + (e.key === 'ArrowDown' ? 1 : -1), 0), options.length - 1);
+      options[next].focus();
+    });
+
+    // Focus moving somewhere outside the dropdown (Tab, Shift+Tab) closes
+    // it. No `relatedTarget` means focus went nowhere in particular - a
+    // click on the page, which the click-outside listener already handles.
+    dropdown.addEventListener('focusout', (e) => {
+      const to = e.relatedTarget as Node | null;
+      if (to && !dropdown.contains(to) && dropdown.classList.contains('open')) {
+        dropdown.classList.remove('open');
+        trigger.setAttribute('aria-expanded', 'false');
       }
     });
   });
 
   if (!globalListenersBound) {
     globalListenersBound = true;
-    // Bound once against `document`, not `root` - closeAll() above already
-    // closes every dropdown found on the page regardless of which root a
-    // given call was scoped to, so there's no reason for these two to be
-    // scoped any narrower or bound more than once.
-    document.addEventListener('click', closeAll);
+    // A click anywhere closes what's open - including a click on one of its
+    // options, which has done its job by then.
+    document.addEventListener('click', () => closeAll());
     document.addEventListener('keydown', (e) => {
       if (e.key === 'Escape') closeAll();
     });

package/src/scripts/search.ts

@@ -72,15 +72,52 @@ export function initSearch(root: ParentNode) {
   let currentResults: HTMLElement[] = [];
   let activeIndex = -1;
 
+  // Down on the last result (or Up on the first) stays there - Enter always
+  // has a result to open.
   function setActive(index: number) {
     currentResults.forEach((el) => el.classList.remove('wd-search-result-active'));
-    activeIndex = index >= 0 && index < currentResults.length ? index : -1;
+    activeIndex = currentResults.length ? Math.min(Math.max(index, 0), currentResults.length - 1) : -1;
     if (activeIndex >= 0) {
       currentResults[activeIndex].classList.add('wd-search-result-active');
       currentResults[activeIndex].scrollIntoView({ block: 'nearest' });
     }
   }
 
+  // Search looks in the version, language and product of the page the reader
+  // is on (plus pages outside any of them), with a switch to search
+  // everything. [...slug].astro marks each page's scope for Pagefind and
+  // for this - see lib/search-scope.js.
+  let everything = false;
+  const pageScope = () => {
+    const el = document.querySelector<HTMLElement>('[data-wd-search-scope]');
+    const key = el?.dataset.wdSearchScope ?? 'all';
+    return key === 'all' ? null : { key, label: el?.dataset.wdSearchScopeLabel || key };
+  };
+  function scopeNote(scope: { label: string } | null, found: boolean) {
+    if (!scope) return null;
+    const note = document.createElement('div');
+    note.className = 'wd-search-scope';
+    const text = document.createElement('span');
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'wd-search-scope-toggle';
+    if (everything) {
+      text.textContent = 'Showing results from the whole site.';
+      button.textContent = `Only ${scope.label}`;
+    } else {
+      text.textContent = found ? `Showing results in ${scope.label}.` : `No results in ${scope.label}.`;
+      button.textContent = 'Search everything';
+    }
+    button.addEventListener('click', (e) => {
+      e.stopPropagation();
+      everything = !everything;
+      input.focus();
+      runSearch(input.value);
+    });
+    note.append(text, ' ', button);
+    return note;
+  }
+
   async function runSearch(term: string) {
     if (!term.trim()) {
       resultsEl.innerHTML = '<div class="wd-search-hint">Start typing to search...</div>';
@@ -94,10 +131,14 @@ export function initSearch(root: ParentNode) {
     // superseded this call - pagefind's own debounce, on top of (not
     // instead of) the plain `input` listener below, so a fast typist never
     // races two searches rendering out of order.
-    const search = await pf.debouncedSearch(term, {}, 150);
+    const scope = pageScope();
+    const options = scope && !everything ? { filters: { any: [{ scope: scope.key }, { scope: 'all' }] } } : {};
+    const search = await pf.debouncedSearch(term, options, 150);
     if (search === null) return;
     if (search.results.length === 0) {
       resultsEl.innerHTML = '<div class="wd-search-empty">No results.</div>';
+      const note = scopeNote(scope, false);
+      if (note) resultsEl.replaceChildren(note);
       currentResults = [];
       activeIndex = -1;
       return;
@@ -111,15 +152,27 @@ export function initSearch(root: ParentNode) {
       const title = document.createElement('div');
       title.className = 'wd-search-result-title';
       title.textContent = data.meta?.title ?? data.url;
+      // Where the page sits: "API Reference › Webhooks".
+      const section = data.meta?.section ? document.createElement('div') : null;
+      if (section) {
+        section.className = 'wd-search-result-section';
+        section.textContent = data.meta.section;
+      }
       const excerpt = document.createElement('div');
       excerpt.className = 'wd-search-result-excerpt';
       // innerHTML (not textContent) is deliberate: pagefind returns this
       // pre-sanitized with <mark> wrapping the matched terms, which is the
       // whole point - a plain-text excerpt couldn't highlight anything.
-      excerpt.innerHTML = data.excerpt;
-      a.append(title, excerpt);
+      // The section is indexed as the page's last words, so a short page's
+      // excerpt ends with it - shown once, on its own line, unless it's what
+      // matched (then the excerpt keeps it, highlighted).
+      const trailing = data.meta?.section ? ` ${data.meta.section}.` : null;
+      excerpt.innerHTML = trailing && data.excerpt.endsWith(trailing) ? data.excerpt.slice(0, -trailing.length) : data.excerpt;
+      a.append(title, ...(section ? [section] : []), excerpt);
       resultsEl.appendChild(a);
     }
+    const note = scopeNote(scope, true);
+    if (note) resultsEl.appendChild(note);
     currentResults = Array.from(resultsEl.querySelectorAll('.wd-search-result'));
     setActive(0);
   }
@@ -128,6 +181,7 @@ export function initSearch(root: ParentNode) {
     overlay.hidden = false;
     document.body.style.overflow = 'hidden';
     input.value = '';
+    everything = false;
     resultsEl.innerHTML = '<div class="wd-search-hint">Start typing to search...</div>';
     currentResults = [];
     activeIndex = -1;

package/src/scripts/tabs-strip.ts

@@ -0,0 +1,169 @@
+// A tab row with more tabs than fit slides sideways instead of wrapping:
+// an arrow shows on each side that has more, the active tab starts in
+// view, and keyboard focus, a horizontal wheel/trackpad swipe and a touch
+// swipe move the row too. TopBar.astro renders the markup:
+// [data-tabs-strip] > arrow, .wd-tabs-viewport > .wd-topbar-tabs, arrow.
+//
+// The row is moved with a transform inside an `overflow-x: clip` viewport,
+// not scrolled: a scroll container clips both directions, and would cut
+// off the menus of the tabs and global dropdowns that open below the row.
+// `clip` on one axis leaves the other visible. Browsers without it keep
+// the row wrapping (topbar.css), and this does nothing.
+import { maxOffset, clampOffset, stepOffset, revealOffset } from '../lib/tabs-strip-offset.js';
+
+export function initTabsStrips(root: ParentNode) {
+  if (!CSS.supports('overflow-x', 'clip')) return;
+  root.querySelectorAll<HTMLElement>('[data-tabs-strip]').forEach(initStrip);
+}
+
+function initStrip(strip: HTMLElement) {
+  if (strip.dataset.wdInit) return;
+  strip.dataset.wdInit = 'true';
+  const viewport = strip.querySelector<HTMLElement>('.wd-tabs-viewport');
+  const track = strip.querySelector<HTMLElement>('.wd-topbar-tabs');
+  const prev = strip.querySelector<HTMLElement>('[data-tabs-prev]');
+  const next = strip.querySelector<HTMLElement>('[data-tabs-next]');
+  if (!viewport || !track || !prev || !next) return;
+
+  let offset = 0;
+  const geometry = () => {
+    const view = viewport.clientWidth;
+    return { view, max: maxOffset(track.scrollWidth, view), edge: prev.offsetWidth || 36 };
+  };
+  const apply = () => {
+    const { max } = geometry();
+    offset = clampOffset(offset, max);
+    track.style.transform = offset ? `translateX(${-offset}px)` : '';
+    strip.classList.toggle('wd-can-prev', offset > 0);
+    strip.classList.toggle('wd-can-next', offset < max);
+  };
+  // The tab (or dropdown) a node belongs to - a direct child of the row.
+  const itemOf = (node: Element | null) => {
+    while (node && node.parentElement !== track) node = node.parentElement;
+    return node as HTMLElement | null;
+  };
+  const reveal = (item: HTMLElement | null) => {
+    if (!item) return;
+    offset = revealOffset(offset, item.offsetLeft, item.offsetLeft + item.offsetWidth, geometry());
+    apply();
+  };
+
+  // Where the page starts: the active tab in view, without sliding to it.
+  // Tabs widen when the web font arrives, after this first placement - until
+  // the reader moves the row, each resize puts the active tab back in view.
+  let readerMoved = false;
+  const activeItem = itemOf(track.querySelector('.wd-tab-link.active'));
+  const settle = () => {
+    strip.classList.remove('wd-tabs-animate');
+    reveal(activeItem);
+    requestAnimationFrame(() => strip.classList.add('wd-tabs-animate'));
+  };
+  settle();
+
+  prev.addEventListener('click', (e) => {
+    e.stopPropagation();
+    readerMoved = true;
+    offset = stepOffset(offset, -1, geometry());
+    apply();
+  });
+  next.addEventListener('click', (e) => {
+    e.stopPropagation();
+    readerMoved = true;
+    offset = stepOffset(offset, 1, geometry());
+    apply();
+  });
+  track.addEventListener('focusin', (e) => reveal(itemOf(e.target as Element)));
+
+  // A sideways swipe on a trackpad, or Shift + wheel. A plain vertical
+  // wheel still scrolls the page.
+  viewport.addEventListener(
+    'wheel',
+    (e) => {
+      const delta = Math.abs(e.deltaX) > Math.abs(e.deltaY) ? e.deltaX : e.shiftKey ? e.deltaY : 0;
+      if (!delta || geometry().max === 0) return;
+      e.preventDefault();
+      readerMoved = true;
+      strip.classList.remove('wd-tabs-animate');
+      offset += delta;
+      apply();
+      requestAnimationFrame(() => strip.classList.add('wd-tabs-animate'));
+    },
+    { passive: false }
+  );
+
+  // Touch: a sideways swipe drags the row, and a quick one carries on a
+  // little after the finger lifts. `touch-action: pan-y` (topbar.css) leaves
+  // sideways moves to this and up/down ones to the page, which scrolls as
+  // usual. A swipe that ends on a tab doesn't open it.
+  let drag: { id: number; x: number; from: number; moving: boolean; last: [number, number][] } | null = null;
+  let swallowClick = false;
+  viewport.addEventListener('pointerdown', (e) => {
+    if (e.pointerType !== 'touch' || geometry().max === 0) return;
+    drag = { id: e.pointerId, x: e.clientX, from: offset, moving: false, last: [[e.clientX, e.timeStamp]] };
+  });
+  viewport.addEventListener('pointermove', (e) => {
+    if (!drag || e.pointerId !== drag.id) return;
+    const dx = e.clientX - drag.x;
+    if (!drag.moving) {
+      if (Math.abs(dx) < 8) return;
+      drag.moving = true;
+      readerMoved = true;
+      strip.classList.remove('wd-tabs-animate');
+      viewport.setPointerCapture(e.pointerId);
+    }
+    drag.last = [...drag.last.slice(-1), [e.clientX, e.timeStamp]];
+    offset = drag.from - dx;
+    apply();
+  });
+  const endDrag = (e: PointerEvent) => {
+    if (!drag || e.pointerId !== drag.id) return;
+    if (drag.moving && e.type === 'pointerup') {
+      const [[x0, t0], [x1, t1]] = drag.last.length > 1 ? drag.last : [drag.last[0], drag.last[0]];
+      const velocity = t1 > t0 ? (x1 - x0) / (t1 - t0) : 0; // px per ms
+      strip.classList.add('wd-tabs-animate');
+      offset -= velocity * 180;
+      apply();
+      swallowClick = true;
+      setTimeout(() => (swallowClick = false), 400);
+    } else {
+      requestAnimationFrame(() => strip.classList.add('wd-tabs-animate'));
+    }
+    drag = null;
+  };
+  viewport.addEventListener('pointerup', endDrag);
+  viewport.addEventListener('pointercancel', endDrag);
+  viewport.addEventListener(
+    'click',
+    (e) => {
+      if (!swallowClick) return;
+      e.preventDefault();
+      e.stopPropagation();
+      swallowClick = false;
+    },
+    true
+  );
+
+  // A menu that opens under a tab near the right end would be cut off
+  // there - it opens to the left of its tab instead.
+  track.querySelectorAll<HTMLElement>('.wd-dropdown').forEach((dropdown) => {
+    const menu = dropdown.querySelector<HTMLElement>('.wd-dropdown-menu');
+    if (!menu) return;
+    const place = () => {
+      const shown = menu.style.display;
+      menu.style.visibility = 'hidden';
+      menu.style.display = 'block';
+      const width = menu.offsetWidth;
+      menu.style.display = shown;
+      menu.style.visibility = '';
+      const right = dropdown.getBoundingClientRect().left + width;
+      dropdown.classList.toggle('wd-dropdown-align-end', right > viewport.getBoundingClientRect().right);
+    };
+    dropdown.addEventListener('pointerenter', place);
+    dropdown.addEventListener('focusin', place);
+  });
+
+  // Tabs change width as fonts load, and the space changes with the window.
+  const resized = () => (readerMoved ? apply() : settle());
+  new ResizeObserver(resized).observe(viewport);
+  new ResizeObserver(resized).observe(track);
+}

package/writedocs.schema.json

@@ -747,30 +747,48 @@
       "markdownDescription": "Default metadata for every page. A page's own `seo` frontmatter overrides it field by field."
     },
     "contextMenu": {
-      "type": "object",
-      "properties": {
-        "openIn": {
-          "default": [
-            "chatgpt",
-            "claude",
-            "perplexity"
-          ],
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
           "type": "array",
           "items": {
             "type": "string",
             "enum": [
+              "copy",
+              "view",
               "chatgpt",
               "claude",
-              "perplexity"
+              "perplexity",
+              "mcp",
+              "cursor",
+              "vscode"
             ]
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "openIn": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "chatgpt",
+                  "claude",
+                  "perplexity"
+                ]
+              },
+              "description": "The earlier form: which AI assistants the menu offers, besides copy and view. A list of options replaces it.",
+              "markdownDescription": "The earlier form: which AI assistants the menu offers, besides copy and view. A list of options replaces it."
+            }
           },
-          "description": "Which AI assistants the menu offers. Default: all three.",
-          "markdownDescription": "Which AI assistants the menu offers. Default: all three."
+          "additionalProperties": false
         }
-      },
-      "additionalProperties": false,
-      "description": "Adds a \"Copy page\" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + \".md\".",
-      "markdownDescription": "Adds a \"Copy page\" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + \".md\"."
+      ],
+      "description": "The \"Copy page\" menu on every page - copy as Markdown, view as Markdown, open in ChatGPT, Claude or Perplexity, copy the MCP server URL, connect to Cursor or VS Code - and a Markdown copy of each page at its address + \".md\". On by default with every option (the MCP ones only while `mcp` is on). A list picks the options (\"copy\", \"view\", \"chatgpt\", \"claude\", \"perplexity\", \"mcp\", \"cursor\", \"vscode\"); false turns it all off.",
+      "markdownDescription": "The \"Copy page\" menu on every page - copy as Markdown, view as Markdown, open in ChatGPT, Claude or Perplexity, copy the MCP server URL, connect to Cursor or VS Code - and a Markdown copy of each page at its address + \".md\". On by default with every option (the MCP ones only while `mcp` is on). A list picks the options (\"copy\", \"view\", \"chatgpt\", \"claude\", \"perplexity\", \"mcp\", \"cursor\", \"vscode\"); false turns it all off."
     },
     "mcp": {
       "default": true,