@freighttech/ui 0.13.18

package/src/portal/components/PortalCard.tsx

@@ -0,0 +1,77 @@
+"use client"
+import type { ReactNode } from 'react'
+
+type PortalCardProps = {
+  children: ReactNode
+  className?: string
+}
+
+/**
+ * Portal-styled card container.
+ * Clean card with subtle border and minimal shadow, matching the
+ * Open Mercato design language.
+ */
+export function PortalCard({ children, className }: PortalCardProps) {
+  return (
+    <div className={`rounded-xl border bg-card p-5 sm:p-6 ${className ?? ''}`}>
+      {children}
+    </div>
+  )
+}
+
+type PortalCardHeaderProps = {
+  title: string
+  description?: string
+  label?: string
+  action?: ReactNode
+}
+
+/**
+ * Card header with optional uppercase label, title, description, and action slot.
+ * Matches the section label pattern from the landing page (small caps, muted).
+ */
+export function PortalCardHeader({ title, description, label, action }: PortalCardHeaderProps) {
+  return (
+    <div className="mb-4 flex items-start justify-between gap-4">
+      <div>
+        {label ? (
+          <p className="mb-1.5 text-[11px] font-medium uppercase tracking-widest text-muted-foreground/60">
+            {label}
+          </p>
+        ) : null}
+        <h3 className="text-base font-semibold tracking-tight">{title}</h3>
+        {description ? (
+          <p className="mt-0.5 text-sm text-muted-foreground">{description}</p>
+        ) : null}
+      </div>
+      {action ? <div className="shrink-0">{action}</div> : null}
+    </div>
+  )
+}
+
+type PortalStatRowProps = {
+  label: string
+  value: ReactNode
+}
+
+/**
+ * Key-value row for displaying stats/info inside a PortalCard.
+ * Uses the uppercase label style from the landing page's data fields.
+ */
+export function PortalStatRow({ label, value }: PortalStatRowProps) {
+  return (
+    <div className="flex items-center justify-between gap-4 py-2.5">
+      <span className="text-[11px] font-medium uppercase tracking-wider text-muted-foreground/70">
+        {label}
+      </span>
+      <span className="text-sm font-medium text-foreground">{value}</span>
+    </div>
+  )
+}
+
+/**
+ * Divider between stat rows.
+ */
+export function PortalCardDivider() {
+  return <div className="border-t" />
+}

package/src/portal/components/PortalEmptyState.tsx

@@ -0,0 +1,32 @@
+"use client"
+import type { ReactNode } from 'react'
+
+type PortalEmptyStateProps = {
+  icon?: ReactNode
+  title: string
+  description?: string
+  action?: ReactNode
+}
+
+/**
+ * Empty state placeholder for portal sections with no content.
+ * Dashed border, centered layout, optional icon and CTA.
+ */
+export function PortalEmptyState({ icon, title, description, action }: PortalEmptyStateProps) {
+  return (
+    <div className="flex flex-col items-center justify-center gap-3 rounded-xl border border-dashed py-12 text-center">
+      {icon ? (
+        <div className="flex size-10 items-center justify-center rounded-lg bg-muted text-muted-foreground">
+          {icon}
+        </div>
+      ) : null}
+      <div>
+        <p className="text-sm font-medium text-foreground">{title}</p>
+        {description ? (
+          <p className="mt-0.5 max-w-sm text-sm text-muted-foreground">{description}</p>
+        ) : null}
+      </div>
+      {action ?? null}
+    </div>
+  )
+}

package/src/portal/components/PortalFeatureCard.tsx

@@ -0,0 +1,41 @@
+"use client"
+import type { ReactNode } from 'react'
+
+type PortalFeatureCardProps = {
+  icon?: ReactNode
+  title: string
+  description?: string
+  href?: string
+  onClick?: () => void
+}
+
+/**
+ * Feature card matching the landing page's 3-column feature grid.
+ * Subtle border, icon block, title, and description.
+ * Can be a link or a static display card.
+ */
+export function PortalFeatureCard({ icon, title, description, href, onClick }: PortalFeatureCardProps) {
+  const content = (
+    <>
+      {icon ? (
+        <div className="mb-3 flex size-10 items-center justify-center rounded-lg border bg-background text-muted-foreground">
+          {icon}
+        </div>
+      ) : null}
+      <h3 className="text-sm font-semibold text-foreground">{title}</h3>
+      {description ? (
+        <p className="mt-1 text-sm leading-relaxed text-muted-foreground">{description}</p>
+      ) : null}
+    </>
+  )
+
+  const cls = 'flex flex-col rounded-xl border bg-card p-5 transition-colors hover:bg-accent/50'
+
+  if (href) {
+    return <a href={href} className={cls}>{content}</a>
+  }
+  if (onClick) {
+    return <button type="button" onClick={onClick} className={`${cls} text-left`}>{content}</button>
+  }
+  return <div className="flex flex-col rounded-xl border bg-card p-5">{content}</div>
+}

package/src/portal/components/PortalNotificationBell.tsx

@@ -0,0 +1,81 @@
+"use client"
+import * as React from 'react'
+import { IconButton } from '../../primitives/icon-button'
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+import { usePortalNotifications } from '../hooks/usePortalNotifications'
+import { PortalNotificationPanel } from './PortalNotificationPanel'
+
+function BellIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className={className}>
+      <path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9" /><path d="M10.3 21a1.94 1.94 0 0 0 3.4 0" />
+    </svg>
+  )
+}
+
+type PortalNotificationBellProps = {
+  t: TranslateFn
+}
+
+/**
+ * Portal notification bell icon with unread badge and slide-over panel.
+ * Renders in the portal header. Uses portal-specific notification endpoints.
+ */
+export function PortalNotificationBell({ t }: PortalNotificationBellProps) {
+  const [panelOpen, setPanelOpen] = React.useState(false)
+  const {
+    notifications,
+    unreadCount,
+    hasNew,
+    markAsRead,
+    dismiss,
+    markAllRead,
+  } = usePortalNotifications()
+
+  const [pulse, setPulse] = React.useState(false)
+  const prevCountRef = React.useRef(unreadCount)
+
+  React.useEffect(() => {
+    if (hasNew && unreadCount > prevCountRef.current) {
+      setPulse(true)
+      const timer = setTimeout(() => setPulse(false), 1200)
+      return () => clearTimeout(timer)
+    }
+    prevCountRef.current = unreadCount
+  }, [unreadCount, hasNew])
+
+  return (
+    <>
+      <IconButton
+        variant="ghost"
+        size="sm"
+        type="button"
+        className="relative"
+        onClick={() => setPanelOpen(true)}
+        aria-label={
+          unreadCount > 0
+            ? t('portal.notifications.badge', '{count} unread', { count: unreadCount })
+            : t('portal.notifications.title', 'Notifications')
+        }
+      >
+        <BellIcon className={`size-[18px] ${pulse ? 'animate-pulse' : ''}`} />
+        {unreadCount > 0 ? (
+          <span className="absolute -right-0.5 -top-0.5 flex size-4 items-center justify-center rounded-full bg-foreground text-[9px] font-bold text-background">
+            {unreadCount > 99 ? '99+' : unreadCount}
+          </span>
+        ) : null}
+      </IconButton>
+
+      <PortalNotificationPanel
+        open={panelOpen}
+        onClose={() => setPanelOpen(false)}
+        notifications={notifications}
+        unreadCount={unreadCount}
+        onMarkAsRead={markAsRead}
+        onDismiss={dismiss}
+        onMarkAllRead={markAllRead}
+        t={t}
+      />
+    </>
+  )
+}

package/src/portal/components/PortalNotificationPanel.tsx

@@ -0,0 +1,230 @@
+"use client"
+import * as React from 'react'
+import { Button } from '../../primitives/button'
+import { IconButton } from '../../primitives/icon-button'
+import type { NotificationDto } from '@open-mercato/shared/modules/notifications/types'
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+
+function XIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className={className}>
+      <path d="M18 6 6 18" /><path d="m6 6 12 12" />
+    </svg>
+  )
+}
+
+function CheckIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className={className}>
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  )
+}
+
+const SEVERITY_STYLES: Record<string, string> = {
+  info: 'bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400',
+  success: 'bg-emerald-100 text-emerald-700 dark:bg-emerald-900/30 dark:text-emerald-400',
+  warning: 'bg-amber-100 text-amber-700 dark:bg-amber-900/30 dark:text-amber-400',
+  error: 'bg-rose-100 text-rose-700 dark:bg-rose-900/30 dark:text-rose-400',
+}
+
+type Tab = 'all' | 'unread'
+
+type PortalNotificationPanelProps = {
+  open: boolean
+  onClose: () => void
+  notifications: NotificationDto[]
+  unreadCount: number
+  onMarkAsRead: (id: string) => Promise<void>
+  onDismiss: (id: string) => Promise<void>
+  onMarkAllRead: () => Promise<void>
+  t: TranslateFn
+}
+
+export function PortalNotificationPanel({
+  open,
+  onClose,
+  notifications,
+  unreadCount,
+  onMarkAsRead,
+  onDismiss,
+  onMarkAllRead,
+  t,
+}: PortalNotificationPanelProps) {
+  const [tab, setTab] = React.useState<Tab>('all')
+  const panelRef = React.useRef<HTMLDivElement>(null)
+
+  // Close on Escape
+  React.useEffect(() => {
+    if (!open) return
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [open, onClose])
+
+  if (!open) return null
+
+  const filtered = tab === 'unread'
+    ? notifications.filter((n) => n.status === 'unread')
+    : notifications
+
+  const formatTime = (iso: string) => {
+    const diff = Date.now() - new Date(iso).getTime()
+    const mins = Math.floor(diff / 60000)
+    if (mins < 1) return t('portal.notifications.justNow', 'Just now')
+    if (mins < 60) return t('portal.notifications.minutesAgo', '{m}m ago', { m: mins })
+    const hours = Math.floor(mins / 60)
+    if (hours < 24) return t('portal.notifications.hoursAgo', '{h}h ago', { h: hours })
+    const days = Math.floor(hours / 24)
+    return t('portal.notifications.daysAgo', '{d}d ago', { d: days })
+  }
+
+  return (
+    <>
+      {/* Backdrop */}
+      <div className="fixed inset-0 z-50 bg-black/20 backdrop-blur-sm" onClick={onClose} />
+
+      {/* Panel */}
+      <div
+        ref={panelRef}
+        className="fixed right-0 top-0 z-50 flex h-full w-full max-w-md flex-col border-l bg-background shadow-2xl"
+      >
+        {/* Header */}
+        <div className="flex h-16 items-center justify-between border-b px-5">
+          <div>
+            <h2 className="text-[15px] font-semibold">{t('portal.notifications.title', 'Notifications')}</h2>
+            {unreadCount > 0 ? (
+              <p className="text-[11px] text-muted-foreground">
+                {t('portal.notifications.unreadSummary', '{count} unread', { count: unreadCount })}
+              </p>
+            ) : null}
+          </div>
+          <div className="flex items-center gap-1">
+            {unreadCount > 0 ? (
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                className="text-[12px] text-muted-foreground"
+                onClick={() => onMarkAllRead()}
+              >
+                <CheckIcon className="mr-1 size-3.5" />
+                {t('portal.notifications.markAllRead', 'Mark all read')}
+              </Button>
+            ) : null}
+            <IconButton variant="ghost" size="sm" type="button" onClick={onClose} aria-label="Close">
+              <XIcon className="size-4" />
+            </IconButton>
+          </div>
+        </div>
+
+        {/* Tabs */}
+        <div className="flex gap-0 border-b px-5">
+          {(['all', 'unread'] as Tab[]).map((tabId) => (
+            <button
+              key={tabId}
+              type="button"
+              onClick={() => setTab(tabId)}
+              className={`border-b-2 px-3 py-2.5 text-[13px] font-medium transition-colors ${
+                tab === tabId
+                  ? 'border-foreground text-foreground'
+                  : 'border-transparent text-muted-foreground hover:text-foreground'
+              }`}
+            >
+              {tabId === 'all'
+                ? t('portal.notifications.tab.all', 'All')
+                : t('portal.notifications.tab.unread', 'Unread')}
+              {tabId === 'unread' && unreadCount > 0 ? (
+                <span className="ml-1.5 inline-flex size-5 items-center justify-center rounded-full bg-foreground text-[10px] font-bold text-background">
+                  {unreadCount}
+                </span>
+              ) : null}
+            </button>
+          ))}
+        </div>
+
+        {/* List */}
+        <div className="flex-1 overflow-y-auto">
+          {filtered.length === 0 ? (
+            <div className="flex flex-col items-center justify-center gap-2 py-16 text-center">
+              <p className="text-sm font-medium text-muted-foreground">
+                {tab === 'unread'
+                  ? t('portal.notifications.emptyUnread', 'All caught up!')
+                  : t('portal.notifications.empty', 'No notifications yet')}
+              </p>
+            </div>
+          ) : (
+            filtered.map((notification) => (
+              <div
+                key={notification.id}
+                className={`flex gap-3 border-b px-5 py-4 transition-colors ${
+                  notification.status === 'unread' ? 'bg-muted/30' : ''
+                }`}
+              >
+                {/* Severity dot */}
+                <div className={`mt-1 flex size-8 shrink-0 items-center justify-center rounded-lg text-[10px] font-bold ${SEVERITY_STYLES[notification.severity] ?? SEVERITY_STYLES.info}`}>
+                  {notification.severity.charAt(0).toUpperCase()}
+                </div>
+
+                {/* Content */}
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-start justify-between gap-2">
+                    <p className="text-[13px] font-medium leading-snug">
+                      {notification.title}
+                    </p>
+                    <span className="shrink-0 text-[11px] text-muted-foreground/60">
+                      {formatTime(notification.createdAt)}
+                    </span>
+                  </div>
+                  {notification.body ? (
+                    <p className="mt-0.5 text-[12px] leading-relaxed text-muted-foreground">
+                      {notification.body}
+                    </p>
+                  ) : null}
+
+                  {/* Actions */}
+                  <div className="mt-2 flex items-center gap-2">
+                    {notification.status === 'unread' ? (
+                      <Button
+                        type="button"
+                        variant="ghost"
+                        size="sm"
+                        className="h-auto px-2 py-1 text-[11px] text-muted-foreground"
+                        onClick={() => onMarkAsRead(notification.id)}
+                      >
+                        {t('portal.notifications.markRead', 'Mark read')}
+                      </Button>
+                    ) : null}
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      className="h-auto px-2 py-1 text-[11px] text-muted-foreground"
+                      onClick={() => onDismiss(notification.id)}
+                    >
+                      {t('portal.notifications.dismiss', 'Dismiss')}
+                    </Button>
+                    {notification.linkHref ? (
+                      <a
+                        href={notification.linkHref}
+                        className="ml-auto text-[11px] font-medium text-foreground underline underline-offset-2 hover:opacity-80"
+                        onClick={() => {
+                          if (notification.status === 'unread') onMarkAsRead(notification.id)
+                          onClose()
+                        }}
+                      >
+                        {t('portal.notifications.view', 'View')}
+                      </a>
+                    ) : null}
+                  </div>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </>
+  )
+}

package/src/portal/components/PortalPageHeader.tsx

@@ -0,0 +1,33 @@
+"use client"
+import type { ReactNode } from 'react'
+
+type PortalPageHeaderProps = {
+  title: string
+  description?: string
+  label?: string
+  action?: ReactNode
+}
+
+/**
+ * Portal page header with large title and optional action slot.
+ * Matches the landing page's hero section typography — large,
+ * tight tracking, with muted description.
+ */
+export function PortalPageHeader({ title, description, label, action }: PortalPageHeaderProps) {
+  return (
+    <div className="flex flex-col gap-1 sm:flex-row sm:items-center sm:justify-between sm:gap-4">
+      <div>
+        {label ? (
+          <p className="mb-1 text-[11px] font-medium uppercase tracking-widest text-muted-foreground/60">
+            {label}
+          </p>
+        ) : null}
+        <h1 className="text-2xl font-bold tracking-tight sm:text-3xl">{title}</h1>
+        {description ? (
+          <p className="mt-1 text-sm text-muted-foreground sm:text-base">{description}</p>
+        ) : null}
+      </div>
+      {action ? <div className="mt-3 shrink-0 sm:mt-0">{action}</div> : null}
+    </div>
+  )
+}

package/src/portal/components/index.ts

@@ -0,0 +1,6 @@
+export { PortalCard, PortalCardHeader, PortalStatRow, PortalCardDivider } from './PortalCard'
+export { PortalPageHeader } from './PortalPageHeader'
+export { PortalEmptyState } from './PortalEmptyState'
+export { PortalFeatureCard } from './PortalFeatureCard'
+export { PortalNotificationBell } from './PortalNotificationBell'
+export { PortalNotificationPanel } from './PortalNotificationPanel'

package/src/portal/hooks/useCustomerAuth.ts

@@ -0,0 +1,97 @@
+"use client"
+import { useCallback, useEffect, useState } from 'react'
+import { useRouter } from 'next/navigation'
+import type { CustomerUser, CustomerRole, CustomerAuthResult } from '@open-mercato/shared/modules/customer-auth'
+import { apiCall } from '../../backend/utils/apiCall'
+
+export type { CustomerUser, CustomerRole, CustomerAuthResult }
+
+/**
+ * Client-side hook for customer portal authentication.
+ *
+ * Fetches the authenticated customer profile from `/api/customer_accounts/portal/profile`
+ * and provides auth state + logout capability.
+ *
+ * @param orgSlug - Optional organization slug for redirect paths
+ *
+ * @example
+ * ```tsx
+ * import { useCustomerAuth } from '@freighttech/ui/portal/hooks/useCustomerAuth'
+ *
+ * function MyPortalPage({ orgSlug }: { orgSlug: string }) {
+ *   const { user, roles, resolvedFeatures, loading, logout } = useCustomerAuth(orgSlug)
+ *   if (loading) return <LoadingMessage />
+ *   if (!user) return <Redirect to={`/${orgSlug}/portal/login`} />
+ *   return <div>Welcome, {user.displayName}</div>
+ * }
+ * ```
+ */
+export function useCustomerAuth(orgSlug?: string) {
+  const router = useRouter()
+  const [state, setState] = useState<CustomerAuthResult>({
+    user: null,
+    roles: [],
+    resolvedFeatures: [],
+    isPortalAdmin: false,
+    loading: true,
+    error: null,
+  })
+
+  useEffect(() => {
+    let cancelled = false
+
+    async function fetchProfile() {
+      try {
+        const { ok, status, result: data } = await apiCall<{ ok: boolean; user: CustomerAuthResult['user']; roles: CustomerAuthResult['roles']; resolvedFeatures: string[]; isPortalAdmin: boolean; error?: string }>('/api/customer_accounts/portal/profile')
+        if (cancelled) return
+
+        if (status === 401) {
+          setState((prev) => ({ ...prev, loading: false, user: null }))
+          return
+        }
+
+        if (!ok || !data?.ok) {
+          setState((prev) => ({ ...prev, loading: false, error: data?.error || `HTTP ${status}` }))
+          return
+        }
+
+        setState({
+          user: data.user,
+          roles: data.roles || [],
+          resolvedFeatures: data.resolvedFeatures || [],
+          isPortalAdmin: data.isPortalAdmin || false,
+          loading: false,
+          error: null,
+        })
+      } catch {
+        if (!cancelled) {
+          setState((prev) => ({ ...prev, loading: false, error: 'Network error' }))
+        }
+      }
+    }
+
+    fetchProfile()
+    return () => { cancelled = true }
+  }, [])
+
+  const loginPath = orgSlug ? `/${orgSlug}/portal/login` : '/portal/login'
+
+  const logout = useCallback(async () => {
+    try {
+      await apiCall('/api/customer_accounts/portal/logout', { method: 'POST' })
+    } catch {
+      // Best-effort logout — redirect regardless
+    }
+    setState({
+      user: null,
+      roles: [],
+      resolvedFeatures: [],
+      isPortalAdmin: false,
+      loading: false,
+      error: null,
+    })
+    router.push(loginPath)
+  }, [router, loginPath])
+
+  return { ...state, logout }
+}

package/src/portal/hooks/usePortalAppEvent.ts

@@ -0,0 +1,56 @@
+"use client"
+import { useEffect, useRef } from 'react'
+import type { AppEventPayload } from '@open-mercato/shared/modules/widgets/injection'
+import { matchesPattern } from '../../backend/injection/useAppEvent'
+
+/**
+ * DOM Event name for portal events.
+ * Portal server-side events with `portalBroadcast: true` are dispatched as
+ * CustomEvents with this name on the window object.
+ */
+export const PORTAL_EVENT_DOM_NAME = 'om:portal-event'
+
+/**
+ * React hook that listens for portal app events delivered via the Portal Event Bridge.
+ *
+ * Events are dispatched as `om:portal-event` CustomEvents on `window` by the portal
+ * event bridge (see `usePortalEventBridge.ts`). This hook filters events by pattern
+ * and calls the handler.
+ *
+ * @param eventPattern - Pattern to match event IDs against (e.g., 'sales.order.*')
+ * @param handler - Callback invoked when a matching event arrives
+ * @param deps - Optional dependency array for the handler (defaults to [])
+ *
+ * @example
+ * ```tsx
+ * import { usePortalAppEvent } from '@freighttech/ui/portal/hooks/usePortalAppEvent'
+ *
+ * usePortalAppEvent('sales.order.status_changed', (event) => {
+ *   refetch() // Refresh order list
+ * })
+ * ```
+ */
+export function usePortalAppEvent(
+  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(PORTAL_EVENT_DOM_NAME, listener)
+    return () => {
+      window.removeEventListener(PORTAL_EVENT_DOM_NAME, listener)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [eventPattern, ...deps])
+}