@konce-pt/react 0.9.1 → 0.10.0

package/dist/menu/menu.js

@@ -3,6 +3,8 @@ import { useCallback, useEffect, useRef } from 'react';
 import { cn } from "../internal/cn.js";
 import { KptOverlay } from "../internal/overlay.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
+import { useKptId } from "../internal/use-id.js";
+import { focusMenuEdge, handleMenuKeydown } from "./menu-keys.js";
 import { MenuRows } from "./menu-rows.js";
 /**
  * Menu rozwijane (dropdown). Pozycje przez `items`, wyzwalacz przez prop `trigger`.
@@ -15,6 +17,10 @@ import { MenuRows } from "./menu-rows.js";
  */
 export function KptMenu({ items = [], trigger, onSelect, open, defaultOpen = false, onOpenChange, className, ...rest }) {
     const triggerRef = useRef(null);
+    const panelRef = useRef(null);
+    /** Którą pozycję skupić po otwarciu — strzałka w górę na wyzwalaczu otwiera „od końca”. */
+    const focusEdge = useRef('first');
+    const panelId = useKptId(undefined, 'kpt-menu');
     const [isOpen, setOpen] = useControllableState({
         value: open,
         defaultValue: defaultOpen,
@@ -26,17 +32,59 @@ export function KptMenu({ items = [], trigger, onSelect, open, defaultOpen = fal
     // zagnieżdżoną kontrolkę i drugi tab stop. `cloneElement` też odpada — `trigger` bywa
     // komponentem, który nie przekazuje nieznanych propsów dalej na DOM.
     useEffect(() => {
-        const control = triggerRef.current?.querySelector('button, a, [role="button"]');
+        const control = findControl();
         if (!control)
             return;
         control.setAttribute('aria-haspopup', 'menu');
         control.setAttribute('aria-expanded', String(isOpen));
-    }, [isOpen, trigger]);
+        if (isOpen)
+            control.setAttribute('aria-controls', panelId);
+        else
+            control.removeAttribute('aria-controls');
+    }, [isOpen, trigger, panelId]);
+    // Po otwarciu fokus na pierwszą (albo ostatnią) pozycję. Klatkę później: `KptOverlay` trzyma
+    // panel w `visibility: hidden`, dopóki go nie zmierzy, a niewidocznego elementu nie da się skupić.
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const frame = requestAnimationFrame(() => {
+            if (panelRef.current)
+                focusMenuEdge(panelRef.current, focusEdge.current);
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [isOpen]);
+    /** Prawdziwa kontrolka w slocie — tam idą ARIA i powrót fokusu. */
+    function findControl() {
+        return triggerRef.current?.querySelector('button, a, [role="button"]') ?? null;
+    }
+    /** Fokus wraca na kontrolkę — inaczej po zniknięciu panelu spadłby na `<body>`. */
+    const closeAndRestoreFocus = () => {
+        close();
+        findControl()?.focus();
+    };
+    const onTriggerKeyDown = (event) => {
+        if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp')
+            return;
+        event.preventDefault();
+        focusEdge.current = event.key === 'ArrowUp' ? 'last' : 'first';
+        if (isOpen && panelRef.current)
+            focusMenuEdge(panelRef.current, focusEdge.current);
+        else
+            setOpen(true);
+    };
+    const onPanelKeyDown = (event) => {
+        if (panelRef.current && handleMenuKeydown(panelRef.current, event.nativeEvent) === 'close') {
+            closeAndRestoreFocus();
+        }
+    };
     const pick = (item) => {
         if (item.disabled)
             return;
         onSelect?.(item);
-        close();
+        closeAndRestoreFocus();
     };
-    return (_jsxs("span", { className: cn('kpt-menu-host', className), ...rest, children: [_jsx("span", { className: "kpt-menu__trigger", ref: triggerRef, onClick: () => setOpen(!isOpen), children: trigger }), _jsx(KptOverlay, { open: isOpen, anchor: triggerRef.current, onClose: close, children: _jsx("div", { className: "kpt-menu__panel", role: "menu", children: _jsx(MenuRows, { items: items, block: "kpt-menu", onPick: pick }) }) })] }));
+    return (_jsxs("span", { className: cn('kpt-menu-host', className), ...rest, children: [_jsx("span", { className: "kpt-menu__trigger", ref: triggerRef, onClick: () => {
+                    focusEdge.current = 'first';
+                    setOpen(!isOpen);
+                }, onKeyDown: onTriggerKeyDown, children: trigger }), _jsx(KptOverlay, { open: isOpen, anchor: triggerRef.current, onClose: close, children: _jsx("div", { ref: panelRef, id: panelId, className: "kpt-menu__panel", role: "menu", onKeyDown: onPanelKeyDown, children: _jsx(MenuRows, { items: items, block: "kpt-menu", onPick: pick }) }) })] }));
 }

package/dist/menubar/llms.txt

@@ -5,18 +5,20 @@ Import: `import { KptMenubar } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-menubar-host">
-      <nav class="kpt-menubar" role="menubar">
-        <div class="kpt-menubar__group">
-          <button class="kpt-menubar__top is-open" role="menuitem">File …caret…</button>
+      <div class="kpt-menubar" role="menubar" aria-orientation="horizontal" aria-label="Editor menu">
+        <div class="kpt-menubar__group" role="none">
+          <button class="kpt-menubar__top is-open" role="menuitem" tabindex="0"
+                  aria-haspopup="menu" aria-expanded="true" aria-controls="kpt-menubar-r1-menu-0">File …caret…</button>
         </div>
-      </nav>
+      </div>
     </div>
     <!-- while open, in a portal: -->
-    <div class="kpt-menubar__dropdown" role="menu">…items and separators…</div>
+    <div class="kpt-menubar__dropdown" role="menu" id="kpt-menubar-r1-menu-0" aria-label="File">…items and separators…</div>
 
 ## Props
 - `items`: `KptMenuItem<T>[]` — a top item's `items` become its dropdown
 - `onSelect(item)` — an action item, or a pick from a dropdown
+- `ariaLabel`: string — the bar's name for screen readers, e.g. "Editor menu"
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## The dropdown is a portal
@@ -36,10 +38,25 @@ bar can mix menus and plain actions with no extra flag.
       { 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. `onSelect`
+still fires before the browser follows the link.
+
 ## Tokens
 `--kpt-color-surface`, `--kpt-color-muted` (the open top item), `--kpt-color-surface-raised` and
 `--kpt-elevation-3` for the dropdown, `--kpt-color-danger`.
 
 ## Accessibility
-The bar is `role="menubar"`, top items and dropdown rows are `role="menuitem"`, separators carry
-`role="separator"`.
+The bar is `role="menubar"` (`aria-orientation="horizontal"`, named by `ariaLabel`), top items and
+dropdown rows are `role="menuitem"`, separators carry `role="separator"`. Top items with a dropdown
+carry `aria-haspopup="menu"`, `aria-expanded` and, while open, `aria-controls`. The bar is a plain
+`<div>`, not `<nav>` — wrap it in your own `<nav aria-label="…">` when it is the site navigation.
+
+## Keyboard
+The bar is a single `Tab` stop (roving `tabindex`), following the WAI-ARIA menubar pattern.
+- 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 dropdown with focus on
+  its first row, `ArrowUp` on its last one.
+- In a dropdown: `ArrowDown`/`ArrowUp`/`Home`/`End` move between rows, `ArrowLeft`/`ArrowRight`
+  open the neighbouring dropdown, `Escape` and `Tab` close it and return focus to the top item.

package/dist/menubar/menubar.d.ts

@@ -3,6 +3,8 @@ import type { KptMenuItem } from '../menu/menu-item.ts';
 export interface KptMenubarProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onSelect'> {
     items?: readonly KptMenuItem<T>[];
     onSelect?: (item: KptMenuItem<T>) => void;
+    /** Nazwa belki dla czytników ekranu, np. „Menu edytora”. */
+    ariaLabel?: string;
 }
 /**
  * Pozioma belka menu z rozwijanymi pod-menu. Pozycja bez `items` działa jak akcja lub link.
@@ -10,7 +12,12 @@ export interface KptMenubarProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
  * Pod-menu renderuje się w portalu, więc rodzic z `overflow: hidden` go nie przycina — to ta sama
  * korzyść, dla której port Angulara sięga po CDK Overlay, tylko bez CDK.
  *
+ * Klawiatura według wzorca WAI-ARIA „menubar”: belka to jeden przystanek Tab, strzałki w lewo/prawo
+ * i `Home`/`End` chodzą po pozycjach górnych, strzałka w dół (albo `Enter`/spacja) otwiera
+ * pod-menu z fokusem na pierwszej pozycji, w górę — na ostatniej. W otwartym pod-menu strzałki
+ * w lewo/prawo przechodzą do sąsiedniego, a `Escape` zamyka je i oddaje fokus belce.
+ *
  * @example
  * <KptMenubar items={items} onSelect={onSelect} />
  */
-export declare function KptMenubar<T>({ items, onSelect, className, ...rest }: Readonly<KptMenubarProps<T>>): import("react").JSX.Element;
+export declare function KptMenubar<T>({ items, onSelect, ariaLabel, className, ...rest }: Readonly<KptMenubarProps<T>>): import("react").JSX.Element;

package/dist/menubar/menubar.js

@@ -1,25 +1,72 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { KptOverlay } from "../internal/overlay.js";
+import { nextRovingIndex, rovingStop } from "../internal/roving.js";
+import { useKptId } from "../internal/use-id.js";
 import { KptIcon } from "../icon/icon.js";
+import { focusMenuEdge, handleMenuKeydown } from "../menu/menu-keys.js";
 /**
  * Pozioma belka menu z rozwijanymi pod-menu. Pozycja bez `items` działa jak akcja lub link.
  *
  * Pod-menu renderuje się w portalu, więc rodzic z `overflow: hidden` go nie przycina — to ta sama
  * korzyść, dla której port Angulara sięga po CDK Overlay, tylko bez CDK.
  *
+ * Klawiatura według wzorca WAI-ARIA „menubar”: belka to jeden przystanek Tab, strzałki w lewo/prawo
+ * i `Home`/`End` chodzą po pozycjach górnych, strzałka w dół (albo `Enter`/spacja) otwiera
+ * pod-menu z fokusem na pierwszej pozycji, w górę — na ostatniej. W otwartym pod-menu strzałki
+ * w lewo/prawo przechodzą do sąsiedniego, a `Escape` zamyka je i oddaje fokus belce.
+ *
  * @example
  * <KptMenubar items={items} onSelect={onSelect} />
  */
-export function KptMenubar({ items = [], onSelect, className, ...rest }) {
+export function KptMenubar({ items = [], onSelect, ariaLabel, className, ...rest }) {
     const [openIndex, setOpenIndex] = useState(null);
+    // Ostatnio skupiona pozycja górna — ona jest przystankiem Tab belki.
+    const [focusIndex, setFocusIndex] = useState(0);
     const buttonsRef = useRef([]);
+    const panelRef = useRef(null);
+    // Którą pozycję pod-menu skupić po otwarciu — strzałka w górę otwiera „od końca”.
+    const focusEdge = useRef('first');
+    const baseId = useKptId(undefined, 'kpt-menubar');
+    const panelId = (index) => `${baseId}-menu-${index}`;
+    const disabled = items.map((item) => !!item.disabled);
+    // Pozycja z `url` (bez pod-menu, niewyłączona) to `<a href>` — nawigację robi przeglądarka,
+    // więc działa nowa karta i podgląd adresu. `onSelect` i tak jest wołane.
+    const isLink = (item) => !!item.url && !item.items?.length && !item.disabled;
+    const tabStop = rovingStop(disabled, focusIndex);
+    // Po otwarciu fokus na pierwszą (albo ostatnią) pozycję. Klatkę później: `KptOverlay` trzyma
+    // panel w `visibility: hidden`, dopóki go nie zmierzy, a niewidocznego elementu nie da się skupić.
+    useEffect(() => {
+        if (openIndex === null)
+            return;
+        const frame = requestAnimationFrame(() => {
+            if (panelRef.current)
+                focusMenuEdge(panelRef.current, focusEdge.current);
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [openIndex]);
     const closeAll = () => setOpenIndex(null);
+    const focusTop = (index) => {
+        setFocusIndex(index);
+        buttonsRef.current[index]?.focus();
+    };
+    /** Skupia pozycję górną i otwiera jej pod-menu, jeśli je ma (inaczej zamyka otwarte). */
+    const openAt = (index, edge) => {
+        focusEdge.current = edge;
+        const hasMenu = !!items[index]?.items?.length;
+        if (hasMenu && openIndex === index && panelRef.current) {
+            focusMenuEdge(panelRef.current, edge);
+            return;
+        }
+        setOpenIndex(hasMenu ? index : null);
+        focusTop(index);
+    };
     const toggle = (index, item) => {
         if (item.disabled)
             return;
         if (item.items?.length) {
+            focusEdge.current = 'first';
             setOpenIndex((current) => (current === index ? null : index));
         }
         else {
@@ -27,13 +74,52 @@ export function KptMenubar({ items = [], onSelect, className, ...rest }) {
             closeAll();
         }
     };
-    const pick = (item) => {
+    const pick = (item, index) => {
         if (item.disabled)
             return;
         onSelect?.(item);
         closeAll();
+        // Fokus wraca na pozycję górną — inaczej po zniknięciu pod-menu spadłby na `<body>`.
+        focusTop(index);
+    };
+    const onTopKeyDown = (event, index) => {
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            if (!items[index]?.items?.length)
+                return;
+            event.preventDefault();
+            openAt(index, event.key === 'ArrowUp' ? 'last' : 'first');
+            return;
+        }
+        const next = nextRovingIndex(disabled, index, event.key);
+        if (next === null)
+            return;
+        event.preventDefault();
+        // Przy otwartym pod-menu przejście w bok otwiera pod-menu sąsiada — jak w menu aplikacji.
+        if (openIndex === null)
+            focusTop(next);
+        else
+            openAt(next, 'first');
+    };
+    const onPanelKeyDown = (event, index) => {
+        if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+            const next = nextRovingIndex(disabled, index, event.key);
+            if (next === null)
+                return;
+            event.preventDefault();
+            openAt(next, 'first');
+            return;
+        }
+        if (handleMenuKeydown(event.currentTarget, event.nativeEvent) === 'close') {
+            closeAll();
+            focusTop(index);
+        }
     };
-    return (_jsx("div", { className: cn('kpt-menubar-host', className), ...rest, children: _jsx("nav", { className: "kpt-menubar", role: "menubar", children: items.map((item, index) => (_jsxs("div", { className: "kpt-menubar__group", children: [_jsxs("button", { ref: (el) => {
-                            buttonsRef.current[index] = el;
-                        }, type: "button", className: cn('kpt-menubar__top', openIndex === index && 'is-open'), role: "menuitem", disabled: item.disabled, onClick: () => toggle(index, item), children: [item.icon ? _jsx(KptIcon, { name: item.icon }) : null, _jsx("span", { children: item.label }), item.items?.length ? _jsx(KptIcon, { name: "chevron-down", className: "kpt-menubar__caret" }) : null] }), _jsx(KptOverlay, { open: openIndex === index && !!item.items?.length, anchor: buttonsRef.current[index] ?? null, onClose: closeAll, children: _jsx("div", { className: "kpt-menubar__dropdown", role: "menu", children: (item.items ?? []).map((sub, subIndex) => sub.separator ? (_jsx("div", { className: "kpt-menubar__separator", role: "separator" }, subIndex)) : (_jsxs("button", { type: "button", className: cn('kpt-menubar__item', sub.danger && 'kpt-menubar__item--danger'), role: "menuitem", disabled: sub.disabled, onClick: () => pick(sub), children: [sub.icon ? _jsx(KptIcon, { name: sub.icon }) : null, _jsx("span", { children: sub.label })] }, subIndex))) }) })] }, index))) }) }));
+    return (_jsx("div", { className: cn('kpt-menubar-host', className), ...rest, children: _jsx("div", { className: "kpt-menubar", role: "menubar", "aria-orientation": "horizontal", "aria-label": ariaLabel || undefined, children: items.map((item, index) => {
+                const hasMenu = !!item.items?.length;
+                return (_jsxs("div", { className: "kpt-menubar__group", role: "none", children: [isLink(item) ? (_jsxs("a", { ref: (el) => {
+                                buttonsRef.current[index] = el;
+                            }, className: "kpt-menubar__top", role: "menuitem", href: item.url, tabIndex: index === tabStop ? 0 : -1, onClick: () => pick(item, index), onFocus: () => setFocusIndex(index), onKeyDown: (event) => onTopKeyDown(event, index), children: [item.icon ? _jsx(KptIcon, { name: item.icon }) : null, _jsx("span", { children: item.label })] })) : (_jsxs("button", { ref: (el) => {
+                                buttonsRef.current[index] = el;
+                            }, type: "button", className: cn('kpt-menubar__top', openIndex === index && 'is-open'), role: "menuitem", disabled: item.disabled, tabIndex: index === tabStop ? 0 : -1, "aria-haspopup": hasMenu ? 'menu' : undefined, "aria-expanded": hasMenu ? openIndex === index : undefined, "aria-controls": openIndex === index ? panelId(index) : undefined, onClick: () => toggle(index, item), onFocus: () => setFocusIndex(index), onKeyDown: (event) => onTopKeyDown(event, index), children: [item.icon ? _jsx(KptIcon, { name: item.icon }) : null, _jsx("span", { children: item.label }), hasMenu ? _jsx(KptIcon, { name: "chevron-down", className: "kpt-menubar__caret" }) : null] })), _jsx(KptOverlay, { open: openIndex === index && hasMenu, anchor: buttonsRef.current[index] ?? null, onClose: closeAll, children: _jsx("div", { ref: panelRef, className: "kpt-menubar__dropdown", role: "menu", id: panelId(index), "aria-label": item.label, onKeyDown: (event) => onPanelKeyDown(event, index), children: (item.items ?? []).map((sub, subIndex) => sub.separator ? (_jsx("div", { className: "kpt-menubar__separator", role: "separator" }, subIndex)) : isLink(sub) ? (_jsxs("a", { className: cn('kpt-menubar__item', sub.danger && 'kpt-menubar__item--danger'), role: "menuitem", tabIndex: -1, href: sub.url, onClick: () => pick(sub, index), children: [sub.icon ? _jsx(KptIcon, { name: sub.icon }) : null, _jsx("span", { children: sub.label })] }, subIndex)) : (_jsxs("button", { type: "button", className: cn('kpt-menubar__item', sub.danger && 'kpt-menubar__item--danger'), role: "menuitem", tabIndex: -1, disabled: sub.disabled, onClick: () => pick(sub, index), children: [sub.icon ? _jsx(KptIcon, { name: sub.icon }) : null, _jsx("span", { children: sub.label })] }, subIndex))) }) })] }, index));
+            }) }) }));
 }

package/dist/meter-group/llms.txt

@@ -6,7 +6,8 @@ Import: `import { KptMeterGroup } from '@konce-pt/react';`
 ## DOM
     <div class="kpt-meter-group-host">
       <div class="kpt-meter-group">
-        <div class="kpt-meter-group__track" role="meter" aria-valuenow="100">
+        <div class="kpt-meter-group__track" role="meter" aria-label="Usage" aria-valuemin="0"
+             aria-valuenow="100" aria-valuemax="100" aria-valuetext="Documents 45, …">
           <span class="kpt-meter-group__segment" style="width:45%" title="Documents"></span>…
         </div>
         <ul class="kpt-meter-group__legend">
@@ -22,6 +23,9 @@ Import: `import { KptMeterGroup } from '@konce-pt/react';`
 - `values`: `KptMeterItem[]` — `{ label, value, color? }`
 - `max`: number — the reference total; without it the values' sum is 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')
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## Percentages come from the sum, not from 100
@@ -43,5 +47,8 @@ The palette `--kpt-color-{primary,info,success,warning,danger}`, the track
 `--kpt-color-surface-sunken`.
 
 ## Accessibility
-The track is `role="meter"` with `aria-valuenow`; every segment carries a native `title`, and the
-legend repeats the same values as text.
+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/dist/meter-group/meter-group.d.ts

@@ -1,15 +1,22 @@
 import type { ComponentPropsWithRef } from 'react';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 export interface KptMeterItem {
     label: string;
     value: number;
     /** Własny kolor segmentu; bez niego wchodzi kolejny z palety. */
     color?: string;
 }
-export interface KptMeterGroupProps extends ComponentPropsWithRef<'div'> {
+export interface KptMeterGroupProps extends ComponentPropsWithRef<'div'>, KptI18nOverrides {
     values?: readonly KptMeterItem[];
     /** Suma odniesienia; domyślnie suma wartości, czyli segmenty wypełniają całość. */
     max?: number;
     showLegend?: boolean;
+    /** Nazwa paska dla czytników ekranu, np. „Miejsce na dysku”; domyślnie `meterGroup.label`. */
+    label?: string;
+    /** Co pokazuje legenda przy etykiecie: udział procentowy albo samą wartość (z `unit`). */
+    legendValue?: 'percent' | 'value';
+    /** Jednostka dopisywana do wartości — w legendzie (`legendValue="value"`) i w `aria-valuetext`. */
+    unit?: string;
 }
 /**
  * Wielosegmentowy miernik z opcjonalną legendą.
@@ -17,4 +24,4 @@ export interface KptMeterGroupProps extends ComponentPropsWithRef<'div'> {
  * @example
  * <KptMeterGroup values={[{ label: 'Użyte', value: 70 }, { label: 'Wolne', value: 30 }]} />
  */
-export declare function KptMeterGroup({ values, max, showLegend, className, ...rest }: Readonly<KptMeterGroupProps>): import("react").JSX.Element;
+export declare function KptMeterGroup({ values, max, showLegend, label, legendValue, unit, locale, dictionary, className, ...rest }: Readonly<KptMeterGroupProps>): import("react").JSX.Element;

package/dist/meter-group/meter-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";
 const PALETTE = [
     'var(--kpt-color-primary)',
     'var(--kpt-color-info)',
@@ -13,12 +14,17 @@ const PALETTE = [
  * @example
  * <KptMeterGroup values={[{ label: 'Użyte', value: 70 }, { label: 'Wolne', value: 30 }]} />
  */
-export function KptMeterGroup({ values = [], max, showLegend = true, className, ...rest }) {
+export function KptMeterGroup({ values = [], max, showLegend = true, label = '', legendValue = 'percent', unit = '', locale, dictionary, className, ...rest }) {
+    const { t } = useKptMessages({ locale, dictionary });
     const sum = values.reduce((acc, item) => acc + item.value, 0);
     // Bez `max` odniesieniem jest suma wartości; `|| 1` chroni przed dzieleniem przez zero,
     // gdy wszystkie segmenty są zerowe.
     const total = max ?? (sum || 1);
     const percent = (item) => (item.value / total) * 100;
     const color = (item, index) => item.color || PALETTE[index % PALETTE.length];
-    return (_jsx("div", { className: cn('kpt-meter-group-host', className), ...rest, children: _jsxs("div", { className: "kpt-meter-group", children: [_jsx("div", { className: "kpt-meter-group__track", role: "meter", "aria-valuenow": sum, "aria-valuemax": max, children: values.map((item, index) => (_jsx("span", { className: "kpt-meter-group__segment", style: { width: `${percent(item)}%`, backgroundColor: color(item, index) }, title: item.label }, index))) }), showLegend ? (_jsx("ul", { className: "kpt-meter-group__legend", children: values.map((item, index) => (_jsxs("li", { className: "kpt-meter-group__legend-item", children: [_jsx("span", { className: "kpt-meter-group__dot", style: { backgroundColor: color(item, index) } }), _jsx("span", { children: item.label }), _jsxs("span", { className: "kpt-meter-group__val", children: [Math.round(percent(item)), "%"] })] }, index))) })) : null] }) }));
+    const withUnit = (value) => (unit ? `${value} ${unit}` : String(value));
+    const legendText = (item) => legendValue === 'value' ? withUnit(item.value) : `${Math.round(percent(item))}%`;
+    // Podział dla czytnika („Zdjęcia 42 GB, Filmy 28 GB…”) — sam `aria-valuenow` mówi tylko sumę.
+    const valueText = values.map((item) => `${item.label} ${withUnit(item.value)}`).join(', ');
+    return (_jsx("div", { className: cn('kpt-meter-group-host', className), ...rest, children: _jsxs("div", { className: "kpt-meter-group", children: [_jsx("div", { className: "kpt-meter-group__track", role: "meter", "aria-valuemin": 0, "aria-valuenow": sum, "aria-valuemax": total, "aria-valuetext": valueText, "aria-label": label || t('meterGroup.label'), children: values.map((item, index) => (_jsx("span", { className: "kpt-meter-group__segment", style: { width: `${percent(item)}%`, backgroundColor: color(item, index) }, title: item.label }, index))) }), showLegend ? (_jsx("ul", { className: "kpt-meter-group__legend", children: values.map((item, index) => (_jsxs("li", { className: "kpt-meter-group__legend-item", children: [_jsx("span", { className: "kpt-meter-group__dot", style: { backgroundColor: color(item, index) } }), _jsx("span", { children: item.label }), _jsx("span", { className: "kpt-meter-group__val", children: legendText(item) })] }, index))) })) : null] }) }));
 }

package/dist/order-list/llms.txt

@@ -46,7 +46,15 @@ no dictionary keys.
 ## Tokens
 The selection `--kpt-color-primary`, the 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
-Both buttons are labelled from the dictionary and go disabled while nothing is selected, so the
-control never looks broken. Native HTML5 drag and drop has no keyboard equivalent, so they stay the
-full keyboard path — `dragdrop` 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/dist/order-list/order-list.d.ts

@@ -14,7 +14,11 @@ export interface KptOrderListProps<T> extends Omit<ComponentPropsWithRef<'div'>,
  * OrderList — lista z ręcznym porządkowaniem. Klik zaznacza element, przyciski przesuwają go
  * w górę i w dół. Z `dragdrop` pozycje przestawia się także przeciąganiem.
  *
+ * Lista to `listbox` z jednym przystankiem Tab (roving tabindex), w którym zaznaczenie idzie
+ * za fokusem: strzałki / `Home` / `End` wybierają pozycję, `Alt`+↑/↓ przestawia ją o jedno
+ * miejsce (fokus jedzie razem z nią).
+ *
  * @example
  * <KptOrderList items={tasks} onItemsChange={setTasks} header="Kolejność" dragdrop renderItem={(t) => t.name} />
  */
-export declare function KptOrderList<T>({ items, defaultItems, onItemsChange, header, dragdrop, renderItem, locale, dictionary, className, ...rest }: Readonly<KptOrderListProps<T>>): import("react").JSX.Element;
+export declare function KptOrderList<T>({ items, defaultItems, onItemsChange, header, dragdrop, renderItem, locale, dictionary, className, ref, ...rest }: Readonly<KptOrderListProps<T>>): import("react").JSX.Element;

package/dist/order-list/order-list.js

@@ -1,18 +1,24 @@
 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 { composeRefs } from "../internal/compose-refs.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
+import { nextMenuIndex } from "../menu/menu-keys.js";
 const EMPTY = [];
 /**
  * OrderList — lista z ręcznym porządkowaniem. Klik zaznacza element, przyciski przesuwają go
  * w górę i w dół. Z `dragdrop` pozycje przestawia się także przeciąganiem.
  *
+ * Lista to `listbox` z jednym przystankiem Tab (roving tabindex), w którym zaznaczenie idzie
+ * za fokusem: strzałki / `Home` / `End` wybierają pozycję, `Alt`+↑/↓ przestawia ją o jedno
+ * miejsce (fokus jedzie razem z nią).
+ *
  * @example
  * <KptOrderList items={tasks} onItemsChange={setTasks} header="Kolejność" dragdrop renderItem={(t) => t.name} />
  */
-export function KptOrderList({ items, defaultItems = EMPTY, onItemsChange, header = '', dragdrop = false, renderItem, locale, dictionary, className, ...rest }) {
+export function KptOrderList({ items, defaultItems = EMPTY, onItemsChange, header = '', dragdrop = false, renderItem, locale, dictionary, className, ref, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const [list, setList] = useControllableState({
         value: items,
@@ -26,18 +32,50 @@ export function KptOrderList({ items, defaultItems = EMPTY, onItemsChange, heade
     const [overIndex, setOverIndex] = useState(null);
     /** Kursor nad pustym obszarem listy — upuszczenie tam dopina na koniec. */
     const [listOver, setListOver] = useState(false);
-    const move = (dir) => {
-        if (selected === null)
+    /** Pozycja, na którą po renderze trzeba przenieść fokus DOM (klawiatura). */
+    const [focusRequest, setFocusRequest] = useState(null);
+    const rootRef = useRef(null);
+    useEffect(() => {
+        if (focusRequest === null)
             return;
-        const target = selected + dir;
+        rootRef.current?.querySelectorAll('[role="option"]')[focusRequest]?.focus();
+        setFocusRequest(null);
+    }, [focusRequest]);
+    /**
+     * Przesuwa pozycję spod `index` o jedno miejsce i zwraca jej nowy indeks. Jawny indeks zamiast
+     * `selected`: klawiatura zaznacza i przesuwa w jednym zdarzeniu, a stan z domknięcia byłby stary.
+     */
+    const moveFrom = (index, dir) => {
+        const target = index + dir;
         if (target < 0 || target >= list.length)
-            return;
+            return index;
         const next = [...list];
-        [next[selected], next[target]] = [next[target], next[selected]];
+        [next[index], next[target]] = [next[target], next[index]];
         setList(next);
         // Zaznaczenie wędruje za elementem, nie zostaje na pozycji — inaczej kolejne kliknięcie
         // przesuwałoby sąsiada zamiast tego samego wpisu.
         setSelected(target);
+        return target;
+    };
+    const move = (dir) => {
+        if (selected !== null)
+            moveFrom(selected, dir);
+    };
+    /** Przystanek Tab: zaznaczona pozycja albo pierwsza. */
+    const tabStop = selected !== null && selected < list.length ? selected : 0;
+    // Strzałki wybierają pozycję (zaznaczenie idzie za fokusem), `Alt`+↑/↓ ją przestawia.
+    const onItemKeyDown = (index, event) => {
+        if (event.altKey && (event.key === 'ArrowUp' || event.key === 'ArrowDown')) {
+            event.preventDefault();
+            setFocusRequest(moveFrom(index, event.key === 'ArrowUp' ? -1 : 1));
+            return;
+        }
+        const next = nextMenuIndex(list.length, index, event.key);
+        if (next === null)
+            return;
+        event.preventDefault();
+        setSelected(next);
+        setFocusRequest(next);
     };
     const clearDrag = () => {
         setDragIndex(null);
@@ -98,5 +136,5 @@ export function KptOrderList({ items, defaultItems = EMPTY, onItemsChange, heade
         setList(next);
         setSelected(next.length - 1);
     };
-    return (_jsx("div", { className: cn('kpt-order-list-host', className), ...rest, children: _jsxs("div", { className: "kpt-order-list", children: [_jsxs("div", { className: "kpt-order-list__controls", children: [_jsx("button", { type: "button", disabled: selected === null, "aria-label": t('orderList.up'), onClick: () => move(-1), children: _jsx(KptIcon, { name: "arrow-up" }) }), _jsx("button", { type: "button", disabled: selected === null, "aria-label": t('orderList.down'), onClick: () => move(1), children: _jsx(KptIcon, { name: "arrow-down" }) })] }), _jsxs("div", { className: "kpt-order-list__panel", children: [header ? _jsx("div", { className: "kpt-order-list__header", children: header }) : null, _jsx("ul", { className: cn('kpt-order-list__items', listOver && 'is-dragover'), onDragOver: onListDragOver, onDragLeave: () => setListOver(false), onDrop: onListDrop, children: list.map((item, index) => (_jsx("li", { className: cn('kpt-order-list__item', selected === index && 'is-selected', dragIndex === index && 'is-dragging', dragdrop && 'kpt-order-list__item--draggable', overIndex === index && dragIndex !== index && 'kpt-order-list__item--dragover'), draggable: dragdrop || undefined, onClick: () => setSelected(index), onDragStart: (event) => onDragStart(index, event), onDragOver: (event) => onDragOver(index, event), onDragLeave: () => setOverIndex(null), onDrop: (event) => onDrop(index, event), onDragEnd: clearDrag, children: renderItem(item, index) }, index))) })] })] }) }));
+    return (_jsx("div", { ref: composeRefs(rootRef, ref), className: cn('kpt-order-list-host', className), ...rest, children: _jsxs("div", { className: "kpt-order-list", children: [_jsxs("div", { className: "kpt-order-list__controls", children: [_jsx("button", { type: "button", disabled: selected === null, "aria-label": t('orderList.up'), onClick: () => move(-1), children: _jsx(KptIcon, { name: "arrow-up" }) }), _jsx("button", { type: "button", disabled: selected === null, "aria-label": t('orderList.down'), onClick: () => move(1), children: _jsx(KptIcon, { name: "arrow-down" }) })] }), _jsxs("div", { className: "kpt-order-list__panel", children: [header ? _jsx("div", { className: "kpt-order-list__header", children: header }) : null, _jsx("ul", { className: cn('kpt-order-list__items', listOver && 'is-dragover'), role: "listbox", "aria-label": header || undefined, onDragOver: onListDragOver, onDragLeave: () => setListOver(false), onDrop: onListDrop, children: list.map((item, index) => (_jsx("li", { className: cn('kpt-order-list__item', selected === index && 'is-selected', dragIndex === index && 'is-dragging', dragdrop && 'kpt-order-list__item--draggable', overIndex === index && dragIndex !== index && 'kpt-order-list__item--dragover'), role: "option", "aria-selected": selected === index, tabIndex: index === tabStop ? 0 : -1, onFocus: () => setSelected(index), onKeyDown: (event) => onItemKeyDown(index, event), draggable: dragdrop || undefined, onClick: () => setSelected(index), onDragStart: (event) => onDragStart(index, event), onDragOver: (event) => onDragOver(index, event), onDragLeave: () => setOverIndex(null), onDrop: (event) => onDrop(index, event), onDragEnd: clearDrag, children: renderItem(item, index) }, index))) })] })] }) }));
 }

package/dist/panel/llms.txt

@@ -9,9 +9,10 @@ Import: `import { KptPanel } from '@konce-pt/react';`
         <div class="kpt-panel__header">
           <span class="kpt-panel__title">Settings</span>
           <span class="kpt-panel__actions">…actions…</span>
-          <button class="kpt-panel__toggle" aria-expanded="true" aria-label="Collapse / expand">…</button>
+          <button class="kpt-panel__toggle" aria-expanded="true" aria-controls="kpt-panel-body-r1"
+                  aria-label="Collapse / expand Settings">…</button>
         </div>
-        <div class="kpt-panel__collapse is-open">
+        <div class="kpt-panel__collapse is-open" id="kpt-panel-body-r1">
           <div class="kpt-panel__collapse-inner">
             <div class="kpt-panel__body">…children…</div>
           </div>
@@ -36,7 +37,7 @@ nothing inside can take focus or be read out. That is also why a collapsed panel
 whatever lives in it — a half-filled form inside survives a collapse.
 
 ## i18n
-The toggle's label comes from `panel.toggle` in the dictionary.
+The toggle's label comes from `panel.toggleNamed` (with `{header}`) or `panel.toggle` in the dictionary.
 
 ## Examples
     <KptPanel header="Settings" toggleable>Panel content…</KptPanel>
@@ -50,6 +51,8 @@ The toggle's label comes from `panel.toggle` in the dictionary.
 `--kpt-color-surface`, `--kpt-color-border`, `--kpt-radius-lg`, `--kpt-motion-easing-standard`.
 
 ## Accessibility
-The toggle is a native button with `aria-expanded` and a label from the dictionary. The header
-title is a `<span>`, not a heading — give the panel your own heading when it needs one in the
-document outline.
+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/dist/panel/panel.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, isValidElement } from 'react';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
+import { useKptId } from "../internal/use-id.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
 /**
@@ -15,6 +16,7 @@ import { KptIcon } from "../icon/icon.js";
  */
 export function KptPanel({ header = '', toggleable = false, collapsed, defaultCollapsed = false, onCollapsedChange, animated = true, animationDuration = 500, locale, dictionary, className, style, children, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
+    const bodyId = useKptId(undefined, 'kpt-panel-body');
     const [isCollapsed, setCollapsed] = useControllableState({
         value: collapsed,
         defaultValue: defaultCollapsed,
@@ -26,7 +28,7 @@ export function KptPanel({ header = '', toggleable = false, collapsed, defaultCo
         const isActions = isValidElement(child) && child.type?.kptPanelSlot === 'actions';
         (isActions ? actions : body).push(child);
     });
-    return (_jsx("div", { className: cn('kpt-panel-host', className), style: { ['--kpt-anim-duration']: `${animated ? animationDuration : 0}ms`, ...style }, ...rest, children: _jsxs("div", { className: "kpt-panel", children: [_jsxs("div", { className: "kpt-panel__header", children: [_jsx("span", { className: "kpt-panel__title", children: header }), _jsx("span", { className: "kpt-panel__actions", children: actions }), toggleable ? (_jsx("button", { type: "button", className: "kpt-panel__toggle", onClick: () => setCollapsed(!isCollapsed), "aria-expanded": !isCollapsed, "aria-label": t('panel.toggle'), children: _jsx(KptIcon, { name: isCollapsed ? 'chevron-down' : 'chevron-up' }) })) : null] }), _jsx("div", { className: cn('kpt-panel__collapse', !isCollapsed && 'is-open'), inert: isCollapsed, "aria-hidden": isCollapsed, children: _jsx("div", { className: "kpt-panel__collapse-inner", children: _jsx("div", { className: "kpt-panel__body", children: body }) }) })] }) }));
+    return (_jsx("div", { className: cn('kpt-panel-host', className), style: { ['--kpt-anim-duration']: `${animated ? animationDuration : 0}ms`, ...style }, ...rest, children: _jsxs("div", { className: "kpt-panel", children: [_jsxs("div", { className: "kpt-panel__header", children: [_jsx("span", { className: "kpt-panel__title", children: header }), _jsx("span", { className: "kpt-panel__actions", children: actions }), toggleable ? (_jsx("button", { type: "button", className: "kpt-panel__toggle", onClick: () => setCollapsed(!isCollapsed), "aria-expanded": !isCollapsed, "aria-controls": bodyId, "aria-label": header ? t('panel.toggleNamed', { header }) : t('panel.toggle'), children: _jsx(KptIcon, { name: isCollapsed ? 'chevron-down' : 'chevron-up' }) })) : null] }), _jsx("div", { className: cn('kpt-panel__collapse', !isCollapsed && 'is-open'), id: bodyId, inert: isCollapsed, "aria-hidden": isCollapsed, children: _jsx("div", { className: "kpt-panel__collapse-inner", children: _jsx("div", { className: "kpt-panel__body", children: body }) }) })] }) }));
 }
 /** Akcje w nagłówku panelu, obok tytułu. */
 export function KptPanelActions({ className, ...rest }) {

package/dist/password/llms.txt

@@ -36,6 +36,14 @@ the dictionary — indexed by the score, so a translation controls the wording w
     <KptPassword value={pass} onValueChange={setPass} feedback />
     <KptPassword value={pass} onValueChange={setPass} autoComplete="new-password" feedback />
 
+## 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 `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
 `--kpt-form-field-*` for the field, `--kpt-color-danger` / `-warning` / `-success` for the meter
 bars by score.

package/dist/password/password.d.ts

@@ -14,6 +14,11 @@ export interface KptPasswordProps extends Omit<ComponentPropsWithRef<'div'>, 'on
     autoComplete?: string | null;
     /** Miernik siły pod polem. */
     feedback?: boolean;
+    /** Nazwa dostępna, gdy pola nie opisuje etykieta (`<label for>` albo `KptFormField`). */
+    ariaLabel?: string | null;
+    /** Oznacza pole jako wymagane atrybutem `aria-required`. */
+    required?: boolean;
+    readOnly?: boolean;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -25,4 +30,4 @@ export interface KptPasswordProps extends Omit<ComponentPropsWithRef<'div'>, 'on
  * @example
  * <KptPassword value={password} onValueChange={setPassword} feedback autoComplete="new-password" />
  */
-export declare function KptPassword({ value, defaultValue, onValueChange, placeholder, id, autoComplete, feedback, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptPasswordProps>): import("react").JSX.Element;
+export declare function KptPassword({ value, defaultValue, onValueChange, placeholder, id, autoComplete, feedback, ariaLabel, required, readOnly, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptPasswordProps>): import("react").JSX.Element;