@close-by/clay 0.2.18 → 0.2.19

package/docs/README.md

@@ -22,6 +22,7 @@ For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these
 | [Ops patterns](./ops-patterns.md) | Dense consoles: chips, master–detail, feeds, sensitive logs, auth nav |
 | [API reference](./api.md) | `ui.*`, `Element` methods, `reactive`, helpers |
 | [Elements](./elements.md) | All element types and props |
+| [Maps](./maps.md) | `ui.map`: MapLibre markers, routes, arcs, GeoJSON, clusters; palette theming and in-place updates |
 | [WebSocket protocol](./protocol.md) | Client ↔ server message formats |
 | [Architecture](./architecture.md) | Packages, data flow, and ownership |
 | [Examples](./examples.md) | Demo apps and patterns |

package/docs/api.md

@@ -91,6 +91,7 @@ ui.run({
 | `title` | `string` | `'Clay'` | HTML `<title>` |
 | `clientDir` | `string` | `resolveClayClientDir()` | Built Vite assets (`@close-by/clay-cli/client-dist` when installed). Prefer `resolveClayClientDir()` over hardcoding `node_modules` paths — see [Boot](./boot.md). |
 | `css` | `string \| string[]` | | Extra CSS file path(s) served after the client bundle (absolute or cwd-relative). Override theme tokens without rebuilding the client. |
+| `sound` | `boolean` | | Play short synthesized interface sounds by default (`false`). See [Sound](#sound). |
 | `app` | `AppProps` | | Global dashboard shell; client keeps chrome sticky across navigate |
 | `authSecret` | `string` | | Enables signed auth cookies (`POST`/`DELETE /auth/session`), `ui.establishAuthSession` / `ui.clearAuthSession`, and default `resolveUserId` from the cookie |
 | `authCookieMaxAgeSec` | `number` | `43200` (12h) | Auth cookie Max-Age |
@@ -1804,6 +1805,10 @@ onClick: async () => {
 | `ui.theme.palette(name)` | `void` | Switch colour palette for this client (`kiln`, `cobalt`, `ocean`, `forest`, `orchid`, `citrus`, `graphite`, `neon`, `sky`, `navy`, `indigo`, `denim`, `midnight`, or a custom one); remembered across reloads |
 | `ui.theme.getPalette()` | `ThemePalette \| null` | Last palette set, else the one the client reported on connect |
 | `ui.theme.palettes` | `readonly string[]` | Built-in palette names |
+| `ui.sound.set(on)` | `void` | Turn automatic interface sounds on/off for this client; remembered across reloads. See [Sound](#sound) |
+| `ui.sound.volume(v)` | `void` | Master volume `0`–`1` (default `0.5`); remembered across reloads |
+| `ui.sound.play(name)` | `void` | Play one cue now, even when automatic sounds are off |
+| `ui.sound.names` | `readonly string[]` | Built-in cue names |
 | `ui.runJavaScript(code)` | `void` | Eval trusted snippet in the browser |
 | `ui.scroll.to(opts)` | `void` | Scroll window (`top` / `bottom` / px) |
 | `ui.scroll.intoView(selector, opts?)` | `void` | `Element.scrollIntoView` via selector |
@@ -1918,6 +1923,7 @@ All layout helpers accept either `(fn, props?)` or `(props, fn)`.
 | `ui.hero` | Centered hero region |
 | `ui.card` | Card; callback receives the card element |
 | `ui.app` | SPA shell: sidebar nav + centered main content |
+| `ui.map` | Live map (MapLibre): markers, routes, arcs, GeoJSON, clusters, popup. See [Maps](./maps.md) |
 
 #### `ui.app(props, fn)`
 
@@ -2016,6 +2022,15 @@ ui.container(() => {
 }, { centered: true, width: 'md' });
 ```
 
+#### `ui.map(props?)`
+
+A live map: MapLibre with markers, routes, arcs, GeoJSON layers, clusters and a popup. Setters (`setMarkers`, `upsertMarker`, `updateRoute`, `flyTo`, `fitBounds`, ...) update it in place. Props, tones, events and layout are in the [Maps guide](./maps.md).
+
+```typescript
+const fleet = ui.map({ fill: true, markers: vehicles(), onMarkerClick: (m) => select(m.id) });
+fleet.fitBounds('markers', { padding: 48 });
+```
+
 ---
 
 ## `Element` methods (`@close-by/clay-core`)
@@ -2183,6 +2198,33 @@ import { button, input /* … */ } from '@close-by/clay-components';
 
 ---
 
+## Sound
+
+Clay can answer interactions with short interface sounds, synthesized in the browser with Web Audio (no audio files). They're **off by default**. Turn them on for every visitor with `createServer({ sound: true })`, or per session with `ui.sound.set(true)`. The client remembers the last choice.
+
+Once sound is on, a mute button appears next to the Clay connection chip in the bottom-left corner, so each user can silence it. A user's mute choice is remembered for their browser. Apps that never turn sound on don't show the button.
+
+When enabled, a page-wide listener picks the cue from the element, so components need no wiring:
+
+| Interaction | Cue |
+|---|---|
+| Button, link, `role="button"` | `tap` (`soft` for `ghost` / `link` variants, `destructive` for the destructive variant) |
+| Tab, menu item, option, radio | `select` (pitch rises with position) |
+| Switch, checkbox | `toggleOn` / `toggleOff` |
+| Disabled control (when it still receives the press) | `blocked` |
+| Dialog / sheet / alert dialog opens or closes | `open` / `close` |
+| Slider value changes | `tick` |
+| OTP digit typed | `key` |
+| `ui.notify` toast | `success` / `error` / `warning` / `notification` by type |
+| `ui.clipboard` / code block copy | `copy` |
+
+Set `data-sound="<cue>"` on an element to override its cue, or `data-sound="none"` to silence it. Use `ui.sound.play(name)` to play a cue from server code, for example when a long job finishes. Cues: `tap`, `soft`, `select`, `destructive`, `blocked`, `toggleOn`, `toggleOff`, `open`, `close`, `tick`, `key`, `copy`, `success`, `error`, `warning`, `notification`.
+
+```ts
+// A settings switch that lets each user turn sounds on or off
+ui.switch({ label: 'Interface sounds', onChange: (on) => ui.sound.set(on) });
+```
+
 ## DuckDB (`@close-by/clay-duckdb`)
 
 See [DuckDB](./duckdb.md) for the multi-database wrapper (`connect`, `attach`, CRUD).

package/docs/demo-deployment.md

@@ -0,0 +1,64 @@
+# Demo deployment on Pi
+
+The demo runs at https://clay.close-by.org/ on Pi as the `bad-ui-demo` systemd service. It runs Bun as the `pi` user from `/home/pi/bad-ui-demo` on port 4000. The existing Flock Cloudflare tunnel forwards `clay.close-by.org` to `http://localhost:4000`; the Cloudflare DNS record is a proxied CNAME to that tunnel.
+
+## Update the demo
+
+From the repository root on a machine with SSH access to the `pi` host, copy the working tree and rebuild on Pi:
+
+```sh
+tar --exclude-vcs --exclude=node_modules --exclude=dist-pack \
+  --exclude=.env --exclude='.env.*' --exclude=.badui-user-data \
+  --exclude=.clay-user-data --exclude=.clay --exclude=.tmp \
+  -czf /tmp/clay-demo-deploy.tgz .
+scp /tmp/clay-demo-deploy.tgz pi:/tmp/clay-demo-deploy.tgz
+ssh pi 'tar -xzf /tmp/clay-demo-deploy.tgz -C ~/bad-ui-demo && \
+  cd ~/bad-ui-demo && export PATH="$HOME/.local/bin:$PATH" && \
+  bun install --frozen-lockfile && bun run build:client && \
+  sudo systemctl restart bad-ui-demo'
+```
+
+This copies the current working tree, including uncommitted changes. Extraction does not delete files removed from the source tree; remove obsolete deployed files deliberately when needed. The service keeps running the previous process until the restart, but the copy and build happen in its working directory.
+
+Check the service and public endpoint:
+
+```sh
+ssh pi 'systemctl status bad-ui-demo --no-pager; journalctl -u bad-ui-demo -n 50 --no-pager'
+curl -I https://clay.close-by.org/
+```
+
+## Service and tunnel setup
+
+The service is enabled with `sudo systemctl enable --now bad-ui-demo`. Its unit is `/etc/systemd/system/bad-ui-demo.service`:
+
+```ini
+[Unit]
+Description=Clay demo
+After=network.target
+
+[Service]
+User=pi
+WorkingDirectory=/home/pi/bad-ui-demo
+Environment=PORT=4000
+Environment=PATH=/home/pi/.local/bin:/usr/local/bin:/usr/bin:/bin
+EnvironmentFile=/home/pi/.config/bad-ui-demo/service.env
+ExecStart=/home/pi/.local/bin/bun apps/demo/src/main.ts
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
+```
+
+The environment file contains `CLAY_AUTH_SECRET`; keep it private and stable across restarts. To create it on a fresh deployment, use `umask 077`, create `/home/pi/.config/bad-ui-demo`, and write `CLAY_AUTH_SECRET=` followed by a random secret (for example, from `openssl rand -hex 32`). Changing it invalidates existing signed sessions. After changing a unit, run `sudo systemctl daemon-reload` and restart the service.
+
+The tunnel configuration is `/etc/cloudflared/flock.yml`, managed by `flock-tunnel.service`. Its Clay ingress entry must precede the final catch-all:
+
+```yaml
+- hostname: clay.close-by.org
+  service: http://localhost:4000
+```
+
+Validate changes with `sudo cloudflared tunnel --config /etc/cloudflared/flock.yml ingress validate`, then restart `flock-tunnel`. This is shared with Flock, so preserve its existing ingress entries. The DNS CNAME must point to the existing tunnel's `<tunnel-id>.cfargotunnel.com` and be proxied; the tunnel credentials on Pi alone do not grant permission to edit Cloudflare DNS.
+
+This is a public demo with example authentication and data, not a hardened production application. See [Production & security](./production.md) before deploying real data or applications.

package/docs/examples.md

@@ -7,7 +7,7 @@ After `bun run build:client && bun run demo` (or `bun run demo:cli`), open http:
 
 ## Sidebar groups
 
-Each page sets `group` / `groupIcon` in its `pageMeta`, so the sidebar and the home page's catalog share one structure: **Start here** (themes, fill layout, counter, todo, kitchen sink) → **Reactivity** → **Data** → **Forms & controls** → **Overlays & layout** → **Apps** → **Account** → **ReUI batches**. Order within a group is `pageMeta.order`.
+Each page sets `group` / `groupIcon` in its `pageMeta`, so the sidebar and the home page's catalog share one structure: **Start here** (themes, fill layout, counter, todo, kitchen sink) → **Reactivity** → **Data** → **Maps** (gallery, delivery tracker, store locator, globe, uptime monitor) → **Forms & controls** → **Overlays & layout** → **Apps** → **Account** → **ReUI batches**. Order within a group is `pageMeta.order`.
 
 ## Catalog
 
@@ -44,6 +44,11 @@ Each page sets `group` / `groupIcon` in its `pageMeta`, so the sidebar and the h
 | `/examples/gantt` | `GanttDemo.ts` | `ui.gantt` owned rows/dates/markers/deps, cross-row drag, header double-click markers, `itemMove` / `markerAdd` settle |
 | `/examples/flow` | `FlowDemo.ts` | Four `ui.flow` demos: ETL with in-node controls + labeled edges + dagre auto-layout, multi-handle approval branches, fan-in/out + `addNode` dynamic stages, group/`parentId` nesting (flow-owned edges/positions; no outer diagram `ui.auto`) |
 | `/examples/data-clients` | `DataClientsDemo.ts` | DuckDB / Kibana / ClickHouse integration story (mock-friendly) |
+| `/examples/maps` | `MapsGallery.ts` | `ui.map` gallery: markers and popups, routes, arcs, choropleth, clusters, compact analytics map |
+| `/examples/delivery-tracker` | `DeliveryTracker.ts` | `ui.map` route progress and courier marker: `updateRoute` / `upsertMarker` on a timer, `fill` layout |
+| `/examples/store-locator` | `StoreLocator.ts` | `ui.map` filtered markers, `flyTo` / `fitBounds('markers')`, popups; list and map select each other by key |
+| `/examples/globe` | `CommunityGlobe.ts` | `ui.map` globe projection, arcs, `setMarkers` / `setArcs` on a 30 s timer |
+| `/examples/uptime` | `UptimeMonitor.ts` | `ui.map` status markers on a globe, refreshed every 2 s with `setMarkers` |
 | `/examples/kitchen-sink` | `KitchenSink.ts` | ShadCN catalog preview (client `KitchenSink`) |
 
 Each page file exports optional `pageMeta` (`label`, `icon`, `order`, optional `nav: false`, optional `roles`) for `ui.navFromPages()`.

package/docs/maps.md

@@ -0,0 +1,214 @@
+# Maps
+
+`ui.map(props)` is a live map with markers, routes, arcs, GeoJSON layers, clusters, heatmaps and a popup. It renders with [MapLibre GL](https://maplibre.org/) through a vendored copy of [mapcn](https://mapcn.vercel.app) (MIT). You create the map on the server, change it with setters, and handle clicks on the server.
+
+- **Lazy.** The client loads the map code only when a page renders a map (`React.lazy` in the element renderer). Other pages do not download MapLibre.
+- **Worker bundled.** The MapLibre worker ships with the client build. No CDN script is loaded.
+
+## Quick start
+
+```typescript
+import { ui } from '@close-by/clay';
+
+ui.page('/fleet', () => {
+  const fleet = ui.map({
+    center: [-9.14, 38.72],
+    zoom: 11,
+    height: '28rem',
+    markers: [
+      { id: 'hq', lngLat: [-9.142, 38.7108], label: 'HQ', popup: { title: 'Head office' } },
+      { id: 'truck-1', lngLat: [-9.1393, 38.7097], tone: 'chart-2', icon: 'truck', pulse: true },
+    ],
+    onMarkerClick: (marker) => ui.notify(`Selected ${marker.id}`),
+  });
+
+  fleet.fitBounds('markers', { padding: 48 });
+});
+```
+
+Coordinates are always `[longitude, latitude]`.
+
+## Theming
+
+- **Light and dark.** The basemap follows the page theme. Markers, routes, arcs and fills take their colours from the active palette.
+- **Tones.** Colour props accept a tone name or a CSS colour such as `#2563eb`:
+
+  | Tone | Palette token |
+  |------|---------------|
+  | `primary` | `--primary` (default for markers, routes and fills) |
+  | `chart-1` … `chart-5` | `--chart-1` … `--chart-5` |
+  | `destructive` | `--destructive` |
+  | `muted` | `--muted-foreground` |
+  | `foreground` | `--foreground` |
+
+- **Live palette changes.** The map watches the root element's `class`, `data-palette` and `style`, and the system colour scheme. A palette change re-resolves the colours in place. The map is not remounted, so the camera and open popups stay put.
+- **`tint`** (default `true`) lightly tints the basemap toward the palette: background, water, and parks or green areas.
+- **`basemap`** (default `'auto'`) pins the basemap to `'light'` or `'dark'`, whatever the page theme.
+- **`styles`** replaces the basemap style URLs: `{ light?: string; dark?: string }`. See [Tiles](#tiles).
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `center` | `LngLat` | `[0, 20]` | Initial centre, read at mount. See [Camera](#camera) |
+| `zoom` | `number` | `1.5` | Initial zoom |
+| `pitch` / `bearing` | `number` | `0` | Initial pitch and bearing |
+| `projection` | `'mercator' \| 'globe'` | `'mercator'` | |
+| `height` | `string` | `'24rem'` | CSS length. Ignored with `fill` |
+| `fill` | `boolean` | `false` | Fill the parent. See [Layout](#layout) |
+| `interactive` | `boolean` | `true` | `false` disables pan, zoom and click |
+| `basemap` | `'auto' \| 'light' \| 'dark'` | `'auto'` | |
+| `styles` | `{ light?, dark? }` | CARTO styles | Custom MapLibre style URLs |
+| `tint` | `boolean` | `true` | Palette tint on the basemap |
+| `controls` | `MapControls \| false` | `{ zoom: true, position: 'bottom-right' }` | Object values merge over the default. `false` hides all controls |
+| `markers` | `MapMarkerDatum[]` | `[]` | |
+| `routes` | `MapRouteDatum[]` | `[]` | |
+| `arcs` | `MapArcGroup[]` | `[]` | |
+| `geojson` | `MapGeoJSONLayer[]` | `[]` | |
+| `clusters` | `MapClusterGroup[]` | `[]` | |
+| `heatmaps` | `MapHeatmapLayer[]` | `[]` | |
+| `popup` | `{ lngLat, title?, description? } \| null` | closed | Standalone popup |
+
+`MapControls` is `{ zoom?, compass?, locate?, fullscreen?, position? }`. `compass`, `locate` and `fullscreen` are off by default. `position` is `top-left`, `top-right`, `bottom-left` or `bottom-right`.
+
+## Data layers
+
+**Markers.** `id` (required, unique) and `lngLat` are required. Optional: `tone`, `label` (always visible), `tooltip` (on hover), `popup` (on click: `title`, `description`, `meta: [{ label, value }]`), `icon` (Lucide kebab-case name, drawn in a 28 px pin), `size` (`sm` / `md` / `lg` dots of 10 / 14 / 20 px, used when there is no icon), `pulse` (animated ring), `draggable`.
+
+**Routes.** `id` and `coordinates: [lng, lat][]` are required. Optional: `tone`, `width` (px), `opacity`, `dashed`, `progress` (0..1: draws a progress overlay and a marker there), `progressIcon` (default `navigation`), `progressMarker` (default `true`; set `false` when you track the vehicle with your own marker), `progressTone` (colour of the travelled part, default `primary`), `active` (emphasise the selected route), `showEndpoints` (start ring and end dot). Change one route with `updateRoute` (see [Live data](#live-data--in-place-updates)).
+
+**Arcs.** Grouped. A group has `id`, `tone`, `width`, `curvature` and `data: { id, from, to, label? }[]`. Arc ids are unique within their group.
+
+```typescript
+ui.map({
+  projection: 'globe',
+  arcs: [{ id: 'lanes', tone: 'chart-1', data: [{ id: 'lis-mad', from: [-9.14, 38.72], to: [-3.7, 40.42], label: 'Lisbon to Madrid' }] }],
+  onArcClick: (arc, group) => ui.notify(`${arc.label ?? arc.id} (${group.id})`),
+});
+```
+
+**GeoJSON.** `{ id, data, fillTone?, lineTone?, fillOpacity?, choropleth?, interactive?, promoteId? }`. `data` is a FeatureCollection, a Feature, or a URL string. A choropleth is `{ property, stops: [value, tone][] }`, with at least two stops. Without a choropleth the layer uses `fillTone`. The default fill opacity is `0.6` for a choropleth and `0.25` otherwise. The server does not validate GeoJSON.
+
+**Clusters.** Grouped points: `{ id, points: [{ id, lngLat, properties? }], tone?, clusterRadius?, clusterMaxZoom? }`. Cluster bubbles use the group tone, `chart-2` and `chart-3`.
+
+**Heatmaps.** `{ id, points: [{ lngLat, weight? }], ramp?, radius?, intensity?, opacity?, maxWeight?, showPointsAtZoom? }`. Weights default to `1` and must be finite and at least `0`. `maxWeight` is the weight that reaches full intensity; it defaults to the largest weight. The `ramp` runs from low to high density and defaults to `['chart-3', 'chart-4', 'primary', 'destructive']`, so it follows the palette and light or dark mode. `radius` (default `20` px at zoom 9) scales with zoom. Set `showPointsAtZoom` to fade the heatmap into individual circles when zoomed in. Replace the data with `setHeatmaps(layers)`; the client updates the source in place.
+
+```typescript
+const heat = ui.map({ projection: 'globe', heatmaps: [{ id: 'quakes', points, maxWeight: 7, showPointsAtZoom: 6 }] });
+heat.setHeatmaps([{ id: 'quakes', points: points.filter((p) => (p.weight ?? 0) >= 5) }]);
+```
+
+**Standalone popup.** `showPopup([lng, lat], { title?, description? })` opens one, and `closePopup()` closes it. The `popup` prop does the same declaratively. Only marker popups take `meta` rows.
+
+## Camera
+
+| Method | Behaviour |
+|--------|-----------|
+| `flyTo(center, zoom?, { duration? })` | Animates. Keeps the current zoom when `zoom` is omitted |
+| `fitBounds([sw, ne], { padding? })` | Fits the given bounds |
+| `fitBounds('markers', { padding? })` | Fits all current markers. Does nothing when there are none |
+| `jumpTo(center, zoom?)` | Moves without animation |
+| `setProjection('mercator' \| 'globe')` | Sends a new `projection` |
+
+Each camera call runs once on the client. The server attaches a nonce, so repeating a call moves the map again.
+
+The client reads `center`, `zoom`, `pitch`, `bearing` and `interactive` once, at mount. Changing those props later does not move an existing map. Use the camera methods instead.
+
+## Events
+
+Handlers are registered only when you pass them. Each handler runs on the server, and receives:
+
+| Handler | Fires when | Argument |
+|---------|------------|----------|
+| `onMarkerClick(marker)` | A marker is clicked | The current marker datum |
+| `onMarkerDragEnd(marker, lngLat)` | A draggable marker is dropped | The updated marker and its new `lngLat`. The stored position is updated first |
+| `onRouteClick(route)` | A route is clicked | The current route datum |
+| `onArcClick(arc, group)` | An arc is clicked | The arc and its group |
+| `onFeatureClick(feature)` | A GeoJSON feature is clicked | `{ layerId, featureId?, properties }` |
+| `onClusterPointClick(point, group)` | A clustered point is clicked | The point and its group |
+| `onMapClick(lngLat)` | The map is clicked | `[lng, lat]` |
+| `onViewportChange(viewport)` | The camera stops moving (`moveend`) | `{ center, zoom, bearing, pitch }` |
+| `onLocate(lngLat)` | The locate control is used (needs `controls.locate`) | `[lng, lat]` |
+
+
+`markerDragEnd` is always recorded on the server, even without `onMarkerDragEnd`, so a later `fitBounds('markers')` uses the dropped position.
+
+## Live data & in-place updates
+
+The map owns its marker, route, arc, cluster and popup state. Each setter sends only the prop it changes, so the client patches the map instead of rebuilding it. Markers are keyed by `id`: when a marker's `lngLat` changes, it moves, and its DOM node stays.
+
+| Method | What it does |
+|--------|--------------|
+| `setMarkers(list)` | Replaces all markers |
+| `upsertMarker(marker)` | Inserts, or replaces the marker with the same id |
+| `removeMarker(id)` | Removes a marker. No-op if absent |
+| `setRoutes(list)` / `updateRoute(id, patch)` | Replaces all routes, or merges `patch` into one. The id cannot change |
+| `setArcs(groups)` / `setGeoJSON(layers)` / `setClusters(groups)` / `setHeatmaps(layers)` | Replace that layer type |
+
+A courier moving along a route:
+
+```typescript
+ui.timer(0.25, () => {
+  progress = Math.min(1, progress + 0.006);
+  map.updateRoute('delivery-route', { progress });
+  map.upsertMarker({ id: 'courier', lngLat: pointAt(progress), tone: 'chart-2', icon: 'truck' });
+});
+```
+
+**Validation** runs when you create the map or call a setter, before anything is sent. It throws on:
+
+- a missing or empty id, or a duplicate id within its list (markers, routes, arc groups, arcs in a group, cluster groups, points in a group). The message is `duplicate id "…"`.
+- a coordinate that is not `[lng, lat]` with two finite numbers. This covers markers, cluster points, route coordinates, arc endpoints, popups, `flyTo` and `jumpTo` centres, and `fitBounds` corners.
+
+## Layout
+
+`height` gives a fixed-size map in normal flow:
+
+```typescript
+ui.card({ title: 'Stores', className: 'p-0 overflow-hidden' }, () => {
+  ui.map({ height: '26rem', center: [-6, 40], zoom: 5 });
+});
+```
+
+`fill: true` makes the map fill its parent (`h-full min-h-0 flex-1`), so the parent needs a definite height. On a page that fills the window, put `fillViewport` on the outer column and `grow` on the panel that holds the map:
+
+```typescript
+ui.column({ fillViewport: true, gap: 4 }, () => {
+  ui.row({ grow: true, wrap: false, gap: 4 }, () => {
+    ui.card({ title: 'Stores', scroll: true, className: 'w-80 shrink-0' }, () => { /* list */ });
+    ui.column({ grow: true }, () => {
+      ui.map({ fill: true, center: [-6, 40], zoom: 5 });
+    });
+  });
+});
+```
+
+See [API reference: Filling the page](./api.md#filling-the-page).
+
+## Tiles
+
+By default the basemap uses CARTO's hosted styles: Positron for light and Dark Matter for dark, served from `basemaps.cartocdn.com`. Those styles are built on OpenStreetMap data. CARTO's free tier and terms apply, and OpenStreetMap data requires attribution.
+
+Before production, check CARTO's current terms and attribution rules, or pass your own styles. Any MapLibre style URL works:
+
+```typescript
+ui.map({ styles: { light: 'https://your-host.example/light.json', dark: 'https://your-host.example/dark.json' } });
+```
+
+[OpenFreeMap](https://openfreemap.org) publishes free style URLs. Check its terms before you rely on it.
+
+## Demos
+
+All five are under the **Maps** group in the sidebar.
+
+- [`/examples/maps`](../apps/demo/src/examples/MapsGallery.ts): markers and popups, routes, arcs, a choropleth, clusters, a seismic heatmap on a globe, and a compact analytics map.
+- [`/examples/delivery-tracker`](../apps/demo/src/examples/DeliveryTracker.ts): a courier moving along a route, with `updateRoute` and `upsertMarker` on a timer.
+- [`/examples/store-locator`](../apps/demo/src/examples/StoreLocator.ts): a filterable store list where list rows and markers select each other.
+- [`/examples/globe`](../apps/demo/src/examples/CommunityGlobe.ts): a globe with arcs and markers that refresh every 30 seconds.
+- [`/examples/uptime`](../apps/demo/src/examples/UptimeMonitor.ts): a status globe of edge locations, refreshed every 2 seconds.
+
+## See also
+
+- [Updating in place](./updating-in-place.md): the general rules for patching instead of rebuilding
+- [API reference](./api.md#uimapprops): `ui.map` in the Layout section
+- [Examples](./examples.md): the demo catalog

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "description": "NiceGUI-like ui.* facade for Clay apps",
   "license": "MIT",
   "type": "module",
@@ -37,10 +37,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@close-by/clay-compiler": "0.2.18",
-    "@close-by/clay-core": "0.2.18",
-    "@close-by/clay-components": "0.2.18",
-    "@close-by/clay-server": "0.2.18",
+    "@close-by/clay-compiler": "0.2.19",
+    "@close-by/clay-core": "0.2.19",
+    "@close-by/clay-components": "0.2.19",
+    "@close-by/clay-server": "0.2.19",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -113,6 +113,9 @@ import {
   list as listFactory,
   imageCrop as imageCropFactory,
   gantt as ganttFactory,
+  map as mapFactory,
+  type MapElement,
+  type MapProps,
   chart as chartNamespace,
   table as tableFactory,
   flow as flowFactory,
@@ -346,6 +349,14 @@ import {
   type GanttDependency,
   type GanttRange,
   type GanttItemMovePayload,
+  type MapMarkerDatum,
+  type MapRouteDatum,
+  type MapArcGroup,
+  type MapGeoJSONLayer,
+  type MapClusterGroup,
+  type MapHeatmapLayer,
+  type LngLat,
+  type MapTone,
   type FlowProps,
   type FlowNodeProps,
   type FlowNodeKind,
@@ -455,6 +466,7 @@ import {
   timer as timerCore,
   storage as storageCore,
   theme as themeCore,
+  sound as soundCore,
   reactive as reactiveCore,
   state as stateCore,
   subscribe as subscribeCore,
@@ -642,6 +654,15 @@ export type {
   GanttDependency,
   GanttRange,
   GanttItemMovePayload,
+  MapProps,
+  MapMarkerDatum,
+  MapRouteDatum,
+  MapArcGroup,
+  MapGeoJSONLayer,
+  MapClusterGroup,
+  MapHeatmapLayer,
+  LngLat,
+  MapTone,
   FlowProps,
   FlowNodeProps,
   FlowNodeKind,
@@ -1180,6 +1201,15 @@ export function gantt(props?: GanttProps): GanttElement {
   return ganttFactory(props);
 }
 
+/**
+ * Live map (MapLibre, styled to the Clay theme) with markers, routes, arcs,
+ * GeoJSON layers, clusters and a popup. Owns its marker / route / popup /
+ * camera state; setters update in place. See {@link MapProps}.
+ */
+export function map(props?: MapProps): MapElement {
+  return mapFactory(props);
+}
+
 /**
  * Interactive flow diagram (`@xyflow/react`). Owns edges + positions;
  * node bodies are Clay trees; drag by card chrome (controls are nodrag);
@@ -1677,6 +1707,9 @@ export const storage = storageCore;
 /** Server-driven appearance (`light` | `dark` | `system`). */
 export const theme = themeCore;
 
+/** Interface sound cues: `ui.sound.set(on)`, `ui.sound.volume(0..1)`, `ui.sound.play(name)`. */
+export const sound = soundCore;
+
 /** Proxy that notifies subscribers on property change. Prefer this over importing from `@close-by/clay-core`. */
 export const reactive = reactiveCore;
 
@@ -1924,6 +1957,7 @@ export const ui = {
   list,
   imageCrop,
   gantt,
+  map,
   flow,
   stat,
   dataTable,
@@ -1991,6 +2025,7 @@ export const ui = {
   timer,
   storage,
   theme,
+  sound,
   reactive,
   state,
   urlState,