poetry-core 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1831a4d45731d76d83cfdbb9a65b20433a32bf7c57a15297f7838e04d0a55c21
-  data.tar.gz: a65f3175560897a70c6f2f8e29d3373bf3c5ef02f7baae20c35fcc3ddb4b3b6f
+  metadata.gz: fc22978b709fc22e859b79edce9929b57a358c7fec1969176f5f3d82e8dacd7a
+  data.tar.gz: 0765f9ded7f711d893f11dba287c2e4014b05a2906e9a3bb3ecf72e3249d7b94
 SHA512:
-  metadata.gz: 2f77187b648438d1e648956744425e82efbeb28f4b8efe0aa19b04ec647db0420bc6320405f01ccb938d6594856974c26702a2572c972a5a71134c16afa67e85
-  data.tar.gz: 59f36c4032dc99a6643486ae88f1cacfe71cf7f1ab94f046ee22654276feba9baa4a95244bfa8a011edd2731d269a8dee2408b458e00d00c52367d38076ee647
+  metadata.gz: 342c1ca9b06f0945c31deb4dab0e25c56e52d2f2afa9ec6dbda9173f1be20e4df699385d070aeb90bbc81a0d43438476c0e3d4a361ca980ea6f4fb163de670cd
+  data.tar.gz: a0a1285525f488233c29823543cb111ea2afc18fc1d2342d3ece955f0770538604367131c82f18792d4a6137bcaa9c1e87e12d7a991d6decd23f1484842393a6

data/.jsdoc_floor

@@ -1 +1 @@
-605
+586

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [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
+
+- The per-connect scope for Stimulus controllers, `@poetry/controllers/helpers/scope`: `scopeOf(controller)` hands out one disposer stack per connect, `teardown(controller)` runs it newest first, aborts the scope's signal and drops it, and the next `connect()` starts clean (Stimulus keeps one instance per element and re-runs `connect()`, which the suite now pins). A controller's `disconnect()` is that one line.
+- Ten behaviors over it, under `@poetry/controllers/behaviors/`: `useListen`, `useEscape`, `useBeforeCache`, `usePresence`, `usePortal`, `useScrollLock`, `useAnnounce`, `useLayers`, `useTypeahead` and `useMobile`. Each is a plain function that does its setup, registers its undo in the scope and returns a handle; none assigns onto the controller. `usePresence` tracks exits per node, so an enter interrupts that node's exit alone; `usePortal` restores every node it moved at teardown, newest first; `useScrollLock` is idempotent per instance; `useLayers` is the one implementation of the layer-token add and remove.
+- A fourth source-scan gate, `behaviors_teardown.test.js`: a controller that uses the scope without `teardown(this)` in its `disconnect()`, or a subclass that overrides `disconnect()` without `super.disconnect()`, fails the suite.
+
+### Changed
+
+- Sixteen controllers run their lifecycle through the scope: the seven hand-rolled `#wired` lists (combobox, hover card, menu, popover, select, toast, tooltip), the `#unsubscribe` fields (dialog, dismissable, navigation menu, sidebar, deferred), the six copies of the layer-token add and remove, the typeahead and scroll-lock instances, and the message scroller's raw before-cache string. Rendered markup and behaviour are unchanged; the suites, the dommy tier and a browser pass are the oracle.
+
+### Fixed
+
+- Three teardown leaks: a typeahead's reset timer outlived its controller (menu, select, tree), a date field's four per-segment listeners were never removed, and a submenu re-opened while its exit was still running had that exit's removal hide the re-opened level (the sub exits carried no cancel; the per-node presence gives them one).
+- A composed trigger lists its own wiring ahead of the caller's actions again. `Attributes` unified the flat and nested spellings of `data-action` and `data-controller` by appending the flat tokens after the nested ones whichever came first, so a Button composed as a Collapsible, Popover, Tooltip or DropdownMenu trigger rendered the caller's `data: { action: }` ahead of the component's `data-action`. Stimulus runs actions in attribute order, and a caller's action written to read the state the toggle leaves behind read the state before it instead: the docs sidebar remembered each disclosure as the opposite of what was chosen. The two spellings now keep the order the hash gave them.
+- A subclass without a `Style` sidecar of its own renders through its parent's dictionary. `Acme::Badge2 < Poetry::Ui::Badge::Component` with nothing beside it rendered no class attribute at all, in any mode, with no message: the dictionary lookup stopped at the class's own name. It now walks up to the nearest ancestor with a sidecar, short of `Poetry::Core::Component`, so a bare subclass renders what its parent renders and a sidecar of its own still takes over. A component built directly on the base with no sidecar stays dictionaryless, as before.
+
 ## [0.1.9] - 2026-09-30
 
 ### Added

data/app/components/poetry/core/concerns/styles.rb

@@ -161,11 +161,26 @@ module Poetry
             style_attributes.include?(name.to_sym)
           end
 
-          # Automatically determines the corresponding Style class for this component.
-          # Example: Poetry::Core::Dot::Component -> Poetry::Core::Dot::Style
+          # The dictionary this component renders through: its own sidecar
+          # Style by the naming convention (Poetry::Core::Dot::Component ->
+          # Poetry::Core::Dot::Style), else the nearest ancestor's. A bare
+          # subclass (`Acme::Badge2 < Poetry::Ui::Badge::Component` with no
+          # `Acme::Badge2::Style`) keeps rendering the classes its parent
+          # renders, the way a subclass keeps the parent's methods; a
+          # sidecar of its own takes over, extending a copy of the parent's
+          # dictionary. A component with no dictionary anywhere in its
+          # chain (Icon) has none.
           #
-          # @return [Class, nil] the style class if it exists, nil otherwise
+          # @return [Class, nil] the style class, or nil when neither this
+          #   class nor an ancestor below Poetry::Core::Component has one
           def style_class
+            own_style_class || inherited_style_class
+          end
+
+          private
+
+          # This class's own sidecar Style, by name, or nil.
+          def own_style_class
             style_class_name = component_module + STYLE_CLASS_SUFFIX
             style_class_name.constantize
           rescue NameError => e
@@ -178,7 +193,15 @@ module Poetry
             nil
           end
 
-          private
+          # The dictionary of the nearest ancestor that has one, stopping
+          # short of Poetry::Core::Component: the base class owns no
+          # component dictionary, so a component built directly on it with
+          # no sidecar stays dictionaryless.
+          def inherited_style_class
+            return nil if superclass == Poetry::Core::Component || !superclass.respond_to?(:style_class)
+
+            superclass.style_class
+          end
 
           # Extracts and processes style-specific options from the options hash.
           #

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

@@ -0,0 +1,18 @@
+// useAnnounce: the shared live regions held for one connect, over the
+// announce helper; the refcount is released at teardown.
+import { acquire, announce, release } from "@poetry/controllers/helpers/announce"
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Takes a refcount on the shared live regions until teardown(controller)
+ * and hands back the announcement surface.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @returns {(message: string, politeness?: "polite" | "assertive") => void} announce
+ */
+export function useAnnounce(controller) {
+  acquire()
+  scopeOf(controller).defer(release)
+
+  return announce
+}

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

@@ -0,0 +1,15 @@
+// useBeforeCache: Turbo's before-cache moment for one connect, over the
+// turbo_cache helper; the unsubscribe is registered for you.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+import { onBeforeCache } from "@poetry/controllers/helpers/turbo_cache"
+
+/**
+ * Subscribes `callback` to turbo:before-cache until teardown(controller).
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {(event: Event) => void} callback - must finish synchronously
+ * @returns {() => void} unsubscribes early; teardown unsubscribes otherwise
+ */
+export function useBeforeCache(controller, callback) {
+  return scopeOf(controller).defer(onBeforeCache(callback))
+}

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

@@ -0,0 +1,16 @@
+// useEscape: capture-phase Escape handling (IME cancels filtered) for one
+// connect, over the escape helper; the unsubscribe is registered for you.
+import { onEscapeKeydown } from "@poetry/controllers/helpers/escape"
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Subscribes `callback` to Escape keydowns until teardown(controller).
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {(event: KeyboardEvent) => void} callback - the handler
+ * @param {Object} [options] - the escape helper's options (capture, target)
+ * @returns {() => void} unsubscribes early; teardown unsubscribes otherwise
+ */
+export function useEscape(controller, callback, options) {
+  return scopeOf(controller).defer(onEscapeKeydown(callback, options))
+}

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

@@ -0,0 +1,55 @@
+// useLayers: the runtime layer activation (focus-scope, dismissable,
+// roving-focus stacked onto content while it is open) for one connect.
+// One implementation of the data-controller token add and remove that
+// six overlay controllers each carried; what is still active at teardown
+// is deactivated, so a torn-down overlay leaves no layer controller alive
+// on an orphaned node.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Layer activation over the controller's current scope.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @returns {{ activate: (element: Element, identifiers: string[]) => void,
+ *   deactivate: (element: Element, identifiers: string[]) => void }}
+ */
+export function useLayers(controller) {
+  const active = new Map()
+
+  const deactivate = (element, identifiers) => {
+    const tokens = (element.getAttribute("data-controller") ?? "")
+      .split(/\s+/)
+      .filter((token) => token && !identifiers.includes(token))
+
+    element.setAttribute("data-controller", tokens.join(" "))
+
+    const remaining = (active.get(element) ?? []).filter((token) => !identifiers.includes(token))
+
+    if (remaining.length > 0) active.set(element, remaining)
+    else active.delete(element)
+  }
+
+  scopeOf(controller).defer(() => {
+    for (const [element, identifiers] of [...active]) deactivate(element, identifiers)
+  })
+
+  return {
+    /**
+     * Adds the identifiers to the element's data-controller, once each.
+     * @param {Element} element
+     * @param {string[]} identifiers
+     * @returns {void}
+     */
+    activate(element, identifiers) {
+      const tokens = (element.getAttribute("data-controller") ?? "").split(/\s+/).filter(Boolean)
+
+      for (const identifier of identifiers) {
+        if (!tokens.includes(identifier)) tokens.push(identifier)
+      }
+
+      element.setAttribute("data-controller", tokens.join(" "))
+      active.set(element, [...new Set([...(active.get(element) ?? []), ...identifiers])])
+    },
+    deactivate
+  }
+}

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

@@ -0,0 +1,18 @@
+// useListen: a DOM listener that lives for one connect. Replaces the
+// hand-rolled `#wired` list seven controllers copied: the listener is
+// added now and removed at teardown(controller), newest first.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Adds `listener` to `target` for the controller's current connect.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {EventTarget} target - the element, document or window to listen on
+ * @param {string} type - the event type
+ * @param {EventListener} listener - the handler
+ * @param {AddEventListenerOptions | boolean} [options] - addEventListener's options
+ * @returns {() => void} removes the listener early; teardown removes it otherwise
+ */
+export function useListen(controller, target, type, listener, options) {
+  return scopeOf(controller).listen(target, type, listener, options)
+}

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

@@ -0,0 +1,16 @@
+// useMobile: the mobile-breakpoint watch for one connect, over the
+// breakpoint helper; the unwatch is registered for you.
+import { watchMobile } from "@poetry/controllers/helpers/breakpoint"
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Watches the mobile breakpoint until teardown(controller): `onChange`
+ * runs now with the current state and again on every crossing.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @param {(isMobile: boolean) => void} onChange - the handler
+ * @returns {() => void} unwatches early; teardown unwatches otherwise
+ */
+export function useMobile(controller, onChange) {
+  return scopeOf(controller).defer(watchMobile(onChange))
+}

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/behaviors/portal.js

@@ -0,0 +1,50 @@
+// usePortal: content moved to a portal container for one connect, over
+// the portal helper. Every node this instance portals is restored at
+// teardown (drop-never-strand: a node whose origin is gone is dropped by
+// the helper), so no controller writes its own restore-on-disconnect.
+import { portalContent, restoreContent } from "@poetry/controllers/helpers/portal"
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Portal moves over the controller's current scope.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @returns {{ portal: (content: Element, options?: Object) => boolean,
+ *   restore: (content: Element) => boolean }}
+ */
+export function usePortal(controller) {
+  const moved = new Set()
+
+  // Newest first: a sub level portaled after its parent goes home before
+  // the parent does, while its placeholder still sits inside the parent.
+  scopeOf(controller).defer(() => {
+    for (const content of [...moved].reverse()) restoreContent(content)
+    moved.clear()
+  })
+
+  return {
+    /**
+     * Moves `content` to the container; a no-op when already portaled.
+     * @param {Element} content
+     * @param {Object} [options] - the portal helper's options (container)
+     * @returns {boolean} true when the move happened
+     */
+    portal(content, options) {
+      const happened = portalContent(content, options)
+
+      if (happened) moved.add(content)
+
+      return happened
+    },
+    /**
+     * Returns `content` home now.
+     * @param {Element} content
+     * @returns {boolean} true when the content went home
+     */
+    restore(content) {
+      moved.delete(content)
+
+      return restoreContent(content)
+    }
+  }
+}

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

@@ -0,0 +1,85 @@
+// usePresence: enter and exit animations for one connect, over the
+// presence helper, with the pending exits tracked PER NODE. An exit's
+// cancel used to live in one `#cancelExit` slot per controller, which a
+// second exiting node (NavigationMenu's lesson) silently overwrote; here
+// every node keeps its own, an enter interrupts that node's exit alone,
+// and teardown abandons whatever is still exiting without running its
+// removal (an interrupted exit, never a removal from a torn-down scope).
+import { enterPresence, exitPresence } from "@poetry/controllers/helpers/presence"
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+
+/**
+ * Presence over the controller's current scope.
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @returns {{ enter: (element: HTMLElement, options?: Object) => HTMLElement,
+ *   exit: (element: HTMLElement, options?: Object) => () => void,
+ *   cancel: (element: HTMLElement) => boolean,
+ *   exiting: (element: HTMLElement) => boolean }}
+ */
+export function usePresence(controller) {
+  const pending = new Map()
+
+  const cancel = (element) => {
+    const abandon = pending.get(element)
+
+    if (!abandon) return false
+
+    pending.delete(element)
+    abandon()
+
+    return true
+  }
+
+  scopeOf(controller).defer(() => {
+    for (const abandon of [...pending.values()]) abandon()
+    pending.clear()
+  })
+
+  return {
+    /**
+     * Runs the entry on `element`, interrupting an exit of the same node.
+     * @param {HTMLElement} element
+     * @param {Object} [options] - the presence helper's enter options
+     * @returns {HTMLElement} the element
+     */
+    enter(element, options) {
+      cancel(element)
+
+      return enterPresence(element, options)
+    },
+    /**
+     * Runs the exit on `element`; `options.onRemove` runs once the exit
+     * finishes, unless an enter or a teardown interrupts it first.
+     * @param {HTMLElement} element
+     * @param {Object} [options] - the presence helper's exit options
+     * @param {() => void} [options.onRemove] - the caller's removal step
+     * @returns {() => void} abandons this exit without removal
+     */
+    exit(element, { onRemove, ...options } = {}) {
+      cancel(element)
+
+      let settled = false
+      const abandon = exitPresence(element, {
+        ...options,
+        onRemove: () => {
+          settled = true
+          pending.delete(element)
+          onRemove?.()
+        }
+      })
+
+      // A node without an exit animation settled inside the call.
+      if (!settled) pending.set(element, abandon)
+
+      return () => cancel(element)
+    },
+    cancel,
+    /**
+     * Whether `element` is mid-exit.
+     * @param {HTMLElement} element
+     * @returns {boolean}
+     */
+    exiting: (element) => pending.has(element)
+  }
+}