@nika-js/onlymap 0.2.1 → 0.2.2

package/llms.txt

@@ -21,6 +21,7 @@ OnlyMapJS is NOT raw deck.gl and NOT generic HTML/JSX. The rules below are the d
 - `<om-widget type="legend|layer-switcher|basemap-switcher|zoom-controls|scale-bar|attribution|filter|vega-lite" position="bottom-right">` — static UI panels. No `type` + HTML + `<script type="om/widget">` = custom widget with `ctx` (`ctx.layers`, `ctx.data(id)`, `ctx.dataInViewport(id)`, `ctx.stats(id, field)`, `ctx.viewport`, `ctx.selection`, `ctx.emit(action, payload)`), `this.watch = ['data:<layerId>', 'viewport', 'selection', 'layers']`, `this.$(sel)`, `vegaEmbed`/`d3` as globals.
 - `<om-overlay id="..." anchor-from="selection">` — rich geo-anchored HTML (≤ ~20 per map). Anchors: `anchor="[lng, lat]"` (static), `anchor-from="selection"` (follows picks), or `anchor-layer="regions" anchor-feature-id="mission"` (anchored to a feature's own geometry — bbox center — no coordinates in markup; `{{field}}` interpolates that feature's attributes). `{{field}}` interpolates the picked feature HTML-escaped; `{{{field}}}` is raw (avoid). For labels on many features use `PopupLayer`, not overlays.
 - `<om-behavior on="click|hover|drag|load|data-loaded" layer="..." action="...">` — declarative interaction. Built-in actions: `show-overlay`, `hide-overlay`, `show-tooltip`, `hide-tooltip`, `toggle-layer`, `filter-layer`, `highlight-feature`, `zoom-to-feature`, `set-basemap`. One payload contract everywhere: `{ layer, target, feature, featureId, coordinate }`.
+- `<om-fallback>` — static no-JS fallback, direct child of `<om-map>` (one per map, no attributes, plain HTML content — links allowed). Shown ONLY where scripts never run (chat-app/email file previews — iOS QuickLook renders HTML attachments with JS off — file managers, sandboxed webviews); hidden automatically once the map boots. GOOD PRACTICE: include one on every complete page, especially pages that may be shared as a file ("This interactive map requires JavaScript — open this file in a web browser", plus a hosted-version link when one exists). Without one, the stylesheet shows a generic text-only banner. The gate is pure CSS (`om-map:not(:defined)` in onlymapjs.css), so the CSS must load without JS — a real `<link rel="stylesheet">` or inlined `<style>` on no-build pages; a bundler-emitted stylesheet is fine in npm projects.
 - Animation: `transition="get-fill-color 800ms, get-radius 400ms"` on a layer GPU-animates prop changes (also smooths streaming updates via `get-position`). Camera: the `fly-to` action takes `center`/`zoom`/`pitch`/`bearing`/`duration` (e.g. `duration="2s"`) — use it in behaviors or `data-emit` buttons; `zoom-to-feature` also accepts `duration`.
 - `<om-story id="tour" autoplay loop interrupt="pause|ignore">` — a storyboard of `<om-step>` children. Each step: `action="..."` + payload attributes (same kebab-case rule as behaviors) + `duration`/`delay`/`parallel` timing. Steps REFERENCE layers/overlays by id (`layer=`/`target=`) — a step must NEVER contain elements (validation error). Control: `<om-widget type="player" story="tour">`, the story-play/story-pause/story-seek actions, or `storyEl.play()/pause()/seek(ms)`. Seeking restores initial state then applies steps before T; use declarative payloads (e.g. `action="toggle-layer" visible="true"`, not bare toggles) so scrubbing is deterministic. Effect verbs as bare step attributes: `<om-step fade layer="regions" duration="1s">` (opacity reveal — start the layer at `opacity="0"`), `pulse` (attention flash), `trace` (progressive draw — whole-layer needs a TripsLayer; add `feature-id="..."` to make ONE polygon/line draw itself on inside any layer, or use it from a click behavior for click-to-trace), `populate` (rows drop in one by one — ordered by the authored filter-field, a payload `field`, or data order).
 - Filtering: `filter-field="magnitude" filter-range="[4, 10]"` on a layer (GPU-side, live-updatable via the `filter-layer` action); pair with `<om-widget type="filter" layer="..." field="...">`.

package/onlymapjs.html-data.json

@@ -93,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"
         }
       ]
     },
@@ -1294,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).",

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.2.1",
+  "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, 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.
+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
@@ -65,9 +65,12 @@ Load the smallest reference needed for the task:
 - 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/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:
 
@@ -243,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.