@nika-js/onlymap 0.2.0 → 0.2.1

package/onlymapjs.html-data.json

@@ -23,10 +23,53 @@
         },
         {
           "name": "basemap",
-          "description": "Basemap renderer.",
+          "description": "Basemap: a registered preset name, \"maplibre\" (demo style), a style URL, or \"none\" (standalone canvas).",
           "values": [
             {
               "name": "maplibre"
+            },
+            {
+              "name": "none"
+            },
+            {
+              "name": "liberty"
+            },
+            {
+              "name": "bright"
+            },
+            {
+              "name": "positron"
+            },
+            {
+              "name": "dark-matter"
+            },
+            {
+              "name": "voyager"
+            },
+            {
+              "name": "osm"
+            },
+            {
+              "name": "maptiler-streets"
+            },
+            {
+              "name": "maptiler-dataviz"
+            },
+            {
+              "name": "maptiler-satellite"
+            }
+          ]
+        },
+        {
+          "name": "basemap-key",
+          "description": "Provider API key for keyed basemap presets (maptiler-*) — publishable origin-restricted key; or call OmMap.configureBasemap once."
+        },
+        {
+          "name": "attribution",
+          "description": "Set \"false\" to opt out of the compact attribution control shown with basemaps.",
+          "values": [
+            {
+              "name": "false"
             }
           ]
         },
@@ -1358,6 +1401,9 @@
             },
             {
               "name": "draw-save"
+            },
+            {
+              "name": "set-basemap"
             }
           ]
         },
@@ -1405,6 +1451,9 @@
             },
             {
               "name": "draw"
+            },
+            {
+              "name": "basemap-switcher"
             }
           ]
         },
@@ -1483,6 +1532,10 @@
           "name": "autosave",
           "description": "Draw widget: localStorage key — mirrors the sketch and restores it on reload."
         },
+        {
+          "name": "options",
+          "description": "Basemap-switcher: space-separated preset names to offer (default: every keyless registered preset)."
+        },
         {
           "name": "title",
           "description": "Widget heading."
@@ -1613,6 +1666,9 @@
             },
             {
               "name": "draw-save"
+            },
+            {
+              "name": "set-basemap"
             }
           ]
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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": {

package/skills/onlymapjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Build, edit, debug, or review OnlyMapJS declarative HTML maps and dashboards, or React maps via the @nika-js/onlymap/react adapter. 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, a React map component, or help with OnlyMapJS syntax, validation, widgets, data formats, testing, or publishing examples.
 ---
 
 # OnlyMapJS
@@ -23,7 +23,17 @@ Use OnlyMapJS as a declarative HTML map library. Write custom elements such as `
 </script>
 ```
 
-For no-build CDN examples, use a published module URL such as `https://esm.sh/@nika-js/onlymap@0.1.0`.
+For no-build CDN examples, use a published module URL such as `https://esm.sh/@nika-js/onlymap@0.2.0`.
+
+## React Projects
+
+In a React codebase, do NOT render `om-*` elements from JSX — React and the library would contend over the same DOM. Use the first-party adapter instead:
+
+```tsx
+import { OmMap, OmLayer, OmWidget, OmOverlay, useOmMap } from "@nika-js/onlymap/react";
+```
+
+The adapter inverts several HTML-manifest rules: props are camelCase deck.gl props, accessors are plain JS functions (`getFillColor={d => ...}` — no `$field` expression language, no `js` opt-in), and interactions are `onClick`/`onHover` handlers plus React state, not `<om-behavior>` or state-mutating actions. Load `references/react.md` before writing React map code.
 
 ## Required References
 
@@ -31,6 +41,7 @@ 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/react.md` — the React adapter: components, the useOmMap hook, HTML-vs-React rule differences, testing.
 - `references/testing.md` — validation, snapshot, headless harness, and browser testing workflow.
 
 ## Non-Negotiable Syntax Rules
@@ -50,6 +61,7 @@ Load the smallest reference needed for the task:
 - 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.
+- Basemap choice or user-switchable basemaps -> `basemap` presets (`positron`, `liberty`, `dark-matter`, `osm`, ...) + `<om-widget type="basemap-switcher">`; MapTiler custom styles via a style URL or `basemap-key`.
 - 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">`.

package/skills/onlymapjs/references/react.md

@@ -0,0 +1,68 @@
+# React adapter — `@nika-js/onlymap/react`
+
+Real components over the same engine as the HTML manifest. React never renders `om-*` elements — components feed a typed programmatic front-end, so there is no DOM contention with the library's reconciler. React ≥ 18 (`npm install @nika-js/onlymap react react-dom`).
+
+## Rules that INVERT the HTML-manifest rules
+
+- Props are **camelCase deck.gl props** (`getFillColor`, `radiusMinPixels`), not kebab-case attributes.
+- Accessors are **plain JS functions**: `getFillColor={d => d.mag > 6 ? [214,40,40] : [252,191,73]}`. Never use `$field` expressions or `scale()` strings here; never add a `js` attribute (there is none).
+- Interactions are **event handlers + state**, not `<om-behavior>`. Toggle a layer by rendering `visible={false}`; filter by changing `filterRange`. The state-mutating actions (`toggle-layer`, `show-overlay`, `fade`, story/draw actions) are not dispatched on this path — a console warning points back to props. Camera actions (`fly-to`, `zoom-to-feature`, `zoom-in`/`-out`), `pulse`, `populate`, and custom `OmMap.registerAction` handlers work via `emit`.
+- Keep inline `data` references **stable across renders** (`useMemo`/`useState`) — data reactivity diffs by reference. deck.gl ignores accessor function identity; pass `updateTriggers={{ getFillColor: theme }}` when an accessor's *output* changes.
+- Stories and the draw widget are HTML-manifest-only for now.
+
+## Complete example
+
+```tsx
+import { useState } from "react";
+import { OmMap, OmLayer, OmWidget, OmOverlay, useOmMap } from "@nika-js/onlymap/react";
+
+function QuakeMap() {
+  const [visible, setVisible] = useState(true);
+  return (
+    <OmMap center={[-119, 36]} zoom={5} basemap="maplibre" style={{ height: "100vh" }}>
+      <OmLayer id="quakes" type="ScatterplotLayer" data="/quakes.csv" label="Earthquakes"
+               visible={visible} pickable
+               getPosition={(d) => [d.longitude, d.latitude]}
+               getFillColor={(d) => (d.mag >= 6 ? [214, 40, 40] : [252, 191, 73])}
+               radiusMinPixels={3}
+               onClick={(sel) => console.log(sel.object)} />
+      <OmWidget position="top-left"><StatsPanel onToggle={() => setVisible(!visible)} /></OmWidget>
+      <OmOverlay anchorFrom="selection" layer="quakes">
+        {(sel) => sel && <div className="card">M{sel.object.mag} — {sel.object.place}</div>}
+      </OmOverlay>
+    </OmMap>
+  );
+}
+
+function StatsPanel({ onToggle }) {
+  const ctx = useOmMap(["viewport", "data:quakes"]); // watch tokens re-render the component
+  return (
+    <div className="panel">
+      {ctx.stats("quakes", "mag").count} quakes at z{ctx.viewport.zoom.toFixed(1)}
+      <button onClick={onToggle}>Toggle</button>
+      <button onClick={() => ctx.emit("fly-to", { center: [140, 38], zoom: 4, duration: 1200 })}>Japan</button>
+    </div>
+  );
+}
+```
+
+## Component surface
+
+- **`<OmMap>`** — `center`/`zoom`/`pitch`/`bearing` (initial; later changes move the camera, unchanged props never fight user panning), `basemap`, `headless`, `onReady`, `onViewStateChange`, `onRuntimeError`. Give it a size via `style`/`className`. `ref` exposes the imperative `MapController` handle: `flyTo`, `setView`, `emit`, `getLayers`, `getSelection`, `injectPick`, `ready` (promise), `project`.
+- **`<OmLayer>`** — `id` + `type` (any registered deck.gl layer type) + deck props. `data`: stable inline reference or URL string (full Data Layer: CSV/Arrow/Shapefile/KML formats, `ws(s)://` streams via `source`/`streamKey`/`flush`, `refresh` polling). `label`/`color` feed `ctx.layers`; `filterField`/`filterRange` = GPU filter; `onClick`/`onHover` receive the flattened picked object (`onHover(null)` = pointer left).
+- **`<OmWidget>`** — positioning shell: `position="top-left|top-right|bottom-left|bottom-right"` + arbitrary JSX. Widgets sharing a corner stack.
+- **`<OmOverlay>`** — geo-anchored HTML with managed projection/tracking/culling. `anchor={[lng, lat]}` or `anchorFrom="selection"` (+ `layer` to scope which picks move it); children may be `(selection) => JSX`; `anchorOffset` (default `bottom-center`); `interactive={false}` for hover-following tooltips.
+- **`useOmMap(watch?)`** — the same `ctx` contract HTML widget scripts get, typed: `layers`, `viewport`, `selection`, `emit`, `data()`, `dataInViewport()`, `stats()`. Watch tokens: `"viewport"`, `"selection"`, `"layers"`, `"data:<layerId>"`.
+
+## Testing (no browser, no GPU)
+
+`<OmMap headless>` runs real projection math under jsdom/happy-dom:
+
+```tsx
+const ref = createRef<OmMapHandle>();
+render(<OmMap ref={ref} headless><OmLayer id="pts" type="ScatterplotLayer" data={rows} getPosition={p} /></OmMap>);
+await ref.current!.ready;
+ref.current!.injectPick({ layerId: "pts", object: rows[0], index: 0, coordinate: [0, 0], pixel: [0, 0], type: "click" });
+```
+
+`injectPick` rides the same selection path as real GPU picks — `onClick`, `useOmMap(["selection"])`, and selection-anchored overlays all react. For browser e2e, expose the `ref` handle (e.g. on `window`) as the readiness/projection probe — a React page has no `<om-map>` element to await.

package/skills/onlymapjs/references/syntax.md

@@ -33,7 +33,8 @@ Common attributes:
 - `zoom="11"`
 - `pitch="55"`
 - `bearing="20"`
-- `basemap="maplibre"` or `basemap="none"` or a MapLibre style URL
+- `basemap` — a free preset (`liberty`, `bright`, `positron`, `dark-matter`, `voyager`, `osm`; keyed `maptiler-streets|dataviz|satellite` with `basemap-key="…"` or `OmMap.configureBasemap({ maptilerKey })`), `maplibre` (bare demo style), a MapLibre style URL, or `none` (standalone canvas). The attribute is live: writing it switches the basemap in place (camera and layers survive). Register more with `OmMap.registerBasemap(name, { style })`.
+- `attribution="false"` to opt out of the automatic provider-attribution control (only if you render equivalent credits yourself)
 - `validate` to show live validation errors during authoring
 - `headless width="800" height="600"` for test harness use
 
@@ -178,6 +179,7 @@ Built-ins:
 - `draw`
 - `vega-lite`
 - `player`
+- `basemap-switcher` — radio list of presets; `options="positron dark-matter osm"` (default: every keyless registered preset)
 
 Positions: `top-left`, `top-right`, `bottom-left`, `bottom-right`.
 
@@ -187,6 +189,7 @@ Examples:
 <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>
+<om-widget type="basemap-switcher" options="positron dark-matter liberty osm" position="top-right"></om-widget>
 ```
 
 Custom widget:
@@ -254,6 +257,7 @@ Common built-in actions:
 - `highlight-feature`
 - `zoom-to-feature`
 - `filter-layer`
+- `set-basemap` — payload `{ basemap }`; writes the `<om-map basemap>` attribute
 - `zoom-in`, `zoom-out`
 - `fly-to`
 - story actions: `story-play`, `story-pause`, `story-seek`