@logic-pad/core 0.26.2 → 0.26.3

package/dist/src/data/dataHelper.d.ts

@@ -0,0 +1,92 @@
+import { Direction, Edge, Orientation, Position } from './primitives.js';
+/**
+ * Offset the given position by a given step in the given direction.
+ * @param position The position to offset.
+ * @param direction The direction to offset in.
+ * @param step The distance to offset by.
+ * @returns The offset position.
+ */
+export declare function move(position: Position, direction: Direction | Orientation, step?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Check if two edges are the same, regardless of direction.
+ * @param a The first edge.
+ * @param b The second edge.
+ * @returns Whether the edges are the same.
+ */
+export declare function isSameEdge(a: Edge, b: Edge): boolean;
+/**
+ * Convert the given direction to a rotation in degrees.
+ * @param direction The direction to convert.
+ * @returns The rotation in degrees.
+ */
+export declare function directionToRotation(direction: Direction): 0 | 270 | 90 | 180;
+/**
+ * Convert the given orientation to a rotation in degrees.
+ * @param orientation The orientation to convert.
+ * @returns The rotation in degrees.
+ */
+export declare function orientationToRotation(orientation: Orientation): 0 | 270 | 90 | 180 | 225 | 125 | 315 | 45;
+/**
+ * Create a new 2D array with the given dimensions and values.
+ * @param width The width of the array.
+ * @param height The height of the array.
+ * @param value A function that returns the value for each x,y coordinate.
+ * @returns The 2D array.
+ */
+export declare function array<T>(width: number, height: number, value: (x: number, y: number) => T): T[][];
+/**
+ * Resize the given array to the new size, cutting off or padding with the default value.
+ * @param array The array to resize.
+ * @param newSize The new size of the array.
+ * @param defaultValue A function that returns the default value for each new element.
+ * @returns The resized array.
+ */
+export declare function resize<T>(array: T[], newSize: number, defaultValue: () => T): T[];
+export declare function resize<T>(array: readonly T[], newSize: number, defaultValue: () => T): readonly T[];
+/**
+ * Check if all the given values are equal.
+ * @param values The values to compare.
+ * @returns Whether all the values are equal.
+ */
+export declare function allEqual<T>(...values: T[]): boolean;
+/**
+ * Return the first element of the array which has the minimum mapped value.
+ *
+ * @param values The array of values.
+ * @param mapper The function to map each value to a number.
+ * @returns The first element with the minimum mapped value.
+ */
+export declare function minBy<T>(values: readonly T[], mapper: (element: T) => number): T | undefined;
+/**
+ * Return the first element of the array which has the maximum mapped value.
+ *
+ * @param values The array of values.
+ * @param mapper The function to map each value to a number.
+ * @returns The first element with the maximum mapped value.
+ */
+export declare function maxBy<T>(values: readonly T[], mapper: (element: T) => number): T | undefined;
+/**
+ * Escape the given text by replacing the specified characters with HTML escape sequences.
+ * @param text The text to escape.
+ * @param escapeCharacters The characters to escape.
+ * @returns The escaped text.
+ */
+export declare function escape(text: string, escapeCharacters?: string): string;
+/**
+ * Unescape the given text by replacing HTML escape sequences with the corresponding characters.
+ * @param text The text to unescape.
+ * @param escapeCharacters The characters to unescape. This should match the characters escaped by the `escape` function.
+ * @returns The unescaped text.
+ */
+export declare function unescape(text: string, escapeCharacters?: string): string;
+export declare class CachedAccess<T> {
+    private readonly getter;
+    private static readonly UNCACHED;
+    private cache;
+    private constructor();
+    static of<T>(getter: () => T): CachedAccess<T>;
+    get value(): T;
+}

package/dist/src/data/dataHelper.js

@@ -0,0 +1,217 @@
+import { Direction, Orientation } from './primitives.js';
+/**
+ * Offset the given position by a given step in the given direction.
+ * @param position The position to offset.
+ * @param direction The direction to offset in.
+ * @param step The distance to offset by.
+ * @returns The offset position.
+ */
+export function move(position, direction, step = 1) {
+    switch (direction) {
+        case Direction.Up:
+        case Orientation.Up:
+            return { x: position.x, y: position.y - step };
+        case Direction.Down:
+        case Orientation.Down:
+            return { x: position.x, y: position.y + step };
+        case Direction.Left:
+        case Orientation.Left:
+            return { x: position.x - step, y: position.y };
+        case Direction.Right:
+        case Orientation.Right:
+            return { x: position.x + step, y: position.y };
+        case Orientation.UpLeft:
+            return { x: position.x - step, y: position.y - step };
+        case Orientation.UpRight:
+            return { x: position.x + step, y: position.y - step };
+        case Orientation.DownLeft:
+            return { x: position.x - step, y: position.y + step };
+        case Orientation.DownRight:
+            return { x: position.x + step, y: position.y + step };
+    }
+}
+/**
+ * Check if two edges are the same, regardless of direction.
+ * @param a The first edge.
+ * @param b The second edge.
+ * @returns Whether the edges are the same.
+ */
+export function isSameEdge(a, b) {
+    return ((a.x1 === b.x1 && a.y1 === b.y1 && a.x2 === b.x2 && a.y2 === b.y2) ||
+        (a.x1 === b.x2 && a.y1 === b.y2 && a.x2 === b.x1 && a.y2 === b.y1));
+}
+/**
+ * Convert the given direction to a rotation in degrees.
+ * @param direction The direction to convert.
+ * @returns The rotation in degrees.
+ */
+export function directionToRotation(direction) {
+    switch (direction) {
+        case Direction.Up:
+            return 0;
+        case Direction.Left:
+            return 270;
+        case Direction.Right:
+            return 90;
+        case Direction.Down:
+            return 180;
+    }
+}
+/**
+ * Convert the given orientation to a rotation in degrees.
+ * @param orientation The orientation to convert.
+ * @returns The rotation in degrees.
+ */
+export function orientationToRotation(orientation) {
+    switch (orientation) {
+        case Orientation.Up:
+            return 0;
+        case Orientation.Left:
+            return 270;
+        case Orientation.Right:
+            return 90;
+        case Orientation.Down:
+            return 180;
+        case Orientation.DownLeft:
+            return 225;
+        case Orientation.DownRight:
+            return 125;
+        case Orientation.UpLeft:
+            return 315;
+        case Orientation.UpRight:
+            return 45;
+    }
+}
+/**
+ * Create a new 2D array with the given dimensions and values.
+ * @param width The width of the array.
+ * @param height The height of the array.
+ * @param value A function that returns the value for each x,y coordinate.
+ * @returns The 2D array.
+ */
+export function array(width, height, value) {
+    const result = [];
+    for (let y = 0; y < height; y++) {
+        result[y] = [];
+        for (let x = 0; x < width; x++) {
+            result[y][x] = value(x, y);
+        }
+    }
+    return result;
+}
+export function resize(array, newSize, defaultValue) {
+    if (array.length < newSize) {
+        return [
+            ...array,
+            ...Array.from({ length: newSize - array.length }, defaultValue),
+        ];
+    }
+    else if (array.length > newSize) {
+        return array.slice(0, newSize);
+    }
+    return array;
+}
+/**
+ * Check if all the given values are equal.
+ * @param values The values to compare.
+ * @returns Whether all the values are equal.
+ */
+export function allEqual(...values) {
+    return values.every(value => value === values[0]);
+}
+/**
+ * Return the first element of the array which has the minimum mapped value.
+ *
+ * @param values The array of values.
+ * @param mapper The function to map each value to a number.
+ * @returns The first element with the minimum mapped value.
+ */
+export function minBy(values, mapper) {
+    let min = Number.POSITIVE_INFINITY;
+    let result;
+    for (const value of values) {
+        const mapped = mapper(value);
+        if (mapped < min) {
+            min = mapped;
+            result = value;
+        }
+    }
+    return result;
+}
+/**
+ * Return the first element of the array which has the maximum mapped value.
+ *
+ * @param values The array of values.
+ * @param mapper The function to map each value to a number.
+ * @returns The first element with the maximum mapped value.
+ */
+export function maxBy(values, mapper) {
+    let max = Number.NEGATIVE_INFINITY;
+    let result;
+    for (const value of values) {
+        const mapped = mapper(value);
+        if (mapped > max) {
+            max = mapped;
+            result = value;
+        }
+    }
+    return result;
+}
+/**
+ * Escape the given text by replacing the specified characters with HTML escape sequences.
+ * @param text The text to escape.
+ * @param escapeCharacters The characters to escape.
+ * @returns The escaped text.
+ */
+export function escape(text, escapeCharacters = '=,:|') {
+    let result = '';
+    for (const char of text) {
+        if (escapeCharacters.includes(char) || char === '&') {
+            result += `&#${char.charCodeAt(0)};`;
+        }
+        else {
+            result += char;
+        }
+    }
+    return result;
+}
+/**
+ * Unescape the given text by replacing HTML escape sequences with the corresponding characters.
+ * @param text The text to unescape.
+ * @param escapeCharacters The characters to unescape. This should match the characters escaped by the `escape` function.
+ * @returns The unescaped text.
+ */
+export function unescape(text, escapeCharacters = '=,:|') {
+    let result = '';
+    const matches = text.matchAll(/&#([0-9]+);/g);
+    let index = 0;
+    for (const match of matches) {
+        result += text.substring(index, match.index);
+        const char = String.fromCharCode(parseInt(match[1], 10));
+        if (escapeCharacters.includes(char) || char === '&') {
+            result += char;
+        }
+        else {
+            result += match[0];
+        }
+        index = match.index + match[0].length;
+    }
+    return result + text.substring(index);
+}
+export class CachedAccess {
+    getter;
+    static UNCACHED = Symbol('uncached');
+    cache = CachedAccess.UNCACHED;
+    constructor(getter) {
+        this.getter = getter;
+    }
+    static of(getter) {
+        return new CachedAccess(getter);
+    }
+    get value() {
+        if (this.cache === CachedAccess.UNCACHED) {
+            this.cache = this.getter();
+        }
+        return this.cache;
+    }
+}

package/dist/src/data/events/eventHelper.d.ts

@@ -0,0 +1 @@
+export declare function isEventHandler<T>(val: unknown, event: string): val is T;

package/dist/src/data/events/eventHelper.js

@@ -0,0 +1,6 @@
+export function isEventHandler(val, event) {
+    if (typeof val !== 'object' || val === null || val === undefined)
+        return false;
+    return (event in val &&
+        typeof val[event] === 'function');
+}

package/dist/src/data/events/onFinalValidation.d.ts

@@ -0,0 +1,14 @@
+import GridData from '../grid.js';
+import Instruction from '../instruction.js';
+import { GridState } from '../primitives.js';
+export interface FinalValidationHandler {
+    /**
+     * Edits the final grid state after all rules and symbols have been validated.
+     *
+     * @param grid The grid that is being validated.
+     * @param solution The solution grid, or null if the solution is not available.
+     * @param state The current state of the grid.
+     */
+    onFinalValidation(grid: GridData, solution: GridData | null, state: GridState): GridState;
+}
+export declare function handlesFinalValidation<T extends Instruction>(val: T): val is T & FinalValidationHandler;

package/dist/src/data/events/onFinalValidation.js

@@ -0,0 +1,4 @@
+import { isEventHandler } from './eventHelper.js';
+export function handlesFinalValidation(val) {
+    return isEventHandler(val, 'onFinalValidation');
+}

package/dist/src/data/events/onGetTile.d.ts

@@ -0,0 +1,7 @@
+import Instruction from '../instruction.js';
+import { Position } from '../primitives.js';
+import GridData from '../grid.js';
+export interface GetTileHandler {
+    onGetTile(x: number, y: number, grid: GridData): Position;
+}
+export declare function handlesGetTile<T extends Instruction>(val: T): val is T & GetTileHandler;

package/dist/src/data/events/onGetTile.js

@@ -0,0 +1,4 @@
+import { isEventHandler } from './eventHelper.js';
+export function handlesGetTile(val) {
+    return isEventHandler(val, 'onGetTile');
+}

package/dist/src/data/events/onGridChange.d.ts

@@ -0,0 +1,6 @@
+import GridData from '../grid.js';
+import Instruction from '../instruction.js';
+export interface GridChangeHandler {
+    onGridChange(newGrid: GridData): this;
+}
+export declare function handlesGridChange<T extends Instruction>(val: T): val is T & GridChangeHandler;

package/dist/src/data/events/onGridChange.js

@@ -0,0 +1,4 @@
+import { isEventHandler } from './eventHelper.js';
+export function handlesGridChange(val) {
+    return isEventHandler(val, 'onGridChange');
+}

package/dist/src/data/events/onGridResize.d.ts

@@ -0,0 +1,9 @@
+import GridData from '../grid.js';
+import Instruction from '../instruction.js';
+export interface GridResizeHandler {
+    /**
+     * Update itself when the grid is resized.
+     */
+    onGridResize(grid: GridData, mode: 'insert' | 'remove', direction: 'row' | 'column', index: number): this | null;
+}
+export declare function handlesGridResize<T extends Instruction>(val: T): val is T & GridResizeHandler;

package/dist/src/data/events/onGridResize.js

@@ -0,0 +1,4 @@
+import { isEventHandler } from './eventHelper.js';
+export function handlesGridResize(val) {
+    return isEventHandler(val, 'onGridResize');
+}

package/dist/src/data/events/onSetGrid.d.ts

@@ -0,0 +1,7 @@
+import GridData from '../grid.js';
+import Instruction from '../instruction.js';
+export interface SetGridHandler {
+    onSetGrid(oldGrid: GridData, newGrid: GridData, solution: GridData | null): GridData;
+}
+export declare function handlesSetGrid<T extends Instruction>(val: T): val is T & SetGridHandler;
+export declare function invokeSetGrid(oldGrid: GridData, newGrid: GridData, solution: GridData | null): GridData;

package/dist/src/data/events/onSetGrid.js

@@ -0,0 +1,19 @@
+import { isEventHandler } from './eventHelper.js';
+export function handlesSetGrid(val) {
+    return isEventHandler(val, 'onSetGrid');
+}
+export function invokeSetGrid(oldGrid, newGrid, solution) {
+    newGrid.symbols.forEach(list => {
+        list.forEach(symbol => {
+            if (handlesSetGrid(symbol)) {
+                newGrid = symbol.onSetGrid(oldGrid, newGrid, solution);
+            }
+        });
+    });
+    newGrid.rules.forEach(rule => {
+        if (handlesSetGrid(rule)) {
+            newGrid = rule.onSetGrid(oldGrid, newGrid, solution);
+        }
+    });
+    return newGrid;
+}

package/dist/src/data/events/onSymbolDisplay.d.ts

@@ -0,0 +1,16 @@
+import GridData from '../grid.js';
+import Instruction from '../instruction.js';
+import Symbol from '../symbols/symbol.js';
+export interface SymbolDisplayHandler {
+    /**
+     * Controls whether a symbol should be visible in the grid.
+     *
+     * @param grid The grid that is being displayed.
+     * @param solution The solution grid, if it is available.
+     * @param symbol The symbol that is being displayed.
+     * @param editing Whether the grid is being edited.
+     * @returns True if the symbol should be displayed, false otherwise. The symbol will not be displayed if any handler returns false.
+     */
+    onSymbolDisplay(grid: GridData, solution: GridData | null, symbol: Symbol, editing: boolean): boolean;
+}
+export declare function handlesSymbolDisplay<T extends Instruction>(val: T): val is T & SymbolDisplayHandler;

package/dist/src/data/events/onSymbolDisplay.js

@@ -0,0 +1,4 @@
+import { isEventHandler } from './eventHelper.js';
+export function handlesSymbolDisplay(val) {
+    return isEventHandler(val, 'onSymbolDisplay');
+}

package/dist/src/data/events/onSymbolMerge.d.ts

@@ -0,0 +1,10 @@
+import Instruction from '../instruction.js';
+import Symbol from '../symbols/symbol.js';
+export interface SymbolMergeHandler {
+    /**
+     * Determines if the description of two symbols can be merged when displayed in the UI.
+     * @param other The other symbol to compare against.
+     */
+    descriptionEquals(other: Symbol): boolean;
+}
+export declare function handlesSymbolMerge<T extends Instruction>(val: T): val is T & SymbolMergeHandler;

package/dist/src/data/events/onSymbolMerge.js

@@ -0,0 +1,4 @@
+import { isEventHandler } from './eventHelper.js';
+export function handlesSymbolMerge(val) {
+    return isEventHandler(val, 'descriptionEquals');
+}

package/dist/src/data/events/onSymbolValidation.d.ts

@@ -0,0 +1,18 @@
+import GridData from '../grid.js';
+import { State } from '../primitives.js';
+import Rule from '../rules/rule.js';
+import Symbol from '../symbols/symbol.js';
+export interface SymbolValidationHandler {
+    /**
+     * Overrides the validation of symbols.
+     *
+     * You can return a different validation result, or call the original validation logic with a modified grid.
+     *
+     * @param grid - The grid to validate.
+     * @param _symbol - The symbol to validate.
+     * @param validator - The original validation logic for the symbol.
+     * @returns The state of the symbol after validation.
+     */
+    onSymbolValidation(grid: GridData, symbol: Symbol, validator: (grid: GridData) => State): State | undefined;
+}
+export declare function handlesSymbolValidation<T extends Rule>(val: T): val is T & SymbolValidationHandler;

package/dist/src/data/events/onSymbolValidation.js

@@ -0,0 +1,4 @@
+import { isEventHandler } from './eventHelper.js';
+export function handlesSymbolValidation(val) {
+    return isEventHandler(val, 'onSymbolValidation');
+}