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