fernandes-ui 0.1.0

data/app/javascript/ui/utils/floating-ui-positioner.js

@@ -0,0 +1,282 @@
+/**
+ * Floating UI Positioner Utility
+ *
+ * Encapsulates Floating UI positioning logic.
+ * Used by popover, dropdown, tooltip, select, hover_card, etc.
+ */
+
+import { computePosition, flip, offset, shift, arrow, autoUpdate } from "@floating-ui/dom"
+
+/**
+ * Default configuration for positioning
+ */
+const DEFAULT_CONFIG = {
+  placement: 'bottom',
+  offsetValue: 4,
+  flipEnabled: true,
+  shiftEnabled: true,
+  shiftPadding: 8,
+  arrowElement: null,
+  arrowPadding: 8,
+  strategy: 'absolute',
+  // autoUpdate options
+  ancestorScroll: true,
+  ancestorResize: true,
+  elementResize: true,
+  layoutShift: true,
+  animationFrame: false
+}
+
+/**
+ * Build middleware array based on options
+ * @param {Object} options - Configuration options
+ * @returns {Array} Middleware array
+ */
+function buildMiddleware(options) {
+  const middleware = []
+
+  // Offset middleware
+  if (options.offsetValue > 0) {
+    middleware.push(offset(options.offsetValue))
+  }
+
+  // Flip middleware
+  if (options.flipEnabled) {
+    middleware.push(flip())
+  }
+
+  // Shift middleware
+  if (options.shiftEnabled) {
+    middleware.push(shift({ padding: options.shiftPadding }))
+  }
+
+  // Arrow middleware
+  if (options.arrowElement) {
+    middleware.push(arrow({
+      element: options.arrowElement,
+      padding: options.arrowPadding
+    }))
+  }
+
+  return middleware
+}
+
+/**
+ * Apply position to content element
+ * @param {HTMLElement} content - Content element
+ * @param {Object} position - Position data from computePosition
+ * @param {Object} options - Options
+ */
+function applyPosition(content, position, options = {}) {
+  const { x, y, placement, middlewareData } = position
+
+  // Apply position styles
+  Object.assign(content.style, {
+    left: `${x}px`,
+    top: `${y}px`,
+    position: options.strategy || 'absolute'
+  })
+
+  // Update data attributes
+  const [side, align] = placement.split('-')
+  content.setAttribute('data-side', side)
+  if (align) {
+    content.setAttribute('data-align', align)
+  }
+
+  // Position arrow if present
+  if (options.arrowElement && middlewareData.arrow) {
+    const { x: arrowX, y: arrowY } = middlewareData.arrow
+
+    const staticSide = {
+      top: 'bottom',
+      right: 'left',
+      bottom: 'top',
+      left: 'right'
+    }[side]
+
+    Object.assign(options.arrowElement.style, {
+      left: arrowX != null ? `${arrowX}px` : '',
+      top: arrowY != null ? `${arrowY}px` : '',
+      right: '',
+      bottom: '',
+      [staticSide]: '-4px'
+    })
+  }
+}
+
+/**
+ * Create a floating UI positioner
+ * @param {HTMLElement} reference - Reference/trigger element
+ * @param {HTMLElement} floating - Floating/content element
+ * @param {Object} options - Configuration options
+ * @returns {Object} Positioner controller
+ */
+export function createPositioner(reference, floating, options = {}) {
+  const config = { ...DEFAULT_CONFIG, ...options }
+  let cleanup = null
+  let isActive = false
+
+  const middleware = buildMiddleware(config)
+
+  const updatePosition = async () => {
+    const position = await computePosition(reference, floating, {
+      placement: config.placement,
+      middleware,
+      strategy: config.strategy
+    })
+
+    applyPosition(floating, position, {
+      strategy: config.strategy,
+      arrowElement: config.arrowElement
+    })
+
+    return position
+  }
+
+  return {
+    /**
+     * Start positioning with auto-update
+     */
+    start() {
+      if (isActive) return
+
+      // Initial position update
+      updatePosition()
+
+      // Setup auto-update
+      cleanup = autoUpdate(reference, floating, updatePosition, {
+        ancestorScroll: config.ancestorScroll,
+        ancestorResize: config.ancestorResize,
+        elementResize: config.elementResize,
+        layoutShift: config.layoutShift,
+        animationFrame: config.animationFrame
+      })
+
+      isActive = true
+    },
+
+    /**
+     * Stop positioning and cleanup
+     */
+    stop() {
+      if (!isActive) return
+
+      if (cleanup) {
+        cleanup()
+        cleanup = null
+      }
+
+      isActive = false
+    },
+
+    /**
+     * Manually update position once
+     * @returns {Promise<Object>} Position data
+     */
+    async update() {
+      return updatePosition()
+    },
+
+    /**
+     * Update placement
+     * @param {string} placement - New placement
+     */
+    setPlacement(placement) {
+      config.placement = placement
+      if (isActive) {
+        updatePosition()
+      }
+    },
+
+    /**
+     * Update offset
+     * @param {number} offsetValue - New offset value
+     */
+    setOffset(offsetValue) {
+      config.offsetValue = offsetValue
+      // Rebuild middleware with new offset
+      middleware.length = 0
+      middleware.push(...buildMiddleware(config))
+      if (isActive) {
+        updatePosition()
+      }
+    },
+
+    /**
+     * Check if positioner is active
+     * @returns {boolean}
+     */
+    isActive() {
+      return isActive
+    },
+
+    /**
+     * Get current configuration
+     * @returns {Object}
+     */
+    getConfig() {
+      return { ...config }
+    }
+  }
+}
+
+/**
+ * Simple one-liner to position and auto-update
+ * Returns cleanup function
+ * @param {HTMLElement} reference - Reference element
+ * @param {HTMLElement} floating - Floating element
+ * @param {Object} options - Configuration options
+ * @returns {Function} Cleanup function
+ */
+export function position(reference, floating, options = {}) {
+  const positioner = createPositioner(reference, floating, options)
+  positioner.start()
+  return () => positioner.stop()
+}
+
+/**
+ * Position once without auto-update
+ * @param {HTMLElement} reference - Reference element
+ * @param {HTMLElement} floating - Floating element
+ * @param {Object} options - Configuration options
+ * @returns {Promise<Object>} Position data
+ */
+export async function positionOnce(reference, floating, options = {}) {
+  const config = { ...DEFAULT_CONFIG, ...options }
+  const middleware = buildMiddleware(config)
+
+  const position = await computePosition(reference, floating, {
+    placement: config.placement,
+    middleware,
+    strategy: config.strategy
+  })
+
+  applyPosition(floating, position, {
+    strategy: config.strategy,
+    arrowElement: config.arrowElement
+  })
+
+  return position
+}
+
+/**
+ * Get placement from data attributes
+ * @param {HTMLElement} element - Element with data-side and data-align attributes
+ * @returns {string} Floating UI placement string
+ */
+export function getPlacementFromAttributes(element) {
+  const side = element.getAttribute('data-side') || 'bottom'
+  const align = element.getAttribute('data-align')
+  return align ? `${side}-${align}` : side
+}
+
+/**
+ * Parse side and align from placement
+ * @param {string} placement - Floating UI placement string
+ * @returns {Object} Object with side and align properties
+ */
+export function parsePlacement(placement) {
+  const [side, align = 'center'] = placement.split('-')
+  return { side, align }
+}

data/app/javascript/ui/utils/focus-trap-manager.js

@@ -0,0 +1,238 @@
+/**
+ * Focus Trap Manager Utility
+ *
+ * Handles focus trapping within modal components.
+ * Used by dialog, alert_dialog, drawer, responsive_dialog, etc.
+ */
+
+// Focusable elements selector
+const FOCUSABLE_SELECTOR = [
+  'button:not([disabled])',
+  '[href]',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])'
+].join(', ')
+
+// Input elements that trigger mobile keyboard
+const INPUT_SELECTOR = 'input:not([type="button"]):not([type="submit"]):not([type="reset"]):not([type="checkbox"]):not([type="radio"]), textarea'
+
+/**
+ * Get all focusable elements within a container
+ * @param {HTMLElement} container - Container to search within
+ * @returns {HTMLElement[]} Array of focusable elements
+ */
+export function getFocusableElements(container) {
+  if (!container) return []
+  return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR))
+}
+
+/**
+ * Get the first focusable element in a container
+ * @param {HTMLElement} container - Container to search within
+ * @param {Object} options - Options
+ * @param {boolean} options.skipInputs - Skip text inputs (useful for mobile to avoid keyboard popup)
+ * @returns {HTMLElement|null}
+ */
+export function getFirstFocusable(container, options = {}) {
+  const elements = getFocusableElements(container)
+
+  if (options.skipInputs) {
+    const nonInput = elements.find(el => !el.matches(INPUT_SELECTOR))
+    return nonInput || elements[0] || null
+  }
+
+  return elements[0] || null
+}
+
+/**
+ * Get the last focusable element in a container
+ * @param {HTMLElement} container - Container to search within
+ * @returns {HTMLElement|null}
+ */
+export function getLastFocusable(container) {
+  const elements = getFocusableElements(container)
+  return elements[elements.length - 1] || null
+}
+
+/**
+ * Check if the current device is mobile
+ * @returns {boolean}
+ */
+export function isMobileDevice() {
+  return /iPhone|iPad|iPod|Android/i.test(navigator.userAgent)
+}
+
+/**
+ * Focus the first appropriate element in a container
+ * @param {HTMLElement} container - Container to focus within
+ * @param {Object} options - Options
+ * @param {boolean} options.mobileAware - Skip inputs on mobile to avoid keyboard popup
+ * @param {boolean} options.excludeInputsOnMobile - Alias for mobileAware (for compatibility)
+ * @param {boolean} options.preventScroll - Pass preventScroll option to focus()
+ * @param {HTMLElement} options.preferredElement - Specific element to focus if available
+ */
+export function focusFirstElement(container, options = {}) {
+  const {
+    mobileAware = true,
+    excludeInputsOnMobile = mobileAware,
+    preventScroll = false,
+    preferredElement = null
+  } = options
+
+  const focusOptions = preventScroll ? { preventScroll: true } : undefined
+
+  // Try preferred element first
+  if (preferredElement && container.contains(preferredElement)) {
+    preferredElement.focus(focusOptions)
+    return preferredElement
+  }
+
+  // On mobile, skip text inputs to avoid keyboard popup
+  const skipInputs = excludeInputsOnMobile && isMobileDevice()
+  const element = getFirstFocusable(container, { skipInputs })
+
+  if (element) {
+    element.focus(focusOptions)
+    return element
+  }
+
+  return null
+}
+
+/**
+ * Create a focus trap for a container
+ * @param {HTMLElement} container - Container to trap focus within
+ * @param {Object} options - Options
+ * @param {boolean} options.mobileAware - Handle mobile devices specially
+ * @param {HTMLElement} options.returnFocus - Element to return focus to on deactivate
+ * @param {boolean} options.autoFocus - Whether to auto-focus first element on activate
+ * @returns {Object} Focus trap controller
+ */
+export function createFocusTrap(container, options = {}) {
+  const {
+    mobileAware = true,
+    returnFocus = null,
+    autoFocus = true
+  } = options
+
+  let isActive = false
+  let previouslyFocused = null
+  let tabHandler = null
+
+  const handleTab = (event) => {
+    if (event.key !== 'Tab') return
+
+    const focusableElements = getFocusableElements(container)
+    if (focusableElements.length === 0) return
+
+    const firstFocusable = focusableElements[0]
+    const lastFocusable = focusableElements[focusableElements.length - 1]
+
+    if (event.shiftKey) {
+      // Shift+Tab: if on first element, go to last
+      if (document.activeElement === firstFocusable) {
+        event.preventDefault()
+        lastFocusable.focus()
+      }
+    } else {
+      // Tab: if on last element, go to first
+      if (document.activeElement === lastFocusable) {
+        event.preventDefault()
+        firstFocusable.focus()
+      }
+    }
+  }
+
+  return {
+    /**
+     * Activate the focus trap
+     */
+    activate() {
+      if (isActive) return
+
+      // Store currently focused element
+      previouslyFocused = returnFocus || document.activeElement
+
+      // Add tab key handler
+      tabHandler = handleTab
+      document.addEventListener('keydown', tabHandler)
+
+      // Focus first element
+      if (autoFocus) {
+        // Delay to allow DOM to settle
+        requestAnimationFrame(() => {
+          focusFirstElement(container, { mobileAware })
+        })
+      }
+
+      isActive = true
+    },
+
+    /**
+     * Deactivate the focus trap and optionally return focus
+     */
+    deactivate() {
+      if (!isActive) return
+
+      // Remove tab handler
+      if (tabHandler) {
+        document.removeEventListener('keydown', tabHandler)
+        tabHandler = null
+      }
+
+      // Return focus to previously focused element
+      if (previouslyFocused && typeof previouslyFocused.focus === 'function') {
+        previouslyFocused.focus()
+      }
+
+      previouslyFocused = null
+      isActive = false
+    },
+
+    /**
+     * Check if trap is active
+     * @returns {boolean}
+     */
+    isActive() {
+      return isActive
+    },
+
+    /**
+     * Update the return focus element
+     * @param {HTMLElement} element
+     */
+    setReturnFocus(element) {
+      previouslyFocused = element
+    },
+
+    /**
+     * Manually focus first element
+     */
+    focusFirst() {
+      focusFirstElement(container, { mobileAware })
+    },
+
+    /**
+     * Manually focus last element
+     */
+    focusLast() {
+      const element = getLastFocusable(container)
+      if (element) element.focus()
+    }
+  }
+}
+
+/**
+ * Simple one-liner to setup focus trap
+ * Returns cleanup function
+ * @param {HTMLElement} container - Container to trap focus within
+ * @param {Object} options - Options for createFocusTrap
+ * @returns {Function} Cleanup function to deactivate trap
+ */
+export function trapFocus(container, options = {}) {
+  const trap = createFocusTrap(container, options)
+  trap.activate()
+  return () => trap.deactivate()
+}

data/app/javascript/ui/utils/index.js

@@ -0,0 +1,86 @@
+/**
+ * UI Utilities Index
+ *
+ * Export all shared utilities for controllers
+ */
+
+// State Management
+export {
+  setState,
+  getState,
+  isOpen,
+  toggleState,
+  setStateOnMultiple,
+  syncCheckedState,
+  syncPressedState,
+  syncExpandedState,
+  syncModalState,
+  createStateSynchronizer
+} from './state-manager.js'
+
+// Floating UI Positioning
+export {
+  createPositioner,
+  position,
+  positionOnce,
+  getPlacementFromAttributes,
+  parsePlacement
+} from './floating-ui-positioner.js'
+
+// Escape Key Handling
+export {
+  createEscapeKeyHandler,
+  onEscapeKey,
+  onEscapeKeyWhen
+} from './escape-key-manager.js'
+
+// Focus Trap
+export {
+  getFocusableElements,
+  getFirstFocusable,
+  getLastFocusable,
+  isMobileDevice,
+  focusFirstElement,
+  createFocusTrap,
+  trapFocus
+} from './focus-trap-manager.js'
+
+// Click Outside Detection
+export {
+  createClickOutsideHandler,
+  onClickOutside,
+  onClickOutsideWhen
+} from './click-outside-manager.js'
+
+// Scroll Lock
+export {
+  lockScroll,
+  unlockScroll,
+  forceUnlockScroll,
+  isScrollLocked,
+  getScrollLockCount,
+  resetScrollLockState,
+  createScrollLock,
+  preventTouchScroll
+} from './scroll-lock-manager.js'
+
+// Menu Utilities (existing)
+export {
+  toggleCheckbox,
+  selectRadio,
+  getFocusableItems,
+  findCurrentItemIndex,
+  focusItem,
+  focusNextItem,
+  focusPreviousItem,
+  hasSubmenu,
+  openSubmenu,
+  closeSubmenu,
+  closeAllSubmenus,
+  closeSiblingSubmenus,
+  positionDropdown,
+  positionSubmenu,
+  updateRovingTabindex,
+  clearAllTabindexes,
+  getKeyboardFocusedItem
+} from './menu_utils.js'