courthive-components 6.0.1 → 6.2.0

package/dist/components/scoring/logic/scoreEntrySelectors.d.ts

@@ -0,0 +1,88 @@
+import { ScoreEntryResolution, SideNumber } from './scoreEntryState';
+import { ScoreEntryModel } from './scoreEntryModel';
+import { SetScore } from '../types';
+/** One visible column: a set's principal cells, or the tiebreak cells beside a set that went to one. */
+export type ScoreSlot = {
+    kind: 'games' | 'tiebreak';
+    setIndex: number;
+};
+export type ColumnOptions = {
+    /**
+     * A set the operator has clicked back into, whose tiebreak column stays open though its points are
+     * known. Presentation, held by the region — passed in rather than kept in the model.
+     */
+    editingSet?: number;
+};
+/** The ending, resolved. The one place `resolveScoreEntry` is asked about a model. */
+export declare function resolveEnding(model: ScoreEntryModel): ScoreEntryResolution;
+/** Sets with BOTH principal cells in, in factory shape, positioned by `setNumber`. A partial set is not here. */
+export declare function enteredSets(model: ScoreEntryModel): SetScore[];
+/** The entered sets that are SETTLED — see `isSettled`. A `4-2` is entered; it is not completed. */
+export declare function completedSets(model: ScoreEntryModel): SetScore[];
+/** Whether ANYTHING has been typed, complete or not — a single digit counts. */
+export declare function hasEntry(model: ScoreEntryModel): boolean;
+/** The score as it stands, in the factory's own line — or nothing while an ending has set it aside. */
+export declare function scoreString(model: ScoreEntryModel): string | undefined;
+/** What a score-clearing ending set aside, so the band can name it. Nothing unless one is chosen. */
+export declare function discardedScore(model: ScoreEntryModel): string | undefined;
+/**
+ * Whether the score is a FINISHED result: the factory names a winner, the last set is settled, and
+ * nothing is wrong with what came before it. An ending that discards the score makes this false,
+ * because there is no result to be finished.
+ */
+export declare function isComplete(model: ScoreEntryModel): boolean;
+/** The winner: the ending's when it names one, otherwise the finished score's. */
+export declare function winningSide(model: ScoreEntryModel): SideNumber | undefined;
+/** The ending's status when one is chosen; `COMPLETED` for a finished score; nothing otherwise. */
+export declare function matchUpStatus(model: ScoreEntryModel): string | undefined;
+/**
+ * The first thing wrong with the score, in words, or `undefined`.
+ *
+ * Three checks, in order:
+ *
+ *   1. a tiebreak that contradicts who won the set, with the participant NAMED — the factory refuses it
+ *      too, but "side 1" is not a message an operator can act on;
+ *   2. the FACTORY's judgement of each entered set (`validateSetScore` with `allowIncomplete`), which
+ *      forgives unfinished games but knows `3-7` cannot be. A set whose tiebreak points are still owed
+ *      is skipped, because the card is asking for them and an error at that moment would answer its
+ *      own question;
+ *   3. invariant 10A: a set before the last entered one that is empty or unfinished.
+ *
+ * Silent while a score-clearing ending is chosen: nothing typed will be submitted.
+ */
+export type ErrorOptions = {
+    /** Names for the two sides, so a message can say who rather than "side 1". */
+    sideNames?: [string, string];
+};
+export declare function error(model: ScoreEntryModel, options?: ErrorOptions): string | undefined;
+/**
+ * The visible columns, left to right.
+ *
+ * Every set that holds anything is shown, whatever came before it — this is the rule that ends the
+ * ghost set: a cleared set 1 beside a typed set 2 shows BOTH, one empty and one full, so the operator
+ * sees the score the model has. Then one empty set opens after the last holding one, and only when
+ * everything before it is settled and the match is not decided; a timed format plays every bolt, so
+ * for it the only question is whether one is left. A tiebreak column sits beside a set whose games call
+ * for points it does not yet have, or that the operator has reopened.
+ */
+export declare function columns(model: ScoreEntryModel, options?: ColumnOptions): ScoreSlot[];
+/**
+ * Whether a set is finished: both principal cells in, no tiebreak points owed, and the factory accepts
+ * it as a COMPLETE legal set. A `7-6` whose points are unknown is not settled, so the next set does not
+ * open under it.
+ *
+ * ── Strict `validateSetScore`, and not `analyzeSet`'s winning side ──
+ *
+ * Measured 2026-09-30, before `#5049(factory)`: `analyzeSet` named a winner for a `3-1` in a match
+ * tiebreak to ten, and for a `10-9` — any lead read as a win. Both answers are fixed in 7.4.0, and
+ * `dynamicSetsLogic` now asks the factory too. Strict validation stays the rule here all the same: it is
+ * the same answer `error` reports, so "settled" and "no error" cannot come apart.
+ *
+ * A timed set is the exception: any pair of scores ends it, a tie included, so both cells in is the
+ * whole test — strict validation refuses a `0-0` bolt, which is unusual but not impossible.
+ */
+export declare function isSettled(model: ScoreEntryModel, index: number): boolean;
+/** Whether the set's games call for a tiebreak whose points the operator has not supplied yet. */
+export declare function tiebreakOutstanding(model: ScoreEntryModel, index: number): boolean;
+/** The value in one cell. Exported for regions, which render cells from the model and never read them back. */
+export declare function cellValue(model: ScoreEntryModel, setIndex: number, side: SideNumber, kind: ScoreSlot['kind']): number | undefined;

package/dist/components/scoring/logic/scoreEntryState.d.ts

@@ -0,0 +1,163 @@
+import { IrregularEndingResolution } from './irregularEnding';
+/** Which side a per-side ending was recorded against. */
+export type SideNumber = 1 | 2;
+/**
+ * Everything the card holds that is not the score itself.
+ *
+ * The score lives in the score region (per-set inputs, a text field, or a keypad) and is passed in
+ * when resolving, because all three regions already own it and the card must not become a second
+ * place it can be edited.
+ */
+export type ScoreEntryState = {
+    /**
+     * The side that ended early, and how. `sideNumber` is the side the ending HAPPENED TO — the one
+     * that retired or failed to appear — not the winner. The winner is derived from it.
+     */
+    sideEnding?: {
+        sideNumber: SideNumber;
+        status: string;
+    };
+    /**
+     * "…did not appear either — no one advances." The checkbox on the affected row that turns a side
+     * ending into a double exit.
+     *
+     * A separate flag rather than a third value on `sideEnding`, because it is a different assertion:
+     * the operator has said something about the OTHER side. Collapsing them is how the old tri-state
+     * came to treat "unanswered" and "neither" as the same thing.
+     */
+    bothSidesOut?: boolean;
+    /** The match-level ending. One of the seven; mutually exclusive with `sideEnding`. */
+    matchEnding?: string;
+    /** The policy reason code chosen for whichever ending is selected. */
+    reasonCode?: string;
+};
+/** What the card resolves to, plus the two things the UI needs that a resolution alone does not say. */
+export type ScoreEntryResolution = IrregularEndingResolution & {
+    /** True when the selected ending means a typed score must be discarded rather than submitted. */
+    clearsScore: boolean;
+    /** True when an ending is selected at all, so the score region can render itself inert. */
+    hasEnding: boolean;
+};
+/** The empty card: no ending chosen, which is a reachable state and not a null one. */
+export declare const emptyScoreEntryState: ScoreEntryState;
+/**
+ * Record (or un-record) a per-side ending.
+ *
+ * Every control in the card is a TOGGLE, so choosing the ending already selected on that same side
+ * clears it. This is what gives the card a reachable empty state; a radio group has none, which is
+ * GOV.UK's standing objection to pre-selected radios — a user cannot get back to "nothing chosen"
+ * without reloading the page.
+ *
+ * Choosing a side ending clears any match-level ending, and vice versa. They answer the same
+ * question — how did this match end — so allowing both would let the card hold two answers and
+ * submit whichever the resolver happened to read first.
+ *
+ * `bothSidesOut` and `reasonCode` are dropped on any change of ending, because both are qualifiers
+ * OF an ending: a reason code chosen for a retirement is not a reason for a walkover, and the codes
+ * come from different policy groups. Carrying either across would submit a qualifier the operator
+ * never chose for the ending it ends up attached to.
+ */
+export declare function chooseSideEnding(state: ScoreEntryState, sideNumber: SideNumber, status: string): ScoreEntryState;
+/**
+ * Record (or un-record) a match-level ending. A toggle, on the same reasoning as above.
+ */
+export declare function chooseMatchEnding(state: ScoreEntryState, status: string): ScoreEntryState;
+/**
+ * Toggle "the other side did not appear either".
+ *
+ * Refused when there is no side ending to qualify, and refused when the ending has no double form:
+ * RETIRED is the case — the factory has no double-retirement status, and two players who both fail
+ * to finish are a double default or a double walkover depending on why, which is the operator's
+ * distinction to make and not one this module can infer. Returning the state unchanged rather than
+ * setting a flag that cannot resolve keeps the card from offering a checkbox whose answer is dropped.
+ */
+export declare function toggleBothSidesOut(state: ScoreEntryState): ScoreEntryState;
+/** Whether the card should offer the "did not appear either" checkbox at all. */
+export declare function offersBothSidesOut(state: ScoreEntryState): boolean;
+/** Choose (or clear) a reason code for the selected ending. A toggle, like everything else. */
+export declare function chooseReasonCode(state: ScoreEntryState, code: string | undefined): ScoreEntryState;
+/**
+ * The status whose policy code group the reason chips should come from.
+ *
+ * `undefined` when no ending is selected, because there is nothing to give a reason for.
+ */
+/**
+ * The card's state for a matchUp that ALREADY has an outcome.
+ *
+ * Without this the dialog opened blank on a scored matchUp: no recorded ending, no reason code. The
+ * shipping modal hydrates, so swapping the card in without this would lose the display of every outcome
+ * already entered — CA, 2026-09-28: *"we need to be able to open existing outcomes!"*
+ *
+ * ── The one inversion, again ──
+ *
+ * A stored matchUp names the WINNER. This card records the side the ending HAPPENED TO, and derives the
+ * winner from it. So hydration runs that mapping backwards: the exiting side is the one that did not
+ * win. `hydrateIrregularEnding` is reused for the status itself rather than re-deriving it, so the
+ * reverse lookup from `DOUBLE_WALKOVER` to the `WALKOVER` an operator actually clicks lives in exactly
+ * one place.
+ *
+ * Three cases and a refusal:
+ *
+ *   - a DOUBLE exit — both sides out, so no side is distinguished. `sideNumber: 1` is arbitrary and only
+ *     decides nothing: `bothSidesOut` makes the resolution `NEITHER_SIDE`, and the card draws the pill on
+ *     both rows regardless.
+ *   - an ending that resolves NOBODY — recorded at match level, because there is no side to attach it to.
+ *   - a single exit — recorded against `3 - winningSide`.
+ *   - a winner-requiring status with NO winning side is a corrupt record, and is refused: it returns the
+ *     empty state rather than inventing a placement. `hydrateIrregularEnding` makes the same choice for
+ *     an unmapped double exit, and for the same reason — a guess here silently advances a participant.
+ */
+export declare function hydrateScoreEntryState(matchUp?: {
+    matchUpStatus?: string;
+    winningSide?: number;
+    sideStatusCodes?: Record<number, string>;
+    matchUpStatusCode?: string;
+    matchUpStatusCodes?: unknown[];
+}): ScoreEntryState;
+export declare function reasonCodeStatus(state: ScoreEntryState): string | undefined;
+/**
+ * Resolve the card into a submittable outcome.
+ *
+ * ── The one piece of derivation that lives here ──
+ *
+ * A per-side ending is recorded against the side it HAPPENED TO, and the winner is the other side.
+ * That inversion is the whole reason the separate winner question can be deleted, so it is stated
+ * once, here, and asserted on its own:
+ *
+ *     sideEnding.sideNumber === 1  →  winnerSelection 2
+ *
+ * Everything past that point is `resolveIrregularEnding`'s answer, unmodified — including the
+ * fail-closed states. Note in particular that a side ending with `bothSidesOut` on an ending with no
+ * double form cannot occur, because `toggleBothSidesOut` refuses to set it; if it somehow does, the
+ * resolver's own guard returns `isValid: false` rather than inventing a status.
+ */
+export declare function resolveScoreEntry(state: ScoreEntryState): ScoreEntryResolution;
+/**
+ * A resolution for an ending the SCORE REGION reported rather than the operator selected.
+ *
+ * Free Score parses endings out of typed text — "6-4 ret" is a retirement — and that must keep
+ * working, because typing the whole result is the entire reason that approach exists. But the card now
+ * owns endings through its own controls, so two sources can speak at once and the precedence has to be
+ * stated rather than emergent:
+ *
+ *   **An explicitly selected ending always wins.** A region-reported one is used only when the
+ *   operator has selected nothing.
+ *
+ * That direction and not the other, because a click is an unambiguous instruction and parsed text is
+ * an inference. An operator who types "ret", then clicks Suspended, means Suspended; clearing the
+ * click falls back to what they typed, which is still on screen in front of them.
+ *
+ * Resolution goes through `resolveIrregularEnding` like everything else, so a parsed ending and a
+ * clicked one cannot disagree about what they mean — only about which one applies.
+ */
+export declare function resolveReportedEnding(matchUpStatus?: string, winningSide?: number): ScoreEntryResolution;
+/**
+ * Which endings the card offers on a player row, and which in the match-level group.
+ *
+ * Derived from the same two sets the approaches use, in `SELECTABLE_ENDINGS` order, so the card
+ * cannot offer an ending the vocabulary does not hold or drop one it does. The split is not a layout
+ * choice: it is `WINNER_REQUIRING_STATUSES` and `NON_DIRECTING_ENDINGS`, which come from the
+ * factory's `directingMatchUpStatuses` / `nonDirectingMatchUpStatuses`.
+ */
+export declare function sideEndingOptions(): string[];
+export declare function matchEndingOptions(): string[];

package/dist/components/scoring/logic/scoreEntryStore.d.ts

@@ -0,0 +1,8 @@
+import { CreateScoreEntryModelParams, ScoreEntryModel } from './scoreEntryModel';
+export type ScoreEntryStore = {
+    /** The model as it stands. Never mutated; read it again after any transition. */
+    get: () => ScoreEntryModel;
+    /** Replace the model. The caller says what must be redrawn. */
+    set: (next: ScoreEntryModel) => void;
+};
+export declare function createScoreEntryStore(params?: CreateScoreEntryModelParams): ScoreEntryStore;

package/dist/components/scoring/logic/scoreEntrySummary.d.ts

@@ -0,0 +1,28 @@
+import { ScoreEntryResolution } from './scoreEntryState';
+export type ResultTone = 'good' | 'warn' | 'neutral';
+export type ResultBand = {
+    tone: ResultTone;
+    /** The main sentence. Always present — a band with no headline would be a band with no purpose. */
+    headline: string;
+    /** The quieter right-hand note: what happens next, or what was recorded. */
+    detail?: string;
+};
+export type SummaryParams = {
+    resolution: ScoreEntryResolution;
+    /** Side 1's name first. */
+    sideNames: [string, string];
+    /** The score as it currently stands, already formatted (e.g. `'6-4 2-1'`). */
+    scoreString?: string;
+    /** Whether that score is a finished result — the score region's judgement, not this module's. */
+    scoreComplete?: boolean;
+    /** The winner a complete score implies, when no ending overrides it. */
+    scoreWinningSide?: 1 | 2;
+    /** Display labels for endings, so a locale can supply them. Defaults to English. */
+    labels?: Record<string, string>;
+    /** The chosen reason code's display form, e.g. `'Wo [inj]'`. */
+    reasonDisplay?: string;
+    /** What the winner advances to, e.g. `'the quarter-final'`. Omitted when unknown. */
+    advancesTo?: string;
+};
+/** The band for the current state of the card. */
+export declare function scoreEntrySummary(params: SummaryParams): ResultBand;

package/dist/components/scoring/logic/statusCodes.d.ts

@@ -42,6 +42,40 @@ export declare function groupKeyForStatus(matchUpStatus: string | undefined): st
  *
  * Returns `undefined` for a provenance element, which carries no code at all.
  */
+/**
+ * The reason code a matchUp actually recorded, for the control that has to re-display it.
+ *
+ * ── Why not `matchUpStatusCodes[0]` ──
+ *
+ * `matchUpStatusCodes` is POSITIONAL BY SIDE, so a reason belonging to side 2 sits at index 1 and
+ * index 0 is an empty string that `normalizeStatusCode` turns into `undefined`. The picker then opens
+ * empty, the operator's reason is missing from the control meant to show it, and re-saving loses it.
+ *
+ * Measured against published **7.1.0**, because the exposure is narrower than it first looks: a code
+ * submitted by this dialog is stored EXACTLY as submitted, so `['W1']` round-trips through index 0 and
+ * reads correctly today. The index-1 case arrives by PROPAGATION — a reason carried into a connected
+ * structure is placed at the arriving side's index — and factory #5016 both fixes that carry and gives
+ * the fact a home that states what it attributes to.
+ *
+ * ── The order, and why each step is needed ──
+ *
+ * 1. `sideStatusCodes[sideNumber]` — the side's own, once the factory writes it.
+ * 2. `matchUpStatusCode` — the MATCH's, for an ending that resolves nobody (ABANDONED, CANCELLED,
+ *    INCOMPLETE). There is no side to ask.
+ * 3. `matchUpStatusCodes[0]` — records written before either field existed. Not optional: the peer
+ *    range still admits a factory major that has neither, so dropping it would read nothing at all
+ *    from every record stored to date.
+ *
+ * The fields are mirrored onto this package's own `MatchUp` rather than imported from the factory, for
+ * the reason `types.ts` already records: they do not exist in the older major the peer range admits.
+ */
+export declare function recordedStatusCode(matchUp?: {
+    matchUpStatus?: string;
+    winningSide?: number;
+    sideStatusCodes?: Record<number, string>;
+    matchUpStatusCode?: string;
+    matchUpStatusCodes?: unknown[];
+}): string | undefined;
 export declare function normalizeStatusCode(entry: unknown): string | undefined;
 /**
  * The codes a policy offers for this status, or an empty list when it offers none.

package/dist/components/scoring/logic/tiebreakEntry.d.ts

@@ -0,0 +1,14 @@
+import { SetFormat } from './dynamicSetsLogic';
+import { SideNumber } from './scoreEntryState';
+/** The points a tiebreak-only set is played to, or `undefined` if this set is not one. */
+export declare function tiebreakOnlyTarget(setFormat?: SetFormat): number | undefined;
+/**
+ * Both sides' points, from the LOWER score and the side it was entered on.
+ *
+ * `undefined` when the set carries no target to complete against, or when the factory declines — never
+ * a guess. The caller leaves what was typed alone in that case rather than inventing the other half.
+ */
+export declare function completeTiebreakOnly(lowValue: number, lowSide: SideNumber, setFormat?: SetFormat): {
+    side1: number;
+    side2: number;
+} | undefined;

package/dist/components/scoring/regions/dialPadRegion.d.ts

@@ -0,0 +1,17 @@
+import { ScoreEntryStore } from '../logic/scoreEntryStore';
+import { ScoreRegion } from '../scoreEntryCard';
+import { SetScore } from '../types';
+export type DialPadRegionParams = {
+    /** The model the card holds. Omit it and the region makes its own from the params below. */
+    store?: ScoreEntryStore;
+    matchUpFormat?: string;
+    /** Sets already recorded, e.g. from a saved matchUp. Read only when no `store` is given. */
+    sets?: SetScore[];
+    onChange?: () => void;
+};
+export type DialPadRegion = ScoreRegion & {
+    store: ScoreEntryStore;
+    /** The entered sets, for a host or a test reading the region directly. The card reads the model. */
+    getSets: () => SetScore[];
+};
+export declare function createDialPadRegion(params: DialPadRegionParams): DialPadRegion;

package/dist/components/scoring/regions/dynamicSetsRegion.d.ts

@@ -0,0 +1,28 @@
+import { ScoreRegion } from '../scoreEntryCard';
+import { ScoreEntryStore } from '../logic/scoreEntryStore';
+import { SetScore } from '../types';
+export type DynamicSetsRegionParams = {
+    /** The model the card holds. Omit it and the region makes its own from the params below. */
+    store?: ScoreEntryStore;
+    matchUpFormat?: string;
+    /** Participant names, so an integrity message can say who rather than "side 1". */
+    sideNames?: [string, string];
+    /** Sets already recorded, e.g. from a saved matchUp. */
+    sets?: SetScore[];
+    /** Whether smart complements starts enabled. Defaults to on. */
+    smartComplements?: boolean;
+    smartComplementsLabel?: string;
+    /** Called after a change affecting only the score. Wire to the card's `refresh`. */
+    onChange?: () => void;
+    /** Called when the COLUMNS change. Wire to the card's `rerender`. */
+    onStructureChange?: () => void;
+};
+export type DynamicSetsRegion = ScoreRegion & {
+    store: ScoreEntryStore;
+    /** The entered sets, for a host or a test reading the region directly. The card reads the model. */
+    getSets: () => SetScore[];
+    /** The model's integrity message, named with this region's `sideNames`. The card computes its own. */
+    error: () => string | undefined;
+    smartComplementsEnabled: () => boolean;
+};
+export declare function createDynamicSetsRegion(params: DynamicSetsRegionParams): DynamicSetsRegion;

package/dist/components/scoring/regions/freeScoreRegion.d.ts

@@ -0,0 +1,24 @@
+import { ScoreEntryStore } from '../logic/scoreEntryStore';
+import { ScoreRegion } from '../scoreEntryCard';
+import { SetScore } from '../types';
+export type FreeScoreRegionParams = {
+    /** The model the card holds. Omit it and the region makes its own from the params below. */
+    store?: ScoreEntryStore;
+    matchUpFormat?: string;
+    /** The score to open with, already formatted (e.g. `'6-4 6-3'`). With a `store`, the model's own line is used. */
+    initialText?: string;
+    /** Label above the field. */
+    label?: string;
+    /** Called after any change. Wire to the card's `refresh`. */
+    onChange?: () => void;
+};
+export type FreeScoreRegion = ScoreRegion & {
+    store: ScoreEntryStore;
+    /** What is currently in the field. */
+    getText: () => string;
+    /** The entered sets, for a host or a test reading the region directly. The card reads the model. */
+    getSets: () => SetScore[];
+    /** Text in the field counts as entry the model cannot see; required here. */
+    hasEntry: () => boolean;
+};
+export declare function createFreeScoreRegion(params: FreeScoreRegionParams): FreeScoreRegion;

package/dist/components/scoring/regions/scoreLine.d.ts

@@ -0,0 +1,2 @@
+import { SetScore } from '../types';
+export declare function scoreLine(sets: SetScore[], matchUpFormat?: string): string | undefined;

package/dist/components/scoring/regions/scoreReadout.d.ts

@@ -0,0 +1,11 @@
+import { SideNumber } from '../logic/scoreEntryState';
+import { SetScore } from '../types';
+/** The track width for the readout column, matching the artboards. */
+export declare const READOUT_COLUMN_WIDTH = "200px";
+export type ScoreReadouts = {
+    /** The cell for a side's row. Registers it, so later `update` calls reach it. */
+    cell: (sideNumber: SideNumber, sets: SetScore[]) => HTMLElement;
+    /** Rewrite every registered readout from the current sets. */
+    update: (sets: SetScore[]) => void;
+};
+export declare function createScoreReadouts(): ScoreReadouts;

package/dist/components/scoring/regions/setColumns.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Labels for the score columns.
+ *
+ * Shared by every region that renders per-set columns, so the Dial Pad and Dynamic Sets cannot end up
+ * heading the same column differently.
+ */
+/**
+ * The column heading for a set: `1st`, `2nd`, `3rd`, `4th`, `5th`.
+ *
+ * CA, 2026-09-27, replacing `SET 1` / `SET 2` / `SET 3`. Shorter matters here for a reason beyond
+ * taste: the heading sits above a 62px column, and `SET 1` is wide enough that shrinking the column
+ * on a narrow viewport would either clip it or force the 44px input below its minimum target.
+ *
+ * The teens are handled even though a match will never have eleven sets, because an ordinal function
+ * that is wrong for 11 is simply a wrong ordinal function, and the next caller will not check.
+ */
+export declare function ordinalSetLabel(setNumber: number): string;

package/dist/components/scoring/scoreEntryCard.d.ts

@@ -0,0 +1,191 @@
+import { ScoreEntryState, SideNumber } from './logic/scoreEntryState';
+import { ScoreEntryModel } from './logic/scoreEntryModel';
+import { ScoreEntryStore } from './logic/scoreEntryStore';
+import { StatusCodeGroups } from './logic/statusCodes';
+/**
+ * One column the region contributes to the participant rows.
+ *
+ * `heading` and `width` travel TOGETHER deliberately. The header row and the participant rows are
+ * built from this one array, so a heading can never end up over a column it does not describe — the
+ * correspondence is structural rather than two lists that have to be kept the same length by hand.
+ * CA asked for that alignment explicitly (2026-09-27) and this is what makes it hold rather than a
+ * rule someone has to remember.
+ *
+ * A column with no `heading` renders no header cell, and a region whose columns are all unheaded gets
+ * no header row at all — which is what Free Score and the Dial Pad want, since their single readout
+ * column needs no label.
+ */
+export type ScoreColumn = {
+    /** The heading above this column, e.g. `1st`. Omit for an unlabelled column. */
+    heading?: string;
+    /** A CSS grid track size. Defaults to the standard score-column width. */
+    width?: string;
+};
+/**
+ * What a score region IS, now that the card holds the model: render, and intent.
+ *
+ * S5 of the state-engine extraction. This contract used to carry fourteen members, six of which were
+ * ANSWERS — `scoreString`, `isComplete`, `winningSide`, `error`, `hasEntry`, `getSets` — computed by each
+ * region on the spot from its private copy of the score. Those are selectors over the model now, asked
+ * by the card, and a region that still answered them would be a second opinion the card ignores.
+ *
+ * What is left is what a region genuinely knows and the model cannot: how to DRAW the score (cells,
+ * a block, a control for the band), where entry begins, what is its own to reset after the model was
+ * emptied, and — for Free Score only — what the TEXT says that the model cannot represent: an ending
+ * parsed out of it, and a half-typed field.
+ */
+export type ScoreRegion = {
+    /**
+     * The store the region renders, when it made its own.
+     *
+     * A region built standalone — the behavioural tests, or a host placing a card inline — creates a store
+     * from its params, and the card adopts it so the two share one model. A host that opens the dialog
+     * gives the same store to the card and every region, and this is never consulted.
+     */
+    store?: ScoreEntryStore;
+    /** The columns this region contributes to each participant row. */
+    columns?: () => ScoreColumn[];
+    /** The cells to place in one side's row. Must return one per column. */
+    rowCells?: (sideNumber: SideNumber) => HTMLElement[];
+    /** A block beneath the rows — a text field, or a keypad. */
+    block?: () => HTMLElement;
+    /**
+     * A compact control the region wants in the result band's right edge rather than in a row of its own.
+     *
+     * CA, 2026-09-27, on the smart-complements checkbox: *"I don't think '[] Smart Complements' should take
+     * up a whole row of the modal. I think it can be a little icon to the far right side of the row where you
+     * have 'No result entered yet'. Just (Smart) maybe, something compact that toggles."*
+     *
+     * It stays a REGION concern — it is a Dynamic Sets behaviour and nothing else reads it — so the region
+     * supplies the element and the card only decides where it sits.
+     */
+    bandControl?: () => HTMLElement | undefined;
+    /**
+     * A matchUpStatus the region itself parsed out of what was typed — Free Score only.
+     *
+     * REPORTED, not selected: an inference about the text, which never enters the model's `ending`. Used
+     * ONLY when the operator has selected no ending. See `resolveReportedEnding` for why that precedence
+     * and not the other.
+     */
+    matchUpStatus?: () => string | undefined;
+    /**
+     * Reset what is the region's own after the card has emptied the model: a text field, a keypad mode,
+     * the set under edit. The score itself is already gone by the time this is called.
+     */
+    clear?: () => void;
+    /**
+     * Put focus where entry begins, selecting what is there.
+     *
+     * Selecting matters as much as focusing: the old dialog's `focusAndSelect` is why typing into a cell
+     * that already holds a score REPLACES it. Used after `[Clear]`, and by a host opening the dialog.
+     */
+    focusFirst?: () => void;
+    /**
+     * Entry the MODEL cannot see — Free Score's half-typed text. The card asks the model first and this
+     * second, so a `6-4 re` mid-word still counts as something to lose.
+     */
+    hasEntry?: () => boolean;
+};
+/** One entry in the approach switcher's menu. */
+export type ApproachOption = {
+    /** Reported to `onSelectApproach`. The host's own name for the approach. */
+    key: string;
+    label: string;
+};
+/**
+ * What the card reports when Submit is pressed.
+ *
+ * `winningSide` is the ending's where one was recorded and the SCORE's otherwise. Both are real answers
+ * and a host needs whichever applies: measured 2026-09-27, this carried only the ending's, so an
+ * ordinary 6-4 6-3 submitted as `{ matchUpStatus: undefined, winningSide: undefined }` — the 95% case
+ * reporting nothing at all about who won.
+ */
+export type ScoreEntryOutcome = {
+    matchUpStatus?: string;
+    winningSide?: number;
+    reasonCode?: string;
+    /** The score as the region formats it, which is what a host stores alongside the outcome. */
+    score?: string;
+    /**
+     * The operator cleared a recorded outcome and submitted the empty result — REMOVE what is stored.
+     *
+     * Only ever `true`, never `false`, so a host that does not know about it is unaffected. It exists
+     * because an empty outcome is otherwise indistinguishable from a submission that says nothing, and
+     * the two must not be treated alike: one erases a stored score and the other must not.
+     */
+    cleared?: boolean;
+};
+export type ScoreEntryCardParams = {
+    sides: [{
+        participantName: string;
+        seed?: string;
+    }, {
+        participantName: string;
+        seed?: string;
+    }];
+    matchUpFormat?: string;
+    /** e.g. `'R16 · Court 3'`. */
+    context?: string;
+    title?: string;
+    /** The score region for the active approach. */
+    region: ScoreRegion;
+    /**
+     * The model, when the host holds it — the dialog does, and shares it with every region it builds.
+     * Omitted, the card adopts the region's own store, or makes one.
+     */
+    store?: ScoreEntryStore;
+    /** The policy's reason-code groups, if the tournament has a scoring policy attached. */
+    statusCodeGroups?: StatusCodeGroups;
+    /** Ending labels, so a locale can supply them. */
+    labels?: Record<string, string>;
+    /** The approach switcher's current label, e.g. `'Dynamic Sets'`. Omit to hide the switcher. */
+    approachLabel?: string;
+    /**
+     * Offered when the switcher should present a CHOICE. The label of the active approach stays
+     * `approachLabel`; these are what it can become.
+     */
+    approaches?: ApproachOption[];
+    /** Called with the chosen approach's key. Wire to a host that swaps the region through `update`. */
+    onSelectApproach?: (key: string) => void;
+    /** Offered instead of `approaches` when the host drives switching from its own control. */
+    onSwitchApproach?: () => void;
+    /** Offered when the host can edit the scoring format. Omit and the format chip stays inert text. */
+    onEditFormat?: () => void;
+    onCancel?: () => void;
+    /** An ending already recorded, for reopening an outcome. Build it with `hydrateScoreEntryState`. */
+    initialState?: ScoreEntryState;
+    onClear?: () => void;
+    onSubmit?: (outcome: ScoreEntryOutcome) => void;
+    onClose?: () => void;
+};
+export type ScoreEntryCard = {
+    element: HTMLElement;
+    /** Re-render the band and the submit gate. Call when the score region's value changes. */
+    refresh: () => void;
+    /** Rebuild everything, including the region's cells. Call when the region's COLUMNS change. */
+    rerender: () => void;
+    /**
+     * Change the region (an approach switch) or the scoring format, keeping the ENDING state.
+     *
+     * Both inputs change while the dialog is open and both invalidate the region's cells, so they share one
+     * mutator. What they must NOT invalidate is the ending: a walkover recorded against a row is a fact
+     * about the match, not about the approach used to type it or the format the score is read under, and
+     * an operator who corrects `SET3-S:6/TB7` to `SET3-S:6/TB7@5` has not retracted it.
+     */
+    update: (next: {
+        region?: ScoreRegion;
+        matchUpFormat?: string;
+        approachLabel?: string;
+    }) => void;
+    /** The store the card renders, for a host that builds regions on it. */
+    store: ScoreEntryStore;
+    /** The model as it stands. */
+    getModel: () => ScoreEntryModel;
+    /** The current ending state — `getModel().ending` — for a host that needs to inspect it. */
+    getState: () => ScoreEntryState;
+    /** Whether anything at all has been entered: a score, an ending, or text the model cannot see. */
+    holdsEntry: () => boolean;
+    /** The DOM id of the card's heading, for a host's `aria-labelledby`. */
+    titleId: string;
+};
+export declare function renderScoreEntryCard(params: ScoreEntryCardParams): ScoreEntryCard;