@mailwoman/react 10.0.0 → 10.1.0

package/lib/map/GeocoderControls.tsx

@@ -2,18 +2,10 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   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.
- *
- *   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, useCallback, useState } from "react"
+import type React from "react"
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react"
 import type { MapInstance } from "react-map-gl/maplibre"
 
 import type { GeocoderPanels, GeocoderRuntime } from "#map/types"
@@ -27,79 +19,74 @@ import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
 import type { Preset } from "../common/PresetChips.tsx"
 import { BackendControl } from "./BackendControl.tsx"
 import { CompareToggle } from "./CompareToggle.tsx"
+import { DebugInfo } from "./DebugInfo.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 { MapSearchBar, SearchGlyph } from "./MapSearchBar.tsx"
+import { MapSheet, SheetClose } from "./MapSheet.tsx"
 import { PlaceAutocomplete } from "./PlaceAutocomplete.tsx"
 import { ResultPanel } from "./ResultPanel.tsx"
 import { VersionPicker } from "./VersionPicker.tsx"
 
+/**
+ * Props for {@linkcode GeocoderControls}.
+ */
 export interface GeocoderControlsProps {
-	/**
-	 * The injected geocoder runtime.
-	 */
 	runtime: GeocoderRuntime
-	/**
-	 * The parse+resolve state machine.
-	 */
 	geocode: UseGeocode
-	/**
-	 * The place-autocomplete combobox state.
-	 */
 	autocomplete: UsePlaceAutocomplete
-	/**
-	 * The compare-mode state.
-	 */
 	compare: UseCompareState
 	/**
-	 * Host-injected panels (about, release blurb, compare, permalink, extras, failure).
+	 * A query from the URL to run once the runtime is ready.
 	 */
+	initialQuery?: string | null
 	panels: GeocoderPanels
-	/**
-	 * Example chips.
-	 */
 	presets: ReadonlyArray<Preset>
 	/**
-	 * Input placeholder.
+	 * The input placeholder.
+	 *
+	 * The field also selects its value on focus while it still equals this text.
 	 */
 	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.
+	 * Called before each user-initiated query, so the host can write the query to its URL.
 	 */
 	onSubmitQuery?: (query: string) => void
-	/**
-	 * Select a model version (the composed geocoder also clears a now-colliding compare selection).
-	 */
 	onSelectVersion: (version: string) => void
-	/**
-	 * 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.
+	 * Whether the developer panel starts open.
 	 *
 	 * @default false
 	 */
 	developer?: boolean
 }
 
+type SheetName = "about" | "layers" | "developer" | null
+
 /**
- * Which side sheet is open. At most one, because they share an edge and a phone gives each the whole panel.
+ * The media query for the bottom-drawer layout.
+ * It must match the breakpoint in `styles.css`.
  */
-type SheetName = "about" | "layers" | "developer" | null
+const DRAWER_LAYOUT = "(max-width: 600px)"
 
 /**
- * The chrome. Everything positioned here floats over the map; nothing occupies a column of the page.
+ * The pointer travel, in px, that turns a press on the header into a drag instead of a tap.
+ */
+const DRAG_TRAVEL_PX = 3
+
+/**
+ * The downward travel, in px, that turns a pull at the top of the panel's scroll into a drawer drag.
+ */
+const OVERSCROLL_PROMOTE_PX = 8
+
+/**
+ * Renders the search and result panels, map control rail and side sheets over the map.
+ *
+ * On narrow screens, users can drag the search panel between bottom-drawer detents.
  */
 export function GeocoderControls({
 	runtime,
@@ -110,6 +97,7 @@ export function GeocoderControls({
 	presets,
 	placeholder,
 	map = null,
+	initialQuery = null,
 	onSubmitQuery,
 	onSelectVersion,
 	onForceWASMChange,
@@ -120,24 +108,270 @@ export function GeocoderControls({
 	const loading = runtime.loading
 	const errorMessage = geocode.parseError ?? runtime.errorMessage ?? null
 
-	// One sheet at a time. Two open at once stack on the same edge, and on a phone each is the full panel.
+	// Only one side sheet is open at a time, because two would stack on the same edge.
 	const [openSheet, setOpenSheet] = useState<SheetName>(developer ? "developer" : null)
+
+	// This flag hides the result panel until the next query resets it.
+	const [resultDismissed, setResultDismissed] = useState(false)
+
+	// The drawer height is in px.
+	// A `null` height leaves the size to the stylesheet.
+	const sheetRef = useRef<HTMLElement>(null)
+	const [sheetHeight, setSheetHeight] = useState<number | null>(null)
+	const sheetDragRef = useRef<{ startY: number; startHeight: number; moved: boolean } | null>(null)
+
+	// The detents are computed on each call, so a rotated or resized viewport needs no resize listener.
+	const sheetDetents = useCallback(() => {
+		const viewport = window.innerHeight
+
+		return {
+			medium: viewport * 0.52,
+			large: viewport * 0.88,
+			floor: viewport * 0.15,
+			// A drag released below this height dismisses the result.
+			dismissBelow: viewport * 0.28,
+			// At or below this height, the drawer counts as collapsed.
+			// The control rail then returns.
+			collapsedBelow: viewport * 0.2,
+		}
+	}, [])
+
+	// This ref holds a pull that started at the top of the panel's scroll.
+	// It becomes a drag after `OVERSCROLL_PROMOTE_PX` of downward travel.
+	const overscrollRef = useRef<{ startY: number; pointerId: number } | null>(null)
+
+	// Drag gestures apply only in the drawer layout.
+	// The desktop column is sized by its content.
+	const isDrawerLayout = () => globalThis.window !== undefined && globalThis.matchMedia(DRAWER_LAYOUT).matches
+
+	const beginSheetDrag = useCallback((clientY: number, pointerId: number) => {
+		const sheet = sheetRef.current
+
+		if (!sheet) return
+
+		sheet.setPointerCapture(pointerId)
+		sheetDragRef.current = { startY: clientY, startHeight: sheet.getBoundingClientRect().height, moved: false }
+	}, [])
+
+	// The whole header is the grab target, except the search input and the close button.
+	const onHeaderPointerDown = useCallback(
+		(event: React.PointerEvent<HTMLDivElement>) => {
+			if (!isDrawerLayout()) return
+
+			if (event.target instanceof Element && event.target.closest("input, .mw-map-sheet__close")) return
+
+			beginSheetDrag(event.clientY, event.pointerId)
+		},
+		[beginSheetDrag]
+	)
+
+	const onGripPointerMove = useCallback(
+		(event: React.PointerEvent<HTMLElement>) => {
+			const drag = sheetDragRef.current
+
+			if (!drag) return
+
+			// An upward drag makes the drawer taller, so the delta is inverted against the pointer's y.
+			const delta = drag.startY - event.clientY
+
+			if (Math.abs(delta) > DRAG_TRAVEL_PX) {
+				drag.moved = true
+			}
+
+			const { floor, large } = sheetDetents()
+
+			setSheetHeight(Math.min(large, Math.max(floor, drag.startHeight + delta)))
+		},
+		[sheetDetents]
+	)
+
+	// A tap, keyboard activation of the handle and the handle's `aria-expanded` state
+	// all use this midpoint to select the drawer detent.
+	const detentMidpoint = useCallback(() => {
+		const { medium, large } = sheetDetents()
+
+		return (medium + large) / 2
+	}, [sheetDetents])
+
+	const atLargeDetent = () => sheetHeight !== null && sheetHeight > detentMidpoint()
+
+	const toggleDetent = useCallback(() => {
+		const { medium, large } = sheetDetents()
+		const current = sheetRef.current?.getBoundingClientRect().height ?? medium
+
+		setSheetHeight(current > detentMidpoint() ? medium : large)
+	}, [sheetDetents, detentMidpoint])
+
+	const onGripPointerUp = useCallback(() => {
+		const drag = sheetDragRef.current
+
+		if (!drag) return
+
+		sheetDragRef.current = null
+
+		const { medium, large, dismissBelow } = sheetDetents()
+		const midpoint = (medium + large) / 2
+		const current = sheetRef.current?.getBoundingClientRect().height ?? medium
+
+		// A press without travel counts as a tap.
+		// It toggles between the two detents.
+		if (!drag.moved) {
+			toggleDetent()
+
+			return
+		}
+
+		if (current < dismissBelow) {
+			setResultDismissed(true)
+			setSheetHeight(null)
+
+			return
+		}
+
+		setSheetHeight(current > midpoint ? large : medium)
+	}, [sheetDetents, toggleDetent])
+
+	// A downward pull on a panel scrolled to its top drags the drawer down.
+	// This handler only arms the pull; `onPanelPointerMove` promotes it, so taps
+	// and upward scrolls are unaffected.
+	const onPanelPointerDown = useCallback((event: React.PointerEvent<HTMLElement>) => {
+		if (!isDrawerLayout()) return
+
+		if (sheetDragRef.current) return
+
+		const sheet = sheetRef.current
+
+		if (!sheet || sheet.scrollTop > 0) return
+
+		if (event.target instanceof Element && event.target.closest(".mw-map-panel__header")) return
+
+		overscrollRef.current = { startY: event.clientY, pointerId: event.pointerId }
+	}, [])
+
+	const onPanelPointerMove = useCallback(
+		(event: React.PointerEvent<HTMLElement>) => {
+			if (sheetDragRef.current) {
+				onGripPointerMove(event)
+
+				return
+			}
+
+			const armed = overscrollRef.current
+
+			if (!armed || armed.pointerId !== event.pointerId) return
+
+			const sheet = sheetRef.current
+
+			if (!sheet) return
+
+			if (sheet.scrollTop > 0) {
+				overscrollRef.current = null
+
+				return
+			}
+
+			if (event.clientY - armed.startY < OVERSCROLL_PROMOTE_PX) return
+
+			overscrollRef.current = null
+			// The drag starts from the pull's origin, so the drawer does not jump by the threshold.
+			sheetDragRef.current = { startY: armed.startY, startHeight: sheet.getBoundingClientRect().height, moved: true }
+			sheet.setPointerCapture(event.pointerId)
+			onGripPointerMove(event)
+		},
+		[onGripPointerMove]
+	)
+
+	const onPanelPointerUp = useCallback(() => {
+		overscrollRef.current = null
+		onGripPointerUp()
+	}, [onGripPointerUp])
+
 	const { bearing, resetNorth } = useMapBearing(map)
 
 	const toggleSheet = (name: Exclude<SheetName, null>) => setOpenSheet((current) => (current === name ? null : name))
 	const closeSheet = useCallback(() => setOpenSheet(null), [])
 
-	// 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.
+	// Every user-initiated query goes through this function, so `onSubmitQuery` fires from one place.
 	const runQuery = useCallback(
 		(query: string) => {
+			// A new query shows the result panel again at its default height.
+			setResultDismissed(false)
+			setSheetHeight(null)
 			onSubmitQuery?.(query)
 			void geocode.submit(query)
 		},
 		[onSubmitQuery, geocode]
 	)
 
-	// A label on the map is a search a visitor already typed by pointing at it.
+	// The initial query waits for `runtime.ready` because the parse pipeline drops
+	// a submit made before the model loads.
+	// The ref makes it run once, so a later render cannot overwrite the user's own query.
+	const autoRanInitialQuery = useRef(false)
+
+	useEffect(() => {
+		if (autoRanInitialQuery.current) return
+
+		if (!initialQuery || !runtime.ready) return
+
+		autoRanInitialQuery.current = true
+		// This calls `geocode.submit` directly because the query is already in the URL.
+		void geocode.submit(initialQuery)
+	}, [initialQuery, runtime.ready, geocode])
+
+	// A drawer-breakpoint crossing clears any dragged height.
+	// The height could clip the desktop column.
+	useEffect(() => {
+		const query = globalThis.matchMedia(DRAWER_LAYOUT)
+		const onChange = () => setSheetHeight(null)
+
+		query.addEventListener("change", onChange)
+
+		return () => query.removeEventListener("change", onChange)
+	}, [])
+
+	// A user pan, zoom, or rotate shrinks the drawer to its floor detent without dismissing the result.
+	// Programmatic camera moves, such as the fly-to after a query, have no `originalEvent` and are ignored.
+	useEffect(() => {
+		if (!map) return
+
+		const collapse = (event: { originalEvent?: unknown }) => {
+			if (!event.originalEvent) return
+
+			if (!isDrawerLayout()) return
+
+			const { floor } = sheetDetents()
+
+			setSheetHeight((current) => (current !== null && current <= floor ? current : floor))
+		}
+
+		map.on("dragstart", collapse)
+		map.on("zoomstart", collapse)
+		map.on("rotatestart", collapse)
+
+		return () => {
+			map.off("dragstart", collapse)
+			map.off("zoomstart", collapse)
+			map.off("rotatestart", collapse)
+		}
+	}, [map, sheetDetents])
+
+	// Escape dismisses the result only while no side sheet is open.
+	// `MapSheet` also listens for Escape on the document, so one keystroke would otherwise close both.
+	useEffect(() => {
+		if (openSheet) return
+
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") {
+				setResultDismissed(true)
+			}
+		}
+
+		document.addEventListener("keydown", onKeyDown)
+
+		return () => document.removeEventListener("keydown", onKeyDown)
+	}, [openSheet])
+
+	// A map-label click searches for its name.
 	const pickLabel = useCallback(
 		(name: string) => {
 			geocode.setText(name)
@@ -150,48 +384,105 @@ export function GeocoderControls({
 	useMapLabelPick(map, pickLabel)
 
 	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)
+	// The model download does not open the result panel.
+	// The progress bar reports it instead.
+	const showSheet = Boolean(busy || result || errorMessage) && !resultDismissed
+
+	// The control rail hides while the drawer is raised above its collapsed height.
+	const drawerRaised =
+		showSheet &&
+		(sheetHeight === null || (globalThis.window !== undefined && sheetHeight > sheetDetents().collapsedBelow))
 
 	const bundleLoading = Boolean(loading && !runtime.ready)
 	const steps = loading?.stepLabels.length ?? 0
 
+	// The model downloads during the first step.
+	// While bytes arrive, the bar follows the byte fraction scaled into the first step's share,
+	// so it does not move backwards when step progress takes over.
+	const stepFraction = steps ? ((loading?.stepIndex ?? 0) + 1) / steps : null
+	const byteFraction = loading?.byteFraction
+
+	const fraction =
+		typeof byteFraction === "number" && steps ? (byteFraction * 1) / steps : (byteFraction ?? stepFraction)
+
 	return (
 		<>
-			<MapProgressBar
-				active={bundleLoading}
-				fraction={steps ? ((loading?.stepIndex ?? 0) + 1) / steps : null}
-				label="Loading the geocoder"
-			/>
-
-			<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>
+			<MapProgressBar active={bundleLoading} fraction={fraction} label="Loading the geocoder" />
+
+			{/* One panel holds the search, examples and result. On desktop it is a left column sized to its content.
+			    On narrow screens it is a bottom drawer. */}
+			<section
+				className="mw-map-panel"
+				aria-label="Search and results"
+				ref={sheetRef}
+				onPointerDown={onPanelPointerDown}
+				onPointerMove={onPanelPointerMove}
+				onPointerUp={onPanelPointerUp}
+				onPointerCancel={onPanelPointerUp}
+				{...(sheetHeight === null ? {} : { style: { maxHeight: `${Math.round(sheetHeight)}px` } })}
+			>
+				{/*
+				 * The header holds the grab bar and search field.
+				 * It stays pinned while the result scrolls.
+				 */}
+				<div className="mw-map-panel__header" onPointerDown={onHeaderPointerDown}>
+					<div className="mw-map-panel__grip">
+						{/* The handle appears only with a result, because there is no content to expand without one. */}
+						{showSheet ? (
+							<button
+								type="button"
+								className="mw-map-sheet__handle"
+								aria-label="Resize the panel"
+								aria-expanded={atLargeDetent()}
+								// The header handles pointer gestures.
+								// A click with `detail === 0` comes from the keyboard,
+								// so only that toggles the detent here.
+								onClick={(event) => {
+									if (event.detail !== 0) return
+
+									toggleDetent()
+								}}
+							/>
+						) : null}
+
+						{showSheet ? (
+							<SheetClose
+								label="Close the result"
+								className="mw-map-sheet__close--floating"
+								onClose={() => setResultDismissed(true)}
+							/>
+						) : null}
+					</div>
+
+					<form
+						className="mw-map-panel__search"
+						onSubmit={(event) => {
+							event.preventDefault()
+							runQuery(geocode.text)
+						}}
+					>
+						{/* The search bar has no trailing control because `type="search"` provides a native clear button. */}
+						<MapSearchBar label="Search addresses" leading={<SearchGlyph />} busy={busy}>
+							<input
+								id="mw-pipeline-input"
+								type="search"
+								aria-label="Address"
+								value={geocode.text}
+								onChange={(event) => geocode.setText(event.target.value)}
+								// Focus selects the value only while it equals the placeholder, so typing replaces it.
+								onFocus={(event) => {
+									if (placeholder && event.currentTarget.value === placeholder) {
+										event.currentTarget.select()
+									}
+								}}
+								disabled={!runtime.ready}
+								placeholder={placeholder}
+								onKeyDown={autocomplete.onInputKeyDown}
+								{...autocomplete.inputProps}
+							/>
+						</MapSearchBar>
+					</form>
+				</div>
 
 				<PlaceAutocomplete
 					suggestions={autocomplete.suggestions}
@@ -215,14 +506,49 @@ export function GeocoderControls({
 				/>
 
 				{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">
+
+				{showSheet ? (
+					<div className="mw-map-panel__result">
+						{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}
+					</div>
+				) : null}
+			</section>
+
+			{/* Every floating control uses this rail to prevent overlap. The compass has its own group because it appears
+			    and disappears. The rail hides while the drawer is raised. */}
+			<MapControlStack label="Map controls" className={drawerRaised ? "mw-map-control-stack--drawer-open" : undefined}>
 				<MapControlGroup>
 					<MapControlButton
 						label="About this geocoder"
@@ -290,6 +616,16 @@ export function GeocoderControls({
 						/>
 					</div>
 
+					<div className="mw-map-sheet__row">
+						<span className="mw-map-sheet__label">Debug info</span>
+						<DebugInfo
+							activeBackend={runtime.activeBackend}
+							forceWASM={runtime.forceWASM}
+							selectedVersion={runtime.selectedVersion}
+							ready={runtime.ready}
+						/>
+					</div>
+
 					<div className="mw-map-sheet__row">
 						<CompareToggle
 							versions={versions}
@@ -306,46 +642,6 @@ export function GeocoderControls({
 				</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}
 		</>
 	)