@altnovatrail/skill-map 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,70 @@
1
+ import type { GetSkillMapResponse, SkillState } from "@altnovatrail/contracts/novatrail/api/v1/progress_pb.js";
2
+ import type { SkillGraph } from "@altnovatrail/spec/formatv0/open";
3
+ /**
4
+ * The state on the map of a skill whose assessability is `verdict`, in the order the first that
5
+ * holds is taken: «пора повторить», «освоено», «в работе», «можно начинать», «ещё закрыт».
6
+ */
7
+ export type MapState = "review" | "mastered" | "practising" | "ready" | "locked";
8
+ /** A skill's assessability, as the graph gives it (concepts 4 spec). */
9
+ export type Assessability = SkillGraph["skills"][string]["assessability"];
10
+ /** What the map shows of a skill of the module. */
11
+ export interface SkillOnMap {
12
+ /** The skill's local ID. */
13
+ readonly id: string;
14
+ /** Its assessability, from the graph. */
15
+ readonly assessability: Assessability;
16
+ /**
17
+ * The state on the map of a skill of `verdict`, and null for one of `rubric` or `none`, which
18
+ * has a mark instead, and for every skill on a map without state.
19
+ */
20
+ readonly state: MapState | null;
21
+ /**
22
+ * Whether the learner may choose the skill on the learner's view: there is state, and the skill
23
+ * is not «ещё закрыт». A skill of `rubric` or `none` is open whenever there is state.
24
+ */
25
+ readonly open: boolean;
26
+ /**
27
+ * What a locked skill waits for: its prerequisites among the module's skills of `verdict` whose
28
+ * mastery band is empty, in the order the graph lists them. Empty for every other skill.
29
+ */
30
+ readonly waitsFor: readonly string[];
31
+ /**
32
+ * The record of the answer the state comes from, the first that names the skill (R03), for the
33
+ * adult's details; absent for a skill the answer does not name, and on a map without state.
34
+ */
35
+ readonly record?: SkillState;
36
+ }
37
+ /** Whether the learner holds an anchor skill: «владеет», «не владеет», «неизвестно». */
38
+ export type Holding = "held" | "not-held" | "unknown";
39
+ /** Why the learner does not hold an anchor skill, or why it is unknown. */
40
+ export type Reason = "not-mastered" | "no-evidence" | "nobody-teaches" | "only-unassessable";
41
+ /** What the map shows of an anchor skill the graph names. */
42
+ export interface AnchorOnMap {
43
+ /** The anchor skill's ID, "core.multiplication-table". */
44
+ readonly id: string;
45
+ /** Whether the learner holds it, and null on a map without state. */
46
+ readonly holding: Holding | null;
47
+ /**
48
+ * Why not, or why it is unknown: null beside one held, for a reason this build does not know,
49
+ * and for one that does not go with the holding.
50
+ */
51
+ readonly reason: Reason | null;
52
+ /**
53
+ * Whether a skill of the module has it as a prerequisite, and so it stands before tier 1; one
54
+ * the graph names only in `teaches` is shown in the details of the skills that teach it (R03).
55
+ */
56
+ readonly prerequisite: boolean;
57
+ }
58
+ /** The states of a map: each skill of the module and each anchor skill its graph names. */
59
+ export interface MapStates {
60
+ /** The module's skills, in the order of the graph, by local ID. */
61
+ readonly skills: ReadonlyMap<string, SkillOnMap>;
62
+ /** The anchor skills the graph names as prerequisites or in `teaches`, by ID, as first named. */
63
+ readonly anchors: ReadonlyMap<string, AnchorOnMap>;
64
+ }
65
+ /**
66
+ * The states of a module's map at a time of the device (R03). Without the answer of GetSkillMap,
67
+ * a map for site and the authors' tools, no skill has a state or is open, and no anchor skill a
68
+ * holding.
69
+ */
70
+ export declare function mapStates(graph: SkillGraph, skillMap: GetSkillMapResponse | null, now: Date): MapStates;
@@ -0,0 +1,134 @@
1
+ // The states on the map (R03; docs/architecture.md, section 3.2): what each skill of a module shows,
2
+ // worked out from the open view of its graph, the answer of GetSkillMap and the time of the device.
3
+ // The map counts no mastery: it matches the marks learner-model has made against the graph.
4
+ /**
5
+ * The values of the contract's enums this build knows. The package takes the contracts' types
6
+ * alone, so the values are its own (R08 in docs/decisions.md); `satisfies` holds each to its
7
+ * member of the contract's: a value renumbered, two swapped, one added or one gone is a type error
8
+ * here.
9
+ */
10
+ const HOLDINGS = {
11
+ 1: "held",
12
+ 2: "not-held",
13
+ 3: "unknown",
14
+ };
15
+ const REASONS = {
16
+ 1: "not-mastered",
17
+ 2: "no-evidence",
18
+ 3: "nobody-teaches",
19
+ 4: "only-unassessable",
20
+ };
21
+ /** The reasons that explain each holding, as `progress.proto` spec gives them. */
22
+ const REASONS_OF = {
23
+ held: [],
24
+ "not-held": ["not-mastered", "no-evidence"],
25
+ unknown: ["nobody-teaches", "only-unassessable"],
26
+ };
27
+ /**
28
+ * The states of a module's map at a time of the device (R03). Without the answer of GetSkillMap,
29
+ * a map for site and the authors' tools, no skill has a state or is open, and no anchor skill a
30
+ * holding.
31
+ */
32
+ export function mapStates(graph, skillMap, now) {
33
+ const records = firstBy(skillMap?.skills ?? [], (record) => record.skill);
34
+ const mastered = (id) => (records.get(id)?.masteryBand ?? "") !== "";
35
+ const skills = new Map();
36
+ for (const [id, skill] of Object.entries(graph.skills)) {
37
+ const { assessability } = skill;
38
+ if (skillMap === null) {
39
+ skills.set(id, { id, assessability, state: null, open: false, waitsFor: [] });
40
+ }
41
+ else if (assessability !== "verdict") {
42
+ skills.set(id, { id, assessability, state: null, open: true, waitsFor: [] });
43
+ }
44
+ else {
45
+ // A prerequisite of rubric or none and an anchor skill do not hold the skill back: the map
46
+ // cannot see them mastered, and the engine keeps the author's order (R03).
47
+ const waitsFor = (skill.prerequisites ?? []).filter((prerequisite) => Object.hasOwn(graph.skills, prerequisite) &&
48
+ graph.skills[prerequisite]?.assessability === "verdict" &&
49
+ !mastered(prerequisite));
50
+ // A skill the answer does not name reads as one without evidence (R03).
51
+ const record = records.get(id);
52
+ const state = stateOf(record, waitsFor.length === 0, now);
53
+ skills.set(id, {
54
+ id,
55
+ assessability,
56
+ state,
57
+ open: state !== "locked",
58
+ waitsFor: state === "locked" ? waitsFor : [],
59
+ ...(record === undefined ? {} : { record }),
60
+ });
61
+ }
62
+ }
63
+ // The anchor skills, as the graph first names them; one named as a prerequisite anywhere stands
64
+ // before tier 1.
65
+ const prerequisites = new Set();
66
+ const ids = [];
67
+ for (const skill of Object.values(graph.skills)) {
68
+ for (const id of skill.prerequisites ?? [])
69
+ prerequisites.add(id);
70
+ for (const id of [...(skill.prerequisites ?? []), ...(skill.teaches ?? [])]) {
71
+ if (!Object.hasOwn(graph.skills, id) && !ids.includes(id))
72
+ ids.push(id);
73
+ }
74
+ }
75
+ const named = firstBy(skillMap?.anchorSkills ?? [], (record) => record.anchorSkill);
76
+ const anchors = new Map();
77
+ for (const id of ids) {
78
+ const prerequisite = prerequisites.has(id);
79
+ anchors.set(id, skillMap === null
80
+ ? { id, holding: null, reason: null, prerequisite }
81
+ : { id, ...holdingOf(named.get(id)), prerequisite });
82
+ }
83
+ return { skills, anchors };
84
+ }
85
+ /** The first state that holds, by R03. */
86
+ function stateOf(record, prerequisitesMastered, now) {
87
+ if (record !== undefined && record.masteryBand !== "") {
88
+ const due = record.reviewDue || (record.reviewDate !== undefined && notAfter(record.reviewDate, now));
89
+ return due ? "review" : "mastered";
90
+ }
91
+ if (record !== undefined && record.evidenceCount > 0)
92
+ return "practising";
93
+ return prerequisitesMastered ? "ready" : "locked";
94
+ }
95
+ /**
96
+ * Whether a moment of the contract is not later than a time of the device, compared exactly: the
97
+ * device's time to the millisecond, the contract's to the nanosecond. A time that is no time, an
98
+ * invalid Date, is later than no moment: the review falls due by `review_due` alone.
99
+ */
100
+ function notAfter(moment, now) {
101
+ const milliseconds = now.getTime();
102
+ if (!Number.isFinite(milliseconds))
103
+ return false;
104
+ const seconds = BigInt(Math.floor(milliseconds / 1000));
105
+ const nanos = (milliseconds - Number(seconds) * 1000) * 1_000_000;
106
+ return moment.seconds < seconds || (moment.seconds === seconds && moment.nanos <= nanos);
107
+ }
108
+ /**
109
+ * The holding and reason of an anchor skill the graph names, from its record in the answer. A
110
+ * holding this build does not know, the one never sent and an anchor skill the answer leaves out
111
+ * read as «неизвестно»; a reason it does not know is not shown, and neither is one that does not
112
+ * go with the holding — beside «владеет» there is none (`progress.proto` spec).
113
+ */
114
+ function holdingOf(record) {
115
+ const holding = known(HOLDINGS, record?.holding) ?? "unknown";
116
+ const reason = known(REASONS, record?.reason);
117
+ return {
118
+ holding,
119
+ reason: reason !== undefined && REASONS_OF[holding].includes(reason) ? reason : null,
120
+ };
121
+ }
122
+ /** The name of a value of an enum, if this build knows it. */
123
+ function known(names, value) {
124
+ return value === undefined ? undefined : names[value];
125
+ }
126
+ /** The records of a list by a key, the first of each key counting (R03). */
127
+ function firstBy(records, key) {
128
+ const byKey = new Map();
129
+ for (const record of records) {
130
+ if (!byKey.has(key(record)))
131
+ byKey.set(key(record), record);
132
+ }
133
+ return byKey;
134
+ }
@@ -0,0 +1,8 @@
1
+ /** The format file the titles come from, and its digest. */
2
+ export declare const SOURCE: {
3
+ readonly release: "spec v0.9.5";
4
+ readonly file: "format-0.3.tar.gz";
5
+ readonly sha256: "48c66b9e817e3caae317d10234a6174d0c5cc16a6cc6cbdb7d38c59960116c2d";
6
+ };
7
+ /** The English title of each anchor skill of the shared taxonomy, by ID (R50 spec). */
8
+ export declare const ANCHOR_TITLES: Readonly<Record<string, string>>;
@@ -0,0 +1,16 @@
1
+ // Written by scripts/taxonomy.ts from the format file of a release of spec, verified by spec's
2
+ // release-verify and held by its sha256 since: `just taxonomy` writes it anew (R09 in
3
+ // docs/decisions.md). Do not edit it by hand: ci-lint checks it against the file.
4
+ /** The format file the titles come from, and its digest. */
5
+ export const SOURCE = {
6
+ release: "spec v0.9.5",
7
+ file: "format-0.3.tar.gz",
8
+ sha256: "48c66b9e817e3caae317d10234a6174d0c5cc16a6cc6cbdb7d38c59960116c2d",
9
+ };
10
+ /** The English title of each anchor skill of the shared taxonomy, by ID (R50 spec). */
11
+ export const ANCHOR_TITLES = {
12
+ "core.division-with-remainder": "Division with a remainder",
13
+ "core.fractions-of-a-whole": "Fractions of a whole",
14
+ "core.linear-equations": "Linear equations",
15
+ "core.multiplication-table": "Multiplication table",
16
+ };
@@ -0,0 +1,59 @@
1
+ /**
2
+ * The icon of each value the map shows by one — a state, a mark, an anchor skill's holding — by
3
+ * the value: its name in the set, its view box and its paths, which the tree fills in the colour of
4
+ * the text.
5
+ */
6
+ export declare const ICONS: {
7
+ readonly review: {
8
+ readonly name: "update-outline-rounded";
9
+ readonly viewBox: "0 0 24 24";
10
+ readonly paths: readonly ["M12 21q-1.875 0-3.512-.712t-2.85-1.925t-1.925-2.85T3 12t.713-3.512t1.924-2.85t2.85-1.925T12 3q2.05 0 3.888.875T19 6.35V5q0-.425.288-.712T20 4t.713.288T21 5v4q0 .425-.288.713T20 10h-4q-.425 0-.712-.288T15 9t.288-.712T16 8h1.75q-1.025-1.4-2.525-2.2T12 5Q9.075 5 7.038 7.038T5 12t2.038 4.963T12 19q2.375 0 4.25-1.425t2.475-3.675q.125-.4.45-.6t.725-.15q.425.05.675.362t.15.688q-.725 2.975-3.15 4.888T12 21m1-9.4l2.5 2.5q.275.275.275.7t-.275.7t-.7.275t-.7-.275l-2.8-2.8q-.15-.15-.225-.337T11 11.975V8q0-.425.288-.712T12 7t.713.288T13 8z"];
11
+ };
12
+ readonly mastered: {
13
+ readonly name: "check-circle-outline-rounded";
14
+ readonly viewBox: "0 0 24 24";
15
+ readonly paths: readonly ["m10.6 13.8l-2.15-2.15q-.275-.275-.7-.275t-.7.275t-.275.7t.275.7L9.9 15.9q.3.3.7.3t.7-.3l5.65-5.65q.275-.275.275-.7t-.275-.7t-.7-.275t-.7.275zM12 22q-2.075 0-3.9-.788t-3.175-2.137T2.788 15.9T2 12t.788-3.9t2.137-3.175T8.1 2.788T12 2t3.9.788t3.175 2.137T21.213 8.1T22 12t-.788 3.9t-2.137 3.175t-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12t-2.325-5.675T12 4T6.325 6.325T4 12t2.325 5.675T12 20m0-8"];
16
+ };
17
+ readonly practising: {
18
+ readonly name: "timelapse-outline-rounded";
19
+ readonly viewBox: "0 0 24 24";
20
+ readonly paths: readonly ["M12 18q2.5 0 4.25-1.75T18 12q0-2.175-1.388-3.825T13.1 6.1q-.45-.05-.775.25T12 7.1V12l-3.45 3.45q-.325.325-.3.775t.375.725q.725.575 1.6.813T12 18m0 4q-2.075 0-3.9-.787t-3.175-2.138T2.788 15.9T2 12t.788-3.9t2.137-3.175T8.1 2.788T12 2t3.9.788t3.175 2.137T21.213 8.1T22 12t-.788 3.9t-2.137 3.175t-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12t-2.325-5.675T12 4T6.325 6.325T4 12t2.325 5.675T12 20m0-8"];
21
+ };
22
+ readonly ready: {
23
+ readonly name: "lock-open-right-outline-rounded";
24
+ readonly viewBox: "0 0 24 24";
25
+ readonly paths: readonly ["M6 20h12V10H6zm7.413-3.588Q14 15.826 14 15t-.587-1.412T12 13t-1.412.588T10 15t.588 1.413T12 17t1.413-.587M6 20V10zm0 2q-.825 0-1.412-.587T4 20V10q0-.825.588-1.412T6 8h7V6q0-2.075 1.463-3.537T18 1q1.775 0 3.1 1.075t1.75 2.7q.125.425-.162.825T22 6q-.425 0-.7-.175t-.4-.575q-.275-.95-1.062-1.6T18 3q-1.25 0-2.125.875T15 6v2h3q.825 0 1.413.588T20 10v10q0 .825-.587 1.413T18 22z"];
26
+ };
27
+ readonly locked: {
28
+ readonly name: "lock-outline-rounded";
29
+ readonly viewBox: "0 0 24 24";
30
+ readonly paths: readonly ["M6 22q-.825 0-1.412-.587T4 20V10q0-.825.588-1.412T6 8h1V6q0-2.075 1.463-3.537T12 1t3.538 1.463T17 6v2h1q.825 0 1.413.588T20 10v10q0 .825-.587 1.413T18 22zm0-2h12V10H6zm7.413-3.588Q14 15.826 14 15t-.587-1.412T12 13t-1.412.588T10 15t.588 1.413T12 17t1.413-.587M9 8h6V6q0-1.25-.875-2.125T12 3t-2.125.875T9 6zM6 20V10z"];
31
+ };
32
+ readonly rubric: {
33
+ readonly name: "rate-review-outline-rounded";
34
+ readonly viewBox: "0 0 24 24";
35
+ readonly paths: readonly ["M7 14h1.625q.2 0 .388-.075t.337-.225l4.7-4.7q.225-.225.338-.513t.112-.562t-.125-.537t-.325-.488l-.9-.95q-.225-.225-.5-.337t-.575-.113q-.275 0-.562.113T11 5.95l-4.7 4.7q-.15.15-.225.338T6 11.375V13q0 .425.288.713T7 14m6-6.075L12.075 7zM7.5 12.5v-.95l2.525-2.525l.5.45l.45.5L8.45 12.5zm3.025-3.025l.45.5l-.95-.95zm.65 4.525H17q.425 0 .713-.288T18 13t-.288-.712T17 12h-3.825zM6 18l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"];
36
+ };
37
+ readonly none: {
38
+ readonly name: "remove-done-outline-rounded";
39
+ readonly viewBox: "0 0 24 24";
40
+ readonly paths: readonly ["m21.125 21.1l-5.9-5.9l-2.15 2.15q-.3.3-.7.3t-.7-.3l-4.25-4.25q-.3-.3-.287-.7t.287-.7q.3-.3.713-.312t.712.287l3.525 3.525l1.4-1.4l-9.65-9.65q-.3-.3-.288-.7t.288-.7q.3-.3.713-.312t.712.287L22.525 19.7q.275.275.275.7t-.275.7t-.7.275t-.7-.275m-15.1-3.75l-4.25-4.25q-.275-.275-.275-.7t.275-.7t.7-.275t.7.275l3.55 3.55l1.4 1.4l-.7.7q-.3.3-.7.3t-.7-.3m12-4.95l-1.4-1.4l4.225-4.225q.275-.275.675-.287t.7.262t.313.7t-.288.725zm-2.85-2.85l-1.4-1.4l1.45-1.45q.275-.275.7-.275t.7.275t.275.7t-.275.7z"];
41
+ };
42
+ readonly held: {
43
+ readonly name: "verified-outline-rounded";
44
+ readonly viewBox: "0 0 24 24";
45
+ readonly paths: readonly ["M10.95 12.7L9.5 11.275Q9.225 11 8.813 11t-.713.3q-.275.275-.275.7t.275.7l2.15 2.15q.3.3.7.3t.7-.3l4.25-4.25q.3-.3.287-.7t-.287-.7q-.3-.3-.712-.312t-.713.287zm-2.8 9.05L6.7 19.3l-2.75-.6q-.375-.075-.6-.387t-.175-.688L3.45 14.8l-1.875-2.15q-.25-.275-.25-.65t.25-.65L3.45 9.2l-.275-2.825q-.05-.375.175-.688t.6-.387l2.75-.6l1.45-2.45q.2-.325.55-.438t.7.038l2.6 1.1l2.6-1.1q.35-.15.7-.038t.55.438L17.3 4.7l2.75.6q.375.075.6.388t.175.687L20.55 9.2l1.875 2.15q.25.275.25.65t-.25.65L20.55 14.8l.275 2.825q.05.375-.175.688t-.6.387l-2.75.6l-1.45 2.45q-.2.325-.55.438t-.7-.038l-2.6-1.1l-2.6 1.1q-.35.15-.7.038t-.55-.438m1.3-1.8l2.55-1.1l2.6 1.1l1.4-2.4l2.75-.65l-.25-2.8l1.85-2.1l-1.85-2.15l.25-2.8l-2.75-.6l-1.45-2.4L12 5.15l-2.6-1.1L8 6.45l-2.75.6l.25 2.8L3.65 12l1.85 2.1l-.25 2.85l2.75.6zM12 12"];
46
+ };
47
+ readonly "not-held": {
48
+ readonly name: "radio-button-unchecked-outline-rounded";
49
+ readonly viewBox: "0 0 24 24";
50
+ readonly paths: readonly ["M12 22q-2.075 0-3.9-.788t-3.175-2.137T2.788 15.9T2 12t.788-3.9t2.137-3.175T8.1 2.788T12 2t3.9.788t3.175 2.137T21.213 8.1T22 12t-.788 3.9t-2.137 3.175t-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12t-2.325-5.675T12 4T6.325 6.325T4 12t2.325 5.675T12 20"];
51
+ };
52
+ readonly unknown: {
53
+ readonly name: "question-mark-outline-rounded";
54
+ readonly viewBox: "0 0 24 24";
55
+ readonly paths: readonly ["M14.6 8.075q0-1.075-.712-1.725T12 5.7q-.725 0-1.312.313t-1.013.912q-.4.575-1.088.663T7.4 7.225q-.35-.325-.387-.8t.237-.9q.8-1.2 2.038-1.862T12 3q2.425 0 3.938 1.375t1.512 3.6q0 1.125-.475 2.025t-1.75 2.125q-.925.875-1.25 1.363T13.55 14.6q-.1.6-.513 1t-.987.4t-.987-.387t-.413-.963q0-.975.425-1.787T12.5 11.15q1.275-1.125 1.688-1.737t.412-1.338M12 22q-.825 0-1.412-.587T10 20t.588-1.412T12 18t1.413.588T14 20t-.587 1.413T12 22"];
56
+ };
57
+ };
58
+ /** A value the map shows by an icon. */
59
+ export type IconValue = keyof typeof ICONS;
@@ -0,0 +1,80 @@
1
+ // Written by scripts/icons.ts — `just icons` — from @iconify-json/material-symbols 1.2.97:
2
+ // Material Symbols by Google, under the Apache License 2.0 (R10 in docs/decisions.md; R78 spec).
3
+ // ci-lint fails unless it is what the script writes, so it is never edited by hand.
4
+ /**
5
+ * The icon of each value the map shows by one — a state, a mark, an anchor skill's holding — by
6
+ * the value: its name in the set, its view box and its paths, which the tree fills in the colour of
7
+ * the text.
8
+ */
9
+ export const ICONS = {
10
+ review: {
11
+ name: "update-outline-rounded",
12
+ viewBox: "0 0 24 24",
13
+ paths: [
14
+ "M12 21q-1.875 0-3.512-.712t-2.85-1.925t-1.925-2.85T3 12t.713-3.512t1.924-2.85t2.85-1.925T12 3q2.05 0 3.888.875T19 6.35V5q0-.425.288-.712T20 4t.713.288T21 5v4q0 .425-.288.713T20 10h-4q-.425 0-.712-.288T15 9t.288-.712T16 8h1.75q-1.025-1.4-2.525-2.2T12 5Q9.075 5 7.038 7.038T5 12t2.038 4.963T12 19q2.375 0 4.25-1.425t2.475-3.675q.125-.4.45-.6t.725-.15q.425.05.675.362t.15.688q-.725 2.975-3.15 4.888T12 21m1-9.4l2.5 2.5q.275.275.275.7t-.275.7t-.7.275t-.7-.275l-2.8-2.8q-.15-.15-.225-.337T11 11.975V8q0-.425.288-.712T12 7t.713.288T13 8z",
15
+ ],
16
+ },
17
+ mastered: {
18
+ name: "check-circle-outline-rounded",
19
+ viewBox: "0 0 24 24",
20
+ paths: [
21
+ "m10.6 13.8l-2.15-2.15q-.275-.275-.7-.275t-.7.275t-.275.7t.275.7L9.9 15.9q.3.3.7.3t.7-.3l5.65-5.65q.275-.275.275-.7t-.275-.7t-.7-.275t-.7.275zM12 22q-2.075 0-3.9-.788t-3.175-2.137T2.788 15.9T2 12t.788-3.9t2.137-3.175T8.1 2.788T12 2t3.9.788t3.175 2.137T21.213 8.1T22 12t-.788 3.9t-2.137 3.175t-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12t-2.325-5.675T12 4T6.325 6.325T4 12t2.325 5.675T12 20m0-8",
22
+ ],
23
+ },
24
+ practising: {
25
+ name: "timelapse-outline-rounded",
26
+ viewBox: "0 0 24 24",
27
+ paths: [
28
+ "M12 18q2.5 0 4.25-1.75T18 12q0-2.175-1.388-3.825T13.1 6.1q-.45-.05-.775.25T12 7.1V12l-3.45 3.45q-.325.325-.3.775t.375.725q.725.575 1.6.813T12 18m0 4q-2.075 0-3.9-.787t-3.175-2.138T2.788 15.9T2 12t.788-3.9t2.137-3.175T8.1 2.788T12 2t3.9.788t3.175 2.137T21.213 8.1T22 12t-.788 3.9t-2.137 3.175t-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12t-2.325-5.675T12 4T6.325 6.325T4 12t2.325 5.675T12 20m0-8",
29
+ ],
30
+ },
31
+ ready: {
32
+ name: "lock-open-right-outline-rounded",
33
+ viewBox: "0 0 24 24",
34
+ paths: [
35
+ "M6 20h12V10H6zm7.413-3.588Q14 15.826 14 15t-.587-1.412T12 13t-1.412.588T10 15t.588 1.413T12 17t1.413-.587M6 20V10zm0 2q-.825 0-1.412-.587T4 20V10q0-.825.588-1.412T6 8h7V6q0-2.075 1.463-3.537T18 1q1.775 0 3.1 1.075t1.75 2.7q.125.425-.162.825T22 6q-.425 0-.7-.175t-.4-.575q-.275-.95-1.062-1.6T18 3q-1.25 0-2.125.875T15 6v2h3q.825 0 1.413.588T20 10v10q0 .825-.587 1.413T18 22z",
36
+ ],
37
+ },
38
+ locked: {
39
+ name: "lock-outline-rounded",
40
+ viewBox: "0 0 24 24",
41
+ paths: [
42
+ "M6 22q-.825 0-1.412-.587T4 20V10q0-.825.588-1.412T6 8h1V6q0-2.075 1.463-3.537T12 1t3.538 1.463T17 6v2h1q.825 0 1.413.588T20 10v10q0 .825-.587 1.413T18 22zm0-2h12V10H6zm7.413-3.588Q14 15.826 14 15t-.587-1.412T12 13t-1.412.588T10 15t.588 1.413T12 17t1.413-.587M9 8h6V6q0-1.25-.875-2.125T12 3t-2.125.875T9 6zM6 20V10z",
43
+ ],
44
+ },
45
+ rubric: {
46
+ name: "rate-review-outline-rounded",
47
+ viewBox: "0 0 24 24",
48
+ paths: [
49
+ "M7 14h1.625q.2 0 .388-.075t.337-.225l4.7-4.7q.225-.225.338-.513t.112-.562t-.125-.537t-.325-.488l-.9-.95q-.225-.225-.5-.337t-.575-.113q-.275 0-.562.113T11 5.95l-4.7 4.7q-.15.15-.225.338T6 11.375V13q0 .425.288.713T7 14m6-6.075L12.075 7zM7.5 12.5v-.95l2.525-2.525l.5.45l.45.5L8.45 12.5zm3.025-3.025l.45.5l-.95-.95zm.65 4.525H17q.425 0 .713-.288T18 13t-.288-.712T17 12h-3.825zM6 18l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z",
50
+ ],
51
+ },
52
+ none: {
53
+ name: "remove-done-outline-rounded",
54
+ viewBox: "0 0 24 24",
55
+ paths: [
56
+ "m21.125 21.1l-5.9-5.9l-2.15 2.15q-.3.3-.7.3t-.7-.3l-4.25-4.25q-.3-.3-.287-.7t.287-.7q.3-.3.713-.312t.712.287l3.525 3.525l1.4-1.4l-9.65-9.65q-.3-.3-.288-.7t.288-.7q.3-.3.713-.312t.712.287L22.525 19.7q.275.275.275.7t-.275.7t-.7.275t-.7-.275m-15.1-3.75l-4.25-4.25q-.275-.275-.275-.7t.275-.7t.7-.275t.7.275l3.55 3.55l1.4 1.4l-.7.7q-.3.3-.7.3t-.7-.3m12-4.95l-1.4-1.4l4.225-4.225q.275-.275.675-.287t.7.262t.313.7t-.288.725zm-2.85-2.85l-1.4-1.4l1.45-1.45q.275-.275.7-.275t.7.275t.275.7t-.275.7z",
57
+ ],
58
+ },
59
+ held: {
60
+ name: "verified-outline-rounded",
61
+ viewBox: "0 0 24 24",
62
+ paths: [
63
+ "M10.95 12.7L9.5 11.275Q9.225 11 8.813 11t-.713.3q-.275.275-.275.7t.275.7l2.15 2.15q.3.3.7.3t.7-.3l4.25-4.25q.3-.3.287-.7t-.287-.7q-.3-.3-.712-.312t-.713.287zm-2.8 9.05L6.7 19.3l-2.75-.6q-.375-.075-.6-.387t-.175-.688L3.45 14.8l-1.875-2.15q-.25-.275-.25-.65t.25-.65L3.45 9.2l-.275-2.825q-.05-.375.175-.688t.6-.387l2.75-.6l1.45-2.45q.2-.325.55-.438t.7.038l2.6 1.1l2.6-1.1q.35-.15.7-.038t.55.438L17.3 4.7l2.75.6q.375.075.6.388t.175.687L20.55 9.2l1.875 2.15q.25.275.25.65t-.25.65L20.55 14.8l.275 2.825q.05.375-.175.688t-.6.387l-2.75.6l-1.45 2.45q-.2.325-.55.438t-.7-.038l-2.6-1.1l-2.6 1.1q-.35.15-.7.038t-.55-.438m1.3-1.8l2.55-1.1l2.6 1.1l1.4-2.4l2.75-.65l-.25-2.8l1.85-2.1l-1.85-2.15l.25-2.8l-2.75-.6l-1.45-2.4L12 5.15l-2.6-1.1L8 6.45l-2.75.6l.25 2.8L3.65 12l1.85 2.1l-.25 2.85l2.75.6zM12 12",
64
+ ],
65
+ },
66
+ "not-held": {
67
+ name: "radio-button-unchecked-outline-rounded",
68
+ viewBox: "0 0 24 24",
69
+ paths: [
70
+ "M12 22q-2.075 0-3.9-.788t-3.175-2.137T2.788 15.9T2 12t.788-3.9t2.137-3.175T8.1 2.788T12 2t3.9.788t3.175 2.137T21.213 8.1T22 12t-.788 3.9t-2.137 3.175t-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12t-2.325-5.675T12 4T6.325 6.325T4 12t2.325 5.675T12 20",
71
+ ],
72
+ },
73
+ unknown: {
74
+ name: "question-mark-outline-rounded",
75
+ viewBox: "0 0 24 24",
76
+ paths: [
77
+ "M14.6 8.075q0-1.075-.712-1.725T12 5.7q-.725 0-1.312.313t-1.013.912q-.4.575-1.088.663T7.4 7.225q-.35-.325-.387-.8t.237-.9q.8-1.2 2.038-1.862T12 3q2.425 0 3.938 1.375t1.512 3.6q0 1.125-.475 2.025t-1.75 2.125q-.925.875-1.25 1.363T13.55 14.6q-.1.6-.513 1t-.987.4t-.987-.387t-.413-.963q0-.975.425-1.787T12.5 11.15q1.275-1.125 1.688-1.737t.412-1.338M12 22q-.825 0-1.412-.587T10 20t.588-1.412T12 18t1.413.588T14 20t-.587 1.413T12 22",
78
+ ],
79
+ },
80
+ };
@@ -0,0 +1,43 @@
1
+ import type { GetSkillMapResponse } from "@altnovatrail/contracts/novatrail/api/v1/progress_pb.js";
2
+ import type { Manifest, SkillGraph } from "@altnovatrail/spec/formatv0/open";
3
+ import { type View } from "../core/attributes.js";
4
+ /** The element's name. */
5
+ export declare const TAG = "novatrail-skill-map";
6
+ /** The view of the map, by the attribute `view`: the learner's or the adult's (R03). */
7
+ export type SkillMapView = View;
8
+ /** What skillchoose carries: the full ID of the skill the learner chose, for ChooseNext. */
9
+ export interface SkillChoose {
10
+ /** The module's ID, `skill` and the skill's ID in the module, joined by `/` (R04). */
11
+ readonly skill: string;
12
+ }
13
+ /** The event the map sends when the learner chooses a skill to practise. */
14
+ export type SkillChooseEvent = CustomEvent<SkillChoose>;
15
+ /** The skill map of one module: its skills in tiers, with the learner model's state over them. */
16
+ export declare class NovatrailSkillMap extends HTMLElement {
17
+ #private;
18
+ static readonly observedAttributes: string[];
19
+ constructor();
20
+ /** The open view of the module's skill graph, as GetSkillGraph gives it (R04). */
21
+ get graph(): SkillGraph | null;
22
+ set graph(graph: SkillGraph | null);
23
+ /** The tiers of the graph's skills, `skill_tiers` of GetSkillGraph, by the skill's local ID. */
24
+ get tiers(): Readonly<Record<string, number>> | null;
25
+ set tiers(tiers: Readonly<Record<string, number>> | null);
26
+ /** The open view of the module's manifest: its ID, explanation language and bands. */
27
+ get manifest(): Manifest | null;
28
+ set manifest(manifest: Manifest | null);
29
+ /** The answer of GetSkillMap, or null for a map without state (R03). */
30
+ get skillMap(): GetSkillMapResponse | null;
31
+ set skillMap(skillMap: GetSkillMapResponse | null);
32
+ connectedCallback(): void;
33
+ disconnectedCallback(): void;
34
+ attributeChangedCallback(): void;
35
+ }
36
+ declare global {
37
+ interface HTMLElementTagNameMap {
38
+ [TAG]: NovatrailSkillMap;
39
+ }
40
+ interface GlobalEventHandlersEventMap {
41
+ skillchoose: SkillChooseEvent;
42
+ }
43
+ }
@@ -0,0 +1,126 @@
1
+ // The package's one entry point: importing it registers <novatrail-skill-map>, the element app
2
+ // draws a module's skill map with (R04; R36 spec). Data comes in by properties, the view, the
3
+ // language and the level of headings by attributes, and the choice of a skill goes out by the
4
+ // event skillchoose; there are no methods. The map keeps nothing of a learner's beyond its memory
5
+ // while it is on the page (R03).
6
+ import { headingLevel, viewOf } from "../core/attributes.js";
7
+ import { styles } from "./styles.js";
8
+ import { MapTree } from "./tree.js";
9
+ import { wordsFor } from "./words.js";
10
+ /** The element's name. */
11
+ export const TAG = "novatrail-skill-map";
12
+ /** The skill map of one module: its skills in tiers, with the learner model's state over them. */
13
+ export class NovatrailSkillMap extends HTMLElement {
14
+ static observedAttributes = ["view", "lang", "heading-level"];
15
+ #graph = null;
16
+ #tiers = null;
17
+ #manifest = null;
18
+ #skillMap = null;
19
+ #scheduled = false;
20
+ #tree;
21
+ constructor() {
22
+ super();
23
+ // A property a page set before the package registered the element is an own property of it,
24
+ // which hides the accessor: it is taken out and assigned again, through the accessor.
25
+ const own = this;
26
+ const early = [];
27
+ for (const name of ["graph", "tiers", "manifest", "skillMap"]) {
28
+ if (Object.hasOwn(this, name)) {
29
+ early.push([name, own[name]]);
30
+ delete own[name];
31
+ }
32
+ }
33
+ const root = this.attachShadow({ mode: "open" });
34
+ root.adoptedStyleSheets = [styles()];
35
+ this.#tree = new MapTree(root, (skill) => {
36
+ this.dispatchEvent(new CustomEvent("skillchoose", {
37
+ bubbles: true,
38
+ composed: true,
39
+ detail: Object.freeze({ skill }),
40
+ }));
41
+ });
42
+ for (const [name, value] of early)
43
+ Reflect.set(this, name, value);
44
+ }
45
+ /** The open view of the module's skill graph, as GetSkillGraph gives it (R04). */
46
+ get graph() {
47
+ return this.#graph;
48
+ }
49
+ set graph(graph) {
50
+ this.#graph = graph;
51
+ this.#schedule();
52
+ }
53
+ /** The tiers of the graph's skills, `skill_tiers` of GetSkillGraph, by the skill's local ID. */
54
+ get tiers() {
55
+ return this.#tiers;
56
+ }
57
+ set tiers(tiers) {
58
+ this.#tiers = tiers;
59
+ this.#schedule();
60
+ }
61
+ /** The open view of the module's manifest: its ID, explanation language and bands. */
62
+ get manifest() {
63
+ return this.#manifest;
64
+ }
65
+ set manifest(manifest) {
66
+ this.#manifest = manifest;
67
+ this.#schedule();
68
+ }
69
+ /** The answer of GetSkillMap, or null for a map without state (R03). */
70
+ get skillMap() {
71
+ return this.#skillMap;
72
+ }
73
+ set skillMap(skillMap) {
74
+ this.#skillMap = skillMap;
75
+ this.#schedule();
76
+ }
77
+ connectedCallback() {
78
+ this.#tree.connect();
79
+ }
80
+ disconnectedCallback() {
81
+ this.#tree.disconnect();
82
+ }
83
+ attributeChangedCallback() {
84
+ this.#schedule();
85
+ }
86
+ /**
87
+ * Updates the map once for whatever one task assigned, after it: app assigns the graph, the
88
+ * tiers, the manifest and the state one after another, and the map follows them in place.
89
+ */
90
+ #schedule() {
91
+ if (this.#scheduled)
92
+ return;
93
+ this.#scheduled = true;
94
+ queueMicrotask(() => {
95
+ this.#scheduled = false;
96
+ this.#render();
97
+ });
98
+ }
99
+ #render() {
100
+ const graph = this.#graph;
101
+ const tiers = this.#tiers;
102
+ const manifest = this.#manifest;
103
+ this.#tree.render(graph === null || tiers === null || manifest === null
104
+ ? null
105
+ : {
106
+ graph,
107
+ tiers,
108
+ manifest,
109
+ skillMap: this.#skillMap,
110
+ view: viewOf(this.getAttribute("view")),
111
+ headingLevel: headingLevel(this.getAttribute("heading-level")),
112
+ now: new Date(),
113
+ words: wordsFor(this.getAttribute("lang")),
114
+ });
115
+ }
116
+ }
117
+ // A second copy of this module, from a second copy of the package, finds the name taken and
118
+ // leaves the first registration in place, rather than throwing when the page imports it. It says
119
+ // so, though: elements of the page are then built by the other copy, of whatever version it is.
120
+ // A module runs once, so the name taken is never this copy's own class.
121
+ if (customElements.get(TAG) === undefined) {
122
+ customElements.define(TAG, NovatrailSkillMap);
123
+ }
124
+ else {
125
+ console.warn(`<${TAG}> is already registered by another copy of @altnovatrail/skill-map; this copy's element is not used`);
126
+ }
@@ -0,0 +1,11 @@
1
+ import type { Line } from "../core/lines.js";
2
+ /** The namespace of SVG. */
3
+ export declare const SVG = "http://www.w3.org/2000/svg";
4
+ /** The lines of one element's map. */
5
+ export declare class Lines {
6
+ #private;
7
+ readonly svg: SVGSVGElement;
8
+ constructor(document: Document);
9
+ /** Draws the lines given, and nothing else. */
10
+ draw(lines: readonly Line[]): void;
11
+ }
@@ -0,0 +1,61 @@
1
+ // The drawing of the expanded skill's lines (R06; R11 in docs/decisions.md): one SVG under the
2
+ // bands of the map, with a path and a point at each end for each line that linesOf of the core
3
+ // gives. One unit of the drawing is a CSS pixel of the map: the SVG has no view box. Places come
4
+ // from attributes of SVG alone — d, cx and cy — and no attribute style, so that a consumer's CSP lets them through (R09). The SVG is hidden from the tree of
5
+ // accessibility: what is linked to what the details and the tiles' labels say in words.
6
+ /** The namespace of SVG. */
7
+ export const SVG = "http://www.w3.org/2000/svg";
8
+ /** The radius of the point at each end of a line, in CSS pixels. */
9
+ const POINT = 4;
10
+ /** The lines of one element's map. */
11
+ export class Lines {
12
+ svg;
13
+ #document;
14
+ #lines = new Map();
15
+ constructor(document) {
16
+ this.#document = document;
17
+ this.svg = document.createElementNS(SVG, "svg");
18
+ this.svg.setAttribute("class", "lines");
19
+ this.svg.setAttribute("aria-hidden", "true");
20
+ this.svg.setAttribute("focusable", "false");
21
+ }
22
+ /** Draws the lines given, and nothing else. */
23
+ draw(lines) {
24
+ const drawn = new Set();
25
+ for (const line of lines) {
26
+ const key = `${line.from}\n${line.to}`;
27
+ drawn.add(key);
28
+ const nodes = this.#lines.get(key) ?? this.#make(line);
29
+ nodes.path.setAttribute("d", line.d);
30
+ place(nodes.start, line.start);
31
+ place(nodes.end, line.end);
32
+ }
33
+ for (const [key, nodes] of this.#lines) {
34
+ if (!drawn.has(key)) {
35
+ nodes.group.remove();
36
+ this.#lines.delete(key);
37
+ }
38
+ }
39
+ }
40
+ #make(line) {
41
+ const group = this.#document.createElementNS(SVG, "g");
42
+ group.setAttribute("data-from", line.from);
43
+ group.setAttribute("data-to", line.to);
44
+ const path = this.#document.createElementNS(SVG, "path");
45
+ const [start, end] = [0, 1].map(() => {
46
+ const point = this.#document.createElementNS(SVG, "circle");
47
+ point.setAttribute("r", String(POINT));
48
+ return point;
49
+ });
50
+ group.append(path, start, end);
51
+ this.svg.append(group);
52
+ const nodes = { group, path, start, end };
53
+ this.#lines.set(`${line.from}\n${line.to}`, nodes);
54
+ return nodes;
55
+ }
56
+ }
57
+ /** Puts a point of a line where it belongs: the core has rounded it as it rounds the curve. */
58
+ function place(point, at) {
59
+ point.setAttribute("cx", String(at.x));
60
+ point.setAttribute("cy", String(at.y));
61
+ }
@@ -0,0 +1,2 @@
1
+ /** The sheet of this copy of the module, made once, the first time an element needs it. */
2
+ export declare function styles(): CSSStyleSheet;