@konce-pt/react 0.11.2 → 0.14.0

package/dist/skeleton/skeleton.d.ts

@@ -10,7 +10,7 @@ export interface KptSkeletonProps extends Omit<ComponentPropsWithRef<'span'>, 'c
 /**
  * Placeholder ładowania z animacją shimmer.
  *
- * Wariant `text` skraca ostatnią linię do 60% — pełny prostokąt nie wygląda jak akapit, a to
+ * Wariant `text` skraca ostatnią linię do 60% - pełny prostokąt nie wygląda jak akapit, a to
  * właśnie akapit ma udawać. Przy jednej linii nie ma czego udawać, więc ta ma pełną szerokość.
  *
  * @example

package/dist/skeleton/skeleton.js

@@ -3,7 +3,7 @@ import { cn } from "../internal/cn.js";
 /**
  * Placeholder ładowania z animacją shimmer.
  *
- * Wariant `text` skraca ostatnią linię do 60% — pełny prostokąt nie wygląda jak akapit, a to
+ * Wariant `text` skraca ostatnią linię do 60% - pełny prostokąt nie wygląda jak akapit, a to
  * właśnie akapit ma udawać. Przy jednej linii nie ma czego udawać, więc ta ma pełną szerokość.
  *
  * @example

package/dist/slider/llms.txt

@@ -6,33 +6,39 @@ Import: `import { KptSlider } from '@konce-pt/react';`
 ## DOM
     <!-- single -->
     <div class="kpt-slider-host">
-      <input class="kpt-slider__input" type="range" style="--_pct: 40%">
+      <div class="kpt-slider__track" style="--_p: 0.4">
+        <input class="kpt-slider__input" type="range">
+        <span class="kpt-slider__bar" aria-hidden="true"><span class="kpt-slider__bar-fill"></span></span>
+        <span class="kpt-slider__knob" aria-hidden="true"></span>
+      </div>
       <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>
+      <div class="kpt-slider__track kpt-slider__track--range" style="--_lo: 0.2; --_hi: 0.8">
         <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="Maximum">
+        <span class="kpt-slider__bar" aria-hidden="true"><span class="kpt-slider__bar-fill"></span></span>
+        <span class="kpt-slider__knob kpt-slider__knob--low" aria-hidden="true"></span>
+        <span class="kpt-slider__knob kpt-slider__knob--high" aria-hidden="true"></span>
       </div>
-      <span class="kpt-slider__value">20–80</span>
+      <span class="kpt-slider__value">20-80</span>
     </div>
 
 ## Props
-- `value` / `defaultValue` / `onValueChange` — `number`, or `[number, number]` in `range` mode
-- `range`: boolean — two handles
+- `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
+- `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.
+gestures and screen readers work with no handling of our own. The only custom pointer logic is the
+press on the track next to the handles (see "Pointer"). The track, fill and handles you see are
+decoration drawn under the transparent inputs.
 
 ## The handles cannot cross
 Moving the low handle above the high one clamps it to the high value, and the other way round. The
@@ -43,7 +49,7 @@ pair therefore always stays ordered, so the fill never inverts.
     <KptSlider range value={span} onValueChange={(v) => setSpan(v as [number, number])} showValue />
 
 ## Screen reader and keyboard
-`suffix`: string (" zł", "%", " km") — shown after the value and put into `aria-valuetext` ("40
+`suffix`: string (" zł", "%", " km") - shown after the value and put into `aria-valuetext` ("40
 zł"), so the unit is read too. `aria-invalid` after touch.
 
 ## Label and description
@@ -55,9 +61,25 @@ previously hard-coded and mixed-language); inside `kpt-form-field` each thumb re
 Minimum" through `aria-labelledby`, without one `ariaLabel` gives "<ariaLabel>, Minimum". `id` goes
 to the single input or the lower thumb.
 
+## Pointer
+The handle reacts to the pointer: it grows on hover, and while held it grows more on a spring with
+a soft halo in the primary colour and a `grabbing` cursor. A click on the track (and a key press) glides
+the handle and the fill to the new value instead of jumping; while dragging they follow the pointer with
+no delay. The native `input[type=range]` stays transparent on top (keyboard, screen reader, dragging) and
+the track, fill and handle are drawn next to it from `--_p` (0..1); `range` draws two handles from
+`--_lo`/`--_hi`. The glide is pure CSS and drops out under "reduce motion".
+
+In `range` mode a press on the track outside the handles - before the range, after it or inside it -
+moves the nearest handle there, focuses it (arrow keys keep working) and keeps dragging it until
+release. The handles themselves are dragged natively. When both handles sit in the upper half, the
+lower one is stacked on top, so two handles pushed against `max` can still be pulled apart.
+
 ## Tokens
-`--kpt-color-primary` (the fill and the handles), `--kpt-color-muted` (the rail).
+`--kpt-color-primary` (the fill and the handles), `--kpt-color-surface-variant` (the track).
 
 ## 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.
+
+## Read-only and required
+`readOnly` keeps the thumb focusable but undoes every move (`aria-readonly`). The range thumbs can no longer cross: the clamped value is written back to the native input, so the thumb stops at the other one. `slider` does not accept `aria-required` - the field asterisk and the validator carry it.

package/dist/slider/slider-drag.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Oznacza tor suwaka jako przeciągany (`data-dragging`) od pierwszego ruchu wskaźnika o kilka pikseli
+ * do puszczenia. Samo kliknięcie zostawia tor bez znacznika, więc skok wartości jedzie przejściem CSS.
+ * Ta sama funkcja jest w porcie Angulara (`slider/slider-drag.ts`).
+ */
+export declare function kptTrackDrag(track: HTMLElement, startX: number): void;
+/** Koniec zakresu: dolny albo górny uchwyt. */
+export type KptRangeEnd = 'low' | 'high';
+export interface KptRangePressOptions {
+    min: number;
+    max: number;
+    step: number;
+    low: number;
+    high: number;
+    /** Ustawia wybrany koniec. Pilnowanie, by uchwyty się nie minęły, zostaje w komponencie. */
+    set: (end: KptRangeEnd, value: number) => void;
+    /** Puszczenie wskaźnika. */
+    release?: () => void;
+}
+/**
+ * Wciśnięcie toru zakresu poza uchwytem. Najbliższy uchwyt skacze w to miejsce (wewnątrz zakresu
+ * też - ten bliższy), dostaje fokus, żeby dalej działały strzałki, i idzie za wskaźnikiem aż do
+ * puszczenia. Natywne suwaki tego nie zrobią: przy dwóch nałożonych inputach wskaźnik łapią tylko
+ * kciuki, a kliknięcie w tor trafiłoby w jeden z nich zawsze, niezależnie od odległości.
+ */
+export declare function kptRangePress(track: HTMLElement, event: PointerEvent, opts: KptRangePressOptions): void;

package/dist/slider/slider-drag.js

@@ -0,0 +1,79 @@
+/**
+ * Oznacza tor suwaka jako przeciągany (`data-dragging`) od pierwszego ruchu wskaźnika o kilka pikseli
+ * do puszczenia. Samo kliknięcie zostawia tor bez znacznika, więc skok wartości jedzie przejściem CSS.
+ * Ta sama funkcja jest w porcie Angulara (`slider/slider-drag.ts`).
+ */
+export function kptTrackDrag(track, startX) {
+    const move = (e) => {
+        if (Math.abs(e.clientX - startX) >= 3)
+            track.setAttribute('data-dragging', '');
+    };
+    const up = () => {
+        window.removeEventListener('pointermove', move);
+        window.removeEventListener('pointerup', up);
+        window.removeEventListener('pointercancel', up);
+        track.removeAttribute('data-dragging');
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+    window.addEventListener('pointercancel', up);
+}
+/**
+ * Wciśnięcie toru zakresu poza uchwytem. Najbliższy uchwyt skacze w to miejsce (wewnątrz zakresu
+ * też - ten bliższy), dostaje fokus, żeby dalej działały strzałki, i idzie za wskaźnikiem aż do
+ * puszczenia. Natywne suwaki tego nie zrobią: przy dwóch nałożonych inputach wskaźnik łapią tylko
+ * kciuki, a kliknięcie w tor trafiłoby w jeden z nich zawsze, niezależnie od odległości.
+ */
+export function kptRangePress(track, event, opts) {
+    if (event.button !== 0)
+        return;
+    // Bez tego przeglądarka zaznacza tekst w trakcie ciągnięcia i zabiera fokus z uchwytu.
+    event.preventDefault();
+    const first = rangeValueAt(track, event.clientX, opts);
+    const end = first < opts.low ? 'low' : first > opts.high ? 'high' : first - opts.low <= opts.high - first ? 'low' : 'high';
+    let last = first;
+    opts.set(end, first);
+    track.querySelector(`.kpt-slider__thumb--${end}`)?.focus({ preventScroll: true });
+    track.setAttribute('data-pressed', end);
+    const move = (e) => {
+        const next = rangeValueAt(track, e.clientX, opts);
+        if (next === last)
+            return;
+        last = next;
+        opts.set(end, next);
+    };
+    const up = () => {
+        window.removeEventListener('pointermove', move);
+        window.removeEventListener('pointerup', up);
+        window.removeEventListener('pointercancel', up);
+        track.removeAttribute('data-pressed');
+        opts.release?.();
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+    window.addEventListener('pointercancel', up);
+}
+/**
+ * Wartość pod wskaźnikiem, przyciągnięta do kroku tak jak natywny suwak. Środek uchwytu jeździ
+ * od połowy jego szerokości do szerokości toru minus połowa - stąd odjęcie szerokości uchwytu.
+ */
+function rangeValueAt(track, clientX, { min, max, step }) {
+    const rect = track.getBoundingClientRect();
+    const thumb = track.querySelector('.kpt-slider__knob')?.offsetWidth ?? 0;
+    const usable = rect.width - thumb;
+    let frac = usable > 0 ? (clientX - rect.left - thumb / 2) / usable : 0;
+    frac = Math.min(1, Math.max(0, frac));
+    if (getComputedStyle(track).direction === 'rtl')
+        frac = 1 - frac;
+    if (max <= min)
+        return min;
+    if (!(step > 0))
+        return min + frac * (max - min);
+    let steps = Math.round((frac * (max - min)) / step);
+    // Jak natywny suwak: ostatni krok nie wychodzi za `max`, gdy zakres nie dzieli się przez krok.
+    if (min + steps * step > max)
+        steps -= 1;
+    // Ułamkowy krok (0.1) zostawia ogon zmiennoprzecinkowy - przycięcie do liczby miejsc kroku.
+    const decimals = String(step).split('.')[1]?.length ?? 0;
+    return Number((min + steps * step).toFixed(decimals));
+}

package/dist/slider/slider.d.ts

@@ -13,25 +13,28 @@ export interface KptSliderProps extends Omit<ComponentPropsWithRef<'div'>, 'onCh
     step?: number;
     /** Pokazuje bieżącą wartość obok suwaka. */
     showValue?: boolean;
-    /** Jednostka za liczbą („ zł”, „%”, „ km”) — w pokazanej wartości i w `aria-valuetext`. */
+    /** Jednostka za liczbą (" zł", "%", " km") - w pokazanej wartości i w `aria-valuetext`. */
     suffix?: string;
     invalid?: boolean;
     touched?: boolean;
-    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` - z wrappera. */
     id?: string;
     /** Nazwa dostępna, gdy kontrolki nie opisuje etykieta (`<label for>` albo `KptFormField`). */
     ariaLabel?: string | null;
     disabled?: boolean;
+    /** Tylko do odczytu - uchwyt można skupić, ale nie przesunąć (`aria-readonly`). */
+    readOnly?: boolean;
     onTouch?: () => void;
 }
 /**
  * Suwak wartości. W trybie `range` udostępnia dwa uchwyty, a wartością jest para `[min, max]`.
  *
- * Oba uchwyty to natywne `<input type="range">` leżące na sobie — dzięki temu klawiatura,
- * gesty dotykowe i czytniki ekranu działają bez ani jednej linii własnej obsługi.
+ * Oba uchwyty to natywne `<input type="range">` leżące na sobie - klawiatura, gesty dotykowe
+ * i czytniki ekranu działają bez własnej obsługi. Własna jest tylko jedna rzecz: wciśnięcie toru
+ * obok kciuków przesuwa najbliższy uchwyt (`kptRangePress`).
  *
  * @example
  * <KptSlider value={volume} onValueChange={setVolume} min={0} max={100} step={5} showValue />
  * <KptSlider range value={range} onValueChange={setRange} showValue />
  */
-export declare function KptSlider({ value, defaultValue, onValueChange, range, min, max, step, showValue, suffix, invalid, touched, id, ariaLabel, disabled, onTouch, locale, dictionary, className, ...rest }: Readonly<KptSliderProps>): import("react").JSX.Element;
+export declare function KptSlider({ value, defaultValue, onValueChange, range, min, max, step, showValue, suffix, invalid, touched, id, ariaLabel, disabled, readOnly, onTouch, locale, dictionary, className, ...rest }: Readonly<KptSliderProps>): import("react").JSX.Element;

package/dist/slider/slider.js

@@ -1,22 +1,25 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
+import { kptRangePress, kptTrackDrag } from "./slider-drag.js";
 /**
  * Suwak wartości. W trybie `range` udostępnia dwa uchwyty, a wartością jest para `[min, max]`.
  *
- * Oba uchwyty to natywne `<input type="range">` leżące na sobie — dzięki temu klawiatura,
- * gesty dotykowe i czytniki ekranu działają bez ani jednej linii własnej obsługi.
+ * Oba uchwyty to natywne `<input type="range">` leżące na sobie - klawiatura, gesty dotykowe
+ * i czytniki ekranu działają bez własnej obsługi. Własna jest tylko jedna rzecz: wciśnięcie toru
+ * obok kciuków przesuwa najbliższy uchwyt (`kptRangePress`).
  *
  * @example
  * <KptSlider value={volume} onValueChange={setVolume} min={0} max={100} step={5} showValue />
  * <KptSlider range value={range} onValueChange={setRange} showValue />
  */
-export function KptSlider({ value, defaultValue, onValueChange, range = false, min = 0, max = 100, step = 1, showValue = false, suffix = '', invalid = false, touched, id, ariaLabel = null, disabled = false, onTouch, locale, dictionary, className, ...rest }) {
+export function KptSlider({ value, defaultValue, onValueChange, range = false, min = 0, max = 100, step = 1, showValue = false, suffix = '', invalid = false, touched, id, ariaLabel = null, disabled = false, readOnly = false, onTouch, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const field = useKptFieldA11y(id, 'kpt-slider');
-    /** Uchwyt zakresu bez etykiety pola: „Cena, Minimum” z `ariaLabel` albo samo „Minimum”. */
+    /** Uchwyt zakresu bez etykiety pola: "Cena, Minimum" z `ariaLabel` albo samo "Minimum". */
     const thumbLabel = (end) => {
         if (field.labelledBy)
             return undefined;
@@ -36,8 +39,35 @@ export function KptSlider({ value, defaultValue, onValueChange, range = false, m
         const span = max - min;
         return span <= 0 ? 0 : ((val - min) / span) * 100;
     };
-    // Uchwyty nie mogą się wyminąć — dolny nie przekracza górnego i odwrotnie.
-    const setLow = (next) => setCurrent([Math.min(next, high), high]);
-    const setHigh = (next) => setCurrent([low, Math.max(next, low)]);
-    return (_jsx("div", { className: cn('kpt-slider-host', className), ...rest, children: range ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-slider__range", children: [_jsx("span", { className: "kpt-slider__sr", id: `${field.id}-min-name`, children: t('slider.min') }), _jsx("span", { className: "kpt-slider__sr", id: `${field.id}-max-name`, children: t('slider.max') }), _jsx("div", { className: "kpt-slider__rail" }), _jsx("div", { className: "kpt-slider__fill", style: { left: `${pct(low)}%`, right: `${100 - pct(high)}%` } }), _jsx("input", { className: "kpt-slider__thumb kpt-slider__thumb--low", type: "range", min: min, max: max, step: step, value: low, "aria-valuetext": suffix ? `${low}${suffix}` : undefined, "aria-invalid": invalid && (touched ?? true) ? true : undefined, id: field.id, disabled: disabled, "aria-label": thumbLabel('min'), "aria-labelledby": thumbLabelledBy('min'), "aria-describedby": field.describedBy, onChange: (event) => setLow(Number(event.target.value)), onBlur: () => onTouch?.() }), _jsx("input", { className: "kpt-slider__thumb kpt-slider__thumb--high", type: "range", min: min, max: max, step: step, value: high, "aria-valuetext": suffix ? `${high}${suffix}` : undefined, "aria-invalid": invalid && (touched ?? true) ? true : undefined, disabled: disabled, "aria-label": thumbLabel('max'), "aria-labelledby": thumbLabelledBy('max'), "aria-describedby": field.describedBy, onChange: (event) => setHigh(Number(event.target.value)), onBlur: () => onTouch?.() })] }), showValue ? (_jsxs("span", { className: "kpt-slider__value", children: [low, suffix, "\u2013", high, suffix] })) : null] })) : (_jsxs(_Fragment, { children: [_jsx("input", { className: "kpt-slider__input", type: "range", min: min, max: max, step: step, value: single, "aria-valuetext": suffix ? `${single}${suffix}` : undefined, "aria-invalid": invalid && (touched ?? true) ? true : undefined, id: field.id, disabled: disabled, "aria-label": ariaLabel ?? undefined, "aria-describedby": field.describedBy, style: { ['--_pct']: `${pct(single)}%` }, onChange: (event) => setCurrent(Number(event.target.value)), onBlur: () => onTouch?.() }), showValue ? (_jsxs("span", { className: "kpt-slider__value", children: [single, suffix] })) : null] })) }));
+    // Uchwyty nie mogą się wyminąć - dolny nie przekracza górnego i odwrotnie.
+    // Suwaki są kontrolowane: przy `readOnly` stan się nie zmienia, więc React cofa uchwyt sam.
+    const setLow = (next) => {
+        if (!readOnly)
+            setCurrent([Math.min(next, high), high]);
+    };
+    const setHigh = (next) => {
+        if (!readOnly)
+            setCurrent([low, Math.max(next, low)]);
+    };
+    // Kciuki ciągnie natywny suwak; wciśnięcie obok nich (przed zakresem, za nim albo w środku)
+    // przesuwa najbliższy uchwyt i dalej go ciągnie - patrz kptRangePress.
+    const onRangePress = (event) => {
+        kptTrackDrag(event.currentTarget, event.clientX);
+        if (disabled || event.target instanceof HTMLInputElement)
+            return;
+        kptRangePress(event.currentTarget, event.nativeEvent, {
+            min,
+            max,
+            step,
+            low,
+            high,
+            set: (end, v) => (end === 'low' ? setLow(v) : setHigh(v)),
+        });
+    };
+    return (_jsx("div", { className: cn('kpt-slider-host', className), ...rest, children: range ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-slider__track kpt-slider__track--range", style: { ['--_lo']: pct(low) / 100, ['--_hi']: pct(high) / 100 }, "data-low-top": pct(low) > 50 ? '' : undefined, onPointerDown: onRangePress, children: [_jsx("span", { className: "kpt-slider__sr", id: `${field.id}-min-name`, children: t('slider.min') }), _jsx("span", { className: "kpt-slider__sr", id: `${field.id}-max-name`, children: t('slider.max') }), _jsx("input", { className: "kpt-slider__thumb kpt-slider__thumb--low", type: "range", min: min, max: max, step: step, value: low, "aria-valuetext": suffix ? `${low}${suffix}` : undefined, "aria-invalid": invalid && (touched ?? true) ? true : undefined, id: field.id, disabled: disabled, "aria-label": thumbLabel('min'), "aria-labelledby": thumbLabelledBy('min'), "aria-describedby": field.describedBy, "aria-readonly": readOnly || undefined, onChange: (event) => setLow(Number(event.target.value)), onBlur: () => onTouch?.() }), _jsx("input", { className: "kpt-slider__thumb kpt-slider__thumb--high", type: "range", min: min, max: max, step: step, value: high, "aria-valuetext": suffix ? `${high}${suffix}` : undefined, "aria-invalid": invalid && (touched ?? true) ? true : undefined, disabled: disabled, "aria-label": thumbLabel('max'), "aria-labelledby": thumbLabelledBy('max'), "aria-describedby": field.describedBy, "aria-readonly": readOnly || undefined, onChange: (event) => setHigh(Number(event.target.value)), onBlur: () => onTouch?.() }), _jsx("span", { className: "kpt-slider__bar", "aria-hidden": "true", children: _jsx("span", { className: "kpt-slider__bar-fill" }) }), _jsx("span", { className: "kpt-slider__knob kpt-slider__knob--low", "aria-hidden": "true" }), _jsx("span", { className: "kpt-slider__knob kpt-slider__knob--high", "aria-hidden": "true" })] }), showValue ? (_jsxs("span", { className: "kpt-slider__value", children: [low, suffix, "-", high, suffix] })) : null] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: "kpt-slider__track", style: { ['--_p']: pct(single) / 100 }, 
+                    // Skok po kliknięciu w tor jedzie (przejście w CSS), przeciąganie już nie - patrz kptTrackDrag.
+                    onPointerDown: (event) => kptTrackDrag(event.currentTarget, event.clientX), children: [_jsx("input", { className: "kpt-slider__input", type: "range", min: min, max: max, step: step, value: single, "aria-valuetext": suffix ? `${single}${suffix}` : undefined, "aria-invalid": invalid && (touched ?? true) ? true : undefined, id: field.id, disabled: disabled, "aria-label": ariaLabel ?? undefined, "aria-describedby": field.describedBy, "aria-readonly": readOnly || undefined, onChange: (event) => {
+                                if (!readOnly)
+                                    setCurrent(Number(event.target.value));
+                            }, onBlur: () => onTouch?.() }), _jsx("span", { className: "kpt-slider__bar", "aria-hidden": "true", children: _jsx("span", { className: "kpt-slider__bar-fill" }) }), _jsx("span", { className: "kpt-slider__knob", "aria-hidden": "true" })] }), showValue ? (_jsxs("span", { className: "kpt-slider__value", children: [single, suffix] })) : null] })) }));
 }

package/dist/speech/llms.txt

@@ -0,0 +1,97 @@
+# KptSpeechButton, KptSpeechWave, useKptSpeechRecognition (@konce-pt/react)
+
+Dictation with a microphone button. A click turns the icon into "stop", an animated wave slides in
+next to it and the recognised words appear live in the target: a textarea, an input, a
+`contenteditable` element, a plain element or a function. Built on the Web Speech API; the session,
+insertion and wave maths live in `@konce-pt/speech`, shared with the Angular port.
+Import: `import { KptSpeechButton, KptSpeechWave, useKptSpeechRecognition } from '@konce-pt/react';`
+
+## The key rule
+Interim text is visible in the target but never reaches your state. A textarea or input shows it in
+the native value without an event; only final text goes in as a regular edit (`setRangeText` +
+`InputEvent`, or `insertText` with native undo when the field has focus), so a controlled field's
+`onChange` sees it like typed text. The core never writes `el.value = x` - React would swallow it.
+
+## DOM
+    <span class="kpt-speech-button-host" data-status="listening" data-wave-position="start">
+      <span class="kpt-speech-wave-host kpt-speech-button__wave" aria-hidden="true" data-mode="live">...</span>
+      <span class="kpt-icon-button-host kpt-speech-button__toggle">
+        <button class="kpt-icon-button" aria-label="Dictate" aria-pressed="true">...icon...</button>
+      </span>
+      <span class="kpt-speech-button__status" aria-live="polite">Listening...</span>
+    </span>
+
+## useKptSpeechRecognition(options)
+Dictation without UI - for your own button, a keyboard shortcut, or to call `flush()` before sending.
+Options:
+- `target`: `HTMLElement | RefObject<HTMLElement | null> | KptSpeechTarget | (snapshot) => void`
+- `lang`: string - BCP 47; without it from `KptI18nProvider` and the browser language
+- `continuous`: boolean = true; `mode`: `'insert' | 'append' | 'replace'` = `'insert'` (`replace`
+  clears the target the moment dictation starts, undoable with Ctrl+Z)
+- `interim`: `'inline' | 'ghost' | 'none'`; `capitalize`: boolean = true
+- `wave`: `'auto' | 'live' | 'synthetic' | 'none'` = `'auto'`; `bars`: number = 5
+- `silenceMs`, `maxDuration` (ms, 0 = off), `processLocally` (on-device only, Chrome 135+), `disabled`
+- `onStart`, `onEnd(reason)`, `onResult(snapshot)`, `onError(code)`
+
+Returns `KptSpeechRecognition`: `status`, `listening`, `support` (`null` until the first client
+render - SSR safe), `available`, `error`, `lastEnd`, `speaking`, `levels`, `waveMode`, `snapshot`
+(`{ finalText, interimText }`), and `start()`, `stop()` (graceful), `flush()` (interim becomes final
+and dictation ends at once), `abort()`, `toggle()`.
+
+## KptSpeechButton - props
+- every option of `useKptSpeechRecognition`, or `speech` - an external controller from the hook (then
+  the button's own dictation options are ignored)
+- `unsupported`: `'disable' | 'hide'` = `'disable'` - Firefox, `http:`, or a browser without the
+  service: a disabled button with the reason in a tooltip, or nothing
+- `wavePosition`: `'start' | 'end'` = `'start'`
+- `listeningColor`: `'primary' | 'danger' | 'success' | 'warning' | 'info'` = `'primary'` - colour of
+  "stop" and the wave while listening (the theme colour by default). Any other colour: set
+  `--kpt-speech-color` and `--kpt-speech-on-color` (icon on it) - both inherit, so they also work on
+  fields with a built-in microphone or globally in `:root`.
+- `size` = 'md', `variant` = 'text'
+- `aria-label` (default "Dictate" from the dictionary); `locale`, `dictionary`
+- `hostProps` - props for `.kpt-speech-button-host`; `className`, `ref` and other `<button>` props go
+  to the inner `<button>`
+
+## Examples
+    const noteRef = useRef<HTMLTextAreaElement>(null);
+    <textarea ref={noteRef} />
+    <KptSpeechButton target={noteRef} />
+
+    <KptSpeechButton target={(snapshot) => setDraft(snapshot.finalText)} lang="en-US" />
+
+    const speech = useKptSpeechRecognition({ target: fieldRef });
+    <KptSpeechButton speech={speech} />
+    <KptButton onClick={() => { speech.flush(); send(); }}>Send</KptButton>
+
+## KptSpeechWave
+Bars next to the microphone, `aria-hidden`. `levels: readonly number[]` (0..1) draws a live wave;
+empty `levels` gives the synthetic one, higher while `active` (voice heard). `bars`: number = 5.
+Colour: `--kpt-speech-wave-color`, otherwise the listening colour of the button.
+
+## Behaviour
+- One dictation per page: starting a microphone stops the previous one.
+- Continuous mode survives Chrome ending recognition after silence or about a minute; on iOS the
+  button stops and announces "Tap the microphone to continue".
+- Typing or moving the caret mid-dictation drops the interim text; dictation continues at the caret.
+- A hidden tab stops dictation; unmounting releases the microphone.
+
+## Screen reader and keyboard
+- The button name stays the same ("Dictate"); the state is carried by `aria-pressed`.
+- A polite live region announces start, stop and errors - never the transcript.
+- Clicking the button does not move focus out of the target. Escape on the button or in the target
+  stops dictation.
+
+## Browsers and privacy
+Chrome, Edge and Safari recognise speech; Firefox does not. A secure context is required. Chrome sends
+audio to a Google service unless `processLocally` is set - mention it in the privacy policy.
+
+## Built into fields
+`KptInput`, `KptTextarea` and `KptChatComposer` take `speech` (`speechLang`, `speechMode`, `speechColor`) - the same
+layout as in Angular; they use `unsupported="hide"` and reserve room only when `available` is true.
+`KptRichText` has the `dictate` tool, `KptAutocomplete` takes `speech` (default `replace`) and
+`KptDataTable` takes `filterSpeech`, `KptMapSearch` takes `speech` (forwarded by `KptMap` as
+`searchSpeech`). Search fields clear on click and listen for one utterance.
+
+The hook option `enabled` (default true) creates no session and no page listeners when false - for
+components where the microphone is optional.

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

@@ -0,0 +1,44 @@
+import type { ComponentPropsWithRef } from 'react';
+import type { KptButtonSize, KptButtonVariant } from '../button/button.tsx';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+import type { KptHostProps } from '../internal/types.ts';
+import { type KptSpeechRecognition, type KptSpeechRecognitionOptions } from './use-speech-recognition.ts';
+/** Co zrobić, gdy przeglądarka nie rozpoznaje mowy. */
+export type KptSpeechUnsupported = 'hide' | 'disable';
+/**
+ * Kolor przycisku "stop" i fali w trakcie nasłuchu. Domyślnie kolor motywu (`primary`); dowolny inny
+ * przez `--kpt-speech-color` i `--kpt-speech-on-color` (dziedziczone, więc działają też w polach).
+ */
+export type KptSpeechColor = 'primary' | 'danger' | 'success' | 'warning' | 'info';
+export interface KptSpeechButtonProps extends KptSpeechRecognitionOptions, Omit<ComponentPropsWithRef<'button'>, 'children' | 'type' | 'onError' | 'disabled'>, KptI18nOverrides {
+    /**
+     * Zewnętrzny kontroler z `useKptSpeechRecognition` - gdy aplikacja sama chce wołać `flush()`,
+     * `stop()` albo czytać `snapshot`. Wtedy opcje dyktowania z propsów przycisku są pomijane.
+     */
+    speech?: KptSpeechRecognition;
+    /** Brak wsparcia: `disable` (domyślnie, z powodem w podpowiedzi) albo `hide`. */
+    unsupported?: KptSpeechUnsupported;
+    /** Po której stronie przycisku stoi fala. */
+    wavePosition?: 'start' | 'end';
+    size?: KptButtonSize;
+    variant?: KptButtonVariant;
+    /** Kolor "stop" i fali w trakcie nasłuchu - domyślnie kolor motywu. */
+    listeningColor?: KptSpeechColor;
+    /** Nazwa przycisku; bez niej "Dyktuj" ze słownika. Stała - stan niesie `aria-pressed`. */
+    'aria-label'?: string;
+    /** Propsy wrappera hosta (`.kpt-speech-button-host`). */
+    hostProps?: KptHostProps<'span'>;
+}
+/**
+ * Mikrofon do dyktowania. Klik zamienia ikonę w "stop", obok wjeżdża animowana fala, a słowa
+ * płyną na żywo do celu: textarea, inputu, contenteditable, zwykłego elementu albo funkcji.
+ *
+ * Tekst tymczasowy widać w celu, ale do stanu kontrolowanego pola trafia wyłącznie tekst
+ * zatwierdzony - przez zwykłą edycję, którą `onChange` widzi jak wpisany tekst.
+ *
+ * @example
+ * const noteRef = useRef<HTMLTextAreaElement>(null);
+ * <textarea ref={noteRef} />
+ * <KptSpeechButton target={noteRef} />
+ */
+export declare function KptSpeechButton({ speech, target, lang, continuous, mode, interim, capitalize, wave, bars, silenceMs, maxDuration, processLocally, disabled, onStart, onEnd, onResult, onError, unsupported, wavePosition, size, variant, listeningColor, 'aria-label': ariaLabel, hostProps, locale, dictionary, className, onClick, onMouseDown, onKeyDown, ...rest }: Readonly<KptSpeechButtonProps>): import("react").JSX.Element;

package/dist/speech/speech-button.js

@@ -0,0 +1,86 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { speechErrorMessageKey } from '@konce-pt/speech';
+import { KptIcon } from "../icon/icon.js";
+import { KptIconButton } from "../icon-button/icon-button.js";
+import { KptTooltip } from "../tooltip/tooltip.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
+import { cn } from "../internal/cn.js";
+import { KptSpeechWave } from "./speech-wave.js";
+import { useKptSpeechRecognition, } from "./use-speech-recognition.js";
+/**
+ * Mikrofon do dyktowania. Klik zamienia ikonę w "stop", obok wjeżdża animowana fala, a słowa
+ * płyną na żywo do celu: textarea, inputu, contenteditable, zwykłego elementu albo funkcji.
+ *
+ * Tekst tymczasowy widać w celu, ale do stanu kontrolowanego pola trafia wyłącznie tekst
+ * zatwierdzony - przez zwykłą edycję, którą `onChange` widzi jak wpisany tekst.
+ *
+ * @example
+ * const noteRef = useRef<HTMLTextAreaElement>(null);
+ * <textarea ref={noteRef} />
+ * <KptSpeechButton target={noteRef} />
+ */
+export function KptSpeechButton({ speech, target, lang, continuous, mode, interim, capitalize, wave, bars = 5, silenceMs, maxDuration, processLocally, disabled = false, onStart, onEnd, onResult, onError, unsupported = 'disable', wavePosition = 'start', size = 'md', variant = 'text', listeningColor = 'primary', 'aria-label': ariaLabel, hostProps, locale, dictionary, className, onClick, onMouseDown, onKeyDown, ...rest }) {
+    const { t } = useKptMessages({ locale, dictionary });
+    // Hook jest wołany zawsze (zasady hooków); z zewnętrznym kontrolerem własny jest wyłączony
+    // (`enabled: false`) - bez sesji i bez nasłuchów strony.
+    const own = useKptSpeechRecognition({
+        enabled: !speech,
+        target,
+        lang,
+        continuous,
+        mode,
+        interim,
+        capitalize,
+        wave,
+        bars,
+        silenceMs,
+        maxDuration,
+        processLocally,
+        disabled,
+        onStart,
+        onEnd,
+        onResult,
+        onError,
+    });
+    const ctl = speech ?? own;
+    const known = ctl.support !== null;
+    const hidden = unsupported === 'hide' && (!known || !ctl.available);
+    const isDisabled = disabled || !ctl.available;
+    // Powód blokady albo ostatni błąd - w podpowiedzi. Cisza nie jest błędem wartym dymka.
+    let hint = '';
+    if (known && !ctl.available) {
+        hint = t(speechErrorMessageKey(ctl.support?.reason ?? 'unsupported'));
+    }
+    else if (ctl.error && ctl.error !== 'no-speech') {
+        hint = t(speechErrorMessageKey(ctl.error));
+    }
+    // Region statusu ogłasza stan i błędy, nigdy treść - czytnik czytający transkrypt zostałby
+    // nagrany przez mikrofon i wpisany z powrotem do pola.
+    let announcement = '';
+    if (ctl.error)
+        announcement = t(speechErrorMessageKey(ctl.error));
+    else if (ctl.listening)
+        announcement = t('speech.listening');
+    else if (ctl.lastEnd && ctl.lastEnd !== 'error') {
+        // iOS: restart bez dotknięcia jest zawodny - sesja staje, a użytkownik dostaje wskazówkę.
+        const iosPause = ctl.support?.ios && (continuous ?? true) && (ctl.lastEnd === 'ended' || ctl.lastEnd === 'silence');
+        announcement = t(iosPause ? 'speech.tapToContinue' : 'speech.stopped');
+    }
+    const { className: hostClassName, ...hostRest } = hostProps ?? {};
+    return (_jsx("span", { className: cn('kpt-speech-button-host', hostClassName), "data-status": ctl.status, "data-wave-position": wavePosition, "data-color": listeningColor, hidden: hidden || undefined, ...hostRest, children: !hidden ? (_jsxs(_Fragment, { children: [ctl.listening && ctl.waveMode !== 'none' ? (_jsx(KptSpeechWave, { className: "kpt-speech-button__wave", levels: ctl.waveMode === 'live' ? ctl.levels : [], active: ctl.speaking, bars: bars })) : null, _jsx(KptTooltip, { text: hint, children: _jsx(KptIconButton, { className: className, hostProps: { className: 'kpt-speech-button__toggle' }, variant: ctl.listening ? 'filled' : variant, size: size, disabled: isDisabled, "aria-label": ariaLabel ?? t('speech.dictate'), "aria-pressed": ctl.listening, onMouseDown: (event) => {
+                            onMouseDown?.(event);
+                            // Klik nie zabiera fokusu z celu - kursor zostaje tam, gdzie trafi tekst.
+                            event.preventDefault();
+                        }, onClick: (event) => {
+                            onClick?.(event);
+                            if (!event.defaultPrevented)
+                                ctl.toggle();
+                        }, onKeyDown: (event) => {
+                            onKeyDown?.(event);
+                            if (event.key === 'Escape' && ctl.listening) {
+                                event.preventDefault();
+                                ctl.stop();
+                            }
+                        }, ...rest, children: _jsx(KptIcon, { name: ctl.listening ? 'player-stop' : 'microphone' }) }) }), _jsx("span", { className: "kpt-speech-button__status", "aria-live": "polite", children: announcement })] })) : null }));
+}

package/dist/speech/speech-wave.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentPropsWithRef } from 'react';
+export interface KptSpeechWaveProps extends Omit<ComponentPropsWithRef<'span'>, 'children'> {
+    /** Poziomy 0..1 z miernika; pusta lista przełącza falę w tryb syntetyczny. */
+    levels?: readonly number[];
+    /** Tryb syntetyczny: silnik słyszy mowę - słupki skaczą wyżej. */
+    active?: boolean;
+    /** Liczba słupków w trybie syntetycznym (na żywo decyduje długość `levels`). */
+    bars?: number;
+}
+/**
+ * Animowana fala dźwięku - słupki obok mikrofonu. Czysta dekoracja (`aria-hidden`): stan
+ * nasłuchu niesie przycisk (`aria-pressed`) i region statusu, nie rysunek. Te same klasy co
+ * `kpt-speech-wave` w Angularze, więc styl jest wspólny.
+ *
+ * @example
+ * <KptSpeechWave levels={speech.levels} />
+ * <KptSpeechWave active={speech.speaking} />
+ */
+export declare function KptSpeechWave({ levels, active, bars, className, ...rest }: Readonly<KptSpeechWaveProps>): import("react").JSX.Element;

package/dist/speech/speech-wave.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "../internal/cn.js";
+/**
+ * Animowana fala dźwięku - słupki obok mikrofonu. Czysta dekoracja (`aria-hidden`): stan
+ * nasłuchu niesie przycisk (`aria-pressed`) i region statusu, nie rysunek. Te same klasy co
+ * `kpt-speech-wave` w Angularze, więc styl jest wspólny.
+ *
+ * @example
+ * <KptSpeechWave levels={speech.levels} />
+ * <KptSpeechWave active={speech.speaking} />
+ */
+export function KptSpeechWave({ levels = [], active = false, bars = 5, className, ...rest }) {
+    const live = levels.length > 0;
+    const slots = live ? levels : Array.from({ length: Math.max(1, bars) }, () => null);
+    return (_jsx("span", { className: cn('kpt-speech-wave-host', className), "aria-hidden": "true", "data-mode": live ? 'live' : 'synthetic', "data-active": active ? '' : undefined, ...rest, children: slots.map((level, index) => (_jsx("span", { className: "kpt-speech-wave__bar", style: { '--_i': index, ...(level === null ? {} : { '--_level': level }) } }, index))) }));
+}