poetry-core 0.0.2

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

@@ -0,0 +1,162 @@
+import { Controller } from "@hotwired/stimulus"
+import { tabbableWithin } from "@poetry/controllers/helpers/tabbable"
+import { ensureFocusGuards, removeFocusGuards } from "@poetry/controllers/helpers/focus_guards"
+import { logicallyContains } from "@poetry/controllers/helpers/portal"
+
+// The overlay focus scope: traps Tab/Shift+Tab within the
+// subtree, loops at the edges, and - the part to get exact - snapshots
+// document.activeElement on connect and RESTORES it on disconnect (focus
+// return). Backs Dialog-family overlays, Popover, Menus, Select, Command.
+//
+// Listeners are wired here, not as data-actions: pause/resume must attach
+// and detach them dynamically as scopes stack, which data-action cannot do.
+export default class FocusScopeController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = [
+    "poetry--core--focus-scope:mount-auto-focus", "poetry--core--focus-scope:unmount-auto-focus"
+  ]
+
+  // Nested scopes: only the TOP scope has live listeners. Opening a child
+  // pauses the parent; closing it resumes the parent (one shared stack -
+  // class-level so it is inspectable).
+  static stack = []
+
+  static values = {
+    trapped: { type: Boolean, default: true },
+    loop: { type: Boolean, default: true }
+  }
+
+  #active = false
+  #guarded = false
+  #previouslyFocused = null
+  #lastFocusedWithin = null
+  #onKeydown = (event) => this.#handleKeydown(event)
+  #onFocusin = (event) => this.#handleFocusin(event)
+
+  /**
+   * Snapshots the focus-return element BEFORE any focus moves, pauses the
+   * previous scope and takes the top of the stack, takes the guard
+   * refcount when trapped, then runs mount auto-focus (cancelable - a
+   * consumer owns initial focus by vetoing it).
+   */
+  connect() {
+    // The container is the focus fallback when the scope has no tabbables.
+    if (!this.element.hasAttribute("tabindex")) this.element.setAttribute("tabindex", "-1")
+
+    // Snapshot BEFORE any focus moves: this is where focus RETURNS to.
+    this.#previouslyFocused = document.activeElement
+
+    FocusScopeController.stack.at(-1)?.#pause()
+    FocusScopeController.stack.push(this)
+    this.#resume()
+
+    if (this.trappedValue) {
+      ensureFocusGuards()
+      this.#guarded = true
+    }
+
+    // Cancelable: a consumer preventDefault()s to own initial focus itself
+    // (e.g. Select focusing the active option, not the first tabbable).
+    const mount = this.dispatch("mount-auto-focus", { cancelable: true })
+
+    if (!mount.defaultPrevented) this.#focus(tabbableWithin(this.element)[0] ?? this.element)
+  }
+
+  /**
+   * Leaves the stack (resuming the scope below when this was the top),
+   * releases the guards, and restores focus to the snapshot (cancelable -
+   * a consumer sends focus elsewhere by vetoing it).
+   */
+  disconnect() {
+    const wasTop = FocusScopeController.stack.at(-1) === this
+    const index = FocusScopeController.stack.indexOf(this)
+
+    if (index !== -1) FocusScopeController.stack.splice(index, 1)
+
+    this.#pause()
+
+    if (wasTop) FocusScopeController.stack.at(-1)?.#resume()
+
+    if (this.#guarded) {
+      removeFocusGuards()
+      this.#guarded = false
+    }
+
+    // Focus return, cancelable so a consumer can send focus elsewhere
+    // (e.g. a submenu handing focus back to its subtrigger).
+    const unmount = this.dispatch("unmount-auto-focus", { cancelable: true })
+
+    if (!unmount.defaultPrevented && this.#previouslyFocused?.isConnected) {
+      this.#previouslyFocused.focus()
+    }
+
+    this.#previouslyFocused = null
+    this.#lastFocusedWithin = null
+  }
+
+  // Paused = no listeners at all: a paused parent neither traps nor loops
+  // while a child scope is on top of it.
+  #pause() {
+    if (!this.#active) return
+
+    this.#active = false
+    this.element.removeEventListener("keydown", this.#onKeydown)
+    document.removeEventListener("focusin", this.#onFocusin)
+  }
+
+  #resume() {
+    if (this.#active) return
+
+    this.#active = true
+    this.element.addEventListener("keydown", this.#onKeydown)
+
+    if (this.trappedValue) document.addEventListener("focusin", this.#onFocusin)
+  }
+
+  // Tab at the EDGES only: wrap under loop, hard-stop under trapped. A
+  // mid-list Tab is the browser's job - only the edges need help.
+  #handleKeydown(event) {
+    if (event.key !== "Tab") return
+    // A Tab mid-IME-composition commits the candidate text, it does not
+    // navigate - intercepting it eats the commit, so let it pass.
+    if (event.isComposing) return
+    if (!this.trappedValue && !this.loopValue) return
+
+    const candidates = tabbableWithin(this.element)
+
+    if (candidates.length === 0) {
+      event.preventDefault() // nothing to land on; focus stays on the container
+      return
+    }
+
+    const first = candidates[0]
+    const last = candidates[candidates.length - 1]
+
+    if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault()
+      if (this.loopValue) this.#focus(first)
+    } else if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault()
+      if (this.loopValue) this.#focus(last)
+    }
+  }
+
+  // trapped: focus escaping the scope (a body-edge guard sentinel, a
+  // programmatic move, a click outside) is yanked back to the last focused
+  // element within the scope.
+  #handleFocusin(event) {
+    // Logical containment: a portaled sub level (menus portal each sub on
+    // its own open) sits outside the scope's SUBTREE but inside its tree.
+    if (logicallyContains(this.element, event.target)) {
+      this.#lastFocusedWithin = event.target
+      return
+    }
+
+    this.#focus(this.#lastFocusedWithin ?? tabbableWithin(this.element)[0] ?? this.element)
+  }
+
+  #focus(element) {
+    element?.focus?.()
+  }
+}

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

@@ -0,0 +1,228 @@
+// The announce SINGLETON: shared screen-reader live regions - a plain
+// module, not a controller. Injecting a node that IS a live region is
+// unreliably announced across SR/browser pairs (the region must exist
+// BEFORE its text changes), so consumers keep their own nodes
+// aria-live=off and route announcements
+// through here: TWO lazily-created sr-only regions on body (polite +
+// assertive), refcounted via acquire()/release() (regions removed when the
+// last consumer releases; consumers: Toast, async form status, Combobox
+// result counts - API changes after Toast ships are breaking, so the
+// surface stays exactly this).
+//
+// Announcement mechanics: clear-then-set on a microtask (identical
+// consecutive messages re-announce), a per-region message queue with a
+// small gap between messages, textContent ONLY (live-region injection is a
+// real sink - never innerHTML).
+//
+// Tab-visibility muting: while the tab is hidden both regions flip
+// aria-live=off (muted); announcements made while hidden keep at most the
+// LAST message, flushed on return (no backlog flood).
+
+// The gap (ms) between queued messages per region - long enough for SRs to
+// treat consecutive messages as separate announcements.
+const QUEUE_GAP = 150
+
+// Safari drops messages announced right after a live region is INSERTED
+// (~100ms of post-creation warmup is required in practice; a WebKit
+// behavior, not a spec timing) - a fresh region holds its queue until
+// this warmup elapses. The clear-then-set rAF alone (~one frame) is
+// shorter than Safari needs.
+const REGION_WARMUP = 100
+
+const POLITENESS = {
+  polite: { role: "status", live: "polite" },
+  assertive: { role: "alert", live: "assertive" }
+}
+
+let refCount = 0
+let regions = null // { polite: region, assertive: region } | null
+let hiddenBacklog = null // { message, politeness } - at most the LAST while hidden
+
+const onVisibilityChange = () => {
+  if (document.hidden) mute()
+  else unmute()
+}
+
+/**
+ * Takes a refcount on the shared live regions (created on the first
+ * acquire): a consumer acquires while it is connected and releases on
+ * teardown.
+ */
+export function acquire() {
+  refCount += 1
+  ensureRegions()
+}
+
+/**
+ * Releases one refcount; the last release removes the regions and their
+ * visibility listener.
+ */
+export function release() {
+  if (refCount === 0) return
+
+  refCount -= 1
+
+  if (refCount === 0) teardown()
+}
+
+/**
+ * The announcement surface: queues `message` on the shared region for
+ * `politeness`. While the tab is hidden only the LAST message is kept,
+ * flushed on return.
+ *
+ * @param {string} message - stringified; injected as textContent only
+ * @param {"polite" | "assertive"} [politeness="polite"] - unknown values
+ *   fall back to polite
+ */
+export function announce(message, politeness = "polite") {
+  ensureRegions()
+
+  const resolved = Object.hasOwn(POLITENESS, politeness) ? politeness : "polite"
+
+  if (document.hidden) {
+    hiddenBacklog = { message, politeness: resolved }
+    return
+  }
+
+  enqueue(regions[resolved], message)
+}
+
+function ensureRegions() {
+  // A body swap (Turbo render, test reset) can detach live regions without
+  // a release - rebuild rather than announce into detached nodes.
+  if (regions && !regions.polite.element.isConnected) teardown()
+  if (regions) return
+
+  regions = {
+    polite: createRegion("polite"),
+    assertive: createRegion("assertive")
+  }
+
+  document.addEventListener("visibilitychange", onVisibilityChange)
+
+  if (document.hidden) mute()
+}
+
+function createRegion(politeness) {
+  const element = document.createElement("div")
+  const { role, live } = POLITENESS[politeness]
+
+  element.setAttribute("data-poetry-announce-region", politeness)
+  element.setAttribute("role", role)
+  element.setAttribute("aria-live", live)
+  element.setAttribute("aria-atomic", "true")
+
+  // sr-only, inline (the helper cannot assume a utility class exists).
+  Object.assign(element.style, {
+    position: "absolute",
+    width: "1px",
+    height: "1px",
+    padding: "0",
+    margin: "-1px",
+    overflow: "hidden",
+    clip: "rect(0, 0, 0, 0)",
+    whiteSpace: "nowrap",
+    border: "0"
+  })
+
+  document.body.appendChild(element)
+
+  const region = {
+    politeness, element, queue: [], draining: false, timer: null,
+    warm: false, warmupTimer: null
+  }
+
+  region.warmupTimer = window.setTimeout(() => {
+    region.warmupTimer = null
+    region.warm = true
+    drain(region)
+  }, REGION_WARMUP)
+
+  return region
+}
+
+// Per-region queue: clear-then-set across an animation FRAME, not a
+// microtask (so a message identical to the region's current text still
+// re-announces), then a small gap before the next queued message. The
+// frame matters twice over: a microtask lands in the SAME accessibility-
+// tree flush, so (a) a freshly created region would be seen "born with
+// content" - a mutation pattern ATs reliably skip - and (b) clear+set
+// would coalesce into one text change, letting AT dedup swallow repeats.
+// rAF pushes the set into the next frame's flush; a hidden document has
+// no frames, but the visibility contract already routes those to the
+// backlog before enqueue.
+function enqueue(region, message) {
+  region.queue.push(String(message))
+  drain(region)
+}
+
+function drain(region) {
+  if (!region.warm || region.draining) return
+
+  const message = region.queue.shift()
+
+  if (message === undefined) return
+
+  region.draining = true
+  region.element.textContent = ""
+
+  requestAnimationFrame(() => {
+    // The regions may have been torn down or muted between ticks.
+    if (!regions || regions[region.politeness] !== region) return
+
+    region.element.textContent = message
+    region.timer = window.setTimeout(() => {
+      region.timer = null
+      region.draining = false
+      drain(region)
+    }, QUEUE_GAP)
+  })
+}
+
+function mute() {
+  if (!regions) return
+
+  for (const region of Object.values(regions)) {
+    region.element.setAttribute("aria-live", "off")
+    // Muted messages are dropped - only announce() calls made while hidden
+    // keep their LAST message (the backlog contract).
+    region.queue.length = 0
+
+    if (region.timer !== null) {
+      window.clearTimeout(region.timer)
+      region.timer = null
+    }
+
+    region.draining = false
+  }
+}
+
+function unmute() {
+  if (!regions) return
+
+  for (const region of Object.values(regions)) {
+    region.element.setAttribute("aria-live", POLITENESS[region.politeness].live)
+  }
+
+  if (hiddenBacklog) {
+    const { message, politeness } = hiddenBacklog
+
+    hiddenBacklog = null
+    enqueue(regions[politeness], message)
+  }
+}
+
+function teardown() {
+  if (!regions) return
+
+  for (const region of Object.values(regions)) {
+    if (region.timer !== null) window.clearTimeout(region.timer)
+    if (region.warmupTimer !== null) window.clearTimeout(region.warmupTimer)
+
+    region.element.remove()
+  }
+
+  regions = null
+  hiddenBacklog = null
+  document.removeEventListener("visibilitychange", onVisibilityChange)
+}

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

@@ -0,0 +1,28 @@
+// The mobile breakpoint: matchMedia below Tailwind's md (768px), with a
+// change listener. The
+// first poetry consumer is the Sidebar's mobile-Sheet mode. Environments
+// without matchMedia (the dommy QuickJS engine, bare jsdom) report
+// DESKTOP - the server-rendered desktop shell is the safe default.
+/** The mobile cutoff (px): viewports strictly narrower are mobile. */
+export const MOBILE_BREAKPOINT = 768
+
+/**
+ * Watches the mobile breakpoint: calls `onChange(isMobile)` immediately
+ * with the current state and again on every crossing. Environments
+ * without matchMedia report desktop once and never call again.
+ *
+ * @param {(isMobile: boolean) => void} onChange
+ * @returns {() => void} unwatch
+ */
+export function watchMobile(onChange) {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    onChange(false)
+    return () => {}
+  }
+
+  const query = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+  const listener = () => onChange(query.matches)
+  query.addEventListener("change", listener)
+  onChange(query.matches)
+  return () => query.removeEventListener("change", listener)
+}

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

@@ -0,0 +1,18 @@
+// The DOM is the registry: collection items are read from the document
+// in DOM order - no client-side bookkeeping, no registration step; a
+// membership question is always a fresh query.
+
+/** The attribute marking an element as a collection item. */
+export const COLLECTION_ITEM_SELECTOR = "[data-poetry-collection-item]"
+
+/**
+ * The collection items under `root`, in DOM order.
+ *
+ * @param {ParentNode} root - the element (or document) to query
+ * @param {string} [selector] - override for consumers with their own item
+ *   marker (defaults to {@link COLLECTION_ITEM_SELECTOR})
+ * @returns {Element[]}
+ */
+export function collectionItems(root, selector = COLLECTION_ITEM_SELECTOR) {
+  return Array.from(root.querySelectorAll(selector))
+}

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

@@ -0,0 +1,15 @@
+// Reading direction: the platform mechanism - the closest [dir]
+// ancestor - consumed by roving-focus (Left/Right flip) and popper (side flip).
+
+/**
+ * The reading direction in effect at `element`: the closest `[dir]`
+ * ancestor's value. Only an explicit rtl flips - dir="auto", dir="ltr" and
+ * no [dir] ancestor at all resolve "ltr".
+ *
+ * @param {Element} element
+ * @returns {"ltr" | "rtl"}
+ */
+export function directionOf(element) {
+  const dir = element.closest("[dir]")?.getAttribute("dir")?.toLowerCase()
+  return dir === "rtl" ? "rtl" : "ltr"
+}

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

@@ -0,0 +1,38 @@
+// Capture-phase Escape handling: the primitive under dismissable's
+// topmost-only Esc behavior.
+
+/**
+ * True when a keydown belongs to an IME composition. An Escape that
+ * cancels IME composition must never reach dismissal: CJK users press
+ * Escape to drop an in-progress composition, and closing the overlay
+ * under them destroys the field they were typing into. Chromium reports
+ * isComposing on the cancel keydown; some engines only mark it with the
+ * legacy 229 keyCode - check both. Every Escape consumer (dismissable via
+ * onEscapeKeydown, plus controllers with their own Escape branches) gates
+ * through this predicate.
+ *
+ * @param {KeyboardEvent} event
+ * @returns {boolean}
+ */
+export function isImeKeydown(event) {
+  return event.isComposing || event.keyCode === 229
+}
+
+/**
+ * Subscribes `callback` to Escape keydowns, with IME-cancel presses
+ * filtered out via {@link isImeKeydown}.
+ *
+ * @param {(event: KeyboardEvent) => void} callback
+ * @param {Object} [options]
+ * @param {boolean} [options.capture=true] - capture phase, so dismissal
+ *   sees the key before bubble-phase consumers can swallow it
+ * @param {EventTarget} [options.target=window]
+ * @returns {() => void} unsubscribe
+ */
+export function onEscapeKeydown(callback, { capture = true, target = window } = {}) {
+  const listener = (event) => {
+    if (event.key === "Escape" && !isImeKeydown(event)) callback(event)
+  }
+  target.addEventListener("keydown", listener, { capture })
+  return () => target.removeEventListener("keydown", listener, { capture })
+}

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

@@ -0,0 +1,104 @@
+// The Command filter spec: deterministic
+// substring + a 5-band rank - deliberately NOT a fuzzy command-score. Pure string
+// functions so the CI spec table pins the contract: any scoring change is
+// a reviewed table change, never a silent reorder of every palette. The
+// score's ONLY job is picking the auto-highlighted first match - the
+// controller hides score-0 items and NEVER reorders the DOM (DOM order is
+// the ranking authority within a band).
+//
+// Bands: prefix 4 > word-boundary 3 > substring 2 > keyword 1 > hidden 0;
+// an empty query scores 1 (everything visible). Matching is
+// diacritic-folded ("creme" matches "Crème") and case-insensitive.
+
+/** An empty query: everything stays visible. */
+export const SCORE_EMPTY_QUERY = 1
+/** The label starts with the query. */
+export const SCORE_PREFIX = 4
+/** A word inside the label starts with the query. */
+export const SCORE_WORD = 3
+/** The query appears anywhere in the label. */
+export const SCORE_SUBSTRING = 2
+/** Only a keyword starts with the query. */
+export const SCORE_KEYWORD = 1
+/** No match - the controller hides the item. */
+export const SCORE_HIDDEN = 0
+
+// Words split on whitespace / dash / underscore / slash (the contract's
+// word-boundary definition).
+const WORD_SPLIT = /[\s\-_/]+/
+
+const ITEM_TEXT_SELECTOR = '[data-slot="command-item-text"], [data-slot="combobox-item-text"]'
+
+/**
+ * trim + lowercase + NFKD-fold combining marks: diacritic-insensitive
+ * matching for free in every locale that marks are decorative in (folding
+ * is always-on - the contract's documented call).
+ *
+ * @param {*} value - stringified; null/undefined normalize to ""
+ * @returns {string}
+ */
+export function normalize(value) {
+  return String(value ?? "").trim().toLowerCase().normalize("NFKD").replace(/\p{M}/gu, "")
+}
+
+/**
+ * The pure scorer. label/query arrive RAW (normalization is this
+ * function's business); keywords is an array of raw strings.
+ *
+ * @param {string} label
+ * @param {string} query
+ * @param {string[]} [keywords=[]]
+ * @returns {number} a SCORE_* band
+ */
+export function scoreText(label, query, keywords = []) {
+  const q = normalize(query)
+
+  if (q === "") return SCORE_EMPTY_QUERY
+
+  const folded = normalize(label)
+
+  if (folded.startsWith(q)) return SCORE_PREFIX
+  if (folded.split(WORD_SPLIT).some((word) => word !== "" && word.startsWith(q))) return SCORE_WORD
+  if (folded.includes(q)) return SCORE_SUBSTRING
+  if (keywords.some((keyword) => normalize(keyword) !== "" && normalize(keyword).startsWith(q))) {
+    return SCORE_KEYWORD
+  }
+
+  return SCORE_HIDDEN
+}
+
+/**
+ * The label an item filters against: data-filter-value overrides
+ * (icon-rich content), else the item-text part, else the item's own text.
+ *
+ * @param {Element} item
+ * @returns {string}
+ */
+export function filterLabel(item) {
+  return item.dataset.filterValue ??
+    item.querySelector(ITEM_TEXT_SELECTOR)?.textContent ??
+    item.textContent ?? ""
+}
+
+/**
+ * data-keywords: whitespace-separated extra filter terms an item may
+ * carry beyond its visible label.
+ *
+ * @param {Element} item
+ * @returns {string[]}
+ */
+export function filterKeywords(item) {
+  return (item.dataset.keywords ?? "").split(/\s+/).filter(Boolean)
+}
+
+/**
+ * Scores one collection item against the query via its filter label and
+ * keywords.
+ *
+ * @param {Element} item
+ * @param {string} query
+ * @returns {number} a SCORE_* band
+ */
+export function scoreItem(item, query) {
+  return scoreText(filterLabel(item), query, filterKeywords(item))
+}

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

@@ -0,0 +1,46 @@
+// Focus guards: two visually-hidden tabindex=0 sentinels at the
+// body edges so focusin/focusout fire predictably at the document boundary
+// while any trapped overlay is open - a Tab out of the last real element
+// lands on a guard (which focus-scope yanks back), never on nothing.
+// Refcounted module state: one pair per page no matter how many overlays.
+
+/** Selector matching the two page-edge focus-guard sentinels. */
+export const FOCUS_GUARD_SELECTOR = "[data-poetry-focus-guard]"
+
+let guardCount = 0
+
+/**
+ * Takes a refcount on the page-edge guard pair, creating the two
+ * sentinels on the first acquire. Pair every call with
+ * {@link removeFocusGuards} on teardown.
+ */
+export function ensureFocusGuards() {
+  if (guardCount === 0) {
+    document.body.insertAdjacentElement("afterbegin", createGuard())
+    document.body.insertAdjacentElement("beforeend", createGuard())
+  }
+  guardCount += 1
+}
+
+/**
+ * Releases one refcount on the guard pair; the last release removes both
+ * sentinels from the document.
+ */
+export function removeFocusGuards() {
+  if (guardCount === 0) return
+
+  guardCount -= 1
+
+  if (guardCount === 0) {
+    for (const guard of document.querySelectorAll(FOCUS_GUARD_SELECTOR)) guard.remove()
+  }
+}
+
+function createGuard() {
+  const guard = document.createElement("span")
+  guard.setAttribute("data-poetry-focus-guard", "")
+  guard.setAttribute("tabindex", "0")
+  guard.setAttribute("aria-hidden", "true")
+  guard.style.cssText = "position: fixed; opacity: 0; pointer-events: none; outline: none;"
+  return guard
+}

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

@@ -0,0 +1,43 @@
+// The hotkey descriptor grammar, extracted from the dialog controller so
+// any surface can speak it (the generic hotkey controller, future
+// data-hotkey affordances). "meta+k" / "ctrl+shift+p": '+'-separated
+// modifiers plus one final key token, matched exactly - unlisted modifiers
+// must be UP, so plain typing never triggers. "meta" matches metaKey OR
+// ctrlKey (⌘K on mac, ^K elsewhere - the command-palette convention).
+/**
+ * Whether a keydown satisfies a hotkey descriptor (the grammar above).
+ *
+ * @param {KeyboardEvent} event
+ * @param {string} descriptor - e.g. "meta+k", "ctrl+shift+p", "?"
+ * @returns {boolean}
+ */
+export function matchesHotkey(event, descriptor) {
+  const tokens = descriptor.toLowerCase().split("+").map((token) => token.trim())
+  const key = tokens.pop()
+
+  if ((event.key ?? "").toLowerCase() !== key) return false
+
+  const meta = tokens.includes("meta") ? (event.metaKey || event.ctrlKey) : true
+  const ctrl = tokens.includes("ctrl") ? event.ctrlKey : true
+  const shift = tokens.includes("shift") === event.shiftKey
+  const alt = tokens.includes("alt") === event.altKey
+  const noStray = tokens.includes("meta") || tokens.includes("ctrl") ||
+    (!event.metaKey && !event.ctrlKey)
+
+  return meta && ctrl && shift && alt && noStray
+}
+
+/**
+ * True when the event originates in a text-editing context - unmodified
+ * single-key shortcuts ("/", "?") must stay inert while the user types
+ * (the standard hotkey ignore list: form fields and contenteditable).
+ *
+ * @param {KeyboardEvent} event
+ * @returns {boolean}
+ */
+export function isEditingTarget(event) {
+  const target = event.composedPath?.()[0] ?? event.target
+  if (!target || !(target instanceof Element)) return false
+
+  return Boolean(["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName) || target.isContentEditable)
+}