@my-games/sudoku-react 0.0.0 → 0.1.0

package/src/GameSudoku.tsx

@@ -1,15 +1,351 @@
-// 0.0.0 空骨架占位组件：仅 import core 样式以让 vite lib build 抽出非空
-// dist/index.css（verify:dist 守卫要求）。真实棋盘/输入/提示 UI 随引擎补入。
+import {
+  type CSSProperties,
+  type ReactNode,
+  type Ref,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState
+} from 'react';
 import '@my-games/sudoku-core/style.css';
+import type { Difficulty, Digit, GameState, SaveStorage } from '@my-games/sudoku-core';
+import { useGame } from './useGame';
+
+/**
+ * GameSudoku —— React 18/19 组件，行为与 Vue 版对齐。
+ * 键盘：数字 1-9 填数 / N 切笔记 / Backspace·Delete 擦除 / 方向键移动选中；
+ * 严格判 `document.activeElement === board`，多实例并存只活动那个响应。
+ */
 
 export interface GameSudokuProps {
+  difficulty?: Difficulty;
+  storage?: SaveStorage | null;
+  saveKey?: string;
+  bestKey?: string;
+  freshStart?: boolean;
+  autofocus?: boolean;
+  showPad?: boolean;
   title?: string;
+  className?: string;
+  showHint?: boolean;
+  onDigit?: (digit: Digit, changed: boolean) => void;
+  onSolved?: (payload: { difficulty: Difficulty; seconds: number }) => void;
+}
+
+export interface GameSudokuHandle {
+  select(row: number, col: number): void;
+  input(digit: Digit): boolean;
+  erase(): boolean;
+  toggleNote(digit: Digit): boolean;
+  hint(): boolean;
+  newGame(difficulty?: Difficulty): void;
+  undo(): boolean;
+}
+
+const PAD_DIGITS: Digit[] = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+const DIFFS: Array<{ key: Difficulty; label: string }> = [
+  { key: 'easy', label: '简单' },
+  { key: 'medium', label: '中等' },
+  { key: 'hard', label: '困难' }
+];
+
+/** 9 宫 × 9 格的全局坐标映射。 */
+const BOXES: Array<Array<{ row: number; col: number }>> = (() => {
+  const out: Array<Array<{ row: number; col: number }>> = [];
+  for (let bi = 0; bi < 9; bi++) {
+    const cells: Array<{ row: number; col: number }> = [];
+    for (let ci = 0; ci < 9; ci++) {
+      cells.push({
+        row: Math.floor(bi / 3) * 3 + Math.floor(ci / 3),
+        col: (bi % 3) * 3 + (ci % 3)
+      });
+    }
+    out.push(cells);
+  }
+  return out;
+})();
+
+function formatTime(totalSeconds: number): string {
+  const m = Math.floor(totalSeconds / 60);
+  const s = totalSeconds % 60;
+  return `${m}:${String(s).padStart(2, '0')}`;
+}
+
+function cellValueOf(state: GameState, row: number, col: number): number {
+  return state.grid[row]?.[col] ?? 0;
+}
+
+function cellClass(state: GameState, row: number, col: number): string {
+  const v = cellValueOf(state, row, col);
+  const given = state.givenMask[row]?.[col] ?? false;
+  const sel = state.selected;
+  const cls = ['game-sudoku-cell'];
+  if (given) cls.push('is-given');
+  else if (v !== 0) cls.push('is-user');
+  if (state.conflicts[row]?.[col]) cls.push('is-conflict');
+  if (sel && sel.row === row && sel.col === col) {
+    cls.push('is-selected');
+  } else if (sel) {
+    const sameBox =
+      Math.floor(sel.row / 3) === Math.floor(row / 3) &&
+      Math.floor(sel.col / 3) === Math.floor(col / 3);
+    if (sel.row === row || sel.col === col || sameBox) cls.push('is-peer');
+    const selVal = cellValueOf(state, sel.row, sel.col);
+    if (v !== 0 && v === selVal) cls.push('is-same');
+  }
+  return cls.join(' ');
+}
+
+function cellNotesOf(state: GameState, row: number, col: number): Digit[] {
+  return cellValueOf(state, row, col) === 0 ? (state.notes[row]?.[col] ?? []) : [];
 }
 
-export function GameSudoku({ title = 'Sudoku' }: GameSudokuProps) {
+function GameSudokuInner(props: GameSudokuProps, ref: Ref<GameSudokuHandle>) {
+  const {
+    difficulty = 'easy',
+    storage,
+    saveKey,
+    bestKey,
+    freshStart = false,
+    autofocus = true,
+    showPad = true,
+    title = '数独',
+    className,
+    showHint = false,
+    onDigit,
+    onSolved
+  } = props;
+
+  const { state, game, select, input, erase, toggleNote, hint, newGame, undo } = useGame({
+    difficulty,
+    storage,
+    saveKey,
+    bestKey,
+    freshStart
+  });
+
+  const boardRef = useRef<HTMLDivElement>(null);
+  const [noteMode, setNoteMode] = useState(false);
+  // 用时每秒刷新：core 只在操作时推快照，tick 触发重绘后由 game.getState() 读实时值。
+  const [, setTick] = useState(0);
+  useEffect(() => {
+    if (state.status !== 'playing') return;
+    const id = window.setInterval(() => setTick((t) => t + 1), 1000);
+    return () => window.clearInterval(id);
+  }, [state.status]);
+
+  const applyDigit = useCallback(
+    (digit: Digit) => {
+      const changed = noteMode ? toggleNote(digit) : input(digit);
+      if (!noteMode) onDigit?.(digit, changed);
+    },
+    [noteMode, toggleNote, input, onDigit]
+  );
+
+  const handleKey = useCallback(
+    (ev: KeyboardEvent) => {
+      if (document.activeElement !== boardRef.current) return;
+      if (/^[1-9]$/.test(ev.key)) {
+        applyDigit(Number(ev.key) as Digit);
+        ev.preventDefault();
+        return;
+      }
+      if (ev.key === 'Backspace' || ev.key === 'Delete') {
+        erase();
+        ev.preventDefault();
+        return;
+      }
+      if (ev.key === 'n' || ev.key === 'N') {
+        setNoteMode((v) => !v);
+        return;
+      }
+      const sel = state.selected;
+      if (!sel) return;
+      let { row, col } = sel;
+      switch (ev.key) {
+        case 'ArrowUp':
+          row = (row + 8) % 9;
+          break;
+        case 'ArrowDown':
+          row = (row + 1) % 9;
+          break;
+        case 'ArrowLeft':
+          col = (col + 8) % 9;
+          break;
+        case 'ArrowRight':
+          col = (col + 1) % 9;
+          break;
+        default:
+          return;
+      }
+      ev.preventDefault();
+      select(row, col);
+    },
+    [applyDigit, erase, select, state.selected]
+  );
+
+  useEffect(() => {
+    window.addEventListener('keydown', handleKey, { passive: false });
+    return () => window.removeEventListener('keydown', handleKey);
+  }, [handleKey]);
+
+  useEffect(() => {
+    if (autofocus) boardRef.current?.focus({ preventScroll: true });
+  }, [autofocus]);
+
+  const lastStatus = useRef(state.status);
+  useEffect(() => {
+    if (state.status === 'won' && lastStatus.current !== 'won') {
+      onSolved?.({ difficulty: state.difficulty, seconds: state.elapsedSeconds });
+    }
+    lastStatus.current = state.status;
+  }, [state.status, state.difficulty, state.elapsedSeconds, onSolved]);
+
+  useImperativeHandle(
+    ref,
+    () => ({ select, input, erase, toggleNote, hint, newGame, undo }),
+    [select, input, erase, toggleNote, hint, newGame, undo]
+  );
+
+  const won = state.status === 'won';
+  const timeText = formatTime(won ? state.elapsedSeconds : game.getState().elapsedSeconds);
+  const bestText = state.bestSeconds === null ? '—' : formatTime(state.bestSeconds);
+
+  const renderCell = (row: number, col: number): ReactNode => {
+    const value = cellValueOf(state, row, col);
+    const notes = cellNotesOf(state, row, col);
+    return (
+      <div
+        key={`${row}-${col}`}
+        className={cellClass(state, row, col)}
+        data-row={row}
+        data-col={col}
+        onClick={() => select(row, col)}
+      >
+        {value !== 0 ? (
+          value
+        ) : (
+          <div className="cell-notes">
+            {PAD_DIGITS.map((d) => (
+              <span key={d}>{notes.includes(d) ? d : ''}</span>
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  };
+
   return (
-    <div className="game-sudoku">
-      <p>{title} · React 占位组件（0.0.0）。真实棋盘随引擎后续提交补入。</p>
+    <div className={['game-sudoku', className].filter(Boolean).join(' ')}>
+      <header className="game-sudoku-header">
+        <h1 className="game-sudoku-title">
+          {title}
+          <span className="subtitle">@my-games/sudoku-react</span>
+        </h1>
+        <div className="game-sudoku-stats">
+          <div className="game-sudoku-stat">
+            <span className="label">用时</span>
+            <span className="value">{timeText}</span>
+          </div>
+          <div className="game-sudoku-stat">
+            <span className="label">最佳</span>
+            <span className="value">{bestText}</span>
+          </div>
+          <div className={`game-sudoku-stat${state.mistakeCount > 0 ? ' is-danger' : ''}`}>
+            <span className="label">错误</span>
+            <span className="value">{state.mistakeCount}</span>
+          </div>
+        </div>
+      </header>
+
+      <div className="game-sudoku-toolbar">
+        <div className="game-sudoku-difficulty" role="group" aria-label="难度">
+          {DIFFS.map((d) => (
+            <button
+              key={d.key}
+              className={`game-sudoku-chip${state.difficulty === d.key ? ' is-active' : ''}`}
+              type="button"
+              onClick={() => newGame(d.key)}
+            >
+              {d.label}
+            </button>
+          ))}
+        </div>
+        <div className="game-sudoku-actions">
+          <button
+            className={`game-sudoku-button${noteMode ? ' is-toggled' : ''}`}
+            type="button"
+            disabled={won}
+            onClick={() => setNoteMode((v) => !v)}
+          >
+            笔记 {noteMode ? '开' : '关'}
+          </button>
+          <button
+            className="game-sudoku-button"
+            type="button"
+            disabled={won || state.historySize === 0}
+            onClick={() => undo()}
+          >
+            撤销
+          </button>
+          {showHint ? (
+            <button
+              className="game-sudoku-button"
+              type="button"
+              disabled={won}
+              onClick={() => hint()}
+            >
+              提示
+            </button>
+          ) : null}
+          <button className="game-sudoku-button is-primary" type="button" onClick={() => newGame()}>
+            新游戏
+          </button>
+        </div>
+      </div>
+
+      <div
+        ref={boardRef}
+        className="game-sudoku-board"
+        tabIndex={0}
+        role="application"
+        aria-label={`数独棋盘 ${state.status}`}
+        style={{ '--cols': 9 } as CSSProperties}
+      >
+        {BOXES.map((cells, bi) => (
+          <div key={bi} className="game-sudoku-box">
+            {cells.map(({ row, col }) => renderCell(row, col))}
+          </div>
+        ))}
+
+        <div className={`game-sudoku-overlay${won ? ' is-visible' : ''}`}>
+          <h2>解开了！</h2>
+          <p className="meta">
+            难度 {state.difficulty} · 用时 {timeText} · 提示 {state.hintCount} 次 · 错误{' '}
+            {state.mistakeCount} 次
+          </p>
+          <div className="row">
+            <button className="game-sudoku-button is-primary" type="button" onClick={() => newGame()}>
+              再来一局
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {showPad ? (
+        <div className="game-sudoku-pad" role="group" aria-label="数字键盘">
+          {PAD_DIGITS.map((d) => (
+            <button key={d} type="button" disabled={won} onClick={() => applyDigit(d)}>
+              {d}
+            </button>
+          ))}
+        </div>
+      ) : null}
     </div>
   );
 }
+
+export const GameSudoku = forwardRef(GameSudokuInner);
+GameSudoku.displayName = 'GameSudoku';

package/src/index.ts

@@ -1,4 +1,12 @@
-export { GameSudoku, type GameSudokuProps } from './GameSudoku';
+export { GameSudoku, type GameSudokuProps, type GameSudokuHandle } from './GameSudoku';
+export { useGame, type UseGameReturn } from './useGame';
 
-export const SUDOKU_PACKAGE = 'sudoku-react' as const;
-export const SUDOKU_STAGE = '0.0.0' as const;
+export type {
+  Cell,
+  Difficulty,
+  Digit,
+  GameState,
+  GameStatus,
+  Grid,
+  SaveStorage
+} from '@my-games/sudoku-core';

package/src/useGame.ts

@@ -0,0 +1,62 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import {
+  Sudoku,
+  type Difficulty,
+  type Digit,
+  type GameOptions,
+  type GameState
+} from '@my-games/sudoku-core';
+
+/**
+ * `useGame` —— React Hook 版引擎桥接（与 Vue 的 useGame 语义对齐）。
+ *
+ * - 引擎实例用 useMemo 按「难度 + 键名」缓存；这些 prop 变化 = 重开一局，视为预期语义。
+ * - useState 订阅引擎快照，useEffect 挂/卸订阅防泄漏。
+ * - useRef 保最新 game 实例给命令式 handler，避免闭包过期。
+ */
+export interface UseGameReturn {
+  state: GameState;
+  game: Sudoku;
+  select: (row: number, col: number) => void;
+  input: (digit: Digit) => boolean;
+  erase: () => boolean;
+  toggleNote: (digit: Digit) => boolean;
+  hint: () => boolean;
+  newGame: (difficulty?: Difficulty) => void;
+  undo: () => boolean;
+  canUndo: () => boolean;
+}
+
+export function useGame(options: GameOptions = {}): UseGameReturn {
+  const { difficulty, storage, saveKey, bestKey, freshStart, puzzle } = options;
+
+  const game = useMemo(
+    () => new Sudoku({ difficulty, storage, saveKey, bestKey, freshStart, puzzle }),
+    // 故意只依赖这些稳定原始值；storage / puzzle / rng / clock 引用不稳定，重开一次即可。
+    [difficulty, saveKey, bestKey]
+  );
+
+  const gameRef = useRef(game);
+  gameRef.current = game;
+
+  const [state, setState] = useState<GameState>(() => game.getState());
+
+  useEffect(() => {
+    setState(game.getState());
+    const unsub = game.subscribe(setState);
+    return unsub;
+  }, [game]);
+
+  return {
+    state,
+    game,
+    select: (row, col) => gameRef.current.select(row, col),
+    input: (digit) => gameRef.current.input(digit),
+    erase: () => gameRef.current.erase(),
+    toggleNote: (digit) => gameRef.current.toggleNote(digit),
+    hint: () => gameRef.current.hint(),
+    newGame: (diff) => gameRef.current.newGame(diff),
+    undo: () => gameRef.current.undo(),
+    canUndo: () => gameRef.current.canUndo()
+  };
+}