@nika-js/onlymap 0.2.0 → 0.2.2

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"
             }
           ]
         },
@@ -50,7 +93,7 @@
       "references": [
         {
           "name": "README",
-          "url": "https://github.com/NikaGeospatial/onlymapjs/blob/main/docs/../README.md"
+          "url": "https://github.com/NikaGeospatial/onlymapjs/blob/main/README.md"
         }
       ]
     },
@@ -1251,6 +1294,17 @@
         }
       ]
     },
+    {
+      "name": "om-fallback",
+      "description": "Static fallback shown only when the library never boots — JS-disabled contexts like chat-app/email file previews (iOS QuickLook), file managers, sandboxed webviews. Direct child of <om-map>; hidden automatically once the map upgrades. Good practice on any page that may be shared as a file. Without one, the stylesheet shows a text-only default banner. Requires onlymapjs.css to load without JS (link tag / bundled / inlined).",
+      "attributes": [],
+      "references": [
+        {
+          "name": "README",
+          "url": "https://github.com/NikaGeospatial/onlymapjs/blob/main/README.md"
+        }
+      ]
+    },
     {
       "name": "om-behavior",
       "description": "Declarative event → action wiring. Every other attribute becomes a payload key (kebab→camel).",
@@ -1358,6 +1412,9 @@
             },
             {
               "name": "draw-save"
+            },
+            {
+              "name": "set-basemap"
             }
           ]
         },
@@ -1405,6 +1462,9 @@
             },
             {
               "name": "draw"
+            },
+            {
+              "name": "basemap-switcher"
             }
           ]
         },
@@ -1483,6 +1543,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 +1677,9 @@
             },
             {
               "name": "draw-save"
+            },
+            {
+              "name": "set-basemap"
             }
           ]
         },

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",
+  "homepage": "https://www.nikaplanet.com/onlymap",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/NikaGeospatial/onlymapjs.git"

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, a map page shared as a single HTML file (incl. no-JS fallbacks for chat/email previews), 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,12 +61,16 @@ 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">`.
+- Page may travel as a file (shared, emailed, downloaded) or be embedded -> add an `<om-fallback>` child to `<om-map>`. Chat-app and email previews render HTML with JavaScript disabled (iOS QuickLook), so the map cannot boot there; the fallback is what recipients see instead. It is hidden automatically once the map boots. Good practice on every complete page — without one, the stylesheet shows a generic text-only banner.
 
 ## 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.
 
+Include an `<om-fallback>` element (a short "this map requires JavaScript — open in a browser" message, optionally with a hosted-version link) as a direct child of `<om-map>` on any complete page. For the fallback to render in no-JS previews, `onlymapjs.css` must load without JavaScript — a real `<link rel="stylesheet">` or inlined `<style>`, not only a runtime `import` (bundler-emitted stylesheets are fine).
+
 When modifying an existing page, preserve the user's data URLs, layer ids, and styling unless the request requires changing them.

package/skills/onlymapjs/references/patterns.md

@@ -29,11 +29,17 @@ Use these patterns as starting points. Replace data URLs, layer ids, fields, cen
                 pickable></om-layer>
     <om-widget type="legend" position="bottom-right" title="Layers"></om-widget>
     <om-widget type="zoom-controls" position="top-right"></om-widget>
+    <!-- Shown only where scripts never run (chat-app/email file previews) -->
+    <om-fallback>
+      <p>This interactive map requires JavaScript — open this file in a web browser.</p>
+    </om-fallback>
   </om-map>
 </body>
 </html>
 ```
 
+Every complete-page pattern below should also carry an `<om-fallback>` (omitted for brevity) — see the good-practice rule in SKILL.md.
+
 ## Click Popup
 
 ```html

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

@@ -19,13 +19,13 @@ Static CDN page:
 <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.
+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).
 
 ## Elements
 
 ### `<om-map>`
 
-Root element. Children are layers, widgets, overlays, behaviors, and stories.
+Root element. Children are layers, widgets, overlays, behaviors, stories, and an optional fallback.
 
 Common attributes:
 
@@ -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:
@@ -240,6 +243,26 @@ Example:
 <om-behavior on="click" layer="quakes" action="show-overlay" target="detail"></om-behavior>
 ```
 
+### `<om-fallback>`
+
+Static content shown only where scripts never run — chat-app/email file previews (iOS QuickLook), file managers, sandboxed webviews. Hidden automatically once the map boots. Good practice on every complete page, especially one that may be shared as a file.
+
+Rules:
+
+- Direct child of `<om-map>` (validation warns elsewhere), one per map.
+- No attributes; plain HTML content — links work, so include a hosted-version URL when one exists.
+- Without an `<om-fallback>`, the stylesheet shows a generic text-only banner instead.
+- Requires `onlymapjs.css` to load without JavaScript (see Import Patterns above).
+
+Example:
+
+```html
+<om-fallback>
+  <p><strong>This interactive map requires JavaScript.</strong><br />
+     Open this file in a web browser, or visit <a href="https://example.com/map">the hosted version</a>.</p>
+</om-fallback>
+```
+
 ### `<om-behavior>`
 
 Declarative event to action binding.
@@ -254,6 +277,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`