@validation-os/dashboard 0.6.1 → 0.7.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { Collection, AnyRecord, Relation } from '@validation-os/core';
-import { PortfolioProgress, StageExperimentInput, MoveKind, NextMoveInput, JourneyEvent, BeliefStage, NextMove, Progress, MoverKind, TrajectoryPoint } from '@validation-os/core/derivation';
+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';
 
 /**
@@ -592,6 +592,24 @@ interface JourneyView {
     /** Killed (Invalidated) / moot / null — the drill-in's terminal state. */
     resolved: "killed" | "moot" | null;
 }
+/** The dot's tone against an event — how that moment read for the belief. */
+declare function eventTone(event: JourneyEvent): Tone;
+/**
+ * The step-in an event offers (OPS-1294's human set: assumption edit · score
+ * impact · write decision), or null for an event there is nothing to act on.
+ *
+ * The story is where step-in lives — the rail is pure status (OPS-1297). Two
+ * acts are deliberately absent: designing a test (no experiment-design form on
+ * this surface) and recording a reading (its form lives with the evidence, not
+ * the narrative). An unscored belief has no `score` event at all, so its
+ * score-impact act rides the next-move card instead.
+ */
+declare function eventStepIn(kind: JourneyEventKind): {
+    form: StoryStepIn;
+    cta: string;
+} | null;
+/** The forms the story can open — the OPS-1294 set, minus experiment design. */
+type StoryStepIn = "edit-belief" | "score-impact" | "write-decision";
 /**
  * Build one belief's journey from the four registers. Returns null when the
  * belief id isn't in the assumptions register. `now` is passed in (an ISO date)
@@ -599,6 +617,266 @@ interface JourneyView {
  */
 declare function buildJourney(assumptionId: string, records: NextMoveRecords, now: string): JourneyView | null;
 
+/**
+ * The per-belief journey — the drill-in altitude (design OPS-1297, build
+ * OPS-1330), mounted on the record page. An A+B hybrid:
+ *
+ *  - at rest, a compact **read-only stage rail** — the same Framed → Planned →
+ *    Tested → Known spine the pipeline board draws, zoomed to one belief. The
+ *    rail is pure status: nothing to act on there;
+ *  - it **expands into the chronological story** through the record page's
+ *    existing "Why?" reveal idiom — the dated event log (bet → score →
+ *    experiment → readings → confidence-cross → now), ending in the ranked
+ *    next-move card (OPS-1292).
+ *
+ * **Step-in is story-only** (OPS-1297): the next-move card and the per-event
+ * edits carry the OPS-1294 human set (edit the bet · score impact · write
+ * decision), and manual override lives at the foot of the story. There is
+ * deliberately no experiment-design form here.
+ *
+ * The narrative is the *loop* story — why the number is what it is. It is not
+ * the raw record history: that audit trail belongs to the record page itself
+ * (OPS-1282) and this must not retell it. Every number arrives derived through
+ * `buildJourney`; nothing is computed here.
+ */
+interface BeliefJourneyProps {
+    /** This belief's journey, already derived (`buildJourney`). */
+    journey: JourneyView;
+    /** The belief record itself — what the step-in forms write against. */
+    assumption: AnyRecord;
+    basePath?: string;
+    /** Navigate the shell — used by the story's manual override. */
+    onNavigate: (route: Route) => void;
+    /** Re-read the registers after a step-in writes. */
+    onChanged: () => void;
+}
+declare function BeliefJourney({ journey, assumption, basePath, onNavigate, onChanged, }: BeliefJourneyProps): react.JSX.Element;
+
+/**
+ * The four loop meters as data — the Framed → Planned → Tested → Known spine
+ * turned into captions and fills, once (OPS-1330).
+ *
+ * Two surfaces draw the same four meters for one belief: the pipeline board's
+ * row (OPS-1300, the cross-belief altitude) and the journey rail (this ticket,
+ * the same spine zoomed to one belief). The *classification* is already shared
+ * in core (`deriveBeliefStage`, OPS-1329); this shares the layer above it — what
+ * each meter is captioned and how full it reads — so a board row and a rail can
+ * never disagree about a belief while looking at the same numbers.
+ *
+ * Only the mapping is shared, not the markup: each surface renders these its own
+ * way (the board as a compact horizontal track, the rail as the labelled spine).
+ * Pure, so the captions are unit-tested here rather than through two DOMs.
+ */
+
+/**
+ * How a meter fills: `fill` runs left→right (0–100%); `signed` is anchored at
+ * the middle and leans by sign — the Known gauge, which never "completes".
+ */
+type MeterKind = "fill" | "signed";
+/** One meter, ready to render. */
+interface StageMeterView {
+    /** Its place on the spine, "1"–"4" — the caption's index. */
+    n: string;
+    /** The stage it meters. */
+    key: StageKey;
+    /** Its display name — "Framed", "Planned", "Tested", "Known". */
+    name: string;
+    /** The caption: "Framed 60%", "No test", "Tested 1/3", "Known +40". */
+    label: string;
+    /**
+     * How full it reads, as a percentage of the track. A `signed` meter fills
+     * from the midpoint, so its span is 0–50 (a full lean is half the track).
+     */
+    pct: number;
+    /** Nothing has happened on this meter yet — the caption reads muted. */
+    muted: boolean;
+    kind: MeterKind;
+    /** Replaces the caption when set — the Known meter's kill-zone re-test flag. */
+    flag?: string;
+    /** Which way a `signed` meter leans. */
+    sign?: ConfSign;
+}
+/**
+ * The meter fields a belief carries. Both `BeliefStage` (the rail) and
+ * `PipelineRow` (the board) satisfy this structurally, so neither has to be
+ * converted before rendering.
+ */
+interface StageMeterInput {
+    framed: number;
+    planned: boolean;
+    tested: {
+        settled: number;
+        total: number;
+    };
+    confidence: number;
+    confSign: ConfSign;
+    killZone: boolean;
+}
+/**
+ * One belief's four meters, in spine order. Nothing is derived here — the
+ * numbers arrive already computed (`deriveBeliefStage`); this only decides how
+ * each one reads.
+ */
+declare function stageMeters(input: StageMeterInput): StageMeterView[];
+
+/**
+ * The cross-surface cold-start view-model (OPS-1331) — pure, no React, no I/O,
+ * so the "what does the dashboard show before any beliefs exist?" mapping is
+ * unit-tested at this seam (like `next-move.ts` / `pipeline.ts` / `journey.ts`).
+ *
+ * The dashboard has three workflow surfaces, and each one had a basic one-line
+ * empty state from its own build (OPS-1304 front door, OPS-1300 pipeline). Now
+ * that all three surfaces exist (OPS-1330 journey landed), this replaces them
+ * with one designed pass: a founder who opens the dashboard before any beliefs
+ * exist is *guided in* rather than shown blank meters.
+ *
+ * Two cold states, one module:
+ *
+ *  - **Cross-surface cold start** — zero beliefs exist. The front door and the
+ *    pipeline each get a designed empty state (a hero with a first-bet CTA, an
+ *    honest 0% burn-up with an invitation), and a shared first-run onboarding
+ *    line ties the three surfaces together. Trigger: `records.assumptions`
+ *    is empty.
+ *  - **Journey no-history cold state** — a belief exists but has no evidence
+ *    yet (no score, no test, no reading). The rail renders honestly (framed at
+ *    its completeness %, 0/0 bars); the story's cold-state copy names the
+ *    belief's first move in plain language, rather than showing two sparse
+ *    events with nothing between. Trigger: the story has only the structural
+ *    `bet` + `now` events.
+ *
+ * No number is invented: the pipeline's cold burn-up reads 0% because there is
+ * no risk to retire; the journey's cold rail reads the belief's real framing %
+ * and 0/0 tests. The copy is plain and consistent across both themes (it
+ * carries no tone — these are invitations, not status).
+ */
+
+/** The cross-surface cold start — zero beliefs exist. */
+interface ColdStart {
+    /** True when no assumptions exist in the register. */
+    cold: boolean;
+    /** The first-run onboarding line — shared across every cold surface. */
+    onboarding: string;
+    /** The front-door hero copy. */
+    next: NextColdStart;
+    /** The pipeline cold-board copy. */
+    pipeline: PipelineColdStart;
+}
+/** The front-door cold-start hero copy. */
+interface NextColdStart {
+    /** The hero's eyebrow — a small label above the headline. */
+    eyebrow: string;
+    /** The hero's headline — the one line a founder reads. */
+    headline: string;
+    /** The hero's supporting line, under the headline. */
+    body: string;
+    /** The primary CTA on the cold hero. */
+    cta: string;
+}
+/** The pipeline cold-start copy. */
+interface PipelineColdStart {
+    /** The burn-up's headline reading (honest: 0%, no risk to retire). */
+    headline: string;
+    /** The line under the 0% — what the founder does next. */
+    invitation: string;
+    /** The empty board's body copy. */
+    boardBody: string;
+    /** The empty board's CTA. */
+    boardCta: string;
+}
+/** The journey's no-history cold-state copy. */
+interface JourneyColdState {
+    /** True when the belief has no evidence yet (only the structural events). */
+    cold: boolean;
+    /** The eyebrow on the cold-state card. */
+    eyebrow: string;
+    /** The cold-state body — names the belief's first move in plain language. */
+    body: string;
+}
+/** The shared first-run onboarding line — one tone across all three surfaces. */
+declare const FIRST_RUN_LINE: string;
+/**
+ * The cross-surface cold start, derived from the fetched registers. Cold when
+ * no assumptions exist; warm otherwise. Pure — the surfaces branch on `cold`
+ * and read the copy off the result.
+ */
+declare function coldStartFor(records: NextMoveRecords): ColdStart;
+/**
+ * The journey's no-history cold state. Cold when the belief's story has only
+ * the two structural events (the `bet` it opened with and the `now` that
+ * anchors today) — no score, no test, no reading, no confidence-cross. The
+ * rail still renders honestly (its real framing % and 0/0 tests); this only
+ * shapes the story's copy so a founder with one fresh belief isn't shown two
+ * sparse events with nothing between.
+ *
+ * The body names the belief's own next move in plain language when one exists,
+ * so the cold state still points forward.
+ */
+declare function journeyColdState(journey: JourneyView): JourneyColdState;
+
+/**
+ * The pure edit-logic seam — which fields a register lets you edit, how a
+ * form draft maps back to a version-guarded patch, and the plain-language
+ * conflict copy. Kept as pure data/functions (no DOM) so the edit behaviour
+ * is unit-testable exactly like `columns.ts`; the drawer component consumes it.
+ *
+ * Derived numbers (Confidence, Risk, Derived Impact, Strength) are never
+ * editable — they are computed server-side on write (spec user story 4/11),
+ * so they never appear here. Relation links are set through `link`, a separate
+ * story, so relation-id fields aren't editable inputs either.
+ */
+
+/** The plain-language conflict prompt — never version jargon (user story 12).
+ * The API returns its own copy on a 409; this is the client-side fallback. */
+declare const CONFLICT_MESSAGE: string;
+type FieldKind = "text" | "textarea" | "number" | "select";
+interface FieldEditor {
+    /** The record key this editor writes. */
+    key: string;
+    /** Plain-language label shown beside the input. */
+    label: string;
+    kind: FieldKind;
+    /** For `select`: the allowed options (a leading blank = "unset"). */
+    options?: readonly string[];
+    /** An empty input clears the field to `null` rather than "". */
+    nullable?: boolean;
+}
+/** The fields a register lets you edit, in render order. */
+declare function editableFields(register: Collection): FieldEditor[];
+/** A form draft is a plain string map keyed by field — what the inputs hold. */
+type Draft = Record<string, string>;
+/** Build the initial form draft from a record: every editable field becomes a
+ * string input value, and missing values become empty inputs. */
+declare function draftFrom(register: Collection, record: AnyRecord): Draft;
+/**
+ * A version-guarded patch from a draft: the loaded `version` plus only the
+ * fields whose value actually changed (so an untouched save doesn't churn
+ * unrelated fields). The API rejects a stale version with a 409.
+ */
+declare function buildPatch(register: Collection, original: AnyRecord, draft: Draft): Record<string, unknown>;
+/** Whether a draft differs from the record it was loaded from. */
+declare function hasEdits(register: Collection, original: AnyRecord, draft: Draft): boolean;
+
+/**
+ * The editable-field stack for a register — the inputs an edit form is made of,
+ * driven by `edit.ts`'s schema (which fields are editable, and as what control).
+ *
+ * Factored out of the record drawer so the drawer and the journey's "edit the
+ * bet" step-in (OPS-1330) render the same controls from the same schema: two
+ * surfaces editing one register should never drift into two different forms.
+ * Derived numbers are never here — they are computed on write (OPS-1251).
+ */
+declare function EditFields({ register, draft, onField, }: {
+    register: Collection;
+    draft: Draft;
+    onField: (key: string, value: string) => void;
+}): react.JSX.Element;
+/** One editable field, as the control its `kind` calls for. */
+declare function FieldInput({ field, value, onChange, }: {
+    field: FieldEditor;
+    value: string | undefined;
+    onChange: (value: string) => void;
+}): react.JSX.Element;
+
 interface RegisterCountsProps {
     counts: Counts;
     /** Optional caption under the tiles (e.g. the backend the numbers came from). */
@@ -829,6 +1107,24 @@ interface ScoreImpactFormProps {
  * ranking. The optional justification records *why* that weight.
  */
 declare function ScoreImpactForm({ assumption, basePath, onDone, onCancel, }: ScoreImpactFormProps): react.JSX.Element;
+interface EditBeliefFormProps {
+    /** The assumption being edited (its version guards the write). */
+    assumption: AnyRecord;
+    basePath?: string;
+    /** Called after a successful save. */
+    onDone: () => void;
+    onCancel: () => void;
+}
+/**
+ * Edit the bet itself — the assumption-edit half of the OPS-1294 step-in set,
+ * reached from the journey story's `bet` event. It renders the register's
+ * editable fields from the same schema the drawer uses (`EditFields`), so the
+ * two never drift, and writes only the fields actually changed: the patch is
+ * diffed against the record it opened on, so a teammate's concurrent edit to an
+ * untouched field survives. Framing completeness (the rail's Framed meter)
+ * recomputes server-side on write.
+ */
+declare function EditBeliefForm({ assumption, basePath, onDone, onCancel, }: EditBeliefFormProps): react.JSX.Element;
 interface WriteDecisionFormProps {
     /** The belief the decision rests on or resolves. */
     assumption: AnyRecord;
@@ -950,49 +1246,6 @@ interface UseLinkResult {
 /** Wire a relation; the API sets both ends and recomputes derived fields. */
 declare function useLink(basePath?: string): UseLinkResult;
 
-/**
- * The pure edit-logic seam — which fields a register lets you edit, how a
- * form draft maps back to a version-guarded patch, and the plain-language
- * conflict copy. Kept as pure data/functions (no DOM) so the edit behaviour
- * is unit-testable exactly like `columns.ts`; the drawer component consumes it.
- *
- * Derived numbers (Confidence, Risk, Derived Impact, Strength) are never
- * editable — they are computed server-side on write (spec user story 4/11),
- * so they never appear here. Relation links are set through `link`, a separate
- * story, so relation-id fields aren't editable inputs either.
- */
-
-/** The plain-language conflict prompt — never version jargon (user story 12).
- * The API returns its own copy on a 409; this is the client-side fallback. */
-declare const CONFLICT_MESSAGE: string;
-type FieldKind = "text" | "textarea" | "number" | "select";
-interface FieldEditor {
-    /** The record key this editor writes. */
-    key: string;
-    /** Plain-language label shown beside the input. */
-    label: string;
-    kind: FieldKind;
-    /** For `select`: the allowed options (a leading blank = "unset"). */
-    options?: readonly string[];
-    /** An empty input clears the field to `null` rather than "". */
-    nullable?: boolean;
-}
-/** The fields a register lets you edit, in render order. */
-declare function editableFields(register: Collection): FieldEditor[];
-/** A form draft is a plain string map keyed by field — what the inputs hold. */
-type Draft = Record<string, string>;
-/** Build the initial form draft from a record: every editable field becomes a
- * string input value, and missing values become empty inputs. */
-declare function draftFrom(register: Collection, record: AnyRecord): Draft;
-/**
- * A version-guarded patch from a draft: the loaded `version` plus only the
- * fields whose value actually changed (so an untouched save doesn't churn
- * unrelated fields). The API rejects a stale version with a 409.
- */
-declare function buildPatch(register: Collection, original: AnyRecord, draft: Draft): Record<string, unknown>;
-/** Whether a draft differs from the record it was loaded from. */
-declare function hasEdits(register: Collection, original: AnyRecord, draft: Draft): boolean;
-
 /**
  * Per-register table columns and value formatting — the presentational shape
  * of the browse tables, kept as pure data/functions so it is unit-testable
@@ -1295,4 +1548,4 @@ declare const REGISTER_GROUPS: {
     registers: Collection[];
 }[];
 
-export { type BacklinkItem, CONFLICT_MESSAGE, type CellKind, type ColumnDef, ConfidenceCell, type Counts, type DashboardConfig, type Draft, type ExperimentView, type FieldEditor, type FieldKind, type FormField, type GlossaryTerm, GlossaryText, type GlossaryTextProps, type GroupBucket, type GroupByAxis, type HumanText, type JourneyEventView, type JourneyView, type LinkArgs, type LinkChoice, type LinkifyNode, type LinkifyOptions, type Meter, type MovePresentation, type NeedsHumanByRegister, type NeedsHumanCounts, type NeighbourChip, type NestedGroup, type NextMoveRecords, NextMoveSurface, type NextMoveSurfaceProps, type OtherMover, type Pill, 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 ResolvedRow, type RiskBand, RiskBar, type Route, type SaveResult, type SavedView, type ScoreChip, ScoreImpactForm, type ScoreImpactFormProps, type ShapedRegister, SidebarNav, type SidebarNavProps, type SortSpec, Sparkline, StatTile, StatusPill, type StepInForm, 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, buildJourney, buildPatch, buildPipeline, buildRecordPage, buildUnderstanding, cellValue, columnsFor, confidenceTone, configureRiskBands, defaultTabId, dontConfuseWith, draftFrom, editableFields, emptyDraft, filterRecords, formFieldsFor, formatCount, formatRoute, formatSigned, formatValue, groupByAxesFor, groupRecords, hasEdits, headerPills, humanInputFields, interpretSave, leadingMeters, linkChoicesFrom, linkify, missingRequired, movePresentation, needsHumanCounts, nestReadingsByPlan, parseRoute, primaryLabel, riskBand, riskFraction, riskLevel, scoreChip, shapeRegister, sortRecords, sparklinePath, statusTone, tabsFor, toCreatePayload, toGlossaryTerms, toNextMoveInput, toStageExperimentInput, useCounts, useCreate, useLink, useList, useNeedsHuman, useRecord, useSavedViews, useUpdate, weekOverWeekDelta };
+export { type BacklinkItem, BeliefJourney, type BeliefJourneyProps, CONFLICT_MESSAGE, type CellKind, type ColdStart, type ColumnDef, ConfidenceCell, type Counts, type DashboardConfig, 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 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, buildJourney, buildPatch, buildPipeline, buildRecordPage, buildUnderstanding, cellValue, coldStartFor, columnsFor, confidenceTone, configureRiskBands, defaultTabId, 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, parseRoute, primaryLabel, riskBand, riskFraction, riskLevel, scoreChip, shapeRegister, sortRecords, sparklinePath, stageMeters, statusTone, tabsFor, toCreatePayload, toGlossaryTerms, toNextMoveInput, toStageExperimentInput, useCounts, useCreate, useLink, useList, useNeedsHuman, useRecord, useSavedViews, useUpdate, weekOverWeekDelta };