@konce-pt/react 0.9.1 → 0.10.0

package/dist/form-field/form-field-context.d.ts

@@ -6,8 +6,14 @@
  * zbudowany na liście) zgłaszają je przez `useKptFormFieldFilled`.
  */
 export interface KptFormFieldContextValue {
-    /** Id, którym wrapper wiąże `label[for]` — kontrolka powinna nadać je swojemu elementowi. */
+    /** Id, którym wrapper wiąże `label[for]` — kontrolka bez własnego `id` nadaje je swojemu elementowi. */
     controlId: string;
+    /** Id elementu etykiety albo `undefined`, gdy wrapper jej nie pokazuje. */
+    labelId: string | undefined;
+    /** Id widocznego komunikatu (błąd albo podpowiedź) albo `undefined`. */
+    describedBy: string | undefined;
+    /** Kontrolka z własnym `id` zgłasza je wrapperowi — na nie wskaże `label[for]`. */
+    reportControlId: (id: string | null) => void;
     /** Czy pole jest oznaczone jako nieprawidłowe (niepusty `error` na wrapperze). */
     invalid: boolean;
     /** Zgłasza wypełnienie kontrolki, gdy nie da się go odczytać z DOM. */
@@ -21,3 +27,26 @@ export declare function useKptFormFieldContext(): KptFormFieldContextValue | nul
  * Steruje uniesieniem etykiety w wariantach float.
  */
 export declare function useKptFormFieldFilled(filled: boolean): void;
+/** To, czego kontrolka potrzebuje, żeby wrapper ją nazwał i opisał. */
+export interface KptFieldA11y {
+    /** Id elementu fokusowalnego: własne `id`, potem `controlId` wrappera, potem wygenerowane. */
+    id: string;
+    /**
+     * Id etykiety wrappera — dla kontrolek na elemencie, którego `label[for]` nie nazywa
+     * (`div` z rolą, `contenteditable`). Natywne `input`/`textarea` nazywa już samo `htmlFor`.
+     */
+    labelledBy: string | undefined;
+    /** Id podpowiedzi albo błędu wrappera — do `aria-describedby`. */
+    describedBy: string | undefined;
+}
+/**
+ * Wiąże kontrolkę z otaczającym `KptFormField`. Poza wrapperem zwraca samo `id` (własne albo
+ * wygenerowane) i puste powiązania. Bliźniak `kptFieldA11y` z portu Angulara.
+ *
+ * @example
+ * const field = useKptFieldA11y(id, 'kpt-textarea');
+ * <textarea id={field.id} aria-describedby={field.describedBy} />
+ */
+export declare function useKptFieldA11y(provided: string | undefined, prefix: string): KptFieldA11y;
+/** Łączy kilka id w wartość `aria-describedby`/`aria-labelledby`; `undefined`, gdy nie ma żadnego. */
+export declare function joinIds(...ids: (string | null | undefined | false)[]): string | undefined;

package/dist/form-field/form-field-context.js

@@ -1,4 +1,5 @@
 import { createContext, useContext, useEffect } from 'react';
+import { useKptId } from "../internal/use-id.js";
 export const KptFormFieldContext = createContext(null);
 /** Kontekst pola formularza albo `null`, gdy kontrolka stoi poza `KptFormField`. */
 export function useKptFormFieldContext() {
@@ -15,3 +16,29 @@ export function useKptFormFieldFilled(filled) {
         reportFilled?.(filled);
     }, [reportFilled, filled]);
 }
+/**
+ * Wiąże kontrolkę z otaczającym `KptFormField`. Poza wrapperem zwraca samo `id` (własne albo
+ * wygenerowane) i puste powiązania. Bliźniak `kptFieldA11y` z portu Angulara.
+ *
+ * @example
+ * const field = useKptFieldA11y(id, 'kpt-textarea');
+ * <textarea id={field.id} aria-describedby={field.describedBy} />
+ */
+export function useKptFieldA11y(provided, prefix) {
+    const context = useKptFormFieldContext();
+    const id = useKptId(provided ?? context?.controlId, prefix);
+    const report = context?.reportControlId;
+    const own = provided ?? null;
+    useEffect(() => {
+        if (!report || !own)
+            return;
+        report(own);
+        return () => report(null);
+    }, [report, own]);
+    return { id, labelledBy: context?.labelId, describedBy: context?.describedBy };
+}
+/** Łączy kilka id w wartość `aria-describedby`/`aria-labelledby`; `undefined`, gdy nie ma żadnego. */
+export function joinIds(...ids) {
+    const list = ids.filter((id) => !!id);
+    return list.length ? list.join(' ') : undefined;
+}

package/dist/form-field/form-field.js

@@ -23,7 +23,14 @@ export function KptFormField({ label = '', hint = '', error = null, required = f
     const [nativeFilled, setNativeFilled] = useState(false);
     const [reportedFilled, setReportedFilled] = useState(null);
     const generatedId = useKptId(undefined, 'kpt-form-field-control');
+    const baseId = useKptId(undefined, 'kpt-form-field');
     const id = controlId || generatedId;
+    // Kontrolka z własnym `id` zgłasza je przez kontekst — wtedy `label[for]` wskazuje właśnie je.
+    const [reportedId, setReportedId] = useState(null);
+    const labelFor = controlId || reportedId || generatedId;
+    const labelId = label ? `${baseId}-label` : undefined;
+    const messageId = `${baseId}-message`;
+    const describedBy = error || hint ? messageId : undefined;
     /** Odczytuje wartość projektowanego `input`/`textarea` i aktualizuje stan wypełnienia. */
     const updateFilled = useCallback(() => {
         const el = hostRef.current?.querySelector('.kpt-form-field__control input, .kpt-form-field__control textarea');
@@ -36,6 +43,13 @@ export function KptFormField({ label = '', hint = '', error = null, required = f
     // powtarzamy po każdym renderze — to jeden `querySelector`, nie warto tu optymalizować.
     useEffect(updateFilled);
     const filled = reportedFilled ?? nativeFilled;
-    const context = useMemo(() => ({ controlId: id, invalid: !!error, reportFilled: setReportedFilled }), [id, error]);
-    return (_jsx(KptFormFieldContext.Provider, { value: context, children: _jsx("div", { className: cn('kpt-form-field-host', className), ref: composeRefs(hostRef, ref), onInput: updateFilled, onChange: updateFilled, ...rest, children: _jsxs("div", { className: cn('kpt-form-field', `kpt-form-field--${labelType}`, labelType !== 'fixed' && 'kpt-form-field--float', error && 'kpt-form-field--invalid'), children: [_jsxs("div", { className: cn('kpt-form-field__box', filled && 'is-filled'), children: [label ? (_jsxs("label", { className: "kpt-form-field__label", htmlFor: id || undefined, children: [label, required ? (_jsx("span", { className: "kpt-form-field__required", "aria-hidden": "true", children: "*" })) : null] })) : null, _jsx("div", { className: "kpt-form-field__control", children: children })] }), error ? (_jsx("p", { className: "kpt-form-field__message kpt-form-field__message--error", role: "alert", children: error })) : hint ? (_jsx("p", { className: "kpt-form-field__message kpt-form-field__message--hint", children: hint })) : null] }) }) }));
+    const context = useMemo(() => ({
+        controlId: id,
+        labelId,
+        describedBy,
+        invalid: !!error,
+        reportFilled: setReportedFilled,
+        reportControlId: setReportedId,
+    }), [id, labelId, describedBy, error]);
+    return (_jsx(KptFormFieldContext.Provider, { value: context, children: _jsx("div", { className: cn('kpt-form-field-host', className), ref: composeRefs(hostRef, ref), onInput: updateFilled, onChange: updateFilled, ...rest, children: _jsxs("div", { className: cn('kpt-form-field', `kpt-form-field--${labelType}`, labelType !== 'fixed' && 'kpt-form-field--float', error && 'kpt-form-field--invalid'), children: [_jsxs("div", { className: cn('kpt-form-field__box', filled && 'is-filled'), children: [label ? (_jsxs("label", { className: "kpt-form-field__label", id: labelId, htmlFor: labelFor, children: [label, required ? (_jsx("span", { className: "kpt-form-field__required", "aria-hidden": "true", children: "*" })) : null] })) : null, _jsx("div", { className: "kpt-form-field__control", children: children })] }), error ? (_jsx("p", { className: "kpt-form-field__message kpt-form-field__message--error", role: "alert", id: messageId, children: error })) : hint ? (_jsx("p", { className: "kpt-form-field__message kpt-form-field__message--hint", id: messageId, children: hint })) : null] }) }) }));
 }

package/dist/form-field/llms.txt

@@ -25,7 +25,16 @@ Import: `import { KptFormField } from '@konce-pt/react';`
 
 ## Label wiring
 The wrapper generates a control id and publishes it through context, so `<KptInput>` inside needs
-no configuration — `label[for]` and `input[id]` always match. Pass `controlId` to take over.
+no configuration — `label[for]` and `input[id]` always match. Pass `controlId` to take over; a control
+with its own `id` reports it, and the label follows.
+
+The context also carries the label's id and the id of the visible hint or error. Every library
+control uses them through `useKptFieldA11y`: the hint or error lands in `aria-describedby`, and a
+control on a `div` with a role (`KptSelect`, `KptDatepicker`, `KptRadioGroup`, `KptRichText`…) gets
+`aria-labelledby` pointing at the label, because `label[for]` does not name it. A custom control:
+
+    const field = useKptFieldA11y(id, 'my-control');
+    <div role="slider" id={field.id} aria-labelledby={field.labelledBy} aria-describedby={field.describedBy} />
 
 ## Float labels
 `labelType` other than `fixed` turns on the floating label with an animated transition: `over`

package/dist/galleria/galleria.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithRef } from 'react';
+import { type ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptGalleriaItem {
     src: string;
@@ -16,6 +16,11 @@ export interface KptGalleriaProps extends Omit<ComponentPropsWithRef<'div'>, 'on
 /**
  * Galleria — duży podgląd obrazu z paskiem miniatur i nawigacją.
  *
+ * Klawiatura: na całej galerii strzałki w lewo/prawo przechodzą do sąsiedniego obrazu (w RTL
+ * odwrotnie), `Home`/`End` — do pierwszego/ostatniego; gdy fokus stoi na miniaturze, idzie za
+ * aktywną. Miniatura ma nazwę z `alt` obrazu i `aria-current` na aktywnej, a zmiana obrazu jest
+ * ogłaszana uprzejmie („Obraz 2 z 4: …”) — dopiero po działaniu użytkownika, nie przy starcie.
+ *
  * @example
  * <KptGalleria items={photos} activeIndex={index} onActiveIndexChange={setIndex} />
  */

package/dist/galleria/galleria.js

@@ -1,11 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, 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";
+/** Klawisze przechodzące między obrazami: kierunek względem bieżącego albo skrajny indeks. */
+const NAV_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'Home', 'End']);
 /**
  * Galleria — duży podgląd obrazu z paskiem miniatur i nawigacją.
  *
+ * Klawiatura: na całej galerii strzałki w lewo/prawo przechodzą do sąsiedniego obrazu (w RTL
+ * odwrotnie), `Home`/`End` — do pierwszego/ostatniego; gdy fokus stoi na miniaturze, idzie za
+ * aktywną. Miniatura ma nazwę z `alt` obrazu i `aria-current` na aktywnej, a zmiana obrazu jest
+ * ogłaszana uprzejmie („Obraz 2 z 4: …”) — dopiero po działaniu użytkownika, nie przy starcie.
+ *
  * @example
  * <KptGalleria items={photos} activeIndex={index} onActiveIndexChange={setIndex} />
  */
@@ -16,6 +24,37 @@ export function KptGalleria({ items = [], activeIndex, defaultActiveIndex = 0, o
         defaultValue: defaultActiveIndex,
         onChange: onActiveIndexChange,
     });
+    // Ogłoszenie dopiero po działaniu użytkownika — przy starcie region ma milczeć.
+    const [userMoved, setUserMoved] = useState(false);
+    const thumbsRef = useRef([]);
+    const rootRef = useRef(null);
     const current = items[active] ?? null;
-    return (_jsx("div", { className: cn('kpt-galleria-host', className), ...rest, children: _jsxs("div", { className: "kpt-galleria", children: [_jsxs("div", { className: "kpt-galleria__stage", children: [_jsx("button", { type: "button", className: "kpt-galleria__nav kpt-galleria__nav--prev", disabled: active === 0, "aria-label": t('common.previous'), onClick: () => setActive(Math.max(active - 1, 0)), children: _jsx(KptIcon, { name: "chevron-left" }) }), current ? _jsx("img", { className: "kpt-galleria__image", src: current.src, alt: current.alt || '' }) : null, _jsx("button", { type: "button", className: "kpt-galleria__nav kpt-galleria__nav--next", disabled: active >= items.length - 1, "aria-label": t('common.next'), onClick: () => setActive(Math.min(active + 1, items.length - 1)), children: _jsx(KptIcon, { name: "chevron-right" }) })] }), showThumbnails ? (_jsx("div", { className: "kpt-galleria__thumbs", children: items.map((item, index) => (_jsx("button", { type: "button", className: cn('kpt-galleria__thumb', index === active && 'is-active'), "aria-label": t('galleria.image', { index: index + 1 }), onClick: () => setActive(index), children: _jsx("img", { src: item.thumbnail || item.src, alt: item.alt || '' }) }, index))) })) : null] }) }));
+    const last = items.length - 1;
+    const select = (index) => {
+        if (last < 0)
+            return active;
+        const next = Math.min(Math.max(index, 0), last);
+        setUserMoved(true);
+        setActive(next);
+        return next;
+    };
+    const onKeyDown = (event) => {
+        if (!NAV_KEYS.has(event.key))
+            return;
+        event.preventDefault();
+        const rtl = rootRef.current ? getComputedStyle(rootRef.current).direction === 'rtl' : false;
+        const step = event.key === 'ArrowRight' ? 1 : -1;
+        const target = event.key === 'Home' ? 0 : event.key === 'End' ? last : active + (rtl ? -step : step);
+        const focusOnThumb = thumbsRef.current.some((thumb) => thumb === document.activeElement);
+        const next = select(target);
+        // Fokus na miniaturze idzie za aktywnym obrazem — inaczej strzałka zmieniałaby obraz,
+        // a fokus zostawał na poprzedniej miniaturze.
+        if (focusOnThumb)
+            thumbsRef.current[next]?.focus();
+    };
+    const position = t('galleria.position', { index: active + 1, total: items.length });
+    const announcement = userMoved ? (current?.alt ? `${position}: ${current.alt}` : position) : '';
+    return (_jsx("div", { className: cn('kpt-galleria-host', className), ...rest, children: _jsxs("div", { ref: rootRef, className: "kpt-galleria", onKeyDown: onKeyDown, children: [_jsxs("div", { className: "kpt-galleria__stage", children: [_jsx("button", { type: "button", className: "kpt-galleria__nav kpt-galleria__nav--prev", "aria-disabled": active <= 0 || undefined, "aria-label": t('common.previous'), onClick: () => select(active - 1), children: _jsx(KptIcon, { name: "chevron-left" }) }), current ? _jsx("img", { className: "kpt-galleria__image", src: current.src, alt: current.alt || '' }) : null, _jsx("button", { type: "button", className: "kpt-galleria__nav kpt-galleria__nav--next", "aria-disabled": active >= last || undefined, "aria-label": t('common.next'), onClick: () => select(active + 1), children: _jsx(KptIcon, { name: "chevron-right" }) })] }), showThumbnails ? (_jsx("div", { className: "kpt-galleria__thumbs", children: items.map((item, index) => (_jsx("button", { ref: (el) => {
+                            thumbsRef.current[index] = el;
+                        }, type: "button", className: cn('kpt-galleria__thumb', index === active && 'is-active'), "aria-current": index === active ? 'true' : undefined, "aria-label": item.alt || t('galleria.image', { index: index + 1 }), onClick: () => select(index), children: _jsx("img", { src: item.thumbnail || item.src, alt: "" }) }, index))) })) : null, _jsx("span", { className: "kpt-galleria__live", "aria-live": "polite", children: announcement })] }) }));
 }

package/dist/galleria/llms.txt

@@ -7,13 +7,14 @@ Import: `import { KptGalleria, type KptGalleriaItem } from '@konce-pt/react';`
     <div class="kpt-galleria-host">
       <div class="kpt-galleria">
         <div class="kpt-galleria__stage">
-          <button class="kpt-galleria__nav kpt-galleria__nav--prev">…</button>
-          <img class="kpt-galleria__image" src="…" alt="…">
-          <button class="kpt-galleria__nav kpt-galleria__nav--next">…</button>
+          <button class="kpt-galleria__nav kpt-galleria__nav--prev" aria-disabled="true" aria-label="Previous">…</button>
+          <img class="kpt-galleria__image" src="…" alt="Mountain lake">
+          <button class="kpt-galleria__nav kpt-galleria__nav--next" aria-label="Next">…</button>
         </div>
         <div class="kpt-galleria__thumbs">
-          <button class="kpt-galleria__thumb is-active"><img src="…"></button>…
+          <button class="kpt-galleria__thumb is-active" aria-current="true" aria-label="Mountain lake"><img src="…" alt=""></button>…
         </div>
+        <span class="kpt-galleria__live" aria-live="polite">Image 2 of 4: Pine forest</span>
       </div>
     </div>
 
@@ -36,11 +37,19 @@ data is still loading shows the stage and the disabled arrows instead of crashin
     <KptGalleria items={photos} activeIndex={index} onActiveIndexChange={setIndex} showThumbnails={false} />
 
 ## i18n
-The arrows use `common.previous` / `common.next`, the thumbnails `galleria.image` (`{index}`).
+The arrows use `common.previous` / `common.next`, the thumbnails without `alt` `galleria.image` (`{index}`), the announcement `galleria.position` (`{index}`, `{total}`).
+
+## 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
-Each thumbnail is a labelled button, and the arrows go dark at the ends; `alt` comes from the item,
-so a photo without a description does not get a made-up one.
+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/dist/icon/icon.d.ts

@@ -4,14 +4,20 @@ export interface KptIconProps extends ComponentPropsWithRef<'span'> {
     name: string;
     /** Rozmiar jako długość CSS (np. '1.25rem'); domyślnie dziedziczy z `font-size`. */
     size?: string;
+    /** Nazwa dla czytnika ekranu — tylko gdy ikona niesie znaczenie bez tekstu obok. */
+    label?: string;
 }
 /**
  * Ikona Koncept UI (inline SVG, zestaw Tabler Icons — MIT). Rozmiar dziedziczy z `font-size`
  * (1em) lub ustaw `size`; kolor z `currentColor`. Ikona musi być w rejestrze — wbudowany
  * zestaw działa od razu, pełny dodaje `registerKptTablerIcons()` z `@konce-pt/react/icons`.
  *
+ * Domyślnie ikona jest dekoracją (`aria-hidden`). Ikona niosąca znaczenie sama, bez tekstu obok,
+ * dostaje `label` — wtedy jest `role="img"` z tą nazwą. W buildzie deweloperskim nieznana nazwa
+ * daje jedno ostrzeżenie w konsoli zamiast cichej pustki.
+ *
  * @example
  * <KptIcon name="menu" />
  * <KptIcon name="check" size="1.25rem" />
  */
-export declare function KptIcon({ name, size, className, style, ...rest }: Readonly<KptIconProps>): import("react").JSX.Element;
+export declare function KptIcon({ name, size, label, className, style, ...rest }: Readonly<KptIconProps>): import("react").JSX.Element;

package/dist/icon/icon.js

@@ -1,23 +1,37 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { renderKptIconSvg } from '@konce-pt/icons';
-import { useSyncExternalStore } from 'react';
+import { useEffect, useSyncExternalStore } from 'react';
 import { cn } from "../internal/cn.js";
+import { isDevBuild } from "../internal/dev.js";
 import { getKptIcon, getKptIconsVersion, subscribeKptIcons } from "./icon-registry.js";
+/** Nazwy, o których już ostrzegliśmy — jedno ostrzeżenie na nazwę, nie na każdą instancję. */
+const warned = new Set();
 /**
  * Ikona Koncept UI (inline SVG, zestaw Tabler Icons — MIT). Rozmiar dziedziczy z `font-size`
  * (1em) lub ustaw `size`; kolor z `currentColor`. Ikona musi być w rejestrze — wbudowany
  * zestaw działa od razu, pełny dodaje `registerKptTablerIcons()` z `@konce-pt/react/icons`.
  *
+ * Domyślnie ikona jest dekoracją (`aria-hidden`). Ikona niosąca znaczenie sama, bez tekstu obok,
+ * dostaje `label` — wtedy jest `role="img"` z tą nazwą. W buildzie deweloperskim nieznana nazwa
+ * daje jedno ostrzeżenie w konsoli zamiast cichej pustki.
+ *
  * @example
  * <KptIcon name="menu" />
  * <KptIcon name="check" size="1.25rem" />
  */
-export function KptIcon({ name, size = '', className, style, ...rest }) {
+export function KptIcon({ name, size = '', label = '', className, style, ...rest }) {
     // Rejestr bywa uzupełniany po pierwszym renderze (leniwy import zestawu Tabler),
     // więc komponent słucha jego wersji zamiast czytać go raz.
     useSyncExternalStore(subscribeKptIcons, getKptIconsVersion, getKptIconsVersion);
     // Treść pochodzi z zaufanego rejestru i przeszła sanitizację przy rejestracji —
     // to ten sam kontrakt, co `innerHTML` w porcie Angulara.
-    const html = renderKptIconSvg(getKptIcon(name));
-    return (_jsx("span", { className: cn('kpt-icon-host', className), "aria-hidden": "true", style: size ? { fontSize: size, ...style } : style, dangerouslySetInnerHTML: { __html: html }, ...rest }));
+    const svg = getKptIcon(name);
+    const html = renderKptIconSvg(svg);
+    useEffect(() => {
+        if (svg || !isDevBuild() || warned.has(name))
+            return;
+        warned.add(name);
+        console.warn(`KptIcon: ikony „${name}” nie ma (jeszcze) w rejestrze — sprawdź nazwę albo zarejestruj ją (registerKptIcons / registerKptTablerIcons).`);
+    }, [svg, name]);
+    return (_jsx("span", { className: cn('kpt-icon-host', className), "aria-hidden": label ? undefined : true, role: label ? 'img' : undefined, "aria-label": label || undefined, style: size ? { fontSize: size, ...style } : style, dangerouslySetInnerHTML: { __html: html }, ...rest }));
 }

package/dist/icon/llms.txt

@@ -12,6 +12,7 @@ Import: `import { KptIcon } from '@konce-pt/react';`
 ## Props
 - `name`: string — the icon name from the registry (required)
 - `size`: string — a CSS length (e.g. '1.25rem'); by default inherited from `font-size`
+- `label`: string — a name for screen readers; with it the icon is `role="img"`, without it `aria-hidden`
 - `className`, `ref` and every other `<span>` prop go to the host
 
 ## The registry
@@ -62,5 +63,7 @@ CMS, an API or an upload.
     <KptButton><KptIcon name="phone" /> Call</KptButton>
 
 ## Accessibility
-The host carries `aria-hidden="true"` — an icon is decoration. Put the accessible name on the
-control around it (`aria-label` on the button), not on the icon.
+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/dist/image/image.d.ts

@@ -11,6 +11,11 @@ export interface KptImageProps extends Omit<ComponentPropsWithRef<'div'>, 'onCli
 /**
  * Obraz z opcjonalnym podglądem pełnoekranowym.
  *
+ * Z `preview` miniatura jest przyciskiem (osiągalnym z klawiatury), a podgląd otwiera się na
+ * natywnym `<dialog>` przez `showModal()`: przeglądarka daje pułapkę fokusu, `Escape`, bezwładną
+ * stronę i górną warstwę. Na czas podglądu blokujemy przewijanie dokumentu, a po zamknięciu
+ * fokus wraca na miniaturę.
+ *
  * @example
  * <KptImage src="/foto.jpg" alt="Zdjęcie" preview width="240px" />
  */

package/dist/image/image.js

@@ -1,16 +1,52 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
 /**
  * Obraz z opcjonalnym podglądem pełnoekranowym.
  *
+ * Z `preview` miniatura jest przyciskiem (osiągalnym z klawiatury), a podgląd otwiera się na
+ * natywnym `<dialog>` przez `showModal()`: przeglądarka daje pułapkę fokusu, `Escape`, bezwładną
+ * stronę i górną warstwę. Na czas podglądu blokujemy przewijanie dokumentu, a po zamknięciu
+ * fokus wraca na miniaturę.
+ *
  * @example
  * <KptImage src="/foto.jpg" alt="Zdjęcie" preview width="240px" />
  */
 export function KptImage({ src, alt = '', width = null, preview = false, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const [open, setOpen] = useState(false);
-    return (_jsxs("div", { className: cn('kpt-image-host', className), ...rest, children: [_jsxs("div", { className: cn('kpt-image', preview && 'kpt-image--preview'), style: width ? { width } : undefined, onClick: () => preview && setOpen(true), children: [_jsx("img", { className: "kpt-image__img", src: src, alt: alt }), preview ? (_jsx("div", { className: "kpt-image__mask", "aria-hidden": "true", children: _jsx(KptIcon, { name: "zoom-in" }) })) : null] }), open ? (_jsxs("div", { className: "kpt-image__overlay", onClick: () => setOpen(false), children: [_jsx("button", { type: "button", className: "kpt-image__close", onClick: () => setOpen(false), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) }), _jsx("img", { className: "kpt-image__full", src: src, alt: alt, onClick: (event) => event.stopPropagation() })] })) : null] }));
+    const dialogRef = useRef(null);
+    const triggerRef = useRef(null);
+    useEffect(() => {
+        const el = dialogRef.current;
+        if (!el || !open)
+            return;
+        if (!el.open)
+            el.showModal();
+        const root = document.documentElement;
+        const saved = root.style.overflow;
+        root.style.overflow = 'hidden';
+        return () => {
+            root.style.overflow = saved;
+            if (el.open)
+                el.close();
+        };
+    }, [open]);
+    const style = width ? { width } : undefined;
+    if (!preview) {
+        return (_jsx("div", { className: cn('kpt-image-host', className), ...rest, children: _jsx("div", { className: "kpt-image", style: style, children: _jsx("img", { className: "kpt-image__img", src: src, alt: alt }) }) }));
+    }
+    // `close` przychodzi z każdej drogi: `×`, `Escape`, tło.
+    const onClosed = () => {
+        setOpen(false);
+        triggerRef.current?.focus();
+    };
+    // Okno wypełnia cały ekran, więc kliknięcie w nie samo (a nie w zdjęcie) to kliknięcie w tło.
+    const onDialogClick = (event) => {
+        if (event.target === event.currentTarget)
+            event.currentTarget.close();
+    };
+    return (_jsxs("div", { className: cn('kpt-image-host', className), ...rest, children: [_jsxs("button", { ref: triggerRef, type: "button", className: "kpt-image kpt-image--preview", "aria-haspopup": "dialog", "aria-label": alt ? t('image.previewOf', { alt }) : t('image.preview'), style: style, onClick: () => setOpen(true), children: [_jsx("img", { className: "kpt-image__img", src: src, alt: "" }), _jsx("span", { className: "kpt-image__mask", "aria-hidden": "true", children: _jsx(KptIcon, { name: "zoom-in" }) })] }), _jsxs("dialog", { ref: dialogRef, className: "kpt-image__overlay", "aria-label": alt || t('image.preview'), onClose: onClosed, onClick: onDialogClick, children: [_jsx("button", { type: "button", className: "kpt-image__close", onClick: () => dialogRef.current?.close(), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) }), _jsx("img", { className: "kpt-image__full", src: src, alt: alt, loading: "lazy" })] })] }));
 }

package/dist/image/llms.txt

@@ -5,27 +5,29 @@ Import: `import { KptImage } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-image-host">
-      <div class="kpt-image kpt-image--preview" style="width:240px">
-        <img class="kpt-image__img" src="…" alt="…">
-        <div class="kpt-image__mask" aria-hidden="true">…zoom-in…</div>
-      </div>
-      <!-- open: -->
-      <div class="kpt-image__overlay">
-        <button class="kpt-image__close">…</button>
-        <img class="kpt-image__full" src="…" alt="…">
-      </div>
+      <!-- with preview: -->
+      <button class="kpt-image kpt-image--preview" type="button" aria-haspopup="dialog"
+              aria-label="Show full size: Photo" style="width:240px">
+        <img class="kpt-image__img" src="…" alt="">
+        <span class="kpt-image__mask" aria-hidden="true">…zoom-in…</span>
+      </button>
+      <dialog class="kpt-image__overlay" aria-label="Photo">
+        <button class="kpt-image__close" type="button" aria-label="Close">…</button>
+        <img class="kpt-image__full" src="…" alt="Photo" loading="lazy">
+      </dialog>
+      <!-- without preview: <div class="kpt-image"><img class="kpt-image__img" …></div> -->
     </div>
 
 ## Props
 - `src`: string (required); `alt`: string
 - `width`: string | null — a CSS length, e.g. `'240px'`
-- `preview`: boolean — a click opens the overlay
+- `preview`: boolean — the thumbnail becomes a button opening a modal preview
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## The overlay closes around the photo, not on it
-The click on `.kpt-image__full` stops propagating, so only the dark area around the image closes
-the preview — clicking the photo itself (to look closer, to drag it) must not dismiss it. The × is
-there for the explicit way out.
+The dialog fills the viewport, so a click on the dialog element itself — not on the photo or the
+× — is a click on the backdrop and closes the preview. Clicking the photo (to look closer, to drag
+it) does not dismiss it; Escape and × are the explicit ways out.
 
 ## The mask is decorative
 The zoom-in overlay is `aria-hidden`: it repeats what the cursor (`zoom-in`) already says and would
@@ -36,11 +38,16 @@ only add noise for a screen reader.
     <KptImage src="/logo.svg" alt="Logo" />
 
 ## i18n
-The close button label comes from `common.close`.
+The thumbnail is named from `image.previewOf` (`{alt}`) or `image.preview`; the close button from `common.close`.
 
 ## Tokens
-The radius `--kpt-radius-md`, the mask and the overlay are black at 40% / 80% via `color-mix`.
+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
-`alt` goes to both the thumbnail and the full-size image; the close button is labelled from the
-dictionary.
+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/dist/input/input.d.ts

@@ -38,4 +38,4 @@ export interface KptInputProps extends Omit<ComponentPropsWithRef<'input'>, 'typ
  * <KptInput name="email" type="email" defaultValue="" />
  * <KptInput value={email} onValueChange={setEmail} invalid={!ok} touched={blurred} />
  */
-export declare function KptInput({ type, required, invalid, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, 'aria-invalid': ariaInvalid, ...rest }: Readonly<KptInputProps>): import("react").JSX.Element;
+export declare function KptInput({ type, required, invalid, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }: Readonly<KptInputProps>): import("react").JSX.Element;

package/dist/input/input.js

@@ -1,8 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback } from 'react';
 import { cn } from "../internal/cn.js";
-import { useKptId } from "../internal/use-id.js";
-import { useKptFormFieldContext } from "../form-field/form-field-context.js";
+import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
 /**
  * Pole tekstowe Koncept UI. Renderuje natywny `<input>` w hoście `.kpt-input-host`.
  *
@@ -17,10 +16,9 @@ import { useKptFormFieldContext } from "../form-field/form-field-context.js";
  * <KptInput name="email" type="email" defaultValue="" />
  * <KptInput value={email} onValueChange={setEmail} invalid={!ok} touched={blurred} />
  */
-export function KptInput({ type = 'text', required = false, invalid = false, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, 'aria-invalid': ariaInvalid, ...rest }) {
-    const field = useKptFormFieldContext();
+export function KptInput({ type = 'text', required = false, invalid = false, touched, onValueChange, onTouch, hostProps, className, id, onChange, onBlur, 'aria-invalid': ariaInvalid, 'aria-describedby': ariaDescribedBy, ...rest }) {
     const { className: hostClassName, ...hostRest } = hostProps ?? {};
-    const inputId = useKptId(id ?? field?.controlId, 'kpt-input');
+    const field = useKptFieldA11y(id, 'kpt-input');
     // Stan nieprawidłowy pokazujemy dopiero po dotknięciu pola — jak natywne `:user-invalid`.
     // Bez `touched` nie ma czego bramkować, więc decyduje samo `invalid`.
     const showInvalid = invalid && (touched ?? true);
@@ -32,5 +30,5 @@ export function KptInput({ type = 'text', required = false, invalid = false, tou
         onBlur?.(event);
         onTouch?.();
     }, [onBlur, onTouch]);
-    return (_jsx("span", { className: cn('kpt-input-host', hostClassName), ...hostRest, children: _jsx("input", { className: cn('kpt-input__field', className), id: inputId, type: type, "aria-required": required || undefined, "aria-invalid": ariaInvalid ?? (showInvalid || undefined), onChange: handleChange, onBlur: handleBlur, ...rest }) }));
+    return (_jsx("span", { className: cn('kpt-input-host', hostClassName), ...hostRest, children: _jsx("input", { className: cn('kpt-input__field', className), id: field.id, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), type: type, "aria-required": required || undefined, "aria-invalid": ariaInvalid ?? (showInvalid || undefined), onChange: handleChange, onBlur: handleBlur, ...rest }) }));
 }

package/dist/input/llms.txt

@@ -46,6 +46,11 @@ configuration. An explicit `id` prop still wins.
       <KptInput type="email" invalid={!!err} onTouch={markTouched} />
     </KptFormField>
 
+## 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-hover,border-focus,border-error,radius}`.
 

package/dist/input-mask/input-mask.d.ts

@@ -16,4 +16,4 @@ export interface KptInputMaskProps extends Omit<ComponentPropsWithRef<'input'>,
  * @example
  * <KptInputMask mask="(999) 999-99-99" value={phone} onValueChange={setPhone} />
  */
-export declare function KptInputMask({ value, defaultValue, onValueChange, mask, placeholder, invalid, touched, onTouch, disabled, className, id, onBlur, ...rest }: Readonly<KptInputMaskProps>): import("react").JSX.Element;
+export declare function KptInputMask({ value, defaultValue, onValueChange, mask, placeholder, invalid, touched, onTouch, disabled, className, id, onBlur, 'aria-describedby': ariaDescribedBy, inputMode, ...rest }: Readonly<KptInputMaskProps>): import("react").JSX.Element;

package/dist/input-mask/input-mask.js

@@ -1,8 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
-import { useKptId } from "../internal/use-id.js";
-import { useKptFormFieldContext } from "../form-field/form-field-context.js";
+import { joinIds, useKptFieldA11y } from "../form-field/form-field-context.js";
 /** Tokeny maski: `9` = cyfra, `a` = litera, `*` = znak alfanumeryczny. */
 const TOKENS = {
     '9': /\d/,
@@ -16,9 +15,12 @@ const TOKENS = {
  * @example
  * <KptInputMask mask="(999) 999-99-99" value={phone} onValueChange={setPhone} />
  */
-export function KptInputMask({ value, defaultValue = '', onValueChange, mask = '', placeholder, invalid = false, touched, onTouch, disabled = false, className, id, onBlur, ...rest }) {
-    const field = useKptFormFieldContext();
-    const inputId = useKptId(id ?? field?.controlId, 'kpt-input-mask');
+export function KptInputMask({ value, defaultValue = '', onValueChange, mask = '', placeholder, invalid = false, touched, onTouch, disabled = false, className, id, onBlur, 'aria-describedby': ariaDescribedBy, inputMode, ...rest }) {
+    const field = useKptFieldA11y(id, 'kpt-input-mask');
+    // Klawiatura ekranowa z maski: same tokeny `9` (telefon, kod pocztowy) → numeryczna.
+    const tokens = [...mask].filter((char) => char in TOKENS);
+    const autoInputMode = tokens.length && tokens.every((char) => char === '9') ? 'numeric' : 'text';
+    const inputId = field.id;
     const [current, setCurrent] = useControllableState({ value, defaultValue, onChange: onValueChange });
     const showInvalid = invalid && (touched ?? true);
     /*
@@ -58,7 +60,7 @@ export function KptInputMask({ value, defaultValue = '', onValueChange, mask = '
         // wpisany znak zostałby na ekranie, więc DOM zrównujemy ręcznie.
         event.target.value = formatted;
     };
-    return (_jsx("span", { className: "kpt-input-mask-host", children: _jsx("input", { className: cn('kpt-input-mask__input', showInvalid && 'kpt-input-mask--invalid', className), id: inputId, type: "text", value: current, disabled: disabled, placeholder: placeholder || mask, onChange: onInput, onBlur: (event) => {
+    return (_jsx("span", { className: "kpt-input-mask-host", children: _jsx("input", { className: cn('kpt-input-mask__input', showInvalid && 'kpt-input-mask--invalid', className), id: inputId, "aria-invalid": showInvalid || undefined, "aria-describedby": joinIds(ariaDescribedBy, field.describedBy), inputMode: inputMode ?? autoInputMode, type: "text", value: current, disabled: disabled, placeholder: placeholder || mask, onChange: onInput, onBlur: (event) => {
                 onBlur?.(event);
                 onTouch?.();
             }, ...rest }) }));

package/dist/input-mask/llms.txt

@@ -29,6 +29,17 @@ change, so React would not re-render and the character would linger on screen.
     <KptInputMask mask="(999) 999-99-99" value={phone} onValueChange={setPhone} />
     <KptInputMask mask="aa-9999" value={code} onValueChange={setCode} />
 
+## Screen reader and keyboard
+The on-screen keyboard follows the mask: only `9` tokens (phone, postal code) give
+`inputMode="numeric"`, otherwise `text`; pass `inputMode` to override it, and `autoComplete` (`tel`,
+`postal-code`…) so the browser can fill the field in.
+
+## 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`.
+New: `aria-invalid` after touch.
+
 ## Tokens
 `--kpt-form-field-{bg,text,placeholder,border,border-focus,border-error,radius}`.