poetry-core 0.0.2

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

@@ -0,0 +1,167 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The Carousel engine, decided NATIVE: no carousel library - the platform's
+// scroll-snap owns the physics (touch, momentum, snapping, overscroll),
+// and this controller adds only what CSS can't: prev/next paging, button
+// state, and arrow keys. Navigation scrolls the VIEWPORT by a bounding-
+// rect delta (RTL- and transform-safe: never scrollLeft sign
+// conventions) - not scrollIntoView, whose alignment bubbles to
+// scrollable ancestors and whose "nearest" no-ops when several slides
+// fit the viewport at once (the vertical stack). Deferred with the
+// library-grade machinery: loop (it clones slides), autoplay, and a plugin API.
+const SLIDE_SELECTOR = '[data-slot="carousel-item"]'
+
+// The component-facing event namespace (the poetry:<component> rule).
+const EVENT_PREFIX = "poetry:carousel"
+
+export default class CarouselController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:carousel:select"]
+
+  static targets = ["viewport", "previous", "next"]
+  static values = {
+    orientation: { type: String, default: "horizontal" }
+  }
+
+  #raf = null
+
+  /** Syncs button state to the initial scroll position. */
+  connect() {
+    this.#sync()
+  }
+
+  /** Cancels any pending sync frame. */
+  disconnect() {
+    if (this.#raf !== null) cancelAnimationFrame(this.#raf)
+  }
+
+  /**
+   * The viewport's scroll action - button state follows the SCROLL
+   * (finger, wheel, keyboard PageDown), not just our own paging.
+   * rAF-coalesced: scroll fires in bursts.
+   */
+  scrolled() {
+    if (this.#raf !== null) return
+
+    this.#raf = requestAnimationFrame(() => {
+      this.#raf = null
+      this.#sync()
+    })
+  }
+
+  /** The previous button's click action: pages one slide back. */
+  previous() {
+    this.#scrollTo(this.#index() - 1)
+  }
+
+  /** The next button's click action: pages one slide forward. */
+  next() {
+    this.#scrollTo(this.#index() + 1)
+  }
+
+  /**
+   * The region root's keydown action:
+   * arrows page the carousel, orientation-aware.
+   *
+   * @param {KeyboardEvent} event
+   */
+  keydown(event) {
+    const [prevKey, nextKey] =
+      this.orientationValue === "vertical" ? ["ArrowUp", "ArrowDown"] : ["ArrowLeft", "ArrowRight"]
+
+    if (event.key === prevKey) {
+      event.preventDefault()
+      this.previous()
+    } else if (event.key === nextKey) {
+      event.preventDefault()
+      this.next()
+    }
+  }
+
+  /**
+   * The programmatic surface: scrolls to a slide by index (clamped).
+   *
+   * @param {number | string} index - stringified numbers accepted
+   */
+  scrollTo(index) {
+    this.#scrollTo(Number(index))
+  }
+
+  #scrollTo(index) {
+    const slides = this.#slides()
+    const target = slides[Math.max(0, Math.min(slides.length - 1, index))]
+    if (!target) return
+
+    // Rect delta start-aligns the target inside the viewport alone.
+    // Subtracting scroll-margin lands on the slide's SNAP position (the
+    // items carry negative scroll-margin to cancel their gutter from the
+    // snap area), so the smooth scroll and the CSS snap agree.
+    const vertical = this.orientationValue === "vertical"
+    const rect = target.getBoundingClientRect()
+    const viewport = this.viewportTarget.getBoundingClientRect()
+    const style = getComputedStyle(target)
+    const delta = vertical
+      ? rect.top - (parseFloat(style.scrollMarginTop) || 0) - viewport.top
+      : rect.left - (parseFloat(style.scrollMarginLeft) || 0) - viewport.left
+
+    this.viewportTarget.scrollBy?.({
+      behavior: "smooth",
+      left: vertical ? 0 : delta,
+      top: vertical ? delta : 0
+    })
+    // Button state also syncs from the scroll events the smooth scroll
+    // emits; this immediate pass covers environments without them.
+    this.#sync(index)
+  }
+
+  // The slide nearest the viewport's start edge - bounding rects, so RTL
+  // and transforms cost nothing.
+  #index() {
+    const viewport = this.viewportTarget.getBoundingClientRect()
+    let nearest = 0
+    let nearestDistance = Infinity
+
+    this.#slides().forEach((slide, index) => {
+      const rect = slide.getBoundingClientRect()
+      const distance = this.orientationValue === "vertical"
+        ? Math.abs(rect.top - viewport.top)
+        : Math.abs(rect.left - viewport.left)
+
+      if (distance < nearestDistance) {
+        nearest = index
+        nearestDistance = distance
+      }
+    })
+
+    return nearest
+  }
+
+  #sync(index = this.#index()) {
+    const last = this.#slides().length - 1
+
+    if (this.hasPreviousTarget) this.previousTarget.disabled = index <= 0
+    if (this.hasNextTarget) this.nextTarget.disabled = index >= last || this.#atEnd()
+
+    this.dispatch("select", { prefix: EVENT_PREFIX, detail: { index } })
+  }
+
+  // Snap points the scroller cannot reach still exist under native
+  // scroll, so next must ALSO disable at max scroll -
+  // otherwise trailing slides that cannot start-align (multi-visible
+  // layouts) leave a live button that does nothing. Math.abs keeps the
+  // check RTL-safe (scrollLeft runs negative there).
+  #atEnd() {
+    const viewport = this.viewportTarget
+    const vertical = this.orientationValue === "vertical"
+    const max = vertical
+      ? viewport.scrollHeight - viewport.clientHeight
+      : viewport.scrollWidth - viewport.clientWidth
+
+    return max > 0 && Math.abs(vertical ? viewport.scrollTop : viewport.scrollLeft) >= max - 1
+  }
+
+  #slides() {
+    return [...this.viewportTarget.querySelectorAll(SLIDE_SELECTOR)]
+  }
+}

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

@@ -0,0 +1,97 @@
+import { Controller } from "@hotwired/stimulus"
+import { stateOf } from "@poetry/controllers/helpers/state"
+
+// The select-all recipe (a parent checkbox running the APG
+// mixed-state pattern) over the checked family. Wrap the parent and its
+// rows, route the bubbling per-checkbox observe event at #changed, and
+// mark the parent (target: all) plus each row (target: item):
+//
+//   <div data-controller="poetry--core--checkbox-group"
+//        data-action="poetry:checkbox:change->poetry--core--checkbox-group#changed">
+//
+// A parent toggle fans its new state out to every enabled row; a row
+// toggle re-derives the parent (all -> checked, none -> unchecked, some ->
+// indeterminate, re-entered via the checked controller's set() - the only
+// path back to mixed). Every state write goes THROUGH each box's checked
+// controller (input first, real change event, aria-checked + the checked
+// triple together) - this controller never touches attributes itself.
+// Disabled rows are skipped by fan-out and excluded from the derivation
+// (the DataTable disabledBehavior 'selection' doctrine;
+// table_selection_controller is this same recipe for NATIVE checkboxes).
+const EVENT_PREFIX = "poetry:checkbox-group"
+
+export default class CheckboxGroupController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:checkbox-group:change"]
+
+  static targets = ["all", "item"]
+
+  #applying = false
+
+  /**
+   * The wrapper's data-action route for every bubbling checkbox change: a
+   * parent toggle fans out, a row toggle re-derives the parent, and the
+   * group's own change event reports the enabled count/total. The
+   * applying flag mutes the echoes our own set() calls dispatch (a
+   * fan-out must not re-derive per row; a parent reflection must not fan
+   * out).
+   *
+   * @param {CustomEvent} event - the per-checkbox change
+   */
+  changed(event) {
+    if (this.#applying) return
+
+    const fromParent = this.hasAllTarget && event.target === this.allTarget
+
+    if (!fromParent && !this.itemTargets.includes(event.target)) return
+    if (fromParent) this.#fanOut(event.detail.checked)
+
+    // After a fan-out too: rows that refused (all disabled) snap the
+    // parent back to what the roster actually holds.
+    this.#reflectParent()
+
+    const enabled = this.#enabled()
+
+    this.dispatch("change", {
+      prefix: EVENT_PREFIX,
+      detail: { count: this.#checked(enabled).length, total: enabled.length }
+    })
+  }
+
+  #fanOut(checked) {
+    this.#applying = true
+    for (const item of this.#enabled()) this.#checkedController(item)?.set(checked)
+    this.#applying = false
+  }
+
+  #reflectParent() {
+    if (!this.hasAllTarget) return
+
+    const enabled = this.#enabled()
+    const checked = this.#checked(enabled).length
+    const state = checked === 0 ? "unchecked" : (checked === enabled.length ? "checked" : "indeterminate")
+
+    // Dedupe: a row toggle that leaves the parent where it was (one of
+    // several rows unchecked) must not re-dispatch the parent's change.
+    if (stateOf(this.allTarget) === state) return
+
+    this.#applying = true
+    this.#checkedController(this.allTarget)?.set(state === "indeterminate" ? state : state === "checked")
+    this.#applying = false
+  }
+
+  #checked(items) {
+    return items.filter((item) => stateOf(item) === "checked")
+  }
+
+  #enabled() {
+    return this.itemTargets.filter(
+      (item) => !item.hasAttribute("disabled") && item.getAttribute("aria-disabled") !== "true"
+    )
+  }
+
+  #checkedController(element) {
+    return this.application.getControllerForElementAndIdentifier(element, "poetry--core--checked")
+  }
+}

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

@@ -0,0 +1,208 @@
+import { Controller } from "@hotwired/stimulus"
+import { setState, stateOf } from "@poetry/controllers/helpers/state"
+
+// The toggle family's checked-state owner (Checkbox introduces it; Switch
+// reuses it VERBATIM - zero fork, CI-asserted). The architecture is the
+// STORE INVERSION: the hidden native <input type=checkbox> is the form
+// participant AND the store - the visual button[role=checkbox|switch] only
+// REFLECTS it (aria-checked incl. "mixed" + the data-checked/data-unchecked/
+// data-indeterminate attributes on the control and every part that carries
+// them: the checkbox indicator, the switch thumb). Every transition writes the input FIRST, dispatches a REAL
+// bubbling change event (no synthetic prototype-setter dance - the
+// input LEADS and the visual follows), then reflects attributes.
+//
+// The three states: checked / unchecked / indeterminate. Indeterminate is
+// server/programmatic only (aria-checked=mixed, input.indeterminate - a
+// JS-only property re-derived from the checked attributes on connect); the first user
+// toggle resolves it to CHECKED - contractual, do not loosen. A Switch
+// never renders it (the Ruby component raises), so that branch is
+// simply dormant there.
+//
+// Enter is suppressed on role=checkbox ONLY (WAI-ARIA: checkboxes activate
+// on Space alone); role=switch has no keydown
+// handler, so Enter toggles via the native button click (a deliberate
+// asymmetry, keyed off the role - no controller fork).
+//
+// No inputId value -> pure visual mode: state lives on the button's
+// checked attributes alone (controlled-UI cases like DataTable row selection).
+// The component-flavored prefixes the dynamic dispatch below emits under
+// (data-component on the host: checkbox / switch, with the bare fallback) -
+// the events declaration, the portal bridge, and the manifest enumerate
+// these REAL names; the identifier-default name never fires here.
+const EVENT_PREFIXES = ["poetry:checkbox", "poetry:switch", "poetry:checked"]
+
+export default class CheckedController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = EVENT_PREFIXES.map((prefix) => `${prefix}:change`)
+
+  static values = {
+    inputId: { type: String, default: "" }
+  }
+
+  #keydown = null
+  #reset = null
+  #form = null
+  #initialIndeterminate = false
+
+  /**
+   * Reconcile-on-connect: derives input.checked/indeterminate from the
+   * checked attributes (the server truth), arms the form-reset restore,
+   * and installs the role-keyed Enter suppression.
+   */
+  connect() {
+    const input = this.#input()
+
+    // Reconcile-on-connect: the checked attributes are the server truth
+    // (Turbo Stream re-render safe); input.indeterminate has no attribute -
+    // derive it.
+    if (input) {
+      const state = this.#state()
+
+      this.#initialIndeterminate = state === "indeterminate"
+      input.checked = state === "checked"
+      input.indeterminate = this.#initialIndeterminate
+
+      // Native form reset restores the server-rendered checked attribute -
+      // initial-state restore for free; rAF because
+      // reset fires BEFORE the browser restores input values.
+      this.#form = input.form
+
+      if (this.#form) {
+        this.#reset = () => window.requestAnimationFrame(() => {
+          input.indeterminate = this.#initialIndeterminate
+          this.#reflect(input.indeterminate ? "indeterminate" : (input.checked ? "checked" : "unchecked"))
+        })
+        this.#form.addEventListener("reset", this.#reset)
+      }
+    }
+
+    // WAI-ARIA: a checkbox does not activate on Enter (Space only - the
+    // form's Enter-to-submit is unaffected). Keyed off the role so the
+    // Switch reuse keeps its native Enter-toggles behavior.
+    if (this.element.getAttribute("role") === "checkbox") {
+      this.#keydown = (event) => {
+        if (event.key === "Enter") event.preventDefault()
+      }
+      this.element.addEventListener("keydown", this.#keydown)
+    }
+  }
+
+  /** Unwires the keydown and form-reset listeners. */
+  disconnect() {
+    if (this.#keydown) this.element.removeEventListener("keydown", this.#keydown)
+    if (this.#reset && this.#form) this.#form.removeEventListener("reset", this.#reset)
+
+    this.#keydown = null
+    this.#reset = null
+    this.#form = null
+  }
+
+  /**
+   * Control activation (click / Space / label-for): indeterminate
+   * resolves to checked (contractual), else flip.
+   */
+  toggle() {
+    if (this.#disabled()) return
+
+    const state = this.#state()
+    const wasIndeterminate = state === "indeterminate"
+
+    this.#commit(wasIndeterminate ? true : state !== "checked", { wasIndeterminate })
+  }
+
+  // --- the programmatic controllable-state surface ---
+
+  /** Programmatically checks (see set). */
+  check() {
+    this.set(true)
+  }
+
+  /** Programmatically unchecks (see set). */
+  uncheck() {
+    this.set(false)
+  }
+
+  /**
+   * The programmatic controllable-state surface: set(true | false |
+   * "indeterminate") reaches all three states (the select-all recipe -
+   * checkbox_group_controller - re-enters indeterminate this way).
+   *
+   * @param {boolean | "indeterminate"} state
+   */
+  set(state) {
+    if (this.#disabled()) return
+
+    if (state === "indeterminate") this.#commitIndeterminate()
+    else this.#commit(Boolean(state), { wasIndeterminate: this.#state() === "indeterminate" })
+  }
+
+  // --- the one write path: input first, real change event, then reflect ---
+
+  #commit(checked, { wasIndeterminate = false } = {}) {
+    const input = this.#input()
+
+    if (input) {
+      input.indeterminate = false
+      input.checked = checked
+      input.dispatchEvent(new Event("change", { bubbles: true }))
+    }
+
+    this.#reflect(checked ? "checked" : "unchecked")
+
+    // The component-flavored observe surface (poetry:checkbox:change /
+    // poetry:switch:change) without forking the shared controller: the
+    // prefix derives from the host's data-component self-id.
+    this.dispatch("change", {
+      prefix: `poetry:${this.element.dataset.component ?? "checked"}`,
+      detail: { checked, was_indeterminate: wasIndeterminate }
+    })
+  }
+
+  #commitIndeterminate() {
+    const input = this.#input()
+
+    if (input) {
+      input.checked = false
+      input.indeterminate = true
+      input.dispatchEvent(new Event("change", { bubbles: true }))
+    }
+
+    this.#reflect("indeterminate")
+    this.dispatch("change", {
+      prefix: `poetry:${this.element.dataset.component ?? "checked"}`,
+      detail: { checked: false, was_indeterminate: false, indeterminate: true }
+    })
+  }
+
+  // aria-checked (mixed mapping) and the checked attributes are written
+  // TOGETHER, on the control AND every part that mirrors the checked state
+  // (indicator / thumb) - recognized by wearing any of the family's pair
+  // attributes (data-checked / data-unchecked / data-indeterminate).
+  #reflect(state) {
+    this.element.setAttribute("aria-checked", state === "indeterminate" ? "mixed" : String(state === "checked"))
+    setState(this.element, state)
+
+    const parts = this.element.querySelectorAll("[data-checked], [data-unchecked], [data-indeterminate]")
+
+    for (const part of parts) setState(part, state)
+  }
+
+  #state() {
+    const state = stateOf(this.element)
+
+    if (state) return state
+
+    const aria = this.element.getAttribute("aria-checked")
+
+    return aria === "mixed" ? "indeterminate" : (aria === "true" ? "checked" : "unchecked")
+  }
+
+  #input() {
+    return this.inputIdValue ? document.getElementById(this.inputIdValue) : null
+  }
+
+  #disabled() {
+    return this.element.hasAttribute("disabled") || this.element.getAttribute("aria-disabled") === "true"
+  }
+}

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

@@ -0,0 +1,111 @@
+import { Controller } from "@hotwired/stimulus"
+import { announce } from "@poetry/controllers/helpers/announce"
+
+// ClipboardText, adapted from an MIT-licensed source (source and license
+// in THIRD_PARTY_NOTICES.md): a read-only value with one
+// copy affordance. navigator.clipboard is the primary path; the
+// execCommand fallback SAVES AND RESTORES the user's own selection and
+// focus (copying a field must never eat a selection made elsewhere on the
+// page). Success stamps data-copied on
+// the root for a beat (CSS swaps the copy/check glyphs off it), announces
+// through the live-region singleton, and dispatches the copied event.
+const EVENT_PREFIX = "poetry:clipboard-text"
+const COPIED_MS = 1500
+
+export default class ClipboardTextController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:clipboard-text:copied"]
+
+  // input: a field whose value is the text. source: any element whose
+  // textContent is the text (CodeBlock's rendered code - CSS-counter line
+  // numbers live in ::before and are excluded by construction).
+  static targets = ["input", "source"]
+
+  static values = {
+    // Copy override: the full value when the display truncates.
+    // Empty means "copy what the input/source shows".
+    text: String,
+    // The announcement, localized server-side.
+    message: String
+  }
+
+  /** Clears the copied-beat timer. */
+  disconnect() {
+    clearTimeout(this.#timer)
+  }
+
+  /**
+   * The copy action: writes the text (navigator.clipboard first, then the
+   * selection-preserving execCommand fallback), stamps data-copied for a
+   * beat, announces, and dispatches the copied event with the text in the
+   * detail. A failed write changes nothing.
+   *
+   * @returns {Promise<void>}
+   */
+  async copy() {
+    const text = this.#text
+    if (!(await this.#write(text))) return
+
+    this.element.toggleAttribute("data-copied", true)
+    clearTimeout(this.#timer)
+    this.#timer = setTimeout(() => this.element.removeAttribute("data-copied"), COPIED_MS)
+
+    if (this.messageValue !== "") announce(this.messageValue)
+    this.dispatch("copied", { prefix: EVENT_PREFIX, detail: { text } })
+  }
+
+  #timer
+
+  get #text() {
+    if (this.textValue !== "") return this.textValue
+    if (this.hasSourceTarget) return this.sourceTarget.textContent
+
+    return this.inputTarget.value
+  }
+
+  async #write(text) {
+    try {
+      await navigator.clipboard.writeText(text)
+      return true
+    } catch {
+      return this.#execCommandFallback(text)
+    }
+  }
+
+  // Legacy path: an offscreen textarea receives the value and the
+  // selection, execCommand copies the LIVE selection - so the user's own
+  // selection is cloned first and restored after, and focus goes back
+  // where it was.
+  #execCommandFallback(text) {
+    const selection = document.getSelection()
+    const savedRanges = []
+    for (let index = 0; index < selection.rangeCount; index += 1) {
+      savedRanges.push(selection.getRangeAt(index).cloneRange())
+    }
+    const savedFocus = document.activeElement
+
+    const textarea = document.createElement("textarea")
+    textarea.value = text
+    textarea.setAttribute("readonly", "")
+    textarea.setAttribute("aria-hidden", "true")
+    textarea.style.position = "fixed"
+    textarea.style.opacity = "0"
+    this.element.appendChild(textarea)
+    textarea.select()
+
+    let copied = false
+    try {
+      copied = document.execCommand("copy")
+    } catch {
+      copied = false
+    }
+
+    textarea.remove()
+    selection.removeAllRanges()
+    for (const range of savedRanges) selection.addRange(range)
+    if (savedFocus && savedFocus.isConnected) savedFocus.focus()
+
+    return copied
+  }
+}