makersclaw 0.2.0 → 0.3.1

package/registry/blocks/map/README.md

@@ -0,0 +1,221 @@
+# MapView
+
+Places on an interactive map, with their list beside it. Every row that
+has a position becomes a marker — a dot in a token tone, or your own kit
+content. Markers that crowd merge into a count; click it to zoom in. Click
+a marker and a popup opens with kit parts. The list on the left is
+searchable and shares one selection and one hover with the map: pick a
+row and the map moves to it, pick a marker and the list scrolls to it.
+Zoom buttons and "Show all" sit top right. Rows with no position are
+listed under "Not on the map", never lost.
+
+On a phone the map fills the block, a strip of cards sits under it, and a
+"List" button swaps to the full list.
+
+It is [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js)
+(BSD-3-Clause) underneath, through
+[react-map-gl](https://github.com/visgl/react-map-gl) (MIT): its tiles,
+camera, gestures and keyboard (arrows pan, + and − zoom). The markers,
+clusters, popup, list and controls are ours, in the kit and the
+workspace's tokens. The blocks built on this one — `location-map`,
+`store-locator`, the Map view of `work-views` — import it, never the map
+packages.
+
+```jsx
+import { MapView, useMapView } from "../components/blocks/map";   // a Makersclaw app ("./blocks/map" from components/)
+import { MapView, useMapView } from "@/components/makersclaw/blocks/map";   // a shadcn project
+```
+
+`MapView` is a client component: render it from a `"use client"`
+component, and load the rows in the server surface (README §4). The
+helpers (`readPosition`, `boundsOf`, `distanceKm`…) are plain functions and
+work on the server.
+
+`makersclaw add map` adds `maplibre-gl` and `react-map-gl` (pinned, exact)
+to package.json: run `npm install` after. They load with the page (no
+`import()`); the map mounts after the first render. Until then — on the
+server — the frame, the list and a quiet "Loading the map…" show.
+
+## What it fetches at run time
+
+A map cannot ship its world inside the app. In the browser it fetches:
+
+- **The tiles, style and fonts** from the style URL. The default is
+  [OpenFreeMap](https://openfreemap.org): free, no key, no sign-up,
+  OpenStreetMap data. `positron` (light) or `dark`, picked from the
+  workspace's scheme and swapped when it changes. The attribution line
+  (bottom right) is the data licence's condition: it stays.
+- **MapLibre's tile worker** from jsDelivr, at exactly the installed
+  version (`https://cdn.jsdelivr.net/npm/maplibre-gl@<version>/dist/maplibre-gl-worker.mjs`).
+  MapLibre 6 finds its worker beside its own file, which a bundled app
+  does not have. Host the file yourself and pass `workerUrl` to avoid
+  the CDN.
+
+Nothing else leaves the page: no geocoding, no analytics.
+
+## The data
+
+Rows are your records. A row's position is read by `positionOf`; the
+default reads any of these:
+
+```js
+{ lat: 38.71, lng: -9.14 }                       // or latitude / longitude, or lon
+{ location: { lat: 38.71, lng: -9.14, label } }   // the task-model shape
+{ position: [-9.14, 38.71] }                     // a GeoJSON pair: [lng, lat]
+```
+
+Numbers or numeric strings, in degrees (WGS 84 — what GPS and every
+geocoder give). A row with no valid position is listed, not mapped.
+
+Tones are token names, never colours: `primary` (the default), `success`,
+`warning`, `destructive`, `info`, `chart-1` … `chart-5`, `muted`. A tone
+means something — status, owner, type — so say it in words too (a badge
+in `asideOf`).
+
+## Props
+
+- `items` — the rows. Pass `useFixture(rows, SAMPLE).rows` to open with an
+  example.
+- `positionOf(row)` — `{ lat, lng }` or null. Default: `readPosition` (above).
+- `idOf(row)` — default `row.id`. Ids are compared as strings.
+- `titleOf(row)` — the name on the marker's label, the list row and the
+  popup. Default `row.title ?? row.name ?? row.label ?? row.location.label`.
+- `metaOf(row)` — a muted line under the title (list, card, popup): a
+  city, an address. A string, or a node.
+- `asideOf(row)` — a node at the row's end: a `Badge`, a distance.
+- `toneOf(row)` — the marker's tone (above). Default `primary`.
+- `searchOf(row)` — the words the search finds a row by. Default: title
+  and meta. Every word typed must appear.
+- `renderMarker(row, { selected, hovered, tone })` — your own marker
+  content (an `Avatar`, a price, an icon), kit parts only. It sits inside
+  the block's button, so clicks, labels and selection still work.
+- `renderPopup(row, { close })` — the popup's content: kit parts and
+  tokens. Default: title, meta and aside. The box and its close button
+  are the block's.
+- `selectedId` · `onSelect(id, row)` — control the selection (the row
+  your form edits, a URL param). `id` is a string, or null when cleared.
+  Leave `selectedId` out and the block keeps its own; `defaultSelectedId`
+  sets where it starts. A selection set from outside moves the map to it.
+- `onMove(row, { lat, lng })` — markers become draggable. The marker stays
+  where it was dropped at once; return `{ ok: true }` or
+  `{ ok: false, error }` (a throw counts as failed) and a failed save puts
+  it back with a toast saying why. The block keeps the new spot until
+  `positionOf(row)` reports a different one.
+- `onMapClick({ lat, lng })` — a click on the map, not a marker ("add a
+  place here"). The block also clears the selection.
+- `onViewChange({ center, zoom, bounds })` — after the map stops moving
+  (and once on load). `bounds` is `{ west, south, east, north }`: search
+  this area, load what is in view.
+- `areas` — tinted regions: `[{ id, label?, tone?, geometry }]`, where
+  `geometry` is GeoJSON (`Polygon`, `MultiPolygon`, `LineString`). A soft
+  fill and a line in the tone, repainted when the scheme changes.
+- `onAreaClick(area)` — an area is clicked.
+- `list` — `"side"` (default: the list beside the map, the card strip on
+  a phone) or `"none"` (the map alone; markers then take Tab focus).
+- `search` — the search field over the list. Default `true`.
+- `cluster` — merge crowded markers. Default `true`. `clusterRadius` —
+  how close in pixels, default `48`.
+- `popup` — open a popup for the selected row. Default `true`.
+- `styleUrl` — the tiles: one URL, or `{ light, dark }` to follow the
+  scheme. Default `DEFAULT_STYLE` (OpenFreeMap positron / dark).
+  `MAP_STYLES` has OpenFreeMap's five: `positron`, `liberty`, `bright`,
+  `dark`, `fiord`. Any MapLibre style URL works (MapTiler, Stadia, your
+  own), with the provider's key in the URL if it needs one.
+- `scheme` — `"auto"` (default: the workspace's light or dark), `"light"`
+  or `"dark"`.
+- `workerUrl` — where MapLibre's worker loads from (above).
+- `initialView` — `{ lat, lng, zoom }` when there are no positions to
+  fit. Default: the whole world.
+- `fitOnChange` — refit to the places when the set on the map changes
+  (new rows, a search). Default `true`. `fitMaxZoom` — how close a fit
+  may go, default `14`. `maxZoom` — default `18`.
+- `scrollZoom` — the wheel zooms. Default `true`; set `false` for a map
+  inside a long page (buttons and pinch still zoom).
+- `controls` — the zoom and "Show all" buttons. Default `true`.
+- `height` — the block's height: a number (px) or a CSS length. Default
+  `520`. The map needs one; the block never sizes itself to its content.
+- `noun` · `nounPlural` — what a row is called: "account" → "Search
+  accounts", "12 accounts", "No accounts yet". Default `place`.
+- `emptyTitle` · `emptyBody` · `emptyAction` — the empty list's words and
+  its one button (a `Button`), when `items` is empty.
+- `label` — what the region is called to a screen reader. Default `Map`.
+- `mapRef` — the handle (below).
+- `className` — layout around it (width, margin). Never colour.
+
+## The handle
+
+```jsx
+const map = useMapView();
+<MapView mapRef={map} items={rows} />
+map.current?.fitAll();                        // every place on the map in view
+map.current?.select("acc-07");               // select and move to it
+map.current?.flyTo({ lat: 48.86, lng: 2.35, zoom: 11 });
+map.current?.fitBounds({ west, south, east, north });
+map.current?.zoomIn();  map.current?.zoomOut();
+map.current?.getView(); // { center, zoom, bounds } or null before load
+map.current?.getMap();  // the maplibre Map, for what the props do not cover
+```
+
+## Helpers
+
+- `readPosition(row)` → `{ lat, lng }` or null.
+- `boundsOf(positions)` → `{ west, south, east, north }` or null;
+  `inBounds(bounds, position)`.
+- `distanceKm(a, b)` — great-circle distance; `formatDistance(km, "km" | "mi")`
+  → "350 m", "4.2 km", "24 mi".
+- `sortByDistance(rows, origin, positionOf?)` → `[{ row, distanceKm }]`,
+  nearest first, rows without a position last.
+- `clusterPoints(points, zoom, radius?)` and `zoomToReveal(points, id, zoom)`
+  — the clustering the map uses, for a list that groups the same way.
+
+## Example
+
+```jsx
+// components/Customers.jsx — client: the map, the list, the popup
+"use client";
+import { Badge, Button } from "./ui";
+import { FixtureNotice, useFixture } from "./parts";
+import { MapView } from "./blocks/map";
+
+const SAMPLE = [
+  { name: "Northwind Café", city: "Lisbon", lat: 38.7107, lng: -9.1422, status: "active" },
+  { name: "Acme Bakery", city: "Porto", lat: 41.1405, lng: -8.6132, status: "at risk" },
+];
+
+export default function Customers({ customers }) {
+  const fixture = useFixture(customers, SAMPLE);
+  return (
+    <div className="grid gap-4">
+      {fixture.isFixture ? <FixtureNotice onClear={fixture.clear} /> : null}
+      <MapView
+        items={fixture.rows}
+        noun="customer"
+        titleOf={(c) => c.name}
+        metaOf={(c) => c.city}
+        toneOf={(c) => (c.status === "active" ? "success" : "warning")}
+        asideOf={(c) => <Badge tone={c.status === "active" ? "success" : "warning"} variant="soft">{c.status}</Badge>}
+        renderPopup={(c) => (
+          <div className="grid gap-2 pr-8">
+            <p className="font-medium">{c.name}</p>
+            <p className="text-muted-foreground">{c.city}</p>
+            <Button size="sm" variant="primary" href={`/customers/${c.id}`}>Open</Button>
+          </div>
+        )}
+      />
+    </div>
+  );
+}
+```
+
+## What it will not do
+
+- Geocode. It maps coordinates; turning an address into them is a
+  server job (store the result on the row).
+- Heatmaps, routes, 3D buildings, satellite imagery. Pass `styleUrl` for
+  another base map; `getMap()` reaches maplibre for the rest.
+- Move a marker from the keyboard. Dragging is pointer-only; keep a
+  coordinates field in the row's form for keyboard users.
+- Scale past a few thousand markers. Each marker is a DOM node; for tens
+  of thousands, use maplibre layers through `getMap()`.
+- Work offline or without WebGL: the list stays, and the map says why it
+  cannot show.

package/registry/blocks/map/block.json

@@ -0,0 +1,14 @@
+{
+  "name": "map",
+  "title": "MapView",
+  "description": "An interactive map (MapLibre) in the workspace theme: places from rows as markers in token tones or your own kit content, clustered when they crowd, a popup with kit parts, a searchable list beside the map that shares one selection and hover with it, fit-to-all, zoom controls, draggable markers with an optimistic save, and tinted areas for territories. Light and dark tiles follow the workspace scheme (OpenFreeMap by default, no key); `styleUrl` swaps them. Helpers for bounds, clustering and distances run anywhere.",
+  "useWhen": "A screen shows records that have a place: customers, stores, offices, field visits, deliveries, events, territories. The location-map and store-locator blocks and the Map view of work-views are built on it. Not for a chart of numbers by region (chart) or a hand-drawn diagram (sketch-canvas, flow-canvas).",
+  "tags": ["map", "maps", "location", "geo", "markers", "pins", "cluster", "maplibre", "openstreetmap", "store locator", "territory", "places", "coordinates", "latitude", "longitude", "distance"],
+  "exports": ["MapView", "useMapView", "MAP_STYLES", "DEFAULT_STYLE", "TONES", "readPosition", "boundsOf", "inBounds", "clusterPoints", "zoomToReveal", "distanceKm", "formatDistance", "sortByDistance"],
+  "files": ["index.js", "map-view.jsx", "list.jsx", "marks.jsx", "maplibre.js", "theme.js", "geo.js"],
+  "requires": [],
+  "dependencies": {
+    "maplibre-gl": "6.11.1",
+    "react-map-gl": "8.1.3"
+  }
+}

package/registry/blocks/map/demo.jsx

@@ -0,0 +1,201 @@
+"use client";
+
+// MapView three ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   Accounts     a roaster's wholesale cafés: tones by status, a cluster in
+//                Lisbon, a popup with kit parts, the list beside the map,
+//                markers that drag (with a switch that makes the save fail),
+//                one account with no location yet.
+//   Territories  the reps' regions as tinted areas, each rep's visits as
+//                an avatar marker (renderMarker), no list, a handle that
+//                flies between regions.
+//   Empty        a new map: the friendly empty state and its one action.
+import { useState } from "react";
+import { Avatar, Badge, Button, Switch, TabPanel, Tabs, toast } from "../components/ui";
+import { FixtureNotice, useFixture } from "../components/parts";
+import { MapView, useMapView } from "../components/blocks/map";
+
+const STATUS = {
+  active: { label: "Active", tone: "success", badge: "success" },
+  risk: { label: "At risk", tone: "warning", badge: "warning" },
+  trial: { label: "Trial", tone: "info", badge: "info" },
+};
+
+const ACCOUNTS = [
+  { id: "acc-01", name: "Fábrica do Grão", city: "Lisbon · Chiado", lat: 38.7107, lng: -9.1422, status: "active", mrr: 1840, bags: 64 },
+  { id: "acc-02", name: "Copo Alto", city: "Lisbon · Príncipe Real", lat: 38.7167, lng: -9.1489, status: "active", mrr: 1210, bags: 41 },
+  { id: "acc-03", name: "Rua Nova Espresso", city: "Lisbon · Cais do Sodré", lat: 38.7066, lng: -9.1447, status: "risk", mrr: 690, bags: 22 },
+  { id: "acc-04", name: "Alfama Torra", city: "Lisbon · Alfama", lat: 38.7118, lng: -9.1301, status: "trial", mrr: 0, bags: 6 },
+  { id: "acc-05", name: "Estrela Café", city: "Lisbon · Estrela", lat: 38.7131, lng: -9.1597, status: "active", mrr: 980, bags: 33 },
+  { id: "acc-06", name: "Ribeira Roasters", city: "Porto · Ribeira", lat: 41.1405, lng: -8.6132, status: "active", mrr: 1560, bags: 52 },
+  { id: "acc-07", name: "Mercado 14", city: "Madrid · Malasaña", lat: 40.4262, lng: -3.7041, status: "risk", mrr: 740, bags: 25 },
+  { id: "acc-08", name: "Café Brisa", city: "Barcelona · Gràcia", lat: 41.4036, lng: 2.1567, status: "active", mrr: 2120, bags: 71 },
+  { id: "acc-09", name: "Le Comptoir Bleu", city: "Paris · Canal Saint-Martin", lat: 48.8717, lng: 2.3645, status: "trial", mrr: 0, bags: 8 },
+  { id: "acc-10", name: "Maison Sillon", city: "Lyon · Croix-Rousse", lat: 45.7745, lng: 4.8311, status: "active", mrr: 1320, bags: 44 },
+  { id: "acc-11", name: "Kaffeehaus Nord", city: "Berlin · Prenzlauer Berg", lat: 52.5388, lng: 13.4244, status: "active", mrr: 1750, bags: 58 },
+  { id: "acc-12", name: "Grachtbar", city: "Amsterdam · Jordaan", lat: 52.3752, lng: 4.8836, status: "risk", mrr: 560, bags: 19 },
+  { id: "acc-13", name: "Mill & Pour", city: "London · Hackney", lat: 51.5450, lng: -0.0553, status: "active", mrr: 2410, bags: 80 },
+  { id: "acc-14", name: "Liffey Cup", city: "Dublin", status: "trial", mrr: 0, bags: 4 },
+];
+
+const euro = (n) => (n ? `€${n.toLocaleString("en")}/mo` : "Trial");
+
+export default function MapDemo() {
+  const [tab, setTab] = useState("accounts");
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="Map examples"
+        tabs={[
+          { key: "accounts", label: "Accounts" },
+          { key: "territories", label: "Territories" },
+          { key: "empty", label: "Empty" },
+        ]}
+        value={tab}
+        onChange={setTab}
+      />
+      <TabPanel tab="accounts" value={tab}>
+        <Accounts />
+      </TabPanel>
+      <TabPanel tab="territories" value={tab}>
+        {tab === "territories" ? <Territories /> : null}
+      </TabPanel>
+      <TabPanel tab="empty" value={tab}>
+        {tab === "empty" ? (
+          <MapView
+            items={[]}
+            noun="account"
+            emptyTitle="No accounts on the map yet"
+            emptyBody="Add an account with an address and it lands here, with its neighbours."
+            emptyAction={
+              <Button variant="primary" size="sm" icon="plus" onClick={() => toast("A new account form would open here")}>
+                Add account
+              </Button>
+            }
+            height={420}
+          />
+        ) : null}
+      </TabPanel>
+    </div>
+  );
+}
+
+function Accounts() {
+  const fixture = useFixture([], ACCOUNTS);
+  const [moved, setMoved] = useState({});
+  const [failSaves, setFailSaves] = useState(false);
+  const [selected, setSelected] = useState(null);
+  const rows = fixture.rows.map((r) => (moved[r.id] ? { ...r, ...moved[r.id] } : r));
+
+  async function onMove(row, pos) {
+    await new Promise((res) => setTimeout(res, 500));
+    if (failSaves) return { ok: false, error: "The server said no (the failing-save switch is on)." };
+    setMoved((m) => ({ ...m, [row.id]: pos }));
+    toast.success(`${row.name} moved`);
+    return { ok: true };
+  }
+
+  return (
+    <div className="grid gap-3">
+      {fixture.isFixture ? <FixtureNotice onClear={fixture.clear} /> : null}
+      <MapView
+        items={rows}
+        noun="account"
+        titleOf={(r) => r.name}
+        metaOf={(r) => r.city}
+        toneOf={(r) => STATUS[r.status].tone}
+        asideOf={(r) => (
+          <Badge tone={STATUS[r.status].badge} variant="soft">
+            {STATUS[r.status].label}
+          </Badge>
+        )}
+        searchOf={(r) => `${r.name} ${r.city} ${STATUS[r.status].label}`}
+        selectedId={selected}
+        onSelect={(id) => setSelected(id)}
+        onMove={onMove}
+        renderPopup={(r, { close }) => (
+          <div className="grid gap-3 pr-8">
+            <div className="grid gap-0.5">
+              <p className="font-medium leading-5">{r.name}</p>
+              <p className="text-muted-foreground">{r.city}</p>
+            </div>
+            <div className="flex items-center gap-3 text-sm">
+              <Badge tone={STATUS[r.status].badge} variant="soft">
+                {STATUS[r.status].label}
+              </Badge>
+              <span className="tabular-nums">{euro(r.mrr)}</span>
+              <span className="tabular-nums text-muted-foreground">{r.bags} bags</span>
+            </div>
+            <div className="flex gap-2">
+              <Button
+                size="sm"
+                variant="primary"
+                onClick={() => {
+                  toast(`Opening ${r.name}`);
+                  close();
+                }}
+              >
+                Open account
+              </Button>
+              <Button size="sm" variant="quiet" icon="calendar" onClick={() => toast(`Visit planned at ${r.name}`)}>
+                Plan a visit
+              </Button>
+            </div>
+          </div>
+        )}
+      />
+      <Switch id="map-fail" checked={failSaves} onChange={(e) => setFailSaves(e.target.checked)} label="Make the next drag fail to save" />
+    </div>
+  );
+}
+
+const REGIONS = [
+  { id: "iberia", label: "Iberia · Inês", tone: "chart-2", center: { lat: 40.2, lng: -5.5, zoom: 4.6 }, ring: [[-9.6, 36.9], [3.3, 36.9], [3.3, 43.8], [-9.6, 43.8]] },
+  { id: "france", label: "France · Hugo", tone: "chart-3", center: { lat: 46.6, lng: 2.4, zoom: 4.8 }, ring: [[-4.8, 42.4], [7.9, 42.4], [7.9, 51.1], [-4.8, 51.1]] },
+  { id: "north", label: "North · Femke", tone: "chart-4", center: { lat: 52.4, lng: 7.5, zoom: 4.8 }, ring: [[-6.5, 49.9], [15.1, 49.9], [15.1, 55.2], [-6.5, 55.2]] },
+];
+
+const AREAS = REGIONS.map((r) => ({ id: r.id, label: r.label, tone: r.tone, geometry: { type: "Polygon", coordinates: [[...r.ring, r.ring[0]]] } }));
+
+const VISITS = [
+  { id: "v-1", rep: "Inês Duarte", where: "Porto", lat: 41.15, lng: -8.61, region: "iberia" },
+  { id: "v-2", rep: "Inês Duarte", where: "Seville", lat: 37.39, lng: -5.98, region: "iberia" },
+  { id: "v-3", rep: "Hugo Marchal", where: "Bordeaux", lat: 44.84, lng: -0.58, region: "france" },
+  { id: "v-4", rep: "Hugo Marchal", where: "Lille", lat: 50.63, lng: 3.06, region: "france" },
+  { id: "v-5", rep: "Femke de Vries", where: "Hamburg", lat: 53.55, lng: 9.99, region: "north" },
+  { id: "v-6", rep: "Femke de Vries", where: "Utrecht", lat: 52.09, lng: 5.12, region: "north" },
+];
+
+function Territories() {
+  const map = useMapView();
+  const visits = useFixture([], VISITS);
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap gap-2">
+        {REGIONS.map((r) => (
+          <Button key={r.id} size="sm" variant="secondary" onClick={() => map.current?.flyTo(r.center)}>
+            {r.label}
+          </Button>
+        ))}
+        <Button size="sm" variant="quiet" icon="maximize" onClick={() => map.current?.fitAll()}>
+          All regions
+        </Button>
+      </div>
+      <MapView
+        mapRef={map}
+        items={visits.rows}
+        list="none"
+        cluster={false}
+        noun="visit"
+        titleOf={(v) => `${v.rep} · ${v.where}`}
+        metaOf={(v) => `Next visit in ${v.where}`}
+        toneOf={(v) => REGIONS.find((r) => r.id === v.region)?.tone}
+        renderMarker={(v, { selected }) => <Avatar name={v.rep} size="xs" className={selected ? "ring-2 ring-primary" : "ring-2 ring-background"} />}
+        areas={AREAS}
+        onAreaClick={(a) => toast(a.label)}
+        height={440}
+        label="Sales territories"
+      />
+    </div>
+  );
+}

package/registry/blocks/map/geo.js

@@ -0,0 +1,198 @@
+// The map's arithmetic: plain functions of plain objects, so they run in
+// node, on the server and in the blocks built on this one (location-map,
+// store-locator, the Map view of work-views). No maplibre in here.
+//
+// A position is { lat, lng } in degrees (WGS 84, what every geocoder and
+// GPS gives). Longitude first only where maplibre wants it ([lng, lat]).
+
+const EARTH_KM = 6371.0088;
+const MAX_LAT = 85.05112878; // web mercator stops here
+
+const num = (v) => (typeof v === "string" && v.trim() !== "" ? Number(v) : v);
+const isLat = (v) => typeof v === "number" && Number.isFinite(v) && v >= -90 && v <= 90;
+const isLng = (v) => typeof v === "number" && Number.isFinite(v) && v >= -180 && v <= 180;
+
+/** A valid { lat, lng } from whatever a row holds, or null. Reads
+ *  `lat`/`lng`, `latitude`/`longitude`, `lon`, `location: { lat, lng }`
+ *  (the task-model shape), `position` and `[lng, lat]` pairs (GeoJSON order). */
+export function readPosition(item) {
+  if (!item || typeof item !== "object") return null;
+  if (Array.isArray(item)) return toPos(num(item[1]), num(item[0]));
+  const direct = toPos(num(item.lat ?? item.latitude), num(item.lng ?? item.lon ?? item.longitude));
+  if (direct) return direct;
+  for (const key of ["location", "position", "coords", "geo"]) {
+    const inner = item[key];
+    if (inner && typeof inner === "object" && inner !== item) {
+      const p = readPosition(inner);
+      if (p) return p;
+    }
+  }
+  return null;
+}
+
+function toPos(lat, lng) {
+  return isLat(lat) && isLng(lng) ? { lat, lng } : null;
+}
+
+/** [lng, lat] → a point on the web-mercator world at `zoom`, in pixels
+ *  (the world is 512 px wide at zoom 0, as maplibre draws it). */
+export function project({ lat, lng }, zoom) {
+  const size = 512 * 2 ** zoom;
+  const clamped = Math.max(-MAX_LAT, Math.min(MAX_LAT, lat));
+  const s = Math.sin((clamped * Math.PI) / 180);
+  return {
+    x: ((lng + 180) / 360) * size,
+    y: (0.5 - Math.log((1 + s) / (1 - s)) / (4 * Math.PI)) * size,
+  };
+}
+
+/** The box around some positions: { west, south, east, north }, or null
+ *  for none. One position gives a box of no size (fitBounds pads it). */
+export function boundsOf(positions) {
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  for (const p of positions ?? []) {
+    if (!p) continue;
+    if (p.lng < west) west = p.lng;
+    if (p.lng > east) east = p.lng;
+    if (p.lat < south) south = p.lat;
+    if (p.lat > north) north = p.lat;
+  }
+  return west === Infinity ? null : { west, south, east, north };
+}
+
+/** Is the box a single spot (every position the same, give or take a metre)? */
+export function isPointBounds(b) {
+  return Boolean(b) && Math.abs(b.east - b.west) < 1e-5 && Math.abs(b.north - b.south) < 1e-5;
+}
+
+/** Does `b` hold the position? */
+export function inBounds(b, p) {
+  if (!b || !p) return false;
+  const lngIn = b.west <= b.east ? p.lng >= b.west && p.lng <= b.east : p.lng >= b.west || p.lng <= b.east; // across the date line
+  return lngIn && p.lat >= b.south && p.lat <= b.north;
+}
+
+/**
+ * Group points that would overlap on screen at `zoom`.
+ *
+ *   points   [{ id, lat, lng }]
+ *   radius   how close, in screen pixels, two points may sit before they
+ *            merge (default 48 — a marker and its label)
+ *
+ * Returns, in the input order of each group's first point:
+ *   { type: "point", id, lat, lng }
+ *   { type: "cluster", id, ids, count, lat, lng, bounds }
+ *
+ * Greedy, like supercluster's single level: each point not yet taken
+ * gathers every free point within `radius` of it (a grid of radius-sized
+ * cells finds them), and the group sits at their mean. It depends on the
+ * zoom only, never on the pan, so the map recomputes it when the zoom
+ * crosses a step, not on every frame. Thousands of points take a few ms.
+ */
+export function clusterPoints(points, zoom, radius = 48) {
+  const list = (points ?? []).filter((p) => p && isLat(p.lat) && isLng(p.lng));
+  const px = list.map((p) => project(p, zoom));
+  const cell = Math.max(1, radius);
+  const grid = new Map();
+  px.forEach((q, i) => {
+    const key = `${Math.floor(q.x / cell)}:${Math.floor(q.y / cell)}`;
+    const bucket = grid.get(key);
+    if (bucket) bucket.push(i);
+    else grid.set(key, [i]);
+  });
+  const taken = new Uint8Array(list.length);
+  const out = [];
+  const r2 = radius * radius;
+  for (let i = 0; i < list.length; i++) {
+    if (taken[i]) continue;
+    taken[i] = 1;
+    const members = [i];
+    const cx = Math.floor(px[i].x / cell);
+    const cy = Math.floor(px[i].y / cell);
+    for (let gx = cx - 1; gx <= cx + 1; gx++) {
+      for (let gy = cy - 1; gy <= cy + 1; gy++) {
+        for (const j of grid.get(`${gx}:${gy}`) ?? []) {
+          if (taken[j]) continue;
+          const dx = px[j].x - px[i].x;
+          const dy = px[j].y - px[i].y;
+          if (dx * dx + dy * dy <= r2) {
+            taken[j] = 1;
+            members.push(j);
+          }
+        }
+      }
+    }
+    if (members.length === 1) {
+      const p = list[i];
+      out.push({ type: "point", id: p.id, lat: p.lat, lng: p.lng });
+      continue;
+    }
+    const ps = members.map((m) => list[m]);
+    out.push({
+      type: "cluster",
+      id: `cluster:${ps[0].id}:${ps.length}`,
+      ids: ps.map((p) => p.id),
+      count: ps.length,
+      lat: ps.reduce((s, p) => s + p.lat, 0) / ps.length,
+      lng: ps.reduce((s, p) => s + p.lng, 0) / ps.length,
+      bounds: boundsOf(ps),
+    });
+  }
+  return out;
+}
+
+/** The lowest zoom, from `zoom` up in half steps to `maxZoom`, at which
+ *  point `id` stands on its own — where the map must go to show it. Null
+ *  when it never does (it shares its spot with another point). */
+export function zoomToReveal(points, id, zoom, { radius = 48, maxZoom = 18 } = {}) {
+  for (let z = Math.max(0, Math.ceil(zoom * 2) / 2); z <= maxZoom; z += 0.5) {
+    const groups = clusterPoints(points, z, radius);
+    if (groups.some((g) => g.type === "point" && g.id === id)) return z;
+  }
+  return null;
+}
+
+/** Great-circle distance between two positions, in kilometres. */
+export function distanceKm(a, b) {
+  if (!a || !b) return NaN;
+  const rad = Math.PI / 180;
+  const dLat = (b.lat - a.lat) * rad;
+  const dLng = (b.lng - a.lng) * rad;
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(a.lat * rad) * Math.cos(b.lat * rad) * Math.sin(dLng / 2) ** 2;
+  return 2 * EARTH_KM * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+
+/** "350 m", "4.2 km", "38 km" — or miles with unit "mi" ("0.3 mi", "24 mi"). */
+export function formatDistance(km, unit = "km") {
+  if (!Number.isFinite(km)) return "";
+  if (unit === "mi") {
+    const mi = km / 1.609344;
+    return mi < 10 ? `${mi.toFixed(1)} mi` : `${Math.round(mi).toLocaleString("en")} mi`;
+  }
+  if (km < 1) return `${Math.max(10, Math.round((km * 1000) / 10) * 10)} m`;
+  return km < 10 ? `${km.toFixed(1)} km` : `${Math.round(km).toLocaleString("en")} km`;
+}
+
+/** Rows nearest first from `origin`, each with its `distanceKm`; rows
+ *  with no position go last (distance NaN). `positionOf` reads a row. */
+export function sortByDistance(rows, origin, positionOf = readPosition) {
+  return (rows ?? [])
+    .map((row) => ({ row, distanceKm: distanceKm(origin, positionOf(row)) }))
+    .sort((a, b) => (Number.isNaN(a.distanceKm) ? 1 : 0) - (Number.isNaN(b.distanceKm) ? 1 : 0) || a.distanceKm - b.distanceKm);
+}
+
+/** A cheap key for a set of ids: equal keys, the same set. */
+export function idsKey(ids) {
+  return [...ids].map(String).sort().join("|");
+}
+
+/** Lower-cased words a row is found by: the title and the meta line. */
+export function matches(text, query) {
+  const q = String(query ?? "").trim().toLowerCase();
+  if (!q) return true;
+  const hay = String(text ?? "").toLowerCase();
+  return q.split(/\s+/).every((w) => hay.includes(w));
+}

package/registry/blocks/map/index.js

@@ -0,0 +1,8 @@
+// The Map block — `makersclaw add map`. Fixed: compose it through its
+// props (README.md beside this file). The helpers (geo.js) are plain
+// functions and work on the server; the blocks built on this one
+// (location-map, store-locator, the Map view of work-views) import it,
+// never maplibre-gl or react-map-gl directly.
+export { MapView, useMapView } from "./map-view";
+export { MAP_STYLES, DEFAULT_STYLE, TONES } from "./theme";
+export { readPosition, boundsOf, inBounds, clusterPoints, zoomToReveal, distanceKm, formatDistance, sortByDistance } from "./geo";