xpt-shared-types 1.1.0 → 1.3.0

package/dist/bracket.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Bracket shape — how many rounds a single-elimination tournament has, what
+ * each is called, how matches are numbered, and where each winner goes.
+ *
+ * This is the single source of truth for both apps: xpt-strapi re-exports it
+ * from `src/utils/bracket.ts` (adding the Strapi-coupled stage sync), and
+ * xpt-client's Storybook fixtures consume it directly — a fixture built any
+ * other way could show a bracket the backend can never produce.
+ */
+import type { MatchRound } from './generated';
+/** The largest bracket the round names can describe. */
+export declare const MAX_BRACKET_SIZE = 128;
+export declare function nextPowerOf2(n: number): number;
+export interface BracketRound {
+    name: MatchRound;
+    matchCount: number;
+}
+export declare function buildBracketRounds(bracketSize: number, hasThirdPlace: boolean): BracketRound[];
+/** The rounds a tournament of this many entrants will be played over. */
+export declare function bracketRoundsForParticipants(participants: number, hasThirdPlace: boolean): BracketRound[];
+/** Uniform Fisher–Yates shuffle. A `sort(() => Math.random() - 0.5)` is
+ * biased — comparison sorts assume a consistent comparator, so some orderings
+ * come up measurably more often than others. */
+export declare function shuffle<T>(items: readonly T[]): T[];
+/**
+ * Standard bracket seed order: which seed (0-based) sits in each first-round
+ * slot. Built by the usual doubling rule — each seed is paired with its
+ * complement, so seed 0 meets seed 1 only in the final.
+ *
+ * This is also the bye-safety property: slots are paired (s, size-1-s), and
+ * byes are the seeds from `checkedIn` upward. Both sides of a pair being byes
+ * would need `checkedIn <= (size-1)/2`, but `nextPowerOf2` guarantees
+ * `checkedIn > size/2` — so a bye always faces a real entrant.
+ */
+export declare function seedOrder(bracketSize: number): number[];
+export interface PlannedMatch {
+    round: MatchRound;
+    matchNumber: number;
+    /** Where this match's winner goes; null for Finals and Third Round. */
+    nextMatchNumber: number | null;
+    winnerSlot: 'home' | 'away' | null;
+    /** First-round matches only: index into the seeded slot array (null = later round). */
+    homeSlot: number | null;
+    awaySlot: number | null;
+}
+export interface BracketPlan {
+    bracketSize: number;
+    rounds: BracketRound[];
+    matches: PlannedMatch[];
+}
+/**
+ * The full bracket as data: every match, its number, and where its winner
+ * goes. Numbering is sequential across rounds in bracket order, with Third
+ * Round (when present) sitting before Finals.
+ */
+export declare function buildBracketPlan(bracketSize: number, hasThirdPlace: boolean): BracketPlan;

package/dist/bracket.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Bracket shape — how many rounds a single-elimination tournament has, what
+ * each is called, how matches are numbered, and where each winner goes.
+ *
+ * This is the single source of truth for both apps: xpt-strapi re-exports it
+ * from `src/utils/bracket.ts` (adding the Strapi-coupled stage sync), and
+ * xpt-client's Storybook fixtures consume it directly — a fixture built any
+ * other way could show a bracket the backend can never produce.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BRACKET_SIZE = void 0;
+exports.nextPowerOf2 = nextPowerOf2;
+exports.buildBracketRounds = buildBracketRounds;
+exports.bracketRoundsForParticipants = bracketRoundsForParticipants;
+exports.shuffle = shuffle;
+exports.seedOrder = seedOrder;
+exports.buildBracketPlan = buildBracketPlan;
+/** The largest bracket the round names can describe. */
+exports.MAX_BRACKET_SIZE = 128;
+function nextPowerOf2(n) {
+    if (n <= 2)
+        return 2;
+    let p = 2;
+    while (p < n)
+        p *= 2;
+    return p;
+}
+/**
+ * The name of the round that *starts* with this many players left. Halving
+ * from the bracket size down to 2 walks the whole bracket, so there is no
+ * table of per-size name lists to fall out of sync — the one way a size can
+ * go wrong is a size that is not a power of two in range, and that throws.
+ */
+const ROUND_NAME_BY_SIZE = {
+    128: 'Round 128',
+    64: 'Round 64',
+    32: 'Round 32',
+    16: 'Round 16',
+    8: 'Quarter Final',
+    4: 'Semi-Final',
+    2: 'Finals',
+};
+function buildBracketRounds(bracketSize, hasThirdPlace) {
+    // An unrecognised size used to fall back to a single round called "Finals"
+    // holding `bracketSize / 2` matches. An unplayable bracket is worse than no
+    // bracket.
+    if (!ROUND_NAME_BY_SIZE[bracketSize]) {
+        throw new Error(`Unsupported bracket size ${bracketSize} — must be a power of two between 2 and ${exports.MAX_BRACKET_SIZE}`);
+    }
+    const rounds = [];
+    for (let size = bracketSize; size >= 2; size /= 2) {
+        rounds.push({ name: ROUND_NAME_BY_SIZE[size], matchCount: size / 2 });
+    }
+    // Inject Third Round slot before Finals when enabled (4+ players)
+    if (hasThirdPlace && bracketSize >= 4) {
+        const finalsIdx = rounds.findIndex((r) => r.name === 'Finals');
+        if (finalsIdx > 0) {
+            rounds.splice(finalsIdx, 0, { name: 'Third Round', matchCount: 1 });
+        }
+    }
+    return rounds;
+}
+/** The rounds a tournament of this many entrants will be played over. */
+function bracketRoundsForParticipants(participants, hasThirdPlace) {
+    return buildBracketRounds(nextPowerOf2(participants), hasThirdPlace);
+}
+/** Uniform Fisher–Yates shuffle. A `sort(() => Math.random() - 0.5)` is
+ * biased — comparison sorts assume a consistent comparator, so some orderings
+ * come up measurably more often than others. */
+function shuffle(items) {
+    const result = [...items];
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}
+/**
+ * Standard bracket seed order: which seed (0-based) sits in each first-round
+ * slot. Built by the usual doubling rule — each seed is paired with its
+ * complement, so seed 0 meets seed 1 only in the final.
+ *
+ * This is also the bye-safety property: slots are paired (s, size-1-s), and
+ * byes are the seeds from `checkedIn` upward. Both sides of a pair being byes
+ * would need `checkedIn <= (size-1)/2`, but `nextPowerOf2` guarantees
+ * `checkedIn > size/2` — so a bye always faces a real entrant.
+ */
+function seedOrder(bracketSize) {
+    if (!ROUND_NAME_BY_SIZE[bracketSize]) {
+        throw new Error(`Unsupported bracket size ${bracketSize} — must be a power of two between 2 and ${exports.MAX_BRACKET_SIZE}`);
+    }
+    let order = [0];
+    while (order.length < bracketSize) {
+        const size = order.length * 2;
+        const next = [];
+        for (const seed of order) {
+            next.push(seed, size - 1 - seed);
+        }
+        order = next;
+    }
+    return order;
+}
+/**
+ * The full bracket as data: every match, its number, and where its winner
+ * goes. Numbering is sequential across rounds in bracket order, with Third
+ * Round (when present) sitting before Finals.
+ */
+function buildBracketPlan(bracketSize, hasThirdPlace) {
+    const rounds = buildBracketRounds(bracketSize, hasThirdPlace);
+    let counter = 1;
+    const roundMatchNumbers = rounds.map((round) => Array.from({ length: round.matchCount }, () => counter++));
+    // Winner linkage skips Third Round — it receives losers, not winners.
+    const linkage = {};
+    const nonThirdRounds = rounds
+        .map((round, index) => ({ round, index }))
+        .filter(({ round }) => round.name !== 'Third Round');
+    for (let ri = 0; ri < nonThirdRounds.length - 1; ri++) {
+        const currentNums = roundMatchNumbers[nonThirdRounds[ri].index];
+        const nextNums = roundMatchNumbers[nonThirdRounds[ri + 1].index];
+        currentNums.forEach((num, mi) => {
+            linkage[num] = {
+                nextMatchNumber: nextNums[Math.floor(mi / 2)],
+                winnerSlot: mi % 2 === 0 ? 'home' : 'away',
+            };
+        });
+    }
+    const matches = [];
+    rounds.forEach((round, ri) => {
+        roundMatchNumbers[ri].forEach((num, mi) => {
+            var _a;
+            const link = (_a = linkage[num]) !== null && _a !== void 0 ? _a : { nextMatchNumber: null, winnerSlot: null };
+            matches.push({
+                round: round.name,
+                matchNumber: num,
+                nextMatchNumber: link.nextMatchNumber,
+                winnerSlot: link.winnerSlot,
+                homeSlot: ri === 0 ? mi * 2 : null,
+                awaySlot: ri === 0 ? mi * 2 + 1 : null,
+            });
+        });
+    });
+    return { bracketSize, rounds, matches };
+}

package/dist/data/countriesList.js

@@ -1090,7 +1090,7 @@ exports.COUNTRIES_LIST = [
     },
     {
         countryName: "United Kingdom",
-        alpha2: "GB-UKM",
+        alpha2: "GB",
         alpha3: "GBR",
         numeric: "826",
     },

package/dist/generated/enums.d.ts

@@ -9,7 +9,7 @@ export type GameRequestTeamPlay = "No (solo)" | "Yes, 2v2" | "Yes, 3v3" | "Yes,
 /** `Match.lobbyStatus` */
 export type MatchLobbyStatus = "waiting" | "ready" | "disputed" | "completed";
 /** `Match.round` */
-export type MatchRound = "Round 32" | "Round 16" | "Quarter Final" | "Semi-Final" | "Third Round" | "Finals" | "League";
+export type MatchRound = "Round 128" | "Round 64" | "Round 32" | "Round 16" | "Quarter Final" | "Semi-Final" | "Third Round" | "Finals" | "League";
 /** `Match.streamPlatform` */
 export type MatchStreamPlatform = "twitch" | "youtube" | "kick" | "other";
 /** `Match.winnerSlot` */
@@ -35,7 +35,7 @@ export type TournamentParticipantStatus = "registered" | "active" | "eliminated"
 /** `TournamentRole.role` */
 export type TournamentRoleRole = "moderator" | "admin";
 /** `TournamentStage.stageName` */
-export type TournamentStageStageName = "Round 32" | "Round 16" | "Quarter Final" | "Semi-Final" | "Third Round" | "Finals" | "League";
+export type TournamentStageStageName = "Round 128" | "Round 64" | "Round 32" | "Round 16" | "Quarter Final" | "Semi-Final" | "Third Round" | "Finals" | "League";
 /** `Tournament.teamSize` */
 export type TournamentTeamSize = "one" | "two" | "three" | "four" | "five";
 /** `Tournament.type` */

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './generated';
 export * from './contracts';
 export * from './manual';
+export * from './bracket';
 export * from './data/countriesList';

package/dist/index.js

@@ -20,5 +20,7 @@ __exportStar(require("./generated"), exports);
 __exportStar(require("./contracts"), exports);
 // Hand-written types with no Strapi content type behind them
 __exportStar(require("./manual"), exports);
+// Bracket shape — shared by the backend generator and Storybook fixtures
+__exportStar(require("./bracket"), exports);
 // Data
 __exportStar(require("./data/countriesList"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xpt-shared-types",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Shared types and data for XPT projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/bracket.ts

@@ -0,0 +1,193 @@
+/**
+ * Bracket shape — how many rounds a single-elimination tournament has, what
+ * each is called, how matches are numbered, and where each winner goes.
+ *
+ * This is the single source of truth for both apps: xpt-strapi re-exports it
+ * from `src/utils/bracket.ts` (adding the Strapi-coupled stage sync), and
+ * xpt-client's Storybook fixtures consume it directly — a fixture built any
+ * other way could show a bracket the backend can never produce.
+ */
+
+import type { MatchRound } from './generated';
+
+/** The largest bracket the round names can describe. */
+export const MAX_BRACKET_SIZE = 128;
+
+export function nextPowerOf2(n: number): number {
+  if (n <= 2) return 2;
+  let p = 2;
+  while (p < n) p *= 2;
+  return p;
+}
+
+export interface BracketRound {
+  name: MatchRound;
+  matchCount: number;
+}
+
+/**
+ * The name of the round that *starts* with this many players left. Halving
+ * from the bracket size down to 2 walks the whole bracket, so there is no
+ * table of per-size name lists to fall out of sync — the one way a size can
+ * go wrong is a size that is not a power of two in range, and that throws.
+ */
+const ROUND_NAME_BY_SIZE: Record<number, MatchRound> = {
+  128: 'Round 128',
+  64: 'Round 64',
+  32: 'Round 32',
+  16: 'Round 16',
+  8: 'Quarter Final',
+  4: 'Semi-Final',
+  2: 'Finals',
+};
+
+export function buildBracketRounds(
+  bracketSize: number,
+  hasThirdPlace: boolean
+): BracketRound[] {
+  // An unrecognised size used to fall back to a single round called "Finals"
+  // holding `bracketSize / 2` matches. An unplayable bracket is worse than no
+  // bracket.
+  if (!ROUND_NAME_BY_SIZE[bracketSize]) {
+    throw new Error(
+      `Unsupported bracket size ${bracketSize} — must be a power of two between 2 and ${MAX_BRACKET_SIZE}`
+    );
+  }
+
+  const rounds: BracketRound[] = [];
+
+  for (let size = bracketSize; size >= 2; size /= 2) {
+    rounds.push({ name: ROUND_NAME_BY_SIZE[size], matchCount: size / 2 });
+  }
+
+  // Inject Third Round slot before Finals when enabled (4+ players)
+  if (hasThirdPlace && bracketSize >= 4) {
+    const finalsIdx = rounds.findIndex((r) => r.name === 'Finals');
+    if (finalsIdx > 0) {
+      rounds.splice(finalsIdx, 0, { name: 'Third Round', matchCount: 1 });
+    }
+  }
+
+  return rounds;
+}
+
+/** The rounds a tournament of this many entrants will be played over. */
+export function bracketRoundsForParticipants(
+  participants: number,
+  hasThirdPlace: boolean
+): BracketRound[] {
+  return buildBracketRounds(nextPowerOf2(participants), hasThirdPlace);
+}
+
+/** Uniform Fisher–Yates shuffle. A `sort(() => Math.random() - 0.5)` is
+ * biased — comparison sorts assume a consistent comparator, so some orderings
+ * come up measurably more often than others. */
+export function shuffle<T>(items: readonly T[]): T[] {
+  const result = [...items];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+}
+
+/**
+ * Standard bracket seed order: which seed (0-based) sits in each first-round
+ * slot. Built by the usual doubling rule — each seed is paired with its
+ * complement, so seed 0 meets seed 1 only in the final.
+ *
+ * This is also the bye-safety property: slots are paired (s, size-1-s), and
+ * byes are the seeds from `checkedIn` upward. Both sides of a pair being byes
+ * would need `checkedIn <= (size-1)/2`, but `nextPowerOf2` guarantees
+ * `checkedIn > size/2` — so a bye always faces a real entrant.
+ */
+export function seedOrder(bracketSize: number): number[] {
+  if (!ROUND_NAME_BY_SIZE[bracketSize]) {
+    throw new Error(
+      `Unsupported bracket size ${bracketSize} — must be a power of two between 2 and ${MAX_BRACKET_SIZE}`
+    );
+  }
+
+  let order = [0];
+  while (order.length < bracketSize) {
+    const size = order.length * 2;
+    const next: number[] = [];
+    for (const seed of order) {
+      next.push(seed, size - 1 - seed);
+    }
+    order = next;
+  }
+  return order;
+}
+
+export interface PlannedMatch {
+  round: MatchRound;
+  matchNumber: number;
+  /** Where this match's winner goes; null for Finals and Third Round. */
+  nextMatchNumber: number | null;
+  winnerSlot: 'home' | 'away' | null;
+  /** First-round matches only: index into the seeded slot array (null = later round). */
+  homeSlot: number | null;
+  awaySlot: number | null;
+}
+
+export interface BracketPlan {
+  bracketSize: number;
+  rounds: BracketRound[];
+  matches: PlannedMatch[];
+}
+
+/**
+ * The full bracket as data: every match, its number, and where its winner
+ * goes. Numbering is sequential across rounds in bracket order, with Third
+ * Round (when present) sitting before Finals.
+ */
+export function buildBracketPlan(
+  bracketSize: number,
+  hasThirdPlace: boolean
+): BracketPlan {
+  const rounds = buildBracketRounds(bracketSize, hasThirdPlace);
+
+  let counter = 1;
+  const roundMatchNumbers = rounds.map((round) =>
+    Array.from({ length: round.matchCount }, () => counter++)
+  );
+
+  // Winner linkage skips Third Round — it receives losers, not winners.
+  const linkage: Record<
+    number,
+    { nextMatchNumber: number; winnerSlot: 'home' | 'away' }
+  > = {};
+  const nonThirdRounds = rounds
+    .map((round, index) => ({ round, index }))
+    .filter(({ round }) => round.name !== 'Third Round');
+
+  for (let ri = 0; ri < nonThirdRounds.length - 1; ri++) {
+    const currentNums = roundMatchNumbers[nonThirdRounds[ri].index];
+    const nextNums = roundMatchNumbers[nonThirdRounds[ri + 1].index];
+
+    currentNums.forEach((num, mi) => {
+      linkage[num] = {
+        nextMatchNumber: nextNums[Math.floor(mi / 2)],
+        winnerSlot: mi % 2 === 0 ? 'home' : 'away',
+      };
+    });
+  }
+
+  const matches: PlannedMatch[] = [];
+  rounds.forEach((round, ri) => {
+    roundMatchNumbers[ri].forEach((num, mi) => {
+      const link = linkage[num] ?? { nextMatchNumber: null, winnerSlot: null };
+      matches.push({
+        round: round.name,
+        matchNumber: num,
+        nextMatchNumber: link.nextMatchNumber,
+        winnerSlot: link.winnerSlot,
+        homeSlot: ri === 0 ? mi * 2 : null,
+        awaySlot: ri === 0 ? mi * 2 + 1 : null,
+      });
+    });
+  });
+
+  return { bracketSize, rounds, matches };
+}

package/src/data/countriesList.ts

@@ -1089,7 +1089,7 @@ export const COUNTRIES_LIST: Country[] = [
   },
   {
     countryName: "United Kingdom",
-    alpha2: "GB-UKM",
+    alpha2: "GB",
     alpha3: "GBR",
     numeric: "826",
   },

package/src/generated/enums.ts

@@ -42,6 +42,8 @@ export type MatchLobbyStatus =
 
 /** `Match.round` */
 export type MatchRound =
+  | "Round 128"
+  | "Round 64"
   | "Round 32"
   | "Round 16"
   | "Quarter Final"
@@ -129,6 +131,8 @@ export type TournamentRoleRole =
 
 /** `TournamentStage.stageName` */
 export type TournamentStageStageName =
+  | "Round 128"
+  | "Round 64"
   | "Round 32"
   | "Round 16"
   | "Quarter Final"

package/src/index.ts

@@ -7,5 +7,8 @@ export * from './contracts';
 // Hand-written types with no Strapi content type behind them
 export * from './manual';
 
+// Bracket shape — shared by the backend generator and Storybook fixtures
+export * from './bracket';
+
 // Data
 export * from './data/countriesList';