@konce-pt/react 0.11.2 → 0.14.0

package/dist/rating/rating.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
@@ -5,16 +6,19 @@ import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { useKptFieldA11y } from "../form-field/form-field-context.js";
 import { KptIcon } from "../icon/icon.js";
+import { playPopMotion, resolveToggleMotion } from '@konce-pt/motion';
+import { useKptMotion } from "../motion/motion-context.js";
+import { ratingValueAt } from "./rating-pointer.js";
 const fillOf = (star, shown) => shown >= star ? 'full' : shown >= star - 0.5 ? 'half' : 'empty';
 /**
  * Ocena gwiazdkami. Kliknięcie zapalonej gwiazdki zeruje ocenę, więc wystawioną można cofnąć
- * bez osobnego przycisku „wyczyść".
+ * bez osobnego przycisku "wyczyść".
  *
  * Do edycji to grupa radiowa (`role="radiogroup"`, gwiazdki jako `role="radio"`): jeden przystanek
  * Tab, strzałki zmieniają ocenę o krok (w RTL odwrócone w poziomie), `Home`/`End` ustawiają
- * skrajne, `Delete`/`Backspace` zeruje. Z `allowHalf` każda gwiazdka ma dwie połówki — dwa osobne
- * `radio` („3,5 z 5”), a krok strzałek to 0,5. Tylko do odczytu (`readOnly`) to obrazek z nazwą
- * „4,3 z 5” — bez przycisków, które czytnik ogłaszałby jako wyłączone; gwiazdki pokazują wartość
+ * skrajne, `Delete`/`Backspace` zeruje. Z `allowHalf` każda gwiazdka ma dwie połówki - dwa osobne
+ * `radio` ("3,5 z 5"), a krok strzałek to 0,5. Tylko do odczytu (`readOnly`) to obrazek z nazwą
+ * "4,3 z 5" - bez przycisków, które czytnik ogłaszałby jako wyłączone; gwiazdki pokazują wartość
  * zaokrągloną do połówki.
  *
  * @example
@@ -30,17 +34,34 @@ export function KptRating({ value, defaultValue = 0, onValueChange, count = 5, a
     const groupRef = useRef(null);
     /** Prośba o fokus na przystanek Tab po najbliższym renderze (zmiana oceny klawiszem). */
     const wantFocus = useRef(false);
+    /** Ocena przeciągana wskaźnikiem (mysz albo dotyk) - podgląd idzie za palcem, puszczenie zatwierdza. */
+    const [dragging, setDragging] = useState(false);
+    const toggleMotion = resolveToggleMotion(undefined, useKptMotion());
     const showInvalid = invalid && (touched ?? true);
     const stars = Array.from({ length: count }, (_, index) => index + 1);
     const step = allowHalf ? 0.5 : 1;
-    // Podgląd pod kursorem wygrywa z oceną, ale tylko dopóki kursor jest nad gwiazdkami —
+    // Podgląd pod kursorem wygrywa z oceną, ale tylko dopóki kursor jest nad gwiazdkami -
     // po `mouseleave` wraca 0 i zapalona zostaje sama wartość.
     const shown = hover || current;
-    /** Przystanek Tab: wybrana wartość, a bez oceny — pierwsza możliwa. */
+    /** Przystanek Tab: wybrana wartość, a bez oceny - pierwsza możliwa. */
     const tabStop = current >= step && current <= count ? current : step;
-    /** Liczba w zapisie języka strony („3,5” po polsku). */
+    /** Liczba w zapisie języka strony ("3,5" po polsku). */
     const numberFormat = new Intl.NumberFormat(activeLocale, { maximumFractionDigits: 2 });
     const starLabel = (score) => t('rating.star', { value: numberFormat.format(score), max: count });
+    // Gwiazdki, które się zapalają (podgląd pod kursorem, przeciąganie, wybór), wskakują po kolei.
+    // Ruch idzie za globalnym `toggle` z `KptMotionProvider`; start strony się nie rusza.
+    const shownBefore = useRef(null);
+    useEffect(() => {
+        const before = shownBefore.current;
+        shownBefore.current = shown;
+        if (before === null || shown <= before || toggleMotion !== 'spring')
+            return;
+        groupRef.current?.querySelectorAll('.kpt-rating__star').forEach((star, i) => {
+            const n = i + 1;
+            if (n > Math.ceil(before) && n <= Math.ceil(shown))
+                playPopMotion(star);
+        });
+    }, [shown, toggleMotion]);
     useEffect(() => {
         if (!wantFocus.current)
             return;
@@ -50,7 +71,7 @@ export function KptRating({ value, defaultValue = 0, onValueChange, count = 5, a
     const starVisual = (star, fill, children, hidden = false) => (_jsxs("span", { className: "kpt-rating__star", "data-fill": fill, "aria-hidden": hidden || undefined, children: [_jsx(KptIcon, { name: "star" }), _jsx("span", { className: "kpt-rating__fill", "aria-hidden": "true", children: _jsx(KptIcon, { name: "star" }) }), children] }, star));
     if (readOnly) {
         const score = starLabel(current);
-        // Gwiazdki pokazują wartość zaokrągloną do połówki (4,3 → 4,5), nazwa — dokładną.
+        // Gwiazdki pokazują wartość zaokrągloną do połówki (4,3 -> 4,5), nazwa - dokładną.
         const display = Math.round(current * 2) / 2;
         return (_jsx("div", { className: cn('kpt-rating-host', className), ...rest, children: _jsx("div", { className: "kpt-rating kpt-rating--readonly", role: "img", id: field.id, "aria-label": ariaLabel ? `${ariaLabel}: ${score}` : score, "aria-describedby": field.describedBy, children: stars.map((star) => starVisual(star, fillOf(star, display), null, true)) }) }));
     }
@@ -77,7 +98,7 @@ export function KptRating({ value, defaultValue = 0, onValueChange, count = 5, a
         else if (event.key === 'Delete' || event.key === 'Backspace')
             next = 0;
         else if (event.key === ' ' || event.key === 'Enter') {
-            // Spacja na gwiazdce wybiera ją (jak radio); ponowna nie zeruje — od tego jest Delete.
+            // Spacja na gwiazdce wybiera ją (jak radio); ponowna nie zeruje - od tego jest Delete.
             const score = Number(event.target.dataset['value']);
             if (score)
                 next = score;
@@ -88,18 +109,62 @@ export function KptRating({ value, defaultValue = 0, onValueChange, count = 5, a
         setCurrent(next);
         wantFocus.current = true;
     };
-    /** „Dotknięcie” dopiero przy wyjściu fokusu z całej grupy, nie przy przejściu między gwiazdkami. */
+    /**
+     * Przeciąganie po gwiazdkach. Krótkie wciśnięcie bez ruchu zostawia sprawę kliknięciu (zachowanie
+     * jak dotąd, łącznie z ponownym kliknięciem zerującym); ruch o kilka pikseli zamienia gest w wybór
+     * przeciąganiem - także dotykiem, gdzie nie ma podglądu na `mouseenter`.
+     */
+    const onPointerDown = (event) => {
+        if (disabled || event.button !== 0)
+            return;
+        const root = event.currentTarget;
+        const startX = event.clientX;
+        let active = false;
+        const valueAt = (x) => ratingValueAt(x, Array.from(root.querySelectorAll('.kpt-rating__star'), (el) => el.getBoundingClientRect()), { allowHalf, rtl: getComputedStyle(root).direction === 'rtl' });
+        const move = (e) => {
+            if (!active && Math.abs(e.clientX - startX) < 4)
+                return;
+            if (!active) {
+                active = true;
+                setDragging(true);
+                root.setPointerCapture(e.pointerId);
+            }
+            setHover(valueAt(e.clientX));
+        };
+        const up = (e) => {
+            root.removeEventListener('pointermove', move);
+            root.removeEventListener('pointerup', up);
+            root.removeEventListener('pointercancel', up);
+            if (!active)
+                return;
+            setDragging(false);
+            // Klik po przeciągnięciu jest skutkiem tego samego gestu - nie może drugi raz przestawić oceny.
+            // Połykamy go w fazie capture; nasłuch znika w następnej klatce, gdyby klik nie przyszedł.
+            const swallow = (ev) => ev.stopPropagation();
+            root.addEventListener('click', swallow, { capture: true, once: true });
+            requestAnimationFrame(() => root.removeEventListener('click', swallow, { capture: true }));
+            const score = valueAt(e.clientX);
+            setCurrent(score);
+            // Mysz zostaje nad gwiazdkami - podgląd i tak zgadza się z wyborem; palec odchodzi, więc czyścimy.
+            setHover(e.pointerType === 'mouse' ? score : 0);
+            onTouch?.();
+        };
+        root.addEventListener('pointermove', move);
+        root.addEventListener('pointerup', up);
+        root.addEventListener('pointercancel', up);
+    };
+    /** "Dotknięcie" dopiero przy wyjściu fokusu z całej grupy, nie przy przejściu między gwiazdkami. */
     const onBlur = (event) => {
         const next = event.relatedTarget;
         if (!next || !event.currentTarget.contains(next))
             onTouch?.();
     };
-    /** Pola wyboru jednej gwiazdki: całość albo — z `allowHalf` — dwie połówki. */
+    /** Pola wyboru jednej gwiazdki: całość albo - z `allowHalf` - dwie połówki. */
     const optionsOf = (star) => allowHalf
         ? [
             { score: star - 0.5, part: 'start' },
             { score: star, part: 'end' },
         ]
         : [{ score: star, part: 'full' }];
-    return (_jsx("div", { className: cn('kpt-rating-host', className), ...rest, children: _jsx("div", { ref: groupRef, className: cn('kpt-rating', disabled && 'kpt-rating--disabled'), role: "radiogroup", id: field.id, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, "aria-required": required || undefined, "aria-invalid": showInvalid || undefined, "aria-disabled": disabled || undefined, onKeyDown: onKeyDown, onBlur: onBlur, onMouseLeave: () => setHover(0), children: stars.map((star) => starVisual(star, fillOf(star, shown), optionsOf(star).map((option) => (_jsx("button", { type: "button", role: "radio", className: cn('kpt-rating__hit', `kpt-rating__hit--${option.part}`), "aria-checked": option.score === current, tabIndex: !disabled && option.score === tabStop ? 0 : -1, "aria-disabled": disabled || undefined, "data-value": option.score, "aria-label": starLabel(option.score), onClick: () => pick(option.score), onMouseEnter: () => !disabled && setHover(option.score) }, option.part))))) }) }));
+    return (_jsx("div", { className: cn('kpt-rating-host', className), ...rest, children: _jsx("div", { ref: groupRef, className: cn('kpt-rating', disabled && 'kpt-rating--disabled', dragging && 'is-dragging'), role: "radiogroup", id: field.id, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, "aria-required": required || undefined, "aria-invalid": showInvalid || undefined, "aria-disabled": disabled || undefined, onKeyDown: onKeyDown, onBlur: onBlur, onMouseLeave: () => !dragging && setHover(0), onPointerDown: onPointerDown, children: stars.map((star) => starVisual(star, fillOf(star, shown), optionsOf(star).map((option) => (_jsx("button", { type: "button", role: "radio", className: cn('kpt-rating__hit', `kpt-rating__hit--${option.part}`), "aria-checked": option.score === current, tabIndex: !disabled && option.score === tabStop ? 0 : -1, "aria-disabled": disabled || undefined, "data-value": option.score, "aria-label": starLabel(option.score), onClick: () => pick(option.score), onMouseEnter: () => !disabled && setHover(option.score) }, option.part))))) }) }));
 }

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

@@ -6,11 +6,11 @@ export declare function canIndentItem(editor: HTMLElement | null, li: HTMLLIElem
 export declare function canOutdentItem(li: HTMLLIElement): boolean;
 /**
  * Punkty listy objęte zaznaczeniem. Przy wielu punktach operujemy na ich wspólnym poziomie
- * zagnieżdżenia — inaczej podpunkt dostałby wcięcie dwa razy: raz sam, raz z rodzicem.
+ * zagnieżdżenia - inaczej podpunkt dostałby wcięcie dwa razy: raz sam, raz z rodzicem.
  */
 export declare function selectedItems(editor: HTMLElement | null): HTMLLIElement[];
 /**
- * Przesuwa zaznaczone punkty o poziom. Zwraca `true`, gdy DOM faktycznie się zmienił — od tego
+ * Przesuwa zaznaczone punkty o poziom. Zwraca `true`, gdy DOM faktycznie się zmienił - od tego
  * zależy, czy Tab dostanie `preventDefault()`, a więc czy edytor nie stanie się pułapką
  * klawiaturową (WCAG 2.1.2).
  */

package/dist/rich-text/lists.js

@@ -1,7 +1,7 @@
 /*
  * Wcięcia list. `execCommand('indent')` daje w Chrome nieprawidłowe `ul > ul` (albo `blockquote`
  * z marginesem, który i tak zdjąłby sanitizer), więc zagnieżdżanie robimy własnym kodem DOM.
- * Plik nie zna Reacta — to czyste operacje na węzłach.
+ * Plik nie zna Reacta - to czyste operacje na węzłach.
  */
 /** Najbliższy punkt listy zawierający węzeł, ale tylko wewnątrz edytora. */
 export function closestItem(editor, node) {
@@ -19,7 +19,7 @@ export function level(editor, li) {
     }
     return depth;
 }
-/** Najgłębszy poziom w poddrzewie punktu — wcięcie przenosi podpunkty razem z rodzicem. */
+/** Najgłębszy poziom w poddrzewie punktu - wcięcie przenosi podpunkty razem z rodzicem. */
 function deepest(editor, li) {
     let max = level(editor, li);
     for (const nested of li.querySelectorAll('li')) {
@@ -35,7 +35,7 @@ export function canOutdentItem(li) {
 }
 /**
  * Punkty listy objęte zaznaczeniem. Przy wielu punktach operujemy na ich wspólnym poziomie
- * zagnieżdżenia — inaczej podpunkt dostałby wcięcie dwa razy: raz sam, raz z rodzicem.
+ * zagnieżdżenia - inaczej podpunkt dostałby wcięcie dwa razy: raz sam, raz z rodzicem.
  */
 export function selectedItems(editor) {
     const selection = window.getSelection();
@@ -68,7 +68,7 @@ export function selectedItems(editor) {
         return [start];
     return siblings.slice(Math.min(from, to), Math.max(from, to) + 1);
 }
-/** Zagnieżdża punkt w podliście poprzedniego punktu — poprawne `li > ul > li`. */
+/** Zagnieżdża punkt w podliście poprzedniego punktu - poprawne `li > ul > li`. */
 function indentItem(editor, li, maxLevel) {
     if (!canIndentItem(editor, li, maxLevel))
         return false;
@@ -104,7 +104,7 @@ function outdentItem(li) {
     return true;
 }
 /**
- * Przesuwa zaznaczone punkty o poziom. Zwraca `true`, gdy DOM faktycznie się zmienił — od tego
+ * Przesuwa zaznaczone punkty o poziom. Zwraca `true`, gdy DOM faktycznie się zmienił - od tego
  * zależy, czy Tab dostanie `preventDefault()`, a więc czy edytor nie stanie się pułapką
  * klawiaturową (WCAG 2.1.2).
  */
@@ -119,7 +119,7 @@ export function shiftItems(editor, dir, maxLevel) {
     const caret = range
         ? { sc: range.startContainer, so: range.startOffset, ec: range.endContainer, eo: range.endOffset }
         : null;
-    // Outdent od końca — inaczej `host.after()` odwróciłby kolejność przenoszonych punktów.
+    // Outdent od końca - inaczej `host.after()` odwróciłby kolejność przenoszonych punktów.
     const order = dir === 'outdent' ? [...items].reverse() : items;
     let changed = false;
     for (const li of order) {
@@ -137,7 +137,7 @@ export function shiftItems(editor, dir, maxLevel) {
             selection.addRange(restored);
         }
         catch {
-            /* offset przestał pasować po przeniesieniu rodzeństwa — zostaw kursor tam, gdzie jest */
+            /* offset przestał pasować po przeniesieniu rodzeństwa - zostaw kursor tam, gdzie jest */
         }
     }
     return true;

package/dist/rich-text/llms.txt

@@ -5,24 +5,24 @@ editing. The value is HTML.
 Import: `import { KptRichText, type KptRichTool } from '@konce-pt/react';`
 
 ## Props
-- `value` / `defaultValue` / `onValueChange` — the HTML
-- `toolbar`: `KptRichTool[] | KptRichTool[][]` — a flat list, or groups = sections separated by a
+- `value` / `defaultValue` / `onValueChange` - the HTML
+- `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
+- `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.
+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).
+Clipboard: `copy`, `paste` (sanitized), `pasteText`. Style: `heading` (a panel: Normal + H1-H6).
 Format: `bold`, `italic`, `underline`, `strike`, `ul`, `ol`, `indent`, `outdent`.
 Colours: `foreColor`, `backColor` (a palette + a native colour input). Alignment: `alignLeft`,
 `alignCenter`, `alignRight`, `alignJustify`. Plus `link`, `table`, `clear`, `html`.
@@ -30,32 +30,43 @@ Colours: `foreColor`, `backColor` (a palette + a native colour input). Alignment
 ## The editor is not rendered by React
 `contentEditable` cannot be a React-rendered subtree: re-rendering would wipe the selection and the
 caret on every keystroke. The value is written into the DOM by hand, only when it differs from what
-is already there — so typing never triggers a rewrite, and sanitization runs solely on writes
+is already there - so typing never triggers a rewrite, and sanitization runs solely on writes
 coming from the application or the HTML source view.
 
 ## Everything that enters the DOM is sanitized
 Not just paste: a `value` from a database, a CMS or another user is untrusted too. Tags outside the
 allowlist are unwrapped (the text survives), `on*` handlers and `javascript:` URLs are dropped,
 `style` is filtered declaration by declaration. `sanitize.ts` knows nothing about React.
+Links keep only relative addresses and `http(s):`, `mailto:`, `tel:` - the same allowlist as the link tool, so
+`data:`, `vbscript:` or `blob:` from a paste are dropped. `class` keeps only the editor's own classes
+(`kpt-rt-*`, `kpt-mention`), a link with `target` always gets `rel="noopener noreferrer"`, and when the
+sanitizer removed something, the cleaned HTML is written back to `value` - the model never holds the
+unsafe original (a pure formatting difference does not touch it, so a clean value does not dirty a form).
 
 ## Lists are indented by our own DOM code
 `execCommand('indent')` produces invalid `ul > ul` in Chrome, so nesting goes through `lists.ts`
 (`li > ul > li`, a sublist inherits the parent's type). Tab and Shift+Tab indent and outdent, but
-only when the operation actually changed something — otherwise Tab stays native and the editor
+only when the operation actually changed something - otherwise Tab stays native and the editor
 never becomes a keyboard trap (WCAG 2.1.2). In a table cell Tab moves to the next cell; a list
 inside the cell takes precedence.
 
 ## The toolbar is one Tab stop
 The toolbar is a named `role="toolbar"` ("Formatting", `richText.toolbar`) with a roving tabindex:
-`←`/`→` (mirrored in RTL) and `Home`/`End` move between tools, skipping disabled ones; the stop
+`ArrowLeft`/`ArrowRight` (mirrored in RTL) and `Home`/`End` move between tools, skipping disabled ones; the stop
 remembers the last tool, so Tab from the toolbar goes straight to the editor.
 
+Tool panels open in the overlay container at the end of `<body>`, so focus moves into them:
+the paragraph style list is a `listbox` (`ArrowUp`/`ArrowDown`, `Home`/`End`, `Enter`/`Space` picks, `Escape`/`Tab` close);
+the table grid is one stop (arrows change the size 1-8, the size is announced, `Enter` inserts);
+the colour palette starts on the first swatch (`ArrowLeft`/`ArrowRight` between swatches, `Tab` cycles inside the
+panel). `Escape` closes any of them and returns focus to the tool.
+
 ## Tables
-Insert from an 8×8 grid popover. Dragging across cells makes a rectangular selection that grows
+Insert from an 8x8 grid popover. Dragging across cells makes a rectangular selection that grows
 until it fully covers merged cells on its edges. Right-click opens the menu: insert and delete rows
-and columns, header row and column (td↔th), cell background, alignment, borders, merge and split,
+and columns, header row and column (td<->th), cell background, alignment, borders, merge and split,
 delete the table. Dragging a column's right edge changes its width. `tables.ts` holds the grid
-math — also framework-free.
+math - also framework-free.
 
 ## Point-anchored panels
 The table menu and its popovers have no trigger element, so they do not go through `KptOverlay`:
@@ -87,5 +98,17 @@ their hex codes. The table size grid is still mouse-only.
 `id` goes to the focusable element, not the host; without one it comes from `KptFormField` or is
 generated. A `div` with a role is not named by `label[for]`, so inside `KptFormField` it gets
 `aria-labelledby` pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error
-is added to `aria-describedby`. New: `id`, `ariaLabel` and `required` (→ `aria-required`) on the
+is added to `aria-describedby`. New: `id`, `ariaLabel` and `required` (-> `aria-required`) on the
 `role="textbox"` area.
+
+## Read-only and required
+`readOnly` keeps the content selectable and copyable but not editable (`aria-readonly`); the toolbar is disabled.
+
+## Dictation
+The `dictate` tool (not in the default toolbar) dictates at the caret: final text goes in through
+`insertText` (native undo, `input` -> value); interim text is an overlay next to the caret
+(`.kpt-speech-ghost`) and never enters the HTML. Hidden without browser support, stopped by the HTML
+source view and by `disabled` / `readOnly`. Language: `speechLang` (BCP 47, default from
+`KptI18nProvider`), listening colour: `speechColor` (theme colour by default).
+
+    <KptRichText value={body} onValueChange={setBody} toolbar={[['bold', 'italic'], ['dictate']]} />

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

@@ -1,8 +1,9 @@
 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. */
+import { type KptSpeechColor } from '../speech/speech-button.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' | 'dictate';
+/** Pasek: płaska lista narzędzi albo grupy - sekcje rozdzielone separatorem. */
 export type KptRichToolbar = readonly KptRichTool[] | readonly (readonly KptRichTool[])[];
 export interface KptRichTextProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'children'>, KptI18nOverrides {
     /** Wartość jako HTML. */
@@ -11,15 +12,17 @@ export interface KptRichTextProps extends Omit<ComponentPropsWithRef<'div'>, 'on
     onValueChange?: (value: string) => void;
     toolbar?: KptRichToolbar;
     placeholder?: string;
-    /** Maksymalna głębokość zagnieżdżenia list (Tab, „Dodaj wcięcie"). */
+    /** Maksymalna głębokość zagnieżdżenia list (Tab, "Dodaj wcięcie"). */
     maxListLevel?: number;
-    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    /** Id elementu fokusowalnego (nie hosta); bez niego generowane, w `KptFormField` - z wrappera. */
     id?: string;
     /** Nazwa dostępna, gdy kontrolki nie opisuje etykieta (`<label for>` albo `KptFormField`). */
     ariaLabel?: string | null;
     /** Oznacza pole jako wymagane atrybutem `aria-required`. */
     required?: boolean;
     disabled?: boolean;
+    /** Tylko do odczytu - treść da się zaznaczyć i skopiować, nie edytować (`aria-readonly`). */
+    readOnly?: boolean;
     invalid?: boolean;
     touched?: boolean;
     onTouch?: () => void;
@@ -30,15 +33,11 @@ export interface KptRichTextProps extends Omit<ComponentPropsWithRef<'div'>, 'on
     mentions?: readonly KptMentionItem[];
     /** Ile podpowiedzi naraz. */
     mentionLimit?: number;
-    /** Wstawiona wzmianka — moment na powiadomienie osoby albo dopięcie powiązania. */
+    /** Wstawiona wzmianka - moment na powiadomienie osoby albo dopięcie powiązania. */
     onMention?: (item: KptMentionItem) => void;
+    /** Język narzędzia `dictate` (BCP 47); bez niego z `KptI18nProvider`. */
+    speechLang?: string;
+    /** Kolor "stop" i fali w trakcie nasłuchu; domyślnie kolor motywu. */
+    speechColor?: KptSpeechColor;
 }
-/**
- * Lekki edytor tekstu sformatowanego na `contenteditable`, z konfigurowalnym paskiem sekcji
- * i edycją tabel. Wartością jest HTML.
- *
- * @example
- * <KptRichText value={html} onValueChange={setHtml} />
- * <KptRichText value={html} onValueChange={setHtml} toolbar={[['bold', 'italic'], ['link']]} />
- */
-export declare function KptRichText({ value, defaultValue, onValueChange, toolbar, placeholder, maxListLevel, id, ariaLabel, required, disabled, invalid, touched, onTouch, mentions, mentionLimit, onMention, locale, dictionary, className, ...rest }: Readonly<KptRichTextProps>): import("react").JSX.Element;
+export declare function KptRichText({ value, defaultValue, onValueChange, toolbar, placeholder, maxListLevel, id, ariaLabel, required, disabled: disabledProp, readOnly, invalid, touched, onTouch, mentions, mentionLimit, onMention, speechLang, speechColor, locale, dictionary, className, ...rest }: Readonly<KptRichTextProps>): import("react").JSX.Element;