poetry-core 0.0.2

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

@@ -0,0 +1,220 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The Autocomplete: a REAL text
+// input that IS the form value, suggesting from a server-rendered list
+// that filters as you type. This is the input-is-the-value semantic -
+// the sibling of Combobox, whose value is a SELECTED ITEM behind a
+// native <select>. Selecting a suggestion writes the input and closes;
+// the text always submits as ordinary params.
+//
+// The contract's fixed behaviors: locale-aware filtering
+// (toLocaleLowerCase), list scroll reset on every filter pass, and
+// change-reason details on the commit event (item-press | enter-key).
+// Positioning rides the shared popper controller (input = anchor).
+const ITEM_SELECTOR = '[data-slot="autocomplete-item"]'
+const EVENT_PREFIX = "poetry:autocomplete"
+
+export default class AutocompleteController extends Controller {
+  static events = ["poetry:autocomplete:commit", "poetry:autocomplete:open", "poetry:autocomplete:closed"]
+
+  static targets = ["input", "content", "list", "empty"]
+
+  static values = {
+    open: { type: Boolean, default: false },
+    // Open the popup on focus even before any typing.
+    openOnFocus: { type: Boolean, default: true }
+  }
+
+  /** Closes an open popup so its state never outlives the controller. */
+  disconnect() {
+    if (this.openValue) this.#close()
+  }
+
+  // --- input events --------------------------------------------------------
+
+  /** The input action: re-filters the list and opens. */
+  input() {
+    this.#filter()
+    if (!this.openValue) this.#open()
+  }
+
+  /** The focus action: opens pre-typing when openOnFocus allows. */
+  focus() {
+    if (this.openOnFocusValue && !this.openValue) {
+      this.#filter()
+      this.#open()
+    }
+  }
+
+  /**
+   * The focusout action: closes, unless focus moved into the popup (an
+   * item click commits first - the body comment).
+   *
+   * @param {FocusEvent} event
+   */
+  blurred(event) {
+    // Focus moving into the popup (a click on an item) must not close
+    // before the click commits - the item's pointerdown commits first.
+    if (event.relatedTarget instanceof Element && this.element.contains(event.relatedTarget)) return
+
+    if (this.openValue) this.#close()
+  }
+
+  /**
+   * The input's keydown action: arrows open / move the highlight, Enter
+   * commits it, Escape closes (consumed - the next press reaches the
+   * layer above), Tab closes and passes through. IME keydowns are
+   * ignored.
+   *
+   * @param {KeyboardEvent} event
+   */
+  keydown(event) {
+    if (event.isComposing || event.keyCode === 229) return
+
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowUp": {
+        event.preventDefault()
+        if (!this.openValue) return this.#open()
+
+        this.#moveHighlight(event.key === "ArrowDown" ? 1 : -1)
+        break
+      }
+      case "Enter": {
+        const highlighted = this.#highlighted()
+        if (!this.openValue || !highlighted) return
+
+        event.preventDefault()
+        this.#commit(highlighted, "enter-key")
+        break
+      }
+      case "Escape": {
+        if (!this.openValue) return
+
+        event.preventDefault()
+        event.stopPropagation() // consumed: this press closes; the next reaches the layer above
+        this.#close()
+        break
+      }
+      case "Tab": {
+        if (this.openValue) this.#close()
+        break
+      }
+    }
+  }
+
+  /**
+   * Each item's pointerdown action (not click): commits BEFORE the
+   * input's blur closes the popup.
+   *
+   * @param {PointerEvent} event
+   */
+  itemPress(event) {
+    const item = event.target.closest(ITEM_SELECTOR)
+    if (!item || item.hasAttribute("data-disabled")) return
+
+    event.preventDefault() // keep focus on the input
+    this.#commit(item, "item-press")
+  }
+
+  /**
+   * Each item's pointerenter action: moves the highlight under the
+   * pointer.
+   *
+   * @param {PointerEvent} event
+   */
+  itemEnter(event) {
+    const item = event.target.closest(ITEM_SELECTOR)
+    if (!item || item.hasAttribute("data-disabled")) return
+
+    this.#setHighlight(item)
+  }
+
+  // --- internals -----------------------------------------------------------
+
+  #items() {
+    return [...this.listTarget.querySelectorAll(ITEM_SELECTOR)]
+  }
+
+  #visibleItems() {
+    return this.#items().filter((item) => !item.hidden && !item.hasAttribute("data-disabled"))
+  }
+
+  #highlighted() {
+    return this.#items().find((item) => item.hasAttribute("data-highlighted") && !item.hidden)
+  }
+
+  #filter() {
+    const query = this.inputTarget.value.trim().toLocaleLowerCase()
+    let any = false
+
+    this.#items().forEach((item) => {
+      const label = (item.dataset.label || item.textContent).trim().toLocaleLowerCase()
+      const match = query === "" || label.includes(query)
+      item.hidden = !match
+      any ||= match
+    })
+
+    // The list scroll resets on every filter pass - a stale scroll
+    // position over fresh results misleads.
+    this.listTarget.scrollTop = 0
+    this.#syncEmpty(any)
+    this.#clearHighlight()
+  }
+
+  #syncEmpty(any) {
+    if (this.hasEmptyTarget) this.emptyTarget.hidden = any
+    this.contentTarget.toggleAttribute("data-empty", !any)
+  }
+
+  #moveHighlight(direction) {
+    const items = this.#visibleItems()
+    if (items.length === 0) return
+
+    const current = items.indexOf(this.#highlighted())
+    const next = current === -1
+      ? (direction > 0 ? 0 : items.length - 1)
+      : (current + direction + items.length) % items.length
+    this.#setHighlight(items[next])
+  }
+
+  #setHighlight(item) {
+    this.#clearHighlight()
+    item.setAttribute("data-highlighted", "")
+    this.inputTarget.setAttribute("aria-activedescendant", item.id)
+    item.scrollIntoView({ block: "nearest" })
+  }
+
+  #clearHighlight() {
+    this.#items().forEach((item) => item.removeAttribute("data-highlighted"))
+    this.inputTarget.removeAttribute("aria-activedescendant")
+  }
+
+  #commit(item, reason) {
+    this.inputTarget.value = item.dataset.value ?? (item.dataset.label || item.textContent.trim())
+    this.inputTarget.dispatchEvent(new Event("input", { bubbles: true }))
+    this.inputTarget.dispatchEvent(new Event("change", { bubbles: true }))
+    this.dispatch("commit", { prefix: EVENT_PREFIX, detail: { value: this.inputTarget.value, reason } })
+    this.#close()
+    this.inputTarget.focus()
+  }
+
+  #open() {
+    this.openValue = true
+    this.contentTarget.hidden = false
+    this.contentTarget.setAttribute("data-open", "")
+    this.contentTarget.removeAttribute("data-closed")
+    this.inputTarget.setAttribute("aria-expanded", "true")
+    this.dispatch("open", { prefix: EVENT_PREFIX })
+  }
+
+  #close() {
+    this.openValue = false
+    this.contentTarget.hidden = true
+    this.contentTarget.removeAttribute("data-open")
+    this.contentTarget.setAttribute("data-closed", "")
+    this.inputTarget.setAttribute("aria-expanded", "false")
+    this.#clearHighlight()
+    this.dispatch("closed", { prefix: EVENT_PREFIX })
+  }
+}

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

@@ -0,0 +1,406 @@
+import { Controller } from "@hotwired/stimulus"
+
+// The Calendar engine, decided OWN-THE-ENGINE: no date-picker library
+// (a heavy JS dep). The month grid is SERVER-RENDERED (Ruby Date math) so a
+// no-JS page shows a valid calendar; this controller adds month navigation
+// (regenerating the 42-cell grid from plain Date math - reusing the day
+// button DOM, no innerHTML churn), single-date selection (writing the
+// hidden input + the data-selected/aria vocabulary), and roving arrow-key
+// focus over the days. Selection is a real form value; the DatePicker
+// composes this inside a Popover.
+//
+// Range mode: mode="range" swaps the click path for a
+// transcription of an MIT-licensed range-selection algorithm (source and
+// license in THIRD_PARTY_NOTICES.md) and the reflection
+// for the range vocabulary (data-range-start/middle/end - dictionary
+// classes that shipped inert until range mode). The form value is TWO
+// hidden inputs (name[start]/name[end] - the wire shape is poetry's).
+// The transcribed semantics hold exactly: an incomplete
+// start-only pick renders as a plain selected single day; the range
+// vocabulary appears only once the range completes.
+//
+// Dropdown caption (caption_layout: :dropdown), the invisible-select overlay
+// pattern: each [data-calendar-unit=month|year] wrapper holds a visible
+// text label (calendar-dropdown-value) with the real select stretched
+// invisibly over it - #jump reads the selects, #render reflects
+// navigation back into both select values AND label text (no caption
+// target in that mode). Week numbers: one role=rowheader per week; each
+// row's Thursday decides the ISO number (matches Ruby Date#cweek under
+// any week_start).
+//
+// Still deferred: multiple months.
+const DAY_SELECTOR = '[data-slot="calendar-day"]'
+const MS_PER_DAY = 86400000
+
+// The component-facing event namespace (the poetry:<component> rule).
+const EVENT_PREFIX = "poetry:calendar"
+
+export default class CalendarController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry:calendar:change"]
+
+  static targets = ["grid", "caption", "input", "startInput", "endInput", "day"]
+  static values = {
+    month: String, // the visible month, "YYYY-MM"
+    selected: String, // the chosen date, "YYYY-MM-DD" (or "")
+    mode: { type: String, default: "single" }, // "single" | "range"
+    rangeStart: String, // "YYYY-MM-DD" (or "")
+    rangeEnd: String,
+    weekStart: { type: Number, default: 0 }, // 0 = Sunday
+    min: String,
+    max: String,
+    // The localized month names, handed down by the SERVER (Ruby I18n) so
+    // the JS caption needs no Intl - correct under app locale AND in the
+    // Intl-less dommy engine. English is the fallback.
+    monthNames: {
+      type: Array,
+      default: ["January", "February", "March", "April", "May", "June",
+                "July", "August", "September", "October", "November", "December"]
+    }
+  }
+
+  #today = null
+  #booted = false
+
+  /** Syncs the selected/today vocabulary over the server-rendered grid. */
+  connect() {
+    // The server rendered the initial month correctly; just sync the
+    // selected/today vocabulary in case selected was set programmatically.
+    this.#reflectSelection()
+    this.#booted = true
+  }
+
+  /** The previous-month button's click action. */
+  previousMonth() {
+    this.#goTo(this.#shiftMonth(-1))
+  }
+
+  /** The next-month button's click action. */
+  nextMonth() {
+    this.#goTo(this.#shiftMonth(1))
+  }
+
+  /**
+   * The dropdown caption's change action (the month/year select
+   * wrappers): navigates to the selects' month.
+   */
+  jump() {
+    const read = (unit) => this.element.querySelector(`[data-calendar-unit="${unit}"] select`)?.value
+    const month = read("month")
+    const year = read("year")
+
+    if (!month || !year) return
+
+    this.#goTo(`${year}-${String(month).padStart(2, "0")}`)
+  }
+
+  /**
+   * Each day button's click action: single mode writes the selection;
+   * range mode runs the addToRange transcription. The change event
+   * carries value (single) or start/end (range) as ISO strings.
+   *
+   * @param {MouseEvent} event
+   */
+  select(event) {
+    const button = event.target.closest(DAY_SELECTOR)
+    if (!button || button.disabled) return
+
+    if (this.modeValue === "range") {
+      this.#addToRange(button.dataset.date)
+      this.#reflectSelection()
+      this.dispatch("change", { prefix: EVENT_PREFIX, detail: { start: this.rangeStartValue, end: this.rangeEndValue } })
+      return
+    }
+
+    this.selectedValue = button.dataset.date
+    this.#reflectSelection()
+    this.dispatch("change", { prefix: EVENT_PREFIX, detail: { value: this.selectedValue } })
+  }
+
+  // The transcribed range-selection algorithm (ISO strings compare
+  // lexicographically, so <,> are date order).
+  #addToRange(clicked) {
+    const start = this.rangeStartValue
+    const end = this.rangeEndValue
+
+    if (!start) {
+      this.rangeStartValue = clicked
+      this.rangeEndValue = ""
+      return
+    }
+    if (!end) {
+      if (clicked === start) this.rangeEndValue = clicked // re-click completes the single-day range
+      else if (clicked < start) {
+        this.rangeStartValue = clicked
+        this.rangeEndValue = start
+      } else this.rangeEndValue = clicked
+      return
+    }
+    // A complete range:
+    if (clicked === start && clicked === end) {
+      this.rangeStartValue = "" // re-click the single-day range clears it
+      this.rangeEndValue = ""
+    } else if (clicked === start) {
+      this.rangeEndValue = clicked // collapse onto the start
+    } else if (clicked === end) {
+      this.rangeStartValue = clicked // restart from the end
+      this.rangeEndValue = ""
+    } else if (clicked < start) {
+      this.rangeStartValue = clicked // extend backward
+    } else {
+      this.rangeEndValue = clicked // move the end
+    }
+  }
+
+  /**
+   * The grid's keydown action: arrows move focus by day/week, PageUp/Down
+   * by month, Home/End to the week edges.
+   *
+   * @param {KeyboardEvent} event
+   */
+  keydown(event) {
+    const current = event.target.closest(DAY_SELECTOR)
+    if (!current) return
+
+    const delta = {
+      ArrowLeft: -1, ArrowRight: 1, ArrowUp: -7, ArrowDown: 7,
+      Home: "week-start", End: "week-end"
+    }[event.key]
+
+    if (event.key === "PageUp") { event.preventDefault(); return this.previousMonth() }
+    if (event.key === "PageDown") { event.preventDefault(); return this.nextMonth() }
+    if (delta === undefined) return
+
+    event.preventDefault()
+    const date = this.#parse(current.dataset.date)
+
+    let target
+    if (delta === "week-start") target = this.#addDays(date, -this.#weekdayIndex(date))
+    else if (delta === "week-end") target = this.#addDays(date, 6 - this.#weekdayIndex(date))
+    else target = this.#addDays(date, delta)
+
+    this.#focusDate(target)
+  }
+
+  // Move focus to a date, crossing a month boundary by re-rendering first.
+  // A disabled (out-of-range) target is a WALL, not a landing spot: min/max
+  // is the only disabled source and it is contiguous, so navigation simply
+  // refuses - focus() on a disabled button is a silent no-op, and stamping
+  // it as the roving stop would leave the grid with no working Tab entry.
+  #focusDate(date) {
+    const iso = this.#iso(date)
+
+    if (this.#outOfRange(iso)) return
+
+    if (this.#monthOf(date) !== this.monthValue) {
+      this.monthValue = this.#monthOf(date)
+      this.#render()
+    }
+    const button = this.dayTargets.find((day) => day.dataset.date === iso)
+    button?.focus()
+    this.#rovingStop(button)
+  }
+
+  #goTo(month) {
+    this.monthValue = month
+    this.#render()
+  }
+
+  /**
+   * Stimulus value callback. The DOM is the store (the anchor-point
+   * precedent): external writes to selected/month - the DatePicker input
+   * variant syncs typed dates this way - re-render on change. The booted
+   * gate skips the init echo (the server's own paint - Stimulus fires
+   * initial value callbacks BEFORE connect, and a connect-era render
+   * would restamp data-today with the client clock over the server's
+   * pinned one). Internal writes re-render once more; the in-place cell
+   * diff makes that free.
+   */
+  selectedValueChanged() {
+    if (this.#booted) this.#render()
+  }
+
+  /** Stimulus value callback: re-renders on external month writes (see above). */
+  monthValueChanged() {
+    if (this.#booted) this.#render()
+  }
+
+  // Rewrite the day buttons for the visible month IN PLACE (42 cells,
+  // stable layout) - date/label/outside/today/disabled/selected. Reuses
+  // the existing button DOM; only cells that changed are touched.
+  #render() {
+    const cells = this.#buildMonth()
+
+    this.dayTargets.forEach((button, index) => {
+      const cell = cells[index]
+      const iso = this.#iso(cell.date)
+
+      button.dataset.date = iso
+      button.querySelector("[data-slot=calendar-day-label]").textContent = String(cell.date.getUTCDate())
+      this.#toggle(button, "data-outside", cell.outside)
+      this.#toggle(button, "data-today", iso === this.#todayIso())
+      button.disabled = this.#outOfRange(iso)
+    })
+
+    if (this.hasCaptionTarget) this.captionTarget.textContent = this.#captionText()
+    this.#reflectDropdowns()
+    this.#reflectWeekNumbers(cells)
+    this.#reflectSelection()
+  }
+
+  // The dropdown caption follows navigation (prev/next must move the
+  // selects too, not just the grid). The visible label span mirrors the
+  // select (the overlay pattern: the select is invisible on top).
+  #reflectDropdowns() {
+    const [year, month] = this.monthValue.split("-").map(Number)
+
+    for (const wrapper of this.element.querySelectorAll("[data-calendar-unit]")) {
+      const monthly = wrapper.dataset.calendarUnit === "month"
+      const select = wrapper.querySelector("select")
+      const label = wrapper.querySelector("[data-slot=\"calendar-dropdown-value\"]")
+
+      if (select) select.value = String(monthly ? month : year)
+      if (label) label.textContent = monthly ? this.monthNamesValue[month - 1] : String(year)
+    }
+  }
+
+  // One rowheader per week; the row's Thursday decides the ISO number
+  // (mirrors Ruby's Date#cweek, stable under any week_start).
+  #reflectWeekNumbers(cells) {
+    const numbers = this.element.querySelectorAll('[role="rowheader"][data-slot="calendar-week-number"]')
+
+    numbers.forEach((cell, row) => {
+      const thursday = cells.slice(row * 7, row * 7 + 7).find((c) => c.date.getUTCDay() === 4)
+
+      cell.textContent = String(this.#isoWeek(thursday.date))
+    })
+  }
+
+  #isoWeek(thursday) {
+    const yearStart = Date.UTC(thursday.getUTCFullYear(), 0, 1)
+    const dayOfYear = (thursday.getTime() - yearStart) / MS_PER_DAY + 1
+
+    return Math.ceil(dayOfYear / 7)
+  }
+
+  #reflectSelection() {
+    if (this.modeValue === "range") {
+      this.#reflectRange()
+      return
+    }
+    for (const button of this.dayTargets) {
+      const selected = button.dataset.date === this.selectedValue && this.selectedValue !== ""
+
+      this.#toggle(button, "data-selected", selected)
+      // aria-selected belongs on the role=gridcell parent, not the button
+      // (the ARIA grid contract; a plain button can't carry aria-selected).
+      button.closest('[role="gridcell"]')?.setAttribute("aria-selected", selected ? "true" : "false")
+      this.#reflectToday(button)
+    }
+    if (this.hasInputTarget) this.inputTarget.value = this.selectedValue ?? ""
+  }
+
+  // The range vocabulary: the span wears range-start /
+  // range-middle / range-end only once COMPLETE; a start-only pick is a
+  // plain selected single day. Survives month nav because it re-derives
+  // from every visible button's date (a span may extend offscreen).
+  #reflectRange() {
+    const start = this.rangeStartValue || ""
+    const end = this.rangeEndValue || ""
+    const complete = start !== "" && end !== ""
+
+    for (const button of this.dayTargets) {
+      const iso = button.dataset.date
+      const inSpan = complete ? iso >= start && iso <= end : start !== "" && iso === start
+
+      this.#toggle(button, "data-selected", !complete && start !== "" && iso === start)
+      this.#toggle(button, "data-range-start", complete && iso === start)
+      this.#toggle(button, "data-range-end", complete && iso === end)
+      this.#toggle(button, "data-range-middle", complete && iso > start && iso < end)
+      button.closest('[role="gridcell"]')?.setAttribute("aria-selected", inSpan ? "true" : "false")
+      this.#reflectToday(button)
+    }
+    if (this.hasStartInputTarget) this.startInputTarget.value = start
+    if (this.hasEndInputTarget) this.endInputTarget.value = end
+  }
+
+  #reflectToday(button) {
+    if (button.dataset.date === this.#todayIso()) button.setAttribute("aria-current", "date")
+    else button.removeAttribute("aria-current")
+  }
+
+  // Exactly one day is the tab stop (the roving contract): the selected
+  // day, else today in view, else the first enabled day.
+  #rovingStop(preferred) {
+    const anchor = this.modeValue === "range" ? this.rangeStartValue : this.selectedValue
+    const stop = preferred
+      || this.dayTargets.find((d) => d.dataset.date === anchor)
+      || this.dayTargets.find((d) => d.dataset.date === this.#todayIso())
+      || this.dayTargets.find((d) => !d.disabled)
+
+    for (const day of this.dayTargets) day.setAttribute("tabindex", day === stop ? "0" : "-1")
+  }
+
+  // --- date math (UTC, so DST never shifts a day) --------------------------
+
+  #buildMonth() {
+    const [year, month] = this.monthValue.split("-").map(Number)
+    const first = new Date(Date.UTC(year, month - 1, 1))
+    const lead = (first.getUTCDay() - this.weekStartValue + 7) % 7
+    const start = this.#addDays(first, -lead)
+
+    return Array.from({ length: 42 }, (_, index) => {
+      const date = this.#addDays(start, index)
+      return { date, outside: date.getUTCMonth() !== month - 1 }
+    })
+  }
+
+  #captionText() {
+    const [year, month] = this.monthValue.split("-").map(Number)
+    return `${this.monthNamesValue[month - 1]} ${year}`
+  }
+
+  #shiftMonth(by) {
+    const [year, month] = this.monthValue.split("-").map(Number)
+    const date = new Date(Date.UTC(year, month - 1 + by, 1))
+    return this.#monthOf(date)
+  }
+
+  #outOfRange(iso) {
+    if (this.minValue && iso < this.minValue) return true
+    if (this.maxValue && iso > this.maxValue) return true
+    return false
+  }
+
+  #addDays(date, days) {
+    return new Date(date.getTime() + days * MS_PER_DAY)
+  }
+
+  #weekdayIndex(date) {
+    return (date.getUTCDay() - this.weekStartValue + 7) % 7
+  }
+
+  #parse(iso) {
+    const [year, month, day] = iso.split("-").map(Number)
+    return new Date(Date.UTC(year, month - 1, day))
+  }
+
+  #iso(date) {
+    return date.toISOString().slice(0, 10)
+  }
+
+  #monthOf(date) {
+    return this.#iso(date).slice(0, 7)
+  }
+
+  #todayIso() {
+    this.#today ??= this.#iso(new Date())
+    return this.#today
+  }
+
+  #toggle(element, attribute, on) {
+    if (on) element.setAttribute(attribute, "")
+    else element.removeAttribute(attribute)
+  }
+}