@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

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,11 +60,35 @@ 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);
@@ -57,6 +102,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 +133,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 +156,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 };

package/dist/ui/mount.d.ts

@@ -2,7 +2,16 @@ import { type KumimojiSaved } from "../export.ts";
 import type { KumimojiDeal, KumimojiLanguage, KumimojiLength, KumimojiLevel } from "../kumimoji.types.ts";
 import { type TilePlay } from "../play.ts";
 import { type KumimojiLocale, type KumimojiStrings } from "../strings.ts";
-/** What `mountKumimoji` may be given. Everything is optional: with nothing, it is a short English game from a hand of seven, with some wild tiles. */
+/**
+ * Optional initial game, presentation, readiness and callback choices.
+ * With nothing, it is a short English game from a hand of seven, with some wild tiles.
+ * @example
+ * ```ts
+ * import type { KumimojiTableOptions } from "@johnmorrisdotca/kumimoji/ui";
+ * const options: KumimojiTableOptions = { hand: 7, keep: false, controls: true };
+ * console.log(options.hand);
+ * ```
+ */
 export type KumimojiTableOptions = {
     /** The language of the tiles: `"english"` or `"japanese"` kana. English by default. */
     language?: KumimojiLanguage;
@@ -32,11 +41,29 @@ export type KumimojiTableOptions = {
     theme?: Readonly<Record<string, string>>;
     /** Whether the table offers saving and loading. True by default. */
     keep?: boolean;
+    /** Show native play-action buttons; a host hiding them supplies its own actions. */
+    controls?: boolean;
+    /** A validated saved game to restore initially instead of dealing a new one. */
+    saved?: KumimojiSaved;
+    /** Called after a word-list load or initial restoration fails. */
+    onError?: (error: Error) => void;
 };
 /** The options that make a game, which a new game may change. */
 type GameOptions = Pick<KumimojiTableOptions, "language" | "hand" | "level" | "gameLength" | "diagonals" | "seed">;
-/** What `mountKumimoji` hands back: the game being played, and the ways to change it from outside. */
+/**
+ * Readiness, structured play and presentation/game controls for a mounted table.
+ * @example
+ * ```ts
+ * import type { KumimojiTableHandle } from "@johnmorrisdotca/kumimoji/ui";
+ * const setJapanese = (table: KumimojiTableHandle): void => table.set({ locale: "ja" });
+ * console.log(typeof setJapanese);
+ * ```
+ */
 export type KumimojiTableHandle = {
+    /** Settles once the initial deal or restored game is ready. */
+    readonly ready: Promise<void>;
+    /** Change presentation and controls without redealing. */
+    set: (options: Pick<KumimojiTableOptions, "locale" | "strings" | "theme" | "keep" | "controls">) => void;
     /** The game as it stands, or null while it is being dealt. */
     play: () => TilePlay | null;
     /** The game as it would be saved (`kumimojiToJSON`), or null while it is being dealt. */
@@ -61,6 +88,18 @@ export type KumimojiTableHandle = {
  * game loads back.
  *
  * The word list is fetched the first time a game in its language is dealt.
+ * @param target - The host element for this table.
+ * @param options - Initial deal or saved state, presentation and callbacks.
+ * @returns The native handle, including ready and presentation updates without redealing.
+ * @example
+ * ```ts
+ * import { mountKumimoji } from "@johnmorrisdotca/kumimoji/ui";
+ * if (typeof document !== "undefined") {
+ *   const table = mountKumimoji(document.createElement("div"), { keep: false });
+ *   void table.ready.then(() => table.destroy());
+ * }
+ * console.log(typeof mountKumimoji);
+ * ```
  */
 export declare function mountKumimoji(target: HTMLElement, options?: KumimojiTableOptions): KumimojiTableHandle;
 export {};

package/dist/ui/mount.js

@@ -46,6 +46,18 @@ function save(name, type, text) {
  * game loads back.
  *
  * The word list is fetched the first time a game in its language is dealt.
+ * @param target - The host element for this table.
+ * @param options - Initial deal or saved state, presentation and callbacks.
+ * @returns The native handle, including ready and presentation updates without redealing.
+ * @example
+ * ```ts
+ * import { mountKumimoji } from "@johnmorrisdotca/kumimoji/ui";
+ * if (typeof document !== "undefined") {
+ *   const table = mountKumimoji(document.createElement("div"), { keep: false });
+ *   void table.ready.then(() => table.destroy());
+ * }
+ * console.log(typeof mountKumimoji);
+ * ```
  */
 export function mountKumimoji(target, options = {}) {
     let settings = { language: options.language, hand: options.hand, level: options.level, gameLength: options.gameLength, diagonals: options.diagonals, seed: options.seed };
@@ -87,6 +99,7 @@ export function mountKumimoji(target, options = {}) {
     const picker = node("div", "km-picker");
     picker.dataset.testid = "km-picker";
     const controls = node("div", "km-controls");
+    controls.hidden = options.controls === false;
     controls.dataset.testid = "km-controls";
     const keep = node("details", "km-keep");
     keep.dataset.testid = "km-keep";
@@ -422,7 +435,29 @@ export function mountKumimoji(target, options = {}) {
         renderControls(verdict);
         keyboardBack(where);
     }
+    let initialReady = Promise.resolve();
     const handle = {
+        get ready() { return initialReady; },
+        set: (changes) => {
+            for (const name of Object.keys(options.theme ?? {}))
+                if (changes.theme !== undefined && !(name in changes.theme))
+                    root.style.removeProperty(name);
+            if (changes.theme !== undefined)
+                for (const [name, value] of Object.entries(changes.theme))
+                    root.style.setProperty(name, value);
+            options = { ...options, ...changes };
+            if (changes.locale !== undefined)
+                locale = changes.locale;
+            if (changes.strings !== undefined)
+                own = changes.strings;
+            say = kumimojiStrings(locale, own);
+            if (options.keep === false)
+                keep.remove();
+            else if (keep.parentNode !== root)
+                root.append(keep);
+            controls.hidden = options.controls === false;
+            render();
+        },
         play: () => play,
         saved: savedNow,
         setGame: async (saved) => {
@@ -482,6 +517,8 @@ export function mountKumimoji(target, options = {}) {
             root.remove();
         },
     };
-    void handle.newGame(settings);
+    initialReady = options.saved === undefined ? handle.newGame(settings) : handle.setGame(options.saved);
+    void initialReady.catch((error) => { if (destroyed)
+        return; const problem = error instanceof Error ? error : new Error(String(error)); status.textContent = say.loadError; options.onError?.(problem); });
     return handle;
 }

package/dist/ui/style.d.ts

@@ -3,5 +3,10 @@
  * variable so a page can wear it in its own colours (set them on the element
  * or any ancestor, or pass them as `theme`). Light and dark follow the
  * reader's system. Everything to be tapped is at least 44px.
+  * @example
+ * ```ts
+ * import { KUMIMOJI_STYLE } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(KUMIMOJI_STYLE.includes(".km-root")); // true
+ * ```
  */
-export declare const KUMIMOJI_STYLE = "\n.km-root {\n  --km-square: 44px; --km-felt: #2f5d4a; --km-grid-line: rgba(255,255,255,.12); --km-tile: #f3e6c8; --km-tile-ink: #2a2118;\n  --km-wild: #f6d27a; --km-wrong: #d9534f; --km-held: #ffcf3f; --km-ink: #1f2320; --km-panel: #f7f3ea;\n  --km-line: rgba(20,20,20,.35); --km-accent: #2f5d4a; --km-accent-ink: #fff;\n  --km-radius: 12px; --km-font: system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  display: grid; gap: 10px; min-width: 0; color: var(--km-ink); font-family: var(--km-font); font-size: 15px;\n}\n@media (prefers-color-scheme: dark) {\n  .km-root { --km-felt: #1e3a2f; --km-ink: #ece8dc; --km-panel: #1d201e; --km-line: rgba(255,255,255,.25); --km-accent: #6fb08f; --km-accent-ink: #10150f; }\n}\n.km-root > * { min-width: 0; }\n.km-status { margin: 0; min-height: 1.4em; font-variant-numeric: tabular-nums; }\n.km-board { background: var(--km-felt); border-radius: var(--km-radius); padding: 10px; overflow: auto; max-height: 70vh; }\n.km-grid { display: grid; gap: 2px; width: max-content; margin: 0 auto; }\n.km-square { width: var(--km-square); height: var(--km-square); border: 0; border-radius: 5px; background: var(--km-grid-line); padding: 0; cursor: pointer; touch-action: manipulation; }\n.km-tile { display: grid; place-items: center; width: var(--km-square); height: var(--km-square); border-radius: 6px; border: 0; padding: 0;\n  background: var(--km-tile); color: var(--km-tile-ink); font: 700 calc(var(--km-square) * .55)/1 var(--km-font); text-transform: uppercase;\n  box-shadow: 0 2px 0 rgba(0,0,0,.35); cursor: pointer; touch-action: manipulation; }\n.km-japanese .km-tile { font-size: calc(var(--km-square) * .52); text-transform: none; }\n.km-wild { background: var(--km-wild); }\n.km-misspelt { box-shadow: 0 0 0 3px var(--km-wrong) inset, 0 2px 0 rgba(0,0,0,.35); }\n.km-apart { opacity: .6; }\n.km-held { outline: 3px solid var(--km-held); outline-offset: 1px; }\n.km-square:focus-visible, .km-in-hand:focus-visible, .km-button:focus-visible, .km-keep-title:focus-visible { outline: 3px solid var(--km-held); outline-offset: 2px; }\n.km-notes { margin: 0; min-height: 1.4em; font-size: 14px; opacity: .8; overflow-wrap: anywhere; }\n.km-hand { display: flex; flex-wrap: wrap; gap: 6px; min-height: calc(var(--km-square) + 16px); align-items: center; padding: 8px; border-radius: 10px; background: var(--km-panel); }\n.km-empty { opacity: .6; font-size: 14px; }\n.km-picker { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; }\n.km-picker:empty { display: none; }\n.km-picker-title { width: 100%; font-size: 14px; }\n.km-picker .km-button { padding: 0 8px; text-transform: uppercase; }\n.km-japanese .km-picker .km-button { text-transform: none; }\n.km-controls { display: flex; flex-wrap: wrap; gap: 8px; }\n.km-button { font: inherit; min-height: 44px; min-width: 44px; padding: 0 14px; border-radius: 8px; border: 1px solid var(--km-line); background: var(--km-panel); color: var(--km-ink); cursor: pointer; touch-action: manipulation; }\n.km-button:disabled { opacity: .45; cursor: default; }\n.km-primary { background: var(--km-accent); color: var(--km-accent-ink); border-color: transparent; }\n.km-keep { border-radius: 10px; background: var(--km-panel); padding: 0 10px; }\n.km-keep[open] { padding-bottom: 10px; }\n.km-keep-title { min-height: 44px; display: flex; align-items: center; font-weight: 600; cursor: pointer; }\n.km-note { margin: 8px 0 0; min-height: 1.4em; font-size: 13px; }\n";
+export declare const KUMIMOJI_STYLE = "\n.km-root {\n  --km-square: 44px; --km-felt: #2f5d4a; --km-grid-line: rgba(255,255,255,.12); --km-tile: #f3e6c8; --km-tile-ink: #2a2118;\n  --km-wild: #f6d27a; --km-wrong: #d9534f; --km-held: #ffcf3f; --km-ink: #1f2320; --km-panel: #f7f3ea;\n  --km-line: rgba(20,20,20,.35); --km-accent: #2f5d4a; --km-accent-ink: #fff;\n  --km-radius: 12px; --km-font: system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  display: grid; gap: 10px; min-width: 0; color: var(--km-ink); font-family: var(--km-font); font-size: 15px;\n}\n@media (prefers-color-scheme: dark) {\n  .km-root { --km-felt: #1e3a2f; --km-ink: #ece8dc; --km-panel: #1d201e; --km-line: rgba(255,255,255,.25); --km-accent: #6fb08f; --km-accent-ink: #10150f; }\n}\n.km-root > * { min-width: 0; }\n.km-status { margin: 0; min-height: 1.4em; font-variant-numeric: tabular-nums; }\n.km-board { background: var(--km-felt); border-radius: var(--km-radius); padding: 10px; overflow: auto; max-height: 70vh; }\n.km-grid { display: grid; gap: 2px; width: max-content; margin: 0 auto; }\n.km-square { width: var(--km-square); height: var(--km-square); border: 0; border-radius: 5px; background: var(--km-grid-line); padding: 0; cursor: pointer; touch-action: manipulation; }\n.km-tile { display: grid; place-items: center; width: var(--km-square); height: var(--km-square); border-radius: 6px; border: 0; padding: 0;\n  background: var(--km-tile); color: var(--km-tile-ink); font: 700 calc(var(--km-square) * .55)/1 var(--km-font); text-transform: uppercase;\n  box-shadow: 0 2px 0 rgba(0,0,0,.35); cursor: pointer; touch-action: manipulation; }\n.km-japanese .km-tile { font-size: calc(var(--km-square) * .52); text-transform: none; }\n.km-wild { background: var(--km-wild); }\n.km-misspelt { box-shadow: 0 0 0 3px var(--km-wrong) inset, 0 2px 0 rgba(0,0,0,.35); }\n.km-apart { opacity: .6; }\n.km-held { outline: 3px solid var(--km-held); outline-offset: 1px; }\n.km-square:focus-visible, .km-in-hand:focus-visible, .km-button:focus-visible, .km-keep-title:focus-visible { outline: 3px solid var(--km-held); outline-offset: 2px; }\n.km-notes { margin: 0; min-height: 1.4em; font-size: 14px; opacity: .8; overflow-wrap: anywhere; }\n.km-hand { display: flex; flex-wrap: wrap; gap: 6px; min-height: calc(var(--km-square) + 16px); align-items: center; padding: 8px; border-radius: 10px; background: var(--km-panel); }\n.km-empty { opacity: .6; font-size: 14px; }\n.km-picker { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; }\n.km-picker:empty { display: none; }\n.km-picker-title { width: 100%; font-size: 14px; }\n.km-picker .km-button { padding: 0 8px; text-transform: uppercase; }\n.km-japanese .km-picker .km-button { text-transform: none; }\n.km-controls[hidden] { display: none; }\n.km-controls { display: flex; flex-wrap: wrap; gap: 8px; }\n.km-button { font: inherit; min-height: 44px; min-width: 44px; padding: 0 14px; border-radius: 8px; border: 1px solid var(--km-line); background: var(--km-panel); color: var(--km-ink); cursor: pointer; touch-action: manipulation; }\n.km-button:disabled { opacity: .45; cursor: default; }\n.km-primary { background: var(--km-accent); color: var(--km-accent-ink); border-color: transparent; }\n.km-keep { border-radius: 10px; background: var(--km-panel); padding: 0 10px; }\n.km-keep[open] { padding-bottom: 10px; }\n.km-keep-title { min-height: 44px; display: flex; align-items: center; font-weight: 600; cursor: pointer; }\n.km-note { margin: 8px 0 0; min-height: 1.4em; font-size: 13px; }\n";

package/dist/ui/style.js

@@ -3,6 +3,11 @@
  * variable so a page can wear it in its own colours (set them on the element
  * or any ancestor, or pass them as `theme`). Light and dark follow the
  * reader's system. Everything to be tapped is at least 44px.
+  * @example
+ * ```ts
+ * import { KUMIMOJI_STYLE } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(KUMIMOJI_STYLE.includes(".km-root")); // true
+ * ```
  */
 export const KUMIMOJI_STYLE = `
 .km-root {
@@ -37,6 +42,7 @@ export const KUMIMOJI_STYLE = `
 .km-picker-title { width: 100%; font-size: 14px; }
 .km-picker .km-button { padding: 0 8px; text-transform: uppercase; }
 .km-japanese .km-picker .km-button { text-transform: none; }
+.km-controls[hidden] { display: none; }
 .km-controls { display: flex; flex-wrap: wrap; gap: 8px; }
 .km-button { font: inherit; min-height: 44px; min-width: 44px; padding: 0 14px; border-radius: 8px; border: 1px solid var(--km-line); background: var(--km-panel); color: var(--km-ink); cursor: pointer; touch-action: manipulation; }
 .km-button:disabled { opacity: .45; cursor: default; }

package/dist/version.d.ts

@@ -1,2 +1,9 @@
-/** The version of this package, as `package.json` has it. A test holds the two together. */
-export declare const KUMIMOJI_VERSION = "1.2.2";
+/** The version of this package, as `package.json` has it. A test holds the two together.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_VERSION } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_VERSION);
+ * ```
+ */
+export declare const KUMIMOJI_VERSION = "1.3.0";

package/dist/version.js

@@ -1,2 +1,9 @@
-/** The version of this package, as `package.json` has it. A test holds the two together. */
-export const KUMIMOJI_VERSION = "1.2.2";
+/** The version of this package, as `package.json` has it. A test holds the two together.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_VERSION } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_VERSION);
+ * ```
+ */
+export const KUMIMOJI_VERSION = "1.3.0";

package/dist/wilds.d.ts

@@ -21,7 +21,28 @@ import type { TileWords } from "./tileWords.ts";
  * table names the run as the player spelled it. It gives up, answering null,
  * past `WILD_SEARCH_MOST` steps: a grid it could not settle is not called
  * sound.
+ *
+ * @example
+ * ```ts
+ * import { WILD_SEARCH_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(WILD_SEARCH_MOST);
+ * ```
  */
 export declare const WILD_SEARCH_MOST = 20000;
-/** The grid with every blank wild read as a letter that makes all its runs words, or null for none; the grid itself when it holds no blank. */
+/** The grid with every blank wild read as a letter that makes all its runs words, or null for none; the grid itself when it holds no blank.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param words - The loaded native language word list and tile mappings.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns The grid with every blank wild read as a letter that makes all its runs words, or null for none; the grid itself when it holds no blank.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { readWilds } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(readWilds(tiles,words));
+ * ```
+ */
 export declare function readWilds(tiles: Tiles, words: TileWords, rules?: GridRules): Tiles | null;

package/dist/wilds.js

@@ -20,9 +20,30 @@ import { runsOf } from "./grid.js";
  * table names the run as the player spelled it. It gives up, answering null,
  * past `WILD_SEARCH_MOST` steps: a grid it could not settle is not called
  * sound.
+ *
+ * @example
+ * ```ts
+ * import { WILD_SEARCH_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(WILD_SEARCH_MOST);
+ * ```
  */
 export const WILD_SEARCH_MOST = 20000;
-/** The grid with every blank wild read as a letter that makes all its runs words, or null for none; the grid itself when it holds no blank. */
+/** The grid with every blank wild read as a letter that makes all its runs words, or null for none; the grid itself when it holds no blank.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param words - The loaded native language word list and tile mappings.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns The grid with every blank wild read as a letter that makes all its runs words, or null for none; the grid itself when it holds no blank.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { readWilds } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(readWilds(tiles,words));
+ * ```
+ */
 export function readWilds(tiles, words, rules = {}) {
     const blanks = [...tiles].filter(([, tile]) => tile === "*").map(([square]) => square);
     if (blanks.length === 0)