@open-mercato/ui 0.6.5-develop.5382.1.f542de69af → 0.6.5

package/src/backend/__tests__/AppShell.test.tsx

@@ -19,7 +19,13 @@ jest.mock('next/link', () => {
   ))
 })
 
-jest.mock('next/image', () => (props: any) => <img alt={props.alt} {...props} />)
+jest.mock('next/image', () => {
+  const React = require('react')
+  return (props: any) => {
+    const { unoptimized, ...rest } = props
+    return <img alt={rest.alt} data-unoptimized={unoptimized ? 'true' : 'false'} {...rest} />
+  }
+})
 
 jest.mock('next/navigation', () => ({
   usePathname: () => mockPathname,
@@ -201,6 +207,60 @@ describe('AppShell', () => {
     )
   })
 
+  it('uses backend chrome brand logo when the selected organization has one', async () => {
+    const previousFetch = global.fetch
+    const previousWindowFetch = window.fetch
+    const previousOriginalFetch = (window as Window & { __omOriginalFetch?: typeof fetch }).__omOriginalFetch
+    const fetchMock = jest.fn().mockResolvedValue(
+      new Response(JSON.stringify({
+        brand: {
+          name: 'Acme',
+          logo: {
+            src: '/api/attachments/image/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/acme.png?width=320',
+            alt: 'Acme logo',
+          },
+        },
+        groups,
+        settingsSections: [],
+        settingsPathPrefixes: [],
+        profileSections: [],
+        profilePathPrefixes: [],
+        grantedFeatures: [],
+        roles: [],
+      }), { status: 200, headers: { 'content-type': 'application/json' } }),
+    ) as typeof fetch
+    global.fetch = fetchMock
+    window.fetch = fetchMock
+    ;(window as Window & { __omOriginalFetch?: typeof fetch }).__omOriginalFetch = fetchMock
+
+    try {
+      renderWithProviders(
+        <AppShell
+          email="demo@example.com"
+          groups={[]}
+          adminNavApi="/api/auth/admin/nav-brand-logo"
+        >
+          <div>Child content</div>
+        </AppShell>,
+        { dict },
+      )
+
+      await waitFor(() => {
+        const logo = screen.getByAltText('Acme logo')
+        expect(logo).toHaveAttribute(
+          'src',
+          '/api/attachments/image/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/acme.png?width=320',
+        )
+        expect(logo).toHaveAttribute('data-unoptimized', 'true')
+      })
+      expect(screen.getByText('Acme')).toBeInTheDocument()
+    } finally {
+      global.fetch = previousFetch
+      window.fetch = previousWindowFetch
+      ;(window as Window & { __omOriginalFetch?: typeof fetch }).__omOriginalFetch = previousOriginalFetch
+    }
+  })
+
   it('renders nested settings links when settings parent route is active', async () => {
     mockPathname = '/backend/entities/user'
 

package/src/backend/__tests__/DataTable.stickyResponsive.test.tsx

@@ -0,0 +1,99 @@
+/** @jest-environment jsdom */
+import * as React from 'react'
+import { DataTable } from '../DataTable'
+import type { ColumnDef } from '@tanstack/react-table'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
+import { render } from '@testing-library/react'
+import { RowActions } from '../RowActions'
+
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push: jest.fn(), replace: jest.fn(), prefetch: jest.fn() }),
+}))
+
+jest.mock('../injection/useInjectionDataWidgets', () => ({
+  useInjectionDataWidgets: () => ({ widgets: [], isLoading: false }),
+}))
+
+type Row = { id: string; title: string; status: string }
+
+const tokensOf = (el: Element | null): string[] =>
+  (el?.getAttribute('class') ?? '').split(/\s+/).filter(Boolean)
+
+// Pinned columns must never consume the viewport on phones: an unconditionally
+// `sticky` first column (often ~300px wide) plus a sticky actions column can
+// exceed a small screen entirely, leaving the middle columns scrolling
+// invisibly underneath with no reachable window. Pinning (position, offsets,
+// z-index, opaque background, edge shadows) must therefore apply only from the
+// `md` breakpoint up, so narrow viewports fall back to the documented plain
+// horizontal-scroll behavior where every column can be swiped into view.
+describe('DataTable sticky columns are viewport-gated', () => {
+  function renderStickyTable() {
+    const columns: ColumnDef<Row>[] = [
+      { accessorKey: 'title', header: 'Title' },
+      { accessorKey: 'status', header: 'Status' },
+    ]
+    const queryClient = new QueryClient({ defaultOptions: { queries: { gcTime: 0 } } })
+    const result = render(
+      <QueryClientProvider client={queryClient}>
+        <I18nProvider locale="en" dict={{}}>
+          <DataTable
+            columns={columns}
+            data={[{ id: '1', title: 'Solar rollout', status: 'open' }]}
+            stickyFirstColumn
+            stickyActionsColumn
+            rowActions={() => (
+              <RowActions items={[{ id: 'edit', label: 'Edit', onSelect: () => {} }]} />
+            )}
+          />
+        </I18nProvider>
+      </QueryClientProvider>,
+    )
+    return { ...result, queryClient }
+  }
+
+  it('pins the first data column only from md up', () => {
+    const { container, queryClient } = renderStickyTable()
+    try {
+      const headerCells = container.querySelectorAll('thead th')
+      const firstHeader = headerCells[0]
+      const firstBodyCell = container.querySelector('tbody tr td')
+
+      for (const cell of [firstHeader, firstBodyCell]) {
+        const tokens = tokensOf(cell)
+        expect(tokens).toEqual(
+          expect.arrayContaining(['md:sticky', 'md:left-0', 'md:bg-background', 'md:after:absolute']),
+        )
+        expect(tokens).not.toContain('sticky')
+        expect(tokens).not.toContain('left-0')
+        expect(tokens).not.toContain('bg-background')
+        expect(tokens).not.toContain('after:absolute')
+      }
+    } finally {
+      queryClient.clear()
+    }
+  })
+
+  it('pins the actions column only from md up', () => {
+    const { container, queryClient } = renderStickyTable()
+    try {
+      const headerCells = container.querySelectorAll('thead th')
+      const actionsHeader = headerCells[headerCells.length - 1]
+      const actionsBodyCell = container.querySelector('tbody tr td[data-actions-cell]')
+      expect(actionsBodyCell).not.toBeNull()
+
+      for (const cell of [actionsHeader, actionsBodyCell]) {
+        const tokens = tokensOf(cell)
+        expect(tokens).toEqual(
+          expect.arrayContaining(['md:sticky', 'md:right-0', 'md:bg-background', 'md:before:absolute']),
+        )
+        expect(tokens).not.toContain('sticky')
+        expect(tokens).not.toContain('right-0')
+        expect(tokens).not.toContain('bg-background')
+        expect(tokens).not.toContain('before:absolute')
+      }
+    } finally {
+      queryClient.clear()
+    }
+  })
+})

package/src/backend/charts/KpiCard.tsx

@@ -20,6 +20,8 @@ export type KpiCardProps = {
   suffix?: string
   className?: string
   headerAction?: React.ReactNode
+  footer?: React.ReactNode
+  titleClassName?: string
 }
 
 function defaultFormatValue(value: number): string {
@@ -32,17 +34,21 @@ function defaultFormatValue(value: number): string {
   return value.toLocaleString(undefined, { maximumFractionDigits: 2 })
 }
 
-function formatPercentageChange(value: number): string {
-  const formatted = Math.abs(value).toFixed(1)
-  return `${formatted}%`
+function formatPercentageChange(value: number, unit: string = '%'): string {
+  const abs = Math.abs(value)
+  const formatted = Number.isInteger(abs) ? String(abs) : abs.toFixed(1)
+  return `${formatted}${unit}`
 }
 
 type BadgeDeltaProps = {
   direction: 'up' | 'down' | 'unchanged'
   value: number
+  unit?: string
+  className?: string
+  title?: string
 }
 
-function BadgeDelta({ direction, value }: BadgeDeltaProps) {
+function BadgeDelta({ direction, value, unit = '%', className = '', title = 'Compared to previous period' }: BadgeDeltaProps) {
   const baseClasses = 'inline-flex items-center gap-1 rounded-md px-2 py-0.5 text-xs font-medium'
 
   const directionClasses = {
@@ -71,15 +77,17 @@ function BadgeDelta({ direction, value }: BadgeDeltaProps) {
 
   return (
     <span
-      className={`${baseClasses} ${directionClasses[direction]}`}
-      title="Compared to previous period"
+      className={`${baseClasses} ${directionClasses[direction]}${className ? ` ${className}` : ''}`}
+      title={title}
     >
       {icons[direction]}
-      {formatPercentageChange(value)}
+      {formatPercentageChange(value, unit)}
     </span>
   )
 }
 
+export const DeltaBadge = BadgeDelta
+
 export function KpiCard({
   title,
   value,
@@ -92,13 +100,15 @@ export function KpiCard({
   suffix = '',
   className = '',
   headerAction,
+  footer,
+  titleClassName,
 }: KpiCardProps) {
   const hasWrapper = !!title
   const wrapperClass = hasWrapper ? `rounded-lg border bg-card p-4 ${className}` : className
 
   const headerRow = (title || headerAction) ? (
     <div className="flex items-center justify-between gap-2 mb-2">
-      {title && <p className="text-sm font-medium text-muted-foreground">{title}</p>}
+      {title && <p className={titleClassName ?? 'text-sm font-medium text-muted-foreground'}>{title}</p>}
       {headerAction}
     </div>
   ) : null
@@ -136,10 +146,9 @@ export function KpiCard({
     <div className={wrapperClass}>
       {headerRow}
       <div className="flex items-baseline gap-3">
-        <p className="text-2xl sm:text-3xl font-semibold tracking-tight text-card-foreground">
-          {prefix}
-          {formatValue(value)}
-          {suffix}
+        <p className="flex items-baseline gap-1.5 text-2xl sm:text-3xl font-semibold tracking-tight text-card-foreground">
+          <span>{prefix}{formatValue(value)}</span>
+          {suffix ? <span className="text-sm font-medium text-muted-foreground">{suffix}</span> : null}
         </p>
         {trend && (
           <BadgeDelta direction={trend.direction} value={trend.value} />
@@ -148,6 +157,7 @@ export function KpiCard({
       {trend && comparisonLabel && (
         <p className="mt-1 text-xs text-muted-foreground">{comparisonLabel}</p>
       )}
+      {footer != null && <div className="mt-3">{footer}</div>}
     </div>
   )
 }

package/src/backend/charts/Sparkline.tsx

@@ -0,0 +1,87 @@
+"use client"
+
+import * as React from 'react'
+
+export type SparklineProps = {
+  values: number[]
+  ariaLabel: string
+  className?: string
+  width?: number
+  height?: number
+}
+
+function buildPoints(values: number[], width: number, height: number): Array<{ x: number; y: number }> {
+  const count = values.length
+  const padding = 2
+  const usableHeight = Math.max(height - padding * 2, 0)
+
+  if (count === 1) {
+    return [{ x: width / 2, y: height / 2 }]
+  }
+
+  let min = values[0]
+  let max = values[0]
+  for (const value of values) {
+    if (value < min) min = value
+    if (value > max) max = value
+  }
+  const range = max - min
+
+  const stepX = count > 1 ? width / (count - 1) : 0
+
+  return values.map((value, index) => {
+    const x = stepX * index
+    const ratio = range === 0 ? 0.5 : (value - min) / range
+    const y = padding + (1 - ratio) * usableHeight
+    return { x, y }
+  })
+}
+
+function toPath(points: Array<{ x: number; y: number }>): string {
+  return points
+    .map((point, index) => `${index === 0 ? 'M' : 'L'} ${point.x.toFixed(2)} ${point.y.toFixed(2)}`)
+    .join(' ')
+}
+
+export function Sparkline({
+  values,
+  ariaLabel,
+  className = '',
+  width = 96,
+  height = 28,
+}: SparklineProps) {
+  if (!values || values.length === 0) {
+    return null
+  }
+
+  const points = buildPoints(values, width, height)
+  const linePath = toPath(points)
+
+  const firstPoint = points[0]
+  const lastPoint = points[points.length - 1]
+  const areaPath = `${linePath} L ${lastPoint.x.toFixed(2)} ${height} L ${firstPoint.x.toFixed(2)} ${height} Z`
+
+  return (
+    <svg
+      role="img"
+      aria-label={ariaLabel}
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      preserveAspectRatio="none"
+      className={className}
+    >
+      <path d={areaPath} fill="currentColor" fillOpacity={0.12} stroke="none" />
+      <path
+        d={linePath}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={1.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+export default Sparkline

package/src/backend/charts/index.ts

@@ -1,4 +1,5 @@
-export { KpiCard, type KpiCardProps, type KpiTrend } from './KpiCard'
+export { KpiCard, DeltaBadge, type KpiCardProps, type KpiTrend } from './KpiCard'
+export { Sparkline, type SparklineProps } from './Sparkline'
 export { BarChart, type BarChartProps, type BarChartDataItem } from './BarChart'
 export { LineChart, type LineChartProps, type LineChartDataItem } from './LineChart'
 export { PieChart, type PieChartProps, type PieChartDataItem } from './PieChart'

package/src/backend/dashboard/DashboardScreen.tsx

@@ -10,7 +10,7 @@ import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
 import { getDashboardWidgets, loadDashboardWidgetModule } from './widgetRegistry'
 import type { DashboardWidgetModule } from '@open-mercato/shared/modules/dashboard/widgets'
 import { cn } from '@open-mercato/shared/lib/utils'
-import { GripVertical, Info, Plus, RefreshCw, Settings2, Trash2, X, Loader2 } from 'lucide-react'
+import { GripVertical, Plus, RefreshCw, Settings2, Trash2, X, Loader2 } from 'lucide-react'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { InjectionSpot } from '../injection/InjectionSpot'
@@ -366,7 +366,6 @@ export function DashboardScreen() {
   if (!hasRegisteredWidgets && layout.length === 0) {
     return (
       <Alert variant="info">
-        <Info className="h-4 w-4" aria-hidden />
         <AlertTitle>{t('dashboard.empty.noWidgets.title', 'No dashboard widgets yet')}</AlertTitle>
         <AlertDescription>
           {t(

package/src/backend/injection/InjectionSpot.tsx

@@ -76,6 +76,15 @@ export function useInjectionWidgets<TContext = unknown>(
   const [error, setError] = React.useState<string | null>(null)
   const [registryVersion, setRegistryVersion] = React.useState(() => getInjectionRegistryVersion())
   const loadedRef = React.useRef(false)
+  const contextRef = React.useRef(options?.context)
+  const triggerOnLoadRef = React.useRef(options?.triggerOnLoad)
+  const onEventRef = React.useRef(options?.onEvent)
+
+  React.useEffect(() => {
+    contextRef.current = options?.context
+    triggerOnLoadRef.current = options?.triggerOnLoad
+    onEventRef.current = options?.onEvent
+  })
 
   React.useEffect(() => {
     return subscribeToInjectionRegistryChanges(() => {
@@ -105,16 +114,16 @@ export function useInjectionWidgets<TContext = unknown>(
           placement: w.placement,
         }))
         setWidgets(widgetList)
-        
+
         // Trigger onLoad for all widgets
-        if (!loadedRef.current && options?.triggerOnLoad) {
+        if (!loadedRef.current && triggerOnLoadRef.current) {
           loadedRef.current = true
           for (const widget of widgetList) {
             if (widget.module.eventHandlers?.onLoad) {
               try {
-                const widgetContext = injectSharedStateIntoContext(options.context as TContext, widget.moduleId)
+                const widgetContext = injectSharedStateIntoContext(contextRef.current as TContext, widget.moduleId)
                 await widget.module.eventHandlers.onLoad(widgetContext)
-                options.onEvent?.('onLoad', widget.widgetId)
+                onEventRef.current?.('onLoad', widget.widgetId)
               } catch (err) {
                 console.error(`[InjectionSpot] Error in onLoad for widget ${widget.widgetId}:`, err)
               }
@@ -133,7 +142,9 @@ export function useInjectionWidgets<TContext = unknown>(
     return () => {
       mounted = false
     }
-  }, [spotId, options?.context, options?.triggerOnLoad, options?.onEvent, registryVersion])
+    // context/triggerOnLoad/onEvent are read from refs so only a real registry-version bump reloads the spot
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [spotId, registryVersion])
 
   return { widgets, loading, error }
 }
@@ -148,16 +159,25 @@ export function InjectionSpot<TContext = unknown, TData = unknown>({
   widgetsOverride,
 }: InjectionSpotProps<TContext, TData>) {
   const useSpotId = widgetsOverride ? null : spotId
+  const onEventRef = React.useRef(onEvent)
+  React.useEffect(() => {
+    onEventRef.current = onEvent
+  })
+  const hasOnEvent = Boolean(onEvent)
+  const stableOnEvent = React.useMemo(
+    () => (hasOnEvent ? (event: 'onLoad', id: string) => onEventRef.current?.(event, id) : undefined),
+    [hasOnEvent],
+  )
   const { widgets, loading, error } = useInjectionWidgets<TContext>(useSpotId, {
     context,
     triggerOnLoad: !widgetsOverride,
-    onEvent: onEvent ? (event, id) => onEvent(event, id) : undefined,
+    onEvent: stableOnEvent,
   })
   const effectiveWidgets = widgetsOverride ?? widgets
   const effectiveLoading = widgetsOverride ? false : loading
   const effectiveError = widgetsOverride ? null : error
 
-  if (effectiveLoading) {
+  if (effectiveLoading && effectiveWidgets.length === 0) {
     return null
   }
 

package/src/backend/injection/__tests__/InjectionSpot.remount.test.tsx

@@ -0,0 +1,140 @@
+/** @jest-environment jsdom */
+
+import * as React from 'react'
+import { act, render, waitFor } from '@testing-library/react'
+
+const mockState: { registryVersion: number; listener: null | (() => void) } = {
+  registryVersion: 0,
+  listener: null,
+}
+const mockLoadSpy = jest.fn()
+
+jest.mock('@open-mercato/shared/modules/widgets/injection-loader', () => ({
+  getInjectionRegistryVersion: () => mockState.registryVersion,
+  subscribeToInjectionRegistryChanges: (listener: () => void) => {
+    mockState.listener = listener
+    return () => {
+      mockState.listener = null
+    }
+  },
+  loadInjectionWidgetsForSpot: (...args: unknown[]) => mockLoadSpy(...args),
+}))
+
+jest.mock('../WidgetSharedState', () => ({
+  getWidgetSharedState: () => ({}),
+}))
+
+import { InjectionSpot } from '../InjectionSpot'
+
+const SPOT_ID = 'data-table:test.products:toolbar'
+const widgetMountSpy = jest.fn()
+const onLoadSpy = jest.fn()
+
+function makeWidget(id: string) {
+  return {
+    metadata: { id },
+    moduleId: 'test_module',
+    key: id,
+    placement: undefined,
+    eventHandlers: { onLoad: onLoadSpy },
+    Widget: ({ context }: { context: unknown }) => {
+      React.useEffect(() => {
+        widgetMountSpy()
+      }, [])
+      const label = (context as { label?: string } | null)?.label ?? ''
+      return <div data-testid="injected-widget">{label}</div>
+    },
+  }
+}
+
+function Harness({ tick, onEvent }: { tick: number; onEvent?: (event: 'onLoad', id: string) => void }) {
+  // Fresh context identity on every render — mirrors hosts that feed a useMemo/closure
+  // context whose identity changes on routine interactions (e.g. row-selection toggles).
+  const context = { label: 'ctx', tick }
+  return <InjectionSpot spotId={SPOT_ID} context={context} onEvent={onEvent} />
+}
+
+describe('InjectionSpot — context identity changes do not remount injected widgets', () => {
+  beforeEach(() => {
+    mockState.registryVersion = 0
+    mockState.listener = null
+    mockLoadSpy.mockReset()
+    mockLoadSpy.mockResolvedValue([makeWidget('test_module:hello')])
+    widgetMountSpy.mockClear()
+    onLoadSpy.mockClear()
+  })
+
+  it('renders the injected widget and loads the spot exactly once', async () => {
+    const { findByTestId } = render(<Harness tick={0} />)
+    await findByTestId('injected-widget')
+    expect(mockLoadSpy).toHaveBeenCalledTimes(1)
+    expect(widgetMountSpy).toHaveBeenCalledTimes(1)
+    expect(onLoadSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('does NOT reload or remount when only the context identity changes', async () => {
+    const { rerender, findByTestId } = render(<Harness tick={0} />)
+    await findByTestId('injected-widget')
+    expect(mockLoadSpy).toHaveBeenCalledTimes(1)
+    expect(widgetMountSpy).toHaveBeenCalledTimes(1)
+
+    for (let next = 1; next <= 3; next += 1) {
+      rerender(<Harness tick={next} />)
+      // flush effects for this render
+      await act(async () => {})
+    }
+
+    expect(mockLoadSpy).toHaveBeenCalledTimes(1)
+    expect(widgetMountSpy).toHaveBeenCalledTimes(1)
+    expect(onLoadSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('does NOT reload when a fresh onEvent closure is passed on every render', async () => {
+    const { rerender, findByTestId } = render(<Harness tick={0} onEvent={() => {}} />)
+    await findByTestId('injected-widget')
+    expect(mockLoadSpy).toHaveBeenCalledTimes(1)
+
+    rerender(<Harness tick={1} onEvent={() => {}} />)
+    await act(async () => {})
+
+    expect(mockLoadSpy).toHaveBeenCalledTimes(1)
+    expect(widgetMountSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('DOES reload when the injection registry version actually bumps', async () => {
+    const { findByTestId } = render(<Harness tick={0} />)
+    await findByTestId('injected-widget')
+    expect(mockLoadSpy).toHaveBeenCalledTimes(1)
+
+    await act(async () => {
+      mockState.registryVersion += 1
+      mockState.listener?.()
+    })
+
+    await waitFor(() => expect(mockLoadSpy).toHaveBeenCalledTimes(2))
+  })
+
+  it('keeps the previously-rendered widget mounted during a registry reload', async () => {
+    const { findByTestId } = render(<Harness tick={0} />)
+    await findByTestId('injected-widget')
+
+    let resolveReload: (value: ReturnType<typeof makeWidget>[]) => void = () => {}
+    mockLoadSpy.mockImplementationOnce(
+      () => new Promise((resolve) => { resolveReload = resolve }),
+    )
+
+    await act(async () => {
+      mockState.registryVersion += 1
+      mockState.listener?.()
+    })
+
+    // Reload is in-flight (loading === true) but the existing widget stays mounted.
+    expect(await findByTestId('injected-widget')).toBeTruthy()
+
+    await act(async () => {
+      resolveReload([makeWidget('test_module:hello')])
+    })
+
+    await findByTestId('injected-widget')
+  })
+})

package/src/primitives/__tests__/alert.test.tsx

@@ -133,6 +133,22 @@ describe('Alert primitive', () => {
       render(<Alert status="information" style="light" icon={<Custom />}>Info</Alert>)
       expect(screen.getByTestId('custom-icon')).toBeInTheDocument()
     })
+
+    it('renders exactly one leading icon by default (#2759)', () => {
+      const { container } = render(<Alert status="information">Info</Alert>)
+      expect(container.querySelectorAll('[data-slot="alert-icon-badge"]')).toHaveLength(1)
+      expect(container.querySelectorAll('[data-slot="alert-icon-badge"] > svg')).toHaveLength(1)
+    })
+
+    it('icon prop REPLACES the default status icon instead of adding a second one (#2759)', () => {
+      const Custom = () => <svg data-testid="custom-icon" aria-hidden="true" />
+      const { container } = render(
+        <Alert status="information" icon={<Custom />}>Info</Alert>,
+      )
+      expect(container.querySelectorAll('[data-slot="alert-icon-badge"]')).toHaveLength(1)
+      expect(container.querySelectorAll('[data-slot="alert-icon-badge"] > svg')).toHaveLength(1)
+      expect(screen.getByTestId('custom-icon')).toBeInTheDocument()
+    })
   })
 
   describe('Action slot + dismiss', () => {

package/src/primitives/__tests__/avatar.test.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react'
 import { render, screen } from '@testing-library/react'
-import { Avatar } from '../avatar'
+import { Avatar, AvatarStack } from '../avatar'
 
 describe('Avatar', () => {
   it('renders two-character initials for multi-word labels', () => {
@@ -193,3 +193,38 @@ describe('Avatar', () => {
     })
   })
 })
+
+describe('AvatarStack', () => {
+  it('derives the +N overflow from children beyond max', () => {
+    render(
+      <AvatarStack max={2}>
+        <Avatar label="Alice Adams" />
+        <Avatar label="Bob Brown" />
+        <Avatar label="Carol Clark" />
+      </AvatarStack>,
+    )
+    expect(screen.getByText('+1')).toBeInTheDocument()
+  })
+
+  it('adds overflowCount (server-truncated items) to the children-derived overflow', () => {
+    // 5 children, max 4 → 1 hidden locally; overflowCount=7 server-hidden → "+8".
+    render(
+      <AvatarStack max={4} overflowCount={7}>
+        {Array.from({ length: 5 }, (_, index) => (
+          <Avatar key={index} label={`Owner ${index}`} />
+        ))}
+      </AvatarStack>,
+    )
+    expect(screen.getByText('+8')).toBeInTheDocument()
+  })
+
+  it('shows no overflow badge when children fit and overflowCount is 0', () => {
+    render(
+      <AvatarStack max={4}>
+        <Avatar label="Alice Adams" />
+        <Avatar label="Bob Brown" />
+      </AvatarStack>,
+    )
+    expect(screen.queryByText(/^\+\d/)).not.toBeInTheDocument()
+  })
+})