@proyecto-viviana/solidaria 0.1.3 → 0.2.0

package/src/live-announcer/announce.ts

@@ -1,322 +0,0 @@
-/**
- * Live announcer for solidaria
- *
- * Provides functions to make announcements to screen readers using
- * ARIA live regions. Useful for announcing dynamic content changes.
- *
- * Port of react-aria's @react-aria/live-announcer.
- *
- * SSR Safety: All functions are safe to call during SSR. The announcer
- * will only be created when running in the browser.
- */
-
-import { onCleanup, createEffect } from 'solid-js';
-import { isServer } from 'solid-js/web';
-
-// ============================================
-// TYPES
-// ============================================
-
-export type Assertiveness = 'assertive' | 'polite';
-
-export type Message = string | { 'aria-labelledby': string };
-
-// ============================================
-// CONSTANTS
-// ============================================
-
-const LIVEREGION_TIMEOUT_DELAY = 7000;
-
-// ============================================
-// LIVE ANNOUNCER CLASS
-// ============================================
-
-/**
- * Singleton class that manages live region announcements.
- * Implemented using vanilla DOM for simplicity and framework independence.
- */
-class LiveAnnouncer {
-  node: HTMLElement | null = null;
-  assertiveLog: HTMLElement | null = null;
-  politeLog: HTMLElement | null = null;
-
-  constructor() {
-    if (typeof document !== 'undefined') {
-      this.node = document.createElement('div');
-      this.node.dataset.liveAnnouncer = 'true';
-      // Visually hidden styles
-      Object.assign(this.node.style, {
-        border: '0',
-        clip: 'rect(0 0 0 0)',
-        clipPath: 'inset(50%)',
-        height: '1px',
-        margin: '-1px',
-        overflow: 'hidden',
-        padding: '0',
-        position: 'absolute',
-        width: '1px',
-        whiteSpace: 'nowrap',
-      });
-
-      this.assertiveLog = this.createLog('assertive');
-      this.node.appendChild(this.assertiveLog);
-
-      this.politeLog = this.createLog('polite');
-      this.node.appendChild(this.politeLog);
-
-      document.body.prepend(this.node);
-    }
-  }
-
-  isAttached(): boolean {
-    return this.node?.isConnected ?? false;
-  }
-
-  createLog(ariaLive: string): HTMLElement {
-    const node = document.createElement('div');
-    node.setAttribute('role', 'log');
-    node.setAttribute('aria-live', ariaLive);
-    node.setAttribute('aria-relevant', 'additions');
-    return node;
-  }
-
-  destroy(): void {
-    if (!this.node) {
-      return;
-    }
-
-    document.body.removeChild(this.node);
-    this.node = null;
-  }
-
-  announce(
-    message: Message,
-    assertiveness: Assertiveness = 'assertive',
-    timeout: number = LIVEREGION_TIMEOUT_DELAY
-  ): void {
-    if (!this.node) {
-      return;
-    }
-
-    const node = document.createElement('div');
-    if (typeof message === 'object') {
-      // To read an aria-labelledby, the element must have an appropriate role, such as img.
-      node.setAttribute('role', 'img');
-      node.setAttribute('aria-labelledby', message['aria-labelledby']);
-    } else {
-      node.textContent = message;
-    }
-
-    if (assertiveness === 'assertive') {
-      this.assertiveLog?.appendChild(node);
-    } else {
-      this.politeLog?.appendChild(node);
-    }
-
-    if (message !== '') {
-      setTimeout(() => {
-        node.remove();
-      }, timeout);
-    }
-  }
-
-  clear(assertiveness?: Assertiveness): void {
-    if (!this.node) {
-      return;
-    }
-
-    if ((!assertiveness || assertiveness === 'assertive') && this.assertiveLog) {
-      this.assertiveLog.innerHTML = '';
-    }
-
-    if ((!assertiveness || assertiveness === 'polite') && this.politeLog) {
-      this.politeLog.innerHTML = '';
-    }
-  }
-}
-
-// ============================================
-// SINGLETON INSTANCE
-// ============================================
-
-let liveAnnouncer: LiveAnnouncer | null = null;
-
-// ============================================
-// PUBLIC API
-// ============================================
-
-/**
- * Announces a message to screen readers using ARIA live regions.
- *
- * @param message - The message to announce, or an object with aria-labelledby
- * @param assertiveness - 'assertive' interrupts, 'polite' waits for a pause
- * @param timeout - How long to keep the message in the DOM (default 7000ms)
- *
- * @example
- * ```tsx
- * // Simple announcement
- * announce('Item added to cart');
- *
- * // Polite announcement (won't interrupt)
- * announce('3 results found', 'polite');
- *
- * // Using aria-labelledby for complex content
- * announce({ 'aria-labelledby': 'my-element-id' });
- * ```
- */
-export function announce(
-  message: Message,
-  assertiveness: Assertiveness = 'assertive',
-  timeout: number = LIVEREGION_TIMEOUT_DELAY
-): void {
-  if (!liveAnnouncer) {
-    liveAnnouncer = new LiveAnnouncer();
-    // Wait for the live announcer regions to be added to the DOM, then announce.
-    // Otherwise Safari won't announce the message if it's added too quickly.
-    // Found most times less than 100ms were not consistent when announcing with Safari.
-
-    // Check for test environment
-    const isTestEnv = typeof (globalThis as Record<string, unknown>).IS_SOLIDARIA_TEST === 'boolean'
-      ? (globalThis as Record<string, unknown>).IS_SOLIDARIA_TEST
-      : typeof (globalThis as Record<string, unknown>).vitest !== 'undefined';
-
-    if (!isTestEnv) {
-      setTimeout(() => {
-        if (liveAnnouncer?.isAttached()) {
-          liveAnnouncer?.announce(message, assertiveness, timeout);
-        }
-      }, 100);
-    } else {
-      liveAnnouncer.announce(message, assertiveness, timeout);
-    }
-  } else {
-    liveAnnouncer.announce(message, assertiveness, timeout);
-  }
-}
-
-/**
- * Clears all queued announcements for the given assertiveness level.
- *
- * @param assertiveness - Which log to clear ('assertive' or 'polite')
- *
- * @example
- * ```tsx
- * // Clear assertive announcements
- * clearAnnouncer('assertive');
- *
- * // Clear polite announcements
- * clearAnnouncer('polite');
- * ```
- */
-export function clearAnnouncer(assertiveness?: Assertiveness): void {
-  if (liveAnnouncer) {
-    liveAnnouncer.clear(assertiveness);
-  }
-}
-
-/**
- * Removes the live announcer from the DOM entirely.
- * Call this when unmounting your app or when announcements are no longer needed.
- *
- * @example
- * ```tsx
- * // Clean up on app unmount
- * onCleanup(() => {
- *   destroyAnnouncer();
- * });
- * ```
- */
-export function destroyAnnouncer(): void {
-  if (liveAnnouncer) {
-    liveAnnouncer.destroy();
-    liveAnnouncer = null;
-  }
-}
-
-// ============================================
-// HOOK-BASED API
-// ============================================
-
-export interface UseAnnouncerResult {
-  /** Announce a message to screen readers. */
-  announce: (
-    message: Message,
-    assertiveness?: Assertiveness,
-    timeout?: number
-  ) => void;
-  /** Clear announcements for the given assertiveness level. */
-  clear: (assertiveness?: Assertiveness) => void;
-}
-
-/**
- * Hook that provides access to the live announcer with automatic cleanup.
- *
- * This is the recommended way to use the announcer in SolidJS components.
- * It ensures the announcer is created only on the client and provides
- * type-safe methods for announcing and clearing messages.
- *
- * SSR Safety: Returns no-op functions during SSR. The announcer is only
- * created when the component mounts on the client.
- *
- * @example
- * ```tsx
- * function SearchResults(props) {
- *   const announcer = useAnnouncer();
- *
- *   createEffect(() => {
- *     const count = props.results.length;
- *     announcer.announce(`${count} results found`, 'polite');
- *   });
- *
- *   return <ul>...</ul>;
- * }
- * ```
- *
- * @example
- * ```tsx
- * function Form() {
- *   const announcer = useAnnouncer();
- *
- *   const onSubmit = async () => {
- *     try {
- *       await submitForm();
- *       announcer.announce('Form submitted successfully');
- *     } catch (error) {
- *       announcer.announce('Error submitting form', 'assertive');
- *     }
- *   };
- *
- *   return <form onSubmit={onSubmit}>...</form>;
- * }
- * ```
- */
-export function useAnnouncer(): UseAnnouncerResult {
-  // During SSR, return no-op functions
-  if (isServer) {
-    return {
-      announce: () => {},
-      clear: () => {},
-    };
-  }
-
-  // Ensure the announcer is initialized
-  createEffect(() => {
-    // Initialize on first use
-    if (!liveAnnouncer) {
-      liveAnnouncer = new LiveAnnouncer();
-    }
-  });
-
-  return {
-    announce: (
-      message: Message,
-      assertiveness: Assertiveness = 'assertive',
-      timeout: number = LIVEREGION_TIMEOUT_DELAY
-    ) => {
-      announce(message, assertiveness, timeout);
-    },
-    clear: (assertiveness?: Assertiveness) => {
-      clearAnnouncer(assertiveness);
-    },
-  };
-}

package/src/live-announcer/index.ts

@@ -1,9 +0,0 @@
-export {
-  announce,
-  clearAnnouncer,
-  destroyAnnouncer,
-  useAnnouncer,
-  type Assertiveness,
-  type Message,
-  type UseAnnouncerResult,
-} from './announce';