@hanzo/dashboard 0.2.0 → 0.2.2

package/src/overview/primitives.tsx

@@ -0,0 +1,306 @@
+'use client'
+
+/**
+ * Composable dashboard primitives — the small, honest building blocks a consumer
+ * mixes directly (without the full `Overview` driver): `Kpi` (an animated stat
+ * tile), `Feed` (a virtualized activity stream), `Board` (a service-health board),
+ * plus the shared `Panel`/`SkeletonBar`/`EmptyPanel`/`PanelSpinner` chrome.
+ *
+ * Every primitive is driven by direct props (data in, view out) and is honest by
+ * construction: a null/absent value renders an em-dash, a <2-point series draws no
+ * trend, reduced motion snaps to the end state. Style props are the @hanzo/gui v5
+ * shorthand set; raw/SVG colors go through inline `style`.
+ */
+import { useMemo, useRef, useState, type ReactNode } from 'react'
+import { Card, Spinner, Text, XStack, YStack } from '@hanzo/gui'
+import { Clock, TrendingDown, TrendingUp } from '@hanzogui/lucide-icons-2'
+
+import { CHART_PALETTE, Sparkline } from '../charts/Charts'
+import { useCountUp, useReducedMotion } from '../motion/hooks'
+import { ago, formatMetric, hasTrend, healthColor, healthTally, statusColor, windowRows, worstHealth, OK, MUTED } from './logic'
+import type { MetricUnit, OverviewEvent, OverviewHealth } from './config'
+import type { IconComponent } from '../types'
+
+const UP = '#23c562'
+const DOWN = '#ff5d8f'
+
+// ── Kpi (count-up stat tile + optional live sparkline + delta) ───────────────
+
+export interface KpiProps {
+  label: string
+  /** The value; `null`/`undefined` → an honest em-dash (backend doesn't report it). */
+  value: number | null | undefined
+  unit?: MetricUnit
+  /** Signed ±% vs the prior window; `null`/`undefined` → honest "— vs prior". */
+  deltaPct?: number | null
+  /** A recent dense series for the sparkline (≥2 finite points, else omitted). */
+  series?: number[]
+  icon?: IconComponent
+  /** Sparkline accent (defaults to the palette head). */
+  color?: string
+  /** A small caption under the value. */
+  caption?: string
+  /** Count the value up on change (respects reduced motion). Default true. */
+  animate?: boolean
+  /** Show the loading skeleton for the value + delta. */
+  loading?: boolean
+}
+
+/** An animated KPI / stat tile — the canonical dashboard number. */
+export function Kpi({ label, value, unit, deltaPct, series, icon: Icon, color, caption, animate = true, loading = false }: KpiProps) {
+  const reduced = useReducedMotion()
+  const finite = value != null && Number.isFinite(value)
+  const target = finite ? (value as number) : 0
+  const shown = useCountUp(target, animate && !reduced && finite)
+  const accent = color ?? CHART_PALETTE[0]
+
+  return (
+    // Responsive KPI columns so a 4-card row balances instead of wrapping 3+1: one
+    // column on phones, two from md, four from xl. flexGrow equalizes the widths.
+    <Card
+      borderWidth={1}
+      borderColor="$borderColor"
+      p="$4"
+      gap="$2"
+      flexGrow={1}
+      flexShrink={1}
+      flexBasis="100%"
+      $md={{ flexBasis: '48%' }}
+      $xl={{ flexBasis: '22%' }}
+      minW={200}
+    >
+      <XStack items="center" gap="$2">
+        {Icon ? <Icon size={15} opacity={0.7} /> : null}
+        <Text fontSize="$2" color="$color10" numberOfLines={1}>
+          {label}
+        </Text>
+      </XStack>
+
+      {loading && !finite ? (
+        <SkeletonBar w={110} h={34} />
+      ) : (
+        <Text fontSize="$9" fontWeight="500" color={finite ? '$color12' : '$color10'} numberOfLines={1} className="tnum">
+          {finite ? formatMetric(shown, unit) : '—'}
+        </Text>
+      )}
+
+      <XStack justify="space-between" items="flex-end" gap="$2">
+        <YStack gap="$1">
+          {caption ? (
+            <Text fontSize="$1" color="$color10" numberOfLines={1}>
+              {caption}
+            </Text>
+          ) : null}
+          <DeltaPill pct={deltaPct ?? null} loading={loading && !finite} />
+        </YStack>
+        {hasTrend(series) ? <Sparkline values={series!} color={accent} /> : null}
+      </XStack>
+    </Card>
+  )
+}
+
+function DeltaPill({ pct, loading }: { pct: number | null; loading: boolean }) {
+  if (loading) return <SkeletonBar w={80} h={12} />
+  if (pct == null || !Number.isFinite(pct)) {
+    return (
+      <Text fontSize="$1" color="$color10">
+        — vs prior
+      </Text>
+    )
+  }
+  const up = pct >= 0
+  const Icon = up ? TrendingUp : TrendingDown
+  const color = up ? UP : DOWN
+  return (
+    <XStack items="center" gap="$1">
+      <Icon size={12} color={color} />
+      <Text fontSize="$1" fontWeight="700" style={{ color }}>
+        {`${up ? '+' : ''}${Math.round(pct)}%`}
+      </Text>
+      <Text fontSize="$1" color="$color10">
+        vs prior
+      </Text>
+    </XStack>
+  )
+}
+
+// ── Feed (virtualized live activity stream) ──────────────────────────────────
+
+const ROW_H = 52
+const VIEWPORT_H = 360
+
+export interface FeedProps {
+  items: OverviewEvent[]
+  title?: string
+  empty?: string
+  loading?: boolean
+}
+
+/** A live activity stream — newest rows on top, virtualized past a viewport. */
+export function Feed({ items, title = 'Live activity', empty = 'No activity in this range yet.', loading = false }: FeedProps) {
+  const [scrollTop, setScrollTop] = useState(0)
+  const nowRef = useRef(Date.now())
+  nowRef.current = Date.now()
+  const rows = items ?? []
+  // Virtualize only when the stream is long; small feeds render whole (no scroll jank).
+  const virtualize = rows.length > Math.ceil(VIEWPORT_H / ROW_H)
+  const win = useMemo(() => windowRows(rows, scrollTop, ROW_H, VIEWPORT_H), [rows, scrollTop])
+
+  return (
+    <Panel title={title} right={<LiveDot on={!loading && rows.length > 0} />}>
+      {loading && rows.length === 0 ? (
+        <YStack gap="$2">
+          {[0, 1, 2, 3].map((i) => (
+            <SkeletonBar key={i} w="100%" h={ROW_H - 12} />
+          ))}
+        </YStack>
+      ) : rows.length === 0 ? (
+        <EmptyPanel note={empty} />
+      ) : virtualize ? (
+        <div style={{ height: VIEWPORT_H, overflowY: 'auto' }} onScroll={(e) => setScrollTop((e.target as HTMLDivElement).scrollTop)}>
+          <div style={{ height: win.padTop }} />
+          {win.slice.map((e) => (
+            <FeedRow key={e.id || `${e.time}-${e.title}`} title={e.title} subtitle={e.subtitle} status={e.status} when={ago(e.time, nowRef.current)} />
+          ))}
+          <div style={{ height: win.padBottom }} />
+        </div>
+      ) : (
+        <YStack>
+          {rows.map((e) => (
+            <FeedRow key={e.id || `${e.time}-${e.title}`} title={e.title} subtitle={e.subtitle} status={e.status} when={ago(e.time, nowRef.current)} />
+          ))}
+        </YStack>
+      )}
+    </Panel>
+  )
+}
+
+function FeedRow({ title, subtitle, status, when }: { title: string; subtitle?: string; status: string; when: string }) {
+  return (
+    <XStack items="center" gap="$3" py="$2.5" borderBottomWidth={1} borderColor="$borderColor" style={{ height: ROW_H }}>
+      <YStack width={8} height={8} rounded="$10" style={{ backgroundColor: statusColor(status) }} />
+      <YStack flex={1}>
+        <Text fontSize="$3" color="$color12" numberOfLines={1}>
+          {title || 'Event'}
+        </Text>
+        {subtitle ? (
+          <Text fontSize="$1" color="$color10" numberOfLines={1}>
+            {subtitle}
+          </Text>
+        ) : null}
+      </YStack>
+      <XStack items="center" gap="$1.5">
+        <Clock size={12} opacity={0.6} />
+        <Text fontSize="$2" color="$color11">
+          {when}
+        </Text>
+      </XStack>
+    </XStack>
+  )
+}
+
+// ── Board (service-health board) ─────────────────────────────────────────────
+
+export interface BoardProps {
+  items: OverviewHealth[]
+  title?: string
+  empty?: string
+  loading?: boolean
+}
+
+/** A service-health board — a healthy/total header + per-service dots. */
+export function Board({ items, title = 'System health', empty = 'Health is reported once the control plane is reachable.', loading = false }: BoardProps) {
+  const rows = items ?? []
+  const worst = worstHealth(rows)
+  const { healthy, total } = healthTally(rows)
+  const headColor = worst === 'red' ? DOWN : worst === 'yellow' ? '#f0a868' : worst === 'green' ? OK : MUTED
+
+  return (
+    <Panel
+      title={title}
+      right={
+        total > 0 ? (
+          <XStack items="center" gap="$2">
+            <YStack width={9} height={9} rounded="$10" style={{ backgroundColor: headColor }} />
+            <Text fontSize="$2" color="$color10">
+              {healthy}/{total} healthy
+            </Text>
+          </XStack>
+        ) : undefined
+      }
+    >
+      {loading && rows.length === 0 ? (
+        <SkeletonBar w="100%" h={40} />
+      ) : rows.length === 0 ? (
+        <EmptyPanel note={empty} />
+      ) : (
+        <XStack flexWrap="wrap" gap="$2">
+          {rows.map((r) => (
+            <XStack key={r.service} items="center" gap="$2" bg="$color2" px="$2.5" py="$1.5" rounded="$10" borderWidth={1} borderColor="$borderColor">
+              <YStack width={8} height={8} rounded="$10" style={{ backgroundColor: healthColor(r.health) }} />
+              <Text fontSize="$2" color="$color11" numberOfLines={1}>
+                {r.service}
+              </Text>
+            </XStack>
+          ))}
+        </XStack>
+      )}
+    </Panel>
+  )
+}
+
+// ── shared chrome ────────────────────────────────────────────────────────────
+
+/** A titled panel shell — the ONE section container across the dashboard. */
+export function Panel({ title, right, children, minW = 320, flex }: { title: string; right?: ReactNode; children: ReactNode; minW?: number; flex?: number }) {
+  return (
+    <Card borderWidth={1} borderColor="$borderColor" p="$4" gap="$3" flex={flex} minW={minW}>
+      <XStack items="center" justify="space-between" gap="$2">
+        <Text fontSize="$4" fontWeight="500" color="$color12">
+          {title}
+        </Text>
+        {right}
+      </XStack>
+      {children}
+    </Card>
+  )
+}
+
+/** A pulsing "live" indicator (steady dot under reduced motion). */
+export function LiveDot({ on }: { on: boolean }) {
+  const reduced = useReducedMotion()
+  if (!on) return null
+  return (
+    <XStack items="center" gap="$1.5">
+      <YStack width={7} height={7} rounded="$10" style={{ backgroundColor: OK, animation: reduced ? undefined : 'pulse 1.6s ease-in-out infinite' }} />
+      <Text fontSize="$1" color="$color10">
+        Live
+      </Text>
+    </XStack>
+  )
+}
+
+/** A shimmer skeleton block (honest "loading", not fabricated content). */
+export function SkeletonBar({ w, h, rounded }: { w: number | string; h: number; rounded?: boolean }) {
+  return <div className="skeleton" style={{ width: w, height: h, borderRadius: rounded ? '50%' : 8 }} aria-hidden />
+}
+
+/** An honest empty-state note inside a panel. */
+export function EmptyPanel({ note }: { note: string }) {
+  return (
+    <YStack p="$5" items="center" gap="$1">
+      <Text fontSize="$3" color="$color11">
+        {note}
+      </Text>
+    </YStack>
+  )
+}
+
+/** A loading spinner centered in a panel (used by the driver's first paint). */
+export function PanelSpinner() {
+  return (
+    <XStack p="$6" justify="center">
+      <Spinner size="large" color="$color11" />
+    </XStack>
+  )
+}

package/src/overview/superadmin.test.ts

@@ -0,0 +1,36 @@
+// The dashboard decides no authority. SuperAdmin is the HOST's verdict (the server's
+// `isSuperAdmin`, or @hanzo/iam `superAdmin(claims)` — a person whose home org is the
+// reserved `admin` org), and the overview only carries it to the product's loader
+// under that one name, so a loader can skip a fleet aggregate the viewer would be
+// refused. These hold the package to that: no predicate of its own, one name.
+import { describe, expect, test } from 'bun:test'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SRC = join(import.meta.dir, '..')
+
+function sources(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const p = join(dir, name)
+    if (statSync(p).isDirectory()) return sources(p)
+    return /\.(ts|tsx)$/.test(name) && !/\.test\.tsx?$/.test(name) ? [p] : []
+  })
+}
+
+describe('SuperAdmin in @hanzo/dashboard', () => {
+  test('the overview hands the loader the host verdict as superAdmin', () => {
+    const overview = readFileSync(join(SRC, 'overview', 'Overview.tsx'), 'utf8')
+    expect(overview).toMatch(/superAdmin = false \}: \{ config: OverviewConfig; allOrgs\?: boolean; superAdmin\?: boolean \}/)
+    expect(overview).toContain('.load({ range, allOrgs, superAdmin })')
+    const config = readFileSync(join(SRC, 'overview', 'config.ts'), 'utf8')
+    expect(config).toMatch(/\n  superAdmin\?: boolean\n/)
+  })
+
+  test('no source decides SuperAdmin itself or names it another way', () => {
+    for (const file of sources(SRC)) {
+      const text = readFileSync(file, 'utf8')
+      expect({ file, hit: /isGlobalAdmin|global[ -]admin/i.test(text) }).toEqual({ file, hit: false })
+      expect({ file, hit: /owner\s*===?\s*['"]admin['"]|orgs\?*\.?\[0\]/.test(text) }).toEqual({ file, hit: false })
+    }
+  })
+})

package/src/overview/tiles.tsx

@@ -0,0 +1,223 @@
+'use client'
+
+/**
+ * Overview tiles — the config-tile adapters that select a slice out of the
+ * normalized `OverviewData` and render the matching primitive. Thin by design:
+ * the presentation lives in the composable primitives (`Kpi`/`Feed`/`Board`) and
+ * the charts (`Line`/`Columns`/`Donut`); these adapters only pick the slice and
+ * hand it over. `Tile` routes a declared tile spec to its adapter (exhaustive on
+ * the `tile` discriminant), which is what the `Overview` driver renders per row.
+ */
+import { Text, XStack, YStack } from '@hanzo/gui'
+
+import { CHART_OTHER, CHART_PALETTE, Columns, Donut, Line, type ChartPoint, type Slice } from '../charts/Charts'
+import { Board, EmptyPanel, Feed, Kpi, Panel, SkeletonBar } from './primitives'
+import {
+  deltaOf,
+  distributionTotal,
+  formatMetric,
+  selectDistribution,
+  selectKpi,
+  selectSeries,
+  severityColor,
+  OK,
+} from './logic'
+import type {
+  ActivityTile,
+  AlertsTile,
+  DistributionTile,
+  HealthTile,
+  MetricTile,
+  OverviewData,
+  OverviewTile,
+  TimeseriesTile,
+} from './config'
+
+/** Format an axis label for a series interval. */
+const fmtAxis = (iso: string, interval: string): string => {
+  const d = new Date(iso)
+  if (Number.isNaN(d.getTime())) return iso
+  return interval === 'day'
+    ? d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+    : d.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' })
+}
+
+// ── Metric tile → Kpi ────────────────────────────────────────────────────────
+
+export function MetricTileView({ tile, data, loading, live, index }: { tile: MetricTile; data: OverviewData | null; loading: boolean; live: boolean; index: number }) {
+  const kpi = data ? selectKpi(data, tile.key) : undefined
+  const delta = deltaOf(kpi)
+  return (
+    <Kpi
+      label={tile.label}
+      icon={tile.icon}
+      unit={tile.unit}
+      caption={tile.caption}
+      color={tile.color ?? CHART_PALETTE[index % CHART_PALETTE.length]}
+      value={kpi === undefined ? null : kpi.value}
+      deltaPct={delta ? delta.pct : null}
+      series={kpi?.series}
+      animate={live}
+      loading={loading && kpi === undefined}
+    />
+  )
+}
+
+// ── Timeseries tile → Line / Columns ─────────────────────────────────────────
+
+export function TimeseriesTileView({ tile, data, loading }: { tile: TimeseriesTile; data: OverviewData | null; loading: boolean }) {
+  const series = data ? selectSeries(data, tile.key) : undefined
+  const points: ChartPoint[] = (series?.points ?? []).map((p) => ({ label: fmtAxis(p.t, series?.interval ?? 'day'), value: p.value }))
+  const fmt = (v: number) => formatMetric(v, tile.unit)
+  const total = points.reduce((s, p) => s + p.value, 0)
+
+  return (
+    <Panel title={tile.title} flex={1} right={points.length ? <Text fontSize="$2" color="$color10" className="tnum">{fmt(total)}</Text> : undefined}>
+      {loading && series === undefined ? (
+        <SkeletonBar w="100%" h={200} />
+      ) : points.length < 2 ? (
+        <EmptyPanel note="Not enough data in this range yet." />
+      ) : tile.kind === 'bar' ? (
+        <Columns data={points} color={CHART_PALETTE[1]} formatValue={fmt} />
+      ) : (
+        <Line data={points} color={CHART_PALETTE[0]} formatValue={fmt} />
+      )}
+    </Panel>
+  )
+}
+
+// ── Distribution tile → Donut + legend ───────────────────────────────────────
+
+export function DistributionTileView({ tile, data, loading }: { tile: DistributionTile; data: OverviewData | null; loading: boolean }) {
+  const raw = data ? selectDistribution(data, tile.key) : []
+  const total = distributionTotal(raw)
+  const slices: Slice[] = raw
+    .filter((s) => s.value > 0)
+    .map((s, i) => ({ label: s.label, value: s.value, color: i < CHART_PALETTE.length ? CHART_PALETTE[i] : CHART_OTHER }))
+  const fmt = (v: number) => formatMetric(v, tile.unit)
+
+  return (
+    <Panel title={tile.title} flex={1} minW={340}>
+      {loading && raw.length === 0 ? (
+        <XStack p="$4" justify="center">
+          <SkeletonBar w={160} h={160} rounded />
+        </XStack>
+      ) : total <= 0 ? (
+        <EmptyPanel note="No breakdown recorded in this range." />
+      ) : (
+        <XStack flexWrap="wrap" gap="$4" items="center">
+          <Donut
+            slices={slices}
+            center={
+              <>
+                <Text fontSize="$5" fontWeight="500" color="$color12" className="tnum">
+                  {fmt(total)}
+                </Text>
+                {tile.centerLabel ? (
+                  <Text fontSize="$1" color="$color10">
+                    {tile.centerLabel}
+                  </Text>
+                ) : null}
+              </>
+            }
+          />
+          <YStack flex={1} minW={200} gap="$2">
+            {raw.filter((s) => s.value > 0).map((s, i) => (
+              <XStack key={s.label} items="center" gap="$2.5">
+                <YStack width={10} height={10} rounded="$10" style={{ backgroundColor: i < CHART_PALETTE.length ? CHART_PALETTE[i] : CHART_OTHER }} />
+                <YStack flex={1}>
+                  <Text fontSize="$3" fontWeight="600" color="$color12" numberOfLines={1}>
+                    {s.label}
+                  </Text>
+                  {s.sub ? (
+                    <Text fontSize="$1" color="$color10" numberOfLines={1}>
+                      {s.sub}
+                    </Text>
+                  ) : null}
+                </YStack>
+                <YStack items="flex-end">
+                  <Text fontSize="$3" fontWeight="500" color="$color12" className="tnum">
+                    {fmt(s.value)}
+                  </Text>
+                  <Text fontSize="$1" color="$color10" className="tnum">
+                    {Math.round((s.value / total) * 100)}%
+                  </Text>
+                </YStack>
+              </XStack>
+            ))}
+          </YStack>
+        </XStack>
+      )}
+    </Panel>
+  )
+}
+
+// ── Activity tile → Feed ─────────────────────────────────────────────────────
+
+export function ActivityTileView({ tile, data, loading }: { tile: ActivityTile; data: OverviewData | null; loading: boolean }) {
+  return <Feed items={data?.activity ?? []} title={tile.title} empty={tile.empty} loading={loading} />
+}
+
+// ── Alerts tile ──────────────────────────────────────────────────────────────
+
+export function AlertsTileView({ tile, data, loading }: { tile: AlertsTile; data: OverviewData | null; loading: boolean }) {
+  const alerts = data?.alerts ?? []
+  return (
+    <Panel title={tile.title ?? 'Alerts'}>
+      {loading && alerts.length === 0 ? (
+        <SkeletonBar w="100%" h={44} />
+      ) : alerts.length === 0 ? (
+        <XStack items="center" gap="$2">
+          <YStack width={9} height={9} rounded="$10" style={{ backgroundColor: OK }} />
+          <Text fontSize="$3" color="$color11">
+            No active alerts.
+          </Text>
+        </XStack>
+      ) : (
+        <YStack gap="$2.5">
+          {alerts.map((a) => (
+            <XStack key={a.id || a.title} items="flex-start" gap="$2.5">
+              <YStack width={9} height={9} rounded="$10" mt="$1.5" style={{ backgroundColor: severityColor(a.severity) }} />
+              <YStack flex={1}>
+                <Text fontSize="$3" fontWeight="600" color="$color12">
+                  {a.title}
+                </Text>
+                {a.detail ? (
+                  <Text fontSize="$1" color="$color10">
+                    {a.detail}
+                  </Text>
+                ) : null}
+              </YStack>
+            </XStack>
+          ))}
+        </YStack>
+      )}
+    </Panel>
+  )
+}
+
+// ── Health tile → Board ──────────────────────────────────────────────────────
+
+export function HealthTileView({ tile, data, loading }: { tile: HealthTile; data: OverviewData | null; loading: boolean }) {
+  return <Board items={data?.health ?? []} title={tile.title} empty={tile.empty} loading={loading} />
+}
+
+// ── Tile router ──────────────────────────────────────────────────────────────
+
+/** Render one declared tile spec against the normalized `OverviewData`. */
+export function Tile({ tile, data, loading, live, index }: { tile: OverviewTile; data: OverviewData | null; loading: boolean; live: boolean; index: number }) {
+  switch (tile.tile) {
+    case 'metric':
+      return <MetricTileView tile={tile} data={data} loading={loading} live={live} index={index} />
+    case 'timeseries':
+      return <TimeseriesTileView tile={tile} data={data} loading={loading} />
+    case 'distribution':
+      return <DistributionTileView tile={tile} data={data} loading={loading} />
+    case 'activity':
+      return <ActivityTileView tile={tile} data={data} loading={loading} />
+    case 'alerts':
+      return <AlertsTileView tile={tile} data={data} loading={loading} />
+    case 'health':
+      return <HealthTileView tile={tile} data={data} loading={loading} />
+  }
+}