@konce-pt/react 0.9.1 → 0.11.0

package/dist/megamenu/megamenu.js

@@ -1,28 +1,139 @@
 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";
 /**
  * Mega-menu — pozioma belka z szerokim, wielokolumnowym panelem.
  * Struktura: pozycja górna → `items` (kolumny) → `items` kolumny (odnośniki).
+ * Pozycja górna bez kolumn działa jak akcja — wywołuje `onSelect` zamiast otwierać pusty panel.
  *
  * Panel kotwiczy się do CAŁEJ belki, nie do pojedynczego przycisku: jest szeroki, więc ma
  * zaczynać się przy krawędzi menu, a nie przy przypadkowej pozycji, w którą kliknięto.
  *
+ * Klawiatura jak w `KptMenubar`: 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 panel
+ * z fokusem na pierwszym odnośniku. W panelu strzałki w górę/dół przechodzą po wszystkich
+ * odnośnikach kolumna po kolumnie, w lewo/prawo — do panelu sąsiedniej pozycji, a `Escape`
+ * zamyka panel i oddaje fokus belce.
+ *
  * @example
  * <KptMegamenu items={items} onSelect={onSelect} />
  */
-export function KptMegamenu({ items = [], onSelect, className, ...rest }) {
-    const navRef = useRef(null);
+export function KptMegamenu({ items = [], onSelect, ariaLabel, className, ...rest }) {
+    const barRef = useRef(null);
+    const panelRef = useRef(null);
+    const buttonsRef = useRef([]);
     const [openIndex, setOpenIndex] = useState(null);
-    const closeAll = () => setOpenIndex(null);
+    // Ostatnio skupiona pozycja górna — ona jest przystankiem Tab belki.
+    const [focusIndex, setFocusIndex] = useState(0);
+    // Który odnośnik skupić po otwarciu — strzałka w górę otwiera „od końca”.
+    const focusEdge = useRef('first');
+    const panelId = useKptId(undefined, 'kpt-megamenu');
+    const disabled = items.map((item) => !!item.disabled);
+    // Pozycja z `url` (bez kolumn, 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);
     const columns = openIndex === null ? [] : (items[openIndex]?.items ?? []);
+    // Po otwarciu i po każdej zmianie pozycji fokus na skrajny odnośnik. Klatkę później:
+    // `KptOverlay` trzyma panel w `visibility: hidden`, dopóki go nie zmierzy.
+    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 pokazuje jej panel, jeśli ma kolumny (inaczej zamyka otwarty). */
+    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 {
+            onSelect?.(item);
+            closeAll();
+        }
+    };
     const pick = (link) => {
         if (link.disabled)
             return;
+        const top = openIndex;
         onSelect?.(link);
         closeAll();
+        if (top !== null)
+            focusTop(top);
+    };
+    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 panelu przejście w bok pokazuje panel sąsiada — jak w menu aplikacji.
+        if (openIndex === null)
+            focusTop(next);
+        else
+            openAt(next, 'first');
+    };
+    const onPanelKeyDown = (event) => {
+        if (openIndex === null)
+            return;
+        if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+            const next = nextRovingIndex(disabled, openIndex, event.key);
+            if (next === null)
+                return;
+            event.preventDefault();
+            openAt(next, 'first');
+            return;
+        }
+        if (handleMenuKeydown(event.currentTarget, event.nativeEvent) === 'close') {
+            const top = openIndex;
+            closeAll();
+            focusTop(top);
+        }
     };
-    return (_jsxs("div", { className: cn('kpt-megamenu-host', className), ...rest, children: [_jsx("nav", { className: "kpt-megamenu", role: "menubar", ref: navRef, children: items.map((item, index) => (_jsxs("button", { type: "button", className: cn('kpt-megamenu__top', openIndex === index && 'is-open'), role: "menuitem", onClick: () => setOpenIndex((current) => (current === index ? null : index)), children: [item.icon ? _jsx(KptIcon, { name: item.icon }) : null, _jsx("span", { children: item.label }), _jsx(KptIcon, { name: "chevron-down", className: "kpt-megamenu__caret" })] }, index))) }), _jsx(KptOverlay, { open: openIndex !== null, anchor: navRef.current, onClose: closeAll, children: _jsx("div", { className: "kpt-megamenu__panel", role: "menu", children: columns.map((column, columnIndex) => (_jsxs("div", { className: "kpt-megamenu__column", children: [column.label ? _jsx("div", { className: "kpt-megamenu__col-title", children: column.label }) : null, (column.items ?? []).map((link, linkIndex) => (_jsxs("button", { type: "button", className: "kpt-megamenu__link", disabled: link.disabled, onClick: () => pick(link), children: [link.icon ? _jsx(KptIcon, { name: link.icon }) : null, _jsx("span", { children: link.label })] }, linkIndex)))] }, columnIndex))) }) })] }));
+    return (_jsxs("div", { className: cn('kpt-megamenu-host', className), ...rest, children: [_jsx("div", { className: "kpt-megamenu", role: "menubar", "aria-orientation": "horizontal", "aria-label": ariaLabel || undefined, ref: barRef, children: items.map((item, index) => {
+                    const hasMenu = !!item.items?.length;
+                    if (isLink(item)) {
+                        return (_jsxs("a", { ref: (el) => {
+                                buttonsRef.current[index] = el;
+                            }, className: "kpt-megamenu__top", role: "menuitem", href: item.url, tabIndex: index === tabStop ? 0 : -1, 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 })] }, index));
+                    }
+                    return (_jsxs("button", { ref: (el) => {
+                            buttonsRef.current[index] = el;
+                        }, type: "button", className: cn('kpt-megamenu__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 : 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-megamenu__caret" }) : null] }, index));
+                }) }), _jsx(KptOverlay, { open: openIndex !== null, anchor: barRef.current, onClose: closeAll, children: _jsx("div", { ref: panelRef, className: "kpt-megamenu__panel", role: "menu", id: panelId, "aria-label": openIndex === null ? undefined : items[openIndex]?.label, onKeyDown: onPanelKeyDown, children: columns.map((column, columnIndex) => {
+                        const titleId = `${panelId}-col-${columnIndex}`;
+                        return (_jsxs("div", { className: "kpt-megamenu__column", role: "group", "aria-labelledby": column.label ? titleId : undefined, children: [column.label ? (_jsx("div", { className: "kpt-megamenu__col-title", role: "presentation", id: titleId, children: column.label })) : null, (column.items ?? []).map((link, linkIndex) => isLink(link) ? (_jsxs("a", { className: "kpt-megamenu__link", role: "menuitem", tabIndex: -1, href: link.url, onClick: () => pick(link), children: [link.icon ? _jsx(KptIcon, { name: link.icon }) : null, _jsx("span", { children: link.label })] }, linkIndex)) : (_jsxs("button", { type: "button", className: "kpt-megamenu__link", role: "menuitem", tabIndex: -1, disabled: link.disabled, onClick: () => pick(link), children: [link.icon ? _jsx(KptIcon, { name: link.icon }) : null, _jsx("span", { children: link.label })] }, linkIndex)))] }, columnIndex));
+                    }) }) })] }));
 }

package/dist/menu/llms.txt

@@ -45,12 +45,23 @@ Angular port, which stands on CDK. Position, backdrop and Escape behave the same
 `--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-elevation-3`, `--kpt-color-danger`
 (the `danger` item), `--kpt-z-overlay`.
 
+## Keyboard
+- `↓` / `↑` on the trigger open the menu with focus on the first / last item; a click, `Enter`
+  or `Space` opens it on the first.
+- Inside: `↓` / `↑` move between items and wrap around, `Home` / `End` jump to the ends;
+  disabled items, separators and headers are skipped.
+- `Escape` and `Tab` close the menu, and so does picking an item — focus returns to the trigger.
+- Items carry `tabindex="-1"` (roving focus), so an open menu is one Tab stop, not one per item.
+
+The logic lives in `menu-keys.ts`, shared with `KptSplitButton`; the other port has a twin file.
+
 ## Accessibility
 The panel is `role="menu"`, items are native buttons with `role="menuitem"`, separators carry
 `role="separator"` and header rows `role="presentation"`, so a screen reader skips them instead of
 announcing them as actions.
 
-The trigger itself gets `aria-haspopup="menu"` and a live `aria-expanded`. They are placed on the
+The trigger itself gets `aria-haspopup="menu"`, a live `aria-expanded` and, while open,
+`aria-controls` pointing at the panel. They are placed on the
 interactive control INSIDE the slot (the projected `<button>`/`<a>`), never on the
 `.kpt-menu__trigger` wrapper — giving that wrapper a role would create a nested control and a second
 tab stop, and state attributes on a roleless element violate `aria-allowed-attr`.

package/dist/menu/menu-keys.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Indeks pozycji, na którą ma przejść fokus. `count` to liczba **aktywnych** pozycji (wyłączone,
+ * separatory i nagłówki są już odfiltrowane), `current` to indeks obecnie skupionej albo `-1`.
+ * Strzałki zawijają się na końcach. Zwraca `null` dla klawisza, który nie nawiguje.
+ */
+export declare function nextMenuIndex(count: number, current: number, key: string): number | null;
+/** Aktywne pozycje panelu w kolejności DOM. */
+export declare function menuItems(panel: HTMLElement): HTMLElement[];
+/** Skupia pierwszą albo ostatnią aktywną pozycję — po otwarciu menu z klawiatury lub myszy. */
+export declare function focusMenuEdge(panel: HTMLElement, edge: 'first' | 'last'): void;
+/**
+ * Obsługa klawisza w otwartym panelu. Zwraca `'close'`, gdy menu ma się zamknąć z powrotem
+ * fokusu na przycisk (Escape, Tab), `true`, gdy klawisz przesunął fokus, `false` — inny klawisz.
+ */
+export declare function handleMenuKeydown(panel: HTMLElement, event: KeyboardEvent): 'close' | boolean;

package/dist/menu/menu-keys.js

@@ -0,0 +1,53 @@
+/*
+ * Klawiatura panelu menu (wzorzec WAI-ARIA „menu button”), wspólna dla `kpt-menu`
+ * i `kpt-split-button` — oba mają ten sam panel z pozycjami `role="menuitem"`.
+ * Port Angulara ma bliźniaczy plik `lib/menu/menu-keys.ts` — zmiana zachowania w obu.
+ */
+/** Klawisze przesuwające fokus po pozycjach. */
+const NAV_KEYS = new Set(['ArrowDown', 'ArrowUp', 'Home', 'End']);
+/**
+ * Indeks pozycji, na którą ma przejść fokus. `count` to liczba **aktywnych** pozycji (wyłączone,
+ * separatory i nagłówki są już odfiltrowane), `current` to indeks obecnie skupionej albo `-1`.
+ * Strzałki zawijają się na końcach. Zwraca `null` dla klawisza, który nie nawiguje.
+ */
+export function nextMenuIndex(count, current, key) {
+    if (!NAV_KEYS.has(key) || count === 0)
+        return null;
+    switch (key) {
+        case 'Home':
+            return 0;
+        case 'End':
+            return count - 1;
+        case 'ArrowDown':
+            return current < 0 ? 0 : (current + 1) % count;
+        default:
+            return current < 0 ? count - 1 : (current - 1 + count) % count;
+    }
+}
+/** Aktywne pozycje panelu w kolejności DOM. */
+export function menuItems(panel) {
+    return [...panel.querySelectorAll('[role="menuitem"]:not(:disabled)')];
+}
+/** Skupia pierwszą albo ostatnią aktywną pozycję — po otwarciu menu z klawiatury lub myszy. */
+export function focusMenuEdge(panel, edge) {
+    const items = menuItems(panel);
+    (edge === 'first' ? items[0] : items[items.length - 1])?.focus();
+}
+/**
+ * Obsługa klawisza w otwartym panelu. Zwraca `'close'`, gdy menu ma się zamknąć z powrotem
+ * fokusu na przycisk (Escape, Tab), `true`, gdy klawisz przesunął fokus, `false` — inny klawisz.
+ */
+export function handleMenuKeydown(panel, event) {
+    if (event.key === 'Escape' || event.key === 'Tab') {
+        event.preventDefault();
+        return 'close';
+    }
+    const items = menuItems(panel);
+    const current = items.indexOf(document.activeElement);
+    const next = nextMenuIndex(items.length, current, event.key);
+    if (next === null)
+        return false;
+    event.preventDefault();
+    items[next].focus();
+    return true;
+}

package/dist/menu/menu-rows.js

@@ -10,6 +10,6 @@ export function MenuRows({ items, block, onPick }) {
         if (item.header) {
             return (_jsxs("div", { className: `${block}__header`, role: "presentation", children: [item.avatar ? (_jsx(KptAvatar, { src: item.avatar.src ?? null, name: item.avatar.name ?? '', icon: item.avatar.icon ?? null, size: "sm" })) : item.icon ? (_jsx(KptIcon, { name: item.icon })) : null, _jsxs("span", { className: `${block}__text`, children: [item.label ? _jsx("span", { className: `${block}__label`, children: item.label }) : null, item.description ? _jsx("span", { className: `${block}__description`, children: item.description }) : null] })] }, index));
         }
-        return (_jsxs("button", { type: "button", className: `${block}__item${item.danger ? ` ${block}__item--danger` : ''}`, role: "menuitem", disabled: item.disabled, onClick: () => onPick(item), children: [item.icon ? _jsx(KptIcon, { name: item.icon }) : null, _jsxs("span", { className: `${block}__text`, children: [_jsx("span", { className: `${block}__label`, children: item.label }), item.description ? _jsx("span", { className: `${block}__description`, children: item.description }) : null] }), item.badge !== undefined && item.badge !== null ? (_jsx(KptBadge, { className: `${block}__badge`, value: item.badge, variant: item.badgeVariant ?? 'primary' })) : null] }, index));
+        return (_jsxs("button", { type: "button", className: `${block}__item${item.danger ? ` ${block}__item--danger` : ''}`, role: "menuitem", tabIndex: -1, disabled: item.disabled, onClick: () => onPick(item), children: [item.icon ? _jsx(KptIcon, { name: item.icon }) : null, _jsxs("span", { className: `${block}__text`, children: [_jsx("span", { className: `${block}__label`, children: item.label }), item.description ? _jsx("span", { className: `${block}__description`, children: item.description }) : null] }), item.badge !== undefined && item.badge !== null ? (_jsx(KptBadge, { className: `${block}__badge`, value: item.badge, variant: item.badgeVariant ?? 'primary' })) : null] }, index));
     });
 }

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;