@konce-pt/react 0.8.3 → 0.9.0

package/dist/progress/llms.txt

@@ -1,47 +1,95 @@
 # KptProgress (@konce-pt/react)
 
-A progress indicator — linear or circular, determinate (0–100) or indeterminate (`value` = null).
+A progress indicator — linear or circular, determinate (`min`–`max`) or indeterminate (`value` = null).
 Import: `import { KptProgress } from '@konce-pt/react';`
 
 ## DOM
-    <!-- linear -->
-    <div class="kpt-progress-host">
-      <div class="kpt-progress__linear" data-variant="primary" role="progressbar" aria-valuenow="65">
-        <div class="kpt-progress__bar" style="width: 65%"></div>
+    <!-- linear, with a label, a buffer and a value -->
+    <div class="kpt-progress-host" data-type="linear" data-size="md" data-variant="primary" data-label-position="top">
+      <span class="kpt-progress__label">Loading…</span>
+      <div class="kpt-progress__linear" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="80">
+        <div class="kpt-progress__buffer" style="width: 92%"></div>
+        <div class="kpt-progress__bar" style="width: 80%"></div>
       </div>
+      <span class="kpt-progress__value" aria-hidden="true">80%</span>
     </div>
 
     <!-- circular -->
-    <svg class="kpt-progress__circular" data-variant="success" viewBox="0 0 40 40" role="progressbar" aria-valuenow="75">
-      <circle class="kpt-progress__track" cx="20" cy="20" r="16"></circle>
-      <circle class="kpt-progress__bar" cx="20" cy="20" r="16" style="stroke-dasharray: 100.531; stroke-dashoffset: 25.1327"></circle>
-    </svg>
+    <div class="kpt-progress-host" data-type="circular" data-size="md" data-variant="success">
+      <svg class="kpt-progress__circular" viewBox="0 0 40 40" role="progressbar" aria-valuenow="75">
+        <circle class="kpt-progress__track" cx="20" cy="20" r="16"></circle>
+        <circle class="kpt-progress__bar" cx="20" cy="20" r="16" style="stroke-dasharray: 100.531; stroke-dashoffset: 25.1327"></circle>
+      </svg>
+      <span class="kpt-progress__value" aria-hidden="true">75%</span>
+    </div>
+
+The label, the track and the value are siblings straight under the host — there is no wrapper element.
+`data-variant`, `data-type`, `data-size` and `data-label-position` all sit on the host, which is also
+where the private `--_color` and `--_thickness` are resolved. This markup matches the Angular port
+element for element, so both share one stylesheet.
 
 ## Props
-- `value`: number | null (default null) — 0–100, or null for indeterminate
+- `value`: number | null (default null) — a value on the `min`–`max` scale, or null for indeterminate
+- `min`: number (default 0); `max`: number (default 100)
 - `variant`: 'primary' | 'success' | 'danger' | 'warning' | 'info' (default 'primary')
 - `type`: 'linear' | 'circular' (default 'linear')
+- `size`: 'sm' | 'md' | 'lg' (default 'md') — track thickness, and arc width on the circular variant
 - `diameter`: number (default 40) — the circular variant's size in pixels
+- `bufferValue`: number | null (default null) — a second, dimmed bar behind the main one; linear only
+- `showValue`: boolean (default false) — turns the value area on; `children` needs it too
+- `valueFormat`: 'percent' | 'fraction' | 'none' (default 'percent')
+- `label`: string — descriptive text next to the bar; it also becomes the `aria-label`
+- `labelPosition`: 'top' | 'bottom' | 'end' (default 'top') — ignored by the circular variant
+- `locale`, `dictionary` — per-instance dictionary overrides
 - `className`, `ref` and every other `<div>` prop go to the host
 
+## Value label
+`showValue` opens the value area; `valueFormat` decides what goes in it — `percent` renders `80%`,
+`fraction` renders `152 / 160` from `value` and `max`, `none` leaves it empty. Both strings come from
+the `KptMessages` dictionary (`progress.percent`, `progress.fraction`), so a new locale can reshape them.
+
+`children` replaces the formatted value instead of adding to it, which is how a circle shows a headline
+number over a caption. It still requires `showValue`, because that prop is what renders the element the
+content lands in.
+
+The circular variant always centres the value over the arc; `label` is not drawn there, it only feeds
+the accessible name.
+
 ## How the arc is drawn
-The circle lives in a fixed `viewBox="0 0 40 40"` with `r=16`, so the circumference is computed
-from that radius, not from `diameter` — the SVG scales, the maths does not change. The arc is the
-dash offset: full circumference means empty, zero means complete. An indeterminate circle is pinned
-at a quarter of the circumference and spun by CSS.
+The circle lives in a fixed `viewBox="0 0 40 40"` with `r=16`, so the circumference is computed from
+that radius, not from `diameter` — the SVG scales, the maths does not change. The arc is the dash
+offset: full circumference means empty, zero means complete. `size` only changes `stroke-width`, and
+the widest step still fits inside the box, so no arc is ever clipped.
 
-Values outside 0–100 are clamped rather than rejected, so a computed percentage that briefly
-overshoots cannot break the drawing.
+Values outside the range are clamped rather than rejected, `max` ≤ `min` collapses to zero, and the
+buffer is never allowed behind the main bar — a computed percentage that briefly overshoots cannot
+break the drawing.
 
 ## Examples
-    <KptProgress value={65} />
-    <KptProgress value={null} variant="info" />
-    <KptProgress type="circular" value={75} variant="success" diameter={64} />
+    <KptProgress value={60} />
+    <KptProgress value={80} label="Loading…" showValue />
+    <KptProgress value={152} max={160} size="lg" showValue valueFormat="fraction" labelPosition="bottom" />
+    <KptProgress value={65} showValue labelPosition="end" />
+    <KptProgress value={38} bufferValue={62} />
+    <KptProgress type="circular" value={80} showValue />
+    <KptProgress type="circular" value={72} diameter={140} size="lg" showValue>
+      <strong>29</strong>
+      <small>Excellent</small>
+    </KptProgress>
+    <KptProgress value={null} />
 
 ## Tokens
 The semantic colour of each variant (`--kpt-color-primary` / `-success` / `-danger` / `-warning` /
-`-info`), `--kpt-color-muted` for the track.
+`-info`), plus the component layer: `--kpt-progress-track-bg`, `--kpt-progress-thickness-sm`,
+`--kpt-progress-thickness-md`, `--kpt-progress-thickness-lg`, `--kpt-progress-buffer-opacity`,
+`--kpt-progress-label-fg`, `--kpt-progress-value-fg`, `--kpt-progress-gap`.
 
 ## Accessibility
-`role="progressbar"` with `aria-valuenow`; an indeterminate bar leaves the value out, which is how
-a screen reader learns the progress is unknown rather than zero.
+`role="progressbar"` with `aria-valuemin`, `aria-valuemax` and `aria-valuenow`; an indeterminate bar
+leaves the value out, which is how a screen reader learns the progress is unknown rather than zero.
+`valueFormat="fraction"` also sets `aria-valuetext`, so the reader says "152 / 160" instead of
+announcing the raw number as a percentage. The visible value is `aria-hidden`, so it is never read
+twice. The accessible name comes from `label`, or from the dictionary when there is none.
+
+Under `prefers-reduced-motion: reduce` the indeterminate animation slows down instead of stopping —
+a frozen progress indicator reads as a hung application.

package/dist/progress/progress.d.ts

@@ -1,19 +1,46 @@
-import type { ComponentPropsWithRef } from 'react';
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export type KptProgressVariant = 'primary' | 'success' | 'danger' | 'warning' | 'info';
-export interface KptProgressProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
-    /** 0–100 albo `null` = postęp nieokreślony. */
+export type KptProgressType = 'linear' | 'circular';
+export type KptProgressSize = 'sm' | 'md' | 'lg';
+/** Postać etykiety wartości: procent, „ile z ilu" albo brak. */
+export type KptProgressValueFormat = 'percent' | 'fraction' | 'none';
+/** Gdzie siada wiersz etykiety względem paska (tylko `type="linear"`). */
+export type KptProgressLabelPosition = 'top' | 'bottom' | 'end';
+export interface KptProgressProps extends ComponentPropsWithRef<'div'>, KptI18nOverrides {
+    /** Wartość w skali `min`–`max` albo `null` = postęp nieokreślony. */
     value?: number | null;
+    min?: number;
+    max?: number;
     variant?: KptProgressVariant;
-    type?: 'linear' | 'circular';
+    type?: KptProgressType;
+    /** Grubość toru: `sm` 0.25rem, `md` 0.5rem, `lg` 0.75rem. */
+    size?: KptProgressSize;
     /** Średnica wariantu kołowego w pikselach. */
     diameter?: number;
+    /** Postęp buforowania — drugi, przygaszony pasek pod głównym (tylko liniowy). */
+    bufferValue?: number | null;
+    /** Włącza obszar etykiety wartości — razem z nim renderuje się `children`. */
+    showValue?: boolean;
+    valueFormat?: KptProgressValueFormat;
+    /** Tekst opisowy obok paska; służy też za `aria-label`. */
+    label?: string;
+    labelPosition?: KptProgressLabelPosition;
+    /** Zastępuje sformatowaną wartość — wymaga `showValue`. */
+    children?: ReactNode;
 }
 /**
- * Wskaźnik postępu — liniowy lub kołowy, określony (0–100) albo nieokreślony (`value` = null).
+ * Wskaźnik postępu — liniowy lub kołowy, określony (`min`–`max`) albo nieokreślony (`value` = null).
+ *
+ * Etykietę wartości włącza `showValue`; `children` zastępuje sformatowaną wartość,
+ * więc w środku koła można pokazać cokolwiek.
  *
  * @example
  * <KptProgress value={60} />
- * <KptProgress type="circular" value={75} variant="success" />
+ * <KptProgress value={80} label="Ładowanie…" showValue />
+ * <KptProgress value={152} max={160} showValue valueFormat="fraction" labelPosition="bottom" />
+ * <KptProgress value={38} bufferValue={62} />
+ * <KptProgress type="circular" value={75} variant="success" showValue />
  * <KptProgress value={null} />
  */
-export declare function KptProgress({ value, variant, type, diameter, className, ...rest }: Readonly<KptProgressProps>): import("react").JSX.Element;
+export declare function KptProgress({ value, min, max, variant, type, size, diameter, bufferValue, showValue, valueFormat, label, labelPosition, locale, dictionary, className, children, ...rest }: Readonly<KptProgressProps>): import("react").JSX.Element;

package/dist/progress/progress.js

@@ -1,21 +1,58 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { cn } from "../internal/cn.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
 /** Promień okręgu w viewBox 0 0 40 40 — obwód liczymy z niego, nie ze średnicy w pikselach. */
 const RADIUS = 16;
 const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
 /**
- * Wskaźnik postępu — liniowy lub kołowy, określony (0–100) albo nieokreślony (`value` = null).
+ * Wskaźnik postępu — liniowy lub kołowy, określony (`min`–`max`) albo nieokreślony (`value` = null).
+ *
+ * Etykietę wartości włącza `showValue`; `children` zastępuje sformatowaną wartość,
+ * więc w środku koła można pokazać cokolwiek.
  *
  * @example
  * <KptProgress value={60} />
- * <KptProgress type="circular" value={75} variant="success" />
+ * <KptProgress value={80} label="Ładowanie…" showValue />
+ * <KptProgress value={152} max={160} showValue valueFormat="fraction" labelPosition="bottom" />
+ * <KptProgress value={38} bufferValue={62} />
+ * <KptProgress type="circular" value={75} variant="success" showValue />
  * <KptProgress value={null} />
  */
-export function KptProgress({ value = null, variant = 'primary', type = 'linear', diameter = 40, className, ...rest }) {
+export function KptProgress({ value = null, min = 0, max = 100, variant = 'primary', type = 'linear', size = 'md', diameter = 40, bufferValue = null, showValue = false, valueFormat = 'percent', label, labelPosition = 'top', locale, dictionary, className, children, ...rest }) {
+    const { t } = useKptMessages({ locale, dictionary });
     const indeterminate = value == null;
-    // Nieokreślony postęp pokazuje wycinek 25% obwodu, który obraca CSS — stąd stały offset.
-    const offset = indeterminate
-        ? CIRCUMFERENCE * 0.75
-        : CIRCUMFERENCE * (1 - Math.min(100, Math.max(0, value)) / 100);
-    return (_jsx("div", { className: cn('kpt-progress-host', className), ...rest, children: type === 'circular' ? (_jsxs("svg", { className: cn('kpt-progress__circular', indeterminate && 'kpt-progress--indeterminate'), "data-variant": variant, width: diameter, height: diameter, viewBox: "0 0 40 40", role: "progressbar", "aria-valuenow": value ?? undefined, children: [_jsx("circle", { className: "kpt-progress__track", cx: "20", cy: "20", r: RADIUS }), _jsx("circle", { className: "kpt-progress__bar", cx: "20", cy: "20", r: RADIUS, style: { strokeDasharray: CIRCUMFERENCE, strokeDashoffset: offset } })] })) : (_jsx("div", { className: "kpt-progress__linear", "data-variant": variant, role: "progressbar", "aria-valuenow": value ?? undefined, children: _jsx("div", { className: cn('kpt-progress__bar', indeterminate && 'kpt-progress--indeterminate'), style: { width: `${value ?? 0}%` } }) })) }));
+    /** Ułamek 0–1. Odporny na `max` ≤ `min` i na wartości spoza zakresu. */
+    const toRatio = (v) => {
+        if (v == null)
+            return 0;
+        const span = max - min;
+        if (span <= 0)
+            return 0;
+        return Math.min(1, Math.max(0, (v - min) / span));
+    };
+    const ratio = toRatio(value);
+    const percent = Math.round(ratio * 100);
+    // Bufor nigdy nie cofa się za pasek główny — inaczej wyglądałby jak błąd renderowania.
+    const bufferRatio = Math.max(ratio, toRatio(bufferValue));
+    const offset = CIRCUMFERENCE * (1 - ratio);
+    const fractionText = () => t('progress.fraction', { value: value ?? 0, max });
+    let valueText = '';
+    if (!indeterminate && valueFormat !== 'none') {
+        valueText = valueFormat === 'fraction' ? fractionText() : t('progress.percent', { value: percent });
+    }
+    /**
+     * Czytnik ekranu domyślnie odczytuje `aria-valuenow` jako procent, więc przy formacie „ile z ilu"
+     * podajemy mu ten sam napis, który widzi użytkownik.
+     */
+    const ariaValueText = indeterminate || valueFormat !== 'fraction' ? undefined : fractionText();
+    const ariaLabel = label ?? t(indeterminate ? 'progress.loading' : 'progress.label');
+    const barAria = {
+        role: 'progressbar',
+        'aria-label': ariaLabel,
+        'aria-valuemin': min,
+        'aria-valuemax': max,
+        'aria-valuenow': indeterminate ? undefined : (value ?? undefined),
+        'aria-valuetext': ariaValueText,
+    };
+    return (_jsxs("div", { className: cn('kpt-progress-host', className), "data-type": type, "data-size": size, "data-variant": variant, "data-label-position": labelPosition, ...rest, children: [type === 'circular' ? (_jsxs("svg", { className: cn('kpt-progress__circular', indeterminate && 'kpt-progress--indeterminate'), width: diameter, height: diameter, viewBox: "0 0 40 40", ...barAria, children: [_jsx("circle", { className: "kpt-progress__track", cx: "20", cy: "20", r: RADIUS }), _jsx("circle", { className: "kpt-progress__bar", cx: "20", cy: "20", r: RADIUS, style: indeterminate ? undefined : { strokeDasharray: CIRCUMFERENCE, strokeDashoffset: offset } })] })) : (_jsxs(_Fragment, { children: [label ? _jsx("span", { className: "kpt-progress__label", children: label }) : null, _jsxs("div", { className: "kpt-progress__linear", ...barAria, children: [bufferValue != null && !indeterminate ? (_jsx("div", { className: "kpt-progress__buffer", style: { width: `${bufferRatio * 100}%` } })) : null, _jsx("div", { className: cn('kpt-progress__bar', indeterminate && 'kpt-progress--indeterminate'), style: indeterminate ? undefined : { width: `${ratio * 100}%` } })] })] })), showValue ? (_jsx("span", { className: "kpt-progress__value", "aria-hidden": "true", children: children ?? valueText })) : null] }));
 }

package/dist/public-api.d.ts

@@ -23,7 +23,7 @@ export type { KptDividerOrientation, KptDividerProps } from './divider/divider.t
 export { KptEmpty } from './empty/empty.tsx';
 export type { KptEmptyProps } from './empty/empty.tsx';
 export { KptProgress } from './progress/progress.tsx';
-export type { KptProgressProps, KptProgressVariant } from './progress/progress.tsx';
+export type { KptProgressProps, KptProgressVariant, KptProgressType, KptProgressSize, KptProgressValueFormat, KptProgressLabelPosition, } from './progress/progress.tsx';
 export { KptSpinner } from './spinner/spinner.tsx';
 export type { KptSpinnerProps } from './spinner/spinner.tsx';
 export { KptSkeleton } from './skeleton/skeleton.tsx';
@@ -36,10 +36,14 @@ export { KptAvatar } from './avatar/avatar.tsx';
 export type { KptAvatarProps, KptAvatarShape, KptAvatarSize } from './avatar/avatar.tsx';
 export { KptBadge } from './badge/badge.tsx';
 export type { KptBadgeProps, KptBadgeSize, KptBadgeVariant } from './badge/badge.tsx';
+export { KptBackdrop } from './backdrop/backdrop.tsx';
+export type { KptBackdropAnchor, KptBackdropEffect, KptBackdropProps } from './backdrop/backdrop.tsx';
+export type { KptBackdropRenderOptions, KptBackdropRenderer, KptOklab, KptRgb, KptSignalGridCell, KptSignalGridFrame, KptSignalGridOptions, KptWaveOptions, KptWaveSettings, } from '@konce-pt/backdrop';
+export { KPT_SIGNAL_GRID_CELL, KPT_SIGNAL_GRID_DENSITY, KPT_SIGNAL_GRID_FALLOFF, KPT_SIGNAL_GRID_GAP, KPT_WAVE_AMPLITUDE, KPT_WAVE_BAND, KPT_WAVE_RESOLUTION, KPT_WAVE_ROTATION, buildSignalGrid, createBackdropRenderer, mixOklch, readCssColor, resolveWave, shiftHue, signalGridAlpha, signalGridDensity, waveIntensity, waveRamp, } from '@konce-pt/backdrop';
 export { KptChip } from './chip/chip.tsx';
-export type { KptChipProps, KptChipVariant } from './chip/chip.tsx';
+export type { KptChipProps, KptChipTextTransform, KptChipVariant } from './chip/chip.tsx';
 export { KptDialog, KptDialogFooter } from './dialog/dialog.tsx';
-export type { KptDialogProps } from './dialog/dialog.tsx';
+export type { KptDialogProps, KptDialogSize } from './dialog/dialog.tsx';
 export { KptDrawer } from './drawer/drawer.tsx';
 export type { KptDrawerPosition, KptDrawerProps } from './drawer/drawer.tsx';
 export { KptBottomSheet } from './bottom-sheet/bottom-sheet.tsx';
@@ -102,6 +106,14 @@ export { KptTooltip } from './tooltip/tooltip.tsx';
 export type { KptTooltipPosition, KptTooltipProps } from './tooltip/tooltip.tsx';
 export { KptPopover } from './popover/popover.tsx';
 export type { KptPopoverProps } from './popover/popover.tsx';
+export { KptPeek } from './peek/peek.tsx';
+export type { KptPeekPlacement, KptPeekProps } from './peek/peek.tsx';
+export { KptMention } from './mention/mention.tsx';
+export type { KptMentionProps } from './mention/mention.tsx';
+export { KptMentions } from './mention/mentions.tsx';
+export type { KptMentionsProps } from './mention/mentions.tsx';
+export type { KptMentionItem, KptMentionQuery, KptMentionSegment } from '@konce-pt/mention';
+export { KPT_MENTION_LIMIT, applyMention, collectMentions, filterMentions, foldMentionText, mentionQuery, mentionToken, parseMentionText, } from '@konce-pt/mention';
 export { KptOverlay } from './internal/overlay.tsx';
 export type { KptOverlayProps } from './internal/overlay.tsx';
 export { KptButtonGroup } from './button-group/button-group.tsx';

package/dist/public-api.js

@@ -27,6 +27,8 @@ export { KptIcon } from "./icon/icon.js";
 export { getKptIcon, hasKptIcon, registerKptIcons } from "./icon/icon-registry.js";
 export { KptAvatar } from "./avatar/avatar.js";
 export { KptBadge } from "./badge/badge.js";
+export { KptBackdrop } from "./backdrop/backdrop.js";
+export { KPT_SIGNAL_GRID_CELL, KPT_SIGNAL_GRID_DENSITY, KPT_SIGNAL_GRID_FALLOFF, KPT_SIGNAL_GRID_GAP, KPT_WAVE_AMPLITUDE, KPT_WAVE_BAND, KPT_WAVE_RESOLUTION, KPT_WAVE_ROTATION, buildSignalGrid, createBackdropRenderer, mixOklch, readCssColor, resolveWave, shiftHue, signalGridAlpha, signalGridDensity, waveIntensity, waveRamp, } from '@konce-pt/backdrop';
 export { KptChip } from "./chip/chip.js";
 // Komponenty — nakładki
 export { KptDialog, KptDialogFooter } from "./dialog/dialog.js";
@@ -60,6 +62,10 @@ export { KptBreadcrumb } from "./breadcrumb/breadcrumb.js";
 export { KptContextMenu } from "./context-menu/context-menu.js";
 export { KptTooltip } from "./tooltip/tooltip.js";
 export { KptPopover } from "./popover/popover.js";
+export { KptPeek } from "./peek/peek.js";
+export { KptMention } from "./mention/mention.js";
+export { KptMentions } from "./mention/mentions.js";
+export { KPT_MENTION_LIMIT, applyMention, collectMentions, filterMentions, foldMentionText, mentionQuery, mentionToken, parseMentionText, } from '@konce-pt/mention';
 export { KptOverlay } from "./internal/overlay.js";
 // Komponenty — formularze
 export { KptButtonGroup } from "./button-group/button-group.js";

package/dist/rich-text/llms.txt

@@ -9,8 +9,18 @@ Import: `import { KptRichText, type KptRichTool } from '@konce-pt/react';`
 - `toolbar`: `KptRichTool[] | KptRichTool[][]` — a flat list, or groups = sections separated by a
   divider. Leaving a tool or a group out disables it; the full toolbar in 5 sections by default.
 - `placeholder`, `maxListLevel` (6), `disabled`, `invalid`, `touched`, `onTouch()`
+- `mentions`: `readonly KptMentionItem[]`, `mentionLimit` (8), `onMention(item)` — suggestions
+  for `@`; an empty list turns the mechanism off, so `@` stays an ordinary character
 - `className`, `ref` and every other `<div>` prop go to the host
 
+## Mentions (`@`)
+With `mentions` set, typing `@` opens a suggestion list anchored at the caret: arrows move through
+it, Enter or Tab inserts, Escape closes. The query is read from the **text node** at the caret and
+recognised by `mentionQuery()` from `@konce-pt/mention` — the same rules as in the Angular port.
+An inserted mention is `<span class="kpt-mention" data-mention="id" contenteditable="false">@Name`
+plus a non-breaking space: the id survives saving, the flag keeps the mention in one piece and the
+space gives the caret a place to stand after it.
+
 ## Tools (KptRichTool)
 Clipboard: `copy`, `paste` (sanitized), `pasteText`. Style: `heading` (a panel: Normal + H1–H6).
 Format: `bold`, `italic`, `underline`, `strike`, `ul`, `ol`, `indent`, `outdent`.

package/dist/rich-text/rich-text.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentPropsWithRef } from 'react';
+import { type KptMentionItem } from '@konce-pt/mention';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export type KptRichTool = 'copy' | 'paste' | 'pasteText' | 'heading' | 'bold' | 'italic' | 'underline' | 'strike' | 'ul' | 'ol' | 'indent' | 'outdent' | 'foreColor' | 'backColor' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'alignJustify' | 'link' | 'table' | 'clear' | 'html';
 /** Pasek: płaska lista narzędzi albo grupy — sekcje rozdzielone separatorem. */
@@ -16,6 +17,15 @@ export interface KptRichTextProps extends Omit<ComponentPropsWithRef<'div'>, 'on
     invalid?: boolean;
     touched?: boolean;
     onTouch?: () => void;
+    /**
+     * Pozycje do podpowiedzi wzmianek. Pusta lista wyłącza mechanizm: `@` zostaje wtedy zwykłym
+     * znakiem, bo nie ma czego podpowiadać.
+     */
+    mentions?: readonly KptMentionItem[];
+    /** Ile podpowiedzi naraz. */
+    mentionLimit?: number;
+    /** Wstawiona wzmianka — moment na powiadomienie osoby albo dopięcie powiązania. */
+    onMention?: (item: KptMentionItem) => void;
 }
 /**
  * Lekki edytor tekstu sformatowanego na `contenteditable`, z konfigurowalnym paskiem sekcji
@@ -25,4 +35,4 @@ export interface KptRichTextProps extends Omit<ComponentPropsWithRef<'div'>, 'on
  * <KptRichText value={html} onValueChange={setHtml} />
  * <KptRichText value={html} onValueChange={setHtml} toolbar={[['bold', 'italic'], ['link']]} />
  */
-export declare function KptRichText({ value, defaultValue, onValueChange, toolbar, placeholder, maxListLevel, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptRichTextProps>): import("react").JSX.Element;
+export declare function KptRichText({ value, defaultValue, onValueChange, toolbar, placeholder, maxListLevel, disabled, invalid, touched, onTouch, mentions, mentionLimit, onMention, locale, dictionary, className, ...rest }: Readonly<KptRichTextProps>): import("react").JSX.Element;

package/dist/rich-text/rich-text.js

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useRef, useState, } from 'react';
 import { createPortal } from 'react-dom';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
+import { KPT_MENTION_LIMIT, filterMentions, mentionQuery } from '@konce-pt/mention';
 import { useKptOverlayContainer } from "../internal/overlay-container.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
@@ -85,7 +86,7 @@ function legacyState(cmd) {
  * <KptRichText value={html} onValueChange={setHtml} />
  * <KptRichText value={html} onValueChange={setHtml} toolbar={[['bold', 'italic'], ['link']]} />
  */
-export function KptRichText({ value, defaultValue = '', onValueChange, toolbar = DEFAULT_TOOLBAR, placeholder = '', maxListLevel = 6, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+export function KptRichText({ value, defaultValue = '', onValueChange, toolbar = DEFAULT_TOOLBAR, placeholder = '', maxListLevel = 6, disabled = false, invalid = false, touched, onTouch, mentions = [], mentionLimit = KPT_MENTION_LIMIT, onMention, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const container = useKptOverlayContainer();
     const editorRef = useRef(null);
@@ -105,6 +106,14 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
     const [sourceView, setSourceView] = useState(false);
     const [menuOpen, setMenuOpen] = useState(false);
     const [menuPoint, setMenuPoint] = useState({ x: 0, y: 0 });
+    // ── Wzmianki (`@`) ──
+    const [mentionOpen, setMentionOpen] = useState(false);
+    const [mentionMatches, setMentionMatches] = useState([]);
+    const [mentionActive, setMentionActive] = useState(0);
+    /** Zaczepienie listy w miejscu kursora — punkt, nie element, bo `@` nie ma własnego elementu. */
+    const [mentionPoint, setMentionPoint] = useState({ x: 0, y: 0 });
+    /** Węzeł tekstowy i zakres zapytania `@…`, który podmieni wybrana pozycja. */
+    const mentionRange = useRef(null);
     const [borderOpen, setBorderOpen] = useState(false);
     const [borderTarget, setBorderTarget] = useState('table');
     const [activeCmds, setActiveCmds] = useState(new Set());
@@ -175,13 +184,106 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         selCells.current = new Set();
         setSelCount(0);
     }, []);
+    /** Zamknięcie podpowiedzi — czyści też zapamiętany zakres zapytania. */
+    const closeMention = useCallback(() => {
+        mentionRange.current = null;
+        setMentionMatches([]);
+        setMentionOpen(false);
+    }, []);
+    /** Punkt pod kursorem — lista podpowiedzi zaczepia się o niego, bo `@` nie ma swojego elementu. */
+    const caretPoint = useCallback((node, offset) => {
+        const range = document.createRange();
+        range.setStart(node, Math.min(offset, node.length));
+        range.collapse(true);
+        const rect = range.getBoundingClientRect();
+        // Zwinięty zakres na początku wiersza potrafi dać zerowy prostokąt — wtedy bierzemy
+        // krawędź samego edytora, żeby lista nie wylądowała w rogu ekranu.
+        if (rect.width === 0 && rect.height === 0) {
+            const fallback = editorRef.current?.getBoundingClientRect();
+            return { x: fallback?.left ?? 0, y: fallback?.top ?? 0 };
+        }
+        return { x: rect.left, y: rect.bottom };
+    }, []);
+    /**
+     * Sprawdza, czy kursor stoi w zapytaniu `@…`, i ustawia listę podpowiedzi.
+     *
+     * Zapytanie liczymy z **węzła tekstowego**, nie z całego HTML-a: w treści siedzą tagi, a `@`
+     * ma widzieć tylko to, co użytkownik naprawdę napisał w tym miejscu. Rozpoznanie zostawiamy
+     * `mentionQuery()` z `@konce-pt/mention` — te same reguły działają w obu portach.
+     */
+    const syncMention = useCallback(() => {
+        if (disabled || !mentions.length) {
+            closeMention();
+            return;
+        }
+        const selection = window.getSelection();
+        const node = selection?.anchorNode;
+        if (!selection?.isCollapsed || !(node instanceof Text) || !editorRef.current?.contains(node)) {
+            closeMention();
+            return;
+        }
+        const query = mentionQuery(node.data, selection.anchorOffset);
+        if (!query) {
+            closeMention();
+            return;
+        }
+        const matches = filterMentions(mentions, query.query, mentionLimit);
+        if (!matches.length) {
+            closeMention();
+            return;
+        }
+        mentionRange.current = { node, start: query.start, end: query.end };
+        setMentionMatches(matches);
+        setMentionActive(0);
+        setMentionPoint(caretPoint(node, query.end));
+        setMentionOpen(true);
+    }, [caretPoint, closeMention, disabled, mentionLimit, mentions]);
+    /**
+     * Wstawia wzmiankę w miejsce zapytania `@…`.
+     *
+     * Wzmianka jest elementem, nie samym tekstem: `data-mention` niesie identyfikator, który
+     * przeżyje zmianę nazwy, a `contenteditable="false"` trzyma ją w jednym kawałku — bez tego
+     * kursor wchodziłby w środek nazwiska i psuł zapis. Spacja po wzmiance daje gdzie postawić
+     * kursor: bez niej nie da się wyjść poza element, który nie jest edytowalny.
+     */
+    const insertMention = useCallback((item) => {
+        const target = mentionRange.current;
+        if (!target)
+            return;
+        const range = document.createRange();
+        range.setStart(target.node, target.start);
+        range.setEnd(target.node, Math.min(target.end, target.node.length));
+        range.deleteContents();
+        const element = document.createElement('span');
+        element.className = 'kpt-mention';
+        element.dataset['mention'] = item.id;
+        element.setAttribute('contenteditable', 'false');
+        element.textContent = '@' + item.label;
+        const space = document.createTextNode(' ');
+        range.insertNode(space);
+        range.insertNode(element);
+        const after = document.createRange();
+        after.setStartAfter(space);
+        after.collapse(true);
+        const selection = window.getSelection();
+        selection?.removeAllRanges();
+        selection?.addRange(after);
+        closeMention();
+        pushValue();
+        onMention?.(item);
+    }, [closeMention, onMention, pushValue]);
     // Stan narzędzi zależy od zaznaczenia, a to zmienia się także poza naszymi zdarzeniami
     // (myszą, klawiaturą, przez inne okno), więc nasłuchujemy `selectionchange` na dokumencie.
     useEffect(() => {
-        const onSelectionChange = () => refreshState();
+        const onSelectionChange = () => {
+            refreshState();
+            // Kursor może odjechać od `@` także bez pisania (klik, strzałki) — wtedy podpowiedzi
+            // muszą zniknąć, inaczej Enter wstawiłby wzmiankę w zupełnie innym miejscu.
+            syncMention();
+        };
         document.addEventListener('selectionchange', onSelectionChange);
         return () => document.removeEventListener('selectionchange', onSelectionChange);
-    }, [refreshState]);
+    }, [refreshState, syncMention]);
     // Przeciąganie krawędzi kolumny i zaznaczanie komórek biegną na całym dokumencie: kursor
     // wyjeżdża poza tabelę praktycznie zawsze.
     useEffect(() => {
@@ -344,8 +446,43 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
      * Tab: wcięcie w liście, przeskok komórki w tabeli. Poza nimi i na krawędziach zostawiamy Tab
      * natywny — inaczej edytor byłby pułapką klawiaturową (WCAG 2.1.2).
      */
+    /** Klawiatura listy podpowiedzi; `true` = zdarzenie obsłużone i edytor go już nie zobaczy. */
+    const onMentionKeyDown = (event) => {
+        const count = mentionMatches.length;
+        if (!count)
+            return false;
+        switch (event.key) {
+            case 'ArrowDown':
+                setMentionActive((index) => (index + 1) % count);
+                break;
+            case 'ArrowUp':
+                setMentionActive((index) => (index - 1 + count) % count);
+                break;
+            case 'Enter':
+            case 'Tab': {
+                const item = mentionMatches[mentionActive];
+                if (!item)
+                    return false;
+                insertMention(item);
+                break;
+            }
+            case 'Escape':
+                closeMention();
+                break;
+            default:
+                return false;
+        }
+        event.preventDefault();
+        return true;
+    };
     const onKeyDown = (event) => {
-        if (disabled || event.key !== 'Tab' || event.ctrlKey || event.altKey || event.metaKey)
+        if (disabled)
+            return;
+        // Podpowiedzi wzmianek przechwytują klawiaturę jako pierwsze: Tab i Enter znaczą w nich
+        // co innego niż w samym edytorze.
+        if (mentionOpen && onMentionKeyDown(event))
+            return;
+        if (event.key !== 'Tab' || event.ctrlKey || event.altKey || event.metaKey)
             return;
         if (shiftItems(editorRef.current, event.shiftKey ? 'outdent' : 'indent', maxListLevel)) {
             event.preventDefault();
@@ -570,7 +707,22 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
                                         return (_jsx("button", { ref: setTableAnchor, type: "button", className: cn('kpt-rich-text__tool', tableOpen && 'is-active'), "aria-label": t('richText.table'), title: t('richText.table'), disabled: disabled, onMouseDown: (event) => event.preventDefault(), onClick: () => exec(item), children: _jsx(KptIcon, { name: ICON[item] }) }, item));
                                     }
                                     return toolButton(item);
-                                })] }, index))) }), sourceView ? (_jsx("textarea", { className: "kpt-rich-text__source", value: current, disabled: disabled, spellCheck: false, "aria-label": t('richText.htmlSource'), onChange: (event) => setCurrent(event.target.value), onBlur: () => onTouch?.() })) : (_jsx("div", { ref: editorRef, className: "kpt-rich-text__editor", contentEditable: !disabled, suppressContentEditableWarning: true, "data-placeholder": placeholder, "aria-invalid": showInvalid || undefined, role: "textbox", "aria-multiline": "true", onInput: pushValue, onKeyDown: onKeyDown, onPaste: onPaste, onContextMenu: onContextMenu, onMouseDown: onEditorMouseDown, onMouseMove: onEditorMouseMove, onBlur: () => onTouch?.() }))] }), _jsx(KptOverlay, { open: styleOpen, anchor: styleAnchor, onClose: () => setStyleOpen(false), offset: 4, children: _jsx("ul", { className: "kpt-rich-text__style-panel", role: "listbox", children: styleOptions.map((option) => (_jsx("li", { className: cn(`kpt-rich-text__style-opt kpt-rich-text__style-opt--${option.tag}`, currentBlock === option.tag && 'is-selected'), role: "option", "aria-selected": currentBlock === option.tag, onClick: () => {
+                                })] }, index))) }), sourceView ? (_jsx("textarea", { className: "kpt-rich-text__source", value: current, disabled: disabled, spellCheck: false, "aria-label": t('richText.htmlSource'), onChange: (event) => setCurrent(event.target.value), onBlur: () => onTouch?.() })) : (_jsx("div", { ref: editorRef, className: "kpt-rich-text__editor", contentEditable: !disabled, suppressContentEditableWarning: true, "data-placeholder": placeholder, "aria-invalid": showInvalid || undefined, role: "textbox", "aria-multiline": "true", onInput: () => {
+                            pushValue();
+                            syncMention();
+                        }, onKeyDown: onKeyDown, onPaste: onPaste, onContextMenu: onContextMenu, onMouseDown: onEditorMouseDown, onMouseMove: onEditorMouseMove, onBlur: () => onTouch?.() }))] }), mentionOpen && container
+                ? createPortal(_jsx("ul", { className: "kpt-rt-mentions", role: "listbox", "aria-label": t('richText.mentions'), style: {
+                        position: 'fixed',
+                        left: mentionPoint.x,
+                        top: mentionPoint.y,
+                        zIndex: 'var(--kpt-z-overlay, 1100)',
+                    }, children: mentionMatches.map((item, index) => (_jsxs("li", { className: "kpt-rt-mentions__item", role: "option", "aria-selected": index === mentionActive, "data-active": index === mentionActive ? '' : undefined, onMouseDown: (event) => {
+                            // `mousedown` zamiast `click`: kliknięcie nie może zabrać fokusu edytorowi,
+                            // bo razem z nim zniknąłby zakres, w który wstawiamy wzmiankę.
+                            event.preventDefault();
+                            insertMention(item);
+                        }, onMouseEnter: () => setMentionActive(index), children: [_jsx("span", { className: "kpt-rt-mentions__label", children: item.label }), item.kind ? _jsx("span", { className: "kpt-rt-mentions__kind", children: item.kind }) : null] }, item.id))) }), container)
+                : null, _jsx(KptOverlay, { open: styleOpen, anchor: styleAnchor, onClose: () => setStyleOpen(false), offset: 4, children: _jsx("ul", { className: "kpt-rich-text__style-panel", role: "listbox", children: styleOptions.map((option) => (_jsx("li", { className: cn(`kpt-rich-text__style-opt kpt-rich-text__style-opt--${option.tag}`, currentBlock === option.tag && 'is-selected'), role: "option", "aria-selected": currentBlock === option.tag, onClick: () => {
                             setStyleOpen(false);
                             focusEditor();
                             restoreSelection();

package/dist/rich-text/sanitize.js

@@ -13,7 +13,16 @@ const ALLOWED_STYLES = new Set([
     'color', 'background-color', 'text-align', 'font-weight', 'font-style', 'text-decoration',
     'width', 'height', 'border', 'border-color', 'border-width', 'border-style', 'vertical-align',
 ]);
-const ALLOWED_ATTRS = new Set(['colspan', 'rowspan', 'span', 'width', 'class', 'target', 'rel', 'title']);
+/*
+ * `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.
+ */
+const ALLOWED_ATTRS = new Set([
+    'colspan', 'rowspan', 'span', 'width', 'class', 'target', 'rel', 'title',
+    'data-mention', 'contenteditable',
+]);
 // Schematy dopuszczone w `href` narzędzia „link"; blocklista byłaby obchodzalna.
 const SAFE_URL_SCHEME = /^(https?:|mailto:|tel:)/i;
 const HAS_URL_SCHEME = /^[a-z][a-z0-9+.-]*:/i;

package/dist/roadmap/roadmap.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { buildRows, buildTimeline, linkGeometry, resolveLinks, resolveRange, 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";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptTooltip } from "../tooltip/tooltip.js";
@@ -262,9 +263,6 @@ export function KptRoadmap({ config, scrollHeight = null, labelWidth = '14rem',
                                                     }, 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));
                         })] }))] }) }));
 }
-function isDevBuild() {
-    return typeof process !== 'undefined' && process?.env?.['NODE_ENV'] !== 'production';
-}
 /** Identyfikatory grup zwiniętych deklaratywnie w danych. */
 function declaredCollapsed(groups) {
     return (groups ?? []).filter((group) => group.collapsed).map((group) => group.id);

package/dist/shared/types.d.ts

@@ -3,6 +3,8 @@ export interface KptOption<T = unknown> {
     label: string;
     value: T;
     disabled?: boolean;
+    /** Nazwa ikony z rejestru. Renderuje ją dziś wyłącznie `kpt-button-group`. */
+    icon?: string;
 }
 /** Wariant komunikatu — wspólny dla alertu i toastów. */
 export type KptAlertVariant = 'info' | 'success' | 'warning' | 'danger';