unmagic-components 0.1.0 → 0.2.0

data/app/assets/javascripts/unmagic/components/tabs.js

@@ -0,0 +1,94 @@
+// <unmagic-tabs> — tabs that switch panels in the page, rendered by `tabs`.
+//
+// The server renders the whole ARIA tab pattern (roles, aria-controls, the
+// selected tab and the hidden panels), so the element only moves the selection:
+// on a click, or with the arrow keys, Home and End, which also move focus. Only the
+// selected tab is in the tab order.
+//
+// When the element has an id, the chosen tab is remembered in sessionStorage for
+// that page, and re-applied after a morph refresh (which resets the markup to the
+// server's selection). Each change fires unmagic-tabs:change.
+
+class UnmagicTabs extends HTMLElement {
+  constructor() {
+    super()
+    this.addEventListener("click", this.#clicked)
+    this.addEventListener("keydown", this.#keydown)
+  }
+
+  connectedCallback() {
+    this.#restore()
+    document.addEventListener("turbo:morph", this.#restore)
+  }
+
+  disconnectedCallback() {
+    document.removeEventListener("turbo:morph", this.#restore)
+  }
+
+  get tabs() {
+    return [...this.querySelectorAll(":scope > [role=tablist] > [role=tab]")]
+  }
+
+  select(tab, { focus = false, remember = true } = {}) {
+    for (const each of this.tabs) {
+      const selected = each === tab
+      each.setAttribute("aria-selected", String(selected))
+      each.tabIndex = selected ? 0 : -1
+
+      const panel = document.getElementById(each.getAttribute("aria-controls"))
+      if (panel) panel.hidden = !selected
+    }
+
+    if (focus) tab.focus()
+    if (!remember) return
+
+    const key = this.#storageKey
+    if (key) {
+      try {
+        sessionStorage.setItem(key, tab.id)
+      } catch {
+        // Storage can be unavailable (a private window, blocked site data); the
+        // selection just isn't remembered.
+      }
+    }
+    this.dispatchEvent(new CustomEvent("unmagic-tabs:change", { bubbles: true, detail: { tab } }))
+  }
+
+  #clicked = (event) => {
+    const tab = event.target instanceof Element && event.target.closest("[role=tab]")
+    if (tab && this.tabs.includes(tab)) this.select(tab)
+  }
+
+  #keydown = (event) => {
+    const tabs = this.tabs
+    const index = tabs.indexOf(event.target)
+    if (index === -1) return
+
+    const targets = { ArrowRight: index + 1, ArrowLeft: index - 1, Home: 0, End: tabs.length - 1 }
+    if (!(event.key in targets)) return
+
+    event.preventDefault()
+    this.select(tabs[(targets[event.key] + tabs.length) % tabs.length], { focus: true })
+  }
+
+  #restore = () => {
+    const key = this.#storageKey
+    if (!key) return
+
+    let id
+    try {
+      id = sessionStorage.getItem(key)
+    } catch {
+      return
+    }
+
+    const tab = id && this.tabs.find((each) => each.id === id)
+    if (tab) this.select(tab, { remember: false })
+  }
+
+  get #storageKey() {
+    return this.id ? `unmagic-tabs:${location.pathname}:${this.id}` : null
+  }
+}
+
+customElements.get("unmagic-tabs") || customElements.define("unmagic-tabs", UnmagicTabs)

data/app/assets/javascripts/unmagic/components/time.js

@@ -0,0 +1,169 @@
+// <unmagic-time> — a timestamp in the viewer's own locale and time zone, rendered
+// by `local_time_tag`.
+//
+//   <unmagic-time datetime="2026-09-16T04:33:24Z" format="relative">
+//     <time datetime="2026-09-16T04:33:24Z">about 3 hours ago</time>
+//   </unmagic-time>
+//
+// The server's text is the fallback until this upgrades; after that the element
+// writes into its <time> with Intl, so the words come from the browser's locale
+// rather than from anything hand-written here.
+//
+// Attributes:
+//   datetime  an ISO 8601 timestamp
+//   format    short | medium | long | full (a date and a time), date, time, or
+//             relative. Defaults to medium.
+//   compact   on a relative time, "5m" rather than "5 minutes ago"
+//
+// A relative time keeps itself current from one shared, minute-aligned clock, and
+// stops ticking once it has settled into a date (a week out).
+
+const ABSOLUTE = {
+  short: { dateStyle: "short", timeStyle: "short" },
+  medium: { dateStyle: "medium", timeStyle: "short" },
+  long: { dateStyle: "long", timeStyle: "short" },
+  full: { dateStyle: "full", timeStyle: "long" },
+  date: { dateStyle: "medium" },
+  time: { timeStyle: "short" },
+}
+
+class UnmagicTime extends HTMLElement {
+  static observedAttributes = ["datetime", "format", "compact"]
+
+  #unsubscribe = null
+
+  connectedCallback() {
+    this.#render()
+  }
+
+  disconnectedCallback() {
+    this.#stopTicking()
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this.#render()
+  }
+
+  get #target() {
+    return this.querySelector(":scope > time") ?? this
+  }
+
+  #render() {
+    const date = new Date(this.getAttribute("datetime"))
+    if (Number.isNaN(date.getTime())) return
+
+    const format = this.getAttribute("format") || "medium"
+    if (format === "relative") {
+      this.#renderRelative(date)
+    } else {
+      this.#stopTicking()
+      this.#target.textContent = formatter(ABSOLUTE[format] ?? ABSOLUTE.medium).format(date)
+    }
+  }
+
+  #renderRelative(date) {
+    const { text, live } = relative(date, new Date(), this.hasAttribute("compact"))
+    const target = this.#target
+    target.textContent = text
+    target.title = formatter({ dateStyle: "long", timeStyle: "short" }).format(date)
+
+    if (live && !this.#unsubscribe) this.#unsubscribe = subscribe(() => this.#render())
+    if (!live) this.#stopTicking()
+  }
+
+  #stopTicking() {
+    this.#unsubscribe?.()
+    this.#unsubscribe = null
+  }
+}
+
+// The ladder: under a minute, minutes, hours while it's still the same day,
+// yesterday/tomorrow, days within the week, then a date that no longer changes.
+// Days are calendar days in the viewer's zone, so "yesterday" turns at midnight.
+//
+// Units round to the nearest, not down: a time rendered two hours ahead is a few
+// seconds under two hours by the time this runs, and should still say "in 2 hours".
+function relative(date, now, compact) {
+  const seconds = Math.round((date - now) / 1000)
+  const sign = Math.sign(seconds) || -1
+  const minutes = Math.round(Math.abs(seconds) / 60)
+  const hours = Math.round(Math.abs(seconds) / 3600)
+  const days = calendarDays(date, now)
+
+  if (minutes === 0) return { text: phrase(0, "second", compact), live: true }
+  if (minutes < 60) return { text: phrase(sign * minutes, "minute", compact), live: true }
+  if (days === 0) return { text: phrase(sign * hours, "hour", compact), live: true }
+  if (Math.abs(days) <= 6) return { text: phrase(days, "day", compact), live: true }
+
+  const options = { day: "numeric", month: compact ? "short" : "long" }
+  if (date.getFullYear() !== now.getFullYear()) options.year = "numeric"
+  return { text: formatter(options).format(date), live: false }
+}
+
+// "now", "5 minutes ago", "yesterday", "in 3 days" — or, compact, "5m", "3h".
+function phrase(value, unit, compact) {
+  if (compact && value !== 0) {
+    return formatter({ style: "unit", unit, unitDisplay: "narrow" }, Intl.NumberFormat).format(Math.abs(value))
+  }
+  return formatter({ numeric: "auto", style: compact ? "narrow" : "long" }, Intl.RelativeTimeFormat).format(value, unit)
+}
+
+function calendarDays(date, now) {
+  const midnight = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate())
+  return Math.round((midnight(date) - midnight(now)) / 86_400_000)
+}
+
+// Building an Intl formatter is the only real cost here, so each is made once and
+// shared by every element on the page.
+const formatters = new Map()
+function formatter(options, Formatter = Intl.DateTimeFormat) {
+  const key = `${Formatter.name}:${JSON.stringify(options)}`
+  if (!formatters.has(key)) formatters.set(key, new Formatter(undefined, options))
+  return formatters.get(key)
+}
+
+// One timer for every live element, aligned to the wall-clock minute, so a page of
+// relative times rolls over together. It pauses while the tab is hidden and
+// catches up the moment it's seen again.
+const subscribers = new Set()
+let timer = null
+let watchingVisibility = false
+
+function subscribe(callback) {
+  if (!watchingVisibility) {
+    watchingVisibility = true
+    document.addEventListener("visibilitychange", () => {
+      if (document.hidden) return stop()
+      notify()
+      schedule()
+    })
+  }
+
+  subscribers.add(callback)
+  schedule()
+
+  return () => {
+    subscribers.delete(callback)
+    if (subscribers.size === 0) stop()
+  }
+}
+
+function schedule() {
+  if (timer || subscribers.size === 0 || document.hidden) return
+  timer = setTimeout(() => {
+    timer = null
+    notify()
+    schedule()
+  }, 60_000 - (Date.now() % 60_000))
+}
+
+function stop() {
+  clearTimeout(timer)
+  timer = null
+}
+
+function notify() {
+  for (const callback of [...subscribers]) callback()
+}
+
+customElements.get("unmagic-time") || customElements.define("unmagic-time", UnmagicTime)

data/app/assets/javascripts/unmagic/components/toasts.js

@@ -0,0 +1,171 @@
+// <unmagic-toasts> — the toasts a layout mounts with `flash_toasts`.
+//
+// Each toast arrives as an inert <template data-unmagic-toast-template> inside the
+// element: rendered with the page, morphed in by a refresh, or appended by
+// turbo_stream.toast. The element clones each one into its stack, animates it in,
+// and dismisses it after the element's `duration` (milliseconds). Hovering or
+// focusing a toast holds it open.
+//
+// The stack is data-turbo-permanent, so a toast on screen survives a Drive visit
+// or a morph. Its timer lives here, in the module, keyed by the toast rather than
+// by the element, because Turbo moves the stack into a fresh <unmagic-toasts> on
+// every visit.
+//
+// The stack is also a manual popover. Showing it puts it in the top layer, where a
+// toast can appear above an open modal dialog; showing it again after a dialog
+// opens lifts it back above. It is only seen there, not touched: a modal dialog
+// makes everything outside it inert, top-layer popovers included, so a toast over
+// one can't be hovered or dismissed until the dialog closes. It still times out.
+
+const DURATION = 5000
+const LEAVE = 200
+const MINIMUM_AFTER_HOLD = 1000
+
+const timers = new WeakMap()
+
+class UnmagicToasts extends HTMLElement {
+  #observer = new MutationObserver(() => this.#consume())
+
+  connectedCallback() {
+    this.#observer.observe(this, { childList: true })
+    this.addEventListener("click", this.#dismiss)
+    this.addEventListener("pointerover", this.#hold)
+    this.addEventListener("focusin", this.#hold)
+    this.addEventListener("pointerout", this.#release)
+    this.addEventListener("focusout", this.#release)
+    document.addEventListener("turbo:render", this.#lift)
+
+    this.stack?.querySelectorAll("[data-unmagic-toast]").forEach((toast) => schedule(toast, this.duration))
+    this.#consume()
+    this.#lift()
+  }
+
+  disconnectedCallback() {
+    this.#observer.disconnect()
+    this.removeEventListener("click", this.#dismiss)
+    this.removeEventListener("pointerover", this.#hold)
+    this.removeEventListener("focusin", this.#hold)
+    this.removeEventListener("pointerout", this.#release)
+    this.removeEventListener("focusout", this.#release)
+    document.removeEventListener("turbo:render", this.#lift)
+  }
+
+  get stack() {
+    return this.querySelector(":scope > .UnmagicToasts__stack")
+  }
+
+  get duration() {
+    const duration = Number(this.getAttribute("duration"))
+    return duration > 0 ? duration : DURATION
+  }
+
+  #consume() {
+    const stack = this.stack
+    const templates = this.querySelectorAll(":scope > template[data-unmagic-toast-template]")
+    if (!stack || templates.length === 0) return
+
+    for (const template of templates) {
+      // Consume the source first, so a later morph or mutation can't pop it twice.
+      template.remove()
+
+      const toast = template.content.firstElementChild?.cloneNode(true)
+      if (!toast) continue
+
+      stack.append(toast)
+      toast.getBoundingClientRect() // commit the starting style so the entrance transitions
+      toast.setAttribute("data-open", "")
+      schedule(toast, this.duration)
+    }
+
+    this.#lift()
+  }
+
+  #lift = () => {
+    const stack = this.stack
+    if (!stack?.showPopover) return
+
+    const open = stack.matches(":popover-open")
+    if (!stack.querySelector("[data-unmagic-toast]")) {
+      if (open) stack.hidePopover()
+      return
+    }
+
+    if (open) stack.hidePopover()
+    stack.showPopover()
+  }
+
+  #dismiss = (event) => {
+    const button = event.target instanceof Element && event.target.closest("[data-unmagic-toast-dismiss]")
+    if (button) remove(button.closest("[data-unmagic-toast]"))
+  }
+
+  #hold = (event) => {
+    const toast = event.target instanceof Element && event.target.closest("[data-unmagic-toast]")
+    if (toast) pause(toast)
+  }
+
+  // pointerout and focusout also fire when moving between a toast's own children,
+  // so wait a frame and ask whether it is still hovered or focused.
+  #release = (event) => {
+    const toast = event.target instanceof Element && event.target.closest("[data-unmagic-toast]")
+    if (!toast) return
+
+    requestAnimationFrame(() => {
+      if (!toast.matches(":hover, :focus-within")) resume(toast)
+    })
+  }
+}
+
+function schedule(toast, duration) {
+  if (timers.has(toast)) return
+
+  const entry = { remaining: duration, started: 0, timer: null }
+  timers.set(toast, entry)
+  start(toast, entry)
+}
+
+function start(toast, entry) {
+  entry.started = Date.now()
+  entry.timer = setTimeout(() => remove(toast), entry.remaining)
+}
+
+function pause(toast) {
+  const entry = timers.get(toast)
+  if (!entry || entry.timer === null) return
+
+  clearTimeout(entry.timer)
+  entry.timer = null
+  entry.remaining -= Date.now() - entry.started
+}
+
+// Give the reader a moment after letting go, even if the time was nearly up.
+function resume(toast) {
+  const entry = timers.get(toast)
+  if (!entry || entry.timer !== null) return
+
+  entry.remaining = Math.max(entry.remaining, MINIMUM_AFTER_HOLD)
+  start(toast, entry)
+}
+
+function remove(toast) {
+  if (!toast || toast.hasAttribute("data-leaving")) return
+
+  const entry = timers.get(toast)
+  if (entry?.timer) clearTimeout(entry.timer)
+  timers.delete(toast)
+
+  toast.setAttribute("data-leaving", "")
+  toast.removeAttribute("data-open")
+
+  const stack = toast.parentElement
+  const leave = matchMedia("(prefers-reduced-motion: reduce)").matches ? 0 : LEAVE
+
+  setTimeout(() => {
+    toast.remove()
+    if (stack?.hidePopover && stack.matches(":popover-open") && !stack.querySelector("[data-unmagic-toast]")) {
+      stack.hidePopover()
+    }
+  }, leave)
+}
+
+customElements.get("unmagic-toasts") || customElements.define("unmagic-toasts", UnmagicToasts)

data/app/assets/javascripts/unmagic/components/tooltip.js

@@ -0,0 +1,133 @@
+// <unmagic-tooltip text="…"> — a hint shown on hover or focus, rendered by
+// `tooltip`.
+//
+// The hint is a manual popover, so it renders in the top layer and no ancestor's
+// overflow can clip it. It is placed with fixed, viewport coordinates each time it
+// opens: on the preferred side (placement="top" or "bottom"), flipped when there
+// isn't room, and clamped so it never runs off the sides.
+//
+// If the content has its own focusable element (a button, a link) the hint
+// describes that element; otherwise the element itself becomes focusable, so a
+// keyboard user can reach the explanation. Escape dismisses it.
+
+const GAP = 8
+const MARGIN = 8
+const DELAY = 150
+const FOCUSABLE = "a[href], button, input, select, textarea, [tabindex]:not([tabindex='-1'])"
+
+let sequence = 0
+
+class UnmagicTooltip extends HTMLElement {
+  static observedAttributes = ["text"]
+
+  #popup = null
+  #pending = null
+  #open = false
+
+  constructor() {
+    super()
+    // On the element itself, once, so moving it (a Turbo cache restore, a permanent
+    // element) never doubles them up.
+    this.addEventListener("pointerenter", () => this.#schedule())
+    this.addEventListener("pointerleave", () => this.#hide())
+    this.addEventListener("focusin", () => this.#schedule(0))
+    this.addEventListener("focusout", () => this.#hide())
+  }
+
+  connectedCallback() {
+    if (this.#popup) return
+
+    // A snapshot Turbo restores is a clone that already holds a popup, but not
+    // this instance's wiring. Start again from the content.
+    this.querySelectorAll(":scope > .UnmagicTooltip__popup").forEach((popup) => popup.remove())
+
+    this.#popup = document.createElement("span")
+    this.#popup.className = "UnmagicTooltip__popup"
+    this.#popup.id = `unmagic_tooltip_${++sequence}`
+    this.#popup.setAttribute("role", "tooltip")
+    this.#popup.setAttribute("popover", "manual")
+    this.#popup.textContent = this.getAttribute("text") ?? ""
+    this.append(this.#popup)
+
+    const trigger = this.querySelector(FOCUSABLE)
+    if (trigger) {
+      trigger.setAttribute("aria-describedby", this.#popup.id)
+    } else {
+      this.tabIndex = 0
+      this.setAttribute("aria-describedby", this.#popup.id)
+    }
+  }
+
+  disconnectedCallback() {
+    this.#hide()
+  }
+
+  attributeChangedCallback(_name, _old, text) {
+    if (this.#popup) this.#popup.textContent = text ?? ""
+  }
+
+  #schedule(delay = DELAY) {
+    clearTimeout(this.#pending)
+    this.#pending = setTimeout(() => this.#show(), delay)
+  }
+
+  #show() {
+    const popup = this.#popup
+    if (this.#open || !popup?.showPopover || !popup.textContent) return
+
+    this.#open = true
+    popup.showPopover()
+    this.#position()
+    popup.setAttribute("data-open", "")
+
+    window.addEventListener("scroll", this.#reposition, { passive: true, capture: true })
+    window.addEventListener("resize", this.#reposition, { passive: true })
+    document.addEventListener("keydown", this.#escape)
+  }
+
+  #hide() {
+    clearTimeout(this.#pending)
+    if (!this.#open) return
+
+    this.#open = false
+    this.#popup.removeAttribute("data-open")
+    this.#popup.hidePopover()
+
+    window.removeEventListener("scroll", this.#reposition, { capture: true })
+    window.removeEventListener("resize", this.#reposition)
+    document.removeEventListener("keydown", this.#escape)
+  }
+
+  #escape = (event) => {
+    if (event.key === "Escape") this.#hide()
+  }
+
+  #reposition = () => {
+    if (this.#open) this.#position()
+  }
+
+  #position() {
+    const anchor = this.getBoundingClientRect()
+    const popup = this.#popup.getBoundingClientRect()
+    const viewportWidth = document.documentElement.clientWidth
+    const viewportHeight = document.documentElement.clientHeight
+
+    const above = anchor.top - popup.height - GAP
+    const below = anchor.bottom + GAP
+    const fitsAbove = above >= MARGIN
+    const fitsBelow = below + popup.height <= viewportHeight - MARGIN
+
+    const top = this.getAttribute("placement") === "bottom"
+      ? (fitsBelow || !fitsAbove ? below : above)
+      : (fitsAbove || !fitsBelow ? above : below)
+
+    const centred = anchor.left + anchor.width / 2 - popup.width / 2
+    const left = Math.max(MARGIN, Math.min(centred, viewportWidth - popup.width - MARGIN))
+
+    this.#popup.style.top = `${top}px`
+    this.#popup.style.left = `${left}px`
+    this.#popup.dataset.side = top === above ? "top" : "bottom"
+  }
+}
+
+customElements.get("unmagic-tooltip") || customElements.define("unmagic-tooltip", UnmagicTooltip)

data/app/assets/javascripts/unmagic/components/uuid_input.js

@@ -0,0 +1,70 @@
+// <unmagic-uuid-input name="message[id]"> — a hidden field holding a fresh UUIDv7,
+// rendered by `uuid_field`.
+//
+// A form can then submit an id the client already knows, for instance to match an
+// optimistically rendered element to the record the server goes on to create
+// under the same id.
+//
+// A new id is minted when the element upgrades, replacing the server's fallback.
+// That also covers a page Turbo restores from its cache, whose id may already have
+// been used. Another is minted every time the form is reset, so a form that clears
+// itself after each submit sends a new one next time.
+
+class UnmagicUuidInput extends HTMLElement {
+  #form = null
+
+  connectedCallback() {
+    this.#input.value = uuidv7()
+    this.#form = this.closest("form")
+    this.#form?.addEventListener("reset", this.#reset)
+  }
+
+  disconnectedCallback() {
+    this.#form?.removeEventListener("reset", this.#reset)
+    this.#form = null
+  }
+
+  get value() {
+    return this.#input.value
+  }
+
+  // The server renders the input; one written by hand might not have.
+  get #input() {
+    let input = this.querySelector(":scope > input[type=hidden]")
+    if (!input) {
+      input = document.createElement("input")
+      input.type = "hidden"
+      input.name = this.getAttribute("name") || "id"
+      this.append(input)
+    }
+    return input
+  }
+
+  // reset fires before the form resets its fields; mint on the microtask after,
+  // once the reset can no longer touch the value.
+  #reset = () => {
+    queueMicrotask(() => {
+      this.#input.value = uuidv7()
+    })
+  }
+}
+
+// A time-ordered UUIDv7: a 48-bit millisecond timestamp, then random bits. It sorts
+// alongside the server's SecureRandom.uuid_v7 and can be used as a record's id.
+export function uuidv7() {
+  const bytes = new Uint8Array(16)
+  crypto.getRandomValues(bytes)
+
+  let time = Date.now()
+  for (let i = 5; i >= 0; i--) {
+    bytes[i] = time % 256
+    time = Math.floor(time / 256)
+  }
+  bytes[6] = 0x70 | (bytes[6] & 0x0f) // version 7
+  bytes[8] = 0x80 | (bytes[8] & 0x3f) // variant 10
+
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+customElements.get("unmagic-uuid-input") || customElements.define("unmagic-uuid-input", UnmagicUuidInput)

data/app/assets/javascripts/unmagic/components.js

@@ -0,0 +1,19 @@
+// Every component's behaviour in one import:
+//
+//   import "unmagic/components"
+//
+// This also installs the confirm dialog in place of window.confirm, and it needs
+// Turbo. An app that wants only some components, or has no Turbo, imports those
+// modules by name instead (import "unmagic/components/tooltip").
+import "unmagic/components/upsert"
+import "unmagic/components/dialog"
+import "unmagic/components/modal"
+import "unmagic/components/confirm"
+import "unmagic/components/toasts"
+import "unmagic/components/time"
+import "unmagic/components/tooltip"
+import "unmagic/components/menu"
+import "unmagic/components/tabs"
+import "unmagic/components/clipboard"
+import "unmagic/components/autogrow"
+import "unmagic/components/uuid_input"