@konce-pt/react 0.17.0 → 0.18.1

package/dist/charts/chart.js

@@ -1,12 +1,35 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useId, useRef, useState } from 'react';
-import { KptChartMotion, areaPath, bandScale, barLayout, chartAccessibleName, chartDataTable, dataScale, deltaKind, domainScale, extent, formatNumber, holdDomain, linePath, linearScale, niceScale, pieSlices, plotArea, polarSlices, polarToCartesian, polygonPath, radarGrid, radarPoints, radialArea, sameChartShape, seriesColor, significantDelta, } from '@konce-pt/chart';
+import { KptChartMotion, areaPath, axisBase, axisLabelIndices, bandPath, bandScale, barLayout, chartScale, chartAccessibleName, chartDataTable, clampLabel, dataScale, deltaKind, domainScale, estimateLabelWidth, formatNumber, linePath, linearScale, pieSlices, plotArea, polarSlices, polarToCartesian, polygonPath, radarGrid, radarPoints, radialArea, sameChartShape, scaleRows, seriesColor, significantDelta, stackSeries, } from '@konce-pt/chart';
 import { cn } from "../internal/cn.js";
 import { useKptMotion } from "../motion/motion-context.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptChartLegend } from "./chart-legend.js";
 import { KptChartTooltip } from "./chart-tooltip.js";
+/** Wysokość linii etykiety kategorii na osi pionowej (słupki poziome) - jednostki viewBoxa. */
+const CATEGORY_LINE = 12;
+/**
+ * Etykiety osi poziomej: wszystkie, jeśli się mieszczą, inaczej równy podział 9/5/3/2
+ * (`axisLabelIndices`). Pełna nazwa każdej kategorii zostaje w pigułce prowadnicy i w dymku.
+ */
+function bottomLabels(labels, centers, y, width) {
+    const sizes = labels.map((l) => estimateLabelWidth(l));
+    const shown = new Set(axisLabelIndices(centers, sizes));
+    return labels.map((text, i) => ({
+        at: centers[i] ?? 0,
+        x: clampLabel(centers[i] ?? 0, sizes[i] ?? 0, 0, width),
+        y,
+        text,
+        anchor: 'middle',
+        visible: shown.has(i),
+    }));
+}
+/** Etykiety osi pionowej (słupki poziome): ten sam podział, rozmiarem jest wysokość linii. */
+function sideLabels(labels, centers, x) {
+    const shown = new Set(axisLabelIndices(centers, centers.map(() => CATEGORY_LINE), 2));
+    return labels.map((text, i) => ({ at: centers[i] ?? 0, x, y: (centers[i] ?? 0) + 3, text, anchor: 'end', visible: shown.has(i) }));
+}
 const VERTICAL_INSETS = { top: 12, right: 16, bottom: 28, left: 46 };
 const HORIZONTAL_INSETS = { top: 12, right: 16, bottom: 28, left: 76 };
 /** Szerokość pasma smugi światła (jednostki viewBoxa) - połowa po każdej stronie czoła fali. */
@@ -106,8 +129,11 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
         const to = config.series.map((s) => [...s.data]);
         const withAxis = config.type === 'line' || config.type === 'bar';
         const visible = (rows) => rows.filter((_, i) => !hidden.has(`ser:${config.series[i]?.name ?? ''}`));
+        const axis = { valueAxis: config.valueAxis, stacked: config.stacked };
+        // Skala trzymana na czas ducha obejmuje oba stany - z wierszy już złożonych w stos.
+        const held = [...scaleRows(visible(from), config.stacked), ...scaleRows(visible(to), config.stacked)];
         const scales = withAxis
-            ? { start: dataScale(visible(from)), hold: dataScale([holdDomain(visible(from), visible(to))]), end: dataScale(visible(to)) }
+            ? { start: dataScale(visible(from), axis), hold: chartScale(held, { valueAxis: config.valueAxis }), end: dataScale(visible(to), axis) }
             : null;
         motion.transition(from, to, { delta: withAxis && config.animation?.delta !== false, scales });
     }, [config, hidden, motion, motionConfig]);
@@ -204,16 +230,19 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
         if (view.type !== 'line')
             return null;
         const active = view.series.map((s, i) => ({ s, i })).filter(({ s }) => !hidden.has(`ser:${s.name}`));
-        const values = active.flatMap(({ s }) => s.data);
-        const [mn, mx] = extent(values.length ? values : [0]);
+        const rows = active.map(({ s }) => s.data);
         const scale = frame.domain
             ? domainScale(frame.domain.target, frame.domain.min, frame.domain.max)
-            : niceScale(Math.min(0, mn), Math.max(0, mx), 5);
+            : chartScale(rows, { valueAxis: view.valueAxis, stacked: view.stacked });
+        // Stos: punkty serii na narastającej sumie, pasmo od linii serii pod nią.
+        const stack = view.stacked ? stackSeries(rows) : null;
         const plot = plotArea(width, height, VERTICAL_INSETS);
         const yScale = linearScale(scale.min, scale.max, plot.y + plot.height, plot.y);
         const count = view.labels.length;
         const xAt = (i) => count > 1 ? plot.x + (i / (count - 1)) * plot.width : plot.x + plot.width / 2;
-        const baseline = yScale(0);
+        // Punkt nie wychodzi poza oś - przypięte `valueAxis.min`/`max` mogą uciąć wartość.
+        const yAt = (v) => yScale(Math.min(scale.max, Math.max(scale.min, v)));
+        const baseline = yScale(axisBase(scale));
         const interpolation = view.interpolation ?? 'linear';
         const showPoints = view.points ?? true;
         const grid = scale.ticks.map((t) => ({
@@ -228,29 +257,35 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
             text: formatNumber(t),
             anchor: 'end',
         }));
-        const catLabels = view.labels.map((label, i) => ({
-            x: xAt(i),
-            y: plot.y + plot.height + 18,
-            text: label,
-            anchor: 'middle',
-        }));
-        const series = active.map(({ s, i }) => ({
+        const catLabels = bottomLabels(view.labels, view.labels.map((_, i) => xAt(i)), plot.y + plot.height + 18, width);
+        const catTicks = view.labels.map((_, i) => ({ x: xAt(i), y: plot.y + plot.height }));
+        const series = active.map(({ s, i }, k) => ({
             key: `ser:${s.name}`,
             name: s.name,
             color: seriesColor(s.color, i),
             i,
-            points: s.data.map((v, idx) => ({ x: xAt(idx), y: yScale(v), value: v, label: view.labels[idx] ?? '' })),
+            points: s.data.map((v, idx) => ({ x: xAt(idx), y: yAt(stack?.top[k]?.[idx] ?? v), value: v, label: view.labels[idx] ?? '' })),
+            floor: stack ? s.data.map((_, idx) => ({ x: xAt(idx), y: yAt(stack.base[k]?.[idx] ?? 0) })) : null,
         }));
+        // Duch w stosie stoi na sumach poprzedniego stanu, tak jak bieżące punkty.
+        const ghostRows = ghostState
+            ? (() => {
+                const prev = active.map(({ i }) => ghostState.prev[i] ?? []);
+                return view.stacked ? stackSeries(prev).top : prev;
+            })()
+            : [];
         const crosshairCat = config.crosshair && activeIndex !== null ? catLabels[activeIndex] : undefined;
         // Prowadnica i pigułka jadą razem z dymkiem.
-        const crossX = crosshairCat ? (frame.tip?.x ?? crosshairCat.x) : 0;
+        const crossX = crosshairCat ? (frame.tip?.x ?? crosshairCat.at) : 0;
         const pillWidth = crosshairCat ? Math.max(28, crosshairCat.text.length * 7 + 16) : 0;
+        // Pigułka przy skrajnej kategorii przesuwa się do środka zamiast wyjść poza viewBox.
+        const pillX = crosshairCat ? clampLabel(crossX, pillWidth, 0, width) : 0;
         /** Najbliższa kategoria w całym obszarze wykresu: wiersze wszystkich serii, dymek nad najwyższym punktem. */
         const onMove = (event) => {
             const p = svgPoint(event);
             if (!p || !series.length)
                 return;
-            const idx = nearestIndex(catLabels.map((l) => l.x), p.x);
+            const idx = nearestIndex(catLabels.map((l) => l.at), p.x);
             if (keepTip(idx))
                 return;
             const hits = series.map((s) => ({ s, pt: s.points[idx] })).filter((e) => !!e.pt);
@@ -264,14 +299,14 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
             if (moved && tipMotion())
                 setRipple({ id: ++rippleId.current, x: top.pt.x, y: top.pt.y, color: top.s.color });
         };
-        return (_jsxs(_Fragment, { children: [_jsx("g", { className: "kpt-chart__grid", children: grid.map((g, i) => (_jsx("line", { className: "kpt-chart__gridline", x1: g.x1, y1: g.y1, x2: g.x2, y2: g.y2 }, i))) }), crosshairCat ? (_jsx("line", { className: "kpt-chart__crosshair", x1: crossX, y1: plot.y, x2: crossX, y2: plot.y + plot.height })) : null, _jsx("g", { className: "kpt-chart__axis", children: [...valueLabels, ...catLabels].map((l, i) => (_jsx("text", { x: l.x, y: l.y, textAnchor: l.anchor, children: l.text }, i))) }), crosshairCat ? (_jsxs("g", { className: "kpt-chart__cat-active", children: [_jsx("rect", { x: crossX - pillWidth / 2, y: crosshairCat.y - 13, width: pillWidth, height: 18, rx: 9 }), _jsx("text", { x: crossX, y: crosshairCat.y, textAnchor: "middle", children: crosshairCat.text })] })) : null, ghostState
+        return (_jsxs(_Fragment, { children: [_jsx("g", { className: "kpt-chart__grid", children: grid.map((g, i) => (_jsx("line", { className: "kpt-chart__gridline", x1: g.x1, y1: g.y1, x2: g.x2, y2: g.y2 }, i))) }), crosshairCat ? (_jsx("line", { className: "kpt-chart__crosshair", x1: crossX, y1: plot.y, x2: crossX, y2: plot.y + plot.height })) : null, _jsx("g", { className: "kpt-chart__axis", children: [...valueLabels, ...catLabels.filter((l) => l.visible)].map((l, i) => (_jsx("text", { x: l.x, y: l.y, textAnchor: l.anchor, children: l.text }, i))) }), _jsx("g", { className: "kpt-chart__cat-ticks", "aria-hidden": "true", children: catTicks.map((tk, i) => (_jsx("circle", { className: cn('kpt-chart__cat-tick', activeIndex === i && 'kpt-chart__cat-tick--active'), r: 2, cx: tk.x, cy: tk.y }, i))) }), crosshairCat ? (_jsxs("g", { className: "kpt-chart__cat-active", children: [_jsx("rect", { x: pillX - pillWidth / 2, y: crosshairCat.y - 13, width: pillWidth, height: 18, rx: 9 }), _jsx("text", { x: pillX, y: crosshairCat.y, textAnchor: "middle", children: crosshairCat.text })] })) : null, ghostState
                     ? series.map((s) => {
                         const prev = ghostState.prev[s.i] ?? [];
                         const next = ghostState.next[s.i] ?? [];
-                        const gpts = prev.map((v, idx) => ({ x: xAt(idx), y: yScale(v) }));
+                        const gpts = (ghostRows[series.indexOf(s)] ?? prev).map((v, idx) => ({ x: xAt(idx), y: yAt(v) }));
                         return (_jsxs("g", { className: "kpt-chart__ghost", "aria-hidden": "true", children: [_jsx("path", { className: "kpt-chart__ghost-line", d: linePath(gpts, interpolation) }), gpts.map((p, idx) => (_jsx("line", { className: "kpt-chart__delta", "data-kind": deltaKind(prev[idx] ?? 0, next[idx] ?? 0), x1: p.x, x2: p.x, y1: p.y, y2: s.points[idx]?.y ?? p.y }, idx)))] }, `${ghostState.id}:${s.key}`));
                     })
-                    : null, series.map((s) => (_jsxs("g", { className: cn('kpt-chart__series', dim(s.key) && 'kpt-chart__series--dim'), children: [view.area ? (_jsx("path", { className: "kpt-chart__area", d: areaPath(s.points, baseline, interpolation), style: { fill: s.color } })) : null, _jsx("path", { className: "kpt-chart__line", d: linePath(s.points, interpolation), style: { stroke: s.color }, pathLength: 1 }), showPoints
+                    : null, series.map((s) => (_jsxs("g", { className: cn('kpt-chart__series', dim(s.key) && 'kpt-chart__series--dim'), children: [view.area ? (_jsx("path", { className: "kpt-chart__area", d: s.floor ? bandPath(s.points, s.floor, interpolation) : areaPath(s.points, baseline, interpolation), style: { fill: s.color } })) : null, _jsx("path", { className: "kpt-chart__line", d: linePath(s.points, interpolation), style: { stroke: s.color }, pathLength: 1 }), showPoints
                             ? s.points.map((p, idx) => (_jsx("circle", { className: cn('kpt-chart__point', activeIndex === idx && 'kpt-chart__point--active'), cx: p.x, cy: p.y, r: 4, style: { fill: s.color, ['--kpt-chart-i']: idx } }, idx)))
                             : null] }, s.key))), sheen
                     ? series.map((s) => (_jsx("path", { className: "kpt-chart__sheen-line", d: linePath(s.points, interpolation), stroke: `url(#${sheenId})`, style: { opacity: sheen.opacity }, "aria-hidden": "true" }, s.key)))
@@ -301,7 +336,7 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
         const active = view.series.map((s, i) => ({ s, i })).filter(({ s }) => !hidden.has(`ser:${s.name}`));
         const plot = plotArea(width, height, vertical ? VERTICAL_INSETS : HORIZONTAL_INSETS);
         const radius = view.borderRadius ?? 4;
-        const layout = barLayout(active.map(({ s }) => s.data), view.labels.length, plot, orientation, radius, frame.domain ? domainScale(frame.domain.target, frame.domain.min, frame.domain.max) : undefined);
+        const layout = barLayout(active.map(({ s }) => s.data), view.labels.length, plot, orientation, radius, frame.domain ? domainScale(frame.domain.target, frame.domain.min, frame.domain.max) : undefined, { stacked: view.stacked, valueAxis: view.valueAxis });
         const colors = active.map(({ s, i }) => seriesColor(s.color, i));
         const names = active.map(({ s }) => s.name);
         const cat = vertical
@@ -318,9 +353,10 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
                 text: formatNumber(t.value),
                 anchor: 'middle',
             }));
+        const centers = view.labels.map((_, i) => cat.center(i));
         const catLabels = vertical
-            ? view.labels.map((l, i) => ({ x: cat.center(i), y: plot.y + plot.height + 18, text: l, anchor: 'middle' }))
-            : view.labels.map((l, i) => ({ x: plot.x - 8, y: cat.center(i) + 3, text: l, anchor: 'end' }));
+            ? bottomLabels(view.labels, centers, plot.y + plot.height + 18, width)
+            : sideLabels(view.labels, centers, plot.x - 8);
         const bars = layout.bars.map((b, order) => ({
             b,
             order,
@@ -335,7 +371,7 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
             ? (() => {
                 const prevRows = active.map(({ i }) => ghostState.prev[i] ?? []);
                 const nextRows = active.map(({ i }) => ghostState.next[i] ?? []);
-                return barLayout(prevRows, view.labels.length, plot, orientation, radius, layout.scale).bars.map((g, k) => {
+                return barLayout(prevRows, view.labels.length, plot, orientation, radius, layout.scale, { stacked: view.stacked }).bars.map((g, k) => {
                     const cur = layout.bars[k] ?? g;
                     const a = barEnd(g, vertical);
                     const z = barEnd(cur, vertical);
@@ -357,7 +393,7 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
             const p = svgPoint(event);
             if (!p)
                 return;
-            const idx = nearestIndex(catLabels.map((l) => (vertical ? l.x : l.y - 3)), vertical ? p.x : p.y);
+            const idx = nearestIndex(catLabels.map((l) => l.at), vertical ? p.x : p.y);
             if (keepTip(idx))
                 return;
             const group = bars.filter((e) => e.b.categoryIndex === idx);
@@ -365,11 +401,11 @@ export function KptChart({ config, width = 600, height = 360, locale, dictionary
             if (!group.length || !center)
                 return;
             const label = config.labels[idx] ?? '';
-            const x = vertical ? center.x : Math.max(...group.map((e) => e.tipX));
-            const y = vertical ? Math.min(...group.map((e) => e.tipY)) : center.y - 3;
+            const x = vertical ? center.at : Math.max(...group.map((e) => e.tipX));
+            const y = vertical ? Math.min(...group.map((e) => e.tipY)) : center.at;
             openTip(x, y, label, group.map((e) => row(e.name, label, e.b.value, e.color)), idx);
         };
-        return (_jsxs(_Fragment, { children: [_jsx("g", { className: "kpt-chart__grid", children: grid.map((g, i) => (_jsx("line", { className: "kpt-chart__gridline", x1: g.x1, y1: g.y1, x2: g.x2, y2: g.y2 }, i))) }), _jsx("g", { className: "kpt-chart__axis", children: [...valueLabels, ...catLabels].map((l, i) => (_jsx("text", { x: l.x, y: l.y, textAnchor: l.anchor, children: l.text }, i))) }), ghostBars.length ? (_jsx("g", { className: "kpt-chart__ghost", "aria-hidden": "true", children: ghostBars.map((g) => (_jsx("path", { className: "kpt-chart__ghost-bar", d: g.path }, g.key))) })) : null, _jsx("g", { className: "kpt-chart__bars", "data-orientation": orientation, children: bars.map((e) => (_jsx("path", { className: cn('kpt-chart__bar', dim(e.key) && 'kpt-chart__series--dim'), d: e.b.path, style: { fill: e.color, ['--kpt-chart-i']: e.order } }, `${e.key}#${e.order}`))) }), ghostBars.length ? (_jsx("g", { className: "kpt-chart__ghost", "aria-hidden": "true", children: ghostBars.map((g) => (_jsx("rect", { className: "kpt-chart__delta-bar", "data-kind": g.kind, rx: 2, ...g.delta }, g.key))) })) : null, sheen
+        return (_jsxs(_Fragment, { children: [_jsx("g", { className: "kpt-chart__grid", children: grid.map((g, i) => (_jsx("line", { className: "kpt-chart__gridline", x1: g.x1, y1: g.y1, x2: g.x2, y2: g.y2 }, i))) }), _jsx("g", { className: "kpt-chart__axis", children: [...valueLabels, ...catLabels.filter((l) => l.visible)].map((l, i) => (_jsx("text", { x: l.x, y: l.y, textAnchor: l.anchor, children: l.text }, i))) }), ghostBars.length ? (_jsx("g", { className: "kpt-chart__ghost", "aria-hidden": "true", children: ghostBars.map((g) => (_jsx("path", { className: "kpt-chart__ghost-bar", d: g.path }, g.key))) })) : null, _jsx("g", { className: "kpt-chart__bars", "data-orientation": orientation, children: bars.map((e) => (_jsx("path", { className: cn('kpt-chart__bar', dim(e.key) && 'kpt-chart__series--dim'), d: e.b.path, style: { fill: e.color, ['--kpt-chart-i']: e.order } }, `${e.key}#${e.order}`))) }), ghostBars.length ? (_jsx("g", { className: "kpt-chart__ghost", "aria-hidden": "true", children: ghostBars.map((g) => (_jsx("rect", { className: "kpt-chart__delta-bar", "data-kind": g.kind, rx: 2, ...g.delta }, g.key))) })) : null, sheen
                     ? bars.map((e) => (_jsx("path", { className: "kpt-chart__sheen-bar", d: e.b.path, fill: `url(#${sheenId})`, style: { opacity: sheen.opacity * 0.7 }, "aria-hidden": "true" }, `${e.key}#${e.order}`)))
                     : null, _jsx("rect", { className: "kpt-chart__hover", x: plot.x, y: plot.y, width: plot.width, height: plot.height, onPointerMove: onMove, onPointerLeave: hideTip })] }));
     })();

package/dist/charts/llms.txt

@@ -19,9 +19,29 @@ proportionally (`width={300} height={180}`) instead of letting a 600-unit chart
 
 ## The config is the API
 `{ type, labels, series, points?, area?, interpolation?, orientation?, borderRadius?, innerRadius?,
-crosshair?, tooltip?, legend?, title?, subtitle?, animation?, ariaLabel?, description? }` - the same shape the Angular port
+valueAxis?, stacked?, crosshair?, tooltip?, legend?, title?, subtitle?, animation?, ariaLabel?, description? }` - the same shape the Angular port
 takes, because both read it from `@konce-pt/chart`.
 
+## Value axis and stacking (line, bar)
+- `valueAxis?: { zero?, min?, max? }` - the value axis starts at zero by default, so a bar and the area under a line
+  show the size directly. `zero: false` fits the axis to the data (a weight of 79-90 kg is no longer a flat line under
+  the ceiling); `min` / `max` pin an end of the axis exactly and win over `zero` - a value beyond a pinned end is
+  cut at the edge. Bars and areas grow from zero, or from the end of the axis nearer to it
+- `stacked?: boolean` - stacked series: bars on top of each other in one band per category (positive values up,
+  negative down; only the outer segment is rounded), lines as running totals with a band under each one (with
+  `area`). The axis covers the totals; the tooltip shows the values of the series, not the totals
+- The rules live in `@konce-pt/chart`: `axisScale`, `chartScale`, `stackSeries`, `bandPath` (tested)
+
+## Category axis (line, bar)
+- When the category labels do not fit, the axis shows an even subset instead of overlapping text: all of
+  them if they fit, otherwise the densest split that fits - 9 labels (eighths of the axis), 5 (first, 1/4,
+  middle, 3/4, last), 3, and finally the two ends only. Horizontal bars apply the same rule to the rows
+- The choice is made in viewBox units, so it follows `width`, not the on-screen size; the outer labels and the
+  crosshair pill are shifted inward so they never leave the chart
+- A line chart marks every category with a small dot on the axis; the active one grows on hover. The full
+  name of any category stays in the crosshair pill and the tooltip
+- The rules live in `@konce-pt/chart`: `axisLabelIndices`, `estimateLabelWidth`, `clampLabel` (tested)
+
 ## The geometry lives in a package
 Scales, paths, bar layout and arcs come from `@konce-pt/chart` - pure functions with `node --test`
 coverage, shared with the Angular port. The component only turns them into SVG elements; there is

package/dist/charts-entry/public-api.d.ts

@@ -1,4 +1,4 @@
 export { KptChart } from '../charts/chart.tsx';
 export type { KptChartProps } from '../charts/chart.tsx';
-export type { KptChartConfig, KptChartSeries, KptChartType, KptLineInterpolation, KptBarOrientation, KptLegendOptions, KptLegendPosition, KptLegendTitle, KptAlign, KptPointStyle, KptTitleOptions, KptTooltipOptions, KptTooltipContext, KptAnimationOptions, KptFont, KptPadding, } from '@konce-pt/chart';
+export type { KptChartConfig, KptChartSeries, KptChartType, KptLineInterpolation, KptBarOrientation, KptLegendOptions, KptLegendPosition, KptLegendTitle, KptAlign, KptPointStyle, KptTitleOptions, KptTooltipOptions, KptTooltipContext, KptAnimationOptions, KptValueAxisOptions, KptFont, KptPadding, } from '@konce-pt/chart';
 export { KPT_CHART_PALETTE, seriesColor, linePath, areaPath, pieSlices, polarSlices, barLayout, radarGrid, radarPoints, niceScale, } from '@konce-pt/chart';

package/dist/data-table/data-table.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type KptColumnGroup } from '@konce-pt/table';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import { type KptSpeechColor } from '../speech/speech-button.tsx';
 import type { KptCellEditEvent, KptCellEditRenderers, KptCellRenderers, KptColumn, KptTableLazyState } from './data-table-types.ts';
@@ -45,6 +46,12 @@ export interface KptDataTableProps<T> extends Omit<ComponentPropsWithRef<'div'>,
     /** Szerokość kolumny bez liczalnego `width` w trybie `virtualScroll` (`px`/`rem`/`em`). */
     columnWidth?: string;
     rowHeight?: number;
+    /**
+     * Nagłówki grupowane: wiersz nad etykietami, w którym sąsiednie kolumny grupy dzielą komórkę
+     * (`[{ header: 'Makroskładniki', fields: ['carbs', 'protein', 'fat'] }]`). Liczony z kolumn
+     * widocznych, w bieżącej kolejności - ukryta albo przestawiona kolumna wypada z grupy sama.
+     */
+    columnGroups?: readonly KptColumnGroup[];
     reorderable?: boolean;
     /**
      * Przykleja kolumny systemowe (rozwijanie, zaznaczanie) do lewej krawędzi także bez kolumn `frozen`.
@@ -83,4 +90,4 @@ export interface KptDataTableProps<T> extends Omit<ComponentPropsWithRef<'div'>,
     /** Treść po lewej stronie paginatora (odpowiednik slotu `[kptPaginatorActions]`). */
     paginatorActions?: ReactNode;
 }
-export declare function KptDataTable<T = Record<string, unknown>>({ columns, data, filterable, filterSpeech, filterSpeechLang, filterSpeechColor, filterRowPosition, pageSize, pageSizeOptions, selectable, loading, ariaLabel, caption, clickableRows, emptyMessage, rowKey, scrollHeight, virtualScroll, columnWidth, rowHeight, reorderable, frozenSystemColumns, exportable, exportFilename, lazy, totalRecords, expandable, multiExpand, summaryLabel, summaryValues, selection, defaultSelection, onSelectionChange, expandedRows, defaultExpandedRows, onExpandedRowsChange, hiddenFields, defaultHiddenFields, onHiddenFieldsChange, onRowClick, onLazyLoad, onCellEdit, cells, cellEditors, renderRowDetail, paginatorActions, locale, dictionary, className, style, ...rest }: Readonly<KptDataTableProps<T>>): import("react").JSX.Element;
+export declare function KptDataTable<T = Record<string, unknown>>({ columns, data, filterable, filterSpeech, filterSpeechLang, filterSpeechColor, filterRowPosition, pageSize, pageSizeOptions, selectable, loading, ariaLabel, caption, clickableRows, emptyMessage, rowKey, scrollHeight, virtualScroll, columnWidth, rowHeight, reorderable, columnGroups, frozenSystemColumns, exportable, exportFilename, lazy, totalRecords, expandable, multiExpand, summaryLabel, summaryValues, selection, defaultSelection, onSelectionChange, expandedRows, defaultExpandedRows, onExpandedRowsChange, hiddenFields, defaultHiddenFields, onHiddenFieldsChange, onRowClick, onLazyLoad, onCellEdit, cells, cellEditors, renderRowDetail, paginatorActions, locale, dictionary, className, style, ...rest }: Readonly<KptDataTableProps<T>>): import("react").JSX.Element;

package/dist/data-table/data-table.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { aggregate, columnOffsets, createGlobalFilter, cssLengthToPx, isEmptyFilterValue, matchesColumnFilter, sortRows, toText, virtualColumnRange, virtualRange, } from '@konce-pt/table';
+import { aggregate, columnOffsets, createGlobalFilter, cssLengthToPx, groupHeaderCells, isEmptyFilterValue, matchesColumnFilter, sortRows, toText, virtualColumnRange, virtualRange, } from '@konce-pt/table';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
@@ -82,7 +82,7 @@ const EMPTY_FIELDS = [];
 function getValue(row, field) {
     return row[field];
 }
-export function KptDataTable({ columns, data = EMPTY_ROWS, filterable = false, filterSpeech = false, filterSpeechLang, filterSpeechColor, filterRowPosition = 'bottom', pageSize = 0, pageSizeOptions = [5, 10, 20, 50], selectable = 'none', loading = false, ariaLabel = null, caption = null, clickableRows, emptyMessage, rowKey = null, scrollHeight = null, virtualScroll = false, columnWidth = '10rem', rowHeight = 41, reorderable = false, frozenSystemColumns = false, exportable = false, exportFilename = 'export.csv', lazy = false, totalRecords = null, expandable = false, multiExpand = true, summaryLabel, summaryValues = null, selection, defaultSelection = EMPTY_ROWS, onSelectionChange, expandedRows, defaultExpandedRows = EMPTY_ROWS, onExpandedRowsChange, hiddenFields, defaultHiddenFields = EMPTY_FIELDS, onHiddenFieldsChange, onRowClick, onLazyLoad, onCellEdit, cells, cellEditors, renderRowDetail, paginatorActions, locale, dictionary, className, style, ...rest }) {
+export function KptDataTable({ columns, data = EMPTY_ROWS, filterable = false, filterSpeech = false, filterSpeechLang, filterSpeechColor, filterRowPosition = 'bottom', pageSize = 0, pageSizeOptions = [5, 10, 20, 50], selectable = 'none', loading = false, ariaLabel = null, caption = null, clickableRows, emptyMessage, rowKey = null, scrollHeight = null, virtualScroll = false, columnWidth = '10rem', rowHeight = 41, reorderable = false, columnGroups, frozenSystemColumns = false, exportable = false, exportFilename = 'export.csv', lazy = false, totalRecords = null, expandable = false, multiExpand = true, summaryLabel, summaryValues = null, selection, defaultSelection = EMPTY_ROWS, onSelectionChange, expandedRows, defaultExpandedRows = EMPTY_ROWS, onExpandedRowsChange, hiddenFields, defaultHiddenFields = EMPTY_FIELDS, onHiddenFieldsChange, onRowClick, onLazyLoad, onCellEdit, cells, cellEditors, renderRowDetail, paginatorActions, locale, dictionary, className, style, ...rest }) {
     const { t, locale: activeLocale } = useKptMessages({ locale, dictionary });
     const uid = useId();
     const rowsClickable = clickableRows ?? onRowClick !== undefined;
@@ -149,6 +149,8 @@ export function KptDataTable({ columns, data = EMPTY_ROWS, filterable = false, f
     const [viewport, setViewport] = useState({ height: 400, width: 1200 });
     const scrollFrame = useRef(0);
     const [theadOffset, setTheadOffset] = useState(0);
+    /** Offset sticky trzeciego wiersza nagłówka (grupy + etykiety + filtry). */
+    const [theadOffset2, setTheadOffset2] = useState(0);
     const scrollRef = useRef(null);
     const theadRef = useRef(null);
     const editorHostRef = useRef(null);
@@ -234,14 +236,17 @@ export function KptDataTable({ columns, data = EMPTY_ROWS, filterable = false, f
             return;
         requestLazyLoad({ pageIndex, pageSize: pageSizeState, sortField, sortDir, filter: filterText, columnFilters });
     }, [lazy, pageIndex, pageSizeState, sortField, sortDir, filterText, columnFilters]);
-    // Offset sticky drugiego wiersza nagłówka = wysokość pierwszego.
+    // Offsety sticky drugiego i trzeciego wiersza nagłówka = wysokość jednego i dwóch pierwszych.
     useLayoutEffect(() => {
-        const first = theadRef.current?.rows?.[0];
+        const rows = theadRef.current?.rows;
         // Dokładna wysokość, nie `offsetHeight`: ten zaokrągla (46,5 -> 47) i przy skali ekranu innej
         // niż 100% między wierszami nagłówka zostawała szpara, przez którą prześwitywały wiersze.
-        if (first)
-            setTheadOffset(first.getBoundingClientRect().height);
-    }, [filterRowPosition, hasColumnFilters, visibleColumns]);
+        const h1 = rows?.[0]?.getBoundingClientRect().height ?? 0;
+        const h2 = rows?.[1]?.getBoundingClientRect().height ?? 0;
+        if (rows?.[0])
+            setTheadOffset(h1);
+        setTheadOffset2(h1 + h2);
+    }, [filterRowPosition, hasColumnFilters, visibleColumns, columnGroups]);
     // Rozmiar viewportu dla wirtualizacji - także po zmianie rozmiaru kontenera bez przewinięcia.
     useLayoutEffect(() => {
         const el = scrollRef.current;
@@ -400,8 +405,22 @@ export function KptDataTable({ columns, data = EMPTY_ROWS, filterable = false, f
     const tableWidth = virtualScroll
         ? scrollable.pinnedWidth + scrollable.offsets[scrollable.offsets.length - 1]
         : undefined;
-    /** Liczba wierszy nagłówka (etykiety + ewentualnie filtry) - przesunięcie `aria-rowindex`. */
-    const headerRowCount = hasColumnFilters ? 2 : 1;
+    /**
+     * Wiersz grup nad etykietami: komórki nad pozycjami `slots`. Komórka przykleja się do lewej, gdy
+     * wszystkie jej kolumny są zamrożone - inaczej przewija się z nimi. Pusta lista = bez wiersza.
+     */
+    const groupCells = columnGroups?.length
+        ? groupHeaderCells(slots.map((s) => s.meta?.col.field ?? null), columnGroups).map((cell) => {
+            const metas = slots.slice(cell.start, cell.start + cell.span).map((s) => s.meta);
+            const spacer = metas.some((m) => m === null);
+            const frozen = !spacer && metas.every((m) => m?.frozen);
+            return { ...cell, key: slots[cell.start]?.key ?? String(cell.start), spacer, frozen, left: frozen ? (metas[0]?.left ?? undefined) : undefined };
+        })
+        : [];
+    /** Wiersz grup jest pierwszym wierszem nagłówka - przesuwa `aria-rowindex` pozostałych. */
+    const groupRows = groupCells.length ? 1 : 0;
+    /** Liczba wierszy nagłówka (grupy, etykiety, ewentualnie filtry) - przesunięcie `aria-rowindex`. */
+    const headerRowCount = groupRows + (hasColumnFilters ? 2 : 1);
     /** `aria-colindex` komórki kolumny (od 1, z kolumnami systemowymi) - tylko w trybie wirtualnym. */
     const colIndex = (meta) => virtualScroll ? leadingCells + meta.index + 1 : undefined;
     // -- Przestawianie kolumn --
@@ -671,7 +690,7 @@ export function KptDataTable({ columns, data = EMPTY_ROWS, filterable = false, f
                 return null;
         }
     };
-    const filterRowIndex = filterRowPosition === 'top' ? 1 : 2;
+    const filterRowIndex = groupRows + (filterRowPosition === 'top' ? 1 : 2);
     const filterRow = (_jsxs("tr", { className: "kpt-data-table__filter-row", "aria-rowindex": virtualScroll ? filterRowIndex : undefined, children: [hasRowDetail ? (_jsx("th", { className: cn('kpt-data-table__expander', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: expanderStickyLeft } })) : null, selectable !== 'none' ? (_jsx("th", { className: cn('kpt-data-table__checkbox', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: checkboxStickyLeft } })) : null, slots.map((slot) => slot.meta ? (_jsx("th", { style: { width: virtualScroll ? undefined : slot.meta.col.width, left: slot.meta.left }, "data-align": slot.meta.align, "aria-colindex": colIndex(slot.meta), className: cn(slot.meta.frozen && 'kpt-data-table__cell--frozen'), children: filterCell(slot.meta.col) }, slot.key)) : (hspacer(slot)))] }));
     const editor = (row, col) => {
         const custom = cellEditors?.[col.field];
@@ -743,7 +762,7 @@ export function KptDataTable({ columns, data = EMPTY_ROWS, filterable = false, f
                                     startEdit(row, col, event);
                             }, children: editing ? (_jsx("div", { ref: editorHostRef, className: "kpt-data-table__editor", onClick: (event) => event.stopPropagation(), onBlur: onEditorFocusOut, children: editor(row, col) })) : cells?.[col.field] ? (cells[col.field](row, getValue(row, col.field))) : getValue(row, col.field) }, slot.key));
                     })] }), hasRowDetail && isExpanded(row) && !virtualScroll ? (_jsx("tr", { className: "kpt-data-table__detail-row", children: _jsx("td", { className: "kpt-data-table__detail", colSpan: colspan, children: renderRowDetail?.(row) }) })) : null] }, rowKey ? String(getValue(row, rowKey)) : index));
-    return (_jsxs("div", { className: cn('kpt-data-table', className), style: { ['--kpt-thead-offset']: `${theadOffset}px`, ...style }, ...rest, children: [filterable || exportable ? (_jsxs("div", { className: "kpt-data-table__toolbar", children: [filterable ? (_jsxs("div", { className: "kpt-data-table__search", "data-speech": filterSpeechState, children: [_jsx("input", { ref: filterRef, className: "kpt-data-table__filter", type: "search", placeholder: t('dataTable.search'), "aria-label": t('dataTable.search'), value: filterInput, onChange: (event) => onFilterInput(event.target.value) }), filterSpeech ? (_jsx(KptSpeechButton, { listeningColor: filterSpeechColor, speech: filterMic, size: "sm", unsupported: "hide", hostProps: { className: 'kpt-data-table__speech' } })) : null] })) : null, exportable ? (_jsx(KptButton, { variant: "outline", size: "sm", onClick: () => exportTableCsv(visibleColumns, (lazy ? data : sorted), exportFilename), children: t('dataTable.exportCsv') })) : null] })) : null, _jsx("div", { ref: scrollRef, className: "kpt-data-table__scroll", style: { maxHeight: scrollHeight ?? undefined }, onScroll: onScroll, children: _jsxs("table", { className: cn('kpt-data-table__table', hasFrozen && 'kpt-data-table__table--frozen', virtualScroll && 'kpt-data-table__table--virtual'), style: { width: tableWidth }, "aria-label": ariaLabel ?? undefined, "aria-busy": loading || undefined, "aria-rowcount": virtualScroll ? headerRowCount + sorted.length + (hasSummary ? 1 : 0) : undefined, "aria-colcount": virtualScroll ? leadingCells + visibleColumns.length : undefined, children: [caption ? _jsx("caption", { className: "kpt-data-table__caption", children: _jsx("span", { className: "kpt-data-table__caption-text", children: caption }) }) : null, virtualScroll ? (_jsxs("colgroup", { children: [hasRowDetail ? _jsx("col", { className: "kpt-data-table__col-expander" }) : null, selectable !== 'none' ? _jsx("col", { className: "kpt-data-table__col-checkbox" }) : null, slots.map((slot) => (_jsx("col", { style: { width: slot.width } }, slot.key)))] })) : null, _jsxs("thead", { ref: theadRef, children: [hasColumnFilters && filterRowPosition === 'top' ? filterRow : null, _jsxs("tr", { "aria-rowindex": virtualScroll ? (hasColumnFilters && filterRowPosition === 'top' ? 2 : 1) : undefined, children: [hasRowDetail ? (_jsx("th", { className: cn('kpt-data-table__expander', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: expanderStickyLeft } })) : null, selectable === 'multiple' ? (_jsx("th", { className: cn('kpt-data-table__checkbox', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: checkboxStickyLeft }, children: _jsx("input", { type: "checkbox", checked: pageAllSelected, ref: (el) => {
+    return (_jsxs("div", { className: cn('kpt-data-table', className), style: { ['--kpt-thead-offset']: `${theadOffset}px`, ['--kpt-thead-offset-2']: `${theadOffset2}px`, ...style }, ...rest, children: [filterable || exportable ? (_jsxs("div", { className: "kpt-data-table__toolbar", children: [filterable ? (_jsxs("div", { className: "kpt-data-table__search", "data-speech": filterSpeechState, children: [_jsx("input", { ref: filterRef, className: "kpt-data-table__filter", type: "search", placeholder: t('dataTable.search'), "aria-label": t('dataTable.search'), value: filterInput, onChange: (event) => onFilterInput(event.target.value) }), filterSpeech ? (_jsx(KptSpeechButton, { listeningColor: filterSpeechColor, speech: filterMic, size: "sm", unsupported: "hide", hostProps: { className: 'kpt-data-table__speech' } })) : null] })) : null, exportable ? (_jsx(KptButton, { variant: "outline", size: "sm", onClick: () => exportTableCsv(visibleColumns, (lazy ? data : sorted), exportFilename), children: t('dataTable.exportCsv') })) : null] })) : null, _jsx("div", { ref: scrollRef, className: "kpt-data-table__scroll", style: { maxHeight: scrollHeight ?? undefined }, onScroll: onScroll, children: _jsxs("table", { className: cn('kpt-data-table__table', hasFrozen && 'kpt-data-table__table--frozen', virtualScroll && 'kpt-data-table__table--virtual'), style: { width: tableWidth }, "aria-label": ariaLabel ?? undefined, "aria-busy": loading || undefined, "aria-rowcount": virtualScroll ? headerRowCount + sorted.length + (hasSummary ? 1 : 0) : undefined, "aria-colcount": virtualScroll ? leadingCells + visibleColumns.length : undefined, children: [caption ? _jsx("caption", { className: "kpt-data-table__caption", children: _jsx("span", { className: "kpt-data-table__caption-text", children: caption }) }) : null, virtualScroll ? (_jsxs("colgroup", { children: [hasRowDetail ? _jsx("col", { className: "kpt-data-table__col-expander" }) : null, selectable !== 'none' ? _jsx("col", { className: "kpt-data-table__col-checkbox" }) : null, slots.map((slot) => (_jsx("col", { style: { width: slot.width } }, slot.key)))] })) : null, _jsxs("thead", { ref: theadRef, children: [groupCells.length ? (_jsxs("tr", { className: "kpt-data-table__group-row", "aria-rowindex": virtualScroll ? 1 : undefined, children: [hasRowDetail ? (_jsx("th", { className: cn('kpt-data-table__expander', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: expanderStickyLeft } })) : null, selectable !== 'none' ? (_jsx("th", { className: cn('kpt-data-table__checkbox', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: checkboxStickyLeft } })) : null, groupCells.map((cell) => cell.spacer ? (_jsx("td", { className: "kpt-data-table__hspacer", colSpan: cell.span, "aria-hidden": "true" }, cell.key)) : (_jsx("th", { className: cn('kpt-data-table__group', !cell.header && 'kpt-data-table__group--empty', cell.frozen && 'kpt-data-table__cell--frozen'), style: { left: cell.left }, colSpan: cell.span > 1 ? cell.span : undefined, scope: cell.header ? 'colgroup' : undefined, children: cell.header }, cell.key)))] })) : null, hasColumnFilters && filterRowPosition === 'top' ? filterRow : null, _jsxs("tr", { "aria-rowindex": virtualScroll ? groupRows + (hasColumnFilters && filterRowPosition === 'top' ? 2 : 1) : undefined, children: [hasRowDetail ? (_jsx("th", { className: cn('kpt-data-table__expander', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: expanderStickyLeft } })) : null, selectable === 'multiple' ? (_jsx("th", { className: cn('kpt-data-table__checkbox', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: checkboxStickyLeft }, children: _jsx("input", { type: "checkbox", checked: pageAllSelected, ref: (el) => {
                                                     if (el)
                                                         el.indeterminate = pageSomeSelected;
                                                 }, "aria-label": t('dataTable.selectAll'), onChange: toggleAllOnPage }) })) : selectable === 'single' ? (_jsx("th", { className: cn('kpt-data-table__checkbox', hasFrozen && 'kpt-data-table__cell--frozen'), style: { left: checkboxStickyLeft } })) : null, slots.map((slot) => {

package/dist/data-table/llms.txt

@@ -18,6 +18,11 @@ rendered header.
 
 ## Props
 - `columns` (required), `data`
+- `columnGroups`: KptColumnGroup[] - grouped headers: a row above the column labels where adjacent columns of a
+  group share one cell (`[{ header: 'Macros', fields: ['carbs', 'protein', 'fat'] }]`, `scope="colgroup"`). It is
+  computed from the visible columns in their current order: a hidden column drops out, a group split by reordering
+  gets two cells with the same text, a column without a group gets an empty cell. A cell sticks to the left only
+  when all its columns are `frozen`. With column filters the header has three rows and all of them stay sticky
 - `filterable`, `filterRowPosition` (`'bottom'` default), `pageSize` (0 = no pagination),
   `pageSizeOptions`, `selectable` (`'none' | 'single' | 'multiple'`), `loading`, `emptyMessage`,
   `rowKey`, `scrollHeight`, `virtualScroll` (rows **and** columns, see below), `columnWidth`
@@ -113,7 +118,7 @@ The toolbar, the states and the filter labels come from the `dataTable` namespac
 the expanded row `--kpt-table-detail-bg`, the summary row `--kpt-table-summary-bg`.
 
 ## Not ported yet
-Grouped columns (absent in the Angular port too). A ready column-toggle UI is not part of either
+A ready column-toggle UI is not part of either
 port - `hiddenFields` is the hook to build one on.
 
 ## Filter by voice

package/dist/dialog/dialog.js

@@ -50,9 +50,16 @@ export function KptDialog({ open, onOpenChange, header = '', size = 'md', dismis
      * `close` przychodzi z każdej drogi. Przy `dismissible=false` zamknąć wolno tylko z kodu:
      * Chromium z CloseWatcherem pozwala anulować `cancel` jedynie po aktywacji użytkownika, więc drugi
      * Escape z rzędu zamyka okno mimo `preventDefault` - wtedy otwieramy je z powrotem.
+     *
+     * Zdarzenie `close` jest asynchroniczne, więc może dojść, gdy okno jest już znowu otwarte: pod
+     * `StrictMode` efekt montuje się dwa razy (`showModal` -> sprzątanie `close` -> `showModal`)
+     * i dialog zamontowany od razu z `open` dostawał `onOpenChange(false)` od własnego sprzątania.
+     * Otwarty element znaczy, że to zamknięcie jest nieaktualne.
      */
     const onClose = () => {
         const el = dialogRef.current;
+        if (el?.open)
+            return;
         if (!dismissible && open && el && !el.open) {
             el.showModal();
             return;

package/dist/input/input.d.ts

@@ -42,6 +42,11 @@ export interface KptInputProps extends Omit<ComponentPropsWithRef<'input'>, 'typ
      * gdzie zastępuje systemowe "x" (ukryte zawsze, także przy `clearable={false}`).
      */
     clearable?: boolean;
+    /**
+     * Ikona z rejestru na początku pola (`search`, `mail`...). Dekoracyjna - nazwę pola daje etykieta
+     * albo `aria-label`, więc ikona nie trafia do drzewa dostępności.
+     */
+    icon?: string;
 }
 /**
  * Pole tekstowe Koncept UI. Renderuje natywny `<input>` w hoście `.kpt-input-host`.
@@ -57,4 +62,4 @@ export interface KptInputProps extends Omit<ComponentPropsWithRef<'input'>, 'typ
  * <KptInput name="email" type="email" defaultValue="" />
  * <KptInput value={email} onValueChange={setEmail} invalid={!ok} touched={blurred} />
  */
-export declare function KptInput({ type, required, invalid, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, ref, speech, speechLang, speechColor, speechMode, clearable, onKeyDown, locale, dictionary, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptInputProps>): import("react").JSX.Element;
+export declare function KptInput({ type, required, invalid, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, ref, speech, speechLang, speechColor, speechMode, clearable, icon, onKeyDown, locale, dictionary, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptInputProps>): import("react").JSX.Element;

package/dist/input/input.js

@@ -30,7 +30,7 @@ function setFieldValue(field, value) {
  * <KptInput name="email" type="email" defaultValue="" />
  * <KptInput value={email} onValueChange={setEmail} invalid={!ok} touched={blurred} />
  */
-export function KptInput({ type = 'text', required = false, invalid = false, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, ref, speech = false, speechLang, speechColor, speechMode = 'insert', clearable, onKeyDown, locale, dictionary, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }) {
+export function KptInput({ type = 'text', required = false, invalid = false, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, ref, speech = false, speechLang, speechColor, speechMode = 'insert', clearable, icon, onKeyDown, locale, dictionary, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }) {
     const { className: hostClassName, ...hostRest } = hostProps ?? {};
     const field = useKptFieldA11y(id, 'kpt-input');
     const innerRef = useRef(null);
@@ -92,5 +92,5 @@ export function KptInput({ type = 'text', required = false, invalid = false, tou
         onBlur?.(event);
         onTouch?.();
     }, [onBlur, onTouch]);
-    return (_jsxs("span", { className: cn('kpt-input-host', hostClassName), "data-speech": speechState, "data-clear": showClear ? '' : undefined, ...hostRest, children: [_jsx("input", { className: cn('kpt-input__field', className), id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), type: type, "aria-required": required || undefined, "aria-invalid": ariaInvalid ?? (showInvalid || undefined), onChange: handleChange, onBlur: handleBlur, onKeyDown: handleKeyDown, ref: composeRefs(innerRef, ref), ...rest }), showClear ? (_jsx("button", { type: "button", className: "kpt-input__clear", tabIndex: -1, "aria-label": t('input.clear'), onMouseDown: (event) => event.preventDefault(), onClick: clear, children: _jsx(KptIcon, { name: "x" }) })) : null, speech ? (_jsx(KptSpeechButton, { listeningColor: speechColor, speech: mic, size: "sm", unsupported: "hide", disabled: !!rest.disabled || !!rest.readOnly, hostProps: { className: 'kpt-input__speech' } })) : null] }));
+    return (_jsxs("span", { className: cn('kpt-input-host', hostClassName), "data-speech": speechState, "data-clear": showClear ? '' : undefined, "data-icon": icon ? '' : undefined, ...hostRest, children: [icon ? _jsx(KptIcon, { className: "kpt-input__icon", name: icon }) : null, _jsx("input", { className: cn('kpt-input__field', className), id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), type: type, "aria-required": required || undefined, "aria-invalid": ariaInvalid ?? (showInvalid || undefined), onChange: handleChange, onBlur: handleBlur, onKeyDown: handleKeyDown, ref: composeRefs(innerRef, ref), ...rest }), showClear ? (_jsx("button", { type: "button", className: "kpt-input__clear", tabIndex: -1, "aria-label": t('input.clear'), onMouseDown: (event) => event.preventDefault(), onClick: clear, children: _jsx(KptIcon, { name: "x" }) })) : null, speech ? (_jsx(KptSpeechButton, { listeningColor: speechColor, speech: mic, size: "sm", unsupported: "hide", disabled: !!rest.disabled || !!rest.readOnly, hostProps: { className: 'kpt-input__speech' } })) : null] }));
 }

package/dist/input/llms.txt

@@ -16,6 +16,9 @@ Import: `import { KptInput } from '@konce-pt/react';`
 - `required`: boolean - see the note below
 - `invalid`: boolean, `touched`: boolean - the error state
 - `clearable`: boolean (default: `true` only for `type="search"`) - a clear button, see "Clear button"
+- `icon`: string - a registry icon at the start of the field (`search`, `mail`...). Decorative: the field's
+  name comes from the label or the aria label, so the icon stays out of the accessibility tree; a click on it
+  lands in the field
 - `hostProps` - props for the `.kpt-input-host` wrapper
 - `className`, `ref`, `name`, `placeholder`, `autoComplete` and every other `<input>` prop go to
   the inner `<input>`
@@ -66,6 +69,7 @@ dictionary. The host gets `data-clear` while the button is visible.
 
     <KptInput type="search" value={query} onValueChange={setQuery} />
     <KptInput clearable value={coupon} onValueChange={setCoupon} />
+    <KptInput type="search" icon="search" value={query} onValueChange={setQuery} />
 
 ## Tokens
 `--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}`.

package/dist/popover/llms.txt

@@ -17,6 +17,9 @@ Import: `import { KptPopover } from '@konce-pt/react';`
 - `placement`: 'bottom' (default) | 'top' - the preferred side; it flips when there is no room
 - `maxWidth`: string - the panel's maximum width, any CSS length (`'24rem'`; default `20rem`). The panel is
   never wider than the window minus the 8 px overlay margin
+- `ariaLabel`: string - the accessible name of the panel (`role="dialog"`); give one whenever the panel has
+  no visible heading. It names the panel, not the host - `aria-label` in the rest props would land on the
+  host `<span>`
 - `className`, `ref` and every other `<span>` prop go to the host
 
 ## The panel is a portal

package/dist/public-api.d.ts

@@ -74,7 +74,7 @@ export { KptDataTable } from './data-table/data-table.tsx';
 export type { KptDataTableProps } from './data-table/data-table.tsx';
 export { exportTableCsv } from './data-table/export-csv.ts';
 export type { KptCellEditContext, KptCellEditEvent, KptCellEditRenderers, KptCellRenderers, KptColumn, KptColumnEdit, KptColumnEditType, KptSortDir, KptTableLazyState, } from './data-table/data-table-types.ts';
-export type { KptColumnFilter, KptColumnFilterType, KptColumnSummary, KptSummaryFn } from '@konce-pt/table';
+export type { KptColumnFilter, KptColumnFilterType, KptColumnGroup, KptColumnSummary, KptSummaryFn } from '@konce-pt/table';
 export { KptDataView } from './data-view/data-view.tsx';
 export type { KptDataViewLayout, KptDataViewProps } from './data-view/data-view.tsx';
 export { KptTree } from './tree/tree.tsx';
@@ -123,7 +123,7 @@ export type { KptOverlayProps } from './internal/overlay.tsx';
 export { KptButtonGroup } from './button-group/button-group.tsx';
 export type { KptButtonGroupProps } from './button-group/button-group.tsx';
 export { KptSelect } from './select/select.tsx';
-export type { KptSelectProps } from './select/select.tsx';
+export type { KptSelectMultipleProps, KptSelectProps, KptSelectSingleProps } from './select/select.tsx';
 export type { KptAlertVariant, KptNavigateEvent, KptOption } from './shared/types.ts';
 export { KptFormField } from './form-field/form-field.tsx';
 export type { KptFormFieldLabelType, KptFormFieldProps } from './form-field/form-field.tsx';

package/dist/select/llms.txt

@@ -15,7 +15,11 @@ A select on its own panel. Variants: single, with a search box (`filter`) and mu
 
 ## Props
 - `options`: `KptOption<T>[]` - `{ label, value, disabled? }`
-- `value` / `defaultValue` / `onValueChange` - a single `T`, or `T[]` in `multiple` mode
+- `value` / `defaultValue` / `onValueChange` - a single `T`, or `T[]` in `multiple` mode. The handler type
+  follows `multiple` (overloads): without it `(value: T) => void` - a single select cannot clear its
+  choice, so it never reports an array or `null`; with `multiple` `(value: T[]) => void`. A flag computed at
+  run time (`multiple={flag}`) keeps the wide `T | T[] | null`. Types: `KptSelectSingleProps`,
+  `KptSelectMultipleProps`, `KptSelectProps` (the wide one)
 - `open` / `defaultOpen` / `onOpenChange` - the panel state, so the list can be opened from outside
 - `placeholder`, `multiple`, `filter`, `disabled`, `invalid`, `touched`
 - `onTouch()` - fires when the panel closes or focus leaves the closed trigger

package/dist/select/select.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentPropsWithRef } from 'react';
+import { type ComponentPropsWithRef, type JSX } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptOption } from '../shared/types.ts';
 export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'children' | 'onChange' | 'defaultValue'>, KptI18nOverrides {
@@ -28,6 +28,23 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
     /** Wywoływane, gdy panel się zamyka albo trigger traci fokus. */
     onTouch?: () => void;
 }
+/**
+ * Pojedynczy wybór: `onValueChange` dostaje zawsze wybraną opcję - nigdy tablicę ani `null`, bo
+ * lista bez `multiple` nie ma jak wyczyścić wyboru. Rodzic trzyma więc zwykłe `T`.
+ */
+export interface KptSelectSingleProps<T> extends Omit<KptSelectProps<T>, 'multiple' | 'value' | 'defaultValue' | 'onValueChange'> {
+    multiple?: false;
+    value?: T | null;
+    defaultValue?: T | null;
+    onValueChange?: (value: T) => void;
+}
+/** Wybór wielokrotny: wartością jest zawsze tablica (pusta, gdy nic nie wybrano). */
+export interface KptSelectMultipleProps<T> extends Omit<KptSelectProps<T>, 'multiple' | 'value' | 'defaultValue' | 'onValueChange'> {
+    multiple: true;
+    value?: T[] | null;
+    defaultValue?: T[] | null;
+    onValueChange?: (value: T[]) => void;
+}
 /**
  * Lista wyboru (select) na własnym panelu. Warianty: pojedynczy, z wyszukiwarką (`filter`)
  * i wielokrotny (`multiple`, chipy).
@@ -46,5 +63,10 @@ export interface KptSelectProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'c
  * @example
  * <KptSelect options={roles} value={role} onValueChange={setRole} placeholder="Wybierz..." />
  * <KptSelect options={tags} multiple filter value={tags} onValueChange={setTags} />
+ *
+ * Typ `onValueChange` idzie za `multiple`: bez niego `(value: T)`, z `multiple` - `(value: T[])`.
+ * `multiple` liczone w locie (`multiple={flag}`) zostawia szeroki typ `T | T[] | null`.
  */
-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;
+export declare function KptSelect<T>(props: Readonly<KptSelectSingleProps<T>>): JSX.Element;
+export declare function KptSelect<T>(props: Readonly<KptSelectMultipleProps<T>>): JSX.Element;
+export declare function KptSelect<T>(props: Readonly<KptSelectProps<T>>): JSX.Element;

package/dist/select/select.js

@@ -18,25 +18,6 @@ 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).
- *
- * Klawiatura według wzorca WAI-ARIA "select-only combobox": fokus zostaje na polu, a aktywna opcja
- * idzie przez `aria-activedescendant`. `ArrowDown`/`ArrowUp`/`Enter`/`Spacja` otwierają listę na wybranej opcji,
- * strzałki, `Home`/`End`, `PageUp`/`PageDown` chodzą po opcjach (z pominięciem wyłączonych),
- * wpisywane litery skaczą do pasującej opcji (bez polskich znaków), `Enter` wybiera, `Escape`
- * zamyka. Z `filter` fokus przechodzi do pola wyszukiwania, które obsługuje te same klawisze.
- * W trybie `multiple` `Backspace` na zamkniętym polu usuwa ostatni wybór.
- *
- * Wewnątrz `KptFormField` zgłasza wypełnienie hookiem `useKptFormFieldFilled`, więc etykieta
- * Float Label unosi się nad wybraną wartością - natywnego pola, z którego wrapper mógłby to
- * odczytać, tu nie ma.
- *
- * @example
- * <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, 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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konce-pt/react",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "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",
@@ -65,19 +65,19 @@
     "leaflet": "^1.9.0"
   },
   "dependencies": {
-    "@konce-pt/chart": "0.17.0",
-    "@konce-pt/chat": "0.17.0",
-    "@konce-pt/backdrop": "0.17.0",
-    "@konce-pt/mention": "0.17.0",
-    "@konce-pt/motion": "0.17.0",
-    "@konce-pt/roadmap": "0.17.0",
-    "@konce-pt/icons": "0.17.0",
-    "@konce-pt/datetime": "0.17.0",
-    "@konce-pt/table": "0.17.0",
-    "@konce-pt/speech": "0.17.0",
-    "@konce-pt/i18n": "0.17.0",
-    "@konce-pt/tokens": "0.17.0",
-    "@konce-pt/map": "0.17.0"
+    "@konce-pt/backdrop": "0.18.1",
+    "@konce-pt/icons": "0.18.1",
+    "@konce-pt/chart": "0.18.1",
+    "@konce-pt/roadmap": "0.18.1",
+    "@konce-pt/mention": "0.18.1",
+    "@konce-pt/speech": "0.18.1",
+    "@konce-pt/motion": "0.18.1",
+    "@konce-pt/i18n": "0.18.1",
+    "@konce-pt/map": "0.18.1",
+    "@konce-pt/chat": "0.18.1",
+    "@konce-pt/tokens": "0.18.1",
+    "@konce-pt/datetime": "0.18.1",
+    "@konce-pt/table": "0.18.1"
   },
   "devDependencies": {
     "@types/react": "^19.2.0",