@konce-pt/react 0.8.1 → 0.8.3

package/dist/auth/llms.txt

@@ -0,0 +1,65 @@
+# KptAuth (@konce-pt/react)
+
+An authentication screen: sign in, sign up and password recovery in one component, with a promo
+panel and a list of external providers.
+Import: `import { KptAuth, type KptAuthProvider } from '@konce-pt/react';`
+
+The component is **presentational** — it calls no API and does not navigate; the app does that in
+the handlers.
+
+## Props
+- `mode` / `defaultMode` / `onModeChange` — `'signIn' | 'signUp' | 'forgot'`
+- `layout`: `'slider'` (default) | `'split'` — the promo panel slides to the other side, or stays put
+- `providers`: `KptAuthProvider[]` — `{ id, label, icon?, iconUrl?, description? }`
+- `providerLayout`: `'list'` (default) | `'grid'`
+- `showName`, `requireTerms`, `showRemember`: boolean (default true)
+- `busy`: boolean — the buttons show a loading state, providers are blocked
+- `error` / `notice`: string | null — a server message (a `danger` / `success` alert)
+- `promoTitle` / `promoText`: `null` = mode-dependent text from i18n, `''` = hidden
+- `animated` (true), `animationDuration` (320 ms)
+- `onSignIn`, `onSignUp`, `onResetPassword`, `onProviderSelect`
+- `renderProvider(provider, select)` — custom markup for one provider; return `null` for the rest
+
+## Slots
+`KptAuth.Brand`, `KptAuth.Promo`, `KptAuth.Sso`, `KptAuth.Fields`, `KptAuth.Footer` — the
+equivalents of the `[kptAuthBrand]`, `[kptAuthPromo]`, `[kptAuthSso]`, `[kptAuthFields]` and
+`[kptAuthFooter]` projections. **Fields from the `Fields` slot are not part of the component's
+model** — bind them to your own state and read them in the handler.
+
+## Validation without a form library
+Three independent forms, one per mode, validated on every render: e-mail required and valid,
+password required (sign up: at least 8 characters), the confirmation matching, consent required
+when `requireTerms`. The validator returns a `kind`, and the message is composed at render time,
+so **changing the language repaints the errors**. The "do not shout at an untouched field" gate
+lives in the presentation, so the submit button's disabled state tells the truth from the start;
+submitting marks the whole form as touched.
+
+## The heading takes focus after a mode change
+Without it a screen reader never announces the change, and focus stays on a button that has just
+slid off screen. Only the active mode's form is in the DOM, so nothing invisible keeps a tab stop.
+
+## Provider icons
+The core set carries no brand icons: use `registerKptTablerIcons()` from `@konce-pt/react/icons`
+(`icon: 'brand-google'`), your own registry entry, `iconUrl`, or `renderProvider`. The icon is
+decorative, so the button's accessible name always comes from `label`.
+
+## Examples
+    <KptAuth
+      providers={[{ id: 'google', label: 'Google', icon: 'brand-google' }]}
+      busy={loading}
+      error={serverError}
+      onSignIn={login}
+      onProviderSelect={(provider) => oauth(provider.id)}
+    >
+      <KptAuth.Brand><img src="/logo.svg" alt="Konce" /></KptAuth.Brand>
+      <KptAuth.Footer><small>© 2026 Konce</small></KptAuth.Footer>
+    </KptAuth>
+
+## Styling
+`--kpt-auth-width` (64rem), `--kpt-auth-card-height` (34rem), `--kpt-auth-min-height` (100dvh),
+`--kpt-auth-promo-bg`, `--kpt-auth-padding`, `--kpt-auth-card-radius` / `-border` / `-shadow`.
+Below the `md` breakpoint the layout drops to a single column.
+
+## i18n
+Every string comes from the `auth` namespace, including `auth.promo.*`, `auth.continueWith`
+(`{provider}`) and `auth.passwordHint` / `auth.errorMinLength` (`{min}`).

package/dist/autocomplete/autocomplete.d.ts

@@ -1,6 +1,6 @@
 import { type ComponentPropsWithRef } from 'react';
 export interface KptAutocompleteProps extends Omit<ComponentPropsWithRef<'input'>, 'value' | 'defaultValue' | 'onChange'> {
-    options?: string[];
+    options?: readonly string[];
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;

package/dist/autocomplete/llms.txt

@@ -0,0 +1,44 @@
+# KptAutocomplete (@konce-pt/react)
+
+A text field with suggestions. Import: `import { KptAutocomplete } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-autocomplete-host">
+      <input class="kpt-autocomplete__input" type="text" role="combobox" aria-expanded="true">
+    </span>
+    <!-- while open, in a portal: -->
+    <ul class="kpt-autocomplete__panel" role="listbox">
+      <li class="kpt-autocomplete__option is-active" role="option">Kraków</li>
+    </ul>
+
+## Props
+- `options`: string[] — the suggestions
+- `value` / `defaultValue` / `onValueChange` — the typed text
+- `invalid`, `touched`, `onTouch()`
+- `className`, `ref` and every other `<input>` prop go to the input
+
+## The value is the text, not the option
+Whatever is typed becomes the value; the suggestions only shorten the typing. That makes the field
+usable for values outside the list — a city nobody put in `options` still submits. When the value
+must come from the list, reach for `KptSelect` instead.
+
+## No backdrop
+Unlike the other overlays this panel has none: a backdrop would cover the input it belongs to and
+swallow every click on it. The panel closes on blur, on Escape and on picking an option. Options
+are picked on `mousedown` with the default prevented, so the click cannot steal focus from the
+input and close the panel before the pick lands.
+
+## Keyboard
+ArrowDown opens the list and moves the active option, ArrowUp moves back, Enter picks the active
+one, Escape closes.
+
+## Examples
+    <KptAutocomplete options={cities} value={city} onValueChange={setCity} placeholder="City…" />
+
+## Tokens
+`--kpt-form-field-{bg,text,placeholder,border,border-focus,radius}`,
+`--kpt-color-surface-raised` and `--kpt-elevation-3` for the panel.
+
+## Accessibility
+The input is `role="combobox"` with `aria-expanded`; the panel is `role="listbox"` with
+`role="option"` rows carrying `aria-selected`.

package/dist/avatar/llms.txt

@@ -0,0 +1,42 @@
+# KptAvatar (@konce-pt/react)
+
+An avatar — a photo, initials (from `name`) or an icon.
+Import: `import { KptAvatar } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-avatar-host">
+      <span class="kpt-avatar" data-size="md" data-shape="circle" title="Anna Kowalska">
+        <img class="kpt-avatar__img" src="…" alt="Anna Kowalska">
+      </span>
+    </span>
+
+## Props
+- `src`: string | null — a photo; it wins over initials and the icon
+- `name`: string — the source of the initials, the `title` and the accessible label
+- `icon`: string | null — a registry icon name, used when there is neither photo nor name
+- `size`: 'sm' | 'md' | 'lg' | 'xl' (default 'md')
+- `shape`: 'circle' | 'square' (default 'circle')
+- `hostProps` — props for the `.kpt-avatar-host` wrapper
+- `className`, `ref` and every other `<span>` prop go to the inner `.kpt-avatar`
+
+## Fallback order
+`src` → `name` (up to two initials, uppercased) → `icon`. With none of them the avatar renders as
+an empty shape, which is a valid placeholder.
+
+## Positioning inside a parent
+The host is the layout element, so classes that place the avatar in its parent go to `hostProps` —
+the overlapping avatar on a card is `hostProps={{ className: 'kpt-card__avatar' }}`.
+
+## Examples
+    <KptAvatar src="/u/anna.jpg" size="lg" />
+    <KptAvatar name="Anna Kowalska" size="lg" />
+    <KptAvatar icon="user" shape="square" />
+    <KptAvatar src="/u/anna.jpg" size="lg" hostProps={{ className: 'kpt-card__avatar' }} />
+
+## Tokens
+`--kpt-color-muted`, `--kpt-color-on-muted`, `--kpt-radius-full`, `--kpt-radius-md` (square).
+
+## Accessibility
+`name` becomes the native `title` — initials alone do not say who this is. Without `src` the avatar
+also gets `role="img"` and `aria-label`, and the initials are `aria-hidden` so a screen reader does
+not spell out "A-K". With `src` the label already lives on the image's `alt`, so it is not doubled.

package/dist/avatar-group/avatar-group.d.ts

@@ -6,7 +6,7 @@ export interface KptAvatarItem {
     icon?: string;
 }
 export interface KptAvatarGroupProps extends ComponentPropsWithRef<'div'> {
-    avatars?: KptAvatarItem[];
+    avatars?: readonly KptAvatarItem[];
     /** Ile awatarów pokazać, zanim pojawi się „+N". */
     max?: number;
     size?: KptAvatarSize;

package/dist/avatar-group/llms.txt

@@ -0,0 +1,38 @@
+# KptAvatarGroup (@konce-pt/react)
+
+A group of overlapping avatars with a "+N" counter. Built on `KptAvatar`.
+Import: `import { KptAvatarGroup } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-avatar-group-host">
+      <div class="kpt-avatar-group" data-size="lg">
+        <span class="kpt-avatar-group__item">…KptAvatar…</span>…
+        <span class="kpt-avatar-group__item kpt-avatar-group__more" data-size="lg">+2</span>
+      </div>
+    </div>
+
+## Props
+- `avatars`: `KptAvatarItem[]` — `{ name?, src?, icon? }`
+- `max`: number (default 4) — how many to show before "+N"
+- `size`: `'sm' | 'md' | 'lg' | 'xl'`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## One list, three fallbacks
+Each entry falls back in order: `src` (a photo) → `name` (initials) → `icon`. A team where only
+some people have a photo therefore needs no branching at the call site — which is exactly the
+common case.
+
+## The name survives the overlap
+Every avatar keeps the `title` from `KptAvatar`, so hovering tells you who it is even at
+`size="sm"`, where initials alone are a guess.
+
+## Examples
+    <KptAvatarGroup avatars={team} max={4} />
+    <KptAvatarGroup avatars={team} max={3} size="sm" />
+
+## Tokens
+The overlap ring uses `--kpt-color-surface`, the "+N" chip `--kpt-color-muted`.
+
+## Accessibility
+The avatars come from `KptAvatar` with its `role="img"` and `aria-label`; "+N" is plain text, so
+the count is read as part of the group.

package/dist/badge/llms.txt

@@ -0,0 +1,38 @@
+# KptBadge (@konce-pt/react)
+
+A badge — a counter or a status dot. Standalone, or laid over content (`overlay`).
+Import: `import { KptBadge } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-badge-host">
+      …children…
+      <span class="kpt-badge kpt-badge--overlay" data-variant="danger" data-size="md">8</span>
+    </span>
+
+## Props
+- `value`: string | number | null — the counter content
+- `variant`: 'neutral' | 'primary' | 'success' | 'danger' | 'warning' | 'info' (default 'primary')
+- `size`: 'sm' | 'md' | 'lg' (default 'md') — `sm` fits inside a line of text
+- `dot`: boolean — a bare status dot, no number
+- `overlay`: boolean — laid over the `children`
+- `max`: number (default 99) — above it the counter reads `99+`
+- `className`, `ref` and every other `<span>` prop go to the host
+
+## Overlay
+`overlay` positions the badge in the corner of `children`, so the host has to be the thing being
+marked: an icon, an avatar, a button. The badge scales with `font-size`, which is why the demo sets
+it on the host rather than on the badge.
+
+## Examples
+    <KptBadge value={3} variant="danger" />
+    <KptBadge dot variant="success" />
+    <KptBadge value={128} overlay style={{ fontSize: '1.5rem' }}><KptIcon name="menu" /></KptBadge>
+    <span>Notifications <KptBadge value={4} size="sm" variant="success" /></span>
+
+## Tokens
+The semantic colour pairs of each variant (`--kpt-color-primary` / `--kpt-color-on-primary`,
+`-success`, `-danger`, `-warning`, `-info`, `--kpt-color-muted` / `--kpt-color-on-muted`).
+
+## Accessibility
+The badge is text inside the host, so a screen reader reads it together with the content it marks.
+For a counter that has to be announced on its own, add your own `aria-label` on the host.

package/dist/bottom-sheet/llms.txt

@@ -0,0 +1,43 @@
+# KptBottomSheet (@konce-pt/react)
+
+A sheet that slides up from the bottom of the screen, with a handle and a backdrop.
+Import: `import { KptBottomSheet } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-bottom-sheet-host">
+      <div class="kpt-bottom-sheet__backdrop is-open"></div>
+      <div class="kpt-bottom-sheet__panel is-open" role="dialog" aria-modal="true" tabindex="-1">
+        <button class="kpt-bottom-sheet__handle"></button>
+        <div class="kpt-bottom-sheet__header">Share</div>
+        <div class="kpt-bottom-sheet__body">…</div>
+      </div>
+    </div>
+
+## Props
+- `open`, `onOpenChange` — controlled, like `KptDialog`
+- `header`: string
+- `closeOnBackdrop`: boolean (default true)
+- `children` — the sheet's content
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The closed sheet stays in the DOM
+It is hidden with `transform` and `visibility`, never `display: none` — the slide-in and slide-out
+animations need something to run on. `visibility` also takes it out of the tab order and out of the
+accessibility tree without `inert`, and does so on the very first frame, with no JavaScript.
+`prefers-reduced-motion: reduce` drops the transitions.
+
+## No portal
+The panel and the backdrop are `position: fixed` and the host is `display: contents`, so the sheet
+needs no portal — the same DOM as the Angular port. A transformed ancestor would break the fixed
+positioning there too.
+
+## Examples
+    <KptButton onClick={() => setOpen(true)}>Share</KptButton>
+    <KptBottomSheet open={open} onOpenChange={setOpen} header="Share">…</KptBottomSheet>
+
+## Tokens
+The panel `--kpt-color-surface-raised`, the top radius `--kpt-radius-lg`, `--kpt-elevation-4`.
+
+## Accessibility
+`role="dialog"` with `aria-modal`; Escape and the handle close the sheet, and the handle is a real
+button labelled from `common.close`.

package/dist/breadcrumb/breadcrumb.d.ts

@@ -5,7 +5,7 @@ export interface KptBreadcrumbItem {
     url?: string;
 }
 export interface KptBreadcrumbProps extends Omit<ComponentPropsWithRef<'div'>, 'children'>, KptI18nOverrides {
-    items?: KptBreadcrumbItem[];
+    items?: readonly KptBreadcrumbItem[];
 }
 /**
  * Ścieżka nawigacji (breadcrumbs).

package/dist/breadcrumb/llms.txt

@@ -0,0 +1,35 @@
+# KptBreadcrumb (@konce-pt/react)
+
+A breadcrumb trail. Import: `import { KptBreadcrumb } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-breadcrumb-host">
+      <nav class="kpt-breadcrumb" aria-label="breadcrumb">
+        <a class="kpt-breadcrumb__link" href="/">Home</a>
+        <span class="kpt-icon-host kpt-breadcrumb__sep">…</span>
+        <span class="kpt-breadcrumb__current" aria-current="page">Showcase</span>
+      </nav>
+    </div>
+
+## Props
+- `items`: `{ label, url? }[]`
+- `locale`, `dictionary` — i18n overrides for this component only
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The last item is never a link
+Even with a `url`, the last item renders as plain text: it is the current page, and a link pointing
+where you already are only misleads. It gets `aria-current="page"` instead.
+
+## i18n
+The nav label comes from `breadcrumb.label` in the dictionary.
+
+## Examples
+    <KptBreadcrumb items={[{ label: 'Home', url: '/' }, { label: 'Settings' }]} />
+
+## Tokens
+`--kpt-color-on-surface-muted` (the separators and the current page), `--kpt-color-primary`
+(the links).
+
+## Accessibility
+A `<nav>` with a label from the dictionary; the current page carries `aria-current="page"`, so a
+screen reader can tell the trail from the position in it.

package/dist/button/llms.txt

@@ -0,0 +1,56 @@
+# KptButton (@konce-pt/react)
+
+The Koncept UI button. It renders a native `<button>` (semantics + form submit) inside a
+`.kpt-button-host` wrapper — two DOM levels, exactly like the Angular port, because the host
+carries its own styles. Import: `import { KptButton } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-button-host">
+      <button class="kpt-button" type="button" data-variant="filled" data-size="md">
+        <span class="kpt-button__content">…</span>
+      </button>
+    </span>
+
+## Props
+- `variant`: 'filled' | 'tonal' | 'outline' | 'text' | 'danger' (default 'filled')
+- `size`: 'sm' | 'md' | 'lg' (default 'md')
+- `type`: 'button' | 'submit' | 'reset' (default 'button')
+- `disabled`: boolean
+- `loading`: boolean — a spinner + blocked interaction, sets `aria-busy`
+- `fullWidth`: boolean — the full width of the container
+- `asChild`: boolean — render the single child instead of `<button>`, keeping every class
+- `hostProps`: props for the `.kpt-button-host` wrapper
+- `className`, `ref` and every other `<button>` prop go to the INNER `<button>`
+
+## Events
+No events of its own — bind `onClick` and it lands on the native `<button>`.
+
+## Examples
+    <KptButton onClick={save}>Save</KptButton>
+    <KptButton variant="outline" size="sm">Cancel</KptButton>
+    <KptButton variant="danger" loading={deleting}>Delete</KptButton>
+    <form action={submitAction}><KptButton type="submit">Send</KptButton></form>
+    <KptButton asChild><a href="/docs">Documentation</a></KptButton>
+
+## asChild
+The wrapper is still rendered; only the inner element is swapped. The content stays wrapped in
+`.kpt-button__content`, so the spinner and the layout keep working. A disabled substituted
+element gets `disabled` when it is a native `<button>`, and `aria-disabled` otherwise — an
+element with no `:disabled` state therefore does not get the dimmed look.
+
+## Tokens (styling)
+`--kpt-button-radius`, `--kpt-button-font-weight`, `--kpt-button-gap`,
+`--kpt-button-filled-{bg,fg,bg-hover,bg-active}`, `--kpt-button-tonal-{bg,fg,bg-hover}`,
+`--kpt-button-outline-{border,fg,bg-hover}`, `--kpt-button-text-{fg,bg-hover}`.
+The 'danger' variant uses `--kpt-color-danger` / `--kpt-color-on-danger`.
+
+## The state layer (hover / active)
+Hover and active feedback is carried by an `::after` pseudo-element (`opacity` 0 → 1), not by
+animating the button's own `background-color`. The CSS is shared with the Angular port, where
+the pattern was introduced to stop the variant flicker on first paint; here it simply comes
+along with the stylesheet.
+
+## Accessibility
+- A native `<button>` — full keyboard and screen reader support.
+- `loading` sets `aria-busy="true"` and disables the button.
+- The focus ring comes from `@konce-pt/styles` (`--kpt-color-focus-ring`).

package/dist/button-group/button-group.d.ts

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

package/dist/button-group/llms.txt

@@ -0,0 +1,40 @@
+# KptButtonGroup (@konce-pt/react)
+
+A segmented button group (toggle) — a single choice out of the options.
+Import: `import { KptButtonGroup } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-button-group-host">
+      <div class="kpt-button-group" role="group" data-size="md">
+        <button type="button" class="kpt-button-group__item is-active" aria-pressed="true">List</button>
+        <button type="button" class="kpt-button-group__item" aria-pressed="false">Grid</button>
+      </div>
+    </span>
+
+## Props
+- `options`: `KptOption<T>[]` — `{ label, value, disabled? }`
+- `value` / `defaultValue` / `onValueChange` — controlled or uncontrolled
+- `size`: 'sm' | 'md' | 'lg' (default 'md')
+- `disabled`: boolean — disables the whole group; a single option disables itself
+- `onTouch()` — fires on a pick, the moment the control becomes touched
+- `hostProps` — props for the `.kpt-button-group-host` wrapper
+- `className`, `ref` and every other `<div>` prop go to `.kpt-button-group`
+
+## Values of any type
+The value is generic, so options can carry objects, not just strings. Keys come from
+`String(option.value)`, so distinct options need distinct string forms — for object values give
+each one a stable id and map back to the object yourself.
+
+## Examples
+    <KptButtonGroup value={view} onValueChange={setView}
+      options={[{ label: 'List', value: 'list' }, { label: 'Grid', value: 'grid' }]} />
+
+    <KptButtonGroup size="sm" defaultValue="M" options={sizeOptions} />
+
+## Tokens
+`--kpt-color-surface`, `--kpt-color-muted`, `--kpt-color-primary` (the active segment),
+`--kpt-color-border-strong`, `--kpt-radius-md`.
+
+## Accessibility
+A `role="group"` of native buttons, each with `aria-pressed` — a screen reader announces which
+segment is on, and the keyboard walks them like any other buttons.

package/dist/card/llms.txt

@@ -0,0 +1,60 @@
+# KptCard (@konce-pt/react)
+
+A card — a surface with elevation (`elevated`) or a border (`outlined`). The card renders its own
+body; the header and the footer are lifted out of the children and placed outside that body,
+exactly where the Angular template puts them, so the DOM tree matches node for node.
+Import: `import { KptCard } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-card" data-variant="elevated">
+      <div class="kpt-card__header">…</div>
+      <div class="kpt-card__body">…</div>
+      <div kptcardfooter="">…</div>
+    </div>
+
+## Props
+- `variant`: 'elevated' | 'outlined' (default 'elevated')
+- `header`: string — optional header text; use `<KptCard.Header>` for richer content
+- `flush`: boolean — a body with no padding (for rich layouts that manage their own sections)
+- `className`, `ref` and every other `<div>` prop go to the card root
+
+## Sub-components
+- `KptCard.Header` — lifted above the body, `.kpt-card__header`
+- `KptCard.Footer` — lifted below the body; carries the `kptcardfooter` attribute the shared
+  SCSS targets (attribute names in CSS selectors are case-insensitive in HTML, so one rule
+  serves both ports)
+- `KptCard.Media` — an `<img>` on the full width, clipped to the radius; set `aspect-ratio`/`height`
+- `KptCard.Lead` — the header row (avatar + titles), with padding
+- `KptCard.Title`, `KptCard.Subtitle` — title/subtitle typography
+- `KptCard.Section` — a padded section (a column with gaps)
+- `KptCard.Tags` — a row of chips; `KptCard.Meta` — an icon+text row (rating/location)
+- `KptCard.Actions` — a row of buttons (equal widths)
+
+There is no `KptCard.Body`: the body belongs to the card itself, and `flush` removes its padding.
+An overlapping avatar is a class you apply to your own element: `className="kpt-card__avatar"`.
+
+## Examples
+    <KptCard header="Settings" variant="outlined">
+      <p>Content…</p>
+      <KptCard.Footer><KptButton>Save</KptButton></KptCard.Footer>
+    </KptCard>
+
+    <KptCard variant="outlined" flush>
+      <KptCard.Lead>
+        <img className="kpt-card__avatar" src="/u.jpg" alt="" width={48} height={48} />
+        <div>
+          <KptCard.Title>Shiba Inu</KptCard.Title>
+          <KptCard.Subtitle>Dog Breed</KptCard.Subtitle>
+        </div>
+      </KptCard.Lead>
+      <KptCard.Media src="/photo.jpg" style={{ aspectRatio: '4 / 3' }} />
+      <KptCard.Section>Description…</KptCard.Section>
+      <KptCard.Footer><KptButton variant="text" size="sm">LIKE</KptButton></KptCard.Footer>
+    </KptCard>
+
+## Tokens
+`--kpt-card-{bg,fg,border,radius,padding,shadow}`.
+
+## Accessibility
+The card is a plain container with no role of its own — give it heading semantics through your
+own content when it needs them.

package/dist/carousel/carousel.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptCarouselProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'children'>, KptI18nOverrides {
-    items?: T[];
+    items?: readonly T[];
     activeIndex?: number;
     defaultActiveIndex?: number;
     onActiveIndexChange?: (index: number) => void;

package/dist/carousel/llms.txt

@@ -0,0 +1,47 @@
+# KptCarousel (@konce-pt/react)
+
+A slide carousel. The data comes from `items`, the look of a slide from `renderSlide`.
+Import: `import { KptCarousel } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-carousel-host">
+      <div class="kpt-carousel">
+        <div class="kpt-carousel__viewport">
+          <div class="kpt-carousel__track" style="transform:translateX(-100%)">
+            <div class="kpt-carousel__slide">…</div>…
+          </div>
+        </div>
+        <button class="kpt-carousel__nav kpt-carousel__nav--prev">…</button>
+        <button class="kpt-carousel__nav kpt-carousel__nav--next">…</button>
+        <div class="kpt-carousel__dots"><button class="kpt-carousel__dot is-active"></button>…</div>
+      </div>
+    </div>
+
+## Props
+- `items`: `T[]`
+- `activeIndex` / `defaultActiveIndex` / `onActiveIndexChange`
+- `renderSlide(item, index)` — required
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The render prop replaces the template
+`renderSlide` is the direct equivalent of Angular's `<ng-template let-item let-i="index">`: the
+carousel owns the layout and the navigation, the caller owns what a slide looks like. Nothing is
+guessed about the item's shape, so the component stays generic in `T`.
+
+## One transform, every slide mounted
+The track slides with a single `translateX` of a multiple of 100%, so every slide stays mounted —
+paging does not lose state inside a slide (a form, a playing video, a scroll position).
+
+## Examples
+    <KptCarousel items={photos} renderSlide={(photo) => <img src={photo} style={{ width: '100%' }} />} />
+    <KptCarousel items={slides} activeIndex={index} onActiveIndexChange={setIndex} renderSlide={renderSlide} />
+
+## i18n
+The arrows use `common.previous` / `common.next`, the dots `carousel.slide` (`{index}`).
+
+## Tokens
+The navigation and dots `--kpt-color-primary`, the arrow background `--kpt-color-surface-raised`.
+
+## Accessibility
+The arrows are disabled at the ends instead of wrapping around, and every dot is a labelled button,
+so a slide can be reached directly from the keyboard.

package/dist/charts/chart-legend.d.ts

@@ -6,7 +6,7 @@ export interface KptChartLegendItem {
     hidden: boolean;
 }
 export interface KptChartLegendProps {
-    items?: KptChartLegendItem[];
+    items?: readonly KptChartLegendItem[];
     position?: KptLegendPosition;
     align?: KptAlign;
     pointStyle?: KptPointStyle;

package/dist/charts/llms.txt

@@ -0,0 +1,57 @@
+# KptChart (@konce-pt/react/charts)
+
+An SVG chart driven by a single `config` object: line, bar, pie, doughnut, polarArea, radar.
+Import: `import { KptChart, type KptChartConfig } from '@konce-pt/react/charts';`
+
+A separate subpath, because the geometry and the chart styles are heavy next to the library core
+and not every app needs them.
+
+## Props
+- `config`: `KptChartConfig` (required)
+- `width`, `height` — the viewBox in SVG units (600 × 360); the chart scales to its container
+
+The whole drawing lives in that coordinate system, TYPOGRAPHY INCLUDED: the axis labels are set in
+`font-size: 11px`, but inside an SVG that means 11 user units, not 11 device pixels. Render a
+600-unit chart in a 300px column and the labels come out at roughly half size. `width`/`height` are
+therefore not just an aspect ratio — they are the text scale. In a narrow container shrink them
+proportionally (`width={300} height={180}`) instead of letting a 600-unit chart squeeze itself.
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The config is the API
+`{ type, labels, series, points?, area?, interpolation?, orientation?, borderRadius?, innerRadius?,
+crosshair?, tooltip?, legend?, title?, subtitle?, animation? }` — the same shape the Angular port
+takes, because both read it from `@konce-pt/chart`.
+
+## The geometry lives in a package
+Scales, paths, bar layout and arcs come from `@konce-pt/chart` — pure functions with `node --test`
+coverage, shared with the Angular port. The component only turns them into SVG elements; there is
+no DOM manipulation and no canvas.
+
+## Points have a bigger hit target than they look
+A 4px point is not something a pointer can reliably hit, so each one is paired with an invisible
+12px circle that carries the events. The visible point only reacts to the state.
+
+## Interaction is local state
+Hidden series, the highlighted one, the tooltip and the active category are `useState` — the config
+stays a plain object the caller owns, and nothing is written back into it.
+
+## Examples
+    <KptChart config={{ type: 'line', labels: ['Jan', 'Feb'], series: [{ name: 'Sales', data: [12, 19] }] }} />
+
+    <KptChart
+      config={{
+        type: 'doughnut',
+        innerRadius: 0.62,
+        labels: ['Done', 'In progress'],
+        series: [{ name: 'Tasks', data: [42, 15] }],
+        legend: { position: 'right' },
+      }}
+    />
+
+## Tokens
+`--kpt-chart-{duration,stagger,delay}` for the animation; series colours come from
+`KPT_CHART_PALETTE` or `series.color`.
+
+## Accessibility
+The `<svg>` carries `role="img"`; the legend is a list of real buttons, so series can be toggled
+from the keyboard.