@nldd/design-system 0.8.62 → 0.8.64

package/dist/components/lists-and-tables/list/list.js

@@ -4,14 +4,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var NLDDList_1;
 import { LitElement } from 'lit';
-import { customElement, property, state } from 'lit/decorators.js';
+import { customElement, property, query, state } from 'lit/decorators.js';
 import { listStyles } from './list.styles.js';
 import { template } from './list.template.js';
 import { nlddListTranslations } from './list.i18n.js';
 import '../../status-and-feedback/inline-dialog/inline-dialog.js';
+import '../../content/icon/icon.js';
+import '../../actions/icon-button/icon-button.js';
 /**
- * A container for `nldd-list-item` elements, with optional header and footer slots.
+ * A container for `nldd-list-item` elements.
  *
  * The `type` attribute switches the list's a11y role and behavior:
  * - `list` (default) — `role="list"`, items `role="listitem"`. Reorderable allowed.
@@ -19,9 +22,37 @@ import '../../status-and-feedback/inline-dialog/inline-dialog.js';
  *                     has no special keyboard semantics.
  * - `navigation`     — host `role="navigation"`, items with `selected` get
  *                     `aria-current="page"` on their inner `<a>` or `<button>`.
+ * - `listbox`        — an accessible, filterable listbox (combobox pattern). The
+ *                     list renders its OWN search input (`role="combobox"`) pinned
+ *                     above the options; `.list__items` becomes `role="listbox"`
+ *                     and items become `role="option"`. Focus stays in the input,
+ *                     the active option moves via `aria-activedescendant`, and
+ *                     filtering is consumer-managed via the `input` event (toggle
+ *                     `[hidden]` on items). See "Listbox" below.
  *
  * Selection state is consumer-managed: the list never mutates `selected` itself.
  *
+ * ### Listbox
+ *
+ * In `type="listbox"` the list owns a native `<input role="combobox">` (mirroring
+ * how `nldd-combo-box` wires an input to a slotted listbox). Keyboard, handled on
+ * the input so focus never leaves it:
+ * - ArrowDown / ArrowUp — move the active option among the VISIBLE (non-`[hidden]`)
+ *   options (wrap around).
+ * - Home / End — first / last visible option.
+ * - Enter — activate the active option by triggering its inner action (a link
+ *   navigates, a button fires the consumer's handler). Selection stays
+ *   consumer-managed.
+ * - Escape — clear the search value (and refire `input`).
+ *
+ * On every active change the input's `aria-activedescendant` is set to the active
+ * option's id and the option is scrolled into view. The active option (`_highlighted`
+ * on the item, a highlight) is distinct from `selected`. Filtering is the
+ * consumer's job: listen to `input` (`{ detail: { value } }`) and toggle `[hidden]`
+ * on items; after the visible set changes the list resets the active option to the
+ * first visible one. `reorderable` and `arrow-navigation` are ignored in listbox
+ * mode (listbox has its own keyboard).
+ *
  * ### Reorder
  *
  * On reorder (type="list" + reorderable), the list dispatches `nldd-reorder` with
@@ -33,16 +64,24 @@ import '../../status-and-feedback/inline-dialog/inline-dialog.js';
  * should manage focus themselves after their render commits.
  *
  * @slot         - List items (`nldd-list-item`)
- * @slot header  - Content above the list body (e.g. `nldd-title`)
- * @slot footer  - Content below the list body (e.g. a short description)
+ * @slot toolbar - Controls below the search field (filters, sort, counts,
+ *                 view toggles). Available for every type; collapses when empty.
+ * @slot search-bar-end - Controls inline at the end of the search bar, beside the
+ *                 search field (e.g. a filter or options button). Listbox only;
+ *                 collapses when empty.
  * @slot empty   - Shown when no items are visible (all `[hidden]` or none). Defaults
  *                 to `nldd-inline-dialog` with `empty-text` / `empty-supporting-text`
- *                 (falling back to Dutch i18n "Geen resultaten"). Slot content
- *                 overrides the default dialog entirely.
+ *                 (falling back to Dutch i18n "Geen items"). Slot content
+ *                 overrides the default dialog entirely. In `type="listbox"` it is
+ *                 suppressed while the search field is empty (no query yet), so the
+ *                 consumer can show just the search field or its own hint outside
+ *                 the list.
  *
  * @fires nldd-reorder - Reorderable `type="list"`: `{ fromIndex, toIndex }` on drop
+ * @fires input        - `type="listbox"`: search value changed; `{ value }`. Toggle
+ *                       `[hidden]` on items to filter.
  */
-let NLDDList = class NLDDList extends LitElement {
+let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
     constructor() {
         super(...arguments);
         /** Visual style of the list. `simple` is a plain vertical strip with
@@ -55,9 +94,38 @@ let NLDDList = class NLDDList extends LitElement {
         this.reorderable = false;
         /** Hides dividers between list items. */
         this.noDividers = false;
+        /**
+         * Roving-tabindex arrow-key navigation. When set, ArrowUp/ArrowDown move focus
+         * between the (interactive) items, Home/End jump to the first/last, and the
+         * whole list becomes a single tab stop — so Tab moves past the rest instead of
+         * stepping through every item. Arrows move focus only; selection stays
+         * consumer-managed.
+         *
+         * Pragmatic by design: the `list`/`navigation` role is kept (no widget role).
+         * Use it only on **simple** lists where each item has a single action and no
+         * extra controls (a control in a `start`/`end` slot would not be reachable as
+         * its own tab stop). Mutually exclusive with `reorderable` (both use the arrow
+         * keys); when both are set, `reorderable` wins and this is ignored.
+         *
+         * Known a11y limitation: because the role stays `list`/`navigation` (not
+         * `listbox`/`menu`), screen readers do not auto-announce that the arrow keys
+         * navigate. As a best-effort signal the host carries
+         * `aria-keyshortcuts="ArrowUp ArrowDown Home End"` while active, but blind users
+         * may still not discover the feature — another reason to keep it to genuinely
+         * simple lists.
+         */
+        this.arrowNavigation = false;
+        /**
+         * Only in `type="listbox"`: caps the options' scroll region at this CSS
+         * length (any value `CSS.supports('max-height', …)` accepts, e.g. "320px").
+         * The search input stays pinned above and the options scroll; the active
+         * option is kept in view via `scrollIntoView`. Unset → no cap. No effect
+         * outside listbox mode.
+         */
+        this.height = '';
         /**
          * Text for the default empty-state dialog. Falls back to the Dutch
-         * i18n default ("Geen resultaten"). Ignored when consumers slot their
+         * i18n default ("Geen items"). Ignored when consumers slot their
          * own content into `[slot=empty]`.
          */
         this.emptyText = '';
@@ -66,11 +134,28 @@ let NLDDList = class NLDDList extends LitElement {
          * Ignored when consumers slot their own content into `[slot=empty]`.
          */
         this.emptySupportingText = '';
+        /** Accessible name for the list, forwarded to the inner role: the list in
+         *  `type=list`, the search field in `type=listbox`. For `type=navigation`,
+         *  set `aria-label` / `aria-labelledby` on the element directly (it is a
+         *  landmark). Falls back to the default i18n label when unset. */
+        this.accessibleLabel = '';
         /** Override one or more translation keys. Unset keys fall back to the Dutch default. */
         this.translations = {};
         this._mergedTranslations = { ...nlddListTranslations };
-        this._hasHeader = false;
+        this._hasToolbar = false;
+        this._hasSearchBarEnd = false;
         this._isEmpty = false;
+        // — Listbox state ————————————————————————————————————————————————————————
+        /** Current search value (listbox mode). Mirrored to the input. */
+        this._searchValue = '';
+        /** ID of the active option (listbox mode), or '' when none. Fed to the
+         *  input's aria-activedescendant. Distinct from selection. */
+        this._activeId = '';
+        /** Whether the search input has focus. aria-activedescendant is the input's
+         *  virtual focus, so the active-option highlight only shows while it is
+         *  focused; _activeId is remembered across blur so focus resumes there. */
+        this._searchFocused = false;
+        this._listboxId = `nldd-list-listbox-${NLDDList_1._idCounter++}`;
         // — Drag state ——————————————————————————————————————————————————————————
         this._draggingEl = null;
         this._draggingFromIndex = -1;
@@ -82,6 +167,117 @@ let NLDDList = class NLDDList extends LitElement {
         this._listRect = null;
         // — Observers ————————————————————————————————————————————————————————————
         this._itemsObserver = null;
+        this._contextScheduled = false;
+        /** Keep the active option valid after the visible set changes (initial
+         *  render, slot change, or consumer-driven `[hidden]` filtering): ensure ids,
+         *  reset the active option to the first visible one when the current active is
+         *  gone (or none was set), push `_highlighted` onto the items, and refresh the
+         *  input's aria-activedescendant. When nothing is visible the empty state
+         *  shows and aria-activedescendant is cleared. Deferred to a microtask for the
+         *  same reason as roving — it can run inside the update lifecycle and would
+         *  otherwise trip Lit's change-in-update warning. */
+        this._listboxScheduled = false;
+        this._onSearchInput = (event) => {
+            // The native input event is composed and would escape the shadow root
+            // alongside our own CustomEvent, reaching consumers as a second `input`
+            // without a `detail`. Stop it so the only `input` they see is ours,
+            // carrying { value }.
+            event.stopPropagation();
+            const input = event.target;
+            this._searchValue = input.value;
+            this._emitListboxInput(this._searchValue);
+        };
+        this._onClearClick = () => {
+            this._clearSearch();
+        };
+        /** Track whether the search-bar-end slot has content, so its wrapper (and the
+         *  bar gap) collapses when empty. Bound in the template so it follows the slot
+         *  even though the search bar only renders in listbox mode. */
+        this._onSearchBarEndSlotChange = (event) => {
+            this._hasSearchBarEnd = event.target.assignedElements().length > 0;
+        };
+        this._onSearchFocus = () => {
+            this._searchFocused = true;
+            // Resume at the remembered active option, or the first visible one if none
+            // is set or it was filtered away.
+            this._applyListboxOptions();
+        };
+        this._onSearchBlur = () => {
+            this._searchFocused = false;
+            this._syncHighlight();
+        };
+        /** Clicking an option moves the (remembered) active descendant to it, so the
+         *  highlight resumes there when the search input regains focus. */
+        this._onListClick = (event) => {
+            if (this.type !== 'listbox')
+                return;
+            const item = event.target?.closest?.('nldd-list-item');
+            if (item && item.parentElement === this && !item.hasAttribute('hidden')) {
+                this._activeId = this._ensureOptionId(item);
+            }
+        };
+        /**
+         * Listbox keyboard, handled on the search input — focus never leaves it.
+         * Arrows/Home/End move the active option among the visible set; Enter
+         * activates it by triggering its inner action; Escape clears the value.
+         */
+        this._onSearchKeyDown = (event) => {
+            const { key } = event;
+            if (key === 'Escape') {
+                if (this._searchValue !== '') {
+                    event.preventDefault();
+                    this._clearSearch();
+                }
+                return;
+            }
+            if (key === 'Enter') {
+                const active = this._activeItem;
+                if (active) {
+                    event.preventDefault();
+                    // Trigger the option's inner action: a link navigates, a button
+                    // fires the consumer's handler. Selection stays consumer-managed.
+                    active.shadowRoot?.querySelector('.list-item__action')?.click();
+                    // Enter is keyboard interaction, so keep focus on the search input
+                    // (the combobox model: the active option is the virtual focus via
+                    // aria-activedescendant). The option's click would otherwise pull DOM
+                    // focus onto it; refocus so typing/arrowing continues and the
+                    // highlight stays.
+                    this._searchInput?.focus();
+                }
+                return;
+            }
+            if (key !== 'ArrowDown' && key !== 'ArrowUp' && key !== 'Home' && key !== 'End')
+                return;
+            const visible = this._getVisibleItems();
+            if (visible.length === 0)
+                return;
+            event.preventDefault();
+            const current = visible.findIndex(item => item.id === this._activeId);
+            let next;
+            if (key === 'Home') {
+                next = 0;
+            }
+            else if (key === 'End') {
+                next = visible.length - 1;
+            }
+            else {
+                const dir = key === 'ArrowDown' ? 1 : -1;
+                const base = current === -1 ? (dir === 1 ? -1 : 0) : current;
+                next = (base + dir + visible.length) % visible.length; // wrap around
+            }
+            this._setActiveOption(visible[next]);
+        };
+        this._rovingScheduled = false;
+        this._onFocusIn = (event) => {
+            if (!this._arrowNavActive)
+                return;
+            const item = event.composedPath().find((el) => el instanceof Element && el.tagName.toLowerCase() === 'nldd-list-item');
+            // Keep the roving entry point wherever focus actually lands (Tab in, a
+            // click, or programmatic focus), so arrows continue from there.
+            if (item && (item.href || item.button) && !item._rovingActive) {
+                this._setRovingActive(item);
+            }
+        };
         // — Drag: pointer ————————————————————————————————————————————————————————
         this._onPointerDown = (event) => {
             if (!this.reorderable || this.type !== 'list')
@@ -143,6 +339,12 @@ let NLDDList = class NLDDList extends LitElement {
         // Mirrors nldd-document-tab-bar: no grab-and-drop cycle — each arrow press
         // reorders the DOM, fires nldd-reorder and restores focus on the handle.
         this._onKeyDown = (event) => {
+            // Arrow-navigation and reorder both claim the arrow keys; _arrowNavActive
+            // is false whenever reorderable wins, so the two never run together.
+            if (this._arrowNavActive) {
+                this._onArrowNav(event);
+                return;
+            }
             if (!this.reorderable || this.type !== 'list')
                 return;
             if (event.key !== 'ArrowUp' && event.key !== 'ArrowDown')
@@ -189,10 +391,17 @@ let NLDDList = class NLDDList extends LitElement {
         });
         this._updateItems();
         this._updateEmpty();
-        const headerSlot = this.shadowRoot?.querySelector('slot[name="header"]');
-        headerSlot?.addEventListener('slotchange', () => {
-            this._hasHeader = (headerSlot.assignedElements().length > 0);
-        });
+        this._warnArrowNav();
+        const toolbarSlot = this.shadowRoot?.querySelector('slot[name="toolbar"]');
+        const syncToolbar = () => { this._hasToolbar = (toolbarSlot?.assignedElements().length ?? 0) > 0; };
+        toolbarSlot?.addEventListener('slotchange', syncToolbar);
+        syncToolbar();
+        // The search-bar-end slot only renders in listbox; sync its initial presence
+        // here. The @slotchange binding in the template keeps it updated afterwards
+        // and re-binds whenever the search bar (re)renders on a type change.
+        const searchBarEndSlot = this.shadowRoot?.querySelector('slot[name="search-bar-end"]');
+        if (searchBarEndSlot)
+            this._hasSearchBarEnd = searchBarEndSlot.assignedElements().length > 0;
         // Watch direct children for add/remove (nldd-list-item gains/lose) and
         // for `hidden` toggles on those direct children (consumer-driven
         // filtering). `subtree: true` is required because `attributes` on the
@@ -234,31 +443,60 @@ let NLDDList = class NLDDList extends LitElement {
         this.style.containerName = 'cells-container';
         this.addEventListener('pointerdown', this._onPointerDown);
         this.addEventListener('keydown', this._onKeyDown);
+        this.addEventListener('focusin', this._onFocusIn);
+        this.addEventListener('click', this._onListClick);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('pointerdown', this._onPointerDown);
         this.removeEventListener('keydown', this._onKeyDown);
+        this.removeEventListener('focusin', this._onFocusIn);
+        this.removeEventListener('click', this._onListClick);
         this._itemsObserver?.disconnect();
         this._itemsObserver = null;
         this._cancelDrag();
     }
     updated(changed) {
-        if (changed.has('reorderable') || changed.has('type')) {
+        if (changed.has('reorderable') || changed.has('type') || changed.has('arrowNavigation')) {
             if (this.reorderable && this.type !== 'list' && import.meta.env?.DEV) {
                 console.warn('nldd-list: `reorderable` is only valid when type="list". Ignoring.');
             }
             this._updateItems();
+            this._warnArrowNav();
+        }
+        if (changed.has('variant')) {
+            this._updateItemContext();
         }
         if (changed.has('translations')) {
             this._mergedTranslations = { ...nlddListTranslations, ...this.translations };
         }
         if (changed.has('type')) {
             this._applyHostType();
+            // Leaving listbox mode: drop the active highlight and reset state so a
+            // stale `_highlighted`/aria-activedescendant doesn't survive the switch.
+            if (changed.get('type') === 'listbox' && this.type !== 'listbox') {
+                this._activeId = '';
+                this._getItems().forEach(item => { item._highlighted = false; });
+            }
+        }
+        if (changed.has('height')) {
+            // Mirror the width/height inline-style pattern: validate, then feed a
+            // local var the CSS reads as max-height on the scroll region.
+            const h = this.height;
+            if (h && CSS.supports('max-height', h)) {
+                this.style.setProperty('--_max-height', h);
+            }
+            else {
+                this.style.removeProperty('--_max-height');
+            }
         }
     }
     // — Host attribute routing ————————————————————————————————————————————————
     _applyHostType() {
+        // Only `navigation` puts a role on the host. `list` and `listbox` leave
+        // the host role-less: `list` carries role="list" on `.list__items`, and
+        // `listbox` carries role="listbox" there — putting a second widget role
+        // on the host would nest landmarks/roles incorrectly.
         if (this.type === 'navigation') {
             this.setAttribute('role', 'navigation');
             if (!this.hasAttribute('aria-label') && !this.hasAttribute('aria-labelledby')) {
@@ -287,12 +525,19 @@ let NLDDList = class NLDDList extends LitElement {
         const slot = this.shadowRoot?.querySelector('slot:not([name])');
         return (slot?.assignedElements() ?? []).filter((el) => el.tagName.toLowerCase() === 'nldd-list-item' && !el.hasAttribute('data-nldd-placeholder'));
     }
+    /** Visible (non-`[hidden]`) items, in DOM order. The active-option model and
+     *  listbox keyboard operate over this set. */
+    _getVisibleItems() {
+        return this._getItems().filter(item => !item.hasAttribute('hidden'));
+    }
     _updateItems() {
         const items = this._getItems();
         const visibleItems = items.filter(item => !item.hasAttribute('hidden'));
+        const firstVisible = visibleItems[0];
         const lastVisible = visibleItems[visibleItems.length - 1];
         const reorderActive = this.reorderable && this.type === 'list';
         items.forEach((item) => {
+            item.classList.toggle('is-first', item === firstVisible);
             item.classList.toggle('is-last', item === lastVisible);
             if (reorderActive) {
                 item.setAttribute('reorderable', '');
@@ -301,11 +546,220 @@ let NLDDList = class NLDDList extends LitElement {
                 item.removeAttribute('reorderable');
             }
         });
+        this._updateItemContext();
+        this._updateRoving();
+        if (this.type === 'listbox')
+            this._updateListboxOptions();
+    }
+    /** Push the list's variant + type onto every item, deferred to a microtask:
+     *  _updateItems runs inside the update lifecycle (firstUpdated/updated), and
+     *  setting the items' reactive state there would trip Lit's change-in-update
+     *  warning. Coalesced so repeated item updates schedule it only once. */
+    _updateItemContext() {
+        if (this._contextScheduled)
+            return;
+        this._contextScheduled = true;
+        queueMicrotask(() => {
+            this._contextScheduled = false;
+            this._applyItemContext();
+        });
+    }
+    /** The list owns variant + type; every item mirrors them (is-boxed styling and
+     *  the option/listitem role). Pushing from the list, not a per-item observer,
+     *  means a runtime variant/type switch, or a freshly added item, always tracks
+     *  the list. */
+    _applyItemContext() {
+        this._getItems().forEach((item) => {
+            item._applyVariant(this.variant);
+            item._applyParentType(this.type);
+        });
     }
     _updateEmpty() {
         const items = this._getItems();
         this._isEmpty = items.length === 0 || items.every(item => item.hasAttribute('hidden'));
     }
+    // — Listbox: active-option model ————————————————————————————————————————————
+    /** Every option needs a stable id for aria-activedescendant. Assign one to
+     *  any item that lacks one (consumer-supplied ids win). */
+    _ensureOptionId(item) {
+        if (!item.id) {
+            item.id = `nldd-list-option-${NLDDList_1._optionIdCounter++}`;
+        }
+        return item.id;
+    }
+    _updateListboxOptions() {
+        if (this._listboxScheduled)
+            return;
+        this._listboxScheduled = true;
+        queueMicrotask(() => {
+            this._listboxScheduled = false;
+            this._applyListboxOptions();
+        });
+    }
+    _applyListboxOptions() {
+        if (this.type !== 'listbox')
+            return;
+        const visible = this._getVisibleItems();
+        visible.forEach(item => this._ensureOptionId(item));
+        // Keep the active option if it's still visible, otherwise fall back to the
+        // first visible option (or none when the list is empty).
+        const current = visible.find(item => item.id === this._activeId);
+        const active = current ?? visible[0];
+        this._activeId = active?.id ?? '';
+        this._syncHighlight();
+    }
+    /** Move the active option to `item`: update state, reflect aria-activedescendant
+     *  on the input, and scroll the option into view (it may be inside the capped
+     *  scroll region). */
+    _setActiveOption(item) {
+        this._activeId = this._ensureOptionId(item);
+        this._syncHighlight();
+        item.scrollIntoView({ block: 'nearest' });
+    }
+    /** Reflect the active descendant onto the items, but only while the search
+     *  input is focused (aria-activedescendant is its virtual focus). _activeId is
+     *  remembered across blur so focus resumes at the same option; the template
+     *  gates aria-activedescendant on _searchFocused the same way. */
+    _syncHighlight() {
+        const active = this._searchFocused ? this._activeItem : null;
+        this._getItems().forEach(i => { i._highlighted = i === active; });
+    }
+    /** The currently active option element, or null. */
+    get _activeItem() {
+        if (!this._activeId)
+            return null;
+        return this._getVisibleItems().find(item => item.id === this._activeId) ?? null;
+    }
+    // — Listbox: search input ————————————————————————————————————————————————————
+    /** Dispatch the consumer-facing `input` event so it can filter (toggle
+     *  `[hidden]` on items). Composed + bubbling, `{ detail: { value } }`. */
+    _emitListboxInput(value) {
+        this.dispatchEvent(new CustomEvent('input', {
+            detail: { value },
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    /** Clear the search value (clear button / Escape) and refire `input` so the
+     *  consumer refilters. Focus stays on the input. */
+    _clearSearch() {
+        this._searchValue = '';
+        if (this._searchInput)
+            this._searchInput.value = '';
+        this._emitListboxInput('');
+        this._searchInput?.focus();
+    }
+    // — Arrow navigation (roving tabindex) ————————————————————————————————————
+    /** Arrow-navigation is effective only when reorderable isn't already claiming
+     *  the arrow keys for drag-reorder (reorderable wins). The guard also checks
+     *  `type === 'list'` on purpose: reorderable is inert without it, so there is no
+     *  conflict to resolve. `arrow-navigation reorderable` without `type="list"`
+     *  therefore keeps arrow-nav active (reorderable does nothing), and
+     *  `_warnArrowNav` likewise only warns for the real reorderable-list conflict. */
+    get _arrowNavActive() {
+        // Listbox has its own keyboard (on the search input) and supersedes the
+        // roving-tabindex arrow-nav — never run both.
+        if (this.type === 'listbox')
+            return false;
+        return this.arrowNavigation && !(this.reorderable && this.type === 'list');
+    }
+    /** Interactive, visible items — the roving stops. Non-interactive items (no
+     *  link/button) and hidden items are skipped. */
+    _getInteractiveItems() {
+        return this._getItems().filter((item) => !item.hasAttribute('hidden') && Boolean(item.href || item.button));
+    }
+    /** Push roving state onto the items, deferred to a microtask: _updateItems can
+     *  run inside the update lifecycle (firstUpdated/updated), and setting the
+     *  items' reactive state there would trip Lit's change-in-update warning.
+     *  Coalesced so repeated item updates schedule it only once. */
+    _updateRoving() {
+        if (this._rovingScheduled)
+            return;
+        this._rovingScheduled = true;
+        queueMicrotask(() => {
+            this._rovingScheduled = false;
+            this._applyRoving();
+        });
+    }
+    /** Sets the arrow-navigation flag on all items and a single roving entry point
+     *  (keep the current one if still valid, else the selected item, else the first
+     *  interactive item). */
+    _applyRoving() {
+        const active = this._arrowNavActive;
+        const items = this._getItems();
+        items.forEach((item) => { item._arrowNavigation = active; });
+        // Best-effort AT discoverability: role="list"/"navigation" doesn't imply
+        // arrow-key navigation the way listbox/menu would, so advertise the keys via
+        // aria-keyshortcuts (queryable) and a plain-language aria-description (surfaced
+        // when AT reaches the list). See the arrowNavigation JSDoc — known limitation.
+        if (active) {
+            this.setAttribute('aria-keyshortcuts', 'ArrowUp ArrowDown Home End');
+            this.setAttribute('aria-description', this._t('components.list.arrow-navigation-description-text'));
+        }
+        else {
+            this.removeAttribute('aria-keyshortcuts');
+            this.removeAttribute('aria-description');
+        }
+        if (!active) {
+            items.forEach((item) => { item._rovingActive = false; });
+            return;
+        }
+        const interactive = this._getInteractiveItems();
+        if (interactive.length === 0)
+            return;
+        const entry = interactive.find((item) => item._rovingActive)
+            ?? interactive.find((item) => item.selected)
+            ?? interactive[0];
+        items.forEach((item) => { item._rovingActive = item === entry; });
+    }
+    // items defaults to all items; _onArrowNav passes the interactive set it already
+    // computed (non-interactive items are kept out of roving, so they stay false).
+    _setRovingActive(activeItem, items = this._getItems()) {
+        items.forEach((item) => { item._rovingActive = item === activeItem; });
+    }
+    _onArrowNav(event) {
+        const { key } = event;
+        if (key !== 'ArrowUp' && key !== 'ArrowDown' && key !== 'Home' && key !== 'End')
+            return;
+        const items = this._getInteractiveItems();
+        if (items.length === 0)
+            return;
+        const current = items.findIndex((item) => item._rovingActive);
+        let next;
+        if (key === 'Home') {
+            next = 0;
+        }
+        else if (key === 'End') {
+            next = items.length - 1;
+        }
+        else {
+            const dir = key === 'ArrowDown' ? 1 : -1;
+            const base = current === -1 ? (dir === 1 ? -1 : 0) : current;
+            next = (base + dir + items.length) % items.length; // wrap around
+        }
+        event.preventDefault();
+        const target = items[next];
+        this._setRovingActive(target, items);
+        target.focus();
+    }
+    _warnArrowNav() {
+        if (!import.meta.env?.DEV)
+            return;
+        if (this.arrowNavigation && this.reorderable && this.type === 'list') {
+            console.warn('nldd-list: `arrow-navigation` and `reorderable` both use the arrow keys; `reorderable` wins and arrow-navigation is ignored.');
+        }
+        if (this._arrowNavActive) {
+            // Best-effort, light-DOM only: a slotted custom element (e.g. nldd-switch)
+            // keeps its focusable control in its own shadow root, so this query won't
+            // catch every extra control. Detecting custom elements generically would
+            // false-positive on non-interactive ones (nldd-icon, nldd-badge), so this
+            // stays a heuristic dev aid for the documented "simple lists" case.
+            const hasExtraControls = this._getInteractiveItems().some((item) => item.querySelector('a[href], button, input, select, textarea, [tabindex]') !== null);
+            if (hasExtraControls) {
+                console.warn('nldd-list: `arrow-navigation` is for simple lists, but a list-item has an extra focusable control (slotted) that will not be reachable as its own tab stop. Remove the control or disable arrow-navigation.');
+            }
+        }
+    }
     _getDeepActiveElement() {
         let active = document.activeElement;
         while (active?.shadowRoot?.activeElement) {
@@ -456,10 +910,37 @@ let NLDDList = class NLDDList extends LitElement {
         }));
     }
     render() {
-        return template(this._t('components.list.items-label-text'), this._hasHeader, this.type, this._isEmpty, this.emptyText || this._t('components.list.empty-text'), this.emptySupportingText);
+        return template({
+            itemsLabel: this.accessibleLabel || this._t('components.list.items-label-text'),
+            hasToolbar: this._hasToolbar,
+            type: this.type,
+            isEmpty: this._isEmpty,
+            emptyText: this.emptyText || this._t('components.list.empty-text'),
+            emptySupportingText: this.emptySupportingText,
+            listbox: {
+                listboxId: this._listboxId,
+                searchValue: this._searchValue,
+                activeId: this._searchFocused ? this._activeId : '',
+                searchPlaceholder: this._t('components.list.search-placeholder-text'),
+                searchAccessibleLabel: this.accessibleLabel || this._t('components.list.search-placeholder-text'),
+                searchClearLabel: this._t('components.list.search-clear-action'),
+                hasSearchBarEnd: this._hasSearchBarEnd,
+                onSearchInput: this._onSearchInput,
+                onSearchKeyDown: this._onSearchKeyDown,
+                onSearchFocus: this._onSearchFocus,
+                onSearchBlur: this._onSearchBlur,
+                onClearClick: this._onClearClick,
+                onSearchBarEndSlotChange: this._onSearchBarEndSlotChange,
+            },
+        });
     }
 };
 NLDDList.styles = [listStyles];
+/** Stable id for `.list__items` (the listbox), referenced by the input's
+ *  aria-controls. Per-instance, like nldd-combo-box's `_menuId`. */
+NLDDList._idCounter = 0;
+/** Counter for auto-assigned option ids (listbox mode). */
+NLDDList._optionIdCounter = 0;
 __decorate([
     property({ reflect: true })
 ], NLDDList.prototype, "variant", void 0);
@@ -475,12 +956,21 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true, attribute: 'no-dividers' })
 ], NLDDList.prototype, "noDividers", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'arrow-navigation' })
+], NLDDList.prototype, "arrowNavigation", void 0);
+__decorate([
+    property({ type: String, reflect: true })
+], NLDDList.prototype, "height", void 0);
 __decorate([
     property({ type: String, attribute: 'empty-text' })
 ], NLDDList.prototype, "emptyText", void 0);
 __decorate([
     property({ type: String, attribute: 'empty-supporting-text' })
 ], NLDDList.prototype, "emptySupportingText", void 0);
+__decorate([
+    property({ type: String, attribute: 'accessible-label' })
+], NLDDList.prototype, "accessibleLabel", void 0);
 __decorate([
     property({ type: Object })
 ], NLDDList.prototype, "translations", void 0);
@@ -489,11 +979,26 @@ __decorate([
 ], NLDDList.prototype, "_mergedTranslations", void 0);
 __decorate([
     state()
-], NLDDList.prototype, "_hasHeader", void 0);
+], NLDDList.prototype, "_hasToolbar", void 0);
+__decorate([
+    state()
+], NLDDList.prototype, "_hasSearchBarEnd", void 0);
 __decorate([
     state()
 ], NLDDList.prototype, "_isEmpty", void 0);
-NLDDList = __decorate([
+__decorate([
+    state()
+], NLDDList.prototype, "_searchValue", void 0);
+__decorate([
+    state()
+], NLDDList.prototype, "_activeId", void 0);
+__decorate([
+    state()
+], NLDDList.prototype, "_searchFocused", void 0);
+__decorate([
+    query('.list__search-field-input')
+], NLDDList.prototype, "_searchInput", void 0);
+NLDDList = NLDDList_1 = __decorate([
     customElement('nldd-list')
 ], NLDDList);
 export { NLDDList };