poetry-core 0.1.0 → 0.1.2

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/component_registry.yml

@@ -14,7 +14,9 @@ components:
       description: The element to render ('div', 'section', 'span', ...); void elements
         (br, hr, img, ...) self-close and take no content block.
     slots: []
+    helper: poetry_box
     identity: false
     parts:
     - name: box
       description: The rendered element itself - the whole component is one part
+internal: true

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/stable_identity.rb

@@ -68,6 +68,19 @@ module Poetry
 
         private
 
+        # The gem convention plus every helper the catalog knows by a name
+        # of its own (an app component's declared helper), so the
+        # heuristics cover app components too.
+        def helper_pattern
+          @helper_pattern ||= begin
+            declared = @catalog.helper_names.reject { |name| name.start_with?("poetry_") }
+            # A bare call: not after a dot or a colon (`u.badge`, `Foo::badge`).
+            Regexp.union(/(?<![\w.:])(poetry_[a-z0-9_]+)\b/, *declared.map do |name|
+              /(?<![\w.:])(#{Regexp.escape(name)})\b/
+            end)
+          end
+        end
+
         def frame_for(code)
           return :cache if code.match?(CACHE_OPENER)
           return :loop if code.match?(LOOP_OPENER)
@@ -76,7 +89,7 @@ module Poetry
         end
 
         def flag_helpers(code, line, stack, findings)
-          code.scan(/\b(poetry_[a-z0-9_]+)\b/) do |(helper)|
+          code.scan(helper_pattern) do |(helper)|
             next unless @catalog.helper?(helper)
             next if @catalog.identity_free?(helper)
             next if code.match?(IDENTITY_ARG)