@konce-pt/angular 0.9.0 → 0.10.0

package/src/lib/select/llms.txt

@@ -17,11 +17,22 @@ Requires the CDK overlay styles in the application: `import '@angular/cdk/overla
 - `filter`: boolean — a search field; `multiple`: boolean — multi-select (chips)
 - `disabled`/`invalid`/`touched`: boolean; the `touch` output.
 - `open`: model (two-way `[(open)]`, the `(openChange)` output) — the panel state. It lets you open
-  the list from outside and know when the user is done choosing. For the latter **do not use `touch`**:
-  it also fires on the trigger's blur, that is, the moment the mouse goes down on an option in the panel (the panel
-  lives in a CDK Overlay container next to `<body>`, outside the control's DOM). That is what inline editing
-  in `kpt-data-table` does — see `data-table/llms.txt`.
-- Keyboard: Enter/↓ opens, ↑/↓ navigate, Enter selects, Esc closes.
+  the list from outside and know when the user is done choosing — that is what inline editing
+  in `kpt-data-table` does, see `data-table/llms.txt`. `touch` fires when the panel closes and when
+  focus leaves the closed trigger; moving focus into the search field does not count as leaving.
+- `ariaLabel`: string|null — the accessible name of the trigger and the list when no `<label for>`
+  describes the field.
+
+## Keyboard
+The select-only combobox pattern: focus stays on the trigger, and the active option is announced
+through `aria-activedescendant` (with `filter`, focus moves to the search field, which is the combobox).
+- Closed: `↓`/`↑`/`Enter`/`Space`/`Home`/`End` open the list; typing letters opens it on the first
+  match; in `multiple` mode `Backspace`/`Delete` removes the last chip.
+- Open: `↑`/`↓` move by one, `Home`/`End` to the ends, `PageUp`/`PageDown` by ten — disabled options
+  are skipped, the list does not wrap. `Enter` (and `Space` on the trigger) picks; a single select
+  closes and returns focus to the trigger, a multiple one stays open. Typing jumps to the next option
+  starting with the letters (diacritics ignored). `Escape` and `Tab` close the list.
+- Clicking an option does not take focus from the trigger, so a mouse pick does not blur the field.
 
 ## Float label
 In a `kpt-form-field` with `labelType` `over`/`in`/`on` the label also floats once an option is chosen —
@@ -36,5 +47,12 @@ be read from the DOM). Nothing needs configuring:
 The "Search…" and "No results" labels and the chip-removal aria text come from i18n (the `select` namespace).
 English by default; configured through `provideKptI18n` — see `i18n/llms.txt`.
 
+## Label and description
+`id` goes to the focusable element — the host never carries it; without one it is generated. A `div`
+with a role is not named by `label[for]`, so inside `kpt-form-field` it gets `aria-labelledby`
+pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error is added to
+`aria-describedby`. No `controlId` needed. New: `id` and `required` (→ `aria-required`); the list
+gets the same name as the trigger.
+
 ## Tokens
 `--kpt-form-field-{bg,text,border,border-hover,border-focus,border-error,radius}`.

package/src/lib/sidenav/llms.txt

@@ -39,5 +39,11 @@ hidden technically (visually hidden), so a screen reader still knows the entry's
 
 These are plain attributes, not directives — there is nothing to import. Without an icon the rail will be empty.
 
+## Links
+Links in the scroll area are `display: flex` with a gap, so an icon and a label never glue together
+even when the template compiler drops the whitespace between them. A link with
+`aria-current="page"` gets the muted background and a medium weight — mark the current page
+yourself, the component does not know which one it is.
+
 ## Tokens
 `--kpt-sidenav-{bg,fg,border,width,rail-width}` (the width is set by `kpt-app-shell`).

package/src/lib/skeleton/llms.txt

@@ -4,6 +4,7 @@ A loading placeholder (shimmer). Import: `import { KptSkeleton } from '@konce-pt
 
 ## Inputs
 - `variant`: 'text'|'circle'|'rect'; `width`: string; `height`: string; `lines`: number (for text)
+- With `lines` above 1 the last line is 60% wide, so it reads as a paragraph; a single line keeps the full `width`.
 
 ## Examples
     <kpt-skeleton variant="text" [lines]="3" />
@@ -11,4 +12,4 @@ A loading placeholder (shimmer). Import: `import { KptSkeleton } from '@konce-pt
     <kpt-skeleton variant="rect" width="100%" height="8rem" />
 
 ## Tokens
-A gradient over `--kpt-color-surface-variant`.
+The base `--kpt-color-muted`; the shimmer is a lighter band mixed with `--kpt-color-surface`; corners `--kpt-radius-md` (blocks) / `--kpt-radius-sm` (text lines).

package/src/lib/slider/llms.txt

@@ -21,5 +21,18 @@ A value slider on Signal Forms. Import: `import { KptSlider } from '@konce-pt/an
 - The `range` mode uses two stacked `input[type=range]` elements; `pointer-events` are active only on the handles (the track does not intercept them).
 - The handles cannot cross — the lower one is clamped to the upper one and vice versa.
 
+## Screen reader and keyboard
+`suffix`: string (" zł", "%", " km") — shown after the value and put into `aria-valuetext` ("40
+zł"), so the unit is read too. `aria-invalid` after touch.
+
+## Label and description
+`id` goes to the native field — the host never carries it; without one it is generated. Inside
+`kpt-form-field` the control links itself: the wrapper's `label[for]` points at it and the hint or
+error is added to `aria-describedby`, so `controlId` is not needed. Without a wrapper, name it with
+`ariaLabel`. With `range` the thumbs are named "Minimum"/"Maximum" from i18n
+(`slider.min`/`slider.max`, previously hard-coded and mixed-language); inside `kpt-form-field` each
+thumb reads "<label> Minimum" through `aria-labelledby`, without one `ariaLabel` gives "<ariaLabel>,
+Minimum". `id` goes to the single input or the lower thumb.
+
 ## Tokens
 The track is filled with `--kpt-color-primary`, the background is `--kpt-color-surface-variant`.

package/src/lib/speed-dial/llms.txt

@@ -12,5 +12,13 @@ Import: `import { KptSpeedDial } from '@konce-pt/angular';`
 ## Example
     <kpt-speed-dial [items]="actions" direction="up" (selected)="onAction($event)" />
 
+## Accessibility
+- The main button carries `aria-expanded` and `aria-controls` pointing at the actions container.
+- Closed actions are `visibility: hidden` (switched after the fade-out), so they are out of the Tab
+  order and the accessibility tree — not just transparent.
+- `Escape` anywhere in the dial closes it and returns focus to the main button.
+- Every action is a `<button>` labelled with its own `label`, so the fan works from the keyboard even
+  when the actions show icons only.
+
 ## Tokens
 The main FAB comes from `kpt-fab`; the actions use `--kpt-color-surface-raised`, `--kpt-elevation-2`.

package/src/lib/spinner/llms.txt

@@ -1,6 +1,6 @@
 # KptSpinner (kpt-spinner)
 
-Loading indicator. Color from `currentColor`. Import: `import { KptSpinner } from '@konce-pt/angular';`
+Loading indicator. Primary colour by default; `color` on the host changes it (`color: inherit` takes the surrounding text). Import: `import { KptSpinner } from '@konce-pt/angular';`
 
 ## Inputs
 - `size`: string (e.g. '2rem', default '1.5rem'); `label`: string (aria)
@@ -8,3 +8,12 @@ Loading indicator. Color from `currentColor`. Import: `import { KptSpinner } fro
 ## Example
     <kpt-spinner />
     <kpt-spinner size="2rem" label="Loading…" />
+
+## Tokens
+The host sets `color: var(--kpt-color-primary)` and the ring is drawn in `currentColor`; the ring width is 8% of `size`, at least 2px.
+
+## Accessibility
+The ring is `aria-hidden`; next to it sits a visually hidden `.kpt-spinner__label` with
+`role="status"`. Its text — `label`, or `spinner.label` — is written a frame after the spinner
+appears, because a status region that is born already filled in is skipped by most screen readers.
+Under `prefers-reduced-motion` the rotation slows down instead of stopping.

package/src/lib/split-button/llms.txt

@@ -5,7 +5,9 @@ Import: `import { KptSplitButton } from '@konce-pt/angular';`
 Requires `import '@angular/cdk/overlay-prebuilt.css';`
 
 ## Inputs
-- `variant`: KptButtonVariant (default 'filled')
+- `variant`: `KptSplitButtonVariant` = 'filled' | 'tonal' | 'outline' | 'text' (default 'filled') —
+  the subset of `KptButtonVariant` that has a style; `outline` and `text` use the `--kpt-button-outline-*`
+  and `--kpt-button-text-*` tokens, so they match `kpt-button` in the same row
 - `items`: KptMenuItem<T>[] — { label, value?, icon?, danger?, disabled?, separator? }
   It also honors `header` (a non-clickable row with `avatar`/`label`/`description`), `description`
   (a second line) and `badge` + `badgeVariant` (a badge on the right) — described in full in menu/llms.txt.
@@ -15,6 +17,12 @@ Requires `import '@angular/cdk/overlay-prebuilt.css';`
 - `primaryClick`: void — a click on the primary button
 - `selected`: KptMenuItem<T> — an entry picked from the menu
 
+## Keyboard
+The toggle is a menu button: `aria-haspopup="menu"`, a live `aria-expanded`, `aria-controls` while
+open. `↓` / `↑` on it open the menu on the first / last item; inside, `↓` / `↑` wrap, `Home` / `End`
+jump, `Escape` / `Tab` close, and closing or picking returns focus to the toggle. Same rules as the
+menu — see menu/llms.txt.
+
 ## Example
     <kpt-split-button [items]="items" (primaryClick)="save()" (selected)="onItem($event)">Save</kpt-split-button>
 
@@ -25,4 +33,5 @@ Requires `import '@angular/cdk/overlay-prebuilt.css';`
     ];
 
 ## Tokens
-Colors inherited from the button; the panel `--kpt-color-surface-raised`, `--kpt-elevation-3`.
+Colors: `filled` / `tonal` from `--kpt-color-primary` / `--kpt-color-muted`, `outline` / `text`
+from the `--kpt-button-*` tokens of those variants; the panel `--kpt-color-surface-raised`, `--kpt-elevation-3`.

package/src/lib/splitter/llms.txt

@@ -7,9 +7,18 @@ Import: `import { KptSplitter } from '@konce-pt/angular';`
 - `orientation`: 'horizontal' | 'vertical' (KptSplitterOrientation)
 - `startSize`: model<number> — the size of the first pane in % (two-way)
 - `minSize`: number (%) — the minimum pane size
+- `ariaLabel`: string — the handle's name; empty = `splitter.resize` from the dictionary
+- `ariaLabel`: string — the handle's name; empty = `splitter.resize` from the dictionary
+- `ariaLabel`: string — the handle's name; empty = `splitter.resize` from the dictionary
+- `ariaLabel`: string — the handle's name; empty = `splitter.resize` from the dictionary
 
 ## Accessibility
-The handle is a `role="separator"`, arrow keys resize it; dragging works with the mouse.
+The handle is a focusable `role="separator"` (the WAI-ARIA window splitter): `aria-valuenow`,
+`aria-valuemin`/`aria-valuemax` (from `minSize`), `aria-controls` pointing at the first pane, and a
+name from `ariaLabel` or `splitter.resize` in the dictionary. Arrow keys resize by 2%, `Home`/`End`
+jump to the minimum/maximum. `aria-orientation` describes the handle's line, not the layout —
+side-by-side panes have a vertical handle. The host takes `height: 100%`, so a height set on the
+parent reaches the panes.
 
 ## Example
     <kpt-splitter orientation="horizontal" [(startSize)]="size">

package/src/lib/stepper/llms.txt

@@ -19,3 +19,11 @@ Import: `import { KptStepper, KptStep } from '@konce-pt/angular';`
 
 ## Tokens
 The active/completed step: `--kpt-color-primary` (marker, connector).
+
+## Accessibility
+The header is an `<ol>` of real buttons, so every step is reachable with the keyboard and the list
+announces how many there are. Each marker is named from the dictionary — `stepper.step`
+(“Step 2: Delivery”) or `stepper.stepDone` (“…, completed”) — because the visible marker is only a
+number or a check; the visible label is `aria-hidden` so it is not read twice. The active marker
+carries `aria-current="step"`. After `next()` focus stays where it was — move it into the new step
+yourself when the step is long.

package/src/lib/switch/llms.txt

@@ -13,5 +13,16 @@ Import: `import { KptSwitch } from '@konce-pt/angular';`
 - `labelPosition`: 'start' | 'end' (default 'end') — the `label` to the left or to the right of the switch.
 - `onLabel`/`offLabel`: string — the state text; shown according to `checked` (the on state highlighted with `--kpt-color-primary`). Can be combined with a static `label`.
 
+## Screen reader and keyboard
+The `onLabel`/`offLabel` text is `aria-hidden`: `role="switch"` already announces the state, and
+text inside the `<label>` would change the switch's name on every toggle.
+
+## Label and description
+`id` goes to the native field — the host never carries it; without one it is generated. Inside
+`kpt-form-field` the control links itself: the wrapper's `label[for]` points at it and the hint or
+error is added to `aria-describedby`, so `controlId` is not needed. Without a wrapper, name it with
+`ariaLabel`. Inside `kpt-form-field` the switch gets both names: the wrapper label and its own
+`label`.
+
 ## Tokens
 `--kpt-color-primary`, `--kpt-color-border-strong`, `--kpt-color-surface`, `--kpt-elevation-1`.

package/src/lib/switch-group/llms.txt

@@ -22,3 +22,14 @@ Built on Signal Forms (`FormValueControl<T | T[] | null>`, the `value` model). I
 Every entry is a `kpt-switch` with a one-way `[checked]`. In single mode turning one on sets `value` to that
 option, which switches the others off automatically. In `multiple` mode the value is normalized to an array — turning
 one on adds the option's value, turning it off removes it. It renders `kpt-switch`, so it inherits its look and tokens.
+
+## Screen reader and keyboard
+`aria-invalid` is not supported on `role="group"`, so the error state is carried by each switch. In
+single mode the switches are mutually exclusive and nothing announces that turning one on turned
+another off — for a single choice prefer `kpt-radio-group`.
+
+## Label and description
+`id` goes to the focusable element — the host never carries it; without one it is generated. A `div`
+with a role is not named by `label[for]`, so inside `kpt-form-field` it gets `aria-labelledby`
+pointing at the wrapper's label (unless `ariaLabel` is set), and the hint or error is added to
+`aria-describedby`. No `controlId` needed. New: `id` and `ariaLabel` on the `group`.

package/src/lib/tabs/llms.txt

@@ -19,3 +19,10 @@ Import: `import { KptTabs, KptTab } from '@konce-pt/angular';`
 
 ## Tokens
 The active tab: `--kpt-color-primary` (text + bottom edge).
+
+## Keyboard and ARIA
+The tab row is a single `Tab` stop (roving `tabindex`): `ArrowLeft`/`ArrowRight` move between tabs,
+wrapping at the ends, `Home`/`End` jump to the first/last one, and disabled tabs are skipped.
+Moving activates the tab straight away; the next `Tab` goes to the panel (`tabindex="0"`).
+Each tab has an `id`, the active one points at the panel with `aria-controls`, and the panel is
+named by the active tab (`aria-labelledby`).

package/src/lib/textarea/llms.txt

@@ -10,5 +10,17 @@ Import: `import { KptTextarea } from '@konce-pt/angular';`
 ## Example
     <kpt-textarea [formField]="f.notes" placeholder="Notes…" autoResize />
 
+## Screen reader and keyboard
+`maxLength`: number — the native `maxlength` (under `[formField]` it comes from `maxLength()` in the
+schema); `counter`: boolean — a "12 / 280" counter under the field, read together with it through
+`aria-describedby`.
+
+## Label and description
+`id` goes to the native field — the host never carries it; without one it is generated. Inside
+`kpt-form-field` the control links itself: the wrapper's `label[for]` points at it and the hint or
+error is added to `aria-describedby`, so `controlId` is not needed. Without a wrapper, name it with
+`ariaLabel`. New: `id`, `ariaLabel` and `required` (→ `aria-required`); `[formField]` binds
+`required`.
+
 ## Tokens
 `--kpt-form-field-*`.

package/src/lib/toast/llms.txt

@@ -13,10 +13,28 @@ Place the container once in the application: `<kpt-toast-container />`.
     toast.info(msg, opts); toast.warning(msg, opts);
     toast.show(msg, { variant, title, duration }); // duration in ms, 0 = no auto-dismiss
     toast.dismiss(id); toast.clear();
+    toast.success('Deleted', { duration: 8000, action: { label: 'Undo', run: () => restore() } });
+    toast.pause(); toast.resume();
 
 ## KptToast
-`{ id, message, title?, variant: 'info'|'success'|'warning'|'danger', duration }`
+`{ id, message, title?, variant: 'info'|'success'|'warning'|'danger', duration, action?: { label, run } }`
+
+## Actions and pausing
+`action: { label, run }` adds one button to the toast (typically “Undo”); a click calls `run` and
+dismisses the toast. Give such toasts a longer `duration`, and keep the action available elsewhere.
+`pause()` / `resume()` stop and continue every timer; the container calls them on hover and focus,
+and resumes by itself when the stack empties.
 
 ## Tokens
 `--kpt-color-surface-raised`, `--kpt-elevation-3`, the accent `--kpt-color-{info,success,warning,danger}`,
 stacking `--kpt-z-toast`.
+
+## Accessibility
+Announcements go through two permanent, visually hidden live regions next to the stack —
+`aria-live="polite"` for ordinary toasts and `aria-live="assertive"` for `danger` — and not through
+the toasts themselves: a live region has to exist before content appears in it, and nested regions
+are read twice by some screen readers. Each region is cleared before it is written, so the same
+text twice is announced twice, and a dismissed toast never re-announces an older one. While there
+are toasts the stack is `role="region"` named `toast.region` (“Notifications”). Pointer or focus on
+the stack pauses every timer (WCAG 2.2.1); the timers resume with the time that was left. The close
+button is labelled from `common.close`.

package/src/lib/tooltip/llms.txt

@@ -29,5 +29,17 @@ current after a change in width, zoom or layout, with no `ResizeObserver`.
     <kpt-button kptTooltip="Save changes" kptTooltipPosition="bottom">Save</kpt-button>
     <span kptTooltip="More information">?</span>
 
+## Accessibility
+- The bubble appears on hover and on keyboard focus. Focus is tracked with `focusin`/`focusout`,
+  so it also works when the focus lands on an inner element (`kpt-button`, `kpt-icon-button`).
+- The text reaches screen readers through a persistent, hidden description linked with
+  `aria-describedby` to the element that actually takes focus (the bubble itself only exists while
+  shown). It is skipped when it would repeat the element's name (an icon button whose label equals
+  the tooltip) and with `onlyWhenTruncated`, where the text is already in the DOM; the visible
+  bubble is then `aria-hidden`.
+- `Escape` closes the bubble, and the pointer can move onto it without it disappearing (a 120 ms
+  grace period) — WCAG 1.4.13.
+- It does NOT replace an accessible name — an icon-only button still needs its own label.
+
 ## Tokens
 Background `--kpt-color-on-surface`, text `--kpt-color-surface` (contrast in both themes), `--kpt-elevation-2`.

package/src/lib/tree/llms.txt

@@ -13,5 +13,26 @@ Import: `import { KptTree, KptTreeNode } from '@konce-pt/angular';`
 ## Example
     <kpt-tree [nodes]="tree" selectable [(selected)]="node" (nodeClick)="open($event)" />
 
+## Expansion is component state, not data
+`expanded` in a node is the initial state only. The component keeps what the user opened or closed
+itself and never writes to the node objects — so two trees fed the same nodes open and close
+independently, and replacing `nodes` with new objects brings their own initial state.
+
+## Keyboard
+The tree is one Tab stop (roving tabindex on the `treeitem` elements), following the WAI-ARIA tree view
+pattern:
+- `↓` / `↑` — the next / previous visible row, `Home` / `End` — the first / last;
+- `→` — expands a closed branch, on an open one moves to its first child;
+- `←` — collapses an open branch, otherwise moves to the parent;
+- `Enter` / `Space` — the same as a click: selects (with `selectable`) or toggles the branch.
+The logic is the pure function `treeKeyAction` in `tree-keys.ts`; the other port has a twin file.
+
+## Accessibility
+`role="tree"`, `treeitem` and `group`; branches carry `aria-expanded`, every row `aria-level`,
+selectable trees `aria-selected`, disabled rows `aria-disabled`. The chevron is mouse-only
+(`aria-hidden`): a button inside a `treeitem` would be a nested control and a second Tab stop per
+row, and the keyboard expands with the arrows anyway. The focus ring is drawn on the row, not on the
+`<li>`, which would outline the whole subtree.
+
 ## Tokens
 Row hover `--kpt-color-surface-variant`; the selected row `--kpt-color-primary`.