lostcoords-ui 0.5.0 → 0.6.0

data/app/javascript/lostcoords/ui/controllers/lc_tabs_controller.js

@@ -1,29 +1,32 @@
 import { Controller } from "@hotwired/stimulus"
+import { navigate } from "lostcoords/ui/helpers/roving_focus"
 
-// Tabs with automatic activation: arrow keys, Home and End move focus and select.
+// The ARIA tabs pattern. Arrow keys follow the tab list's aria-orientation, and
+// Home and End jump to the ends. With automatic activation, moving focus selects
+// the tab; with manual activation, Enter or Space does.
 export default class extends Controller {
   static targets = ["tab", "panel"]
+  static values = { activation: { type: String, default: "automatic" } }
 
   select(event) {
     this.show(event.currentTarget)
   }
 
   navigate(event) {
-    const tabs = this.tabTargets.filter((tab) => !tab.disabled)
-    const index = tabs.indexOf(event.currentTarget)
-    const step = getComputedStyle(this.element).direction === "rtl" ? -1 : 1
-    const next = {
-      ArrowRight: index + step,
-      ArrowLeft: index - step,
-      Home: 0,
-      End: tabs.length - 1,
-    }[event.key]
-    if (next === undefined) return
+    const list = event.currentTarget.closest('[role="tablist"]')
+    const tab = navigate(event, this.tabTargets, {
+      orientation:
+        list?.getAttribute("aria-orientation") === "vertical" ? "vertical" : "horizontal",
+      wrap: true,
+    })
+    if (!tab) return
 
-    event.preventDefault()
-    const tab = tabs[(next + tabs.length) % tabs.length]
-    tab.focus()
-    this.show(tab)
+    if (this.activationValue === "manual") this.focusOnly(tab)
+    else this.show(tab)
+  }
+
+  focusOnly(tab) {
+    for (const candidate of this.tabTargets) candidate.tabIndex = candidate === tab ? 0 : -1
   }
 
   show(tab) {

data/app/javascript/lostcoords/ui/controllers/lc_toast_region_controller.js

@@ -0,0 +1,62 @@
+import { Controller } from "@hotwired/stimulus"
+import { topModalElement } from "lostcoords/ui/helpers/dismiss_stack"
+import { hideTopLayer, showTopLayer, supportsTopLayer } from "lostcoords/ui/helpers/top_layer"
+
+// Shows the region in the top layer while it holds toasts, so no sticky header,
+// sheet or dialog paints over them. Each new toast re-opens the region, which
+// moves it above anything opened since. A modal dialog makes the rest of the
+// page inert, so while one is open the region moves inside it, keeping toasts
+// clickable and announced, and moves back when it closes. Without the Popover
+// API the region stays fixed at --lc-z-toast.
+const homes = new WeakMap()
+
+export default class extends Controller {
+  connect() {
+    if (!supportsTopLayer()) return
+
+    this.observer = new MutationObserver((records) => {
+      if (records.some((record) => record.addedNodes.length > 0)) this.raise()
+      else if (this.element.childElementCount === 0) this.lower()
+    })
+    this.observer.observe(this.element, { childList: true })
+    if (this.element.childElementCount > 0) this.raise()
+  }
+
+  // A modal removed right after closing (before its close event) takes the
+  // region with it; put the region back in the page.
+  disconnect() {
+    this.observer?.disconnect()
+    hideTopLayer(this.element)
+    if (!this.element.isConnected) this.goHome()
+  }
+
+  raise() {
+    const modal = topModalElement()
+    if (modal && !modal.contains(this.element)) return this.moveInto(modal)
+
+    hideTopLayer(this.element)
+    showTopLayer(this.element)
+  }
+
+  lower() {
+    hideTopLayer(this.element)
+    this.goHome()
+  }
+
+  // Moving the region reconnects this controller, which raises it again.
+  moveInto(modal) {
+    if (!homes.has(this.element))
+      homes.set(this.element, { parent: this.element.parentNode, next: this.element.nextSibling })
+    const region = this.element
+    modal.addEventListener("close", () => this.goHome(region), { once: true })
+    modal.append(region)
+  }
+
+  goHome(region = this.element) {
+    const home = homes.get(region)
+    if (!home?.parent.isConnected) return
+
+    homes.delete(region)
+    home.parent.insertBefore(region, home.next?.parentNode === home.parent ? home.next : null)
+  }
+}

data/app/javascript/lostcoords/ui/controllers/lc_tooltip_controller.js

@@ -1,14 +1,54 @@
 import { Controller } from "@hotwired/stimulus"
+import { registerDismissable } from "lostcoords/ui/helpers/dismiss_stack"
+import { liftToTopLayer, onPageLeave } from "lostcoords/ui/helpers/top_layer"
 
-// Escape hides a visible tooltip without moving the pointer or focus. It shows
-// again after the pointer leaves or focus moves away.
+// Opens the tooltip in the top layer, so no stacking context or overflow clip
+// covers it. Without the Popover API it stays in place. Escape closes it before
+// any menu or dialog around it, and it stays hidden until the pointer leaves
+// and focus moves away.
 export default class extends Controller {
-  dismiss(event) {
-    if (event.key !== "Escape" || !this.element.matches(":hover, :focus-within")) return
-    this.element.dataset.dismissed = ""
+  static targets = ["content"]
+
+  connect() {
+    this.stopPageLeave = onPageLeave(() => this.close({ immediate: true }))
+  }
+
+  disconnect() {
+    this.stopPageLeave?.()
+    this.close({ immediate: true })
+  }
+
+  show(event) {
+    if (event.type === "focusin" && !event.target.matches(":focus-visible")) return
+    if (this.release || this.element.hasAttribute("data-dismissed")) return
+
+    this.element.toggleAttribute("data-open", true)
+    this.release = liftToTopLayer(this.contentTarget, this.element)
+    this.unregister = registerDismissable({
+      type: "tooltip",
+      element: this.element,
+      isOpen: () => this.element.hasAttribute("data-open"),
+      close: () => this.dismiss(),
+    })
   }
 
-  reset() {
+  hide() {
+    if (this.element.matches(":hover") || this.element.querySelector(":focus-visible")) return
+
     delete this.element.dataset.dismissed
+    this.close()
+  }
+
+  dismiss() {
+    this.element.dataset.dismissed = ""
+    this.close({ immediate: true })
+  }
+
+  close({ immediate = false } = {}) {
+    this.element.toggleAttribute("data-open", false)
+    this.release?.({ immediate })
+    this.release = null
+    this.unregister?.()
+    this.unregister = null
   }
 }

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

@@ -1,6 +1,8 @@
 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()
@@ -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) {
@@ -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/dismiss_stack.js

@@ -47,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()
@@ -54,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
@@ -84,6 +100,12 @@ function topModal() {
     .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))
 }
@@ -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

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

@@ -1,9 +1,8 @@
 import { Controller } from "@hotwired/stimulus"
 import { registerDismissable } from "lostcoords/ui/helpers/dismiss_stack"
-import { liftToTopLayer } from "lostcoords/ui/helpers/top_layer"
+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)
+}