@johnmorrisdotca/kazu 1.0.0

package/dist/mount.js

@@ -0,0 +1,558 @@
+import { decodeCells, stepEntry, symbolOf, valueOfSymbol } from "./cells.js";
+import { kazuClockText } from "./clock.js";
+import { drawKazu, kazuCellName, kazuWhere } from "./draw.js";
+import { answerOf, clearCell, enterNumber, gameConflicts, isPrinted, isSolved, kazuProgress, newKazuGame, numberCounts, restartKazu, toggleNote, undoKazu, valuesOf } from "./game.js";
+import { hintKazu } from "./hint.js";
+import { KAZU_PLAY_STYLE } from "./playStyle.js";
+import { decodeNotes, decodeRun, encodeNotes, encodeRun, notesOf } from "./progress.js";
+import { solveKazu } from "./solve.js";
+import { kazuLanguageOf, kazuNameOf, kazuSay } from "./strings.js";
+/** Put the style in the page once: in the document's head, or in the shadow root the host is in. */
+export function ensureKazuPlayStyle(host) {
+    const root = host.getRootNode();
+    const target = typeof ShadowRoot !== "undefined" && root instanceof ShadowRoot ? root : host.ownerDocument.head;
+    if (target.querySelector("style[data-kazu-play]") !== null)
+        return;
+    const style = host.ownerDocument.createElement("style");
+    style.setAttribute("data-kazu-play", "");
+    style.textContent = KAZU_PLAY_STYLE;
+    target.append(style);
+}
+function create(document, tag, className, text) {
+    const element = document.createElement(tag);
+    element.className = className;
+    if (text !== undefined)
+        element.textContent = text;
+    return element;
+}
+const ARROWS = { ArrowUp: [-1, 0], ArrowDown: [1, 0], ArrowLeft: [0, -1], ArrowRight: [0, 1] };
+/** Draw a puzzle into `host` and play it. Returns the handle that drives it, or null for givens that are not a puzzle of that kind and side. */
+export function mountKazu(host, options) {
+    const document = host.ownerDocument;
+    const view = document.defaultView;
+    const firstGame = start(options);
+    if (firstGame === null)
+        return null;
+    ensureKazuPlayStyle(host);
+    let game = firstGame;
+    let level = options.level;
+    let seed = options.seed;
+    let solution = options.solution ?? null;
+    let settings = {
+        hints: options.hints ?? "place",
+        check: options.check ?? "count",
+        conflicts: options.conflicts !== false,
+        peers: options.peers !== false,
+        tidy: options.tidy !== false,
+        tapToStep: options.tapToStep !== false,
+        clock: options.clock !== false,
+        controls: options.controls !== false,
+    };
+    const explicitLanguage = { value: options.language };
+    const callbacks = options;
+    let selected = null;
+    let pencilOn = false;
+    let hintCell = null;
+    let wrongCells = [];
+    let says = { key: "tap" };
+    let hints = 0;
+    let checks = 0;
+    let solved = isSolved(game);
+    let banked = options.elapsed ?? 0;
+    let ranSince = null;
+    let tick = null;
+    let language = explicitLanguage.value ?? languageOfPage();
+    let drawn = "";
+    let announced = "";
+    function languageOfPage() {
+        return kazuLanguageOf(host.closest("[lang]")?.getAttribute("lang") ?? document.documentElement.lang);
+    }
+    // The parts.
+    host.classList.add("kazu-play");
+    host.replaceChildren();
+    const bar = create(document, "div", "kzp-bar");
+    const clockEl = create(document, "span", "kzp-clock");
+    clockEl.setAttribute("role", "timer");
+    const progressEl = create(document, "span", "kzp-progress");
+    bar.append(clockEl, progressEl);
+    const box = create(document, "div", "kzp-box");
+    box.tabIndex = 0;
+    box.setAttribute("role", "application");
+    const inner = create(document, "div", "kzp-inner");
+    box.append(inner);
+    const keysNote = create(document, "p", "kzp-sr");
+    box.setAttribute("aria-describedby", `kzp-keys-${Math.random().toString(36).slice(2, 8)}`);
+    keysNote.id = box.getAttribute("aria-describedby");
+    const announce = create(document, "p", "kzp-sr");
+    announce.setAttribute("aria-live", "polite");
+    const pad = create(document, "div", "kzp-pad");
+    pad.setAttribute("role", "group");
+    const controls = create(document, "div", "kzp-controls");
+    const saysEl = create(document, "p", "kzp-says");
+    saysEl.setAttribute("aria-live", "polite");
+    host.append(bar, box, keysNote, announce, pad, controls, saysEl);
+    const button = (name, onPress, parent, className = "kzp-button") => {
+        const one = create(document, "button", className);
+        one.type = "button";
+        one.dataset.action = name;
+        one.addEventListener("click", onPress);
+        parent.append(one);
+        return one;
+    };
+    const undoButton = button("undo", () => api.undo(), controls);
+    const pencilButton = button("pencil", () => api.pencil(), controls);
+    const hintButton = button("hint", () => api.hint(), controls);
+    const checkButton = button("check", () => api.check(), controls);
+    let padKeys = [];
+    let eraseKey = null;
+    const say = (key, values = {}) => kazuSay(language, key, values);
+    function elapsed() {
+        return banked + (ranSince === null ? 0 : view.performance.now() - ranSince);
+    }
+    function runClock() {
+        if (ranSince !== null || solved || document.hidden)
+            return;
+        ranSince = view.performance.now();
+        if (tick === null)
+            tick = setInterval(paintClock, 1000);
+    }
+    function stopClock() {
+        if (ranSince !== null)
+            banked += view.performance.now() - ranSince;
+        ranSince = null;
+        if (tick !== null)
+            clearInterval(tick);
+        tick = null;
+    }
+    function paintClock() {
+        const text = kazuClockText(elapsed());
+        if (clockEl.textContent !== text)
+            clockEl.textContent = text;
+    }
+    // The pad: a key for every number, and one to erase. Its columns are fixed for a puzzle's side.
+    function buildPad() {
+        pad.replaceChildren();
+        padKeys = [];
+        for (let value = 1; value <= game.size; value += 1) {
+            const key = button(`number-${value}`, () => api.enter(value), pad, "kzp-key");
+            key.dataset.value = String(value);
+            key.textContent = symbolOf(value);
+            padKeys.push(key);
+        }
+        eraseKey = button("erase", () => api.enter(0), pad, "kzp-key");
+        eraseKey.dataset.erase = "true";
+        eraseKey.textContent = "×";
+        const rows = game.size <= 6 ? 1 : game.size <= 9 ? 2 : 3;
+        pad.style.setProperty("--kzp-columns", String(Math.ceil((game.size + 1) / rows)));
+    }
+    function detail() {
+        return {
+            kind: game.kind,
+            size: game.size,
+            level,
+            seed,
+            run: encodeRun(game.entries),
+            notes: encodeNotes(game.notes),
+            answer: answerOf(game),
+            progress: kazuProgress(game),
+            elapsedMs: Math.round(elapsed()),
+            hints,
+            checks,
+            helped: hints > 0,
+            solved,
+        };
+    }
+    function emit(name, extra = {}) {
+        const info = { ...detail(), ...extra };
+        host.dispatchEvent(new CustomEvent(name, { detail: info, bubbles: true }));
+        const call = { "kazu-change": callbacks.onChange, "kazu-hint": callbacks.onHint, "kazu-check": callbacks.onCheck, "kazu-solve": callbacks.onSolve }[name];
+        call?.(info);
+    }
+    function answerKey() {
+        if (solution === null)
+            solution = solveKazu(game.kind, game.size, game.givens);
+        return solution;
+    }
+    function sayText() {
+        return says.text ?? kazuSay(language, says.key, says.values ?? {});
+    }
+    function cellDescription(index) {
+        const cell = kazuCellName(game.size, index, language);
+        const shown = valuesOf(game)[index];
+        if (isPrinted(game, index))
+            return say("cellGiven", { cell, value: symbolOf(shown) });
+        if (shown !== 0)
+            return say(gameConflicts(game).includes(index) ? "cellConflict" : "cellValue", { cell, value: symbolOf(shown) });
+        const notes = notesOf(game.notes[index]);
+        return notes.length > 0 ? say("cellNotes", { cell, notes: notes.map(symbolOf).join(", ") }) : say("cellEmpty", { cell });
+    }
+    function render() {
+        const conflicts = settings.conflicts ? gameConflicts(game) : [];
+        const svg = drawKazu(game.kind, game.size, game.givens, {
+            entries: game.entries,
+            notes: game.notes,
+            selected,
+            peers: settings.peers,
+            conflicts,
+            wrong: wrongCells,
+            hint: hintCell,
+            done: solved,
+            interactive: !solved,
+            language,
+        });
+        if (svg !== null && svg !== drawn) {
+            inner.innerHTML = svg;
+            drawn = svg;
+        }
+        box.dataset.over = String(solved);
+        host.dataset.solved = String(solved);
+        host.dataset.pencil = String(pencilOn);
+        host.dataset.kind = game.kind;
+        host.dataset.size = String(game.size);
+        box.setAttribute("aria-label", say("board", { name: kazuNameOf(game.kind, language), size: game.size }));
+        keysNote.textContent = say("keys");
+        const counts = numberCounts(game);
+        padKeys.forEach((key, at) => {
+            const value = at + 1;
+            key.disabled = solved;
+            key.dataset.done = String(counts[value] >= game.size);
+            key.setAttribute("aria-label", say(counts[value] >= game.size ? "padDone" : "padNumber", { n: symbolOf(value) }));
+        });
+        if (eraseKey !== null) {
+            eraseKey.disabled = solved;
+            eraseKey.setAttribute("aria-label", say("erase"));
+        }
+        pad.setAttribute("aria-label", say("pad"));
+        undoButton.textContent = say("undo");
+        undoButton.disabled = game.past.length === 0 || solved;
+        pencilButton.textContent = say("pencil");
+        pencilButton.title = say("pencilTitle");
+        pencilButton.setAttribute("aria-pressed", String(pencilOn));
+        pencilButton.disabled = solved;
+        hintButton.textContent = say("hint");
+        hintButton.title = say("hintTitle");
+        hintButton.hidden = settings.hints === "off";
+        hintButton.disabled = solved;
+        checkButton.textContent = say("check");
+        checkButton.title = say("checkTitle");
+        checkButton.hidden = settings.check === "off";
+        checkButton.disabled = solved;
+        controls.hidden = !settings.controls;
+        pad.hidden = !settings.controls;
+        clockEl.hidden = !settings.clock;
+        clockEl.setAttribute("aria-label", say("clock"));
+        const progress = kazuProgress(game);
+        progressEl.textContent = `${progress.filled} / ${progress.total}`;
+        paintClock();
+        const text = solved ? say(banked > 0 || ranSince !== null ? "solvedIn" : "solved", { time: kazuClockText(elapsed()) }) : sayText();
+        saysEl.textContent = text;
+        saysEl.dataset.warn = String(says.warn === true && !solved);
+        const note = selected === null ? "" : cellDescription(selected);
+        if (note !== announced) {
+            announced = note;
+            announce.textContent = note;
+        }
+    }
+    function setSays(key, values, warn = false, text) {
+        says = { key, values, warn, text };
+    }
+    function tapWords() {
+        setSays(pencilOn ? "tapPencil" : "tap");
+    }
+    function changed() {
+        hintCell = null;
+        wrongCells = [];
+        solved = isSolved(game);
+        if (solved) {
+            stopClock();
+            setSays("solved");
+        }
+        else if (kazuProgress(game).filled === game.size * game.size)
+            setSays("full", undefined, true);
+        else
+            tapWords();
+        render();
+        emit("kazu-change");
+        if (solved)
+            emit("kazu-solve");
+    }
+    function write(cell, value) {
+        if (solved || cell < 0 || isPrinted(game, cell))
+            return;
+        const next = pencilOn && value !== 0 ? toggleNote(game, cell, value) : value === 0 ? clearCell(game, cell) : enterNumber(game, cell, value, settings.tidy);
+        if (next === game)
+            return;
+        runClock();
+        game = next;
+        changed();
+    }
+    function move(by) {
+        const { size } = game;
+        const from = selected ?? 0;
+        const row = Math.min(size - 1, Math.max(0, Math.floor(from / size) + by[0]));
+        const col = Math.min(size - 1, Math.max(0, (from % size) + by[1]));
+        api.select(row * size + col);
+    }
+    const onClick = (event) => {
+        const target = event.target?.closest("[data-cell]");
+        if (target === null || target === undefined || solved)
+            return;
+        const index = Number(target.dataset.cell);
+        if (!Number.isInteger(index))
+            return;
+        if (index === selected && settings.tapToStep && !pencilOn && !isPrinted(game, index))
+            write(index, stepEntry(game.entries[index], game.size));
+        else
+            api.select(index);
+    };
+    const onKey = (event) => {
+        if (event.metaKey || event.ctrlKey || event.altKey) {
+            if ((event.metaKey || event.ctrlKey) && !event.altKey && event.key.toLowerCase() === "z") {
+                event.preventDefault();
+                api.undo();
+            }
+            return;
+        }
+        if (event.key in ARROWS) {
+            event.preventDefault();
+            move(ARROWS[event.key]);
+            return;
+        }
+        if (solved)
+            return;
+        if (event.key === "Escape") {
+            event.preventDefault();
+            api.select(null);
+        }
+        else if (event.key === "Backspace" || event.key === "Delete" || event.key === "0" || event.key === " ") {
+            event.preventDefault();
+            api.enter(0);
+        }
+        else if (event.key.toLowerCase() === "n") {
+            event.preventDefault();
+            api.pencil();
+        }
+        else if (event.shiftKey && selected !== null) {
+            // Shift with a number is a pencil mark, whatever the keyboard writes for a shifted digit: read the key's place, not its symbol.
+            const code = /^Digit([1-9])$/.exec(event.code)?.[1] ?? /^Key([A-G])$/.exec(event.code)?.[1];
+            const value = code === undefined ? 0 : valueOfSymbol(code);
+            if (value >= 1 && value <= game.size) {
+                event.preventDefault();
+                write(selected, 0);
+                const next = toggleNote(game, selected, value);
+                if (next !== game) {
+                    runClock();
+                    game = next;
+                    changed();
+                }
+            }
+        }
+        else {
+            const value = valueOfSymbol(event.key);
+            if (value >= 1 && value <= game.size) {
+                event.preventDefault();
+                api.enter(value);
+            }
+        }
+    };
+    const onFocus = () => {
+        if (selected === null && !solved)
+            api.select(0);
+    };
+    const onVisible = () => {
+        if (document.hidden) {
+            if (ranSince !== null) {
+                stopClock();
+                paintClock();
+                resumeOnShow = true;
+            }
+        }
+        else if (resumeOnShow) {
+            resumeOnShow = false;
+            runClock();
+        }
+    };
+    let resumeOnShow = false;
+    box.addEventListener("click", onClick);
+    box.addEventListener("keydown", onKey);
+    box.addEventListener("focus", onFocus);
+    document.addEventListener("visibilitychange", onVisible);
+    const watching = typeof MutationObserver === "undefined"
+        ? null
+        : new MutationObserver(() => {
+            if (explicitLanguage.value !== undefined)
+                return;
+            const next = languageOfPage();
+            if (next === language)
+                return;
+            language = next;
+            drawn = "";
+            render();
+        });
+    watching?.observe(document.documentElement, { attributes: true, attributeFilter: ["lang"] });
+    buildPad();
+    render();
+    const api = {
+        host,
+        game: () => game,
+        detail,
+        load: (puzzle) => {
+            const next = start(puzzle);
+            if (next === null)
+                return false;
+            stopClock();
+            game = next;
+            solution = puzzle.solution ?? null;
+            level = puzzle.level;
+            seed = puzzle.seed;
+            banked = puzzle.elapsed ?? 0;
+            selected = null;
+            pencilOn = false;
+            hints = 0;
+            checks = 0;
+            hintCell = null;
+            wrongCells = [];
+            solved = isSolved(game);
+            drawn = "";
+            setSays("tap");
+            buildPad();
+            render();
+            return true;
+        },
+        set: (changes) => {
+            const { language: nextLanguage, ...rest } = changes;
+            settings = { ...settings, ...Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined)) };
+            if ("language" in changes) {
+                explicitLanguage.value = nextLanguage;
+                language = nextLanguage ?? languageOfPage();
+            }
+            drawn = "";
+            render();
+        },
+        select: (cell) => {
+            selected = cell !== null && cell >= 0 && cell < game.size * game.size ? cell : null;
+            if (hintCell !== null && hintCell !== selected)
+                hintCell = null;
+            render();
+        },
+        enter: (value) => {
+            if (selected !== null)
+                write(selected, value);
+        },
+        pencil: (on) => {
+            pencilOn = on ?? !pencilOn;
+            if (!solved)
+                tapWords();
+            render();
+        },
+        undo: () => {
+            const next = undoKazu(game);
+            if (next === game || solved)
+                return;
+            game = next;
+            changed();
+        },
+        hint: () => {
+            if (solved || settings.hints === "off")
+                return;
+            const found = hintKazu(game.kind, game.size, game.givens, game.entries, answerKey() ?? undefined);
+            if (found === null) {
+                setSays("hintDone");
+                render();
+                return;
+            }
+            hints += 1;
+            selected = found.cell;
+            const words = hintWords(found);
+            if (settings.hints === "place") {
+                runClock();
+                game = enterNumber(game, found.cell, found.value, settings.tidy);
+                changed();
+                if (!solved)
+                    setSays("", undefined, false, words);
+                hintCell = found.cell;
+                render();
+            }
+            else {
+                hintCell = found.cell;
+                wrongCells = [];
+                setSays("", undefined, false, words);
+                render();
+            }
+            emit("kazu-hint", { hint: found });
+        },
+        check: () => {
+            if (solved || settings.check === "off")
+                return;
+            checks += 1;
+            const answer = decodeCells(answerKey() ?? "", game.size);
+            const wrong = [];
+            const empty = game.entries.filter((value, index) => !isPrinted(game, index) && value === 0).length;
+            if (answer !== null)
+                game.entries.forEach((value, index) => (!isPrinted(game, index) && value !== 0 && value !== answer[index] ? wrong.push(index) : undefined));
+            else
+                wrong.push(...gameConflicts(game).filter((index) => !isPrinted(game, index)));
+            wrongCells = settings.check === "show" ? wrong : [];
+            hintCell = null;
+            if (wrong.length === 0 && empty === 0)
+                setSays("checkRight");
+            else if (wrong.length === 0)
+                setSays("checkOnlyEmpty", { empty });
+            else if (empty === 0)
+                setSays("checkWrongNoneEmpty", { wrong: wrong.length }, true);
+            else
+                setSays("checkWrong", { wrong: wrong.length, empty }, true);
+            render();
+            emit("kazu-check");
+        },
+        restart: () => {
+            stopClock();
+            game = restartKazu(game);
+            banked = 0;
+            hints = 0;
+            checks = 0;
+            selected = null;
+            hintCell = null;
+            wrongCells = [];
+            solved = isSolved(game);
+            setSays("tap");
+            render();
+            emit("kazu-change");
+        },
+        destroy: () => {
+            stopClock();
+            box.removeEventListener("click", onClick);
+            box.removeEventListener("keydown", onKey);
+            box.removeEventListener("focus", onFocus);
+            document.removeEventListener("visibilitychange", onVisible);
+            watching?.disconnect();
+            host.replaceChildren();
+            host.classList.remove("kazu-play");
+            for (const name of ["solved", "pencil", "kind", "size"])
+                delete host.dataset[name];
+        },
+    };
+    /** The line a hint says, in the board's language. */
+    function hintWords(found) {
+        const cell = kazuCellName(game.size, found.cell, language);
+        const value = symbolOf(found.value);
+        const lead = found.replaces ? say("hintReplaces", { cell }) : "";
+        if (found.why === "answer")
+            return lead + say("hintAnswer", { cell, value });
+        if (found.why === "only-number") {
+            const where = kazuWhere(game.kind, language);
+            return lead + (found.by === undefined ? say("hintOnly", { cell, value, where }) : say("hintOnlyBy", { cell, value, where, by: say(found.by === "cage" ? "byCage" : found.by === "marks" ? "byMarks" : "byClues") }));
+        }
+        const group = found.group;
+        const diagonal = group.type === "diagonal" ? say(group.index === 0 ? "groupDiagonal" : "groupDiagonalOther") : "";
+        const named = group.type === "diagonal" ? diagonal : say(`group${group.type[0].toUpperCase()}${group.type.slice(1)}`, { n: group.index + 1 });
+        return lead + say("hintPlace", { group: named, value, cell });
+    }
+    return api;
+}
+/** The game a set of options starts from, or null for givens that are not a puzzle. */
+function start(options) {
+    const entries = options.run === undefined ? undefined : (decodeRun(options.run, options.size) ?? undefined);
+    const notes = options.notes === undefined ? undefined : (decodeNotes(options.notes, options.size) ?? undefined);
+    return newKazuGame(options.kind, options.size, options.givens, { entries, notes });
+}

package/dist/names.d.ts

@@ -0,0 +1,41 @@
+import type { KazuKind } from "./kinds.ts";
+/**
+ * WHAT EACH PUZZLE IS CALLED, and what it is, in English and Japanese: the name a player searches for,
+ * its Japanese name, a line saying how it is played, and a few lines of rules. Plain data, for a page
+ * that lists the puzzles (a chooser, a rules page); `strings.ts` has the words a playable board says.
+ *
+ * The English names are the ones players search for: Sudoku, Killer Sudoku, Futoshiki, Skyscrapers.
+ * 数独 is Nikoli's mark in Japan, so Sudoku's Japanese name here is ナンプレ (Number Place, the puzzle's
+ * own original name, and the word Japanese publishers use); the others keep names of their own. The
+ * keys the package uses are `number-place`, `sum-cages`, `more-or-less`, `towers`: what each one is, not
+ * somebody's trademark.
+ */
+export type KazuName = {
+    /** The name players search for. */
+    en: string;
+    /** The Japanese name. */
+    ja: string;
+    /** Other names the same puzzle goes by. */
+    alsoKnownAs: readonly string[];
+    /** How it is played, in a line. */
+    tagline: {
+        en: string;
+        ja: string;
+    };
+    /** The rules, a few lines each. */
+    rules: {
+        en: readonly string[];
+        ja: readonly string[];
+    };
+    /** Where it comes from, in a sentence. */
+    origin: {
+        en: string;
+        ja: string;
+    };
+};
+export declare const KAZU_NAMES: Record<KazuKind, KazuName>;
+/** What each side is for, under its size on a chooser: the quick one, the usual one, the long one. */
+export declare const KAZU_SIZE_NAMES: Record<KazuKind, Record<number, {
+    en: string;
+    ja: string;
+}>>;