packing-bingo 0.5.0 → 0.6.0

package/dist/core.d.cts

@@ -35,13 +35,55 @@ interface Messages {
     shuffle: string;
     soundOn: string;
     soundOff: string;
-    /** Volume reminder in the pre-play popup; an empty string hides it. */
+    /** The big line on the gray start screen over the card (with the `ready` option). */
+    readyTitle?: string;
+    /** A line under it; empty (not shown) by default. */
+    readyPrompt?: string;
+    /** Volume reminder on the start screen; an empty string hides it. */
     soundHint?: string;
     /** Android Do Not Disturb reminder; hidden when vibration is disabled or this is empty. */
     vibrationHint?: string;
-    /** Pre-play popup title and buttons. */
+    /** The "tap to start" cue on the start screen. */
+    readyTap?: string;
+    /** Shown after the 3, 2, 1 countdown, as the stopwatch starts. */
+    readyGo?: string;
+    /** Label of the stopwatch, read out by screen readers. */
+    time?: string;
+    /** Before the finishing time on the perfect card. */
+    statTime?: string;
+    /** Floats up with the points for the clear time (`speedBonus`). */
+    speedBonus?: (points: number) => string;
+    /** Label of the mode switch, read out by screen readers. */
+    modeLabel?: string;
+    /** The mode switch's choice for the normal card. */
+    modeNormal?: string;
+    /** The mode switch's choice for the infinite mode. */
+    modeInfinite?: string;
+    /** The big word that sweeps over the card when the normal mode is chosen. */
+    normalTitle?: string;
+    /** The line under it. */
+    normalSub?: string;
+    /** The big word that sweeps over the card when the infinite mode is chosen. */
+    infiniteTitle?: string;
+    /** The line under it, also shown in the start screen's badge in the infinite mode. */
+    infiniteSub?: string;
+    /** The rule, shown on the start screen in the infinite mode; an empty string hides it. */
+    infiniteRule?: string;
+    /** The button that ends an infinite game and shows its results. */
+    finish?: string;
+    /** Title of the infinite game's results. */
+    finishTitle?: string;
+    /** Text inside the round medal on those results; `\n` starts a new line. */
+    finishStamp?: string;
+    /** Before the time played on those results. */
+    finishTime?: string;
+    /** The results' button that starts a new infinite game. */
+    again?: string;
+    /** @deprecated Ignored since 0.6.0: the pre-play popup became the start screen (see `readyTitle`). */
     playTitle?: string;
+    /** @deprecated Ignored since 0.6.0. */
     playStart?: string;
+    /** @deprecated Ignored since 0.6.0. */
     playSkip?: string;
     stamp: string;
     /** Text on the FREE square in the center (with `free`). */
@@ -85,14 +127,37 @@ declare const en: Messages;
  * For other sizes, use `bingoLines(size, free)`.
  */
 declare const LINES: readonly (readonly number[])[];
+/**
+ * "normal": the packing card. "infinite": an endless game on the same squares; completed lines
+ * clear so they can be filled again. It never touches the packing checks.
+ */
+type BingoMode = "normal" | "infinite";
 interface PackingBingoState {
-    /** One boolean per item, row by row (the FREE square is not included). */
+    /**
+     * One boolean per item, row by row (the FREE square is not included). In the infinite mode,
+     * the squares of that game, not the packing checks.
+     */
     checked: boolean[];
     /** The completed lines, as indices into `bingoLines(size, free)`. */
     lines: number[];
     score: number;
     maxCombo: number;
+    /** Every item is checked (always false in the infinite mode). */
     complete: boolean;
+    /** The mode on the card. */
+    mode: BingoMode;
+    /** Lines completed in this infinite game (each one clears); 0 in the normal mode. */
+    cleared: number;
+    /** The infinite game was ended with FINISH (its squares are locked until a new game). */
+    finished: boolean;
+    /**
+     * In the infinite mode, the packing card waiting behind the game: its checks and arrangement,
+     * as they will be when the card switches back. Null in the normal mode.
+     */
+    packing: {
+        checked: boolean[];
+        order: number[];
+    } | null;
     /** Squares per side. */
     size: number;
     /** Whether the center is a FREE square. */
@@ -102,16 +167,34 @@ interface PackingBingoState {
      * is shuffled. Line `k` holds the items `bingoLines(size, free)[k].map((s) => order[s])`.
      */
     order: number[];
+    /** The stopwatch in milliseconds: running since the countdown (or the first tap), frozen once the card is complete. */
+    time: number;
 }
 interface BingoEvent {
     /** Lines (indices into `bingoLines(size, free)`, which is LINES for 4×4) completed by this change. */
     newLines: number[];
+    /** Lines complete on the card; in the infinite mode, lines completed in this game. */
     totalLines: number;
     score: number;
+    /** The mode it happened in. */
+    mode: BingoMode;
 }
 interface PerfectEvent {
     score: number;
     maxCombo: number;
+    /** The stopwatch when the card was completed, in milliseconds; null if this game was not timed. */
+    time: number | null;
+    /** Points `score` got for the clear time (see `speedBonus`); 0 if none were given. */
+    speedBonus: number;
+}
+/** An infinite game ended with FINISH. */
+interface FinishEvent {
+    score: number;
+    maxCombo: number;
+    /** Lines completed in the game. */
+    lines: number;
+    /** The stopwatch when it ended, in milliseconds. */
+    time: number;
 }
 interface PackingBingoOptions {
     /**
@@ -171,11 +254,36 @@ interface PackingBingoOptions {
      * M PLUS Rounded 1c, load them on the page (see the README's フォント section).
      */
     fonts?: boolean;
+    /**
+     * Start each game on a see-through dark screen over the whole card ("Are you ready?" with the
+     * volume and Do Not Disturb reminders); a tap counts down 3, 2, 1 and starts the stopwatch
+     * (default true). With false, the stopwatch starts on the first tap.
+     */
+    ready?: boolean;
+    /**
+     * Let a tap on a stamped square take the stamp off again (default false). By default a
+     * stamped square stays stamped when tapped; `reset()`, `setChecked` and controlled `checked`
+     * can still clear it.
+     */
+    uncheck?: boolean;
+    /**
+     * The mode to start in (default "normal"). "infinite" is an endless game on the same squares:
+     * every completed line clears after its celebration, so it can be filled again, and the
+     * score keeps growing. It neither changes nor saves the packing checks, and calls no
+     * `onChange`; switching back to "normal" brings the packing card back as it was.
+     */
+    mode?: BingoMode;
+    /** Show the NORMAL / ∞ INFINITE switch in the header (default true). */
+    modeSwitch?: boolean;
     /** Pre-fill a few items and show demo buttons. */
     demo?: boolean;
     onChange?: (checked: boolean[]) => void;
     onBingo?: (event: BingoEvent) => void;
     onPerfect?: (event: PerfectEvent) => void;
+    /** The mode was changed, with the switch or `setMode`. */
+    onModeChange?: (mode: BingoMode) => void;
+    /** An infinite game was ended with the 🏁 FINISH button or `finish()`. */
+    onFinish?: (event: FinishEvent) => void;
 }
 interface PackingBingoInstance {
     /**
@@ -185,21 +293,41 @@ interface PackingBingoInstance {
     setChecked(next: readonly boolean[], options?: {
         animate?: boolean;
     }): void;
-    /** Clear the card and score (calls onChange), and put the items back in their own squares. */
+    /**
+     * Clear the card and score (calls onChange), and put the items back in their own squares.
+     * In the infinite mode, like the reset button, it starts a new infinite game instead.
+     */
     reset(): void;
     /**
      * Move the items to random squares, as the 🔀 button does. Checks stay with their items; lines
      * the new arrangement happens to complete count as done but earn no points.
      */
     shuffle(): void;
+    /**
+     * Switch modes, as the switch does (with its animation). Each switch starts a new game: the
+     * stopwatch and score start over, and the packing checks and arrangement are kept.
+     */
+    setMode(mode: BingoMode): void;
+    /**
+     * End a running infinite game, as the 🏁 FINISH button does: stop the stopwatch, lock the
+     * squares and show the results. Does nothing in the normal mode or before the game starts.
+     */
+    finish(): void;
     getState(): PackingBingoState;
     /** Redraw the status text, e.g. after functions in `messages` start returning something else. */
     refresh(): void;
     /** Stop everything and remove the card from the container. */
     destroy(): void;
 }
+/** Stopwatch text: 0:12.3 (or 1:02:03.4 past an hour); `digits` decimals of a second. */
+declare function formatTime(ms: number, digits?: number): string;
+/**
+ * Points for clearing a card of `items` items in `ms` milliseconds: 1000 per item per second,
+ * so it has no ceiling. Halving the time doubles it.
+ */
+declare function speedBonus(items: number, ms: number): number;
 /** Render a packing bingo card into `container`. Call only in the browser. */
 declare function createPackingBingo(container: HTMLElement, options?: PackingBingoOptions): PackingBingoInstance;
 
-export { DEFAULT_ITEMS, LINES, bingoLines, createPackingBingo, en, ja };
-export type { BingoEvent, BingoItem, Messages, PackingBingoInstance, PackingBingoOptions, PackingBingoState, PerfectEvent };
+export { DEFAULT_ITEMS, LINES, bingoLines, createPackingBingo, en, formatTime, ja, speedBonus };
+export type { BingoEvent, BingoItem, BingoMode, FinishEvent, Messages, PackingBingoInstance, PackingBingoOptions, PackingBingoState, PerfectEvent };

package/dist/core.d.ts

@@ -35,13 +35,55 @@ interface Messages {
     shuffle: string;
     soundOn: string;
     soundOff: string;
-    /** Volume reminder in the pre-play popup; an empty string hides it. */
+    /** The big line on the gray start screen over the card (with the `ready` option). */
+    readyTitle?: string;
+    /** A line under it; empty (not shown) by default. */
+    readyPrompt?: string;
+    /** Volume reminder on the start screen; an empty string hides it. */
     soundHint?: string;
     /** Android Do Not Disturb reminder; hidden when vibration is disabled or this is empty. */
     vibrationHint?: string;
-    /** Pre-play popup title and buttons. */
+    /** The "tap to start" cue on the start screen. */
+    readyTap?: string;
+    /** Shown after the 3, 2, 1 countdown, as the stopwatch starts. */
+    readyGo?: string;
+    /** Label of the stopwatch, read out by screen readers. */
+    time?: string;
+    /** Before the finishing time on the perfect card. */
+    statTime?: string;
+    /** Floats up with the points for the clear time (`speedBonus`). */
+    speedBonus?: (points: number) => string;
+    /** Label of the mode switch, read out by screen readers. */
+    modeLabel?: string;
+    /** The mode switch's choice for the normal card. */
+    modeNormal?: string;
+    /** The mode switch's choice for the infinite mode. */
+    modeInfinite?: string;
+    /** The big word that sweeps over the card when the normal mode is chosen. */
+    normalTitle?: string;
+    /** The line under it. */
+    normalSub?: string;
+    /** The big word that sweeps over the card when the infinite mode is chosen. */
+    infiniteTitle?: string;
+    /** The line under it, also shown in the start screen's badge in the infinite mode. */
+    infiniteSub?: string;
+    /** The rule, shown on the start screen in the infinite mode; an empty string hides it. */
+    infiniteRule?: string;
+    /** The button that ends an infinite game and shows its results. */
+    finish?: string;
+    /** Title of the infinite game's results. */
+    finishTitle?: string;
+    /** Text inside the round medal on those results; `\n` starts a new line. */
+    finishStamp?: string;
+    /** Before the time played on those results. */
+    finishTime?: string;
+    /** The results' button that starts a new infinite game. */
+    again?: string;
+    /** @deprecated Ignored since 0.6.0: the pre-play popup became the start screen (see `readyTitle`). */
     playTitle?: string;
+    /** @deprecated Ignored since 0.6.0. */
     playStart?: string;
+    /** @deprecated Ignored since 0.6.0. */
     playSkip?: string;
     stamp: string;
     /** Text on the FREE square in the center (with `free`). */
@@ -85,14 +127,37 @@ declare const en: Messages;
  * For other sizes, use `bingoLines(size, free)`.
  */
 declare const LINES: readonly (readonly number[])[];
+/**
+ * "normal": the packing card. "infinite": an endless game on the same squares; completed lines
+ * clear so they can be filled again. It never touches the packing checks.
+ */
+type BingoMode = "normal" | "infinite";
 interface PackingBingoState {
-    /** One boolean per item, row by row (the FREE square is not included). */
+    /**
+     * One boolean per item, row by row (the FREE square is not included). In the infinite mode,
+     * the squares of that game, not the packing checks.
+     */
     checked: boolean[];
     /** The completed lines, as indices into `bingoLines(size, free)`. */
     lines: number[];
     score: number;
     maxCombo: number;
+    /** Every item is checked (always false in the infinite mode). */
     complete: boolean;
+    /** The mode on the card. */
+    mode: BingoMode;
+    /** Lines completed in this infinite game (each one clears); 0 in the normal mode. */
+    cleared: number;
+    /** The infinite game was ended with FINISH (its squares are locked until a new game). */
+    finished: boolean;
+    /**
+     * In the infinite mode, the packing card waiting behind the game: its checks and arrangement,
+     * as they will be when the card switches back. Null in the normal mode.
+     */
+    packing: {
+        checked: boolean[];
+        order: number[];
+    } | null;
     /** Squares per side. */
     size: number;
     /** Whether the center is a FREE square. */
@@ -102,16 +167,34 @@ interface PackingBingoState {
      * is shuffled. Line `k` holds the items `bingoLines(size, free)[k].map((s) => order[s])`.
      */
     order: number[];
+    /** The stopwatch in milliseconds: running since the countdown (or the first tap), frozen once the card is complete. */
+    time: number;
 }
 interface BingoEvent {
     /** Lines (indices into `bingoLines(size, free)`, which is LINES for 4×4) completed by this change. */
     newLines: number[];
+    /** Lines complete on the card; in the infinite mode, lines completed in this game. */
     totalLines: number;
     score: number;
+    /** The mode it happened in. */
+    mode: BingoMode;
 }
 interface PerfectEvent {
     score: number;
     maxCombo: number;
+    /** The stopwatch when the card was completed, in milliseconds; null if this game was not timed. */
+    time: number | null;
+    /** Points `score` got for the clear time (see `speedBonus`); 0 if none were given. */
+    speedBonus: number;
+}
+/** An infinite game ended with FINISH. */
+interface FinishEvent {
+    score: number;
+    maxCombo: number;
+    /** Lines completed in the game. */
+    lines: number;
+    /** The stopwatch when it ended, in milliseconds. */
+    time: number;
 }
 interface PackingBingoOptions {
     /**
@@ -171,11 +254,36 @@ interface PackingBingoOptions {
      * M PLUS Rounded 1c, load them on the page (see the README's フォント section).
      */
     fonts?: boolean;
+    /**
+     * Start each game on a see-through dark screen over the whole card ("Are you ready?" with the
+     * volume and Do Not Disturb reminders); a tap counts down 3, 2, 1 and starts the stopwatch
+     * (default true). With false, the stopwatch starts on the first tap.
+     */
+    ready?: boolean;
+    /**
+     * Let a tap on a stamped square take the stamp off again (default false). By default a
+     * stamped square stays stamped when tapped; `reset()`, `setChecked` and controlled `checked`
+     * can still clear it.
+     */
+    uncheck?: boolean;
+    /**
+     * The mode to start in (default "normal"). "infinite" is an endless game on the same squares:
+     * every completed line clears after its celebration, so it can be filled again, and the
+     * score keeps growing. It neither changes nor saves the packing checks, and calls no
+     * `onChange`; switching back to "normal" brings the packing card back as it was.
+     */
+    mode?: BingoMode;
+    /** Show the NORMAL / ∞ INFINITE switch in the header (default true). */
+    modeSwitch?: boolean;
     /** Pre-fill a few items and show demo buttons. */
     demo?: boolean;
     onChange?: (checked: boolean[]) => void;
     onBingo?: (event: BingoEvent) => void;
     onPerfect?: (event: PerfectEvent) => void;
+    /** The mode was changed, with the switch or `setMode`. */
+    onModeChange?: (mode: BingoMode) => void;
+    /** An infinite game was ended with the 🏁 FINISH button or `finish()`. */
+    onFinish?: (event: FinishEvent) => void;
 }
 interface PackingBingoInstance {
     /**
@@ -185,21 +293,41 @@ interface PackingBingoInstance {
     setChecked(next: readonly boolean[], options?: {
         animate?: boolean;
     }): void;
-    /** Clear the card and score (calls onChange), and put the items back in their own squares. */
+    /**
+     * Clear the card and score (calls onChange), and put the items back in their own squares.
+     * In the infinite mode, like the reset button, it starts a new infinite game instead.
+     */
     reset(): void;
     /**
      * Move the items to random squares, as the 🔀 button does. Checks stay with their items; lines
      * the new arrangement happens to complete count as done but earn no points.
      */
     shuffle(): void;
+    /**
+     * Switch modes, as the switch does (with its animation). Each switch starts a new game: the
+     * stopwatch and score start over, and the packing checks and arrangement are kept.
+     */
+    setMode(mode: BingoMode): void;
+    /**
+     * End a running infinite game, as the 🏁 FINISH button does: stop the stopwatch, lock the
+     * squares and show the results. Does nothing in the normal mode or before the game starts.
+     */
+    finish(): void;
     getState(): PackingBingoState;
     /** Redraw the status text, e.g. after functions in `messages` start returning something else. */
     refresh(): void;
     /** Stop everything and remove the card from the container. */
     destroy(): void;
 }
+/** Stopwatch text: 0:12.3 (or 1:02:03.4 past an hour); `digits` decimals of a second. */
+declare function formatTime(ms: number, digits?: number): string;
+/**
+ * Points for clearing a card of `items` items in `ms` milliseconds: 1000 per item per second,
+ * so it has no ceiling. Halving the time doubles it.
+ */
+declare function speedBonus(items: number, ms: number): number;
 /** Render a packing bingo card into `container`. Call only in the browser. */
 declare function createPackingBingo(container: HTMLElement, options?: PackingBingoOptions): PackingBingoInstance;
 
-export { DEFAULT_ITEMS, LINES, bingoLines, createPackingBingo, en, ja };
-export type { BingoEvent, BingoItem, Messages, PackingBingoInstance, PackingBingoOptions, PackingBingoState, PerfectEvent };
+export { DEFAULT_ITEMS, LINES, bingoLines, createPackingBingo, en, formatTime, ja, speedBonus };
+export type { BingoEvent, BingoItem, BingoMode, FinishEvent, Messages, PackingBingoInstance, PackingBingoOptions, PackingBingoState, PerfectEvent };

package/dist/core.js

@@ -5,13 +5,17 @@ import {
   bingoLines,
   createPackingBingo,
   en,
-  ja
-} from "./chunk-ZPZZDZUH.js";
+  formatTime,
+  ja,
+  speedBonus
+} from "./chunk-A5JVNVWS.js";
 export {
   DEFAULT_ITEMS,
   LINES,
   bingoLines,
   createPackingBingo,
   en,
-  ja
+  formatTime,
+  ja,
+  speedBonus
 };