@konce-pt/react 0.9.0 → 0.10.0

package/dist/select/select.d.ts

@@ -8,6 +8,10 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
     multiple?: boolean;
     /** Pole wyszukiwania nad listą. */
     filter?: boolean;
+    /** Id wyzwalacza; bez niego generowane, w `KptFormField` — z wrappera. */
+    id?: string;
+    /** Oznacza pole jako wymagane atrybutem `aria-required`. */
+    required?: boolean;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -26,6 +30,13 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
  * Lista wyboru (select) na własnym panelu. Warianty: pojedynczy, z wyszukiwarką (`filter`)
  * i wielokrotny (`multiple`, chipy).
  *
+ * Klawiatura według wzorca WAI-ARIA „select-only combobox”: fokus zostaje na polu, a aktywna opcja
+ * idzie przez `aria-activedescendant`. `↓`/`↑`/`Enter`/`Spacja` otwierają listę na wybranej opcji,
+ * strzałki, `Home`/`End`, `PageUp`/`PageDown` chodzą po opcjach (z pominięciem wyłączonych),
+ * wpisywane litery skaczą do pasującej opcji (bez polskich znaków), `Enter` wybiera, `Escape`
+ * zamyka. Z `filter` fokus przechodzi do pola wyszukiwania, które obsługuje te same klawisze.
+ * W trybie `multiple` `Backspace` na zamkniętym polu usuwa ostatni wybór.
+ *
  * Wewnątrz `KptFormField` zgłasza wypełnienie hookiem `useKptFormFieldFilled`, więc etykieta
  * Float Label unosi się nad wybraną wartością — natywnego pola, z którego wrapper mógłby to
  * odczytać, tu nie ma.
@@ -34,4 +45,4 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
  * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz…" />
  * <KptSelect options={tags} multiple filter value={tags} onValueChange={setTags} />
  */
-export declare function KptSelect<T>({ options, placeholder, multiple, filter, disabled, invalid, touched, value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, onTouch, locale, dictionary, className, onBlur, ...rest }: Readonly<KptSelectProps<T>>): import("react").JSX.Element;
+export declare function KptSelect<T>({ options, placeholder, multiple, filter, disabled, invalid, touched, value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, onTouch, locale, dictionary, className, onBlur, id, required, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptSelectProps<T>>): import("react").JSX.Element;

package/dist/select/select.js

@@ -3,13 +3,22 @@ import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
 import { cn } from "../internal/cn.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
+import { useKptId } from "../internal/use-id.js";
+import { KptTypeahead, OPTION_NAV_KEYS, isTypeaheadKey, nextOptionIndex, typeaheadIndex } from "../internal/option-nav.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
-import { useKptFormFieldFilled } from "../form-field/form-field-context.js";
+import { joinIds, useKptFieldA11y, useKptFormFieldFilled } from "../form-field/form-field-context.js";
 import { KptIcon } from "../icon/icon.js";
 /**
  * Lista wyboru (select) na własnym panelu. Warianty: pojedynczy, z wyszukiwarką (`filter`)
  * i wielokrotny (`multiple`, chipy).
  *
+ * Klawiatura według wzorca WAI-ARIA „select-only combobox”: fokus zostaje na polu, a aktywna opcja
+ * idzie przez `aria-activedescendant`. `↓`/`↑`/`Enter`/`Spacja` otwierają listę na wybranej opcji,
+ * strzałki, `Home`/`End`, `PageUp`/`PageDown` chodzą po opcjach (z pominięciem wyłączonych),
+ * wpisywane litery skaczą do pasującej opcji (bez polskich znaków), `Enter` wybiera, `Escape`
+ * zamyka. Z `filter` fokus przechodzi do pola wyszukiwania, które obsługuje te same klawisze.
+ * W trybie `multiple` `Backspace` na zamkniętym polu usuwa ostatni wybór.
+ *
  * Wewnątrz `KptFormField` zgłasza wypełnienie hookiem `useKptFormFieldFilled`, więc etykieta
  * Float Label unosi się nad wybraną wartością — natywnego pola, z którego wrapper mógłby to
  * odczytać, tu nie ma.
@@ -18,9 +27,16 @@ import { KptIcon } from "../icon/icon.js";
  * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz…" />
  * <KptSelect options={tags} multiple filter value={tags} onValueChange={setTags} />
  */
-export function KptSelect({ options = [], placeholder = '', multiple = false, filter = false, disabled = false, invalid = false, touched, value, defaultValue = null, onValueChange, open, defaultOpen = false, onOpenChange, onTouch, locale, dictionary, className, onBlur, ...rest }) {
+export function KptSelect({ options = [], placeholder = '', multiple = false, filter = false, disabled = false, invalid = false, touched, value, defaultValue = null, onValueChange, open, defaultOpen = false, onOpenChange, onTouch, locale, dictionary, className, onBlur, id, required = false, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }) {
+    /** `div` z rolą nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
+    const field = useKptFieldA11y(id, 'kpt-select-trigger');
     const { t } = useKptMessages({ locale, dictionary });
     const triggerRef = useRef(null);
+    const searchRef = useRef(null);
+    const typeahead = useRef(new KptTypeahead());
+    const uid = useKptId(undefined, 'kpt-select');
+    const listId = `${uid}-list`;
+    const optionId = (index) => `${uid}-opt-${index}`;
     const [current, setCurrent] = useControllableState({
         value,
         defaultValue,
@@ -33,14 +49,6 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
     });
     const [filterText, setFilterText] = useState('');
     const [activeIndex, setActiveIndex] = useState(-1);
-    // Panel może zostać otwarty także z zewnątrz (`open`), nie tylko klikiem w trigger —
-    // filtr i aktywną pozycję resetujemy więc przy każdym otwarciu, nie przy przełączaniu.
-    useEffect(() => {
-        if (!isOpen)
-            return;
-        setFilterText('');
-        setActiveIndex(-1);
-    }, [isOpen]);
     const showInvalid = invalid && (touched ?? true);
     const selectedValues = useMemo(() => {
         if (multiple)
@@ -48,19 +56,47 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
         return current == null ? [] : [current];
     }, [current, multiple]);
     const selectedOptions = useMemo(() => options.filter((option) => selectedValues.includes(option.value)), [options, selectedValues]);
-    const filteredOptions = useMemo(() => {
-        const q = filterText.trim().toLowerCase();
+    const filterOptions = (text) => {
+        const q = text.trim().toLowerCase();
         return q ? options.filter((option) => option.label.toLowerCase().includes(q)) : options;
-    }, [options, filterText]);
+    };
+    const filteredOptions = useMemo(() => filterOptions(filterText), [options, filterText]); // eslint-disable-line react-hooks/exhaustive-deps
+    const disabledMap = filteredOptions.map((option) => !!option.disabled);
     const filled = selectedOptions.length > 0;
     useKptFormFieldFilled(filled);
     const isSelected = (option) => selectedValues.includes(option.value);
+    // Panel może zostać otwarty także z zewnątrz (`open`), nie tylko z pola — filtr i aktywną
+    // pozycję ustawiamy więc przy każdym otwarciu. Lista otwiera się na wybranej opcji; z `filter`
+    // fokus idzie do wyszukiwarki (klatkę później: `KptOverlay` mierzy panel w `visibility: hidden`).
+    // Tylko na otwarcie — zmiana wyboru w trybie `multiple` nie może przesuwać aktywnej opcji.
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        setFilterText('');
+        const selected = options.findIndex((option) => selectedValues.includes(option.value));
+        const firstEnabled = nextOptionIndex(options.map((o) => !!o.disabled), -1, 'ArrowDown') ?? -1;
+        setActiveIndex(selected >= 0 ? selected : firstEnabled);
+        if (!filter)
+            return;
+        const frame = requestAnimationFrame(() => searchRef.current?.focus());
+        return () => cancelAnimationFrame(frame);
+    }, [isOpen]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Aktywna opcja zawsze w polu widzenia listy.
+    useEffect(() => {
+        if (isOpen && activeIndex >= 0)
+            document.getElementById(`${uid}-opt-${activeIndex}`)?.scrollIntoView({ block: 'nearest' });
+    }, [isOpen, activeIndex, uid]);
     const close = useCallback(() => {
         if (!isOpen)
             return;
         setOpen(false);
         onTouch?.();
     }, [isOpen, setOpen, onTouch]);
+    /** Zamknięcie z powrotem fokusu na pole — po wyborze, `Escape`, `Tab` w wyszukiwarce. */
+    const closeAndFocus = () => {
+        close();
+        triggerRef.current?.focus();
+    };
     const pick = (option) => {
         if (option.disabled)
             return;
@@ -69,49 +105,85 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
         }
         else {
             setCurrent(option.value);
-            close();
+            closeAndFocus();
         }
     };
-    const onTriggerKeyDown = (event) => {
+    const jumpTo = (char) => {
+        const labels = filteredOptions.map((option) => option.label);
+        const found = typeaheadIndex(labels, disabledMap, activeIndex, typeahead.current.push(char));
+        if (found !== null)
+            setActiveIndex(found);
+    };
+    /** Jeden obsługiwacz dla pola i dla wyszukiwarki w panelu — różnią się tylko `Spacją` i `Tab`. */
+    const onKeyDown = (event, source) => {
         if (disabled)
             return;
-        if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
-            event.preventDefault();
-            if (!isOpen)
+        const key = event.key;
+        if (!isOpen) {
+            if (['ArrowDown', 'ArrowUp', 'Enter', ' ', 'Home', 'End'].includes(key)) {
+                event.preventDefault();
                 setOpen(true);
+                if (key === 'ArrowUp' || key === 'End' || key === 'Home') {
+                    // Efekt otwarcia ustawia wybraną opcję; skrajne klawisze nadpisują to klatkę później.
+                    const target = nextOptionIndex(disabledMap, -1, key === 'Home' ? 'Home' : 'End');
+                    requestAnimationFrame(() => {
+                        if (target !== null)
+                            setActiveIndex(target);
+                    });
+                }
+            }
+            else if ((key === 'Backspace' || key === 'Delete') && multiple && selectedValues.length) {
+                event.preventDefault();
+                setCurrent(selectedValues.slice(0, -1));
+            }
+            else if (isTypeaheadKey(event.nativeEvent) && !filter) {
+                setOpen(true);
+                jumpTo(key);
+            }
+            return;
         }
-        else if (event.key === 'Escape') {
-            close();
-        }
-    };
-    const onPanelKeyDown = (event) => {
-        if (event.key === 'Escape') {
+        if (key === 'Escape') {
             event.preventDefault();
-            close();
+            closeAndFocus();
         }
-        else if (event.key === 'ArrowDown') {
-            event.preventDefault();
-            setActiveIndex((index) => Math.min(index + 1, filteredOptions.length - 1));
+        else if (key === 'Tab') {
+            // Z wyszukiwarki (w portalu na końcu strony) Tab uciekłby w próżnię — wracamy na pole.
+            if (source === 'search') {
+                event.preventDefault();
+                closeAndFocus();
+            }
+            else {
+                close();
+            }
         }
-        else if (event.key === 'ArrowUp') {
+        else if (OPTION_NAV_KEYS.has(key)) {
             event.preventDefault();
-            setActiveIndex((index) => Math.max(index - 1, 0));
+            const next = nextOptionIndex(disabledMap, activeIndex, key);
+            if (next !== null)
+                setActiveIndex(next);
         }
-        else if (event.key === 'Enter') {
+        else if (key === 'Enter' || (key === ' ' && source === 'trigger')) {
             event.preventDefault();
             const option = filteredOptions[activeIndex];
-            if (option)
+            if (option && !option.disabled)
                 pick(option);
         }
+        else if (source === 'trigger' && isTypeaheadKey(event.nativeEvent)) {
+            jumpTo(key);
+        }
     };
-    return (_jsxs("span", { className: "kpt-select-host", children: [_jsxs("div", { ref: triggerRef, className: cn('kpt-select', isOpen && 'kpt-select--open', disabled && 'kpt-select--disabled', showInvalid && 'kpt-select--invalid', className), role: "combobox", tabIndex: 0, "aria-expanded": isOpen, "aria-disabled": disabled || undefined, onClick: () => !disabled && setOpen(!isOpen), onKeyDown: onTriggerKeyDown, onBlur: (event) => {
+    return (_jsxs("span", { className: "kpt-select-host", children: [_jsxs("div", { ref: triggerRef, className: cn('kpt-select', isOpen && 'kpt-select--open', disabled && 'kpt-select--disabled', showInvalid && 'kpt-select--invalid', className), role: "combobox", id: field.id, tabIndex: 0, "aria-haspopup": "listbox", "aria-label": ariaLabel, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), "aria-required": required || undefined, "aria-expanded": isOpen, "aria-controls": isOpen ? listId : undefined, "aria-activedescendant": isOpen && !filter && activeIndex >= 0 ? optionId(activeIndex) : undefined, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, onClick: () => !disabled && setOpen(!isOpen), onKeyDown: (event) => onKeyDown(event, 'trigger'), onBlur: (event) => {
                     onBlur?.(event);
-                    onTouch?.();
-                }, ...rest, children: [_jsx("div", { className: "kpt-select__value", children: multiple && selectedOptions.length ? (selectedOptions.map((option) => (_jsxs("span", { className: "kpt-select__chip", children: [option.label, _jsx("button", { type: "button", className: "kpt-select__chip-remove", "aria-label": t('select.removeChip'), onClick: (event) => {
+                    // Przy otwartym panelu fokus idzie do pola szukania — „dotknięcie” wyśle dopiero zamknięcie.
+                    if (!isOpen)
+                        onTouch?.();
+                }, ...rest, children: [_jsx("div", { className: "kpt-select__value", children: multiple && selectedOptions.length ? (selectedOptions.map((option) => (_jsxs("span", { className: "kpt-select__chip", children: [option.label, _jsx("button", { type: "button", className: "kpt-select__chip-remove", tabIndex: -1, "aria-label": `${t('select.removeChip')}: ${option.label}`, onClick: (event) => {
                                         event.stopPropagation();
                                         setCurrent(selectedValues.filter((v) => v !== option.value));
-                                    }, children: _jsx(KptIcon, { name: "x" }) })] }, String(option.value))))) : !multiple && filled ? (_jsx("span", { className: "kpt-select__single", children: selectedOptions[0]?.label })) : (_jsx("span", { className: "kpt-select__placeholder", children: placeholder })) }), _jsx(KptIcon, { className: "kpt-select__chevron", name: "chevron-down" })] }), _jsx(KptOverlay, { open: isOpen, anchor: triggerRef.current, onClose: close, matchAnchorWidth: true, children: _jsxs("div", { className: "kpt-select__panel", onKeyDown: onPanelKeyDown, children: [filter ? (_jsxs("div", { className: "kpt-select__search", children: [_jsx(KptIcon, { name: "search" }), _jsx("input", { type: "text", className: "kpt-select__search-input", value: filterText, placeholder: t('select.search'), autoFocus: true, onChange: (event) => {
+                                    }, children: _jsx(KptIcon, { name: "x" }) })] }, String(option.value))))) : !multiple && filled ? (_jsx("span", { className: "kpt-select__single", children: selectedOptions[0]?.label })) : (_jsx("span", { className: "kpt-select__placeholder", children: placeholder })) }), _jsx(KptIcon, { className: "kpt-select__chevron", name: "chevron-down" })] }), _jsx(KptOverlay, { open: isOpen, anchor: triggerRef.current, onClose: close, matchAnchorWidth: true, children: _jsxs("div", { className: "kpt-select__panel", children: [filter ? (_jsxs("div", { className: "kpt-select__search", children: [_jsx(KptIcon, { name: "search" }), _jsx("input", { ref: searchRef, type: "text", className: "kpt-select__search-input", role: "combobox", "aria-autocomplete": "list", "aria-expanded": true, "aria-controls": listId, "aria-activedescendant": activeIndex >= 0 ? optionId(activeIndex) : undefined, "aria-label": t('select.search'), value: filterText, placeholder: t('select.search'), onKeyDown: (event) => onKeyDown(event, 'search'), onChange: (event) => {
                                         setFilterText(event.target.value);
-                                        setActiveIndex(-1);
-                                    } })] })) : null, _jsx("ul", { className: "kpt-select__list", role: "listbox", "aria-multiselectable": multiple, children: filteredOptions.length ? (filteredOptions.map((option, index) => (_jsxs("li", { className: cn('kpt-select__option', isSelected(option) && 'kpt-select__option--selected', index === activeIndex && 'kpt-select__option--active', option.disabled && 'kpt-select__option--disabled'), role: "option", "aria-selected": isSelected(option), onClick: () => pick(option), onMouseEnter: () => setActiveIndex(index), children: [multiple ? (_jsx("span", { className: cn('kpt-select__check', isSelected(option) && 'is-on'), children: _jsx(KptIcon, { name: "check" }) })) : null, _jsx("span", { className: "kpt-select__option-label", children: option.label }), !multiple && isSelected(option) ? (_jsx(KptIcon, { className: "kpt-select__option-tick", name: "check" })) : null] }, String(option.value))))) : (_jsx("li", { className: "kpt-select__empty", children: t('select.noResults') })) })] }) })] }));
+                                        // Po zawężeniu aktywna jest pierwsza pasująca opcja — `Enter` wybiera ją od razu.
+                                        const narrowed = filterOptions(event.target.value).map((o) => !!o.disabled);
+                                        setActiveIndex(nextOptionIndex(narrowed, -1, 'ArrowDown') ?? -1);
+                                    } })] })) : null, _jsx("ul", { className: "kpt-select__list", role: "listbox", id: listId, "aria-multiselectable": multiple, "aria-label": ariaLabel, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, children: filteredOptions.length ? (filteredOptions.map((option, index) => (_jsxs("li", { id: optionId(index), className: cn('kpt-select__option', isSelected(option) && 'kpt-select__option--selected', index === activeIndex && 'kpt-select__option--active', option.disabled && 'kpt-select__option--disabled'), role: "option", "aria-selected": isSelected(option), "aria-disabled": option.disabled || undefined, onMouseDown: (event) => event.preventDefault(), onClick: () => pick(option), onMouseEnter: () => setActiveIndex(index), children: [multiple ? (_jsx("span", { className: cn('kpt-select__check', isSelected(option) && 'is-on'), children: _jsx(KptIcon, { name: "check" }) })) : null, _jsx("span", { className: "kpt-select__option-label", children: option.label }), !multiple && isSelected(option) ? (_jsx(KptIcon, { className: "kpt-select__option-tick", name: "check" })) : null] }, String(option.value))))) : (_jsx("li", { className: "kpt-select__empty", role: "status", children: t('select.noResults') })) })] }) })] }));
 }

package/dist/sidenav/llms.txt

@@ -44,6 +44,12 @@ attribute names in CSS selectors are case-insensitive in HTML, so one rule serve
 the components rather than writing the attribute by hand — JSX rejects an unknown camelCase
 attribute, and a hand-written one is easy to misspell.
 
+## Links
+Links in the scroll area are `display: flex` with a gap, so an icon and a label never glue together
+even when the template compiler drops the whitespace between them. A link with
+`aria-current="page"` gets the muted background and a medium weight — mark the current page
+yourself, the component does not know which one it is.
+
 ## Tokens
 `--kpt-sidenav-bg`, `--kpt-sidenav-fg`, `--kpt-sidenav-border`, plus `--kpt-sidenav-width` and
 `--kpt-sidenav-rail-width`, which are read by `KptAppShell`.

package/dist/skeleton/llms.txt

@@ -17,7 +17,8 @@ Import: `import { KptSkeleton } from '@konce-pt/react';`
 
 ## The last line is shorter
 In the `text` variant the last line is 60% wide. A stack of full-width rectangles does not read as
-a paragraph, and a paragraph is exactly what it stands in for.
+a paragraph, and a paragraph is exactly what it stands in for. A single line (`lines={1}`) keeps
+the full `width` — there is no paragraph to imitate.
 
 ## Examples
     <KptSkeleton variant="text" lines={3} />
@@ -25,7 +26,7 @@ a paragraph, and a paragraph is exactly what it stands in for.
     <KptSkeleton variant="rect" width="100%" height="8rem" />
 
 ## Tokens
-`--kpt-color-muted` and `--kpt-color-surface` for the shimmer gradient, `--kpt-radius-md`.
+The base `--kpt-color-muted`; the shimmer is a lighter band mixed with `--kpt-color-surface`; corners `--kpt-radius-md` (blocks) / `--kpt-radius-sm` (text lines).
 
 ## Accessibility
 The host is `aria-hidden="true"` — a placeholder has nothing to announce, and reading out empty

package/dist/skeleton/skeleton.d.ts

@@ -11,7 +11,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
- * właśnie akapit ma udawać.
+ * właśnie akapit ma udawać. Przy jednej linii nie ma czego udawać, więc ta ma pełną szerokość.
  *
  * @example
  * <KptSkeleton variant="text" lines={3} />

package/dist/skeleton/skeleton.js

@@ -4,12 +4,12 @@ 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
- * właśnie akapit ma udawać.
+ * właśnie akapit ma udawać. Przy jednej linii nie ma czego udawać, więc ta ma pełną szerokość.
  *
  * @example
  * <KptSkeleton variant="text" lines={3} />
  * <KptSkeleton variant="circle" width="3rem" height="3rem" />
  */
 export function KptSkeleton({ variant = 'rect', width = '100%', height = '1rem', lines = 3, className, ...rest }) {
-    return (_jsx("span", { className: cn('kpt-skeleton-host', className), "aria-hidden": "true", ...rest, children: variant === 'text' ? (Array.from({ length: lines }, (_, index) => (_jsx("span", { className: "kpt-skeleton kpt-skeleton--text", style: { width: index === lines - 1 ? '60%' : width } }, index)))) : (_jsx("span", { className: "kpt-skeleton", "data-variant": variant, style: { width, height } })) }));
+    return (_jsx("span", { className: cn('kpt-skeleton-host', className), "aria-hidden": "true", ...rest, children: variant === 'text' ? (Array.from({ length: lines }, (_, index) => (_jsx("span", { className: "kpt-skeleton kpt-skeleton--text", style: { width: lines > 1 && index === lines - 1 ? '60%' : width } }, index)))) : (_jsx("span", { className: "kpt-skeleton", "data-variant": variant, style: { width, height } })) }));
 }

package/dist/slider/llms.txt

@@ -16,7 +16,7 @@ Import: `import { KptSlider } from '@konce-pt/react';`
         <div class="kpt-slider__rail"></div>
         <div class="kpt-slider__fill" style="left: 20%; right: 20%"></div>
         <input class="kpt-slider__thumb kpt-slider__thumb--low" type="range" aria-label="Minimum">
-        <input class="kpt-slider__thumb kpt-slider__thumb--high" type="range" aria-label="Maksimum">
+        <input class="kpt-slider__thumb kpt-slider__thumb--high" type="range" aria-label="Maximum">
       </div>
       <span class="kpt-slider__value">20–80</span>
     </div>
@@ -42,6 +42,19 @@ pair therefore always stays ordered, so the fill never inverts.
     <KptSlider value={volume} onValueChange={(v) => setVolume(v as number)} showValue />
     <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
+zł"), so the unit is read too. `aria-invalid` after touch.
+
+## Label and description
+`id` goes to the native field, not the host; without one it comes from `KptFormField` or is
+generated. Inside `KptFormField` the wrapper's `label[for]` points at it and the hint or error is
+added to `aria-describedby` (merged with your own). Without a wrapper, name it with `ariaLabel`.
+With `range` the thumbs are named "Minimum"/"Maximum" from i18n (`slider.min`/`slider.max`,
+previously hard-coded and mixed-language); inside `kpt-form-field` each thumb reads "<label>
+Minimum" through `aria-labelledby`, without one `ariaLabel` gives "<ariaLabel>, Minimum". `id` goes
+to the single input or the lower thumb.
+
 ## Tokens
 `--kpt-color-primary` (the fill and the handles), `--kpt-color-muted` (the rail).
 

package/dist/slider/slider.d.ts

@@ -1,7 +1,8 @@
 import type { ComponentPropsWithRef } from 'react';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 /** Wartość suwaka: pojedyncza liczba albo para `[min, max]` w trybie `range`. */
 export type KptSliderValue = number | [number, number];
-export interface KptSliderProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
+export interface KptSliderProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'>, KptI18nOverrides {
     value?: KptSliderValue;
     defaultValue?: KptSliderValue;
     onValueChange?: (value: KptSliderValue) => void;
@@ -12,6 +13,14 @@ 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`. */
+    suffix?: string;
+    invalid?: boolean;
+    touched?: boolean;
+    /** 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;
     onTouch?: () => void;
 }
@@ -25,4 +34,4 @@ export interface KptSliderProps extends Omit<ComponentPropsWithRef<'div'>, 'onCh
  * <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, disabled, onTouch, 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, onTouch, locale, dictionary, className, ...rest }: Readonly<KptSliderProps>): import("react").JSX.Element;

package/dist/slider/slider.js

@@ -1,6 +1,8 @@
 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";
 /**
  * Suwak wartości. W trybie `range` udostępnia dwa uchwyty, a wartością jest para `[min, max]`.
  *
@@ -11,7 +13,18 @@ import { useControllableState } from "../internal/use-controllable-state.js";
  * <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, disabled = false, onTouch, 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, 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”. */
+    const thumbLabel = (end) => {
+        if (field.labelledBy)
+            return undefined;
+        const name = t(end === 'min' ? 'slider.min' : 'slider.max');
+        return ariaLabel ? `${ariaLabel}, ${name}` : name;
+    };
+    /** Uchwyt zakresu w `KptFormField`: etykieta pola + nazwa uchwytu. */
+    const thumbLabelledBy = (end) => field.labelledBy ? joinIds(field.labelledBy, `${field.id}-${end}-name`) : undefined;
     const [current, setCurrent] = useControllableState({
         value,
         defaultValue: defaultValue ?? (range ? [min, max] : 0),
@@ -26,5 +39,5 @@ export function KptSlider({ value, defaultValue, onValueChange, range = false, m
     // 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("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, disabled: disabled, "aria-label": "Minimum", 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, disabled: disabled, "aria-label": "Maksimum", onChange: (event) => setHigh(Number(event.target.value)), onBlur: () => onTouch?.() })] }), showValue ? (_jsxs("span", { className: "kpt-slider__value", children: [low, "\u2013", high] })) : null] })) : (_jsxs(_Fragment, { children: [_jsx("input", { className: "kpt-slider__input", type: "range", min: min, max: max, step: step, value: single, disabled: disabled, style: { ['--_pct']: `${pct(single)}%` }, onChange: (event) => setCurrent(Number(event.target.value)), onBlur: () => onTouch?.() }), showValue ? _jsx("span", { className: "kpt-slider__value", children: single }) : null] })) }));
+    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] })) }));
 }

package/dist/speed-dial/llms.txt

@@ -42,5 +42,9 @@ The main button comes from `KptFab`; the actions use `--kpt-color-surface-raised
 `--kpt-elevation-2`.
 
 ## Accessibility
-Every action is a `<button>` labelled with its own `label`, so the fan works from the keyboard even
-when the actions show icons only.
+- 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.
+- `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

@@ -17,4 +17,4 @@ export interface KptSpeedDialProps<T> extends Omit<ComponentPropsWithRef<'div'>,
  * @example
  * <KptSpeedDial items={actions} direction="up" onSelect={onAction} />
  */
-export declare function KptSpeedDial<T>({ items, direction, icon, ariaLabel, onSelect, locale, dictionary, className, ...rest }: Readonly<KptSpeedDialProps<T>>): import("react").JSX.Element;
+export declare function KptSpeedDial<T>({ items, direction, icon, ariaLabel, onSelect, locale, dictionary, className, onKeyDown: onKeyDownProp, ...rest }: Readonly<KptSpeedDialProps<T>>): import("react").JSX.Element;

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

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
+import { useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
+import { useKptId } from "../internal/use-id.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptFab } from "../fab/fab.js";
 import { KptIcon } from "../icon/icon.js";
@@ -10,14 +11,24 @@ import { KptIcon } from "../icon/icon.js";
  * @example
  * <KptSpeedDial items={actions} direction="up" onSelect={onAction} />
  */
-export function KptSpeedDial({ items = [], direction = 'up', icon = 'plus', ariaLabel, onSelect, locale, dictionary, className, ...rest }) {
+export function KptSpeedDial({ items = [], direction = 'up', icon = 'plus', ariaLabel, onSelect, locale, dictionary, className, onKeyDown: onKeyDownProp, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const [open, setOpen] = useState(false);
+    const actionsId = useKptId(undefined, 'kpt-speed-dial-actions');
+    const hostRef = useRef(null);
+    /** Escape z dowolnego miejsca w wachlarzu: zamyka i zwraca fokus na główny przycisk. */
+    const onKeyDown = (event) => {
+        onKeyDownProp?.(event);
+        if (event.key !== 'Escape' || !open)
+            return;
+        setOpen(false);
+        hostRef.current?.querySelector('.kpt-fab')?.focus();
+    };
     const pick = (item) => {
         if (item.disabled)
             return;
         onSelect?.(item);
         setOpen(false);
     };
-    return (_jsxs("div", { className: cn('kpt-speed-dial-host', className), ...rest, children: [_jsxs("div", { className: cn('kpt-speed-dial', open && 'is-open'), "data-direction": direction, children: [_jsx("div", { className: "kpt-speed-dial__actions", 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')), 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

@@ -4,7 +4,8 @@ A loading indicator. Import: `import { KptSpinner } from '@konce-pt/react';`
 
 ## DOM
     <span class="kpt-spinner-host">
-      <span class="kpt-spinner" role="status" aria-label="Loading" style="width: 1.75rem; height: 1.75rem"></span>
+      <span class="kpt-spinner" aria-hidden="true" style="width: 1.75rem; height: 1.75rem"></span>
+      <span class="kpt-spinner__label" role="status">Loading</span>
     </span>
 
 ## Props
@@ -14,9 +15,10 @@ A loading indicator. Import: `import { KptSpinner } from '@konce-pt/react';`
 - `className`, `ref` and every other `<span>` prop go to the host
 
 ## The colour is inherited
-The spinner draws itself in `currentColor`, so it takes the colour of the text around it. Put it
-inside a button and it matches the button; put it on a card and it matches the card. There is no
-colour prop, on purpose.
+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.
 
 ## Examples
     <KptSpinner />
@@ -24,10 +26,12 @@ colour prop, on purpose.
     <KptButton disabled><KptSpinner size="1em" /> Saving…</KptButton>
 
 ## Tokens
-None of its own — the size comes from the prop, the colour from `currentColor`, the speed from
+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
-`role="status"` with a label, so a screen reader announces the wait politely. For a longer
-operation prefer `KptProgress` — a spinner says "something is happening", a progress bar says how
-much is left.
+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
+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

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithRef } from 'react';
+import { type ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptSpinnerProps extends Omit<ComponentPropsWithRef<'span'>, 'children'>, KptI18nOverrides {
     size?: string;
@@ -8,6 +8,10 @@ export interface KptSpinnerProps extends Omit<ComponentPropsWithRef<'span'>, 'ch
 /**
  * Wskaźnik ładowania. Kolor bierze z `currentColor`, więc dopasowuje się do treści wokół.
  *
+ * 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ę.
+ *
  * @example
  * <KptSpinner />
  * <KptSpinner size="2rem" label="Wczytywanie danych" />

package/dist/spinner/spinner.js

@@ -1,14 +1,24 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 /**
  * Wskaźnik ładowania. Kolor bierze z `currentColor`, więc dopasowuje się do treści wokół.
  *
+ * 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ę.
+ *
  * @example
  * <KptSpinner />
  * <KptSpinner size="2rem" label="Wczytywanie danych" />
  */
 export function KptSpinner({ size = '1.5rem', label, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
-    return (_jsx("span", { className: cn('kpt-spinner-host', className), ...rest, children: _jsx("span", { className: "kpt-spinner", role: "status", "aria-label": label ?? t('spinner.label'), style: { width: size, height: size } }) }));
+    const [ready, setReady] = useState(false);
+    useEffect(() => {
+        const frame = requestAnimationFrame(() => setReady(true));
+        return () => cancelAnimationFrame(frame);
+    }, []);
+    return (_jsxs("span", { className: cn('kpt-spinner-host', className), ...rest, children: [_jsx("span", { className: "kpt-spinner", "aria-hidden": "true", style: { width: size, height: size, borderWidth: `max(2px, calc(${size} * 0.08))` } }), _jsx("span", { className: "kpt-spinner__label", role: "status", children: ready ? (label ?? t('spinner.label')) : '' })] }));
 }

package/dist/split-button/llms.txt

@@ -14,7 +14,9 @@ Import: `import { KptSplitButton } from '@konce-pt/react';`
     <div class="kpt-split-button__panel" role="menu">…rows…</div>
 
 ## Props
-- `variant`: the same union as `KptButton` (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
@@ -35,6 +37,12 @@ the `danger` modifier all behave identically, only the BEM block differs.
 ## i18n
 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`
+jump, `Escape` / `Tab` close, and closing or picking returns focus to the toggle. Same rules as the
+menu — see the `KptMenu` docs.
+
 ## Examples
     <KptSplitButton items={items} onPrimaryClick={save} onSelect={onItem}>Save</KptSplitButton>
 
@@ -50,5 +58,5 @@ The `--kpt-button-*` tokens of the chosen variant, plus `--kpt-color-surface-rai
 `--kpt-elevation-3` for the panel.
 
 ## Accessibility
-Two native buttons; the toggle carries `aria-label`, the panel is `role="menu"` with
-`role="menuitem"` rows.
+Two native buttons; the toggle carries `aria-label` plus the menu-button attributes above, the
+panel is `role="menu"` with `role="menuitem"` rows.