@konce-pt/react 0.11.1 → 0.12.0

package/dist/rich-text/sanitize.js

@@ -1,7 +1,6 @@
 /*
- * Sanityzacja treści edytora. Kod nie zna Reacta — operuje wyłącznie na DOM, więc gdyby port
- * Angulara kiedyś sięgnął po wspólny rdzeń, wystarczy przenieść ten plik do osobnej paczki
- * (jak `@konce-pt/datetime`).
+ * Sanityzacja treści edytora. Kod nie zna frameworka — operuje wyłącznie na DOM. Bliźniak
+ * w porcie Angulara: `rich-text/sanitize.ts` — zmiana w obu (docelowo wspólna paczka pure-TS).
  */
 /** Znaczniki dopuszczone w treści; pozostałe rozwijamy do dzieci, nie usuwając tekstu. */
 const ALLOWED_TAGS = new Set([
@@ -17,15 +16,29 @@ const ALLOWED_STYLES = new Set([
  * `data-mention` i `contenteditable` są tu dla wzmianek: identyfikator musi przeżyć zapis treści,
  * a `contenteditable="false"` trzyma wzmiankę jako jeden kawałek, w którego środku nie da się
  * pisać. Oba atrybuty są bierne — nie wykonują niczego i nie wskazują zasobów, więc wpuszczenie
- * ich nie otwiera nowej furtki.
+ * ich nie otwiera nowej furtki. `class` przechodzi osobno, tylko z klasami samego edytora.
  */
 const ALLOWED_ATTRS = new Set([
-    'colspan', 'rowspan', 'span', 'width', 'class', 'target', 'rel', 'title',
+    'colspan', 'rowspan', 'span', 'width', 'target', 'rel', 'title', 'color',
     'data-mention', 'contenteditable',
 ]);
-// Schematy dopuszczone w `href` narzędzia „link"; blocklista byłaby obchodzalna.
+/**
+ * Klasy, które zostawia sam edytor (`kpt-rt-table`, `kpt-mention`). Obce klasy z wklejki — aplikacji,
+ * biblioteki (`kpt-dialog`, `kpt-visually-hidden`) czy Tailwinda — przejęłyby ich wygląd tam,
+ * gdzie aplikacja wyświetla treść.
+ */
+const EDITOR_CLASS = /^kpt-(rt-[a-z0-9-]+|mention)$/;
+// Schematy dopuszczone w `href` — ta sama allowlista dla narzędzia „link” i dla wklejonego HTML.
 const SAFE_URL_SCHEME = /^(https?:|mailto:|tel:)/i;
 const HAS_URL_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/** Znaki sterujące, które przeglądarka pomija przy parsowaniu URL-a (`jav\tascript:`). */
+// eslint-disable-next-line no-control-regex -- celowo: właśnie te znaki trzeba wyciąć przed testem schematu
+const URL_CONTROL = /[\x00-\x1f]/g;
+/** Czy adres z treści może zostać: względny (bez schematu) albo ze schematu z allowlisty. */
+function isSafeHref(value) {
+    const compact = value.replace(URL_CONTROL, '').trim();
+    return !HAS_URL_SCHEME.test(compact) || SAFE_URL_SCHEME.test(compact);
+}
 /** Deklaracje `style` z allowlisty; `null`, gdy nie zostaje nic. */
 function sanitizeStyleAttr(value) {
     const kept = value
@@ -34,56 +47,91 @@ function sanitizeStyleAttr(value) {
         .filter((decl) => ALLOWED_STYLES.has(decl.split(':')[0]?.trim().toLowerCase() ?? ''));
     return kept.length ? kept.join('; ') : null;
 }
-function sanitizeAttribute(el, attr) {
+function sanitizeAttribute(el, attr, report) {
     const name = attr.name.toLowerCase();
-    if (name.startsWith('on')) {
+    const remove = () => {
         el.removeAttribute(attr.name);
-    }
-    else if (name === 'href' || name === 'src') {
-        // Znaki kontrolne usuwamy przed testem schematu — przeglądarka i tak je pomija przy
-        // parsowaniu URL-a, więc `jav\tascript:` obszedłby samo porównanie napisów.
-        // eslint-disable-next-line no-control-regex
-        if (/^\s*javascript:/i.test(attr.value.replace(/[\x00-\x1f]/g, '')))
-            el.removeAttribute(attr.name);
+        report.changed = true;
+    };
+    if (name === 'href') {
+        if (!isSafeHref(attr.value))
+            remove();
     }
     else if (name === 'style') {
         const kept = sanitizeStyleAttr(attr.value);
-        if (kept)
+        const declared = attr.value.split(';').filter((decl) => decl.trim()).length;
+        if (kept === null)
+            remove();
+        else if (kept.split('; ').length !== declared) {
+            // Zmiana tylko wtedy, gdy wypadła deklaracja — samo przeformatowanie zapisu się nie liczy.
             el.setAttribute('style', kept);
-        else
-            el.removeAttribute('style');
+            report.changed = true;
+        }
     }
-    else if (!ALLOWED_ATTRS.has(name) && name !== 'color') {
-        el.removeAttribute(attr.name);
+    else if (name === 'class') {
+        const tokens = attr.value.split(/\s+/).filter(Boolean);
+        const kept = tokens.filter((token) => EDITOR_CLASS.test(token));
+        if (kept.length === 0)
+            remove();
+        else if (kept.length !== tokens.length) {
+            el.setAttribute('class', kept.join(' '));
+            report.changed = true;
+        }
     }
+    else if (!ALLOWED_ATTRS.has(name)) {
+        // Także `on*` i `src` — żaden dopuszczony znacznik nie ładuje zasobów.
+        remove();
+    }
+}
+/** Link otwierany w nowej karcie dostaje `noopener noreferrer` — bez tego karta sięga do `opener`. */
+function secureTarget(el, report) {
+    if (el.tagName !== 'A' || !el.hasAttribute('target'))
+        return;
+    const rel = new Set((el.getAttribute('rel') ?? '').split(/\s+/).filter(Boolean));
+    if (rel.has('noopener') && rel.has('noreferrer'))
+        return;
+    rel.add('noopener');
+    rel.add('noreferrer');
+    el.setAttribute('rel', [...rel].join(' '));
+    report.changed = true;
 }
 /** Tag spoza allowlisty rozwijamy do dzieci; atrybuty czyścimy po kolei. */
-function sanitizeElement(el) {
+function sanitizeElement(el, report) {
     if (!ALLOWED_TAGS.has(el.tagName)) {
         el.replaceWith(...Array.from(el.childNodes));
+        report.changed = true;
         return;
     }
     for (const attr of Array.from(el.attributes))
-        sanitizeAttribute(el, attr);
+        sanitizeAttribute(el, attr, report);
+    secureTarget(el, report);
 }
 /**
- * Czyści HTML wchodzący do edytora. Dotyczy **każdego** zapisu do DOM edytora, nie tylko
- * wklejania: `value` z aplikacji też bywa niezaufane (baza, CMS, inny użytkownik).
+ * Czyści HTML i mówi, czy coś usunął. `changed: false` znaczy, że treść była czysta — wtedy
+ * wołający nie musi nadpisywać wartości modelu (serializacja DOM potrafi zmienić zapis, np.
+ * cudzysłowy, bez zmiany treści, a taka różnica nie może brudzić formularza).
  */
-export function sanitizeHtml(html) {
+export function sanitizeHtmlReport(html) {
     const template = document.createElement('template');
     template.innerHTML = html;
+    const report = { changed: false };
     for (const el of Array.from(template.content.querySelectorAll('*')))
-        sanitizeElement(el);
-    return template.innerHTML;
+        sanitizeElement(el, report);
+    return { html: template.innerHTML, changed: report.changed };
+}
+/**
+ * Czyści HTML wchodzący do edytora. Dotyczy **każdego** zapisu do DOM edytora, nie tylko
+ * wklejania: `value` z aplikacji też bywa niezaufane (baza, CMS, inny użytkownik).
+ */
+export function sanitizeHtml(html) {
+    return sanitizeHtmlReport(html).html;
 }
 /**
  * Waliduje URL z narzędzia „link". Brak schematu → dopisujemy `https://`; `#` i `/` przechodzą
  * bez zmian; schemat spoza allowlisty → `null`, czyli link nie zostaje wstawiony.
  */
 export function sanitizeUrl(url) {
-    // eslint-disable-next-line no-control-regex
-    const trimmed = url.trim().replace(/[\x00-\x1f]/g, '');
+    const trimmed = url.trim().replace(URL_CONTROL, '');
     if (!trimmed)
         return null;
     if (trimmed.startsWith('#') || trimmed.startsWith('/'))

package/dist/roadmap/llms.txt

@@ -69,7 +69,7 @@ frame without arrows beats arrows in the wrong place.
 - Entries with an invalid date or a duplicate `id` are skipped, with a warning in a development build.
 
 ## i18n
-The `roadmap.*` keys: `empty`, `week`, `today`, `milestone`, `expandGroup`, `collapseGroup`.
+The `roadmap.*` keys: `empty`, `week`, `today`, `milestone`, `expandGroup`, `collapseGroup`, `progress` (`{percent}`).
 Month and weekday names come from `Intl` per `config.locale` or the locale from `KptI18nProvider`.
 
 ## Tokens
@@ -78,5 +78,11 @@ bars per variant `--kpt-color-{primary,success,danger,warning,info,muted}`.
 Sizes: `--kpt-roadmap-label-w`, `--kpt-roadmap-cell-w` (both can be overridden from outside).
 
 ## Accessibility
-Group toggles are real buttons with `aria-expanded`; bars and milestones are focusable and answer
-Enter and Space like a click. The background grid and the dependency layer are `aria-hidden`.
+Bars and milestones are `role="button"` with an accessible name built from the label, sublabel, date range
+and progress (`Design, 3–14 Mar 2026, 40% complete`) — the end is exclusive, so the last occupied day is
+announced. The whole bar grid is one Tab stop (roving tabindex): Left/Right move within a row, Up/Down go to
+the bar with the nearest start in the neighbouring row, Home/End jump to the row's edge, Ctrl+Home/End to the
+first/last bar; Enter and Space act like a click. With `virtual` on, moving to a row outside the window
+scrolls it in first. Disabled items get `aria-disabled`. A group toggle is named by the group label and
+carries `aria-expanded`; "Expand/Collapse group" is only its tooltip. The background grid and the dependency
+layer are `aria-hidden`.

package/dist/roadmap/roadmap.js

@@ -1,6 +1,7 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { buildRows, buildTimeline, linkGeometry, resolveLinks, resolveRange, sliceRows, } from '@konce-pt/roadmap';
+import { buildRows, buildTimeline, linkGeometry, resolveLinks, resolveRange, roadmapItemDates, roadmapNavTarget, sliceRows, } from '@konce-pt/roadmap';
 import { cn } from "../internal/cn.js";
 import { isDevBuild } from "../internal/dev.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
@@ -44,9 +45,9 @@ export function KptRoadmap({ config, scrollHeight = null, labelWidth = '14rem',
      * efekt zrobiłby to samo o jeden render za późno, czyli po mignięciu rozwiniętej grupy.
      */
     const [fromConfig, setFromConfig] = useState(() => declaredCollapsed(config.groups));
-    const groupsRef = useRef(config.groups);
-    if (groupsRef.current !== config.groups) {
-        groupsRef.current = config.groups;
+    const [prevGroups, setPrevGroups] = useState(config.groups);
+    if (prevGroups !== config.groups) {
+        setPrevGroups(config.groups);
         setFromConfig(declaredCollapsed(config.groups));
     }
     /** Suma obu źródeł — stan faktycznie użyty do budowy wierszy. */
@@ -68,6 +69,28 @@ export function KptRoadmap({ config, scrollHeight = null, labelWidth = '14rem',
         weekPrefix: config.timeline?.weekPrefix ?? t('roadmap.week'),
     }), [range, zoom, config, locale, t]);
     const layout = useMemo(() => buildRows(config.items, config.groups, collapsedIds, config.rows), [config.items, config.groups, config.rows, collapsedIds]);
+    const itemLocale = config.locale ?? config.timeline?.locale ?? locale;
+    /**
+     * Paski widoczne na osi, wiersz po wierszu — mapa dla nawigacji strzałkami. Liczona ze wszystkich
+     * wierszy, nie z okna wirtualizacji: strzałka w dół z ostatniego wyrenderowanego wiersza ma dokąd iść.
+     */
+    const navGrid = useMemo(() => layout.rows.map((row) => row.kind === 'group'
+        ? []
+        : row.items
+            .filter((item) => timeline.span(item.start, item.end).visible)
+            .map((item) => ({ id: item.id, start: item.start }))
+            .sort((a, b) => a.start - b.start)), [layout, timeline]);
+    /** Pasek, na którym ostatnio był fokus. */
+    const [activeId, setActiveId] = useState(null);
+    /**
+     * Jedyny przystanek Tab w siatce pasków (roving tabindex) — ostatnio aktywny pasek, a gdy zniknął
+     * (zwinięta grupa, inne dane), pierwszy. Bez tego roadmapa ze stu zadaniami to sto przystanków Tab.
+     */
+    const tabStopId = useMemo(() => {
+        if (activeId && navGrid.some((row) => row.some((item) => item.id === activeId)))
+            return activeId;
+        return navGrid.find((row) => row.length > 0)?.[0].id ?? null;
+    }, [navGrid, activeId]);
     /** Wiersze faktycznie renderowane — całość albo okno wirtualizacji. */
     const visibleRows = useMemo(() => {
         if (!virtual || viewportHeight <= 0)
@@ -110,6 +133,21 @@ export function KptRoadmap({ config, scrollHeight = null, labelWidth = '14rem',
         const total = row.laneCount * barHeight + (row.laneCount - 1) * LANE_GAP;
         return Math.max(0, (row.height - total) / 2) + lane * laneStep;
     }, [barHeight, laneStep]);
+    /** Nazwa dostępna paska: „Etykieta, 3–14 mar 2026, ukończono 40%". */
+    const itemAriaLabel = useCallback((item) => {
+        const source = item.source;
+        const dates = roadmapItemDates(item.start, item.end, itemLocale, {
+            isMilestone: item.isMilestone,
+            withTime: zoom === 'hour',
+        });
+        const parts = [item.isMilestone ? `${t('roadmap.milestone')}: ${source.label}` : source.label, dates];
+        if (source.sublabel)
+            parts.splice(1, 0, source.sublabel);
+        if (source.progress != null && !item.isMilestone) {
+            parts.push(t('roadmap.progress', { percent: Math.round(source.progress * 100) }));
+        }
+        return parts.join(', ');
+    }, [itemLocale, zoom, t]);
     /** Paski danego wiersza gotowe do renderu. */
     const bars = useCallback((row) => {
         const result = [];
@@ -132,10 +170,11 @@ export function KptRoadmap({ config, scrollHeight = null, labelWidth = '14rem',
                 isMilestone: item.isMilestone,
                 clippedStart: geom.clippedStart,
                 clippedEnd: geom.clippedEnd,
+                ariaLabel: itemAriaLabel(item),
             });
         }
         return result;
-    }, [timeline, barTop, barHeight]);
+    }, [timeline, barTop, barHeight, itemAriaLabel]);
     /** Pasek zbiorczy wiersza grupy. */
     const summary = useCallback((row) => {
         const span = row.groupState?.span;
@@ -208,11 +247,49 @@ export function KptRoadmap({ config, scrollHeight = null, labelWidth = '14rem',
             return;
         onItemClick?.(item.source);
     };
+    /** Przy wirtualizacji przewija tak, żeby wiersz z paskiem wszedł do okna i się wyrenderował. */
+    const revealRow = (scroll, id) => {
+        if (!virtual)
+            return;
+        const row = layout.rows.find((candidate) => candidate.items.some((item) => item.id === id));
+        if (!row)
+            return;
+        const header = scroll.querySelector('.kpt-roadmap__head')?.offsetHeight ?? 0;
+        const viewport = scroll.clientHeight - header;
+        let top = scroll.scrollTop;
+        if (row.top < top)
+            top = row.top;
+        else if (row.top + row.height > top + viewport)
+            top = row.top + row.height - viewport;
+        if (top === scroll.scrollTop)
+            return;
+        scroll.scrollTop = top;
+        setScrollTop(top);
+    };
+    /**
+     * Klawiatura na pasku: Enter/Spacja działają jak kliknięcie, strzałki przenoszą fokus po siatce
+     * (w poziomie po wierszu, w pionie między wierszami), Home/End na skraj wiersza, z Ctrl — roadmapy.
+     */
     const handleItemKeydown = (event, item) => {
-        if (event.key !== 'Enter' && event.key !== ' ')
+        if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            handleItemClick(item);
+            return;
+        }
+        const target = roadmapNavTarget(navGrid, item.id, event.key, event.ctrlKey || event.metaKey);
+        if (!target)
             return;
         event.preventDefault();
-        handleItemClick(item);
+        setActiveId(target);
+        const scroll = event.currentTarget.closest('.kpt-roadmap__scroll');
+        if (!scroll)
+            return;
+        revealRow(scroll, target);
+        // Pasek z innego wiersza może jeszcze nie istnieć w DOM (wirtualizacja). Aktualizacja ze zdarzenia
+        // klawiatury jest zatwierdzana synchronicznie, więc w następnej klatce pasek już jest.
+        requestAnimationFrame(() => {
+            scroll.querySelector(`[data-kpt-item="${CSS.escape(target)}"]`)?.focus();
+        });
     };
     /**
      * Treść dymka dla kolumny etykiet. Pusta tam, gdzie dymek nie miałby czego
@@ -242,25 +319,25 @@ export function KptRoadmap({ config, scrollHeight = null, labelWidth = '14rem',
                             const group = row.group;
                             const first = row.items[0];
                             const sum = row.kind === 'group' ? summary(row) : null;
-                            return (_jsxs("div", { className: cn('kpt-roadmap__row', row.kind === 'group' && 'kpt-roadmap__row--group'), style: { insetBlockStart: `${row.top}px`, blockSize: `${row.height}px` }, children: [_jsx(KptTooltip, { text: labelTooltip(row), onlyWhenTruncated: true, children: _jsx("div", { className: cn('kpt-roadmap__label', row.kind === 'group' && 'kpt-roadmap__label--group'), style: { paddingInlineStart: `${0.75 + row.depth * 1}rem` }, children: group ? (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "kpt-roadmap__toggle", "aria-expanded": !isCollapsed(group), "aria-label": isCollapsed(group) ? t('roadmap.expandGroup') : t('roadmap.collapseGroup'), onClick: () => toggleGroup(group), children: _jsx("span", { className: cn('kpt-roadmap__toggle-icon', !isCollapsed(group) && 'kpt-roadmap__toggle-icon--open') }) }), _jsx(KptTooltip, { text: group.sublabel ? `${group.label} — ${group.sublabel}` : group.label, onlyWhenTruncated: true, children: _jsxs("span", { className: "kpt-roadmap__label-stack", children: [_jsx("span", { className: "kpt-roadmap__label-text kpt-roadmap__label-text--group", children: group.label }), group.sublabel && _jsx("span", { className: "kpt-roadmap__label-sub", children: group.sublabel })] }) }), row.groupState?.itemCount ? (_jsx("span", { className: "kpt-roadmap__label-count", children: row.groupState.itemCount })) : null] })) : (first && (_jsxs(_Fragment, { children: [_jsx("span", { className: "kpt-roadmap__label-text", children: first.source.label }), row.items.length === 1 && first.source.sublabel && (_jsx("span", { className: "kpt-roadmap__label-sub", children: first.source.sublabel }))] }))) }) }), _jsx("div", { className: "kpt-roadmap__lane", children: row.kind === 'group'
+                            return (_jsxs("div", { className: cn('kpt-roadmap__row', row.kind === 'group' && 'kpt-roadmap__row--group'), style: { insetBlockStart: `${row.top}px`, blockSize: `${row.height}px` }, children: [_jsx(KptTooltip, { text: labelTooltip(row), onlyWhenTruncated: true, children: _jsx("div", { className: cn('kpt-roadmap__label', row.kind === 'group' && 'kpt-roadmap__label--group'), style: { paddingInlineStart: `${0.75 + row.depth * 1}rem` }, children: group ? (_jsxs(_Fragment, { children: [_jsx(KptTooltip, { text: isCollapsed(group) ? t('roadmap.expandGroup') : t('roadmap.collapseGroup'), children: _jsx("button", { type: "button", className: "kpt-roadmap__toggle", "aria-expanded": !isCollapsed(group), "aria-label": group.label, onClick: () => toggleGroup(group), children: _jsx("span", { className: cn('kpt-roadmap__toggle-icon', !isCollapsed(group) && 'kpt-roadmap__toggle-icon--open') }) }) }), _jsx(KptTooltip, { text: group.sublabel ? `${group.label} — ${group.sublabel}` : group.label, onlyWhenTruncated: true, children: _jsxs("span", { className: "kpt-roadmap__label-stack", children: [_jsx("span", { className: "kpt-roadmap__label-text kpt-roadmap__label-text--group", children: group.label }), group.sublabel && _jsx("span", { className: "kpt-roadmap__label-sub", children: group.sublabel })] }) }), row.groupState?.itemCount ? (_jsx("span", { className: "kpt-roadmap__label-count", children: row.groupState.itemCount })) : null] })) : (first && (_jsxs(_Fragment, { children: [_jsx("span", { className: "kpt-roadmap__label-text", children: first.source.label }), row.items.length === 1 && first.source.sublabel && (_jsx("span", { className: "kpt-roadmap__label-sub", children: first.source.sublabel }))] }))) }) }), _jsx("div", { className: "kpt-roadmap__lane", children: row.kind === 'group'
                                             ? sum && (_jsx("div", { className: "kpt-roadmap__summary", "data-variant": sum.variant, style: {
                                                     insetInlineStart: `${sum.left}%`,
                                                     inlineSize: `${sum.width}%`,
                                                     backgroundColor: sum.color,
                                                 } }))
-                                            : bars(row).map((bar) => bar.isMilestone ? (_jsx(KptTooltip, { text: bar.title, children: _jsx("div", { className: "kpt-roadmap__milestone", "data-variant": bar.variant, "aria-label": `${t('roadmap.milestone')}: ${bar.label}`, style: {
+                                            : bars(row).map((bar) => bar.isMilestone ? (_jsx(KptTooltip, { text: bar.title, children: _jsx("div", { className: "kpt-roadmap__milestone", "data-variant": bar.variant, style: {
                                                         insetInlineStart: `${bar.left}%`,
                                                         insetBlockStart: `${bar.top}px`,
                                                         inlineSize: `${bar.height}px`,
                                                         blockSize: `${bar.height}px`,
                                                         backgroundColor: bar.color,
-                                                    }, tabIndex: 0, onClick: () => handleItemClick(bar.item), onKeyDown: (event) => handleItemKeydown(event, bar.item) }) }, bar.item.id)) : (_jsx(KptTooltip, { text: bar.title, onlyWhenTruncated: true, children: _jsxs("div", { className: cn('kpt-roadmap__bar', bar.clippedStart && 'kpt-roadmap__bar--clipped-start', bar.clippedEnd && 'kpt-roadmap__bar--clipped-end', bar.item.source.disabled && 'kpt-roadmap__bar--disabled'), "data-variant": bar.variant, style: {
+                                                    }, role: "button", "aria-label": bar.ariaLabel, "aria-disabled": bar.item.source.disabled || undefined, "data-kpt-item": bar.item.id, tabIndex: bar.item.id === tabStopId ? 0 : -1, onClick: () => handleItemClick(bar.item), onFocus: () => setActiveId(bar.item.id), onKeyDown: (event) => handleItemKeydown(event, bar.item) }) }, bar.item.id)) : (_jsx(KptTooltip, { text: bar.title, onlyWhenTruncated: true, children: _jsxs("div", { className: cn('kpt-roadmap__bar', bar.clippedStart && 'kpt-roadmap__bar--clipped-start', bar.clippedEnd && 'kpt-roadmap__bar--clipped-end', bar.item.source.disabled && 'kpt-roadmap__bar--disabled'), "data-variant": bar.variant, style: {
                                                         insetInlineStart: `${bar.left}%`,
                                                         inlineSize: `${bar.width}%`,
                                                         insetBlockStart: `${bar.top}px`,
                                                         blockSize: `${bar.height}px`,
                                                         backgroundColor: bar.color,
-                                                    }, tabIndex: 0, onClick: () => handleItemClick(bar.item), onKeyDown: (event) => handleItemKeydown(event, bar.item), children: [bar.progress !== null && (_jsx("span", { className: "kpt-roadmap__bar-progress", style: { inlineSize: `${bar.progress * 100}%` } })), _jsx("span", { className: "kpt-roadmap__bar-label", children: bar.label })] }) }, bar.item.id))) })] }, row.key));
+                                                    }, role: "button", "aria-label": bar.ariaLabel, "aria-disabled": bar.item.source.disabled || undefined, "data-kpt-item": bar.item.id, tabIndex: bar.item.id === tabStopId ? 0 : -1, onClick: () => handleItemClick(bar.item), onFocus: () => setActiveId(bar.item.id), onKeyDown: (event) => handleItemKeydown(event, bar.item), children: [bar.progress !== null && (_jsx("span", { className: "kpt-roadmap__bar-progress", style: { inlineSize: `${bar.progress * 100}%` } })), _jsx("span", { className: "kpt-roadmap__bar-label", children: bar.label })] }) }, bar.item.id))) })] }, row.key));
                         })] }))] }) }));
 }
 /** Identyfikatory grup zwiniętych deklaratywnie w danych. */

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

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { cn } from "../internal/cn.js";

package/dist/select/llms.txt

@@ -68,3 +68,6 @@ The trigger is `role="combobox"` with `aria-haspopup="listbox"`, `aria-expanded`
 and `aria-activedescendant`; the list is `role="listbox"` with `aria-multiselectable`, and each
 option is `role="option"` with `aria-selected` and `aria-disabled`. Chip remove buttons sit outside
 the Tab order and are named with the option label.
+
+## Read-only and required
+`readOnly` shows the choice, but the panel does not open and the chips have no remove button (`aria-readonly`). The filter ignores case and diacritics ("lodz" finds "Łódź"), as in `listbox`. "No results" sits next to the list, not inside it (a listbox may contain only options).

package/dist/select/select.d.ts

@@ -13,6 +13,8 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
     /** Oznacza pole jako wymagane atrybutem `aria-required`. */
     required?: boolean;
     disabled?: boolean;
+    /** Tylko do odczytu — wybór widać, panel się nie otwiera (`aria-readonly`). */
+    readOnly?: boolean;
     invalid?: boolean;
     touched?: boolean;
     /** Wartość: pojedyncza (T) albo tablica (T[]) w trybie `multiple`. */
@@ -45,4 +47,4 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
  * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz…" />
  * <KptSelect options={tags} multiple filter value={tags} onValueChange={setTags} />
  */
-export declare function KptSelect<T>({ options, placeholder, multiple, filter, disabled, invalid, touched, value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, onTouch, locale, dictionary, className, onBlur, id, required, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptSelectProps<T>>): import("react").JSX.Element;
+export declare function KptSelect<T>({ options, placeholder, multiple, filter, disabled, readOnly, invalid, touched, value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, onTouch, locale, dictionary, className, onBlur, id, required, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptSelectProps<T>>): import("react").JSX.Element;

package/dist/select/select.js

@@ -1,6 +1,9 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { foldMentionText } from '@konce-pt/mention';
 import { cn } from "../internal/cn.js";
+import { optionKey } from "../internal/option-key.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptId } from "../internal/use-id.js";
@@ -8,6 +11,11 @@ import { KptTypeahead, OPTION_NAV_KEYS, isTypeaheadKey, nextOptionIndex, typeahe
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { joinIds, useKptFieldA11y, useKptFormFieldFilled } from "../form-field/form-field-context.js";
 import { KptIcon } from "../icon/icon.js";
+/** Filtr opcji bez wielkości liter i diakrytyków, jak w `KptListbox`: „lodz” znajduje „Łódź”. */
+function filterSelectOptions(options, text) {
+    const q = foldMentionText(text.trim());
+    return q ? options.filter((option) => foldMentionText(option.label).includes(q)) : options;
+}
 /**
  * Lista wyboru (select) na własnym panelu. Warianty: pojedynczy, z wyszukiwarką (`filter`)
  * i wielokrotny (`multiple`, chipy).
@@ -27,11 +35,13 @@ import { KptIcon } from "../icon/icon.js";
  * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz…" />
  * <KptSelect options={tags} multiple filter value={tags} onValueChange={setTags} />
  */
-export function KptSelect({ options = [], placeholder = '', multiple = false, filter = false, disabled = false, invalid = false, touched, value, defaultValue = null, onValueChange, open, defaultOpen = false, onOpenChange, onTouch, locale, dictionary, className, onBlur, id, required = false, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }) {
+export function KptSelect({ options = [], placeholder = '', multiple = false, filter = false, disabled = false, readOnly = false, invalid = false, touched, value, defaultValue = null, onValueChange, open, defaultOpen = false, onOpenChange, onTouch, locale, dictionary, className, onBlur, id, required = false, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...rest }) {
     /** `div` z rolą nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
     const field = useKptFieldA11y(id, 'kpt-select-trigger');
     const { t } = useKptMessages({ locale, dictionary });
     const triggerRef = useRef(null);
+    /** Kotwica nakładki w stanie (callback ref), nie `triggerRef.current` czytane w renderze. */
+    const [anchor, setAnchor] = useState(null);
     const searchRef = useRef(null);
     const typeahead = useRef(new KptTypeahead());
     const uid = useKptId(undefined, 'kpt-select');
@@ -52,35 +62,41 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
     const showInvalid = invalid && (touched ?? true);
     const selectedValues = useMemo(() => {
         if (multiple)
-            return Array.isArray(current) ? current : [];
+            return Array.isArray(current) ? (current) : [];
         return current == null ? [] : [current];
     }, [current, multiple]);
     const selectedOptions = useMemo(() => options.filter((option) => selectedValues.includes(option.value)), [options, selectedValues]);
-    const filterOptions = (text) => {
-        const q = text.trim().toLowerCase();
-        return q ? options.filter((option) => option.label.toLowerCase().includes(q)) : options;
-    };
-    const filteredOptions = useMemo(() => filterOptions(filterText), [options, filterText]); // eslint-disable-line react-hooks/exhaustive-deps
+    const filteredOptions = useMemo(() => filterSelectOptions(options, filterText), [options, filterText]);
     const disabledMap = filteredOptions.map((option) => !!option.disabled);
     const filled = selectedOptions.length > 0;
     useKptFormFieldFilled(filled);
     const isSelected = (option) => selectedValues.includes(option.value);
+    /** Skrajna opcja, na której ma się otworzyć lista (`Home`/`End`/`↑` na zamkniętym polu). */
+    const [openEdge, setOpenEdge] = useState(null);
     // Panel może zostać otwarty także z zewnątrz (`open`), nie tylko z pola — filtr i aktywną
-    // pozycję ustawiamy więc przy każdym otwarciu. Lista otwiera się na wybranej opcji; z `filter`
-    // fokus idzie do wyszukiwarki (klatkę później: `KptOverlay` mierzy panel w `visibility: hidden`).
-    // Tylko na otwarcie — zmiana wyboru w trybie `multiple` nie może przesuwać aktywnej opcji.
+    // pozycję ustawiamy więc przy każdym przejściu w stan otwarty, wzorcem „poprzednia wartość
+    // w stanie” (w tym samym renderze, bez efektu). Lista otwiera się na wybranej opcji; zmiana
+    // wyboru w trybie `multiple` przy otwartym panelu nie przesuwa aktywnej opcji.
+    const [wasOpen, setWasOpen] = useState(isOpen);
+    if (wasOpen !== isOpen) {
+        setWasOpen(isOpen);
+        if (isOpen) {
+            setFilterText('');
+            const disabledAll = options.map((o) => !!o.disabled);
+            const selected = options.findIndex((option) => selectedValues.includes(option.value));
+            const firstEnabled = nextOptionIndex(disabledAll, -1, 'ArrowDown') ?? -1;
+            setActiveIndex(openEdge ? (nextOptionIndex(disabledAll, -1, openEdge) ?? -1) : selected >= 0 ? selected : firstEnabled);
+            setOpenEdge(null);
+        }
+    }
+    // Z `filter` fokus idzie do wyszukiwarki — klatkę później, bo `KptOverlay` mierzy panel
+    // w `visibility: hidden`.
     useEffect(() => {
-        if (!isOpen)
-            return;
-        setFilterText('');
-        const selected = options.findIndex((option) => selectedValues.includes(option.value));
-        const firstEnabled = nextOptionIndex(options.map((o) => !!o.disabled), -1, 'ArrowDown') ?? -1;
-        setActiveIndex(selected >= 0 ? selected : firstEnabled);
-        if (!filter)
+        if (!isOpen || !filter)
             return;
         const frame = requestAnimationFrame(() => searchRef.current?.focus());
         return () => cancelAnimationFrame(frame);
-    }, [isOpen]); // eslint-disable-line react-hooks/exhaustive-deps
+    }, [isOpen, filter]);
     // Aktywna opcja zawsze w polu widzenia listy.
     useEffect(() => {
         if (isOpen && activeIndex >= 0)
@@ -116,21 +132,16 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
     };
     /** Jeden obsługiwacz dla pola i dla wyszukiwarki w panelu — różnią się tylko `Spacją` i `Tab`. */
     const onKeyDown = (event, source) => {
-        if (disabled)
+        if (disabled || readOnly)
             return;
         const key = event.key;
         if (!isOpen) {
             if (['ArrowDown', 'ArrowUp', 'Enter', ' ', 'Home', 'End'].includes(key)) {
                 event.preventDefault();
+                // Skrajne klawisze otwierają listę na pierwszej albo ostatniej opcji zamiast na wybranej.
+                if (key === 'ArrowUp' || key === 'End' || key === 'Home')
+                    setOpenEdge(key === 'Home' ? 'Home' : 'End');
                 setOpen(true);
-                if (key === 'ArrowUp' || key === 'End' || key === 'Home') {
-                    // Efekt otwarcia ustawia wybraną opcję; skrajne klawisze nadpisują to klatkę później.
-                    const target = nextOptionIndex(disabledMap, -1, key === 'Home' ? 'Home' : 'End');
-                    requestAnimationFrame(() => {
-                        if (target !== null)
-                            setActiveIndex(target);
-                    });
-                }
             }
             else if ((key === 'Backspace' || key === 'Delete') && multiple && selectedValues.length) {
                 event.preventDefault();
@@ -172,18 +183,21 @@ export function KptSelect({ options = [], placeholder = '', multiple = false, fi
             jumpTo(key);
         }
     };
-    return (_jsxs("span", { className: "kpt-select-host", children: [_jsxs("div", { ref: triggerRef, className: cn('kpt-select', isOpen && 'kpt-select--open', disabled && 'kpt-select--disabled', showInvalid && 'kpt-select--invalid', className), role: "combobox", id: field.id, tabIndex: 0, "aria-haspopup": "listbox", "aria-label": ariaLabel, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), "aria-required": required || undefined, "aria-expanded": isOpen, "aria-controls": isOpen ? listId : undefined, "aria-activedescendant": isOpen && !filter && activeIndex >= 0 ? optionId(activeIndex) : undefined, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, onClick: () => !disabled && setOpen(!isOpen), onKeyDown: (event) => onKeyDown(event, 'trigger'), onBlur: (event) => {
+    return (_jsxs("span", { className: "kpt-select-host", children: [_jsxs("div", { ref: (el) => {
+                    triggerRef.current = el;
+                    setAnchor(el);
+                }, className: cn('kpt-select', isOpen && 'kpt-select--open', disabled && 'kpt-select--disabled', readOnly && 'kpt-select--readonly', showInvalid && 'kpt-select--invalid', className), role: "combobox", id: field.id, tabIndex: 0, "aria-haspopup": "listbox", "aria-label": ariaLabel, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), "aria-required": required || undefined, "aria-readonly": readOnly || undefined, "aria-expanded": isOpen, "aria-controls": isOpen ? listId : undefined, "aria-activedescendant": isOpen && !filter && activeIndex >= 0 ? optionId(activeIndex) : undefined, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, onClick: () => !disabled && !readOnly && setOpen(!isOpen), onKeyDown: (event) => onKeyDown(event, 'trigger'), onBlur: (event) => {
                     onBlur?.(event);
                     // Przy otwartym panelu fokus idzie do pola szukania — „dotknięcie” wyśle dopiero zamknięcie.
                     if (!isOpen)
                         onTouch?.();
-                }, ...rest, children: [_jsx("div", { className: "kpt-select__value", children: multiple && selectedOptions.length ? (selectedOptions.map((option) => (_jsxs("span", { className: "kpt-select__chip", children: [option.label, _jsx("button", { type: "button", className: "kpt-select__chip-remove", tabIndex: -1, "aria-label": `${t('select.removeChip')}: ${option.label}`, onClick: (event) => {
+                }, ...rest, children: [_jsx("div", { className: "kpt-select__value", children: multiple && selectedOptions.length ? (selectedOptions.map((option, index) => (_jsxs("span", { className: "kpt-select__chip", children: [option.label, readOnly ? null : (_jsx("button", { type: "button", className: "kpt-select__chip-remove", tabIndex: -1, "aria-label": `${t('select.removeChip')}: ${option.label}`, onClick: (event) => {
                                         event.stopPropagation();
                                         setCurrent(selectedValues.filter((v) => v !== option.value));
-                                    }, children: _jsx(KptIcon, { name: "x" }) })] }, String(option.value))))) : !multiple && filled ? (_jsx("span", { className: "kpt-select__single", children: selectedOptions[0]?.label })) : (_jsx("span", { className: "kpt-select__placeholder", children: placeholder })) }), _jsx(KptIcon, { className: "kpt-select__chevron", name: "chevron-down" })] }), _jsx(KptOverlay, { open: isOpen, anchor: triggerRef.current, onClose: close, minAnchorWidth: true, children: _jsxs("div", { className: "kpt-select__panel", children: [filter ? (_jsxs("div", { className: "kpt-select__search", children: [_jsx(KptIcon, { name: "search" }), _jsx("input", { ref: searchRef, type: "text", className: "kpt-select__search-input", role: "combobox", "aria-autocomplete": "list", "aria-expanded": true, "aria-controls": listId, "aria-activedescendant": activeIndex >= 0 ? optionId(activeIndex) : undefined, "aria-label": t('select.search'), value: filterText, placeholder: t('select.search'), onKeyDown: (event) => onKeyDown(event, 'search'), onChange: (event) => {
+                                    }, children: _jsx(KptIcon, { name: "x" }) }))] }, optionKey(option.value, index))))) : !multiple && filled ? (_jsx("span", { className: "kpt-select__single", children: selectedOptions[0]?.label })) : (_jsx("span", { className: "kpt-select__placeholder", children: placeholder })) }), _jsx(KptIcon, { className: "kpt-select__chevron", name: "chevron-down" })] }), _jsx(KptOverlay, { open: isOpen, anchor: anchor, onClose: close, minAnchorWidth: true, children: _jsxs("div", { className: "kpt-select__panel", children: [filter ? (_jsxs("div", { className: "kpt-select__search", children: [_jsx(KptIcon, { name: "search" }), _jsx("input", { ref: searchRef, type: "text", className: "kpt-select__search-input", role: "combobox", "aria-autocomplete": "list", "aria-expanded": true, "aria-controls": listId, "aria-activedescendant": activeIndex >= 0 ? optionId(activeIndex) : undefined, "aria-label": t('select.search'), value: filterText, placeholder: t('select.search'), onKeyDown: (event) => onKeyDown(event, 'search'), onChange: (event) => {
                                         setFilterText(event.target.value);
                                         // Po zawężeniu aktywna jest pierwsza pasująca opcja — `Enter` wybiera ją od razu.
-                                        const narrowed = filterOptions(event.target.value).map((o) => !!o.disabled);
+                                        const narrowed = filterSelectOptions(options, event.target.value).map((o) => !!o.disabled);
                                         setActiveIndex(nextOptionIndex(narrowed, -1, 'ArrowDown') ?? -1);
-                                    } })] })) : null, _jsx("ul", { className: "kpt-select__list", role: "listbox", id: listId, "aria-multiselectable": multiple, "aria-label": ariaLabel, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, children: filteredOptions.length ? (filteredOptions.map((option, index) => (_jsxs("li", { id: optionId(index), className: cn('kpt-select__option', isSelected(option) && 'kpt-select__option--selected', index === activeIndex && 'kpt-select__option--active', option.disabled && 'kpt-select__option--disabled'), role: "option", "aria-selected": isSelected(option), "aria-disabled": option.disabled || undefined, onMouseDown: (event) => event.preventDefault(), onClick: () => pick(option), onMouseEnter: () => setActiveIndex(index), children: [multiple ? (_jsx("span", { className: cn('kpt-select__check', isSelected(option) && 'is-on'), children: _jsx(KptIcon, { name: "check" }) })) : null, _jsx("span", { className: "kpt-select__option-label", children: option.label }), !multiple && isSelected(option) ? (_jsx(KptIcon, { className: "kpt-select__option-tick", name: "check" })) : null] }, String(option.value))))) : (_jsx("li", { className: "kpt-select__empty", role: "status", children: t('select.noResults') })) })] }) })] }));
+                                    } })] })) : null, _jsx("ul", { className: "kpt-select__list", role: "listbox", id: listId, "aria-multiselectable": multiple, "aria-label": ariaLabel, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, children: filteredOptions.map((option, index) => (_jsxs("li", { id: optionId(index), className: cn('kpt-select__option', isSelected(option) && 'kpt-select__option--selected', index === activeIndex && 'kpt-select__option--active', option.disabled && 'kpt-select__option--disabled'), role: "option", "aria-selected": isSelected(option), "aria-disabled": option.disabled || undefined, onMouseDown: (event) => event.preventDefault(), onClick: () => pick(option), onMouseEnter: () => setActiveIndex(index), children: [multiple ? (_jsx("span", { className: cn('kpt-select__check', isSelected(option) && 'is-on'), children: _jsx(KptIcon, { name: "check" }) })) : null, _jsx("span", { className: "kpt-select__option-label", children: option.label }), !multiple && isSelected(option) ? (_jsx(KptIcon, { className: "kpt-select__option-tick", name: "check" })) : null] }, optionKey(option.value, index)))) }), filteredOptions.length === 0 ? (_jsx("div", { className: "kpt-select__empty", role: "status", children: t('select.noResults') })) : null] }) })] }));
 }

package/dist/shared/types.d.ts

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

package/dist/shared/types.js

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

package/dist/sidenav/sidenav.d.ts

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

package/dist/sidenav/sidenav.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, isValidElement } from 'react';
+import { isValidElement } from 'react';
 import { cn } from "../internal/cn.js";
+import { slotChildren } from "../internal/slot-children.js";
 /*
  * Panel odtwarza projekcję z Angulara: treść domyślna ląduje w obszarze przewijanym,
  * a `<KptSidenav.Footer>` jest wynoszona POZA ten obszar. Dzięki temu stopka zostaje
@@ -20,14 +21,14 @@ import { cn } from "../internal/cn.js";
 export function KptSidenav({ className, children, ...rest }) {
     const scroll = [];
     const footers = [];
-    Children.forEach(children, (child) => {
+    for (const child of slotChildren(children)) {
         if (isValidElement(child) && child.type?.kptSidenavSlot === 'footer') {
             footers.push(child);
         }
         else {
             scroll.push(child);
         }
-    });
+    }
     return (_jsxs("div", { className: cn('kpt-sidenav', className), ...rest, children: [_jsx("div", { className: "kpt-sidenav__scroll", children: scroll }), footers] }));
 }
 /**