The prop and the loader context named it isGlobalAdmin. It was always the host's verdict passed through, never decided here, and the one term for that verdict is SuperAdmin. No consumer passes the old name.
12 KiB
@hanzo/dashboard
The reusable dashboard layer on @hanzo/gui.
A set of composable, honest, reduced-motion-guarded dashboard primitives extracted
from the Hanzo Cloud Console so every Hanzo app — console, admin surfaces,
hanzo.team, desktop dashboards — builds the same dashboard system instead of
re-implementing it.
Everything here is pure: data comes in via props or a loader you supply, actions
are callbacks, and @hanzo/gui is a peer dependency (this layer sits on it, never
forks it). No app-specific API imports.
pnpm add @hanzo/dashboard @hanzo/gui @hanzogui/lucide-icons-2
import '@hanzo/dashboard/dashboard.css' // once — ships the motion keyframes
import { Overview, Kpi, Sparkline, Landing, Pipeline } from '@hanzo/dashboard'
dashboard.csscarries the loading shimmer, live-feed pulse, fade-up entrance, and the deploy-pipeline animations — every one reduced-motion-guarded (→ static). The count-up + live sparkline motion is driven in JS and gated onprefers-reduced-motionin the hooks.
Charts — the ONE way to draw a trend / series / share / distribution
Monochrome SVG (dependency-free) that themes to the shell. Honest by construction: a
Sparkline with < 2 points renders nothing; Donut/Bars with no positive value
render an em-dash. Callers pass REAL series — these never fabricate data.
| Export | What it draws |
|---|---|
Sparkline |
A fixed-size mini trend (for stat tiles). |
Line |
A value over time (line + hover tooltip). |
Columns |
A value over time (vertical bars + hover). |
Donut |
Categorical share (optional legend, center slot). |
Bars |
A ranked distribution (horizontal, token-native). |
useContainerWidth |
Measure a container for responsive SVG. |
CHART_PALETTE, CHART_OTHER |
The categorical hues. |
types ChartPoint, Slice |
Data shapes. |
<Line data={[{ label: 'Mon', value: 12 }, { label: 'Tue', value: 30 }]} formatValue={(v) => `${v}`} />
<Donut slices={[{ label: 'zen', value: 60 }, { label: 'gpt', value: 40 }]} legend />
<Sparkline values={[3, 5, 4, 9, 12]} />
Motion — pure math + rAF/interval hooks
Unit-testable pure functions plus the thin browser hooks that drive them; every hook self-cleans on unmount (no leaked frames/timers).
- Pure:
easeOutCubic,countUpValue,progress,pushSample,shouldTick,effectiveInterval. - Hooks:
useCountUp,usePoll,useReducedMotion,usePageHidden.
const value = useCountUp(target, /* enabled */ true) // snaps to target under reduced motion
const { tick, bump } = usePoll(15_000) // paused when interval ≤ 0
Overview — the videogame-like living dashboard
Declare a product's tiles + a REAL data loader; Overview renders + animates the
board and keeps it alive (one throttled poll loop, hidden-tab-paused, range selector,
count-up on change). A product is added by writing a config, never overview UI.
import { Overview, type OverviewConfig } from '@hanzo/dashboard'
import { Cpu } from '@hanzogui/lucide-icons-2'
const config: OverviewConfig = {
id: 'gpus', title: 'GPUs',
live: { pollMs: 15_000, countUp: true },
rows: [
[{ tile: 'metric', key: 'active', label: 'Active', icon: Cpu }],
[{ tile: 'timeseries', key: 'usage', title: 'Usage over time' },
{ tile: 'distribution', key: 'byModel', title: 'By model' }],
[{ tile: 'activity' }, { tile: 'health' }],
],
load: async ({ range }) => fromMyApi(await MyApi.overview(range)), // → OverviewData
}
<Overview config={config} superAdmin={superAdmin(claims)} /> // @hanzo/iam's one reading
The loader returns the normalized OverviewData (kpi / series / distribution
/ activity / alerts / health maps). A missing slice renders an honest empty tile
— you can over-declare tiles a slow backend hasn't filled yet. First load shows a
spinner; a failure shows a retry card; a background refetch never blanks a board that
already has real data.
Composable primitives (use without the driver)
The tiles are also standalone, direct-props components — the valuable, reusable core:
| Export | Props (data in, view out) |
|---|---|
Kpi |
label, value (null → "—"), unit, deltaPct, series, icon, color, caption, animate, loading |
Feed |
items: OverviewEvent[], title, empty, loading (virtualizes past a viewport) |
Board |
items: OverviewHealth[], title, empty, loading (health tally + dots) |
Tile |
Render one declared tile spec against OverviewData. |
Panel, SkeletonBar, EmptyPanel, PanelSpinner, LiveDot |
Shared chrome. |
<Kpi label="Requests" value={32_412} unit="count" deltaPct={12} series={[10,14,22,31]} icon={Zap} />
Plus the pure tile logic (formatMetric, deltaOf, hasTrend, mergeActivity,
windowRows, statusColor/healthColor/severityColor, selectKpi/selectSeries/
selectDistribution, …) and the OverviewConfig / OverviewData / tile types.
Landing — the polished product landing kit
Compose a LandingConfig and render <Landing> to get a hero + live count-up metrics
row + an interactive code-sample block + a resources rail. Parts are exported too
(Hero, Metrics, Samples, Rail).
import { Landing, type LandingConfig } from '@hanzo/dashboard'
const config: LandingConfig = {
productId: 'embeddings', title: 'Embeddings',
tagline: 'Vector search over your data.',
brandName: 'Hanzo Cloud', docsUrl: 'https://docs.hanzo.ai', docsProduct: 'embeddings',
primary: { label: 'Create collection', onPress: onCreate },
loadMetrics: async () => [{ key: 'vectors', label: 'Vectors', value: 1_240, series: [...] }],
samples: [{ lang: 'curl', label: 'cURL', code: 'curl https://api.hanzo.ai/v1/embeddings ...' }],
}
<Landing config={config}>{/* the product's own real content */}</Landing>
All links (docs / quickstart / examples / API / support) derive from config.docsUrl,
so a Lux/Zoo console links to ITS OWN surfaces. Brand + accent come from the config
(brandName, accent) — no hardcoded brand. Pure link helpers are exported
(apexFromDocs, apiBaseFromDocs, landingDocsUrl, standardResources, supportMailto).
Pipeline — the deploy-stage line
A small, presentational animated pipeline (Queued → Building → Deploying → Live, or any
custom stages). Driven by a stages prop; derive it from a real status string with the
pure pipelineModel, and poll to pass fresh stages.
import { Pipeline, pipelineModel } from '@hanzo/dashboard'
const model = pipelineModel(app.status, furthestReached) // furthest tracked across polls
<Pipeline stages={model.stages} label={model.label} />
Pure helpers: pipelineModel, pipelinePhase, stageIndex, isTerminalPhase,
pipelineTone, PIPELINE_STAGES, and the PipelineStage/PipelineModel/StageState
types. Completed stages fill with a check, the current stage pulses, the active leg
flows, a failure turns the reached stage red — all reduced-motion-guarded.
Provenance — how each export maps back to the console
Extracted (and generalized: no ~/lib/* / ~/config imports) from
~/work/hanzo/console2:
@hanzo/dashboard |
console2 source |
|---|---|
charts/Charts (Sparkline/Line/Columns/Donut/Bars) |
src/components/ui/Charts.tsx (Sparkline/LineChart/BarChart/Donut/BarRows) |
motion/motion + motion/hooks |
src/components/products/overview/living/{motion,hooks}.ts |
overview/{config,logic} |
.../overview/living/{config,logic}.ts |
overview/primitives (Kpi/Feed/Board) + overview/tiles (Tile) |
.../overview/living/tiles.tsx (the tile views) |
overview/Overview |
.../overview/living/LivingOverview.tsx |
landing/* (Landing/Hero/Metrics/Samples/Rail) |
src/components/products/landing/* (ProductLanding/LandingHero/LandingMetrics/CodeSamples/ResourceRail) |
pipeline/{pipeline,Pipeline} |
src/components/products/paas/{railway.ts,RailwayDeploy.tsx} |
Generalizations made during extraction
- Icons are consumer-supplied (
IconComponent= asize/coloricon), replacing the console'sProductIconfrom its registry. Overviewdrops~/lib/apiApiError, the console's SuperAdmin hook,PageHeader,FadeIn, andStates—superAdminis now a prop (the host's verdict) and the header/fade/error chrome is inlined (self-contained).- Landing takes brand/docs/support/discord/accent from
LandingConfig(was~/config).LandingHeroinlines the hero graphic + accent button (was../inference/parts). - Pipeline takes a
stagesprop and drops the console'sPaasApi.getAppself-poll — the consumer polls and passes fresh stages. - Naming is de-branded and single-word:
LivingOverview→Overview,RailwayDeploy→Pipeline,ProductLanding→Landing,LineChart/BarChart/BarRows→Line/Columns/Bars. CSS classeshz-rail-*→hz-pipe-*.
Follow-up: swapping console2 onto this package (a later pass)
console2 is untouched this pass. To consume @hanzo/dashboard back in console2,
per component:
- Charts — delete
src/components/ui/Charts.tsx; re-export from the package (export { Sparkline, Line as LineChart, Columns as BarChart, Bars as BarRows, Donut, useContainerWidth, CHART_PALETTE, CHART_OTHER } from '@hanzo/dashboard') or update call sites to the new names.~/components/products/inference/parts,landing/*, andoverview/living/tilesimportCharts— the alias keeps them working. - Motion — replace
overview/living/{motion,hooks}.tswith re-exports from@hanzo/dashboard;RailwayDeploy+LandingMetricsimport these hooks. - Overview — replace
overview/living/{config,logic,tiles,LivingOverview}with thin wrappers over the package. The console'sLivingOverviewModulekeeps its registry-router wrapper and passessuperAdmin={useIsSuperAdmin()}+ mapsApiErrorinto the driver's caught error.PageHeader/FadeIn/Statesstay in console (they're used elsewhere) — the driver now inlines its own. - Landing — replace
products/landing/*with the package; the console builds aLandingConfigwithdocsUrl: config.docsUrl,brandName: config.brandName,discordUrl: 'https://discord.gg/CJCyAsm9Vr'.LandingHero's console-specificHeroGraphic/AccentButton(frominference/parts) are now inlined in the package. - Pipeline — swap
paas/RailwayDeploy.tsxfor<Pipeline>; the console owns thePaasApi.getApppoll (usePoll+PaasApi) and the monotonicfurtheststate, callingpipelineModel(status, furthest)and passing.stages+.label.
Once swapped, the console2 tests that already cover the pure logic
(motion.test.ts, logic.test.ts, railway.test.ts, landing/logic.test.ts) move
here (or re-run against the re-exports) so coverage follows the code.
Honest about what didn't extract cleanly
- The console's
config.tsregistry (LivingOverviewConfig.loadadapters:fromCloudUsage,fromAdminOverview,fromFunctions,healthFromApps) is product/API-specific and stays in console2 — it's the data half. This package is the view half; theOverviewDatacontract is the seam between them. - Console tile icons come from the console's product registry; here they're plain
IconComponentprops (the consumer supplies them). - The
Pipelineself-poll was PaaS-coupled and is intentionally dropped — the small, minor pipeline primitive is presentational only.
Build
pnpm typecheck # tsc --noEmit (strict) — clean
pnpm build # tsc → dist (proof; the package ships src)
The package ships src (source-only, like @hanzo/data); the consumer's bundler
transpiles it, and the @hanzo/gui shorthand style props type-check against the real
token unions via gui.config.ts + gui.d.ts.
License: MIT · Hanzo AI, Inc. — see LICENSE.md. HIP-0137 (hanzoai/hips).