@proyecto-viviana/solidaria 0.1.3 → 0.2.0

package/src/focus/FocusScope.tsx

@@ -1,408 +0,0 @@
-/**
- * FocusScope component for managing focus containment, restoration, and auto-focus.
- * Based on @react-aria/focus FocusScope.
- */
-
-import {
-  createContext,
-  useContext,
-  createEffect,
-  onCleanup,
-  type JSX,
-  type Accessor,
-  type ParentComponent,
-  createSignal,
-  onMount,
-} from 'solid-js'
-import { isServer } from 'solid-js/web'
-import { getOwnerDocument, isFocusable } from '../utils'
-import { focusSafely } from '../utils/focus'
-
-// ============================================
-// TYPES
-// ============================================
-
-export interface FocusScopeProps {
-  /** The contents of the focus scope. */
-  children: JSX.Element
-  /**
-   * Whether to contain focus inside the scope, so users cannot
-   * move focus outside, for example in a modal dialog.
-   */
-  contain?: boolean
-  /**
-   * Whether to restore focus back to the element that was focused
-   * when the focus scope mounted, after the focus scope unmounts.
-   */
-  restoreFocus?: boolean
-  /** Whether to auto focus the first focusable element in the focus scope on mount. */
-  autoFocus?: boolean
-}
-
-export interface FocusManagerOptions {
-  /** The element to start searching from. The currently focused element by default. */
-  from?: Element
-  /** Whether to only include tabbable elements, or all focusable elements. */
-  tabbable?: boolean
-  /** Whether focus should wrap around when it reaches the end of the scope. */
-  wrap?: boolean
-  /** A callback that determines whether the given element is focused. */
-  accept?: (node: Element) => boolean
-}
-
-export interface FocusManager {
-  /** Moves focus to the next focusable or tabbable element in the focus scope. */
-  focusNext(opts?: FocusManagerOptions): HTMLElement | null
-  /** Moves focus to the previous focusable or tabbable element in the focus scope. */
-  focusPrevious(opts?: FocusManagerOptions): HTMLElement | null
-  /** Moves focus to the first focusable or tabbable element in the focus scope. */
-  focusFirst(opts?: FocusManagerOptions): HTMLElement | null
-  /** Moves focus to the last focusable or tabbable element in the focus scope. */
-  focusLast(opts?: FocusManagerOptions): HTMLElement | null
-}
-
-// ============================================
-// CONTEXT
-// ============================================
-
-interface FocusScopeContextValue {
-  focusManager: FocusManager
-  scopeRef: Accessor<Element[]>
-}
-
-const FocusScopeContext = createContext<FocusScopeContextValue | null>(null)
-
-/**
- * Returns a FocusManager interface for the parent FocusScope.
- * A FocusManager can be used to programmatically move focus within
- * a FocusScope, e.g. in response to user events like keyboard navigation.
- */
-export function useFocusManager(): FocusManager | undefined {
-  return useContext(FocusScopeContext)?.focusManager
-}
-
-// ============================================
-// UTILITIES
-// ============================================
-
-/**
- * Checks if an element is tabbable (focusable via Tab key).
- */
-function isTabbable(element: Element): boolean {
-  if (!isFocusable(element)) {
-    return false
-  }
-
-  // Check tabIndex
-  const tabIndex = element.getAttribute('tabindex')
-  if (tabIndex != null) {
-    return parseInt(tabIndex, 10) >= 0
-  }
-
-  return true
-}
-
-/**
- * Gets all focusable elements within a scope.
- */
-function getFocusableElements(scope: Element[], tabbable = false): HTMLElement[] {
-  const elements: HTMLElement[] = []
-  const filter = tabbable ? isTabbable : isFocusable
-
-  for (const scopeElement of scope) {
-    // Check the element itself
-    if (filter(scopeElement)) {
-      elements.push(scopeElement as HTMLElement)
-    }
-
-    // Check all descendants
-    const descendants = scopeElement.querySelectorAll('*')
-    for (let i = 0; i < descendants.length; i++) {
-      const el = descendants[i]
-      if (filter(el)) {
-        elements.push(el as HTMLElement)
-      }
-    }
-  }
-
-  return elements
-}
-
-/**
- * Checks if an element is within a scope.
- */
-function isElementInScope(element: Element | null, scope: Element[]): boolean {
-  if (!element) return false
-  return scope.some(node => node.contains(element))
-}
-
-/**
- * Gets the active element, accounting for shadow DOM.
- */
-function getActiveElement(doc: Document): Element | null {
-  let activeElement = doc.activeElement
-  while (activeElement?.shadowRoot?.activeElement) {
-    activeElement = activeElement.shadowRoot.activeElement
-  }
-  return activeElement
-}
-
-// ============================================
-// FOCUS SCOPE COMPONENT
-// ============================================
-
-/**
- * A FocusScope manages focus for its descendants. It supports containing focus inside
- * the scope, restoring focus to the previously focused element on unmount, and auto
- * focusing children on mount. It also acts as a container for a programmatic focus
- * management interface that can be used to move focus forward and back in response
- * to user events.
- */
-export const FocusScope: ParentComponent<FocusScopeProps> = (props) => {
-  if (isServer) {
-    return <>{props.children}</>
-  }
-
-  let startRef: HTMLSpanElement | undefined
-  let endRef: HTMLSpanElement | undefined
-  const [scopeElements, setScopeElements] = createSignal<Element[]>([])
-
-  // Store the element that was focused when the scope mounted
-  let nodeToRestore: Element | null = null
-
-  // Create focus manager
-  const focusManager: FocusManager = {
-    focusNext(opts = {}) {
-      const scope = scopeElements()
-      if (scope.length === 0) return null
-
-      const { from, tabbable = true, wrap = false, accept } = opts
-      const elements = getFocusableElements(scope, tabbable).filter(el => !accept || accept(el))
-      const doc = getOwnerDocument(scope[0])
-      const current = from || getActiveElement(doc)
-
-      if (!current || elements.length === 0) return null
-
-      const currentIndex = elements.indexOf(current as HTMLElement)
-      let nextIndex = currentIndex + 1
-
-      if (nextIndex >= elements.length) {
-        if (wrap) {
-          nextIndex = 0
-        } else {
-          return null
-        }
-      }
-
-      const nextElement = elements[nextIndex]
-      if (nextElement) {
-        focusSafely(nextElement)
-        return nextElement
-      }
-
-      return null
-    },
-
-    focusPrevious(opts = {}) {
-      const scope = scopeElements()
-      if (scope.length === 0) return null
-
-      const { from, tabbable = true, wrap = false, accept } = opts
-      const elements = getFocusableElements(scope, tabbable).filter(el => !accept || accept(el))
-      const doc = getOwnerDocument(scope[0])
-      const current = from || getActiveElement(doc)
-
-      if (!current || elements.length === 0) return null
-
-      const currentIndex = elements.indexOf(current as HTMLElement)
-      let prevIndex = currentIndex - 1
-
-      if (prevIndex < 0) {
-        if (wrap) {
-          prevIndex = elements.length - 1
-        } else {
-          return null
-        }
-      }
-
-      const prevElement = elements[prevIndex]
-      if (prevElement) {
-        focusSafely(prevElement)
-        return prevElement
-      }
-
-      return null
-    },
-
-    focusFirst(opts = {}) {
-      const scope = scopeElements()
-      if (scope.length === 0) return null
-
-      const { tabbable = true, accept } = opts
-      const elements = getFocusableElements(scope, tabbable).filter(el => !accept || accept(el))
-
-      if (elements.length > 0) {
-        focusSafely(elements[0])
-        return elements[0]
-      }
-
-      return null
-    },
-
-    focusLast(opts = {}) {
-      const scope = scopeElements()
-      if (scope.length === 0) return null
-
-      const { tabbable = true, accept } = opts
-      const elements = getFocusableElements(scope, tabbable).filter(el => !accept || accept(el))
-
-      if (elements.length > 0) {
-        const lastElement = elements[elements.length - 1]
-        focusSafely(lastElement)
-        return lastElement
-      }
-
-      return null
-    },
-  }
-
-  // Collect scope elements after render
-  onMount(() => {
-    if (!startRef || !endRef) return
-
-    const nodes: Element[] = []
-    let node = startRef.nextSibling
-    while (node && node !== endRef) {
-      if (node.nodeType === Node.ELEMENT_NODE) {
-        nodes.push(node as Element)
-      }
-      node = node.nextSibling
-    }
-    setScopeElements(nodes)
-  })
-
-  // Save the currently focused element for restoration (must happen before autoFocus/contain effects run).
-  onMount(() => {
-    if (!props.restoreFocus) return
-
-    // Focus can be in the main document, or inside this iframe's document.
-    const scopeDoc = startRef ? getOwnerDocument(startRef) : document
-    const scopeActive = getActiveElement(scopeDoc)
-    const topActive = getActiveElement(document)
-
-    // If the scope is in an iframe and that iframe is currently focused, prefer the iframe document's active element.
-    if (
-      scopeDoc !== document &&
-      document.activeElement instanceof HTMLIFrameElement &&
-      document.activeElement.contentDocument === scopeDoc &&
-      scopeActive &&
-      scopeActive !== scopeDoc.body
-    ) {
-      nodeToRestore = scopeActive
-      return
-    }
-
-    nodeToRestore = topActive
-  })
-
-  // Auto-focus first element
-  createEffect(() => {
-    if (!props.autoFocus) return
-
-    const scope = scopeElements()
-    if (scope.length === 0) return
-
-    const doc = getOwnerDocument(scope[0])
-    const activeElement = getActiveElement(doc)
-
-    // Only auto-focus if focus is not already inside the scope
-    if (!isElementInScope(activeElement, scope)) {
-      focusManager.focusFirst()
-    }
-  })
-
-  // Focus containment
-  createEffect(() => {
-    if (!props.contain) return
-
-    const scope = scopeElements()
-    if (scope.length === 0) return
-
-    const doc = getOwnerDocument(scope[0])
-    let focusedNode: Element | null = null
-
-    const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key !== 'Tab' || e.altKey || e.ctrlKey || e.metaKey) {
-        return
-      }
-
-      const scope = scopeElements()
-      const activeElement = getActiveElement(doc)
-      if (!isElementInScope(activeElement, scope)) {
-        return
-      }
-
-      const elements = getFocusableElements(scope, true)
-      if (elements.length === 0) return
-
-      const firstElement = elements[0]
-      const lastElement = elements[elements.length - 1]
-
-      if (e.shiftKey && activeElement === firstElement) {
-        e.preventDefault()
-        focusSafely(lastElement)
-      } else if (!e.shiftKey && activeElement === lastElement) {
-        e.preventDefault()
-        focusSafely(firstElement)
-      }
-    }
-
-    const onFocusIn = (e: FocusEvent) => {
-      const scope = scopeElements()
-      const target = e.target as Element
-
-      if (isElementInScope(target, scope)) {
-        focusedNode = target
-      } else if (focusedNode) {
-        // Focus escaped the scope, bring it back
-        focusSafely(focusedNode as HTMLElement)
-      } else {
-        // No previous focus, focus first element
-        focusManager.focusFirst()
-      }
-    }
-
-    doc.addEventListener('keydown', onKeyDown, true)
-    doc.addEventListener('focusin', onFocusIn, true)
-
-    onCleanup(() => {
-      doc.removeEventListener('keydown', onKeyDown, true)
-      doc.removeEventListener('focusin', onFocusIn, true)
-    })
-  })
-
-  // Restore focus on unmount
-  onCleanup(() => {
-    if (props.restoreFocus && nodeToRestore && (nodeToRestore as HTMLElement).focus) {
-      const doc = getOwnerDocument(nodeToRestore as Element)
-      const win = doc.defaultView ?? window
-
-      // Use requestAnimationFrame to ensure the element is still in the DOM
-      win.requestAnimationFrame(() => {
-        if (nodeToRestore && doc.body.contains(nodeToRestore as Node)) {
-          ;(nodeToRestore as HTMLElement).focus()
-        }
-      })
-    }
-  })
-
-  return (
-    <FocusScopeContext.Provider value={{ focusManager, scopeRef: scopeElements }}>
-      <span data-focus-scope-start hidden ref={startRef} />
-      {props.children}
-      <span data-focus-scope-end hidden ref={endRef} />
-    </FocusScopeContext.Provider>
-  )
-}
-
-export default FocusScope

package/src/focus/createAutoFocus.ts

@@ -1,321 +0,0 @@
-/**
- * Auto-focus management for solidaria
- *
- * Provides priority-based auto-focus with deferred execution
- * and conflict resolution for multiple auto-focus elements.
- */
-
-import { createEffect, onCleanup, onMount } from 'solid-js';
-import { isServer } from 'solid-js/web';
-import { focusSafely } from '../utils/focus';
-
-// ============================================
-// TYPES
-// ============================================
-
-export interface AutoFocusOptions {
-  /**
-   * Whether auto-focus is enabled.
-   * @default true
-   */
-  isEnabled?: boolean;
-  /**
-   * Priority level (higher = more important).
-   * When multiple elements request auto-focus, the highest priority wins.
-   * @default 0
-   */
-  priority?: number;
-  /**
-   * Delay in milliseconds before focusing.
-   * Useful for animations or transitions.
-   * @default 0
-   */
-  delay?: number;
-  /**
-   * Whether to focus even if another element is already focused.
-   * @default false
-   */
-  force?: boolean;
-  /**
-   * Whether to prevent scrolling when focusing.
-   * @default true
-   */
-  preventScroll?: boolean;
-  /**
-   * Callback when focus is applied.
-   */
-  onFocus?: (element: HTMLElement) => void;
-  /**
-   * Callback when focus is skipped (due to lower priority or other reasons).
-   */
-  onSkip?: () => void;
-}
-
-export interface AutoFocusResult {
-  /**
-   * Manually trigger the auto-focus.
-   */
-  focus: () => void;
-  /**
-   * Cancel any pending auto-focus.
-   */
-  cancel: () => void;
-}
-
-// ============================================
-// AUTO-FOCUS QUEUE
-// ============================================
-
-interface QueuedFocus {
-  ref: () => HTMLElement | null | undefined;
-  priority: number;
-  delay: number;
-  force: boolean;
-  preventScroll: boolean;
-  onFocus?: (element: HTMLElement) => void;
-  onSkip?: () => void;
-}
-
-// Global queue for managing auto-focus requests
-let autoFocusQueue: QueuedFocus[] = [];
-let processingTimeout: ReturnType<typeof setTimeout> | null = null;
-
-/**
- * Process the auto-focus queue and focus the highest priority element.
- */
-function processAutoFocusQueue(): void {
-  if (processingTimeout) {
-    clearTimeout(processingTimeout);
-    processingTimeout = null;
-  }
-
-  if (autoFocusQueue.length === 0) return;
-
-  // Sort by priority (highest first)
-  autoFocusQueue.sort((a, b) => b.priority - a.priority);
-
-  // Get the highest priority item
-  const winner = autoFocusQueue[0];
-  const losers = autoFocusQueue.slice(1);
-
-  // Clear the queue
-  autoFocusQueue = [];
-
-  // Notify losers
-  for (const loser of losers) {
-    loser.onSkip?.();
-  }
-
-  // Focus the winner
-  const element = winner.ref();
-  if (!element) {
-    winner.onSkip?.();
-    return;
-  }
-
-  // Check if we should focus
-  const activeElement = document.activeElement;
-  const shouldFocus =
-    winner.force ||
-    !activeElement ||
-    activeElement === document.body ||
-    activeElement === document.documentElement;
-
-  if (!shouldFocus) {
-    winner.onSkip?.();
-    return;
-  }
-
-  // Apply focus with optional delay
-  if (winner.delay > 0) {
-    setTimeout(() => {
-      const el = winner.ref();
-      if (el && document.body.contains(el)) {
-        if (winner.preventScroll) {
-          focusSafely(el);
-        } else {
-          el.focus();
-        }
-        winner.onFocus?.(el);
-      }
-    }, winner.delay);
-  } else {
-    if (winner.preventScroll) {
-      focusSafely(element);
-    } else {
-      element.focus();
-    }
-    winner.onFocus?.(element);
-  }
-}
-
-/**
- * Queue an element for auto-focus.
- */
-function queueAutoFocus(item: QueuedFocus): void {
-  autoFocusQueue.push(item);
-
-  // Schedule processing on next frame to allow all components to register
-  if (processingTimeout === null) {
-    processingTimeout = setTimeout(processAutoFocusQueue, 0);
-  }
-}
-
-/**
- * Remove an item from the auto-focus queue.
- */
-function removeFromQueue(ref: () => HTMLElement | null | undefined): void {
-  autoFocusQueue = autoFocusQueue.filter((item) => item.ref !== ref);
-}
-
-// ============================================
-// HOOK
-// ============================================
-
-/**
- * Creates auto-focus behavior for an element.
- *
- * This hook registers the element for auto-focus when mounted. If multiple
- * elements request auto-focus, the one with the highest priority wins.
- *
- * @param ref - Accessor for the element to focus
- * @param options - Auto-focus options
- *
- * @example
- * ```tsx
- * function Dialog(props) {
- *   let contentRef: HTMLDivElement | undefined;
- *
- *   createAutoFocus(() => contentRef, {
- *     priority: 10, // High priority for dialogs
- *     onFocus: () => console.log('Dialog focused'),
- *   });
- *
- *   return (
- *     <div ref={contentRef} tabIndex={-1}>
- *       {props.children}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * ```tsx
- * // With delay for animations
- * function AnimatedPanel() {
- *   let panelRef: HTMLDivElement | undefined;
- *
- *   createAutoFocus(() => panelRef, {
- *     delay: 300, // Wait for animation
- *   });
- *
- *   return <div ref={panelRef} class="animated-panel">...</div>;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Conditional auto-focus
- * function Input(props) {
- *   let inputRef: HTMLInputElement | undefined;
- *
- *   createAutoFocus(() => inputRef, {
- *     isEnabled: props.autoFocus,
- *   });
- *
- *   return <input ref={inputRef} />;
- * }
- * ```
- */
-export function createAutoFocus(
-  ref: () => HTMLElement | null | undefined,
-  options: AutoFocusOptions = {}
-): AutoFocusResult {
-  const {
-    isEnabled = true,
-    priority = 0,
-    delay = 0,
-    force = false,
-    preventScroll = true,
-    onFocus,
-    onSkip,
-  } = options;
-
-  // During SSR, return no-op functions
-  if (isServer) {
-    return {
-      focus: () => {},
-      cancel: () => {},
-    };
-  }
-
-  let canceled = false;
-
-  // Queue auto-focus on mount
-  onMount(() => {
-    if (!isEnabled || canceled) return;
-
-    queueAutoFocus({
-      ref,
-      priority,
-      delay,
-      force,
-      preventScroll,
-      onFocus,
-      onSkip,
-    });
-  });
-
-  // Remove from queue on cleanup
-  onCleanup(() => {
-    removeFromQueue(ref);
-  });
-
-  const focus = (): void => {
-    if (canceled) return;
-
-    const element = ref();
-    if (!element) return;
-
-    if (preventScroll) {
-      focusSafely(element);
-    } else {
-      element.focus();
-    }
-    onFocus?.(element);
-  };
-
-  const cancel = (): void => {
-    canceled = true;
-    removeFromQueue(ref);
-  };
-
-  return {
-    focus,
-    cancel,
-  };
-}
-
-// ============================================
-// UTILITIES
-// ============================================
-
-/**
- * Clears all pending auto-focus requests.
- * Useful for testing or when navigating away.
- */
-export function clearAutoFocusQueue(): void {
-  if (processingTimeout) {
-    clearTimeout(processingTimeout);
-    processingTimeout = null;
-  }
-  autoFocusQueue = [];
-}
-
-/**
- * Gets the current auto-focus queue length.
- * Useful for debugging.
- */
-export function getAutoFocusQueueLength(): number {
-  return autoFocusQueue.length;
-}