@konce-pt/angular 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/CHANGELOG.md +591 -369
  2. package/README.md +111 -55
  3. package/charts/src/lib/llms.txt +17 -17
  4. package/chat/src/lib/llms.txt +61 -35
  5. package/fesm2022/konce-pt-angular-charts.mjs +11 -11
  6. package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
  7. package/fesm2022/konce-pt-angular-chat.mjs +236 -127
  8. package/fesm2022/konce-pt-angular-chat.mjs.map +1 -1
  9. package/fesm2022/konce-pt-angular-grid.mjs +16 -16
  10. package/fesm2022/konce-pt-angular-grid.mjs.map +1 -1
  11. package/fesm2022/konce-pt-angular-icons.mjs +5 -5
  12. package/fesm2022/konce-pt-angular-icons.mjs.map +1 -1
  13. package/fesm2022/konce-pt-angular-map.mjs +308 -280
  14. package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
  15. package/fesm2022/konce-pt-angular-roadmap.mjs +23 -23
  16. package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
  17. package/fesm2022/konce-pt-angular.mjs +4410 -2128
  18. package/fesm2022/konce-pt-angular.mjs.map +1 -1
  19. package/grid/src/lib/llms.txt +18 -18
  20. package/map/src/lib/llms.txt +142 -141
  21. package/package.json +14 -12
  22. package/roadmap/src/lib/llms.txt +27 -27
  23. package/src/lib/accordion/llms.txt +18 -6
  24. package/src/lib/alert/llms.txt +5 -5
  25. package/src/lib/app-shell/llms.txt +23 -21
  26. package/src/lib/auth/llms.txt +22 -22
  27. package/src/lib/autocomplete/llms.txt +15 -4
  28. package/src/lib/avatar/llms.txt +3 -3
  29. package/src/lib/avatar-group/llms.txt +5 -5
  30. package/src/lib/backdrop/llms.txt +35 -35
  31. package/src/lib/badge/llms.txt +7 -7
  32. package/src/lib/bottom-sheet/llms.txt +4 -4
  33. package/src/lib/breadcrumb/llms.txt +2 -2
  34. package/src/lib/breakpoint/llms.txt +8 -8
  35. package/src/lib/button/llms.txt +26 -18
  36. package/src/lib/button-group/llms.txt +37 -31
  37. package/src/lib/card/llms.txt +19 -19
  38. package/src/lib/carousel/llms.txt +6 -6
  39. package/src/lib/checkbox/llms.txt +15 -3
  40. package/src/lib/chip/llms.txt +6 -6
  41. package/src/lib/chips-input/llms.txt +11 -4
  42. package/src/lib/color-picker/llms.txt +4 -4
  43. package/src/lib/confirm/llms.txt +5 -5
  44. package/src/lib/context-menu/llms.txt +4 -4
  45. package/src/lib/data-table/llms.txt +280 -239
  46. package/src/lib/data-view/llms.txt +25 -4
  47. package/src/lib/date-range/llms.txt +27 -27
  48. package/src/lib/datepicker/llms.txt +34 -34
  49. package/src/lib/dialog/llms.txt +27 -27
  50. package/src/lib/divider/llms.txt +2 -2
  51. package/src/lib/drawer/llms.txt +7 -7
  52. package/src/lib/empty/llms.txt +4 -4
  53. package/src/lib/fab/llms.txt +6 -2
  54. package/src/lib/fieldset/llms.txt +22 -4
  55. package/src/lib/file-upload/llms.txt +1 -1
  56. package/src/lib/form-field/llms.txt +33 -19
  57. package/src/lib/galleria/llms.txt +3 -3
  58. package/src/lib/i18n/llms.txt +9 -9
  59. package/src/lib/icon/llms.txt +8 -8
  60. package/src/lib/icon-button/llms.txt +8 -3
  61. package/src/lib/image/llms.txt +4 -4
  62. package/src/lib/input/llms.txt +21 -7
  63. package/src/lib/input-mask/llms.txt +2 -2
  64. package/src/lib/input-number/llms.txt +14 -14
  65. package/src/lib/input-otp/llms.txt +6 -6
  66. package/src/lib/knob/llms.txt +11 -6
  67. package/src/lib/listbox/llms.txt +6 -6
  68. package/src/lib/loader/llms.txt +72 -0
  69. package/src/lib/megamenu/llms.txt +7 -7
  70. package/src/lib/mention/llms.txt +15 -15
  71. package/src/lib/menu/llms.txt +12 -12
  72. package/src/lib/menubar/llms.txt +7 -7
  73. package/src/lib/meter-group/llms.txt +7 -7
  74. package/src/lib/order-list/llms.txt +18 -6
  75. package/src/lib/paginator/llms.txt +5 -5
  76. package/src/lib/panel/llms.txt +20 -8
  77. package/src/lib/password/llms.txt +14 -6
  78. package/src/lib/peek/llms.txt +10 -10
  79. package/src/lib/pick-list/llms.txt +26 -6
  80. package/src/lib/popover/llms.txt +7 -7
  81. package/src/lib/progress/llms.txt +16 -16
  82. package/src/lib/radio-group/llms.txt +10 -3
  83. package/src/lib/rating/llms.txt +13 -6
  84. package/src/lib/rich-text/llms.txt +34 -29
  85. package/src/lib/scroll-top/llms.txt +3 -3
  86. package/src/lib/select/llms.txt +20 -13
  87. package/src/lib/sidenav/llms.txt +8 -8
  88. package/src/lib/slider/llms.txt +21 -8
  89. package/src/lib/speech/llms.txt +108 -0
  90. package/src/lib/speed-dial/llms.txt +9 -3
  91. package/src/lib/spinner/llms.txt +2 -2
  92. package/src/lib/split-button/llms.txt +14 -8
  93. package/src/lib/splitter/llms.txt +8 -8
  94. package/src/lib/stepper/llms.txt +24 -8
  95. package/src/lib/switch/llms.txt +10 -3
  96. package/src/lib/switch-group/llms.txt +10 -10
  97. package/src/lib/tabs/llms.txt +5 -5
  98. package/src/lib/textarea/llms.txt +16 -5
  99. package/src/lib/timeline/llms.txt +1 -1
  100. package/src/lib/toast/llms.txt +33 -5
  101. package/src/lib/toolbar/llms.txt +3 -3
  102. package/src/lib/tooltip/llms.txt +10 -10
  103. package/src/lib/tree/llms.txt +19 -6
  104. package/src/lib/update/llms.txt +52 -0
  105. package/types/konce-pt-angular-charts.d.ts +2 -2
  106. package/types/konce-pt-angular-chat.d.ts +87 -44
  107. package/types/konce-pt-angular-chat.d.ts.map +1 -1
  108. package/types/konce-pt-angular-grid.d.ts +14 -14
  109. package/types/konce-pt-angular-icons.d.ts +3 -3
  110. package/types/konce-pt-angular-map.d.ts +137 -121
  111. package/types/konce-pt-angular-map.d.ts.map +1 -1
  112. package/types/konce-pt-angular-roadmap.d.ts +13 -13
  113. package/types/konce-pt-angular.d.ts +1383 -625
  114. package/types/konce-pt-angular.d.ts.map +1 -1
@@ -1,12 +1,12 @@
1
1
  # KptProgress (kpt-progress)
2
2
 
3
- A progress indicator — linear or circular, determinate (`min`–`max`) or indeterminate (`value` = null).
3
+ A progress indicator - linear or circular, determinate (`min`-`max`) or indeterminate (`value` = null).
4
4
  Import: `import { KptProgress } from '@konce-pt/angular';`
5
5
 
6
6
  ## DOM
7
7
  <!-- linear, with a label, a buffer and a value -->
8
8
  <kpt-progress class="kpt-progress-host" data-type="linear" data-size="md" data-variant="primary" data-label-position="top">
9
- <span class="kpt-progress__label">Loading…</span>
9
+ <span class="kpt-progress__label">Loading...</span>
10
10
  <div class="kpt-progress__linear" role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="80">
11
11
  <div class="kpt-progress__buffer" style="width: 92%"></div>
12
12
  <div class="kpt-progress__bar" style="width: 80%"></div>
@@ -23,25 +23,25 @@ Import: `import { KptProgress } from '@konce-pt/angular';`
23
23
  <span class="kpt-progress__value" aria-hidden="true">75%</span>
24
24
  </kpt-progress>
25
25
 
26
- The label, the track and the value are siblings straight under the host — there is no wrapper element.
26
+ The label, the track and the value are siblings straight under the host - there is no wrapper element.
27
27
  `data-variant`, `data-type`, `data-size` and `data-label-position` all sit on the host, which is also
28
28
  where the private `--_color` and `--_thickness` are resolved.
29
29
 
30
30
  ## Inputs
31
- - `value`: number|null (default null) — a value on the `min`–`max` scale, or null for indeterminate
31
+ - `value`: number|null (default null) - a value on the `min`-`max` scale, or null for indeterminate
32
32
  - `min`: number (default 0); `max`: number (default 100)
33
33
  - `variant`: 'primary'|'success'|'danger'|'warning'|'info' (default 'primary')
34
34
  - `type`: 'linear'|'circular' (default 'linear')
35
- - `size`: 'sm'|'md'|'lg' (default 'md') — track thickness, and arc width on the circular variant
36
- - `diameter`: number (default 40) — the circular variant's size in pixels
37
- - `bufferValue`: number|null (default null) — a second, dimmed bar behind the main one; linear only
38
- - `showValue`: boolean (default false) — turns the value area on; projected content needs it too
35
+ - `size`: 'sm'|'md'|'lg' (default 'md') - track thickness, and arc width on the circular variant
36
+ - `diameter`: number (default 40) - the circular variant's size in pixels
37
+ - `bufferValue`: number|null (default null) - a second, dimmed bar behind the main one; linear only
38
+ - `showValue`: boolean (default false) - turns the value area on; projected content needs it too
39
39
  - `valueFormat`: 'percent'|'fraction'|'none' (default 'percent')
40
- - `label`: string — descriptive text next to the bar; it also becomes the `aria-label`
41
- - `labelPosition`: 'top'|'bottom'|'end' (default 'top') — ignored by the circular variant
40
+ - `label`: string - descriptive text next to the bar; it also becomes the `aria-label`
41
+ - `labelPosition`: 'top'|'bottom'|'end' (default 'top') - ignored by the circular variant
42
42
 
43
43
  ## Value label
44
- `showValue` opens the value area; `valueFormat` decides what goes in it — `percent` renders `80%`,
44
+ `showValue` opens the value area; `valueFormat` decides what goes in it - `percent` renders `80%`,
45
45
  `fraction` renders `152 / 160` from `value` and `max`, `none` leaves it empty. Both strings come from
46
46
  the `KptMessages` dictionary (`progress.percent`, `progress.fraction`), so a new locale can reshape them.
47
47
 
@@ -54,17 +54,17 @@ the accessible name.
54
54
 
55
55
  ## How the arc is drawn
56
56
  The circle lives in a fixed `viewBox="0 0 40 40"` with `r=16`, so the circumference is computed from
57
- that radius, not from `diameter` — the SVG scales, the maths does not change. The arc is the dash
57
+ that radius, not from `diameter` - the SVG scales, the maths does not change. The arc is the dash
58
58
  offset: full circumference means empty, zero means complete. `size` only changes `stroke-width`, and
59
59
  the widest step still fits inside the box, so no arc is ever clipped.
60
60
 
61
- Values outside the range are clamped rather than rejected, `max` ≤ `min` collapses to zero, and the
62
- buffer is never allowed behind the main bar — a computed percentage that briefly overshoots cannot
61
+ Values outside the range are clamped rather than rejected, `max` <= `min` collapses to zero, and the
62
+ buffer is never allowed behind the main bar - a computed percentage that briefly overshoots cannot
63
63
  break the drawing.
64
64
 
65
65
  ## Examples
66
66
  <kpt-progress [value]="60" />
67
- <kpt-progress [value]="80" label="Loading…" showValue />
67
+ <kpt-progress [value]="80" label="Loading..." showValue />
68
68
  <kpt-progress [value]="152" [max]="160" size="lg" showValue valueFormat="fraction" labelPosition="bottom" />
69
69
  <kpt-progress [value]="65" showValue labelPosition="end" />
70
70
  <kpt-progress [value]="38" [bufferValue]="62" />
@@ -88,5 +88,5 @@ leaves the value out, which is how a screen reader learns the progress is unknow
88
88
  announcing the raw number as a percentage. The visible value is `aria-hidden`, so it is never read
89
89
  twice. The accessible name comes from `label`, or from the dictionary when there is none.
90
90
 
91
- Under `prefers-reduced-motion: reduce` the indeterminate animation slows down instead of stopping —
91
+ Under `prefers-reduced-motion: reduce` the indeterminate animation slows down instead of stopping -
92
92
  a frozen progress indicator reads as a hung application.
@@ -10,18 +10,25 @@ Import: `import { KptRadioGroup, KptOption } from '@konce-pt/angular';`
10
10
  ## Inputs
11
11
  - `value`: model<T>; `options`: KptOption<T>[] `{ label, value, disabled? }`
12
12
  - `disabled`/`invalid`/`touched`: boolean; `name`: string (automatic); the `touch` output.
13
+ - `toggleMotion`: 'spring' | 'fade' | 'none' (default from `provideKptMotion`, else `spring`) - see "Toggle motion"
13
14
 
14
15
  ## Screen reader and keyboard
15
- `orientation`: 'vertical' (default) | 'horizontal' — options in a column or in a wrapping row; also
16
+ `orientation`: 'vertical' (default) | 'horizontal' - options in a column or in a wrapping row; also
16
17
  sets `aria-orientation`.
17
18
 
18
19
  ## Label and description
19
- `id` goes to the focusable element — the host never carries it; without one it is generated. A `div`
20
+ `id` goes to the focusable element - the host never carries it; without one it is generated. A `div`
20
21
  with a role is not named by `label[for]`, so inside `kpt-form-field` it gets `aria-labelledby`
21
22
  pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error is added to
22
- `aria-describedby`. No `controlId` needed. New: `id`, `ariaLabel` and `required` (→ `aria-required`)
23
+ `aria-describedby`. No `controlId` needed. New: `id`, `ariaLabel` and `required` (-> `aria-required`)
23
24
  on the `radiogroup`.
24
25
 
26
+ ## Toggle motion
27
+ `toggleMotion`: `spring` - the dot pops in on a spring and the circle bounces; `fade` - a calm colour and mark transition; `none` - no
28
+ motion. The bounce is started by the change handler, so a control that is checked on load does not
29
+ move. With no value it takes `toggle` from `provideKptMotion` (default `spring`); `enabled: false` and the
30
+ system "reduce motion" setting always win.
31
+
25
32
  ## Tokens
26
33
  `--kpt-color-primary`, `--kpt-form-field-border`.
27
34
 
@@ -4,9 +4,9 @@ A star rating on Signal Forms. Import: `import { KptRating } from '@konce-pt/ang
4
4
 
5
5
  ## Inputs
6
6
  - `value`: model<number>; `count`: number (number of stars, default 5)
7
- - `allowHalf`: boolean — half stars, the value goes in steps of 0.5
7
+ - `allowHalf`: boolean - half stars, the value goes in steps of 0.5
8
8
  - `readonly`/`disabled`/`required`/`invalid`/`touched`: boolean; `touch`: output
9
- - `id`/`ariaLabel`: string|null — `id` goes to the group, never the host
9
+ - `id`/`ariaLabel`: string|null - `id` goes to the group, never the host
10
10
 
11
11
  ## Example
12
12
  <kpt-rating [formField]="f.score" [count]="5" />
@@ -15,18 +15,25 @@ A star rating on Signal Forms. Import: `import { KptRating } from '@konce-pt/ang
15
15
 
16
16
  ## Accessibility
17
17
  `role="radiogroup"` named by `ariaLabel` or the `kpt-form-field` label; each star is
18
- `role="radio"` with `aria-checked`, labelled from `rating.star` (`{value}`, `{max}`) — EN `1 of 5`,
19
- PL `1 z 5`. One Tab stop: `→`/`↑` raise the score by one, `←`/`↓` lower it (mirrored in RTL),
18
+ `role="radio"` with `aria-checked`, labelled from `rating.star` (`{value}`, `{max}`) - EN `1 of 5`,
19
+ PL `1 z 5`. One Tab stop: `ArrowRight`/`ArrowUp` raise the score by one, `ArrowLeft`/`ArrowDown` lower it (mirrored in RTL),
20
20
  `Home`/`End` set the extremes, `Delete`/`Backspace` clear it; clicking the chosen star also clears it.
21
21
  `readonly` renders `role="img"` named "4 of 5" with no buttons, so a screen reader does not announce
22
22
  a row of disabled controls. `touch` fires when focus leaves the group.
23
23
 
24
24
  ## Half stars
25
- `allowHalf` splits every star into two halves, each its own `role="radio"` ("3.5 of 5" — the number
25
+ `allowHalf` splits every star into two halves, each its own `role="radio"` ("3.5 of 5" - the number
26
26
  follows the page language, PL "3,5 z 5"), so the group keeps the radio pattern: clicking the left half
27
- gives x.5, and the arrows step by 0.5. Read-only stars show the value rounded to a half (4.3 → four
27
+ gives x.5, and the arrows step by 0.5. Read-only stars show the value rounded to a half (4.3 -> four
28
28
  and a half stars) while the name carries the exact score ("4.3 of 5"), so an average can be shown
29
29
  as it is.
30
30
 
31
+ ## Pointer
32
+ Dragging across the stars (mouse or touch) picks a score: the preview follows the pointer and releasing
33
+ commits it - with `allowHalf` to the nearest half, in RTL mirrored; dragging past the first star clears
34
+ the score. A short press without movement stays a click (including a second click that clears the
35
+ score). Stars that light up pop in one after another - the motion follows `toggle` from `provideKptMotion`
36
+ (`spring` only); `enabled: false` and the system "reduce motion" setting always win.
37
+
31
38
  ## Tokens
32
39
  Filled stars `--kpt-color-warning`; empty ones `--kpt-color-border-strong`.
@@ -2,7 +2,7 @@
2
2
 
3
3
  A lightweight rich text editor (contenteditable) with a configurable, sectioned toolbar.
4
4
  The value is HTML. No external dependencies. Signal Forms.
5
- The color popover sits on CDK Overlay — requires `import '@angular/cdk/overlay-prebuilt.css';`
5
+ The color popover sits on CDK Overlay - requires `import '@angular/cdk/overlay-prebuilt.css';`
6
6
  Import: `import { KptRichText, KptRichTool, KptRichToolbar } from '@konce-pt/angular';`
7
7
 
8
8
  ## Inputs
@@ -10,60 +10,65 @@ Import: `import { KptRichText, KptRichTool, KptRichToolbar } from '@konce-pt/ang
10
10
  - `toolbar`: KptRichToolbar = KptRichTool[] | KptRichTool[][] (a flat list, or groups = sections).
11
11
  Leaving a tool or a group out disables it; groups are separated by a divider. The full toolbar in 5 sections by default.
12
12
  - `placeholder`: string; `disabled`/`invalid`/`touched`: boolean; `touch`: output
13
- - `maxListLevel`: number = 6 — the maximum list nesting depth. The limit applies to interaction
13
+ - `maxListLevel`: number = 6 - the maximum list nesting depth. The limit applies to interaction
14
14
  (Tab and the `indent`/`outdent` tools); pasted content is not flattened, so that no data is lost.
15
- - `mentions`: `readonly KptMentionItem[]` — suggestions for `@`; an empty list turns the mechanism
15
+ - `mentions`: `readonly KptMentionItem[]` - suggestions for `@`; an empty list turns the mechanism
16
16
  off, so `@` stays an ordinary character. `mentionLimit`: number = 8; `(mentioned)` fires with the
17
- inserted entry — the moment to notify a person or attach a link.
17
+ inserted entry - the moment to notify a person or attach a link.
18
18
 
19
19
  ## Mentions (`@`)
20
20
  With `mentions` set, typing `@` opens a suggestion list anchored at the caret: arrows move through
21
21
  it, Enter or Tab inserts, Escape closes. The query is read from the **text node** at the caret, not
22
- from the HTML, and recognised by `mentionQuery()` from `@konce-pt/mention` — the same rules as in a
22
+ from the HTML, and recognised by `mentionQuery()` from `@konce-pt/mention` - the same rules as in a
23
23
  plain text field.
24
24
 
25
25
  An inserted mention is `<span class="kpt-mention" data-mention="id" contenteditable="false">@Name`
26
26
  plus a non-breaking space. The id survives a rename and the round trip through the value;
27
27
  `contenteditable="false"` keeps the mention in one piece, and the space is what gives the caret a
28
- place to stand after a block it cannot enter. Both attributes are on the sanitizer's allowlist —
28
+ place to stand after a block it cannot enter. Both attributes are on the sanitizer's allowlist -
29
29
  they are inert, so they open no new door.
30
30
 
31
31
  ## Tools (KptRichTool)
32
32
  - Clipboard: `copy`, `paste` (with formatting, sanitized), `pasteText` (without formatting)
33
- - Style: `heading` (a select: Normal/paragraph + Heading 1–6)
33
+ - Style: `heading` (a select: Normal/paragraph + Heading 1-6)
34
34
  - Format: `bold`, `italic`, `underline`, `strike`, `ul`, `ol`
35
- - List indentation: `indent` (add an indent), `outdent` (remove one) — they work only inside an `li`,
35
+ - List indentation: `indent` (add an indent), `outdent` (remove one) - they work only inside an `li`,
36
36
  nesting per the specification (`li > ul/ol > li`, a sublist inherits the parent list's type).
37
37
  They are only active where they would do something (outside a list and at the limit the button is dimmed).
38
- Level markers cycle every 3 (as in word processors): `ol` 1. → a. → i., `ul` • → ○ → ▪.
38
+ Level markers cycle every 3 (as in word processors): `ol` 1. -> a. -> i., `ul` - -> o -> -.
39
39
  The `list-style-type` rules apply in the editor view (`.kpt-rich-text__editor`) down to level 6.
40
- The saved HTML carries no classes — when rendering `value` outside the editor, wrap it in `.kpt-rich-content`
40
+ The saved HTML carries no classes - when rendering `value` outside the editor, wrap it in `.kpt-rich-content`
41
41
  from `@konce-pt/styles` so the lists look the same.
42
- - Colors: `foreColor` (text color), `backColor` (background color) — a popover with swatches + an `input type=color`
42
+ - Colors: `foreColor` (text color), `backColor` (background color) - a popover with swatches + an `input type=color`
43
43
  - Alignment: `alignLeft`, `alignCenter`, `alignRight`, `alignJustify`
44
44
  - `table` (insert a table: a popover with an NxM grid). Inside a cell, right-click opens a context menu
45
- (insert/remove a row and a column, a row/column header — toggling td↔th, cell background color and alignment,
46
- table/cell borders — color + thickness (thin/medium/thick) or none, delete the table).
45
+ (insert/remove a row and a column, a row/column header - toggling td<->th, cell background color and alignment,
46
+ table/cell borders - color + thickness (thin/medium/thick) or none, delete the table).
47
47
  Dragging across cells makes a rectangular selection (highlighted); merging/splitting cells
48
48
  (colspan/rowspan) from the menu; cell operations (background, alignment, borders) apply to the whole selection.
49
49
  Dragging a column's right edge changes its width.
50
50
  Deferred: irregular selection, Ctrl+Backspace, bulk formatting from the top toolbar.
51
- - `link` (a URL prompt), `clear` (remove formatting), `html` (a toggle for the HTML source view — editing raw HTML)
51
+ - `link` (a URL prompt), `clear` (remove formatting), `html` (a toggle for the HTML source view - editing raw HTML)
52
+ - `dictate` - dictation at the caret (`kpt-speech-button`, Web Speech API); not in the default toolbar.
53
+ Final text goes in through `insertText` (native undo, `input` -> value); interim text is an overlay
54
+ next to the caret (`.kpt-speech-ghost`) and never enters `innerHTML`. Hidden without browser support,
55
+ stopped by the HTML source view and by `disabled`/`readonly`. Language: `speechLang` (BCP 47, default
56
+ from `KptI18n.locale`), listening colour: `speechColor` (theme colour by default). Example: `[toolbar]="[['bold','italic'],['dictate']]"`.
52
57
 
53
58
  ## Keyboard
54
59
  - The toolbar is a named `role="toolbar"` ("Formatting", `richText.toolbar`) with one Tab stop:
55
- `←`/`→` (mirrored in RTL) and `Home`/`End` move between tools, skipping disabled ones; the stop
60
+ `ArrowLeft`/`ArrowRight` (mirrored in RTL) and `Home`/`End` move between tools, skipping disabled ones; the stop
56
61
  remembers the last tool, so Tab from the toolbar goes straight to the editor.
57
62
  - Tool panels open in the overlay container at the end of `<body>`, so focus moves into them:
58
- the paragraph style list is a `listbox` (`↑`/`↓`, `Home`/`End`, `Enter`/`Space` picks, `Escape`/`Tab` close);
59
- the table grid is one stop (arrows change the size 1–8, the size is announced, `Enter` inserts);
60
- the colour palette starts on the first swatch (`←`/`→` between swatches, `Tab` cycles inside the
63
+ the paragraph style list is a `listbox` (`ArrowUp`/`ArrowDown`, `Home`/`End`, `Enter`/`Space` picks, `Escape`/`Tab` close);
64
+ the table grid is one stop (arrows change the size 1-8, the size is announced, `Enter` inserts);
65
+ the colour palette starts on the first swatch (`ArrowLeft`/`ArrowRight` between swatches, `Tab` cycles inside the
61
66
  panel). `Escape` closes any of them and returns focus to the tool.
62
67
  - Tab / Shift+Tab inside a list item = indent / one level up (the same as `indent`/`outdent`).
63
68
  - Tab / Shift+Tab inside a table cell = the next / previous cell (with its content selected).
64
- A list inside a cell takes precedence — only once it can no longer be indented does Tab move to another cell.
65
- - Everywhere else — including on the first list item, at the top level, at `maxListLevel`
66
- and in the last table cell — Tab stays **native** and moves focus out of the editor. That is deliberate:
69
+ A list inside a cell takes precedence - only once it can no longer be indented does Tab move to another cell.
70
+ - Everywhere else - including on the first list item, at the top level, at `maxListLevel`
71
+ and in the last table cell - Tab stays **native** and moves focus out of the editor. That is deliberate:
67
72
  an editor must not be a keyboard trap (WCAG 2.1.2), so `preventDefault()` is called only
68
73
  when the operation actually changed the content.
69
74
 
@@ -73,22 +78,22 @@ they are inert, so they open no new door.
73
78
 
74
79
  ## i18n
75
80
  Every label (the tools' aria text, the "Normal/Heading N" styles, the link prompt, the table context menu,
76
- the border popover, "Custom…") comes from i18n (the `richText` namespace, including `richText.menu.*`,
77
- `richText.border.*`). English by default — see `i18n/llms.txt`.
81
+ the border popover, "Custom...") comes from i18n (the `richText` namespace, including `richText.menu.*`,
82
+ `richText.border.*`). English by default - see `i18n/llms.txt`.
78
83
 
79
84
  ## Notes
80
85
  Formatting goes through document.execCommand; active tools are highlighted (queryCommandState).
81
86
  Pasting (both native and through the buttons) is sanitized (a tag/style allowlist; it strips script/on*/javascript:).
82
- Sanitization covers **every** write into the editor's DOM, not just paste — including a `value` set from
87
+ Sanitization covers **every** write into the editor's DOM, not just paste - including a `value` set from
83
88
  outside (`[(value)]`/`formField` from the application, the HTML source mode). Treat an incoming `value` as
84
89
  potentially untrusted (a database, another user, a CMS); on the way out of the component it is sanitized.
85
- Links keep only relative addresses and `http(s):`, `mailto:`, `tel:` — the same allowlist as the link tool, so
90
+ Links keep only relative addresses and `http(s):`, `mailto:`, `tel:` - the same allowlist as the link tool, so
86
91
  `data:`, `vbscript:` or `blob:` from a paste are dropped. `class` keeps only the editor's own classes
87
92
  (`kpt-rt-*`, `kpt-mention`), a link with `target` always gets `rel="noopener noreferrer"`, and when the
88
- sanitizer removed something, the cleaned HTML is written back to `value` — the model never holds the
93
+ sanitizer removed something, the cleaned HTML is written back to `value` - the model never holds the
89
94
  unsafe original (a pure formatting difference does not touch it, so a clean value does not dirty a form).
90
95
  The "paste"/"paste without formatting" clipboard tools use the async Clipboard API (which needs browser permission).
91
- An exception to execCommand: list indentation is done with our own DOM code — `execCommand('indent')` produces
96
+ An exception to execCommand: list indentation is done with our own DOM code - `execCommand('indent')` produces
92
97
  invalid `ul > ul` in Chrome (or a `blockquote` with a margin, which the sanitizer would strip anyway).
93
98
 
94
99
  ## Screen reader and keyboard
@@ -100,10 +105,10 @@ goes back to the cell. Colour swatches are named ("Dark grey", `richText.swatche
100
105
  their hex codes. The table size grid is still mouse-only.
101
106
 
102
107
  ## Label and description
103
- `id` goes to the focusable element — the host never carries it; without one it is generated. A `div`
108
+ `id` goes to the focusable element - the host never carries it; without one it is generated. A `div`
104
109
  with a role is not named by `label[for]`, so inside `kpt-form-field` it gets `aria-labelledby`
105
110
  pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error is added to
106
- `aria-describedby`. No `controlId` needed. New: `id`, `ariaLabel` and `required` (→ `aria-required`)
111
+ `aria-describedby`. No `controlId` needed. New: `id`, `ariaLabel` and `required` (-> `aria-required`)
107
112
  on the `role="textbox"` area.
108
113
 
109
114
  ## Read-only and required
@@ -1,11 +1,11 @@
1
1
  # KptScrollTop (kpt-scroll-top)
2
2
 
3
- A "back to top" button — appears after scrolling past `threshold` px.
3
+ A "back to top" button - appears after scrolling past `threshold` px.
4
4
  Import: `import { KptScrollTop } from '@konce-pt/angular';`
5
5
 
6
6
  ## Inputs
7
7
  - `threshold`: number (px, default 300)
8
- - `target`: string | null — selector of the scrolled element; the window by default
8
+ - `target`: string | null - selector of the scrolled element; the window by default
9
9
 
10
10
  ## Example
11
11
  <kpt-scroll-top [threshold]="300" />
@@ -24,4 +24,4 @@ A real `<button>` labelled from `scrollTop.label`; while hidden it is `visibilit
24
24
  out of the tab order and the accessibility tree. It sits in the bottom-end corner
25
25
  (`inset-inline-end`), so it moves to the left in RTL. With `prefers-reduced-motion` the scroll is a
26
26
  jump instead of smooth and the button appears without a transition. Focus stays on the button after
27
- the jump — move it to your page heading if that matters.
27
+ the jump - move it to your page heading if that matters.
@@ -8,34 +8,34 @@ Requires the CDK overlay styles in the application: `import '@angular/cdk/overla
8
8
 
9
9
  ## Usage
10
10
  roles: KptOption<string>[] = [{label:'Admin',value:'admin'}, ...];
11
- <kpt-select [formField]="f.role" [options]="roles" placeholder="Choose…" />
12
- <kpt-select [formField]="f.city" [options]="cities" filter placeholder="Search…" />
11
+ <kpt-select [formField]="f.role" [options]="roles" placeholder="Choose..." />
12
+ <kpt-select [formField]="f.city" [options]="cities" filter placeholder="Search..." />
13
13
  <kpt-select [formField]="f.tags" [options]="tags" multiple filter /> <!-- value: string[] -->
14
14
 
15
15
  ## Inputs
16
16
  - `value`: model (T, or T[] with multiple); `options`: KptOption<T>[]; `placeholder`: string
17
- - `filter`: boolean — a search field; `multiple`: boolean — multi-select (chips)
17
+ - `filter`: boolean - a search field; `multiple`: boolean - multi-select (chips)
18
18
  - `disabled`/`invalid`/`touched`: boolean; the `touch` output.
19
- - `open`: model (two-way `[(open)]`, the `(openChange)` output) — the panel state. It lets you open
20
- the list from outside and know when the user is done choosing — that is what inline editing
19
+ - `open`: model (two-way `[(open)]`, the `(openChange)` output) - the panel state. It lets you open
20
+ the list from outside and know when the user is done choosing - that is what inline editing
21
21
  in `kpt-data-table` does, see `data-table/llms.txt`. `touch` fires when the panel closes and when
22
22
  focus leaves the closed trigger; moving focus into the search field does not count as leaving.
23
- - `ariaLabel`: string|null — the accessible name of the trigger and the list when no `<label for>`
23
+ - `ariaLabel`: string|null - the accessible name of the trigger and the list when no `<label for>`
24
24
  describes the field.
25
25
 
26
26
  ## Keyboard
27
27
  The select-only combobox pattern: focus stays on the trigger, and the active option is announced
28
28
  through `aria-activedescendant` (with `filter`, focus moves to the search field, which is the combobox).
29
- - Closed: `↓`/`↑`/`Enter`/`Space`/`Home`/`End` open the list; typing letters opens it on the first
29
+ - Closed: `ArrowDown`/`ArrowUp`/`Enter`/`Space`/`Home`/`End` open the list; typing letters opens it on the first
30
30
  match; in `multiple` mode `Backspace`/`Delete` removes the last chip.
31
- - Open: `↑`/`↓` move by one, `Home`/`End` to the ends, `PageUp`/`PageDown` by ten — disabled options
31
+ - Open: `ArrowUp`/`ArrowDown` move by one, `Home`/`End` to the ends, `PageUp`/`PageDown` by ten - disabled options
32
32
  are skipped, the list does not wrap. `Enter` (and `Space` on the trigger) picks; a single select
33
33
  closes and returns focus to the trigger, a multiple one stays open. Typing jumps to the next option
34
34
  starting with the letters (diacritics ignored). `Escape` and `Tab` close the list.
35
35
  - Clicking an option does not take focus from the trigger, so a mouse pick does not blur the field.
36
36
 
37
37
  ## Float label
38
- In a `kpt-form-field` with `labelType` `over`/`in`/`on` the label also floats once an option is chosen —
38
+ In a `kpt-form-field` with `labelType` `over`/`in`/`on` the label also floats once an option is chosen -
39
39
  the select provides the `KPT_FORM_FIELD_CONTROL` token with a `filled` signal (a value in an overlay cannot
40
40
  be read from the DOM). Nothing needs configuring:
41
41
 
@@ -44,16 +44,23 @@ be read from the DOM). Nothing needs configuring:
44
44
  </kpt-form-field>
45
45
 
46
46
  ## i18n
47
- The "Search…" and "No results" labels and the chip-removal aria text come from i18n (the `select` namespace).
48
- English by default; configured through `provideKptI18n` — see `i18n/llms.txt`.
47
+ The "Search..." and "No results" labels and the chip-removal aria text come from i18n (the `select` namespace).
48
+ English by default; configured through `provideKptI18n` - see `i18n/llms.txt`.
49
49
 
50
50
  ## Label and description
51
- `id` goes to the focusable element — the host never carries it; without one it is generated. A `div`
51
+ `id` goes to the focusable element - the host never carries it; without one it is generated. A `div`
52
52
  with a role is not named by `label[for]`, so inside `kpt-form-field` it gets `aria-labelledby`
53
53
  pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error is added to
54
- `aria-describedby`. No `controlId` needed. New: `id` and `required` (→ `aria-required`); the list
54
+ `aria-describedby`. No `controlId` needed. New: `id` and `required` (-> `aria-required`); the list
55
55
  gets the same name as the trigger.
56
56
 
57
+ ## Motion
58
+ With `multiple`, a chip of a newly picked option pops in at its place (chips follow the order of
59
+ `options`), a removed one - by its "x", by unpicking it in the list or by `Backspace` - fades and shrinks in
60
+ place while the rest slide over on a spring. Several changes at once (e.g. a new value set from code) go
61
+ without motion. Follows `enter` from `provideKptMotion` (`spring` / `fade` / `none`); `enabled: false` and the
62
+ system "reduce motion" setting always win.
63
+
57
64
  ## Tokens
58
65
  `--kpt-form-field-{bg,text,border,border-hover,border-focus,border-error,radius}`.
59
66
 
@@ -1,20 +1,20 @@
1
1
  # KptSidenav (kpt-sidenav)
2
2
 
3
- A side panel — a styled navigation container, usually in the `kptShellSidenav` slot
3
+ A side panel - a styled navigation container, usually in the `kptShellSidenav` slot
4
4
  of `kpt-app-shell`. Import: `import { KptSidenav } from '@konce-pt/angular';`
5
5
 
6
6
  ## Selector
7
7
  `kpt-sidenav`
8
8
 
9
9
  ## Content
10
- Anything (ng-content) — it lands in the scrollable area. `<a>` elements come with built-in
10
+ Anything (ng-content) - it lands in the scrollable area. `<a>` elements come with built-in
11
11
  navigation-entry styling (hover with `--kpt-color-muted`).
12
12
 
13
- ## The footer — `kptSidenavFooter`
13
+ ## The footer - `kptSidenavFooter`
14
14
  An element carrying this attribute lands outside the scrollable area and stays stuck to the bottom of the
15
15
  panel, no matter how long the navigation is. It gets a top rule (`--kpt-sidenav-border`) across the panel's
16
16
  full width and the same padding as the navigation. Typical uses: the signed-in user block,
17
- a theme toggle, the application version. It is a plain attribute, not a directive — there is nothing
17
+ a theme toggle, the application version. It is a plain attribute, not a directive - there is nothing
18
18
  to import.
19
19
 
20
20
  ## Example
@@ -28,21 +28,21 @@ to import.
28
28
  </div>
29
29
  </kpt-sidenav>
30
30
 
31
- In the icon rail, mark the footer text with the `kptNavLabel` attribute — the collapsed panel then leaves just the avatar.
31
+ In the icon rail, mark the footer text with the `kptNavLabel` attribute - the collapsed panel then leaves just the avatar.
32
32
 
33
33
  ## The icon rail (kpt-app-shell)
34
34
  If the shell has `sidenavRailBreakpoint` enabled, mark an entry's text with the `kptNavLabel` attribute
35
- and a group heading with `kptNavSection` — in the collapsed rail only the icon remains, and the label is
35
+ and a group heading with `kptNavSection` - in the collapsed rail only the icon remains, and the label is
36
36
  hidden technically (visually hidden), so a screen reader still knows the entry's name:
37
37
 
38
38
  <a href="#"><kpt-icon name="list" /> <span kptNavLabel>Dashboard</span></a>
39
39
 
40
- These are plain attributes, not directives — there is nothing to import. Without an icon the rail will be empty.
40
+ These are plain attributes, not directives - there is nothing to import. Without an icon the rail will be empty.
41
41
 
42
42
  ## Links
43
43
  Links in the scroll area are `display: flex` with a gap, so an icon and a label never glue together
44
44
  even when the template compiler drops the whitespace between them. A link with
45
- `aria-current="page"` gets the muted background and a medium weight — mark the current page
45
+ `aria-current="page"` gets the muted background and a medium weight - mark the current page
46
46
  yourself, the component does not know which one it is.
47
47
 
48
48
  ## Tokens
@@ -3,9 +3,9 @@
3
3
  A value slider on Signal Forms. Import: `import { KptSlider } from '@konce-pt/angular';`
4
4
 
5
5
  ## Inputs
6
- - `value`: model<number | [number, number]> — in `range` mode a `[min, max]` pair, otherwise a single number
7
- - `range`: boolean — two handles (a range); `min`/`max`: number (per FormValueControl); `step`: number
8
- - Under `[formField]` do NOT bind the bounds — they are declared by `min()`/`max()` in `form()`, and `FormField`
6
+ - `value`: model<number | [number, number]> - in `range` mode a `[min, max]` pair, otherwise a single number
7
+ - `range`: boolean - two handles (a range); `min`/`max`: number (per FormValueControl); `step`: number
8
+ - Under `[formField]` do NOT bind the bounds - they are declared by `min()`/`max()` in `form()`, and `FormField`
9
9
  injects them into the `min`/`max` inputs itself; `[min]`/`[max]` next to `[formField]` is a compilation error
10
10
  (FORM_FIELD_UNSUPPORTED_BINDING). The `range` mode (a `[number, number]` value) has no counterpart
11
11
  among the validators (`min()`/`max()` only accept numeric fields), so it is paired with `[(value)]`.
@@ -18,15 +18,15 @@ A value slider on Signal Forms. Import: `import { KptSlider } from '@konce-pt/an
18
18
  <kpt-slider range [(value)]="span" [min]="0" [max]="100" showValue />
19
19
 
20
20
  ## Notes
21
- - The `range` mode uses two stacked `input[type=range]` elements; `pointer-events` are active only on the handles (the track does not intercept them).
22
- - The handles cannot cross — the lower one is clamped to the upper one and vice versa.
21
+ - The `range` mode uses two stacked `input[type=range]` elements; `pointer-events` are active only on the handles, and a press on the track moves the nearest handle (see "Pointer").
22
+ - The handles cannot cross - the lower one is clamped to the upper one and vice versa.
23
23
 
24
24
  ## Screen reader and keyboard
25
- `suffix`: string (" zł", "%", " km") — shown after the value and put into `aria-valuetext` ("40
25
+ `suffix`: string (" zł", "%", " km") - shown after the value and put into `aria-valuetext` ("40
26
26
  zł"), so the unit is read too. `aria-invalid` after touch.
27
27
 
28
28
  ## Label and description
29
- `id` goes to the native field — the host never carries it; without one it is generated. Inside
29
+ `id` goes to the native field - the host never carries it; without one it is generated. Inside
30
30
  `kpt-form-field` the control links itself: the wrapper's `label[for]` points at it and the hint or
31
31
  error is added to `aria-describedby`, so `controlId` is not needed. Without a wrapper, name it with
32
32
  `ariaLabel`. With `range` the thumbs are named "Minimum"/"Maximum" from i18n
@@ -34,8 +34,21 @@ error is added to `aria-describedby`, so `controlId` is not needed. Without a wr
34
34
  thumb reads "<label> Minimum" through `aria-labelledby`, without one `ariaLabel` gives "<ariaLabel>,
35
35
  Minimum". `id` goes to the single input or the lower thumb.
36
36
 
37
+ ## Pointer
38
+ The handle reacts to the pointer: it grows on hover, and while held it grows more on a spring with
39
+ a soft halo in the primary colour and a `grabbing` cursor. A click on the track (and a key press) glides
40
+ the handle and the fill to the new value instead of jumping; while dragging they follow the pointer with
41
+ no delay. The native `input[type=range]` stays transparent on top (keyboard, screen reader, dragging) and
42
+ the track, fill and handle are drawn next to it from `--_p` (0..1); `range` draws two handles from
43
+ `--_lo`/`--_hi`. The glide is pure CSS and drops out under "reduce motion".
44
+
45
+ In `range` mode a press on the track outside the handles - before the range, after it or inside it -
46
+ moves the nearest handle there, focuses it (arrow keys keep working) and keeps dragging it until
47
+ release. The handles themselves are dragged natively. When both handles sit in the upper half, the
48
+ lower one is stacked on top, so two handles pushed against `max` can still be pulled apart.
49
+
37
50
  ## Tokens
38
51
  The track is filled with `--kpt-color-primary`, the background is `--kpt-color-surface-variant`.
39
52
 
40
53
  ## Read-only and required
41
- `readonly` keeps the thumb focusable but undoes every move (`aria-readonly`). The range thumbs can no longer cross: the clamped value is written back to the native input, so the thumb stops at the other one. `slider` does not accept `aria-required` — the field asterisk and the validator carry it.
54
+ `readonly` keeps the thumb focusable but undoes every move (`aria-readonly`). The range thumbs can no longer cross: the clamped value is written back to the native input, so the thumb stops at the other one. `slider` does not accept `aria-required` - the field asterisk and the validator carry it.
@@ -0,0 +1,108 @@
1
+ # KptSpeechButton (kpt-speech-button), KptSpeechWave (kpt-speech-wave)
2
+
3
+ Dictation with a microphone button. A click turns the icon into "stop", an animated wave slides in
4
+ next to it and the recognised words appear live in the target: a textarea, an input, a
5
+ `contenteditable` element, a plain element or a function. Built on the Web Speech API; the session,
6
+ insertion and wave maths live in `@konce-pt/speech`.
7
+ Import: `import { KptSpeechButton, KptSpeechWave } from '@konce-pt/angular';`
8
+
9
+ ## The key rule
10
+ Interim text is visible in the target but never reaches the model. A textarea or input shows it in
11
+ the native value without an `input` event; only final text goes in as a regular edit (with native
12
+ undo when the field has focus). Signal Forms (`[formField]`), `[(value)]`, validators and search
13
+ fields see final text only - no half-words, no query per syllable.
14
+
15
+ ## KptSpeechButton - inputs
16
+ - `target`: `HTMLElement | KptSpeechTarget | (snapshot) => void | ElementRef | KptSpeechTargetProvider`
17
+ (default `null` - only `(result)` is emitted). A template reference to a native element is enough.
18
+ - `lang`: string | null - BCP 47 tag (`pl-PL`); without it from `KptI18n.locale` and the browser
19
+ language (`defaultSpeechLang`). A change applies from the next session.
20
+ - `continuous`: boolean = true - listen until "stop"; `false` - one utterance (search fields).
21
+ - `mode`: `'insert' | 'append' | 'replace'` = `'insert'` - at the caret, at the end, or clear the
22
+ target the moment dictation starts (undoable with Ctrl+Z).
23
+ - `interim`: `'inline' | 'ghost' | 'none' | null` - how interim text is shown; `null` = the default for
24
+ the target kind (`inline` in fields, `ghost` overlay in contenteditable).
25
+ - `capitalize`: boolean = true - capital letter at the start of a sentence.
26
+ - `wave`: `'auto' | 'live' | 'synthetic' | 'none'` = `'auto'` - `live` measures the voice level
27
+ (desktop), `synthetic` is a CSS animation (phones, tablets, or when the meter fails).
28
+ - `wavePosition`: `'start' | 'end'` = `'start'`; `bars`: number = 5.
29
+ - `silenceMs`: number = 0 - stop after this much silence; `maxDuration`: number = 0 - hard limit (ms).
30
+ - `processLocally`: boolean = false - on-device recognition only (Chrome 135+), audio never leaves
31
+ the computer.
32
+ - `unsupported`: `'disable' | 'hide'` = `'disable'` - Firefox, `http:`, or a browser without the
33
+ service (Brave, Opera): a disabled button with the reason in a tooltip, or nothing.
34
+ - `listeningColor`: `'primary' | 'danger' | 'success' | 'warning' | 'info'` = `'primary'` - colour of
35
+ "stop" and the wave while listening (the theme colour by default). Any other colour: set
36
+ `--kpt-speech-color` and `--kpt-speech-on-color` (icon on it) - both inherit, so they also work on
37
+ fields with a built-in microphone or globally in `:root`.
38
+ - `disabled`, `size` (`KptButtonSize`), `variant` = `'text'`,
39
+ `ariaLabel` (default "Dictate" from the dictionary), `tabIndex` (for roving toolbars).
40
+
41
+ ## Outputs and methods
42
+ - `(started)`, `(finished)` -> `KptSpeechEndReason` (`stopped | silence | max-duration | aborted | ended | error`),
43
+ `(result)` -> `KptSpeechSnapshot` (`{ finalText, interimText }`), `(failed)` -> `KptSpeechErrorCode`.
44
+ - `exportAs: 'kptSpeech'`: `status()`, `listening()`, `available()`, `start()`, `stop()` (graceful), `flush()` (interim
45
+ becomes final and dictation ends at once - call it before sending), `abort()`, `toggle()`.
46
+
47
+ ## Examples
48
+ <textarea #note></textarea>
49
+ <kpt-speech-button [target]="note" />
50
+
51
+ <input #query type="search" />
52
+ <kpt-speech-button [target]="query" mode="replace" [continuous]="false" wavePosition="end" />
53
+
54
+ <kpt-speech-button [target]="onSnapshot" lang="en-US" (finished)="save()" />
55
+
56
+ <kpt-speech-button #mic="kptSpeech" [target]="draft" />
57
+ <kpt-button (click)="mic.flush(); send()">Send</kpt-button>
58
+
59
+ ## Built into fields
60
+ The same microphone is built into `kpt-input`, `kpt-textarea` and `kpt-chat-composer` with the
61
+ `speech` input (`speechLang`, `speechMode`, `speechColor`), into `kpt-rich-text` as the `dictate` tool, and into the
62
+ search fields: `kpt-autocomplete` (`speech`, default `replace`), `kpt-data-table` (`filterSpeech`) and
63
+ `kpt-map` / `kpt-map-search` (`searchSpeech` / `speech`) - search fields clear on click and listen
64
+ for one utterance. Embedded microphones use `unsupported="hide"`, and the
65
+ field reserves room for the button only when `available()` is true.
66
+
67
+ ## Own components as targets
68
+ A component that knows where text goes (its own selection, its own model) implements
69
+ `KptSpeechTargetProvider` - `speechTarget()` returns a `KptSpeechTarget` (`begin(mode)`,
70
+ `interim(text)`, `commit(text)`, `end()`) or an element. `resolveSpeechTarget()` from the core builds
71
+ the default adapters.
72
+
73
+ ## KptSpeechWave
74
+ Bars next to the microphone, `aria-hidden`. `levels: readonly number[]` (0..1) draws a live wave;
75
+ empty `levels` gives the synthetic one, higher while `active` (voice heard). `bars`: number = 5.
76
+ Colour: `--kpt-speech-wave-color`, otherwise the listening colour of the button (matching "stop").
77
+
78
+ ## Behaviour
79
+ - One dictation per page: starting a microphone stops the previous one.
80
+ - Continuous mode survives Chrome ending recognition after silence or about a minute - the session
81
+ restarts the engine, and ends as `silence` after several empty restarts. On iOS a restart without a
82
+ tap is unreliable, so the button stops and announces "Tap the microphone to continue".
83
+ - The user types or moves the caret mid-dictation: interim text disappears and dictation continues
84
+ at the new caret.
85
+ - A hidden tab stops dictation; leaving the page releases the microphone.
86
+
87
+ ## Screen reader and keyboard
88
+ - The button name stays the same ("Dictate"); the state is carried by `aria-pressed`, the icon swaps
89
+ between `microphone` and `player-stop`.
90
+ - A polite live region announces start, stop and errors - never the transcript (a screen reader
91
+ reading it would be recorded by the microphone).
92
+ - Clicking the button does not move focus out of the target, so the caret stays where text goes.
93
+ - Escape on the button or in the target stops dictation.
94
+
95
+ ## Motion
96
+ The wave slides in with `--kpt-motion-duration-base`. The synthetic wave is a state indicator like
97
+ the typing dots: with motion off (`provideKptMotion({ enabled: false })`) or "reduce motion" it turns
98
+ into a slow pulse instead of stopping. The live wave keeps showing the level, without smoothing.
99
+
100
+ ## Browsers and privacy
101
+ Chrome, Edge and Safari recognise speech; Firefox does not. A secure context (`https:` or `localhost`)
102
+ is required. Chrome sends audio to a Google service unless `processLocally` is set - mention it in the
103
+ privacy policy.
104
+
105
+ ## Tokens
106
+ `--kpt-color-primary` / `--kpt-color-on-primary` (stop and wave, by `listeningColor`; overridden by
107
+ `--kpt-speech-color` / `--kpt-speech-on-color`), `--kpt-color-text-muted` (interim text in `.kpt-speech-ghost`
108
+ and `.kpt-speech-interim`), button tokens shared with `kpt-icon-button`.