@close-by/clay 0.2.18 → 0.2.20

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 |
@@ -1219,6 +1220,21 @@ ui.radialChart({
 });
 ```
 
+#### Live chart updates
+
+Every chart factory and `ui.chart.*` builder returns a `ChartElement`:
+
+| Method | What it sends |
+|--------|---------------|
+| `appendData(rows, { max? })` | `appendRows` with only the new rows; client trims to the last `max` |
+| `setData(rows)` | `updateProps` (`data`) |
+| `upsertData(row, { key?, max? })` | Replaces the row with the same `key` (default `xKey`, or `nameKey` for pies) or appends it |
+| `setSeries(series)` / `setHeadline(h)` / `setTitle(t)` / `setDescription(d)` / `setLoading(b)` | `updateProps` for that prop |
+
+`ui.stat(items)` returns a `StatElement` with `setItems(items)`, `updateItem(titleOrIndex, patch)` and `appendSparkline(titleOrIndex, points, { max? })`. Each sends one `updateProps` (`items`).
+
+All charts accept `animate?: boolean` (default `true`). See [Updating in place](./updating-in-place.md#live-charts-appenddata--setdata--upsertdata).
+
 #### Structured charts (`ui.chart`)
 
 Optional sugar over the props APIs above. Mode-first builders compile to the same `Element` types — legacy `ui.areaChart` / `ui.pieChart` / etc. remain fully supported.
@@ -1804,6 +1820,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 +1938,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 +2037,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 +2213,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
 
@@ -26,6 +26,7 @@ Each page sets `group` / `groupIcon` in its `pageMeta`, so the sidebar and the h
 | `/examples/reui-batches` | `ReuiBatchesDemo.ts` | ReUI batches 3–6: `buttonGroup`, `empty`, `pagination`, `filterBar`, form inputs, `navigationMenu`, `notice`, `stat`+sparkline, `eventCalendar`, datatable `showFilterChips` |
 | `/examples/reui-batch-7` | `ReuiBatch7Demo.ts` | ReUI batch 7: `inputGroup`, `toggle`, `descriptionList`, `staticTable`, `aspectRatio`, `itemList`, `checkboxGroup` |
 | `/examples/charts` | `ChartDemo.ts` | `ui.chart.*`, `ui.sparkline`, composed/scatter charts |
+| `/examples/live-charts` | `LiveCharts.ts` | Live charts: `appendData` sliding windows, `setData` tweens, `upsertData` buckets, live gauge and sparklines |
 | `/examples/slider-demo` | `SliderDemo.ts` | Slider, checkbox, select + bindings |
 | `/examples/themes` | `ThemesDemo.ts` | Palette gallery: `ui.theme.palette`, light/dark, component preview |
 | `/examples/layout` | `LayoutDemo.ts` | Fill layout: `fillViewport`, `grow`, `scroll`, `ui.grid` |
@@ -44,6 +45,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/docs/protocol.md

@@ -79,6 +79,7 @@ Browser Back/Forward (or other `popstate`) changed the query and/or hash **witho
 | `replace` | `id`, `node` | Replace entire subtree at `id` |
 | `updateProps` | `id`, `props` | Shallow-merge props |
 | `setChildren` | `id`, `children` | Replace children array |
+| `appendRows` | `id`, `prop`, `rows`, `max?` | Append `rows` to the array prop `prop`, then keep the last `max` items (chart streaming) |
 | `remove` | `id` | Remove node from parent |
 
 ### `navigate`

package/docs/updating-in-place.md

@@ -20,6 +20,7 @@ The flicker is caused by the remount, not by the new value. If a frame carries o
 | Change one value (a label, badge, or input) | `label.setText(…)`, `el.setValue(…)`, `el.update({ … })` | `updateProps` for that element |
 | Live table data | `table.setRows(rows)` on a table created with a stable `keyField` (add `highlightChanges: true` to flash changed rows) | `updateProps` on the table; rows keyed by `keyField` keep their DOM |
 | Table refetch | `table.setLoading(true)` / `table.withLoading(fn)` | `updateProps` (`loading`); previous rows stay, dimmed, instead of blanking |
+| Live chart data (any chart) | `chart.appendData(point, { max })` for a stream, `chart.setData(rows)` for a snapshot, `chart.upsertData(row)` for a growing bucket | `appendRows` with only the new points, or `updateProps` (`data`); the chart stays mounted |
 | A section whose structure depends on data | `ui.refreshable(() => …)` + `.refresh()`, or `ui.auto(() => …)` | Reconciled: matched children get `updateProps` only; added, removed, or reordered children cause one `setChildren` per affected parent |
 | Items in a list inside either of the above | `.key(item.id)` on each item | Items keep their identity through reorder, filter, and prepend |
 
@@ -31,7 +32,7 @@ When a `refreshable` or `auto` block re-runs, Clay builds a fresh tree and match
 
 1. **Keyed first.** A new child with `.key(k)` matches the old child with the same key and the same element type. Keyed children are matched only by key.
 2. **Unkeyed by position.** Unkeyed children are matched in order, by element type. If the next old child matches the current new one, the current old child was removed and is skipped. If the current old child matches the next new one, the new child was inserted. Otherwise the pair is treated as a replacement at that position. This lookahead covers a single insert or remove; larger reshuffles should be keyed.
-3. **Matched pairs keep the old element and its id.** The fresh element's handlers and props are copied onto the old one. Only props that actually changed are sent, as one `updateProps`.
+3. **Matched pairs keep the id on screen.** The freshly built element takes over the old element's id and the old one is destroyed. Only props that actually changed are sent, as one `updateProps`. Because the fresh instance is the one that stays live, its built-in handlers (table search, sort and paging, map drags) and any reference you saved while building (`table = ui.dataTable(...)`) keep working after the refresh.
 4. **Leftovers.** Old children with no match are destroyed. New children with no match are mounted. The parent sends one `setChildren` only if its list of ids changed. A child whose type changed at a position is replaced; its siblings keep their ids.
 5. **Nested blocks keep their instance.** A nested `refreshable` or `auto` keeps its id and its subscriptions and adopts the new builder, so its own refreshes keep working.
 
@@ -103,11 +104,35 @@ async function refresh() {
 
 If you want columns to stay fixed across refreshes, pass `columns` explicitly. Otherwise columns are inferred again on each `setRows`.
 
+### Live charts (`appendData` / `setData` / `upsertData`)
+
+Every chart (`ui.lineChart`, `areaChart`, `barChart`, `composedChart`, `scatterChart`, `pieChart`, `radarChart`, `radialChart`, `sparkline`, and the `ui.chart.*` builders) returns a `ChartElement`. Create it once and push data into it.
+
+```typescript
+const latency = ui.lineChart({ data: seed, xKey: 't', series: [{ key: 'p50', label: 'p50' }] });
+const byRegion = ui.barChart({ data: regions, xKey: 'region', series: [{ key: 'orders', label: 'Orders' }] });
+
+ui.timer(1, () => {
+  latency.appendData({ t: clock(), p50: sample() }, { max: 60 }); // only the new point is sent
+  latency.setHeadline({ value: `${p50} ms` });
+});
+ui.timer(5, async () => byRegion.setData(await fetchRegions())); // bars tween to the new values
+```
+
+- **`appendData(rows, { max })`** sends only the new rows. The client appends them and drops the oldest past `max`, so a sliding window costs one point per tick.
+- **`setData(rows)`** replaces the data. When the row count and first x value are unchanged, the marks tween to their new values.
+- **`upsertData(row, { key, max })`** replaces the row with the same x value (or `nameKey` for pies), or appends it. Use it for a bucket that keeps growing, such as the current minute.
+- **`setSeries`, `setHeadline`, `setTitle`, `setDescription`, `setLoading`** patch one prop each. Anything else goes through `update({ … })`.
+
+KPI stat grids work the same way: `ui.stat(items)` returns a `StatElement`. `updateItem(titleOrIndex, patch)` changes one card, `appendSparkline(titleOrIndex, points, { max })` extends that card's sparkline, and `setItems(items)` replaces them all.
+
+Appends and sliding windows draw without animation, so lines don't slide sideways or replay their entrance. Pass `animate: false` to turn chart animation off entirely. The interactive period tabs keep the selected period while data streams in.
+
 ## Anti-patterns
 
 - **Rebuilding a whole section when one value changes.** Wrapping a whole page in `ui.refreshable` and calling `.refresh()` every second to update a clock. Keep a reference to the clock label and call `setText`.
 - **Unkeyed lists that get sorted or filtered.** Without `.key()`, position is the identity. After a sort, the element in slot 3 is reused for whatever item is now third, so focus and typed text stay in the slot instead of following the row.
-- **Creating a new table instead of `setRows`.** A `ui.dataTable(...)` created inside a refreshable on every tick remounts the table and loses sort, scroll, selection, and search. Create the table once and call `setRows`.
+- **Creating a new table instead of `setRows`.** A `ui.dataTable(...)` rebuilt inside a refreshable keeps its id and stays interactive, but each rebuild starts the table's server-side state over, so sort, search, page and selection reset. Create the table once and call `setRows`.
 - **Tables without `keyField`.** Rows are stamped `__rowId` by their index, so inserting or re-sorting the source shifts every row's identity. Set `keyField` to your primary key.
 - **Toggling a constructor option by rebuilding.** Recreating a table with `zebra: on` inside an `auto` block. Use the setters instead: `setZebra`, `setDensity`, `setHighlightChanges`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "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.20",
+    "@close-by/clay-core": "0.2.20",
+    "@close-by/clay-components": "0.2.20",
+    "@close-by/clay-server": "0.2.20",
     "@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,
@@ -200,6 +203,8 @@ import {
   type CheckboxGroupProps,
   type CheckboxGroupOption,
   type StatItem,
+  type StatItemRef,
+  type StatElement,
   type DataTableProps,
   type DataTableAction,
   type DataTableView,
@@ -232,6 +237,7 @@ import {
   type ComposedChartProps,
   type ComposedChartSeries,
   type ComposedSeriesType,
+  type ChartElement,
   type CartesianChartProps,
   type ChartSeries,
   type ChartHeadline,
@@ -346,6 +352,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,
@@ -412,7 +426,6 @@ import {
   DialogElement,
   DialogStackElement,
   StepperElement,
-  NavigationMenuElement,
   AlertDialogElement,
   DropdownMenuElement,
   ContextMenuElement,
@@ -455,6 +468,7 @@ import {
   timer as timerCore,
   storage as storageCore,
   theme as themeCore,
+  sound as soundCore,
   reactive as reactiveCore,
   state as stateCore,
   subscribe as subscribeCore,
@@ -515,6 +529,9 @@ export {
 } from './tailwind';
 
 
+export { ChartElement, StatElement } from '@close-by/clay-components';
+export type { StatItemRef } from '@close-by/clay-components';
+
 export type {
   GridProps,
   LayoutProps,
@@ -642,6 +659,15 @@ export type {
   GanttDependency,
   GanttRange,
   GanttItemMovePayload,
+  MapProps,
+  MapMarkerDatum,
+  MapRouteDatum,
+  MapArcGroup,
+  MapGeoJSONLayer,
+  MapClusterGroup,
+  MapHeatmapLayer,
+  LngLat,
+  MapTone,
   FlowProps,
   FlowNodeProps,
   FlowNodeKind,
@@ -1180,6 +1206,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);
@@ -1193,7 +1228,7 @@ export function flow(a: any, b?: any): FlowElement {
 }
 
 /** Stat strip (label/value items). Prefer `ui.stat`. */
-export function stat(items: StatItem[], props?: { className?: string }): Element {
+export function stat(items: StatItem[], props?: { className?: string }): StatElement {
   return statFactory(items, props);
 }
 
@@ -1217,47 +1252,47 @@ export const chart = chartNamespace;
 export const ai = aiNamespace;
 
 /** Area chart. Prefer `ui.areaChart`. See {@link AreaChartProps}. */
-export function areaChart(props: AreaChartProps): Element {
+export function areaChart(props: AreaChartProps): ChartElement {
   return areaChartFactory(props);
 }
 
 /** Bar chart. Prefer `ui.barChart`. See {@link BarChartProps}. */
-export function barChart(props: BarChartProps): Element {
+export function barChart(props: BarChartProps): ChartElement {
   return barChartFactory(props);
 }
 
 /** Line chart. Prefer `ui.lineChart`. See {@link LineChartProps}. */
-export function lineChart(props: LineChartProps): Element {
+export function lineChart(props: LineChartProps): ChartElement {
   return lineChartFactory(props);
 }
 
 /** Pie / donut chart. Prefer `ui.pieChart`. See {@link PieChartProps}. */
-export function pieChart(props: PieChartProps): Element {
+export function pieChart(props: PieChartProps): ChartElement {
   return pieChartFactory(props);
 }
 
 /** Radar chart. Prefer `ui.radarChart`. See {@link RadarChartProps}. */
-export function radarChart(props: RadarChartProps): Element {
+export function radarChart(props: RadarChartProps): ChartElement {
   return radarChartFactory(props);
 }
 
 /** Radial / gauge chart. Prefer `ui.radialChart`. See {@link RadialChartProps}. */
-export function radialChart(props: RadialChartProps): Element {
+export function radialChart(props: RadialChartProps): ChartElement {
   return radialChartFactory(props);
 }
 
 /** Scatter chart. Prefer `ui.scatterChart`. See {@link ScatterChartProps}. */
-export function scatterChart(props: ScatterChartProps): Element {
+export function scatterChart(props: ScatterChartProps): ChartElement {
   return scatterChartFactory(props);
 }
 
 /** Composed multi-geometry chart. Prefer `ui.composedChart`. See {@link ComposedChartProps}. */
-export function composedChart(props: ComposedChartProps): Element {
+export function composedChart(props: ComposedChartProps): ChartElement {
   return composedChartFactory(props);
 }
 
 /** KPI card with inline sparkline. Prefer `ui.sparkline`. See {@link SparklineProps}. */
-export function sparkline(props: SparklineProps): Element {
+export function sparkline(props: SparklineProps): ChartElement {
   return sparklineFactory(props);
 }
 
@@ -1677,6 +1712,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 +1962,7 @@ export const ui = {
   list,
   imageCrop,
   gantt,
+  map,
   flow,
   stat,
   dataTable,
@@ -1991,6 +2030,7 @@ export const ui = {
   timer,
   storage,
   theme,
+  sound,
   reactive,
   state,
   urlState,