@startsimpli/ui 0.4.50 → 0.4.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.50",
+  "version": "0.4.51",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -40,8 +40,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/auth": "0.4.29",
-    "@startsimpli/api": "0.5.44"
+    "@startsimpli/api": "0.5.44",
+    "@startsimpli/auth": "0.4.29"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/catalog/catalog.ts

@@ -74,6 +74,52 @@ export const UI_CATALOG: CatalogEntry[] = [
     source: { export: 'KanbanBoard', from: '@startsimpli/ui' },
     configExample: { kind: 'kanban-board', type: '<typeKey>', title: 'Board' },
   },
+  {
+    id: 'pipeline-health',
+    category: 'widget',
+    title: 'Pipeline health',
+    description:
+      'A compact health card for one status type: how many records sit in each stage, plus a stuck/aging flag that pulls the card to a warning tone. Use on a system-health home to bubble up a content type\'s throughput at a glance (the pipeline funnel shows conversion; this shows health).',
+    dataNeeds: 'A type with a status/enum field.',
+    source: { export: 'PipelineHealth', from: '@startsimpli/ui' },
+    configExample: { kind: 'pipeline-health', type: '<typeKey>', title: 'Pipeline health' },
+  },
+  {
+    id: 'source-freshness',
+    category: 'widget',
+    title: 'Source freshness',
+    description:
+      'A health card listing upstream sources as fresh vs stale by their last-updated time — any stale feed pulls the card to a warning. Use to prove ongoing ingestion is actually flowing (a stale source is a bug, not coverage).',
+    dataNeeds: 'A type whose records carry a last-updated / last-fetched timestamp.',
+    source: { export: 'SourceFreshness', from: '@startsimpli/ui' },
+    configExample: { kind: 'source-freshness', type: '<typeKey>', title: 'Source freshness' },
+  },
+  {
+    id: 'delivery-health',
+    category: 'widget',
+    title: 'Delivery health',
+    description:
+      'A health card for scheduled deliverables: on-time / late / missed / upcoming counts derived from a type\'s scheduled and delivered date fields. Use for recurring outputs like weekly briefs.',
+    dataNeeds: 'A type with a scheduled-date and a delivered-date field.',
+    source: { export: 'DeliveryHealth', from: '@startsimpli/ui' },
+    configExample: {
+      kind: 'delivery-health',
+      type: '<typeKey>',
+      scheduledField: '<scheduled>',
+      deliveredField: '<delivered>',
+      title: 'Delivery',
+    },
+  },
+  {
+    id: 'attention',
+    category: 'widget',
+    title: 'Needs attention',
+    description:
+      'A cross-type queue of records that need a human — stuck records, drafts awaiting review. Empty is the healthy state. Use as the "what should I look at" panel on a system-health home.',
+    dataNeeds: 'Any types (flags records by status / age).',
+    source: { export: 'AttentionFeed', from: '@startsimpli/ui' },
+    configExample: { kind: 'attention', limit: 8, title: 'Needs attention' },
+  },
   {
     id: 'data-table',
     category: 'view',

package/src/components/health/AttentionFeed.tsx

@@ -0,0 +1,95 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { Inbox } from 'lucide-react'
+import { formatRelativeTime } from '../../utils'
+import { HealthCard, HealthDot } from './HealthCard'
+import { worstStatus, type HealthStatus } from './health-status'
+
+export interface AttentionItem {
+  id: string
+  label: string
+  /** Optional context line, e.g. "Weekly brief · awaiting review". */
+  meta?: string
+  /** Link target; when set the row is a link. */
+  href?: string
+  /** Row tone (default warn — it's in the attention queue for a reason). */
+  tone?: HealthStatus
+  /** Timestamp shown as relative time on the right. */
+  at?: string | Date | null
+}
+
+export interface AttentionFeedProps {
+  title?: string
+  items: AttentionItem[]
+  limit?: number
+  emptyMessage?: string
+  className?: string
+}
+
+/**
+ * The "needs a human" queue: records flagged for review across every type. Empty
+ * is the healthy state (all clear); anything in the queue pulls the card to warn
+ * (or worse, per item tone). Presentational — a tenant widget collects the items
+ * from whatever it considers actionable (stuck records, drafts awaiting review…).
+ */
+export function AttentionFeed({
+  title = 'Needs attention',
+  items,
+  limit,
+  emptyMessage = 'All clear — nothing needs review.',
+  className,
+}: AttentionFeedProps) {
+  const status: HealthStatus =
+    items.length === 0 ? 'ok' : worstStatus(items.map((it) => it.tone ?? 'warn'))
+  const statusLabel = items.length === 0 ? 'All clear' : `${items.length} to review`
+  const listed = limit ? items.slice(0, limit) : items
+
+  return (
+    <HealthCard
+      title={title}
+      status={status}
+      statusLabel={statusLabel}
+      icon={Inbox}
+      isEmpty={items.length === 0}
+      emptyMessage={emptyMessage}
+      className={className}
+    >
+      <ul className="divide-y divide-gray-100" aria-label={`${title} items`}>
+        {listed.map((item) => {
+          const body = (
+            <span className="flex items-start justify-between gap-3 py-2">
+              <span className="flex items-start gap-2 min-w-0">
+                <HealthDot status={item.tone ?? 'warn'} className="mt-1.5" />
+                <span className="min-w-0">
+                  <span className="block text-sm text-gray-900 truncate">{item.label}</span>
+                  {item.meta && <span className="block text-xs text-gray-500 truncate">{item.meta}</span>}
+                </span>
+              </span>
+              {item.at && (
+                <span className="text-xs text-gray-400 tabular-nums flex-shrink-0 pt-0.5">
+                  {formatRelativeTime(item.at)}
+                </span>
+              )}
+            </span>
+          )
+          return (
+            <li key={item.id}>
+              {item.href ? (
+                <a
+                  href={item.href}
+                  className={cn(
+                    'block rounded px-1 -mx-1 hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-primary-500',
+                  )}
+                >
+                  {body}
+                </a>
+              ) : (
+                body
+              )}
+            </li>
+          )
+        })}
+      </ul>
+    </HealthCard>
+  )
+}

package/src/components/health/DeliveryHealth.tsx

@@ -0,0 +1,127 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { CalendarClock } from 'lucide-react'
+import { formatRelativeTime } from '../../utils'
+import { HealthCard, HealthDot } from './HealthCard'
+import { worstStatus, type HealthStatus } from './health-status'
+
+export type DeliveryState = 'on_time' | 'upcoming' | 'late' | 'missed'
+
+export interface DeliveryItem {
+  label: string
+  /** Explicit state; otherwise derived from due/delivered vs now. */
+  status?: DeliveryState
+  dueAt?: string | Date | null
+  deliveredAt?: string | Date | null
+}
+
+export interface DeliveryHealthProps {
+  title?: string
+  items: DeliveryItem[]
+  /** Compare against this instant (injectable for tests); defaults to Date.now(). */
+  now?: number
+  /** Cap the number of rows listed (summary counts still cover all). */
+  limit?: number
+  emptyMessage?: string
+  className?: string
+}
+
+const STATE_TONE: Record<DeliveryState, HealthStatus> = {
+  on_time: 'ok',
+  upcoming: 'neutral',
+  late: 'warn',
+  missed: 'critical',
+}
+
+const STATE_LABEL: Record<DeliveryState, string> = {
+  on_time: 'On time',
+  upcoming: 'Upcoming',
+  late: 'Late',
+  missed: 'Missed',
+}
+
+function deriveState(item: DeliveryItem, now: number): DeliveryState {
+  if (item.status) return item.status
+  const due = item.dueAt ? new Date(item.dueAt).getTime() : null
+  if (item.deliveredAt) {
+    const delivered = new Date(item.deliveredAt).getTime()
+    return due !== null && delivered > due ? 'late' : 'on_time'
+  }
+  if (due === null) return 'upcoming'
+  return due < now ? 'missed' : 'upcoming'
+}
+
+/**
+ * Delivery / schedule health: were scheduled deliverables (e.g. weekly briefs)
+ * shipped on time? Missed/late deliveries drive the card critical/warn; upcoming
+ * ones are informational. Presentational — a tenant widget derives states from a
+ * type's scheduled_for / delivered_at fields.
+ */
+export function DeliveryHealth({
+  title = 'Delivery',
+  items,
+  now,
+  limit,
+  emptyMessage = 'Nothing scheduled.',
+  className,
+}: DeliveryHealthProps) {
+  const at = now ?? Date.now()
+  const rows = items.map((it) => ({ ...it, state: deriveState(it, at) }))
+  const counts = rows.reduce(
+    (acc, r) => ((acc[r.state] += 1), acc),
+    { on_time: 0, upcoming: 0, late: 0, missed: 0 } as Record<DeliveryState, number>,
+  )
+  const status = worstStatus(rows.map((r) => STATE_TONE[r.state]))
+  const problems = counts.late + counts.missed
+  const statusLabel =
+    items.length === 0 ? undefined : problems > 0 ? `${problems} off-track` : 'On track'
+
+  const listed = limit ? rows.slice(0, limit) : rows
+
+  return (
+    <HealthCard
+      title={title}
+      status={status}
+      statusLabel={statusLabel}
+      icon={CalendarClock}
+      isEmpty={items.length === 0}
+      emptyMessage={emptyMessage}
+      className={className}
+    >
+      <div className="flex flex-wrap gap-x-4 gap-y-1 text-xs text-gray-600">
+        {(['on_time', 'late', 'missed', 'upcoming'] as DeliveryState[])
+          .filter((s) => counts[s] > 0)
+          .map((s) => (
+            <span key={s} className="inline-flex items-center gap-1.5">
+              <HealthDot status={STATE_TONE[s]} />
+              <span className="tabular-nums font-medium text-gray-900">{counts[s]}</span> {STATE_LABEL[s]}
+            </span>
+          ))}
+      </div>
+
+      <ul className="space-y-2" aria-label={`${title} items`}>
+        {listed.map((row, i) => (
+          <li key={`${row.label}-${i}`} className="flex items-center justify-between gap-3 text-sm">
+            <span className="flex items-center gap-2 min-w-0">
+              <HealthDot status={STATE_TONE[row.state]} />
+              <span className="text-gray-700 truncate">{row.label}</span>
+            </span>
+            <span
+              className={cn(
+                'text-xs tabular-nums flex-shrink-0',
+                STATE_TONE[row.state] === 'ok' ? 'text-gray-500' : 'text-gray-900 font-medium',
+              )}
+            >
+              {STATE_LABEL[row.state]}
+              {row.deliveredAt
+                ? ` · ${formatRelativeTime(row.deliveredAt)}`
+                : row.dueAt
+                  ? ` · ${formatRelativeTime(row.dueAt)}`
+                  : ''}
+            </span>
+          </li>
+        ))}
+      </ul>
+    </HealthCard>
+  )
+}

package/src/components/health/HealthCard.tsx

@@ -0,0 +1,108 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { HEALTH_TONE, type HealthStatus } from './health-status'
+
+/** A small solid status dot. Pair it with a label — never rely on color alone. */
+export function HealthDot({ status, className }: { status: HealthStatus; className?: string }) {
+  return (
+    <span
+      className={cn('inline-block w-2.5 h-2.5 rounded-full flex-shrink-0', HEALTH_TONE[status].dot, className)}
+      aria-hidden="true"
+    />
+  )
+}
+
+/** A tone pill: icon + label, used in a HealthCard header to name the roll-up state. */
+export function HealthBadge({
+  status,
+  label,
+  className,
+}: {
+  status: HealthStatus
+  label?: string
+  className?: string
+}) {
+  const tone = HEALTH_TONE[status]
+  const Icon = tone.Icon
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1.5 rounded-full px-2.5 py-0.5 text-xs font-medium',
+        tone.softBg,
+        tone.text,
+        className,
+      )}
+    >
+      <Icon className="w-3.5 h-3.5" aria-hidden="true" />
+      {label ?? tone.label}
+    </span>
+  )
+}
+
+export interface HealthCardProps {
+  /** Card heading. */
+  title: string
+  /** The rolled-up tone — drives the left accent + the header badge. */
+  status: HealthStatus
+  /** Optional short label overriding the tone's default badge text (e.g. "3 stale"). */
+  statusLabel?: string
+  /** Optional leading icon for the title. */
+  icon?: React.ComponentType<{ className?: string }>
+  /** Optional right-aligned header slot (a link, a period selector…). */
+  action?: React.ReactNode
+  /** Body — the signal-specific content. */
+  children?: React.ReactNode
+  /** Shown (muted, centered) when there is nothing to report. */
+  emptyMessage?: string
+  /** Render the empty state instead of children. */
+  isEmpty?: boolean
+  isLoading?: boolean
+  className?: string
+}
+
+/**
+ * The base surface every SystemHealth block renders into: a titled card with a
+ * left tone-accent and a status badge, so a wall of them reads as a scannable
+ * health board. Presentational only — the tone + contents are computed by the
+ * composer (or, in a tenant app, by the dashboard widget that fetches the data).
+ */
+export function HealthCard({
+  title,
+  status,
+  statusLabel,
+  icon: Icon,
+  action,
+  children,
+  emptyMessage = 'Nothing to report.',
+  isEmpty,
+  isLoading,
+  className,
+}: HealthCardProps) {
+  return (
+    <div
+      className={cn(
+        'rounded-xl border border-l-4 bg-card text-card-foreground shadow p-5 space-y-4',
+        HEALTH_TONE[status].border,
+        isLoading && 'animate-pulse',
+        className,
+      )}
+    >
+      <div className="flex items-center justify-between gap-3">
+        <div className="flex items-center gap-2 min-w-0">
+          {Icon && <Icon className="w-4 h-4 text-gray-400 flex-shrink-0" aria-hidden="true" />}
+          <h3 className="text-sm font-semibold text-gray-900 truncate">{title}</h3>
+        </div>
+        <div className="flex items-center gap-2 flex-shrink-0">
+          {action}
+          <HealthBadge status={status} label={statusLabel} />
+        </div>
+      </div>
+
+      {isEmpty ? (
+        <p className="text-sm text-gray-500 py-4 text-center">{emptyMessage}</p>
+      ) : (
+        children
+      )}
+    </div>
+  )
+}

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')
+  })
+})

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

@@ -0,0 +1,192 @@
+'use client'
+
+import * as React from 'react'
+import { useState } from 'react'
+import { ChevronDown } from 'lucide-react'
+import { cn } from '../../lib/utils'
+
+export interface GroupedNavLink {
+  href: string
+  label: string
+  icon?: React.ReactNode
+  /** Optional trailing slot (count pill, status dot…). */
+  badge?: React.ReactNode
+}
+
+export interface GroupedNavGroup {
+  label: string
+  icon?: React.ReactNode
+  items: GroupedNavLink[]
+  /** Start expanded (default true). Ignored while a child is active — then forced open. */
+  defaultOpen?: boolean
+  /** Show a chevron toggle (default true). false = a static section heading. */
+  collapsible?: boolean
+}
+
+/** A top-level link, or a named group of links. Discriminated by `items`. */
+export type GroupedNavEntry = GroupedNavLink | GroupedNavGroup
+
+export interface GroupedNavRenderLinkArgs {
+  link: GroupedNavLink
+  active: boolean
+  className: string
+  /** The pre-composed inner content (icon + label + badge). */
+  content: React.ReactNode
+}
+
+export interface GroupedNavProps {
+  items: GroupedNavEntry[]
+  /** The current path; drives active state. */
+  activeHref?: string
+  /** Override active matching (default: exact, or `activeHref` under `href/`). */
+  isActive?: (href: string, activeHref?: string) => boolean
+  /**
+   * Render a link — pass `next/link` here in a Next app. Default renders a plain
+   * `<a>` so the primitive stays framework-agnostic.
+   */
+  renderLink?: (args: GroupedNavRenderLinkArgs) => React.ReactNode
+  className?: string
+}
+
+function isGroup(entry: GroupedNavEntry): entry is GroupedNavGroup {
+  return Array.isArray((entry as GroupedNavGroup).items)
+}
+
+function defaultIsActive(href: string, activeHref?: string): boolean {
+  if (!activeHref) return false
+  if (href === '/') return activeHref === '/'
+  return activeHref === href || activeHref.startsWith(href + '/')
+}
+
+const defaultRenderLink = ({ link, active, className, content }: GroupedNavRenderLinkArgs) => (
+  <a href={link.href} className={className} aria-current={active ? 'page' : undefined}>
+    {content}
+  </a>
+)
+
+function linkClasses(active: boolean, indented: boolean) {
+  return cn(
+    'flex items-center gap-3 px-3 py-2 rounded-md text-sm font-medium transition-colors',
+    indented && 'pl-9',
+    active
+      ? 'bg-primary-600 text-white'
+      : 'text-gray-700 hover:bg-gray-100 hover:text-gray-900',
+  )
+}
+
+/**
+ * A grouped sidebar navigation list: a mix of top-level links and collapsible
+ * groups (e.g. Dashboard + a "Content" group of the three content types). Purely
+ * the `<nav>` list — the app shell owns the logo, user footer, and chrome. Active
+ * state and link rendering are injectable so it drops into any router.
+ */
+export function GroupedNav({
+  items,
+  activeHref,
+  isActive = defaultIsActive,
+  renderLink = defaultRenderLink,
+  className,
+}: GroupedNavProps) {
+  return (
+    <nav className={cn('space-y-1', className)} aria-label="Primary">
+      {items.map((entry, idx) =>
+        isGroup(entry) ? (
+          <NavGroup
+            key={`group-${entry.label}-${idx}`}
+            group={entry}
+            activeHref={activeHref}
+            isActive={isActive}
+            renderLink={renderLink}
+          />
+        ) : (
+          <NavLinkRow
+            key={entry.href}
+            link={entry}
+            active={isActive(entry.href, activeHref)}
+            indented={false}
+            renderLink={renderLink}
+          />
+        ),
+      )}
+    </nav>
+  )
+}
+
+function NavLinkRow({
+  link,
+  active,
+  indented,
+  renderLink,
+}: {
+  link: GroupedNavLink
+  active: boolean
+  indented: boolean
+  renderLink: NonNullable<GroupedNavProps['renderLink']>
+}) {
+  const content = (
+    <>
+      {link.icon ? <span className="flex-shrink-0 w-5 h-5 flex items-center justify-center">{link.icon}</span> : null}
+      <span className="flex-1 truncate">{link.label}</span>
+      {link.badge ? <span className="flex-shrink-0">{link.badge}</span> : null}
+    </>
+  )
+  return <>{renderLink({ link, active, className: linkClasses(active, indented), content })}</>
+}
+
+function NavGroup({
+  group,
+  activeHref,
+  isActive,
+  renderLink,
+}: {
+  group: GroupedNavGroup
+  activeHref?: string
+  isActive: NonNullable<GroupedNavProps['isActive']>
+  renderLink: NonNullable<GroupedNavProps['renderLink']>
+}) {
+  const collapsible = group.collapsible ?? true
+  const hasActiveChild = group.items.some((l) => isActive(l.href, activeHref))
+  const [open, setOpen] = useState(group.defaultOpen ?? true)
+  const expanded = hasActiveChild || open
+
+  const links = expanded
+    ? group.items.map((link) => (
+        <NavLinkRow
+          key={link.href}
+          link={link}
+          active={isActive(link.href, activeHref)}
+          indented
+          renderLink={renderLink}
+        />
+      ))
+    : null
+
+  const heading = (
+    <span className="flex items-center gap-2 min-w-0">
+      {group.icon ? <span className="flex-shrink-0 w-5 h-5 flex items-center justify-center">{group.icon}</span> : null}
+      <span className="text-xs font-semibold text-gray-400 uppercase tracking-wider truncate">{group.label}</span>
+    </span>
+  )
+
+  return (
+    <div className="pt-3 first:pt-0">
+      {collapsible ? (
+        <button
+          type="button"
+          onClick={() => setOpen((o) => !o)}
+          aria-expanded={expanded}
+          className="w-full flex items-center justify-between gap-2 px-3 py-1.5 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-primary-500"
+        >
+          {heading}
+          <ChevronDown
+            className={cn('w-4 h-4 text-gray-400 transition-transform flex-shrink-0', expanded ? '' : '-rotate-90')}
+            aria-hidden="true"
+          />
+        </button>
+      ) : (
+        <div className="px-3 py-1.5">{heading}</div>
+      )}
+      {links && <div className="mt-1 space-y-1">{links}</div>}
+    </div>
+  )
+}