poetry-core 0.0.2

data/app/javascript/poetry/core/helpers/portal.js

@@ -0,0 +1,217 @@
+import { onBeforeCache } from "@poetry/controllers/helpers/turbo_cache"
+
+// The portal-on-open mechanism: move popper
+// content to a stable container (body by default) while open so it can
+// position `absolute` - static under compositor scroll, immune to
+// transformed ancestors - and return it HOME on close, exactly where a
+// placeholder comment marks the origin.
+//
+// THE EVENT BRIDGE (the logical-tree trap): a component-tree portal
+// re-bubbles events from its logical position; a DOM portal does not. A
+// host's data-action on the component ROOT would go deaf to events
+// rising out of portaled content. The bridge restores logical-tree
+// bubbling for poetry's OWN
+
+// CustomEvents (the registered list below - NEVER native events, which
+// the dismissal/hotkey layers listen for at document and must see on the
+// real path): propagation is CUT at the content boundary and a clone is
+// re-dispatched from the home position, so above the content the event
+// exists on exactly ONE path - the home one. Cancellation transfers back
+// (the re-dispatch is synchronous, inside the original dispatch), and the
+// real origin element rides the clone as `portalTarget` (the clone's own
+// `target` is the home-side parent - a re-dispatched event cannot keep
+// the original).
+//
+// Restore is guarded: if a Turbo morph replaced the origin while the
+// popup was out, the content is DROPPED, never stranded at body. A lazy
+// turbo:before-cache net force-restores everything still portaled so a
+// snapshot never caches body-level popups (the zombie-popup class).
+const portaled = new Map()
+const bridgeEvents = new Set(["poetry:state-change"])
+let cacheNetInstalled = false
+
+/**
+ * Adds event names to the bridge list. index.js registers the union of
+ * every controller's declared `static events` at boot - the bridge list
+ * stays honest against the manifest surface without portal.js importing
+ * the controllers (no cycle).
+ *
+ * @param {Iterable<string>} names - full event names as emitted
+ */
+export function registerBridgeEvents(names) {
+  for (const name of names) bridgeEvents.add(name)
+}
+
+/**
+ * The portal-container seam, attribute-shaped: a host scoping themes to
+ * a subtree points its overlays at a container inside that scope via
+ * data-poetry-portal-container="<element id>".
+ *
+ * @param {Element | null} root - the element carrying the attribute
+ * @returns {Element} the named container, or document.body
+ */
+export function resolvePortalContainer(root) {
+  const id = root?.getAttribute?.("data-poetry-portal-container")
+
+  return (id ? document.getElementById(id) : null) ?? document.body
+}
+
+/**
+ * Whether `content` is currently portaled out (has a live placeholder).
+ *
+ * @param {Element} content
+ * @returns {boolean}
+ */
+export function isPortaled(content) {
+  return portaled.has(content)
+}
+
+/**
+ * Containment that follows portals HOME: a node inside portaled content
+ * counts as inside `container` when the content's home position does.
+ * Focus-scope's trap keys on this - a portaled sub level is outside the
+ * root content's subtree but logically inside its tree, and the trap
+ * must follow the logical tree or every portaled level reads as outside.
+ *
+ * @param {Element} container
+ * @param {Node | null} node
+ * @returns {boolean}
+ */
+export function logicallyContains(container, node) {
+  let current = node
+
+  while (current) {
+    if (container.contains(current)) return true
+
+    const content = portaledAncestorOf(current)
+
+    if (!content) return false
+
+    current = portaled.get(content).placeholder.parentNode
+  }
+
+  return false
+}
+
+function portaledAncestorOf(node) {
+  for (let el = node instanceof Element ? node : node?.parentElement; el; el = el.parentElement) {
+    if (portaled.has(el)) return el
+  }
+
+  return null
+}
+
+/**
+ * Moves `content` to `container`, leaving a placeholder comment at home
+ * and wiring the event bridge for the registered list. No-op (false) when
+ * already portaled or parentless. The home-effective `dir` is stamped
+ * onto undeclared content for the trip, so direction-dependent behavior
+ * survives the move (un-stamped on restore).
+ *
+ * @param {Element} content
+ * @param {Object} [options]
+ * @param {Element} [options.container=document.body]
+ * @returns {boolean} true when the move happened
+ */
+export function portalContent(content, { container = document.body } = {}) {
+  if (portaled.has(content) || !content.parentNode) return false
+
+  const placeholder = document.createComment("poetry-portal")
+
+  content.parentNode.insertBefore(placeholder, content)
+
+  // Direction survives the move: dir inherits through the DOM, so a body
+  // portal would silently flip a locally-RTL subtree back to the document
+  // direction - menu arrow semantics (directionOf walks closest [dir])
+  // and every CSS logical property inside the popup key on it. Stamp the
+  // home-effective dir when the content declares none; restore un-stamps.
+  let stampedDir = false
+
+  if (!content.hasAttribute("dir")) {
+    const dir = content.closest("[dir]")?.getAttribute("dir")
+
+    if (dir) {
+      content.setAttribute("dir", dir)
+      stampedDir = true
+    }
+  }
+
+  container.append(content)
+
+  const bridges = []
+
+  for (const type of bridgeEvents) {
+    const listener = (event) => bridge(event, placeholder)
+
+    content.addEventListener(type, listener)
+    bridges.push([type, listener])
+  }
+
+  portaled.set(content, { placeholder, bridges, stampedDir })
+  installCacheNet()
+  return true
+}
+
+/**
+ * Returns portaled `content` to its placeholder and unwires the bridge.
+ * When the origin is gone (a morph replaced it) the content is DROPPED,
+ * never stranded at the container.
+ *
+ * @param {Element} content
+ * @returns {boolean} true when the content went home; false when it was
+ *   not portaled, or had to be dropped
+ */
+export function restoreContent(content) {
+  const state = portaled.get(content)
+
+  if (!state) return false
+
+  portaled.delete(content)
+  for (const [type, listener] of state.bridges) content.removeEventListener(type, listener)
+  if (state.stampedDir) content.removeAttribute("dir")
+
+  // Home-aliveness reads the parent ELEMENT, never the comment: dommy's
+  // QuickJS DOM has no Comment#isConnected (undefined reads as "origin
+  // gone" and silently DROPS live content - the dommy tier caught it).
+  // replaceChild over ChildNode.replaceWith for the same reason.
+  const home = state.placeholder.parentNode
+
+  if (home?.isConnected) {
+    home.replaceChild(content, state.placeholder)
+    return true
+  }
+
+  // The origin is gone (a morph replaced it) - drop, never strand.
+  state.placeholder.parentNode?.removeChild(state.placeholder)
+  content.remove()
+  return false
+}
+
+// Bubble-phase on the content node itself, so the consumer's own content
+// listeners (wired at connect, before any portal) always run first.
+function bridge(event, placeholder) {
+  const home = placeholder.parentNode
+
+  if (!home?.isConnected) return
+
+  event.stopPropagation()
+
+  const clone = new CustomEvent(event.type, {
+    detail: event.detail, bubbles: true,
+    cancelable: event.cancelable, composed: event.composed
+  })
+
+  clone.portalTarget = event.target
+  home.dispatchEvent(clone)
+
+  if (clone.defaultPrevented) event.preventDefault()
+}
+
+function installCacheNet() {
+  if (cacheNetInstalled) return
+
+  cacheNetInstalled = true
+  onBeforeCache(() => {
+    for (const content of [...portaled.keys()]) restoreContent(content)
+  })
+}

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

@@ -0,0 +1,210 @@
+import { setState } from "@poetry/controllers/helpers/state"
+import { onBeforeCache } from "@poetry/controllers/helpers/turbo_cache"
+
+// Presence: the mount/unmount animation convention - a helper, not a
+// controller (no element ownership here). Exit flips the pair to
+// data-closed and HOLDS the node in the DOM until its CSS exit animation /
+// transition finishes, then hands removal back to the caller via onRemove
+// (this module never removes DOM); enter just flips the pair to data-open
+// so the data-open: animation runs. State writes go through setState so
+// poetry:state-change fires like every other state flip.
+
+// Grace (ms) added to the computed animation/transition time before the
+// safety timeout fires - animationend can lag the declared duration.
+const EXIT_TIMEOUT_GRACE = 100
+
+// Safety net (ms) when a duration cannot be computed (an animation is
+// declared but reports zero length): never strand a closed node in the DOM.
+const EXIT_TIMEOUT_FALLBACK = 1000
+
+// Exits waiting on their CSS animation. A Turbo snapshot must never
+// capture one mid-flight: the owner's onRemove (hidden + layer-controller
+// removal) would land AFTER the cache is taken, so the restored page
+// resurrects a live layer - the click-dead restore class. Every pending
+// exit is flushed synchronously at turbo:before-cache; the dismissable
+// layer also flushes explicitly after dispatching its before-cache
+// dismiss, so exits STARTED by that dismiss complete in the same tick
+// regardless of listener order.
+const pendingExits = new Set()
+
+/**
+ * Settles every exit still waiting on its CSS animation, synchronously
+ * (each runs its onRemove). Wired to turbo:before-cache at module load;
+ * the dismissable layer also calls it directly (see above).
+ */
+export function flushPendingExits() {
+  for (const flush of [...pendingExits]) flush()
+}
+
+if (typeof document !== "undefined") onBeforeCache(flushPendingExits)
+
+/**
+ * The measured-entry/exit hook (the Accordion contract's height
+ * mechanism): height keyframes cannot animate to auto, so the keyframe
+ * chain reads a CSS var instead. This measures the settled box -
+ * temporarily unhiding the element and suppressing its animations so
+ * scrollHeight reports the real content height - writes "<n>px" to the
+ * custom property, then restores exactly what it changed.
+ *
+ * @param {HTMLElement} element
+ * @param {Object} [options]
+ * @param {string} [options.property="--poetry-presence-height"] -
+ *   overridable because the vendored keyframes read
+ *   --accordion-panel-height
+ * @returns {number} the measured height (px)
+ */
+export function measurePresence(element, { property = "--poetry-presence-height" } = {}) {
+  const wasHidden = element.hidden
+  const previousAnimation = element.style.animation
+
+  if (wasHidden) element.hidden = false
+  element.style.animation = "none" // a mid-flight keyframe must not skew the measure
+
+  const height = element.scrollHeight
+  element.style.setProperty(property, `${height}px`)
+
+  element.style.animation = previousAnimation
+  if (wasHidden) element.hidden = true
+
+  return height
+}
+
+/**
+ * Runs the entry: flips the pair to data-open (through setState, so the
+ * state-change event fires) wearing data-starting-style for exactly one
+ * painted frame after the flip (the two-frame trick below), so CSS
+ * transitions can animate FROM the starting declarations. No poetry class
+ * consumes the attribute yet - it ships so a future theme layer can adopt
+ * the transition idiom without touching JS.
+ *
+ * @param {HTMLElement} element
+ * @param {Object} [options]
+ * @param {boolean} [options.measure=false] - measure BEFORE the pair
+ *   flips, so the entry keyframe can consume the var from its first frame
+ * @param {string} [options.property] - forwarded to
+ *   {@link measurePresence}
+ * @returns {HTMLElement} the element
+ */
+export function enterPresence(element, { measure = false, property } = {}) {
+  if (measure) measurePresence(element, { property })
+
+  element.removeAttribute("data-ending-style") // an interrupted exit must not linger
+  element.setAttribute("data-starting-style", "")
+  setState(element, "open")
+
+  if (typeof requestAnimationFrame === "function") {
+    // Two frames: the first paints WITH the attribute, the removal lands
+    // on the next - the transition sees both endpoints.
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => element.removeAttribute("data-starting-style"))
+    })
+  } else {
+    element.removeAttribute("data-starting-style") // no rAF (bare interpreter): inert either way
+  }
+
+  return element
+}
+
+/**
+ * Runs the exit: flips the pair to data-closed and HOLDS the node in the
+ * DOM until its CSS exit animation/transition finishes, then hands
+ * removal back to the caller (this module never removes DOM). onRemove
+ * runs at most once, on the first of animationend / transitionend (on the
+ * element itself, not a child) or the safety timeout - or synchronously
+ * when no exit animation exists. data-ending-style rides the whole exit.
+ *
+ * @param {HTMLElement} element
+ * @param {Object} [options]
+ * @param {() => void} [options.onRemove] - the caller's removal step
+ * @param {boolean} [options.measure=false] - measure while the element is
+ *   STILL VISIBLE, before the flip to "closed" starts the exit keyframe
+ * @param {string} [options.property] - forwarded to
+ *   {@link measurePresence}
+ * @returns {() => void} cancel() - abandons the wait WITHOUT calling
+ *   onRemove (an exit interrupted by a re-open)
+ */
+export function exitPresence(element, { onRemove, measure = false, property } = {}) {
+  if (measure) measurePresence(element, { property })
+
+  // The exit-window hook: data-ending-style rides the whole exit
+  // and leaves with the node's removal (or an interrupting re-open).
+  element.setAttribute("data-ending-style", "")
+  setState(element, "closed")
+
+  if (!hasExitAnimation(element)) {
+    element.removeAttribute("data-ending-style")
+    onRemove?.()
+    return () => {}
+  }
+
+  let settled = false
+  let timeout = null
+
+  const cleanup = () => {
+    element.removeEventListener("animationend", settle)
+    element.removeEventListener("transitionend", settle)
+    if (timeout !== null) window.clearTimeout(timeout)
+    pendingExits.delete(flush)
+  }
+
+  const settle = (event) => {
+    if (event && event.target !== element) return // a child's animation is not ours
+    if (settled) return
+
+    settled = true
+    cleanup()
+    element.removeAttribute("data-ending-style")
+    onRemove?.()
+  }
+
+  const flush = () => settle()
+
+  element.addEventListener("animationend", settle)
+  element.addEventListener("transitionend", settle)
+  timeout = window.setTimeout(settle, exitTimeoutFor(element))
+  pendingExits.add(flush)
+
+  // getAnimations().finished is the robust end-detection: it resolves for
+  // transitions AND keyframes symmetrically and needs no duration math.
+  // Kept ALONGSIDE the listener+timeout paths - jsdom and the dommy tier
+  // don't implement getAnimations, and settle() is idempotent.
+  if (typeof element.getAnimations === "function") {
+    const animations = element.getAnimations()
+    if (animations.length > 0) {
+      Promise.allSettled(animations.map((animation) => animation.finished))
+        .then(() => settle())
+    }
+  }
+
+  return () => {
+    settled = true
+    cleanup()
+    element.removeAttribute("data-ending-style")
+  }
+}
+
+// jsdom (and a bare node) report animationName as "" - treat it as "none".
+function hasExitAnimation(element) {
+  const style = getComputedStyle(element)
+  const animated = (style.animationName || "none") !== "none"
+  const transitioned = maxTimeMs(style.transitionDuration) > 0
+  return animated || transitioned
+}
+
+function exitTimeoutFor(element) {
+  const style = getComputedStyle(element)
+  const total = Math.max(
+    maxTimeMs(style.animationDuration) + maxTimeMs(style.animationDelay),
+    maxTimeMs(style.transitionDuration) + maxTimeMs(style.transitionDelay)
+  )
+  return total > 0 ? total + EXIT_TIMEOUT_GRACE : EXIT_TIMEOUT_FALLBACK
+}
+
+// Longest entry of a comma-separated CSS time list: "0.2s, 50ms" -> 200.
+function maxTimeMs(value = "") {
+  return Math.max(0, ...String(value).split(",").map((time) => {
+    const parsed = parseFloat(time)
+    if (Number.isNaN(parsed)) return 0
+    return time.trim().endsWith("ms") ? parsed : parsed * 1000
+  }))
+}

data/app/javascript/poetry/core/helpers/registration_guard.js

@@ -0,0 +1,76 @@
+// The registration guard: Stimulus never errors on a data-controller
+// identifier nothing registered - the element simply stays inert - and one
+// failed import in the host's controllers graph silently takes every poetry
+// controller down with it. After the page is ready (and again on every
+// Turbo navigation) this compares the poetry-prefixed identifiers on the
+// page with the application's registry and warns ONCE per identifier. Host
+// controllers are never inspected (they may lazy-load); poetry's cannot.
+
+const PREFIX = "poetry--"
+const warned = new Set()
+
+/**
+ * The poetry identifiers on the page that `application` has not
+ * registered.
+ *
+ * @param {import("@hotwired/stimulus").Application} application
+ * @param {ParentNode} [root=document] - the subtree to inspect
+ * @returns {string[]} sorted, deduplicated identifiers
+ */
+export function unregisteredPoetryControllers(application, root = document) {
+  const registry = application && application.router && application.router.modulesByIdentifier
+  if (!registry || !root || !root.querySelectorAll) return []
+  const missing = new Set()
+  for (const element of root.querySelectorAll("[data-controller]")) {
+    for (const identifier of element.getAttribute("data-controller").split(/\s+/)) {
+      if (identifier.startsWith(PREFIX) && !registry.has(identifier)) missing.add(identifier)
+    }
+  }
+  return Array.from(missing).sort()
+}
+
+/**
+ * Warns once per newly-seen unregistered poetry identifier.
+ *
+ * @param {import("@hotwired/stimulus").Application} application
+ * @param {ParentNode} [root=document]
+ * @returns {string[]} the identifiers warned about in this call
+ */
+export function checkPoetryRegistration(application, root = document) {
+  const fresh = unregisteredPoetryControllers(application, root).filter((identifier) => !warned.has(identifier))
+  if (fresh.length === 0) return fresh
+  fresh.forEach((identifier) => warned.add(identifier))
+  console.warn(
+    `[poetry] ${fresh.length} poetry controller(s) on this page are not registered on the Stimulus application: ` +
+      `${fresh.join(", ")}. The elements stay inert - check the importmap pins and that every poetry gem's ` +
+      `register call runs in controllers/index.js.`
+  )
+  return fresh
+}
+
+let scheduled = false
+
+/**
+ * Runs the check once the DOM is parsed (registration usually happens
+ * while the document is still loading) and after every Turbo navigation.
+ * Idempotent: the first registrar to call it wires the listeners.
+ *
+ * @param {import("@hotwired/stimulus").Application} application
+ */
+export function guardPoetryRegistration(application) {
+  if (scheduled || typeof document === "undefined") return
+  scheduled = true
+  const run = () => checkPoetryRegistration(application)
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", run, { once: true })
+  } else {
+    setTimeout(run, 0)
+  }
+  document.addEventListener("turbo:load", run)
+}
+
+/** Test seam: forget what has been warned about and re-arm the scheduler. */
+export function resetPoetryRegistrationGuard() {
+  warned.clear()
+  scheduled = false
+}

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

@@ -0,0 +1,67 @@
+// Body scroll-lock with scrollbar-width compensation: bare
+// `overflow: hidden` shifts the whole layout by the scrollbar width the
+// moment an overlay opens on a scrollable page.
+// The gap is measured BEFORE locking and paid back as body padding-right.
+// Refcounted so stacked overlays (a dialog opened from a sheet) lock once
+// and restore only when the LAST one closes - per-instance saved values
+// break on out-of-order closes.
+//
+// Why not scrollbar-gutter: stable (this helper's original primary)?
+// Measured live with classic
+// scrollbars: Chrome drops the viewport's rail AND its reserved gutter
+// the moment the viewport's used overflow computes to hidden - whether
+// the pair sits on the root, propagates from body, or the gutter was set
+// permanently - so the page shifted by the scrollbar width anyway (the
+// exact wiggle the strategy existed to stop). The body-padding payback
+// is the only compensation the viewport honors; its known cost is that
+// position:fixed elements aren't compensated - accepted deliberately,
+// not an oversight.
+let locks = 0
+let previous = null
+
+/**
+ * Locks body scrolling, paying the measured scrollbar gap back as body
+ * padding-right so the layout never shifts. Refcounted: stacked overlays
+ * lock once; only the first call writes styles.
+ */
+export function lockScroll() {
+  locks += 1
+  if (locks > 1) return
+
+  const gap = window.innerWidth - document.documentElement.clientWidth
+  // Never save a value the lock itself writes: a Turbo-restored snapshot
+  // arrives with the serialized "hidden" already inline (no refcount
+  // behind it), and saving it would re-freeze scrolling on every later
+  // unlock (the poisoned-previous restore class).
+  const overflow = document.body.style.overflow
+  previous = {
+    overflow: overflow === "hidden" ? "" : overflow,
+    paddingRight: document.body.style.paddingRight
+  }
+  if (gap > 0) {
+    const current = parseFloat(getComputedStyle(document.body).paddingRight) || 0
+    document.body.style.paddingRight = `${current + gap}px`
+  }
+  document.body.style.overflow = "hidden"
+}
+
+/**
+ * Releases one scroll lock; the LAST release restores the body's saved
+ * overflow and padding-right.
+ */
+export function unlockScroll() {
+  if (locks === 0) return
+
+  locks -= 1
+  if (locks > 0) return
+
+  document.body.style.overflow = previous.overflow
+  document.body.style.paddingRight = previous.paddingRight
+  previous = null
+}
+
+/** Test seam: vitest suites run many overlays in one document. */
+export function resetScrollLock() {
+  locks = 0
+  previous = null
+}