poetry-core 0.0.2

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

@@ -0,0 +1,151 @@
+import { Controller } from "@hotwired/stimulus"
+import { setState } from "@poetry/controllers/helpers/state"
+
+// The Tabs activation machine: this controller owns ONLY the
+// active-value state + attribute writes; the shared poetry--core--roving-focus
+// on the tablist owns the keyboard (default tabindex-managing mode - one Tab
+// stop). Triggers are DUMB buttons (click -> tabs#activate; with automatic
+// activation - the APG default for tabs - focusin activates too, so arrow
+// keys both move focus AND switch panels).
+//
+// The state vocabulary: the active trigger carries data-active
+// (the styled token) + aria-selected; inactive panels carry the hidden
+// property + data-hidden. data-activation-direction is deliberately NOT
+// emitted - no shipped class consumes it (add it with the animated
+// indicator, when something does).
+//
+// Panels are scoped to THIS root (a nested Tabs inside a panel owns its own
+// triggers/panels - the DOM is the registry, same rule as roving-focus).
+const TRIGGER_SELECTOR = '[data-slot="tabs-trigger"]'
+const PANEL_SELECTOR = '[data-slot="tabs-content"]'
+
+// The component-facing event namespace (the poetry:<component> rule).
+const EVENT_PREFIX = "poetry:tabs"
+
+export default class TabsController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:tabs:change"]
+
+  static values = {
+    // false = manual activation (arrows only move focus; Enter/Space - the
+    // native button click - activates). true is the APG-recommended default.
+    activateOnFocus: { type: Boolean, default: true }
+  }
+
+  /**
+   * Reconcile-on-connect: derives the full vocabulary from the
+   * server-rendered data-active truth (the body comment holds the rules).
+   */
+  connect() {
+    // Reconcile-on-connect: the server-rendered data-active trigger is the
+    // truth; aria-selected/tabindex/hidden are (re)derived from it, so a
+    // Turbo re-render can never leave mixed vocabularies. No data-active
+    // anywhere -> the first enabled trigger becomes active.
+    const active = this.#triggers().find((trigger) => trigger.hasAttribute("data-active"))
+    const fallback = this.#triggers().find((trigger) => !this.#disabled(trigger))
+    const value = (active ?? fallback)?.dataset.value
+
+    if (value !== undefined) this.#apply(value, { silent: true })
+  }
+
+  /**
+   * Each trigger's click action: activates the pressed trigger's value.
+   *
+   * @param {MouseEvent} event
+   */
+  activate(event) {
+    const trigger = this.#triggerFrom(event)
+
+    if (!trigger || this.#disabled(trigger)) return
+
+    this.#apply(trigger.dataset.value)
+  }
+
+  /**
+   * The tablist's roving-focus entry action - automatic activation
+   * follows the roving focus via the roving controller's entry event
+   * (deterministic: never depends on the platform firing focusin for a
+   * programmatic .focus()). A raw focusin routes here too, so hand-wired
+   * hosts get the same behavior.
+   *
+   * @param {CustomEvent | FocusEvent} event
+   */
+  focusActivate(event) {
+    if (!this.activateOnFocusValue) return
+
+    const trigger = (event.detail && event.detail.item) || this.#triggerFrom(event)
+
+    if (!trigger || this.#disabled(trigger)) return
+    if (trigger.hasAttribute("data-active")) return // already there - no re-fire
+
+    this.#apply(trigger.dataset.value)
+  }
+
+  /**
+   * The programmatic controllable-state surface: setValue("account").
+   * Unknown values are ignored (the contract's guard). Returns the
+   * resulting state - what an agent tool reports back - so a no-op is
+   * visible as changed: false.
+   *
+   * @param {string} value - a trigger's data-value (stringified)
+   * @returns {{ value: string, changed: boolean }} the active value after the call
+   */
+  setValue(value) {
+    const next = String(value)
+    const known = this.#triggers().some((trigger) => trigger.dataset.value === next)
+    const before = this.#activeValue()
+
+    if (known) this.#apply(next)
+
+    return { value: known ? next : before, changed: known && next !== before }
+  }
+
+  #activeValue() {
+    return this.#triggers().find((trigger) => trigger.getAttribute("aria-selected") === "true")?.dataset.value ?? ""
+  }
+
+  #apply(value, { silent = false } = {}) {
+    for (const trigger of this.#triggers()) {
+      const active = trigger.dataset.value === value
+
+      setState(trigger, active ? "active" : "inactive")
+      trigger.setAttribute("aria-selected", active ? "true" : "false")
+      // The active tab is the roving tab stop (re-entering the tablist
+      // lands on the selection) - the stamp roving-focus adopts.
+      trigger.setAttribute("tabindex", active ? "0" : "-1")
+    }
+
+    for (const panel of this.#panels()) {
+      const active = panel.dataset.value === value
+
+      panel.hidden = !active
+      if (active) panel.removeAttribute("data-hidden")
+      else panel.setAttribute("data-hidden", "")
+    }
+
+    if (!silent) this.dispatch("change", { prefix: EVENT_PREFIX, detail: { value } })
+  }
+
+  #triggerFrom(event) {
+    const origin = event.target instanceof Element ? event.target : null
+
+    return origin?.closest(TRIGGER_SELECTOR) ?? null
+  }
+
+  #disabled(trigger) {
+    return trigger.hasAttribute("disabled") || trigger.hasAttribute("data-disabled")
+  }
+
+  #triggers() {
+    return [...this.element.querySelectorAll(TRIGGER_SELECTOR)].filter((el) => this.#owns(el))
+  }
+
+  #panels() {
+    return [...this.element.querySelectorAll(PANEL_SELECTOR)].filter((el) => this.#owns(el))
+  }
+
+  #owns(el) {
+    return el.closest(`[data-controller~="${this.identifier}"]`) === this.element
+  }
+}

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

@@ -0,0 +1,134 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The TagGroup removal engine (the tag-group contract):
+// navigation itself rides the roving-focus controller (the toolbar
+// precedent) - this controller owns what tags add on top:
+//
+// - Delete/Backspace on a focused tag removes it (row-origin keys only;
+//   keys from a tag's inner remove button must not drive the grid).
+// - The remove button removes exactly its own tag.
+// - Focus recovery after removal is the reference walk: FORWARD through
+//   the pre-removal order to the first surviving enabled tag, then
+//   backward; when the last tag goes, the CONTAINER takes focus, flips
+//   role grid->group, and becomes the tab stop.
+// - The container is a live region ONLY while focus is within (polite,
+//   additions) - SRs hear tags added while working in the group without
+//   spam from elsewhere.
+//
+// Removal is CANCELABLE (poetry:tag-group:remove): a Turbo-driven host
+// preventDefault()s and re-renders; otherwise this controller removes the
+// row (and the hidden input riding it - form mode serializes name[] per
+// tag).
+const EVENT_PREFIX = "poetry:tag-group"
+
+export default class TagGroupController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:tag-group:remove"]
+
+  #onFocusin = () => this.element.setAttribute("aria-live", "polite")
+  #onFocusout = (event) => {
+    if (this.element.contains(event.relatedTarget)) return
+
+    this.element.setAttribute("aria-live", "off")
+  }
+
+  /**
+   * Wires the focus-scoped live-region toggling and reflects emptiness
+   * (role, tab stop, data-empty).
+   */
+  connect() {
+    this.element.addEventListener("focusin", this.#onFocusin)
+    this.element.addEventListener("focusout", this.#onFocusout)
+    this.#reflectEmpty()
+  }
+
+  /** Unwires the focus listeners. */
+  disconnect() {
+    this.element.removeEventListener("focusin", this.#onFocusin)
+    this.element.removeEventListener("focusout", this.#onFocusout)
+  }
+
+  /**
+   * The container's keydown action: Delete/Backspace on a focused tag ROW
+   * removes it - row-origin keys only (keys from a tag's inner remove
+   * button must not drive the grid).
+   *
+   * @param {KeyboardEvent} event
+   */
+  keydown(event) {
+    if (event.key !== "Delete" && event.key !== "Backspace") return
+
+    const row = event.target.closest("[data-slot='tag-group-tag']")
+
+    // Row-origin only: the remove button's own keys stay its own.
+    if (!row || event.target !== row) return
+    if (row.hasAttribute("data-disabled")) return
+
+    event.preventDefault()
+    this.#remove(row)
+  }
+
+  /**
+   * The remove button's click action: removes exactly its own tag.
+   *
+   * @param {MouseEvent} event
+   */
+  remove(event) {
+    event.preventDefault()
+    const row = event.target.closest("[data-slot='tag-group-tag']")
+
+    if (!row || row.hasAttribute("data-disabled")) return
+
+    this.#remove(row)
+  }
+
+  #remove(row) {
+    const removal = this.dispatch("remove", {
+      prefix: EVENT_PREFIX,
+      detail: { value: row.getAttribute("data-value"), id: row.id },
+      cancelable: true
+    })
+
+    if (removal.defaultPrevented) return // the host re-renders instead
+
+    const target = this.#recoveryTarget(row)
+
+    row.remove()
+    this.#reflectEmpty()
+
+    if (target) {
+      target.setAttribute("tabindex", "0")
+      target.focus()
+    } else if (this.element.contains(document.activeElement) ||
+               document.activeElement === document.body) {
+      this.element.focus()
+    }
+  }
+
+  // The reference walk, in pre-removal DOM order: forward to the first
+  // surviving enabled tag, then backward.
+  #recoveryTarget(row) {
+    const rows = this.#rows()
+    const index = rows.indexOf(row)
+    const enabled = (candidate) => candidate !== row && !candidate.hasAttribute("data-disabled")
+
+    return rows.slice(index + 1).find(enabled) ??
+      rows.slice(0, index).reverse().find(enabled) ??
+      null
+  }
+
+  #reflectEmpty() {
+    const empty = this.#rows().length === 0
+
+    this.element.toggleAttribute("data-empty", empty)
+    this.element.setAttribute("role", empty ? "group" : "grid")
+
+    if (empty) this.element.setAttribute("tabindex", "0")
+    else this.element.removeAttribute("tabindex")
+  }
+
+  #rows() {
+    return Array.from(this.element.querySelectorAll("[data-slot='tag-group-tag']"))
+  }
+}

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

@@ -0,0 +1,228 @@
+import { Controller } from "@hotwired/stimulus"
+import { announce } from "@poetry/controllers/helpers/announce"
+import { isImeKeydown } from "@poetry/controllers/helpers/escape"
+import { exitPresence } from "@poetry/controllers/helpers/presence"
+import { setState, stateOf } from "@poetry/controllers/helpers/state"
+
+// One toast item (poetry's own Toast - the stacked-toaster genre with
+// strict a11y semantics). The item is role=status aria-live=off: it
+// never announces itself - on connect it speaks ONCE through the
+// announce singleton at its politeness (destructive -> assertive,
+// wired server-side via the
+// politeness value). The auto-dismiss timer follows APG/WCAG 2.2.1 timing:
+// it PAUSES on hover, focus-within, window blur and tab-hidden (reasons are
+// refcounted so overlapping pauses cannot resume early), and duration <= 0
+// means persistent (required for undo/action toasts). Dismiss flips
+// data-open -> data-closed, dispatches poetry:toast:dismiss {id, reason} (the
+// toaster's reflow + focus-return seam), then presence holds the node until
+// its exit animation finishes before removal.
+//
+// Swipe-to-dismiss is a browser-verification-GATED enhancement (contract) -
+// it does not ship in this pass; the swipe reason is reserved.
+const EVENT_PREFIX = "poetry:toast"
+
+const ACTION_SELECTOR = '[data-slot="toast-action"]'
+const TITLE_SELECTOR = '[data-slot="toast-title"]'
+const DESCRIPTION_SELECTOR = '[data-slot="toast-description"]'
+
+// event.type -> pause/resume reason, so each pause source releases only
+// its own hold (hover out must not resume a focus hold).
+const PAUSE_REASONS = {
+  mouseenter: "hover",
+  mouseleave: "hover",
+  focusin: "focus",
+  focusout: "focus"
+}
+
+let toastSequence = 0
+
+export default class ToastController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:toast:dismiss", "poetry:toast:show"]
+
+  static targets = ["action", "close"]
+  static values = {
+    duration: { type: Number, default: 5000 },
+    politeness: { type: String, default: "polite" }
+  }
+
+  #wired = []
+  #timer = null
+  #remaining = 0
+  #startedAt = null
+  #pauseReasons = new Set()
+  #dismissed = false
+  #onVisibilityChange = () => {
+    if (document.hidden) this.pause("visibility")
+    else this.resume("visibility")
+  }
+  #onWindowBlur = () => this.pause("window")
+  #onWindowFocus = () => this.resume("window")
+
+  /**
+   * Assigns an id when missing, adopts the open pair, announces ONCE
+   * through the singleton, wires the pause sources and the toast-local
+   * Escape, and starts the auto-dismiss timer (queued/hidden toasts hold
+   * theirs).
+   */
+  connect() {
+    if (!this.element.id) this.element.id = `poetry-toast-${(toastSequence += 1).toString(16)}`
+    if (!stateOf(this.element)) setState(this.element, "open")
+
+    // Announce ONCE through the singleton (the item is aria-live=off).
+    // Consumers must never announce() toast content themselves.
+    announce(this.#message(), this.politenessValue)
+
+    // APG timing: pause while the tab is hidden or the window is blurred.
+    this.#listen(document, "visibilitychange", this.#onVisibilityChange)
+    this.#listen(window, "blur", this.#onWindowBlur)
+    this.#listen(window, "focus", this.#onWindowFocus)
+    // Esc while focus is inside dismisses this toast (it reports as the
+    // close affordance: close-press).
+    this.#listen(this.element, "keydown", (event) => {
+      if (event.key !== "Escape" || isImeKeydown(event)) return
+
+      event.stopPropagation()
+      this.dismiss("close-press")
+    })
+
+    this.#remaining = this.durationValue
+
+    // A toast queued by the toaster (hidden at connect) holds its timer
+    // until promotion; the toaster resumes it with the "queued" reason.
+    if (this.element.hidden) this.#pauseReasons.add("queued")
+    if (document.hidden) this.#pauseReasons.add("visibility")
+
+    this.#startTimer()
+
+    this.dispatch("show", {
+      prefix: EVENT_PREFIX,
+      detail: { id: this.element.id, variant: this.element.dataset.variant ?? "default" }
+    })
+  }
+
+  /** Stops the timer and unwires every listener. */
+  disconnect() {
+    this.#stopTimer()
+
+    for (const [target, type, listener] of this.#wired) target.removeEventListener(type, listener)
+
+    this.#wired = []
+    this.#pauseReasons.clear()
+  }
+
+  // --- timer pause/resume (markup: mouseenter/focusin -> pause,
+  //     mouseleave/focusout -> resume; the toaster + window paths call with
+  //     string reasons) ---
+
+  /**
+   * Holds the auto-dismiss timer under a reason (hover/focus derive from
+   * events; the toaster and window paths pass strings). Reasons pool in a
+   * set, so overlapping pauses cannot resume early.
+   *
+   * @param {Event | string} [eventOrReason]
+   */
+  pause(eventOrReason) {
+    this.#pauseReasons.add(this.#reasonFor(eventOrReason))
+    this.#stopTimer()
+  }
+
+  /**
+   * Releases one pause reason; the timer restarts when none remain.
+   *
+   * @param {Event | string} [eventOrReason]
+   */
+  resume(eventOrReason) {
+    this.#pauseReasons.delete(this.#reasonFor(eventOrReason))
+    this.#startTimer()
+  }
+
+  // --- dismissal ---
+
+  /**
+   * Dismisses the toast. Reasons: timeout | close-press | action |
+   * swipe(reserved) | manual - the family reason vocabulary plus
+   * poetry's own timeout/action/queued/manual extensions. A click on the
+   * action slot reports "action"; the close
+   * button "close-press". The dismiss event goes out BEFORE removal (the
+   * toaster's reflow + focus-return seam); presence then holds the node
+   * through its exit animation.
+   *
+   * @param {Event | string} [eventOrReason] - the triggering event (the
+   *   reason derives from its origin) or an explicit reason string
+   */
+  dismiss(eventOrReason) {
+    if (this.#dismissed) return
+
+    this.#dismissed = true
+    this.#stopTimer()
+    this.#pauseReasons.clear()
+
+    const reason = typeof eventOrReason === "string"
+      ? eventOrReason
+      : this.#reasonFromEvent(eventOrReason)
+
+    // Dispatched BEFORE removal so it bubbles to the toaster (reflow +
+    // focus return); presence then holds the node through its exit.
+    this.dispatch("dismiss", {
+      prefix: EVENT_PREFIX,
+      detail: { id: this.element.id, reason }
+    })
+
+    exitPresence(this.element, { onRemove: () => this.element.remove() })
+  }
+
+  // --- internals ---
+
+  #startTimer() {
+    if (this.#timer !== null || this.#dismissed) return
+    if (this.#pauseReasons.size > 0) return
+    if (this.durationValue <= 0) return // persistent (undo toasts)
+    if (this.#remaining <= 0) return
+
+    this.#startedAt = Date.now()
+    this.#timer = window.setTimeout(() => {
+      this.#timer = null
+      this.dismiss("timeout")
+    }, this.#remaining)
+  }
+
+  #stopTimer() {
+    if (this.#timer === null) return
+
+    window.clearTimeout(this.#timer)
+    this.#timer = null
+    this.#remaining = Math.max(0, this.#remaining - (Date.now() - this.#startedAt))
+    this.#startedAt = null
+  }
+
+  #reasonFor(eventOrReason) {
+    if (typeof eventOrReason === "string") return eventOrReason
+    if (eventOrReason?.type) return PAUSE_REASONS[eventOrReason.type] ?? eventOrReason.type
+
+    return "manual"
+  }
+
+  #reasonFromEvent(event) {
+    const origin = event?.currentTarget instanceof Element ? event.currentTarget : event?.target
+
+    if (origin instanceof Element && origin.closest(ACTION_SELECTOR)) return "action"
+
+    return "close-press"
+  }
+
+  // Title + description text, the announced payload (textContent only -
+  // the singleton never sees markup).
+  #message() {
+    const title = this.element.querySelector(TITLE_SELECTOR)?.textContent?.trim() ?? ""
+    const description = this.element.querySelector(DESCRIPTION_SELECTOR)?.textContent?.trim() ?? ""
+
+    return [title, description].filter(Boolean).join(" ")
+  }
+
+  #listen(target, type, listener) {
+    target.addEventListener(type, listener)
+    this.#wired.push([target, type, listener])
+  }
+}

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

@@ -0,0 +1,26 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The client-side toast delivery trigger (poetry's no-round-trip path -
+// what a toast() JS factory does elsewhere, done with server-rendered
+// markup): press -> dispatch poetry:toaster:stamp, and the toaster clones
+// the addressed <template>'s toast into its region. The toast inside the
+// template is byte-for-byte what a Turbo Stream would deliver.
+export default class ToastTriggerController extends Controller {
+  static events = ["poetry:toaster:stamp"]
+  static values = {
+    // The <template> element id holding the rendered toast.
+    template: String,
+    // Optional toaster region id - omit for the page's toaster.
+    toaster: String
+  }
+
+  /**
+   * The click action: stamps the addressed template's toast into the
+   * toaster region (the no-round-trip delivery the header describes).
+   */
+  fire() {
+    window.dispatchEvent(new CustomEvent("poetry:toaster:stamp", {
+      detail: { template: this.templateValue, toaster: this.toasterValue || null }
+    }))
+  }
+}