@open-mercato/ui 0.4.5-develop-6bdcebbece → 0.4.5-develop-986cfd8c37

package/src/backend/injection/eventBridge.ts

@@ -0,0 +1,134 @@
+"use client"
+import { useEffect, useRef } from 'react'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+import { APP_EVENT_DOM_NAME } from './useAppEvent'
+
+const SSE_ENDPOINT = '/api/events/stream'
+const HEARTBEAT_TIMEOUT = 45_000 // Expect heartbeat every 30s, allow 45s grace
+const RECONNECT_BASE_MS = 1_000
+const RECONNECT_MAX_MS = 30_000
+const DEDUP_WINDOW_MS = 500
+
+/**
+ * React hook that establishes a singleton SSE connection to the event bridge.
+ *
+ * Mount once in the app shell/layout. Receives server-side events with
+ * `clientBroadcast: true` and dispatches them as `om:event` CustomEvents
+ * on the window object for consumption by `useAppEvent`.
+ *
+ * Features:
+ * - Auto-reconnect with exponential backoff
+ * - Deduplication within 500ms window
+ * - Heartbeat-based liveness detection
+ * - Singleton connection per browser tab
+ */
+export function useEventBridge(): void {
+  const sourceRef = useRef<EventSource | null>(null)
+  const reconnectAttempts = useRef(0)
+  const reconnectTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const heartbeatTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const recentEvents = useRef<Map<string, number>>(new Map())
+
+  useEffect(() => {
+    let mounted = true
+
+    function isDuplicate(eventPayload: AppEventPayload): boolean {
+      const key = `${eventPayload.id}:${JSON.stringify(eventPayload.payload ?? {})}`
+      const lastSeen = recentEvents.current.get(key)
+      if (lastSeen && Date.now() - lastSeen < DEDUP_WINDOW_MS) return true
+      recentEvents.current.set(key, Date.now())
+      // Prune old entries
+      if (recentEvents.current.size > 100) {
+        const now = Date.now()
+        for (const [k, v] of recentEvents.current) {
+          if (now - v > DEDUP_WINDOW_MS * 2) recentEvents.current.delete(k)
+        }
+      }
+      return false
+    }
+
+    function resetHeartbeatTimer() {
+      if (heartbeatTimer.current) clearTimeout(heartbeatTimer.current)
+      heartbeatTimer.current = setTimeout(() => {
+        console.warn('[EventBridge] Heartbeat timeout — reconnecting')
+        disconnect()
+        scheduleReconnect()
+      }, HEARTBEAT_TIMEOUT)
+    }
+
+    function connect() {
+      if (!mounted) return
+      if (sourceRef.current) return
+
+      try {
+        const source = new EventSource(SSE_ENDPOINT, { withCredentials: true })
+        sourceRef.current = source
+
+        source.onopen = () => {
+          reconnectAttempts.current = 0
+          resetHeartbeatTimer()
+        }
+
+        source.onmessage = (event) => {
+          resetHeartbeatTimer()
+          if (!event.data || event.data === ':heartbeat') return
+
+          try {
+            const parsed = JSON.parse(event.data) as AppEventPayload
+            if (!parsed.id || typeof parsed.id !== 'string') return
+
+            if (isDuplicate(parsed)) return
+
+            window.dispatchEvent(
+              new CustomEvent(APP_EVENT_DOM_NAME, { detail: parsed }),
+            )
+          } catch {
+            // Ignore malformed events
+          }
+        }
+
+        source.onerror = () => {
+          disconnect()
+          if (mounted) scheduleReconnect()
+        }
+      } catch {
+        if (mounted) scheduleReconnect()
+      }
+    }
+
+    function disconnect() {
+      if (sourceRef.current) {
+        sourceRef.current.close()
+        sourceRef.current = null
+      }
+      if (heartbeatTimer.current) {
+        clearTimeout(heartbeatTimer.current)
+        heartbeatTimer.current = null
+      }
+    }
+
+    function scheduleReconnect() {
+      if (reconnectTimer.current) return
+      const delay = Math.min(
+        RECONNECT_BASE_MS * Math.pow(2, reconnectAttempts.current),
+        RECONNECT_MAX_MS,
+      )
+      reconnectAttempts.current++
+      reconnectTimer.current = setTimeout(() => {
+        reconnectTimer.current = null
+        connect()
+      }, delay)
+    }
+
+    connect()
+
+    return () => {
+      mounted = false
+      disconnect()
+      if (reconnectTimer.current) {
+        clearTimeout(reconnectTimer.current)
+        reconnectTimer.current = null
+      }
+    }
+  }, [])
+}

package/src/backend/injection/mergeMenuItems.ts

@@ -0,0 +1,71 @@
+import type { InjectionMenuItem } from '@open-mercato/shared/modules/widgets/injection'
+import { insertByInjectionPlacement } from '@open-mercato/shared/modules/widgets/injection-position'
+
+export type MergedMenuItem = {
+  id: string
+  label?: string
+  labelKey?: string
+  icon?: string
+  href?: string
+  onClick?: () => void
+  separator?: boolean
+  badge?: string | number
+  groupId?: string
+  groupLabel?: string
+  groupLabelKey?: string
+  groupOrder?: number
+  children?: Omit<InjectionMenuItem, 'children'>[]
+  source: 'built-in' | 'injected'
+}
+
+type BuiltInMenuItem = {
+  id: string
+  [key: string]: unknown
+}
+
+function toMergedInjectedItem(item: InjectionMenuItem): MergedMenuItem {
+  return {
+    id: item.id,
+    label: item.label,
+    labelKey: item.labelKey,
+    icon: item.icon,
+    href: item.href,
+    onClick: item.onClick,
+    separator: item.separator,
+    badge: item.badge,
+    groupId: item.groupId,
+    groupLabel: item.groupLabel,
+    groupLabelKey: item.groupLabelKey,
+    groupOrder: item.groupOrder,
+    children: item.children,
+    source: 'injected',
+  }
+}
+
+export function mergeMenuItems(
+  builtIn: BuiltInMenuItem[],
+  injected: InjectionMenuItem[],
+): MergedMenuItem[] {
+  let merged: MergedMenuItem[] = builtIn.map((item) => ({
+    ...(item as Record<string, unknown>),
+    id: item.id,
+    source: 'built-in',
+  })) as MergedMenuItem[]
+
+  for (const item of injected) {
+    const nextItem = toMergedInjectedItem(item)
+    if (!item.placement && item.groupId) {
+      const existingGroupIndexes = merged
+        .map((entry, index) => ({ entry, index }))
+        .filter(({ entry }) => entry.groupId === item.groupId)
+      if (existingGroupIndexes.length > 0) {
+        const insertAfter = existingGroupIndexes[existingGroupIndexes.length - 1]?.index ?? -1
+        merged.splice(insertAfter + 1, 0, nextItem)
+        continue
+      }
+    }
+    merged = insertByInjectionPlacement(merged, nextItem, item.placement, (entry) => entry.id)
+  }
+
+  return merged
+}

package/src/backend/injection/resolveInjectedIcon.tsx

@@ -0,0 +1,30 @@
+import * as React from 'react'
+import * as LucideIcons from 'lucide-react'
+
+type LucideIconComponent = React.ComponentType<{ className?: string }>
+
+function toPascalCaseIconName(name: string): string {
+  if (!name.includes('-') && !name.includes('_') && !name.includes(' ')) return name
+  return name
+    .split(/[-_\s]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+export function resolveInjectedIcon(icon?: string, className = 'size-4'): React.ReactNode | null {
+  if (!icon) return null
+  const normalized = icon.trim()
+  if (!normalized) return null
+
+  const candidates = [normalized, toPascalCaseIconName(normalized)]
+  const registry = LucideIcons as unknown as Record<string, LucideIconComponent | undefined>
+
+  for (const candidate of candidates) {
+    const IconComponent = registry[candidate]
+    if (!IconComponent) continue
+    return <IconComponent className={className} />
+  }
+
+  return null
+}

package/src/backend/injection/spotIds.ts

@@ -5,3 +5,41 @@ export const BACKEND_LAYOUT_TOP_INJECTION_SPOT_ID: InjectionSpotId = 'backend:la
 export const BACKEND_LAYOUT_FOOTER_INJECTION_SPOT_ID: InjectionSpotId = 'backend:layout:footer'
 export const BACKEND_SIDEBAR_TOP_INJECTION_SPOT_ID: InjectionSpotId = 'backend:sidebar:top'
 export const BACKEND_SIDEBAR_FOOTER_INJECTION_SPOT_ID: InjectionSpotId = 'backend:sidebar:footer'
+
+// Standardized backend chrome spot ids
+export const BACKEND_TOPBAR_PROFILE_MENU_INJECTION_SPOT_ID: InjectionSpotId = 'backend:topbar:profile-menu'
+export const BACKEND_TOPBAR_ACTIONS_INJECTION_SPOT_ID: InjectionSpotId = 'backend:topbar:actions'
+export const BACKEND_SIDEBAR_NAV_INJECTION_SPOT_ID: InjectionSpotId = 'backend:sidebar:nav'
+export const BACKEND_SIDEBAR_NAV_FOOTER_INJECTION_SPOT_ID: InjectionSpotId = 'backend:sidebar:nav:footer'
+
+// Standardized global status spot ids
+export const GLOBAL_SIDEBAR_STATUS_BADGES_INJECTION_SPOT_ID: InjectionSpotId = 'global:sidebar:status-badges'
+export const GLOBAL_HEADER_STATUS_INDICATORS_INJECTION_SPOT_ID: InjectionSpotId = 'global:header:status-indicators'
+
+// Standardized pattern helpers
+export const CrudFormInjectionSpots = {
+  base: (entityId: string): InjectionSpotId => `crud-form:${entityId}`,
+  beforeFields: (entityId: string): InjectionSpotId => `crud-form:${entityId}:before-fields`,
+  afterFields: (entityId: string): InjectionSpotId => `crud-form:${entityId}:after-fields`,
+  header: (entityId: string): InjectionSpotId => `crud-form:${entityId}:header`,
+  footer: (entityId: string): InjectionSpotId => `crud-form:${entityId}:footer`,
+  sidebar: (entityId: string): InjectionSpotId => `crud-form:${entityId}:sidebar`,
+  group: (entityId: string, groupId: string): InjectionSpotId => `crud-form:${entityId}:group:${groupId}`,
+  fieldBefore: (entityId: string, fieldId: string): InjectionSpotId => `crud-form:${entityId}:field:${fieldId}:before`,
+  fieldAfter: (entityId: string, fieldId: string): InjectionSpotId => `crud-form:${entityId}:field:${fieldId}:after`,
+} as const
+
+export const DataTableInjectionSpots = {
+  header: (tableId: string): InjectionSpotId => `data-table:${tableId}:header`,
+  footer: (tableId: string): InjectionSpotId => `data-table:${tableId}:footer`,
+  toolbar: (tableId: string): InjectionSpotId => `data-table:${tableId}:toolbar`,
+  emptyState: (tableId: string): InjectionSpotId => `data-table:${tableId}:empty-state`,
+} as const
+
+export const DetailInjectionSpots = {
+  header: (entityId: string): InjectionSpotId => `detail:${entityId}:header`,
+  tabs: (entityId: string): InjectionSpotId => `detail:${entityId}:tabs`,
+  sidebar: (entityId: string): InjectionSpotId => `detail:${entityId}:sidebar`,
+  footer: (entityId: string): InjectionSpotId => `detail:${entityId}:footer`,
+  statusBadges: (entityId: string): InjectionSpotId => `detail:${entityId}:status-badges`,
+} as const

package/src/backend/injection/useAppEvent.ts

@@ -0,0 +1,76 @@
+"use client"
+import { useEffect, useRef } from 'react'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+
+/**
+ * DOM Event Bridge event name.
+ * Server-side events with `clientBroadcast: true` are dispatched as
+ * CustomEvents with this name on the window object.
+ */
+export const APP_EVENT_DOM_NAME = 'om:event'
+
+/**
+ * Match an event ID against a wildcard pattern.
+ *
+ * Supports:
+ * - Exact match: `'example.todo.created'`
+ * - Wildcard suffix: `'example.todo.*'` matches `'example.todo.created'`, `'example.todo.updated'`
+ * - Global wildcard: `'*'` matches everything
+ *
+ * @example
+ * matchesPattern('example.todo.*', 'example.todo.created') // true
+ * matchesPattern('example.todo.*', 'example.item.created') // false
+ * matchesPattern('*', 'anything.here') // true
+ */
+export function matchesPattern(pattern: string, eventId: string): boolean {
+  if (pattern === '*') return true
+  if (!pattern.includes('*')) return pattern === eventId
+  const escapedPattern = pattern
+    .replace(/[|\\{}()[\]^$+?.]/g, '\\$&')
+    .replace(/\*/g, '.*')
+  const regex = new RegExp(
+    '^' + escapedPattern + '$',
+  )
+  return regex.test(eventId)
+}
+
+/**
+ * React hook that listens for app events delivered via the DOM Event Bridge.
+ *
+ * Events are dispatched as `om:event` CustomEvents on `window` by the event bridge
+ * (see `eventBridge.ts`). This hook filters events by pattern and calls the handler.
+ *
+ * @param eventPattern - Pattern to match event IDs against (e.g., 'example.todo.*')
+ * @param handler - Callback invoked when a matching event arrives
+ * @param deps - Optional dependency array for the handler (defaults to [])
+ *
+ * @example
+ * useAppEvent('example.todo.*', (event) => {
+ *   console.log('Todo event:', event.id, event.payload)
+ *   setRefreshKey(k => k + 1)
+ * })
+ */
+export function useAppEvent(
+  eventPattern: string,
+  handler: (payload: AppEventPayload) => void,
+  deps: unknown[] = [],
+): void {
+  const handlerRef = useRef(handler)
+  handlerRef.current = handler
+
+  useEffect(() => {
+    const listener = (e: Event) => {
+      const detail = (e as CustomEvent<AppEventPayload>).detail
+      if (!detail || typeof detail.id !== 'string') return
+      if (matchesPattern(eventPattern, detail.id)) {
+        handlerRef.current(detail)
+      }
+    }
+
+    window.addEventListener(APP_EVENT_DOM_NAME, listener)
+    return () => {
+      window.removeEventListener(APP_EVENT_DOM_NAME, listener)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [eventPattern, ...deps])
+}

package/src/backend/injection/useInjectedMenuItems.ts

@@ -0,0 +1,125 @@
+'use client'
+
+import * as React from 'react'
+import type { InjectionMenuItem } from '@open-mercato/shared/modules/widgets/injection'
+import { useInjectionDataWidgets } from './useInjectionDataWidgets'
+import { apiCall } from '../utils/apiCall'
+
+export type MenuSurfaceId =
+  | 'menu:sidebar:main'
+  | 'menu:sidebar:settings'
+  | 'menu:sidebar:profile'
+  | 'menu:topbar:profile-dropdown'
+  | 'menu:topbar:actions'
+  | `menu:sidebar:settings:${string}`
+  | `menu:sidebar:main:${string}`
+  | `menu:${string}`
+
+type FeatureCheckResponse = {
+  ok: boolean
+  granted?: string[]
+}
+
+type ProfileResponse = {
+  email?: string
+  roles?: string[]
+}
+
+function collectRequiredFeatures(items: InjectionMenuItem[]): string[] {
+  const set = new Set<string>()
+  for (const item of items) {
+    for (const feature of item.features ?? []) {
+      if (!feature || feature.trim().length === 0) continue
+      set.add(feature)
+    }
+  }
+  return Array.from(set)
+}
+
+async function readGrantedFeatures(features: string[]): Promise<Set<string>> {
+  if (features.length === 0) return new Set()
+  const call = await apiCall<FeatureCheckResponse>('/api/auth/feature-check', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ features }),
+  })
+  if (!call.ok) return new Set()
+  return new Set(call.result?.granted ?? [])
+}
+
+async function readUserRoles(): Promise<Set<string>> {
+  const call = await apiCall<ProfileResponse>('/api/auth/profile')
+  if (!call.ok) return new Set()
+  const roles = Array.isArray(call.result?.roles) ? call.result.roles : []
+  return new Set(roles.filter((role): role is string => typeof role === 'string' && role.trim().length > 0))
+}
+
+export function useInjectedMenuItems(surfaceId: MenuSurfaceId): {
+  items: InjectionMenuItem[]
+  isLoading: boolean
+} {
+  const { widgets, isLoading } = useInjectionDataWidgets(surfaceId)
+  const [grantedFeatures, setGrantedFeatures] = React.useState<Set<string>>(new Set())
+  const [userRoles, setUserRoles] = React.useState<Set<string>>(new Set())
+
+  const rawItems = React.useMemo(() => {
+    const entries: InjectionMenuItem[] = []
+    for (const widget of widgets) {
+      if (!('menuItems' in widget)) continue
+      const metadataFeatures = widget.metadata.features ?? []
+      for (const menuItem of widget.menuItems) {
+        const features = [...metadataFeatures, ...(menuItem.features ?? [])]
+        const normalizedLabelKey =
+          menuItem.labelKey ??
+          (typeof menuItem.label === 'string' && menuItem.label.includes('.') ? menuItem.label : undefined)
+        entries.push({
+          ...menuItem,
+          labelKey: normalizedLabelKey,
+          features,
+        })
+      }
+    }
+    return entries
+  }, [widgets])
+
+  React.useEffect(() => {
+    let mounted = true
+    const run = async () => {
+      const features = collectRequiredFeatures(rawItems)
+      const next = await readGrantedFeatures(features)
+      if (!mounted) return
+      setGrantedFeatures(next)
+    }
+    void run()
+    return () => {
+      mounted = false
+    }
+  }, [rawItems])
+
+  React.useEffect(() => {
+    let mounted = true
+    const run = async () => {
+      const roles = await readUserRoles()
+      if (!mounted) return
+      setUserRoles(roles)
+    }
+    void run()
+    return () => {
+      mounted = false
+    }
+  }, [])
+
+  const items = React.useMemo(
+    () =>
+      rawItems.filter((item) => {
+        const features = item.features ?? []
+        const roles = item.roles ?? []
+        const featuresOk = features.length === 0 || features.every((feature) => grantedFeatures.has(feature))
+        const rolesOk = roles.length === 0 || roles.some((role) => userRoles.has(role))
+        return featuresOk && rolesOk
+      }),
+    [rawItems, grantedFeatures, userRoles],
+  )
+
+  return { items, isLoading }
+}

package/src/backend/injection/useInjectionDataWidgets.ts

@@ -0,0 +1,41 @@
+'use client'
+
+import * as React from 'react'
+import type { InjectionSpotId } from '@open-mercato/shared/modules/widgets/injection'
+import { loadInjectionDataWidgetsForSpot, type LoadedInjectionDataWidget } from '@open-mercato/shared/modules/widgets/injection-loader'
+
+export function useInjectionDataWidgets(spotId: InjectionSpotId): {
+  widgets: LoadedInjectionDataWidget[]
+  isLoading: boolean
+  error: string | null
+} {
+  const [widgets, setWidgets] = React.useState<LoadedInjectionDataWidget[]>([])
+  const [isLoading, setIsLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+
+  React.useEffect(() => {
+    let mounted = true
+    const load = async () => {
+      try {
+        setIsLoading(true)
+        setError(null)
+        const loaded = await loadInjectionDataWidgetsForSpot(spotId)
+        if (!mounted) return
+        setWidgets(loaded)
+      } catch (loadError) {
+        if (!mounted) return
+        console.error(`[useInjectionDataWidgets] Failed to load widgets for spot ${spotId}:`, loadError)
+        setError(loadError instanceof Error ? loadError.message : String(loadError))
+        setWidgets([])
+      } finally {
+        if (mounted) setIsLoading(false)
+      }
+    }
+    void load()
+    return () => {
+      mounted = false
+    }
+  }, [spotId])
+
+  return { widgets, isLoading, error }
+}

package/src/backend/injection/useOperationProgress.ts

@@ -0,0 +1,105 @@
+"use client"
+import { useState, useRef, useEffect } from 'react'
+import type { OperationProgressEvent } from '@open-mercato/shared/modules/widgets/injection-progress'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+import { useAppEvent } from './useAppEvent'
+
+type ProgressStatus = 'idle' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+interface OperationProgressState {
+  status: ProgressStatus
+  progress: number
+  processedCount: number
+  totalCount: number
+  currentStep?: string
+  errors: number
+  startedAt?: number
+  elapsedMs: number
+}
+
+const IDLE_STATE: OperationProgressState = {
+  status: 'idle',
+  progress: 0,
+  processedCount: 0,
+  totalCount: 0,
+  errors: 0,
+  elapsedMs: 0,
+}
+
+/**
+ * React hook that tracks long-running operation progress via the DOM Event Bridge.
+ *
+ * Listens for progress events matching the given pattern and aggregates state.
+ * When `operationId` is provided, only events for that specific operation are tracked.
+ *
+ * @param operationPattern - Event pattern to listen for (e.g., 'integration.sync.progress')
+ * @param operationId - Optional filter for a specific operation instance
+ *
+ * @example
+ * const progress = useOperationProgress('integration.sync.progress', syncRunId)
+ * if (progress.status === 'running') {
+ *   return <ProgressBar value={progress.progress} />
+ * }
+ */
+export function useOperationProgress(
+  operationPattern: string,
+  operationId?: string,
+): OperationProgressState {
+  const [state, setState] = useState<OperationProgressState>(IDLE_STATE)
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const startedAtRef = useRef<number | undefined>(undefined)
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) {
+        clearInterval(timerRef.current)
+        timerRef.current = null
+      }
+    }
+  }, [])
+
+  useAppEvent(
+    operationPattern,
+    (event: AppEventPayload) => {
+      const payload = event.payload as unknown as OperationProgressEvent
+      if (!payload || typeof payload.status !== 'string') return
+      if (operationId && payload.operationId !== operationId) return
+
+      startedAtRef.current = payload.startedAt
+
+      const newState: OperationProgressState = {
+        status: payload.status,
+        progress: payload.progress,
+        processedCount: payload.processedCount,
+        totalCount: payload.totalCount,
+        currentStep: payload.currentStep,
+        errors: payload.errors,
+        startedAt: payload.startedAt,
+        elapsedMs: payload.startedAt ? Date.now() - payload.startedAt : 0,
+      }
+
+      setState(newState)
+
+      // Start elapsed time ticker when running
+      if (payload.status === 'running' && !timerRef.current) {
+        timerRef.current = setInterval(() => {
+          if (startedAtRef.current) {
+            setState((prev) => ({
+              ...prev,
+              elapsedMs: Date.now() - startedAtRef.current!,
+            }))
+          }
+        }, 1000)
+      }
+
+      // Clear ticker when operation ends
+      if (payload.status !== 'running' && timerRef.current) {
+        clearInterval(timerRef.current)
+        timerRef.current = null
+      }
+    },
+    [operationId],
+  )
+
+  return state
+}

package/src/backend/injection/useWidgetSharedState.ts

@@ -0,0 +1,28 @@
+'use client'
+
+import * as React from 'react'
+import { getWidgetSharedState } from './WidgetSharedState'
+
+export function useWidgetSharedState<T>(key: string, namespace = 'global'): [T | undefined, (value: T) => void] {
+  const store = React.useMemo(() => getWidgetSharedState(namespace), [namespace])
+
+  const subscribe = React.useCallback(
+    (onStoreChange: () => void) => {
+      const unsubscribe = store.subscribe(key, () => onStoreChange())
+      return unsubscribe
+    },
+    [key, store],
+  )
+
+  const getSnapshot = React.useCallback(() => store.get<T>(key), [key, store])
+  const value = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+  const setValue = React.useCallback(
+    (nextValue: T) => {
+      store.set<T>(key, nextValue)
+    },
+    [key, store],
+  )
+
+  return [value, setValue]
+}