@validation-os/dashboard 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -295,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;
@@ -1381,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;
@@ -1803,4 +1937,4 @@ declare const REGISTER_GROUPS: {
     registers: Collection[];
 }[];
 
-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, 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, bodyPreview, 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, readingAssumptionChips, readingBeliefVerdicts, 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 };