@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

package/dist/random.d.ts

@@ -4,9 +4,40 @@
  * is small, fast and good enough for shuffling tiles; nothing here is a
  * credential.
  */
-/** A number in [0, 1), like `Math.random`, from a stream a seed fixes. */
+/** A number in [0, 1), like `Math.random`, from a stream a seed fixes.
+ *
+ * @example
+ * ```ts
+ * import type { Random } from "@johnmorrisdotca/kumimoji";
+ * import { seededRandom } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: Random = seededRandom(42);
+ * console.log(value);
+ * ```
+ */
 export type Random = () => number;
-/** A stream of numbers in [0, 1) that the seed fixes: mulberry32. */
+/** A stream of numbers in [0, 1) that the seed fixes: mulberry32.
+ *
+ * @param seed - The numeric seed for deterministic deals or random draws.
+ * @returns A stream of numbers in [0, 1) that the seed fixes: mulberry32.
+ * @example
+ * ```ts
+ * import { seededRandom } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(seededRandom(42)());
+ * ```
+ */
 export declare function seededRandom(seed: number): Random;
-/** A copy of the list in a random order (Fisher–Yates). */
+/** A copy of the list in a random order (Fisher–Yates).
+ *
+ * @param items - The items to copy and shuffle.
+ * @param random - A reproducible random function returning values in [0,1).
+ * @returns A copy of the list in a random order (Fisher–Yates).
+ * @example
+ * ```ts
+ * import { seededRandom, shuffled } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(shuffled(["c","a","t"],seededRandom(42)));
+ * ```
+ */
 export declare function shuffled<T>(items: readonly T[], random: Random): T[];

package/dist/random.js

@@ -4,7 +4,17 @@
  * is small, fast and good enough for shuffling tiles; nothing here is a
  * credential.
  */
-/** A stream of numbers in [0, 1) that the seed fixes: mulberry32. */
+/** A stream of numbers in [0, 1) that the seed fixes: mulberry32.
+ *
+ * @param seed - The numeric seed for deterministic deals or random draws.
+ * @returns A stream of numbers in [0, 1) that the seed fixes: mulberry32.
+ * @example
+ * ```ts
+ * import { seededRandom } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(seededRandom(42)());
+ * ```
+ */
 export function seededRandom(seed) {
     let state = seed >>> 0;
     return () => {
@@ -15,7 +25,18 @@ export function seededRandom(seed) {
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     };
 }
-/** A copy of the list in a random order (Fisher–Yates). */
+/** A copy of the list in a random order (Fisher–Yates).
+ *
+ * @param items - The items to copy and shuffle.
+ * @param random - A reproducible random function returning values in [0,1).
+ * @returns A copy of the list in a random order (Fisher–Yates).
+ * @example
+ * ```ts
+ * import { seededRandom, shuffled } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(shuffled(["c","a","t"],seededRandom(42)));
+ * ```
+ */
 export function shuffled(items, random) {
     const out = [...items];
     for (let i = out.length - 1; i > 0; i -= 1) {

package/dist/react.d.ts

@@ -1,7 +1,21 @@
 import { type HTMLAttributes } from "react";
 import type { GridVerdict, Tiles } from "./grid.ts";
 import { type KumimojiTableOptions } from "./ui/mount.ts";
-/** What `KumimojiBoard` takes: a grid to draw, and any attribute of its `<div>`. */
+/** What `KumimojiBoard` takes: a grid to draw, and any attribute of its `<div>`.
+ *
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { judgeWithWords } from "@johnmorrisdotca/kumimoji";
+ * import type { KumimojiBoardProps } from "@johnmorrisdotca/kumimoji/react";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
+ * const value: KumimojiBoardProps = {tiles,verdict:null};
+ * console.log(value);
+ * ```
+ */
 export type KumimojiBoardProps = {
     /** The tiles on the table, by square: `play.tiles`. */
     tiles: Tiles;
@@ -22,14 +36,38 @@ export type KumimojiBoardProps = {
  * apart from the crossword faded, and a press on any square reported by its
  * key (`squareAt(row, col)`). It draws; what a press does is yours to decide
  * with `placeFromHand`, `moveOnTable` and the rest.
+ *
+ * @param options - Native game, component or presentation options.
+ * @returns The React grid element.
+ * @example
+ * ```ts no-run
+ * import {createElement} from "react";
+ * import { KumimojiBoard } from "@johnmorrisdotca/kumimoji/react";
+ * console.log(createElement(KumimojiBoard,{tiles:new Map([["0,0","c"]])}));
+ * ```
  */
 export declare function KumimojiBoard({ tiles, verdict, glyphOf, onSquare, held, square, style, ...element }: KumimojiBoardProps): import("react").JSX.Element;
-/** What `KumimojiTable` takes: the options of `mountKumimoji`, and any attribute of its `<div>`. */
+/**
+ * Native table options, readiness/error choices and attributes of the host div.
+ * @example
+ * ```ts
+ * import type { KumimojiTableProps } from "@johnmorrisdotca/kumimoji/react";
+ * const props: KumimojiTableProps = { controls: true, keep: false, onError: error => console.log(error.message) };
+ * console.log(props.controls);
+ * ```
+ */
 export type KumimojiTableProps = KumimojiTableOptions & Omit<HTMLAttributes<HTMLDivElement>, keyof KumimojiTableOptions>;
 /**
  * A whole game alone, as a React component: the plain-DOM table
  * (`mountKumimoji`) mounted into this component's element once the browser
  * has it. Options are read when it mounts; give it a new `key` to start over
- * with different ones.
+ * with different ones. Native callbacks are forwarded independently of host DOM events.
+ * @param props - Native table choices and host-div attributes.
+ * @returns A div whose effect owns the native table and cleanup.
+ * @example
+ * ```ts
+ * import { KumimojiTable } from "@johnmorrisdotca/kumimoji/react";
+ * console.log(typeof KumimojiTable);
+ * ```
  */
-export declare function KumimojiTable({ language, hand, level, gameLength, diagonals, seed, onFinish, onChange, locale, strings, theme, keep, ...element }: KumimojiTableProps): import("react").JSX.Element;
+export declare function KumimojiTable(props: KumimojiTableProps): import("react").JSX.Element;

package/dist/react.js

@@ -17,6 +17,15 @@ const TILE = {
  * apart from the crossword faded, and a press on any square reported by its
  * key (`squareAt(row, col)`). It draws; what a press does is yours to decide
  * with `placeFromHand`, `moveOnTable` and the rest.
+ *
+ * @param options - Native game, component or presentation options.
+ * @returns The React grid element.
+ * @example
+ * ```ts no-run
+ * import {createElement} from "react";
+ * import { KumimojiBoard } from "@johnmorrisdotca/kumimoji/react";
+ * console.log(createElement(KumimojiBoard,{tiles:new Map([["0,0","c"]])}));
+ * ```
  */
 export function KumimojiBoard({ tiles, verdict = null, glyphOf, onSquare, held = null, square = 36, style, ...element }) {
     const model = boardModel(tiles, verdict, glyphOf);
@@ -32,19 +41,27 @@ export function KumimojiBoard({ tiles, verdict = null, glyphOf, onSquare, held =
  * A whole game alone, as a React component: the plain-DOM table
  * (`mountKumimoji`) mounted into this component's element once the browser
  * has it. Options are read when it mounts; give it a new `key` to start over
- * with different ones.
+ * with different ones. Native callbacks are forwarded independently of host DOM events.
+ * @param props - Native table choices and host-div attributes.
+ * @returns A div whose effect owns the native table and cleanup.
+ * @example
+ * ```ts
+ * import { KumimojiTable } from "@johnmorrisdotca/kumimoji/react";
+ * console.log(typeof KumimojiTable);
+ * ```
  */
-export function KumimojiTable({ language, hand, level, gameLength, diagonals, seed, onFinish, onChange, locale, strings, theme, keep, ...element }) {
+export function KumimojiTable(props) {
+    const { language, hand, level, gameLength, diagonals, seed, onFinish, onChange, locale, strings, theme, keep, controls, saved, onError, ...element } = props;
     const host = useRef(null);
-    const latest = useRef({ onFinish, onChange });
+    const latest = useRef({ onFinish, onChange, onError });
     useEffect(() => {
-        latest.current = { onFinish, onChange };
+        latest.current = { onFinish, onChange, onError };
     });
     useEffect(() => {
         const target = host.current;
         if (target === null)
             return;
-        const table = mountKumimoji(target, { language, hand, level, gameLength, diagonals, seed, locale, strings, theme, keep, onFinish: (result) => latest.current.onFinish?.(result), onChange: (saved) => latest.current.onChange?.(saved) });
+        const table = mountKumimoji(target, { language, hand, level, gameLength, diagonals, seed, locale, strings, theme, keep, controls, saved, onError: error => latest.current.onError?.(error), onFinish: (result) => latest.current.onFinish?.(result), onChange: (saved) => latest.current.onChange?.(saved) });
         return () => table.destroy();
         // Mounted once per key, as documented above.
         // eslint-disable-next-line react-hooks/exhaustive-deps

package/dist/showcase.d.ts

@@ -6,14 +6,35 @@ import type { KumimojiLanguage, KumimojiLength } from "./kumimoji.types.ts";
  * each length of game deals. Pure, so the rules page draws it at build time
  * and the tests hold it to the constants.
  */
-/** One kind of tile in a set: the code the game deals, what is printed on it, what shows in its corner, and how many the set holds. */
+/** One kind of tile in a set: the code the game deals, what is printed on it, what shows in its corner, and how many the set holds.
+ *
+ * @example
+ * ```ts
+ * import type { MixTile } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: MixTile = {code:"c",glyph:"c",forms:"",count:2};
+ * console.log(value);
+ * ```
+ */
 export type MixTile = {
     code: string;
     glyph: string;
     forms: string;
     count: number;
 };
-/** A whole set, in its own order (a to z, あ to ん), with what a reader needs to see how uneven it is. */
+/** A whole set, in its own order (a to z, あ to ん), with what a reader needs to see how uneven it is.
+ *
+ * @example
+ * ```ts
+ * import type { MixShown } from "@johnmorrisdotca/kumimoji";
+ * import { mixShown } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const value: MixShown = mixShown("english");
+ * console.log(value);
+ * ```
+ */
 export type MixShown = {
     tiles: MixTile[];
     total: number;
@@ -25,11 +46,43 @@ export type MixShown = {
     /** The tiles with the most, the ones a hand is full of. */
     commonest: string[];
 };
-/** A language's set as a page shows it: every tile with its count, the total, and which are the rarest and the commonest. */
+/** A language's set as a page shows it: every tile with its count, the total, and which are the rarest and the commonest.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns A language's set as a page shows it: every tile with its count, the total, and which are the rarest and the commonest.
+ * @example
+ * ```ts
+ * import { mixShown } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(mixShown("english").total);
+ * ```
+ */
 export declare function mixShown(language: KumimojiLanguage): MixShown;
-/** Every hiragana a tile plays as, itself first: は is は, ば and ぱ. None for a kana that is not a tile's own. */
+/** Every hiragana a tile plays as, itself first: は is は, ば and ぱ. None for a kana that is not a tile's own.
+ *
+ * @param kana - The hiragana reading to map to a base tile.
+ * @returns Every hiragana a tile plays as, itself first: は is は, ば and ぱ. None for a kana that is not a tile's own.
+ * @example
+ * ```ts
+ * import { formsOfTile } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(formsOfTile("は"));
+ * ```
+ */
 export declare function formsOfTile(kana: string): string[];
-/** One length of game at one opening hand: how many tiles it deals from one set and from two, and how many of them are wild at each level. */
+/** One length of game at one opening hand: how many tiles it deals from one set and from two, and how many of them are wild at each level.
+ *
+ * @example
+ * ```ts
+ * import type { LengthRow } from "@johnmorrisdotca/kumimoji";
+ * import { lengthRows } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: LengthRow = lengthRows(7)[0];
+ * console.log(value);
+ * ```
+ */
 export type LengthRow = {
     length: KumimojiLength;
     tiles: number;
@@ -37,9 +90,26 @@ export type LengthRow = {
     doubleTiles: number;
     wilds: Record<"easy" | "medium" | "hard", number>;
 };
-/** The lengths of game, shortest first. */
+/** The lengths of game, shortest first.
+ *
+ * @example
+ * ```ts
+ * import { LENGTHS } from "@johnmorrisdotca/kumimoji";
+ * console.log(LENGTHS);
+ * ```
+ */
 export declare const LENGTHS: readonly KumimojiLength[];
-/** For one opening hand, each length of game: how many tiles it deals, from one set and from two, and how many are wild at each level. */
+/** For one opening hand, each length of game: how many tiles it deals, from one set and from two, and how many are wild at each level.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @returns For one opening hand, each length of game: how many tiles it deals, from one set and from two, and how many are wild at each level.
+ * @example
+ * ```ts
+ * import { lengthRows } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(lengthRows(7));
+ * ```
+ */
 export declare function lengthRows(hand?: number): LengthRow[];
 /**
  * THE TRY-IT ON THE FRONT DOOR: a Kumimoji of ten tiles, played in the
@@ -48,6 +118,12 @@ export declare function lengthRows(hand?: number): LengthRow[];
  * fixed rather than dealt, so the page is the same for everybody and needs no
  * generator; `showcase.test.ts` proves it can be finished, with a crossword
  * checked against the real list.
+ *
+ * @example
+ * ```ts
+ * import { TRY_IT } from "@johnmorrisdotca/kumimoji";
+ * console.log(TRY_IT);
+ * ```
  */
 export declare const TRY_IT: {
     readonly bag: "rotenasdi*";

package/dist/showcase.js

@@ -1,7 +1,19 @@
 import { BASE_KANA, CORNER_FORMS, tileKana } from "./kana.js";
 import { kanaTileCode } from "./tileFace.js";
 import { JAPANESE_TILE_MIX, KUMIMOJI_HANDS, TILE_MIX, kumimojiTileCount, kumimojiWildCount } from "./tiles.constants.js";
-/** A language's set as a page shows it: every tile with its count, the total, and which are the rarest and the commonest. */
+/** A language's set as a page shows it: every tile with its count, the total, and which are the rarest and the commonest.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns A language's set as a page shows it: every tile with its count, the total, and which are the rarest and the commonest.
+ * @example
+ * ```ts
+ * import { mixShown } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(mixShown("english").total);
+ * ```
+ */
 export function mixShown(language) {
     const tiles = language === "english"
         ? Object.entries(TILE_MIX).map(([letter, count]) => ({ code: letter, glyph: letter, forms: "", count }))
@@ -26,7 +38,17 @@ export function mixShown(language) {
  */
 const HIRAGANA_FIRST = 0x3041;
 const HIRAGANA_LAST = 0x3096;
-/** Every hiragana a tile plays as, itself first: は is は, ば and ぱ. None for a kana that is not a tile's own. */
+/** Every hiragana a tile plays as, itself first: は is は, ば and ぱ. None for a kana that is not a tile's own.
+ *
+ * @param kana - The hiragana reading to map to a base tile.
+ * @returns Every hiragana a tile plays as, itself first: は is は, ば and ぱ. None for a kana that is not a tile's own.
+ * @example
+ * ```ts
+ * import { formsOfTile } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(formsOfTile("は"));
+ * ```
+ */
 export function formsOfTile(kana) {
     if (tileKana(kana) !== kana)
         return [];
@@ -38,9 +60,26 @@ export function formsOfTile(kana) {
     }
     return forms;
 }
-/** The lengths of game, shortest first. */
+/** The lengths of game, shortest first.
+ *
+ * @example
+ * ```ts
+ * import { LENGTHS } from "@johnmorrisdotca/kumimoji";
+ * console.log(LENGTHS);
+ * ```
+ */
 export const LENGTHS = ["short", "medium", "full"];
-/** For one opening hand, each length of game: how many tiles it deals, from one set and from two, and how many are wild at each level. */
+/** For one opening hand, each length of game: how many tiles it deals, from one set and from two, and how many are wild at each level.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @returns For one opening hand, each length of game: how many tiles it deals, from one set and from two, and how many are wild at each level.
+ * @example
+ * ```ts
+ * import { lengthRows } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(lengthRows(7));
+ * ```
+ */
 export function lengthRows(hand = KUMIMOJI_HANDS.classic) {
     return LENGTHS.map((length) => {
         const tiles = kumimojiTileCount(hand, length);
@@ -59,5 +98,11 @@ export function lengthRows(hand = KUMIMOJI_HANDS.classic) {
  * fixed rather than dealt, so the page is the same for everybody and needs no
  * generator; `showcase.test.ts` proves it can be finished, with a crossword
  * checked against the real list.
+ *
+ * @example
+ * ```ts
+ * import { TRY_IT } from "@johnmorrisdotca/kumimoji";
+ * console.log(TRY_IT);
+ * ```
  */
 export const TRY_IT = { bag: "rotenasdi*", hand: 7 };

package/dist/strings.d.ts

@@ -11,10 +11,20 @@
  * `docs/strings-ja.md` lists the two languages side by side and is made from
  * this file.
  */
-/** The languages the table speaks: English and Japanese. */
+/** The languages the table speaks: English and Japanese.
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiLocale } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * const value: KumimojiLocale = "ja";
+ * console.log(value);
+ * ```
+ */
 export type KumimojiLocale = "en" | "ja";
 declare const EN: {
     dealing: string;
+    loadError: string;
     leftOne: string;
     left: string;
     finished: string;
@@ -50,14 +60,53 @@ declare const EN: {
     english: string;
     japanese: string;
 };
-/** Every word the table shows, by name: one table of these for each language. */
+/** Every word the table shows, by name: one table of these for each language.
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiStrings } from "@johnmorrisdotca/kumimoji/ui";
+ * import { kumimojiStrings } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * const value: KumimojiStrings = kumimojiStrings("ja");
+ * console.log(value);
+ * ```
+ */
 export type KumimojiStrings = {
     [Name in keyof typeof EN]: string;
 };
-/** The table's words in each language it speaks: `KUMIMOJI_STRINGS.en`, `KUMIMOJI_STRINGS.ja`. */
+/** The table's words in each language it speaks: `KUMIMOJI_STRINGS.en`, `KUMIMOJI_STRINGS.ja`.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_STRINGS } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(KUMIMOJI_STRINGS);
+ * ```
+ */
 export declare const KUMIMOJI_STRINGS: Readonly<Record<KumimojiLocale, KumimojiStrings>>;
-/** A line from a table of strings with its braces filled in: `kumimojiSay(strings.left, { n: 12, time: "1:05" })`. A brace with no value is left as it is. */
+/** A line from a table of strings with its braces filled in: `kumimojiSay(strings.left, { n: 12, time: "1:05" })`. A brace with no value is left as it is.
+ *
+ * @param line - Text containing named replacement braces.
+ * @param values - Replacement text or numbers keyed by brace name.
+ * @returns A line from a table of strings with its braces filled in: `kumimojiSay(strings.left, { n: 12, time: "1:05" })`. A brace with no value is left as it is.
+ * @example
+ * ```ts
+ * import { kumimojiSay } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * console.log(kumimojiSay("Tile {n}",{n:3}));
+ * ```
+ */
 export declare function kumimojiSay(line: string, values?: Readonly<Record<string, string | number>>): string;
-/** The table of strings for a locale with a page's own words laid over it. An unknown locale is English. */
+/** The table of strings for a locale with a page's own words laid over it. An unknown locale is English.
+ *
+ * @param locale - The requested display language tag.
+ * @param own - Optional overrides for built-in display words.
+ * @returns The table of strings for a locale with a page's own words laid over it. An unknown locale is English.
+ * @example
+ * ```ts
+ * import { kumimojiStrings } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * console.log(Object.keys(kumimojiStrings("ja")).length);
+ * ```
+ */
 export declare function kumimojiStrings(locale: KumimojiLocale | string | undefined, own?: Partial<KumimojiStrings>): KumimojiStrings;
 export {};

package/dist/strings.js

@@ -13,6 +13,7 @@
  */
 const EN = {
     dealing: "Dealing…",
+    loadError: "The word list could not be loaded. Try again.",
     leftOne: "1 tile left in the bag · {time}",
     left: "{n} tiles left in the bag · {time}",
     finished: "Finished in {time}. Every tile laid, every run a word.",
@@ -50,6 +51,7 @@ const EN = {
 };
 const JA = {
     dealing: "配っています…",
+    loadError: "単語の一覧を読み込めませんでした。もう一度お試しください。",
     leftOne: "袋の残り1枚 · {time}",
     left: "袋の残り{n}枚 · {time}",
     finished: "{time}で完成しました。すべてのタイルを置き、どの並びも単語になっています。",
@@ -85,13 +87,42 @@ const JA = {
     english: "英語",
     japanese: "日本語",
 };
-/** The table's words in each language it speaks: `KUMIMOJI_STRINGS.en`, `KUMIMOJI_STRINGS.ja`. */
+/** The table's words in each language it speaks: `KUMIMOJI_STRINGS.en`, `KUMIMOJI_STRINGS.ja`.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_STRINGS } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(KUMIMOJI_STRINGS);
+ * ```
+ */
 export const KUMIMOJI_STRINGS = { en: EN, ja: JA };
-/** A line from a table of strings with its braces filled in: `kumimojiSay(strings.left, { n: 12, time: "1:05" })`. A brace with no value is left as it is. */
+/** A line from a table of strings with its braces filled in: `kumimojiSay(strings.left, { n: 12, time: "1:05" })`. A brace with no value is left as it is.
+ *
+ * @param line - Text containing named replacement braces.
+ * @param values - Replacement text or numbers keyed by brace name.
+ * @returns A line from a table of strings with its braces filled in: `kumimojiSay(strings.left, { n: 12, time: "1:05" })`. A brace with no value is left as it is.
+ * @example
+ * ```ts
+ * import { kumimojiSay } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * console.log(kumimojiSay("Tile {n}",{n:3}));
+ * ```
+ */
 export function kumimojiSay(line, values = {}) {
     return line.replace(/\{(\w+)\}/g, (whole, name) => (name in values ? String(values[name]) : whole));
 }
-/** The table of strings for a locale with a page's own words laid over it. An unknown locale is English. */
+/** The table of strings for a locale with a page's own words laid over it. An unknown locale is English.
+ *
+ * @param locale - The requested display language tag.
+ * @param own - Optional overrides for built-in display words.
+ * @returns The table of strings for a locale with a page's own words laid over it. An unknown locale is English.
+ * @example
+ * ```ts
+ * import { kumimojiStrings } from "@johnmorrisdotca/kumimoji/ui";
+ *
+ * console.log(Object.keys(kumimojiStrings("ja")).length);
+ * ```
+ */
 export function kumimojiStrings(locale, own = {}) {
     const base = typeof locale === "string" && locale.toLowerCase().startsWith("ja") ? JA : EN;
     return { ...base, ...own };