@johnmorrisdotca/kumimoji 1.2.2 → 1.3.1

package/dist/tableView.d.ts

@@ -10,6 +10,12 @@ import { type Tiles } from "./grid.ts";
  * there is always room to build outward, and it zooms to fit the crossword:
  * big tiles for a first word, smaller as the grid spreads, never smaller than
  * a thumb can press (`TABLE.tileLeast`). Past that the table pans instead.
+ *
+ * @example
+ * ```ts
+ * import { TABLE } from "@johnmorrisdotca/kumimoji";
+ * console.log(TABLE);
+ * ```
  */
 export declare const TABLE: {
     /** Empty squares shown beyond the tiles on every side. */
@@ -40,20 +46,52 @@ export declare const TABLE: {
     /** How long a dragged tile must stay near an edge before the table pans: crossing an edge on the way in is not asking to pan. */
     readonly edgeDwellMs: 350;
 };
-/** The squares shown: from `top`/`left`, `rows` by `cols`. */
+/** The squares shown: from `top`/`left`, `rows` by `cols`.
+ *
+ * @example
+ * ```ts
+ * import type { Area } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * const value: Area = area;
+ * console.log(value);
+ * ```
+ */
 export type Area = {
     top: number;
     left: number;
     rows: number;
     cols: number;
 };
-/** A view: a tile's side in pixels, and where the corner of square (0, 0) is drawn. */
+/** A view: a tile's side in pixels, and where the corner of square (0, 0) is drawn.
+ *
+ * @example
+ * ```ts
+ * import type { View } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * const value: View = view;
+ * console.log(value);
+ * ```
+ */
 export type View = {
     tile: number;
     x: number;
     y: number;
 };
-/** The squares to show: the tiles' extent and the margin, or the margin round square (0, 0) on an empty table. Extra squares (the one a typed letter goes to) are kept in. */
+/** The squares to show: the tiles' extent and the margin, or the margin round square (0, 0) on an empty table. Extra squares (the one a typed letter goes to) are kept in.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param also - Additional square names to include in the table bounds.
+ * @returns The squares to show: the tiles' extent and the margin, or the margin round square (0, 0) on an empty table. Extra squares (the one a typed letter goes to) are kept in.
+ * @example
+ * ```ts
+ * import { tableArea } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(tableArea(tiles));
+ * ```
+ */
 export declare function tableArea(tiles: Tiles, also?: readonly string[]): Area;
 /**
  * The largest a fitted tile is drawn in a table this big. `tileMost` in any
@@ -61,32 +99,137 @@ export declare function tableArea(tiles: Tiles, also?: readonly string[]): Area;
  * the Regular desk table; past that, in proportion, so a table the player asked
  * to be Large or Full (`BoardScale`) draws bigger squares rather than only more
  * of them — never past what a hand may zoom to.
+ *
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @returns The largest a fitted tile is drawn in a table this big. `tileMost` in any table up to `growsFrom` across its shorter side, which is every phone's and the Regular desk table; past that, in proportion, so a table the player asked to be Large or Full (`BoardScale`) draws bigger squares rather than only more of them — never past what a hand may zoom to.
+ * @example
+ * ```ts
+ * import { fittedMost } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(fittedMost(640,480));
+ * ```
  */
 export declare function fittedMost(width: number, height: number): number;
 /**
  * The view that shows the whole area, centred, its tiles as big as fit between
  * the least and the most. A picture nobody presses (a finished grid, the
  * set-up preview) passes a smaller least, so a whole grid fits its box.
+ *
+ * @param area - The occupied table bounds.
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @param least - The minimum permitted tile size.
+ * @returns The view that shows the whole area, centred, its tiles as big as fit between the least and the most. A picture nobody presses (a finished grid, the set-up preview) passes a smaller least, so a whole grid fits its box.
+ * @example
+ * ```ts
+ * import { fitView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * console.log(fitView(area,640,480));
+ * ```
  */
 export declare function fitView(area: Area, width: number, height: number, least?: number): View;
-/** Whether the area, at this view's size, is bigger than the screen: then the table pans. */
+/** Whether the area, at this view's size, is bigger than the screen: then the table pans.
+ *
+ * @param area - The occupied table bounds.
+ * @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 Whether the area, at this view's size, is bigger than the screen: then the table pans.
+ * @example
+ * ```ts
+ * import { overflows } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * const view = {tile:40,x:100,y:100};
+ * console.log(overflows(area,view,640,480));
+ * ```
+ */
 export declare function overflows(area: Area, view: View, width: number, height: number): boolean;
-/** Zoomed by `factor` about the point (px, py) on the screen, which stays over the same spot of the table. */
+/** Zoomed by `factor` about the point (px, py) on the screen, which stays over the same spot of the table.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param factor - The positive scale factor for zooming.
+ * @param px - The horizontal pointer position in pixels.
+ * @param py - The vertical pointer position in pixels.
+ * @returns Zoomed by `factor` about the point (px, py) on the screen, which stays over the same spot of the table.
+ * @example
+ * ```ts
+ * import { zoomView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * console.log(zoomView(view,1.2,320,240));
+ * ```
+ */
 export declare function zoomView(view: View, factor: number, px: number, py: number): View;
-/** The view moved by `dx` and `dy` screen pixels. */
+/** The view moved by `dx` and `dy` screen pixels.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param dx - The horizontal pixel movement.
+ * @param dy - The vertical pixel movement.
+ * @returns The view moved by `dx` and `dy` screen pixels.
+ * @example
+ * ```ts
+ * import { panView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * console.log(panView(view,20,10));
+ * ```
+ */
 export declare function panView(view: View, dx: number, dy: number): View;
 /**
  * Kept within reach: some of the area always on the screen, so a pan can
  * never lose the crossword. A quarter of the screen or two tiles, whichever
  * is less, stays in view on every side.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param area - The occupied table bounds.
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @returns Kept within reach: some of the area always on the screen, so a pan can never lose the crossword. A quarter of the screen or two tiles, whichever is less, stays in view on every side.
+ * @example
+ * ```ts
+ * import { keepInReach } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * const view = {tile:40,x:100,y:100};
+ * console.log(keepInReach(view,area,640,480));
+ * ```
  */
 export declare function keepInReach(view: View, area: Area, width: number, height: number): View;
-/** The square under a point on the screen. */
+/** The square under a point on the screen.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param px - The horizontal pointer position in pixels.
+ * @param py - The vertical pointer position in pixels.
+ * @returns The square under a point on the screen.
+ * @example
+ * ```ts
+ * import { squareUnder } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * console.log(squareUnder(view,100,100));
+ * ```
+ */
 export declare function squareUnder(view: View, px: number, py: number): {
     row: number;
     col: number;
 };
-/** Which way, and how far, the table pans this frame for a tile dragged to (px, py): toward the edge it is near. */
+/** Which way, and how far, the table pans this frame for a tile dragged to (px, py): toward the edge it is near.
+ *
+ * @param px - The horizontal pointer position in pixels.
+ * @param py - The vertical pointer position in pixels.
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @returns Which way, and how far, the table pans this frame for a tile dragged to (px, py): toward the edge it is near.
+ * @example
+ * ```ts
+ * import { edgePan } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(edgePan(5,240,640,480));
+ * ```
+ */
 export declare function edgePan(px: number, py: number, width: number, height: number): {
     dx: number;
     dy: number;

package/dist/tableView.js

@@ -10,6 +10,12 @@ import { boundsOf, placeOf } from "./grid.js";
  * there is always room to build outward, and it zooms to fit the crossword:
  * big tiles for a first word, smaller as the grid spreads, never smaller than
  * a thumb can press (`TABLE.tileLeast`). Past that the table pans instead.
+ *
+ * @example
+ * ```ts
+ * import { TABLE } from "@johnmorrisdotca/kumimoji";
+ * console.log(TABLE);
+ * ```
  */
 export const TABLE = {
     /** Empty squares shown beyond the tiles on every side. */
@@ -40,7 +46,19 @@ export const TABLE = {
     /** How long a dragged tile must stay near an edge before the table pans: crossing an edge on the way in is not asking to pan. */
     edgeDwellMs: 350,
 };
-/** The squares to show: the tiles' extent and the margin, or the margin round square (0, 0) on an empty table. Extra squares (the one a typed letter goes to) are kept in. */
+/** The squares to show: the tiles' extent and the margin, or the margin round square (0, 0) on an empty table. Extra squares (the one a typed letter goes to) are kept in.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param also - Additional square names to include in the table bounds.
+ * @returns The squares to show: the tiles' extent and the margin, or the margin round square (0, 0) on an empty table. Extra squares (the one a typed letter goes to) are kept in.
+ * @example
+ * ```ts
+ * import { tableArea } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(tableArea(tiles));
+ * ```
+ */
 export function tableArea(tiles, also = []) {
     const bounds = boundsOf(tiles) ?? { top: 0, left: 0, bottom: 0, right: 0 };
     let { top, left, bottom, right } = bounds;
@@ -60,6 +78,16 @@ export function tableArea(tiles, also = []) {
  * the Regular desk table; past that, in proportion, so a table the player asked
  * to be Large or Full (`BoardScale`) draws bigger squares rather than only more
  * of them — never past what a hand may zoom to.
+ *
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @returns The largest a fitted tile is drawn in a table this big. `tileMost` in any table up to `growsFrom` across its shorter side, which is every phone's and the Regular desk table; past that, in proportion, so a table the player asked to be Large or Full (`BoardScale`) draws bigger squares rather than only more of them — never past what a hand may zoom to.
+ * @example
+ * ```ts
+ * import { fittedMost } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(fittedMost(640,480));
+ * ```
  */
 export function fittedMost(width, height) {
     const side = Math.min(width, height);
@@ -71,6 +99,19 @@ export function fittedMost(width, height) {
  * The view that shows the whole area, centred, its tiles as big as fit between
  * the least and the most. A picture nobody presses (a finished grid, the
  * set-up preview) passes a smaller least, so a whole grid fits its box.
+ *
+ * @param area - The occupied table bounds.
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @param least - The minimum permitted tile size.
+ * @returns The view that shows the whole area, centred, its tiles as big as fit between the least and the most. A picture nobody presses (a finished grid, the set-up preview) passes a smaller least, so a whole grid fits its box.
+ * @example
+ * ```ts
+ * import { fitView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * console.log(fitView(area,640,480));
+ * ```
  */
 export function fitView(area, width, height, least = TABLE.tileLeast) {
     const fits = Math.min(width / area.cols, height / area.rows);
@@ -81,17 +122,59 @@ export function fitView(area, width, height, least = TABLE.tileLeast) {
         y: Math.round((height - area.rows * tile) / 2 - area.top * tile),
     };
 }
-/** Whether the area, at this view's size, is bigger than the screen: then the table pans. */
+/** Whether the area, at this view's size, is bigger than the screen: then the table pans.
+ *
+ * @param area - The occupied table bounds.
+ * @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 Whether the area, at this view's size, is bigger than the screen: then the table pans.
+ * @example
+ * ```ts
+ * import { overflows } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * const view = {tile:40,x:100,y:100};
+ * console.log(overflows(area,view,640,480));
+ * ```
+ */
 export function overflows(area, view, width, height) {
     return area.cols * view.tile > width + 0.5 || area.rows * view.tile > height + 0.5;
 }
-/** Zoomed by `factor` about the point (px, py) on the screen, which stays over the same spot of the table. */
+/** Zoomed by `factor` about the point (px, py) on the screen, which stays over the same spot of the table.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param factor - The positive scale factor for zooming.
+ * @param px - The horizontal pointer position in pixels.
+ * @param py - The vertical pointer position in pixels.
+ * @returns Zoomed by `factor` about the point (px, py) on the screen, which stays over the same spot of the table.
+ * @example
+ * ```ts
+ * import { zoomView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * console.log(zoomView(view,1.2,320,240));
+ * ```
+ */
 export function zoomView(view, factor, px, py) {
     const tile = Math.max(TABLE.zoomLeast, Math.min(TABLE.zoomMost, view.tile * factor));
     const scale = tile / view.tile;
     return { tile, x: px - (px - view.x) * scale, y: py - (py - view.y) * scale };
 }
-/** The view moved by `dx` and `dy` screen pixels. */
+/** The view moved by `dx` and `dy` screen pixels.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param dx - The horizontal pixel movement.
+ * @param dy - The vertical pixel movement.
+ * @returns The view moved by `dx` and `dy` screen pixels.
+ * @example
+ * ```ts
+ * import { panView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * console.log(panView(view,20,10));
+ * ```
+ */
 export function panView(view, dx, dy) {
     return { ...view, x: view.x + dx, y: view.y + dy };
 }
@@ -99,6 +182,20 @@ export function panView(view, dx, dy) {
  * Kept within reach: some of the area always on the screen, so a pan can
  * never lose the crossword. A quarter of the screen or two tiles, whichever
  * is less, stays in view on every side.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param area - The occupied table bounds.
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @returns Kept within reach: some of the area always on the screen, so a pan can never lose the crossword. A quarter of the screen or two tiles, whichever is less, stays in view on every side.
+ * @example
+ * ```ts
+ * import { keepInReach } from "@johnmorrisdotca/kumimoji";
+ *
+ * const area = {top:0,left:0,rows:1,cols:3};
+ * const view = {tile:40,x:100,y:100};
+ * console.log(keepInReach(view,area,640,480));
+ * ```
  */
 export function keepInReach(view, area, width, height) {
     const hold = (span) => Math.min(span / 4, view.tile * 2);
@@ -117,11 +214,37 @@ export function keepInReach(view, area, width, height) {
         y -= top - (height - hold(height));
     return { ...view, x, y };
 }
-/** The square under a point on the screen. */
+/** The square under a point on the screen.
+ *
+ * @param view - The current tile size and pixel translation.
+ * @param px - The horizontal pointer position in pixels.
+ * @param py - The vertical pointer position in pixels.
+ * @returns The square under a point on the screen.
+ * @example
+ * ```ts
+ * import { squareUnder } from "@johnmorrisdotca/kumimoji";
+ *
+ * const view = {tile:40,x:100,y:100};
+ * console.log(squareUnder(view,100,100));
+ * ```
+ */
 export function squareUnder(view, px, py) {
     return { row: Math.floor((py - view.y) / view.tile), col: Math.floor((px - view.x) / view.tile) };
 }
-/** Which way, and how far, the table pans this frame for a tile dragged to (px, py): toward the edge it is near. */
+/** Which way, and how far, the table pans this frame for a tile dragged to (px, py): toward the edge it is near.
+ *
+ * @param px - The horizontal pointer position in pixels.
+ * @param py - The vertical pointer position in pixels.
+ * @param width - The available viewport width in pixels.
+ * @param height - The available viewport height in pixels.
+ * @returns Which way, and how far, the table pans this frame for a tile dragged to (px, py): toward the edge it is near.
+ * @example
+ * ```ts
+ * import { edgePan } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(edgePan(5,240,640,480));
+ * ```
+ */
 export function edgePan(px, py, width, height) {
     const step = (near) => (near < TABLE.edge ? TABLE.edgeStep * (1 - Math.max(0, near) / TABLE.edge) : 0);
     return { dx: step(px) - step(width - px), dy: step(py) - step(height - py) };

package/dist/tileFace.d.ts

@@ -6,13 +6,47 @@
  * `KANA_TILE_START`, or above `KANA_WILD_START` for a wild given that kana.
  * So the set-up's preview and a finished game's page draw Japanese tiles
  * without fetching the dictionary, and `tileWords` reads the same codes.
+ *
+ * @example
+ * ```ts
+ * import { KANA_TILE_START } from "@johnmorrisdotca/kumimoji";
+ * console.log(KANA_TILE_START);
+ * ```
  */
 export declare const KANA_TILE_START = 57344;
-/** Where the codes of wild tiles given a kana begin: the kana's place in `BASE_KANA` above this. */
+/** Where the codes of wild tiles given a kana begin: the kana's place in `BASE_KANA` above this.
+ *
+ * @example
+ * ```ts
+ * import { KANA_WILD_START } from "@johnmorrisdotca/kumimoji";
+ * console.log(KANA_WILD_START);
+ * ```
+ */
 export declare const KANA_WILD_START = 61440;
-/** The code of a base kana's tile, or of a wild given that kana. */
+/** The code of a base kana's tile, or of a wild given that kana.
+ *
+ * @param kana - The hiragana reading to map to a base tile.
+ * @param wild - Whether to encode the assigned face as a wild tile.
+ * @returns The internal tile code, or null when the kana has no supported base tile.
+ * @example
+ * ```ts
+ * import { kanaTileCode } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kanaTileCode("は"));
+ * ```
+ */
 export declare function kanaTileCode(kana: string, wild?: boolean): string | null;
-/** What a tile shows: what `tileFace` answers. */
+/** What a tile shows: what `tileFace` answers.
+ *
+ * @example
+ * ```ts
+ * import type { TileFaceOf } from "@johnmorrisdotca/kumimoji";
+ * import { tileFace } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: TileFaceOf = tileFace("A");
+ * console.log(value);
+ * ```
+ */
 export type TileFaceOf = {
     /** The letter or kana printed on it: 五 on a wild nobody has given one. */
     glyph: string;
@@ -23,7 +57,27 @@ export type TileFaceOf = {
     /** A wild with no letter yet. */
     blank: boolean;
 };
-/** What a tile code shows, read without the word list: its letter or kana, its corner forms, and whether it is a wild. */
+/** What a tile code shows, read without the word list: its letter or kana, its corner forms, and whether it is a wild.
+ *
+ * @param tile - The internal tile code to describe.
+ * @returns What a tile code shows, read without the word list: its letter or kana, its corner forms, and whether it is a wild.
+ * @example
+ * ```ts
+ * import { tileFace } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileFace("A"));
+ * ```
+ */
 export declare function tileFace(tile: string): TileFaceOf;
-/** What a screen reader says for a tile: its letter, or that it is a wild and what it stands for. */
+/** What a screen reader says for a tile: its letter, or that it is a wild and what it stands for.
+ *
+ * @param tile - The internal tile code to describe.
+ * @returns What a screen reader says for a tile: its letter, or that it is a wild and what it stands for.
+ * @example
+ * ```ts
+ * import { tileDescription } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileDescription("A"));
+ * ```
+ */
 export declare function tileDescription(tile: string): string;

package/dist/tileFace.js

@@ -7,17 +7,51 @@ import { BASE_KANA, CORNER_FORMS } from "./kana.js";
  * `KANA_TILE_START`, or above `KANA_WILD_START` for a wild given that kana.
  * So the set-up's preview and a finished game's page draw Japanese tiles
  * without fetching the dictionary, and `tileWords` reads the same codes.
+ *
+ * @example
+ * ```ts
+ * import { KANA_TILE_START } from "@johnmorrisdotca/kumimoji";
+ * console.log(KANA_TILE_START);
+ * ```
  */
 export const KANA_TILE_START = 0xe000;
-/** Where the codes of wild tiles given a kana begin: the kana's place in `BASE_KANA` above this. */
+/** Where the codes of wild tiles given a kana begin: the kana's place in `BASE_KANA` above this.
+ *
+ * @example
+ * ```ts
+ * import { KANA_WILD_START } from "@johnmorrisdotca/kumimoji";
+ * console.log(KANA_WILD_START);
+ * ```
+ */
 export const KANA_WILD_START = 0xf000;
 const KANA = [...BASE_KANA];
-/** The code of a base kana's tile, or of a wild given that kana. */
+/** The code of a base kana's tile, or of a wild given that kana.
+ *
+ * @param kana - The hiragana reading to map to a base tile.
+ * @param wild - Whether to encode the assigned face as a wild tile.
+ * @returns The internal tile code, or null when the kana has no supported base tile.
+ * @example
+ * ```ts
+ * import { kanaTileCode } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kanaTileCode("は"));
+ * ```
+ */
 export function kanaTileCode(kana, wild = false) {
     const at = KANA.indexOf(kana);
     return at === -1 ? null : String.fromCodePoint((wild ? KANA_WILD_START : KANA_TILE_START) + at);
 }
-/** What a tile code shows, read without the word list: its letter or kana, its corner forms, and whether it is a wild. */
+/** What a tile code shows, read without the word list: its letter or kana, its corner forms, and whether it is a wild.
+ *
+ * @param tile - The internal tile code to describe.
+ * @returns What a tile code shows, read without the word list: its letter or kana, its corner forms, and whether it is a wild.
+ * @example
+ * ```ts
+ * import { tileFace } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileFace("A"));
+ * ```
+ */
 export function tileFace(tile) {
     if (tile === "*")
         return { glyph: "五", forms: "", wild: true, blank: true };
@@ -32,7 +66,17 @@ export function tileFace(tile) {
         return { glyph: wildKana, forms: "", wild: true, blank: false };
     return { glyph: tile, forms: "", wild: false, blank: false };
 }
-/** What a screen reader says for a tile: its letter, or that it is a wild and what it stands for. */
+/** What a screen reader says for a tile: its letter, or that it is a wild and what it stands for.
+ *
+ * @param tile - The internal tile code to describe.
+ * @returns What a screen reader says for a tile: its letter, or that it is a wild and what it stands for.
+ * @example
+ * ```ts
+ * import { tileDescription } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileDescription("A"));
+ * ```
+ */
 export function tileDescription(tile) {
     const face = tileFace(tile);
     if (face.wild)

package/dist/tileFamily.d.ts

@@ -7,5 +7,14 @@ import type { KumimojiLanguage } from "./kumimoji.types.ts";
  * several devices (docs/plans/party-online/README.md, John 2026-09-29: the
  * browser checks the words, the server only that the tiles are real).
  * `tileFamily.test.ts` holds the two to one another.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns A function returning the physical family of a tile, or null for an invalid code.
+ * @example
+ * ```ts
+ * import { familyKeyOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(familyKeyOf("english")("A"));
+ * ```
  */
 export declare function familyKeyOf(language: KumimojiLanguage): (tile: string) => string | null;

package/dist/tileFamily.js

@@ -8,6 +8,15 @@ import { KANA_TILE_START, KANA_WILD_START, tileFace } from "./tileFace.js";
  * several devices (docs/plans/party-online/README.md, John 2026-09-29: the
  * browser checks the words, the server only that the tiles are real).
  * `tileFamily.test.ts` holds the two to one another.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns A function returning the physical family of a tile, or null for an invalid code.
+ * @example
+ * ```ts
+ * import { familyKeyOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(familyKeyOf("english")("A"));
+ * ```
  */
 export function familyKeyOf(language) {
     if (language === "english") {