@konce-pt/react 0.8.1 → 0.8.3

package/dist/split-button/llms.txt

@@ -0,0 +1,54 @@
+# KptSplitButton (@konce-pt/react)
+
+A split button — a primary action plus a dropdown of further actions.
+Import: `import { KptSplitButton } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-split-button-host">
+      <div class="kpt-split-button" data-variant="filled">
+        <button class="kpt-split-button__main" type="button">Save</button>
+        <button class="kpt-split-button__toggle" type="button" aria-label="More actions">…chevron…</button>
+      </div>
+    </span>
+    <!-- while open, in a portal: -->
+    <div class="kpt-split-button__panel" role="menu">…rows…</div>
+
+## Props
+- `variant`: the same union as `KptButton` (default 'filled')
+- `items`: `KptMenuItem<T>[]` — the same shape as `KptMenu`
+- `disabled`: boolean — disables both buttons
+- `onPrimaryClick()` — the main action
+- `onSelect(item)` — a pick from the menu
+- `open` / `defaultOpen` / `onOpenChange` — the panel state
+- `children` — the content of the main action
+- `locale`, `dictionary` — i18n overrides for this component only
+
+## The panel aligns to the right
+The toggle sits on the right-hand side of the control, so the panel is anchored by its RIGHT edge
+(`align="end"` on the overlay). Anchored to the left it would hang off the control instead of under
+it — the same reasoning the Angular port encodes in its CDK position list.
+
+## Shared rows
+The panel renders the same rows as `KptMenu` — icons, descriptions, badges, separators, headers and
+the `danger` modifier all behave identically, only the BEM block differs.
+
+## i18n
+The toggle's label comes from `splitButton.more` in the dictionary.
+
+## Examples
+    <KptSplitButton items={items} onPrimaryClick={save} onSelect={onItem}>Save</KptSplitButton>
+
+    const items: KptMenuItem[] = [
+      { label: 'Save as draft', value: 'draft' },
+      { label: 'Save and publish', value: 'publish' },
+      { separator: true },
+      { label: 'Discard', value: 'discard', danger: true },
+    ];
+
+## Tokens
+The `--kpt-button-*` tokens of the chosen variant, plus `--kpt-color-surface-raised` and
+`--kpt-elevation-3` for the panel.
+
+## Accessibility
+Two native buttons; the toggle carries `aria-label`, the panel is `role="menu"` with
+`role="menuitem"` rows.

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

@@ -4,7 +4,7 @@ import type { KptMenuItem } from '../menu/menu-item.ts';
 import type { KptButtonVariant } from '../button/button.tsx';
 export interface KptSplitButtonProps<T> extends Omit<ComponentPropsWithRef<'span'>, 'onSelect'>, KptI18nOverrides {
     variant?: KptButtonVariant;
-    items?: KptMenuItem<T>[];
+    items?: readonly KptMenuItem<T>[];
     disabled?: boolean;
     /** Kliknięcie akcji głównej. */
     onPrimaryClick?: () => void;

package/dist/splitter/llms.txt

@@ -0,0 +1,44 @@
+# KptSplitter (@konce-pt/react)
+
+Two panes with a draggable handle.
+Import: `import { KptSplitter } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-splitter-host">
+      <div class="kpt-splitter" data-orientation="horizontal">
+        <div class="kpt-splitter__pane" style="flex-basis:40%">…</div>
+        <div class="kpt-splitter__gutter" role="separator" tabindex="0" aria-valuenow="40"></div>
+        <div class="kpt-splitter__pane" style="flex-basis:60%">…</div>
+      </div>
+    </div>
+
+## Props
+- `orientation`: `'horizontal'` (default) | `'vertical'`
+- `startSize` / `defaultStartSize` / `onStartSizeChange` — the first pane's size in percent
+- `minSize`: number (percent, default 10) — neither pane goes below it
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Panes
+`<KptSplitter.Start>` and `<KptSplitter.End>` replace Angular's `[kptSplitStart]` / `[kptSplitEnd]`
+slots. They render nothing themselves: the splitter reads their children and wraps them in
+`__pane`, because it is the splitter that owns the size.
+
+## Dragging listens on the window
+`pointermove` and `pointerup` are attached to `window`, not to the handle: on a quick drag the
+pointer outruns a 6px strip, and a handle-bound listener would drop the drag after a few pixels.
+
+## Examples
+    <KptSplitter startSize={size} onStartSizeChange={setSize}>
+      <KptSplitter.Start>Left</KptSplitter.Start>
+      <KptSplitter.End>Right</KptSplitter.End>
+    </KptSplitter>
+
+    <KptSplitter orientation="vertical" defaultStartSize={30} minSize={20}>…</KptSplitter>
+
+## Tokens
+The handle `--kpt-color-border` → `--kpt-color-primary` on hover and focus; the frame
+`--kpt-color-border` with `--kpt-radius-md`.
+
+## Accessibility
+The handle is `role="separator"` with `aria-orientation` and `aria-valuenow`, reachable with Tab;
+the arrow keys resize by 2% a press, clamped by `minSize`.

package/dist/stepper/llms.txt

@@ -0,0 +1,64 @@
+# KptStepper + KptStep (@konce-pt/react)
+
+A step wizard — a header of numbered steps plus the active step's content.
+Import: `import { KptStepper, useKptStepper } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-stepper-host" style="--kpt-anim-duration:500ms; --kpt-anim-dir:1">
+      <ol class="kpt-stepper__header">
+        <li class="kpt-stepper__step is-done">
+          <button class="kpt-stepper__marker">✓</button>
+          <span class="kpt-stepper__label">Account</span>
+          <span class="kpt-stepper__connector"></span>
+        </li>
+        …
+      </ol>
+      <div class="kpt-stepper__body"><div class="kpt-stepper__panel">…</div></div>
+    </div>
+
+## KptStepper props
+- `activeIndex` / `defaultActiveIndex` / `onActiveIndexChange`
+- `animated`: boolean (default true), `animationDuration`: ms (default 500)
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## KptStepper.Step props
+- `label`: string (required); `children` — the step's content
+
+## useKptStepper()
+`{ activeIndex, count, next, prev, goTo }` — the replacement for Angular's `#s` + `s.next()`.
+It reads a context the stepper provides around the panel, so it works only in a component
+rendered inside a step (a hook cannot be called in the parent's body) and throws elsewhere.
+`count` lets a step hide "Next" on the last one.
+
+## The step is a config carrier
+`KptStep` renders `null`; `KptStepper` reads its props and decides what to show, so only the
+active step's content is ever mounted — the same laziness as the `kpt-step` template in Angular.
+
+## The panel is keyed by index
+`key={active}` forces a remount on every change, otherwise the enter animation would have nothing
+to start from. The slide direction rides on `--kpt-anim-dir` (1 forward, -1 back), so jumping to
+an earlier step animates from the other side.
+
+## Examples
+    <KptStepper>
+      <KptStepper.Step label="Account"><StepNav /></KptStepper.Step>
+      <KptStepper.Step label="Profile">…</KptStepper.Step>
+    </KptStepper>
+
+    function StepNav() {
+      const { activeIndex, count, next, prev } = useKptStepper();
+      return (
+        <>
+          {activeIndex > 0 && <KptButton size="sm" variant="text" onClick={prev}>Back</KptButton>}
+          {activeIndex < count - 1 && <KptButton size="sm" onClick={next}>Next</KptButton>}
+        </>
+      );
+    }
+
+## Tokens
+The active and completed step: `--kpt-color-primary` (marker, connector); the rest
+`--kpt-color-border-strong` and `--kpt-color-on-surface-muted`.
+
+## Accessibility
+The header is an `<ol>` of real buttons — every step is reachable with the keyboard; the active
+marker carries `aria-current="step"`.

package/dist/switch/llms.txt

@@ -0,0 +1,42 @@
+# KptSwitch (@konce-pt/react)
+
+A switch / toggle. Underneath it is a native `<input type="checkbox" role="switch">`, so the
+keyboard and screen readers work with no extra handling.
+Import: `import { KptSwitch } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-switch-host">
+      <label class="kpt-switch">
+        <input type="checkbox" role="switch" class="kpt-switch__input">
+        <span class="kpt-switch__track" aria-hidden="true"><span class="kpt-switch__thumb"></span></span>
+        <span class="kpt-switch__label">Notifications</span>
+        <span class="kpt-switch__state kpt-switch__state--on">On</span>
+      </label>
+    </span>
+
+## Props
+- `label`: string, `labelPosition`: 'start' | 'end' (default 'end')
+- `onLabel`, `offLabel`: string — the state text, swapped on toggle
+- `checked` / `defaultChecked`, `onCheckedChange(checked)`, `onTouch()`
+- `required`, `invalid`, `touched` — as in `KptCheckbox`
+- `hostProps` — props for the `.kpt-switch-host` wrapper
+- `className` goes to the `.kpt-switch` block; the rest to the native `<input>`
+
+## The state text needs a controlled value
+`onLabel` and `offLabel` read `checked`, so they only follow the switch in controlled mode.
+Uncontrolled, the value belongs to the DOM and React never learns about a toggle, which would
+freeze the state text on its initial value — use `checked` with `onCheckedChange` whenever you
+show one.
+
+## Examples
+    <KptSwitch name="notifications" label="Notifications" />
+    <KptSwitch checked={on} onCheckedChange={setOn} onLabel="On" offLabel="Off" />
+    <KptSwitch checked={on} onCheckedChange={setOn} label="Dark mode" labelPosition="start" />
+
+## Tokens
+`--kpt-color-primary` (the on track), `--kpt-color-muted` (the off track), `--kpt-color-surface`
+(the thumb), `--kpt-motion-duration-fast`.
+
+## Accessibility
+`role="switch"` on a native checkbox — a screen reader announces on/off instead of
+checked/unchecked. The track and the thumb are `aria-hidden`.

package/dist/switch-group/llms.txt

@@ -0,0 +1,43 @@
+# KptSwitchGroup (@konce-pt/react)
+
+A group of switches — mutually exclusive by default, multi-select with `multiple`.
+Import: `import { KptSwitchGroup } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-switch-group-host">
+      <div class="kpt-switch-group" role="group">
+        <span class="kpt-switch-host kpt-switch-group__item">…KptSwitch…</span>
+        …one per option…
+      </div>
+    </div>
+
+## Props
+- `options`: `KptOption<T>[]` — `{ label, value, disabled? }`
+- `value` / `defaultValue` / `onValueChange` — single select: the option's value or `null`;
+  with `multiple`: an array of the selected values
+- `multiple`: boolean (default false)
+- `orientation`: `'vertical'` (default) | `'horizontal'`
+- `allowDeselect`: boolean (default true) — single select only; in `multiple` mode turning an
+  option off is always allowed
+- `disabled`, `invalid`, `touched`, `onTouch()`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Single select comes out of the value, not out of the switches
+Every entry is a `KptSwitch` whose `checked` is derived from the group value, so turning one on
+turns the rest off by itself — there is no per-switch state to keep in sync.
+
+That is also why `allowDeselect={false}` needs no code: the handler writes nothing, so React
+re-applies the controlled `checked` and the switch snaps back on.
+
+## Examples
+    <KptSwitchGroup value={mode} onValueChange={setMode} options={options} />
+    <KptSwitchGroup multiple value={channels} onValueChange={setChannels} options={options} />
+    <KptSwitchGroup orientation="horizontal" value={mode} onValueChange={setMode} options={options} />
+
+## Tokens
+Layout only: `--kpt-space-2` (vertical gap) and `--kpt-space-4` (horizontal). The look comes from
+`KptSwitch` and its tokens.
+
+## Accessibility
+`role="group"` with `aria-invalid` once the field is touched; every entry keeps the native
+checkbox of `KptSwitch`, so keyboard and screen readers work with no extra handling.

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

@@ -1,7 +1,7 @@
 import type { ComponentPropsWithRef } from 'react';
 import type { KptOption } from '../shared/types.ts';
 export interface KptSwitchGroupProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
-    options?: KptOption<T>[];
+    options?: readonly KptOption<T>[];
     /** Pojedynczy wybór: wartość opcji albo `null`. Tryb `multiple`: tablica wartości. */
     value?: T | T[] | null;
     defaultValue?: T | T[] | null;

package/dist/tabs/llms.txt

@@ -0,0 +1,48 @@
+# KptTabs (@konce-pt/react)
+
+Tabs — switching views, with the content rendered lazily.
+Import: `import { KptTabs } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-tabs-host" style="--kpt-anim-duration: 500ms; --kpt-anim-dir: 1">
+      <div class="kpt-tabs__header" role="tablist">
+        <button class="kpt-tabs__tab is-active" role="tab" aria-selected="true">General</button>
+        <button class="kpt-tabs__tab" role="tab" aria-selected="false">Advanced</button>
+        <span class="kpt-tabs__ink" style="width: 95px; transform: translateX(85px)"></span>
+      </div>
+      <div class="kpt-tabs__body" role="tabpanel">
+        <div class="kpt-tabs__panel">…active tab content…</div>
+      </div>
+    </div>
+
+## Props
+- `activeIndex` / `defaultActiveIndex` / `onActiveIndexChange` — controlled or uncontrolled
+- `animated`: boolean (default true), `animationDuration`: number (ms, default 500)
+- `children` — `<KptTabs.Tab>` elements
+
+## KptTabs.Tab
+`label` (required), `disabled`, `children`. The tab component never renders itself — `KptTabs`
+reads its props and decides what to show, exactly as the Angular version reads the `kpt-tab`
+template. Only the active tab's content is in the DOM.
+
+## The underline is measured, not computed
+`__ink` takes its width and offset from the active button in the DOM, not from the index: tabs have
+different widths and the labels change with the language. The measurement runs after every render,
+and the state is only replaced when the numbers actually change — otherwise each measurement would
+schedule another render and the component would loop.
+
+## Examples
+    <KptTabs>
+      <KptTabs.Tab label="General">…</KptTabs.Tab>
+      <KptTabs.Tab label="Advanced">…</KptTabs.Tab>
+    </KptTabs>
+
+    <KptTabs activeIndex={tab} onActiveIndexChange={setTab} animated={false}>…</KptTabs>
+
+## Tokens
+`--kpt-color-primary` (the active tab and the ink), `--kpt-color-on-surface-muted`,
+`--kpt-color-border`, `--kpt-motion-easing-standard`.
+
+## Accessibility
+The header is `role="tablist"` with `role="tab"` buttons carrying `aria-selected`; the body is
+`role="tabpanel"`. A disabled tab is a disabled button, so the keyboard skips it.

package/dist/textarea/llms.txt

@@ -0,0 +1,40 @@
+# KptTextarea (@konce-pt/react)
+
+A multi-line field, with optional auto-resize. It renders a native `<textarea>` inside a
+`.kpt-textarea-host` wrapper. Import: `import { KptTextarea } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-textarea-host">
+      <textarea class="kpt-textarea__field" rows="3"></textarea>
+    </span>
+
+## Props
+- `autoResize`: boolean — matches the height to the content on every change
+- `rows`: number (default 3) — the starting height
+- `value` / `defaultValue` — controlled or uncontrolled, like a native textarea
+- `onValueChange(value)`, `onTouch()` — the value alone, and the blur moment
+- `required`: boolean — set as `aria-required`, not as the native attribute
+- `invalid`, `touched` — the error state, gated the same way as in `KptInput`
+- `hostProps` — props for the wrapper
+- `className`, `ref`, `name`, `placeholder` and every other `<textarea>` prop go to the textarea
+
+## Auto-resize
+The height is read straight from the DOM (`scrollHeight`), so it is right for a controlled field, an
+uncontrolled one, and a prefilled initial value alike. The measurement resets the height to `auto`
+first — without that a field can only ever grow, since `scrollHeight` never drops below the current
+height.
+
+## Examples
+    <KptTextarea name="notes" placeholder="Notes…" autoResize />
+    <KptTextarea value={note} onValueChange={setNote} rows={6} />
+    <KptFormField label="Notes" error={err}>
+      <KptTextarea invalid={!!err} onTouch={markTouched} />
+    </KptFormField>
+
+## Tokens
+`--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}` —
+the same set as the text field, so both controls stay in step.
+
+## Accessibility
+A native `<textarea>`. Inside `KptFormField` it takes its `id` from the wrapper, so `label[for]`
+is wired with no configuration.

package/dist/timeline/llms.txt

@@ -0,0 +1,53 @@
+# KptTimeline (@konce-pt/react)
+
+A timeline — a vertical list of events with markers.
+Import: `import { KptTimeline } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-timeline-host">
+      <ol class="kpt-timeline">
+        <li class="kpt-timeline__item">
+          <div class="kpt-timeline__marker" data-variant="success">…icon…</div>
+          <div class="kpt-timeline__content">
+            <div class="kpt-timeline__header">
+              <span class="kpt-timeline__title">Order created</span>
+              <span class="kpt-timeline__time">10:02</span>
+            </div>
+            <p class="kpt-timeline__desc">…</p>
+          </div>
+        </li>
+      </ol>
+    </div>
+
+## Props
+- `items`: `KptTimelineItem[]`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+### KptTimelineItem
+- `title`: string (required)
+- `description?`, `time?`: string; `icon?`: an icon name from the registry
+- `variant?`: `'neutral' | 'primary' | 'success' | 'danger' | 'warning' | 'info'` (default `'primary'`)
+
+## The variant is an attribute, not a class
+The marker carries `data-variant`, and the SCSS maps it to `--_color` — the same contract as every
+other component in the library, so a new variant is a token, not a new class.
+
+## The connecting line is a pseudo-element
+`::before` on every item but the last, so the line is drawn between markers without an extra node
+and needs no knowledge of the list's length.
+
+## Examples
+    <KptTimeline items={events} />
+
+    const events: KptTimelineItem[] = [
+      { title: 'Order created', time: '10:02', variant: 'success', icon: 'check' },
+      { title: 'Shipped', time: '12:30', variant: 'info' },
+    ];
+
+## Tokens
+The marker follows the variant (`--kpt-color-{variant}`), the line `--kpt-color-border`, the
+description `--kpt-color-on-surface-muted`.
+
+## Accessibility
+An ordered list (`<ol>`), so the sequence of events is conveyed by the markup itself; markers are
+decorative and carry no text of their own.

package/dist/timeline/timeline.d.ts

@@ -8,7 +8,7 @@ export interface KptTimelineItem {
     variant?: 'neutral' | 'primary' | 'success' | 'danger' | 'warning' | 'info';
 }
 export interface KptTimelineProps extends ComponentPropsWithRef<'div'> {
-    items?: KptTimelineItem[];
+    items?: readonly KptTimelineItem[];
 }
 /**
  * Oś czasu — pionowa lista zdarzeń z markerami.

package/dist/toast/llms.txt

@@ -0,0 +1,52 @@
+# Toast (@konce-pt/react)
+
+Notifications. `kptToast` raises them, `<KptToastContainer />` renders them.
+Import: `import { kptToast, KptToastContainer } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-toast-container-host">
+      <div class="kpt-toast-container" aria-live="polite" aria-atomic="false">
+        <div class="kpt-toast" data-variant="success" role="status">
+          <span class="kpt-icon-host kpt-toast__icon">…</span>
+          <div class="kpt-toast__content">
+            <div class="kpt-toast__title">Saved</div>
+            <div class="kpt-toast__message">Your changes are stored.</div>
+          </div>
+          <button class="kpt-toast__close" type="button" aria-label="Close">…</button>
+        </div>
+      </div>
+    </div>
+
+## kptToast
+- `show(message, options?)` — returns the toast id
+- `info` / `success` / `warning` / `error` — the same, with the variant preset
+- `dismiss(id)`, `clear()`
+- options: `title`, `variant`, `duration` (ms, default 4000; `0` disables auto-dismiss)
+
+## A module singleton, not a provider
+The store lives in the module, which is the closest equivalent of Angular's
+`providedIn: 'root'`. `kptToast.error(...)` therefore works from anywhere — including outside the
+React tree, in a data-layer error handler or an HTTP interceptor — with no provider wrapping the
+application. `useKptToasts()` exposes the current list when you want to render them yourself.
+
+## Placement
+Render `<KptToastContainer />` once, near the root of the application. Toasts raised before it
+mounts are kept in the store and appear as soon as it does.
+
+## Examples
+    // once in the app
+    <KptToastContainer />
+
+    kptToast.success('Saved', { title: 'Saved' });
+    kptToast.error('Could not connect to the server.', { title: 'Error', duration: 0 });
+    const id = kptToast.info('Uploading…', { duration: 0 });
+    kptToast.dismiss(id);
+
+## Tokens
+The semantic colour pairs of each variant (`--kpt-color-info` / `-success` / `-warning` /
+`-danger` with their `-subtle` and `on-` counterparts), `--kpt-elevation-3`, `--kpt-z-overlay`.
+
+## Accessibility
+The container is `aria-live="polite"` with `aria-atomic="false"`, and each toast is
+`role="status"`, so a screen reader announces new ones without interrupting the current task.
+The close button gets its label from `common.close`.

package/dist/toolbar/llms.txt

@@ -0,0 +1,45 @@
+# KptToolbar (@konce-pt/react)
+
+The top bar — a horizontal strip for application content (logo, actions).
+Import: `import { KptToolbar, KptToolbarSpacer } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-toolbar kpt-toolbar--elevated">
+      …children…
+      <span kpttoolbarspacer=""></span>
+      …children…
+    </div>
+
+## Props
+- `elevated`: boolean — adds a shadow under the bar
+- `wrap`: boolean — lets the content wrap onto further rows when it runs out of room
+- `className`, `ref` and every other `<div>` prop go to the bar itself
+
+`wrap` is opt-in because wrapping changes what `<KptToolbarSpacer>` does: in a single-row bar it
+pushes content apart, in a wrapping one it can shove the rest onto a new row.
+
+## KptToolbarSpacer
+A flexible gap that pushes the bar's content apart. It carries the `kpttoolbarspacer` attribute the
+shared SCSS targets (attribute names in CSS selectors are case-insensitive in HTML, so one rule
+serves both ports).
+
+## Examples
+    <KptToolbar elevated>
+      <strong>Koncept UI</strong>
+      <KptToolbarSpacer />
+      <KptButton variant="text">Sign out</KptButton>
+    </KptToolbar>
+
+    <KptAppShell toolbar={<KptToolbar elevated>…</KptToolbar>} sidenav={…}>…</KptAppShell>
+
+## Responsiveness
+Below the `sm` breakpoint the bar shrinks on its own — a lower height
+(`--kpt-toolbar-height-compact`), narrower inline padding and a smaller gap. No props involved.
+
+## Tokens
+`--kpt-toolbar-height` (3.5rem), `--kpt-toolbar-height-compact` (3rem), `--kpt-toolbar-bg`,
+`--kpt-toolbar-fg`, `--kpt-toolbar-border`, `--kpt-elevation-1` for the elevated variant.
+
+## Accessibility
+A plain container with no role of its own. Give it `role="banner"` or wrap it in a `<header>`
+when it is the page's main bar.

package/dist/tooltip/llms.txt

@@ -0,0 +1,42 @@
+# KptTooltip (@konce-pt/react)
+
+A tooltip shown on hover and focus. Light — the element is appended to `body` and positioned
+against the child. Import: `import { KptTooltip } from '@konce-pt/react';`
+
+## DOM
+The component renders NO wrapper of its own — it clones the child and attaches the handlers and a
+ref to it, so the tree stays exactly as it would be without the tooltip. This is the port of the
+`[kptTooltip]` directive, which likewise added nothing to the DOM.
+
+    <!-- while visible, appended to body: -->
+    <div class="kpt-tooltip" role="tooltip" style="position: fixed; …">Save changes</div>
+
+## Props
+- `text`: string — the bubble content; empty text disables the tooltip
+- `position`: 'top' | 'bottom' | 'left' | 'right' (default 'top')
+- `onlyWhenTruncated`: boolean — show it only when the content does not fit
+- `children` — exactly one element, the one that gets hover and focus
+
+## onlyWhenTruncated
+The check runs at hover time, not at render, so the result is always current after a width or zoom
+change, with no observers. It measures the host AND its direct children, because
+`text-overflow: ellipsis` usually sits on an inner element — and such an element shrinks to the
+available width instead of stretching its parent, so measuring the host alone would find nothing.
+
+## Styling
+The bubble carries inline styles built from tokens rather than a class from the shared stylesheet,
+exactly like the Angular directive — it is created outside React's tree, so there is nothing to
+attach a stylesheet rule to reliably.
+
+## Examples
+    <KptTooltip text="Save changes" position="bottom"><KptButton>Save</KptButton></KptTooltip>
+    <KptTooltip text={name} onlyWhenTruncated><span className="ellipsis">{name}</span></KptTooltip>
+
+## Tokens
+`--kpt-color-on-surface` (the background), `--kpt-color-surface` (the text), `--kpt-radius-sm`,
+`--kpt-font-size-xs`, `--kpt-elevation-2`.
+
+## Accessibility
+The bubble is `role="tooltip"` and appears on focus as well as hover, so it is reachable from the
+keyboard. It is `pointer-events: none`, so it never steals a click. It does NOT replace an
+accessible name — for an icon-only button give the button its own `aria-label`.

package/dist/tree/llms.txt

@@ -0,0 +1,45 @@
+# KptTree (@konce-pt/react)
+
+A hierarchical tree: expanding, selection, icons.
+Import: `import { KptTree, type KptTreeNode } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-tree-host">
+      <ul class="kpt-tree" role="tree">
+        <li class="kpt-tree__node" role="treeitem" aria-expanded="true">
+          <div class="kpt-tree__row is-selected">
+            <button class="kpt-tree__toggle">…chevron…</button>
+            <span class="kpt-tree__icon">…</span>
+            <span class="kpt-tree__label">src</span>
+          </div>
+          <ul role="group">…</ul>
+        </li>
+      </ul>
+    </div>
+
+## Props
+- `nodes`: `KptTreeNode<T>[]` — `{ label, value?, icon?, children?, expanded?, disabled? }`
+- `selectable`: boolean — a row click selects instead of expanding
+- `selected` / `defaultSelected` / `onSelectedChange` — the node object, or `null`
+- `onNodeClick(node)`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Expansion is component state, not data
+The Angular port flips `node.expanded` in place and bumps a version signal. In React that would be
+a side effect on someone else's array during render, so the open branches live in a `Set` of node
+references instead — and `expanded` in the data goes back to being what it should be: the initial
+state, read once on mount.
+
+## Examples
+    <KptTree nodes={tree} />
+    <KptTree nodes={tree} selectable selected={node} onSelectedChange={setNode} />
+
+## i18n
+The toggle is labelled from `tree.expand` / `tree.collapse`.
+
+## Tokens
+The selected row `--kpt-color-primary`, the hover `--kpt-color-surface-variant`.
+
+## Accessibility
+`role="tree"` / `role="treeitem"` with `aria-expanded` on branches only; the indentation is
+`padding-inline-start`, so it follows the writing direction.

package/dist/tree/tree.d.ts

@@ -4,13 +4,13 @@ export interface KptTreeNode<T = unknown> {
     label: string;
     value?: T;
     icon?: string;
-    children?: KptTreeNode<T>[];
+    children?: readonly KptTreeNode<T>[];
     /** Stan początkowy gałęzi; dalej rozwijaniem steruje już komponent. */
     expanded?: boolean;
     disabled?: boolean;
 }
 export interface KptTreeProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onSelect' | 'children'>, KptI18nOverrides {
-    nodes?: KptTreeNode<T>[];
+    nodes?: readonly KptTreeNode<T>[];
     /** Klik w wiersz zaznacza gałąź zamiast ją rozwijać. */
     selectable?: boolean;
     selected?: KptTreeNode<T> | null;