@nika-js/onlymap 0.7.6 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "Declarative deck.gl maps for HTML and React — interactive WebGL mapping with GeoJSON/CSV/Arrow data, MapLibre basemaps, widgets, popups, and live streams from a custom-element manifest or typed React components. TypeScript, no build step.",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
@@ -74,6 +74,17 @@
       "import": "./dist/onlymap.standalone.js",
       "default": "./dist/onlymap.standalone.js"
     },
+    "./cartograph": {
+      "types": "./dist/cartograph/index.d.ts",
+      "import": "./dist/cartograph.js",
+      "default": "./dist/cartograph.js"
+    },
+    "./cartograph/standalone": {
+      "types": "./dist/cartograph/standalone.d.ts",
+      "import": "./dist/cartograph.standalone.js",
+      "default": "./dist/cartograph.standalone.js"
+    },
+    "./cartograph.css": "./dist/cartograph.css",
     "./onlymapjs.css": "./dist/onlymapjs.css",
     "./style.css": "./dist/style.css",
     "./onlymapjs.html-data.json": "./onlymapjs.html-data.json",
@@ -108,7 +119,7 @@
   ],
   "scripts": {
     "dev": "vite",
-    "build": "npm run typecheck && npm run gen:licenses && vite build && vite build --config vite.react.config.ts && vite build --config vite.deck.config.ts && vite build --config vite.standalone.config.ts && node dev/assert-bundle-cdn-safe.mjs && npm run build:types",
+    "build": "npm run typecheck && npm run gen:licenses && vite build && vite build --config vite.react.config.ts && vite build --config vite.deck.config.ts && vite build --config vite.standalone.config.ts && vite build --config vite.cartograph.config.ts && vite build --config vite.cartograph-standalone.config.ts && node dev/assert-bundle-cdn-safe.mjs && npm run build:types",
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.e2e.json --noEmit && tsc -p cloud/workers/telemetry/tsconfig.json && tsc -p cloud/workers/examples/tsconfig.json",
     "test": "vitest run",

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, a map page shared as a single HTML file (incl. no-JS fallbacks for chat/email previews), a responsive/mobile map whose controls auto-fold on narrow screens, auditing a map's widget layout with the check-layout tool, syncing OnlyMapJS map/camera state into an app state store (Redux, MobX, Zustand, Jotai — the getStore contract), BIM/IFC models (loading .ifc files in the browser, 3D Tiles per-element picking, isolate/hide/ghost, clash detection, model federation), routes and directions (a styled A-to-B route line, OSRM or another routing engine, click-to-route), live vehicle/rider/delivery tracking (a moving marker gliding between GPS fixes with a follow camera), a React Native or Expo mobile map (route to the separate @nika-js/onlymap-native package), a Remotion map video or programmatic map flyover with overlays (route to the separate @nika-js/onlymap-remotion package), 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), a print-ready map sheet / PDF map / atlas (the cartograph entry: mm-based pages, frames, derived legends, scale bars, graticules), a responsive/mobile map whose controls auto-fold on narrow screens, auditing a map's widget layout with the check-layout tool, syncing OnlyMapJS map/camera state into an app state store (Redux, MobX, Zustand, Jotai — the getStore contract), BIM/IFC models (loading .ifc files in the browser, 3D Tiles per-element picking, isolate/hide/ghost, clash detection, model federation), routes and directions (a styled A-to-B route line, OSRM or another routing engine, click-to-route), live vehicle/rider/delivery tracking (a moving marker gliding between GPS fixes with a follow camera), a Remotion map video or programmatic map flyover with overlays (route to the separate @nika-js/onlymap-remotion package), a React Native or Expo mobile map (route to the separate @nika-js/onlymap-native package), or help with OnlyMapJS syntax, validation, widgets, data formats, testing, or publishing examples.
 ---
 
 # OnlyMapJS
@@ -23,7 +23,7 @@ Use OnlyMapJS as a declarative HTML map library. Write custom elements such as `
 </script>
 ```
 
-For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.7.5` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.7.5/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
+For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.8.0` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.8.0/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
 
 ## React Projects
 

package/skills/onlymapjs/references/syntax.md

@@ -16,8 +16,8 @@ Vite/npm project:
 Static CDN page (raw-file CDNs only — unpkg/jsDelivr; never esm.sh or another rebundling CDN, which duplicates the WebGL runtime and breaks layer shaders):
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.7.5/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.7.5"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.8.0/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.8.0"></script>
 ```
 
 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).
@@ -622,6 +622,30 @@ Example:
 
 
 
+### Cartographs (`@nika-js/onlymap/cartograph` — print layouts)
+
+A separate lazy entry (`import "@nika-js/onlymap/cartograph"`; CDN: `https://unpkg.com/@nika-js/onlymap/dist/cartograph.standalone.js`). Pages are measured in millimetres and print at true size.
+
+```html
+<om-cartograph size="A3" orientation="landscape" title="Parcel survey" dpi="300">
+  <om-text kind="title" x="10" y="8" w="250" h="12">{{title}}</om-text>
+  <om-frame id="main" x="24" y="28" w="236" h="196" center="[103.81, 1.31]" zoom="14.4">
+    <om-map basemap="none">…layers…</om-map>
+  </om-frame>
+  <om-legend for="main" x="270" y="84" w="60" h="62" title="Legend"></om-legend>
+  <om-scalebar for="main" x="10" y="230" w="72" h="10" units="metric"></om-scalebar>
+  <om-north for="main" x="238" y="226" w="16" h="18" kind="rose"></om-north>
+  <om-graticule for="main" x="24" y="28" w="236" h="196" interval="0.005" labels="outside"></om-graticule>
+</om-cartograph>
+```
+
+- Frames: live (`<om-map>` child, the FRAME's camera attributes win) or `mode="static"` with `crs` + `corners` for a georeferenced raster. `overview-of="<frame-id>"` draws a locator footprint.
+- `<om-legend for>` derives rows from the live map's own symbology (classified breaks included); literal rows via `derived="false"` + `<om-legend-row>` children.
+- `<om-atlas for="<frame-id>" layer="<layer-id>">` renders one page per feature sequentially and exports a ZIP.
+- Output: `page.print()` / `?print=1` (PDF at page size), `renderCartograph(page, {dpi})` / `?export=png&dpi=300` (PNG). Press attributes: `bleed`, `crop-marks`, `safe-zone` (screen-only), `flatten`. `cvd="deuteranopia|…"` simulates colour-vision deficiency; `lintLegendColours()` flags collapsing palettes.
+- Free plan injects a small foot credit — suppressed by an authored `om-text` crediting OnlyMap or a paid key on a live frame's map.
+- Deep reference: `docs/cartograph.md`.
+
 ### `<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.