@konce-pt/angular 0.11.2 → 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.
- package/CHANGELOG.md +792 -333
- package/README.md +111 -55
- package/charts/src/lib/llms.txt +23 -15
- package/chat/src/lib/llms.txt +68 -33
- package/fesm2022/konce-pt-angular-charts.mjs +149 -68
- package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-chat.mjs +296 -135
- package/fesm2022/konce-pt-angular-chat.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-grid.mjs +16 -16
- package/fesm2022/konce-pt-angular-grid.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-icons.mjs +5 -5
- package/fesm2022/konce-pt-angular-icons.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-map.mjs +360 -293
- package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-roadmap.mjs +120 -34
- package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
- package/fesm2022/konce-pt-angular.mjs +7117 -3373
- package/fesm2022/konce-pt-angular.mjs.map +1 -1
- package/grid/src/lib/llms.txt +18 -18
- package/map/src/lib/llms.txt +142 -140
- package/package.json +14 -12
- package/roadmap/src/lib/llms.txt +37 -27
- package/src/lib/accordion/llms.txt +18 -6
- package/src/lib/alert/llms.txt +5 -4
- package/src/lib/app-shell/llms.txt +25 -22
- package/src/lib/auth/llms.txt +26 -22
- package/src/lib/autocomplete/llms.txt +18 -4
- package/src/lib/avatar/llms.txt +3 -3
- package/src/lib/avatar-group/llms.txt +5 -5
- package/src/lib/backdrop/llms.txt +35 -35
- package/src/lib/badge/llms.txt +7 -7
- package/src/lib/bottom-sheet/llms.txt +6 -3
- package/src/lib/breadcrumb/llms.txt +9 -1
- package/src/lib/breakpoint/llms.txt +8 -8
- package/src/lib/button/llms.txt +26 -18
- package/src/lib/button-group/llms.txt +40 -31
- package/src/lib/card/llms.txt +19 -19
- package/src/lib/carousel/llms.txt +6 -6
- package/src/lib/checkbox/llms.txt +17 -2
- package/src/lib/chip/llms.txt +6 -6
- package/src/lib/chips-input/llms.txt +14 -4
- package/src/lib/color-picker/llms.txt +7 -4
- package/src/lib/confirm/llms.txt +9 -3
- package/src/lib/context-menu/llms.txt +7 -4
- package/src/lib/data-table/llms.txt +280 -227
- package/src/lib/data-view/llms.txt +25 -4
- package/src/lib/date-range/llms.txt +37 -18
- package/src/lib/datepicker/llms.txt +46 -29
- package/src/lib/dialog/llms.txt +29 -26
- package/src/lib/divider/llms.txt +2 -1
- package/src/lib/drawer/llms.txt +9 -6
- package/src/lib/empty/llms.txt +4 -4
- package/src/lib/fab/llms.txt +6 -2
- package/src/lib/fieldset/llms.txt +22 -4
- package/src/lib/file-upload/llms.txt +3 -0
- package/src/lib/form-field/llms.txt +33 -19
- package/src/lib/galleria/llms.txt +3 -3
- package/src/lib/i18n/llms.txt +15 -8
- package/src/lib/icon/llms.txt +9 -9
- package/src/lib/icon-button/llms.txt +8 -3
- package/src/lib/image/llms.txt +4 -4
- package/src/lib/input/llms.txt +21 -7
- package/src/lib/input-mask/llms.txt +5 -2
- package/src/lib/input-number/llms.txt +18 -15
- package/src/lib/input-otp/llms.txt +15 -4
- package/src/lib/knob/llms.txt +14 -7
- package/src/lib/listbox/llms.txt +8 -5
- package/src/lib/loader/llms.txt +72 -0
- package/src/lib/megamenu/llms.txt +16 -5
- package/src/lib/mention/llms.txt +15 -15
- package/src/lib/menu/llms.txt +12 -12
- package/src/lib/menubar/llms.txt +16 -5
- package/src/lib/meter-group/llms.txt +7 -7
- package/src/lib/order-list/llms.txt +20 -5
- package/src/lib/paginator/llms.txt +5 -5
- package/src/lib/panel/llms.txt +20 -8
- package/src/lib/password/llms.txt +17 -5
- package/src/lib/peek/llms.txt +11 -11
- package/src/lib/pick-list/llms.txt +28 -5
- package/src/lib/popover/llms.txt +9 -6
- package/src/lib/progress/llms.txt +16 -16
- package/src/lib/radio-group/llms.txt +13 -3
- package/src/lib/rating/llms.txt +13 -6
- package/src/lib/rich-text/llms.txt +42 -24
- package/src/lib/scroll-top/llms.txt +3 -3
- package/src/lib/select/llms.txt +23 -13
- package/src/lib/sidenav/llms.txt +8 -8
- package/src/lib/slider/llms.txt +23 -7
- package/src/lib/speech/llms.txt +108 -0
- package/src/lib/speed-dial/llms.txt +9 -3
- package/src/lib/spinner/llms.txt +2 -2
- package/src/lib/split-button/llms.txt +14 -8
- package/src/lib/splitter/llms.txt +8 -8
- package/src/lib/stepper/llms.txt +26 -7
- package/src/lib/switch/llms.txt +13 -3
- package/src/lib/switch-group/llms.txt +12 -9
- package/src/lib/tabs/llms.txt +7 -4
- package/src/lib/textarea/llms.txt +16 -5
- package/src/lib/timeline/llms.txt +1 -1
- package/src/lib/toast/llms.txt +36 -5
- package/src/lib/toolbar/llms.txt +3 -3
- package/src/lib/tooltip/llms.txt +13 -10
- package/src/lib/tree/llms.txt +19 -5
- package/src/lib/update/llms.txt +52 -0
- package/types/konce-pt-angular-charts.d.ts +11 -0
- package/types/konce-pt-angular-charts.d.ts.map +1 -1
- package/types/konce-pt-angular-chat.d.ts +98 -40
- package/types/konce-pt-angular-chat.d.ts.map +1 -1
- package/types/konce-pt-angular-grid.d.ts +14 -14
- package/types/konce-pt-angular-icons.d.ts +3 -3
- package/types/konce-pt-angular-map.d.ts +147 -119
- package/types/konce-pt-angular-map.d.ts.map +1 -1
- package/types/konce-pt-angular-roadmap.d.ts +34 -9
- package/types/konce-pt-angular-roadmap.d.ts.map +1 -1
- package/types/konce-pt-angular.d.ts +1774 -651
- 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
|
|
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
|
|
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
|
|
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)
|
|
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')
|
|
36
|
-
- `diameter`: number (default 40)
|
|
37
|
-
- `bufferValue`: number|null (default null)
|
|
38
|
-
- `showValue`: boolean (default false)
|
|
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
|
|
41
|
-
- `labelPosition`: 'top'|'bottom'|'end' (default 'top')
|
|
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
|
|
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`
|
|
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`
|
|
62
|
-
buffer is never allowed behind the main bar
|
|
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
|
|
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,17 +10,27 @@ 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'
|
|
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
|
|
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` (
|
|
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`.
|
|
34
|
+
|
|
35
|
+
## Read-only and required
|
|
36
|
+
`readonly` blocks the click and the arrow keys (natively they move the selection); the group gets `aria-readonly`.
|
package/src/lib/rating/llms.txt
CHANGED
|
@@ -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
|
|
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
|
|
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}`)
|
|
19
|
-
PL `1 z 5`. One Tab stop:
|
|
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"
|
|
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
|
|
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
|
|
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,55 +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
|
|
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[]`
|
|
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
|
|
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`
|
|
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
|
|
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)
|
|
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.
|
|
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
|
|
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)
|
|
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
|
|
46
|
-
table/cell borders
|
|
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
|
|
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
|
-
|
|
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.
|
|
62
|
+
- Tool panels open in the overlay container at the end of `<body>`, so focus moves into them:
|
|
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
|
|
66
|
+
panel). `Escape` closes any of them and returns focus to the tool.
|
|
57
67
|
- Tab / Shift+Tab inside a list item = indent / one level up (the same as `indent`/`outdent`).
|
|
58
68
|
- Tab / Shift+Tab inside a table cell = the next / previous cell (with its content selected).
|
|
59
|
-
A list inside a cell takes precedence
|
|
60
|
-
- Everywhere else
|
|
61
|
-
and in the last table cell
|
|
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:
|
|
62
72
|
an editor must not be a keyboard trap (WCAG 2.1.2), so `preventDefault()` is called only
|
|
63
73
|
when the operation actually changed the content.
|
|
64
74
|
|
|
@@ -68,17 +78,22 @@ they are inert, so they open no new door.
|
|
|
68
78
|
|
|
69
79
|
## i18n
|
|
70
80
|
Every label (the tools' aria text, the "Normal/Heading N" styles, the link prompt, the table context menu,
|
|
71
|
-
the border popover, "Custom
|
|
72
|
-
`richText.border.*`). English by default
|
|
81
|
+
the border popover, "Custom...") comes from i18n (the `richText` namespace, including `richText.menu.*`,
|
|
82
|
+
`richText.border.*`). English by default - see `i18n/llms.txt`.
|
|
73
83
|
|
|
74
84
|
## Notes
|
|
75
85
|
Formatting goes through document.execCommand; active tools are highlighted (queryCommandState).
|
|
76
86
|
Pasting (both native and through the buttons) is sanitized (a tag/style allowlist; it strips script/on*/javascript:).
|
|
77
|
-
Sanitization covers **every** write into the editor's DOM, not just paste
|
|
87
|
+
Sanitization covers **every** write into the editor's DOM, not just paste - including a `value` set from
|
|
78
88
|
outside (`[(value)]`/`formField` from the application, the HTML source mode). Treat an incoming `value` as
|
|
79
89
|
potentially untrusted (a database, another user, a CMS); on the way out of the component it is sanitized.
|
|
90
|
+
Links keep only relative addresses and `http(s):`, `mailto:`, `tel:` - the same allowlist as the link tool, so
|
|
91
|
+
`data:`, `vbscript:` or `blob:` from a paste are dropped. `class` keeps only the editor's own classes
|
|
92
|
+
(`kpt-rt-*`, `kpt-mention`), a link with `target` always gets `rel="noopener noreferrer"`, and when the
|
|
93
|
+
sanitizer removed something, the cleaned HTML is written back to `value` - the model never holds the
|
|
94
|
+
unsafe original (a pure formatting difference does not touch it, so a clean value does not dirty a form).
|
|
80
95
|
The "paste"/"paste without formatting" clipboard tools use the async Clipboard API (which needs browser permission).
|
|
81
|
-
An exception to execCommand: list indentation is done with our own DOM code
|
|
96
|
+
An exception to execCommand: list indentation is done with our own DOM code - `execCommand('indent')` produces
|
|
82
97
|
invalid `ul > ul` in Chrome (or a `blockquote` with a margin, which the sanitizer would strip anyway).
|
|
83
98
|
|
|
84
99
|
## Screen reader and keyboard
|
|
@@ -90,8 +105,11 @@ goes back to the cell. Colour swatches are named ("Dark grey", `richText.swatche
|
|
|
90
105
|
their hex codes. The table size grid is still mouse-only.
|
|
91
106
|
|
|
92
107
|
## Label and description
|
|
93
|
-
`id` goes to the focusable element
|
|
108
|
+
`id` goes to the focusable element - the host never carries it; without one it is generated. A `div`
|
|
94
109
|
with a role is not named by `label[for]`, so inside `kpt-form-field` it gets `aria-labelledby`
|
|
95
110
|
pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error is added to
|
|
96
|
-
`aria-describedby`. No `controlId` needed. New: `id`, `ariaLabel` and `required` (
|
|
111
|
+
`aria-describedby`. No `controlId` needed. New: `id`, `ariaLabel` and `required` (-> `aria-required`)
|
|
97
112
|
on the `role="textbox"` area.
|
|
113
|
+
|
|
114
|
+
## Read-only and required
|
|
115
|
+
`readonly` keeps the content selectable and copyable but not editable (`aria-readonly`); the toolbar is disabled.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# KptScrollTop (kpt-scroll-top)
|
|
2
2
|
|
|
3
|
-
A "back to top" button
|
|
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
|
|
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
|
|
27
|
+
the jump - move it to your page heading if that matters.
|
package/src/lib/select/llms.txt
CHANGED
|
@@ -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
|
|
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)
|
|
20
|
-
the list from outside and know when the user is done choosing
|
|
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
|
|
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:
|
|
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:
|
|
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,15 +44,25 @@ be read from the DOM). Nothing needs configuring:
|
|
|
44
44
|
</kpt-form-field>
|
|
45
45
|
|
|
46
46
|
## i18n
|
|
47
|
-
The "Search
|
|
48
|
-
English by default; configured through `provideKptI18n`
|
|
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
|
|
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` (
|
|
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}`.
|
|
66
|
+
|
|
67
|
+
## Read-only and required
|
|
68
|
+
`readonly` shows the choice, but the panel does not open and the chips have no remove button (`aria-readonly`). The filter ignores case and diacritics ("lodz" finds "Łódź"), as in `listbox`. "No results" sits next to the list, not inside it (a listbox may contain only options).
|
package/src/lib/sidenav/llms.txt
CHANGED
|
@@ -1,20 +1,20 @@
|
|
|
1
1
|
# KptSidenav (kpt-sidenav)
|
|
2
2
|
|
|
3
|
-
A side panel
|
|
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)
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
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
|
package/src/lib/slider/llms.txt
CHANGED
|
@@ -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]>
|
|
7
|
-
- `range`: boolean
|
|
8
|
-
- Under `[formField]` do NOT bind the bounds
|
|
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
|
|
22
|
-
- The handles cannot cross
|
|
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")
|
|
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
|
|
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,5 +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`.
|
|
52
|
+
|
|
53
|
+
## Read-only and required
|
|
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`.
|