@scriptonita/chess-football-ui 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -15,8 +15,9 @@ interface GameBoardProps {
      * `KeyboardShortcutsList` itself (e.g. in a side panel) so nothing is shown twice.
      */
     toolbar?: boolean;
+    className?: string;
 }
-declare function GameBoard({ userSide, showCoordinates, keyboardNav, toolbar }: GameBoardProps): react.JSX.Element | null;
+declare function GameBoard({ userSide, showCoordinates, keyboardNav, toolbar, className }: GameBoardProps): react.JSX.Element | null;
 
 interface GamePieceProps {
     piece: Piece;
@@ -43,8 +44,9 @@ interface ScoreboardProps {
     creatorAvatarUrl?: string;
     opponentAvatarUrl?: string;
     userSide?: 'white' | 'black' | null;
+    className?: string;
 }
-declare function Scoreboard({ creatorUsername, opponentUsername, creatorAvatarUrl, opponentAvatarUrl, userSide, }: ScoreboardProps): react.JSX.Element | null;
+declare function Scoreboard({ creatorUsername, opponentUsername, creatorAvatarUrl, opponentAvatarUrl, userSide, className, }: ScoreboardProps): react.JSX.Element | null;
 
 interface MiniScoreboardProps {
     creatorUsername: string;
@@ -60,8 +62,9 @@ declare function MiniScoreboard({ creatorUsername, opponentUsername, userSide, c
 
 interface GameControlsProps {
     isMyTurn: boolean;
+    className?: string;
 }
-declare function GameControls({ isMyTurn }: GameControlsProps): react.JSX.Element | null;
+declare function GameControls({ isMyTurn, className }: GameControlsProps): react.JSX.Element | null;
 
 interface SelectedPieceDetailProps {
     isMyTurn: boolean;
@@ -86,7 +89,34 @@ interface MoveHistoryProps {
  */
 declare function MoveHistory({ scrollable, limit, className }: MoveHistoryProps): react.JSX.Element;
 
-declare function StaticGameBoard(): react.JSX.Element;
+declare function StaticGameBoard({ className }?: {
+    className?: string;
+}): react.JSX.Element;
+
+interface PlayerIdentityProps {
+    name: string;
+    team: string;
+    /**
+     * `full` — the side panels and the mobile scoreboard: name on its own line,
+     * team beneath it. `compact` — the tablet/desktop mini-scoreboard, where the
+     * pair shares one line.
+     */
+    variant?: 'full' | 'compact';
+    isActive?: boolean;
+    align?: 'left' | 'right';
+    /** Rendered inline after the team label (e.g. the active-turn pulse dot). */
+    adornment?: React.ReactNode;
+    className?: string;
+}
+/**
+ * One player's name and team.
+ *
+ * `Scoreboard` set this in Inter 13px semibold with the team in mono 10px, and
+ * `MiniScoreboard` in mono 10px uppercase joined by a middot — so the same
+ * player changed appearance on a viewport change. Both now render this, and the
+ * only difference left is the deliberate one: how much room there is.
+ */
+declare function PlayerIdentity({ name, team, variant, isActive, align, adornment, className, }: PlayerIdentityProps): react.JSX.Element;
 
 declare const PITCH_COLS = 9;
 declare const PITCH_ROWS = 12;
@@ -246,6 +276,27 @@ interface ConfirmDialogProps {
 }
 declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, onConfirm, onCancel }: ConfirmDialogProps): react.JSX.Element | null;
 
+/**
+ * Every CSS custom property the package's Tailwind classes resolve against.
+ *
+ * A token the host app does not define fails *silently*: Tailwind emits the
+ * rule, the variable resolves to nothing, and the declaration is dropped. That
+ * is how `--last-move-highlight` went missing in the CrazyGames SPA — the
+ * last-move highlight and the bot's turn replay simply never rendered, with no
+ * error anywhere.
+ *
+ * This is the visual counterpart to `GAME_I18N_KEYS`: assert it in each app.
+ *
+ * ```ts
+ * import { REQUIRED_TOKENS } from '@scriptonita/chess-football-ui'
+ *
+ * const css = readFileSync('src/index.css', 'utf8')
+ * expect(REQUIRED_TOKENS.filter(t => !css.includes(`${t}:`))).toEqual([])
+ * ```
+ */
+declare const REQUIRED_TOKENS: readonly ["--bg-primary", "--bg-secondary", "--bg-surface", "--bg-surface-elevated", "--fg-primary", "--fg-secondary", "--fg-muted", "--accent-green", "--accent-green-light", "--accent-green-dark", "--border-subtle", "--danger", "--warning", "--field-green-1", "--field-green-2", "--field-frame", "--move-highlight", "--pass-highlight", "--last-move-highlight"];
+type RequiredToken = (typeof REQUIRED_TOKENS)[number];
+
 /**
  * A translator scoped to the `game` namespace: `t('yourTurn')`, `t('move')`, …
  * Each host app supplies one bound to its own i18n library:
@@ -259,11 +310,11 @@ type GameTranslator = (key: string, values?: Record<string, unknown>) => string;
  *   grep -rhoE "t\('[a-zA-Z0-9_.]+'" src/components | sed -E "s/t\('//;s/'//" | sort -u
  * (the dynamic `pieces.*` / `eventToast.*` families are derived separately below).
  */
-declare const STATIC_I18N_KEYS: readonly ["actionPointsAriaLabel", "actionPointsShort", "ballHolder", "endTurn", "endTurnConfirm", "endTurnConfirmDescription", "endTurnConfirmYes", "endTurnKeepPlaying", "history.empty", "history.goal", "history.interception", "history.move", "history.offside", "history.pass", "history.tackle", "history.title", "history.turn", "history.viewAll", "move", "offsideWarning", "pass", "selectedPiece.alreadyMoved", "selectedPiece.atSquare", "selectedPiece.empty", "selectedPiece.hasBall", "shortcuts.arrows", "shortcuts.buttonLabel", "shortcuts.cancel", "shortcuts.move", "shortcuts.pass", "shortcuts.select", "shortcuts.title", "teamBlack", "teamWhite", "waitingRival", "yourTurn"];
+declare const STATIC_I18N_KEYS: readonly ["actionPointsAriaLabel", "actionPointsShort", "ballHolder", "boardAriaLabel", "endTurn", "endTurnConfirm", "endTurnConfirmDescription", "endTurnConfirmYes", "endTurnKeepPlaying", "history.empty", "history.goal", "history.interception", "history.move", "history.offside", "history.pass", "history.tackle", "history.title", "history.close", "history.turn", "history.viewAll", "move", "offsideWarning", "pass", "scoreAriaLabel", "selectedPiece.alreadyMoved", "selectedPiece.atSquare", "selectedPiece.empty", "selectedPiece.hasBall", "shortcuts.arrows", "shortcuts.buttonLabel", "shortcuts.cancel", "shortcuts.move", "shortcuts.pass", "shortcuts.select", "shortcuts.title", "square.empty", "square.emptyWithBall", "square.moveOrPassTarget", "square.moveTarget", "square.passTarget", "square.piece", "square.pieceWithBall", "square.selected", "teamBlack", "teamWhite", "waitingRival", "yourTurn"];
 /** `pieces.*` — one key per short and long piece label the engine exposes (move-history, selected-piece-detail). */
 type PieceI18nKey = `pieces.${PieceShortKey | PieceLongKey}`;
 /** `eventToast.*` — one key per toastable event (see `ToastEvent` in `event-toast.tsx`). */
-type EventToastI18nKey = `eventToast.${'interception' | 'offside' | 'tackle'}`;
+type EventToastI18nKey = `eventToast.${'goal' | 'interception' | 'offside' | 'tackle'}`;
 /** Union of every `game`-namespace key the package reads. */
 type GameI18nKey = (typeof STATIC_I18N_KEYS)[number] | PieceI18nKey | EventToastI18nKey;
 /**
@@ -283,4 +334,23 @@ declare function useGameT(): GameTranslator;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { ActionPoints, Avatar, AvatarFallback, AvatarImage, BallHolderChip, Button, type ButtonProps, ConfirmDialog, EventToast, Football, GAME_I18N_KEYS, GOAL_AREA_SHADE_CLASS, GameBoard, GameControls, type GameI18nKey, GameI18nProvider, GamePiece, type GameTranslator, GrassOverlay, KeyboardShortcutsList, MiniScoreboard, MobileHistory, MoveHistory, PITCH_COLS, PITCH_ROWS, PitchMarkings, PitchSurface, Scoreboard, SelectedPieceDetail, StaticGameBoard, TurnBanner, cn, isGoalAreaSquare, pitchSquareClass, useGameT };
+interface DialogA11yOptions {
+    open: boolean;
+    onClose: () => void;
+}
+/**
+ * The four behaviours `aria-modal="true"` promises but does not implement.
+ * Declaring `aria-modal` without them is worse than not declaring it at all:
+ * assistive tech stops exposing the page behind the dialog while the keyboard
+ * happily walks straight into it.
+ *
+ *   1. Initial focus — the first focusable control, or the panel itself.
+ *   2. Focus trap — Tab / Shift+Tab cycle inside the panel.
+ *   3. Escape closes.
+ *   4. Focus returns to whatever opened the dialog.
+ *
+ * Attach the returned ref to the dialog panel (the node carrying `role="dialog"`).
+ */
+declare function useDialogA11y({ open, onClose }: DialogA11yOptions): react.RefObject<HTMLDivElement | null>;
+
+export { ActionPoints, Avatar, AvatarFallback, AvatarImage, BallHolderChip, Button, type ButtonProps, ConfirmDialog, EventToast, Football, GAME_I18N_KEYS, GOAL_AREA_SHADE_CLASS, GameBoard, GameControls, type GameI18nKey, GameI18nProvider, GamePiece, type GameTranslator, GrassOverlay, KeyboardShortcutsList, MiniScoreboard, MobileHistory, MoveHistory, PITCH_COLS, PITCH_ROWS, PitchMarkings, PitchSurface, PlayerIdentity, REQUIRED_TOKENS, type RequiredToken, Scoreboard, SelectedPieceDetail, StaticGameBoard, TurnBanner, cn, isGoalAreaSquare, pitchSquareClass, useDialogA11y, useGameT };

package/dist/index.d.ts

@@ -15,8 +15,9 @@ interface GameBoardProps {
      * `KeyboardShortcutsList` itself (e.g. in a side panel) so nothing is shown twice.
      */
     toolbar?: boolean;
+    className?: string;
 }
-declare function GameBoard({ userSide, showCoordinates, keyboardNav, toolbar }: GameBoardProps): react.JSX.Element | null;
+declare function GameBoard({ userSide, showCoordinates, keyboardNav, toolbar, className }: GameBoardProps): react.JSX.Element | null;
 
 interface GamePieceProps {
     piece: Piece;
@@ -43,8 +44,9 @@ interface ScoreboardProps {
     creatorAvatarUrl?: string;
     opponentAvatarUrl?: string;
     userSide?: 'white' | 'black' | null;
+    className?: string;
 }
-declare function Scoreboard({ creatorUsername, opponentUsername, creatorAvatarUrl, opponentAvatarUrl, userSide, }: ScoreboardProps): react.JSX.Element | null;
+declare function Scoreboard({ creatorUsername, opponentUsername, creatorAvatarUrl, opponentAvatarUrl, userSide, className, }: ScoreboardProps): react.JSX.Element | null;
 
 interface MiniScoreboardProps {
     creatorUsername: string;
@@ -60,8 +62,9 @@ declare function MiniScoreboard({ creatorUsername, opponentUsername, userSide, c
 
 interface GameControlsProps {
     isMyTurn: boolean;
+    className?: string;
 }
-declare function GameControls({ isMyTurn }: GameControlsProps): react.JSX.Element | null;
+declare function GameControls({ isMyTurn, className }: GameControlsProps): react.JSX.Element | null;
 
 interface SelectedPieceDetailProps {
     isMyTurn: boolean;
@@ -86,7 +89,34 @@ interface MoveHistoryProps {
  */
 declare function MoveHistory({ scrollable, limit, className }: MoveHistoryProps): react.JSX.Element;
 
-declare function StaticGameBoard(): react.JSX.Element;
+declare function StaticGameBoard({ className }?: {
+    className?: string;
+}): react.JSX.Element;
+
+interface PlayerIdentityProps {
+    name: string;
+    team: string;
+    /**
+     * `full` — the side panels and the mobile scoreboard: name on its own line,
+     * team beneath it. `compact` — the tablet/desktop mini-scoreboard, where the
+     * pair shares one line.
+     */
+    variant?: 'full' | 'compact';
+    isActive?: boolean;
+    align?: 'left' | 'right';
+    /** Rendered inline after the team label (e.g. the active-turn pulse dot). */
+    adornment?: React.ReactNode;
+    className?: string;
+}
+/**
+ * One player's name and team.
+ *
+ * `Scoreboard` set this in Inter 13px semibold with the team in mono 10px, and
+ * `MiniScoreboard` in mono 10px uppercase joined by a middot — so the same
+ * player changed appearance on a viewport change. Both now render this, and the
+ * only difference left is the deliberate one: how much room there is.
+ */
+declare function PlayerIdentity({ name, team, variant, isActive, align, adornment, className, }: PlayerIdentityProps): react.JSX.Element;
 
 declare const PITCH_COLS = 9;
 declare const PITCH_ROWS = 12;
@@ -246,6 +276,27 @@ interface ConfirmDialogProps {
 }
 declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, onConfirm, onCancel }: ConfirmDialogProps): react.JSX.Element | null;
 
+/**
+ * Every CSS custom property the package's Tailwind classes resolve against.
+ *
+ * A token the host app does not define fails *silently*: Tailwind emits the
+ * rule, the variable resolves to nothing, and the declaration is dropped. That
+ * is how `--last-move-highlight` went missing in the CrazyGames SPA — the
+ * last-move highlight and the bot's turn replay simply never rendered, with no
+ * error anywhere.
+ *
+ * This is the visual counterpart to `GAME_I18N_KEYS`: assert it in each app.
+ *
+ * ```ts
+ * import { REQUIRED_TOKENS } from '@scriptonita/chess-football-ui'
+ *
+ * const css = readFileSync('src/index.css', 'utf8')
+ * expect(REQUIRED_TOKENS.filter(t => !css.includes(`${t}:`))).toEqual([])
+ * ```
+ */
+declare const REQUIRED_TOKENS: readonly ["--bg-primary", "--bg-secondary", "--bg-surface", "--bg-surface-elevated", "--fg-primary", "--fg-secondary", "--fg-muted", "--accent-green", "--accent-green-light", "--accent-green-dark", "--border-subtle", "--danger", "--warning", "--field-green-1", "--field-green-2", "--field-frame", "--move-highlight", "--pass-highlight", "--last-move-highlight"];
+type RequiredToken = (typeof REQUIRED_TOKENS)[number];
+
 /**
  * A translator scoped to the `game` namespace: `t('yourTurn')`, `t('move')`, …
  * Each host app supplies one bound to its own i18n library:
@@ -259,11 +310,11 @@ type GameTranslator = (key: string, values?: Record<string, unknown>) => string;
  *   grep -rhoE "t\('[a-zA-Z0-9_.]+'" src/components | sed -E "s/t\('//;s/'//" | sort -u
  * (the dynamic `pieces.*` / `eventToast.*` families are derived separately below).
  */
-declare const STATIC_I18N_KEYS: readonly ["actionPointsAriaLabel", "actionPointsShort", "ballHolder", "endTurn", "endTurnConfirm", "endTurnConfirmDescription", "endTurnConfirmYes", "endTurnKeepPlaying", "history.empty", "history.goal", "history.interception", "history.move", "history.offside", "history.pass", "history.tackle", "history.title", "history.turn", "history.viewAll", "move", "offsideWarning", "pass", "selectedPiece.alreadyMoved", "selectedPiece.atSquare", "selectedPiece.empty", "selectedPiece.hasBall", "shortcuts.arrows", "shortcuts.buttonLabel", "shortcuts.cancel", "shortcuts.move", "shortcuts.pass", "shortcuts.select", "shortcuts.title", "teamBlack", "teamWhite", "waitingRival", "yourTurn"];
+declare const STATIC_I18N_KEYS: readonly ["actionPointsAriaLabel", "actionPointsShort", "ballHolder", "boardAriaLabel", "endTurn", "endTurnConfirm", "endTurnConfirmDescription", "endTurnConfirmYes", "endTurnKeepPlaying", "history.empty", "history.goal", "history.interception", "history.move", "history.offside", "history.pass", "history.tackle", "history.title", "history.close", "history.turn", "history.viewAll", "move", "offsideWarning", "pass", "scoreAriaLabel", "selectedPiece.alreadyMoved", "selectedPiece.atSquare", "selectedPiece.empty", "selectedPiece.hasBall", "shortcuts.arrows", "shortcuts.buttonLabel", "shortcuts.cancel", "shortcuts.move", "shortcuts.pass", "shortcuts.select", "shortcuts.title", "square.empty", "square.emptyWithBall", "square.moveOrPassTarget", "square.moveTarget", "square.passTarget", "square.piece", "square.pieceWithBall", "square.selected", "teamBlack", "teamWhite", "waitingRival", "yourTurn"];
 /** `pieces.*` — one key per short and long piece label the engine exposes (move-history, selected-piece-detail). */
 type PieceI18nKey = `pieces.${PieceShortKey | PieceLongKey}`;
 /** `eventToast.*` — one key per toastable event (see `ToastEvent` in `event-toast.tsx`). */
-type EventToastI18nKey = `eventToast.${'interception' | 'offside' | 'tackle'}`;
+type EventToastI18nKey = `eventToast.${'goal' | 'interception' | 'offside' | 'tackle'}`;
 /** Union of every `game`-namespace key the package reads. */
 type GameI18nKey = (typeof STATIC_I18N_KEYS)[number] | PieceI18nKey | EventToastI18nKey;
 /**
@@ -283,4 +334,23 @@ declare function useGameT(): GameTranslator;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { ActionPoints, Avatar, AvatarFallback, AvatarImage, BallHolderChip, Button, type ButtonProps, ConfirmDialog, EventToast, Football, GAME_I18N_KEYS, GOAL_AREA_SHADE_CLASS, GameBoard, GameControls, type GameI18nKey, GameI18nProvider, GamePiece, type GameTranslator, GrassOverlay, KeyboardShortcutsList, MiniScoreboard, MobileHistory, MoveHistory, PITCH_COLS, PITCH_ROWS, PitchMarkings, PitchSurface, Scoreboard, SelectedPieceDetail, StaticGameBoard, TurnBanner, cn, isGoalAreaSquare, pitchSquareClass, useGameT };
+interface DialogA11yOptions {
+    open: boolean;
+    onClose: () => void;
+}
+/**
+ * The four behaviours `aria-modal="true"` promises but does not implement.
+ * Declaring `aria-modal` without them is worse than not declaring it at all:
+ * assistive tech stops exposing the page behind the dialog while the keyboard
+ * happily walks straight into it.
+ *
+ *   1. Initial focus — the first focusable control, or the panel itself.
+ *   2. Focus trap — Tab / Shift+Tab cycle inside the panel.
+ *   3. Escape closes.
+ *   4. Focus returns to whatever opened the dialog.
+ *
+ * Attach the returned ref to the dialog panel (the node carrying `role="dialog"`).
+ */
+declare function useDialogA11y({ open, onClose }: DialogA11yOptions): react.RefObject<HTMLDivElement | null>;
+
+export { ActionPoints, Avatar, AvatarFallback, AvatarImage, BallHolderChip, Button, type ButtonProps, ConfirmDialog, EventToast, Football, GAME_I18N_KEYS, GOAL_AREA_SHADE_CLASS, GameBoard, GameControls, type GameI18nKey, GameI18nProvider, GamePiece, type GameTranslator, GrassOverlay, KeyboardShortcutsList, MiniScoreboard, MobileHistory, MoveHistory, PITCH_COLS, PITCH_ROWS, PitchMarkings, PitchSurface, PlayerIdentity, REQUIRED_TOKENS, type RequiredToken, Scoreboard, SelectedPieceDetail, StaticGameBoard, TurnBanner, cn, isGoalAreaSquare, pitchSquareClass, useDialogA11y, useGameT };