poetry-core 0.0.2

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

@@ -0,0 +1,65 @@
+// The composed-DOM duplicate-id tripwire: the ONLY
+// check that sees the page as actually composed - static lints can't see
+// across templates, frames, streams, or cached fragments, so this scans
+// the live document for duplicate [id] values after every composition
+// event and reports what it finds. Development tooling: install via
+// poetry_id_integrity_script (dev layouts); never wired in production.
+//
+// Duplicate ids are always a bug regardless of source (ARIA IDREFs
+// resolve to the first match only), and under StableId they are the
+// signature of the two documented hazards: the same key rendered twice,
+// or sequence-mode collisions across frames/cached fragments.
+
+/**
+ * Scans the live (composed) document for duplicate [id] values.
+ *
+ * @param {ParentNode} [root=document]
+ * @returns {string[]} the duplicated ids, each listed once ("" ignored)
+ */
+export function scanForDuplicateIds(root = document) {
+  const seen = new Set()
+  const dups = new Set()
+  root.querySelectorAll("[id]").forEach((el) => {
+    if (el.id === "") return
+    if (seen.has(el.id)) dups.add(el.id)
+    seen.add(el.id)
+  })
+  return [...dups]
+}
+
+/**
+ * Installs the scanner on the page's composition events (initial load,
+ * Turbo loads, frame loads, morphs, stream insertions - each checked one
+ * frame after the event so the DOM has settled).
+ *
+ * @param {Object} [options]
+ * @param {(dups: string[]) => void} [options.report] - overrides the
+ *   console warning
+ * @returns {() => string[]} the scan trigger, for manual use
+ */
+export function installPoetryIdIntegrityCheck({ report } = {}) {
+  const notify = report || ((dups) => {
+    console.warn(
+      `[poetry] duplicate DOM ids in the composed page: ${dups.join(", ")} - ` +
+        "ARIA references resolve to the first match only. Same key: twice, " +
+        "or sequence-mode ids colliding across frames/cached fragments?"
+    )
+  })
+  const scan = () => {
+    const dups = scanForDuplicateIds()
+    if (dups.length > 0) notify(dups)
+    return dups
+  }
+  const settle = () => requestAnimationFrame(scan)
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", settle, { once: true })
+  } else {
+    settle()
+  }
+  ;["turbo:load", "turbo:frame-load", "turbo:morph", "turbo:before-stream-render"].forEach((event) => {
+    document.addEventListener(event, settle)
+  })
+
+  return scan
+}

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

@@ -0,0 +1,328 @@
+// The nullable-segment date/time value (the IncompleteDate model, adapted
+// from an Apache-2.0-licensed source - source and license in
+// THIRD_PARTY_NOTICES.md): segments
+// are stored RAW so a user can edit day before
+// month - the object can hold February 31st and only commit constrains.
+// Hour is stored in the LOCALE'S HOUR CYCLE with a separate dayPeriod bit
+// (0 = AM, 1 = PM), so am/pm edits are independent and "12 means 0" lives
+// in exactly one place. Gregorian-only by design (the calendar seam is
+// clean if that ever changes - limits() is the only calendar knowledge).
+
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+
+/** PageUp/PageDown step per segment type. */
+export const PAGE_STEP = { year: 5, month: 2, day: 7, hour: 2, minute: 15, second: 15 }
+
+/**
+ * Days in a Gregorian month, leap Februaries included.
+ *
+ * @param {number} year
+ * @param {number} month - 1-12 (out-of-range months report 31)
+ * @returns {number}
+ */
+export function daysInMonth(year, month) {
+  if (month === 2 && year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)) return 29
+
+  return DAYS_IN_MONTH[month - 1] ?? 31
+}
+
+function pad(number, width = 2) {
+  return String(number).padStart(width, "0")
+}
+
+/**
+ * A date/time value whose segments may each be null (the module header
+ * holds the storage rules). One instance backs one date-field.
+ */
+export class IncompleteDate {
+  /**
+   * @param {"h11" | "h12" | "h23" | "h24"} [hourCycle="h23"] - the
+   *   field's RESOLVED cycle ({@link resolveHourCycle})
+   */
+  constructor(hourCycle = "h23") {
+    this.hourCycle = hourCycle
+    this.year = null
+    this.month = null
+    this.day = null
+    this.hour = null // stored in the display cycle, NOT h23
+    this.minute = null
+    this.second = null
+    this.dayPeriod = null // 0 | 1 | null; only meaningful under h11/h12
+  }
+
+  /** @returns {boolean} whether the cycle carries a dayPeriod (h11/h12) */
+  get twelveHour() {
+    return this.hourCycle === "h11" || this.hourCycle === "h12"
+  }
+
+  /**
+   * Segment limits in DISPLAY terms. Day deliberately allows the calendar
+   * maximum (31) regardless of the month segment - editing order must not
+   * trap the user; constrain() clamps at commit.
+   *
+   * @param {string} type - "year" | "month" | "day" | "hour" | "minute" |
+   *   "second" | "dayPeriod"
+   * @returns {{ min: number, max: number }}
+   */
+  limits(type) {
+    switch (type) {
+      case "year": return { min: 1, max: 9999 }
+      case "month": return { min: 1, max: 12 }
+      case "day": return { min: 1, max: 31 }
+      case "minute":
+      case "second": return { min: 0, max: 59 }
+      case "dayPeriod": return { min: 0, max: 1 }
+      case "hour":
+        switch (this.hourCycle) {
+          case "h11": return { min: 0, max: 11 }
+          case "h12": return { min: 1, max: 12 }
+          case "h24": return { min: 1, max: 24 }
+          default: return { min: 0, max: 23 }
+        }
+      default: return { min: 0, max: 0 }
+    }
+  }
+
+  /**
+   * Arrow/page steps a segment. The first press on an EMPTY segment lands
+   * on the placeholder value, the second one moves it (the cycle
+   * contract); values wrap within the segment's limits (the spinbutton
+   * contract).
+   *
+   * @param {string} type - the segment
+   * @param {number} amount - signed step
+   * @param {number} placeholderValue - what an empty segment lands on
+   * @param {Object} [options]
+   * @param {boolean} [options.round=false] - PageUp/Down snap to the next
+   *   multiple of amount instead of adding it
+   */
+  cycle(type, amount, placeholderValue, { round = false } = {}) {
+    const { min, max } = this.limits(type)
+    const current = this[type]
+
+    if (current === null) {
+      this[type] = clampToLimits(placeholderValue, min, max)
+      return
+    }
+
+    if (type === "dayPeriod") {
+      this.dayPeriod = current === 0 ? 1 : 0
+      return
+    }
+
+    let next
+
+    if (round) {
+      const step = Math.abs(amount)
+
+      next = amount > 0
+        ? Math.floor(current / step) * step + step
+        : Math.ceil(current / step) * step - step
+    } else {
+      next = current + amount
+    }
+
+    // Wrap (the spinbutton contract), keeping the span inclusive.
+    const span = max - min + 1
+    next = ((next - min) % span + span) % span + min
+
+    this[type] = next
+  }
+
+  /**
+   * Sets a segment, clamped to its limits.
+   *
+   * @param {string} type
+   * @param {number | null} value - null clears
+   */
+  set(type, value) {
+    const { min, max } = this.limits(type)
+
+    this[type] = value === null ? null : clampToLimits(value, min, max)
+  }
+
+  /**
+   * Empties a segment.
+   * @param {string} type
+   */
+  clear(type) {
+    this[type] = null
+  }
+
+  /**
+   * Whether every listed segment holds a value.
+   *
+   * @param {string[]} types
+   * @returns {boolean}
+   */
+  isComplete(types) {
+    return types.every((type) => this[type] !== null)
+  }
+
+  /**
+   * A complete date can still be invalid (February 31st): valid means the
+   * day exists in the month.
+   *
+   * @returns {boolean} false while year/month/day are incomplete
+   */
+  isValidDate() {
+    if (this.year === null || this.month === null || this.day === null) return false
+
+    return this.day <= daysInMonth(this.year, this.month)
+  }
+
+  /**
+   * Commit-time clamp (blur): the raw day is pulled into the real month.
+   *
+   * @param {string[]} types - the field's segments; day is only clamped
+   *   when listed
+   */
+  constrain(types) {
+    if (types.includes("day") && this.year !== null && this.month !== null && this.day !== null) {
+      this.day = Math.min(this.day, daysInMonth(this.year, this.month))
+    }
+  }
+
+  // --- hour-cycle conversion (the ONE place "12 means 0" lives) ---
+
+  /**
+   * The stored hour converted to h23. Under h11/h12 an unset dayPeriod
+   * reads as AM.
+   *
+   * @returns {number | null} null while the hour is unset
+   */
+  hourInH23() {
+    if (this.hour === null) return null
+
+    switch (this.hourCycle) {
+      case "h11":
+        return this.hour + (this.dayPeriod === 1 ? 12 : 0)
+      case "h12": {
+        const base = this.hour % 12
+        return base + (this.dayPeriod === 1 ? 12 : 0)
+      }
+      case "h24":
+        return this.hour % 24
+      default:
+        return this.hour
+    }
+  }
+
+  /**
+   * Sets hour (and dayPeriod under h11/h12) from an h23 hour.
+   * @param {number} h23 - 0-23
+   */
+  setFromH23(h23) {
+    switch (this.hourCycle) {
+      case "h11":
+        this.hour = h23 % 12
+        this.dayPeriod = h23 < 12 ? 0 : 1
+        break
+      case "h12":
+        this.hour = h23 % 12 === 0 ? 12 : h23 % 12
+        this.dayPeriod = h23 < 12 ? 0 : 1
+        break
+      case "h24":
+        this.hour = h23 === 0 ? 24 : h23
+        break
+      default:
+        this.hour = h23
+    }
+  }
+
+  // --- ISO serialization (the native input's value format) ---
+
+  /** @returns {string | null} "YYYY-MM-DD", or null while incomplete */
+  toISODate() {
+    if (!this.isComplete(["year", "month", "day"])) return null
+
+    return `${pad(this.year, 4)}-${pad(this.month)}-${pad(this.day)}`
+  }
+
+  /**
+   * @param {boolean} [withSeconds=false]
+   * @returns {string | null} "HH:MM" or "HH:MM:SS" (h23 on the wire), or
+   *   null while incomplete (a twelve-hour cycle needs dayPeriod too)
+   */
+  toISOTime(withSeconds = false) {
+    const types = withSeconds ? ["hour", "minute", "second"] : ["hour", "minute"]
+
+    if (this.twelveHour && this.dayPeriod === null) return null
+    if (!this.isComplete(types)) return null
+
+    const h23 = this.hourInH23()
+    const base = `${pad(h23)}:${pad(this.minute)}`
+
+    return withSeconds ? `${base}:${pad(this.second)}` : base
+  }
+
+  /**
+   * Fills year/month/day from "YYYY-MM-DD".
+   *
+   * @param {string | null} iso
+   * @returns {boolean} false (nothing touched) on a non-matching string
+   */
+  setFromISODate(iso) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso ?? "")
+
+    if (!match) return false
+
+    this.year = Number(match[1])
+    this.month = Number(match[2])
+    this.day = Number(match[3])
+    return true
+  }
+
+  /**
+   * Fills hour/minute(/second) from "HH:MM(:SS)" (h23 on the wire).
+   *
+   * @param {string | null} iso
+   * @returns {boolean} false (nothing touched) on a non-matching string
+   */
+  setFromISOTime(iso) {
+    const match = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(iso ?? "")
+
+    if (!match) return false
+
+    this.setFromH23(Number(match[1]))
+    this.minute = Number(match[2])
+    this.second = match[3] === undefined ? null : Number(match[3])
+    return true
+  }
+}
+
+function clampToLimits(value, min, max) {
+  return Math.min(max, Math.max(min, value))
+}
+
+/**
+ * The resolved hour cycle for a locale, with two known Intl bug
+ * detections built in: Chrome resolves `hour12: false` to the buggy h24
+ * per the ECMA-402 spec bug, and WebKit misreports
+ * resolvedOptions().hourCycle in some locales - so the cycle is INFERRED
+ * by formatting hour 0 and hour 23 and reading what comes out.
+ *
+ * @param {string | undefined} locale
+ * @param {"h11" | "h12" | "h23" | "h24" | null} [override=null] - wins
+ *   outright when present
+ * @returns {"h11" | "h12" | "h23" | "h24"}
+ */
+export function resolveHourCycle(locale, override = null) {
+  if (override) return override
+
+  const formatter = new Intl.DateTimeFormat(locale, { hour: "numeric" })
+  const hourAt = (hour) => {
+    const parts = formatter.formatToParts(new Date(2020, 0, 1, hour))
+
+    return {
+      value: Number(parts.find((part) => part.type === "hour")?.value ?? NaN),
+      dayPeriod: parts.some((part) => part.type === "dayPeriod")
+    }
+  }
+  const midnight = hourAt(0)
+  const evening = hourAt(23)
+
+  if (midnight.dayPeriod || evening.dayPeriod) return midnight.value === 0 ? "h11" : "h12"
+
+  return midnight.value === 0 || evening.value === 23 ? "h23" : "h24"
+}

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

@@ -0,0 +1,283 @@
+// The mask engine, adapted from an MIT-licensed source (source and
+// license in THIRD_PARTY_NOTICES.md).
+// Pure functions over a parsed slot list, zero DOM. A mask is a sequence of
+// slots: token slots
+// validate ONE character against a pattern, literal slots are fixed chrome
+// ("/", "-", " ") the engine inserts and the user never types. Every value
+// decision lives here so it stays exhaustively unit-testable; the caret
+// math and events live in mask_controller.js.
+
+/** The default token map: mask char -> the pattern one input char must match. */
+export const DEFAULT_TOKENS = {
+  "9": /[0-9]/,
+  a: /[A-Za-z]/,
+  A: /[A-Z]/,
+  "*": /[A-Za-z0-9]/,
+  "#": /[-+0-9]/
+}
+
+/**
+ * Parses a mask into a slot list. String grammar: token chars from the
+ * (custom-over-default merged) token map, "\" escapes the next char to a
+ * literal, "?" is consumed and makes every LATER slot optional - the flag
+ * is STICKY, it never resets, so "(999) 999-9999? x9999" is complete
+ * without the extension. Array grammar: RegExp item = token slot, string
+ * item = literal.
+ *
+ * @param {string | Array<RegExp | string>} mask
+ * @param {Object<string, RegExp>} [tokens={}] - custom tokens, merged
+ *   over {@link DEFAULT_TOKENS}
+ * @returns {Array<Object>} slots: { type: "token" | "literal", char,
+ *   pattern?, optional? }
+ */
+export function parseMask(mask, tokens = {}) {
+  if (Array.isArray(mask)) {
+    return mask.map((item) =>
+      item instanceof RegExp
+        ? { type: "token", char: "_", pattern: item }
+        : { type: "literal", char: item }
+    )
+  }
+
+  const map = { ...DEFAULT_TOKENS, ...tokens }
+  const slots = []
+  let optional = false
+
+  for (let i = 0; i < mask.length; i++) {
+    const char = mask[i]
+
+    if (char === "\\" && i + 1 < mask.length) {
+      i++
+      slots.push({ type: "literal", char: mask[i] })
+      continue
+    }
+
+    if (char === "?") {
+      optional = true
+      continue
+    }
+
+    if (map[char]) slots.push({ type: "token", char, pattern: map[char], optional })
+    else slots.push({ type: "literal", char })
+  }
+
+  return slots
+}
+
+/**
+ * Raw chars -> masked string. Literals append EAGERLY (raw "12" under
+ * "99/99" is "12/" - the separator paints the moment it is reachable); a
+ * token slot consumes the next raw char when it matches, else silently
+ * DROPS it and retries the SAME slot with the following char; transform
+ * (poetry's upcase knob) runs before validation.
+ *
+ * @param {string} raw
+ * @param {Array<Object>} slots - from {@link parseMask}
+ * @param {(char: string) => string} [transform]
+ * @returns {string} the masked value
+ */
+export function applyMaskToRaw(raw, slots, transform) {
+  let result = ""
+  let rawIndex = 0
+
+  for (let slotIndex = 0; slotIndex < slots.length; slotIndex++) {
+    const slot = slots[slotIndex]
+
+    if (slot.type === "literal") {
+      result += slot.char
+      continue
+    }
+
+    if (rawIndex >= raw.length) break
+
+    const char = transform ? transform(raw[rawIndex]) : raw[rawIndex]
+
+    if (slot.pattern.test(char)) {
+      result += char
+      rawIndex++
+    } else {
+      rawIndex++ // silent drop
+      slotIndex-- // retry the same slot
+    }
+  }
+
+  return result
+}
+
+/**
+ * Re-parses arbitrary display text (autofill, a server-rendered value,
+ * IME output): literals self-match or are inserted, token slots scan
+ * forward discarding non-matching chars, and the walk stops at the first
+ * slot the remaining text cannot fill.
+ *
+ * @param {string} text
+ * @param {Array<Object>} slots
+ * @returns {string} the re-masked value
+ */
+export function processInput(text, slots) {
+  let result = ""
+  let index = 0
+
+  for (let slotIndex = 0; slotIndex < slots.length && index <= text.length; slotIndex++) {
+    const slot = slots[slotIndex]
+
+    if (slot.type === "literal") {
+      result += slot.char
+      if (index < text.length && text[index] === slot.char) index++
+      continue
+    }
+
+    if (index >= text.length) break
+
+    while (index < text.length) {
+      const char = text[index]
+
+      index++
+
+      if (slot.pattern.test(char)) {
+        result += char
+        break
+      }
+    }
+
+    if (result.length <= slotIndex) break // the slot went unfilled
+  }
+
+  return result
+}
+
+/**
+ * Chars at token positions - the value the form actually means.
+ *
+ * @param {string} masked
+ * @param {Array<Object>} slots
+ * @returns {string}
+ */
+export function extractRaw(masked, slots) {
+  let raw = ""
+
+  for (let i = 0; i < masked.length && i < slots.length; i++) {
+    if (slots[i].type === "token") raw += masked[i]
+  }
+
+  return raw
+}
+
+/**
+ * Pads the masked value with the mask skeleton. slotChar "_" by default;
+ * a multi-char slotChar indexes per position ("dd/mm/yyyy" under a date
+ * mask) falling back to "_" past its end; null/"" disables padding (the
+ * display stops at the first empty token slot).
+ *
+ * @param {string} value - the masked value so far
+ * @param {Array<Object>} slots
+ * @param {string | null} [slotChar="_"]
+ * @param {boolean} [showSlots=true] - false returns `value` untouched
+ * @returns {string}
+ */
+export function buildDisplayValue(value, slots, slotChar = "_", showSlots = true) {
+  if (!showSlots) return value
+
+  let display = value
+
+  for (let i = value.length; i < slots.length; i++) {
+    const slot = slots[i]
+
+    if (slot.type === "literal") {
+      display += slot.char
+      continue
+    }
+
+    const char = slotCharAt(slotChar, i)
+
+    if (!char) break
+
+    display += char
+  }
+
+  return display
+}
+
+function slotCharAt(slotChar, index) {
+  if (slotChar === null || slotChar === undefined || slotChar === "") return ""
+
+  return slotChar.length > 1 ? (slotChar[index] ?? "_") : slotChar
+}
+
+/**
+ * Complete = every non-optional token position is filled and
+ * pattern-valid.
+ *
+ * @param {string} masked
+ * @param {Array<Object>} slots
+ * @returns {boolean}
+ */
+export function checkComplete(masked, slots) {
+  return slots.every((slot, i) =>
+    slot.type !== "token" || slot.optional || (i < masked.length && slot.pattern.test(masked[i]))
+  )
+}
+
+/**
+ * Regex source for the HTML pattern attribute: "full" wraps each token in
+ * a capture group, "full-inexact" doesn't; optional tokens get a trailing
+ * "?"; literals are regex-escaped.
+ *
+ * @param {Array<Object>} slots
+ * @param {"full" | "full-inexact"} [kind="full"]
+ * @returns {string}
+ */
+export function generatePattern(slots, kind = "full") {
+  return slots.map((slot) => {
+    if (slot.type === "literal") return slot.char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+    const source = kind === "full-inexact" ? slot.pattern.source : `(${slot.pattern.source})`
+
+    return slot.optional ? `${source}?` : source
+  }).join("")
+}
+
+/**
+ * Skips a literal run rightward from `pos`, bounded by the filled region
+ * - the caret never lands inside chrome or out in the skeleton.
+ *
+ * @param {number} pos
+ * @param {Array<Object>} slots
+ * @param {number} filledLength
+ * @returns {number}
+ */
+export function findNextEditablePosition(pos, slots, filledLength) {
+  while (pos < slots.length && pos < filledLength && slots[pos].type === "literal") pos++
+
+  return pos
+}
+
+/**
+ * First token position at or after `from`.
+ *
+ * @param {Array<Object>} slots
+ * @param {number} [from=0]
+ * @returns {number} slots.length when none
+ */
+export function nextTokenPosition(slots, from = 0) {
+  for (let i = from; i < slots.length; i++) {
+    if (slots[i].type === "token") return i
+  }
+
+  return slots.length
+}
+
+/**
+ * Last token position at or before `from`.
+ *
+ * @param {Array<Object>} slots
+ * @param {number} from
+ * @returns {number} -1 when none
+ */
+export function prevTokenPosition(slots, from) {
+  for (let i = from; i >= 0; i--) {
+    if (slots[i].type === "token") return i
+  }
+
+  return -1
+}