@konce-pt/angular 0.12.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/CHANGELOG.md +617 -369
  2. package/README.md +111 -55
  3. package/charts/src/lib/llms.txt +17 -17
  4. package/chat/src/lib/llms.txt +61 -35
  5. package/fesm2022/konce-pt-angular-charts.mjs +11 -11
  6. package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
  7. package/fesm2022/konce-pt-angular-chat.mjs +236 -127
  8. package/fesm2022/konce-pt-angular-chat.mjs.map +1 -1
  9. package/fesm2022/konce-pt-angular-grid.mjs +16 -16
  10. package/fesm2022/konce-pt-angular-grid.mjs.map +1 -1
  11. package/fesm2022/konce-pt-angular-icons.mjs +5 -5
  12. package/fesm2022/konce-pt-angular-icons.mjs.map +1 -1
  13. package/fesm2022/konce-pt-angular-map.mjs +308 -280
  14. package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
  15. package/fesm2022/konce-pt-angular-roadmap.mjs +23 -23
  16. package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
  17. package/fesm2022/konce-pt-angular.mjs +4416 -2132
  18. package/fesm2022/konce-pt-angular.mjs.map +1 -1
  19. package/grid/src/lib/llms.txt +18 -18
  20. package/map/src/lib/llms.txt +142 -141
  21. package/package.json +14 -12
  22. package/roadmap/src/lib/llms.txt +27 -27
  23. package/src/lib/accordion/llms.txt +18 -6
  24. package/src/lib/alert/llms.txt +5 -5
  25. package/src/lib/app-shell/llms.txt +23 -21
  26. package/src/lib/auth/llms.txt +22 -22
  27. package/src/lib/autocomplete/llms.txt +15 -4
  28. package/src/lib/avatar/llms.txt +3 -3
  29. package/src/lib/avatar-group/llms.txt +5 -5
  30. package/src/lib/backdrop/llms.txt +35 -35
  31. package/src/lib/badge/llms.txt +7 -7
  32. package/src/lib/bottom-sheet/llms.txt +4 -4
  33. package/src/lib/breadcrumb/llms.txt +2 -2
  34. package/src/lib/breakpoint/llms.txt +8 -8
  35. package/src/lib/button/llms.txt +26 -18
  36. package/src/lib/button-group/llms.txt +37 -31
  37. package/src/lib/card/llms.txt +19 -19
  38. package/src/lib/carousel/llms.txt +6 -6
  39. package/src/lib/checkbox/llms.txt +15 -3
  40. package/src/lib/chip/llms.txt +6 -6
  41. package/src/lib/chips-input/llms.txt +11 -4
  42. package/src/lib/color-picker/llms.txt +4 -4
  43. package/src/lib/confirm/llms.txt +5 -5
  44. package/src/lib/context-menu/llms.txt +4 -4
  45. package/src/lib/data-table/llms.txt +280 -239
  46. package/src/lib/data-view/llms.txt +25 -4
  47. package/src/lib/date-range/llms.txt +27 -27
  48. package/src/lib/datepicker/llms.txt +34 -34
  49. package/src/lib/dialog/llms.txt +22 -28
  50. package/src/lib/divider/llms.txt +2 -2
  51. package/src/lib/drawer/llms.txt +7 -7
  52. package/src/lib/empty/llms.txt +4 -4
  53. package/src/lib/fab/llms.txt +6 -2
  54. package/src/lib/fieldset/llms.txt +22 -4
  55. package/src/lib/file-upload/llms.txt +1 -1
  56. package/src/lib/form-field/llms.txt +33 -19
  57. package/src/lib/galleria/llms.txt +3 -3
  58. package/src/lib/i18n/llms.txt +9 -9
  59. package/src/lib/icon/llms.txt +8 -8
  60. package/src/lib/icon-button/llms.txt +8 -3
  61. package/src/lib/image/llms.txt +4 -4
  62. package/src/lib/input/llms.txt +21 -7
  63. package/src/lib/input-mask/llms.txt +2 -2
  64. package/src/lib/input-number/llms.txt +14 -14
  65. package/src/lib/input-otp/llms.txt +6 -6
  66. package/src/lib/knob/llms.txt +11 -6
  67. package/src/lib/listbox/llms.txt +6 -6
  68. package/src/lib/loader/llms.txt +72 -0
  69. package/src/lib/megamenu/llms.txt +7 -7
  70. package/src/lib/mention/llms.txt +15 -15
  71. package/src/lib/menu/llms.txt +12 -12
  72. package/src/lib/menubar/llms.txt +7 -7
  73. package/src/lib/meter-group/llms.txt +7 -7
  74. package/src/lib/order-list/llms.txt +18 -6
  75. package/src/lib/paginator/llms.txt +5 -5
  76. package/src/lib/panel/llms.txt +20 -8
  77. package/src/lib/password/llms.txt +14 -6
  78. package/src/lib/peek/llms.txt +10 -10
  79. package/src/lib/pick-list/llms.txt +26 -6
  80. package/src/lib/popover/llms.txt +7 -7
  81. package/src/lib/progress/llms.txt +16 -16
  82. package/src/lib/radio-group/llms.txt +10 -3
  83. package/src/lib/rating/llms.txt +13 -6
  84. package/src/lib/rich-text/llms.txt +34 -29
  85. package/src/lib/scroll-top/llms.txt +3 -3
  86. package/src/lib/select/llms.txt +20 -13
  87. package/src/lib/sidenav/llms.txt +8 -8
  88. package/src/lib/slider/llms.txt +21 -8
  89. package/src/lib/speech/llms.txt +108 -0
  90. package/src/lib/speed-dial/llms.txt +9 -3
  91. package/src/lib/spinner/llms.txt +2 -2
  92. package/src/lib/split-button/llms.txt +14 -8
  93. package/src/lib/splitter/llms.txt +8 -8
  94. package/src/lib/stepper/llms.txt +24 -8
  95. package/src/lib/switch/llms.txt +10 -3
  96. package/src/lib/switch-group/llms.txt +10 -10
  97. package/src/lib/tabs/llms.txt +5 -5
  98. package/src/lib/textarea/llms.txt +16 -5
  99. package/src/lib/timeline/llms.txt +1 -1
  100. package/src/lib/toast/llms.txt +33 -5
  101. package/src/lib/toolbar/llms.txt +3 -3
  102. package/src/lib/tooltip/llms.txt +10 -10
  103. package/src/lib/tree/llms.txt +19 -6
  104. package/src/lib/update/llms.txt +52 -0
  105. package/types/konce-pt-angular-charts.d.ts +2 -2
  106. package/types/konce-pt-angular-chat.d.ts +87 -44
  107. package/types/konce-pt-angular-chat.d.ts.map +1 -1
  108. package/types/konce-pt-angular-grid.d.ts +14 -14
  109. package/types/konce-pt-angular-icons.d.ts +3 -3
  110. package/types/konce-pt-angular-map.d.ts +137 -121
  111. package/types/konce-pt-angular-map.d.ts.map +1 -1
  112. package/types/konce-pt-angular-roadmap.d.ts +13 -13
  113. package/types/konce-pt-angular.d.ts +1391 -628
  114. package/types/konce-pt-angular.d.ts.map +1 -1
@@ -7,33 +7,33 @@ Projected content sits a layer above the canvas and behaves normally.
7
7
  Import: `import { KptBackdrop } from '@konce-pt/angular';`
8
8
 
9
9
  ## Inputs (shared)
10
- - `effect`: 'signal-grid' | 'wave' (default 'signal-grid') — the effect to draw
11
- - `background`: string — the section background; empty takes `--kpt-color-surface`
12
- - `speed`: number (default 1) — 1 is the calm pace of either effect, 0 freezes the picture
13
- - `seed`: number (default 0) — the same value gives the same layout and the same sway
14
- - `paused`: boolean — stops the animation, leaving the last frame
15
- - `adaptive`: boolean — carries hardcoded colours onto the current theme's surface
10
+ - `effect`: 'signal-grid' | 'wave' (default 'signal-grid') - the effect to draw
11
+ - `background`: string - the section background; empty takes `--kpt-color-surface`
12
+ - `speed`: number (default 1) - 1 is the calm pace of either effect, 0 freezes the picture
13
+ - `seed`: number (default 0) - the same value gives the same layout and the same sway
14
+ - `paused`: boolean - stops the animation, leaving the last frame
15
+ - `adaptive`: boolean - carries hardcoded colours onto the current theme's surface
16
16
 
17
17
  ## Inputs (signal-grid)
18
- - `color`: string — the square colour, any CSS notation, tokens included; empty takes
18
+ - `color`: string - the square colour, any CSS notation, tokens included; empty takes
19
19
  `--kpt-color-primary`
20
- - `anchor`: 'left' | 'right' (default 'right') — the edge the grid is densest at
21
- - `cell`: number (default 5) — the square's side in px
22
- - `gap`: number (default 11) — the space between squares in px
23
- - `density`: number (default 0.8) — the share of lit cells at the anchor, 0–1
24
- - `falloff`: number (default 1.4) — how fast the grid fades towards the far edge
20
+ - `anchor`: 'left' | 'right' (default 'right') - the edge the grid is densest at
21
+ - `cell`: number (default 5) - the square's side in px
22
+ - `gap`: number (default 11) - the space between squares in px
23
+ - `density`: number (default 0.8) - the share of lit cells at the anchor, 0-1
24
+ - `falloff`: number (default 1.4) - how fast the grid fades towards the far edge
25
25
 
26
26
  ## Inputs (wave)
27
- - `colors`: string[] — the colour ramp the current slides along, closed into a loop; every
27
+ - `colors`: string[] - the colour ramp the current slides along, closed into a loop; every
28
28
  stop takes any CSS notation, `color`'s rules exactly
29
- - `rotation`: number (default 12) — the angle the current crosses the frame at, in degrees
30
- - `band`: number (default 0.34) — the band's width as a fraction of the frame's height
31
- - `amplitude`: number (default 0.16) — how far the centre line sways
29
+ - `rotation`: number (default 12) - the angle the current crosses the frame at, in degrees
30
+ - `band`: number (default 0.34) - the band's width as a fraction of the frame's height
31
+ - `amplitude`: number (default 0.16) - how far the centre line sways
32
32
 
33
33
  An input that does not belong to the current effect is simply not read.
34
34
 
35
35
  ## Methods
36
- - `reseed()` — a fresh run of the effect at the same size and the same inputs
36
+ - `reseed()` - a fresh run of the effect at the same size and the same inputs
37
37
 
38
38
  ## Example
39
39
  <kpt-backdrop effect="wave" [rotation]="18" [colors]="['#5B8AF2', '#A86DF2', '#F25B9E']">
@@ -43,12 +43,12 @@ An input that does not belong to the current effect is simply not read.
43
43
 
44
44
  ## signal-grid
45
45
  A fine grid of squares that quietly twinkle, dense at one edge and fading to empty at the other.
46
- The gradient comes from **how many** squares are lit, not from opacity laid over an even grid —
46
+ The gradient comes from **how many** squares are lit, not from opacity laid over an even grid -
47
47
  that is why it reads as a signal rather than as a texture with a mask on top.
48
48
 
49
- Each cell derives its own draws — whether it is lit, its twinkle phase and its rate — from its own
49
+ Each cell derives its own draws - whether it is lit, its twinkle phase and its rate - from its own
50
50
  column and row, so the layout survives a resize instead of reshuffling. The rates are spread over
51
- 0.45–1.55, because at one shared rate the whole grid pulses in unison and the effect turns into
51
+ 0.45-1.55, because at one shared rate the whole grid pulses in unison and the effect turns into
52
52
  breathing. The grid deliberately runs past the area and the overflow is clipped: a grid that stops
53
53
  before the edge looks cut off.
54
54
 
@@ -58,7 +58,7 @@ anywhere. The centre line is a sum of harmonics at incommensurable frequencies,
58
58
  sways without a repeating pattern; brightness falls away from it on a Gaussian curve.
59
59
 
60
60
  `rotation` turns the whole current: 0 runs it horizontally, 90 stands it on end. `band` sets how
61
- wide it is, `amplitude` how much it sways — set `amplitude` to 0 and the shape stands still while
61
+ wide it is, `amplitude` how much it sways - set `amplitude` to 0 and the shape stands still while
62
62
  the colours keep flowing.
63
63
 
64
64
  The ramp is closed into a loop, so the last colour returns to the first; a ramp with a seam would
@@ -67,12 +67,12 @@ circle rather than across it: a straight mix of opposite hues crosses the achrom
67
67
  current goes grey exactly where it is brightest.
68
68
 
69
69
  Without `colors` the ramp is `--kpt-color-primary` plus two hues derived from it by rotation.
70
- The library's palette is neutral, so that default current is single-hued and muted — the hue
70
+ The library's palette is neutral, so that default current is single-hued and muted - the hue
71
71
  sliding only shows once you give it a real ramp.
72
72
 
73
73
  Every stop is put to the browser, so `oklch()`, `color-mix()`, `rgb()` and named colours are read
74
74
  the same as hex; alpha is dropped. A stop the browser refuses falls out of the ramp, and if every
75
- one of them falls out the default ramp takes over rather than the section going blank — a dev
75
+ one of them falls out the default ramp takes over rather than the section going blank - a dev
76
76
  build says in the console which stops it dropped.
77
77
 
78
78
  ## What it costs
@@ -81,21 +81,21 @@ browser's interpolation, so a few thousand pixels a frame cover a frame of any s
81
81
  drawn at full canvas resolution.
82
82
 
83
83
  ## Where the maths lives
84
- The grid layout, the density ramp, the twinkle, the current and the colour ramp — plus the
85
- renderers for both effects — live in `@konce-pt/backdrop`, plain TypeScript with its own
84
+ The grid layout, the density ramp, the twinkle, the current and the colour ramp - plus the
85
+ renderers for both effects - live in `@konce-pt/backdrop`, plain TypeScript with its own
86
86
  `node --test` suite, shared by both ports. The component is the lifecycle around them.
87
87
 
88
88
  ## Rest
89
89
  Drawing stops when there is nothing to watch: the section is off-screen (`IntersectionObserver`),
90
90
  the tab is in the background, `paused` is set, `speed` is 0, or the system asks for reduced motion
91
- (`prefers-reduced-motion`). What is left is a single static frame, not emptiness — the effect is
91
+ (`prefers-reduced-motion`). What is left is a single static frame, not emptiness - the effect is
92
92
  part of the composition, not decoration.
93
93
 
94
94
  `speed` feeds the clock rather than the phase, so moving a speed slider accelerates the picture
95
95
  instead of jumping it.
96
96
 
97
97
  ## Accessibility
98
- The canvas carries `aria-hidden="true"` and `pointer-events: none` — it is decoration with no
98
+ The canvas carries `aria-hidden="true"` and `pointer-events: none` - it is decoration with no
99
99
  content and nothing to hit. Content keeps its own roles and tab order. Under reduced motion the
100
100
  animation does not start at all.
101
101
 
@@ -109,24 +109,24 @@ A literal stays put by design, which is right for a brand colour and wrong for a
109
109
  read in both themes. `adaptive` closes that gap: it carries `color`, `colors` and `background`
110
110
  onto the surface of the current theme, keeping each one's distance from that surface. Black picked
111
111
  for a white section comes out white on a near-black ground, and that white background comes out at
112
- the surface's own lightness. Only lightness moves — hue and chroma stay, so a brand colour keeps
112
+ the surface's own lightness. Only lightness moves - hue and chroma stay, so a brand colour keeps
113
113
  being that colour and only changes how light it is.
114
114
 
115
115
  It touches literals only. An empty input takes a token, and a value reaching through `var()`
116
116
  reaches a token too; both already follow the theme, and adapting them would turn them back again.
117
- Values written for the light theme are the assumption — the library keeps light in `:root` and
117
+ Values written for the light theme are the assumption - the library keeps light in `:root` and
118
118
  dark as the override.
119
119
 
120
120
  ## Content on a custom background
121
121
  The host paints `--kpt-color-surface` and lets content inherit `--kpt-color-on-surface`, which is
122
- right until the section gets a `background` of its own — then that token describes the page around
122
+ right until the section gets a `background` of its own - then that token describes the page around
123
123
  it, not the ground the content actually sits on. A dark section in a light theme would come out
124
124
  black on black.
125
125
 
126
126
  So a section with its own background works out its own ink: the host sets `color` to match what it
127
127
  paints, and announces the result as `data-tone` (`light` for a light background, `dark` for a dark
128
- one). Text follows by inheritance; anything needing more than a text colour — buttons in the
129
- section, say — can hang its own tokens off the attribute:
128
+ one). Text follows by inheritance; anything needing more than a text colour - buttons in the
129
+ section, say - can hang its own tokens off the attribute:
130
130
 
131
131
  :where(kpt-backdrop[data-tone='light']) .hero { --kpt-button-filled-bg: #15181a; }
132
132
 
@@ -135,7 +135,7 @@ matches the adapted value, not the one written in the template. A section withou
135
135
  background announces nothing and content stays on `--kpt-color-on-surface`.
136
136
 
137
137
  ## Theme
138
- Canvas does not expand `var()`, so the colour is read once and baked into the renderer — the
138
+ Canvas does not expand `var()`, so the colour is read once and baked into the renderer - the
139
139
  component therefore watches for anything that can restyle the tokens under it and reads them
140
140
  again. `[data-theme="dark"]` is not tied to `:root`, so the watch covers `data-theme`, `class`
141
141
  and `style` on every ancestor from the host up to `<html>`, plus the `prefers-color-scheme` query
@@ -145,7 +145,7 @@ when the colour actually came out different, so an unrelated class landing on `<
145
145
  cheap read and nothing else.
146
146
 
147
147
  Whether an explicit `color` or `colors` follows the theme is up to how it is written. A literal
148
- stays put — `#5b8af2` is `#5b8af2` in either theme, which is what someone spelling out a brand
148
+ stays put - `#5b8af2` is `#5b8af2` in either theme, which is what someone spelling out a brand
149
149
  colour wants. An expression reaching for a token is resolved against the tree on every rebuild, so
150
150
  it moves with the theme on its own:
151
151
 
@@ -156,7 +156,7 @@ token for `color`, and drops out of the ramp for `colors`.
156
156
 
157
157
  ## Contrast
158
158
  The palette is neutral, so `--kpt-color-primary` is near-black on a light surface and near-white
159
- on a dark one — at the default density the picture is strong, and text laid over the dense half
159
+ on a dark one - at the default density the picture is strong, and text laid over the dense half
160
160
  loses its reading. Keep the copy on the side the grid fades towards (that is what `anchor` is
161
161
  for), or drop `density`. `wave` is brightest along its centre line, so the same rule applies
162
162
  through `rotation` and `band`. On a custom `background` give the colours a muted shade:
@@ -1,16 +1,16 @@
1
1
  # KptBadge (kpt-badge)
2
2
 
3
- A badge — a counter or a status dot; standalone or overlaid on content (`overlay`).
3
+ A badge - a counter or a status dot; standalone or overlaid on content (`overlay`).
4
4
  Import: `import { KptBadge } from '@konce-pt/angular';`
5
5
 
6
6
  ## Inputs
7
7
  - `value`: string|number|null; `variant`: 'neutral'|'primary'|'success'|'danger'|'warning'|'info' (default 'primary')
8
- - `size`: 'sm'|'md'|'lg' (default 'md') — height 1rem / 1.25rem / 1.5rem. The type size, the side inset
8
+ - `size`: 'sm'|'md'|'lg' (default 'md') - height 1rem / 1.25rem / 1.5rem. The type size, the side inset
9
9
  and the dot diameter are derived from the height, so the proportions hold at every size.
10
10
  `sm` is meant for a badge sitting inside a line of text (a menu entry, a label, a table cell).
11
- - `dot`: boolean (a dot with no number); `overlay`: boolean (the corner of the content); `max`: number (default 99 → '99+')
12
- - `label`: string — the meaning for screen readers (“3 unread”, “online”); the visible text is then `aria-hidden`
13
- - `hideZero`: boolean — hides the badge when `value` is `0` or `null` (not with `dot`)
11
+ - `dot`: boolean (a dot with no number); `overlay`: boolean (the corner of the content); `max`: number (default 99 -> '99+')
12
+ - `label`: string - the meaning for screen readers ("3 unread", "online"); the visible text is then `aria-hidden`
13
+ - `hideZero`: boolean - hides the badge when `value` is `0` or `null` (not with `dot`)
14
14
 
15
15
  ## Examples
16
16
  <kpt-badge [value]="3" variant="danger" />
@@ -19,10 +19,10 @@ Import: `import { KptBadge } from '@konce-pt/angular';`
19
19
  <kpt-badge dot variant="success" overlay><kpt-avatar name="AK" /></kpt-badge>
20
20
 
21
21
  ## Tokens
22
- Background `--kpt-color-{primary,success,danger,warning,info}` with the text in the matching `*-contrast` token (`--kpt-color-on-primary` for `primary`) — the same pairs as `kpt-button`; `neutral` is `--kpt-color-muted` / `--kpt-color-on-muted`; the overlay ring comes from `--kpt-color-surface`.
22
+ Background `--kpt-color-{primary,success,danger,warning,info}` with the text in the matching `*-contrast` token (`--kpt-color-on-primary` for `primary`) - the same pairs as `kpt-button`; `neutral` is `--kpt-color-muted` / `--kpt-color-on-muted`; the overlay ring comes from `--kpt-color-surface`.
23
23
 
24
24
  ## Accessibility
25
- On its own a badge is just a number, and a `dot` is nothing. `label` gives it a meaning — a visually
25
+ On its own a badge is just a number, and a `dot` is nothing. `label` gives it a meaning - a visually
26
26
  hidden `.kpt-badge__label` that screen readers read instead of the visible text. Without `label`, put
27
27
  the meaning into the name of the control the badge sits on. Count changes are not announced. The
28
28
  `success`, `warning` and `info` variants draw the text in `--kpt-color-surface`; check the contrast
@@ -10,17 +10,17 @@ Import: `import { KptBottomSheet } from '@konce-pt/angular';`
10
10
 
11
11
  ## Example
12
12
  <kpt-button (click)="sheetOpen.set(true)">Share</kpt-button>
13
- <kpt-bottom-sheet [(open)]="sheetOpen" header="Share">…</kpt-bottom-sheet>
13
+ <kpt-bottom-sheet [(open)]="sheetOpen" header="Share">...</kpt-bottom-sheet>
14
14
 
15
15
  ## The closed state / a11y
16
- The sheet is always in the DOM (no `@if`), hidden with `transform` **and** `visibility: hidden` — never
16
+ The sheet is always in the DOM (no `@if`), hidden with `transform` **and** `visibility: hidden` - never
17
17
  `display: none`, so that the slide-in and slide-out animations survive. `visibility` takes the closed sheet
18
18
  out of the tab order and out of the accessibility tree without `inert`, and it does so on the very first frame,
19
19
  without waiting for JavaScript. `prefers-reduced-motion: reduce` drops the transitions.
20
20
 
21
21
  ## Focus and keyboard
22
22
  Opening moves focus into the panel (`cdkFocusInitial`, else its first focusable element, else the
23
- panel itself) and traps it there — `Tab` / `Shift+Tab` wrap inside, as `aria-modal="true"` promises.
23
+ panel itself) and traps it there - `Tab` / `Shift+Tab` wrap inside, as `aria-modal="true"` promises.
24
24
  Closing returns focus to the element that had it before. `Escape` closes the panel. The panel
25
25
  is named by its `header` through `aria-labelledby`. The shared helper is `shared/modal-focus.ts` (on the CDK focus trap; the React port has a twin hook).
26
26
 
@@ -29,4 +29,4 @@ The panel `--kpt-color-surface-raised`, the top radius `--kpt-radius-lg`, `--kpt
29
29
  `--kpt-color-overlay-scrim`.
30
30
 
31
31
  ## Name and scrolling
32
- Without `header` give the sheet `ariaLabel` — a `role="dialog"` without a name is announced as a bare "dialog". An open sheet locks page scrolling underneath.
32
+ Without `header` give the sheet `ariaLabel` - a `role="dialog"` without a name is announced as a bare "dialog". An open sheet locks page scrolling underneath.
@@ -9,7 +9,7 @@ A navigation trail. Import: `import { KptBreadcrumb, KptBreadcrumbItem } from '@
9
9
  <kpt-breadcrumb [items]="[{label:'Home',url:'/'},{label:'Settings',url:'/s'},{label:'Profile'}]" />
10
10
 
11
11
  ## Tokens
12
- The separator is a `chevron-right` icon; links `--kpt-color-on-surface-muted` → hover `--kpt-color-primary`.
12
+ The separator is a `chevron-right` icon; links `--kpt-color-on-surface-muted` -> hover `--kpt-color-primary`.
13
13
 
14
14
  ## Accessibility
15
15
  A `<nav>` landmark labelled from `breadcrumb.label`, holding an ordered list (`<ol>`/`<li>`), so a
@@ -18,7 +18,7 @@ screen reader announces how many levels the trail has. The current page carries
18
18
 
19
19
  ## Router
20
20
  Links are plain `<a href>`, so without a router a click reloads the page. `navigate` fires on a plain
21
- click (left button, no Ctrl/⌘/Shift, no `target="_blank"`) with `{ item, url, event }`: call
21
+ click (left button, no Ctrl/Cmd/Shift, no `target="_blank"`) with `{ item, url, event }`: call
22
22
  `event.preventDefault()` and navigate with your router. Modified clicks stay native (a new tab, a new
23
23
  window). The library depends on no router.
24
24
 
@@ -7,31 +7,31 @@ A root service that turns media queries into signals. The only way in the librar
7
7
 
8
8
  inject(KptBreakpointObserver)
9
9
 
10
- - `up(bp: KptBreakpoint): Signal<boolean>` — `(min-width: <threshold>px)`, mobile-first.
11
- - `down(bp: KptBreakpoint): Signal<boolean>` — `(max-width: <threshold - 0.02>px)`; subtracting 0.02px
10
+ - `up(bp: KptBreakpoint): Signal<boolean>` - `(min-width: <threshold>px)`, mobile-first.
11
+ - `down(bp: KptBreakpoint): Signal<boolean>` - `(max-width: <threshold - 0.02>px)`; subtracting 0.02px
12
12
  keeps the `up`/`down` bands from overlapping at fractional widths (zoom, DPI).
13
- - `matches(query: string): Signal<boolean>` — any media query.
13
+ - `matches(query: string): Signal<boolean>` - any media query.
14
14
 
15
15
  `KptBreakpoint` = `'sm' | 'md' | 'lg' | 'xl' | '2xl'`; the thresholds live in `KPT_BREAKPOINTS`
16
16
  (640 / 768 / 1024 / 1280 / 1536 px).
17
17
 
18
18
  ## Where the values come from
19
19
 
20
- From tokens: `packages/tokens/tokens/primitives/breakpoint.json` → `scripts/gen-tokens.mjs`
20
+ From tokens: `packages/tokens/tokens/primitives/breakpoint.json` -> `scripts/gen-tokens.mjs`
21
21
  generates `breakpoint/breakpoints.generated.ts` (for JS) and `styles/_breakpoints.generated.scss`
22
- (for `@media` in component SCSS). Both files are committed and **must not be edited by hand** —
22
+ (for `@media` in component SCSS). Both files are committed and **must not be edited by hand** -
23
23
  a threshold change goes through the token plus `pnpm nx build angular`. With a single source, the library's
24
24
  CSS and its JavaScript cannot drift apart silently.
25
25
 
26
26
  ## SSR
27
27
 
28
- Outside the browser every signal is a constant `false`. Do not build page layout on it — that is what
28
+ Outside the browser every signal is a constant `false`. Do not build page layout on it - that is what
29
29
  CSS (`@media`) is for, otherwise you get flicker before hydration. The service is for behavior:
30
30
  which way a button should act, whether to close a panel after navigation, what to defer.
31
31
 
32
32
  ## Example
33
33
 
34
- @Component({ /* … */ })
34
+ @Component({ /* ... */ })
35
35
  export class Header {
36
36
  private readonly breakpoints = inject(KptBreakpointObserver);
37
37
  readonly isDesktop = this.breakpoints.up('lg');
@@ -40,6 +40,6 @@ which way a button should act, whether to close a panel after navigation, what t
40
40
 
41
41
  ## Notes
42
42
 
43
- - Queries are memoized per string — `up('lg')` across ten components is one
43
+ - Queries are memoized per string - `up('lg')` across ten components is one
44
44
  `MediaQueryList` and one listener; there is no need to cache it yourself.
45
45
  - Cleanup goes through the root injector's `DestroyRef`, so there is nothing to unsubscribe.
@@ -9,9 +9,9 @@ you pass `href`. Standalone, OnPush, signals. Import: `import { KptButton } from
9
9
  ## DOM
10
10
  <kpt-button class="kpt-button-host">
11
11
  <button class="kpt-button" type="button" data-variant="filled" data-size="md">
12
- <kpt-icon class="kpt-button__icon kpt-icon-host">…</kpt-icon>
13
- <span class="kpt-button__content">…</span>
14
- <kpt-icon class="kpt-button__icon kpt-button__icon--end kpt-icon-host">…</kpt-icon>
12
+ <kpt-icon class="kpt-button__icon kpt-icon-host">...</kpt-icon>
13
+ <span class="kpt-button__content">...</span>
14
+ <kpt-icon class="kpt-button__icon kpt-button__icon--end kpt-icon-host">...</kpt-icon>
15
15
  </button>
16
16
  </kpt-button>
17
17
 
@@ -20,39 +20,39 @@ you pass `href`. Standalone, OnPush, signals. Import: `import { KptButton } from
20
20
  - `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' (default 'md')
21
21
  - `type`: 'button' | 'submit' | 'reset' (default 'button')
22
22
  - `disabled`: boolean (booleanAttribute)
23
- - `loading`: boolean — a spinner + blocked interaction, sets aria-busy
24
- - `fullWidth`: boolean — the full width of the container
25
- - `icon` / `iconEnd`: string — a name from the icon registry
26
- - `iconClass` / `iconEndClass`: string — an extra class on that icon
27
- - `href`: string — renders an `<a>` instead of a `<button>`
28
- - `target` / `rel`: string — only meaningful together with `href`
29
- - `ariaLabel`: string | null (default null) — the accessible name for an icon-only button; it lands on
23
+ - `loading`: boolean - a spinner + blocked interaction, sets aria-busy
24
+ - `fullWidth`: boolean - the full width of the container
25
+ - `icon` / `iconEnd`: string - a name from the icon registry
26
+ - `iconClass` / `iconEndClass`: string - an extra class on that icon
27
+ - `href`: string - renders an `<a>` instead of a `<button>`
28
+ - `target` / `rel`: string - only meaningful together with `href`
29
+ - `ariaLabel`: string | null (default null) - the accessible name for an icon-only button; it lands on
30
30
  the inner `<button>`/`<a>`. Do not use `[attr.aria-label]` on `<kpt-button>`: that puts it on the host,
31
31
  which has no button role, and a screen reader announces a nameless button
32
32
 
33
33
  ## Events
34
- None of its own — the native `click` bubbles out of the inner `<button>`; bind `(click)` on `<kpt-button>`.
34
+ None of its own - the native `click` bubbles out of the inner `<button>`; bind `(click)` on `<kpt-button>`.
35
35
 
36
36
  ## Icons
37
37
  Two ways in, one result. `icon` and `iconEnd` take a name from the icon registry and the component
38
38
  renders it; anything put in the slot is laid out the same way. Both get the gap from
39
- `--kpt-button-gap` and a size that follows `size` (0.875rem at `xs` up to 1.5rem at `xl`) — the
39
+ `--kpt-button-gap` and a size that follows `size` (0.875rem at `xs` up to 1.5rem at `xl`) - the
40
40
  content box is a flex container, so an icon sits on the centre line rather than on the text baseline.
41
41
 
42
42
  `loading` replaces the leading icon with the spinner instead of standing next to it, and the
43
43
  spinner takes that icon's size, so the label does not jump when loading starts. The trailing icon
44
- stays put — it usually marks direction rather than the action.
44
+ stays put - it usually marks direction rather than the action.
45
45
 
46
46
  `iconClass` / `iconEndClass` add a class next to the permanent `.kpt-button__icon` hook, for the
47
47
  cases where one instance needs a different colour or a rotation.
48
48
 
49
49
  ## Link and the `link` variant
50
- Two different things. `variant="link"` only changes the looks — underline, transparent background,
50
+ Two different things. `variant="link"` only changes the looks - underline, transparent background,
51
51
  no side padding, so it sits inside a sentence. `href` changes the element: the component renders
52
52
  `<a class="kpt-button">` instead of `<button>`, and the two combine freely (a filled button can be
53
53
  a link, a `link` variant can be a plain button).
54
54
 
55
- A disabled link loses its `href` rather than just gaining an attribute — otherwise it would stay
55
+ A disabled link loses its `href` rather than just gaining an attribute - otherwise it would stay
56
56
  clickable and reachable with the keyboard; it also gets `aria-disabled="true"` and `tabindex="-1"`.
57
57
  `target="_blank"` without an explicit `rel` gets `rel="noopener noreferrer"`.
58
58
 
@@ -67,6 +67,14 @@ clickable and reachable with the keyboard; it also gets `aria-disabled="true"` a
67
67
  <kpt-button variant="outline"><kpt-icon name="printer" />Print</kpt-button>
68
68
  <form (submit)="onSubmit()"><kpt-button type="submit">Send</kpt-button></form>
69
69
 
70
+ ## Motion
71
+ Pressed, it squeezes slightly and springs back on release (shared mixin `styles/_press.scss`). Entering `loading` pops the spinner in where the leading icon was
72
+ and dims the label. `link` does not squeeze (text in a sentence would jitter): its colour and
73
+ underline change smoothly and it dims while pressed. `elevated` lifts on hover and is pressed down
74
+ (the shadow shrinks smoothly). A pressed button uses its own variant's hover colour - only `filled` has
75
+ a separate pressed colour. Pure CSS; durations follow `--kpt-motion-scale`, so `enabled: false` turns it off, and it drops out
76
+ under "reduce motion".
77
+
70
78
  ## Tokens (styling)
71
79
  `--kpt-button-radius`, `--kpt-button-font-weight`, `--kpt-button-gap`, and one group per variant:
72
80
  `--kpt-button-filled-{bg,fg,bg-hover,bg-active}`, `--kpt-button-elevated-{bg,fg,bg-hover}`,
@@ -76,10 +84,10 @@ clickable and reachable with the keyboard; it also gets `aria-disabled="true"` a
76
84
  The elevated variant also reaches for `--kpt-shadow-sm` and `--kpt-shadow-md`.
77
85
 
78
86
  ## The state layer (hover / active)
79
- Hover and active feedback is carried by an `::after` pseudo-element (`opacity` 0 → 1),
87
+ Hover and active feedback is carried by an `::after` pseudo-element (`opacity` 0 -> 1),
80
88
  not by animating the button's own `background-color`. The reason: the variant colors (`--_bg`,
81
89
  `--_border`) arrive through `[attr.data-variant]`, which Angular only sets
82
- during the update pass — an animated transition briefly showed the base variant
90
+ during the update pass - an animated transition briefly showed the base variant
83
91
  (`filled`) and then repainted it into the target one, which produced flicker at application start.
84
92
  The layer starts at `opacity: 0`, so changing its color on the first render is
85
93
  invisible. That is why the button carries `position: relative` and `isolation: isolate`
@@ -87,7 +95,7 @@ invisible. That is why the button carries `position: relative` and `isolation: i
87
95
  `kpt-icon-button`, `kpt-fab` and `kpt-split-button` follow the same pattern.
88
96
 
89
97
  ## Accessibility
90
- - A native `<button>` — full keyboard and screen reader support.
98
+ - A native `<button>` - full keyboard and screen reader support.
91
99
  - `loading` sets `aria-busy="true"` and disables the button (`disabled`).
92
100
  - An `<a>` matches no `:disabled`, so the disabled look keys off `[aria-disabled='true']` as well.
93
101
  - The focus ring comes from `@konce-pt/styles` (`--kpt-color-focus-ring`).
@@ -1,34 +1,40 @@
1
- # KptButtonGroup (kpt-button-group)
2
-
3
- A segmented button group (toggle, single choice). Signal Forms.
4
- Import: `import { KptButtonGroup, KptOption } from '@konce-pt/angular';`
5
-
6
- ## Inputs
7
- - `options`: KptOption<T>[]; `value`: model<T>; `size`: 'sm'|'md'|'lg'; `disabled`/`invalid`/`touched`; `touch`
8
- - `iconOnly`: boolean — hides the labels and leaves the icons alone
9
-
10
- ## Icons
11
- An option carries its icon by name: `KptOption.icon` is a key from the icon registry, and the group
12
- renders it before the label. The item is a flex box, so the icon gets the `--kpt-button-gap` spacing
13
- and a size that follows `size` (1rem at `sm` up to 1.25rem at `lg`) — the same scale as `kpt-button`,
14
- so a group standing next to a button matches it.
15
-
16
- `iconOnly` drops the label from the page but keeps it as the accessible name: the item gets both
17
- `aria-label` and a `kptTooltip`, so a screen reader still says "Grid" and a mouse or keyboard user
18
- gets the library tooltip (not the native `title`, which ignores the theme and never shows on focus).
19
- Each item also becomes a square, because a lone icon inside a 1rem side padding looks adrift.
20
-
21
- The icon takes its colour from `currentColor`, so the active item — filled with
22
- `--kpt-color-primary` — flips the icon to `--kpt-color-on-primary` with no extra rule.
23
-
24
- ## Examples
25
- <kpt-button-group [(value)]="view" [options]="[{label:'List',value:'list'},{label:'Grid',value:'grid'}]" />
26
- <kpt-button-group [(value)]="view" [options]="[{icon:'list',label:'List',value:'list'}]" />
27
- <kpt-button-group [(value)]="align" [options]="alignOptions" iconOnly />
28
- <kpt-button-group [formField]="f.period" [options]="periods" />
29
-
30
- ## Tokens
1
+ # KptButtonGroup (kpt-button-group)
2
+
3
+ A segmented button group (toggle, single choice). Signal Forms.
4
+ Import: `import { KptButtonGroup, KptOption } from '@konce-pt/angular';`
5
+
6
+ ## Inputs
7
+ - `options`: KptOption<T>[]; `value`: model<T>; `size`: 'sm'|'md'|'lg'; `disabled`/`invalid`/`touched`; `touch`
8
+ - `iconOnly`: boolean - hides the labels and leaves the icons alone
9
+
10
+ ## Icons
11
+ An option carries its icon by name: `KptOption.icon` is a key from the icon registry, and the group
12
+ renders it before the label. The item is a flex box, so the icon gets the `--kpt-button-gap` spacing
13
+ and a size that follows `size` (1rem at `sm` up to 1.25rem at `lg`) - the same scale as `kpt-button`,
14
+ so a group standing next to a button matches it.
15
+
16
+ `iconOnly` drops the label from the page but keeps it as the accessible name: the item gets both
17
+ `aria-label` and a `kptTooltip`, so a screen reader still says "Grid" and a mouse or keyboard user
18
+ gets the library tooltip (not the native `title`, which ignores the theme and never shows on focus).
19
+ Each item also becomes a square, because a lone icon inside a 1rem side padding looks adrift.
20
+
21
+ The icon takes its colour from `currentColor`, so the active item - filled with
22
+ `--kpt-color-primary` - flips the icon to `--kpt-color-on-primary` with no extra rule.
23
+
24
+ ## Examples
25
+ <kpt-button-group [(value)]="view" [options]="[{label:'List',value:'list'},{label:'Grid',value:'grid'}]" />
26
+ <kpt-button-group [(value)]="view" [options]="[{icon:'list',label:'List',value:'list'}]" />
27
+ <kpt-button-group [(value)]="align" [options]="alignOptions" iconOnly />
28
+ <kpt-button-group [formField]="f.period" [options]="periods" />
29
+
30
+ ## Motion
31
+ The selection background slides from the previously selected option to the new one on a spring (a FLIP
32
+ of the `::before` layer, `playIndicatorMotion` from `@konce-pt/motion`), the label colour crossfades,
33
+ and a pressed option squeezes slightly. The slide follows `toggle` from `provideKptMotion` (`spring` only);
34
+ `enabled: false` and the system "reduce motion" setting always win.
35
+
36
+ ## Tokens
31
37
  `--kpt-color-primary`, `--kpt-color-border-strong`, `--kpt-color-muted`, `--kpt-button-gap`.
32
38
 
33
39
  ## Read-only and required
34
- The group is `role="radiogroup"` with `role="radio"` items (`aria-checked`) instead of `aria-pressed` buttons — the choice is exclusive, so a screen reader announces "2 of 3". One Tab stop, arrows move the selection, `Home`/`End` jump to the ends. New: `id`, `ariaLabel`, `readonly`, `required`, and the error state (`invalid` + `touched`) visible on the group itself.
40
+ The group is `role="radiogroup"` with `role="radio"` items (`aria-checked`) instead of `aria-pressed` buttons - the choice is exclusive, so a screen reader announces "2 of 3". One Tab stop, arrows move the selection, `Home`/`End` jump to the ends. New: `id`, `ariaLabel`, `readonly`, `required`, and the error state (`invalid` + `touched`) visible on the group itself.
@@ -1,6 +1,6 @@
1
1
  # KptCard (kpt-card)
2
2
 
3
- A card — a surface with elevation (elevated) or a border (outlined).
3
+ A card - a surface with elevation (elevated) or a border (outlined).
4
4
  Import: `import { KptCard } from '@konce-pt/angular';`
5
5
 
6
6
  ## Selector
@@ -8,33 +8,33 @@ Import: `import { KptCard } from '@konce-pt/angular';`
8
8
 
9
9
  ## Inputs
10
10
  - `variant`: 'elevated' | 'outlined' (default 'elevated')
11
- - `header`: string — optional header text
12
- - `headingLevel`: 1–6 | null (default null) — makes `header` a heading of that level
13
- - `headingLevel`: 1–6 | null (default null) — makes `header` a heading of that level
14
- - `flush`: boolean — a body with no padding (for rich layouts that manage their own sections)
11
+ - `header`: string - optional header text
12
+ - `headingLevel`: 1-6 | null (default null) - makes `header` a heading of that level
13
+ - `headingLevel`: 1-6 | null (default null) - makes `header` a heading of that level
14
+ - `flush`: boolean - a body with no padding (for rich layouts that manage their own sections)
15
15
 
16
16
  ## Content projection
17
- - the default content → the card body
18
- - an element carrying the `kptCardFooter` attribute (a direct child of `kpt-card`) → the footer
17
+ - the default content -> the card body
18
+ - an element carrying the `kptCardFooter` attribute (a direct child of `kpt-card`) -> the footer
19
19
 
20
20
  `kptCardFooter` must be a DIRECT child. Angular's content projection matches direct children only,
21
21
  so a footer nested inside a `<form>` (or any other wrapper) inside the card is never projected into
22
- the footer slot — it falls into the body instead, picking up the body's padding. Nothing warns about
22
+ the footer slot - it falls into the body instead, picking up the body's padding. Nothing warns about
23
23
  it, and the footer's own styling still applies, which makes the symptom read as a spacing bug rather
24
24
  than a placement one. Put the wrapper inside the footer, not the footer inside the wrapper.
25
25
 
26
26
  ## Reusable layout classes (media / profile)
27
- - `kpt-card__media` — a full-width image (clipped to the radius; set `aspect-ratio`/`height` inline)
28
- - `kpt-card__lead` — the header row (avatar + titles), with padding
29
- - `kpt-card__title`, `kpt-card__subtitle` — title/subtitle typography
30
- - `kpt-card__section` — a padded section (a column with gaps)
31
- - `kpt-card__tags` — a row of chips; `kpt-card__meta` — an icon+text row (rating/location)
32
- - `kpt-card__avatar` — an overlapping avatar with a ring (on the cover)
33
- - `kpt-card__actions` — a row of buttons (equal widths)
27
+ - `kpt-card__media` - a full-width image (clipped to the radius; set `aspect-ratio`/`height` inline)
28
+ - `kpt-card__lead` - the header row (avatar + titles), with padding
29
+ - `kpt-card__title`, `kpt-card__subtitle` - title/subtitle typography
30
+ - `kpt-card__section` - a padded section (a column with gaps)
31
+ - `kpt-card__tags` - a row of chips; `kpt-card__meta` - an icon+text row (rating/location)
32
+ - `kpt-card__avatar` - an overlapping avatar with a ring (on the cover)
33
+ - `kpt-card__actions` - a row of buttons (equal widths)
34
34
 
35
35
  ## Example
36
36
  <kpt-card header="Settings" variant="outlined">
37
- <p>Content…</p>
37
+ <p>Content...</p>
38
38
  <div kptCardFooter><kpt-button>Save</kpt-button></div>
39
39
  </kpt-card>
40
40
 
@@ -45,7 +45,7 @@ than a placement one. Put the wrapper inside the footer, not the footer inside t
45
45
  <div><div class="kpt-card__title">Shiba Inu</div><div class="kpt-card__subtitle">Dog Breed</div></div>
46
46
  </div>
47
47
  <img class="kpt-card__media" src="/photo.jpg" alt="" style="aspect-ratio: 4/3" />
48
- <div class="kpt-card__section">Description…</div>
48
+ <div class="kpt-card__section">Description...</div>
49
49
  <div kptCardFooter><kpt-button variant="text" size="sm">LIKE</kpt-button></div>
50
50
  </kpt-card>
51
51
 
@@ -53,7 +53,7 @@ than a placement one. Put the wrapper inside the footer, not the footer inside t
53
53
  `--kpt-card-{bg,fg,border,radius,padding,shadow}`.
54
54
 
55
55
  ## Accessibility
56
- The card is a plain container with no role of its own. `header` is styled text by default — set
57
- `headingLevel` (1–6) to make it a heading (`role="heading"` + `aria-level`) when the card should
56
+ The card is a plain container with no role of its own. `header` is styled text by default - set
57
+ `headingLevel` (1-6) to make it a heading (`role="heading"` + `aria-level`) when the card should
58
58
  appear in the page outline; leave it off for tiles that would only clutter it. Give media images a
59
59
  meaningful `alt`, or `alt=""` when decorative.
@@ -4,12 +4,12 @@ A slide carousel (generic). Import: `import { KptCarousel } from '@konce-pt/angu
4
4
  Data through `items`, the slide template through projection: `<ng-template let-item>`.
5
5
 
6
6
  ## Inputs / model
7
- - `items`: T[] — the slide data
8
- - `activeIndex`: model<number> (default 0) — the two-way index of the active slide
9
- - `label`: string — the region name; empty = `carousel.label`
7
+ - `items`: T[] - the slide data
8
+ - `activeIndex`: model<number> (default 0) - the two-way index of the active slide
9
+ - `label`: string - the region name; empty = `carousel.label`
10
10
 
11
11
  ## Content projection
12
- - `<ng-template let-item let-i="index">` — the template for a single slide; context: `$implicit` = the item, `index`.
12
+ - `<ng-template let-item let-i="index">` - the template for a single slide; context: `$implicit` = the item, `index`.
13
13
 
14
14
  ## Methods
15
15
  - `next()`, `prev()`, `goTo(index)`
@@ -26,9 +26,9 @@ The active dot `--kpt-color-primary`; the arrows `--kpt-color-surface` (80% via
26
26
 
27
27
  ## Accessibility
28
28
  The WAI-ARIA carousel pattern without autoplay. The root is `role="region"` with
29
- `aria-roledescription` from `carousel.roleCarousel` (“carousel”) and a name from `label` or
29
+ `aria-roledescription` from `carousel.roleCarousel` ("carousel") and a name from `label` or
30
30
  `carousel.label`. Each slide is `role="group"` with `aria-roledescription` from `carousel.roleSlide`
31
- and a name from `carousel.slideOf` (“Slide 2 of 4”); slides outside the view are `inert` and
31
+ and a name from `carousel.slideOf` ("Slide 2 of 4"); slides outside the view are `inert` and
32
32
  `aria-hidden`, so Tab never lands on an invisible link. The track is `aria-live="polite"`, so the
33
33
  slide that comes in is announced. The arrows use `aria-disabled` at the ends instead of `disabled`,
34
34
  so they keep the focus; the active dot carries `aria-current`, and every dot has a 24 px target
@@ -10,19 +10,31 @@ Import: `import { KptCheckbox } from '@konce-pt/angular';`
10
10
  - `checked`: model<boolean> (the FormCheckboxControl contract)
11
11
  - `label`: string
12
12
  - `disabled` / `invalid` / `touched`: boolean (bound by FormField); the `touch` output (blur)
13
+ - `toggleMotion`: 'spring' | 'fade' | 'none' (default from `provideKptMotion`, else `spring`) - see "Toggle motion"
13
14
 
14
15
  ## Screen reader and keyboard
15
- `indeterminate`: model<boolean> — the "some selected" state for a "select all" box (a dash in the
16
+ `indeterminate`: model<boolean> - the "some selected" state for a "select all" box (a dash in the
16
17
  box; screen readers say "partially checked"). A click clears it and sets `checked`.
17
18
 
18
19
  ## Label and description
19
- `id` goes to the native field — the host never carries it; without one it is generated. Inside
20
+ `id` goes to the native field - the host never carries it; without one it is generated. Inside
20
21
  `kpt-form-field` the control links itself: the wrapper's `label[for]` points at it and the hint or
21
22
  error is added to `aria-describedby`, so `controlId` is not needed. Without a wrapper, name it with
22
23
  `ariaLabel`. Inside `kpt-form-field` the box gets both names: the wrapper label and its own `label`.
23
24
 
25
+ ## Toggle motion
26
+ `toggleMotion`: `spring` - the box pops and the check mark draws itself as a stroke; `fade` - a calm colour and mark transition; `none` - no
27
+ motion. The bounce is started by the change handler, so a control that is checked on load does not
28
+ move. With no value it takes `toggle` from `provideKptMotion` (default `spring`); `enabled: false` and the
29
+ system "reduce motion" setting always win.
30
+
31
+ With `spring` the error gets a signal too: when the field turns invalid (`invalid` and `touched`),
32
+ an error-coloured ring spreads from the box and fades, and the box shakes briefly. An error present on
33
+ load stays still, and a repeated submit with the field still invalid does not replay it. Inside an
34
+ invalid form field the field already shakes, so the checkbox adds only the ring.
35
+
24
36
  ## Tokens
25
37
  `--kpt-color-primary`, `--kpt-color-on-primary`, `--kpt-form-field-border`, `--kpt-form-field-border-error`.
26
38
 
27
39
  ## Read-only and required
28
- `readonly` keeps the box focusable but blocks the click and Space (`aria-readonly`) — the native attribute does not work on checkboxes.
40
+ `readonly` keeps the box focusable but blocks the click and Space (`aria-readonly`) - the native attribute does not work on checkboxes.