@johnmorrisdotca/kumimoji 1.2.1 → 1.3.0

package/dist/element.js

@@ -9,14 +9,16 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var _KumimojiTable_instances, _KumimojiTable_table, _KumimojiTable_key, _KumimojiTable_queued, _KumimojiTable_seed, _KumimojiTable_refresh;
+var _KumimojiTable_instances, _KumimojiTable_table, _KumimojiTable_key, _KumimojiTable_queued, _KumimojiTable_seed, _KumimojiTable_options, _KumimojiTable_revision, _KumimojiTable_widthBefore, _KumimojiTable_widthOwned, _KumimojiTable_labelBefore, _KumimojiTable_write, _KumimojiTable_frame, _KumimojiTable_refresh;
+import { embedDay } from "./embed-day.js";
+import { KUMIMOJI_STYLE } from "./ui/style.js";
 import { kumimojiDailySeed } from "./daily.js";
 import { KUMIMOJI_HANDS } from "./tiles.constants.js";
 import { mountKumimoji } from "./ui/mount.js";
 const ElementBase = typeof HTMLElement === "undefined" ? class {
 } : HTMLElement;
 const oneOf = (value, allowed) => (allowed.includes(value) ? value : undefined);
-const isOn = (value) => value !== null && ["true", "on", "1", "yes"].includes(value.toLowerCase());
+const isOn = (value, fallback = false) => value === null ? fallback : !["false", "off", "no", "0"].includes(value.trim().toLowerCase());
 const HANDS = Object.values(KUMIMOJI_HANDS);
 /**
  * THE `<kumimoji-table>` ELEMENT: a game of Kumimoji alone in a tag, with no
@@ -29,8 +31,7 @@ const HANDS = Object.values(KUMIMOJI_HANDS);
  * <kumimoji-table language="japanese" level="easy" seed="daily"></kumimoji-table>
  * ```
  *
- * Attributes (each is read again when it changes; a change to any but `lang`
- * deals a new game):
+ * Attributes configure the starting game; display, language and control changes preserve play:
  *  - `language`: the tiles, `english` (default) or `japanese` kana.
  *  - `hand`: the opening hand, 3, 7 (default) or 11.
  *  - `level`: how many tiles are wild, `easy` (most), `medium` (default) or `hard` (none).
@@ -42,7 +43,24 @@ const HANDS = Object.values(KUMIMOJI_HANDS);
  * It fires `kumimoji-change` after every change to the game, with the game as it would
  * be saved as `event.detail.saved`, and `kumimoji-finish` when the last tile is laid and every run
  * is a word, with `event.detail` the deal, the play and the time it took. It has the methods
- * `newGame()` and `setGame()`. A table the rules do not offer (a hand of 5, say) draws nothing.
+ * `newGame()` and `setGame()`. Invalid input shows a status and a plain error event.
+ */
+/**
+ * Native table options, checked alongside builder coverage.
+ * @example
+ * ```ts
+ * import { KUMIMOJI_EMBED_OPTION_KEYS } from "@johnmorrisdotca/kumimoji/element";
+ * console.log(KUMIMOJI_EMBED_OPTION_KEYS.includes("saved"));
+ * ```
+ */
+export const KUMIMOJI_EMBED_OPTION_KEYS = Object.keys({ language: true, hand: true, level: true, gameLength: true, diagonals: true, seed: true, onFinish: true, onChange: true, locale: true, strings: true, theme: true, keep: true, controls: true, saved: true, onError: true });
+/**
+ * A reflected crossword table with the native table handle and saved-state getter.
+ * @example
+ * ```ts
+ * import { KumimojiTable } from "@johnmorrisdotca/kumimoji/element";
+ * console.log(KumimojiTable.observedAttributes.includes("daily"));
+ * ```
  */
 export class KumimojiTable extends ElementBase {
     constructor() {
@@ -52,11 +70,22 @@ export class KumimojiTable extends ElementBase {
         _KumimojiTable_key.set(this, "");
         _KumimojiTable_queued.set(this, false);
         _KumimojiTable_seed.set(this, null);
+        _KumimojiTable_options.set(this, {});
+        _KumimojiTable_revision.set(this, 0);
+        _KumimojiTable_widthBefore.set(this, null);
+        _KumimojiTable_widthOwned.set(this, false);
+        _KumimojiTable_labelBefore.set(this, null);
     }
+    /** Native host options. Callback/presentation changes preserve the current game. */
+    get options() { return __classPrivateFieldGet(this, _KumimojiTable_options, "f"); }
+    set options(value) { __classPrivateFieldSet(this, _KumimojiTable_options, value ?? {}, "f"); if (this.isConnected)
+        __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_refresh).call(this); }
     connectedCallback() {
         __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_refresh).call(this);
     }
     disconnectedCallback() {
+        var _a;
+        __classPrivateFieldSet(this, _KumimojiTable_revision, (_a = __classPrivateFieldGet(this, _KumimojiTable_revision, "f"), ++_a), "f");
         __classPrivateFieldGet(this, _KumimojiTable_table, "f")?.destroy();
         __classPrivateFieldSet(this, _KumimojiTable_table, null, "f");
         __classPrivateFieldSet(this, _KumimojiTable_key, "", "f");
@@ -67,7 +96,8 @@ export class KumimojiTable extends ElementBase {
         __classPrivateFieldSet(this, _KumimojiTable_queued, true, "f");
         queueMicrotask(() => {
             __classPrivateFieldSet(this, _KumimojiTable_queued, false, "f");
-            __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_refresh).call(this);
+            if (this.isConnected)
+                __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_refresh).call(this);
         });
     }
     /** The mounted table's handle (`mountKumimoji`), or null while the attributes name no table the rules offer. */
@@ -86,45 +116,146 @@ export class KumimojiTable extends ElementBase {
     setGame(saved) {
         return __classPrivateFieldGet(this, _KumimojiTable_table, "f")?.setGame(saved) ?? Promise.resolve();
     }
+    /** The `language` attribute, reflected. */
+    get language() { return this.getAttribute("language"); }
+    set language(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "language", value); }
+    /** The `hand` attribute, reflected. */
+    get hand() { return this.getAttribute("hand"); }
+    set hand(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "hand", value); }
+    /** The `level` attribute, reflected. */
+    get level() { return this.getAttribute("level"); }
+    set level(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "level", value); }
+    /** The `length` attribute, reflected. */
+    get length() { return this.getAttribute("length"); }
+    set length(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "length", value); }
+    /** The `diagonals` attribute, reflected. */
+    get diagonals() { return this.getAttribute("diagonals"); }
+    set diagonals(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "diagonals", value); }
+    /** The `seed` attribute, reflected. */
+    get seed() { return this.getAttribute("seed"); }
+    set seed(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "seed", value); }
+    /** The `keep` attribute, reflected. */
+    get keep() { return this.getAttribute("keep"); }
+    set keep(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "keep", value); }
+    /** The `daily` attribute, reflected. */
+    get daily() { return this.getAttribute("daily"); }
+    set daily(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "daily", value); }
+    /** The `controls` attribute, reflected. */
+    get controls() { return this.getAttribute("controls"); }
+    set controls(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "controls", value); }
+    /** The `theme` attribute, reflected. */
+    get theme() { return this.getAttribute("theme"); }
+    set theme(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "theme", value); }
+    /** The `size` attribute, reflected. */
+    get size() { return this.getAttribute("size"); }
+    set size(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "size", value); }
+    /** The `width` attribute, reflected. */
+    get width() { return this.getAttribute("width"); }
+    set width(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "width", value); }
+    /** The `label` attribute, reflected. */
+    get label() { return this.getAttribute("label"); }
+    set label(value) { __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_write).call(this, "label", value); }
 }
-_KumimojiTable_table = new WeakMap(), _KumimojiTable_key = new WeakMap(), _KumimojiTable_queued = new WeakMap(), _KumimojiTable_seed = new WeakMap(), _KumimojiTable_instances = new WeakSet(), _KumimojiTable_refresh = function _KumimojiTable_refresh() {
-    const language = oneOf(this.getAttribute("language"), ["english", "japanese"]);
-    const handAttribute = this.getAttribute("hand");
-    const hand = handAttribute === null ? undefined : Number(handAttribute);
-    const level = oneOf(this.getAttribute("level"), ["easy", "medium", "hard"]);
-    const gameLength = oneOf(this.getAttribute("length"), ["short", "medium", "full"]);
-    const diagonals = isOn(this.getAttribute("diagonals"));
-    const seedAttribute = this.getAttribute("seed");
-    const asked = Number(seedAttribute);
-    const seed = seedAttribute === "daily"
-        ? kumimojiDailySeed(new Date())
-        : seedAttribute !== null && Number.isInteger(asked) && asked >= 0 && asked <= 0xffffffff
-            ? asked
-            : (__classPrivateFieldSet(this, _KumimojiTable_seed, __classPrivateFieldGet(this, _KumimojiTable_seed, "f") ?? Math.floor(Math.random() * 2 ** 31), "f"));
-    const lang = this.getAttribute("lang");
-    const locale = lang === "en" || lang === "ja" ? lang : undefined;
-    const keep = !["false", "off", "0", "no"].includes((this.getAttribute("keep") ?? "").toLowerCase());
-    const key = JSON.stringify([language, hand, level, gameLength, diagonals, seed, keep]);
-    if (key === __classPrivateFieldGet(this, _KumimojiTable_key, "f") && __classPrivateFieldGet(this, _KumimojiTable_table, "f") !== null) {
-        __classPrivateFieldGet(this, _KumimojiTable_table, "f").setLocale(locale ?? (document.documentElement.lang.toLowerCase().startsWith("ja") ? "ja" : "en"));
-        return;
+_KumimojiTable_table = new WeakMap(), _KumimojiTable_key = new WeakMap(), _KumimojiTable_queued = new WeakMap(), _KumimojiTable_seed = new WeakMap(), _KumimojiTable_options = new WeakMap(), _KumimojiTable_revision = new WeakMap(), _KumimojiTable_widthBefore = new WeakMap(), _KumimojiTable_widthOwned = new WeakMap(), _KumimojiTable_labelBefore = new WeakMap(), _KumimojiTable_instances = new WeakSet(), _KumimojiTable_write = function _KumimojiTable_write(name, value) { if (value === null || value === undefined)
+    this.removeAttribute(name);
+else
+    this.setAttribute(name, String(value)); }, _KumimojiTable_frame = function _KumimojiTable_frame() {
+    this.style.display = "block";
+    this.style.maxWidth = "100%";
+    const width = Number(this.getAttribute("width")), size = this.getAttribute("size");
+    const pixels = this.hasAttribute("width") && width > 0 && Number.isFinite(width) ? Math.min(width, 2000) : size === "small" ? 320 : size === "medium" ? 480 : size === "large" ? 640 : null;
+    if (pixels !== null) {
+        if (!__classPrivateFieldGet(this, _KumimojiTable_widthOwned, "f"))
+            __classPrivateFieldSet(this, _KumimojiTable_widthBefore, this.style.width, "f");
+        __classPrivateFieldSet(this, _KumimojiTable_widthOwned, true, "f");
+        this.style.width = `${pixels}px`;
+    }
+    else if (__classPrivateFieldGet(this, _KumimojiTable_widthOwned, "f")) {
+        this.style.width = __classPrivateFieldGet(this, _KumimojiTable_widthBefore, "f") ?? "";
+        __classPrivateFieldSet(this, _KumimojiTable_widthOwned, false, "f");
+    }
+    const theme = this.getAttribute("theme");
+    this.style.colorScheme = theme === "light" || theme === "dark" ? theme : "light dark";
+    this.setAttribute("data-kumimoji-embed", "");
+    const root = this.getRootNode(), target = typeof ShadowRoot !== "undefined" && root instanceof ShadowRoot ? root : this.ownerDocument.head;
+    if (target.querySelector("style[data-kumimoji-embed-style]") === null) {
+        const style = this.ownerDocument.createElement("style");
+        style.setAttribute("data-kumimoji-embed-style", "");
+        const light = KUMIMOJI_STYLE.match(/\.km-root \{([^}]+)\}/)?.[1] ?? "";
+        const dark = KUMIMOJI_STYLE.match(/@media \(prefers-color-scheme: dark\) \{\s*\.km-root \{([^}]+)\}/)?.[1] ?? "";
+        style.textContent = `[data-kumimoji-embed][theme="light"] .km-root{${light}}[data-kumimoji-embed][theme="dark"] .km-root{${dark}}[data-kumimoji-embed]>.km-root{background:var(--km-panel);padding:12px;border-radius:12px}[data-kumimoji-embed] .km-controls[hidden]{display:none}`;
+        target.append(style);
+    }
+    if (this.hasAttribute("label")) {
+        __classPrivateFieldSet(this, _KumimojiTable_labelBefore, __classPrivateFieldGet(this, _KumimojiTable_labelBefore, "f") ?? { role: this.getAttribute("role"), label: this.getAttribute("aria-label") }, "f");
+        this.setAttribute("role", "group");
+        this.setAttribute("aria-label", this.getAttribute("label"));
+    }
+    else if (__classPrivateFieldGet(this, _KumimojiTable_labelBefore, "f") !== null) {
+        for (const [name, value] of [["role", __classPrivateFieldGet(this, _KumimojiTable_labelBefore, "f").role], ["aria-label", __classPrivateFieldGet(this, _KumimojiTable_labelBefore, "f").label]]) {
+            if (value === null)
+                this.removeAttribute(name);
+            else
+                this.setAttribute(name, value);
+        }
+        __classPrivateFieldSet(this, _KumimojiTable_labelBefore, null, "f");
+    }
+}, _KumimojiTable_refresh = function _KumimojiTable_refresh() {
+    var _a;
+    __classPrivateFieldGet(this, _KumimojiTable_instances, "m", _KumimojiTable_frame).call(this);
+    try {
+        const language = oneOf(this.getAttribute("language"), ["english", "japanese"]) ?? __classPrivateFieldGet(this, _KumimojiTable_options, "f").language;
+        const hand = this.hasAttribute("hand") ? Number(this.getAttribute("hand")) : __classPrivateFieldGet(this, _KumimojiTable_options, "f").hand;
+        const level = oneOf(this.getAttribute("level"), ["easy", "medium", "hard"]) ?? __classPrivateFieldGet(this, _KumimojiTable_options, "f").level;
+        const gameLength = oneOf(this.getAttribute("length"), ["short", "medium", "full"]) ?? __classPrivateFieldGet(this, _KumimojiTable_options, "f").gameLength;
+        const diagonals = isOn(this.getAttribute("diagonals"), __classPrivateFieldGet(this, _KumimojiTable_options, "f").diagonals ?? false);
+        const seedAttribute = this.getAttribute("seed"), asked = Number(seedAttribute);
+        const day = embedDay(this.hasAttribute("daily") ? this.getAttribute("daily") : seedAttribute === "daily" ? "today" : null);
+        const seed = day !== null ? kumimojiDailySeed(new Date(`${day}T00:00:00Z`)) : seedAttribute !== null && Number.isInteger(asked) && asked >= 0 && asked <= 0xffffffff ? asked : __classPrivateFieldGet(this, _KumimojiTable_options, "f").seed ?? (__classPrivateFieldSet(this, _KumimojiTable_seed, __classPrivateFieldGet(this, _KumimojiTable_seed, "f") ?? Math.floor(Math.random() * 2 ** 31), "f"));
+        const lang = this.getAttribute("lang"), locale = lang === "en" || lang === "ja" ? lang : __classPrivateFieldGet(this, _KumimojiTable_options, "f").locale ?? (this.ownerDocument.documentElement.lang.toLowerCase().startsWith("ja") ? "ja" : "en");
+        const keep = isOn(this.getAttribute("keep"), __classPrivateFieldGet(this, _KumimojiTable_options, "f").keep ?? true), controls = isOn(this.getAttribute("controls"), __classPrivateFieldGet(this, _KumimojiTable_options, "f").controls ?? true);
+        const key = JSON.stringify([language, hand, level, gameLength, diagonals, seed, day, __classPrivateFieldGet(this, _KumimojiTable_options, "f").saved]);
+        if (key === __classPrivateFieldGet(this, _KumimojiTable_key, "f") && __classPrivateFieldGet(this, _KumimojiTable_table, "f") !== null) {
+            __classPrivateFieldGet(this, _KumimojiTable_table, "f").set({ locale, strings: __classPrivateFieldGet(this, _KumimojiTable_options, "f").strings, theme: __classPrivateFieldGet(this, _KumimojiTable_options, "f").theme ?? {}, keep, controls });
+            return;
+        }
+        if (hand !== undefined && !HANDS.includes(hand))
+            throw new RangeError("Choose a hand of 3, 7 or 11 tiles.");
+        __classPrivateFieldGet(this, _KumimojiTable_table, "f")?.destroy();
+        __classPrivateFieldSet(this, _KumimojiTable_table, null, "f");
+        __classPrivateFieldSet(this, _KumimojiTable_key, "", "f");
+        this.replaceChildren();
+        const revision = __classPrivateFieldSet(this, _KumimojiTable_revision, (_a = __classPrivateFieldGet(this, _KumimojiTable_revision, "f"), ++_a), "f");
+        const table = mountKumimoji(this, { ...__classPrivateFieldGet(this, _KumimojiTable_options, "f"), language, hand, level, gameLength, diagonals, seed, locale, keep, controls, onChange: saved => { this.dispatchEvent(new CustomEvent("kumimoji-change", { detail: JSON.parse(JSON.stringify({ saved })), bubbles: true, composed: true })); __classPrivateFieldGet(this, _KumimojiTable_options, "f").onChange?.(saved); }, onFinish: result => { this.dispatchEvent(new CustomEvent("kumimoji-finish", { detail: JSON.parse(JSON.stringify(result)), bubbles: true, composed: true })); __classPrivateFieldGet(this, _KumimojiTable_options, "f").onFinish?.(result); }, onError: error => { this.dispatchEvent(new CustomEvent("kumimoji-error", { detail: { message: error.message }, bubbles: true, composed: true })); __classPrivateFieldGet(this, _KumimojiTable_options, "f").onError?.(error); } });
+        __classPrivateFieldSet(this, _KumimojiTable_table, table, "f");
+        __classPrivateFieldSet(this, _KumimojiTable_key, key, "f");
+        void table.ready.then(() => { if (this.isConnected && revision === __classPrivateFieldGet(this, _KumimojiTable_revision, "f") && table.saved() !== null)
+            this.dispatchEvent(new CustomEvent("kumimoji-load", { bubbles: true, composed: true, detail: { seed: table.saved().deal.seed, day } })); }).catch(() => { });
+    }
+    catch (error) {
+        __classPrivateFieldGet(this, _KumimojiTable_table, "f")?.destroy();
+        __classPrivateFieldSet(this, _KumimojiTable_table, null, "f");
+        __classPrivateFieldSet(this, _KumimojiTable_key, "", "f");
+        const message = error instanceof Error ? error.message : String(error), status = this.ownerDocument.createElement("p");
+        status.setAttribute("role", "status");
+        status.textContent = message;
+        this.replaceChildren(status);
+        this.dispatchEvent(new CustomEvent("kumimoji-error", { detail: { message }, bubbles: true, composed: true }));
     }
-    __classPrivateFieldGet(this, _KumimojiTable_table, "f")?.destroy();
-    __classPrivateFieldSet(this, _KumimojiTable_table, null, "f");
-    __classPrivateFieldSet(this, _KumimojiTable_key, key, "f");
-    if (hand !== undefined && !HANDS.includes(hand))
-        return;
-    __classPrivateFieldSet(this, _KumimojiTable_table, mountKumimoji(this, {
-        language,
-        hand,
-        level,
-        gameLength,
-        diagonals,
-        seed,
-        locale,
-        keep,
-        onChange: (saved) => this.dispatchEvent(new CustomEvent("kumimoji-change", { detail: { saved }, bubbles: true })),
-        onFinish: (result) => this.dispatchEvent(new CustomEvent("kumimoji-finish", { detail: result, bubbles: true })),
-    }), "f");
 };
-KumimojiTable.observedAttributes = ["language", "hand", "level", "length", "diagonals", "seed", "lang", "keep"];
+KumimojiTable.observedAttributes = ["language", "hand", "level", "length", "diagonals", "seed", "lang", "keep", "daily", "controls", "theme", "size", "width", "label"];
+/**
+ * Defines the table or a subclass under a custom tag. Server-safe and idempotent.
+ * @param tagName - The tag name; kumimoji-table by default.
+ * @param registry - The page registry, or undefined on a server.
+ * @returns Nothing; existing definitions are left alone.
+ * @example
+ * ```ts
+ * import { defineTable } from "@johnmorrisdotca/kumimoji/element";
+ * defineTable();
+ * console.log(typeof defineTable);
+ * ```
+ */
+export function defineTable(tagName = "kumimoji-table", registry = typeof customElements === "undefined" ? undefined : customElements) { if (registry !== undefined && registry.get(tagName) === undefined)
+    registry.define(tagName, tagName === "kumimoji-table" ? KumimojiTable : class extends KumimojiTable {
+    }); }

package/dist/embed-day.d.ts

@@ -0,0 +1,4 @@
+/** Shared UTC day parsing for the family's daily embeds. No storage, service or rollover timer. */
+export declare function embedDay(value: string | null | undefined, now?: Date): string | null;
+/** The same day and namespace give the same nonzero 32-bit seed on every machine. */
+export declare function dailySeed(day: string, namespace: string): number;

package/dist/embed-day.js

@@ -0,0 +1,23 @@
+/** Shared UTC day parsing for the family's daily embeds. No storage, service or rollover timer. */
+export function embedDay(value, now = new Date()) {
+    if (value === null || value === undefined || ["off", "false", "no", "0"].includes(value.trim().toLowerCase()))
+        return null;
+    const asked = value.trim().toLowerCase();
+    const day = ["", "today", "on", "true", "1"].includes(asked) ? Number.isNaN(now.getTime()) ? "" : now.toISOString().slice(0, 10) : value.trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(day))
+        throw new RangeError("Use a real UTC date written YYYY-MM-DD.");
+    const time = Date.parse(`${day}T00:00:00Z`);
+    if (!Number.isFinite(time) || new Date(time).toISOString().slice(0, 10) !== day)
+        throw new RangeError("Use a real UTC date written YYYY-MM-DD.");
+    return day;
+}
+/** The same day and namespace give the same nonzero 32-bit seed on every machine. */
+export function dailySeed(day, namespace) {
+    const parsed = embedDay(day);
+    if (parsed === null)
+        throw new RangeError("A daily seed needs a UTC date.");
+    let hash = 2166136261;
+    for (const letter of `${parsed}/${namespace}`)
+        hash = Math.imul(hash ^ letter.charCodeAt(0), 16777619) >>> 0;
+    return hash || 1;
+}

package/dist/export.d.ts

@@ -14,9 +14,31 @@ import { type KumimojiStrings } from "./strings.ts";
  * the game only if every tile in the hand and on the table is one that came
  * out of that bag and was not given back.
  */
-/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one. */
+/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_EXPORT_FORMAT } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_EXPORT_FORMAT);
+ * ```
+ */
 export declare const KUMIMOJI_EXPORT_FORMAT = 1;
-/** A game alone as it is kept: the deal, where the player has got to, and the time spent so far. */
+/** A game alone as it is kept: the deal, where the player has got to, and the time spent so far.
+ *
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import type { KumimojiSaved } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * const value: KumimojiSaved = saved;
+ * console.log(value);
+ * ```
+ */
 export type KumimojiSaved = {
     /** The game as dealt: `generateKumimoji`'s. */
     deal: KumimojiDeal;
@@ -25,7 +47,22 @@ export type KumimojiSaved = {
     /** Milliseconds spent on it so far. */
     elapsedMs: number;
 };
-/** A whole JSON export of one game: what `kumimojiToJSON` writes and `kumimojiFromJSON` reads. */
+/** A whole JSON export of one game: what `kumimojiToJSON` writes and `kumimojiFromJSON` reads.
+ *
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import type { KumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * const value: KumimojiExported = kumimojiExported(saved);
+ * console.log(value);
+ * ```
+ */
 export type KumimojiExported = {
     /** The shape's number: `KUMIMOJI_EXPORT_FORMAT`. */
     format: typeof KUMIMOJI_EXPORT_FORMAT;
@@ -52,9 +89,39 @@ export type KumimojiExported = {
     /** Milliseconds spent so far. */
     elapsedMs: number;
 };
-/** A game as the JSON export's object. */
+/** A game as the JSON export's object.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as the JSON export's object.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiExported(saved).format);
+ * ```
+ */
 export declare function kumimojiExported(saved: KumimojiSaved): KumimojiExported;
-/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back. */
+/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToJSON(saved));
+ * ```
+ */
 export declare function kumimojiToJSON(saved: KumimojiSaved): string;
 /**
  * A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the
@@ -66,15 +133,50 @@ export declare function kumimojiToJSON(saved: KumimojiSaved): string;
  * The word list of the game's language is loaded first, since dealing needs
  * it; where there is no browser, import `@johnmorrisdotca/kumimoji/words`
  * once, or the promise is rejected as `loadTileWords` rejects it.
+ *
+ * @param text - The saved JSON text to validate.
+ * @returns A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the bag is dealt again from the seed, and the game opens only if every tile held is one that came out of that bag. Resolves to null when the text is not JSON, is of a later format than this version reads, is another game's, or holds a hand or a grid that this bag never dealt.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiFromJSON, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log((await kumimojiFromJSON(kumimojiToJSON(saved)))?.deal.seed);
+ * ```
  */
 export declare function kumimojiFromJSON(text: string): Promise<KumimojiSaved | null>;
-/** A time as minutes and seconds: `1:05`. */
+/** A time as minutes and seconds: `1:05`.
+ *
+ * @param ms - The duration in milliseconds.
+ * @returns A time as minutes and seconds: `1:05`.
+ * @example
+ * ```ts
+ * import { kumimojiClock } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiClock(65000));
+ * ```
+ */
 export declare function kumimojiClock(ms: number): string;
 /**
  * A grid as lines of text, the way it lies on the table: English letters in
  * capitals with a space between squares and a dot for an empty one, kana side
  * by side with a full-width dot for an empty one, so that either lines up in a
  * fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param language - The English or Japanese tile language.
+ * @returns A grid as lines of text, the way it lies on the table: English letters in capitals with a space between squares and a dot for an empty one, kana side by side with a full-width dot for an empty one, so that either lines up in a fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ * @example
+ * ```ts
+ * import { gridToText } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(gridToText(tiles));
+ * ```
  */
 export declare function gridToText(tiles: Tiles, language?: KumimojiLanguage): string;
 /**
@@ -83,5 +185,20 @@ export declare function gridToText(tiles: Tiles, language?: KumimojiLanguage): s
  * English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The
  * word list of the game's language must have been loaded, as for any judging.
  * Lines end with a line feed.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @param strings - The localized words for readable export.
+ * @returns A game as plain text, for a chat or a note: how it was set up, the crossword as it lies, the hand, how many tiles are left, and the time. In English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The word list of the game's language must have been loaded, as for any judging. Lines end with a line feed.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToText } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToText(saved));
+ * ```
  */
 export declare function kumimojiToText(saved: KumimojiSaved, strings?: KumimojiStrings): string;

package/dist/export.js

@@ -19,9 +19,31 @@ import { KUMIMOJI_VERSION } from "./version.js";
  * the game only if every tile in the hand and on the table is one that came
  * out of that bag and was not given back.
  */
-/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one. */
+/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_EXPORT_FORMAT } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_EXPORT_FORMAT);
+ * ```
+ */
 export const KUMIMOJI_EXPORT_FORMAT = 1;
-/** A game as the JSON export's object. */
+/** A game as the JSON export's object.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as the JSON export's object.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiExported } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiExported(saved).format);
+ * ```
+ */
 export function kumimojiExported(saved) {
     const { deal, play } = saved;
     return {
@@ -39,7 +61,22 @@ export function kumimojiExported(saved) {
         elapsedMs: Math.max(0, Math.round(saved.elapsedMs)),
     };
 }
-/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back. */
+/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @returns A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToJSON(saved));
+ * ```
+ */
 export function kumimojiToJSON(saved) {
     return `${JSON.stringify(kumimojiExported(saved), null, 2)}\n`;
 }
@@ -57,6 +94,20 @@ const PROGRESS_MOST = 4000;
  * The word list of the game's language is loaded first, since dealing needs
  * it; where there is no browser, import `@johnmorrisdotca/kumimoji/words`
  * once, or the promise is rejected as `loadTileWords` rejects it.
+ *
+ * @param text - The saved JSON text to validate.
+ * @returns A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the bag is dealt again from the seed, and the game opens only if every tile held is one that came out of that bag. Resolves to null when the text is not JSON, is of a later format than this version reads, is another game's, or holds a hand or a grid that this bag never dealt.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiFromJSON, kumimojiToJSON } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log((await kumimojiFromJSON(kumimojiToJSON(saved)))?.deal.seed);
+ * ```
  */
 export async function kumimojiFromJSON(text) {
     let data;
@@ -102,7 +153,17 @@ export async function kumimojiFromJSON(text) {
     const play = decodeTileProgress(progress, deal.givens, language);
     return play === null ? null : { deal, play, elapsedMs: spent };
 }
-/** A time as minutes and seconds: `1:05`. */
+/** A time as minutes and seconds: `1:05`.
+ *
+ * @param ms - The duration in milliseconds.
+ * @returns A time as minutes and seconds: `1:05`.
+ * @example
+ * ```ts
+ * import { kumimojiClock } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiClock(65000));
+ * ```
+ */
 export function kumimojiClock(ms) {
     const seconds = Math.max(0, Math.floor(ms / 1000));
     return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
@@ -112,6 +173,17 @@ export function kumimojiClock(ms) {
  * capitals with a space between squares and a dot for an empty one, kana side
  * by side with a full-width dot for an empty one, so that either lines up in a
  * fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param language - The English or Japanese tile language.
+ * @returns A grid as lines of text, the way it lies on the table: English letters in capitals with a space between squares and a dot for an empty one, kana side by side with a full-width dot for an empty one, so that either lines up in a fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ * @example
+ * ```ts
+ * import { gridToText } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(gridToText(tiles));
+ * ```
  */
 export function gridToText(tiles, language = "english") {
     const bounds = boundsOf(tiles);
@@ -140,6 +212,21 @@ export function gridToText(tiles, language = "english") {
  * English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The
  * word list of the game's language must have been loaded, as for any judging.
  * Lines end with a line feed.
+ *
+ * @param saved - The original deal, current progress and elapsed time.
+ * @param strings - The localized words for readable export.
+ * @returns A game as plain text, for a chat or a note: how it was set up, the crossword as it lies, the hand, how many tiles are left, and the time. In English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The word list of the game's language must have been loaded, as for any judging. Lines end with a line feed.
+ * @example
+ * ```ts
+ * import { deal, generateKumimoji, kumimojiToText } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const saved = {deal:dealt,play:deal(dealt.givens,dealt.size),elapsedMs:0};
+ * console.log(kumimojiToText(saved));
+ * ```
  */
 export function kumimojiToText(saved, strings = KUMIMOJI_STRINGS.en) {
     const { deal, play } = saved;

package/dist/generate.d.ts

@@ -25,5 +25,19 @@ import type { KumimojiDeal, KumimojiLevel, KumimojiOptions } from "./kumimoji.ty
  *
  * Deterministic in the seed, like every generator here: two browsers in a
  * race, or one tomorrow, deal the same bag in the same order.
+ *
+ * @param size - The supported initial hand size.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param seed - The numeric seed for deterministic deals or random draws.
+ * @param options - Native game, component or presentation options.
+ * @returns MAKING A KUMIMOJI, in the browser, from a seed: the bag the game is played from, in the order its tiles come out.
+ * @example
+ * ```ts
+ * import { generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(generateKumimoji(3,"hard",44).givens);
+ * ```
  */
 export declare function generateKumimoji(size: number, level: KumimojiLevel, seed: number, options?: KumimojiOptions): KumimojiDeal;