@konce-pt/react 0.9.0 → 0.10.0

package/dist/listbox/listbox.d.ts

@@ -9,6 +9,12 @@ export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
     multiple?: boolean;
     /** Pole filtrowania nad listą. */
     filter?: boolean;
+    /** Id listy (nie hosta); bez niego generowane, w `KptFormField` — z wrappera. */
+    id?: string;
+    /** Nazwa dostępna listy, gdy nie opisuje jej etykieta (`KptFormField`). */
+    ariaLabel?: string | null;
+    /** Oznacza listę jako wymaganą atrybutem `aria-required`. */
+    required?: boolean;
     disabled?: boolean;
     invalid?: boolean;
     touched?: boolean;
@@ -21,8 +27,14 @@ export interface KptListboxProps<T> extends Omit<ComponentPropsWithRef<'div'>, '
  * W trybie pojedynczym ponowny klik w zaznaczoną opcję odznacza ją — lista bywa filtrem,
  * a filtr trzeba dać się wyczyścić bez sięgania po osobny przycisk.
  *
+ * Klawiatura według wzorca WAI-ARIA „listbox”: lista to jeden przystanek Tab, a aktywną opcję
+ * ogłasza `aria-activedescendant`. Strzałki, `Home`/`End`, `PageUp`/`PageDown` przesuwają aktywną
+ * opcję (wyłączone są pomijane), pisanie liter skacze do kolejnej pasującej (bez względu na
+ * diakrytyki), `Spacja`/`Enter` wybiera, a w trybie wielokrotnym `Ctrl`/`⌘`+`A` zaznacza wszystkie
+ * widoczne. Pole filtra stoi przed listą; `↓` przenosi z niego fokus do listy.
+ *
  * @example
  * <KptListbox options={roles} value={role} onValueChange={setRole} filter />
  * <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
  */
-export declare function KptListbox<T>({ options, value, defaultValue, onValueChange, multiple, filter, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptListboxProps<T>>): import("react").JSX.Element;
+export declare function KptListbox<T>({ options, value, defaultValue, onValueChange, multiple, filter, id, ariaLabel, required, disabled, invalid, touched, onTouch, locale, dictionary, className, ...rest }: Readonly<KptListboxProps<T>>): import("react").JSX.Element;

package/dist/listbox/listbox.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { foldMentionText } from '@konce-pt/mention';
 import { cn } from "../internal/cn.js";
 import { useControllableState } from "../internal/use-controllable-state.js";
+import { KptTypeahead, OPTION_NAV_KEYS, isTypeaheadKey, nextOptionIndex, typeaheadIndex } from "../internal/option-nav.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
+import { useKptFieldA11y } from "../form-field/form-field-context.js";
 import { KptIcon } from "../icon/icon.js";
 /**
  * Lista wyboru widoczna w całości, bez rozwijania. Pojedynczy albo wielokrotny wybór,
@@ -11,23 +14,44 @@ import { KptIcon } from "../icon/icon.js";
  * W trybie pojedynczym ponowny klik w zaznaczoną opcję odznacza ją — lista bywa filtrem,
  * a filtr trzeba dać się wyczyścić bez sięgania po osobny przycisk.
  *
+ * Klawiatura według wzorca WAI-ARIA „listbox”: lista to jeden przystanek Tab, a aktywną opcję
+ * ogłasza `aria-activedescendant`. Strzałki, `Home`/`End`, `PageUp`/`PageDown` przesuwają aktywną
+ * opcję (wyłączone są pomijane), pisanie liter skacze do kolejnej pasującej (bez względu na
+ * diakrytyki), `Spacja`/`Enter` wybiera, a w trybie wielokrotnym `Ctrl`/`⌘`+`A` zaznacza wszystkie
+ * widoczne. Pole filtra stoi przed listą; `↓` przenosi z niego fokus do listy.
+ *
  * @example
  * <KptListbox options={roles} value={role} onValueChange={setRole} filter />
  * <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
  */
-export function KptListbox({ options = [], value, defaultValue = null, onValueChange, multiple = false, filter = false, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
+export function KptListbox({ options = [], value, defaultValue = null, onValueChange, multiple = false, filter = false, id, ariaLabel = null, required = false, disabled = false, invalid = false, touched, onTouch, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
+    /** `div` z rolą nie dostaje nazwy z `label[for]` — stąd `aria-labelledby` na etykietę wrappera. */
+    const field = useKptFieldA11y(id, 'kpt-listbox');
     const [current, setCurrent] = useControllableState({
         value,
         defaultValue,
         onChange: onValueChange,
     });
     const [query, setQuery] = useState('');
+    /** Aktywna opcja (indeks w `visible`); `-1` = żadna. */
+    const [activeIndex, setActiveIndex] = useState(-1);
+    const listRef = useRef(null);
+    const typeahead = useRef(new KptTypeahead()).current;
     const showInvalid = invalid && (touched ?? true);
+    /** Filtr bez względu na wielkość liter i diakrytyki („lodz” znajduje „Łódź”). */
     const visible = useMemo(() => {
-        const q = query.trim().toLowerCase();
-        return q ? options.filter((option) => option.label.toLowerCase().includes(q)) : options;
+        const q = foldMentionText(query.trim());
+        return q ? options.filter((option) => foldMentionText(option.label).includes(q)) : options;
     }, [options, query]);
+    const disabledMap = visible.map((option) => disabled || !!option.disabled);
+    const optionId = (index) => `${field.id}-opt-${index}`;
+    const activeOptionId = activeIndex >= 0 && activeIndex < visible.length ? optionId(activeIndex) : undefined;
+    // Aktywna opcja zawsze w polu widzenia listy (przewijana `max-height`).
+    useEffect(() => {
+        if (activeOptionId)
+            document.getElementById(activeOptionId)?.scrollIntoView({ block: 'nearest' });
+    }, [activeOptionId]);
     const isSelected = (candidate) => multiple ? Array.isArray(current) && current.includes(candidate) : current === candidate;
     const toggle = (candidate) => {
         if (multiple) {
@@ -37,7 +61,66 @@ export function KptListbox({ options = [], value, defaultValue = null, onValueCh
         else {
             setCurrent(current === candidate ? null : candidate);
         }
-        onTouch?.();
     };
-    return (_jsx("div", { className: cn('kpt-listbox-host', className), ...rest, children: _jsxs("div", { className: cn('kpt-listbox', showInvalid && 'kpt-listbox--invalid'), role: "listbox", "aria-multiselectable": multiple, children: [filter ? (_jsxs("div", { className: "kpt-listbox__filter", children: [_jsx(KptIcon, { name: "search" }), _jsx("input", { type: "text", placeholder: t('listbox.search'), value: query, onChange: (event) => setQuery(event.target.value) })] })) : null, _jsx("div", { className: "kpt-listbox__items", children: visible.length ? (visible.map((option) => (_jsxs("button", { type: "button", role: "option", className: cn('kpt-listbox__item', isSelected(option.value) && 'is-selected'), "aria-selected": isSelected(option.value), disabled: disabled || option.disabled, onClick: () => toggle(option.value), children: [_jsx("span", { children: option.label }), isSelected(option.value) ? _jsx(KptIcon, { name: "check" }) : null] }, String(option.value))))) : (_jsx("div", { className: "kpt-listbox__empty", children: t('listbox.empty') })) })] }) }));
+    const pick = (index) => {
+        const option = visible[index];
+        if (!option || disabledMap[index])
+            return;
+        setActiveIndex(index);
+        toggle(option.value);
+    };
+    /** Wejście fokusem: aktywna zostaje wybrana opcja, a bez niej pierwsza dozwolona. */
+    const onFocus = () => {
+        if (activeIndex >= 0 && activeIndex < visible.length)
+            return;
+        const selected = visible.findIndex((option, index) => isSelected(option.value) && !disabledMap[index]);
+        setActiveIndex(selected >= 0 ? selected : (nextOptionIndex(disabledMap, -1, 'Home') ?? -1));
+    };
+    const onQuery = (text) => {
+        setQuery(text);
+        const q = foldMentionText(text.trim());
+        const next = q ? options.filter((option) => foldMentionText(option.label).includes(q)) : options;
+        setActiveIndex(nextOptionIndex(next.map((option) => disabled || !!option.disabled), -1, 'Home') ?? -1);
+    };
+    const onKeyDown = (event) => {
+        if (disabled)
+            return;
+        if (OPTION_NAV_KEYS.has(event.key)) {
+            event.preventDefault();
+            const next = nextOptionIndex(disabledMap, activeIndex, event.key);
+            if (next !== null)
+                setActiveIndex(next);
+            return;
+        }
+        if (event.key === ' ' || event.key === 'Enter') {
+            if (activeIndex < 0)
+                return;
+            event.preventDefault();
+            pick(activeIndex);
+            return;
+        }
+        if (multiple && (event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'a') {
+            event.preventDefault();
+            const all = visible.filter((_, index) => !disabledMap[index]).map((option) => option.value);
+            const list = Array.isArray(current) ? current : [];
+            // Drugi raz `Ctrl+A` przy wszystkich zaznaczonych — odznacza widoczne.
+            const allOn = all.every((item) => list.includes(item));
+            setCurrent(allOn ? list.filter((item) => !all.includes(item)) : [...list, ...all.filter((item) => !list.includes(item))]);
+            return;
+        }
+        if (isTypeaheadKey(event.nativeEvent)) {
+            const hit = typeaheadIndex(visible.map((option) => option.label), disabledMap, activeIndex, typeahead.push(event.key));
+            if (hit !== null)
+                setActiveIndex(hit);
+        }
+    };
+    return (_jsx("div", { className: cn('kpt-listbox-host', className), ...rest, children: _jsxs("div", { className: cn('kpt-listbox', showInvalid && 'kpt-listbox--invalid', disabled && 'kpt-listbox--disabled'), children: [filter ? (_jsxs("div", { className: "kpt-listbox__filter", children: [_jsx(KptIcon, { name: "search" }), _jsx("input", { type: "text", placeholder: t('listbox.search'), "aria-label": t('listbox.search'), "aria-controls": field.id, disabled: disabled, value: query, onChange: (event) => onQuery(event.target.value), onKeyDown: (event) => {
+                                if (event.key !== 'ArrowDown')
+                                    return;
+                                event.preventDefault();
+                                listRef.current?.focus();
+                            } })] })) : null, _jsx("div", { ref: listRef, className: "kpt-listbox__items", role: "listbox", id: field.id, tabIndex: disabled ? -1 : 0, "aria-multiselectable": multiple || undefined, "aria-activedescendant": activeOptionId, "aria-disabled": disabled || undefined, "aria-invalid": showInvalid || undefined, "aria-required": required || undefined, "aria-label": ariaLabel ?? undefined, "aria-labelledby": ariaLabel ? undefined : field.labelledBy, "aria-describedby": field.describedBy, onKeyDown: onKeyDown, onFocus: onFocus, onBlur: () => onTouch?.(), children: visible.length ? (visible.map((option, index) => (_jsxs("div", { role: "option", id: optionId(index), className: cn('kpt-listbox__item', isSelected(option.value) && 'is-selected', index === activeIndex && 'is-active'), "aria-selected": isSelected(option.value), "aria-disabled": disabledMap[index] || undefined, onMouseDown: (event) => {
+                            event.preventDefault();
+                            listRef.current?.focus();
+                        }, onClick: () => pick(index), children: [_jsx("span", { children: option.label }), isSelected(option.value) ? _jsx(KptIcon, { name: "check" }) : null] }, String(option.value))))) : (_jsx("div", { className: "kpt-listbox__empty", role: "status", children: t('listbox.empty') })) })] }) }));
 }

package/dist/listbox/llms.txt

@@ -5,10 +5,10 @@ Import: `import { KptListbox } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-listbox-host">
-      <div class="kpt-listbox" role="listbox" aria-multiselectable="false">
+      <div class="kpt-listbox">
         <div class="kpt-listbox__filter">…icon + input…</div>
-        <div class="kpt-listbox__items">
-          <button class="kpt-listbox__item is-selected" role="option" aria-selected="true">Admin</button>
+        <div class="kpt-listbox__items" role="listbox" tabindex="0" aria-activedescendant="…-opt-0">
+          <div class="kpt-listbox__item is-selected is-active" role="option" id="…-opt-0" aria-selected="true">Admin</div>
         </div>
       </div>
     </div>
@@ -17,6 +17,7 @@ Import: `import { KptListbox } from '@konce-pt/react';`
 - `options`: `KptOption<T>[]`
 - `value` / `defaultValue` / `onValueChange` — `T` (single) or `T[]` (multiple)
 - `multiple`, `filter`, `disabled`, `invalid`, `touched`, `onTouch()`
+- `id`, `ariaLabel`, `required`
 - `locale`, `dictionary` — i18n overrides for this component only
 
 ## Clicking the selection clears it
@@ -30,10 +31,25 @@ filter has to be clearable without a separate button.
     <KptListbox options={roles} value={role} onValueChange={setRole} filter />
     <KptListbox options={tags} value={tags} onValueChange={setTags} multiple />
 
+## Keyboard
+The WAI-ARIA listbox pattern: the list is one Tab stop and the active option is announced through
+`aria-activedescendant`. `↑`/`↓`, `Home`/`End` and `PageUp`/`PageDown` move the active option,
+skipping disabled ones (no wrapping); typing letters jumps to the next match, diacritics ignored;
+`Space`/`Enter` picks; in `multiple` mode `Ctrl`/`⌘`+`A` selects every visible option (again —
+clears them). The filter field sits before the list (outside the `listbox`) and `↓` moves focus
+from it into the list; the filter itself ignores diacritics ("lodz" finds "Łódź").
+
+## Label and description
+`id` goes to the list (`role="listbox"`), never the host. A `div` with a role is not named by
+`label[for]`, so inside `KptFormField` the list gets `aria-labelledby` pointing at the wrapper's
+label (unless `ariaLabel` is set) and the hint or error in `aria-describedby`. New: `id`,
+`ariaLabel`, `required` (→ `aria-required`); `aria-invalid` after touch; `touch` fires on blur of the list.
+
 ## Tokens
 `--kpt-color-surface`, `--kpt-color-border`, `--kpt-color-primary-subtle` (the selected row),
 `--kpt-form-field-border-error`.
 
 ## Accessibility
-`role="listbox"` with `aria-multiselectable`; every option is a native button with
-`role="option"` and `aria-selected`, so the keyboard walks the list without extra handling.
+The list is `role="listbox"` with `aria-multiselectable`, `aria-activedescendant` and a name from
+`ariaLabel` or `KptFormField`; options are `role="option"` with `aria-selected`/`aria-disabled`.
+The keyboard is described above.

package/dist/megamenu/llms.txt

@@ -5,21 +5,23 @@ Import: `import { KptMegamenu } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-megamenu-host">
-      <nav class="kpt-megamenu" role="menubar">
-        <button class="kpt-megamenu__top is-open" role="menuitem">Products …caret…</button>
-      </nav>
+      <div class="kpt-megamenu" role="menubar" aria-orientation="horizontal" aria-label="Main menu">
+        <button class="kpt-megamenu__top is-open" role="menuitem" tabindex="0"
+                aria-haspopup="menu" aria-expanded="true" aria-controls="kpt-megamenu-r1">Products …caret…</button>
+      </div>
     </div>
     <!-- while open, in a portal: -->
-    <div class="kpt-megamenu__panel" role="menu">
-      <div class="kpt-megamenu__column">
-        <div class="kpt-megamenu__col-title">Components</div>
-        <button class="kpt-megamenu__link">Forms</button>
+    <div class="kpt-megamenu__panel" role="menu" id="kpt-megamenu-r1" aria-label="Products">
+      <div class="kpt-megamenu__column" role="group" aria-labelledby="kpt-megamenu-r1-col-0">
+        <div class="kpt-megamenu__col-title" role="presentation" id="kpt-megamenu-r1-col-0">Components</div>
+        <button class="kpt-megamenu__link" role="menuitem" tabindex="-1">Forms</button>
       </div>
     </div>
 
 ## Props
 - `items`: `KptMenuItem<T>[]` — three levels: top item → `items` (columns) → column `items` (links)
-- `onSelect(link)` — a picked link from a column
+- `onSelect(link)` — a picked link from a column, or a top item without columns
+- `ariaLabel`: string — the bar's name for screen readers, e.g. "Main menu"
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## The panel is anchored to the whole bar
@@ -39,10 +41,26 @@ without closing the panel, so browsing across sections costs one click each.
       ],
     }];
 
+## 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-raised`, `--kpt-color-border`, `--kpt-elevation-3`,
 `--kpt-color-on-surface-muted` (the column titles).
 
 ## Accessibility
-The bar is `role="menubar"` with `role="menuitem"` buttons; the panel is `role="menu"`. Column
-titles are plain text, not headings, so they do not disturb the page outline.
+The bar is `role="menubar"` (`aria-orientation="horizontal"`, named by `ariaLabel`) with
+`role="menuitem"` buttons; those with columns carry `aria-haspopup="menu"`, `aria-expanded` and
+`aria-controls`. The panel is `role="menu"` named after the open item, each column is
+`role="group"` named by its title, and links are `role="menuitem"`. Column titles are not headings,
+so they do not disturb the page outline. A top item without columns fires `onSelect` instead of
+opening an empty panel.
+
+## Keyboard
+The same as `KptMenubar`: one `Tab` stop for the bar, `ArrowLeft`/`ArrowRight` and `Home`/`End`
+along it, `ArrowDown` (or `Enter`/`Space`) opens the panel on the first link, `ArrowUp` on the last.
+In the panel `ArrowDown`/`ArrowUp`/`Home`/`End` walk through all links column by column,
+`ArrowLeft`/`ArrowRight` show the neighbouring item's panel, `Escape` or `Tab` close it and return
+focus to the top item.

package/dist/megamenu/megamenu.d.ts

@@ -3,15 +3,24 @@ import type { KptMenuItem } from '../menu/menu-item.ts';
 export interface KptMegamenuProps<T> extends Omit<ComponentPropsWithRef<'div'>, 'onSelect'> {
     items?: readonly KptMenuItem<T>[];
     onSelect?: (item: KptMenuItem<T>) => void;
+    /** Nazwa belki dla czytników ekranu, np. „Menu główne”. */
+    ariaLabel?: string;
 }
 /**
  * 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 declare function KptMegamenu<T>({ items, onSelect, className, ...rest }: Readonly<KptMegamenuProps<T>>): import("react").JSX.Element;
+export declare function KptMegamenu<T>({ items, onSelect, ariaLabel, className, ...rest }: Readonly<KptMegamenuProps<T>>): import("react").JSX.Element;

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));
     });
 }