@startsimpli/ui 0.4.50 → 0.4.52

package/src/components/health/PipelineHealth.tsx

@@ -0,0 +1,99 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { GitBranch } from 'lucide-react'
+import { HealthCard } from './HealthCard'
+import { HEALTH_TONE, worstStatus, type HealthStatus } from './health-status'
+
+export interface PipelineStage {
+  label: string
+  count: number
+  /** Optional per-stage tone accent (default derived: 0 records = neutral, else ok). */
+  tone?: HealthStatus
+}
+
+export interface PipelineHealthProps {
+  title?: string
+  stages: PipelineStage[]
+  /** Records stuck / aging past their SLA — surfaces as the card's warning. */
+  attention?: number
+  attentionLabel?: string
+  onStageClick?: (label: string) => void
+  emptyMessage?: string
+  className?: string
+}
+
+/**
+ * Content-pipeline health: the count of records in each stage of a status field,
+ * plus a "stuck / aging" attention flag. Presentational — a tenant dashboard
+ * widget derives `stages` from groupByStatus over one content type's records.
+ */
+export function PipelineHealth({
+  title = 'Pipeline',
+  stages,
+  attention = 0,
+  attentionLabel,
+  onStageClick,
+  emptyMessage = 'No records yet.',
+  className,
+}: PipelineHealthProps) {
+  const total = stages.reduce((sum, s) => sum + s.count, 0)
+  const max = Math.max(1, ...stages.map((s) => s.count))
+
+  const status: HealthStatus =
+    total === 0
+      ? 'neutral'
+      : attention > 0
+        ? worstStatus(['warn', ...stages.map((s) => s.tone ?? 'ok')])
+        : 'ok'
+
+  const statusLabel =
+    total === 0
+      ? undefined
+      : attention > 0
+        ? (attentionLabel ?? `${attention} need attention`)
+        : `${total} total`
+
+  return (
+    <HealthCard
+      title={title}
+      status={status}
+      statusLabel={statusLabel}
+      icon={GitBranch}
+      isEmpty={total === 0}
+      emptyMessage={emptyMessage}
+      className={className}
+    >
+      <div className="space-y-2.5" role="list" aria-label={`${title} stages`}>
+        {stages.map((stage) => {
+          const tone = HEALTH_TONE[stage.tone ?? (stage.count === 0 ? 'neutral' : 'ok')]
+          const pct = (stage.count / max) * 100
+          const clickable = Boolean(onStageClick)
+          return (
+            <button
+              key={stage.label}
+              type="button"
+              role="listitem"
+              disabled={!clickable}
+              onClick={() => onStageClick?.(stage.label)}
+              className={cn(
+                'w-full text-left group focus:outline-none',
+                clickable && 'cursor-pointer focus:ring-2 focus:ring-primary-500 rounded',
+              )}
+            >
+              <div className="flex items-center justify-between mb-1">
+                <span className="text-xs font-medium text-gray-600 capitalize">{stage.label}</span>
+                <span className="text-xs font-bold text-gray-900 tabular-nums">{stage.count}</span>
+              </div>
+              <div className="h-1.5 rounded-full bg-gray-100 overflow-hidden">
+                <div
+                  className={cn('h-full rounded-full transition-all', tone.dot, clickable && 'group-hover:opacity-80')}
+                  style={{ width: `${pct}%` }}
+                />
+              </div>
+            </button>
+          )
+        })}
+      </div>
+    </HealthCard>
+  )
+}

package/src/components/health/SourceFreshness.tsx

@@ -0,0 +1,88 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { Rss } from 'lucide-react'
+import { formatRelativeTime } from '../../utils'
+import { HealthCard, HealthDot } from './HealthCard'
+import { worstStatus, type HealthStatus } from './health-status'
+
+export interface SourceFreshnessItem {
+  name: string
+  /** Last time this source delivered data. Null/undefined = never = stale. */
+  lastUpdated?: string | Date | null
+  /** Explicit status; otherwise derived from lastUpdated vs staleAfterHours. */
+  status?: HealthStatus
+}
+
+export interface SourceFreshnessProps {
+  title?: string
+  sources: SourceFreshnessItem[]
+  /** A source with no update within this window is stale (default 48h). */
+  staleAfterHours?: number
+  /** Compare against this instant (injectable for tests); defaults to Date.now(). */
+  now?: number
+  emptyMessage?: string
+  className?: string
+}
+
+function deriveStatus(item: SourceFreshnessItem, staleAfterHours: number, now: number): HealthStatus {
+  if (item.status) return item.status
+  if (!item.lastUpdated) return 'critical'
+  const ts = new Date(item.lastUpdated).getTime()
+  if (Number.isNaN(ts)) return 'neutral'
+  const ageHours = (now - ts) / 3_600_000
+  if (ageHours <= staleAfterHours) return 'ok'
+  if (ageHours <= staleAfterHours * 2) return 'warn'
+  return 'critical'
+}
+
+/**
+ * Source / ingestion freshness: which upstream feeds are fresh vs stale. A stale
+ * source is a bug (everything is ongoing — no one-time fetches), so any stale
+ * feed pulls the whole card to warn/critical. Presentational — a tenant widget
+ * feeds it the source records + their last-fetched markers.
+ */
+export function SourceFreshness({
+  title = 'Source freshness',
+  sources,
+  staleAfterHours = 48,
+  now,
+  emptyMessage = 'No sources configured.',
+  className,
+}: SourceFreshnessProps) {
+  const at = now ?? Date.now()
+  const rows = sources.map((s) => ({ ...s, resolved: deriveStatus(s, staleAfterHours, at) }))
+  const staleCount = rows.filter((r) => r.resolved === 'warn' || r.resolved === 'critical').length
+  const status = worstStatus(rows.map((r) => r.resolved))
+  const statusLabel = sources.length === 0 ? undefined : staleCount > 0 ? `${staleCount} stale` : 'All fresh'
+
+  return (
+    <HealthCard
+      title={title}
+      status={status}
+      statusLabel={statusLabel}
+      icon={Rss}
+      isEmpty={sources.length === 0}
+      emptyMessage={emptyMessage}
+      className={className}
+    >
+      <ul className="space-y-2" aria-label={`${title} sources`}>
+        {rows.map((row) => (
+          <li key={row.name} className="flex items-center justify-between gap-3 text-sm">
+            <span className="flex items-center gap-2 min-w-0">
+              <HealthDot status={row.resolved} />
+              <span className="text-gray-700 truncate">{row.name}</span>
+            </span>
+            <span
+              className={cn(
+                'text-xs tabular-nums flex-shrink-0',
+                row.resolved === 'ok' ? 'text-gray-500' : 'text-gray-900 font-medium',
+              )}
+            >
+              {row.lastUpdated ? formatRelativeTime(row.lastUpdated) : 'never'}
+            </span>
+          </li>
+        ))}
+      </ul>
+    </HealthCard>
+  )
+}

package/src/components/health/__tests__/health.test.tsx

@@ -0,0 +1,142 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import {
+  worstStatus,
+  HealthCard,
+  PipelineHealth,
+  SourceFreshness,
+  DeliveryHealth,
+  AttentionFeed,
+} from '../index'
+
+const NOW = 1_700_000_000_000 // fixed instant for freshness/delivery derivation
+const hoursAgo = (h: number) => new Date(NOW - h * 3_600_000).toISOString()
+const hoursAhead = (h: number) => new Date(NOW + h * 3_600_000).toISOString()
+
+describe('worstStatus', () => {
+  it('returns neutral for an empty list', () => {
+    expect(worstStatus([])).toBe('neutral')
+  })
+  it('escalates critical > warn > ok > neutral', () => {
+    expect(worstStatus(['ok', 'neutral'])).toBe('ok')
+    expect(worstStatus(['ok', 'warn'])).toBe('warn')
+    expect(worstStatus(['ok', 'warn', 'critical'])).toBe('critical')
+  })
+})
+
+describe('HealthCard', () => {
+  it('renders the title and the tone badge', () => {
+    render(<HealthCard title="Pipeline" status="ok" />)
+    expect(screen.getByText('Pipeline')).toBeInTheDocument()
+    expect(screen.getByText('Healthy')).toBeInTheDocument()
+  })
+  it('shows the empty message when isEmpty', () => {
+    render(<HealthCard title="X" status="neutral" isEmpty emptyMessage="Nothing here" />)
+    expect(screen.getByText('Nothing here')).toBeInTheDocument()
+  })
+  it('honors a custom status label', () => {
+    render(<HealthCard title="X" status="warn" statusLabel="3 stale" />)
+    expect(screen.getByText('3 stale')).toBeInTheDocument()
+  })
+})
+
+describe('PipelineHealth', () => {
+  const stages = [
+    { label: 'draft', count: 4 },
+    { label: 'review', count: 2 },
+    { label: 'ready', count: 1 },
+  ]
+  it('renders every stage with its count', () => {
+    render(<PipelineHealth title="Briefs" stages={stages} />)
+    expect(screen.getByText('draft')).toBeInTheDocument()
+    expect(screen.getByText('4')).toBeInTheDocument()
+    expect(screen.getByText('7 total')).toBeInTheDocument()
+  })
+  it('flags attention items in the badge', () => {
+    render(<PipelineHealth stages={stages} attention={2} />)
+    expect(screen.getByText('2 need attention')).toBeInTheDocument()
+  })
+  it('renders the empty state when there are no records', () => {
+    render(<PipelineHealth stages={[{ label: 'draft', count: 0 }]} emptyMessage="No records yet." />)
+    expect(screen.getByText('No records yet.')).toBeInTheDocument()
+  })
+  it('calls onStageClick', () => {
+    const onClick = jest.fn()
+    render(<PipelineHealth stages={stages} onStageClick={onClick} />)
+    fireEvent.click(screen.getByText('review'))
+    expect(onClick).toHaveBeenCalledWith('review')
+  })
+})
+
+describe('SourceFreshness', () => {
+  it('reports all fresh when every source is recent', () => {
+    render(
+      <SourceFreshness
+        now={NOW}
+        staleAfterHours={48}
+        sources={[
+          { name: 'RSS A', lastUpdated: hoursAgo(2) },
+          { name: 'RSS B', lastUpdated: hoursAgo(10) },
+        ]}
+      />,
+    )
+    expect(screen.getByText('All fresh')).toBeInTheDocument()
+  })
+  it('counts stale sources and shows "never" for missing timestamps', () => {
+    render(
+      <SourceFreshness
+        now={NOW}
+        staleAfterHours={48}
+        sources={[
+          { name: 'RSS A', lastUpdated: hoursAgo(2) },
+          { name: 'RSS B', lastUpdated: hoursAgo(200) },
+          { name: 'RSS C', lastUpdated: null },
+        ]}
+      />,
+    )
+    expect(screen.getByText('2 stale')).toBeInTheDocument()
+    expect(screen.getByText('never')).toBeInTheDocument()
+  })
+})
+
+describe('DeliveryHealth', () => {
+  it('is on track when deliveries are on time', () => {
+    render(
+      <DeliveryHealth
+        now={NOW}
+        items={[{ label: 'Week 1', dueAt: hoursAgo(48), deliveredAt: hoursAgo(50) }]}
+      />,
+    )
+    expect(screen.getByText('On track')).toBeInTheDocument()
+  })
+  it('flags missed and late deliveries', () => {
+    render(
+      <DeliveryHealth
+        now={NOW}
+        items={[
+          { label: 'Week 1', dueAt: hoursAgo(10) }, // undelivered + past due => missed
+          { label: 'Week 2', dueAt: hoursAhead(24) }, // upcoming
+        ]}
+      />,
+    )
+    expect(screen.getByText('1 off-track')).toBeInTheDocument()
+  })
+})
+
+describe('AttentionFeed', () => {
+  it('is all clear when empty', () => {
+    render(<AttentionFeed items={[]} />)
+    expect(screen.getByText('All clear')).toBeInTheDocument()
+  })
+  it('counts items to review and links them', () => {
+    render(
+      <AttentionFeed
+        items={[
+          { id: '1', label: 'Draft needs review', href: '/t/general/1' },
+          { id: '2', label: 'Stuck brief' },
+        ]}
+      />,
+    )
+    expect(screen.getByText('2 to review')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: /Draft needs review/ })).toHaveAttribute('href', '/t/general/1')
+  })
+})

package/src/components/health/health-status.ts

@@ -0,0 +1,79 @@
+import {
+  CheckCircle2,
+  AlertTriangle,
+  AlertCircle,
+  CircleDashed,
+  type LucideIcon,
+} from 'lucide-react'
+
+/**
+ * Shared status vocabulary for the SystemHealth blocks (768w.16.8.2).
+ *
+ * Every health signal collapses to one of four tones. The tone is always
+ * encoded REDUNDANTLY — a colored dot AND an icon AND a text label — so the
+ * signal never depends on color alone (accessibility), matching the rest of the
+ * @startsimpli/ui dashboard kit's static semantic palette.
+ */
+export type HealthStatus = 'ok' | 'warn' | 'critical' | 'neutral'
+
+export interface HealthTone {
+  /** Default human label for the tone (composers may override). */
+  label: string
+  /** Solid dot / bar fill. */
+  dot: string
+  /** Foreground text for the tone. */
+  text: string
+  /** Soft background for pills / accents. */
+  softBg: string
+  /** Left-accent border color for HealthCard. */
+  border: string
+  /** The lucide icon that stands in for the tone. */
+  Icon: LucideIcon
+}
+
+export const HEALTH_TONE: Record<HealthStatus, HealthTone> = {
+  ok: {
+    label: 'Healthy',
+    dot: 'bg-emerald-500',
+    text: 'text-emerald-700',
+    softBg: 'bg-emerald-50',
+    border: 'border-l-emerald-500',
+    Icon: CheckCircle2,
+  },
+  warn: {
+    label: 'Needs attention',
+    dot: 'bg-amber-500',
+    text: 'text-amber-700',
+    softBg: 'bg-amber-50',
+    border: 'border-l-amber-500',
+    Icon: AlertTriangle,
+  },
+  critical: {
+    label: 'Critical',
+    dot: 'bg-red-500',
+    text: 'text-red-700',
+    softBg: 'bg-red-50',
+    border: 'border-l-red-500',
+    Icon: AlertCircle,
+  },
+  neutral: {
+    label: 'No data',
+    dot: 'bg-gray-400',
+    text: 'text-gray-600',
+    softBg: 'bg-gray-50',
+    border: 'border-l-gray-300',
+    Icon: CircleDashed,
+  },
+}
+
+const SEVERITY: Record<HealthStatus, number> = { neutral: 0, ok: 1, warn: 2, critical: 3 }
+
+/**
+ * Roll several signals up to the single worst tone — the accent a HealthCard
+ * shows. `critical` beats `warn` beats `ok`; `neutral` (no data) only wins when
+ * there is nothing else to report.
+ */
+export function worstStatus(statuses: HealthStatus[]): HealthStatus {
+  if (statuses.length === 0) return 'neutral'
+  return statuses.reduce((worst, s) => (SEVERITY[s] > SEVERITY[worst] ? s : worst), 'neutral')
+}

package/src/components/health/index.ts

@@ -0,0 +1,24 @@
+/**
+ * SystemHealth blocks (768w.16.8.2) — presentational, bring-your-own-data cards
+ * that bubble up the health of a data-driven tenant app: pipeline status, source
+ * freshness, delivery/schedule adherence, and a needs-attention queue. A tenant
+ * dashboard widget fetches the data and hands each block plain props; the blocks
+ * own the tone roll-up + layout so the app wrapper stays thin.
+ */
+export { HealthCard, HealthDot, HealthBadge } from './HealthCard'
+export type { HealthCardProps } from './HealthCard'
+
+export { HEALTH_TONE, worstStatus } from './health-status'
+export type { HealthStatus, HealthTone } from './health-status'
+
+export { PipelineHealth } from './PipelineHealth'
+export type { PipelineHealthProps, PipelineStage } from './PipelineHealth'
+
+export { SourceFreshness } from './SourceFreshness'
+export type { SourceFreshnessProps, SourceFreshnessItem } from './SourceFreshness'
+
+export { DeliveryHealth } from './DeliveryHealth'
+export type { DeliveryHealthProps, DeliveryItem, DeliveryState } from './DeliveryHealth'
+
+export { AttentionFeed } from './AttentionFeed'
+export type { AttentionFeedProps, AttentionItem } from './AttentionFeed'

package/src/components/index.ts

@@ -53,6 +53,7 @@ export * from './unified-table/utils'
 // Export Navigation
 export * from './navigation/sidebar'
 export * from './navigation/app-shell'
+export * from './navigation/grouped-nav'
 
 // Workspace layout primitives (SplitPane, DualPaneWorkspace) — generic two-pane shell
 export * from './workspace'
@@ -121,6 +122,9 @@ export * from './email-dialogs'
 // Dashboard components (MetricCard, PeriodSelector, SparklineTrend, DashboardGrid, DashboardSection)
 export * from './dashboard'
 
+// SystemHealth blocks (HealthCard, PipelineHealth, SourceFreshness, DeliveryHealth, AttentionFeed)
+export * from './health'
+
 // Enrichment components (QualityBadge, EnrichButton, EnrichmentProgress)
 export * from './enrichment'
 

package/src/components/navigation/__tests__/grouped-nav.test.tsx

@@ -0,0 +1,69 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { GroupedNav, type GroupedNavEntry } from '../grouped-nav'
+
+const items: GroupedNavEntry[] = [
+  { href: '/', label: 'Dashboard' },
+  {
+    label: 'Content',
+    items: [
+      { href: '/t/weekly_brief', label: 'Weekly Briefs' },
+      { href: '/t/lead_magnet', label: 'Lead Magnets' },
+      { href: '/t/general', label: 'General' },
+    ],
+  },
+]
+
+describe('GroupedNav', () => {
+  it('renders top-level links and grouped links', () => {
+    render(<GroupedNav items={items} activeHref="/" />)
+    expect(screen.getByText('Dashboard')).toBeInTheDocument()
+    expect(screen.getByText('Content')).toBeInTheDocument()
+    expect(screen.getByText('Weekly Briefs')).toBeInTheDocument()
+    expect(screen.getByText('General')).toBeInTheDocument()
+  })
+
+  it('marks the active link with aria-current=page', () => {
+    render(<GroupedNav items={items} activeHref="/t/lead_magnet" />)
+    expect(screen.getByRole('link', { name: 'Lead Magnets' })).toHaveAttribute('aria-current', 'page')
+    expect(screen.getByRole('link', { name: 'Weekly Briefs' })).not.toHaveAttribute('aria-current')
+  })
+
+  it('treats a child path as active for its link', () => {
+    render(<GroupedNav items={items} activeHref="/t/general/42" />)
+    expect(screen.getByRole('link', { name: 'General' })).toHaveAttribute('aria-current', 'page')
+  })
+
+  it('collapses and expands a group on heading click', () => {
+    render(<GroupedNav items={items} activeHref="/" />)
+    expect(screen.getByText('Weekly Briefs')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /Content/ }))
+    expect(screen.queryByText('Weekly Briefs')).not.toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /Content/ }))
+    expect(screen.getByText('Weekly Briefs')).toBeInTheDocument()
+  })
+
+  it('forces a collapsed group open when one of its children is active', () => {
+    const collapsed: GroupedNavEntry[] = [
+      { label: 'Content', defaultOpen: false, items: [{ href: '/t/general', label: 'General' }] },
+    ]
+    render(<GroupedNav items={collapsed} activeHref="/t/general" />)
+    // defaultOpen=false but the active child forces it visible
+    expect(screen.getByText('General')).toBeInTheDocument()
+  })
+
+  it('uses a custom renderLink (e.g. a router Link)', () => {
+    render(
+      <GroupedNav
+        items={items}
+        activeHref="/"
+        renderLink={({ link, active, className }) => (
+          <a href={link.href} className={className} data-active={active} data-router-link="1">
+            {link.label}
+          </a>
+        )}
+      />,
+    )
+    const link = screen.getByText('Weekly Briefs')
+    expect(link).toHaveAttribute('data-router-link', '1')
+  })
+})