@proyecto-viviana/solidaria 0.2.2 → 0.2.4

package/src/utils/createDescription.ts

@@ -0,0 +1,137 @@
+/**
+ * createDescription - Creates a hidden element for dynamic aria-describedby content.
+ *
+ * This utility creates a visually hidden element containing description text and
+ * returns an aria-describedby prop pointing to it. Multiple components using the
+ * same description will share the same element (reference counted).
+ *
+ * Port of @react-aria/utils/useDescription.
+ *
+ * @example
+ * ```tsx
+ * function SortableColumn(props) {
+ *   const descriptionProps = createDescription(
+ *     () => props.sortDirection ? `Sorted ${props.sortDirection}` : undefined
+ *   );
+ *
+ *   return (
+ *     <th {...descriptionProps}>
+ *       {props.children}
+ *     </th>
+ *   );
+ * }
+ * ```
+ */
+
+import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
+import { isServer } from 'solid-js/web';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface DescriptionProps {
+  'aria-describedby'?: string;
+}
+
+// ============================================
+// STATE
+// ============================================
+
+let descriptionId = 0;
+const descriptionNodes = new Map<string, { refCount: number; element: Element }>();
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Creates an invisible description element and returns aria-describedby props.
+ *
+ * The element is created in the DOM and reference counted - multiple uses of
+ * the same description text will share the same element. When all references
+ * are removed, the element is cleaned up.
+ *
+ * @param description - Accessor that returns the description text, or undefined
+ * @returns Object with aria-describedby prop (or empty object if no description)
+ *
+ * @example
+ * ```tsx
+ * const descProps = createDescription(() => 'Press Enter to submit');
+ * return <button {...descProps}>Submit</button>;
+ * ```
+ */
+export function createDescription(description: Accessor<string | undefined>): DescriptionProps {
+  // SSR: return empty object
+  if (isServer) {
+    return {};
+  }
+
+  const [id, setId] = createSignal<string | undefined>();
+
+  createEffect(() => {
+    const desc = description();
+
+    if (!desc) {
+      setId(undefined);
+      return;
+    }
+
+    let node = descriptionNodes.get(desc);
+
+    if (!node) {
+      // Create new description element
+      const newId = `solidaria-description-${descriptionId++}`;
+      setId(newId);
+
+      const element = document.createElement('div');
+      element.id = newId;
+      element.style.display = 'none';
+      element.textContent = desc;
+      document.body.appendChild(element);
+
+      node = { refCount: 0, element };
+      descriptionNodes.set(desc, node);
+    } else {
+      // Reuse existing element
+      setId(node.element.id);
+    }
+
+    node.refCount++;
+
+    // Cleanup when description changes or component unmounts
+    onCleanup(() => {
+      if (node && --node.refCount === 0) {
+        node.element.remove();
+        descriptionNodes.delete(desc);
+      }
+    });
+  });
+
+  // Return reactive props object
+  return {
+    get 'aria-describedby'() {
+      const desc = description();
+      return desc ? id() : undefined;
+    },
+  };
+}
+
+/**
+ * Utility to get all active description nodes (for testing).
+ * @internal
+ */
+export function getDescriptionNodeCount(): number {
+  return descriptionNodes.size;
+}
+
+/**
+ * Utility to clear all description nodes (for testing cleanup).
+ * @internal
+ */
+export function clearDescriptionNodes(): void {
+  for (const [, node] of descriptionNodes) {
+    node.element.remove();
+  }
+  descriptionNodes.clear();
+}

package/src/utils/dom.ts

@@ -0,0 +1,327 @@
+/**
+ * DOM utilities for cross-browser compatibility.
+ * Based on @react-aria/utils DOM utilities.
+ */
+
+/**
+ * Gets the owner document of an element, or the global document.
+ */
+export function getOwnerDocument(el: Element | null | undefined): Document {
+  return el?.ownerDocument ?? document;
+}
+
+/**
+ * Gets the owner window of an element, or the global window.
+ */
+export function getOwnerWindow(el: Element | null | undefined): Window & typeof globalThis {
+  return getOwnerDocument(el).defaultView ?? window;
+}
+
+/**
+ * Cross-browser implementation of Node.contains that works with ShadowDOM.
+ * In Safari, Node.contains doesn't properly detect elements inside shadow roots.
+ */
+export function nodeContains(parent: Node | null, child: Node | null): boolean {
+  if (!parent || !child) {
+    return false;
+  }
+
+  // Standard contains check
+  if (parent.contains(child)) {
+    return true;
+  }
+
+  // Check if child is in a shadow root
+  let node: Node | null = child;
+  while (node) {
+    if (node === parent) {
+      return true;
+    }
+
+    // Check shadow root host
+    if ((node as ShadowRoot).host) {
+      node = (node as ShadowRoot).host;
+    } else {
+      node = node.parentNode;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Gets the event target, handling composed path for shadow DOM.
+ */
+export function getEventTarget<T extends EventTarget>(event: Event): T | null {
+  // Use composedPath to get the real target when using Shadow DOM
+  if (typeof event.composedPath === 'function') {
+    const path = event.composedPath();
+    if (path.length > 0) {
+      return path[0] as T;
+    }
+  }
+  return event.target as T | null;
+}
+
+/**
+ * Checks if an element is a valid focusable element.
+ */
+export function isFocusable(element: Element): boolean {
+  // Check if element is disabled
+  if ((element as HTMLInputElement).disabled) {
+    return false;
+  }
+
+  // Check native focusable elements
+  const tagName = element.tagName.toLowerCase();
+  if (['input', 'select', 'textarea', 'button', 'a', 'area'].includes(tagName)) {
+    // For anchor elements, they must have href to be focusable
+    if (tagName === 'a' || tagName === 'area') {
+      return element.hasAttribute('href');
+    }
+    return true;
+  }
+
+  // Check for tabIndex
+  const tabIndex = element.getAttribute('tabindex');
+  if (tabIndex != null && tabIndex !== '-1') {
+    return true;
+  }
+
+  // Check for contenteditable
+  if (element.hasAttribute('contenteditable') && element.getAttribute('contenteditable') !== 'false') {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Checks if a keyboard event should trigger the default action (like clicking).
+ */
+export function isValidKeyboardEvent(event: KeyboardEvent, currentTarget: Element): boolean {
+  const { key, code } = event;
+  const element = currentTarget as HTMLElement;
+  const tagName = element.tagName.toLowerCase();
+  const role = element.getAttribute('role');
+
+  // Only accept Enter and Space
+  const isActivationKey = key === 'Enter' || key === ' ' || key === 'Spacebar' || code === 'Space';
+  if (!isActivationKey) {
+    return false;
+  }
+
+  // Text inputs should handle their own keyboard events
+  if (tagName === 'textarea') {
+    return false;
+  }
+
+  // Content editable elements should handle their own keyboard events
+  if (element.isContentEditable) {
+    return false;
+  }
+
+  // Links should only respond to Enter, not Space
+  const isLink = role === 'link' || (!role && isHTMLAnchorLink(element));
+  if (isLink && key !== 'Enter') {
+    return false;
+  }
+
+  // Input elements have specific key handling
+  if (tagName === 'input') {
+    return isValidInputKey(element as HTMLInputElement, key);
+  }
+
+  return true;
+}
+
+/**
+ * Checks if a key is valid for a specific input type.
+ */
+export function isValidInputKey(target: HTMLInputElement, key: string): boolean {
+  const type = target.type.toLowerCase();
+
+  // Checkbox and radio only respond to Space
+  if (type === 'checkbox' || type === 'radio') {
+    return key === ' ' || key === 'Spacebar';
+  }
+
+  // Text-like inputs handle their own keyboard events
+  const textInputTypes = [
+    'text', 'search', 'url', 'tel', 'email', 'password',
+    'date', 'month', 'week', 'time', 'datetime-local', 'number'
+  ];
+  if (textInputTypes.includes(type)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Checks if an element is an HTML anchor link (has href attribute).
+ */
+export function isHTMLAnchorLink(target: Element): boolean {
+  return target.tagName === 'A' && target.hasAttribute('href');
+}
+
+/**
+ * Whether to prevent default on keyboard events for this element.
+ */
+export function shouldPreventDefaultKeyboard(target: Element, key: string): boolean {
+  const tagName = target.tagName.toLowerCase();
+
+  // Never prevent default on inputs - they handle their own behavior
+  if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+    return false;
+  }
+
+  // Don't prevent default on links for Enter (native navigation)
+  if ((tagName === 'a' || target.getAttribute('role') === 'link') && key === 'Enter') {
+    return false;
+  }
+
+  // Buttons with submit/reset type should not prevent default
+  if (tagName === 'button') {
+    const type = (target as HTMLButtonElement).type;
+    if (type === 'submit' || type === 'reset') {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Whether to prevent default on pointer up for this element.
+ */
+export function shouldPreventDefaultUp(target: Element): boolean {
+  const tagName = target.tagName.toLowerCase();
+
+  // Never prevent default on form elements
+  if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+    return false;
+  }
+
+  // Don't prevent default on links
+  if (tagName === 'a' || target.getAttribute('role') === 'link') {
+    return false;
+  }
+
+  // Buttons with submit/reset type should not prevent default
+  if (tagName === 'button') {
+    const type = (target as HTMLButtonElement).type;
+    if (type === 'submit' || type === 'reset') {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Opens a link, supporting both same-window and new-window navigation.
+ * Used for keyboard activation of links with Space key (which doesn't natively open links).
+ */
+export function openLink(target: HTMLAnchorElement, event: Event, allowOpener = false): void {
+  const { href, target: linkTarget, rel } = target;
+  (openLink as { isOpening?: boolean }).isOpening = true;
+
+  // Handle modifier keys for open-in-new-tab behavior
+  const keyEvent = event as KeyboardEvent;
+  const shouldOpenInNewTab =
+    linkTarget === '_blank' ||
+    keyEvent?.metaKey ||
+    keyEvent?.ctrlKey ||
+    keyEvent?.shiftKey ||
+    keyEvent?.altKey;
+
+  if (shouldOpenInNewTab) {
+    const features = !allowOpener && rel?.includes('noopener') ? 'noopener' : undefined;
+    window.open(href, linkTarget || '_blank', features);
+  } else {
+    window.location.href = href;
+  }
+
+  (openLink as { isOpening?: boolean }).isOpening = false;
+}
+
+(openLink as { isOpening?: boolean }).isOpening = false;
+
+// ============================================
+// Scroll utilities
+// ============================================
+
+/**
+ * Checks if an element is scrollable based on its overflow style.
+ * @param node - The element to check
+ * @param checkForOverflow - If true, also check if the element actually overflows
+ */
+export function isScrollable(node: Element | null, checkForOverflow?: boolean): boolean {
+  if (!node) {
+    return false;
+  }
+
+  const style = window.getComputedStyle(node);
+  const scrollable = /(auto|scroll)/.test(style.overflow + style.overflowX + style.overflowY);
+
+  if (scrollable && checkForOverflow) {
+    return node.scrollHeight !== node.clientHeight || node.scrollWidth !== node.clientWidth;
+  }
+
+  return scrollable;
+}
+
+/**
+ * Gets the nearest scrollable parent element.
+ * @param node - The starting element
+ * @param checkForOverflow - If true, only return parents that actually overflow
+ */
+export function getScrollParent(node: Element, checkForOverflow?: boolean): Element {
+  let scrollableNode: Element | null = node;
+
+  if (isScrollable(scrollableNode, checkForOverflow)) {
+    scrollableNode = scrollableNode.parentElement;
+  }
+
+  while (scrollableNode && !isScrollable(scrollableNode, checkForOverflow)) {
+    scrollableNode = scrollableNode.parentElement;
+  }
+
+  return scrollableNode || document.scrollingElement || document.documentElement;
+}
+
+/**
+ * Checks if an element will open a virtual keyboard when focused.
+ * Used for iOS Safari scroll handling.
+ */
+export function willOpenKeyboard(target: Element | null): boolean {
+  if (!target) {
+    return false;
+  }
+
+  const tagName = target.tagName.toLowerCase();
+
+  // Inputs that open keyboard (not all input types do)
+  if (tagName === 'input') {
+    const type = (target as HTMLInputElement).type.toLowerCase();
+    // These input types open the keyboard
+    const keyboardTypes = [
+      'text', 'search', 'url', 'tel', 'email', 'password',
+      'date', 'month', 'week', 'time', 'datetime-local', 'number'
+    ];
+    return keyboardTypes.includes(type);
+  }
+
+  // Textareas always open keyboard
+  if (tagName === 'textarea') {
+    return true;
+  }
+
+  // Contenteditable elements open keyboard
+  if (target.hasAttribute('contenteditable') && target.getAttribute('contenteditable') !== 'false') {
+    return true;
+  }
+
+  return false;
+}

package/src/utils/env.ts

@@ -0,0 +1,54 @@
+/**
+ * Environment detection utilities.
+ * These avoid direct references to process.env which can cause TypeScript issues in browser environments.
+ * Compatible with Node.js, Deno, and Vite environments.
+ */
+
+// Type-safe access to import.meta.env (Vite) and Deno.env
+declare const Deno: { env?: { get(key: string): string | undefined } } | undefined;
+
+function getEnvVar(key: string): string | undefined {
+  // Check Vite's import.meta.env
+  if (typeof import.meta !== 'undefined' && (import.meta as any).env) {
+    return (import.meta as any).env[key];
+  }
+  // Check Deno
+  if (typeof Deno !== 'undefined' && Deno.env) {
+    return Deno.env.get(key);
+  }
+  // Check Node.js process.env via globalThis
+  if (typeof globalThis !== 'undefined' && (globalThis as any).process?.env) {
+    return (globalThis as any).process.env[key];
+  }
+  return undefined;
+}
+
+/**
+ * Check if we're running in a test environment.
+ */
+export function isTestEnv(): boolean {
+  return getEnvVar('NODE_ENV') === 'test';
+}
+
+/**
+ * Check if we're running in a development environment (not production).
+ */
+export function isDevEnv(): boolean {
+  // Check Vite's DEV flag
+  if (typeof import.meta !== 'undefined' && (import.meta as any).env?.DEV) {
+    return true;
+  }
+  const nodeEnv = getEnvVar('NODE_ENV');
+  return nodeEnv !== 'production';
+}
+
+/**
+ * Check if we're running in production.
+ */
+export function isProdEnv(): boolean {
+  // Check Vite's PROD flag
+  if (typeof import.meta !== 'undefined' && (import.meta as any).env?.PROD) {
+    return true;
+  }
+  return getEnvVar('NODE_ENV') === 'production';
+}

package/src/utils/events.ts

@@ -0,0 +1,106 @@
+/**
+ * Event utilities for detecting virtual clicks and event handling.
+ * Based on @react-aria/utils event utilities.
+ */
+
+import { isAndroid } from './platform';
+
+/**
+ * Checks if a click event was generated from a virtual source like a screen reader.
+ * Virtual clicks typically have detail of 0 and may have zero coordinates.
+ */
+export function isVirtualClick(event: MouseEvent | PointerEvent): boolean {
+  // JAWS/NVDA with Firefox.
+  if ((event as PointerEvent).pointerType === '' && event.isTrusted) {
+    return true;
+  }
+
+  // Android TalkBack's detail value varies depending on the event listener providing the event.
+  // If pointerType is defined, event is from a click listener.
+  if (isAndroid() && (event as PointerEvent).pointerType) {
+    return event.type === 'click' && (event as MouseEvent).buttons === 1;
+  }
+
+  return event.detail === 0 && !(event as PointerEvent).pointerType;
+}
+
+/**
+ * Checks if a pointer event was generated by a virtual source.
+ * iOS VoiceOver fires pointer events with incorrect coordinates.
+ * These events have zero width/height.
+ */
+export function isVirtualPointerEvent(event: PointerEvent): boolean {
+  // If the pointer size is zero, then we assume it's from a screen reader.
+  // Android TalkBack double tap will sometimes return a event with width and height of 1
+  // and pointerType === 'mouse' so we need to check for a specific combination of event attributes.
+  // Cannot use "event.pressure === 0" as the sole check due to Safari pointer events always returning pressure === 0.
+  return (
+    (!isAndroid() && event.width === 0 && event.height === 0) ||
+    (event.width === 1 &&
+      event.height === 1 &&
+      event.pressure === 0 &&
+      event.detail === 0 &&
+      event.pointerType === 'mouse')
+  );
+}
+
+/**
+ * Creates a synthetic mouse event for programmatic clicking.
+ */
+export function createMouseEvent(type: string, nativeEvent?: Event): MouseEvent {
+  const init: MouseEventInit = {
+    bubbles: true,
+    cancelable: true,
+    view: window,
+  };
+
+  // Copy properties from the native event if provided
+  if (nativeEvent) {
+    const e = nativeEvent as MouseEvent;
+    init.screenX = e.screenX;
+    init.screenY = e.screenY;
+    init.clientX = e.clientX;
+    init.clientY = e.clientY;
+    init.ctrlKey = e.ctrlKey;
+    init.shiftKey = e.shiftKey;
+    init.altKey = e.altKey;
+    init.metaKey = e.metaKey;
+    init.button = e.button;
+    init.buttons = e.buttons;
+    init.relatedTarget = e.relatedTarget;
+  }
+
+  return new MouseEvent(type, init);
+}
+
+/**
+ * Creates a chain of event handlers that calls each in sequence.
+ */
+export function chain<T extends (...args: any[]) => any>(
+  ...callbacks: (T | undefined | null)[]
+): T {
+  return ((...args: Parameters<T>) => {
+    for (const callback of callbacks) {
+      if (typeof callback === 'function') {
+        callback(...args);
+      }
+    }
+  }) as T;
+}
+
+/**
+ * Sets the target property on an event object.
+ * Used for synthetic events where target needs to be modified.
+ */
+export function setEventTarget<T extends Event>(event: T, target: EventTarget): void {
+  Object.defineProperty(event, 'target', {
+    value: target,
+    writable: false,
+    configurable: true,
+  });
+  Object.defineProperty(event, 'currentTarget', {
+    value: target,
+    writable: false,
+    configurable: true,
+  });
+}