@konce-pt/react 0.9.1 → 0.10.0

package/dist/accordion/accordion.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, cloneElement, createContext, isValidElement, useContext, useState, } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
+import { useKptId } from "../internal/use-id.js";
 import { KptIcon } from "../icon/icon.js";
 const AccordionContext = createContext(null);
 /**
@@ -46,6 +47,9 @@ export function KptAccordion({ multi = false, animated = true, animationDuration
 /** Panel akordeonu. Umieszczaj w `<KptAccordion>` albo używaj samodzielnie. */
 export function KptAccordionPanel({ title, disabled = false, expanded, defaultExpanded = false, onExpandedChange, index, className, style, children, ...rest }) {
     const accordion = useContext(AccordionContext);
+    const uid = useKptId(undefined, 'kpt-accordion');
+    const headerId = `${uid}-header`;
+    const bodyId = `${uid}-body`;
     const [standalone, setStandalone] = useControllableState({
         value: expanded,
         defaultValue: defaultExpanded,
@@ -63,7 +67,9 @@ export function KptAccordionPanel({ title, disabled = false, expanded, defaultEx
             setStandalone(willOpen);
         onExpandedChange?.(willOpen);
     };
-    return (_jsx("div", { className: cn('kpt-accordion-panel-host', className), style: { ['--kpt-anim-duration']: accordion?.animMs ?? '500ms', ...style }, ...rest, children: _jsxs("div", { className: cn('kpt-accordion-panel', isOpen && 'is-open'), children: [_jsxs("button", { type: "button", className: "kpt-accordion-panel__header", "aria-expanded": isOpen, disabled: disabled, onClick: toggle, children: [_jsx("span", { className: "kpt-accordion-panel__title", children: title }), _jsx(KptIcon, { name: "chevron-down", className: cn('kpt-accordion-panel__chevron', isOpen && 'is-open') })] }), _jsx("div", { className: cn('kpt-accordion-panel__collapse', isOpen && 'is-open'), inert: !isOpen, "aria-hidden": !isOpen, children: _jsx("div", { className: "kpt-accordion-panel__collapse-inner", children: _jsx("div", { className: "kpt-accordion-panel__body", children: children }) }) })] }) }));
+    return (_jsx("div", { className: cn('kpt-accordion-panel-host', className), style: { ['--kpt-anim-duration']: accordion?.animMs ?? '500ms', ...style }, ...rest, children: _jsxs("div", { className: cn('kpt-accordion-panel', isOpen && 'is-open'), children: [_jsxs("button", { type: "button", className: "kpt-accordion-panel__header", id: headerId, "aria-expanded": isOpen, "aria-controls": bodyId, disabled: disabled, onClick: toggle, children: [_jsx("span", { className: "kpt-accordion-panel__title", children: title }), _jsx(KptIcon, { name: "chevron-down", className: cn('kpt-accordion-panel__chevron', isOpen && 'is-open') })] }), _jsx("div", { className: cn('kpt-accordion-panel__collapse', isOpen && 'is-open'), 
+                    // Treść to region nazwany nagłówkiem — czytnik ogłasza nie tylko stan, ale i to, czego dotyczy.
+                    role: "region", id: bodyId, "aria-labelledby": headerId, inert: !isOpen, "aria-hidden": !isOpen, children: _jsx("div", { className: "kpt-accordion-panel__collapse-inner", children: _jsx("div", { className: "kpt-accordion-panel__body", children: children }) }) })] }) }));
 }
 KptAccordionPanel.kptAccordionSlot = 'panel';
 KptAccordion.Panel = KptAccordionPanel;

package/dist/accordion/llms.txt

@@ -7,11 +7,13 @@ Import: `import { KptAccordion } from '@konce-pt/react';`
     <div class="kpt-accordion-host">
       <div class="kpt-accordion-panel-host" style="--kpt-anim-duration: 500ms">
         <div class="kpt-accordion-panel is-open">
-          <button class="kpt-accordion-panel__header" aria-expanded="true">
+          <button class="kpt-accordion-panel__header" id="kpt-accordion-r1-header"
+                  aria-expanded="true" aria-controls="kpt-accordion-r1-body">
             <span class="kpt-accordion-panel__title">Section 1</span>
             <span class="kpt-icon-host kpt-accordion-panel__chevron is-open">…</span>
           </button>
-          <div class="kpt-accordion-panel__collapse is-open">
+          <div class="kpt-accordion-panel__collapse is-open" role="region" id="kpt-accordion-r1-body"
+               aria-labelledby="kpt-accordion-r1-header">
             <div class="kpt-accordion-panel__collapse-inner">
               <div class="kpt-accordion-panel__body">…children…</div>
             </div>
@@ -52,5 +54,7 @@ nothing inside takes focus or reaches a screen reader.
 `--kpt-anim-duration` set by the accordion on each panel.
 
 ## Accessibility
-The header is a native button with `aria-expanded`; the collapsed region is `inert` and
-`aria-hidden`, so it is skipped by both the keyboard and the screen reader.
+Each header is a native button with `aria-expanded` and `aria-controls`; the body is a
+`role="region"` named by its header (`aria-labelledby`), so a screen reader announces both the state
+and what it belongs to. A collapsed body is `inert` and `aria-hidden`, skipped by the keyboard and
+the screen reader alike.

package/dist/alert/alert.d.ts

@@ -1,4 +1,4 @@
-import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import type { ComponentPropsWithRef, ReactNode } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptAlertVariant } from '../shared/types.ts';
 export type { KptAlertVariant };
@@ -9,17 +9,23 @@ export interface KptAlertProps extends Omit<ComponentPropsWithRef<'div'>, 'title
     dismissible?: boolean;
     /** Wywoływane po zamknięciu przez użytkownika. */
     onClosed?: () => void;
+    /** Widoczność (sterowana); bez niej alert sam trzyma stan. */
+    visible?: boolean;
+    defaultVisible?: boolean;
+    onVisibleChange?: (visible: boolean) => void;
     children?: ReactNode;
 }
 /**
  * Komunikat inline (alert). Warianty info/success/warning/danger, opcjonalny tytuł i zamykanie.
  *
  * Zamknięcie chowa komunikat atrybutem `hidden` (tak samo jak port Angulara), a nie odmontowuje
- * go — dzięki temu ten sam alert da się pokazać ponownie bez przebudowy drzewa. Gdy wolisz nim
- * sterować z zewnątrz, po prostu nie renderuj komponentu.
+ * go. `visible`/`onVisibleChange` pozwalają pokazać go ponownie z zewnątrz.
+ *
+ * Rola idzie za wagą komunikatu: `info` i `success` to `role="status"` (czytnik ogłosi je uprzejmie,
+ * nie przerywając), `warning` i `danger` — `role="alert"` (natychmiast).
  *
  * @example
  * <KptAlert variant="success" title="Zapisano">Zmiany zostały zapisane.</KptAlert>
  * <KptAlert variant="warning" dismissible onClosed={onClosed}>Uwaga…</KptAlert>
  */
-export declare function KptAlert({ variant, title, dismissible, onClosed, locale, dictionary, className, children, ...rest }: Readonly<KptAlertProps>): import("react").JSX.Element;
+export declare function KptAlert({ variant, title, dismissible, onClosed, visible, defaultVisible, onVisibleChange, locale, dictionary, className, children, ...rest }: Readonly<KptAlertProps>): import("react").JSX.Element;

package/dist/alert/alert.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
 import { cn } from "../internal/cn.js";
+import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
 const ICONS = {
@@ -13,19 +13,26 @@ const ICONS = {
  * Komunikat inline (alert). Warianty info/success/warning/danger, opcjonalny tytuł i zamykanie.
  *
  * Zamknięcie chowa komunikat atrybutem `hidden` (tak samo jak port Angulara), a nie odmontowuje
- * go — dzięki temu ten sam alert da się pokazać ponownie bez przebudowy drzewa. Gdy wolisz nim
- * sterować z zewnątrz, po prostu nie renderuj komponentu.
+ * go. `visible`/`onVisibleChange` pozwalają pokazać go ponownie z zewnątrz.
+ *
+ * Rola idzie za wagą komunikatu: `info` i `success` to `role="status"` (czytnik ogłosi je uprzejmie,
+ * nie przerywając), `warning` i `danger` — `role="alert"` (natychmiast).
  *
  * @example
  * <KptAlert variant="success" title="Zapisano">Zmiany zostały zapisane.</KptAlert>
  * <KptAlert variant="warning" dismissible onClosed={onClosed}>Uwaga…</KptAlert>
  */
-export function KptAlert({ variant = 'info', title = '', dismissible = false, onClosed, locale, dictionary, className, children, ...rest }) {
+export function KptAlert({ variant = 'info', title = '', dismissible = false, onClosed, visible, defaultVisible = true, onVisibleChange, locale, dictionary, className, children, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
-    const [visible, setVisible] = useState(true);
+    const [isVisible, setVisible] = useControllableState({
+        value: visible,
+        defaultValue: defaultVisible,
+        onChange: onVisibleChange,
+    });
+    const role = variant === 'warning' || variant === 'danger' ? 'alert' : 'status';
     const dismiss = () => {
         setVisible(false);
         onClosed?.();
     };
-    return (_jsx("div", { className: cn('kpt-alert-host', className), hidden: !visible, ...rest, children: _jsxs("div", { className: "kpt-alert", "data-variant": variant, role: "alert", children: [_jsx(KptIcon, { className: "kpt-alert__icon", name: ICONS[variant] }), _jsxs("div", { className: "kpt-alert__content", children: [title ? _jsx("div", { className: "kpt-alert__title", children: title }) : null, _jsx("div", { className: "kpt-alert__message", children: children })] }), dismissible ? (_jsx("button", { className: "kpt-alert__close", type: "button", onClick: dismiss, "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })) : null] }) }));
+    return (_jsx("div", { className: cn('kpt-alert-host', className), hidden: !isVisible, ...rest, children: _jsxs("div", { className: "kpt-alert", "data-variant": variant, role: role, children: [_jsx(KptIcon, { className: "kpt-alert__icon", name: ICONS[variant] }), _jsxs("div", { className: "kpt-alert__content", children: [title ? _jsx("div", { className: "kpt-alert__title", children: title }) : null, _jsx("div", { className: "kpt-alert__message", children: children })] }), dismissible ? (_jsx("button", { className: "kpt-alert__close", type: "button", onClick: dismiss, "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })) : null] }) }));
 }

package/dist/alert/llms.txt

@@ -5,7 +5,7 @@ Import: `import { KptAlert } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-alert-host">
-      <div class="kpt-alert" data-variant="success" role="alert">
+      <div class="kpt-alert" data-variant="success" role="status">
         <span class="kpt-icon-host kpt-alert__icon">…</span>
         <div class="kpt-alert__content">
           <div class="kpt-alert__title">Saved</div>
@@ -19,14 +19,14 @@ Import: `import { KptAlert } from '@konce-pt/react';`
 - `variant`: 'info' | 'success' | 'warning' | 'danger' (default 'info')
 - `title`: string
 - `dismissible`: boolean — adds the close button
+- `visible` / `defaultVisible` / `onVisibleChange` — controlled or uncontrolled visibility
 - `onClosed()` — fires after the user dismisses it
 - `locale`, `dictionary` — i18n overrides for this component only
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Dismissal hides, it does not unmount
-Closing sets `hidden` on the host, the same as the Angular port, so the same alert can be shown
-again without rebuilding the tree. When you would rather drive it from outside, simply do not render
-the component — the internal state is a convenience, not the only way.
+Closing sets `hidden` on the host, the same as the Angular port. `visible` / `onVisibleChange`
+make it controllable, so the same alert can be shown again from outside.
 
 ## The icon follows the variant
 Each variant picks its own icon from the built-in set (`info`, `circle-check`, `alert-triangle`,
@@ -41,5 +41,7 @@ The semantic colour pairs of each variant (`--kpt-color-info` / `-success` / `-w
 `-danger` with their `-subtle` counterparts), `--kpt-radius-md`.
 
 ## Accessibility
-The message is `role="alert"`, so a screen reader announces it as it appears. Use it for something
-that just happened — for a permanent note, style your own container without that role.
+The role follows the weight of the message: `info` and `success` are `role="status"` (read
+politely, without interrupting), `warning` and `danger` are `role="alert"` (read at once). The icon
+is decorative; the × button is labelled from `common.close`. After closing, focus falls back to the
+page — move it yourself in the close handler when the alert was reached with the keyboard.

package/dist/app-shell/app-shell.js

@@ -1,10 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, } from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptId } from "../internal/use-id.js";
 import { useKptBreakpointUp } from "../internal/use-breakpoint.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
+/** Pierwszy element panelu, który przyjmie fokus po otwarciu nakładki. */
+const FOCUSABLE = 'a[href], button:not(:disabled), input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex="-1"])';
 const KptAppShellContext = createContext(null);
 /**
  * Szkielet aplikacji: pasek u góry, panel boczny i treść.
@@ -73,7 +75,31 @@ export function KptAppShell({ toolbar, sidenav, children, sidenavOpen, defaultSi
     }), [isSidenavOpen, isOverlay, sidenavId, setSidenavOpen, closeSidenav]);
     // Scrim blokuje wskaźnik, ale nie klawiaturę — treść pod nakładką nie może łapać fokusu.
     const contentInert = isOverlay && isSidenavOpen;
-    return (_jsx(KptAppShellContext.Provider, { value: context, children: _jsxs("div", { className: cn('kpt-app-shell', dockedOpen && 'kpt-app-shell--nav-open', compactOpen && 'kpt-app-shell--nav-compact-open', className), "data-sidenav-mode": sidenavMode, "data-sidenav-breakpoint": sidenavBreakpoint, "data-sidenav-rail": sidenavRailBreakpoint ?? undefined, ...rest, children: [toolbar, _jsxs("div", { className: "kpt-app-shell__body", children: [_jsx("aside", { className: "kpt-app-shell__sidenav", role: "navigation", tabIndex: -1, id: sidenavId, "aria-label": sidenavLabel || t('appShell.navigation'), children: sidenav }), _jsx("div", { className: "kpt-app-shell__scrim", "aria-hidden": "true", onClick: closeSidenav }), _jsx("main", { className: "kpt-app-shell__content", inert: contentInert, children: children })] })] }) }));
+    // Otwarta nakładka robi treść `inert`, więc fokus zostawiony w niej (albo na przycisku menu)
+    // nie miałby dokąd pójść. Po otwarciu przenosimy go do panelu, po zamknięciu oddajemy tam,
+    // skąd przyszedł — chyba że użytkownik zdążył go przenieść gdzie indziej. Stan `null` przed
+    // pierwszym renderem: nakładka otwarta już przy starcie nie zabiera fokusu.
+    const asideRef = useRef(null);
+    const overlayWasOpen = useRef(null);
+    const returnFocusTo = useRef(null);
+    useEffect(() => {
+        const was = overlayWasOpen.current;
+        overlayWasOpen.current = contentInert;
+        const panel = asideRef.current;
+        if (was === null || was === contentInert || !panel)
+            return;
+        const active = document.activeElement;
+        if (contentInert) {
+            returnFocusTo.current = active instanceof HTMLElement && !panel.contains(active) ? active : null;
+            (panel.querySelector(FOCUSABLE) ?? panel).focus();
+            return;
+        }
+        const focusLost = !active || active === document.body || panel.contains(active);
+        if (focusLost && returnFocusTo.current?.isConnected)
+            returnFocusTo.current.focus();
+        returnFocusTo.current = null;
+    }, [contentInert]);
+    return (_jsx(KptAppShellContext.Provider, { value: context, children: _jsxs("div", { className: cn('kpt-app-shell', dockedOpen && 'kpt-app-shell--nav-open', compactOpen && 'kpt-app-shell--nav-compact-open', className), "data-sidenav-mode": sidenavMode, "data-sidenav-breakpoint": sidenavBreakpoint, "data-sidenav-rail": sidenavRailBreakpoint ?? undefined, ...rest, children: [toolbar, _jsxs("div", { className: "kpt-app-shell__body", children: [_jsx("aside", { ref: asideRef, className: "kpt-app-shell__sidenav", role: "navigation", tabIndex: -1, id: sidenavId, "aria-label": sidenavLabel || t('appShell.navigation'), children: sidenav }), _jsx("div", { className: "kpt-app-shell__scrim", "aria-hidden": "true", onClick: closeSidenav }), _jsx("main", { className: "kpt-app-shell__content", inert: contentInert, children: children })] })] }) }));
 }
 /** Dostęp do stanu shella. Poza `KptAppShell` rzuca — to zawsze błąd użycia. */
 export function useKptAppShell() {

package/dist/app-shell/llms.txt

@@ -57,3 +57,6 @@ decides WHICH state the button flips. The scrim is always in the DOM; CSS contro
 - The panel is an `<aside role="navigation">` with a label and an `id` for `aria-controls`.
 - A closed docked panel leaves the tab order through `visibility`, correct on the first frame.
 - While the overlay is open the content gets `inert`, and Escape closes the panel.
+- Opening the overlay moves focus into the panel (its first focusable element, or the `<aside>`
+  itself); closing it returns focus to where it came from — usually the menu button — unless the user
+  has already moved it elsewhere. An overlay that is open when the page loads does not take focus.

package/dist/autocomplete/autocomplete.d.ts

@@ -1,5 +1,6 @@
 import { type ComponentPropsWithRef } from 'react';
-export interface KptAutocompleteProps extends Omit<ComponentPropsWithRef<'input'>, 'value' | 'defaultValue' | 'onChange'> {
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+export interface KptAutocompleteProps extends Omit<ComponentPropsWithRef<'input'>, 'value' | 'defaultValue' | 'onChange'>, KptI18nOverrides {
     options?: readonly string[];
     value?: string;
     defaultValue?: string;
@@ -12,7 +13,11 @@ export interface KptAutocompleteProps extends Omit<ComponentPropsWithRef<'input'
  * Pole z podpowiedziami. Wartością jest wpisany tekst, nie wybrana opcja — podpowiedzi
  * skracają pisanie, ale nie ograniczają wpisu, więc pole nadaje się też do wartości spoza listy.
  *
+ * Wzorzec WAI-ARIA „combobox z listą”: fokus zostaje w polu, aktywną podpowiedź ogłasza
+ * `aria-activedescendant`, a liczbę podpowiedzi (albo ich brak) — region `polite`. Dopasowanie
+ * pomija wielkość liter i diakrytyki („lodz” znajduje „Łódź”).
+ *
  * @example
  * <KptAutocomplete options={cities} value={city} onValueChange={setCity} placeholder="Miasto…" />
  */
-export declare function KptAutocomplete({ options, value, defaultValue, onValueChange, invalid, touched, onTouch, disabled, className, onBlur, onFocus, onKeyDown, ref, ...rest }: Readonly<KptAutocompleteProps>): import("react").JSX.Element;
+export declare function KptAutocomplete({ options, value, defaultValue, onValueChange, invalid, touched, onTouch, disabled, className, onBlur, onFocus, onKeyDown, ref, id, 'aria-describedby': ariaDescribedBy, locale, dictionary, ...rest }: Readonly<KptAutocompleteProps>): import("react").JSX.Element;

package/dist/autocomplete/autocomplete.js

@@ -1,17 +1,26 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useMemo, useRef, useState, } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
 import { cn } from "../internal/cn.js";
 import { composeRefs } from "../internal/compose-refs.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
+import { foldMentionText } from '@konce-pt/mention';
+import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
 /**
  * Pole z podpowiedziami. Wartością jest wpisany tekst, nie wybrana opcja — podpowiedzi
  * skracają pisanie, ale nie ograniczają wpisu, więc pole nadaje się też do wartości spoza listy.
  *
+ * Wzorzec WAI-ARIA „combobox z listą”: fokus zostaje w polu, aktywną podpowiedź ogłasza
+ * `aria-activedescendant`, a liczbę podpowiedzi (albo ich brak) — region `polite`. Dopasowanie
+ * pomija wielkość liter i diakrytyki („lodz” znajduje „Łódź”).
+ *
  * @example
  * <KptAutocomplete options={cities} value={city} onValueChange={setCity} placeholder="Miasto…" />
  */
-export function KptAutocomplete({ options = [], value, defaultValue = '', onValueChange, invalid = false, touched, onTouch, disabled = false, className, onBlur, onFocus, onKeyDown, ref, ...rest }) {
+export function KptAutocomplete({ options = [], value, defaultValue = '', onValueChange, invalid = false, touched, onTouch, disabled = false, className, onBlur, onFocus, onKeyDown, ref, id, 'aria-describedby': ariaDescribedBy, locale, dictionary, ...rest }) {
+    const { t } = useKptMessages({ locale, dictionary });
+    const field = useKptFieldA11y(id, 'kpt-autocomplete');
     const inputRef = useRef(null);
     const [current, setCurrent] = useControllableState({
         value,
@@ -20,11 +29,26 @@ export function KptAutocomplete({ options = [], value, defaultValue = '', onValu
     });
     const [open, setOpen] = useState(false);
     const [activeIndex, setActiveIndex] = useState(-1);
+    /** Wpisano coś od ostatniego otwarcia — dopiero wtedy ogłaszamy liczbę podpowiedzi. */
+    const [typed, setTyped] = useState(false);
     const showInvalid = invalid && (touched ?? true);
     const filtered = useMemo(() => {
-        const q = current.trim().toLowerCase();
-        return q ? options.filter((option) => option.toLowerCase().includes(q)) : options;
+        const q = foldMentionText(current.trim());
+        return q ? options.filter((option) => foldMentionText(option).includes(q)) : options;
     }, [options, current]);
+    const panelOpen = open && filtered.length > 0;
+    const listId = `${field.id}-list`;
+    const optionId = (index) => `${field.id}-opt-${index}`;
+    const activeOptionId = panelOpen && activeIndex >= 0 && activeIndex < filtered.length ? optionId(activeIndex) : undefined;
+    const announcement = open && typed && current.trim()
+        ? filtered.length
+            ? t('autocomplete.results', { count: filtered.length })
+            : t('autocomplete.noResults')
+        : '';
+    useEffect(() => {
+        if (activeOptionId)
+            document.getElementById(activeOptionId)?.scrollIntoView({ block: 'nearest' });
+    }, [activeOptionId]);
     const pick = useCallback((option) => {
         setCurrent(option);
         setOpen(false);
@@ -38,7 +62,9 @@ export function KptAutocomplete({ options = [], value, defaultValue = '', onValu
         }
         else if (event.key === 'ArrowUp') {
             event.preventDefault();
-            setActiveIndex((index) => Math.max(index - 1, 0));
+            setOpen(true);
+            // Z pola (bez aktywnej) `↑` idzie na ostatnią podpowiedź.
+            setActiveIndex((index) => (index <= 0 ? filtered.length - 1 : index - 1));
         }
         else if (event.key === 'Enter') {
             const option = filtered[activeIndex];
@@ -48,12 +74,22 @@ export function KptAutocomplete({ options = [], value, defaultValue = '', onValu
             }
         }
         else if (event.key === 'Escape') {
-            setOpen(false);
+            // Pierwszy `Escape` zamyka listę, drugi (przy zamkniętej) czyści pole.
+            if (panelOpen) {
+                event.preventDefault();
+                setOpen(false);
+                setActiveIndex(-1);
+            }
+            else if (current) {
+                event.preventDefault();
+                setCurrent('');
+            }
         }
     };
-    return (_jsxs("span", { className: "kpt-autocomplete-host", children: [_jsx("input", { ref: composeRefs(inputRef, ref), className: cn('kpt-autocomplete__input', className), type: "text", role: "combobox", "aria-expanded": open, "aria-invalid": showInvalid || undefined, disabled: disabled, value: current, onChange: (event) => {
+    return (_jsxs("span", { className: "kpt-autocomplete-host", children: [_jsx("input", { ref: composeRefs(inputRef, ref), className: cn('kpt-autocomplete__input', className), type: "text", id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), role: "combobox", "aria-autocomplete": "list", autoComplete: "off", "aria-expanded": panelOpen, "aria-controls": panelOpen ? listId : undefined, "aria-activedescendant": activeOptionId, "aria-invalid": showInvalid || undefined, disabled: disabled, value: current, onChange: (event) => {
                     setCurrent(event.target.value);
                     setOpen(true);
+                    setTyped(true);
                     setActiveIndex(-1);
                 }, onFocus: (event) => {
                     onFocus?.(event);
@@ -61,12 +97,13 @@ export function KptAutocomplete({ options = [], value, defaultValue = '', onValu
                 }, onBlur: (event) => {
                     onBlur?.(event);
                     setOpen(false);
+                    setTyped(false);
                     onTouch?.();
-                }, onKeyDown: handleKeyDown, ...rest }), _jsx(KptOverlay, { open: open && filtered.length > 0, anchor: inputRef.current, onClose: () => setOpen(false), matchAnchorWidth: true, withBackdrop: false, children: _jsx("ul", { className: "kpt-autocomplete__panel", role: "listbox", children: filtered.map((option, index) => (_jsx("li", { className: cn('kpt-autocomplete__option', index === activeIndex && 'is-active'), role: "option", "aria-selected": index === activeIndex, 
+                }, onKeyDown: handleKeyDown, ...rest }), _jsx(KptOverlay, { open: panelOpen, anchor: inputRef.current, onClose: () => setOpen(false), matchAnchorWidth: true, withBackdrop: false, children: _jsx("ul", { className: "kpt-autocomplete__panel", role: "listbox", id: listId, "aria-label": rest['aria-label'], children: filtered.map((option, index) => (_jsx("li", { id: optionId(index), className: cn('kpt-autocomplete__option', index === activeIndex && 'is-active'), role: "option", "aria-selected": index === activeIndex, 
                         // `mousedown` z zablokowanym domyślnym zachowaniem: klik w opcję nie może
                         // zabrać fokusu polu, bo `blur` zamknąłby panel przed wyborem.
                         onMouseDown: (event) => {
                             event.preventDefault();
                             pick(option);
-                        }, onMouseEnter: () => setActiveIndex(index), children: option }, option))) }) })] }));
+                        }, onMouseEnter: () => setActiveIndex(index), children: option }, option))) }) }), _jsx("span", { className: "kpt-autocomplete__live", "aria-live": "polite", children: announcement })] }));
 }

package/dist/autocomplete/llms.txt

@@ -35,6 +35,18 @@ one, Escape closes.
 ## Examples
     <KptAutocomplete options={cities} value={city} onValueChange={setCity} placeholder="City…" />
 
+## Screen reader and keyboard
+The WAI-ARIA combobox-with-list pattern: focus stays in the field, `aria-autocomplete="list"`,
+`aria-controls` and `aria-activedescendant` point at the active suggestion, and a polite live region
+says how many suggestions there are (`autocomplete.results`) or that there are none
+(`autocomplete.noResults`). Matching ignores case and diacritics ("lodz" finds "Łódź"). `↑` from the
+field goes to the last suggestion; the first `Escape` closes the list, the second clears the field.
+
+## Label and description
+`id` goes to the native field, not the host; without one it comes from `KptFormField` or is
+generated. Inside `KptFormField` the wrapper's `label[for]` points at it and the hint or error is
+added to `aria-describedby` (merged with your own). Without a wrapper, name it with `aria-label`.
+
 ## Tokens
 `--kpt-form-field-{bg,text,placeholder,border,border-focus,radius}`,
 `--kpt-color-surface-raised` and `--kpt-elevation-3` for the panel.

package/dist/avatar/avatar.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithRef } from 'react';
+import { type ComponentPropsWithRef } from 'react';
 import type { KptHostProps } from '../internal/types.ts';
 export type KptAvatarSize = 'sm' | 'md' | 'lg' | 'xl';
 export type KptAvatarShape = 'circle' | 'square';
@@ -11,6 +11,8 @@ export interface KptAvatarProps extends Omit<ComponentPropsWithRef<'span'>, 'chi
     icon?: string | null;
     size?: KptAvatarSize;
     shape?: KptAvatarShape;
+    /** Ukrywa awatar przed czytnikiem ekranu, gdy imię jest już napisane obok. */
+    decorative?: boolean;
     /**
      * Propsy wrappera hosta (`.kpt-avatar-host`). To on jest elementem układu, więc klasy
      * pozycjonujące awatar w rodzicu — jak `kpt-card__avatar` — idą właśnie tutaj.
@@ -30,4 +32,4 @@ export interface KptAvatarProps extends Omit<ComponentPropsWithRef<'span'>, 'chi
  * <KptAvatar name="Anna Kowalska" size="lg" />
  * <KptAvatar icon="user" shape="square" />
  */
-export declare function KptAvatar({ src, name, icon, size, shape, hostProps, className, ...rest }: Readonly<KptAvatarProps>): import("react").JSX.Element;
+export declare function KptAvatar({ src, name, icon, size, shape, decorative, hostProps, className, ...rest }: Readonly<KptAvatarProps>): import("react").JSX.Element;

package/dist/avatar/avatar.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { KptIcon } from "../icon/icon.js";
 /**
@@ -14,10 +15,14 @@ import { KptIcon } from "../icon/icon.js";
  * <KptAvatar name="Anna Kowalska" size="lg" />
  * <KptAvatar icon="user" shape="square" />
  */
-export function KptAvatar({ src = null, name = '', icon = null, size = 'md', shape = 'circle', hostProps, className, ...rest }) {
+export function KptAvatar({ src = null, name = '', icon = null, size = 'md', shape = 'circle', decorative = false, hostProps, className, ...rest }) {
     const { className: hostClassName, ...hostRest } = hostProps ?? {};
-    const labelled = !src && !!name;
-    return (_jsx("span", { className: cn('kpt-avatar-host', hostClassName), ...hostRest, children: _jsx("span", { className: cn('kpt-avatar', className), ...rest, "data-size": size, "data-shape": shape, title: name || undefined, role: labelled ? 'img' : undefined, "aria-label": labelled ? name : undefined, children: src ? (_jsx("img", { className: "kpt-avatar__img", src: src, alt: name })) : name ? (_jsx("span", { className: "kpt-avatar__initials", "aria-hidden": "true", children: initialsOf(name) })) : icon ? (_jsx(KptIcon, { name: icon })) : null }) }));
+    // Zdjęcie, które się nie wczytało — awatar wraca wtedy do inicjałów (albo ikony). Pamiętamy,
+    // którego `src` dotyczy błąd, więc nowy adres próbuje się wczytać od nowa.
+    const [brokenSrc, setBrokenSrc] = useState(null);
+    const showImage = !!src && brokenSrc !== src;
+    const labelled = !decorative && !showImage && !!name;
+    return (_jsx("span", { className: cn('kpt-avatar-host', hostClassName), ...hostRest, children: _jsx("span", { className: cn('kpt-avatar', className), ...rest, "data-size": size, "data-shape": shape, title: decorative ? undefined : name || undefined, role: labelled ? 'img' : undefined, "aria-label": labelled ? name : undefined, "aria-hidden": decorative || undefined, children: showImage ? (_jsx("img", { className: "kpt-avatar__img", src: src, alt: decorative ? '' : name, onError: () => setBrokenSrc(src) })) : name ? (_jsx("span", { className: "kpt-avatar__initials", "aria-hidden": "true", children: initialsOf(name) })) : icon ? (_jsx(KptIcon, { name: icon })) : null }) }));
 }
 /** Do dwóch pierwszych liter z kolejnych członów nazwy. */
 function initialsOf(name) {

package/dist/avatar/llms.txt

@@ -16,12 +16,14 @@ Import: `import { KptAvatar } from '@konce-pt/react';`
 - `icon`: string | null — a registry icon name, used when there is neither photo nor name
 - `size`: 'sm' | 'md' | 'lg' | 'xl' (default 'md')
 - `shape`: 'circle' | 'square' (default 'circle')
+- `decorative`: boolean — hides the avatar from screen readers (the name is written next to it)
 - `hostProps` — props for the `.kpt-avatar-host` wrapper
 - `className`, `ref` and every other `<span>` prop go to the inner `.kpt-avatar`
 
 ## Fallback order
-`src` → `name` (up to two initials, uppercased) → `icon`. With none of them the avatar renders as
-an empty shape, which is a valid placeholder.
+`src` → `name` (up to two initials, uppercased) → `icon`. A photo that fails to load drops to the
+next step by itself, and a new `src` is tried again. With none of them the avatar renders as an
+empty shape, which is a valid placeholder.
 
 ## Positioning inside a parent
 The host is the layout element, so classes that place the avatar in its parent go to `hostProps` —
@@ -37,6 +39,8 @@ the overlapping avatar on a card is `hostProps={{ className: 'kpt-card__avatar'
 `--kpt-color-muted`, `--kpt-color-on-muted`, `--kpt-radius-full`, `--kpt-radius-md` (square).
 
 ## Accessibility
-`name` becomes the native `title` — initials alone do not say who this is. Without `src` the avatar
-also gets `role="img"` and `aria-label`, and the initials are `aria-hidden` so a screen reader does
-not spell out "A-K". With `src` the label already lives on the image's `alt`, so it is not doubled.
+`name` goes into the native `title` (initials alone say nothing). With a photo the name is the
+image's `alt`; without one the avatar is `role="img"` with `aria-label`, and the initials are
+`aria-hidden`. A photo that fails to load falls back to the initials (or the icon); a new `src` is
+tried again. `decorative` removes the avatar from the accessibility tree — use it when the name is
+already written next to it.

package/dist/avatar-group/avatar-group.d.ts

@@ -1,15 +1,18 @@
 import type { ComponentPropsWithRef } from 'react';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import { type KptAvatarSize } from '../avatar/avatar.tsx';
 export interface KptAvatarItem {
     name?: string;
     src?: string;
     icon?: string;
 }
-export interface KptAvatarGroupProps extends ComponentPropsWithRef<'div'> {
+export interface KptAvatarGroupProps extends ComponentPropsWithRef<'div'>, KptI18nOverrides {
     avatars?: readonly KptAvatarItem[];
     /** Ile awatarów pokazać, zanim pojawi się „+N". */
     max?: number;
     size?: KptAvatarSize;
+    /** Nazwa grupy dla czytników ekranu, np. „Członkowie projektu”; bez niej grupa nie ma roli. */
+    label?: string;
 }
 /**
  * Grupa nakładających się awatarów z licznikiem „+N". Buduje na `KptAvatar`, więc każdy element
@@ -18,4 +21,4 @@ export interface KptAvatarGroupProps extends ComponentPropsWithRef<'div'> {
  * @example
  * <KptAvatarGroup avatars={team} max={4} />
  */
-export declare function KptAvatarGroup({ avatars, max, size, className, ...rest }: Readonly<KptAvatarGroupProps>): import("react").JSX.Element;
+export declare function KptAvatarGroup({ avatars, max, size, label, locale, dictionary, className, ...rest }: Readonly<KptAvatarGroupProps>): import("react").JSX.Element;

package/dist/avatar-group/avatar-group.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../internal/cn.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptAvatar } from "../avatar/avatar.js";
 /**
  * Grupa nakładających się awatarów z licznikiem „+N". Buduje na `KptAvatar`, więc każdy element
@@ -8,8 +9,15 @@ import { KptAvatar } from "../avatar/avatar.js";
  * @example
  * <KptAvatarGroup avatars={team} max={4} />
  */
-export function KptAvatarGroup({ avatars = [], max = 4, size = 'md', className, ...rest }) {
+export function KptAvatarGroup({ avatars = [], max = 4, size = 'md', label = '', locale, dictionary, className, ...rest }) {
+    const { t } = useKptMessages({ locale, dictionary });
     const shown = avatars.slice(0, max);
     const overflow = Math.max(0, avatars.length - max);
-    return (_jsx("div", { className: cn('kpt-avatar-group-host', className), ...rest, children: _jsxs("div", { className: "kpt-avatar-group", "data-size": size, children: [shown.map((avatar, index) => (_jsx("span", { className: "kpt-avatar-group__item", children: _jsx(KptAvatar, { name: avatar.name || '', src: avatar.src || null, icon: avatar.icon || null, size: size }) }, index))), overflow > 0 ? (_jsxs("span", { className: "kpt-avatar-group__item kpt-avatar-group__more", "data-size": size, children: ["+", overflow] })) : null] }) }));
+    // Sam „+2” nic czytnikowi nie mówi — licznik ma nazwę „i 2 więcej” i podpowiedź z imionami.
+    const hiddenNames = avatars
+        .slice(max)
+        .map((avatar) => avatar.name)
+        .filter(Boolean)
+        .join(', ');
+    return (_jsx("div", { className: cn('kpt-avatar-group-host', className), ...rest, children: _jsxs("div", { className: "kpt-avatar-group", "data-size": size, role: label ? 'group' : undefined, "aria-label": label || undefined, children: [shown.map((avatar, index) => (_jsx("span", { className: "kpt-avatar-group__item", children: _jsx(KptAvatar, { name: avatar.name || '', src: avatar.src || null, icon: avatar.icon || null, size: size }) }, index))), overflow > 0 ? (_jsx("span", { className: "kpt-avatar-group__item kpt-avatar-group__more", role: "img", "data-size": size, "aria-label": t('avatarGroup.more', { count: overflow }), title: hiddenNames || undefined, children: _jsxs("span", { "aria-hidden": "true", children: ["+", overflow] }) })) : null] }) }));
 }

package/dist/avatar-group/llms.txt

@@ -5,9 +5,10 @@ Import: `import { KptAvatarGroup } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-avatar-group-host">
-      <div class="kpt-avatar-group" data-size="lg">
+      <div class="kpt-avatar-group" data-size="lg" role="group" aria-label="Project members">
         <span class="kpt-avatar-group__item">…KptAvatar…</span>…
-        <span class="kpt-avatar-group__item kpt-avatar-group__more" data-size="lg">+2</span>
+        <span class="kpt-avatar-group__item kpt-avatar-group__more" role="img" data-size="lg"
+              aria-label="2 more" title="Marta, Tomasz"><span aria-hidden="true">+2</span></span>
       </div>
     </div>
 
@@ -15,6 +16,7 @@ Import: `import { KptAvatarGroup } from '@konce-pt/react';`
 - `avatars`: `KptAvatarItem[]` — `{ name?, src?, icon? }`
 - `max`: number (default 4) — how many to show before "+N"
 - `size`: `'sm' | 'md' | 'lg' | 'xl'`
+- `label`: string — the group's name; with it the row is `role="group"`
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## One list, three fallbacks
@@ -34,5 +36,6 @@ Every avatar keeps the `title` from `KptAvatar`, so hovering tells you who it is
 The overlap ring uses `--kpt-color-surface`, the "+N" chip `--kpt-color-muted`.
 
 ## Accessibility
-The avatars come from `KptAvatar` with its `role="img"` and `aria-label`; "+N" is plain text, so
-the count is read as part of the group.
+Every avatar keeps its own name. With `label` the row is `role="group"` with that name. The “+N”
+counter is `role="img"` named from `avatarGroup.more` (`{count}` — “2 more”), with the hidden names
+in its `title`. The overlap uses `margin-inline-start`, so it mirrors in RTL.

package/dist/badge/badge.d.ts

@@ -12,6 +12,13 @@ export interface KptBadgeProps extends ComponentPropsWithRef<'span'> {
     overlay?: boolean;
     /** Powyżej tej wartości licznik pokazuje `99+`. */
     max?: number;
+    /**
+     * Znaczenie plakietki dla czytnika ekranu, np. „3 nieprzeczytane”. Sama liczba („3”) albo kropka
+     * nic nie mówią; z `label` widoczny tekst jest ukryty przed czytnikiem, a odczytywana jest etykieta.
+     */
+    label?: string;
+    /** Chowa plakietkę, gdy `value` to `0` albo `null` (nie dotyczy `dot`). */
+    hideZero?: boolean;
     children?: ReactNode;
 }
 /**
@@ -22,4 +29,4 @@ export interface KptBadgeProps extends ComponentPropsWithRef<'span'> {
  * <KptBadge value={128} overlay><KptIcon name="menu" /></KptBadge>
  * <KptBadge dot variant="success" overlay><KptAvatar name="AK" /></KptBadge>
  */
-export declare function KptBadge({ value, variant, size, dot, overlay, max, className, children, ...rest }: Readonly<KptBadgeProps>): import("react").JSX.Element;
+export declare function KptBadge({ value, variant, size, dot, overlay, max, label, hideZero, className, children, ...rest }: Readonly<KptBadgeProps>): import("react").JSX.Element;

package/dist/badge/badge.js

@@ -8,7 +8,8 @@ import { cn } from "../internal/cn.js";
  * <KptBadge value={128} overlay><KptIcon name="menu" /></KptBadge>
  * <KptBadge dot variant="success" overlay><KptAvatar name="AK" /></KptBadge>
  */
-export function KptBadge({ value = null, variant = 'primary', size = 'md', dot = false, overlay = false, max = 99, className, children, ...rest }) {
+export function KptBadge({ value = null, variant = 'primary', size = 'md', dot = false, overlay = false, max = 99, label = '', hideZero = false, className, children, ...rest }) {
     const display = typeof value === 'number' && value > max ? `${max}+` : (value ?? '');
-    return (_jsxs("span", { className: cn('kpt-badge-host', className), ...rest, children: [children, _jsx("span", { className: cn('kpt-badge', overlay && 'kpt-badge--overlay', dot && 'kpt-badge--dot'), "data-variant": variant, "data-size": size, children: dot ? '' : display })] }));
+    const hiddenZero = hideZero && !dot && (value === 0 || value === null || value === '');
+    return (_jsxs("span", { className: cn('kpt-badge-host', className), ...rest, children: [children, hiddenZero ? null : (_jsxs("span", { className: cn('kpt-badge', overlay && 'kpt-badge--overlay', dot && 'kpt-badge--dot'), "data-variant": variant, "data-size": size, children: [_jsx("span", { "aria-hidden": label ? true : undefined, children: dot ? '' : display }), label ? _jsx("span", { className: "kpt-badge__label", children: label }) : null] }))] }));
 }