@scriptonita/chess-football-ui 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -9,16 +9,28 @@ interface GameBoardProps {
     showCoordinates?: boolean;
     /** When true, the board is keyboard-operable (arrows move a cursor, Enter acts). */
     keyboardNav?: boolean;
+    /**
+     * Desktop-only row above the grid with the ball-holder chip and the keyboard
+     * shortcuts button. Pass `false` when the app renders `BallHolderChip` and
+     * `KeyboardShortcutsList` itself (e.g. in a side panel) so nothing is shown twice.
+     */
+    toolbar?: boolean;
 }
-declare function GameBoard({ userSide, showCoordinates, keyboardNav }: GameBoardProps): react.JSX.Element | null;
+declare function GameBoard({ userSide, showCoordinates, keyboardNav, toolbar }: GameBoardProps): react.JSX.Element | null;
 
 interface GamePieceProps {
     piece: Piece;
     isSelected: boolean;
     hasBall: boolean;
     onClick: (e: React.MouseEvent) => void;
+    /**
+     * True while the piece is travelling between squares. The chip lifts
+     * slightly and its ground shadow drops away, so the move reads as the
+     * piece being picked up and slid across the turf rather than dragged.
+     */
+    isMoving?: boolean;
 }
-declare function GamePiece({ piece, isSelected, hasBall, onClick }: GamePieceProps): react.JSX.Element;
+declare function GamePiece({ piece, isSelected, hasBall, onClick, isMoving }: GamePieceProps): react.JSX.Element;
 
 interface FootballProps {
     className?: string;
@@ -76,6 +88,71 @@ declare function MoveHistory({ scrollable, limit, className }: MoveHistoryProps)
 
 declare function StaticGameBoard(): react.JSX.Element;
 
+declare const PITCH_COLS = 9;
+declare const PITCH_ROWS = 12;
+/** The two goal boxes: files c–g on the first two and last two ranks. */
+declare const isGoalAreaSquare: (x: number, y: number) => boolean;
+/**
+ * Goal-box shading: an inset box-shadow that darkens the square *over* its own
+ * green, so the box reads as a distinct zone (the king's area) while the
+ * checkerboard alternation stays visible — opponents enter it square by square
+ * and need to read their moves there. An inset shadow (rather than a flat
+ * replacement colour) keeps the app's tokens in charge of the hue and composes
+ * with Tailwind's `ring-*` utilities on the live board's highlighted squares.
+ */
+declare const GOAL_AREA_SHADE_CLASS = "shadow-[inset_0_0_0_100vmax_rgba(0,0,0,0.32)]";
+/**
+ * Base classes of one pitch square. Every board renderer — the live GameBoard,
+ * StaticGameBoard, and any app-side mini board built on PitchSurface — derives
+ * its squares from here, so the field reads identically everywhere. Colours
+ * come from the app's `field-green-*` design tokens.
+ */
+declare function pitchSquareClass(x: number, y: number): string;
+interface GrassOverlayProps {
+    className?: string;
+}
+/**
+ * Decorative turf texture for the pitch. Absolutely positioned over the square
+ * grid and click-through, so it sits between the squares and the pieces without
+ * affecting hit-testing or the per-square highlight classes.
+ */
+declare function GrassOverlay({ className }: GrassOverlayProps): react.JSX.Element;
+interface PitchMarkingsProps {
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * The painted pitch lines — touchline, goal boxes, halfway line, centre circle,
+ * spots and the two "D" arcs — drawn to look like chalk on grass: a roughened,
+ * slightly displaced edge and a noise-driven alpha so the coverage is powdery
+ * rather than a crisp vector stroke. A faint, wider unfiltered pass underneath
+ * acts as the dust halo the line leaves on the turf.
+ *
+ * Static and cached by the browser as its own layer; anything dynamic that
+ * shares the board's coordinate space (e.g. the pass-trajectory preview) should
+ * live in a separate <svg> so a hover repaint never re-runs this filter.
+ */
+declare function PitchMarkings({ className, children }: PitchMarkingsProps): react.JSX.Element;
+interface PitchSurfaceProps {
+    className?: string;
+    /**
+     * Extra classes for a given square (e.g. a highlighted area in a rules
+     * diagram). Falsy return values are ignored.
+     */
+    squareClassName?: (x: number, y: number) => string | false | null | undefined;
+    /** Layers rendered above the markings — pieces, ball, overlays. */
+    children?: React.ReactNode;
+}
+/**
+ * The complete, non-interactive pitch: squares, turf grain and chalk lines, in
+ * that order, inside a container-query wrapper so pieces can size themselves
+ * with `cqw`. Callers put their own frame (border/radius) around it and their
+ * own piece layer inside it. The interactive GameBoard renders its own square
+ * grid (it needs per-square handlers) but builds every square from the same
+ * `pitchSquareClass`, and stacks the same GrassOverlay + PitchMarkings.
+ */
+declare function PitchSurface({ className, squareClassName, children }: PitchSurfaceProps): react.JSX.Element;
+
 interface TurnBannerProps {
     isMyTurn: boolean;
     /** Override for the "not my turn" label (e.g. "Bot pensando…" in training mode). */
@@ -101,6 +178,29 @@ interface MobileHistoryProps {
 }
 declare function MobileHistory({ className }: MobileHistoryProps): react.JSX.Element | null;
 
+interface BallHolderChipProps {
+    className?: string;
+}
+/**
+ * §12b: a persistent, always-visible answer to "whose ball is it" — the piece
+ * type currently holding the ball, drawn as a mini chip. Additive to the subtle
+ * per-piece ring on the board. Renders nothing while the ball is loose.
+ *
+ * GameBoard shows it in its own toolbar by default; apps with a side panel can
+ * pass `toolbar={false}` to the board and place this chip wherever it reads best.
+ */
+declare function BallHolderChip({ className }: BallHolderChipProps): react.JSX.Element | null;
+
+interface KeyboardShortcutsListProps {
+    className?: string;
+}
+/**
+ * §12: the legend of the board's keyboard shortcuts. GameBoard shows it in a
+ * popover behind a "?" button in its toolbar; apps that pass `toolbar={false}`
+ * can render the list inline in a side panel instead.
+ */
+declare function KeyboardShortcutsList({ className }: KeyboardShortcutsListProps): react.JSX.Element;
+
 interface ActionPointsProps {
     total: number;
     remaining: number;
@@ -183,4 +283,4 @@ declare function useGameT(): GameTranslator;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { ActionPoints, Avatar, AvatarFallback, AvatarImage, Button, type ButtonProps, ConfirmDialog, EventToast, Football, GAME_I18N_KEYS, GameBoard, GameControls, type GameI18nKey, GameI18nProvider, GamePiece, type GameTranslator, MiniScoreboard, MobileHistory, MoveHistory, Scoreboard, SelectedPieceDetail, StaticGameBoard, TurnBanner, cn, useGameT };
+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 };

package/dist/index.d.ts

@@ -9,16 +9,28 @@ interface GameBoardProps {
     showCoordinates?: boolean;
     /** When true, the board is keyboard-operable (arrows move a cursor, Enter acts). */
     keyboardNav?: boolean;
+    /**
+     * Desktop-only row above the grid with the ball-holder chip and the keyboard
+     * shortcuts button. Pass `false` when the app renders `BallHolderChip` and
+     * `KeyboardShortcutsList` itself (e.g. in a side panel) so nothing is shown twice.
+     */
+    toolbar?: boolean;
 }
-declare function GameBoard({ userSide, showCoordinates, keyboardNav }: GameBoardProps): react.JSX.Element | null;
+declare function GameBoard({ userSide, showCoordinates, keyboardNav, toolbar }: GameBoardProps): react.JSX.Element | null;
 
 interface GamePieceProps {
     piece: Piece;
     isSelected: boolean;
     hasBall: boolean;
     onClick: (e: React.MouseEvent) => void;
+    /**
+     * True while the piece is travelling between squares. The chip lifts
+     * slightly and its ground shadow drops away, so the move reads as the
+     * piece being picked up and slid across the turf rather than dragged.
+     */
+    isMoving?: boolean;
 }
-declare function GamePiece({ piece, isSelected, hasBall, onClick }: GamePieceProps): react.JSX.Element;
+declare function GamePiece({ piece, isSelected, hasBall, onClick, isMoving }: GamePieceProps): react.JSX.Element;
 
 interface FootballProps {
     className?: string;
@@ -76,6 +88,71 @@ declare function MoveHistory({ scrollable, limit, className }: MoveHistoryProps)
 
 declare function StaticGameBoard(): react.JSX.Element;
 
+declare const PITCH_COLS = 9;
+declare const PITCH_ROWS = 12;
+/** The two goal boxes: files c–g on the first two and last two ranks. */
+declare const isGoalAreaSquare: (x: number, y: number) => boolean;
+/**
+ * Goal-box shading: an inset box-shadow that darkens the square *over* its own
+ * green, so the box reads as a distinct zone (the king's area) while the
+ * checkerboard alternation stays visible — opponents enter it square by square
+ * and need to read their moves there. An inset shadow (rather than a flat
+ * replacement colour) keeps the app's tokens in charge of the hue and composes
+ * with Tailwind's `ring-*` utilities on the live board's highlighted squares.
+ */
+declare const GOAL_AREA_SHADE_CLASS = "shadow-[inset_0_0_0_100vmax_rgba(0,0,0,0.32)]";
+/**
+ * Base classes of one pitch square. Every board renderer — the live GameBoard,
+ * StaticGameBoard, and any app-side mini board built on PitchSurface — derives
+ * its squares from here, so the field reads identically everywhere. Colours
+ * come from the app's `field-green-*` design tokens.
+ */
+declare function pitchSquareClass(x: number, y: number): string;
+interface GrassOverlayProps {
+    className?: string;
+}
+/**
+ * Decorative turf texture for the pitch. Absolutely positioned over the square
+ * grid and click-through, so it sits between the squares and the pieces without
+ * affecting hit-testing or the per-square highlight classes.
+ */
+declare function GrassOverlay({ className }: GrassOverlayProps): react.JSX.Element;
+interface PitchMarkingsProps {
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * The painted pitch lines — touchline, goal boxes, halfway line, centre circle,
+ * spots and the two "D" arcs — drawn to look like chalk on grass: a roughened,
+ * slightly displaced edge and a noise-driven alpha so the coverage is powdery
+ * rather than a crisp vector stroke. A faint, wider unfiltered pass underneath
+ * acts as the dust halo the line leaves on the turf.
+ *
+ * Static and cached by the browser as its own layer; anything dynamic that
+ * shares the board's coordinate space (e.g. the pass-trajectory preview) should
+ * live in a separate <svg> so a hover repaint never re-runs this filter.
+ */
+declare function PitchMarkings({ className, children }: PitchMarkingsProps): react.JSX.Element;
+interface PitchSurfaceProps {
+    className?: string;
+    /**
+     * Extra classes for a given square (e.g. a highlighted area in a rules
+     * diagram). Falsy return values are ignored.
+     */
+    squareClassName?: (x: number, y: number) => string | false | null | undefined;
+    /** Layers rendered above the markings — pieces, ball, overlays. */
+    children?: React.ReactNode;
+}
+/**
+ * The complete, non-interactive pitch: squares, turf grain and chalk lines, in
+ * that order, inside a container-query wrapper so pieces can size themselves
+ * with `cqw`. Callers put their own frame (border/radius) around it and their
+ * own piece layer inside it. The interactive GameBoard renders its own square
+ * grid (it needs per-square handlers) but builds every square from the same
+ * `pitchSquareClass`, and stacks the same GrassOverlay + PitchMarkings.
+ */
+declare function PitchSurface({ className, squareClassName, children }: PitchSurfaceProps): react.JSX.Element;
+
 interface TurnBannerProps {
     isMyTurn: boolean;
     /** Override for the "not my turn" label (e.g. "Bot pensando…" in training mode). */
@@ -101,6 +178,29 @@ interface MobileHistoryProps {
 }
 declare function MobileHistory({ className }: MobileHistoryProps): react.JSX.Element | null;
 
+interface BallHolderChipProps {
+    className?: string;
+}
+/**
+ * §12b: a persistent, always-visible answer to "whose ball is it" — the piece
+ * type currently holding the ball, drawn as a mini chip. Additive to the subtle
+ * per-piece ring on the board. Renders nothing while the ball is loose.
+ *
+ * GameBoard shows it in its own toolbar by default; apps with a side panel can
+ * pass `toolbar={false}` to the board and place this chip wherever it reads best.
+ */
+declare function BallHolderChip({ className }: BallHolderChipProps): react.JSX.Element | null;
+
+interface KeyboardShortcutsListProps {
+    className?: string;
+}
+/**
+ * §12: the legend of the board's keyboard shortcuts. GameBoard shows it in a
+ * popover behind a "?" button in its toolbar; apps that pass `toolbar={false}`
+ * can render the list inline in a side panel instead.
+ */
+declare function KeyboardShortcutsList({ className }: KeyboardShortcutsListProps): react.JSX.Element;
+
 interface ActionPointsProps {
     total: number;
     remaining: number;
@@ -183,4 +283,4 @@ declare function useGameT(): GameTranslator;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { ActionPoints, Avatar, AvatarFallback, AvatarImage, Button, type ButtonProps, ConfirmDialog, EventToast, Football, GAME_I18N_KEYS, GameBoard, GameControls, type GameI18nKey, GameI18nProvider, GamePiece, type GameTranslator, MiniScoreboard, MobileHistory, MoveHistory, Scoreboard, SelectedPieceDetail, StaticGameBoard, TurnBanner, cn, useGameT };
+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 };