@konce-pt/react 0.12.0 → 0.15.0

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,43 +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
+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
+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` (`↑`/`↓`, `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 (`←`/`→` between swatches, `Tab` cycles inside the
+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`:
@@ -98,8 +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,16 +12,16 @@ 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`). */
+    /** Tylko do odczytu - treść da się zaznaczyć i skopiować, nie edytować (`aria-readonly`). */
     readOnly?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -32,7 +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;
 }
-export declare function KptRichText({ value, defaultValue, onValueChange, toolbar, placeholder, maxListLevel, id, ariaLabel, required, disabled: disabledProp, readOnly, 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;

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

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState, } from 'react';
+import { useCallback, useEffect, useEffectEvent, useRef, useState, } from 'react';
 import { createPortal } from 'react-dom';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
@@ -9,6 +9,8 @@ import { useKptOverlayContainer } from "../internal/overlay-container.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
+import { KptSpeechButton } from "../speech/speech-button.js";
+import { useKptSpeechRecognition } from "../speech/use-speech-recognition.js";
 import { sanitizeHtml, sanitizeHtmlReport, sanitizeUrl } from "./sanitize.js";
 import { canIndentItem, canOutdentItem, selectedItems, shiftItems } from "./lists.js";
 import { CELL_SELECTED, deleteColumn, deleteRow, insertColumn, insertRow, mergeCells, regionBetween, splitCell, tableHtml, toggleHeaderColumn, toggleHeaderRow, } from "./tables.js";
@@ -20,7 +22,7 @@ const ICON = {
     copy: 'copy',
     paste: 'clipboard',
     pasteText: 'clipboard-text',
-    heading: 'code', // nieużywane — „heading" renderuje select
+    heading: 'code', // nieużywane - "heading" renderuje select
     bold: 'bold',
     italic: 'italic',
     underline: 'underline',
@@ -39,8 +41,9 @@ const ICON = {
     table: 'table',
     clear: 'clear-formatting',
     html: 'code',
+    dictate: 'microphone', // nieużywane - "dictate" renderuje KptSpeechButton
 };
-/** Narzędzia zwykłe → komenda `execCommand` (zarazem nazwa dla `queryCommandState`). */
+/** Narzędzia zwykłe -> komenda `execCommand` (zarazem nazwa dla `queryCommandState`). */
 const COMMAND = {
     bold: 'bold',
     italic: 'italic',
@@ -54,7 +57,7 @@ const COMMAND = {
     alignJustify: 'justifyFull',
     clear: 'removeFormat',
 };
-/** Paleta kolorów z nazwami (`richText.swatches.*`) — sam kod szesnastkowy nic czytnikowi nie mówi. */
+/** Paleta kolorów z nazwami (`richText.swatches.*`) - sam kod szesnastkowy nic czytnikowi nie mówi. */
 const SWATCHES = [
     { color: '#000000', name: 'black' },
     { color: '#434343', name: 'darkGray' },
@@ -98,10 +101,10 @@ function legacyState(cmd) {
         return false;
     }
 }
-export function KptRichText({ value, defaultValue = '', onValueChange, toolbar = DEFAULT_TOOLBAR, placeholder = '', maxListLevel = 6, id, ariaLabel = null, required = false, disabled: disabledProp = false, readOnly = false, invalid = false, touched, onTouch, mentions = [], mentionLimit = KPT_MENTION_LIMIT, onMention, locale, dictionary, className, ...rest }) {
-    /** Edycja zablokowana: wyłączone pole albo tylko do odczytu — narzędzia i skróty nie działają. */
+export function KptRichText({ value, defaultValue = '', onValueChange, toolbar = DEFAULT_TOOLBAR, placeholder = '', maxListLevel = 6, id, ariaLabel = null, required = false, disabled: disabledProp = false, readOnly = false, invalid = false, touched, onTouch, mentions = [], mentionLimit = KPT_MENTION_LIMIT, onMention, speechLang, speechColor, locale, dictionary, className, ...rest }) {
+    /** Edycja zablokowana: wyłączone pole albo tylko do odczytu - narzędzia i skróty nie działają. */
     const disabled = disabledProp || readOnly;
-    /** `contenteditable` nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
+    /** `contenteditable` nie dostaje nazwy z `label[for]` - stąd `aria-labelledby` na etykietę wrappera. */
     const field = useKptFieldA11y(id, 'kpt-rich-text');
     const { t } = useKptMessages({ locale, dictionary });
     const container = useKptOverlayContainer();
@@ -109,7 +112,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
     const savedRange = useRef(null);
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const showInvalid = invalid && (touched ?? true);
-    // Kotwice narzędzi z panelem — `KptOverlay` przypina panel do konkretnego przycisku.
+    // Kotwice narzędzi z panelem - `KptOverlay` przypina panel do konkretnego przycisku.
     const [styleAnchor, setStyleAnchor] = useState(null);
     const [foreAnchor, setForeAnchor] = useState(null);
     const [backAnchor, setBackAnchor] = useState(null);
@@ -118,10 +121,10 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
     /** Okienko adresu linku (zamiast `window.prompt()`) i wpisywany adres. */
     const [linkOpen, setLinkOpen] = useState(false);
     const [linkDraft, setLinkDraft] = useState('');
-    /** Menu tabeli otwarte z klawiatury — po zamontowaniu fokus idzie na pierwszą pozycję. */
+    /** Menu tabeli otwarte z klawiatury - po zamontowaniu fokus idzie na pierwszą pozycję. */
     const menuFromKeyboard = useRef(false);
     const [styleOpen, setStyleOpen] = useState(false);
-    /** Narzędzie, na którym ostatnio stał fokus paska — przystanek Tab przy powrocie. */
+    /** Narzędzie, na którym ostatnio stał fokus paska - przystanek Tab przy powrocie. */
     const [lastTool, setLastTool] = useState(null);
     const [colorOpen, setColorOpen] = useState(false);
     const [colorKind, setColorKind] = useState('foreColor');
@@ -132,13 +135,13 @@ 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 (`@`) ──
+    // -- 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. */
+    /** 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. */
+    /** 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');
@@ -158,6 +161,18 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         : Array.isArray(toolbar[0])
             ? toolbar
             : [toolbar];
+    // -- Dyktowanie (narzędzie `dictate`) --
+    // Cel to sam obszar edycji: tekst zatwierdzony wchodzi przez `insertText` w miejsce kursora
+    // (natywne undo, zdarzenie `input` -> wartość), tymczasowy jest nakładką przy kursorze i nie trafia
+    // do HTML-a. Bez narzędzia w pasku kontroler nie tworzy sesji.
+    const hasDictate = sections.some((section) => section.includes('dictate'));
+    const mic = useKptSpeechRecognition({ enabled: hasDictate, target: editorRef, lang: speechLang, disabled });
+    // Widok źródła zdejmuje obszar edycji, a blokada zabrania pisania - dyktowanie przerywamy.
+    const stopDictation = useEffectEvent(() => mic.abort());
+    useEffect(() => {
+        if (sourceView || disabled)
+            stopDictation();
+    }, [sourceView, disabled]);
     const pushValue = useCallback(() => {
         const el = editorRef.current;
         if (el)
@@ -165,10 +180,10 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
     }, [setCurrent]);
     /*
      * Zapis z zewnątrz wstawiamy ręcznie, bo `contenteditable` nie może być renderowany przez
-     * Reacta — przerysowanie kasowałoby zaznaczenie i pozycję kursora przy każdym znaku.
+     * Reacta - przerysowanie kasowałoby zaznaczenie i pozycję kursora przy każdym znaku.
      * Porównanie z surowym `innerHTML` sprawia, że pisanie w edytorze nie wchodzi w tę gałąź,
      * więc sanityzacja włącza się wyłącznie przy zapisie z aplikacji albo z trybu HTML. Gdy
-     * sanityzator coś usunął, oczyszczona treść wraca też do wartości — inaczej aplikacja dostawałaby
+     * sanityzator coś usunął, oczyszczona treść wraca też do wartości - inaczej aplikacja dostawałaby
      * z powrotem niebezpieczny HTML. Sama różnica zapisu (cudzysłowy) wartości nie rusza.
      */
     useEffect(() => {
@@ -185,7 +200,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         const selection = window.getSelection();
         return !!el && !!selection && selection.rangeCount > 0 && el.contains(selection.anchorNode);
     }, []);
-    /** Tag bloku, w którym stoi kursor — dla selecta stylu; domyślnie paragraf. */
+    /** Tag bloku, w którym stoi kursor - dla selecta stylu; domyślnie paragraf. */
     const blockTag = useCallback(() => {
         let node = window.getSelection()?.anchorNode;
         while (node && node !== editorRef.current) {
@@ -216,19 +231,19 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         selCells.current = new Set();
         setSelCount(0);
     }, []);
-    /** Zamknięcie podpowiedzi — czyści też zapamiętany zakres zapytania. */
+    /** 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. */
+    /** 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
+        // 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();
@@ -237,11 +252,11 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         return { x: rect.left, y: rect.bottom };
     }, []);
     /**
-     * Sprawdza, czy kursor stoi w zapytaniu `@…`, i ustawia listę podpowiedzi.
+     * 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.
+     * `mentionQuery()` z `@konce-pt/mention` - te same reguły działają w obu portach.
      */
     const syncMention = useCallback(() => {
         if (disabled || !mentions.length) {
@@ -271,10 +286,10 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         setMentionOpen(true);
     }, [caretPoint, closeMention, disabled, mentionLimit, mentions]);
     /**
-     * Wstawia wzmiankę w miejsce zapytania `@…`.
+     * 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
+     * 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.
      */
@@ -309,7 +324,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
     useEffect(() => {
         const onSelectionChange = () => {
             refreshState();
-            // Kursor może odjechać od `@` także bez pisania (klik, strzałki) — wtedy podpowiedzi
+            // 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();
         };
@@ -374,7 +389,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
             selection.addRange(savedRange.current);
         }
     };
-    // ── Schowek ──
+    // -- Schowek --
     const copySelection = async () => {
         const selection = window.getSelection();
         if (!selection || selection.rangeCount === 0 || selection.isCollapsed)
@@ -411,7 +426,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
             pushValue();
         }
         catch {
-            /* brak uprawnień albo API — ignorujemy */
+            /* brak uprawnień albo API - ignorujemy */
         }
     };
     const pastePlain = async () => {
@@ -422,10 +437,10 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
             pushValue();
         }
         catch {
-            /* brak uprawnień albo API — ignorujemy */
+            /* brak uprawnień albo API - ignorujemy */
         }
     };
-    // ── Narzędzia ──
+    // -- Narzędzia --
     const exec = (item) => {
         if (disabled)
             return;
@@ -470,7 +485,7 @@ 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).
+     * 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) => {
@@ -531,7 +546,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         const cells = [...table.querySelectorAll('td, th')];
         const next = cells[cells.indexOf(cell) + (event.shiftKey ? -1 : 1)];
         if (!next)
-            return; // koniec tabeli — Tab zostaje natywny
+            return; // koniec tabeli - Tab zostaje natywny
         event.preventDefault();
         const range = document.createRange();
         range.selectNodeContents(next);
@@ -541,7 +556,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         clearCellSelection();
         refreshState();
     };
-    /** Natywne wklejanie — czyścimy treść, żeby nie wnosić śmieci z edytorów tekstu i stron. */
+    /** Natywne wklejanie - czyścimy treść, żeby nie wnosić śmieci z edytorów tekstu i stron. */
     const onPaste = (event) => {
         if (disabled)
             return;
@@ -554,7 +569,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
             legacyExec('insertText', text);
         pushValue();
     };
-    // ── Kolory ──
+    // -- Kolory --
     const activeCells = () => {
         if (selCells.current.size)
             return [...selCells.current];
@@ -576,7 +591,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
             legacyExec('backColor', color);
         pushValue();
     };
-    // ── Tabele ──
+    // -- Tabele --
     const pickStyle = (tag) => {
         setStyleOpen(false);
         focusEditor();
@@ -585,7 +600,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         pushValue();
         refreshState();
     };
-    /** Siatka tabeli z klawiatury: strzałki zmieniają rozmiar (1–8), Enter wstawia, Escape wraca. */
+    /** Siatka tabeli z klawiatury: strzałki zmieniają rozmiar (1-8), Enter wstawia, Escape wraca. */
     const onGridKeyDown = (event) => {
         const clamp = (n) => Math.min(GRID_ROWS.length, Math.max(1, n));
         const r = grid.r || 1;
@@ -621,7 +636,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
     const afterTableOp = () => {
         const fromMenu = !!document.activeElement?.closest('.kpt-rt-menu');
         setMenuOpen(false);
-        // Pozycja wybrana z klawiatury znika razem z menu — fokus wraca do edytora, nie na <body>.
+        // Pozycja wybrana z klawiatury znika razem z menu - fokus wraca do edytora, nie na <body>.
         if (fromMenu)
             focusEditor();
         pushValue();
@@ -637,7 +652,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         if (handleMenuKeydown(event.currentTarget, event.nativeEvent) === 'close')
             closeMenuToEditor();
     };
-    /** Menu tabeli z klawiatury: klawisz menu albo `Shift+F10` w komórce — jak natywne menu kontekstowe. */
+    /** Menu tabeli z klawiatury: klawisz menu albo `Shift+F10` w komórce - jak natywne menu kontekstowe. */
     const openMenuFromKeyboard = () => {
         const node = window.getSelection()?.anchorNode ?? null;
         const el = node instanceof Element ? node : (node?.parentElement ?? null);
@@ -653,7 +668,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         setMenuOpen(true);
         return true;
     };
-    /** Okienko adresu zamiast `window.prompt()` — nazwane pole, `Enter` wstawia, `Escape` wraca do tekstu. */
+    /** Okienko adresu zamiast `window.prompt()` - nazwane pole, `Enter` wstawia, `Escape` wraca do tekstu. */
     const openLink = () => {
         if (disabled)
             return;
@@ -753,7 +768,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         }
         pushValue();
     };
-    // ── Prezentacja narzędzi ──
+    // -- Prezentacja narzędzi --
     const styleOptions = [
         { tag: 'p', label: t('richText.styleNormal') },
         ...[1, 2, 3, 4, 5, 6].map((level) => ({
@@ -768,17 +783,19 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         const cmd = COMMAND[item];
         return !!cmd && activeCmds.has(cmd);
     };
-    /** `aria-pressed` tylko dla przełączników — wcięcia są akcjami, nie stanem. */
+    /** `aria-pressed` tylko dla przełączników - wcięcia są akcjami, nie stanem. */
     const pressed = (item) => item === 'indent' || item === 'outdent' ? undefined : isActive(item);
     const enabled = (item) => {
         if (item === 'indent')
             return canIndent;
         if (item === 'outdent')
             return canOutdent;
+        if (item === 'dictate')
+            return mic.available && !sourceView;
         return true;
     };
     /**
-     * Panele narzędzi żyją w nakładce na końcu `<body>` — po zamontowaniu fokus wchodzi do środka,
+     * Panele narzędzi żyją w nakładce na końcu `<body>` - po zamontowaniu fokus wchodzi do środka,
      * inaczej Tab musiałby przejść przez całą stronę, żeby do nich dojść (WCAG 2.1.1).
      */
     // Refy stabilne (`useCallback`): nowa funkcja przy każdym renderze byłaby wołana od nowa
@@ -826,7 +843,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
     };
     const paletteContent = (_jsxs("div", { ref: focusSwatchOnMount, className: "kpt-rich-text__palette", role: "group", "aria-label": t(colorKind === 'backColor' ? 'richText.backColor' : 'richText.foreColor'), onMouseDown: (event) => event.preventDefault(), onKeyDown: onPaletteKeyDown, children: [_jsx("div", { className: "kpt-rich-text__swatches", children: SWATCHES.map((swatch) => (_jsx("button", { type: "button", className: "kpt-rich-text__swatch", style: { background: swatch.color }, "aria-label": t(`richText.swatches.${swatch.name}`), onClick: () => applyColor(swatch.color) }, swatch.color))) }), _jsxs("label", { className: "kpt-rich-text__picker", children: [_jsx("span", { children: t('richText.paletteCustom') }), _jsx("input", { type: "color", onInput: (event) => applyColor(event.target.value) })] })] }));
     /**
-     * Panel otwarty przy dolnej albo prawej krawędzi okna wychodziłby poza ekran — CDK robił to
+     * Panel otwarty przy dolnej albo prawej krawędzi okna wychodziłby poza ekran - CDK robił to
      * w Angularze sam, tutaj przesuwamy go po zamontowaniu, gdy już znać jego rozmiar.
      */
     const clampToViewport = (el) => {
@@ -839,13 +856,13 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
         el.style.top = `${top}px`;
     };
     /**
-     * Panel przypięty do punktu kursora — menu tabeli i jego popovery nie mają wyzwalacza, więc
+     * Panel przypięty do punktu kursora - menu tabeli i jego popovery nie mają wyzwalacza, więc
      * nie przechodzą przez `KptOverlay`; pozycję niosą współrzędne kliknięcia, tak jak
      * w `KptContextMenu`.
      */
     const pointPanel = (content, onClose) => {
         if (!container)
-            return null; // render na serwerze — nie ma czego portalować
+            return null; // render na serwerze - nie ma czego portalować
         const layer = { zIndex: 'var(--kpt-z-overlay, 1100)' };
         return createPortal(_jsxs(_Fragment, { children: [_jsx("div", { style: { position: 'fixed', inset: 0, ...layer }, onClick: onClose, onContextMenu: (event) => {
                         event.preventDefault();
@@ -853,33 +870,35 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
                     } }), _jsx("div", { ref: clampToViewport, style: { position: 'fixed', left: menuPoint.x, top: menuPoint.y, ...layer }, children: content })] }), container);
     };
     /**
-     * Przystanek Tab paska: ostatnio użyte narzędzie, a gdy jest wyłączone albo go nie ma —
+     * Przystanek Tab paska: ostatnio użyte narzędzie, a gdy jest wyłączone albo go nie ma -
      * pierwsze dostępne. Dzięki temu `Tab` z paska idzie od razu do edytora, a nie przez kilkanaście
      * przycisków.
      */
     const usableTools = sections.flat().filter((item) => !disabled && enabled(item));
     const toolStop = lastTool && usableTools.includes(lastTool) ? lastTool : (usableTools[0] ?? null);
     const rovingProps = (item) => ({ 'data-tool': item, tabIndex: item === toolStop ? 0 : -1 });
-    /** Strzałki po pasku (w RTL odwrócone), `Home`/`End` — skrajne; wyłączone narzędzia są pomijane. */
+    /** Strzałki po pasku (w RTL odwrócone), `Home`/`End` - skrajne; wyłączone narzędzia są pomijane. */
     const onToolbarKeyDown = (event) => {
         const bar = event.currentTarget;
-        const buttons = [...bar.querySelectorAll('[data-tool]')];
+        const tools = [...bar.querySelectorAll('[data-tool]')];
+        // Narzędzie może być komponentem (`dictate` to KptSpeechButton) - fokus dostaje jego przycisk.
+        const buttons = tools.map((tool) => (tool instanceof HTMLButtonElement ? tool : tool.querySelector('button')));
         const current = buttons.indexOf(event.target);
         if (current < 0)
             return;
         const rtl = getComputedStyle(bar).direction === 'rtl';
         const key = rtl && event.key === 'ArrowLeft' ? 'ArrowRight' : rtl && event.key === 'ArrowRight' ? 'ArrowLeft' : event.key;
-        const next = nextRovingIndex(buttons.map((button) => button.disabled), current, key);
+        const next = nextRovingIndex(buttons.map((button) => !button || button.disabled), current, key);
         if (next === null)
             return;
         event.preventDefault();
-        setLastTool(buttons[next].dataset['tool']);
-        buttons[next].focus();
+        setLastTool(tools[next].dataset['tool']);
+        buttons[next]?.focus();
     };
     const toolButton = (item) => (_jsx("button", { ...rovingProps(item), ref: item === 'link' ? setLinkAnchor : undefined, "aria-haspopup": item === 'link' ? 'dialog' : undefined, "aria-expanded": item === 'link' ? linkOpen : undefined, type: "button", className: cn('kpt-rich-text__tool', isActive(item) && 'is-active'), "aria-label": t(`richText.${item}`), "aria-pressed": pressed(item), title: t(`richText.${item}`), disabled: disabled || !enabled(item), onMouseDown: (event) => event.preventDefault(), onClick: () => exec(item), children: _jsx(KptIcon, { name: ICON[item] }) }, item));
     /**
      * Akcje menu tabeli po identyfikatorze. Handlery żyją tutaj, a nie jako domknięcia przekazywane
-     * do `menuItem()` — funkcja wołana w renderze nie dostaje wtedy niczego, co czyta refy.
+     * do `menuItem()` - funkcja wołana w renderze nie dostaje wtedy niczego, co czyta refy.
      */
     const runTableAction = (action) => {
         switch (action) {
@@ -1004,6 +1023,11 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
                                     if (item === 'table') {
                                         return (_jsx("button", { ref: setTableAnchor, ...rovingProps(item), 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));
                                     }
+                                    if (item === 'dictate') {
+                                        // `data-tool` na hoście - roving znajduje narzędzie, a fokus dostaje jego przycisk.
+                                        const host = { className: 'kpt-rich-text__dictate', 'data-tool': item };
+                                        return (_jsx(KptSpeechButton, { listeningColor: speechColor, speech: mic, size: "sm", unsupported: "hide", wavePosition: "end", tabIndex: item === toolStop ? 0 : -1, disabled: disabled || sourceView, hostProps: host }, 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, 
                         // Wyłączony edytor (contentEditable=false) wypada z kolejności Tab jak wyłączone pole.
@@ -1023,7 +1047,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
                             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: linkOpen, anchor: linkAnchor, onClose: () => closeLink(false), offset: 4, children: _jsxs("form", { className: "kpt-rt-link", role: "dialog", 
-                    // Bez walidacji przeglądarki: „example.com” jest poprawnym wpisem — `sanitizeUrl` dopisze https://.
+                    // Bez walidacji przeglądarki: "example.com" jest poprawnym wpisem - `sanitizeUrl` dopisze https://.
                     noValidate: true, "aria-label": t('richText.link'), onSubmit: (event) => {
                         event.preventDefault();
                         applyLink();
@@ -1034,7 +1058,7 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
                         event.stopPropagation();
                         closeLink(true);
                     }, children: [_jsx("label", { className: "kpt-rt-link__label", htmlFor: `${field.id}-link`, children: t('richText.linkPrompt') }), _jsx("input", { ref: (el) => {
-                                // Panel jest niewidoczny do pierwszego pomiaru — fokus po klatce.
+                                // Panel jest niewidoczny do pierwszego pomiaru - fokus po klatce.
                                 if (el)
                                     requestAnimationFrame(() => el.focus());
                             }, className: "kpt-rt-link__input", id: `${field.id}-link`, type: "url", inputMode: "url", placeholder: "https://", value: linkDraft, onChange: (event) => setLinkDraft(event.target.value) }), _jsx("button", { type: "submit", className: "kpt-rt-link__apply", children: t('richText.linkApply') })] }) }), _jsx(KptOverlay, { open: styleOpen, anchor: styleAnchor, onClose: () => setStyleOpen(false), offset: 4, children: _jsx("ul", { ref: focusPanelOnMount, className: "kpt-rich-text__style-panel", role: "listbox", tabIndex: -1, "aria-label": t('richText.heading'), "aria-activedescendant": `${field.id}-style-${styleActive}`, onKeyDown: (event) => {
@@ -1061,9 +1085,9 @@ export function KptRichText({ value, defaultValue = '', onValueChange, toolbar =
                     setTableOpen(false);
                     setGrid({ r: 0, c: 0 });
                 }, offset: 4, children: _jsxs("div", { className: "kpt-rt-grid-pop", onMouseDown: (event) => event.preventDefault(), children: [_jsx("div", { ref: focusGridOnMount, className: "kpt-rt-grid", role: "group", 
-                            // Jeden przystanek ze strzałkami (rozmiar tabeli) — grupa z własną obsługą klawiatury.
+                            // Jeden przystanek ze strzałkami (rozmiar tabeli) - grupa z własną obsługą klawiatury.
                             // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- patrz wyżej
-                            tabIndex: 0, "aria-label": t('richText.table'), "aria-describedby": `${field.id}-grid-size`, "aria-keyshortcuts": "ArrowUp ArrowDown ArrowLeft ArrowRight Enter Escape", onKeyDown: onGridKeyDown, onMouseLeave: () => setGrid({ r: 0, c: 0 }), children: GRID_ROWS.map((r) => (_jsx("div", { className: "kpt-rt-grid__row", children: GRID_COLS.map((c) => (_jsx("span", { className: cn('kpt-rt-grid__cell', r <= grid.r && c <= grid.c && 'is-on'), onMouseEnter: () => setGrid({ r, c }), onClick: () => insertTableAt(r, c) }, c))) }, r))) }), _jsxs("div", { className: "kpt-rt-grid__label", id: `${field.id}-grid-size`, "aria-live": "polite", children: [grid.r, " \u00D7 ", grid.c] })] }) }), menuOpen
+                            tabIndex: 0, "aria-label": t('richText.table'), "aria-describedby": `${field.id}-grid-size`, "aria-keyshortcuts": "ArrowUp ArrowDown ArrowLeft ArrowRight Enter Escape", onKeyDown: onGridKeyDown, onMouseLeave: () => setGrid({ r: 0, c: 0 }), children: GRID_ROWS.map((r) => (_jsx("div", { className: "kpt-rt-grid__row", children: GRID_COLS.map((c) => (_jsx("span", { className: cn('kpt-rt-grid__cell', r <= grid.r && c <= grid.c && 'is-on'), onMouseEnter: () => setGrid({ r, c }), onClick: () => insertTableAt(r, c) }, c))) }, r))) }), _jsxs("div", { className: "kpt-rt-grid__label", id: `${field.id}-grid-size`, "aria-live": "polite", children: [grid.r, " x ", grid.c] })] }) }), menuOpen
                 ? pointPanel(_jsxs("div", { ref: (el) => {
                         if (el && menuFromKeyboard.current) {
                             menuFromKeyboard.current = false;

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

@@ -1,5 +1,5 @@
 /**
- * Czyści HTML i mówi, czy coś usunął. `changed: false` znaczy, że treść była czysta — wtedy
+ * Czyści HTML i mówi, czy coś usunął. `changed: false` znaczy, że treść była czysta - wtedy
  * wołający nie musi nadpisywać wartości modelu (serializacja DOM potrafi zmienić zapis, np.
  * cudzysłowy, bez zmiany treści, a taka różnica nie może brudzić formularza).
  */
@@ -13,7 +13,7 @@ export declare function sanitizeHtmlReport(html: string): {
  */
 export declare function sanitizeHtml(html: string): string;
 /**
- * Waliduje URL z narzędzia „link". Brak schematu → dopisujemy `https://`; `#` i `/` przechodzą
- * bez zmian; schemat spoza allowlisty → `null`, czyli link nie zostaje wstawiony.
+ * Waliduje URL z narzędzia "link". Brak schematu -> dopisujemy `https://`; `#` i `/` przechodzą
+ * bez zmian; schemat spoza allowlisty -> `null`, czyli link nie zostaje wstawiony.
  */
 export declare function sanitizeUrl(url: string): string | null;