@konce-pt/react 0.11.2 → 0.14.0

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,
+    };
+}

package/dist/speed-dial/llms.txt

@@ -1,25 +1,25 @@
 # KptSpeedDial (@konce-pt/react)
 
-A speed dial — a FAB that fans out a set of actions. Built on `KptFab`.
+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>…
+          <button class="kpt-speed-dial__action" aria-label="Upload file">...</button>...
         </div>
-        <span class="kpt-fab-host"><button class="kpt-fab">…</button></span>
+        <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`)
+- `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
+- `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
@@ -37,6 +37,12 @@ present would swallow clicks meant for the page underneath.
 ## i18n
 `speedDial.actions` and `common.close`; `locale` and `dictionary` override them per instance.
 
+## Motion
+The actions fan out from the button in a cascade - the nearest first, on a spring, from the side of the
+button - and fold back in reverse order; the trigger icon turns on a spring. The container hides
+(`visibility`) only after the last action, so the closing cascade is not cut off. Pressed, it squeezes slightly and springs back on release (shared mixin `styles/_press.scss`). Pure CSS; durations follow `--kpt-motion-scale`, so `enabled: false` turns it off, and it drops out
+under "reduce motion".
+
 ## Tokens
 The main button comes from `KptFab`; the actions use `--kpt-color-surface-raised` and
 `--kpt-elevation-2`.
@@ -44,7 +50,7 @@ The main button comes from `KptFab`; the actions use `--kpt-color-surface-raised
 ## Accessibility
 - The main button carries `aria-expanded` and `aria-controls` pointing at the actions container.
 - Closed actions are `visibility: hidden` (switched after the fade-out), so they are out of the Tab
-  order and the accessibility tree — not just transparent.
+  order and the accessibility tree - not just transparent.
 - `Escape` anywhere in the dial closes it and returns focus to the main button.
 - 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

@@ -12,7 +12,7 @@ export interface KptSpeedDialProps<T> extends Omit<ComponentPropsWithRef<'div'>,
     onSelect?: (item: KptMenuItem<T>) => void;
 }
 /**
- * Speed dial — FAB rozwijający zestaw akcji wachlarzem. Buduje na `KptFab`.
+ * Speed dial - FAB rozwijający zestaw akcji wachlarzem. Buduje na `KptFab`.
  *
  * @example
  * <KptSpeedDial items={actions} direction="up" onSelect={onAction} />

package/dist/speed-dial/speed-dial.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
@@ -6,7 +7,7 @@ import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptFab } from "../fab/fab.js";
 import { KptIcon } from "../icon/icon.js";
 /**
- * Speed dial — FAB rozwijający zestaw akcji wachlarzem. Buduje na `KptFab`.
+ * Speed dial - FAB rozwijający zestaw akcji wachlarzem. Buduje na `KptFab`.
  *
  * @example
  * <KptSpeedDial items={actions} direction="up" onSelect={onAction} />
@@ -30,5 +31,5 @@ export function KptSpeedDial({ items = [], direction = 'up', icon = 'plus', aria
         onSelect?.(item);
         setOpen(false);
     };
-    return (_jsxs("div", { ref: hostRef, className: cn('kpt-speed-dial-host', className), onKeyDown: onKeyDown, ...rest, children: [_jsxs("div", { className: cn('kpt-speed-dial', open && 'is-open'), "data-direction": direction, children: [_jsx("div", { className: "kpt-speed-dial__actions", id: actionsId, children: items.map((item, index) => (_jsxs("button", { type: "button", className: "kpt-speed-dial__action", disabled: item.disabled, "aria-label": item.label, onClick: () => pick(item), children: [item.icon ? _jsx(KptIcon, { name: item.icon }) : null, item.label ? _jsx("span", { className: "kpt-speed-dial__label", children: item.label }) : null] }, index))) }), _jsx(KptFab, { "aria-label": open ? t('common.close') : (ariaLabel ?? t('speedDial.actions')), "aria-expanded": open, "aria-controls": actionsId, onClick: () => setOpen(!open), children: _jsx("span", { className: "kpt-speed-dial__trigger-icon", children: _jsx(KptIcon, { name: icon }) }) })] }), open ? _jsx("div", { className: "kpt-speed-dial__backdrop", onClick: () => setOpen(false) }) : null] }));
+    return (_jsxs("div", { ref: hostRef, className: cn('kpt-speed-dial-host', className), onKeyDown: onKeyDown, ...rest, children: [_jsxs("div", { className: cn('kpt-speed-dial', open && 'is-open'), "data-direction": direction, children: [_jsx("div", { className: "kpt-speed-dial__actions", id: actionsId, children: items.map((item, index) => (_jsxs("button", { type: "button", className: "kpt-speed-dial__action", disabled: item.disabled, "aria-label": item.label, onClick: () => pick(item), children: [item.icon ? _jsx(KptIcon, { name: item.icon }) : null, item.label ? _jsx("span", { className: "kpt-speed-dial__label", children: item.label }) : null] }, index))) }), _jsx(KptFab, { "aria-label": open ? t('common.close') : (ariaLabel ?? t('speedDial.actions')), "aria-expanded": open, "aria-controls": actionsId, onClick: () => setOpen(!open), children: _jsx("span", { className: "kpt-speed-dial__trigger-icon", children: _jsx(KptIcon, { name: icon }) }) })] }), open ? (_jsx("div", { className: "kpt-speed-dial__backdrop", onClick: () => setOpen(false) })) : null] }));
 }

package/dist/spinner/llms.txt

@@ -9,13 +9,13 @@ A loading indicator. Import: `import { KptSpinner } from '@konce-pt/react';`
     </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
+- `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 host sets `color: var(--kpt-color-primary)`, and the ring is drawn in `currentColor` — so the
+The host sets `color: var(--kpt-color-primary)`, and the ring is drawn in `currentColor` - so the
 spinner is primary by default, and anything that sets `color` on the host changes it. Pass
 `style={{ color: 'inherit' }}` (or a class) to take the colour of the text around it, e.g. inside a
 filled chip. There is no colour prop, on purpose.
@@ -23,15 +23,15 @@ filled chip. There is no colour prop, on purpose.
 ## Examples
     <KptSpinner />
     <KptSpinner size="2rem" label="Loading data" />
-    <KptButton disabled><KptSpinner size="1em" /> Saving…</KptButton>
+    <KptButton disabled><KptSpinner size="1em" /> Saving...</KptButton>
 
 ## Tokens
-None of its own — the colour is `--kpt-color-primary` on the host (drawn in `currentColor`), the
+None of its own - the colour is `--kpt-color-primary` on the host (drawn in `currentColor`), the
 size comes from the prop, the ring width is 8% of the size (at least 2px), the speed from
 `--kpt-motion-duration-*`.
 
 ## Accessibility
 The ring is `aria-hidden`; next to it sits a visually hidden `.kpt-spinner__label` with
-`role="status"`. Its text — `label`, or `spinner.label` — is written a frame after the spinner
+`role="status"`. Its text - `label`, or `spinner.label` - is written a frame after the spinner
 appears, because a status region that is born already filled in is skipped by most screen readers.
 Under `prefers-reduced-motion` the rotation slows down instead of stopping.

package/dist/spinner/spinner.d.ts

@@ -10,7 +10,7 @@ export interface KptSpinnerProps extends Omit<ComponentPropsWithRef<'span'>, 'ch
  *
  * Pierścień jest dekoracją (`aria-hidden`); dla czytnika jest osobny, wizualnie ukryty region
  * `role="status"` z etykietą. Tekst trafia do regionu klatkę po pojawieniu się spinnera: region,
- * który powstaje od razu z treścią, większość czytników przemilcza — ogłaszają dopiero zmianę.
+ * który powstaje od razu z treścią, większość czytników przemilcza - ogłaszają dopiero zmianę.
  *
  * @example
  * <KptSpinner />

package/dist/spinner/spinner.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { cn } from "../internal/cn.js";
@@ -7,7 +8,7 @@ import { useKptMessages } from "../i18n/i18n-context.js";
  *
  * Pierścień jest dekoracją (`aria-hidden`); dla czytnika jest osobny, wizualnie ukryty region
  * `role="status"` z etykietą. Tekst trafia do regionu klatkę po pojawieniu się spinnera: region,
- * który powstaje od razu z treścią, większość czytników przemilcza — ogłaszają dopiero zmianę.
+ * który powstaje od razu z treścią, większość czytników przemilcza - ogłaszają dopiero zmianę.
  *
  * @example
  * <KptSpinner />

package/dist/split-button/llms.txt

@@ -1,37 +1,37 @@
 # KptSplitButton (@konce-pt/react)
 
-A split button — a primary action plus a dropdown of further actions.
+A split button - a primary action plus a dropdown of further actions.
 Import: `import { KptSplitButton } from '@konce-pt/react';`
 
 ## DOM
     <span class="kpt-split-button-host">
       <div class="kpt-split-button" data-variant="filled">
         <button class="kpt-split-button__main" type="button">Save</button>
-        <button class="kpt-split-button__toggle" type="button" aria-label="More actions">…chevron…</button>
+        <button class="kpt-split-button__toggle" type="button" aria-label="More actions">...chevron...</button>
       </div>
     </span>
     <!-- while open, in a portal: -->
-    <div class="kpt-split-button__panel" role="menu">…rows…</div>
+    <div class="kpt-split-button__panel" role="menu">...rows...</div>
 
 ## Props
-- `variant`: `KptSplitButtonVariant` = 'filled' | 'tonal' | 'outline' | 'text' (default 'filled') —
+- `variant`: `KptSplitButtonVariant` = 'filled' | 'tonal' | 'outline' | 'text' (default 'filled') -
   the subset of `KptButtonVariant` that has a style; `outline` and `text` use the `--kpt-button-outline-*`
   and `--kpt-button-text-*` tokens, so they match `kpt-button` in the same row
-- `items`: `KptMenuItem<T>[]` — the same shape as `KptMenu`
-- `disabled`: boolean — disables both buttons
-- `onPrimaryClick()` — the main action
-- `onSelect(item)` — a pick from the menu
-- `open` / `defaultOpen` / `onOpenChange` — the panel state
-- `children` — the content of the main action
-- `locale`, `dictionary` — i18n overrides for this component only
+- `items`: `KptMenuItem<T>[]` - the same shape as `KptMenu`
+- `disabled`: boolean - disables both buttons
+- `onPrimaryClick()` - the main action
+- `onSelect(item)` - a pick from the menu
+- `open` / `defaultOpen` / `onOpenChange` - the panel state
+- `children` - the content of the main action
+- `locale`, `dictionary` - i18n overrides for this component only
 
 ## The panel aligns to the right
 The toggle sits on the right-hand side of the control, so the panel is anchored by its RIGHT edge
 (`align="end"` on the overlay). Anchored to the left it would hang off the control instead of under
-it — the same reasoning the Angular port encodes in its CDK position list.
+it - the same reasoning the Angular port encodes in its CDK position list.
 
 ## Shared rows
-The panel renders the same rows as `KptMenu` — icons, descriptions, badges, separators, headers and
+The panel renders the same rows as `KptMenu` - icons, descriptions, badges, separators, headers and
 the `danger` modifier all behave identically, only the BEM block differs.
 
 ## i18n
@@ -39,9 +39,9 @@ The toggle's label comes from `splitButton.more` in the dictionary.
 
 ## Keyboard
 The toggle is a menu button: `aria-haspopup="menu"`, a live `aria-expanded`, `aria-controls` while
-open. `↓` / `↑` on it open the menu on the first / last item; inside, `↓` / `↑` wrap, `Home` / `End`
+open. `ArrowDown` / `ArrowUp` on it open the menu on the first / last item; inside, `ArrowDown` / `ArrowUp` wrap, `Home` / `End`
 jump, `Escape` / `Tab` close, and closing or picking returns focus to the toggle. Same rules as the
-menu — see the `KptMenu` docs.
+menu - see the `KptMenu` docs.
 
 ## Examples
     <KptSplitButton items={items} onPrimaryClick={save} onSelect={onItem}>Save</KptSplitButton>
@@ -53,6 +53,12 @@ menu — see the `KptMenu` docs.
       { label: 'Discard', value: 'discard', danger: true },
     ];
 
+## Motion
+Pressing either part squeezes the whole pill (one part alone would come apart from the other inside
+the clipped container); the arrow turns over when the menu opens and the menu slides out from under the
+button. Pure CSS; durations follow `--kpt-motion-scale`, so `enabled: false` turns it off, and it drops out
+under "reduce motion".
+
 ## Tokens
 The `--kpt-button-*` tokens of the chosen variant, plus `--kpt-color-surface-raised` and
 `--kpt-elevation-3` for the panel.

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

@@ -2,7 +2,7 @@ import { type ComponentPropsWithRef, type ReactNode } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptMenuItem } from '../menu/menu-item.ts';
 import type { KptButtonVariant } from '../button/button.tsx';
-/** Warianty, które mają styl — podzbiór `KptButtonVariant`. */
+/** Warianty, które mają styl - podzbiór `KptButtonVariant`. */
 export type KptSplitButtonVariant = Extract<KptButtonVariant, 'filled' | 'tonal' | 'outline' | 'text'>;
 export interface KptSplitButtonProps<T> extends Omit<ComponentPropsWithRef<'span'>, 'onSelect'>, KptI18nOverrides {
     variant?: KptSplitButtonVariant;
@@ -19,7 +19,7 @@ export interface KptSplitButtonProps<T> extends Omit<ComponentPropsWithRef<'span
     children?: ReactNode;
 }
 /**
- * Przycisk dzielony — akcja główna plus rozwijane menu dodatkowych akcji.
+ * Przycisk dzielony - akcja główna plus rozwijane menu dodatkowych akcji.
  *
  * Panel wyrównuje się do PRAWEJ krawędzi przycisku, nie do lewej: rozwijacz siedzi po prawej
  * stronie kontrolki, więc menu otwierające się w lewo nie wychodzi poza nią.

package/dist/split-button/split-button.js

@@ -1,5 +1,6 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
@@ -9,7 +10,7 @@ import { KptIcon } from "../icon/icon.js";
 import { MenuRows } from "../menu/menu-rows.js";
 import { focusMenuEdge, handleMenuKeydown } from "../menu/menu-keys.js";
 /**
- * Przycisk dzielony — akcja główna plus rozwijane menu dodatkowych akcji.
+ * Przycisk dzielony - akcja główna plus rozwijane menu dodatkowych akcji.
  *
  * Panel wyrównuje się do PRAWEJ krawędzi przycisku, nie do lewej: rozwijacz siedzi po prawej
  * stronie kontrolki, więc menu otwierające się w lewo nie wychodzi poza nią.
@@ -20,8 +21,14 @@ import { focusMenuEdge, handleMenuKeydown } from "../menu/menu-keys.js";
 export function KptSplitButton({ variant = 'filled', items = [], disabled = false, onPrimaryClick, onSelect, open, defaultOpen = false, onOpenChange, locale, dictionary, className, children, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const toggleRef = useRef(null);
+    /** Kotwica panelu - w stanie, bo czyta ją render; ref zostaje dla przywracania fokusu. */
+    const [toggleEl, setToggleEl] = useState(null);
+    const setToggle = useCallback((element) => {
+        toggleRef.current = element;
+        setToggleEl(element);
+    }, []);
     const panelRef = useRef(null);
-    /** Którą pozycję skupić po otwarciu — strzałka w górę na przycisku otwiera „od końca”. */
+    /** Którą pozycję skupić po otwarciu - strzałka w górę na przycisku otwiera "od końca". */
     const focusEdge = useRef('first');
     const panelId = useKptId(undefined, 'kpt-split-button-menu');
     const [isOpen, setOpen] = useControllableState({
@@ -41,7 +48,7 @@ export function KptSplitButton({ variant = 'filled', items = [], disabled = fals
         });
         return () => cancelAnimationFrame(frame);
     }, [isOpen]);
-    /** Fokus wraca na strzałkę — inaczej po zniknięciu panelu spadłby na `<body>`. */
+    /** Fokus wraca na strzałkę - inaczej po zniknięciu panelu spadłby na `<body>`. */
     const closeAndRestoreFocus = () => {
         close();
         toggleRef.current?.focus();
@@ -67,8 +74,8 @@ export function KptSplitButton({ variant = 'filled', items = [], disabled = fals
         onSelect?.(item);
         closeAndRestoreFocus();
     };
-    return (_jsxs("span", { className: cn('kpt-split-button-host', className), ...rest, children: [_jsxs("div", { className: "kpt-split-button", "data-variant": variant, children: [_jsx("button", { className: "kpt-split-button__main", type: "button", disabled: disabled, onClick: onPrimaryClick, children: children }), _jsx("button", { ref: toggleRef, className: "kpt-split-button__toggle", type: "button", disabled: disabled, onClick: () => {
+    return (_jsxs("span", { className: cn('kpt-split-button-host', className), ...rest, children: [_jsxs("div", { className: "kpt-split-button", "data-variant": variant, children: [_jsx("button", { className: "kpt-split-button__main", type: "button", disabled: disabled, onClick: onPrimaryClick, children: children }), _jsx("button", { ref: setToggle, className: "kpt-split-button__toggle", type: "button", disabled: disabled, onClick: () => {
                             focusEdge.current = 'first';
                             setOpen(!isOpen);
-                        }, onKeyDown: onToggleKeyDown, "aria-haspopup": "menu", "aria-expanded": isOpen, "aria-controls": isOpen ? panelId : undefined, "aria-label": t('splitButton.more'), children: _jsx(KptIcon, { name: "chevron-down" }) })] }), _jsx(KptOverlay, { open: isOpen, anchor: toggleRef.current, onClose: close, align: "end", children: _jsx("div", { ref: panelRef, id: panelId, className: "kpt-split-button__panel", role: "menu", onKeyDown: onPanelKeyDown, children: _jsx(MenuRows, { items: items, block: "kpt-split-button", onPick: pick }) }) })] }));
+                        }, onKeyDown: onToggleKeyDown, "aria-haspopup": "menu", "aria-expanded": isOpen, "aria-controls": isOpen ? panelId : undefined, "aria-label": t('splitButton.more'), children: _jsx(KptIcon, { name: "chevron-down" }) })] }), _jsx(KptOverlay, { open: isOpen, anchor: toggleEl, onClose: close, align: "end", children: _jsx("div", { ref: panelRef, id: panelId, className: "kpt-split-button__panel", role: "menu", tabIndex: -1, onKeyDown: onPanelKeyDown, children: _jsx(MenuRows, { items: items, block: "kpt-split-button", onPick: pick }) }) })] }));
 }

package/dist/splitter/llms.txt

@@ -6,22 +6,22 @@ Import: `import { KptSplitter } from '@konce-pt/react';`
 ## DOM
     <div class="kpt-splitter-host">
       <div class="kpt-splitter" data-orientation="horizontal">
-        <div class="kpt-splitter__pane" id="kpt-splitter-start-r1" style="flex-basis:40%">…</div>
+        <div class="kpt-splitter__pane" id="kpt-splitter-start-r1" style="flex-basis:40%">...</div>
         <div class="kpt-splitter__gutter" role="separator" tabindex="0" aria-orientation="vertical"
              aria-valuenow="40" aria-valuemin="10" aria-valuemax="90"
              aria-controls="kpt-splitter-start-r1" aria-label="Resize panes"></div>
-        <div class="kpt-splitter__pane" style="flex-basis:60%">…</div>
+        <div class="kpt-splitter__pane" style="flex-basis:60%">...</div>
       </div>
     </div>
 
 ## Props
 - `orientation`: `'horizontal'` (default) | `'vertical'`
-- `startSize` / `defaultStartSize` / `onStartSizeChange` — the first pane's size in percent
-- `minSize`: number (percent, default 10) — neither pane goes below it
-- `ariaLabel`: string — the handle's name; empty = `splitter.resize` from the dictionary
-- `ariaLabel`: string — the handle's name; empty = `splitter.resize` from the dictionary
-- `ariaLabel`: string — the handle's name; empty = `splitter.resize` from the dictionary
-- `ariaLabel`: string — the handle's name; empty = `splitter.resize` from the dictionary
+- `startSize` / `defaultStartSize` / `onStartSizeChange` - the first pane's size in percent
+- `minSize`: number (percent, default 10) - neither pane goes below it
+- `ariaLabel`: string - the handle's name; empty = `splitter.resize` from the dictionary
+- `ariaLabel`: string - the handle's name; empty = `splitter.resize` from the dictionary
+- `ariaLabel`: string - the handle's name; empty = `splitter.resize` from the dictionary
+- `ariaLabel`: string - the handle's name; empty = `splitter.resize` from the dictionary
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Panes
@@ -39,16 +39,16 @@ pointer outruns a 6px strip, and a handle-bound listener would drop the drag aft
       <KptSplitter.End>Right</KptSplitter.End>
     </KptSplitter>
 
-    <KptSplitter orientation="vertical" defaultStartSize={30} minSize={20}>…</KptSplitter>
+    <KptSplitter orientation="vertical" defaultStartSize={30} minSize={20}>...</KptSplitter>
 
 ## Tokens
-The handle `--kpt-color-border` → `--kpt-color-primary` on hover and focus; the frame
+The handle `--kpt-color-border` -> `--kpt-color-primary` on hover and focus; the frame
 `--kpt-color-border` with `--kpt-radius-md`.
 
 ## Accessibility
 The handle is a focusable `role="separator"` (the WAI-ARIA window splitter): `aria-valuenow`,
 `aria-valuemin`/`aria-valuemax` (from `minSize`), `aria-controls` pointing at the first pane, and a
 name from `ariaLabel` or `splitter.resize` in the dictionary. Arrow keys resize by 2%, `Home`/`End`
-jump to the minimum/maximum. `aria-orientation` describes the handle's line, not the layout —
+jump to the minimum/maximum. `aria-orientation` describes the handle's line, not the layout -
 side-by-side panes have a vertical handle. The host takes `height: 100%`, so a height set on the
 parent reaches the panes.

package/dist/splitter/splitter.d.ts

@@ -15,7 +15,7 @@ export declare namespace KptSplitterEnd {
 }
 export interface KptSplitterProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange'>, KptI18nOverrides {
     orientation?: KptSplitterOrientation;
-    /** Rozmiar pierwszego panelu w procentach (0–100). */
+    /** Rozmiar pierwszego panelu w procentach (0-100). */
     startSize?: number;
     defaultStartSize?: number;
     onStartSizeChange?: (size: number) => void;
@@ -29,9 +29,9 @@ export interface KptSplitterProps extends Omit<ComponentPropsWithRef<'div'>, 'on
  * Dwa panele z przeciąganym uchwytem. `horizontal` stawia je obok siebie, `vertical` jeden pod
  * drugim.
  *
- * Uchwyt to `role="separator"` z wartością (wzorzec WAI-ARIA „window splitter”): strzałki
+ * Uchwyt to `role="separator"` z wartością (wzorzec WAI-ARIA "window splitter"): strzałki
  * przesuwają go o 2%, `Home`/`End` dosuwają do minimum i maksimum. `aria-orientation` opisuje
- * linię uchwytu, nie układ — przy panelach obok siebie linia jest pionowa.
+ * linię uchwytu, nie układ - przy panelach obok siebie linia jest pionowa.
  *
  * @example
  * <KptSplitter startSize={size} onStartSizeChange={setSize}>