@konce-pt/angular 0.6.1 → 0.7.5

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@konce-pt/angular",
-  "version": "0.6.1",
+  "version": "0.7.5",
   "description": "Open-source Angular 22 component library on Signals & Signal Forms — 70+ components, rich data table, zoneless, fully tokenized. Selektory kpt-*, klasy Kpt*.",
   "license": "MIT",
   "author": "konce.pt",
-  "homepage": "https://gitlab.com/konce-pt/koncept-ui#readme",
+  "homepage": "https://ui.konce.pt/",
   "repository": {
     "type": "git",
     "url": "git+https://gitlab.com/konce-pt/koncept-ui.git",
@@ -26,68 +26,58 @@
     "cdk",
     "data-table",
     "kpt",
-    "koncept-ui"
+    "koncept-ui",
+    "map",
+    "leaflet",
+    "openstreetmap"
   ],
   "sideEffects": false,
-  "files": [
-    "dist"
-  ],
-  "module": "./dist/fesm2022/konce-pt-angular.mjs",
-  "types": "./dist/types/konce-pt-angular.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/types/konce-pt-angular.d.ts",
-      "default": "./dist/fesm2022/konce-pt-angular.mjs"
-    },
-    "./icons": {
-      "types": "./dist/types/konce-pt-angular-icons.d.ts",
-      "default": "./dist/fesm2022/konce-pt-angular-icons.mjs"
-    },
-    "./charts": {
-      "types": "./dist/types/konce-pt-angular-charts.d.ts",
-      "default": "./dist/fesm2022/konce-pt-angular-charts.mjs"
-    },
-    "./grid": {
-      "types": "./dist/types/konce-pt-angular-grid.d.ts",
-      "default": "./dist/fesm2022/konce-pt-angular-grid.mjs"
-    }
-  },
   "peerDependencies": {
     "@angular/cdk": "^22.0.0",
     "@angular/common": "^22.0.0",
     "@angular/core": "^22.0.0",
-    "@angular/forms": "^22.0.0"
+    "@angular/forms": "^22.0.0",
+    "leaflet": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "leaflet": {
+      "optional": true
+    }
   },
   "dependencies": {
     "tslib": "^2.3.0"
   },
-  "devDependencies": {
-    "@angular/cdk": "22.1.0",
-    "@angular/common": "22.1.0",
-    "@angular/compiler": "22.1.0",
-    "@angular/compiler-cli": "22.1.0",
-    "@angular/core": "22.1.0",
-    "@angular/forms": "22.1.0",
-    "@storybook/angular": "10.5.6",
-    "@tabler/icons": "^3.46.0",
-    "ng-packagr": "22.1.0",
-    "rxjs": "^7.8.0",
-    "sass": "^1.77.0",
-    "storybook": "10.5.6",
-    "typescript": "~6.0.3"
-  },
-  "nx": {
-    "targets": {
-      "build": {
-        "outputs": [
-          "{projectRoot}/dist"
-        ],
-        "cache": true
-      }
+  "module": "fesm2022/konce-pt-angular.mjs",
+  "typings": "types/konce-pt-angular.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/konce-pt-angular.d.ts",
+      "default": "./fesm2022/konce-pt-angular.mjs"
+    },
+    "./charts": {
+      "types": "./types/konce-pt-angular-charts.d.ts",
+      "default": "./fesm2022/konce-pt-angular-charts.mjs"
+    },
+    "./grid": {
+      "types": "./types/konce-pt-angular-grid.d.ts",
+      "default": "./fesm2022/konce-pt-angular-grid.mjs"
+    },
+    "./icons": {
+      "types": "./types/konce-pt-angular-icons.d.ts",
+      "default": "./fesm2022/konce-pt-angular-icons.mjs"
+    },
+    "./map": {
+      "types": "./types/konce-pt-angular-map.d.ts",
+      "default": "./fesm2022/konce-pt-angular-map.mjs"
+    },
+    "./roadmap": {
+      "types": "./types/konce-pt-angular-roadmap.d.ts",
+      "default": "./fesm2022/konce-pt-angular-roadmap.mjs"
     }
   },
-  "scripts": {
-    "build": "ng-packagr -p ng-package.json",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
-  }
+  "type": "module",
+  "scripts": {}
 }

package/roadmap/src/lib/llms.txt

@@ -0,0 +1,112 @@
+# KptRoadmap (kpt-roadmap)
+
+Roadmapa — wiersze zadań na poziomej osi czasu (widok typu Gantt). Kolumna etykiet i nagłówek osi
+są przyklejone przy przewijaniu, paski pozycjonowane procentowo, zależności rysuje warstwa SVG.
+Import: `import { KptRoadmap } from '@konce-pt/angular/roadmap';`
+
+## Selektor
+`kpt-roadmap` — standalone, OnPush, zoneless. Generyk `KptRoadmap<TItem, TGroup>` typuje pole `meta`.
+
+## Wejścia
+- `config`: KptRoadmapConfig (wymagane) — dane i wszystkie opcje
+- `scrollHeight`: string | null — stała wysokość, np. '420px'; włącza przyklejony nagłówek
+- `labelWidth`: string — szerokość kolumny etykiet (domyślnie '14rem')
+- `cellWidthPx`: number | null — szerokość kolumny osi; brak ⇒ wartość zależna od zoomu
+- `showToday`: boolean — znacznik „dziś" (domyślnie true)
+- `virtual`: boolean — renderuje tylko widoczne wiersze; warto od ~100 wierszy
+
+## Model / zdarzenia
+- `collapsedGroups`: model<string[]> — dwukierunkowe id zwiniętych grup
+- `itemClick`: output<KptRoadmapItem>
+- `rangeChange`: output<KptTimeRange> — wyliczony zakres osi
+
+## KptRoadmapConfig
+- `items`: KptRoadmapItem[] (wymagane)
+- `groups?`: KptRoadmapGroup[]
+- `links?`: KptRoadmapLink[] — zależności podane grafowo
+- `zoom?`: 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' (domyślnie 'week')
+- `range?`: { start?: number; end?: number } — brakujący kraniec wyliczany z danych
+- `locale?`: string; `today?`: Date | number | string
+- `timeline?`, `rows?`, `dependencies?`, `interaction?` — opcje szczegółowe
+
+### KptRoadmapItem
+- `id`: string, `label`: string (wymagane)
+- `start`: Date | number | string; `end?`: to samo — brak `end` oznacza kamień milowy
+- `sublabel?`, `icon?`, `disabled?`
+- `variant?`: 'neutral' | 'primary' | 'success' | 'danger' | 'warning' | 'info'
+- `color?`: string — dowolny kolor CSS, nadpisuje `variant`
+- `progress?`: number 0..1 — wypełnienie wewnątrz paska
+- `groupId?`: string; `dependsOn?`: (string | KptRoadmapLink)[] — sam string oznacza zależność 'FS'
+- `milestone?`: boolean — wymusza romb
+- `meta?`: TItem
+- Pola `draggable`, `resizable`, `locked`, `constraints` są zarezerwowane pod edycję i dziś ignorowane.
+
+### KptRoadmapGroup
+- `id`, `label` (wymagane); `sublabel?`, `parentId?`, `collapsed?`, `variant?`, `color?`
+- `summary?`: 'auto' | 'none' — 'auto' rysuje pasek zbiorczy od min(start) do max(end) dzieci
+
+### KptTimelineOptions (`config.timeline`)
+- `weekendDays?`: number[] (domyślnie [0, 6]); `weekPrefix?`: string (domyślnie z i18n)
+- `workHours?`: { from, to, mode?: 'skip' | 'dim', skipWeekends? } — tylko przy `zoom: 'hour'`;
+  'skip' wycina noce z osi, 'dim' zostawia kolumny wyszarzone
+- `positionMode?`: 'uniform' (domyślnie) | 'linear'
+- `bandUnit?`: jednostka górnego poziomu nagłówka; `maxCells?`: number (domyślnie 4000)
+
+### KptRoadmapRowOptions (`config.rows`)
+- `mode?`: 'row-per-item' (domyślnie) | 'pack' — 'pack' układa nienachodzące zadania w jednym wierszu
+- `itemHeight?`, `groupHeight?`, `laneHeight?`, `packMinGapMs?`
+- `showUngroupedHeader?`, `ungroupedLabel?`
+
+## Przykład
+
+    <kpt-roadmap [config]="roadmap" scrollHeight="420px" />
+
+    roadmap: KptRoadmapConfig = {
+      zoom: 'week',
+      groups: [{ id: 'app', label: 'Aplikacja' }],
+      items: [
+        { id: 'auth', label: 'Logowanie', start: '2026-08-24', end: '2026-08-31',
+          groupId: 'app', variant: 'success', progress: 1 },
+        { id: 'ship', label: 'Wydanie', start: '2026-09-14', groupId: 'app',
+          variant: 'warning', dependsOn: ['auth'] },
+      ],
+    };
+
+## Zachowanie
+- Oś liczona w czasie lokalnym; numeracja tygodni wg ISO 8601 (tydzień 1 zawiera pierwszy czwartek roku).
+- Tryb 'uniform' daje kolumny równej szerokości mimo zmiany czasu i różnej długości miesięcy;
+  wewnątrz kolumny pozycja jest interpolowana liniowo, więc zadanie może zaczynać się w środku dnia.
+- Zmiana roku: mocniejsza pionowa linia i czarny znacznik z rokiem na pierwszym paśmie danego roku.
+  Przy zoomie tygodniowym granica liczona po roku tygodnia ISO, więc W53 nie trafia do kolejnego roku.
+- Item wystający poza zakres osi jest ścinany od strony przycięcia.
+- Podpowiedzi to dyrektywa `kptTooltip` (nie natywny `title`): dymek pojawia się od razu, jest
+  stylowany tokenami i działa też na focusie z klawiatury.
+- Zasada: dymek pokazuje to, czego nie widać. Paski, etykiety wierszy i pasma nagłówka mają go
+  z `kptTooltipOnlyWhenTruncated`, więc podpowiedź wyskakuje wyłącznie przy tekście uciętym
+  wielokropkiem — sprawdzanym przy najechaniu, więc reagującym na zmianę szerokości i zoomu.
+  Kamienie milowe i komórki nagłówka mają dymek bezwarunkowo: romb nie pokazuje tekstu w ogóle,
+  a komórka dopowiada rok, którego w „W35 / 24.08–30.08" nie widać.
+- Zależności: 'FS' (domyślna), 'SS', 'FF', 'SF'; naruszone są rysowane linią przerywaną w kolorze danger.
+- Elementy z niepoprawną datą lub zduplikowanym `id` są pomijane, z ostrzeżeniem w trybie deweloperskim.
+
+## i18n
+Klucze `roadmap.*`: `empty`, `week`, `today`, `milestone`, `expandGroup`, `collapseGroup`.
+Nazwy miesięcy i dni tygodnia pochodzą z `Intl` wg `config.locale` albo locale z `KptI18n`,
+więc mają formę zgodną z ortografią języka (po polsku małą literą, po angielsku wielką).
+W nagłówku pierwszy znak jest kapitalizowany przez `::first-letter`, żeby wygląd osi był ten sam
+niezależnie od języka; sam tekst pozostaje niezmieniony, więc podpowiedzi i odczyt przez czytnik
+ekranu dostają formę oryginalną.
+
+## Tokeny
+Powierzchnie `--kpt-color-surface{,-variant,-sunken,-hover}`, obrys `--kpt-color-border{,-strong}`,
+paski wg wariantu `--kpt-color-{primary,success,danger,warning,info,muted}`.
+Etykieta paska jest biała, ale wariant `neutral` ma jasne tło, więc jego napis używa
+`--kpt-color-on-muted`. Pasek zbiorczy grupy w wariancie `neutral` rysuje się kolorem
+`--kpt-color-on-surface-muted` — `--kpt-color-muted` byłby nieodróżnialny od tła wiersza.
+Dalej:
+znacznik roku na inwersji `--kpt-color-on-surface` / `--kpt-color-surface`.
+Rozmiary: `--kpt-roadmap-label-w`, `--kpt-roadmap-cell-w` (obie można nadpisać z zewnątrz).
+
+## Do zrobienia (roadmap)
+Przeciąganie i zmiana zakresu pasków, rysowanie zależności myszą, dodawanie wierszy —
+typy (`KptRoadmapChange`, `constraints`, `interaction`) są już częścią API.

package/src/lib/app-shell/llms.txt

@@ -0,0 +1,89 @@
+# KptAppShell (kpt-app-shell)
+
+Szkielet aplikacji: pasek u góry, panel boczny, treść. Responsywny bez konfiguracji.
+Import: `import { KptAppShell, KptShellNavToggle } from '@konce-pt/angular';`
+
+## Selektor
+`kpt-app-shell`
+
+## Wejścia / wyjścia
+- `sidenavOpen`: model<boolean> (domyślnie `true`) — stan panelu ZADOKOWANEGO
+  (oraz wymuszonego trybu `over`); dwukierunkowe `[(sidenavOpen)]`
+- `sidenavCompactOpen`: model<boolean> (domyślnie `false`) — stan NAKŁADKI w trybie `auto`
+- `sidenavMode`: `'auto' | 'side' | 'over'` (domyślnie **`'auto'`**)
+- `sidenavBreakpoint`: `'sm'|'md'|'lg'|'xl'|'2xl'` (domyślnie `'lg'`) — od tego progu w górę
+  tryb `auto` dokuje panel, poniżej robi z niego nakładkę
+- `sidenavRailBreakpoint`: ten sam zbiór albo `null` (domyślnie `null`) — włącza szynę ikon
+  w paśmie od `sidenavBreakpoint` do tego progu; wartość musi być WYŻSZA niż `sidenavBreakpoint`
+- `sidenavLabel`: string — etykieta a11y panelu; puste = `appShell.navigation` ze słownika
+- `sidenavId`: readonly string — identyfikator panelu (`aria-controls`)
+- `isOverlay()`, `isSidenavOpen()`: Signal<boolean> — stan efektywny dla bieżącego układu
+- `toggleSidenav()`, `openSidenav()`, `closeSidenav()` — trafiają w stan właściwy dla układu
+
+## Sloty projekcji
+- `[kptShellToolbar]` → pasek u góry
+- `[kptShellSidenav]` → panel boczny
+- treść domyślna → obszar główny
+
+## Przykład
+    <kpt-app-shell [(sidenavOpen)]="navOpen">
+      <kpt-toolbar kptShellToolbar elevated>
+        <kpt-icon-button kptShellNavToggle variant="text" ariaLabel="Menu">
+          <kpt-icon name="menu" />
+        </kpt-icon-button>
+      </kpt-toolbar>
+      <kpt-sidenav kptShellSidenav>
+        <a href="#"><kpt-icon name="list" /> <span kptNavLabel>Pulpit</span></a>
+      </kpt-sidenav>
+      <router-outlet />
+    </kpt-app-shell>
+
+## Trzy pasma trybu 'auto'
+| szerokość | układ | co robi zamknięcie |
+|---|---|---|
+| `< sidenavBreakpoint` | nakładka + scrim | panel wyjeżdża poza krawędź (stan: `sidenavCompactOpen`) |
+| `>= sidenavBreakpoint`, `< sidenavRailBreakpoint` | szyna ikon | panel zwęża się do `--kpt-sidenav-rail-width` |
+| `>= sidenavRailBreakpoint` (lub brak szyny) | pełny panel | panel chowa się w całości |
+
+## Dlaczego DWA stany otwarcia
+„Otwarty" znaczy co innego po obu stronach progu: na desktopie panel domyślnie stoi otwarty,
+na telefonie domyślnie musi być schowany. Gdyby oba układy dzieliły jeden model, wejście na wąski
+ekran musiałoby nadpisać stan aplikacji, a powrót na szeroki nie miałby czego przywrócić.
+Rozdzielenie sprawia, że intencja z desktopu przeżywa zwężenie i rozszerzenie okna za darmo.
+
+Przycisk `kptShellNavToggle` sam trafia we właściwy stan — nie pisz `navOpen.set(...)` ręcznie,
+bo na wąskim ekranie ustawisz nie ten model.
+
+## Konwencja treści menu (potrzebna tylko dla szyny)
+- `[kptNavLabel]` — tekst pozycji; w szynie chowany techniką „visually hidden", więc pozycja
+  zachowuje dostępną nazwę dla czytnika ekranu.
+- `[kptNavSection]` — nagłówek grupy; chowany tak samo.
+
+To płaskie atrybuty (jak `kptShellToolbar` czy `kptToolbarSpacer`), nie dyrektywy — nic nie trzeba
+importować. Bez nich szyna pokaże ucięty tekst zamiast ikony. W szynie warto opatrzyć pozycje
+`kptTooltip`, bo widać sam znak.
+
+## Zachowanie
+- O układzie decyduje wyłącznie CSS (`@media`), więc nic nie migocze przed hydracją i całość
+  działa na SSR. JavaScript odpowiada tylko za to, który stan przełącza przycisk.
+- Zamknięty panel wypada z kolejki Tab przez `visibility: hidden` (nie `inert`) — jest poprawny
+  już na pierwszej klatce.
+- Otwarta nakładka nakłada `inert` na treść (`<main>`), więc Tab nie wchodzi pod scrim.
+- `Escape` zamyka nakładkę; klik w scrim też.
+- Kierunek wysuwu idzie za `dir` (RTL wyjeżdża z prawej).
+- Wysokość: `100dvh` z fallbackiem `100vh`.
+- **Nie** zamyka menu po nawigacji — shell nie wie, co w danej aplikacji nią jest.
+  Zrób to sam: `if (shell.isOverlay()) shell.closeSidenav();`.
+
+## Tryby wymuszone (zgodność wsteczna)
+`sidenavMode="side"` i `"over"` ignorują szerokość okna i czytają `sidenavOpen`, dokładnie jak
+przed wprowadzeniem `auto`. Ustaw `"side"`, jeśli aplikacja sama zarządza responsywnością —
+inaczej dostaniesz dwie warstwy tej samej logiki.
+
+## Tokeny
+`--kpt-sidenav-width` (16rem), `--kpt-sidenav-rail-width` (4rem), `--kpt-z-overlay`,
+`--kpt-color-overlay-scrim`, `--kpt-elevation-3`, `--kpt-motion-duration-base`.
+
+## Odłożone
+Focus trap i zwrot fokusu do przycisku po zamknięciu (spójnie z `kpt-drawer`, który też ich
+nie ma — to osobne zadanie dla całego repo). `<aside>` ma już `tabindex="-1"`.

package/src/lib/breakpoint/llms.txt

@@ -0,0 +1,45 @@
+# KptBreakpointObserver
+
+Serwis (root) zamieniający media query na sygnały. Jedyny w bibliotece sposób na zapytanie
+„jak szerokie jest okno" z poziomu TypeScriptu.
+
+## API
+
+    inject(KptBreakpointObserver)
+
+- `up(bp: KptBreakpoint): Signal<boolean>` — `(min-width: <próg>px)`, mobile-first.
+- `down(bp: KptBreakpoint): Signal<boolean>` — `(max-width: <próg - 0.02>px)`; odjęcie 0.02px
+  sprawia, że pasma `up`/`down` nie nakładają się na ułamkowych szerokościach (zoom, DPI).
+- `matches(query: string): Signal<boolean>` — dowolne media query.
+
+`KptBreakpoint` = `'sm' | 'md' | 'lg' | 'xl' | '2xl'`; progi w `KPT_BREAKPOINTS`
+(640 / 768 / 1024 / 1280 / 1536 px).
+
+## Skąd biorą się wartości
+
+Z tokenów: `packages/tokens/tokens/primitives/breakpoint.json` → `scripts/gen-tokens.mjs`
+generuje `breakpoint/breakpoints.generated.ts` (dla JS) i `styles/_breakpoints.generated.scss`
+(dla `@media` w SCSS komponentów). Oba pliki są commitowane i **nie edytuje się ich ręcznie** —
+zmiana progu idzie przez token i `pnpm nx build angular`. Dzięki jednemu źródłu CSS biblioteki
+i jej JavaScript nie mogą rozjechać się cicho.
+
+## SSR
+
+Poza przeglądarką każdy sygnał to stałe `false`. Nie buduj na nim układu strony — od tego jest
+CSS (`@media`), inaczej dostaniesz migotanie przed hydracją. Serwis służy do zachowań:
+w którą stronę ma zadziałać przycisk, czy zamykać panel po nawigacji, co odłożyć na później.
+
+## Przykład
+
+    @Component({ /* … */ })
+    export class Header {
+      private readonly breakpoints = inject(KptBreakpointObserver);
+      readonly isDesktop = this.breakpoints.up('lg');
+      readonly isCompact = this.breakpoints.down('md');
+    }
+
+## Uwagi
+
+- Zapytania są memoizowane per string — `up('lg')` w dziesięciu komponentach to jeden
+  `MediaQueryList` i jeden nasłuch; nie trzeba tego cache'ować u siebie.
+- Sprzątanie idzie przez `DestroyRef` root injectora, więc nie ma czego odsubskrybować.

package/{dist/src → src}/lib/datepicker/llms.txt

@@ -23,6 +23,9 @@ Import: `import { KptDatepicker } from '@konce-pt/angular';`
 - `monthDisplay`: 'long' | 'number' (domyślnie 'long') — w trybie 'month' i etykietach miesięcy: słownie (styczeń) lub liczbą (01)
 - `displayFormat`: 'pl' | 'iso' (domyślnie 'pl') — format wyświetlania i domyślnego placeholdera
 - `disabled`/`invalid`/`touched`: boolean; output `touch`.
+- `ariaLabel`: string|null — nazwa dostępna, gdy pola nie opisuje `<label for>`
+  (np. dwie godziny w jednym wierszu edytora). Bez niej czytnik ekranu ogłasza samą wartość.
+- Ikona w polu: kalendarz, a w trybie 'time' zegar.
 - Panel: nawigacja (‹ ›) miesięcy/lat/dekad wg trybu; tarcza zegara z „Gotowe"; przycisk czyszczenia (×).
 
 ## i18n

package/src/lib/dialog/llms.txt

@@ -0,0 +1,68 @@
+# KptDialog (kpt-dialog)
+
+Okno modalne na natywnym `<dialog>` (focus trap, Esc, backdrop w standardzie).
+Import: `import { KptDialog } from '@konce-pt/angular';`
+
+## Selektor
+`kpt-dialog`
+
+## Wejścia
+- `open`: model<boolean> — dwukierunkowe `[(open)]`
+- `header`: string; `dismissible`: boolean (Esc/× zamyka; domyślnie true)
+
+## Sloty
+- treść domyślna → body; element z atrybutem `kptDialogFooter` → stopka
+
+## Przykład
+    <kpt-dialog [(open)]="confirmOpen" header="Usunąć?">
+      Nieodwracalne.
+      <div kptDialogFooter>
+        <kpt-button variant="text" (click)="confirmOpen.set(false)">Anuluj</kpt-button>
+        <kpt-button variant="danger" (click)="remove()">Usuń</kpt-button>
+      </div>
+    </kpt-dialog>
+
+## Tokeny
+`--kpt-color-surface-raised`, `--kpt-color-overlay-scrim` (::backdrop), `--kpt-elevation-4`.
+Uwaga: globalny reset zeruje margin — komponent przywraca `margin:auto` (centrowanie).
+
+## Kontrolki na CDK Overlay w środku okna
+
+`kpt-dialog` stoi na natywnym `<dialog>` i otwiera się przez `showModal()`, co wynosi je
+do **warstwy szczytowej** przeglądarki — a ta jest ponad całym drzewem dokumentu i żaden
+`z-index` jej nie przebije. Kontener CDK Overlay wisi domyślnie na `<body>`, więc panele
+`kpt-select`, `kpt-datepicker`, `kpt-autocomplete` i `kpt-menu` otwierałyby się w środku
+okna NIEWIDOCZNE, schowane za jego tłem.
+
+Dlatego `kpt-dialog` na czas otwarcia przenosi kontener overlayów do wnętrza `<dialog>`
+i oddaje go na miejsce przy zamknięciu (również gdy komponent zostanie zniszczony
+z otwartym oknem). Nie trzeba nic konfigurować — kontrolki overlayowe działają w oknie
+tak samo jak poza nim.
+
+## Układ i przewijanie
+
+Otwarte okno jest kolumną flex: nagłówek (`.kpt-dialog__header`) i stopka
+(`[kptDialogFooter]`) stoją nieruchomo, a przewija się wyłącznie `.kpt-dialog__body`.
+Pasek przewijania biegnie więc tylko wzdłuż treści, nie wzdłuż całego okna.
+
+Treść dostaje `flex: 0 1 auto` (domyślne) + `min-height: 0`, celowo **nie** `flex: 1`
+jak w `kpt-drawer`. Szuflada wypełnia wysokość ekranu, okno ma kurczyć się do treści:
+krótkie (`kpt-confirm` — dwa zdania i dwa przyciski) zostaje krótkie, długie zatrzymuje się
+na `max-height: calc(100vh - 4rem)` i przewija samą treść.
+
+Deklaracja `display: flex` jest scopowana `&[open]` i musi taka zostać. Regułę
+`dialog:not([open]) { display: none }` daje arkusz przeglądarki, a każda deklaracja
+autorska ją bije — także z `@layer`. Niescopowane `display: flex` zostawiłoby wszystkie
+zamknięte okna widoczne na stronie.
+
+`.kpt-dialog` nie dostaje `overflow: hidden` — kontener CDK Overlay jest na czas otwarcia
+przeniesiony do wnętrza `<dialog>` (patrz sekcja wyżej), więc przycięcie okna ucięłoby
+panele `kpt-select` czy `kpt-datepicker`. Do samego przewijania nie jest potrzebne:
+po przejściu na flex nic nie wystaje poza okno.
+
+Przypięty pasek akcji wewnątrz treści (np. „Anuluj / Zapisz" w `kpt-map-create-dialog`)
+robi się przez `position: sticky` — kontenerem przewijania jest `.kpt-dialog__body`.
+Ujemne marginesy boczne muszą zgadzać się z jego paddingiem (`--kpt-space-6`),
+a przesunięcie `bottom` musi być lustrem ujemnego marginesu dolnego
+(`bottom: calc(var(--kpt-space-6) * -1)`) — przyklejanie liczy się dla marginesowego
+pudełka, więc przy `bottom: 0` pod paskiem przesuwałby się skrawek treści.

package/{dist/src → src}/lib/form-field/llms.txt

@@ -24,12 +24,30 @@ Import: `import { KptFormField } from '@konce-pt/angular';`
 Warianty float mają animowane przejście etykiety (pozycja spoczynkowa w miejscu placeholdera →
 uniesiona). Uniesienie następuje przy focusie kontrolki **lub** gdy pole ma wartość. Wykrywanie
 wypełnienia jest po stronie komponentu (zdarzenia `input`/`change` + wartość początkowa) — **nie**
-wymaga ustawiania placeholdera na kontrolce. Uwaga: wzorzec działa dla kontrolek `input`/`textarea`.
+wymaga ustawiania placeholdera na kontrolce.
 
     <kpt-form-field label="E-mail" labelType="over">
       <kpt-input />
     </kpt-form-field>
 
+### Kontrolki bez natywnego `input`/`textarea`
+
+Wartości `kpt-select` nie da się odczytać z DOM (panel żyje w overlayu), więc taka kontrolka
+zgłasza wypełnienie sama — dostarcza token `KPT_FORM_FIELD_CONTROL` z sygnałem `filled`.
+`kpt-select` robi to z pudełka; własna kontrolka wymaga:
+
+    import { KPT_FORM_FIELD_CONTROL, type KptFormFieldControl } from '@konce-pt/angular';
+
+    @Component({
+      providers: [{ provide: KPT_FORM_FIELD_CONTROL, useExisting: forwardRef(() => MyControl) }],
+    })
+    export class MyControl implements KptFormFieldControl {
+      readonly filled = computed(() => this.value() != null);
+    }
+
+Gdy kontrolka dostarczy token, `kpt-form-field` przestaje zaglądać do DOM i ufa wyłącznie
+sygnałowi `filled` — dlatego etykieta unosi się natychmiast po zmianie wartości.
+
 ## Projekcja
 Kontrolkę umieszcza się w treści (ng-content):
 
@@ -45,6 +63,11 @@ Kontrolkę umieszcza się w treści (ng-content):
       return s.touched() && s.invalid() ? s.errors()[0]?.message ?? null : null;
     });
 
+Bramka `touched()` dotyczy wyłącznie komunikatu — walidatorów nie warunkuj (`when:` na
+`state.touched()` sprawia, że `valid()` kłamie na nietkniętym formularzu). Kontrolki `kpt-*`
+same bramkują swój stan wizualny tak samo. Pełny przepływ submit: sekcja
+`## Formularz od zera (Signal Forms)` w głównym llms.txt.
+
 ## Tokeny
 `--kpt-form-field-label`, `--kpt-form-field-hint`, `--kpt-form-field-error`, `--kpt-color-danger`.
 Warianty float dodatkowo: `--kpt-form-field-placeholder` (etykieta spoczynkowa),

package/{dist/src → src}/lib/icon/llms.txt

@@ -14,7 +14,8 @@ kolor z `currentColor`. Import: `import { KptIcon } from '@konce-pt/angular';`
 menu, x, chevron-up, chevron-down, chevron-left, chevron-right, check, search,
 grip-vertical, info, alert-triangle, circle-check, circle-x, calendar, copy, link, code,
 star, phone, map-pin, world, clock, align-left, align-center, align-right, align-justified,
-palette, highlight, clipboard, clipboard-text, table (pełna lista w `icons.ts`).
+palette, highlight, clipboard, clipboard-text, table, mail, share, external-link, crosshair
+(pełna lista w `icons.ts`).
 
 ## Pełny zestaw (5130 ikon Tabler)
 Opcjonalny entry point `@konce-pt/angular/icons` (pobierany tylko przy imporcie):

package/{dist/src → src}/lib/input/llms.txt

@@ -17,11 +17,18 @@ Bez `ControlValueAccessor`. Import: `import { KptInput } from '@konce-pt/angular
       email(p.email, { message: 'Podaj poprawny adres e-mail' });
     });
 
-    // szablon (imports: [KptInput, FormField])
-    <kpt-input [formField]="loginForm.email" type="email" id="f-email" />
+    // szablon (imports: [KptInput, FormField, FormRoot, KptButton])
+    <form [formRoot]="loginForm" (submit)="onSubmit()">
+      <kpt-input [formField]="loginForm.email" type="email" id="f-email" />
+      <kpt-button type="submit" [disabled]="loginForm().invalid()">Zaloguj</kpt-button>
+    </form>
+
+`[formRoot]` sam ustawia `novalidate` i woła `submit()`; `submit()` sam robi `markAsTouched()`.
+Nie warunkuj walidatorów przez `when: state.touched()` — psuje to `valid()`.
+Pełny przepływ: sekcja `## Formularz od zera (Signal Forms)` w głównym llms.txt.
 
 ## Wejścia prezentacyjne
-- `type`: 'text'|'email'|'password'|'number'|'search'|'tel'|'url' (domyślnie 'text')
+- `type`: 'text'|'email'|'password'|'number'|'search'|'tel'|'url'|'time' (domyślnie 'text')
 - `placeholder`: string
 - `id`: string — trafia na wewnętrzny `<input>` (do `label[for]`); host go nie nosi
 - `ariaLabel`: string | null
@@ -34,5 +41,8 @@ Bez `ControlValueAccessor`. Import: `import { KptInput } from '@konce-pt/angular
 `--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}`.
 
 ## Dostępność
-- `aria-invalid="true"` przy nieprawidłowym stanie; `blur` oznacza pole jako dotknięte.
+- `aria-invalid="true"` dopiero gdy pole jest nieprawidłowe **i** dotknięte (`blur`) — świeży,
+  pusty formularz nie jest malowany na czerwono.
+- `aria-required="true"` przy `required` — celowo nie natywny atrybut `required`, który
+  blokowałby zdarzenie submit i uruchamiał walidację przeglądarki obok Signal Forms.
 - Komunikaty błędów wyświetla zwykle `kpt-form-field` (`role="alert"`).

package/src/lib/input-number/llms.txt

@@ -0,0 +1,61 @@
+# KptInputNumber (kpt-input-number)
+
+Pole liczbowe ze strzałkami krokowania na Signal Forms. Wartość = number | null.
+`showButtons="false"` daje wariant bez strzałek — do zakresów „od–do".
+Import: `import { KptInputNumber } from '@konce-pt/angular';`
+
+## Wejścia / model
+- `value`: model<number | null> (lub `formField`)
+- `min`/`max`: number | undefined; `step`: number (domyślnie 1)
+- `suffix`: string (np. ' %'); `placeholder`: string
+- `showButtons`: boolean (domyślnie `true`) — `false` chowa strzałki `−`/`+`; treść pola
+  wyrównuje się wtedy do lewej, jak w `kpt-input` (modyfikator `.kpt-input-number--plain`)
+- `disabled`/`invalid`/`touched`: boolean; `touch`: output
+
+## Przykład
+    <kpt-input-number [formField]="f.qty" [min]="0" [max]="99" [step]="1" />
+    <kpt-input-number [(value)]="qty" suffix=" szt." />
+    <kpt-input-number [formField]="f.priceFrom" [showButtons]="false" suffix=" zł" />
+
+## Zakres „od–do" (walidacja między polami)
+
+Dwa osobne pola formularza; regułę „do ≥ od" wpina się przez `validateTree` na korzeniu.
+Błąd celuje się w konkretne pole właściwością `fieldTree` — inaczej wylądowałby na formularzu
+i nie pokazałby się pod żadną kontrolką.
+
+    import { form, min, validateTree } from '@angular/forms/signals';
+
+    model = signal({ priceFrom: null as number | null, priceTo: null as number | null });
+
+    rangeForm = form(this.model, (path) => {
+      min(path.priceFrom, 0, { message: 'Wartość nie może być ujemna' });
+      min(path.priceTo, 0, { message: 'Wartość nie może być ujemna' });
+
+      validateTree(path, (ctx) => {
+        const from = ctx.valueOf(path.priceFrom);
+        const to = ctx.valueOf(path.priceTo);
+        if (from === null || to === null || from <= to) return null;
+        return {
+          kind: 'range',
+          message: 'Wartość „do" nie może być mniejsza niż „od"',
+          fieldTree: ctx.fieldTreeOf(path.priceTo),   // błąd ląduje na polu „do"
+        };
+      });
+    });
+
+    // szablon — dwie kolumny od md (klasy utility z @konce-pt/grid)
+    <form class="kpt-grid" [formRoot]="rangeForm" (submit)="onSubmit()">
+      <kpt-form-field class="kpt-col-12 kpt-col-md-6" label="Cena od" [error]="fromError()">
+        <kpt-input-number [formField]="rangeForm.priceFrom" [min]="0" [showButtons]="false" suffix=" zł" />
+      </kpt-form-field>
+      <kpt-form-field class="kpt-col-12 kpt-col-md-6" label="Cena do" [error]="toError()">
+        <kpt-input-number [formField]="rangeForm.priceTo" [min]="0" [showButtons]="false" suffix=" zł" />
+      </kpt-form-field>
+    </form>
+
+`ctx.valueOf(path.x)` czyta wartość innego pola, `ctx.fieldTreeOf(path.x)` wskazuje pole
+docelowe błędu. Komunikaty podaje się przez `errorFor()` z bramką `touched()` — walidatorów
+nie warunkuj. Pełny przepływ submit: `## Formularz od zera (Signal Forms)` w głównym llms.txt.
+
+## Tokeny
+Pole `--kpt-form-field-*`; przyciski `--kpt-color-muted`.

package/{dist/src → src}/lib/select/llms.txt

@@ -18,6 +18,15 @@ Wymaga stylów overlay CDK w aplikacji: `import '@angular/cdk/overlay-prebuilt.c
 - `disabled`/`invalid`/`touched`: boolean; output `touch`.
 - Klawiatura: Enter/↓ otwiera, ↑/↓ nawigacja, Enter wybiera, Esc zamyka.
 
+## Float Label
+W `kpt-form-field` z `labelType` `over`/`in`/`on` etykieta unosi się także po wybraniu opcji —
+select dostarcza token `KPT_FORM_FIELD_CONTROL` z sygnałem `filled` (wartości w overlayu nie da
+się odczytać z DOM). Nic nie trzeba konfigurować:
+
+    <kpt-form-field label="Kraj" labelType="on">
+      <kpt-select [formField]="f.country" [options]="countries" />
+    </kpt-form-field>
+
 ## i18n
 Etykiety „Szukaj…", „Brak wyników" i aria usuwania chipa z i18n (namespace `select`).
 Domyślnie EN; konfiguracja przez `provideKptI18n` — patrz `i18n/llms.txt`.

package/src/lib/sidenav/llms.txt

@@ -0,0 +1,29 @@
+# KptSidenav (kpt-sidenav)
+
+Panel boczny — stylowany kontener nawigacji, zwykle w slocie `kptShellSidenav`
+komponentu `kpt-app-shell`. Import: `import { KptSidenav } from '@konce-pt/angular';`
+
+## Selektor
+`kpt-sidenav`
+
+## Treść
+Dowolna zawartość (ng-content). Elementy `<a>` mają wbudowane style pozycji nawigacji
+(hover z `--kpt-color-muted`).
+
+## Przykład
+    <kpt-sidenav kptShellSidenav>
+      <a href="#">Pulpit</a>
+      <a href="#">Ustawienia</a>
+    </kpt-sidenav>
+
+## Szyna ikon (kpt-app-shell)
+Jeśli shell ma włączone `sidenavRailBreakpoint`, opatrz tekst pozycji atrybutem `kptNavLabel`,
+a nagłówek grupy `kptNavSection` — w zwiniętej szynie zostaje sama ikona, a etykieta jest
+chowana technicznie (visually hidden), więc czytnik ekranu wciąż zna nazwę pozycji:
+
+    <a href="#"><kpt-icon name="list" /> <span kptNavLabel>Pulpit</span></a>
+
+To płaskie atrybuty, nie dyrektywy — nic nie trzeba importować. Bez ikony szyna będzie pusta.
+
+## Tokeny
+`--kpt-sidenav-{bg,fg,border,width,rail-width}` (szerokość ustawia `kpt-app-shell`).