@konce-pt/react 0.11.2 → 0.14.0

package/dist/tooltip/tooltip.js

@@ -1,11 +1,26 @@
+'use client';
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { cloneElement, isValidElement, useCallback, useEffect, useId, useRef } from 'react';
 import { composeRefs } from "../internal/compose-refs.js";
-/** Elementy, które same przyjmują fokus — na nie trafia `aria-describedby`. */
+import { isDevBuild } from "../internal/dev.js";
+/** Elementy, które same przyjmują fokus - na nie trafia `aria-describedby`. */
 const FOCUSABLE = 'a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])';
 /** Ile czasu ma wskaźnik na przejście z elementu na dymek, zanim ten zniknie (WCAG 1.4.13). */
 const HIDE_DELAY_MS = 120;
-/** Strona przeciwna i dwie boczne — kolejność prób, gdy zadana strona się nie nadaje. */
+/**
+ * Zwłoka pokazania pod wskaźnikiem - przejazd myszą po pasku ikon nie zapala po kolei wszystkich
+ * dymków. Fokus z klawiatury pokazuje dymek od razu.
+ */
+const SHOW_DELAY_MS = 300;
+/**
+ * Gdzie dokleić dymek: do najbliższego otwartego `<dialog>` albo popovera hosta, inaczej do `body`.
+ * Modalny `<dialog>` leży w warstwie szczytowej - dymek z `body` byłby pod nim niewidoczny.
+ * Bliźniak w porcie Angulara.
+ */
+function tooltipContainer(host) {
+    return host.closest('dialog[open], [popover]') ?? host.ownerDocument.body;
+}
+/** Strona przeciwna i dwie boczne - kolejność prób, gdy zadana strona się nie nadaje. */
 const FALLBACKS = {
     top: ['top', 'bottom', 'right', 'left'],
     bottom: ['bottom', 'top', 'right', 'left'],
@@ -15,10 +30,10 @@ const FALLBACKS = {
 /**
  * Ustawia dymek przy hoście, na pierwszej stronie z `FALLBACKS`, która się nadaje: dymek mieści się
  * w oknie, a krawędź hosta od tej strony nie jest niczym przykryta (przyklejony nagłówek, menu, panel
- * — sprawdzane `elementFromPoint` tuż przy krawędzi). Bez tego dymek przycisku wsuniętego pod
+ * - sprawdzane `elementFromPoint` tuż przy krawędzi). Bez tego dymek przycisku wsuniętego pod
  * nagłówek wyskakiwał nad nagłówkiem, odcięty od tego, co opisuje. Gdy żadna strona się nie nadaje,
  * zostaje zadana. Na koniec dymek jest dociśnięty do okna z marginesem 4 px.
- * Bliźniak tej funkcji żyje w drugim porcie — zmiany w obu naraz.
+ * Bliźniak tej funkcji żyje w drugim porcie - zmiany w obu naraz.
  */
 function placeTooltip(host, tip, preferred) {
     const r = host.getBoundingClientRect();
@@ -41,7 +56,7 @@ function placeTooltip(host, tip, preferred) {
     };
     const fits = (side) => {
         const { top, left } = at(side);
-        // Po osi poprzecznej dymek i tak zostanie dociśnięty do okna — liczy się tylko oś strony.
+        // Po osi poprzecznej dymek i tak zostanie dociśnięty do okna - liczy się tylko oś strony.
         return side === 'top' || side === 'bottom'
             ? top >= margin && top + t.height <= vh - margin
             : left >= margin && left + t.width <= vw - margin;
@@ -63,14 +78,15 @@ function placeTooltip(host, tip, preferred) {
     tip.style.left = `${Math.min(Math.max(margin, left), Math.max(margin, vw - t.width - margin))}px`;
 }
 /**
- * Dymek podpowiedzi pokazywany na hover i focus. Lekki — element dodawany do `body`
- * i pozycjonowany względem dziecka.
+ * Dymek podpowiedzi pokazywany na hover i focus. Lekki - element dodawany do `body` (albo do
+ * otwartego `<dialog>`/popovera dziecka, żeby był widoczny w warstwie szczytowej) i pozycjonowany
+ * względem dziecka. Wygląd daje klasa `.kpt-tooltip` z `@konce-pt/styles` w warstwie `kpt.components`.
  *
  * Port dyrektywy `[kptTooltip]`: nie renderuje własnego opakowania, tylko dokleja handlery
  * i ref do przekazanego elementu, więc drzewo DOM zostaje takie samo jak bez tooltipa.
  *
  * Dostępność (jak w porcie Angulara): tekst trafia do czytników przez trwały, ukryty opis
- * powiązany `aria-describedby` z elementem przyjmującym fokus — pomijany, gdy powtarzałby
+ * powiązany `aria-describedby` z elementem przyjmującym fokus - pomijany, gdy powtarzałby
  * jego nazwę albo przy `onlyWhenTruncated`. `Escape` zamyka dymek, a wskaźnik może na niego
  * przejść bez zniknięcia (WCAG 1.4.13).
  *
@@ -80,9 +96,18 @@ function placeTooltip(host, tip, preferred) {
  */
 export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false, children }) {
     const hostRef = useRef(null);
+    // Dymek przypina się do elementu przez `ref` dziecka. Własny komponent, który nie przekazuje
+    // `ref` do elementu DOM, zostawia hosta pustym - dymek wtedy po cichu nie działa.
+    useEffect(() => {
+        if (isDevBuild() && isValidElement(children) && !hostRef.current) {
+            console.warn('[KptTooltip] Dziecko nie przekazało `ref` do elementu DOM - dymek nie ma się do czego przypiąć.');
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- sprawdzenie raz, po montażu
+    }, []);
     const tipRef = useRef(null);
     const descRef = useRef(null);
     const hideTimer = useRef(undefined);
+    const showTimer = useRef(undefined);
     const descId = `kpt-tooltip-desc-${useId().replace(/[^a-zA-Z0-9]/g, '')}`;
     // Trwały opis dla czytników: dymek powstaje dopiero przy pokazaniu, więc nie da się go
     // wskazać wcześniej. Opis żyje razem z komponentem i aktualizuje się ze zmianą tekstu.
@@ -119,67 +144,98 @@ export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false,
             return;
         placeTooltip(host, tip, position);
     }, [position]);
-    const onKeyDown = useCallback((event) => {
-        if (event.key === 'Escape')
-            hideRef.current();
-    }, []);
+    /** Sprzątanie bieżącego dymka (nasłuchy i element) - ustawiane przy pokazaniu, wołane przy ukryciu. */
+    const cleanupRef = useRef(null);
     const cancelHide = useCallback(() => {
         if (hideTimer.current !== undefined)
             clearTimeout(hideTimer.current);
         hideTimer.current = undefined;
     }, []);
+    const cancelShow = useCallback(() => {
+        if (showTimer.current !== undefined)
+            clearTimeout(showTimer.current);
+        showTimer.current = undefined;
+    }, []);
     const hide = useCallback(() => {
         cancelHide();
-        window.removeEventListener('scroll', reposition, true);
-        window.removeEventListener('resize', reposition);
-        document.removeEventListener('keydown', onKeyDown);
-        tipRef.current?.remove();
-        tipRef.current = null;
-    }, [reposition, onKeyDown, cancelHide]);
-    // `onKeyDown` potrzebuje aktualnego `hide`, a `hide` zdejmuje `onKeyDown` — ref przerywa krąg.
-    const hideRef = useRef(hide);
-    hideRef.current = hide;
+        cancelShow();
+        cleanupRef.current?.();
+        cleanupRef.current = null;
+    }, [cancelHide, cancelShow]);
     const scheduleHide = useCallback(() => {
+        cancelShow();
         cancelHide();
-        hideTimer.current = setTimeout(() => hideRef.current(), HIDE_DELAY_MS);
-    }, [cancelHide]);
-    useEffect(() => () => hideRef.current(), []);
+        hideTimer.current = setTimeout(hide, HIDE_DELAY_MS);
+    }, [cancelHide, cancelShow, hide]);
+    useEffect(() => hide, [hide]);
     const show = useCallback(() => {
         cancelHide();
-        if (tipRef.current || !text)
+        cancelShow();
+        const host = hostRef.current;
+        if (tipRef.current || !text || !host)
             return;
         // Sprawdzamy dopiero teraz, a nie przy renderze: dzięki temu wynik jest zawsze aktualny
         // po zmianie szerokości czy powiększenia, bez żadnych obserwatorów.
-        if (onlyWhenTruncated && !isTruncated(hostRef.current))
+        if (onlyWhenTruncated && !isTruncated(host))
             return;
         const tip = document.createElement('div');
         tip.className = 'kpt-tooltip';
         tip.setAttribute('role', 'tooltip');
-        // Treść czytnik dostaje z trwałego opisu — dymek by ją zdublował.
+        // Treść czytnik dostaje z trwałego opisu - dymek by ją zdublował.
         if (descRef.current)
             tip.setAttribute('aria-hidden', 'true');
         tip.textContent = text;
-        tip.style.cssText =
-            'position:fixed;z-index:1400;max-width:16rem;padding:0.35rem 0.6rem;' +
-                'border-radius:var(--kpt-radius-sm,0.25rem);font-size:var(--kpt-font-size-xs,0.75rem);' +
-                'line-height:1.4;background:var(--kpt-color-on-surface);color:var(--kpt-color-surface);' +
-                'box-shadow:var(--kpt-elevation-2);opacity:0;transition:opacity 120ms;';
+        // Inline tylko to, bez czego dymek nie stanie przy hoście; wygląd daje klasa w `@layer`.
+        tip.style.position = 'fixed';
         tip.addEventListener('mouseenter', cancelHide);
         tip.addEventListener('mouseleave', scheduleHide);
-        document.body.appendChild(tip);
+        tooltipContainer(host).appendChild(tip);
         tipRef.current = tip;
         reposition();
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape')
+                hide();
+        };
         // Faza przechwytywania łapie także przewijanie zagnieżdżonych kontenerów, bo zdarzenie
         // `scroll` elementu się nie propaguje.
         window.addEventListener('scroll', reposition, true);
         window.addEventListener('resize', reposition);
         document.addEventListener('keydown', onKeyDown);
-        requestAnimationFrame(() => {
-            if (tipRef.current)
-                tipRef.current.style.opacity = '1';
+        const frame = requestAnimationFrame(() => {
+            tip.dataset['visible'] = '';
         });
-    }, [text, onlyWhenTruncated, reposition, onKeyDown, cancelHide, scheduleHide]);
-    /** Fokus przeszedł do innego elementu w obrębie hosta — dymek zostaje. */
+        cleanupRef.current = () => {
+            cancelAnimationFrame(frame);
+            window.removeEventListener('scroll', reposition, true);
+            window.removeEventListener('resize', reposition);
+            document.removeEventListener('keydown', onKeyDown);
+            tip.remove();
+            tipRef.current = null;
+        };
+    }, [text, onlyWhenTruncated, reposition, cancelHide, cancelShow, scheduleHide, hide]);
+    /** Najechanie wskaźnikiem pokazuje dymek po chwili; fokus - od razu. */
+    const scheduleShow = useCallback(() => {
+        cancelHide();
+        if (tipRef.current || showTimer.current !== undefined)
+            return;
+        showTimer.current = setTimeout(() => {
+            showTimer.current = undefined;
+            show();
+        }, SHOW_DELAY_MS);
+    }, [cancelHide, show]);
+    // Zmiana tekstu przy widocznym dymku - bez tego dymek pokazywałby starą treść do zamknięcia.
+    useEffect(() => {
+        const tip = tipRef.current;
+        if (!tip)
+            return;
+        if (!text)
+            hide();
+        else if (tip.textContent !== text) {
+            tip.textContent = text;
+            reposition();
+        }
+    }, [text, hide, reposition]);
+    /** Fokus przeszedł do innego elementu w obrębie hosta - dymek zostaje. */
     const onBlur = (event) => {
         const next = event.relatedTarget;
         if (next && hostRef.current?.contains(next))
@@ -190,15 +246,18 @@ export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false,
         return _jsx(_Fragment, { children: children });
     const child = children;
     const props = child.props;
+    /* eslint-disable react-hooks/refs -- composeRefs i chain tylko składają funkcje; refy czytają one
+       dopiero przy podpięciu elementu i w zdarzeniach, nigdy w renderze */
     return cloneElement(child, {
         ref: composeRefs(hostRef, props['ref']),
-        onMouseEnter: chain(props['onMouseEnter'], show),
+        onMouseEnter: chain(props['onMouseEnter'], scheduleShow),
         onMouseLeave: chain(props['onMouseLeave'], scheduleHide),
         onFocus: chain(props['onFocus'], show),
         onBlur: chain(props['onBlur'], onBlur),
     });
+    /* eslint-enable react-hooks/refs */
 }
-/** Handler dziecka najpierw, nasz po nim — jak w scalaniu propsów slotu. */
+/** Handler dziecka najpierw, nasz po nim - jak w scalaniu propsów slotu. */
 function chain(theirs, ours) {
     return (...args) => {
         if (typeof theirs === 'function')
@@ -208,7 +267,7 @@ function chain(theirs, ours) {
 }
 /**
  * Czy treść jest przycięta? Sprawdzamy hosta oraz jego bezpośrednie dzieci, bo
- * `text-overflow: ellipsis` siedzi zwykle na wewnętrznym elemencie — a taki element kurczy się
+ * `text-overflow: ellipsis` siedzi zwykle na wewnętrznym elemencie - a taki element kurczy się
  * do dostępnej szerokości i nie rozpycha rodzica, więc pomiar samego hosta nie wykryłby niczego.
  */
 function isTruncated(root) {

package/dist/tree/llms.txt

@@ -8,25 +8,26 @@ Import: `import { KptTree, type KptTreeNode } from '@konce-pt/react';`
       <ul class="kpt-tree" role="tree">
         <li class="kpt-tree__node" role="treeitem" aria-expanded="true">
           <div class="kpt-tree__row is-selected">
-            <span class="kpt-tree__toggle" aria-hidden="true">…chevron…</span>
-            <span class="kpt-tree__icon">…</span>
+            <span class="kpt-tree__toggle" aria-hidden="true">...chevron...</span>
+            <span class="kpt-tree__icon">...</span>
             <span class="kpt-tree__label">src</span>
           </div>
-          <ul role="group">…</ul>
+          <ul role="group">...</ul>
         </li>
       </ul>
     </div>
 
 ## Props
-- `nodes`: `KptTreeNode<T>[]` — `{ label, value?, icon?, children?, expanded?, disabled? }`
-- `selectable`: boolean — a row click selects instead of expanding
-- `selected` / `defaultSelected` / `onSelectedChange` — the node object, or `null`
+- `nodes`: `KptTreeNode<T>[]` - `{ label, value?, icon?, children?, expanded?, disabled? }`
+- `selectable`: boolean - a row click selects instead of expanding
+- `collapseMotion` - `'spring' | 'fade' | 'none'` (default from `KptMotionProvider`, else `spring`) - see below
+- `selected` / `defaultSelected` / `onSelectedChange` - the node object, or `null`
 - `onNodeClick(node)`
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Expansion is component state, not data
 `expanded` in a node is the initial state only. The component keeps what the user opened or closed
-itself and never writes to the node objects — so two trees fed the same nodes open and close
+itself and never writes to the node objects - so two trees fed the same nodes open and close
 independently, and replacing `nodes` with new objects brings their own initial state.
 
 ## Examples
@@ -36,16 +37,28 @@ independently, and replacing `nodes` with new objects brings their own initial s
 ## Keyboard
 The tree is one Tab stop (roving tabindex on the `treeitem` elements), following the WAI-ARIA tree view
 pattern:
-- `↓` / `↑` — the next / previous visible row, `Home` / `End` — the first / last;
-- `→` — expands a closed branch, on an open one moves to its first child;
-- `←` — collapses an open branch, otherwise moves to the parent;
-- `Enter` / `Space` — the same as a click: selects (with `selectable`) or toggles the branch.
+- `ArrowDown` / `ArrowUp` - the next / previous visible row, `Home` / `End` - the first / last;
+- `ArrowRight` - expands a closed branch, on an open one moves to its first child;
+- `ArrowLeft` - collapses an open branch, otherwise moves to the parent;
+- `Enter` / `Space` - the same as a click: selects (with `selectable`) or toggles the branch.
 The logic is the pure function `treeKeyAction` in `tree-keys.ts`; the other port has a twin file.
 
 ## i18n
 No labels of its own any more: the chevron is mouse-only and the keyboard expands with the arrows.
 `locale` and `dictionary` are still accepted, so existing call sites keep compiling.
 
+## Branch motion
+`collapseMotion` animates expanding and collapsing a branch:
+- `spring` - the height opens on a soft spring, children slide in as a cascade and sharpen out of a
+  blur; when collapsing, the children fade first;
+- `fade` - children cross-fade;
+- `none` - no motion.
+
+A collapsing branch stays in the DOM (`inert`) until its animation ends, so it does not cut off
+mid-way; keyboard navigation already skips it. Entry rules apply only after the first render, so
+branches expanded in the data do not animate on page load. With no value it takes `collapse` from
+`KptMotionProvider` (default `spring`); `enabled: false` and the system "reduce motion" setting always win.
+
 ## Tokens
 The selected row `--kpt-color-primary`, the hover `--kpt-color-surface-variant`.
 
@@ -55,3 +68,4 @@ selectable trees `aria-selected`, disabled rows `aria-disabled`. The chevron is
 (`aria-hidden`): a button inside a `treeitem` would be a nested control and a second Tab stop per
 row, and the keyboard expands with the arrows anyway. The focus ring is drawn on the row, not on the
 `<li>`, which would outline the whole subtree.
+`ariaLabel` names the `role="tree"` element (e.g. "Project files") - a separate prop because `aria-label` from the rest props lands on the wrapper, not on the tree.

package/dist/tree/tree-keys.d.ts

@@ -18,10 +18,10 @@ export type KptTreeKeyAction = {
     index: number;
 };
 /**
- * ↓ / ↑ — następny / poprzedni widoczny wiersz (bez zawijania), `Home` / `End` — pierwszy / ostatni.
- * → — zamkniętą gałąź rozwija, w otwartej przechodzi do pierwszego dziecka.
- * ← — otwartą gałąź zwija, w pozostałych przypadkach przechodzi do rodzica.
- * `Enter` / spacja — aktywuje wiersz (zaznaczenie albo przełączenie, jak kliknięcie).
- * Zwraca `null` dla klawisza, który nic nie robi — wtedy nie blokujemy jego domyślnej akcji.
+ * ArrowDown / ArrowUp - następny / poprzedni widoczny wiersz (bez zawijania), `Home` / `End` - pierwszy / ostatni.
+ * -> - zamkniętą gałąź rozwija, w otwartej przechodzi do pierwszego dziecka.
+ * <- - otwartą gałąź zwija, w pozostałych przypadkach przechodzi do rodzica.
+ * `Enter` / spacja - aktywuje wiersz (zaznaczenie albo przełączenie, jak kliknięcie).
+ * Zwraca `null` dla klawisza, który nic nie robi - wtedy nie blokujemy jego domyślnej akcji.
  */
 export declare function treeKeyAction(rows: readonly KptTreeRow[], current: number, key: string): KptTreeKeyAction | null;

package/dist/tree/tree-keys.js

@@ -1,13 +1,13 @@
 /*
- * Klawiatura drzewa (wzorzec WAI-ARIA „tree view”) — czysta funkcja na spłaszczonej liście
- * widocznych wierszy. Port Angulara ma bliźniaczy plik `lib/tree/tree-keys.ts` — zmiana zachowania w obu.
+ * Klawiatura drzewa (wzorzec WAI-ARIA "tree view") - czysta funkcja na spłaszczonej liście
+ * widocznych wierszy. Port Angulara ma bliźniaczy plik `lib/tree/tree-keys.ts` - zmiana zachowania w obu.
  */
 /**
- * ↓ / ↑ — następny / poprzedni widoczny wiersz (bez zawijania), `Home` / `End` — pierwszy / ostatni.
- * → — zamkniętą gałąź rozwija, w otwartej przechodzi do pierwszego dziecka.
- * ← — otwartą gałąź zwija, w pozostałych przypadkach przechodzi do rodzica.
- * `Enter` / spacja — aktywuje wiersz (zaznaczenie albo przełączenie, jak kliknięcie).
- * Zwraca `null` dla klawisza, który nic nie robi — wtedy nie blokujemy jego domyślnej akcji.
+ * ArrowDown / ArrowUp - następny / poprzedni widoczny wiersz (bez zawijania), `Home` / `End` - pierwszy / ostatni.
+ * -> - zamkniętą gałąź rozwija, w otwartej przechodzi do pierwszego dziecka.
+ * <- - otwartą gałąź zwija, w pozostałych przypadkach przechodzi do rodzica.
+ * `Enter` / spacja - aktywuje wiersz (zaznaczenie albo przełączenie, jak kliknięcie).
+ * Zwraca `null` dla klawisza, który nic nie robi - wtedy nie blokujemy jego domyślnej akcji.
  */
 export function treeKeyAction(rows, current, key) {
     const row = rows[current];

package/dist/tree/tree.d.ts

@@ -1,5 +1,6 @@
 import { type ComponentPropsWithRef } from 'react';
 import type { KptI18nOverrides } from '../i18n/i18n-context.tsx';
+import { type KptCollapseMotion } from '@konce-pt/motion';
 export interface KptTreeNode<T = unknown> {
     label: string;
     value?: T;
@@ -17,22 +18,33 @@ export interface KptTreeProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onS
     defaultSelected?: KptTreeNode<T> | null;
     onSelectedChange?: (node: KptTreeNode<T> | null) => void;
     onNodeClick?: (node: KptTreeNode<T>) => void;
+    /**
+     * Nazwa drzewa dla czytnika (`role="tree"` bez nazwy to samo "drzewo"), np. "Pliki projektu".
+     * Trafia na element `role="tree"`, nie na opakowanie - dlatego osobny prop, a nie `aria-label`.
+     */
+    ariaLabel?: string;
+    /**
+     * Ruch rozwijania gałęzi: `spring` - wysokość na sprężynie, dzieci wjeżdżają kaskadą i wyostrzają
+     * się z rozmycia; `fade` - dzieci się przenikają; `none` - bez ruchu. Bez wartości bierze `collapse`
+     * z `KptMotionProvider` (domyślnie `spring`); `enabled={false}` i systemowe "ogranicz ruch" wyłączają go zawsze.
+     */
+    collapseMotion?: KptCollapseMotion;
 }
 /**
  * Drzewo hierarchiczne: rozwijanie, zaznaczanie, ikony.
  *
  * Stan rozwinięcia trzyma komponent, a nie pole `expanded` w danych: mutowanie cudzej tablicy
  * przy każdym kliknięciu byłoby w Reakcie efektem ubocznym renderu, a `expanded` z danych zostaje
- * tym, czym powinno być — stanem początkowym.
+ * tym, czym powinno być - stanem początkowym.
  *
- * Klawiatura według wzorca WAI-ARIA „tree view”: jeden przystanek Tab na całe drzewo (roving
- * tabindex), strzałki po widocznych wierszach, → / ← rozwijają i zwijają, `Enter` / spacja
+ * Klawiatura według wzorca WAI-ARIA "tree view": jeden przystanek Tab na całe drzewo (roving
+ * tabindex), strzałki po widocznych wierszach, -> / <- rozwijają i zwijają, `Enter` / spacja
  * działają jak kliknięcie. Logika klawiszy siedzi w czystej funkcji `treeKeyAction`.
  *
- * `locale` i `dictionary` są przyjmowane dla zgodności — drzewo nie ma już własnych etykiet:
+ * `locale` i `dictionary` są przyjmowane dla zgodności - drzewo nie ma już własnych etykiet:
  * przełącznik gałęzi jest tylko dla myszy, a z klawiatury rozwija się strzałkami.
  *
  * @example
  * <KptTree nodes={tree} selectable selected={node} onSelectedChange={setNode} />
  */
-export declare function KptTree<T>({ nodes, selectable, selected, defaultSelected, onSelectedChange, onNodeClick, locale: _locale, dictionary: _dictionary, className, ...rest }: Readonly<KptTreeProps<T>>): import("react").JSX.Element;
+export declare function KptTree<T>({ nodes, selectable, selected, defaultSelected, onSelectedChange, onNodeClick, ariaLabel, collapseMotion, locale: _locale, dictionary: _dictionary, className, ...rest }: Readonly<KptTreeProps<T>>): import("react").JSX.Element;

package/dist/tree/tree.js

@@ -1,43 +1,59 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState, } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { KptIcon } from "../icon/icon.js";
 import { treeKeyAction } from "./tree-keys.js";
+import { layoutMotionAllowed, resolveCollapseMotion } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
+/** Ile gałąź w trakcie zwijania zostaje w DOM - z zapasem nad `--kpt-motion-duration-slow`. */
+const CLOSE_MS = 420;
+/** Wiersze drzewa z pominięciem tych w zwijanej gałęzi - ich kolejność to kolejność `rows`. */
+const VISIBLE_ITEMS = '[role="treeitem"]:not(.kpt-tree__collapse:not(.is-open) *)';
 /**
  * Drzewo hierarchiczne: rozwijanie, zaznaczanie, ikony.
  *
  * Stan rozwinięcia trzyma komponent, a nie pole `expanded` w danych: mutowanie cudzej tablicy
  * przy każdym kliknięciu byłoby w Reakcie efektem ubocznym renderu, a `expanded` z danych zostaje
- * tym, czym powinno być — stanem początkowym.
+ * tym, czym powinno być - stanem początkowym.
  *
- * Klawiatura według wzorca WAI-ARIA „tree view”: jeden przystanek Tab na całe drzewo (roving
- * tabindex), strzałki po widocznych wierszach, → / ← rozwijają i zwijają, `Enter` / spacja
+ * Klawiatura według wzorca WAI-ARIA "tree view": jeden przystanek Tab na całe drzewo (roving
+ * tabindex), strzałki po widocznych wierszach, -> / <- rozwijają i zwijają, `Enter` / spacja
  * działają jak kliknięcie. Logika klawiszy siedzi w czystej funkcji `treeKeyAction`.
  *
- * `locale` i `dictionary` są przyjmowane dla zgodności — drzewo nie ma już własnych etykiet:
+ * `locale` i `dictionary` są przyjmowane dla zgodności - drzewo nie ma już własnych etykiet:
  * przełącznik gałęzi jest tylko dla myszy, a z klawiatury rozwija się strzałkami.
  *
  * @example
  * <KptTree nodes={tree} selectable selected={node} onSelectedChange={setNode} />
  */
-export function KptTree({ nodes = [], selectable = false, selected, defaultSelected = null, onSelectedChange, onNodeClick, locale: _locale, dictionary: _dictionary, className, ...rest }) {
+export function KptTree({ nodes = [], selectable = false, selected, defaultSelected = null, onSelectedChange, onNodeClick, ariaLabel, collapseMotion, locale: _locale, dictionary: _dictionary, className, ...rest }) {
     const [active, setActive] = useControllableState({
         value: selected,
         defaultValue: defaultSelected,
         onChange: onSelectedChange,
     });
-    // Gałęzie przełączone przez użytkownika (węzeł → otwarta?). Węzeł spoza mapy ma stan z `expanded`
-    // w danych — dzięki temu nowa tablica `nodes` przychodzi z własnym stanem początkowym.
+    // Gałęzie przełączone przez użytkownika (węzeł -> otwarta?). Węzeł spoza mapy ma stan z `expanded`
+    // w danych - dzięki temu nowa tablica `nodes` przychodzi z własnym stanem początkowym.
     const [toggled, setToggled] = useState(() => new Map());
-    /** Wiersz, który ostatnio miał fokus — on jest przystankiem Tab. */
+    /** Wiersz, który ostatnio miał fokus - on jest przystankiem Tab. */
     const [focused, setFocused] = useState(null);
     /** Węzeł, na który po renderze trzeba przenieść fokus DOM (klawiatura). */
     const [focusRequest, setFocusRequest] = useState(null);
+    const handledFocus = useRef(null);
     const treeRef = useRef(null);
+    const motion = resolveCollapseMotion(collapseMotion, useKptMotion());
+    /** Gałęzie w trakcie zwijania - zostają w DOM, dopóki gra animacja. */
+    const [closing, setClosing] = useState(() => new Set());
+    // Reguły wejścia (`@starting-style`) dopiero po pierwszym renderze - start strony się nie rusza.
+    // Klasa idzie wprost na element: osobny stan dałby drugi przebieg renderu tylko po to.
+    useEffect(() => {
+        treeRef.current?.classList.add('is-live');
+    }, []);
     const hasChildren = (node) => !!node.children?.length;
     const isOpen = (node) => toggled.get(node) ?? !!node.expanded;
-    // Widoczne wiersze w kolejności DOM — tyle widzi klawiatura.
+    // Widoczne wiersze w kolejności DOM - tyle widzi klawiatura.
     const rows = useMemo(() => {
         const out = [];
         const walk = (list, level, parent) => {
@@ -53,20 +69,46 @@ export function KptTree({ nodes = [], selectable = false, selected, defaultSelec
         walk(nodes, 0, -1);
         return out;
     }, [nodes, toggled]);
-    // Jedyny wiersz z `tabIndex=0`: ostatnio skupiony, a gdy go nie widać — zaznaczony albo pierwszy.
+    // Jedyny wiersz z `tabIndex=0`: ostatnio skupiony, a gdy go nie widać - zaznaczony albo pierwszy.
     const visible = rows.map((r) => r.node);
     const tabStop = focused && visible.includes(focused) ? focused : active && visible.includes(active) ? active : (visible[0] ?? null);
+    // Żądanie nie jest zerowane w efekcie (setState w efekcie = dodatkowy przebieg renderu): każde jest
+    // nowym obiektem, a obsłużone zapamiętuje ref - kolejne przebiegi efektu go pomijają.
     useEffect(() => {
-        if (!focusRequest)
+        if (!focusRequest || handledFocus.current === focusRequest)
             return;
-        const index = rows.findIndex((r) => r.node === focusRequest);
-        treeRef.current?.querySelectorAll('[role="treeitem"]')[index]?.focus();
-        setFocusRequest(null);
+        const index = rows.findIndex((r) => r.node === focusRequest.node);
+        const element = treeRef.current?.querySelectorAll(VISIBLE_ITEMS)[index];
+        if (!element)
+            return; // wiersz jeszcze nie wyrenderowany (rozwijanie) - spróbujemy po zmianie `rows`
+        handledFocus.current = focusRequest;
+        element.focus();
     }, [focusRequest, rows]);
     const toggle = (node) => {
+        const willOpen = !isOpen(node);
         const next = new Map(toggled);
-        next.set(node, !isOpen(node));
+        next.set(node, willOpen);
         setToggled(next);
+        // Zwijana gałąź zostaje w DOM na czas animacji; ponowne otwarcie w trakcie ją po prostu zatrzymuje.
+        const animate = motion !== 'none' && layoutMotionAllowed();
+        setClosing((current) => {
+            const set = new Set(current);
+            set.delete(node);
+            if (!willOpen && animate)
+                set.add(node);
+            return set;
+        });
+        if (!willOpen && animate) {
+            setTimeout(() => {
+                setClosing((current) => {
+                    if (!current.has(node))
+                        return current;
+                    const set = new Set(current);
+                    set.delete(node);
+                    return set;
+                });
+            }, CLOSE_MS);
+        }
     };
     const onRow = (node) => {
         setFocused(node);
@@ -79,7 +121,7 @@ export function KptTree({ nodes = [], selectable = false, selected, defaultSelec
         onNodeClick?.(node);
     };
     const onKeyDown = (node, event) => {
-        // Zagnieżdżone `<li>` przepuszczają zdarzenie w górę — obsługuje je tylko wiersz z fokusem.
+        // Zagnieżdżone `<li>` przepuszczają zdarzenie w górę - obsługuje je tylko wiersz z fokusem.
         if (event.target !== event.currentTarget)
             return;
         const current = rows.findIndex((r) => r.node === node);
@@ -94,15 +136,15 @@ export function KptTree({ nodes = [], selectable = false, selected, defaultSelec
             onRow(target);
         else {
             setFocused(target);
-            setFocusRequest(target);
+            setFocusRequest({ node: target });
         }
     };
-    const renderList = (list, level) => list.map((node, index) => (_jsxs("li", { className: "kpt-tree__node", role: "treeitem", "aria-level": level + 1, "aria-expanded": hasChildren(node) ? isOpen(node) : undefined, "aria-selected": selectable ? active === node : undefined, "aria-disabled": node.disabled ? true : undefined, tabIndex: node === tabStop ? 0 : -1, onFocus: (event) => {
+    const renderList = (list, level) => list.map((node, index) => (_jsxs("li", { className: "kpt-tree__node", style: { '--_i': index }, role: "treeitem", "aria-level": level + 1, "aria-expanded": hasChildren(node) ? isOpen(node) : undefined, "aria-selected": selectable ? active === node : undefined, "aria-disabled": node.disabled ? true : undefined, tabIndex: node === tabStop ? 0 : -1, onFocus: (event) => {
             if (event.target === event.currentTarget)
                 setFocused(node);
         }, onKeyDown: (event) => onKeyDown(node, event), children: [_jsxs("div", { className: cn('kpt-tree__row', active === node && 'is-selected', node.disabled && 'is-disabled'), style: { paddingInlineStart: `${0.5 + level * 1.1}rem` }, onClick: () => onRow(node), children: [hasChildren(node) ? (_jsx("span", { className: "kpt-tree__toggle", "aria-hidden": "true", onClick: (event) => {
                             event.stopPropagation();
                             toggle(node);
-                        }, children: _jsx(KptIcon, { name: "chevron-right", className: cn('kpt-tree__chevron', isOpen(node) && 'is-open') }) })) : (_jsx("span", { className: "kpt-tree__spacer" })), node.icon ? _jsx(KptIcon, { name: node.icon, className: "kpt-tree__icon" }) : null, _jsx("span", { className: "kpt-tree__label", children: node.label })] }), hasChildren(node) && isOpen(node) ? _jsx("ul", { role: "group", children: renderList(node.children, level + 1) }) : null] }, index)));
-    return (_jsx("div", { className: cn('kpt-tree-host', className), ...rest, children: _jsx("ul", { ref: treeRef, className: "kpt-tree", role: "tree", children: renderList(nodes, 0) }) }));
+                        }, children: _jsx(KptIcon, { name: "chevron-right", className: cn('kpt-tree__chevron', isOpen(node) && 'is-open') }) })) : (_jsx("span", { className: "kpt-tree__spacer" })), node.icon ? _jsx(KptIcon, { name: node.icon, className: "kpt-tree__icon" }) : null, _jsx("span", { className: "kpt-tree__label", children: node.label })] }), hasChildren(node) && (isOpen(node) || closing.has(node)) ? (_jsx("div", { className: cn('kpt-tree__collapse', isOpen(node) && 'is-open'), inert: !isOpen(node), children: _jsx("ul", { role: "group", className: "kpt-tree__group", children: renderList(node.children, level + 1) }) })) : null] }, index)));
+    return (_jsx("div", { className: cn('kpt-tree-host', className), ...rest, children: _jsx("ul", { ref: treeRef, className: "kpt-tree", role: "tree", "aria-label": ariaLabel || undefined, "data-motion": motion, children: renderList(nodes, 0) }) }));
 }

package/dist/update/llms.txt

@@ -0,0 +1,54 @@
+# KptUpdate (@konce-pt/react)
+
+An app update row: the icon in `KptLoader variant="ring"`, the name, a status line
+("12.3 MB of 24 MB") and a button whose label follows the state; texts cross-fade on a state change.
+Same classes as `kpt-update` in Angular. Import: `import { KptUpdate } from '@konce-pt/react';`
+
+The component downloads nothing - the app owns the state, the byte counts and what an action does.
+
+## DOM
+    <div class="kpt-update-host">
+      <div class="kpt-update" data-status="downloading">
+        <span class="kpt-loader-host kpt-update__ring">...<span class="kpt-update__icon">...</span>...</span>
+        <div class="kpt-update__meta">
+          <span class="kpt-update__name">Kompas</span>
+          <span class="kpt-update__line kpt-update__swap" aria-hidden="true"><span>0.4 MB of 24 MB</span></span>
+          <span class="kpt-button-host kpt-update__action"><button class="kpt-button">...</button></span>
+        </div>
+        <span class="kpt-update__live" role="status">Kompas: Downloading...</span>
+      </div>
+    </div>
+
+## States (`status`)
+`pending` (default, ring loops, button "Update") -> `downloading` (with `total` the ring draws
+progress and the line shows both sizes in the unit of the total; button "Cancel") -> `success`
+(the ring releases the icon; "Open") or `error` (a badge on the icon; "Retry").
+
+## Props
+- `name`: string (required)
+- `status`: KptUpdateStatus (default 'pending')
+- `loaded`, `total`: number | null (bytes) - formatted with `Intl` in the interface language
+- `size`: string (default '5.5rem'), `color`: KptLoaderColor (default 'info')
+- `showAction`: boolean (default true)
+- `pendingText`, `downloadingText`, `successText`, `errorText`, `updateLabel`, `cancelLabel`,
+  `openLabel`, `retryLabel` - override the `update.*` texts
+- `onAction`: (action: KptUpdateAction) => void - 'update' | 'cancel' | 'open' | 'retry' by state
+- `children` - the icon (`<img>`, SVG, `KptIcon`); omitted = `download`
+- `locale`, `dictionary` - i18n overrides for this component only
+- `className`, `style`, `ref` and other `<div>` props go to `.kpt-update`; `hostProps` to the wrapper
+
+## Example
+    <KptUpdate name="Kompas" status={status} loaded={loaded} total={total} onAction={handle}>
+      <img src="/kompas.svg" alt="" />
+    </KptUpdate>
+
+## Tokens
+The tile: a gradient from the `color` role to `--kpt-color-success`, the icon in
+`--kpt-color-<role>-contrast`, `--kpt-shadow-sm`. Text: `--kpt-font-weight-semibold`,
+`--kpt-font-size-sm`, `--kpt-color-text-muted`.
+
+## Accessibility
+A visually hidden `role="status"` region holds "name: state" and announces state changes, not
+bytes (the line is `aria-hidden`). While downloading with a known total the ring is a
+`role="progressbar"`. During the cross-fade the leaving label is `aria-hidden`; with motion off
+texts change at once.