@johnmorrisdotca/kumimoji 1.2.2 → 1.3.1

package/dist/tiles.constants.js

@@ -13,10 +13,40 @@
  *
  * To tune the letters, change the counts here. The total is checked by
  * `tiles.test.ts`, so an edit that loses a tile says so.
+ *
+ * @example
+ * ```ts
+ * import { TILE_MIX } from "@johnmorrisdotca/kumimoji";
+ * console.log(TILE_MIX);
+ * ```
  */
 export const TILE_MIX = {
-    a: 13, b: 3, c: 3, d: 6, e: 18, f: 3, g: 4, h: 3, i: 12, j: 2, k: 2, l: 5, m: 3,
-    n: 8, o: 11, p: 3, q: 2, r: 9, s: 6, t: 9, u: 6, v: 3, w: 3, x: 2, y: 3, z: 2,
+    a: 13,
+    b: 3,
+    c: 3,
+    d: 6,
+    e: 18,
+    f: 3,
+    g: 4,
+    h: 3,
+    i: 12,
+    j: 2,
+    k: 2,
+    l: 5,
+    m: 3,
+    n: 8,
+    o: 11,
+    p: 3,
+    q: 2,
+    r: 9,
+    s: 6,
+    t: 9,
+    u: 6,
+    v: 3,
+    w: 3,
+    x: 2,
+    y: 3,
+    z: 2,
 };
 /**
  * THE JAPANESE SET: 144 hiragana tiles in 45 kinds (`kana.ts`), as the English
@@ -31,15 +61,68 @@ export const TILE_MIX = {
  * Fixed here rather than taken from the monthly dictionary refresh, which
  * prints what it measures beside this table (`scripts/word-lists-ja.mjs`): a
  * kept game's bag is checked against these counts.
+ *
+ * @example
+ * ```ts
+ * import { JAPANESE_TILE_MIX } from "@johnmorrisdotca/kumimoji";
+ * console.log(JAPANESE_TILE_MIX);
+ * ```
  */
 export const JAPANESE_TILE_MIX = {
-    あ: 2, い: 11, う: 12, え: 1, お: 2, か: 7, き: 6, く: 6, け: 3, こ: 4,
-    さ: 3, し: 10, す: 2, せ: 3, そ: 2, た: 4, ち: 3, つ: 6, て: 2, と: 3,
-    な: 1, に: 1, ぬ: 1, ね: 1, の: 1, は: 2, ひ: 2, ふ: 2, へ: 1, ほ: 1,
-    ま: 2, み: 1, む: 1, め: 1, も: 1, や: 2, ゆ: 4, よ: 6, ら: 1, り: 3,
-    る: 3, れ: 1, ろ: 1, わ: 1, ん: 11,
+    あ: 2,
+    い: 11,
+    う: 12,
+    え: 1,
+    お: 2,
+    か: 7,
+    き: 6,
+    く: 6,
+    け: 3,
+    こ: 4,
+    さ: 3,
+    し: 10,
+    す: 2,
+    せ: 3,
+    そ: 2,
+    た: 4,
+    ち: 3,
+    つ: 6,
+    て: 2,
+    と: 3,
+    な: 1,
+    に: 1,
+    ぬ: 1,
+    ね: 1,
+    の: 1,
+    は: 2,
+    ひ: 2,
+    ふ: 2,
+    へ: 1,
+    ほ: 1,
+    ま: 2,
+    み: 1,
+    む: 1,
+    め: 1,
+    も: 1,
+    や: 2,
+    ゆ: 4,
+    よ: 6,
+    ら: 1,
+    り: 3,
+    る: 3,
+    れ: 1,
+    ろ: 1,
+    わ: 1,
+    ん: 11,
 };
-/** The whole set, counted from the table. */
+/** The whole set, counted from the table.
+ *
+ * @example
+ * ```ts
+ * import { TILE_MIX_TOTAL } from "@johnmorrisdotca/kumimoji";
+ * console.log(TILE_MIX_TOTAL);
+ * ```
+ */
 export const TILE_MIX_TOTAL = Object.values(TILE_MIX).reduce((sum, count) => sum + count, 0);
 /**
  * THERE IS NO BOARD. John, 2026-09-26: "curious if we just have a large board
@@ -48,6 +131,12 @@ export const TILE_MIX_TOTAL = Object.values(TILE_MIX).reduce((sum, count) => sum
  * grows with them (`tableView.ts`), so a grid is as wide and as tall as its
  * player builds it. This is only the most a finished grid may measure either
  * way before the check refuses it unread: fifty tiles in one line is fifty.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_GRID_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_GRID_MOST);
+ * ```
  */
 export const KUMIMOJI_GRID_MOST = 60;
 /**
@@ -55,24 +144,56 @@ export const KUMIMOJI_GRID_MOST = 60;
  * 2026-09-26: "you were given seven or 11 starting tiles". Three is for the
  * browser tests alone — a game that can be finished in a few presses — and is
  * never offered on the set-up screen.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_HANDS } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_HANDS);
+ * ```
  */
 export const KUMIMOJI_HANDS = { tiny: 3, quick: 7, classic: 11 };
 /**
  * SHORT GAME TOTALS, by opening hand. Medium and Full derive from the tile
  * inventory in `kumimojiTileCount`; these stay the existing Short lengths.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_BAG } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_BAG);
+ * ```
  */
 export const KUMIMOJI_BAG = {
     [KUMIMOJI_HANDS.tiny]: 5,
     [KUMIMOJI_HANDS.quick]: 40,
     [KUMIMOJI_HANDS.classic]: 50,
 };
-/** Wild tiles per original 40/50-tile game, included within the bag total. */
+/** Wild tiles per original 40/50-tile game, included within the bag total.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_WILDS } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_WILDS);
+ * ```
+ */
 export const KUMIMOJI_WILDS = {
     [KUMIMOJI_HANDS.tiny]: { easy: 0, medium: 0, hard: 0 },
     [KUMIMOJI_HANDS.quick]: { easy: 6, medium: 3, hard: 0 },
     [KUMIMOJI_HANDS.classic]: { easy: 8, medium: 4, hard: 0 },
 };
-/** Tile count for a selected length and inventory size. Double supplies two sets. */
+/** Tile count for a selected length and inventory size. Double supplies two sets.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param length - The game length or decoded word length, as declared.
+ * @param setSize - The number of physical tiles in the language set.
+ * @param doubleSet - Whether to use two English tile sets.
+ * @returns Tile count for a selected length and inventory size. Double supplies two sets.
+ * @example
+ * ```ts
+ * import { kumimojiTileCount } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiTileCount(7,"short"));
+ * ```
+ */
 export function kumimojiTileCount(hand, length, setSize = TILE_MIX_TOTAL, doubleSet = false) {
     const short = KUMIMOJI_BAG[hand];
     if (short === undefined)
@@ -89,7 +210,19 @@ export function kumimojiTileCount(hand, length, setSize = TILE_MIX_TOTAL, double
         return Math.floor(available / 2);
     return available;
 }
-/** Wilds scale with the bag; doubling the tile set doubles the wild count too. */
+/** Wilds scale with the bag; doubling the tile set doubles the wild count too.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param totalTiles - The total number of physical tiles in this bag.
+ * @returns Wilds scale with the bag; doubling the tile set doubles the wild count too.
+ * @example
+ * ```ts
+ * import { kumimojiWildCount, kumimojiTileCount } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiWildCount(7,"easy",kumimojiTileCount(7,"short")));
+ * ```
+ */
 export function kumimojiWildCount(hand, level, totalTiles) {
     const short = KUMIMOJI_BAG[hand];
     const wilds = KUMIMOJI_WILDS[hand];
@@ -99,13 +232,26 @@ export function kumimojiWildCount(hand, level, totalTiles) {
         throw new Error(`Invalid Kumimoji tile count: ${totalTiles}.`);
     return Math.round((wilds[level] * totalTiles) / short);
 }
-/** How many tiles one Draw takes from the bag, once the hand is used and the grid is sound. */
+/** How many tiles one Draw takes from the bag, once the hand is used and the grid is sound.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_DRAW } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_DRAW);
+ * ```
+ */
 export const KUMIMOJI_DRAW = 1;
 /**
  * THE TRADE: one awkward tile back into the bag for three new ones — the
  * classic way out of a hand of Q, X and J. The tile given back goes to the
  * bottom of the bag, so it comes round again before the end; offered only
  * while the bag has three to give.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_TRADE } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_TRADE);
+ * ```
  */
 export const KUMIMOJI_TRADE = { give: 1, take: 3 };
 /**
@@ -114,8 +260,14 @@ export const KUMIMOJI_TRADE = { give: 1, take: 3 };
  * speed, which falls away evenly until a game that took half a minute a tile
  * earns no speed at all. A Classic game of fifty tiles in ten minutes is
  * 500 + 300 = 800. The time is the browser's clock, as every solo time here is.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_SCORE } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_SCORE);
+ * ```
  */
-export const KUMIMOJI_SCORE = { tile: 10, slowestMsATile: 30000 };
+export const KUMIMOJI_SCORE = { tile: 10, slowestMsATile: 30_000 };
 /**
  * PASS AND PLAY: up to eight people round one device, each with a hand and a
  * table of their own from one shared bag (`party.ts`). John, 2026-09-28: "pass
@@ -128,5 +280,11 @@ export const KUMIMOJI_SCORE = { tile: 10, slowestMsATile: 30000 };
  * set, and chooses it when the count reaches it (John, 2026-09-28: "when having
  * 6 or more players, we should recommend the double size 288 version"); in
  * Japanese, which has no Double, the Full game instead.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_PARTY } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_PARTY);
+ * ```
  */
 export const KUMIMOJI_PARTY = { least: 2, most: 8, nameMost: 20, doubleFrom: 6 };

package/dist/turn.d.ts

@@ -17,24 +17,69 @@ import type { Area, View } from "./tableView.ts";
  * Pure, like the rest of the view (`tableView.ts`), which works on the turned
  * squares unchanged: fitting, zooming and panning are all in screen terms.
  */
-/** The next turn a press gives: a quarter clockwise, and four presses back to the start. */
+/** The next turn a press gives: a quarter clockwise, and four presses back to the start.
+ *
+ * @param turn - The number of quarter turns of the view.
+ * @returns The next turn a press gives: a quarter clockwise, and four presses back to the start.
+ * @example
+ * ```ts
+ * import { nextTurn } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(nextTurn(3));
+ * ```
+ */
 export declare function nextTurn(turn: Turn): Turn;
 /**
  * Where square (row, col) of the grid is drawn with the table turned: a
  * quarter clockwise sends a word running right to one running down, and one
  * running down to one running left. It is linear, so it turns a step (a
  * direction) as well as a square.
+ *
+ * @param row - The integer row coordinate, which may be negative.
+ * @param col - The integer column coordinate, which may be negative.
+ * @param turn - The number of quarter turns of the view.
+ * @returns Where square (row, col) of the grid is drawn with the table turned: a quarter clockwise sends a word running right to one running down, and one running down to one running left. It is linear, so it turns a step (a direction) as well as a square.
+ * @example
+ * ```ts
+ * import { turnPlace } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(turnPlace(1,2,1));
+ * ```
  */
 export declare function turnPlace(row: number, col: number, turn: Turn): {
     row: number;
     col: number;
 };
-/** The grid's square drawn at (row, col) of the turned table: `turnPlace` undone. */
+/** The grid's square drawn at (row, col) of the turned table: `turnPlace` undone.
+ *
+ * @param row - The integer row coordinate, which may be negative.
+ * @param col - The integer column coordinate, which may be negative.
+ * @param turn - The number of quarter turns of the view.
+ * @returns The grid's square drawn at (row, col) of the turned table: `turnPlace` undone.
+ * @example
+ * ```ts
+ * import { unturnPlace } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(unturnPlace(1,2,1));
+ * ```
+ */
 export declare function unturnPlace(row: number, col: number, turn: Turn): {
     row: number;
     col: number;
 };
-/** The squares a turned table shows: the grid's area, turned. */
+/** The squares a turned table shows: the grid's area, turned.
+ *
+ * @param area - The occupied table bounds.
+ * @param turn - The number of quarter turns of the view.
+ * @returns The squares a turned table shows: the grid's area, turned.
+ * @example
+ * ```ts
+ * import { turnArea } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * console.log(turnArea(area,1));
+ * ```
+ */
 export declare function turnArea(area: Area, turn: Turn): Area;
 /**
  * A view the player zoomed or panned, turned a quarter clockwise with the
@@ -44,18 +89,51 @@ export declare function turnArea(area: Area, turn: Turn): Area;
  * On the screen a square's corner is `x + col * tile`; the turn takes a point
  * (row v, col u) of the table to (row u, col 1 - v), which is a quarter turn
  * about the middle of square (0, 0) — the same turn as `turnPlace`.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @returns A view the player zoomed or panned, turned a quarter clockwise with the table about the middle of its box: the same zoom, and the spot of the table that was in the middle stays there. (A fitted view simply fits again.)
+ * @example
+ * ```ts
+ * import { turnView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * console.log(turnView(view,640,480));
+ * ```
  */
 export declare function turnView(view: View, width: number, height: number): View;
 /**
  * Which way typed letters run ON THE SCREEN. Typing lays a word across or
  * down the grid, so that it reads as a word; with the table turned, that is
  * another way on the screen, and the cursor's arrow points it.
+ *
+ * @param across - Whether to lay or type horizontally rather than vertically.
+ * @param turn - The number of quarter turns of the view.
+ * @returns Which way typed letters run ON THE SCREEN. Typing lays a word across or down the grid, so that it reads as a word; with the table turned, that is another way on the screen, and the cursor's arrow points it.
+ * @example
+ * ```ts
+ * import { typingWay } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(typingWay(true,1));
+ * ```
  */
 export declare function typingWay(across: boolean, turn: Turn): {
     arrow: string;
     name: string;
 };
-/** The step in the grid an arrow key means: the square that way on the screen, with the table turned. Null for any other key. */
+/** The step in the grid an arrow key means: the square that way on the screen, with the table turned. Null for any other key.
+ *
+ * @param key - The keyboard key identifier.
+ * @param turn - The number of quarter turns of the view.
+ * @returns The step in the grid an arrow key means: the square that way on the screen, with the table turned. null for any other key.
+ * @example
+ * ```ts
+ * import { arrowStep } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(arrowStep("ArrowRight",1));
+ * ```
+ */
 export declare function arrowStep(key: string, turn: Turn): {
     row: number;
     col: number;

package/dist/turn.js

@@ -15,7 +15,17 @@
  * Pure, like the rest of the view (`tableView.ts`), which works on the turned
  * squares unchanged: fitting, zooming and panning are all in screen terms.
  */
-/** The next turn a press gives: a quarter clockwise, and four presses back to the start. */
+/** The next turn a press gives: a quarter clockwise, and four presses back to the start.
+ *
+ * @param turn - The number of quarter turns of the view.
+ * @returns The next turn a press gives: a quarter clockwise, and four presses back to the start.
+ * @example
+ * ```ts
+ * import { nextTurn } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(nextTurn(3));
+ * ```
+ */
 export function nextTurn(turn) {
     return ((turn + 1) % 4);
 }
@@ -26,6 +36,17 @@ const negate = (n) => 0 - n;
  * quarter clockwise sends a word running right to one running down, and one
  * running down to one running left. It is linear, so it turns a step (a
  * direction) as well as a square.
+ *
+ * @param row - The integer row coordinate, which may be negative.
+ * @param col - The integer column coordinate, which may be negative.
+ * @param turn - The number of quarter turns of the view.
+ * @returns Where square (row, col) of the grid is drawn with the table turned: a quarter clockwise sends a word running right to one running down, and one running down to one running left. It is linear, so it turns a step (a direction) as well as a square.
+ * @example
+ * ```ts
+ * import { turnPlace } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(turnPlace(1,2,1));
+ * ```
  */
 export function turnPlace(row, col, turn) {
     switch (turn) {
@@ -39,15 +60,44 @@ export function turnPlace(row, col, turn) {
             return { row: negate(col), col: row };
     }
 }
-/** The grid's square drawn at (row, col) of the turned table: `turnPlace` undone. */
+/** The grid's square drawn at (row, col) of the turned table: `turnPlace` undone.
+ *
+ * @param row - The integer row coordinate, which may be negative.
+ * @param col - The integer column coordinate, which may be negative.
+ * @param turn - The number of quarter turns of the view.
+ * @returns The grid's square drawn at (row, col) of the turned table: `turnPlace` undone.
+ * @example
+ * ```ts
+ * import { unturnPlace } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(unturnPlace(1,2,1));
+ * ```
+ */
 export function unturnPlace(row, col, turn) {
     return turnPlace(row, col, ((4 - turn) % 4));
 }
-/** The squares a turned table shows: the grid's area, turned. */
+/** The squares a turned table shows: the grid's area, turned.
+ *
+ * @param area - The occupied table bounds.
+ * @param turn - The number of quarter turns of the view.
+ * @returns The squares a turned table shows: the grid's area, turned.
+ * @example
+ * ```ts
+ * import { turnArea } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * console.log(turnArea(area,1));
+ * ```
+ */
 export function turnArea(area, turn) {
     const a = turnPlace(area.top, area.left, turn);
     const b = turnPlace(area.top + area.rows - 1, area.left + area.cols - 1, turn);
-    return { top: Math.min(a.row, b.row), left: Math.min(a.col, b.col), rows: Math.abs(a.row - b.row) + 1, cols: Math.abs(a.col - b.col) + 1 };
+    return {
+        top: Math.min(a.row, b.row),
+        left: Math.min(a.col, b.col),
+        rows: Math.abs(a.row - b.row) + 1,
+        cols: Math.abs(a.col - b.col) + 1,
+    };
 }
 /**
  * A view the player zoomed or panned, turned a quarter clockwise with the
@@ -57,6 +107,18 @@ export function turnArea(area, turn) {
  * On the screen a square's corner is `x + col * tile`; the turn takes a point
  * (row v, col u) of the table to (row u, col 1 - v), which is a quarter turn
  * about the middle of square (0, 0) — the same turn as `turnPlace`.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @returns A view the player zoomed or panned, turned a quarter clockwise with the table about the middle of its box: the same zoom, and the spot of the table that was in the middle stays there. (A fitted view simply fits again.)
+ * @example
+ * ```ts
+ * import { turnView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * console.log(turnView(view,640,480));
+ * ```
  */
 export function turnView(view, width, height) {
     const px = width / 2;
@@ -76,6 +138,16 @@ const WAYS = [
  * Which way typed letters run ON THE SCREEN. Typing lays a word across or
  * down the grid, so that it reads as a word; with the table turned, that is
  * another way on the screen, and the cursor's arrow points it.
+ *
+ * @param across - Whether to lay or type horizontally rather than vertically.
+ * @param turn - The number of quarter turns of the view.
+ * @returns Which way typed letters run ON THE SCREEN. Typing lays a word across or down the grid, so that it reads as a word; with the table turned, that is another way on the screen, and the cursor's arrow points it.
+ * @example
+ * ```ts
+ * import { typingWay } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(typingWay(true,1));
+ * ```
  */
 export function typingWay(across, turn) {
     const step = turnPlace(across ? 0 : 1, across ? 1 : 0, turn);
@@ -89,7 +161,18 @@ const ARROW_KEYS = {
     ArrowLeft: { row: 0, col: -1 },
     ArrowUp: { row: -1, col: 0 },
 };
-/** The step in the grid an arrow key means: the square that way on the screen, with the table turned. Null for any other key. */
+/** The step in the grid an arrow key means: the square that way on the screen, with the table turned. Null for any other key.
+ *
+ * @param key - The keyboard key identifier.
+ * @param turn - The number of quarter turns of the view.
+ * @returns The step in the grid an arrow key means: the square that way on the screen, with the table turned. null for any other key.
+ * @example
+ * ```ts
+ * import { arrowStep } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(arrowStep("ArrowRight",1));
+ * ```
+ */
 export function arrowStep(key, turn) {
     const step = ARROW_KEYS[key];
     return step === undefined ? null : unturnPlace(step.row, step.col, turn);

package/dist/ui/board.d.ts

@@ -1,7 +1,25 @@
 import { type GridVerdict, type Tiles } from "../grid.ts";
-/** How a tile on the table stands: part of a sound crossword, in a run that is not a word, or apart from the rest. */
+/** How a tile on the table stands: part of a sound crossword, in a run that is not a word, or apart from the rest.
+ *
+ * @example
+ * ```ts
+ * import type { TileMark } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * const value: TileMark = "sound";
+ * console.log(value);
+ * ```
+ */
 export type TileMark = "sound" | "misspelt" | "apart";
-/** One square of the board drawn. */
+/** One square of the board drawn.
+ *
+ * @example
+ * ```ts
+ * import type { BoardSquare } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * const value: BoardSquare = {square:"0,0",row:0,col:0,tile:"c",glyph:"c",wild:false,mark:null};
+ * console.log(value);
+ * ```
+ */
 export type BoardSquare = {
     /** Its key, `squareAt(row, col)`. */
     square: string;
@@ -16,20 +34,57 @@ export type BoardSquare = {
     /** How the tile stands; null for an empty square, or with no verdict. */
     mark: TileMark | null;
 };
-/** The part of the table to draw: how many rows and columns, and every square, row by row. */
+/** The part of the table to draw: how many rows and columns, and every square, row by row.
+ *
+ * @example
+ * ```ts
+ * import type { BoardModel } from "@johnmorrisdotca/kumimoji/ui";
+ * import { boardModel } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const value: BoardModel = boardModel(tiles,null);
+ * console.log(value);
+ * ```
+ */
 export type BoardModel = {
     rows: number;
     cols: number;
     squares: BoardSquare[];
 };
-/** How many empty squares are kept round the tiles on every side, so there is always room to build out. */
+/** How many empty squares are kept round the tiles on every side, so there is always room to build out.
+ *
+ * @example
+ * ```ts
+ * import { BOARD_MARGIN } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(BOARD_MARGIN);
+ * ```
+ */
 export declare const BOARD_MARGIN = 2;
-/** The fewest squares a side, so an empty or small table is still a table. */
+/** The fewest squares a side, so an empty or small table is still a table.
+ *
+ * @example
+ * ```ts
+ * import { BOARD_LEAST } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(BOARD_LEAST);
+ * ```
+ */
 export declare const BOARD_LEAST = 7;
 /**
  * THE PART OF THE TABLE TO DRAW, for a grid and its verdict: the tiles and a
  * margin round them, at least `BOARD_LEAST` a side, each square with its tile,
  * what is printed on it, and how it stands. Row by row, left to right. The
  * grid itself has no edges; this is only the window a board shows it through.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @param glyphOf - The function that renders an internal tile code as a visible glyph.
+ * @returns THE PART OF THE TABLE TO DRAW, for a grid and its verdict: the tiles and a margin round them, at least `BOARD_LEAST` a side, each square with its tile, what is printed on it, and how it stands. Row by row, left to right. The grid itself has no edges; this is only the window a board shows it through.
+ * @example
+ * ```ts
+ * import { boardModel } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(boardModel(tiles,null).squares.length);
+ * ```
  */
 export declare function boardModel(tiles: Tiles, verdict: GridVerdict | null, glyphOf?: (tile: string) => string): BoardModel;

package/dist/ui/board.js

@@ -1,14 +1,40 @@
 import { boundsOf, squareAt } from "../grid.js";
 import { tileFace } from "../tileFace.js";
-/** How many empty squares are kept round the tiles on every side, so there is always room to build out. */
+/** How many empty squares are kept round the tiles on every side, so there is always room to build out.
+ *
+ * @example
+ * ```ts
+ * import { BOARD_MARGIN } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(BOARD_MARGIN);
+ * ```
+ */
 export const BOARD_MARGIN = 2;
-/** The fewest squares a side, so an empty or small table is still a table. */
+/** The fewest squares a side, so an empty or small table is still a table.
+ *
+ * @example
+ * ```ts
+ * import { BOARD_LEAST } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(BOARD_LEAST);
+ * ```
+ */
 export const BOARD_LEAST = 7;
 /**
  * THE PART OF THE TABLE TO DRAW, for a grid and its verdict: the tiles and a
  * margin round them, at least `BOARD_LEAST` a side, each square with its tile,
  * what is printed on it, and how it stands. Row by row, left to right. The
  * grid itself has no edges; this is only the window a board shows it through.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @param glyphOf - The function that renders an internal tile code as a visible glyph.
+ * @returns THE PART OF THE TABLE TO DRAW, for a grid and its verdict: the tiles and a margin round them, at least `BOARD_LEAST` a side, each square with its tile, what is printed on it, and how it stands. Row by row, left to right. The grid itself has no edges; this is only the window a board shows it through.
+ * @example
+ * ```ts
+ * import { boardModel } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(boardModel(tiles,null).squares.length);
+ * ```
  */
 export function boardModel(tiles, verdict, glyphOf = (tile) => tileFace(tile).glyph) {
     const bounds = boundsOf(tiles) ?? { top: 0, left: 0, bottom: 0, right: 0 };
@@ -29,8 +55,22 @@ export function boardModel(tiles, verdict, glyphOf = (tile) => tileFace(tile).gl
         for (let col = left; col < left + cols; col += 1) {
             const square = squareAt(row, col);
             const tile = tiles.get(square) ?? null;
-            const mark = tile === null || verdict === null ? null : verdict.misspelt.has(square) ? "misspelt" : verdict.apart.has(square) ? "apart" : "sound";
-            squares.push({ square, row, col, tile, glyph: tile === null ? "" : glyphOf(tile), wild: tile !== null && tileFace(tile).wild, mark });
+            const mark = tile === null || verdict === null
+                ? null
+                : verdict.misspelt.has(square)
+                    ? "misspelt"
+                    : verdict.apart.has(square)
+                        ? "apart"
+                        : "sound";
+            squares.push({
+                square,
+                row,
+                col,
+                tile,
+                glyph: tile === null ? "" : glyphOf(tile),
+                wild: tile !== null && tileFace(tile).wild,
+                mark,
+            });
         }
     }
     return { rows, cols, squares };