@konce-pt/react 0.11.1 → 0.12.0

package/dist/tooltip/tooltip.js

@@ -1,13 +1,86 @@
+'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";
+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;
 /**
- * Dymek podpowiedzi pokazywany na hover i focus. Lekki — element dodawany do `body`
- * i pozycjonowany względem dziecka.
+ * 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'],
+    left: ['left', 'right', 'top', 'bottom'],
+    right: ['right', 'left', 'top', 'bottom'],
+};
+/**
+ * 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
+ * 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.
+ */
+function placeTooltip(host, tip, preferred) {
+    const r = host.getBoundingClientRect();
+    const t = tip.getBoundingClientRect();
+    const gap = 8;
+    const margin = 4;
+    const vw = document.documentElement.clientWidth;
+    const vh = document.documentElement.clientHeight;
+    const at = (side) => {
+        switch (side) {
+            case 'bottom':
+                return { top: r.bottom + gap, left: r.left + r.width / 2 - t.width / 2 };
+            case 'left':
+                return { top: r.top + r.height / 2 - t.height / 2, left: r.left - t.width - gap };
+            case 'right':
+                return { top: r.top + r.height / 2 - t.height / 2, left: r.right + gap };
+            default:
+                return { top: r.top - t.height - gap, left: r.left + r.width / 2 - t.width / 2 };
+        }
+    };
+    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.
+        return side === 'top' || side === 'bottom'
+            ? top >= margin && top + t.height <= vh - margin
+            : left >= margin && left + t.width <= vw - margin;
+    };
+    // Punkt 2 px w głąb hosta przy krawędzi danej strony; widoczny, gdy na wierzchu jest host, jego
+    // potomek albo sam dymek (stoi jeszcze w poprzednim miejscu).
+    const exposed = (side) => {
+        const x = side === 'left' ? r.left + 2 : side === 'right' ? r.right - 2 : r.left + r.width / 2;
+        const y = side === 'top' ? r.top + 2 : side === 'bottom' ? r.bottom - 2 : r.top + r.height / 2;
+        if (x < 0 || y < 0 || x >= vw || y >= vh)
+            return false;
+        const hit = document.elementFromPoint(x, y);
+        return !hit || host.contains(hit) || tip.contains(hit);
+    };
+    const side = FALLBACKS[preferred].find((s) => fits(s) && exposed(s)) ?? preferred;
+    const { top, left } = at(side);
+    tip.dataset['side'] = side;
+    tip.style.top = `${Math.min(Math.max(margin, top), Math.max(margin, vh - t.height - margin))}px`;
+    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` (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.
@@ -23,9 +96,18 @@ const HIDE_DELAY_MS = 120;
  */
 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.
@@ -60,63 +142,41 @@ export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false,
         const host = hostRef.current;
         if (!tip || !host)
             return;
-        const r = host.getBoundingClientRect();
-        const t = tip.getBoundingClientRect();
-        const gap = 8;
-        let top;
-        let left;
-        switch (position) {
-            case 'bottom':
-                top = r.bottom + gap;
-                left = r.left + r.width / 2 - t.width / 2;
-                break;
-            case 'left':
-                top = r.top + r.height / 2 - t.height / 2;
-                left = r.left - t.width - gap;
-                break;
-            case 'right':
-                top = r.top + r.height / 2 - t.height / 2;
-                left = r.right + gap;
-                break;
-            default:
-                top = r.top - t.height - gap;
-                left = r.left + r.width / 2 - t.width / 2;
-        }
-        tip.style.top = `${Math.max(4, top)}px`;
-        tip.style.left = `${Math.max(4, left)}px`;
+        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';
@@ -125,26 +185,56 @@ export function KptTooltip({ text, position = 'top', onlyWhenTruncated = false,
         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]);
+        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;
@@ -156,13 +246,16 @@ 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. */
 function chain(theirs, ours) {

package/dist/tree/llms.txt

@@ -55,3 +55,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.d.ts

@@ -17,6 +17,11 @@ 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;
 }
 /**
  * Drzewo hierarchiczne: rozwijanie, zaznaczanie, ikony.
@@ -35,4 +40,4 @@ export interface KptTreeProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onS
  * @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, locale: _locale, dictionary: _dictionary, className, ...rest }: Readonly<KptTreeProps<T>>): import("react").JSX.Element;

package/dist/tree/tree.js

@@ -1,3 +1,4 @@
+'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";
@@ -21,7 +22,7 @@ import { treeKeyAction } from "./tree-keys.js";
  * @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, locale: _locale, dictionary: _dictionary, className, ...rest }) {
     const [active, setActive] = useControllableState({
         value: selected,
         defaultValue: defaultSelected,
@@ -34,6 +35,7 @@ export function KptTree({ nodes = [], selectable = false, selected, defaultSelec
     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 hasChildren = (node) => !!node.children?.length;
     const isOpen = (node) => toggled.get(node) ?? !!node.expanded;
@@ -56,12 +58,17 @@ export function KptTree({ nodes = [], selectable = false, selected, defaultSelec
     // 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('[role="treeitem"]')[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 next = new Map(toggled);
@@ -94,7 +101,7 @@ 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) => {
@@ -104,5 +111,5 @@ export function KptTree({ nodes = [], selectable = false, selected, defaultSelec
                             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) }) }));
+    return (_jsx("div", { className: cn('kpt-tree-host', className), ...rest, children: _jsx("ul", { ref: treeRef, className: "kpt-tree", role: "tree", "aria-label": ariaLabel || undefined, children: renderList(nodes, 0) }) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konce-pt/react",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Open-source React 19 component library on the Koncept UI design system — the same kpt-* CSS layer and --kpt-* tokens as the Angular port. Zero runtime dependencies.",
   "license": "MIT",
   "author": "konce.pt",
@@ -60,22 +60,22 @@
     }
   },
   "peerDependencies": {
-    "react": ">=19.0.0",
-    "react-dom": ">=19.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "leaflet": "^1.9.0"
   },
   "dependencies": {
-    "@konce-pt/roadmap": "0.11.1",
-    "@konce-pt/backdrop": "0.11.1",
-    "@konce-pt/chart": "0.11.1",
-    "@konce-pt/table": "0.11.1",
-    "@konce-pt/icons": "0.11.1",
-    "@konce-pt/chat": "0.11.1",
-    "@konce-pt/map": "0.11.1",
-    "@konce-pt/datetime": "0.11.1",
-    "@konce-pt/mention": "0.11.1",
-    "@konce-pt/tokens": "0.11.1",
-    "@konce-pt/i18n": "0.11.1"
+    "@konce-pt/datetime": "0.12.0",
+    "@konce-pt/icons": "0.12.0",
+    "@konce-pt/chart": "0.12.0",
+    "@konce-pt/backdrop": "0.12.0",
+    "@konce-pt/map": "0.12.0",
+    "@konce-pt/tokens": "0.12.0",
+    "@konce-pt/i18n": "0.12.0",
+    "@konce-pt/table": "0.12.0",
+    "@konce-pt/mention": "0.12.0",
+    "@konce-pt/chat": "0.12.0",
+    "@konce-pt/roadmap": "0.12.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.0",
@@ -93,6 +93,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/copy-llms.mjs",
+    "lint": "eslint .",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
   }
 }