@nika-js/onlymap 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/.vscode/onlymap.code-snippets +27 -4
  2. package/LICENSE.md +22 -12
  3. package/README.md +29 -7
  4. package/dist/actions.d.ts +2 -2
  5. package/dist/badge.d.ts +4 -0
  6. package/dist/{basemap-COurZNDH.js → basemap-BdvB-SHy.js} +1 -1
  7. package/dist/ctx.d.ts +10 -1
  8. package/dist/elements/om-fallback.d.ts +22 -0
  9. package/dist/elements/om-map.d.ts +1 -0
  10. package/dist/error-reporting.d.ts +17 -0
  11. package/dist/history.d.ts +53 -0
  12. package/dist/html-data.d.ts +2 -2
  13. package/dist/{index-COu-3-gN.js → index-BVQ0s1Zh.js} +1 -1
  14. package/dist/{index-CvfuISOc.js → index-BxzDKZpu.js} +14525 -13990
  15. package/dist/{index-D-X8KPA1.js → index-CJOMgp8k.js} +1 -1
  16. package/dist/{index-DuvXK95V.js → index-CvBHiOGD.js} +2 -2
  17. package/dist/{index-CgyAD98B.js → index-Vc8QfNEf.js} +1 -1
  18. package/dist/index.d.ts +10 -0
  19. package/dist/internal-ids.d.ts +7 -0
  20. package/dist/ir-diff.d.ts +1 -1
  21. package/dist/license.d.ts +64 -0
  22. package/dist/onlymapjs.css +1 -1
  23. package/dist/onlymapjs.js +27 -24
  24. package/dist/onlymapjs.umd.cjs +290 -280
  25. package/dist/runtime-core.d.ts +6 -0
  26. package/dist/telemetry-schema.d.ts +53 -0
  27. package/dist/telemetry.d.ts +60 -0
  28. package/dist/version.d.ts +8 -0
  29. package/docs/react.md +1 -0
  30. package/docs/telemetry.md +78 -0
  31. package/docs/testing.md +2 -2
  32. package/llms.txt +5 -3
  33. package/onlymapjs.html-data.json +44 -1
  34. package/package.json +7 -4
  35. package/skills/onlymapjs/SKILL.md +8 -2
  36. package/skills/onlymapjs/references/patterns.md +6 -0
  37. package/skills/onlymapjs/references/syntax.md +30 -2
  38. package/skills/onlymapjs/references/testing.md +2 -0
package/.vscode/onlymap.code-snippets CHANGED
@@ -16,8 +16,8 @@
16
16
  "</head>",
17
17
  "<body>",
18
18
  "",
19
- " <!-- validate → live error panel while you hand-author (strip for production) -->",
20
- " <om-map center=\"[-122.42, 37.77]\" zoom=\"${2:11}\" basemap=\"maplibre\" validate>",
19
+ " <!-- validate → live error panel while you hand-author (strip for production); map-id identifies this map artifact (delete to opt out of telemetry dedup) -->",
20
+ " <om-map center=\"[-122.42, 37.77]\" zoom=\"${2:11}\" basemap=\"maplibre\" map-id=\"$UUID\" validate>",
21
21
  "",
22
22
  " <!-- One data layer: type + data URL + accessors. pickable → behaviors can fire. -->",
23
23
  " <om-layer id=\"${3:points}\" type=\"ScatterplotLayer\"",
@@ -36,6 +36,11 @@
36
36
  " <!-- Built-in legend — reads label/color from each <om-layer> -->",
37
37
  " <om-widget type=\"legend\" title=\"Layers\" position=\"top-right\"></om-widget>",
38
38
  "",
39
+ " <!-- Shown only where scripts never run (chat-app/email file previews) — hidden once the map boots -->",
40
+ " <om-fallback>",
41
+ " <p>This interactive map requires JavaScript.<br />Open this file in a web browser such as Chrome, Safari, or Firefox.</p>",
42
+ " </om-fallback>",
43
+ "",
39
44
  " </om-map>",
40
45
  "",
41
46
  "</body>",
@@ -73,11 +78,16 @@
73
78
  "prefix": "!map",
74
79
  "description": "<om-map> root with camera + basemap + validate",
75
80
  "body": [
76
- "<!-- validate → on-page error panel; basemap=\"maplibre\" needs no token -->",
77
- "<om-map center=\"[-122.42, 37.77]\" zoom=\"${1:11}\" basemap=\"maplibre\" validate>",
81
+ "<!-- validate → on-page error panel; basemap=\"maplibre\" needs no token; map-id identifies this map artifact (delete to opt out of telemetry dedup) -->",
82
+ "<om-map center=\"[-122.42, 37.77]\" zoom=\"${1:11}\" basemap=\"maplibre\" map-id=\"$UUID\" validate>",
78
83
  "",
79
84
  " $0",
80
85
  "",
86
+ " <!-- Shown only where scripts never run (chat-app/email file previews) -->",
87
+ " <om-fallback>",
88
+ " <p>This interactive map requires JavaScript — open this file in a web browser.</p>",
89
+ " </om-fallback>",
90
+ "",
81
91
  "</om-map>"
82
92
  ]
83
93
  },
@@ -157,6 +167,19 @@
157
167
  ]
158
168
  },
159
169
 
170
+ "!fallback": {
171
+ "scope": "html",
172
+ "prefix": "!fallback",
173
+ "description": "<om-fallback> — no-JS fallback for shared/previewed files (hidden once the map boots)",
174
+ "body": [
175
+ "<!-- Shown only where scripts never run (chat-app/email file previews, iOS QuickLook) -->",
176
+ "<om-fallback>",
177
+ " <p>${1:This interactive map requires JavaScript.}<br />",
178
+ " ${2:Open this file in a web browser such as Chrome, Safari, or Firefox.}</p>",
179
+ "</om-fallback>$0"
180
+ ]
181
+ },
182
+
160
183
  "!inline-data": {
161
184
  "scope": "html",
162
185
  "prefix": "!inline-data",
package/LICENSE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # OnlyMap Commercial License Agreement
2
2
 
3
- **Last Updated:** July 9, 2026
3
+ **Last Updated:** July 14, 2026
4
4
 
5
5
  This OnlyMap Commercial License Agreement ("Agreement") governs access to and use of OnlyMap, published as the `OnlyMap` package or otherwise made available by the copyright holder ("Licensor"). By downloading, installing, accessing, or using the Software, you accept this Agreement.
6
6
 
@@ -27,9 +27,13 @@ Subject to Licensee's compliance with this Agreement and any applicable Order Fo
27
27
 
28
28
  No ownership rights are transferred. Licensor and its licensors retain all right, title, and interest in and to the Software.
29
29
 
30
- ## 3. Commercial Authorization Required
30
+ ## 3. Non-Commercial and Commercial Use
31
31
 
32
- The Software is commercial proprietary software. Unless Licensor has granted Licensee a written evaluation license, Licensee may use the Software only if Licensee has purchased and maintains a valid commercial license from Licensor.
32
+ The Software is commercial proprietary software.
33
+
34
+ **Non-Commercial Use.** Licensee may exercise the rights granted in Section 2 free of charge for Non-Commercial Use, provided that the Software's included attribution — the on-map "OnlyMap by NIKA" notice and other proprietary notices — remains visible, unmodified, and unobstructed in every Application. "Non-Commercial Use" means personal, educational, academic-research, or evaluation use that is not intended for or directed toward commercial advantage or monetary compensation, whether for Licensee or any third party. Use by or on behalf of a for-profit business (including internal business tools), in any product or service that generates revenue (including through advertising, subscriptions, or paid access), or in paid consulting or government work is not Non-Commercial Use. Non-Commercial Use may be subject to technical limits built into the Software.
35
+
36
+ **Commercial use.** Any use other than Non-Commercial Use requires a purchased and maintained valid commercial license from Licensor, unless Licensor has granted Licensee a separate written license.
33
37
 
34
38
  Access to an npm package, repository, package tarball, source archive, or build artifact does not by itself grant any rights beyond the rights expressly granted in this Agreement.
35
39
 
@@ -88,13 +92,19 @@ Licensor may provide updates, patches, or new versions at its discretion. Unless
88
92
 
89
93
  Updates are part of the Software and are governed by this Agreement unless Licensor provides different terms with the update.
90
94
 
91
- ## 11. Fees and Taxes
95
+ ## 11. Telemetry
96
+
97
+ The Software may transmit anonymous, deployment-scoped usage reports and error reports to Licensor's telemetry endpoint when the Software runs (for example, when a map finishes loading). These reports may include the Software version, feature and layer usage counts, widget types, the hostname of the page using the Software, an optional author-assigned map identifier, and, for errors caused by the Software, sanitized error signatures.
98
+
99
+ Telemetry reports do not include end-user identifiers, page URLs or paths, cookies, map data, or the contents of Licensee's Applications, and Licensor does not store IP addresses from telemetry requests. Telemetry can be disabled at any time, globally via `OmMap.configureTelemetry({ disabled: true })` or per map with the `telemetry="off"` attribute. The full payload schema and collection rules are documented in the Software's `docs/telemetry.md`.
100
+
101
+ ## 12. Fees and Taxes
92
102
 
93
103
  Licensee must pay all fees stated in the applicable Order Form. Fees are non-refundable except as expressly stated in the Order Form or required by law.
94
104
 
95
105
  Licensee is responsible for taxes, duties, levies, and similar governmental charges arising from its purchase or use of the Software, excluding taxes based on Licensor's net income.
96
106
 
97
- ## 12. Term and Termination
107
+ ## 13. Term and Termination
98
108
 
99
109
  This Agreement begins when Licensee first downloads, installs, accesses, or uses the Software and continues until terminated.
100
110
 
@@ -102,32 +112,32 @@ Licensor may terminate this Agreement immediately if Licensee breaches this Agre
102
112
 
103
113
  Sections that by their nature should survive termination will survive, including ownership, restrictions, payment obligations, warranty disclaimers, liability limits, and governing law.
104
114
 
105
- ## 13. Disclaimer of Warranty
115
+ ## 14. Disclaimer of Warranty
106
116
 
107
117
  TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE," WITHOUT WARRANTIES OF ANY KIND, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, ACCURACY, AVAILABILITY, SECURITY, OR ERROR-FREE OPERATION.
108
118
 
109
- ## 14. Limitation of Liability
119
+ ## 15. Limitation of Liability
110
120
 
111
121
  TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR WILL NOT BE LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOST PROFITS, LOST REVENUE, LOST DATA, BUSINESS INTERRUPTION, OR PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, ARISING OUT OF OR RELATING TO THE SOFTWARE OR THIS AGREEMENT, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF THOSE DAMAGES.
112
122
 
113
123
  TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR'S TOTAL LIABILITY ARISING OUT OF OR RELATING TO THE SOFTWARE OR THIS AGREEMENT WILL NOT EXCEED THE AMOUNTS PAID BY LICENSEE TO LICENSOR FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE THE EVENT GIVING RISE TO LIABILITY, OR USD 100 IF LICENSEE PAID NO AMOUNTS DURING THAT PERIOD.
114
124
 
115
- ## 15. Export and Compliance
125
+ ## 16. Export and Compliance
116
126
 
117
127
  Licensee must comply with all applicable export control, sanctions, anti-corruption, privacy, data protection, and other laws applicable to Licensee's use of the Software.
118
128
 
119
- ## 16. Assignment
129
+ ## 17. Assignment
120
130
 
121
131
  Licensee may not assign or transfer this Agreement, any Order Form, or any rights or obligations under them without Licensor's prior written consent. Any attempted assignment in violation of this section is void.
122
132
 
123
- ## 17. Governing Law
133
+ ## 18. Governing Law
124
134
 
125
135
  This Agreement is governed by the laws of the jurisdiction in which Licensor resides or is organized, without regard to conflict of law principles. The parties consent to the exclusive jurisdiction and venue of the courts located in that jurisdiction for disputes arising out of or relating to this Agreement.
126
136
 
127
- ## 18. Entire Agreement
137
+ ## 19. Entire Agreement
128
138
 
129
139
  This Agreement, together with any applicable Order Form, is the entire agreement between Licensor and Licensee regarding the Software and supersedes all prior or contemporaneous agreements, proposals, or understandings about the Software.
130
140
 
131
- ## 19. Contact
141
+ ## 20. Contact
132
142
 
133
143
  For licensing questions or requests for permissions beyond this Agreement, contact Licensor through the official repository, npm package page, website, or other distribution channel for the Software.
package/README.md CHANGED
@@ -30,7 +30,7 @@ That's a complete app: a no-token MapLibre basemap, data-driven colors and sizes
30
30
 
31
31
  It's also designed to be written **by AI agents**: HTML is a reliable generation target, [`llms.txt`](llms.txt) teaches the format, and `OmMap.validate()` returns structured errors with actionable fixes — a real feedback loop instead of a blank canvas.
32
32
 
33
- > ⚠️ **Status: v0.1.** Proprietary — commercial licensing terms are in [LICENSE.md](LICENSE.md); APIs may still move before 1.0.
33
+ > ⚠️ **Status: v0.2.** Proprietary — free for non-commercial use with attribution; commercial licensing terms are in [LICENSE.md](LICENSE.md). APIs may still move before 1.0.
34
34
 
35
35
  ## Install
36
36
 
@@ -44,22 +44,23 @@ Or with no build step at all, straight from a CDN:
44
44
  <script type="module" src="https://esm.sh/@nika-js/onlymap"></script>
45
45
  ```
46
46
 
47
- Then `npx @nika-js/onlymap init` wires up VS Code IntelliSense and `!`-prefixed manifest snippets for your project. The library ships with 254 unit/behavioral tests and 12 Playwright GPU tests.
47
+ Then `npx @nika-js/onlymap init` wires up VS Code IntelliSense and `!`-prefixed manifest snippets for your project. The library ships with 366 unit/behavioral tests and 21 Playwright GPU tests.
48
48
 
49
49
  The [examples](https://github.com/NikaGeospatial/onlymapjs/tree/main/examples) are the best tour: widgets, behaviors & overlays, basemaps, columnar/Arrow data, manual drawing, 3D models, a live WebSocket ship feed, and a polled driver fleet.
50
50
 
51
51
  ## The manifest
52
52
 
53
- Five elements, one rule: **attributes are kebab-case versions of deck.gl props** (`radius-units` → `radiusUnits`), and `get-*` attributes are data-driven accessors.
53
+ A handful of elements, one rule: **attributes are kebab-case versions of deck.gl props** (`radius-units` → `radiusUnits`), and `get-*` attributes are data-driven accessors.
54
54
 
55
55
  | Element | Role |
56
56
  |---|---|
57
57
  | `<om-map>` | The map. `center`, `zoom`, `pitch`, `bearing`; `basemap` takes a free preset (`positron`, `liberty`, `dark-matter`, `osm`, …), a style URL, or `"none"` (standalone canvas) — and switches **live**; `validate` for a live on-page error panel. |
58
58
  | `<om-layer>` | Any of **33 layer types** by name — all of deck.gl's core, geo, aggregation, and mesh layers (Scatterplot, GeoJson, Arc, Path, Heatmap, Hexagon, Trips, Tile, Tile3D, Scenegraph, …) plus the built-in `PopupLayer` for WebGL badges/labels at scale. `id` required; `label`/`color` feed the legend. |
59
- | `<om-widget>` | UI panels. Built-ins: `legend`, `layer-switcher`, `basemap-switcher`, `zoom-controls`, `scale-bar`, `attribution`, `filter`, `draw`, `vega-lite` (live charts). Or write your own inline with HTML + a `<script type="om/widget">`. |
59
+ | `<om-widget>` | UI panels. Built-ins: `legend`, `layer-switcher`, `basemap-switcher`, `zoom-controls`, `undo-redo`, `scale-bar`, `attribution`, `filter`, `draw`, `vega-lite` (live charts). Or write your own inline with HTML + a `<script type="om/widget">`. |
60
60
  | `<om-overlay>` | Rich HTML anchored to a map location — a static `anchor="[lng, lat]"`, the current selection, or a feature's own geometry via `anchor-layer`/`anchor-feature-id`. `{{field}}` interpolates the picked feature, HTML-escaped by default. |
61
61
  | `<om-behavior>` | Declarative interactions: `on="click|hover|drag|load|data-loaded"` → a named action. |
62
62
  | `<om-story>` | A storyboard: `<om-step>` children fire actions on a timeline. Controlled by the `player` widget, behaviors, or `storyEl.play()/pause()/seek()`. |
63
+ | `<om-fallback>` | What shows where scripts never run — chat-app/email file previews (iOS QuickLook renders HTML attachments with JS off), file managers, sandboxed webviews. A direct child of `<om-map>`, hidden automatically the moment the map boots; pages without one get a text-only default banner from the stylesheet. Good practice on any page that may travel as a file. The gate is pure CSS (`om-map:not(:defined)`), so `onlymapjs.css` must load without JS — a real `<link>`, a bundler-emitted sheet, or an inlined `<style>`. |
63
64
 
64
65
  ### Accessors without JavaScript
65
66
 
@@ -93,7 +94,9 @@ Private endpoints: `OmMap.configureData({ headers, credentials, fetch })` — ap
93
94
 
94
95
  ### Interaction
95
96
 
96
- Built-in actions wire to picks, widget buttons (`data-emit`), or script (`ctx.emit`) with one shared payload contract: `show-overlay`, `hide-overlay`, `show-tooltip`, `hide-tooltip`, `toggle-layer`, `highlight-feature`, `zoom-to-feature`, `filter-layer`, `set-basemap`, `zoom-in`, `zoom-out` — plus `OmMap.registerAction` for your own.
97
+ Built-in actions wire to picks, widget buttons (`data-emit`), or script (`ctx.emit`) with one shared payload contract: `show-overlay`, `hide-overlay`, `show-tooltip`, `hide-tooltip`, `toggle-layer`, `highlight-feature`, `zoom-to-feature`, `filter-layer`, `set-basemap`, `zoom-in`, `zoom-out`, `undo`, `redo` — plus `OmMap.registerAction` for your own.
98
+
99
+ **Undo/redo:** user-facing manifest changes — layer toggles, filter changes, basemap switches, element edits, drawn sketches — are undoable out of the box; the manifest *is* the state, so history is recorded from the DOM itself. Add `<om-widget type="undo-redo">` for buttons, or just press Cmd/Ctrl-Z (Shift-Cmd/Ctrl-Z or Ctrl-Y to redo). Camera moves, hover effects, and story playback are deliberately not undo steps.
97
100
 
98
101
  **Basemaps:** free presets out of the box — OpenFreeMap `liberty`/`bright`/`positron` (no key, no limits), CARTO `dark-matter`/`voyager`, classic `osm` raster, and keyed `maptiler-*` presets (MapTiler's style editor is the visual way to customize basemap JSON; keys are publishable, via `basemap-key` or `OmMap.configureBasemap`). The `basemap` attribute switches **live** — camera and layers survive — from a hand edit, the `set-basemap` action, or `<om-widget type="basemap-switcher">`. Add your own with `OmMap.registerBasemap(name, { style })`; required attribution renders automatically. Guide: [docs/basemaps.md](docs/basemaps.md).
99
102
 
@@ -192,11 +195,30 @@ Plus `OmMap.snapshotIR(html)` to lock down what a manifest *means* in a snapshot
192
195
 
193
196
  ## Programmatic surface
194
197
 
195
- - **`OmMap.*`** — `validate`, `snapshotIR`, `registerLayer`, `registerWidget`, `registerAction`, `registerSource`, `registerFormat`, `registerBasemap`, `configureBasemap`, `configureData`, `getLayerSchema`
198
+ - **`OmMap.*`** — `validate`, `snapshotIR`, `registerLayer`, `registerWidget`, `registerAction`, `registerSource`, `registerFormat`, `registerBasemap`, `configureBasemap`, `configureData`, `configureTelemetry`, `configureLicense`, `getLayerSchema`
196
199
  - **On a `<om-map>` element** — `ready` (promise), `flyTo(coords, zoom?)`, `setLayerVisible(id, bool)`, `getLayers()`, `emit(action, payload)`; `document.querySelector("om-map")` is fully typed
197
200
  - **`MapController`** — the framework-grade programmatic front-end (typed `LayerDescriptor`s → the same reconcile core, no DOM manifest): `setLayers`, `watch`, `emit`, camera methods, `injectPick`, `ready`. The React adapter rides it; usable directly from vanilla TS or other frameworks
198
201
  - **Testing** — `mountForTest`, and imports are SSR-safe (importing in Node/jsdom never touches browser globals)
199
202
 
203
+ ## Free tier & licensing
204
+
205
+ **Non-commercial use is free with attribution** (LICENSE.md §3); commercial use requires a license. Without a license key, maps run on the **free plan**: up to **5 layers** and **25,000 rows per layer** (20 MB per data fetch), with a small "OnlyMap by NIKA. Free for non-commercial use." badge in the corner. Exceeding a limit never breaks the map — the offending layer simply doesn't render, and the validation stream/error panel tells you exactly which limit, why, and how to lift it. Limits apply identically everywhere (including localhost — no dev/prod surprises).
206
+
207
+ A license key lifts all limits and removes the badge:
208
+
209
+ ```html
210
+ <om-map license-key="om_live_…"> <!-- keys are publishable & origin-restricted — safe in page source -->
211
+ ```
212
+ ```ts
213
+ OmMap.configureLicense("om_live_…"); // or once, in code
214
+ ```
215
+
216
+ Keys are self-verifying signed tokens (no network round-trip, works offline and in CI) bound to your domains. Licensing: https://www.nikaplanet.com/onlymap.
217
+
218
+ ## Telemetry
219
+
220
+ The library reports one **deployment-scoped** usage snapshot per map per page load — layer types and counts, widget types, renderer; hostname only, no page URLs, no visitor identifiers, and `headless` (test) maps never report — plus errors caused by the library's own code (own-bundle stack filtering, scrubbed, rate-limited). Reports go to a first-party endpoint, never a third-party domain. Opt out globally with `OmMap.configureTelemetry({ disabled: true })` or per map with `telemetry="off"`. Full schema, rules, and the license disclosure: [docs/telemetry.md](docs/telemetry.md), LICENSE.md §11.
221
+
200
222
  ## Not implemented yet (honestly)
201
223
 
202
224
  Mapbox GL basemaps, depth-interleaved 3D compositing, globe projection, SSE transport, multi-field filters, `dblclick` behaviors, the `transform` data pipeline, the typed fluent builder, and stories/draw as React components (both work via the HTML manifest).
@@ -205,6 +227,6 @@ Mapbox GL basemaps, depth-interleaved 3D compositing, globe projection, SSE tran
205
227
 
206
228
  | | |
207
229
  |---|---|
208
- | [docs/react.md](docs/react.md) · [docs/basemaps.md](docs/basemaps.md) · [docs/testing.md](docs/testing.md) · [docs/live-data.md](docs/live-data.md) · [docs/3d-assets.md](docs/3d-assets.md) · [docs/stories.md](docs/stories.md) | Consumer guides |
230
+ | [docs/react.md](docs/react.md) · [docs/basemaps.md](docs/basemaps.md) · [docs/testing.md](docs/testing.md) · [docs/live-data.md](docs/live-data.md) · [docs/3d-assets.md](docs/3d-assets.md) · [docs/stories.md](docs/stories.md) · [docs/telemetry.md](docs/telemetry.md) | Consumer guides |
209
231
  | [llms.txt](llms.txt) | The agent-facing quick reference |
210
232
  | `skills/onlymapjs` | Installable LLM skill for OnlyMapJS authoring |
package/dist/actions.d.ts CHANGED
@@ -14,8 +14,8 @@ export type ActionHandler = (payload: Record<string, unknown>, mapEl: Element, c
14
14
  export declare function hasAction(name: string): boolean;
15
15
  export declare function registerAction(name: string, handler: ActionHandler): void;
16
16
  export declare function dispatchAction(name: string, payload: Record<string, unknown>, mapEl: Element, core: RuntimeCore, layerIRs?: ReadonlyMap<string, LayerIR>): void;
17
- /** Ids in this namespace are runtime-managed plumbing — excluded from ctx.layers (legend, layer-list, user widgets). */
18
- export declare const RUNTIME_INTERNAL_PREFIX = "__onlymapjs-";
17
+ /** Ids in this namespace are runtime-managed plumbing — excluded from ctx.layers (legend, layer-list, user widgets). Defined in internal-ids.ts (dependency-free); re-exported here as the historical home. */
18
+ export { RUNTIME_INTERNAL_PREFIX } from "./internal-ids";
19
19
  /** The overlay anchor for a feature: its bbox center for geojson geometry, else its point (flat lon/lat). */
20
20
  export declare function featureAnchorPoint(feature: unknown): [number, number] | undefined;
21
21
  /**
package/dist/badge.d.ts ADDED
@@ -0,0 +1,4 @@
1
+ export interface BadgeHandle {
2
+ destroy(): void;
3
+ }
4
+ export declare function mountBadge(container: HTMLElement): BadgeHandle;
package/dist/{basemap-COurZNDH.js → basemap-BdvB-SHy.js} RENAMED
@@ -1,7 +1,7 @@
1
1
  var sy = Object.defineProperty;
2
2
  var oy = (ve, J, me) => J in ve ? sy(ve, J, { enumerable: !0, configurable: !0, writable: !0, value: me }) : ve[J] = me;
3
3
  var _s = (ve, J, me) => oy(ve, typeof J != "symbol" ? J + "" : J, me);
4
- import { a4 as ay, a5 as ly, a6 as cy, a7 as uy, a8 as Ra, a9 as ac, aa as Pd, ab as om, ac as hy, ad as dy, ae as py, af as fy, ag as ju, ah as Cd, ai as my, aj as gy, ak as _y, al as em, am as yy } from "./index-CvfuISOc.js";
4
+ import { a4 as ay, a5 as ly, a6 as cy, a7 as uy, a8 as Ra, a9 as ac, aa as Pd, ab as om, ac as hy, ad as dy, ae as py, af as fy, ag as ju, ah as Cd, ai as my, aj as gy, ak as _y, al as em, am as yy } from "./index-BxzDKZpu.js";
5
5
  const Ad = Math.PI / 180, vy = 180 / Math.PI;
6
6
  function tm(ve, J = 0) {
7
7
  const me = Math.min(180, ve) * Ad;
package/dist/ctx.d.ts CHANGED
@@ -32,6 +32,11 @@ export interface RuntimeContext {
32
32
  project(lngLat: [number, number]): [number, number];
33
33
  };
34
34
  selection: Selection | null;
35
+ /** Manifest undo/redo state (spec: "Undo / Redo — Manifest History") — drive it via emit("undo"/"redo"). Always false on the programmatic/React path (the app owns state there). */
36
+ history: {
37
+ canUndo: boolean;
38
+ canRedo: boolean;
39
+ };
35
40
  emit(event: string, payload?: Record<string, unknown>): void;
36
41
  data(layerId: string, opts?: DataOpts): Promise<unknown[]>;
37
42
  dataInViewport(layerId: string, opts?: DataOpts): Promise<unknown[]>;
@@ -44,6 +49,10 @@ export interface BuildCtxDeps {
44
49
  core: RuntimeCore;
45
50
  mapEl: Element;
46
51
  selection: Selection | null;
52
+ history?: {
53
+ canUndo: boolean;
54
+ canRedo: boolean;
55
+ };
47
56
  }
48
57
  /** Built fresh on every widget-render invocation — never mutated, never reused. */
49
- export declare function buildCtx({ layerIRs, core, mapEl, selection }: BuildCtxDeps): RuntimeContext;
58
+ export declare function buildCtx({ layerIRs, core, mapEl, selection, history }: BuildCtxDeps): RuntimeContext;
package/dist/elements/om-fallback.d.ts ADDED
@@ -0,0 +1,22 @@
1
+ /**
2
+ * <om-fallback> — static content shown only when the library never boots:
3
+ * scripting-disabled contexts like chat-app/email file previews (iOS
4
+ * QuickLook renders HTML attachments with JS off), file managers, and
5
+ * sandboxed webviews (spec: "Deployment & Distribution / No-JS fallback").
6
+ *
7
+ * Deliberately logic-free: the show/hide gate lives in the shipped
8
+ * stylesheet (src/fallback.css) as `om-map:not(:defined)` rules, because
9
+ * only the CSS engine — not script — still runs where this element earns
10
+ * its keep. The class exists for two reasons: registering it keeps the
11
+ * element out of "unknown tag" territory for tooling, and its
12
+ * connectedCallback hides the element inline as a belt-and-braces for
13
+ * pages that loaded the JS bundle but not onlymapjs.css (if this code
14
+ * runs at all, the map is booting and the fallback must not show).
15
+ *
16
+ * Pages without an <om-fallback> still get a text-only default banner,
17
+ * generated by the stylesheet on `om-map:not(:defined)::before`.
18
+ */
19
+ import { HTMLElementBase } from "../env";
20
+ export declare class OmFallbackElement extends HTMLElementBase {
21
+ connectedCallback(): void;
22
+ }
package/dist/elements/om-map.d.ts CHANGED
@@ -28,6 +28,7 @@ interface OverlayHost {
28
28
  export declare class OmMapElement extends HTMLElementBase {
29
29
  private core;
30
30
  private observer;
31
+ private history;
31
32
  private keydownHandler?;
32
33
  private dblclickHandler?;
33
34
  private contextmenuHandler?;
package/dist/error-reporting.d.ts ADDED
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The library's own code location — the directory this module was loaded
3
+ * from (`dist/` for the published bundle and its lazy chunks, `src/` in
4
+ * dev). A frame is "ours" iff its URL starts with this prefix; everything
5
+ * else on the page is not our bug to report.
6
+ */
7
+ export declare const OWN_CODE_PREFIX: string;
8
+ /**
9
+ * Report an error IF it is ours: at least one stack frame must come from
10
+ * the library's own code location. Exported for the window listeners below
11
+ * and for direct use by future internal catch sites.
12
+ */
13
+ export declare function reportLibraryError(candidate: unknown, filename?: string): void;
14
+ /** Idempotent page-level install — the first om-map to connect calls this. */
15
+ export declare function installErrorReporting(): void;
16
+ /** Test hook — resets the per-page dedup/cap state. */
17
+ export declare function resetErrorReportingForTests(): void;
package/dist/history.d.ts ADDED
@@ -0,0 +1,53 @@
1
+ export interface HistoryOptions {
2
+ /** The renderer-owned subtree — mutations inside are never manifest changes. */
3
+ excludeContainer?: () => Node | null;
4
+ /** Fired whenever canUndo/canRedo may have changed (om-map notifies `history`-watching widgets). */
5
+ onChange?: () => void;
6
+ limit?: number;
7
+ }
8
+ export declare class ManifestHistory {
9
+ private readonly root;
10
+ private readonly opts;
11
+ private readonly undoStack;
12
+ private readonly redoStack;
13
+ private readonly observer;
14
+ private applying;
15
+ private suppressDepth;
16
+ private readonly limit;
17
+ constructor(root: Element, opts?: HistoryOptions);
18
+ get canUndo(): boolean;
19
+ get canRedo(): boolean;
20
+ get depth(): number;
21
+ /**
22
+ * Push a non-DOM inverse pair onto the same stack (the draw store's
23
+ * committed-sketch snapshots). Ignored while a replay is applying — a
24
+ * custom op's own side effects must not re-record — or while suppressed.
25
+ */
26
+ record(entry: {
27
+ undo(): void;
28
+ redo(): void;
29
+ }): void;
30
+ /**
31
+ * Run `fn` with recording off — story playback/scrub, hover-driven
32
+ * transients. Pending records from BEFORE the call are ingested first
33
+ * (they were recordable); records produced BY the call are discarded
34
+ * synchronously via takeRecords, so suppression needs no async handshake.
35
+ */
36
+ suppress<T>(fn: () => T): T;
37
+ undo(): void;
38
+ redo(): void;
39
+ destroy(): void;
40
+ /** Observer callbacks are microtasks — force pending records through NOW so undo()/canUndo see a current stack. */
41
+ private settle;
42
+ private apply;
43
+ private applyOp;
44
+ private ingest;
45
+ private push;
46
+ private isExcludedNode;
47
+ private isRecordableAttr;
48
+ }
49
+ export declare function createHistory(mapEl: Element, opts?: HistoryOptions): ManifestHistory;
50
+ export declare function peekHistory(mapEl: Element): ManifestHistory | undefined;
51
+ export declare function destroyHistory(mapEl: Element): void;
52
+ /** Run `fn` with this map's recording suppressed — a no-op passthrough when no history exists (headless React path, early boot). */
53
+ export declare function suppressHistory<T>(mapEl: Element | null, fn: () => T): T;
package/dist/html-data.d.ts CHANGED
@@ -15,9 +15,9 @@ interface TagData {
15
15
  }[];
16
16
  }
17
17
  /** Hand-authored action list — validated against hasAction() in html-data.test.ts. */
18
- export declare const BUILTIN_ACTIONS: readonly ["toggle-layer", "zoom-in", "zoom-out", "filter-layer", "highlight-feature", "fade", "pulse", "populate", "trace", "story-play", "story-pause", "story-seek", "fly-to", "zoom-to-feature", "show-overlay", "hide-overlay", "show-tooltip", "hide-tooltip", "draw-mode", "draw-commit", "draw-cancel", "draw-delete", "draw-clear", "draw-config", "draw-save", "set-basemap"];
18
+ export declare const BUILTIN_ACTIONS: readonly ["toggle-layer", "zoom-in", "zoom-out", "filter-layer", "highlight-feature", "fade", "pulse", "populate", "trace", "story-play", "story-pause", "story-seek", "fly-to", "zoom-to-feature", "show-overlay", "hide-overlay", "show-tooltip", "hide-tooltip", "draw-mode", "draw-commit", "draw-cancel", "draw-delete", "draw-clear", "draw-config", "draw-save", "set-basemap", "undo", "redo"];
19
19
  /** Hand-authored widget types — validated against the widget registry in html-data.test.ts. */
20
- export declare const BUILTIN_WIDGETS: readonly ["legend", "layer-switcher", "zoom-controls", "scale-bar", "attribution", "filter", "vega-lite", "player", "draw", "basemap-switcher"];
20
+ export declare const BUILTIN_WIDGETS: readonly ["legend", "layer-switcher", "zoom-controls", "scale-bar", "attribution", "filter", "vega-lite", "player", "draw", "basemap-switcher", "undo-redo"];
21
21
  export declare function buildHtmlCustomData(): {
22
22
  version: number;
23
23
  tags: TagData[];
package/dist/{index-COu-3-gN.js → index-BVQ0s1Zh.js} RENAMED
@@ -1,7 +1,7 @@
1
1
  var Oe = Object.defineProperty;
2
2
  var ke = (r, e, t) => e in r ? Oe(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
3
3
  var l = (r, e, t) => ke(r, typeof e != "symbol" ? e + "" : e, t);
4
- import { g as ve, a as ce, b as he, i as Fe, t as je, l as xe } from "./index-CvfuISOc.js";
4
+ import { g as ve, a as ce, b as he, i as Fe, t as je, l as xe } from "./index-BxzDKZpu.js";
5
5
  import { ai as Ie, h as ue, au as X, a2 as W, af as fe, Y as Ne, F as Le, aR as Ue, S as Me, bP as qe } from "./recordbatch-HRu0SMKp.js";
6
6
  import { g as $, a as de, b as Ve, c as $e, d as Pe, e as He, m as ze } from "./table-accessors-DBjWgN0C.js";
7
7
  import { c as Qe } from "./convert-arrow-schema-CvZ3cT5m.js";