poetry-core 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be0bfa6a89f4e90c5ff4227fb55faae46a68c2d8b6a85fbe7b954fe1a859314b
-  data.tar.gz: 466897acf54b0ada006299af237b50c8d32fe5ee846c8cac5d4b29723e93d33a
+  metadata.gz: f473efd9c0d12c6d6c8df6fd9273881e7c47ae51049041ec77b4e8ca1cbd4287
+  data.tar.gz: 87b7bc488972de80728431ab4888b9160c9a7676ae5f956ff155fe0fa52c6cad
 SHA512:
-  metadata.gz: d8d10b2fce56d3217292ff638aec3f3680202278f28144ed5a2a91c6f92fd51d2ea288b3b67987a9edc27fc3cb9e1c20e9fab94f44a22596553c98abb8ca69a6
-  data.tar.gz: 75db75e6f640a176bf84d99d64f8c4e354fcc563c1f01892b83af1d217ebd7879989d841cb62a4adef7e0a091c870e6bf5689f1410e0322b84fee7c3dc07fb2f
+  metadata.gz: 167f3b0a36846778aeda28b072567ed91af0a67c3f55c1eeae79db7785afc4a947a71314d7e2895cf2205dd829eabbfa88a4d1365a5b7a0d423fd8d7fddf6181
+  data.tar.gz: 249b441648327a54d8d906a526c269e8194add9badd1468111636ab03d7499962cd9949f6c981c8e0a158cceb41d1e1490e3f18d2414e48786dab70c90b2466f

data/.jsdoc_floor

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

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # 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
+
+- `element_tag(name, ..., **attributes)`, on every component and in every view: the helper a template builds its elements through, and where a component's template spends what `root_attributes` and `element_attributes` build. It takes what `content_tag` takes and renders the same bytes, and it renders a void element the way `tag.input` does. A host that compiles its templates with Herb's slots has Action View's own tag helpers resolved into markup ahead of the render, and a splat or a tag name held in a variable does not survive that: the element comes out without its attributes, or the template stops compiling. A helper Herb does not know stays a call. Components written on the DSL in a host should build their elements the same way.
+- `poetry check` holds a component's template (an ERB file under `app/components/`) to the element rule, `element-tag`, as a warning: a tag helper handed a splat or a variable for its attributes, `content_tag` given a tag name that is not a literal, and `tag.attributes` handed a splat each name the `element_tag` call to write instead. A view is left alone: handing a tag helper a splat is valid Rails, and whether the host compiles with slots is not something a lint of the source can know.
+- `poetry check` compiles a component's HTML template under Herb, in the posture `bin/rails herb:check` holds an app's views to: the security validator, with the compiled Ruby checked for syntax. Rails renders HTML templates through Herb under its 8.2 defaults and its task walks the view paths, so a template under `app/components/` is outside its reach. Rails checks views, Poetry checks components. A template Herb refuses is a `herb-compile` finding that carries the engine's reason and its line: an error when the app renders through Herb, a warning until then. The runner compiles when it is handed the tier (`Check::Runner.new(catalog, compile:)`), and `Poetry::Core::TemplateCompile` takes `posture: :rails` for it beside the strict posture the gems' own gate runs.
+- `poetry check` holds a component class to the renderable rule, `renderable-reader`: an `option`, a `style` or a slot named `format` defines the reader Rails asks a component for the format of its template, and it answers with the declared value, so a render through the renderer raises `Invalid formats`. From Rails 8.2 every render in a view goes through the renderer, so the host's check reports it as an error there and as a warning before. A class that defines `format` itself, with `def` or `define_method`, is left alone: it keeps the keyword for its callers and reads the value under another name, which is what NumberField does.
+- `Poetry::Core::SlotMarkers.strip(html)` takes off what a slot compile writes around a template's own markup: the region, slot and branch comments, the `data-herb-slot` attribute and the branches parked in a `<template>`. What is left is the markup the template wrote, which is what a test in a host that compiles with slots means to compare.
+
+### Changed
+
+- The helpers of an app's own components (`helper :name`) are defined before the first view renders, not while the application is still initializing. The engine used to load every `app/components` directory from `to_prepare`, and a component is a view, so Action View loaded before initialization completed: Rails logs that in a boot that does not eager load, and raises on it when `config.action_on_early_load_hook` is `:raise`. A host that eager loads now syncs once its boot is done, with the classes already loaded; every other host syncs on its first view context, at render time; a reload syncs as before. `Poetry::Core::HostHelpers.sync_now!` is the sync, `ready?` says whether the first one has happened, and `HostHelpers::FirstView` is what Action View's base class gets for it.
+- The template compile gate (`rake herb:compile`, `Poetry::Core::TemplateCompile`) runs on Herb 0.11. It requires the engine itself, since `require "herb"` no longer loads it. It hands the engine every validator Herb ships, each one fatal, since from 0.11 the engine validates nothing it is not handed, and has the compiled Ruby checked for syntax. It lists parse and compile errors, which Herb now raises as syntax errors, where they used to pass the rescue and abort the run. A Herb older than 0.11.0 raises a setup error that names the version found.
+
 ## [0.1.8] - 2026-09-22
 
 ### Added

data/app/components/poetry/core/component.rb

@@ -39,6 +39,7 @@ module Poetry
       include ActiveModel::AttributeAssignment
       include ActiveModel::Validations
       include Poetry::Core::Contrib::WrappedHelper
+      include Poetry::Core::TagHelper
       include Poetry::Core::Concerns::Styles
       include Poetry::Core::Concerns::Options
       include Poetry::Core::Concerns::Stimulus
@@ -296,12 +297,12 @@ module Poetry
       #     super("role" => "status", "data-variant" => variant)
       #   end
       # @example The template
-      #   <%= tag.div(**root_attributes) do %>
+      #   <%= element_tag(:div, **root_attributes) do %>
       #
       # @param extra [Hash] the component's own root attributes; a
       #   `"data-slot"` here replaces the default
       # @return [Hash] the root's attributes, flat (`data-x`, `aria-x`,
-      #   booleans as the attribute name), for `tag` and `content_tag`
+      #   booleans as the attribute name), for {Poetry::Core::TagHelper#element_tag}
       def root_attributes(extra = {})
         own = { "data-slot" => root_slot }.merge(extra).merge(component_data_attributes)
         wired = self.class.stimulus_elements.key?(:root) ? :root : nil
@@ -335,7 +336,7 @@ module Poetry
       #     attrs["hidden"] = true unless open
       #     element_attributes(:content, attrs)
       #   end
-      #   # <%= tag.div(**content_attributes) do %>
+      #   # <%= element_tag(:div, **content_attributes) do %>
       #
       # @param part [Symbol, String, nil] the part; nil (or a Hash in its
       #   place) for markup with no part of its own
@@ -343,7 +344,7 @@ module Poetry
       # @param stimulus [Symbol, String, false, nil] the `use_stimulus`
       #   element whose wiring joins the markup: nil takes the part's own when
       #   one is declared, false takes none
-      # @return [Hash] the element's attributes, flat, for `tag` and `content_tag`
+      # @return [Hash] the element's attributes, flat, for {Poetry::Core::TagHelper#element_tag}
       def element_attributes(part = nil, attrs = {}, stimulus: nil)
         if part.is_a?(Hash)
           attrs = part

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
+}