poetry-core 0.0.2

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

@@ -0,0 +1,197 @@
+import { Controller } from "@hotwired/stimulus"
+import { acquire, release } from "@poetry/controllers/helpers/announce"
+import { isEditingTarget, matchesHotkey } from "@poetry/controllers/helpers/hotkey"
+import { stateOf } from "@poetry/controllers/helpers/state"
+
+// The toast viewport (one per page): the labeled role=region <ol> that is
+// the Turbo Stream append target (id=poetry-toaster, data-turbo-permanent).
+// It ACQUIRES the announce singleton for its lifetime (items announce
+// through it on connect), owns the F8 hotkey (focus moves to the most
+// recent toast; the prior focus is remembered so dismissal returns it),
+// enforces the visible LIMIT (default 3 - the oldest overflow toasts queue
+// hidden with their timers held, promoted as newer ones dismiss), and owns
+// the stack reflow (--poetry-toast-index, newest = 0, for the offset/scale
+// stack styling).
+//
+// Items arrive by server render, Turbo Stream append, or a stamp (the
+// poetry:toaster:stamp window event - poetry_toast_trigger's no-round-trip
+// path, cloning a <template> toast into the region);
+// a childList MutationObserver reconciles limit + reflow on every change,
+// so no append path needs to know about the toaster.
+const TOAST_SELECTOR = '[data-slot="toast"]'
+const TOAST_IDENTIFIER = "poetry--core--toast"
+
+const INDEX_PROPERTY = "--poetry-toast-index"
+
+export default class ToasterController extends Controller {
+  static targets = ["item"]
+  static values = {
+    hotkey: { type: String, default: "F8" },
+    limit: { type: Number, default: 3 },
+    position: String
+  }
+
+  #observer = null
+  #returnFocusTo = null
+  #onKeydown = (event) => this.focusRegion(event)
+  #onDismiss = (event) => this.#handleDismiss(event)
+  #onStamp = (event) => this.#stamp(event)
+
+  /**
+   * Acquires the announce singleton, wires the hotkey / stamp / dismiss
+   * listeners, and starts the childList reconciler.
+   */
+  connect() {
+    acquire() // the singleton lives while a toaster is connected
+
+    window.addEventListener("keydown", this.#onKeydown)
+    window.addEventListener("poetry:toaster:stamp", this.#onStamp)
+    this.element.addEventListener("poetry:toast:dismiss", this.#onDismiss)
+
+    this.#observer = new MutationObserver(() => this.#reconcile())
+    this.#observer.observe(this.element, { childList: true })
+
+    this.#reconcile()
+  }
+
+  /** Unwires everything and releases the announce singleton. */
+  disconnect() {
+    this.#observer?.disconnect()
+    this.#observer = null
+    window.removeEventListener("keydown", this.#onKeydown)
+    window.removeEventListener("poetry:toaster:stamp", this.#onStamp)
+    this.element.removeEventListener("poetry:toast:dismiss", this.#onDismiss)
+    this.#returnFocusTo = null
+    release()
+  }
+
+  // The stamp delivery path: clone a <template>'s toast into the region.
+  // detail.toaster (an id) scopes multi-toaster pages - a stamp addressed
+  // elsewhere is ignored; unaddressed stamps land in every toaster that
+  // hears them (one per page canonically). The childList observer then
+  // reconciles limit + reflow like any other append.
+  #stamp(event) {
+    const { template, toaster } = event.detail || {}
+    if (toaster && toaster !== this.element.id) return
+
+    const node = template ? document.getElementById(template) : null
+    if (!(node instanceof HTMLTemplateElement)) {
+      console.warn(`poetry toaster: stamp template ${JSON.stringify(template)} not found or not a <template>`)
+      return
+    }
+
+    this.element.append(node.content.cloneNode(true))
+  }
+
+  /**
+   * The hotkey's landing (F8 default, configurable): moves focus into the
+   * region - onto the most recent visible toast, else the region itself.
+   * The prior focus is remembered for the dismiss return.
+   *
+   * @param {Event} [event] - the window keydown when the hotkey drove it;
+   *   programmatic calls may omit it
+   */
+  focusRegion(event) {
+    if (event instanceof KeyboardEvent) {
+      // The full descriptor grammar + the editing-target rule (the hotkey
+      // controller's idiom): a bare key comparison fires on stray-modifier
+      // chords and while the user types in a field.
+      if (event.defaultPrevented || !matchesHotkey(event, this.hotkeyValue)) return
+      if (isEditingTarget(event) && !(event.metaKey || event.ctrlKey || event.altKey)) return
+
+      event.preventDefault()
+    }
+
+    const active = document.activeElement
+
+    if (active instanceof HTMLElement && !this.element.contains(active)) {
+      this.#returnFocusTo = active
+    }
+
+    const target = this.#visibleToasts().at(-1) ?? this.element
+
+    target.focus()
+  }
+
+  /**
+   * Stack reflow: newest toast = index 0 (the front of the stack),
+   * written as the offset/scale custom property.
+   */
+  reflow() {
+    const visible = this.#visibleToasts()
+
+    visible.forEach((toast, index) => {
+      toast.style.setProperty(INDEX_PROPERTY, String(visible.length - 1 - index))
+    })
+  }
+
+  // --- internals ---
+
+  // Limit + queue + reflow, run on every childList change: the newest
+  // `limit` open toasts are visible; older overflow queues hidden (timer
+  // held via the toast controller's "queued" pause) until slots free up.
+  #reconcile() {
+    const open = this.#openToasts()
+    const overflow = Math.max(0, open.length - this.limitValue)
+
+    open.forEach((toast, index) => {
+      if (index < overflow) this.#queue(toast)
+      else this.#promote(toast)
+    })
+
+    this.reflow()
+    this.#restoreFocusIfLost()
+  }
+
+  #queue(toast) {
+    if (toast.hasAttribute("data-queued")) return
+
+    toast.setAttribute("data-queued", "")
+    toast.hidden = true
+    this.#toastController(toast)?.pause("queued")
+  }
+
+  #promote(toast) {
+    if (!toast.hasAttribute("data-queued")) return
+
+    toast.removeAttribute("data-queued")
+    toast.hidden = false
+    this.#toastController(toast)?.resume("queued")
+  }
+
+  // Dismissal focus return: when the dismissed toast held focus (hotkey
+  // entry), focus goes back to the remembered prior element.
+  #handleDismiss(event) {
+    const toast = event.target instanceof Element ? event.target.closest(TOAST_SELECTOR) : null
+
+    if (toast?.contains(document.activeElement) && this.#returnFocusTo?.isConnected) {
+      this.#returnFocusTo.focus()
+      this.#returnFocusTo = null
+    }
+  }
+
+  // A removed toast that carried focus drops it on <body>; hand it back.
+  #restoreFocusIfLost() {
+    if (document.activeElement !== document.body) return
+    if (!this.#returnFocusTo?.isConnected) return
+
+    this.#returnFocusTo.focus()
+    this.#returnFocusTo = null
+  }
+
+  #toasts() {
+    return Array.from(this.element.querySelectorAll(TOAST_SELECTOR))
+  }
+
+  #openToasts() {
+    return this.#toasts().filter((toast) => stateOf(toast) !== "closed")
+  }
+
+  #visibleToasts() {
+    return this.#openToasts().filter((toast) => !toast.hidden)
+  }
+
+  #toastController(toast) {
+    return this.application.getControllerForElementAndIdentifier(toast, TOAST_IDENTIFIER)
+  }
+}

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

@@ -0,0 +1,206 @@
+import { Controller } from "@hotwired/stimulus"
+import { setState, stateOf } from "@poetry/controllers/helpers/state"
+
+// The ToggleGroup value-set machine (the Accordion composition, second
+// consumer): this controller owns ONLY the pressed-values set + attribute
+// writes; the shared poetry--core--roving-focus on the same root owns the
+// keyboard (default tabindex-managing mode - one Tab stop). Items are DUMB
+// buttons (data-action -> group#toggle; poetry--core--pressed is NOT
+// attached in group context - one owner, no event soup).
+//
+// The role/vocabulary split, enforced here: type=single is
+// RADIO semantics - items carry aria-checked (aria-pressed stripped) and
+// re-pressing the sole pressed item deselects to EMPTY;
+// type=multiple is toolbar semantics - independent aria-pressed items. The
+// controller reads type once and never mixes vocabularies; the bare
+// data-pressed presence boolean styles both types identically (Toggle's
+// classes just work).
+//
+// After every transition the PRESSED item becomes the roving tab stop
+// (re-entering the group lands on the selection) -
+// written directly as the tabindex stamp roving-focus adopts.
+const ITEM_SELECTOR = '[data-slot="toggle-group-item"]'
+
+export default class ToggleGroupController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:toggle-group:change"]
+
+  static values = {
+    type: { type: String, default: "single" }
+  }
+
+  /**
+   * Reconcile-on-connect: re-derives the type-correct aria vocabulary
+   * from the server-rendered data-pressed truth, then prefers the pressed
+   * tab stop.
+   */
+  connect() {
+    // Reconcile-on-connect: server-rendered data-pressed is the truth; the
+    // type-correct aria attribute is (re)derived from it, so a Turbo Stream
+    // re-render (or a hand-patched item) can never mix vocabularies.
+    for (const item of this.#items()) this.#write(item, stateOf(item) === "pressed")
+
+    this.#preferPressedTabStop()
+  }
+
+  // --- item activation (click / Space / Enter via native button click) ---
+
+  /**
+   * Each item's click action (Space/Enter arrive via native button
+   * activation): single mode is radio semantics with deselect-to-empty;
+   * multiple XORs the value in and out.
+   *
+   * @param {MouseEvent} event
+   */
+  toggle(event) {
+    const origin = event.currentTarget instanceof Element ? event.currentTarget : event.target
+    const item = origin instanceof Element ? origin.closest(ITEM_SELECTOR) : null
+
+    if (!item || this.#disabled(item)) return
+
+    const value = item.dataset.value
+
+    if (this.#single()) this.#toggleSingle(value)
+    else this.#toggleMultiple(value)
+  }
+
+  // --- the programmatic controllable-state surface ---
+
+  /**
+   * The programmatic controllable-state surface: setValue("b") in single
+   * mode ("" / null clears); setValue(["a", "b"]) in multiple mode.
+   * Validated against type; unknown values are ignored (logged in dev -
+   * the contract's guard).
+   *
+   * @param {string | string[] | null} value
+   */
+  setValue(value) {
+    const values = this.#known(Array.isArray(value) ? value : (value ? [value] : []))
+
+    if (this.#single()) {
+      if (Array.isArray(value) && value.length > 1) {
+        console.warn("poetry--core--toggle-group: setValue(array) is invalid with type=single")
+        return
+      }
+
+      this.#apply(new Set(values.slice(0, 1)))
+    } else {
+      if (!Array.isArray(value) && value != null && value !== "") {
+        console.warn("poetry--core--toggle-group: setValue expects an array with type=multiple")
+        return
+      }
+
+      this.#apply(new Set(values))
+    }
+  }
+
+  // --- the set machine ---
+
+  // single: S == {v} -> {} (deselect-to-empty, contractual), else -> {v}.
+  #toggleSingle(value) {
+    const pressed = this.#pressedValues()
+
+    this.#apply(new Set(pressed.has(value) ? [] : [value]))
+  }
+
+  // multiple: S -> S XOR {v}.
+  #toggleMultiple(value) {
+    const pressed = this.#pressedValues()
+
+    if (pressed.has(value)) pressed.delete(value)
+    else pressed.add(value)
+
+    this.#apply(pressed)
+  }
+
+  #apply(next) {
+    const pressed = []
+    const unpressed = []
+
+    for (const item of this.#items()) {
+      const on = next.has(item.dataset.value)
+      const was = stateOf(item) === "pressed"
+
+      this.#write(item, on)
+
+      if (on && !was) pressed.push(item.dataset.value)
+      if (!on && was) unpressed.push(item.dataset.value)
+    }
+
+    if (pressed.length === 0 && unpressed.length === 0) return
+
+    this.#preferPressedTabStop()
+
+    const values = [...next]
+
+    this.dispatch("change", {
+      prefix: "poetry:toggle-group",
+      detail: {
+        type: this.typeValue,
+        ...(this.#single() ? { value: values[0] ?? null } : { values }),
+        pressed,
+        unpressed
+      }
+    })
+  }
+
+  // data-pressed and the TYPE-CORRECT aria attribute, written together:
+  // single items are radios (aria-checked only - a stale aria-pressed
+  // would double-voice the state); multiple items are toggle buttons.
+  #write(item, on) {
+    setState(item, on ? "pressed" : "unpressed")
+
+    if (this.#single()) {
+      item.setAttribute("aria-checked", String(on))
+      item.removeAttribute("aria-pressed")
+    } else {
+      item.setAttribute("aria-pressed", String(on))
+      item.removeAttribute("aria-checked")
+    }
+  }
+
+  // The pressed item is the preferred tab stop.
+  // Written as the tabindex stamp the roving-focus controller adopts (its
+  // current-stop scan reads tabindex="0"); only when roving already manages
+  // tabindex here (the stamp exists), so a manage-tabindex:false host is
+  // left untouched.
+  #preferPressedTabStop() {
+    const items = this.#items()
+
+    if (!items.some((item) => item.hasAttribute("tabindex"))) return
+
+    const target = items.find((item) => stateOf(item) === "pressed" && !this.#disabled(item)) ??
+      items.find((item) => !this.#disabled(item))
+
+    if (!target) return
+
+    for (const item of items) item.setAttribute("tabindex", item === target ? "0" : "-1")
+  }
+
+  #pressedValues() {
+    return new Set(this.#items().filter((item) => stateOf(item) === "pressed").map((item) => item.dataset.value))
+  }
+
+  #known(values) {
+    const valid = new Set(this.#items().map((item) => item.dataset.value))
+    const unknown = values.filter((value) => !valid.has(value))
+
+    if (unknown.length > 0) console.debug(`poetry--core--toggle-group: unknown value(s) ${unknown.join(", ")}`)
+
+    return values.filter((value) => valid.has(value))
+  }
+
+  #items() {
+    return Array.from(this.element.querySelectorAll(ITEM_SELECTOR))
+  }
+
+  #single() {
+    return this.typeValue !== "multiple"
+  }
+
+  #disabled(item) {
+    return item.hasAttribute("disabled") || item.hasAttribute("data-disabled") ||
+      this.element.hasAttribute("data-disabled")
+  }
+}