@konce-pt/react 0.8.1 → 0.8.3

package/dist/icon/llms.txt

@@ -0,0 +1,66 @@
+# KptIcon (@konce-pt/react)
+
+An inline SVG icon (Tabler Icons — MIT). The size follows `font-size` (1em) or the `size` prop;
+the colour comes from `currentColor`.
+Import: `import { KptIcon } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-icon-host" aria-hidden="true">
+      <svg class="kpt-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor">…</svg>
+    </span>
+
+## Props
+- `name`: string — the icon name from the registry (required)
+- `size`: string — a CSS length (e.g. '1.25rem'); by default inherited from `font-size`
+- `className`, `ref` and every other `<span>` prop go to the host
+
+## The registry
+The built-in set (84 icons) works with no setup. It covers both what the library's own components
+draw and the staples of an application shell — sun, moon, bell, settings, users, user-circle,
+logout, layout-dashboard, home, activity, chart-bar, arrow-up-right, brand-github and the like —
+so a typical admin panel never needs the full set.
+
+The full Tabler set (5130 icons) is opt-in, and there are two paths. `@konce-pt/react/icons`
+exposes every icon as its own export, so importing by name lets the bundler keep only what you
+used:
+
+    // main.tsx — production: two icons reach the bundle.
+    import { LayoutDashboard, Rocket } from '@konce-pt/react/icons';
+    import { registerKptIcons } from '@konce-pt/react';
+
+    registerKptIcons([LayoutDashboard, Rocket]);
+
+    // main.tsx — prototype: every icon, about 1.2 MB.
+    import { registerKptTablerIcons } from '@konce-pt/react/icons';
+
+    registerKptTablerIcons();
+
+`registerKptIcons` is the one that shrinks: it takes the data as an argument and imports nothing
+from the Tabler subpath, so the bundle follows your imports. Passing the namespace object
+(`import * as tabler`) registers everything — a namespace handed to a function blocks static
+analysis, so it is the explicit form of the prototype path, not a smaller one.
+
+Export names are PascalCase because `kebab-case` is not a legal identifier and camelCase would
+collide with keywords (`function`, `package`, `switch`). Each icon carries its own registry name,
+so `BrandHtml5` registers as `brand-html5`.
+
+The registry is a module singleton, not a context: icons are global to the application, so there is
+nothing to provide. `KptIcon` subscribes to it, so icons registered after the first render appear
+without a manual refresh. Register your own with `registerKptIcons({ name: '<path … />' })`.
+
+An unknown name renders an empty host rather than throwing — a missing icon never takes the page
+down with it.
+
+## Security
+Registry content reaches `innerHTML`; `registerKptIcons` sanitizes it to the SVG geometry
+allowlist, but call it only with developer-controlled, build-time content, never straight from a
+CMS, an API or an upload.
+
+## Examples
+    <KptIcon name="menu" />
+    <KptIcon name="check" size="1.25rem" />
+    <KptButton><KptIcon name="phone" /> Call</KptButton>
+
+## Accessibility
+The host carries `aria-hidden="true"` — an icon is decoration. Put the accessible name on the
+control around it (`aria-label` on the button), not on the icon.

package/dist/icon-button/llms.txt

@@ -0,0 +1,38 @@
+# KptIconButton (@konce-pt/react)
+
+An icon-only button. Import: `import { KptIconButton } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-icon-button-host">
+      <button class="kpt-icon-button" type="button" data-variant="text" data-size="md" data-shape="round" aria-label="Settings">
+        …icon…
+      </button>
+    </span>
+
+## Props
+- `variant`: the same union as `KptButton` — 'filled' | 'tonal' | 'outline' | 'text' | 'danger'
+  (default 'text')
+- `size`: 'sm' | 'md' | 'lg' (default 'md')
+- `shape`: 'round' | 'square' (default 'round')
+- `loading`: boolean — a spinner instead of the icon, sets `aria-busy` and disables the button
+- `aria-label`: string — REQUIRED by the type
+- `hostProps` — props for the `.kpt-icon-button-host` wrapper
+- `className`, `ref` and every other `<button>` prop go to the inner `<button>`
+
+## The label is required by the type
+`aria-label` is not optional in `KptIconButtonProps`: a button with no text has no accessible name,
+and that is the most common accessibility bug in this family. TypeScript refuses the component
+without it, so the mistake cannot reach the browser.
+
+## Examples
+    <KptIconButton aria-label="Settings"><KptIcon name="menu" /></KptIconButton>
+    <KptIconButton variant="filled" shape="square" aria-label="Delete"><KptIcon name="x" /></KptIconButton>
+    <KptIconButton loading aria-label="Saving" />
+
+## Tokens
+The same button tokens as `KptButton` (`--kpt-button-*` for each variant), plus the size and shape
+geometry from the shared stylesheet.
+
+## Accessibility
+A native `<button>` with a mandatory `aria-label`. In `loading` the icon is replaced by a spinner
+and the button is disabled with `aria-busy="true"`.

package/dist/icons-entry/public-api.d.ts

@@ -1,9 +1,13 @@
-export { KPT_TABLER_ICONS, KPT_TABLER_ICON_NAMES } from '@konce-pt/icons/tabler';
+export * from '@konce-pt/icons/tabler';
 /**
  * Rejestruje pełny zestaw Tabler Icons (5130), dzięki czemu `KptIcon` może użyć dowolnej
  * ikony po nazwie. Wywołaj raz, w wejściu aplikacji — rejestr jest globalny, więc nie ma
  * potrzeby owijać drzewa żadnym providerem.
  *
+ * Wciąga komplet (~1,2 MB), więc to ścieżka prototypowa. W produkcji zaimportuj ikony
+ * po nazwie i podaj je do `registerKptIcons([...])` z rdzenia `@konce-pt/react` — ta funkcja
+ * nie importuje pełnego zestawu, więc bundler zostawia wyłącznie użyte ikony.
+ *
  * @example
  * // main.tsx
  * import { registerKptTablerIcons } from '@konce-pt/react/icons';

package/dist/icons-entry/public-api.js

@@ -4,12 +4,18 @@
  */
 import { KPT_TABLER_ICONS } from '@konce-pt/icons/tabler';
 import { registerKptIcons } from "../icon/icon-registry.js";
-export { KPT_TABLER_ICONS, KPT_TABLER_ICON_NAMES } from '@konce-pt/icons/tabler';
+// `export *` udostępnia 5130 ikon jako osobne eksporty (import po nazwie wchodzi do bundla
+// pojedynczo) obok dwóch eksportów zbiorczych, które wciągają komplet.
+export * from '@konce-pt/icons/tabler';
 /**
  * Rejestruje pełny zestaw Tabler Icons (5130), dzięki czemu `KptIcon` może użyć dowolnej
  * ikony po nazwie. Wywołaj raz, w wejściu aplikacji — rejestr jest globalny, więc nie ma
  * potrzeby owijać drzewa żadnym providerem.
  *
+ * Wciąga komplet (~1,2 MB), więc to ścieżka prototypowa. W produkcji zaimportuj ikony
+ * po nazwie i podaj je do `registerKptIcons([...])` z rdzenia `@konce-pt/react` — ta funkcja
+ * nie importuje pełnego zestawu, więc bundler zostawia wyłącznie użyte ikony.
+ *
  * @example
  * // main.tsx
  * import { registerKptTablerIcons } from '@konce-pt/react/icons';

package/dist/image/llms.txt

@@ -0,0 +1,46 @@
+# KptImage (@konce-pt/react)
+
+An image with an optional full-screen preview.
+Import: `import { KptImage } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-image-host">
+      <div class="kpt-image kpt-image--preview" style="width:240px">
+        <img class="kpt-image__img" src="…" alt="…">
+        <div class="kpt-image__mask" aria-hidden="true">…zoom-in…</div>
+      </div>
+      <!-- open: -->
+      <div class="kpt-image__overlay">
+        <button class="kpt-image__close">…</button>
+        <img class="kpt-image__full" src="…" alt="…">
+      </div>
+    </div>
+
+## Props
+- `src`: string (required); `alt`: string
+- `width`: string | null — a CSS length, e.g. `'240px'`
+- `preview`: boolean — a click opens the overlay
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The overlay closes around the photo, not on it
+The click on `.kpt-image__full` stops propagating, so only the dark area around the image closes
+the preview — clicking the photo itself (to look closer, to drag it) must not dismiss it. The × is
+there for the explicit way out.
+
+## The mask is decorative
+The zoom-in overlay is `aria-hidden`: it repeats what the cursor (`zoom-in`) already says and would
+only add noise for a screen reader.
+
+## Examples
+    <KptImage src="/photo.jpg" alt="Photo" preview width="240px" />
+    <KptImage src="/logo.svg" alt="Logo" />
+
+## i18n
+The close button label comes from `common.close`.
+
+## Tokens
+The radius `--kpt-radius-md`, the mask and the overlay are black at 40% / 80% via `color-mix`.
+
+## Accessibility
+`alt` goes to both the thumbnail and the full-size image; the close button is labelled from the
+dictionary.

package/dist/input/llms.txt

@@ -0,0 +1,54 @@
+# KptInput (@konce-pt/react)
+
+The Koncept UI text field. It renders a native `<input>` inside a `.kpt-input-host` wrapper.
+Import: `import { KptInput } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-input-host">
+      <input class="kpt-input__field" id="…" type="text">
+    </span>
+
+## Props
+- `type`: 'text' | 'email' | 'password' | 'number' | 'search' | 'tel' | 'url' | 'time' (default 'text')
+- `value` / `defaultValue` — controlled or uncontrolled, exactly like a native input
+- `onValueChange(value)` — the value alone; `onChange` still fires with the full event
+- `onTouch()` — fires on blur, the moment the field becomes touched
+- `required`: boolean — see the note below
+- `invalid`: boolean, `touched`: boolean — the error state
+- `hostProps` — props for the `.kpt-input-host` wrapper
+- `className`, `ref`, `name`, `placeholder`, `autoComplete` and every other `<input>` prop go to
+  the inner `<input>`
+
+## Controlled and uncontrolled
+Pass `value` and the field is controlled. Pass `defaultValue` (or nothing) and the value belongs
+to the DOM, so a native `<form>`, `<form action={…}>`, a form reset and React Hook Form's
+`register()` all work without an adapter — there is no internal mirror of the value to fight with.
+
+## The error state
+`aria-invalid="true"` is set when `invalid` is true. Pass `touched` as well to reproduce the
+Angular port's gate — the error then shows only after the field has been touched, like the native
+`:user-invalid`. With `touched` omitted there is nothing to gate on, so `invalid` decides alone;
+that is the common case in React, where the form library already knows when an error is ready.
+The style hangs off `aria-invalid`, never off a class.
+
+## `required` is `aria-required`
+The native `required` attribute is deliberately NOT set: it would block the submit event and start
+the browser's own validation next to yours. Screen readers still announce the field as required.
+
+## Inside KptFormField
+The field takes its `id` from the wrapper through context, so `label[for]` is wired with no
+configuration. An explicit `id` prop still wins.
+
+## Examples
+    <KptInput name="email" type="email" placeholder="jan@firma.pl" />
+    <KptInput value={name} onValueChange={setName} />
+    <KptFormField label="E-mail" error={err}>
+      <KptInput type="email" invalid={!!err} onTouch={markTouched} />
+    </KptFormField>
+
+## Tokens
+`--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}`.
+
+## Accessibility
+A native `<input>` — full keyboard and screen reader support. `aria-required` marks the field as
+required, `aria-invalid` marks it as erroneous, and the focus ring comes from `@konce-pt/styles`.

package/dist/input-mask/llms.txt

@@ -0,0 +1,37 @@
+# KptInputMask (@konce-pt/react)
+
+A text field with a character mask.
+Import: `import { KptInputMask } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-input-mask-host">
+      <input class="kpt-input-mask__input" type="text" placeholder="(999) 999-99-99">
+    </span>
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — the formatted text
+- `mask`: string — `9` a digit, `a` a letter, `*` alphanumeric; everything else is a literal
+- `placeholder`: string — defaults to the mask itself, which doubles as a hint
+- `invalid`, `touched`, `onTouch()`
+- `className`, `ref` and every other `<input>` prop go to the input
+
+## The mask rewrites, it does not patch
+Every keystroke is re-formatted from scratch: only characters matching the next token are taken
+from the input, literals are inserted by the mask. Typing the formatted form and pasting the raw
+digits therefore produce the same result, and deleting a literal cannot leave a hole in the
+pattern. Characters that match nothing are skipped rather than rejected, so stray letters around a
+number still format.
+
+Like the OTP field, the DOM is synced by hand when the mask drops a character — the value did not
+change, so React would not re-render and the character would linger on screen.
+
+## Examples
+    <KptInputMask mask="(999) 999-99-99" value={phone} onValueChange={setPhone} />
+    <KptInputMask mask="aa-9999" value={code} onValueChange={setCode} />
+
+## Tokens
+`--kpt-form-field-{bg,text,placeholder,border,border-focus,border-error,radius}`.
+
+## Accessibility
+A native text input; the mask doubles as the placeholder, so the expected shape is visible before
+typing starts.

package/dist/input-number/llms.txt

@@ -0,0 +1,44 @@
+# KptInputNumber (@konce-pt/react)
+
+A number field with stepper arrows. Import: `import { KptInputNumber } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-input-number-host">
+      <div class="kpt-input-number">
+        <button class="kpt-input-number__btn" aria-label="Decrease">…</button>
+        <input class="kpt-input-number__input" type="text" inputmode="decimal" value="12 zł">
+        <button class="kpt-input-number__btn" aria-label="Increase">…</button>
+      </div>
+    </div>
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — `number | null`
+- `min`, `max`, `step` (default 1)
+- `placeholder`, `suffix` — text shown after the number, e.g. ' szt.' or 'ms'
+- `showButtons`: boolean (default true) — `false` leaves the bare field
+- `disabled`, `invalid`, `touched`, `onTouch()`
+- `locale`, `dictionary` — i18n overrides for this component only
+
+## Null is a value
+The value is `number | null`, not `number`: an empty field means "no value", which is not the same
+as zero. Clearing the input yields `null`, and the stepper starts from `min` (or 0) when it has
+nothing to step from.
+
+## A text input, not a number input
+The field is `type="text"` with `inputmode="decimal"`, so the suffix can live inside it and a comma
+works as the decimal separator — typing "12,5 zł" parses correctly. A native `type="number"` would
+reject both. Values out of range are clamped on input, not rejected.
+
+## i18n
+The stepper labels come from `inputNumber.decrement` and `inputNumber.increment`.
+
+## Examples
+    <KptInputNumber value={qty} onValueChange={setQty} min={0} max={99} />
+    <KptInputNumber value={price} onValueChange={setPrice} showButtons={false} suffix=" zł" />
+
+## Tokens
+`--kpt-form-field-{bg,text,border,border-focus,border-error,radius}`.
+
+## Accessibility
+The stepper buttons carry labels from the dictionary and go `disabled` at the limits, so the
+keyboard never lands on a control that cannot do anything.

package/dist/input-otp/llms.txt

@@ -0,0 +1,43 @@
+# KptInputOtp (@konce-pt/react)
+
+A one-time code field (OTP / PIN) — N separate boxes, auto-advance and paste.
+Import: `import { KptInputOtp } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-input-otp-host">
+      <div class="kpt-input-otp">
+        <input class="kpt-input-otp__cell" type="text" inputmode="numeric" maxlength="1" value="1">
+        …N cells…
+      </div>
+    </div>
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — one string, the characters joined
+- `length`: number (default 6)
+- `integerOnly`: boolean — digits only, and a numeric keyboard on mobile
+- `disabled`, `invalid`, `touched`, `onTouch()`
+
+## One string, N boxes
+The value is a single string while the UI is N inputs, so a gap in the middle has to be
+expressible. Writing pads with spaces, replaces the character and trims trailing spaces — that way
+a code with a hole round-trips and a single character does not turn into one followed by blanks.
+
+The DOM of a cell is also synced by hand after a rejected character: the value did not change, so
+React has nothing to re-render, and the typed character would otherwise stay on screen.
+
+## Keyboard and paste
+A character moves focus to the next cell; Backspace in an empty cell moves back; ArrowLeft and
+ArrowRight walk the cells; focus selects the content so typing overwrites. Pasting fills the whole
+code at once — with `integerOnly` everything non-numeric is stripped first, so a copied
+"123-456" still lands correctly.
+
+## Examples
+    <KptInputOtp value={code} onValueChange={setCode} length={6} integerOnly />
+    <KptInputOtp value={code} onValueChange={setCode} length={4} />
+
+## Tokens
+`--kpt-form-field-{bg,text,border,border-focus,border-error,radius}`.
+
+## Accessibility
+Native inputs with `inputmode` matched to the allowed characters, so a phone shows the numeric
+keypad for a PIN instead of the full keyboard.

package/dist/internal/use-breakpoint.js

@@ -18,20 +18,28 @@ export const KPT_BREAKPOINTS = {
  * komponenty — tak samo jak memoizacja w `KptBreakpointObserver` po stronie Angulara.
  */
 const stores = new Map();
+/**
+ * Zastępczy magazyn dla środowisk bez `matchMedia`. Jedna instancja, bo `useSyncExternalStore`
+ * przepina nasłuch przy każdej zmianie tożsamości `subscribe`.
+ */
+const UNSUPPORTED = { subscribe: () => () => { }, getSnapshot: () => false };
 function storeFor(query) {
     const cached = stores.get(query);
     if (cached)
         return cached;
-    const list = typeof window === 'undefined' ? null : window.matchMedia(query);
-    const store = list
-        ? {
-            subscribe: (onChange) => {
-                list.addEventListener('change', onChange);
-                return () => list.removeEventListener('change', onChange);
-            },
-            getSnapshot: () => list.matches,
-        }
-        : { subscribe: () => () => { }, getSnapshot: () => false };
+    // Sam brak `window` nie wystarcza: jsdom go dostarcza, ale bez `matchMedia` — bez sprawdzenia
+    // metody każdy test dotykający `KptAppShell` wywala się na TypeError. Wyniku nie zapisujemy
+    // w cache'u, żeby stub podstawiony później (typowy `setup` testów) został podchwycony.
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+        return UNSUPPORTED;
+    const list = window.matchMedia(query);
+    const store = {
+        subscribe: (onChange) => {
+            list.addEventListener('change', onChange);
+            return () => list.removeEventListener('change', onChange);
+        },
+        getSnapshot: () => list.matches,
+    };
     stores.set(query, store);
     return store;
 }

package/dist/knob/llms.txt

@@ -0,0 +1,46 @@
+# KptKnob (@konce-pt/react)
+
+A knob — pick a value along an SVG arc, by dragging or with the arrow keys.
+Import: `import { KptKnob } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-knob-host">
+      <div class="kpt-knob" role="slider" tabindex="0" aria-valuenow="40">
+        <svg viewBox="0 0 96 96">
+          <path class="kpt-knob__range" d="M …" />
+          <path class="kpt-knob__value" d="M …" />
+          <text class="kpt-knob__text">40%</text>
+        </svg>
+      </div>
+    </div>
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — the number
+- `min` (0), `max` (100), `step` (1)
+- `size`: px (96) — the side of the SVG square; `stroke`: px (10) — arc thickness
+- `suffix`: string appended to the value in the middle; `showValue`: boolean (default true)
+- `disabled`, `invalid`, `touched`, `onTouch()`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The gap at the bottom
+The arc is a full circle minus a 45° gap at the bottom, so its start and end are distinguishable.
+A pointer inside that gap has no value of its own — it is snapped to the nearer end, otherwise
+dragging across the bottom would jump between minimum and maximum.
+
+## Dragging listens on the window
+`pointermove` / `pointerup` are attached to `window`, not to the knob: the pointer leaves the
+circle during almost every drag, and the value must keep following it. Both listeners are removed
+on `pointerup`, which is also where `onTouch` fires — one touch per drag, not per pixel.
+
+## Examples
+    <KptKnob value={level} onValueChange={setLevel} min={0} max={100} step={5} suffix="%" />
+    <KptKnob value={level} onValueChange={setLevel} size={64} stroke={6} showValue={false} />
+
+## Tokens
+The background arc `--kpt-color-border`, the value `--kpt-color-primary`, the text
+`--kpt-color-on-surface`.
+
+## Accessibility
+`role="slider"` with `aria-valuemin` / `aria-valuemax` / `aria-valuenow`; arrows step by `step`,
+Home and End jump to the bounds. `disabled` sets `aria-disabled` and drops the knob out of the
+tab order.

package/dist/listbox/listbox.d.ts

@@ -2,7 +2,7 @@ import { type ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptOption } from '../shared/types.ts';
 export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'>, KptI18nOverrides {
-    options?: KptOption<T>[];
+    options?: readonly KptOption<T>[];
     value?: T | T[] | null;
     defaultValue?: T | T[] | null;
     onValueChange?: (value: T | T[] | null) => void;

package/dist/listbox/llms.txt

@@ -0,0 +1,39 @@
+# KptListbox (@konce-pt/react)
+
+A selection list shown in full, with no dropdown. Single or multiple selection, optional filter.
+Import: `import { KptListbox } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-listbox-host">
+      <div class="kpt-listbox" role="listbox" aria-multiselectable="false">
+        <div class="kpt-listbox__filter">…icon + input…</div>
+        <div class="kpt-listbox__items">
+          <button class="kpt-listbox__item is-selected" role="option" aria-selected="true">Admin</button>
+        </div>
+      </div>
+    </div>
+
+## Props
+- `options`: `KptOption<T>[]`
+- `value` / `defaultValue` / `onValueChange` — `T` (single) or `T[]` (multiple)
+- `multiple`, `filter`, `disabled`, `invalid`, `touched`, `onTouch()`
+- `locale`, `dictionary` — i18n overrides for this component only
+
+## Clicking the selection clears it
+In single mode clicking the already selected option deselects it. A listbox is often a filter, and a
+filter has to be clearable without a separate button.
+
+## i18n
+`listbox.search` (the filter placeholder) and `listbox.empty` (nothing matched).
+
+## Examples
+    <KptListbox options={roles} value={role} onValueChange={setRole} filter />
+    <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
+
+## Tokens
+`--kpt-color-surface`, `--kpt-color-border`, `--kpt-color-primary-subtle` (the selected row),
+`--kpt-form-field-border-error`.
+
+## Accessibility
+`role="listbox"` with `aria-multiselectable`; every option is a native button with
+`role="option"` and `aria-selected`, so the keyboard walks the list without extra handling.

package/dist/map/llms.txt

@@ -0,0 +1,108 @@
+# KptMap (@konce-pt/react/map)
+
+A map with configurable markers: categories carrying a colour and an icon, clustering with a count,
+a details popup whose content depends on the category, a ready-made place card, a legend, an address
+search and adding locations with the right mouse button. The engine (Leaflet + OpenStreetMap or
+Google) comes from `@konce-pt/map`; the component knows nothing about it beyond the `KptMapEngine`
+interface.
+
+Import: `import { KptMap, createLeafletEngine } from '@konce-pt/react/map';`
+
+## Requirements
+1. The **optional** `leaflet` dependency — the library does not install it: `pnpm add leaflet`
+2. Its stylesheet: `import 'leaflet/dist/leaflet.css';`
+3. An engine factory on the `engine` prop: `engine={() => createLeafletEngine()}`
+
+Leaflet is loaded with a dynamic `import()`, so an app that never renders a map does not download
+it. Without the package the component still imports and compiles — only rendering the map ends with
+a readable message.
+
+## Props
+- `locations`: `readonly KptMapLocation<T>[]` — **required**
+- `categories`: `readonly KptMapCategory[]` — **required**
+- `engine`: `KptMapEngineFactory` — **required**; a factory, not an instance, because every map
+  needs its own object. Read once, at mount.
+- `country`: string = `'PL'` — the initial view preset; an unknown code falls back to Poland
+- `view`, `bounds` — an explicit view or extent; they override `country`
+- `restrictToCountry`: boolean — blocks panning outside the country's bounds
+- `cluster`: boolean = true, `clusterOptions`, `clusterColorBy`: `'dominant' | 'none'`
+- `legend`, `legendCounts`: boolean = true
+- `hiddenCategories` / `defaultHiddenCategories` / `onHiddenCategoriesChange` — the ids hidden in
+  the legend, controlled or uncontrolled
+- `showUserLocation`, `followUser`: boolean; `geolocation`: `KptMapGeolocationPort | null`
+- `allowCreate`: boolean — the "Add location" menu under the right mouse button
+- `search`: boolean, `searchPlaceholder`, `searchOptions`, `searchZoom`, `searchMarker`
+- `geocoder`: `KptMapGeocoderPort | null` — this map's geocoder; it feeds both the search and the
+  address suggestions in the create form
+- `popupLayout`: `'plain' | 'card'`; `distanceFrom`: `KptLatLng | null`
+- `height`: string = `'480px'`; `tileUrl`, `attribution` (ignored by the Google engine)
+- `renderPopup`, `renderCreateForm` — see below
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Events
+`onLocationClick`, `onClusterClick`, `onLocationCreate`, `onSearchSelect`, `onViewChange`,
+`onUserPositionChange`, `onUserLocationError`.
+
+`onLocationCreate` gives `{ at, categoryId, value }` — the component appends **nothing** to
+`locations`; the application is the source of truth.
+
+## Render props instead of templates
+The Angular port picks a popup template per category (`kptMapPopup category="…"`). React has one
+prop and a `switch`: `renderPopup({ location, data, category, distance, close })` — the category
+travels in the context, and the type of `data` follows the map's generic without an extra input.
+
+    <KptMap
+      engine={engine}
+      locations={locations}
+      categories={categories}
+      renderPopup={({ location, data, category }) =>
+        category?.id === 'dc' ? <ChargerPopup data={data} /> : <strong>{location.title}</strong>
+      }
+    />
+
+`renderCreateForm({ at, category, submit, close })` replaces the schema-built form the same way.
+
+## Ports are props, not DI
+Angular injects `KPT_MAP_ENGINE`, `KPT_MAP_GEOCODER` and `KPT_MAP_GEOLOCATION`. React has no
+injector, so all three arrive as props — and the geocoder was already per-map in Angular for a
+licensing reason (a Google geocoder may only be paired with a Google map), so nothing is lost.
+
+The ports themselves are promise-shaped rather than `Observable`-shaped: `reverse()`, `search()`
+and `resolve()` return promises and take an `AbortSignal`, which is what `fetch` speaks anyway.
+
+    import { createNominatimGeocoder, browserGeolocation } from '@konce-pt/react/map';
+
+    <KptMap geocoder={createNominatimGeocoder()} geolocation={browserGeolocation()} … />
+
+`createGeocoderStub()` and `geolocationStub(at)` cover demos and tests.
+
+## Mounting is serialised
+A map engine marks its container as taken for the life of the map, and React's strict mode mounts
+every effect twice in a row. The component therefore chains mount and teardown on one promise: the
+second mount waits for the first teardown to finish, instead of failing with "Map container is
+already initialized".
+
+## Sub-components
+- `KptMapLegend` — the legend on its own, when you want it somewhere other than under the map
+  (`hiddenCategories` instead of Angular's `hidden`: `hidden` on a DOM element is a boolean and
+  would clash with the `<div>` prop)
+- `KptMapPoiCard` — the ready-made place card for `popupLayout="card"`
+- `KptMapSearch` — the address field alone
+- `KptMapCreateDialog`, `KptMapHoursField`, `KptMapImageField` — the schema-built form and its two
+  non-trivial field types
+
+## Validation without a form framework
+The create dialog is built from `category.fields`. The Angular port stands on Signal Forms; here the
+model is plain state and the rules are a map of functions beside it. The contract is the same:
+declared once with the schema, and the "do not shout in red" gate lives in presentation — an error
+shows after the field is touched or after a failed submit.
+
+## Tokens
+`--kpt-map-height`, `--kpt-map-popup-width`, `--kpt-map-popup-width-card`,
+`--kpt-map-popup-max-height`, `--kpt-map-poi-media-radius`, plus the semantic colour roles used by
+the categories.
+
+## Accessibility
+Zoom and "my location" are real buttons with labels; the popup is a `role="dialog"` with the
+location's title; the create menu is a `role="menu"`; the search field is a combobox with
+`aria-activedescendant` and a polite status line. Marker markup carries `role="img"` and a label.