@joewinke/jatui 0.37.0 → 0.38.0

package/dist/artifact-blocks/review.d.ts

@@ -0,0 +1,180 @@
+import type { BlockReviewState, BlocksSpec, ReviewItem, SentAnswer, SentItemsMap, VerdictEntry, VerdictWord } from "./types.js";
+/**
+ * A stored spec, defensively: untrusted JSON → a BlocksSpec, or null when it
+ * is not one. NOT registry validation — rendering must degrade per block,
+ * not refuse the whole page. A JSON string (a double-encoded jsonb scalar)
+ * is decoded first.
+ */
+export declare function coerceBlocksSpec(input: unknown): BlocksSpec | null;
+export declare function reviewKey(blockId: string): string;
+/**
+ * Block types whose verdicts are per ITEM inside their own state. Known by
+ * name so the census holds even before a host registers the block (it then
+ * counts zero items and never offers a block-level verdict); a registered
+ * block with an `itemReview` hook joins automatically.
+ */
+export declare const ITEM_REVIEW_BLOCK_TYPES: ReadonlySet<string>;
+export declare function isItemReviewBlock(type: string): boolean;
+/** The id of a decision callout's free-text "Other" choice. */
+export declare const OTHER_ID = "__other__";
+/** A decision callout: answered by its own pick, never by a verdict strip. */
+export declare function isDecisionBlock(type: string, params: unknown): boolean;
+/**
+ * Does this block take the block-level verdict strip (and count as one
+ * review unit)? Never an item-review block or a decision callout.
+ * Otherwise the spec decides with `params.reviewable: true|false` (a page
+ * intro sets `reviewable: false` explicitly — PARAMS-SPEC §3); absent that,
+ * only the work-product types do.
+ */
+export declare function takesBlockVerdict(type: string, params: unknown): boolean;
+export interface DecisionOption {
+    letter: string;
+    /** The callout option id this letter stands for (OTHER_ID for "Other"). */
+    id: string;
+    label: string;
+}
+export interface DecisionCard {
+    question: string;
+    options: DecisionOption[];
+}
+/**
+ * The page's decision cards: `callout` blocks with variant `decision`.
+ * Answered with a LETTER: options get A, B, C… by position unless they
+ * carry their own, and an `allowOther` card's "Other" takes the next free
+ * letter.
+ */
+export declare function decisionCardsOf(spec: unknown): Map<string, DecisionCard>;
+/**
+ * The contract verdicts a Send carries, read from a viewer's blocks map:
+ * each decision card's pick as `chose` + its letter, and each
+ * verdict-taking block's `review:<id>` entry. Item-review blocks carry
+ * their verdicts per item (itemVerdictsOf), never here.
+ */
+export declare function verdictsFromBlocks(spec: unknown, blocks: Record<string, unknown> | null): Record<string, VerdictEntry>;
+/** A saved chrome verdict, defensively. */
+export declare function blockReviewStateOf(blocks: Record<string, unknown>, blockId: string): BlockReviewState | null;
+/** The items of one item-review block (through its def's hook). Empty when
+ * the block is unregistered or declares no hook. */
+export declare function reviewItemsOf(type: string, params: unknown, state: unknown): ReviewItem[];
+/** The chrome vocabulary: per-block verdicts plus decision picks. */
+export declare const BLOCKS_VOCABULARY: VerdictWord[];
+/**
+ * The word a stored verdict shows in `vocab`. `raw` is the block's own id;
+ * a spelling the vocabulary does not know falls back to the vocabulary's
+ * word for the same bucket. null = no word.
+ */
+export declare function wordFor(vocab: VerdictWord[], raw: string | null, bucket: string | null): VerdictWord | null;
+/** One block's units in that block's own words. */
+export interface ReviewUnitLine {
+    /** The item-review block's id, or "blocks" for the page's other blocks. */
+    key: string;
+    /** The vocabulary key: the block type, or "blocks". */
+    vocab: string;
+    words: VerdictWord[];
+    title: string;
+    /** Decided units per verdict id of `words`. */
+    counts: Record<string, number>;
+    total: number;
+    retest: number;
+}
+/** What the Finish review panel counts: reviewable units, not blocks. */
+export interface ReviewUnitCounts {
+    total: number;
+    approved: number;
+    needsWork: number;
+    rejected: number;
+    /** Decision callouts answered with a pick. */
+    chose: number;
+    /** Undecided items the team reopened for this viewer. */
+    retest: number;
+    /** Item-review blocks on the page (0 → a page of plain blocks). */
+    itemBlocks: number;
+    lines: ReviewUnitLine[];
+}
+/**
+ * Count one viewer's reviewable units: every item of an item-review block,
+ * every decision callout, and the approve / needs-a-pass of every block that
+ * takes one. Information blocks are not units. `blocks` is the viewer's
+ * saved blocks map.
+ */
+export declare function countReviewUnits(spec: unknown, blocks: Record<string, unknown>): ReviewUnitCounts;
+/** The props of one jatui ReviewProgress. */
+export interface ReviewProgressProps {
+    verdicts: VerdictWord[];
+    counts: Record<string, number>;
+    total: number;
+    retest: number;
+    decidedWord: string;
+}
+/** The page Finish bar's progress. */
+export interface PageReviewProgress extends ReviewProgressProps {
+    /** Empty when every unit on the page speaks one vocabulary. Otherwise one
+     * ReviewProgress per block, and the bar above is the total by tone only. */
+    lines: (ReviewProgressProps & {
+        key: string;
+        title: string;
+    })[];
+    /** "5 of 7 decided · 1 to retest" — the mixed page's headline. */
+    headline: string;
+}
+/**
+ * The Finish review bar's progress, aggregated by tone but LABELLED with
+ * the page's own words: one vocabulary → one sentence; mixed vocabularies
+ * → each block keeps its own sentence. Never folds one word into another.
+ */
+export declare function pageReviewProgress(c: ReviewUnitCounts): PageReviewProgress;
+/** One still-open review unit, identified well enough to JUMP to it. */
+export interface OpenReviewUnit {
+    /** Stable jump key: the block id, or `blockId:itemId` for an item. */
+    key: string;
+    blockId: string;
+    type: string;
+    /** Item-review blocks only: the item's id inside its block. */
+    itemId?: string;
+    /** The item's title, the decision question, or the block's params title
+     * ("" when a plain verdict block has none — the view falls back). */
+    label: string;
+    /** The holding block's title, for items only. */
+    context?: string;
+    thumb?: string;
+    retest: boolean;
+}
+/**
+ * The page's still-open review units, in page order — the census walk with
+ * IDENTITY, so `openReviewUnits(...).length` is exactly the page's
+ * undecided count.
+ */
+export declare function openReviewUnits(spec: unknown, blocks: Record<string, unknown>): OpenReviewUnit[];
+/**
+ * Item verdicts from item-review blocks in the viewer's saved state, only
+ * items the viewer gave a verdict (an authored seed is not theirs). The
+ * page's changed-after-send diff runs this SAME read on both sides.
+ */
+export declare function itemVerdictsOf(saved: Record<string, unknown> | null, spec: unknown): SentItemsMap;
+/**
+ * The seeded done state from a stored event payload (`sentVerdicts`,
+ * `sentItems`). Untrusted JSON: an entry that does not parse DROPS the
+ * whole map — the page then reads "sent, details unknown" — never a wrong
+ * changed-state from a malformed row.
+ */
+export declare function coerceSentAnswer(input: {
+    sentAt: string;
+    sentTo: string | null;
+    payload: Record<string, unknown>;
+    eventId?: string;
+    deliveredAt?: string | null;
+    deliverable?: boolean;
+}): SentAnswer;
+export interface ChangedSinceSend {
+    blocks: number;
+    items: number;
+    /** blocks + items — the (n) on "Send changes". */
+    total: number;
+}
+/**
+ * Which sent entries differ from the viewer's current decisions. Sent maps
+ * ABSENT → all zeros: unknown is never reported as changed.
+ */
+export declare function changedSinceSend(sentVerdicts: Record<string, VerdictEntry> | null | undefined, currentVerdicts: Record<string, VerdictEntry>, sentItems: SentItemsMap | null | undefined, currentItems: SentItemsMap): ChangedSinceSend;
+/** The one-line "what was sent" of the done state. "" for a note-only answer. */
+export declare function sentAnswerLine(verdicts: Record<string, VerdictEntry> | null | undefined, items: SentItemsMap | null | undefined): string;