@konce-pt/react 0.11.2 → 0.14.0

package/dist/pick-list/pick-list.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type KptLayoutMotion } from '@konce-pt/motion';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptPickListProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'children'>, KptI18nOverrides {
     source?: T[];
@@ -13,13 +14,20 @@ export interface KptPickListProps<T> extends Omit<ComponentPropsWithRef<'div'>,
     targetHeader?: string;
     /** Włącza porządkowanie i przenoszenie elementów metodą przeciągnij-i-upuść. */
     dragdrop?: boolean;
-    /** Szablon elementu — odpowiednik `<ng-template let-item>` z Angulara. */
+    /**
+     * Ruch przy przenoszeniu i przestawianiu elementów: `spring` - element płynie na sprężynie,
+     * `arc` - unosi się i leci po łuku, `morph` - natywny morf przeglądarki (View Transitions),
+     * `none` - bez ruchu. Bez wartości bierze `layout` z `KptMotionProvider` (domyślnie `spring`);
+     * `<KptMotionProvider enabled={false}>` i systemowe "ogranicz ruch" wyłączają go zawsze.
+     */
+    layoutMotion?: KptLayoutMotion;
+    /** Szablon elementu - odpowiednik `<ng-template let-item>` z Angulara. */
     renderItem: (item: T, index: number) => ReactNode;
 }
 /**
- * PickList — transfer elementów między dwiema listami. Klik zaznacza, przyciski pośrodku
+ * PickList - transfer elementów między dwiema listami. Klik zaznacza, przyciski pośrodku
  * przenoszą zaznaczone albo wszystko, dwuklik przerzuca pojedynczy element na drugą stronę.
- * Z `dragdrop` dochodzi przeciąganie — porządkowanie wewnątrz panelu i przenoszenie na
+ * Z `dragdrop` dochodzi przeciąganie - porządkowanie wewnątrz panelu i przenoszenie na
  * konkretną pozycję drugiego panelu.
  *
  * Każda lista to `listbox` z wielokrotnym wyborem i jednym przystankiem Tab (roving tabindex):
@@ -34,4 +42,4 @@ export interface KptPickListProps<T> extends Omit<ComponentPropsWithRef<'div'>,
  *   renderItem={(item) => item.name}
  * />
  */
-export declare function KptPickList<T>({ source, defaultSource, onSourceChange, target, defaultTarget, onTargetChange, sourceHeader, targetHeader, dragdrop, renderItem, locale, dictionary, className, ref, ...rest }: Readonly<KptPickListProps<T>>): import("react").JSX.Element;
+export declare function KptPickList<T>({ source, defaultSource, onSourceChange, target, defaultTarget, onTargetChange, sourceHeader, targetHeader, dragdrop, layoutMotion, renderItem, locale, dictionary, className, ref, ...rest }: Readonly<KptPickListProps<T>>): import("react").JSX.Element;

package/dist/pick-list/pick-list.js

@@ -1,16 +1,32 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useEffectEvent, useId, useLayoutEffect, useRef, useState, } from 'react';
+import { flushSync } from 'react-dom';
+import { isVisibleInScroller, layoutMotionAllowed, morphKeyed, playKeyedMotion, resolveLayoutMotion, revealInScroller, snapshotKeyed, stopKeyedMotion, } from '@konce-pt/motion';
 import { cn } from "../internal/cn.js";
 import { composeRefs } from "../internal/compose-refs.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
 import { nextMenuIndex } from "../menu/menu-keys.js";
+import { useKptMotion } from "../motion/motion-context.js";
 const EMPTY = [];
+/** Klasy ruchu przenoszenia - reguły we wspólnym CSS komponentu. */
+const MOTION_CLASSES = {
+    ghostClass: 'kpt-pick-list__ghost',
+    hiddenClass: 'kpt-pick-list__item--waiting',
+    movingClass: 'kpt-pick-list__item--moving',
+};
+/** Klasa View Transitions dla morfu. */
+const MORPH_CLASS = 'kpt-pick-list-morph';
+/** Przewijany pojemnik wiersza - lista panelu. */
+function scrollerOf(element) {
+    return element.closest('.kpt-pick-list__items');
+}
 /**
- * PickList — transfer elementów między dwiema listami. Klik zaznacza, przyciski pośrodku
+ * PickList - transfer elementów między dwiema listami. Klik zaznacza, przyciski pośrodku
  * przenoszą zaznaczone albo wszystko, dwuklik przerzuca pojedynczy element na drugą stronę.
- * Z `dragdrop` dochodzi przeciąganie — porządkowanie wewnątrz panelu i przenoszenie na
+ * Z `dragdrop` dochodzi przeciąganie - porządkowanie wewnątrz panelu i przenoszenie na
  * konkretną pozycję drugiego panelu.
  *
  * Każda lista to `listbox` z wielokrotnym wyborem i jednym przystankiem Tab (roving tabindex):
@@ -25,7 +41,7 @@ const EMPTY = [];
  *   renderItem={(item) => item.name}
  * />
  */
-export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, target, defaultTarget = EMPTY, onTargetChange, sourceHeader, targetHeader, dragdrop = false, renderItem, locale, dictionary, className, ref, ...rest }) {
+export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, target, defaultTarget = EMPTY, onTargetChange, sourceHeader, targetHeader, dragdrop = false, layoutMotion, renderItem, locale, dictionary, className, ref, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const [left, setLeft] = useControllableState({
         value: source,
@@ -41,18 +57,80 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
     // po obu stronach się przesuwają, a referencja zostaje ta sama.
     const [selLeft, setSelLeft] = useState(new Set());
     const [selRight, setSelRight] = useState(new Set());
-    /** Przeciągany element — strona i pozycja w jej tablicy. */
+    /** Przeciągany element - strona i pozycja w jej tablicy. */
     const [drag, setDrag] = useState(null);
-    /** Element pod kursorem — rysuje wskaźnik miejsca upuszczenia. */
+    /** Element pod kursorem - rysuje wskaźnik miejsca upuszczenia. */
     const [over, setOver] = useState(null);
-    /** Panel, nad którego pustym obszarem jest kursor — upuszczenie tam dopina na koniec. */
+    /** Panel, nad którego pustym obszarem jest kursor - upuszczenie tam dopina na koniec. */
     const [listOver, setListOver] = useState(null);
-    /** Pozycja, która ostatnio miała fokus w każdej liście — ona jest przystankiem Tab. */
+    /** Pozycja, która ostatnio miała fokus w każdej liście - ona jest przystankiem Tab. */
     const [focusLeft, setFocusLeft] = useState(0);
     const [focusRight, setFocusRight] = useState(0);
     /** Pozycja, na którą po renderze trzeba przenieść fokus DOM (klawiatura). */
     const [focusRequest, setFocusRequest] = useState(null);
     const rootRef = useRef(null);
+    const motionConfig = useKptMotion();
+    // `view-transition-name` musi być poprawnym identyfikatorem CSS - `useId` daje dwukropki.
+    const morphPrefix = `kpt-pick-list-${useId().replaceAll(/[^a-zA-Z0-9-]/g, '')}`;
+    /** Który element danych pokazuje każdy wiersz - wiersze mają klucz po indeksie, więc go zmieniają. */
+    const keyOf = useRef(new WeakMap());
+    /** Stan sprzed zmiany, czekający na commit nowego układu. */
+    const pending = useRef(null);
+    /** Elementy, które przy ostatniej zmianie przeszły na drugą stronę - lista przewija się do nich. */
+    const crossed = useRef([]);
+    const stage = () => rootRef.current?.querySelector('.kpt-pick-list') ?? null;
+    const nodes = () => {
+        const root = stage();
+        if (!root)
+            return [];
+        return Array.from(root.querySelectorAll('.kpt-pick-list__items > .kpt-pick-list__item')).flatMap((element) => keyOf.current.has(element) ? [{ key: keyOf.current.get(element), element }] : []);
+    };
+    /** Przewija listę docelową do ostatniego przeniesionego elementu - ląduje tam, gdzie go widać. */
+    const revealCrossed = () => {
+        const last = crossed.current.at(-1);
+        if (last === undefined)
+            return;
+        const node = nodes().find((n) => n.key === last);
+        if (node)
+            revealInScroller(node.element, scrollerOf(node.element));
+    };
+    /**
+     * Zmiana list z ruchem. Stan sprzed zmiany mierzymy, zanim React zmieni DOM - dlatego animujemy
+     * zmiany z interakcji (przyciski, dwuklik, Enter, przeciąganie), a listy podmienione z zewnątrz
+     * przełączają się od razu.
+     */
+    const withMotion = (apply, origin) => {
+        const motion = resolveLayoutMotion(layoutMotion, motionConfig);
+        crossed.current = [];
+        const root = stage();
+        if (motion === 'none' || !root || !layoutMotionAllowed()) {
+            apply();
+            return;
+        }
+        if (motion === 'morph') {
+            morphKeyed(nodes(), nodes, morphPrefix, MORPH_CLASS, () => {
+                flushSync(apply);
+                revealCrossed();
+            }, (el) => isVisibleInScroller(el, scrollerOf(el)));
+            return;
+        }
+        pending.current = { first: snapshotKeyed(root, nodes(), scrollerOf), motion, origin };
+        stopKeyedMotion(root, MOTION_CLASSES);
+        apply();
+    };
+    // Nowy układ jest już w DOM (a `keyOf` zaktualizowany refami) - gramy loty od zapamiętanego stanu.
+    const playPending = useEffectEvent(() => {
+        const job = pending.current;
+        pending.current = null;
+        const root = stage();
+        if (!job || !root)
+            return;
+        revealCrossed();
+        playKeyedMotion(root, job.first, nodes(), { motion: job.motion, scrollerOf, ...MOTION_CLASSES }, job.origin);
+    });
+    useLayoutEffect(() => {
+        playPending();
+    }, [left, right]);
     const listOf = (side) => (side === 'source' ? left : right);
     const setListOf = (side) => (side === 'source' ? setLeft : setRight);
     const selectionOf = (side) => (side === 'source' ? selLeft : selRight);
@@ -60,15 +138,16 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
     const other = (side) => (side === 'source' ? 'target' : 'source');
     const focusOf = (side) => (side === 'source' ? focusLeft : focusRight);
     const setFocusOf = (side) => (side === 'source' ? setFocusLeft : setFocusRight);
-    /** Przystanek Tab listy — ostatnio skupiona pozycja, przycięta do długości listy. */
+    /** Przystanek Tab listy - ostatnio skupiona pozycja, przycięta do długości listy. */
     const tabIndexOf = (side) => Math.min(focusOf(side), listOf(side).length - 1);
+    // Żądanie nie jest zerowane w efekcie (setState w efekcie = dodatkowy przebieg renderu): każde jest
+    // nowym obiektem, więc efekt rusza raz na żądanie, także o ten sam indeks.
     useEffect(() => {
         if (!focusRequest)
             return;
         const list = rootRef.current?.querySelectorAll('.kpt-pick-list__items')[focusRequest.side === 'source' ? 0 : 1];
         const options = list?.querySelectorAll('[role="option"]') ?? [];
         options[Math.min(focusRequest.index, options.length - 1)]?.focus();
-        setFocusRequest(null);
     }, [focusRequest]);
     const focusItem = (side, index) => {
         setFocusOf(side)(index);
@@ -82,7 +161,21 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
             next.add(item);
         setSelectionOf(side)(next);
     };
-    const move = (from, all) => {
+    const headerOf = (side) => side === 'source' ? (sourceHeader ?? t('pickList.available')) : (targetHeader ?? t('pickList.selected'));
+    /** Treść regionu `aria-live` po przeniesieniu. */
+    const [announcement, setAnnouncement] = useState('');
+    /**
+     * Ogłasza przeniesienie. Ten sam tekst drugi raz pod rząd nie zostałby przeczytany (region
+     * reaguje na zmianę), więc naprzemiennie dokładamy niewidoczną spację.
+     */
+    const announce = (count, to) => {
+        const text = t('pickList.moved', { count, list: headerOf(to) });
+        setAnnouncement((current) => (current === text ? text + '\u00a0' : text));
+    };
+    const move = (from, all, origin) => {
+        withMotion(() => moveNow(from, all), origin);
+    };
+    const moveNow = (from, all) => {
         const to = other(from);
         const fromItems = listOf(from);
         const selection = selectionOf(from);
@@ -91,7 +184,9 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
             return;
         setListOf(from)(fromItems.filter((item) => !moving.includes(item)));
         setListOf(to)([...listOf(to), ...moving]);
+        crossed.current = moving;
         setSelectionOf(from)(new Set());
+        announce(moving.length, to);
     };
     /** Przenosi jeden element między panelami, wstawiając go pod wskazanym indeksem. */
     const transfer = (fromSide, fromIndex, toSide, toIndex) => {
@@ -103,7 +198,11 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
         toItems.splice(toIndex, 0, moved);
         setListOf(fromSide)(fromItems);
         setListOf(toSide)(toItems);
-        // Element opuszcza panel — jego zaznaczenie po tamtej stronie przestaje cokolwiek znaczyć.
+        if (fromSide !== toSide) {
+            crossed.current = [moved];
+            announce(1, toSide);
+        }
+        // Element opuszcza panel - jego zaznaczenie po tamtej stronie przestaje cokolwiek znaczyć.
         const selection = selectionOf(fromSide);
         if (selection.has(moved)) {
             const next = new Set(selection);
@@ -112,12 +211,12 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
         }
     };
     /** Dwuklik: przenosi wyłącznie klikniętą pozycję, niezależnie od zaznaczenia. */
-    const moveOne = (from, item) => {
+    const moveOne = (from, item, origin) => {
         const index = listOf(from).indexOf(item);
         if (index === -1)
             return;
         const to = other(from);
-        transfer(from, index, to, listOf(to).length);
+        withMotion(() => transfer(from, index, to, listOf(to).length), origin);
     };
     const onItemKeyDown = (side, index, item, event) => {
         if (event.key === ' ') {
@@ -127,8 +226,8 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
         }
         if (event.key === 'Enter') {
             event.preventDefault();
-            moveOne(side, item);
-            // Pozycja zniknęła z listy — fokus zostaje w tym samym miejscu listy, na następnej.
+            moveOne(side, item, event.currentTarget);
+            // Pozycja zniknęła z listy - fokus zostaje w tym samym miejscu listy, na następnej.
             focusItem(side, index);
             return;
         }
@@ -166,20 +265,21 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
         clearDrag();
         if (from === null)
             return;
+        const origin = event.currentTarget;
         if (from.side !== side) {
-            transfer(from.side, from.index, side, index);
+            withMotion(() => transfer(from.side, from.index, side, index), origin);
             return;
         }
         if (from.index === index)
             return;
-        // Indeks celu liczony na tablicy sprzed usunięcia — element ląduje na pozycji tego,
+        // Indeks celu liczony na tablicy sprzed usunięcia - element ląduje na pozycji tego,
         // na który go upuszczono (ten sam wzór co przestawianie kolumn w KptDataTable).
         const next = [...listOf(side)];
         const [moved] = next.splice(from.index, 1);
         if (moved === undefined)
             return;
         next.splice(index, 0, moved);
-        setListOf(side)(next);
+        withMotion(() => setListOf(side)(next), origin);
     };
     const onListDragOver = (side, event) => {
         if (drag === null)
@@ -194,8 +294,9 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
         clearDrag();
         if (from === null)
             return;
+        const origin = event.currentTarget;
         if (from.side !== side) {
-            transfer(from.side, from.index, side, listOf(side).length);
+            withMotion(() => transfer(from.side, from.index, side, listOf(side).length), origin);
             return;
         }
         const next = [...listOf(side)];
@@ -203,16 +304,19 @@ export function KptPickList({ source, defaultSource = EMPTY, onSourceChange, tar
         if (moved === undefined)
             return;
         next.push(moved);
-        setListOf(side)(next);
+        withMotion(() => setListOf(side)(next), origin);
     };
     const column = (side) => {
         const items = listOf(side);
         const selection = selectionOf(side);
-        const header = side === 'source' ? (sourceHeader ?? t('pickList.available')) : (targetHeader ?? t('pickList.selected'));
+        const header = headerOf(side);
         return (_jsxs("div", { className: "kpt-pick-list__col", children: [_jsx("div", { className: "kpt-pick-list__header", children: header }), _jsx("ul", { className: cn('kpt-pick-list__items', listOver === side && 'is-dragover'), role: "listbox", "aria-multiselectable": "true", "aria-label": header, onDragOver: (event) => onListDragOver(side, event), onDragLeave: () => setListOver(null), onDrop: (event) => onListDrop(side, event), children: items.map((item, index) => {
                         const dragging = drag?.side === side && drag.index === index;
-                        return (_jsx("li", { className: cn('kpt-pick-list__item', selection.has(item) && 'is-selected', dragging && 'is-dragging', dragdrop && 'kpt-pick-list__item--draggable', over?.side === side && over.index === index && !dragging && 'kpt-pick-list__item--dragover'), role: "option", "aria-selected": selection.has(item), tabIndex: index === tabIndexOf(side) ? 0 : -1, onFocus: () => setFocusOf(side)(index), onKeyDown: (event) => onItemKeyDown(side, index, item, event), draggable: dragdrop || undefined, onClick: () => toggle(side, item), onDoubleClick: () => moveOne(side, item), onDragStart: (event) => onDragStart(side, index, event), onDragOver: (event) => onDragOver(side, index, event), onDragLeave: () => setOver(null), onDrop: (event) => onDrop(side, index, event), onDragEnd: clearDrag, children: renderItem(item, index) }, index));
+                        return (_jsx("li", { ref: (element) => {
+                                if (element)
+                                    keyOf.current.set(element, item);
+                            }, className: cn('kpt-pick-list__item', selection.has(item) && 'is-selected', dragging && 'is-dragging', dragdrop && 'kpt-pick-list__item--draggable', over?.side === side && over.index === index && !dragging && 'kpt-pick-list__item--dragover'), role: "option", "aria-selected": selection.has(item), tabIndex: index === tabIndexOf(side) ? 0 : -1, onFocus: () => setFocusOf(side)(index), onKeyDown: (event) => onItemKeyDown(side, index, item, event), draggable: dragdrop || undefined, onClick: () => toggle(side, item), onDoubleClick: (event) => moveOne(side, item, event.currentTarget), onDragStart: (event) => onDragStart(side, index, event), onDragOver: (event) => onDragOver(side, index, event), onDragLeave: () => setOver(null), onDrop: (event) => onDrop(side, index, event), onDragEnd: clearDrag, children: renderItem(item, index) }, index));
                     }) })] }));
     };
-    return (_jsx("div", { ref: composeRefs(rootRef, ref), className: cn('kpt-pick-list-host', className), ...rest, children: _jsxs("div", { className: "kpt-pick-list", children: [column('source'), _jsxs("div", { className: "kpt-pick-list__controls", children: [_jsxs("button", { type: "button", "aria-label": t('pickList.moveAllRight'), onClick: () => move('source', true), children: [_jsx(KptIcon, { name: "chevron-right" }), _jsx(KptIcon, { name: "chevron-right" })] }), _jsx("button", { type: "button", "aria-label": t('pickList.moveRight'), onClick: () => move('source', false), children: _jsx(KptIcon, { name: "chevron-right" }) }), _jsx("button", { type: "button", "aria-label": t('pickList.moveLeft'), onClick: () => move('target', false), children: _jsx(KptIcon, { name: "chevron-left" }) }), _jsxs("button", { type: "button", "aria-label": t('pickList.moveAllLeft'), onClick: () => move('target', true), children: [_jsx(KptIcon, { name: "chevron-left" }), _jsx(KptIcon, { name: "chevron-left" })] })] }), column('target')] }) }));
+    return (_jsxs("div", { ref: composeRefs(rootRef, ref), className: cn('kpt-pick-list-host', className), ...rest, children: [_jsxs("div", { className: "kpt-pick-list", children: [column('source'), _jsxs("div", { className: "kpt-pick-list__controls", children: [_jsxs("button", { type: "button", "aria-label": t('pickList.moveAllRight'), "aria-disabled": !left.length || undefined, onClick: (event) => move('source', true, event.currentTarget), children: [_jsx(KptIcon, { name: "chevron-right" }), _jsx(KptIcon, { name: "chevron-right" })] }), _jsx("button", { type: "button", "aria-label": t('pickList.moveRight'), "aria-disabled": !selLeft.size || undefined, onClick: (event) => move('source', false, event.currentTarget), children: _jsx(KptIcon, { name: "chevron-right" }) }), _jsx("button", { type: "button", "aria-label": t('pickList.moveLeft'), "aria-disabled": !selRight.size || undefined, onClick: (event) => move('target', false, event.currentTarget), children: _jsx(KptIcon, { name: "chevron-left" }) }), _jsxs("button", { type: "button", "aria-label": t('pickList.moveAllLeft'), "aria-disabled": !right.length || undefined, onClick: (event) => move('target', true, event.currentTarget), children: [_jsx(KptIcon, { name: "chevron-left" }), _jsx(KptIcon, { name: "chevron-left" })] })] }), column('target')] }), _jsx("p", { className: "kpt-visually-hidden", "aria-live": "polite", children: announcement })] }));
 }

package/dist/popover/llms.txt

@@ -1,20 +1,20 @@
 # KptPopover (@konce-pt/react)
 
-Any content in a bubble pinned to its trigger — richer than a tooltip.
+Any content in a bubble pinned to its trigger - richer than a tooltip.
 Import: `import { KptPopover } from '@konce-pt/react';`
 
 ## DOM
     <span class="kpt-popover-host">
-      <span class="kpt-popover__trigger">…trigger…</span>
+      <span class="kpt-popover__trigger">...trigger...</span>
     </span>
     <!-- while open, in a portal on document.body: -->
-    <div class="kpt-popover__panel" role="dialog">…children…</div>
+    <div class="kpt-popover__panel" role="dialog">...children...</div>
 
 ## Props
-- `trigger`: ReactNode — the element that opens the bubble, rendered in place
-- `children`: ReactNode — the panel content
-- `open` / `defaultOpen` / `onOpenChange` — controlled or uncontrolled
-- `placement`: 'bottom' (default) | 'top' — the preferred side; it flips when there is no room
+- `trigger`: ReactNode - the element that opens the bubble, rendered in place
+- `children`: ReactNode - the panel content
+- `open` / `defaultOpen` / `onOpenChange` - controlled or uncontrolled
+- `placement`: 'bottom' (default) | 'top' - the preferred side; it flips when there is no room
 - `className`, `ref` and every other `<span>` prop go to the host
 
 ## The panel is a portal
@@ -22,7 +22,7 @@ The Angular port stands on CDK Overlay. Here the panel renders into a portal on
 with the same behaviour: positioned below the trigger, flipping above when there is no room, closed
 by a click outside or by Escape, and following scroll and resize.
 
-Clicking the trigger while the bubble is open closes it and does not reopen it — the transparent
+Clicking the trigger while the bubble is open closes it and does not reopen it - the transparent
 backdrop takes that click, exactly as the CDK backdrop does.
 
 ## Examples
@@ -43,7 +43,10 @@ The panel is `role="dialog"` with an `id` the trigger points to.
 
 ## Focus and keyboard
 The control inside the trigger slot gets `aria-haspopup="dialog"`, a live `aria-expanded` and, while
-open, `aria-controls` — on the real `<button>`, not on the wrapper. Opening moves focus to the first
+open, `aria-controls` - on the real `<button>`, not on the wrapper. Opening moves focus to the first
 interactive element of the bubble; `Escape` or a click outside closes it, and focus returns to the
-trigger when it was inside the bubble. Focus is not trapped — the popover is supporting content, not
+trigger when it was inside the bubble. Focus is not trapped - the popover is supporting content, not
 a modal.
+
+## Name and Escape
+Give the panel `ariaLabel` - it is a `role="dialog"`. Escape closes only the top-most panel and does not reach an enclosing `<dialog>`, so a popover inside a dialog closes alone.

package/dist/popover/popover.d.ts

@@ -1,6 +1,6 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
 export interface KptPopoverProps extends Omit<ComponentPropsWithRef<'span'>, 'content'> {
-    /** Element otwierający dymek — renderowany w miejscu popovera. */
+    /** Element otwierający dymek - renderowany w miejscu popovera. */
     trigger: ReactNode;
     /** Treść panelu. */
     children?: ReactNode;
@@ -9,9 +9,11 @@ export interface KptPopoverProps extends Omit<ComponentPropsWithRef<'span'>, 'co
     onOpenChange?: (open: boolean) => void;
     /** Preferowana strona dymka; gdy brakuje miejsca, przechodzi na drugą. */
     placement?: 'bottom' | 'top';
+    /** Nazwa panelu (`role="dialog"`) - okno bez nazwy czytnik ogłasza jako samo "okno dialogowe". */
+    ariaLabel?: string;
 }
 /**
- * Popover — dowolna treść w dymku przypiętym do wyzwalacza (bogatszy niż tooltip).
+ * Popover - dowolna treść w dymku przypiętym do wyzwalacza (bogatszy niż tooltip).
  *
  * Port Angulara stoi na CDK Overlay; tutaj panel renderuje się w portalu do `document.body`,
  * z tym samym zachowaniem: pozycja pod wyzwalaczem (albo nad nim przy `placement="top"`)
@@ -23,7 +25,7 @@ export interface KptPopoverProps extends Omit<ComponentPropsWithRef<'span'>, 'co
  *
  * @example
  * <KptPopover trigger={<KptButton variant="outline">Szczegóły</KptButton>}>
- *   <div>Bogata treść popovera…</div>
+ *   <div>Bogata treść popovera...</div>
  * </KptPopover>
  */
-export declare function KptPopover({ trigger, children, open, defaultOpen, onOpenChange, placement, className, ...rest }: Readonly<KptPopoverProps>): import("react").JSX.Element;
+export declare function KptPopover({ trigger, children, open, defaultOpen, onOpenChange, placement, ariaLabel, className, ...rest }: Readonly<KptPopoverProps>): import("react").JSX.Element;

package/dist/popover/popover.js

@@ -1,13 +1,14 @@
+'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";
 import { useKptId } from "../internal/use-id.js";
-/** Elementy, które same przyjmują fokus — pierwszy z nich dostaje fokus po otwarciu dymka. */
+/** Elementy, które same przyjmują fokus - pierwszy z nich dostaje fokus po otwarciu dymka. */
 const FOCUSABLE = 'a[href], button:not(:disabled), input:not(:disabled), select, textarea, [tabindex]:not([tabindex="-1"])';
 /**
- * Popover — dowolna treść w dymku przypiętym do wyzwalacza (bogatszy niż tooltip).
+ * Popover - dowolna treść w dymku przypiętym do wyzwalacza (bogatszy niż tooltip).
  *
  * Port Angulara stoi na CDK Overlay; tutaj panel renderuje się w portalu do `document.body`,
  * z tym samym zachowaniem: pozycja pod wyzwalaczem (albo nad nim przy `placement="top"`)
@@ -19,11 +20,17 @@ const FOCUSABLE = 'a[href], button:not(:disabled), input:not(:disabled), select,
  *
  * @example
  * <KptPopover trigger={<KptButton variant="outline">Szczegóły</KptButton>}>
- *   <div>Bogata treść popovera…</div>
+ *   <div>Bogata treść popovera...</div>
  * </KptPopover>
  */
-export function KptPopover({ trigger, children, open, defaultOpen = false, onOpenChange, placement = 'bottom', className, ...rest }) {
+export function KptPopover({ trigger, children, open, defaultOpen = false, onOpenChange, placement = 'bottom', ariaLabel = '', className, ...rest }) {
     const triggerRef = useRef(null);
+    /** Kotwica panelu - w stanie, bo czyta ją render; ref zostaje dla handlerów. */
+    const [anchor, setAnchor] = useState(null);
+    const setTrigger = useCallback((element) => {
+        triggerRef.current = element;
+        setAnchor(element);
+    }, []);
     const panelRef = useRef(null);
     const panelId = useKptId(undefined, 'kpt-popover');
     const [isOpen, setOpen] = useControllableState({
@@ -44,7 +51,7 @@ export function KptPopover({ trigger, children, open, defaultOpen = false, onOpe
         else
             control.removeAttribute('aria-controls');
     }, [isOpen, trigger, panelId]);
-    // Fokus do dymka klatkę później — `KptOverlay` trzyma panel niewidoczny, dopóki go nie zmierzy.
+    // Fokus do dymka klatkę później - `KptOverlay` trzyma panel niewidoczny, dopóki go nie zmierzy.
     useEffect(() => {
         if (!isOpen)
             return;
@@ -58,5 +65,5 @@ export function KptPopover({ trigger, children, open, defaultOpen = false, onOpe
             findControl()?.focus();
         setOpen(false);
     }, [setOpen]);
-    return (_jsxs("span", { className: cn('kpt-popover-host', className), ...rest, children: [_jsx("span", { className: "kpt-popover__trigger", ref: triggerRef, onClick: () => setOpen(!isOpen), children: trigger }), _jsx(KptOverlay, { open: isOpen, anchor: triggerRef.current, onClose: close, offset: 6, preferAbove: placement === 'top', children: _jsx("div", { ref: panelRef, id: panelId, className: "kpt-popover__panel", role: "dialog", children: children }) })] }));
+    return (_jsxs("span", { className: cn('kpt-popover-host', className), ...rest, children: [_jsx("span", { className: "kpt-popover__trigger", ref: setTrigger, onClick: () => setOpen(!isOpen), children: trigger }), _jsx(KptOverlay, { open: isOpen, anchor: anchor, onClose: close, offset: 6, preferAbove: placement === 'top', children: _jsx("div", { ref: panelRef, id: panelId, className: "kpt-popover__panel", role: "dialog", "aria-label": ariaLabel || undefined, children: children }) })] }));
 }

package/dist/progress/llms.txt

@@ -1,12 +1,12 @@
 # KptProgress (@konce-pt/react)
 
-A progress indicator — linear or circular, determinate (`min`–`max`) or indeterminate (`value` = null).
+A progress indicator - linear or circular, determinate (`min`-`max`) or indeterminate (`value` = null).
 Import: `import { KptProgress } from '@konce-pt/react';`
 
 ## DOM
     <!-- linear, with a label, a buffer and a value -->
     <div class="kpt-progress-host" data-type="linear" data-size="md" data-variant="primary" data-label-position="top">
-      <span class="kpt-progress__label">Loading…</span>
+      <span class="kpt-progress__label">Loading...</span>
       <div class="kpt-progress__linear" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="80">
         <div class="kpt-progress__buffer" style="width: 92%"></div>
         <div class="kpt-progress__bar" style="width: 80%"></div>
@@ -23,28 +23,28 @@ Import: `import { KptProgress } from '@konce-pt/react';`
       <span class="kpt-progress__value" aria-hidden="true">75%</span>
     </div>
 
-The label, the track and the value are siblings straight under the host — there is no wrapper element.
+The label, the track and the value are siblings straight under the host - there is no wrapper element.
 `data-variant`, `data-type`, `data-size` and `data-label-position` all sit on the host, which is also
 where the private `--_color` and `--_thickness` are resolved. This markup matches the Angular port
 element for element, so both share one stylesheet.
 
 ## Props
-- `value`: number | null (default null) — a value on the `min`–`max` scale, or null for indeterminate
+- `value`: number | null (default null) - a value on the `min`-`max` scale, or null for indeterminate
 - `min`: number (default 0); `max`: number (default 100)
 - `variant`: 'primary' | 'success' | 'danger' | 'warning' | 'info' (default 'primary')
 - `type`: 'linear' | 'circular' (default 'linear')
-- `size`: 'sm' | 'md' | 'lg' (default 'md') — track thickness, and arc width on the circular variant
-- `diameter`: number (default 40) — the circular variant's size in pixels
-- `bufferValue`: number | null (default null) — a second, dimmed bar behind the main one; linear only
-- `showValue`: boolean (default false) — turns the value area on; `children` needs it too
+- `size`: 'sm' | 'md' | 'lg' (default 'md') - track thickness, and arc width on the circular variant
+- `diameter`: number (default 40) - the circular variant's size in pixels
+- `bufferValue`: number | null (default null) - a second, dimmed bar behind the main one; linear only
+- `showValue`: boolean (default false) - turns the value area on; `children` needs it too
 - `valueFormat`: 'percent' | 'fraction' | 'none' (default 'percent')
-- `label`: string — descriptive text next to the bar; it also becomes the `aria-label`
-- `labelPosition`: 'top' | 'bottom' | 'end' (default 'top') — ignored by the circular variant
-- `locale`, `dictionary` — per-instance dictionary overrides
+- `label`: string - descriptive text next to the bar; it also becomes the `aria-label`
+- `labelPosition`: 'top' | 'bottom' | 'end' (default 'top') - ignored by the circular variant
+- `locale`, `dictionary` - per-instance dictionary overrides
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Value label
-`showValue` opens the value area; `valueFormat` decides what goes in it — `percent` renders `80%`,
+`showValue` opens the value area; `valueFormat` decides what goes in it - `percent` renders `80%`,
 `fraction` renders `152 / 160` from `value` and `max`, `none` leaves it empty. Both strings come from
 the `KptMessages` dictionary (`progress.percent`, `progress.fraction`), so a new locale can reshape them.
 
@@ -57,17 +57,17 @@ the accessible name.
 
 ## How the arc is drawn
 The circle lives in a fixed `viewBox="0 0 40 40"` with `r=16`, so the circumference is computed from
-that radius, not from `diameter` — the SVG scales, the maths does not change. The arc is the dash
+that radius, not from `diameter` - the SVG scales, the maths does not change. The arc is the dash
 offset: full circumference means empty, zero means complete. `size` only changes `stroke-width`, and
 the widest step still fits inside the box, so no arc is ever clipped.
 
-Values outside the range are clamped rather than rejected, `max` ≤ `min` collapses to zero, and the
-buffer is never allowed behind the main bar — a computed percentage that briefly overshoots cannot
+Values outside the range are clamped rather than rejected, `max` <= `min` collapses to zero, and the
+buffer is never allowed behind the main bar - a computed percentage that briefly overshoots cannot
 break the drawing.
 
 ## Examples
     <KptProgress value={60} />
-    <KptProgress value={80} label="Loading…" showValue />
+    <KptProgress value={80} label="Loading..." showValue />
     <KptProgress value={152} max={160} size="lg" showValue valueFormat="fraction" labelPosition="bottom" />
     <KptProgress value={65} showValue labelPosition="end" />
     <KptProgress value={38} bufferValue={62} />
@@ -91,5 +91,5 @@ leaves the value out, which is how a screen reader learns the progress is unknow
 announcing the raw number as a percentage. The visible value is `aria-hidden`, so it is never read
 twice. The accessible name comes from `label`, or from the dictionary when there is none.
 
-Under `prefers-reduced-motion: reduce` the indeterminate animation slows down instead of stopping —
+Under `prefers-reduced-motion: reduce` the indeterminate animation slows down instead of stopping -
 a frozen progress indicator reads as a hung application.

package/dist/progress/progress.d.ts

@@ -3,12 +3,12 @@ import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export type KptProgressVariant = 'primary' | 'success' | 'danger' | 'warning' | 'info';
 export type KptProgressType = 'linear' | 'circular';
 export type KptProgressSize = 'sm' | 'md' | 'lg';
-/** Postać etykiety wartości: procent, „ile z ilu" albo brak. */
+/** Postać etykiety wartości: procent, "ile z ilu" albo brak. */
 export type KptProgressValueFormat = 'percent' | 'fraction' | 'none';
 /** Gdzie siada wiersz etykiety względem paska (tylko `type="linear"`). */
 export type KptProgressLabelPosition = 'top' | 'bottom' | 'end';
 export interface KptProgressProps extends ComponentPropsWithRef<'div'>, KptI18nOverrides {
-    /** Wartość w skali `min`–`max` albo `null` = postęp nieokreślony. */
+    /** Wartość w skali `min`-`max` albo `null` = postęp nieokreślony. */
     value?: number | null;
     min?: number;
     max?: number;
@@ -18,26 +18,26 @@ export interface KptProgressProps extends ComponentPropsWithRef<'div'>, KptI18nO
     size?: KptProgressSize;
     /** Średnica wariantu kołowego w pikselach. */
     diameter?: number;
-    /** Postęp buforowania — drugi, przygaszony pasek pod głównym (tylko liniowy). */
+    /** Postęp buforowania - drugi, przygaszony pasek pod głównym (tylko liniowy). */
     bufferValue?: number | null;
-    /** Włącza obszar etykiety wartości — razem z nim renderuje się `children`. */
+    /** Włącza obszar etykiety wartości - razem z nim renderuje się `children`. */
     showValue?: boolean;
     valueFormat?: KptProgressValueFormat;
     /** Tekst opisowy obok paska; służy też za `aria-label`. */
     label?: string;
     labelPosition?: KptProgressLabelPosition;
-    /** Zastępuje sformatowaną wartość — wymaga `showValue`. */
+    /** Zastępuje sformatowaną wartość - wymaga `showValue`. */
     children?: ReactNode;
 }
 /**
- * Wskaźnik postępu — liniowy lub kołowy, określony (`min`–`max`) albo nieokreślony (`value` = null).
+ * Wskaźnik postępu - liniowy lub kołowy, określony (`min`-`max`) albo nieokreślony (`value` = null).
  *
  * Etykietę wartości włącza `showValue`; `children` zastępuje sformatowaną wartość,
  * więc w środku koła można pokazać cokolwiek.
  *
  * @example
  * <KptProgress value={60} />
- * <KptProgress value={80} label="Ładowanie…" showValue />
+ * <KptProgress value={80} label="Ładowanie..." showValue />
  * <KptProgress value={152} max={160} showValue valueFormat="fraction" labelPosition="bottom" />
  * <KptProgress value={38} bufferValue={62} />
  * <KptProgress type="circular" value={75} variant="success" showValue />