unmagic-components 0.3.0 → 0.4.0

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

@@ -0,0 +1,269 @@
+// <unmagic-streaming-markdown id="…_content"> — server-rendered HTML revealed at a
+// steady pace as fuller renders arrive, rendered by `streaming_markdown_tag` and
+// `ai_chat_message`.
+//
+// The server renders a reply to HTML and sends the whole render on every flush,
+// through the `stream_markdown` Turbo Stream action registered below. Flushes
+// arrive in bursts, which paints chunkily; this element decouples reveal cadence
+// from arrival. It holds the newest render as a target and eases a character
+// cursor toward it every animation frame. Parsing stays on the server: this only
+// reveals a growing prefix of the HTML.
+//
+// It reveals at a constant velocity — the model's own average production rate —
+// and lets the buffer (how far the cursor trails the live edge) absorb the bursts.
+// A proportional "close a fraction of the gap" scheme would speed up and slow down
+// on every burst. The rate is an average over RATE_SMOOTHING; a soft pull toward a
+// small buffer (BUFFER_SECONDS) stops the trailing distance drifting; a lag cap
+// catches up on a big jump (a reconnect) and a trickle floor finishes the tail.
+//
+// The visible prefix is reconciled block by block: settled leading blocks
+// (identical by tag and text) are left alone, and everything from the first
+// changed block is rebuilt, which keeps lists and tables structurally intact.
+//
+// When the settled turn replaces the streaming one mid-reveal, the replacement
+// picks up where the old element left off (HANDOFF) and paces to the end, but only
+// if its content extends what was on screen; a divergent settle (a "stopped" note)
+// shows at once.
+//
+//   final       settled: show the content as it is and refuse any later flush.
+//               This is what lets a Stop button's optimistic swap stick before
+//               the server has settled the turn.
+//   aria-busy   rendered while a reply is live; removed once the reveal has
+//               caught up and gone quiet, so a live region announces the reply
+//               once rather than on every flush.
+//
+// It fires unmagic-streaming-markdown:settle when it catches up. Under reduced
+// motion every flush paints in full. Needs Turbo.
+import { Turbo } from "@hotwired/turbo-rails"
+
+const RATE_SMOOTHING = 0.6 // seconds: the window for the production-rate average, which is the reveal speed
+const BUFFER_SECONDS = 0.3 // seconds of text the cursor aims to keep between itself and the live edge
+const SOFTNESS = 0.4 // per second: how firmly that buffer is held; smaller is steadier and drifts more
+const MAX_LAG_SECONDS = 1.5 // always drain the whole backlog within this long
+const MIN_TRICKLE = 24 // characters a second, so the tail still finishes
+const IDLE_MS = 700 // keep the loop alive this long after the last flush
+const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)")
+
+// Reveal progress carried across an element swap, keyed by element id.
+const HANDOFF = new Map()
+
+class UnmagicStreamingMarkdown extends HTMLElement {
+  #target = null // DocumentFragment: the newest full render
+  #targetLength = 0 // its revealable length (the sum of top-level block text)
+  #revealed = 0 // characters on screen, fractional between frames
+  #rate = 0 // estimated production rate in characters a second
+  #lastArrival = 0
+  #lastFrame = 0
+  #frame = null
+  #frozen = false
+
+  connectedCallback() {
+    if (this.hasAttribute("final")) {
+      HANDOFF.delete(this.id)
+      this.#frozen = true
+      this.#revealed = blockLength(this)
+      return
+    }
+
+    const handoff = HANDOFF.get(this.id)
+    HANDOFF.delete(this.id)
+    const full = blockLength(this)
+    const continues =
+      handoff && handoff.revealed > 0 && handoff.revealed < full && this.textContent.startsWith(handoff.text)
+
+    if (continues && !reducedMotion.matches) {
+      this.#target = adoptChildren(this)
+      this.#targetLength = full
+      this.#revealed = handoff.revealed
+      this.#rate = handoff.rate
+      this.#lastArrival = performance.now()
+      this.#paint()
+      this.#schedule()
+    } else {
+      this.#revealed = full
+      this.#targetLength = full
+    }
+  }
+
+  disconnectedCallback() {
+    if (this.#frame) cancelAnimationFrame(this.#frame)
+    this.#frame = null
+
+    if (this.#revealed < this.#targetLength) {
+      HANDOFF.set(this.id, { revealed: this.#revealed, rate: this.#rate, text: this.textContent })
+    } else {
+      HANDOFF.delete(this.id)
+    }
+  }
+
+  // Called by the stream_markdown action with a fragment of the whole render so far.
+  streamUpdate(fragment) {
+    if (this.#frozen) return
+
+    const now = performance.now()
+    const length = blockLength(fragment)
+    const grew = Math.max(0, length - this.#targetLength)
+    this.#target = fragment
+    this.#targetLength = length
+    if (this.#revealed > length) this.#revealed = length
+
+    this.#observeRate(now, grew)
+    this.#lastArrival = now
+    this.setAttribute("aria-busy", "true")
+
+    if (reducedMotion.matches) {
+      this.#revealed = length
+      this.#paint()
+      this.#settle()
+    } else {
+      this.#paint()
+      this.#schedule()
+    }
+  }
+
+  // Lock onto the first reading, so the opening characters don't crawl while the
+  // average warms up.
+  #observeRate(now, grew) {
+    if (!this.#lastArrival) return
+
+    const dt = (now - this.#lastArrival) / 1000
+    if (dt <= 0) return
+
+    const instant = grew / dt
+    if (this.#rate === 0) this.#rate = instant
+    else this.#rate += (1 - Math.exp(-dt / RATE_SMOOTHING)) * (instant - this.#rate)
+  }
+
+  #schedule() {
+    if (this.#frame) return
+    this.#lastFrame = performance.now()
+    this.#frame = requestAnimationFrame((now) => this.#tick(now))
+  }
+
+  #tick(now) {
+    this.#frame = null
+    const dt = Math.min(0.05, (now - this.#lastFrame) / 1000) // a backgrounded tab resumes gently
+    this.#lastFrame = now
+
+    const backlog = this.#targetLength - this.#revealed
+    if (backlog > 0) {
+      let velocity = this.#rate + (backlog - this.#rate * BUFFER_SECONDS) * SOFTNESS
+      velocity = Math.max(velocity, backlog / MAX_LAG_SECONDS)
+      velocity = Math.min(2000, Math.max(MIN_TRICKLE, velocity))
+      this.#revealed = Math.min(this.#targetLength, this.#revealed + velocity * dt)
+      if (this.#targetLength - this.#revealed < 0.5) this.#revealed = this.#targetLength
+      this.#paint()
+    }
+
+    const streaming = now - this.#lastArrival < IDLE_MS
+    if (this.#revealed < this.#targetLength || streaming) this.#schedule()
+    else this.#settle()
+  }
+
+  #settle() {
+    if (!this.hasAttribute("aria-busy")) return
+    this.removeAttribute("aria-busy")
+    this.dispatchEvent(new CustomEvent("unmagic-streaming-markdown:settle", { bubbles: true }))
+  }
+
+  #paint() {
+    const visible = truncatedClone(this.#target, Math.floor(this.#revealed))
+    try {
+      this.#reconcile(visible)
+    } catch {
+      this.replaceChildren(visible)
+    }
+  }
+
+  #reconcile(fragment) {
+    const incoming = Array.from(fragment.children)
+    if (incoming.length === 0) return this.replaceChildren(fragment)
+
+    const current = Array.from(this.children)
+    let i = 0
+    while (
+      i < current.length &&
+      i < incoming.length &&
+      current[i].nodeName === incoming[i].nodeName &&
+      current[i].textContent === incoming[i].textContent
+    )
+      i++
+
+    if (i === 0) {
+      this.replaceChildren()
+    } else {
+      const anchor = current[i - 1]
+      while (anchor.nextSibling) anchor.nextSibling.remove()
+    }
+    for (let k = i; k < incoming.length; k++) this.append(incoming[k])
+  }
+}
+
+customElements.get("unmagic-streaming-markdown") ||
+  customElements.define("unmagic-streaming-markdown", UnmagicStreamingMarkdown)
+
+// Move an element's children into a fragment, leaving it empty to reveal into.
+function adoptChildren(root) {
+  const fragment = document.createDocumentFragment()
+  while (root.firstChild) fragment.append(root.firstChild)
+  return fragment
+}
+
+// A clone of the target's top-level blocks, cut to `limit` characters of block
+// text; the last block is split where the cursor lands inside it.
+function truncatedClone(target, limit) {
+  const fragment = document.createDocumentFragment()
+  if (!target) return fragment
+
+  let count = 0
+  for (const child of target.children) {
+    if (count >= limit) break
+    const length = child.textContent.length
+    const clone = child.cloneNode(true)
+    if (count + length <= limit) {
+      fragment.append(clone)
+      count += length
+    } else {
+      truncateTo(clone, limit - count)
+      fragment.append(clone)
+      break
+    }
+  }
+  return fragment
+}
+
+// The text length of an element's top-level blocks. Whitespace between blocks
+// doesn't count.
+function blockLength(root) {
+  let length = 0
+  for (const child of root.children) length += child.textContent.length
+  return length
+}
+
+function truncateTo(root, limit) {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT)
+  let count = 0
+  let lastKept = null
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const length = node.data.length
+    if (count + length <= limit) {
+      count += length
+      lastKept = node
+      if (count === limit) break
+    } else {
+      node.data = node.data.slice(0, limit - count)
+      lastKept = node
+      break
+    }
+  }
+  if (!lastKept) return root.replaceChildren()
+  for (let node = lastKept; node && node !== root; node = node.parentNode) {
+    while (node.nextSibling) node.nextSibling.remove()
+  }
+}
+
+// `update`, for streamed Markdown: hand the whole render to the element, which
+// paces its way to it.
+Turbo.StreamActions.stream_markdown = function () {
+  for (const element of this.targetElements) element.streamUpdate?.(this.templateContent)
+}

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

@@ -3,8 +3,8 @@
 // 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.
+// and dismisses it after the element's `duration` (milliseconds), or keeps it up
+// until it is dismissed when that is 0. 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
@@ -54,9 +54,16 @@ class UnmagicToasts extends HTMLElement {
     return this.querySelector(":scope > .UnmagicToasts__stack")
   }
 
+  // `duration="0"` keeps a toast up until it is dismissed. Absent, empty, negative or unparseable
+  // all fall back to the default rather than silently pinning every toast to the screen — which is
+  // why this isn't `Number(attr) || DURATION`: Number(null) and Number("") are both 0, so a missing
+  // attribute would have read as "never" too.
   get duration() {
-    const duration = Number(this.getAttribute("duration"))
-    return duration > 0 ? duration : DURATION
+    const raw = this.getAttribute("duration")?.trim()
+    if (!raw) return DURATION
+
+    const duration = Number(raw)
+    return Number.isFinite(duration) && duration >= 0 ? duration : DURATION
   }
 
   #consume() {
@@ -118,6 +125,9 @@ class UnmagicToasts extends HTMLElement {
 
 function schedule(toast, duration) {
   if (timers.has(toast)) return
+  // A duration of 0 is a toast that waits to be dismissed: no timer, and so nothing for hold and
+  // release to pause — both look the toast up in `timers` and leave when it isn't there.
+  if (duration === 0) return
 
   const entry = { remaining: duration, started: 0, timer: null }
   timers.set(toast, entry)

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

@@ -0,0 +1,76 @@
+// <unmagic-toolbar role="toolbar"> — a row of controls with one Tab stop,
+// rendered by `ai_chat_action_bar`.
+//
+// The WAI-ARIA toolbar pattern: Tab enters and leaves the row as one stop, and
+// Left, Right, Home and End move between its controls (a roving tabindex). The
+// control that last had focus is the one Tab returns to. Controls are its
+// buttons, links and anything already carrying a tabindex, skipping disabled and
+// hidden ones. It rescans when its contents change, so a streamed or
+// re-rendered bar needs no setup.
+
+class UnmagicToolbar extends HTMLElement {
+  #observer = new MutationObserver(() => this.#reset())
+
+  constructor() {
+    super()
+    this.addEventListener("keydown", this.#keydown)
+    this.addEventListener("focusin", (event) => {
+      if (this.#controls.includes(event.target)) this.#activate(event.target)
+    })
+  }
+
+  connectedCallback() {
+    this.#reset()
+    this.#observer.observe(this, { childList: true, subtree: true })
+  }
+
+  disconnectedCallback() {
+    this.#observer.disconnect()
+  }
+
+  get #controls() {
+    return Array.from(this.querySelectorAll("button, a[href], [tabindex]")).filter(
+      (control) => !control.disabled && control.getAttribute("aria-disabled") !== "true" && !control.closest("[hidden]"),
+    )
+  }
+
+  #reset() {
+    const controls = this.#controls
+    const current = controls.find((control) => control.getAttribute("tabindex") === "0") ?? controls[0]
+    if (current) this.#activate(current, controls)
+  }
+
+  #activate(target, controls = this.#controls) {
+    for (const control of controls) control.setAttribute("tabindex", control === target ? "0" : "-1")
+  }
+
+  #keydown = (event) => {
+    const controls = this.#controls
+    const index = controls.indexOf(document.activeElement)
+    if (index === -1) return
+
+    let next
+    switch (event.key) {
+      case "ArrowRight":
+        next = controls[(index + 1) % controls.length]
+        break
+      case "ArrowLeft":
+        next = controls[(index - 1 + controls.length) % controls.length]
+        break
+      case "Home":
+        next = controls[0]
+        break
+      case "End":
+        next = controls[controls.length - 1]
+        break
+      default:
+        return
+    }
+
+    event.preventDefault()
+    this.#activate(next, controls)
+    next.focus()
+  }
+}
+
+customElements.get("unmagic-toolbar") || customElements.define("unmagic-toolbar", UnmagicToolbar)

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

@@ -9,7 +9,8 @@
 // server is now confirming — it is replaced in place, so a record that is both on the page and
 // broadcast never duplicates. Otherwise it is inserted into the target container at the position
 // its id sorts to, so out-of-order delivery still lands in id order. That ordering assumes
-// time-ordered ids (UUIDv7, ULID); with random ids the position is stable but arbitrary.
+// time-ordered ids (UUIDv7, ULID); with random ids the position is stable but arbitrary. The rule
+// itself lives in placement.js, shared with <unmagic-optimistic>.
 //
 // A list showing newest first says so, and the comparison flips:
 //
@@ -18,28 +19,11 @@
 //   broadcast_action_to "tasks", action: :upsert, target: "task_rows",
 //     attributes: { order: "desc" }, partial: "tasks/row", locals: { task: self }
 import { Turbo } from "@hotwired/turbo-rails"
+import { place } from "unmagic/components/placement"
 
 Turbo.StreamActions.upsert = function () {
   const incoming = this.templateContent.firstElementChild
   if (!incoming) return
 
-  const existing = incoming.id ? document.getElementById(incoming.id) : null
-  if (existing) {
-    existing.replaceWith(incoming)
-    return
-  }
-
-  const container = this.targetElements[0]
-  if (!container) return
-
-  const descending = this.getAttribute("order") === "desc"
-
-  // Without an id there is nothing to sort on, so it goes last.
-  const successor = incoming.id
-    ? Array.from(container.children).find(
-        (child) => child.id && (descending ? child.id < incoming.id : child.id > incoming.id),
-      )
-    : null
-
-  container.insertBefore(incoming, successor ?? null)
+  place(incoming, this.targetElements[0], { descending: this.getAttribute("order") === "desc" })
 }

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

@@ -17,3 +17,13 @@ import "unmagic/components/tabs"
 import "unmagic/components/clipboard"
 import "unmagic/components/autogrow"
 import "unmagic/components/uuid_input"
+import "unmagic/components/elapsed"
+import "unmagic/components/autoscroll"
+import "unmagic/components/optimistic"
+import "unmagic/components/streaming_markdown"
+import "unmagic/components/toolbar"
+import "unmagic/components/slash_menu"
+import "unmagic/components/dropzone"
+import "unmagic/components/ai_chat"
+import "unmagic/components/sortable"
+import "unmagic/components/board"