@nika-js/onlymap 0.7.6 → 0.8.1

package/dist/cartograph/schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cartograph vocabulary — the SINGLE SOURCE for which attributes each element
+ * accepts (spec: docs/cartograph.md; issue onlymap-js#41).
+ *
+ * This module is the RUNTIME half: attribute rosters, format and theme names,
+ * page presets, the inert-reserved map. The elements derive their
+ * `observedAttributes` from it and the validator checks against it.
+ *
+ * The human-readable half — every attribute's description, for editor
+ * IntelliSense — lives in ./html-data.ts and is NOT imported here, so
+ * documentation strings never ship in the runtime bundle. (The core makes the
+ * same split: src/index.ts never imports src/html-data.ts.) The html-data test
+ * asserts every attribute rostered here is described there, so the two halves
+ * cannot drift.
+ *
+ * PURITY RULE: data only — no DOM, no imports from the core entry.
+ */
+/** The document format identifier carried by `<om-cartograph format=>`. */
+export declare const CARTOGRAPH_FORMAT = "cartograph/2";
+/** Built-in theme ids (ported 1:1 from NIKA's BUILTIN_THEMES — cartograph.css). */
+export declare const CARTOGRAPH_THEMES: readonly ["default", "dark", "sepia", "blueprint", "minimal"];
+/** Page presets, portrait mm. The runtime treats unknown `size` as A4; the validator flags it. */
+export declare const PAGE_SIZE_NAMES: readonly ["A0", "A1", "A2", "A3", "A4", "A5", "Letter", "Legal"];
+/**
+ * Reserved-but-unbuilt attributes, keyed attribute name → reason. Mirrors
+ * the core's INERT_RESERVED_ATTRS pattern (attribute-resolution.ts — which
+ * is layer-specific and untouched by the cartograph): the validator warns
+ * "has no effect: <reason>" instead of staying silent. Implementing one of
+ * these means deleting its entry in the same commit.
+ */
+export declare const INERT_RESERVED_CARTOGRAPH_ATTRS: ReadonlyMap<string, string>;
+/**
+ * Placement attributes shared by every placed element (everything except
+ * `<om-cartograph>` and `<om-atlas>`). Millimetres from the page's top-left.
+ */
+export declare const PLACED_ATTR_NAMES: readonly ["id", "x", "y", "w", "h", "rotation", "z", "locked", "hidden"];
+export declare const CARTOGRAPH_ELEMENT_ATTRS: Record<string, readonly string[]>;
+export declare const CARTOGRAPH_TAG_NAMES: readonly string[];

package/dist/cartograph/standalone.d.ts

@@ -0,0 +1 @@
+export * from "./api";

package/dist/cartograph/textlayout.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared text line-boxing — ONE wrapping implementation, used by both the DOM
+ * renderer and the canvas exporter.
+ *
+ * Why not let the browser wrap in the DOM and re-wrap independently on canvas:
+ * the two would disagree at the margins (different rounding, different
+ * measurement paths), so a PNG export and the printed PDF of the same page
+ * would break lines in different places. Computing the line boxes once and
+ * having both renderers draw THOSE gives parity by construction.
+ *
+ * Deliberately simple: greedy word wrap on whitespace, with a hard break for
+ * words longer than the line. No hyphenation, no bidi reordering — a
+ * cartograph title is a short phrase, not a paragraph of prose. When no text
+ * measurer is available (node, no canvas), `layoutText` returns null and
+ * callers fall back to natural flow.
+ */
+export interface TextLine {
+    text: string;
+    /** Baseline offset from the block's top, in the same units the measurer uses. */
+    baselineY: number;
+    width: number;
+}
+export interface TextLayout {
+    lines: TextLine[];
+    lineHeight: number;
+    /** Widest line — callers use it for alignment and overflow checks. */
+    maxWidth: number;
+}
+export interface LayoutTextOptions {
+    text: string;
+    /** Available width in CSS px; Infinity disables wrapping. */
+    maxWidth: number;
+    fontSizePx: number;
+    lineHeightPx: number;
+    measure: (text: string) => number;
+}
+/**
+ * Wrap `text` into line boxes. Explicit newlines always break; runs of other
+ * whitespace collapse, matching how the DOM renders the same content.
+ */
+export declare function layoutText({ text, maxWidth, fontSizePx, lineHeightPx, measure }: LayoutTextOptions): TextLayout;
+/** A measurer backed by a 2D canvas, or null where none exists (node/SSR). */
+export declare function canvasMeasurer(font: string): ((text: string) => number) | null;
+/** Horizontal offset for a line inside a box, given the CSS text-align value. */
+export declare function alignOffset(align: string, boxWidth: number, lineWidth: number): number;

package/dist/cartograph/tokens.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `{{token}}` substitution for cartograph text.
+ *
+ * SECURITY CONTRACT: substitution is TEXT-NODE ONLY. Token values come from
+ * map data (a feature's fields, via the atlas) and from authored attributes;
+ * routing them through innerHTML would make a GeoJSON property containing
+ * markup into live DOM on any page displaying a third-party cartograph. Every
+ * value lands in a text node's `data`, never parsed as HTML.
+ *
+ * Resolution order (design §3.4): atlas feature → frame → cartograph. Unknown
+ * tokens render literally and are reported by the validator, so a typo is
+ * visible on the page rather than silently blank.
+ */
+export interface FrameTokenValues {
+    /** Representative-fraction denominator, formatted for print. */
+    scale?: string;
+    crs?: string;
+}
+export interface TokenContext {
+    /** Cartograph-level values: title, date, attribution, notes, … */
+    page: Record<string, string>;
+    /** Per-frame values, keyed by frame id — reached as {{frame.<id>.scale}}. */
+    frames?: Map<string, FrameTokenValues>;
+    /** The single frame bare {{scale}}/{{crs}} bind to, when the page has exactly one. */
+    soleFrameId?: string | null;
+    /** Atlas feature fields, reached as {{atlas.<field>}} (Phase 4). */
+    atlas?: Record<string, string>;
+}
+/** Resolve one token name, or undefined when nothing provides it. */
+export declare function resolveToken(name: string, ctx: TokenContext): string | undefined;
+export interface TokenResult {
+    text: string;
+    /** Token names nothing resolved — rendered literally, reported by the validator. */
+    unresolved: string[];
+}
+export declare function resolveTokens(template: string, ctx: TokenContext): TokenResult;
+/** Every token name appearing in a template (for validation). */
+export declare function tokensIn(template: string): string[];
+/**
+ * Substitute tokens in every text node under `root`, in place. Returns the
+ * token names that went unresolved.
+ */
+export declare function applyTokens(root: Node, ctx: TokenContext): string[];
+/** Today's date in ISO form — the default `{{date}}` value. */
+export declare function isoDate(now?: Date): string;

package/dist/cartograph/url-actions.d.ts

@@ -0,0 +1,26 @@
+import type { OmCartographElement } from "./elements/om-cartograph";
+/** How long to wait for frames and fonts before acting anyway. */
+export declare const URL_ACTION_TIMEOUT_MS = 30000;
+/**
+ * Resolves when every frame has settled and fonts are loaded — or when the
+ * timeout expires, which is deliberate: a dead raster URL must degrade to a
+ * page with a visible error placeholder, not hang forever with no output.
+ */
+export declare function whenPageReady(page: Element, timeoutMs?: number): Promise<{
+    timedOut: boolean;
+}>;
+export interface UrlActionOptions {
+    /** Defaults to the page's own location. */
+    search?: string;
+    timeoutMs?: number;
+}
+/**
+ * Apply whatever the URL asks of this cartograph. Returns the action taken,
+ * or null when there was nothing to do (or the page did not opt in).
+ */
+export declare function applyUrlActions(page: OmCartographElement, options?: UrlActionOptions): Promise<"print" | "export" | "cvd" | null>;
+/**
+ * Install the triggers once the document is parsed. Called by the entry; a
+ * page with no `allow-url-actions` cartograph does nothing at all.
+ */
+export declare function installUrlActions(): void;

package/dist/cartograph/validate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cartograph validation (spec: docs/cartograph.md; design §3.7).
+ *
+ * Returns the CORE validator's `ValidationResult` shape so a host folds
+ * cartograph diagnostics into agent tool results with exactly the code it
+ * already uses for map manifests. The types are `import type` only — erased at
+ * compile time — because src/validation.ts transitively imports every deck.gl
+ * layer package, and pulling that in would break the cartograph entry's
+ * lazy-core rule (the CI bundle gate would fail the build).
+ *
+ * SYNCHRONOUS AND HEADLESS by design: hosts validate on every agent write, so
+ * it must run in node over a parsed document with no element upgrade and no
+ * renderer. That is also why inline `<om-map>` manifests are NOT deep-validated
+ * here — delegating would require loading the core. Phase 2 adds an async
+ * `validateCartographDeep()` for hosts that already have the core loaded.
+ */
+import type { ValidationResult } from "../validation";
+/**
+ * Validate a parsed cartograph document (or a bare `<om-cartograph>` element).
+ */
+export declare function validateCartograph(root: ParentNode): ValidationResult;
+/** Validate a cartograph HTML string. Needs a DOM implementation for DOMParser. */
+export declare function validateCartographString(html: string): ValidationResult;
+/**
+ * Everything `validateCartograph` checks, PLUS the inline `<om-map>` manifests,
+ * delegated to the core validator.
+ *
+ * Separate and async because the core validator's import graph reaches every
+ * deck.gl layer package: pulling it into the synchronous path would break the
+ * lazy-core rule and load the whole map runtime just to check a document. Hosts
+ * that already have the core loaded (the NIKA editor) use this; hosts that
+ * validate on every agent write (a file-write hook, the QGIS plugin) use the
+ * sync form and stay cheap.
+ *
+ * Entries from an inline manifest are prefixed with their frame, so a host can
+ * tell "the cartograph is malformed" from "the map inside frame #main is".
+ */
+export declare function validateCartographDeep(root: ParentNode): Promise<ValidationResult>;

package/dist/cartograph/zip.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A minimal ZIP writer (STORE method — no compression).
+ *
+ * An atlas export is N pages, and browsers block or prompt on a loop of N
+ * downloads, so the export has to hand back ONE file. PNGs are already
+ * deflate-compressed internally, so storing them uncompressed costs almost
+ * nothing and saves pulling a compression library into a bundle whose whole
+ * premise is staying small.
+ *
+ * Deliberately not a general zip implementation: no directories, no zip64, no
+ * unicode path extras beyond UTF-8 names with the language-encoding flag set.
+ */
+export interface ZipFile {
+    name: string;
+    data: Blob | Uint8Array;
+}
+/**
+ * Build a ZIP archive. `modified` is a parameter so a caller that needs a
+ * byte-reproducible archive can pin it — the timestamp is otherwise the one
+ * part of the output that changes between runs.
+ */
+export declare function createZip(files: readonly ZipFile[], modified?: Date): Promise<Blob>;

package/dist/cartograph.css

@@ -0,0 +1 @@
+om-cartograph{--om-carto-bg: #fbf8fb;--om-carto-ink: #6d5b72;--om-carto-font: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;--om-carto-title-ink: #2a1f2d;--om-carto-title-font: var(--om-carto-font);--om-carto-title-weight: 600;--om-carto-attr-ink: #8b7890;--om-carto-legend-bg: #fbf8fb;--om-carto-legend-border: #dfd0df;--om-carto-legend-title-ink: #2a1f2d;--om-carto-frame-stroke: #2a1f2d;--om-carto-frame-bg: #f1ebf1;--om-carto-compass-ink: #2a1f2d;--om-carto-scalebar-ink: #2a1f2d;--om-carto-shape-fill: #f0d9a5;--om-carto-shape-stroke: #2a1f2d;--om-carto-graticule-ink: #ffffff;display:block;position:relative;overflow:hidden;background:var(--om-carto-bg);color:var(--om-carto-ink);font-family:var(--om-carto-font);box-sizing:border-box}om-cartograph[theme=dark]{--om-carto-bg: #261a29;--om-carto-ink: #d7bfb5;--om-carto-title-ink: #f7ece6;--om-carto-attr-ink: #b996a6;--om-carto-legend-bg: #2f2134;--om-carto-legend-border: #4b3450;--om-carto-legend-title-ink: #f7ece6;--om-carto-frame-stroke: #4b3450;--om-carto-frame-bg: #2f2134;--om-carto-compass-ink: #f7ece6;--om-carto-scalebar-ink: #f7ece6;--om-carto-shape-fill: #3b2a41;--om-carto-shape-stroke: #f7ece6;--om-carto-graticule-ink: #ffffff}om-cartograph[theme=sepia]{--om-carto-bg: #f4ead5;--om-carto-ink: #3a2c1a;--om-carto-font: "Iowan Old Style", "Palatino Linotype", Palatino, "Hoefler Text", Georgia, serif;--om-carto-title-ink: #2a1f0e;--om-carto-title-weight: 700;--om-carto-attr-ink: #6b5638;--om-carto-legend-bg: #fbf4e3;--om-carto-legend-border: #a78a5a;--om-carto-legend-title-ink: #3a2c1a;--om-carto-frame-stroke: #5c4528;--om-carto-frame-bg: #e8dcc1;--om-carto-compass-ink: #5c4528;--om-carto-scalebar-ink: #3a2c1a;--om-carto-shape-fill: #e8dcc1;--om-carto-shape-stroke: #5c4528;--om-carto-graticule-ink: #5c4528}om-cartograph[theme=blueprint]{--om-carto-bg: #0d2e5c;--om-carto-ink: #cfe3ff;--om-carto-title-ink: #ffffff;--om-carto-attr-ink: #7fa6da;--om-carto-legend-bg: #11366b;--om-carto-legend-border: #5d8dc5;--om-carto-legend-title-ink: #ffffff;--om-carto-frame-stroke: #cfe3ff;--om-carto-frame-bg: #11366b;--om-carto-compass-ink: #cfe3ff;--om-carto-scalebar-ink: #cfe3ff;--om-carto-shape-fill: #11366b;--om-carto-shape-stroke: #cfe3ff;--om-carto-graticule-ink: #cfe3ff}om-cartograph[theme=minimal]{--om-carto-bg: #fafafa;--om-carto-ink: #444444;--om-carto-title-ink: #111111;--om-carto-title-weight: 500;--om-carto-attr-ink: #999999;--om-carto-legend-bg: #ffffff;--om-carto-legend-border: #e5e5e5;--om-carto-legend-title-ink: #222222;--om-carto-frame-stroke: #bbbbbb;--om-carto-frame-bg: #ffffff;--om-carto-compass-ink: #666666;--om-carto-scalebar-ink: #444444;--om-carto-shape-fill: #ffffff;--om-carto-shape-stroke: #999999;--om-carto-graticule-ink: #888888}om-text,om-frame,om-legend,om-scalebar,om-north,om-graticule,om-shape,om-image{display:block;position:absolute;box-sizing:border-box}om-text[hidden],om-cartograph [hidden]{display:none!important}om-legend-row{display:none!important}om-scalebar{color:var(--om-carto-scalebar-ink);font-family:var(--om-carto-font)}om-north{color:var(--om-carto-compass-ink);font-family:var(--om-carto-font)}om-graticule{color:var(--om-carto-graticule-ink)}om-legend{background:var(--om-carto-legend-bg);border:.2mm solid var(--om-carto-legend-border);color:var(--om-carto-ink)}om-frame{background:var(--om-carto-frame-bg);overflow:hidden}om-frame>img,om-image>img{display:block}om-frame>svg,om-scalebar>svg,om-north>svg,om-shape>svg,om-graticule>svg{display:block;overflow:visible}om-text[kind=title]{color:var(--om-carto-title-ink);font-family:var(--om-carto-title-font);font-weight:var(--om-carto-title-weight);font-size:18pt;line-height:1.2}om-text[kind=attribution]{color:var(--om-carto-attr-ink);font-size:6.5pt;line-height:1.4}om-text{font-size:10pt;line-height:1.4}@media print{[data-om-carto-screen-only]{display:none!important}om-cartograph{margin:0;box-shadow:none;filter:none!important}}om-cartograph:not(:defined){display:block;position:relative;min-height:240px;background:#fff;border:1px solid #d1d5db;color:#374151;font:14px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;overflow:hidden}om-cartograph:not(:defined)>:not(om-text):not(om-frame):not(om-image):not(om-shape){display:none!important}om-cartograph:not(:defined) om-text{display:block;position:absolute}om-cartograph:not(:defined):after{content:"This cartograph requires JavaScript for its interactive map frames. Static content is shown as authored.";position:absolute;inset:auto 0 0;padding:8px 12px;font-size:11px;color:#6b7280;text-align:center;opacity:0;animation:om-carto-fallback-reveal .3s ease .4s forwards}@media(scripting:enabled){om-cartograph:not(:defined):after{content:"This cartograph is taking too long to load. Its JavaScript may be blocked or unreachable — check the connection, then reload the page.";animation-delay:4s}}@media(scripting:none){om-cartograph:not(:defined):after{opacity:1;animation:none}}@keyframes om-carto-fallback-reveal{to{opacity:1}}