Implement keyboard navigation using arrow keys in the whole application. (#2)
This commit is contained in:
@@ -0,0 +1,479 @@
|
||||
/**
|
||||
* Keyboard Navigation Module
|
||||
*
|
||||
* Provides reusable arrow key navigation for button groups and grids.
|
||||
*
|
||||
* Concepts:
|
||||
* - Group: A container with focusable elements (buttons, links, items)
|
||||
* - Button row: Left/right arrows navigate between buttons, up/down navigate to adjacent groups
|
||||
* - Grid: A responsive grid of items; arrows follow the visual grid layout
|
||||
*
|
||||
* Data attributes for customization:
|
||||
* - data-nav-group: Marks a navigation group container
|
||||
* - data-nav-primary: Marks the preferred element to focus when entering a group
|
||||
* - data-nav-items: CSS selector for focusable items within the group (default: 'button, a, [tabindex="0"], [tabindex="-1"]:not([disabled])')
|
||||
*
|
||||
* Automatic navigation:
|
||||
* - Buttons/links inside .button-row or .modal-actions get automatic left/right arrow navigation
|
||||
* - No need for explicit @keydown handlers on elements
|
||||
* - Call initKeyboardNavigation() once at app startup to enable global navigation
|
||||
*/
|
||||
|
||||
// Direction mapping from key events
|
||||
const DIRECTION_MAP = {
|
||||
ArrowLeft: 'left',
|
||||
ArrowRight: 'right',
|
||||
ArrowUp: 'up',
|
||||
ArrowDown: 'down'
|
||||
}
|
||||
|
||||
// Input types that use left/right arrows for internal cursor movement
|
||||
const TEXT_INPUT_TYPES = new Set([
|
||||
'text', 'email', 'password', 'search', 'tel', 'url', 'number'
|
||||
])
|
||||
|
||||
/**
|
||||
* Get the direction from a keyboard event.
|
||||
* For text inputs with content, left/right arrows return null to preserve cursor movement.
|
||||
* @param {KeyboardEvent} event
|
||||
* @returns {string|null} 'left', 'right', 'up', 'down', or null
|
||||
*/
|
||||
export const getDirection = (event) => {
|
||||
const direction = DIRECTION_MAP[event.key]
|
||||
if (!direction) return null
|
||||
|
||||
// For text inputs, preserve left/right for cursor movement when there's content
|
||||
const target = event.target
|
||||
const isTextInput = (target.tagName === 'INPUT' && TEXT_INPUT_TYPES.has(target.type)) || target.tagName === 'TEXTAREA'
|
||||
if (isTextInput && (direction === 'left' || direction === 'right')) {
|
||||
// Only allow navigation when input is empty
|
||||
if (target.value !== '') return null
|
||||
}
|
||||
|
||||
return direction
|
||||
}
|
||||
|
||||
/**
|
||||
* Get focusable elements within a container
|
||||
* @param {HTMLElement} container
|
||||
* @param {string} selector - CSS selector for items (optional)
|
||||
* @returns {HTMLElement[]}
|
||||
*/
|
||||
export const getFocusableItems = (container, selector = null) => {
|
||||
if (!container) return []
|
||||
const sel = selector || container.dataset?.navItems || 'button:not([disabled]), a, [tabindex="0"], [tabindex="-1"]:not([disabled])'
|
||||
return Array.from(container.querySelectorAll(sel))
|
||||
}
|
||||
|
||||
/**
|
||||
* Get grid layout information for a container
|
||||
* @param {HTMLElement} container
|
||||
* @param {string} itemSelector - CSS selector for grid items
|
||||
* @returns {{ items: HTMLElement[], cols: number } | null}
|
||||
*/
|
||||
export const getGridInfo = (container, itemSelector) => {
|
||||
const items = getFocusableItems(container, itemSelector)
|
||||
if (items.length === 0) return null
|
||||
|
||||
// Calculate columns by checking which items share the same top position
|
||||
const firstTop = items[0].getBoundingClientRect().top
|
||||
let cols = 0
|
||||
for (const item of items) {
|
||||
if (Math.abs(item.getBoundingClientRect().top - firstTop) < 5) cols++
|
||||
else break
|
||||
}
|
||||
return { items, cols: Math.max(1, cols) }
|
||||
}
|
||||
|
||||
/**
|
||||
* Navigate within a horizontal button row
|
||||
* @param {HTMLElement} container - The container element
|
||||
* @param {HTMLElement} current - Currently focused element
|
||||
* @param {string} direction - 'left', 'right', 'up', or 'down'
|
||||
* @param {Object} options
|
||||
* @param {string} options.itemSelector - CSS selector for buttons
|
||||
* @returns {'moved'|'boundary'|'none'} Result of navigation
|
||||
*/
|
||||
export const navigateButtonRow = (container, current, direction, options = {}) => {
|
||||
const items = getFocusableItems(container, options.itemSelector)
|
||||
if (items.length === 0) return 'none'
|
||||
|
||||
const currentIndex = items.indexOf(current)
|
||||
if (currentIndex === -1) return 'none'
|
||||
|
||||
if (direction === 'left') {
|
||||
if (currentIndex > 0) {
|
||||
items[currentIndex - 1].focus()
|
||||
return 'moved'
|
||||
}
|
||||
return 'boundary'
|
||||
}
|
||||
|
||||
if (direction === 'right') {
|
||||
if (currentIndex < items.length - 1) {
|
||||
items[currentIndex + 1].focus()
|
||||
return 'moved'
|
||||
}
|
||||
return 'boundary'
|
||||
}
|
||||
|
||||
// Up/down are always boundaries for button rows
|
||||
return 'boundary'
|
||||
}
|
||||
|
||||
/**
|
||||
* Navigate within a responsive grid
|
||||
* @param {HTMLElement} container - The grid container
|
||||
* @param {HTMLElement} current - Currently focused element
|
||||
* @param {string} direction - 'left', 'right', 'up', or 'down'
|
||||
* @param {Object} options
|
||||
* @param {string} options.itemSelector - CSS selector for grid items
|
||||
* @returns {'moved'|'boundary'|'none'} Result of navigation
|
||||
*/
|
||||
export const navigateGrid = (container, current, direction, options = {}) => {
|
||||
const grid = getGridInfo(container, options.itemSelector)
|
||||
if (!grid) return 'none'
|
||||
|
||||
const { items, cols } = grid
|
||||
const currentIndex = items.indexOf(current)
|
||||
if (currentIndex === -1) return 'none'
|
||||
|
||||
const row = Math.floor(currentIndex / cols)
|
||||
const col = currentIndex % cols
|
||||
let newIndex = currentIndex
|
||||
|
||||
switch (direction) {
|
||||
case 'left':
|
||||
if (col === 0) return 'boundary'
|
||||
newIndex = currentIndex - 1
|
||||
break
|
||||
case 'right':
|
||||
if (currentIndex >= items.length - 1) return 'boundary'
|
||||
newIndex = currentIndex + 1
|
||||
break
|
||||
case 'up':
|
||||
if (row === 0) return 'boundary'
|
||||
newIndex = currentIndex - cols
|
||||
break
|
||||
case 'down':
|
||||
if (currentIndex + cols >= items.length) return 'boundary'
|
||||
newIndex = currentIndex + cols
|
||||
break
|
||||
default:
|
||||
return 'none'
|
||||
}
|
||||
|
||||
if (newIndex !== currentIndex) {
|
||||
items[newIndex].focus()
|
||||
return 'moved'
|
||||
}
|
||||
return 'none'
|
||||
}
|
||||
|
||||
/**
|
||||
* Focus the preferred element in a group (primary or first focusable)
|
||||
* @param {HTMLElement} container
|
||||
* @param {Object} options
|
||||
* @param {string} options.primarySelector - CSS selector for primary element
|
||||
* @param {string} options.itemSelector - CSS selector for items
|
||||
* @returns {HTMLElement|null} The focused element, or null if none found
|
||||
*/
|
||||
export const focusPreferred = (container, options = {}) => {
|
||||
if (!container) return null
|
||||
|
||||
// First try data-nav-primary
|
||||
const primary = container.querySelector('[data-nav-primary]') ||
|
||||
(options.primarySelector && container.querySelector(options.primarySelector))
|
||||
if (primary) {
|
||||
primary.focus()
|
||||
return primary
|
||||
}
|
||||
|
||||
// Fall back to first focusable
|
||||
const items = getFocusableItems(container, options.itemSelector)
|
||||
if (items.length > 0) {
|
||||
items[0].focus()
|
||||
return items[0]
|
||||
}
|
||||
|
||||
return null
|
||||
}
|
||||
|
||||
/**
|
||||
* Focus a specific item by index in a group
|
||||
* @param {HTMLElement} container
|
||||
* @param {number} index - Index of item to focus (negative counts from end)
|
||||
* @param {Object} options
|
||||
* @param {string} options.itemSelector - CSS selector for items
|
||||
* @returns {HTMLElement|null} The focused element, or null if not found
|
||||
*/
|
||||
export const focusAtIndex = (container, index, options = {}) => {
|
||||
if (!container) return null
|
||||
|
||||
const items = getFocusableItems(container, options.itemSelector)
|
||||
if (items.length === 0) return null
|
||||
|
||||
// Support negative indices
|
||||
const resolvedIndex = index < 0 ? items.length + index : index
|
||||
if (resolvedIndex >= 0 && resolvedIndex < items.length) {
|
||||
items[resolvedIndex].focus()
|
||||
return items[resolvedIndex]
|
||||
}
|
||||
|
||||
return null
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a keydown handler for button row navigation
|
||||
* @param {Object} options
|
||||
* @param {() => HTMLElement} options.getContainer - Function returning the container element
|
||||
* @param {string} options.itemSelector - CSS selector for buttons
|
||||
* @param {(direction: string) => void} options.onBoundary - Called when navigation hits a boundary
|
||||
* @param {() => boolean} options.isDisabled - Function returning whether navigation is disabled
|
||||
* @returns {(event: KeyboardEvent) => void}
|
||||
*/
|
||||
export const createButtonRowHandler = (options) => {
|
||||
const { getContainer, itemSelector, onBoundary, isDisabled } = options
|
||||
|
||||
return (event) => {
|
||||
if (isDisabled?.()) return
|
||||
|
||||
const direction = getDirection(event)
|
||||
if (!direction) return
|
||||
|
||||
event.preventDefault()
|
||||
const container = getContainer()
|
||||
|
||||
if (direction === 'up' || direction === 'down') {
|
||||
// Vertical navigation always exits button rows
|
||||
onBoundary?.(direction)
|
||||
return
|
||||
}
|
||||
|
||||
const result = navigateButtonRow(container, event.target, direction, { itemSelector })
|
||||
if (result === 'boundary') {
|
||||
onBoundary?.(direction)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a keydown handler for grid navigation
|
||||
* @param {Object} options
|
||||
* @param {() => HTMLElement} options.getContainer - Function returning the container element
|
||||
* @param {string} options.itemSelector - CSS selector for grid items
|
||||
* @param {(direction: string) => void} options.onBoundary - Called when navigation hits a boundary
|
||||
* @param {() => boolean} options.isDisabled - Function returning whether navigation is disabled
|
||||
* @returns {(event: KeyboardEvent) => void}
|
||||
*/
|
||||
export const createGridHandler = (options) => {
|
||||
const { getContainer, itemSelector, onBoundary, isDisabled } = options
|
||||
|
||||
return (event) => {
|
||||
if (isDisabled?.()) return
|
||||
|
||||
const direction = getDirection(event)
|
||||
if (!direction) return
|
||||
|
||||
event.preventDefault()
|
||||
const container = getContainer()
|
||||
const result = navigateGrid(container, event.target, direction, { itemSelector })
|
||||
|
||||
if (result === 'boundary') {
|
||||
onBoundary?.(direction)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle escape key to navigate out of a component
|
||||
* @param {KeyboardEvent} event
|
||||
* @param {(direction: string) => void} onNavigateOut - Callback with direction
|
||||
* @param {() => boolean} isDisabled - Function returning whether navigation is disabled
|
||||
*/
|
||||
export const handleEscape = (event, onNavigateOut, isDisabled) => {
|
||||
if (isDisabled?.()) return false
|
||||
if (event.key !== 'Escape') return false
|
||||
|
||||
event.preventDefault()
|
||||
onNavigateOut?.('up')
|
||||
return true
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle delete/backspace key for item deletion
|
||||
* @param {KeyboardEvent} event
|
||||
* @param {() => void} onDelete - Callback to perform deletion
|
||||
* @returns {boolean} Whether the key was handled
|
||||
*/
|
||||
export const handleDeleteKey = (event, onDelete) => {
|
||||
const isMac = navigator.userAgent.includes('Mac OS')
|
||||
if (event.key === 'Delete' || (isMac && event.key === 'Backspace')) {
|
||||
event.preventDefault()
|
||||
onDelete?.()
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
/**
|
||||
* Focus the most appropriate button in a dialog/modal.
|
||||
* Priority: .btn-primary > .btn-secondary > any button
|
||||
* @param {HTMLElement} container - The dialog/modal container element
|
||||
* @returns {HTMLElement|null} The focused element, or null if none found
|
||||
*/
|
||||
export const focusDialogButton = (container) => {
|
||||
if (!container) return null
|
||||
|
||||
// Priority order for button selection
|
||||
const selectors = [
|
||||
'.btn-primary:not([disabled])',
|
||||
'.btn-secondary:not([disabled])',
|
||||
'button:not([disabled])'
|
||||
]
|
||||
|
||||
for (const selector of selectors) {
|
||||
const btn = container.querySelector(selector)
|
||||
if (btn) {
|
||||
btn.focus()
|
||||
return btn
|
||||
}
|
||||
}
|
||||
|
||||
return null
|
||||
}
|
||||
|
||||
/**
|
||||
* Focus the most appropriate element in a dialog/modal.
|
||||
* For dialogs with input fields (rename/edit forms): focuses first input and selects text
|
||||
* For other dialogs: focuses primary button (or fallback)
|
||||
* @param {HTMLElement} container - The dialog/modal container element
|
||||
* @returns {HTMLElement|null} The focused element, or null if none found
|
||||
*/
|
||||
export const focusDialogDefault = (container) => {
|
||||
if (!container) return null
|
||||
|
||||
// Check for input fields first (form dialogs like rename)
|
||||
const input = container.querySelector('input:not([disabled]):not([type="hidden"]), textarea:not([disabled])')
|
||||
if (input) {
|
||||
input.focus()
|
||||
// Select text for better UX in rename dialogs
|
||||
if (typeof input.select === 'function') {
|
||||
input.select()
|
||||
}
|
||||
return input
|
||||
}
|
||||
|
||||
// Fall back to button focus for non-form dialogs
|
||||
return focusDialogButton(container)
|
||||
}
|
||||
|
||||
/**
|
||||
* Standard keydown handler for button rows with left/right navigation.
|
||||
* Can be used directly on buttons or on a container with event delegation.
|
||||
* Automatically finds the .button-row or .modal-actions container.
|
||||
* @param {KeyboardEvent} event - The keydown event
|
||||
* @param {Object} options
|
||||
* @param {(direction: string) => void} options.onBoundary - Called when navigation hits a boundary (up/down or edge)
|
||||
*/
|
||||
export const handleButtonKeydown = (event, options = {}) => {
|
||||
const direction = getDirection(event)
|
||||
if (!direction) return
|
||||
|
||||
// Find the button row container
|
||||
const target = event.target
|
||||
if (target.tagName !== 'BUTTON' && target.tagName !== 'A') return
|
||||
|
||||
const container = target.closest('.button-row, .modal-actions')
|
||||
if (!container) return
|
||||
|
||||
if (direction === 'left' || direction === 'right') {
|
||||
event.preventDefault()
|
||||
const result = navigateButtonRow(container, target, direction, { itemSelector: 'button, a' })
|
||||
if (result === 'boundary') {
|
||||
options.onBoundary?.(direction)
|
||||
}
|
||||
} else if (direction === 'up' || direction === 'down') {
|
||||
// Vertical navigation exits button rows
|
||||
options.onBoundary?.(direction)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Install keyboard navigation on a container element.
|
||||
* Handles arrow key navigation for buttons within .button-row or .modal-actions.
|
||||
* Uses event delegation so no need to add handlers to individual buttons.
|
||||
* @param {HTMLElement} container - The container element to enable navigation on
|
||||
* @param {Object} options
|
||||
* @param {(direction: string) => void} options.onBoundary - Called when navigation hits a boundary
|
||||
* @returns {() => void} Cleanup function to remove the event listener
|
||||
*/
|
||||
export const installKeyboardNav = (container, options = {}) => {
|
||||
if (!container) return () => {}
|
||||
|
||||
const handler = (event) => handleButtonKeydown(event, options)
|
||||
container.addEventListener('keydown', handler)
|
||||
|
||||
return () => container.removeEventListener('keydown', handler)
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Global Automatic Keyboard Navigation
|
||||
// ============================================================================
|
||||
|
||||
/**
|
||||
* Selector for containers that should have automatic button row navigation
|
||||
*/
|
||||
const BUTTON_ROW_SELECTOR = '.button-row, .modal-actions, .actions, .role-actions, .ancillary-actions'
|
||||
|
||||
/**
|
||||
* Global keydown handler for automatic button row navigation.
|
||||
* Handles arrow key navigation for buttons/links within .button-row or .modal-actions containers.
|
||||
* @param {KeyboardEvent} event
|
||||
*/
|
||||
const globalKeydownHandler = (event) => {
|
||||
const direction = getDirection(event)
|
||||
if (!direction) return
|
||||
|
||||
// Only handle buttons and links
|
||||
const target = event.target
|
||||
if (target.tagName !== 'BUTTON' && target.tagName !== 'A') return
|
||||
|
||||
// Find the button row container
|
||||
const container = target.closest(BUTTON_ROW_SELECTOR)
|
||||
if (!container) return
|
||||
|
||||
if (direction === 'left' || direction === 'right') {
|
||||
event.preventDefault()
|
||||
navigateButtonRow(container, target, direction, { itemSelector: 'button:not([disabled]), a' })
|
||||
}
|
||||
// Note: up/down navigation is intentionally not handled globally
|
||||
// Components can add their own handlers for vertical navigation between groups
|
||||
}
|
||||
|
||||
let globalNavInitialized = false
|
||||
|
||||
/**
|
||||
* Initialize global keyboard navigation.
|
||||
* Call this once at app startup to enable automatic arrow key navigation
|
||||
* for buttons within .button-row and .modal-actions containers.
|
||||
* Safe to call multiple times (only initializes once).
|
||||
*/
|
||||
export const initKeyboardNavigation = () => {
|
||||
if (globalNavInitialized) return
|
||||
if (typeof document === 'undefined') return // SSR safety
|
||||
|
||||
document.addEventListener('keydown', globalKeydownHandler)
|
||||
globalNavInitialized = true
|
||||
}
|
||||
|
||||
/**
|
||||
* Cleanup global keyboard navigation (useful for testing).
|
||||
*/
|
||||
export const destroyKeyboardNavigation = () => {
|
||||
if (!globalNavInitialized) return
|
||||
if (typeof document === 'undefined') return
|
||||
|
||||
document.removeEventListener('keydown', globalKeydownHandler)
|
||||
globalNavInitialized = false
|
||||
}
|
||||
@@ -57,21 +57,15 @@ export async function register(resetToken = null, displayName = null, onstartreg
|
||||
export async function authenticate() {
|
||||
const ws = await aWebSocket(await makeUrl('/auth/ws/authenticate'))
|
||||
try {
|
||||
const res = await ws.receive_json()
|
||||
console.log('Authentication options:', res)
|
||||
// status field present means error
|
||||
if (res.status) {
|
||||
throw new Error(res.detail || `Authentication failed: ${res.status}`)
|
||||
}
|
||||
let res = await ws.receive_json()
|
||||
if (res.status >= 400) throw new Error(res.detail || `Authentication failed: ${res.status}`)
|
||||
|
||||
const authResponse = await startAuthentication(res)
|
||||
ws.send_json(authResponse)
|
||||
|
||||
const result = await ws.receive_json()
|
||||
if (result.status) {
|
||||
throw new Error(result.detail || `Authentication failed: ${result.status}`)
|
||||
}
|
||||
return result
|
||||
res = await ws.receive_json()
|
||||
if (res.status >= 400) throw new Error(res.detail || `Authentication failed: ${res.status}`)
|
||||
return res
|
||||
} catch (error) {
|
||||
console.error('Authentication error:', error)
|
||||
throw Error(error.name === "NotAllowedError" ? 'Passkey authentication cancelled' : error.message)
|
||||
|
||||
Reference in New Issue
Block a user