courthive-components 3.15.1 → 4.0.0

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

@@ -1,5 +1,6 @@
 export { InlineScoringManager } from './inlineScoringManager';
 export { renderInlineMatchUp } from './renderInlineMatchUp';
+export { isScorable, sideParticipantName } from './isScorable';
 export { engineToMatchUp } from './engineToMatchUp';
 export { createInlineScoringFooter } from './inlineScoringFooter';
 export type { InlineScoringMode, InlineScoringConfig, InlineScoringCallbacks, InlineScoringEngineState } from './inlineScoringTypes';

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

@@ -0,0 +1,37 @@
+import { MatchUp } from '../../types';
+/**
+ * The name a side's participant is known by, or `undefined` when there isn't one.
+ *
+ * Returns `undefined` rather than a placeholder ON PURPOSE. `"Side 1"` reads like a legitimate name
+ * everywhere it is subsequently displayed or persisted, so a fallback here is indistinguishable from
+ * a real record. A refusal you can see beats a plausible value you cannot.
+ */
+export declare function sideParticipantName(matchUp: MatchUp | undefined, sideNumber: number): string | undefined;
+/**
+ * May this matchUp be offered for interactive scoring at all?
+ *
+ * FAIL CLOSED. A scoring affordance leads to stored results, and the two things that make a stored
+ * result trustworthy cannot be reconstructed afterwards:
+ *
+ * - **`matchUpFormat`** decides how a score is *interpreted*. It is determined by the tournamentRecord
+ *   and delivered by the factory; there is no correct way to guess it. A score kept against an invented
+ *   format is not slightly wrong, it is uninterpretable.
+ * - **Named participants.** A result attributed to "Side 1" is indistinguishable from a genuine one at
+ *   every point downstream.
+ *
+ * So a matchUp missing either is not scored with a substitute — it is not offered for scoring. That is
+ * the only arrangement in which the substitute cannot exist.
+ *
+ * This lives in the LIBRARY rather than in each app deliberately. Both consumers had grown their own
+ * weaker version of this check (participant existence, no name check, no format check), and
+ * `renderInlineMatchUp` — the single place a scoring affordance is minted — defaulted the format for
+ * everyone. A guard beside the thing it guards is structural; a guard in each app is a rule each app
+ * has to remember.
+ *
+ * Costs nothing in practice: across a real production tournament (three events, 211 matchUps) every
+ * matchUp carried a `matchUpFormat`, and the set passing this gate was exactly the set with two
+ * hydrated, named sides.
+ *
+ * @param matchUpFormat optional override, matching `renderInlineMatchUp`'s parameter of the same name.
+ */
+export declare function isScorable(matchUp: MatchUp | undefined, matchUpFormat?: string): boolean;

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

@@ -21,7 +21,9 @@ interface RenderInlineMatchUpParams {
  * The footer buttons (Undo/Redo/Clear/Submit) are rendered by `renderMatchUp` itself,
  * driven by the inlineScoring config state and eventHandlers passed down.
  *
- * Returns a container element that re-renders itself after each scoring action.
+ * Returns a container element that re-renders itself after each scoring action, or **`null`** when the
+ * matchUp must not be offered for scoring — see `isScorable`. Callers must handle the null rather than
+ * replacing a rendered cell with it; the return type is what forces them to.
  */
-export declare function renderInlineMatchUp(params: RenderInlineMatchUpParams): HTMLElement;
+export declare function renderInlineMatchUp(params: RenderInlineMatchUpParams): HTMLElement | null;
 export {};

package/dist/components/pressureChart/buildPressureSeries.d.ts

@@ -0,0 +1,21 @@
+import { ProjectedPressureResult, PressureSeries } from './types';
+import { GetProjectedPressureParams } from './getProjectedPressure';
+export type BuildPressureSeriesParams = GetProjectedPressureParams;
+export type PressureSeriesResult = {
+    series: PressureSeries[];
+    projection: ProjectedPressureResult;
+    /** The rating scale the values were read from, for axis labelling. */
+    scaleName?: string;
+    unratedCount: number;
+};
+export declare function buildPressureSeries(params: BuildPressureSeriesParams): PressureSeriesResult;
+/**
+ * Participants ordered hardest SLOT first — the ranked "path difficulty" view,
+ * and the entry point of the all-players surface.
+ *
+ * Sorts on `slotDifficulty`, not `pathDifficulty`: the reach-weighted figure
+ * discounts the late rounds a weak player is unlikely to reach, so ranking on it
+ * would report the toughest draws in the field as the easiest. Unrated
+ * participants sort last rather than being dropped, so the field size stays honest.
+ */
+export declare function byPathDifficulty(series: PressureSeries[]): PressureSeries[];

package/dist/components/pressureChart/drawGraph.d.ts

@@ -0,0 +1,41 @@
+import { PressureUnsupportedReason } from './types';
+export declare const BYE_STATUS = "BYE";
+export type GraphSide = {
+    participantId?: string;
+    participant?: any;
+    drawPosition?: number;
+    bye: boolean;
+};
+export type GraphMatchUp = {
+    matchUpId?: string;
+    roundNumber: number;
+    roundPosition: number;
+    sides: [GraphSide, GraphSide];
+    winningSide?: number;
+    matchUpStatus?: string;
+    raw: any;
+};
+export type EliminationGraph = {
+    roundNumbers: number[];
+    /** roundNumber -> roundPosition -> matchUp */
+    byRound: Map<number, Map<number, GraphMatchUp>>;
+    firstRound: number;
+};
+/**
+ * Build the graph, or say why it could not be built.
+ *
+ * Rejects anything that is not a clean halving tree — round-robin containers,
+ * ad-hoc structures, and fed/consolation shapes whose round sizes do not halve.
+ * Refusing is deliberate: a wrong tree would produce a plausible-looking
+ * projection with silently wrong opponents, which is worse than no chart.
+ */
+export declare function buildEliminationGraph(matchUps: any[]): {
+    graph?: EliminationGraph;
+    unsupported?: PressureUnsupportedReason;
+};
+/** The two feeder positions of `(roundNumber, roundPosition)` in the previous round. */
+export declare function feederPositions(roundPosition: number): [number, number];
+/** The position a winner of `roundPosition` advances into, in the next round. */
+export declare function advancingPosition(roundPosition: number): number;
+/** True when the matchUp is a bye for whichever side is present. */
+export declare function isByeMatchUp(matchUp: GraphMatchUp): boolean;

package/dist/components/pressureChart/getActualPressure.d.ts

@@ -0,0 +1,14 @@
+import { ParticipantActualPressure } from './types';
+export type GetActualPressureParams = {
+    matchUps: any[];
+    matchUpType?: string;
+    scaleName?: string;
+};
+/**
+ * Walk every matchUp a participant appears in and describe what they met.
+ *
+ * Only matchUps whose sides are hydrated contribute — an unplayed later round
+ * has empty sides, so it simply produces no entry. That is the correct
+ * behaviour: this series exists to show what *happened*.
+ */
+export declare function getActualPressure(params: GetActualPressureParams): ParticipantActualPressure[];

package/dist/components/pressureChart/getProjectedPressure.d.ts

@@ -0,0 +1,23 @@
+import { WinProbabilityModel } from './winProbability';
+import { ProjectedPressureResult } from './types';
+/** Opponents below this arrival probability are excluded from the displayed range. */
+export declare const DEFAULT_RANGE_THRESHOLD = 0.01;
+export type GetProjectedPressureParams = {
+    /** Structure matchUps, hydrated with sides + participants. */
+    matchUps: any[];
+    /** SINGLES (default) or DOUBLES — selects which ratings block to read. */
+    matchUpType?: string;
+    /** Prefer this scale when a participant carries several. */
+    scaleName?: string;
+    /** Pairwise model knobs; see `winProbability`. */
+    model?: WinProbabilityModel;
+    /**
+     * When true, a played matchUp collapses to its actual winner, so the
+     * projection reads "from here". Default **false** — the untouched projection
+     * is what the draw said at the outset, which is the comparison the chart makes.
+     */
+    respectResults?: boolean;
+    /** Arrival-probability floor for inclusion in `opponentEloRange`. */
+    rangeThreshold?: number;
+};
+export declare function getProjectedPressure(params: GetProjectedPressureParams): ProjectedPressureResult;

package/dist/components/pressureChart/index.d.ts

@@ -0,0 +1,18 @@
+export { buildPressureSmallMultiples, sharedYDomain } from './pressureSmallMultiples';
+export { buildPressureSeries, byPathDifficulty } from './buildPressureSeries';
+export { buildPressureChart, resolveYDomain, defaultRoundLabel } from './pressureChart';
+export { getProjectedPressure, DEFAULT_RANGE_THRESHOLD } from './getProjectedPressure';
+export { eloWinProbability, winProbability, DEFAULT_ELO_DIVISOR } from './winProbability';
+export { resolveParticipantRating, ratingToElo, convertRange } from './ratingScale';
+export { buildPathDifficultyBar } from './pathDifficultyBar';
+export { getActualPressure } from './getActualPressure';
+export { buildPressureTable } from './pressureTable';
+export { PRESSURE_UNSUPPORTED } from './types';
+export type { PressureSmallMultiplesOptions, PressureSmallMultiplesInstance } from './pressureSmallMultiples';
+export type { PathDifficultyBarOptions, PathDifficultyBarInstance } from './pathDifficultyBar';
+export type { BuildPressureSeriesParams, PressureSeriesResult } from './buildPressureSeries';
+export type { PressureChartOptions, PressureChartInstance } from './pressureChart';
+export type { GetProjectedPressureParams } from './getProjectedPressure';
+export type { GetActualPressureParams } from './getActualPressure';
+export type { WinProbabilityModel } from './winProbability';
+export type { ParticipantPressureProjection, ParticipantActualPressure, ProjectedPressureResult, PressureUnsupportedReason, ProjectedRoundPressure, ActualRoundPressure, PressureSeriesPoint, PossibleOpponent, ResolvedRating, PressureSeries } from './types';

package/dist/components/pressureChart/pathDifficultyBar.d.ts

@@ -0,0 +1,17 @@
+import { PressureSeries } from './types';
+export type PathDifficultyBarOptions = {
+    width?: number;
+    rowHeight?: number;
+    labelWidth?: number;
+    /** Cap the rows rendered. When set, the count dropped is stated in the caption. */
+    limit?: number;
+    /** Overlay the difficulty actually faced so far, where a participant has played. */
+    showActual?: boolean;
+    onSelect?: (series: PressureSeries) => void;
+    emptyMessage?: string;
+};
+export type PathDifficultyBarInstance = {
+    element: HTMLElement;
+    update: (series: PressureSeries[], options?: PathDifficultyBarOptions) => void;
+};
+export declare function buildPathDifficultyBar(container: HTMLElement, series?: PressureSeries[], options?: PathDifficultyBarOptions): PathDifficultyBarInstance;

package/dist/components/pressureChart/pressureChart.d.ts

@@ -0,0 +1,40 @@
+import { PressureSeries, PressureSeriesPoint } from './types';
+export type PressureChartOptions = {
+    width?: number;
+    height?: number;
+    margin?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Compact mode for the small-multiples grid: no labels, no legend, thin marks. */
+    spark?: boolean;
+    /** Fix the y domain across a set of charts so small multiples are comparable. */
+    yDomain?: [number, number];
+    /** Label for the rating scale, e.g. 'WTN'. Shown on the axis. */
+    scaleName?: string;
+    showLegend?: boolean;
+    ariaLabel?: string;
+    roundLabels?: (roundNumber: number, index: number, total: number) => string;
+    emptyMessage?: string;
+};
+export type PressureChartInstance = {
+    element: HTMLElement;
+    update: (series: PressureSeries | undefined, options?: PressureChartOptions) => void;
+    destroy: () => void;
+};
+/** QF / SF / F for the last three rounds, R1.. before that — matches the round-nav convention. */
+export declare function defaultRoundLabel(_roundNumber: number, index: number, total: number): string;
+/** Symmetric domain around zero so "playing up" and "playing down" read equally. */
+export declare function resolveYDomain(points: PressureSeriesPoint[], override?: [number, number]): [number, number];
+/** Round a half-extent down to a readable 1 / 2 / 5 x 10^n step. */
+export declare function niceStep(extent: number): number;
+/**
+ * Build (or rebuild) the chart into a container.
+ *
+ * Returns a handle so a consumer can re-render on a live update without
+ * re-querying the DOM. `update(undefined)` renders the empty state — an unrated
+ * field is a legitimate outcome, not an error.
+ */
+export declare function buildPressureChart(container: HTMLElement, series?: PressureSeries, options?: PressureChartOptions): PressureChartInstance;

package/dist/components/pressureChart/pressureSmallMultiples.d.ts

@@ -0,0 +1,17 @@
+import { PressureSeries } from './types';
+export type PressureSmallMultiplesOptions = {
+    cellWidth?: number;
+    cellHeight?: number;
+    /** Cap the cells rendered; the number dropped is stated in the caption. */
+    limit?: number;
+    scaleName?: string;
+    onSelect?: (series: PressureSeries) => void;
+    emptyMessage?: string;
+};
+export type PressureSmallMultiplesInstance = {
+    element: HTMLElement;
+    update: (series: PressureSeries[], options?: PressureSmallMultiplesOptions) => void;
+};
+/** One y domain across every cell, so the grid can be read as a comparison. */
+export declare function sharedYDomain(series: PressureSeries[]): [number, number];
+export declare function buildPressureSmallMultiples(container: HTMLElement, series?: PressureSeries[], options?: PressureSmallMultiplesOptions): PressureSmallMultiplesInstance;

package/dist/components/pressureChart/pressureTable.d.ts

@@ -0,0 +1,2 @@
+import { PressureSeries } from './types';
+export declare function buildPressureTable(container: HTMLElement, series: PressureSeries): HTMLTableElement;

package/dist/components/pressureChart/ratingScale.d.ts

@@ -0,0 +1,44 @@
+import { ResolvedRating } from './types';
+/** Linear map of a value from one range onto another. Mirrors factory `convertRange`. */
+export declare function convertRange({ value, sourceRange, targetRange }: {
+    value: number;
+    sourceRange?: number[];
+    targetRange?: number[];
+}): number;
+/**
+ * Convert a value on `scaleName` to its ELO equivalent.
+ *
+ * Scales where a LOWER number is better (WTN, declared `range: [40, 1]`) are
+ * declared high-to-low; the factory detects that as `range[0] > range[1]` and
+ * reflects the value before mapping, which is reproduced here.
+ */
+export declare function ratingToElo({ scaleName, value }: {
+    scaleName?: string;
+    value?: number;
+}): number | undefined;
+/**
+ * Resolve a participant's rating onto the common scale.
+ *
+ * Expects the `participant.ratings` shape produced with
+ * `participantsProfile: { withScaleValues: true }` — the hydration CFS already
+ * requests in `getEventData`:
+ *
+ * ```
+ * ratings: { SINGLES: [{ scaleName: 'WTN', scaleValue: { wtnRating: 4.13 } }] }
+ * ```
+ *
+ * **Without `withScaleValues` the `ratings` key is present but empty** and the
+ * value lives in `participant.timeItems` instead; this returns `null` in that
+ * case rather than inventing a default. A blank chart is the correct outcome for
+ * an unrated field — see `PRESSURE_UNSUPPORTED.NO_RATINGS`.
+ */
+export declare function resolveParticipantRating({ participant, matchUpType, preferredScaleName }: {
+    participant?: any;
+    matchUpType?: string;
+    preferredScaleName?: string;
+}): ResolvedRating | null;
+/**
+ * The scale name that appears most often across a set of resolved ratings.
+ * Reported so a caller can label the axis honestly when a field is mixed-scale.
+ */
+export declare function dominantScaleName(ratings: (ResolvedRating | null)[]): string | undefined;

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

@@ -0,0 +1,153 @@
+import { CompetitivenessBucket } from '../competitivenessBar/types';
+/** Why a projection could not be produced. Never guess — say which. */
+export declare const PRESSURE_UNSUPPORTED: {
+    readonly NO_MATCHUPS: "NO_MATCHUPS";
+    readonly NOT_ELIMINATION: "NOT_ELIMINATION";
+    readonly NO_RATINGS: "NO_RATINGS";
+};
+export type PressureUnsupportedReason = (typeof PRESSURE_UNSUPPORTED)[keyof typeof PRESSURE_UNSUPPORTED];
+/** A rating resolved onto the common (ELO-equivalent) scale. */
+export type ResolvedRating = {
+    /** ELO-equivalent value, produced by the same range conversion the factory uses. */
+    elo: number;
+    /** The scale the value was read from, e.g. 'WTN' / 'UTR' / 'ELO'. */
+    scaleName: string;
+    /** The raw value as published on that scale, for display. */
+    sourceValue: number;
+};
+/** A participant who could arrive in the opponent slot, with the probability they do. */
+export type PossibleOpponent = {
+    participantId: string;
+    participantName?: string;
+    probability: number;
+    elo: number | null;
+};
+/** One round of a participant's projected path. */
+export type ProjectedRoundPressure = {
+    roundNumber: number;
+    /** Probability the participant plays this round at all. Round 1 is 1. */
+    reachProbability: number;
+    /**
+     * Probability-weighted mean opponent rating (ELO-equivalent) over the
+     * participants who could arrive from the sibling sub-bracket. `null` when no
+     * opponent in that sub-bracket carries a rating.
+     */
+    expectedOpponentElo: number | null;
+    /** [min, max] over opponents whose arrival probability clears the threshold. */
+    opponentEloRange: [number, number] | null;
+    /** expectedOpponentElo - own rating. Positive = projected to play up. */
+    expectedSignedDelta: number | null;
+    /** How many distinct participants could arrive from the sibling sub-bracket. */
+    possibleOpponentCount: number;
+    /**
+     * Who could arrive, most-likely first. Drives the hover layer ("possible
+     * opponents"), and lets a test assert opponent *identity* rather than only a
+     * range — a range can be right by coincidence when sub-brackets are similar.
+     */
+    possibleOpponents: PossibleOpponent[];
+    /** True once exactly one opponent is possible — i.e. the uncertainty has burned off. */
+    resolved: boolean;
+    /** True when this round is a BYE for the participant: no opponent, no pressure. */
+    bye: boolean;
+};
+/** A participant's full projection across the structure. */
+export type ParticipantPressureProjection = {
+    participantId: string;
+    participantName?: string;
+    drawPosition?: number;
+    /** The participant's own rating on the common scale, or `null` if unrated. */
+    rating: ResolvedRating | null;
+    rounds: ProjectedRoundPressure[];
+    /**
+     * **Experienced** difficulty: the reach-weighted mean of `expectedSignedDelta`.
+     * Answers "how hard are the matches this participant should expect to actually
+     * play?" — which is legitimately *lower* for a weak player, because the hard
+     * late rounds are discounted by their small chance of getting there.
+     *
+     * Do NOT rank a field on this. It systematically flatters weak players and so
+     * hides exactly the draw imbalance the ranked view exists to expose. Use
+     * `slotDifficulty` for that.
+     */
+    pathDifficulty: number | null;
+    /**
+     * **Slot** difficulty: the unweighted mean of `expectedSignedDelta` across all
+     * rounds carrying a rated opponent — i.e. how hard this bracket slot is if you
+     * had to walk the whole thing, independent of the occupant's own survival odds.
+     *
+     * This is the number the ranked "path difficulty" view sorts on.
+     *
+     * **Known limitation, measured on production data.** Because this is
+     * `mean(opponentElo) - ownElo` and the opponent mean varies far less across a
+     * field than the players' own ratings do, it is dominated by the participant's
+     * own rating: on the 2019 ITA DI Texas Men's Regional (99 rated entrants)
+     * Spearman rank correlation against own rating was **-0.986**. So ranking on it
+     * is close to ranking by rating inverted, and it does NOT by itself expose draw
+     * imbalance. Real draw-position signal is present but small — two entrants at
+     * UTR 10.42 and 10.55 in that draw differ by ~110 ELO of slot difficulty — and
+     * surfacing it needs the opponent-strength component on its own, or a residual
+     * against what a player of that rating typically faces. Not yet built.
+     */
+    slotDifficulty: number | null;
+    /** Sum of `reachProbability` across rounds — the expected number of matches played. */
+    expectedMatchesPlayed: number;
+};
+export type ProjectedPressureResult = {
+    projections: ParticipantPressureProjection[];
+    /** Present only when nothing could be produced. */
+    unsupported?: PressureUnsupportedReason;
+    /** The scale ratings were read from, when a single scale dominated. */
+    scaleName?: string;
+    /** Count of entrants with no usable rating — surfaced, never silently defaulted. */
+    unratedCount: number;
+};
+/** One round of a participant's realised path. */
+export type ActualRoundPressure = {
+    roundNumber: number;
+    matchUpId?: string;
+    opponentParticipantId?: string;
+    opponentParticipantName?: string;
+    opponentElo: number | null;
+    /** opponentElo - own rating. Positive = played up. */
+    signedDelta: number | null;
+    /** How close the scoreline was. Undefined until the matchUp has a winner. */
+    competitiveness?: CompetitivenessBucket;
+    won?: boolean;
+    bye: boolean;
+};
+export type ParticipantActualPressure = {
+    participantId: string;
+    rating: ResolvedRating | null;
+    rounds: ActualRoundPressure[];
+    /** Mean `signedDelta` across played rounds carrying a rated opponent. */
+    facedDifficulty: number | null;
+    matchesPlayed: number;
+};
+/** Chart-ready merge of the projected and actual series for one participant. */
+export type PressureSeries = {
+    participantId: string;
+    participantName?: string;
+    drawPosition?: number;
+    rating: ResolvedRating | null;
+    /** Reach-weighted expected delta. Do not rank on this — see the projection type. */
+    pathDifficulty: number | null;
+    /** Unweighted slot difficulty. This is what the ranked view sorts on. */
+    slotDifficulty: number | null;
+    facedDifficulty: number | null;
+    points: PressureSeriesPoint[];
+};
+export type PressureSeriesPoint = {
+    roundNumber: number;
+    /** Projected band, in signed-delta space. `null` where the round carries no rated opponent. */
+    projected: {
+        expected: number | null;
+        low: number | null;
+        high: number | null;
+    };
+    reachProbability: number;
+    /** Realised signed delta, present only once the round has been played. */
+    actual: number | null;
+    competitiveness?: CompetitivenessBucket;
+    won?: boolean;
+    bye: boolean;
+    resolved: boolean;
+};

package/dist/components/pressureChart/winProbability.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pairwise win probability on the common (ELO-equivalent) scale.
+ *
+ * The standard ELO logistic:
+ *
+ *     P(A beats B) = 1 / (1 + 10 ^ ((eloB - eloA) / divisor))
+ *
+ * `divisor` is a policy knob rather than a constant so it can be calibrated per
+ * federation / discipline. 400 is the ELO convention and the default here.
+ *
+ * This is an ASSUMPTION until measured. The factory ships
+ * `getPredictiveAccuracy` for exactly this purpose — it scores how well a rating
+ * scale predicts real outcomes over a corpus. Anything presented to a user as a
+ * likelihood should be calibrated against that first; this module only ever
+ * feeds *relative* opponent-strength expectations, which are far less sensitive
+ * to the divisor than a displayed percentage would be.
+ */
+export declare const DEFAULT_ELO_DIVISOR = 400;
+export type WinProbabilityModel = {
+    divisor?: number;
+};
+/** Probability that the `elo`-rated side beats the `opponentElo`-rated side. */
+export declare function eloWinProbability(elo: number, opponentElo: number, model?: WinProbabilityModel): number;
+/**
+ * Win probability where either side may be unrated. An unrated participant is
+ * treated as a coin flip against anyone — a deliberate, visible choice: it keeps
+ * a single unrated entrant from erasing the whole sub-bracket's projection,
+ * while `unratedCount` on the result reports how much of the field it applied to.
+ */
+export declare function winProbability(elo: number | null, opponentElo: number | null, model?: WinProbabilityModel): number;

package/dist/components/tournament-card/types.d.ts

@@ -24,6 +24,14 @@ export interface TierClassification {
 export interface TournamentEntryFee {
     amount: number;
     currencyCode?: string;
+    /**
+     * Whether `amount` is in the currency's smallest unit or in whole units.
+     *
+     * Optional here because a stored record written before the field existed still arrives without
+     * one — but a fee with no unit is NOT rendered as a number. See `feeFormatter`.
+     */
+    unit?: 'MINOR' | 'MAJOR';
+    eventId?: string;
     category?: string;
     eventType?: string;
 }