@konce-pt/angular 0.9.0 → 0.10.0

package/src/lib/form-field/llms.txt

@@ -12,7 +12,7 @@ Import: `import { KptFormField } from '@konce-pt/angular';`
 - `hint`: string — a hint (hidden while there is an error)
 - `error`: string | null — the error message; when non-empty, the field is marked invalid
 - `required`: boolean — an asterisk next to the label
-- `controlId`: string — the control's id, for the `label[for]` association
+- `controlId`: string — optional; the control's id for `label[for]` (library controls report theirs)
 - `labelType`: 'fixed' | 'over' | 'in' | 'on' — the label variant (default `fixed`)
 
 ## Label variants (labelType)
@@ -48,11 +48,30 @@ reports being filled itself — it provides the `KPT_FORM_FIELD_CONTROL` token w
 Once a control provides the token, `kpt-form-field` stops looking into the DOM and trusts the
 `filled` signal alone — which is why the label rises the instant the value changes.
 
+## Linking the control (label, hint, error)
+`kpt-form-field` provides the `KPT_FORM_FIELD` context to its content, and every library control
+uses it: the control reports its `id` (its own, or a generated one) and `label[for]` points at it,
+so **`controlId` is optional**. A control on a `div` with a role (`kpt-select`, `kpt-datepicker`,
+`kpt-radio-group`, `kpt-rich-text`…) is not named by `label[for]`, so it gets `aria-labelledby`
+pointing at the label. The visible hint or error has an `id` and lands in the control's
+`aria-describedby` — a screen reader hears it when it reaches the field, not only when the error appears.
+
+A custom control links itself with `kptFieldA11y`:
+
+    import { kptFieldA11y } from '@konce-pt/angular';
+
+    readonly id = input<string | null>(null);
+    protected readonly field = kptFieldA11y(this.id, 'my-control');
+    // template: [id]="field.id()" [attr.aria-labelledby]="field.labelledBy()"
+    //           [attr.aria-describedby]="field.describedBy()"
+
+`controlId` given explicitly still wins, and a control without its own `id` takes it.
+
 ## Content projection
 The control goes into the content (ng-content):
 
-    <kpt-form-field label="E-mail" [error]="emailError()" hint="Your work address" required controlId="f-email">
-      <kpt-input [formField]="loginForm.email" type="email" id="f-email" />
+    <kpt-form-field label="E-mail" [error]="emailError()" hint="Your work address" required>
+      <kpt-input [formField]="loginForm.email" type="email" />
     </kpt-form-field>
 
 ## Integration with Signal Forms
@@ -77,4 +96,5 @@ The float variants add: `--kpt-form-field-placeholder` (the resting label),
 
 ## Accessibility
 - The error message carries `role="alert"`.
-- Tie `controlId` to the control's `id` so the label is clickable (`label[for]`).
+- The label, hint and error are linked to the control automatically (`label[for]` or `aria-labelledby`,
+  plus `aria-describedby`) — see "Linking the control" above.

package/src/lib/galleria/llms.txt

@@ -11,5 +11,17 @@ Import: `import { KptGalleria } from '@konce-pt/angular';`
 ## Example
     <kpt-galleria [items]="photos" [(activeIndex)]="idx" />
 
+## Keyboard
+Anywhere inside the gallery, `ArrowLeft`/`ArrowRight` move to the neighbouring image (reversed in
+RTL) and `Home`/`End` to the first/last. When focus is on a thumbnail, it follows the active one.
+
 ## Tokens
-The stage `--kpt-color-muted`; the active thumbnail `--kpt-color-primary`.
+The stage `--kpt-color-muted`; the active thumbnail `--kpt-color-primary`; the arrows `--kpt-color-surface` (85% via `color-mix`, solid on hover) / `--kpt-color-on-surface` with `--kpt-elevation-2`.
+
+## Accessibility
+The large image carries its `alt`. Each thumbnail is a button named by the item's `alt` (or
+`galleria.image` — “Image 3” — when there is none), with `alt=""` on the thumbnail image so the
+name is not read twice; the active one carries `aria-current`. The arrows use `aria-disabled` at
+the ends instead of `disabled`, so they keep the focus. A change of image is announced politely
+through a hidden live region — `galleria.position` (“Image 2 of 4”) plus the `alt` — only after the
+user acts, never on first render.

package/src/lib/i18n/llms.txt

@@ -26,9 +26,9 @@ Import: `import { provideKptI18n, KptI18n } from '@konce-pt/angular';`
 ## The key contract (KptMessages)
 Namespaces: `common` (close/remove/previous/next/clear/done/all), `paginator` (rowsPerPage/range/prevPage/nextPage),
 `select`, `listbox`, `dataView`, `dataTable`, `confirm`, `fileUpload`, `chipsInput`, `dateRange`, `datepicker`,
-`pickList`, `orderList`, `inputNumber`, `password`, `rating`, `spinner`, `speedDial`, `scrollTop`, `splitButton`, `panel`,
+`pickList`, `orderList`, `inputNumber`, `password`, `rating`, `slider`, `colorPicker`, `inputOtp`, `autocomplete`, `spinner`, `speedDial`, `scrollTop`, `splitButton`, `panel`, `splitter`, `stepper`, `image`, `toast`, `avatarGroup`, `meterGroup`,
 `breadcrumb`, `richText`, `auth` (including `auth.promo.*`). Interpolations: `paginator.range` ({start},{end},{total}), `dataTable.filter*` ({column}),
-`richText.styleHeading` ({level}), `auth.continueWith` ({provider}), `auth.passwordHint` and `auth.errorMinLength` ({min}), `rating.star` ({value},{max}). Day and month names in calendars are derived from `Intl` per locale (not from the dictionary).
+`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).
 
 ## Note
 Individual labels can also be overridden per component through the matching `input()` (e.g. `emptyMessage`, `acceptLabel`) —

package/src/lib/icon/llms.txt

@@ -11,6 +11,7 @@ the color from `currentColor`. Import: `import { KptIcon } from '@konce-pt/angul
   built-in names: once the Tabler set is registered there are 5130 legal names, so a closed
   union would reject icons that work at runtime.
 - `size`: string (optional, e.g. '1.25rem') — otherwise inherited from font-size
+- `label`: string — a name for screen readers; with it the icon is `role="img"`, without it `aria-hidden`
 
 ## Available names (built in, no configuration)
 menu, x, chevron-up, chevron-down, chevron-left, chevron-right, check, search
@@ -23,7 +24,8 @@ clipboard, clipboard-text, table, mail, share, external-link, crosshair
 adjustments-horizontal, sun, moon, bell, settings, users, user-circle, logout, login
 layout-dashboard, home, activity, cube, shopping-cart, currency-dollar, arrow-left
 arrow-right, arrow-up-right, arrow-down-right, chart-bar, chart-line, filter, download
-refresh, dots, brand-github, brand-google
+refresh, dots, brand-github, brand-google, layout-grid, grid-dots, checks, paperclip
+send, message-circle, corner-up-left, mood-smile, device-floppy, arrow-back-up, printer
 
 These cover both what the components themselves draw and the staples of an application shell
 (theme, notifications, account, navigation, KPI). A typical admin panel needs nothing else.
@@ -66,3 +68,9 @@ at build time, never straight from runtime/CMS/upload data.
 ## Icon license
 Tabler Icons (MIT). The icons are extracted inline into `icons.ts`. See ICONS-LICENSE at the root.
 Adding an icon: add an entry to `KPT_ICONS`/`KptIconName` (a 24×24 grid, 2px stroke).
+
+## Accessibility
+By default an icon is `aria-hidden` — decorative, which is right next to a text label or inside
+an icon button with its own name. An icon that carries meaning on its own gets `label`: it becomes
+`role="img"` with that `aria-label`. In development builds an unknown name logs one console
+warning per name instead of rendering silently empty.

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

@@ -4,7 +4,9 @@ An icon-only button. `ariaLabel` is required.
 Import: `import { KptIconButton } from '@konce-pt/angular';`
 
 ## Inputs
-- `variant`: 'filled'|'tonal'|'outline'|'text'|'danger'; `size`: 'sm'|'md'|'lg'; `shape`: 'round'|'square'
+- `variant`: 'filled'|'tonal'|'outline'|'text'|'danger' (default 'text'); `size`: 'sm'|'md'|'lg' (default 'md');
+  `shape`: 'round'|'square' (default 'round'). The type is the wider `KptButtonVariant` / `KptButtonSize`,
+  but only these values have a style
 - `type`, `disabled`, `loading`, `ariaLabel` (required)
 - `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)
 - `ariaExpanded`: `boolean | null` = `null` — disclosure state for a button that opens a panel; lands on the inner `<button>` for the same reason

package/src/lib/image/llms.txt

@@ -12,4 +12,13 @@ Import: `import { KptImage } from '@konce-pt/angular';`
     <kpt-image src="/photo.jpg" alt="Photo" preview width="240px" />
 
 ## Tokens
-A semi-transparent preview mask; the `zoom-in` icon; a dark overlay.
+The radius `--kpt-radius-md`; the backdrop and the hover mask `--kpt-color-overlay-scrim`; the × button and the magnifier disc `--kpt-color-surface` / `--kpt-color-on-surface` with `--kpt-elevation-2`.
+
+## Accessibility
+With `preview`, the thumbnail is a `<button aria-haspopup="dialog">` named “Show full size: <alt>”
+(`image.previewOf`, or `image.preview` without `alt`), so it is reached with Tab and opened with
+Enter or Space; the magnifier shows on hover and on `:focus-visible`. The preview is a native modal
+`<dialog>` opened with `showModal()` and named by `alt`: focus moves to its × button and stays inside,
+Escape closes it, the page behind is inert, document scrolling is locked while it is open, and focus
+returns to the thumbnail. It sits in the top layer, so no ancestor with `transform` or
+`overflow: hidden` can clip it.

package/src/lib/input/llms.txt

@@ -39,6 +39,12 @@ The full flow: the `## A form from scratch (Signal Forms)` section in the root l
 `value` (model, required), `disabled`, `readonly`, `required`, `invalid`, `errors`,
 `touched`; the `touch` output (emitted on blur). Do not set them by hand when used with a form.
 
+## 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`.
+
 ## Tokens
 `--kpt-form-field-{bg,text,placeholder,border,border-hover,border-focus,border-error,radius}`.
 

package/src/lib/input-mask/llms.txt

@@ -16,5 +16,16 @@ Import: `import { KptInputMask } from '@konce-pt/angular';`
     <kpt-input-mask [formField]="f.phone" mask="(999) 999-99-99" />
     <kpt-input-mask [(value)]="zip" mask="99-999" />
 
+## Screen reader and keyboard
+The on-screen keyboard follows the mask: only `9` tokens (phone, postal code) give
+`inputmode="numeric"`, otherwise `text`; override it with `inputMode`. `autocomplete` (`tel`,
+`postal-code`…) lets the browser fill the field in.
+
+## 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: `aria-invalid` after touch.
+
 ## Tokens
 The field uses `--kpt-form-field-*`.

package/src/lib/input-number/llms.txt

@@ -62,5 +62,23 @@ and would not show up under any control.
 the error belongs to. Messages are supplied through `errorFor()` with a `touched()` gate — do not
 gate the validators. The full submit flow: `## A form from scratch (Signal Forms)` in the root llms.txt.
 
+## Keyboard
+The field is `role="spinbutton"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow` (and
+`aria-valuetext` with the `suffix`, "5 pcs"). `↑`/`↓` change the value by `step`,
+`PageUp`/`PageDown` by ten steps; stepping is rounded to the precision of `step`. A typed value is
+**not** clamped while typing ("150" with `max` 99 stays "150", so the form's `max()` can report it) —
+it is clamped on blur. The `−`/`+` buttons sit outside the Tab order and do not take focus from the
+field, so focus never drops to `<body>` when a button goes disabled at a limit.
+
+## Screen reader and keyboard
+The value is shown in the active locale's notation (PL `12,5`), without thousands separators — the
+field accepts both a dot and a comma, and digit grouping would clash with what the user types.
+
+## 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`, `required` and `aria-invalid` on the field.
+
 ## Tokens
 The field `--kpt-form-field-*`; the buttons `--kpt-color-muted`.

package/src/lib/input-otp/llms.txt

@@ -15,5 +15,19 @@ Typing a character moves to the next box; Backspace goes back; pasting spreads t
 ## Example
     <kpt-input-otp [formField]="f.code" [length]="6" integerOnly />
 
+## Screen reader and keyboard
+The first cell has `autocomplete="one-time-code"`, so phones offer the code from an SMS; a code that
+arrives in one cell at once (autofill, an on-screen keyboard paste) is spread over the cells like a
+paste. `touch` fires when focus leaves the whole group — not after a paste, and not when moving
+between cells.
+
+## 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. The cells form a named `role="group"`; `id` goes to the
+first cell (clicking the label starts at the beginning), and each cell is named "Character 2 of 6"
+(`inputOtp.cell`).
+
 ## Tokens
 The boxes use `--kpt-form-field-*`.

package/src/lib/knob/llms.txt

@@ -19,5 +19,13 @@ Import: `import { KptKnob } from '@konce-pt/angular';`
     <kpt-knob [formField]="f.level" [step]="5" />          <!-- bounds from min()/max() in form() -->
     <kpt-knob [(value)]="level" [min]="0" [max]="100" [step]="5" />
 
+## 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`, `ariaLabel`; `aria-valuetext` includes
+`suffix` ("40%"), and a disabled knob leaves the Tab order. Use `ariaLabel`, not `aria-label` on the
+host — that one lands on the wrapper.
+
 ## Tokens
 The background arc `--kpt-color-border`; the value `--kpt-color-primary`; text `--kpt-color-on-surface`.

package/src/lib/listbox/llms.txt

@@ -7,11 +7,26 @@ Value: `T` (single) or `T[]` (multiple). Import: `import { KptListbox } from '@k
 - `value`: model<T | T[] | null> (or `formField`)
 - `options`: KptOption<T>[] — { label, value, disabled? }
 - `multiple`: boolean; `filter`: boolean (a search field)
-- `disabled`/`invalid`/`touched`: boolean; `touch`: output
+- `id`/`ariaLabel`: string|null; `required`: boolean
+- `disabled`/`invalid`/`touched`: boolean; `touch`: output (blur of the list)
 
 ## Example
     <kpt-listbox [formField]="f.role" [options]="roles" filter />
     <kpt-listbox [(value)]="tags" [options]="tagOptions" multiple />
 
+## Keyboard
+The WAI-ARIA listbox pattern: the list is one Tab stop and the active option is announced through
+`aria-activedescendant`. `↑`/`↓`, `Home`/`End` and `PageUp`/`PageDown` move the active option,
+skipping disabled ones (no wrapping); typing letters jumps to the next match, diacritics ignored;
+`Space`/`Enter` picks; in `multiple` mode `Ctrl`/`⌘`+`A` selects every visible option (again —
+clears them). The filter field sits before the list (outside the `listbox`) and `↓` moves focus
+from it into the list; the filter itself ignores diacritics ("lodz" finds "Łódź").
+
+## Label and description
+`id` goes to the list (`role="listbox"`), never the host. A `div` with a role is not named by
+`label[for]`, so inside `kpt-form-field` the list gets `aria-labelledby` pointing at the wrapper's
+label (unless `ariaLabel` is set) and the hint or error in `aria-describedby`. New: `id`,
+`ariaLabel`, `required` (→ `aria-required`); `aria-invalid` after touch; `touch` fires on blur of the list.
+
 ## Tokens
 The frame `--kpt-form-field-*`; selection `--kpt-color-primary`.

package/src/lib/megamenu/llms.txt

@@ -8,7 +8,8 @@ Import: `import { KptMegamenu } from '@konce-pt/angular';`
 
 ## Inputs / outputs
 - `items`: KptMenuItem<T>[] (3 levels: top → columns → links)
-- `selected`: KptMenuItem<T> (the clicked link)
+- `ariaLabel`: string — the bar's name for screen readers, e.g. "Main menu"
+- `selected`: KptMenuItem<T> (the clicked link, or a top item without columns)
 
 ## Example
     items = [{
@@ -19,5 +20,24 @@ Import: `import { KptMegamenu } from '@konce-pt/angular';`
       ],
     }];
 
+## Links (`url`)
+An entry with `url` and no children (and not disabled) renders as a real `<a href>` with the same
+look, so the browser handles navigation — opening in a new tab, the status-bar preview. `selected`
+still fires before the browser follows the link.
+
 ## Tokens
 The panel `--kpt-color-surface-raised`, `--kpt-elevation-3`.
+
+## Keyboard
+The same as `kpt-menubar`: the bar is a single `Tab` stop (roving `tabindex`), `ArrowLeft`/`ArrowRight`
+and `Home`/`End` move along it, `ArrowDown` (or `Enter`/`Space`) opens the panel with focus on the
+first link, `ArrowUp` on the last one. In the panel `ArrowDown`/`ArrowUp`/`Home`/`End` walk through
+all links column by column, `ArrowLeft`/`ArrowRight` show the neighbouring item's panel, and
+`Escape` or `Tab` close it and return focus to the top item.
+
+## ARIA
+The bar is `role="menubar"` (`aria-orientation="horizontal"`, named by `ariaLabel`); top items with
+columns carry `aria-haspopup="menu"`, `aria-expanded` and `aria-controls`. The panel is
+`role="menu"` named after the open item, each column is `role="group"` named by its title
+(`aria-labelledby`), and links are `role="menuitem"`. A top item without columns acts as an action:
+it emits `selected` instead of opening an empty panel, and has no caret.

package/src/lib/menu/llms.txt

@@ -21,7 +21,7 @@ Import: `import { KptMenu, KptMenuItem } from '@konce-pt/angular';`
 - `header?: boolean` — a header row: a non-clickable block of text instead of a menu entry. It holds the
   signed-in user's details (`avatar` + `label` + `description`) or a description of what the menu does. Rendered
   as a `<div role="presentation">` — it does not take focus and is not a `menuitem`.
-- `items?`, `url?` — used by the menubar / megamenu
+- `items?`, `url?` — used by the menubar / megamenu; an entry with `url` (no children, not disabled) renders as `<a href>`
 
 The `header`, `description`, `badge` and `avatar` fields are honored by `kpt-context-menu` and `kpt-split-button` too.
 
@@ -43,12 +43,22 @@ The `header`, `description`, `badge` and `avatar` fields are honored by `kpt-con
 The panel `--kpt-color-surface-raised`, `--kpt-elevation-3`; a danger entry `--kpt-color-danger`;
 descriptions and icons `--kpt-color-on-surface-muted`, `--kpt-font-size-xs`.
 
+## Keyboard
+- `↓` / `↑` on the trigger open the menu with focus on the first / last item; a click, `Enter`
+  or `Space` opens it on the first.
+- Inside: `↓` / `↑` move between items and wrap around, `Home` / `End` jump to the ends;
+  disabled items, separators and headers are skipped.
+- `Escape` and `Tab` close the menu, and so does picking an item — focus returns to the trigger.
+- Items carry `tabindex="-1"` (roving focus), so an open menu is one Tab stop, not one per item.
+
+The logic lives in `menu-keys.ts`, shared with `kpt-split-button`; the other port has a twin file.
+
 ## A11y
-The panel is `role="menu"`, entries are `role="menuitem"` (native `<button>` elements — keyboard support with no
-extra code). The header sits outside keyboard navigation. The badge value becomes part of the entry's accessible
+The panel is `role="menu"`, entries are `role="menuitem"` (native `<button>` elements). The header sits outside keyboard navigation. The badge value becomes part of the entry's accessible
 name ("Notifications 4").
 
-The trigger gets `aria-haspopup="menu"` and a live `aria-expanded`. They are placed on the
+The trigger gets `aria-haspopup="menu"`, a live `aria-expanded` and, while open, `aria-controls`
+pointing at the panel. They are placed on the
 interactive control INSIDE the slot (the projected `<button>`/`<a>`), never on the
 `.kpt-menu__trigger` wrapper — giving that wrapper a role would create a nested control and a second
 tab stop, and state attributes on a roleless element violate `aria-allowed-attr`.

package/src/lib/menubar/llms.txt

@@ -7,6 +7,7 @@ Import: `import { KptMenubar } from '@konce-pt/angular';`
 
 ## Inputs / outputs
 - `items`: KptMenuItem<T>[] — the top-level entries; submenus live in each entry's `items?`
+- `ariaLabel`: string — the bar's name for screen readers, e.g. "Editor menu"
 - `selected`: KptMenuItem<T>
 
 ## Example
@@ -17,5 +18,25 @@ Import: `import { KptMenubar } from '@konce-pt/angular';`
       { label: 'Help' },
     ];
 
+## Links (`url`)
+An entry with `url` and no children (and not disabled) renders as a real `<a href>` with the same
+look, so the browser handles navigation — opening in a new tab, the status-bar preview. `selected`
+still fires before the browser follows the link.
+
 ## Tokens
 The bar `--kpt-color-surface-raised`; the dropdown `--kpt-elevation-3`.
+
+## Keyboard
+The bar follows the WAI-ARIA menubar pattern and is a single `Tab` stop (roving `tabindex`).
+- On a top item: `ArrowLeft`/`ArrowRight` move along the bar (wrapping, skipping disabled items),
+  `Home`/`End` jump to the ends; `ArrowDown`, `Enter` or `Space` open the submenu with focus on its
+  first entry, `ArrowUp` on its last one.
+- In a submenu: `ArrowDown`/`ArrowUp`/`Home`/`End` move between entries, `ArrowLeft`/`ArrowRight`
+  open the neighbouring submenu, `Escape` and `Tab` close it and return focus to the top item.
+- While a submenu is open, moving along the bar opens the neighbour's submenu as well.
+
+## ARIA
+The bar is `role="menubar"` with `aria-orientation="horizontal"`, named by `ariaLabel`. Top items
+with a submenu carry `aria-haspopup="menu"`, `aria-expanded` and (while open) `aria-controls`; each
+submenu is `role="menu"` named after its top item. The bar is a plain `<div>`, not `<nav>` — wrap
+it in your own `<nav aria-label="…">` when it is the site navigation.

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

@@ -7,9 +7,19 @@ Import: `import { KptMeterGroup } from '@konce-pt/angular';`
 - `values`: KptMeterItem[] — { label, value, color? }
 - `max`: number | undefined — the reference total (by default the sum of the values = 100%)
 - `showLegend`: boolean (default true)
+- `label`: string — the meter's name; empty = `meterGroup.label`
+- `legendValue`: 'percent' | 'value' (default 'percent') — what the legend shows next to each label
+- `unit`: string — appended to the values in the legend and in `aria-valuetext` (e.g. 'GB')
 
 ## Example
     <kpt-meter-group [values]="[{label:'Used', value:70}, {label:'Free', value:30}]" />
 
 ## Tokens
 Segments: the `--kpt-color-{primary,info,success,warning,danger}` palette or a custom `color`.
+
+## Accessibility
+The track is `role="meter"` named by `label` (or `meterGroup.label`), with `aria-valuemin="0"`,
+`aria-valuenow` set to the sum and `aria-valuemax` set to the real total — `max`, or the sum without
+it. `aria-valuetext` spells out the split (“Photos 42 GB, Videos 28 GB, …”), so the segments reach
+the screen reader even with the legend hidden. Keep the legend visible anyway: it is the text
+alternative to the colours.

package/src/lib/order-list/llms.txt

@@ -23,6 +23,15 @@ end. Either way the selection follows the item, so the next button press moves t
 ## Tokens
 Selection `--kpt-color-primary`; buttons `--kpt-color-surface-raised`.
 
+## Keyboard
+The list is a `listbox` with a single Tab stop (roving tabindex), and the selection follows focus:
+- `↓` / `↑` select the next / previous item (wrapping), `Home` / `End` the first / last;
+- `Alt`+`↑` / `Alt`+`↓` move the selected item one place up / down — focus travels with it, so
+  repeated presses keep moving the same entry.
+The up / down buttons stay and act on the same selection.
+
 ## Accessibility
-Native HTML5 drag and drop has no keyboard equivalent, so the up/down buttons stay the full keyboard
-path — `dragdrop` adds to them, it never replaces them.
+The list is named after `header` (`aria-label`) and the selected item carries `aria-selected`.
+Both buttons are labelled from the dictionary and go disabled while nothing is selected. Native
+HTML5 drag and drop has no keyboard equivalent — `Alt`+arrows and the buttons cover it, and
+`dragdrop` adds to them, it never replaces them.

package/src/lib/panel/llms.txt

@@ -18,3 +18,10 @@ A panel with a header and optional collapsing. Import: `import { KptPanel } from
 
 ## Tokens
 The header `--kpt-color-surface-variant`; the border `--kpt-color-border`.
+
+## Accessibility
+The toggle is a native button with `aria-expanded` and `aria-controls` pointing at the body. Its
+name says which panel it collapses — `panel.toggleNamed` (“Collapse / expand Settings”) when there
+is a `header`, `panel.toggle` otherwise — so several panels on one page are told apart. A collapsed
+body is `inert` and `aria-hidden`. The header title is not a heading — add your own when the panel
+should appear in the document outline.

package/src/lib/password/llms.txt

@@ -7,7 +7,7 @@ Import: `import { KptPassword } from '@konce-pt/angular';`
 - `value`: model<string> (or `formField`)
 - `feedback`: boolean — shows the strength meter (4 bars + a label)
 - `placeholder`: string
-- `id`: string — the id of the native field; ties the label to `kpt-form-field [controlId]`
+- `id`: string|null — the id of the native field (the host never carries it); generated when absent
 - `autocomplete`: string | null = 'current-password' — in sign-up and reset flows set it to
   `new-password`, otherwise the password manager fills in the old password instead of proposing a new one
 - `disabled`/`invalid`/`touched`: boolean; `touch`: output
@@ -19,5 +19,13 @@ A 0–4 score: length ≥8, lower+upper case, a digit, a special character. Colo
     <kpt-password [formField]="f.password" feedback />
     <kpt-password [(value)]="pass" />
 
+## 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`. The host no longer carries the `id` (it used to, so `label[for]` pointed at
+`kpt-password` and the same id existed twice). New: `ariaLabel`, `required`, `readonly`/`readOnly`,
+`aria-invalid` after touch; with `feedback` the strength label is added to `aria-describedby`.
+
 ## Tokens
 The field `--kpt-form-field-*`; the meter bars `--kpt-color-{danger,warning,info,success}`.

package/src/lib/pick-list/llms.txt

@@ -28,6 +28,16 @@ leaves a panel also leaves that panel's selection.
 ## Tokens
 Selection `--kpt-color-primary`; headers `--kpt-color-surface-variant`.
 
+## Keyboard
+Each list is a `listbox` with `aria-multiselectable` and a single Tab stop (roving tabindex):
+- `↓` / `↑` move between items (wrapping), `Home` / `End` jump to the ends;
+- `Space` toggles the focused item's selection (`aria-selected`), the same as a click;
+- `Enter` moves the focused item to the other list, the same as a double-click — focus stays at
+  that position in the list, on the next item.
+The move buttons act on the same selection, so the whole control works without a mouse.
+
 ## Accessibility
-Native HTML5 drag and drop has no keyboard equivalent, so the four move buttons stay the full
-keyboard path — `dragdrop` adds to them, it never replaces them.
+Each list is named after its header (`aria-label`). The four move buttons are labelled from the
+dictionary, so "move all right" is distinguishable from "move right" without seeing the double
+chevron. Native HTML5 drag and drop has no keyboard equivalent — `Enter` and the buttons cover
+everything it does, and `dragdrop` adds to them, it never replaces them.

package/src/lib/popover/llms.txt

@@ -4,6 +4,10 @@ A popover — arbitrary content in a bubble on CDK Overlay (richer than a toolti
 Requires `import '@angular/cdk/overlay-prebuilt.css';`
 Import: `import { KptPopover } from '@konce-pt/angular';`
 
+## Inputs / model
+- `placement`: 'bottom' | 'top' (default 'bottom') — the preferred side; CDK flips it when there is no room
+- `open`: model<boolean> (default false) — two-way, so the application can close the bubble from code
+
 ## Slots
 - the element carrying the `kptPopoverTrigger` attribute = the trigger; everything else = the panel
 
@@ -13,5 +17,12 @@ Import: `import { KptPopover } from '@konce-pt/angular';`
       <div>Rich popover content…</div>
     </kpt-popover>
 
+## Focus and keyboard
+The control inside the trigger slot gets `aria-haspopup="dialog"`, a live `aria-expanded` and, while
+open, `aria-controls` — on the real `<button>`, not on the wrapper. Opening moves focus to the first
+interactive element of the bubble; `Escape` or a click outside closes it, and focus returns to the
+trigger when it was inside the bubble. Focus is not trapped — the popover is supporting content, not
+a modal.
+
 ## Tokens
 `--kpt-color-surface-raised`, `--kpt-elevation-3`.

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

@@ -11,5 +11,16 @@ Import: `import { KptRadioGroup, KptOption } from '@konce-pt/angular';`
 - `value`: model<T>; `options`: KptOption<T>[] `{ label, value, disabled? }`
 - `disabled`/`invalid`/`touched`: boolean; `name`: string (automatic); the `touch` output.
 
+## Screen reader and keyboard
+`orientation`: 'vertical' (default) | 'horizontal' — options in a column or in a wrapping row; also
+sets `aria-orientation`.
+
+## 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`, `ariaLabel` and `required` (→ `aria-required`)
+on the `radiogroup`.
+
 ## Tokens
 `--kpt-color-primary`, `--kpt-form-field-border`.

package/src/lib/rating/llms.txt

@@ -4,15 +4,29 @@ A star rating on Signal Forms. Import: `import { KptRating } from '@konce-pt/ang
 
 ## Inputs
 - `value`: model<number>; `count`: number (number of stars, default 5)
-- `readonly`/`disabled`/`touched`: boolean; `touch`: output
+- `allowHalf`: boolean — half stars, the value goes in steps of 0.5
+- `readonly`/`disabled`/`required`/`invalid`/`touched`: boolean; `touch`: output
+- `id`/`ariaLabel`: string|null — `id` goes to the group, never the host
 
 ## Example
     <kpt-rating [formField]="f.score" [count]="5" />
-    <kpt-rating [value]="4" readonly />
+    <kpt-rating [(value)]="score" allowHalf ariaLabel="Rating" />
+    <kpt-rating [value]="4.3" readonly />
 
 ## Accessibility
-`role="slider"` with `aria-valuenow`/`aria-valuemax`; each star is a real button labelled from
-`rating.star` (`{value}`, `{max}`) — EN `1 of 5`, PL `1 z 5`.
+`role="radiogroup"` named by `ariaLabel` or the `kpt-form-field` label; each star is
+`role="radio"` with `aria-checked`, labelled from `rating.star` (`{value}`, `{max}`) — EN `1 of 5`,
+PL `1 z 5`. One Tab stop: `→`/`↑` raise the score by one, `←`/`↓` lower it (mirrored in RTL),
+`Home`/`End` set the extremes, `Delete`/`Backspace` clear it; clicking the chosen star also clears it.
+`readonly` renders `role="img"` named "4 of 5" with no buttons, so a screen reader does not announce
+a row of disabled controls. `touch` fires when focus leaves the group.
+
+## Half stars
+`allowHalf` splits every star into two halves, each its own `role="radio"` ("3.5 of 5" — the number
+follows the page language, PL "3,5 z 5"), so the group keeps the radio pattern: clicking the left half
+gives x.5, and the arrows step by 0.5. Read-only stars show the value rounded to a half (4.3 → four
+and a half stars) while the name carries the exact score ("4.3 of 5"), so an average can be shown
+as it is.
 
 ## Tokens
 Filled stars `--kpt-color-warning`; empty ones `--kpt-color-border-strong`.

package/src/lib/rich-text/llms.txt

@@ -51,6 +51,9 @@ they are inert, so they open no new door.
 - `link` (a URL prompt), `clear` (remove formatting), `html` (a toggle for the HTML source view — editing raw HTML)
 
 ## Keyboard
+- The toolbar is a named `role="toolbar"` ("Formatting", `richText.toolbar`) with one Tab stop:
+  `←`/`→` (mirrored in RTL) and `Home`/`End` move between tools, skipping disabled ones; the stop
+  remembers the last tool, so Tab from the toolbar goes straight to the editor.
 - Tab / Shift+Tab inside a list item = indent / one level up (the same as `indent`/`outdent`).
 - Tab / Shift+Tab inside a table cell = the next / previous cell (with its content selected).
   A list inside a cell takes precedence — only once it can no longer be indented does Tab move to another cell.
@@ -77,3 +80,18 @@ potentially untrusted (a database, another user, a CMS); on the way out of the c
 The "paste"/"paste without formatting" clipboard tools use the async Clipboard API (which needs browser permission).
 An exception to execCommand: list indentation is done with our own DOM code — `execCommand('indent')` produces
 invalid `ul > ul` in Chrome (or a `blockquote` with a margin, which the sanitizer would strip anyway).
+
+## Screen reader and keyboard
+`link` opens a small dialog instead of the browser's `prompt()`: a labelled URL field (prefilled
+with the current link), `Enter` inserts, `Escape` returns to the text with the selection restored.
+The table context menu is a `role="menu"` of `menuitem`s: it also opens from the keyboard (the menu
+key or `Shift+F10` in a cell), the arrows and `Home`/`End` move, `Escape`/`Tab` close it, and focus
+goes back to the cell. Colour swatches are named ("Dark grey", `richText.swatches.*`) instead of
+their hex codes. The table size grid is still mouse-only.
+
+## 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`, `ariaLabel` and `required` (→ `aria-required`)
+on the `role="textbox"` area.

package/src/lib/scroll-top/llms.txt

@@ -11,5 +11,17 @@ Import: `import { KptScrollTop } from '@konce-pt/angular';`
     <kpt-scroll-top [threshold]="300" />
     <kpt-scroll-top target="#panel" />
 
+## The scrolled element
+Without `target` the button watches the window. `target` is a selector, resolved after render, so
+the element must already be in the page; changing it re-attaches the listener, and the listener is
+removed when the component is destroyed.
+
 ## Tokens
 The button uses `--kpt-color-primary` / `--kpt-color-on-primary`, `--kpt-elevation-3`.
+
+## Accessibility
+A real `<button>` labelled from `scrollTop.label`; while hidden it is `visibility: hidden`, so it is
+out of the tab order and the accessibility tree. It sits in the bottom-end corner
+(`inset-inline-end`), so it moves to the left in RTL. With `prefers-reduced-motion` the scroll is a
+jump instead of smooth and the button appears without a transition. Focus stays on the button after
+the jump — move it to your page heading if that matters.