@konce-pt/react 0.12.0 → 0.15.0

package/dist/slider/slider.js

@@ -4,11 +4,13 @@ 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 />
@@ -17,7 +19,7 @@ import { useKptMessages } from "../i18n/i18n-context.js";
 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;
@@ -37,7 +39,7 @@ 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.
+    // 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)
@@ -47,8 +49,25 @@ export function KptSlider({ value, defaultValue, onValueChange, range = false, m
         if (!readOnly)
             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, "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?.() })] }), 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)}%` }, "aria-readonly": readOnly || undefined, onChange: (event) => {
-                        if (!readOnly)
-                            setCurrent(Number(event.target.value));
-                    }, onBlur: () => onTouch?.() }), showValue ? (_jsxs("span", { className: "kpt-slider__value", children: [single, suffix] })) : null] })) }));
+    // 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))) }));
+}

package/dist/speech/use-speech-recognition.d.ts

@@ -0,0 +1,81 @@
+import { type RefObject } from 'react';
+import { type KptSpeechEndReason, type KptSpeechErrorCode, type KptSpeechInterimDisplay, type KptSpeechMode, type KptSpeechSnapshot, type KptSpeechStatus, type KptSpeechSupport, type KptSpeechTargetInput, type KptSpeechWaveMode } from '@konce-pt/speech';
+/** Cel dyktowania: element, `ref` do elementu, gotowy `KptSpeechTarget` albo funkcja. */
+export type KptSpeechTargetRef = KptSpeechTargetInput | RefObject<HTMLElement | null>;
+export interface KptSpeechRecognitionOptions {
+    /** Gdzie trafia tekst. Bez celu kontroler tylko zgłasza `onResult`. */
+    target?: KptSpeechTargetRef | null;
+    /** Język rozpoznawania (BCP 47); bez niego z `KptI18nProvider` i języka przeglądarki. */
+    lang?: string;
+    /** Słuchaj do "stop" (domyślnie) albo do końca jednej wypowiedzi. */
+    continuous?: boolean;
+    /** `insert` (w kursor, domyślnie), `append` albo `replace` (czyści cel w chwili startu). */
+    mode?: KptSpeechMode;
+    /** Pokaz tekstu tymczasowego; bez wartości - domyślny dla rodzaju celu. */
+    interim?: KptSpeechInterimDisplay;
+    /** Wielka litera na początku zdania. Domyślnie `true`. */
+    capitalize?: boolean;
+    /** Fala: `auto` (na żywo na desktopie, syntetyczna na telefonie), `live`, `synthetic`, `none`. */
+    wave?: KptSpeechWaveMode;
+    /** Słupki fali na żywo. Domyślnie 5. */
+    bars?: number;
+    /** Zatrzymaj po tylu ms bez nowego słowa; `0` - nigdy. */
+    silenceMs?: number;
+    /** Twardy limit długości dyktowania w ms; `0` - bez limitu. */
+    maxDuration?: number;
+    /** Rozpoznawanie wyłącznie w urządzeniu (Chrome 135+). */
+    processLocally?: boolean;
+    disabled?: boolean;
+    /**
+     * Czy kontroler w ogóle istnieje. `false` nie tworzy sesji ani nasłuchów strony - dla pól,
+     * w których mikrofon jest opcją (`speech` w `KptInput`). Domyślnie `true`.
+     */
+    enabled?: boolean;
+    onStart?: () => void;
+    onEnd?: (reason: KptSpeechEndReason) => void;
+    /** Stan transkryptu po każdej zmianie: zatwierdzony i tymczasowy osobno. */
+    onResult?: (snapshot: KptSpeechSnapshot) => void;
+    onError?: (code: KptSpeechErrorCode) => void;
+}
+export interface KptSpeechRecognition {
+    status: KptSpeechStatus;
+    /** Trwa nasłuch (także start i łagodne zatrzymywanie). */
+    listening: boolean;
+    /** Wsparcie przeglądarki - `null` do pierwszego renderu po stronie klienta (SSR). */
+    support: KptSpeechSupport | null;
+    /** Da się dyktować: przeglądarka rozpoznaje mowę, a usługa nie odmówiła (`network`). */
+    available: boolean;
+    /** Ostatni błąd albo `null`. */
+    error: KptSpeechErrorCode | null;
+    /** Powód końca ostatniego dyktowania; `null` przed pierwszym i w trakcie nasłuchu. */
+    lastEnd: KptSpeechEndReason | null;
+    /** Silnik słyszy mowę - napęd fali syntetycznej. */
+    speaking: boolean;
+    /** Poziomy fali na żywo (0..1), puste poza nasłuchem i w trybie syntetycznym. */
+    levels: readonly number[];
+    /** Rozstrzygnięty tryb fali. */
+    waveMode: Exclude<KptSpeechWaveMode, 'auto'>;
+    snapshot: KptSpeechSnapshot;
+    start: () => void;
+    /** Łagodny stop: ostatnie słowa jeszcze się zatwierdzą. */
+    stop: () => void;
+    /** Zatwierdź to, co widać, i skończ od razu - przed wysłaniem treści. */
+    flush: () => void;
+    /** Przerwij bez zatwierdzania tekstu tymczasowego. */
+    abort: () => void;
+    toggle: () => void;
+}
+/**
+ * Dyktowanie bez UI - sesja Web Speech API, wstawianie w cel i poziomy fali z `@konce-pt/speech`.
+ * `KptSpeechButton` używa go pod spodem; własny przycisk albo skrót klawiszowy dostaje to samo.
+ *
+ * Tekst tymczasowy widać w celu, ale do wartości (stanu kontrolowanego pola) trafia wyłącznie
+ * zatwierdzony - przez zwykłą edycję, którą `onChange` widzi jak wpisany tekst.
+ *
+ * @example
+ * const fieldRef = useRef<HTMLTextAreaElement>(null);
+ * const speech = useKptSpeechRecognition({ target: fieldRef });
+ * <KptSpeechButton speech={speech} />
+ * <KptButton onClick={() => { speech.flush(); send(); }}>Send</KptButton>
+ */
+export declare function useKptSpeechRecognition(options?: KptSpeechRecognitionOptions): KptSpeechRecognition;

package/dist/speech/use-speech-recognition.js

@@ -0,0 +1,179 @@
+'use client';
+import { useEffect, useEffectEvent, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { browserSpeechEngine, createSpeechSession, defaultSpeechLang, mirrorSpeechLevels, onSpeechPageHidden, resolveSpeechTarget, resolveWaveMode, speechSupport, speechUnavailable, startSpeechMeter, } from '@konce-pt/speech';
+import { useKptI18n } from "../i18n/i18n-context.js";
+// Wsparcie przeglądarki nie zmienia się w trakcie życia strony - liczone raz, czytane przez
+// `useSyncExternalStore`, żeby serwer i hydracja widziały "nieznane", a klient od razu prawdę.
+let supportCache = null;
+const readSupport = () => (supportCache ??= speechSupport());
+const readServerSupport = () => null;
+const subscribeNever = () => () => undefined;
+const EMPTY_SNAPSHOT = { finalText: '', interimText: '' };
+const NO_LEVELS = [];
+function isRef(value) {
+    return typeof value === 'object' && value !== null && 'current' in value && !('begin' in value);
+}
+/**
+ * Dyktowanie bez UI - sesja Web Speech API, wstawianie w cel i poziomy fali z `@konce-pt/speech`.
+ * `KptSpeechButton` używa go pod spodem; własny przycisk albo skrót klawiszowy dostaje to samo.
+ *
+ * Tekst tymczasowy widać w celu, ale do wartości (stanu kontrolowanego pola) trafia wyłącznie
+ * zatwierdzony - przez zwykłą edycję, którą `onChange` widzi jak wpisany tekst.
+ *
+ * @example
+ * const fieldRef = useRef<HTMLTextAreaElement>(null);
+ * const speech = useKptSpeechRecognition({ target: fieldRef });
+ * <KptSpeechButton speech={speech} />
+ * <KptButton onClick={() => { speech.flush(); send(); }}>Send</KptButton>
+ */
+export function useKptSpeechRecognition(options = {}) {
+    const { locale } = useKptI18n();
+    const support = useSyncExternalStore(subscribeNever, readSupport, readServerSupport);
+    const enabled = options.enabled ?? true;
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(null);
+    const [speaking, setSpeaking] = useState(false);
+    const [levels, setLevels] = useState(NO_LEVELS);
+    const [meterFailed, setMeterFailed] = useState(false);
+    const [unavailable, setUnavailable] = useState(false);
+    const [snapshot, setSnapshot] = useState(EMPTY_SNAPSHOT);
+    const [lastEnd, setLastEnd] = useState(null);
+    const sessionRef = useRef(null);
+    const targetRef = useRef(null);
+    const targetElementRef = useRef(null);
+    const meterRef = useRef(null);
+    const listening = status === 'starting' || status === 'listening' || status === 'stopping';
+    const available = enabled && !!support?.supported && !unavailable && !speechUnavailable();
+    const resolvedWave = support ? resolveWaveMode(options.wave ?? 'auto', support) : 'none';
+    const waveMode = resolvedWave === 'live' && meterFailed ? 'synthetic' : resolvedWave;
+    const emitStart = useEffectEvent(() => options.onStart?.());
+    const emitEnd = useEffectEvent((reason) => options.onEnd?.(reason));
+    const emitResult = useEffectEvent((next) => options.onResult?.(next));
+    const emitError = useEffectEvent((code) => options.onError?.(code));
+    // Escape w celu zatrzymuje dyktowanie - jak na samym przycisku.
+    const onTargetKeydown = useRef((event) => {
+        if (event.key !== 'Escape')
+            return;
+        const session = sessionRef.current;
+        if (!session || session.status === 'idle' || session.status === 'error')
+            return;
+        event.preventDefault();
+        session.stop();
+    });
+    // Sesja żyje tyle, co komponent. Słuchacze wołają zdarzenia efektu - zawsze z najnowszymi
+    // propsami, bez odtwarzania sesji przy każdym renderze.
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const engine = browserSpeechEngine();
+        if (!engine)
+            return;
+        const releaseTarget = () => {
+            targetRef.current?.end();
+            targetRef.current = null;
+            targetElementRef.current?.removeEventListener('keydown', onTargetKeydown.current);
+            targetElementRef.current = null;
+            meterRef.current?.stop();
+            meterRef.current = null;
+            setLevels(NO_LEVELS);
+            setSpeaking(false);
+        };
+        const session = createSpeechSession({ engine }, { lang: 'en-US' }, {
+            status: (next) => {
+                setStatus(next);
+                if (next === 'starting')
+                    emitStart();
+            },
+            interim: (text) => targetRef.current?.interim(text),
+            commit: (text) => targetRef.current?.commit(text),
+            snapshot: (next) => {
+                setSnapshot(next);
+                emitResult(next);
+            },
+            speech: (active) => setSpeaking(active),
+            error: (code) => {
+                setError(code);
+                if (speechUnavailable())
+                    setUnavailable(true);
+                emitError(code);
+            },
+            end: (reason) => {
+                setLastEnd(reason);
+                releaseTarget();
+                emitEnd(reason);
+            },
+        });
+        sessionRef.current = session;
+        const offPageHidden = onSpeechPageHidden(() => session.stop());
+        return () => {
+            offPageHidden();
+            session.abort();
+            releaseTarget();
+            sessionRef.current = null;
+        };
+    }, [enabled]);
+    // Kontrolowane pole nadpisuje `value` stanem przy każdym renderze rodzica - a stan nie zna
+    // tekstu tymczasowego, więc React by go zmywał (przy fali na żywo co klatkę). Po każdym commicie,
+    // jeszcze przed malowaniem, cel przywraca tekst tymczasowy na swoje miejsce: nic nie mruga.
+    useLayoutEffect(() => {
+        targetRef.current?.refresh?.();
+    });
+    const start = () => {
+        const session = sessionRef.current;
+        if (!session || !support || !available || options.disabled)
+            return;
+        if (session.status !== 'idle' && session.status !== 'error')
+            return;
+        setError(null);
+        setLastEnd(null);
+        setMeterFailed(false);
+        setSnapshot(EMPTY_SNAPSHOT);
+        const raw = options.target;
+        const target = isRef(raw) ? raw.current : raw;
+        if (target) {
+            targetElementRef.current = target instanceof HTMLElement ? target : null;
+            targetElementRef.current?.addEventListener('keydown', onTargetKeydown.current);
+            const capitalize = options.capitalize ?? true;
+            targetRef.current = resolveSpeechTarget(target, options.interim ? { capitalize, interim: options.interim } : { capitalize });
+            targetRef.current.begin(options.mode ?? 'insert');
+        }
+        session.configure({
+            lang: options.lang ?? defaultSpeechLang(locale, globalThis.navigator?.language),
+            continuous: options.continuous ?? true,
+            processLocally: options.processLocally ?? false,
+            autoRestart: !support.ios,
+            silenceMs: options.silenceMs ?? 0,
+            maxDurationMs: options.maxDuration ?? 0,
+        });
+        // Miernik startuje jeszcze w geście kliknięcia - poza nim `AudioContext` jest zawieszony.
+        if (waveMode === 'live') {
+            meterRef.current = startSpeechMeter({
+                bars: options.bars ?? 5,
+                onLevels: (next) => setLevels(mirrorSpeechLevels(next)),
+                onFail: () => setMeterFailed(true),
+            });
+        }
+        session.start();
+    };
+    const stop = () => sessionRef.current?.stop();
+    const flush = () => sessionRef.current?.flush();
+    const abort = () => sessionRef.current?.abort();
+    const toggle = () => (listening ? stop() : start());
+    return {
+        status,
+        listening,
+        support,
+        available,
+        error,
+        lastEnd,
+        speaking,
+        levels,
+        waveMode,
+        snapshot,
+        start,
+        stop,
+        flush,
+        abort,
+        toggle,
+    };
+}