@konce-pt/react 0.9.1 → 0.11.0

package/dist/toast/llms.txt

@@ -5,23 +5,26 @@ Import: `import { kptToast, KptToastContainer } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-toast-container-host">
-      <div class="kpt-toast-container" aria-live="polite" aria-atomic="false">
-        <div class="kpt-toast" data-variant="success" role="status">
+      <div class="kpt-toast-container" role="region" aria-label="Notifications">
+        <div class="kpt-toast" data-variant="success">
           <span class="kpt-icon-host kpt-toast__icon">…</span>
           <div class="kpt-toast__content">
             <div class="kpt-toast__title">Saved</div>
             <div class="kpt-toast__message">Your changes are stored.</div>
           </div>
+          <button class="kpt-toast__action" type="button">Undo</button>
           <button class="kpt-toast__close" type="button" aria-label="Close">…</button>
         </div>
       </div>
+      <span class="kpt-toast-container__live" aria-live="polite" aria-atomic="true">Saved. Your changes are stored.</span>
+      <span class="kpt-toast-container__live" aria-live="assertive" aria-atomic="true"></span>
     </div>
 
 ## kptToast
 - `show(message, options?)` — returns the toast id
 - `info` / `success` / `warning` / `error` — the same, with the variant preset
-- `dismiss(id)`, `clear()`
-- options: `title`, `variant`, `duration` (ms, default 4000; `0` disables auto-dismiss)
+- `dismiss(id)`, `clear()`, `pause()`, `resume()`
+- options: `title`, `variant`, `duration` (ms, default 4000; `0` disables auto-dismiss), `action: { label, run }`
 
 ## A module singleton, not a provider
 The store lives in the module, which is the closest equivalent of Angular's
@@ -42,11 +45,22 @@ mounts are kept in the store and appear as soon as it does.
     const id = kptToast.info('Uploading…', { duration: 0 });
     kptToast.dismiss(id);
 
+## Actions and pausing
+`action: { label, run }` adds one button to the toast (typically “Undo”); a click calls `run` and
+dismisses the toast. Give such toasts a longer `duration`, and keep the action available elsewhere.
+`pause()` / `resume()` stop and continue every timer; the container calls them on hover and focus,
+and resumes by itself when the stack empties.
+
 ## Tokens
 The semantic colour pairs of each variant (`--kpt-color-info` / `-success` / `-warning` /
 `-danger` with their `-subtle` and `on-` counterparts), `--kpt-elevation-3`, `--kpt-z-overlay`.
 
 ## Accessibility
-The container is `aria-live="polite"` with `aria-atomic="false"`, and each toast is
-`role="status"`, so a screen reader announces new ones without interrupting the current task.
-The close button gets its label from `common.close`.
+Announcements go through two permanent, visually hidden live regions next to the stack —
+`aria-live="polite"` for ordinary toasts and `aria-live="assertive"` for `danger` — and not through
+the toasts themselves: a live region has to exist before content appears in it, and nested regions
+are read twice by some screen readers. Each region is cleared before it is written, so the same
+text twice is announced twice, and a dismissed toast never re-announces an older one. While there
+are toasts the stack is `role="region"` named `toast.region` (“Notifications”). Pointer or focus on
+the stack pauses every timer (WCAG 2.2.1); the timers resume with the time that was left. The close
+button is labelled from `common.close`.

package/dist/toast/toast-container.d.ts

@@ -1,10 +1,15 @@
-import type { ComponentPropsWithRef } from 'react';
+import { type ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptToastContainerProps extends ComponentPropsWithRef<'div'>, KptI18nOverrides {
 }
 /**
  * Kontener renderujący toasty z `kptToast`. Umieść raz w aplikacji, np. w komponencie głównym.
  *
+ * Ogłaszanie idzie przez dwa stałe, niewidoczne regiony na żywo — uprzejmy dla zwykłych toastów
+ * i natychmiastowy dla błędów — a nie przez same toasty: region musi istnieć, zanim pojawi się
+ * w nim treść, a zagnieżdżone regiony część czytników ogłasza dwa razy. Gdy wskaźnik albo fokus
+ * jest na toastach, liczniki stoją, więc komunikat nie znika w trakcie czytania.
+ *
  * @example
  * <KptToastContainer />
  * // gdziekolwiek: kptToast.success('Zapisano');

package/dist/toast/toast-container.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
@@ -12,6 +13,11 @@ const ICONS = {
 /**
  * Kontener renderujący toasty z `kptToast`. Umieść raz w aplikacji, np. w komponencie głównym.
  *
+ * Ogłaszanie idzie przez dwa stałe, niewidoczne regiony na żywo — uprzejmy dla zwykłych toastów
+ * i natychmiastowy dla błędów — a nie przez same toasty: region musi istnieć, zanim pojawi się
+ * w nim treść, a zagnieżdżone regiony część czytników ogłasza dwa razy. Gdy wskaźnik albo fokus
+ * jest na toastach, liczniki stoją, więc komunikat nie znika w trakcie czytania.
+ *
  * @example
  * <KptToastContainer />
  * // gdziekolwiek: kptToast.success('Zapisano');
@@ -19,5 +25,50 @@ const ICONS = {
 export function KptToastContainer({ locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const toasts = useKptToasts();
-    return (_jsx("div", { className: cn('kpt-toast-container-host', className), ...rest, children: _jsx("div", { className: "kpt-toast-container", "aria-live": "polite", "aria-atomic": "false", children: toasts.map((toast) => (_jsxs("div", { className: "kpt-toast", "data-variant": toast.variant, role: "status", children: [_jsx(KptIcon, { className: "kpt-toast__icon", name: ICONS[toast.variant] }), _jsxs("div", { className: "kpt-toast__content", children: [toast.title ? _jsx("div", { className: "kpt-toast__title", children: toast.title }) : null, _jsx("div", { className: "kpt-toast__message", children: toast.message })] }), _jsx("button", { className: "kpt-toast__close", type: "button", onClick: () => kptToast.dismiss(toast.id), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })] }, toast.id))) }) }));
+    const [politeText, setPoliteText] = useState('');
+    const [alertText, setAlertText] = useState('');
+    // Ostatni ogłoszony toast — zamknięcie nowszego nie może ponownie ogłosić starszego.
+    const lastAnnounced = useRef(0);
+    const holds = useRef(new Set());
+    const hold = (reason, on) => {
+        if (on)
+            holds.current.add(reason);
+        else
+            holds.current.delete(reason);
+        if (holds.current.size)
+            kptToast.pause();
+        else
+            kptToast.resume();
+    };
+    useEffect(() => {
+        // Pusty kontener nie dostanie już `mouseleave`, więc zdejmujemy wstrzymanie sami —
+        // inaczej kolejne toasty czekałyby w nieskończoność.
+        if (!toasts.length && holds.current.size) {
+            holds.current.clear();
+            kptToast.resume();
+        }
+        const fresh = toasts.filter((toast) => toast.id > lastAnnounced.current);
+        if (!fresh.length)
+            return;
+        lastAnnounced.current = fresh[fresh.length - 1].id;
+        const frames = [];
+        for (const toast of fresh) {
+            const text = toast.title ? `${toast.title}. ${toast.message}` : toast.message;
+            const set = toast.variant === 'danger' ? setAlertText : setPoliteText;
+            // Czyścimy region przed wpisaniem — ten sam tekst drugi raz inaczej nie zostałby ogłoszony.
+            set('');
+            frames.push(requestAnimationFrame(() => set(text)));
+        }
+        return () => frames.forEach(cancelAnimationFrame);
+    }, [toasts]);
+    // Fokus przechodzący między przyciskami toastów nie wznawia liczników.
+    const onBlur = (event) => {
+        if (event.relatedTarget && event.currentTarget.contains(event.relatedTarget))
+            return;
+        hold('focus', false);
+    };
+    return (_jsxs("div", { className: cn('kpt-toast-container-host', className), ...rest, children: [_jsx("div", { className: "kpt-toast-container", role: toasts.length ? 'region' : undefined, "aria-label": toasts.length ? t('toast.region') : undefined, onMouseEnter: () => hold('pointer', true), onMouseLeave: () => hold('pointer', false), onFocus: () => hold('focus', true), onBlur: onBlur, children: toasts.map((toast) => (_jsxs("div", { className: "kpt-toast", "data-variant": toast.variant, children: [_jsx(KptIcon, { className: "kpt-toast__icon", name: ICONS[toast.variant] }), _jsxs("div", { className: "kpt-toast__content", children: [toast.title ? _jsx("div", { className: "kpt-toast__title", children: toast.title }) : null, _jsx("div", { className: "kpt-toast__message", children: toast.message })] }), toast.action ? (_jsx("button", { className: "kpt-toast__action", type: "button", onClick: () => {
+                                toast.action?.run();
+                                kptToast.dismiss(toast.id);
+                            }, children: toast.action.label })) : null, _jsx("button", { className: "kpt-toast__close", type: "button", onClick: () => kptToast.dismiss(toast.id), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })] }, toast.id))) }), _jsx("span", { className: "kpt-toast-container__live", "aria-live": "polite", "aria-atomic": "true", children: politeText }), _jsx("span", { className: "kpt-toast-container__live", "aria-live": "assertive", "aria-atomic": "true", children: alertText })] }));
 }

package/dist/toast/toast-store.d.ts

@@ -1,4 +1,9 @@
 import type { KptAlertVariant } from '../shared/types.ts';
+/** Przycisk akcji w toaście, np. „Cofnij”. Kliknięcie uruchamia `run` i zamyka toast. */
+export interface KptToastAction {
+    label: string;
+    run: () => void;
+}
 export interface KptToast {
     id: number;
     message: string;
@@ -6,11 +11,16 @@ export interface KptToast {
     variant: KptAlertVariant;
     /** Czas życia w ms; 0 = bez auto-zamykania. */
     duration: number;
+    action?: KptToastAction;
 }
 export type KptToastOptions = Partial<Omit<KptToast, 'id' | 'message'>>;
 declare function show(message: string, options?: KptToastOptions): number;
 declare function dismiss(id: number): void;
 declare function clear(): void;
+/** Wstrzymuje wszystkie liczniki; toasty dodane w tym czasie też czekają. */
+declare function pause(): void;
+/** Wznawia liczniki od pozostałego czasu. */
+declare function resume(): void;
 /** Powiadomienia (toasty). Renderuje je `<KptToastContainer />`, umieszczony raz w aplikacji. */
 export declare const kptToast: {
     show: typeof show;
@@ -20,6 +30,8 @@ export declare const kptToast: {
     error: (message: string, options?: KptToastOptions) => number;
     dismiss: typeof dismiss;
     clear: typeof clear;
+    pause: typeof pause;
+    resume: typeof resume;
 };
 /** Bieżąca lista toastów. Używane przez kontener; przydaje się też do własnego renderowania. */
 export declare function useKptToasts(): KptToast[];

package/dist/toast/toast-store.js

@@ -1,11 +1,8 @@
 import { useSyncExternalStore } from 'react';
-/*
- * Magazyn toastów jako moduł-singleton — odpowiednik serwisu `providedIn: 'root'` z Angulara.
- * Dzięki temu `kptToast.success(...)` woła się z dowolnego miejsca, także spoza drzewa Reacta
- * (obsługa błędu w warstwie danych, interceptor), bez owijania aplikacji providerem.
- */
 let toasts = [];
 let seq = 0;
+let paused = false;
+const timers = new Map();
 const listeners = new Set();
 function emit() {
     for (const listener of listeners)
@@ -16,18 +13,58 @@ function show(message, options = {}) {
     const toast = { id, message, variant: 'info', duration: 4000, ...options };
     toasts = [...toasts, toast];
     emit();
-    if (toast.duration > 0)
-        setTimeout(() => dismiss(id), toast.duration);
+    if (toast.duration > 0) {
+        timers.set(id, { handle: null, remaining: toast.duration, startedAt: 0 });
+        if (!paused)
+            start(id);
+    }
     return id;
 }
+function start(id) {
+    const timer = timers.get(id);
+    if (!timer || timer.handle)
+        return;
+    timer.startedAt = Date.now();
+    timer.handle = setTimeout(() => dismiss(id), timer.remaining);
+}
 function dismiss(id) {
+    const timer = timers.get(id);
+    if (timer?.handle)
+        clearTimeout(timer.handle);
+    timers.delete(id);
     toasts = toasts.filter((toast) => toast.id !== id);
     emit();
 }
 function clear() {
+    for (const timer of timers.values())
+        if (timer.handle)
+            clearTimeout(timer.handle);
+    timers.clear();
     toasts = [];
     emit();
 }
+/** Wstrzymuje wszystkie liczniki; toasty dodane w tym czasie też czekają. */
+function pause() {
+    if (paused)
+        return;
+    paused = true;
+    const now = Date.now();
+    for (const timer of timers.values()) {
+        if (!timer.handle)
+            continue;
+        clearTimeout(timer.handle);
+        timer.handle = null;
+        timer.remaining = Math.max(0, timer.remaining - (now - timer.startedAt));
+    }
+}
+/** Wznawia liczniki od pozostałego czasu. */
+function resume() {
+    if (!paused)
+        return;
+    paused = false;
+    for (const id of timers.keys())
+        start(id);
+}
 /** Powiadomienia (toasty). Renderuje je `<KptToastContainer />`, umieszczony raz w aplikacji. */
 export const kptToast = {
     show,
@@ -37,6 +74,8 @@ export const kptToast = {
     error: (message, options) => show(message, { ...options, variant: 'danger' }),
     dismiss,
     clear,
+    pause,
+    resume,
 };
 const EMPTY = [];
 function subscribe(listener) {

package/dist/tooltip/llms.txt

@@ -37,6 +37,13 @@ attach a stylesheet rule to reliably.
 `--kpt-font-size-xs`, `--kpt-elevation-2`.
 
 ## Accessibility
-The bubble is `role="tooltip"` and appears on focus as well as hover, so it is reachable from the
-keyboard. It is `pointer-events: none`, so it never steals a click. It does NOT replace an
-accessible name — for an icon-only button give the button its own `aria-label`.
+- The bubble appears on hover and on keyboard focus. Focus is tracked with `focusin`/`focusout`,
+  so it also works when the focus lands on an inner element (`kpt-button`, `kpt-icon-button`).
+- The text reaches screen readers through a persistent, hidden description linked with
+  `aria-describedby` to the element that actually takes focus (the bubble itself only exists while
+  shown). It is skipped when it would repeat the element's name (an icon button whose label equals
+  the tooltip) and with `onlyWhenTruncated`, where the text is already in the DOM; the visible
+  bubble is then `aria-hidden`.
+- `Escape` closes the bubble, and the pointer can move onto it without it disappearing (a 120 ms
+  grace period) — WCAG 1.4.13.
+- It does NOT replace an accessible name — an icon-only button still needs its own label.

package/dist/tooltip/tooltip.d.ts

@@ -19,6 +19,11 @@ export interface KptTooltipProps {
  * 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
+ * jego nazwę albo przy `onlyWhenTruncated`. `Escape` zamyka dymek, a wskaźnik może na niego
+ * przejść bez zniknięcia (WCAG 1.4.13).
+ *
  * @example
  * <KptTooltip text="Zapisz zmiany" position="bottom"><KptButton>Zapisz</KptButton></KptTooltip>
  * <KptTooltip text={name} onlyWhenTruncated><span className="ellipsis">{name}</span></KptTooltip>

package/dist/tooltip/tooltip.js

@@ -1,6 +1,10 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { cloneElement, isValidElement, useCallback, useRef } from 'react';
+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`. */
+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;
 /**
  * Dymek podpowiedzi pokazywany na hover i focus. Lekki — element dodawany do `body`
  * i pozycjonowany względem dziecka.
@@ -8,6 +12,11 @@ import { composeRefs } from "../internal/compose-refs.js";
  * 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
+ * jego nazwę albo przy `onlyWhenTruncated`. `Escape` zamyka dymek, a wskaźnik może na niego
+ * przejść bez zniknięcia (WCAG 1.4.13).
+ *
  * @example
  * <KptTooltip text="Zapisz zmiany" position="bottom"><KptButton>Zapisz</KptButton></KptTooltip>
  * <KptTooltip text={name} onlyWhenTruncated><span className="ellipsis">{name}</span></KptTooltip>
@@ -15,6 +24,37 @@ import { composeRefs } from "../internal/compose-refs.js";
 export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false, children }) {
     const hostRef = useRef(null);
     const tipRef = useRef(null);
+    const descRef = useRef(null);
+    const hideTimer = 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.
+    useEffect(() => {
+        const host = hostRef.current;
+        if (!host || !text || onlyWhenTruncated)
+            return;
+        const target = host.matches(FOCUSABLE) ? host : (host.querySelector(FOCUSABLE) ?? host);
+        const name = (target.getAttribute('aria-label') ?? target.textContent ?? '').trim();
+        if (name === text.trim())
+            return;
+        const desc = document.createElement('span');
+        desc.id = descId;
+        desc.hidden = true;
+        desc.textContent = text;
+        document.body.appendChild(desc);
+        descRef.current = desc;
+        const ids = (target.getAttribute('aria-describedby') ?? '').split(/\s+/).filter(Boolean);
+        target.setAttribute('aria-describedby', [...ids, descId].join(' '));
+        return () => {
+            const rest = (target.getAttribute('aria-describedby') ?? '').split(/\s+/).filter((id) => id && id !== descId);
+            if (rest.length)
+                target.setAttribute('aria-describedby', rest.join(' '));
+            else
+                target.removeAttribute('aria-describedby');
+            desc.remove();
+            descRef.current = null;
+        };
+    }, [text, onlyWhenTruncated, descId]);
     const reposition = useCallback(() => {
         const tip = tipRef.current;
         const host = hostRef.current;
@@ -45,13 +85,33 @@ export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false,
         tip.style.top = `${Math.max(4, top)}px`;
         tip.style.left = `${Math.max(4, left)}px`;
     }, [position]);
+    const onKeyDown = useCallback((event) => {
+        if (event.key === 'Escape')
+            hideRef.current();
+    }, []);
+    const cancelHide = useCallback(() => {
+        if (hideTimer.current !== undefined)
+            clearTimeout(hideTimer.current);
+        hideTimer.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]);
+    }, [reposition, onKeyDown, cancelHide]);
+    // `onKeyDown` potrzebuje aktualnego `hide`, a `hide` zdejmuje `onKeyDown` — ref przerywa krąg.
+    const hideRef = useRef(hide);
+    hideRef.current = hide;
+    const scheduleHide = useCallback(() => {
+        cancelHide();
+        hideTimer.current = setTimeout(() => hideRef.current(), HIDE_DELAY_MS);
+    }, [cancelHide]);
+    useEffect(() => () => hideRef.current(), []);
     const show = useCallback(() => {
+        cancelHide();
         if (tipRef.current || !text)
             return;
         // Sprawdzamy dopiero teraz, a nie przy renderze: dzięki temu wynik jest zawsze aktualny
@@ -61,12 +121,17 @@ export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false,
         const tip = document.createElement('div');
         tip.className = 'kpt-tooltip';
         tip.setAttribute('role', 'tooltip');
+        // 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);pointer-events:none;opacity:0;transition:opacity 120ms;';
+                'box-shadow:var(--kpt-elevation-2);opacity:0;transition:opacity 120ms;';
+        tip.addEventListener('mouseenter', cancelHide);
+        tip.addEventListener('mouseleave', scheduleHide);
         document.body.appendChild(tip);
         tipRef.current = tip;
         reposition();
@@ -74,11 +139,19 @@ export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false,
         // `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';
         });
-    }, [text, onlyWhenTruncated, reposition]);
+    }, [text, onlyWhenTruncated, reposition, onKeyDown, cancelHide, scheduleHide]);
+    /** Fokus przeszedł do innego elementu w obrębie hosta — dymek zostaje. */
+    const onBlur = (event) => {
+        const next = event.relatedTarget;
+        if (next && hostRef.current?.contains(next))
+            return;
+        hide();
+    };
     if (!isValidElement(children))
         return _jsx(_Fragment, { children: children });
     const child = children;
@@ -86,9 +159,9 @@ export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false,
     return cloneElement(child, {
         ref: composeRefs(hostRef, props['ref']),
         onMouseEnter: chain(props['onMouseEnter'], show),
-        onMouseLeave: chain(props['onMouseLeave'], hide),
+        onMouseLeave: chain(props['onMouseLeave'], scheduleHide),
         onFocus: chain(props['onFocus'], show),
-        onBlur: chain(props['onBlur'], hide),
+        onBlur: chain(props['onBlur'], onBlur),
     });
 }
 /** Handler dziecka najpierw, nasz po nim — jak w scalaniu propsów slotu. */
@@ -96,7 +169,7 @@ function chain(theirs, ours) {
     return (...args) => {
         if (typeof theirs === 'function')
             theirs(...args);
-        ours();
+        ours(...args);
     };
 }
 /**

package/dist/tree/llms.txt

@@ -8,7 +8,7 @@ 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">
-            <button class="kpt-tree__toggle">…chevron…</button>
+            <span class="kpt-tree__toggle" aria-hidden="true">…chevron…</span>
             <span class="kpt-tree__icon">…</span>
             <span class="kpt-tree__label">src</span>
           </div>
@@ -25,21 +25,33 @@ Import: `import { KptTree, type KptTreeNode } from '@konce-pt/react';`
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Expansion is component state, not data
-The Angular port flips `node.expanded` in place and bumps a version signal. In React that would be
-a side effect on someone else's array during render, so the open branches live in a `Set` of node
-references instead — and `expanded` in the data goes back to being what it should be: the initial
-state, read once on mount.
+`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
+independently, and replacing `nodes` with new objects brings their own initial state.
 
 ## Examples
     <KptTree nodes={tree} />
     <KptTree nodes={tree} selectable selected={node} onSelectedChange={setNode} />
 
+## 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.
+The logic is the pure function `treeKeyAction` in `tree-keys.ts`; the other port has a twin file.
+
 ## i18n
-The toggle is labelled from `tree.expand` / `tree.collapse`.
+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.
 
 ## Tokens
 The selected row `--kpt-color-primary`, the hover `--kpt-color-surface-variant`.
 
 ## Accessibility
-`role="tree"` / `role="treeitem"` with `aria-expanded` on branches only; the indentation is
-`padding-inline-start`, so it follows the writing direction.
+`role="tree"`, `treeitem` and `group`; branches carry `aria-expanded`, every row `aria-level`,
+selectable trees `aria-selected`, disabled rows `aria-disabled`. The chevron is mouse-only
+(`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.

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

@@ -0,0 +1,27 @@
+/** Widoczny wiersz drzewa w kolejności DOM (preorder, tylko rozwinięte gałęzie). */
+export interface KptTreeRow {
+    /** Ma dzieci, więc da się go rozwinąć. */
+    expandable: boolean;
+    open: boolean;
+    /** Indeks rodzica w tej samej liście albo `-1` dla korzenia. */
+    parent: number;
+}
+/** Co zrobić po naciśnięciu klawisza: przenieść fokus, przełączyć gałąź albo aktywować wiersz. */
+export type KptTreeKeyAction = {
+    type: 'focus';
+    index: number;
+} | {
+    type: 'toggle';
+    index: number;
+} | {
+    type: 'activate';
+    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.
+ */
+export declare function treeKeyAction(rows: readonly KptTreeRow[], current: number, key: string): KptTreeKeyAction | null;

package/dist/tree/tree-keys.js

@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+export function treeKeyAction(rows, current, key) {
+    const row = rows[current];
+    if (!row)
+        return null;
+    switch (key) {
+        case 'ArrowDown':
+            return current < rows.length - 1 ? { type: 'focus', index: current + 1 } : null;
+        case 'ArrowUp':
+            return current > 0 ? { type: 'focus', index: current - 1 } : null;
+        case 'Home':
+            return { type: 'focus', index: 0 };
+        case 'End':
+            return { type: 'focus', index: rows.length - 1 };
+        case 'ArrowRight':
+            if (!row.expandable)
+                return null;
+            return row.open ? { type: 'focus', index: current + 1 } : { type: 'toggle', index: current };
+        case 'ArrowLeft':
+            if (row.expandable && row.open)
+                return { type: 'toggle', index: current };
+            return row.parent >= 0 ? { type: 'focus', index: row.parent } : null;
+        case 'Enter':
+        case ' ':
+            return { type: 'activate', index: current };
+        default:
+            return null;
+    }
+}

package/dist/tree/tree.d.ts

@@ -1,5 +1,5 @@
 import { type ComponentPropsWithRef } from 'react';
-import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+import type { KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptTreeNode<T = unknown> {
     label: string;
     value?: T;
@@ -21,11 +21,18 @@ export interface KptTreeProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onS
 /**
  * Drzewo hierarchiczne: rozwijanie, zaznaczanie, ikony.
  *
- * Stan rozwinięcia trzyma komponent w zbiorze węzłów, 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.
+ * 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.
+ *
+ * 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:
+ * 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, dictionary, className, ...rest }: Readonly<KptTreeProps<T>>): import("react").JSX.Element;
+export declare function KptTree<T>({ nodes, selectable, selected, defaultSelected, onSelectedChange, onNodeClick, locale: _locale, dictionary: _dictionary, className, ...rest }: Readonly<KptTreeProps<T>>): import("react").JSX.Element;