@konce-pt/react 0.8.1 → 0.8.3

package/dist/megamenu/llms.txt

@@ -0,0 +1,48 @@
+# KptMegamenu (@konce-pt/react)
+
+A mega menu — a horizontal bar with a wide, multi-column panel.
+Import: `import { KptMegamenu } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-megamenu-host">
+      <nav class="kpt-megamenu" role="menubar">
+        <button class="kpt-megamenu__top is-open" role="menuitem">Products …caret…</button>
+      </nav>
+    </div>
+    <!-- while open, in a portal: -->
+    <div class="kpt-megamenu__panel" role="menu">
+      <div class="kpt-megamenu__column">
+        <div class="kpt-megamenu__col-title">Components</div>
+        <button class="kpt-megamenu__link">Forms</button>
+      </div>
+    </div>
+
+## Props
+- `items`: `KptMenuItem<T>[]` — three levels: top item → `items` (columns) → column `items` (links)
+- `onSelect(link)` — a picked link from a column
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The panel is anchored to the whole bar
+Not to the clicked button: the panel is wide, so it should start at the edge of the menu rather
+than at whichever item happened to be pressed. Switching to another top item swaps the columns
+without closing the panel, so browsing across sections costs one click each.
+
+## Examples
+    <KptMegamenu items={items} onSelect={onSelect} />
+
+    // top → columns → links
+    const items: KptMenuItem[] = [{
+      label: 'Products',
+      items: [
+        { label: 'Components', items: [{ label: 'Forms' }, { label: 'Tables' }] },
+        { label: 'Templates', items: [{ label: 'Dashboard' }] },
+      ],
+    }];
+
+## Tokens
+`--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-elevation-3`,
+`--kpt-color-on-surface-muted` (the column titles).
+
+## Accessibility
+The bar is `role="menubar"` with `role="menuitem"` buttons; the panel is `role="menu"`. Column
+titles are plain text, not headings, so they do not disturb the page outline.

package/dist/megamenu/megamenu.d.ts

@@ -1,7 +1,7 @@
 import { type ComponentPropsWithRef } from 'react';
 import type { KptMenuItem } from '../menu/menu-item.ts';
 export interface KptMegamenuProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onSelect'> {
-    items?: KptMenuItem<T>[];
+    items?: readonly KptMenuItem<T>[];
     onSelect?: (item: KptMenuItem<T>) => void;
 }
 /**

package/dist/menu/llms.txt

@@ -0,0 +1,56 @@
+# KptMenu (@konce-pt/react)
+
+A dropdown menu. Items come from `items`, the trigger from the `trigger` prop.
+Import: `import { KptMenu, type KptMenuItem } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-menu-host"><span class="kpt-menu__trigger">…trigger…</span></span>
+    <!-- while open, in a portal on document.body: -->
+    <div class="kpt-menu__panel" role="menu">
+      <div class="kpt-menu__header" role="presentation">…</div>
+      <div class="kpt-menu__separator" role="separator"></div>
+      <button class="kpt-menu__item" role="menuitem">…</button>
+    </div>
+
+## Props
+- `items`: `KptMenuItem<T>[]`
+- `trigger`: ReactNode — the element that opens the menu, rendered in place
+- `onSelect(item)` — the picked item; headers, separators and disabled items never arrive here
+- `open` / `defaultOpen` / `onOpenChange` — controlled or uncontrolled
+- `className`, `ref` and every other `<span>` prop go to the host
+
+## KptMenuItem
+`label`, `value`, `icon`, `description` (a second line), `badge` + `badgeVariant`,
+`avatar` (`{ src?, name?, icon? }` — the header row of a user menu), `header` (a non-clickable
+block instead of an item), `disabled`, `danger`, `separator`, plus `items` and `url` for the
+menubar and megamenu that build on the same shape.
+
+## The panel is a portal
+It renders through the internal `KptOverlay`, so no overlay stylesheet is required — unlike the
+Angular port, which stands on CDK. Position, backdrop and Escape behave the same.
+
+## Examples
+    <KptMenu items={items} onSelect={onSelect} trigger={<KptButton variant="outline">Options</KptButton>} />
+
+    const items: KptMenuItem[] = [
+      { header: true, avatar: { src: '/u/admin.jpg' }, label: 'Admin', description: 'admin@konce.pt' },
+      { separator: true },
+      { label: 'Edit', value: 'edit', icon: 'copy' },
+      { label: 'Notifications', value: 'notif', icon: 'bell', badge: 4, badgeVariant: 'success' },
+      { separator: true },
+      { label: 'Delete', value: 'del', icon: 'x', danger: true },
+    ];
+
+## Tokens
+`--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-elevation-3`, `--kpt-color-danger`
+(the `danger` item), `--kpt-z-overlay`.
+
+## Accessibility
+The panel is `role="menu"`, items are native buttons with `role="menuitem"`, separators carry
+`role="separator"` and header rows `role="presentation"`, so a screen reader skips them instead of
+announcing them as actions.
+
+The trigger itself gets `aria-haspopup="menu"` and a live `aria-expanded`. They are placed on the
+interactive control INSIDE the slot (the projected `<button>`/`<a>`), never on the
+`.kpt-menu__trigger` wrapper — giving that wrapper a role would create a nested control and a second
+tab stop, and state attributes on a roleless element violate `aria-allowed-attr`.

package/dist/menu/menu-item.d.ts

@@ -27,7 +27,7 @@ export interface KptMenuItem<T = unknown> {
     danger?: boolean;
     separator?: boolean;
     /** Pozycje podrzędne (menubar / megamenu). */
-    items?: KptMenuItem<T>[];
+    items?: readonly KptMenuItem<T>[];
     /** Adres odnośnika (menubar / megamenu). */
     url?: string;
 }

package/dist/menu/menu-rows.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 import type { KptMenuItem } from './menu-item.ts';
 export interface MenuRowsProps<T> {
-    items: KptMenuItem<T>[];
+    items: readonly KptMenuItem<T>[];
     /** Prefiks bloku BEM: `kpt-menu` albo `kpt-context-menu`. */
     block: string;
     onPick: (item: KptMenuItem<T>) => void;

package/dist/menu/menu.d.ts

@@ -1,7 +1,7 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
 import type { KptMenuItem } from './menu-item.ts';
 export interface KptMenuProps<T> extends Omit<ComponentPropsWithRef<'span'>, 'onSelect'> {
-    items?: KptMenuItem<T>[];
+    items?: readonly KptMenuItem<T>[];
     /** Element otwierający menu — renderowany w miejscu komponentu. */
     trigger: ReactNode;
     /** Wybrana pozycja; pozycje `header`, `separator` i wyłączone nigdy tu nie trafiają. */

package/dist/menu/menu.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { cn } from "../internal/cn.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
@@ -21,6 +21,17 @@ export function KptMenu({ items = [], trigger, onSelect, open, defaultOpen = fal
         onChange: onOpenChange,
     });
     const close = useCallback(() => setOpen(false), [setOpen]);
+    // ARIA idzie na kontrolkę wewnątrz slotu, nie na `.kpt-menu__trigger`. Trigger to zwykły
+    // `<span>` opakowujący dowolny węzeł z propa `trigger`: nadanie mu `role="button"` zrobiłoby
+    // zagnieżdżoną kontrolkę i drugi tab stop. `cloneElement` też odpada — `trigger` bywa
+    // komponentem, który nie przekazuje nieznanych propsów dalej na DOM.
+    useEffect(() => {
+        const control = triggerRef.current?.querySelector('button, a, [role="button"]');
+        if (!control)
+            return;
+        control.setAttribute('aria-haspopup', 'menu');
+        control.setAttribute('aria-expanded', String(isOpen));
+    }, [isOpen, trigger]);
     const pick = (item) => {
         if (item.disabled)
             return;

package/dist/menubar/llms.txt

@@ -0,0 +1,45 @@
+# KptMenubar (@konce-pt/react)
+
+A horizontal menu bar with dropdowns. An item without `items` acts as an action or a link.
+Import: `import { KptMenubar } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-menubar-host">
+      <nav class="kpt-menubar" role="menubar">
+        <div class="kpt-menubar__group">
+          <button class="kpt-menubar__top is-open" role="menuitem">File …caret…</button>
+        </div>
+      </nav>
+    </div>
+    <!-- while open, in a portal: -->
+    <div class="kpt-menubar__dropdown" role="menu">…items and separators…</div>
+
+## Props
+- `items`: `KptMenuItem<T>[]` — a top item's `items` become its dropdown
+- `onSelect(item)` — an action item, or a pick from a dropdown
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The dropdown is a portal
+It renders outside the bar, so a parent with `overflow: hidden` cannot clip it — the same benefit
+the Angular port gets from CDK Overlay, without CDK. Each dropdown is anchored to its own top
+button, so it opens directly under the label it belongs to.
+
+## Top items do double duty
+With `items` a top item toggles its dropdown; without them it fires `onSelect` straight away, so a
+bar can mix menus and plain actions with no extra flag.
+
+## Examples
+    <KptMenubar items={items} onSelect={onSelect} />
+
+    const items: KptMenuItem[] = [
+      { label: 'File', items: [{ label: 'New' }, { separator: true }, { label: 'Close', danger: true }] },
+      { label: 'Help' },
+    ];
+
+## Tokens
+`--kpt-color-surface`, `--kpt-color-muted` (the open top item), `--kpt-color-surface-raised` and
+`--kpt-elevation-3` for the dropdown, `--kpt-color-danger`.
+
+## Accessibility
+The bar is `role="menubar"`, top items and dropdown rows are `role="menuitem"`, separators carry
+`role="separator"`.

package/dist/menubar/menubar.d.ts

@@ -1,7 +1,7 @@
 import { type ComponentPropsWithRef } from 'react';
 import type { KptMenuItem } from '../menu/menu-item.ts';
 export interface KptMenubarProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onSelect'> {
-    items?: KptMenuItem<T>[];
+    items?: readonly KptMenuItem<T>[];
     onSelect?: (item: KptMenuItem<T>) => void;
 }
 /**

package/dist/meter-group/llms.txt

@@ -0,0 +1,47 @@
+# KptMeterGroup (@konce-pt/react)
+
+A multi-segment meter with an optional legend.
+Import: `import { KptMeterGroup } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-meter-group-host">
+      <div class="kpt-meter-group">
+        <div class="kpt-meter-group__track" role="meter" aria-valuenow="100">
+          <span class="kpt-meter-group__segment" style="width:45%" title="Documents"></span>…
+        </div>
+        <ul class="kpt-meter-group__legend">
+          <li class="kpt-meter-group__legend-item">
+            <span class="kpt-meter-group__dot"></span><span>Documents</span>
+            <span class="kpt-meter-group__val">45%</span>
+          </li>…
+        </ul>
+      </div>
+    </div>
+
+## Props
+- `values`: `KptMeterItem[]` — `{ label, value, color? }`
+- `max`: number — the reference total; without it the values' sum is 100%
+- `showLegend`: boolean (default true)
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Percentages come from the sum, not from 100
+Without `max` the reference is the sum of the values, so `[45, 25, 15, 15]` and `[9, 5, 3, 3]`
+draw the same picture. Pass `max` when the segments are meant to leave a gap — a quota that is
+not full yet. All-zero values fall back to a divisor of 1 instead of producing `NaN%`.
+
+## Colours
+`color` per item, otherwise the next one from the semantic palette
+(`primary → info → success → warning → danger`, cycled), so a group of any length stays readable
+without picking colours by hand.
+
+## Examples
+    <KptMeterGroup values={[{ label: 'Used', value: 70 }, { label: 'Free', value: 30 }]} />
+    <KptMeterGroup values={values} max={200} showLegend={false} />
+
+## Tokens
+The palette `--kpt-color-{primary,info,success,warning,danger}`, the track
+`--kpt-color-surface-sunken`.
+
+## Accessibility
+The track is `role="meter"` with `aria-valuenow`; every segment carries a native `title`, and the
+legend repeats the same values as text.

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

@@ -6,7 +6,7 @@ export interface KptMeterItem {
     color?: string;
 }
 export interface KptMeterGroupProps extends ComponentPropsWithRef<'div'> {
-    values?: KptMeterItem[];
+    values?: readonly KptMeterItem[];
     /** Suma odniesienia; domyślnie suma wartości, czyli segmenty wypełniają całość. */
     max?: number;
     showLegend?: boolean;

package/dist/order-list/llms.txt

@@ -0,0 +1,41 @@
+# KptOrderList (@konce-pt/react)
+
+A list with manual reordering. Click selects an item, the buttons move it up and down.
+Import: `import { KptOrderList } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-order-list-host">
+      <div class="kpt-order-list">
+        <div class="kpt-order-list__controls">…up, down…</div>
+        <div class="kpt-order-list__panel">
+          <div class="kpt-order-list__header">Order</div>
+          <ul class="kpt-order-list__items">
+            <li class="kpt-order-list__item is-selected">…</li>…
+          </ul>
+        </div>
+      </div>
+    </div>
+
+## Props
+- `items` / `defaultItems` / `onItemsChange` — the list; the callback receives the new order
+- `header`: string
+- `renderItem(item, index)` — required; the equivalent of `<ng-template let-item>`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The selection follows the item
+After a move the selection jumps to the new index, so pressing the button again moves the same
+entry — with the selection pinned to a position, the second press would move its neighbour.
+
+## Examples
+    <KptOrderList items={tasks} onItemsChange={setTasks} header="Order" renderItem={(item) => item} />
+    <KptOrderList defaultItems={steps} renderItem={(step) => step.name} />
+
+## i18n
+The buttons use `orderList.up` and `orderList.down`.
+
+## Tokens
+The selection `--kpt-color-primary`, the buttons `--kpt-color-surface-raised`.
+
+## Accessibility
+Both buttons are labelled from the dictionary and go disabled while nothing is selected, so the
+control never looks broken.

package/dist/paginator/llms.txt

@@ -0,0 +1,48 @@
+# KptPaginator (@konce-pt/react)
+
+Page-size selector, item range and navigation.
+Import: `import { KptPaginator } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-paginator">
+      <div class="kpt-paginator__size"><label>Rows: <select class="kpt-paginator__select">…</select></label></div>
+      <span class="kpt-paginator__range">1–10 of 120</span>
+      <div class="kpt-paginator__nav">…two KptButton…</div>
+    </div>
+
+## Props
+- `length`: number — the total number of items (required)
+- `pageIndex` / `defaultPageIndex` / `onPageIndexChange` — the 0-based page
+- `pageSize` / `defaultPageSize` / `onPageSizeChange` — the page size (default 10)
+- `pageSizeOptions`: readonly number[] (default [5, 10, 20, 50])
+
+  The select always offers the current `pageSize` even when it is absent from this list: without
+  that, `pageSize={8}` against the defaults left no matching option, so the control displayed the
+  first entry while the table paged by eight.
+- `prevIcon`, `nextIcon`: ReactNode — the navigation button content
+- `locale`, `dictionary` — i18n overrides for this component only
+- `className`, `ref` and every other `<div>` prop go to the paginator root
+
+## Behaviour
+Works controlled and uncontrolled. Changing the page size returns to the first page. The index is
+clamped whenever `length` or `pageSize` shrinks it out of range, so the component never shows an
+empty page after the data changes underneath it.
+
+## i18n
+Labels come from the dictionary: `paginator.rowsPerPage`, `paginator.prevPage`,
+`paginator.nextPage` and `paginator.range` with `{start}`, `{end}` and `{total}` interpolation.
+
+## Icons
+The default arrows are `KptIcon` with `chevron-left` / `chevron-right` from the built-in set, so
+they work without registering the full Tabler set. Pass `prevIcon` / `nextIcon` to swap in your own.
+
+## Examples
+    <KptPaginator length={120} pageIndex={page} onPageIndexChange={setPage} />
+    <KptPaginator length={total} defaultPageSize={20} pageSizeOptions={[20, 50, 100]} />
+
+## Tokens
+`--kpt-form-field-{bg,text,border,border-focus}` for the select, plus the button tokens.
+
+## Accessibility
+The navigation buttons carry `aria-label` from the dictionary and go `disabled` at the ends of the
+range, so the keyboard never lands on a dead control.

package/dist/paginator/paginator.d.ts

@@ -12,7 +12,7 @@ export interface KptPaginatorProps extends Omit<ComponentPropsWithRef<'div'>, 'c
     defaultPageIndex?: number;
     onPageIndexChange?: (pageIndex: number) => void;
     /** Dostępne rozmiary strony. */
-    pageSizeOptions?: number[];
+    pageSizeOptions?: readonly number[];
     /** Treść przycisków nawigacji; domyślnie strzałki z wbudowanego zestawu ikon. */
     prevIcon?: ReactNode;
     nextIcon?: ReactNode;

package/dist/paginator/paginator.js

@@ -41,5 +41,11 @@ export function KptPaginator({ length, pageSize, defaultPageSize = 10, onPageSiz
         setSize(Number(event.target.value));
         setIndex(0);
     };
-    return (_jsxs("div", { className: cn('kpt-paginator', className), ...rest, children: [_jsx("div", { className: "kpt-paginator__size", children: _jsxs("label", { children: [t('paginator.rowsPerPage'), _jsx("select", { className: "kpt-paginator__select", value: size, onChange: onSizeChange, children: pageSizeOptions.map((option) => (_jsx("option", { value: option, children: option }, option))) })] }) }), _jsx("span", { className: "kpt-paginator__range", children: t('paginator.range', { start: rangeStart, end: rangeEnd, total: length }) }), _jsxs("div", { className: "kpt-paginator__nav", children: [_jsx(KptButton, { variant: "outline", size: "sm", disabled: !canPrev, onClick: () => setIndex(index - 1), "aria-label": t('paginator.prevPage'), children: prevIcon }), _jsx(KptButton, { variant: "outline", size: "sm", disabled: !canNext, onClick: () => setIndex(index + 1), "aria-label": t('paginator.nextPage'), children: nextIcon })] })] }));
+    // Opcje selecta uzupełnione o bieżący rozmiar. Bez tego `pageSize` spoza listy nie ma
+    // odpowiadającej opcji: React ostrzega o `value` bez dopasowania, a select pokazuje
+    // pierwszą pozycję, choć stronicowanie idzie po zupełnie innej liczbie.
+    const sizeOptions = pageSizeOptions.includes(size)
+        ? pageSizeOptions
+        : [...pageSizeOptions, size].sort((a, b) => a - b);
+    return (_jsxs("div", { className: cn('kpt-paginator', className), ...rest, children: [_jsx("div", { className: "kpt-paginator__size", children: _jsxs("label", { children: [t('paginator.rowsPerPage'), _jsx("select", { className: "kpt-paginator__select", value: size, onChange: onSizeChange, children: sizeOptions.map((option) => (_jsx("option", { value: option, children: option }, option))) })] }) }), _jsx("span", { className: "kpt-paginator__range", children: t('paginator.range', { start: rangeStart, end: rangeEnd, total: length }) }), _jsxs("div", { className: "kpt-paginator__nav", children: [_jsx(KptButton, { variant: "outline", size: "sm", disabled: !canPrev, onClick: () => setIndex(index - 1), "aria-label": t('paginator.prevPage'), children: prevIcon }), _jsx(KptButton, { variant: "outline", size: "sm", disabled: !canNext, onClick: () => setIndex(index + 1), "aria-label": t('paginator.nextPage'), children: nextIcon })] })] }));
 }

package/dist/panel/llms.txt

@@ -0,0 +1,55 @@
+# KptPanel (@konce-pt/react)
+
+A panel with a header and optional collapsing.
+Import: `import { KptPanel } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-panel-host" style="--kpt-anim-duration: 500ms">
+      <div class="kpt-panel">
+        <div class="kpt-panel__header">
+          <span class="kpt-panel__title">Settings</span>
+          <span class="kpt-panel__actions">…actions…</span>
+          <button class="kpt-panel__toggle" aria-expanded="true" aria-label="Collapse / expand">…</button>
+        </div>
+        <div class="kpt-panel__collapse is-open">
+          <div class="kpt-panel__collapse-inner">
+            <div class="kpt-panel__body">…children…</div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+## Props
+- `header`: string
+- `toggleable`: boolean — adds the collapse button to the header
+- `collapsed` / `defaultCollapsed` / `onCollapsedChange` — controlled or uncontrolled
+- `animated`: boolean (default true), `animationDuration`: number (ms, default 500)
+- `locale`, `dictionary` — i18n overrides for this component only
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Sub-components
+- `KptPanel.Actions` — lifted into the header, next to the title, before the collapse button.
+
+## Collapsed content stays mounted
+It gets `inert` and `aria-hidden` rather than being removed, so the height is animatable while
+nothing inside can take focus or be read out. That is also why a collapsed panel keeps the state of
+whatever lives in it — a half-filled form inside survives a collapse.
+
+## i18n
+The toggle's label comes from `panel.toggle` in the dictionary.
+
+## Examples
+    <KptPanel header="Settings" toggleable>Panel content…</KptPanel>
+
+    <KptPanel header="Filters" toggleable collapsed={collapsed} onCollapsedChange={setCollapsed}>
+      <KptPanel.Actions><KptIconButton aria-label="Reset"><KptIcon name="x" /></KptIconButton></KptPanel.Actions>
+      …
+    </KptPanel>
+
+## Tokens
+`--kpt-color-surface`, `--kpt-color-border`, `--kpt-radius-lg`, `--kpt-motion-easing-standard`.
+
+## Accessibility
+The toggle is a native button with `aria-expanded` and a label from the dictionary. The header
+title is a `<span>`, not a heading — give the panel your own heading when it needs one in the
+document outline.

package/dist/password/llms.txt

@@ -0,0 +1,45 @@
+# KptPassword (@konce-pt/react)
+
+A password field with a reveal toggle and an optional strength meter.
+Import: `import { KptPassword } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-password-host">
+      <div class="kpt-password">
+        <input class="kpt-password__input" type="password" autocomplete="current-password">
+        <button class="kpt-password__toggle" type="button" aria-label="Show password">…</button>
+      </div>
+      <div class="kpt-password__meter" data-score="3">
+        <div class="kpt-password__bars"><span class="kpt-password__bar is-on"></span>…</div>
+        <span class="kpt-password__hint">Good</span>
+      </div>
+    </div>
+
+## Props
+- `value` / `defaultValue` / `onValueChange`
+- `feedback`: boolean — shows the strength meter once something is typed
+- `autoComplete`: string | null (default 'current-password')
+- `placeholder`, `id`, `disabled`, `invalid`, `touched`, `onTouch()`
+- `locale`, `dictionary` — i18n overrides for this component only
+
+## autoComplete is not a detail
+Sign-up and password reset need `autoComplete="new-password"`. With the default, a password manager
+fills in the OLD password instead of offering a new one, and the user ends up saving the wrong
+thing.
+
+## How the score is computed
+Four independent criteria, one point each: at least 8 characters, both letter cases, a digit, a
+non-alphanumeric character. The label comes from `password.strength` — the only array-valued key in
+the dictionary — indexed by the score, so a translation controls the wording without touching code.
+
+## Examples
+    <KptPassword value={pass} onValueChange={setPass} feedback />
+    <KptPassword value={pass} onValueChange={setPass} autoComplete="new-password" feedback />
+
+## Tokens
+`--kpt-form-field-*` for the field, `--kpt-color-danger` / `-warning` / `-success` for the meter
+bars by score.
+
+## Accessibility
+The toggle's label swaps between `password.show` and `password.hide`, so a screen reader knows what
+pressing it will do rather than just that a button exists.

package/dist/pick-list/llms.txt

@@ -0,0 +1,52 @@
+# KptPickList (@konce-pt/react)
+
+Transfers items between two lists. Click to select, the middle buttons move the selection or
+everything.
+Import: `import { KptPickList } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-pick-list-host">
+      <div class="kpt-pick-list">
+        <div class="kpt-pick-list__col">
+          <div class="kpt-pick-list__header">Available</div>
+          <ul class="kpt-pick-list__items">
+            <li class="kpt-pick-list__item is-selected">…</li>…
+          </ul>
+        </div>
+        <div class="kpt-pick-list__controls">…four buttons…</div>
+        <div class="kpt-pick-list__col">…</div>
+      </div>
+    </div>
+
+## Props
+- `source` / `defaultSource` / `onSourceChange` — the left list
+- `target` / `defaultTarget` / `onTargetChange` — the right list
+- `sourceHeader`, `targetHeader` — without them `pickList.available` / `pickList.selected`
+- `renderItem(item, index)` — required; the equivalent of `<ng-template let-item>`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The selection is kept by reference
+Selected items live in a `Set` of references, not of indexes: after a move the indexes on both
+sides shift, while a reference stays the same. That is also why a moved item never carries its
+selection over — the selection is cleared on every move.
+
+## Two lists, two controlled values
+Both sides are independent controllable values, so the component works uncontrolled (`default*`),
+half-controlled, or fully controlled by the form.
+
+## Examples
+    <KptPickList
+      source={available} onSourceChange={setAvailable}
+      target={selected} onTargetChange={setSelected}
+      renderItem={(item) => item.name}
+    />
+
+## i18n
+The headers and the four move buttons come from the `pickList` namespace.
+
+## Tokens
+The selection `--kpt-color-primary`, the headers `--kpt-color-surface-variant`.
+
+## Accessibility
+Every move button is labelled from the dictionary, so "move all right" is distinguishable from
+"move right" without seeing the double chevron.

package/dist/popover/llms.txt

@@ -0,0 +1,42 @@
+# KptPopover (@konce-pt/react)
+
+Any content in a bubble pinned to its trigger — richer than a tooltip.
+Import: `import { KptPopover } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-popover-host">
+      <span class="kpt-popover__trigger">…trigger…</span>
+    </span>
+    <!-- while open, in a portal on document.body: -->
+    <div class="kpt-popover__panel" role="dialog">…children…</div>
+
+## Props
+- `trigger`: ReactNode — the element that opens the bubble, rendered in place
+- `children`: ReactNode — the panel content
+- `open` / `defaultOpen` / `onOpenChange` — controlled or uncontrolled
+- `className`, `ref` and every other `<span>` prop go to the host
+
+## The panel is a portal
+The Angular port stands on CDK Overlay. Here the panel renders into a portal on `document.body`
+with the same behaviour: positioned below the trigger, flipping above when there is no room, closed
+by a click outside or by Escape, and following scroll and resize.
+
+Clicking the trigger while the bubble is open closes it and does not reopen it — the transparent
+backdrop takes that click, exactly as the CDK backdrop does.
+
+## Examples
+    <KptPopover trigger={<KptButton variant="outline">Details</KptButton>}>
+      <div>Richer content in the bubble.</div>
+    </KptPopover>
+
+    <KptPopover open={open} onOpenChange={setOpen} trigger={<KptButton>Filters</KptButton>}>
+      <FilterForm onDone={() => setOpen(false)} />
+    </KptPopover>
+
+## Tokens
+`--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-radius-md`, `--kpt-elevation-3`,
+`--kpt-z-overlay`.
+
+## Accessibility
+The panel is `role="dialog"` and Escape closes it. Focus is not trapped — the popover is meant for
+supporting content, so for a real modal reach for a dialog instead.

package/dist/progress/llms.txt

@@ -0,0 +1,47 @@
+# KptProgress (@konce-pt/react)
+
+A progress indicator — linear or circular, determinate (0–100) or indeterminate (`value` = null).
+Import: `import { KptProgress } from '@konce-pt/react';`
+
+## DOM
+    <!-- linear -->
+    <div class="kpt-progress-host">
+      <div class="kpt-progress__linear" data-variant="primary" role="progressbar" aria-valuenow="65">
+        <div class="kpt-progress__bar" style="width: 65%"></div>
+      </div>
+    </div>
+
+    <!-- circular -->
+    <svg class="kpt-progress__circular" data-variant="success" viewBox="0 0 40 40" role="progressbar" aria-valuenow="75">
+      <circle class="kpt-progress__track" cx="20" cy="20" r="16"></circle>
+      <circle class="kpt-progress__bar" cx="20" cy="20" r="16" style="stroke-dasharray: 100.531; stroke-dashoffset: 25.1327"></circle>
+    </svg>
+
+## Props
+- `value`: number | null (default null) — 0–100, or null for indeterminate
+- `variant`: 'primary' | 'success' | 'danger' | 'warning' | 'info' (default 'primary')
+- `type`: 'linear' | 'circular' (default 'linear')
+- `diameter`: number (default 40) — the circular variant's size in pixels
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## How the arc is drawn
+The circle lives in a fixed `viewBox="0 0 40 40"` with `r=16`, so the circumference is computed
+from that radius, not from `diameter` — the SVG scales, the maths does not change. The arc is the
+dash offset: full circumference means empty, zero means complete. An indeterminate circle is pinned
+at a quarter of the circumference and spun by CSS.
+
+Values outside 0–100 are clamped rather than rejected, so a computed percentage that briefly
+overshoots cannot break the drawing.
+
+## Examples
+    <KptProgress value={65} />
+    <KptProgress value={null} variant="info" />
+    <KptProgress type="circular" value={75} variant="success" diameter={64} />
+
+## Tokens
+The semantic colour of each variant (`--kpt-color-primary` / `-success` / `-danger` / `-warning` /
+`-info`), `--kpt-color-muted` for the track.
+
+## Accessibility
+`role="progressbar"` with `aria-valuenow`; an indeterminate bar leaves the value out, which is how
+a screen reader learns the progress is unknown rather than zero.