@validation-os/dashboard 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -3,6 +3,142 @@ import { ReactNode } from 'react';
 import { Collection, AnyRecord, Relation } from '@validation-os/core';
 import { Progress, MoverKind, TrajectoryPoint } from '@validation-os/core/derivation';
 
+/**
+ * Everything the instance passes — config only, never secrets. The API base
+ * path points at where the Clerk-gated `@validation-os/api` routes are mounted;
+ * the backend label (from the connector config) shows in the topbar; branding
+ * and the signed-in user are optional cosmetics. Auth is the instance's Clerk
+ * provider that this renders within — no credential reaches the package.
+ */
+interface DashboardConfig {
+    /** Where the API is mounted (default `/api`). */
+    basePath?: string;
+    /** Topbar backend indicator, e.g. "Firestore · doshi-crm". */
+    backendLabel?: string;
+    /** Optional product branding for the sidebar. */
+    branding?: {
+        /** Product name shown next to the mark (default "Validation-OS"). */
+        name?: string;
+        /** One or two letters for the square mark (default "V"). */
+        initials?: string;
+        /** A logo image for the square mark; overrides `initials` when set. */
+        logoUrl?: string;
+    };
+    /** Optional agent label shown in the topbar, e.g. "Claude Code". */
+    agentLabel?: string;
+    /** The signed-in user, for the topbar avatar + name. */
+    user?: {
+        name?: string;
+        caption?: string;
+    };
+    /** Restrict/reorder the registers shown; defaults to all, in order. */
+    registers?: Collection[];
+}
+interface ValidationOSDashboardProps {
+    config?: DashboardConfig;
+}
+/**
+ * The entire styled dashboard as one mountable app (spec OPS-1280): the frame —
+ * sidebar composing register nav + live counts, topbar with the backend
+ * indicator and user — and the register views (browse → drawer → understanding)
+ * it composes from the package's own bricks. Navigation is owned here, not the
+ * host router: the active register lives in client state (synced to the URL
+ * hash), so the instance mounts this at one route and wires no routing. Styled
+ * by the package's own token sheet — the instance imports `styles.css` once and
+ * builds no UI.
+ */
+declare function ValidationOSDashboard({ config }: ValidationOSDashboardProps): react.JSX.Element;
+
+/**
+ * Pure presentation logic for the dashboard's visual primitives — status→tone,
+ * risk→fraction/level, the sparkline path, and count/number formatting. Kept
+ * free of React and the DOM so the mapping that drives every pill, bar and
+ * sparkline is unit-tested at this seam (spec story 13), and the components stay
+ * thin wrappers over it.
+ */
+/** A pill/fill tone — maps onto the `--vos-good/warn/crit/accent` tokens. */
+type Tone = "good" | "warn" | "crit" | "accent" | "neutral";
+/**
+ * A record's Status → a pill tone. Live/concluded read good, testing/running
+ * read warn, invalidated/rejected read crit; everything else (Proposed, and any
+ * status we don't recognise) stays neutral rather than guessing a colour. Case-
+ * and whitespace-insensitive.
+ */
+declare function statusTone(status: string | null | undefined): Tone;
+/** Risk thresholds — a belief is critical at ≥60, watch at ≥30 (prototype). */
+declare const RISK_CRIT = 60;
+declare const RISK_WARN = 30;
+/** Risk (0–100) → a tone for the bar fill and the number. */
+declare function riskLevel(risk: number): Tone;
+/** Risk (0–100) → the bar's fill fraction (0–1), clamped. */
+declare function riskFraction(risk: number): number;
+/** Confidence (signed) → the tone for its number: negative reads crit. */
+declare function confidenceTone(confidence: number): Tone;
+/** A signed number rendered with an explicit sign: `+6`, `-3`, `0`. */
+declare function formatSigned(n: number): string;
+/** A count for the nav/tiles, thousands-separated. */
+declare function formatCount(n: number): string;
+/**
+ * An SVG polyline `d` for a sparkline over `values`, fit to a `width`×`height`
+ * box with a 2px inset. The vertical domain defaults to the data's own range
+ * (with 0 always included, so a signed series keeps its baseline meaningful);
+ * pass `min`/`max` to pin it — e.g. −100…100 for Confidence. Returns "" for
+ * fewer than two points (nothing to draw).
+ */
+declare function sparklinePath(values: number[], width: number, height: number, min?: number, max?: number): string;
+
+/** A colored status pill — tone from the status, the label shown verbatim. */
+declare function StatusPill({ status }: {
+    status: string | null | undefined;
+}): react.JSX.Element;
+/**
+ * A risk bar (0–100) plus its number, both toned by threshold: a longer, redder
+ * bar means a riskier belief the eye should land on first (spec story 5).
+ */
+declare function RiskBar({ risk }: {
+    risk: number;
+}): react.JSX.Element;
+/**
+ * A signed confidence reading: a tiny sparkline of its trajectory when a
+ * history is available, always the +/- number (negative reads crit) — so a row
+ * shows both where a belief stands and, when known, which way it is trending
+ * (spec story 6). With no history the number stands alone; the list endpoint
+ * carries no per-row series, so the in-row sparkline appears wherever a caller
+ * does have one (e.g. the drawer trajectory uses `Sparkline` directly).
+ */
+declare function ConfidenceCell({ confidence, history, }: {
+    confidence: number;
+    history?: number[];
+}): react.JSX.Element;
+/**
+ * A signed sparkline over `values`. A zero baseline is drawn whenever the domain
+ * spans it, so a line dipping below zero reads as a belief losing ground. The
+ * last point gets a dot. `fill` shades the area under the line. Pure geometry
+ * comes from `sparklinePath`/`sparklineY`.
+ */
+declare function Sparkline({ values, width, height, min, max, tone, fill, ariaLabel, }: {
+    values: number[];
+    width?: number;
+    height?: number;
+    min?: number;
+    max?: number;
+    tone?: Tone;
+    fill?: boolean;
+    ariaLabel?: string;
+}): react.JSX.Element | null;
+/**
+ * A glanceable stat tile — a label, a big number, and an optional sub-caption.
+ * Becomes a button when `onClick` is given (counts that double as nav). Pure
+ * presentation; the caller supplies the value.
+ */
+declare function StatTile({ label, value, sub, onClick, active, }: {
+    label: string;
+    value: number;
+    sub?: ReactNode;
+    onClick?: () => void;
+    active?: boolean;
+}): react.JSX.Element;
+
 type Counts = Partial<Record<Collection, number>>;
 interface UseCountsResult {
     counts: Counts | null;
@@ -17,24 +153,43 @@ interface UseCountsResult {
  */
 declare function useCounts(basePath?: string): UseCountsResult;
 
+interface RegisterNavProps {
+    /** The active register, highlighted with a clear active state (spec story 7). */
+    active: Collection;
+    /** Called when a register is chosen. */
+    onSelect: (register: Collection) => void;
+    /** Live per-register counts; a middle dot shows until they load. */
+    counts?: Counts | null;
+    /** Restrict/reorder the registers shown; defaults to all, grouped. */
+    registers?: Collection[];
+}
+/**
+ * The sidebar register nav — every register with its live count and an active
+ * state, grouped into the register set and reference data (spec story 7). A
+ * presentational brick: the caller owns which register is active and supplies
+ * the counts. The assembled `<ValidationOSDashboard />` composes this; it's also
+ * exported so anyone building their own surface can reuse it (the second level
+ * of entry). Styled with the package's own token sheet — no host Tailwind.
+ */
+declare function RegisterNav({ active, onSelect, counts, registers, }: RegisterNavProps): react.JSX.Element;
+
 interface RegisterCountsProps {
     counts: Counts;
     /** Optional caption under the tiles (e.g. the backend the numbers came from). */
     caption?: string;
-    /**
-     * Optional link target per register. When supplied, each tile becomes a link
-     * (a plain anchor — works with any router), so counts double as navigation
-     * into the browse tables.
-     */
-    hrefFor?: (register: Collection) => string;
+    /** Optional click handler per register — makes each tile a nav button. */
+    onSelect?: (register: Collection) => void;
+    /** The active register, highlighted when tiles are nav. */
+    active?: Collection | null;
 }
 /**
  * A glanceable grid of stat tiles — one per register, the register's row count
- * as the hero number. Presentational: the caller reads the counts (server-side,
- * through the adapter) and hands them in. Styled with Tailwind utility classes;
- * the host app provides Tailwind.
+ * as the hero number. A brick kept for a counts landing; the assembled app
+ * surfaces the same counts in the sidebar nav. Presentational: the caller reads
+ * the counts (server-side, through the adapter) and hands them in. Rendered in
+ * the package's own token sheet — no host Tailwind.
  */
-declare function RegisterCounts({ counts, caption, hrefFor }: RegisterCountsProps): react.JSX.Element;
+declare function RegisterCounts({ counts, caption, onSelect, active, }: RegisterCountsProps): react.JSX.Element;
 
 interface RegisterTableProps {
     register: Collection;
@@ -46,9 +201,11 @@ interface RegisterTableProps {
 }
 /**
  * A list table for one register — a row per record, the register's key fields
- * as columns (assumptions show Impact, Confidence and Risk). Presentational:
- * the caller supplies the rows. Clicking a row opens the read-only drawer.
- * Styled with Tailwind utilities the host app provides.
+ * as columns. Assumptions read their state at a glance: a colored Status pill, a
+ * signed Confidence, and a threshold-toned Risk bar (spec stories 4–6). Which
+ * cells render as pills/bars/sparklines is declared on the column (`kind`), so
+ * the treatment stays testable at the columns seam and this component stays a
+ * dumb renderer. Presentational: the caller supplies the rows.
  */
 declare function RegisterTable({ register, records, onRowClick, selectedId, }: RegisterTableProps): react.JSX.Element;
 
@@ -71,14 +228,15 @@ interface RecordDrawerProps {
     children?: ReactNode;
 }
 /**
- * A record drawer that reads and edits, and wires relations. Derived numbers
- * always lead as the hero, explicitly marked computed and never editable (spec
- * user story 4) — a "Why?" affordance on Confidence explains how the number was
- * earned. Editing recomputes those numbers server-side on save (story 11); a
- * concurrent edit surfaces as a gentle, jargon-free prompt with a re-fetch path
- * (story 12). In read mode the drawer also hosts the relation editor (`children`,
- * story 14). The slide-over chrome is shared with the create drawer via
- * `DrawerShell`.
+ * A record drawer that reads and edits, and wires relations. The derived
+ * numbers lead as a visually distinct "computed — not editable" hero (spec
+ * stories 4/10): a bordered box, each number big and mono, Confidence toned by
+ * sign and Risk by threshold, with a "Why?" reveal opening the understanding
+ * layer in the same accent/pill language (story 11). Editing recomputes those
+ * numbers server-side on save; a concurrent edit surfaces as a gentle, jargon-
+ * free prompt with a re-fetch path (story 12). In read mode the drawer hosts
+ * the relation editor (`children`). Chrome is shared via `DrawerShell`; styled
+ * with the package's own token sheet, no host Tailwind.
  */
 declare function RecordDrawer({ register, record, loading, error, open, onClose, basePath, onChanged, children, }: RecordDrawerProps): react.JSX.Element;
 
@@ -118,11 +276,12 @@ declare function RelationEditor({ register, recordId, basePath, onLinked, }: Rel
 /**
  * The understanding layer behind the Confidence "Why?" (OPS-1276): which
  * experiments move the number (ranked by push) and how close each running
- * experiment is to concluding, the goal/direct evidence that also moves it,
- * and Confidence over time. It lazy-loads the readings + experiments registers
- * (it only mounts when the Reveal is open), then derives everything through the
- * shared derivation module. The derived box stays the hero; this is the tucked-
- * away detail.
+ * experiment is to concluding, the goal/direct evidence that also moves it, and
+ * Confidence over time. It lazy-loads the readings + experiments registers (it
+ * only mounts when the Reveal is open), then derives everything through the
+ * shared derivation module. Restyled into the drawer's accent/pill language
+ * (spec story 11): signed push tracks and a signed trajectory sparkline, in the
+ * package's own token sheet — no host Tailwind.
  */
 declare function UnderstandingPanel({ assumption, basePath, }: {
     assumption: AnyRecord;
@@ -184,6 +343,8 @@ interface RegisterBrowserProps {
     register: Collection;
     /** API base path (default `/api`). */
     basePath?: string;
+    /** A one-line description under the register title (spec story 7/9). */
+    subtitle?: string;
 }
 /**
  * The browse-create-edit surface for one register: a list table that opens a
@@ -195,7 +356,7 @@ interface RegisterBrowserProps {
  * everywhere. The thin host app renders this with a `register` — that's the
  * whole page.
  */
-declare function RegisterBrowser({ register, basePath }: RegisterBrowserProps): react.JSX.Element;
+declare function RegisterBrowser({ register, basePath, subtitle, }: RegisterBrowserProps): react.JSX.Element;
 
 interface UseListResult {
     records: AnyRecord[] | null;
@@ -333,6 +494,14 @@ declare function hasEdits(register: Collection, original: AnyRecord, draft: Draf
  * headers are plain language and derived numbers are shown, never hidden.
  */
 
+/**
+ * How a cell renders. `text` is plain formatted text; `status` is a colored
+ * pill; `risk` is a threshold-toned bar + number; `confidence` is a signed
+ * number (with a sparkline when a trajectory is available). Keeping this on the
+ * column — not branching by key in the table — is what makes the visual
+ * treatment declarative and testable at this seam (spec story 13).
+ */
+type CellKind = "text" | "status" | "risk" | "confidence";
 interface ColumnDef {
     /** Stable key; also the default field read from the record. */
     key: string;
@@ -344,6 +513,8 @@ interface ColumnDef {
     align?: "left" | "right";
     /** Marks a column whose value is computed, never hand-typed (spec story 4). */
     derived?: boolean;
+    /** How the cell renders; defaults to `text`. */
+    kind?: CellKind;
 }
 /** The columns to render for a register. */
 declare function columnsFor(register: Collection): ColumnDef[];
@@ -415,5 +586,15 @@ declare const REGISTER_LABEL: Record<Collection, string>;
 declare const REGISTER_SINGULAR: Record<Collection, string>;
 /** The order tiles read left-to-right, top-to-bottom. */
 declare const REGISTER_ORDER: Collection[];
+/** A one-line description shown under each register's title (spec story 9). */
+declare const REGISTER_SUBTITLE: Record<Collection, string>;
+/** A single-glyph icon per register for the sidebar nav (matches the prototype
+ * feel; a glyph, not an icon font, so nothing external is pulled in). */
+declare const REGISTER_ICON: Record<Collection, string>;
+/** The sidebar groups the registers into the register set and reference data. */
+declare const REGISTER_GROUPS: {
+    label: string;
+    registers: Collection[];
+}[];
 
-export { CONFLICT_MESSAGE, type ColumnDef, type Counts, type Draft, type ExperimentView, type FieldEditor, type FieldKind, type FormField, type LinkArgs, type LinkChoice, type OtherMover, REGISTER_LABEL, REGISTER_ORDER, REGISTER_SINGULAR, RecordDrawer, type RecordDrawerProps, RecordForm, type RecordFormProps, RegisterBrowser, type RegisterBrowserProps, RegisterCounts, type RegisterCountsProps, RegisterTable, type RegisterTableProps, RelationEditor, type RelationEditorProps, type SaveResult, type Understanding, UnderstandingPanel, type UseCountsResult, type UseCreateResult, type UseLinkResult, type UseListResult, type UseRecordResult, type UseUpdateResult, buildPatch, buildUnderstanding, cellValue, columnsFor, draftFrom, editableFields, emptyDraft, formFieldsFor, formatValue, hasEdits, interpretSave, linkChoicesFrom, missingRequired, primaryLabel, toCreatePayload, useCounts, useCreate, useLink, useList, useRecord, useUpdate };
+export { CONFLICT_MESSAGE, type CellKind, type ColumnDef, ConfidenceCell, type Counts, type DashboardConfig, type Draft, type ExperimentView, type FieldEditor, type FieldKind, type FormField, type LinkArgs, type LinkChoice, type OtherMover, REGISTER_GROUPS, REGISTER_ICON, REGISTER_LABEL, REGISTER_ORDER, REGISTER_SINGULAR, REGISTER_SUBTITLE, RISK_CRIT, RISK_WARN, RecordDrawer, type RecordDrawerProps, RecordForm, type RecordFormProps, RegisterBrowser, type RegisterBrowserProps, RegisterCounts, type RegisterCountsProps, RegisterNav, type RegisterNavProps, RegisterTable, type RegisterTableProps, RelationEditor, type RelationEditorProps, RiskBar, type SaveResult, Sparkline, StatTile, StatusPill, type Tone, type Understanding, UnderstandingPanel, type UseCountsResult, type UseCreateResult, type UseLinkResult, type UseListResult, type UseRecordResult, type UseUpdateResult, ValidationOSDashboard, type ValidationOSDashboardProps, buildPatch, buildUnderstanding, cellValue, columnsFor, confidenceTone, draftFrom, editableFields, emptyDraft, formFieldsFor, formatCount, formatSigned, formatValue, hasEdits, interpretSave, linkChoicesFrom, missingRequired, primaryLabel, riskFraction, riskLevel, sparklinePath, statusTone, toCreatePayload, useCounts, useCreate, useLink, useList, useRecord, useUpdate };