@konce-pt/map 0.8.0

package/dist/types.d.ts

@@ -0,0 +1,238 @@
+/** Punkt geograficzny w stopniach (WGS 84). */
+export interface KptLatLng {
+    lat: number;
+    lng: number;
+}
+/** Prostokąt geograficzny. `south < north`; `west`/`east` w stopniach. */
+export interface KptMapBounds {
+    south: number;
+    west: number;
+    north: number;
+    east: number;
+}
+/** Punkt w pikselach — kontenera mapy albo świata, zależnie od kontekstu. */
+export interface KptMapPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Kolor znacznika: rola z warstwy semantycznej tokenów albo gotowe `var(--kpt-*)`.
+ * Literały (`#c00`, `rgb(...)`) są celowo niedozwolone — kontrakt repo wymaga tokenów.
+ */
+export type KptMapColorRole = 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'muted';
+export type KptMapColor = KptMapColorRole | `var(--kpt-${string})`;
+/** Kształt znacznika. */
+export type KptMapMarkerShape = 'pin' | 'dot' | 'square';
+/** Typ pola w schemie formularza „dodaj lokalizację". */
+export type KptMapFieldType = 'text' | 'textarea' | 'number' | 'date' | 'select' | 'multiselect' | 'checkbox' | 'tel' | 'email' | 'url'
+/** Zdjęcie: wybór pliku (wartość jako `data:`) albo wklejony adres. */
+ | 'image'
+/** Tygodniowy rozkład godzin otwarcia; wartość to `KptMapOpeningHours`. */
+ | 'hours';
+/** Opcja listy wyboru w polu `select` / `multiselect`. */
+export interface KptMapFieldOption {
+    value: unknown;
+    label: string;
+}
+/** Definicja jednego pola formularza dodawania lokalizacji. */
+export interface KptMapFieldDef {
+    /** Klucz w obiekcie wartości formularza. */
+    key: string;
+    type: KptMapFieldType;
+    label: string;
+    required?: boolean;
+    placeholder?: string;
+    /** Tekst pomocniczy pod polem. */
+    hint?: string;
+    /** Wymagane dla `select` i `multiselect`. */
+    options?: KptMapFieldOption[];
+    /** Dolna granica dla `number`; dla `date` data w formacie ISO. */
+    min?: number | string;
+    /** Górna granica dla `number`; dla `date` data w formacie ISO. */
+    max?: number | string;
+    /** Wartość początkowa; bez niej pole startuje puste (`''`, `null`, `[]`, `false`). */
+    initial?: unknown;
+    /**
+     * Część adresu, którą wypełnić z geokodowania wstecznego współrzędnych kliknięcia.
+     * Działa tylko dla pól tekstowych i tylko gdy aplikacja poda port `KPT_MAP_GEOCODER`.
+     * Nigdy nie nadpisuje tego, co użytkownik już wpisał.
+     */
+    autofill?: KptMapAddressPart;
+}
+/** Rozbiór adresu zwracany przez geokoder. Wszystko opcjonalne — źródła bywają dziurawe. */
+export interface KptMapAddress {
+    /** Nazwa ulicy bez numeru. */
+    street?: string;
+    houseNumber?: string;
+    /** Ulica z numerem, gotowa do jednego pola „Adres". */
+    address?: string;
+    city?: string;
+    postcode?: string;
+    /** Województwo / region. */
+    state?: string;
+    /** Powiat / hrabstwo. */
+    county?: string;
+    country?: string;
+    /** Kod ISO 3166-1 alpha-2, wielkimi literami. */
+    countryCode?: string;
+    /** Pełny adres jednym ciągiem, tak jak podał go geokoder. */
+    label?: string;
+}
+/** Pole `KptMapAddress`, którym można wypełnić kontrolkę formularza. */
+export type KptMapAddressPart = keyof KptMapAddress;
+/**
+ * Podpowiedź z listy wyszukiwarki adresów (geokodowanie wprost: tekst → miejsce).
+ *
+ * Pochodzi z portu `KPT_MAP_GEOCODER`, więc kształt jest wspólny dla dowolnego
+ * dostawcy — Nominatim, instancji własnej i komercyjnej.
+ */
+export interface KptMapSuggestion {
+    /** Stabilny w obrębie jednej odpowiedzi — służy za klucz `track` listy podpowiedzi. */
+    id: string;
+    /** Pełna nazwa jednym ciągiem; to widzi użytkownik na liście. */
+    label: string;
+    /**
+     * Współrzędne, **gdy dostawca podaje je już na liście** — tak robi każdy geokoder
+     * pytany wprost (Nominatim, Photon, Google Geocoding API).
+     *
+     * Brak wartości znaczy, że podpowiedź trzeba jeszcze uzupełnić metodą `resolve()`
+     * portu. Tak działa Google Places Autocomplete: zwraca `placeId` i tekst, a `lat`/`lng`
+     * dociąga się osobnym Place Details — jedno wywołanie na *wybór* użytkownika, a nie
+     * na każdy naciśnięty klawisz. Na tym stoi jego rozliczanie sesyjne, więc to nie jest
+     * dziwactwo jednego dostawcy, tylko wzorzec, który port musi umieć wyrazić.
+     */
+    at?: KptLatLng;
+    /**
+     * Zasięg obiektu, gdy dostawca go podaje. Miasto trafia wtedy w kadr w całości,
+     * zamiast dostać punktowy zoom w środek rynku.
+     */
+    bounds?: KptMapBounds;
+    /** Rozbiór adresu, gdy dostawca go podaje — ten sam typ, co przy geokodowaniu wstecznym. */
+    address?: KptMapAddress;
+}
+/**
+ * Wybrane miejsce — podpowiedź z **pewnymi** współrzędnymi.
+ *
+ * To ten typ wychodzi z `selected` pola wyszukiwania i z `searchSelect` mapy: zanim
+ * zdarzenie poleci, brakujące `at` zostaje dociągnięte przez `resolve()`. Aplikacja
+ * nigdy nie musi sprawdzać, czy współrzędne są.
+ */
+export interface KptMapSearchResult extends KptMapSuggestion {
+    at: KptLatLng;
+}
+/** Kategoria obiektu — kolor, ikona i schema formularza. */
+export interface KptMapCategory {
+    id: string;
+    /** Etykieta w legendzie i domyślnym popupie. */
+    label: string;
+    color: KptMapColor;
+    /** Nazwa ikony z `KptIconRegistry`; bez niej znacznik nie ma glifu. */
+    icon?: string;
+    /** Domyślnie `'pin'`. */
+    shape?: KptMapMarkerShape;
+    /** Schema formularza „dodaj lokalizację" dla tej kategorii. */
+    fields?: KptMapFieldDef[];
+    /** Pokazać w legendzie. Domyślnie `true`. */
+    legend?: boolean;
+}
+/** Pojedyncza lokalizacja na mapie. */
+export interface KptMapLocation<T = unknown> {
+    id: string;
+    at: KptLatLng;
+    categoryId: string;
+    /** Tytuł w popupie oraz `aria-label` znacznika — bez niego znacznik jest niedostępny. */
+    title: string;
+    /** Dowolne dane aplikacji; trafiają do szablonu popupu jako `data`. */
+    data?: T;
+}
+/** Grupa lokalizacji zwinięta w jeden znacznik z licznikiem. */
+export interface KptMapCluster<T = unknown> {
+    /** Stabilny w obrębie zoomu: `c:{zoom}:{cellX}:{cellY}`. */
+    id: string;
+    /** Środek ciężkości grupy. */
+    at: KptLatLng;
+    count: number;
+    /** Najliczniejsza kategoria w grupie — źródło koloru przy `clusterColorBy: 'dominant'`. */
+    dominantCategoryId: string;
+    items: KptMapLocation<T>[];
+    /** Zasięg grupy — do `fitBounds` po kliknięciu. */
+    bounds: KptMapBounds;
+}
+/** Element wyniku grupowania: albo grupa, albo pojedyncza lokalizacja. */
+export type KptMapClusterEntry<T = unknown> = KptMapCluster<T> | KptMapLocation<T>;
+/** Zawęża wynik `clusterLocations` do grupy. */
+export declare function isCluster<T>(entry: KptMapClusterEntry<T>): entry is KptMapCluster<T>;
+/** Pozycja użytkownika z geolokalizacji. */
+export interface KptMapUserPosition {
+    at: KptLatLng;
+    /** Promień niepewności w metrach (`GeolocationCoordinates.accuracy`). */
+    accuracy: number;
+    /** Znacznik czasu odczytu. */
+    timestamp: number;
+}
+/** Powód niepowodzenia geolokalizacji. */
+export type KptMapGeolocationErrorKind = 'denied' | 'unavailable' | 'timeout' | 'unsupported';
+export interface KptMapGeolocationError {
+    kind: KptMapGeolocationErrorKind;
+    message: string;
+}
+/** Zdarzenie utworzenia lokalizacji przez formularz. */
+export interface KptMapCreateEvent {
+    at: KptLatLng;
+    categoryId: string;
+    /** Wartości pól wg schemy kategorii (albo z własnego szablonu formularza). */
+    value: Record<string, unknown>;
+}
+/** Widok mapy — środek i zoom. */
+export interface KptMapView {
+    center: KptLatLng;
+    zoom: number;
+}
+/** Dzień tygodnia wg ISO-8601: 1 = poniedziałek … 7 = niedziela. */
+export type KptMapWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/**
+ * Przedział otwarcia w dobie, `HH:MM` w czasie lokalnym miejsca.
+ *
+ * `to` mniejsze albo równe `from` znaczy „przez północ" — przedział kończy się
+ * następnego dnia. `24:00` to prawidłowy koniec doby i nie jest przejściem przez północ.
+ */
+export interface KptMapHoursRange {
+    from: string;
+    to: string;
+}
+/** Godziny jednego dnia tygodnia. */
+export interface KptMapDayHours {
+    day: KptMapWeekday;
+    /** Zamknięte przez całą dobę — `ranges` jest wtedy ignorowane. */
+    closed?: boolean;
+    ranges: KptMapHoursRange[];
+}
+/** Tygodniowy rozkład godzin. Brakujący dzień znaczy „zamknięte". */
+export type KptMapOpeningHours = KptMapDayHours[];
+/** Wiersz „ikona + etykieta + wartość" w karcie miejsca. */
+export interface KptMapPoiFact {
+    /** Nazwa ikony z `KptIconRegistry`; bez niej wiersz jest bez glifu. */
+    icon?: string;
+    label: string;
+    value: string;
+}
+/**
+ * Dane karty miejsca (`kpt-map-poi-card`). Aplikacja mapuje na to swój
+ * `KptMapLocation.data` — biblioteka nie narzuca kształtu danych domenowych.
+ */
+export interface KptMapPoi {
+    title: string;
+    /** Drugi wiersz nagłówka, obok dystansu. */
+    address?: string;
+    /** Adres zdjęcia albo `data:`; karta nie rozróżnia. Puste = zastępnik z ikoną. */
+    photo?: string;
+    photoAlt?: string;
+    hours?: KptMapOpeningHours;
+    phone?: string;
+    email?: string;
+    website?: string;
+    /** Wiersz współrzędnych; bez tego się nie renderuje. */
+    at?: KptLatLng;
+    /** Dodatkowe wiersze informacyjne, bez akcji. */
+    facts?: KptMapPoiFact[];
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/*
+ * Typy rdzenia mapy — pure TS, zero Angulara i zero silnika mapowego.
+ * Ten plik przenosi się do portu React bez zmian.
+ */
+/** Zawęża wynik `clusterLocations` do grupy. */
+export function isCluster(entry) {
+    return entry.count !== undefined;
+}

package/dist/url.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Adres bez schematu dostaje `https://` — inaczej przeglądarka potraktuje go jak ścieżkę względną.
+ * Schemat spoza allowlisty (np. `javascript:`) traktujemy jak brak schematu — bezpieczny
+ * fallback zamiast przepuszczenia surowej wartości do `[href]`/`[src]`/`navigator.share()`.
+ */
+export declare function normalizeUrl(value: string): string;
+/** Wersja adresu do pokazania: bez schematu i bez końcowego ukośnika. */
+export declare function prettyUrl(value: string): string;

package/dist/url.js

@@ -0,0 +1,20 @@
+/*
+ * Normalizacja adresów dla karty POI — pure TS. Wydzielone z `map-poi-card.component.ts`,
+ * żeby dało się to testować `node --test` bez ciągnięcia Angulara.
+ */
+const HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+const SAFE_SCHEME = /^(https?:|mailto:|tel:)/i;
+/**
+ * Adres bez schematu dostaje `https://` — inaczej przeglądarka potraktuje go jak ścieżkę względną.
+ * Schemat spoza allowlisty (np. `javascript:`) traktujemy jak brak schematu — bezpieczny
+ * fallback zamiast przepuszczenia surowej wartości do `[href]`/`[src]`/`navigator.share()`.
+ */
+export function normalizeUrl(value) {
+    if (!HAS_SCHEME.test(value))
+        return `https://${value}`;
+    return SAFE_SCHEME.test(value) ? value : `https://${value.replace(HAS_SCHEME, '')}`;
+}
+/** Wersja adresu do pokazania: bez schematu i bez końcowego ukośnika. */
+export function prettyUrl(value) {
+    return value.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').replace(/\/$/, '');
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@konce-pt/map",
+  "version": "0.8.0",
+  "description": "Map core for Koncept UI — projection and bounds maths, marker clustering, opening hours, marker markup, plus the Leaflet and Google engine adapters. Framework-free TypeScript, zero runtime dependencies.",
+  "license": "MIT",
+  "author": "konce.pt",
+  "homepage": "https://ui.konce.pt/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/konce-pt/koncept-ui.git",
+    "directory": "packages/map"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/konce-pt/koncept-ui/-/issues"
+  },
+  "keywords": [
+    "map",
+    "leaflet",
+    "markers",
+    "design-system",
+    "koncept-ui",
+    "kpt"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "leaflet": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "leaflet": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/leaflet": "^1.9.22",
+    "leaflet": "^1.9.4",
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  }
+}