poetry-core 0.0.2

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

@@ -0,0 +1,111 @@
+import { Controller } from "@hotwired/stimulus"
+import { onBeforeCache } from "@poetry/controllers/helpers/turbo_cache"
+
+// Error isolation for deferred turbo-frames. Turbo owns the
+// loading physics (loading="lazy" fetches on visibility, "eager" after
+// paint) but leaves failure INVISIBLE: a missing frame logs "Content
+// missing" or - Turbo 8 - promotes the error response to a full-page
+// visit, and a network error leaves the placeholder spinning forever.
+// This controller makes failure a state: data-error reflected on the
+// frame (a bespoke boolean, deliberately not the shared open/closed
+// vocabulary), the placeholder hidden, and the slotted <template> error
+// content stamped so the region shows a real, retryable message.
+//
+// THE BOOT CONTRACT: the frame renders with NO src - the URL rides
+// srcValue and connect() arms it. A visible lazy frame with src in
+// markup can complete its fetch before the controllers module graph
+// finishes loading (caught live: a local 404 beat Stimulus and Turbo 8
+// navigated the whole page to the error response); with src armed at
+// connect, no fetch - and so no failure - can predate the instance.
+//
+// retry() prefers Turbo's FrameElement#reload(); environments without
+// the Turbo runtime (jsdom, dommy) fall back to re-setting src, the same
+// signal Turbo reacts to.
+export default class DeferredController extends Controller {
+  static targets = ["placeholder", "error"]
+  static values = { src: String }
+
+  /**
+   * Wires the three failure listeners, subscribes the before-cache reset,
+   * and arms src LAST (the boot contract above: no fetch can predate the
+   * instance).
+   */
+  connect() {
+    // Three failure paths, one state. turbo:before-fetch-response is the
+    // load-bearing one: for 4xx/5xx frame responses Turbo 8 fires NO
+    // frame-missing - it promotes the error response straight to a
+    // full-page visit (caught live: the docs page navigated to a bare
+    // 404). Cancelling the response event here stops that promotion cold.
+    // frame-missing still covers 2xx-without-a-matching-frame, and
+    // fetch-request-error covers the network layer.
+    this.element.addEventListener("turbo:before-fetch-response", this.#onResponse)
+    this.element.addEventListener("turbo:frame-missing", this.#failed)
+    this.element.addEventListener("turbo:fetch-request-error", this.#failed)
+
+    // Reset before Turbo snapshots: a stamped error message serialized
+    // into the cache restores as a permanent failure - the placeholder
+    // posture retries the (transient) fetch on the restoration visit.
+    this.#unsubscribeBeforeCache = onBeforeCache(() => this.#reset())
+
+    if (!this.element.getAttribute("src")) this.element.setAttribute("src", this.srcValue)
+  }
+
+  /** Unwires the listeners and the before-cache subscription. */
+  disconnect() {
+    this.element.removeEventListener("turbo:before-fetch-response", this.#onResponse)
+    this.element.removeEventListener("turbo:frame-missing", this.#failed)
+    this.element.removeEventListener("turbo:fetch-request-error", this.#failed)
+    this.#unsubscribeBeforeCache?.()
+    this.#unsubscribeBeforeCache = null
+  }
+
+  /**
+   * The retry action: back to the placeholder posture, then reload -
+   * Turbo's FrameElement#reload when the runtime is present, else the
+   * re-set-src fallback (the same signal Turbo reacts to).
+   */
+  retry() {
+    this.#reset()
+
+    if (typeof this.element.reload === "function") {
+      this.element.reload()
+    } else {
+      const src = this.element.getAttribute("src") || this.srcValue
+      this.element.removeAttribute("src")
+      this.element.setAttribute("src", src)
+    }
+  }
+
+  #onResponse = (event) => {
+    if (event.detail?.fetchResponse?.succeeded !== false) return
+
+    event.preventDefault()
+    this.#failed(event)
+  }
+
+  #failed = (event) => {
+    // Keep Turbo from acting on the failure itself (frame-missing default
+    // = promote the response to a page visit) - the error template below
+    // is the user-visible state.
+    if (event.type === "turbo:frame-missing") event.preventDefault()
+
+    this.element.setAttribute("data-error", "")
+    if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = true
+    if (this.hasErrorTarget && !this.#stamped) {
+      this.#stamped = this.errorTarget.content.firstElementChild?.cloneNode(true)
+      if (this.#stamped) this.element.appendChild(this.#stamped)
+    }
+  }
+
+  // Back to the placeholder posture (shared by retry and the
+  // before-cache teardown).
+  #reset() {
+    this.#stamped?.remove()
+    this.#stamped = null
+    this.element.removeAttribute("data-error")
+    if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = false
+  }
+
+  #stamped = null
+  #unsubscribeBeforeCache = null
+}

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

@@ -0,0 +1,206 @@
+import { Controller } from "@hotwired/stimulus"
+import { setState } from "@poetry/controllers/helpers/state"
+import { matchesHotkey } from "@poetry/controllers/helpers/hotkey"
+import { lockScroll, unlockScroll } from "@poetry/controllers/helpers/scroll_lock"
+import { onBeforeCache } from "@poetry/controllers/helpers/turbo_cache"
+import { exitPresence, flushPendingExits } from "@poetry/controllers/helpers/presence"
+
+// The native-dialog primitive: borrow the PLATFORM overlay -
+// showModal() gives the focus trap, Esc handling, top-layer stacking, and
+// focus return for free; this controller adds what the platform doesn't:
+// the data-open/data-closed pair for CSS variants, backdrop-click
+// dismissal, a body scroll-lock, and the presence-hold close - exit flips
+// the pair to data-closed and HOLDS the dialog through its CSS exit
+// animation before the native close() (synchronous when no exit animation
+// applies, so reduced-motion and unthemed hosts close instantly).
+// Consumed by Dialog (and AlertDialog / CommandDialog / Sheet).
+export default class extends Controller {
+  static targets = ["dialog"]
+  static values = {
+    // Set false for AlertDialog-style confirmations: backdrop clicks stop dismissing.
+    dismissible: { type: Boolean, default: true },
+    // OPT-IN global shortcut ("meta+k") toggling the dialog - the
+    // command-palette ⌘K affordance, shipped here because every
+    // consumer would otherwise write the same ten lines. "meta" matches metaKey OR
+    // ctrlKey (⌘K on mac, ^K elsewhere - the command-palette convention).
+    hotkey: { type: String, default: "" }
+  }
+
+  #onHotkey = null
+  #unsubscribeBeforeCache = null
+
+  /**
+   * Heals a restored zombie snapshot, subscribes the before-cache close,
+   * and arms the opt-in global hotkey.
+   */
+  connect() {
+    this.#healRestoredSnapshot()
+    // Close before Turbo snapshots: an open dialog serialized into the
+    // cache restores as a de-modalized zombie over a frozen scroll lock.
+    // The close is animated now, so the exit it starts must settle in
+    // this same tick - flush regardless of listener order (the presence
+    // module's own before-cache flush may already have run).
+    this.#unsubscribeBeforeCache = onBeforeCache(() => {
+      if (this.hasDialogTarget && this.dialogTarget.open) {
+        this.close()
+        flushPendingExits()
+      }
+    })
+
+    if (this.hotkeyValue === "") return
+
+    // defaultPrevented gate: two dialogs bound to the same descriptor
+    // degrade to first-registered-wins instead of both toggling open.
+    this.#onHotkey = (event) => {
+      if (event.defaultPrevented || !this.#matchesHotkey(event)) return
+
+      event.preventDefault()
+      this.toggle()
+    }
+    window.addEventListener("keydown", this.#onHotkey)
+  }
+
+  /**
+   * Balances the scroll lock and unwires the hotkey and before-cache
+   * subscriptions.
+   */
+  disconnect() {
+    this.unlockScroll()
+    this.#unsubscribeBeforeCache?.()
+    this.#unsubscribeBeforeCache = null
+
+    if (this.#onHotkey) {
+      window.removeEventListener("keydown", this.#onHotkey)
+      this.#onHotkey = null
+    }
+  }
+
+  // A dialog restored from a PRE-FIX cached snapshot: the open attribute
+  // survived serialization but :modal did not, and the body's inline
+  // scroll-lock styles came back with no refcount behind them. Normalize
+  // to closed and clear the orphaned lock styles directly (the refcounted
+  // helper is at zero on a fresh page and must not be decremented).
+  #healRestoredSnapshot() {
+    if (!this.hasDialogTarget) return
+
+    const dialog = this.dialogTarget
+
+    if (!dialog.open) return
+    // A genuinely modal dialog only reconnects mid-flight when its subtree
+    // is MOVED while open (the sidebar DOM-move class) - leave those alone.
+    // Engines without :modal support (happy-dom) treat open-at-connect as
+    // the zombie it almost certainly is.
+    let modal = false
+    try {
+      modal = dialog.matches(":modal")
+    } catch {
+      modal = false
+    }
+    if (modal) return
+
+    dialog.close()
+    setState(dialog, "closed")
+    document.body.style.overflow = ""
+    document.body.style.paddingRight = ""
+    document.documentElement.style.scrollbarGutter = ""
+  }
+
+  /** The toggle action (and the hotkey's landing): open <-> close. */
+  toggle() {
+    if (this.dialogTarget.open) this.close()
+    else this.open()
+  }
+
+  /**
+   * Opens modally: showModal() (the platform trap, top-layer and focus
+   * return), the pair flip, and the body scroll lock. Returns the
+   * resulting state (what an agent tool reports back).
+   *
+   * @returns {{ open: boolean, changed: boolean }}
+   */
+  open() {
+    if (this.dialogTarget.open) return { open: true, changed: false }
+
+    this.dialogTarget.showModal()
+    setState(this.dialogTarget, "open")
+    this.lockScroll()
+
+    return { open: true, changed: true }
+  }
+
+  /**
+   * Closes with the presence hold: flips the pair to data-closed and
+   * holds the dialog through its CSS exit animation before the native
+   * close() and the unlock (synchronous when no exit animation applies).
+   * The native cancel event (Esc) routes through here so state stays in
+   * sync.
+   *
+   * @param {Event} [event] - the native cancel event, when Esc drove it
+   * @returns {{ open: boolean, changed: boolean }} the resulting state (what an agent tool reports back)
+   */
+  close(event) {
+    if (event?.type === "cancel") event.preventDefault() // route Esc through close() so state stays in sync
+    if (this.#closing || !this.dialogTarget.open) return { open: false, changed: false }
+
+    this.#closing = true
+    exitPresence(this.dialogTarget, {
+      onRemove: () => {
+        this.#closing = false
+        this.dialogTarget.close()
+        this.unlockScroll()
+      }
+    })
+
+    return { open: false, changed: true }
+  }
+
+  /**
+   * The click action discriminating backdrop presses: a backdrop click
+   * targets the <dialog> element itself AND lands outside its bounding
+   * rect (the backdrop is rendered by the dialog). The target check alone
+   * is not enough: clicks on the dialog's own padding / grid gaps also
+   * target the element (found in a live browser pass - they were
+   * incorrectly dismissing).
+   *
+   * @param {MouseEvent} event
+   */
+  backdropClose(event) {
+    if (!this.dismissibleValue) return
+    if (event.target !== this.dialogTarget) return
+
+    const rect = this.dialogTarget.getBoundingClientRect()
+    const inside = rect.top <= event.clientY && event.clientY <= rect.bottom &&
+      rect.left <= event.clientX && event.clientX <= rect.right
+    if (!inside) this.close()
+  }
+
+  // The descriptor grammar lives in helpers/hotkey.js (shared with the
+  // generic hotkey controller).
+  #matchesHotkey(event) {
+    return matchesHotkey(event, this.hotkeyValue)
+  }
+
+  /**
+   * Takes the shared refcounted body scroll lock (scrollbar-width
+   * compensated) - subclasses (sheet/drawer/sidebar) inherit these entry
+   * points unchanged; the instance flag keeps double-unlocks (disconnect
+   * after close) balanced.
+   */
+  lockScroll() {
+    if (this.#locked) return
+
+    this.#locked = true
+    lockScroll()
+  }
+
+  /** Balances {@link lockScroll}; safe when already unlocked. */
+  unlockScroll() {
+    if (!this.#locked) return
+
+    this.#locked = false
+    unlockScroll()
+  }
+
+  #locked = false
+  #closing = false
+}

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

@@ -0,0 +1,182 @@
+import { Controller } from "@hotwired/stimulus"
+import { onEscapeKeydown } from "@poetry/controllers/helpers/escape"
+import { onBeforeCache } from "@poetry/controllers/helpers/turbo_cache"
+import { flushPendingExits } from "@poetry/controllers/helpers/presence"
+
+// The dismissal layer: Escape + pointerdown-outside for every
+// overlay. This controller NEVER removes DOM - it dispatches "dismiss" and
+// the consumer closes itself (removes the node, collapses a disclosure,
+// navigates a frame). The class-level stack makes Esc topmost-only, so
+// stacked overlays peel one at a time.
+export default class DismissableController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = [
+    "poetry--core--dismissable:dismiss", "poetry--core--dismissable:interact-outside"
+  ]
+
+  static stack = []
+
+  // The body pointer-events scrim (the CSS-only modal): refcounted across
+  // layers that request it, each such layer opting its own element back in.
+  static #scrimCount = 0
+  static #previousBodyPointerEvents = null
+
+  static values = {
+    disableOutsidePointerEvents: { type: Boolean, default: false }
+  }
+
+  // Pages cached BEFORE the before-cache teardown shipped carry a poisoned
+  // body (inline pointer-events:none serialized with no live scrim behind
+  // it) - and no layer connects on the restored page to release it. Heal
+  // on every Turbo render: with zero scrim holders, the style can only be
+  // a serialized leftover.
+  static {
+    if (typeof document !== "undefined") {
+      document.addEventListener("turbo:load", () => {
+        if (DismissableController.#scrimCount === 0 && document.body?.style.pointerEvents === "none") {
+          document.body.style.pointerEvents = ""
+        }
+      })
+    }
+  }
+
+  #unsubscribeEscape = null
+  #unsubscribeBeforeCache = null
+  #onPointerdown = (event) => this.#handlePointerdown(event)
+
+  /**
+   * Registers on the layer stack, wires the capture-phase Escape and
+   * pointerdown listeners, subscribes the before-cache dismissal, and
+   * takes the body scrim when configured.
+   */
+  connect() {
+    DismissableController.stack.push(this)
+
+    // Both capture-phase: the layer must see the interaction before any
+    // inner handler can swallow it (the escape helper defaults to capture).
+    this.#unsubscribeEscape = onEscapeKeydown((event) => this.#handleEscape(event))
+    document.addEventListener("pointerdown", this.#onPointerdown, { capture: true })
+    // A layer still open when Turbo snapshots serializes its scrim's
+    // inline body pointer-events into the cache - a restored page is
+    // click-dead. Dismiss synchronously so the snapshot is clean, and
+    // release the scrim HERE too: the owner's close resets its own
+    // attributes in the same tick, but its unmount (which normally
+    // releases the scrim via disconnect) can ride an exit transition -
+    // after the snapshot is already taken.
+    this.#unsubscribeBeforeCache = onBeforeCache(() => {
+      this.#dismiss(null)
+      // The dismiss just started the owner's exit presence - flush it in
+      // the same tick so hidden + layer-controller removal land BEFORE
+      // the snapshot (a serialized live layer resurrects on restore).
+      flushPendingExits()
+      this.#disableScrim()
+    })
+
+    if (this.disableOutsidePointerEventsValue) this.#enableScrim()
+  }
+
+  /**
+   * Leaves the stack and unwires everything, releasing the scrim when
+   * held.
+   */
+  disconnect() {
+    const index = DismissableController.stack.indexOf(this)
+
+    if (index !== -1) DismissableController.stack.splice(index, 1)
+
+    this.#unsubscribeEscape?.()
+    this.#unsubscribeEscape = null
+    document.removeEventListener("pointerdown", this.#onPointerdown, { capture: true })
+    this.#unsubscribeBeforeCache?.()
+    this.#unsubscribeBeforeCache = null
+
+    if (this.disableOutsidePointerEventsValue) this.#disableScrim()
+  }
+
+  #handleEscape(event) {
+    if (!this.#topmost()) return
+
+    this.#dismiss(event)
+  }
+
+  // pointerdown, not click: dismissal happens on press, so a drag
+  // that starts inside can never end up counting as outside.
+  #handlePointerdown(event) {
+    // A target already unhooked from the document (a Turbo morph or an
+    // earlier handler removed it mid-gesture) says nothing about WHERE the
+    // press landed - dismissing on it is the false-dismiss class.
+    if (!(event.target instanceof Element) || !event.target.isConnected) return
+
+    // composedPath, not contains(): the path is fixed at dispatch, so a
+    // press on a node an inner handler removes (a chip, a swapped row)
+    // still counts as inside - and shadow-DOM retargeting can't hide it.
+    const path = event.composedPath()
+
+    if (path.includes(this.element)) return
+    // A press inside a HIGHER layer (a nested overlay, often portaled out
+    // of this subtree) is inside the stack, not "outside" this layer.
+    if (this.#layersAbove().some((layer) => path.includes(layer.element))) return
+    // The top layer (toasts) sits above EVERY dismissal layer by fiat:
+    // pressing a toast must never dismiss the overlay under it.
+    if (event.target.closest("[data-poetry-top-layer]")) return
+
+    const interactOutside = this.dispatch("interact-outside", {
+      detail: { originalEvent: event },
+      cancelable: true
+    })
+
+    if (interactOutside.defaultPrevented) return // consumer veto: no dismiss
+
+    this.#dismiss(event)
+  }
+
+  #dismiss(originalEvent) {
+    this.dispatch("dismiss", { detail: { originalEvent } })
+  }
+
+  #topmost() {
+    return DismissableController.stack.at(-1) === this
+  }
+
+  #layersAbove() {
+    return DismissableController.stack.slice(DismissableController.stack.indexOf(this) + 1)
+  }
+
+  // Per-instance flag so enable/disable pair exactly once: the
+  // before-cache release and the later disconnect (after the owner's
+  // deferred unmount) must not double-decrement.
+  #scrimEnabled = false
+
+  #enableScrim() {
+    if (this.#scrimEnabled) return
+
+    this.#scrimEnabled = true
+
+    if (DismissableController.#scrimCount === 0) {
+      // Never save a value this scrim itself writes: a page restored from
+      // a cached snapshot arrives with the serialized "none" already on
+      // the body, and saving it would make every later restore re-freeze
+      // the page (the poisoned-previous restore class).
+      const current = document.body.style.pointerEvents
+      DismissableController.#previousBodyPointerEvents = current === "none" ? "" : current
+      document.body.style.pointerEvents = "none"
+    }
+
+    DismissableController.#scrimCount += 1
+    this.element.style.pointerEvents = "auto"
+  }
+
+  #disableScrim() {
+    if (!this.#scrimEnabled) return
+
+    this.#scrimEnabled = false
+    DismissableController.#scrimCount -= 1
+    this.element.style.pointerEvents = ""
+
+    if (DismissableController.#scrimCount === 0) {
+      document.body.style.pointerEvents = DismissableController.#previousBodyPointerEvents ?? ""
+      DismissableController.#previousBodyPointerEvents = null
+    }
+  }
+}