@nika-js/onlymap 0.1.0

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@nika-js/onlymap",
+  "version": "0.1.0",
+  "description": "Interactive WebGL maps from declarative HTML — a custom-element manifest drives deck.gl: rendering, data loading, live updates, picking, widgets, and validation. No build step.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "NikaGeospatial",
+  "homepage": "https://github.com/NikaGeospatial/onlymapjs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NikaGeospatial/onlymapjs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NikaGeospatial/onlymapjs/issues"
+  },
+  "keywords": [
+    "deck.gl",
+    "maps",
+    "webgl",
+    "geospatial",
+    "gis",
+    "declarative",
+    "custom-elements",
+    "web-components",
+    "maplibre",
+    "dataviz",
+    "visualization",
+    "llm",
+    "agent"
+  ],
+  "type": "module",
+  "main": "./dist/onlymapjs.js",
+  "module": "./dist/onlymapjs.js",
+  "types": "./dist/index.d.ts",
+  "style": "./dist/onlymapjs.css",
+  "bin": {
+    "onlymapjs": "bin/onlymapjs.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/onlymapjs.js",
+      "require": "./dist/onlymapjs.umd.cjs",
+      "default": "./dist/onlymapjs.js"
+    },
+    "./onlymapjs.css": "./dist/onlymapjs.css",
+    "./onlymapjs.html-data.json": "./onlymapjs.html-data.json",
+    "./onlymap.code-snippets": "./.vscode/onlymap.code-snippets"
+  },
+  "files": [
+    ".vscode/onlymap.code-snippets",
+    "bin/onlymapjs.mjs",
+    "dist",
+    "README.md",
+    "LICENSE.md",
+    "llms.txt",
+    "onlymapjs.html-data.json",
+    "skills/onlymapjs"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run typecheck && vite build && npm run build:types",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.e2e.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "try": "vite-node dev/expr-repl.mjs",
+    "test:e2e": "playwright test",
+    "gen:html-data": "vite-node dev/generate-html-data.ts",
+    "gen:public": "npm run gen:html-data && vite-node dev/build-public.ts",
+    "test:public": "npm run gen:public -- --dry-run --strict"
+  },
+  "dependencies": {
+    "@deck.gl/aggregation-layers": "^9.3.5",
+    "@deck.gl/core": "^9.3.5",
+    "@deck.gl/extensions": "^9.3.5",
+    "@deck.gl/geo-layers": "^9.3.5",
+    "@deck.gl/layers": "^9.3.5",
+    "@deck.gl/mapbox": "^9.3.5",
+    "@deck.gl/mesh-layers": "^9.3.5",
+    "@loaders.gl/csv": "^4.4.3",
+    "@loaders.gl/kml": "^4.4.3",
+    "@loaders.gl/shapefile": "^4.4.3",
+    "acorn": "^8.17.0",
+    "apache-arrow": "^21.1.0",
+    "d3-array": "^3.2.4",
+    "d3-color": "^3.1.0",
+    "d3-interpolate": "^3.0.1",
+    "d3-scale": "^4.0.2",
+    "fzstd": "^0.1.1",
+    "maplibre-gl": "^5.24.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "@types/d3-array": "^3.2.2",
+    "@types/d3-color": "^3.1.3",
+    "@types/d3-interpolate": "^3.0.4",
+    "@types/d3-scale": "^4.0.9",
+    "@types/estree": "^1.0.9",
+    "@types/ws": "^8.18.1",
+    "happy-dom": "^20.10.6",
+    "playwright": "^1.61.1",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vite-node": "^6.0.0",
+    "vitest": "^4.1.9",
+    "ws": "^8.21.0"
+  }
+}

package/skills/onlymapjs/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: onlymapjs
+description: Build, edit, debug, or review OnlyMapJS declarative HTML maps and dashboards. Use when a user asks for an interactive map, deck.gl-style visualization, geospatial dashboard, live fleet/telemetry map, choropleth, popup/tooltip map, map story/tour, manual drawing/sketch map, 3D map assets, or help with OnlyMapJS syntax, validation, widgets, data formats, testing, or publishing examples.
+---
+
+# OnlyMapJS
+
+Use OnlyMapJS as a declarative HTML map library. Write custom elements such as `<om-map>`, `<om-layer>`, `<om-widget>`, `<om-overlay>`, `<om-behavior>`, `<om-story>`, and `<om-step>`. Do not write raw imperative deck.gl setup unless the user explicitly asks to integrate below the OnlyMapJS layer.
+
+## Core Workflow
+
+1. Start with valid HTML custom elements with explicit closing tags. Never self-close OnlyMapJS elements.
+2. Express deck.gl props as kebab-case attributes. Use `get-*` attributes for data-driven accessors.
+3. Use `$field` expressions for data access. Do not write `d.properties.x`, row-object loops, or column-index access in manifests.
+4. Add `validate` to `<om-map>` while authoring.
+5. Verify with `OmMap.validate(html)`, then `OmMap.snapshotIR(html)`, and use `mountForTest` for interaction behavior when tests are requested.
+6. Prefer public, package-safe imports:
+
+```html
+<script type="module">
+  import "@nika-js/onlymap";
+  import "onlymapjs/onlymapjs.css";
+</script>
+```
+
+For no-build CDN examples, use a published module URL such as `https://esm.sh/@nika-js/onlymap@0.1.0`.
+
+## Required References
+
+Load the smallest reference needed for the task:
+
+- `references/syntax.md` — element vocabulary, attributes, data formats, accessors, actions, widgets, overlays, drawing, 3D, built-in layer types.
+- `references/patterns.md` — copyable manifest patterns for common map requests.
+- `references/testing.md` — validation, snapshot, headless harness, and browser testing workflow.
+
+## Non-Negotiable Syntax Rules
+
+- Always use explicit closing tags: `<om-layer ...></om-layer>`, not `<om-layer ... />`.
+- Every `<om-layer>` needs a stable `id`.
+- Attribute names are kebab-case: `get-fill-color`, `radius-units`, `line-width-min-pixels`.
+- Accessor values are expressions: `get-position="[$lon, $lat]"`.
+- `scale()` always needs an explicit `domain=`.
+- Inline handlers such as `onclick` are wrong. Use `data-emit`, `<om-behavior>`, or widget scripts.
+- Full JavaScript accessor blocks require the `js` attribute on `<om-layer>`.
+- Do not put secrets in markup. Use `OmMap.configureData({ headers, credentials, fetch })`.
+
+## Authoring Decisions
+
+- UI panel, control, chart, legend, stats, filter, or draw toolbar -> `<om-widget>`.
+- Sparse rich HTML at one geographic location -> `<om-overlay>`.
+- Many labels/badges -> `<om-layer type="PopupLayer">`.
+- Guided tour or narrative sequence -> `<om-story>` with `<om-step>` siblings that reference existing layers/overlays by id.
+- Live entity updates -> `wss://` stream with `key` and optional `source` decoder.
+- REST snapshot that changes over time -> `refresh="5s"`.
+- User sketching -> `data="draw:sketch"` layer plus `<om-widget type="draw" target="sketch">`.
+
+## Output Expectations
+
+When creating a map page, output a complete runnable HTML file unless the user asks for a fragment. Include CSS only as needed for page sizing or custom widgets/overlays. Keep the first screen the usable map, not a landing page.
+
+When modifying an existing page, preserve the user's data URLs, layer ids, and styling unless the request requires changing them.

package/skills/onlymapjs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OnlyMapJS"
+  short_description: "Build declarative HTML maps with OnlyMapJS"
+  default_prompt: "Use $onlymapjs to create a declarative HTML map."

package/skills/onlymapjs/references/patterns.md

@@ -0,0 +1,213 @@
+# OnlyMapJS Patterns
+
+Use these patterns as starting points. Replace data URLs, layer ids, fields, centers, and style values with the user's domain.
+
+## Minimal Point Map
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>OnlyMapJS map</title>
+  <script type="module">
+    import "@nika-js/onlymap";
+    import "onlymapjs/onlymapjs.css";
+  </script>
+  <style>
+    html, body { margin: 0; height: 100%; }
+    om-map { display: block; height: 100vh; }
+  </style>
+</head>
+<body>
+  <om-map center="[-122.42, 37.77]" zoom="11" basemap="maplibre" validate>
+    <om-layer id="points" type="ScatterplotLayer"
+                data="./points.json"
+                label="Points" color="#1f9e89"
+                get-position="[$lon, $lat]"
+                radius="6" radius-units="pixels"
+                pickable></om-layer>
+    <om-widget type="legend" position="bottom-right" title="Layers"></om-widget>
+    <om-widget type="zoom-controls" position="top-right"></om-widget>
+  </om-map>
+</body>
+</html>
+```
+
+## Click Popup
+
+```html
+<om-layer id="quakes" type="ScatterplotLayer"
+            data="./quakes.json"
+            get-position="[$lon, $lat]"
+            get-fill-color="scale($magnitude, sequential, ['#fee8c8','#b30000'], domain=[0,8])"
+            get-radius="$magnitude * 2"
+            radius-units="pixels" pickable></om-layer>
+
+<om-overlay id="quake-detail" anchor-from="selection" anchor-offset="bottom-center" visible="false">
+  <div><b>{{place}}</b><br />M {{magnitude}}</div>
+</om-overlay>
+
+<om-behavior on="click" layer="quakes" action="show-overlay" target="quake-detail"></om-behavior>
+```
+
+## Hover Tooltip
+
+```html
+<template id="point-tooltip">
+  <div><b>{{name}}</b><br />Value: {{value}}</div>
+</template>
+<om-behavior on="hover" layer="points" action="show-tooltip" template="#point-tooltip"></om-behavior>
+```
+
+## Choropleth GeoJSON
+
+```html
+<om-layer id="regions" type="GeoJsonLayer"
+            data="./regions.geojson"
+            label="Regions" color="#3388ff"
+            get-fill-color="scale($rate, sequential, ['#eff3ff','#08519c'], domain=[0,100])"
+            get-line-color="[40, 40, 40]"
+            line-width-min-pixels="1"
+            filled stroked pickable></om-layer>
+```
+
+For GeoJSON, `$rate` reads `feature.properties.rate`.
+
+## Filtered Dashboard
+
+```html
+<om-layer id="quakes" type="ScatterplotLayer"
+            data="./quakes.csv"
+            get-position="[$longitude, $latitude]"
+            get-fill-color="scale($mag, sequential, ['#ffffcc','#800026'], domain=[0,8])"
+            filter-field="mag" filter-range="[0, 8]"
+            radius="5" radius-units="pixels" pickable></om-layer>
+
+<om-widget type="filter" layer="quakes" field="mag" position="top-left"></om-widget>
+
+<om-widget type="vega-lite" layer="quakes" watch="viewport" position="bottom-left" title="Magnitude">
+  <script type="application/json">
+    {
+      "mark": "bar",
+      "encoding": {
+        "x": { "bin": true, "field": "mag", "type": "quantitative" },
+        "y": { "aggregate": "count", "type": "quantitative" }
+      }
+    }
+  </script>
+</om-widget>
+```
+
+## Custom Stats Widget
+
+```html
+<om-widget position="top-left">
+  <div id="stats"></div>
+  <script type="om/widget">
+    this.watch = ["data:quakes", "viewport", "selection"];
+    this.render = (ctx) => {
+      const s = ctx.stats("quakes", "magnitude", { scope: "viewport" });
+      const selected = ctx.selection ? ctx.selection.object.place : "none";
+      this.$("#stats").textContent = `${s.count} in view; max ${s.max ?? "—"}; selected ${selected}`;
+    };
+  </script>
+</om-widget>
+```
+
+## Dense Labels with PopupLayer
+
+```html
+<om-layer id="labels" type="PopupLayer"
+            data="./places.json"
+            layout="badge"
+            min-zoom="10"
+            get-position="[$lon, $lat]"
+            get-text="$name"
+            get-color="$category === 'A' ? [0, 120, 255] : [255, 120, 0]"
+            pickable></om-layer>
+```
+
+Use `PopupLayer` instead of many `<om-overlay>` elements for labels/badges at scale.
+
+## WebSocket Fleet
+
+```html
+<script type="module">
+  import { OmMap } from "@nika-js/onlymap";
+  import "onlymapjs/onlymapjs.css";
+
+  OmMap.registerSource("fleet", {
+    decode: (m) => m.type === "position"
+      ? { id: m.id, lon: m.lon, lat: m.lat, heading: m.heading, speed: m.speed }
+      : null
+  });
+</script>
+
+<om-layer id="vehicles" type="ScatterplotLayer"
+            data="wss://example.com/fleet" source="fleet" key="id" flush="250ms"
+            get-position="[$lon, $lat]"
+            transition="get-position 300ms"
+            radius="5" radius-units="pixels" pickable></om-layer>
+```
+
+## Polled REST Fleet
+
+```html
+<script type="module">
+  import { OmMap } from "@nika-js/onlymap";
+  OmMap.configureData({ headers: { Authorization: `Bearer ${token}` } });
+</script>
+
+<om-layer id="drivers" type="IconLayer"
+            data="/api/fleet.json" refresh="5s"
+            get-position="[$lon, $lat]"
+            get-angle="-$heading"
+            pickable></om-layer>
+```
+
+## Draw/Sketch Map
+
+```html
+<om-layer id="sketch" type="GeoJsonLayer" data="draw:sketch"
+            label="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="onlymapjs-sketch"></om-widget>
+```
+
+## Story/Tour
+
+```html
+<om-overlay id="intro" anchor="[-122.42, 37.77]" visible="false">
+  <div>Welcome</div>
+</om-overlay>
+
+<om-story id="tour" interrupt="pause">
+  <om-step duration="2s" action="fly-to" center="[-122.42, 37.77]" zoom="12" curve></om-step>
+  <om-step duration="1s" action="show-overlay" target="intro" parallel></om-step>
+  <om-step duration="2s" populate layer="points"></om-step>
+</om-story>
+
+<om-widget type="player" story="tour" position="bottom-left"></om-widget>
+```
+
+## 3D Models
+
+```html
+<om-map center="[-122.399, 37.79]" zoom="15.5" pitch="55" bearing="20" basemap="maplibre">
+  <om-layer id="assets" type="ScenegraphLayer"
+              scenegraph="./asset.glb"
+              data="./assets.json"
+              get-position="[$lon, $lat]"
+              get-orientation="[0, $heading, 90]"
+              get-scale="[$width, $height, $depth]"
+              lighting="pbr" pickable></om-layer>
+</om-map>
+```