@proyecto-viviana/solidaria 0.3.0 → 0.4.0

package/dist/_chunk/live-announcer.jsx

@@ -0,0 +1,207 @@
+import { createEffect } from "solid-js";
+import { isServer } from "solid-js/web";
+//#region src/live-announcer/announce.ts
+/**
+* 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.
+*/
+const LIVEREGION_TIMEOUT_DELAY = 7e3;
+/**
+* Singleton class that manages live region announcements.
+* Implemented using vanilla DOM for simplicity and framework independence.
+*/
+var LiveAnnouncer = class {
+	node = null;
+	assertiveLog = null;
+	politeLog = null;
+	constructor() {
+		if (typeof document !== "undefined") {
+			this.node = document.createElement("div");
+			this.node.dataset.liveAnnouncer = "true";
+			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() {
+		return this.node?.isConnected ?? false;
+	}
+	createLog(ariaLive) {
+		const node = document.createElement("div");
+		node.setAttribute("role", "log");
+		node.setAttribute("aria-live", ariaLive);
+		node.setAttribute("aria-relevant", "additions");
+		return node;
+	}
+	destroy() {
+		if (!this.node) return;
+		document.body.removeChild(this.node);
+		this.node = null;
+	}
+	announce(message, assertiveness = "assertive", timeout = LIVEREGION_TIMEOUT_DELAY) {
+		if (!this.node) return;
+		const node = document.createElement("div");
+		if (typeof message === "object") {
+			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) {
+		if (!this.node) return;
+		if ((!assertiveness || assertiveness === "assertive") && this.assertiveLog) this.assertiveLog.innerHTML = "";
+		if ((!assertiveness || assertiveness === "polite") && this.politeLog) this.politeLog.innerHTML = "";
+	}
+};
+let liveAnnouncer = null;
+/**
+* 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' });
+* ```
+*/
+function announce(message, assertiveness = "assertive", timeout = LIVEREGION_TIMEOUT_DELAY) {
+	if (!liveAnnouncer) {
+		liveAnnouncer = new LiveAnnouncer();
+		if (!(typeof globalThis.IS_SOLIDARIA_TEST === "boolean" ? globalThis.IS_SOLIDARIA_TEST : typeof globalThis.vitest !== "undefined")) 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');
+* ```
+*/
+function clearAnnouncer(assertiveness) {
+	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();
+* });
+* ```
+*/
+function destroyAnnouncer() {
+	if (liveAnnouncer) {
+		liveAnnouncer.destroy();
+		liveAnnouncer = null;
+	}
+}
+/**
+* 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>;
+* }
+* ```
+*/
+function useAnnouncer() {
+	if (isServer) return {
+		announce: () => {},
+		clear: () => {}
+	};
+	createEffect(() => {
+		if (!liveAnnouncer) liveAnnouncer = new LiveAnnouncer();
+	});
+	return {
+		announce: (message, assertiveness = "assertive", timeout = LIVEREGION_TIMEOUT_DELAY) => {
+			announce(message, assertiveness, timeout);
+		},
+		clear: (assertiveness) => {
+			clearAnnouncer(assertiveness);
+		}
+	};
+}
+//#endregion
+export { useAnnouncer as i, clearAnnouncer as n, destroyAnnouncer as r, announce as t };
+
+//# sourceMappingURL=live-announcer.jsx.map

package/dist/_chunk/live-announcer.jsx.map

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