poetry-core 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1831a4d45731d76d83cfdbb9a65b20433a32bf7c57a15297f7838e04d0a55c21
-  data.tar.gz: a65f3175560897a70c6f2f8e29d3373bf3c5ef02f7baae20c35fcc3ddb4b3b6f
+  metadata.gz: f473efd9c0d12c6d6c8df6fd9273881e7c47ae51049041ec77b4e8ca1cbd4287
+  data.tar.gz: 87b7bc488972de80728431ab4888b9160c9a7676ae5f956ff155fe0fa52c6cad
 SHA512:
-  metadata.gz: 2f77187b648438d1e648956744425e82efbeb28f4b8efe0aa19b04ec647db0420bc6320405f01ccb938d6594856974c26702a2572c972a5a71134c16afa67e85
-  data.tar.gz: 59f36c4032dc99a6643486ae88f1cacfe71cf7f1ab94f046ee22654276feba9baa4a95244bfa8a011edd2731d269a8dee2408b458e00d00c52367d38076ee647
+  metadata.gz: 167f3b0a36846778aeda28b072567ed91af0a67c3f55c1eeae79db7785afc4a947a71314d7e2895cf2205dd829eabbfa88a4d1365a5b7a0d423fd8d7fddf6181
+  data.tar.gz: 249b441648327a54d8d906a526c269e8194add9badd1468111636ab03d7499962cd9949f6c981c8e0a158cceb41d1e1490e3f18d2414e48786dab70c90b2466f

data/.jsdoc_floor

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

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [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/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)
+  }
+}

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

@@ -0,0 +1,41 @@
+// useScrollLock: the body scroll lock for one connect, over the
+// scroll_lock helper. Idempotent per instance (the dialog's `#locked`
+// flag, generalized): lock twice holds one refcount, unlock when not
+// locked is a no-op, and teardown balances a lock still held.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+import { lockScroll, unlockScroll } from "@poetry/controllers/helpers/scroll_lock"
+
+/**
+ * A per-instance scroll lock, balanced at teardown(controller).
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @returns {{ lock: () => void, unlock: () => void, locked: () => boolean }}
+ */
+export function useScrollLock(controller) {
+  let locked = false
+
+  const unlock = () => {
+    if (!locked) return
+
+    locked = false
+    unlockScroll()
+  }
+
+  scopeOf(controller).defer(unlock)
+
+  return {
+    /** Takes the instance's one refcount on the body lock. */
+    lock() {
+      if (locked) return
+
+      locked = true
+      lockScroll()
+    },
+    unlock,
+    /**
+     * Whether this instance holds its refcount.
+     * @returns {boolean}
+     */
+    locked: () => locked
+  }
+}

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

@@ -0,0 +1,21 @@
+// useTypeahead: one typeahead per connect, over the typeahead helper,
+// with its buffer timer reset at teardown - the leak the hand-rolled
+// field initializers (menu, select, tree) never closed.
+import { scopeOf } from "@poetry/controllers/helpers/scope"
+import { createTypeahead } from "@poetry/controllers/helpers/typeahead"
+
+/**
+ * A typeahead instance whose pending timer is cleared at
+ * teardown(controller).
+ *
+ * @param {Object} controller - the Stimulus controller instance
+ * @returns {{ pending: () => boolean, reset: () => void,
+ *   search: (key: string, items: Element[], options?: Object) => Element | null }}
+ */
+export function useTypeahead(controller) {
+  const typeahead = createTypeahead()
+
+  scopeOf(controller).defer(() => typeahead.reset())
+
+  return typeahead
+}

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

@@ -1,8 +1,12 @@
 import { Controller } from "@hotwired/stimulus"
 import { collectionItems } from "@poetry/controllers/helpers/collection"
 import { isImeKeydown } from "@poetry/controllers/helpers/escape"
-import { isPortaled, portalContent, resolvePortalContainer, restoreContent } from "@poetry/controllers/helpers/portal"
-import { enterPresence, exitPresence } from "@poetry/controllers/helpers/presence"
+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 { teardown } from "@poetry/controllers/helpers/scope"
 import { setState, stateOf } from "@poetry/controllers/helpers/state"
 import { tabbableWithin } from "@poetry/controllers/helpers/tabbable"
 
@@ -99,9 +103,10 @@ export default class ComboboxController extends Controller {
   }
 
   #connected = false
-  #wired = []
   #suppressRestore = false
-  #cancelExit = null
+  #presence = null
+  #portal = null
+  #layers = null
   #applied = ""
   #placeholder = ""
   #dismissedEvent = null
@@ -113,6 +118,10 @@ 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)
+
     const content = this.#content()
 
     if (content) this.#wireContent(content)
@@ -121,7 +130,7 @@ export default class ComboboxController extends Controller {
 
     // The chips FIELD is a second wired keyboard surface in multiple
     // (Tab-out closes from the inline input exactly like from the popup).
-    if (chips) this.#listen(chips, "keydown", this.#onKeydown)
+    if (chips) useListen(this, chips, "keydown", this.#onKeydown)
 
     const display = this.#display()
 
@@ -158,27 +167,19 @@ export default class ComboboxController extends Controller {
     window.requestAnimationFrame(() => {
       if (!this.#connected || !this.#isOpen()) return
 
-      portalContent(content, { container: resolvePortalContainer(this.element) })
+      this.#portal.portal(content, { container: resolvePortalContainer(this.element) })
       this.element.setAttribute(POPPER_STRATEGY, "absolute")
     })
   }
 
   /**
-   * Restores portaled content (drop-never-strand) and unwires everything.
+   * Tears the scope down: the content and chips listeners, a pending
+   * exit, the layer tokens and portaled content (restored home, or
+   * dropped when the home is gone - never stranded).
    */
   disconnect() {
     this.#connected = false
-
-    // Never leave content stranded at the container (drop-never-strand).
-    const content = this.#content()
-
-    if (content) restoreContent(content)
-
-    for (const [target, type, listener] of this.#wired) target.removeEventListener(type, listener)
-
-    this.#wired = []
-    this.#cancelExit?.()
-    this.#cancelExit = null
+    teardown(this)
   }
 
   // --- controllable state ---
@@ -525,8 +526,7 @@ export default class ComboboxController extends Controller {
 
     if (!content || this.#isOpen()) return
 
-    this.#cancelExit?.()
-    this.#cancelExit = null
+    this.#presence.cancel(content)
     this.#suppressRestore = false
 
     const expander = this.#expander()
@@ -536,7 +536,7 @@ export default class ComboboxController extends Controller {
     // 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.
-    portalContent(content, { container: resolvePortalContainer(this.element) })
+    this.#portal.portal(content, { container: resolvePortalContainer(this.element) })
     this.element.setAttribute(POPPER_STRATEGY, "absolute")
 
     content.hidden = false
@@ -545,7 +545,7 @@ export default class ComboboxController extends Controller {
     else content.removeAttribute("data-open-seed")
     expander?.setAttribute("aria-expanded", "true")
     if (expander) setState(expander, "popup-open")
-    enterPresence(content)
+    this.#presence.enter(content)
     this.#activateLayers(content)
     this.openValue = true
 
@@ -595,15 +595,14 @@ export default class ComboboxController extends Controller {
     content.removeAttribute("data-open-seed")
     this.openValue = false
 
-    this.#cancelExit = exitPresence(content, {
+    this.#presence.exit(content, {
       onRemove: () => {
-        this.#cancelExit = null
         content.hidden = true
         // Home AFTER the exit finished and hidden landed; focus
         // return is focus-scope's ref-based job, indifferent to the move.
-        restoreContent(content)
+        this.#portal.restore(content)
         this.element.setAttribute(POPPER_STRATEGY, "fixed")
-        this.#removeControllers(content, CONTENT_LAYER_CONTROLLERS)
+        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()
@@ -842,17 +841,12 @@ export default class ComboboxController extends Controller {
   // --- content wiring (programmatic: portal-safe) ---
 
   #wireContent(content) {
-    this.#listen(content, "keydown", this.#onKeydown)
-    this.#listen(content, "poetry:command:select", this.#onCommandSelect)
-    this.#listen(content, "poetry--core--dismissable:interact-outside", this.#onInteractOutside)
-    this.#listen(content, "poetry--core--dismissable:dismiss", this.#onDismiss)
-    this.#listen(content, "poetry--core--focus-scope:mount-auto-focus", this.#onMountAutoFocus)
-    this.#listen(content, "poetry--core--focus-scope:unmount-auto-focus", this.#onUnmountAutoFocus)
-  }
-
-  #listen(target, type, listener) {
-    target.addEventListener(type, listener)
-    this.#wired.push([target, type, listener])
+    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)
   }
 
   // Tab while open CLOSES WITHOUT COMMIT and lets focus proceed (Popover
@@ -945,26 +939,9 @@ export default class ComboboxController extends Controller {
       "data-poetry--core--dismissable-disable-outside-pointer-events-value", String(this.modalValue)
     )
 
-    this.#addControllers(content, CONTENT_LAYER_CONTROLLERS)
+    this.#layers.activate(content, CONTENT_LAYER_CONTROLLERS)
   }
 
-  #addControllers(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(" "))
-  }
-
-  #removeControllers(element, identifiers) {
-    const tokens = (element.getAttribute("data-controller") ?? "")
-      .split(/\s+/)
-      .filter((token) => token && !identifiers.includes(token))
-
-    element.setAttribute("data-controller", tokens.join(" "))
-  }
 
   // --- structural resolution (ids are the seams; portal/stream-safe) ---
 

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

@@ -1,4 +1,6 @@
 import { Controller } from "@hotwired/stimulus"
+import { useListen } from "@poetry/controllers/behaviors/listen"
+import { teardown } from "@poetry/controllers/helpers/scope"
 import {
   IncompleteDate, PAGE_STEP, resolveHourCycle
 } from "@poetry/controllers/helpers/incomplete_date"
@@ -80,17 +82,16 @@ export default class DateFieldController extends Controller {
 
     // Native required validation fires on the (visually hidden) input;
     // route the browser's focus request to the first empty segment.
-    this.inputTarget.addEventListener("invalid", this.#onInvalid)
-    document.addEventListener("selectionchange", this.#onSelectionChange)
+    useListen(this, this.inputTarget, "invalid", this.#onInvalid)
+    useListen(this, document, "selectionchange", this.#onSelectionChange)
   }
 
   /**
-   * Restores the native input's tab order / AT visibility and unwires the
-   * document listeners.
+   * Restores the native input's tab order / AT visibility and tears the
+   * scope down: the input, document and per-segment listeners.
    */
   disconnect() {
-    this.inputTarget?.removeEventListener("invalid", this.#onInvalid)
-    document.removeEventListener("selectionchange", this.#onSelectionChange)
+    teardown(this)
     this.element.removeAttribute("data-enhanced")
     this.inputTarget?.removeAttribute("tabindex")
     this.inputTarget?.removeAttribute("aria-hidden")
@@ -232,10 +233,10 @@ export default class DateFieldController extends Controller {
 
     span.style.caretColor = "transparent"
 
-    span.addEventListener("keydown", (event) => this.#onKeydown(event, span, type))
-    span.addEventListener("beforeinput", (event) => this.#onBeforeinput(event, span, type))
-    span.addEventListener("input", (event) => this.#onInput(event, span, type))
-    span.addEventListener("focus", () => { this.#entered = "" })
+    useListen(this, span, "keydown", (event) => this.#onKeydown(event, span, type))
+    useListen(this, span, "beforeinput", (event) => this.#onBeforeinput(event, span, type))
+    useListen(this, span, "input", (event) => this.#onInput(event, span, type))
+    useListen(this, span, "focus", () => { this.#entered = "" })
 
     return span
   }