@nldd/design-system 0.8.82 → 0.8.84

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

@@ -14,6 +14,9 @@ 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';
+/** What the browser counts as a tab stop in a shadow root: focusable, enabled,
+ *  and not parked at a negative tabindex. */
+const SHADOW_TAB_STOP = ':is(a[href], button, input, select, textarea, [tabindex]):not([tabindex^="-"]):not(:disabled)';
 /**
  * A container for `nldd-list-item` elements.
  *
@@ -28,6 +31,16 @@ import '../../actions/icon-button/icon-button.js';
  *   spacer-cell per level. Comes with its own keyboard, see "Tree" below.
  * - `navigation` — host `role="navigation"`, items with `selected` get
  *   `aria-current="page"` on their inner `<a>` or `<button>`.
+ * - `form` — rows that are not actions themselves: the controls inside them
+ *   are. A row of a label and a field, a switch, a menu button, or a value you
+ *   cannot change at all. Semantically the same as `list` (`role="list"`,
+ *   `role="listitem"`), and everything visual is unchanged; what falls away is
+ *   the keyboard of a list you walk through. No arrow navigation, so no
+ *   promise of it either, and no tab stop on the row: Tab goes straight to the
+ *   controls, in source order, the way it does in any form. Rows that ARE
+ *   actions (`href`, `button`, `checkbox`, or a segment) contradict that and
+ *   warn in development. SwiftUI draws the same line between `List` and
+ *   `Form`, for the same reason.
  * - `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"`
@@ -38,6 +51,39 @@ import '../../actions/icon-button/icon-button.js';
  *
  * Selection state is consumer-managed: the list never mutates `selected` itself.
  *
+ * ### Keyboard
+ *
+ * A list you walk through answers to the arrow keys, and there is no attribute to
+ * switch that on. Whether the keys do something is not a property of one list: it
+ * is what a reader may assume about all of them, and a per-list setting made that
+ * unknowable from the outside. It follows the type, which you can see before you
+ * touch a key.
+ *
+ * - ArrowUp / ArrowDown — move focus between the rows there is something to do
+ *   with. A row of nothing but text is skipped, because focus that leads nowhere
+ *   is a dead end.
+ * - Home / End — the first / last of those rows.
+ * - Tab — the list is ONE tab stop, so Tab moves past it rather than through it.
+ *   Within the current row Tab walks that row's own controls: a chevron beside a
+ *   checkbox, a menu button at the end. The same controls in the other rows are
+ *   held out of the tab order (`tabindex="-1"`, or `no-tab` on a design-system
+ *   control that keeps its tab stop in its own shadow root), and so are this
+ *   row's once focus leaves the list, so tabbing back in lands on the row again.
+ * - Escape — out of a control the row holds, back onto the row. One level up,
+ *   where Shift+Tab is one step back. On the row itself the list claims nothing,
+ *   so Escape carries on to whatever holds the list, and a control showing a
+ *   menu keeps the first press for closing that menu.
+ *
+ * While focus sits in a control a row holds, the list stands down: those keys
+ * are the control's, and a list that took them anyway would pull focus out of a
+ * combo box or a text field mid-word. What the row IS — its own link, button or
+ * segments — keeps answering here.
+ *
+ * Arrows move focus only; selection stays consumer-managed. Three types answer
+ * differently, and all three say so on screen before you touch a key: a listbox
+ * runs its keyboard from its search field, a reorderable list moves rows with the
+ * arrows, and a form has no rows to move between at all.
+ *
  * ### Listbox
  *
  * In `type="listbox"` the list owns a native `<input role="combobox">` (mirroring
@@ -56,24 +102,23 @@ import '../../actions/icon-button/icon-button.js';
  * 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).
+ * first visible one. `reorderable` and the roving arrow keys are ignored in
+ * listbox mode (listbox has its own keyboard).
  *
  * ### Tree
  *
- * A tree is a composite widget, so it brings its own keyboard — `arrow-navigation`
- * is implied and needn't be set:
- * - ArrowDown / ArrowUp — move between the rows in the order they appear on
- *   screen, the rows of an open branch included.
- * - Home / End — first / last row.
+ * A tree adds to that keyboard, and counts the rows of an open branch as part of
+ * the order the arrows walk:
  * - ArrowRight — opens a closed branch; on an open one it steps to its first child.
  * - ArrowLeft — closes an open branch; on a leaf it steps out to the parent row.
- * - Enter / Space — open and close, the same as Right and Left. Only while focus
+ * - Enter — follows the row: its own link or button, or on a segmented branch the
+ *   first action that is not the chevron. A branch with only a chevron folds instead.
+ * - Space — open and close, the same as Right and Left. Only while focus
  *   sits on the row itself: a row that is its own control, and a segmented
  *   action you tabbed into, handle both keys themselves.
  *
  * Opening and closing runs through the row's own disclosure control — the
- * segmented action marked `disclosure`, or the row itself when it is a button.
+ * segment marked `disclosure`, or the row itself when it is a button.
  * The list activates that control rather than writing `expanded`, so the state
  * keeps being set in one place: the consumer's handler. A row that is a link is
  * never activated this way, since that would navigate away.
@@ -103,20 +148,17 @@ import '../../actions/icon-button/icon-button.js';
  * @element nldd-list
  *
  * @attr {'simple'|'box-tinted'|'box-base'} variant - Visual style (default 'simple'): `simple` is a plain vertical strip with no chrome, the two `box` values a framed card with rounded corners, fill and inset border ring. `box-tinted` for a list on a plain page, `box-base` for one on an already-tinted parent (the border ring gets +2 palette steps so it still reads against a card-on-card)
- * @attr {'list'|'navigation'|'listbox'|'tree'} type - A11y role and behavior (default 'list'). See the docblock above.
- * @attr {boolean} reorderable - Enables drag-to-reorder and pushes `reorderable` onto the items. Only valid with `type="list"`; wins over `arrow-navigation` when both are set.
+ * @attr {'list'|'navigation'|'listbox'|'tree'|'form'} type - A11y role and behavior (default 'list'). See the docblock above.
+ * @attr {boolean} reorderable - Enables drag-to-reorder and pushes `reorderable` onto the items. Only valid with `type="list"`; there the arrow keys move rows instead of focus.
  * @attr {'always'|'on-touch'|'never'} dividers - When to draw the lines between the items (default 'always'). `on-touch` draws them only where the primary input is touch, under `(pointer: coarse)`: a pointer has the hover highlight to tell one row from the next and a finger has nothing, so the line earns its place in the one case and is clutter in the other. `never` hides them everywhere
- * @attr {boolean} arrow-navigation - Roving-tabindex arrow-key navigation: ArrowUp/ArrowDown move focus between the rows, Home/End jump to first/last, and the list becomes a single tab stop. Implied by `type="tree"` (which adds ArrowLeft/ArrowRight, see above). Ignored when `reorderable` is active on a `type="list"`, and in listbox mode.
  * @attr {string} height - Listbox only: caps the options' scroll region at this CSS length (e.g. '320px'). Unset means no cap.
- * @attr {string} empty-text - Text for the default empty-state dialog (falls back to the Dutch i18n default). Ignored when `[slot=empty]` is filled.
- * @attr {string} empty-supporting-text - Supporting text for the default empty-state dialog. Ignored when `[slot=empty]` is filled.
  * @attr {string} accessible-label - Accessible name, forwarded to the list in `type="list"` and to the search field in `type="listbox"`. For `type="navigation"` set `aria-label` / `aria-labelledby` on the element itself. Falls back to the i18n default.
  * @attr {object} translations - Override translation keys; unset keys fall back to Dutch
  *
  * @slot        - List items (`nldd-list-item`)
  * @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 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.
+ * @slot empty - Shown when no items are visible (all `[hidden]` or none). Empty by default: what an empty list should say is the app's to write, so put an `nldd-inline-dialog` here. 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.
@@ -136,27 +178,6 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
          *  primary input is touch: a pointer has the hover highlight to tell one row
          *  from the next, and a finger has nothing. */
         this.dividers = 'always';
-        /**
-         * 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").
@@ -165,17 +186,6 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
          * outside listbox mode.
          */
         this.height = '';
-        /**
-         * Text for the default empty-state dialog. Falls back to the Dutch
-         * i18n default ("Geen items"). Ignored when consumers slot their
-         * own content into `[slot=empty]`.
-         */
-        this.emptyText = '';
-        /**
-         * Optional supporting text for the default empty-state dialog.
-         * 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
@@ -210,6 +220,7 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         // — Observers ————————————————————————————————————————————————————————————
         this._itemsObserver = null;
         this._contextScheduled = false;
+        this._warnedSilentEmpty = 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
@@ -236,7 +247,8 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
          *  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;
+            const slot = event.target;
+            queueMicrotask(() => { this._hasSearchBarEnd = slot.assignedElements().length > 0; });
         };
         this._onSearchFocus = () => {
             this._searchFocused = true;
@@ -310,6 +322,25 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
             this._setActiveOption(visible[next]);
         };
         this._rovingScheduled = false;
+        this._warnedActionRowInForm = false;
+        /**
+         * Whether the control the Escape came from had a popover open when the key
+         * went down. Read on the way in, because a control closes its own menu in its
+         * own handler and does not stop the key: by the time this list sees it on the
+         * way out, the menu is already gone and one press would do two levels at once.
+         */
+        this._popoverWasOpen = false;
+        this._onKeyDownCapture = (event) => {
+            if (event.key !== 'Escape' || !this._arrowNavActive)
+                return;
+            const origin = this._origin(event);
+            // Asked of the whole row rather than of the control the event came from:
+            // a popover can hang anywhere between the focused node and the row — under
+            // the control, beside it in the same cell — and missing one costs a level.
+            // The other way round costs a press, once, in a row that has an open menu
+            // and a second control you are typing in.
+            this._popoverWasOpen = !!origin?.control && !!origin.row.querySelector(':popover-open');
+        };
         this._onFocusIn = (event) => {
             if (!this._arrowNavActive)
                 return;
@@ -318,8 +349,40 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
             // click, or programmatic focus), so arrows continue from there.
             if (item && !item._rovingActive && this._getInteractiveItems().includes(item)) {
                 this._setRovingActive(item);
+                return;
             }
+            // Focus back on the row it was already on: hand its controls their stops
+            // again, since leaving the list parked them.
+            if (item?._rovingActive)
+                item._syncRovingTabStops();
         };
+        /**
+         * Focus gone from the list: park everything but the row.
+         *
+         * The stops a row hands out to its controls last as long as the row is the
+         * current one, so without this they are still there after you tab away, and
+         * Shift+Tab back in lands inside the control you left rather than on the row.
+         * A roving list is one stop from the outside; what is inside opens up once
+         * you are in. _onFocusIn puts them back.
+         *
+         * Deferred: focus moving between two controls of the same row fires focusout
+         * before focusin, and `relatedTarget` is retargeted at a shadow boundary, so
+         * the only reliable answer to "did focus leave" is the one you get after it
+         * has landed.
+         */
+        this._onFocusOut = () => {
+            if (!this._arrowNavActive)
+                return;
+            queueMicrotask(() => {
+                if (!this.isConnected || this._containsFocus())
+                    return;
+                this._getAllRows().forEach((row) => { row._parkControls(); });
+            });
+        };
+        /** Reported once per element: a list that gains rows would otherwise repeat
+         *  the same line on every change. */
+        this._warnedUnmanaged = new WeakSet();
+        this._unmanagedWarnScheduled = false;
         // — Drag: pointer ————————————————————————————————————————————————————————
         this._onPointerDown = (event) => {
             if (!this.reorderable || this.type !== 'list')
@@ -384,6 +447,10 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
             // Arrow-navigation and reorder both claim the arrow keys; _arrowNavActive
             // is false whenever reorderable wins, so the two never run together.
             if (this._arrowNavActive) {
+                if (event.key === 'Escape') {
+                    this._onEscape(event);
+                    return;
+                }
                 this._onArrowNav(event);
                 return;
             }
@@ -425,25 +492,46 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         };
     }
     // — Lifecycle ————————————————————————————————————————————————————————————
+    /**
+     * What the first render needs to know, read before it happens.
+     *
+     * All three of these used to be set in `firstUpdated`, from the slots in the
+     * shadow root. Setting reactive state there asks for a second render the
+     * moment the first one finished, which Lit reports on every page as "an
+     * update scheduled after an update completed". The same three answers are in
+     * the light DOM, which is there before the first render, so they are read
+     * from the children instead. The slotchange listeners below keep them true
+     * afterwards, and by then a second render is what you actually want.
+     */
+    willUpdate(changed) {
+        // Derived state belongs before the render that reads it. In `updated` the
+        // merge lands after the first render has finished, and asks for a second
+        // one on the spot.
+        if (changed.has('translations') || !this.hasUpdated) {
+            this._mergedTranslations = { ...nlddListTranslations, ...this.translations };
+        }
+        if (this.hasUpdated)
+            return;
+        this._updateEmpty();
+        this._hasToolbar = this.querySelector(':scope > [slot="toolbar"]') !== null;
+        this._hasSearchBarEnd = this.querySelector(':scope > [slot="search-bar-end"]') !== null;
+    }
     firstUpdated() {
+        // Deferred: the browser fires the first slotchange the moment this render
+        // commits, and state set there is an update scheduled on top of the one
+        // that just finished. willUpdate already read these from the light DOM, so
+        // the first event has nothing to add anyway; the later ones do.
         const slot = this.shadowRoot?.querySelector('slot:not([name])');
-        slot?.addEventListener('slotchange', () => {
+        slot?.addEventListener('slotchange', () => queueMicrotask(() => {
             this._updateItems();
             this._updateEmpty();
-        });
+        }));
         this._updateItems();
-        this._updateEmpty();
         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;
+        toolbarSlot?.addEventListener('slotchange', () => queueMicrotask(() => {
+            this._hasToolbar = toolbarSlot.assignedElements().length > 0;
+        }));
         // Watch for rows being added or removed, for `hidden` toggles on them
         // (consumer-driven filtering) and for branches opening and closing, since
         // all three change which row paints first and last. `subtree: true` is
@@ -460,7 +548,7 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
                     return m.target === this || isRow(m.target);
                 if (m.type !== 'attributes' || !isRow(m.target))
                     return false;
-                if (m.attributeName === 'expanded')
+                if (m.attributeName === 'expanded' || m.attributeName === 'disabled')
                     return true;
                 return m.attributeName === 'hidden'
                     && (m.target.parentElement === this || isRow(m.target.parentElement));
@@ -469,12 +557,13 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
                 return;
             this._updateItems();
             this._updateEmpty();
+            this._warnUnmanagedControls();
         });
         this._itemsObserver.observe(this, {
             childList: true,
             subtree: true,
             attributes: true,
-            attributeFilter: ['hidden', 'expanded'],
+            attributeFilter: ['hidden', 'expanded', 'disabled'],
         });
         this._applyHostType();
     }
@@ -488,22 +577,26 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         this.style.containerType = 'inline-size';
         this.style.containerName = 'cells-container';
         this.addEventListener('pointerdown', this._onPointerDown);
+        this.addEventListener('keydown', this._onKeyDownCapture, true);
         this.addEventListener('keydown', this._onKeyDown);
         this.addEventListener('focusin', this._onFocusIn);
+        this.addEventListener('focusout', this._onFocusOut);
         this.addEventListener('click', this._onListClick);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('pointerdown', this._onPointerDown);
+        this.removeEventListener('keydown', this._onKeyDownCapture, true);
         this.removeEventListener('keydown', this._onKeyDown);
         this.removeEventListener('focusin', this._onFocusIn);
+        this.removeEventListener('focusout', this._onFocusOut);
         this.removeEventListener('click', this._onListClick);
         this._itemsObserver?.disconnect();
         this._itemsObserver = null;
         this._cancelDrag();
     }
     updated(changed) {
-        if (changed.has('reorderable') || changed.has('type') || changed.has('arrowNavigation')) {
+        if (changed.has('reorderable') || changed.has('type')) {
             if (this.reorderable && this.type !== 'list' && import.meta.env?.DEV) {
                 console.warn('nldd-list: `reorderable` is only valid when type="list". Ignoring.');
             }
@@ -513,9 +606,6 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         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
@@ -638,6 +728,35 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
     _updateEmpty() {
         const items = this._getItems();
         this._isEmpty = items.length === 0 || items.every(item => item.hasAttribute('hidden'));
+        // Nothing in it and nothing said about that is not a thing on the page.
+        // Drawing the surface anyway makes "nothing" look different per variant:
+        // invisible on a plain list, an empty tinted bar on a boxed one, which
+        // reads as a skeleton that never loaded.
+        this.classList.toggle('is-blank', this._isEmpty && !this.querySelector(':scope > [slot="empty"]'));
+        this._warnSilentEmpty();
+    }
+    /**
+     * A list with nothing in it and nothing to say about that.
+     *
+     * There is no default text any more, because what an empty list means is
+     * the app's to write and a house sentence was wrong more often than right.
+     * That leaves a real risk of a blank area with nothing in the accessibility
+     * tree either, so the list asks the person building it rather than
+     * answering for them. A listbox before you have typed is left alone: an
+     * empty search is not an empty list.
+     */
+    _warnSilentEmpty() {
+        if (!import.meta.env?.DEV)
+            return;
+        if (!this._isEmpty || this._warnedSilentEmpty)
+            return;
+        if (this.type === 'listbox' && !this._searchValue)
+            return;
+        if (this.querySelector(':scope > [slot="empty"]'))
+            return;
+        this._warnedSilentEmpty = true;
+        console.warn('nldd-list: no items and nothing in [slot="empty"], so the list renders a blank area. '
+            + 'Put an nldd-inline-dialog in that slot saying what is not there and what the next move is.', this);
     }
     // — Listbox: active-option model ————————————————————————————————————————————
     /** Every option needs a stable id for aria-activedescendant. Assign one to
@@ -711,41 +830,49 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         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. */
+    /**
+     * Every list answers to the arrow keys. There is no switch for it, on purpose:
+     * whether the keys do something is not a property of one list, it is what a
+     * reader may assume about all of them, and a per-list setting made that
+     * unknowable from the outside.
+     *
+     * Two lists answer differently, and you can see which before you touch a key:
+     * a listbox has a search field and runs its own keyboard from there, and a
+     * reorderable list uses the arrows to move rows. The guard checks
+     * `type === 'list'` because reorderable is inert without it, so there is no
+     * conflict to resolve.
+     */
     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;
-        // A tree is a composite widget: role="tree" promises arrow keys, so it
-        // gets them without the consumer asking. Everywhere else arrow-nav stays
-        // opt-in, because a plain list is not a widget and Tab per row is fine.
-        if (this.type === 'tree')
-            return true;
-        return this.arrowNavigation && !(this.reorderable && this.type === 'list');
+        // A form's rows are not somewhere to go: the controls in them are, and Tab
+        // already reaches those. Arrow keys would be a promise with nothing behind
+        // it, and the tab stop they need on the row would sit in front of every
+        // field.
+        if (this.type === 'form')
+            return false;
+        return !(this.reorderable && this.type === 'list');
     }
     /** Interactive, painted rows — the roving stops, in the order they appear on
-     *  screen. Non-interactive rows (no link/button) and hidden ones are skipped.
+     *  screen. Rows with nothing to operate and hidden ones are skipped.
      *  Painted, not top-level: in a tree the rows of an open branch sit between
      *  the branch and the next top-level row, and arrows have to walk them too. */
     _getInteractiveItems() {
         const painted = this._getPaintedRows();
-        // In a tree every row is a stop, including one that only holds segmented
-        // actions: the row itself takes focus (that is where role="treeitem"
-        // sits) and Tab reaches the controls inside it.
+        // In a tree every row is a stop, including one that holds nothing at all:
+        // the row itself takes focus (that is where role="treeitem" sits), and a
+        // branch you cannot reach is a branch you cannot open.
         if (this.type === 'tree')
             return painted;
-        return painted.filter((row) => Boolean(row.href || row.button));
+        return painted.filter((row) => row._isRovingStop);
     }
     /** 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. */
+     *  Coalesced so repeated item updates schedule it only once.
+     *
+     *  @internal Also called by a row whose content changed after the stops were
+     *  picked. */
     _updateRoving() {
         if (this._rovingScheduled)
             return;
@@ -762,11 +889,22 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         const active = this._arrowNavActive;
         const rows = this._getAllRows();
         rows.forEach((row) => { row._arrowNavigation = active; });
+        const interactive = active ? this._getInteractiveItems() : [];
         // 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) {
+        // when AT reaches the list). See _arrowNavActive — known limitation.
+        // Only where the keys go somewhere: a list of nothing but text has no stops
+        // to move between, and promising keys that do nothing is worse than silence.
+        if (import.meta.env?.DEV && this.type === 'form' && !this._warnedActionRowInForm) {
+            const action = rows.find((row) => row.href || row.button || row.checkbox
+                || row.querySelector(':scope > nldd-list-item-segment'));
+            if (action) {
+                this._warnedActionRowInForm = true;
+                console.warn('nldd-list: type="form" says the rows are not actions and the controls inside them are, so its rows carry no keyboard of their own. This one is a link, a button, a checkbox or a set of segments, which contradicts that. Use type="list" for rows you activate, and put the action in a cell if it belongs to a form row.');
+            }
+        }
+        if (interactive.length > 0) {
             this.setAttribute('aria-keyshortcuts', 'ArrowUp ArrowDown Home End');
             this.setAttribute('aria-description', this._t('components.list.arrow-navigation-description-text'));
         }
@@ -778,7 +916,6 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
             rows.forEach((row) => { row._rovingActive = false; });
             return;
         }
-        const interactive = this._getInteractiveItems();
         if (interactive.length === 0)
             return;
         const entry = interactive.find((row) => row._rovingActive)
@@ -789,9 +926,8 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
             row._syncRovingTabStops();
         });
     }
-    // items defaults to every row, nested ones included; _onArrowNav passes the
-    // interactive set it already computed (non-interactive rows are kept out of
-    // roving, so they stay false).
+    // items defaults to every row, nested ones included. Callers that pass a
+    // narrower set take on clearing whatever is outside it themselves.
     _setRovingActive(activeItem, items = this._getAllRows()) {
         items.forEach((item) => {
             item._rovingActive = item === activeItem;
@@ -800,8 +936,36 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
             item._syncRovingTabStops();
         });
     }
+    /** Whether focus is anywhere in this list, shadow boundaries included. */
+    _containsFocus() {
+        // document.activeElement only ever names the outermost host, so the answer
+        // is a walk down the chain of active elements: at every level, is this the
+        // list or inside it.
+        let node = document.activeElement;
+        while (node) {
+            if (node === this || this.contains(node))
+                return true;
+            node = node.shadowRoot?.activeElement ?? null;
+        }
+        return false;
+    }
+    /** The row an event came from, and the control of that row it started in. */
+    _origin(event) {
+        const path = event.composedPath();
+        const row = path.find((el) => el instanceof Element && el.tagName.toLowerCase() === 'nldd-list-item');
+        if (!row)
+            return null;
+        return { row, control: row._slottedControlFor(path) };
+    }
     _onArrowNav(event) {
         const { key } = event;
+        // Hands off while focus is in a control the row holds. What those keys do
+        // is the control's business — a combo box moves its options with them, a
+        // text field its caret — and a list that takes them anyway pulls focus out
+        // of the control mid-word. The row itself, its own action and its segments
+        // are not controls it holds, so those keep answering here.
+        if (this._origin(event)?.control)
+            return;
         if (this.type === 'tree' && (key === 'ArrowRight' || key === 'ArrowLeft')) {
             this._onTreeHorizontal(event, key);
             return;
@@ -830,9 +994,38 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         }
         event.preventDefault();
         const target = items[next];
-        this._setRovingActive(target, items);
+        // Every row, not just the interactive ones: Escape can leave the flag on a
+        // row that holds a control but is no stop itself, and clearing only the
+        // stops would leave two rows claiming to be the current one.
+        this._setRovingActive(target);
         target.focus();
     }
+    /**
+     * Escape: out of a control, back onto the row that holds it.
+     *
+     * One level up, not one step back. Shift+Tab retraces the order and lands on
+     * whatever came before, which is the row only from the first control of a
+     * row; from the second it is the first. This is the move that works wherever
+     * you are in the row, and it puts the arrow keys back in reach.
+     *
+     * It claims Escape at exactly this one level. On the row it claims nothing,
+     * so Escape carries on to whatever holds the list — a sheet, a dialog, or
+     * nothing at all. And a control showing a popover keeps it: that menu is the
+     * topmost thing you opened, so it is what the first Escape closes.
+     */
+    _onEscape(event) {
+        const hadPopover = this._popoverWasOpen;
+        this._popoverWasOpen = false;
+        const origin = this._origin(event);
+        if (!origin?.control)
+            return;
+        if (hadPopover)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        this._setRovingActive(origin.row);
+        origin.row.focus();
+    }
     /** Tree only: Right opens a closed branch and steps into an open one, Left
      *  closes an open branch and steps out of a leaf. Opening and closing runs
      *  through the row's own disclosure control, so `expanded` keeps being
@@ -866,10 +1059,17 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         event.preventDefault();
         this._moveRovingTo(parent);
     }
-    /** Tree only: Enter and Space open and close the row, the same thing Right and
-     *  Left do. Only when focus sits on the row ITSELF — a row that is its own
-     *  control, and a segmented action you tabbed into, handle both keys
-     *  natively, and acting here as well would toggle twice. */
+    /**
+     * Tree only, and only while focus sits on the row ITSELF: a row that is its
+     * own control, and a segment you tabbed into, handle both keys
+     * natively, and acting here as well would fire twice.
+     *
+     * Enter does what the row is for — it follows the row's own link or button,
+     * or on a branch cut into segments the first one that is not the chevron.
+     * Space folds, the same thing Right and Left do, because a chevron is a
+     * button and Space is what a button answers to. A branch with nothing but a
+     * chevron takes Enter for folding too, so the key is never dead.
+     */
     _onTreeActivate(event) {
         const target = event.target;
         if (!(target instanceof Element) || target.tagName.toLowerCase() !== 'nldd-list-item')
@@ -877,6 +1077,10 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
         const row = target;
         if (row.shadowRoot?.activeElement)
             return;
+        if (event.key === 'Enter' && row._activatePrimary()) {
+            event.preventDefault();
+            return;
+        }
         if (row._activateDisclosure())
             event.preventDefault();
     }
@@ -887,23 +1091,69 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
     _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.hasAttribute('arrow-navigation')) {
+            console.warn('nldd-list: `arrow-navigation` is the default now and the attribute does nothing; remove it.');
         }
-        // A tree row is meant to hold more than one control (a chevron beside a
-        // checkbox); there Tab walks the current row, so the warning below would
-        // be noise.
-        if (this._arrowNavActive && this.type !== 'tree') {
-            // 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.');
+        this._warnUnmanagedControls();
+    }
+    /**
+     * A control the row cannot reach: a custom element that keeps its tab stop in
+     * its own shadow root and has no `no-tab` to close it. Such a control stays a
+     * tab stop in EVERY row, which is exactly what the roving promises it is not,
+     * and the row does not even count as a stop for the arrow keys.
+     *
+     * Deferred, and re-run whenever the rows change. A slotted custom element has
+     * its shadow root the moment it connects, but Lit renders the content on the
+     * first update, so a check that runs in `firstUpdated` looks into an empty
+     * shadow root and finds nothing to warn about. Waiting for the element to be
+     * defined is not enough either: it has to have rendered.
+     */
+    _warnUnmanagedControls() {
+        if (!import.meta.env?.DEV || !this._arrowNavActive)
+            return;
+        if (this._unmanagedWarnScheduled)
+            return;
+        this._unmanagedWarnScheduled = true;
+        const check = async () => {
+            this._unmanagedWarnScheduled = false;
+            const rows = this._getPaintedRows();
+            await Promise.all(rows.map((row) => row.updateComplete));
+            for (const row of rows) {
+                for (const el of Array.from(row.querySelectorAll('*'))) {
+                    if (el.closest('nldd-list-item') !== row)
+                        continue;
+                    // A segment is managed over its own channel (`_tabbable`), so it
+                    // needs no `no-tab`.
+                    if (el.tagName.toLowerCase() === 'nldd-list-item-segment')
+                        continue;
+                    if (!el.tagName.includes('-') || 'noTab' in el)
+                        continue;
+                    if (this._warnedUnmanaged.has(el))
+                        continue;
+                    const upgraded = el;
+                    if (upgraded.updateComplete)
+                        await upgraded.updateComplete;
+                    if (!el.shadowRoot?.querySelector(SHADOW_TAB_STOP))
+                        continue;
+                    // Nothing hidden on the way from the row: a menu item in a closed
+                    // menu is no tab stop of the row's, and the component that hides it
+                    // runs its own focus. Computed style, not checkVisibility(): that one
+                    // needs a laid-out box and answers false until the first layout.
+                    if (this._hiddenWithin(row, el))
+                        continue;
+                    this._warnedUnmanaged.add(el);
+                    console.warn(`nldd-list: <${el.tagName.toLowerCase()}> in a list-item keeps its tab stop in its own shadow root and has no \`no-tab\`, so the row cannot take it out of the tab order and the arrow keys skip that row. If the rows of this list are not actions themselves, it is a form: set type="form" and the roving falls away. Otherwise give the component \`no-tab\`, or wrap the control in an nldd-list-item-segment.`);
+                }
             }
+        };
+        void check();
+    }
+    _hiddenWithin(row, el) {
+        for (let node = el; node && node !== row; node = node.parentElement) {
+            if (getComputedStyle(node).display === 'none')
+                return true;
         }
+        return false;
     }
     _getDeepActiveElement() {
         let active = document.activeElement;
@@ -1063,8 +1313,6 @@ let NLDDList = NLDDList_1 = class NLDDList extends LitElement {
             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,
@@ -1101,18 +1349,9 @@ __decorate([
 __decorate([
     property({ reflect: true, converter: reflectNonDefault('always') })
 ], NLDDList.prototype, "dividers", 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({ reflect: true, attribute: 'empty-text', converter: reflectNonDefault('') })
-], NLDDList.prototype, "emptyText", void 0);
-__decorate([
-    property({ reflect: true, attribute: 'empty-supporting-text', converter: reflectNonDefault('') })
-], NLDDList.prototype, "emptySupportingText", void 0);
 __decorate([
     property({ type: String, attribute: 'accessible-label' })
 ], NLDDList.prototype, "accessibleLabel", void 0);