@nika-js/onlymap 0.5.3 → 0.5.7

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.3/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.5.3"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.7/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.5.7"></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,13 +113,24 @@ 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
 
 Use the `type` value exactly:
 
-`A5Layer`, `ArcLayer`, `BitmapLayer`, `COGLayer`, `ColumnLayer`, `ContourLayer`, `GeoJsonLayer`, `GeohashLayer`, `GreatCircleLayer`, `GridCellLayer`, `GridLayer`, `H3ClusterLayer`, `H3HexagonLayer`, `HeatmapLayer`, `HexagonLayer`, `IconLayer`, `LineLayer`, `MVTLayer`, `PathLayer`, `PointCloudLayer`, `PolygonLayer`, `PopupLayer`, `QuadkeyLayer`, `S2Layer`, `ScatterplotLayer`, `ScenegraphLayer`, `ScreenGridLayer`, `SimpleMeshLayer`, `SolidPolygonLayer`, `TerrainLayer`, `TextLayer`, `Tile3DLayer`, `TileLayer`, `TripsLayer`.
+`A5Layer`, `ArcLayer`, `BitmapLayer`, `COGLayer`, `ColumnLayer`, `ContourLayer`, `GeoJsonLayer`, `GeohashLayer`, `GreatCircleLayer`, `GridCellLayer`, `GridLayer`, `H3ClusterLayer`, `H3HexagonLayer`, `HeatmapLayer`, `HexagonLayer`, `IconLayer`, `ImageOverlay`, `LineLayer`, `MVTLayer`, `PathLayer`, `PointCloudLayer`, `PolygonLayer`, `PopupLayer`, `QuadkeyLayer`, `S2Layer`, `ScatterplotLayer`, `ScenegraphLayer`, `ScreenGridLayer`, `SimpleMeshLayer`, `SolidPolygonLayer`, `TerrainLayer`, `TextLayer`, `Tile3DLayer`, `TileLayer`, `TripsLayer`.
 
 Common choices:
 
@@ -119,6 +141,7 @@ Common choices:
 - Tiles: `TileLayer`, `MVTLayer`, `Tile3DLayer`.
 - 3D models: `ScenegraphLayer`, `SimpleMeshLayer`, `PointCloudLayer`, `Tile3DLayer`.
 - GeoTIFF/COG rasters: `COGLayer`.
+- Geotagged drone JPEGs: `ImageOverlay`.
 
 
 
@@ -137,6 +160,23 @@ Common choices:
 - Plain 8-bit RGB COGs (satellite truecolor) need no styling attributes at all.
 - Restretch/recolor (min/max/colormap edits) are GPU uniform updates — tiles are not refetched. The legend widget renders the colormap ramp automatically when `colormap` + `min`/`max` are authored.
 
+### ImageOverlay (drone JPEG)
+
+```html
+<om-layer id="photo" type="ImageOverlay"
+          src="./DJI_0123.jpg" georeference="exif"
+          opacity="0.8"></om-layer>
+```
+
+- `src` (required) — a JPEG with GPS/relative-altitude/camera/focal-length EXIF and DJI gimbal XMP.
+- `georeference="exif"` — fetches through `OmMap.configureData`, computes a flat-ground WGS84 footprint, and bakes yaw/roll into the pixels. `map.ready` waits for it.
+- Verified camera paths include DJI FC300S and M30T, including M30T JPEGs carrying a 180° gimbal-roll correction.
+- Unknown camera: supply `sensor-width-mm` + `sensor-height-mm` together. If EXIF lacks focal length, also supply `focal-length-mm`. Values are physical millimetres and must be positive.
+- Persisted/preprocessed form: omit `georeference` and set `bounds="[west,south,east,north]"`; `src` may be the processed PNG. Optional JSON `metadata` passes through. Explicit bounds perform no EXIF fetch.
+- `depth-test` defaults false. `opacity`, `visible`, and `pickable` behave like other layers.
+- The public `await OmMap.resolveImageOverlay(fileOrUrl, options?)` returns `{image, bounds, metadata}` for upload/persistence.
+- Visualization-grade only: no terrain, lens-distortion, calibration, or perspective-correct four-corner orthorectification. Use `COGLayer` for large orthomosaics.
+
 External layer classes become manifest types via `OmMap.registerLayer({type, deckClass, props})`. Build them on `@nika-js/onlymap/deck` (the bundled `CompositeLayer`/`TileLayer`/… re-exports — a separately-installed deck.gl is a different class hierarchy and breaks in the renderer); function-valued props ride the subclass's `static defaultProps`; register at module top level before the manifest mounts. Full recipe: docs/custom-layers.md.
 
 ### Data Sources
@@ -151,6 +191,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.                                         |
@@ -296,11 +339,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">
@@ -315,20 +377,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>`
 
@@ -494,4 +596,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