packing-bingo 0.2.0 → 0.4.0

package/dist/core.d.cts

@@ -3,13 +3,27 @@ interface BingoItem {
     emoji: string;
     label: string;
 }
-/** The default 16 school-trip items (Japanese), listed row by row from the top left. */
+/**
+ * The default 16 school-trip items (Japanese), listed row by row from the top left.
+ * Smaller cards (`size` 2 or 3, without `items`) use the first ones.
+ * Labels keep each unbreakable run to about 6 characters so they fit the narrow (phone) card;
+ * `\u200B` marks where a longer label may wrap.
+ */
 declare const DEFAULT_ITEMS: readonly BingoItem[];
 
+/**
+ * The winning lines of a size × size card, as indices into its items (row by row, skipping the
+ * FREE square): first the rows, then the columns, then the diagonal from the top left and the
+ * one from the top right. With `free`, the lines through the center have size − 1 items.
+ */
+declare function bingoLines(size: number, free?: boolean): number[][];
+
 /** Every piece of UI text. Pass a partial object as `messages` to override some of them. */
 interface Messages {
     title: string;
+    /** A label above the title; empty (not shown) by default. */
     tag: string;
+    /** A line under the title; empty (not shown) by default. */
     subtitle: string;
     packed: string;
     bingo: string;
@@ -17,9 +31,13 @@ interface Messages {
     combo: (n: number) => string;
     comboPop: (n: number) => string;
     reset: string;
+    /** The button that moves the items to random squares. */
+    shuffle: string;
     soundOn: string;
     soundOff: string;
     stamp: string;
+    /** Text on the FREE square in the center (with `free`). */
+    free: string;
     reachBadge: string;
     reachPop: string;
     bannerSingle: string;
@@ -27,17 +45,18 @@ interface Messages {
     bannerTriple: string;
     bannerNth: (totalLines: number) => string;
     bannerMulti: (newLines: number) => string;
+    /** The status line before the first line is complete; empty by default. */
     statusStart: (left: number) => string;
     statusLines: (lines: number, left: number) => string;
-    /** `labels` are the items that would each complete a line right now. */
+    /** `labels` are the items that would each complete a line right now; empty by default. */
     statusReach: (labels: string[]) => string;
     statusDone: string;
     perfectTag: string;
     /** Text inside the round stamp; `\n` starts a new line. */
     perfectStamp: string;
     perfectTitle: string;
-    /** `\n` starts a new line. */
-    perfectBody: string;
+    /** `\n` starts a new line. As a function, it gets the number of items on the card. */
+    perfectBody: string | ((total: number) => string);
     perfectBonus: (points: number) => string;
     statScore: string;
     statCombo: string;
@@ -53,19 +72,31 @@ declare const ja: Messages;
 /** English. */
 declare const en: Messages;
 
-/** The 10 winning lines of a 4×4 card: 4 rows, 4 columns, 2 diagonals (indices are row-major). */
+/**
+ * The 10 winning lines of a 4×4 card: 4 rows, 4 columns, 2 diagonals (indices are row-major).
+ * For other sizes, use `bingoLines(size, free)`.
+ */
 declare const LINES: readonly (readonly number[])[];
 interface PackingBingoState {
-    /** 16 booleans, row-major. */
+    /** One boolean per item, row by row (the FREE square is not included). */
     checked: boolean[];
-    /** Indices into LINES of the completed lines. */
+    /** The completed lines, as indices into `bingoLines(size, free)`. */
     lines: number[];
     score: number;
     maxCombo: number;
     complete: boolean;
+    /** Squares per side. */
+    size: number;
+    /** Whether the center is a FREE square. */
+    free: boolean;
+    /**
+     * The item in each slot (row by row, skipping the FREE square): `[0, 1, 2, …]` until the card
+     * is shuffled. Line `k` holds the items `bingoLines(size, free)[k].map((s) => order[s])`.
+     */
+    order: number[];
 }
 interface BingoEvent {
-    /** Lines (indices into LINES) completed by this change. */
+    /** Lines (indices into `bingoLines(size, free)`, which is LINES for 4×4) completed by this change. */
     newLines: number[];
     totalLines: number;
     score: number;
@@ -75,14 +106,27 @@ interface PerfectEvent {
     maxCombo: number;
 }
 interface PackingBingoOptions {
-    /** Exactly 16 items, row by row. Defaults to a Japanese school-trip list. */
+    /**
+     * One item per square, row by row (skipping the FREE square). Defaults to a Japanese
+     * school-trip list of 16. The count sets the size unless `size` is given: 9 → 3×3, 16 → 4×4.
+     */
     items?: readonly BingoItem[];
+    /**
+     * Squares per side, 2 to 10. By default it follows the number of items. Without `items`,
+     * a 2×2 or 3×3 card uses the first default items.
+     */
+    size?: number;
+    /**
+     * Make the center a FREE square (odd sizes only): it is always stamped and counts toward the
+     * lines through it. `items`, `checked` and `defaultChecked` then have size² − 1 entries.
+     */
+    free?: boolean;
     /** Overrides for UI text. Start from `ja` (default) or `en`. */
     messages?: Partial<Messages>;
     title?: string;
     tag?: string;
     subtitle?: string;
-    /** Initial state (16 booleans), used when nothing is saved under `storageKey`. */
+    /** Initial state (one boolean per item), used when nothing is saved under `storageKey`. */
     defaultChecked?: readonly boolean[];
     /**
      * When true, taps don't change the card by themselves: they call `onChange` with the
@@ -97,7 +141,27 @@ interface PackingBingoOptions {
     storageKey?: string | null;
     /** Start with sound on (default) or off. A choice made with the sound button is remembered. */
     sound?: boolean;
-    /** Load the display fonts from Google Fonts (default true). */
+    /**
+     * Show the 🔀 button that moves the items to random squares (default true). Checks stay with
+     * their items. The arrangement is saved next to the checks, under "packing-bingo-order:" +
+     * the storage key.
+     */
+    shuffle?: boolean;
+    /**
+     * The starting arrangement, as in `getState().order`, used when no shuffled arrangement is
+     * saved. Ignored unless it lists every item index exactly once.
+     */
+    defaultOrder?: readonly number[];
+    /**
+     * Buzz on phones (default true): a short buzz on each tap and longer patterns for a bingo, a
+     * perfect card and a shuffle where the Vibration API exists (Android), and the system tap
+     * haptic on iPhone (iOS 18 and later), which only follows a real tap.
+     */
+    vibrate?: boolean;
+    /**
+     * @deprecated Ignored since 0.4.0: the card no longer loads fonts. To get Dela Gothic One and
+     * M PLUS Rounded 1c, load them on the page (see the README's フォント section).
+     */
     fonts?: boolean;
     /** Pre-fill a few items and show demo buttons. */
     demo?: boolean;
@@ -113,8 +177,13 @@ interface PackingBingoInstance {
     setChecked(next: readonly boolean[], options?: {
         animate?: boolean;
     }): void;
-    /** Clear the card and score (calls onChange). */
+    /** Clear the card and score (calls onChange), and put the items back in their own squares. */
     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;
     getState(): PackingBingoState;
     /** Redraw the status text, e.g. after functions in `messages` start returning something else. */
     refresh(): void;
@@ -124,5 +193,5 @@ interface PackingBingoInstance {
 /** Render a packing bingo card into `container`. Call only in the browser. */
 declare function createPackingBingo(container: HTMLElement, options?: PackingBingoOptions): PackingBingoInstance;
 
-export { DEFAULT_ITEMS, LINES, createPackingBingo, en, ja };
+export { DEFAULT_ITEMS, LINES, bingoLines, createPackingBingo, en, ja };
 export type { BingoEvent, BingoItem, Messages, PackingBingoInstance, PackingBingoOptions, PackingBingoState, PerfectEvent };

package/dist/core.d.ts

@@ -3,13 +3,27 @@ interface BingoItem {
     emoji: string;
     label: string;
 }
-/** The default 16 school-trip items (Japanese), listed row by row from the top left. */
+/**
+ * The default 16 school-trip items (Japanese), listed row by row from the top left.
+ * Smaller cards (`size` 2 or 3, without `items`) use the first ones.
+ * Labels keep each unbreakable run to about 6 characters so they fit the narrow (phone) card;
+ * `\u200B` marks where a longer label may wrap.
+ */
 declare const DEFAULT_ITEMS: readonly BingoItem[];
 
+/**
+ * The winning lines of a size × size card, as indices into its items (row by row, skipping the
+ * FREE square): first the rows, then the columns, then the diagonal from the top left and the
+ * one from the top right. With `free`, the lines through the center have size − 1 items.
+ */
+declare function bingoLines(size: number, free?: boolean): number[][];
+
 /** Every piece of UI text. Pass a partial object as `messages` to override some of them. */
 interface Messages {
     title: string;
+    /** A label above the title; empty (not shown) by default. */
     tag: string;
+    /** A line under the title; empty (not shown) by default. */
     subtitle: string;
     packed: string;
     bingo: string;
@@ -17,9 +31,13 @@ interface Messages {
     combo: (n: number) => string;
     comboPop: (n: number) => string;
     reset: string;
+    /** The button that moves the items to random squares. */
+    shuffle: string;
     soundOn: string;
     soundOff: string;
     stamp: string;
+    /** Text on the FREE square in the center (with `free`). */
+    free: string;
     reachBadge: string;
     reachPop: string;
     bannerSingle: string;
@@ -27,17 +45,18 @@ interface Messages {
     bannerTriple: string;
     bannerNth: (totalLines: number) => string;
     bannerMulti: (newLines: number) => string;
+    /** The status line before the first line is complete; empty by default. */
     statusStart: (left: number) => string;
     statusLines: (lines: number, left: number) => string;
-    /** `labels` are the items that would each complete a line right now. */
+    /** `labels` are the items that would each complete a line right now; empty by default. */
     statusReach: (labels: string[]) => string;
     statusDone: string;
     perfectTag: string;
     /** Text inside the round stamp; `\n` starts a new line. */
     perfectStamp: string;
     perfectTitle: string;
-    /** `\n` starts a new line. */
-    perfectBody: string;
+    /** `\n` starts a new line. As a function, it gets the number of items on the card. */
+    perfectBody: string | ((total: number) => string);
     perfectBonus: (points: number) => string;
     statScore: string;
     statCombo: string;
@@ -53,19 +72,31 @@ declare const ja: Messages;
 /** English. */
 declare const en: Messages;
 
-/** The 10 winning lines of a 4×4 card: 4 rows, 4 columns, 2 diagonals (indices are row-major). */
+/**
+ * The 10 winning lines of a 4×4 card: 4 rows, 4 columns, 2 diagonals (indices are row-major).
+ * For other sizes, use `bingoLines(size, free)`.
+ */
 declare const LINES: readonly (readonly number[])[];
 interface PackingBingoState {
-    /** 16 booleans, row-major. */
+    /** One boolean per item, row by row (the FREE square is not included). */
     checked: boolean[];
-    /** Indices into LINES of the completed lines. */
+    /** The completed lines, as indices into `bingoLines(size, free)`. */
     lines: number[];
     score: number;
     maxCombo: number;
     complete: boolean;
+    /** Squares per side. */
+    size: number;
+    /** Whether the center is a FREE square. */
+    free: boolean;
+    /**
+     * The item in each slot (row by row, skipping the FREE square): `[0, 1, 2, …]` until the card
+     * is shuffled. Line `k` holds the items `bingoLines(size, free)[k].map((s) => order[s])`.
+     */
+    order: number[];
 }
 interface BingoEvent {
-    /** Lines (indices into LINES) completed by this change. */
+    /** Lines (indices into `bingoLines(size, free)`, which is LINES for 4×4) completed by this change. */
     newLines: number[];
     totalLines: number;
     score: number;
@@ -75,14 +106,27 @@ interface PerfectEvent {
     maxCombo: number;
 }
 interface PackingBingoOptions {
-    /** Exactly 16 items, row by row. Defaults to a Japanese school-trip list. */
+    /**
+     * One item per square, row by row (skipping the FREE square). Defaults to a Japanese
+     * school-trip list of 16. The count sets the size unless `size` is given: 9 → 3×3, 16 → 4×4.
+     */
     items?: readonly BingoItem[];
+    /**
+     * Squares per side, 2 to 10. By default it follows the number of items. Without `items`,
+     * a 2×2 or 3×3 card uses the first default items.
+     */
+    size?: number;
+    /**
+     * Make the center a FREE square (odd sizes only): it is always stamped and counts toward the
+     * lines through it. `items`, `checked` and `defaultChecked` then have size² − 1 entries.
+     */
+    free?: boolean;
     /** Overrides for UI text. Start from `ja` (default) or `en`. */
     messages?: Partial<Messages>;
     title?: string;
     tag?: string;
     subtitle?: string;
-    /** Initial state (16 booleans), used when nothing is saved under `storageKey`. */
+    /** Initial state (one boolean per item), used when nothing is saved under `storageKey`. */
     defaultChecked?: readonly boolean[];
     /**
      * When true, taps don't change the card by themselves: they call `onChange` with the
@@ -97,7 +141,27 @@ interface PackingBingoOptions {
     storageKey?: string | null;
     /** Start with sound on (default) or off. A choice made with the sound button is remembered. */
     sound?: boolean;
-    /** Load the display fonts from Google Fonts (default true). */
+    /**
+     * Show the 🔀 button that moves the items to random squares (default true). Checks stay with
+     * their items. The arrangement is saved next to the checks, under "packing-bingo-order:" +
+     * the storage key.
+     */
+    shuffle?: boolean;
+    /**
+     * The starting arrangement, as in `getState().order`, used when no shuffled arrangement is
+     * saved. Ignored unless it lists every item index exactly once.
+     */
+    defaultOrder?: readonly number[];
+    /**
+     * Buzz on phones (default true): a short buzz on each tap and longer patterns for a bingo, a
+     * perfect card and a shuffle where the Vibration API exists (Android), and the system tap
+     * haptic on iPhone (iOS 18 and later), which only follows a real tap.
+     */
+    vibrate?: boolean;
+    /**
+     * @deprecated Ignored since 0.4.0: the card no longer loads fonts. To get Dela Gothic One and
+     * M PLUS Rounded 1c, load them on the page (see the README's フォント section).
+     */
     fonts?: boolean;
     /** Pre-fill a few items and show demo buttons. */
     demo?: boolean;
@@ -113,8 +177,13 @@ interface PackingBingoInstance {
     setChecked(next: readonly boolean[], options?: {
         animate?: boolean;
     }): void;
-    /** Clear the card and score (calls onChange). */
+    /** Clear the card and score (calls onChange), and put the items back in their own squares. */
     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;
     getState(): PackingBingoState;
     /** Redraw the status text, e.g. after functions in `messages` start returning something else. */
     refresh(): void;
@@ -124,5 +193,5 @@ interface PackingBingoInstance {
 /** Render a packing bingo card into `container`. Call only in the browser. */
 declare function createPackingBingo(container: HTMLElement, options?: PackingBingoOptions): PackingBingoInstance;
 
-export { DEFAULT_ITEMS, LINES, createPackingBingo, en, ja };
+export { DEFAULT_ITEMS, LINES, bingoLines, createPackingBingo, en, ja };
 export type { BingoEvent, BingoItem, Messages, PackingBingoInstance, PackingBingoOptions, PackingBingoState, PerfectEvent };

package/dist/core.js

@@ -2,13 +2,15 @@
 import {
   DEFAULT_ITEMS,
   LINES,
+  bingoLines,
   createPackingBingo,
   en,
   ja
-} from "./chunk-WGZKPODU.js";
+} from "./chunk-BAA2CFUA.js";
 export {
   DEFAULT_ITEMS,
   LINES,
+  bingoLines,
   createPackingBingo,
   en,
   ja