@mailwoman/react 9.4.0 → 10.1.0

package/lib/map/GraticuleLayer.tsx

@@ -0,0 +1,54 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Draws a grid of meridians and parallels under the basemap so that the globe is readable while
+ *   tiles load. Loaded tiles cover the grid.
+ */
+
+import { type ReactNode, useMemo } from "react"
+import { Layer, Source } from "react-map-gl/maplibre"
+
+import { buildGraticule } from "./graticule.ts"
+
+/**
+ * Props for {@link GraticuleLayer}.
+ */
+export interface GraticuleLayerProps {
+	/**
+	 * The basemap layer to draw the grid beneath.
+	 * Without it, the grid is drawn on top.
+	 */
+	beforeID?: string
+	/**
+	 * Hides the grid. @default false
+	 */
+	hidden?: boolean
+}
+
+/**
+ * Renders the graticule source and line layer.
+ */
+export function GraticuleLayer({ beforeID, hidden = false }: GraticuleLayerProps): ReactNode {
+	const data = useMemo(() => buildGraticule(), [])
+
+	return (
+		<>
+			<Source id="mw-graticule" type="geojson" data={data} />
+			<Layer
+				id="mw-graticule-line"
+				type="line"
+				source="mw-graticule"
+				{...(beforeID ? { beforeId: beforeID } : {})}
+				layout={{ visibility: hidden ? "none" : "visible", "line-cap": "round" }}
+				paint={{
+					"line-color": "#8aa0c8",
+					// The grid fades out by zoom 8, where map detail makes it unnecessary.
+					"line-opacity": ["interpolate", ["linear"], ["zoom"], 0, 0.3, 3, 0.2, 6, 0.09, 8, 0],
+					"line-width": ["interpolate", ["linear"], ["zoom"], 0, 0.5, 4, 0.75],
+				}}
+			/>
+		</>
+	)
+}

package/lib/map/MapCanvas.tsx

@@ -5,18 +5,18 @@
  *
  *   `<MapCanvas>` — the declarative map shell for the geocoder demo, over `react-map-gl/maplibre` (v8).
  *   Phase 1 is the shell only: a `<Map>` that takes a host-composed `mapStyle`, an initial (or
- *   controlled) view state, and a `children` slot for the overlays/markers that land in later phases.
+ *   controlled) view state and a `children` slot for overlays/markers from later phases.
  *   No overlay/marker/camera logic lives here yet.
  *
- *   NODE-IMPORT SAFETY: this module imports `react-map-gl/maplibre` (which pulls `maplibre-gl` — WebGL
- *   + DOM at import) at module scope, so it is reachable ONLY through the `@mailwoman/react/map`
+ *   node-import safety: this module imports `react-map-gl/maplibre` (which pulls `maplibre-gl` — WebGL
+ *   + DOM at import) at module scope, so it is reachable only through the `@mailwoman/react/map`
  *   subpath, never from the package root (`index.ts`). The bare `import("@mailwoman/react")` a node
  *   consumer (or the CI smoke IMPORT_CHECK) runs must never transitively load this file. Keep it out of
  *   the root barrel.
  *
  *   CSS: the package imports no CSS from its modules (the node-safe invariant), so a host that renders
  *   `<MapCanvas>` must import `maplibre-gl/dist/maplibre-gl.css` itself (plus `@mailwoman/react/styles.css`
- *   for the `.mw-demo-map` container). `<MapCanvas>` is intrinsically a client component — a host that
+ *   for the `.mw-demo-map` container). `<MapCanvas>` is intrinsically a client component. A host that
  *   server-renders should wrap it in a client boundary (the package's `ClientOnly`), exactly as the
  *   composed `Geocoder` will in a later phase.
  */
@@ -31,8 +31,10 @@ import type { MapProps, MapRef, ViewStateChangeEvent } from "react-map-gl/maplib
 export type MapCanvasStyle = NonNullable<MapProps["mapStyle"]>
 
 /**
- * Override for the `<Map>` props `<MapCanvas>` does not surface explicitly (e.g. `minZoom`, `attributionControl`,
- * `maplibreLogo`). The controlled fields MapCanvas owns are omitted so they can't be set twice.
+ * Override for the `<Map>` props `<MapCanvas>` does not surface explicitly
+ * (e.g. `minZoom`, `attributionControl`, `maplibreLogo`).
+ *
+ * The controlled fields MapCanvas owns are omitted so they can't be set twice.
  */
 export type MapCanvasExtraProps = Partial<
 	Omit<MapProps, "mapStyle" | "initialViewState" | "viewState" | "onMove" | "children" | "style" | "ref">
@@ -44,11 +46,15 @@ export interface MapCanvasProps {
 	 */
 	mapStyle: MapCanvasStyle
 	/**
-	 * Uncontrolled initial camera. Use this OR `viewState`, not both.
+	 * Uncontrolled initial camera.
+	 *
+	 * Use this or `viewState`, not both.
 	 */
 	initialViewState?: MapProps["initialViewState"]
 	/**
-	 * Controlled camera. Pair with `onMove` to persist it.
+	 * Controlled camera.
+	 *
+	 * Pair with `onMove` to persist it.
 	 */
 	viewState?: MapProps["viewState"]
 	/**
@@ -64,7 +70,9 @@ export interface MapCanvasProps {
 	 */
 	mapRef?: Ref<MapRef>
 	/**
-	 * Overlays, markers, and controls — rendered as `<Map>` children. Empty in phase 1.
+	 * Overlays, markers and controls — rendered as `<Map>` children.
+	 *
+	 * Empty in phase 1.
 	 */
 	children?: ReactNode
 	/**
@@ -76,7 +84,7 @@ export interface MapCanvasProps {
 	 */
 	style?: CSSProperties
 	/**
-	 * Remaining `<Map>` props MapCanvas does not surface explicitly.
+	 * Other `<Map>` props that MapCanvas does not surface explicitly.
 	 */
 	mapProps?: MapCanvasExtraProps
 }
@@ -84,8 +92,11 @@ export interface MapCanvasProps {
 const FILL: CSSProperties = { width: "100%", height: "100%" }
 
 /**
- * The controlled-viewport map shell. Renders a sized wrapper around a `react-map-gl/maplibre` `<Map>`; everything
- * host-specific (the composed `mapStyle`, the initial center) is injected, and overlays ride in as `children`.
+ * The controlled-viewport map shell.
+ *
+ * Renders a sized wrapper around a `react-map-gl/maplibre` `<Map>`; everything
+ * host-specific (the composed `mapStyle`, the initial center) is injected.
+ * Overlays arrive as `children`.
  */
 export function MapCanvas({
 	mapStyle,

package/lib/map/MapChipRow.tsx

@@ -0,0 +1,73 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render example-query chips in a single horizontally scrollable row.
+ */
+
+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,68 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Shows a compass that rotates with the map bearing and hides when the map faces north. A press
+ *   it asks the host to reset the bearing.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+/**
+ * The compass counts as facing north below this bearing.
+ * It fades out below the same threshold.
+ */
+const HIDE_BELOW_DEGREES = 0.5
+
+/**
+ * Props for {@link MapCompass}.
+ */
+export interface MapCompassProps {
+	/**
+	 * The map's bearing in degrees as MapLibre reports it, where 0 is north.
+	 */
+	bearing: number
+	/**
+	 * Called when the compass is pressed.
+	 * The host should reset its map to north.
+	 */
+	onResetNorth: () => void
+	/**
+	 * The control's accessible name. @default "Reset bearing to north"
+	 */
+	label?: string
+	className?: string
+}
+
+/**
+ * Renders the compass button.
+ */
+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"}
+			// The hidden compass leaves the tab order and the accessibility tree.
+			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" />
+
+					{/* The north needle, then the south needle. */}
+					<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,97 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Provide accessible map-control buttons arranged in grouped capsules.
+ */
+
+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 rather than 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>
+	)
+}

package/lib/map/MapFooter.tsx

@@ -0,0 +1,101 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import { type ReactNode, useEffect, useId, useRef, useState } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapFooterProps {
+	/**
+	 * The left side: a wordmark, a body name, a line saying what the page does.
+	 */
+	identity?: ReactNode
+	/**
+	 * What is loading right now, beside the identity.
+	 */
+	status?: ReactNode
+	/**
+	 * The credits, one entry per source, shown in the popover the attribution button opens.
+	 */
+	attribution?: ReactNode[]
+	/**
+	 * What the attribution button reads. @default "Sources"
+	 */
+	attributionLabel?: string
+	className?: string
+}
+
+export function MapFooter({
+	identity,
+	status,
+	attribution,
+	attributionLabel = "Sources",
+	className,
+}: MapFooterProps): ReactNode {
+	const [open, setOpen] = useState(false)
+	const popoverID = useId()
+	const root = useRef<HTMLElement>(null)
+
+	useEffect(() => {
+		if (!open) return
+
+		const onPointerDown = (event: PointerEvent) => {
+			if (!root.current?.contains(event.target as Node)) {
+				setOpen(false)
+			}
+		}
+
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") {
+				setOpen(false)
+			}
+		}
+
+		document.addEventListener("pointerdown", onPointerDown)
+		document.addEventListener("keydown", onKeyDown)
+
+		return () => {
+			document.removeEventListener("pointerdown", onPointerDown)
+			document.removeEventListener("keydown", onKeyDown)
+		}
+	}, [open])
+
+	if (!identity && !status && !attribution?.length) return null
+
+	return (
+		<footer className={cx("mw-map-footer", className)} ref={root}>
+			<div className="mw-map-footer__identity">
+				{identity}
+				{status ? <span className="mw-map-footer__status">{status}</span> : null}
+			</div>
+
+			{attribution?.length ? (
+				<div className="mw-map-footer__sources">
+					{open ? (
+						<div className="mw-map-footer__popover" id={popoverID} role="group" aria-label="Map data sources">
+							{attribution.map((entry, index) => (
+								// The entries are a fixed, ordered credit list that never reorders, so position is the identity.
+								<span key={index} className="mw-map-footer__credit">
+									{entry}
+								</span>
+							))}
+						</div>
+					) : null}
+
+					<button
+						type="button"
+						className="mw-map-footer__attribution-button"
+						aria-expanded={open}
+						aria-controls={open ? popoverID : undefined}
+						onClick={() => setOpen((value) => !value)}
+					>
+						{attributionLabel}
+					</button>
+				</div>
+			) : null}
+		</footer>
+	)
+}

package/lib/map/MapProgressBar.tsx

@@ -0,0 +1,55 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Show loading progress at the top of the viewport.
+ *   Use a determinate bar when progress is known, otherwise an indeterminate bar.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapProgressBarProps {
+	/**
+	 * Whether the bar is showing at all.
+	 *
+	 * It stays mounted through its fade rather than unmounting on the transition.
+	 */
+	active: boolean
+	/**
+	 * Completed steps over total steps, in [0, 1].
+	 *
+	 * Omit for work whose length is unknown.
+	 */
+	fraction?: number | null
+	/**
+	 * The bar's accessible name.
+	 * What is loading, in a few words.
+	 */
+	label: string
+	className?: string
+}
+
+export function MapProgressBar({ active, fraction, label, className }: MapProgressBarProps): ReactNode {
+	const determinate = typeof fraction === "number" && Number.isFinite(fraction)
+	const clamped = determinate ? Math.min(1, Math.max(0, fraction)) : 0
+
+	return (
+		<div
+			className={cx("mw-map-progress", !active && "mw-map-progress--idle", className)}
+			role="progressbar"
+			aria-label={label}
+			aria-hidden={!active}
+			aria-valuemin={determinate ? 0 : undefined}
+			aria-valuemax={determinate ? 100 : undefined}
+			aria-valuenow={determinate ? Math.round(clamped * 100) : undefined}
+		>
+			<div
+				className={cx("mw-map-progress__fill", !determinate && "mw-map-progress__fill--indeterminate")}
+				style={determinate ? { transform: `scaleX(${clamped})` } : undefined}
+			/>
+		</div>
+	)
+}

package/lib/map/MapSearchBar.tsx

@@ -0,0 +1,82 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Presentational search pill for map UIs. The host supplies the input and icons.
+ *   Busy state uses a bottom-edge indicator to avoid changing the pill layout.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+/**
+ * Draw a consistently sized magnifier for the leading slot.
+ */
+export function SearchGlyph(): ReactNode {
+	return (
+		<svg
+			viewBox="0 0 20 20"
+			width="18"
+			height="18"
+			aria-hidden="true"
+			focusable="false"
+			className="mw-map-searchbar__glyph"
+		>
+			<circle cx="8.75" cy="8.75" r="5.5" fill="none" stroke="currentColor" strokeWidth="1.8" />
+			<line x1="12.9" y1="12.9" x2="17" y2="17" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+		</svg>
+	)
+}
+
+export interface MapSearchBarProps {
+	/**
+	 * The input (or combobox) the host owns.
+	 *
+	 * Rendered between the two slots.
+	 */
+	children: ReactNode
+	/**
+	 * Rendered before the input — a magnifier, a body mark, a back arrow.
+	 */
+	leading?: ReactNode
+	/**
+	 * Rendered after the input — a microphone, a menu.
+	 *
+	 * Not a spinner: pass {@link busy} instead.
+	 */
+	trailing?: ReactNode
+	/**
+	 * A query is running.
+	 *
+	 * Draws a progress hairline along the pill's lower edge.
+	 * The hairline takes no layout space.
+	 */
+	busy?: boolean
+	/**
+	 * Extra class on the pill.
+	 */
+	className?: string
+	/**
+	 * Accessible name for the surrounding region, when the bar is the app's primary search.
+	 */
+	label?: string
+}
+
+export function MapSearchBar({ children, leading, trailing, busy, className, label }: MapSearchBarProps): ReactNode {
+	return (
+		<div
+			className={cx("mw-map-searchbar", busy && "mw-map-searchbar--busy", className)}
+			role={label ? "search" : undefined}
+			aria-label={label}
+			aria-busy={busy}
+		>
+			{leading ? <span className="mw-map-searchbar__slot mw-map-searchbar__slot--leading">{leading}</span> : null}
+
+			<span className="mw-map-searchbar__field">{children}</span>
+
+			{trailing ? <span className="mw-map-searchbar__slot mw-map-searchbar__slot--trailing">{trailing}</span> : null}
+		</div>
+	)
+}

package/lib/map/MapSheet.tsx

@@ -0,0 +1,71 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Side panel over the map with a heading, close button and Escape dismissal.
+ */
+
+import { type ReactNode, useEffect } from "react"
+
+import { cx } from "#common/cx"
+
+export interface SheetCloseProps {
+	/**
+	 * What is being closed, for the accessible name: "Close the result", "Close About".
+	 */
+	label: string
+	onClose: () => void
+	className?: string
+}
+
+/**
+ * Accessible button for dismissing a sheet.
+ */
+export function SheetClose({ label, onClose, className }: SheetCloseProps): ReactNode {
+	return (
+		<button type="button" className={cx("mw-map-sheet__close", className)} aria-label={label} onClick={onClose}>
+			<span aria-hidden="true">×</span>
+		</button>
+	)
+}
+
+export interface MapSheetProps {
+	/**
+	 * The sheet's heading.
+	 * It also supplies the accessible name.
+	 */
+	title: string
+	/**
+	 * Dismiss the sheet.
+	 */
+	onClose: () => void
+	children: ReactNode
+	className?: string
+}
+
+export function MapSheet({ title, onClose, children, className }: MapSheetProps): ReactNode {
+	useEffect(() => {
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") {
+				onClose()
+			}
+		}
+
+		document.addEventListener("keydown", onKeyDown)
+
+		return () => document.removeEventListener("keydown", onKeyDown)
+	}, [onClose])
+
+	return (
+		<aside className={cx("mw-map-sheet mw-map-sheet--side", className)} aria-label={title}>
+			<div className="mw-map-sheet__header">
+				<h2 className="mw-map-sheet__title">{title}</h2>
+
+				<SheetClose label={`Close ${title}`} onClose={onClose} />
+			</div>
+
+			<div className="mw-map-sheet__body">{children}</div>
+		</aside>
+	)
+}

package/lib/map/OverlayLayers.tsx

@@ -9,7 +9,7 @@
  *   the host composes the specs, the package renders them, react-map-gl owns the add/remove lifecycle.
  *
  *   Each overlay's `visible` flag flips the layers' `visibility` layout property — the declarative control a
- *   layer-toggle control drives in a later phase. NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` —
+ *   layer-toggle control drives in a later phase. node-import safety: imports `react-map-gl/maplibre` —
  *   reachable only via `@mailwoman/react/map`.
  */