@graph8/sdk 0.362.0 → 0.370.0

package/blocks/_foundation/components/connect-graph8.tsx

@@ -0,0 +1,280 @@
+"use client";
+
+/**
+ * Connect graph8 (local preview only): the first-run screen of a created app when the server has no graph8 API
+ * key yet, and the place to replace or remove the key later.
+ *
+ * Calls this app's own `/api/g8-connect` route (g8/server/connect.ts), never graph8 directly:
+ *   GET    status: is a key configured, where from (server environment or the pasted file), whose is it
+ *   POST   { key }: the server checks the key with a free read (GET /me), then stores it in .g8/local-key
+ *   DELETE remove the stored key
+ * No billable, external or destructive graph8 operation (removing the local file only forgets the key here).
+ * The key goes from the input to the server once and is never kept in browser state after submit, storage or URL.
+ *
+ * Exports:
+ *   - ConnectGraph8Panel: the full-page panel (no required props).
+ *   - G8ConnectGate: wraps the app; in `next dev` it shows the screen until a key is connected, plus a small
+ *     "Local preview" button to manage the key. In a production build it renders its children and nothing else.
+ */
+
+import { useCallback, useEffect, useId, useState, type FormEvent, type ReactNode } from "react";
+import { CheckCircle2, ExternalLink, KeyRound, Loader2, X } from "lucide-react";
+import { Button, Input, cn } from "@graph8/sdk/ui";
+import { DEFAULT_BRAND, brandUrl, useBrand } from "../hooks/use-brand";
+
+export const CONNECT_PATH = "/api/g8-connect";
+/** Where API keys are managed, on the platform's web app (white-label: see hooks/use-brand). */
+const KEYS_PATH = "/studio/settings?tab=api";
+
+export interface ConnectStatus {
+  localPreview: boolean;
+  connected: boolean;
+  source: "env" | "file" | null;
+  keyHint?: string;
+  keyFile?: string;
+  account?: { name?: string; workspace?: string; scopes?: string[] };
+  problem?: string;
+}
+
+async function readJson(res: Response): Promise<Record<string, unknown>> {
+  return (await res.json().catch(() => ({}))) as Record<string, unknown>;
+}
+
+/** GET the status. Null when the route does not exist or refuses (production, not this machine). */
+export async function fetchConnectStatus(): Promise<ConnectStatus | null> {
+  try {
+    const res = await fetch(CONNECT_PATH, { headers: { accept: "application/json" }, cache: "no-store" });
+    if (!res.ok) return null;
+    const body = await readJson(res);
+    return body.localPreview === true ? (body as unknown as ConnectStatus) : null;
+  } catch {
+    return null;
+  }
+}
+
+function accountLine(s: ConnectStatus, platform = DEFAULT_BRAND.linkLabel): string {
+  const a = s.account ?? {};
+  return [a.name, a.workspace].filter(Boolean).join(" at ") || `a ${platform} key`;
+}
+
+export interface ConnectGraph8PanelProps {
+  /** Status from a previous GET (the gate passes it); fetched on mount when absent. */
+  status?: ConnectStatus | null;
+  /** Called after a key is stored or removed, with the new status. */
+  onChange?: (status: ConnectStatus) => void;
+  className?: string;
+}
+
+/** Paste, check and store the server's graph8 API key; replace or remove it. */
+export function ConnectGraph8Panel({ status: initial, onChange, className }: ConnectGraph8PanelProps) {
+  const [status, setStatus] = useState<ConnectStatus | null | undefined>(initial);
+  const [key, setKey] = useState("");
+  const [busy, setBusy] = useState<"save" | "remove" | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [replacing, setReplacing] = useState(false);
+  const inputId = useId();
+  const brand = useBrand();
+
+  useEffect(() => {
+    if (initial === undefined) void fetchConnectStatus().then(setStatus);
+  }, [initial]);
+
+  const apply = (next: ConnectStatus) => {
+    setStatus(next);
+    setReplacing(false);
+    onChange?.(next);
+  };
+
+  const submit = async (e: FormEvent) => {
+    e.preventDefault();
+    if (!key.trim() || busy) return;
+    setBusy("save");
+    setError(null);
+    try {
+      const res = await fetch(CONNECT_PATH, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ key: key.trim() }) });
+      const body = await readJson(res);
+      setKey("");
+      if (!res.ok) setError(typeof body.message === "string" ? body.message : `Could not save the key (HTTP ${res.status}).`);
+      else apply(body as unknown as ConnectStatus);
+    } catch {
+      setError("Could not reach this app's server. Is `npm run dev` still running?");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const remove = async () => {
+    setBusy("remove");
+    setError(null);
+    try {
+      const res = await fetch(CONNECT_PATH, { method: "DELETE" });
+      const body = await readJson(res);
+      if (!res.ok) setError(typeof body.message === "string" ? body.message : `Could not remove the key (HTTP ${res.status}).`);
+      else apply(body as unknown as ConnectStatus);
+    } catch {
+      setError("Could not reach this app's server. Is `npm run dev` still running?");
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const connected = Boolean(status?.connected);
+  const fromEnv = status?.source === "env";
+  const showForm = !fromEnv && (!status?.source || replacing);
+
+  return (
+    <section aria-labelledby={`${inputId}-title`} className={cn("mx-auto flex w-full max-w-md flex-col gap-5 px-4 py-14", className)}>
+      <div className="flex flex-col gap-2">
+        <div aria-hidden className="flex size-10 items-center justify-center rounded-lg border border-border bg-muted text-foreground">
+          <KeyRound className="size-5" strokeWidth={1.5} />
+        </div>
+        <h1 id={`${inputId}-title`} className="text-lg font-medium text-foreground">
+          {connected ? `Connected to ${brand.linkLabel}` : `Connect ${brand.linkLabel}`}
+        </h1>
+        <p className="text-sm leading-5 text-text-color-muted">
+          This app reads and writes your {brand.linkLabel} data through its own server. Paste an API key once: the server checks
+          it and keeps it in <code className="text-xs">{status?.keyFile ?? ".g8/local-key"}</code> on this computer. The
+          browser never stores it.
+        </p>
+      </div>
+
+      {status?.source ? (
+        <div className="flex items-start gap-3 rounded-lg border border-border p-3 text-sm">
+          {connected ? (
+            <CheckCircle2 aria-hidden className="mt-0.5 size-4 shrink-0 text-positive-foreground" strokeWidth={1.5} />
+          ) : (
+            <X aria-hidden className="mt-0.5 size-4 shrink-0 text-error-foreground" strokeWidth={1.5} />
+          )}
+          <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+            <span className="text-foreground">{connected ? accountLine(status, brand.linkLabel) : "The key no longer works"}</span>
+            <span className="text-xs text-text-color-muted">
+              Key {status.keyHint ?? ""} from {fromEnv ? "the server environment (.env.local)" : status.keyFile ?? ".g8/local-key"}
+              {status.problem ? `. ${status.problem}` : ""}
+            </span>
+            {fromEnv ? <span className="text-xs text-text-color-muted">To change it, edit .env.local and restart the dev server.</span> : null}
+          </div>
+        </div>
+      ) : null}
+
+      {showForm ? (
+        <form onSubmit={submit} className="flex flex-col gap-2">
+          <label htmlFor={inputId} className="text-sm font-medium text-foreground">
+            {brand.linkLabel} API key
+          </label>
+          <Input
+            id={inputId}
+            type="password"
+            autoComplete="off"
+            spellCheck={false}
+            value={key}
+            onChange={(e) => setKey(e.target.value)}
+            placeholder="Paste the key"
+            aria-invalid={error ? true : undefined}
+            aria-describedby={error ? `${inputId}-error` : undefined}
+          />
+          {error ? (
+            <p id={`${inputId}-error`} role="alert" className="text-xs text-error-foreground">
+              {error}
+            </p>
+          ) : null}
+          <div className="flex items-center gap-2 pt-1">
+            <Button type="submit" disabled={!key.trim() || busy !== null}>
+              {busy === "save" ? <Loader2 aria-hidden className="size-4 animate-spin" /> : null}
+              {busy === "save" ? "Checking" : "Connect"}
+            </Button>
+            {replacing ? (
+              <Button type="button" variant="ghost" onClick={() => setReplacing(false)}>
+                Cancel
+              </Button>
+            ) : null}
+          </div>
+        </form>
+      ) : status?.source === "file" ? (
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-2">
+            <Button type="button" variant="outline" onClick={() => setReplacing(true)} disabled={busy !== null}>
+              Replace key
+            </Button>
+            <Button type="button" variant="ghost" onClick={() => void remove()} disabled={busy !== null}>
+              {busy === "remove" ? <Loader2 aria-hidden className="size-4 animate-spin" /> : null}
+              Remove key
+            </Button>
+          </div>
+          {error ? (
+            <p role="alert" className="text-xs text-error-foreground">
+              {error}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+
+      <a href={brandUrl(brand, KEYS_PATH)} target="_blank" rel="noreferrer" className="inline-flex items-center gap-1 text-sm text-foreground underline-offset-4 hover:underline">
+        Get a key in {brand.linkLabel} (Settings, API)
+        <ExternalLink aria-hidden className="size-3.5" strokeWidth={1.5} />
+      </a>
+      <p className="text-xs leading-5 text-text-color-muted">
+        Local preview: this screen and the data routes only answer requests from this computer while you run the dev
+        server. Before you deploy, set <code>authorize</code> in app/api/g8/[...path]/route.ts and the key in your host&apos;s
+        environment; <code>npx @graph8/sdk doctor --production</code> checks both.
+      </p>
+    </section>
+  );
+}
+
+export interface G8ConnectGateProps {
+  children: ReactNode;
+  /** Hide the small "Local preview" button once connected. Default false. */
+  hideManageButton?: boolean;
+}
+
+/**
+ * In `next dev`: shows ConnectGraph8Panel instead of the app until a key is connected, and a small button to
+ * manage the key afterwards. In a production build (and when /api/g8-connect is missing or refuses) it is
+ * exactly its children: no request, no extra markup.
+ */
+export function G8ConnectGate({ children, hideManageButton = false }: G8ConnectGateProps) {
+  const dev = process.env.NODE_ENV !== "production";
+  const [status, setStatus] = useState<ConnectStatus | null | undefined>(dev ? undefined : null);
+  const [managing, setManaging] = useState(false);
+  const brand = useBrand();
+
+  useEffect(() => {
+    if (dev) void fetchConnectStatus().then(setStatus);
+  }, [dev]);
+
+  const changed = useCallback((next: ConnectStatus) => {
+    setStatus(next);
+    // Every screen loaded its data with the old (or no) key: start them again.
+    if (next.connected) window.location.reload();
+  }, []);
+
+  if (!status) return <>{children}</>;
+  if (!status.connected || managing) {
+    return (
+      <div className="relative">
+        {managing && status.connected ? (
+          <Button type="button" variant="ghost" size="sm" className="absolute right-4 top-4" onClick={() => setManaging(false)}>
+            Back to the app
+          </Button>
+        ) : null}
+        <ConnectGraph8Panel status={status} onChange={changed} />
+      </div>
+    );
+  }
+  return (
+    <>
+      {children}
+      {hideManageButton ? null : (
+        <button
+          type="button"
+          onClick={() => setManaging(true)}
+          title={`Local preview, connected as ${accountLine(status, brand.linkLabel)}. Manage the ${brand.linkLabel} key.`}
+          className="fixed bottom-3 right-3 z-40 inline-flex h-7 items-center gap-1.5 rounded-md border border-border bg-background px-2 text-xs text-text-color-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <KeyRound aria-hidden className="size-3.5" strokeWidth={1.5} />
+          Local preview
+        </button>
+      )}
+    </>
+  );
+}

package/blocks/_foundation/components/screen/index.ts

@@ -12,6 +12,7 @@ export * from "./entity-avatar";
 export * from "./form-sheet";
 export * from "./key-value-list";
 export * from "./screen-layout";
+export * from "./record-link";
 export * from "./section-card";
 export * from "./sparkline";
 export * from "./split-view";

package/blocks/_foundation/components/screen/record-link.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+/**
+ * RecordLink: a record's name as a real `<a href>`. A plain click runs `onOpen` (the screen opens the record
+ * the way it always did: its own URL state or component state); Cmd/Ctrl/Shift/Alt-click and middle-click fall
+ * through to the browser, so "open in a new tab" lands on the same screen with the record open. The href is
+ * `?<param>=<id>`, where `param` is the URL param the OWNING screen reads for this record type. Without a `param`
+ * there is no honest href (a new tab would open nothing, or the wrong record), so it renders a plain button that
+ * only runs `onOpen`. The href is relative (SSR-safe) and is completed with the current query when the pointer or
+ * focus reaches it, so Cmd-click keeps `tab`, `pipeline` and the rest. Add `full` for `view=full`. Only a screen
+ * without an `onOpen` of its own should pass `writeUrl`, which makes a plain click write the param itself.
+ *
+ * SDK operations: none.
+ */
+import type { MouseEvent, ReactNode, SyntheticEvent } from "react";
+import { cn } from "@graph8/sdk/ui";
+import { writeUrlParam } from "../../hooks/use-url-state";
+
+export interface RecordLinkProps {
+  /** The record id written to the URL param. */
+  id: string | number;
+  /** URL param the owning screen reads for this record. Omit it when the screen reads none: a button is rendered. */
+  param?: string;
+  /** Also set `view=full` (the record as a full page). */
+  full?: boolean;
+  /** Runs on a plain click: open the record the way the screen does (its URL setter or component state). */
+  onOpen?: () => void;
+  /** A plain click also writes `param` (and `view`) to the URL itself. Default false: `onOpen` owns the state. */
+  writeUrl?: boolean;
+  className?: string;
+  children: ReactNode;
+}
+
+/** Relative href that opens `id`: `?param=id[&view=full]`. Depends on nothing but its arguments, so server and client agree. */
+export function recordHref(id: string | number, param: string, full = false): string {
+  return `?${param}=${encodeURIComponent(String(id))}${full ? "&view=full" : ""}`;
+}
+
+/** The same href merged into the page's current query (call it at event time, never during render). */
+export function currentRecordHref(id: string | number, param: string, full = false): string {
+  const url = new URL(window.location.href);
+  url.searchParams.set(param, String(id));
+  if (full) url.searchParams.set("view", "full");
+  else url.searchParams.delete("view");
+  return `${url.pathname}${url.search}${url.hash}`;
+}
+
+export function RecordLink({ id, param, full = false, onOpen, writeUrl = false, className, children }: RecordLinkProps) {
+  const key = param ?? (writeUrl ? "id" : undefined);
+  const cls = cn("font-medium text-foreground underline-offset-2 hover:underline focus-visible:underline", className);
+  if (!key) {
+    return (
+      <button type="button" className={cn(cls, "text-left")} onClick={(e) => { e.stopPropagation(); onOpen?.(); }}>
+        {children}
+      </button>
+    );
+  }
+  const onClick = (e: MouseEvent<HTMLAnchorElement>): void => {
+    e.stopPropagation(); // the row around it also opens the record: do not do it twice
+    if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    if (!onOpen && !writeUrl) return; // nothing to do in place: let the browser follow the href
+    e.preventDefault();
+    if (writeUrl) {
+      writeUrlParam("view", full ? "full" : null);
+      writeUrlParam(key, String(id), { push: true });
+    }
+    onOpen?.();
+  };
+  /** Complete the href with the current query just before the browser can use it (hover, press, focus, context menu). */
+  const complete = (e: SyntheticEvent<HTMLAnchorElement>): void => e.currentTarget.setAttribute("href", currentRecordHref(id, key, full));
+  return (
+    <a href={recordHref(id, key, full)} onClick={onClick} onMouseEnter={complete} onMouseDown={complete} onFocus={complete} onContextMenu={complete} onTouchStart={complete} className={cls}>
+      {children}
+    </a>
+  );
+}

package/blocks/_foundation/components/screen/time-series-chart-recharts.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+/**
+ * The recharts half of TimeSeriesChart, in its own module so it is code-split: `time-series-chart.tsx`
+ * loads it on demand (React.lazy), and pages without a chart never download recharts. Import this file
+ * directly only if you need the chart rendered synchronously (it then joins your page bundle).
+ *
+ * SDK operations: none. Peer: recharts.
+ */
+import { useMemo } from "react";
+import { Area, AreaChart, Bar, BarChart, CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
+import { ChartContainer, ChartTooltip, ChartTooltipContent, cn, type ChartConfig } from "@graph8/sdk/ui";
+import { TONE_VAR, defaultFormatX, defaultFormatY } from "./time-series-format";
+import type { TimeSeries, TimeSeriesChartProps } from "./time-series-format";
+
+export function TimeSeriesChartRecharts({ data, xKey, series, kind = "line", height = 220, formatX = defaultFormatX, formatY = defaultFormatY, stacked, className }: TimeSeriesChartProps) {
+  const config = useMemo<ChartConfig>(
+    () => Object.fromEntries(series.map((s) => [s.key, { label: s.label ?? s.key, color: TONE_VAR[s.tone ?? "ink"] }])),
+    [series],
+  );
+  const axes = (
+    <>
+      <CartesianGrid vertical={false} strokeDasharray="0" stroke="var(--border)" strokeOpacity={0.9} />
+      <XAxis dataKey={xKey} tickLine={false} axisLine={false} tickMargin={8} minTickGap={24} tickFormatter={formatX} tick={{ fontSize: 11 }} />
+      <YAxis width={36} tickLine={false} axisLine={false} tickMargin={4} tickFormatter={formatY} tick={{ fontSize: 11 }} allowDecimals={false} />
+      <ChartTooltip cursor={{ stroke: "var(--border)" }} content={<ChartTooltipContent labelFormatter={(v) => formatX(v)} formatter={(v, name) => [`${formatY(Number(v))} `, String(config[String(name)]?.label ?? name)]} indicator="line" />} />
+    </>
+  );
+  const stroke = (s: TimeSeries) => ({
+    stroke: `var(--color-${s.key})`,
+    strokeWidth: s.tone === "prior" ? 1.25 : 1.5,
+    strokeDasharray: s.tone === "prior" ? "4 3" : undefined,
+    dot: false as const,
+    activeDot: { r: 3 },
+    isAnimationActive: false,
+  });
+  const style = { height } as const;
+
+  return (
+    <ChartContainer config={config} className={cn("aspect-auto w-full text-text-color-muted", className)} style={style} data-testid="time-series-chart">
+      {kind === "bar" ? (
+        <BarChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }} barCategoryGap="25%">
+          {axes}
+          {series.map((s) => (
+            <Bar key={s.key} dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone ? 0.85 : 1} radius={[2, 2, 0, 0]} isAnimationActive={false} />
+          ))}
+        </BarChart>
+      ) : kind === "area" ? (
+        <AreaChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
+          {axes}
+          {series.map((s) => (
+            <Area key={s.key} type="monotone" dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone === "prior" ? 0 : 0.06} {...stroke(s)} />
+          ))}
+        </AreaChart>
+      ) : (
+        <LineChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
+          {axes}
+          {series.map((s) => (
+            <Line key={s.key} type="monotone" dataKey={s.key} name={s.key} {...stroke(s)} />
+          ))}
+        </LineChart>
+      )}
+    </ChartContainer>
+  );
+}

package/blocks/_foundation/components/screen/time-series-chart.tsx

@@ -6,109 +6,27 @@
  * A `prior` series is the dashed warm-grey comparison. Chrome is recessive: hairline gridlines, muted
  * axis labels, no borders. Built on recharts through the UI kit's ChartContainer.
  *
+ * recharts is code-split: the chart module (time-series-chart-recharts.tsx) loads on first render, with a
+ * same-height skeleton meanwhile, so a page that shows no chart never downloads it. Same props as before.
+ *
  * SDK operations: none. Peer: recharts.
  */
-import { useMemo } from "react";
-import { Area, AreaChart, Bar, BarChart, CartesianGrid, Line, LineChart, XAxis, YAxis } from "recharts";
-import { ChartContainer, ChartTooltip, ChartTooltipContent, cn, type ChartConfig } from "@graph8/sdk/ui";
-import type { Tone } from "./status-pill";
-
-export interface TimeSeries {
-  /** The field of each row to plot. */
-  key: string;
-  label?: string;
-  /** Ink unless the direction means good or bad. "prior" is the dashed comparison line. */
-  tone?: Tone | "prior";
-}
-
-export interface TimeSeriesChartProps {
-  data: Array<Record<string, unknown>>;
-  /** Field holding the x value (an ISO date, a label). */
-  xKey: string;
-  series: TimeSeries[];
-  kind?: "line" | "area" | "bar";
-  height?: number;
-  /** Format an x value for the axis ("2026-10-01" -> "Oct 1"). */
-  formatX?: (value: unknown) => string;
-  /** Format a y value for the axis and the tooltip. */
-  formatY?: (value: number) => string;
-  /** Stack bars/areas. */
-  stacked?: boolean;
-  className?: string;
-}
+import { Suspense, lazy } from "react";
+import { Skeleton, cn } from "@graph8/sdk/ui";
+import type { TimeSeriesChartProps } from "./time-series-format";
 
-const TONE_VAR: Record<NonNullable<TimeSeries["tone"]> | "ink", string> = {
-  ink: "var(--foreground)",
-  neutral: "var(--text-color-muted)",
-  info: "var(--info-foreground)",
-  positive: "var(--positive-foreground)",
-  warning: "var(--warning-foreground)",
-  negative: "var(--error-foreground)",
-  prior: "var(--text-color-muted)",
-};
+export type { TimeSeries, TimeSeriesChartProps } from "./time-series-format";
+export { defaultFormatX, defaultFormatY } from "./time-series-format";
 
-export function defaultFormatX(value: unknown): string {
-  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
-    const d = new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
-    if (!Number.isNaN(d.getTime())) return d.toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: value.length === 10 ? "UTC" : undefined });
-  }
-  return String(value ?? "");
-}
-
-export function defaultFormatY(value: number): string {
-  if (Math.abs(value) >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
-  if (Math.abs(value) >= 10_000) return `${(value / 1_000).toFixed(0)}k`;
-  if (Math.abs(value) >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
-  return value.toLocaleString();
-}
+const Recharts = lazy(() => import("./time-series-chart-recharts").then((m) => ({ default: m.TimeSeriesChartRecharts })));
 
-export function TimeSeriesChart({ data, xKey, series, kind = "line", height = 220, formatX = defaultFormatX, formatY = defaultFormatY, stacked, className }: TimeSeriesChartProps) {
-  const config = useMemo<ChartConfig>(
-    () => Object.fromEntries(series.map((s) => [s.key, { label: s.label ?? s.key, color: TONE_VAR[s.tone ?? "ink"] }])),
-    [series],
+export function TimeSeriesChart(props: TimeSeriesChartProps) {
+  const fallback = (
+    <Skeleton className={cn("w-full", props.className)} style={{ height: props.height ?? 220 }} aria-label="Loading chart" data-testid="time-series-chart-loading" />
   );
-  const axes = (
-    <>
-      <CartesianGrid vertical={false} strokeDasharray="0" stroke="var(--border)" strokeOpacity={0.9} />
-      <XAxis dataKey={xKey} tickLine={false} axisLine={false} tickMargin={8} minTickGap={24} tickFormatter={formatX} tick={{ fontSize: 11 }} />
-      <YAxis width={36} tickLine={false} axisLine={false} tickMargin={4} tickFormatter={formatY} tick={{ fontSize: 11 }} allowDecimals={false} />
-      <ChartTooltip cursor={{ stroke: "var(--border)" }} content={<ChartTooltipContent labelFormatter={(v) => formatX(v)} formatter={(v, name) => [`${formatY(Number(v))} `, String(config[String(name)]?.label ?? name)]} indicator="line" />} />
-    </>
-  );
-  const stroke = (s: TimeSeries) => ({
-    stroke: `var(--color-${s.key})`,
-    strokeWidth: s.tone === "prior" ? 1.25 : 1.5,
-    strokeDasharray: s.tone === "prior" ? "4 3" : undefined,
-    dot: false as const,
-    activeDot: { r: 3 },
-    isAnimationActive: false,
-  });
-  const style = { height } as const;
-
   return (
-    <ChartContainer config={config} className={cn("aspect-auto w-full text-text-color-muted", className)} style={style} data-testid="time-series-chart">
-      {kind === "bar" ? (
-        <BarChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }} barCategoryGap="25%">
-          {axes}
-          {series.map((s) => (
-            <Bar key={s.key} dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone ? 0.85 : 1} radius={[2, 2, 0, 0]} isAnimationActive={false} />
-          ))}
-        </BarChart>
-      ) : kind === "area" ? (
-        <AreaChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
-          {axes}
-          {series.map((s) => (
-            <Area key={s.key} type="monotone" dataKey={s.key} name={s.key} stackId={stacked ? "a" : undefined} fill={`var(--color-${s.key})`} fillOpacity={s.tone === "prior" ? 0 : 0.06} {...stroke(s)} />
-          ))}
-        </AreaChart>
-      ) : (
-        <LineChart data={data} margin={{ top: 8, right: 8, left: 0, bottom: 0 }}>
-          {axes}
-          {series.map((s) => (
-            <Line key={s.key} type="monotone" dataKey={s.key} name={s.key} {...stroke(s)} />
-          ))}
-        </LineChart>
-      )}
-    </ChartContainer>
+    <Suspense fallback={fallback}>
+      <Recharts {...props} />
+    </Suspense>
   );
 }

package/blocks/_foundation/components/screen/time-series-format.ts

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * Types and formatters shared by TimeSeriesChart and its lazily loaded recharts implementation.
+ * No recharts here, so importing them costs nothing.
+ */
+import type { Tone } from "./status-pill";
+
+export interface TimeSeries {
+  /** The field of each row to plot. */
+  key: string;
+  label?: string;
+  /** Ink unless the direction means good or bad. "prior" is the dashed comparison line. */
+  tone?: Tone | "prior";
+}
+
+export interface TimeSeriesChartProps {
+  data: Array<Record<string, unknown>>;
+  /** Field holding the x value (an ISO date, a label). */
+  xKey: string;
+  series: TimeSeries[];
+  kind?: "line" | "area" | "bar";
+  height?: number;
+  /** Format an x value for the axis ("2026-10-01" -> "Oct 1"). */
+  formatX?: (value: unknown) => string;
+  /** Format a y value for the axis and the tooltip. */
+  formatY?: (value: number) => string;
+  /** Stack bars/areas. */
+  stacked?: boolean;
+  className?: string;
+}
+
+export const TONE_VAR: Record<NonNullable<TimeSeries["tone"]> | "ink", string> = {
+  ink: "var(--foreground)",
+  neutral: "var(--text-color-muted)",
+  info: "var(--info-foreground)",
+  positive: "var(--positive-foreground)",
+  warning: "var(--warning-foreground)",
+  negative: "var(--error-foreground)",
+  prior: "var(--text-color-muted)",
+};
+
+export function defaultFormatX(value: unknown): string {
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+    const d = new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
+    if (!Number.isNaN(d.getTime())) return d.toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: value.length === 10 ? "UTC" : undefined });
+  }
+  return String(value ?? "");
+}
+
+export function defaultFormatY(value: number): string {
+  if (Math.abs(value) >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+  if (Math.abs(value) >= 10_000) return `${(value / 1_000).toFixed(0)}k`;
+  if (Math.abs(value) >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
+  return value.toLocaleString();
+}
+

package/blocks/_foundation/hooks/use-brand.ts

@@ -0,0 +1,52 @@
+"use client";
+
+/**
+ * White-label: who the app is and what the platform behind it is called. Every block reads the platform's name
+ * and link-outs from here ("Connect in graph8", "Open in graph8", the settings pages they open), so an agency or
+ * reseller can show its own name and its own app URL everywhere, from one config (`g8.config.ts` in a created app,
+ * passed to <BrandProvider>).
+ *
+ *   const brand = useBrand();           // { name, appUrl, linkLabel, logo? }
+ *   brandUrl(brand, "/studio/settings?tab=integrations")
+ *
+ * With no provider, or for any field left out, the default is graph8 itself (app.graph8.com), so nothing changes
+ * for an app that does not brand.
+ */
+
+import { createContext, useContext } from "react";
+
+export interface BrandConfig {
+  /** The app's own name (sidebar, page title). */
+  name: string;
+  /** Base URL of the platform's web app; link-outs append their path. No trailing slash needed. */
+  appUrl: string;
+  /** What the platform is called in copy and links ("Connect in <linkLabel>"). */
+  linkLabel: string;
+  /** Public path or URL of the logo (`/brand/logo.svg`). */
+  logo?: string;
+}
+
+export const DEFAULT_BRAND: BrandConfig = { name: "graph8 app", appUrl: "https://app.graph8.com", linkLabel: "graph8" };
+
+/** Fill the gaps of a partial config with the defaults; an appUrl that is not http(s) falls back to the default. */
+export function resolveBrand(partial?: Partial<BrandConfig> | null): BrandConfig {
+  const p = partial ?? {};
+  const text = (v: unknown, d: string) => (typeof v === "string" && v.trim() ? v.trim() : d);
+  let appUrl = DEFAULT_BRAND.appUrl;
+  if (typeof p.appUrl === "string" && /^https?:\/\/[^\s/]+/i.test(p.appUrl.trim())) appUrl = p.appUrl.trim().replace(/\/+$/, "");
+  const logo = typeof p.logo === "string" && p.logo.trim() ? p.logo.trim() : undefined;
+  return { name: text(p.name, DEFAULT_BRAND.name), appUrl, linkLabel: text(p.linkLabel, DEFAULT_BRAND.linkLabel), ...(logo ? { logo } : {}) };
+}
+
+export const BrandContext = createContext<BrandConfig>(DEFAULT_BRAND);
+
+/** The current brand: the nearest <BrandProvider>'s, else graph8's defaults. */
+export function useBrand(): BrandConfig {
+  return useContext(BrandContext);
+}
+
+/** `appUrl` + a path on the platform (`"/lists"`, `"/studio/settings?tab=api"`); no path gives the app's home. */
+export function brandUrl(brand: Pick<BrandConfig, "appUrl">, path = ""): string {
+  if (!path) return brand.appUrl;
+  return `${brand.appUrl}${path.startsWith("/") || path.startsWith("?") ? "" : "/"}${path}`;
+}