@nika-js/onlymap 0.5.2 → 0.5.6

package/skills/onlymapjs/references/syntax.md

@@ -16,8 +16,8 @@ Vite/npm project:
 Static CDN page (raw-file CDNs only — unpkg/jsDelivr; never esm.sh or another rebundling CDN, which duplicates the WebGL runtime and breaks layer shaders):
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.2/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.5.2"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.6/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.5.6"></script>
 ```
 
 Always include `onlymapjs.css` — it carries the MapLibre basemap styles and the no-JS fallback rules (`<om-fallback>` / default banner). For the fallback to work in script-disabled previews it must load without JavaScript: a real `<link rel="stylesheet">` or inlined `<style>` on no-build pages (a bundler-emitted stylesheet is fine in npm projects).
@@ -81,10 +81,21 @@ get-position="[$lon, $lat]"
 get-radius="$population * 0.001"
 get-fill-color="$value > 100 ? [255,0,0] : [0,128,255]"
 get-fill-color="scale($depth, sequential, ['#ffffcc','#800026'], domain=[0,700])"
+get-text="formatDate($time, 'datetime', 'UTC')"
 ```
 
 `$field` works on flat rows, GeoJSON properties, columnar JSON, CSV/TSV columns, and Arrow point columns.
 
+Date formatting is a safe built-in rather than an opt-in to arbitrary JavaScript:
+
+```html
+get-text="formatDate($time)"
+get-text="formatDate($time, 'date')"
+get-text="formatDate($time, 'datetime', 'Asia/Singapore')"
+```
+
+`formatDate(value, style?, timeZone?)` accepts epoch-millisecond numbers/numeric strings or ISO date strings. Numeric values are always milliseconds—multiply Unix seconds by 1000 before formatting. Styles are `date`, `datetime` (default), `time`, and `iso`; the default time zone is `UTC`, while `local` opts into the viewer's zone and IANA names select a specific zone. Invalid values produce an empty string. Restricted expressions still reject `new Date()`, `Intl`, and instance-method calls.
+
 Smart shorthands:
 
 - `color="#1f9e89"` sets a constant `getFillColor` when no explicit `get-fill-color` exists, and always feeds the legend swatch.
@@ -102,6 +113,17 @@ Filtering:
 filter-field="magnitude" filter-range="[4, 10]"
 ```
 
+For an epoch-millisecond filter, format the built-in widget's numeric labels declaratively:
+
+```html
+<om-layer id="quakes" type="GeoJsonLayer" data="./quakes.geojson"
+          filter-field="time" filter-range="[1782889284760, 1785480717910]"></om-layer>
+<om-widget type="filter" layer="quakes" field="time"
+           format="date" date-style="datetime" time-zone="UTC"></om-widget>
+```
+
+`format` is `number` (default) or `date`. With `format="date"`, `date-style` uses the same four styles as `formatDate()` and `time-zone` defaults to `UTC`.
+
 
 
 ### Built-In Layer Types
@@ -151,6 +173,9 @@ External layer classes become manifest types via `OmMap.registerLayer({type, dec
 | Arrow / GeoArrow IPC | `data="./big.arrow"`                                        | Points stay columnar; lines/polygons become GeoJSON features. |
 | Shapefile            | `data="./countries.shp"`                                    | Loads sidecars and joins `.dbf` attributes.                   |
 | KML                  | `data="./tour.kml"`                                         | Placemarks become GeoJSON features.                           |
+| GPX                  | `data="./hike.gpx"` (opt. `#waypoints`/`#tracks`/`#routes`) | Waypoints/tracks/routes → GeoJSON features, each tagged `_gpxKind`; a URL fragment selects one part (no fragment = all). |
+| FlatGeobuf           | `data="./cities.fgb"`                                       | Cloud-native binary vector — whole-file decode to GeoJSON features (bbox-streaming is a later phase). |
+| GeoParquet           | `data="./data.parquet"` (or `.geoparquet`)                 | Cloud-native columnar vector — all-Point files stay columnar, lines/polygons become GeoJSON features; needs the `geo` metadata (WKB geometry) and CRS84/EPSG:4326 (a projected CRS errors — reproject first). |
 | CityJSON             | `data="./tile.city.json"`                                   | 3D city models → extruded footprints, or `?om-surfaces=1` for real per-face roof geometry; see below. |
 | CityJSONSeq          | `data="./tile.city.jsonl"`                                  | Same, streamed line by line as it downloads.                  |
 | WebSocket            | `data="wss://feed" key="id" flush="250ms" source="decoder"` | Upsert-by-key stream.                                         |
@@ -266,10 +291,11 @@ Built-ins:
 - `legend` — symbology-aware by default: it parses each layer's `get-fill-color`. A `sequential`/`diverging` `scale()` renders as a gradient ramp with the domain ends labeled; a `threshold` scale as discrete class ranges (`< b1`, `b1 – b2`, `≥ bN`); an equality ternary chain (`$f == 'a' ? '#c1' : $f == 'b' ? '#c2' : '#fallback'`) as a category palette with an "other" row. Any other expression falls back to the single `color` swatch — so writing the canonical shapes buys a self-describing legend for free.
 - `layer-switcher`
 - `zoom-controls`
-- `scale-bar`
+- `scale-bar` — `units="metric|imperial|nautical"` (default metric) picks the length system; snaps to a nice round distance.
 - `attribution`
 - `filter`
 - `draw`
+- `measure` — geodesic ruler: `modes="distance area"` (space-separated; default both), `units="metric|imperial|nautical"`. Click the map to place points; live per-segment + total labels render on the map, and a totals panel + a `units` toggle sit in the widget. Distance is haversine on the WGS84 mean sphere (≤0.56% vs. the true geodesic); area is the spherical-excess integral. Nautical shows nmi for length and falls back to metric for area. Reuses the draw capture stack (measure and draw are mutually exclusive); the geometry is ephemeral (never saved, never an undo step). Consume the reading programmatically via the `om-measure` event on `<om-map>` (`detail = {mode, units, totalMeters, segments, areaMeters2, perimeterMeters, poleWarning}`).
 - `vega-lite`
 - `player`
 - `basemap-switcher` — radio list of presets; `options="positron dark-matter osm"` (default: every keyless registered preset)
@@ -295,11 +321,30 @@ Examples:
 ```html
 <om-widget type="legend" position="bottom-right" title="Layers" interactive></om-widget>
 <om-widget type="filter" layer="quakes" field="magnitude" position="top-left"></om-widget>
+<om-widget type="filter" layer="quakes" field="time" format="date"
+           date-style="datetime" time-zone="UTC" position="bottom-center"></om-widget>
 <om-widget type="draw" target="sketch" modes="point line polygon" save="both"></om-widget>
 <om-widget type="basemap-switcher" options="positron dark-matter liberty osm" position="top-right"></om-widget>
 ```
 
-Custom widget:
+### Custom widgets & event emission
+
+**Reach for a built-in first.** A plain value/time slider is a built-in:
+`<om-widget type="filter" layer="quakes" field="time" format="date">` — it
+renders readable date labels AND wires the `filter-layer` action for you (pair
+it with the layer's `filter-field`). Author a custom widget ONLY for bespoke UI
+or logic the built-ins don't cover — most "it looked right but didn't work"
+widgets should have been a `type="filter"`/`legend`/`vega-lite` built-in.
+
+A custom widget is an `<om-widget>` with **no `type`** plus inline HTML and a
+`<script type="om/widget">` block. The script is full JS, evaluated ONCE at
+connect with `this` bound to the `<om-widget>` element: set `this.watch` (a
+list of re-render triggers) and `this.render = (ctx) => {…}`. `vegaEmbed`/`d3`
+are available. Content renders in shadow DOM — reach it with `this.$(selector)`
+and `this.root`.
+
+**Read map state** through `ctx` (the `render` argument), re-rendering when a
+watched token fires:
 
 ```html
 <om-widget position="top-left">
@@ -314,20 +359,60 @@ Custom widget:
 </om-widget>
 ```
 
-Widget context:
-
-- `ctx.layers`
-- `ctx.data(id)`
-- `ctx.dataInViewport(id)`
-- `ctx.stats(id, field, { scope: "viewport" })`
-- `ctx.selection`
-- `ctx.viewport`
-- `ctx.history` — `{ canUndo, canRedo }`; re-render on changes via the `history` watch token
-- `ctx.emit(action, payload)`
-
-Watch tokens: `data:<layerId>`, `viewport`, `selection`, `layers` (fires on layer add/remove, visibility, and filter changes), `basemap`, `lighting`, `terrain`, `history`, `widgets` (fires on a `widgets-hidden` hide-all toggle).
-
-Use `this.$()` and `this.root`; widgets render in shadow DOM.
+- `ctx.layers`, `ctx.data(id)`, `ctx.dataInViewport(id)`,
+  `ctx.stats(id, field, { scope: "viewport" })`, `ctx.selection`,
+  `ctx.viewport`, `ctx.history` (`{ canUndo, canRedo }`).
+- Watch tokens: `data:<layerId>`, `viewport`, `selection`, `layers` (add/remove,
+  visibility, filter changes), `basemap`, `lighting`, `terrain`, `history`,
+  `widgets` (`widgets-hidden` hide-all toggle).
+
+**Drive the map — the emission contract.** This is the part authors get wrong.
+A widget NEVER mutates the map directly and NEVER dispatches its own
+`CustomEvent` hoping the map listens. It **emits a registered action**, exactly
+two ways:
+
+1. **Declarative `data-emit`** (no script): `data-emit="<action>"` + `data-*`
+   payload keys on an element. Fires on **click** (non-form elements) or
+   **change** (form controls — `input`/`select`/`textarea`, whose `.value` is
+   auto-merged into the payload). `data-*` keys camelCase (`data-feature-id` →
+   `featureId`) and arrive as **strings** — fine for `toggle-layer`/`fly-to`,
+   but a numeric/array payload (a slider's `range: [min, max]`) needs `ctx.emit`.
+   ```html
+   <button data-emit="toggle-layer" data-layer="quakes">Toggle quakes</button>
+   ```
+
+2. **Programmatic `ctx.emit(action, payload)`** — for typed payloads. Wire it
+   INSIDE `render` so `ctx` is in scope, assigning `.oninput`/`.onclick`
+   (idempotent across re-renders; prefer over `addEventListener`, which stacks a
+   fresh listener every render):
+   ```html
+   <om-widget position="bottom-center">
+     <input id="day" type="range" min="1" max="14" step="1" value="1">
+     <script type="om/widget">
+       this.render = (ctx) => {
+         this.$("#day").oninput = (e) => {
+           const d = Number(e.target.value);
+           ctx.emit("filter-layer", { layer: "quakes", field: "day", range: [d, d] });
+         };
+       };
+     </script>
+   </om-widget>
+   ```
+
+**NEVER inline handlers** (`onclick="…"`, `oninput="ctx.emit(…)"`): `ctx` is not
+a global, they execute in page scope, and CSP blocks them — the widget looks
+right and silently emits nothing. This is the #1 custom-widget failure, and
+validation errors on it.
+
+**Actions a widget can emit** (payload keys): `filter-layer`
+`{layer, field?, range:[min,max]}` (value/time sliders), `toggle-layer`
+`{layer, visible?}`, `fly-to` `{center:[lng,lat], zoom?, pitch?, bearing?,
+duration?}`, `zoom-to-feature` `{layer, featureId, duration?}`, `set-basemap`
+`{basemap}`, `set-lighting`/`set-terrain`, `highlight-feature`
+`{layer, featureId}`, `show-overlay`/`hide-overlay` `{target}`,
+`story-play`/`story-pause`/`story-seek` `{story, t?}`, `undo`/`redo`,
+`zoom-in`/`zoom-out`, `set-widgets-visible` `{visible}`. Register your own with
+`OmMap.registerAction(name, (payload, mapEl) => …)`.
 
 ### `<om-overlay>`
 
@@ -493,4 +578,3 @@ For 3D Tiles LOD/refinement experiments, use:
             maximum-memory-usage="256"
             view-distance-scale="0.85"></om-layer>
 ```
-

package/skills/onlymapjs/references/testing.md

@@ -10,11 +10,20 @@ Use `OmMap.validate(htmlString)` before finalizing agent-written maps.
 import { OmMap } from "@nika-js/onlymap";
 
 const result = OmMap.validate(html);
-if (!result.valid) {
-  console.log(result.errors);
+// `valid` reflects ERRORS ONLY. Warnings (e.g. `Unknown attribute "get-radius"
+// on GeoJsonLayer — likely a typo`) mean a prop is being silently dropped and
+// the layer renders wrong-but-"valid", so act on BOTH lists — never stop at
+// `valid: true`.
+for (const entry of [...result.errors, ...result.warnings]) {
+  console.log(entry.severity, entry.attribute, entry.message, "→", entry.fix);
 }
 ```
 
+An `Unknown attribute` warning is usually a wrong-for-this-layer prop — check
+`onlymapjs.html-data.json` for the layer's real attributes (e.g. `GeoJsonLayer`
+points use `get-point-radius`/`point-radius-units`, not `ScatterplotLayer`'s
+`get-radius`/`radius-units`).
+
 Errors and warnings have:
 
 ```ts