@proyecto-viviana/solidaria 0.0.1 → 0.0.2

package/src/interactions/createFocus.ts

@@ -0,0 +1,157 @@
+/**
+ * createFocus - Handles focus events for the immediate target.
+ *
+ * This is a 1-1 port of React-Aria's useFocus hook adapted for SolidJS.
+ * Focus events on child elements will be ignored.
+ */
+
+import { JSX, onCleanup } from 'solid-js';
+import { getOwnerDocument, getEventTarget } from '../utils';
+
+export interface FocusEvents {
+  /** Handler that is called when the element receives focus. */
+  onFocus?: (e: FocusEvent) => void;
+  /** Handler that is called when the element loses focus. */
+  onBlur?: (e: FocusEvent) => void;
+  /** Handler that is called when the element's focus status changes. */
+  onFocusChange?: (isFocused: boolean) => void;
+}
+
+export interface CreateFocusProps extends FocusEvents {
+  /** Whether the focus events should be disabled. */
+  isDisabled?: boolean;
+}
+
+export interface FocusResult {
+  /** Props to spread onto the target element. */
+  focusProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+/**
+ * Synthetic blur event handler for Firefox bug workaround.
+ * React (and we) don't fire onBlur when an element is disabled.
+ * Most browsers fire a native focusout event in this case, except for Firefox.
+ * We use a MutationObserver to watch for the disabled attribute.
+ */
+function createSyntheticBlurHandler(
+  onBlur: ((e: FocusEvent) => void) | undefined
+): (_e: FocusEvent, target: Element) => (() => void) | undefined {
+  let isFocused = false;
+  let observer: MutationObserver | null = null;
+
+  return (_e: FocusEvent, target: Element) => {
+    if (
+      target instanceof HTMLButtonElement ||
+      target instanceof HTMLInputElement ||
+      target instanceof HTMLTextAreaElement ||
+      target instanceof HTMLSelectElement
+    ) {
+      isFocused = true;
+
+      const onBlurHandler = (blurEvent: Event) => {
+        isFocused = false;
+
+        if ((target as HTMLButtonElement).disabled && onBlur) {
+          onBlur(blurEvent as FocusEvent);
+        }
+
+        if (observer) {
+          observer.disconnect();
+          observer = null;
+        }
+      };
+
+      target.addEventListener('focusout', onBlurHandler, { once: true });
+
+      observer = new MutationObserver(() => {
+        if (isFocused && (target as HTMLButtonElement).disabled) {
+          observer?.disconnect();
+          const relatedTarget = target === document.activeElement ? null : document.activeElement;
+          target.dispatchEvent(new FocusEvent('blur', { relatedTarget }));
+          target.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget }));
+        }
+      });
+
+      observer.observe(target, { attributes: true, attributeFilter: ['disabled'] });
+
+      // Return cleanup function
+      return () => {
+        if (observer) {
+          observer.disconnect();
+          observer = null;
+        }
+      };
+    }
+
+    return undefined;
+  };
+}
+
+/**
+ * Handles focus events for the immediate target.
+ * Focus events on child elements will be ignored.
+ *
+ * Based on react-aria's useFocus but adapted for SolidJS.
+ */
+export function createFocus(props: CreateFocusProps = {}): FocusResult {
+  const { isDisabled, onFocus: onFocusProp, onBlur: onBlurProp, onFocusChange } = props;
+
+  let cleanupRef: (() => void) | undefined;
+  const syntheticBlurHandler = createSyntheticBlurHandler(onBlurProp);
+
+  // Cleanup on unmount
+  onCleanup(() => {
+    if (cleanupRef) {
+      cleanupRef();
+    }
+  });
+
+  const onBlur: JSX.EventHandler<HTMLElement, FocusEvent> = (e) => {
+    // Only handle if target is the currentTarget (not bubbled from children)
+    if (e.target === e.currentTarget) {
+      if (onBlurProp) {
+        onBlurProp(e);
+      }
+
+      if (onFocusChange) {
+        onFocusChange(false);
+      }
+    }
+  };
+
+  const onFocus: JSX.EventHandler<HTMLElement, FocusEvent> = (e) => {
+    // Double check that document.activeElement actually matches e.target
+    // in case a previously chained focus handler already moved focus somewhere else.
+    const ownerDocument = getOwnerDocument(e.target);
+    const activeElement = ownerDocument?.activeElement;
+
+    if (e.target === e.currentTarget && activeElement === getEventTarget(e)) {
+      if (onFocusProp) {
+        onFocusProp(e);
+      }
+
+      if (onFocusChange) {
+        onFocusChange(true);
+      }
+
+      // Set up synthetic blur handler for Firefox bug
+      cleanupRef = syntheticBlurHandler(e, e.target);
+    }
+  };
+
+  // If disabled or no handlers, return empty props
+  if (isDisabled) {
+    return {
+      focusProps: {},
+    };
+  }
+
+  const hasHandlers = onFocusProp || onFocusChange || onBlurProp;
+
+  return {
+    focusProps: {
+      onFocus: hasHandlers ? onFocus : undefined,
+      onBlur: onBlurProp || onFocusChange ? onBlur : undefined,
+    },
+  };
+}

package/src/interactions/createFocusRing.ts

@@ -0,0 +1,142 @@
+/**
+ * createFocusRing hook for Solidaria
+ *
+ * Determines whether a focus ring should be visible for a given element.
+ * Focus rings are visible when the user navigates with keyboard, but hidden
+ * when using mouse/touch.
+ *
+ * Port of @react-aria/focus useFocusRing.
+ */
+
+import { type JSX, type Accessor, createSignal, createEffect, onCleanup } from 'solid-js';
+import { createFocus } from './createFocus';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface FocusRingProps {
+  /** Whether the element is a text input. */
+  isTextInput?: boolean;
+  /** Whether the element will be auto focused. */
+  autoFocus?: boolean;
+  /** Whether focus should be tracked within the element. */
+  within?: boolean;
+}
+
+export interface FocusRingResult {
+  /** Whether the element is currently focused. */
+  isFocused: Accessor<boolean>;
+  /** Whether the focus ring should be visible. */
+  isFocusVisible: Accessor<boolean>;
+  /** Props to spread on the element to track focus. */
+  focusProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+// ============================================
+// GLOBAL STATE
+// ============================================
+
+type Modality = 'keyboard' | 'pointer' | 'virtual';
+
+let currentModality: Modality | null = null;
+let hasSetupGlobalListeners = false;
+let changeHandlers = new Set<(modality: Modality) => void>();
+
+function triggerChangeHandlers(modality: Modality) {
+  currentModality = modality;
+  for (const handler of changeHandlers) {
+    handler(modality);
+  }
+}
+
+function handleKeyboardEvent(e: KeyboardEvent) {
+  // Ignore modifier keys
+  if (e.metaKey || e.altKey || e.ctrlKey || e.key === 'Control' || e.key === 'Shift' || e.key === 'Meta') {
+    return;
+  }
+  currentModality = 'keyboard';
+  triggerChangeHandlers('keyboard');
+}
+
+function handlePointerEvent(e: PointerEvent | MouseEvent) {
+  currentModality = 'pointer';
+  if (e.type === 'mousedown' || e.type === 'pointerdown') {
+    triggerChangeHandlers('pointer');
+  }
+}
+
+function setupGlobalFocusListeners() {
+  if (typeof document === 'undefined' || hasSetupGlobalListeners) {
+    return;
+  }
+
+  hasSetupGlobalListeners = true;
+
+  // Track keyboard vs pointer modality
+  document.addEventListener('keydown', handleKeyboardEvent, true);
+  document.addEventListener('keyup', handleKeyboardEvent, true);
+  document.addEventListener('mousedown', handlePointerEvent, true);
+  document.addEventListener('pointerdown', handlePointerEvent, true);
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Determines whether a focus ring should be visible for a given element.
+ *
+ * Focus rings are visible when:
+ * - The element is focused AND
+ * - The user is navigating with keyboard (not mouse/touch)
+ *
+ * For text inputs, focus rings are always visible when focused.
+ */
+export function createFocusRing(props: FocusRingProps = {}): FocusRingResult {
+  const { isTextInput = false, autoFocus = false } = props;
+
+  const [isFocused, setIsFocused] = createSignal(false);
+  const [isFocusVisible, setIsFocusVisible] = createSignal(autoFocus);
+  const [modality, setModality] = createSignal<Modality | null>(currentModality);
+
+  // Setup global listeners
+  createEffect(() => {
+    setupGlobalFocusListeners();
+
+    const handler = (newModality: Modality) => {
+      setModality(newModality);
+    };
+
+    changeHandlers.add(handler);
+    onCleanup(() => {
+      changeHandlers.delete(handler);
+    });
+  });
+
+  // Update focus visible based on modality and focus state
+  createEffect(() => {
+    const focused = isFocused();
+    const mod = modality();
+
+    if (focused) {
+      // Text inputs always show focus ring when focused
+      // Otherwise, only show if last interaction was keyboard
+      setIsFocusVisible(isTextInput || mod === 'keyboard');
+    } else {
+      setIsFocusVisible(false);
+    }
+  });
+
+  // Use createFocus to track focus state
+  const focusResult = createFocus({
+    onFocus: () => setIsFocused(true),
+    onBlur: () => setIsFocused(false),
+  });
+
+  return {
+    isFocused,
+    isFocusVisible,
+    focusProps: focusResult.focusProps as JSX.HTMLAttributes<HTMLElement>,
+  };
+}

package/src/interactions/createFocusWithin.ts

@@ -0,0 +1,141 @@
+/**
+ * createFocusWithin - Handles focus events for the target and its descendants.
+ *
+ * This is a 1-1 port of React-Aria's useFocusWithin hook adapted for SolidJS.
+ */
+
+import { JSX, onCleanup } from 'solid-js';
+import { getOwnerDocument, getEventTarget, nodeContains, createGlobalListeners } from '../utils';
+import { setEventTarget } from '../utils/events';
+
+export interface FocusWithinProps {
+  /** Whether the focus within events should be disabled. */
+  isDisabled?: boolean;
+  /** Handler that is called when the target element or a descendant receives focus. */
+  onFocusWithin?: (e: FocusEvent) => void;
+  /** Handler that is called when the target element and all descendants lose focus. */
+  onBlurWithin?: (e: FocusEvent) => void;
+  /** Handler that is called when the focus within state changes. */
+  onFocusWithinChange?: (isFocusWithin: boolean) => void;
+}
+
+export interface FocusWithinResult {
+  /** Props to spread onto the target element. */
+  focusWithinProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+/**
+ * Handles focus events for the target and its descendants.
+ *
+ * Based on react-aria's useFocusWithin but adapted for SolidJS.
+ */
+export function createFocusWithin(props: FocusWithinProps = {}): FocusWithinResult {
+  const { isDisabled, onBlurWithin, onFocusWithin, onFocusWithinChange } = props;
+
+  // State tracking
+  let isFocusWithin = false;
+
+  // Global listeners manager
+  const { addGlobalListener, removeAllGlobalListeners } = createGlobalListeners();
+
+  // Cleanup on unmount
+  onCleanup(() => {
+    removeAllGlobalListeners();
+  });
+
+  const onBlur: JSX.EventHandler<HTMLElement, FocusEvent> = (e) => {
+    // Ignore events bubbling through portals
+    if (!e.currentTarget.contains(e.target as Node)) {
+      return;
+    }
+
+    // We don't want to trigger onBlurWithin and then immediately onFocusWithin again
+    // when moving focus inside the element. Only trigger if the currentTarget doesn't
+    // include the relatedTarget (where focus is moving).
+    if (isFocusWithin && !e.currentTarget.contains(e.relatedTarget as Node)) {
+      isFocusWithin = false;
+      removeAllGlobalListeners();
+
+      if (onBlurWithin) {
+        onBlurWithin(e);
+      }
+
+      if (onFocusWithinChange) {
+        onFocusWithinChange(false);
+      }
+    }
+  };
+
+  const onFocus: JSX.EventHandler<HTMLElement, FocusEvent> = (e) => {
+    // Ignore events bubbling through portals
+    if (!e.currentTarget.contains(e.target as Node)) {
+      return;
+    }
+
+    // Double check that document.activeElement actually matches e.target
+    // in case a previously chained focus handler already moved focus somewhere else.
+    const ownerDocument = getOwnerDocument(e.target);
+    const activeElement = ownerDocument?.activeElement;
+
+    if (!isFocusWithin && activeElement === getEventTarget(e)) {
+      if (onFocusWithin) {
+        onFocusWithin(e);
+      }
+
+      if (onFocusWithinChange) {
+        onFocusWithinChange(true);
+      }
+
+      isFocusWithin = true;
+
+      // Browsers don't fire blur events when elements are removed from the DOM.
+      // However, if a focus event occurs outside the element we're tracking, we
+      // can manually fire onBlur.
+      const currentTarget = e.currentTarget;
+
+      addGlobalListener(
+        'focus',
+        (focusEvent: Event) => {
+          if (isFocusWithin && !nodeContains(currentTarget, (focusEvent as FocusEvent).target as Element)) {
+            // Create a synthetic blur event
+            const window = ownerDocument?.defaultView;
+            if (window) {
+              const nativeEvent = new window.FocusEvent('blur', {
+                relatedTarget: (focusEvent as FocusEvent).target as Element,
+              });
+              setEventTarget(nativeEvent, currentTarget);
+
+              isFocusWithin = false;
+              removeAllGlobalListeners();
+
+              if (onBlurWithin) {
+                onBlurWithin(nativeEvent);
+              }
+
+              if (onFocusWithinChange) {
+                onFocusWithinChange(false);
+              }
+            }
+          }
+        },
+        { capture: true }
+      );
+    }
+  };
+
+  if (isDisabled) {
+    return {
+      focusWithinProps: {
+        onFocus: undefined,
+        onBlur: undefined,
+      },
+    };
+  }
+
+  return {
+    focusWithinProps: {
+      onFocus,
+      onBlur,
+    },
+  };
+}

package/src/interactions/createFocusable.ts

@@ -0,0 +1,168 @@
+/**
+ * createFocusable - Makes an element focusable and capable of auto focus.
+ *
+ * This is a 1-1 port of React-Aria's useFocusable hook adapted for SolidJS.
+ */
+
+import { JSX, Accessor, createContext, useContext, onMount } from 'solid-js';
+import { createFocus, type FocusEvents } from './createFocus';
+import { createKeyboard, type KeyboardEvents } from './createKeyboard';
+import { mergeProps, focusSafely } from '../utils';
+
+export interface FocusableDOMProps {
+  /** Whether to exclude the element from the sequential tab order. */
+  excludeFromTabOrder?: boolean;
+}
+
+export interface FocusableProps extends FocusEvents, KeyboardEvents {
+  /** Whether the element should receive focus on mount. */
+  autoFocus?: boolean;
+}
+
+export interface CreateFocusableProps extends FocusableProps, FocusableDOMProps {
+  /** Whether focus should be disabled. */
+  isDisabled?: Accessor<boolean> | boolean;
+}
+
+export interface FocusableResult {
+  /** Props to spread on the focusable element. */
+  focusableProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+// --- FocusableContext ---
+
+export interface FocusableContextValue {
+  ref?: (el: HTMLElement) => void;
+  [key: string]: unknown;
+}
+
+/**
+ * Context for passing focusable props to nested focusable children.
+ * Used by FocusableProvider to pass DOM props to the nearest focusable child.
+ */
+export const FocusableContext = createContext<FocusableContextValue | null>(null);
+
+/**
+ * Hook to consume the FocusableContext and sync the ref.
+ */
+function useFocusableContext(
+  setRef: (el: HTMLElement) => void
+): Omit<FocusableContextValue, 'ref'> {
+  const context = useContext(FocusableContext) || {};
+
+  // If context has a ref, sync our ref to it
+  if (context.ref) {
+    const contextRef = context.ref;
+    // Create a combined ref that calls both
+    const originalSetRef = setRef;
+    setRef = (el: HTMLElement) => {
+      originalSetRef(el);
+      contextRef(el);
+    };
+  }
+
+  // Return context without the ref
+  const { ref: _, ...otherProps } = context;
+  return otherProps;
+}
+
+export interface FocusableProviderProps {
+  /** The child element to provide DOM props to. */
+  children?: JSX.Element;
+}
+
+function isDisabledValue(isDisabled: Accessor<boolean> | boolean | undefined): boolean {
+  if (typeof isDisabled === 'function') {
+    return isDisabled();
+  }
+  return isDisabled ?? false;
+}
+
+/**
+ * Makes an element focusable, handling disabled state and tab order.
+ * Provides focus state tracking and autoFocus support.
+ *
+ * Based on react-aria's useFocusable but adapted for SolidJS.
+ *
+ * @example
+ * ```tsx
+ * import { createFocusable } from 'solidaria';
+ *
+ * function FocusableInput(props) {
+ *   let ref;
+ *   const { focusableProps } = createFocusable({
+ *     autoFocus: props.autoFocus,
+ *     onFocusChange: (focused) => console.log('Focus:', focused),
+ *   });
+ *
+ *   return (
+ *     <input
+ *       {...focusableProps}
+ *       ref={(el) => { ref = el; focusableProps.ref?.(el); }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function createFocusable(
+  props: CreateFocusableProps = {},
+  ref?: (el: HTMLElement) => void
+): FocusableResult {
+  let elementRef: HTMLElement | null = null;
+  let autoFocusDone = false;
+
+  // Set up ref handler
+  const setRef = (el: HTMLElement) => {
+    elementRef = el;
+    ref?.(el);
+  };
+
+  // Get focus and keyboard props from the respective hooks
+  const { focusProps } = createFocus({
+    isDisabled: isDisabledValue(props.isDisabled),
+    onFocus: props.onFocus,
+    onBlur: props.onBlur,
+    onFocusChange: props.onFocusChange,
+  });
+
+  const { keyboardProps } = createKeyboard({
+    isDisabled: isDisabledValue(props.isDisabled),
+    onKeyDown: props.onKeyDown,
+    onKeyUp: props.onKeyUp,
+  });
+
+  // Merge focus and keyboard interactions
+  const interactions = mergeProps(focusProps, keyboardProps);
+
+  // Get context props (from FocusableProvider if present)
+  const contextProps = useFocusableContext(setRef);
+  const interactionProps = isDisabledValue(props.isDisabled) ? {} : contextProps;
+
+  // Handle autoFocus
+  onMount(() => {
+    if (props.autoFocus && elementRef && !autoFocusDone) {
+      focusSafely(elementRef);
+      autoFocusDone = true;
+    }
+  });
+
+  // Always set a tabIndex so that Safari allows focusing native buttons and inputs.
+  let tabIndex: number | undefined = props.excludeFromTabOrder ? -1 : 0;
+  if (isDisabledValue(props.isDisabled)) {
+    tabIndex = undefined;
+  }
+
+  // Build final focusable props
+  const focusableProps = mergeProps(
+    {
+      ...interactions,
+      tabIndex,
+      ref: setRef,
+    },
+    interactionProps
+  ) as JSX.HTMLAttributes<HTMLElement>;
+
+  return {
+    focusableProps,
+  };
+}