poetry-core 0.0.2

data/app/javascript/poetry/core/helpers/scroller_geometry.js

@@ -0,0 +1,422 @@
+// Scroll geometry for the message-scroller, adapted from an MIT-licensed
+// source (source and license in THIRD_PARTY_NOTICES.md): pure functions
+// of {viewport, content, spacer, rects} - no Stimulus, no state. This is
+// the jsdom-testable half; the controller owns the policy that decides
+// when to call these. The constants encode deliberate fixes - treat them
+// as pinned values, not tunables.
+
+/**
+ * Two fractional scrollTop values within this range are treated as equal,
+ * to absorb zoom and HiDPI rounding drift.
+ */
+export const SCROLL_POSITION_EPSILON = 0.5
+
+/** Initial scrollable snapshot before measurement. */
+export const EMPTY_MESSAGE_SCROLLER_SCROLLABLE = Object.freeze({
+  start: false,
+  end: false
+})
+
+/** Initial visibility snapshot: nothing tracked, no current anchor. */
+export const EMPTY_MESSAGE_SCROLLER_VISIBILITY_STATE = Object.freeze({
+  currentAnchorId: null,
+  visibleMessageIds: Object.freeze([])
+})
+
+/**
+ * Whether the scroller has scroll room past each edge, beyond the
+ * configured threshold.
+ *
+ * @param {Object} args
+ * @param {HTMLElement | null} args.content
+ * @param {number} args.scrollEdgeThreshold - px of slack that still
+ *   counts as "at the edge"
+ * @param {HTMLElement | null} args.spacer
+ * @param {HTMLElement | null} args.viewport
+ * @returns {{ start: boolean, end: boolean }}
+ */
+export function getMessageScrollerScrollable({ content, scrollEdgeThreshold, spacer, viewport }) {
+  if (!viewport || !content) return EMPTY_MESSAGE_SCROLLER_SCROLLABLE
+
+  const contentBottom = getContentBottom({ content, spacer, viewport })
+
+  return {
+    start: viewport.scrollTop > scrollEdgeThreshold,
+    end: contentBottom - viewport.scrollTop - viewport.clientHeight > scrollEdgeThreshold
+  }
+}
+
+/**
+ * The visible message ids (top-to-bottom) and the current anchor - the
+ * last anchor row to have reached the reading line (the comments inside
+ * hold the line rules).
+ *
+ * @param {Object} args
+ * @param {HTMLElement | null} args.content
+ * @param {number} args.scrollMargin
+ * @param {number} args.scrollPreviousItemPeek
+ * @param {HTMLElement | null} args.spacer
+ * @param {HTMLElement | null} args.viewport
+ * @param {Set<string>} args.visibleMessageIds - the observer's current
+ *   set (consulted when IntersectionObserver exists)
+ * @returns {{ currentAnchorId: string | null, visibleMessageIds: string[] }}
+ */
+export function getMessageScrollerVisibilityState({
+  content,
+  scrollMargin,
+  scrollPreviousItemPeek,
+  spacer,
+  viewport,
+  visibleMessageIds
+}) {
+  if (!content || !viewport) return EMPTY_MESSAGE_SCROLLER_VISIBILITY_STATE
+
+  const viewportRect = viewport.getBoundingClientRect()
+  // The reading line sits scrollPreviousItemPeek below scrollMargin: anchored
+  // turns land there with the previous turn peeking above. A row only peeking
+  // in that band has not been read down to yet, so it counts as neither
+  // visible nor current.
+  const lineTop = viewportRect.top + scrollMargin + scrollPreviousItemPeek
+  const trackByLayout = typeof IntersectionObserver === "undefined"
+
+  const visible = []
+  let currentAnchorId = null
+
+  // Walk rows in document order so visible ids come out top-to-bottom.
+  for (const item of getMessageScrollerItems(content, spacer)) {
+    const messageId = item.dataset.messageId
+    if (!messageId) continue
+
+    const isAnchor = item.dataset.scrollAnchor === "true"
+    // Anchors need a rect to place the current line; non-anchors lean on the
+    // observer set (or a rect in the no-observer fallback).
+    const rect = isAnchor || trackByLayout ? item.getBoundingClientRect() : null
+
+    const isVisible = trackByLayout && rect
+      ? rect.bottom > lineTop && rect.top < viewportRect.bottom
+      : visibleMessageIds.has(messageId)
+
+    if (isVisible) visible.push(messageId)
+
+    // Current is the last anchor to have reached the reading line: the turn
+    // you scrolled to (placed at the line) wins over newer turns lower down,
+    // the previous turn peeking above the line has been passed, and it stays
+    // current even after its header scrolls above the viewport.
+    if (isAnchor && rect && rect.top <= lineTop + SCROLL_POSITION_EPSILON) {
+      currentAnchorId = messageId
+    }
+  }
+
+  if (visible.length === 0 && currentAnchorId === null) {
+    return EMPTY_MESSAGE_SCROLLER_VISIBILITY_STATE
+  }
+
+  return { currentAnchorId, visibleMessageIds: visible }
+}
+
+/**
+ * The collection is DOM order: rows are content's element children minus
+ * the tail spacer - membership is a filter over live children, never a
+ * registration step.
+ *
+ * @param {HTMLElement} content
+ * @param {HTMLElement | null} spacer
+ * @returns {HTMLElement[]}
+ */
+export function getMessageScrollerItems(content, spacer) {
+  return Array.from(content.children).filter(
+    (child) => child instanceof HTMLElement && child !== spacer
+  )
+}
+
+/**
+ * The first anchor row appended after `previousItemCount` items existed.
+ *
+ * @param {HTMLElement[]} items
+ * @param {number} previousItemCount
+ * @returns {HTMLElement | null}
+ */
+export function getNewScrollAnchor(items, previousItemCount) {
+  for (let index = previousItemCount; index < items.length; index++) {
+    const item = items[index]
+    if (item?.dataset.scrollAnchor === "true") return item
+  }
+  return null
+}
+
+/**
+ * The first anchor row not yet in `handledAnchors`.
+ *
+ * @param {HTMLElement[]} items
+ * @param {Set<HTMLElement>} handledAnchors
+ * @returns {HTMLElement | null}
+ */
+export function getUnanchoredScrollAnchor(items, handledAnchors) {
+  for (const item of items) {
+    if (item.dataset.scrollAnchor === "true" && !handledAnchors.has(item)) return item
+  }
+  return null
+}
+
+/**
+ * Whether more than one anchor row arrived after `previousItemCount`
+ * items existed (a multi-turn batch).
+ *
+ * @param {HTMLElement[]} items
+ * @param {number} previousItemCount
+ * @returns {boolean}
+ */
+export function hasMultipleNewScrollAnchors(items, previousItemCount) {
+  let count = 0
+
+  for (let index = previousItemCount; index < items.length; index++) {
+    const item = items[index]
+    if (item?.dataset.scrollAnchor !== "true") continue
+
+    count += 1
+    if (count > 1) return true
+  }
+
+  return false
+}
+
+/**
+ * The last anchor row in the collection.
+ *
+ * @param {HTMLElement[]} items
+ * @returns {HTMLElement | null}
+ */
+export function getLastScrollAnchor(items) {
+  for (let index = items.length - 1; index >= 0; index--) {
+    const item = items[index]
+    if (item?.dataset.scrollAnchor === "true") return item
+  }
+  return null
+}
+
+/**
+ * The topmost message row intersecting the viewport.
+ *
+ * @param {Object} args
+ * @param {HTMLElement} args.content
+ * @param {HTMLElement | null} args.spacer
+ * @param {HTMLElement} args.viewport
+ * @returns {HTMLElement | null}
+ */
+export function getFirstVisibleMessageItem({ content, spacer, viewport }) {
+  const viewportRect = viewport.getBoundingClientRect()
+
+  for (const item of getMessageScrollerItems(content, spacer)) {
+    if (!item.dataset.messageId) continue
+
+    const rect = item.getBoundingClientRect()
+    if (rect.bottom > viewportRect.top && rect.top < viewportRect.bottom) return item
+  }
+
+  return null
+}
+
+/**
+ * Target scrollTop that aligns `element` to the viewport inset (content
+ * block padding respected).
+ *
+ * @param {Object} args
+ * @param {"start" | "center" | "end" | "nearest"} args.align
+ * @param {HTMLElement} args.element
+ * @param {number} args.scrollMargin
+ * @param {HTMLElement | null} args.spacer
+ * @param {HTMLElement} args.viewport
+ * @returns {number} the target scrollTop (the caller clamps)
+ */
+export function getElementScrollTop({ align, element, scrollMargin, spacer, viewport }) {
+  const elementTop = getElementTop(element, viewport)
+  const elementHeight = element.getBoundingClientRect().height
+  const contentPadding = getContentBlockPadding(spacer)
+
+  if (align === "center") {
+    const insetHeight = Math.max(
+      0,
+      viewport.clientHeight - contentPadding.start - contentPadding.end
+    )
+
+    return elementTop - contentPadding.start - (insetHeight - elementHeight) / 2 - scrollMargin
+  }
+
+  if (align === "end") {
+    return elementTop - viewport.clientHeight + elementHeight + contentPadding.end + scrollMargin
+  }
+
+  if (align === "nearest") {
+    const elementBottom = elementTop + elementHeight
+    const viewportTop = viewport.scrollTop + contentPadding.start
+    const viewportBottom = viewport.scrollTop + viewport.clientHeight - contentPadding.end
+
+    if (elementTop >= viewportTop && elementBottom <= viewportBottom) {
+      return viewport.scrollTop
+    }
+
+    if (elementTop < viewportTop) {
+      return elementTop - contentPadding.start - scrollMargin
+    }
+
+    return elementBottom - viewport.clientHeight + contentPadding.end + scrollMargin
+  }
+
+  return elementTop - contentPadding.start - scrollMargin
+}
+
+/**
+ * `element`'s top in the viewport's content space (independent of the
+ * current scroll position).
+ *
+ * @param {HTMLElement} element
+ * @param {HTMLElement} viewport
+ * @returns {number} px
+ */
+export function getElementTop(element, viewport) {
+  const elementRect = element.getBoundingClientRect()
+  const viewportRect = viewport.getBoundingClientRect()
+
+  return elementRect.top - viewportRect.top + viewport.scrollTop
+}
+
+/**
+ * `element`'s top relative to the viewport's current visual top.
+ *
+ * @param {HTMLElement} element
+ * @param {HTMLElement} viewport
+ * @returns {number} px
+ */
+export function getElementViewportTop(element, viewport) {
+  return element.getBoundingClientRect().top - viewport.getBoundingClientRect().top
+}
+
+/**
+ * Scroll room the tail spacer must fake below the last row so the
+ * requested scrollTop is reachable. Caller clamps/ceils (see the
+ * controller).
+ *
+ * @param {Object} args
+ * @param {HTMLElement} args.content
+ * @param {number} args.scrollTop - the position being made reachable
+ * @param {HTMLElement | null} args.spacer
+ * @param {HTMLElement} args.viewport
+ * @returns {number} px (possibly negative - the caller clamps)
+ */
+export function getTailSpacerHeight({ content, scrollTop, spacer, viewport }) {
+  const contentBottom = getContentBottom({ content, spacer, viewport })
+
+  return scrollTop + viewport.clientHeight - contentBottom
+}
+
+/**
+ * Lowest row bottom in content space plus block padding, EXCLUDING the
+ * tail spacer - the spacer must never make the jump button appear.
+ *
+ * @param {Object} args
+ * @param {HTMLElement} args.content
+ * @param {HTMLElement | null} args.spacer
+ * @param {HTMLElement} args.viewport
+ * @returns {number} px
+ */
+export function getContentBottom({ content, spacer, viewport }) {
+  const items = getMessageScrollerItems(content, spacer)
+  const padding = getBlockPadding(content)
+  const viewportRect = viewport.getBoundingClientRect()
+  const scrollTop = viewport.scrollTop
+  let contentBottom = padding.start + padding.end
+
+  for (const item of items) {
+    const rect = item.getBoundingClientRect()
+
+    contentBottom = Math.max(
+      contentBottom,
+      rect.bottom - viewportRect.top + scrollTop + padding.end
+    )
+  }
+
+  return contentBottom
+}
+
+/**
+ * The viewport's maximum scrollTop (never negative).
+ *
+ * @param {HTMLElement} viewport
+ * @returns {number} px
+ */
+export function getMaxScrollTop(viewport) {
+  return Math.max(0, viewport.scrollHeight - viewport.clientHeight)
+}
+
+function getBlockPadding(element) {
+  const style = window.getComputedStyle(element)
+
+  return {
+    end: readCssPixel(style.paddingBlockEnd || style.paddingBottom),
+    start: readCssPixel(style.paddingBlockStart || style.paddingTop)
+  }
+}
+
+/**
+ * Block padding of the spacer's parent (the content element); zeros
+ * without a spacer.
+ *
+ * @param {HTMLElement | null} spacer
+ * @returns {{ start: number, end: number }} px
+ */
+export function getContentBlockPadding(spacer) {
+  const content = spacer?.parentElement
+  if (!content) return { end: 0, start: 0 }
+
+  return getBlockPadding(content)
+}
+
+/**
+ * The element's effective row gap (0 for "normal" or no element).
+ *
+ * @param {HTMLElement | null} element
+ * @returns {number} px
+ */
+export function getFlexGap(element) {
+  if (!element) return 0
+
+  const style = window.getComputedStyle(element)
+  const gap = style.rowGap === "normal" ? style.gap : style.rowGap
+
+  return readCssPixel(gap)
+}
+
+function readCssPixel(value) {
+  if (!value) return 0
+
+  const number = Number.parseFloat(value)
+
+  return Number.isFinite(number) ? number : 0
+}
+
+/**
+ * Value equality for two scrollable snapshots.
+ *
+ * @param {{ start: boolean, end: boolean }} current
+ * @param {{ start: boolean, end: boolean }} next
+ * @returns {boolean}
+ */
+export function areScrollStatesEqual(current, next) {
+  return current.start === next.start && current.end === next.end
+}
+
+/**
+ * Value equality for two visibility snapshots (anchor + ordered ids).
+ *
+ * @param {{ currentAnchorId: string | null, visibleMessageIds: string[] }} current
+ * @param {{ currentAnchorId: string | null, visibleMessageIds: string[] }} next
+ * @returns {boolean}
+ */
+export function areVisibilityStatesEqual(current, next) {
+  if (current.currentAnchorId !== next.currentAnchorId) return false
+  if (current.visibleMessageIds.length !== next.visibleMessageIds.length) return false
+
+  return current.visibleMessageIds.every(
+    (messageId, index) => messageId === next.visibleMessageIds[index]
+  )
+}

data/app/javascript/poetry/core/helpers/state.js

@@ -0,0 +1,80 @@
+// The controllable-state convention (the DOM is the store): runtime
+// state is a set of presence-boolean data attributes - written here,
+// styled by CSS variants (data-open:..., via the vendored bridge
+// variants that also match the older data-state="open|closed" value
+// form), owned by whichever layer set it (a Stimulus Value default, the
+// DOM, the URL, or a server re-render).
+//
+// Keys are PAIRS (or triples): setting one member writes its attribute
+// and removes its counterparts. The negative popup/panel/pressed/selected
+// keys only remove, deliberately: there is no data-popup-closed -
+// absence IS the state.
+/** Vocabulary key -> its writes: { add: attribute | null, remove: [attributes] }. */
+export const VOCABULARY = {
+  open: { add: "data-open", remove: ["data-closed"] },
+  closed: { add: "data-closed", remove: ["data-open"] },
+  "popup-open": { add: "data-popup-open", remove: [] },
+  "popup-closed": { add: null, remove: ["data-popup-open"] },
+  "panel-open": { add: "data-panel-open", remove: [] },
+  "panel-closed": { add: null, remove: ["data-panel-open"] },
+  checked: { add: "data-checked", remove: ["data-unchecked", "data-indeterminate"] },
+  unchecked: { add: "data-unchecked", remove: ["data-checked", "data-indeterminate"] },
+  indeterminate: { add: "data-indeterminate", remove: ["data-checked", "data-unchecked"] },
+  pressed: { add: "data-pressed", remove: [] },
+  active: { add: "data-active", remove: [] },
+  inactive: { add: null, remove: ["data-active"] },
+  unpressed: { add: null, remove: ["data-pressed"] },
+  selected: { add: "data-selected", remove: [] },
+  unselected: { add: null, remove: ["data-selected"] }
+}
+
+// Derivation order: the open/closed pair first (the common ask), then the
+// checked family, then the bare booleans. Attribute-only "closed" states
+// (popup/panel/pressed/selected negatives) derive as undefined - callers
+// that care test the attribute directly (hasAttribute("data-popup-open")).
+const DERIVATION = [
+  ["data-open", "open"], ["data-closed", "closed"],
+  ["data-checked", "checked"], ["data-unchecked", "unchecked"],
+  ["data-indeterminate", "indeterminate"],
+  ["data-popup-open", "popup-open"], ["data-panel-open", "panel-open"],
+  ["data-pressed", "pressed"], ["data-selected", "selected"], ["data-active", "active"]
+]
+
+/**
+ * The vocabulary key `element` currently wears, per the derivation order
+ * above. Attribute-only negative states (the popup/panel/pressed/selected
+ * negatives) have no positive attribute to find and derive as undefined -
+ * callers that care test the attribute directly.
+ *
+ * @param {Element} element
+ * @returns {string | undefined}
+ */
+export function stateOf(element) {
+  for (const [attribute, key] of DERIVATION) {
+    if (element.hasAttribute(attribute)) return key
+  }
+  return undefined
+}
+
+/**
+ * Writes vocabulary key `key` onto `element`: sets its add-attribute (when
+ * the key has one), removes its counterparts, and announces the flip as a
+ * bubbling `poetry:state-change` CustomEvent carrying `{ state: key }`.
+ *
+ * @param {Element} element
+ * @param {string} key - a {@link VOCABULARY} key
+ * @returns {string} the key that was written
+ * @throws {Error} on a key outside the vocabulary
+ */
+export function setState(element, key) {
+  const writes = VOCABULARY[key]
+  if (!writes) throw new Error(`poetry state: unknown vocabulary key ${key}`)
+
+  if (writes.add) element.setAttribute(writes.add, "")
+  for (const attribute of writes.remove) element.removeAttribute(attribute)
+
+  element.dispatchEvent(
+    new CustomEvent("poetry:state-change", { detail: { state: key }, bubbles: true })
+  )
+  return key
+}

data/app/javascript/poetry/core/helpers/tabbable.js

@@ -0,0 +1,56 @@
+// Tabbable-candidate walk: the shared filter behind focus-scope and
+// the Dialog trap. Candidates in DOM order, minus disabled / hidden /
+// tabindex=-1 / inert-subtree elements.
+
+const CANDIDATE_SELECTOR = [
+  "a[href]",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "[tabindex]",
+  '[contenteditable="true"]',
+  "audio[controls]",
+  "video[controls]"
+].join(", ")
+
+/**
+ * The tabbable elements under `container`, in DOM order: candidate
+ * tags/tabindexes minus disabled / hidden / tabindex=-1 / inert-subtree /
+ * type=hidden elements, with each radio group collapsed to its single
+ * real tab stop (see below).
+ *
+ * @param {Element} container
+ * @returns {Element[]}
+ */
+export function tabbableWithin(container) {
+  const candidates = Array.from(container.querySelectorAll(CANDIDATE_SELECTOR)).filter(
+    (element) =>
+      !element.disabled &&
+      !element.hidden &&
+      element.getAttribute("tabindex") !== "-1" &&
+      element.closest("[inert]") === null &&
+      element.type !== "hidden"
+  )
+
+  return candidates.filter((element) => isRadioTabStop(element, candidates))
+}
+
+// A radio GROUP is one tab stop, not one per radio - the platform's own
+// Tab rule: the checked radio represents the group; an all-unchecked group is
+// represented by its first radio. Without this, a dialog trap treats every
+// radio as an edge candidate and Shift+Tab at the "first" tabbable is
+// wrong whenever a radio group sits at either end of the scope.
+function isRadioTabStop(element, candidates) {
+  if (element.type !== "radio" || !element.name) return true
+
+  const group = candidates.filter(
+    (candidate) =>
+      candidate.type === "radio" &&
+      candidate.name === element.name &&
+      candidate.form === element.form
+  )
+  const checked = group.find((candidate) => candidate.checked)
+
+  return checked ? element === checked : element === group[0]
+}

data/app/javascript/poetry/core/helpers/turbo_cache.js

@@ -0,0 +1,21 @@
+// Turbo snapshots the page BEFORE caching it (turbo:before-cache), and an
+// overlay still open at that moment serializes INTO the snapshot: the
+// restoration visit then renders a de-modalized zombie dialog (the open
+// attribute survives HTML serialization, top-layer/modal state does not)
+// over a body whose inline scroll-lock / pointer-events-scrim styles came
+// back frozen - a page that can never scroll, or never be clicked, again
+// (both reproduced live against the docs app). Overlay controllers
+// subscribe their synchronous teardown here; no-op when Turbo is absent.
+/**
+ * Subscribes `callback` to Turbo's before-cache moment - the last
+ * synchronous chance to tear an overlay down before the snapshot is
+ * taken. A page without Turbo simply never fires it.
+ *
+ * @param {(event: Event) => void} callback - must finish synchronously;
+ *   the snapshot is taken right after the event dispatch completes
+ * @returns {() => void} unsubscribe
+ */
+export function onBeforeCache(callback) {
+  document.addEventListener("turbo:before-cache", callback)
+  return () => document.removeEventListener("turbo:before-cache", callback)
+}

data/app/javascript/poetry/core/helpers/typeahead.js

@@ -0,0 +1,85 @@
+// The APG typeahead buffer, shared: printable keys accumulate into a
+// search buffer that resets after a timeout (1s default), matching wraps
+// from the current item, and a repeated same-letter buffer cycles matches.
+// Extracted VERBATIM from menu_controller.js so the menu family and the
+// Select listbox run the identical algorithm - the buffer/timer state
+// lives in the instance this factory returns, one per consuming
+// controller.
+
+/**
+ * The label an item types against: data-text-value overrides textContent
+ * (icon-rich content declares its typed label explicitly).
+ *
+ * @param {Element} item
+ * @returns {string} the trimmed label ("" when neither source exists)
+ */
+export function typeaheadLabel(item) {
+  return (item.dataset.textValue ?? item.textContent ?? "").trim()
+}
+
+/**
+ * One typeahead instance for a consuming controller - the buffer/timer
+ * state lives in the returned object (the module header holds the
+ * algorithm).
+ *
+ * @returns {{ pending: () => boolean, reset: () => void,
+ *   search: (key: string, items: Element[], options?: Object) => Element | null }}
+ */
+export function createTypeahead() {
+  let buffer = ""
+  let timer = null
+
+  return {
+    /**
+     * A live buffer means Space extends the search instead of activating.
+     * @returns {boolean}
+     */
+    pending() {
+      return buffer !== ""
+    },
+
+    /** Clears the buffer and cancels its reset timer. */
+    reset() {
+      window.clearTimeout(timer)
+      timer = null
+      buffer = ""
+    },
+
+    /**
+     * The match walk: a repeated same-letter buffer cycles matches;
+     * a growing buffer keeps the current item first so continued typing
+     * stays put while it still matches; single-letter search excludes the
+     * current item so it always advances. The consumer decides what a
+     * match means (menus focus it; a closed Select trigger commits it).
+     *
+     * @param {string} key - the printable key just typed
+     * @param {Element[]} items - ENABLED items only (disabled filtering
+     *   is the consumer's collection contract)
+     * @param {Object} [options]
+     * @param {Element | null} [options.active=null] - the item the walk
+     *   starts from
+     * @param {number} [options.timeout=1000] - ms before the buffer resets
+     * @param {(item: Element) => string} [options.labelOf=typeaheadLabel]
+     * @returns {Element | null} the matched item
+     */
+    search(key, items, { active = null, timeout = 1000, labelOf = typeaheadLabel } = {}) {
+      window.clearTimeout(timer)
+      timer = window.setTimeout(() => { buffer = "" }, timeout)
+      buffer += key
+
+      if (items.length === 0) return null
+
+      const repeated = buffer.length > 1 && Array.from(buffer).every((char) => char === buffer[0])
+      const search = (repeated ? buffer[0] : buffer).toLowerCase()
+      const currentIndex = Math.max(items.indexOf(active), 0)
+
+      let ordered = items.map((_, offset) => (currentIndex + offset) % items.length)
+
+      if (search.length === 1) ordered = ordered.filter((index) => items[index] !== active)
+
+      const match = ordered.find((index) => labelOf(items[index]).toLowerCase().startsWith(search))
+
+      return match === undefined ? null : items[match]
+    }
+  }
+}