@writedocs/generator 0.8.1 → 0.9.0

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

@@ -760,7 +760,10 @@
               "view",
               "chatgpt",
               "claude",
-              "perplexity"
+              "perplexity",
+              "mcp",
+              "cursor",
+              "vscode"
             ]
           }
         },
@@ -784,8 +787,8 @@
           "additionalProperties": false
         }
       ],
-      "description": "The \"Copy page\" menu on every page - copy as Markdown, view as Markdown, open in ChatGPT, Claude or Perplexity - and a Markdown copy of each page at its address + \".md\". On by default with every option. A list picks the options (\"copy\", \"view\", \"chatgpt\", \"claude\", \"perplexity\"); 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 - and a Markdown copy of each page at its address + \".md\". On by default with every option. A list picks the options (\"copy\", \"view\", \"chatgpt\", \"claude\", \"perplexity\"); false turns it all off."
+      "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,