@konce-pt/react 0.8.1 → 0.8.3

package/dist/public-api.d.ts

@@ -1,4 +1,4 @@
-export { KptAppShell, useKptAppShell, useKptShellNavToggle } from './app-shell/app-shell.tsx';
+export { KptAppShell, KptNavLabel, KptNavSection, useKptAppShell, useKptShellNavToggle } from './app-shell/app-shell.tsx';
 export type { KptAppShellContextValue, KptAppShellProps, KptSidenavMode } from './app-shell/app-shell.tsx';
 export { KptToolbar, KptToolbarSpacer } from './toolbar/toolbar.tsx';
 export type { KptToolbarProps } from './toolbar/toolbar.tsx';
@@ -31,6 +31,7 @@ export type { KptSkeletonProps, KptSkeletonVariant } from './skeleton/skeleton.t
 export { KptIcon } from './icon/icon.tsx';
 export type { KptIconProps } from './icon/icon.tsx';
 export { getKptIcon, hasKptIcon, registerKptIcons } from './icon/icon-registry.ts';
+export type { KptIconDef, KptIconInput } from '@konce-pt/icons';
 export { KptAvatar } from './avatar/avatar.tsx';
 export type { KptAvatarProps, KptAvatarShape, KptAvatarSize } from './avatar/avatar.tsx';
 export { KptBadge } from './badge/badge.tsx';

package/dist/public-api.js

@@ -6,7 +6,7 @@
  * jest wspólna i nie ma tu własnych stylów.
  */
 // Komponenty — układ
-export { KptAppShell, useKptAppShell, useKptShellNavToggle } from "./app-shell/app-shell.js";
+export { KptAppShell, KptNavLabel, KptNavSection, useKptAppShell, useKptShellNavToggle } from "./app-shell/app-shell.js";
 export { KptToolbar, KptToolbarSpacer } from "./toolbar/toolbar.js";
 export { KptSidenav, KptSidenavFooter } from "./sidenav/sidenav.js";
 // Komponenty — panele

package/dist/radio-group/llms.txt

@@ -0,0 +1,40 @@
+# KptRadioGroup (@konce-pt/react)
+
+A group of radio buttons, driven by `options`.
+Import: `import { KptRadioGroup } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-radio-group-host">
+      <div class="kpt-radio-group" role="radiogroup">
+        <label class="kpt-radio">
+          <input type="radio" class="kpt-radio__input" name="kpt-radio-r1" checked>
+          <span class="kpt-radio__dot" aria-hidden="true"></span>
+          <span class="kpt-radio__label">Pro</span>
+        </label>
+      </div>
+    </div>
+
+## Props
+- `options`: `KptOption<T>[]` — `{ label, value, disabled? }`
+- `value` / `defaultValue` / `onValueChange` — controlled or uncontrolled
+- `name`: string — the form group name; omitted means one is generated
+- `disabled`, `invalid`, `touched`, `onTouch()`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The shared name does the work
+All inputs share one `name`, and that — not any code in the component — is what makes the browser
+treat them as one group: arrow keys move between them, only one can be checked, and a native form
+submits a single value. The generated name is unique per instance, so two groups on one page never
+interfere.
+
+## Examples
+    <KptRadioGroup options={plans} value={plan} onValueChange={setPlan} />
+    <KptRadioGroup name="plan" options={plans} defaultValue="pro" />
+
+## Tokens
+`--kpt-color-primary` (the checked dot), `--kpt-form-field-border`,
+`--kpt-form-field-border-error`.
+
+## Accessibility
+The container is `role="radiogroup"` with `aria-invalid` when the error shows; every option is a
+native radio inside a `<label>`, so the label text is clickable and is the accessible name.

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

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

package/dist/rating/llms.txt

@@ -0,0 +1,43 @@
+# KptRating (@konce-pt/react)
+
+A star rating.
+Import: `import { KptRating } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-rating-host">
+      <div class="kpt-rating" role="slider" aria-valuenow="3" aria-valuemax="5">
+        <button class="kpt-rating__star is-filled" aria-label="1 of 5">…</button>
+        …count buttons…
+      </div>
+    </div>
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — the score as a number, `0` means unrated
+- `count`: number (default 5)
+- `readOnly`: boolean — display only, no clicking and no hover preview
+- `disabled`: boolean
+- `onTouch()` — fired together with a pick
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Clicking a lit star clears the score
+Picking the star that already holds the value writes `0`, so a rating can be taken back without a
+separate "clear" button — the same contract as the Angular port.
+
+## Hover beats the value, but only while the pointer is there
+The lit count comes from `hover || value`, so the row previews the score under the cursor and
+falls back to the real value on `mouseleave`. `readOnly` and `disabled` freeze both.
+
+## i18n
+Each star is labelled from `rating.star` (`{value}`, `{max}`) — EN `1 of 5`, PL `1 z 5`. Override
+per instance with the `locale` / `dictionary` props.
+
+## Examples
+    <KptRating value={score} onValueChange={setScore} count={5} />
+    <KptRating value={4} readOnly />
+
+## Tokens
+Lit stars `--kpt-color-warning`, empty ones `--kpt-color-border-strong`.
+
+## Accessibility
+`role="slider"` with `aria-valuenow` / `aria-valuemax`; every star is a real `<button>`, so the
+row is reachable with Tab and each value can be picked from the keyboard.

package/dist/rich-text/llms.txt

@@ -0,0 +1,61 @@
+# KptRichText (@konce-pt/react)
+
+A lightweight rich text editor (contenteditable) with a configurable, sectioned toolbar and table
+editing. The value is HTML.
+Import: `import { KptRichText, type KptRichTool } from '@konce-pt/react';`
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — the HTML
+- `toolbar`: `KptRichTool[] | KptRichTool[][]` — a flat list, or groups = sections separated by a
+  divider. Leaving a tool or a group out disables it; the full toolbar in 5 sections by default.
+- `placeholder`, `maxListLevel` (6), `disabled`, `invalid`, `touched`, `onTouch()`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Tools (KptRichTool)
+Clipboard: `copy`, `paste` (sanitized), `pasteText`. Style: `heading` (a panel: Normal + H1–H6).
+Format: `bold`, `italic`, `underline`, `strike`, `ul`, `ol`, `indent`, `outdent`.
+Colours: `foreColor`, `backColor` (a palette + a native colour input). Alignment: `alignLeft`,
+`alignCenter`, `alignRight`, `alignJustify`. Plus `link`, `table`, `clear`, `html`.
+
+## The editor is not rendered by React
+`contentEditable` cannot be a React-rendered subtree: re-rendering would wipe the selection and the
+caret on every keystroke. The value is written into the DOM by hand, only when it differs from what
+is already there — so typing never triggers a rewrite, and sanitization runs solely on writes
+coming from the application or the HTML source view.
+
+## Everything that enters the DOM is sanitized
+Not just paste: a `value` from a database, a CMS or another user is untrusted too. Tags outside the
+allowlist are unwrapped (the text survives), `on*` handlers and `javascript:` URLs are dropped,
+`style` is filtered declaration by declaration. `sanitize.ts` knows nothing about React.
+
+## Lists are indented by our own DOM code
+`execCommand('indent')` produces invalid `ul > ul` in Chrome, so nesting goes through `lists.ts`
+(`li > ul > li`, a sublist inherits the parent's type). Tab and Shift+Tab indent and outdent, but
+only when the operation actually changed something — otherwise Tab stays native and the editor
+never becomes a keyboard trap (WCAG 2.1.2). In a table cell Tab moves to the next cell; a list
+inside the cell takes precedence.
+
+## Tables
+Insert from an 8×8 grid popover. Dragging across cells makes a rectangular selection that grows
+until it fully covers merged cells on its edges. Right-click opens the menu: insert and delete rows
+and columns, header row and column (td↔th), cell background, alignment, borders, merge and split,
+delete the table. Dragging a column's right edge changes its width. `tables.ts` holds the grid
+math — also framework-free.
+
+## Point-anchored panels
+The table menu and its popovers have no trigger element, so they do not go through `KptOverlay`:
+they are portalled at the cursor coordinates and clamped to the viewport, because CDK's automatic
+repositioning is not there to do it.
+
+## Examples
+    <KptRichText value={body} onValueChange={setBody} />
+    <KptRichText value={body} onValueChange={setBody} toolbar={[['bold', 'italic'], ['ul', 'ol'], ['link']]} />
+
+## i18n
+Every label comes from the `richText` namespace, including `richText.menu.*` and
+`richText.border.*`.
+
+## Note
+Formatting goes through `document.execCommand`. The API is formally deprecated, but it is the only
+route into the browser's native undo stack (Ctrl+Z); replacing it would mean writing our own
+history, that is, a different editor.

package/dist/rich-text/rich-text.d.ts

@@ -2,7 +2,7 @@ import { type ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export type KptRichTool = 'copy' | 'paste' | 'pasteText' | 'heading' | 'bold' | 'italic' | 'underline' | 'strike' | 'ul' | 'ol' | 'indent' | 'outdent' | 'foreColor' | 'backColor' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'alignJustify' | 'link' | 'table' | 'clear' | 'html';
 /** Pasek: płaska lista narzędzi albo grupy — sekcje rozdzielone separatorem. */
-export type KptRichToolbar = KptRichTool[] | KptRichTool[][];
+export type KptRichToolbar = readonly KptRichTool[] | readonly (readonly KptRichTool[])[];
 export interface KptRichTextProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'children'>, KptI18nOverrides {
     /** Wartość jako HTML. */
     value?: string;

package/dist/roadmap/llms.txt

@@ -0,0 +1,82 @@
+# KptRoadmap (@konce-pt/react/roadmap)
+
+Rows of tasks on a horizontal timeline (a Gantt-style view). The label column and the axis header
+stay stuck while scrolling, the bars are positioned as percentages, and dependencies are drawn by
+an SVG layer.
+Import: `import { KptRoadmap, type KptRoadmapConfig } from '@konce-pt/react/roadmap';`
+
+A separate subpath, because the geometry, the styles and the data model are heavy next to the
+library core and not every app needs them.
+
+## Props
+- `config`: `KptRoadmapConfig` (required) — the data and every option
+- `scrollHeight`: string | null — a fixed height, e.g. '420px'; enables the sticky header
+- `labelWidth`: string — the width of the label column (default '14rem')
+- `cellWidthPx`: number | null — the width of an axis column; without it the value depends on the zoom
+- `showToday`: boolean — the "today" marker (default true)
+- `virtual`: boolean — renders only the visible rows; worth it from roughly 100 rows up
+- `collapsedGroups` / `defaultCollapsedGroups` / `onCollapsedGroupsChange` — the ids of collapsed
+  groups, controlled or uncontrolled
+- `onItemClick(item)`, `onRangeChange(range)` — the click on a bar and the computed axis range
+- `className`, `ref` and every other `<div>` prop go to the host
+- `locale`, `dictionary` — the per-component i18n overrides
+
+## The config is the API
+`{ items, groups?, links?, zoom?, range?, locale?, today?, timeline?, rows?, dependencies?,
+interaction? }` — the same shape the Angular port takes, because both read it from
+`@konce-pt/roadmap`. An item is `{ id, label, start, end?, sublabel?, variant?, color?, progress?,
+groupId?, dependsOn?, milestone?, meta? }`; no `end` means a milestone diamond, and a bare string in
+`dependsOn` is an 'FS' dependency.
+
+## The geometry lives in a package
+The calendar arithmetic, the timeline bands and cells, the row layout, lane packing and the
+dependency polylines come from `@konce-pt/roadmap` — pure functions with `node --test` coverage,
+shared with the Angular port. The component only turns them into DOM and SVG.
+
+## Collapsing has two sources
+`group.collapsed` in the data and the `collapsedGroups` prop are kept apart, so an app that controls
+the state keeps control while a group collapsed declaratively still works. Expanding removes the
+group from both — otherwise `group.collapsed` would immediately collapse it again. The declarative
+set is recomputed during render whenever the `groups` array identity changes; an effect would do it
+one render too late, that is after the group flashed open.
+
+## Measuring, not guessing
+The SVG dependency layer works in pixels, so the lane width and the scroll viewport are measured
+with a `ResizeObserver` in a layout effect. Before the first measurement no link is drawn — half a
+frame without arrows beats arrows in the wrong place.
+
+## Examples
+    <KptRoadmap config={{ zoom: 'week', items }} scrollHeight="420px" />
+
+    const [collapsed, setCollapsed] = useState<string[]>(['analytics']);
+
+    <KptRoadmap
+      config={roadmap}
+      collapsedGroups={collapsed}
+      onCollapsedGroupsChange={setCollapsed}
+      onItemClick={(item) => open(item.id)}
+    />
+
+## Behavior
+- The axis is computed in local time; week numbering follows ISO 8601.
+- The 'uniform' position mode gives columns of equal width despite DST changes and months of
+  different lengths; inside a column the position is interpolated linearly.
+- An item extending past the axis range is cut off on the side where it is clipped.
+- Tooltips use `KptTooltip`, mostly with `onlyWhenTruncated`: a tooltip shows what cannot be seen.
+  Milestones and header cells carry one unconditionally — a diamond shows no text at all.
+- Dependencies: 'FS' (the default), 'SS', 'FF', 'SF'; violated ones are drawn as a dashed line in
+  the danger color.
+- Entries with an invalid date or a duplicate `id` are skipped, with a warning in a development build.
+
+## i18n
+The `roadmap.*` keys: `empty`, `week`, `today`, `milestone`, `expandGroup`, `collapseGroup`.
+Month and weekday names come from `Intl` per `config.locale` or the locale from `KptI18nProvider`.
+
+## Tokens
+Surfaces `--kpt-color-surface{,-variant,-sunken,-hover}`, outlines `--kpt-color-border{,-strong}`,
+bars per variant `--kpt-color-{primary,success,danger,warning,info,muted}`.
+Sizes: `--kpt-roadmap-label-w`, `--kpt-roadmap-cell-w` (both can be overridden from outside).
+
+## Accessibility
+Group toggles are real buttons with `aria-expanded`; bars and milestones are focusable and answer
+Enter and Space like a click. The background grid and the dependency layer are `aria-hidden`.

package/dist/scroll-top/llms.txt

@@ -0,0 +1,41 @@
+# KptScrollTop (@konce-pt/react)
+
+A "back to top" button — appears once the scroll passes `threshold` px.
+Import: `import { KptScrollTop } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-scroll-top-host">
+      <button class="kpt-scroll-top is-visible" tabindex="0" aria-label="Scroll to top">…</button>
+    </div>
+
+## Props
+- `threshold`: number (px, default 300)
+- `target`: string | null — a selector for the scrolled element; the window by default
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## `target` is not optional in a shell
+Whenever the app scrolls a container rather than the page — an `KptAppShell` layout, for instance —
+the window never scrolls and the button would never appear. Point it at the container:
+`target=".kpt-app-shell__content"`.
+
+## The element is found in an effect
+The scrolled container is queried after mount, not during render: it is often mounted after this
+component, and on the server it does not exist at all. The listener is removed on cleanup, and the
+position is read once on mount, because the page may already be scrolled (arriving at an anchor).
+
+## The hidden button stays in the DOM
+It fades in and out, so hiding it is `tabindex="-1"` plus the CSS class, not a conditional render —
+otherwise the animation would have nothing to run on.
+
+## Examples
+    <KptScrollTop threshold={300} />
+    <KptScrollTop target="#panel" />
+
+## i18n
+The label comes from `scrollTop.label`.
+
+## Tokens
+`--kpt-color-primary` / `--kpt-color-on-primary`, `--kpt-elevation-3`.
+
+## Accessibility
+A real `<button>` with a label from the dictionary; while hidden it is out of the tab order.

package/dist/select/llms.txt

@@ -0,0 +1,56 @@
+# KptSelect (@konce-pt/react)
+
+A select on its own panel. Variants: single, with a search box (`filter`) and multiple
+(`multiple`, chips). Import: `import { KptSelect } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-select-host">
+      <div class="kpt-select" role="combobox" tabindex="0" aria-expanded="false">
+        <div class="kpt-select__value"><span class="kpt-select__placeholder">Choose…</span></div>
+        <span class="kpt-icon-host kpt-select__chevron">…</span>
+      </div>
+    </span>
+    <!-- while open, in a portal on document.body: -->
+    <div class="kpt-select__panel"><ul class="kpt-select__list" role="listbox">…</ul></div>
+
+## Props
+- `options`: `KptOption<T>[]` — `{ label, value, disabled? }`
+- `value` / `defaultValue` / `onValueChange` — a single `T`, or `T[]` in `multiple` mode
+- `open` / `defaultOpen` / `onOpenChange` — the panel state, so the list can be opened from outside
+- `placeholder`, `multiple`, `filter`, `disabled`, `invalid`, `touched`
+- `onTouch()` — fires when the panel closes or the trigger loses focus
+- `locale`, `dictionary` — i18n overrides for this component only
+- `className`, `ref` and every other `<div>` prop go to the trigger
+
+## The panel is a portal
+The Angular port stands on CDK Overlay, which React has no equivalent of. The panel renders into a
+portal on `document.body` with the same behaviour: the trigger's width, a position below it that
+flips above when there is no room, a transparent backdrop that closes on click, and Escape. It
+follows scrolling and resizing, so the panel never drifts away from its trigger.
+
+## Keyboard
+On the trigger: ArrowDown, Enter or Space open the list; Escape closes it. In the panel: ArrowUp and
+ArrowDown move the active option, Enter picks it, Escape closes. Hovering an option makes it active,
+so the mouse and the keyboard share one highlight.
+
+## Inside KptFormField
+There is no native field for the wrapper to read, so the select reports its filled state with
+`useKptFormFieldFilled` — the float label then floats over the chosen value.
+
+## i18n
+`select.search` (the search placeholder), `select.noResults` (the empty list),
+`select.removeChip` (the chip's remove button).
+
+## Examples
+    <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Choose…" />
+    <KptSelect options={roles} value={role} onValueChange={setRole} filter />
+    <KptSelect options={tags} value={tags} onValueChange={setTags} multiple filter />
+
+## Tokens
+`--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}`,
+`--kpt-color-surface-raised` and `--kpt-elevation-3` for the panel, `--kpt-z-overlay` for the layer.
+
+## Accessibility
+The trigger is `role="combobox"` with `aria-expanded` and `tabindex="0"`; the list is
+`role="listbox"` with `aria-multiselectable`, and each option is `role="option"` with
+`aria-selected`.

package/dist/select/select.d.ts

@@ -2,7 +2,7 @@ import { type ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptOption } from '../shared/types.ts';
 export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'children' | 'onChange' | 'defaultValue'>, KptI18nOverrides {
-    options?: KptOption<T>[];
+    options?: readonly KptOption<T>[];
     placeholder?: string;
     /** Wybór wielokrotny — wartością jest tablica, a wybrane opcje pokazują się jako chipy. */
     multiple?: boolean;

package/dist/sidenav/llms.txt

@@ -0,0 +1,53 @@
+# KptSidenav (@konce-pt/react)
+
+The side panel — a styled navigation container, usually handed to the `sidenav` slot of
+`<KptAppShell>`. Import: `import { KptSidenav } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-sidenav">
+      <div class="kpt-sidenav__scroll">…children…</div>
+      <div kptsidenavfooter="">…footer…</div>
+    </div>
+
+## Props
+- `className`, `ref` and every other `<div>` prop go to the panel root
+
+## Sub-components
+- `KptSidenav.Footer` — lifted OUT of the scrolling area, so it stays pinned to the bottom of the
+  panel however long the navigation gets (a user block, an app version, a theme switch). It carries
+  the `kptsidenavfooter` attribute the shared SCSS targets.
+
+Default children land in the scrolling area. Plain `<a>` elements inside it are styled by the
+stylesheet already — padding, radius, a hover background — so a simple link list needs no classes.
+
+## Examples
+    <KptSidenav>
+      <a href="/">Dashboard</a>
+      <a href="/settings">Settings</a>
+      <KptSidenav.Footer>v0.7.12</KptSidenav.Footer>
+    </KptSidenav>
+
+    <KptAppShell sidenav={<KptSidenav>…</KptSidenav>} toolbar={…}>…</KptAppShell>
+
+## Rail mode
+When `<KptAppShell sidenavRailBreakpoint>` is on, a closed panel narrows instead of hiding. Mark the
+labels inside your menu items with `<KptNavLabel>` (and group headings with `<KptNavSection>`) and
+the shell will clip them the accessible way (visually hidden, still in the accessibility tree).
+
+    import { KptNavLabel, KptNavSection } from '@konce-pt/react';
+
+    <KptNavSection>Reports</KptNavSection>
+    <a href="/dashboard"><KptIcon name="layout-dashboard" /> <KptNavLabel>Dashboard</KptNavLabel></a>
+
+Both render the lowercase attribute the shared SCSS targets (`kptnavlabel` / `kptnavsection`);
+attribute names in CSS selectors are case-insensitive in HTML, so one rule serves both ports. Use
+the components rather than writing the attribute by hand — JSX rejects an unknown camelCase
+attribute, and a hand-written one is easy to misspell.
+
+## Tokens
+`--kpt-sidenav-bg`, `--kpt-sidenav-fg`, `--kpt-sidenav-border`, plus `--kpt-sidenav-width` and
+`--kpt-sidenav-rail-width`, which are read by `KptAppShell`.
+
+## Accessibility
+The panel itself is a plain container — the `role="navigation"` and the label live on the shell's
+`<aside>` around it, so a sidenav used outside `KptAppShell` needs its own landmark.

package/dist/skeleton/llms.txt

@@ -0,0 +1,33 @@
+# KptSkeleton (@konce-pt/react)
+
+A loading placeholder with a shimmer animation.
+Import: `import { KptSkeleton } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-skeleton-host" aria-hidden="true">
+      <span class="kpt-skeleton kpt-skeleton--text" style="width: 100%"></span>
+      <span class="kpt-skeleton kpt-skeleton--text" style="width: 60%"></span>
+    </span>
+
+## Props
+- `variant`: 'text' | 'circle' | 'rect' (default 'rect')
+- `width`: string (default '100%'), `height`: string (default '1rem')
+- `lines`: number (default 3) — the number of lines in the `text` variant
+- `className`, `ref` and every other `<span>` prop go to the host
+
+## The last line is shorter
+In the `text` variant the last line is 60% wide. A stack of full-width rectangles does not read as
+a paragraph, and a paragraph is exactly what it stands in for.
+
+## Examples
+    <KptSkeleton variant="text" lines={3} />
+    <KptSkeleton variant="circle" width="3rem" height="3rem" />
+    <KptSkeleton variant="rect" width="100%" height="8rem" />
+
+## Tokens
+`--kpt-color-muted` and `--kpt-color-surface` for the shimmer gradient, `--kpt-radius-md`.
+
+## Accessibility
+The host is `aria-hidden="true"` — a placeholder has nothing to announce, and reading out empty
+boxes only adds noise. Announce the wait with `KptSpinner` or `KptProgress` next to it when it
+matters.

package/dist/slider/llms.txt

@@ -0,0 +1,50 @@
+# KptSlider (@konce-pt/react)
+
+A value slider. In `range` mode it exposes two handles and the value becomes a `[min, max]` pair.
+Import: `import { KptSlider } from '@konce-pt/react';`
+
+## DOM
+    <!-- single -->
+    <div class="kpt-slider-host">
+      <input class="kpt-slider__input" type="range" style="--_pct: 40%">
+      <span class="kpt-slider__value">40</span>
+    </div>
+
+    <!-- range -->
+    <div class="kpt-slider-host">
+      <div class="kpt-slider__range">
+        <div class="kpt-slider__rail"></div>
+        <div class="kpt-slider__fill" style="left: 20%; right: 20%"></div>
+        <input class="kpt-slider__thumb kpt-slider__thumb--low" type="range" aria-label="Minimum">
+        <input class="kpt-slider__thumb kpt-slider__thumb--high" type="range" aria-label="Maksimum">
+      </div>
+      <span class="kpt-slider__value">20–80</span>
+    </div>
+
+## Props
+- `value` / `defaultValue` / `onValueChange` — `number`, or `[number, number]` in `range` mode
+- `range`: boolean — two handles
+- `min` (default 0), `max` (default 100), `step` (default 1)
+- `showValue`: boolean — prints the current value next to the slider
+- `disabled`, `onTouch()`
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## Native inputs all the way down
+Both handles are native `<input type="range">` stacked on each other, so the keyboard, touch
+gestures and screen readers work with no handling of our own — there is no custom drag logic to get
+wrong. The rail and the fill are decoration underneath them.
+
+## The handles cannot cross
+Moving the low handle above the high one clamps it to the high value, and the other way round. The
+pair therefore always stays ordered, so the fill never inverts.
+
+## Examples
+    <KptSlider value={volume} onValueChange={(v) => setVolume(v as number)} showValue />
+    <KptSlider range value={span} onValueChange={(v) => setSpan(v as [number, number])} showValue />
+
+## Tokens
+`--kpt-color-primary` (the fill and the handles), `--kpt-color-muted` (the rail).
+
+## Accessibility
+Native range inputs carry their own role and value semantics. In `range` mode each handle gets an
+`aria-label` telling the two apart, because "slider" twice would say nothing.

package/dist/speed-dial/llms.txt

@@ -0,0 +1,46 @@
+# KptSpeedDial (@konce-pt/react)
+
+A speed dial — a FAB that fans out a set of actions. Built on `KptFab`.
+Import: `import { KptSpeedDial } from '@konce-pt/react';`
+
+## DOM
+    <div class="kpt-speed-dial-host">
+      <div class="kpt-speed-dial is-open" data-direction="up">
+        <div class="kpt-speed-dial__actions">
+          <button class="kpt-speed-dial__action" aria-label="Upload file">…</button>…
+        </div>
+        <span class="kpt-fab-host"><button class="kpt-fab">…</button></span>
+      </div>
+      <div class="kpt-speed-dial__backdrop"></div>
+    </div>
+
+## Props
+- `items`: `KptMenuItem<T>[]` — the actions (`label`, `icon`, `disabled`)
+- `direction`: `'up'` (default) | `'down'` | `'left'` | `'right'`
+- `icon`: string (default `'plus'`) — the SCSS rotates it 45° when open
+- `ariaLabel`: string — the closed-state label; without it `speedDial.actions`
+- `onSelect(item)` — fired on pick; a disabled item fires nothing
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The label follows the state
+Closed, the FAB is named "actions"; open, it is `common.close`, because that is what pressing it
+does then. One button, two meanings, and a screen reader hears the current one.
+
+## The backdrop exists only while open
+It is rendered conditionally, not hidden with CSS: a transparent, full-screen layer that is always
+present would swallow clicks meant for the page underneath.
+
+## Examples
+    <KptSpeedDial items={actions} onSelect={onAction} />
+    <KptSpeedDial items={actions} direction="left" icon="dots" ariaLabel="More" />
+
+## i18n
+`speedDial.actions` and `common.close`; `locale` and `dictionary` override them per instance.
+
+## Tokens
+The main button comes from `KptFab`; the actions use `--kpt-color-surface-raised` and
+`--kpt-elevation-2`.
+
+## Accessibility
+Every action is a `<button>` labelled with its own `label`, so the fan works from the keyboard even
+when the actions show icons only.

package/dist/speed-dial/speed-dial.d.ts

@@ -3,7 +3,7 @@ import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptMenuItem } from '../menu/menu-item.ts';
 export type KptSpeedDialDirection = 'up' | 'down' | 'left' | 'right';
 export interface KptSpeedDialProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onSelect'>, KptI18nOverrides {
-    items?: KptMenuItem<T>[];
+    items?: readonly KptMenuItem<T>[];
     direction?: KptSpeedDialDirection;
     /** Ikona głównego przycisku; SCSS obraca ją o 45° po otwarciu. */
     icon?: string;

package/dist/spinner/llms.txt

@@ -0,0 +1,33 @@
+# KptSpinner (@konce-pt/react)
+
+A loading indicator. Import: `import { KptSpinner } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-spinner-host">
+      <span class="kpt-spinner" role="status" aria-label="Loading" style="width: 1.75rem; height: 1.75rem"></span>
+    </span>
+
+## Props
+- `size`: string (default '1.5rem') — a CSS length, applied to width and height
+- `label`: string — the accessibility label; omitted falls back to `spinner.label`
+- `locale`, `dictionary` — i18n overrides for this component only
+- `className`, `ref` and every other `<span>` prop go to the host
+
+## The colour is inherited
+The spinner draws itself in `currentColor`, so it takes the colour of the text around it. Put it
+inside a button and it matches the button; put it on a card and it matches the card. There is no
+colour prop, on purpose.
+
+## Examples
+    <KptSpinner />
+    <KptSpinner size="2rem" label="Loading data" />
+    <KptButton disabled><KptSpinner size="1em" /> Saving…</KptButton>
+
+## Tokens
+None of its own — the size comes from the prop, the colour from `currentColor`, the speed from
+`--kpt-motion-duration-*`.
+
+## Accessibility
+`role="status"` with a label, so a screen reader announces the wait politely. For a longer
+operation prefer `KptProgress` — a spinner says "something is happening", a progress bar says how
+much is left.