flexdesk 0.17.17 → 0.18.0

package/src/ui/components/modal.js

@@ -77,7 +77,7 @@
  *   }
  *
  * Dependent-property pick-or-create — a `select` field that carries a
- * `create` spec renders as a **type-ahead combobox** instead of a
+ * `create` spec renders as a `createCombobox` instead of a
  * dropdown: the user picks an existing option OR types a new value.
  * On submit, a value that isn't an existing option is created via
  * `create.onCreate(value)` before the form resolves:
@@ -115,29 +115,11 @@ import { ToggleField } from '../../ui/components/toggle_field.js';
 import { ColorField } from './color_field.js';
 import { ColorListField } from './color_list_field.js';
 import { choiceList, findChoice, flatChoices, selectBox, toggleChips } from './choice_controls.js';
+import { createCombobox } from './combobox.js';
+import { modalHost, setModalHost } from '../utils/modal_host.js';
+import { fireEvent } from '../utils/fire_event.js';
 
-/**
- * C25. WHERE A DIALOG OPENS, when the application spans more than one window.
- *
- * Every modal here is a `ManagedWindow` with no `container`, so it mounts into
- * `document.body` — and "document" is the document this MODULE was loaded in.
- * A consumer that opens a second browser window with `window.open` and builds
- * its DOM from the opener's realm (which is how a pop-out grid works: same
- * modules, same JS context, a different document) therefore gets its dialogs in
- * the window it popped OUT of. The user presses "Add column" on their second
- * monitor and a dialog appears on the first, behind whatever is there.
- *
- * Passing a container at each call site was the other option and it is worse:
- * twenty-one of them across eleven files, every one of which would have to be
- * given a document it has no other reason to know about, and any one missed is
- * this bug again with no way to see it from here.
- *
- * So the HOST is ambient and the consumer sets it when its focus moves. Null —
- * every consumer today — means `document.body`, exactly as before.
- */
-let _modalHost = null;
-export function setModalHost(el) { _modalHost = el || null; }
-export function modalHost() { return _modalHost; }
+export { setModalHost, modalHost };
 
 let _modalSeq = 1;
 
@@ -198,7 +180,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
         `;
 
         const win = new ManagedWindow({
-            container: _modalHost,
+            container: modalHost(),
             id: `twm-modal-${_modalSeq++}`,
             title: title || 'Dialog',
             icon: 'edit_note',
@@ -237,12 +219,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
         // The options each field offers NOW — `setOptions` replaces them, the
         // caller's field object is never written to.
         const optionsOf = new Map(formFields.map((f) => [f.name, f.options]));
-        const comboHints = new Map();
         for (const f of formFields) {
-            if (f.type === 'select' && f.create) {
-                const update = _wireComboboxHint(body, f, () => optionsOf.get(f.name));
-                if (update) comboHints.set(f.name, update);
-            }
             if (f.type === 'picker') _wirePicker(body, f);
         }
         const rowHidden = (name) => !!body.querySelector(`[data-field-row="${name}"]`)?.hidden;
@@ -281,13 +258,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
          *  read a combobox through this, so they agree (`'2'` is option `2`). */
         const comboOption = (f, text) => findChoice(flatChoices(optionsOf.get(f.name)), text, true);
         /** A disabled option's reason ('' with none) when one is the value, else null. */
-        const unavailable = (f, value) => {
-            const c = controls.get(f.name);
-            if (c) return c.unavailable();
-            if (f.type !== 'select' || !f.create || value == null || value === '') return null;
-            const o = comboOption(f, value);
-            return o?.disabled ? (o.reason || '') : null;
-        };
+        const unavailable = (f) => controls.get(f.name)?.unavailable() ?? null;
 
         // Clear per-field errors on input so the user sees the row recover.
         for (const f of formFields) {
@@ -337,11 +308,6 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
                     const el = body.querySelector(`[name="${name}"]`);
                     if (!el) return undefined;
                     if (el.type === 'checkbox') return !!el.checked;
-                    const f = fieldOf(name);
-                    if (f?.type === 'select' && f.create) {
-                        const match = comboOption(f, el.value);
-                        return match ? match.value : el.value;
-                    }
                     return el.value;
                 },
                 set(name, value) {
@@ -350,29 +316,17 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
                     if (!el) return;
                     if (el.type === 'checkbox') { el.checked = !!value; return; }
                     const f = fieldOf(name);
-                    // A combobox does not take a disabled option's text either.
-                    const shut = f?.type === 'select' && f.create && comboOption(f, value)?.disabled;
-                    el.value = value == null || shut ? '' : String(value);
-                    comboHints.get(name)?.();
+                    el.value = value == null ? '' : String(value);
                     if (f?.type === 'picker') {
                         const display = body.querySelector(`[data-picker-display="${name}"]`);
                         if (display) display.value = _pickerLabel(f, el.value);
                     }
                 },
                 setOptions(name, options) {
-                    const f = fieldOf(name);
-                    if (!f) return;
                     const c = controls.get(name);
-                    if (c?.setOptions) {
-                        optionsOf.set(name, options);
-                        c.setOptions(options);
-                        return;
-                    }
-                    if (f.type !== 'select' || !f.create) return;
+                    if (!c?.setOptions) return;
                     optionsOf.set(name, options);
-                    const list = body.querySelector(`[data-datalist-for="${name}"]`);
-                    if (list) list.innerHTML = _datalistOptions(options);
-                    comboHints.get(name)?.();
+                    c.setOptions(options);
                 },
             };
             const fire = (name) => {
@@ -444,7 +398,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
                 if (rowHidden(f.name)) {
                     // Not asked about — but a disabled option is still never
                     // the value: a hidden row holding one submits no value.
-                    if (unavailable(f, data[f.name]) != null) data[f.name] = f.type === 'radio' ? null : '';
+                    if (unavailable(f) != null) data[f.name] = f.type === 'radio' ? null : '';
                     continue;
                 }
                 const v = data[f.name];
@@ -454,7 +408,7 @@ export function openForm({ title, fields = [], defaults = {}, submitLabel = 'OK'
                 let msg = f.required && _missing(f, v) ? 'Required.' : null;
                 if (!msg && _outOfRange(f, v)) msg = _rangeMessage(f);
                 if (!msg) {
-                    const reason = unavailable(f, v);
+                    const reason = unavailable(f);
                     if (reason != null) msg = reason ? `Not available: ${reason}` : 'Not available.';
                 }
                 if (!msg) msg = controls.get(f.name)?.error?.() ?? null;
@@ -527,7 +481,7 @@ export function openConfirm({
 
         let _resolved = false;
         const win = new ManagedWindow({
-            container: _modalHost,
+            container: modalHost(),
             id: `twm-confirm-${_modalSeq++}`,
             title: title || 'Confirm',
             icon: icon || (danger ? 'warning' : 'help'),
@@ -601,6 +555,9 @@ export function openConfirm({
  *                 existing caller has always got.
  *   - `onMaximizeChange` `(maximized, contentEl) => void`, called on each
  *                 flip. Only useful with `maximizable`.
+ *   - `beforeClose`      `() => boolean | Promise<boolean>`: asked when Esc or
+ *                 the X would dismiss; answering false keeps the modal open. An
+ *                 action button does not ask it.
  *
  * ══ C29. WHY A DIALOG'S MAXIMISE IS THE GEOMETRIC ONE ═══════════════════
  *
@@ -642,6 +599,7 @@ export function openModal({
     backdropOpacity = undefined,
     maximizable      = false,
     onMaximizeChange = null,
+    beforeClose      = null,
 } = {}) {
     return new Promise((resolve) => {
         const body = document.createElement('div');
@@ -726,7 +684,7 @@ export function openModal({
             _onMax = null;
         };
         const win = new ManagedWindow({
-            container: _modalHost,
+            container: modalHost(),
             id: `twm-modal-${_modalSeq++}`,
             title,
             icon,
@@ -747,6 +705,7 @@ export function openModal({
             canDrag: true,
             defaultWidth:  width,
             defaultHeight: height,
+            beforeClose,
             // Esc, the X and the backdrop all land here without passing through
             // `close`, so the listener is dropped here as well as there — the
             // three dismissals a user reaches for most are exactly the ones
@@ -953,14 +912,68 @@ function _offered(options) {
     return flatChoices(options).filter((o) => !o.disabled);
 }
 
-function _datalistOptions(options) {
-    return _offered(options).map((o) => `<option value="${_esc(o.value)}"></option>`).join('');
+/**
+ * A `select` with `create`: `createCombobox` over the enabled options. The box holds
+ * the text; `read` is the value of the option that text names, else the text. A
+ * disabled option is not offered, and a default or `write` naming one leaves the box
+ * empty; typed all the same, it is `unavailable`.
+ */
+function _mountCombobox(slot, f, value) {
+    let options = f.options;
+    const named = (text) => findChoice(flatChoices(options), text, true);
+    const shown = (v) => (v == null || named(v)?.disabled ? '' : String(v));
+
+    const hint = document.createElement('span');
+    hint.className = 'twm-combobox__hint';
+    hint.hidden = true;
+    // With `create: true` the typed value simply IS the value — there is no
+    // entity being made, so promising to "create" one is a lie that reads as
+    // a warning.
+    const noun = f.create === true ? null : _createSpec(f).hint || 'new entry';
+    const updateHint = () => {
+        const v = c.value.trim();
+        const isNew = noun && v && !flatChoices(options).some((o) => String(o.value) === v);
+        if (isNew) hint.textContent = `↳ will create ${noun} “${v}”`;
+        hint.hidden = !isNew;
+    };
+
+    const c = createCombobox({
+        options: _offered(options),
+        value: shown(value),
+        name: f.name,
+        placeholder: f.placeholder ?? 'type to pick or create…',
+        // Enter keeps what was typed: this field exists to accept a value nobody listed.
+        autoHighlight: false,
+        onChange: () => updateHint(),
+    });
+    if (f.required) c.input.required = true;
+    c.el.appendChild(hint);
+    slot.replaceWith(c.el);
+    updateHint();
+    return {
+        read() {
+            const o = named(c.value);
+            return o ? o.value : c.value;
+        },
+        write(v) { c.value = shown(v); updateHint(); },
+        focus: c.focus,
+        unavailable() {
+            const o = c.value === '' ? undefined : named(c.value);
+            return o?.disabled ? (o.reason || '') : null;
+        },
+        setOptions(next) {
+            options = next;
+            c.setOptions(_offered(next));
+            updateHint();
+        },
+        dispose: c.destroy,
+    };
 }
 
 /**
  * Mount a field that is a component rather than markup — a `toggle`, a
- * `select` (not a combobox), `checklist` or `radio` drawn by
- * `choice_controls.js`, or a `color` / `colorList` — into the
+ * `select`, `checklist` or `radio` drawn by `choice_controls.js`, a `select`
+ * with `create` drawn by `createCombobox`, or a `color` / `colorList` — into the
  * `data-control-slot` its row left, and hand back what the form needs of it:
  * `{ read(), write(v), focus(), unavailable(), submit?(), error?(),
  * setOptions?(options), dispose?() }`. `unavailable()` is the reason (or '')
@@ -1018,6 +1031,7 @@ function _mountControl(host, f, value, onChange) {
             dispose: () => c.dispose(),
         };
     }
+    if (f.type === 'select' && f.create) return _mountCombobox(slot, f, value);
     const common = { keepMissing: false, loose: true };
     const disabledReason = (entry) => (entry?.disabled ? (entry.reason || '') : null);
     if (f.type === 'select') {
@@ -1113,7 +1127,7 @@ function _wirePicker(host, f) {
             ? String(picked.label) : _pickerLabel(f, hidden.value);
         // A hidden input fires no `change` of its own; this is the one the
         // field-error clear and `onFieldChange` listen for.
-        hidden.dispatchEvent(new Event('change', { bubbles: true }));
+        fireEvent(hidden, 'change', { bubbles: true });
     };
     btn.addEventListener('click', open);
     // The read-only box is the obvious thing to click; make it work too.
@@ -1121,33 +1135,6 @@ function _wirePicker(host, f) {
 }
 
 
-/** Show / hide the "↳ will create …" hint as the user types into a
- *  create-capable combobox. */
-function _wireComboboxHint(host, f, optionsOf) {
-    const input = host.querySelector(`input[name="${f.name}"]`);
-    const hintEl = host.querySelector(`.twm-combobox__hint[data-for="${f.name}"]`);
-    if (!input || !hintEl) return;
-    // With `create: true` the typed value simply IS the value — there is no
-    // entity being made, so promising to "create" one is a lie that reads as
-    // a warning.
-    if (f.create === true) return;
-    const label = _createSpec(f).hint || 'new entry';
-    const update = () => {
-        const v = input.value.trim();
-        const known = new Set(flatChoices(optionsOf()).map((o) => String(o.value)));
-        if (v && !known.has(v)) {
-            hintEl.textContent = `↳ will create ${label} “${v}”`;
-            hintEl.hidden = false;
-        } else {
-            hintEl.hidden = true;
-        }
-    };
-    input.addEventListener('input', update);
-    update();
-    return update;
-}
-
-
 function _renderEntry(f, defaults) {
     if (f && f.section != null) {
         // A named section is addressable by `setVisible`, so a heading can be
@@ -1247,23 +1234,6 @@ function _renderField(f, value) {
             </div>
         `);
     }
-    if (f.type === 'select' && f.create) {
-        // A default naming a disabled option is not taken, as in a select.
-        const shown = findChoice(flatChoices(f.options), value, true)?.disabled ? '' : v;
-        const dlId = `ea-dl-${f.name}-${_modalSeq}`;
-        const opts = _datalistOptions(f.options);
-        const placeholder = f.placeholder
-            ? `placeholder="${_esc(f.placeholder)}"` : 'placeholder="type to pick or create…"';
-        return wrap(`
-            <div class="twm-combobox">
-                <input name="${f.name}" type="text" list="${dlId}"
-                       value="${_esc(shown)}" ${placeholder} ${required}
-                       autocomplete="off">
-                <datalist id="${dlId}" data-datalist-for="${f.name}">${opts}</datalist>
-                <span class="twm-combobox__hint" data-for="${f.name}" hidden></span>
-            </div>
-        `);
-    }
     if (f.type === 'select') return wrap(slot);
     const step = f.step != null ? `step="${f.step}"` : '';
     const placeholder = f.placeholder ? `placeholder="${_esc(f.placeholder)}"` : '';

package/src/ui/components/option_list.js

@@ -0,0 +1,160 @@
+/**
+ * THE ROWS `createSelect`, `createCombobox` AND `createTagInput`'s SUGGESTIONS
+ * DRAW: a `role="listbox"` of options, each with a glyph, a label, a second line,
+ * a hint at the end of the row and, when disabled, its reason; `{ group, options }`
+ * sections under a heading; one active row that the arrow keys walk.
+ *
+ * Focus never comes here. The text box or trigger that holds it names the active
+ * row with `aria-activedescendant` (`onActive`), and a press on a row is
+ * prevented from taking focus, so that a list row can be chosen with the box
+ * still holding the caret, and no blur closes the list under the pointer.
+ *
+ * `aria-selected` says which row IS the current value; the active row is a class.
+ * They are different things in a select, where the highlight walks away from the
+ * value and comes back. Every word is built with `textContent`: these lists carry
+ * text users wrote.
+ *
+ * An internal part: not exported from `@flexdesk/widgets`.
+ */
+
+let SEQ = 0;
+
+function node(tag, className, text) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (text !== undefined && text !== null) n.textContent = String(text);
+    return n;
+}
+
+/** `text` with the first run of `needle` in a `<mark>`, so it is plain why a row is offered. */
+function marked(target, text, needle) {
+    const at = needle ? text.toLowerCase().indexOf(needle.toLowerCase()) : -1;
+    if (at < 0) { target.textContent = text; return; }
+    target.append(text.slice(0, at), node('mark', 'twm-option-list__match', text.slice(at, at + needle.length)),
+                  text.slice(at + needle.length));
+}
+
+/**
+ * @param {object} o
+ * @param {(option: object) => void} o.onPick   A row was clicked. Never a disabled one.
+ * @param {(id: string|null) => void} [o.onActive]  The active row's id changed.
+ */
+export function createOptionList({ onPick, onActive = null }) {
+    const id = `twm-option-list-${++SEQ}`;
+    const el = node('div', 'twm-option-list');
+    el.id = id;
+    el.setAttribute('role', 'listbox');
+
+    /** Every row drawn: `{ option, row }`. */
+    let rows = [];
+    let active = -1;
+
+    const paintActive = () => {
+        rows.forEach(({ row }, i) => row.classList.toggle('twm-option-list__row--active', i === active));
+        const row = rows[active]?.row;
+        // jsdom does not implement it, and a test harness is no reason to drop it.
+        row?.scrollIntoView?.({ block: 'nearest' });
+        onActive?.(row ? row.id : null);
+    };
+
+    const rowFor = (option, { glyphs, mark, isCurrent }) => {
+        const row = node('div', 'twm-option-list__row');
+        row.id = `${id}-${rows.length}`;
+        row.setAttribute('role', 'option');
+        row.setAttribute('aria-selected', String(!!isCurrent?.(option)));
+        if (option.disabled) row.setAttribute('aria-disabled', 'true');
+        row.title = option.description ? `${option.label} — ${option.description}` : option.label;
+        if (glyphs) {
+            const glyph = node('span', 'twm-option-list__glyph material-symbols-outlined', option.icon || '');
+            glyph.setAttribute('aria-hidden', 'true');
+            row.appendChild(glyph);
+        }
+        const words = node('span', 'twm-option-list__words');
+        const label = node('span', 'twm-option-list__label');
+        marked(label, option.label, mark);
+        words.appendChild(label);
+        if (option.description) words.appendChild(node('span', 'twm-option-list__description', option.description));
+        if (option.disabled && option.reason) words.appendChild(node('span', 'twm-choice__reason', option.reason));
+        row.appendChild(words);
+        if (option.hint) row.appendChild(node('span', 'twm-option-list__hint', option.hint));
+        return row;
+    };
+
+    const enabled = () => rows.map((r, i) => (r.option.disabled ? -1 : i)).filter((i) => i >= 0);
+
+    // A press on the list leaves focus where it is. See the header.
+    el.addEventListener('mousedown', (ev) => ev.preventDefault());
+    el.addEventListener('click', (ev) => {
+        const row = ev.target.closest?.('[role="option"]');
+        const hit = rows.find((r) => r.row === row);
+        if (hit && !hit.option.disabled) onPick(hit.option);
+    });
+
+    return {
+        el,
+        id,
+        /**
+         * Draw `sections` (`[{ heading, items }]`, as `choiceSections` gives them).
+         * @param {object} [opts]
+         * @param {string} [opts.mark]  The text to mark in each label.
+         * @param {(option: object) => boolean} [opts.isCurrent]  Is this the current value?
+         */
+        setRows(sections, { mark = '', isCurrent = null } = {}) {
+            rows = [];
+            active = -1;
+            el.replaceChildren();
+            const glyphs = sections.some((s) => s.items.some((o) => o.icon));
+            for (const { heading, items } of sections) {
+                let parent = el;
+                if (heading != null) {
+                    parent = node('div', 'twm-option-list__section');
+                    parent.setAttribute('role', 'group');
+                    parent.setAttribute('aria-label', heading);
+                    const title = node('div', 'twm-choice__group', heading);
+                    title.setAttribute('aria-hidden', 'true');
+                    parent.appendChild(title);
+                    el.appendChild(parent);
+                }
+                for (const option of items) {
+                    const row = rowFor(option, { glyphs, mark, isCurrent });
+                    rows.push({ option, row });
+                    parent.appendChild(row);
+                }
+            }
+            paintActive();
+        },
+        /** One line of text in place of the rows: nothing matched, still loading, a failure. */
+        setMessage(text) {
+            rows = [];
+            active = -1;
+            el.replaceChildren(node('div', 'twm-option-list__message', text));
+            paintActive();
+        },
+        /** How many rows are drawn. */
+        get size() { return rows.length; },
+        /** The drawn options, in order. */
+        options: () => rows.map((r) => r.option),
+        /** The active row's option, or null. */
+        activeOption: () => rows[active]?.option ?? null,
+        /** Make row `index` active; -1, or a row that is disabled, makes none active. */
+        setActive(index) {
+            active = rows[index] && !rows[index].option.disabled ? index : -1;
+            paintActive();
+        },
+        /** The next row that may be chosen, by `step`, wrapping. From none: the first or the last. */
+        move(step) {
+            const stops = enabled();
+            if (!stops.length) return;
+            const at = stops.indexOf(active);
+            const next = at < 0 ? (step > 0 ? 0 : stops.length - 1) : (at + step + stops.length) % stops.length;
+            active = stops[next];
+            paintActive();
+        },
+        /** The first (`step` 1) or last (`step` -1) row that may be chosen. */
+        moveToEnd(step) {
+            const stops = enabled();
+            active = stops.length ? stops[step > 0 ? 0 : stops.length - 1] : -1;
+            paintActive();
+        },
+    };
+}

package/src/ui/components/popover.js

@@ -0,0 +1,94 @@
+/**
+ * A POPOVER — a panel of rich content hung off the element that opened it. (0.18.0)
+ *
+ * `role="dialog"`, on an anchored layer (`anchored_layer.js`, which says how it is
+ * placed and what closes it). Focus moves into it on open and comes back to the
+ * anchor on close. Opening one from the anchor that holds an open one closes it,
+ * a toggle; opening one anywhere else closes the open one, unless that one owns
+ * the new anchor (`anchored_layer.js`).
+ *
+ * TAB STAYS INSIDE, cycling the panel's controls, as a modal's and a `CategoryPicker`'s
+ * do. The panel is mounted at the end of the page, so past its edge lies whatever comes
+ * next in the document, which is not the anchor's neighbour and, over a modal, is behind
+ * it. Escape is the way out.
+ */
+import { openAnchoredLayer } from './anchored_layer.js';
+import { collectFocusable } from '../utils/focusable.js';
+
+/** The open popovers, to find the one an anchor holds. */
+const OPEN = new Set();
+
+/** What a call answers when nothing opened. */
+const nothingOpened = (toggled) => ({ el: null, close() {}, closed: Promise.resolve(), reposition() {}, toggled });
+
+/** Tab at the panel's edge goes round to the other edge. */
+function keepTabInside(el) {
+    el.addEventListener('keydown', (ev) => {
+        if (ev.key !== 'Tab' || ev.defaultPrevented) return;
+        const controls = collectFocusable(el);
+        if (!controls.length) { ev.preventDefault(); return; }
+        const first = controls[0];
+        const last = controls[controls.length - 1];
+        const active = el.ownerDocument.activeElement;
+        if (ev.shiftKey ? (active === first || active === el) : active === last) {
+            ev.preventDefault();
+            (ev.shiftKey ? last : first).focus();
+        }
+    });
+}
+
+/**
+ * @param {object} o
+ * @param {HTMLElement} o.anchor     What opened it; focus returns here.
+ * @param {HTMLElement} o.content    The popover's body.
+ * @param {string} [o.label]         Its accessible name.
+ * @param {string} [o.className]     Extra classes on the panel.
+ * @param {HTMLElement} [o.focus]    What takes focus on open; else the panel.
+ * @param {'start'|'end'} [o.align]  Which anchor edge it lines up with first.
+ * @param {string} [o.inside]        A selector for floating things of your own that
+ *                                   are not "outside" it.
+ * @param {(reason: string) => void} [o.onClose]  After it is gone.
+ * @returns {{el: HTMLElement|null, close: (reason?: string) => void, closed: Promise<void>,
+ *            reposition: () => void, toggled: boolean}}
+ *          `el` is null when nothing opened, and `onClose` is not called for it: `toggled`
+ *          is true when the call only CLOSED the popover its anchor held, false when
+ *          the anchor has left the document.
+ */
+export function openPopover({ anchor, content, label = '', className = '', focus = null, align = 'start',
+                              inside = null, onClose = null }) {
+    for (const open of OPEN) {
+        if (anchor && open.anchor === anchor) {
+            open.close('toggle');
+            return nothingOpened(true);
+        }
+    }
+
+    const el = document.createElement('div');
+    el.className = `twm-popover${className ? ` ${className}` : ''}`;
+    el.setAttribute('role', 'dialog');
+    if (label) el.setAttribute('aria-label', label);
+    el.tabIndex = -1;
+    el.appendChild(content);
+    keepTabInside(el);
+
+    let settle;
+    const closed = new Promise((resolve) => { settle = resolve; });
+    const layer = openAnchoredLayer({
+        anchor, el, align, gap: 4, inside,
+        onClose(reason) {
+            OPEN.delete(handle);
+            anchor?.classList?.remove('twm-is-open');
+            anchor?.setAttribute?.('aria-expanded', 'false');
+            onClose?.(reason);
+            settle();
+        },
+    });
+    if (!layer) return nothingOpened(false);
+    const handle = { el, anchor, closed, toggled: false, close: layer.close, reposition: layer.place };
+    OPEN.add(handle);
+    anchor?.classList?.add('twm-is-open');
+    if (anchor && !anchor.hasAttribute?.('aria-haspopup')) anchor.setAttribute?.('aria-haspopup', 'dialog');
+    anchor?.setAttribute?.('aria-expanded', 'true');
+    (focus || el).focus?.({ preventScroll: true });
+    return handle;
+}