@navaramap/three 0.0.0

package/src/plugins/AttributionPlugin/attribution.ts

@@ -0,0 +1,355 @@
+/**
+ * Attribution data model and framework-agnostic helpers.
+ *
+ * This module imports **nothing from the engine (WASM)**, so the pure logic
+ * (type guards, zoom-band matching, HTML sanitization) is unit-testable without
+ * loading it. The `AttributionPlugin` class composes these.
+ */
+
+/**
+ * A single zoom-banded child credit under a top-level source. The band
+ * `[minZoom, maxZoom]` is matched against the current camera zoom; an omitted
+ * bound is unbounded on that side.
+ */
+export type AttributionChild = {
+  /** Attribution / credit text. May contain partial `<a>` links. */
+  attribution: string;
+  /** Inclusive lower zoom bound. Unbounded when omitted. */
+  minZoom?: number;
+  /** Inclusive upper zoom bound. Unbounded when omitted. */
+  maxZoom?: number;
+};
+
+/**
+ * A top-level source (provider). It may carry zoom-banded child credits
+ * (`children`), a mandated `logo`, and dynamic per-layer credits linked via
+ * `creditLayerId`.
+ */
+export type AttributionSource = {
+  /** Top-level source / provider name. */
+  attribution: string;
+  /** Optional link for the source name, rendered as an `<a>`. */
+  attributionUrl?: string;
+  /**
+   * Optional logo image URL. When set, the logo is shown in an always-visible
+   * frame in the bottom-left corner, independent of the popover's open state —
+   * as required for contractually-mandated marks (Google, Cesium ion, etc.).
+   * The logo is linked only when {@link logoUrl} is set; otherwise it is a plain
+   * image (e.g. a mark that must be shown but not turned into a link).
+   */
+  logo?: string;
+  /**
+   * Optional click target for the {@link logo}, opened in a new tab. Kept
+   * separate from {@link attributionUrl} (the title's link) so a provider can
+   * require the logo be shown without linking it, or point the logo somewhere
+   * other than the title. Has no effect unless {@link logo} is also set.
+   */
+  logoUrl?: string;
+  /** Zoom-banded child credits, filtered by current camera zoom. */
+  children?: AttributionChild[];
+  /**
+   * Optional id (`layer.id`) of the tracked layer whose per-feature credits are
+   * nested under this source. Named `creditLayerId` rather than `layerId`
+   * because "layer" alone is ambiguous in this project. A plain string (not a
+   * `Layer`) keeps `attribution.ts` engine-free.
+   */
+  creditLayerId?: string;
+};
+
+/**
+ * Customizable colors for the attribution UI. Every field is optional; an unset
+ * field keeps the built-in default. Applied as CSS custom properties, so
+ * {@link AttributionPlugin.setStyle} can re-theme live (e.g. light ⇄ dark)
+ * without rebuilding the DOM.
+ */
+export type AttributionStyle = {
+  /** Source title text color. */
+  titleColor?: string;
+  /** Link (`<a>`) and info-icon color. */
+  linkColor?: string;
+  /** Bullet (list marker) color. */
+  listStyleColor?: string;
+  /** Body text color. */
+  textColor?: string;
+  /** Nested sub-credit text color. */
+  nestedTextColor?: string;
+  /** Popover and trigger background color. */
+  backgroundColor?: string;
+  /** Header divider (border) color — useful for dark themes. */
+  borderColor?: string;
+};
+
+/** A raw HTML credit with partial links, rendered as-is (after sanitization). */
+export type AttributionHtml = {
+  /** Credit HTML containing partial `<a>` links. */
+  attributionHtml: string;
+};
+
+/** An attribution entry: either a structured source or a raw HTML credit. */
+export type AttributionItem = AttributionSource | AttributionHtml;
+
+/** Type guard distinguishing a raw HTML credit from a structured source. */
+export function isAttributionHtml(
+  item: AttributionItem,
+): item is AttributionHtml {
+  return "attributionHtml" in item;
+}
+
+/**
+ * Stable identity of an item for deduplication: everything that affects how it
+ * renders. Sources that differ in `creditLayerId` or `children` produce
+ * different keys, so distinct per-layer / zoom-banded credits are preserved.
+ */
+export function attributionItemKey(item: AttributionItem): string {
+  if (isAttributionHtml(item)) {
+    return JSON.stringify(["html", item.attributionHtml]);
+  }
+  // Explicit, ordered field list so JSON.stringify yields a collision-free key.
+  return JSON.stringify([
+    "src",
+    item.attribution,
+    item.attributionUrl ?? null,
+    item.logo ?? null,
+    item.logoUrl ?? null,
+    item.creditLayerId ?? null,
+    (item.children ?? []).map((c) => [
+      c.attribution,
+      c.minZoom ?? null,
+      c.maxZoom ?? null,
+    ]),
+  ]);
+}
+
+/**
+ * Drop exact-duplicate entries, preserving first-seen order. Two items are
+ * duplicates only when they would render identically (same text, link, logo,
+ * tracked layer, and zoom-banded children).
+ *
+ * Callers often list several distinct data sources that happen to share one
+ * credit (e.g. multiple Overture themes); without this the same line would
+ * render once per source.
+ */
+export function dedupeAttributionItems(
+  items: AttributionItem[],
+): AttributionItem[] {
+  const seen = new Set<string>();
+  const result: AttributionItem[] = [];
+  for (const item of items) {
+    const key = attributionItemKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}
+
+/**
+ * Aggregate `;`-separated credit strings (e.g. a 3D-tile's `asset.copyright`)
+ * into a deduplicated list, ordered by frequency (desc) with a deterministic
+ * code-point tie-break, so the order is stable across updates and environments.
+ *
+ * The `;` split is **HTML-aware** (see {@link splitCredits}): a `;` inside an
+ * `<a href>` or an HTML entity is never treated as a delimiter, so attribution
+ * URLs and links are preserved verbatim — a license notice must not be altered.
+ */
+export function aggregateCredits(creditStrings: Iterable<string>): string[] {
+  const counts = new Map<string, number>();
+  for (const raw of creditStrings) {
+    for (const credit of splitCredits(raw)) {
+      counts.set(credit, (counts.get(credit) ?? 0) + 1);
+    }
+  }
+  return Array.from(counts.entries())
+    .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([credit]) => credit);
+}
+
+/** Escape text so it round-trips faithfully back through HTML parsing. */
+function escapeHtmlText(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Split a raw credit on the `;` delimiter (the glTF / Cesium `asset.copyright`
+ * convention) **without breaking HTML**. The string is parsed first, so a `;`
+ * inside an `<a href>` or an HTML entity is not a delimiter and links / URLs
+ * stay intact. Each returned segment is a trimmed HTML string (empties
+ * dropped); plain-text segments are escaped so they survive re-parsing.
+ *
+ * Note: a literal `;` in plain (non-HTML) text is still a delimiter — the
+ * convention can't represent a credit that itself contains an unescaped `;`.
+ */
+function splitCredits(raw: string): string[] {
+  const doc = new DOMParser().parseFromString(raw, "text/html");
+  const segments: string[] = [];
+  let current = "";
+  const flush = (): void => {
+    const trimmed = current.trim();
+    if (trimmed) segments.push(trimmed);
+    current = "";
+  };
+  const walk = (parent: Node): void => {
+    parent.childNodes.forEach((node) => {
+      if (node instanceof Text) {
+        const parts = (node.textContent ?? "").split(";");
+        parts.forEach((part, i) => {
+          if (i > 0) flush();
+          current += escapeHtmlText(part);
+        });
+        return;
+      }
+      if (node instanceof HTMLAnchorElement) {
+        // Keep `<a>` atomic so a `;` inside its href/text isn't a delimiter.
+        current += node.outerHTML;
+        return;
+      }
+      if (node instanceof Element) {
+        // Other tags are dropped by the sanitizer anyway — recurse into their
+        // children so a `;` inside still splits and the tag doesn't end up in
+        // the dedup key.
+        walk(node);
+      }
+    });
+  };
+  walk(doc.body);
+  flush();
+  return segments;
+}
+
+/**
+ * Whether a child credit applies at the given integer zoom level. A missing
+ * bound is unbounded on that side; a missing level (undef) matches everything.
+ */
+export function matchesZoom(
+  child: AttributionChild,
+  level: number | undefined,
+): boolean {
+  if (level === undefined) return true;
+  if (child.minZoom !== undefined && level < child.minZoom) return false;
+  if (child.maxZoom !== undefined && level > child.maxZoom) return false;
+  return true;
+}
+
+/**
+ * Returns `href` if it points to a safe location (http / https / mailto, or a
+ * relative URL), otherwise `undefined`. Blocks code-executing schemes such as
+ * `javascript:` and `data:` to prevent XSS via attribution links.
+ */
+export function safeHref(href: string): string | undefined {
+  let url: URL;
+  try {
+    // A fixed base resolves relative URLs; only the scheme matters here.
+    url = new URL(href, "http://localhost/");
+  } catch {
+    return undefined;
+  }
+  if (
+    url.protocol === "http:" ||
+    url.protocol === "https:" ||
+    url.protocol === "mailto:"
+  ) {
+    return href;
+  }
+  return undefined;
+}
+
+/**
+ * Create an `<a>` for an already-validated safe href with the standard
+ * external-link attributes. Centralizes `target`/`rel` so no call site forgets
+ * them. Pass `text` to set the visible label (omit to fill children manually).
+ */
+export function createSafeAnchor(
+  href: string,
+  text?: string,
+): HTMLAnchorElement {
+  const anchor = document.createElement("a");
+  anchor.href = href;
+  anchor.target = "_blank";
+  anchor.rel = "noopener noreferrer";
+  if (text !== undefined) anchor.textContent = text;
+  return anchor;
+}
+
+/**
+ * Append a credit HTML string to `target`, allowing only `<a href>` elements
+ * with a safe scheme. Other tags (and unsafe links) are dropped while keeping
+ * their (sanitized) text content. Surviving links get `target="_blank"` and
+ * `rel="noopener noreferrer"`. Bare `http(s)` URLs in text are auto-linked too,
+ * so an official notice can be pasted verbatim without hand-wrapping its URL.
+ */
+export function appendSanitizedHtml(target: Node, html: string): void {
+  // Parse without a wrapper element: a wrapper would be closed early by a
+  // stray `</span>` in the input, dropping the nodes parsed after it (and thus
+  // silently omitting credits). Sanitizing the whole body keeps every node.
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  appendSanitizedChildren(target, doc.body);
+}
+
+function appendSanitizedChildren(
+  target: Node,
+  source: Node,
+  autolink = true,
+): void {
+  source.childNodes.forEach((node) => {
+    if (node instanceof Text) {
+      // Inside an existing `<a>`, emit plain text — never nest a link.
+      if (autolink) appendTextWithLinks(target, node.textContent ?? "");
+      else target.appendChild(document.createTextNode(node.textContent ?? ""));
+      return;
+    }
+    if (node instanceof HTMLAnchorElement) {
+      const raw = node.getAttribute("href");
+      const href = raw ? safeHref(raw) : undefined;
+      if (!href) {
+        // Unsafe / missing href: drop the link, keep its text.
+        appendSanitizedChildren(target, node, autolink);
+        return;
+      }
+      const anchor = createSafeAnchor(href);
+      appendSanitizedChildren(anchor, node, false);
+      target.appendChild(anchor);
+      return;
+    }
+    if (node instanceof Element) {
+      // Drop the tag, keep its sanitized contents.
+      appendSanitizedChildren(target, node, autolink);
+    }
+  });
+}
+
+/** Matches an explicit http(s) URL, used to auto-link bare URLs in credit text. */
+const BARE_URL_PATTERN = /https?:\/\/[^\s]+/g;
+/** Trailing punctuation kept outside an auto-linked URL (e.g. a closing paren). */
+const TRAILING_PUNCTUATION = /[.,;:!?)\]}'"]+$/;
+
+/**
+ * Append `text` to `target`, turning bare http(s) URLs into links. This lets an
+ * attribution be pasted verbatim (no hand-inserted `<a>`, which would itself
+ * edit the notice) while its URL stays both faithful and clickable: the URL
+ * text is preserved exactly and only trailing sentence punctuation is left out.
+ */
+function appendTextWithLinks(target: Node, text: string): void {
+  let lastIndex = 0;
+  for (const match of text.matchAll(BARE_URL_PATTERN)) {
+    const start = match.index ?? 0;
+    let url = match[0];
+    const trailing = url.match(TRAILING_PUNCTUATION);
+    if (trailing) url = url.slice(0, url.length - trailing[0].length);
+    if (start > lastIndex) {
+      target.appendChild(document.createTextNode(text.slice(lastIndex, start)));
+    }
+    const href = safeHref(url);
+    if (href) {
+      target.appendChild(createSafeAnchor(href, url));
+    } else {
+      target.appendChild(document.createTextNode(url));
+    }
+    lastIndex = start + url.length;
+  }
+  if (lastIndex < text.length) {
+    target.appendChild(document.createTextNode(text.slice(lastIndex)));
+  }
+}

package/src/plugins/AttributionPlugin/attributionStyles.ts

@@ -0,0 +1,163 @@
+/**
+ * Presentation constants for {@link AttributionPlugin}: the shared `<style>`
+ * element id, the ⓘ trigger icon markup, and the popover CSS. Extracted so the
+ * bulky CSS string doesn't dominate the plugin class file.
+ */
+
+/** Shared `<style>` element id; reference-counted by the plugin. */
+export const STYLE_ELEMENT_ID = "navara-attribution-styles";
+
+/**
+ * ⓘ trigger icon as a markup string, inserted via `innerHTML` so the icon can
+ * be swapped in one place. `currentColor` makes it follow the button's color.
+ */
+export const SVG_ICON_HTML = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+  <circle cx="12" cy="12" r="10.5" stroke="currentColor" stroke-width="2" />
+  <circle cx="12" cy="8" r="1" fill="currentColor" />
+  <rect x="11" y="11" width="2" height="6" rx="1" fill="currentColor" />
+</svg>`;
+
+export const STYLE_TEXT = `
+.navara-attr-dock {
+  position: fixed;
+  right: 8px;
+  bottom: 8px;
+  z-index: 1000;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 10px;
+  font-family: system-ui, sans-serif;
+}
+.navara-attr-dock--left {
+  right: auto;
+  left: 8px;
+  align-items: flex-start;
+}
+.navara-attr-logoframe {
+  position: fixed;
+  left: 8px;
+  bottom: 8px;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+/* Bottom-left mode: the ⓘ trigger (24px) occupies the far-left corner, so the
+   logo frame starts to its right, keeping the two in a single row. */
+.navara-attr-logoframe--left {
+  left: 40px;
+}
+.navara-attr-logo {
+  height: 24px;
+  width: auto;
+  display: block;
+  user-select: none;
+}
+.navara-attr-toggle {
+  width: 24px;
+  height: 24px;
+  min-width: 24px;
+  padding: 0;
+  border-radius: 50%;
+  cursor: pointer;
+  background: var(--nvr-attr-bg, rgba(252, 253, 254, 0.92));
+  border: 1px solid var(--nvr-attr-border, rgba(0, 0, 0, 0.1));
+  box-shadow: 0 2px 8px rgba(20, 24, 28, 0.16);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--nvr-attr-link, #3a6595);
+}
+.navara-attr-toggle svg {
+  width: 16px;
+  height: 16px;
+  display: block;
+}
+.navara-attr-card {
+  width: 280px;
+  max-width: calc(100vw - 16px);
+  max-height: 340px;
+  overflow-y: auto;
+  background: var(--nvr-attr-bg, rgba(252, 253, 254, 0.96));
+  border-radius: 14px;
+  box-shadow: 0 10px 30px rgba(20, 24, 28, 0.16);
+  color: var(--nvr-attr-text, #1b1f24);
+}
+.navara-attr-card[hidden] {
+  display: none;
+}
+/* display:flex on these beats the UA [hidden] rule, so hide explicitly. */
+.navara-attr-dock[hidden],
+.navara-attr-logoframe[hidden] {
+  display: none;
+}
+.navara-attr-head {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 12px;
+  border-bottom: 1px solid var(--nvr-attr-border, rgba(0, 0, 0, 0.08));
+}
+.navara-attr-head h3 {
+  margin: 0;
+  font-size: 13.5px;
+  font-weight: 600;
+  color: var(--nvr-attr-title, inherit);
+}
+.navara-attr-close {
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  font-size: 15px;
+  line-height: 1;
+  color: var(--nvr-attr-nested, rgba(27, 31, 36, 0.64));
+  padding: 2px 4px;
+}
+.navara-attr-list {
+  list-style: none;
+  margin: 0;
+  padding: 12px;
+}
+.navara-attr-item + .navara-attr-item {
+  margin-top: 15px;
+}
+.navara-attr-name {
+  display: flex;
+  gap: 8px;
+  font-size: 13px;
+  font-weight: 500;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
+.navara-attr-bullet {
+  width: 5px;
+  height: 5px;
+  border-radius: 50%;
+  background: var(--nvr-attr-bullet, #3a6595);
+  flex: none;
+  margin-top: 6px;
+}
+.navara-attr-related {
+  list-style: none;
+  margin: 5px 0 0 13px;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+}
+.navara-attr-related li {
+  font-size: 12px;
+  color: var(--nvr-attr-nested, rgba(27, 31, 36, 0.64));
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
+.navara-attr-card a {
+  color: var(--nvr-attr-link, #3a6595);
+  text-decoration: none;
+}
+.navara-attr-card a:hover {
+  text-decoration: underline;
+}
+`;