@open-mercato/ui 0.8.1-develop.7268.1.033c0546d5 → 0.8.1-develop.7269.1.493e13f954

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
 Generated lucide registry with 169 icons -> /home/runner/work/open-mercato/open-mercato/packages/ui/src/backend/icons/lucideRegistry.generated.tsx
-[build:ui] found 451 entry points
+[build:ui] found 452 entry points
 [build:ui] built successfully

package/dist/backend/injection/useAppEventCoalesced.js

@@ -0,0 +1,43 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { APP_EVENT_DOM_NAME, matchesPattern } from "./useAppEvent.js";
+const DEFAULT_APP_EVENT_COALESCE_WINDOW_MS = 1e3;
+function useAppEventCoalesced(eventPattern, handler, deps = [], options = {}) {
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  const windowMs = options.windowMs ?? DEFAULT_APP_EVENT_COALESCE_WINDOW_MS;
+  useEffect(() => {
+    let windowTimer = null;
+    let pending = null;
+    const closeWindow = () => {
+      windowTimer = null;
+      if (!pending) return;
+      const payload = pending;
+      pending = null;
+      handlerRef.current(payload);
+    };
+    const listener = (e) => {
+      const detail = e.detail;
+      if (!detail || typeof detail.id !== "string") return;
+      if (!matchesPattern(eventPattern, detail.id)) return;
+      if (windowTimer !== null) {
+        pending = detail;
+        return;
+      }
+      windowTimer = setTimeout(closeWindow, windowMs);
+      handlerRef.current(detail);
+    };
+    window.addEventListener(APP_EVENT_DOM_NAME, listener);
+    return () => {
+      window.removeEventListener(APP_EVENT_DOM_NAME, listener);
+      if (windowTimer !== null) clearTimeout(windowTimer);
+      windowTimer = null;
+      pending = null;
+    };
+  }, [eventPattern, windowMs, ...deps]);
+}
+export {
+  DEFAULT_APP_EVENT_COALESCE_WINDOW_MS,
+  useAppEventCoalesced
+};
+//# sourceMappingURL=useAppEventCoalesced.js.map

package/dist/backend/injection/useAppEventCoalesced.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/backend/injection/useAppEventCoalesced.ts"],
+  "sourcesContent": ["\"use client\"\nimport { useEffect, useRef } from 'react'\nimport type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'\nimport { APP_EVENT_DOM_NAME, matchesPattern } from './useAppEvent'\n\n/**\n * Default coalescing window. Long enough to swallow a server-side ingest burst\n * (a mail poll emits its per-message events within a few hundred milliseconds),\n * short enough that the trailing refresh is not perceived as lag.\n */\nexport const DEFAULT_APP_EVENT_COALESCE_WINDOW_MS = 1000\n\nexport type AppEventCoalesceOptions = {\n  /** Coalescing window in milliseconds. Defaults to {@link DEFAULT_APP_EVENT_COALESCE_WINDOW_MS}. */\n  windowMs?: number\n}\n\n/**\n * Like {@link useAppEvent}, but collapses a burst of matching events into a\n * leading and a trailing handler call.\n *\n * Use this when the handler is expensive and idempotent \u2014 a react-query\n * invalidation that reloads a list is the canonical case: a single ingest cycle\n * emitting N events would otherwise trigger N full reloads of the same page.\n *\n * Semantics (leading + trailing, not plain debounce):\n * - The first event of a quiet period is handled synchronously, so a single\n *   user action still refreshes immediately.\n * - Every further event inside the window is collapsed; when the window closes,\n *   the handler runs once more with the most recent payload, so the final state\n *   is never missed. A burst spanning several windows keeps collapsing at a\n *   steady one call per window.\n * - Unmounting clears the pending window; the handler never runs afterwards.\n *\n * This differs from `NotificationDispatcher`'s `debounceMs` suppression, which\n * drops repeats outright because re-showing a toast has no value. Here the\n * trailing call is mandatory, because dropping it would leave the list stale.\n *\n * @param eventPattern - Pattern to match event IDs against (e.g. 'messages.message.*')\n * @param handler - Callback invoked with the most recent matching event of the window\n * @param deps - Optional dependency array for the handler (defaults to [])\n * @param options - Coalescing options\n *\n * @example\n * useAppEventCoalesced('messages.message.*', () => {\n *   void queryClient.invalidateQueries({ queryKey: ['messages', 'list'] })\n * }, [queryClient])\n */\nexport function useAppEventCoalesced(\n  eventPattern: string,\n  handler: (payload: AppEventPayload) => void,\n  deps: unknown[] = [],\n  options: AppEventCoalesceOptions = {},\n): void {\n  const handlerRef = useRef(handler)\n  handlerRef.current = handler\n  const windowMs = options.windowMs ?? DEFAULT_APP_EVENT_COALESCE_WINDOW_MS\n\n  useEffect(() => {\n    let windowTimer: ReturnType<typeof setTimeout> | null = null\n    let pending: AppEventPayload | null = null\n\n    const closeWindow = () => {\n      windowTimer = null\n      if (!pending) return\n      const payload = pending\n      pending = null\n      handlerRef.current(payload)\n    }\n\n    const listener = (e: Event) => {\n      const detail = (e as CustomEvent<AppEventPayload>).detail\n      if (!detail || typeof detail.id !== 'string') return\n      if (!matchesPattern(eventPattern, detail.id)) return\n      if (windowTimer !== null) {\n        pending = detail\n        return\n      }\n      windowTimer = setTimeout(closeWindow, windowMs)\n      handlerRef.current(detail)\n    }\n\n    window.addEventListener(APP_EVENT_DOM_NAME, listener)\n    return () => {\n      window.removeEventListener(APP_EVENT_DOM_NAME, listener)\n      if (windowTimer !== null) clearTimeout(windowTimer)\n      windowTimer = null\n      pending = null\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [eventPattern, windowMs, ...deps])\n}\n"],
+  "mappings": ";AACA,SAAS,WAAW,cAAc;AAElC,SAAS,oBAAoB,sBAAsB;AAO5C,MAAM,uCAAuC;AAsC7C,SAAS,qBACd,cACA,SACA,OAAkB,CAAC,GACnB,UAAmC,CAAC,GAC9B;AACN,QAAM,aAAa,OAAO,OAAO;AACjC,aAAW,UAAU;AACrB,QAAM,WAAW,QAAQ,YAAY;AAErC,YAAU,MAAM;AACd,QAAI,cAAoD;AACxD,QAAI,UAAkC;AAEtC,UAAM,cAAc,MAAM;AACxB,oBAAc;AACd,UAAI,CAAC,QAAS;AACd,YAAM,UAAU;AAChB,gBAAU;AACV,iBAAW,QAAQ,OAAO;AAAA,IAC5B;AAEA,UAAM,WAAW,CAAC,MAAa;AAC7B,YAAM,SAAU,EAAmC;AACnD,UAAI,CAAC,UAAU,OAAO,OAAO,OAAO,SAAU;AAC9C,UAAI,CAAC,eAAe,cAAc,OAAO,EAAE,EAAG;AAC9C,UAAI,gBAAgB,MAAM;AACxB,kBAAU;AACV;AAAA,MACF;AACA,oBAAc,WAAW,aAAa,QAAQ;AAC9C,iBAAW,QAAQ,MAAM;AAAA,IAC3B;AAEA,WAAO,iBAAiB,oBAAoB,QAAQ;AACpD,WAAO,MAAM;AACX,aAAO,oBAAoB,oBAAoB,QAAQ;AACvD,UAAI,gBAAgB,KAAM,cAAa,WAAW;AAClD,oBAAc;AACd,gBAAU;AAAA,IACZ;AAAA,EAEF,GAAG,CAAC,cAAc,UAAU,GAAG,IAAI,CAAC;AACtC;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/ui",
-  "version": "0.8.1-develop.7268.1.033c0546d5",
+  "version": "0.8.1-develop.7269.1.493e13f954",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -155,14 +155,14 @@
     "remark-gfm": "^4.0.1"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.8.1-develop.7268.1.033c0546d5",
+    "@open-mercato/shared": "0.8.1-develop.7269.1.493e13f954",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "react-is": ">=18.0.0"
   },
   "devDependencies": {
     "@figma/code-connect": "^1.3.4",
-    "@open-mercato/shared": "0.8.1-develop.7268.1.033c0546d5",
+    "@open-mercato/shared": "0.8.1-develop.7269.1.493e13f954",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",

package/src/backend/injection/__tests__/useAppEventCoalesced.test.tsx

@@ -0,0 +1,166 @@
+/** @jest-environment jsdom */
+import { act, renderHook } from '@testing-library/react'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+import { APP_EVENT_DOM_NAME, useAppEvent } from '../useAppEvent'
+import { DEFAULT_APP_EVENT_COALESCE_WINDOW_MS, useAppEventCoalesced } from '../useAppEventCoalesced'
+
+const MESSAGE_LIST_KEY = ['messages', 'list']
+
+function dispatchMessageEvents(count: number, gapMs = 5) {
+  for (let i = 0; i < count; i++) {
+    const detail: AppEventPayload = {
+      id: 'messages.message.sent',
+      payload: { messageId: `message-${i}` },
+    } as AppEventPayload
+    act(() => {
+      window.dispatchEvent(new CustomEvent(APP_EVENT_DOM_NAME, { detail }))
+      jest.advanceTimersByTime(gapMs)
+    })
+  }
+}
+
+describe('useAppEventCoalesced', () => {
+  let invalidateQueries: jest.Mock
+
+  beforeEach(() => {
+    jest.useFakeTimers()
+    invalidateQueries = jest.fn()
+  })
+
+  afterEach(() => {
+    jest.useRealTimers()
+  })
+
+  const invalidateMessageList = () => {
+    invalidateQueries({ queryKey: MESSAGE_LIST_KEY })
+  }
+
+  it('characterizes the un-coalesced hook: one invalidation per ingested message', () => {
+    renderHook(() => useAppEvent('messages.message.*', invalidateMessageList, []))
+
+    dispatchMessageEvents(50)
+
+    expect(invalidateQueries).toHaveBeenCalledTimes(50)
+    expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: MESSAGE_LIST_KEY })
+  })
+
+  it('collapses an ingest burst into a leading and a trailing invalidation', () => {
+    renderHook(() => useAppEventCoalesced('messages.message.*', invalidateMessageList, []))
+
+    dispatchMessageEvents(50)
+    expect(invalidateQueries).toHaveBeenCalledTimes(1)
+
+    act(() => {
+      jest.advanceTimersByTime(DEFAULT_APP_EVENT_COALESCE_WINDOW_MS)
+    })
+
+    expect(invalidateQueries).toHaveBeenCalledTimes(2)
+    expect(invalidateQueries).toHaveBeenCalledWith({ queryKey: MESSAGE_LIST_KEY })
+  })
+
+  it('runs the trailing invalidation even when the burst ends mid-window', () => {
+    const handler = jest.fn()
+    renderHook(() => useAppEventCoalesced('messages.message.*', handler, []))
+
+    dispatchMessageEvents(3)
+    expect(handler).toHaveBeenCalledTimes(1)
+
+    act(() => {
+      jest.advanceTimersByTime(DEFAULT_APP_EVENT_COALESCE_WINDOW_MS)
+    })
+
+    expect(handler).toHaveBeenCalledTimes(2)
+    expect(handler.mock.calls[1][0]).toMatchObject({ payload: { messageId: 'message-2' } })
+  })
+
+  it('invalidates once and immediately for a single event', () => {
+    renderHook(() => useAppEventCoalesced('messages.message.*', invalidateMessageList, []))
+
+    dispatchMessageEvents(1)
+    expect(invalidateQueries).toHaveBeenCalledTimes(1)
+
+    act(() => {
+      jest.advanceTimersByTime(DEFAULT_APP_EVENT_COALESCE_WINDOW_MS * 5)
+    })
+
+    expect(invalidateQueries).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps slow traffic at one invalidation per event', () => {
+    renderHook(() => useAppEventCoalesced('messages.message.*', invalidateMessageList, []))
+
+    for (let i = 0; i < 4; i++) {
+      dispatchMessageEvents(1)
+      act(() => {
+        jest.advanceTimersByTime(DEFAULT_APP_EVENT_COALESCE_WINDOW_MS * 2)
+      })
+    }
+
+    expect(invalidateQueries).toHaveBeenCalledTimes(4)
+  })
+
+  it('does not invalidate after unmount mid-window', () => {
+    const { unmount } = renderHook(() =>
+      useAppEventCoalesced('messages.message.*', invalidateMessageList, []),
+    )
+
+    dispatchMessageEvents(10)
+    expect(invalidateQueries).toHaveBeenCalledTimes(1)
+
+    unmount()
+
+    act(() => {
+      jest.advanceTimersByTime(DEFAULT_APP_EVENT_COALESCE_WINDOW_MS * 5)
+    })
+    dispatchMessageEvents(5)
+
+    expect(invalidateQueries).toHaveBeenCalledTimes(1)
+  })
+
+  it('ignores events that do not match the pattern', () => {
+    renderHook(() => useAppEventCoalesced('messages.message.*', invalidateMessageList, []))
+
+    act(() => {
+      window.dispatchEvent(
+        new CustomEvent(APP_EVENT_DOM_NAME, { detail: { id: 'sales.order.created' } }),
+      )
+      jest.advanceTimersByTime(DEFAULT_APP_EVENT_COALESCE_WINDOW_MS * 2)
+    })
+
+    expect(invalidateQueries).not.toHaveBeenCalled()
+  })
+
+  it('fires immediately for a fresh event shortly after a multi-event burst settles', () => {
+    renderHook(() => useAppEventCoalesced('messages.message.*', invalidateMessageList, []))
+
+    dispatchMessageEvents(2)
+    expect(invalidateQueries).toHaveBeenCalledTimes(1)
+
+    act(() => {
+      jest.advanceTimersByTime(DEFAULT_APP_EVENT_COALESCE_WINDOW_MS)
+    })
+    expect(invalidateQueries).toHaveBeenCalledTimes(2)
+
+    act(() => {
+      jest.advanceTimersByTime(100)
+    })
+    dispatchMessageEvents(1)
+
+    expect(invalidateQueries).toHaveBeenCalledTimes(3)
+  })
+
+  it('honours a custom window', () => {
+    renderHook(() =>
+      useAppEventCoalesced('messages.message.*', invalidateMessageList, [], { windowMs: 200 }),
+    )
+
+    dispatchMessageEvents(10, 1)
+    expect(invalidateQueries).toHaveBeenCalledTimes(1)
+
+    act(() => {
+      jest.advanceTimersByTime(200)
+    })
+
+    expect(invalidateQueries).toHaveBeenCalledTimes(2)
+  })
+})

package/src/backend/injection/useAppEventCoalesced.ts

@@ -0,0 +1,92 @@
+"use client"
+import { useEffect, useRef } from 'react'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+import { APP_EVENT_DOM_NAME, matchesPattern } from './useAppEvent'
+
+/**
+ * Default coalescing window. Long enough to swallow a server-side ingest burst
+ * (a mail poll emits its per-message events within a few hundred milliseconds),
+ * short enough that the trailing refresh is not perceived as lag.
+ */
+export const DEFAULT_APP_EVENT_COALESCE_WINDOW_MS = 1000
+
+export type AppEventCoalesceOptions = {
+  /** Coalescing window in milliseconds. Defaults to {@link DEFAULT_APP_EVENT_COALESCE_WINDOW_MS}. */
+  windowMs?: number
+}
+
+/**
+ * Like {@link useAppEvent}, but collapses a burst of matching events into a
+ * leading and a trailing handler call.
+ *
+ * Use this when the handler is expensive and idempotent — a react-query
+ * invalidation that reloads a list is the canonical case: a single ingest cycle
+ * emitting N events would otherwise trigger N full reloads of the same page.
+ *
+ * Semantics (leading + trailing, not plain debounce):
+ * - The first event of a quiet period is handled synchronously, so a single
+ *   user action still refreshes immediately.
+ * - Every further event inside the window is collapsed; when the window closes,
+ *   the handler runs once more with the most recent payload, so the final state
+ *   is never missed. A burst spanning several windows keeps collapsing at a
+ *   steady one call per window.
+ * - Unmounting clears the pending window; the handler never runs afterwards.
+ *
+ * This differs from `NotificationDispatcher`'s `debounceMs` suppression, which
+ * drops repeats outright because re-showing a toast has no value. Here the
+ * trailing call is mandatory, because dropping it would leave the list stale.
+ *
+ * @param eventPattern - Pattern to match event IDs against (e.g. 'messages.message.*')
+ * @param handler - Callback invoked with the most recent matching event of the window
+ * @param deps - Optional dependency array for the handler (defaults to [])
+ * @param options - Coalescing options
+ *
+ * @example
+ * useAppEventCoalesced('messages.message.*', () => {
+ *   void queryClient.invalidateQueries({ queryKey: ['messages', 'list'] })
+ * }, [queryClient])
+ */
+export function useAppEventCoalesced(
+  eventPattern: string,
+  handler: (payload: AppEventPayload) => void,
+  deps: unknown[] = [],
+  options: AppEventCoalesceOptions = {},
+): void {
+  const handlerRef = useRef(handler)
+  handlerRef.current = handler
+  const windowMs = options.windowMs ?? DEFAULT_APP_EVENT_COALESCE_WINDOW_MS
+
+  useEffect(() => {
+    let windowTimer: ReturnType<typeof setTimeout> | null = null
+    let pending: AppEventPayload | null = null
+
+    const closeWindow = () => {
+      windowTimer = null
+      if (!pending) return
+      const payload = pending
+      pending = null
+      handlerRef.current(payload)
+    }
+
+    const listener = (e: Event) => {
+      const detail = (e as CustomEvent<AppEventPayload>).detail
+      if (!detail || typeof detail.id !== 'string') return
+      if (!matchesPattern(eventPattern, detail.id)) return
+      if (windowTimer !== null) {
+        pending = detail
+        return
+      }
+      windowTimer = setTimeout(closeWindow, windowMs)
+      handlerRef.current(detail)
+    }
+
+    window.addEventListener(APP_EVENT_DOM_NAME, listener)
+    return () => {
+      window.removeEventListener(APP_EVENT_DOM_NAME, listener)
+      if (windowTimer !== null) clearTimeout(windowTimer)
+      windowTimer = null
+      pending = null
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [eventPattern, windowMs, ...deps])
+}