@altnovatrail/canvas 0.0.0-stage → 0.1.1

package/lib/element/index.d.ts

@@ -0,0 +1,219 @@
+import type { CanvasElement, CanvasEventMap, ExportedWork } from "@altnovatrail/spec/canvas";
+import { type Filled } from "../core/boxes.js";
+import { type DemoState, type WorkedExample } from "../core/example.js";
+import { type HistoryEvent } from "../core/history.js";
+import { type Manifest } from "../core/manifest.js";
+import { type Marks } from "../core/marks.js";
+import { type Task, type Tool } from "../core/task.js";
+import { type Media } from "./pictures.js";
+/**
+ * The types of the contract of canvas and app are spec's (R74 spec; R07): the element as
+ * CanvasElement has it, what its events tell and the work it gives for checking, here, and the data
+ * — the history of writing, the context of a submission, the filled slots and the state of a demo
+ * — through the DOM-free part. The entry point gives them under spec's names, the same types. The
+ * tutor's marks, the media, the crop and a task with its temporary tools are the element's own
+ * (R26, R41).
+ */
+export type { Box, CanvasElement, CanvasEventMap, DemoChangeEvent, ExportedCell, ExportedSheet, ExportedWork, ExportedWorkbook, HistoryChange, HistoryChangeEvent, ToolChange, ToolChangeEvent, } from "@altnovatrail/spec/canvas";
+export type { Filled, Filling } from "../core/boxes.js";
+export type { Crop, Frame } from "../core/crop.js";
+export type { DemoState, WorkedExample } from "../core/example.js";
+export type { GridKind } from "../core/grid.js";
+export type { Group } from "../core/groups.js";
+export type { HistoryEvent } from "../core/history.js";
+export type { InkPoint, Stroke } from "../core/ink.js";
+export type { Manifest } from "../core/manifest.js";
+export type { Anchor, CellPlace, CropNumbers, Mark, Marks, SheetSubmission, Submission, WorkbookSubmission, } from "../core/marks.js";
+export type { Canvas, Task, Tool } from "../core/task.js";
+export type { Media } from "./pictures.js";
+/** The name the element is registered under. */
+export declare const TAG = "novatrail-canvas";
+/**
+ * The element `<novatrail-canvas>`: the contract's `CanvasElement` (R74 spec), and beyond it the
+ * tutor's marks, the media and the commands undo and clear, which the contract does not name.
+ */
+export declare class NovatrailCanvas extends HTMLElement implements CanvasElement {
+    #private;
+    constructor();
+    /** The element follows its own `lang`: its buttons are labelled in it (R07, R28). */
+    static readonly observedAttributes: string[];
+    /**
+     * What a press of the primary button does: "pen" writes, as the element starts, and "eraser"
+     * erases (R22). The learner switches it with the element's own buttons, which say a choice of
+     * theirs with a `toolchange`, and the consumer may set it too, which says nothing (R28). A press
+     * under way goes on as it began. A pen's eraser erases whatever the tool. A task without the
+     * eraser has none of it: "eraser" is a TypeError then, and a new task without it puts the pen
+     * back. A worked example has the pen alone, which writes nothing on its sheet (R42).
+     */
+    get tool(): Tool;
+    set tool(tool: Tool);
+    /**
+     * The open view of the task, of the module format 0.2 (R32): its ID, its statement, which the
+     * element shows above the page (R23), what the statement gives and asks, which app shows (R57
+     * spec), its canvas — the kind, the sheet's grid and the tools the task allows (R28) — and its
+     * items. A workbook's items are its lines, which the template shows, laid out on the page (R35,
+     * R36). The type is spec's, with the element's own tools (R73 spec; R41). A task the schema
+     * refuses is a TypeError that names the field, a field the open view has not among it, and so are
+     * a workbook whose lines do not fit, at the first item that does not (R35), and an answer slot in
+     * a zone; the sheet passes over a choice and an item's text, which app shows. Another task of the
+     * same layer, tools and statement changes nothing, and any other changes the template alone, of
+     * either kind: the work stays, for the next task is a new element (R20). A task without the
+     * eraser puts the pen back, with no event. While a worked example is shown a task is a TypeError,
+     * and `undefined` changes nothing: the element shows one or the other (R42).
+     */
+    get task(): Task | undefined;
+    set task(task: Task | undefined);
+    /**
+     * A lesson's worked example (R42; R58 spec): the open view of a segment `worked_example` of the
+     * module format 0.2 — its statement, which the element shows above the sheet as a task's (R23),
+     * the grid of its sheet, and the parts of the author's demo. The type is spec's (R73 spec; R41).
+     * The element shows a task or a worked example, not both: an example while a task is given, while
+     * the sheet has a history of writing, or while a stroke or an erasing is under way, is a
+     * TypeError, and so is one the schema refuses, at its field. `undefined` takes the example off,
+     * and the sheet is one with no task again. An example equal to the one shown changes nothing, and
+     * another replaces it, its grid and its statement apart, as a task does.
+     *
+     * On a worked example's sheet the learner does not write: the canvas takes no input, and a finger
+     * or a pen there scrolls the sheet as the browser scrolls the statement. Its row has no tools of
+     * writing and is named a worked example's. `task`, `history` other than the empty one and
+     * `marks` are TypeErrors, and so is an eraser: the tool is the pen alone, and `exportWork()` and
+     * `filled` give null. The next segment of a lesson is a new element (R20).
+     *
+     * The parts of the demo the learner opens one at a time with the row's Next, into a list between
+     * the statement and the sheet, and hides and shows whole with Demo; `demoState` tells how far
+     * they have gone. Another example starts its demo at the beginning.
+     */
+    get workedExample(): WorkedExample | undefined;
+    set workedExample(example: WorkedExample | undefined);
+    /**
+     * How far the learner has gone through the worked example's demo (R42): `opened`, how many of
+     * its parts are open, from the first, and `hidden`, whether the whole demo is hidden — frozen,
+     * and the same object until it changes. A new example starts at `{ opened: 0, hidden: false }`,
+     * and without one it is `undefined`. The learner changes it with the row's Next and Demo, which
+     * say so with a `demochange`; the consumer may give it back, which says nothing, tells a screen
+     * reader nothing, and scrolls nothing. It is given after the example, for it is checked against
+     * the example's parts: before one, a state is a TypeError, and `undefined` changes nothing. A
+     * state is an object of `opened`, a whole number from 0 to the number of parts, and `hidden`,
+     * true or false, or it is a TypeError that names the field. One that says the same changes
+     * nothing. Parts do not close one by one for the learner, but a consumer may give fewer.
+     */
+    get demoState(): DemoState | undefined;
+    set demoState(state: DemoState | undefined);
+    /**
+     * The open view of the module's manifest (R32), of which the element reads the version of the
+     * module format — "0.2", or the manifest is a TypeError (R44 spec) — the height of a digit on the
+     * crop for checking, `canvas.digit_height`, 24 px unless given, and the explanation language, the
+     * statement's and a workbook's lines'. Without a manifest the digits are 24 px, and the statement
+     * and the lines are in the element's own `lang`. The rest of it the element passes over, but for
+     * the canvas settings, which are its own: one it does not know is a TypeError. A manifest it
+     * cannot read is a TypeError that names the field, and the element stays as it was; the same
+     * object given again is read again, for the consumer may have changed it. The task and the
+     * manifest are each the consumer's to give, in either order: `exportWork()` takes the height
+     * when it is called (R27).
+     */
+    get manifest(): Manifest | undefined;
+    set manifest(manifest: Manifest | undefined);
+    /**
+     * What gives the files of the pictures, by their references (R07): a task's statement's, and a
+     * worked example's — its statement's and every part's of its demo, which it asks for as the
+     * example comes, before the learner opens them (R42). A reference is asked for once, whichever
+     * pictures show it, and its file stays while the task or the example names it. Until a picture's
+     * file comes, or if it never does, its frame shows what it shows in words. A new function serves
+     * the references that have no file yet, and stops no load the last one began.
+     */
+    get media(): Media | undefined;
+    set media(media: Media | undefined);
+    /**
+     * The history of writing (R22, R27): every stroke, erasing, clearing and undo on the sheet, in the
+     * order they landed, at the sheet's time — frozen, and the same array until the next action. The
+     * consumer keeps it, adding what `historychange` tells, and gives it back to open the sheet as it
+     * was: the strokes, and the actions undo takes back.
+     *
+     * The history the sheet has changes nothing: the very array, or one whose every event says the
+     * same — fields the sheet does not keep are passed over, and `undefined` is the empty one. A
+     * stroke under way goes on, and the marks stay. Any other history replaces the sheet, with no
+     * event: it must be one the sheet could have written, or it is a TypeError that names the field,
+     * and the sheet stays as it was. A stroke or an erasing under way goes: its IDs and its times are
+     * the last sheet's. The clock goes on more than the pause of the groups after the history's last
+     * event, the next stroke takes the next ID, and the tutor's marks go back on the strokes, or off,
+     * if the history has not their strokes. A history that is where the sheet's began loses what came
+     * after, and says so in the console. The task and the history are each the consumer's to give, in
+     * either order. A worked example's sheet has the empty history alone: any other is a TypeError
+     * (R42).
+     */
+    get history(): readonly HistoryEvent[];
+    set history(history: readonly HistoryEvent[] | undefined);
+    /**
+     * Which answer slots the learner's strokes fill, per item, per slot, in the task's order, by the
+     * strokes `exportWork()` would take — not the stroke under way, but those under an eraser not
+     * yet lifted. A workbook's boxes, each whether it holds one (R34, R37): a stroke is in one box
+     * or in none, by the rule of R37, and what is in none is the draft. A sheet's one answer anywhere
+     * on it or the whole sheet, whether the sheet holds one (R42). `null` for a sheet of choices,
+     * whose options app marks, for a sheet with no task, and for a worked example. Frozen, and the
+     * same array until a slot changes. An action on the sheet changes it before its
+     * `historychange`, and a task or a history given changes it with no event.
+     */
+    get filled(): Filled | null;
+    /**
+     * The tutor's marks of one submission, with the context the element gave with its work (R07,
+     * R26): each a frame where a group of strokes is, or a box on the crop the model saw, and on a
+     * workbook where an answer cell is, by its item and its slot (R39). A mark holds on to the
+     * strokes the model saw there and is drawn around those of them the sheet shows, as they are now
+     * — a cell's around its box too: new strokes do not move it, and when all of them are erased it
+     * is gone, till undo brings them back. A box that comes near no stroke, a cell on a sheet, which
+     * takes no zones, and a box of a workbook that was empty, have no frame: the question is asked
+     * without one. The type is the element's own until spec's contract gives one. A submission goes
+     * back to a sheet whose history holds its strokes, as its digest tells (R27), and a workbook's
+     * to a page of its boxes: one of other strokes or other boxes is a TypeError, and so are marks
+     * given before the task and the history they hold on to, and marks that are not marks. A new
+     * history, and a new page, put the marks back on their strokes, or take them off. `undefined`
+     * takes the marks off. Every value is checked as it comes, and marks equal to those shown write
+     * nothing. A worked example's sheet has nothing to mark: marks are a TypeError there (R42).
+     */
+    get marks(): Marks | undefined;
+    set marks(marks: Marks | undefined);
+    connectedCallback(): void;
+    /**
+     * The element's `lang` came, changed or went: its buttons and a workbook's boxes are labelled in
+     * it, or in English for a language their labels are not in, and for none (R28, R36). An attribute
+     * the element had before it was defined comes here just after the constructor, which reads no
+     * attribute.
+     */
+    attributeChangedCallback(): void;
+    /**
+     * Takes back the last action on the sheet — the last stroke written, the last erasing, or the
+     * clearing — and says whether there was one (R19, R22), with a `historychange` if there was
+     * (R27). The element's Undo button calls it, and so may the consumer (R28). A stroke under way
+     * stays: it lands when it ends. So does an erasing: what it came near leaves the sheet when it
+     * lifts, if it is on the sheet then.
+     */
+    undo(): boolean;
+    /**
+     * Takes every stroke off the sheet, an action that undo takes back, and says whether there were
+     * any (R19), with a `historychange` if there were (R27). The element's Clear button calls it, and
+     * so may the consumer (R28). A stroke under way stays: it lands when it ends.
+     */
+    clear(): boolean;
+    /**
+     * The work for checking (R07, R27), when the consumer asks for it, at Check, at the height of a
+     * digit the manifest asks for (R25, R32). On a sheet it is the crop of the strokes the sheet
+     * shows, its PNG, and the context of the submission — the crop's numbers, the groups and their
+     * digest (R26, R27). On a workbook it is the crop of each filled box, by its strokes alone, with
+     * its item and its slot, and the context — the table «box → stroke IDs» and its digest (R34,
+     * R38); the draft goes nowhere. The consumer keeps the context, sends only the PNGs and their
+     * places to be checked (R09 spec), and gives the context back with the tutor's marks. It is the
+     * sheet as it is when this is called: a stroke under way is not on it yet, while the strokes
+     * under an eraser not yet lifted still are, as `filled` has them. A sheet without strokes, and a
+     * workbook with no box filled, have no work to check, and the promise gives null (H3); so has a
+     * worked example, whose sheet the learner does not write on (R42).
+     */
+    exportWork(): Promise<ExportedWork | null>;
+    disconnectedCallback(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "novatrail-canvas": NovatrailCanvas;
+    }
+    interface GlobalEventHandlersEventMap extends CanvasEventMap {
+    }
+}