@nika-js/onlymap 0.1.0

package/skills/onlymapjs/references/syntax.md

@@ -0,0 +1,342 @@
+# OnlyMapJS Syntax Reference
+
+This reference is public-safe and self-contained. Use it when authoring or reviewing OnlyMapJS manifests.
+
+## Import Patterns
+
+Vite/npm project:
+
+```html
+<script type="module">
+  import "@nika-js/onlymap";
+  import "onlymapjs/onlymapjs.css";
+</script>
+```
+
+Static CDN page:
+
+```html
+<script type="module" src="https://esm.sh/@nika-js/onlymap@0.1.0"></script>
+```
+
+If using MapLibre basemaps from a built package, include the CSS import or stylesheet. Standalone `basemap="none"` maps do not need the CSS.
+
+## Elements
+
+### `<om-map>`
+
+Root element. Children are layers, widgets, overlays, behaviors, and stories.
+
+Common attributes:
+
+- `center="[lng, lat]"`
+- `zoom="11"`
+- `pitch="55"`
+- `bearing="20"`
+- `basemap="maplibre"` or `basemap="none"` or a MapLibre style URL
+- `validate` to show live validation errors during authoring
+- `headless width="800" height="600"` for test harness use
+
+Example:
+
+```html
+<om-map center="[-122.42, 37.77]" zoom="11" basemap="maplibre" validate>
+  ...
+</om-map>
+```
+
+### `<om-layer>`
+
+Declares a deck.gl layer. Required: `id`, `type`.
+
+Core attributes:
+
+- `id="quakes"` — stable identity for behaviors, widgets, tests, stories.
+- `type="ScatterplotLayer"` — any bundled layer type.
+- `data="./points.json"` — URL, stream, draw store, or omit for inline JSON.
+- `label="Earthquakes"` and `color="#b30000"` — legend metadata.
+- `pickable` — enable click/hover behaviors.
+- `visible="false"` or `opacity="0"` — initial visibility/opacity.
+
+Accessors:
+
+```html
+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])"
+```
+
+`$field` works on flat rows, GeoJSON properties, columnar JSON, CSV/TSV columns, and Arrow point columns.
+
+Smart shorthands:
+
+- `color="#1f9e89"` sets a constant `getFillColor` when no explicit `get-fill-color` exists, and always feeds the legend swatch.
+- `radius="6"` sets a constant `getRadius` when no explicit `get-radius` exists.
+
+Transitions:
+
+```html
+transition="get-fill-color 800ms, get-radius 400ms"
+```
+
+Filtering:
+
+```html
+filter-field="magnitude" filter-range="[4, 10]"
+```
+
+### Built-In Layer Types
+
+Use the `type` value exactly:
+
+`A5Layer`, `ArcLayer`, `BitmapLayer`, `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`.
+
+Common choices:
+
+- Points: `ScatterplotLayer`, `IconLayer`, `TextLayer`, `PopupLayer`.
+- Lines/routes: `PathLayer`, `LineLayer`, `ArcLayer`, `TripsLayer`.
+- Polygons/choropleths: `GeoJsonLayer`, `PolygonLayer`.
+- Aggregation: `HeatmapLayer`, `HexagonLayer`, `GridLayer`, `ScreenGridLayer`.
+- Tiles: `TileLayer`, `MVTLayer`, `Tile3DLayer`.
+- 3D models: `ScenegraphLayer`, `SimpleMeshLayer`, `PointCloudLayer`, `Tile3DLayer`.
+
+### Data Sources
+
+| Source | Manifest | Notes |
+|---|---|---|
+| JSON / GeoJSON URL | `data="./points.json"` | Arrays or FeatureCollections. |
+| Inline JSON | child `<script type="application/json">` | Good for tests/demos. |
+| Columnar JSON | `{"columns": {"lon": [...], "lat": [...]}}` | Fast point path. |
+| CSV / TSV | `data="./quakes.csv"` | Parsed to typed columns. |
+| 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. |
+| WebSocket | `data="wss://feed" key="id" flush="250ms" source="decoder"` | Upsert-by-key stream. |
+| Polling | `data="/api/fleet.json" refresh="5s"` | Snapshot replace. |
+| Draw store | `data="draw:sketch"` | Written by draw widget. |
+
+Authenticated fetches:
+
+```js
+import { OmMap } from "@nika-js/onlymap";
+OmMap.configureData({ headers: { Authorization: `Bearer ${token}` } });
+```
+
+Custom format:
+
+```js
+OmMap.registerFormat({
+  match: (url, contentType) => url.endsWith(".custom"),
+  parse: async (res, url) => /* return rows or columnar data */
+});
+```
+
+Custom stream decoder:
+
+```js
+OmMap.registerSource("fleet", {
+  onOpen: (send) => send(JSON.stringify({ subscribe: "vehicles" })),
+  decode: (msg) => msg.type === "position" ? { id: msg.id, lon: msg.lon, lat: msg.lat } : null
+});
+```
+
+### Accessor Blocks
+
+Restricted expression block:
+
+```html
+<script type="om/accessors">
+  export const getPosition = d => [$lon, $lat];
+  export const getRadius = d => Math.max(2, $magnitude * 3);
+</script>
+```
+
+Full JavaScript block:
+
+```html
+<om-layer id="routes" type="PathLayer" js>
+  <script type="om/accessors">
+    const speeds = { slow: [80, 120, 255], fast: [255, 80, 80] };
+    export const getColor = d => speeds[d.speedClass] ?? [180, 180, 180];
+  </script>
+</om-layer>
+```
+
+Do not use full-JS blocks on columnar/Arrow layers.
+
+### `<om-widget>`
+
+Built-ins:
+
+- `legend`
+- `layer-switcher`
+- `zoom-controls`
+- `scale-bar`
+- `attribution`
+- `filter`
+- `draw`
+- `vega-lite`
+- `player`
+
+Positions: `top-left`, `top-right`, `bottom-left`, `bottom-right`.
+
+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="draw" target="sketch" modes="point line polygon" save="both"></om-widget>
+```
+
+Custom widget:
+
+```html
+<om-widget position="top-left">
+  <div id="out"></div>
+  <script type="om/widget">
+    this.watch = ["data:quakes", "viewport", "selection"];
+    this.render = (ctx) => {
+      const s = ctx.stats("quakes", "magnitude", { scope: "viewport" });
+      this.$("#out").textContent = `${s.count} quakes`;
+    };
+  </script>
+</om-widget>
+```
+
+Widget context:
+
+- `ctx.layers`
+- `ctx.data(id)`
+- `ctx.dataInViewport(id)`
+- `ctx.stats(id, field, { scope: "viewport" })`
+- `ctx.selection`
+- `ctx.viewport`
+- `ctx.emit(action, payload)`
+
+Use `this.$()` and `this.root`; widgets render in shadow DOM.
+
+### `<om-overlay>`
+
+Rich sparse HTML anchored to the map.
+
+Anchors:
+
+- `anchor="[lng, lat]"`
+- `anchor-from="selection"`
+- `anchor-layer="regions" anchor-feature-id="mission"`
+
+Templates:
+
+- `{{field}}` HTML-escaped interpolation.
+- `{{{field}}}` raw HTML; avoid unless trusted.
+
+Example:
+
+```html
+<om-overlay id="detail" anchor-from="selection" visible="false">
+  <div><b>{{place}}</b> M {{magnitude}}</div>
+</om-overlay>
+<om-behavior on="click" layer="quakes" action="show-overlay" target="detail"></om-behavior>
+```
+
+### `<om-behavior>`
+
+Declarative event to action binding.
+
+Events: `click`, `hover`, `drag`, `load`, `data-loaded`.
+
+Common built-in actions:
+
+- `show-overlay`, `hide-overlay`
+- `show-tooltip`, `hide-tooltip`
+- `toggle-layer`
+- `highlight-feature`
+- `zoom-to-feature`
+- `filter-layer`
+- `zoom-in`, `zoom-out`
+- `fly-to`
+- story actions: `story-play`, `story-pause`, `story-seek`
+- effect actions: `fade`, `pulse`, `trace`, `populate`
+- draw actions: `draw-mode`, `draw-commit`, `draw-cancel`, `draw-delete`, `draw-clear`, `draw-config`, `draw-save`
+
+Payload attributes are kebab-case and become camelCase payload keys.
+
+Example:
+
+```html
+<om-behavior on="click" layer="regions" action="zoom-to-feature" duration="1200ms"></om-behavior>
+```
+
+### Stories
+
+Use `<om-story>` with `<om-step>` children. Stories are siblings of layers/overlays, not containers.
+
+```html
+<om-story id="tour" interrupt="pause">
+  <om-step duration="2s" action="fly-to" center="[-122.44, 37.78]" zoom="12" curve></om-step>
+  <om-step duration="1s" action="show-overlay" target="intro" parallel></om-step>
+  <om-step duration="1500ms" fade layer="regions"></om-step>
+  <om-step duration="2s" trace layer="regions" feature-id="mission"></om-step>
+</om-story>
+<om-widget type="player" story="tour" position="bottom-left"></om-widget>
+```
+
+Story timing attributes:
+
+- `duration`
+- `delay`
+- `parallel`
+
+Use declarative payloads for scrub-safe state: `visible="true"` when toggling, explicit `filter-range`, explicit camera target.
+
+### Manual Drawing
+
+Use a normal GeoJSON layer bound to a draw store plus a draw widget:
+
+```html
+<om-layer id="sketch" type="GeoJsonLayer" data="draw:sketch"
+            get-fill-color="[80, 140, 255, 90]"
+            get-line-color="[40, 90, 220]"
+            point-radius-min-pixels="6"
+            line-width-min-pixels="3"
+            stroked filled pickable></om-layer>
+<om-widget type="draw" target="sketch" position="top-left"
+             modes="point line polygon" save="both"
+             autosave="my-sketch"></om-widget>
+```
+
+The draw widget supports points, lines, polygons, delete-last, clear, save, and autosave. Lines/polygons close with double-click or Enter; Escape cancels the in-progress shape.
+
+### 3D
+
+ScenegraphLayer places GLB/glTF models at coordinates:
+
+```html
+<om-layer id="vehicles" type="ScenegraphLayer"
+            scenegraph="./truck.glb"
+            data="./vehicles.json"
+            get-position="[$lon, $lat]"
+            get-orientation="[0, $heading, 90]"
+            get-scale="[1, 1, 1]"
+            lighting="pbr" pickable></om-layer>
+```
+
+Roll `90` stands Y-up glTF assets upright. Use `Tile3DLayer` for large 3D Tiles datasets.
+
+3D Tiles roots use `tileset`, not `data`, because OnlyMapJS reserves `data` for parsed datasets:
+
+```html
+<om-layer id="city" type="Tile3DLayer"
+            tileset="https://example.com/tileset.json"></om-layer>
+```
+
+For 3D Tiles LOD/refinement experiments, use:
+
+```html
+<om-layer id="city" type="Tile3DLayer"
+            tileset="https://example.com/tileset.json"
+            maximum-screen-space-error="2"
+            maximum-memory-usage="256"
+            view-distance-scale="0.85"></om-layer>
+```

package/skills/onlymapjs/references/testing.md

@@ -0,0 +1,126 @@
+# OnlyMapJS Validation And Testing
+
+Use this reference when a user asks to debug, validate, review, or test an OnlyMapJS page.
+
+## Static Validation
+
+Use `OmMap.validate(htmlString)` before finalizing agent-written maps.
+
+```ts
+import { OmMap } from "@nika-js/onlymap";
+
+const result = OmMap.validate(html);
+if (!result.valid) {
+  console.log(result.errors);
+}
+```
+
+Errors and warnings have:
+
+```ts
+{
+  severity: "error" | "warning",
+  element: "om-layer#quakes",
+  attribute: "get-position",
+  message: "...",
+  fix: "..."
+}
+```
+
+Treat `fix` as the direct instruction to apply.
+
+Common validation failures:
+
+- Self-closing custom elements cause bad DOM nesting. Use explicit closing tags.
+- Missing layer `id`.
+- Unknown layer `type`.
+- Missing required accessor such as `get-position`.
+- `scale()` missing explicit `domain=`.
+- Unknown attributes from camelCase or typos.
+- `js` full-JS accessor block on columnar/Arrow data.
+- `filter-field` without `filter-range`.
+- Inline handlers in widget/overlay content.
+- Story steps containing child elements.
+
+## Snapshot IR
+
+Use `OmMap.snapshotIR(html)` to inspect what a manifest means without WebGL or network.
+
+```ts
+expect(OmMap.snapshotIR(html)).toMatchSnapshot();
+```
+
+The snapshot contains resolved layer descriptors. Accessors appear as behavioral fingerprints, so expression changes show up in diffs without serializing functions.
+
+## Headless Behavior Harness
+
+Use `mountForTest` for most interaction tests.
+
+```ts
+// @vitest-environment happy-dom
+import "@nika-js/onlymap";
+import { mountForTest } from "@nika-js/onlymap";
+
+const h = await mountForTest(`
+  <om-map center="[-122.42, 37.77]" zoom="11">
+    <om-layer id="points" type="ScatterplotLayer" get-position="[$lon, $lat]" pickable>
+      <script type="application/json">
+        [{ "id": "p1", "name": "A", "lon": -122.42, "lat": 37.77 }]
+      </script>
+    </om-layer>
+    <om-overlay id="detail" anchor-from="selection" visible="false">
+      <div>{{name}}</div>
+    </om-overlay>
+    <om-behavior on="click" layer="points" action="show-overlay" target="detail"></om-behavior>
+  </om-map>
+`);
+
+await h.pick({ layer: "points", featureId: "p1" });
+expect(h.map.querySelector("#detail").shadowRoot.textContent).toContain("A");
+```
+
+Harness operations:
+
+- `h.pick({ layer, featureId | index, type })`
+- `h.clearSelection()`
+- `h.emit(action, payload)`
+- `h.setView({ center, zoom, pitch, bearing })`
+- `h.layers()`
+- `h.story(id).advance(ms)`
+- `h.story(id).seek(ms)`
+- `h.unmount()`
+
+Use `vi.stubGlobal("fetch", ...)` for URL data and `vi.stubGlobal("WebSocket", ...)` for streams.
+
+## Browser/E2E Testing
+
+Use Playwright only for pixels, real GPU picking, basemap composition, or asset rendering.
+
+Wait for readiness:
+
+```ts
+await page.evaluate(() => document.querySelector("om-map").ready);
+```
+
+Project data coordinates to click pixels:
+
+```ts
+const p = await page.evaluate(() => document.querySelector("om-map").projectInternal([-122.42, 37.77]));
+const box = await page.locator("om-map").boundingBox();
+await page.mouse.click(box.x + p[0], box.y + p[1]);
+```
+
+Do not use sleeps. Wait for `ready`, DOM state, screenshots, or `expect.poll`.
+
+## Debugging Checklist
+
+1. Is every OnlyMapJS custom element explicitly closed?
+2. Does every layer have `id` and a valid `type`?
+3. Are attributes kebab-case?
+4. Is the data shape compatible with the accessor? Prefer `$field`.
+5. Does every `scale()` include `domain=`?
+6. Are behaviors pointing at existing `layer`/`target` ids?
+7. Is `pickable` present where click/hover behaviors are expected?
+8. Are credentials configured through `OmMap.configureData`, not markup?
+9. Is the relevant CSS imported when using MapLibre basemaps?
+10. Is a story step setting state rather than toggling ambiguous state?