@waveso/docs 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @waveso/docs
 
+## 0.4.0
+
+### Minor Changes
+
+- The search dialog, corrected by using it. Five defects a reader meets and no test could see, and one rename that follows from the largest of them.
+
+  **`maxResults` is now `pageSize`, and it is a window rather than a ceiling.** It capped the list at 20 (8 in 0.2.0): on a _six-page_ site "docs" matches 18, so results were unreachable, and the live region announced the slice as though it were the total — not a smaller truth but a false one.
+
+  The cap was justified by a claim nobody had measured, and measuring it did not support the claim. On a 300-page corpus (2,100 records) a MiniSearch query costs **1.3–3.0 ms**, and rendering _every_ matching row costs **40 ms**, 128 ms at 4× CPU throttle. The search was never the cost; the DOM only becomes one in the thousands.
+
+  So the list pages. Twenty rows render, and another twenty each time the reader scrolls near the end — the DOM stays bounded and nothing is withheld. The keyboard widens the window too, or `aria-activedescendant` points at an option that is not in the DOM. `aria-setsize` carries the real total on every option, because a listbox rendering 20 of 2,100 that says "20 of 20" tells a reader they have reached the end when they have not.
+
+  **Migration:** rename the prop. `maxResults={20}` becomes `pageSize={20}`, and it now means "reveal this many at a time" rather than "never show more than this".
+
+  **The dialog sizes to its results.** It was 32rem tall in every state — measured 514px with no query, 514px with eight results, 514px with none, of which 392px was an empty results area, so a reader typed into a box floating at the top of a large blank rectangle. A flex container defaults to `align-items: stretch`, so the dialog stretched to the viewport and `max-height` capped it at a constant instead of being the ceiling it was written to be. It is content-height now, and starts scrolling at the same 32rem.
+
+  **Hovering a half-visible result no longer yanks the list.** Pointing at a row clipped by the top or bottom edge set the active option, which fired the scroll-into-view meant for the arrow keys: the row snapped flush, the whole list moved under the cursor, and the cursor was then over a different row. Measured as a 28px jump. Only the keyboard scrolls now, and a new result set explicitly returns to the top — which that effect had been doing by accident.
+
+  **Every result row says where it lands, in the same words.** The second line was a breadcrumb of page and heading names, except on a page's own record — whose heading _is_ its page title — which got no second line at all rather than repeat itself. On a six-page site that is six of twenty-nine records, so the list came out ragged and the barest rows said the least: a row reading only "Wave Docs" told a reader nothing about what it opened.
+
+  Every row now shows the page it lands on: the route, without its anchor. The anchor is slugged from the heading printed directly above it, so it spent the line restating line one. The link keeps it, so a hit still deep-links to its section.
+
+  **Breaking in rendered output:** `.wave-docs-search-result-breadcrumb`, `.wave-docs-search-result-crumb` and `.wave-docs-search-result-crumb-separator` are replaced by a single `.wave-docs-search-result-location`, because a breadcrumb it is not. A screen reader still hears the words — a route read aloud is punctuation — so the option's `aria-label` carries "Layout tokens, Styling" while the visible line carries the address.
+
+  **A query is at least two characters**, settable with `minQueryLength`. Measured on this package's own documentation: `a` matches 100% of the corpus, `i` 97%, `s` 93%. One character is not a query, it is a reader halfway through typing one, and answering it with everything teaches them that search returns noise. Below the floor nothing runs — no search, no index request — and the dialog says "Keep typing" rather than sitting there answering nothing.
+
+  Two rather than three, and the difference matters on a docs site: three would refuse `ts`, `js`, `id`, `h1` and `px`, each a real query here and each selective — 10%, 17%, 14%, 3%, 0%. The noise is at one character, so that is where the floor goes.
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/react/search-dialog.d.ts

@@ -26,8 +26,39 @@ interface SearchDialogProps {
   placeholder?: string | undefined;
   /** Accessible name for the dialog. Defaults to `'Search documentation'`. */
   dialogLabel?: string | undefined;
-  /** Maximum results rendered. Defaults to 8. */
-  maxResults?: number | undefined;
+  /**
+   * How many results to render at a time. Defaults to 20.
+   *
+   * ⚠️ NOT A CAP. Every match is reachable — the list renders this many, then
+   * another `pageSize` each time the reader scrolls near the end, so the DOM
+   * stays bounded without anything being withheld.
+   *
+   * This was `maxResults`, and it was a hard ceiling of 8. On a *six-page*
+   * site "docs" matches 18, so ten results simply could not be reached, and
+   * the live region announced "8 results" — not a smaller truth but a false
+   * one. The ceiling was justified by a claim nobody had measured, and the
+   * measurement did not support it: on a 300-page corpus (2,100 records) a
+   * query costs 1.3–3.0 ms and rendering *every* row costs 40 ms, 128 ms at
+   * 4x CPU throttle. Paging exists to keep that worst case from ever being
+   * reached, not because the search cannot find things.
+   */
+  pageSize?: number | undefined;
+  /**
+   * Shortest query that runs. Defaults to 2.
+   *
+   * A single character is not a query — measured on this package's own docs,
+   * "a" matches 100% of the corpus, "i" 97%, "s" 93%. Answering those wastes a
+   * render and, worse, teaches a reader mid-word that search returns noise.
+   *
+   * ⚠️ TWO, NOT THREE, AND THE DIFFERENCE MATTERS ON A DOCS SITE. Three would
+   * refuse `ts`, `js`, `id`, `h1`, `px` — every one a real query here, and each
+   * one selective: 10%, 17%, 14%, 3%, 0%. The noise is at one character, so
+   * that is where the floor goes.
+   *
+   * A word like `is` still matches 83%; that is a stopword problem rather than
+   * a length one, and `miniSearchOptions.processTerm` is the tool for it.
+   */
+  minQueryLength?: number | undefined;
   /** Input debounce in milliseconds. Defaults to 120. */
   debounceMs?: number | undefined;
   /** Extra class names for the trigger button, e.g. a navbar's own layout. */
@@ -64,6 +95,6 @@ interface SearchDialogProps {
  * portalled to `document.body`, so a navbar's stacking context cannot trap
  * it behind the page.
  */
-declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, maxResults, debounceMs, className, miniSearchOptions }: SearchDialogProps): ReactNode;
+declare function SearchDialog({ indexUrl, navigate, Link, triggerLabel, placeholder, dialogLabel, pageSize, minQueryLength, debounceMs, className, miniSearchOptions }: SearchDialogProps): ReactNode;
 //#endregion
 export { SearchDialog, SearchDialogProps };

package/dist/react/search-dialog.js

@@ -26,10 +26,31 @@ const FOCUSABLE_SELECTOR = [
 * portalled to `document.body`, so a navbar's stacking context cannot trap
 * it behind the page.
 */
-function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", maxResults = 8, debounceMs = 120, className, miniSearchOptions }) {
+function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", placeholder = "Search documentation", dialogLabel = "Search documentation", pageSize = 20, minQueryLength = 2, debounceMs = 120, className, miniSearchOptions }) {
 	const [isOpen, setIsOpen] = useState(false);
 	const [query, setQuery] = useState("");
 	const [hits, setHits] = useState([]);
+	/**
+	* How many of `hits` are rendered.
+	*
+	* `hits` holds every match; this is the window. It grows by `pageSize` when
+	* the reader scrolls near the end, and whenever the keyboard walks past it —
+	* so an option always exists for `aria-activedescendant` to point at.
+	*/
+	const [visibleCount, setVisibleCount] = useState(pageSize);
+	/**
+	* Whether the active option moved because of a key, rather than a pointer.
+	*
+	* ⚠️ THE SCROLL-INTO-VIEW BELOW MUST NOT RUN FOR A HOVER. Pointing at a row
+	* that is half-clipped by the top or bottom edge set the active index, which
+	* scrolled that row flush — moving the whole list under the cursor, which
+	* then landed on a different row. Measured: hovering the visible sliver of a
+	* clipped row jumped the list 28px.
+	*
+	* A ref rather than state: it records how the *last* change happened and must
+	* not itself cause a render.
+	*/
+	const movedByKeyboard = useRef(false);
 	const [activeIndex, setActiveIndex] = useState(0);
 	const [status, setStatus] = useState("idle");
 	const [shortcutHint, setShortcutHint] = useState("");
@@ -135,9 +156,10 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	}, [isOpen]);
 	useEffect(() => {
 		const trimmed = query.trim();
-		if (trimmed === "") {
+		if (trimmed.length < minQueryLength) {
 			setHits([]);
 			setActiveIndex(0);
+			setVisibleCount(pageSize);
 			return;
 		}
 		let isCancelled = false;
@@ -145,8 +167,9 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			ensureIndex().then((index) => {
 				if (isCancelled) return;
 				setStatus("ready");
-				setHits(index.search(trimmed).slice(0, maxResults).map(toSearchHit).filter(isSearchHit));
+				setHits(index.search(trimmed).map(toSearchHit).filter(isSearchHit));
 				setActiveIndex(0);
+				setVisibleCount(pageSize);
 			}, () => {
 				if (!isCancelled) setStatus("error");
 			});
@@ -158,11 +181,55 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	}, [
 		query,
 		ensureIndex,
-		maxResults,
-		debounceMs
+		pageSize,
+		debounceMs,
+		minQueryLength
 	]);
+	/**
+	* Reveal another page when the reader nears the end of the list.
+	*
+	* A scroll handler rather than an `IntersectionObserver` on a sentinel: the
+	* scrollport is one element this component already holds a ref to, the test
+	* is one subtraction, and an observer would cost bytes on the largest client
+	* entry this package ships for no behaviour the reader can tell apart.
+	*
+	* `passive`, because this never calls `preventDefault` and a non-passive
+	* scroll listener blocks the compositor on every wheel event.
+	*
+	* No `isOpen` dependency, though the list does not exist while the dialog is
+	* closed: the effect returns early on a null ref, and `hits.length` going
+	* from 0 to N re-runs it — which happens after the list has mounted, because
+	* closing resets the query. The listener attaches exactly when there is
+	* something to scroll.
+	*/
+	useEffect(() => {
+		const list = listRef.current;
+		if (list === null || visibleCount >= hits.length) return;
+		const onScroll = () => {
+			if (list.scrollHeight - list.scrollTop - list.clientHeight < list.clientHeight) setVisibleCount((count) => Math.min(count + pageSize, hits.length));
+		};
+		list.addEventListener("scroll", onScroll, { passive: true });
+		return () => list.removeEventListener("scroll", onScroll);
+	}, [
+		visibleCount,
+		hits.length,
+		pageSize
+	]);
+	useEffect(() => {
+		if (activeIndex >= visibleCount) setVisibleCount(Math.min(activeIndex + 1, hits.length));
+	}, [
+		activeIndex,
+		visibleCount,
+		hits.length
+	]);
+	useEffect(() => {
+		const list = listRef.current;
+		if (list !== null && list.scrollTop !== 0) list.scrollTop = 0;
+	}, [hits]);
 	useEffect(() => {
 		if (hits.length === 0) return;
+		if (!movedByKeyboard.current) return;
+		movedByKeyboard.current = false;
 		(listRef.current?.querySelector(`#${CSS.escape(`${baseId}-option-${activeIndex}`)}`))?.scrollIntoView({ block: "nearest" });
 	}, [
 		activeIndex,
@@ -179,6 +246,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			if (hits.length === 0) return;
 			event.preventDefault();
 			const delta = event.key === "ArrowDown" ? 1 : -1;
+			movedByKeyboard.current = true;
 			setActiveIndex((index) => (index + delta + hits.length) % hits.length);
 			return;
 		}
@@ -250,11 +318,16 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 					className: "wave-docs-search-results",
 					role: "listbox",
 					"aria-label": dialogLabel,
-					children: hits.map((hit, index) => /* @__PURE__ */ jsx(SearchResultOption, {
+					children: hits.slice(0, visibleCount).map((hit, index) => /* @__PURE__ */ jsx(SearchResultOption, {
 						hit,
 						id: optionId(index),
 						isActive: index === activeIndex,
-						onActivate: () => setActiveIndex(index),
+						setSize: hits.length,
+						posInSet: index + 1,
+						onActivate: () => {
+							movedByKeyboard.current = false;
+							setActiveIndex(index);
+						},
 						onSelect: selectHit,
 						...Link === void 0 ? {} : { Link }
 					}, hit.id))
@@ -262,40 +335,36 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 				/* @__PURE__ */ jsx(SearchStatus, {
 					status,
 					query: query.trim(),
-					hitCount: hits.length
+					hitCount: hits.length,
+					minQueryLength
 				})
 			]
 		})
 	}), document.body) : null] });
 }
 /** One result row: a real link, so middle-click and "open in new tab" work. */
-function SearchResultOption({ hit, id, isActive, onActivate, onSelect, Link }) {
+function SearchResultOption({ hit, id, isActive, setSize, posInSet, onActivate, onSelect, Link }) {
 	function handleClick(event) {
 		if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
 		event.preventDefault();
 		onSelect(hit);
 	}
-	const trail = toBreadcrumbs(hit);
 	const body = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("span", {
 		className: "wave-docs-search-result-heading",
 		children: hit.heading
-	}), trail.length === 0 ? null : /* @__PURE__ */ jsx("span", {
-		className: "wave-docs-search-result-breadcrumb",
-		children: trail.map((crumb, index) => /* @__PURE__ */ jsxs("span", {
-			className: "wave-docs-search-result-crumb",
-			children: [index === 0 ? null : /* @__PURE__ */ jsx("span", {
-				className: "wave-docs-search-result-crumb-separator",
-				"aria-hidden": "true",
-				children: "›"
-			}), crumb.text]
-		}, crumb.key))
+	}), /* @__PURE__ */ jsx("span", {
+		className: "wave-docs-search-result-location",
+		"aria-hidden": "true",
+		children: toDisplayPath(hit.href)
 	})] });
 	return /* @__PURE__ */ jsx("div", {
 		id,
 		className: isActive ? "wave-docs-search-result wave-docs-search-result-active" : "wave-docs-search-result",
 		role: "option",
 		"aria-selected": isActive,
-		"aria-label": [hit.heading, ...trail.map((crumb) => crumb.text)].join(", "),
+		"aria-setsize": setSize,
+		"aria-posinset": posInSet,
+		"aria-label": spokenName(hit),
 		tabIndex: -1,
 		onPointerMove: onActivate,
 		children: Link === void 0 ? /* @__PURE__ */ jsx("a", {
@@ -314,7 +383,7 @@ function SearchResultOption({ hit, id, isActive, onActivate, onSelect, Link }) {
 	});
 }
 /** Loading, failure and empty states, plus a live region for hit counts. */
-function SearchStatus({ status, query, hitCount }) {
+function SearchStatus({ status, query, hitCount, minQueryLength }) {
 	let message = null;
 	let modifier = "";
 	if (status === "error") {
@@ -323,6 +392,9 @@ function SearchStatus({ status, query, hitCount }) {
 	} else if (query === "") {
 		message = "Start typing to search the documentation.";
 		modifier = " wave-docs-search-status-hint";
+	} else if (query.length < minQueryLength) {
+		message = `Keep typing — ${minQueryLength} characters or more.`;
+		modifier = " wave-docs-search-status-hint";
 	} else if (status !== "ready") {
 		message = "Loading the search index…";
 		modifier = " wave-docs-search-status-loading";
@@ -380,24 +452,47 @@ function isSearchHit(hit) {
 	return hit !== void 0;
 }
 /**
-* Page title first, then the ancestor headings: `ancestors` deliberately excludes
-* the page title so the index does not carry it twice.
+* The route, without its anchor, for display only.
 *
-* A page's lead record carries `heading === title` and no ancestors (see
-* `extractSearchRecords`), so its trail would be the one string already printed
-* above it. "Installation" over "Installation" is not a path, it is a bug that
-* reads as a rendering glitch — such a hit gets no trail at all.
+* ⚠️ THE ANCHOR IS NOISE HERE, AND ALMOST ALWAYS A REPEAT. A section's anchor
+* is slugged from its heading, so `/docs/styling#layout-tokens` under a row
+* whose first line already reads "Layout tokens" spends its width restating
+* it — and on a real site it is the part that pushes the line past the
+* ellipsis.
+*
+* What the line is for is "which page does this land on", and the path answers
+* that on its own. Two rows from the same page showing the same path is not
+* ambiguity: they *are* the same page, and their headings above say which part.
+*
+* Display only. `hit.href` keeps the anchor, so the link still deep-links to
+* the section — that is the whole point of section-scoped records.
 */
-function toBreadcrumbs(hit) {
-	if (hit.ancestors.length === 0 && hit.heading === hit.title) return [];
-	let trail = "";
-	return [hit.title, ...hit.ancestors].map((text) => {
-		trail = trail === "" ? text : `${trail}/${text}`;
-		return {
-			key: trail,
-			text
-		};
-	});
+function toDisplayPath(href) {
+	const hash = href.indexOf("#");
+	return hash === -1 ? href : href.slice(0, hash);
+}
+/**
+* What a result is called when it is read aloud.
+*
+* Words, not the route the row displays. `/docs/styling#layout-tokens` is
+* punctuation to a screen reader — spelled out slash by slash — so the visible
+* line and the announced name deliberately carry the same fact in two forms:
+* the route for a sighted reader scanning for where a hit lands, and
+* "Layout tokens, Styling" for a listener.
+*
+* `ancestors` deliberately excludes the page title, so the page comes first
+* here and the enclosing headings follow, outermost first.
+*
+* A page's own record carries `heading === title` and no ancestors, so its name
+* is the heading alone — "Styling, Styling" is not a path, it is a stutter.
+*/
+function spokenName(hit) {
+	if (hit.ancestors.length === 0 && hit.heading === hit.title) return hit.heading;
+	return [
+		hit.heading,
+		hit.title,
+		...hit.ancestors
+	].join(", ");
 }
 function trapFocus(root, event) {
 	if (root === null) return;

package/dist/styles.css

@@ -1844,6 +1844,19 @@
     z-index: 50;
     display: flex;
     justify-content: center;
+    /*
+     * ⚠️ `flex-start`, OR THE DIALOG IS ALWAYS 32rem TALL. A flex container
+     * defaults to `align-items: stretch`, so the dialog stretched to the full
+     * viewport height and `max-height` then capped it — at a constant. Measured
+     * before this line: 514px with no query, 514px with eight results, 514px
+     * with none, of which 392px was an empty results area. The reader typed
+     * into a box floating at the top of a large blank rectangle.
+     *
+     * Aligned to the start, the dialog is as tall as its content and the
+     * `max-height` below goes back to being what it says it is — a ceiling
+     * where the list starts scrolling, not a height.
+     */
+    align-items: flex-start;
     /* Not centred: a dialog that grows downward from a fixed top does not
      * shift under the reader as results stream in. */
     /* `dvh`, not `vh`: on a phone `vh` is the viewport with the URL bar
@@ -1930,12 +1943,29 @@
     border-color: var(--wave-docs-border-strong);
   }
 
+  /*
+   * `1 1 auto` and not `0 1 auto`: once the dialog hits its `max-height` this
+   * is the part that must take the remaining space and scroll, rather than the
+   * list overflowing a box sized to the input. With the dialog content-sized
+   * there is no free space to grow into, so it only bites at the ceiling —
+   * which is exactly when it should.
+   */
   .wave-docs-search-results {
     flex: 1 1 auto;
     overflow-y: auto;
     padding: 0.375rem;
   }
 
+  /*
+   * An empty results container has no padding to contribute. Without this it
+   * adds 12px of nothing under the input on every keystroke that matches
+   * nothing — small, and precisely the sort of gap that reads as a broken
+   * layout rather than as an empty state.
+   */
+  .wave-docs-search-results:empty {
+    display: none;
+  }
+
   .wave-docs-search-result {
     border-radius: var(--wave-docs-radius-sm);
   }
@@ -1969,20 +1999,39 @@
     line-height: 1.4;
   }
 
-  .wave-docs-search-result-breadcrumb {
-    color: var(--wave-docs-fg-subtle);
-    font-size: 0.75rem;
-    line-height: 1.4;
-  }
-
-  /* A crumb never wraps mid-title: the trail reads as a path or not at all.
-   * The breadcrumb line itself is free to wrap between crumbs. */
-  .wave-docs-search-result-crumb {
+  /*
+   * Where the hit lands, as a route.
+   *
+   * ⚠️ RENAMED FROM `…-breadcrumb` / `…-crumb`, WHICH IS BREAKING AND
+   * DELIBERATE. This used to be a trail of human names — "Installation ›
+   * Requirements" — and a page's own record, whose heading IS its page title,
+   * got no line at all rather than repeat itself. That left a list where some
+   * rows had two lines and some had one.
+   *
+   * The first repair gave those rows the route and kept the trail on the
+   * others, which was worse: one slot carrying two different kinds of thing,
+   * so "Styling" under one row was a page and "/docs/styling" under the next
+   * was an address. Now every row shows the route, always, and the class is
+   * named for what it holds — a breadcrumb it is not.
+   *
+   * The words live in the option's `aria-label`, because a route read aloud is
+   * punctuation.
+   */
+  .wave-docs-search-result-location {
+    display: block;
+    /* One line, ellipsised. A real site's routes reach
+     * `/docs/api/reference/authentication#rotating-keys`, and a wrapped route
+     * makes the row two different heights depending on its depth — the raggedness
+     * this whole change exists to remove. */
+    overflow: hidden;
     white-space: nowrap;
-  }
-
-  .wave-docs-search-result-crumb-separator {
-    margin-inline: 0.25rem;
+    text-overflow: ellipsis;
+    color: var(--wave-docs-fg-subtle);
+    font-family: var(--wave-docs-font-mono);
+    /* Smaller than the trail was: a monospace face reads larger at the same
+     * size, and this line is a reference rather than something to read. */
+    font-size: 0.6875rem;
+    line-height: 1.5;
   }
 
   .wave-docs-search-status {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Zero parser bytes in the browser: markdown docs for Next.js, built to hast in Node and rendered as your components",
   "type": "module",
   "sideEffects": [