@proyecto-viviana/solidaria-components 0.2.9 → 0.3.1

package/src/Toast.tsx

@@ -7,46 +7,60 @@
 
 import {
   type JSX,
+  type Accessor,
   createContext,
   createMemo,
   createEffect,
+  createSignal,
   onCleanup,
   splitProps,
   Show,
   useContext,
-} from 'solid-js';
-import { Portal, isServer } from 'solid-js/web';
+} from "solid-js";
+import { Portal } from "solid-js/web";
 import {
   type ToastState,
   type QueuedToast,
   type ToastQueueOptions,
+  type ToastOptions,
   ToastQueue,
   createToastState,
-} from '@proyecto-viviana/solid-stately';
+} from "@proyecto-viviana/solid-stately";
 import {
   createToast,
   createToastRegion,
   useUNSAFE_PortalContext,
-} from '@proyecto-viviana/solidaria';
+} from "@proyecto-viviana/solidaria";
 import {
   type RenderChildren,
   type ClassNameOrFunction,
   type StyleOrFunction,
   useRenderProps,
   filterDOMProps,
-} from './utils';
-
-// ============================================
-// TYPES
-// ============================================
+  useIsHydrated,
+} from "./utils";
 
 export interface ToastContent {
+  /** DOM id for the toast root when content is queued through Spectrum ToastQueue. */
+  id?: string;
+  /** Data attributes for the toast root when content is queued through Spectrum ToastQueue. */
+  [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+  /** Spectrum Toast message content. */
+  children?: string;
   /** The title of the toast. */
   title?: string;
   /** The description/body of the toast. */
   description?: string;
-  /** The type/variant of the toast (info, success, warning, error). */
-  type?: 'info' | 'success' | 'warning' | 'error';
+  /** Spectrum variant. */
+  variant?: "info" | "positive" | "negative" | "neutral";
+  /** Backward-compatible type/variant of the toast. */
+  type?: "info" | "success" | "warning" | "error" | "positive" | "negative" | "neutral";
+  /** Spectrum action button label. */
+  actionLabel?: string;
+  /** Handler called when the Spectrum action button is pressed. */
+  onAction?: () => void;
+  /** Whether the toast should close when the Spectrum action is performed. */
+  shouldCloseOnAction?: boolean;
   /** Custom action button. */
   action?: {
     label: string;
@@ -60,14 +74,14 @@ export interface ToastRenderProps {
   /** Whether the toast is currently animating out. */
   isExiting: boolean;
   /** The animation state (entering, exiting, queued). */
-  animation: 'entering' | 'exiting' | 'queued' | undefined;
+  animation: "entering" | "exiting" | "queued" | undefined;
   /** The toast data. */
   toast: QueuedToast<ToastContent>;
 }
 
 export interface ToastRegionRenderProps {
   /** The visible toasts. */
-  visibleToasts: QueuedToast<ToastContent>[];
+  visibleToasts: Accessor<QueuedToast<ToastContent>[]>;
 }
 
 export interface ToastRegionProps {
@@ -80,14 +94,28 @@ export interface ToastRegionProps {
   /** The toast state to display. If not provided, uses ToastContext. */
   state?: ToastState<ToastContent>;
   /** Accessible label for the region. */
-  'aria-label'?: string;
+  "aria-label"?: string;
   /** Whether to render in a portal. */
   portal?: boolean;
   /** Placement of the toast region. */
-  placement?: 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end';
+  placement?:
+    | "top"
+    | "top start"
+    | "top end"
+    | "top-start"
+    | "top-end"
+    | "bottom"
+    | "bottom start"
+    | "bottom end"
+    | "bottom-start"
+    | "bottom-end";
 }
 
 export interface ToastProps {
+  /** DOM id for the toast root. */
+  id?: string;
+  /** Data attributes for the toast root. */
+  [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
   /** The toast data. */
   toast: QueuedToast<ToastContent>;
   /** The children of the component - can be JSX or render function. */
@@ -98,10 +126,6 @@ export interface ToastProps {
   style?: StyleOrFunction<ToastRenderProps>;
 }
 
-// ============================================
-// CONTEXT
-// ============================================
-
 export const ToastContext = createContext<ToastState<ToastContent> | null>(null);
 
 interface ToastAriaContextValue {
@@ -110,22 +134,19 @@ interface ToastAriaContextValue {
 }
 
 const ToastAriaContext = createContext<ToastAriaContextValue | null>(null);
+const toastStateByKey = new Map<string, ToastState<ToastContent>>();
 
 export function useToastContext(): ToastState<ToastContent> {
   const context = useContext(ToastContext);
   if (!context) {
-    throw new Error('Toast components must be used within a ToastProvider');
+    throw new Error("Toast components must be used within a ToastProvider");
   }
   return context;
 }
 
-// ============================================
-// GLOBAL TOAST QUEUE
-// ============================================
-
 /** Default global toast queue that can be used for app-wide toasts. */
 export const globalToastQueue = new ToastQueue<ToastContent>({
-  maxVisibleToasts: 5,
+  maxVisibleToasts: Infinity,
   hasExitAnimation: true,
 });
 
@@ -133,16 +154,13 @@ export const globalToastQueue = new ToastQueue<ToastContent>({
  * Add a toast to the global queue.
  * Convenience function for adding toasts from anywhere in the app.
  */
-export function addToast(
-  content: ToastContent,
-  options?: { timeout?: number; priority?: number }
-): string {
+export function addToast(content: ToastContent, options?: ToastOptions): string {
   return globalToastQueue.add(content, options);
 }
 
-// ============================================
-// TOAST PROVIDER
-// ============================================
+function normalizeToastPlacement(placement?: ToastRegionProps["placement"]) {
+  return (placement ?? "bottom").replace("-", " ") as NonNullable<ToastRegionProps["placement"]>;
+}
 
 export interface ToastProviderProps {
   /** The children of the provider. */
@@ -172,17 +190,9 @@ export function ToastProvider(props: ToastProviderProps): JSX.Element {
 
   const state = createToastState({ queue });
 
-  return (
-    <ToastContext.Provider value={state}>
-      {props.children}
-    </ToastContext.Provider>
-  );
+  return <ToastContext.Provider value={state}>{props.children}</ToastContext.Provider>;
 }
 
-// ============================================
-// TOAST REGION COMPONENT
-// ============================================
-
 /**
  * ToastRegion is a container that displays all visible toasts.
  * It handles pause on hover/focus and provides the landmark region.
@@ -199,91 +209,117 @@ export function ToastProvider(props: ToastProviderProps): JSX.Element {
  * ```
  */
 export function ToastRegion(props: ToastRegionProps): JSX.Element {
-  if (isServer) {
-    return null as unknown as JSX.Element;
-  }
+  // Do NOT early-return on the server: returning null on the server and a <Show>
+  // on the client desyncs hydration when the region is in the SSR tree. Render the
+  // same structure on both and gate the Portal on useIsHydrated() (see Popover).
+  const isHydrated = useIsHydrated();
 
   const [local, rest] = splitProps(props, [
-    'children',
-    'class',
-    'style',
-    'state',
-    'aria-label',
-    'portal',
-    'placement',
+    "children",
+    "class",
+    "style",
+    "state",
+    "aria-label",
+    "portal",
+    "placement",
   ]);
   const portalContext = useUNSAFE_PortalContext();
   const portalContainer = () => portalContext.getContainer?.() ?? undefined;
+  const [regionElement, setRegionElement] = createSignal<HTMLElement>();
 
-  // Get state from context if not provided
   const contextState = useContext(ToastContext);
   const state = () => local.state ?? contextState;
 
-  // Create region accessibility props
-  const getRegionAria = () => {
-    const s = state();
-    if (!s) return null;
-    return createToastRegion({
-      state: s,
-      'aria-label': local['aria-label'],
-    });
-  };
+  const regionAria = createToastRegion<ToastContent>({
+    state: {
+      visibleToasts: () => state()?.visibleToasts() ?? [],
+      add: (content, options) => state()?.add(content, options) ?? "",
+      close: (key) => state()?.close(key),
+      remove: (key) => state()?.remove(key),
+      clear: () => state()?.clear(),
+      pauseAll: () => state()?.pauseAll(),
+      resumeAll: () => state()?.resumeAll(),
+    },
+    ref: regionElement,
+    get "aria-label"() {
+      return local["aria-label"];
+    },
+  });
 
-  // Render props values
   const renderValues = createMemo<ToastRegionRenderProps>(() => ({
-    visibleToasts: state()?.visibleToasts() ?? [],
+    visibleToasts: () => state()?.visibleToasts() ?? [],
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
-      children: props.children,
+      // Lazy: the region content is gated behind `<Show when={isHydrated() && …}>`
+      // (Portal) below, so reading children must not instantiate templates during
+      // the component body (would walk getNextElement before the gate the server
+      // kept closed → hydration mismatch). See Popover for the full rationale.
+      get children() {
+        return props.children;
+      },
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-ToastRegion',
+      defaultClassName: "solidaria-ToastRegion",
     },
-    renderValues
+    renderValues,
   );
+  const renderedChildren = createMemo(() => renderProps.renderChildren());
 
-  // Filter DOM props
-  const domProps = createMemo(() => filterDOMProps(rest as Record<string, unknown>, { global: true }));
+  const domProps = createMemo(() =>
+    filterDOMProps(rest as Record<string, unknown>, { global: true }),
+  );
 
-  // Placement styles
   const placementStyles = createMemo<JSX.CSSProperties>(() => {
-    const placement = local.placement ?? 'bottom-end';
+    const placement = normalizeToastPlacement(local.placement);
+    const [edge, align = "center"] = placement.split(" ");
     const base: JSX.CSSProperties = {
-      position: 'fixed',
-      'z-index': 100001,
-      display: 'flex',
-      'flex-direction': 'column',
-      gap: '8px',
-      padding: '16px',
-      'pointer-events': 'none',
+      position: "fixed",
+      "z-index": 100001,
+      display: "flex",
+      "flex-direction": edge === "top" ? "column" : "column-reverse",
+      gap: "8px",
+      padding: "16px",
+      "pointer-events": "none",
     };
 
-    switch (placement) {
-      case 'top':
-        return { ...base, top: 0, left: '50%', transform: 'translateX(-50%)' } as JSX.CSSProperties;
-      case 'top-start':
-        return { ...base, top: 0, left: 0 } as JSX.CSSProperties;
-      case 'top-end':
-        return { ...base, top: 0, right: 0 } as JSX.CSSProperties;
-      case 'bottom':
-        return { ...base, bottom: 0, left: '50%', transform: 'translateX(-50%)' } as JSX.CSSProperties;
-      case 'bottom-start':
-        return { ...base, bottom: 0, left: 0 } as JSX.CSSProperties;
-      case 'bottom-end':
-      default:
-        return { ...base, bottom: 0, right: 0 } as JSX.CSSProperties;
+    if (edge === "top") {
+      if (align === "end") {
+        return { ...base, top: "16px", right: "16px" } as JSX.CSSProperties;
+      }
+      if (align === "start") {
+        return { ...base, top: "16px", left: "16px" } as JSX.CSSProperties;
+      }
+      return {
+        ...base,
+        top: "16px",
+        left: "50%",
+        transform: "translateX(-50%)",
+      } as JSX.CSSProperties;
+    }
+
+    if (align === "end") {
+      return { ...base, bottom: "16px", right: "16px" } as JSX.CSSProperties;
+    }
+    if (align === "start") {
+      return { ...base, bottom: "16px", left: "16px" } as JSX.CSSProperties;
     }
+    return {
+      ...base,
+      bottom: "16px",
+      left: "50%",
+      transform: "translateX(-50%)",
+    } as JSX.CSSProperties;
   });
 
+  const normalizedPlacement = () => normalizeToastPlacement(local.placement);
+
   const visibleToasts = () => state()?.visibleToasts() ?? [];
   const hasToasts = () => visibleToasts().length > 0;
 
   const regionContent = () => {
-    const regionAria = getRegionAria();
-    if (!regionAria || !state()) return null;
+    if (!state()) return null;
 
     // Merge styles - placement styles are base, renderProps.style() overrides
     const mergedStyle = () => {
@@ -293,25 +329,24 @@ export function ToastRegion(props: ToastRegionProps): JSX.Element {
       return { ...placement, ...custom } as JSX.CSSProperties;
     };
 
-    // Extract ref from regionProps to avoid type conflicts
     const { ref: _ref, ...cleanRegionProps } = regionAria.regionProps as Record<string, unknown>;
 
     return (
       <div
+        ref={setRegionElement}
         {...domProps()}
         {...cleanRegionProps}
         class={renderProps.class()}
         style={mergedStyle()}
-        data-placement={local.placement ?? 'bottom-end'}
+        data-placement={normalizedPlacement()}
       >
-        {renderProps.renderChildren()}
+        {renderedChildren()}
       </div>
     );
   };
 
-  // Only render when there are toasts
   return (
-    <Show when={hasToasts()}>
+    <Show when={isHydrated() && hasToasts()}>
       <Show when={local.portal !== false} fallback={regionContent()}>
         <Portal mount={portalContainer()}>{regionContent()}</Portal>
       </Show>
@@ -319,10 +354,6 @@ export function ToastRegion(props: ToastRegionProps): JSX.Element {
   );
 }
 
-// ============================================
-// TOAST COMPONENT
-// ============================================
-
 /**
  * Toast is an individual notification component.
  *
@@ -339,53 +370,64 @@ export function ToastRegion(props: ToastRegionProps): JSX.Element {
  * ```
  */
 export function Toast(props: ToastProps): JSX.Element {
-  const [local, rest] = splitProps(props, [
-    'toast',
-    'children',
-    'class',
-    'style',
-  ]);
+  const [local, rest] = splitProps(props, ["toast", "children", "class", "style"]);
 
   let toastRef!: HTMLDivElement;
 
-  // Get state from context
   const state = useToastContext();
 
-  // Create toast accessibility props
+  createEffect(() => {
+    const key = local.toast.key;
+    toastStateByKey.set(key, state);
+    onCleanup(() => {
+      if (toastStateByKey.get(key) === state) {
+        toastStateByKey.delete(key);
+      }
+    });
+  });
+
+  const hasTitle = () => !!(local.toast.content.children ?? local.toast.content.title);
   const toastAria = createToast({
     toast: local.toast,
     state,
-    hasTitle: !!local.toast.content.title,
+    hasTitle: hasTitle(),
     hasDescription: !!local.toast.content.description,
   });
 
-  // Render props values
   const renderValues = createMemo<ToastRenderProps>(() => ({
-    isEntering: local.toast.animation === 'entering',
-    isExiting: local.toast.animation === 'exiting',
+    isEntering: local.toast.animation === "entering",
+    isExiting: local.toast.animation === "exiting",
     animation: local.toast.animation,
     toast: local.toast,
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       children: props.children,
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-Toast',
+      defaultClassName: "solidaria-Toast",
     },
-    renderValues
+    renderValues,
   );
 
-  // Filter DOM props
-  const domProps = createMemo(() => filterDOMProps(rest as Record<string, unknown>, { global: true }));
+  const domProps = createMemo(() =>
+    filterDOMProps(rest as Record<string, unknown>, { global: true }),
+  );
 
-  // Merge styles
   const mergedStyle = () => {
     const custom = renderProps.style();
-    if (!custom) return { 'pointer-events': 'auto' as const };
-    return { 'pointer-events': 'auto' as const, ...custom } as JSX.CSSProperties;
+    if (!custom) return { "pointer-events": "auto" as const };
+    return { "pointer-events": "auto" as const, ...custom } as JSX.CSSProperties;
+  };
+
+  const handleRootClick = (event: MouseEvent) => {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    if (target.closest("[data-solidaria-toast-close-button]")) {
+      state.close(local.toast.key);
+      state.remove(local.toast.key);
+    }
   };
 
   // Exit animation lifecycle:
@@ -395,14 +437,14 @@ export function Toast(props: ToastProps): JSX.Element {
   // Reduced-motion is handled by CSS (shorter/no animations), so the lifecycle
   // naturally completes faster when the user prefers reduced motion.
   createEffect(() => {
-    if (local.toast.animation !== 'exiting') return;
+    if (local.toast.animation !== "exiting") return;
     if (!toastRef) {
       state.remove(local.toast.key);
       return;
     }
 
     // Check if the element supports the Web Animations API
-    if (!('getAnimations' in toastRef)) {
+    if (!("getAnimations" in toastRef)) {
       state.remove(local.toast.key);
       return;
     }
@@ -434,7 +476,6 @@ export function Toast(props: ToastProps): JSX.Element {
     });
   });
 
-  // Extract ref from toastProps to avoid type conflicts
   const { ref: _ref, ...cleanToastProps } = toastAria.toastProps as Record<string, unknown>;
 
   // Ensure ARIA title/description IDs are present on rendered sub-components,
@@ -443,17 +484,19 @@ export function Toast(props: ToastProps): JSX.Element {
     if (!toastRef) return;
 
     const titleId = (toastAria.titleProps as Record<string, unknown>).id as string | undefined;
-    const descriptionId = (toastAria.descriptionProps as Record<string, unknown>).id as string | undefined;
+    const descriptionId = (toastAria.descriptionProps as Record<string, unknown>).id as
+      | string
+      | undefined;
 
     if (titleId) {
-      const titleEl = toastRef.querySelector('[data-solidaria-toast-title]');
+      const titleEl = toastRef.querySelector("[data-solidaria-toast-title]");
       if (titleEl instanceof HTMLElement) {
         titleEl.id = titleId;
       }
     }
 
     if (descriptionId) {
-      const descriptionEl = toastRef.querySelector('[data-solidaria-toast-description]');
+      const descriptionEl = toastRef.querySelector("[data-solidaria-toast-description]");
       if (descriptionEl instanceof HTMLElement) {
         descriptionEl.id = descriptionId;
       }
@@ -461,7 +504,9 @@ export function Toast(props: ToastProps): JSX.Element {
   });
 
   return (
-    <ToastAriaContext.Provider value={{ titleProps: toastAria.titleProps, descriptionProps: toastAria.descriptionProps }}>
+    <ToastAriaContext.Provider
+      value={{ titleProps: toastAria.titleProps, descriptionProps: toastAria.descriptionProps }}
+    >
       <div
         ref={toastRef}
         {...domProps()}
@@ -469,7 +514,9 @@ export function Toast(props: ToastProps): JSX.Element {
         class={renderProps.class()}
         style={mergedStyle()}
         data-animation={local.toast.animation}
-        data-type={local.toast.content.type}
+        data-type={local.toast.content.type ?? local.toast.content.variant}
+        data-variant={local.toast.content.variant}
+        on:click={handleRootClick}
       >
         {renderProps.renderChildren()}
       </div>
@@ -477,10 +524,6 @@ export function Toast(props: ToastProps): JSX.Element {
   );
 }
 
-// ============================================
-// TOAST SUB-COMPONENTS
-// ============================================
-
 export interface ToastTitleProps {
   children: JSX.Element;
   class?: string;
@@ -512,10 +555,18 @@ export interface ToastDescriptionProps {
  */
 export function ToastDescription(props: ToastDescriptionProps): JSX.Element {
   const context = useContext(ToastAriaContext);
-  const { ref: _ref, ...ariaDescriptionProps } = (context?.descriptionProps ?? {}) as Record<string, unknown>;
+  const { ref: _ref, ...ariaDescriptionProps } = (context?.descriptionProps ?? {}) as Record<
+    string,
+    unknown
+  >;
 
   return (
-    <div data-solidaria-toast-description="" {...ariaDescriptionProps} class={props.class} style={props.style}>
+    <div
+      data-solidaria-toast-description=""
+      {...ariaDescriptionProps}
+      class={props.class}
+      style={props.style}
+    >
       {props.children}
     </div>
   );
@@ -527,17 +578,19 @@ export interface ToastCloseButtonProps {
   children?: JSX.Element;
   class?: string;
   style?: JSX.CSSProperties;
-  'aria-label'?: string;
+  "aria-label"?: string;
 }
 
 /**
  * ToastCloseButton is a button that closes the toast.
  */
 export function ToastCloseButton(props: ToastCloseButtonProps): JSX.Element {
-  const state = useToastContext();
-
+  const contextState = useContext(ToastContext);
   const handleClose = () => {
-    state.close(props.toast.key);
+    const key = props.toast.key;
+    const state = contextState ?? toastStateByKey.get(key);
+    state?.close(key);
+    state?.remove(key);
   };
 
   return (
@@ -545,18 +598,16 @@ export function ToastCloseButton(props: ToastCloseButtonProps): JSX.Element {
       type="button"
       class={props.class}
       style={props.style}
-      aria-label={props['aria-label'] ?? 'Close'}
+      aria-label={props["aria-label"] ?? "Close"}
+      data-solidaria-toast-close-button=""
+      on:click={handleClose}
       onClick={handleClose}
     >
-      {props.children ?? '×'}
+      {props.children ?? "×"}
     </button>
   );
 }
 
-// ============================================
-// DEFAULT TOAST RENDERING
-// ============================================
-
 export interface DefaultToastProps {
   toast: QueuedToast<ToastContent>;
 }
@@ -567,26 +618,33 @@ export interface DefaultToastProps {
  */
 export function DefaultToast(props: DefaultToastProps): JSX.Element {
   const content = () => props.toast.content;
+  const title = () => content().children ?? content().title;
+  const actionLabel = () => content().actionLabel ?? content().action?.label;
+  const actionHandler = () => content().onAction ?? content().action?.onAction;
+  const state = useToastContext();
+  const handleAction = () => {
+    actionHandler()?.();
+    if (content().shouldCloseOnAction) {
+      state.close(props.toast.key);
+      state.remove(props.toast.key);
+    }
+  };
 
   return (
     <Toast toast={props.toast}>
-      <div style={{ display: 'flex', 'align-items': 'flex-start', gap: '12px' }}>
+      <div style={{ display: "flex", "align-items": "flex-start", gap: "12px" }}>
         <div style={{ flex: 1 }}>
-          <Show when={content().title}>
-            <ToastTitle style={{ 'font-weight': 'bold', 'margin-bottom': '4px' }}>
-              {content().title}
+          <Show when={title()}>
+            <ToastTitle style={{ "font-weight": "bold", "margin-bottom": "4px" }}>
+              {title()}
             </ToastTitle>
           </Show>
           <Show when={content().description}>
             <ToastDescription>{content().description}</ToastDescription>
           </Show>
-          <Show when={content().action}>
-            <button
-              type="button"
-              style={{ 'margin-top': '8px' }}
-              onClick={content().action?.onAction}
-            >
-              {content().action?.label}
+          <Show when={actionLabel()}>
+            <button type="button" style={{ "margin-top": "8px" }} onClick={handleAction}>
+              {actionLabel()}
             </button>
           </Show>
         </div>