@waveso/docs 0.10.0 → 0.12.0

package/dist/react/search-dialog.js

@@ -1,7 +1,7 @@
 "use client";
 import { docsError } from "../docs-error.js";
 import { mergeSearchOptions } from "../search-options.js";
-import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { Fragment, useCallback, useEffect, useId, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
 //#region src/react/search-dialog.tsx
@@ -51,7 +51,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 	* not itself cause a render.
 	*/
 	const movedByKeyboard = useRef(false);
-	const [activeIndex, setActiveIndex] = useState(0);
+	const [activeIndex, setActiveIndex] = useState(-1);
 	const [status, setStatus] = useState("idle");
 	/**
 	* The trigger's shortcut, split rather than held as one string.
@@ -166,13 +166,13 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 		if (isOpen) return;
 		setQuery("");
 		setHits([]);
-		setActiveIndex(0);
+		setActiveIndex(-1);
 	}, [isOpen]);
 	useEffect(() => {
 		const trimmed = query.trim();
 		if (trimmed.length < minQueryLength) {
 			setHits([]);
-			setActiveIndex(0);
+			setActiveIndex(-1);
 			setVisibleCount(pageSize);
 			return;
 		}
@@ -182,7 +182,7 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 				if (isCancelled) return;
 				setStatus("ready");
 				setHits(index.search(trimmed).map(toSearchHit).filter(isSearchHit));
-				setActiveIndex(0);
+				setActiveIndex(-1);
 				setVisibleCount(pageSize);
 			}, () => {
 				if (!isCancelled) setStatus("error");
@@ -261,7 +261,10 @@ function SearchDialog({ indexUrl, navigate, Link, triggerLabel = "Search", place
 			event.preventDefault();
 			const delta = event.key === "ArrowDown" ? 1 : -1;
 			movedByKeyboard.current = true;
-			setActiveIndex((index) => (index + delta + hits.length) % hits.length);
+			setActiveIndex((index) => {
+				if (index < 0) return delta > 0 ? 0 : hits.length - 1;
+				return (index + delta + hits.length) % hits.length;
+			});
 			return;
 		}
 		if (event.key === "Enter") {
@@ -446,13 +449,16 @@ function SearchResultOption({ hit, id, isActive, setSize, posInSet, onActivate,
 		event.preventDefault();
 		onSelect(hit);
 	}
-	const body = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("span", {
-		className: "wave-docs-search-result-heading",
-		children: hit.heading
-	}), /* @__PURE__ */ jsx("span", {
-		className: "wave-docs-search-result-location",
-		"aria-hidden": "true",
-		children: toDisplayPath(hit.href)
+	const body = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(ResultIcon, { section: hit.href.includes("#") }), /* @__PURE__ */ jsxs("span", {
+		className: "wave-docs-search-result-text",
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "wave-docs-search-result-heading",
+			children: hit.heading
+		}), /* @__PURE__ */ jsx("span", {
+			className: "wave-docs-search-result-location",
+			"aria-hidden": "true",
+			children: toDisplaySegments(hit.href).map((segment, index, all) => /* @__PURE__ */ jsxs(Fragment, { children: [index === 0 ? null : /* @__PURE__ */ jsx(PathChevron, {}), segment] }, all.slice(0, index + 1).join("/")))
+		})]
 	})] });
 	return /* @__PURE__ */ jsx("div", {
 		id,
@@ -599,9 +605,10 @@ function isSearchHit(hit) {
 * 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 toDisplayPath(href) {
+function toDisplaySegments(href) {
 	const hash = href.indexOf("#");
-	return hash === -1 ? href : href.slice(0, hash);
+	const segments = (hash === -1 ? href : href.slice(0, hash)).split("/").filter(Boolean);
+	return segments.length === 0 ? ["/"] : segments;
 }
 /**
 * What a result is called when it is read aloud.
@@ -618,6 +625,71 @@ function toDisplayPath(href) {
 * 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.
 */
+/**
+* A page or a section, as one Lucide glyph.
+*
+* ⚠️ THE PATHS ARE WRITTEN OUT RATHER THAN IMPORTED FROM THE SIDEBAR, WHICH
+* HAS THE SAME PAGE ICON. `NAV_ICON_PATHS` lives in a different client
+* component, and importing across the two would pull the whole navigation
+* tree into the search dialog's bundle to reuse one string. The duplication is
+* two path strings; the alternative is kilobytes.
+*/
+const RESULT_ICON_PATHS = {
+	page: ["M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z", "M14 2v4a2 2 0 0 0 2 2h4"],
+	section: [
+		"M4 9h16",
+		"M4 15h16",
+		"m10 3-2 18",
+		"m16 3-2 18"
+	]
+};
+/**
+* The separator between two route segments.
+*
+* The same path the sidebar's group toggle and the pager draw, at the same
+* `1rem` they draw it. Decorative, and inside a span that is already
+* `aria-hidden` — the route is announced as words by `spokenName`, never read
+* out as punctuation.
+*
+* ⚠️ THE `viewBox` IS CROPPED HORIZONTALLY AND THAT IS NOT A DIFFERENT GLYPH.
+* `d` is Lucide's chevron unchanged and `8 0 8 24` keeps its vertical grid, so
+* the stroke ratio and the ink are exactly what the sidebar and the pager
+* paint. What it drops is the padding either side that the path never reaches:
+* on the full grid a 24-unit box held six units of chevron, so five-sixths of
+* this element was air and the stylesheet had to subtract it back with
+* negative margins. Cropped, the box is the ink and the spacing beside it is
+* one positive value. See `.wave-docs-search-result-sep`.
+*/
+function PathChevron() {
+	return /* @__PURE__ */ jsx("svg", {
+		className: "wave-docs-search-result-sep",
+		"aria-hidden": "true",
+		focusable: "false",
+		viewBox: "8 5 8 14",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: /* @__PURE__ */ jsx("path", { d: "m9 18 6-6-6-6" })
+	});
+}
+function ResultIcon({ section }) {
+	return /* @__PURE__ */ jsx("svg", {
+		className: "wave-docs-search-result-icon",
+		"aria-hidden": "true",
+		focusable: "false",
+		viewBox: "0 0 24 24",
+		width: "16",
+		height: "16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: RESULT_ICON_PATHS[section ? "section" : "page"].map((d) => /* @__PURE__ */ jsx("path", { d }, d))
+	});
+}
 function spokenName(hit) {
 	if (hit.ancestors.length === 0 && hit.heading === hit.title) return hit.heading;
 	return [

package/dist/react/shell-labels.d.ts

@@ -76,6 +76,13 @@ interface DocsLabels {
    * The direction, not the destination: the page's own title is the name, and
    * these two words are what say which way it lies.
    */
+  /**
+   * The "where to go next" block's heading. Defaults to `'Where to go next'`.
+   *
+   * A page opts into that block with `explore` in its frontmatter; this is the one
+   * string the package supplies for it, and the questions are the author's.
+   */
+  explore?: string | undefined;
   previousPage?: string | undefined;
   /** The same for the next page. Defaults to `'Next'`. */
   nextPage?: string | undefined;
@@ -154,7 +161,7 @@ interface DocsLabels {
  * failure being guarded against is a key that is declared, documented and never
  * read, which type-checks perfectly.
  */
-declare const DOCS_LABEL_KEYS: readonly ["nav", "openNav", "closeNav", "skipToContent", "expandGroup", "collapseGroup", "toc", "backToTop", "externalLink", "table", "calloutNote", "calloutTip", "calloutImportant", "calloutWarning", "calloutCaution", "youtubeTitle", "youtubePlay", "youtubeHide", "copyCode", "copyCodeFrom", "previousPage", "nextPage", "pagination", "copied", "copyFailed"];
+declare const DOCS_LABEL_KEYS: readonly ["nav", "openNav", "closeNav", "skipToContent", "expandGroup", "collapseGroup", "toc", "backToTop", "externalLink", "table", "calloutNote", "calloutTip", "calloutImportant", "calloutWarning", "calloutCaution", "youtubeTitle", "youtubePlay", "youtubeHide", "copyCode", "copyCodeFrom", "explore", "previousPage", "nextPage", "pagination", "copied", "copyFailed"];
 /** The four the shell renders itself, resolved centrally. */
 type ShellLabelKey = 'nav' | 'openNav' | 'closeNav' | 'skipToContent';
 /**

package/dist/react/shell-labels.js

@@ -27,6 +27,7 @@ const DOCS_LABEL_KEYS = [
 	"youtubeHide",
 	"copyCode",
 	"copyCodeFrom",
+	"explore",
 	"previousPage",
 	"nextPage",
 	"pagination",