poetry-core 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec837c1c31e39d20d47e278d7ae7dde0ff26f036f17e8bc33dcf81abd6daafdd
-  data.tar.gz: 650c0d9053220a0500ae619402dd92515248b0b6bfe960f85e874ace979f36af
+  metadata.gz: 9b4189654db2722eff128793c1bd4ce725c06a60ec1b7ff8bf29d5af7aa4e9ef
+  data.tar.gz: fb0245f3b9abff92ad3f9bdd48d3da7a5fc421531e346d40e3e53eadaf304233
 SHA512:
-  metadata.gz: d9e82544dcb308ba9feea37d8de5f2272bae3be011c59601c584f6b2b90f1156f6bfef8864d03b0d17c62308eba42e8f82572acfc55a7dd8ce3510c95266ca8a
-  data.tar.gz: b35b3d54fa5f02ebd98357a1c93cf4b89a0969a45c1793e15e782d23921cb670a52889fc888e0204dbde640bc0a83176c54ea8f285031f41802b12bbadbd45de
+  metadata.gz: 3c79e20564e016e6b3b7b34378bb6222ca8708279864235bfd0c8d2a7b899f56e229a53cb284dbec9b9601e91922fc6f9799353fc8c7ddac8d1fa5d8fba6ae0b
+  data.tar.gz: 73b7dc73529fb2c1782a343ef7ddac9228591fba3b73c57163a0cfab4f6066e26da0d573447af273605e0bc98e1ff40d0fe0917a770c56e873ec22714b563182

data/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-## [Unreleased]
+## [0.1.1] - 2026-09-08
+
+### Added
+
+- `identity:` on every component: the one sanctioned way for a component that renders as another component's root to name it (its `data-component`). Universal like `key:`, never an HTML attribute.
+- `poetry check` rule `reserved-attribute`: `data-component` passed through a helper, as a string key or `data: { component: }`, is an error.
+
+### Changed
+
+- The passthrough contract is enforced at render. A keyword that is not an option still renders as an HTML attribute on the root, but a near miss of a declared option (`varient:`) raises in development and test with a did-you-mean and logs in production; `data-component` is never overridable (raised in development and test, dropped in production); `data-slot` stays open as a composition seam. `poetry check`'s `unknown-option` finding is an error, no longer a warning.
+- `poetry--core--hover-card`: `touchGuard` (on touchstart) is replaced by `pointerDown` (on pointerdown). `poetry--core--number-field`: the `focus` action is removed. A host that wired either by hand updates the action strings; poetry-ui's components already have.
+- `css_mode :bem` is documented as the mode for kits authored on the DSL that write their own templates; poetry-ui is Tailwind-native and not a `:bem` consumer.
+
+### Fixed
+
+- HoverCard: a tap on the trigger keeps its click on touch devices. The touchstart guard cancelled the click; a pointerdown latch held through the tap's compatibility mouse events replaces it.
+- MessageScroller: `data-pending-scroll` holds the root and the viewport until the opening position (`end` or `last-anchor`) is applied, releases at once for an empty transcript, is stripped when a Turbo morph re-stamps it, and is re-armed at `turbo:before-cache`, so a server-rendered or restored transcript never shows the top of the thread first.
+- NumberField: a sideways trackpad gesture over a wheel-enabled field scrolls the page instead of stepping, Shift on the horizontal axis steps large, and an event with no movement is neither stepped nor cancelled. Focus keeps the browser's own selection (Tab selects the value, a click places the caret); the steppers park the caret at the end.
+- NavigationMenu: a disabled trigger never opens, by hover or click, and the arrows step over it; ArrowDown on a trigger opens its panel with focus staying on the trigger; removing the open trigger's item, as a morph can, closes the bar and drops its orphaned panel.
+- Drawer: the click that follows a press inside the panel never dismisses, so a drag against the clamp released over the backdrop no longer closes the sheet.
 
 ## [0.1.0] - 2026-09-05
 

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

@@ -145,14 +145,36 @@ module Poetry
         end
       end
 
+      # Keywords that are never options and never typos - the passthrough
+      # vocabulary the static check exempts too (Check::Catalog::PASSTHROUGH).
+      PASSTHROUGH_KEYS = %w[class id key webmcp identity data aria role style].freeze
+
+      # HTML attribute names a caller passes through on purpose. Exempt from
+      # the near-miss guard so `for:` never reads as a typo of a `form`
+      # option, `size:` on a component without a size axis stays the native
+      # attribute, and so on. Only keys that are NOT declared options reach
+      # the guard, so a declared option of the same name is untouched.
+      HTML_ATTRIBUTE_KEYS = %w[
+        accept accesskey action alt autocapitalize autocomplete autofocus checked cite cols colspan
+        contenteditable crossorigin datetime decoding dir dirname disabled download draggable enctype
+        enterkeyhint for form headers height hidden href hreflang inert inputmode is itemid itemprop
+        itemref itemscope itemtype label lang list loading max maxlength method min minlength multiple
+        name nonce novalidate open part pattern ping placeholder popover readonly referrerpolicy rel
+        required reversed rows rowspan scope selected size sizes slot span spellcheck src srcset start
+        step tabindex target title translate type value width wrap
+      ].freeze
+
       # The self-identification markup contract, the convention every
       # component follows: `data-component` on the component root maps live DOM
       # back to the component that rendered it - the hook agents, the
       # Verifier, and the browser-verification loop key on.
       #
+      # A component rendering as another's root passes identity: (the
+      # composition seam), and the root wears that name instead.
+      #
       # @return [Hash] e.g. { "data-component" => "button" }
       def component_data_attributes
-        { "data-component" => self.class.component_title }
+        { "data-component" => (@identity || self.class.component_title).to_s }
       end
 
       # `data-slot` for a named part of the component's anatomy
@@ -224,6 +246,14 @@ module Poetry
         @webmcp = attributes[:webmcp] || attributes["webmcp"]
         attributes = attributes.except(:webmcp, "webmcp") unless @webmcp.nil?
 
+        # identity: is the composition seam for a component that renders AS
+        # another component's root (ToastTrigger renders as a Button): the
+        # inner root wears the outer's data-component. Universal like key:,
+        # never an HTML attribute - and the ONLY sanctioned way to set
+        # data-component (the raw attribute is reserved, see guard_passthrough).
+        @identity = attributes[:identity] || attributes["identity"]
+        attributes = attributes.except(:identity, "identity") unless @identity.nil?
+
         # Initialize a fresh Set for this instance
         self.registered_styles = Set.new
         self.registered_options = Set.new
@@ -249,12 +279,77 @@ module Poetry
         end
 
         @attributes = self.class._default_attributes.deep_dup
-        html_attrs = attributes.with_indifferent_access.except(*attribute_names)
+        html_attrs = guard_passthrough(attributes.with_indifferent_access.except(*attribute_names))
         @html_attributes = Poetry::Core::HTML::Attributes.new(html_attrs)
 
         assign_attributes attributes.with_indifferent_access.slice(*attribute_names)
       end
 
+      # The passthrough contract, enforced at the seam. A keyword that is not
+      # an option renders as an HTML attribute on the root (title:, tabindex:,
+      # colspan:) - so a NEAR-MISS of a declared option (varient:) would
+      # silently render a bogus attribute while the default applied. That
+      # raises in development and test with the did-you-mean the static check
+      # gives, and only logs in production (the render still succeeds).
+      # data-component is the component's own identity - the hook agents,
+      # the Verifier and the browser loop key on - and is never overridable:
+      # dropped in production, raised the same way in development and test.
+      # data-slot is NOT reserved: re-slotting an embedded root is the
+      # composition seam a part contract allows; re-identifying one goes
+      # through identity:, the sanctioned spelling.
+      #
+      # @param html_attrs [ActiveSupport::HashWithIndifferentAccess]
+      # @return [ActiveSupport::HashWithIndifferentAccess] the attributes, minus a reserved override
+      def guard_passthrough(html_attrs)
+        problems = []
+
+        if html_attrs.key?("data-component")
+          problems << "data-component is #{passthrough_owner}'s own identity attribute and is never overridable"
+          html_attrs = html_attrs.except("data-component")
+        end
+        data = html_attrs["data"]
+        if data.respond_to?(:key?) && data.key?("component")
+          problems << "data: { component: } is #{passthrough_owner}'s own identity attribute and is never overridable"
+          html_attrs["data"] = data.except("component")
+        end
+
+        html_attrs.each_key do |key|
+          next if PASSTHROUGH_KEYS.include?(key) || HTML_ATTRIBUTE_KEYS.include?(key) || key.include?("-")
+
+          suggestion = option_suggestion(key)
+          next unless suggestion
+
+          problems << "#{passthrough_owner} has no option #{key}: (did you mean #{suggestion}:?) - " \
+                      "unknown keywords render as HTML attributes"
+        end
+        return html_attrs if problems.empty?
+
+        raise ArgumentError, problems.join("; ") if strict_passthrough?
+
+        Rails.logger&.warn("poetry: #{problems.join("; ")}") if defined?(Rails) && Rails.respond_to?(:logger)
+        html_attrs
+      end
+
+      # The did-you-mean against this component's declared options and
+      # styles, the same checker the static check runs.
+      def option_suggestion(key)
+        require "did_you_mean"
+        DidYouMean::SpellChecker.new(dictionary: self.class.attribute_names.map(&:to_s)).correct(key.to_s).first
+      end
+
+      # The component named in a passthrough problem - an anonymous class
+      # (a test double) has no path to title.
+      def passthrough_owner
+        self.class.name ? self.class.component_title : "this component"
+      end
+
+      # Raise (development, test) or log (everything else).
+      def strict_passthrough?
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
+      end
+
+      private :guard_passthrough, :option_suggestion, :passthrough_owner, :strict_passthrough?
+
       # Returns all component attributes, ensuring proc defaults are evaluated.
       #
       # This method overrides ActiveModel's attributes method to trigger evaluation

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

@@ -49,6 +49,10 @@ export default class DrawerController extends DialogController {
   }
 
   #swipe = null
+  // Where the last press landed (inside the panel or on the backdrop) -
+  // the click that follows a press is never a backdrop dismissal when the
+  // press started inside, however far the pointer travelled since.
+  #pressInside = false
   #closing = false
   #snapIndex = 0
 
@@ -114,6 +118,29 @@ export default class DrawerController extends DialogController {
     })
   }
 
+  /**
+   * The inherited backdrop click, minus the ghost: a press that started
+   * inside the panel can end over the backdrop (a drag against the
+   * clamp, a slip off an inner control) and the click the browser then
+   * fires is a backdrop click by target and coordinates, never by intent.
+   *
+   * @param {MouseEvent} event
+   */
+  backdropClose(event) {
+    if (this.#pressInside) return
+
+    super.backdropClose(event)
+  }
+
+  // The dialog's own inside test (a press on the backdrop targets the
+  // <dialog> too - only the rect tells them apart).
+  #insidePanel(event) {
+    const rect = this.dialogTarget.getBoundingClientRect()
+
+    return rect.top <= event.clientY && event.clientY <= rect.bottom &&
+      rect.left <= event.clientX && event.clientX <= rect.right
+  }
+
   // --- the swipe -----------------------------------------------------------
 
   /**
@@ -124,6 +151,7 @@ export default class DrawerController extends DialogController {
    * @param {PointerEvent} event
    */
   swipeStart(event) {
+    this.#pressInside = this.#insidePanel(event)
     if (event.button !== 0 && event.pointerType === "mouse") return
     if (this.#closing) return
 

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

@@ -8,8 +8,9 @@ import { tabbableWithin } from "@poetry/controllers/helpers/tabbable"
 // pointer-only enrichment behind a LINK. Two timers (open 600 / close
 // 300, over the trigger+content
 // pair, re-enter cancels - the grace window, no polygon), the touch double-guard
-// (pointerType 'touch' no-ops AND touchstart preventDefaults so a tap can
-// never synthesize a focus-open - a tap just navigates the link), the focus
+// (pointerType 'touch' no-ops AND the pointerdown latch swallows the focus a
+// tap or click causes, so a tap keeps its click and just navigates the
+// link - cancelling touchstart would cancel that click with it), the focus
 // mirror (trigger focus opens immediately / blur closes - a keyboard user
 // SEES the card), the per-open TABINDEX STRIP (every tabbable inside is
 // forced tabindex=-1: keyboard and touch users never reach inside,
@@ -28,6 +29,11 @@ const CONTENT_SELECTOR = '[data-slot="hover-card-content"]'
 const EVENT_PREFIX = "poetry:hover-card"
 
 const DISMISSABLE = "poetry--core--dismissable"
+// The pointerdown latch releases once the press has fully landed: the
+// compatibility mouseup (a tap dispatches its mouse events, focus among
+// them, AFTER its pointerup - so pointerup is too early), a cancelled
+// touch, or any key (keyboard use is never mid-press).
+const LATCH_RELEASE_EVENTS = ["mouseup", "pointercancel", "keydown"]
 const POPPER_STRATEGY = "data-poetry--core--popper-strategy-value"
 
 export default class HoverCardController extends Controller {
@@ -49,7 +55,12 @@ export default class HoverCardController extends Controller {
   #containSelection = false
   #hasSelection = false
   #previousBodyUserSelect = null
+  #isPointerDown = false
   #onPointerup = () => this.#handlePointerup()
+  #releaseLatch = () => {
+    this.#isPointerDown = false
+    for (const type of LATCH_RELEASE_EVENTS) document.removeEventListener(type, this.#releaseLatch)
+  }
 
   /**
    * Wires the content listeners (portal-safe) and reconciles a
@@ -93,6 +104,7 @@ export default class HoverCardController extends Controller {
 
     this.#wired = []
     document.removeEventListener("pointerup", this.#onPointerup)
+    this.#releaseLatch()
   }
 
   /**
@@ -152,9 +164,11 @@ export default class HoverCardController extends Controller {
   /**
    * The trigger's focus action: opens IMMEDIATELY, skipping the timers -
    * a keyboard user sees the preview even though they
-   * cannot enter it.
+   * cannot enter it. Focus a pointer caused (the latch) does not open.
    */
   focusOpen() {
+    if (this.#isPointerDown) return
+
     this.#clearCloseTimer()
     this.#show()
   }
@@ -169,15 +183,16 @@ export default class HoverCardController extends Controller {
   }
 
   /**
-   * The trigger's touchstart action - the touch guard: preventDefault so
-   * a tap can never synthesize a focus event (a focus-opened card on
-   * touch would be unreachable). The tap still navigates the
-   * link.
-   *
-   * @param {TouchEvent} event
+   * The trigger's pointerdown action - the latch: the focus a tap or a
+   * click causes must not open the card (a pointer user never gets a
+   * focus-opened card; on touch it would be unreachable), so focusOpen
+   * stays shut until the press has landed (LATCH_RELEASE_EVENTS). The
+   * event is never cancelled: cancelling touchstart would cancel the
+   * tap's click, and the tap must still navigate the link.
    */
-  touchGuard(event) {
-    event.preventDefault()
+  pointerDown() {
+    this.#isPointerDown = true
+    for (const type of LATCH_RELEASE_EVENTS) document.addEventListener(type, this.#releaseLatch)
   }
 
   // --- open / close ---

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

@@ -27,6 +27,17 @@ import {
 // auto-scroll animation cannot release itself.
 const AUTOSCROLLING_CLEAR_DELAY = 180
 
+// The opening-position hold: data-pending-scroll sits on the root and the
+// viewport until defaultScrollPosition end / last-anchor is applied (or
+// skipped, on an empty transcript), so the dictionary can hide the viewport
+// instead of painting the top of the thread and then jumping. The server
+// renders the attribute for those two positions (a scroll container always
+// opens at the top, and the first paint must not wait for this controller);
+// from connect on the controller owns it. Mount-only: a live value change
+// re-applies the position without hiding the viewport again.
+const PENDING_SCROLL_ATTRIBUTE = "data-pending-scroll"
+const HELD_SCROLL_POSITIONS = new Set(["end", "last-anchor"])
+
 // Viewport keys that count as deliberate scroll intent and release follow.
 const USER_SCROLL_KEYS = new Set([
   "ArrowDown",
@@ -56,6 +67,10 @@ const USER_SCROLL_KEYS = new Set([
 //   anchored-to-message a turn held at the reading line while a reply streams
 //   settling-jump       a programmatic jump animating; intent suppressed
 //
+// Presence attributes mirrored on the root AND the viewport: data-scrollable
+// (which edges have room), data-autoscrolling (a programmatic scroll is
+// settling), data-pending-scroll (the opening-position hold, above).
+//
 // Viewport scroll/wheel/touchmove/keydown listeners are wired here (passive
 // flags need addEventListener) - do NOT also declare them as data-actions.
 // The jump button IS a data-action: click->...#jump.
@@ -101,6 +116,7 @@ export default class extends Controller {
     this.prependRestore = null
     this.pendingScrollToMessage = null
     this.defaultScrollPositionApplied = false
+    this.pendingScroll = HELD_SCROLL_POSITIONS.has(this.defaultScrollPositionValue)
     this.spacerHeight = 0
     this.spacerGap = getFlexGap(this.#spacer()?.parentElement ?? null)
     this.handledScrollAnchors = new WeakSet()
@@ -150,6 +166,16 @@ export default class extends Controller {
     // defaultScrollPosition once, commits scrollable state.
     this.#handleContentChange()
 
+    // The hold releases with the opening position (inside the mount pass),
+    // or right away when there is nothing to scroll. A Turbo morph that
+    // re-stamps the server's attribute afterwards is stripped by the
+    // observer; a cache snapshot re-arms it (see #rearmPendingScroll).
+    if (this.itemCount === 0) this.pendingScroll = false
+    this.#writePendingScroll()
+    this.#observePendingScroll(viewport)
+    this.onBeforeCache = () => this.#rearmPendingScroll()
+    document.addEventListener("turbo:before-cache", this.onBeforeCache)
+
     if (this.trackVisibilityValue) this.#observeVisibility()
 
     this.started = true
@@ -189,6 +215,9 @@ export default class extends Controller {
     this.contentResizeObserver = null
     this.visibilityObserver?.disconnect()
     this.visibilityObserver = null
+    this.pendingScrollObserver?.disconnect()
+    this.pendingScrollObserver = null
+    document.removeEventListener("turbo:before-cache", this.onBeforeCache)
     this.observedRows.clear()
     this.visibleMessageIds.clear()
 
@@ -661,7 +690,7 @@ export default class extends Controller {
 
     if (!handled) return false
 
-    this.defaultScrollPositionApplied = true
+    this.#markDefaultScrollPositionApplied()
 
     return true
   }
@@ -708,6 +737,55 @@ export default class extends Controller {
     return true
   }
 
+  // --- the opening-position hold ---
+
+  #markDefaultScrollPositionApplied() {
+    this.defaultScrollPositionApplied = true
+
+    if (!this.pendingScroll) return
+
+    this.pendingScroll = false
+    this.#writePendingScroll()
+  }
+
+  #writePendingScroll() {
+    for (const element of [this.element, this.#viewport()]) {
+      if (!element) continue
+
+      if (this.pendingScroll) element.setAttribute(PENDING_SCROLL_ATTRIBUTE, "")
+      else element.removeAttribute(PENDING_SCROLL_ATTRIBUTE)
+    }
+  }
+
+  // A Turbo morph re-stamps the server-rendered attribute onto the live
+  // elements after the position already applied: strip it. Never re-add
+  // through this path - an inline script that scrolled and released the
+  // hold before connect must keep its release.
+  #observePendingScroll(viewport) {
+    if (typeof MutationObserver === "undefined") return
+
+    this.pendingScrollObserver = new MutationObserver(() => {
+      if (!this.pendingScroll) this.#writePendingScroll()
+    })
+
+    for (const element of [this.element, viewport]) {
+      this.pendingScrollObserver.observe(element, {
+        attributes: true,
+        attributeFilter: [PENDING_SCROLL_ATTRIBUTE]
+      })
+    }
+  }
+
+  // A cached snapshot clones the elements without their scroll position, so
+  // a restore would paint the top of the thread until reconnect re-applies
+  // the opening position: re-arm the hold before Turbo caches the page.
+  #rearmPendingScroll() {
+    if (!HELD_SCROLL_POSITIONS.has(this.defaultScrollPositionValue)) return
+
+    this.pendingScroll = true
+    this.#writePendingScroll()
+  }
+
   // --- scroll commands (mechanics, split from the policy above as in source) ---
 
   #setAutoScrolling(autoscrolling) {
@@ -878,7 +956,7 @@ export default class extends Controller {
     if (!element) {
       if (this.itemCount === 0) {
         this.pendingScrollToMessage = { messageId, options }
-        this.defaultScrollPositionApplied = true
+        this.#markDefaultScrollPositionApplied()
 
         return true
       }
@@ -886,7 +964,7 @@ export default class extends Controller {
       return false
     }
 
-    this.defaultScrollPositionApplied = true
+    this.#markDefaultScrollPositionApplied()
 
     if (this.#scrollToElement(element, options)) {
       this.pendingScrollToMessage = null
@@ -910,7 +988,7 @@ export default class extends Controller {
     if (!this.#scrollToElement(element, pending.options)) return false
 
     this.pendingScrollToMessage = null
-    this.defaultScrollPositionApplied = true
+    this.#markDefaultScrollPositionApplied()
 
     return true
   }

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

@@ -44,6 +44,7 @@ export default class NavigationMenuController extends Controller {
   #cancelExit = new Map() // value -> abandon-this-panel's-exit (per panel, not global)
   #onOutsidePress = null
   #unsubscribeBeforeCache = null
+  #itemsObserver = null
   #sizeGeneration = 0
 
   /**
@@ -62,6 +63,16 @@ export default class NavigationMenuController extends Controller {
       this.#close()
       flushPendingExits()
     })
+
+    // A morph or stream that removes the OPEN trigger's item takes the
+    // per-item panel with it but leaves an adopted viewport panel behind,
+    // and either way the bar still counts itself open: close as if the
+    // trigger had been dismissed, and drop any adopted panel no trigger
+    // owns any more.
+    if (typeof MutationObserver !== "undefined") {
+      this.#itemsObserver = new MutationObserver(() => this.#reconcileRemovedItems())
+      this.#itemsObserver.observe(this.element, { childList: true, subtree: true })
+    }
   }
 
   /**
@@ -73,6 +84,8 @@ export default class NavigationMenuController extends Controller {
     this.#unbindOutsidePress()
     this.#unsubscribeBeforeCache?.()
     this.#unsubscribeBeforeCache = null
+    this.#itemsObserver?.disconnect()
+    this.#itemsObserver = null
   }
 
   /**
@@ -82,7 +95,7 @@ export default class NavigationMenuController extends Controller {
    */
   toggle(event) {
     const value = this.#valueFrom(event)
-    if (value === null) return
+    if (value === null || this.#disabled(value)) return
 
     this.#clearTimer()
     if (this.#openValue === value) this.#close()
@@ -101,7 +114,7 @@ export default class NavigationMenuController extends Controller {
     if (event.pointerType === "touch") return // touch is click's job
 
     const value = this.#valueFrom(event)
-    if (value === null) return
+    if (value === null || this.#disabled(value)) return
     if (value === this.#openValue) {
       this.#clearTimer() // re-entering the open item cancels a pending close
       return
@@ -152,6 +165,20 @@ export default class NavigationMenuController extends Controller {
       return
     }
 
+    // ArrowDown on a trigger opens its panel and is consumed; focus stays
+    // on the trigger (Tab enters the panel). A top-level link is not a
+    // trigger and keeps the key.
+    if (event.key === "ArrowDown") {
+      const trigger = event.target instanceof Element ? event.target.closest(TRIGGER_SELECTOR) : null
+      const value = this.#valueFrom(event)
+      if (!trigger || value === null || this.#disabled(value)) return
+
+      event.preventDefault()
+      this.#clearTimer()
+      if (this.#openValue !== value) this.#open(value)
+      return
+    }
+
     if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return
 
     const stops = this.#arrowStops()
@@ -211,6 +238,28 @@ export default class NavigationMenuController extends Controller {
     this.#bindOutsidePress()
   }
 
+  #reconcileRemovedItems() {
+    const viewport = this.#viewport()
+    if (viewport) {
+      for (const panel of viewport.querySelectorAll("[data-viewport-panel]")) {
+        if (!this.#ownerOf(panel)) panel.remove()
+      }
+    }
+    if (this.#openValue === null || this.#triggerFor(this.#openValue)) return
+
+    this.#clearTimer()
+    this.#close()
+  }
+
+  // The trigger whose aria-controls names this adopted panel, if it still
+  // exists.
+  #ownerOf(panel) {
+    if (!panel.id) return null
+
+    return [...this.element.querySelectorAll(TRIGGER_SELECTOR)]
+      .find((trigger) => trigger.getAttribute("aria-controls") === panel.id) ?? null
+  }
+
   #close() {
     if (this.#openValue === null) return
 
@@ -434,6 +483,12 @@ export default class NavigationMenuController extends Controller {
     return this.#itemFor(value)?.querySelector(TRIGGER_SELECTOR) ?? null
   }
 
+  // A disabled trigger (native disabled, data-disabled) never opens its
+  // panel - not by click, not by hover - and the arrows step over it.
+  #disabled(value) {
+    return this.#triggerFor(value)?.disabled === true
+  }
+
   // An adopted panel (viewport mode) no longer lives inside its item -
   // the trigger's aria-controls id finds it wherever it moved.
   #panelFor(value) {
@@ -449,10 +504,10 @@ export default class NavigationMenuController extends Controller {
       .find((item) => item.dataset.value === value) ?? null
   }
 
-  // Arrow stops: every trigger and top-level link in the bar, DOM order.
+  // Arrow stops: every enabled trigger and top-level link in the bar, DOM order.
   #arrowStops() {
     return [...this.element.querySelectorAll(
       `${TRIGGER_SELECTOR}, [data-slot="navigation-menu-list"] > ${ITEM_SELECTOR} > a`
-    )]
+    )].filter((stop) => !stop.disabled)
   }
 }

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

@@ -32,7 +32,6 @@ export default class extends Controller {
   static events = ["poetry:number-field:change", "poetry:number-field:commit"]
 
   #value = null
-  #focusedOnce = false
   #holdTimer = null
   #holdInterval = null
   #holdChanged = false
@@ -119,15 +118,6 @@ export default class extends Controller {
     if (parsed !== null) this.#apply(parsed, { display: false })
   }
 
-  /** The focus action: the first focus parks the caret at the end. */
-  focus() {
-    if (this.#focusedOnce) return
-
-    this.#focusedOnce = true
-    const end = this.inputTarget.value.length
-    this.inputTarget.setSelectionRange(end, end)
-  }
-
   /**
    * The blur action - the text commit point: empty clears, unparseable
    * text is left as typed with no commit, parseable text clamps and
@@ -161,7 +151,7 @@ export default class extends Controller {
     if (event.button !== 0 || this.inputTarget.readOnly) return
 
     // Mouse focuses the input (touch would pop the software keyboard).
-    if (event.pointerType !== "touch") this.inputTarget.focus()
+    if (event.pointerType !== "touch") this.#focusInput()
     this.#pressTicked = true
     this.#holdChanged = false
     const direction = this.#directionFor(event.currentTarget)
@@ -224,6 +214,17 @@ export default class extends Controller {
     return changed
   }
 
+  // Programmatic focus (the steppers) parks the caret at the end BEFORE
+  // focusing: every engine restores the stored selection on focus, and a
+  // host's own focus handler can still choose differently. Keyboard and
+  // pointer focus keep the browser's native selection (Tab selects the
+  // value, a click places the caret).
+  #focusInput() {
+    const end = this.inputTarget.value.length
+    this.inputTarget.setSelectionRange(end, end)
+    this.inputTarget.focus()
+  }
+
   #directionFor(button) {
     return this.hasIncrementTarget && button === this.incrementTarget ? 1 : -1
   }
@@ -240,13 +241,22 @@ export default class extends Controller {
     this.#apply(candidate, { display: true })
   }
 
+  // The dominant axis decides (a precision touchpad emits sub-pixel
+  // cross-axis noise): a sideways gesture is page scroll and passes
+  // through untouched, except under Shift, which some browsers deliver
+  // on the horizontal axis - there the horizontal delta is the intended
+  // one. Positive is "down", stepping the value down.
   #wheel(event) {
     if (event.ctrlKey || document.activeElement !== this.inputTarget) return
 
-    event.preventDefault()
-    if (event.deltaY === 0) return
+    const horizontal = Math.abs(event.deltaX) > Math.abs(event.deltaY)
+    if (horizontal && !event.shiftKey) return
+
+    const delta = horizontal ? event.deltaX : event.deltaY
+    if (delta === 0) return
 
-    this.#step(event.deltaY > 0 ? -1 : 1, event)
+    event.preventDefault()
+    this.#step(delta > 0 ? -1 : 1, event)
     this.#commit()
   }
 

data/config/controllers_manifest.json

@@ -595,9 +595,9 @@
       "disconnect",
       "focusOpen",
       "openValueChanged",
+      "pointerDown",
       "pointerEnter",
-      "pointerLeave",
-      "touchGuard"
+      "pointerLeave"
     ],
     "events": [
       "poetry:hover-card:closed",
@@ -841,7 +841,6 @@
       "blur",
       "connect",
       "disconnect",
-      "focus",
       "hiddenChanged",
       "input",
       "keydown",

data/lib/poetry/core/check.rb

@@ -47,7 +47,7 @@ module Poetry
       #
       # @api private
       class Catalog
-        PASSTHROUGH = %w[class id key webmcp data aria role style if unless].freeze
+        PASSTHROUGH = %w[class id key webmcp identity data aria role style if unless].freeze
         COLOR_FAMILIES = %w[
           slate gray zinc neutral stone red orange amber yellow lime green emerald
           teal cyan sky blue indigo violet purple fuchsia pink rose
@@ -401,7 +401,7 @@ module Poetry
           unless path
             return helper_findings(helper, call, base_line) + yieldless_findings(helper, call, line) +
                    helper_arity_findings(helper, call, line) + webmcp_form_findings(helper, call, line) +
-                   passthrough_findings(keyword_pairs(call), base_line) + data_findings(call, base_line)
+                   passthrough_findings(keyword_pairs(call), base_line) + data_findings(call, base_line, helper)
           end
 
           record_binding(call, path, bindings, line)
@@ -415,7 +415,7 @@ module Poetry
             content_findings(path, helper, call, line, content_fed) +
             blockless_slot_findings(path, helper, call, pairs, line) +
             requires_any_findings(path, call, pairs, line, content_fed) +
-            passthrough_findings(pairs, base_line) + data_findings(call, base_line)
+            passthrough_findings(pairs, base_line) + data_findings(call, base_line, helper)
         end
 
         # The requires_content tier: a component that raises without a
@@ -474,13 +474,19 @@ module Poetry
           known = @catalog.option_names(path)
           entry = @catalog.option_entry(path, key)
 
+          # The component's identity attribute: never overridable (the render
+          # raises in development and test, drops it in production).
+          return [reserved_finding("data-component", helper_of(path), line)] if key == "data-component"
+
           unless known.include?(key) || Catalog::PASSTHROUGH.include?(key)
             suggestion = suggest(key, known)
-            # No suggestion => an intentional pass-through html attribute, not a typo.
+            # No suggestion => an intentional pass-through html attribute, not a
+            # typo. A suggestion is the render-time raise (development, test).
             if suggestion
-              findings << Finding.new(rule: "unknown-option", severity: :warning,
-                                      message: "#{helper_of(path)} has no option #{key}", line: line,
-                                      suggestion: suggestion)
+              findings << Finding.new(rule: "unknown-option", severity: :error,
+                                      message: "#{helper_of(path)} has no option #{key} " \
+                                               "(unknown keywords render as HTML attributes)",
+                                      line: line, suggestion: suggestion)
             end
           end
 
@@ -640,7 +646,7 @@ module Poetry
           findings = arity_findings(entry, slot_name, call, line) +
                      setter_block_findings(entry, slot_name, call, line) +
                      setter_keyword_findings(entry, slot_name, call, base_line) +
-                     passthrough_findings(keyword_pairs(call), base_line) + data_findings(call, base_line)
+                     passthrough_findings(keyword_pairs(call), base_line) + data_findings(call, base_line, label)
           component = entry["component"]
           return findings unless component
 
@@ -948,18 +954,29 @@ module Poetry
         # data key (`poetry__core__x_target:` and `"poetry--core--x-target":`
         # both render data-poetry--core--x-target), so the rendered name is
         # what gets checked. Dynamic values are left alone.
-        def data_findings(call, base_line)
+        def data_findings(call, base_line, helper)
           hash = hash_argument(call, "data")
           return [] unless hash
 
           hash_pairs(hash).flat_map do |key, node|
+            line = base_line + node.location.start_line - 1
+            next [reserved_finding("data: { component: }", helper, line)] if key == "component"
+
             value = literal_value(node)
             next [] unless value.is_a?(String)
 
-            stimulus_findings("data-#{key.tr("_", "-")}", value, base_line + node.location.start_line - 1)
+            stimulus_findings("data-#{key.tr("_", "-")}", value, line)
           end
         end
 
+        def reserved_finding(spelling, helper, line)
+          Finding.new(rule: "reserved-attribute", severity: :error,
+                      message: "#{spelling} is #{helper}'s own identity attribute and is never overridable " \
+                               "(a composed root takes identity: instead; the raw attribute raises at render " \
+                               "in development)",
+                      line: line)
+        end
+
         def controller_findings(value, line)
           value.split.filter_map do |identifier|
             next unless identifier.start_with?(POETRY_PREFIX)

data/lib/poetry/core/config.rb

@@ -56,7 +56,8 @@ module Poetry
         #   actions.
         # - `css_mode` (`:tailwind`) - `:tailwind` emits resolved utility
         #   classes; `:bem` emits the BEM token IR for bring-your-own-CSS
-        #   hosts.
+        #   kits authored on this DSL (poetry-ui is Tailwind-native and is
+        #   not a `:bem` consumer).
         # - `icon_library` (`:lucide`) - the active icon set, by the key it
         #   registered under ({Poetry::Core::Icons.register}).
         # - `raise_on_missing_icon` (`nil`) - the policy for a dynamic icon
@@ -169,7 +170,9 @@ module Poetry
       #
       # @!method css_mode
       #   The class emission mode: `:tailwind` resolves style values to
-      #   utility classes, `:bem` emits the BEM token IR.
+      #   utility classes, `:bem` emits the BEM token IR - for kits authored
+      #   on the DSL that write their own templates; poetry-ui is
+      #   Tailwind-native and is not a `:bem` consumer.
       #   @return [Symbol] :tailwind or :bem
       #
       # @!method css_mode=(mode)

data/lib/poetry/core/version.rb

@@ -4,6 +4,6 @@ module Poetry
   module Core
     # The gem version. Every gem in the family carries the same version
     # and pins poetry-core to it exactly.
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: poetry-core
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Matt Solt