@santi020k/lumen-core 3.0.0 → 4.0.0

package/dist/world-map-navigation.d.ts

@@ -0,0 +1,16 @@
+export interface WorldMapZoomAnchor {
+    x: number;
+    y: number;
+}
+interface MapBounds extends WorldMapZoomAnchor {
+    width: number;
+    height: number;
+}
+/** Map geometry uses a left origin; RTL browser scroll offsets use the right edge. */
+export declare const readMapScrollLeft: (viewport: HTMLElement) => number;
+export declare const writeMapScrollLeft: (viewport: HTMLElement, value: number) => void;
+export declare const getHighlightedMapBounds: (root: HTMLElement) => MapBounds | undefined;
+export declare const fitHighlightedMap: (root: HTMLElement, viewport: HTMLElement, update: (zoom: number) => void) => void;
+export declare const initMapWheelZoom: (viewport: HTMLElement, getZoom: () => number, update: (value: number, anchor: WorldMapZoomAnchor) => void, signal: AbortSignal) => void;
+export {};
+//# sourceMappingURL=world-map-navigation.d.ts.map

package/dist/world-map-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-map-navigation.d.ts","sourceRoot":"","sources":["../src/world-map-navigation.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,UAAU,SAAU,SAAQ,kBAAkB;IAC5C,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAID,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,GAAI,UAAU,WAAW,KAAG,MAMzD,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,UAAU,WAAW,EAAE,OAAO,MAAM,KAAG,IAIzE,CAAA;AAED,eAAO,MAAM,uBAAuB,GAAI,MAAM,WAAW,KAAG,SAAS,GAAG,SAwBvE,CAAA;AAED,eAAO,MAAM,iBAAiB,GAC5B,MAAM,WAAW,EAAE,UAAU,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KACvE,IAeF,CAAA;AAED,eAAO,MAAM,gBAAgB,GAC3B,UAAU,WAAW,EAAE,SAAS,MAAM,MAAM,EAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,KAAK,IAAI,EAAE,QAAQ,WAAW,KAC/E,IAYF,CAAA"}

package/dist/world-map-navigation.js

@@ -0,0 +1,53 @@
+const isRtlMap = (viewport) => viewport.ownerDocument.defaultView?.getComputedStyle(viewport).direction === 'rtl';
+/** Map geometry uses a left origin; RTL browser scroll offsets use the right edge. */
+export const readMapScrollLeft = (viewport) => {
+    if (!isRtlMap(viewport))
+        return viewport.scrollLeft;
+    const max = Math.max(0, viewport.scrollWidth - viewport.clientWidth);
+    return Math.min(max, Math.max(0, max + viewport.scrollLeft));
+};
+export const writeMapScrollLeft = (viewport, value) => {
+    const max = Math.max(0, viewport.scrollWidth - viewport.clientWidth);
+    viewport.scrollLeft = isRtlMap(viewport) ? Math.min(max, Math.max(0, value)) - max : Math.max(0, value);
+};
+export const getHighlightedMapBounds = (root) => {
+    const paths = [...root.querySelectorAll('.ui-world-map__country--highlighted')];
+    let bounds;
+    for (const path of paths) {
+        const box = path.getBBox();
+        if (![box.x, box.y, box.width, box.height].every(Number.isFinite))
+            continue;
+        if (!bounds) {
+            bounds = { x: box.x, y: box.y, width: box.width, height: box.height };
+            continue;
+        }
+        const right = Math.max(bounds.x + bounds.width, box.x + box.width);
+        const bottom = Math.max(bounds.y + bounds.height, box.y + box.height);
+        const x = Math.min(bounds.x, box.x);
+        const y = Math.min(bounds.y, box.y);
+        bounds = { x, y, width: right - x, height: bottom - y };
+    }
+    return bounds;
+};
+export const fitHighlightedMap = (root, viewport, update) => {
+    const bounds = getHighlightedMapBounds(root);
+    if (!bounds)
+        return;
+    const scaleToBounds = Math.min(1000 / Math.max(1, bounds.width), 400 / Math.max(1, bounds.height));
+    const zoom = Math.min(8, Math.max(1, scaleToBounds * 0.85));
+    update(zoom);
+    const scale = viewport.clientWidth * zoom / 1000;
+    writeMapScrollLeft(viewport, (bounds.x + bounds.width / 2) * scale - viewport.clientWidth / 2);
+    viewport.scrollTop = Math.max(0, (bounds.y + bounds.height / 2) * scale - viewport.clientHeight / 2);
+};
+export const initMapWheelZoom = (viewport, getZoom, update, signal) => {
+    viewport.addEventListener('wheel', event => {
+        if (!event.ctrlKey && !event.metaKey)
+            return;
+        event.preventDefault();
+        const rect = viewport.getBoundingClientRect();
+        const unit = [1, 16, viewport.clientHeight][event.deltaMode] ?? 1;
+        const delta = Math.max(-1000, Math.min(1000, event.deltaY * unit));
+        update(getZoom() * Math.exp(-delta * 0.002), { x: event.clientX - rect.left, y: event.clientY - rect.top });
+    }, { passive: false, signal });
+};

package/dist/world-map-pan.d.ts

@@ -0,0 +1,3 @@
+/** Mouse and pen dragging complements native touch and keyboard scrolling. */
+export declare const initLumenWorldMapPan: (viewport: HTMLElement, signal: AbortSignal) => void;
+//# sourceMappingURL=world-map-pan.d.ts.map

package/dist/world-map-pan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-map-pan.d.ts","sourceRoot":"","sources":["../src/world-map-pan.ts"],"names":[],"mappings":"AASA,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,GAAI,UAAU,WAAW,EAAE,QAAQ,WAAW,KAAG,IAsFjF,CAAA"}

package/dist/world-map-pan.js

@@ -0,0 +1,66 @@
+/** Mouse and pen dragging complements native touch and keyboard scrolling. */
+export const initLumenWorldMapPan = (viewport, signal) => {
+    let drag;
+    let suppressClick = false;
+    let clickTimer;
+    const end = () => {
+        if (!drag)
+            return;
+        suppressClick = drag.moved;
+        if (viewport.hasPointerCapture(drag.id))
+            viewport.releasePointerCapture(drag.id);
+        drag = undefined;
+        viewport.removeAttribute('data-panning');
+        clearTimeout(clickTimer);
+        clickTimer = setTimeout(() => {
+            suppressClick = false;
+        }, 0);
+    };
+    viewport.addEventListener('pointerdown', event => {
+        if (event.button !== 0 || event.pointerType === 'touch' || viewport.dataset.panEnabled !== 'true')
+            return;
+        drag = {
+            id: event.pointerId,
+            x: event.clientX,
+            y: event.clientY,
+            left: viewport.scrollLeft,
+            top: viewport.scrollTop,
+            moved: false
+        };
+    }, { signal });
+    viewport.addEventListener('pointerleave', () => {
+        if (!drag?.moved)
+            drag = undefined;
+    }, { signal });
+    viewport.addEventListener('pointermove', event => {
+        if (drag?.id !== event.pointerId)
+            return;
+        const x = event.clientX - drag.x;
+        const y = event.clientY - drag.y;
+        if (!drag.moved && Math.hypot(x, y) < 4)
+            return;
+        drag.moved = true;
+        viewport.setPointerCapture(drag.id);
+        viewport.dataset.panning = '';
+        viewport.scrollLeft = drag.left - x;
+        viewport.scrollTop = drag.top - y;
+        event.preventDefault();
+    }, { signal });
+    viewport.addEventListener('pointerup', end, { signal });
+    viewport.addEventListener('pointercancel', end, { signal });
+    viewport.addEventListener('lostpointercapture', () => {
+        drag = undefined;
+        viewport.removeAttribute('data-panning');
+    }, { signal });
+    viewport.addEventListener('click', event => {
+        if (!suppressClick)
+            return;
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        suppressClick = false;
+    }, { capture: true, signal });
+    signal.addEventListener('abort', () => {
+        end();
+        clearTimeout(clickTimer);
+    }, { once: true });
+};

package/dist/world-map-zoom.d.ts

@@ -0,0 +1,13 @@
+/** Shared DOM enhancement for the web map's native zoom controls and scrollable viewport. */
+export interface LumenWorldMapZoomLabels {
+    fit: string;
+    level: string;
+    reset: string;
+    viewport: string;
+    zoomIn: string;
+    zoomOut: string;
+}
+export declare const lumenWorldMapZoomLabels: Readonly<LumenWorldMapZoomLabels>;
+export declare const normalizeLumenWorldMapZoom: (value: number) => number;
+export declare const initLumenWorldMapZoom: (root: HTMLElement, signal: AbortSignal) => void;
+//# sourceMappingURL=world-map-zoom.d.ts.map

package/dist/world-map-zoom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-map-zoom.d.ts","sourceRoot":"","sources":["../src/world-map-zoom.ts"],"names":[],"mappings":"AAGA,6FAA6F;AAC7F,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,uBAAuB,CAEpE,CAAA;AAEF,eAAO,MAAM,0BAA0B,GAAI,OAAO,MAAM,KAAG,MAExD,CAAA;AAQH,eAAO,MAAM,qBAAqB,GAAI,MAAM,WAAW,EAAE,QAAQ,WAAW,KAAG,IAuE9E,CAAA"}

package/dist/world-map-zoom.js

@@ -0,0 +1,61 @@
+import { fitHighlightedMap, initMapWheelZoom, readMapScrollLeft, writeMapScrollLeft } from './world-map-navigation.js';
+import { initLumenWorldMapPan } from './world-map-pan.js';
+export const lumenWorldMapZoomLabels = Object.freeze({
+    fit: 'Fit highlighted countries', level: 'Zoom level', reset: 'Reset zoom', viewport: 'Map viewport', zoomIn: 'Zoom in', zoomOut: 'Zoom out'
+});
+export const normalizeLumenWorldMapZoom = (value) => Number.isFinite(value) ?
+    Math.min(8, Math.max(1, value)) :
+    1;
+const isZoomControlDisabled = (root, action, zoom) => {
+    if (action === 'fit')
+        return !root.querySelector('.ui-world-map__country--highlighted');
+    return action === 'in' ? zoom === 8 : zoom === 1;
+};
+export const initLumenWorldMapZoom = (root, signal) => {
+    const viewport = root.querySelector('[data-ui-world-map-viewport]');
+    const controls = [...root.querySelectorAll('[data-ui-world-map-zoom]')];
+    const status = root.querySelector('[data-ui-world-map-zoom-status]');
+    if (!viewport)
+        return;
+    viewport.style.setProperty('--ui-world-map-zoom', '1');
+    viewport.dataset.panEnabled = 'false';
+    viewport.scrollLeft = 0;
+    viewport.scrollTop = 0;
+    if (controls.length === 0)
+        return;
+    initLumenWorldMapPan(viewport, signal);
+    let zoom = 1;
+    const update = (value, anchor = { x: viewport.clientWidth / 2, y: viewport.clientHeight / 2 }) => {
+        const next = normalizeLumenWorldMapZoom(value);
+        const ratio = next / zoom;
+        const x = (readMapScrollLeft(viewport) + anchor.x) * ratio - anchor.x;
+        const y = (viewport.scrollTop + anchor.y) * ratio - anchor.y;
+        zoom = next;
+        viewport.dataset.panEnabled = String(zoom > 1);
+        viewport.style.setProperty('--ui-world-map-zoom', String(zoom));
+        writeMapScrollLeft(viewport, x);
+        viewport.scrollTop = Math.max(0, y);
+        if (status)
+            status.value = `${Math.round(zoom * 100)}%`;
+        for (const button of controls) {
+            const action = button.dataset.uiWorldMapZoom;
+            button.disabled = isZoomControlDisabled(root, action, zoom);
+            button.classList.toggle('ui-button--disabled', button.disabled);
+        }
+    };
+    for (const button of controls) {
+        button.addEventListener('click', () => {
+            const action = button.dataset.uiWorldMapZoom;
+            if (action === 'fit') {
+                fitHighlightedMap(root, viewport, update);
+                return;
+            }
+            const next = action === 'reset' ? 1 : zoom + (action === 'in' ? 0.5 : -0.5);
+            update(next);
+        }, { signal });
+    }
+    update(1);
+    initMapWheelZoom(viewport, () => zoom, update, signal);
+    if (root.dataset.initialView === 'highlighted')
+        fitHighlightedMap(root, viewport, update);
+};

package/dist/world-map.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared, framework-agnostic contract for the WorldMap primitive: variant and marker types,
+ * the equirectangular projection, and validation/normalization helpers used by every adapter.
+ *
+ * Country path geometry (the generated SVG data) is intentionally NOT exported from this module;
+ * it lives in the explicit `@santi020k/lumen-core/world-map-data` subpath so consumers who do not
+ * render a world map never pull the geometry payload into their bundle.
+ */
+export type LumenWorldMapVariant = 'dotted' | 'solid';
+/** One resolved country's projected SVG path and label anchor. Produced by `generate:world-map-data`. */
+export interface LumenWorldMapCountryGeometry {
+    readonly id: string;
+    readonly labelX: number;
+    readonly labelY: number;
+    readonly name: string;
+    readonly path: string;
+}
+/** A consumer-supplied point of interest, placed with the same projection as country paths. */
+export interface LumenWorldMapMarker {
+    readonly id: string;
+    readonly label: string;
+    readonly latitude: number;
+    readonly longitude: number;
+}
+export interface LumenWorldMapSelectDetail {
+    readonly countryId: string;
+    readonly highlighted: boolean;
+    readonly label: string;
+}
+export interface LumenWorldMapViewBox {
+    readonly height: number;
+    readonly width: number;
+}
+export interface LumenWorldMapPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** Fixed SVG viewBox shared by every projected country path and marker. */
+export declare const LUMEN_WORLD_MAP_VIEW_BOX: LumenWorldMapViewBox;
+/**
+ * Latitude band kept by the equirectangular projection. Antarctica is excluded from the dataset
+ * for a familiar world-map extent; see maps/README.md for the documented rationale.
+ */
+export declare const LUMEN_WORLD_MAP_LATITUDE_BOUNDS: Readonly<{
+    max: 84;
+    min: -60;
+}>;
+/**
+ * Projects a [longitude, latitude] pair to the shared SVG viewBox using a simple equirectangular
+ * projection. This is the single documented projection used to build country paths
+ * (`generate:world-map-data`) and to place markers at render time; keep both in sync with
+ * scripts/lib/world-map-geometry.mjs if either changes.
+ */
+export declare const projectLumenWorldMapCoordinate: (longitude: number, latitude: number) => LumenWorldMapPoint;
+export declare const normalizeLumenWorldMapCountries: (value: unknown) => LumenWorldMapCountryGeometry[];
+/**
+ * Trims, upper-cases, deduplicates, and drops highlighted country ids that are not present in
+ * `countries`. Invalid entries (wrong type, blank, unknown, duplicate) are silently dropped so a
+ * typo in application data degrades gracefully instead of breaking the map.
+ */
+export declare const normalizeLumenWorldMapHighlightedCountries: (highlighted: unknown, countries: readonly LumenWorldMapCountryGeometry[]) => string[];
+/**
+ * Validates consumer-supplied markers: requires a non-blank id/label, finite latitude/longitude
+ * within the visible latitude band, and drops duplicate ids. Invalid markers are dropped rather than throwing.
+ */
+export declare const normalizeLumenWorldMapMarkers: (markers: unknown) => LumenWorldMapMarker[];
+export declare const findLumenWorldMapCountry: (countries: readonly LumenWorldMapCountryGeometry[], countryId: string | null | undefined) => LumenWorldMapCountryGeometry | undefined;
+/** Resolves a country's display label, honoring a consumer-supplied override keyed by country id. */
+export declare const resolveLumenWorldMapCountryLabel: (country: LumenWorldMapCountryGeometry, labelOverrides?: Readonly<Record<string, string>> | null) => string;
+export declare const createLumenWorldMapSelectDetail: (country: LumenWorldMapCountryGeometry, highlightedIds: ReadonlySet<string>, labelOverrides?: Readonly<Record<string, string>> | null) => LumenWorldMapSelectDetail;
+//# sourceMappingURL=world-map.d.ts.map

package/dist/world-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-map.d.ts","sourceRoot":"","sources":["../src/world-map.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,OAAO,CAAA;AAErD,yGAAyG;AACzG,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,+FAA+F;AAC/F,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,EAAE,oBAAkE,CAAA;AAEzG;;;GAGG;AACH,eAAO,MAAM,+BAA+B;;;EAAuC,CAAA;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GACzC,WAAW,MAAM,EACjB,UAAU,MAAM,KACf,kBAgBF,CAAA;AAsBD,eAAO,MAAM,+BAA+B,GAAI,OAAO,OAAO,KAAG,4BAA4B,EAkB5F,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,0CAA0C,GACrD,aAAa,OAAO,EACpB,WAAW,SAAS,4BAA4B,EAAE,KACjD,MAAM,EAqBR,CAAA;AA2BD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GACxC,SAAS,OAAO,KACf,mBAAmB,EAkBrB,CAAA;AAED,eAAO,MAAM,wBAAwB,GACnC,WAAW,SAAS,4BAA4B,EAAE,EAClD,WAAW,MAAM,GAAG,IAAI,GAAG,SAAS,KACnC,4BAA4B,GAAG,SAMjC,CAAA;AAED,qGAAqG;AACrG,eAAO,MAAM,gCAAgC,GAC3C,SAAS,4BAA4B,EACrC,iBAAiB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,KACvD,MAIF,CAAA;AAED,eAAO,MAAM,+BAA+B,GAC1C,SAAS,4BAA4B,EACrC,gBAAgB,WAAW,CAAC,MAAM,CAAC,EACnC,iBAAiB,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,KACvD,yBAID,CAAA"}

package/dist/world-map.js

@@ -0,0 +1,143 @@
+/**
+ * Shared, framework-agnostic contract for the WorldMap primitive: variant and marker types,
+ * the equirectangular projection, and validation/normalization helpers used by every adapter.
+ *
+ * Country path geometry (the generated SVG data) is intentionally NOT exported from this module;
+ * it lives in the explicit `@santi020k/lumen-core/world-map-data` subpath so consumers who do not
+ * render a world map never pull the geometry payload into their bundle.
+ */
+/** Fixed SVG viewBox shared by every projected country path and marker. */
+export const LUMEN_WORLD_MAP_VIEW_BOX = Object.freeze({ height: 400, width: 1000 });
+/**
+ * Latitude band kept by the equirectangular projection. Antarctica is excluded from the dataset
+ * for a familiar world-map extent; see maps/README.md for the documented rationale.
+ */
+export const LUMEN_WORLD_MAP_LATITUDE_BOUNDS = Object.freeze({ max: 84, min: -60 });
+/**
+ * Projects a [longitude, latitude] pair to the shared SVG viewBox using a simple equirectangular
+ * projection. This is the single documented projection used to build country paths
+ * (`generate:world-map-data`) and to place markers at render time; keep both in sync with
+ * scripts/lib/world-map-geometry.mjs if either changes.
+ */
+export const projectLumenWorldMapCoordinate = (longitude, latitude) => {
+    if (!Number.isFinite(longitude) || !Number.isFinite(latitude)) {
+        throw new RangeError(`Expected a finite [longitude, latitude] pair, received [${longitude}, ${latitude}].`);
+    }
+    if (longitude < -180 || longitude > 180 || latitude < -90 || latitude > 90) {
+        throw new RangeError('Longitude must be between -180 and 180 and latitude between -90 and 90.');
+    }
+    const { max: latitudeMax, min: latitudeMin } = LUMEN_WORLD_MAP_LATITUDE_BOUNDS;
+    const { height, width } = LUMEN_WORLD_MAP_VIEW_BOX;
+    return {
+        x: ((longitude + 180) / 360) * width,
+        y: ((latitudeMax - latitude) / (latitudeMax - latitudeMin)) * height
+    };
+};
+const isPlainString = (value) => typeof value === 'string' && value.trim().length > 0;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const finiteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const parseCountry = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    const { id, labelX, labelY, name, path } = value;
+    if (typeof id !== 'string' || typeof name !== 'string')
+        return undefined;
+    if (!isPlainString(path))
+        return undefined;
+    if (!finiteNumber(labelX) || !finiteNumber(labelY))
+        return undefined;
+    if (!id.trim() || !name.trim())
+        return undefined;
+    return { id: id.trim().toUpperCase(), labelX, labelY, name, path };
+};
+export const normalizeLumenWorldMapCountries = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    const candidates = value;
+    const result = [];
+    const ids = new Set();
+    for (const candidate of candidates) {
+        const country = parseCountry(candidate);
+        if (!country || ids.has(country.id))
+            continue;
+        ids.add(country.id);
+        result.push(country);
+    }
+    return result;
+};
+/**
+ * Trims, upper-cases, deduplicates, and drops highlighted country ids that are not present in
+ * `countries`. Invalid entries (wrong type, blank, unknown, duplicate) are silently dropped so a
+ * typo in application data degrades gracefully instead of breaking the map.
+ */
+export const normalizeLumenWorldMapHighlightedCountries = (highlighted, countries) => {
+    if (!Array.isArray(highlighted))
+        return [];
+    const candidates = highlighted;
+    const knownIds = new Set(countries.map(country => country.id));
+    const seen = new Set();
+    const result = [];
+    for (const raw of candidates) {
+        if (!isPlainString(raw))
+            continue;
+        const id = raw.trim().toUpperCase();
+        if (seen.has(id) || !knownIds.has(id))
+            continue;
+        seen.add(id);
+        result.push(id);
+    }
+    return result;
+};
+const isValidLatitude = (latitude) => {
+    const { max, min } = LUMEN_WORLD_MAP_LATITUDE_BOUNDS;
+    return latitude >= min && latitude <= max;
+};
+const isValidLongitude = (longitude) => longitude >= -180 && longitude <= 180;
+/** Parses one candidate marker, or returns undefined if it fails any validation rule. */
+const parseLumenWorldMapMarker = (marker) => {
+    if (!isRecord(marker) || !isPlainString(marker.id) || !isPlainString(marker.label))
+        return undefined;
+    const { latitude, longitude } = marker;
+    if (typeof latitude !== 'number' || typeof longitude !== 'number')
+        return undefined;
+    if (!Number.isFinite(latitude) || !Number.isFinite(longitude))
+        return undefined;
+    if (!isValidLatitude(latitude) || !isValidLongitude(longitude))
+        return undefined;
+    return { id: marker.id.trim(), label: marker.label.trim(), latitude, longitude };
+};
+/**
+ * Validates consumer-supplied markers: requires a non-blank id/label, finite latitude/longitude
+ * within the visible latitude band, and drops duplicate ids. Invalid markers are dropped rather than throwing.
+ */
+export const normalizeLumenWorldMapMarkers = (markers) => {
+    if (!Array.isArray(markers))
+        return [];
+    const candidates = markers;
+    const seen = new Set();
+    const result = [];
+    for (const candidate of candidates) {
+        const marker = parseLumenWorldMapMarker(candidate);
+        if (!marker || seen.has(marker.id))
+            continue;
+        seen.add(marker.id);
+        result.push(marker);
+    }
+    return result;
+};
+export const findLumenWorldMapCountry = (countries, countryId) => {
+    if (!isPlainString(countryId))
+        return undefined;
+    const id = countryId.trim().toUpperCase();
+    return countries.find(country => country.id === id);
+};
+/** Resolves a country's display label, honoring a consumer-supplied override keyed by country id. */
+export const resolveLumenWorldMapCountryLabel = (country, labelOverrides) => {
+    const override = labelOverrides?.[country.id];
+    return isPlainString(override) ? override.trim() : country.name;
+};
+export const createLumenWorldMapSelectDetail = (country, highlightedIds, labelOverrides) => ({
+    countryId: country.id,
+    highlighted: highlightedIds.has(country.id),
+    label: resolveLumenWorldMapCountryLabel(country, labelOverrides)
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@santi020k/lumen-core",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "publishConfig": {
     "access": "public"
   },
@@ -67,22 +67,69 @@
     "./icon-data": {
       "types": "./dist/icon-data.generated.d.ts",
       "import": "./dist/icon-data.generated.js"
+    },
+    "./image-comparison": {
+      "types": "./dist/image-comparison.d.ts",
+      "import": "./dist/image-comparison.js"
+    },
+    "./virtual-list": {
+      "types": "./dist/virtual-list.d.ts",
+      "import": "./dist/virtual-list.js"
+    },
+    "./virtual-window": {
+      "types": "./dist/virtual-window.d.ts",
+      "import": "./dist/virtual-window.js"
+    },
+    "./rive": {
+      "types": "./dist/rive.d.ts",
+      "import": "./dist/rive.js"
+    },
+    "./world-map": {
+      "types": "./dist/world-map.d.ts",
+      "import": "./dist/world-map.js"
+    },
+    "./world-map-data": {
+      "types": "./dist/world-map-data.generated.d.ts",
+      "import": "./dist/world-map-data.generated.js"
+    },
+    "./world-map-zoom": {
+      "types": "./dist/world-map-zoom.d.ts",
+      "import": "./dist/world-map-zoom.js"
+    },
+    "./media-workspace": {
+      "types": "./dist/media-workspace.d.ts",
+      "import": "./dist/media-workspace.js"
+    },
+    "./media-viewport": {
+      "types": "./dist/media-viewport.d.ts",
+      "import": "./dist/media-viewport.js"
     }
   },
   "files": [
     "dist",
     "README.md",
     "LICENSE",
+    "PHONE_FLAG_LICENSE.txt",
     "THIRD_PARTY_NOTICES.md"
   ],
   "dependencies": {
-    "@lucide/icons": "^1.48.0",
+    "@lucide/icons": "^1.50.0",
     "libphonenumber-js": "^1.13.14"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^5.0.1",
+    "@rive-app/canvas": "2.44.0",
+    "@vitest/coverage-v8": "^5.0.3",
+    "jsdom": "^30.1.1",
     "typescript": "~6.0.3",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.3"
+  },
+  "peerDependencies": {
+    "@rive-app/canvas": "^2.44.0"
+  },
+  "peerDependenciesMeta": {
+    "@rive-app/canvas": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.12.0"