mumuki-puzzle-runner 0.0.1 → 0.4.0

data/lib/public/vendor/headbreaker.d.ts

@@ -28,14 +28,14 @@ declare class Anchor {
     /**
      * Converts this anchor into a point
      */
-    asPoint(): Pair;
+    asPair(): Pair;
     /**
-     * Converts this anchor into a position
+     * Converts this anchor into a vector
      */
-    asPosition(): Position;
-    export(): Position;
+    asVector(): Vector;
+    export(): Vector;
     static atRandom(maxX: number, maxY: number): Anchor;
-    static import(position: Position): Anchor;
+    static import(vector: Vector): Anchor;
 }
 
 /**
@@ -43,6 +43,8 @@ declare class Anchor {
  */
 declare function anchor(x: number, y: number): Anchor;
 
+declare type Axis = Vertical | Horizontal;
+
 declare type Label = any;
 
 declare type Figure = {
@@ -76,9 +78,10 @@ declare type LabelMetadata = {
 
 declare type CanvasMetadata = {
     id?: string;
-    targetPosition?: Position;
-    currentPosition?: Position;
+    targetPosition?: Vector;
+    currentPosition?: Vector;
     color?: string;
+    fixed?: boolean;
     strokeColor?: string;
     image?: ImageLike;
     label?: LabelMetadata;
@@ -86,6 +89,7 @@ declare type CanvasMetadata = {
 
 declare type Template = {
     structure: StructureLike;
+    size?: Size;
     metadata: CanvasMetadata;
 };
 
@@ -93,25 +97,37 @@ declare type Template = {
  * An HTML graphical area where puzzles and pieces can be rendered. No assumption of the rendering backend is done - it may be
  * and be a plain HTML SVG or canvas element, or a higher-level library - and this task is fully delegated to {@link Painter}
  * @param id - the html id of the element where to place the canvas
+ * @param [options.pieceSize] - the piece size expresed as it edge-to-edge diameter
  * @param [options.borderFill] - the broder fill of the pieces, expresed in pixels. 0 means no border fill, 0.5 * pieceSize means full fill
  * @param [options.lineSoftness] - how soft the line will be
  * @param [options.image] - an optional background image for the puzzle that will be split across all pieces.
+ * @param [options.fixed] - whether the canvas can is fixed or can be dragged
  * @param [options.painter] - the Painter object used to actually draw figures in canvas
+ * @param [options.puzzleDiameter] - the puzzle diameter used to calculate the maximal width and height
+ *                                                                    You only need to specify this option when pieces are manually sketched and images must be adjusted
+ * @param [options.maxPiecesCount] - the maximal amount of pieces used to calculate the maximal width and height.
+ *                                                                    You only need to specify this option when pieces are manually sketched and images must be adjusted
  */
 declare class Canvas {
     constructor(id: string, options: {
         width: number;
         height: number;
-        pieceSize?: number;
+        pieceSize?: Vector | number;
         proximity?: number;
-        borderFill?: number;
+        borderFill?: Vector | number;
         strokeWidth?: number;
         strokeColor?: string;
         lineSoftness?: number;
         image?: ImageLike;
+        fixed?: boolean;
         painter?: Painter;
+        puzzleDiameter?: Vector | number;
+        maxPiecesCount?: Vector | number;
     });
     _painter: Painter;
+    _maxPiecesCount: Vector;
+    _puzzleDiameter: Vector;
+    _imageAdjuster: any;
     _puzzle: Puzzle;
     figures: {
         [key: string]: Figure;
@@ -133,7 +149,7 @@ declare class Canvas {
     renderPieces(pieces: Piece[]): void;
     /**
      * Renders a previously created puzzle object. This method
-     * overrides this canvas' {@link Canvas#pieceSize} and {@link Canvas#proximity}
+     * overrides this canvas' {@link Canvas#pieceDiameter} and {@link Canvas#proximity}
      */
     renderPuzzle(puzzle: Puzzle): void;
     /**
@@ -157,9 +173,17 @@ declare class Canvas {
      */
     sketchPieceUsingTemplate(id: string, templateName: string): void;
     /**
-     * @param farness - from 0 to 1, how far pieces will be placed from x = pieceSize, y = pieceSize
+     * @param farness - from 0 to 1, how far pieces will be placed from x = pieceDiameter.x, y = pieceDiameter.y
      */
     shuffle(farness?: number): void;
+    /**
+     * **Warning**: this method requires {@code maxPiecesCount} to be set.
+     */
+    shuffleColumns(farness?: number): void;
+    /**
+     * **Warning**: this method requires {@code maxPiecesCount} to be set.
+     */
+    shuffleGrid(farness?: number): void;
     /**
      * Draws this canvas for the first time
      */
@@ -189,6 +213,11 @@ declare class Canvas {
      * positions, overriding any previously configured validator
      */
     attachRelativePositionValidator(): void;
+    /**
+     * Sets a validator that will report when puzzle are at the expected given
+     * relative refs
+     */
+    attachRelativeRefsValidator(expected: any): void;
     /**
      * Sets a validator that will report when puzzle pieces are in their expected absolute
      * positions, overriding any previously configured validator
@@ -204,6 +233,10 @@ declare class Canvas {
     onDisconnect(f: CanvasConnectionListener): void;
     onTranslate(f: CanvasTranslationListener): void;
     onValid(f: ValidationListener): void;
+    /**
+     * Returns the current validation status
+     */
+    valid: boolean;
     /**
      * Answers the visual representation for the given piece.
      * This method uses piece's id.
@@ -213,6 +246,14 @@ declare class Canvas {
      * Answers the visual representation for the given piece id.
      */
     getFigureById(id: string): Figure;
+    /**
+     * Sets the new width and height of the canvas
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Scales the canvas contents to the given factor
+     */
+    scale(factor: Vector | number): void;
     _annotatePiecePosition(piece: Piece): void;
     /**
      * Configures updates from piece into group
@@ -222,13 +263,64 @@ declare class Canvas {
      * * Configures updates from group into piece
      */
     _bindPieceToGroup(piece: Piece, group: Group): void;
-    _imageMetadataFor(model: Piece): ImageMetadata;
-    _newPiece(structureLike: StructureLike, metadata: CanvasMetadata): void;
+    _baseImageMetadataFor(piece: Piece): ImageMetadata;
+    imageMetadataFor(piece: Piece): ImageMetadata;
+    /**
+     * Configures canvas to adjust images axis to puzzle's axis.
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPuzzle(axis: Axis): void;
+    /**
+     * Configures canvas to adjust images width to puzzle's width
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPuzzleWidth(): void;
+    /**
+     * Configures canvas to adjust images height to puzzle's height
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPuzzleHeight(): void;
+    /**
+     * Configures canvas to adjust images axis to pieces's axis
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPiece(axis: Axis): void;
+    /**
+     * Configures canvas to adjust images width to pieces's width
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPieceWidth(): void;
+    /**
+     * Configures canvas to adjust images height to pieces's height
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPieceHeight(): void;
+    /**
+     * @param structureLike - the piece structure
+     */
+    _newPiece(structureLike: StructureLike, size: Size, metadata: CanvasMetadata): void;
+    /**
+     * The puzzle diameter, using the
+     * configured puzzle diameter or the estimated one, if the first is not available.
+     */
+    puzzleDiameter: Vector;
+    /**
+     * The estimated puzzle diameter calculated using the the max pieces count.
+     */
+    estimatedPuzzleDiameter: Vector;
+    pieceRadio: Vector;
+    pieceDiameter: Vector;
     /**
      * The puzzle rendered by this canvas
      */
-    puzzle: any;
-    settings: any;
+    puzzle: Puzzle;
+    settings: Settings;
 }
 
 declare interface DummyPainter extends Painter {
@@ -245,7 +337,7 @@ declare class DummyPainter implements Painter {
 
 declare type ImageMetadata = {
     content: HTMLImageElement;
-    offset?: Position;
+    offset?: Vector;
     scale?: number;
 };
 
@@ -258,30 +350,7 @@ declare module "ImageMetadata" {
     function asImageMetadata(imageLike: ImageLike): ImageMetadata;
 }
 
-declare module "headbreaker" {
-    var anchor: any;
-    var position: any;
-    var Anchor: any;
-    var Puzzle: any;
-    var Piece: any;
-    var Canvas: any;
-    var Manufacturer: any;
-    var InsertSequence: any;
-    var PieceValidator: any;
-    var PuzzleValidator: any;
-    var NullValidator: any;
-    var Tab: any;
-    var Slot: any;
-    var None: any;
-    var Pair: any;
-    var Metadata: any;
-    var SpatialMetadata: any;
-    var Outline: any;
-    var Structure: any;
-    var Position: any;
-    var generators: any;
-    var painters: any;
-}
+declare module "headbreaker" { }
 
 /**
  * A connection element of a piece
@@ -298,6 +367,8 @@ declare class KonvaPainter implements Painter {
     initialize(canvas: Canvas, id: string): void;
     draw(canvas: Canvas): void;
     reinitialize(canvas: Canvas): void;
+    resize(canvas: Canvas, width: number, height: number): void;
+    scale(canvas: Canvas, factor: Vector): void;
     sketch(canvas: Canvas, piece: Piece, figure: Figure): void;
     label(_canvas: Canvas, piece: Piece, figure: Figure): void;
     physicalTranslate(_canvas: Canvas, group: Group, piece: Piece): void;
@@ -340,6 +411,8 @@ declare class Manufacturer {
 
 declare class Positioner {
     constructor(puzzle: Puzzle, headAnchor: Anchor);
+    initializeOffset(headAnchor: Anchor): void;
+    offset: Vector;
     naturalAnchor(x: number, y: number): void;
 }
 
@@ -358,7 +431,7 @@ declare module "Metadata" {
  */
 declare module "Outline" {
     function select(insert: Insert, t: number, s: number, n: number): void;
-    function draw(piece: Piece, size?: number): number[];
+    function draw(piece: Piece, size?: Vector | number, borderFill?: Vector | number): number[];
 }
 
 declare type VectorAction = (dx: number, dy: number) => void;
@@ -370,6 +443,7 @@ declare type Action = () => void;
  * order to create UI representations of a puzzle.
  */
 declare interface Painter {
+    resize(canvas: Canvas, width: number, height: number): void;
     /**
      * Creates the rendering backend, initializig all its contents.
      * After this call, painter is ready to receive any other messages
@@ -385,6 +459,10 @@ declare interface Painter {
      * Draws the canvas figures in the rendering backend
      */
     draw(canvas: Canvas): void;
+    /**
+     * Scales the canvas contents
+     */
+    scale(canvas: Canvas, factor: Vector): void;
     /**
      * Adds a piece to the rendering backend, so that it is ready to be drawn
      * @param figure - the rendering backend information for this piece. This method may mutate it if necessary
@@ -418,7 +496,10 @@ declare module "Pair" {
      * Tells whether this pair is (0, 0)
      */
     function isNull(x: number, y: number): boolean;
-    function equal(x1: number, y1: number, x2: number, y2: number): boolean;
+    /**
+     * @param [delta = 0] - tolerance in comparison
+     */
+    function equal(x1: number, y1: number, x2: number, y2: number, delta?: number): boolean;
     /**
      * Calculates the difference of two vectors
      */
@@ -429,25 +510,39 @@ declare type TranslationListener = (piece: Piece, dx: number, dy: number) => voi
 
 declare type ConnectionListener = (piece: Piece, target: Piece) => void;
 
+declare type PieceConfig = {
+    centralAnchor?: Vector;
+    size?: Size;
+    metadata?: any;
+};
+
 /**
  * A piece primitive representation that can be easily stringified, exchanged and persisted
  */
 declare type PieceDump = {
-    centralAnchor: Position;
-    structure: string;
-    connections?: Orthogonal<object>;
+    centralAnchor: Vector;
+    size?: Size;
     metadata: any;
+    connections?: Orthogonal<object>;
+    structure: string;
 };
 
 /**
  * A jigsaw piece
  */
 declare class Piece {
-    constructor(options?: Structure);
+    constructor(structure?: Structure, config?: PieceConfig);
+    metadata: any;
     centralAnchor: Anchor;
+    _size: Size;
     translateListeners: TranslationListener[];
     connectListeners: ConnectionListener[];
     disconnectListeners: ConnectionListener[];
+    /**
+     * Runs positining, sizing and metadata configurations
+     * in a single step
+     */
+    configure(config: PieceConfig): void;
     /**
      * Adds unestructured user-defined metadata on this piece.
      */
@@ -460,7 +555,9 @@ declare class Piece {
      */
     reannotate(metadata: any): void;
     belongTo(puzzle: any): void;
-    presentConnections: any;
+    presentConnections: Piece[];
+    connections: Piece[];
+    inserts: Insert[];
     /**
      * @param f - the callback
      */
@@ -531,16 +628,25 @@ declare class Piece {
     horizontallyCloseTo(other: Piece): boolean;
     verticallyMatch(other: Piece): boolean;
     horizontallyMatch(other: Piece): boolean;
-    downAnchor: any;
-    rightAnchor: any;
-    upAnchor: any;
-    leftAnchor: any;
-    size: any;
-    proximity: any;
+    downAnchor: Anchor;
+    rightAnchor: Anchor;
+    upAnchor: Anchor;
+    leftAnchor: Anchor;
+    /**
+     * Defines this piece's own dimmension, overriding puzzle's
+     * default dimmension
+     */
+    resize(size: Size): void;
+    radio: Vector;
+    /**
+     * The double of the radio
+     */
+    diameter: Vector;
+    proximity: number;
     /**
      * This piece id. It is extracted from metadata
      */
-    id: any;
+    id: string;
     /**
      * Converts this piece into a plain, stringify-ready object.
      * Connections should have ids
@@ -555,37 +661,6 @@ declare class Piece {
     static import(dump: PieceDump): Piece;
 }
 
-declare type Position = {
-    x: number;
-    y: number;
-};
-
-declare function position(x: number, y: number): Position;
-
-/**
- * This module contains functions for dealing with objects with x and y
- * coordinates that represent or include point data
- */
-declare module "Position" {
-    /**
-     * Returns a new (0, 0) position
-     */
-    function origin(): Position;
-    /**
-     * Compares two points
-     */
-    function equal(one: Position, other: Position): boolean;
-    /**
-     * Creates a copy of the given point
-     */
-    function copy(one: Position): Position;
-    function update(position: Position, x: any, y: any): void;
-    /**
-     * @returns ;
-     */
-    function diff(one: Position, other: Position): Pair;
-}
-
 declare type Orthogonal = {
     up: A;
     down: A;
@@ -609,13 +684,13 @@ declare module "Prelude" {
  * A puzzle primitive representation that can be easily stringified, exchanged and persisted
  */
 declare type PuzzleDump = {
-    pieceSize: number;
+    pieceRadio: Vector;
     proximity: number;
     pieces: PieceDump[];
 };
 
 declare type Settings = {
-    pieceSize?: number;
+    pieceRadio?: Vector | number;
     proximity?: number;
 };
 
@@ -629,10 +704,11 @@ declare class Puzzle {
     validator: Validator;
     /**
      * Creates and adds to this puzzle a new piece
-     * @param [options] - the piece structure
+     * @param [structure] - the piece structure
+     * @param [config] - the piece config
      * @returns the new piece
      */
-    newPiece(options?: Structure): Piece;
+    newPiece(structure?: Structure, config?: PieceConfig): Piece;
     addPiece(piece: Piece): void;
     addPieces(pieces: Piece[]): void;
     /**
@@ -658,6 +734,7 @@ declare class Puzzle {
      */
     autoconnectWith(piece: Piece): void;
     shuffle(maxX: number, maxY: number): void;
+    shuffleWith(shuffler: Shuffler): void;
     translate(dx: number, dy: number): void;
     onTranslate(f: TranslationListener): void;
     onConnect(f: ConnectionListener): void;
@@ -667,29 +744,59 @@ declare class Puzzle {
      * Answers the list of points where
      * central anchors of pieces are located
      */
-    points: any;
+    points: Pair[];
     /**
      * Answers a list of points whose coordinates are scaled
      * to the {@link Puzzle#pieceWidth}
      */
-    refs: any;
+    refs: Pair[];
+    metadata: any[];
     /**
      * Returns the first piece
      */
-    head: any;
+    head: Piece;
     /**
      * Returns the central anchor of the first piece
      */
-    headAnchor: any;
+    headAnchor: Anchor;
     attachValidator(validator: Validator): void;
+    /**
+     * Checks whether this puzzle is valid.
+     *
+     * Calling this method will not fire any validation listeners nor update the
+     * valid property.
+     */
+    isValid(): boolean;
+    /**
+     * Returns the current validation status
+     *
+     * Calling this property will not fire any validation listeners.
+     */
+    valid: boolean;
+    /**
+     * Checks whether this puzzle is valid, updating valid property
+     * and firing validation listeners if becomes valid
+     */
+    validate(): void;
+    /**
+     * Checks whether this puzzle is valid, updating valid property.
+     *
+     * Validations listeners are NOT fired.
+     */
+    updateValidity(): void;
     /**
      * Wether all the pieces in this puzzle are connected
      */
-    connected: any;
+    connected: boolean;
     /**
-     * The piece width, from edge to edge
+     * The piece width, from edge to edge.
+     * This is the double of the {@link Puzzle#pieceRadio}
      */
-    pieceWidth: any;
+    pieceDiameter: Vector;
+    /**
+     * The piece width, from center to edge
+     */
+    pieceRadio: Vector;
     /**
      * Converts this piece into a plain, stringify-ready object.
      * Pieces should have ids
@@ -744,9 +851,30 @@ declare module "sequence" {
     }
 }
 
+declare function random(maxX: number, maxY: number): Shuffler;
+
+declare function grid(): void;
+
+declare function columns(): void;
+
+declare function padder(padding: number, width: number, height: number): Shuffler;
+
+declare function noise(maxDistance: Vector): Shuffler;
+
+declare function noop(): void;
+
+declare type Size = {
+    radio: Vector;
+    diameter: Vector;
+};
+
+declare function radio(value: Vector | number): Size;
+
+declare function diameter(value: Vector | number): Size;
+
 declare type SpatialMetadata = {
-    targetPosition?: Position;
-    currentPosition?: Position;
+    targetPosition?: Vector;
+    currentPosition?: Vector;
 };
 
 /**
@@ -754,10 +882,11 @@ declare type SpatialMetadata = {
  * and pieces and puzzles that are annotated with it
  */
 declare module "SpatialMetadata" {
+    function diffToTarget(piece: Piece): void;
     function solved(): void;
     function relativePosition(): void;
     function absolutePosition(): void;
-    function initialize(metadata: SpatialMetadata, target: Position, current?: Position): void;
+    function initialize(metadata: SpatialMetadata, target: Vector, current?: Vector): void;
 }
 
 declare type Structure = {
@@ -778,6 +907,33 @@ declare type Validator = PieceValidator | PuzzleValidator | NullValidator;
 
 declare type ValidationListener = (puzzle: Puzzle) => void;
 
+declare class AbstractValidator {
+    validListeners: ValidationListener[];
+    /**
+     * Validates the puzzle, updating the validity state and
+     * firing validation events
+     */
+    validate(puzzle: Puzzle): void;
+    /**
+     * Updates the valid state.
+     */
+    updateValidity(puzzle: Puzzle): void;
+    fireValid(puzzle: Puzzle): void;
+    /**
+     * Registers a validation listener
+     */
+    onValid(f: ValidationListener): void;
+    /**
+     * Answers the current validity status of this validator. This
+     * property neither alters the current status nor triggers new validity checks
+     */
+    valid: boolean;
+    /**
+     * Answers wether this is the {@link NullValidator}
+     */
+    isNull: boolean;
+}
+
 declare type PieceCondition = (puzzle: Piece) => boolean;
 
 declare type PuzzleCondition = (puzzle: Puzzle) => boolean;
@@ -790,9 +946,20 @@ declare class PieceValidator {
     isValid(puzzle: Puzzle): boolean;
 }
 
+/**
+ * A validator that evaluates the whole puzzle
+ */
 declare class PuzzleValidator {
     constructor(f: PuzzleCondition);
     isValid(puzzle: Puzzle): void;
+    /**
+     * Compares two pairs
+     */
+    static equalDiffs(param0: Pair, param1: Pair): boolean;
+    /**
+     * The delta used to compare distances
+     */
+    static DIFF_DELTA: number;
     static connected(): void;
     /**
      * @param expected - the expected relative refs
@@ -800,3 +967,50 @@ declare class PuzzleValidator {
     static relativeRefs(expected: Pair[]): PuzzleCondition;
 }
 
+/**
+ * A validator that always is invalid
+ */
+declare class NullValidator {
+    isValid(puzzle: Puzzle): void;
+    isNull: boolean;
+}
+
+declare type Vector = {
+    x: number;
+    y: number;
+};
+
+declare function vector(x: number, y: number): Vector;
+
+declare function cast(value: Vector | number): Vector;
+
+/**
+ * This module contains functions for dealing with objects with x and y
+ * coordinates that represent or include point data
+ */
+declare module "Vector" {
+    /**
+     * Returns a new (0, 0) vector
+     */
+    function zero(): Vector;
+    /**
+     * Compares two points
+     * @param [delta = 0] - the tolance in comparison
+     */
+    function equal(one: Vector, other: Vector, delta?: number): boolean;
+    /**
+     * Creates a copy of the given point
+     */
+    function copy(one: Vector): Vector;
+    function update(vector: Vector, x: any, y: any): void;
+    /**
+     * @returns ;
+     */
+    function diff(one: Vector, other: Vector): Pair;
+    function multiply(one: Vector | number, other: Vector | number): Vector;
+    function divide(one: Vector | number, other: Vector | number): Vector;
+    function plus(one: Vector | number, other: Vector | number): Vector;
+    function minus(one: Vector | number, other: Vector | number): Vector;
+    function apply(one: Vector | number, other: Vector | number, f: any): Vector;
+}
+