@konce-pt/angular 0.7.11 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konce-pt/angular",
-  "version": "0.7.11",
+  "version": "0.8.0",
   "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",
@@ -45,7 +45,14 @@
     }
   },
   "dependencies": {
-    "tslib": "^2.3.0"
+    "tslib": "^2.3.0",
+    "@konce-pt/chart": "0.8.0",
+    "@konce-pt/i18n": "0.8.0",
+    "@konce-pt/table": "0.8.0",
+    "@konce-pt/datetime": "0.8.0",
+    "@konce-pt/map": "0.8.0",
+    "@konce-pt/roadmap": "0.8.0",
+    "@konce-pt/icons": "0.8.0"
   },
   "module": "fesm2022/konce-pt-angular.mjs",
   "typings": "types/konce-pt-angular.d.ts",

package/roadmap/src/lib/llms.txt

@@ -1,112 +1,113 @@
 # 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.
+A roadmap — rows of tasks on a horizontal timeline (a Gantt-style view). The label column and the axis header
+stay stuck while scrolling, the bars are positioned as percentages, and dependencies are drawn by an SVG layer.
+The computation core lives in `@konce-pt/roadmap` — plain TypeScript, tested, shared with the React port.
 Import: `import { KptRoadmap } from '@konce-pt/angular/roadmap';`
 
-## Selektor
-`kpt-roadmap` — standalone, OnPush, zoneless. Generyk `KptRoadmap<TItem, TGroup>` typuje pole `meta`.
+## Selector
+`kpt-roadmap` — standalone, OnPush, zoneless. The generic `KptRoadmap<TItem, TGroup>` types the `meta` field.
 
-## 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
+## Inputs
+- `config`: KptRoadmapConfig (required) — the data and every option
+- `scrollHeight`: string | null — a fixed height, e.g. '420px'; enables the sticky header
+- `labelWidth`: string — the width of the label column (default '14rem')
+- `cellWidthPx`: number | null — the width of an axis column; without it the value depends on the zoom
+- `showToday`: boolean — the "today" marker (default true)
+- `virtual`: boolean — renders only the visible rows; worth it from roughly 100 rows up
 
-## Model / zdarzenia
-- `collapsedGroups`: model<string[]> — dwukierunkowe id zwiniętych grup
+## Model / events
+- `collapsedGroups`: model<string[]> — the two-way ids of collapsed groups
 - `itemClick`: output<KptRoadmapItem>
-- `rangeChange`: output<KptTimeRange> — wyliczony zakres osi
+- `rangeChange`: output<KptTimeRange> — the computed axis range
 
 ## KptRoadmapConfig
-- `items`: KptRoadmapItem[] (wymagane)
+- `items`: KptRoadmapItem[] (required)
 - `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
+- `links?`: KptRoadmapLink[] — dependencies given as a graph
+- `zoom?`: 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' (default 'week')
+- `range?`: { start?: number; end?: number } — a missing end is computed from the data
 - `locale?`: string; `today?`: Date | number | string
-- `timeline?`, `rows?`, `dependencies?`, `interaction?` — opcje szczegółowe
+- `timeline?`, `rows?`, `dependencies?`, `interaction?` — the detailed options
 
 ### KptRoadmapItem
-- `id`: string, `label`: string (wymagane)
-- `start`: Date | number | string; `end?`: to samo — brak `end` oznacza kamień milowy
+- `id`: string, `label`: string (required)
+- `start`: Date | number | string; `end?`: the same — no `end` means a milestone
 - `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
+- `color?`: string — any CSS color, overriding `variant`
+- `progress?`: number 0..1 — the fill inside the bar
+- `groupId?`: string; `dependsOn?`: (string | KptRoadmapLink)[] — a bare string means an 'FS' dependency
+- `milestone?`: boolean — forces a diamond
 - `meta?`: TItem
-- Pola `draggable`, `resizable`, `locked`, `constraints` są zarezerwowane pod edycję i dziś ignorowane.
+- The `draggable`, `resizable`, `locked` and `constraints` fields are reserved for editing and are ignored today.
 
 ### KptRoadmapGroup
-- `id`, `label` (wymagane); `sublabel?`, `parentId?`, `collapsed?`, `variant?`, `color?`
-- `summary?`: 'auto' | 'none' — 'auto' rysuje pasek zbiorczy od min(start) do max(end) dzieci
+- `id`, `label` (required); `sublabel?`, `parentId?`, `collapsed?`, `variant?`, `color?`
+- `summary?`: 'auto' | 'none' — 'auto' draws a rolled-up bar from min(start) to max(end) of the children
 
 ### 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)
+- `weekendDays?`: number[] (default [0, 6]); `weekPrefix?`: string (from i18n by default)
+- `workHours?`: { from, to, mode?: 'skip' | 'dim', skipWeekends? } — only with `zoom: 'hour'`;
+  'skip' cuts the nights out of the axis, 'dim' leaves the columns greyed out
+- `positionMode?`: 'uniform' (default) | 'linear'
+- `bandUnit?`: the unit of the header's top level; `maxCells?`: number (default 4000)
 
 ### KptRoadmapRowOptions (`config.rows`)
-- `mode?`: 'row-per-item' (domyślnie) | 'pack' — 'pack' układa nienachodzące zadania w jednym wierszu
+- `mode?`: 'row-per-item' (default) | 'pack' — 'pack' lays non-overlapping tasks out in a single row
 - `itemHeight?`, `groupHeight?`, `laneHeight?`, `packMinGapMs?`
 - `showUngroupedHeader?`, `ungroupedLabel?`
 
-## Przykład
+## Example
 
     <kpt-roadmap [config]="roadmap" scrollHeight="420px" />
 
     roadmap: KptRoadmapConfig = {
       zoom: 'week',
-      groups: [{ id: 'app', label: 'Aplikacja' }],
+      groups: [{ id: 'app', label: 'Application' }],
       items: [
-        { id: 'auth', label: 'Logowanie', start: '2026-08-24', end: '2026-08-31',
+        { id: 'auth', label: 'Sign-in', start: '2026-08-24', end: '2026-08-31',
           groupId: 'app', variant: 'success', progress: 1 },
-        { id: 'ship', label: 'Wydanie', start: '2026-09-14', groupId: 'app',
+        { id: 'ship', label: 'Release', 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.
+## Behavior
+- The axis is computed in local time; week numbering follows ISO 8601 (week 1 contains the year's first Thursday).
+- The 'uniform' mode gives columns of equal width despite DST changes and months of different lengths;
+  inside a column the position is interpolated linearly, so a task can start in the middle of a day.
+- A year change: a stronger vertical line and a black marker with the year on that year's first band.
+  At week zoom the boundary is computed by the ISO week year, so W53 does not fall into the next year.
+- An item extending past the axis range is cut off on the side where it is clipped.
+- Tooltips use the `kptTooltip` directive (not the native `title`): the bubble appears immediately, is
+  styled with tokens and works with keyboard focus too.
+- The rule: a tooltip shows what cannot be seen. Bars, row labels and header bands carry it
+  with `kptTooltipOnlyWhenTruncated`, so a tooltip only pops up for text cut off with
+  an ellipsis — checked on hover, so it reacts to changes in width and zoom.
+  Milestones and header cells carry a tooltip unconditionally: a diamond shows no text at all,
+  and a cell fills in the year that "W35 / 24.08–30.08" does not show.
+- Dependencies: 'FS' (the default), 'SS', 'FF', 'SF'; violated ones are drawn as a dashed line in the danger color.
+- Entries with an invalid date or a duplicate `id` are skipped, with a warning in development mode.
 
 ## 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.
+The `roadmap.*` keys: `empty`, `week`, `today`, `milestone`, `expandGroup`, `collapseGroup`.
+Month and weekday names come from `Intl` per `config.locale` or the locale from `KptI18n`,
+so they follow each language's orthography (lowercase in Polish, capitalized in English).
+In the header the first character is capitalized through `::first-letter`, so that the axis looks the same
+regardless of language; the text itself is untouched, so tooltips and screen reader output
+get the original form.
+
+## Tokens
+Surfaces `--kpt-color-surface{,-variant,-sunken,-hover}`, outlines `--kpt-color-border{,-strong}`,
+bars per variant `--kpt-color-{primary,success,danger,warning,info,muted}`.
+A bar's label is white, but the `neutral` variant has a light background, so its text uses
+`--kpt-color-on-muted`. A group's rolled-up bar in the `neutral` variant is drawn in
+`--kpt-color-on-surface-muted` — `--kpt-color-muted` would be indistinguishable from the row background.
+Further:
+the year marker is inverted, `--kpt-color-on-surface` / `--kpt-color-surface`.
+Sizes: `--kpt-roadmap-label-w`, `--kpt-roadmap-cell-w` (both can be overridden from outside).
+
+## To do (roadmap)
+Dragging and resizing bars, drawing dependencies with the mouse, adding rows —
+the types (`KptRoadmapChange`, `constraints`, `interaction`) are already part of the API.

package/src/lib/accordion/llms.txt

@@ -1,20 +1,20 @@
 # KptAccordion (kpt-accordion) + KptAccordionPanel (kpt-accordion-panel)
 
-Akordeon — grupa rozwijanych paneli.
+An accordion — a group of expandable panels.
 Import: `import { KptAccordion, KptAccordionPanel } from '@konce-pt/angular';`
 
 ## KptAccordion
-- `multi`: boolean — pozwala otworzyć wiele naraz (domyślnie: tylko jeden)
-- `animated`: boolean (domyślnie true) — animacja rozwijania paneli (CSS grid, czysty CSS)
-- `animationDuration`: number (domyślnie 500) — czas animacji w ms (dziedziczone przez panele)
+- `multi`: boolean — allows several panels open at once (default: only one)
+- `animated`: boolean (default true) — the panel expand animation (CSS grid, pure CSS)
+- `animationDuration`: number (default 500) — animation time in ms (inherited by the panels)
 
 ## KptAccordionPanel
-- `title`: string (wymagane); `disabled`: boolean; `expanded`: model<boolean>
+- `title`: string (required); `disabled`: boolean; `expanded`: model<boolean>
 
-## Przykład
+## Example
     <kpt-accordion>
-      <kpt-accordion-panel title="Sekcja 1" [expanded]="true">…</kpt-accordion-panel>
-      <kpt-accordion-panel title="Sekcja 2">…</kpt-accordion-panel>
+      <kpt-accordion-panel title="Section 1" [expanded]="true">…</kpt-accordion-panel>
+      <kpt-accordion-panel title="Section 2">…</kpt-accordion-panel>
     </kpt-accordion>
 
-Koordynacja single/multi: panel woła rodzica przez inject(KptAccordion).
+Single/multi coordination: a panel calls its parent through inject(KptAccordion).

package/src/lib/alert/llms.txt

@@ -1,19 +1,19 @@
 # KptAlert (kpt-alert)
 
-Komunikat inline. Warianty info/success/warning/danger, tytuł, zamykanie.
+An inline message. Variants info/success/warning/danger, a title, dismissal.
 Import: `import { KptAlert } from '@konce-pt/angular';`
 
-## Selektor
+## Selector
 `kpt-alert`
 
-## Wejścia / wyjścia
-- `variant`: 'info'|'success'|'warning'|'danger' (domyślnie 'info')
-- `title`: string; `dismissible`: boolean (przycisk ×)
+## Inputs / outputs
+- `variant`: 'info'|'success'|'warning'|'danger' (default 'info')
+- `title`: string; `dismissible`: boolean (a × button)
 - `closed`: output<void>
 
-## Przykład
-    <kpt-alert variant="success" title="Zapisano">Zmiany zapisane.</kpt-alert>
-    <kpt-alert variant="danger" dismissible (closed)="onClose()">Błąd.</kpt-alert>
+## Example
+    <kpt-alert variant="success" title="Saved">Your changes have been saved.</kpt-alert>
+    <kpt-alert variant="danger" dismissible (closed)="onClose()">Something went wrong.</kpt-alert>
 
-## Tokeny
-Akcent z `--kpt-color-{info,success,warning,danger}`; tło color-mix na `--kpt-color-surface`.
+## Tokens
+The accent comes from `--kpt-color-{info,success,warning,danger}`; the background is a color-mix over `--kpt-color-surface`.

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

@@ -1,31 +1,31 @@
 # KptAppShell (kpt-app-shell)
 
-Szkielet aplikacji: pasek u góry, panel boczny, treść. Responsywny bez konfiguracji.
+The application skeleton: a top bar, a side panel, the content. Responsive with no configuration.
 Import: `import { KptAppShell, KptShellNavToggle } from '@konce-pt/angular';`
 
-## Selektor
+## Selector
 `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
+## Inputs / outputs
+- `sidenavOpen`: model<boolean> (default `true`) — the state of the DOCKED panel
+  (and of the forced `over` mode); two-way `[(sidenavOpen)]`
+- `sidenavCompactOpen`: model<boolean> (default `false`) — the state of the OVERLAY in `auto` mode
+- `sidenavMode`: `'auto' | 'side' | 'over'` (default **`'auto'`**)
+- `sidenavBreakpoint`: `'sm'|'md'|'lg'|'xl'|'2xl'` (default `'lg'`) — from this threshold upward
+  `auto` docks the panel, below it turns it into an overlay
+- `sidenavRailBreakpoint`: the same set or `null` (default `null`) — enables the icon rail
+  in the band from `sidenavBreakpoint` up to this threshold; the value must be HIGHER than `sidenavBreakpoint`
+- `sidenavLabel`: string — the panel's a11y label; empty = `appShell.navigation` from the dictionary
+- `sidenavId`: readonly string — the panel's identifier (`aria-controls`)
+- `isOverlay()`, `isSidenavOpen()`: Signal<boolean> — the effective state for the current layout
+- `toggleSidenav()`, `openSidenav()`, `closeSidenav()` — they hit the state that belongs to the layout
 
-## Sloty projekcji
-- `[kptShellToolbar]` → pasek u góry
-- `[kptShellSidenav]` → panel boczny
-- treść domyślna → obszar główny
+## Projection slots
+- `[kptShellToolbar]` → the top bar
+- `[kptShellSidenav]` → the side panel
+- the default content → the main area
 
-## Przykład
+## Example
     <kpt-app-shell [(sidenavOpen)]="navOpen">
       <kpt-toolbar kptShellToolbar elevated>
         <kpt-icon-button kptShellNavToggle variant="text" ariaLabel="Menu">
@@ -33,57 +33,57 @@ Import: `import { KptAppShell, KptShellNavToggle } from '@konce-pt/angular';`
         </kpt-icon-button>
       </kpt-toolbar>
       <kpt-sidenav kptShellSidenav>
-        <a href="#"><kpt-icon name="list" /> <span kptNavLabel>Pulpit</span></a>
+        <a href="#"><kpt-icon name="list" /> <span kptNavLabel>Dashboard</span></a>
       </kpt-sidenav>
       <router-outlet />
     </kpt-app-shell>
 
-## Trzy pasma trybu 'auto'
-| szerokość | układ | co robi zamknięcie |
+## The three bands of 'auto' mode
+| width | layout | what closing does |
 |---|---|---|
-| `< 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 |
+| `< sidenavBreakpoint` | overlay + scrim | the panel slides off the edge (state: `sidenavCompactOpen`) |
+| `>= sidenavBreakpoint`, `< sidenavRailBreakpoint` | icon rail | the panel narrows to `--kpt-sidenav-rail-width` |
+| `>= sidenavRailBreakpoint` (or no rail) | full panel | the panel hides entirely |
 
-## 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.
+## Why TWO open states
+"Open" means different things on either side of the threshold: on a desktop the panel stands open by default,
+on a phone it has to be hidden by default. If both layouts shared one model, moving to a narrow
+screen would have to overwrite the application's state, and coming back to a wide one would have nothing to restore.
+Keeping them apart means the desktop intent survives narrowing and widening the window for free.
 
-Przycisk `kptShellNavToggle` sam trafia we właściwy stan — nie pisz `navOpen.set(...)` ręcznie,
-bo na wąskim ekranie ustawisz nie ten model.
+The `kptShellNavToggle` button hits the right state on its own — do not write `navOpen.set(...)` by hand,
+because on a narrow screen you would be setting the wrong 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.
+## The menu content convention (needed only for the rail)
+- `[kptNavLabel]` — the entry's text; in the rail it is hidden with the "visually hidden" technique, so the entry
+  keeps an accessible name for a screen reader.
+- `[kptNavSection]` — a group heading; hidden the same way.
 
-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.
+These are plain attributes (like `kptShellToolbar` or `kptToolbarSpacer`), not directives — there is nothing
+to import. Without them the rail shows clipped text instead of an icon. In the rail it is worth marking entries
+with `kptTooltip`, since only the glyph is visible.
 
-## 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();`.
+## Behavior
+- The layout is decided by CSS alone (`@media`), so nothing flickers before hydration and the whole thing
+  works under SSR. JavaScript is only responsible for which state the button toggles.
+- A closed panel drops out of the tab order through `visibility: hidden` (not `inert`) — it is correct
+  from the very first frame.
+- An open overlay puts `inert` on the content (`<main>`), so Tab does not walk underneath the scrim.
+- `Escape` closes the overlay; so does clicking the scrim.
+- The slide direction follows `dir` (RTL slides in from the right).
+- Height: `100dvh` with a `100vh` fallback.
+- It does **not** close the menu after navigation — the shell does not know what counts as navigation
+  in a given application. Do it yourself: `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.
+## Forced modes (backward compatibility)
+`sidenavMode="side"` and `"over"` ignore the window width and read `sidenavOpen`, exactly as
+before `auto` was introduced. Set `"side"` if the application manages responsiveness itself —
+otherwise you end up with two layers of the same logic.
 
-## Tokeny
+## Tokens
 `--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"`.
+## Deferred
+A focus trap and returning focus to the button after closing (consistent with `kpt-drawer`, which does not
+have them either — that is a separate task for the whole repo). The `<aside>` already carries `tabindex="-1"`.