courthive-components 4.4.0 → 4.5.0

package/dist/components/inline-scoring/inlineScoringTypes.d.ts

@@ -24,6 +24,8 @@ export interface InlineScoringCallbacks {
     onEndMatch?: (params: {
         matchUpId: string;
         matchUpStatus: string;
+        /** Resolved from the exiting side; absent for a double exit and the non-directing statuses. */
+        winningSide?: number;
         sideNumber?: number;
         engine: any;
     }) => void;

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

@@ -0,0 +1,141 @@
+/**
+ * Pure logic for resolving an irregular ending into a matchUpStatus.
+ *
+ * Every score-entry approach needs the same rule, and until now each one carried its own copy:
+ * "walkover with a winner is a WALKOVER, walkover without one is a DOUBLE_WALKOVER". Three copies
+ * of a rule is three chances to disagree about it, and they already disagreed about when Submit
+ * should be live.
+ *
+ * The rule this module encodes differs from those copies in one deliberate way. A missing winner
+ * used to mean "double exit" — so merely selecting Walkover produced a valid, submittable
+ * DOUBLE_WALKOVER before the operator had chosen anything. That is a fail-open default (Mentat
+ * architectural standard A3): the absence of an answer was read as a particular answer, and the
+ * particular answer it was read as is one of the most consequential outcomes in the draw, because a
+ * double exit advances nobody and propagates a walkover downstream.
+ *
+ * Here, absence is absence. `undefined` is "the operator has not answered yet" and is never valid;
+ * a double exit requires explicitly choosing NEITHER_SIDE. No DOM dependencies, no side effects.
+ */
+/**
+ * The winner-selection value meaning "no side won this matchUp" — the explicit choice that produces
+ * a double exit. A sentinel rather than `null` so the three states (unanswered / a side / neither)
+ * stay distinguishable in a radio group's string values.
+ */
+export declare const NEITHER_SIDE = "NEITHER";
+/** Shown when an irregular ending has been chosen but the winner question is unanswered. */
+export declare const WINNER_REQUIRED_ERROR = "Select a winner";
+/** The statuses whose selection opens the winner question at all. */
+export declare const WINNER_REQUIRING_STATUSES: Set<string>;
+/**
+ * Endings that resolve nobody: the match did not produce a result, so there is no winner to name
+ * and no winner question to answer. The factory classifies these as non-directing
+ * (`nonDirectingMatchUpStatuses`) — nothing advances out of them.
+ *
+ * These are NOT a smaller version of the winner-requiring endings. Asking "who won an abandoned
+ * match" is not a question with a missing answer; it is not a question. So unlike a walkover with
+ * no winner selection, one of these is valid the moment it is chosen.
+ */
+export declare const NON_DIRECTING_ENDINGS: Set<string>;
+/**
+ * Every irregular ending a set-entry approach offers, in display order.
+ *
+ * These six are exactly the keys the factory's scoring policy can refine with `matchUpStatusCodes`
+ * (ABANDONED, CANCELLED, DEFAULTED, INCOMPLETE, RETIRED, WALKOVER), which is why the list is this
+ * list: a status with no code group cannot carry a reason, and a code group with no status cannot
+ * be reached. Ordered so the three an operator reaches for most sit first.
+ */
+export declare const SELECTABLE_ENDINGS: string[];
+/** Whether choosing this ending obliges the operator to answer the winner question. */
+export declare function requiresWinner(selectedOutcome: string | undefined): boolean;
+/**
+ * Statuses that carry NO score at all, so there is nothing to validate and nothing to submit.
+ *
+ * This mirrors the factory, which is the authority: `modifyMatchUpScore.ts:236` blanks the score
+ * outright for exactly this set — `Object.assign(matchUp, { ...toBePlayed })`, commented "a walkover
+ * has none". Note what is NOT here: `DEFAULTED` and `DOUBLE_DEFAULT` are absent in the factory too,
+ * because a player can default part-way through a match that was genuinely played, and that partial
+ * score is real. The same goes for `RETIRED` — a retirement keeps whatever was played, and needs no
+ * completed set to be a valid result.
+ *
+ * `CANCELLED` and `DEAD_RUBBER` are deliberately NOT here even though this repo's `validateScore`
+ * strips scores for them. They are unreachable from the set-entry approaches today (only freeScore
+ * parses them) and the factory does not blank scores for them, so adding them here would be a
+ * guess. Revisit when the status list widens — see Mentat SCORING_MODAL_STATUS_CODES.md M2.
+ */
+export declare const NO_SCORE_STATUSES: Set<string>;
+/**
+ * Whether this ending means "no score exists", so score validation must be skipped rather than run
+ * and then overridden.
+ */
+export declare function carriesNoScore(selectedOutcome: string | undefined): boolean;
+/**
+ * Unanswered (`undefined`), a side (`1` | `2`), or explicitly neither.
+ */
+export type WinnerSelection = 1 | 2 | typeof NEITHER_SIDE | undefined;
+/** The double-exit statuses themselves, as opposed to the endings that produce them. */
+export declare const DOUBLE_EXIT_STATUSES: Set<string>;
+/**
+ * Whether this status IS a double exit — no side advances.
+ *
+ * Distinct from `supportsNeitherSide`, which asks whether an *ending* can become one. Use this
+ * where a status arrives already resolved, as it does from the inline popover.
+ */
+export declare function isDoubleExitStatus(matchUpStatus: string | undefined): boolean;
+/**
+ * The winner implied by a per-side exit control, where clicking a side's pill means THAT side is the
+ * one exiting and the other therefore wins.
+ *
+ * Returns `undefined` for a double exit (nobody advances) and for the non-directing statuses —
+ * SUSPENDED, CANCELLED, ABANDONED — which resolve nothing. The inline popover previously listed the
+ * double exits among the statuses that "produce a winner", so had one ever been selectable it would
+ * have stamped a winningSide on an outcome that must carry none.
+ */
+export declare function winnerFromExitingSide(matchUpStatus: string | undefined, exitingSideNumber?: number): number | undefined;
+/**
+ * Whether "Neither side" is a legitimate answer for this irregular ending.
+ */
+export declare function supportsNeitherSide(selectedOutcome: string | undefined): boolean;
+/**
+ * Message shown beside a double-exit selection. A double exit is not a scoring detail — it advances
+ * nobody and propagates a walkover into the next round — so the modal says what it will do before it
+ * is submitted rather than after.
+ */
+export declare function doubleExitWarning(selectedOutcome: string | undefined): string;
+export type IrregularEndingResolution = {
+    /** The status to submit. `undefined` while the selection is incomplete. */
+    matchUpStatus?: string;
+    /** Present only when a side was named. A double exit deliberately carries none. */
+    winningSide?: number;
+    /** Whether this resolution may be submitted. */
+    isValid: boolean;
+    /** True when the operator still owes a winner answer — the fail-closed state. */
+    awaitingWinner: boolean;
+    /** True when the resolution is a double exit, so callers can warn before it is submitted. */
+    isDoubleExit: boolean;
+};
+/**
+ * Resolve an irregular ending plus a winner selection into the status to submit.
+ *
+ * `COMPLETED` is not an irregular ending — callers keep their own completion handling and this
+ * returns an inert resolution for it.
+ */
+export declare function resolveIrregularEnding(params: {
+    selectedOutcome: string | undefined;
+    winnerSelection: WinnerSelection;
+}): IrregularEndingResolution;
+/**
+ * Apply a resolution onto a validation object in place, the shape the approaches already pass to
+ * `onScoreChange`.
+ *
+ * It also clears any `error` the score validator left behind, and the two cases that reach here are
+ * worth separating because only one of them is legitimate:
+ *
+ * - **RETIRED / DEFAULTED with a partial score.** The validator correctly reports "this is not a
+ *   completed match"; the ending is what makes it a valid result anyway. Clearing the error is the
+ *   right call — the validator answered a question that is no longer the one being asked.
+ * - **A walkover.** There is no score to validate, so the validator should never have run. Callers
+ *   must check `carriesNoScore()` and skip validation entirely; the clear here is a backstop, not
+ *   the fix. A walkover that reported `isValid: true` beside
+ *   `error: 'At least one set is required'` was the symptom of exactly that missing check.
+ */
+export declare function applyIrregularEndingToValidation(validation: any, selectedOutcome: string | undefined, winnerSelection: WinnerSelection): IrregularEndingResolution;

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

@@ -0,0 +1,62 @@
+/**
+ * Reading a scoring policy's `matchUpStatusCodes` vocabulary.
+ *
+ * The policy refines a matchUpStatus with caller-defined codes — a retirement becomes "Ret [inj]",
+ * a default becomes "Def [dq]". The modal renders them; it never invents them. If a tournament's
+ * policy carries no codes for the chosen status, there is nothing to show and no control is drawn.
+ * That is the designed state, not a degraded one: CA, 2026-09-20 — TMX ships no built-in default,
+ * so the reason field exists exactly where a governing body's vocabulary applies and nowhere else.
+ *
+ * No DOM, no side effects.
+ */
+/**
+ * One entry of a policy's code group, as the factory's fixtures ship it.
+ *
+ * CA settled the canonical shape on 2026-09-19: the OBJECT form is authoritative, because a bare
+ * string cannot carry the display text the picker exists to render.
+ */
+export type StatusCodeEntry = {
+    matchUpStatusCode: string;
+    matchUpStatusCodeDisplay?: string;
+    label?: string;
+    description?: string;
+};
+/** A policy's groups, keyed by the matchUpStatus each refines. */
+export type StatusCodeGroups = Record<string, StatusCodeEntry[]>;
+/**
+ * The group key a status reads its codes from.
+ *
+ * A double exit has no group of its own — the policy files "Wo/Wo" inside WALKOVER and "Def/Def"
+ * inside DEFAULTED, because they are walkovers and defaults. Mapping them here is what keeps the
+ * double-exit choice and the code list from becoming two controls that can disagree.
+ */
+export declare function groupKeyForStatus(matchUpStatus: string | undefined): string | undefined;
+/**
+ * Normalise one element of a code group, or of a matchUp's `matchUpStatusCodes`, to its code string.
+ *
+ * Three shapes are legitimate and all three occur. `matchUpStatusCodes` on a matchUp is an `any[]`
+ * shared by three tenants (policy codes, propagation provenance, and `{ code }` wrappers), and
+ * `updateMatchUpStatusCodes` in the factory rewraps every string element as `{ code }` — so a code
+ * written as `'RJ'` reads back as `{ code: 'RJ' }` once propagation has touched the matchUp. A
+ * reader that assumes a string is wrong, and it is wrong only sometimes, which is worse.
+ *
+ * Returns `undefined` for a provenance element, which carries no code at all.
+ */
+export declare function normalizeStatusCode(entry: unknown): string | undefined;
+/**
+ * The codes a policy offers for this status, or an empty list when it offers none.
+ *
+ * Entries without a `matchUpStatusCode` are dropped rather than rendered as a blank option — an
+ * unpickable row in a picker is worse than a shorter picker.
+ */
+export declare function codesForStatus(groups: StatusCodeGroups | undefined, matchUpStatus: string | undefined): StatusCodeEntry[];
+/**
+ * What to show for a code: the policy's display form, falling back to its label, then to the code.
+ *
+ * The three fields are authored per code and mean different things — `matchUpStatusCodeDisplay` is
+ * the terse form an operator recognises ("Ret [inj]"), `label` the prose one ("Injury"). Never
+ * synthesise a display from the code: a policy that authored none is saying the code IS the label.
+ */
+export declare function statusCodeDisplay(entry: StatusCodeEntry): string;
+/** The secondary line beside the display form, when the policy authored one that adds something. */
+export declare function statusCodeSubtext(entry: StatusCodeEntry): string | undefined;

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

@@ -0,0 +1,13 @@
+import { StatusCodeGroups } from './logic/statusCodes';
+import { ScoringModalLabels } from './types';
+export type StatusCodePickerHandle = {
+    element: HTMLElement;
+    /** Re-render for a new status. Returns the code still selected, if any. */
+    update: (matchUpStatus: string | undefined) => string | undefined;
+    /** The chosen code, or undefined when none is chosen or none is offered. */
+    getSelectedCode: () => string | undefined;
+};
+export declare function buildStatusCodePicker(params: {
+    groups?: StatusCodeGroups;
+    labels?: ScoringModalLabels;
+}): StatusCodePickerHandle;

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

@@ -1,6 +1,4 @@
-/**
- * Type definitions for scoring modal V2
- */
+import { StatusCodeGroups } from './logic/statusCodes';
 export type SetScore = {
     setNumber?: number;
     side1Score?: number;
@@ -17,6 +15,8 @@ export type ScoreOutcome = {
     scoreObject?: any;
     winningSide?: number;
     matchUpStatus?: string;
+    /** Policy reason codes chosen for this outcome, as code strings — e.g. `['RJ']`. */
+    matchUpStatusCodes?: string[];
     error?: string;
     matchUpFormat?: string;
     score?: string;
@@ -30,13 +30,19 @@ export type ScoringModalLabels = {
     formatEditTitle?: string;
     irregularEnding?: string;
     winner?: string;
+    neitherSide?: string;
     retired?: string;
+    abandoned?: string;
+    cancelled?: string;
+    incomplete?: string;
     walkover?: string;
     defaulted?: string;
     validScore?: string;
     scoreIncomplete?: string;
     invalidScore?: string;
     scoreTips?: string;
+    reasonCode?: string;
+    noReasonCode?: string;
     setScores?: string;
     tiebreaks?: string;
     matchTiebreaks?: string;
@@ -50,6 +56,13 @@ export type ScoringModalParams = {
     callback: (outcome: any) => void;
     onClose?: () => void;
     labels?: ScoringModalLabels;
+    /**
+     * The scoring policy's `matchUpStatusCodes` groups, resolved by the CALLER — components never
+     * reaches into factory fixtures or the engine. Omit it (or pass groups with no entries for the
+     * chosen status) and no reason control is drawn, which is the designed state for a tournament
+     * with no governing-body policy attached.
+     */
+    matchUpStatusCodes?: StatusCodeGroups;
 };
 export type ScoreChangeHandler = (outcome: ScoreOutcome) => void;
 export type RenderScoreEntryParams = {