@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
package/README.md CHANGED
@@ -1,11 +1,11 @@
1
1
  <div align="center">
2
2
 
3
- <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — Angular component library" width="100%" />
3
+ <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI - Angular component library" width="100%" />
4
4
 
5
- # Koncept UI — Angular
5
+ # Koncept UI - Angular
6
6
 
7
7
  **Open-source Angular 22 component library built on Signals & Signal Forms.**
8
- 70+ components, a feature-rich data table and app-shell layout — zoneless, standalone, fully tokenized.
8
+ 70+ components, a feature-rich data table and app-shell layout - zoneless, standalone, fully tokenized.
9
9
 
10
10
  [![npm version](https://img.shields.io/npm/v/@konce-pt/angular?color=%233b82f6&label=npm)](https://www.npmjs.com/package/@konce-pt/angular)
11
11
  [![npm downloads](https://img.shields.io/npm/dm/@konce-pt/angular?color=%233b82f6)](https://www.npmjs.com/package/@konce-pt/angular)
@@ -26,13 +26,13 @@
26
26
 
27
27
  **Koncept UI** is a free, MIT-licensed component library for **Angular 22**, built from the ground up on a modern signal-based foundation:
28
28
 
29
- - ⚡ **Signals everywhere** — `input()`, `output()`, `model()`, `computed`. `OnPush` + **zoneless** by default.
30
- - 📝 **Forms on Signal Forms only** — components implement `FormValueControl<T>` and bind through the `field`/`Control` directive. No `ControlValueAccessor`.
31
- - 📊 **Flagship data table** — sorting, global filter, pagination, virtual scroll (5000+ rows), row selection, column reorder & freeze, CSV export, cell templates.
32
- - 🎨 **100% tokenized** — every style is a `var(--kpt-*)` CSS custom property. Light/dark theme, neutral OKLCH palette. Swap the brand by swapping one token layer.
33
- - 🧩 **Standalone components** — no NgModules. Import only what you use; tree-shakeable.
34
- - ♿ **Built on Angular CDK** — overlays, a11y, focus management, virtual scrolling.
35
- - 🌍 **i18n built in** — English (default) & Polish out of the box, runtime locale switch, add any language with one JSON.
29
+ - **Signals everywhere** - `input()`, `output()`, `model()`, `computed`. `OnPush` + **zoneless** by default.
30
+ - **Forms on Signal Forms only** - components implement `FormValueControl<T>` and bind through the `field`/`Control` directive. No `ControlValueAccessor`.
31
+ - **Flagship data table** - sorting, global filter, pagination, virtual scroll (5000+ rows), row selection, column reorder & freeze, CSV export, cell templates.
32
+ - **100% tokenized** - every style is a `var(--kpt-*)` CSS custom property. Light/dark theme, neutral OKLCH palette. Swap the brand by swapping one token layer.
33
+ - **Standalone components** - no NgModules. Import only what you use; tree-shakeable.
34
+ - **Built on Angular CDK** - overlays, a11y, focus management, virtual scrolling.
35
+ - **i18n built in** - English (default) & Polish out of the box, runtime locale switch, add any language with one JSON.
36
36
 
37
37
  ## Installation
38
38
 
@@ -41,16 +41,16 @@ npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles @angular/cdk
41
41
  # or: pnpm add / yarn add
42
42
  ```
43
43
 
44
- `@angular/core`, `@angular/common` and `@angular/forms` (all `^22`) are already in an Angular app; **`@angular/cdk` (`^22`) is a required peer** — overlay components (select, autocomplete, datepicker, date-range, dialog, drawer, tooltip, popover, menu…) build on the CDK Overlay — so install it explicitly (above). Optional: `@konce-pt/validators` for the Polish-market validators (NIP, REGON, PESEL, IBAN, postal code). Optional: [`@konce-pt/grid`](https://www.npmjs.com/package/@konce-pt/grid) for the mobile-first layout system — its Angular directives live in `@konce-pt/angular/grid`.
44
+ `@angular/core`, `@angular/common` and `@angular/forms` (all `^22`) are already in an Angular app; **`@angular/cdk` (`^22`) is a required peer** - overlay components (select, autocomplete, datepicker, date-range, dialog, drawer, tooltip, popover, menu...) build on the CDK Overlay - so install it explicitly (above). Optional: `@konce-pt/validators` for the Polish-market validators (NIP, REGON, PESEL, IBAN, postal code). Optional: [`@konce-pt/grid`](https://www.npmjs.com/package/@konce-pt/grid) for the mobile-first layout system - its Angular directives live in `@konce-pt/angular/grid`.
45
45
 
46
46
  ## Setup
47
47
 
48
48
  ### Angular CLI (recommended)
49
49
 
50
- Add the design tokens, base styles and — if you use overlay components — the CDK overlay CSS to the **`styles`** array in `angular.json`. **Order matters:** tokens first, your own `src/styles.scss` **last** so your overrides win the cascade.
50
+ Add the design tokens, base styles and - if you use overlay components - the CDK overlay CSS to the **`styles`** array in `angular.json`. **Order matters:** tokens first, your own `src/styles.scss` **last** so your overrides win the cascade.
51
51
 
52
52
  ```jsonc
53
- // angular.json → projects.<app>.architect.build.options
53
+ // angular.json -> projects.<app>.architect.build.options
54
54
  "styles": [
55
55
  "node_modules/@konce-pt/tokens/dist/css/tokens.css",
56
56
  "node_modules/@konce-pt/tokens/dist/css/tokens.dark.css",
@@ -60,7 +60,7 @@ Add the design tokens, base styles and — if you use overlay components — the
60
60
  ]
61
61
  ```
62
62
 
63
- Zoneless bootstrap (Angular 22) lives in your app config — no CSS imports in `main.ts`:
63
+ Zoneless bootstrap (Angular 22) lives in your app config - no CSS imports in `main.ts`:
64
64
 
65
65
  ```ts
66
66
  import { provideZonelessChangeDetection } from '@angular/core';
@@ -69,16 +69,16 @@ import { provideZonelessChangeDetection } from '@angular/core';
69
69
 
70
70
  providers: [
71
71
  provideZonelessChangeDetection(), // required (zoneless)
72
- // provideKptI18n({ locale: 'pl' }), // optional — UI is English by default; set for Polish/other
73
- // provideKptTablerIcons(), // optional — full Tabler icon set
72
+ // provideKptI18n({ locale: 'pl' }), // optional - UI is English by default; set for Polish/other
73
+ // provideKptTablerIcons(), // optional - full Tabler icon set
74
74
  ]
75
75
  ```
76
76
 
77
- The UI language defaults to **English** and works with **zero config** — `provideKptI18n(...)` is optional and only needed for Polish (or a custom language). See [Internationalization](#internationalization-i18n) below.
77
+ The UI language defaults to **English** and works with **zero config** - `provideKptI18n(...)` is optional and only needed for Polish (or a custom language). See [Internationalization](#internationalization-i18n) below.
78
78
 
79
79
  Dark theme: set `<html data-theme="dark">` (or rely on `prefers-color-scheme`).
80
80
 
81
- > **Why not `import '…css'` in `main.ts`?** Angular CLI (`@angular/build`) turns side-effect CSS imports into a separate stylesheet that isn't linked from `index.html`, so the app builds **without styles**. Use `angular.json → styles[]` instead.
81
+ > **Why not `import '...css'` in `main.ts`?** Angular CLI (`@angular/build`) turns side-effect CSS imports into a separate stylesheet that isn't linked from `index.html`, so the app builds **without styles**. Use `angular.json -> styles[]` instead.
82
82
 
83
83
  ### Other bundlers (Vite / webpack)
84
84
 
@@ -93,7 +93,7 @@ import '@angular/cdk/overlay-prebuilt.css';
93
93
 
94
94
  ## Quick start
95
95
 
96
- A login form powered by **Signal Forms** — no `ControlValueAccessor`, no `FormsModule`:
96
+ A login form powered by **Signal Forms** - no `ControlValueAccessor`, no `FormsModule`:
97
97
 
98
98
  ```ts
99
99
  import { Component, computed, signal } from '@angular/core';
@@ -126,7 +126,7 @@ export class Login {
126
126
  required(p.password, { message: 'Password is required' });
127
127
  });
128
128
 
129
- // Validators stay pure — only the *message* waits for the field to be touched.
129
+ // Validators stay pure - only the *message* waits for the field to be touched.
130
130
  private errorFor(name: 'email' | 'password'): string | null {
131
131
  const s = this.loginForm[name]();
132
132
  return s.touched() && s.invalid() ? s.errors()[0]?.message ?? null : null;
@@ -142,7 +142,7 @@ export class Login {
142
142
  }
143
143
  ```
144
144
 
145
- > Don't gate validators on UI state (`when: ({ state }) => state.touched()`) — it makes
145
+ > Don't gate validators on UI state (`when: ({ state }) => state.touched()`) - it makes
146
146
  > `loginForm().valid()` return `true` on an untouched form. Koncept UI controls already show
147
147
  > the invalid state only once a field is touched.
148
148
 
@@ -172,7 +172,7 @@ Every component ships an `llms.txt` API sheet next to its source for quick refer
172
172
 
173
173
  ## Theming
174
174
 
175
- All visuals are driven by `var(--kpt-*)` tokens (three tiers: primitives → semantic → component). Override them in your **`src/styles.scss`** (it's last in `styles[]`, so it wins the cascade):
175
+ All visuals are driven by `var(--kpt-*)` tokens (three tiers: primitives -> semantic -> component). Override them in your **`src/styles.scss`** (it's last in `styles[]`, so it wins the cascade):
176
176
 
177
177
  ```scss
178
178
  :root {
@@ -184,25 +184,25 @@ All visuals are driven by `var(--kpt-*)` tokens (three tiers: primitives → sem
184
184
  }
185
185
  ```
186
186
 
187
- **Common token names:** surfaces `--kpt-color-surface`, `--kpt-color-surface-sunken|raised|variant|hover|selected`; text `--kpt-color-on-surface`, `--kpt-color-on-surface-muted` (aliases `--kpt-color-text`, `--kpt-color-text-muted|subtle|inverse`); borders `--kpt-color-border`, `--kpt-color-border-strong`; accent roles in full — `{primary,danger,success,warning,info}` each with `-hover`, `-contrast`, `-subtle`, `-border`; radii `--kpt-radius-sm|md|lg|xl|full|none`; elevation `--kpt-elevation-1..4` (aliases `--kpt-shadow-sm|md|lg`). There is no `--kpt-color-bg`.
187
+ **Common token names:** surfaces `--kpt-color-surface`, `--kpt-color-surface-sunken|raised|variant|hover|selected`; text `--kpt-color-on-surface`, `--kpt-color-on-surface-muted` (aliases `--kpt-color-text`, `--kpt-color-text-muted|subtle|inverse`); borders `--kpt-color-border`, `--kpt-color-border-strong`; accent roles in full - `{primary,danger,success,warning,info}` each with `-hover`, `-contrast`, `-subtle`, `-border`; radii `--kpt-radius-sm|md|lg|xl|full|none`; elevation `--kpt-elevation-1..4` (aliases `--kpt-shadow-sm|md|lg`). There is no `--kpt-color-bg`.
188
188
 
189
189
  ## Icons
190
190
 
191
- **84 icons are built in and need no configuration** — what the components themselves draw plus the
191
+ **84 icons are built in and need no configuration** - what the components themselves draw plus the
192
192
  staples of an application shell (`sun`, `moon`, `bell`, `settings`, `users`, `logout`,
193
- `layout-dashboard`, `home`, `activity`, `chart-bar`, `brand-github` …). A typical admin panel needs
193
+ `layout-dashboard`, `home`, `activity`, `chart-bar`, `brand-github` ...). A typical admin panel needs
194
194
  nothing else.
195
195
 
196
196
  For the full **Tabler Icons** set (MIT, 5130 icons) there are two paths, and the difference is the
197
197
  bundle. Every icon is its own export, so importing by name lets the bundler keep just those:
198
198
 
199
199
  ```ts
200
- // Production — two icons reach the bundle.
200
+ // Production - two icons reach the bundle.
201
201
  import { LayoutDashboard, Rocket } from '@konce-pt/angular/icons';
202
202
  import { provideKptIcons } from '@konce-pt/angular';
203
203
  // providers: [provideKptIcons([LayoutDashboard, Rocket])]
204
204
 
205
- // Prototype — every icon, about 1.2 MB.
205
+ // Prototype - every icon, about 1.2 MB.
206
206
  import { provideKptTablerIcons } from '@konce-pt/angular/icons';
207
207
  // providers: [provideKptTablerIcons()]
208
208
  ```
@@ -210,15 +210,15 @@ import { provideKptTablerIcons } from '@konce-pt/angular/icons';
210
210
  `provideKptIcons` comes from the **core** entry point on purpose: `@konce-pt/angular/icons` imports
211
211
  the whole set statically, so a subset parameter there could not shrink anything. For the same
212
212
  reason `provideKptIcons(tabler)` with a namespace import (`import * as tabler`) registers
213
- everything — handing a namespace object to a function blocks static analysis.
213
+ everything - handing a namespace object to a function blocks static analysis.
214
214
 
215
215
  ## Internationalization (i18n)
216
216
 
217
- Component labels ship in **English (default)** and **Polish**. The `KptI18n` service is `providedIn: 'root'`, so **English works out of the box with no provider**. Call `provideKptI18n(...)` only to start in Polish (or another language), or to register/override dictionaries. All user-facing strings — aria-labels, empty states, paginator, calendars, rich-text menus — read from this signal-based service, so switching locale updates the UI instantly (zoneless-friendly).
217
+ Component labels ship in **English (default)** and **Polish**. The `KptI18n` service is `providedIn: 'root'`, so **English works out of the box with no provider**. Call `provideKptI18n(...)` only to start in Polish (or another language), or to register/override dictionaries. All user-facing strings - aria-labels, empty states, paginator, calendars, rich-text menus - read from this signal-based service, so switching locale updates the UI instantly (zoneless-friendly).
218
218
 
219
219
  ```ts
220
220
  import { provideKptI18n } from '@konce-pt/angular';
221
- // providers: [provideKptI18n({ locale: 'pl' })] // optional — Polish UI (EN is the default)
221
+ // providers: [provideKptI18n({ locale: 'pl' })] // optional - Polish UI (EN is the default)
222
222
  ```
223
223
 
224
224
  Switch at runtime:
@@ -246,12 +246,43 @@ provideKptI18n({ messages: { en: { paginator: { rowsPerPage: 'Rows per page:' }
246
246
 
247
247
  Calendar weekday/month names come from the browser's `Intl` API for the active locale. Per-component label inputs (e.g. `emptyMessage`, `acceptLabel`) still take precedence over the dictionary.
248
248
 
249
+ ## Motion
250
+
251
+ Components animate out of the box - springs, smooth layout changes, enter and exit - with **no provider**.
252
+ `provideKptMotion(...)` sets app-wide defaults: whether motion is on at all and which kind each group of
253
+ components gets. Every key is optional.
254
+
255
+ ```ts
256
+ import { provideKptMotion } from '@konce-pt/angular';
257
+
258
+ bootstrapApplication(App, {
259
+ providers: [
260
+ provideZonelessChangeDetection(),
261
+ provideKptMotion({ layout: 'arc', enter: 'fade' }),
262
+ // provideKptMotion({ enabled: false }), // no motion at all (visual tests, kiosk)
263
+ ],
264
+ });
265
+ ```
266
+
267
+ | Key | Values | Components (per-component input) |
268
+ | --- | --- | --- |
269
+ | `enabled` | `true` \| `false` | All. `false` also zeroes CSS durations (`data-kpt-motion="off"`, `--kpt-motion-scale: 0` on `<html>`); loading indicators slow down instead of stopping |
270
+ | `layout` | `spring` \| `arc` \| `morph` \| `none` | DataView, PickList, OrderList (`layoutMotion`) |
271
+ | `collapse` | `spring` \| `fade` \| `none` | Accordion, Fieldset, Panel, Tree (`collapseMotion`) |
272
+ | `enter` | `spring` \| `fade` \| `none` | Chat, ChatMessage, ChatDock, FormField (`enterMotion`); Password meter, ChipsInput and Select chips |
273
+ | `toggle` | `spring` \| `fade` \| `none` | Checkbox, RadioGroup, Switch (`toggleMotion`); Rating stars, ButtonGroup selection |
274
+
275
+ Precedence: `enabled: false` always wins, then the component's own input, then the provider value,
276
+ then `spring`. Small reactions (button press, field focus and error, slider handle) are plain CSS and follow
277
+ only `enabled`. The system "reduce motion" setting is always respected. The same springs and FLIP helpers
278
+ are available for your own views in [`@konce-pt/motion`](https://www.npmjs.com/package/@konce-pt/motion).
279
+
249
280
  ## Documentation
250
281
 
251
- - **Storybook** — interactive docs for every component.
252
- - **Playground** — live demos with copyable HTML/TS/SCSS.
253
- - **`llms.txt`** — LLM-friendly API sheets per component, shipped inside the package; the project-wide sheet lives at [ui.konce.pt/llms.txt](https://ui.konce.pt/llms.txt).
254
- - **Security scanners** — Socket.dev and similar tools flag i18n keys as domain names (`.email`, `.today` and friends are real TLDs) and the map's default endpoints; the [project sheet](https://ui.konce.pt/llms.txt) explains each alert under "Security scanners".
282
+ - **Storybook** - interactive docs for every component.
283
+ - **Playground** - live demos with copyable HTML/TS/SCSS.
284
+ - **`llms.txt`** - LLM-friendly API sheets per component, shipped inside the package; the project-wide sheet lives at [ui.konce.pt/llms.txt](https://ui.konce.pt/llms.txt).
285
+ - **Security scanners** - Socket.dev and similar tools flag i18n keys as domain names (`.email`, `.today` and friends are real TLDs) and the map's default endpoints; the [project sheet](https://ui.konce.pt/llms.txt) explains each alert under "Security scanners".
255
286
  - Repository: [gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui)
256
287
 
257
288
  ## License
@@ -262,18 +293,18 @@ MIT © konce.pt
262
293
 
263
294
  <div align="center">
264
295
 
265
- ## 🇵🇱 Wersja polska
296
+ ## Wersja polska
266
297
 
267
298
  </div>
268
299
 
269
300
  **Koncept UI** to darmowa biblioteka komponentów na licencji **MIT** dla **Angulara 22**, zbudowana od podstaw na nowoczesnym fundamencie sygnałów.
270
301
 
271
- - ⚡ **Sygnały wszędzie** — `input()`, `output()`, `model()`, `computed`. `OnPush` + **zoneless** domyślnie.
272
- - 📝 **Formularze wyłącznie na Signal Forms** — komponenty implementują `FormValueControl<T>`, bez `ControlValueAccessor`.
273
- - 📊 **Flagowa tabela danych** — sortowanie, filtr, paginacja, virtual scroll, zaznaczanie, przestawianie/zamrażanie kolumn, eksport CSV, szablony komórek.
274
- - 🎨 **100% na tokenach** — każdy styl to `var(--kpt-*)`. Motyw jasny/ciemny, neutralna paleta OKLCH.
275
- - 🧩 **Standalone** — bez NgModules, tree-shaking.
276
- - 🌍 **Wbudowane i18n** — angielski (domyślny) i polski, przełączanie języka w runtime, dowolny język jednym plikiem JSON.
302
+ - **Sygnały wszędzie** - `input()`, `output()`, `model()`, `computed`. `OnPush` + **zoneless** domyślnie.
303
+ - **Formularze wyłącznie na Signal Forms** - komponenty implementują `FormValueControl<T>`, bez `ControlValueAccessor`.
304
+ - **Flagowa tabela danych** - sortowanie, filtr, paginacja, virtual scroll, zaznaczanie, przestawianie/zamrażanie kolumn, eksport CSV, szablony komórek.
305
+ - **100% na tokenach** - każdy styl to `var(--kpt-*)`. Motyw jasny/ciemny, neutralna paleta OKLCH.
306
+ - **Standalone** - bez NgModules, tree-shaking.
307
+ - **Wbudowane i18n** - angielski (domyślny) i polski, przełączanie języka w runtime, dowolny język jednym plikiem JSON.
277
308
 
278
309
  ### Instalacja
279
310
 
@@ -281,11 +312,11 @@ MIT © konce.pt
281
312
  npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles @angular/cdk
282
313
  ```
283
314
 
284
- `@angular/core`, `@angular/common` i `@angular/forms` (`^22`) są już w aplikacji Angulara; **`@angular/cdk` (`^22`) to wymagany peer** — komponenty overlay (select, autocomplete, datepicker, date-range, dialog, drawer, tooltip, popover, menu…) bazują na CDK Overlay — więc instaluj go jawnie (powyżej). Opcjonalnie: `@konce-pt/validators` (walidatory PL: NIP, REGON, PESEL, IBAN, kod pocztowy).
315
+ `@angular/core`, `@angular/common` i `@angular/forms` (`^22`) są już w aplikacji Angulara; **`@angular/cdk` (`^22`) to wymagany peer** - komponenty overlay (select, autocomplete, datepicker, date-range, dialog, drawer, tooltip, popover, menu...) bazują na CDK Overlay - więc instaluj go jawnie (powyżej). Opcjonalnie: `@konce-pt/validators` (walidatory PL: NIP, REGON, PESEL, IBAN, kod pocztowy).
285
316
 
286
317
  ### Konfiguracja
287
318
 
288
- **Angular CLI (zalecane)** — dodaj CSS do tablicy **`styles`** w `angular.json`; kolejność ważna, `src/styles.scss` **na końcu**:
319
+ **Angular CLI (zalecane)** - dodaj CSS do tablicy **`styles`** w `angular.json`; kolejność ważna, `src/styles.scss` **na końcu**:
289
320
 
290
321
  ```jsonc
291
322
  "styles": [
@@ -297,9 +328,9 @@ npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles @angular/cdk
297
328
  ]
298
329
  ```
299
330
 
300
- > W Angular CLI **nie** używaj `import '…css'` w `main.ts` — bundler wrzuca taki CSS do osobnego, niepodlinkowanego arkusza i aplikacja jest bez stylów. Dla **Vite/webpack** import w `main.ts` działa (tak robi playground).
331
+ > W Angular CLI **nie** używaj `import '...css'` w `main.ts` - bundler wrzuca taki CSS do osobnego, niepodlinkowanego arkusza i aplikacja jest bez stylów. Dla **Vite/webpack** import w `main.ts` działa (tak robi playground).
301
332
 
302
- Zoneless bootstrap (Angular 22) w konfiguracji aplikacji — bez importów CSS w `main.ts`:
333
+ Zoneless bootstrap (Angular 22) w konfiguracji aplikacji - bez importów CSS w `main.ts`:
303
334
 
304
335
  ```ts
305
336
  import { provideZonelessChangeDetection } from '@angular/core';
@@ -308,24 +339,24 @@ import { provideZonelessChangeDetection } from '@angular/core';
308
339
 
309
340
  providers: [
310
341
  provideZonelessChangeDetection(), // wymagane (zoneless)
311
- // provideKptI18n({ locale: 'pl' }), // opcjonalne — UI domyślnie po angielsku; ustaw dla PL/innego
312
- // provideKptTablerIcons(), // opcjonalne — pełny zestaw Tabler
342
+ // provideKptI18n({ locale: 'pl' }), // opcjonalne - UI domyślnie po angielsku; ustaw dla PL/innego
343
+ // provideKptTablerIcons(), // opcjonalne - pełny zestaw Tabler
313
344
  ]
314
345
  ```
315
346
 
316
- Język UI to domyślnie **angielski** i działa **bez żadnej konfiguracji** — `provideKptI18n(...)` jest opcjonalny, potrzebny tylko dla polskiego (lub własnego języka); szczegóły w sekcji i18n niżej.
347
+ Język UI to domyślnie **angielski** i działa **bez żadnej konfiguracji** - `provideKptI18n(...)` jest opcjonalny, potrzebny tylko dla polskiego (lub własnego języka); szczegóły w sekcji i18n niżej.
317
348
 
318
349
  Motyw ciemny: `<html data-theme="dark">`; nadpisania `--kpt-color-*` w `styles.scss`. Pełny zestaw ikon Tabler: `provideKptTablerIcons()` z `@konce-pt/angular/icons`.
319
350
 
320
- Układ strony: `@konce-pt/grid` (osobna paczka CSS) plus dyrektywy `[kptGrid]`, `[kptCol]`, `[kptFlex]` z `@konce-pt/angular/grid` — siatka mobile-first, utilities flexbox i opcjonalne container queries.
351
+ Układ strony: `@konce-pt/grid` (osobna paczka CSS) plus dyrektywy `[kptGrid]`, `[kptCol]`, `[kptFlex]` z `@konce-pt/angular/grid` - siatka mobile-first, utilities flexbox i opcjonalne container queries.
321
352
 
322
353
  ### Internacjonalizacja (i18n)
323
354
 
324
- Etykiety komponentów są dostępne po **angielsku (domyślnie)** i **polsku**. Serwis `KptI18n` jest `providedIn: 'root'`, więc **angielski działa od razu, bez providera**. `provideKptI18n(...)` wołasz tylko, by wystartować po polsku (lub w innym języku) albo zarejestrować/nadpisać słowniki. Wszystkie napisy (aria-label, stany puste, paginator, kalendarze, menu edytora) pochodzą z tego serwisu opartego o sygnały — zmiana języka odświeża UI natychmiast (zoneless).
355
+ Etykiety komponentów są dostępne po **angielsku (domyślnie)** i **polsku**. Serwis `KptI18n` jest `providedIn: 'root'`, więc **angielski działa od razu, bez providera**. `provideKptI18n(...)` wołasz tylko, by wystartować po polsku (lub w innym języku) albo zarejestrować/nadpisać słowniki. Wszystkie napisy (aria-label, stany puste, paginator, kalendarze, menu edytora) pochodzą z tego serwisu opartego o sygnały - zmiana języka odświeża UI natychmiast (zoneless).
325
356
 
326
357
  ```ts
327
358
  import { provideKptI18n } from '@konce-pt/angular';
328
- // providers: [provideKptI18n({ locale: 'pl' })] // opcjonalne — polski interfejs (EN domyślnie)
359
+ // providers: [provideKptI18n({ locale: 'pl' })] // opcjonalne - polski interfejs (EN domyślnie)
329
360
  ```
330
361
 
331
362
  Przełączanie w runtime: `inject(KptI18n).setLocale('en')`.
@@ -340,16 +371,41 @@ provideKptI18n({ locale: 'de', messages: { de } });
340
371
  Nadpisanie pojedynczych etykiet: `provideKptI18n({ messages: { pl: { paginator: { rowsPerPage: 'Na stronie:' } } } })`.
341
372
  Nazwy dni/miesięcy w kalendarzach pochodzą z `Intl` wg locale. Inputy etykiet per-komponent (np. `emptyMessage`) mają priorytet nad słownikiem.
342
373
 
374
+ ### Animacje
375
+
376
+ Komponenty animują się od razu - sprężyny, płynne zmiany układu, wejścia i wyjścia - **bez providera**.
377
+ `provideKptMotion(...)` ustawia wartości domyślne dla całej aplikacji: czy ruch w ogóle jest włączony i jaki
378
+ rodzaj dostaje każda grupa komponentów. Każdy klucz jest opcjonalny.
379
+
380
+ ```ts
381
+ import { provideKptMotion } from '@konce-pt/angular';
382
+ // providers: [provideKptMotion({ layout: 'arc', enter: 'fade' })]
383
+ // providers: [provideKptMotion({ enabled: false })] // bez ruchu (testy wizualne, kiosk)
384
+ ```
385
+
386
+ | Klucz | Wartości | Komponenty (input per komponent) |
387
+ | --- | --- | --- |
388
+ | `enabled` | `true` \| `false` | Wszystkie. `false` zeruje też czasy w CSS (`data-kpt-motion="off"`, `--kpt-motion-scale: 0` na `<html>`); wskaźniki ładowania zwalniają zamiast stanąć |
389
+ | `layout` | `spring` \| `arc` \| `morph` \| `none` | DataView, PickList, OrderList (`layoutMotion`) |
390
+ | `collapse` | `spring` \| `fade` \| `none` | Accordion, Fieldset, Panel, Tree (`collapseMotion`) |
391
+ | `enter` | `spring` \| `fade` \| `none` | Chat, ChatMessage, ChatDock, FormField (`enterMotion`); miernik hasła, chipy ChipsInput i Select |
392
+ | `toggle` | `spring` \| `fade` \| `none` | Checkbox, RadioGroup, Switch (`toggleMotion`); gwiazdki Rating, wybór ButtonGroup |
393
+
394
+ Pierwszeństwo: `enabled: false` wygrywa zawsze, potem input samego komponentu, potem wartość z providera,
395
+ a na końcu `spring`. Drobne reakcje (wciśnięcie przycisku, fokus i błąd pola, uchwyt suwaka) to czysty CSS
396
+ i idą tylko za `enabled`. Systemowe "ogranicz ruch" jest respektowane zawsze. Te same sprężyny i pomocniki
397
+ FLIP dla własnych widoków są w [`@konce-pt/motion`](https://www.npmjs.com/package/@konce-pt/motion).
398
+
343
399
  ### Komponenty (70+)
344
400
 
345
- Formularze (Signal Forms), przyciski i akcje, layout, nawigacja, dane (z flagową `kpt-data-table`), feedback i overlay — pełna lista w tabeli powyżej. Każdy komponent ma plik `llms.txt` z opisem API obok źródła.
401
+ Formularze (Signal Forms), przyciski i akcje, layout, nawigacja, dane (z flagową `kpt-data-table`), feedback i overlay - pełna lista w tabeli powyżej. Każdy komponent ma plik `llms.txt` z opisem API obok źródła.
346
402
 
347
403
  ### Dokumentacja
348
404
 
349
- Storybook (interaktywne docs), playground (dema z kopiowaniem kodu), `llms.txt` (opisy API — obok każdego komponentu w paczce, całość projektu pod [ui.konce.pt/llms.txt](https://ui.konce.pt/llms.txt)). Repozytorium: [gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui).
405
+ Storybook (interaktywne docs), playground (dema z kopiowaniem kodu), `llms.txt` (opisy API - obok każdego komponentu w paczce, całość projektu pod [ui.konce.pt/llms.txt](https://ui.konce.pt/llms.txt)). Repozytorium: [gitlab.com/konce-pt/koncept-ui](https://gitlab.com/konce-pt/koncept-ui).
350
406
 
351
- Alerty skanerów łańcucha dostaw (Socket.dev i podobne) — klucze i18n czytane jak domeny
352
- oraz domyślne endpointy mapy — omawia sekcja „Skanery bezpieczeństwa" w
407
+ Alerty skanerów łańcucha dostaw (Socket.dev i podobne) - klucze i18n czytane jak domeny
408
+ oraz domyślne endpointy mapy - omawia sekcja "Skanery bezpieczeństwa" w
353
409
  [arkuszu projektu](https://ui.konce.pt/llms-pl.txt).
354
410
 
355
411
  ### Licencja
@@ -1,26 +1,26 @@
1
1
  # KptChart (kpt-chart)
2
2
 
3
3
  An SVG chart in plain Angular (signals, zoneless), with no Chart.js/D3-style dependency.
4
- The computation core lives in `@konce-pt/chart` — plain TypeScript, tested, shared with the React port.
4
+ The computation core lives in `@konce-pt/chart` - plain TypeScript, tested, shared with the React port.
5
5
  Import: `import { KptChart } from '@konce-pt/angular/charts';`
6
6
 
7
7
  ## Chart types (config.type)
8
- - `line` — a line chart; interpolation `linear` | `cubic` | `cubic-monotonic`; `area?: boolean`, `points?: boolean`,
9
- `crosshair?: boolean` (hovering a point → a vertical guide + a highlighted pill on the X axis label)
10
- - `bar` — a bar chart; `orientation: 'vertical' | 'horizontal'`, `borderRadius?: px`
11
- - `pie` — a pie chart
12
- - `doughnut` — a doughnut; `innerRadius?: 0..1` (default 0.6)
13
- - `polarArea` — equal angles, the radius proportional to the value
14
- - `radar` — radial axes + a polygon per series
8
+ - `line` - a line chart; interpolation `linear` | `cubic` | `cubic-monotonic`; `area?: boolean`, `points?: boolean`,
9
+ `crosshair?: boolean` (hovering a point -> a vertical guide + a highlighted pill on the X axis label)
10
+ - `bar` - a bar chart; `orientation: 'vertical' | 'horizontal'`, `borderRadius?: px`
11
+ - `pie` - a pie chart
12
+ - `doughnut` - a doughnut; `innerRadius?: 0..1` (default 0.6)
13
+ - `polarArea` - equal angles, the radius proportional to the value
14
+ - `radar` - radial axes + a polygon per series
15
15
 
16
16
  ## Inputs
17
- - `config: KptChartConfig` (required) — a single object driving everything
18
- - `width` / `height`: viewBox units (600×360); the chart scales to its container
17
+ - `config: KptChartConfig` (required) - a single object driving everything
18
+ - `width` / `height`: viewBox units (600x360); the chart scales to its container
19
19
 
20
20
  The whole drawing lives in that coordinate system, TYPOGRAPHY INCLUDED: the axis labels are set in
21
21
  `font-size: 11px`, but inside an SVG that means 11 user units, not 11 device pixels. Render a
22
22
  600-unit chart in a 300px column and the labels come out at roughly half size. `width`/`height` are
23
- therefore not just an aspect ratio — they are the text scale. In a narrow container shrink them
23
+ therefore not just an aspect ratio - they are the text scale. In a narrow container shrink them
24
24
  proportionally (`width={300} height={180}`) instead of letting a 600-unit chart squeeze itself.
25
25
 
26
26
  ## KptChartConfig (in brief)
@@ -29,12 +29,12 @@ proportionally (`width={300} height={180}`) instead of letting a 600-unit chart
29
29
  - `title` / `subtitle`: `{ display?, text, align, color?, font?, padding? }`
30
30
  - `tooltip`: `{ enabled?, format?(ctx: {series,label,value}): string }`
31
31
  - `animation`: `{ enabled?, duration=400, delay=0, stagger=60 }`
32
- - `ariaLabel?`: string — the chart's accessible name; `description?`: string — the takeaway for a screen reader
32
+ - `ariaLabel?`: string - the chart's accessible name; `description?`: string - the takeaway for a screen reader
33
33
 
34
34
  ## Interactions
35
- - Hovering a point/bar/slice → a tooltip (series, label, value); the bubble is clamped to the edges.
36
- - Clicking the legend → hide/show a series (pie/doughnut/polar: hide a slice) with the scale recomputed.
37
- - Hovering the legend → highlight that series, dim the rest.
35
+ - Hovering a point/bar/slice -> a tooltip (series, label, value); the bubble is clamped to the edges.
36
+ - Clicking the legend -> hide/show a series (pie/doughnut/polar: hide a slice) with the scale recomputed.
37
+ - Hovering the legend -> highlight that series, dim the rest.
38
38
 
39
39
  ## Animations
40
40
  Line: `stroke-dasharray/offset`. Bars: `scaleY/scaleX` (origin at the axis). Slices/radar: `scale` from the center.
@@ -53,7 +53,7 @@ Stagger `delay = index * stagger`. Disabled by `animation.enabled=false` and by
53
53
  The `<svg>` is `role="img"` with a name: `config.ariaLabel`, else the title text, else `chart.label`
54
54
  from i18n. `config.description` (one sentence with the takeaway) is tied to it through
55
55
  `aria-describedby`. The data itself sits in a visually hidden `<table>` (categories in rows, series in
56
- columns, numbers in the active language), so a screen reader can walk the values — the tooltip is
56
+ columns, numbers in the active language), so a screen reader can walk the values - the tooltip is
57
57
  pointer-only. The legend is a list of real buttons, so series can be toggled from the keyboard.
58
58
 
59
59
  ## Tokens / styling
@@ -62,5 +62,5 @@ SCSS lives in `@layer kpt.components`, classes `kpt-chart__*`. Series colors can
62
62
 
63
63
  ## Core (pure TS, optional)
64
64
  Exported functions: `linePath`, `areaPath`, `barLayout`, `pieSlices`, `polarSlices`, `radarGrid`,
65
- `radarPoints`, `niceScale`, `seriesColor`, `KPT_CHART_PALETTE` — for your own extensions or SSR.
65
+ `radarPoints`, `niceScale`, `seriesColor`, `KPT_CHART_PALETTE` - for your own extensions or SSR.
66
66
  They are re-exported from `@konce-pt/chart`, so an app never has to install that package itself.
@@ -1,26 +1,27 @@
1
1
  # KptChat (kpt-chat, kpt-chat-message, kpt-chat-typing, kpt-chat-composer, kpt-chat-dock)
2
2
 
3
3
  A conversation: a grouped message list, a typing indicator, a composer and a floating dock in the
4
- corner of the screen. The row-building core — grouping, day separators, send-status arithmetic —
4
+ corner of the screen. The row-building core - grouping, day separators, send-status arithmetic -
5
5
  lives in `@konce-pt/chat`: plain TypeScript, tested, shared with the React port.
6
6
 
7
7
  Import: `import { KptChat, KptChatComposer, KptChatDock, KptChatMessage, KptChatTyping } from '@konce-pt/angular/chat';`
8
8
 
9
- The library covers presentation and the local state of the list. Transport — a socket, HTTP, retry
10
- with backoff — stays in the application: the component takes messages and only reports `(retry)`
9
+ The library covers presentation and the local state of the list. Transport - a socket, HTTP, retry
10
+ with backoff - stays in the application: the component takes messages and only reports `(retry)`
11
11
  and `(loadMore)`.
12
12
 
13
- ## KptChat — inputs / outputs
14
- - `messages: readonly KptChatMessage<T>[]` — **in chronological order**; the component does not sort
15
- - `currentUser: string` — the author id treated as "me": those messages go right and carry a status
16
- - `groupGapMs: number` (default `KPT_CHAT_GROUP_GAP_MS`, 5 min) — the silence that breaks a group
17
- - `unreadFrom: string | null` — the id of the first unread message; the divider goes above it
18
- - `offline: boolean` — the warning strip with a count of messages waiting to be sent
19
- - `typing: readonly KptChatAuthor[]` — who is typing right now
13
+ ## KptChat - inputs / outputs
14
+ - `messages: readonly KptChatMessage<T>[]` - **in chronological order**; the component does not sort
15
+ - `currentUser: string` - the author id treated as "me": those messages go right and carry a status
16
+ - `groupGapMs: number` (default `KPT_CHAT_GROUP_GAP_MS`, 5 min) - the silence that breaks a group
17
+ - `unreadFrom: string | null` - the id of the first unread message; the divider goes above it
18
+ - `offline: boolean` - the warning strip with a count of messages waiting to be sent
19
+ - `typing: readonly KptChatAuthor[]` - who is typing right now
20
20
  - `autoScroll: boolean` (default true), `actions: boolean`, `emptyLabel: string`
21
- - `reactionOptions: readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) — passed to the bubbles
22
- - `(retry)`, `(reply)` → `KptChatMessage<T>`; `(react)` → `KptChatReactEvent<T>` (`{ message, emoji }`);
23
- `(quoted)` → `KptChatReplyRef`; `(loadMore)` → `void`, fired when the viewport reaches the top
21
+ - `reactionOptions: readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) - passed to the bubbles
22
+ - `enterMotion`: `'spring' | 'fade' | 'none'` (default from `provideKptMotion`, else `spring`) - see "Motion"
23
+ - `(retry)`, `(reply)` -> `KptChatMessage<T>`; `(react)` -> `KptChatReactEvent<T>` (`{ message, emoji }`);
24
+ `(quoted)` -> `KptChatReplyRef`; `(loadMore)` -> `void`, fired when the viewport reaches the top
24
25
 
25
26
  ## Example
26
27
  <kpt-chat
@@ -38,37 +39,37 @@ have to carry a text field it never shows.
38
39
 
39
40
  ## Custom bubble content
40
41
  An `<ng-template>` inside `<kpt-chat>` replaces the bubble's text; the context is the message as
41
- `$implicit` and the whole row as `row`. The bubble, its grouping and its meta row stay in place —
42
+ `$implicit` and the whole row as `row`. The bubble, its grouping and its meta row stay in place -
42
43
  only the content is yours.
43
44
 
44
45
  <kpt-chat [messages]="messages()" currentUser="me">
45
46
  <ng-template let-message><kpt-card>{{ message.data.title }}</kpt-card></ng-template>
46
47
  </kpt-chat>
47
48
 
48
- ## KptChatMessage — the bubble on its own
49
+ ## KptChatMessage - the bubble on its own
49
50
  Works with a whole `[message]` object or with single inputs (`author`, `text`, `time`, `status`,
50
51
  `attachments`, `reactions`, `replyTo`), and takes projected content, so it renders anything.
51
- - `align`: 'start' | 'end' — someone else's message versus your own
52
+ - `align`: 'start' | 'end' - someone else's message versus your own
52
53
  - `variant`: 'neutral' | 'primary' | 'solid' | 'ghost' | 'system'
53
- - `position`: 'single' | 'first' | 'middle' | 'last' — the place in a group
54
+ - `position`: 'single' | 'first' | 'middle' | 'last' - the place in a group
54
55
  - `showAuthor` / `showAvatar` / `showMeta` / `tail` / `actions`: boolean
55
- - `reactionOptions`: `readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) — the picker set
56
+ - `reactionOptions`: `readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) - the picker set
56
57
 
57
58
  The default variant follows the alignment: your own message gets the full `solid`, someone else's
58
- gets `neutral`. The theme is monochrome, so the difference between bubbles is lightness, not hue —
59
+ gets `neutral`. The theme is monochrome, so the difference between bubbles is lightness, not hue -
59
60
  `--kpt-color-primary-subtle` has exactly the lightness of `--kpt-color-muted`, which would make the
60
61
  two sides indistinguishable. For a quieter list set `variant="primary"` by hand.
61
62
 
62
63
  ## Bubble actions: reply and react
63
64
  `actions` puts two buttons beside the bubble, shown on hover and on focus. The arrow emits
64
- `(reply)` with the whole message — `replyRefFrom()` from `@konce-pt/chat` turns it into the
65
+ `(reply)` with the whole message - `replyRefFrom()` from `@konce-pt/chat` turns it into the
65
66
  `replyTo` the composer's quote bar wants. The smiley opens a picker of five reactions (like, heart,
66
- smile, wow, sad — `KPT_CHAT_REACTIONS`, overridable through `reactionOptions`) and emits `(react)`
67
+ smile, wow, sad - `KPT_CHAT_REACTIONS`, overridable through `reactionOptions`) and emits `(react)`
67
68
  with the chosen emoji.
68
69
 
69
70
  Neither one writes to the model: the library says what was clicked, the application decides what
70
71
  the conversation looks like afterwards. `toggleReaction(message.reactions, emoji)` does that
71
- arithmetic — it adds the reaction, takes it back on a second click and drops an entry that reaches
72
+ arithmetic - it adds the reaction, takes it back on a second click and drops an entry that reaches
72
73
  zero, keeping the order of the rest.
73
74
 
74
75
  (reply)="replyTo.set(replyRefFrom($event))"
@@ -76,7 +77,7 @@ zero, keeping the order of the rest.
76
77
 
77
78
  The picker closes on Escape, on a click outside and on picking; an option already given is marked
78
79
  `aria-pressed`, so it is visible which one the next click takes back. The retry arrow of a failed
79
- message takes the place of both — a message that has not gone out has nothing to reply to yet.
80
+ message takes the place of both - a message that has not gone out has nothing to reply to yet.
80
81
 
81
82
  ## Grouping is what the shape is made of
82
83
  `position` decides which corner collapses, which bubble wears the tail, carries the avatar and shows
@@ -87,7 +88,7 @@ you build the list yourself.
87
88
  A group breaks on a different author, a gap longer than `groupGapMs`, a calendar-day boundary, a
88
89
  system message and the unread divider.
89
90
 
90
- The bubble that wears the tail has a **square** bottom corner on that side — a rounded one curved
91
+ The bubble that wears the tail has a **square** bottom corner on that side - a rounded one curved
91
92
  away from the tail and the list background showed through the gap, which made the tail read as a
92
93
  separate arrow stuck next to the bubble rather than a part of it. Bubbles without a tail keep the
93
94
  rounded corner.
@@ -101,7 +102,7 @@ of frames grew up there and the older, wider pills stuck out from behind the new
101
102
  On every scroll (and after every re-render and resize) the component measures the separators, the
102
103
  unread divider and the system notices, hands the rectangles to `chatDayIndicator()` from
103
104
  `@konce-pt/chat` and swaps the pill's text. A centred label driving into the pill's band puts the
104
- pill out — it is the pill that yields, never the content — and with a separator that is also the
105
+ pill out - it is the pill that yields, never the content - and with a separator that is also the
105
106
  handover, since the arriving "Today" says the same thing. Bubbles are not blockers: a pill over an
106
107
  utterance is the normal chat picture. The pill keeps its last label while it is out, so its band does
107
108
  not change height under the script that measures it.
@@ -109,13 +110,27 @@ not change height under the script that measures it.
109
110
  ## An unsent message must be able to say so
110
111
  `status: 'failed'` outlines the bubble with `--kpt-color-danger-border` and puts a retry arrow
111
112
  **outside** it, on the outer side of the list. That bubble also shows its meta row even in the
112
- middle of a group — the arrow with nothing to explain it would be a mystery.
113
+ middle of a group - the arrow with nothing to explain it would be a mystery.
113
114
  Statuses: `sending`, `sent`, `delivered`, `read` (the same double check, in the accent colour) and
114
115
  `failed`. Out-of-order acks are what `mergeStatus()` from `@konce-pt/chat` is for.
115
116
 
117
+ ## Motion
118
+ `enterMotion` (`spring | fade | none`) on the chat, the bubble and the dock:
119
+ - a new message at the bottom - your own grows from the composer side, someone else's comes in from
120
+ the sender's side, sharpening out of a blur; the first load and older messages loaded at the top
121
+ (`loadMore`) do not move - they are not news;
122
+ - a new reaction pops in, a changed count rolls in like a drum, a new status icon turns into place
123
+ (only after the bubble's first render, so loaded history stays still);
124
+ - the dock: `spring` grows the window out of the button (a capsule the size of the FAB opens into
125
+ the panel), `fade` slides and fades it as before.
126
+
127
+ With no value it takes `enter` from `provideKptMotion` (default `spring`); `enabled: false` and the system
128
+ "reduce motion" setting always win. The typing dots are a state indicator - with motion off they
129
+ pulse slower instead of stopping.
130
+
116
131
  ## KptChatComposer
117
132
  `[(value)]`, `placeholder`, `disabled`, `offline`, `allowAttachments`, `maxRows` (default 6),
118
- `enterToSend` (default true), `[(replyTo)]`, `(send)` → `{ text, files, replyTo }`, `(typing)`.
133
+ `enterToSend` (default true), `[(replyTo)]`, `(send)` -> `{ text, files, replyTo }`, `(typing)`.
119
134
  Enter sends, Shift+Enter breaks the line; `enterToSend=false` swaps the two. The field grows with
120
135
  the content up to `maxRows` and then scrolls.
121
136
 
@@ -128,14 +143,14 @@ It is **not** a Signal Forms control and will not become one: it never enters a
128
143
 
129
144
  ## Sharing the corner with kpt-scroll-top
130
145
  `kpt-scroll-top` pins itself to the same spot with the same `--kpt-z-overlay`, and it would swallow
131
- the chat FAB whole — only the unread badge would stick out, and the button could not be clicked.
146
+ the chat FAB whole - only the unread badge would stick out, and the button could not be clicked.
132
147
  The stylesheet resolves it by itself: when a `bottom-end` dock is on the page, the scroll-top button
133
148
  steps **aside** (`:root:has()` shifts it left by the width of the FAB plus a gap). Sideways, not up,
134
- because the conversation panel stands above the FAB — moving it up would trade one collision for a
149
+ because the conversation panel stands above the FAB - moving it up would trade one collision for a
135
150
  worse one, with the button landing on the messages.
136
151
  It applies to `bottom-end` only, and it measures from the default offset: an application that sets
137
152
  `offset` positions the scroll-top button itself.
138
- The FAB is `kpt-fab` — the dock uses it, it does not replace it. The panel content is projected, so
153
+ The FAB is `kpt-fab` - the dock uses it, it does not replace it. The panel content is projected, so
139
154
  the dock knows nothing about messages. Opening moves focus to the composer, `Escape` closes and
140
155
  returns focus to the FAB. Below `--kpt-breakpoint-sm` the panel goes full-screen.
141
156
 
@@ -146,16 +161,16 @@ returns focus to the FAB. Below `--kpt-breakpoint-sm` the panel goes full-screen
146
161
 
147
162
  ## Accessibility
148
163
  The list is `role="log"` with `aria-live="polite"`, so a new message is announced without cutting
149
- off what is being read. Each bubble is an `article` labelled with author, time and status — content
164
+ off what is being read. Each bubble is an `article` labelled with author, time and status - content
150
165
  alone would say nothing about who wrote it or whether it was sent. The typing indicator is
151
- `role="status"`; under `prefers-reduced-motion` the dots stop bouncing and pulse instead — they are
166
+ `role="status"`; under `prefers-reduced-motion` the dots stop bouncing and pulse instead - they are
152
167
  the only carrier of "someone is typing", so switching them off entirely would remove the message.
153
168
 
154
169
  ## Tokens
155
170
  Bubble `--kpt-color-muted` (incoming) / `--kpt-color-primary` + `--kpt-color-on-primary` (own);
156
171
  failed `--kpt-color-danger-subtle` + `--kpt-color-danger-border`; offline strip
157
172
  `--kpt-color-warning-subtle`; the day pill `--kpt-color-surface-raised` + a border and
158
- `--kpt-elevation-1` (the same look in the list and floating above it — the floating one travels over
173
+ `--kpt-elevation-1` (the same look in the list and floating above it - the floating one travels over
159
174
  the bubbles and has to stand apart from them); dock `--kpt-elevation-3`
160
175
  and `--kpt-z-overlay`.
161
176
 
@@ -163,7 +178,18 @@ and `--kpt-z-overlay`.
163
178
  The scrolling history (`role="log"`) is a Tab stop named "Conversation history" (`chat.history`), so the
164
179
  keyboard can scroll it even when no bubble holds a focusable element. The "new messages" button counts
165
180
  the messages that actually arrived (a batch of five gives "5"). The typing indicator sits inside the log
166
- but with `aria-live="off"`, so "X is typing…" is not announced like a message. Older messages loaded at
181
+ but with `aria-live="off"`, so "X is typing..." is not announced like a message. Older messages loaded at
167
182
  the top keep the view on the same message, also in Safari (no `overflow-anchor`). The composer reports
168
183
  typing on the first keystroke and then at most every 3 s (`KPT_CHAT_TYPING_THROTTLE_MS`). A custom
169
- reaction option may carry `label` — its accessible name.
184
+ reaction option may carry `label` - its accessible name.
185
+
186
+ ## Dictation in the composer
187
+ `speech`: boolean = false puts a microphone between the field and the send button
188
+ (`kpt-speech-button`); `speechLang` sets the language and `speechColor` the listening colour (theme
189
+ colour by default). Words appear in the field live. Enter or
190
+ "Send" during dictation commits what is visible (`flush()`) and stops listening, so exactly the
191
+ visible text is sent - the send button is enabled while listening even if only interim words exist.
192
+ Final text enters through the field's `(input)`: the field grows and `(typing)` fires as with a
193
+ keyboard. Without browser support the microphone is not shown.
194
+
195
+ <kpt-chat-composer speech (send)="askAgent($event.text)" />