@hanzo/dashboard 0.2.0 → 0.2.2

package/src/landing/Samples.tsx

@@ -0,0 +1,78 @@
+'use client'
+
+/**
+ * Samples — the interactive Quick Start / code block. Tab-switch between the REAL
+ * API call in curl / Python / TS / JS, copy the current sample, and (optionally)
+ * Run / Try in Playground. Not a screenshot — real, copyable, tab-switchable code.
+ * The block scrolls horizontally inside its own container so a wide line never
+ * scrolls the page.
+ */
+import { useState } from 'react'
+import { Button, Text, XStack, YStack } from '@hanzo/gui'
+import { Check, Copy, Play } from '@hanzogui/lucide-icons-2'
+
+import { LandingCard, openExternal } from './parts'
+import type { CodeSample, LandingAction } from './types'
+
+export function Samples({ samples, run, title = 'Quick start' }: { samples: CodeSample[]; run?: LandingAction; title?: string }) {
+  const [active, setActive] = useState(0)
+  const [copied, setCopied] = useState(false)
+  const idx = Math.min(active, samples.length - 1)
+  const sample = samples[idx]
+
+  const copy = async () => {
+    if (typeof navigator === 'undefined' || !navigator.clipboard) return
+    try {
+      await navigator.clipboard.writeText(sample.code)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1400)
+    } catch {
+      /* clipboard denied — no-op (the code is still visible + selectable) */
+    }
+  }
+
+  return (
+    <LandingCard
+      title={title}
+      actions={
+        run ? (
+          <Button size="$2" icon={<Play size={14} />} onPress={() => (run.href ? openExternal(run.href) : run.onPress?.())}>
+            {run.label}
+          </Button>
+        ) : undefined
+      }
+    >
+      <XStack items="center" justify="space-between" gap="$2" flexWrap="wrap">
+        <XStack gap="$1" flexWrap="wrap" items="center">
+          {samples.map((s, i) => {
+            const on = i === idx
+            return (
+              <Button key={s.lang} size="$2" bg={on ? '$color5' : 'transparent'} borderWidth={1} borderColor={on ? '$color7' : '$borderColor'} onPress={() => setActive(i)}>
+                <Text fontSize="$2" fontWeight={on ? '700' : '500'} color={on ? '$color12' : '$color11'}>
+                  {s.label}
+                </Text>
+              </Button>
+            )
+          })}
+        </XStack>
+        <Button size="$2" chromeless icon={copied ? <Check size={14} color="#23c562" /> : <Copy size={14} />} onPress={copy}>
+          {copied ? 'Copied' : 'Copy'}
+        </Button>
+      </XStack>
+
+      <YStack bg="$color1" borderWidth={1} borderColor="$borderColor" rounded="$4" p="$3" style={{ overflowX: 'auto' }}>
+        <Text
+          color="$color11"
+          style={{
+            fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+            whiteSpace: 'pre',
+            fontSize: 12,
+            lineHeight: 1.6,
+          }}
+        >
+          {sample.code}
+        </Text>
+      </YStack>
+    </LandingCard>
+  )
+}

package/src/landing/logic.ts

@@ -0,0 +1,47 @@
+/**
+ * Landing — PURE link helpers (no UI, no I/O), unit-testable. Builds the real docs
+ * / API / support links a landing rail and code samples point at, derived from the
+ * brand docs host so a Lux/Zoo console links to ITS OWN surfaces (never hardcoded).
+ */
+
+/** Apex domain from a docs URL (https://docs.hanzo.ai → hanzo.ai). */
+export function apexFromDocs(docsUrl: string): string {
+  return docsUrl
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '')
+    .replace(/^docs\./, '')
+    .trim()
+}
+
+/** The brand API base for code samples, e.g. https://api.hanzo.ai/v1. */
+export function apiBaseFromDocs(docsUrl: string): string {
+  return `https://api.${apexFromDocs(docsUrl)}/v1`
+}
+
+/** A docs URL for a product, with an optional sub-path. */
+export function landingDocsUrl(docsUrl: string, product: string, sub?: string): string {
+  const base = `${docsUrl.replace(/\/+$/, '')}/${product}`
+  return sub ? `${base}/${sub}` : base
+}
+
+/** The brand support mailbox derived from the docs host (docs.hanzo.ai → support@hanzo.ai). */
+export function supportMailto(docsUrl: string): string {
+  return `mailto:support@${apexFromDocs(docsUrl)}`
+}
+
+/** The standard doc links every product's resource rail shows. */
+export interface StandardResources {
+  docs: string
+  quickstart: string
+  examples: string
+  api: string
+}
+
+export function standardResources(docsUrl: string, product: string): StandardResources {
+  return {
+    docs: landingDocsUrl(docsUrl, product),
+    quickstart: landingDocsUrl(docsUrl, product, 'quickstart'),
+    examples: landingDocsUrl(docsUrl, product, 'examples'),
+    api: landingDocsUrl(docsUrl, product, 'api-reference'),
+  }
+}

package/src/landing/parts.tsx

@@ -0,0 +1,116 @@
+'use client'
+
+/**
+ * Landing UI atoms — the shared card / action-row / delta-chip language, in a
+ * dark-card idiom. Strictly @hanzo/gui v5 shorthands.
+ */
+import type { ComponentProps, ReactNode } from 'react'
+import { Card, Text, XStack, YStack } from '@hanzo/gui'
+import { TrendingDown, TrendingUp } from '@hanzogui/lucide-icons-2'
+
+/** Open an external URL in a new tab (SSR-guarded). */
+export function openExternal(href: string): void {
+  if (typeof window !== 'undefined') window.open(href, '_blank', 'noopener')
+}
+
+/** A titled dark card — the ONE section container across the landing. */
+export function LandingCard({
+  title,
+  subtitle,
+  actions,
+  children,
+  p = '$4',
+  ...rest
+}: {
+  title?: ReactNode
+  subtitle?: ReactNode
+  actions?: ReactNode
+  children: ReactNode
+  p?: ComponentProps<typeof Card>['p']
+} & Omit<ComponentProps<typeof Card>, 'children' | 'title'>) {
+  return (
+    <Card borderWidth={1} borderColor="$borderColor" bg="$color2" rounded="$5" p={p} gap="$3.5" {...rest}>
+      {title || actions ? (
+        <XStack justify="space-between" items="center" gap="$3" flexWrap="wrap">
+          <YStack gap="$0.5" flex={1} minW={120}>
+            {title ? (
+              <Text fontSize="$5" fontWeight="800" color="$color12">
+                {title}
+              </Text>
+            ) : null}
+            {subtitle ? (
+              <Text fontSize="$2" color="$color10">
+                {subtitle}
+              </Text>
+            ) : null}
+          </YStack>
+          {actions ? (
+            <XStack gap="$2" items="center">
+              {actions}
+            </XStack>
+          ) : null}
+        </XStack>
+      ) : null}
+      {children}
+    </Card>
+  )
+}
+
+/** One tappable action row (icon + label + optional sub-line). */
+export function ActionRow({
+  icon,
+  label,
+  sub,
+  onPress,
+}: {
+  icon?: ReactNode
+  label: string
+  sub?: string
+  onPress: () => void
+}) {
+  return (
+    <XStack items="center" gap="$3" py="$2" px="$2" rounded="$3" cursor="pointer" hoverStyle={{ bg: '$color3' }} onPress={onPress}>
+      <YStack width={30} height={30} items="center" justify="center" rounded="$3" bg="$color3">
+        {icon}
+      </YStack>
+      <YStack flex={1} minW={0} gap="$0.5">
+        <Text fontSize="$3" color="$color12" numberOfLines={1}>
+          {label}
+        </Text>
+        {sub ? (
+          <Text fontSize="$1" color="$color10" numberOfLines={1}>
+            {sub}
+          </Text>
+        ) : null}
+      </YStack>
+      <Text fontSize="$4" color="$color9">
+        ›
+      </Text>
+    </XStack>
+  )
+}
+
+/** An ↑/↓ delta chip. Up→green, down→red, null→muted em-dash. Direction only (honest). */
+export function DeltaChip({ pct }: { pct: number | null }) {
+  if (pct == null || !Number.isFinite(pct)) {
+    return (
+      <Text fontSize="$1" color="$color10">
+        —
+      </Text>
+    )
+  }
+  const rounded = Math.round(pct)
+  const up = rounded >= 0
+  const color = up ? '#23c562' : '#ff5d8f'
+  const Icon = up ? TrendingUp : TrendingDown
+  const sign = rounded > 0 ? '+' : rounded < 0 ? '−' : ''
+  return (
+    <XStack items="center" gap="$1">
+      <Icon size={13} color={color} />
+      <Text fontSize="$1" fontWeight="700" style={{ color }}>
+        {sign}
+        {Math.abs(rounded)}%
+      </Text>
+    </XStack>
+  )
+}

package/src/landing/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Landing — the shared config contract every product supplies to get a polished
+ * landing/overview: a hero, live count-up metrics, an interactive code-sample
+ * block, and a resources rail. One landing system, DRY across products.
+ *
+ * Types only — erased at build; the pure link logic lives in `logic.ts`.
+ */
+import type { ReactElement, ReactNode } from 'react'
+
+import type { IconComponent } from '../types'
+
+/** Languages the interactive code block offers. */
+export type CodeLang = 'curl' | 'python' | 'ts' | 'js'
+
+/** One copyable code sample — the REAL API call for the product. */
+export interface CodeSample {
+  lang: CodeLang
+  /** Tab label, e.g. "cURL", "Python", "TypeScript", "JavaScript". */
+  label: string
+  code: string
+}
+
+/** A call-to-action — an in-app handler OR an external link. `icon` is a rendered
+ *  element so it satisfies the Button `icon` prop. */
+export interface LandingAction {
+  label: string
+  onPress?: () => void
+  href?: string
+  icon?: ReactElement
+}
+
+/** One headline metric — a real value (null → honest "—"), optional trend + delta. */
+export interface LandingMetric {
+  key: string
+  label: string
+  /** Current value, or null when the backend doesn't report it (renders "—"). */
+  value: number | null
+  /** Formats the (count-up) value; defaults to a localized integer. */
+  format?: (n: number) => string
+  /** Real time series for the sparkline (≥2 points, else omitted — never faked). */
+  series?: number[]
+  /** Fractional/percent change vs the prior window; null → honest em-dash. */
+  deltaPct?: number | null
+  icon?: ReactNode
+  /** A small honest caption shown when there is no series (e.g. "Awaiting metering"). */
+  hint?: string
+}
+
+/** A resource rail row (Documentation / Quick Start / Examples / Support …). */
+export interface ResourceLink {
+  id: string
+  label: string
+  sub?: string
+  href?: string
+  onPress?: () => void
+  icon?: ReactNode
+}
+
+/**
+ * The full landing config a product composes. `metrics` (controlled by the parent)
+ * OR `loadMetrics` (self-loading + polling) drives the live KPI row; supply one.
+ */
+export interface LandingConfig {
+  productId: string
+  title: string
+  /** One-line "what it is". */
+  tagline: string
+  icon?: IconComponent
+  /** Docs host base the rail/samples derive links from (e.g. 'https://docs.hanzo.ai'). */
+  docsUrl: string
+  /** Docs path segment under the docs host (e.g. 'embeddings'). */
+  docsProduct: string
+  /** Brand name shown in the hero kicker (omitted when unset). */
+  brandName?: string
+  /** Accent color for the hero + sparklines (defaults to the palette head). */
+  accent?: string
+  /** Community link for the resource rail (row omitted when unset). */
+  discordUrl?: string
+  /** Support email override (defaults to `support@<docs apex>`). */
+  supportEmail?: string
+  /** The hero's primary + optional secondary CTA. */
+  primary?: LandingAction
+  secondary?: LandingAction
+  /** Controlled metrics (parent owns the data). */
+  metrics?: LandingMetric[]
+  /** Self-loading metrics (real data / honest gaps) — used with `pollMs`. */
+  loadMetrics?: () => Promise<LandingMetric[]>
+  /** Poll interval for `loadMetrics` in ms (0/undefined → load once, no poll). */
+  pollMs?: number
+  /** Interactive, copyable code samples (curl/python/ts/js). */
+  samples?: CodeSample[]
+  /** A "Run"/"Try in Playground" affordance for the code block. */
+  run?: LandingAction
+  /** Quick-action rows appended to the resource rail. */
+  actions?: LandingAction[]
+  /** Extra resource rows appended after the standard ones. */
+  resources?: ResourceLink[]
+}

package/src/motion/hooks.ts

@@ -0,0 +1,98 @@
+'use client'
+
+/**
+ * Overview React hooks — the thin rAF/interval drivers on top of the pure
+ * `motion.ts` math. Each hook owns exactly one browser concern (animation frames,
+ * the poll clock, reduced-motion, tab visibility) and cleans itself up on unmount
+ * (no leaked intervals/frames).
+ */
+import { useEffect, useRef, useState } from 'react'
+
+import { countUpValue, progress } from './motion'
+
+/** `true` when the user asked for reduced motion — every animation short-circuits to its end state. */
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false)
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)')
+    const on = () => setReduced(mq.matches)
+    on()
+    // addEventListener is the modern API; older Safari uses addListener.
+    if (mq.addEventListener) mq.addEventListener('change', on)
+    else mq.addListener(on)
+    return () => {
+      if (mq.removeEventListener) mq.removeEventListener('change', on)
+      else mq.removeListener(on)
+    }
+  }, [])
+  return reduced
+}
+
+/** `true` when the document is hidden (background tab) — the poll clock pauses. */
+export function usePageHidden(): boolean {
+  const [hidden, setHidden] = useState(false)
+  useEffect(() => {
+    if (typeof document === 'undefined') return
+    const on = () => setHidden(document.visibilityState === 'hidden')
+    on()
+    document.addEventListener('visibilitychange', on)
+    return () => document.removeEventListener('visibilitychange', on)
+  }, [])
+  return hidden
+}
+
+/**
+ * Animate a number from its previous value to `target` on the eased count-up curve.
+ * Returns the value to display right now. When `enabled` is false (reduced motion,
+ * or count-up turned off in config), it snaps to `target` — the tile still shows the
+ * real number, just without the tween. Cleans up its rAF on unmount/retarget.
+ */
+export function useCountUp(target: number, enabled: boolean, durationMs = 700): number {
+  const [value, setValue] = useState(target)
+  // The value currently ON SCREEN, tracked every frame. A retarget mid-flight
+  // animates from HERE (not the previous target), so a new poll never snaps the
+  // digits back before easing — smooth all the way.
+  const shownRef = useRef(target)
+  const frameRef = useRef<number | null>(null)
+
+  useEffect(() => {
+    const from = shownRef.current
+    if (!enabled || from === target) {
+      shownRef.current = target
+      setValue(target)
+      return
+    }
+    const startedAt = typeof performance !== 'undefined' ? performance.now() : Date.now()
+    const tick = () => {
+      const now = typeof performance !== 'undefined' ? performance.now() : Date.now()
+      const t = progress(startedAt, now, durationMs)
+      const v = countUpValue(from, target, t)
+      shownRef.current = v
+      setValue(v)
+      if (t < 1) frameRef.current = requestAnimationFrame(tick)
+    }
+    frameRef.current = requestAnimationFrame(tick)
+    return () => {
+      if (frameRef.current != null) cancelAnimationFrame(frameRef.current)
+    }
+  }, [target, enabled, durationMs])
+
+  return value
+}
+
+/**
+ * A monotonic tick that fires every `everyMs` while the tab is visible, paused when
+ * `everyMs <= 0`. The consumer refetches on each tick. Self-clearing on unmount and
+ * on interval change — no stacked timers. Returns the tick count (a dependency the
+ * caller can watch) and a `bump()` to force an immediate refetch (e.g. range change).
+ */
+export function usePoll(everyMs: number): { tick: number; bump: () => void } {
+  const [tick, setTick] = useState(0)
+  useEffect(() => {
+    if (everyMs <= 0) return
+    const id = setInterval(() => setTick((n) => n + 1), everyMs)
+    return () => clearInterval(id)
+  }, [everyMs])
+  return { tick, bump: () => setTick((n) => n + 1) }
+}

package/src/motion/motion.ts

@@ -0,0 +1,76 @@
+/**
+ * Overview motion — the PURE math behind the "videogame-like" feel, kept
+ * out of the React components so it is unit-testable in the node env (no jsdom).
+ * The `.tsx` tiles are thin wrappers that drive `requestAnimationFrame` with these
+ * functions.
+ *
+ * Three primitives, one law each:
+ *   - `easeOutCubic` / `countUpValue` — a number animates from a→b on an eased
+ *     curve; at `t>=1` it lands EXACTLY on `b` (no float drift, no fabricated
+ *     overshoot). Reduced-motion callers pass `t=1` and get `b` immediately.
+ *   - `pushSample` — a live sparkline is a bounded ring of the most-recent real
+ *     samples; a new reading appends and evicts the oldest past `cap`. It never
+ *     invents points — an empty history stays empty (the tile shows no trend).
+ *   - `shouldTick` — a self-correcting poll clock: given the last tick and now, it
+ *     answers whether it is time to refetch, so a throttled live loop can't drift
+ *     or stack overlapping fetches.
+ *
+ * Honesty: none of these create data. Count-up interpolates BETWEEN two real
+ * values the caller already has; the sparkline ring holds only real samples.
+ */
+
+/** Ease-out cubic — fast then settling, the house count-up curve. Clamps to [0,1]. */
+export const easeOutCubic = (t: number): number => {
+  const x = t <= 0 ? 0 : t >= 1 ? 1 : t
+  return 1 - Math.pow(1 - x, 3)
+}
+
+/**
+ * The displayed value at normalized progress `t` (0..1) animating `from`→`to`.
+ * Lands exactly on `to` at t>=1 (and returns `to` for a non-finite `from`, so a
+ * first-ever value counts up from 0 only when the caller seeds `from=0`).
+ */
+export function countUpValue(from: number, to: number, t: number): number {
+  if (!Number.isFinite(to)) return Number.isFinite(from) ? from : 0
+  if (t >= 1) return to
+  const base = Number.isFinite(from) ? from : to
+  return base + (to - base) * easeOutCubic(t)
+}
+
+/** Normalized progress for an animation started at `startedAt`, now `now`, over `durationMs`. */
+export function progress(startedAt: number, now: number, durationMs: number): number {
+  if (durationMs <= 0) return 1
+  return Math.min(1, Math.max(0, (now - startedAt) / durationMs))
+}
+
+/**
+ * Append `sample` to a live-sparkline ring, evicting oldest beyond `cap`. Returns
+ * a NEW array (never mutates) so React state updates cleanly. A non-finite sample
+ * is dropped — the trend only ever holds real readings.
+ */
+export function pushSample(history: readonly number[], sample: number, cap: number): number[] {
+  if (!Number.isFinite(sample)) return history.slice()
+  const next = [...history, sample]
+  return next.length > cap ? next.slice(next.length - cap) : next
+}
+
+/**
+ * Poll clock. `true` when `now - lastTickAt >= everyMs` (time to refetch). A
+ * non-positive interval disables polling (always `false`) so a config can turn
+ * live updates off without a special case.
+ */
+export function shouldTick(lastTickAt: number, now: number, everyMs: number): boolean {
+  if (everyMs <= 0) return false
+  return now - lastTickAt >= everyMs
+}
+
+/**
+ * Effective poll interval given a requested `everyMs`, a floor, and whether the
+ * document is hidden. Returns 0 (paused) when hidden — a background tab must not
+ * burn the backend — and never goes below `floorMs` (throttle guard) when active.
+ */
+export function effectiveInterval(everyMs: number, floorMs: number, hidden: boolean): number {
+  if (everyMs <= 0) return 0
+  if (hidden) return 0
+  return Math.max(floorMs, everyMs)
+}