courthive-components 4.0.0 → 4.1.0

package/dist/components/pressureHorizon/drawOrderGame.d.ts

@@ -0,0 +1,34 @@
+import { DrawOrderGameState } from './drawOrderGameState';
+import { ProjectedPressureResult, PressureSeries } from '../pressureChart/types';
+import { DrawOrderScore } from './scoreDrawOrder';
+import { HorizonVariant } from './pressureHorizon';
+export type DrawOrderGameOptions = {
+    width?: number;
+    rowHeight?: number;
+    rowGap?: number;
+    columnGap?: number;
+    bands?: number;
+    /**
+     * `ribbon` is the gentler board: mirror pairs read as reflected curves, which is
+     * far easier to spot than comparing wall depths. `walls` is the hard mode.
+     */
+    variant?: HorizonVariant;
+    /** Enables the weighted fan on the ribbon. Carries no identities, so it cannot leak. */
+    projection?: ProjectedPressureResult;
+    seed?: number;
+    scaleName?: string;
+    /** Cap the field so a 128-draw stays a game rather than a chore. */
+    limit?: number;
+    roundLabels?: (roundNumber: number, index: number, total: number) => string;
+    onComplete?: (score: DrawOrderScore, state: DrawOrderGameState) => void;
+    emptyMessage?: string;
+};
+export type DrawOrderGameInstance = {
+    element: HTMLElement;
+    /** The current state — for a story or a host that wants to drive the board. */
+    getState: () => DrawOrderGameState;
+    reshuffle: (seed?: number) => void;
+    reveal: () => void;
+    destroy: () => void;
+};
+export declare function buildDrawOrderGame(container: HTMLElement, series?: PressureSeries[], options?: DrawOrderGameOptions): DrawOrderGameInstance;

package/dist/components/pressureHorizon/drawOrderGameState.d.ts

@@ -0,0 +1,35 @@
+import { DrawOrderScore } from './scoreDrawOrder';
+export type DrawOrderGameState = {
+    /** participantIds in true draw-position order — the answer key. */
+    actualOrder: string[];
+    /** participantIds in the player's current order. */
+    order: string[];
+    /** The seed that dealt this board; quoting it reproduces the puzzle exactly. */
+    seed: number;
+    /** False when the deal could not avoid leaving a row in its true slot. */
+    deranged: boolean;
+    revealed: boolean;
+    /** Null until `revealDrawOrder`. */
+    score: DrawOrderScore | null;
+    /** Reorder operations the player has made on this board. */
+    moves: number;
+};
+export declare function createDrawOrderGame({ actualOrder, seed }: {
+    actualOrder: string[];
+    seed: number;
+}): DrawOrderGameState;
+/**
+ * Lift the row at `from` and drop it at `to`, closing the gap behind it.
+ *
+ * An out-of-range index returns the state untouched rather than throwing: a
+ * pointer drag can legitimately end outside the list, and that is a no-op, not
+ * an error. A revealed board is frozen — the answer is already on screen, so a
+ * further move would produce a score that no longer describes what was guessed.
+ */
+export declare function moveSlot(state: DrawOrderGameState, from: number, to: number): DrawOrderGameState;
+/** Exchange two rows in place — what a keyboard nudge does. */
+export declare function swapSlots(state: DrawOrderGameState, a: number, b: number): DrawOrderGameState;
+/** Score the board and freeze it. Repeated calls are idempotent. */
+export declare function revealDrawOrder(state: DrawOrderGameState): DrawOrderGameState;
+/** Deal a fresh board from a new seed, keeping the same field. */
+export declare function reshuffleDrawOrder(state: DrawOrderGameState, seed: number): DrawOrderGameState;

package/dist/components/pressureHorizon/horizonBands.d.ts

@@ -0,0 +1,38 @@
+import { BuildHorizonRowsParams, HorizonRowsResult, HorizonSource, HorizonLayer } from './types';
+import { PressureSeriesPoint, PressureSeries } from '../pressureChart/types';
+/** Four steps per arm. More than four stops reading as ordered at row heights this small. */
+export declare const DEFAULT_BANDS = 4;
+/**
+ * Floor on the domain, in ELO points. Without it a draw whose deltas are all tiny
+ * would autoscale until rounding noise filled the darkest band — the horizon
+ * equivalent of a truncated y-axis, and just as misleading.
+ */
+export declare const MIN_HORIZON_DOMAIN = 60;
+/** The value a cell paints, and whether it came from a played matchUp. */
+export declare function selectCellValue(point: PressureSeriesPoint, source: HorizonSource): {
+    value: number | null;
+    fromActual: boolean;
+};
+/**
+ * Split a magnitude into paintable layers.
+ *
+ * Returns `clipped: true` when the magnitude ran past the domain — the wall is
+ * capped at the darkest band and the caller is expected to say so rather than
+ * let the reader assume the cap is the true value.
+ */
+export declare function bandLayers({ magnitude, bands, domainMax }: {
+    magnitude: number;
+    bands?: number;
+    domainMax: number;
+}): {
+    layers: HorizonLayer[];
+    clipped: boolean;
+};
+/**
+ * One domain across every row, so a stack of rows is actually a comparison.
+ *
+ * Letting each row autoscale is the single easiest way to make this chart lie:
+ * an easy road and a brutal one would paint identically.
+ */
+export declare function resolveHorizonDomain(series: PressureSeries[], source: HorizonSource): number;
+export declare function buildHorizonRows({ series, source, bands, domainMax, projection }: BuildHorizonRowsParams): HorizonRowsResult;

package/dist/components/pressureHorizon/horizonLegend.d.ts

@@ -0,0 +1,14 @@
+import { HorizonDirection } from './types';
+/**
+ * One arm's steps, stepped in depth as well as hue so the ramp reads as ordered.
+ *
+ * `centred` mirrors the ribbon's geometry — steps grow from the middle rather than
+ * from an edge — so the glyph matches the chart it is keying.
+ */
+export declare function buildArmSwatch(direction: HorizonDirection, bands: number, centred?: boolean): SVGElement;
+export declare function buildHorizonLegend({ bands, scaleName, note, variant }: {
+    bands: number;
+    scaleName?: string;
+    note?: string;
+    variant?: string;
+}): HTMLElement;

package/dist/components/pressureHorizon/horizonRibbon.d.ts

@@ -0,0 +1,28 @@
+import { HorizonRow } from './types';
+export type HorizonRibbonOptions = {
+    width: number;
+    height: number;
+    domainMax: number;
+    /** Colour bands across the domain. Must match the walls or the two stop reading alike. */
+    bands?: number;
+    /**
+     * How many colour bands of the domain map to HALF the row height.
+     *
+     * This is the ribbon's version of the fold, and it is the setting that decides
+     * whether the chart is readable. A centred line splits the row between the two
+     * arms, so mapping the whole domain across it leaves a median value moving about
+     * three pixels — measured on a 16-draw, `|delta|` has a median of 238 against a
+     * 668 domain, which on a 22px row is 3.4px of travel. Mapping half the domain
+     * instead doubles every amplitude and leaves roughly a third of cells saturating
+     * at the row edge, where the gradient keeps them distinguishable.
+     */
+    positionBands?: number;
+    /** Attach hover descriptions. MUST stay false in the game — a title names the answer. */
+    describe?: boolean;
+    roundLabels?: (roundNumber: number, index: number, total: number) => string;
+    scaleName?: string;
+    ariaLabel?: string;
+    /** Draw the even-match reference line. */
+    showZeroLine?: boolean;
+};
+export declare function buildHorizonRibbonSvg(row: HorizonRow, options: HorizonRibbonOptions): SVGSVGElement;

package/dist/components/pressureHorizon/horizonRow.d.ts

@@ -0,0 +1,19 @@
+import { HorizonRow } from './types';
+export type HorizonRowOptions = {
+    width: number;
+    height: number;
+    gap?: number;
+    /**
+     * Attach per-wall `<title>` tooltips and a descriptive aria-label. MUST stay
+     * false in the game: a tooltip carrying the opponent rating hands over the
+     * deduction the puzzle is asking for.
+     */
+    describe?: boolean;
+    /** Used only when `describe` is true. */
+    roundLabels?: (roundNumber: number, index: number, total: number) => string;
+    scaleName?: string;
+    /** Overrides the aria-label. In the game this is the slot number, never a name. */
+    ariaLabel?: string;
+};
+/** The strip for one participant. Columns are laid out on the row's own cell order. */
+export declare function buildHorizonRowSvg(row: HorizonRow, options: HorizonRowOptions): SVGSVGElement;

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

@@ -0,0 +1,20 @@
+export { createDrawOrderGame, reshuffleDrawOrder, revealDrawOrder, moveSlot, swapSlots } from './drawOrderGameState';
+export { buildHorizonRows, resolveHorizonDomain, selectCellValue, bandLayers, DEFAULT_BANDS } from './horizonBands';
+export { shuffleWithSeed, shuffleDeranged, createRandom, fixedPoints } from './shuffleWithSeed';
+export { scoreDrawOrder, blockLevels, maxDisplacementFor } from './scoreDrawOrder';
+export { buildPressureHorizon, HORIZON_ORDER, HORIZON_VARIANT } from './pressureHorizon';
+export { HORIZON_DIRECTION, HORIZON_SOURCE } from './types';
+export { MIN_HORIZON_DOMAIN } from './horizonBands';
+export { buildDrawOrderGame } from './drawOrderGame';
+export { buildHorizonLegend, buildArmSwatch } from './horizonLegend';
+export { opponentSpread, weightedQuantile, INNER_QUANTILES } from './opponentSpread';
+export { buildHorizonRibbonSvg } from './horizonRibbon';
+export { buildHorizonRowSvg } from './horizonRow';
+export type { PressureHorizonOptions, PressureHorizonInstance, HorizonOrder, HorizonVariant } from './pressureHorizon';
+export type { DrawOrderGameOptions, DrawOrderGameInstance } from './drawOrderGame';
+export type { DrawOrderScore, BlockLevelScore, SlotResult } from './scoreDrawOrder';
+export type { DrawOrderGameState } from './drawOrderGameState';
+export type { HorizonRibbonOptions } from './horizonRibbon';
+export type { OpponentSpread } from './opponentSpread';
+export type { HorizonRowOptions } from './horizonRow';
+export type { BuildHorizonRowsParams, HorizonRowsResult, HorizonDirection, HorizonSource, HorizonSpread, HorizonLayer, HorizonCell, HorizonRow } from './types';

package/dist/components/pressureHorizon/opponentSpread.d.ts

@@ -0,0 +1,31 @@
+import { PossibleOpponent } from '../pressureChart/types';
+/** Default inner-envelope quantiles. The middle half of the arrival probability. */
+export declare const INNER_QUANTILES: [number, number];
+export type OpponentSpread = {
+    /** Full range over opponents clearing the projection's threshold. */
+    outerLow: number;
+    outerHigh: number;
+    /** Weighted interquartile range — where the probability mass sits. */
+    innerLow: number;
+    innerHigh: number;
+};
+/**
+ * Weighted quantile over (value, weight) pairs, values ascending.
+ *
+ * Uses the inclusive definition — walk the cumulative weight and take the first
+ * value whose running total reaches `q` of the total. With a single opponent every
+ * quantile is that opponent, which is what makes round 1 collapse to a point rather
+ * than to an arbitrary interval.
+ */
+export declare function weightedQuantile(sorted: {
+    value: number;
+    weight: number;
+}[], q: number): number | null;
+/**
+ * Derive both envelopes from the opponents who could arrive.
+ *
+ * Returns `null` when nobody in the pool carries a rating — the caller is expected
+ * to fall back to the projection's own `low`/`high`, and to draw nothing at all if
+ * that is absent too. Never invents a spread.
+ */
+export declare function opponentSpread(opponents: PossibleOpponent[], quantiles?: [number, number]): OpponentSpread | null;

package/dist/components/pressureHorizon/pressureHorizon.d.ts

@@ -0,0 +1,57 @@
+import { HorizonSource } from './types';
+import { ProjectedPressureResult, PressureSeries } from '../pressureChart/types';
+export declare const HORIZON_ORDER: {
+    readonly DRAW: "draw";
+    readonly DIFFICULTY: "difficulty";
+};
+export type HorizonOrder = (typeof HORIZON_ORDER)[keyof typeof HORIZON_ORDER];
+/**
+ * How a row is drawn. Neither is a replacement for the other:
+ *
+ *  - WALLS  — one hard-edged column per round, magnitude folded into colour bands.
+ *             Maximum density; reads down to 10px rows.
+ *  - RIBBON — a connected line through the rounds inside a fan of possible
+ *             opponents. Carries the spread the walls discard, and makes a near-zero
+ *             delta visible instead of a 1px sliver. Wants ~22px.
+ */
+export declare const HORIZON_VARIANT: {
+    readonly WALLS: "walls";
+    readonly RIBBON: "ribbon";
+};
+export type HorizonVariant = (typeof HORIZON_VARIANT)[keyof typeof HORIZON_VARIANT];
+export type PressureHorizonOptions = {
+    /** Width of the wall strip, excluding the label gutter. */
+    width?: number;
+    rowHeight?: number;
+    rowGap?: number;
+    /** Surface gap between round columns. */
+    columnGap?: number;
+    bands?: number;
+    variant?: HorizonVariant;
+    source?: HorizonSource;
+    /**
+     * The projection `buildPressureSeries` returns beside `series`. Only the ribbon
+     * reads it, and only to weight the inner fan; without it the fan falls back to the
+     * unweighted low/high envelope and says so.
+     */
+    projection?: ProjectedPressureResult;
+    /** Fix the domain across several stacks so they can be read against each other. */
+    domainMax?: number;
+    showLabels?: boolean;
+    labelWidth?: number;
+    showLegend?: boolean;
+    showRoundHeader?: boolean;
+    scaleName?: string;
+    order?: HorizonOrder;
+    /** Cap the rows rendered; the number dropped is stated in the caption. */
+    limit?: number;
+    onSelect?: (series: PressureSeries) => void;
+    roundLabels?: (roundNumber: number, index: number, total: number) => string;
+    emptyMessage?: string;
+};
+export type PressureHorizonInstance = {
+    element: HTMLElement;
+    update: (series: PressureSeries[], options?: PressureHorizonOptions) => void;
+    destroy: () => void;
+};
+export declare function buildPressureHorizon(container: HTMLElement, series?: PressureSeries[], options?: PressureHorizonOptions): PressureHorizonInstance;

package/dist/components/pressureHorizon/scoreDrawOrder.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Score a guessed draw order against the real one.
+ *
+ * **Why the headline number is structural, not positional.** The obvious score —
+ * "how many rows landed in the right slot" — punishes a player for being right.
+ * A draw sheet is mirror-symmetric: swapping the top half with the bottom half,
+ * or the two quarters inside a half, or the two players inside a first-round
+ * pair, produces a bracket with identical structure and a completely different
+ * set of slot numbers. A player who reconstructs the pairings perfectly but
+ * mirrors one half scores near zero on exact slots while having solved the
+ * puzzle.
+ *
+ * So the score counts **blocks**: at every level of the bracket (pairs, then
+ * quarters-of-the-half, then halves), how many of the guessed groupings are real
+ * groupings — matched as unordered member sets, anywhere in the guess. That is
+ * invariant under every symmetry of the bracket, which is exactly the property
+ * the answer key needs.
+ *
+ * `exact` and `proximity` are still reported, because they are what a player
+ * intuitively expects to see and because their gap against `structureScore` is
+ * itself the interesting feedback ("you had the draw right and the sheet upside
+ * down"). They are not the headline.
+ */
+export type BlockLevelScore = {
+    /** 2 = first-round pairs, 4 = who could meet by round 2, and so on. */
+    blockSize: number;
+    matched: number;
+    total: number;
+};
+export type SlotResult = {
+    slotIndex: number;
+    participantId: string;
+    /** Where this participant really sits, 0-based. */
+    actualIndex: number;
+    correct: boolean;
+};
+export type DrawOrderScore = {
+    slots: number;
+    /** Rows sitting in exactly the right slot. Symmetry-sensitive — read it with `structureScore`. */
+    exact: number;
+    /** Sum of |guessed index - actual index| across all rows. */
+    displacement: number;
+    /** The worst displacement a permutation of this size can achieve. */
+    maxDisplacement: number;
+    /** 1 - displacement/maxDisplacement. 1 is perfect, 0 is maximally reversed. */
+    proximity: number;
+    levels: BlockLevelScore[];
+    blocksMatched: number;
+    blocksTotal: number;
+    /** 0-100, the headline. Symmetry-invariant. */
+    structureScore: number;
+    /** Every block at every level was a real grouping. */
+    structurePerfect: boolean;
+    /** The guess is the actual order, slot for slot. */
+    perfect: boolean;
+    slotResults: SlotResult[];
+};
+/** The block sizes a field of this size actually has. Empty when it does not divide. */
+export declare function blockLevels(slots: number): number[];
+/**
+ * Maximum total displacement over all permutations of n elements.
+ * Reversal achieves it, and it evaluates to floor(n^2 / 2).
+ */
+export declare function maxDisplacementFor(slots: number): number;
+/**
+ * @throws when `guess` is not a permutation of `actual` — that is a caller bug,
+ * and scoring it would quietly report a number for an impossible board.
+ */
+export declare function scoreDrawOrder({ guess, actual }: {
+    guess: string[];
+    actual: string[];
+}): DrawOrderScore;

package/dist/components/pressureHorizon/shuffleWithSeed.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Deterministic shuffling for the draw-order game.
+ *
+ * `Math.random()` is deliberately not used. A puzzle has to be reproducible: the
+ * same seed must always deal the same board so two people can be given the same
+ * one to race on, a score can be quoted against an identifiable puzzle, and the
+ * shuffle can be asserted in a unit test rather than described in a comment.
+ */
+/** mulberry32 — small, fast, and good enough for dealing a board. Not cryptographic. */
+export declare function createRandom(seed: number): () => number;
+/** Fisher-Yates against a seeded stream. Non-mutating. */
+export declare function shuffleWithSeed<T>(items: readonly T[], seed: number): T[];
+/** How many items a shuffle left sitting in their original slot. */
+export declare function fixedPoints<T>(items: readonly T[], shuffled: readonly T[]): number;
+/**
+ * A shuffle that actually looks shuffled.
+ *
+ * A plain shuffle leaves roughly one item in place on average, and a board that
+ * opens with three rows already correct is a worse puzzle than one that opens
+ * with none — the player cannot tell luck from deduction. So walk consecutive
+ * seeds until a derangement turns up, and if none does inside `attempts`, take
+ * the best of what was seen and **report which seed produced it** so the board
+ * stays reproducible either way.
+ *
+ * Fewer than two items cannot be deranged; that is returned as-is rather than
+ * spun on, with `deranged: false` so the caller is never told a fiction.
+ */
+export declare function shuffleDeranged<T>(items: readonly T[], seed: number, attempts?: number): {
+    items: T[];
+    seed: number;
+    deranged: boolean;
+};

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

@@ -0,0 +1,124 @@
+/**
+ * Pressure horizon — type definitions.
+ *
+ * A **second, independent iteration** on `pressureChart`, not a replacement for
+ * it. Both read the same `PressureSeries`; they differ in what they optimise
+ * for:
+ *
+ *  - `pressureChart` is a DETAIL view — one participant, a continuous y-axis,
+ *    the projected ribbon visibly narrowing as the draw resolves.
+ *  - `pressureHorizon` is a DENSITY view — one row per participant at 14-20px,
+ *    every row on the same domain, designed to be stacked and compared by the
+ *    dozen. Magnitude is folded out of height and into colour bands, which is
+ *    the whole point of a horizon chart: it buys vertical space by spending
+ *    colour.
+ *
+ * Two encodings carry direction, never colour alone:
+ *
+ *   position -> a HARD round (playing up) grows from the row's baseline;
+ *               an EASY round (playing down) hangs from the row's top edge
+ *   hue      -> red arm for hard, blue arm for easy, both ordinal light->dark
+ *
+ * That redundancy is deliberate. The palest step of each arm sits below 3:1
+ * against the surface (2.11:1 blue, 2.16:1 red on white), which the data-viz
+ * standard permits only with relief — so the legend is always present and the
+ * anchoring cue is doing real work, not decoration.
+ */
+/** Which series a cell reads its value from. */
+export declare const HORIZON_SOURCE: {
+    /** The projected expected signed delta — the wall as it looked before the round was played. */
+    readonly PROJECTED: "projected";
+    /** The realised signed delta where a round has been played, falling back to projected. */
+    readonly ACTUAL: "actual";
+};
+export type HorizonSource = (typeof HORIZON_SOURCE)[keyof typeof HORIZON_SOURCE];
+/** Sign of the signed delta, named for what it means rather than for its sign. */
+export declare const HORIZON_DIRECTION: {
+    /** Opponent rated above the participant — projected to play up. */
+    readonly HARD: "hard";
+    /** Opponent rated below the participant — projected to play down. */
+    readonly EASY: "easy";
+};
+export type HorizonDirection = (typeof HORIZON_DIRECTION)[keyof typeof HORIZON_DIRECTION];
+/**
+ * One painted layer of a wall. `fraction` is the share of the row height this
+ * layer covers, so a full band is 1 and the topmost partial band is < 1.
+ *
+ * Layers are painted in ascending `bandIndex` with each one anchored to the same
+ * edge, so the darkest step ends up over the shallowest extent — that overlap IS
+ * the horizon fold, and it is why a value of 3.4 bands reads darker than 1.2
+ * without being any taller.
+ */
+export type HorizonLayer = {
+    bandIndex: number;
+    fraction: number;
+};
+/**
+ * The opponent spread for a round, in signed-delta space (opponent minus own).
+ *
+ * Two envelopes, because one would lie. See `opponentSpread` for the measurement
+ * that decided it. `null` where the round carries no rated opponent pool.
+ */
+export type HorizonSpread = {
+    /** Full range over opponents clearing the projection's arrival threshold. */
+    outerLow: number;
+    outerHigh: number;
+    /** Weighted interquartile range — where the arrival probability actually sits. */
+    innerLow: number;
+    innerHigh: number;
+    /** True when the inner envelope came from the projection rather than a low/high fallback. */
+    weighted: boolean;
+};
+/** One round of one participant — a single wall, or one vertex of a ribbon. */
+export type HorizonCell = {
+    roundNumber: number;
+    /** Signed delta, or `null` where the round carries no rated opponent. */
+    value: number | null;
+    direction: HorizonDirection | null;
+    /** Empty when there is nothing to paint. */
+    layers: HorizonLayer[];
+    /** True when `|value|` exceeded the domain and the wall was capped. Counted, never silent. */
+    clipped: boolean;
+    /** True when the value came from a played matchUp rather than the projection. */
+    fromActual: boolean;
+    reachProbability: number;
+    bye: boolean;
+    resolved: boolean;
+    /**
+     * Where the possible opponents sit. Read by the ribbon renderer; the walls
+     * renderer ignores it, which is why it is `null` rather than absent when no
+     * projection was supplied.
+     */
+    spread: HorizonSpread | null;
+};
+/** One participant's full path, aligned to the shared round axis. */
+export type HorizonRow = {
+    participantId: string;
+    participantName?: string;
+    drawPosition?: number;
+    cells: HorizonCell[];
+};
+export type BuildHorizonRowsParams = {
+    series: import('../pressureChart/types').PressureSeries[];
+    source?: HorizonSource;
+    bands?: number;
+    /** Fix the domain across a set of rows. Omit to derive it from the series. */
+    domainMax?: number;
+    /**
+     * The projection `buildPressureSeries` already returns beside `series`. Optional:
+     * supply it and each cell gains a probability-weighted inner envelope; omit it and
+     * the spread falls back to the projection's own low/high, which is a min/max over
+     * a 1% arrival threshold and therefore much wider. Taking it here rather than
+     * widening `PressureSeries` is what keeps `pressureChart/` untouched.
+     */
+    projection?: import('../pressureChart/types').ProjectedPressureResult;
+};
+export type HorizonRowsResult = {
+    rows: HorizonRow[];
+    /** The union of round numbers across every row, ascending. Columns align to this. */
+    roundNumbers: number[];
+    domainMax: number;
+    bands: number;
+    /** How many walls hit the domain cap. Surfaced in the caption when non-zero. */
+    clippedCells: number;
+};