lostcoords-ui 0.4.1 → 0.6.0

data/app/javascript/lostcoords/ui/helpers/catalog_picker.js

@@ -1,7 +1,9 @@
-import { holdDocumentScroll } from "helpers/dismiss_stack"
-import { FloatingPanel } from "helpers/floating_panel"
-import { SHEET_TIMING, sheetDuration } from "helpers/sheet_motion"
-import { isSheetViewport } from "helpers/viewport"
+import { holdDocumentScroll } from "lostcoords/ui/helpers/dismiss_stack"
+import { FloatingPanel } from "lostcoords/ui/helpers/floating_panel"
+import { navigableItems, navigate, rove } from "lostcoords/ui/helpers/roving_focus"
+import { SHEET_TIMING, sheetDuration } from "lostcoords/ui/helpers/sheet_motion"
+import { hideTopLayer, showTopLayer, supportsTopLayer } from "lostcoords/ui/helpers/top_layer"
+import { isSheetViewport } from "lostcoords/ui/helpers/viewport"
 
 const catalogs = new Map()
 const MAX_RESULTS = 250
@@ -133,24 +135,14 @@ export class CatalogPicker extends FloatingPanel {
   }
 
   showSheet() {
-    if (!this.supportsPopover) return
-
-    if (this.popoverTarget.getAttribute("popover") !== "manual") {
+    if (this.popoverTarget.getAttribute("popover") !== "manual")
       this.popoverTarget.setAttribute("popover", "manual")
-    }
-    try {
-      if (!this.popoverTarget.matches(":popover-open")) this.popoverTarget.showPopover()
-    } catch {}
+    showTopLayer(this.popoverTarget)
   }
 
   hideSheet() {
-    if (this.supportsPopover && this.popoverTarget.matches(":popover-open")) {
-      try {
-        this.popoverTarget.hidePopover()
-      } catch {}
-    } else {
-      this.popoverTarget.hidden = true
-    }
+    if (this.supportsPopover) hideTopLayer(this.popoverTarget)
+    else this.popoverTarget.hidden = true
   }
 
   // A non-modal popover's ::backdrop doesn't block input, so a tap in the dimmed
@@ -179,13 +171,71 @@ export class CatalogPicker extends FloatingPanel {
     this.applyFilter(this.searchQuery)
   }
 
+  // Arrow Down leaves the search for the first option in view; Enter picks
+  // the best match.
   onSearchKeydown(event) {
-    if (event.key !== "Escape" || !this.searchQuery) return
+    if (event.isComposing) return
+
+    if (event.key === "ArrowDown") {
+      const top = this.bodyTarget.getBoundingClientRect().top
+      const option = this.gridOptions().find((item) => item.getBoundingClientRect().bottom > top)
+      if (!option) return
+      event.preventDefault()
+      rove(this.allOptions(), option)
+      option.focus()
+    } else if (event.key === "Enter" && this.searchQuery) {
+      const first = this.gridOptions()[0]
+      if (!first) return
+      event.preventDefault()
+      first.click()
+    }
+  }
+
+  // The options are one Tab stop. Arrows move through them as a grid that
+  // flows in rows, across section breaks; Arrow Up from the top row returns
+  // to the search field.
+  navigateGrid(event) {
+    if (!event.target.matches(this.optionSelector)) return
+
+    const options = this.gridOptions()
+    const option = navigate(event, options, { orientation: "grid", flow: "row" })
+    if (option) {
+      rove(this.allOptions(), option)
+      return
+    }
+    if (event.key === "ArrowUp" && this.hasSearchInputTarget && !event.defaultPrevented) {
+      event.preventDefault()
+      this.searchInputTarget.focus()
+    }
+  }
+
+  // Keeps the Tab stop on the option focus last landed on.
+  trackGridFocus(event) {
+    if (event.target.matches?.(this.optionSelector)) rove(this.allOptions(), event.target)
+  }
+
+  syncGridStop() {
+    const options = this.allOptions()
+    const stop = this.gridStop(options)
+    rove(options, stop)
+  }
+
+  gridStop(options = this.allOptions()) {
+    const visible = (option) => option.getClientRects().length > 0
+    return (
+      options.find((option) => option.getAttribute("tabindex") === "0" && visible(option)) ||
+      options.find((option) => option.getAttribute("aria-current") === "true" && visible(option)) ||
+      options.find(visible) ||
+      null
+    )
+  }
+
+  gridOptions() {
+    return navigableItems(this.allOptions())
+  }
 
-    event.preventDefault()
-    event.stopPropagation()
-    this.searchInputTarget.value = ""
-    this.applyFilter("")
+  allOptions() {
+    return [...this.bodyTarget.querySelectorAll(this.optionSelector)]
   }
 
   applyFilter(query) {
@@ -195,6 +245,7 @@ export class CatalogPicker extends FloatingPanel {
     if (!normalizedQuery) {
       if (this.hasResultsTarget) this.resultsTarget.hidden = true
       if (this.hasEmptyTarget) this.emptyTarget.hidden = true
+      this.syncGridStop()
       return
     }
 
@@ -216,6 +267,7 @@ export class CatalogPicker extends FloatingPanel {
     this.resultsTarget.hidden = matches.length === 0
     if (this.hasEmptyTarget) this.emptyTarget.hidden = matches.length > 0
     this.bodyTarget.scrollTop = 0
+    this.syncGridStop()
   }
 
   score(entry, query) {
@@ -433,7 +485,7 @@ export class CatalogPicker extends FloatingPanel {
       duration,
       settle: duration,
       transition: `transform ${SHEET_TIMING}`,
-      offscreen: "translateY(var(--sheet-offscreen))",
+      offscreen: "translateY(var(--lc-sheet-offscreen))",
     }
   }
 
@@ -446,7 +498,7 @@ export class CatalogPicker extends FloatingPanel {
   }
 
   get supportsPopover() {
-    return typeof this.popoverTarget.showPopover === "function"
+    return supportsTopLayer()
   }
 
   get searchQuery() {

data/app/javascript/lostcoords/ui/helpers/context_dialog.js

@@ -1,4 +1,4 @@
-import { isSheetViewport } from "helpers/viewport"
+import { isSheetViewport } from "lostcoords/ui/helpers/viewport"
 
 const EDGE = 16
 
@@ -10,19 +10,19 @@ export function showContextDialog(dialog, menu) {
   const corner = rect?.height
     ? { top: Math.max(EDGE, rect.bottom - dialog.offsetHeight), right: rect.right }
     : null
-  if (anchorDialog(dialog, corner)) dialog.style.setProperty("--dialog-origin", "bottom right")
+  if (anchorDialog(dialog, corner)) dialog.style.setProperty("--lc-dialog-origin", "bottom right")
 }
 
 export function anchorDialog(dialog, corner) {
   delete dialog.dataset.anchored
-  dialog.style.removeProperty("--dialog-top")
-  dialog.style.removeProperty("--dialog-right")
+  dialog.style.removeProperty("--lc-dialog-top")
+  dialog.style.removeProperty("--lc-dialog-right")
   if (!corner || isSheetViewport()) return false
 
   dialog.dataset.anchored = ""
-  dialog.style.setProperty("--dialog-top", `${corner.top}px`)
+  dialog.style.setProperty("--lc-dialog-top", `${corner.top}px`)
   dialog.style.setProperty(
-    "--dialog-right",
+    "--lc-dialog-right",
     `${Math.max(EDGE, window.innerWidth - corner.right)}px`,
   )
   return true

data/app/javascript/lostcoords/ui/helpers/dialog.js

@@ -1,4 +1,4 @@
-import { registerDismissable } from "helpers/dismiss_stack"
+import { registerDismissable } from "lostcoords/ui/helpers/dismiss_stack"
 
 const registrations = new WeakMap()
 
@@ -8,7 +8,7 @@ export function registerDialog(dialog, { close = () => dialog.close(), lockScrol
 
   const unregisterDismissable = registerDismissable({
     element: dialog,
-    type: "modal",
+    type: "lc-dialog",
     lockScroll,
     close,
     isOpen: () => dialog.open,

data/app/javascript/lostcoords/ui/helpers/dismiss_stack.js

@@ -3,9 +3,8 @@ let nextOrder = 0
 let lockedScrollY = 0
 let scrollHolds = 0
 
-document.addEventListener("keydown", dismissOnEscape, true)
-
 export function registerDismissable(options) {
+  if (stack.length === 0) document.addEventListener("keydown", dismissOnEscape, true)
   const entry = {
     type: "panel",
     isOpen: defaultIsOpen,
@@ -17,7 +16,7 @@ export function registerDismissable(options) {
   stack.push(entry)
   syncModalScrollLock()
 
-  if (entry.type === "modal" && entry.element instanceof HTMLDialogElement) {
+  if (entry.type === "lc-dialog" && entry.element instanceof HTMLDialogElement) {
     entry.cancel = (event) => cancelDialog(event, entry)
     entry.element.addEventListener("cancel", entry.cancel)
   }
@@ -48,6 +47,7 @@ export function closeTopDismissable(event) {
 
 function dismissOnEscape(event) {
   if (event.key !== "Escape" && event.key !== "Esc") return
+  if (clearSearchField(event)) return
   if (!closeTopDismissable(event)) return
 
   event.preventDefault()
@@ -55,6 +55,21 @@ function dismissOnEscape(event) {
   event.stopImmediatePropagation()
 }
 
+// Escape in a search field that has text clears it, as a native search field
+// does, and only the next Escape closes the panel around it.
+function clearSearchField(event) {
+  const field = event.target
+  if (!(field instanceof HTMLInputElement) || field.type !== "search" || field.value === "")
+    return false
+  if (!topDismissable()?.element.contains(field)) return false
+
+  event.preventDefault()
+  event.stopImmediatePropagation()
+  field.value = ""
+  field.dispatchEvent(new Event("input", { bubbles: true }))
+  return true
+}
+
 function cancelDialog(event, dialogEntry) {
   const entry = topDismissable(dialogEntry.element)
   if (!entry) return
@@ -81,10 +96,16 @@ function topDismissable(scope = topModal()?.element) {
 
 function topModal() {
   return openEntries()
-    .filter((entry) => entry.type === "modal")
+    .filter((entry) => entry.type === "lc-dialog")
     .at(-1)
 }
 
+// The modal the page is limited to, if any: the top open lc-dialog, or a native
+// modal <dialog> opened without one. Shortcuts and toasts stay inside it.
+export function topModalElement() {
+  return topModal()?.element ?? [...document.querySelectorAll("dialog:modal")].at(-1) ?? null
+}
+
 function openEntries() {
   return stack.filter((entry) => entry.element?.isConnected && entry.isOpen.call(entry))
 }
@@ -92,6 +113,7 @@ function openEntries() {
 function unregisterDismissable(entry) {
   const index = stack.indexOf(entry)
   if (index >= 0) stack.splice(index, 1)
+  if (stack.length === 0) document.removeEventListener("keydown", dismissOnEscape, true)
 
   if (entry.cancel) {
     entry.element.removeEventListener("cancel", entry.cancel)
@@ -108,6 +130,7 @@ function defaultIsOpen() {
 }
 
 function priorityFor(type) {
+  if (type === "tooltip") return 40
   if (type === "popover") return 30
   if (type === "panel") return 20
   return 10
@@ -116,7 +139,7 @@ function priorityFor(type) {
 function syncModalScrollLock() {
   if (
     scrollHolds > 0 ||
-    openEntries().some((entry) => entry.type === "modal" && entry.lockScroll !== false)
+    openEntries().some((entry) => entry.type === "lc-dialog" && entry.lockScroll !== false)
   ) {
     lockDocumentScroll()
     return
@@ -136,7 +159,7 @@ function lockDocumentScroll() {
   body.style.top = `-${lockedScrollY}px`
   // Pinning the body drags the sticky nav off with the scrolled-away page;
   // the nav offsets itself by this to stay where it was.
-  body.style.setProperty("--scroll-lock-y", `${lockedScrollY}px`)
+  body.style.setProperty("--lc-scroll-lock-y", `${lockedScrollY}px`)
   body.style.inlineSize = "100%"
 }
 
@@ -147,7 +170,7 @@ function unlockDocumentScroll() {
   body.style.position = ""
   body.style.inset = ""
   body.style.top = ""
-  body.style.removeProperty("--scroll-lock-y")
+  body.style.removeProperty("--lc-scroll-lock-y")
   body.style.inlineSize = ""
   delete body.dataset.modalScrollLock
   window.scrollTo({ top: lockedScrollY, behavior: "instant" })

data/app/javascript/lostcoords/ui/helpers/floating_panel.js

@@ -1,9 +1,8 @@
 import { Controller } from "@hotwired/stimulus"
-import { registerDismissable } from "helpers/dismiss_stack"
-import { liftToTopLayer } from "helpers/top_layer"
+import { registerDismissable } from "lostcoords/ui/helpers/dismiss_stack"
+import { liftToTopLayer, onPageLeave } from "lostcoords/ui/helpers/top_layer"
 
 const BEFORE_OPEN = "overlay:before-open"
-const PAGE_LEAVES = ["turbo:before-cache", "turbo:before-visit", "turbo:before-render"]
 
 export class FloatingPanel extends Controller {
   static targets = ["trigger", "popover"]
@@ -14,7 +13,9 @@ export class FloatingPanel extends Controller {
 
   initialize() {
     this.closeForOther = (event) => {
-      if (event.detail?.source !== this) this.close()
+      // A panel opened inside this one (a menu in a popover form) keeps it open.
+      const source = event.detail?.source
+      if (source !== this && !this.element.contains(source?.element)) this.close()
     }
     this.closeOnOutsideClick = (event) => {
       if (!this.element.contains(event.target)) this.close()
@@ -24,14 +25,12 @@ export class FloatingPanel extends Controller {
 
   connect() {
     document.addEventListener(BEFORE_OPEN, this.closeForOther)
-    for (const type of PAGE_LEAVES) document.addEventListener(type, this.closeForPageLeave)
-    window.addEventListener("pagehide", this.closeForPageLeave)
+    this.stopPageLeave = onPageLeave(this.closeForPageLeave)
   }
 
   disconnect() {
     document.removeEventListener(BEFORE_OPEN, this.closeForOther)
-    for (const type of PAGE_LEAVES) document.removeEventListener(type, this.closeForPageLeave)
-    window.removeEventListener("pagehide", this.closeForPageLeave)
+    this.stopPageLeave?.()
     this.release({ immediate: true })
   }
 

data/app/javascript/lostcoords/ui/helpers/menu_keys.js

@@ -1,27 +1,28 @@
-const ITEMS = '[role^="menuitem"]:not([disabled]):not([aria-disabled="true"])'
+import { navigableItems, navigate } from "lostcoords/ui/helpers/roving_focus"
 
-function items(menu) {
-  return [...menu.querySelectorAll(ITEMS)].filter((item) => item.getClientRects().length > 0)
+const ITEMS = '[role^="menuitem"]'
+
+export function menuItems(menu) {
+  return navigableItems(menu.querySelectorAll(ITEMS))
 }
 
 export function focusFirstMenuItem(menu) {
-  items(menu)[0]?.focus()
+  menuItems(menu)[0]?.focus()
 }
 
-// The ARIA menu pattern: arrows move between items and wrap, Home/End jump.
-export function navigateMenu(event, menu) {
-  const list = items(menu)
-  if (list.length === 0) return
+export function focusLastMenuItem(menu) {
+  menuItems(menu).at(-1)?.focus()
+}
 
-  const index = list.indexOf(document.activeElement)
-  const next = {
-    ArrowDown: (index + 1) % list.length,
-    ArrowUp: (index - 1 + list.length) % list.length,
-    Home: 0,
-    End: list.length - 1,
-  }[event.key]
-  if (next === undefined) return
+// The ARIA menu pattern: arrows move between items and wrap, Home/End jump,
+// typing a letter jumps to the next item that starts with it, and Space
+// activates a link item as Enter does.
+export function navigateMenu(event, menu, { orientation = "vertical" } = {}) {
+  if (event.key === " " && event.target.matches(`a${ITEMS}`)) {
+    event.preventDefault()
+    event.target.click()
+    return
+  }
 
-  event.preventDefault()
-  list[next].focus()
+  navigate(event, menuItems(menu), { orientation, wrap: true, typeahead: true })
 }

data/app/javascript/lostcoords/ui/helpers/roving_focus.js

@@ -0,0 +1,175 @@
+// Arrow-key navigation shared by every list, toolbar and grid in the library.
+//
+// orientation:
+//   "vertical"   ArrowUp/ArrowDown move through the items in order.
+//   "horizontal" ArrowLeft/ArrowRight do, flipped in right-to-left text.
+//   "both"       All four arrows do, for toolbars that wrap onto two lines.
+//   "grid"       Items laid out in rows (flow: "row") or columns (flow: "column").
+//                Arrows along the flow move in order; arrows across it move to
+//                the nearest item in the next row or column, by position on screen.
+// wrap:      the ends lead back round to the other end. Grids never wrap.
+// typeahead: typing a letter moves to the next item whose label starts with it.
+//
+// navigate() moves focus and returns the item it moved to, or null when the key
+// is not one it handles. rove() keeps a single Tab stop on the current item.
+
+const TYPEAHEAD_RESET = 500
+const typeaheads = new WeakMap()
+
+export function navigableItems(items) {
+  return [...items].filter(
+    (item) =>
+      !item.disabled &&
+      item.getAttribute("aria-disabled") !== "true" &&
+      !item.closest("[inert]") &&
+      item.getClientRects().length > 0,
+  )
+}
+
+export function rove(items, current) {
+  for (const item of items) item.tabIndex = item === current ? 0 : -1
+}
+
+export function navigate(
+  event,
+  items,
+  {
+    orientation = "vertical",
+    flow = "row",
+    wrap = orientation !== "grid",
+    typeahead = false,
+    label = defaultLabel,
+    focus = true,
+  } = {},
+) {
+  if (event.defaultPrevented || event.isComposing || event.altKey || event.metaKey) return null
+
+  const list = navigableItems(items)
+  if (list.length === 0) return null
+
+  const index = list.findIndex((item) => item === event.target || item.contains(event.target))
+  const editing = isEditable(event.target)
+  let target = null
+
+  if (event.key === "Home" || event.key === "End") {
+    if (editing) return null
+    if (event.ctrlKey && orientation !== "grid") return null
+    target = event.key === "Home" ? list[0] : list.at(-1)
+  } else if (event.key.startsWith("Arrow")) {
+    if (event.ctrlKey) return null
+    if (editing && (event.key === "ArrowLeft" || event.key === "ArrowRight")) return null
+    target = arrowTarget(event.key, list, index, {
+      orientation,
+      flow,
+      wrap,
+      rtl: isRtl(event.target),
+    })
+  } else if (typeahead && !editing && !event.ctrlKey) {
+    target = typeaheadTarget(event.key, list, index, label)
+  }
+
+  if (!target) return null
+  event.preventDefault()
+  if (focus) target.focus()
+  return target
+}
+
+function arrowTarget(key, list, index, { orientation, flow, wrap, rtl }) {
+  const vertical = key === "ArrowUp" || key === "ArrowDown"
+  const forward = key === "ArrowDown" || key === (rtl ? "ArrowLeft" : "ArrowRight")
+
+  if (orientation === "vertical" && !vertical) return null
+  if (orientation === "horizontal" && vertical) return null
+  if (orientation === "grid" && vertical !== (flow === "column")) {
+    return index < 0 ? list[0] : nearestAcross(list, list[index], key)
+  }
+
+  if (index < 0) return forward ? list[0] : list.at(-1)
+  const next = index + (forward ? 1 : -1)
+  if (next >= 0 && next < list.length) return list[next]
+  if (!wrap) return null
+  return list[(next + list.length) % list.length]
+}
+
+// The nearest row (or column) in the arrow's direction first, then the item in
+// it closest to the current one, so a short last row still has a landing spot.
+function nearestAcross(list, from, key) {
+  const vertical = key === "ArrowUp" || key === "ArrowDown"
+  const sign = key === "ArrowDown" || key === "ArrowRight" ? 1 : -1
+  const origin = centre(from.getBoundingClientRect())
+  const reach = (vertical ? from.offsetHeight : from.offsetWidth) / 2
+
+  const ahead = []
+  for (const item of list) {
+    if (item === from) continue
+    const point = centre(item.getBoundingClientRect())
+    const along = (vertical ? point.y - origin.y : point.x - origin.x) * sign
+    if (along < reach) continue
+    ahead.push({
+      item,
+      along,
+      across: Math.abs(vertical ? point.x - origin.x : point.y - origin.y),
+    })
+  }
+  if (ahead.length === 0) return null
+
+  const line = Math.min(...ahead.map((candidate) => candidate.along)) + reach
+  const sameLine = ahead.filter((candidate) => candidate.along <= line)
+  return sameLine.reduce((best, candidate) => (candidate.across < best.across ? candidate : best))
+    .item
+}
+
+// Repeating one letter cycles through the items that start with it; typing a
+// word quickly matches the whole prefix.
+function typeaheadTarget(key, list, index, label) {
+  if (key.length !== 1) return null
+
+  const state = typeaheads.get(list[0].parentElement) ?? { text: "", timer: null }
+  if (key === " " && state.text === "") return null
+
+  clearTimeout(state.timer)
+  state.text += key.toLocaleLowerCase()
+  state.timer = setTimeout(() => {
+    state.text = ""
+  }, TYPEAHEAD_RESET)
+  typeaheads.set(list[0].parentElement, state)
+
+  const repeated = [...state.text].every((letter) => letter === state.text[0])
+  const query = repeated ? state.text[0] : state.text
+  const start = repeated ? index + 1 : Math.max(index, 0)
+  for (let offset = 0; offset < list.length; offset++) {
+    const item = list[(start + offset) % list.length]
+    if (label(item).startsWith(query)) return item
+  }
+  return null
+}
+
+function defaultLabel(item) {
+  return (item.getAttribute("aria-label") || item.textContent).trim().toLocaleLowerCase()
+}
+
+function centre(rect) {
+  return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 }
+}
+
+function isRtl(element) {
+  return getComputedStyle(element).direction === "rtl"
+}
+
+export function isEditable(element) {
+  if (!(element instanceof Element)) return false
+  if (element.isContentEditable || element.tagName === "TEXTAREA" || element.tagName === "SELECT")
+    return true
+  if (element.tagName !== "INPUT") return false
+  return ![
+    "button",
+    "checkbox",
+    "radio",
+    "range",
+    "reset",
+    "submit",
+    "color",
+    "file",
+    "image",
+  ].includes(element.type)
+}

data/app/javascript/lostcoords/ui/helpers/sheet_motion.js

@@ -1,13 +1,13 @@
-import { prefersReducedMotion } from "helpers/viewport"
-// The sheet beat lives in CSS (--sheet-duration, --ease-sheet) so CSS- and
+import { prefersReducedMotion } from "lostcoords/ui/helpers/viewport"
+// The sheet beat lives in CSS (--lc-sheet-duration, --lc-ease-sheet) so CSS- and
 // JS-driven slides can't drift apart. Inline transitions use the variables
 // directly; timers need the duration in milliseconds.
-export const SHEET_TIMING = "var(--sheet-duration) var(--ease-sheet)"
+export const SHEET_TIMING = "var(--lc-sheet-duration) var(--lc-ease-sheet)"
 
 export function sheetDuration() {
   if (prefersReducedMotion()) return 0
   const value = getComputedStyle(document.documentElement)
-    .getPropertyValue("--sheet-duration")
+    .getPropertyValue("--lc-sheet-duration")
     .trim()
   return value.endsWith("ms") ? parseFloat(value) : parseFloat(value) * 1000
 }