turbo_overlay 0.3.0

data/app/javascript/turbo_overlay/history.js

@@ -0,0 +1,184 @@
+// URL advance bookkeeping for turbo_overlay.
+//
+// `advance: true` on a modal_link_to / drawer_link_to (or a per-type
+// config default) pushes a history entry when the overlay opens, so
+// the URL bar reflects what the user is looking at and browser-back
+// closes the top overlay instead of navigating away from the page
+// beneath. Popovers and hints never advance — they're ephemeral and
+// shouldn't churn browser history.
+//
+// State lives at module scope so the bookkeeping survives Stimulus
+// disconnect/reconnect and idiomorph re-renders (the dialog node may
+// be morphed in place; the controller instance can be re-created;
+// the overlay id is the stable key).
+
+// Resolved advance URL set by the click handler before the fetch
+// goes out; consumed by the overlay controller when `shown` fires.
+const advanceUrls = new Map()
+
+// Overlays we've called history.pushState for. Keyed by overlay id so
+// close-path code can ask "did we push for this overlay?" without
+// reaching into a possibly-discarded controller instance.
+const pushedEntries = new Map()
+
+// Counter of popstates we caused ourselves via `history.back()` and
+// must swallow before the popstate handler treats one as user input.
+let expectedPopstates = 0
+
+// Read-only accessor for setup.js's `turbo:before-visit` guard.
+// Exposed as a function so the value reflects the current count, not
+// a snapshot at import time.
+export function expectedPopstateCount() {
+  return expectedPopstates
+}
+
+// True if any currently-tracked overlay entry on the stack has a
+// `pushed` record. Used by setup.js to decide whether to cancel a
+// Turbo restoration visit that was triggered by popstate over an
+// advance-pushed entry.
+export function hasPushedOverlayOnStack() {
+  if (!stackController || !stackController.entries) return false
+  for (const entry of stackController.entries) {
+    if (entry && pushedEntries.has(entry.id)) return true
+  }
+  return false
+}
+
+// Live reference to the per-page stack controller. The stack
+// Stimulus controller calls `setStackController(this)` on connect and
+// `setStackController(null)` on disconnect. Used by the popstate
+// handler to walk the stack without reaching into Stimulus internals
+// from setup.js (which is not itself a controller).
+let stackController = null
+
+export function setStackController(controller) {
+  stackController = controller
+}
+
+export function getStackController() {
+  return stackController
+}
+
+export function setAdvanceUrl(id, url) {
+  if (!id) return
+  if (url) advanceUrls.set(id, url)
+  else advanceUrls.delete(id)
+}
+
+export function getAdvanceUrl(id) {
+  return id ? (advanceUrls.get(id) || null) : null
+}
+
+export function clearAdvanceUrl(id) {
+  if (id) advanceUrls.delete(id)
+}
+
+export function markPushed(id, url, type) {
+  if (!id) return
+  pushedEntries.set(id, { url, type })
+}
+
+export function isPushed(id) {
+  return !!(id && pushedEntries.has(id))
+}
+
+export function clearPushed(id) {
+  if (id) pushedEntries.delete(id)
+}
+
+// Count entries from a stack snapshot whose id has a `pushed` record.
+// Used by close-path code to detect whether a given close actually
+// reduced the live pushed count (and therefore should reverse history).
+export function livePushedCount(stackEntries) {
+  if (!stackEntries || !stackEntries.length) return 0
+  let n = 0
+  for (const e of stackEntries) {
+    if (e && pushedEntries.has(e.id)) n += 1
+  }
+  return n
+}
+
+export function pushOverlayState(id, type, url) {
+  if (typeof window === "undefined" || !window.history) return
+  try {
+    window.history.pushState(
+      { turboOverlay: { id, type } },
+      "",
+      url
+    )
+  } catch (_) {
+    // pushState can throw on cross-origin URLs; treat as "didn't push"
+    // so the close path won't try to reverse a history entry that
+    // doesn't exist. The caller is expected to skip markPushed too if
+    // this throws — but we're defensive: the caller's surrounding
+    // try/catch will handle it.
+    throw _
+  }
+}
+
+export function reverseHistoryForClose() {
+  if (typeof window === "undefined" || !window.history) return
+  expectedPopstates += 1
+  try {
+    window.history.back()
+  } catch (_) {
+    // Same defensive note as pushOverlayState. If back() throws we'll
+    // have an over-counted expectedPopstates that one stray popstate
+    // (if it ever fires) would swallow. Acceptable.
+  }
+}
+
+// Wipe state at navigation boundaries. The pushed history entries the
+// gem created remain in the session-history backing store — the user
+// could still navigate back to them — but the gem no longer tracks
+// them, so a popstate landing on one of those URLs after navigation
+// is treated as a regular user-initiated history navigation (no
+// overlay matches; we no-op).
+export function resetHistoryState() {
+  advanceUrls.clear()
+  pushedEntries.clear()
+  expectedPopstates = 0
+}
+
+export function registerPopstateHandler() {
+  if (typeof window === "undefined") return
+  if (window._turboOverlayPopstateRegistered) return
+  window._turboOverlayPopstateRegistered = true
+
+  // Two responsibilities:
+  //
+  //   1. If we caused this popstate via `history.back()` (close path),
+  //      just decrement the counter. The matching overlay was already
+  //      cleared from `pushedEntries` before history.back().
+  //
+  //   2. If the user pressed browser-back over an advance overlay's
+  //      pushed URL, close the topmost overlay whose id is still in
+  //      `pushedEntries`. The overlay's close path sees `_closedByBack`
+  //      and skips its own `history.back()` so we don't double-pop.
+  //
+  // Note: we can't stop Turbo Drive's own popstate handler from
+  // running (for window-only events, capture/bubble flags don't
+  // change at-target order; Turbo's handler is registered first via
+  // its own import order and runs first). The protection against
+  // Turbo's `historyPoppedWithEmptyState` → `before-cache` → teardown
+  // chain lives in setup.js, which gates `tearDownAllOverlays` on
+  // whether a real Turbo visit is actually in progress.
+  window.addEventListener("popstate", () => {
+    if (expectedPopstates > 0) {
+      expectedPopstates -= 1
+      return
+    }
+    const stack = stackController
+    if (!stack || !stack.entries) return
+    for (let i = stack.entries.length - 1; i >= 0; i--) {
+      const entry = stack.entries[i]
+      if (!entry || !entry.controller) continue
+      if (!pushedEntries.has(entry.id)) continue
+      entry.controller._closedByBack = true
+      if (typeof entry.controller.close === "function") {
+        entry.controller.close()
+      }
+      return
+    }
+  })
+}

data/app/javascript/turbo_overlay/index.js

@@ -0,0 +1,53 @@
+import "turbo_overlay/setup"
+import "turbo_overlay/hint"
+import { registerConfirm } from "turbo_overlay/setup"
+import StackController from "turbo_overlay/stack_controller"
+import OverlayController from "turbo_overlay/overlay_controller"
+import { visit } from "turbo_overlay/visit"
+
+// Single entry point for the gem's Stimulus controllers.
+//
+//   import { register } from "turbo_overlay"
+//   register(application)
+//
+// Registers two controllers under their canonical identifiers:
+// `turbo-overlay-stack` and `turbo-overlay`.
+//
+// Importing this module also runs `turbo_overlay/setup` (page-level
+// wiring: request-header injection, loading placeholders, back/forward
+// cache teardown, the `turbo_stream.overlay` custom stream action) and
+// `turbo_overlay/hint` (hover-triggered preview module). Both
+// self-bootstrap and are guarded by `window._turboOverlay*Registered`
+// flags, so importing this entry point more than once is safe.
+//
+// Pass `{ confirm: true }` to also route `data-turbo-confirm` on
+// links/forms through the gem's themed overlay instead of the
+// browser-native `window.confirm`. Requires confirm chrome partials
+// in `app/views/turbo_overlay/` (copied by `turbo_overlay:install`);
+// falls back to native `confirm` if no variant partial is present.
+//
+//   register(application, { confirm: true })
+//
+// The hint module is loaded unconditionally — it's inert until a link
+// carrying `data-turbo-overlay-hint` is hovered.
+export function register(application, options = {}) {
+  application.register("turbo-overlay-stack", StackController)
+  application.register("turbo-overlay", OverlayController)
+  if (options.confirm) registerConfirm()
+}
+
+export { StackController, OverlayController, registerConfirm, visit }
+
+// Expose a window global so non-bundler callers — inline `onclick`,
+// third-party callbacks (Google Maps markers, Leaflet popups), custom
+// elements that don't import from this package — can call
+// `TurboOverlay.visit(url, opts)` without a module import. Assigned at
+// import time, not inside `register()`, so it's available the moment
+// the gem's JS loads.
+if (typeof window !== "undefined") {
+  window.TurboOverlay = Object.assign(window.TurboOverlay || {}, {
+    visit,
+    register,
+    registerConfirm,
+  })
+}

data/app/javascript/turbo_overlay/options.js

@@ -0,0 +1,152 @@
+// Single source of truth for the overlay trigger contract — option
+// names, dataset attribute names, request header names, encoding rules,
+// type restrictions, plus the validation + dataset-build helpers that
+// the JS-facing `visit()` API relies on.
+//
+// Three places write or read these mappings:
+//   1. Ruby view helpers (`view_helper.rb`) — write dataset attributes
+//      when rendering `modal_link_to` / `drawer_link_to` /
+//      `popover_link_to`. Authoritative on the server side; Ruby can't
+//      share this table.
+//   2. `visit.js` — writes dataset attributes on a synthesized link
+//      when JS code calls `TurboOverlay.visit(url, opts)`. Uses
+//      `buildOverlayDataset` and `validateVisitArgs` from this file.
+//   3. `setup.js` (turbo:before-fetch-request hook) — reads dataset
+//      attributes off the trigger and emits the X-Turbo-Overlay-*
+//      headers via `emitOverlayHeaders` from this file.
+//
+// (2) and (3) both consume this table. Adding a header-bearing option
+// here is enough to make it round-trip through `visit()` and the fetch
+// hook. The Ruby helper must still be updated in parallel.
+//
+// This module deliberately has no imports so it stays unit-testable
+// under plain `node --test` (no DOM, no importmap).
+//
+// Encoding rules mirror `_overlay_normalize_link_args` at
+// `lib/turbo_overlay/helpers/view_helper.rb:454-482`:
+//   - `backdrop` / `close` only emit on `false` (the non-default)
+//   - `keepOpenOnRedirect` only emits on `true` (the non-default)
+//   - `advance` is restricted to modal/drawer
+//   - everything else emits whenever a value is supplied
+
+export const OVERLAY_OPTIONS = [
+  {
+    key: "id",
+    dataset: "turboOverlayId",
+    header: "X-Turbo-Overlay-Id",
+  },
+  {
+    key: "position",
+    dataset: "turboOverlayPosition",
+    header: "X-Turbo-Overlay-Position",
+  },
+  {
+    key: "align",
+    dataset: "turboOverlayAlign",
+    header: "X-Turbo-Overlay-Align",
+  },
+  {
+    key: "offset",
+    dataset: "turboOverlayOffset",
+    header: "X-Turbo-Overlay-Offset",
+  },
+  {
+    key: "backdrop",
+    dataset: "turboOverlayBackdrop",
+    header: "X-Turbo-Overlay-Backdrop",
+    onlyWhen: (v) => v === false,
+    encode: () => "false",
+  },
+  {
+    key: "close",
+    dataset: "turboOverlayClose",
+    header: "X-Turbo-Overlay-Close",
+    onlyWhen: (v) => v === false,
+    encode: () => "false",
+  },
+  {
+    key: "keepOpenOnRedirect",
+    dataset: "turboOverlayKeepOpenOnRedirect",
+    header: "X-Turbo-Overlay-Keep-Open",
+    onlyWhen: (v) => v === true,
+    encode: () => "true",
+  },
+  {
+    key: "advance",
+    dataset: "turboOverlayAdvance",
+    onlyTypes: ["modal", "drawer"],
+    encode: (v) => (v === true ? "true" : v === false ? "false" : String(v)),
+  },
+]
+
+export const VALID_TYPES = ["modal", "drawer", "popover", "hint"]
+
+// Writes dataset attributes on `el` for each option in `opts` whose
+// entry passes the table's gating rules. `type` is the overlay type
+// (modal/drawer/popover/hint) and is used to honor `onlyTypes`.
+//
+// Returns nothing; mutates `el.dataset` in place. `el` is duck-typed —
+// any object with a `.dataset` property works.
+export function applyOverlayOptions(el, type, opts) {
+  for (const entry of OVERLAY_OPTIONS) {
+    const value = opts[entry.key]
+    if (value === undefined || value === null) continue
+    if (entry.onlyTypes && !entry.onlyTypes.includes(type)) continue
+    if (entry.onlyWhen && !entry.onlyWhen(value)) continue
+    el.dataset[entry.dataset] = entry.encode ? entry.encode(value) : String(value)
+  }
+}
+
+// Reads dataset attributes from a trigger element and writes the
+// corresponding X-Turbo-Overlay-* headers into `headers`. Only entries
+// that declare a `header` participate (e.g. `advance` is dataset-only —
+// the server reads it from the response context, not a request header).
+export function emitOverlayHeaders(dataset, headers) {
+  for (const entry of OVERLAY_OPTIONS) {
+    if (!entry.header) continue
+    const value = dataset[entry.dataset]
+    if (value === undefined || value === null || value === "") continue
+    headers[entry.header] = value
+  }
+}
+
+// Returns the dataset object that a trigger element synthesized by
+// `visit()` should carry. Includes the three always-present attributes
+// (`turboStream`, `turboOverlay`, `turboFrame`) plus everything written
+// by `applyOverlayOptions`.
+export function buildOverlayDataset(type, options = {}) {
+  const target = { dataset: {} }
+  target.dataset.turboStream = "true"
+  target.dataset.turboOverlay = type
+  target.dataset.turboFrame = options.frame || "_top"
+  applyOverlayOptions(target, type, options)
+  return target.dataset
+}
+
+// Validates the (url, options) pair `visit()` receives. Throws
+// TypeError on misuse. Returns the resolved overlay type so callers
+// don't have to re-derive it.
+//
+// Popovers must carry an `anchor` element — the synthesized trigger
+// link has no useful bounding rect, so `setup.js` reads the anchor off
+// `link.__turboOverlayAnchor` to position the popover. We skip the
+// `instanceof Element` check when `Element` is undefined (the node test
+// environment) so the pure validation can be unit-tested with a duck.
+export function validateVisitArgs(url, options) {
+  if (typeof url !== "string" || url.length === 0) {
+    throw new TypeError("TurboOverlay.visit: url must be a non-empty string")
+  }
+  const type = options.type || "modal"
+  if (!VALID_TYPES.includes(type)) {
+    throw new TypeError(
+      `TurboOverlay.visit: invalid type "${type}" (expected one of ${VALID_TYPES.join(", ")})`
+    )
+  }
+  if (type === "popover") {
+    const ElementCtor = typeof Element === "function" ? Element : null
+    if (!options.anchor || (ElementCtor && !(options.anchor instanceof ElementCtor))) {
+      throw new TypeError("TurboOverlay.visit: popover requires an `anchor` element")
+    }
+  }
+  return type
+}