courthive-components 6.1.0 → 6.2.1

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

@@ -1,4 +1,6 @@
 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.
@@ -19,26 +21,99 @@ export type ScoreColumn = {
     /** 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;
-    /** The score as it currently stands, for the result band. */
-    scoreString?: () => string | undefined;
-    /** Whether that score is a finished result. The region's judgement, never the card's. */
-    isComplete?: () => boolean;
-    /** The winner the score implies, when no ending overrides it. */
-    winningSide?: () => SideNumber | undefined;
+    /**
+     * 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.
      *
-     * Used ONLY when the operator has selected no ending. See `resolveReportedEnding` for why that
-     * precedence and not the other.
+     * 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: [{
@@ -54,30 +129,63 @@ export type ScoreEntryCardParams = {
     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: {
-        matchUpStatus?: string;
-        winningSide?: number;
-        reasonCode?: string;
-    }) => void;
+    onSubmit?: (outcome: ScoreEntryOutcome) => void;
     onClose?: () => void;
 };
-/** A card instance: its element, plus the handle the host needs to react to score-region changes. */
 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;
-    /** The current ending state, for a host that needs to inspect it. */
+    /**
+     * 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;

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

@@ -0,0 +1,94 @@
+import { SetScore } from './types';
+import { ScoreEntryCard, ScoreEntryCardParams, ScoreEntryOutcome } from './scoreEntryCard';
+/** The three entry approaches. The key is what `onSelectApproach` reports and what a host persists. */
+export type ScoreEntryApproach = 'dynamicSets' | 'freeScore' | 'dialPad';
+export type ScoreEntryDialogParams = Omit<ScoreEntryCardParams, 'region' | 'approachLabel' | 'approaches' | 'onSelectApproach' | 'onSwitchApproach' | 'onEditFormat' | 'onClose' | 'onSubmit'> & {
+    /**
+     * Called with the outcome, then the dialog closes.
+     *
+     * `sets` is added to what the card reports, because the dialog knows its regions carry them and a
+     * host saving to the factory needs the structured sets rather than only the formatted string.
+     */
+    onSubmit?: (outcome: ScoreEntryOutcome & {
+        sets: SetScore[];
+    }) => void;
+    /** Which approach opens. Defaults to Dynamic Sets. */
+    approach?: ScoreEntryApproach;
+    /** Which approaches the switcher offers. Defaults to all three; a single entry hides the menu. */
+    approaches?: ScoreEntryApproach[];
+    /** Sets already recorded, e.g. from a saved matchUp. Ignored when `matchUp` carries a score. */
+    sets?: SetScore[];
+    /**
+     * A matchUp whose outcome is being REOPENED.
+     *
+     * Everything a recorded outcome needs comes from here: the sets, the format, the ending, and the
+     * reason code — CA, 2026-09-28: *"we need to be able to open existing outcomes!"* Anything passed
+     * explicitly wins, so a host can override one part without unpacking the rest.
+     *
+     * `sides` stays separate rather than being read off `matchUp.sides`, because the card wants display
+     * names and a matchUp carries participants; that mapping belongs to the host, which already has it.
+     */
+    matchUp?: {
+        matchUpFormat?: string;
+        matchUpStatus?: string;
+        winningSide?: number;
+        score?: {
+            sets?: SetScore[];
+        };
+        sideStatusCodes?: Record<number, string>;
+        matchUpStatusCode?: string;
+        matchUpStatusCodes?: unknown[];
+    };
+    /** Called with the chosen approach whenever it changes, so a host can remember the preference. */
+    onApproachChange?: (approach: ScoreEntryApproach) => void;
+    /** Called with a format chosen in the picker. Omit and the format chip stays inert text. */
+    onFormatChange?: (matchUpFormat: string) => void;
+    /**
+     * Called when a format change DISCARDS part of the score, with what was lost and why.
+     *
+     * Only when something was actually discarded — a change that costs the operator nothing says
+     * nothing. `discarded` carries the sets themselves rather than a count, because a host that means to
+     * tell the operator has to quote them in their own numbers, and `reason` is the factory validator's
+     * own words about the first casualty.
+     */
+    onScoreDiscarded?: (discarded: {
+        sets: SetScore[];
+        discarded: SetScore[];
+        reason?: string;
+        matchUpFormat: string;
+    }) => void;
+    /** Called when the dialog closes, by `[X]`, by a footer button, or by `close()`. */
+    onClose?: () => void;
+    /**
+     * Whether to focus the first entry field on open. Defaults to true.
+     *
+     * `false` for a host that opens the dialog as a side effect of something else, where stealing focus
+     * would interrupt what the operator was actually doing.
+     */
+    autoFocus?: boolean;
+    /** Overrides cModal's config. `maxWidth`, `clickAway` and `padding` have deliberate defaults. */
+    modalConfig?: Record<string, any>;
+    /**
+     * The format picker. Defaults to this package's `getMatchUpFormatModal`.
+     *
+     * Injectable because a unit test has no business opening the real picker's modal — it is a second
+     * dialog with its own state — and because a host may have its own.
+     */
+    openFormatPicker?: (params: {
+        existingMatchUpFormat: string;
+        callback: (matchUpFormat: string) => void;
+    }) => void;
+};
+export type ScoreEntryDialog = {
+    /** The card, for a host that needs to read the state or drive it. */
+    card: ScoreEntryCard;
+    /** The approach currently shown. */
+    approach: () => ScoreEntryApproach;
+    /** Switch approach, carrying the typed score across. */
+    setApproach: (approach: ScoreEntryApproach) => void;
+    /** Change the scoring format, rebuilding the region under it. */
+    setMatchUpFormat: (matchUpFormat: string) => void;
+    /** Close the dialog. Runs `onClose` exactly once, however the close was triggered. */
+    close: () => void;
+};
+export declare function openScoreEntryDialog(params: ScoreEntryDialogParams): ScoreEntryDialog;