@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.
Files changed (116) hide show
  1. package/CHANGELOG.md +792 -333
  2. package/README.md +111 -55
  3. package/charts/src/lib/llms.txt +23 -15
  4. package/chat/src/lib/llms.txt +68 -33
  5. package/fesm2022/konce-pt-angular-charts.mjs +149 -68
  6. package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
  7. package/fesm2022/konce-pt-angular-chat.mjs +296 -135
  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 +360 -293
  14. package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
  15. package/fesm2022/konce-pt-angular-roadmap.mjs +120 -34
  16. package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
  17. package/fesm2022/konce-pt-angular.mjs +7117 -3373
  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 -140
  21. package/package.json +14 -12
  22. package/roadmap/src/lib/llms.txt +37 -27
  23. package/src/lib/accordion/llms.txt +18 -6
  24. package/src/lib/alert/llms.txt +5 -4
  25. package/src/lib/app-shell/llms.txt +25 -22
  26. package/src/lib/auth/llms.txt +26 -22
  27. package/src/lib/autocomplete/llms.txt +18 -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 +6 -3
  33. package/src/lib/breadcrumb/llms.txt +9 -1
  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 +40 -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 +17 -2
  40. package/src/lib/chip/llms.txt +6 -6
  41. package/src/lib/chips-input/llms.txt +14 -4
  42. package/src/lib/color-picker/llms.txt +7 -4
  43. package/src/lib/confirm/llms.txt +9 -3
  44. package/src/lib/context-menu/llms.txt +7 -4
  45. package/src/lib/data-table/llms.txt +280 -227
  46. package/src/lib/data-view/llms.txt +25 -4
  47. package/src/lib/date-range/llms.txt +37 -18
  48. package/src/lib/datepicker/llms.txt +46 -29
  49. package/src/lib/dialog/llms.txt +29 -26
  50. package/src/lib/divider/llms.txt +2 -1
  51. package/src/lib/drawer/llms.txt +9 -6
  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 +3 -0
  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 +15 -8
  59. package/src/lib/icon/llms.txt +9 -9
  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 +5 -2
  64. package/src/lib/input-number/llms.txt +18 -15
  65. package/src/lib/input-otp/llms.txt +15 -4
  66. package/src/lib/knob/llms.txt +14 -7
  67. package/src/lib/listbox/llms.txt +8 -5
  68. package/src/lib/loader/llms.txt +72 -0
  69. package/src/lib/megamenu/llms.txt +16 -5
  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 +16 -5
  73. package/src/lib/meter-group/llms.txt +7 -7
  74. package/src/lib/order-list/llms.txt +20 -5
  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 +17 -5
  78. package/src/lib/peek/llms.txt +11 -11
  79. package/src/lib/pick-list/llms.txt +28 -5
  80. package/src/lib/popover/llms.txt +9 -6
  81. package/src/lib/progress/llms.txt +16 -16
  82. package/src/lib/radio-group/llms.txt +13 -3
  83. package/src/lib/rating/llms.txt +13 -6
  84. package/src/lib/rich-text/llms.txt +42 -24
  85. package/src/lib/scroll-top/llms.txt +3 -3
  86. package/src/lib/select/llms.txt +23 -13
  87. package/src/lib/sidenav/llms.txt +8 -8
  88. package/src/lib/slider/llms.txt +23 -7
  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 +26 -7
  95. package/src/lib/switch/llms.txt +13 -3
  96. package/src/lib/switch-group/llms.txt +12 -9
  97. package/src/lib/tabs/llms.txt +7 -4
  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 +36 -5
  101. package/src/lib/toolbar/llms.txt +3 -3
  102. package/src/lib/tooltip/llms.txt +13 -10
  103. package/src/lib/tree/llms.txt +19 -5
  104. package/src/lib/update/llms.txt +52 -0
  105. package/types/konce-pt-angular-charts.d.ts +11 -0
  106. package/types/konce-pt-angular-charts.d.ts.map +1 -1
  107. package/types/konce-pt-angular-chat.d.ts +98 -40
  108. package/types/konce-pt-angular-chat.d.ts.map +1 -1
  109. package/types/konce-pt-angular-grid.d.ts +14 -14
  110. package/types/konce-pt-angular-icons.d.ts +3 -3
  111. package/types/konce-pt-angular-map.d.ts +147 -119
  112. package/types/konce-pt-angular-map.d.ts.map +1 -1
  113. package/types/konce-pt-angular-roadmap.d.ts +34 -9
  114. package/types/konce-pt-angular-roadmap.d.ts.map +1 -1
  115. package/types/konce-pt-angular.d.ts +1774 -651
  116. package/types/konce-pt-angular.d.ts.map +1 -1
@@ -1,29 +1,30 @@
1
1
  # KptFormField (kpt-form-field)
2
2
 
3
3
  A form field wrapper: the label, the hint and the error message around any control
4
- (`kpt-input`, for instance). Presentational — the error state is passed in through `error`.
4
+ (`kpt-input`, for instance). Presentational - the error state is passed in through `error`.
5
5
  Import: `import { KptFormField } from '@konce-pt/angular';`
6
6
 
7
7
  ## Selector
8
8
  `kpt-form-field`
9
9
 
10
10
  ## Inputs (input signals)
11
- - `label`: string — the label text
12
- - `hint`: string — a hint (hidden while there is an error)
13
- - `error`: string | null — the error message; when non-empty, the field is marked invalid
14
- - `required`: boolean — an asterisk next to the label
15
- - `controlId`: string — optional; the control's id for `label[for]` (library controls report theirs)
16
- - `labelType`: 'fixed' | 'over' | 'in' | 'on' — the label variant (default `fixed`)
11
+ - `label`: string - the label text
12
+ - `hint`: string - a hint (hidden while there is an error)
13
+ - `error`: string | null - the error message; when non-empty, the field is marked invalid
14
+ - `required`: boolean - an asterisk next to the label
15
+ - `controlId`: string - optional; the control's id for `label[for]` (library controls report theirs)
16
+ - `labelType`: 'fixed' | 'over' | 'in' | 'on' - the label variant (default `fixed`)
17
+ - `enterMotion`: 'spring' | 'fade' | 'none' - how the message and the error appear (default from `provideKptMotion`, else `spring`)
17
18
 
18
19
  ## Label variants (labelType)
19
- - `fixed` (the default) — a static label above the control (as before).
20
- - `over` — a float label: the label rises above the field's border.
21
- - `in` — a float label: the label rises into the upper part inside the field (a taller field, the "filled" style).
22
- - `on` — a float label: the label sits on the top border (a notch, the "outlined" style).
20
+ - `fixed` (the default) - a static label above the control (as before).
21
+ - `over` - a float label: the label rises above the field's border.
22
+ - `in` - a float label: the label rises into the upper part inside the field (a taller field, the "filled" style).
23
+ - `on` - a float label: the label sits on the top border (a notch, the "outlined" style).
23
24
 
24
- The float variants animate the label's transition (from its resting position where the placeholder is →
25
+ The float variants animate the label's transition (from its resting position where the placeholder is ->
25
26
  raised). It rises when the control takes focus **or** when the field has a value. Detecting whether
26
- it is filled happens inside the component (`input`/`change` events + the initial value) — it does **not**
27
+ it is filled happens inside the component (`input`/`change` events + the initial value) - it does **not**
27
28
  require setting a placeholder on the control.
28
29
 
29
30
  <kpt-form-field label="E-mail" labelType="over">
@@ -33,7 +34,7 @@ require setting a placeholder on the control.
33
34
  ### Controls with no native `input`/`textarea`
34
35
 
35
36
  The value of `kpt-select` cannot be read from the DOM (the panel lives in an overlay), so such a control
36
- reports being filled itself — it provides the `KPT_FORM_FIELD_CONTROL` token with a `filled` signal.
37
+ reports being filled itself - it provides the `KPT_FORM_FIELD_CONTROL` token with a `filled` signal.
37
38
  `kpt-select` does this out of the box; a custom control needs:
38
39
 
39
40
  import { KPT_FORM_FIELD_CONTROL, type KptFormFieldControl } from '@konce-pt/angular';
@@ -46,15 +47,15 @@ reports being filled itself — it provides the `KPT_FORM_FIELD_CONTROL` token w
46
47
  }
47
48
 
48
49
  Once a control provides the token, `kpt-form-field` stops looking into the DOM and trusts the
49
- `filled` signal alone — which is why the label rises the instant the value changes.
50
+ `filled` signal alone - which is why the label rises the instant the value changes.
50
51
 
51
52
  ## Linking the control (label, hint, error)
52
53
  `kpt-form-field` provides the `KPT_FORM_FIELD` context to its content, and every library control
53
54
  uses it: the control reports its `id` (its own, or a generated one) and `label[for]` points at it,
54
55
  so **`controlId` is optional**. A control on a `div` with a role (`kpt-select`, `kpt-datepicker`,
55
- `kpt-radio-group`, `kpt-rich-text`…) is not named by `label[for]`, so it gets `aria-labelledby`
56
+ `kpt-radio-group`, `kpt-rich-text`...) is not named by `label[for]`, so it gets `aria-labelledby`
56
57
  pointing at the label. The visible hint or error has an `id` and lands in the control's
57
- `aria-describedby` — a screen reader hears it when it reaches the field, not only when the error appears.
58
+ `aria-describedby` - a screen reader hears it when it reaches the field, not only when the error appears.
58
59
 
59
60
  A custom control links itself with `kptFieldA11y`:
60
61
 
@@ -82,11 +83,24 @@ The control goes into the content (ng-content):
82
83
  return s.touched() && s.invalid() ? s.errors()[0]?.message ?? null : null;
83
84
  });
84
85
 
85
- The `touched()` gate applies to the message only — do not gate the validators (`when:` on
86
+ The `touched()` gate applies to the message only - do not gate the validators (`when:` on
86
87
  `state.touched()` makes `valid()` lie on an untouched form). The `kpt-*` controls gate their own
87
88
  visual state the same way. The full submit flow: the
88
89
  `## A form from scratch (Signal Forms)` section in the root llms.txt.
89
90
 
91
+ ## Motion
92
+ `enterMotion` (`spring | fade | none`):
93
+ - the message under the field enters on every change - hint -> error, error A -> error B - sliding in
94
+ from above and sharpening out of a blur (`fade`: only fades); each new error is a new element, so it
95
+ is also announced again;
96
+ - `spring` only: the control shakes briefly when the field turns invalid - not when the error text
97
+ changes and not for an error present on load; the floating label rises on a spring.
98
+
99
+ Messages present on the first render do not animate. With no value it takes `enter` from `provideKptMotion`
100
+ (default `spring`); `enabled: false` and the system "reduce motion" setting always win. Every form
101
+ control's surface (border, focus ring, background) changes smoothly on hover, focus and error - a shared
102
+ rule, independent of this input.
103
+
90
104
  ## Tokens
91
105
  `--kpt-form-field-label`, `--kpt-form-field-hint`, `--kpt-form-field-error`, `--kpt-color-danger`.
92
106
  The float variants add: `--kpt-form-field-placeholder` (the resting label),
@@ -97,4 +111,4 @@ The float variants add: `--kpt-form-field-placeholder` (the resting label),
97
111
  ## Accessibility
98
112
  - The error message carries `role="alert"`.
99
113
  - The label, hint and error are linked to the control automatically (`label[for]` or `aria-labelledby`,
100
- plus `aria-describedby`) — see "Linking the control" above.
114
+ plus `aria-describedby`) - see "Linking the control" above.
@@ -4,7 +4,7 @@ A large image preview with a thumbnail strip and navigation.
4
4
  Import: `import { KptGalleria } from '@konce-pt/angular';`
5
5
 
6
6
  ## Inputs / model
7
- - `items`: KptGalleriaItem[] — { src, thumbnail?, alt? }
7
+ - `items`: KptGalleriaItem[] - { src, thumbnail?, alt? }
8
8
  - `activeIndex`: model<number> (two-way)
9
9
  - `showThumbnails`: boolean (default true)
10
10
 
@@ -20,8 +20,8 @@ The stage `--kpt-color-muted`; the active thumbnail `--kpt-color-primary`; the a
20
20
 
21
21
  ## Accessibility
22
22
  The large image carries its `alt`. Each thumbnail is a button named by the item's `alt` (or
23
- `galleria.image` — “Image 3” — when there is none), with `alt=""` on the thumbnail image so the
23
+ `galleria.image` - "Image 3" - when there is none), with `alt=""` on the thumbnail image so the
24
24
  name is not read twice; the active one carries `aria-current`. The arrows use `aria-disabled` at
25
25
  the ends instead of `disabled`, so they keep the focus. A change of image is announced politely
26
- through a hidden live region — `galleria.position` (“Image 2 of 4”) plus the `alt` — only after the
26
+ through a hidden live region - `galleria.position` ("Image 2 of 4") plus the `alt` - only after the
27
27
  user acts, never on first render.
@@ -4,15 +4,15 @@ Translations for component labels. Base languages: EN (default), PL. Signal-base
4
4
  Import: `import { provideKptI18n, KptI18n } from '@konce-pt/angular';`
5
5
 
6
6
  ## Configuration (provider)
7
- - `provideKptI18n({ locale?, messages? }): EnvironmentProviders` — in `bootstrapApplication`.
7
+ - `provideKptI18n({ locale?, messages? }): EnvironmentProviders` - in `bootstrapApplication`.
8
8
  - `locale`: 'en' | 'pl' | any string (default 'en').
9
- - `messages`: `Record<locale, DeepPartial<KptMessages>>` — registers a new language or overrides an existing one (deep merge, missing keys fall back to EN).
9
+ - `messages`: `Record<locale, DeepPartial<KptMessages>>` - registers a new language or overrides an existing one (deep merge, missing keys fall back to EN).
10
10
 
11
11
  ## The KptI18n service (providedIn: 'root')
12
- - `locale: Signal<KptLocale>` — the current language.
13
- - `setLocale(locale)` — a runtime change (reactive across every component).
14
- - `registerMessages(locale, patch)` — adds to or overrides a dictionary at runtime.
15
- - `t(key, params?)` — translates a dotted key (`'paginator.range'`) with `{name}` interpolation.
12
+ - `locale: Signal<KptLocale>` - the current language.
13
+ - `setLocale(locale)` - a runtime change (reactive across every component).
14
+ - `registerMessages(locale, patch)` - adds to or overrides a dictionary at runtime.
15
+ - `t(key, params?)` - translates a dotted key (`'paginator.range'`) with `{name}` interpolation.
16
16
 
17
17
  ## Adding your own language (one JSON file)
18
18
  import de from './i18n/de.json'; // the shape is the KptMessages interface
@@ -31,11 +31,18 @@ Namespaces: `common` (close/remove/previous/next/clear/done/all), `paginator` (r
31
31
  `richText.styleHeading` ({level}), `auth.continueWith` ({provider}), `auth.passwordHint` and `auth.errorMinLength` ({min}), `rating.star` ({value},{max}), `panel.toggleNamed` ({header}), `stepper.step*` ({index},{label}), `carousel.slideOf` and `galleria.position` ({index},{total}), `image.previewOf` ({alt}), `avatarGroup.more` ({count}), `inputOtp.cell` ({index},{count}), `autocomplete.results` ({count}), `chipsInput.added`/`removed`/`duplicate` ({value}), `dateRange.rangeStart`/`rangeEnd`/`inRange`/`pickEnd` ({date}) and `dateRange.picked` ({start},{end}). Day and month names in calendars are derived from `Intl` per locale (not from the dictionary).
32
32
 
33
33
  ## Note
34
- Individual labels can also be overridden per component through the matching `input()` (e.g. `emptyMessage`, `acceptLabel`) —
34
+ Individual labels can also be overridden per component through the matching `input()` (e.g. `emptyMessage`, `acceptLabel`) -
35
35
  the input takes priority over the i18n dictionary.
36
36
 
37
37
  ## Where the dictionaries live
38
38
  The contract (`KptMessages`), the base EN/PL dictionaries and the translation core (`translate`, `deepMerge`)
39
- live in `@konce-pt/i18n` — a pure-TypeScript package with no framework dependency, shared with the React port
39
+ live in `@konce-pt/i18n` - a pure-TypeScript package with no framework dependency, shared with the React port
40
40
  so both render identical labels. `@konce-pt/angular` re-exports all of it, so the imports above stay unchanged;
41
41
  you never need to install `@konce-pt/i18n` yourself.
42
+
43
+ ## Runtime dictionaries, keys and the page language
44
+ `registerMessages()` after start-up (a lazily loaded JSON) repaints the components at once, also for the
45
+ active language. `t()` accepts `KptMessageKey` (the base dictionary's dotted keys, with editor
46
+ completion) or any string; a key found in no dictionary returns the key itself and, in a dev build,
47
+ warns once in the console. The library does not set `<html lang>` - set it yourself together with the
48
+ language, so a screen reader reads the labels with the right pronunciation.
@@ -1,17 +1,17 @@
1
1
  # KptIcon (kpt-icon)
2
2
 
3
- An inline SVG icon (the Tabler Icons set — MIT). The size is inherited from `font-size` (1em),
3
+ An inline SVG icon (the Tabler Icons set - MIT). The size is inherited from `font-size` (1em),
4
4
  the color from `currentColor`. Import: `import { KptIcon } from '@konce-pt/angular';`
5
5
 
6
6
  ## Selector
7
7
  `kpt-icon`
8
8
 
9
9
  ## Inputs
10
- - `name`: string (required) — an icon name from the registry. Deliberately not a union of the
10
+ - `name`: string (required) - an icon name from the registry. Deliberately not a union of the
11
11
  built-in names: once the Tabler set is registered there are 5130 legal names, so a closed
12
12
  union would reject icons that work at runtime.
13
- - `size`: string (optional, e.g. '1.25rem') — otherwise inherited from font-size
14
- - `label`: string — a name for screen readers; with it the icon is `role="img"`, without it `aria-hidden`
13
+ - `size`: string (optional, e.g. '1.25rem') - otherwise inherited from font-size
14
+ - `label`: string - a name for screen readers; with it the icon is `role="img"`, without it `aria-hidden`
15
15
 
16
16
  ## Available names (built in, no configuration)
17
17
  menu, x, chevron-up, chevron-down, chevron-left, chevron-right, check, search
@@ -25,7 +25,7 @@ adjustments-horizontal, sun, moon, bell, settings, users, user-circle, logout, l
25
25
  layout-dashboard, home, activity, cube, shopping-cart, currency-dollar, arrow-left
26
26
  arrow-right, arrow-up-right, arrow-down-right, chart-bar, chart-line, filter, download
27
27
  refresh, dots, brand-github, brand-google, layout-grid, grid-dots, checks, paperclip
28
- send, message-circle, corner-up-left, mood-smile, device-floppy, arrow-back-up, printer
28
+ send, message-circle, corner-up-left, mood-smile, device-floppy, arrow-back-up, printer, selector
29
29
 
30
30
  These cover both what the components themselves draw and the staples of an application shell
31
31
  (theme, notifications, account, navigation, KPI). A typical admin panel needs nothing else.
@@ -47,14 +47,14 @@ so importing by name lets the bundler keep only what you used:
47
47
 
48
48
  `provideKptIcons` lives in the core entry point on purpose: `@konce-pt/angular/icons` imports the whole set
49
49
  statically, so a subset parameter there could not shrink anything. Passing the namespace object
50
- (`import * as tabler`) also registers everything — a namespace handed to a function blocks static
50
+ (`import * as tabler`) also registers everything - a namespace handed to a function blocks static
51
51
  analysis, so it is the explicit form of the prototype path, not a smaller one.
52
52
 
53
53
  Export names are PascalCase because `kebab-case` is not a legal identifier and camelCase would
54
54
  collide with keywords (`function`, `package`, `switch`). Each icon carries its own registry name,
55
55
  so `BrandHtml5` registers as `brand-html5`.
56
56
 
57
- You can also register your own through `KptIconRegistry.register({ name: 'inner svg' })` — the content is
57
+ You can also register your own through `KptIconRegistry.register({ name: 'inner svg' })` - the content is
58
58
  sanitized down to an allowlist of SVG geometry (`path`/`circle`/`rect`/`g`/`line`/`polygon`/`polyline`/
59
59
  `ellipse` + shape/style attributes), but `register()` may only be called with content the developer controls
60
60
  at build time, never straight from runtime/CMS/upload data.
@@ -67,10 +67,10 @@ at build time, never straight from runtime/CMS/upload data.
67
67
 
68
68
  ## Icon license
69
69
  Tabler Icons (MIT). The icons are extracted inline into `icons.ts`. See ICONS-LICENSE at the root.
70
- Adding an icon: add an entry to `KPT_ICONS`/`KptIconName` (a 24×24 grid, 2px stroke).
70
+ Adding an icon: add an entry to `KPT_ICONS`/`KptIconName` (a 24x24 grid, 2px stroke).
71
71
 
72
72
  ## Accessibility
73
- By default an icon is `aria-hidden` — decorative, which is right next to a text label or inside
73
+ By default an icon is `aria-hidden` - decorative, which is right next to a text label or inside
74
74
  an icon button with its own name. An icon that carries meaning on its own gets `label`: it becomes
75
75
  `role="img"` with that `aria-label`. In development builds an unknown name logs one console
76
76
  warning per name instead of rendering silently empty.
@@ -8,12 +8,17 @@ Import: `import { KptIconButton } from '@konce-pt/angular';`
8
8
  `shape`: 'round'|'square' (default 'round'). The type is the wider `KptButtonVariant` / `KptButtonSize`,
9
9
  but only these values have a style
10
10
  - `type`, `disabled`, `loading`, `ariaLabel` (required)
11
- - `ariaPressed`: `boolean | null` = `null` — toggle state; lands on the inner `<button>`, so a screen reader announces it (`[attr.aria-pressed]` on the tag would sit on the host, which has no button role)
12
- - `ariaExpanded`: `boolean | null` = `null` — disclosure state for a button that opens a panel; lands on the inner `<button>` for the same reason
11
+ - `ariaPressed`: `boolean | null` = `null` - toggle state; lands on the inner `<button>`, so a screen reader announces it (`[attr.aria-pressed]` on the tag would sit on the host, which has no button role)
12
+ - `ariaExpanded`: `boolean | null` = `null` - disclosure state for a button that opens a panel; lands on the inner `<button>` for the same reason
13
+ - `tabIndex`: `number | null` = `null` - `tabindex` of the inner `<button>`, for toolbars with a single Tab stop (roving tabindex), where inactive buttons get `-1`
13
14
 
14
15
  ## Examples
15
16
  <kpt-icon-button ariaLabel="Settings"><kpt-icon name="menu" /></kpt-icon-button>
16
17
  <kpt-icon-button variant="danger" shape="square" ariaLabel="Delete"><kpt-icon name="x" /></kpt-icon-button>
17
18
 
19
+ ## Motion
20
+ Pressed, it squeezes slightly and springs back on release (shared mixin `styles/_press.scss`). The `loading` spinner pops in. Pure CSS; durations follow `--kpt-motion-scale`, so `enabled: false` turns it off, and it drops out
21
+ under "reduce motion".
22
+
18
23
  ## Tokens
19
- Shared with kpt-button (`--kpt-color-primary`, `--kpt-color-muted`, …).
24
+ Shared with kpt-button (`--kpt-color-primary`, `--kpt-color-muted`, ...).
@@ -6,19 +6,19 @@ Import: `import { KptImage } from '@konce-pt/angular';`
6
6
  ## Inputs
7
7
  - `src`: string (required); `alt`: string
8
8
  - `width`: string | null (e.g. '240px')
9
- - `preview`: boolean — a click opens a magnifying overlay
9
+ - `preview`: boolean - a click opens a magnifying overlay
10
10
 
11
11
  ## Example
12
12
  <kpt-image src="/photo.jpg" alt="Photo" preview width="240px" />
13
13
 
14
14
  ## Tokens
15
- The radius `--kpt-radius-md`; the backdrop and the hover mask `--kpt-color-overlay-scrim`; the × button and the magnifier disc `--kpt-color-surface` / `--kpt-color-on-surface` with `--kpt-elevation-2`.
15
+ The radius `--kpt-radius-md`; the backdrop and the hover mask `--kpt-color-overlay-scrim`; the x button and the magnifier disc `--kpt-color-surface` / `--kpt-color-on-surface` with `--kpt-elevation-2`.
16
16
 
17
17
  ## Accessibility
18
- With `preview`, the thumbnail is a `<button aria-haspopup="dialog">` named “Show full size: <alt>”
18
+ With `preview`, the thumbnail is a `<button aria-haspopup="dialog">` named "Show full size: <alt>"
19
19
  (`image.previewOf`, or `image.preview` without `alt`), so it is reached with Tab and opened with
20
20
  Enter or Space; the magnifier shows on hover and on `:focus-visible`. The preview is a native modal
21
- `<dialog>` opened with `showModal()` and named by `alt`: focus moves to its × button and stays inside,
21
+ `<dialog>` opened with `showModal()` and named by `alt`: focus moves to its x button and stays inside,
22
22
  Escape closes it, the page behind is inert, document scrolling is locked while it is open, and focus
23
23
  returns to the thumbnail. It sits in the top layer, so no ancestor with `transform` or
24
24
  `overflow: hidden` can clip it.
@@ -1,7 +1,7 @@
1
1
  # KptInput (kpt-input)
2
2
 
3
3
  The Koncept UI text field, integrated with Angular Signal Forms. It implements
4
- `FormValueControl<string>` — bind it with the `FormField` directive (`@angular/forms/signals`).
4
+ `FormValueControl<string>` - bind it with the `FormField` directive (`@angular/forms/signals`).
5
5
  No `ControlValueAccessor`. Import: `import { KptInput } from '@konce-pt/angular';`
6
6
 
7
7
  ## Selector
@@ -24,15 +24,15 @@ No `ControlValueAccessor`. Import: `import { KptInput } from '@konce-pt/angular'
24
24
  </form>
25
25
 
26
26
  `[formRoot]` sets `novalidate` and calls `submit()` on its own; `submit()` does `markAsTouched()` on its own.
27
- Do not gate validators with `when: state.touched()` — it breaks `valid()`.
27
+ Do not gate validators with `when: state.touched()` - it breaks `valid()`.
28
28
  The full flow: the `## A form from scratch (Signal Forms)` section in the root llms.txt.
29
29
 
30
30
  ## Presentational inputs
31
31
  - `type`: 'text'|'email'|'password'|'number'|'search'|'tel'|'url'|'time' (default 'text')
32
32
  - `placeholder`: string
33
- - `id`: string — lands on the inner `<input>` (for `label[for]`); the host does not carry it
33
+ - `id`: string - lands on the inner `<input>` (for `label[for]`); the host does not carry it
34
34
  - `ariaLabel`: string | null
35
- - `autocomplete`: string | null — a hint for the browser and the password manager
35
+ - `autocomplete`: string | null - a hint for the browser and the password manager
36
36
  (e.g. `email`, `username`, `one-time-code`); without it autofill does not work
37
37
 
38
38
  ## State bound automatically by FormField
@@ -40,7 +40,7 @@ The full flow: the `## A form from scratch (Signal Forms)` section in the root l
40
40
  `touched`; the `touch` output (emitted on blur). Do not set them by hand when used with a form.
41
41
 
42
42
  ## Label and description
43
- `id` goes to the native field — the host never carries it; without one it is generated. Inside
43
+ `id` goes to the native field - the host never carries it; without one it is generated. Inside
44
44
  `kpt-form-field` the control links itself: the wrapper's `label[for]` points at it and the hint or
45
45
  error is added to `aria-describedby`, so `controlId` is not needed. Without a wrapper, name it with
46
46
  `ariaLabel`.
@@ -49,8 +49,22 @@ error is added to `aria-describedby`, so `controlId` is not needed. Without a wr
49
49
  `--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}`.
50
50
 
51
51
  ## Accessibility
52
- - `aria-invalid="true"` only once the field is invalid **and** touched (`blur`) — a fresh,
52
+ - `aria-invalid="true"` only once the field is invalid **and** touched (`blur`) - a fresh,
53
53
  empty form is not painted red.
54
- - `aria-required="true"` with `required` — deliberately not the native `required` attribute, which
54
+ - `aria-required="true"` with `required` - deliberately not the native `required` attribute, which
55
55
  would block the submit event and run browser validation alongside Signal Forms.
56
56
  - Error messages are usually rendered by `kpt-form-field` (`role="alert"`).
57
+
58
+ ## Dictation
59
+ - `speech`: boolean = false - a microphone at the end of the field (`kpt-speech-button`, Web Speech
60
+ API). Without browser support it is not shown and the field keeps its normal padding.
61
+ - `speechLang`: string | null - BCP 47 tag; without it from `KptI18n.locale`.
62
+ - `speechColor`: `'primary' | 'danger' | 'success' | 'warning' | 'info'` = `'primary'` - colour of "stop" and the wave while listening.
63
+ - `speechMode`: `'insert' | 'append' | 'replace'` = `'insert'`. `replace` clears the field the moment
64
+ the microphone is clicked (undoable with Ctrl+Z) and stops after one utterance - the search pattern.
65
+
66
+ Interim words are visible in the field but never reach the model; final text enters through the
67
+ field's `(input)` like typed text, so `[formField]` validates whole words only.
68
+
69
+ <kpt-input [formField]="f.title" speech />
70
+ <kpt-input type="search" speech speechMode="replace" />
@@ -19,13 +19,16 @@ Import: `import { KptInputMask } from '@konce-pt/angular';`
19
19
  ## Screen reader and keyboard
20
20
  The on-screen keyboard follows the mask: only `9` tokens (phone, postal code) give
21
21
  `inputmode="numeric"`, otherwise `text`; override it with `inputMode`. `autocomplete` (`tel`,
22
- `postal-code`…) lets the browser fill the field in.
22
+ `postal-code`...) lets the browser fill the field in.
23
23
 
24
24
  ## Label and description
25
- `id` goes to the native field — the host never carries it; without one it is generated. Inside
25
+ `id` goes to the native field - the host never carries it; without one it is generated. Inside
26
26
  `kpt-form-field` the control links itself: the wrapper's `label[for]` points at it and the hint or
27
27
  error is added to `aria-describedby`, so `controlId` is not needed. Without a wrapper, name it with
28
28
  `ariaLabel`. New: `aria-invalid` after touch.
29
29
 
30
30
  ## Tokens
31
31
  The field uses `--kpt-form-field-*`.
32
+
33
+ ## Read-only and required
34
+ `readonly` is the native read-only field. The caret stays where you typed: fixing a digit in the middle of a phone number no longer throws it to the end. The `a` and `*` tokens accept every letter (`ą`, `ł`, `ß`), not only ASCII.
@@ -1,29 +1,30 @@
1
1
  # KptInputNumber (kpt-input-number)
2
2
 
3
3
  A numeric field with stepper arrows on Signal Forms. The value is number | null.
4
- `showButtons="false"` gives the arrow-less variant — for "from–to" ranges.
4
+ `showButtons="false"` gives the arrow-less variant - for "from-to" ranges.
5
5
  Import: `import { KptInputNumber } from '@konce-pt/angular';`
6
6
 
7
7
  ## Inputs / model
8
8
  - `value`: model<number | null> (or `formField`)
9
9
  - `min`/`max`: number | undefined; `step`: number (default 1). Under `[formField]` do NOT
10
- bind the bounds — they are declared by `min()`/`max()` in `form()`, and `FormField` injects them
10
+ bind the bounds - they are declared by `min()`/`max()` in `form()`, and `FormField` injects them
11
11
  into these inputs itself; `[min]`/`[max]` next to `[formField]` is a compilation error
12
12
  (FORM_FIELD_UNSUPPORTED_BINDING). Bind them directly only together with `[(value)]`.
13
13
  - `suffix`: string (e.g. ' %'); `placeholder`: string
14
- - `showButtons`: boolean (default `true`) — `false` hides the `−`/`+` arrows; the field content
14
+ - `showButtons`: boolean (default `true`) - `false` hides the `-`/`+` arrows; the field content
15
15
  then aligns left, as in `kpt-input` (the `.kpt-input-number--plain` modifier)
16
- - `disabled`/`invalid`/`touched`: boolean; `touch`: output
16
+ - `disabled`/`readonly`/`invalid`/`touched`: boolean; `touch`: output. `readonly` (also from `readonly()` in
17
+ the schema) leaves the value selectable but blocks typing, the arrows and the buttons (`aria-readonly`)
17
18
 
18
19
  ## Example
19
20
  <kpt-input-number [formField]="f.qty" [step]="1" />
20
21
  <kpt-input-number [(value)]="qty" [min]="0" [max]="99" suffix=" pcs" />
21
22
  <kpt-input-number [formField]="f.priceFrom" [showButtons]="false" suffix=" USD" />
22
23
 
23
- ## A "from–to" range (cross-field validation)
24
+ ## A "from-to" range (cross-field validation)
24
25
 
25
- Two separate form fields; the "to ≥ from" rule is attached through `validateTree` on the root.
26
- The error is aimed at a specific field with the `fieldTree` property — otherwise it would land on the form
26
+ Two separate form fields; the "to >= from" rule is attached through `validateTree` on the root.
27
+ The error is aimed at a specific field with the `fieldTree` property - otherwise it would land on the form
27
28
  and would not show up under any control.
28
29
 
29
30
  import { form, max, min, validateTree } from '@angular/forms/signals';
@@ -48,7 +49,7 @@ and would not show up under any control.
48
49
  });
49
50
  });
50
51
 
51
- // template — two columns from md up (utility classes from @konce-pt/grid)
52
+ // template - two columns from md up (utility classes from @konce-pt/grid)
52
53
  <form class="kpt-grid" [formRoot]="rangeForm" (submit)="onSubmit()">
53
54
  <kpt-form-field class="kpt-col-12 kpt-col-md-6" label="Price from" [error]="fromError()">
54
55
  <kpt-input-number [formField]="rangeForm.priceFrom" [showButtons]="false" suffix=" USD" />
@@ -59,23 +60,25 @@ and would not show up under any control.
59
60
  </form>
60
61
 
61
62
  `ctx.valueOf(path.x)` reads another field's value, `ctx.fieldTreeOf(path.x)` points at the field
62
- the error belongs to. Messages are supplied through `errorFor()` with a `touched()` gate — do not
63
+ the error belongs to. Messages are supplied through `errorFor()` with a `touched()` gate - do not
63
64
  gate the validators. The full submit flow: `## A form from scratch (Signal Forms)` in the root llms.txt.
64
65
 
65
66
  ## Keyboard
66
67
  The field is `role="spinbutton"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow` (and
67
- `aria-valuetext` with the `suffix`, "5 pcs"). `↑`/`↓` change the value by `step`,
68
- `PageUp`/`PageDown` by ten steps; stepping is rounded to the precision of `step`. A typed value is
69
- **not** clamped while typing ("150" with `max` 99 stays "150", so the form's `max()` can report it) —
70
- it is clamped on blur. The `−`/`+` buttons sit outside the Tab order and do not take focus from the
68
+ `aria-valuetext` with the `suffix`, "5 pcs"). `ArrowUp`/`ArrowDown` change the value by `step`,
69
+ `PageUp`/`PageDown` by ten steps; stepping is rounded to the precision of `step` or of the current
70
+ value, whichever is finer (`1.25` + 1 gives `2.25`, not `2`). Only a plain decimal is accepted while
71
+ typing - `0x1A`, `1e3` and `Infinity` are ignored. A typed value is
72
+ **not** clamped while typing ("150" with `max` 99 stays "150", so the form's `max()` can report it) -
73
+ it is clamped on blur. The `-`/`+` buttons sit outside the Tab order and do not take focus from the
71
74
  field, so focus never drops to `<body>` when a button goes disabled at a limit.
72
75
 
73
76
  ## Screen reader and keyboard
74
- The value is shown in the active locale's notation (PL `12,5`), without thousands separators — the
77
+ The value is shown in the active locale's notation (PL `12,5`), without thousands separators - the
75
78
  field accepts both a dot and a comma, and digit grouping would clash with what the user types.
76
79
 
77
80
  ## Label and description
78
- `id` goes to the native field — the host never carries it; without one it is generated. Inside
81
+ `id` goes to the native field - the host never carries it; without one it is generated. Inside
79
82
  `kpt-form-field` the control links itself: the wrapper's `label[for]` points at it and the hint or
80
83
  error is added to `aria-describedby`, so `controlId` is not needed. Without a wrapper, name it with
81
84
  `ariaLabel`. New: `id`, `ariaLabel`, `required` and `aria-invalid` on the field.
@@ -1,12 +1,12 @@
1
1
  # KptInputOtp (kpt-input-otp)
2
2
 
3
- A one-time code field (OTP/PIN) — N separate boxes with autofocus and paste support. Signal Forms.
3
+ A one-time code field (OTP/PIN) - N separate boxes with autofocus and paste support. Signal Forms.
4
4
  The value is a string (the characters joined). Import: `import { KptInputOtp } from '@konce-pt/angular';`
5
5
 
6
6
  ## Inputs / model
7
7
  - `value`: model<string> (or `formField`)
8
8
  - `length`: number (default 6)
9
- - `integerOnly`: boolean — digits only
9
+ - `integerOnly`: boolean - digits only
10
10
  - `disabled`/`invalid`/`touched`: boolean; `touch`: output
11
11
 
12
12
  ## Behavior
@@ -18,11 +18,11 @@ Typing a character moves to the next box; Backspace goes back; pasting spreads t
18
18
  ## Screen reader and keyboard
19
19
  The first cell has `autocomplete="one-time-code"`, so phones offer the code from an SMS; a code that
20
20
  arrives in one cell at once (autofill, an on-screen keyboard paste) is spread over the cells like a
21
- paste. `touch` fires when focus leaves the whole group — not after a paste, and not when moving
21
+ paste. `touch` fires when focus leaves the whole group - not after a paste, and not when moving
22
22
  between cells.
23
23
 
24
24
  ## Label and description
25
- `id` goes to the focusable element — the host never carries it; without one it is generated. A `div`
25
+ `id` goes to the focusable element - the host never carries it; without one it is generated. A `div`
26
26
  with a role is not named by `label[for]`, so inside `kpt-form-field` it gets `aria-labelledby`
27
27
  pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error is added to
28
28
  `aria-describedby`. No `controlId` needed. The cells form a named `role="group"`; `id` goes to the
@@ -31,3 +31,14 @@ first cell (clicking the label starts at the beginning), and each cell is named
31
31
 
32
32
  ## Tokens
33
33
  The boxes use `--kpt-form-field-*`.
34
+
35
+ ## Read-only and required
36
+ `readonly` shows the code but blocks typing and paste; `required` sets `aria-required` on the cells (`group` does not accept it). The value holds the typed characters **without gaps**: clearing a middle cell gives `"13"`, not `"1 3"`, while the cell itself stays empty on screen.
37
+
38
+ ## Groups
39
+ `groupSize` (default `0` = no groups) inserts a separator after every N boxes, counted from the
40
+ left; `groupSeparator` sets the character (default `-`). With `length` 9 and `groupSize` 3 you get
41
+ `[][][]-[][][]-[][][]`. The separator is purely visual (`aria-hidden`): the value is the bare characters
42
+ (`"123456789"`), each box keeps its name "Character 4 of 9", and arrows/Backspace jump over it.
43
+
44
+ <kpt-input-otp [formField]="f.code" [length]="9" groupSize="3" integerOnly />
@@ -1,38 +1,45 @@
1
1
  # KptKnob (kpt-knob)
2
2
 
3
- A knob — pick a value along an SVG arc, with the mouse (drag) or the arrow keys. Signal Forms.
3
+ A knob - pick a value along an SVG arc, with the mouse (drag) or the arrow keys. Signal Forms.
4
4
  Import: `import { KptKnob } from '@konce-pt/angular';`
5
5
 
6
6
  ## Inputs / model
7
7
  - `value`: model<number> (or `formField`)
8
8
  - `min`/`max`: number | undefined (0/100); `step`: number. Under `[formField]` the bounds come
9
- from `min()`/`max()` in `form()` — `[min]`/`[max]` next to `[formField]` is a compilation error
9
+ from `min()`/`max()` in `form()` - `[min]`/`[max]` next to `[formField]` is a compilation error
10
10
  (FORM_FIELD_UNSUPPORTED_BINDING); bind them directly only together with `[(value)]`.
11
11
  - `size`: px (default 96); `stroke`: px (10); `suffix`: string
12
12
  - `showValue`: boolean (default true)
13
- - `disabled`/`invalid`/`touched`: boolean; `touch`: output
13
+ - `disabled`/`readonly`/`invalid`/`touched`: boolean; `touch`: output. `readonly` (also from `readonly()` in
14
+ the schema) keeps the knob focusable but ignores the pointer and the keys (`aria-readonly`)
14
15
 
15
16
  ## Motion
16
- A jump in value — an arrow key, Home/End, a click on the arc, a change from outside — moves the arc
17
+ A jump in value - an arrow key, Home/End, a click on the arc, a change from outside - moves the arc
17
18
  and counts the number up or down over ~220 ms (ease-out). Dragging follows the pointer with no
18
19
  delay, so it never feels laggy. `prefers-reduced-motion: reduce` turns the animation off.
19
20
  `aria-valuenow` always carries the target value, never an in-between frame. Dragging does not
20
21
  select the number or the arc.
21
22
 
22
23
  ## Accessibility
23
- `role="slider"` + aria-valuemin/max/now; arrow keys, Home/End.
24
+ `role="slider"` + aria-valuemin/max/now; arrow keys, PageUp/PageDown (ten steps), Home/End. Values sit on
25
+ the grid `min + k,step` for both the pointer and the keys - with `min=1, step=2` that is 1, 3, 5...
24
26
 
25
27
  ## Example
26
28
  <kpt-knob [formField]="f.level" [step]="5" /> <!-- bounds from min()/max() in form() -->
27
29
  <kpt-knob [(value)]="level" [min]="0" [max]="100" [step]="5" />
28
30
 
29
31
  ## Label and description
30
- `id` goes to the focusable element — the host never carries it; without one it is generated. A `div`
32
+ `id` goes to the focusable element - the host never carries it; without one it is generated. A `div`
31
33
  with a role is not named by `label[for]`, so inside `kpt-form-field` it gets `aria-labelledby`
32
34
  pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error is added to
33
35
  `aria-describedby`. No `controlId` needed. New: `id`, `ariaLabel`; `aria-valuetext` includes
34
36
  `suffix` ("40%"), and a disabled knob leaves the Tab order. Use `ariaLabel`, not `aria-label` on the
35
- host — that one lands on the wrapper.
37
+ host - that one lands on the wrapper.
38
+
39
+ ## Pointer
40
+ While held (from press to release) the knob reacts: the cursor becomes `grabbing`, the dial grows
41
+ slightly, the value arc glows stronger and the number in the middle scales up. On hover the arc glows
42
+ softly. All of it is CSS on the `is-grabbing` class and drops out under "reduce motion".
36
43
 
37
44
  ## Tokens
38
45
  The background arc `--kpt-color-border`; the value `--kpt-color-primary`; text `--kpt-color-on-surface`.
@@ -5,7 +5,7 @@ Value: `T` (single) or `T[]` (multiple). Import: `import { KptListbox } from '@k
5
5
 
6
6
  ## Inputs / model
7
7
  - `value`: model<T | T[] | null> (or `formField`)
8
- - `options`: KptOption<T>[] — { label, value, disabled? }
8
+ - `options`: KptOption<T>[] - { label, value, disabled? }
9
9
  - `multiple`: boolean; `filter`: boolean (a search field)
10
10
  - `id`/`ariaLabel`: string|null; `required`: boolean
11
11
  - `disabled`/`invalid`/`touched`: boolean; `touch`: output (blur of the list)
@@ -16,17 +16,20 @@ Value: `T` (single) or `T[]` (multiple). Import: `import { KptListbox } from '@k
16
16
 
17
17
  ## Keyboard
18
18
  The WAI-ARIA listbox pattern: the list is one Tab stop and the active option is announced through
19
- `aria-activedescendant`. `↑`/`↓`, `Home`/`End` and `PageUp`/`PageDown` move the active option,
19
+ `aria-activedescendant`. `ArrowUp`/`ArrowDown`, `Home`/`End` and `PageUp`/`PageDown` move the active option,
20
20
  skipping disabled ones (no wrapping); typing letters jumps to the next match, diacritics ignored;
21
- `Space`/`Enter` picks; in `multiple` mode `Ctrl`/`⌘`+`A` selects every visible option (again —
22
- clears them). The filter field sits before the list (outside the `listbox`) and `↓` moves focus
21
+ `Space`/`Enter` picks; in `multiple` mode `Ctrl`/`Cmd`+`A` selects every visible option (again -
22
+ clears them). The filter field sits before the list (outside the `listbox`) and `ArrowDown` moves focus
23
23
  from it into the list; the filter itself ignores diacritics ("lodz" finds "Łódź").
24
24
 
25
25
  ## Label and description
26
26
  `id` goes to the list (`role="listbox"`), never the host. A `div` with a role is not named by
27
27
  `label[for]`, so inside `kpt-form-field` the list gets `aria-labelledby` pointing at the wrapper's
28
28
  label (unless `ariaLabel` is set) and the hint or error in `aria-describedby`. New: `id`,
29
- `ariaLabel`, `required` (→ `aria-required`); `aria-invalid` after touch; `touch` fires on blur of the list.
29
+ `ariaLabel`, `required` (-> `aria-required`); `aria-invalid` after touch; `touch` fires on blur of the list.
30
30
 
31
31
  ## Tokens
32
32
  The frame `--kpt-form-field-*`; selection `--kpt-color-primary`.
33
+
34
+ ## Read-only and required
35
+ `readonly` lets you move through the list and read the choice but not change it (`aria-readonly`). With `multiple`, `Shift+ArrowUp/ArrowDown` selects the option focus moves to and `Shift+click` adds the range from the last clicked option (APG). The empty message sits next to the list.