@validation-os/dashboard 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { Collection, AnyRecord, Result, Relation, BarLine } from '@validation-os/core';
+import { Collection, AnyRecord, Result, Rung, MagnitudeBand, Relation, BarLine } from '@validation-os/core';
 import { PortfolioProgress, StageExperimentInput, MoveKind, NextMoveInput, BeliefStage, JourneyEvent, NextMove, JourneyEventKind, ConfSign, StageKey, Progress, MoverKind, TrajectoryPoint } from '@validation-os/core/derivation';
 export { StageKey } from '@validation-os/core/derivation';
 
@@ -243,7 +243,9 @@ interface GroupBucket {
  * risk band by severity, everything else first-appearance.
  */
 declare function groupRecords(records: AnyRecord[], axis: GroupByAxis): GroupBucket[];
-/** Case-insensitive substring filter over Title + Description. */
+/** Case-insensitive substring filter over Title + Description + Source. Source
+ * (a reading's generator — person / dataset / cohort) is searchable so a
+ * teammate can pull every reading from one source by typing its name. */
 declare function filterRecords(records: AnyRecord[], query: string): AnyRecord[];
 /** A stable sort by one key; numbers compare numerically, everything else by
  * locale string. Missing values sort last regardless of direction. */
@@ -293,21 +295,24 @@ interface NeedsHumanCounts {
 declare function needsHumanCounts(ctx: RegisterContext): NeedsHumanCounts;
 
 /**
- * The dashboard's client-owned navigation state, across the three workflow
+ * The dashboard's client-owned navigation state, across the workflow
  * altitudes plus the kept register tables (OPS-1298). One `<ValidationOSDashboard/>`
  * mounts at a single host route and drives everything off the URL hash — there
  * is no second entry point (OPS-1280).
  *
- *  - `next`     — the front door ("what's my next move"); the default landing.
- *  - `pipeline` — the step-back portfolio pipeline.
- *  - `records`  — one register's browse table (the manual-override surface,
- *                 kept from the original scheme).
- *  - `record`   — the per-belief drill-in (full record page).
+ *  - `next`       — the front door ("what's my next move"); the default landing.
+ *  - `pipeline`   — the step-back portfolio pipeline.
+ *  - `stage-grid` — the Lens × Stage heatmap (docs/stage-policy.md).
+ *  - `records`    — one register's browse table (the manual-override surface,
+ *                   kept from the original scheme).
+ *  - `record`     — the per-belief drill-in (full record page).
  */
 type Route = {
     name: "next";
 } | {
     name: "pipeline";
+} | {
+    name: "stage-grid";
 } | {
     name: "records";
     register: Collection;
@@ -1040,6 +1045,9 @@ interface RegisterTableProps {
     onRowClick?: (id: string) => void;
     /** The id of the currently-open record, highlighted in the list. */
     selectedId?: string | null;
+    /** Assumption id → title, so a reading row's belief chips read as titles
+     * rather than ids (OPS-1305). Omitted → chips fall back to the bare ids. */
+    assumptionTitles?: Map<string, string>;
 }
 /**
  * A list table for one register — a row per record, the register's key fields
@@ -1049,7 +1057,7 @@ interface RegisterTableProps {
  * 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;
+declare function RegisterTable({ register, records, onRowClick, selectedId, assumptionTitles, }: RegisterTableProps): react.JSX.Element;
 
 /**
  * The record-page view-model (OPS-1286) — the pure join behind the canonical
@@ -1119,6 +1127,27 @@ interface HumanText {
 }
 /** The human-input fields a register carries text for (empty ones dropped). */
 declare function humanInputFields(register: Collection, record: AnyRecord): HumanText[];
+/** One belief a reading grades, prepared for the reading detail's verdict list
+ * (OPS-1305). Modelled on the experiment bar-line view: the assumption resolved
+ * to a title + navigable id, plus this belief's own Rung / Result / derived
+ * Strength / magnitude band and the grading justification. */
+interface BeliefVerdict {
+    assumptionId: string;
+    /** The belief's title if it's in the loaded set, else its bare id. */
+    title: string;
+    /** True when the assumption resolved — drives whether the title links. */
+    linked: boolean;
+    rung: Rung | null;
+    result: Result | null;
+    /** Derived per-belief strength (signed −100…100). */
+    strength: number | null;
+    magnitudeBand: MagnitudeBand | null;
+    justification: string;
+}
+/** The per-belief verdicts a reading carries, in stored order — the reading
+ * detail's answer to "what did this artifact say about each belief?". Pure:
+ * resolves each belief-score against the loaded assumptions for its title. */
+declare function readingBeliefVerdicts(reading: AnyRecord, assumptions?: AnyRecord[]): BeliefVerdict[];
 /** A glance-readable score chip for a linked record (story 9). */
 interface ScoreChip {
     label: string;
@@ -1263,7 +1292,10 @@ declare function UnderstandingPanel({ assumption, basePath, }: {
  * also moves the number, and the Confidence-over-time trajectory.
  *
  * The record → derivation-input mapping is `@validation-os/core`'s shared
- * `toReadingInput`, so a reading is read here exactly as it is server-side.
+ * `readingBeliefInputs`, which fans a reading row out into one input per belief;
+ * we keep this belief's inputs, so a reading is read here exactly as it is
+ * server-side. Archived experiments never surface here (OPS-1305) — the "Why?"
+ * only ever shows a live plan or direct evidence.
  */
 
 /** An experiment testing this assumption: how hard it moves Confidence, and
@@ -1352,6 +1384,137 @@ interface NextMoveSurfaceProps {
 }
 declare function NextMoveSurface({ basePath, onNavigate }: NextMoveSurfaceProps): react.JSX.Element;
 
+/**
+ * The Lens × Stage heatmap view-model (docs/stage-policy.md §The dashboard
+ * surface) — pure, no React, no I/O, so the grid's shape and the drill-
+ * through's Risk-ranked list are unit-tested at this seam (like
+ * `pipeline.ts` / `journey.ts` / `next-move.ts`).
+ *
+ * The grid is the **filter**, Risk is the **rank**. Where the pipeline board
+ * reads "where every belief stands" row-by-row, this reads the same beliefs
+ * cross-tabbed by Lens (the actor — who the belief is about) × Stage (the
+ * kind of response — engage / pay / scale / defend). The densest cell per
+ * row is where that part of the business is — no flag, no declaration, the
+ * density tells you. Click a cell → the assumptions in it, ranked by Risk.
+ *
+ * Pure and computed fresh on read (like `pipeline.ts`): it only reads numbers
+ * already kept current (`derived.risk`), so it stays out of the OPS-1251
+ * on-write recompute. The Lens list comes from the caller (the surface
+ * supplies the workspace's configured vocabulary); the Stage list is fixed
+ * (the four discovery stages — see `ontology.yaml §vocabularies.stage`).
+ */
+
+/** The four discovery stages, in their canonical ordinal order (1→4). The
+ * stored value is the name; the ordinal is for sort/display only. */
+declare const STAGE_ORDER: readonly ["Discovery", "Validation", "Scale", "Maturity"];
+type StageValue = (typeof STAGE_ORDER)[number];
+/** A short, plain-language gloss for each stage — the column header's
+ * subtitle and the cell tooltip. Drawn from docs/stage-policy.md. */
+declare const STAGE_GLOSS: Record<StageValue, string>;
+/** One cell of the Lens × Stage grid. */
+interface StageGridCell {
+    /** The Lens (row) this cell sits under. */
+    lens: string;
+    /** The Stage (column) this cell sits under — one of the four canonical
+     * stages, or the `NO_STAGE` ("—") sentinel for records with no/invalid
+     * Stage (the gate-leakage bucket, only emitted when needed). */
+    stage: StageValue | typeof NO_STAGE;
+    /** How many assumptions hold this Lens × Stage pair. */
+    count: number;
+    /** The assumptions in this cell, ranked by Risk (highest first). Empty
+     * when `count` is 0. The rank is the cell's drill-through order. */
+    assumptions: AnyRecord[];
+    /** Density in [0, 1] — `count / maxCellCount` across the whole grid, for
+     * the heatmap colour scale. 0 for an empty cell. */
+    density: number;
+}
+/** The grid view-model — rows per Lens, columns per Stage, cells with counts
+ * and Risk-ranked drill-through lists. */
+interface StageGridView {
+    /** The Lens values, in first-appearance order (the configured vocabulary
+     * order is the caller's job; the grid keeps the order it sees). Includes
+     * a trailing "—" row for assumptions with no Lens set. */
+    lenses: string[];
+    /** The four stages in their canonical ordinal order. */
+    stages: StageValue[];
+    /** One cell per (lens, stage) pair, in row-major order: lens-first,
+     * stage-within-lens. */
+    cells: StageGridCell[];
+    /** The maximum cell count across the grid — what `density` is normalised
+     * against. 0 when the grid is empty. */
+    maxCellCount: number;
+    /** Total assumptions counted in the grid (every cell's count summed).
+     * Equal to the input length minus any rows with neither Lens nor Stage
+     * set, which fall in the "—" row / "—" cell. */
+    total: number;
+}
+declare const NO_LENS = "\u2014";
+declare const NO_STAGE = "\u2014";
+/** A stage value from a record, validated against the fixed vocabulary.
+ * Returns null for an empty or unrecognised value — the caller decides
+ * whether to bucket those or drop them. */
+declare function stageOf(record: AnyRecord): StageValue | null;
+/** Sort a list of assumptions by Risk, highest first. Stable on tie by id —
+ * matches the pipeline board's "riskiest first" convention. Pure: returns a
+ * new array, leaves the input alone. */
+declare function rankByRisk(records: AnyRecord[]): AnyRecord[];
+/**
+ * Build the Lens × Stage grid from the assumption register. Pure — no I/O,
+ * no React. The Lens list is read off the records in first-appearance order
+ * (the configured vocabulary order is the caller's concern; the grid keeps
+ * what it sees, so a workspace with no Commercial-stage-4 bets simply shows
+ * a 0 cell, never a missing row). A record with no Lens set falls into a
+ * trailing "—" row; a record with no Stage set (or an unrecognised Stage)
+ * falls into a trailing "—" column. The "—"/"—" cell holds the records the
+ * gate would have caught — write-time enforcement is the gate's job, this
+ * just surfaces them honestly.
+ *
+ * The "—" row and "—" column are **only emitted when needed** — i.e. when at
+ * least one record has a missing Lens (resp. Stage). A clean register
+ * renders a pure Lens × 4-Stage matrix; a register with gate-leakage gets
+ * the diagnostic row/column added. This keeps the matrix rectangular and
+ * matches the spec ("if a claim doesn't fit any stage, it falls out" — the
+ * "—" column is a diagnostic, not a feature).
+ *
+ * Each cell's `assumptions` list is ranked by Risk (highest first), so the
+ * drill-through reads "the riskiest belief in this cell" first — the grid is
+ * the filter, Risk is the rank. `density` is `count / maxCellCount` across
+ * the whole grid, for the heatmap colour scale; an empty cell reads 0.
+ */
+declare function buildStageGrid(assumptions: AnyRecord[]): StageGridView;
+/** The cell at a given (lens, stage) — null if no such cell (e.g. a stage
+ * not in the canonical order). The "—" row / "—" column are addressable
+ * with the `NO_LENS` / `NO_STAGE` sentinels. */
+declare function cellAt(view: StageGridView, lens: string, stage: StageValue | typeof NO_STAGE): StageGridCell | null;
+
+/**
+ * The Lens × Stage heatmap surface (docs/stage-policy.md §The dashboard
+ * surface) — the workflow dashboard's portfolio lens, mounted alongside
+ * `NextMoveSurface` and `PipelineSurface`. One row per Lens (the actor — who
+ * the belief is about), one column per Stage (the kind of response — engage
+ * / pay / scale / defend), each cell carrying its assumption count and a
+ * heatmap colour by density. Click a cell → a drill-through drawer with the
+ * assumptions in that cell, ranked by Risk (the grid is the filter, Risk is
+ * the rank).
+ *
+ * No stage-flag selector, no "what stage am I" prompt, no per-stage
+ * confidence model — the grid reads the business state off where the bets
+ * cluster, and lets you drill into any cell ranked by Risk. The densest cell
+ * per row is where that part of the business is; thin/empty cells are gaps
+ * (Consumer × Maturity is honestly 0 — consumers don't drive defense bets).
+ *
+ * Lazy-loads the assumption register and derives everything through the pure
+ * `buildStageGrid` view-model — no number is computed here (spec: explain
+ * from inputs). Clicking a belief in the drill-through routes to that
+ * belief's record page (OPS-1298), the review surface where step-in happens.
+ */
+interface StageGridSurfaceProps {
+    basePath?: string;
+    /** Navigate across the shell (belief → record). */
+    onNavigate: (route: Route) => void;
+}
+declare function StageGridSurface({ basePath, onNavigate }: StageGridSurfaceProps): react.JSX.Element;
+
 interface ScoreImpactFormProps {
     /** The assumption being weighted (its version guards the write). */
     assumption: AnyRecord;
@@ -1537,6 +1700,14 @@ interface ColumnDef {
 }
 /** The columns to render for a register. */
 declare function columnsFor(register: Collection): ColumnDef[];
+/** A one-line, length-capped preview of a reading's free-text `body` (its
+ * quote), for the readings table. Collapses whitespace and ellipsises; a
+ * missing/empty body reads as the empty string (formatted to an em dash). */
+declare function bodyPreview(value: unknown, max?: number): string;
+/** The belief chips for a reading row — the assumptions it grades, resolved to
+ * titles when a lookup is given, else their bare ids. Disambiguates readings
+ * that share a Title by showing which belief(s) each one actually scored. */
+declare function readingAssumptionChips(record: AnyRecord, titleById?: Map<string, string>): string[];
 /** Read a column's raw value from a record (accessor, else `record[key]`). */
 declare function cellValue(column: ColumnDef, record: AnyRecord): unknown;
 /** Format any stored value for display; empty/missing reads as an em dash. */
@@ -1544,6 +1715,17 @@ declare function formatValue(value: unknown): string;
 /** The record's headline for a row/drawer: Title, else Name, else its id. */
 declare function primaryLabel(record: AnyRecord): string;
 
+/** Render Markdown `text` into the package's prose styling. Empty → nothing. */
+declare function Markdown({ text }: {
+    text: string;
+}): react.JSX.Element | null;
+
+declare function BeliefVerdicts({ reading, assumptions, onOpenRecord, }: {
+    reading: AnyRecord;
+    assumptions: AnyRecord[];
+    onOpenRecord?: (id: string) => void;
+}): react.JSX.Element;
+
 /**
  * The editable-field spec for the "new record" form, per register — kept as
  * pure data + functions (like `columns.ts`) so the create form is unit-testable
@@ -1755,4 +1937,4 @@ declare const REGISTER_GROUPS: {
     registers: Collection[];
 }[];
 
-export { type BacklinkItem, BeliefJourney, type BeliefJourneyProps, CONFLICT_MESSAGE, type CellKind, type ColdStart, type ColumnDef, ConfidenceCell, ConnectClaudeCode, type ConnectClaudeCodeProps, type ConnectCommandInput, type Counts, type CycleReadingView, type CycleView, DEFAULT_TOKEN_ENV, DIRECT_CYCLE_KEY, type DashboardConfig, type DetailRelationItem, type DetailRow, type DetailRowKind, type Draft, EditBeliefForm, type EditBeliefFormProps, EditFields, type ExperimentView, FIRST_RUN_LINE, type FieldEditor, FieldInput, type FieldKind, type FormField, type GlossaryTerm, GlossaryText, type GlossaryTextProps, type GroupBucket, type GroupByAxis, type HumanText, type JourneyColdState, type JourneyEventView, type JourneyView, type LinkArgs, type LinkChoice, type LinkifyNode, type LinkifyOptions, type Meter, type MeterKind, type MovePresentation, type NeedsHumanByRegister, type NeedsHumanCounts, type NeighbourChip, type NestedGroup, type NextColdStart, type NextMoveRecords, NextMoveSurface, type NextMoveSurfaceProps, type OtherMover, type Pill, type PipelineColdStart, type PipelineRow, PipelineSurface, type PipelineView, REGISTER_GROUPS, REGISTER_ICON, REGISTER_LABEL, REGISTER_ORDER, REGISTER_SINGULAR, REGISTER_SUBTITLE, RISK_CRIT, RISK_WARN, RecordDrawer, type RecordDrawerProps, RecordForm, type RecordFormProps, RecordPage, type RecordPageModel, type RecordPageProps, type RecordTabId, RegisterBrowser, type RegisterBrowserProps, type RegisterContext, RegisterCounts, type RegisterCountsProps, RegisterTable, type RegisterTableProps, type RelatedSet, RelationEditor, type RelationEditorProps, type RelationPanel, type ResolvedBarLine, type ResolvedRow, type RiskBand, RiskBar, type Route, type SaveResult, type SavedView, type ScoreChip, ScoreImpactForm, type ScoreImpactFormProps, type ShapedRegister, SidebarNav, type SidebarNavProps, type SortSpec, Sparkline, type StageMeterInput, type StageMeterView, StatTile, StatusPill, type StepInForm, type StoryStepIn, SurfacePlaceholder, type SurfacePlaceholderProps, type TabDef, type TermPreview, type Tone, type Understanding, UnderstandingPanel, type UseCountsResult, type UseCreateResult, type UseLinkResult, type UseListResult, type UseNeedsHumanResult, type UseRecordResult, type UseSavedViewsResult, type UseUpdateResult, ValidationOSDashboard, type ValidationOSDashboardProps, type ViewDescriptor, WriteDecisionForm, type WriteDecisionFormProps, backlinkPanels, buildCycles, buildJourney, buildPatch, buildPipeline, buildRecordPage, buildUnderstanding, cellValue, coldStartFor, columnsFor, composeConnectCommand, confidenceTone, configureRiskBands, defaultTabId, detailRows, dontConfuseWith, draftFrom, editableFields, emptyDraft, eventStepIn, eventTone, filterRecords, formFieldsFor, formatCount, formatRoute, formatSigned, formatValue, groupByAxesFor, groupRecords, hasEdits, headerPills, humanInputFields, interpretSave, journeyColdState, leadingMeters, linkChoicesFrom, linkify, missingRequired, movePresentation, needsHumanCounts, nestReadingsByPlan, ownerNames, parseRoute, primaryLabel, resolveBarLines, riskBand, riskFraction, riskLevel, scoreChip, shapeRegister, sortRecords, sparklinePath, stageMeters, statusTone, tabsFor, toCreatePayload, toGlossaryTerms, toNextMoveInput, toStageExperimentInput, useCounts, useCreate, useLink, useList, useNeedsHuman, useRecord, useSavedViews, useUpdate, weekOverWeekDelta };
+export { type BacklinkItem, BeliefJourney, type BeliefJourneyProps, type BeliefVerdict, BeliefVerdicts, CONFLICT_MESSAGE, type CellKind, type ColdStart, type ColumnDef, ConfidenceCell, ConnectClaudeCode, type ConnectClaudeCodeProps, type ConnectCommandInput, type Counts, type CycleReadingView, type CycleView, DEFAULT_TOKEN_ENV, DIRECT_CYCLE_KEY, type DashboardConfig, type DetailRelationItem, type DetailRow, type DetailRowKind, type Draft, EditBeliefForm, type EditBeliefFormProps, EditFields, type ExperimentView, FIRST_RUN_LINE, type FieldEditor, FieldInput, type FieldKind, type FormField, type GlossaryTerm, GlossaryText, type GlossaryTextProps, type GroupBucket, type GroupByAxis, type HumanText, type JourneyColdState, type JourneyEventView, type JourneyView, type LinkArgs, type LinkChoice, type LinkifyNode, type LinkifyOptions, Markdown, type Meter, type MeterKind, type MovePresentation, NO_LENS, NO_STAGE, type NeedsHumanByRegister, type NeedsHumanCounts, type NeighbourChip, type NestedGroup, type NextColdStart, type NextMoveRecords, NextMoveSurface, type NextMoveSurfaceProps, type OtherMover, type Pill, type PipelineColdStart, type PipelineRow, PipelineSurface, type PipelineView, REGISTER_GROUPS, REGISTER_ICON, REGISTER_LABEL, REGISTER_ORDER, REGISTER_SINGULAR, REGISTER_SUBTITLE, RISK_CRIT, RISK_WARN, RecordDrawer, type RecordDrawerProps, RecordForm, type RecordFormProps, RecordPage, type RecordPageModel, type RecordPageProps, type RecordTabId, RegisterBrowser, type RegisterBrowserProps, type RegisterContext, RegisterCounts, type RegisterCountsProps, RegisterTable, type RegisterTableProps, type RelatedSet, RelationEditor, type RelationEditorProps, type RelationPanel, type ResolvedBarLine, type ResolvedRow, type RiskBand, RiskBar, type Route, STAGE_GLOSS, STAGE_ORDER, type SaveResult, type SavedView, type ScoreChip, ScoreImpactForm, type ScoreImpactFormProps, type ShapedRegister, SidebarNav, type SidebarNavProps, type SortSpec, Sparkline, type StageGridCell, StageGridSurface, type StageGridSurfaceProps, type StageGridView, type StageMeterInput, type StageMeterView, type StageValue, StatTile, StatusPill, type StepInForm, type StoryStepIn, SurfacePlaceholder, type SurfacePlaceholderProps, type TabDef, type TermPreview, type Tone, type Understanding, UnderstandingPanel, type UseCountsResult, type UseCreateResult, type UseLinkResult, type UseListResult, type UseNeedsHumanResult, type UseRecordResult, type UseSavedViewsResult, type UseUpdateResult, ValidationOSDashboard, type ValidationOSDashboardProps, type ViewDescriptor, WriteDecisionForm, type WriteDecisionFormProps, backlinkPanels, bodyPreview, buildCycles, buildJourney, buildPatch, buildPipeline, buildRecordPage, buildStageGrid, buildUnderstanding, cellAt, cellValue, coldStartFor, columnsFor, composeConnectCommand, confidenceTone, configureRiskBands, defaultTabId, detailRows, dontConfuseWith, draftFrom, editableFields, emptyDraft, eventStepIn, eventTone, filterRecords, formFieldsFor, formatCount, formatRoute, formatSigned, formatValue, groupByAxesFor, groupRecords, hasEdits, headerPills, humanInputFields, interpretSave, journeyColdState, leadingMeters, linkChoicesFrom, linkify, missingRequired, movePresentation, needsHumanCounts, nestReadingsByPlan, ownerNames, parseRoute, primaryLabel, rankByRisk, readingAssumptionChips, readingBeliefVerdicts, resolveBarLines, riskBand, riskFraction, riskLevel, scoreChip, shapeRegister, sortRecords, sparklinePath, stageMeters, stageOf, statusTone, tabsFor, toCreatePayload, toGlossaryTerms, toNextMoveInput, toStageExperimentInput, useCounts, useCreate, useLink, useList, useNeedsHuman, useRecord, useSavedViews, useUpdate, weekOverWeekDelta };