@fgv/ts-sudoku-lib 5.0.1-0 → 5.0.1-2

package/lib/packlets/hints/puzzleSessionHints.d.ts

@@ -0,0 +1,306 @@
+import { Result } from '@fgv/ts-utils';
+import { ICellState, IRowColumn, ICell, PuzzleSession } from '../common';
+import { HintSystem, IHintSystemConfig } from './hints';
+import { ExplanationLevel, IHint, IHintGenerationOptions } from './types';
+/**
+ * Configuration options for the PuzzleSessionHints integration.
+ * @public
+ */
+export interface IPuzzleSessionHintsConfig extends IHintSystemConfig {
+    readonly cacheTimeoutMs?: number;
+    readonly maxCacheEntries?: number;
+}
+/**
+ * Wrapper class that integrates hint functionality with PuzzleSession.
+ * Provides hint generation, application, and explanation capabilities while
+ * maintaining integration with existing state management and undo/redo functionality.
+ * @public
+ */
+export declare class PuzzleSessionHints {
+    private readonly _session;
+    private readonly _hintSystem;
+    private readonly _config;
+    private _hintCache;
+    /**
+     * @internal
+     */
+    private constructor();
+    /**
+     * Creates a new PuzzleSessionHints wrapper for an existing PuzzleSession.
+     * @param session - The PuzzleSession to wrap
+     * @param config - Optional configuration for the hint system
+     * @returns Result containing the new PuzzleSessionHints wrapper
+     */
+    static create(session: PuzzleSession, config?: IPuzzleSessionHintsConfig): Result<PuzzleSessionHints>;
+    /**
+     * Gets the wrapped PuzzleSession instance.
+     * @returns The underlying PuzzleSession
+     */
+    get session(): PuzzleSession;
+    /**
+     * Gets the HintSystem instance.
+     * @returns The hint system
+     */
+    get hintSystem(): HintSystem;
+    /**
+     * Gets the configuration.
+     * @returns The configuration
+     */
+    get config(): IPuzzleSessionHintsConfig;
+    /**
+     * Gets the puzzle ID.
+     * @returns The puzzle ID
+     */
+    get id(): string | undefined;
+    /**
+     * Gets the puzzle description.
+     * @returns The puzzle description
+     */
+    get description(): string;
+    /**
+     * Gets the number of rows in the puzzle.
+     * @returns The number of rows
+     */
+    get numRows(): number;
+    /**
+     * Gets the number of columns in the puzzle.
+     * @returns The number of columns
+     */
+    get numColumns(): number;
+    /**
+     * Gets the current puzzle state.
+     * @returns The current state
+     */
+    get state(): import('../common').PuzzleState;
+    /**
+     * Gets whether undo is possible.
+     * @returns true if undo is possible
+     */
+    get canUndo(): boolean;
+    /**
+     * Gets whether redo is possible.
+     * @returns true if redo is possible
+     */
+    get canRedo(): boolean;
+    /**
+     * Checks if the puzzle is solved.
+     * @returns true if the puzzle is solved
+     */
+    checkIsSolved(): boolean;
+    /**
+     * Checks if the puzzle is valid.
+     * @returns true if the puzzle is valid
+     */
+    checkIsValid(): boolean;
+    /**
+     * Updates a cell value.
+     * @param spec - Cell specification
+     * @param value - New value
+     * @returns Result with this instance
+     */
+    updateCellValue(spec: string | IRowColumn | ICell, value: number | undefined): Result<this>;
+    /**
+     * Updates cell notes.
+     * @param spec - Cell specification
+     * @param notes - New notes
+     * @returns Result with this instance
+     */
+    updateCellNotes(spec: string | IRowColumn | ICell, notes: number[]): Result<this>;
+    /**
+     * Updates multiple cells.
+     * @param updates - Array of cell updates
+     * @returns Result with this instance
+     */
+    updateCells(updates: ICellState[]): Result<this>;
+    /**
+     * Performs an undo operation.
+     * @returns Result with this instance
+     */
+    undo(): Result<this>;
+    /**
+     * Performs a redo operation.
+     * @returns Result with this instance
+     */
+    redo(): Result<this>;
+    /**
+     * Gets the best available hint for the current puzzle state.
+     * @param options - Optional hint generation options
+     * @returns Result containing the best hint
+     */
+    getHint(options?: IHintGenerationOptions): Result<IHint>;
+    /**
+     * Gets all available hints for the current puzzle state.
+     * @param options - Optional hint generation options
+     * @returns Result containing array of hints
+     */
+    getAllHints(options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Applies a hint to the puzzle, updating the state and adding to undo history.
+     * @param hint - The hint to apply
+     * @returns Result with this instance if successful
+     */
+    applyHint(hint: IHint): Result<this>;
+    /**
+     * Gets hints that specifically affect a given cell.
+     * @param spec - Cell specification (ID, row/column, or cell object)
+     * @param options - Optional hint generation options
+     * @returns Result containing hints affecting the specified cell
+     */
+    getHintsForCell(spec: string | IRowColumn | ICell, options?: IHintGenerationOptions): Result<readonly IHint[]>;
+    /**
+     * Gets a formatted explanation for a hint.
+     * @param hint - The hint to explain
+     * @param level - The explanation level (defaults to configured default)
+     * @returns Formatted explanation string
+     */
+    getExplanation(hint: IHint, level?: ExplanationLevel): string;
+    /**
+     * Validates that a hint can be applied to the current state.
+     * @param hint - The hint to validate
+     * @returns Result indicating validation success or failure
+     */
+    validateHint(hint: IHint): Result<void>;
+    /**
+     * Checks if hints are available for the current state.
+     * @param options - Optional hint generation options
+     * @returns Result containing boolean indicating availability
+     */
+    hasHints(options?: IHintGenerationOptions): Result<boolean>;
+    /**
+     * Gets statistics about available hints.
+     * @param options - Optional hint generation options
+     * @returns Result containing hint statistics
+     */
+    getHintStatistics(options?: IHintGenerationOptions): Result<{
+        totalHints: number;
+        hintsByTechnique: Map<string, number>;
+        hintsByDifficulty: Map<string, number>;
+    }>;
+    /**
+     * Gets a summary of the hint system capabilities.
+     * @returns System capabilities summary
+     */
+    getSystemSummary(): string;
+    /**
+     * Gets the rows.
+     * @returns Array of row cages
+     */
+    get rows(): import('../common').ICage[];
+    /**
+     * Gets the columns.
+     * @returns Array of column cages
+     */
+    get cols(): import('../common').ICage[];
+    /**
+     * Gets the sections.
+     * @returns Array of section cages
+     */
+    get sections(): import('../common').ICage[];
+    /**
+     * Gets all cages.
+     * @returns Array of all cages
+     */
+    get cages(): import('../common').ICage[];
+    /**
+     * Gets all cells.
+     * @returns Array of all cells
+     */
+    get cells(): ICell[];
+    /**
+     * Gets the next step index.
+     * @returns Next step index
+     */
+    get nextStep(): number;
+    /**
+     * Gets the number of steps.
+     * @returns Number of steps
+     */
+    get numSteps(): number;
+    /**
+     * Gets empty cells.
+     * @returns Array of empty cells
+     */
+    getEmptyCells(): ICell[];
+    /**
+     * Gets invalid cells.
+     * @returns Array of invalid cells
+     */
+    getInvalidCells(): ICell[];
+    /**
+     * Checks if a cell is valid.
+     * @param spec - Cell specification
+     * @returns true if valid
+     */
+    cellIsValid(spec: string | IRowColumn | ICell): boolean;
+    /**
+     * Checks if a cell has a value.
+     * @param spec - Cell specification
+     * @returns true if cell has value
+     */
+    cellHasValue(spec: string | IRowColumn | ICell): boolean;
+    /**
+     * Checks if a value is valid for a cell.
+     * @param spec - Cell specification
+     * @param value - Value to check
+     * @returns true if valid
+     */
+    isValidForCell(spec: string | IRowColumn | ICell, value: number): boolean;
+    /**
+     * Gets a cell neighbor.
+     * @param spec - Cell specification
+     * @param direction - Navigation direction
+     * @param wrap - Wrap behavior
+     * @returns Result containing neighbor cell
+     */
+    getCellNeighbor(spec: string | IRowColumn | ICell, direction: import('../common').NavigationDirection, wrap: import('../common').NavigationWrap): Result<ICell>;
+    /**
+     * Gets cell contents.
+     * @param spec - Cell specification
+     * @returns Result containing cell and contents
+     */
+    getCellContents(spec: string | IRowColumn): Result<{
+        cell: ICell;
+        contents: import('../common').ICellContents;
+    }>;
+    /**
+     * Checks if a cage contains a value.
+     * @param spec - Cage specification
+     * @param value - Value to check
+     * @returns true if cage contains value
+     */
+    cageContainsValue(spec: string | import('../common').ICage, value: number): boolean;
+    /**
+     * Gets contained values in a cage.
+     * @param spec - Cage specification
+     * @returns Set of contained values
+     */
+    cageContainedValues(spec: string | import('../common').ICage): Set<number>;
+    /**
+     * Gets string representation of the puzzle.
+     * @returns Array of strings representing puzzle rows
+     */
+    toStrings(): string[];
+    /**
+     * Generates a cache key for the current state and options.
+     * @param options - Hint generation options
+     * @returns Cache key
+     */
+    private _generateCacheKey;
+    /**
+     * Gets cached hints if valid.
+     * @param options - Hint generation options
+     * @returns Cached hints or undefined
+     */
+    private _getCachedHints;
+    /**
+     * Updates the cache with new hints.
+     * @param hints - Generated hints
+     * @param options - Generation options
+     */
+    private _updateCache;
+    /**
+     * Invalidates the current hint cache.
+     */
+    private _invalidateCache;
+}
+//# sourceMappingURL=puzzleSessionHints.d.ts.map