@hanzo/dashboard 0.2.0 → 0.2.1

package/src/overview/Overview.tsx

@@ -0,0 +1,203 @@
+'use client'
+
+/**
+ * Overview — the ONE reusable, videogame-like dashboard driver. Given an
+ * `OverviewConfig` (a product's tiles + its REAL data loader + live/motion
+ * settings) it renders the board and keeps it alive: a single throttled poll loop
+ * refetches on an interval (paused on a hidden tab), the range selector re-scopes,
+ * and every number counts up on change (unless reduced motion / count-up off).
+ *
+ * DRY + orthogonal: this file knows nothing about any specific product or endpoint.
+ * The tiles read their slice out of the normalized `OverviewData` the loader returns;
+ * a product is added by writing a config, never overview UI.
+ *
+ * Honest by construction: the FIRST load shows a spinner; a failure shows the error
+ * card; thereafter a background refetch never blanks the board (the last real data
+ * stays until new real data lands), and any tile whose slice is absent renders its
+ * own skeleton/empty. Style props are the @hanzo/gui v5 shorthand set.
+ */
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import { Button, Card, Spinner, Text, XStack, YStack } from '@hanzo/gui'
+
+import { effectiveInterval } from '../motion/motion'
+import { usePageHidden, usePoll } from '../motion/hooks'
+import { type Loadable } from './logic'
+import { PanelSpinner } from './primitives'
+import { Tile } from './tiles'
+import type { OverviewConfig, OverviewData, OverviewRange } from './config'
+
+/** Throttle floor: a config can ask for faster, but never faster than this. */
+const POLL_FLOOR_MS = 5000
+
+const RANGES: { key: OverviewRange; label: string }[] = [
+  { key: '24h', label: '24H' },
+  { key: '7d', label: '7D' },
+  { key: '30d', label: '30D' },
+]
+
+export function Overview({ config, allOrgs, isGlobalAdmin = false }: { config: OverviewConfig; allOrgs?: boolean; isGlobalAdmin?: boolean }) {
+  const [range, setRange] = useState<OverviewRange>('24h')
+  const [state, setState] = useState<Loadable<OverviewData>>({ s: 'loading' })
+  const [refreshing, setRefreshing] = useState(false)
+  const reqRef = useRef(0)
+
+  const hidden = usePageHidden()
+  // Pause polling while the tab is hidden OR the board is in its error state — an
+  // errored source should not be hammered on a loop; the user retries explicitly.
+  const pollMs = effectiveInterval(config.live?.pollMs ?? 0, POLL_FLOOR_MS, hidden || state.s === 'error')
+  const { tick, bump } = usePoll(pollMs)
+  const live = (config.live?.pollMs ?? 0) > 0
+  const countUp = config.live?.countUp !== false
+
+  // One load path for the first paint, the range change, and every poll tick. The
+  // reqRef guard drops a stale in-flight response so a fast range toggle can't
+  // render older data over newer.
+  useEffect(() => {
+    const id = ++reqRef.current
+    const first = state.s === 'loading'
+    if (!first) setRefreshing(true)
+    config
+      .load({ range, allOrgs, isGlobalAdmin })
+      .then((v) => {
+        if (id === reqRef.current) setState({ s: 'ready', v })
+      })
+      .catch((e) => {
+        // A background refetch that fails must NOT blank a board that already has
+        // real data — keep the last data, surface the error only on the first load.
+        if (id !== reqRef.current) return
+        if (first) {
+          const err = asLoadError(e)
+          setState({ s: 'error', message: err.message, status: err.status })
+        }
+      })
+      .finally(() => {
+        if (id === reqRef.current) setRefreshing(false)
+      })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [range, allOrgs, isGlobalAdmin, tick, config])
+
+  const onRange = (k: OverviewRange) => {
+    setRange(k)
+    bump()
+  }
+
+  const data = state.s === 'ready' ? state.v : null
+
+  return (
+    <YStack gap="$4">
+      <Header
+        title={allOrgs ? `${config.title} — all orgs` : config.title}
+        subtitle={config.subtitle}
+        actions={
+          <XStack gap="$2" items="center">
+            {refreshing ? <Spinner size="small" color="$color10" /> : null}
+            {config.ranged === false ? null : <RangeSelector value={range} onChange={onRange} />}
+          </XStack>
+        }
+      />
+
+      {state.s === 'error' ? (
+        <ErrorState
+          message={state.message}
+          status={state.status}
+          onRetry={() => {
+            setState({ s: 'loading' })
+            bump()
+          }}
+        />
+      ) : state.s === 'loading' ? (
+        <PanelSpinner />
+      ) : (
+        <YStack gap="$4">
+          {config.rows.map((row, ri) => (
+            <FadeIn key={ri} index={ri} step={60}>
+              <XStack flexWrap="wrap" gap="$3">
+                {row.map((tile, ti) => (
+                  <Tile key={ti} tile={tile} data={data} loading={false} live={live && countUp} index={ti} />
+                ))}
+              </XStack>
+            </FadeIn>
+          ))}
+        </YStack>
+      )}
+    </YStack>
+  )
+}
+
+// ── chrome (self-contained — no host-app coupling) ───────────────────────────
+
+/** Extract an honest message + status from an unknown thrown value. */
+function asLoadError(e: unknown): { message: string; status: number } {
+  if (e && typeof e === 'object') {
+    const anyE = e as { message?: unknown; status?: unknown }
+    return {
+      message: typeof anyE.message === 'string' ? anyE.message : 'Something went wrong.',
+      status: typeof anyE.status === 'number' ? anyE.status : 0,
+    }
+  }
+  return { message: typeof e === 'string' ? e : 'Something went wrong.', status: 0 }
+}
+
+/** Section title + optional subtitle and right-aligned actions. */
+function Header({ title, subtitle, actions }: { title: string; subtitle?: string; actions?: ReactNode }) {
+  return (
+    <XStack justify="space-between" items="flex-start" gap="$3" flexWrap="wrap">
+      <YStack gap="$1" flex={1} minW={200}>
+        <Text fontSize="$7" fontWeight="500" letterSpacing={-0.4}>
+          {title}
+        </Text>
+        {subtitle ? (
+          <Text fontSize="$3" color="$color11">
+            {subtitle}
+          </Text>
+        ) : null}
+      </YStack>
+      {actions ? <XStack gap="$2" items="center">{actions}</XStack> : null}
+    </XStack>
+  )
+}
+
+/** A fade-up entrance (staggered by index). Honors reduced motion via the CSS. */
+function FadeIn({ children, index = 0, step = 50 }: { children: ReactNode; index?: number; step?: number }) {
+  return (
+    <div className="fade-up" style={{ animationDelay: `${index * step}ms` }}>
+      {children}
+    </div>
+  )
+}
+
+/** The first-load / retry error card (honest, with a retry). */
+function ErrorState({ message, status, onRetry }: { message: string; status: number; onRetry: () => void }) {
+  const note =
+    status === 404
+      ? 'This overview’s data source is not routed on this deployment yet — it appears automatically once the backend is reachable for your org.'
+      : message
+  return (
+    <Card borderWidth={1} borderColor="$borderColor" p="$5" gap="$3" items="flex-start">
+      <Text fontSize="$5" fontWeight="600" color="$color12">
+        Could not load
+      </Text>
+      <Text fontSize="$3" color="$color11" maxW={620}>
+        {note}
+      </Text>
+      <Button onPress={onRetry}>Retry</Button>
+    </Card>
+  )
+}
+
+function RangeSelector({ value, onChange }: { value: OverviewRange; onChange: (k: OverviewRange) => void }) {
+  return (
+    <XStack borderWidth={1} borderColor="$borderColor" rounded="$4" overflow="hidden">
+      {RANGES.map((r) => {
+        const active = r.key === value
+        return (
+          <Button key={r.key} size="$2" chromeless={!active} bg={active ? '$color5' : 'transparent'} rounded="$0" onPress={() => onChange(r.key)}>
+            <Text fontSize="$2" fontWeight={active ? '700' : '500'} color={active ? '$color12' : '$color10'}>
+              {r.label}
+            </Text>
+          </Button>
+        )
+      })}
+    </XStack>
+  )
+}

package/src/overview/config.ts

@@ -0,0 +1,176 @@
+/**
+ * Overview config — the DECLARATIVE contract that makes one overview
+ * component serve every product. A product declares WHICH tiles it has and WHERE
+ * their data comes from; `Overview` renders + animates them. No product
+ * writes overview UI — it writes a `OverviewConfig`.
+ *
+ * Orthogonal by design:
+ *   - a `LoadOverview` is the ONE async that fetches a product's REAL data and
+ *     returns a normalized `OverviewData` (KPIs, series, distribution, activity,
+ *     alerts, health). It owns the endpoint; the tiles know nothing about it.
+ *   - each tile is a small value object naming a slice of that data by key
+ *     (`kpi.tokens`, `series.spend`, …). A missing slice renders its honest empty
+ *     state — the config can over-declare tiles a slow backend hasn't filled yet.
+ *   - `live` is the videogame layer: a poll interval (throttled, hidden-tab-paused)
+ *     and whether numbers count up. Off → a static overview, same component.
+ *
+ * The consumer supplies its own adapter that maps each real source (usage ledger,
+ * admin aggregate, functions metrics, …) onto `OverviewData`, so wiring a product =
+ * one adapter + one config, never new UI.
+ */
+import type { IconComponent } from '../types'
+
+/** A KPI datum for an animated metric tile. Raw numbers; the tile formats them. */
+export type OverviewKpi = {
+  value: number
+  /** Prior-period value for the ±% delta; omit when there is no basis (→ honest "—"). */
+  prior?: number
+  /** A recent dense series for the tile's live sparkline (oldest→newest). */
+  series?: number[]
+}
+
+/** A point on a temporal series. */
+export type OverviewPoint = { t: string; value: number }
+
+/** A named temporal series with its bucket interval (drives the x-axis labels). */
+export type OverviewSeries = { interval: 'hour' | 'day' | (string & {}); points: OverviewPoint[] }
+
+/** A slice of a distribution (spend by model, revenue by product). */
+export type OverviewSlice = { label: string; value: number; sub?: string }
+
+/** A live activity/event row. */
+export type OverviewEvent = {
+  id: string
+  time: string
+  title: string
+  subtitle?: string
+  /** `success` | `error` | `warn` | '' — drives the status dot. */
+  status: string
+}
+
+/** An open alert. */
+export type OverviewAlert = { id: string; severity: 'critical' | 'warning' | 'info' | (string & {}); title: string; detail?: string }
+
+/** A service-health row. */
+export type OverviewHealth = { service: string; health: 'green' | 'yellow' | 'red' | (string & {}); detail?: string }
+
+/**
+ * The normalized data every tile reads. Keyed maps so a tile names its slice by a
+ * stable key; every map may be partial (a slice with no data → honest empty tile).
+ */
+export type OverviewData = {
+  kpi: Record<string, OverviewKpi>
+  series: Record<string, OverviewSeries>
+  distribution: Record<string, OverviewSlice[]>
+  activity: OverviewEvent[]
+  alerts: OverviewAlert[]
+  health: OverviewHealth[]
+  /** Total count behind `activity` for pagination, when the source knows it. */
+  activityTotal?: number
+}
+
+/** How a number is displayed. `cents`→USD, `count`→compacted, `ms`→duration, `pct`→percent. */
+export type MetricUnit = 'count' | 'cents' | 'ms' | 'pct'
+
+/** An animated KPI tile: a count-up number + optional live sparkline + delta. */
+export type MetricTile = {
+  tile: 'metric'
+  /** Key into `OverviewData.kpi`. */
+  key: string
+  label: string
+  icon: IconComponent
+  unit?: MetricUnit
+  /** Static caption under the value (e.g. "across 3 providers"). */
+  caption?: string
+  /** Accent color for the sparkline (defaults to the palette by position). */
+  color?: string
+}
+
+/** A timeseries panel (line or bars) over `OverviewData.series[key]`. */
+export type TimeseriesTile = {
+  tile: 'timeseries'
+  key: string
+  title: string
+  kind?: 'line' | 'bar'
+  unit?: MetricUnit
+}
+
+/** A distribution panel (donut + legend) over `OverviewData.distribution[key]`. */
+export type DistributionTile = {
+  tile: 'distribution'
+  key: string
+  title: string
+  /** Center caption under the total. */
+  centerLabel?: string
+  unit?: MetricUnit
+}
+
+/** The live activity stream (virtualized, streaming/polled). */
+export type ActivityTile = {
+  tile: 'activity'
+  title?: string
+  /** Empty-state copy when there is no activity in range. */
+  empty?: string
+}
+
+/** The open-alerts panel. */
+export type AlertsTile = { tile: 'alerts'; title?: string }
+
+/** The service-health board. */
+export type HealthTile = { tile: 'health'; title?: string; empty?: string }
+
+/** Any tile. Discriminated on `tile` so the renderer branches exhaustively. */
+export type OverviewTile =
+  | MetricTile
+  | TimeseriesTile
+  | DistributionTile
+  | ActivityTile
+  | AlertsTile
+  | HealthTile
+
+/** The "videogame" layer — live updates + motion, all off-able for a static view. */
+export type LiveConfig = {
+  /**
+   * Poll the loader every `pollMs` (throttled to a floor, paused when the tab is
+   * hidden). 0/undefined → no polling (a one-shot static overview).
+   */
+  pollMs?: number
+  /** Count numbers up on change (respects prefers-reduced-motion). Default true. */
+  countUp?: boolean
+}
+
+/** The context passed to a loader (range + org scope). */
+export type OverviewContext = {
+  range: OverviewRange
+  /** Global-admin all-orgs god view. */
+  allOrgs?: boolean
+  /**
+   * True when the viewer is a global (cross-tenant) admin. Loaders use this to
+   * SKIP admin-only aggregates that a tenant user's browser would only ever get a
+   * 403 from, going straight to the org-scoped source instead — the board renders
+   * the same, minus the console noise.
+   */
+  isGlobalAdmin?: boolean
+}
+
+export type OverviewRange = '24h' | '7d' | '30d'
+
+/** The ONE async that fetches a product's REAL data, normalized to `OverviewData`. */
+export type LoadOverview = (ctx: OverviewContext) => Promise<OverviewData>
+
+/**
+ * A product's complete overview — its header, its tiles (in render order), its
+ * real data loader, and its live/motion settings. This IS the reusable unit: a
+ * consumer builds one of these; `Overview` renders it.
+ */
+export type OverviewConfig = {
+  id: string
+  title: string
+  subtitle?: string
+  /** Ordered rows of tiles (each row is a responsive wrap group). */
+  rows: OverviewTile[][]
+  load: LoadOverview
+  live?: LiveConfig
+  /** Show the range selector (24H/7D/30D). Default true. */
+  ranged?: boolean
+}

package/src/overview/logic.ts

@@ -0,0 +1,204 @@
+/**
+ * Overview tile logic — the PURE decisions behind every tile, so the honest
+ * empty/loading/error/reduced-motion behavior is unit-testable in the node env and
+ * the `.tsx` tiles stay thin.
+ *
+ * Every function here answers ONE question a tile needs: how to format a value for
+ * its unit, whether a live sparkline has enough real points to draw, what a delta
+ * reads (or the honest "—" when there's no basis), what color a status/health dot
+ * is, and — critically — how to SELECT a tile's slice out of `OverviewData` so a
+ * missing slice becomes an honest empty tile instead of a crash.
+ *
+ * Nothing here fabricates data: a formatter turns a real number into a string, a
+ * selector returns `undefined`/`[]` for absent data, and the sparkline gate returns
+ * false for <2 points (the tile then renders no trend).
+ */
+import type {
+  MetricUnit,
+  OverviewData,
+  OverviewKpi,
+  OverviewSlice,
+  OverviewEvent,
+  OverviewHealth,
+  OverviewSeries,
+} from './config'
+
+// ── value formatting ─────────────────────────────────────────────────────────
+
+const compact = (n: number): string =>
+  new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 }).format(n)
+
+const usd = (cents: number): string => {
+  const d = cents / 100
+  if (Math.abs(d) >= 1000) return '$' + new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 }).format(d)
+  return '$' + d.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+}
+
+const duration = (ms: number): string => {
+  if (ms >= 1000) return (ms / 1000).toFixed(ms >= 10_000 ? 0 : 1) + 's'
+  return Math.round(ms) + 'ms'
+}
+
+/** Format a raw metric value for its unit. The ONE place units become strings. */
+export function formatMetric(value: number, unit: MetricUnit = 'count'): string {
+  if (!Number.isFinite(value)) return '—'
+  switch (unit) {
+    case 'cents':
+      return usd(value)
+    case 'ms':
+      return duration(value)
+    case 'pct':
+      return `${Math.round(value)}%`
+    default:
+      return compact(value)
+  }
+}
+
+/**
+ * The number the count-up animation should target for a unit. Money counts up in
+ * DOLLARS (not cents) so the animated digits read naturally; everything else counts
+ * up in its own value. The tile formats the interpolated number back via
+ * `formatMetric` on the same unit. This returns the raw value; the divisor is in
+ * `formatMetric`.
+ */
+export function metricTarget(value: number): number {
+  return Number.isFinite(value) ? value : 0
+}
+
+/** A delta descriptor for a KPI, or null when there's no prior basis (honest "—"). */
+export function deltaOf(kpi: OverviewKpi | undefined): { pct: number; up: boolean } | null {
+  if (!kpi || kpi.prior === undefined || !Number.isFinite(kpi.prior) || kpi.prior === 0) return null
+  const pct = Math.round(((kpi.value - kpi.prior) / kpi.prior) * 100)
+  return { pct, up: pct >= 0 }
+}
+
+/** True when a live sparkline has ≥2 finite points to draw (else the tile shows no trend). */
+export function hasTrend(series: readonly number[] | undefined): boolean {
+  if (!series) return false
+  return series.filter((v) => Number.isFinite(v)).length >= 2
+}
+
+// ── status / health colors (the ONE mapping) ─────────────────────────────────
+
+export const OK = '#23c562'
+export const WARN = '#f0a868'
+export const BAD = '#ff5d8f'
+export const MUTED = '#64748b'
+
+/** Dot color for an activity/event status. */
+export function statusColor(status: string): string {
+  const s = status.toLowerCase()
+  if (s === 'error' || s === 'failed' || s === 'fail') return BAD
+  if (s === 'warn' || s === 'warning' || s === 'pending') return WARN
+  return OK // success or unknown/'' reads as nominal
+}
+
+/** Dot color for a service-health verdict. */
+export function healthColor(health: string): string {
+  const h = health.toLowerCase()
+  if (h === 'green' || h === 'healthy' || h === 'ok') return OK
+  if (h === 'yellow' || h === 'degraded' || h === 'warn') return WARN
+  if (h === 'red' || h === 'down' || h === 'unhealthy') return BAD
+  return MUTED
+}
+
+/** Dot color for an alert severity. */
+export function severityColor(severity: string): string {
+  const s = severity.toLowerCase()
+  if (s === 'critical' || s === 'error') return BAD
+  if (s === 'warning' || s === 'warn') return WARN
+  return MUTED
+}
+
+// ── overall health verdict for the board header ──────────────────────────────
+
+/** The worst verdict across health rows: red > yellow > green; '' when no rows. */
+export function worstHealth(rows: readonly OverviewHealth[]): '' | 'green' | 'yellow' | 'red' {
+  let sawYellow = false
+  let sawGreen = false
+  for (const r of rows) {
+    const h = r.health.toLowerCase()
+    if (h === 'red' || h === 'down' || h === 'unhealthy') return 'red' // worst — short-circuit
+    if (h === 'yellow' || h === 'degraded') sawYellow = true
+    else if (h === 'green' || h === 'healthy' || h === 'ok') sawGreen = true
+  }
+  if (sawYellow) return 'yellow'
+  if (sawGreen) return 'green'
+  return ''
+}
+
+/** Count healthy rows / total (for the "12/14 healthy" header). */
+export function healthTally(rows: readonly OverviewHealth[]): { healthy: number; total: number } {
+  const total = rows.length
+  const healthy = rows.filter((r) => healthColor(r.health) === OK).length
+  return { healthy, total }
+}
+
+// ── slice selectors (a missing slice → honest empty, never a crash) ──────────
+
+export const selectKpi = (data: OverviewData, key: string): OverviewKpi | undefined => data.kpi[key]
+export const selectSeries = (data: OverviewData, key: string): OverviewSeries | undefined => data.series[key]
+export const selectDistribution = (data: OverviewData, key: string): OverviewSlice[] => data.distribution[key] ?? []
+
+/** Sum a distribution's positive values (the donut center total). */
+export function distributionTotal(slices: readonly OverviewSlice[]): number {
+  return slices.reduce((sum, s) => sum + Math.max(0, s.value), 0)
+}
+
+/**
+ * Merge freshly-polled activity into the current list, newest-first, de-duped by
+ * id, capped. This is what lets the live stream GROW smoothly across polls without
+ * duplicating a row already on screen or re-ordering the feed. Rows with an empty
+ * id are kept (can't dedupe them) but still ordered by time.
+ */
+export function mergeActivity(current: readonly OverviewEvent[], incoming: readonly OverviewEvent[], cap: number): OverviewEvent[] {
+  const seen = new Set<string>()
+  const out: OverviewEvent[] = []
+  for (const e of [...incoming, ...current]) {
+    if (e.id && seen.has(e.id)) continue
+    if (e.id) seen.add(e.id)
+    out.push(e)
+  }
+  out.sort((a, b) => tOf(b.time) - tOf(a.time))
+  return out.slice(0, cap)
+}
+
+const tOf = (iso: string): number => {
+  const t = Date.parse(iso)
+  return Number.isNaN(t) ? 0 : t
+}
+
+/** Which rows of a virtualized list are visible for a scroll offset + viewport. */
+export function windowRows<T>(rows: readonly T[], scrollTop: number, rowH: number, viewportH: number, overscan = 4): { start: number; end: number; padTop: number; padBottom: number; slice: T[] } {
+  if (rows.length === 0 || rowH <= 0) return { start: 0, end: 0, padTop: 0, padBottom: 0, slice: [] }
+  const start = Math.max(0, Math.floor(scrollTop / rowH) - overscan)
+  const visible = Math.ceil(viewportH / rowH) + overscan * 2
+  const end = Math.min(rows.length, start + visible)
+  return {
+    start,
+    end,
+    padTop: start * rowH,
+    padBottom: Math.max(0, (rows.length - end) * rowH),
+    slice: rows.slice(start, end),
+  }
+}
+
+// ── async state (the repo idiom, shared by the driver + tests) ───────────────
+
+export type Loadable<T> = { s: 'loading' } | { s: 'error'; message: string; status: number } | { s: 'ready'; v: T }
+
+/** True when a tile should render its SKELETON (first load, no data yet). */
+export const isSkeleton = <T>(state: Loadable<T>): boolean => state.s === 'loading'
+
+/** Relative-time label for an event/activity timestamp (honest for a bad stamp). */
+export function ago(iso: string, now: number): string {
+  const t = Date.parse(iso)
+  if (Number.isNaN(t)) return '—'
+  const s = Math.max(0, Math.round((now - t) / 1000))
+  if (s < 60) return `${s}s ago`
+  const m = Math.round(s / 60)
+  if (m < 60) return `${m}m ago`
+  const h = Math.round(m / 60)
+  if (h < 24) return `${h}h ago`
+  return `${Math.round(h / 24)}d ago`
+}