@scriptonita/chess-football-ui 0.7.0 → 0.8.0

package/README.md

@@ -35,6 +35,27 @@ npm install @scriptonita/chess-football-ui
   (`bg-bg-surface`, `text-accent-green`, …). Each app must define those tokens and include this
   package's files in its Tailwind `content`/`@source` scan so the classes are generated.
 
+## Host app contract
+
+Two things the package cannot enforce at build time and every consumer must check:
+
+**1. Translation coverage.** `GAME_I18N_KEYS` is the manifest of every `game`-namespace key
+the components read. Assert it in each app's test suite — without this, a key added here
+surfaces as raw text on the pitch (`⚠ game.offsideWarning`) instead of failing CI:
+
+```ts
+import { GAME_I18N_KEYS } from '@scriptonita/chess-football-ui'
+import es from './messages/es.json'
+
+const missing = GAME_I18N_KEYS.filter(k => !k.split('.').reduce<any>((o, p) => o?.[p], es.game))
+expect(missing).toEqual([])
+```
+
+**2. Design tokens.** Components emit Tailwind classes bound to tokens the app defines. A
+token that is missing fails silently — the rule simply does not apply. The board's
+`--last-move-highlight`, `--move-highlight`, `--pass-highlight`, `--accent-green`,
+`--accent-green-light` and `--accent-green-dark` are all required.
+
 ## Peer dependencies
 
 `react`, `react-dom`, `framer-motion`, `lucide-react`.

package/dist/index.cjs

@@ -190,6 +190,7 @@ var STATIC_I18N_KEYS = [
   "actionPointsAriaLabel",
   "actionPointsShort",
   "ballHolder",
+  "boardAriaLabel",
   "endTurn",
   "endTurnConfirm",
   "endTurnConfirmDescription",
@@ -203,11 +204,13 @@ var STATIC_I18N_KEYS = [
   "history.pass",
   "history.tackle",
   "history.title",
+  "history.close",
   "history.turn",
   "history.viewAll",
   "move",
   "offsideWarning",
   "pass",
+  "scoreAriaLabel",
   "selectedPiece.alreadyMoved",
   "selectedPiece.atSquare",
   "selectedPiece.empty",
@@ -219,6 +222,14 @@ var STATIC_I18N_KEYS = [
   "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",
@@ -228,6 +239,7 @@ var PIECE_I18N_KEYS = [...Object.values(chessFootballEngine.SHORT_KEY), ...Objec
   (label) => `pieces.${label}`
 );
 var EVENT_TOAST_I18N_KEYS = [
+  "eventToast.goal",
   "eventToast.interception",
   "eventToast.offside",
   "eventToast.tackle"
@@ -237,7 +249,13 @@ var GAME_I18N_KEYS = [
   ...PIECE_I18N_KEYS,
   ...EVENT_TOAST_I18N_KEYS
 ];
-var fallback = (key) => key;
+var nodeEnv = globalThis.process?.env?.NODE_ENV;
+var fallback = (key) => {
+  if (nodeEnv && nodeEnv !== "production") {
+    console.warn(`[chess-football-ui] missing game i18n key: "${key}" (no GameI18nProvider?)`);
+  }
+  return key;
+};
 var GameI18nContext = React.createContext(fallback);
 function GameI18nProvider({ t, children }) {
   return /* @__PURE__ */ jsxRuntime.jsx(GameI18nContext.Provider, { value: t, children: /* @__PURE__ */ jsxRuntime.jsx(framerMotion.MotionConfig, { reducedMotion: "user", children }) });
@@ -444,6 +462,7 @@ var PIECE_SLIDE = { type: "spring", stiffness: 190, damping: 28, mass: 1 };
 var BALL_SLIDE = { type: "spring", stiffness: 300, damping: 26, mass: 0.6 };
 function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, toolbar = true }) {
   const t = useGameT();
+  const boardId = React.useId();
   const prefersReducedMotion = framerMotion.useReducedMotion();
   const {
     boardState,
@@ -674,9 +693,28 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
         break;
     }
   };
-  const renderSquares = () => {
-    const squares = [];
+  const cellId = (x, y) => `${boardId}-sq-${x}-${y}`;
+  const squareLabel = (x, y, pieceAt, isValidMove, isValidPass) => {
+    const square = chessFootballEngine.squareName({ x, y });
+    const ballHere = ball.pos.x === x && ball.pos.y === y;
+    const parts = [];
+    if (pieceAt) {
+      const piece = t(`pieces.${chessFootballEngine.LONG_KEY[pieceAt.type]}`);
+      const team = pieceAt.side === "white" ? t("teamWhite") : t("teamBlack");
+      parts.push(t(ballHere ? "square.pieceWithBall" : "square.piece", { square, piece, team }));
+    } else {
+      parts.push(t(ballHere ? "square.emptyWithBall" : "square.empty", { square }));
+    }
+    if (isValidMove && isValidPass) parts.push(t("square.moveOrPassTarget"));
+    else if (isValidMove) parts.push(t("square.moveTarget"));
+    else if (isValidPass) parts.push(t("square.passTarget"));
+    if (pieceAt && pieceAt.id === selectedPieceId) parts.push(t("square.selected"));
+    return parts.join(", ");
+  };
+  const renderRows = () => {
+    const rows = [];
     for (let y = ROWS - 1; y >= 0; y--) {
+      const squares = [];
       for (let x = 0; x < COLS; x++) {
         const isValidMove = validMoves.some((m) => m.x === x && m.y === y);
         const isValidPass = validPasses.some((p) => p.x === x && p.y === y);
@@ -693,6 +731,10 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
           /* @__PURE__ */ jsxRuntime.jsxs(
             "div",
             {
+              id: cellId(x, y),
+              role: "gridcell",
+              "aria-label": squareLabel(x, y, pieceAt, isValidMove, isValidPass),
+              "aria-selected": !!pieceAt && pieceAt.id === selectedPieceId,
               onClick: () => handleSquareClick(x, y),
               onMouseEnter: () => {
                 if (isValidPass) setHoveredPassAt({ x, y });
@@ -766,26 +808,23 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
           )
         );
       }
+      rows.push(
+        /* @__PURE__ */ jsxRuntime.jsx("div", { role: "row", className: "contents", children: squares }, `row-${y}`)
+      );
     }
-    return squares;
+    return rows;
   };
   const board = /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
+      "data-testid": "board-root",
       className: cn(
         // §6: Mobile edge-to-edge — thin 2px margin, no border, no radius
         "w-full mx-0.5 bg-[#1a3317] overflow-hidden",
         // §5+§6: Desktop — centered, rounded, bordered, height-based max-width
         "md:mx-auto md:rounded-xl md:shadow-2xl md:border-4 md:border-[#1a3317]",
-        "md:max-w-[min(700px,calc((100dvh_-_150px)*0.75))]",
-        keyboardNav && "focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-green focus-visible:ring-offset-2 focus-visible:ring-offset-bg-primary"
+        "md:max-w-[min(700px,calc((100dvh_-_150px)*0.75))]"
       ),
-      ...keyboardNav ? {
-        tabIndex: 0,
-        role: "application",
-        "aria-label": "Game board \u2014 arrow keys to move the cursor, Enter to act",
-        onKeyDown: handleKeyDown
-      } : {},
       children: [
         toolbar && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "hidden md:flex items-center justify-between gap-2 px-2.5 py-1", "data-testid": "board-toolbar", children: [
           /* @__PURE__ */ jsxRuntime.jsx(BallHolderChip, {}),
@@ -794,7 +833,12 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
             {
               ref: shortcutsRef,
               className: "relative",
-              onKeyDown: (e) => e.stopPropagation(),
+              onKeyDown: (e) => {
+                if (e.key === "Escape" && shortcutsOpen) {
+                  e.stopPropagation();
+                  setShortcutsOpen(false);
+                }
+              },
               children: [
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "button",
@@ -826,7 +870,25 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
           )
         ] }),
         /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative", style: { containerType: "inline-size" }, children: [
-          /* @__PURE__ */ jsxRuntime.jsx("div", { className: "grid grid-cols-9 gap-[1px]", children: renderSquares() }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "div",
+            {
+              role: "grid",
+              "aria-label": t("boardAriaLabel"),
+              "aria-rowcount": ROWS,
+              "aria-colcount": COLS,
+              className: cn(
+                "grid grid-cols-9 gap-[1px]",
+                keyboardNav && "focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-accent-green"
+              ),
+              ...keyboardNav ? {
+                tabIndex: 0,
+                onKeyDown: handleKeyDown,
+                "aria-activedescendant": cursor ? cellId(cursor.x, cursor.y) : void 0
+              } : {},
+              children: renderRows()
+            }
+          ),
           /* @__PURE__ */ jsxRuntime.jsx(GrassOverlay, {}),
           /* @__PURE__ */ jsxRuntime.jsx(PitchMarkings, {}),
           /* @__PURE__ */ jsxRuntime.jsx(
@@ -852,7 +914,7 @@ function GameBoard({ userSide, showCoordinates = false, keyboardNav = true, tool
               )
             }
           ),
-          /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "absolute inset-0 pointer-events-none", "data-testid": "pieces-layer", children: [
+          /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "absolute inset-0 pointer-events-none", "data-testid": "pieces-layer", "aria-hidden": "true", children: [
             /* @__PURE__ */ jsxRuntime.jsx(framerMotion.AnimatePresence, { mode: "sync", children: boardState.pieces.map((piece) => {
               const isPickupCarrier = pickupCarrierId === piece.id;
               const pieceTransition = isPickupCarrier ? { duration: PICKUP_DURATION, ease: "linear" } : PIECE_SLIDE;
@@ -1087,10 +1149,11 @@ function Scoreboard({
         align: "left"
       }
     ),
-    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-3", children: [
-      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-anton text-[32px] leading-none text-fg-primary tabular-nums", children: myScore }),
-      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-anton text-2xl text-fg-muted", children: "\u2014" }),
-      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-anton text-[32px] leading-none text-fg-primary tabular-nums", children: rivalScore })
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { role: "status", "aria-live": "polite", "aria-atomic": "true", className: "flex items-center gap-3", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", className: "font-anton text-[32px] leading-none text-fg-primary tabular-nums", children: myScore }),
+      /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", className: "font-anton text-2xl text-fg-muted", children: "\u2014" }),
+      /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", className: "font-anton text-[32px] leading-none text-fg-primary tabular-nums", children: rivalScore }),
+      /* @__PURE__ */ jsxRuntime.jsx("span", { className: "sr-only", children: t("scoreAriaLabel", { me: myName, myScore, rival: rivalName, rivalScore }) })
     ] }),
     /* @__PURE__ */ jsxRuntime.jsx(
       PlayerInfo,
@@ -1158,15 +1221,21 @@ function MiniScoreboard({
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
+      role: "status",
+      "aria-live": "polite",
+      "aria-atomic": "true",
       className: cn(
         "w-full max-w-[540px] rounded-xl bg-bg-surface border border-border-subtle",
         "flex items-center justify-between gap-4 px-5 py-3",
         className
       ),
       children: [
-        /* @__PURE__ */ jsxRuntime.jsx(SideCell, { name: myName, team: myTeam, score: myScore, isActive: isMyTurn, align: "left" }),
-        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-anton text-base text-fg-muted uppercase tracking-[2px]", "aria-hidden": "true", children: "vs" }),
-        /* @__PURE__ */ jsxRuntime.jsx(SideCell, { name: rivalName, team: rivalTeam, score: rivalScore, isActive: !isMyTurn, align: "right" })
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "contents", "aria-hidden": "true", children: [
+          /* @__PURE__ */ jsxRuntime.jsx(SideCell, { name: myName, team: myTeam, score: myScore, isActive: isMyTurn, align: "left" }),
+          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-anton text-base text-fg-muted uppercase tracking-[2px]", children: "vs" }),
+          /* @__PURE__ */ jsxRuntime.jsx(SideCell, { name: rivalName, team: rivalTeam, score: rivalScore, isActive: !isMyTurn, align: "right" })
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "sr-only", children: t("scoreAriaLabel", { me: myName, myScore, rival: rivalName, rivalScore }) })
       ]
     }
   );
@@ -1188,7 +1257,12 @@ function SideCell({ name, team, score, isActive, align }) {
   ] });
 }
 var VARIANT = {
-  primary: "bg-accent-green text-fg-primary font-anton tracking-widest rounded-md hover:bg-accent-green-light active:bg-accent-green-dark",
+  // White on `--accent-green` is 4.27:1 — under WCAG AA for the Anton 400 the
+  // primary CTA is set in. `--accent-green-dark` clears it (~6.5:1), so the
+  // resting state is the dark green and interaction brightens it rather than
+  // darkening it. Hover/active are transient; the resting state is the one a
+  // player reads.
+  primary: "bg-accent-green-dark text-fg-primary font-anton tracking-widest rounded-md hover:bg-accent-green active:bg-accent-green-light",
   secondary: "bg-bg-surface text-fg-primary font-inter font-semibold rounded-md border border-border-subtle hover:bg-bg-surface-elevated active:bg-bg-secondary",
   ghost: "bg-transparent text-fg-secondary font-inter font-medium rounded-md hover:text-fg-primary active:text-fg-muted",
   destructive: "bg-danger/10 text-danger font-inter font-semibold rounded-md border border-danger hover:bg-danger/20 active:bg-danger/30"
@@ -1218,24 +1292,97 @@ var Button = React__namespace.forwardRef(
   )
 );
 Button.displayName = "Button";
+var FOCUSABLE = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])'
+].join(",");
+function focusableWithin(panel) {
+  return Array.from(panel.querySelectorAll(FOCUSABLE)).filter(
+    (el) => !el.closest("[hidden]") && !el.closest('[aria-hidden="true"]')
+  );
+}
+function useDialogA11y({ open, onClose }) {
+  const panelRef = React.useRef(null);
+  const restoreToRef = React.useRef(null);
+  const onCloseRef = React.useRef(onClose);
+  React.useEffect(() => {
+    onCloseRef.current = onClose;
+  });
+  React.useEffect(() => {
+    if (!open) return;
+    const panel = panelRef.current;
+    if (!panel) return;
+    restoreToRef.current = document.activeElement;
+    const initial = focusableWithin(panel)[0];
+    if (initial) {
+      initial.focus();
+    } else {
+      panel.tabIndex = -1;
+      panel.focus();
+    }
+    const onKeyDown = (e) => {
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        onCloseRef.current();
+        return;
+      }
+      if (e.key !== "Tab") return;
+      const items = focusableWithin(panel);
+      if (items.length === 0) {
+        e.preventDefault();
+        return;
+      }
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey && (active === first || !panel.contains(active))) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && (active === last || !panel.contains(active))) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", onKeyDown, true);
+    return () => {
+      document.removeEventListener("keydown", onKeyDown, true);
+      restoreToRef.current?.focus?.();
+    };
+  }, [open]);
+  return panelRef;
+}
 function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, onConfirm, onCancel }) {
+  const baseId = React.useId();
+  const titleId = `${baseId}-title`;
+  const descId = `${baseId}-desc`;
+  const panelRef = useDialogA11y({ open, onClose: onCancel });
   if (!open) return null;
   return /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
       className: "fixed inset-0 z-50 flex items-center justify-center bg-black/60 backdrop-blur-sm",
-      role: "dialog",
-      "aria-modal": "true",
+      onClick: onCancel,
       children: /* @__PURE__ */ jsxRuntime.jsxs(
         "div",
         {
+          ref: panelRef,
+          role: "dialog",
+          "aria-modal": "true",
+          "aria-labelledby": titleId,
+          "aria-describedby": description ? descId : void 0,
+          onClick: (e) => e.stopPropagation(),
           className: cn(
             "bg-bg-surface border border-border-subtle rounded-xl p-6 mx-4 max-w-sm w-full",
-            "flex flex-col gap-4 shadow-2xl"
+            "flex flex-col gap-4 shadow-2xl",
+            "focus:outline-none"
           ),
           children: [
-            /* @__PURE__ */ jsxRuntime.jsx("h2", { className: "font-anton text-lg text-fg-primary uppercase tracking-wide", children: title }),
-            description && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "font-inter text-sm text-fg-secondary", children: description }),
+            /* @__PURE__ */ jsxRuntime.jsx("h2", { id: titleId, className: "font-anton text-lg text-fg-primary uppercase tracking-wide", children: title }),
+            description && /* @__PURE__ */ jsxRuntime.jsx("p", { id: descId, className: "font-inter text-sm text-fg-secondary", children: description }),
             /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex gap-2 pt-1", children: [
               /* @__PURE__ */ jsxRuntime.jsx(Button, { variant: "secondary", className: "flex-1", onClick: onCancel, children: cancelLabel }),
               /* @__PURE__ */ jsxRuntime.jsx(Button, { variant: "primary", className: "flex-1", onClick: onConfirm, children: confirmLabel })
@@ -1561,8 +1708,9 @@ function TurnBanner({ isMyTurn, waitingLabel, className }) {
     }
   );
 }
-var TOASTABLE = /* @__PURE__ */ new Set(["interception", "offside", "tackle"]);
+var TOASTABLE = /* @__PURE__ */ new Set(["goal", "interception", "offside", "tackle"]);
 var TOAST_CONFIG = {
+  goal: "bg-accent-green/20 border-accent-green/60 text-accent-green-light",
   interception: "bg-danger/20 border-danger/50 text-danger",
   offside: "bg-warning/20 border-warning/50 text-warning",
   tackle: "bg-warning/20 border-warning/50 text-warning"
@@ -1610,6 +1758,8 @@ function EventToast({ className }) {
 function MobileHistory({ className }) {
   const { boardState } = chunkLTFNSTAQ_cjs.useGameStore();
   const [open, setOpen] = React.useState(false);
+  const titleId = `${React.useId()}-title`;
+  const panelRef = useDialogA11y({ open, onClose: () => setOpen(false) });
   const lastMove = boardState?.moveHistory?.at(-1);
   if (!lastMove) return null;
   return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
@@ -1635,11 +1785,13 @@ function MobileHistory({ className }) {
           animate: { y: 0 },
           exit: { y: "100%" },
           transition: { type: "spring", stiffness: 300, damping: 32 },
-          className: "fixed bottom-0 left-0 right-0 z-50 bg-bg-secondary rounded-t-2xl border-t border-border-subtle shadow-xl",
+          ref: panelRef,
+          className: "fixed bottom-0 left-0 right-0 z-50 bg-bg-secondary rounded-t-2xl border-t border-border-subtle shadow-xl focus:outline-none",
           role: "dialog",
           "aria-modal": "true",
+          "aria-labelledby": titleId,
           children: [
-            /* @__PURE__ */ jsxRuntime.jsx(SheetHeader, { onClose: () => setOpen(false) }),
+            /* @__PURE__ */ jsxRuntime.jsx(SheetHeader, { titleId, onClose: () => setOpen(false) }),
             /* @__PURE__ */ jsxRuntime.jsx("div", { className: "px-4 pb-6 max-h-[50dvh] overflow-y-auto", children: /* @__PURE__ */ jsxRuntime.jsx(MoveHistory, { scrollable: false }) })
           ]
         },
@@ -1648,17 +1800,17 @@ function MobileHistory({ className }) {
     ] }) })
   ] });
 }
-function SheetHeader({ onClose }) {
+function SheetHeader({ titleId, onClose }) {
   const t = useGameT();
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center justify-between px-5 pt-4 pb-3 border-b border-border-subtle", children: [
-    /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-mono text-[10px] tracking-[0.5px] uppercase text-fg-muted", children: t("history.title") }),
+    /* @__PURE__ */ jsxRuntime.jsx("span", { id: titleId, className: "font-mono text-[10px] tracking-[0.5px] uppercase text-fg-muted", children: t("history.title") }),
     /* @__PURE__ */ jsxRuntime.jsx(
       "button",
       {
         onClick: onClose,
         className: "w-8 h-8 flex items-center justify-center rounded-full bg-bg-surface hover:bg-bg-surface-elevated text-fg-muted hover:text-fg-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-green",
-        "aria-label": "Close",
-        children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.X, { size: 14 })
+        "aria-label": t("history.close"),
+        children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.X, { size: 14, "aria-hidden": "true" })
       }
     )
   ] });
@@ -1742,6 +1894,7 @@ exports.TurnBanner = TurnBanner;
 exports.cn = cn;
 exports.isGoalAreaSquare = isGoalAreaSquare;
 exports.pitchSquareClass = pitchSquareClass;
+exports.useDialogA11y = useDialogA11y;
 exports.useGameT = useGameT;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map