@validation-os/dashboard 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import * as react from 'react';
-import { Collection, AnyRecord } from '@validation-os/core';
+import { ReactNode } from 'react';
+import { Collection, AnyRecord, Relation } from '@validation-os/core';
+import { Progress, MoverKind, TrajectoryPoint } from '@validation-os/core/derivation';
 
 type Counts = Partial<Record<Collection, number>>;
 interface UseCountsResult {
@@ -60,14 +62,123 @@ interface RecordDrawerProps {
     /** Whether the drawer is open (a row is selected). */
     open: boolean;
     onClose: () => void;
+    /** API base path (default `/api`). */
+    basePath?: string;
+    /** Re-fetch the record + its list — called after a save, and the re-fetch
+     * path offered when a concurrent edit is detected. */
+    onChanged?: () => void;
+    /** Extra content below the fields in read mode — e.g. the relation editor. */
+    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`.
+ */
+declare function RecordDrawer({ register, record, loading, error, open, onClose, basePath, onChanged, children, }: RecordDrawerProps): react.JSX.Element;
+
+interface RecordFormProps {
+    register: Collection;
+    basePath?: string;
+    /** Called with the new record's id after a successful create. */
+    onCreated: (id: string) => void;
+    onCancel: () => void;
 }
 /**
- * A read-only drawer for one record. Any derived numbers lead as the hero,
- * explicitly marked computed — not editable (spec user story 4), so a reader
- * trusts they follow the formulas; the record's own fields follow. This slice
- * is read-only; editing lands in a later slice.
+ * The "new record" form for one register (spec user story 13). Editable own-
+ * fields only — derived numbers are computed server-side and marked
+ * computed-not-editable elsewhere; relations are wired by linking after the
+ * record exists. Presence-gap fields (5 Whys, etc.) appear as first-class
+ * textareas. On submit it POSTs through the API, which recomputes on write.
+ */
+declare function RecordForm({ register, basePath, onCreated, onCancel, }: RecordFormProps): react.JSX.Element;
+
+interface RelationEditorProps {
+    /** The register of the open record initiating the link. */
+    register: Collection;
+    /** The open record's id (the `from` end). */
+    recordId: string;
+    basePath?: string;
+    /** Called after a relation is wired, so the drawer can re-fetch. */
+    onLinked: () => void;
+}
+/**
+ * Wire a relation from the open record (spec user story 14). Pick an edge, then
+ * a target record from the register that edge points at; linking sets both ends
+ * server-side and recomputes derived fields. Registers with no outbound edges
+ * (glossary, people) render nothing.
+ */
+declare function RelationEditor({ register, recordId, basePath, onLinked, }: RelationEditorProps): react.JSX.Element | null;
+
+/**
+ * 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.
+ */
+declare function UnderstandingPanel({ assumption, basePath, }: {
+    assumption: AnyRecord;
+    basePath?: string;
+}): react.JSX.Element;
+
+/**
+ * The understanding layer's data join (OPS-1276). Pure: given an assumption
+ * and the readings + experiments registers, it produces everything the Reveal
+ * shows — the experiments testing the belief (each with how hard it moves
+ * Confidence and how close it is to concluding), the goal/direct evidence that
+ * 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.
  */
-declare function RecordDrawer({ register, record, loading, error, open, onClose, }: RecordDrawerProps): react.JSX.Element | null;
+
+/** An experiment testing this assumption: how hard it moves Confidence, and
+ * how close it is to concluding. `contribution` is 0 for a running experiment
+ * that has not produced a concluded reading yet — it still shows, so its
+ * progress-to-conclusion is visible. */
+interface ExperimentView {
+    experimentId: string;
+    title: string | null;
+    status: string | null;
+    /** Signed push on Confidence; 0 until a concluded reading lands. */
+    contribution: number;
+    magnitude: number;
+    /** Concluded readings this experiment has produced for the belief. */
+    readingCount: number;
+    progress: Progress | null;
+    /** Concluded/closed — reads as done rather than in-flight. */
+    done: boolean;
+}
+/** Goal-rung or direct evidence that moves Confidence but is not an experiment. */
+interface OtherMover {
+    key: string;
+    kind: Exclude<MoverKind, "experiment">;
+    goalId: string | null;
+    contribution: number;
+    magnitude: number;
+    readingCount: number;
+}
+interface Understanding {
+    /** The same Confidence the derived box shows. */
+    confidence: number;
+    /** Experiments testing this belief, ranked by how hard they push. */
+    experiments: ExperimentView[];
+    /** Goal/direct evidence that also moves the number. */
+    otherMovers: OtherMover[];
+    /** Confidence over time; empty when no concluded reading is dated. */
+    trajectory: TrajectoryPoint[];
+    /** Concluded readings feeding the number, across all sources. */
+    readingCount: number;
+}
+declare function buildUnderstanding(assumption: AnyRecord, readings: AnyRecord[], experiments: AnyRecord[]): Understanding;
 
 interface RegisterBrowserProps {
     register: Collection;
@@ -75,10 +186,14 @@ interface RegisterBrowserProps {
     basePath?: string;
 }
 /**
- * The browse-and-open surface for one register: a list table that opens a
- * read-only drawer on row click. Reads over HTTP through the Clerk-gated API
- * read routes (list + get), so the browser never touches Firestore directly.
- * The thin host app renders this with a `register` — that's the whole page.
+ * The browse-create-edit surface for one register: a list table that opens a
+ * record drawer on row click, a "New" button that opens the create form, and a
+ * relation editor in the drawer for wiring links. All reads and writes go over
+ * HTTP through the Clerk-gated API (which recomputes derived fields on write),
+ * so the browser never touches Firestore directly. After an edit saves, both
+ * the drawer's record and the list re-fetch so recomputed derived numbers show
+ * everywhere. The thin host app renders this with a `register` — that's the
+ * whole page.
  */
 declare function RegisterBrowser({ register, basePath }: RegisterBrowserProps): react.JSX.Element;
 
@@ -94,12 +209,122 @@ interface UseRecordResult {
     record: AnyRecord | null;
     loading: boolean;
     error: string | null;
+    /** Re-fetch the record — the re-fetch path after a save or edit conflict. */
+    refresh: () => void;
 }
 /**
  * Fetch one record by id. `id` may be null (nothing open) — the hook stays
  * idle until an id is supplied, so it drives a drawer that opens on row click.
+ * `refresh` re-fetches: the edit flow calls it after a save, and it's the
+ * re-fetch path offered when a write hits a concurrent-edit conflict.
  */
 declare function useRecord(register: Collection, id: string | null, basePath?: string): UseRecordResult;
+/** The outcome of a save: the recomputed record, or a rejection with a
+ * plain-language message (a concurrent-edit conflict, or another failure). */
+type SaveResult = {
+    ok: true;
+    record: AnyRecord;
+} | {
+    ok: false;
+    conflict: boolean;
+    message: string;
+};
+/**
+ * Map an update response (status + parsed body) to a `SaveResult`. Pure, so
+ * the 409/error/ok branching is unit-testable without a DOM. A 409 is a
+ * concurrent-edit conflict, surfaced in the API's plain-language copy (or the
+ * `CONFLICT_MESSAGE` fallback) — never version jargon (spec user story 12).
+ */
+declare function interpretSave(status: number, body: unknown): SaveResult;
+interface UseUpdateResult {
+    /** PATCH `{ version, ...patch }`; resolves to the recomputed record or a
+     * rejection. Never throws — callers branch on `result.ok`. */
+    save: (id: string, patch: Record<string, unknown>) => Promise<SaveResult>;
+    saving: boolean;
+    /** Plain-language conflict prompt when a concurrent edit was detected. */
+    conflict: string | null;
+    /** Plain-language message for any other save failure. */
+    error: string | null;
+    /** Clear conflict/error state (e.g. when re-entering edit mode). */
+    reset: () => void;
+}
+/**
+ * Version-guarded update over the API write route. A stale version comes back
+ * as a 409, which we surface as a gentle, jargon-free `conflict` message (spec
+ * user story 12) — the API sends the copy, and `CONFLICT_MESSAGE` is the
+ * fallback. Derived values are recomputed server-side, so the returned record
+ * carries the authoritative numbers, never anything the client computed.
+ */
+declare function useUpdate(register: Collection, basePath?: string): UseUpdateResult;
+
+interface UseCreateResult {
+    create: (data: Record<string, unknown>) => Promise<AnyRecord>;
+    saving: boolean;
+    error: string | null;
+}
+/** Create a record in `register`; the server stamps derived fields on write. */
+declare function useCreate(register: Collection, basePath?: string): UseCreateResult;
+interface LinkArgs {
+    relation: Relation;
+    from: {
+        register: Collection;
+        id: string;
+    };
+    to: {
+        register: Collection;
+        id: string;
+    };
+}
+interface UseLinkResult {
+    link: (args: LinkArgs) => Promise<void>;
+    linking: boolean;
+    error: string | null;
+}
+/** 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
@@ -129,10 +354,66 @@ 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;
 
+/**
+ * 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
+ * without a DOM. Only a record's own scalar fields appear here: derived numbers
+ * are computed server-side (never typed), and relations are wired separately by
+ * linking (see `relations.ts` / the relation editor), so id/relation fields are
+ * deliberately absent. Vocabularies mirror `core`'s type unions.
+ */
+
+interface FormField {
+    /** Record field key (what the create payload uses). */
+    key: string;
+    /** Plain-language label a non-technical teammate reads. */
+    label: string;
+    kind: FieldKind;
+    /** Options for a `select`. */
+    options?: readonly string[];
+    /** A `select`/`text` value that should be stored as a number. */
+    coerce?: "number";
+    required?: boolean;
+    placeholder?: string;
+}
+/** The editable fields for a register's create form, in display order. */
+declare function formFieldsFor(register: Collection): FormField[];
+/** A blank draft: every field keyed to an empty string (form-friendly). */
+declare function emptyDraft(register: Collection): Record<string, string>;
+/** Labels of required fields the draft has left blank (submit-gating). */
+declare function missingRequired(register: Collection, draft: Record<string, string>): string[];
+/**
+ * Turn a string-keyed form draft into a create payload: numbers coerced, blank
+ * optional values dropped so the record stores only what was filled. Derived
+ * and relation fields are never here — the server computes the former and
+ * linking wires the latter.
+ */
+declare function toCreatePayload(register: Collection, draft: Record<string, string>): Record<string, unknown>;
+
+/**
+ * Which relations a record of a given register can initiate — the menu the
+ * relation editor offers. Derived from `core`'s single `RELATIONS` table (so
+ * the two never drift) and turned into plain-language choices, each naming the
+ * register whose records are valid link targets.
+ */
+
+interface LinkChoice {
+    relation: Relation;
+    /** Plain-language name of the edge, from the initiating record's side. */
+    label: string;
+    /** The register to pick a target record from. */
+    targetRegister: Collection;
+}
+/** The relations a record of `register` can initiate, in table order. */
+declare function linkChoicesFrom(register: Collection): LinkChoice[];
+
 /** Plain-language labels — the register is a surface a non-technical
  * teammate meets, so no jargon and no code-y plurals. */
 declare const REGISTER_LABEL: Record<Collection, string>;
+/** Singular labels — for "New {thing}" affordances (never a naive de-pluralise
+ * that would read "New Peopl" / "New Glossary"). */
+declare const REGISTER_SINGULAR: Record<Collection, string>;
 /** The order tiles read left-to-right, top-to-bottom. */
 declare const REGISTER_ORDER: Collection[];
 
-export { type ColumnDef, type Counts, REGISTER_LABEL, REGISTER_ORDER, RecordDrawer, type RecordDrawerProps, RegisterBrowser, type RegisterBrowserProps, RegisterCounts, type RegisterCountsProps, RegisterTable, type RegisterTableProps, type UseCountsResult, type UseListResult, type UseRecordResult, cellValue, columnsFor, formatValue, primaryLabel, useCounts, useList, useRecord };
+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 };