@proyecto-viviana/solidaria 0.2.2 → 0.2.3

package/src/live-announcer/announce.ts

@@ -0,0 +1,322 @@
+/**
+ * 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

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