@konce-pt/react 0.11.2 → 0.14.0

package/dist/map/map-search.js

@@ -1,76 +1,103 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
+import { KptSpeechButton } from "../speech/speech-button.js";
 /**
  * Wyszukiwarka adresów: pole z podpowiedziami z geokodera. Wynik wyboru leci w `onSelect`,
- * a co z nim zrobić — decyduje rodzic (`KptMap` przenosi na niego widok).
+ * a co z nim zrobić - decyduje rodzic (`KptMap` przenosi na niego widok).
  *
  * Świadomie **nie** stoi na `KptAutocomplete`: tamten filtruje opcje po stronie klienta (wyniki
  * geokodera, tolerancyjne na literówki, wypadałyby z listy), a jego wartością jest sam `string`
- * — nie ma czym przewieźć współrzędnych.
+ * - nie ma czym przewieźć współrzędnych.
  *
  * @example
  * <KptMapSearch geocoder={geocoder} viewbox={bounds} onSelect={goTo} />
  */
-export function KptMapSearch({ geocoder = null, placeholder = '', minLength = 3, debounce = 300, limit = 5, countryCodes = null, viewbox = null, disabled = false, onSelect, onClear, locale: localeOverride, dictionary, className, ...rest }) {
+export function KptMapSearch({ geocoder = null, placeholder = '', minLength = 3, debounce = 300, limit = 5, countryCodes = null, viewbox = null, disabled = false, speech = false, speechLang, speechColor, onSelect, onClear, locale: localeOverride, dictionary, className, ...rest }) {
     const { t, locale } = useKptMessages({ locale: localeOverride, dictionary });
     const uid = useId();
     /** Tekst widoczny w polu. Wybór podpowiedzi wpisuje tu jego etykietę. */
     const [query, setQuery] = useState('');
     /**
      * Fraza do odpytania geokodera. Osobna od `query`, bo wybór podpowiedzi zmienia treść pola
-     * — a to nie może wywołać kolejnego zapytania o coś, co już znaleźliśmy.
+     * - a to nie może wywołać kolejnego zapytania o coś, co już znaleźliśmy.
      */
     const [term, setTerm] = useState('');
     const [results, setResults] = useState([]);
-    const [loading, setLoading] = useState(false);
-    /** Trwa dociąganie współrzędnych wybranej podpowiedzi — inny moment niż czekanie na listę. */
+    /** Trwa dociąganie współrzędnych wybranej podpowiedzi - inny moment niż czekanie na listę. */
     const [resolving, setResolving] = useState(false);
-    /** Czy jakieś zapytanie już wróciło — bez tego „brak wyników" mignąłby przed pierwszym. */
+    /** Czy jakieś zapytanie już wróciło - bez tego "brak wyników" mignąłby przed pierwszym. */
     const [searched, setSearched] = useState(false);
     const [open, setOpen] = useState(false);
     const [activeIndex, setActiveIndex] = useState(-1);
-    /** Nie udało się ustalić miejsca wybranej podpowiedzi — komunikat zamiast cichej ciszy. */
+    /** Nie udało się ustalić miejsca wybranej podpowiedzi - komunikat zamiast cichej ciszy. */
     const [unresolved, setUnresolved] = useState(false);
-    /** Przerywacz dociągania w locie — kolejny wybór i czyszczenie pola go używają. */
+    /** Przerywacz dociągania w locie - kolejny wybór i czyszczenie pola go używają. */
     const pending = useRef(null);
+    /** Pole - cel dyktowania (`speech`). */
+    const inputRef = useRef(null);
     const canSearch = !!geocoder?.search;
+    /*
+     * Zapytanie do geokodera jako wartość: nowa tożsamość = nowe zapytanie. `viewbox` i `countryCodes`
+     * wchodzą jako klucze tekstowe - rodzic podaje je zwykle świeżą tablicą w każdym renderze, a to
+     * restartowałoby odliczanie przy każdym ruchu mapy i zapytanie nigdy by nie wyszło.
+     */
+    const needle = term.trim();
+    const viewboxKey = viewbox ? JSON.stringify(viewbox) : '';
+    const countryKey = countryCodes?.join(',') ?? '';
+    const request = useMemo(() => {
+        if (!geocoder?.search || needle.length < minLength)
+            return null;
+        return {
+            geocoder,
+            needle,
+            options: {
+                language: locale,
+                limit,
+                viewbox: viewboxKey ? JSON.parse(viewboxKey) : undefined,
+                countryCodes: countryKey ? countryKey.split(',') : undefined,
+            },
+        };
+    }, [geocoder, needle, minLength, locale, limit, viewboxKey, countryKey]);
+    /** Zapytanie, na które przyszła już odpowiedź (albo błąd). */
+    const [settled, setSettled] = useState(null);
+    const loading = request !== null && settled !== request;
+    // Fraza za krótka (albo brak geokodera) - lista i stan wracają do zera. W renderze, nie w efekcie,
+    // żeby nie mignęła jedna klatka starych wyników.
+    const [hadRequest, setHadRequest] = useState(request !== null);
+    if (hadRequest !== (request !== null)) {
+        setHadRequest(request !== null);
+        if (!request) {
+            setResults([]);
+            setSearched(false);
+            setActiveIndex(-1);
+        }
+    }
     const busy = loading || resolving;
     const tooShort = query.trim().length > 0 && query.trim().length < minLength;
     const hasPanel = open && (tooShort || busy || results.length > 0 || searched);
-    const applyResults = useCallback((found) => {
-        // Podpowiedź bez współrzędnych ma sens tylko wtedy, gdy port umie ją uzupełnić —
-        // pozycja, która nie ma dokąd polecieć, jest gorsza od jej braku.
-        setResults(geocoder?.resolve ? found : found.filter((suggestion) => suggestion.at));
-        setLoading(false);
-        setSearched(true);
-        setActiveIndex(-1);
-        setOpen(true);
-    }, [geocoder]);
     // Odpytanie geokodera po odczekaniu `debounce` od ostatniego znaku. Sprzątanie kasuje
-    // zarówno niewystrzelony timer, jak i zapytanie w locie — adapter przerywa wtedy `fetch`.
+    // zarówno niewystrzelony timer, jak i zapytanie w locie - adapter przerywa wtedy `fetch`.
     useEffect(() => {
-        const needle = term.trim();
-        if (!geocoder?.search || needle.length < minLength) {
-            setResults([]);
-            setLoading(false);
-            setSearched(false);
-            setActiveIndex(-1);
+        if (!request)
             return;
-        }
-        setLoading(true);
+        const { geocoder: port, needle: phrase, options } = request;
+        const applyResults = (found) => {
+            // Podpowiedź bez współrzędnych ma sens tylko wtedy, gdy port umie ją uzupełnić -
+            // pozycja, która nie ma dokąd polecieć, jest gorsza od jej braku.
+            setResults(port.resolve ? found : found.filter((suggestion) => suggestion.at));
+            setSettled(request);
+            setSearched(true);
+            setActiveIndex(-1);
+            setOpen(true);
+        };
         const controller = new AbortController();
         const timer = setTimeout(() => {
-            geocoder
-                .search(needle, {
-                language: locale,
-                limit,
-                viewbox: viewbox ?? undefined,
-                countryCodes: countryCodes ?? undefined,
-                signal: controller.signal,
-            })
+            port
+                .search(phrase, { ...options, signal: controller.signal })
                 .then((found) => {
                 if (!controller.signal.aborted)
                     applyResults(found);
@@ -85,7 +112,7 @@ export function KptMapSearch({ geocoder = null, placeholder = '', minLength = 3,
             clearTimeout(timer);
             controller.abort();
         };
-    }, [term, geocoder, minLength, debounce, limit, viewbox, countryCodes, locale, applyResults]);
+    }, [request, debounce]);
     useEffect(() => () => pending.current?.abort(), []);
     const status = (() => {
         if (tooShort)
@@ -102,11 +129,11 @@ export function KptMapSearch({ geocoder = null, placeholder = '', minLength = 3,
     })();
     /**
      * Wybór podpowiedzi. Dostawca, który podał współrzędne na liście, emituje natychmiast;
-     * podpowiedź bez `at` trzeba najpierw uzupełnić — jedno wywołanie `resolve()` na *wybór*,
+     * podpowiedź bez `at` trzeba najpierw uzupełnić - jedno wywołanie `resolve()` na *wybór*,
      * nigdy w trakcie pisania.
      */
     const pick = (suggestion) => {
-        // Etykieta wraca do pola, ale `term` zostaje — inaczej wybór odpaliłby kolejne zapytanie.
+        // Etykieta wraca do pola, ale `term` zostaje - inaczej wybór odpaliłby kolejne zapytanie.
         setQuery(suggestion.label);
         setActiveIndex(-1);
         setUnresolved(false);
@@ -171,14 +198,14 @@ export function KptMapSearch({ geocoder = null, placeholder = '', minLength = 3,
             case 'Enter': {
                 const result = results[activeIndex];
                 if (result) {
-                    // Pole bywa w formularzu aplikacji — Enter nie ma go wysyłać.
+                    // Pole bywa w formularzu aplikacji - Enter nie ma go wysyłać.
                     event.preventDefault();
                     pick(result);
                 }
                 break;
             }
             case 'Escape':
-                // Pierwszy Esc zamyka listę, drugi czyści pole — jak w polu wyszukiwania przeglądarki.
+                // Pierwszy Esc zamyka listę, drugi czyści pole - jak w polu wyszukiwania przeglądarki.
                 if (open)
                     setOpen(false);
                 else if (query)
@@ -189,12 +216,12 @@ export function KptMapSearch({ geocoder = null, placeholder = '', minLength = 3,
         }
     };
     const optionId = (index) => `${uid}-opt-${index}`;
-    return (_jsxs("div", { className: cn('kpt-map-search', className), ...rest, children: [_jsxs("div", { className: "kpt-map-search__field", children: [_jsx("span", { className: "kpt-map-search__icon", "aria-hidden": "true", children: _jsx(KptIcon, { name: "search" }) }), _jsx("input", { className: "kpt-map-search__input", type: "text", autoComplete: "off", autoCapitalize: "off", spellCheck: false, role: "combobox", "aria-autocomplete": "list", id: uid, value: query, placeholder: placeholder || t('map.search.placeholder'), disabled: disabled || !canSearch, "aria-label": t('map.search.label'), "aria-expanded": hasPanel, "aria-busy": busy || undefined, "aria-controls": hasPanel ? `${uid}-panel` : undefined, "aria-activedescendant": activeIndex >= 0 ? optionId(activeIndex) : undefined, onChange: (event) => {
+    return (_jsxs("div", { className: cn('kpt-map-search', className), ...rest, children: [_jsxs("div", { className: "kpt-map-search__field", children: [_jsx("span", { className: "kpt-map-search__icon", "aria-hidden": "true", children: _jsx(KptIcon, { name: "search" }) }), _jsx("input", { ref: inputRef, className: "kpt-map-search__input", type: "text", autoComplete: "off", autoCapitalize: "off", spellCheck: false, role: "combobox", "aria-autocomplete": "list", id: uid, value: query, placeholder: placeholder || t('map.search.placeholder'), disabled: disabled || !canSearch, "aria-label": t('map.search.label'), "aria-expanded": hasPanel, "aria-busy": busy || undefined, "aria-controls": hasPanel && results.length && !tooShort && !busy ? `${uid}-list` : undefined, "aria-activedescendant": activeIndex >= 0 ? optionId(activeIndex) : undefined, onChange: (event) => {
                             setQuery(event.target.value);
                             setTerm(event.target.value);
                             setOpen(true);
                             setUnresolved(false);
-                        }, onFocus: () => setOpen(true), onBlur: () => setOpen(false), onKeyDown: onKeyDown }), query ? (_jsx("button", { className: "kpt-map-search__clear", type: "button", "aria-label": t('map.search.clear'), title: t('map.search.clear'), onClick: clear, children: _jsx(KptIcon, { name: "x" }) })) : null] }), hasPanel ? (_jsx("div", { className: "kpt-map-search__panel", id: `${uid}-panel`, children: tooShort ? (_jsx("p", { className: "kpt-map-search__note", children: t('map.search.minLength', { count: minLength }) })) : busy ? (_jsx("p", { className: "kpt-map-search__note", children: t('map.search.searching') })) : results.length ? (_jsx("ul", { className: "kpt-map-search__list", role: "listbox", "aria-label": t('map.search.results'), children: results.map((result, index) => (_jsxs("li", { className: cn('kpt-map-search__option', index === activeIndex && 'is-active'), role: "option", id: optionId(index), "aria-selected": index === activeIndex, onMouseDown: (event) => {
+                        }, onFocus: () => setOpen(true), onBlur: () => setOpen(false), onKeyDown: onKeyDown }), query ? (_jsx("button", { className: "kpt-map-search__clear", type: "button", "aria-label": t('map.search.clear'), title: t('map.search.clear'), onClick: clear, children: _jsx(KptIcon, { name: "x" }) })) : null, speech ? (_jsx(KptSpeechButton, { listeningColor: speechColor, target: inputRef, lang: speechLang, mode: "replace", continuous: false, size: "sm", unsupported: "hide", disabled: disabled || !canSearch, hostProps: { className: 'kpt-map-search__speech' } })) : null] }), hasPanel ? (_jsx("div", { className: "kpt-map-search__panel", id: `${uid}-panel`, children: tooShort ? (_jsx("p", { className: "kpt-map-search__note", children: t('map.search.minLength', { count: minLength }) })) : busy ? (_jsx("p", { className: "kpt-map-search__note", children: t('map.search.searching') })) : results.length ? (_jsx("ul", { className: "kpt-map-search__list", id: `${uid}-list`, role: "listbox", "aria-label": t('map.search.results'), children: results.map((result, index) => (_jsxs("li", { className: cn('kpt-map-search__option', index === activeIndex && 'is-active'), role: "option", id: optionId(index), "aria-selected": index === activeIndex, onMouseDown: (event) => {
                             event.preventDefault();
                             pick(result);
                         }, onMouseEnter: () => setActiveIndex(index), children: [_jsx("span", { className: "kpt-map-search__pin", "aria-hidden": "true", children: _jsx(KptIcon, { name: "map-pin" }) }), _jsx("span", { className: "kpt-map-search__label", children: result.label })] }, result.id))) })) : (_jsx("p", { className: "kpt-map-search__note", children: t('map.search.noResults') })) })) : null, _jsx("p", { className: "kpt-map-search__status", "aria-live": "polite", children: status })] }));

package/dist/map/map.d.ts

@@ -2,7 +2,8 @@ import type { KptClusterOptions, KptLatLng, KptMapBounds, KptMapCategory, KptMap
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptMapGeocoderPort, KptMapGeolocationPort } from './ports.ts';
-/** Kontekst treści popupu — odpowiednik kontekstu szablonu `kptMapPopup` z portu Angulara. */
+import type { KptSpeechColor } from '../speech/speech-button.tsx';
+/** Kontekst treści popupu - odpowiednik kontekstu szablonu `kptMapPopup` z portu Angulara. */
 export interface KptMapPopupContext<T> {
     location: KptMapLocation<T>;
     data: T | undefined;
@@ -11,7 +12,7 @@ export interface KptMapPopupContext<T> {
     distance: number | null;
     close: () => void;
 }
-/** Kontekst własnego formularza „dodaj lokalizację". */
+/** Kontekst własnego formularza "dodaj lokalizację". */
 export interface KptMapCreateFormApi {
     at: KptLatLng;
     category: KptMapCategory;
@@ -21,7 +22,7 @@ export interface KptMapCreateFormApi {
 export interface KptMapProps<T = unknown> extends Omit<ComponentPropsWithRef<'div'>, 'children' | 'onSelect'>, KptI18nOverrides {
     locations: readonly KptMapLocation<T>[];
     categories: readonly KptMapCategory[];
-    /** Kod kraju z presetów (`PL`, `DE`, `EU`…). Nieznany kod cofa się do Polski. */
+    /** Kod kraju z presetów (`PL`, `DE`, `EU`...). Nieznany kod cofa się do Polski. */
     country?: string;
     /** Jawny widok startowy; nadpisuje `country`. */
     view?: KptMapView | null;
@@ -36,16 +37,16 @@ export interface KptMapProps<T = unknown> extends Omit<ComponentPropsWithRef<'di
     /** Renderuje legendę pod mapą. */
     legend?: boolean;
     legendCounts?: boolean;
-    /** Identyfikatory ukrytych kategorii — kontrolowane albo niekontrolowane. */
+    /** Identyfikatory ukrytych kategorii - kontrolowane albo niekontrolowane. */
     hiddenCategories?: string[];
     defaultHiddenCategories?: string[];
     onHiddenCategoriesChange?: (hidden: string[]) => void;
     showUserLocation?: boolean;
     /** Przy każdej nowej pozycji centruje mapę na użytkowniku. */
     followUser?: boolean;
-    /** Źródło pozycji użytkownika. Bez niego kontrolka „moje położenie" nie ma czego pokazać. */
+    /** Źródło pozycji użytkownika. Bez niego kontrolka "moje położenie" nie ma czego pokazać. */
     geolocation?: KptMapGeolocationPort | null;
-    /** Włącza menu „Dodaj lokalizację" pod prawym przyciskiem myszy. */
+    /** Włącza menu "Dodaj lokalizację" pod prawym przyciskiem myszy. */
     allowCreate?: boolean;
     /** Pokazuje wyszukiwarkę adresów. Wymaga geokodera **z metodą `search()`**. */
     search?: boolean;
@@ -60,29 +61,35 @@ export interface KptMapProps<T = unknown> extends Omit<ComponentPropsWithRef<'di
     searchZoom?: number;
     /** Zostawia tymczasową pinezkę w znalezionym punkcie. */
     searchMarker?: boolean;
-    /** Geokoder tej mapy — obsługuje i wyszukiwarkę, i podpowiedzi adresu w formularzu. */
+    /** Mikrofon w wyszukiwarce - adres podyktowany zamiast wpisanego (patrz `KptMapSearch`). */
+    searchSpeech?: boolean;
+    /** Język dyktowania adresu (BCP 47); bez niego z `KptI18nProvider`. */
+    searchSpeechLang?: string;
+    /** Kolor "stop" i fali w trakcie nasłuchu; domyślnie kolor motywu. */
+    searchSpeechColor?: KptSpeechColor;
+    /** Geokoder tej mapy - obsługuje i wyszukiwarkę, i podpowiedzi adresu w formularzu. */
     geocoder?: KptMapGeocoderPort | null;
     /** `card` oddaje popup w całości treści: bez paddingu, szerszy, z przewijaniem. */
     popupLayout?: 'plain' | 'card';
     /** Punkt odniesienia dystansu w popupie; `null` = pozycja użytkownika. */
     distanceFrom?: KptLatLng | null;
     height?: string;
-    /** Bez znaczenia dla silnika Google — kafle i atrybucję dostarcza tam Google. */
+    /** Bez znaczenia dla silnika Google - kafle i atrybucję dostarcza tam Google. */
     tileUrl?: string | null;
     attribution?: string | null;
     /**
-     * Fabryka silnika tej mapy. W Reakcie nie ma DI, więc to jedyna droga — i dobrze:
+     * Fabryka silnika tej mapy. W Reakcie nie ma DI, więc to jedyna droga - i dobrze:
      * dwie mapy o różnych silnikach mieszczą się na stronie bez żadnych opakowań.
      * Czytana raz, przy inicjalizacji.
      */
     engine: KptMapEngineFactory;
     /** Treść popupu. Bez niej popup pokazuje tytuł i nazwę kategorii. */
     renderPopup?: (context: KptMapPopupContext<T>) => ReactNode;
-    /** Własny formularz „dodaj lokalizację"; jego obecność wyłącza formularz ze schemy. */
+    /** Własny formularz "dodaj lokalizację"; jego obecność wyłącza formularz ze schemy. */
     renderCreateForm?: (api: KptMapCreateFormApi) => ReactNode;
     onLocationClick?: (location: KptMapLocation<T>) => void;
     onClusterClick?: (cluster: KptMapCluster<T>) => void;
-    /** Komponent **nie dopisuje** nic do `locations` — źródłem prawdy jest aplikacja. */
+    /** Komponent **nie dopisuje** nic do `locations` - źródłem prawdy jest aplikacja. */
     onLocationCreate?: (event: KptMapCreateEvent) => void;
     /** Wybrano podpowiedź wyszukiwarki; mapa już przeniosła widok. */
     onSearchSelect?: (result: KptMapSearchResult) => void;
@@ -93,12 +100,17 @@ export interface KptMapProps<T = unknown> extends Omit<ComponentPropsWithRef<'di
     }) => void;
     onUserPositionChange?: (position: KptMapUserPosition | null) => void;
     onUserLocationError?: (error: KptMapGeolocationError) => void;
+    /**
+     * Silnika nie udało się uruchomić - brak paczki `leaflet`, odrzucony klucz Google. Błąd i tak
+     * trafia do konsoli; callback pozwala aplikacji pokazać własny komunikat zamiast szarego prostokąta.
+     */
+    onEngineError?: (error: unknown) => void;
 }
 /**
  * Mapa z konfigurowalnymi znacznikami: kategorie z kolorem i ikoną, grupowanie z licznikiem,
  * popup szczegółów, legenda, wyszukiwarka adresów i dodawanie lokalizacji prawym przyciskiem.
  *
- * Silnik (Leaflet albo Google) przychodzi propem `engine` z `@konce-pt/map` — ta sama warstwa,
+ * Silnik (Leaflet albo Google) przychodzi propem `engine` z `@konce-pt/map` - ta sama warstwa,
  * na której stoi port Angulara. Leaflet ładuje się dynamicznym `import()`, więc aplikacja bez
  * mapy go nie pobiera; wymaga też arkusza `leaflet/dist/leaflet.css`.
  *
@@ -110,4 +122,4 @@ export interface KptMapProps<T = unknown> extends Omit<ComponentPropsWithRef<'di
  *   renderPopup={({ location, data }) => <strong>{location.title}</strong>}
  * />
  */
-export declare function KptMap<T = unknown>({ locations, categories, country, view, bounds, restrictToCountry, cluster, clusterOptions, clusterColorBy, legend, legendCounts, hiddenCategories, defaultHiddenCategories, onHiddenCategoriesChange, showUserLocation, followUser, geolocation, allowCreate, search, searchPlaceholder, searchOptions, searchZoom, searchMarker, geocoder, popupLayout, distanceFrom, height, tileUrl, attribution, engine, renderPopup, renderCreateForm, onLocationClick, onClusterClick, onLocationCreate, onSearchSelect, onViewChange, onUserPositionChange, onUserLocationError, locale: localeOverride, dictionary, className, style, ...rest }: Readonly<KptMapProps<T>>): import("react").JSX.Element;
+export declare function KptMap<T = unknown>({ locations, categories, country, view, bounds, restrictToCountry, cluster, clusterOptions, clusterColorBy, legend, legendCounts, hiddenCategories, defaultHiddenCategories, onHiddenCategoriesChange, showUserLocation, followUser, geolocation, allowCreate, search, searchPlaceholder, searchOptions, searchZoom, searchMarker, searchSpeech, searchSpeechLang, searchSpeechColor, geocoder, popupLayout, distanceFrom, height, tileUrl, attribution, engine, renderPopup, renderCreateForm, onLocationClick, onClusterClick, onLocationCreate, onSearchSelect, onViewChange, onUserPositionChange, onUserLocationError, onEngineError, locale: localeOverride, dictionary, className, style, ...rest }: Readonly<KptMapProps<T>>): import("react").JSX.Element;