poetry-core 0.0.2

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

@@ -0,0 +1,202 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The Resizable engine, decided NATIVE: no panel library -
+// panels are flex children whose flex-grow IS the percentage, and this
+// controller implements the APG window-splitter on the handles: pointer
+// drag redistributes the two adjacent panels (clamped to each panel's
+// min/max), arrows step, Home/End jump the range, and every move writes
+// aria-valuenow (the preceding panel's size).
+// Deferred with the library's machinery: persistence (autoSaveId),
+// collapsible panels, and the imperative API.
+const PANEL_SELECTOR = '[data-slot="resizable-panel"]'
+const HANDLE_SELECTOR = '[data-slot="resizable-handle"]'
+
+const KEY_STEP = 5 // percent per arrow press (the APG "larger than one pixel" step)
+const DEFAULT_MIN = 10
+const DEFAULT_MAX = 90
+
+// The component-facing event namespace (the poetry:<component> rule).
+const EVENT_PREFIX = "poetry:resizable"
+
+export default class ResizableController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:resizable:resize"]
+
+  static values = {
+    orientation: { type: String, default: "horizontal" }
+  }
+
+  #drag = null
+
+  /** Writes the initial aria-value* reflection onto every handle. */
+  connect() {
+    this.#reflectAll()
+  }
+
+  /**
+   * Each handle's pointerdown action: begins a drag between the two
+   * adjacent panels (pointer capture holds the gesture).
+   *
+   * @param {PointerEvent} event
+   */
+  dragStart(event) {
+    if (event.button !== 0 && event.pointerType === "mouse") return
+
+    const handle = this.#handleFrom(event)
+    if (!handle) return
+
+    const [before, after] = this.#panelsAround(handle)
+    if (!before || !after) return
+
+    this.#drag = {
+      pointerId: event.pointerId, handle, before, after,
+      start: this.#along(event),
+      beforeSize: this.#sizeOf(before), afterSize: this.#sizeOf(after)
+    }
+    handle.setPointerCapture(event.pointerId)
+  }
+
+  /**
+   * The captured pointermove action: redistributes the two panels by the
+   * drag delta, clamped to both panels' min/max.
+   *
+   * @param {PointerEvent} event
+   */
+  dragMove(event) {
+    const drag = this.#drag
+    if (!drag || event.pointerId !== drag.pointerId) return
+
+    const groupSize = this.#groupSize()
+    const deltaPercent = ((this.#along(event) - drag.start) / groupSize) * 100
+
+    this.#apply(drag.before, drag.after, drag.beforeSize + deltaPercent, drag.beforeSize + drag.afterSize)
+    this.#reflect(drag.handle)
+  }
+
+  /**
+   * The pointerup / pointercancel action: ends the drag.
+   *
+   * @param {PointerEvent} event
+   */
+  dragEnd(event) {
+    if (!this.#drag || event.pointerId !== this.#drag.pointerId) return
+
+    this.#drag = null
+  }
+
+  /**
+   * Each handle's keydown action (the APG window splitter): arrows step
+   * by 5%, Home/End jump the range.
+   *
+   * @param {KeyboardEvent} event
+   */
+  keydown(event) {
+    const handle = this.#handleFrom(event)
+    if (!handle) return
+
+    const [before, after] = this.#panelsAround(handle)
+    if (!before || !after) return
+
+    const [decrease, increase] = this.orientationValue === "vertical"
+      ? ["ArrowUp", "ArrowDown"]
+      : ["ArrowLeft", "ArrowRight"]
+    const pool = this.#sizeOf(before) + this.#sizeOf(after)
+    let target = null
+
+    if (event.key === decrease) target = this.#sizeOf(before) - KEY_STEP
+    else if (event.key === increase) target = this.#sizeOf(before) + KEY_STEP
+    else if (event.key === "Home") target = this.#minOf(before)
+    else if (event.key === "End") target = pool - this.#minOf(after)
+    else return
+
+    event.preventDefault()
+    this.#apply(before, after, target, pool)
+    this.#reflect(handle)
+  }
+
+  // Redistribute the shared pool between two adjacent panels, honoring
+  // BOTH panels' min/max.
+  #apply(before, after, requestedBefore, pool) {
+    const beforeSize = Math.min(
+      Math.max(requestedBefore, this.#minOf(before), pool - this.#maxOf(after)),
+      this.#maxOf(before), pool - this.#minOf(after)
+    )
+
+    this.#write(before, beforeSize)
+    this.#write(after, pool - beforeSize)
+    this.dispatch("resize", { prefix: EVENT_PREFIX, detail: { sizes: this.#panels().map((panel) => this.#sizeOf(panel)) } })
+  }
+
+  #write(panel, size) {
+    panel.style.flexGrow = String(Math.round(size * 100) / 100)
+    panel.style.flexShrink = "1"
+    panel.style.flexBasis = "0px"
+  }
+
+  // aria-valuenow = the PRECEDING panel's size.
+  #reflect(handle) {
+    const [before] = this.#panelsAround(handle)
+    if (!before) return
+
+    handle.setAttribute("aria-valuenow", String(Math.round(this.#sizeOf(before))))
+    handle.setAttribute("aria-valuemin", String(Math.round(this.#minOf(before))))
+    handle.setAttribute("aria-valuemax", String(Math.round(this.#maxOf(before))))
+  }
+
+  #reflectAll() {
+    for (const handle of this.#handles()) this.#reflect(handle)
+  }
+
+  #handleFrom(event) {
+    const origin = event.target instanceof Element ? event.target : null
+    const handle = origin?.closest(HANDLE_SELECTOR)
+
+    return handle && this.#owns(handle) ? handle : null
+  }
+
+  // The panels immediately around a handle, in DOM order.
+  #panelsAround(handle) {
+    let before = handle.previousElementSibling
+    while (before && !before.matches(PANEL_SELECTOR)) before = before.previousElementSibling
+    let after = handle.nextElementSibling
+    while (after && !after.matches(PANEL_SELECTOR)) after = after.nextElementSibling
+
+    return [before, after]
+  }
+
+  #sizeOf(panel) {
+    return parseFloat(panel.style.flexGrow || "1") || 1
+  }
+
+  #minOf(panel) {
+    return parseFloat(panel.dataset.minSize ?? "") || DEFAULT_MIN
+  }
+
+  #maxOf(panel) {
+    return parseFloat(panel.dataset.maxSize ?? "") || DEFAULT_MAX
+  }
+
+  #along(event) {
+    return this.orientationValue === "vertical" ? event.clientY : event.clientX
+  }
+
+  #groupSize() {
+    const rect = this.element.getBoundingClientRect()
+
+    return Math.max(1, this.orientationValue === "vertical" ? rect.height : rect.width)
+  }
+
+  #panels() {
+    return [...this.element.querySelectorAll(PANEL_SELECTOR)].filter((el) => this.#owns(el))
+  }
+
+  #handles() {
+    return [...this.element.querySelectorAll(HANDLE_SELECTOR)].filter((el) => this.#owns(el))
+  }
+
+  // Nested groups self-scope (the DOM is the registry).
+  #owns(el) {
+    return el.closest(`[data-controller~="${this.identifier}"]`) === this.element
+  }
+}

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

@@ -0,0 +1,215 @@
+import { Controller } from "@hotwired/stimulus"
+import { COLLECTION_ITEM_SELECTOR, collectionItems } from "@poetry/controllers/helpers/collection"
+import { directionOf } from "@poetry/controllers/helpers/direction"
+
+// The roving-tabindex engine: the group is ONE Tab stop -
+// exactly one item holds tabindex=0, the rest -1, and arrow keys move focus
+// among the collection items in DOM order. Orientation gates which arrows
+// are live (horizontal flips Left/Right under RTL via the direction
+// helper); Home/End jump to the edges; loop wraps. Backs Tabs, Toolbar,
+// RadioGroup, Menus, ToggleGroup, and the Select/Command list.
+//
+// Dynamic items: NAVIGATION recomputes the collection on every keydown (the
+// DOM is the registry - always fresh, zero bookkeeping), but that alone is
+// not correct: an item appended between keystrokes would sit at its natural
+// tabindex and grow the group a SECOND Tab stop before any arrow is
+// pressed. The MutationObserver exists for that one job - re-stamping the
+// roving tabindex the moment items enter or leave.
+export default class RovingFocusController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry--core--roving-focus:entry"]
+
+  static values = {
+    orientation: { type: String, default: "vertical" }, // horizontal | vertical | both
+    loop: { type: Boolean, default: true },
+    // false = focus-nav-only mode (the APG accordion contract): every
+    // trigger stays tabbable and arrows are convenience navigation, not a
+    // roving tab stop. The controller then NEVER writes tabindex - not on
+    // connect, not on mutation, not on focus moves.
+    manageTabindex: { type: Boolean, default: true }
+  }
+
+  #observer = null
+
+  /**
+   * Stamps the initial tab stops and starts the item-mutation
+   * re-stamping (the header's second-Tab-stop hazard).
+   */
+  connect() {
+    this.#syncItems()
+
+    this.#observer = new MutationObserver(() => this.#syncItems())
+    this.#observer.observe(this.element, { childList: true, subtree: true })
+  }
+
+  /** Stops the mutation observer. */
+  disconnect() {
+    this.#observer?.disconnect()
+    this.#observer = null
+  }
+
+  /**
+   * The group root's keydown action: arrows/Home/End move the roving
+   * focus - orientation-gated, RTL-aware, loop-wrapping. The caret guard
+   * leaves text-entry controls their keys until the caret reaches the
+   * travel-direction boundary.
+   *
+   * @param {KeyboardEvent} event
+   */
+  keydown(event) {
+    if (event.defaultPrevented) return // a nested group (an open menu level) already moved focus
+    if (this.#caretTrapped(event)) return // the caret owns this key inside a text control
+
+    const items = this.#items()
+
+    if (items.length === 0) return
+
+    const nextIndex = this.#nextIndex(event.key, this.#indexFor(event.target, items), items.length)
+
+    if (nextIndex === null) return
+
+    event.preventDefault() // a handled arrow must not also scroll the page
+    this.#focusItem(items[nextIndex], items)
+  }
+
+  // The caret guard: when the keydown originates inside a text-entry
+  // control (a toolbar's search field, a menu's filter input), the caret
+  // owns horizontal arrows and Home/End until it reaches the boundary in
+  // the travel direction - only then does the group rove. Any selection
+  // means the key collapses it (caret work, never roving); contenteditable
+  // and controls without a selection API (type=number steps on arrows)
+  // are never stolen from. Vertical arrows inside a textarea stay with the
+  // caret too; a single-line input has no vertical caret motion, so
+  // Up/Down rove as usual.
+  #caretTrapped(event) {
+    const target = event.target
+
+    if (!(target instanceof HTMLElement)) return false
+    if (target.isContentEditable) return true
+
+    const isTextarea = target instanceof HTMLTextAreaElement
+    const isInput = target instanceof HTMLInputElement
+
+    if (!isTextarea && !isInput) return false
+    if (isTextarea && event.key.startsWith("Arrow")) return true
+
+    const horizontal = ["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)
+
+    if (!horizontal) return false
+
+    const start = target.selectionStart
+    const end = target.selectionEnd
+
+    if (start === null || end === null) return true // no selection API: never steal
+    if (start !== end) return true // a selection collapses first
+
+    const length = target.value.length
+    const rtl = directionOf(target) === "rtl"
+    const towardStart = event.key === "Home" || (event.key === (rtl ? "ArrowRight" : "ArrowLeft"))
+
+    return towardStart ? start > 0 : end < length
+  }
+
+  // The group's OWN items only: a hidden subtree (a closed submenu level) is
+  // not navigable, data-disabled items are filtered at query time (the menu
+  // contract), and an item claimed by a DESCENDANT roving group (an open
+  // submenu's content) roves there, not here - nested groups self-scope
+  // without any registration bookkeeping (the DOM is the registry).
+  #items() {
+    return collectionItems(this.element).filter((item) => this.#owns(item))
+  }
+
+  #owns(item) {
+    if (item.closest("[hidden]")) return false
+    if (item.hasAttribute("data-disabled")) return false
+
+    const scope = item.parentElement?.closest(`[data-controller~="${this.identifier}"]`)
+
+    return !scope || scope === this.element
+  }
+
+  #indexFor(target, items) {
+    const item = target instanceof Element ? target.closest(COLLECTION_ITEM_SELECTOR) : null
+    const index = items.indexOf(item)
+
+    if (index !== -1) return index
+
+    // Keydown from the group itself (entry): start from the current tab stop.
+    return Math.max(this.#currentIndex(items), 0)
+  }
+
+  #currentIndex(items) {
+    return items.findIndex((item) => item.getAttribute("tabindex") === "0")
+  }
+
+  #nextIndex(key, index, count) {
+    if (key === "Home") return 0
+    if (key === "End") return count - 1
+
+    const delta = this.#arrowDelta(key)
+
+    if (delta === null) return null
+
+    const next = index + delta
+
+    if (this.loopValue) return (next + count) % count
+
+    return Math.min(Math.max(next, 0), count - 1) // no loop: the edges clamp
+  }
+
+  // Orientation gates the axis; the cross-axis arrows fall through untouched
+  // (a vertical menu must not swallow Left/Right). "both" activates all four
+  // arrows (the APG radio contract): Down/Right advance,
+  // Up/Left retreat, with ONLY the horizontal pair RTL-flipped. RTL is read
+  // per keystroke from the closest [dir] ancestor, so a dir flip needs no
+  // reconnect.
+  #arrowDelta(key) {
+    const axis = this.orientationValue
+
+    if (axis !== "vertical" && (key === "ArrowRight" || key === "ArrowLeft")) {
+      const rtl = directionOf(this.element) === "rtl"
+
+      if (key === "ArrowRight") return rtl ? -1 : 1
+
+      return rtl ? 1 : -1
+    }
+
+    if (axis !== "horizontal") {
+      if (key === "ArrowDown") return 1
+      if (key === "ArrowUp") return -1
+    }
+
+    return null
+  }
+
+  // Cancelable entry: a consumer preventDefault()s to keep focus where it
+  // is. The tab stop only moves when focus actually does.
+  #focusItem(item, items = this.#items()) {
+    const entry = this.dispatch("entry", { detail: { item }, cancelable: true })
+
+    if (entry.defaultPrevented) return
+
+    this.#writeTabStops(items, item)
+    item.focus()
+  }
+
+  // One 0, rest -1. The current stop survives re-syncs; if it was removed
+  // (or never existed - fresh connect), the first item takes it.
+  #syncItems() {
+    const items = this.#items()
+
+    this.element.dataset.orientation = this.orientationValue
+
+    const currentIndex = this.#currentIndex(items)
+    this.#writeTabStops(items, items[Math.max(currentIndex, 0)])
+  }
+
+  #writeTabStops(items, current) {
+    for (const item of items) {
+      if (this.manageTabindexValue) item.setAttribute("tabindex", item === current ? "0" : "-1")
+
+      item.dataset.orientation = this.orientationValue
+    }
+  }
+}

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

@@ -0,0 +1,84 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Scroll-spy: marks the
+// nav link whose section is currently active while the page scrolls - the
+// docs-TOC pattern. Put the controller on the nav; every link target's
+// href="#id" names its section:
+//
+//   <nav data-controller="poetry--core--scroll-spy">
+//     <a href="#usage" data-poetry--core--scroll-spy-target="link">Usage</a>
+//
+// The active section is the LAST one whose top sits above the offset line
+// (a closest-heading reduce); its link gains data-active and a
+// poetry--core--scroll-spy:changed event carries the id. rAF-coalesced
+// passive scroll + resize listeners; call refresh() after content changes.
+export default class extends Controller {
+  static targets = ["link"]
+  static values = {
+    // Viewport y (px) a section must cross to count as active.
+    offset: { type: Number, default: 96 }
+  }
+
+  static events = ["poetry--core--scroll-spy:changed"]
+
+  #onScroll = null
+  #frame = null
+  #sections = []
+  #activeId = null
+
+  /**
+   * Resolves the sections and wires the rAF-coalesced passive
+   * scroll/resize listeners.
+   */
+  connect() {
+    this.refresh()
+    this.#onScroll = () => {
+      if (this.#frame !== null) return
+
+      this.#frame = requestAnimationFrame(() => {
+        this.#frame = null
+        this.#update()
+      })
+    }
+    window.addEventListener("scroll", this.#onScroll, { passive: true })
+    window.addEventListener("resize", this.#onScroll, { passive: true })
+  }
+
+  /** Unwires the listeners and cancels any pending frame. */
+  disconnect() {
+    window.removeEventListener("scroll", this.#onScroll)
+    window.removeEventListener("resize", this.#onScroll)
+    if (this.#frame !== null) cancelAnimationFrame(this.#frame)
+    this.#frame = null
+  }
+
+  /**
+   * Re-resolves sections from the links' hashes (content changed, Turbo
+   * morph, tab switch) and recomputes immediately.
+   */
+  refresh() {
+    this.#sections = this.linkTargets
+      .map((link) => {
+        const hash = link.getAttribute("href") || ""
+        const id = hash.startsWith("#") ? hash.slice(1) : null
+        return id ? { link, section: document.getElementById(id) } : null
+      })
+      .filter((entry) => entry && entry.section)
+    this.#update()
+  }
+
+  #update() {
+    let active = null
+    for (const entry of this.#sections) {
+      if (entry.section.getBoundingClientRect().top <= this.offsetValue) active = entry
+    }
+
+    const id = active ? active.section.id : null
+    if (id === this.#activeId) return
+
+    this.#activeId = id
+    this.linkTargets.forEach((link) => link.removeAttribute("data-active"))
+    if (active) active.link.setAttribute("data-active", "")
+    this.dispatch("changed", { detail: { id } })
+  }
+}

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

@@ -0,0 +1,95 @@
+import { Controller } from "@hotwired/stimulus"
+import { isImeKeydown } from "@poetry/controllers/helpers/escape"
+
+// The SearchField seams: Escape CLEARS a
+// non-empty field and is consumed - the NEXT press reaches the dismissal
+// layer and closes a parent overlay; an already-empty field lets Escape
+// propagate untouched. Emptiness is checked against the RAW input value
+// (autofill and scripts poke the DOM directly). The clear button keeps
+// focus in the input by preventing the press's focus steal at
+// pointerdown - on mobile that is what keeps the virtual keyboard up.
+// Enter is never intercepted: native form submission is the Rails path.
+const EVENT_PREFIX = "poetry:search-field"
+
+export default class SearchFieldController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:search-field:clear"]
+
+  static targets = ["input", "clear"]
+
+  /** Reflects the initial emptiness (data-empty + the clear affordance). */
+  connect() {
+    this.#reflect()
+  }
+
+  /** The input action: keeps data-empty and the clear affordance honest. */
+  changed() {
+    this.#reflect()
+  }
+
+  /**
+   * The input's keydown action: Escape CLEARS a non-empty field and is
+   * consumed; an already-empty field lets it propagate to the dismissal
+   * layer (the seam the header documents).
+   *
+   * @param {KeyboardEvent} event
+   */
+  keydown(event) {
+    if (event.key !== "Escape" || isImeKeydown(event)) return
+    if (this.inputTarget.disabled || this.inputTarget.readOnly) return
+    if (this.inputTarget.value === "") return // propagate: the dismissal layer's turn
+
+    event.preventDefault()
+    event.stopPropagation()
+    this.#clear()
+  }
+
+  /**
+   * The clear button's pointerdown action: keeps focus (and the mobile
+   * keyboard) in the input - the later click acts.
+   *
+   * @param {PointerEvent} event
+   */
+  holdFocus(event) {
+    event.preventDefault()
+    this.inputTarget.focus()
+  }
+
+  /**
+   * The clear button's click action: empties the field (dispatching a
+   * REAL input event so live-search listeners react) and refocuses it.
+   * No-op while disabled or readonly.
+   *
+   * @param {MouseEvent} event
+   */
+  clear(event) {
+    event.preventDefault()
+    if (this.inputTarget.disabled || this.inputTarget.readOnly) return
+
+    this.#clear()
+    this.inputTarget.focus()
+  }
+
+  #clear() {
+    if (this.inputTarget.value !== "") {
+      this.inputTarget.value = ""
+      // A REAL input event: live-search listeners (and Turbo forms) react
+      // to programmatic clearing exactly like typing.
+      this.inputTarget.dispatchEvent(new Event("input", { bubbles: true }))
+    }
+
+    this.#reflect()
+    this.dispatch("clear", { prefix: EVENT_PREFIX })
+  }
+
+  #reflect() {
+    const empty = this.inputTarget.value === ""
+
+    this.element.toggleAttribute("data-empty", empty)
+
+    if (this.hasClearTarget) {
+      this.clearTarget.hidden = empty || this.inputTarget.readOnly || this.inputTarget.disabled
+    }
+  }
+}