@konce-pt/react 0.11.2 → 0.14.0

package/dist/scroll-top/llms.txt

@@ -1,20 +1,20 @@
 # KptScrollTop (@konce-pt/react)
 
-A "back to top" button — appears once the scroll passes `threshold` px.
+A "back to top" button - appears once the scroll passes `threshold` px.
 Import: `import { KptScrollTop } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-scroll-top-host">
-      <button class="kpt-scroll-top is-visible" tabindex="0" aria-label="Scroll to top">…</button>
+      <button class="kpt-scroll-top is-visible" tabindex="0" aria-label="Scroll to top">...</button>
     </div>
 
 ## Props
 - `threshold`: number (px, default 300)
-- `target`: string | null — a selector for the scrolled element; the window by default
+- `target`: string | null - a selector for the scrolled element; the window by default
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## `target` is not optional in a shell
-Whenever the app scrolls a container rather than the page — an `KptAppShell` layout, for instance —
+Whenever the app scrolls a container rather than the page - an `KptAppShell` layout, for instance -
 the window never scrolls and the button would never appear. Point it at the container:
 `target=".kpt-app-shell__content"`.
 
@@ -24,7 +24,7 @@ component, and on the server it does not exist at all. The listener is removed o
 position is read once on mount, because the page may already be scrolled (arriving at an anchor).
 
 ## The hidden button stays in the DOM
-It fades in and out, so hiding it is `tabindex="-1"` plus the CSS class, not a conditional render —
+It fades in and out, so hiding it is `tabindex="-1"` plus the CSS class, not a conditional render -
 otherwise the animation would have nothing to run on.
 
 ## Examples
@@ -42,4 +42,4 @@ A real `<button>` labelled from `scrollTop.label`; while hidden it is `visibilit
 out of the tab order and the accessibility tree. It sits in the bottom-end corner
 (`inset-inline-end`), so it moves to the left in RTL. With `prefers-reduced-motion` the scroll is a
 jump instead of smooth and the button appears without a transition. Focus stays on the button after
-the jump — move it to your page heading if that matters.
+the jump - move it to your page heading if that matters.

package/dist/scroll-top/scroll-top.d.ts

@@ -7,7 +7,7 @@ export interface KptScrollTopProps extends ComponentPropsWithRef<'div'>, KptI18n
     target?: string | null;
 }
 /**
- * Przycisk „do góry" — pojawia się po przewinięciu ponad `threshold` px.
+ * Przycisk "do góry" - pojawia się po przewinięciu ponad `threshold` px.
  *
  * @example
  * <KptScrollTop threshold={300} />

package/dist/scroll-top/scroll-top.js

@@ -1,10 +1,11 @@
+'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
 /**
- * Przycisk „do góry" — pojawia się po przewinięciu ponad `threshold` px.
+ * Przycisk "do góry" - pojawia się po przewinięciu ponad `threshold` px.
  *
  * @example
  * <KptScrollTop threshold={300} />

package/dist/select/llms.txt

@@ -6,21 +6,21 @@ A select on its own panel. Variants: single, with a search box (`filter`) and mu
 ## DOM
     <span class="kpt-select-host">
       <div class="kpt-select" role="combobox" tabindex="0" aria-expanded="false">
-        <div class="kpt-select__value"><span class="kpt-select__placeholder">Choose…</span></div>
-        <span class="kpt-icon-host kpt-select__chevron">…</span>
+        <div class="kpt-select__value"><span class="kpt-select__placeholder">Choose...</span></div>
+        <span class="kpt-icon-host kpt-select__chevron">...</span>
       </div>
     </span>
     <!-- while open, in a portal on document.body: -->
-    <div class="kpt-select__panel"><ul class="kpt-select__list" role="listbox">…</ul></div>
+    <div class="kpt-select__panel"><ul class="kpt-select__list" role="listbox">...</ul></div>
 
 ## Props
-- `options`: `KptOption<T>[]` — `{ label, value, disabled? }`
-- `value` / `defaultValue` / `onValueChange` — a single `T`, or `T[]` in `multiple` mode
-- `open` / `defaultOpen` / `onOpenChange` — the panel state, so the list can be opened from outside
+- `options`: `KptOption<T>[]` - `{ label, value, disabled? }`
+- `value` / `defaultValue` / `onValueChange` - a single `T`, or `T[]` in `multiple` mode
+- `open` / `defaultOpen` / `onOpenChange` - the panel state, so the list can be opened from outside
 - `placeholder`, `multiple`, `filter`, `disabled`, `invalid`, `touched`
-- `onTouch()` — fires when the panel closes or focus leaves the closed trigger
+- `onTouch()` - fires when the panel closes or focus leaves the closed trigger
 - `aria-label` (through the rest props) names the trigger when no `<label for>` describes it
-- `locale`, `dictionary` — i18n overrides for this component only
+- `locale`, `dictionary` - i18n overrides for this component only
 - `className`, `ref` and every other `<div>` prop go to the trigger
 
 ## The panel is a portal
@@ -35,20 +35,20 @@ through `aria-activedescendant` (with `filter`, focus moves to the search field)
 ArrowUp, Enter, Space, Home and End open the list, typing letters opens it on the first match, and
 in `multiple` mode Backspace/Delete removes the last chip. Open: ArrowUp/ArrowDown move by one,
 Home/End to the ends, PageUp/PageDown by ten, skipping disabled options without wrapping; Enter (and
-Space on the trigger) picks — a single select closes and returns focus to the trigger; typing jumps
+Space on the trigger) picks - a single select closes and returns focus to the trigger; typing jumps
 to the next match, diacritics ignored; Escape and Tab close. Hovering an option makes it active, so
 the mouse and the keyboard share one highlight, and clicking it does not take focus from the trigger.
 
 ## Inside KptFormField
 There is no native field for the wrapper to read, so the select reports its filled state with
-`useKptFormFieldFilled` — the float label then floats over the chosen value.
+`useKptFormFieldFilled` - the float label then floats over the chosen value.
 
 ## i18n
 `select.search` (the search placeholder), `select.noResults` (the empty list),
 `select.removeChip` (the chip's remove button).
 
 ## Examples
-    <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Choose…" />
+    <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Choose..." />
     <KptSelect options={roles} value={role} onValueChange={setRole} filter />
     <KptSelect options={tags} value={tags} onValueChange={setTags} multiple filter />
 
@@ -56,9 +56,16 @@ There is no native field for the wrapper to read, so the select reports its fill
 `id` goes to the focusable element, not the host; without one it comes from `KptFormField` or is
 generated. A `div` with a role is not named by `label[for]`, so inside `KptFormField` it gets
 `aria-labelledby` pointing at the wrapper's label (unless `aria-label` is set), and the hint or
-error is added to `aria-describedby`. New: `id` and `required` (→ `aria-required`); the list gets
+error is added to `aria-describedby`. New: `id` and `required` (-> `aria-required`); the list gets
 the same name as the trigger.
 
+## Motion
+With `multiple`, a chip of a newly picked option pops in at its place (chips follow the order of
+`options`), a removed one - by its "x", by unpicking it in the list or by `Backspace` - fades and shrinks in
+place while the rest slide over on a spring. Several changes at once (e.g. a new value set from code) go
+without motion. Follows `enter` from `KptMotionProvider` (`spring` / `fade` / `none`); `enabled: false` and the
+system "reduce motion" setting always win.
+
 ## Tokens
 `--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}`,
 `--kpt-color-surface-raised` and `--kpt-elevation-3` for the panel, `--kpt-z-overlay` for the layer.
@@ -68,3 +75,6 @@ The trigger is `role="combobox"` with `aria-haspopup="listbox"`, `aria-expanded`
 and `aria-activedescendant`; the list is `role="listbox"` with `aria-multiselectable`, and each
 option is `role="option"` with `aria-selected` and `aria-disabled`. Chip remove buttons sit outside
 the Tab order and are named with the option label.
+
+## Read-only and required
+`readOnly` shows the choice, but the panel does not open and the chips have no remove button (`aria-readonly`). The filter ignores case and diacritics ("lodz" finds "Łódź"), as in `listbox`. "No results" sits next to the list, not inside it (a listbox may contain only options).

package/dist/select/select.d.ts

@@ -4,22 +4,24 @@ import type { KptOption } from '../shared/types.ts';
 export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'children' | 'onChange' | 'defaultValue'>, KptI18nOverrides {
     options?: readonly KptOption<T>[];
     placeholder?: string;
-    /** Wybór wielokrotny — wartością jest tablica, a wybrane opcje pokazują się jako chipy. */
+    /** Wybór wielokrotny - wartością jest tablica, a wybrane opcje pokazują się jako chipy. */
     multiple?: boolean;
     /** Pole wyszukiwania nad listą. */
     filter?: boolean;
-    /** Id wyzwalacza; bez niego generowane, w `KptFormField` — z wrappera. */
+    /** Id wyzwalacza; bez niego generowane, w `KptFormField` - z wrappera. */
     id?: string;
     /** Oznacza pole jako wymagane atrybutem `aria-required`. */
     required?: boolean;
     disabled?: boolean;
+    /** Tylko do odczytu - wybór widać, panel się nie otwiera (`aria-readonly`). */
+    readOnly?: boolean;
     invalid?: boolean;
     touched?: boolean;
     /** Wartość: pojedyncza (T) albo tablica (T[]) w trybie `multiple`. */
     value?: T | T[] | null;
     defaultValue?: T | T[] | null;
     onValueChange?: (value: T | T[] | null) => void;
-    /** Stan panelu — pozwala otworzyć listę z zewnątrz i wiedzieć, kiedy user skończył wybierać. */
+    /** Stan panelu - pozwala otworzyć listę z zewnątrz i wiedzieć, kiedy user skończył wybierać. */
     open?: boolean;
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
@@ -30,19 +32,19 @@ 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,
+ * Klawiatura według wzorca WAI-ARIA "select-only combobox": fokus zostaje na polu, a aktywna opcja
+ * idzie przez `aria-activedescendant`. `ArrowDown`/`ArrowUp`/`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
+ * Float Label unosi się nad wybraną wartością - natywnego pola, z którego wrapper mógłby to
  * odczytać, tu nie ma.
  *
  * @example
- * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz…" />
+ * <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, id, required, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptSelectProps<T>>): import("react").JSX.Element;
+export declare function KptSelect<T>({ options, placeholder, multiple, filter, disabled, readOnly, 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

@@ -1,6 +1,11 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { foldMentionText } from '@konce-pt/mention';
+import { flowChangeOf, prepareFlowMotion, resolveEnterMotion } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
 import { cn } from "../internal/cn.js";
+import { optionKey } from "../internal/option-key.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptId } from "../internal/use-id.js";
@@ -8,30 +13,37 @@ import { KptTypeahead, OPTION_NAV_KEYS, isTypeaheadKey, nextOptionIndex, typeahe
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { joinIds, useKptFieldA11y, useKptFormFieldFilled } from "../form-field/form-field-context.js";
 import { KptIcon } from "../icon/icon.js";
+/** Filtr opcji bez wielkości liter i diakrytyków, jak w `KptListbox`: "lodz" znajduje "Łódź". */
+function filterSelectOptions(options, text) {
+    const q = foldMentionText(text.trim());
+    return q ? options.filter((option) => foldMentionText(option.label).includes(q)) : options;
+}
 /**
  * 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,
+ * Klawiatura według wzorca WAI-ARIA "select-only combobox": fokus zostaje na polu, a aktywna opcja
+ * idzie przez `aria-activedescendant`. `ArrowDown`/`ArrowUp`/`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
+ * Float Label unosi się nad wybraną wartością - natywnego pola, z którego wrapper mógłby to
  * odczytać, tu nie ma.
  *
  * @example
- * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz…" />
+ * <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, 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. */
+export function KptSelect({ options = [], placeholder = '', multiple = false, filter = false, disabled = false, readOnly = 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);
+    /** Kotwica nakładki w stanie (callback ref), nie `triggerRef.current` czytane w renderze. */
+    const [anchor, setAnchor] = useState(null);
     const searchRef = useRef(null);
     const typeahead = useRef(new KptTypeahead());
     const uid = useKptId(undefined, 'kpt-select');
@@ -52,35 +64,41 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
     const showInvalid = invalid && (touched ?? true);
     const selectedValues = useMemo(() => {
         if (multiple)
-            return Array.isArray(current) ? current : [];
+            return Array.isArray(current) ? (current) : [];
         return current == null ? [] : [current];
     }, [current, multiple]);
     const selectedOptions = useMemo(() => options.filter((option) => selectedValues.includes(option.value)), [options, selectedValues]);
-    const filterOptions = (text) => {
-        const q = text.trim().toLowerCase();
-        return q ? options.filter((option) => option.label.toLowerCase().includes(q)) : options;
-    };
-    const filteredOptions = useMemo(() => filterOptions(filterText), [options, filterText]); // eslint-disable-line react-hooks/exhaustive-deps
+    const filteredOptions = useMemo(() => filterSelectOptions(options, filterText), [options, filterText]);
     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.
+    /** Skrajna opcja, na której ma się otworzyć lista (`Home`/`End`/`ArrowUp` na zamkniętym polu). */
+    const [openEdge, setOpenEdge] = useState(null);
+    // 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 przejściu w stan otwarty, wzorcem "poprzednia wartość
+    // w stanie" (w tym samym renderze, bez efektu). Lista otwiera się na wybranej opcji; zmiana
+    // wyboru w trybie `multiple` przy otwartym panelu nie przesuwa aktywnej opcji.
+    const [wasOpen, setWasOpen] = useState(isOpen);
+    if (wasOpen !== isOpen) {
+        setWasOpen(isOpen);
+        if (isOpen) {
+            setFilterText('');
+            const disabledAll = options.map((o) => !!o.disabled);
+            const selected = options.findIndex((option) => selectedValues.includes(option.value));
+            const firstEnabled = nextOptionIndex(disabledAll, -1, 'ArrowDown') ?? -1;
+            setActiveIndex(openEdge ? (nextOptionIndex(disabledAll, -1, openEdge) ?? -1) : selected >= 0 ? selected : firstEnabled);
+            setOpenEdge(null);
+        }
+    }
+    // Z `filter` fokus idzie do wyszukiwarki - klatkę później, bo `KptOverlay` mierzy panel
+    // w `visibility: hidden`.
     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)
+        if (!isOpen || !filter)
             return;
         const frame = requestAnimationFrame(() => searchRef.current?.focus());
         return () => cancelAnimationFrame(frame);
-    }, [isOpen]); // eslint-disable-line react-hooks/exhaustive-deps
+    }, [isOpen, filter]);
     // Aktywna opcja zawsze w polu widzenia listy.
     useEffect(() => {
         if (isOpen && activeIndex >= 0)
@@ -92,16 +110,40 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
         setOpen(false);
         onTouch?.();
     }, [isOpen, setOpen, onTouch]);
-    /** Zamknięcie z powrotem fokusu na pole — po wyborze, `Escape`, `Tab` w wyszukiwarce. */
+    /** Zamknięcie z powrotem fokusu na pole - po wyborze, `Escape`, `Tab` w wyszukiwarce. */
     const closeAndFocus = () => {
         close();
         triggerRef.current?.focus();
     };
+    const enterMotion = resolveEnterMotion(undefined, useKptMotion());
+    const valueRef = useRef(null);
+    /** Ruch chipów przygotowany przed zmianą wyboru, odtwarzany po jej wyrenderowaniu. */
+    const pendingFlow = useRef(null);
+    const chipElements = () => Array.from(valueRef.current?.querySelectorAll('.kpt-select__chip') ?? []);
+    // Przed malowaniem - inaczej mignęłaby klatka z nowym układem, zanim FLIP cofnie chipy.
+    useLayoutEffect(() => {
+        const play = pendingFlow.current;
+        pendingFlow.current = null;
+        play?.(chipElements());
+    });
+    /**
+     * Nowy wybór w trybie `multiple` z ruchem chipów: dodany wskakuje, usunięty gaśnie, reszta się
+     * dosuwa (`prepareFlowMotion`, za `enter` z `KptMotionProvider`). Chipy stoją w kolejności opcji,
+     * więc pozycję zmiany liczymy z list przed i po; kilka zmian naraz idzie bez ruchu.
+     */
+    const setSelected = (next) => {
+        const box = valueRef.current;
+        const order = (values) => options.filter((o) => values.includes(o.value)).map((o) => o.value);
+        const change = flowChangeOf(order(selectedValues), order(next));
+        if (enterMotion !== 'none' && box && change)
+            pendingFlow.current = prepareFlowMotion(box, chipElements(), change, enterMotion);
+        setCurrent(next);
+    };
     const pick = (option) => {
         if (option.disabled)
             return;
         if (multiple) {
-            setCurrent(isSelected(option) ? selectedValues.filter((v) => v !== option.value) : [...selectedValues, option.value]);
+            setSelected(isSelected(option) ? selectedValues.filter((v) => v !== option.value) : [...selectedValues, option.value]);
         }
         else {
             setCurrent(option.value);
@@ -114,27 +156,22 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
         if (found !== null)
             setActiveIndex(found);
     };
-    /** Jeden obsługiwacz dla pola i dla wyszukiwarki w panelu — różnią się tylko `Spacją` i `Tab`. */
+    /** Jeden obsługiwacz dla pola i dla wyszukiwarki w panelu - różnią się tylko `Spacją` i `Tab`. */
     const onKeyDown = (event, source) => {
-        if (disabled)
+        if (disabled || readOnly)
             return;
         const key = event.key;
         if (!isOpen) {
             if (['ArrowDown', 'ArrowUp', 'Enter', ' ', 'Home', 'End'].includes(key)) {
                 event.preventDefault();
+                // Skrajne klawisze otwierają listę na pierwszej albo ostatniej opcji zamiast na wybranej.
+                if (key === 'ArrowUp' || key === 'End' || key === 'Home')
+                    setOpenEdge(key === 'Home' ? 'Home' : 'End');
                 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));
+                setSelected(selectedValues.slice(0, -1));
             }
             else if (isTypeaheadKey(event.nativeEvent) && !filter) {
                 setOpen(true);
@@ -147,7 +184,7 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
             closeAndFocus();
         }
         else if (key === 'Tab') {
-            // Z wyszukiwarki (w portalu na końcu strony) Tab uciekłby w próżnię — wracamy na pole.
+            // Z wyszukiwarki (w portalu na końcu strony) Tab uciekłby w próżnię - wracamy na pole.
             if (source === 'search') {
                 event.preventDefault();
                 closeAndFocus();
@@ -172,18 +209,21 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
             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", 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) => {
+    return (_jsxs("span", { className: "kpt-select-host", children: [_jsxs("div", { ref: (el) => {
+                    triggerRef.current = el;
+                    setAnchor(el);
+                }, className: cn('kpt-select', isOpen && 'kpt-select--open', disabled && 'kpt-select--disabled', readOnly && 'kpt-select--readonly', 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-readonly": readOnly || 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 && !readOnly && setOpen(!isOpen), onKeyDown: (event) => onKeyDown(event, 'trigger'), onBlur: (event) => {
                     onBlur?.(event);
-                    // Przy otwartym panelu fokus idzie do pola szukania — „dotknięcie” wyśle dopiero zamknięcie.
+                    // 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) => {
+                }, ...rest, children: [_jsx("div", { className: "kpt-select__value", ref: valueRef, children: multiple && selectedOptions.length ? (selectedOptions.map((option, index) => (_jsxs("span", { className: "kpt-select__chip", children: [option.label, readOnly ? null : (_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, minAnchorWidth: 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) => {
+                                        setSelected(selectedValues.filter((v) => v !== option.value));
+                                    }, children: _jsx(KptIcon, { name: "x" }) }))] }, optionKey(option.value, index))))) : !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: anchor, onClose: close, minAnchorWidth: 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);
-                                        // Po zawężeniu aktywna jest pierwsza pasująca opcja — `Enter` wybiera ją od razu.
-                                        const narrowed = filterOptions(event.target.value).map((o) => !!o.disabled);
+                                        // Po zawężeniu aktywna jest pierwsza pasująca opcja - `Enter` wybiera ją od razu.
+                                        const narrowed = filterSelectOptions(options, 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') })) })] }) })] }));
+                                    } })] })) : 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.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] }, optionKey(option.value, index)))) }), filteredOptions.length === 0 ? (_jsx("div", { className: "kpt-select__empty", role: "status", children: t('select.noResults') })) : null] }) })] }));
 }

package/dist/shared/types.d.ts

@@ -6,5 +6,26 @@ export interface KptOption<T = unknown> {
     /** Nazwa ikony z rejestru. Renderuje ją dziś wyłącznie `kpt-button-group`. */
     icon?: string;
 }
-/** Wariant komunikatu — wspólny dla alertu i toastów. */
+/** Wariant komunikatu - wspólny dla alertu i toastów. */
 export type KptAlertVariant = 'info' | 'success' | 'warning' | 'danger';
+/**
+ * Klik w odnośnik komponentu nawigacji (`kpt-breadcrumb`, `kpt-menubar`, `kpt-megamenu`). Linki
+ * są zwykłym `<a href>`, więc bez routera klik przeładowuje stronę. Aplikacja z routerem łapie to
+ * zdarzenie, woła `event.preventDefault()` i nawiguje sama - biblioteka nie zależy od żadnego routera.
+ * Zdarzenie leci tylko dla zwykłego kliku: Ctrl/Cmd/Shift/środkowy przycisk i `target="_blank"`
+ * zostają natywne (nowa karta, nowe okno).
+ */
+export interface KptNavigateEvent<T = unknown> {
+    /** Pozycja, w którą kliknięto. */
+    item: T;
+    /** Adres z `href`. */
+    url: string;
+    /** Oryginalne zdarzenie - `preventDefault()` zatrzymuje przeładowanie strony. */
+    event: MouseEvent;
+}
+/**
+ * Czy klik to zwykła nawigacja w tej samej karcie: lewy przycisk, bez modyfikatorów, a odnośnik
+ * nie ma `target` innego niż `_self`. `target` podaje wołający - w React `currentTarget`
+ * zdarzenia natywnego to korzeń aplikacji, nie kliknięty odnośnik.
+ */
+export declare function kptIsPlainClick(event: Pick<MouseEvent, 'button' | 'ctrlKey' | 'metaKey' | 'shiftKey' | 'altKey'>, target?: string): boolean;

package/dist/shared/types.js

@@ -1 +1,9 @@
-export {};
+/**
+ * Czy klik to zwykła nawigacja w tej samej karcie: lewy przycisk, bez modyfikatorów, a odnośnik
+ * nie ma `target` innego niż `_self`. `target` podaje wołający - w React `currentTarget`
+ * zdarzenia natywnego to korzeń aplikacji, nie kliknięty odnośnik.
+ */
+export function kptIsPlainClick(event, target = '') {
+    const modified = event.ctrlKey || event.metaKey || event.shiftKey || event.altKey;
+    return event.button === 0 && !modified && (target === '' || target === '_self');
+}

package/dist/sidenav/llms.txt

@@ -1,24 +1,24 @@
 # KptSidenav (@konce-pt/react)
 
-The side panel — a styled navigation container, usually handed to the `sidenav` slot of
+The side panel - a styled navigation container, usually handed to the `sidenav` slot of
 `<KptAppShell>`. Import: `import { KptSidenav } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-sidenav">
-      <div class="kpt-sidenav__scroll">…children…</div>
-      <div kptsidenavfooter="">…footer…</div>
+      <div class="kpt-sidenav__scroll">...children...</div>
+      <div kptsidenavfooter="">...footer...</div>
     </div>
 
 ## Props
 - `className`, `ref` and every other `<div>` prop go to the panel root
 
 ## Sub-components
-- `KptSidenav.Footer` — lifted OUT of the scrolling area, so it stays pinned to the bottom of the
+- `KptSidenav.Footer` - lifted OUT of the scrolling area, so it stays pinned to the bottom of the
   panel however long the navigation gets (a user block, an app version, a theme switch). It carries
   the `kptsidenavfooter` attribute the shared SCSS targets.
 
 Default children land in the scrolling area. Plain `<a>` elements inside it are styled by the
-stylesheet already — padding, radius, a hover background — so a simple link list needs no classes.
+stylesheet already - padding, radius, a hover background - so a simple link list needs no classes.
 
 ## Examples
     <KptSidenav>
@@ -27,7 +27,7 @@ stylesheet already — padding, radius, a hover background — so a simple link
       <KptSidenav.Footer>v0.7.12</KptSidenav.Footer>
     </KptSidenav>
 
-    <KptAppShell sidenav={<KptSidenav>…</KptSidenav>} toolbar={…}>…</KptAppShell>
+    <KptAppShell sidenav={<KptSidenav>...</KptSidenav>} toolbar={...}>...</KptAppShell>
 
 ## Rail mode
 When `<KptAppShell sidenavRailBreakpoint>` is on, a closed panel narrows instead of hiding. Mark the
@@ -41,13 +41,13 @@ the shell will clip them the accessible way (visually hidden, still in the acces
 
 Both render the lowercase attribute the shared SCSS targets (`kptnavlabel` / `kptnavsection`);
 attribute names in CSS selectors are case-insensitive in HTML, so one rule serves both ports. Use
-the components rather than writing the attribute by hand — JSX rejects an unknown camelCase
+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
+`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
@@ -55,5 +55,5 @@ yourself, the component does not know which one it is.
 `--kpt-sidenav-rail-width`, which are read by `KptAppShell`.
 
 ## Accessibility
-The panel itself is a plain container — the `role="navigation"` and the label live on the shell's
+The panel itself is a plain container - the `role="navigation"` and the label live on the shell's
 `<aside>` around it, so a sidenav used outside `KptAppShell` needs its own landmark.

package/dist/sidenav/sidenav.d.ts

@@ -1,8 +1,7 @@
 import { type ComponentPropsWithRef } from 'react';
-export interface KptSidenavProps extends ComponentPropsWithRef<'div'> {
-}
+export type KptSidenavProps = ComponentPropsWithRef<'div'>;
 /**
- * Panel boczny (sidenav) — stylowany kontener nawigacji, zwykle podawany do slotu
+ * Panel boczny (sidenav) - stylowany kontener nawigacji, zwykle podawany do slotu
  * `sidenav` komponentu `<KptAppShell>`.
  *
  * @example

package/dist/sidenav/sidenav.js

@@ -1,13 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, isValidElement } from 'react';
+import { isValidElement } from 'react';
 import { cn } from "../internal/cn.js";
+import { slotChildren } from "../internal/slot-children.js";
 /*
  * Panel odtwarza projekcję z Angulara: treść domyślna ląduje w obszarze przewijanym,
  * a `<KptSidenav.Footer>` jest wynoszona POZA ten obszar. Dzięki temu stopka zostaje
  * przyklejona do dołu panelu niezależnie od długości nawigacji.
  */
 /**
- * Panel boczny (sidenav) — stylowany kontener nawigacji, zwykle podawany do slotu
+ * Panel boczny (sidenav) - stylowany kontener nawigacji, zwykle podawany do slotu
  * `sidenav` komponentu `<KptAppShell>`.
  *
  * @example
@@ -20,14 +21,14 @@ import { cn } from "../internal/cn.js";
 export function KptSidenav({ className, children, ...rest }) {
     const scroll = [];
     const footers = [];
-    Children.forEach(children, (child) => {
+    for (const child of slotChildren(children)) {
         if (isValidElement(child) && child.type?.kptSidenavSlot === 'footer') {
             footers.push(child);
         }
         else {
             scroll.push(child);
         }
-    });
+    }
     return (_jsxs("div", { className: cn('kpt-sidenav', className), ...rest, children: [_jsx("div", { className: "kpt-sidenav__scroll", children: scroll }), footers] }));
 }
 /**

package/dist/skeleton/llms.txt

@@ -12,13 +12,13 @@ Import: `import { KptSkeleton } from '@konce-pt/react';`
 ## Props
 - `variant`: 'text' | 'circle' | 'rect' (default 'rect')
 - `width`: string (default '100%'), `height`: string (default '1rem')
-- `lines`: number (default 3) — the number of lines in the `text` variant
+- `lines`: number (default 3) - the number of lines in the `text` variant
 - `className`, `ref` and every other `<span>` prop go to the host
 
 ## The last line is shorter
 In the `text` variant the last line is 60% wide. A stack of full-width rectangles does not read as
 a paragraph, and a paragraph is exactly what it stands in for. A single line (`lines={1}`) keeps
-the full `width` — there is no paragraph to imitate.
+the full `width` - there is no paragraph to imitate.
 
 ## Examples
     <KptSkeleton variant="text" lines={3} />
@@ -29,6 +29,6 @@ the full `width` — there is no paragraph to imitate.
 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
+The host is `aria-hidden="true"` - a placeholder has nothing to announce, and reading out empty
 boxes only adds noise. Announce the wait with `KptSpinner` or `KptProgress` next to it when it
 matters.