poetry-core 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f473efd9c0d12c6d6c8df6fd9273881e7c47ae51049041ec77b4e8ca1cbd4287
-  data.tar.gz: 87b7bc488972de80728431ab4888b9160c9a7676ae5f956ff155fe0fa52c6cad
+  metadata.gz: 30f3e5a92218a515eb068a382276bb2ecab9795e9205a265039bac71bac5d27c
+  data.tar.gz: 9ba29c74dcd4526e5e4e3b3dbdecb0d877ae86d44280aefb7beb1450bc87b21e
 SHA512:
-  metadata.gz: 167f3b0a36846778aeda28b072567ed91af0a67c3f55c1eeae79db7785afc4a947a71314d7e2895cf2205dd829eabbfa88a4d1365a5b7a0d423fd8d7fddf6181
-  data.tar.gz: 249b441648327a54d8d906a526c269e8194add9badd1468111636ab03d7499962cd9949f6c981c8e0a158cceb41d1e1490e3f18d2414e48786dab70c90b2466f
+  metadata.gz: a15e8257a9c946eeba75798bc32848b0c86fb9d7c17a780506b38d2eb98d85fbdf34ce5844da7d584c08a12bceb923f43b8bda0432ccbaef792ed03530ed6337
+  data.tar.gz: 139af0f376f0e35b3fbaf93bc25e31ba9fd5e8b9e13c687b867af957a585b1a7482d8f7bfcb67b34da1c3c4260a8621af4fdb2f08c55ed91f141028d4f82c0fc

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.1.12] - 2026-10-07
+
+### Changed
+
+- Version bump with the family; no changes in this gem.
+
+## [0.1.11] - 2026-10-05
+
+### Changed
+
+- The four layered popups share one machine: `@poetry/controllers/behaviors/overlay` (`useOverlay`) owns the show and hide sequencing, the late portal on reconcile, the layer tokens, the dismiss, interact-outside and auto-focus vetoes and the focus-restore suppression rule, and popover, menu, select and combobox hand it their policies as hooks: how the content and the trigger resolve, which layers go on, what the open microtask does, what a hide settles first, how the open event reads. Rendered markup, event names and sequencing are unchanged; the controllers lose about a third of their lines between them. Tooltip and hover card stay on their own pointer-timed machines, which share less with the four than the hooks to express the difference would cost.
+
+### Fixed
+
+- The command engine writes `data-empty` on its list when the filter pass leaves no visible item, beside unhiding the empty part, so a theme can restyle an empty list; the Combobox themes' `data-empty:p-0` rule was dead without it.
+
 ## [0.1.10] - 2026-10-03
 
 ### Added

data/app/javascript/poetry/core/behaviors/overlay.js

@@ -0,0 +1,289 @@
+// useOverlay: the popup machine the layered overlays share (popover,
+// menu, select, combobox): show and hide sequencing, the late portal on
+// reconcile, the layer tokens, the dismiss, interact-outside and
+// auto-focus vetoes, and the focus-restore suppression rule. The
+// policies that make each component itself stay in the controller and
+// come in as hooks: how the content and the trigger resolve, which
+// layers go on, what happens on open, what to settle before a hide, how
+// the open event reads. Rendered markup and sequencing are what the six
+// controllers did by hand; this is the skeleton, not the product.
+import { useLayers } from "@poetry/controllers/behaviors/layers"
+import { useListen } from "@poetry/controllers/behaviors/listen"
+import { usePortal } from "@poetry/controllers/behaviors/portal"
+import { usePresence } from "@poetry/controllers/behaviors/presence"
+import { resolvePortalContainer } from "@poetry/controllers/helpers/portal"
+import { setState, stateOf } from "@poetry/controllers/helpers/state"
+
+const POPPER_STRATEGY = "data-poetry--core--popper-strategy-value"
+const DISMISS_EVENT = "poetry--core--dismissable:dismiss"
+const INTERACT_OUTSIDE_EVENT = "poetry--core--dismissable:interact-outside"
+const MOUNT_AUTO_FOCUS_EVENT = "poetry--core--focus-scope:mount-auto-focus"
+const UNMOUNT_AUTO_FOCUS_EVENT = "poetry--core--focus-scope:unmount-auto-focus"
+
+/**
+ * The overlay machine for one controller, over the controller's
+ * current scope (its behaviors tear down with `teardown(controller)`).
+ *
+ * @param {Object} controller - the Stimulus controller instance; reads
+ *   and writes `openValue`, dispatches through `controller.dispatch`
+ * @param {Object} options
+ * @param {() => Element | null} options.content - the popup element
+ * @param {() => Element | null} options.trigger - the element whose
+ *   press toggles the popup, the interact-outside veto's inside
+ * @param {() => Element | null} [options.expander] - the element that
+ *   carries aria-expanded and the popup-open state; the trigger by default
+ * @param {string[]} options.layers - the layer controllers the content
+ *   wears while open
+ * @param {string} options.eventPrefix - the prefix of the open and closed events
+ * @param {() => boolean} [options.modal] - whether the popup is modal;
+ *   decides the suppression of focus restore after an outside press
+ * @param {boolean} [options.reasons=false] - whether the content carries
+ *   data-open-reason and data-open-seed while open
+ * @param {boolean} [options.expandedWhenPresent=false] - write
+ *   aria-expanded only when the expander already carries it
+ * @param {boolean} [options.vetoMountAutoFocus=false] - keep focus-scope
+ *   from moving focus on mount (the controller places it itself)
+ * @param {(content: Element) => void} [options.activateLayers] - writes
+ *   the layer values before the tokens go on; the tokens go on either way
+ * @param {(content: Element, strategy: string) => void} [options.strategy]
+ *   - writes the popper strategy; the root's attribute by default
+ * @param {(content: Element, open: Object) => void} [options.onOpen] -
+ *   runs on the microtask after a show, before the open event
+ * @param {(reason: string, seed: string | null) => Object} [options.openDetail]
+ *   - the open event's detail
+ * @param {(content: Element, reason: string) => void} [options.beforeHide]
+ *   - settles what a hide must settle first (sub levels, a typeahead)
+ * @param {(content: Element) => void} [options.beforeExit] - runs after
+ *   the state flips closed and before the exit presence starts
+ * @param {(content: Element) => void} [options.onHidden] - runs once the
+ *   exit finished and the content is home, before the closed event
+ * @param {(origin: Element) => boolean} [options.insideAlso] - more
+ *   elements an outside press must not dismiss from (a chips field)
+ * @param {(event: Event) => void} [options.onDismiss] - sees every
+ *   dismiss event on the content before the machine acts
+ * @param {(target: Element, escaped: boolean) => void} [options.onDismissElsewhere]
+ *   - a dismiss from a node inside the content that is not the content
+ * @returns {Object} the machine: connect, show, hide, isOpen, portalPinned
+ */
+export function useOverlay(controller, options) {
+  const presence = usePresence(controller)
+  const portal = usePortal(controller)
+  const layers = useLayers(controller)
+  const element = controller.element
+  const content = options.content
+  const trigger = options.trigger
+  const expander = options.expander ?? trigger
+  const modal = options.modal ?? (() => false)
+  const setStrategy = options.strategy ?? ((_content, strategy) => element.setAttribute(POPPER_STRATEGY, strategy))
+  const openDetail = options.openDetail ?? ((reason, seed) => (seed ? { reason, seed } : { reason }))
+
+  let connected = false
+  let suppressRestore = false
+
+  const isOpen = () => {
+    const node = content()
+
+    return Boolean(node) && stateOf(node) === "open"
+  }
+
+  const activateLayers = (node) => {
+    options.activateLayers?.(node)
+    layers.activate(node, options.layers)
+  }
+
+  // The reconcile path portals ONE FRAME LATE: connect order within a
+  // boot is unordered, and portaling before the sibling popper's connect
+  // would rob it of its content target before it could cache the node.
+  const portalPinned = (node) => {
+    window.requestAnimationFrame(() => {
+      if (!connected || !isOpen()) return
+
+      portal.portal(node, { container: resolvePortalContainer(element) })
+      setStrategy(node, "absolute")
+    })
+  }
+
+  const show = (reason, { seed = null, focus = true } = {}) => {
+    const node = content()
+
+    if (!node || isOpen()) return
+
+    presence.cancel(node)
+    suppressRestore = false
+
+    const opener = expander()
+
+    // Portal-on-open: move BEFORE the enter presence (reparenting
+    // mid-animation restarts it), re-anchor absolute - static under
+    // compositor scroll, transform-immune.
+    portal.portal(node, { container: resolvePortalContainer(element) })
+    setStrategy(node, "absolute")
+
+    node.hidden = false
+    if (options.reasons) {
+      node.setAttribute("data-open-reason", reason)
+      if (seed) node.setAttribute("data-open-seed", seed)
+      else node.removeAttribute("data-open-seed")
+    }
+    if (opener && (!options.expandedWhenPresent || opener.hasAttribute("aria-expanded"))) {
+      opener.setAttribute("aria-expanded", "true")
+    }
+    if (opener) setState(opener, "popup-open")
+    presence.enter(node)
+    activateLayers(node)
+    controller.openValue = true
+
+    queueMicrotask(() => {
+      if (!isOpen()) return
+
+      options.onOpen?.(node, { reason, seed, focus })
+      controller.dispatch("open", { prefix: options.eventPrefix, detail: openDetail(reason, seed) })
+    })
+  }
+
+  const hide = (reason, { restoreFocus = true } = {}) => {
+    const node = content()
+
+    if (!node || !isOpen()) return
+
+    options.beforeHide?.(node, reason)
+    suppressRestore = !restoreFocus || (reason === "outside-press" && !modal())
+
+    const opener = expander()
+
+    if (opener && (!options.expandedWhenPresent || opener.hasAttribute("aria-expanded"))) {
+      opener.setAttribute("aria-expanded", "false")
+    }
+    if (opener) setState(opener, "popup-closed")
+    if (options.reasons) {
+      node.removeAttribute("data-open-reason")
+      node.removeAttribute("data-open-seed")
+    }
+    options.beforeExit?.(node)
+    controller.openValue = false
+
+    presence.exit(node, {
+      onRemove: () => {
+        node.hidden = true
+        // Home AFTER the exit finished and hidden landed; focus return is
+        // focus-scope's ref-based job, indifferent to the move.
+        portal.restore(node)
+        setStrategy(node, "fixed")
+        layers.deactivate(node, options.layers)
+        options.onHidden?.(node)
+        controller.dispatch("closed", { prefix: options.eventPrefix, detail: { reason } })
+      }
+    })
+  }
+
+  // A press on the popup's OWN trigger is the toggle's job, not an
+  // outside press: veto the dismissal so the toggle can close it.
+  const onInteractOutside = (event) => {
+    if (event.target !== content()) return
+
+    const origin = event.detail?.originalEvent?.target
+
+    if (!(origin instanceof Element)) return
+    if (trigger()?.contains(origin) || options.insideAlso?.(origin)) event.preventDefault()
+  }
+
+  const onDismiss = (event) => {
+    const target = event.target instanceof Element ? event.target : null
+
+    if (!target) return
+
+    options.onDismiss?.(event)
+
+    const escaped = event.detail?.originalEvent?.type === "keydown"
+
+    if (target === content()) hide(escaped ? "escape-key" : "outside-press")
+    else options.onDismissElsewhere?.(target, escaped)
+  }
+
+  const onMountAutoFocus = (event) => {
+    if (event.target === content()) event.preventDefault()
+  }
+
+  const onUnmountAutoFocus = (event) => {
+    if (event.target === content() && suppressRestore) event.preventDefault()
+  }
+
+  const wire = (node) => {
+    useListen(controller, node, DISMISS_EVENT, onDismiss)
+    useListen(controller, node, INTERACT_OUTSIDE_EVENT, onInteractOutside)
+    if (options.vetoMountAutoFocus) useListen(controller, node, MOUNT_AUTO_FOCUS_EVENT, onMountAutoFocus)
+    useListen(controller, node, UNMOUNT_AUTO_FOCUS_EVENT, onUnmountAutoFocus)
+  }
+
+  return {
+    /**
+     * Wires the content's layer events now; `connect()` reconciles later.
+     * @returns {void}
+     */
+    wire() {
+      const node = content()
+
+      if (node) wire(node)
+    },
+    /**
+     * Marks the machine connected and reconciles: server-open content
+     * adopts the layer stack and re-portals one frame late (the DOM
+     * wins); an open value with closed markup shows.
+     * @param {Object} [initial] - the show call for an open value
+     * @param {string} [initial.reason="trigger-press"]
+     * @param {boolean} [initial.focus=true]
+     * @returns {void}
+     */
+    connect({ reason = "trigger-press", focus = true } = {}) {
+      connected = true
+
+      const node = content()
+
+      if (isOpen()) {
+        if (node) {
+          activateLayers(node)
+          portalPinned(node)
+        }
+        controller.openValue = true
+      } else if (controller.openValue) {
+        show(reason, { focus })
+      }
+    },
+    /**
+     * Marks the machine disconnected; the behaviors tear down with the
+     * controller's scope.
+     * @returns {void}
+     */
+    disconnect() {
+      connected = false
+    },
+    /**
+     * Whether the machine has connected and not yet disconnected.
+     * @returns {boolean}
+     */
+    connected: () => connected,
+    show,
+    hide,
+    isOpen,
+    portalPinned,
+    // The behaviors under the machine, for a controller with more levels
+    // than the root popup (a menu's sub levels ride the same instances,
+    // so teardown restores them newest first, subs before the root).
+    presence,
+    portal,
+    layers,
+    /**
+     * Wires the dismiss and interact-outside handlers onto another node
+     * (a portaled sub level, which no longer bubbles through the root);
+     * a dismiss from it reaches `onDismissElsewhere`.
+     * @param {Element} node
+     * @returns {Array<() => void>} the unlisten handles
+     */
+    wireLevel(node) {
+      return [
+        useListen(controller, node, DISMISS_EVENT, onDismiss),
+        useListen(controller, node, INTERACT_OUTSIDE_EVENT, onInteractOutside)
+      ]
+    }
+  }
+}

data/app/javascript/poetry/core/combobox_controller.js

@@ -1,13 +1,11 @@
 import { Controller } from "@hotwired/stimulus"
 import { collectionItems } from "@poetry/controllers/helpers/collection"
 import { isImeKeydown } from "@poetry/controllers/helpers/escape"
-import { useLayers } from "@poetry/controllers/behaviors/layers"
 import { useListen } from "@poetry/controllers/behaviors/listen"
-import { usePortal } from "@poetry/controllers/behaviors/portal"
-import { usePresence } from "@poetry/controllers/behaviors/presence"
-import { isPortaled, resolvePortalContainer } from "@poetry/controllers/helpers/portal"
+import { useOverlay } from "@poetry/controllers/behaviors/overlay"
+import { isPortaled } from "@poetry/controllers/helpers/portal"
 import { teardown } from "@poetry/controllers/helpers/scope"
-import { setState, stateOf } from "@poetry/controllers/helpers/state"
+import { setState } from "@poetry/controllers/helpers/state"
 import { tabbableWithin } from "@poetry/controllers/helpers/tabbable"
 
 const TRIGGER_SELECTOR = '[data-slot="combobox-trigger"]'
@@ -29,7 +27,6 @@ const COMMAND_IDENTIFIER = "poetry--core--command"
 // NO roving-focus (the popup is Command's activedescendant session - the
 // family's first popup without it).
 const CONTENT_LAYER_CONTROLLERS = ["poetry--core--focus-scope", "poetry--core--dismissable"]
-const POPPER_STRATEGY = "data-poetry--core--popper-strategy-value"
 
 /**
  * The Combobox ORCHESTRATOR: Select's shell
@@ -38,10 +35,12 @@ const POPPER_STRATEGY = "data-poetry--core--popper-strategy-value"
  * listens for the embedded engine's poetry:command:select; it contains NO
  * filter/highlight/scoring code (Command owns those) and Command gained no
  * combobox code (engine purity, fenced both directions by the conformance
- * greps). Zero code is shared with SelectController - the PATTERNS are
- * (the layer mechanism, the native-first 5-step pipeline, the adoption
- * path), re-instantiated here because a facade extraction was explicitly
- * declined (the Select contract's open question, answered by this build).
+ * greps). What it shares with SelectController is the SKELETON, the
+ * overlay machine in behaviors/overlay.js (show and hide sequencing,
+ * the late portal, the layer tokens, the vetoes); the policies (the
+ * native-first 5-step pipeline, the adoption path, the three deltas
+ * below) stay here. A facade over the policies was evaluated and
+ * declined once, and that call stands: only the sequence is shared.
  *
  * THE THREE DELIBERATE DELTAS vs Select, each pinned by tests so neither
  * sibling's rules leak:
@@ -102,11 +101,7 @@ export default class ComboboxController extends Controller {
     multiple: { type: Boolean, default: false }
   }
 
-  #connected = false
-  #suppressRestore = false
-  #presence = null
-  #portal = null
-  #layers = null
+  #overlay = null
   #applied = ""
   #placeholder = ""
   #dismissedEvent = null
@@ -118,9 +113,21 @@ export default class ComboboxController extends Controller {
    * popup up (layers + the late portal).
    */
   connect() {
-    this.#presence = usePresence(this)
-    this.#portal = usePortal(this)
-    this.#layers = useLayers(this)
+    this.#overlay = useOverlay(this, {
+      content: () => this.#content(),
+      trigger: () => this.#trigger(),
+      expander: () => this.#expander(),
+      layers: CONTENT_LAYER_CONTROLLERS,
+      eventPrefix: EVENT_PREFIX,
+      modal: () => this.modalValue,
+      reasons: true,
+      vetoMountAutoFocus: true,
+      activateLayers: (content) => this.#activateLayers(content),
+      onOpen: (content, { seed }) => this.#opened(seed),
+      onHidden: () => this.#command()?.reset(),
+      insideAlso: (origin) => this.multipleValue && Boolean(this.#chips()?.contains(origin)),
+      onDismiss: (event) => { this.#dismissedEvent = event.detail?.originalEvent ?? null }
+    })
 
     const content = this.#content()
 
@@ -147,29 +154,7 @@ export default class ComboboxController extends Controller {
     this.#applied = serverValue
     this.#apply(serverValue, { silent: true, force: true })
 
-    this.#connected = true
-
-    if (this.#isOpen()) {
-      if (content) {
-        this.#activateLayers(content)
-        this.#portalPinned(content)
-      }
-      this.openValue = true
-    } else if (this.openValue) {
-      this.#show("trigger-press")
-    }
-  }
-
-  // The reconcile path portals ONE FRAME LATE: connect order within a boot
-  // is unordered, and portaling before the sibling popper's connect would
-  // rob it of its content target before it could cache the node.
-  #portalPinned(content) {
-    window.requestAnimationFrame(() => {
-      if (!this.#connected || !this.#isOpen()) return
-
-      this.#portal.portal(content, { container: resolvePortalContainer(this.element) })
-      this.element.setAttribute(POPPER_STRATEGY, "absolute")
-    })
+    this.#overlay.connect()
   }
 
   /**
@@ -178,7 +163,7 @@ export default class ComboboxController extends Controller {
    * dropped when the home is gone - never stranded).
    */
   disconnect() {
-    this.#connected = false
+    this.#overlay?.disconnect()
     teardown(this)
   }
 
@@ -190,7 +175,7 @@ export default class ComboboxController extends Controller {
    * @param {boolean} value
    */
   openValueChanged(value) {
-    if (!this.#connected) return
+    if (!this.#overlay?.connected()) return
 
     if (value && !this.#isOpen()) this.#show("trigger-press")
     else if (!value && this.#isOpen()) this.#hide("none")
@@ -203,7 +188,7 @@ export default class ComboboxController extends Controller {
    * @param {string} value
    */
   valueValueChanged(value) {
-    if (!this.#connected) return
+    if (!this.#overlay?.connected()) return
 
     if (this.multipleValue) {
       const values = this.#listValues(value)
@@ -522,105 +507,31 @@ export default class ComboboxController extends Controller {
   // --- open / close ---
 
   #show(reason, { seed = "" } = {}) {
-    const content = this.#content()
-
-    if (!content || this.#isOpen()) return
-
-    this.#presence.cancel(content)
-    this.#suppressRestore = false
-
-    const expander = this.#expander()
-
-    // Portal-on-open: move BEFORE the
-    // enter presence (reparenting mid-animation restarts it), re-anchor
-    // absolute - static under compositor scroll, transform-immune. In
-    // multiple mode only the popup (listbox) moves; the chips field with
-    // its inline input stays home as the popper anchor.
-    this.#portal.portal(content, { container: resolvePortalContainer(this.element) })
-    this.element.setAttribute(POPPER_STRATEGY, "absolute")
-
-    content.hidden = false
-    content.setAttribute("data-open-reason", reason)
-    if (seed) content.setAttribute("data-open-seed", seed)
-    else content.removeAttribute("data-open-seed")
-    expander?.setAttribute("aria-expanded", "true")
-    if (expander) setState(expander, "popup-open")
-    this.#presence.enter(content)
-    this.#activateLayers(content)
-    this.openValue = true
-
-    // Layer controllers connect on the attribute-mutation microtask; focus
-    // rides one behind so focus-scope has snapshotted the trigger.
-    queueMicrotask(() => {
-      if (!this.#isOpen()) return
-
-      const input = this.#input()
+    this.#overlay.show(reason, { seed: seed || null })
+  }
 
-      // FOCUS GOES TO THE INPUT for every reason (the typing-session call);
-      // the selected option is communicated by highlight, not focus.
-      input?.focus()
+  // The open microtask: focus the input, seed the filter or highlight
+  // the selected (else the first enabled) option.
+  #opened(seed) {
+    const input = this.#input()
 
-      if (seed && input) {
-        input.value = seed
-        // The engine's own action runs the pass (and re-seats highlight).
-        input.dispatchEvent(new Event("input", { bubbles: true }))
-      } else {
-        // Seed the highlight on the COMMITTED option via the Command
-        // controller (activedescendant + scrollIntoView) - first enabled
-        // when no value (the engine cannot seat while the popup was
-        // hidden, so the shell seeds every open).
-        const items = this.#items()
-        const target = items.find((item) => item.getAttribute("aria-selected") === "true") ??
-          items.find((item) => !item.hasAttribute("data-disabled") && !item.closest("[hidden]"))
-
-        if (target) this.#command()?.highlightItem(target)
-      }
+    input?.focus()
+    if (seed && input) {
+      input.value = seed
+      input.dispatchEvent(new Event("input", { bubbles: true }))
+    } else {
+      const items = this.#items()
+      const target = items.find((item) => item.getAttribute("aria-selected") === "true") ??
+        items.find((item) => !item.hasAttribute("data-disabled") && !item.closest("[hidden]"))
 
-      this.dispatch("open", { prefix: EVENT_PREFIX, detail: seed ? { reason, seed } : { reason } })
-    })
+      if (target) this.#command()?.highlightItem(target)
+    }
   }
 
   #hide(reason, { restoreFocus = true } = {}) {
-    const content = this.#content()
-
-    if (!content || !this.#isOpen()) return
-
-    this.#suppressRestore = !restoreFocus || (reason === "outside-press" && !this.modalValue)
-
-    const expander = this.#expander()
-
-    expander?.setAttribute("aria-expanded", "false")
-    if (expander) setState(expander, "popup-closed")
-    content.removeAttribute("data-open-reason")
-    content.removeAttribute("data-open-seed")
-    this.openValue = false
-
-    this.#presence.exit(content, {
-      onRemove: () => {
-        content.hidden = true
-        // Home AFTER the exit finished and hidden landed; focus
-        // return is focus-scope's ref-based job, indifferent to the move.
-        this.#portal.restore(content)
-        this.element.setAttribute(POPPER_STRATEGY, "fixed")
-        this.#layers.deactivate(content, CONTENT_LAYER_CONTROLLERS)
-        // Reset the query so reopen starts clean (a remount would get
-        // this for free; persistent DOM does it deliberately).
-        this.#command()?.reset()
-        this.dispatch("closed", { prefix: EVENT_PREFIX, detail: { reason } })
-      }
-    })
+    this.#overlay.hide(reason, { restoreFocus })
   }
 
-  // --- the commit pipeline ---
-
-  // Command's select event is the ONLY commit trigger (no click handling
-  // here - the composition boundary). Cancelable BEFORE the value commits;
-  // vetoing keeps the popup open. Committing the already-selected value is
-  // IDEMPOTENT: close, value unchanged, no change events (deselection is a
-  // form affordance - include_blank - not a hidden toggle gesture).
-  // multiple INVERTS both rules: selection TOGGLES membership
-  // (appended at the array END) and the popup STAYS OPEN; a typed query
-  // clears immediately so the full list is restored for the next pick.
   #onCommandSelect = (event) => {
     const { item, value = "", label = "" } = event.detail ?? {}
 
@@ -843,10 +754,7 @@ export default class ComboboxController extends Controller {
   #wireContent(content) {
     useListen(this, content, "keydown", this.#onKeydown)
     useListen(this, content, "poetry:command:select", this.#onCommandSelect)
-    useListen(this, content, "poetry--core--dismissable:interact-outside", this.#onInteractOutside)
-    useListen(this, content, "poetry--core--dismissable:dismiss", this.#onDismiss)
-    useListen(this, content, "poetry--core--focus-scope:mount-auto-focus", this.#onMountAutoFocus)
-    useListen(this, content, "poetry--core--focus-scope:unmount-auto-focus", this.#onUnmountAutoFocus)
+    this.#overlay.wire()
   }
 
   // Tab while open CLOSES WITHOUT COMMIT and lets focus proceed (Popover
@@ -895,38 +803,6 @@ export default class ComboboxController extends Controller {
   // trailing click re-opens). In multiple, a press in the chips FIELD is
   // an anchor press too - vetoing the layer keeps the popup open while
   // chips mutate under the pointer.
-  #onInteractOutside = (event) => {
-    if (event.target !== this.#content()) return
-
-    const origin = event.detail?.originalEvent?.target
-
-    if (!(origin instanceof Element)) return
-    if (this.#trigger()?.contains(origin)) return event.preventDefault()
-    if (this.multipleValue && this.#chips()?.contains(origin)) event.preventDefault()
-  }
-
-  // Esc / outside press arrive as the dismissable layer's dismiss event.
-  // Neither EVER commits - the value is untouched (family rule).
-  #onDismiss = (event) => {
-    if (event.target !== this.#content()) return
-
-    const escaped = event.detail?.originalEvent?.type === "keydown"
-
-    // Remembered so the SAME keypress cannot double as the closed-popup
-    // Escape wipe in the multiple input map.
-    this.#dismissedEvent = event.detail?.originalEvent ?? null
-    this.#hide(escaped ? "escape-key" : "outside-press")
-  }
-
-  // The combobox owns initial focus (the command input), not focus-scope.
-  #onMountAutoFocus = (event) => {
-    if (event.target === this.#content()) event.preventDefault()
-  }
-
-  #onUnmountAutoFocus = (event) => {
-    if (event.target === this.#content() && this.#suppressRestore) event.preventDefault()
-  }
-
   // --- the layer stack (Select's proven mechanism, MINUS roving-focus) ---
 
   #activateLayers(content) {
@@ -938,8 +814,6 @@ export default class ComboboxController extends Controller {
     content.setAttribute(
       "data-poetry--core--dismissable-disable-outside-pointer-events-value", String(this.modalValue)
     )
-
-    this.#layers.activate(content, CONTENT_LAYER_CONTROLLERS)
   }
 
 
@@ -1065,9 +939,7 @@ export default class ComboboxController extends Controller {
   }
 
   #isOpen() {
-    const content = this.#content()
-
-    return Boolean(content) && stateOf(content) === "open"
+    return this.#overlay.isOpen()
   }
 
   #items() {

data/app/javascript/poetry/core/command_controller.js

@@ -347,6 +347,9 @@ export default class CommandController extends Controller {
     const empty = list.querySelector(EMPTY_SELECTOR) ?? this.element.querySelector(EMPTY_SELECTOR)
 
     if (empty) empty.hidden = visible !== 0
+    // The list says so too, so a theme can restyle it (the source drops
+    // the list padding when only the empty message shows).
+    list.toggleAttribute("data-empty", visible === 0)
 
     // Re-seat: highest score among visible ∩ enabled, first-in-DOM
     // tiebreak (strictly-greater replacement preserves DOM order as the