@konce-pt/map 0.8.0

package/dist/geo.d.ts

@@ -0,0 +1,64 @@
+import type { KptLatLng, KptMapBounds, KptMapPoint } from './types.ts';
+/** Bok kafla w pikselach — stała obu silników. */
+export declare const KPT_TILE_SIZE = 256;
+/**
+ * Granica szerokości w Mercatorze. Powyżej niej projekcja ucieka do nieskończoności,
+ * więc obie biblioteki przycinają świat dokładnie w tym miejscu.
+ */
+export declare const KPT_MAX_LATITUDE = 85.05112877980659;
+/** Promień Ziemi w metrach (sfera, jak w Leaflet `L.CRS.Earth`). */
+export declare const KPT_EARTH_RADIUS = 6378137;
+/** Przycina szerokość do zakresu obsługiwanego przez Mercator. */
+export declare function clampLat(lat: number): number;
+/**
+ * Zawija długość geograficzną do zakresu [-180, 180].
+ *
+ * Wartości już w zakresie wracają nietknięte — także -180, bo w projekcji jest to
+ * lewa krawędź świata (x = 0), a nie ta sama kolumna pikseli co +180. Zawijanie
+ * dotyczy wyłącznie tego, co wychodzi poza zakres: 540° to ten sam południk co 180°.
+ */
+export declare function normalizeLng(lng: number): number;
+/** Liczba pikseli świata na danym zoomie. */
+export declare function worldSize(zoom: number): number;
+/** Współrzędne → piksele świata na danym zoomie (origin w lewym górnym rogu). */
+export declare function project(at: KptLatLng, zoom: number): KptMapPoint;
+/** Piksele świata → współrzędne. Odwrotność `project`. */
+export declare function unproject(point: KptMapPoint, zoom: number): KptLatLng;
+/** Najmniejszy prostokąt obejmujący wszystkie punkty. Pusta lista → `null`. */
+export declare function boundsOf(points: readonly KptLatLng[]): KptMapBounds | null;
+/**
+ * Najmniejszy zasięg w stopniach, przy którym `fitBounds` ma jeszcze sens (~100 m).
+ *
+ * Geokodery obrysowują pojedynczy adres prostokątem rzędu 0,0001°. Wpasowanie takiego
+ * w kadr wjeżdża na górny limit zoomu, a wynik zależy od tego, jak dostawca obrysował
+ * budynek — dwa sąsiednie adresy lądują w różnych przybliżeniach.
+ */
+export declare const KPT_MIN_FIT_SPAN = 0.001;
+/**
+ * Czy prostokąt warto wpasowywać w kadr, zamiast potraktować go jak punkt.
+ *
+ * `false` dla zasięgu zdegenerowanego albo ciaśniejszego niż `minSpan` w OBU osiach —
+ * długa, wąska ulica ma jeden wymiar mikroskopijny i dalej zasługuje na `fitBounds`.
+ */
+export declare function isFittableBounds(bounds: KptMapBounds, minSpan?: number): boolean;
+/** Środek prostokąta. */
+export declare function boundsCenter(bounds: KptMapBounds): KptLatLng;
+/** Czy punkt leży w prostokącie (granice włącznie). */
+export declare function boundsContain(bounds: KptMapBounds, at: KptLatLng): boolean;
+/** Rozszerza prostokąt o zadaną liczbę stopni w każdą stronę. */
+export declare function padBounds(bounds: KptMapBounds, degrees: number): KptMapBounds;
+/** Odległość po wielkim kole w metrach. */
+export declare function haversine(a: KptLatLng, b: KptLatLng): number;
+/**
+ * Ile metrów przypada na piksel na danej szerokości i zoomie.
+ * Potrzebne, żeby krąg dokładności geolokalizacji miał realny promień.
+ */
+export declare function metersPerPixel(lat: number, zoom: number): number;
+/**
+ * Największy zoom, przy którym `bounds` mieści się w kontenerze o zadanym rozmiarze.
+ * Zwraca liczbę zmiennoprzecinkową — zaokrąglenie w dół zostawiamy wołającemu.
+ */
+export declare function zoomForBounds(bounds: KptMapBounds, size: {
+    width: number;
+    height: number;
+}, paddingPx?: number): number;

package/dist/geo.js

@@ -0,0 +1,136 @@
+/** Bok kafla w pikselach — stała obu silników. */
+export const KPT_TILE_SIZE = 256;
+/**
+ * Granica szerokości w Mercatorze. Powyżej niej projekcja ucieka do nieskończoności,
+ * więc obie biblioteki przycinają świat dokładnie w tym miejscu.
+ */
+export const KPT_MAX_LATITUDE = 85.051_128_779_806_59;
+/** Promień Ziemi w metrach (sfera, jak w Leaflet `L.CRS.Earth`). */
+export const KPT_EARTH_RADIUS = 6_378_137;
+/** Przycina szerokość do zakresu obsługiwanego przez Mercator. */
+export function clampLat(lat) {
+    return Math.max(-KPT_MAX_LATITUDE, Math.min(KPT_MAX_LATITUDE, lat));
+}
+/**
+ * Zawija długość geograficzną do zakresu [-180, 180].
+ *
+ * Wartości już w zakresie wracają nietknięte — także -180, bo w projekcji jest to
+ * lewa krawędź świata (x = 0), a nie ta sama kolumna pikseli co +180. Zawijanie
+ * dotyczy wyłącznie tego, co wychodzi poza zakres: 540° to ten sam południk co 180°.
+ */
+export function normalizeLng(lng) {
+    if (lng >= -180 && lng <= 180)
+        return lng;
+    const wrapped = ((lng + 180) % 360 + 360) % 360 - 180;
+    return wrapped === -180 ? 180 : wrapped;
+}
+/** Liczba pikseli świata na danym zoomie. */
+export function worldSize(zoom) {
+    return KPT_TILE_SIZE * Math.pow(2, zoom);
+}
+/** Współrzędne → piksele świata na danym zoomie (origin w lewym górnym rogu). */
+export function project(at, zoom) {
+    const size = worldSize(zoom);
+    const lat = clampLat(at.lat);
+    const sin = Math.sin((lat * Math.PI) / 180);
+    return {
+        x: size * (normalizeLng(at.lng) / 360 + 0.5),
+        y: size * (0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI)),
+    };
+}
+/** Piksele świata → współrzędne. Odwrotność `project`. */
+export function unproject(point, zoom) {
+    const size = worldSize(zoom);
+    const lng = (point.x / size - 0.5) * 360;
+    const n = Math.PI * (1 - 2 * (point.y / size));
+    const lat = (180 / Math.PI) * Math.atan(Math.sinh(n));
+    return { lat, lng };
+}
+/** Najmniejszy prostokąt obejmujący wszystkie punkty. Pusta lista → `null`. */
+export function boundsOf(points) {
+    if (points.length === 0)
+        return null;
+    let south = Infinity;
+    let north = -Infinity;
+    let west = Infinity;
+    let east = -Infinity;
+    for (const p of points) {
+        if (p.lat < south)
+            south = p.lat;
+        if (p.lat > north)
+            north = p.lat;
+        if (p.lng < west)
+            west = p.lng;
+        if (p.lng > east)
+            east = p.lng;
+    }
+    return { south, west, north, east };
+}
+/**
+ * Najmniejszy zasięg w stopniach, przy którym `fitBounds` ma jeszcze sens (~100 m).
+ *
+ * Geokodery obrysowują pojedynczy adres prostokątem rzędu 0,0001°. Wpasowanie takiego
+ * w kadr wjeżdża na górny limit zoomu, a wynik zależy od tego, jak dostawca obrysował
+ * budynek — dwa sąsiednie adresy lądują w różnych przybliżeniach.
+ */
+export const KPT_MIN_FIT_SPAN = 0.001;
+/**
+ * Czy prostokąt warto wpasowywać w kadr, zamiast potraktować go jak punkt.
+ *
+ * `false` dla zasięgu zdegenerowanego albo ciaśniejszego niż `minSpan` w OBU osiach —
+ * długa, wąska ulica ma jeden wymiar mikroskopijny i dalej zasługuje na `fitBounds`.
+ */
+export function isFittableBounds(bounds, minSpan = KPT_MIN_FIT_SPAN) {
+    const lat = bounds.north - bounds.south;
+    const lng = bounds.east - bounds.west;
+    if (!Number.isFinite(lat) || !Number.isFinite(lng) || lat < 0 || lng < 0)
+        return false;
+    return lat >= minSpan || lng >= minSpan;
+}
+/** Środek prostokąta. */
+export function boundsCenter(bounds) {
+    return { lat: (bounds.south + bounds.north) / 2, lng: (bounds.west + bounds.east) / 2 };
+}
+/** Czy punkt leży w prostokącie (granice włącznie). */
+export function boundsContain(bounds, at) {
+    return at.lat >= bounds.south && at.lat <= bounds.north && at.lng >= bounds.west && at.lng <= bounds.east;
+}
+/** Rozszerza prostokąt o zadaną liczbę stopni w każdą stronę. */
+export function padBounds(bounds, degrees) {
+    return {
+        south: clampLat(bounds.south - degrees),
+        north: clampLat(bounds.north + degrees),
+        west: bounds.west - degrees,
+        east: bounds.east + degrees,
+    };
+}
+/** Odległość po wielkim kole w metrach. */
+export function haversine(a, b) {
+    const toRad = Math.PI / 180;
+    const dLat = (b.lat - a.lat) * toRad;
+    const dLng = (b.lng - a.lng) * toRad;
+    const s = Math.sin(dLat / 2) ** 2 +
+        Math.cos(a.lat * toRad) * Math.cos(b.lat * toRad) * Math.sin(dLng / 2) ** 2;
+    return 2 * KPT_EARTH_RADIUS * Math.asin(Math.min(1, Math.sqrt(s)));
+}
+/**
+ * Ile metrów przypada na piksel na danej szerokości i zoomie.
+ * Potrzebne, żeby krąg dokładności geolokalizacji miał realny promień.
+ */
+export function metersPerPixel(lat, zoom) {
+    return (Math.cos((clampLat(lat) * Math.PI) / 180) * 2 * Math.PI * KPT_EARTH_RADIUS) / worldSize(zoom);
+}
+/**
+ * Największy zoom, przy którym `bounds` mieści się w kontenerze o zadanym rozmiarze.
+ * Zwraca liczbę zmiennoprzecinkową — zaokrąglenie w dół zostawiamy wołającemu.
+ */
+export function zoomForBounds(bounds, size, paddingPx = 0) {
+    const w = Math.max(1, size.width - paddingPx * 2);
+    const h = Math.max(1, size.height - paddingPx * 2);
+    // Rozpiętość liczona na zoomie 0, potem skalowana logarytmicznie.
+    const sw = project({ lat: bounds.south, lng: bounds.west }, 0);
+    const ne = project({ lat: bounds.north, lng: bounds.east }, 0);
+    const dx = Math.max(1e-9, Math.abs(ne.x - sw.x));
+    const dy = Math.max(1e-9, Math.abs(sw.y - ne.y));
+    return Math.min(Math.log2(w / dx), Math.log2(h / dy));
+}

package/dist/hours.d.ts

@@ -0,0 +1,41 @@
+import type { KptMapOpeningHours, KptMapWeekday } from './types.ts';
+/** Minuta doby dla `HH:MM`; `24:00` to 1440. `null`, gdy zapis jest nieprawidłowy. */
+export declare function parseTime(value: string): number | null;
+/** `HH:MM` z minuty doby. 1440 wraca jako `24:00`, nie `00:00`. */
+export declare function formatTime(minutes: number): string;
+/** Dzień tygodnia wg ISO (1 = poniedziałek) z natywnej daty. */
+export declare function isoWeekday(date: Date): KptMapWeekday;
+/**
+ * Czy miejsce jest otwarte w danym momencie.
+ *
+ * Sprawdza dwa dni: bieżący oraz poprzedni, bo przedział przez północ
+ * (`22:00 – 01:00`) obejmuje wczesne godziny dnia następnego.
+ */
+export declare function isOpenAt(hours: KptMapOpeningHours | undefined, date: Date): boolean;
+/** Czy rozkład to pełna doba przez siedem dni — wtedy karta pisze po prostu „24/7". */
+export declare function isAlwaysOpen(hours: KptMapOpeningHours | undefined): boolean;
+/** Najbliższa zmiana stanu otwarte/zamknięte albo `null`, gdy w ciągu tygodnia jej nie ma. */
+export declare function nextChange(hours: KptMapOpeningHours | undefined, date: Date): {
+    open: boolean;
+    at: Date;
+} | null;
+/** Skrócona nazwa dnia z `Intl` — bez słownika, więc działa dla dowolnego locale. */
+export declare function weekdayName(day: KptMapWeekday, locale: string): string;
+/** Wiersz rozkładu: jeden dzień albo sklejony zakres dni o identycznych godzinach. */
+export interface KptMapHoursGroup {
+    /** `pon.` albo `wt.–sob.`, wg locale. */
+    label: string;
+    days: KptMapWeekday[];
+    closed: boolean;
+    /** Sformatowane przedziały, np. `['11:00 – 24:00']`. Puste, gdy zamknięte. */
+    ranges: string[];
+}
+/**
+ * Rozkład tygodnia z sąsiadującymi dniami sklejonymi w jeden wiersz.
+ *
+ * Niedziela i poniedziałek się nie sklejają, choć w tablicy sąsiadują — tydzień
+ * czyta się liniowo od poniedziałku i zawijanie byłoby mylące.
+ */
+export declare function groupWeek(hours: KptMapOpeningHours | undefined, locale: string, separator?: string): KptMapHoursGroup[];
+/** Siedem dni oznaczonych jako zamknięte — wartość startowa pola `hours` w formularzu. */
+export declare function emptyWeek(): KptMapOpeningHours;

package/dist/hours.js

@@ -0,0 +1,174 @@
+/*
+ * Godziny otwarcia — pure TS, bez Angulara i bez silnika mapowego.
+ * Ten plik przenosi się do portu React bez zmian.
+ *
+ * Umowa o czasie: `HH:MM` w czasie lokalnym miejsca, a porównania robimy
+ * na lokalnym czasie przeglądarki. Miejsce w innej strefie niż użytkownik
+ * pokaże więc status wg zegara użytkownika — to świadome uproszczenie,
+ * bo model nie niesie strefy. Kto potrzebuje inaczej, liczy status u siebie.
+ */
+/** Minuta doby dla `HH:MM`; `24:00` to 1440. `null`, gdy zapis jest nieprawidłowy. */
+export function parseTime(value) {
+    const match = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+    if (!match)
+        return null;
+    const hours = Number(match[1]);
+    const minutes = Number(match[2]);
+    if (minutes > 59)
+        return null;
+    const total = hours * 60 + minutes;
+    return total > 1440 ? null : total;
+}
+/** `HH:MM` z minuty doby. 1440 wraca jako `24:00`, nie `00:00`. */
+export function formatTime(minutes) {
+    const m = Math.max(0, Math.min(1440, Math.round(minutes)));
+    return `${String(Math.floor(m / 60)).padStart(2, '0')}:${String(m % 60).padStart(2, '0')}`;
+}
+/** Dzień tygodnia wg ISO (1 = poniedziałek) z natywnej daty. */
+export function isoWeekday(date) {
+    const day = date.getDay();
+    return (day === 0 ? 7 : day);
+}
+function previousDay(day) {
+    return (day === 1 ? 7 : day - 1);
+}
+function dayOf(hours, day) {
+    return hours.find((entry) => entry.day === day);
+}
+/** Przedział przechodzi przez północ, gdy kończy się nie później niż zaczyna. */
+function crossesMidnight(range) {
+    const from = parseTime(range.from);
+    const to = parseTime(range.to);
+    return from !== null && to !== null && to <= from;
+}
+function usableRanges(entry) {
+    if (!entry || entry.closed)
+        return [];
+    return entry.ranges.filter((r) => parseTime(r.from) !== null && parseTime(r.to) !== null);
+}
+/**
+ * Czy miejsce jest otwarte w danym momencie.
+ *
+ * Sprawdza dwa dni: bieżący oraz poprzedni, bo przedział przez północ
+ * (`22:00 – 01:00`) obejmuje wczesne godziny dnia następnego.
+ */
+export function isOpenAt(hours, date) {
+    if (!hours || hours.length === 0)
+        return false;
+    const minute = date.getHours() * 60 + date.getMinutes();
+    const today = isoWeekday(date);
+    for (const range of usableRanges(dayOf(hours, today))) {
+        const from = parseTime(range.from);
+        const to = parseTime(range.to);
+        if (to > from ? minute >= from && minute < to : minute >= from)
+            return true;
+    }
+    for (const range of usableRanges(dayOf(hours, previousDay(today)))) {
+        if (!crossesMidnight(range))
+            continue;
+        if (minute < parseTime(range.to))
+            return true;
+    }
+    return false;
+}
+/** Czy rozkład to pełna doba przez siedem dni — wtedy karta pisze po prostu „24/7". */
+export function isAlwaysOpen(hours) {
+    if (!hours)
+        return false;
+    for (let day = 1; day <= 7; day++) {
+        const ranges = usableRanges(dayOf(hours, day));
+        const full = ranges.some((r) => parseTime(r.from) === 0 && parseTime(r.to) === 1440);
+        if (!full)
+            return false;
+    }
+    return true;
+}
+/** Najbliższa zmiana stanu otwarte/zamknięte albo `null`, gdy w ciągu tygodnia jej nie ma. */
+export function nextChange(hours, date) {
+    if (!hours || hours.length === 0)
+        return null;
+    const now = isOpenAt(hours, date);
+    // Granice przedziałów na najbliższe osiem dób; pierwsza różnica wygrywa.
+    for (let offset = 0; offset <= 8; offset++) {
+        const base = new Date(date);
+        base.setHours(0, 0, 0, 0);
+        base.setDate(base.getDate() + offset);
+        const day = isoWeekday(base);
+        const minutes = new Set();
+        for (const range of usableRanges(dayOf(hours, day))) {
+            minutes.add(parseTime(range.from));
+            const to = parseTime(range.to);
+            if (to > parseTime(range.from))
+                minutes.add(to);
+        }
+        for (const range of usableRanges(dayOf(hours, previousDay(day)))) {
+            if (crossesMidnight(range))
+                minutes.add(parseTime(range.to));
+        }
+        for (const minute of [...minutes].sort((a, b) => a - b)) {
+            const at = new Date(base);
+            at.setMinutes(minute);
+            if (at.getTime() <= date.getTime())
+                continue;
+            const open = isOpenAt(hours, at);
+            if (open !== now)
+                return { open, at };
+        }
+    }
+    return null;
+}
+/** Skrócona nazwa dnia z `Intl` — bez słownika, więc działa dla dowolnego locale. */
+export function weekdayName(day, locale) {
+    // 2024-01-01 był poniedziałkiem, więc dzień ISO wypada na tę samą liczbę w miesiącu.
+    const date = new Date(Date.UTC(2024, 0, day));
+    return new Intl.DateTimeFormat(locale, { weekday: 'short', timeZone: 'UTC' }).format(date);
+}
+function signatureOf(entry) {
+    const ranges = usableRanges(entry);
+    if (ranges.length === 0)
+        return 'closed';
+    return ranges.map((r) => `${parseTime(r.from)}-${parseTime(r.to)}`).join(',');
+}
+/**
+ * Rozkład tygodnia z sąsiadującymi dniami sklejonymi w jeden wiersz.
+ *
+ * Niedziela i poniedziałek się nie sklejają, choć w tablicy sąsiadują — tydzień
+ * czyta się liniowo od poniedziałku i zawijanie byłoby mylące.
+ */
+export function groupWeek(hours, locale, separator = ' – ') {
+    if (!hours || hours.length === 0)
+        return [];
+    const groups = [];
+    let signature = null;
+    for (let day = 1; day <= 7; day++) {
+        const entry = dayOf(hours, day);
+        const current = signatureOf(entry);
+        const previous = groups[groups.length - 1];
+        if (current === signature && previous) {
+            previous.days.push(day);
+            continue;
+        }
+        signature = current;
+        const ranges = usableRanges(entry);
+        groups.push({
+            label: '',
+            days: [day],
+            closed: ranges.length === 0,
+            ranges: ranges.map((r) => `${r.from}${separator}${r.to}`),
+        });
+    }
+    for (const group of groups) {
+        const first = weekdayName(group.days[0], locale);
+        const last = weekdayName(group.days[group.days.length - 1], locale);
+        group.label = group.days.length === 1 ? first : `${first}–${last}`;
+    }
+    return groups;
+}
+/** Siedem dni oznaczonych jako zamknięte — wartość startowa pola `hours` w formularzu. */
+export function emptyWeek() {
+    return Array.from({ length: 7 }, (_, i) => ({
+        day: (i + 1),
+        closed: true,
+        ranges: [],
+    }));
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './types.ts';
+export * from './geo.ts';
+export * from './cluster.ts';
+export * from './countries.ts';
+export * from './marker-html.ts';
+export * from './engine.ts';
+export * from './hours.ts';
+export * from './format.ts';
+export * from './url.ts';
+export * from './engines/leaflet.engine.ts';
+export * from './engines/google.engine.ts';

package/dist/index.js

@@ -0,0 +1,16 @@
+/*
+ * Rdzeń mapy — pure TS, bez frameworka. Obok obliczeń (geometria, klastrowanie, godziny)
+ * mieszkają tu adaptery silników: Leaflet i Google. Oba rozmawiają z resztą kodu wyłącznie
+ * przez interfejs `KptMapEngine`, więc port Angulara i Reacta dzielą całą tę warstwę.
+ */
+export * from "./types.js";
+export * from "./geo.js";
+export * from "./cluster.js";
+export * from "./countries.js";
+export * from "./marker-html.js";
+export * from "./engine.js";
+export * from "./hours.js";
+export * from "./format.js";
+export * from "./url.js";
+export * from "./engines/leaflet.engine.js";
+export * from "./engines/google.engine.js";

package/dist/marker-html.d.ts

@@ -0,0 +1,37 @@
+import type { KptMapColor, KptMapMarkerShape } from './types.ts';
+/** Rola koloru → zmienna CSS. Gotowe `var(--kpt-*)` przechodzi bez zmian; cokolwiek spoza tego
+ *  kontraktu dostaje bezpieczny fallback zamiast trafić surowo do wyjścia. */
+export declare function colorVarOf(color: KptMapColor): string;
+/** Kolor treści na tle `color` — dla ról znany, dla własnych zmiennych fallback na biel tokenową. */
+export declare function contrastVarOf(color: KptMapColor): string;
+export declare function foregroundVarOf(color: KptMapColor): string;
+/** Ucieka znaki, które rozbiłyby atrybut albo wstrzyknęły znacznik. */
+export declare function escapeHtml(value: string): string;
+export interface KptMarkerHtmlInput {
+    shape?: KptMapMarkerShape;
+    color: KptMapColor;
+    /** Inner-SVG ikony (bez wrappera `<svg>`); bez niego znacznik nie ma glifu. */
+    iconSvgInner?: string;
+    /** Tekst dla czytnika ekranu — zwykle tytuł lokalizacji. */
+    label: string;
+    /** Znacznik wybrany (otwarty popup) — dostaje klasę modyfikującą. */
+    selected?: boolean;
+}
+export declare function renderMarkerHtml(input: KptMarkerHtmlInput): string;
+export interface KptClusterHtmlInput {
+    count: number;
+    color: KptMapColor;
+    /** Gotowy tekst dla czytnika (i18n rozwiązane po stronie Angulara). */
+    label: string;
+}
+/** Koło z licznikiem; rozmiar rośnie schodkowo z liczebnością grupy. */
+export declare function renderClusterHtml(input: KptClusterHtmlInput): string;
+/** Próg wielkości grupy — trzy stopnie wystarczą, żeby zobaczyć różnicę bez skalowania ciągłego. */
+export declare function clusterTier(count: number): 'sm' | 'md' | 'lg';
+/** Powyżej 999 licznik przestaje się mieścić — skracamy. */
+export declare function formatCount(count: number): string;
+/** Znacznik pozycji użytkownika — ikona podawana z zewnątrz, jak przy zwykłym znaczniku. */
+export declare function renderUserMarkerHtml(input: {
+    label: string;
+    iconSvgInner?: string;
+}): string;

package/dist/marker-html.js

@@ -0,0 +1,119 @@
+const ROLE_VARS = {
+    primary: 'var(--kpt-color-primary)',
+    success: 'var(--kpt-color-success)',
+    warning: 'var(--kpt-color-warning)',
+    danger: 'var(--kpt-color-danger)',
+    info: 'var(--kpt-color-info)',
+    muted: 'var(--kpt-color-muted)',
+};
+const ROLE_CONTRAST_VARS = {
+    primary: 'var(--kpt-color-primary-contrast)',
+    success: 'var(--kpt-color-success-contrast)',
+    warning: 'var(--kpt-color-warning-contrast)',
+    danger: 'var(--kpt-color-danger-contrast)',
+    info: 'var(--kpt-color-info-contrast)',
+    muted: 'var(--kpt-color-on-muted)',
+};
+/**
+ * Kształt jedynego wejścia spoza znanej roli, jakie kontrakt `KptMapColor` dopuszcza —
+ * gotowy token `var(--kpt-*)`. Dane runtime (JSON/CMS) nie są tym kontraktem związane, więc
+ * zanim trafią do atrybutu `style="..."` budowanego konkatenacją stringów w `renderMarkerHtml`/
+ * `renderClusterHtml`, muszą zostać zweryfikowane — inaczej cudzysłów/`>` wyrywa się z atrybutu
+ * (HTML injection), a średnik wstrzykuje dodatkową deklarację CSS.
+ */
+const SAFE_VAR_TOKEN = /^var\(--kpt-[\w-]+\)$/;
+/** Rola koloru → zmienna CSS. Gotowe `var(--kpt-*)` przechodzi bez zmian; cokolwiek spoza tego
+ *  kontraktu dostaje bezpieczny fallback zamiast trafić surowo do wyjścia. */
+export function colorVarOf(color) {
+    const known = ROLE_VARS[color];
+    if (known)
+        return known;
+    return SAFE_VAR_TOKEN.test(color) ? color : ROLE_VARS.muted;
+}
+/** Kolor treści na tle `color` — dla ról znany, dla własnych zmiennych fallback na biel tokenową. */
+export function contrastVarOf(color) {
+    return ROLE_CONTRAST_VARS[color] ?? 'var(--kpt-color-text-inverse)';
+}
+/**
+ * Kolor **glifu stojącego wprost na powierzchni**, bez własnego tła.
+ *
+ * Różni się od `colorVarOf()` tylko dla roli `muted`: `--kpt-color-muted` to neutral-100,
+ * czyli token tła, a nie treści — goły znak w tym kolorze na jasnej powierzchni jest
+ * niewidoczny. Bierzemy więc czytelny szary tekstowy. Pozostałe role są nasycone
+ * i jako treść czytają się bez zmian.
+ */
+const ROLE_FOREGROUND_VARS = {
+    ...ROLE_VARS,
+    muted: 'var(--kpt-color-on-surface-muted)',
+};
+export function foregroundVarOf(color) {
+    const known = ROLE_FOREGROUND_VARS[color];
+    if (known)
+        return known;
+    return SAFE_VAR_TOKEN.test(color) ? color : ROLE_FOREGROUND_VARS.muted;
+}
+/** Ucieka znaki, które rozbiłyby atrybut albo wstrzyknęły znacznik. */
+export function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+/**
+ * Pinezka o wysokości `--kpt-map-marker-size`, zakotwiczona czubkiem w punkcie.
+ * `viewBox` 24×32: 24 szerokości koła + ogon do 32.
+ */
+const PIN_PATH = 'M12 0C5.8 0 .8 5 .8 11.2c0 8 9.9 19.4 10.3 19.9a1.2 1.2 0 0 0 1.8 0c.4-.5 10.3-11.9 10.3-19.9C23.2 5 18.2 0 12 0z';
+export function renderMarkerHtml(input) {
+    // `shape` trafia do atrybutu `class="..."` konkatenacją stringów — `KptMapMarkerShape` ogranicza
+    // to tylko compile-time, dane runtime (JSON/CMS) nie są tym związane (ten sam powód, dla którego
+    // `color`/`contrast` dostały escapowanie/whitelistę wyżej w pliku).
+    const shape = escapeHtml(input.shape ?? 'pin');
+    const color = colorVarOf(input.color);
+    const contrast = contrastVarOf(input.color);
+    const label = escapeHtml(input.label);
+    const cls = `kpt-map__marker kpt-map__marker--${shape}${input.selected ? ' kpt-map__marker--selected' : ''}`;
+    const glyph = input.iconSvgInner
+        ? `<svg class="kpt-map__marker-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor"` +
+            ` stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${input.iconSvgInner}</svg>`
+        : '';
+    const body = shape === 'pin'
+        ? `<svg class="kpt-map__marker-shape" viewBox="0 0 24 32" aria-hidden="true">` +
+            `<path d="${PIN_PATH}" /></svg><span class="kpt-map__marker-glyph">${glyph}</span>`
+        : `<span class="kpt-map__marker-glyph">${glyph}</span>`;
+    return (`<div class="${cls}" role="img" aria-label="${label}" title="${label}"` +
+        ` style="--_kpt-map-marker-bg:${color};--_kpt-map-marker-fg:${contrast}">${body}</div>`);
+}
+/** Koło z licznikiem; rozmiar rośnie schodkowo z liczebnością grupy. */
+export function renderClusterHtml(input) {
+    const color = colorVarOf(input.color);
+    const contrast = contrastVarOf(input.color);
+    const label = escapeHtml(input.label);
+    const tier = clusterTier(input.count);
+    return (`<div class="kpt-map__cluster kpt-map__cluster--${tier}" role="img" aria-label="${label}" title="${label}"` +
+        ` style="--_kpt-map-cluster-bg:${color};--_kpt-map-cluster-fg:${contrast}">` +
+        `<span class="kpt-map__cluster-count">${formatCount(input.count)}</span></div>`);
+}
+/** Próg wielkości grupy — trzy stopnie wystarczą, żeby zobaczyć różnicę bez skalowania ciągłego. */
+export function clusterTier(count) {
+    if (count < 10)
+        return 'sm';
+    if (count < 100)
+        return 'md';
+    return 'lg';
+}
+/** Powyżej 999 licznik przestaje się mieścić — skracamy. */
+export function formatCount(count) {
+    return count > 999 ? '999+' : String(count);
+}
+/** Znacznik pozycji użytkownika — ikona podawana z zewnątrz, jak przy zwykłym znaczniku. */
+export function renderUserMarkerHtml(input) {
+    const label = escapeHtml(input.label);
+    const glyph = input.iconSvgInner
+        ? `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"` +
+            ` stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${input.iconSvgInner}</svg>`
+        : '';
+    return `<div class="kpt-map__user-marker" role="img" aria-label="${label}" title="${label}">${glyph}</div>`;
+}