@freighttech/ui 0.13.18

package/src/portal/hooks/usePortalDashboardWidgets.ts

@@ -0,0 +1,50 @@
+'use client'
+
+import * as React from 'react'
+import type { InjectionSpotId } from '@open-mercato/shared/modules/widgets/injection'
+import { loadInjectionWidgetsForSpot, type LoadedInjectionWidget } from '@open-mercato/shared/modules/widgets/injection-loader'
+
+/**
+ * Loads UI injection widgets (with Widget component) for a portal spot.
+ *
+ * Unlike `useInjectionDataWidgets` which loads data-only widgets (columns, fields, menuItems),
+ * this hook loads widgets that export a `Widget` React component — suitable for
+ * portal dashboard sections and other UI injection spots.
+ */
+export function usePortalDashboardWidgets(spotId: InjectionSpotId): {
+  widgets: LoadedInjectionWidget[]
+  isLoading: boolean
+  error: string | null
+} {
+  const [widgets, setWidgets] = React.useState<LoadedInjectionWidget[]>([])
+  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 loadInjectionWidgetsForSpot(spotId)
+        if (!mounted) return
+        // Only keep widgets that have a Widget component
+        const uiWidgets = loaded.filter((w) => typeof w.Widget === 'function')
+        setWidgets(uiWidgets)
+      } catch (loadError) {
+        if (!mounted) return
+        console.error(`[usePortalDashboardWidgets] 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/portal/hooks/usePortalEventBridge.ts

@@ -0,0 +1,162 @@
+"use client"
+import { useEffect, useRef } from 'react'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+import { PORTAL_EVENT_DOM_NAME } from './usePortalAppEvent'
+
+const PORTAL_SSE_ENDPOINT = '/api/customer_accounts/portal/events/stream'
+const HEARTBEAT_TIMEOUT = 45_000
+const RECONNECT_BASE_MS = 1_000
+const RECONNECT_MAX_MS = 30_000
+const DEDUP_WINDOW_MS = 500
+const PORTAL_BRIDGE_RECONNECTED_EVENT_ID = 'om:portal-bridge:reconnected'
+
+/**
+ * React hook that establishes a singleton SSE connection to the portal event bridge.
+ *
+ * Mount once in the portal shell/layout. Receives server-side events with
+ * `portalBroadcast: true` and dispatches them as `om:portal-event` CustomEvents
+ * on the window object for consumption by `usePortalAppEvent`.
+ *
+ * Uses customer auth (cookie-based JWT) instead of staff auth.
+ *
+ * @example
+ * ```tsx
+ * import { usePortalEventBridge } from '@freighttech/ui/portal/hooks/usePortalEventBridge'
+ *
+ * function PortalShell({ children }) {
+ *   usePortalEventBridge()
+ *   return <div>{children}</div>
+ * }
+ * ```
+ */
+export function usePortalEventBridge(): 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())
+  const hasEverConnected = useRef(false)
+  const reconnectPending = useRef(false)
+
+  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())
+      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('[PortalEventBridge] Heartbeat timeout — reconnecting')
+        disconnect()
+        scheduleReconnect()
+      }, HEARTBEAT_TIMEOUT)
+    }
+
+    function connect() {
+      if (!mounted) return
+      if (sourceRef.current) return
+
+      try {
+        const source = new EventSource(PORTAL_SSE_ENDPOINT, { withCredentials: true })
+        sourceRef.current = source
+
+        source.onopen = () => {
+          const shouldEmitReconnect = hasEverConnected.current && reconnectPending.current
+          hasEverConnected.current = true
+          reconnectPending.current = false
+          reconnectAttempts.current = 0
+          resetHeartbeatTimer()
+          if (shouldEmitReconnect) {
+            window.dispatchEvent(
+              new CustomEvent(PORTAL_EVENT_DOM_NAME, {
+                detail: {
+                  id: PORTAL_BRIDGE_RECONNECTED_EVENT_ID,
+                  payload: {},
+                  timestamp: Date.now(),
+                  organizationId: '',
+                } satisfies AppEventPayload,
+              }),
+            )
+          }
+        }
+
+        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(PORTAL_EVENT_DOM_NAME, { detail: parsed }),
+            )
+          } catch {
+            // Ignore malformed events
+          }
+        }
+
+        source.onerror = () => {
+          if (hasEverConnected.current) {
+            reconnectPending.current = true
+          }
+          disconnect()
+          if (mounted) scheduleReconnect()
+        }
+      } catch {
+        if (hasEverConnected.current) {
+          reconnectPending.current = true
+        }
+        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/portal/hooks/usePortalInjectedMenuItems.ts

@@ -0,0 +1,130 @@
+'use client'
+
+import * as React from 'react'
+import type { InjectionMenuItem } from '@open-mercato/shared/modules/widgets/injection'
+import { hasAllFeatures } from '@open-mercato/shared/security/features'
+import { useInjectionDataWidgets } from '../../backend/injection/useInjectionDataWidgets'
+import { apiCall } from '../../backend/utils/apiCall'
+import { usePortalContext } from '../PortalContext'
+
+function useOptionalOrgSlug(): string {
+  try {
+    return usePortalContext().orgSlug
+  } catch {
+    return ''
+  }
+}
+
+export type PortalMenuSurfaceId =
+  | 'menu:portal:sidebar:main'
+  | 'menu:portal:sidebar:account'
+  | 'menu:portal:header:actions'
+  | 'menu:portal:user-dropdown'
+  | `menu:portal:${string}`
+
+type PortalFeatureCheckResponse = {
+  ok: boolean
+  granted?: 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 readPortalGrantedFeatures(features: string[]): Promise<Set<string>> {
+  if (features.length === 0) return new Set()
+  try {
+    const { ok, result: data } = await apiCall<PortalFeatureCheckResponse>('/api/customer_accounts/portal/feature-check', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ features }),
+    })
+    if (!ok || !data?.ok) return new Set()
+    return new Set(data.granted ?? [])
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * Portal-aware variant of useInjectedMenuItems.
+ *
+ * Checks feature visibility against the customer portal RBAC
+ * via `/api/customer_accounts/portal/feature-check` instead of
+ * the staff `/api/auth/feature-check`.
+ *
+ * @example
+ * ```tsx
+ * import { usePortalInjectedMenuItems } from '@freighttech/ui/portal/hooks/usePortalInjectedMenuItems'
+ *
+ * const { items, isLoading } = usePortalInjectedMenuItems('menu:portal:sidebar:main')
+ * ```
+ */
+export function usePortalInjectedMenuItems(surfaceId: PortalMenuSurfaceId): {
+  items: InjectionMenuItem[]
+  isLoading: boolean
+} {
+  const { widgets, isLoading } = useInjectionDataWidgets(surfaceId)
+  const orgSlug = useOptionalOrgSlug()
+  const [grantedFeatures, setGrantedFeatures] = React.useState<Set<string>>(new Set())
+  const grantedFeatureList = React.useMemo(() => Array.from(grantedFeatures), [grantedFeatures])
+
+  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 readPortalGrantedFeatures(features)
+      if (!mounted) return
+      setGrantedFeatures(next)
+    }
+    void run()
+    return () => {
+      mounted = false
+    }
+  }, [rawItems])
+
+  const items = React.useMemo(
+    () =>
+      rawItems
+        .filter((item) => {
+          const features = item.features ?? []
+          return features.length === 0 || hasAllFeatures(grantedFeatureList, features)
+        })
+        .map((item) => ({
+          ...item,
+          href: item.href && orgSlug && item.href.startsWith('/portal/')
+            ? `/${orgSlug}${item.href}`
+            : item.href,
+        })),
+    [rawItems, grantedFeatureList, orgSlug],
+  )
+
+  return { items, isLoading }
+}

package/src/portal/hooks/usePortalNotifications.ts

@@ -0,0 +1,116 @@
+"use client"
+import * as React from 'react'
+import type { NotificationDto } from '@open-mercato/shared/modules/notifications/types'
+import { apiCall } from '../../backend/utils/apiCall'
+
+export type UsePortalNotificationsResult = {
+  notifications: NotificationDto[]
+  unreadCount: number
+  hasNew: boolean
+  isLoading: boolean
+  refresh: () => void
+  markAsRead: (id: string) => Promise<void>
+  dismiss: (id: string) => Promise<void>
+  markAllRead: () => Promise<void>
+}
+
+const POLL_INTERVAL = 8000
+const BASE = '/api/customer_accounts/portal/notifications'
+
+async function fetchJson<T>(url: string, init?: RequestInit): Promise<T | null> {
+  try {
+    const { ok, result } = await apiCall<T>(url, init)
+    if (!ok) return null
+    return result
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Portal notification hook — polls customer notification endpoints.
+ *
+ * Fetches notifications from `/api/customer_accounts/portal/notifications`
+ * and unread count from `.../unread-count`. Polls every 8 seconds.
+ *
+ * Also listens for portal SSE events (`notifications.notification.created`)
+ * to trigger immediate refresh.
+ */
+export function usePortalNotifications(): UsePortalNotificationsResult {
+  const [notifications, setNotifications] = React.useState<NotificationDto[]>([])
+  const [unreadCount, setUnreadCount] = React.useState(0)
+  const [hasNew, setHasNew] = React.useState(false)
+  const [isLoading, setIsLoading] = React.useState(true)
+  const lastIdRef = React.useRef<string | null>(null)
+
+  const fetchAll = React.useCallback(async () => {
+    const [listData, countData] = await Promise.all([
+      fetchJson<{ ok: boolean; items: NotificationDto[] }>(`${BASE}?pageSize=50`),
+      fetchJson<{ ok: boolean; unreadCount: number }>(`${BASE}/unread-count`),
+    ])
+
+    if (listData?.ok && listData.items) {
+      const items = listData.items
+      if (lastIdRef.current && items.length > 0 && items[0].id !== lastIdRef.current) {
+        setHasNew(true)
+        setTimeout(() => setHasNew(false), 3000)
+      }
+      if (items.length > 0) lastIdRef.current = items[0].id
+      setNotifications(items)
+    }
+
+    if (countData?.ok) {
+      setUnreadCount(countData.unreadCount)
+    }
+
+    setIsLoading(false)
+  }, [])
+
+  // Poll
+  React.useEffect(() => {
+    fetchAll()
+    const interval = setInterval(fetchAll, POLL_INTERVAL)
+    return () => clearInterval(interval)
+  }, [fetchAll])
+
+  // Listen for portal SSE notification events
+  React.useEffect(() => {
+    const handler = (e: Event) => {
+      const detail = (e as CustomEvent).detail
+      if (detail?.id === 'notifications.notification.created' || detail?.id === 'notifications.notification.batch_created') {
+        fetchAll()
+      }
+    }
+    window.addEventListener('om:portal-event', handler)
+    return () => window.removeEventListener('om:portal-event', handler)
+  }, [fetchAll])
+
+  const markAsRead = React.useCallback(async (id: string) => {
+    await fetchJson(`${BASE}/${id}/read`, { method: 'PUT' })
+    setNotifications((prev) =>
+      prev.map((n) => (n.id === id ? { ...n, status: 'read', readAt: new Date().toISOString() } : n)),
+    )
+    setUnreadCount((prev) => Math.max(0, prev - 1))
+  }, [])
+
+  const dismiss = React.useCallback(async (id: string) => {
+    await fetchJson(`${BASE}/${id}/dismiss`, { method: 'PUT' })
+    setNotifications((prev) => prev.filter((n) => n.id !== id))
+    setUnreadCount((prev) => {
+      const wasDismissedUnread = notifications.find((n) => n.id === id)?.status === 'unread'
+      return wasDismissedUnread ? Math.max(0, prev - 1) : prev
+    })
+  }, [notifications])
+
+  const markAllRead = React.useCallback(async () => {
+    await fetchJson(`${BASE}/mark-all-read`, { method: 'PUT' })
+    setNotifications((prev) =>
+      prev.map((n) => (n.status === 'unread' ? { ...n, status: 'read', readAt: new Date().toISOString() } : n)),
+    )
+    setUnreadCount(0)
+  }, [])
+
+  const refresh = React.useCallback(() => { fetchAll() }, [fetchAll])
+
+  return { notifications, unreadCount, hasNew, isLoading, refresh, markAsRead, dismiss, markAllRead }
+}

package/src/portal/hooks/useTenantContext.ts

@@ -0,0 +1,83 @@
+"use client"
+import { useEffect, useState } from 'react'
+import { apiCall } from '../../backend/utils/apiCall'
+
+type OrgContext = {
+  tenantId: string | undefined
+  organizationId: string | undefined
+  organizationName: string | undefined
+  loading: boolean
+  error: string | null
+}
+
+/**
+ * Client-side hook for resolving organization/tenant context by slug.
+ *
+ * Used in portal pages before login/signup to resolve the tenant and organization
+ * from the URL slug via `/api/directory/organizations/lookup`.
+ *
+ * @param orgSlug - Organization slug from the URL
+ *
+ * @example
+ * ```tsx
+ * import { useTenantContext } from '@freighttech/ui/portal/hooks/useTenantContext'
+ *
+ * function LoginPage({ orgSlug }: { orgSlug: string }) {
+ *   const { tenantId, organizationId, organizationName, loading, error } = useTenantContext(orgSlug)
+ *   if (loading) return <LoadingMessage />
+ *   if (error) return <ErrorMessage error={error} />
+ *   // ...
+ * }
+ * ```
+ */
+export function useTenantContext(orgSlug: string): OrgContext {
+  const [state, setState] = useState<OrgContext>({
+    tenantId: undefined,
+    organizationId: undefined,
+    organizationName: undefined,
+    loading: true,
+    error: null,
+  })
+
+  useEffect(() => {
+    let cancelled = false
+
+    async function lookup() {
+      if (!orgSlug) {
+        setState((prev) => ({ ...prev, loading: false, error: 'No organization slug provided.' }))
+        return
+      }
+
+      try {
+        const { ok, result: data } = await apiCall<{ ok: boolean; organization: { id: string; tenantId: string; name: string }; error?: string }>(`/api/directory/organizations/lookup?slug=${encodeURIComponent(orgSlug)}`)
+        if (cancelled) return
+
+        if (!ok || !data?.ok || !data.organization) {
+          setState((prev) => ({
+            ...prev,
+            loading: false,
+            error: data?.error || 'Organization not found.',
+          }))
+          return
+        }
+
+        setState({
+          tenantId: data.organization.tenantId ?? undefined,
+          organizationId: data.organization.id,
+          organizationName: data.organization.name,
+          loading: false,
+          error: null,
+        })
+      } catch {
+        if (!cancelled) {
+          setState((prev) => ({ ...prev, loading: false, error: 'Failed to load organization.' }))
+        }
+      }
+    }
+
+    lookup()
+    return () => { cancelled = true }
+  }, [orgSlug])
+
+  return state
+}

package/src/primitives/DataLoader.tsx

@@ -0,0 +1,93 @@
+"use client"
+import * as React from 'react'
+import { Spinner } from './spinner'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+
+export interface DataLoaderProps {
+  isLoading: boolean
+  children: React.ReactNode
+  loadingMessage?: string
+  spinnerSize?: 'sm' | 'md' | 'lg'
+  className?: string
+  loadingClassName?: string
+  // Optional: show a skeleton or placeholder instead of just spinner
+  showSkeleton?: boolean
+  skeletonComponent?: React.ReactNode
+}
+
+export function DataLoader({
+  isLoading,
+  children,
+  loadingMessage,
+  spinnerSize = 'md',
+  className = '',
+  loadingClassName = '',
+  showSkeleton = false,
+  skeletonComponent
+}: DataLoaderProps) {
+  const t = useT()
+  const resolvedLoadingMessage = loadingMessage ?? t('ui.dataLoader.loading', 'Loading...')
+  if (isLoading) {
+    if (showSkeleton && skeletonComponent) {
+      return <div className={className}>{skeletonComponent}</div>
+    }
+
+    return (
+      <div className={`flex items-center justify-center gap-2 py-4 ${loadingClassName} ${className}`}>
+        <Spinner size={spinnerSize} />
+        <span className="text-sm text-muted-foreground">{resolvedLoadingMessage}</span>
+      </div>
+    )
+  }
+
+  return <div className={className}>{children}</div>
+}
+
+// Convenience component for inline loading states
+export function InlineLoader({
+  isLoading,
+  children,
+  loadingMessage,
+  spinnerSize = 'sm'
+}: {
+  isLoading: boolean
+  children: React.ReactNode
+  loadingMessage?: string
+  spinnerSize?: 'sm' | 'md' | 'lg'
+}) {
+  return (
+    <DataLoader
+      isLoading={isLoading}
+      loadingMessage={loadingMessage}
+      spinnerSize={spinnerSize}
+      className="inline-flex items-center"
+      loadingClassName="py-2"
+    >
+      {children}
+    </DataLoader>
+  )
+}
+
+// Convenience component for full-page loading states
+export function PageLoader({
+  isLoading,
+  children,
+  loadingMessage,
+  spinnerSize = 'lg'
+}: {
+  isLoading: boolean
+  children: React.ReactNode
+  loadingMessage?: string
+  spinnerSize?: 'sm' | 'md' | 'lg'
+}) {
+  return (
+    <DataLoader
+      isLoading={isLoading}
+      loadingMessage={loadingMessage}
+      spinnerSize={spinnerSize}
+      className="min-h-[200px] flex items-center justify-center"
+    >
+      {children}
+    </DataLoader>
+  )
+}

package/src/primitives/ErrorNotice.tsx

@@ -0,0 +1,17 @@
+"use client"
+import * as React from 'react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { Notice } from './Notice'
+
+export function ErrorNotice({ title, message, action }: {
+  title?: string
+  message?: string
+  action?: React.ReactNode
+}) {
+  const t = useT()
+  const defaultTitle = title ?? t('ui.errors.defaultTitle', 'Something went wrong')
+  const defaultMessage = message ?? t('ui.errors.defaultMessage', 'Unable to load data. Please try again.')
+  return (
+    <Notice variant="error" title={defaultTitle} message={defaultMessage} action={action} />
+  )
+}