packing-bingo 0.1.1 → 0.3.0

package/dist/core.d.cts

@@ -3,13 +3,26 @@ 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;
     tag: string;
+    /** A line under the title; empty (not shown) by default. */
     subtitle: string;
     packed: string;
     bingo: string;
@@ -20,6 +33,8 @@ interface Messages {
     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,6 +42,7 @@ 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. */
@@ -36,8 +52,8 @@ interface Messages {
     /** 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 +69,26 @@ 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;
 }
 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,21 +98,38 @@ 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
      * requested state, and the card only changes through `setChecked`. (React's `checked` prop.)
      */
     controlled?: boolean;
-    /** Save and restore the checks in localStorage under this key. Ignored when controlled. */
+    /**
+     * Where the checks are saved in localStorage. By default (omitted) a key derived from the
+     * items is used, so progress is saved automatically; pass a string to choose the key, or null
+     * to turn saving off. Ignored when controlled. Demo cards only save when given a key.
+     */
     storageKey?: string | null;
     /** Start with sound on (default) or off. A choice made with the sound button is remembered. */
     sound?: boolean;
@@ -120,5 +160,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,26 @@ 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;
     tag: string;
+    /** A line under the title; empty (not shown) by default. */
     subtitle: string;
     packed: string;
     bingo: string;
@@ -20,6 +33,8 @@ interface Messages {
     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,6 +42,7 @@ 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. */
@@ -36,8 +52,8 @@ interface Messages {
     /** 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 +69,26 @@ 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;
 }
 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,21 +98,38 @@ 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
      * requested state, and the card only changes through `setChecked`. (React's `checked` prop.)
      */
     controlled?: boolean;
-    /** Save and restore the checks in localStorage under this key. Ignored when controlled. */
+    /**
+     * Where the checks are saved in localStorage. By default (omitted) a key derived from the
+     * items is used, so progress is saved automatically; pass a string to choose the key, or null
+     * to turn saving off. Ignored when controlled. Demo cards only save when given a key.
+     */
     storageKey?: string | null;
     /** Start with sound on (default) or off. A choice made with the sound button is remembered. */
     sound?: boolean;
@@ -120,5 +160,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-ZDBGKPFF.js";
+} from "./chunk-Z34GMJW2.js";
 export {
   DEFAULT_ITEMS,
   LINES,
+  bingoLines,
   createPackingBingo,
   en,
   ja