@nldd/design-system 0.8.64 → 0.8.66

package/dist/components/inputs/token-field/token-field.js

@@ -0,0 +1,889 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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 NLDDTokenField_1;
+/**
+ * Nederlandse Digitale Dienst Token Field Component (Lit + TypeScript)
+ *
+ * A multi-select input that looks like a normal input field: chosen values show
+ * as dismissible tokens in a wrapping row, followed by an inline text input that
+ * stretches to fill the remaining space and wraps to a new line (growing the
+ * field) when it no longer fits. Options are supplied as a slotted nldd-menu,
+ * exactly like nldd-combo-box; the menu filters as you type, with a chevron picker
+ * button, arrow-key roving across the tokens and ElementInternals form participation.
+ *
+ * @element nldd-token-field
+ * @attr {string}   values           - Initial token values as a comma-separated string
+ *                                     (e.g. "nl, be, de"). Not reflected; the live value is
+ *                                     the `.values` array property. Values can't contain commas.
+ * @attr {string}   placeholder      - Placeholder shown in the input
+ * @attr {string}   type             - Input type forwarded to the inner input (e.g. 'email')
+ * @attr {string}   autocomplete     - Autocomplete hint forwarded to the inner input
+ * @attr {string}   accessible-label - Accessible label forwarded as aria-label to the input
+ * @attr {boolean}  allow-custom     - Allow free-typed values (not just menu options)
+ * @attr {boolean}  valid            - Marks the field valid (shows the valid icon)
+ * @attr {boolean}  invalid          - Marks the field invalid (shows the invalid icon)
+ * @attr {boolean}  no-spellcheck    - Disables browser spellchecking on the inner input
+ * @attr {boolean}  readonly         - Readonly: static tokens, no input/picker, read-only surface
+ * @attr {boolean}  required         - Marks the field required (invalid when it has no tokens)
+ * @attr {boolean}  disabled         - Disabled state
+ * @attr {string}   token-control    - Trailing control per token: 'dismiss' (default, a ✕ that removes it) or 'menu' (a ⌄ opening a per-token action menu supplied by the template prototypes)
+ * @attr {string}   name             - Name for form submission
+ * @attr {object}   translations     - Override translation keys; unset keys fall back to Dutch
+ *
+ * @slot - An nldd-menu with nldd-menu-item options; each item's `value`/`text`
+ *         supplies a token's value and its display label.
+ * @slot template - `nldd-token` prototypes supplying each token's action menu when
+ *                  token-control="menu": a keyless one is the shared default, a
+ *                  `data-value="X"` one overrides value X. Only the prototype's nested
+ *                  `nldd-menu` is used today; its other props are ignored.
+ *
+ * @fires change - When the selected values change; detail: { values: string[] }
+ * @fires input  - When the input text changes; detail: { value: string }
+ * @fires token-action - When a token's menu action is chosen (token-control="menu"); detail: { value: string, action: string }
+ */
+import { LitElement } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { tokenFieldStyles } from './token-field.styles.js';
+import { tokenFieldTemplate } from './token-field.template.js';
+import { nlddTokenFieldTranslations } from './token-field.i18n.js';
+import '../../actions/menu/menu.js';
+let NLDDTokenField = NLDDTokenField_1 = class NLDDTokenField extends LitElement {
+    constructor() {
+        super(...arguments);
+        this._internals = this.attachInternals();
+        this._initialValues = [];
+        this._values = [];
+        this.placeholder = '';
+        /** Input type forwarded to the inner input (e.g. 'email' for the right mobile
+         *  keyboard). Values are still handled as plain strings. */
+        this.type = 'text';
+        this.autocomplete = '';
+        this.accessibleLabel = '';
+        /** Allow committing free-typed values (not just menu options): a typed value
+         *  becomes a token on Enter, a trailing comma, or blur. Also governs whether
+         *  the input stays visible when no options remain. */
+        this.allowCustom = false;
+        this.valid = false;
+        this.invalid = false;
+        this.noSpellcheck = false;
+        /** Readonly: shows the tokens as static (no dismiss control, no input, no
+         *  picker) with the read-only surface treatment. */
+        this.readonly = false;
+        this.required = false;
+        this.disabled = false;
+        /** Trailing control on each token: 'dismiss' shows a ✕ that removes it; 'menu'
+         *  shows a ⌄ that opens a per-token action menu built from the `token-menu`
+         *  template. Choosing an action fires `token-action` for the app to handle. */
+        this.tokenControl = 'dismiss';
+        this.name = '';
+        this.translations = {};
+        /** The current text in the inline input; drives the menu filter. */
+        this._text = '';
+        /** Whether the option menu is currently open (drives aria-expanded). */
+        this._isOpen = false;
+        /** ID of the highlighted menu item, mirrored to aria-activedescendant. */
+        this._highlightedId = '';
+        /** Which token carries the roving tabindex — the token group's single tab stop
+         *  when the input is hidden (all values in, no custom, no options left). */
+        this._rovingIndex = 0;
+        this._menuId = `nldd-token-field-menu-${NLDDTokenField_1._idCounter++}`;
+        this._menu = null;
+        this._resizeObserver = null;
+        /** Watches the slotted menu for options added/removed after the initial slot
+         *  change (e.g. a framework populating them asynchronously), so the field
+         *  re-evaluates whether to show the input/picker and re-resolves token labels. */
+        this._menuObserver = null;
+        /** Watches the light-DOM `[slot="template"]` prototypes for changes (menu items,
+         *  their attributes, or an added/removed prototype) and invalidates the cloned
+         *  per-token menus so they re-clone. These components run on live sites, not just
+         *  static demos, so the prototypes can change at runtime. */
+        this._templateObserver = null;
+        /** True between a picker pointerdown-while-open and its trailing click, so the
+         *  click (which follows the native light-dismiss) doesn't reopen the menu. */
+        this._pickerPointerdownWhileOpen = false;
+        /** The index a token was just removed from through a field interaction (its ✕, a
+         *  menu action the app handled, or Backspace/Delete). Set at the interaction — when
+         *  focus is still reliably in the field, unlike at willUpdate time after a closing
+         *  menu has moved it — and consumed in updated() to focus the token that shifted in
+         *  (or the input). Null for background/programmatic value changes. */
+        this._removalFocusIndex = null;
+        /** When focus leaves the field entirely, reset the roving tab stop to the first
+         *  token, so tabbing back in from a preceding component always starts there.
+         *  Deferred a microtask because focusout fires before the matching focusin, so
+         *  the incoming focus target has settled by the time this runs. A focused token
+         *  (or the slotted menu) retargets document.activeElement to a node the field
+         *  contains, so moves within the field don't reset. */
+        this._handleFocusOut = () => {
+            queueMicrotask(() => {
+                if (this.isConnected && !this.contains(document.activeElement))
+                    this._rovingIndex = 0;
+            });
+        };
+        /** Cloned action menu per value, so each token's menu stays stable across
+         *  re-renders (a fresh clone every render would drop its open/focus state). Pruned
+         *  when a value leaves; see willUpdate. */
+        this._tokenMenuCache = new Map();
+        this._handleScrollOrResize = () => {
+            if (!this._isOpen)
+                return;
+            this._updateMenuWidth();
+            this._menu?.reposition();
+        };
+        this._handleMenuToggle = (e) => {
+            this._isOpen = e.newState === 'open';
+            if (!this._isOpen) {
+                this._highlightedId = '';
+            }
+            else {
+                requestAnimationFrame(() => {
+                    // The menu clears its highlight on open; seat it on the first option
+                    // by default so that option is the active descendant and Enter picks
+                    // it — unless something is already highlighted.
+                    if (this._menu && !this._menu.getHighlighted())
+                        this._menu.moveHighlight('next');
+                    this._updateActiveDescendant();
+                });
+            }
+        };
+        this._handleMenuSelect = (e) => {
+            const item = e.target;
+            this._commitValue(item.value || item.text);
+        };
+        /**
+         * Tab inside the menu (a top-layer popover) would move focus to an arbitrary
+         * next element in DOM order. Instead close the menu and return focus to the
+         * input so Tab continues from there — same handling as the combo-box.
+         */
+        this._handleMenuKeydown = (e) => {
+            if (e.key !== 'Tab')
+                return;
+            e.preventDefault();
+            this._closeMenu();
+            this._input?.focus();
+        };
+    }
+    // Property order matches the story controls (values kept high, above
+    // placeholder, per the text-field convention). No `size` axis yet — the field
+    // is md-only for now; a sm variant lands later.
+    /** Selected token values. The attribute is a comma-separated string used to seed
+     *  the initial values (like native `<input value>`); it is not reflected, so the
+     *  live source is always the `.values` array property. Values can't contain
+     *  commas — set those via the property. */
+    get values() {
+        return this._values;
+    }
+    set values(next) {
+        // A multi-select holds a *set* of values. Dedupe on every assignment so the
+        // keyed token render can never get a duplicate key (which silently drops a
+        // token) and the submitted form value stays one entry per value.
+        const unique = next ? next.filter((v, i) => next.indexOf(v) === i) : [];
+        const old = this._values;
+        this._values = unique;
+        this.requestUpdate('values', old);
+    }
+    _t(key) {
+        return this.translations[key] ?? nlddTokenFieldTranslations[key];
+    }
+    // — Lifecycle ————————————————————————————————————————————————————————————
+    connectedCallback() {
+        super.connectedCallback();
+        this._resizeObserver = new ResizeObserver(() => this._updateMenuWidth());
+        this._resizeObserver.observe(this);
+        window.addEventListener('scroll', this._handleScrollOrResize, true);
+        window.addEventListener('resize', this._handleScrollOrResize);
+        this.addEventListener('focusout', this._handleFocusOut);
+        this._templateObserver = new MutationObserver((records) => this._onTemplateMutation(records));
+        this._templateObserver.observe(this, {
+            childList: true, subtree: true, attributes: true, characterData: true,
+        });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this._resizeObserver?.disconnect();
+        this._resizeObserver = null;
+        this._menuObserver?.disconnect();
+        this._menuObserver = null;
+        this._templateObserver?.disconnect();
+        this._templateObserver = null;
+        window.removeEventListener('scroll', this._handleScrollOrResize, true);
+        window.removeEventListener('resize', this._handleScrollOrResize);
+        this.removeEventListener('focusout', this._handleFocusOut);
+        if (this._menu) {
+            this._menu.removeEventListener('toggle', this._handleMenuToggle);
+            this._menu.removeEventListener('select', this._handleMenuSelect);
+            this._menu.removeEventListener('keydown', this._handleMenuKeydown);
+            this._menu = null;
+        }
+    }
+    firstUpdated() {
+        this._initialValues = [...this.values];
+        this._updateFormValue();
+        // Give the host a lasting accessible name and grouping via ElementInternals.
+        // The input carries aria-label, but it is removed when every value is chosen
+        // (no custom, no options left) — exactly the state roving token navigation
+        // makes a first-class tab stop — so without this the field would lose its name.
+        this._internals.role = 'group';
+        this._internals.ariaLabel = this.accessibleLabel || null;
+    }
+    willUpdate(changed) {
+        // React to a values change BEFORE render, so the reactive state this
+        // touches (_highlightedId, via _syncMenuItems' active-descendant sync when
+        // hiding a token's highlighted option moves the highlight) folds into this
+        // same update. The identical work in updated() sets state after the update
+        // completed, which trips Lit's change-in-update warning.
+        //
+        // A token added or removed changes which options are still available:
+        // re-run the text filter (unhides options freed by a removed token) and
+        // re-hide the ones now selected. Close the menu if nothing is left to add.
+        if (changed.has('values')) {
+            this._rovingIndex = Math.max(0, Math.min(this._rovingIndex, this.values.length - 1));
+            for (const key of [...this._tokenMenuCache.keys()]) {
+                if (!this.values.includes(key))
+                    this._tokenMenuCache.delete(key);
+            }
+            this._updateFormValue();
+            if (this._menu) {
+                this._syncMenuItems();
+                if (!this._showInput)
+                    this._closeMenu();
+            }
+        }
+        if (changed.has('required'))
+            this._updateValidity();
+        if (changed.has('readonly') && this.readonly)
+            this._closeMenu();
+        if (changed.has('accessibleLabel'))
+            this._internals.ariaLabel = this.accessibleLabel || null;
+    }
+    updated() {
+        // The input narrows/widens as tokens come and go; keep the open menu's
+        // pinned width in step with it. This reads layout (getBoundingClientRect),
+        // so it must run after render, not in willUpdate().
+        if (this._isOpen)
+            this._updateMenuWidth();
+        // Keep focus in the field after a token was removed while it held focus.
+        // Deferred past this update: _focusAfterRemoval sets _rovingIndex (to move the
+        // roving tab stop), which must schedule its own update rather than mutate state
+        // mid-update (Lit's change-in-update warning).
+        if (this._removalFocusIndex !== null) {
+            const index = this._removalFocusIndex;
+            this._removalFocusIndex = null;
+            void this.updateComplete.then(() => this._focusAfterRemoval(index));
+        }
+    }
+    // — Form participation ————————————————————————————————————————————————————
+    /** Submit one entry per value under `name` (like a multi-select), so a form
+     *  receives `name=value` repeated for each token. */
+    _updateFormValue() {
+        const data = new FormData();
+        for (const value of this.values)
+            data.append(this.name, value);
+        this._internals.setFormValue(this.name ? data : null);
+        this._updateValidity();
+    }
+    /** A required field with no tokens is invalid (valueMissing). */
+    _updateValidity() {
+        if (this.required && this.values.length === 0) {
+            this._internals.setValidity({ valueMissing: true }, this._t('components.token-field.required-error-text'), this._input ?? this);
+        }
+        else {
+            this._internals.setValidity({});
+        }
+    }
+    formResetCallback() {
+        this.values = [...this._initialValues];
+    }
+    formDisabledCallback(disabled) {
+        this.disabled = disabled;
+    }
+    get _input() {
+        return this.shadowRoot?.querySelector('.token-field__input') ?? null;
+    }
+    /** The input + picker wrapper — the menu's anchor, so the menu lines up under
+     *  the whole area (including the picker), not just the input. */
+    get _inputArea() {
+        return this.shadowRoot?.querySelector('.token-field__input-area') ?? null;
+    }
+    /** Programmatic focus goes to the inner input, or — when it is hidden (all values
+     *  in, no custom, no options left) — to the token holding the roving tabindex. */
+    focus(options) {
+        if (this._input)
+            this._input.focus(options);
+        else
+            this._focusTokenAt(this._rovingIndex);
+    }
+    /** A token's display label: the matching slotted menu-item's text, else the
+     *  raw value (covers values whose option is not currently present). */
+    /** Slotted menu options not yet selected — what the picker could still add. */
+    get _availableOptionCount() {
+        let n = 0;
+        // Scope to the options menu (a direct-child nldd-menu); this deliberately
+        // skips nldd-menu-items inside the token-menu template prototypes.
+        for (const el of this.querySelectorAll(':scope > nldd-menu nldd-menu-item')) {
+            const item = el;
+            const v = item.value || item.text; // property, not attribute: consumers (Vue) set the property
+            if (v && !this.values.includes(v))
+                n++;
+        }
+        return n;
+    }
+    /** Hide the input entirely when there is nothing left to do: no options remain
+     *  and free text is not allowed. Readonly fields never show the input. */
+    get _showInput() {
+        return !this.readonly && (this.allowCustom || this._availableOptionCount > 0);
+    }
+    /** Whether an options menu is slotted — drives the picker button. Free-text-only
+     *  fields (e.g. e-mail addresses) have no menu and get no picker. */
+    get _hasMenu() {
+        return this._menu !== null;
+    }
+    /** Show the picker only while there are still options left to pick. Once every
+     *  menu item sits in the field there is nothing to open, so it disappears.
+     *  Readonly fields never show the picker. */
+    get _showPicker() {
+        return !this.readonly && this._hasMenu && this._availableOptionCount > 0;
+    }
+    _labelFor(value) {
+        // Scope to the options menu (a direct-child nldd-menu); this deliberately
+        // skips nldd-menu-items inside the token-menu template prototypes.
+        for (const el of this.querySelectorAll(':scope > nldd-menu nldd-menu-item')) {
+            const item = el;
+            if ((item.value || item.text) === value) {
+                return item.text || item.textContent?.trim() || value;
+            }
+        }
+        return value;
+    }
+    /** The action menu for a value's token (token-control="menu"): a clone of the
+     *  matching `nldd-token[slot="template"][data-value]` prototype's `nldd-menu`, else
+     *  the shared keyless prototype's. Cloned once per value and reused. Only the
+     *  prototype's nested menu is read today; its other props are ignored. */
+    _tokenMenuFor(value) {
+        const cached = this._tokenMenuCache.get(value);
+        if (cached)
+            return cached;
+        const clone = this._cloneTokenMenu(value);
+        if (clone)
+            this._tokenMenuCache.set(value, clone);
+        return clone;
+    }
+    _cloneTokenMenu(value) {
+        let shared = null;
+        let match = null;
+        for (const proto of this.querySelectorAll('nldd-token[slot="template"]')) {
+            if (proto.dataset.value === value) {
+                match = proto;
+                break;
+            }
+            if (!proto.hasAttribute('data-value'))
+                shared ?? (shared = proto);
+        }
+        const source = (match ?? shared)?.querySelector('nldd-menu[slot="menu"]');
+        return source ? source.cloneNode(true) : null;
+    }
+    /** A change to any `[slot="template"]` prototype (its menu items, their attributes,
+     *  or an added/removed prototype) invalidates the cloned per-token menus, so they
+     *  re-clone on the next render. The field only ever *reads* the prototypes — it
+     *  mutates the options menu and its own shadow DOM — so filtering to template-scoped
+     *  mutations keeps this from looping with the field's own option hiding. */
+    _onTemplateMutation(records) {
+        const touchesTemplate = records.some((r) => {
+            if (r.target.closest?.('[slot="template"]'))
+                return true;
+            return [...r.addedNodes, ...r.removedNodes].some((n) => n.nodeType === Node.ELEMENT_NODE && n.matches?.('[slot="template"]'));
+        });
+        if (!touchesTemplate)
+            return;
+        this._tokenMenuCache.clear();
+        this.requestUpdate();
+    }
+    _addValue(value) {
+        if (!value || this.values.includes(value))
+            return; // dedupe
+        this.values = [...this.values, value];
+        this._emitChange();
+    }
+    _removeValue(value) {
+        if (!this.values.includes(value))
+            return;
+        this.values = this.values.filter((v) => v !== value);
+        this._emitChange();
+    }
+    _emitChange() {
+        this.dispatchEvent(new CustomEvent('change', {
+            detail: { values: [...this.values] },
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    // — Input handlers ———————————————————————————————————————————————————————
+    _handleInput(e) {
+        this._text = e.target.value;
+        // A comma commits the text before it as a token (typed or pasted) — the
+        // Enter-equivalent for free text. Only meaningful with custom values.
+        if (this.allowCustom && this._text.includes(',')) {
+            this._commitCommaSeparated();
+            return;
+        }
+        this._syncMenuItems();
+        if (!this._isOpen)
+            this._openMenu();
+        this.dispatchEvent(new CustomEvent('input', {
+            detail: { value: this._text },
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    /** Split the input on commas: every complete segment becomes a token; the
+     *  trailing segment (after the last comma) stays in the input to keep typing.
+     *  Emits a single change for the batch. */
+    _commitCommaSeparated() {
+        const parts = this._text.split(',');
+        const remainder = parts.pop() ?? '';
+        const next = [...this.values];
+        for (const part of parts) {
+            const value = part.trim();
+            if (value && !next.includes(value))
+                next.push(value);
+        }
+        if (next.length !== this.values.length) {
+            this.values = next;
+            this._emitChange();
+        }
+        this._text = remainder;
+        if (this._input)
+            this._input.value = remainder;
+        this._syncMenuItems();
+        this.dispatchEvent(new CustomEvent('input', {
+            detail: { value: this._text },
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    /** Close the menu when focus leaves the field for anything but the menu. */
+    _handleBlur(e) {
+        const related = e.relatedTarget;
+        if (related && this._menu?.contains(related))
+            return;
+        // Commit any free-typed text when focus leaves, so a value typed without
+        // pressing Enter/comma isn't silently dropped — it becomes a visible token
+        // and joins the form value. Only with custom values allowed; commit without
+        // re-focusing so the focus move isn't fought. `_commitValue` closes the
+        // menu, so only close it ourselves when nothing was committed.
+        if (this.allowCustom && this._text.trim())
+            this._commitValue(this._text.trim(), false);
+        else
+            this._closeMenu();
+    }
+    _handleKeydown(e) {
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                if (!this._isOpen) {
+                    this._syncMenuItems();
+                    this._openMenu();
+                }
+                else {
+                    this._menu?.moveHighlight('next');
+                    this._updateActiveDescendant();
+                }
+                break;
+            case 'ArrowUp':
+                if (!this._isOpen)
+                    return;
+                e.preventDefault();
+                this._menu?.moveHighlight('prev');
+                this._updateActiveDescendant();
+                break;
+            case 'Enter': {
+                // A highlighted option wins; otherwise commit the typed text as a
+                // custom token. Works whether the menu is open or not — with no
+                // matching options the menu is closed, but Enter should still add
+                // the free-text value. preventDefault only when we actually act, so
+                // a no-op Enter can still submit an enclosing form.
+                const highlighted = this._isOpen ? (this._menu?.getHighlighted() ?? null) : null;
+                if (highlighted) {
+                    e.preventDefault();
+                    highlighted.select(); // routes through _handleMenuSelect
+                }
+                else if (this.allowCustom && this._text.trim()) {
+                    e.preventDefault();
+                    this._commitValue(this._text.trim());
+                }
+                break;
+            }
+            case 'Escape':
+                if (!this._isOpen)
+                    return;
+                e.preventDefault();
+                this._closeMenu();
+                break;
+            case 'ArrowLeft':
+                // At the very start of the input, step left into the tokens.
+                if (this._caretAtStart() && this._tokens.length > 0) {
+                    e.preventDefault();
+                    this._focusTokenAt(this._tokens.length - 1);
+                }
+                break;
+            case 'Backspace':
+                // Empty input: step focus onto the last token first; a second
+                // Backspace (now on the focused token) deletes it.
+                if (this._text === '' && this._tokens.length > 0) {
+                    e.preventDefault();
+                    this._focusTokenAt(this._tokens.length - 1);
+                }
+                break;
+        }
+    }
+    _caretAtStart() {
+        const input = this._input;
+        if (!input)
+            return false;
+        // type="email" / "number" etc. don't expose a caret (selectionStart is null),
+        // so an empty value is the only reliable "at the start" signal for those.
+        if (input.selectionStart === null)
+            return input.value === '';
+        return input.selectionStart === 0 && input.selectionEnd === 0;
+    }
+    // — Token roving navigation ————————————————————————————————————————————————
+    get _tokens() {
+        return Array.from(this.shadowRoot?.querySelectorAll('nldd-token') ?? []);
+    }
+    /** Focus the token at `index` (clamped); focus the input when there are none. */
+    _focusTokenAt(index) {
+        const tokens = this._tokens;
+        if (tokens.length === 0) {
+            this._input?.focus();
+            return;
+        }
+        const clamped = Math.max(0, Math.min(index, tokens.length - 1));
+        this._rovingIndex = clamped;
+        tokens[clamped].focus();
+    }
+    /** After removing the token at `index`, move focus to the token that shifted into
+     *  its slot (the one that was to its right). If the last token was removed, hand
+     *  focus to the input, or to the new last token when the input is hidden. */
+    _focusAfterRemoval(index) {
+        if (this._tokens.length === 0) {
+            this._input?.focus();
+            return;
+        }
+        if (index < this._tokens.length)
+            this._focusTokenAt(index);
+        else if (this._showInput)
+            this._input?.focus();
+        else
+            this._focusTokenAt(this._tokens.length - 1);
+    }
+    /** Arrow keys move between tokens; ArrowRight past the last returns to the
+     *  input; Backspace/Delete removes the token and steps focus onto the next one.
+     *  A disabled field is inert — no roving, no keyboard removal. */
+    _handleTokenKeydown(e, index) {
+        if (this.disabled)
+            return;
+        switch (e.key) {
+            case 'ArrowLeft':
+                e.preventDefault();
+                this._focusTokenAt(index - 1);
+                break;
+            case 'ArrowRight':
+                e.preventDefault();
+                if (index >= this._tokens.length - 1)
+                    this._input?.focus();
+                else
+                    this._focusTokenAt(index + 1);
+                break;
+            case 'Home':
+                e.preventDefault();
+                this._focusTokenAt(0);
+                break;
+            case 'End':
+                e.preventDefault();
+                this._focusTokenAt(this._tokens.length - 1);
+                break;
+            case 'Backspace':
+            case 'Delete':
+                // Remove the token and mark its slot; updated() then steps focus onto the
+                // token that took this one's place (or the input), so repeated Backspace
+                // walks the row and focus never drops to the body.
+                e.preventDefault();
+                this._removeValue(this.values[index]);
+                this._removalFocusIndex = index;
+                break;
+        }
+    }
+    /** Clicking empty space in the field (not a token or the picker) focuses the
+     *  input, or — when it is hidden — the last token, so a click after the tokens
+     *  lets you rove them with the arrow keys. The menu opens deliberately via the
+     *  picker, typing, or ArrowDown, not by clicking the field. */
+    _handleFieldClick(e) {
+        const target = e.target;
+        if (target.closest('nldd-token') || target.closest('.token-field__picker'))
+            return;
+        if (this._showInput)
+            this._input?.focus();
+        else
+            this._focusTokenAt(this._tokens.length - 1);
+    }
+    /** The ✕ dismiss control: remove the value and mark its slot so updated() steps
+     *  focus onto the token that takes its place (or the input). */
+    _handleTokenDismiss(value, index) {
+        this._removeValue(value);
+        this._removalFocusIndex = index;
+    }
+    /** A token's menu action was chosen (token-control="menu"): report which token
+     *  and which action and let the app decide what happens (remove, edit, …). The
+     *  token owns closing the menu and returning focus to its chevron. When the app
+     *  handles the action synchronously by removing this token, mark its slot so
+     *  updated() re-homes focus (the closing menu has left focus adrift by then). */
+    _handleTokenAction(e, value) {
+        const item = e.target;
+        const action = item.value || item.text;
+        const index = this.values.indexOf(value);
+        this.dispatchEvent(new CustomEvent('token-action', {
+            detail: { value, action },
+            bubbles: true,
+            composed: true,
+        }));
+        if (index !== -1 && !this.values.includes(value))
+            this._removalFocusIndex = index;
+    }
+    /**
+     * The picker (a real button) toggles the menu. Because it opens on `click`
+     * (after the gesture's pointerdown), the auto-popover isn't light-dismissed by
+     * the opening gesture. When the menu is already open, this same gesture's
+     * pointerdown light-dismisses it; the flag makes the trailing click a no-op so
+     * it doesn't flicker back open. Mirrors the combo-box picker.
+     */
+    _handlePickerPointerdown() {
+        if (this._isOpen)
+            this._pickerPointerdownWhileOpen = true;
+    }
+    _togglePicker() {
+        this._input?.focus();
+        if (this._pickerPointerdownWhileOpen) {
+            this._pickerPointerdownWhileOpen = false;
+            return;
+        }
+        if (this._isOpen) {
+            this._closeMenu();
+        }
+        else {
+            this._syncMenuItems();
+            this._openMenu();
+        }
+    }
+    // — Menu wiring ——————————————————————————————————————————————————————————
+    _onSlotChange() {
+        this.requestUpdate(); // re-render token labels when options change
+        const slot = this.shadowRoot?.querySelector('slot');
+        const menu = slot
+            ?.assignedElements({ flatten: true })
+            .find((el) => el.tagName.toLowerCase() === 'nldd-menu');
+        if (!menu)
+            return;
+        if (menu === this._menu)
+            return;
+        this._menu = menu;
+        menu.id = this._menuId;
+        menu.anchorElement = this;
+        menu.placement = 'bottom-start';
+        menu.variant = 'listbox';
+        menu.addEventListener('toggle', this._handleMenuToggle);
+        menu.addEventListener('select', this._handleMenuSelect);
+        menu.addEventListener('keydown', this._handleMenuKeydown);
+        this._updateMenuWidth();
+        this._hideSelectedMenuItems();
+        // Options may be added/removed after this (async framework rendering).
+        // Watch child changes only — not attributes — so the field's own hidden/
+        // query toggles on items don't loop. childList picks up added menu-items.
+        this._menuObserver?.disconnect();
+        this._menuObserver = new MutationObserver(() => {
+            this._hideSelectedMenuItems();
+            this.requestUpdate();
+        });
+        this._menuObserver.observe(menu, { childList: true, subtree: true });
+    }
+    /** Pin the menu to the native input's width (its anchor) so it lines up under
+     *  the input and never extends past it. */
+    _updateMenuWidth() {
+        if (!this._menu)
+            return;
+        const rect = (this._inputArea ?? this._input ?? this).getBoundingClientRect();
+        this._menu.width = `${rect.width}px`;
+    }
+    /**
+     * Add a value, clear the input, and close the menu — focus returns to the empty
+     * input. The menu only reopens on a deliberate action (typing, ArrowDown, or the
+     * picker), so a focused empty field behaves the same whether it was just focused
+     * or a value was just committed.
+     */
+    _commitValue(value, refocus = true) {
+        this._addValue(value);
+        this._resetInputText();
+        this._closeMenu();
+        // On blur we commit but must NOT pull focus back — the user is leaving the
+        // field (e.g. onto a submit button); re-focusing would fight that move.
+        if (!refocus)
+            return;
+        // After the last value the input disappears (no custom, no options left); put
+        // focus on the last token instead of dropping it to the body.
+        void this.updateComplete.then(() => {
+            if (this._showInput)
+                this._input?.focus();
+            else
+                this._focusTokenAt(this._tokens.length - 1);
+        });
+    }
+    _openMenu() {
+        if (!this._menu || this.disabled)
+            return;
+        if (!('showPopover' in this._menu))
+            return;
+        // Nothing to show (all options selected / filtered out) — don't open an
+        // empty menu. Callers sync the items first, so the count is current.
+        if (this._visibleOptionCount === 0)
+            return;
+        // Guard on the real popover state, not `_isOpen`: the popover toggle event
+        // that drives `_isOpen` is async, so right after a menu-item hides the
+        // popover `_isOpen` is still stale-true — guarding on it would wrongly skip
+        // the reopen. `:popover-open` also prevents the throw on double-show.
+        if (this._menu.matches(':popover-open'))
+            return;
+        // Anchor to the input + picker wrapper so the menu lines up under the whole
+        // field row (including the picker), wherever it sits after the tokens.
+        this._menu.anchorElement = this._inputArea ?? this._input ?? this;
+        this._updateMenuWidth();
+        this._menu.showPopover();
+    }
+    _closeMenu() {
+        if (!this._menu)
+            return;
+        if (!this._menu.matches(':popover-open'))
+            return;
+        this._menu.hidePopover();
+    }
+    _updateActiveDescendant() {
+        this._highlightedId = this._menu?.getHighlightedId() ?? '';
+    }
+    _resetInputText() {
+        this._text = '';
+        if (this._input)
+            this._input.value = '';
+    }
+    /** Options currently shown in the menu (matching the filter and not already
+     *  selected). Zero means there is nothing worth opening the menu for. */
+    get _visibleOptionCount() {
+        if (!this._menu)
+            return 0;
+        return this._menu.querySelectorAll('nldd-menu-item:not([hidden])').length;
+    }
+    /** Apply the text filter, then hide options already selected. Used after
+     *  typing, selecting, and whenever `values` changes. */
+    _syncMenuItems() {
+        if (!this._menu)
+            return;
+        this._menu.filter(this._text);
+        this._hideSelectedMenuItems();
+        this._updateActiveDescendant();
+        // Don't leave an empty menu open. Without options the empty-state dialog is
+        // noise — especially with allow-custom, where the user just types instead.
+        if (this._isOpen && this._visibleOptionCount === 0)
+            this._closeMenu();
+    }
+    /** Hide every option whose value is already a token. The text filter unhides
+     *  matches, so this runs after it. Moves the highlight off an item it hides. */
+    _hideSelectedMenuItems() {
+        if (!this._menu)
+            return;
+        const selected = new Set(this.values);
+        let reseat = false;
+        for (const el of this._menu.querySelectorAll('nldd-menu-item')) {
+            const item = el;
+            if (selected.has(item.value || item.text)) {
+                if (item.hasAttribute('highlighted'))
+                    reseat = true;
+                item.setAttribute('hidden', '');
+            }
+        }
+        if (reseat)
+            this._menu.moveHighlight('next');
+    }
+    render() {
+        return tokenFieldTemplate(this);
+    }
+};
+NLDDTokenField.formAssociated = true;
+NLDDTokenField.styles = tokenFieldStyles;
+NLDDTokenField._idCounter = 0;
+__decorate([
+    property({
+        converter: {
+            fromAttribute: (value) => value ? value.split(',').map((v) => v.trim()).filter(Boolean) : [],
+            toAttribute: () => null,
+        },
+    })
+], NLDDTokenField.prototype, "values", null);
+__decorate([
+    property({ type: String })
+], NLDDTokenField.prototype, "placeholder", void 0);
+__decorate([
+    property({ type: String })
+], NLDDTokenField.prototype, "type", void 0);
+__decorate([
+    property({ type: String })
+], NLDDTokenField.prototype, "autocomplete", void 0);
+__decorate([
+    property({ type: String, attribute: 'accessible-label' })
+], NLDDTokenField.prototype, "accessibleLabel", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'allow-custom' })
+], NLDDTokenField.prototype, "allowCustom", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NLDDTokenField.prototype, "valid", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NLDDTokenField.prototype, "invalid", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true, attribute: 'no-spellcheck' })
+], NLDDTokenField.prototype, "noSpellcheck", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NLDDTokenField.prototype, "readonly", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NLDDTokenField.prototype, "required", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], NLDDTokenField.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: 'token-control' })
+], NLDDTokenField.prototype, "tokenControl", void 0);
+__decorate([
+    property({ type: String })
+], NLDDTokenField.prototype, "name", void 0);
+__decorate([
+    property({ type: Object })
+], NLDDTokenField.prototype, "translations", void 0);
+__decorate([
+    state()
+], NLDDTokenField.prototype, "_text", void 0);
+__decorate([
+    state()
+], NLDDTokenField.prototype, "_isOpen", void 0);
+__decorate([
+    state()
+], NLDDTokenField.prototype, "_highlightedId", void 0);
+__decorate([
+    state()
+], NLDDTokenField.prototype, "_rovingIndex", void 0);
+NLDDTokenField = NLDDTokenField_1 = __decorate([
+    customElement('nldd-token-field')
+], NLDDTokenField);
+export { NLDDTokenField };
+//# sourceMappingURL=token-field.js.map