@konce-pt/react 0.8.1 → 0.8.3

package/README.md

@@ -1,27 +1,230 @@
-<p align="center">
-  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — component library" width="100%" />
-</p>
+<div align="center">
 
-# @konce-pt/react
+<img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — React component library" width="100%" />
 
-Komponenty React 19 systemu projektowego [Koncept UI](https://gitlab.com/konce-pt/koncept-ui).
-Ta sama warstwa CSS co port Angulara — te same klasy `kpt-*`, te same tokeny `--kpt-*` —
-więc oba frameworki wyglądają identycznie. **Zero zależności runtime.**
+# Koncept UI — React
+
+**Open-source React 19 component library on the Koncept UI design system.**
+80+ components sharing the exact CSS layer with the Angular port — zero runtime dependencies.
+
+[![npm version](https://img.shields.io/npm/v/@konce-pt/react?color=%233b82f6&label=npm)](https://www.npmjs.com/package/@konce-pt/react)
+[![npm downloads](https://img.shields.io/npm/dm/@konce-pt/react?color=%233b82f6)](https://www.npmjs.com/package/@konce-pt/react)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/@konce-pt/react)](https://bundlephobia.com/package/@konce-pt/react)
+[![types](https://img.shields.io/npm/types/@konce-pt/react)](https://www.npmjs.com/package/@konce-pt/react)
+[![license](https://img.shields.io/npm/l/@konce-pt/react?color=%2310b981)](https://gitlab.com/konce-pt/koncept-ui/-/blob/main/LICENSE)
+
+![React](https://img.shields.io/badge/React-19-61dafb?logo=react&logoColor=white)
+![dependencies](https://img.shields.io/badge/runtime%20deps-0-10b981)
+![CSS](https://img.shields.io/badge/CSS-shared%20with%20Angular-3b82f6)
+![Components](https://img.shields.io/badge/components-80%2B-8b5cf6)
+
+</div>
+
+---
+
+## Why Koncept UI React
+
+**Koncept UI** is a free, MIT-licensed design system. This package is its **React 19** port — not a
+lookalike, but the same rendering contract:
+
+- 🎯 **One CSS layer for both ports** — the same `kpt-*` classes, the same `--kpt-*` tokens, the same
+  `@layer kpt.*` ordering. The DOM tree matches the Angular port node for node, so an app can mix
+  the two and nothing shifts by a pixel.
+- 📦 **Zero runtime dependencies** — no `clsx`, no `radix`, no CSS-in-JS. `cn`, `Slot` and
+  `composeRefs` ship with the package.
+- ⚛️ **React 19 native** — `ref` is a plain prop (no `forwardRef`), and every form control renders a
+  native `name`/`form`, so `<form action={…}>` Actions and React Hook Form's `register()` work
+  **without an adapter**. Controls are usable controlled *and* uncontrolled.
+- 📊 **Flagship data table** — sorting, global and per-column filters, pagination, virtual scroll
+  (5000+ rows), selection, column reorder & freeze, inline editing, summary row, CSV export.
+- 🎨 **100% tokenized** — every style is a `var(--kpt-*)` custom property. Light/dark theme, neutral
+  OKLCH palette. Rebrand by swapping one token layer.
+- ♿ **Native elements first** — `<button>`, `<input>`, `<label>` wherever one exists, so keyboard and
+  screen-reader behaviour comes from the platform. Invalid state travels on `aria-invalid`, never on
+  a class.
+- 🌍 **i18n built in** — English (default) & Polish out of the box, runtime locale switch, add any
+  language with one JSON.
+
+## Installation
 
 ```bash
-npm i @konce-pt/react @konce-pt/styles @konce-pt/tokens
+npm i @konce-pt/react @konce-pt/tokens @konce-pt/styles
+# or: pnpm add / yarn add
 ```
 
-CSS ładujesz raz, w wejściu aplikacji (pakiet wysyła wyłącznie JavaScript):
+`react` and `react-dom` (`>=19`) are peers you already have. Optional extras:
+
+- [`@konce-pt/grid`](https://www.npmjs.com/package/@konce-pt/grid) — the mobile-first layout system;
+  its React components live in `@konce-pt/react/grid`.
+- [`@konce-pt/validators`](https://www.npmjs.com/package/@konce-pt/validators) — Polish-market
+  validators (NIP, REGON, PESEL, IBAN, postal code).
+- `leaflet` (`^1.9`) — an **optional** peer, needed only by `@konce-pt/react/map`, loaded through a
+  dynamic `import()`.
+
+## Setup
+
+The package ships **JavaScript only**. Load the shared CSS layer once, in your app entry:
 
 ```ts
 import '@konce-pt/tokens/css';
 import '@konce-pt/tokens/css/dark';
-import '@konce-pt/styles'; // reset, warstwy, motyw
-import '@konce-pt/styles/components'; // warstwa komponentów — wymagane
-import '@konce-pt/grid'; // opcjonalnie — klasy układu
+import '@konce-pt/styles';            // reset, @layer ordering, theme
+import '@konce-pt/styles/components'; // the component layer — REQUIRED, this is what styles kpt-*
+import '@konce-pt/grid';              // optional — only if you use the layout classes
 ```
 
+`@konce-pt/styles/components` is generated from the same SCSS the Angular port compiles into its own
+bundle, which is why both ports render identically. The Angular package injects those styles at
+runtime; React has no other source for them, so this import is not optional.
+
+Dark theme: set `<html data-theme="dark">` (or rely on `prefers-color-scheme`).
+
+> **No CDK here.** Components with a floating panel (`KptSelect`, `KptPopover`, `KptMenu`,
+> `KptAutocomplete`, `KptDatepicker`…) portal into `document.body` through the internal
+> `KptOverlay`, so `@angular/cdk/overlay-prebuilt.css` is **not** needed — positioning lives in the
+> component, the look in `@konce-pt/styles/components`. Inside an open `KptDialog` those panels
+> portal into the `<dialog>` instead, because `showModal()` moves it to the browser top layer.
+
+## Quick start
+
+A login form — controlled values, the error gated on touch, no form library required:
+
+```tsx
+import { useState } from 'react';
+import { KptButton, KptFormField, KptInput } from '@konce-pt/react';
+
+export function Login() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [touched, setTouched] = useState<Record<string, boolean>>({});
+
+  const emailError = !email.includes('@') ? 'Enter a valid e-mail address' : null;
+  const passwordError = password.length < 8 ? 'At least 8 characters' : null;
+  const invalid = Boolean(emailError || passwordError);
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        console.log({ email, password });
+      }}
+    >
+      <KptFormField label="E-mail" error={touched.email ? emailError : null} required>
+        <KptInput
+          type="email"
+          name="email"
+          value={email}
+          onValueChange={setEmail}
+          onTouch={() => setTouched((t) => ({ ...t, email: true }))}
+          invalid={Boolean(emailError)}
+        />
+      </KptFormField>
+
+      <KptFormField label="Password" error={touched.password ? passwordError : null} required>
+        <KptInput
+          type="password"
+          name="password"
+          value={password}
+          onValueChange={setPassword}
+          onTouch={() => setTouched((t) => ({ ...t, password: true }))}
+          invalid={Boolean(passwordError)}
+        />
+      </KptFormField>
+
+      <KptButton type="submit" disabled={invalid}>Sign in</KptButton>
+    </form>
+  );
+}
+```
+
+`KptFormField` generates the control id and publishes it through context, so `label[for]` and
+`input[id]` match with no configuration. Drop `value`/`onValueChange` and the field becomes
+uncontrolled — the value lives in the DOM, and a native `<form action={…}>` or React Hook Form's
+`register()` picks it up as-is.
+
+Data table with sorting, filtering, pagination and a custom cell:
+
+```tsx
+<KptDataTable
+  columns={columns}
+  data={users}
+  filterable
+  exportable
+  pageSize={10}
+  selectable="multiple"
+  rowKey="id"
+  selection={selected}
+  onSelectionChange={setSelected}
+  cells={{ status: (row, value) => <KptBadge value={String(value)} /> }}
+/>
+```
+
+## Components (80+)
+
+| Category | Components |
+| --- | --- |
+| **Forms** | `KptInput`, `KptTextarea`, `KptSelect`, `KptAutocomplete`, `KptCheckbox`, `KptSwitch`, `KptSwitchGroup`, `KptRadioGroup`, `KptSlider`, `KptRating`, `KptDatepicker`, `KptDateRange`, `KptClock`, `KptColorPicker`, `KptFileUpload`, `KptInputNumber`, `KptPassword`, `KptInputOtp`, `KptChipsInput`, `KptInputMask`, `KptListbox`, `KptKnob`, `KptRichText`, `KptFormField` |
+| **Buttons & actions** | `KptButton`, `KptIconButton`, `KptButtonGroup`, `KptFab`, `KptSplitButton`, `KptSpeedDial` |
+| **Layout** | `KptAppShell`, `KptToolbar`, `KptSidenav`, `KptCard` (+ `Header`, `Footer`, `Media`, `Title`…), `KptDivider`, `KptPanel`, `KptFieldset`, `KptSplitter`, `KptScrollTop` |
+| **Navigation** | `KptTabs`, `KptAccordion`, `KptBreadcrumb`, `KptStepper`, `KptMenu`, `KptMenubar`, `KptMegamenu`, `KptContextMenu` |
+| **Data** | `KptDataTable`, `KptPaginator`, `KptTree`, `KptTimeline`, `KptCarousel`, `KptDataView`, `KptPickList`, `KptOrderList`, `KptGalleria`, `KptMeterGroup` |
+| **Feedback & overlay** | `KptAlert`, `KptDialog`, `kptToast` + `KptToastContainer`, `KptTooltip`, `KptPopover`, `KptDrawer`, `KptBottomSheet`, `kptConfirm`, `KptBadge`, `KptChip`, `KptAvatar`, `KptAvatarGroup`, `KptSpinner`, `KptProgress`, `KptSkeleton`, `KptEmpty`, `KptImage`, `KptAuth` |
+| **Subpaths** | `@konce-pt/react/charts` (`KptChart`), `/roadmap` (`KptRoadmap`), `/grid` (`KptGrid`, `KptCol`, `KptFlex`), `/map` (`KptMap` + legend, POI card, search), `/icons` (full Tabler set) |
+
+The heavy pieces (charts, roadmap, maps, the full icon set) live in subpaths on purpose, so the core
+entry point stays small. Every component ships an `llms.txt` API sheet next to its source.
+
+## Theming
+
+All visuals are driven by `var(--kpt-*)` tokens (three tiers: primitives → semantic → component).
+Override them in a stylesheet imported **after** `@konce-pt/styles`:
+
+```css
+:root {
+  --kpt-color-primary: oklch(0.55 0.2 265);        /* rebrand in one line */
+  --kpt-color-primary-hover: oklch(0.5 0.2 265);
+}
+:root[data-theme='dark'] {
+  --kpt-color-primary: oklch(0.7 0.16 265);
+}
+```
+
+**Common token names:** surfaces `--kpt-color-surface`, `--kpt-color-surface-sunken|raised|variant|hover|selected`; text `--kpt-color-on-surface`, `--kpt-color-on-surface-muted` (aliases `--kpt-color-text`, `--kpt-color-text-muted|subtle|inverse`); borders `--kpt-color-border`, `--kpt-color-border-strong`; accent roles in full — `{primary,danger,success,warning,info}` each with `-hover`, `-contrast`, `-subtle`, `-border`; radii `--kpt-radius-sm|md|lg|xl|full|none`; elevation `--kpt-elevation-1..4` (aliases `--kpt-shadow-sm|md|lg`). There is no `--kpt-color-bg`.
+
+Variants and sizes travel on `data-*` attributes (`data-variant`, `data-size`), never on modifier
+classes — that is what the SCSS reads.
+
+## Icons
+
+**84 icons are built in and need no configuration** — what the components themselves draw plus the
+staples of an application shell (`sun`, `moon`, `bell`, `settings`, `users`, `logout`,
+`layout-dashboard`, `home`, `activity`, `chart-bar`, `brand-github` …). A typical admin panel needs
+nothing else.
+
+For the full **Tabler Icons** set (MIT, 5130 icons) there are two paths, and the difference is the
+bundle. Every icon is its own export, so importing by name lets the bundler keep just those:
+
+```tsx
+// Production — two icons reach the bundle.
+import { LayoutDashboard, Rocket } from '@konce-pt/react/icons';
+import { registerKptIcons } from '@konce-pt/react';
+registerKptIcons([LayoutDashboard, Rocket]);
+
+// 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. For the same reason `registerKptIcons(tabler)` with a namespace import
+(`import * as tabler`) registers everything — a namespace object handed to a function blocks static
+analysis. The registry is global, so one call at the app entry is enough; no provider needed.
+
+## Internationalization (i18n)
+
+Component labels ship in **English (default)** and **Polish**. Without a provider everything renders
+in English — a missing provider is never an error. `KptI18nProvider` sets the language for a subtree:
+
 ```tsx
 import { KptI18nProvider, useKptI18n } from '@konce-pt/react';
 
@@ -34,26 +237,177 @@ export function App() {
 }
 
 function Toolbar() {
-  const { t } = useKptI18n();
-  return <span>{t('paginator.range', { start: 1, end: 10, total: 42 })}</span>;
+  const { t, setLocale } = useKptI18n();
+  return (
+    <button onClick={() => setLocale('en')}>
+      {t('paginator.range', { start: 1, end: 10, total: 42 })}
+    </button>
+  );
 }
 ```
 
-## Zasady portu
+`useKptI18n()` returns `{ locale, setLocale, messages, messagesFor, t }`. `t(key, params?)` takes a
+dotted key with `{name}` interpolation and falls back to English, then to the key itself.
+
+**Add any language with one JSON** (shape = the `KptMessages` contract; missing keys fall back to
+English):
+
+```tsx
+import de from './i18n/de.json';
+
+<KptI18nProvider locale="de" messages={{ de }}>…</KptI18nProvider>
+```
+
+Any component with labels also accepts `locale` and `dictionary` props, which take priority over the
+provider. Calendar weekday/month names come from the browser's `Intl` API. The contract and the
+dictionaries live in [`@konce-pt/i18n`](https://www.npmjs.com/package/@konce-pt/i18n), shared with
+the Angular port.
+
+## Helpers
+
+- `cn(...values)` — class-name joining (the `clsx` role, no dependency).
+- `Slot` + the `asChild` prop — render as another element while keeping classes and attributes.
+- `composeRefs(...refs)` — merge several refs into one callback.
+
+## Documentation
+
+- **Playground** — live demos with copyable code: [ui.konce.pt/react](https://ui.konce.pt/react).
+- **`llms.txt`** — LLM-friendly API sheets per component, shipped inside the package; the
+  package-wide sheet lives at [ui.konce.pt/llms/react/llms.txt](https://ui.konce.pt/llms/react/llms.txt)
+  (PL mirror: [llms-pl.txt](https://ui.konce.pt/llms/react/llms-pl.txt)).
+- **Security scanners** — Socket.dev and similar tools flag i18n keys as domain names
+  (`.email`, `.today` and friends are real TLDs) and the map's default endpoints; the
+  [project sheet](https://ui.konce.pt/llms.txt) explains each alert under "Security scanners".
+- Repository: [gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui)
+
+## License
+
+MIT © konce.pt
+
+---
+
+<div align="center">
+
+## 🇵🇱 Wersja polska
+
+</div>
+
+**Koncept UI** to darmowy system projektowy na licencji **MIT**. Ta paczka to jego port na
+**Reacta 19** — nie podobnie wyglądający zamiennik, tylko ten sam kontrakt renderowania.
+
+- 🎯 **Jedna warstwa CSS dla obu portów** — te same klasy `kpt-*`, te same tokeny `--kpt-*`, ta sama
+  kolejność `@layer kpt.*`. Drzewo DOM odpowiada wersji Angulara węzeł w węzeł.
+- 📦 **Zero zależności runtime** — `cn`, `Slot` i `composeRefs` są w paczce.
+- ⚛️ **React 19** — `ref` jako zwykły prop (bez `forwardRef`), kontrolki działają kontrolowane
+  i niekontrolowane, z natywnym `name`/`form` (React 19 Actions i React Hook Form bez adaptera).
+- 📊 **Flagowa tabela danych** — sortowanie, filtry globalne i kolumnowe, paginacja, virtual scroll,
+  zaznaczanie, przestawianie i zamrażanie kolumn, edycja w miejscu, podsumowanie, eksport CSV.
+- 🎨 **100% na tokenach** — każdy styl to `var(--kpt-*)`. Motyw jasny/ciemny, neutralna paleta OKLCH.
+- ♿ **Natywne elementy** — `<button>`, `<input>`, `<label>` wszędzie tam, gdzie istnieją; stan błędu
+  na `aria-invalid`, nie na klasie.
+- 🌍 **Wbudowane i18n** — angielski (domyślny) i polski, przełączanie w runtime, dowolny język
+  jednym plikiem JSON.
+
+### Instalacja
+
+```bash
+npm i @konce-pt/react @konce-pt/tokens @konce-pt/styles
+```
+
+`react` i `react-dom` (`>=19`) to peery, które masz już w aplikacji. Opcjonalnie:
+`@konce-pt/grid` (układ; komponenty w `@konce-pt/react/grid`), `@konce-pt/validators`
+(walidatory PL: NIP, REGON, PESEL, IBAN, kod pocztowy) oraz `leaflet` (`^1.9`) — **opcjonalny**
+peer, potrzebny wyłącznie dla `@konce-pt/react/map`.
+
+### Konfiguracja
+
+Paczka wysyła **sam JavaScript**. CSS ładujesz raz, w wejściu aplikacji:
+
+```ts
+import '@konce-pt/tokens/css';
+import '@konce-pt/tokens/css/dark';
+import '@konce-pt/styles';            // reset, kolejność warstw, motyw
+import '@konce-pt/styles/components'; // warstwa komponentów — WYMAGANE, to ona styluje kpt-*
+import '@konce-pt/grid';              // opcjonalnie — klasy układu
+```
+
+`@konce-pt/styles/components` powstaje z tego samego SCSS-a, który port Angulara kompiluje do
+własnego bundla — stąd identyczny wygląd obu portów. Angular wstrzykuje te style w runtime, React
+nie ma dla nich innego źródła, więc ten import nie jest opcjonalny.
+
+Motyw ciemny: `<html data-theme="dark">` (albo `prefers-color-scheme`). Nadpisania `--kpt-color-*`
+w arkuszu importowanym **po** `@konce-pt/styles`.
+
+> **CDK nie jest tu potrzebny.** Komponenty z panelem (`KptSelect`, `KptPopover`, `KptMenu`,
+> `KptAutocomplete`, `KptDatepicker`…) renderują go przez wewnętrzny `KptOverlay` do portalu na
+> `document.body`, więc `@angular/cdk/overlay-prebuilt.css` nie jest wymagany. W otwartym
+> `KptDialog` panel trafia do `<dialog>`, bo `showModal()` przenosi go do górnej warstwy przeglądarki.
+
+### Ikony
+
+**84 ikony są wbudowane i nie wymagają konfiguracji** — to, co rysują same komponenty, plus staple
+powłoki aplikacji (`sun`, `moon`, `bell`, `settings`, `users`, `logout`, `layout-dashboard`,
+`home`, `activity`, `chart-bar`, `brand-github`…). Typowy panel administracyjny nie potrzebuje nic
+więcej.
+
+Pełny zestaw **Tabler Icons** (MIT, 5130 ikon) ma dwie ścieżki, a różnica jest w bundlu. Każda ikona
+jest osobnym eksportem, więc import po nazwie zostawia w bundlu wyłącznie użyte:
+
+```tsx
+// Produkcja — do bundla wchodzą dwie ikony.
+import { LayoutDashboard, Rocket } from '@konce-pt/react/icons';
+import { registerKptIcons } from '@konce-pt/react';
+registerKptIcons([LayoutDashboard, Rocket]);
+
+// Prototyp — wszystkie ikony, około 1,2 MB.
+import { registerKptTablerIcons } from '@konce-pt/react/icons';
+registerKptTablerIcons();
+```
+
+To `registerKptIcons` odchudza, bo przyjmuje dane argumentem i sam nie importuje pełnego zestawu.
+Z tego samego powodu `registerKptIcons(tabler)` z importem przestrzeni nazw (`import * as tabler`)
+rejestruje komplet — namespace przekazany do funkcji blokuje analizę statyczną. Rejestr jest
+globalny, więc wystarczy jedno wywołanie w wejściu aplikacji.
+
+### Internacjonalizacja (i18n)
+
+Etykiety są dostępne po **angielsku (domyślnie)** i **polsku**. Bez providera wszystko renderuje się
+po angielsku — brak providera nigdy nie jest błędem. `<KptI18nProvider locale="pl">` ustawia język
+dla poddrzewa, `useKptI18n()` zwraca `{ locale, setLocale, messages, messagesFor, t }`, a
+`t('paginator.range', { start: 1, end: 10, total: 42 })` interpoluje `{nazwa}` i spada na EN, potem
+na sam klucz.
+
+**Własny język jednym plikiem JSON** (kształt = kontrakt `KptMessages`; brakujące klucze spadają
+na EN):
+
+```tsx
+import de from './i18n/de.json';
+
+<KptI18nProvider locale="de" messages={{ de }}>…</KptI18nProvider>
+```
+
+Propsy `locale` i `dictionary` na komponencie mają priorytet nad providerem. Nazwy dni i miesięcy
+w kalendarzach pochodzą z `Intl`. Kontrakt i słowniki żyją w `@konce-pt/i18n`, wspólnym z portem
+Angulara.
+
+### Komponenty (80+)
+
+Formularze, przyciski i akcje, layout, nawigacja, dane (z flagową `KptDataTable`), feedback
+i overlay — pełna lista w tabeli powyżej. Ciężkie rzeczy (wykresy, roadmapa, mapy, pełny Tabler)
+siedzą w subpathach `@konce-pt/react/{charts,roadmap,grid,map,icons}`, żeby nie obciążać rdzenia.
+Każdy komponent ma obok źródła plik `llms.txt` z opisem API.
+
+### Dokumentacja
 
-- Drzewo DOM odpowiada wersji Angulara węzeł w węzeł — host jest odtwarzany jako wrapper
-  (`<span class="kpt-button-host">` wokół `<button class="kpt-button">`), dzięki czemu SCSS
-  jest reużyty bez zmian.
-- `ref` i `className` trafiają na element wewnętrzny; wrapper konfiguruje `hostProps`.
-- Warianty i rozmiary przez atrybuty `data-*`, nie przez klasy modyfikatorów.
-- React 19: `ref` jest zwykłym propem — bez `forwardRef`.
-- Kontrolki formularza działają kontrolowane i niekontrolowane, z natywnym `name`/`form`
-  (React 19 Actions i React Hook Form bez adaptera).
-- Tłumaczenia pochodzą z `@konce-pt/i18n`, wspólnego z portem Angulara.
+Playground z demami: [ui.konce.pt/react](https://ui.konce.pt/react). Opisy API dla modeli:
+[`llms.txt`](https://ui.konce.pt/llms/react/llms.txt) (EN) i
+[`llms-pl.txt`](https://ui.konce.pt/llms/react/llms-pl.txt) (PL). Repozytorium:
+[gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui).
 
-Pełna dokumentacja dla modeli: [`llms.txt`](https://ui.konce.pt/llms/react/llms.txt) (EN)
-i [`llms-pl.txt`](https://ui.konce.pt/llms/react/llms-pl.txt) (PL).
+Alerty skanerów łańcucha dostaw (Socket.dev i podobne) — klucze i18n czytane jak domeny
+oraz domyślne endpointy mapy — omawia sekcja „Skanery bezpieczeństwa" w
+[arkuszu projektu](https://ui.konce.pt/llms-pl.txt).
 
-## Licencja
+### Licencja
 
 MIT © konce.pt

package/dist/accordion/llms.txt

@@ -0,0 +1,56 @@
+# KptAccordion (@konce-pt/react)
+
+An accordion — a group of expandable panels. `multi` allows several open at once.
+Import: `import { KptAccordion } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-accordion-host">
+      <div class="kpt-accordion-panel-host" style="--kpt-anim-duration: 500ms">
+        <div class="kpt-accordion-panel is-open">
+          <button class="kpt-accordion-panel__header" aria-expanded="true">
+            <span class="kpt-accordion-panel__title">Section 1</span>
+            <span class="kpt-icon-host kpt-accordion-panel__chevron is-open">…</span>
+          </button>
+          <div class="kpt-accordion-panel__collapse is-open">
+            <div class="kpt-accordion-panel__collapse-inner">
+              <div class="kpt-accordion-panel__body">…children…</div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+## KptAccordion props
+- `multi`: boolean — several panels open at once
+- `openIndexes` / `defaultOpenIndexes` / `onOpenIndexesChange` — the open state, by index
+- `animated`: boolean (default true), `animationDuration`: number (ms, default 500)
+
+## KptAccordion.Panel props
+- `title` (required), `disabled`
+- `expanded` / `defaultExpanded` / `onExpandedChange` — used when the panel stands alone
+- `children`
+
+## Who owns the state
+The accordion owns it, and panels receive their index by cloning — without that, single mode would
+have no way to close its siblings. A panel used outside an accordion falls back to its own state, so
+it works standalone with no extra wrapper.
+
+## Collapsed content stays mounted
+It gets `inert` and `aria-hidden` instead of being removed, so the height can be animated while
+nothing inside takes focus or reaches a screen reader.
+
+## Examples
+    <KptAccordion defaultOpenIndexes={[0]}>
+      <KptAccordion.Panel title="Section 1">…</KptAccordion.Panel>
+      <KptAccordion.Panel title="Section 2">…</KptAccordion.Panel>
+    </KptAccordion>
+
+    <KptAccordion multi openIndexes={open} onOpenIndexesChange={setOpen}>…</KptAccordion>
+
+## Tokens
+`--kpt-color-border`, `--kpt-color-surface`, `--kpt-motion-easing-standard`, plus
+`--kpt-anim-duration` set by the accordion on each panel.
+
+## Accessibility
+The header is a native button with `aria-expanded`; the collapsed region is `inert` and
+`aria-hidden`, so it is skipped by both the keyboard and the screen reader.

package/dist/alert/llms.txt

@@ -0,0 +1,45 @@
+# KptAlert (@konce-pt/react)
+
+An inline message. Variants info/success/warning/danger, an optional title and dismissal.
+Import: `import { KptAlert } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-alert-host">
+      <div class="kpt-alert" data-variant="success" role="alert">
+        <span class="kpt-icon-host kpt-alert__icon">…</span>
+        <div class="kpt-alert__content">
+          <div class="kpt-alert__title">Saved</div>
+          <div class="kpt-alert__message">…children…</div>
+        </div>
+        <button class="kpt-alert__close" type="button" aria-label="Close">…</button>
+      </div>
+    </div>
+
+## Props
+- `variant`: 'info' | 'success' | 'warning' | 'danger' (default 'info')
+- `title`: string
+- `dismissible`: boolean — adds the close button
+- `onClosed()` — fires after the user dismisses it
+- `locale`, `dictionary` — i18n overrides for this component only
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Dismissal hides, it does not unmount
+Closing sets `hidden` on the host, the same as the Angular port, so the same alert can be shown
+again without rebuilding the tree. When you would rather drive it from outside, simply do not render
+the component — the internal state is a convenience, not the only way.
+
+## The icon follows the variant
+Each variant picks its own icon from the built-in set (`info`, `circle-check`, `alert-triangle`,
+`circle-x`), so there is nothing to configure and no way for the icon to contradict the colour.
+
+## Examples
+    <KptAlert variant="info" title="Info">A new version is available.</KptAlert>
+    <KptAlert variant="danger" title="Error" dismissible onClosed={onClosed}>Could not save.</KptAlert>
+
+## Tokens
+The semantic colour pairs of each variant (`--kpt-color-info` / `-success` / `-warning` /
+`-danger` with their `-subtle` counterparts), `--kpt-radius-md`.
+
+## Accessibility
+The message is `role="alert"`, so a screen reader announces it as it appears. Use it for something
+that just happened — for a permanent note, style your own container without that role.

package/dist/app-shell/app-shell.d.ts

@@ -92,3 +92,23 @@ export declare function useKptShellNavToggle(options?: {
     readonly 'aria-label': string;
     readonly onClick: () => void;
 };
+/**
+ * Etykieta pozycji nawigacji. W szynie ikon (układ md–xl) shell chowa ją techniką
+ * „visually hidden", więc pozycja zwęża się do samego znaku, a czytnik ekranu wciąż
+ * odczytuje pełny tekst.
+ *
+ * Nosi atrybut `kptnavlabel` — to po nim celuje wspólny SCSS. Nazwy atrybutów w selektorach
+ * CSS są w HTML case-insensitive, więc jedna reguła obsługuje oba porty; zapis małymi literami
+ * omija przy okazji ostrzeżenie React o nieznanym propie.
+ *
+ * @example
+ * <a href="/pulpit"><KptIcon name="layout-dashboard" /> <KptNavLabel>Pulpit</KptNavLabel></a>
+ */
+export declare function KptNavLabel({ className, ...rest }: Readonly<ComponentPropsWithRef<'span'>>): import("react").JSX.Element;
+/**
+ * Nagłówek grupy pozycji w nawigacji. W szynie ikon chowany tak samo jak [[KptNavLabel]].
+ *
+ * @example
+ * <KptNavSection>Raporty</KptNavSection>
+ */
+export declare function KptNavSection({ className, ...rest }: Readonly<ComponentPropsWithRef<'div'>>): import("react").JSX.Element;

package/dist/app-shell/app-shell.js

@@ -103,3 +103,27 @@ export function useKptShellNavToggle(options) {
         onClick: toggleSidenav,
     };
 }
+/**
+ * Etykieta pozycji nawigacji. W szynie ikon (układ md–xl) shell chowa ją techniką
+ * „visually hidden", więc pozycja zwęża się do samego znaku, a czytnik ekranu wciąż
+ * odczytuje pełny tekst.
+ *
+ * Nosi atrybut `kptnavlabel` — to po nim celuje wspólny SCSS. Nazwy atrybutów w selektorach
+ * CSS są w HTML case-insensitive, więc jedna reguła obsługuje oba porty; zapis małymi literami
+ * omija przy okazji ostrzeżenie React o nieznanym propie.
+ *
+ * @example
+ * <a href="/pulpit"><KptIcon name="layout-dashboard" /> <KptNavLabel>Pulpit</KptNavLabel></a>
+ */
+export function KptNavLabel({ className, ...rest }) {
+    return _jsx("span", { kptnavlabel: '', className: className, ...rest });
+}
+/**
+ * Nagłówek grupy pozycji w nawigacji. W szynie ikon chowany tak samo jak [[KptNavLabel]].
+ *
+ * @example
+ * <KptNavSection>Raporty</KptNavSection>
+ */
+export function KptNavSection({ className, ...rest }) {
+    return _jsx("div", { kptnavsection: '', className: className, ...rest });
+}

package/dist/app-shell/llms.txt

@@ -0,0 +1,59 @@
+# KptAppShell (@konce-pt/react)
+
+The application skeleton: a bar on top, a side panel and the content.
+Import: `import { KptAppShell, useKptShellNavToggle } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-app-shell kpt-app-shell--nav-open"
+         data-sidenav-mode="auto" data-sidenav-breakpoint="lg">
+      …toolbar…
+      <div class="kpt-app-shell__body">
+        <aside class="kpt-app-shell__sidenav" role="navigation" tabindex="-1" id="…">…sidenav…</aside>
+        <div class="kpt-app-shell__scrim" aria-hidden="true"></div>
+        <main class="kpt-app-shell__content">…children…</main>
+      </div>
+    </div>
+
+## Props
+- `toolbar`: ReactNode — the slot above the content area (usually `<KptToolbar>`)
+- `sidenav`: ReactNode — the side panel slot (usually `<KptSidenav>`)
+- `children`: ReactNode — the application content
+- `sidenavOpen` / `defaultSidenavOpen` / `onSidenavOpenChange` — the docked layout's open state
+  (default open)
+- `sidenavCompactOpen` / `defaultSidenavCompactOpen` / `onSidenavCompactOpenChange` — the overlay's
+  open state (default closed)
+- `sidenavMode`: 'auto' | 'side' | 'over' (default 'auto')
+- `sidenavBreakpoint`: 'sm' | 'md' | 'lg' | 'xl' | '2xl' (default 'lg')
+- `sidenavRailBreakpoint`: the same union or null (default null)
+- `sidenavLabel`: string — empty falls back to `appShell.navigation` from the dictionary
+- `locale`, `dictionary` — i18n overrides for this component only
+
+## Two open states, on purpose
+The docked layout and the overlay keep separate state. If they shared one, narrowing the window
+would have to overwrite the consumer's state, and widening it back would have nothing to restore.
+`useKptShellNavToggle` hits whichever state governs the current layout, so one button serves both.
+
+## The nav toggle
+    const toggle = useKptShellNavToggle();          // optional { label }
+    <KptButton variant="text" {...toggle}>Menu</KptButton>
+
+It returns `aria-expanded`, `aria-controls`, `aria-label` and `onClick`. Spread them on a native
+`<button>` or on `<KptButton>` (which forwards them to its inner `<button>`) — ARIA attributes must
+land on the element that carries the role, never on a wrapper.
+
+`useKptAppShell()` exposes the same state directly: `{ isSidenavOpen, isOverlay, sidenavId,
+toggleSidenav, openSidenav, closeSidenav }`. It throws outside `<KptAppShell>`.
+
+## Layout is CSS, behaviour is JS
+Which layout applies is decided entirely by the stylesheet from the `data-*` attributes, so nothing
+flickers before hydration and the page is correct with JavaScript disabled. The breakpoint hook only
+decides WHICH state the button flips. The scrim is always in the DOM; CSS controls its visibility.
+
+## Tokens
+`--kpt-sidenav-width` (16rem), `--kpt-sidenav-rail-width` (4rem), `--kpt-z-overlay`,
+`--kpt-color-overlay-scrim`, `--kpt-motion-duration-base`, `--kpt-motion-easing-standard`.
+
+## Accessibility
+- The panel is an `<aside role="navigation">` with a label and an `id` for `aria-controls`.
+- A closed docked panel leaves the tab order through `visibility`, correct on the first frame.
+- While the overlay is open the content gets `inert`, and Escape closes the panel.

package/dist/auth/auth.d.ts

@@ -10,7 +10,7 @@ export interface KptAuthProps extends Omit<ComponentPropsWithRef<'div'>, 'onSubm
     defaultMode?: KptAuthMode;
     onModeChange?: (mode: KptAuthMode) => void;
     layout?: KptAuthLayout;
-    providers?: KptAuthProvider[];
+    providers?: readonly KptAuthProvider[];
     providerLayout?: KptAuthProviderLayout;
     showName?: boolean;
     requireTerms?: boolean;