@mailwoman/react 10.1.0 → 10.2.0

package/lib/search/SearchModal.tsx

@@ -5,10 +5,13 @@
  *
  *   The docs search modal. A native `<dialog>` opened with `showModal()` supplies the focus trap, the inert
  *   background, the backdrop, the close on Escape and the return of focus to the opener. The query field is an
- *   `<input type="search">` with the ARIA combobox role. DOM focus stays on the input, and the selected hit is
- *   named by `aria-activedescendant`. The component owns no data access: `search` is passed in.
+ *   `<input type="search">` with the ARIA combobox role. DOM focus stays on the input, and
+ *   `aria-activedescendant` identifies the selected hit. The component owns no data access: `search` is
+ *   passed in. Recent queries are a per-viewer convenience in `localStorage`; the modal renders the same
+ *   without them.
  */
 
+import { stringifyJSON, tryParsingJSON } from "@mailwoman/core/json"
 import { type KeyboardEvent, type MouseEvent, type ReactNode, useEffect, useId, useMemo, useRef, useState } from "react"
 
 import { useDebouncedValue } from "#common/useDebouncedValue"
@@ -30,6 +33,11 @@ export interface SearchModalProps {
 	 * because a new identity refires the request for the current query.
 	 */
 	search: (q: string, signal: AbortSignal) => Promise<SearchResponse>
+	/**
+	 * The `localStorage` key under which recent queries are kept.
+	 * Absent, recent queries are not kept.
+	 */
+	recentKey?: string
 }
 
 type Status =
@@ -46,6 +54,7 @@ const DEBOUNCE_MS = 150
 const LOADING_ANNOUNCE_MS = 300
 const MAX_QUERY_LENGTH = 200
 const DEFAULT_CATEGORY = "Documentation"
+const RECENT_LIMIT = 5
 
 /**
  * The site-relative link for a hit.
@@ -68,30 +77,100 @@ function statusText(status: Status): string {
 	return response.hits.length === 1 ? "1 result." : `${response.hits.length} results.`
 }
 
-function highlighted(hit: SearchHit): ReactNode[] {
+/**
+ * The ranges of `text` that match a query token, case-insensitively, for emphasis in a title.
+ */
+function tokenRanges(text: string, query: string): [number, number][] {
+	const lower = text.toLowerCase()
+	const ranges: [number, number][] = []
+
+	for (const token of new Set(
+		query
+			.toLowerCase()
+			.split(/\s+/)
+			.filter((part) => part.length >= 2)
+	)) {
+		for (let index = lower.indexOf(token); index >= 0; index = lower.indexOf(token, index + token.length)) {
+			ranges.push([index, index + token.length])
+		}
+	}
+
+	return ranges.toSorted((a, b) => a[0] - b[0])
+}
+
+function emphasized(text: string, ranges: readonly [number, number][]): ReactNode[] {
 	const parts: ReactNode[] = []
 	let cursor = 0
 
-	for (const [start, end] of hit.highlights) {
+	for (const [start, end] of ranges) {
 		if (start < cursor) continue
 
-		parts.push(hit.snippet.slice(cursor, start), <mark key={start}>{hit.snippet.slice(start, end)}</mark>)
+		parts.push(text.slice(cursor, start), <mark key={start}>{text.slice(start, end)}</mark>)
 		cursor = end
 	}
 
-	parts.push(hit.snippet.slice(cursor))
+	parts.push(text.slice(cursor))
 
 	return parts
 }
 
-function title(hit: SearchHit): string {
-	return hit.hierarchy
-		.slice(1)
-		.filter((entry): entry is string => entry !== null)
-		.join(" › ")
+/**
+ * The deepest heading of a hit is its title.
+ * The headings between the category and it are its path.
+ */
+function headings(hit: SearchHit): { title: string; path: string[] } {
+	const named = hit.hierarchy.slice(1).filter((entry): entry is string => entry !== null)
+	const title = named.at(-1) ?? hit.url
+
+	return { title, path: named.slice(0, -1) }
+}
+
+function readRecent(key: string | undefined): string[] {
+	if (!key) return []
+
+	try {
+		const stored = tryParsingJSON<unknown>(globalThis.localStorage.getItem(key))
+
+		return Array.isArray(stored) ? stored.filter((entry): entry is string => typeof entry === "string") : []
+	} catch {
+		return []
+	}
+}
+
+function writeRecent(key: string | undefined, entries: readonly string[]): void {
+	if (!key) return
+
+	try {
+		globalThis.localStorage.setItem(key, stringifyJSON(entries))
+	} catch {
+		// Storage can be absent or blocked.
+		// The modal works without it.
+	}
 }
 
-export function SearchModal({ open, onClose, onNavigate, search }: SearchModalProps) {
+const SearchIcon = () => (
+	<svg className="mw-search__icon" viewBox="0 0 20 20" aria-hidden="true" focusable="false">
+		<circle cx="8.5" cy="8.5" r="5.5" fill="none" stroke="currentColor" strokeWidth="2" />
+		<path d="M13 13l4.5 4.5" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
+	</svg>
+)
+
+const Spinner = () => (
+	<svg className="mw-search__icon mw-search__icon--spinning" viewBox="0 0 20 20" aria-hidden="true" focusable="false">
+		<circle
+			cx="10"
+			cy="10"
+			r="7"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth="2"
+			strokeDasharray="22 22"
+			strokeLinecap="round"
+		/>
+	</svg>
+)
+
+export function SearchModal({ open, onClose, onNavigate, search, recentKey }: SearchModalProps) {
 	const dialogRef = useRef<HTMLDialogElement>(null)
 	const inputRef = useRef<HTMLInputElement>(null)
 	const baseID = useId()
@@ -100,6 +179,7 @@ export function SearchModal({ open, onClose, onNavigate, search }: SearchModalPr
 	const [settled, setSettled] = useState<Status>({ kind: "idle" })
 	const [selected, setSelected] = useState(0)
 	const [loading, setLoading] = useState(false)
+	const [recent, setRecent] = useState<string[]>([])
 	const trimmed = query.trim().slice(0, MAX_QUERY_LENGTH)
 	const debounced = useDebouncedValue(trimmed, DEBOUNCE_MS)
 
@@ -111,15 +191,16 @@ export function SearchModal({ open, onClose, onNavigate, search }: SearchModalPr
 		if (open && !dialog.open) {
 			dialog.showModal()
 			inputRef.current?.focus()
+			setRecent(readRecent(recentKey))
 		} else if (!open && dialog.open) {
 			dialog.close()
 		}
-	}, [open])
+	}, [open, recentKey])
 
 	useEffect(() => {
 		if (debounced === "") return
 
-		// Aborting the earlier request is what keeps a late response from replacing newer results.
+		// The abort of the earlier request keeps a late response from replacing newer results.
 		const controller = new AbortController()
 		const loadingTimer = setTimeout(() => setLoading(true), LOADING_ANNOUNCE_MS)
 
@@ -175,10 +256,29 @@ export function SearchModal({ open, onClose, onNavigate, search }: SearchModalPr
 
 	const ordered = groups.flatMap((group) => group.entries)
 	const optionID = (order: number) => `${baseID}-option-${order}`
+	const emphasis = response?.corrected ?? debounced
+
+	function remember(text: string) {
+		const entries = [text, ...recent.filter((entry) => entry !== text)].slice(0, RECENT_LIMIT)
+
+		setRecent(entries)
+		writeRecent(recentKey, entries)
+	}
+
+	function forget(text: string) {
+		const entries = recent.filter((entry) => entry !== text)
+
+		setRecent(entries)
+		writeRecent(recentKey, entries)
+	}
 
 	function go(hit: SearchHit) {
 		const href = hitHref(hit)
 
+		if (trimmed !== "") {
+			remember(trimmed)
+		}
+
 		onClose()
 
 		if (onNavigate) {
@@ -243,6 +343,9 @@ export function SearchModal({ open, onClose, onNavigate, search }: SearchModalPr
 		go(hit)
 	}
 
+	const showRecent = trimmed === "" && recent.length > 0
+	const noResults = response !== undefined && response.hits.length === 0
+
 	return (
 		<dialog
 			ref={dialogRef}
@@ -252,66 +355,124 @@ export function SearchModal({ open, onClose, onNavigate, search }: SearchModalPr
 			onClick={onDialogClick}
 		>
 			<form role="search" className="mw-search__form" onSubmit={(event) => event.preventDefault()}>
-				<input
-					ref={inputRef}
-					type="search"
-					className="mw-search__input"
-					role="combobox"
-					aria-label="Search the documentation"
-					aria-autocomplete="list"
-					aria-expanded={ordered.length > 0}
-					aria-controls={listboxID}
-					aria-activedescendant={ordered.length ? optionID(selected) : undefined}
-					autoComplete="off"
-					spellCheck={false}
-					maxLength={MAX_QUERY_LENGTH}
-					placeholder="Search the documentation"
-					value={query}
-					onChange={(event) => setQuery(event.target.value)}
-					onKeyDown={onKeyDown}
-				/>
+				<label className="mw-search__field">
+					{loading ? <Spinner /> : <SearchIcon />}
+					<input
+						ref={inputRef}
+						type="search"
+						className="mw-search__input"
+						role="combobox"
+						aria-label="Search the documentation"
+						aria-autocomplete="list"
+						aria-expanded={ordered.length > 0}
+						aria-controls={listboxID}
+						aria-activedescendant={ordered.length ? optionID(selected) : undefined}
+						autoComplete="off"
+						spellCheck={false}
+						maxLength={MAX_QUERY_LENGTH}
+						placeholder="Search the documentation"
+						value={query}
+						onChange={(event) => setQuery(event.target.value)}
+						onKeyDown={onKeyDown}
+					/>
+				</label>
+				<button type="button" className="mw-search__cancel" onClick={() => dialogRef.current?.close()}>
+					Cancel
+				</button>
 			</form>
 
-			{response?.corrected !== undefined && (
+			{response?.corrected != null && (
 				<p className="mw-search__corrected">Showing results for “{response.corrected}”</p>
 			)}
 
-			<div id={listboxID} role="listbox" aria-label="Search results" className="mw-search__results">
-				{groups.map((group, groupIndex) => (
-					<div
-						key={group.category}
-						role="group"
-						aria-labelledby={`${baseID}-group-${groupIndex}`}
-						className="mw-search__group"
-					>
-						<div id={`${baseID}-group-${groupIndex}`} className="mw-search__category">
-							{group.category}
+			<div className="mw-search__body">
+				{showRecent && (
+					<section className="mw-search__recent" aria-label="Recent searches">
+						<div className="mw-search__category">Recent</div>
+						<ul className="mw-search__recent-list">
+							{recent.map((entry) => (
+								<li key={entry} className="mw-search__recent-item">
+									<button type="button" className="mw-search__recent-query" onClick={() => setQuery(entry)}>
+										{entry}
+									</button>
+									<button
+										type="button"
+										className="mw-search__recent-remove"
+										aria-label={`Remove “${entry}” from recent searches`}
+										onClick={() => forget(entry)}
+									>
+										×
+									</button>
+								</li>
+							))}
+						</ul>
+					</section>
+				)}
+
+				{noResults && (
+					<p className="mw-search__empty">
+						No results for “{response.query}”. Try a different spelling or a shorter query.
+					</p>
+				)}
+
+				<div id={listboxID} role="listbox" aria-label="Search results" className="mw-search__results">
+					{groups.map((group, groupIndex) => (
+						<div
+							key={group.category}
+							role="group"
+							aria-labelledby={`${baseID}-group-${groupIndex}`}
+							className="mw-search__group"
+						>
+							<div id={`${baseID}-group-${groupIndex}`} className="mw-search__category">
+								{group.category}
+							</div>
+							{group.entries.map(({ hit, order }) => {
+								const { title, path } = headings(hit)
+
+								return (
+									// The option is the link itself: an option may not contain an interactive element, and
+									// `option` is an allowed role on `a[href]`, which keeps the URL for open-in-new-tab.
+									<a
+										key={order}
+										id={optionID(order)}
+										role="option"
+										aria-selected={order === selected}
+										href={hitHref(hit)}
+										tabIndex={-1}
+										className={`mw-search__option ${hit.anchor === "" ? "mw-search__option--page" : "mw-search__option--section"}`}
+										onPointerMove={() => setSelected(order)}
+										onClick={(event) => onLinkClick(event, hit)}
+									>
+										{path.length > 0 && <span className="mw-search__path">{path.join(" › ")}</span>}
+										<span className="mw-search__title">{emphasized(title, tokenRanges(title, emphasis))}</span>
+										{hit.snippet !== "" && (
+											<span className="mw-search__snippet">{emphasized(hit.snippet, hit.highlights)}</span>
+										)}
+									</a>
+								)
+							})}
 						</div>
-						{group.entries.map(({ hit, order }) => (
-							// The option is the link itself: an option may not contain an interactive element, and
-							// `option` is an allowed role on `a[href]`, which keeps the URL for open-in-new-tab.
-							<a
-								key={order}
-								id={optionID(order)}
-								role="option"
-								aria-selected={order === selected}
-								href={hitHref(hit)}
-								tabIndex={-1}
-								className="mw-search__option"
-								onPointerMove={() => setSelected(order)}
-								onClick={(event) => onLinkClick(event, hit)}
-							>
-								<span className="mw-search__title">{title(hit)}</span>
-								{hit.snippet !== "" && <span className="mw-search__snippet">{highlighted(hit)}</span>}
-							</a>
-						))}
-					</div>
-				))}
+					))}
+				</div>
 			</div>
 
-			<p aria-live="polite" className="mw-search__status">
-				{statusText(announced)}
-			</p>
+			<footer className="mw-search__footer">
+				<p aria-live="polite" className="mw-search__status">
+					{statusText(announced)}
+				</p>
+				<ul className="mw-search__hints" aria-label="Keyboard shortcuts">
+					<li>
+						<kbd>↵</kbd> open
+					</li>
+					<li>
+						<kbd>↑</kbd>
+						<kbd>↓</kbd> move
+					</li>
+					<li>
+						<kbd>esc</kbd> close
+					</li>
+				</ul>
+			</footer>
 		</dialog>
 	)
 }

package/lib/search/search.css

@@ -2,12 +2,12 @@
  * The docs search modal.
  *
  * The native <dialog> has zero padding, so the only click whose target is the dialog element itself is a click on
- * the backdrop. The padding sits on the form, the results and the status line instead.
+ * the backdrop. The padding sits on the form, the body and the footer instead.
  *
  * The selected option is marked by an inset accent bar as well as a fill, so the selection holds 3:1 against the
  * panel without depending on the fill alone. Colors, radii, spacing, type and motion read semantic tokens from
  * tokens.css. The layout literals are the panel width and height caps, the 44px input height, the 3px selection
- * bar and the backdrop scrim, for which no token exists.
+ * bar, the 640px phone breakpoint, the icon size and the backdrop scrim, for which no token exists.
  * --------------------------------------------------------------------------- */
 
 .mw-search {
@@ -36,27 +36,64 @@
 }
 
 .mw-search__form {
-	padding: var(--space-5);
+	display: flex;
+	gap: var(--space-3);
+	align-items: center;
+	padding: var(--space-4) var(--space-5);
 	border-bottom: 1px solid var(--color-separator);
 }
 
-.mw-search__input {
-	width: 100%;
+.mw-search__field {
+	display: flex;
+	flex: 1 1 auto;
+	gap: var(--space-3);
+	align-items: center;
 	min-height: 44px;
-	padding: var(--space-3) var(--space-4);
+	padding: 0 var(--space-4);
 	color: var(--control-foreground);
-	font: inherit;
-	font-size: var(--font-size-body);
 	background: var(--control-background);
 	border: 1px solid var(--control-border);
 	border-radius: var(--radius-control);
 }
 
-.mw-search__input:focus-visible {
+.mw-search__field:focus-within {
 	outline: 2px solid var(--color-accent);
 	outline-offset: 1px;
 }
 
+.mw-search__icon {
+	flex: 0 0 auto;
+	width: 20px;
+	height: 20px;
+	color: var(--color-accent);
+}
+
+.mw-search__icon--spinning {
+	animation: mw-search-spin 0.8s linear infinite;
+}
+
+.mw-search__input {
+	flex: 1 1 auto;
+	min-width: 0;
+	padding: var(--space-3) 0;
+	color: inherit;
+	font: inherit;
+	font-size: var(--font-size-body);
+	background: transparent;
+	border: 0;
+	outline: 0;
+}
+
+.mw-search__cancel {
+	display: none;
+	padding: var(--space-2) var(--space-3);
+	color: var(--color-accent);
+	font: inherit;
+	background: transparent;
+	border: 0;
+	cursor: pointer;
+}
+
 .mw-search__corrected {
 	margin: 0;
 	padding: var(--space-3) var(--space-5) 0;
@@ -64,7 +101,7 @@
 	font-size: var(--font-size-footnote);
 }
 
-.mw-search__results {
+.mw-search__body {
 	flex: 1 1 auto;
 	min-height: 0;
 	padding: var(--space-3) var(--space-4);
@@ -78,6 +115,57 @@
 	font-weight: var(--font-weight-semibold);
 }
 
+.mw-search__recent-list {
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.mw-search__recent-item {
+	display: flex;
+	align-items: center;
+	border-radius: var(--radius-control);
+}
+
+.mw-search__recent-item:hover {
+	background: var(--color-background-sunken);
+}
+
+.mw-search__recent-query {
+	flex: 1 1 auto;
+	padding: var(--space-3) var(--space-4);
+	color: inherit;
+	font: inherit;
+	text-align: left;
+	background: transparent;
+	border: 0;
+	cursor: pointer;
+}
+
+.mw-search__recent-remove {
+	flex: 0 0 auto;
+	width: 44px;
+	height: 44px;
+	color: var(--color-text-secondary);
+	font: inherit;
+	font-size: var(--font-size-body);
+	background: transparent;
+	border: 0;
+	cursor: pointer;
+}
+
+.mw-search__recent-remove:hover,
+.mw-search__recent-remove:focus-visible {
+	color: var(--color-text-primary);
+}
+
+.mw-search__empty {
+	margin: 0;
+	padding: var(--space-5) var(--space-4);
+	color: var(--color-text-secondary);
+	text-align: center;
+}
+
 .mw-search__option {
 	border-radius: var(--radius-control);
 	display: flex;
@@ -88,11 +176,20 @@
 	text-decoration: none;
 }
 
+.mw-search__option--section {
+	padding-left: calc(var(--space-4) + var(--space-5));
+}
+
 .mw-search__option[aria-selected="true"] {
 	background: var(--color-background-sunken);
 	box-shadow: inset 3px 0 0 var(--color-accent);
 }
 
+.mw-search__path {
+	color: var(--color-text-secondary);
+	font-size: var(--font-size-footnote);
+}
+
 .mw-search__title {
 	font-size: var(--font-size-subheadline);
 	font-weight: var(--font-weight-semibold);
@@ -103,31 +200,66 @@
 	font-size: var(--font-size-footnote);
 }
 
-.mw-search__snippet mark {
+.mw-search mark {
 	color: var(--color-text-primary);
 	font-weight: var(--font-weight-semibold);
 	background: var(--color-accent-background);
 	border-radius: var(--radius-tick);
 }
 
-.mw-search__status {
-	margin: 0;
+.mw-search__footer {
+	display: flex;
+	gap: var(--space-4);
+	align-items: center;
+	justify-content: space-between;
 	padding: var(--space-3) var(--space-5);
 	color: var(--color-text-secondary);
 	font-size: var(--font-size-footnote);
 	border-top: 1px solid var(--color-separator);
 }
 
-/* An empty live region stays rendered, because a region that appears with its text is often not announced. */
-.mw-search__status:empty {
-	position: absolute;
-	width: 1px;
-	height: 1px;
+.mw-search__status {
+	margin: 0;
+}
+
+.mw-search__hints {
+	display: flex;
+	gap: var(--space-4);
+	margin: 0;
 	padding: 0;
-	overflow: hidden;
-	border: 0;
-	clip-path: inset(50%);
-	white-space: nowrap;
+	list-style: none;
+}
+
+.mw-search__hints kbd {
+	display: inline-block;
+	min-width: 1.5em;
+	margin-right: var(--space-1);
+	padding: 0 var(--space-1);
+	font: inherit;
+	text-align: center;
+	background: var(--color-background-sunken);
+	border: 1px solid var(--control-border);
+	border-radius: var(--radius-tick);
+}
+
+@media (width <= 640px) {
+	.mw-search {
+		width: 100vw;
+		max-width: none;
+		height: 100dvh;
+		max-height: none;
+		margin: 0;
+		border: 0;
+		border-radius: 0;
+	}
+
+	.mw-search__cancel {
+		display: inline-block;
+	}
+
+	.mw-search__hints {
+		display: none;
+	}
 }
 
 @media (prefers-reduced-motion: no-preference) {
@@ -142,3 +274,9 @@
 		transform: translateY(calc(var(--space-4) * -1));
 	}
 }
+
+@keyframes mw-search-spin {
+	to {
+		transform: rotate(360deg);
+	}
+}

package/lib/search/types.ts

@@ -61,7 +61,8 @@ export interface SearchResponse {
 	query: string
 	/**
 	 * The text actually searched when a token was corrected against the vocabulary.
+	 * It is `null` when no token was.
 	 */
-	corrected?: string
+	corrected: string | null
 	hits: SearchHit[]
 }

package/out/common/About.d.ts

@@ -13,7 +13,7 @@ export interface AboutProps {
      * Set false where the host is already the disclosure, because a summary repeating
      * an About button's words is one control too many.
      *
-     * @default true
+     * @defaultValue `true`
      */
     collapsible?: boolean;
 }