@altnovatrail/canvas 0.0.0-stage → 0.1.0

package/lib/element/statement.d.ts

@@ -0,0 +1,35 @@
+import type { PicturePart, StatementPart } from "../core/task.js";
+import type { Pictures } from "./pictures.js";
+/** The statement of a task above the sheet, as the element shows it. */
+export declare class Statement {
+    #private;
+    /**
+     * The statement's element: the paragraphs and the pictures, in the module's explanation language,
+     * or in the element's own without a manifest (R32).
+     */
+    readonly element: HTMLDivElement;
+    /** A statement whose pictures the element's pictures give their files. */
+    constructor(pictures: Pictures);
+    /**
+     * The language the statement is in, a BCP 47 tag, or `undefined` for the element's own, which
+     * the statement inherits. A new language changes the attribute alone: the paragraphs and the
+     * pictures stay as they are.
+     */
+    set lang(lang: string | undefined);
+    /**
+     * The statement of a task, in place of the last, whose pictures are taken off. A picture whose
+     * file has come shows it at once: the element names the new statement's pictures first.
+     */
+    show(statement: readonly StatementPart[]): void;
+}
+/** A picture beside the sheet in its frame, and what takes it off when the frame leaves. */
+export interface Framed {
+    readonly frame: HTMLElement;
+    readonly off: () => void;
+}
+/**
+ * A picture beside the sheet in a frame of its size, placed with the element's pictures: a
+ * statement's, and a worked example's in its list of parts (R42). The frame shows the picture once
+ * its file has come and is decoded, and what it shows in words till then, or if it never does.
+ */
+export declare function framed(pictures: Pictures, part: PicturePart): Framed;

package/lib/element/statement.js

@@ -0,0 +1,116 @@
+// The statement of a task, above the sheet, in the element's own scrolling (R23): its paragraphs
+// as text and its pictures from the consumer's media, which the element's pictures load (R42).
+// Each picture keeps a frame of its own size, so that nothing moves under the pen when it comes,
+// and the frame shows what the picture shows in words until it comes, or if it never does. This
+// module is no entry point of the package.
+/** The statement of a task above the sheet, as the element shows it. */
+export class Statement {
+    /**
+     * The statement's element: the paragraphs and the pictures, in the module's explanation language,
+     * or in the element's own without a manifest (R32).
+     */
+    element = document.createElement("div");
+    #pictures;
+    /** What takes the statement's pictures off, once another statement takes its place. */
+    #off = [];
+    /** A statement whose pictures the element's pictures give their files. */
+    constructor(pictures) {
+        this.#pictures = pictures;
+        this.element.className = "statement";
+    }
+    /**
+     * The language the statement is in, a BCP 47 tag, or `undefined` for the element's own, which
+     * the statement inherits. A new language changes the attribute alone: the paragraphs and the
+     * pictures stay as they are.
+     */
+    set lang(lang) {
+        if (lang === undefined)
+            this.element.removeAttribute("lang");
+        else
+            this.element.lang = lang;
+    }
+    /**
+     * The statement of a task, in place of the last, whose pictures are taken off. A picture whose
+     * file has come shows it at once: the element names the new statement's pictures first.
+     */
+    show(statement) {
+        for (const off of this.#off)
+            off();
+        const off = [];
+        const parts = statement.map((part) => {
+            if ("text" in part) {
+                const paragraph = document.createElement("p");
+                // Text, never markup: a module is data (R02 spec).
+                paragraph.textContent = part.text;
+                return paragraph;
+            }
+            const picture = framed(this.#pictures, part);
+            off.push(picture.off);
+            return picture.frame;
+        });
+        this.element.replaceChildren(...parts);
+        this.#off = off;
+    }
+}
+/**
+ * A picture beside the sheet in a frame of its size, placed with the element's pictures: a
+ * statement's, and a worked example's in its list of parts (R42). The frame shows the picture once
+ * its file has come and is decoded, and what it shows in words till then, or if it never does.
+ */
+export function framed(pictures, part) {
+    const frame = document.createElement("div");
+    frame.className = "picture";
+    frame.style.width = `${part.width}px`;
+    frame.style.aspectRatio = `${part.width} / ${part.height}`;
+    fillFrame(frame, part);
+    /** The address the frame is to show, until it goes. */
+    let shown;
+    const off = pictures.place(part.picture, {
+        show(url) {
+            shown = url;
+            const image = document.createElement("img");
+            image.alt = part.alt;
+            image.src = url;
+            const swap = () => {
+                frame.removeAttribute("role");
+                frame.removeAttribute("aria-label");
+                frame.classList.add("shown");
+                frame.replaceChildren(image);
+            };
+            // A browser that keeps the decoded address at hand has the picture whole at once, as
+            // Chromium does; another decodes it again, and the frame shows its words till then (T64).
+            if (image.complete && image.naturalWidth > 0) {
+                swap();
+                return;
+            }
+            image.decode().then(() => {
+                if (shown === url)
+                    swap();
+            }, 
+            // The address went while it was decoded: the frame keeps its words.
+            () => undefined);
+        },
+        hide() {
+            shown = undefined;
+            fillFrame(frame, part);
+        },
+    });
+    return { frame, off };
+}
+/**
+ * A frame without its picture shows what the picture shows in words, and is read as the picture.
+ * One that only decorates shows nothing and is not read.
+ */
+function fillFrame(frame, part) {
+    frame.classList.remove("shown");
+    if (part.alt === "") {
+        frame.classList.add("decorative");
+        frame.removeAttribute("role");
+        frame.removeAttribute("aria-label");
+        frame.replaceChildren();
+        return;
+    }
+    frame.setAttribute("role", "img");
+    frame.setAttribute("aria-label", part.alt);
+    frame.textContent = part.alt;
+}

package/lib/element/tools.d.ts

@@ -0,0 +1,64 @@
+import type { Tool } from "../core/task.js";
+/**
+ * What the row asks of the element: a tool the learner chose — perhaps the one in use — an undo, a
+ * clearing, a scroll on down the sheet, for `onward`, or back up it, the finger to write again,
+ * out of pen mode, and on a worked example the next part of its demo, or the whole demo hidden or
+ * shown (R42).
+ */
+export interface ToolActions {
+    readonly choose: (tool: Tool) => void;
+    readonly undo: () => void;
+    readonly clear: () => void;
+    readonly upOrDown: (onward: boolean) => void;
+    readonly fingers: () => void;
+    readonly next: () => void;
+    readonly toggle: () => void;
+}
+/** What Next and Demo control, by their IDs in the element's shadow root (R42). */
+export interface DemoControls {
+    /** The region that tells of the part Next opens. */
+    readonly status: string;
+    /** The list of the open parts, which Demo hides and shows. */
+    readonly parts: string;
+}
+/** What the row is of, and is named by: a sheet, a workbook or a worked example (R36, R42). */
+export type RowKind = "sheet" | "workbook" | "example";
+/**
+ * What the row shows: what it is of, the tools the task allows, the one in use, whether undo and
+ * clearing have anything to do, whether the finger may be asked to write again, and on a worked
+ * example whether Next has a part to open and whether the demo is shown (R42).
+ */
+export interface ToolState {
+    readonly kind: RowKind;
+    readonly tools: readonly Tool[];
+    readonly tool: Tool;
+    readonly undoable: boolean;
+    readonly clearable: boolean;
+    readonly finger: boolean;
+    readonly opens: boolean;
+    readonly expanded: boolean;
+}
+/** The row of the element's own buttons, as the element shows it. */
+export declare class Tools {
+    #private;
+    /** The row: a toolbar, named in the element's language. */
+    readonly element: HTMLDivElement;
+    constructor(actions: ToolActions, controls: DemoControls);
+    /**
+     * The row as the sheet now is. Only what has changed is written. A worked example's row has no
+     * tools of writing, no undo and no clearing, for the learner does not write on its sheet, and has
+     * Next, unavailable while the demo is hidden or open whole, and Demo, expanded while the demo is
+     * shown (R42).
+     */
+    show({ kind, tools, tool, undoable, clearable, finger, opens, expanded }: ToolState): void;
+    /**
+     * Whether anything scrolls back up the sheet, for Up, and on down it, for Down: a button with
+     * nowhere to go stands unavailable. Only what has changed is written.
+     */
+    edges(above: boolean, below: boolean): void;
+    /**
+     * The labels in the language of a tag — the element's `lang` — and the row's own `lang` theirs,
+     * so that a screen reader reads them in the language they are in.
+     */
+    label(tag: string | null): void;
+}

package/lib/element/tools.js

@@ -0,0 +1,254 @@
+// The element's own row of buttons (R28): the tools the task allows — the pen and the eraser — and
+// undo and clearing. It is a toolbar as WAI-ARIA's Authoring Practices have one: one stop of Tab,
+// the arrow keys from button to button, and the tools a group of radio buttons that the arrows go
+// through without choosing one. Undo and Clear with nothing to take back or to clear stay where the
+// focus can reach them, marked unavailable: a last undo from the keyboard leaves the focus where it
+// was. Up and Down scroll the sheet with a single pointer, and stand unavailable at the end they
+// scroll to (R33). In pen mode a last button lets a finger write again (R29). The labels are in
+// the element's language (labels.ts), and the row is named by the canvas kind: the sheet or the
+// workbook (R36). A lesson's worked example names it too, and has no tools of writing in it: the
+// learner does not write on its sheet. Its first buttons are its demo's, Next, which opens the next
+// part, and Demo, a disclosure button that hides the whole demo and shows it again (R42). A button
+// that goes gives its stop of Tab and the focus to the first button shown. This module is no entry
+// point of the package.
+import { SVG, write } from "./attributes.js";
+import { labelsFor } from "./labels.js";
+/** The row of the element's own buttons, as the element shows it. */
+export class Tools {
+    /** The row: a toolbar, named in the element's language. */
+    element = document.createElement("div");
+    /** Next and Demo, a worked example's first buttons, kept together on a narrow screen (R42). */
+    #demoPair = document.createElement("div");
+    #next = plainButton();
+    #demo = plainButton();
+    #demoLabel = document.createElement("span");
+    #group = document.createElement("div");
+    #pen = radioButton();
+    #eraser = radioButton();
+    #undo = plainButton();
+    #clear = plainButton();
+    /** Up and Down, a pair that a row wrapping on a narrow screen keeps together. */
+    #pair = document.createElement("div");
+    #up = plainButton();
+    #down = plainButton();
+    #finger = plainButton();
+    /** The buttons in the order the arrow keys go through them: the row's own. */
+    #buttons = [
+        this.#next,
+        this.#demo,
+        this.#pen,
+        this.#eraser,
+        this.#undo,
+        this.#clear,
+        this.#up,
+        this.#down,
+        this.#finger,
+    ];
+    /** The language of the labels shown. */
+    #lang;
+    /** What the row is of, named so. */
+    #kind = "sheet";
+    /** Whether a button of the row has had the focus: Tab comes to the first button until one has. */
+    #chosen = false;
+    constructor(actions, controls) {
+        this.element.className = "tools";
+        this.element.setAttribute("role", "toolbar");
+        this.#demoPair.className = "demo";
+        // Next and Demo control what they do not hold: the region that tells of a part, and the list.
+        this.#next.setAttribute("aria-controls", controls.status);
+        this.#demo.setAttribute("aria-controls", controls.parts);
+        this.#demo.setAttribute("aria-expanded", "true");
+        this.#demo.append(triangle(), this.#demoLabel);
+        this.#demoPair.append(this.#next, this.#demo);
+        this.#group.className = "choice";
+        this.#group.setAttribute("role", "radiogroup");
+        this.#group.append(this.#pen, this.#eraser);
+        this.#pair.className = "updown";
+        this.#pair.append(this.#up, this.#down);
+        // The finger's button comes last: coming and going, it moves no other button of the row.
+        this.element.append(this.#demoPair, this.#group, this.#undo, this.#clear, this.#pair, this.#finger);
+        // A worked example's buttons and the finger's come with what they are for.
+        for (const hidden of [this.#demoPair, this.#next, this.#demo, this.#finger]) {
+            hidden.hidden = true;
+        }
+        // Tab comes to the first button shown, until another has had the focus.
+        this.#stopAt(this.#first());
+        // The element decides whether a choice is a change: the tool in use, chosen again, is none.
+        this.#pen.addEventListener("click", () => actions.choose("pen"));
+        this.#eraser.addEventListener("click", () => actions.choose("eraser"));
+        const doing = (button, act) => {
+            // aria-disabled stops no click: the button does nothing while it stands unavailable.
+            button.addEventListener("click", () => {
+                if (button.getAttribute("aria-disabled") !== "true")
+                    act();
+            });
+        };
+        doing(this.#undo, actions.undo);
+        doing(this.#clear, actions.clear);
+        doing(this.#next, actions.next);
+        this.#demo.addEventListener("click", () => actions.toggle());
+        // Up and Down ask the element anew at every press, unavailable or not: a scroll the element did
+        // not hear may have left either standing as it no longer is.
+        this.#up.addEventListener("click", () => actions.upOrDown(false));
+        this.#down.addEventListener("click", () => actions.upOrDown(true));
+        this.#finger.addEventListener("click", () => actions.fingers());
+        this.element.addEventListener("keydown", (event) => this.#key(event));
+        // The button that had the focus last is the one Tab comes back to.
+        this.element.addEventListener("focusin", (event) => {
+            const focused = this.#buttons.find((button) => button === event.target);
+            if (focused === undefined)
+                return;
+            this.#chosen = true;
+            this.#stopAt(focused);
+        });
+        this.label(null);
+    }
+    /**
+     * The row as the sheet now is. Only what has changed is written. A worked example's row has no
+     * tools of writing, no undo and no clearing, for the learner does not write on its sheet, and has
+     * Next, unavailable while the demo is hidden or open whole, and Demo, expanded while the demo is
+     * shown (R42).
+     */
+    show({ kind, tools, tool, undoable, clearable, finger, opens, expanded }) {
+        if (kind !== this.#kind) {
+            this.#kind = kind;
+            this.#name();
+        }
+        const writes = kind !== "example";
+        this.#reveal([
+            [this.#demoPair, !writes],
+            [this.#next, !writes],
+            [this.#demo, !writes],
+            [this.#group, writes],
+            [this.#pen, writes],
+            [this.#eraser, writes && tools.includes("eraser")],
+            [this.#undo, writes],
+            [this.#clear, writes],
+            [this.#finger, writes && finger],
+        ]);
+        write(this.#pen, "aria-checked", String(tool === "pen"));
+        write(this.#eraser, "aria-checked", String(tool === "eraser"));
+        write(this.#undo, "aria-disabled", undoable ? null : "true");
+        write(this.#clear, "aria-disabled", clearable ? null : "true");
+        write(this.#next, "aria-disabled", opens ? null : "true");
+        write(this.#demo, "aria-expanded", String(expanded));
+    }
+    /**
+     * Whether anything scrolls back up the sheet, for Up, and on down it, for Down: a button with
+     * nowhere to go stands unavailable. Only what has changed is written.
+     */
+    edges(above, below) {
+        write(this.#up, "aria-disabled", above ? null : "true");
+        write(this.#down, "aria-disabled", below ? null : "true");
+    }
+    /**
+     * The labels in the language of a tag — the element's `lang` — and the row's own `lang` theirs,
+     * so that a screen reader reads them in the language they are in.
+     */
+    label(tag) {
+        const { lang, labels } = labelsFor(tag);
+        if (lang === this.#lang)
+            return;
+        this.#lang = lang;
+        this.element.lang = lang;
+        this.#name();
+        this.#group.setAttribute("aria-label", labels.tool);
+        this.#next.textContent = labels.next;
+        this.#demoLabel.textContent = labels.demo;
+        this.#pen.textContent = labels.pen;
+        this.#eraser.textContent = labels.eraser;
+        this.#undo.textContent = labels.undo;
+        this.#clear.textContent = labels.clear;
+        this.#up.textContent = labels.up;
+        this.#down.textContent = labels.down;
+        this.#finger.textContent = labels.finger;
+    }
+    /** The row's name: the canvas kind's, in the labels' language. */
+    #name() {
+        const { labels } = labelsFor(this.#lang ?? null);
+        write(this.element, "aria-label", labels[this.#kind]);
+    }
+    /**
+     * The arrow keys move the focus to the next button or the one before, round the row, and Home
+     * and End to the first and the last: nothing is chosen, and no other key is the row's.
+     */
+    #key(event) {
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const shown = this.#shown();
+        const at = shown.indexOf(event.target);
+        if (at < 0)
+            return;
+        let next;
+        if (event.key === "ArrowRight")
+            next = shown[(at + 1) % shown.length];
+        else if (event.key === "ArrowLeft")
+            next = shown[(at - 1 + shown.length) % shown.length];
+        else if (event.key === "Home")
+            next = shown[0];
+        else if (event.key === "End")
+            next = shown.at(-1);
+        else
+            return;
+        event.preventDefault();
+        next?.focus();
+    }
+    /**
+     * Buttons come or go, all of them at once, and then a button that went gives its stop of Tab and
+     * the focus to the first button shown: the pen on a sheet, Next on a worked example (R28, R42). Till
+     * a button has had the focus, the stop is the first button shown, whichever it is now. Nothing is
+     * read or written while every button stays as it is: the row is shown anew after every stroke.
+     */
+    #reveal(wanted) {
+        if (wanted.every(([element, shown]) => element.hidden !== shown))
+            return;
+        // Read before a button hides: a hidden one loses the focus at the next update of the style.
+        const focused = this.#buttons.find((button) => button.matches(":focus"));
+        for (const [element, shown] of wanted)
+            element.hidden = !shown;
+        const first = this.#first();
+        if (!this.#chosen || this.#buttons.some((button) => button.tabIndex === 0 && button.hidden)) {
+            this.#stopAt(first);
+        }
+        if (focused?.hidden)
+            first.focus();
+    }
+    /** The buttons the row shows, in its order. */
+    #shown() {
+        return this.#buttons.filter((button) => !button.hidden);
+    }
+    /** The first button the row shows: Up and Down are on every row (R33). */
+    #first() {
+        return this.#shown()[0] ?? this.#up;
+    }
+    /** The one button Tab comes to: the arrow keys reach the others. */
+    #stopAt(stop) {
+        for (const button of this.#buttons)
+            button.tabIndex = button === stop ? 0 : -1;
+    }
+}
+/** A button of a tool: a radio button of the group, a button still, which the arrows leave alone. */
+function radioButton() {
+    const button = plainButton();
+    button.setAttribute("role", "radio");
+    button.setAttribute("aria-checked", "false");
+    return button;
+}
+/**
+ * The triangle of a disclosure button, pointing down while what it shows is shown: a picture that
+ * says nothing, for aria-expanded says it (R42).
+ */
+function triangle() {
+    const svg = document.createElementNS(SVG, "svg");
+    svg.setAttribute("viewBox", "0 0 10 10");
+    svg.setAttribute("aria-hidden", "true");
+    const path = document.createElementNS(SVG, "path");
+    path.setAttribute("d", "M1 3h8L5 8z");
+    svg.append(path);
+    return svg;
+}
+function plainButton() {
+    const button = document.createElement("button");
+    button.type = "button";
+    return button;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@altnovatrail/canvas",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "NovaTrail's canvases: the workplace of a task, where the learner writes, draws and types.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/altnovatrail/canvas.git"
+  },
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/element/index.d.ts",
+      "default": "./lib/element/index.js"
+    },
+    "./core": {
+      "types": "./lib/core/index.d.ts",
+      "default": "./lib/core/index.js"
+    }
+  },
+  "sideEffects": [
+    "./lib/element/index.js"
+  ],
+  "dependencies": {
+    "@altnovatrail/spec": "0.6.2",
+    "perfect-freehand": "1.2.3",
+    "rbush": "4.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.4",
+    "@types/node": "24.19.2",
+    "@types/rbush": "4.0.0",
+    "@vitest/browser-playwright": "5.0.5",
+    "@vitest/coverage-v8": "5.0.5",
+    "playwright": "1.64.1",
+    "typescript": "7.0.2",
+    "vite": "8.3.5",
+    "vitest": "5.0.5"
+  }
+}