@mailwoman/react 9.4.0 → 10.0.0

package/lib/map/GeocoderControls.tsx

@@ -3,28 +3,36 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<GeocoderControls>` — the geocoder's floating control panel, assembled from the geocoder-specific units
- *   (VersionPicker / CompareToggle / BackendControl / PlaceAutocomplete / ResultPanel) and the REUSED
- *   pipeline units (QueryForm / PresetChips / LoadingIndicator). It reads the injected {@link GeocoderRuntime}
- *   for ready/version/backend/loading state and threads the {@link useGeocode} + {@link usePlaceAutocomplete}
- *   + {@link useCompareState} hooks into the controls. Host-specific visualizers arrive via {@link GeocoderPanels}.
+ *   The geocoder's chrome over the map: a search pill on top, example chips on one line beneath it, a control column
+ *   down the right edge, and a result sheet that rises from the bottom when there is something to show.
  *
- *   NODE-SAFE: pure React + the shared/geocoder units, no maplibre. It rides `@mailwoman/react/map` as a
- *   geocoder-specific control, not for WebGL.
+ *   It replaces a 400px full-height panel that carried every control at once. The layout is the one the reference
+ *   map apps use, and the reason is the map: chrome that floats over it leaves the map the page, where a slab makes
+ *   the map the leftover third.
+ *
+ *   NODE-SAFE: pure React + the shared units, no maplibre.
  */
 
-import type { ReactNode } from "react"
+import { type ReactNode, useCallback, useState } from "react"
+import type { MapInstance } from "react-map-gl/maplibre"
 
 import type { GeocoderPanels, GeocoderRuntime } from "#map/types"
 import type { UseCompareState } from "#map/useCompareState"
 import type { UseGeocode } from "#map/useGeocode"
+import { useMapBearing } from "#map/useMapBearing"
+import { useMapLabelPick } from "#map/useMapLabelPick"
 import type { UsePlaceAutocomplete } from "#map/usePlaceAutocomplete"
 
 import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
-import { PresetChips, type Preset } from "../common/PresetChips.tsx"
-import { QueryForm } from "../pipeline/QueryForm.tsx"
+import type { Preset } from "../common/PresetChips.tsx"
 import { BackendControl } from "./BackendControl.tsx"
 import { CompareToggle } from "./CompareToggle.tsx"
+import { MapChipRow } from "./MapChipRow.tsx"
+import { MapCompass } from "./MapCompass.tsx"
+import { MapControlButton, MapControlGroup, MapControlStack } from "./MapControlStack.tsx"
+import { MapProgressBar } from "./MapProgressBar.tsx"
+import { MapSearchBar } from "./MapSearchBar.tsx"
+import { MapSheet } from "./MapSheet.tsx"
 import { PlaceAutocomplete } from "./PlaceAutocomplete.tsx"
 import { ResultPanel } from "./ResultPanel.tsx"
 import { VersionPicker } from "./VersionPicker.tsx"
@@ -58,6 +66,16 @@ export interface GeocoderControlsProps {
 	 * Input placeholder.
 	 */
 	placeholder: string
+	/**
+	 * The live map, for the controls that read it: the compass takes its bearing, the host's layer control reads its
+	 * style. `null` until react-map-gl instantiates the map.
+	 */
+	map?: MapInstance | null
+	/**
+	 * Fired with the query whenever one is submitted, before the parse starts. The host writes it into the URL; this
+	 * package never touches `location`, because the address bar is the app's state, not a control's.
+	 */
+	onSubmitQuery?: (query: string) => void
 	/**
 	 * Select a model version (the composed geocoder also clears a now-colliding compare selection).
 	 */
@@ -66,10 +84,22 @@ export interface GeocoderControlsProps {
 	 * Toggle the forced WASM backend.
 	 */
 	onForceWASMChange: (forceWASM: boolean) => void
+	/**
+	 * Open the developer panel on mount. The model version, the backend readout and compare live inside it: they read on
+	 * the model rather than on an address, and above the query field they were the first thing every visitor met.
+	 *
+	 * @default false
+	 */
+	developer?: boolean
 }
 
 /**
- * The floating control panel.
+ * Which side sheet is open. At most one, because they share an edge and a phone gives each the whole panel.
+ */
+type SheetName = "about" | "layers" | "developer" | null
+
+/**
+ * The chrome. Everything positioned here floats over the map; nothing occupies a column of the page.
  */
 export function GeocoderControls({
 	runtime,
@@ -79,115 +109,244 @@ export function GeocoderControls({
 	panels,
 	presets,
 	placeholder,
+	map = null,
+	onSubmitQuery,
 	onSelectVersion,
 	onForceWASMChange,
+	developer = false,
 }: GeocoderControlsProps): ReactNode {
 	const versions = runtime.availableVersions ?? []
 	const { busy, result, selectedCandidate } = geocode
 	const loading = runtime.loading
 	const errorMessage = geocode.parseError ?? runtime.errorMessage ?? null
 
-	return (
-		<section className="mw-demo-controls">
-			{panels.header}
-			{panels.releaseInfo}
-
-			<VersionPicker
-				versions={versions}
-				selected={runtime.selectedVersion ?? null}
-				onSelect={onSelectVersion}
-				disabled={busy}
-			/>
+	// One sheet at a time. Two open at once stack on the same edge, and on a phone each is the full panel.
+	const [openSheet, setOpenSheet] = useState<SheetName>(developer ? "developer" : null)
+	const { bearing, resetNorth } = useMapBearing(map)
 
-			<BackendControl
-				activeBackend={runtime.activeBackend}
-				forceWASM={runtime.forceWASM ?? false}
-				onForceWASMChange={onForceWASMChange}
-			/>
+	const toggleSheet = (name: Exclude<SheetName, null>) => setOpenSheet((current) => (current === name ? null : name))
+	const closeSheet = useCallback(() => setOpenSheet(null), [])
 
-			<CompareToggle
-				versions={versions}
-				primaryVersion={runtime.selectedVersion ?? null}
-				compareMode={compare.compareMode}
-				onCompareModeChange={compare.setCompareMode}
-				compareVersion={compare.compareVersion}
-				onCompareVersionChange={compare.setCompareVersion}
-				disabled={busy}
-			/>
+	// Every path that starts a query goes through here, so the URL is written in exactly one place — the event that
+	// caused it, rather than an effect watching the result after the fact.
+	const runQuery = useCallback(
+		(query: string) => {
+			onSubmitQuery?.(query)
+			void geocode.submit(query)
+		},
+		[onSubmitQuery, geocode]
+	)
 
-			<QueryForm
-				value={geocode.text}
-				onChange={geocode.setText}
-				onSubmit={geocode.submit}
-				disabled={!runtime.ready}
-				busy={busy}
-				placeholder={placeholder}
-				onKeyDown={autocomplete.onInputKeyDown}
-				inputProps={autocomplete.inputProps}
-			/>
+	// A label on the map is a search a visitor already typed by pointing at it.
+	const pickLabel = useCallback(
+		(name: string) => {
+			geocode.setText(name)
+			geocode.reset()
+			runQuery(name)
+		},
+		[geocode, runQuery]
+	)
 
-			{panels.bias}
+	useMapLabelPick(map, pickLabel)
 
-			<PlaceAutocomplete
-				suggestions={autocomplete.suggestions}
-				activeIndex={autocomplete.activeIndex}
-				onPick={autocomplete.pick}
-				onHover={autocomplete.setActiveIndex}
-				listboxID={autocomplete.listboxID}
-				optionID={autocomplete.optionID}
-			/>
+	const chips = presets.map((preset) => ({ label: preset.label, value: preset.value }))
+	// The bundle load no longer opens the result sheet: it reports on the bar at the top of the viewport and in the
+	// footer, so an empty sheet does not sit over the map for the length of a 38 MB download.
+	const showSheet = Boolean(busy || result || errorMessage)
+
+	const bundleLoading = Boolean(loading && !runtime.ready)
+	const steps = loading?.stepLabels.length ?? 0
 
-			<PresetChips
-				presets={presets}
-				disabled={!runtime.ready || busy}
-				onPick={(value) => {
-					geocode.setText(value)
-					geocode.reset()
-				}}
-				trailing={panels.permalink ? panels.permalink(geocode.text) : null}
+	return (
+		<>
+			<MapProgressBar
+				active={bundleLoading}
+				fraction={steps ? ((loading?.stepIndex ?? 0) + 1) / steps : null}
+				label="Loading the geocoder"
 			/>
 
-			{loading && !runtime.ready ? (
-				<LoadingIndicator
-					mode="staged"
-					steps={loading.stepLabels.length ? loading.stepLabels : undefined}
-					activeStep={loading.stepIndex}
-					label={loading.progress}
+			<div className="mw-map-chrome mw-map-chrome--top">
+				<form
+					className="mw-map-chrome__search"
+					onSubmit={(event) => {
+						event.preventDefault()
+						runQuery(geocode.text)
+					}}
+				>
+					{/*
+					 * `type="search"` brings its own clear button, so the pill carries no trailing slot: a second cross
+					 * beside the native one is two controls for one job, and the spinner that used to live there changed
+					 * the field's height on every submit.
+					 */}
+					<MapSearchBar label="Search addresses" leading={<span aria-hidden="true">⌕</span>} busy={busy}>
+						<input
+							id="mw-pipeline-input"
+							type="search"
+							aria-label="Address"
+							value={geocode.text}
+							onChange={(event) => geocode.setText(event.target.value)}
+							disabled={!runtime.ready}
+							placeholder={placeholder}
+							onKeyDown={autocomplete.onInputKeyDown}
+							{...autocomplete.inputProps}
+						/>
+					</MapSearchBar>
+				</form>
+
+				<PlaceAutocomplete
+					suggestions={autocomplete.suggestions}
+					activeIndex={autocomplete.activeIndex}
+					onPick={autocomplete.pick}
+					onHover={autocomplete.setActiveIndex}
+					listboxID={autocomplete.listboxID}
+					optionID={autocomplete.optionID}
 				/>
+
+				<MapChipRow
+					chips={chips}
+					label="Example addresses"
+					activeValue={geocode.text}
+					disabled={!runtime.ready || busy}
+					onPick={(value) => {
+						geocode.setText(value)
+						geocode.reset()
+						runQuery(value)
+					}}
+				/>
+
+				{panels.bias}
+			</div>
+
+			{/*
+			 * Every floating control lives in this one column, so nothing can land on top of anything else: the layer
+			 * control joins the capsule rather than sitting in the left column, and the compass takes its own capsule
+			 * below because it comes and goes and would otherwise resize the one above it.
+			 */}
+			<MapControlStack label="Map controls">
+				<MapControlGroup>
+					<MapControlButton
+						label="About this geocoder"
+						active={openSheet === "about"}
+						onPress={() => toggleSheet("about")}
+					>
+						<span aria-hidden="true">i</span>
+					</MapControlButton>
+
+					{panels.layers ? (
+						<MapControlButton label="Map layers" active={openSheet === "layers"} onPress={() => toggleSheet("layers")}>
+							<span aria-hidden="true">≡</span>
+						</MapControlButton>
+					) : null}
+
+					<MapControlButton
+						label="Developer controls"
+						active={openSheet === "developer"}
+						onPress={() => toggleSheet("developer")}
+					>
+						<span aria-hidden="true">⚙</span>
+					</MapControlButton>
+				</MapControlGroup>
+
+				<MapControlGroup className="mw-map-control-group--compass">
+					<MapCompass bearing={bearing} onResetNorth={resetNorth} />
+				</MapControlGroup>
+			</MapControlStack>
+
+			{openSheet === "about" ? (
+				<MapSheet title="About" onClose={closeSheet}>
+					{panels.header}
+				</MapSheet>
 			) : null}
-			{errorMessage ? <p className="mw-error">{errorMessage}</p> : null}
-
-			{panels.aboveResult ? panels.aboveResult({ result }) : null}
-
-			{busy ? (
-				<div className="mw-result">
-					<LoadingIndicator mode="staged" steps={runtime.parseStageLabels} activeStep={geocode.parseStage} />
-				</div>
-			) : result ? (
-				panels.result ? (
-					panels.result({
-						result,
-						selectedCandidate,
-						selectedCandidateIndex: geocode.selectedCandidateIndex,
-						onSelectCandidate: geocode.selectCandidate,
-					})
-				) : (
-					<ResultPanel
-						result={result}
-						selectedCandidate={selectedCandidate}
-						selectedCandidateIndex={geocode.selectedCandidateIndex}
-						onSelectCandidate={geocode.selectCandidate}
-						extras={panels.extras}
-						failure={panels.failure}
-					/>
-				)
+
+			{openSheet === "layers" ? (
+				<MapSheet title="Layers" onClose={closeSheet}>
+					{panels.layers?.({ map })}
+				</MapSheet>
 			) : null}
 
-			{panels.compare
-				? panels.compare({ result, compareMode: compare.compareMode, compareVersion: compare.compareVersion })
-				: null}
+			{openSheet === "developer" ? (
+				<MapSheet title="Developer" onClose={closeSheet}>
+					{panels.releaseInfo ? (
+						<div className="mw-map-sheet__row">
+							<span className="mw-map-sheet__label">This release</span>
+							{panels.releaseInfo}
+						</div>
+					) : null}
+
+					<div className="mw-map-sheet__row">
+						<VersionPicker
+							versions={versions}
+							selected={runtime.selectedVersion ?? null}
+							onSelect={onSelectVersion}
+							disabled={busy}
+						/>
+					</div>
+
+					<div className="mw-map-sheet__row">
+						<BackendControl
+							activeBackend={runtime.activeBackend}
+							forceWASM={runtime.forceWASM ?? false}
+							onForceWASMChange={onForceWASMChange}
+						/>
+					</div>
+
+					<div className="mw-map-sheet__row">
+						<CompareToggle
+							versions={versions}
+							primaryVersion={runtime.selectedVersion ?? null}
+							compareMode={compare.compareMode}
+							onCompareModeChange={compare.setCompareMode}
+							compareVersion={compare.compareVersion}
+							onCompareVersionChange={compare.setCompareVersion}
+							disabled={busy}
+						/>
+					</div>
+
+					{panels.developerExtras}
+				</MapSheet>
+			) : null}
+
+			{showSheet ? (
+				<section className="mw-map-sheet mw-map-sheet--bottom" aria-label="Result">
+					<div className="mw-map-sheet__handle" aria-hidden="true" />
+
+					{errorMessage ? <p className="mw-error">{errorMessage}</p> : null}
+
+					{panels.aboveResult ? panels.aboveResult({ result }) : null}
+
+					{busy ? (
+						<div className="mw-result">
+							<LoadingIndicator mode="staged" steps={runtime.parseStageLabels} activeStep={geocode.parseStage} />
+						</div>
+					) : result ? (
+						panels.result ? (
+							panels.result({
+								result,
+								selectedCandidate,
+								selectedCandidateIndex: geocode.selectedCandidateIndex,
+								onSelectCandidate: geocode.selectCandidate,
+							})
+						) : (
+							<ResultPanel
+								result={result}
+								selectedCandidate={selectedCandidate}
+								selectedCandidateIndex={geocode.selectedCandidateIndex}
+								onSelectCandidate={geocode.selectCandidate}
+								extras={panels.extras}
+								failure={panels.failure}
+							/>
+						)
+					) : null}
+
+					{panels.compare
+						? panels.compare({ result, compareMode: compare.compareMode, compareVersion: compare.compareVersion })
+						: null}
+
+					{panels.permalink ? <div className="mw-map-sheet__actions">{panels.permalink(geocode.text)}</div> : null}
+				</section>
+			) : null}
 
 			{panels.footer}
-		</section>
+		</>
 	)
 }

package/lib/map/MapChipRow.tsx

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapChipRow>` — the row of example queries under a search bar.
+ *
+ *   It SCROLLS horizontally and never wraps. Earth's twelve examples wrapped down five ragged rows (3/3/2/1/1/1) and
+ *   took a third of the panel; one scrolling line is the shape the reference map apps use, and it costs a fixed
+ *   height whatever the number of examples.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapChip {
+	/**
+	 * What the chip reads.
+	 */
+	label: string
+	/**
+	 * The query the chip stands for, handed back on press. Defaults to the label.
+	 */
+	value?: string
+	/**
+	 * Rendered before the label — a category mark.
+	 */
+	icon?: ReactNode
+}
+
+export interface MapChipRowProps {
+	chips: MapChip[]
+	/**
+	 * Fired with the chip's `value` (or its label) when one is pressed.
+	 */
+	onPick: (value: string) => void
+	/**
+	 * The chip matching this value reads as pressed.
+	 */
+	activeValue?: string
+	disabled?: boolean
+	className?: string
+	/**
+	 * Accessible name for the row, e.g. "Example addresses".
+	 */
+	label?: string
+}
+
+export function MapChipRow({ chips, onPick, activeValue, disabled, className, label }: MapChipRowProps): ReactNode {
+	if (!chips.length) return null
+
+	return (
+		<div className={cx("mw-map-chiprow", className)} role="group" aria-label={label}>
+			{chips.map((chip) => {
+				const value = chip.value ?? chip.label
+				const active = value === activeValue
+
+				return (
+					<button
+						key={value}
+						type="button"
+						className={cx("mw-map-chip", active && "mw-map-chip--active")}
+						aria-pressed={active}
+						disabled={disabled}
+						onClick={() => onPick(value)}
+					>
+						{chip.icon ? <span className="mw-map-chip__icon">{chip.icon}</span> : null}
+						{chip.label}
+					</button>
+				)
+			})}
+		</div>
+	)
+}

package/lib/map/MapCompass.tsx

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapCompass>` — the needle that appears when the map leaves north and fades out when it returns.
+ *
+ *   It is a compass ROSE, the way the reference map apps draw it: a ringed dial carrying a two-tone needle whose red
+ *   half points north and whose pale half points south. A single-color arrow cannot say which end is north, so a
+ *   reader has to already know the convention to read it; two tones say it outright. There is no `N` on the dial —
+ *   at this size the letter and the needle's north tip want the same few pixels, and the tip is the clearer of them.
+ *
+ *   The whole dial counter-rotates the bearing, so the needle keeps pointing at true north while the map turns under
+ *   it. Pressing it returns the map to north, which is why the control is a button rather than an ornament.
+ *
+ *   It stays mounted through the fade rather than unmounting on the bearing crossing zero, because a control that
+ *   vanishes mid-gesture is the thing that reads as a glitch. `HIDE_BELOW_DEGREES` is the dead zone: a map settled by
+ *   a snap-to-north lands a fraction off zero, and a compass that lingers over that fraction never goes away.
+ *
+ *   Under `prefers-reduced-motion` it appears and disappears with no transition, and the dial still rotates —
+ *   rotation IS the information, not decoration.
+ *
+ *   NODE-SAFE: pure React, no maplibre. The host reads the bearing off its own map and passes it in.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+/**
+ * Below this many degrees off north the compass is treated as pointing north and fades out.
+ */
+const HIDE_BELOW_DEGREES = 0.5
+
+export interface MapCompassProps {
+	/**
+	 * The map's bearing in degrees, as MapLibre reports it: 0 is north, positive is counter-clockwise.
+	 */
+	bearing: number
+	/**
+	 * Fired when the compass is pressed — the host resets its map to north.
+	 */
+	onResetNorth: () => void
+	/**
+	 * The control's accessible name. @default "Reset bearing to north"
+	 */
+	label?: string
+	className?: string
+}
+
+export function MapCompass({ bearing, onResetNorth, label, className }: MapCompassProps): ReactNode {
+	const facingNorth = Math.abs(bearing) < HIDE_BELOW_DEGREES
+
+	return (
+		<button
+			type="button"
+			className={cx("mw-map-compass", facingNorth && "mw-map-compass--north", className)}
+			aria-label={label ?? "Reset bearing to north"}
+			title={label ?? "Reset bearing to north"}
+			// Out of the tab order and out of the accessibility tree while it is invisible, so a keyboard reaches only
+			// the controls a pointer can see.
+			aria-hidden={facingNorth}
+			tabIndex={facingNorth ? -1 : 0}
+			onClick={onResetNorth}
+		>
+			<svg viewBox="0 0 32 32" width="26" height="26" aria-hidden="true" focusable="false">
+				<g style={{ transform: `rotate(${-bearing}deg)`, transformOrigin: "16px 16px" }}>
+					<circle cx="16" cy="16" r="12.5" className="mw-map-compass__dial" />
+
+					{/* North, then south. Two triangles meeting at the hub rather than one arrow through it. */}
+					<path d="M16 5.5 L20.5 16 L16 16 Z M16 5.5 L11.5 16 L16 16 Z" className="mw-map-compass__north" />
+					<path d="M16 26.5 L20.5 16 L16 16 Z M16 26.5 L11.5 16 L16 16 Z" className="mw-map-compass__south" />
+				</g>
+			</svg>
+		</button>
+	)
+}

package/lib/map/MapControlStack.tsx

@@ -0,0 +1,98 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapControlStack>` — the column of map controls down one edge, and `<MapControlButton>`, the control inside it.
+ *
+ *   Controls sit in GROUPS: a group is one glass capsule with hairlines between its buttons, and separate groups are
+ *   separate capsules with a gap. That grouping is the whole layout idea — related controls read as one object, and
+ *   an unrelated one (a compass that comes and goes) does not join a capsule it would resize.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapControlButtonProps {
+	/**
+	 * The mark inside the control — an SVG icon or a single glyph.
+	 */
+	children: ReactNode
+	/**
+	 * The control's accessible name. Required: the visible content is a mark, not a word.
+	 */
+	label: string
+	onPress: () => void
+	/**
+	 * Reads as active, for a control that toggles a layer or a mode.
+	 */
+	active?: boolean
+	disabled?: boolean
+	className?: string
+}
+
+export function MapControlButton({
+	children,
+	label,
+	onPress,
+	active,
+	disabled,
+	className,
+}: MapControlButtonProps): ReactNode {
+	return (
+		<button
+			type="button"
+			className={cx("mw-map-control", active && "mw-map-control--active", className)}
+			aria-label={label}
+			aria-pressed={active}
+			title={label}
+			disabled={disabled}
+			onClick={onPress}
+		>
+			{children}
+		</button>
+	)
+}
+
+export interface MapControlGroupProps {
+	children: ReactNode
+	className?: string
+}
+
+/**
+ * One capsule. Put related controls in the same group; give an unrelated one its own.
+ */
+export function MapControlGroup({ children, className }: MapControlGroupProps): ReactNode {
+	return <div className={cx("mw-map-control-group", className)}>{children}</div>
+}
+
+export interface MapControlStackProps {
+	/**
+	 * Groups, top to bottom.
+	 */
+	children: ReactNode
+	/**
+	 * Which edge the column sits against. @default "right"
+	 */
+	side?: "left" | "right"
+	className?: string
+	/**
+	 * Accessible name for the column, e.g. "Map controls".
+	 */
+	label?: string
+}
+
+export function MapControlStack({ children, side = "right", className, label }: MapControlStackProps): ReactNode {
+	return (
+		<div
+			className={cx("mw-map-control-stack", `mw-map-control-stack--${side}`, className)}
+			role="group"
+			aria-label={label}
+		>
+			{children}
+		</div>
+	)
+}