@proyecto-viviana/solidaria 0.2.2 → 0.2.4

package/src/interactions/createInteractionModality.ts

@@ -0,0 +1,424 @@
+/**
+ * createInteractionModality + focus-visible tracking for solidaria
+ *
+ * Port of @react-aria/interactions useFocusVisible/useInteractionModality.
+ * Tracks the current interaction modality (keyboard, pointer, or virtual) and
+ * provides focus-visible state and listeners.
+ */
+
+import { type Accessor, createSignal, createEffect, onCleanup } from 'solid-js';
+import { isServer } from 'solid-js/web';
+import { getOwnerDocument, getOwnerWindow, isMac, isVirtualClick, openLink } from '../utils';
+
+// ============================================
+// TYPES
+// ============================================
+
+export type Modality = 'keyboard' | 'pointer' | 'virtual';
+export type PointerType = 'mouse' | 'pen' | 'touch' | 'keyboard' | 'virtual';
+type HandlerEvent = PointerEvent | MouseEvent | KeyboardEvent | FocusEvent | null;
+type Handler = (modality: Modality, e: HandlerEvent) => void;
+
+export type FocusVisibleHandler = (isFocusVisible: boolean) => void;
+
+export interface FocusVisibleProps {
+  /** Whether the element is a text input. */
+  isTextInput?: boolean;
+  /** Whether the element will be auto focused. */
+  autoFocus?: boolean;
+}
+
+export interface FocusVisibleResult {
+  /** Whether keyboard focus is visible globally. */
+  isFocusVisible: Accessor<boolean>;
+}
+
+export interface InteractionModalityResult {
+  /** The current interaction modality. */
+  modality: Accessor<Modality | null>;
+}
+
+// ============================================
+// GLOBAL STATE
+// ============================================
+
+let currentModality: Modality | null = null;
+let currentPointerType: PointerType = 'keyboard';
+const changeHandlers = new Set<Handler>();
+
+export let hasSetupGlobalListeners: Map<
+  Window,
+  { focus: typeof window.HTMLElement.prototype.focus; canOverride: boolean }
+> = new Map();
+let hasEventBeforeFocus = false;
+let hasBlurredWindowRecently = false;
+let ignoreFocusEvent = false;
+
+const FOCUS_VISIBLE_INPUT_KEYS: Record<string, boolean> = {
+  Tab: true,
+  Escape: true,
+};
+
+function triggerChangeHandlers(modality: Modality, e: HandlerEvent) {
+  for (const handler of changeHandlers) {
+    handler(modality, e);
+  }
+}
+
+function isValidKey(e: KeyboardEvent) {
+  return !(
+    e.metaKey ||
+    (!isMac() && e.altKey) ||
+    e.ctrlKey ||
+    e.key === 'Control' ||
+    e.key === 'Shift' ||
+    e.key === 'Meta'
+  );
+}
+
+function handleKeyboardEvent(e: KeyboardEvent) {
+  hasEventBeforeFocus = true;
+  const isOpening = (openLink as { isOpening?: boolean }).isOpening;
+  if (!isOpening && isValidKey(e)) {
+    currentModality = 'keyboard';
+    currentPointerType = 'keyboard';
+    triggerChangeHandlers('keyboard', e);
+  }
+}
+
+function handlePointerEvent(e: PointerEvent | MouseEvent) {
+  currentModality = 'pointer';
+  currentPointerType = 'pointerType' in e ? (e.pointerType as PointerType) : 'mouse';
+  if (e.type === 'mousedown' || e.type === 'pointerdown') {
+    hasEventBeforeFocus = true;
+    triggerChangeHandlers('pointer', e);
+  }
+}
+
+function handleClickEvent(e: MouseEvent) {
+  const isOpening = (openLink as { isOpening?: boolean }).isOpening;
+  if (!isOpening && isVirtualClick(e)) {
+    hasEventBeforeFocus = true;
+    currentModality = 'virtual';
+    currentPointerType = 'virtual';
+  }
+}
+
+function handleFocusEvent(e: FocusEvent) {
+  if (!e.isTrusted || ignoreFocusEvent) {
+    return;
+  }
+
+  const target = e.target as EventTarget | null;
+  const targetElement = target && (target as Element).nodeType ? (target as Element) : null;
+  const ownerWindow = targetElement ? getOwnerWindow(targetElement) : window;
+  const ownerDocument = targetElement ? getOwnerDocument(targetElement) : document;
+
+  if (target === ownerWindow || target === ownerDocument) {
+    return;
+  }
+
+  if (!hasEventBeforeFocus && !hasBlurredWindowRecently) {
+    currentModality = 'virtual';
+    currentPointerType = 'virtual';
+    triggerChangeHandlers('virtual', e);
+  }
+
+  hasEventBeforeFocus = false;
+  hasBlurredWindowRecently = false;
+}
+
+function handleWindowBlur() {
+  if (ignoreFocusEvent) {
+    return;
+  }
+
+  hasEventBeforeFocus = false;
+  hasBlurredWindowRecently = true;
+}
+
+function setupGlobalFocusEvents(element?: HTMLElement | null) {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return;
+  }
+
+  const windowObject = getOwnerWindow(element);
+  if (hasSetupGlobalListeners.get(windowObject)) {
+    return;
+  }
+
+  const documentObject = getOwnerDocument(element);
+
+  const originalFocus = windowObject.HTMLElement.prototype.focus;
+  let canOverride = true;
+  try {
+    windowObject.HTMLElement.prototype.focus = function () {
+      hasEventBeforeFocus = true;
+      originalFocus.apply(this, arguments as unknown as [options?: FocusOptions | undefined]);
+    };
+  } catch {
+    canOverride = false;
+  }
+
+  documentObject.addEventListener('keydown', handleKeyboardEvent, true);
+  documentObject.addEventListener('keyup', handleKeyboardEvent, true);
+  documentObject.addEventListener('click', handleClickEvent, true);
+
+  windowObject.addEventListener('focus', handleFocusEvent, true);
+  windowObject.addEventListener('blur', handleWindowBlur, false);
+
+  if (typeof windowObject.PointerEvent !== 'undefined') {
+    documentObject.addEventListener('pointerdown', handlePointerEvent, true);
+    documentObject.addEventListener('pointermove', handlePointerEvent, true);
+    documentObject.addEventListener('pointerup', handlePointerEvent, true);
+  } else {
+    documentObject.addEventListener('mousedown', handlePointerEvent, true);
+    documentObject.addEventListener('mousemove', handlePointerEvent, true);
+    documentObject.addEventListener('mouseup', handlePointerEvent, true);
+  }
+
+  windowObject.addEventListener(
+    'beforeunload',
+    () => {
+      tearDownWindowFocusTracking(element);
+    },
+    { once: true }
+  );
+
+  hasSetupGlobalListeners.set(windowObject, { focus: originalFocus, canOverride });
+}
+
+function tearDownWindowFocusTracking(element?: HTMLElement | null, loadListener?: () => void) {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return;
+  }
+
+  const windowObject = getOwnerWindow(element);
+  const documentObject = getOwnerDocument(element);
+
+  if (loadListener) {
+    documentObject.removeEventListener('DOMContentLoaded', loadListener);
+  }
+
+  if (!hasSetupGlobalListeners.has(windowObject)) {
+    return;
+  }
+
+  const entry = hasSetupGlobalListeners.get(windowObject)!;
+  if (entry.canOverride) {
+    windowObject.HTMLElement.prototype.focus = entry.focus;
+  }
+
+  documentObject.removeEventListener('keydown', handleKeyboardEvent, true);
+  documentObject.removeEventListener('keyup', handleKeyboardEvent, true);
+  documentObject.removeEventListener('click', handleClickEvent, true);
+
+  windowObject.removeEventListener('focus', handleFocusEvent, true);
+  windowObject.removeEventListener('blur', handleWindowBlur, false);
+
+  if (typeof windowObject.PointerEvent !== 'undefined') {
+    documentObject.removeEventListener('pointerdown', handlePointerEvent, true);
+    documentObject.removeEventListener('pointermove', handlePointerEvent, true);
+    documentObject.removeEventListener('pointerup', handlePointerEvent, true);
+  } else {
+    documentObject.removeEventListener('mousedown', handlePointerEvent, true);
+    documentObject.removeEventListener('mousemove', handlePointerEvent, true);
+    documentObject.removeEventListener('mouseup', handlePointerEvent, true);
+  }
+
+  hasSetupGlobalListeners.delete(windowObject);
+}
+
+/**
+ * Adds a window (i.e. iframe) to the list of windows that are being tracked for focus visible.
+ */
+export function addWindowFocusTracking(element?: HTMLElement | null): () => void {
+  const documentObject = getOwnerDocument(element);
+  let loadListener: (() => void) | undefined;
+
+  if (documentObject.readyState !== 'loading') {
+    setupGlobalFocusEvents(element);
+  } else {
+    loadListener = () => {
+      setupGlobalFocusEvents(element);
+    };
+    documentObject.addEventListener('DOMContentLoaded', loadListener);
+  }
+
+  return () => tearDownWindowFocusTracking(element, loadListener);
+}
+
+export function setupGlobalFocusListeners(): void {
+  addWindowFocusTracking();
+}
+
+if (typeof document !== 'undefined') {
+  addWindowFocusTracking();
+}
+
+/**
+ * If true, keyboard focus is visible.
+ */
+export function isFocusVisible(): boolean {
+  return currentModality !== 'pointer';
+}
+
+/**
+ * Gets the current interaction modality.
+ */
+export function getInteractionModality(): Modality | null {
+  return currentModality;
+}
+
+/**
+ * Sets the current interaction modality.
+ */
+export function setInteractionModality(modality: Modality): void {
+  currentModality = modality;
+  currentPointerType = modality === 'pointer' ? 'mouse' : modality;
+  triggerChangeHandlers(modality, null);
+}
+
+/**
+ * Gets the current pointer type.
+ */
+export function getPointerType(): PointerType {
+  return currentPointerType;
+}
+
+function isKeyboardFocusEvent(
+  isTextInput: boolean,
+  modality: Modality,
+  e: HandlerEvent
+): boolean {
+  if (!e) {
+    return true;
+  }
+
+  const target = 'target' in e ? (e.target as Element | null) : null;
+  const ownerDocument = target ? getOwnerDocument(target) : document;
+  const ownerWindow = target ? getOwnerWindow(target) : window;
+
+  const IHTMLInputElement = ownerWindow.HTMLInputElement;
+  const IHTMLTextAreaElement = ownerWindow.HTMLTextAreaElement;
+  const IHTMLElement = ownerWindow.HTMLElement;
+  const IKeyboardEvent = ownerWindow.KeyboardEvent;
+
+  const nonTextInputTypes = new Set([
+    'checkbox',
+    'radio',
+    'range',
+    'color',
+    'file',
+    'image',
+    'button',
+    'submit',
+    'reset',
+  ]);
+
+  isTextInput =
+    isTextInput ||
+    (ownerDocument.activeElement instanceof IHTMLInputElement &&
+      !nonTextInputTypes.has(ownerDocument.activeElement.type)) ||
+    ownerDocument.activeElement instanceof IHTMLTextAreaElement ||
+    (ownerDocument.activeElement instanceof IHTMLElement && ownerDocument.activeElement.isContentEditable);
+
+  return !(
+    isTextInput &&
+    modality === 'keyboard' &&
+    e instanceof IKeyboardEvent &&
+    !FOCUS_VISIBLE_INPUT_KEYS[e.key]
+  );
+}
+
+/**
+ * Listens for trigger change and reports if focus is visible.
+ */
+export function createFocusVisibleListener(
+  handler: FocusVisibleHandler,
+  opts?: { isTextInput?: boolean }
+): () => void {
+  setupGlobalFocusEvents();
+  const listener: Handler = (modality: Modality, e: HandlerEvent) => {
+    if (!isKeyboardFocusEvent(!!opts?.isTextInput, modality, e)) {
+      return;
+    }
+    handler(isFocusVisible());
+  };
+  changeHandlers.add(listener);
+  return () => {
+    changeHandlers.delete(listener);
+  };
+}
+
+/**
+ * Manages focus visible state for the page.
+ */
+export function createFocusVisible(props: FocusVisibleProps = {}): FocusVisibleResult {
+  if (isServer) {
+    return { isFocusVisible: () => false };
+  }
+
+  const { isTextInput, autoFocus } = props;
+  const [isVisible, setIsVisible] = createSignal<boolean>(autoFocus || isFocusVisible());
+
+  createEffect(() => {
+    const cleanup = createFocusVisibleListener(setIsVisible, { isTextInput });
+    onCleanup(cleanup);
+  });
+
+  return { isFocusVisible: isVisible };
+}
+
+/**
+ * Tracks the current interaction modality.
+ */
+export function createInteractionModality(): InteractionModalityResult {
+  if (isServer) {
+    return {
+      modality: () => null,
+    };
+  }
+
+  const [modality, setModality] = createSignal<Modality | null>(currentModality);
+
+  createEffect(() => {
+    setupGlobalFocusEvents();
+    const handler: Handler = (newModality: Modality) => {
+      setModality(newModality);
+    };
+    changeHandlers.add(handler);
+    onCleanup(() => {
+      changeHandlers.delete(handler);
+    });
+  });
+
+  return {
+    modality,
+  };
+}
+
+/**
+ * Adds a listener for modality changes.
+ */
+export function addModalityListener(handler: (modality: Modality) => void): () => void {
+  const wrapped: Handler = (modality) => {
+    handler(modality);
+  };
+  changeHandlers.add(wrapped);
+  return () => {
+    changeHandlers.delete(wrapped);
+  };
+}
+
+/**
+ * Hook to track whether the user is currently interacting with the keyboard.
+ */
+export function useIsKeyboardFocused(): Accessor<boolean> {
+  if (isServer) {
+    return () => false;
+  }
+
+  const { modality } = createInteractionModality();
+  return () => modality() === 'keyboard';
+}

package/src/interactions/createKeyboard.ts

@@ -0,0 +1,82 @@
+/**
+ * createKeyboard - Handles keyboard interactions for a focusable element.
+ *
+ * This is a 1-1 port of React-Aria's useKeyboard hook adapted for SolidJS.
+ */
+
+import { JSX } from 'solid-js';
+
+/**
+ * Keyboard event with continuePropagation support.
+ * By default, keyboard events stop propagation.
+ */
+export interface KeyboardEvent extends globalThis.KeyboardEvent {
+  /** Call this to allow the event to propagate to parent elements. */
+  continuePropagation(): void;
+}
+
+export interface KeyboardEvents {
+  /** Handler that is called when a key is pressed. */
+  onKeyDown?: (e: KeyboardEvent) => void;
+  /** Handler that is called when a key is released. */
+  onKeyUp?: (e: KeyboardEvent) => void;
+}
+
+export interface CreateKeyboardProps extends KeyboardEvents {
+  /** Whether the keyboard events should be disabled. */
+  isDisabled?: boolean;
+}
+
+export interface KeyboardResult {
+  /** Props to spread onto the target element. */
+  keyboardProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+/**
+ * Wraps a keyboard event handler to make stopPropagation the default,
+ * and support continuePropagation instead.
+ */
+function createEventHandler<T extends globalThis.KeyboardEvent>(
+  handler?: (e: KeyboardEvent) => void
+): ((e: T) => void) | undefined {
+  if (!handler) {
+    return undefined;
+  }
+
+  return (e: T) => {
+    let shouldStopPropagation = true;
+
+    // Create a wrapped event with continuePropagation
+    const event = Object.assign(e, {
+      continuePropagation() {
+        shouldStopPropagation = false;
+      },
+    }) as KeyboardEvent;
+
+    handler(event);
+
+    if (shouldStopPropagation) {
+      e.stopPropagation();
+    }
+  };
+}
+
+/**
+ * Handles keyboard interactions for a focusable element.
+ *
+ * Based on react-aria's useKeyboard but adapted for SolidJS.
+ */
+export function createKeyboard(props: CreateKeyboardProps = {}): KeyboardResult {
+  if (props.isDisabled) {
+    return {
+      keyboardProps: {},
+    };
+  }
+
+  return {
+    keyboardProps: {
+      onKeyDown: createEventHandler(props.onKeyDown),
+      onKeyUp: createEventHandler(props.onKeyUp),
+    },
+  };
+}

package/src/interactions/createLongPress.ts

@@ -0,0 +1,174 @@
+/**
+ * createLongPress - Handles long press interactions across mouse and touch.
+ *
+ * Port of @react-aria/interactions useLongPress, adapted for SolidJS.
+ */
+
+import { JSX, onCleanup } from 'solid-js';
+import { createPress, type PressEvent } from './createPress';
+import { mergeProps, focusWithoutScrolling, createGlobalListeners } from '../utils';
+import { createDescription } from '../utils/createDescription';
+import { type MaybeAccessor } from '../utils/reactivity';
+
+export interface LongPressEvent {
+  /** The type of long press event being fired. */
+  type: 'longpressstart' | 'longpressend' | 'longpress';
+  /** The pointer type that triggered the long press. */
+  pointerType: PressEvent['pointerType'];
+  /** The target element of the long press event. */
+  target: Element;
+  /** Whether the shift keyboard modifier was held during the long press event. */
+  shiftKey: boolean;
+  /** Whether the ctrl keyboard modifier was held during the long press event. */
+  ctrlKey: boolean;
+  /** Whether the meta keyboard modifier was held during the long press event. */
+  metaKey: boolean;
+  /** Whether the alt keyboard modifier was held during the long press event. */
+  altKey: boolean;
+  /** X position relative to the target. */
+  x: number;
+  /** Y position relative to the target. */
+  y: number;
+}
+
+export interface LongPressProps {
+  /** Whether long press events should be disabled. */
+  isDisabled?: MaybeAccessor<boolean>;
+  /** Handler that is called when a long press interaction starts. */
+  onLongPressStart?: (e: LongPressEvent) => void;
+  /**
+   * Handler that is called when a long press interaction ends, either
+   * over the target or when the pointer leaves the target.
+   */
+  onLongPressEnd?: (e: LongPressEvent) => void;
+  /**
+   * Handler that is called when the threshold time is met while
+   * the press is over the target.
+   */
+  onLongPress?: (e: LongPressEvent) => void;
+  /**
+   * The amount of time in milliseconds to wait before triggering a long press.
+   * @default 500ms
+   */
+  threshold?: number;
+  /**
+   * A description for assistive technology users indicating that a long press
+   * action is available, e.g. "Long press to open menu".
+   */
+  accessibilityDescription?: string;
+}
+
+export interface LongPressResult {
+  /** Props to spread on the target element. */
+  longPressProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+const DEFAULT_THRESHOLD = 500;
+
+function isDisabledValue(isDisabled: MaybeAccessor<boolean> | undefined): boolean {
+  return typeof isDisabled === 'function' ? isDisabled() : !!isDisabled;
+}
+
+function createLongPressEvent(type: LongPressEvent['type'], e: PressEvent): LongPressEvent {
+  return {
+    type,
+    pointerType: e.pointerType,
+    target: e.target,
+    shiftKey: e.shiftKey,
+    ctrlKey: e.ctrlKey,
+    metaKey: e.metaKey,
+    altKey: e.altKey,
+    x: e.x,
+    y: e.y,
+  };
+}
+
+/**
+ * Handles long press interactions across mouse and touch devices.
+ */
+export function createLongPress(props: LongPressProps = {}): LongPressResult {
+  const {
+    isDisabled,
+    onLongPressStart,
+    onLongPressEnd,
+    onLongPress,
+    threshold = DEFAULT_THRESHOLD,
+    accessibilityDescription,
+  } = props;
+
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  const { addGlobalListener } = createGlobalListeners();
+
+  const { pressProps } = createPress({
+    isDisabled,
+    onPressStart(e) {
+      e.continuePropagation();
+      if (e.pointerType === 'mouse' || e.pointerType === 'touch') {
+        onLongPressStart?.(createLongPressEvent('longpressstart', e));
+
+        timeoutId = setTimeout(() => {
+          // Prevent other press handlers from also handling this event.
+          e.target.dispatchEvent(new PointerEvent('pointercancel', { bubbles: true }));
+
+          // Ensure target is focused. On touch devices, browsers typically focus on pointer up.
+          if (document.activeElement !== e.target) {
+            focusWithoutScrolling(e.target as HTMLElement);
+          }
+
+          onLongPress?.(createLongPressEvent('longpress', e));
+          timeoutId = undefined;
+        }, threshold);
+
+        if (e.pointerType === 'touch') {
+          const onContextMenu = (event: Event) => {
+            event.preventDefault();
+          };
+          const target = e.target as HTMLElement;
+          target.addEventListener('contextmenu', onContextMenu, { once: true });
+
+          addGlobalListener(
+            'pointerup',
+            () => {
+              setTimeout(() => {
+                target.removeEventListener('contextmenu', onContextMenu);
+              }, 30);
+            },
+            { isWindow: true, once: true }
+          );
+        }
+      }
+    },
+    onPressEnd(e) {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = undefined;
+      }
+
+      if (onLongPressEnd && (e.pointerType === 'mouse' || e.pointerType === 'touch')) {
+        onLongPressEnd(createLongPressEvent('longpressend', e));
+      }
+    },
+  });
+
+  const descriptionProps = createDescription(() =>
+    onLongPress && !isDisabledValue(isDisabled) ? accessibilityDescription : undefined
+  );
+
+  onCleanup(() => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = undefined;
+    }
+  });
+
+  const longPressProps = mergeProps(pressProps) as JSX.HTMLAttributes<HTMLElement>;
+  Object.defineProperty(longPressProps, 'aria-describedby', {
+    get: () => descriptionProps['aria-describedby'],
+    enumerable: true,
+    configurable: true,
+  });
+
+  return {
+    longPressProps,
+  };
+}