@unitedstatespowersquadrons/components 1.3.14 → 1.4.0-2

package/.claude/settings.local.json

@@ -4,7 +4,8 @@
       "Bash(yarn run test*)",
       "Bash(yarn run vitest*)",
       "Bash(yarn run tsc*)",
-      "Bash(yarn run eslint*)"
+      "Bash(yarn run eslint*)",
+      "Bash(git commit -m ' *)"
     ]
   }
 }

package/Toasts/GlobalToasts.test.tsx

@@ -0,0 +1,101 @@
+import React from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, cleanup, render, screen } from "@testing-library/react";
+import GlobalToasts from "./GlobalToasts";
+import { toastStore } from "./globalStore";
+import { Toast_Status } from "./types";
+
+interface ReceivedHandler {
+  (data: { toasts?: Array<Record<string, unknown>>; dismissToast?: number }): void;
+}
+
+const subscriptionStub = {
+  send: vi.fn(),
+  unsubscribe: vi.fn(),
+};
+let lastReceived: ReceivedHandler | null = null;
+const createSpy = vi.fn((_channel: { channel: string }, handlers: { received: ReceivedHandler }) => {
+  lastReceived = handlers.received;
+  return subscriptionStub;
+});
+
+vi.mock("@rails/actioncable", () => ({
+  createConsumer: () => ({
+    subscriptions: { create: createSpy },
+  }),
+}));
+
+beforeEach(() => {
+  toastStore.clear();
+  createSpy.mockClear();
+  subscriptionStub.send.mockClear();
+  subscriptionStub.unsubscribe.mockClear();
+  lastReceived = null;
+});
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("<GlobalToasts />", () => {
+  it("subscribes exactly once to BroadcastToastChannel on mount", () => {
+    render(<GlobalToasts />);
+    expect(createSpy).toHaveBeenCalledTimes(1);
+    expect(createSpy.mock.calls[0]?.[0]).toEqual({ channel: "BroadcastToastChannel" });
+  });
+
+  it("unsubscribes on unmount", () => {
+    const { unmount } = render(<GlobalToasts />);
+    unmount();
+    expect(subscriptionStub.unsubscribe).toHaveBeenCalledOnce();
+  });
+
+  it("renders broadcasts received from the channel with broadcast styling above local toasts", () => {
+    toastStore.add({
+      body: "local body",
+      status: Toast_Status.SUCCESS,
+      timeout: 0,
+      title: "Local title",
+    });
+
+    render(<GlobalToasts />);
+
+    act(() => {
+      lastReceived!({
+        toasts: [{
+          body: "broadcast body",
+          status: Toast_Status.NOTICE,
+          timeout: 0,
+          title: "Broadcast title",
+        }],
+      });
+    });
+
+    const titles = screen.getAllByText(/title$/i).map(el => el.textContent);
+    expect(titles[0]).toBe("Broadcast title");
+    expect(titles[1]).toBe("Local title");
+    expect(screen.getByText("Broadcast")).toBeInTheDocument();
+  });
+
+  it("removes a toast when the channel sends dismissToast", () => {
+    render(<GlobalToasts />);
+
+    act(() => {
+      lastReceived!({
+        toasts: [{
+          body: "B",
+          id: 42,
+          status: Toast_Status.NOTICE,
+          timeout: 0,
+          title: "Going",
+        }],
+      });
+    });
+    expect(screen.getByText("Going")).toBeInTheDocument();
+
+    act(() => {
+      lastReceived!({ dismissToast: 42 });
+    });
+    expect(screen.queryByText("Going")).not.toBeInTheDocument();
+  });
+});

package/Toasts/GlobalToasts.tsx

@@ -0,0 +1,58 @@
+import React, { useEffect, useSyncExternalStore } from "react";
+import Toasts from "./Toasts";
+import { toastStore } from "./globalStore";
+import { dismissToastGlobal } from "./globalHelpers";
+import { broadcastSubscriptionRef, getConsumer } from "./cableConsumer";
+import { Toast, ToastProps } from "./types";
+
+interface Props {
+  allowedDomains?: string[];
+}
+
+interface BroadcastPayload {
+  toasts?: Toast[];
+  dismissToast?: number;
+}
+
+const sortBroadcastsFirst = (toasts: readonly ToastProps[]): ToastProps[] => (
+  [...toasts].sort((a, b) => (
+    Number(b.kind === "broadcast") - Number(a.kind === "broadcast")
+  ))
+);
+
+const GlobalToasts = ({ allowedDomains }: Props) => {
+  const toasts = useSyncExternalStore(toastStore.subscribe, toastStore.getSnapshot, toastStore.getSnapshot);
+
+  useEffect(() => {
+    const consumer = getConsumer();
+    const sub = consumer.subscriptions.create(
+      { channel: "BroadcastToastChannel" },
+      {
+        received: (data: BroadcastPayload) => {
+          if (data.toasts) {
+            data.toasts.forEach(t => toastStore.add({ ...t, kind: "broadcast" }));
+          }
+          if (typeof data.dismissToast === "number") {
+            toastStore.remove(data.dismissToast);
+          }
+        },
+      }
+    );
+    broadcastSubscriptionRef.current = sub;
+
+    return () => {
+      sub.unsubscribe();
+      if (broadcastSubscriptionRef.current === sub) {
+        broadcastSubscriptionRef.current = null;
+      }
+    };
+  }, []);
+
+  const sorted = sortBroadcastsFirst(toasts);
+
+  return allowedDomains
+    ? <Toasts allowedDomains={allowedDomains} dismiss={dismissToastGlobal} toasts={sorted} />
+    : <Toasts dismiss={dismissToastGlobal} toasts={sorted} />;
+};
+
+export default GlobalToasts;

package/Toasts/Toast.tsx

@@ -22,6 +22,20 @@ const isAllowedUrl = (url: string, allowedDomains?: string[]): boolean => {
 };
 
 const useStyles = createUseStyles({
+  broadcast: {
+    borderLeft: "4px solid #7A1FA2",
+  },
+  broadcastTag: {
+    backgroundColor: "#7A1FA2",
+    borderRadius: "0.25em",
+    color: "#FFFFFF",
+    fontSize: "0.75em",
+    fontWeight: "bold",
+    letterSpacing: "0.05em",
+    marginRight: "0.5em",
+    padding: "0.1em 0.4em",
+    textTransform: "uppercase",
+  },
   dismissed: { opacity: "0" },
   error: {
     borderColor: "#CC0000",
@@ -84,7 +98,8 @@ const Toast = (props: Props) => {
   const classes = useStyles();
 
   const { allowedDomains, dismiss, toast } = props;
-  const { body, dismissed, id, status, timeout, title } = toast;
+  const { body, dismissed, id, kind, status, timeout, title } = toast;
+  const isBroadcast = kind === "broadcast";
 
   const handleDismiss = () => dismiss(id);
 
@@ -140,9 +155,13 @@ const Toast = (props: Props) => {
   const opacityClass = dismissed ? classes.dismissed : classes.visible;
 
   return (
-    <div className={classNames(classes.toast, statusClassName, opacityClass)} key={`toast-${id}`}>
+    <div
+      className={classNames(classes.toast, statusClassName, opacityClass, isBroadcast && classes.broadcast)}
+      key={`toast-${id}`}
+    >
       <div className={classes.toastTitle}>
         <FontAwesomeIcon fa="fw" icon={icon} mode="duotone" />
+        {isBroadcast && <span className={classes.broadcastTag}>Broadcast</span>}
         <span>{title}</span>
       </div>
       <div className={classes.toastBody}>{renderBody()}</div>

package/Toasts/Toasts.tsx

@@ -54,9 +54,13 @@ const Toasts = (props: Props) => {
     }
   };
 
+  const sorted = toasts && [...toasts].sort((a, b) => (
+    Number(b.kind === "broadcast") - Number(a.kind === "broadcast")
+  ));
+
   return (
     <div className={classNames("toastsContainer", classes.toastsContainer)}>
-      {toasts?.map(toast => (
+      {sorted?.map(toast => (
         <Toast allowedDomains={allowedDomains} dismiss={dismissFunc()} key={toast.id} toast={toast} />
       ))}
     </div>

package/Toasts/cableConsumer.ts

@@ -0,0 +1,10 @@
+import { Consumer, createConsumer, Subscription } from "@rails/actioncable";
+
+let consumer: Consumer | null = null;
+
+export const getConsumer = (): Consumer => {
+  if (!consumer) consumer = createConsumer();
+  return consumer;
+};
+
+export const broadcastSubscriptionRef: { current: Subscription | null } = { current: null };

package/Toasts/globalHelpers.test.ts

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { dismissToastGlobal, handleToastsGlobal, pushToast, removeToastGlobal } from "./globalHelpers";
+import { toastStore } from "./globalStore";
+import { Toast_Status } from "./types";
+
+const baseToast = {
+  body: "Body",
+  status: Toast_Status.SUCCESS,
+  timeout: 0,
+  title: "Title",
+};
+
+beforeEach(() => { toastStore.clear(); });
+
+describe("pushToast", () => {
+  it("delegates to the singleton and returns the id", () => {
+    const id = pushToast(baseToast);
+    expect(toastStore.getSnapshot()[0]?.id).toBe(id);
+  });
+});
+
+describe("handleToastsGlobal", () => {
+  it("adds each toast to the singleton", () => {
+    handleToastsGlobal([
+      baseToast,
+      { ...baseToast, body: "Two" },
+    ]);
+    expect(toastStore.getSnapshot()).toHaveLength(2);
+  });
+
+  it("does nothing for an empty array", () => {
+    handleToastsGlobal([]);
+    expect(toastStore.getSnapshot()).toHaveLength(0);
+  });
+});
+
+describe("removeToastGlobal", () => {
+  it("removes a toast by id", () => {
+    const id = pushToast(baseToast);
+    removeToastGlobal(id);
+    expect(toastStore.getSnapshot()).toHaveLength(0);
+  });
+});
+
+describe("dismissToastGlobal", () => {
+  it("marks the toast dismissed", () => {
+    const id = pushToast(baseToast);
+    dismissToastGlobal(id);
+    expect(toastStore.getSnapshot()[0]?.dismissed).toBe(true);
+  });
+});

package/Toasts/globalHelpers.ts

@@ -0,0 +1,12 @@
+import { toastStore } from "./globalStore";
+import { Toast } from "./types";
+
+export const pushToast = (toast: Toast): number => toastStore.add(toast);
+
+export const handleToastsGlobal = (toasts: Toast[]): void => {
+  toasts.forEach(t => toastStore.add(t));
+};
+
+export const dismissToastGlobal = (id: number): void => toastStore.dismiss(id);
+
+export const removeToastGlobal = (id: number): void => toastStore.remove(id);

package/Toasts/globalStore.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { toastStore } from "./globalStore";
+import { Toast_Status } from "./types";
+
+const baseToast = {
+  body: "Body",
+  status: Toast_Status.SUCCESS,
+  timeout: 0,
+  title: "Title",
+};
+
+beforeEach(() => {
+  toastStore.clear();
+});
+
+describe("toastStore.add", () => {
+  it("adds a toast and emits", () => {
+    const listener = vi.fn();
+    toastStore.subscribe(listener);
+
+    const id = toastStore.add(baseToast);
+
+    expect(toastStore.getSnapshot()).toHaveLength(1);
+    expect(toastStore.getSnapshot()[0]?.id).toBe(id);
+    expect(toastStore.getSnapshot()[0]?.kind).toBe("local");
+    expect(listener).toHaveBeenCalledOnce();
+  });
+
+  it("assigns auto-incrementing ids", () => {
+    const a = toastStore.add(baseToast);
+    const b = toastStore.add({ ...baseToast, body: "Other" });
+
+    expect(b).toBe(a + 1);
+  });
+
+  it("respects an explicit id and advances nextId past it", () => {
+    toastStore.add({ ...baseToast, id: 50 });
+    const next = toastStore.add({ ...baseToast, body: "Next" });
+
+    expect(next).toBe(51);
+  });
+
+  it("stores broadcast kind when supplied", () => {
+    toastStore.add({ ...baseToast, kind: "broadcast" });
+    expect(toastStore.getSnapshot()[0]?.kind).toBe("broadcast");
+  });
+
+  it("dedupes identical toasts (body+status+title)", () => {
+    const a = toastStore.add(baseToast);
+    const b = toastStore.add(baseToast);
+
+    expect(toastStore.getSnapshot()).toHaveLength(1);
+    expect(b).toBe(a);
+  });
+
+  it("returns a new array reference on mutation", () => {
+    const before = toastStore.getSnapshot();
+    toastStore.add(baseToast);
+    const after = toastStore.getSnapshot();
+
+    expect(after).not.toBe(before);
+  });
+});
+
+describe("toastStore.dismiss", () => {
+  beforeEach(() => { vi.useFakeTimers(); });
+  afterEach(() => { vi.useRealTimers(); });
+
+  it("flags the toast dismissed and removes it after 2000ms", () => {
+    const id = toastStore.add(baseToast);
+
+    toastStore.dismiss(id);
+    expect(toastStore.getSnapshot()[0]?.dismissed).toBe(true);
+    expect(toastStore.getSnapshot()).toHaveLength(1);
+
+    vi.advanceTimersByTime(2000);
+    expect(toastStore.getSnapshot()).toHaveLength(0);
+  });
+
+  it("is a no-op for unknown ids", () => {
+    toastStore.dismiss(999);
+    expect(toastStore.getSnapshot()).toHaveLength(0);
+  });
+});
+
+describe("toastStore.remove", () => {
+  it("removes a toast by id and cancels any pending dismiss timer", () => {
+    vi.useFakeTimers();
+    const listener = vi.fn();
+    const id = toastStore.add(baseToast);
+    toastStore.dismiss(id);
+
+    toastStore.subscribe(listener);
+    toastStore.remove(id);
+    expect(toastStore.getSnapshot()).toHaveLength(0);
+
+    listener.mockClear();
+    vi.advanceTimersByTime(2000);
+    expect(listener).not.toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+
+  it("is a no-op for unknown ids and does not emit", () => {
+    const listener = vi.fn();
+    toastStore.subscribe(listener);
+
+    toastStore.remove(999);
+    expect(listener).not.toHaveBeenCalled();
+  });
+});
+
+describe("toastStore.subscribe", () => {
+  it("returns an unsubscribe function", () => {
+    const listener = vi.fn();
+    const unsubscribe = toastStore.subscribe(listener);
+
+    toastStore.add(baseToast);
+    expect(listener).toHaveBeenCalledOnce();
+
+    unsubscribe();
+    toastStore.add({ ...baseToast, body: "Two" });
+    expect(listener).toHaveBeenCalledOnce();
+  });
+});

package/Toasts/globalStore.ts

@@ -0,0 +1,86 @@
+import { Toast, ToastKind, ToastProps } from "./types";
+
+type Listener = () => void;
+
+let toasts: ToastProps[] = [];
+let nextId = 1;
+const listeners = new Set<Listener>();
+const pendingRemovals = new Map<number, ReturnType<typeof setTimeout>>();
+
+const emit = () => listeners.forEach(l => l());
+
+const isDuplicate = (toast: Toast) => toasts.some(t => (
+  t.body === toast.body && t.status === toast.status && t.title === toast.title
+));
+
+const add = (toast: Toast & { kind?: ToastKind }): number => {
+  if (isDuplicate(toast)) {
+    const existing = toasts.find(t => (
+      t.body === toast.body && t.status === toast.status && t.title === toast.title
+    ));
+    return existing!.id;
+  }
+
+  const id = toast.id ?? nextId++;
+  if (toast.id && toast.id >= nextId) nextId = toast.id + 1;
+
+  const next: ToastProps = {
+    body: toast.body,
+    id,
+    kind: toast.kind ?? "local",
+    status: toast.status,
+    timeout: toast.timeout,
+    title: toast.title,
+  };
+
+  toasts = [...toasts, next];
+  emit();
+  return id;
+};
+
+const dismiss = (id: number): void => {
+  const idx = toasts.findIndex(t => t.id === id);
+  if (idx < 0) return;
+
+  toasts = toasts.map((t, i) => (i === idx ? { ...t, dismissed: true } : t));
+  emit();
+
+  if (pendingRemovals.has(id)) return;
+
+  const timer = setTimeout(() => {
+    pendingRemovals.delete(id);
+    remove(id);
+  }, 2000);
+  pendingRemovals.set(id, timer);
+};
+
+const remove = (id: number): void => {
+  const timer = pendingRemovals.get(id);
+  if (timer) {
+    clearTimeout(timer);
+    pendingRemovals.delete(id);
+  }
+
+  const next = toasts.filter(t => t.id !== id);
+  if (next.length === toasts.length) return;
+
+  toasts = next;
+  emit();
+};
+
+const clear = (): void => {
+  pendingRemovals.forEach(t => clearTimeout(t));
+  pendingRemovals.clear();
+  toasts = [];
+  nextId = 1;
+  emit();
+};
+
+const subscribe = (listener: Listener): (() => void) => {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+};
+
+const getSnapshot = (): readonly ToastProps[] => toasts;
+
+export const toastStore = { add, clear, dismiss, getSnapshot, remove, subscribe };

package/Toasts/index.tsx

@@ -1,5 +1,9 @@
 export { default as Toasts } from "./Toasts";
+export { default as GlobalToasts } from "./GlobalToasts";
 export * from "./toastHelpers";
+export * from "./globalHelpers";
+export { useBroadcastChannel } from "./useBroadcastChannel";
+export type { BroadcastChannelHandle } from "./useBroadcastChannel";
 
 export * from "./types";
 export type * from "./types";

package/Toasts/types.ts

@@ -11,6 +11,8 @@ export type ToastAppAction =
   | { type: "addToast" } & Toast
   | ToastRemoveAppAction;
 
+export type ToastKind = "local" | "broadcast";
+
 export interface Toast {
   id?: number;
   status: Toast_Status;
@@ -18,6 +20,7 @@ export interface Toast {
   body: string;
   timeout: number;
   toastId?: number | undefined;
+  kind?: ToastKind;
 }
 
 export enum Toast_Status {

package/Toasts/useBroadcastChannel.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useBroadcastChannel } from "./useBroadcastChannel";
+import { broadcastSubscriptionRef } from "./cableConsumer";
+
+describe("useBroadcastChannel", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    broadcastSubscriptionRef.current = null;
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    broadcastSubscriptionRef.current = null;
+    warnSpy.mockRestore();
+  });
+
+  it("delegates send to the active subscription", () => {
+    const send = vi.fn();
+    broadcastSubscriptionRef.current = { send } as unknown as typeof broadcastSubscriptionRef.current;
+
+    const { send: handleSend } = useBroadcastChannel();
+    handleSend({ hello: "world" });
+
+    expect(send).toHaveBeenCalledWith({ hello: "world" });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("warns and is a no-op when no subscription is mounted", () => {
+    const { send } = useBroadcastChannel();
+    send({ hello: "world" });
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+  });
+});

package/Toasts/useBroadcastChannel.ts

@@ -0,0 +1,17 @@
+import { broadcastSubscriptionRef } from "./cableConsumer";
+
+export interface BroadcastChannelHandle {
+  send: (data: object) => void;
+}
+
+export const useBroadcastChannel = (): BroadcastChannelHandle => ({
+  send: (data: object) => {
+    const sub = broadcastSubscriptionRef.current;
+    if (!sub) {
+      // eslint-disable-next-line no-console
+      console.warn("useBroadcastChannel: <GlobalToasts /> is not mounted; broadcast send ignored");
+      return;
+    }
+    sub.send(data);
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unitedstatespowersquadrons/components",
-  "version": "1.3.14",
+  "version": "1.4.0-2",
   "description": "USPS shared React components library",
   "main": "index.tsx",
   "scripts": {