@l.x/notifications 1.0.3 → 1.0.4

package/src/notification-processor/implementations/createBaseNotificationProcessor.ts

@@ -0,0 +1,254 @@
+import { ContentStyle, type InAppNotification, OnClickAction } from '@l.x/api'
+import { createNotificationProcessor } from '@l.x/notifications/src/notification-processor/implementations/createNotificationProcessor'
+import {
+  type NotificationProcessor,
+  type NotificationProcessorResult,
+} from '@l.x/notifications/src/notification-processor/NotificationProcessor'
+import { type NotificationTracker } from '@l.x/notifications/src/notification-tracker/NotificationTracker'
+import { getLogger } from 'utilities/src/logger/logger'
+
+/**
+ * Creates a base notification processor that implements style-based deduplication and limiting,
+ * as well as separating primary and chained notifications using topological sorting.
+ *
+ * Processing rules:
+ * 1. Builds a dependency graph of notifications based on POPUP actions
+ * 2. Uses topological sort to identify root notifications (those with no incoming edges)
+ * 3. Filters out notifications that have already been processed (tracked)
+ * 4. Limits the number of primary notifications per content style (LOWER_LEFT_BANNER: 3, others: 1)
+ * 5. Returns primary notifications for immediate rendering and chained notifications for later
+ *
+ * This properly handles notification chains of any length (A → B → C → D → ...).
+ *
+ * @param tracker - The NotificationTracker to check which notifications have been processed
+ * @returns A NotificationProcessor that applies these rules
+ */
+export function createBaseNotificationProcessor(tracker: NotificationTracker): NotificationProcessor {
+  return createNotificationProcessor({
+    process: async (notifications: InAppNotification[]): Promise<NotificationProcessorResult> => {
+      const processedIds = await tracker.getProcessedIds()
+
+      // Step 1: Build dependency graph and identify roots using topological analysis
+      const { roots, nonRoots } = identifyRootsAndChained(notifications)
+
+      // Step 2: Separate primary (roots) and chained (non-roots) notifications
+      const primaryNotifications: InAppNotification[] = []
+      const chainedNotifications: InAppNotification[] = []
+
+      for (const notification of notifications) {
+        if (roots.has(notification.id)) {
+          primaryNotifications.push(notification)
+        } else if (nonRoots.has(notification.id)) {
+          chainedNotifications.push(notification)
+        }
+      }
+
+      // Step 3: Filter out notifications that are locally tracked or don't have DISMISS action.
+      // Required cards are exempt from the DISMISS check — they self-dismiss when their
+      // underlying data condition resolves (e.g. wallet receives funds).
+      const filteredPrimary = primaryNotifications.filter((notification) => {
+        if (processedIds.has(notification.id)) {
+          return false
+        }
+        if (!isRequiredCard(notification) && !hasDismissAction(notification)) {
+          getLogger().warn(
+            'createBaseNotificationProcessor',
+            'process',
+            `Filtering out notification ${notification.id} - no DISMISS action found in any click configuration`,
+            { notification },
+          )
+          return false
+        }
+        return true
+      })
+
+      const filteredChained = chainedNotifications.filter((notification) => {
+        if (processedIds.has(notification.id)) {
+          return false
+        }
+        if (!isRequiredCard(notification) && !hasDismissAction(notification)) {
+          getLogger().warn(
+            'createBaseNotificationProcessor',
+            'process',
+            `Filtering out notification ${notification.id} - no DISMISS action found in any click configuration`,
+            { notification },
+          )
+          return false
+        }
+        return true
+      })
+
+      // Step 4: Limit the number of primary notifications per content style
+      const limitedPrimary = limitNotifications(filteredPrimary)
+
+      // Step 5: Convert chained notifications to a Map for fast lookup
+      const chainedMap = new Map<string, InAppNotification>()
+      for (const notification of filteredChained) {
+        chainedMap.set(notification.id, notification)
+      }
+
+      return {
+        primary: limitedPrimary,
+        chained: chainedMap,
+      }
+    },
+  })
+}
+
+/**
+ * Returns true if the notification is a required card — one that self-dismisses when its
+ * underlying data condition resolves rather than via explicit user action.
+ */
+function isRequiredCard(notification: InAppNotification): boolean {
+  try {
+    const extra = notification.content?.extra ? JSON.parse(notification.content.extra) : {}
+    return extra.cardType === 'required'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Checks if a notification has at least one DISMISS action in any of its click configurations.
+ * Every notification must have a way to be dismissed.
+ */
+function hasDismissAction(notification: InAppNotification): boolean {
+  // Check all buttons for DISMISS action
+  const buttons = notification.content?.buttons ?? []
+  for (const button of buttons) {
+    if (button.onClick?.onClick.includes(OnClickAction.DISMISS)) {
+      return true
+    }
+  }
+
+  // Check background click for DISMISS action
+  const backgroundOnClick = notification.content?.background?.backgroundOnClick
+  if (backgroundOnClick?.onClick.includes(OnClickAction.DISMISS)) {
+    return true
+  }
+
+  // Check onDismissClick for DISMISS action (close button)
+  const onDismissClick = notification.content?.onDismissClick
+  if (onDismissClick?.onClick.includes(OnClickAction.DISMISS)) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Identifies root notifications and chained notifications using graph analysis.
+ *
+ * Builds a dependency graph where:
+ * - Nodes are notifications
+ * - Edges represent POPUP actions (A → B means A has a button/background that pops up B)
+ *
+ * Root notifications are those with no incoming edges (not referenced by any POPUP action).
+ * Chained notifications are those with at least one incoming edge.
+ *
+ * This properly handles chains of any length: A → B → C → D
+ * - A is a root (no incoming edges)
+ * - B, C, D are chained (have incoming edges)
+ *
+ * @returns Object with two sets: roots (primary notifications) and nonRoots (chained notifications)
+ */
+function identifyRootsAndChained(notifications: InAppNotification[]): { roots: Set<string>; nonRoots: Set<string> } {
+  const allIds = new Set<string>(notifications.map((n) => n.id))
+  const hasIncomingEdge = new Set<string>()
+
+  for (const notification of notifications) {
+    const popupTargets = extractPopupTargets(notification)
+
+    for (const targetId of popupTargets) {
+      if (allIds.has(targetId)) {
+        hasIncomingEdge.add(targetId)
+      }
+    }
+  }
+
+  const roots = new Set<string>()
+  const nonRoots = new Set<string>()
+
+  for (const notification of notifications) {
+    if (hasIncomingEdge.has(notification.id)) {
+      nonRoots.add(notification.id)
+    } else {
+      roots.add(notification.id)
+    }
+  }
+
+  return { roots, nonRoots }
+}
+
+/**
+ * Extracts all notification IDs that are targeted by POPUP actions in this notification.
+ * Checks both button clicks and background clicks.
+ */
+function extractPopupTargets(notification: InAppNotification): string[] {
+  const targets: string[] = []
+
+  const buttons = notification.content?.buttons ?? []
+  for (const button of buttons) {
+    const target = getPopupTarget(button.onClick)
+    if (target) {
+      targets.push(target)
+    }
+  }
+
+  const backgroundTarget = getPopupTarget(notification.content?.background?.backgroundOnClick)
+  if (backgroundTarget) {
+    targets.push(backgroundTarget)
+  }
+
+  return targets
+}
+
+/**
+ * Gets the target notification ID if this onClick action includes POPUP.
+ */
+function getPopupTarget(onClick: { onClick: OnClickAction[]; onClickLink?: string } | undefined): string | undefined {
+  if (!onClick?.onClick.includes(OnClickAction.POPUP)) {
+    return undefined
+  }
+  return onClick.onClickLink
+}
+
+/**
+ * Limits the number of notifications per content style.
+ * - LOWER_LEFT_BANNER: up to 3 notifications
+ * - SYSTEM_BANNER: 1 notification (sticky system alerts)
+ * - All other styles: 1 notification each
+ */
+function limitNotifications(notifications: InAppNotification[]): InAppNotification[] {
+  const groupedByStyle = new Map<number, InAppNotification[]>()
+
+  for (const notification of notifications) {
+    const style = notification.content?.style ?? ContentStyle.UNSPECIFIED
+    const group = groupedByStyle.get(style) ?? []
+    group.push(notification)
+    groupedByStyle.set(style, group)
+  }
+
+  const limited: InAppNotification[] = []
+
+  for (const [style, group] of groupedByStyle.entries()) {
+    const limit = getStyleLimit(style)
+    limited.push(...group.slice(0, limit))
+  }
+
+  return limited
+}
+
+/**
+ * Returns the maximum number of concurrent notifications for a given content style.
+ */
+function getStyleLimit(style: number): number {
+  if (style === ContentStyle.LOWER_LEFT_BANNER) {
+    return 3
+  }
+  if (style === ContentStyle.SYSTEM_BANNER) {
+    return 1
+  }
+  // Default: 1 for MODAL, UNSPECIFIED, and any future styles
+  return 1
+}

package/src/notification-processor/implementations/createNotificationProcessor.test.ts

@@ -0,0 +1,130 @@
+import type { InAppNotification } from '@l.x/api'
+import { createNotificationProcessor } from '@l.x/notifications/src/notification-processor/implementations/createNotificationProcessor'
+import { describe, expect, it, vi } from 'vitest'
+
+describe('createNotificationProcessor', () => {
+  it('creates a notification processor with process method', () => {
+    const mockProcess = vi.fn()
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    expect(processor).toBeDefined()
+    expect(typeof processor.process).toBe('function')
+  })
+
+  it('delegates process call to injected process function', async () => {
+    const mockNotifications: InAppNotification[] = [
+      {
+        id: 'test-notif-1-id',
+        metaData: {},
+        notificationName: 'test-notif-1',
+        timestamp: 1000,
+        content: { style: 'CONTENT_STYLE_MODAL', title: 'test-notif-1-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+    const mockResult: InAppNotification[] = [
+      {
+        id: 'result-notif-id',
+        metaData: {},
+        notificationName: 'result-notif',
+        timestamp: 2000,
+        content: { style: 'CONTENT_STYLE_MODAL', title: 'result-notif-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+
+    const mockProcess = vi.fn().mockResolvedValue(mockResult)
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    const result = await processor.process(mockNotifications)
+
+    expect(mockProcess).toHaveBeenCalledWith(mockNotifications)
+    expect(result).toBe(mockResult)
+  })
+
+  it('preserves the exact arguments passed to process method', async () => {
+    const notifications: InAppNotification[] = [
+      {
+        id: 'notif-1-id',
+        metaData: {},
+        notificationName: 'notif-1',
+        timestamp: 1000,
+        content: { style: 'CONTENT_STYLE_MODAL', title: 'notif-1-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+      {
+        id: 'notif-2-id',
+        metaData: {},
+        notificationName: 'notif-2',
+        timestamp: 2000,
+        content: { style: 'CONTENT_STYLE_BANNER', title: 'notif-2-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+
+    let capturedNotifications: InAppNotification[] | undefined
+
+    const mockProcess = vi.fn(async (notifs) => {
+      capturedNotifications = notifs
+      return []
+    })
+
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    await processor.process(notifications)
+
+    expect(capturedNotifications).toBe(notifications)
+  })
+
+  it('returns empty array when injected process returns empty array', async () => {
+    const mockProcess = vi.fn().mockResolvedValue([])
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    const result = await processor.process([])
+
+    expect(result).toEqual([])
+  })
+
+  it('handles multiple calls with different arguments', async () => {
+    const mockProcess = vi.fn(async (notifications) => notifications)
+    const processor = createNotificationProcessor({
+      process: mockProcess,
+    })
+
+    const notifs1: InAppNotification[] = [
+      {
+        id: 'notif-1-id',
+        metaData: {},
+        notificationName: 'notif-1',
+        timestamp: 1000,
+        content: { style: 'CONTENT_STYLE_MODAL', title: 'notif-1-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+    const notifs2: InAppNotification[] = [
+      {
+        id: 'notif-2-id',
+        metaData: {},
+        notificationName: 'notif-2',
+        timestamp: 2000,
+        content: { style: 'CONTENT_STYLE_BANNER', title: 'notif-2-title' },
+        userId: 'user-1',
+      } as InAppNotification,
+    ]
+
+    const result1 = await processor.process(notifs1)
+    const result2 = await processor.process(notifs2)
+
+    expect(mockProcess).toHaveBeenCalledTimes(2)
+    expect(result1).toEqual(notifs1)
+    expect(result2).toEqual(notifs2)
+  })
+})

package/src/notification-processor/implementations/createNotificationProcessor.ts

@@ -0,0 +1,15 @@
+import { type InAppNotification } from '@l.x/api'
+import {
+  type NotificationProcessor,
+  type NotificationProcessorResult,
+} from '@l.x/notifications/src/notification-processor/NotificationProcessor'
+
+export function createNotificationProcessor(ctx: {
+  process: (notifications: InAppNotification[]) => Promise<NotificationProcessorResult>
+}): NotificationProcessor {
+  return {
+    process: async (notifications: InAppNotification[]): Promise<NotificationProcessorResult> => {
+      return ctx.process(notifications)
+    },
+  }
+}

package/src/notification-renderer/NotificationRenderer.ts

@@ -0,0 +1,8 @@
+import { type InAppNotification } from '@l.x/api'
+
+export interface NotificationRenderer {
+  // Render a notification and return cleanup function
+  render(notification: InAppNotification): () => void
+  // Check if a notification type can be rendered (e.g., only one modal at a time)
+  canRender(notification: InAppNotification): boolean
+}

package/src/notification-renderer/components/BannerTemplate.tsx

@@ -0,0 +1,188 @@
+import { ReactNode } from 'react'
+import { Button, Flex, IconButton, styled, Text, useIsDarkMode } from 'ui/src'
+import { X } from 'ui/src/components/icons/X'
+import { zIndexes } from 'ui/src/theme'
+
+const BANNER_WIDTH = 260
+const BANNER_HEIGHT = 150
+const GRADIENT_BACKGROUND_HEIGHT = 64 // Vertical midpoint of the thumbnail
+const ICON_SIZE = 40
+
+const BannerContainer = styled(Flex, {
+  borderRadius: '$rounded16',
+  minHeight: BANNER_HEIGHT,
+  shadowColor: '$shadowColor',
+  shadowOffset: { width: 0, height: 4 },
+  shadowOpacity: 0.4,
+  shadowRadius: 10,
+  overflow: 'hidden',
+  padding: '$spacing16',
+  backgroundColor: '$surface1',
+  borderWidth: 1,
+  borderColor: '$surface3',
+  variants: {
+    clickable: {
+      true: {
+        cursor: 'pointer',
+      },
+      false: {
+        cursor: 'default',
+      },
+    },
+  } as const,
+})
+
+const GradientBackground = styled(Flex, {
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  right: 0,
+  width: '100%',
+  height: GRADIENT_BACKGROUND_HEIGHT,
+  backgroundSize: 'cover',
+  backgroundPosition: 'center',
+  backgroundRepeat: 'no-repeat',
+  mask: 'linear-gradient(180deg, rgba(0,0,0,0.48) 0%, rgba(0,0,0,0) 100%)',
+})
+
+const IconContainer = styled(Flex, {
+  width: ICON_SIZE,
+  height: ICON_SIZE,
+  backgroundSize: 'cover',
+  backgroundPosition: 'center',
+  backgroundRepeat: 'no-repeat',
+  borderRadius: '$rounded6',
+})
+
+const ContentWrapper = styled(Flex, {
+  flex: 1,
+  justifyContent: 'space-between',
+  paddingTop: 16,
+})
+
+function BannerXButton({ handleClose }: { handleClose: () => void }): JSX.Element {
+  return (
+    <Flex row centered position="absolute" right={8} top={8} zIndex={zIndexes.mask}>
+      <IconButton
+        size="xxsmall"
+        emphasis="secondary"
+        icon={<X />}
+        onPress={(e) => {
+          e.stopPropagation()
+          handleClose()
+        }}
+      />
+    </Flex>
+  )
+}
+
+export interface BannerTemplateButton {
+  text: string
+  onPress: () => void
+  isPrimary?: boolean
+}
+
+interface BannerTemplateProps {
+  backgroundImageUrl?: string
+  /** Optional dark mode variant for backgroundImageUrl. Falls back to backgroundImageUrl if not provided. */
+  darkModeBackgroundImageUrl?: string
+  /** Pre-rendered icon element. When provided, takes priority over iconUrl. */
+  icon?: ReactNode
+  iconUrl?: string
+  /** Optional dark mode variant for iconUrl. Falls back to iconUrl if not provided. */
+  darkModeIconUrl?: string
+  title: string
+  subtitle?: string
+  onClose: () => void
+  onPress?: () => void
+  children?: ReactNode
+  /** Override the default banner width. Use '100%' for full-width. */
+  width?: number | string
+  /** Optional button to display below the content */
+  button?: BannerTemplateButton
+}
+
+/**
+ * BannerTemplate component
+ *
+ * A reusable template for rendering lower-banner notifications.
+ * Extracted from SolanaPromoBanner to be shared across the notification system.
+ *
+ * Features:
+ * - Fixed position in lower-left corner
+ * - Optional background image with gradient overlay
+ * - Optional icon
+ * - Title and subtitle text (or custom children)
+ * - Dismiss button
+ * - Click handler support
+ */
+export function BannerTemplate({
+  backgroundImageUrl,
+  darkModeBackgroundImageUrl,
+  icon,
+  iconUrl,
+  darkModeIconUrl,
+  title,
+  subtitle,
+  onClose,
+  onPress,
+  children,
+  width,
+  button,
+}: BannerTemplateProps): JSX.Element {
+  const isDarkMode = useIsDarkMode()
+  const effectiveBackgroundUrl =
+    isDarkMode && darkModeBackgroundImageUrl ? darkModeBackgroundImageUrl : backgroundImageUrl
+  const effectiveIconUrl = isDarkMode && darkModeIconUrl ? darkModeIconUrl : iconUrl
+
+  return (
+    <BannerContainer pointerEvents="auto" width={width ?? BANNER_WIDTH} clickable={!!onPress} onPress={onPress}>
+      <BannerXButton handleClose={onClose} />
+
+      {effectiveBackgroundUrl && <GradientBackground backgroundImage={`url(${effectiveBackgroundUrl})`} />}
+
+      <ContentWrapper>
+        <Flex gap="$spacing8">
+          {icon ? (
+            <Flex centered width={ICON_SIZE} height={ICON_SIZE}>
+              {icon}
+            </Flex>
+          ) : effectiveIconUrl ? (
+            <IconContainer backgroundImage={`url(${effectiveIconUrl})`} />
+          ) : (
+            <Flex width={ICON_SIZE} height={ICON_SIZE} backgroundColor="transparent" />
+          )}
+
+          {children || (
+            <Flex gap="$spacing4">
+              <Text variant="body3" color="$neutral1">
+                {title}
+              </Text>
+              {subtitle && (
+                <Text variant="body4" color="$neutral2">
+                  {subtitle}
+                </Text>
+              )}
+            </Flex>
+          )}
+        </Flex>
+
+        {button && (
+          <Flex marginTop="$spacing12">
+            <Button
+              size="medium"
+              emphasis={button.isPrimary ? 'primary' : 'secondary'}
+              minHeight="$spacing36"
+              onPress={(e) => {
+                e.stopPropagation()
+                button.onPress()
+              }}
+            >
+              {button.text}
+            </Button>
+          </Flex>
+        )}
+      </ContentWrapper>
+    </BannerContainer>
+  )
+}