@doenet/doenetml-headless 0.0.0-stage → 0.7.27-dev.867
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.
- package/README.md +257 -2
- package/cli.d.ts +25 -0
- package/cli.js +199 -0
- package/cli.js.map +1 -0
- package/gradeState-DgaD_akY.js +269100 -0
- package/gradeState-DgaD_akY.js.map +1 -0
- package/index.d.ts +520 -0
- package/index.js +405 -0
- package/index.js.map +1 -0
- package/lib_doenetml_worker_bg.wasm +0 -0
- package/package.json +31 -4
- package/sha256-8sXzDnE0-BnWUgPS4-Dmbjs5kC.js +228 -0
- package/sha256-8sXzDnE0-BnWUgPS4-Dmbjs5kC.js.map +1 -0
- package/sha256-8sXzDnE0-Cn67cg22.js +228 -0
- package/sha256-8sXzDnE0-Cn67cg22.js.map +1 -0
package/index.d.ts
ADDED
|
@@ -0,0 +1,520 @@
|
|
|
1
|
+
import { DiagnosticArgs } from '../../packages/i18n/dist';
|
|
2
|
+
import { DiagnosticCode } from '../../packages/i18n/dist';
|
|
3
|
+
import { Position } from '../../packages/parser/dist';
|
|
4
|
+
|
|
5
|
+
declare type AccessibilityRecord = BaseDiagnosticRecord & {
|
|
6
|
+
type: "accessibility";
|
|
7
|
+
level: DiagnosticLevel;
|
|
8
|
+
};
|
|
9
|
+
|
|
10
|
+
declare type BaseDiagnosticRecord = {
|
|
11
|
+
/**
|
|
12
|
+
* The diagnostic as a finished sentence.
|
|
13
|
+
*
|
|
14
|
+
* Always present, even on a coded record. The worker always writes it in
|
|
15
|
+
* English — that is what its dedupe keys on, and what the worker's own
|
|
16
|
+
* tests assert — and `DocViewer` re-renders it in `uiLocale` on the way
|
|
17
|
+
* out, so a host reading `setDiagnosticsCallback` sees the reader's
|
|
18
|
+
* language. A code with no translation in the negotiated locale keeps the
|
|
19
|
+
* English.
|
|
20
|
+
*/
|
|
21
|
+
message: string;
|
|
22
|
+
/**
|
|
23
|
+
* The stable code naming this situation, for records that have migrated to
|
|
24
|
+
* the catalogs (#1518). Absent on a legacy diagnostic, whose English
|
|
25
|
+
* string is all there is.
|
|
26
|
+
*/
|
|
27
|
+
code?: DiagnosticCode;
|
|
28
|
+
/**
|
|
29
|
+
* The values filling the coded message's blanks, kept as data so the main
|
|
30
|
+
* thread can re-render the message in the reader's language.
|
|
31
|
+
*/
|
|
32
|
+
args?: DiagnosticArgs;
|
|
33
|
+
position?: Position;
|
|
34
|
+
sourceDoc?: number;
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Run `doenetML` in one variant and report what is wrong with it and what it
|
|
39
|
+
* asks: all of its diagnostics, its answers with their stable keys, which of
|
|
40
|
+
* them have none, and how many variants it has.
|
|
41
|
+
*/
|
|
42
|
+
export declare function check(doenetML: string, { variantIndex, flags, coreFactory, }?: CheckOptions): Promise<CheckResult>;
|
|
43
|
+
|
|
44
|
+
export declare type CheckedAnswer = {
|
|
45
|
+
/** The answer's stable key (`r[3].g.ans`), or `null` if it has none. */
|
|
46
|
+
stableKey: string | null;
|
|
47
|
+
componentType: string;
|
|
48
|
+
position?: Position;
|
|
49
|
+
/** The answer's own inputs, in position order. */
|
|
50
|
+
inputs: {
|
|
51
|
+
componentType: string;
|
|
52
|
+
}[];
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
export declare type CheckOptions = {
|
|
56
|
+
/** The variant to check, numbered from 1. Defaults to 1. */
|
|
57
|
+
variantIndex?: number;
|
|
58
|
+
/** Viewer flags to run the document with. */
|
|
59
|
+
flags?: Record<string, unknown>;
|
|
60
|
+
/** The core to run. Defaults to the JavaScript core. */
|
|
61
|
+
coreFactory?: HeadlessCoreFactory;
|
|
62
|
+
};
|
|
63
|
+
|
|
64
|
+
export declare type CheckResult = {
|
|
65
|
+
variantIndex: number;
|
|
66
|
+
numVariants: number;
|
|
67
|
+
/** Every diagnostic: errors, warnings, infos and accessibility. */
|
|
68
|
+
diagnostics: DiagnosticRecord[];
|
|
69
|
+
answers: CheckedAnswer[];
|
|
70
|
+
/**
|
|
71
|
+
* The answers with no stable key: no path from the document root reaches
|
|
72
|
+
* them and nothing else. Their inputs cannot be driven, and nothing that
|
|
73
|
+
* records answers by key can name them.
|
|
74
|
+
*/
|
|
75
|
+
answersWithoutStableKey: CheckedAnswer[];
|
|
76
|
+
};
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Create a core running `doenetML` without a browser.
|
|
80
|
+
*
|
|
81
|
+
* A `savedState` is applied as it is, without the checks `gradeState` makes;
|
|
82
|
+
* use `gradeState` to grade one. Call `terminate()` on the core when done.
|
|
83
|
+
*/
|
|
84
|
+
export declare function createHeadlessCore({ coreFactory, ...options }: CreateHeadlessCoreOptions): Promise<HeadlessCore>;
|
|
85
|
+
|
|
86
|
+
export declare type CreateHeadlessCoreOptions = HeadlessCoreOptions & {
|
|
87
|
+
/** The core to run. Defaults to the JavaScript core. */
|
|
88
|
+
coreFactory?: HeadlessCoreFactory;
|
|
89
|
+
};
|
|
90
|
+
|
|
91
|
+
export declare const defaultCoreFactory: HeadlessCoreFactory;
|
|
92
|
+
|
|
93
|
+
/** 1 = WCAG AA violation (critical); 2 = advisory recommendation. */
|
|
94
|
+
declare type DiagnosticLevel = 1 | 2;
|
|
95
|
+
|
|
96
|
+
export declare type DiagnosticRecord = ErrorRecord | WarningRecord | InfoRecord | AccessibilityRecord;
|
|
97
|
+
|
|
98
|
+
declare type ErrorRecord = BaseDiagnosticRecord & {
|
|
99
|
+
type: "error";
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
export declare type GradedAnswer = {
|
|
103
|
+
/** The answer's stable key (`r[3].g.ans`), or `null` if it has none. */
|
|
104
|
+
stableKey: string | null;
|
|
105
|
+
/** Its index in the core that graded it. Not stable; do not store it. */
|
|
106
|
+
componentIdx: number;
|
|
107
|
+
componentType: string;
|
|
108
|
+
position?: Position;
|
|
109
|
+
/**
|
|
110
|
+
* The credit the document assigns to the answer's inputs as stored in the
|
|
111
|
+
* state: `creditAchievedIfSubmit`, recomputed on load. Ignores attempt
|
|
112
|
+
* limits and is not reduced by `creditByAttempt`.
|
|
113
|
+
*/
|
|
114
|
+
credit: number;
|
|
115
|
+
/**
|
|
116
|
+
* What the state itself claims, as the browser stored it. Not
|
|
117
|
+
* recomputed, so not evidence of anything; shown beside `credit` for
|
|
118
|
+
* comparison.
|
|
119
|
+
*/
|
|
120
|
+
stored: {
|
|
121
|
+
creditAchieved: number;
|
|
122
|
+
numSubmissions: number;
|
|
123
|
+
};
|
|
124
|
+
inputs: {
|
|
125
|
+
componentType: string;
|
|
126
|
+
}[];
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Grade a saved state: load it into a fresh core for `doenetML` and
|
|
131
|
+
* `variantIndex`, and read the credit the document assigns to it.
|
|
132
|
+
*
|
|
133
|
+
* `savedState` is the payload the viewer reports to a host
|
|
134
|
+
* (`reportScoreAndState`'s `state`, or `SPLICE.reportScoreAndState`'s), as the
|
|
135
|
+
* host stored it, either as an object or as its JSON text.
|
|
136
|
+
*
|
|
137
|
+
* Refuses, with a `HeadlessError`, a state that is not such a payload, whose
|
|
138
|
+
* `data_format_version` the core does not read, that was written for another
|
|
139
|
+
* document source (`cid`), another variant, or (when `attemptNumber` is given)
|
|
140
|
+
* another attempt.
|
|
141
|
+
*/
|
|
142
|
+
export declare function gradeState(doenetML: string, variantIndex: number, savedState: HeadlessSavedState | string, { flags, attemptNumber, coreFactory, }?: GradeStateOptions): Promise<GradeStateResult>;
|
|
143
|
+
|
|
144
|
+
export declare type GradeStateOptions = {
|
|
145
|
+
/** Viewer flags to run the document with, as `DoenetViewer` takes them. */
|
|
146
|
+
flags?: Record<string, unknown>;
|
|
147
|
+
/**
|
|
148
|
+
* The attempt the state is expected to belong to. When given, a state
|
|
149
|
+
* that records a different attempt is refused.
|
|
150
|
+
*/
|
|
151
|
+
attemptNumber?: number;
|
|
152
|
+
/** The core to run. Defaults to the JavaScript core. */
|
|
153
|
+
coreFactory?: HeadlessCoreFactory;
|
|
154
|
+
};
|
|
155
|
+
|
|
156
|
+
export declare type GradeStateResult = {
|
|
157
|
+
variantIndex: number;
|
|
158
|
+
numVariants: number;
|
|
159
|
+
answers: GradedAnswer[];
|
|
160
|
+
document: {
|
|
161
|
+
/**
|
|
162
|
+
* The document's own `creditAchievedIfSubmit`, recomputed on load.
|
|
163
|
+
* Read from the document, which weighs its answers, pretzels and
|
|
164
|
+
* sections itself; not a sum of `answers`. `NaN` (`null` in JSON)
|
|
165
|
+
* when the document weighs nothing, or a `<problem>` or other
|
|
166
|
+
* aggregating section in it has no scored part.
|
|
167
|
+
*/
|
|
168
|
+
credit: number;
|
|
169
|
+
/** The document's credit from the stored credit of its parts. */
|
|
170
|
+
stored: {
|
|
171
|
+
creditAchieved: number;
|
|
172
|
+
};
|
|
173
|
+
};
|
|
174
|
+
diagnostics: DiagnosticRecord[];
|
|
175
|
+
savedState: {
|
|
176
|
+
dataFormatVersion: string;
|
|
177
|
+
/**
|
|
178
|
+
* Whether the state is the report the viewer made at a submission
|
|
179
|
+
* (`onSubmission: true`). A state saved at any other time can hold
|
|
180
|
+
* inputs changed after the last submission.
|
|
181
|
+
*/
|
|
182
|
+
onSubmission: boolean;
|
|
183
|
+
};
|
|
184
|
+
};
|
|
185
|
+
|
|
186
|
+
export declare type HeadlessAction = {
|
|
187
|
+
componentIdx: number;
|
|
188
|
+
actionName: string;
|
|
189
|
+
args?: Record<string, unknown>;
|
|
190
|
+
};
|
|
191
|
+
|
|
192
|
+
export declare type HeadlessActionResult = {
|
|
193
|
+
/**
|
|
194
|
+
* Each change the action asked for that was refused because
|
|
195
|
+
* `componentIdx` (the component the action changed, or a source it
|
|
196
|
+
* shadows) is `fixed` or has `fixLocation`. A change asked for by an
|
|
197
|
+
* action it set off (an `<updateValue>` or `<callAction>` triggered by
|
|
198
|
+
* the change) is not among them.
|
|
199
|
+
*/
|
|
200
|
+
refusedChanges: {
|
|
201
|
+
componentIdx: number;
|
|
202
|
+
stateVariable: string;
|
|
203
|
+
reason: "fixed" | "fixLocation";
|
|
204
|
+
}[];
|
|
205
|
+
};
|
|
206
|
+
|
|
207
|
+
export declare type HeadlessAnswer = HeadlessComponent & {
|
|
208
|
+
/**
|
|
209
|
+
* The answer's stable key: the shortest path from the document root that
|
|
210
|
+
* reaches it and nothing else, written as a reference without the `$`
|
|
211
|
+
* (`r[3].g.ans`). `null` when no such path exists, which is the case for a
|
|
212
|
+
* name that is not unique from the root and for an answer with no name on
|
|
213
|
+
* its way from the root.
|
|
214
|
+
*/
|
|
215
|
+
stableKey: string | null;
|
|
216
|
+
/** Where the answer is written in the source, when the core knows. */
|
|
217
|
+
position?: Position;
|
|
218
|
+
/**
|
|
219
|
+
* The credit the answer would get if it were submitted now, computed from
|
|
220
|
+
* its current inputs. It ignores attempt limits and is not reduced by
|
|
221
|
+
* `creditByAttempt`.
|
|
222
|
+
*/
|
|
223
|
+
creditAchievedIfSubmit: number;
|
|
224
|
+
/**
|
|
225
|
+
* Values the document holds as they were stored, not recomputed: after a
|
|
226
|
+
* saved state is loaded, these are whatever the saved state said.
|
|
227
|
+
*/
|
|
228
|
+
stored: {
|
|
229
|
+
creditAchieved: number;
|
|
230
|
+
numSubmissions: number;
|
|
231
|
+
};
|
|
232
|
+
/**
|
|
233
|
+
* The inputs that are the answer's own children, in order, so that
|
|
234
|
+
* `inputs[n - 1]` is the input at position `n`; none for a part scored as
|
|
235
|
+
* a whole, such as a `<pretzel>`. An input the answer uses
|
|
236
|
+
* through `forAnswer` is not here; it is reached by its own path.
|
|
237
|
+
*/
|
|
238
|
+
inputs: HeadlessComponent[];
|
|
239
|
+
};
|
|
240
|
+
|
|
241
|
+
export declare type HeadlessComponent = {
|
|
242
|
+
/**
|
|
243
|
+
* The component's index in this core. Stable only while the document
|
|
244
|
+
* source does not change, so not a key to store.
|
|
245
|
+
*/
|
|
246
|
+
componentIdx: number;
|
|
247
|
+
componentType: string;
|
|
248
|
+
};
|
|
249
|
+
|
|
250
|
+
/**
|
|
251
|
+
* The interface between `@doenet/doenetml-headless` and a DoenetML core.
|
|
252
|
+
*
|
|
253
|
+
* A core that implements this can be run without a browser: created from a
|
|
254
|
+
* document, a variant and an optional saved state, driven by actions, and read
|
|
255
|
+
* for its answers, credit and diagnostics. `@doenet/doenetml-headless` depends
|
|
256
|
+
* on this interface alone, so another core can stand in for the JavaScript one
|
|
257
|
+
* without changing that package's API or CLI. The JavaScript core's
|
|
258
|
+
* implementation is `createJavascriptHeadlessCoreFactory` in
|
|
259
|
+
* `@doenet/doenetml-worker-javascript/headless`.
|
|
260
|
+
*
|
|
261
|
+
* It lives here, rather than in either package, so that both can import it
|
|
262
|
+
* without depending on each other.
|
|
263
|
+
*/
|
|
264
|
+
export declare interface HeadlessCore {
|
|
265
|
+
/** What this core can do beyond the required members. */
|
|
266
|
+
readonly capabilities: HeadlessCoreCapabilities;
|
|
267
|
+
/** The variant this core is running, numbered from 1. */
|
|
268
|
+
readonly variantIndex: number;
|
|
269
|
+
/** How many variants the document has. */
|
|
270
|
+
readonly numVariants: number;
|
|
271
|
+
/**
|
|
272
|
+
* Run an action on a component, as a renderer would, and wait for the
|
|
273
|
+
* document to settle. Rejects if the core refuses the action itself.
|
|
274
|
+
* Resolves with the changes the action asked for that the core refused
|
|
275
|
+
* because a component, or a source it shadows, is `fixed` or has
|
|
276
|
+
* `fixLocation`: the action ran, and those changes did not happen.
|
|
277
|
+
*/
|
|
278
|
+
dispatchAction(action: HeadlessAction): Promise<HeadlessActionResult>;
|
|
279
|
+
/**
|
|
280
|
+
* Resolve a reference path such as `r[3].g.p` (with or without the leading
|
|
281
|
+
* `$`) from the document root, expanding whatever composites the path runs
|
|
282
|
+
* through. A path resolves only if each step resolves uniquely from the one
|
|
283
|
+
* before it, which is what makes it a stable key for the component.
|
|
284
|
+
* Throws if `path` is not written as names joined by `.` with literal
|
|
285
|
+
* indices.
|
|
286
|
+
*/
|
|
287
|
+
resolvePath(path: string): Promise<HeadlessPathResolution>;
|
|
288
|
+
/** The component's children, in order, as the document holds them now. */
|
|
289
|
+
getChildren(componentIdx: number): Promise<HeadlessComponent[]>;
|
|
290
|
+
/**
|
|
291
|
+
* The current values of the named state variables of a component, public
|
|
292
|
+
* or not. A name the component does not have is absent from the result.
|
|
293
|
+
* `setValue` reads `disabled`, `fixed`, `fixLocation`, `draggable`,
|
|
294
|
+
* `numChoices`, `selectMultiple`, `choicesDisabled`, `inline`, `numRows`,
|
|
295
|
+
* `numColumns` and `numDimensions`.
|
|
296
|
+
*/
|
|
297
|
+
readProperties(componentIdx: number, propertyNames: string[]): Promise<Record<string, unknown>>;
|
|
298
|
+
/**
|
|
299
|
+
* The document's scored parts, in the order a reader meets them (a
|
|
300
|
+
* repeat's iteration by iteration, a select's in the order selected):
|
|
301
|
+
* each `<answer>`, and each component scored as a whole, such as a
|
|
302
|
+
* `<pretzel>`, the parts the document numbers as its answers. Not
|
|
303
|
+
* included: a copy that shadows one (the part itself is reported once), a
|
|
304
|
+
* part whose content has not been created (inside an unopened
|
|
305
|
+
* `<solution>`), and the `<answer>` that gives each of a pretzel's
|
|
306
|
+
* problems' answer, which the pretzel turns into text.
|
|
307
|
+
*/
|
|
308
|
+
getAnswers(): Promise<HeadlessAnswer[]>;
|
|
309
|
+
/** The document's own credit. */
|
|
310
|
+
getDocumentCredit(): Promise<HeadlessDocumentCredit>;
|
|
311
|
+
/** Every diagnostic the document has reported so far, of every type. */
|
|
312
|
+
getDiagnostics(): Promise<DiagnosticRecord[]>;
|
|
313
|
+
/**
|
|
314
|
+
* The document's state as the viewer reports it to a host
|
|
315
|
+
* (`reportScoreAndState`'s `state`), including its `data_format_version`.
|
|
316
|
+
*/
|
|
317
|
+
serializeState(): Promise<HeadlessSavedState>;
|
|
318
|
+
/**
|
|
319
|
+
* Replace the running document's state with a saved one. Present only on a
|
|
320
|
+
* core whose `capabilities.loadState` is `true`; a core without it applies
|
|
321
|
+
* a saved state only when it is created, so a caller makes a new core for
|
|
322
|
+
* each state instead.
|
|
323
|
+
*/
|
|
324
|
+
loadState?(savedState: HeadlessSavedState): Promise<void>;
|
|
325
|
+
/** Release everything the core holds. The core cannot be used after. */
|
|
326
|
+
terminate(): Promise<void>;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
export declare type HeadlessCoreCapabilities = {
|
|
330
|
+
/** Whether `loadState` is implemented. */
|
|
331
|
+
readonly loadState: boolean;
|
|
332
|
+
};
|
|
333
|
+
|
|
334
|
+
/** Creates cores. Each core implementation provides one. */
|
|
335
|
+
export declare type HeadlessCoreFactory = {
|
|
336
|
+
/**
|
|
337
|
+
* The `data_format_version` the cores write into a saved state, and the
|
|
338
|
+
* only one they read back. On the factory rather than on a core, so that a
|
|
339
|
+
* saved state can be checked before a core is made from it.
|
|
340
|
+
*/
|
|
341
|
+
readonly dataFormatVersion: string;
|
|
342
|
+
create(options: HeadlessCoreOptions): Promise<HeadlessCore>;
|
|
343
|
+
};
|
|
344
|
+
|
|
345
|
+
export declare type HeadlessCoreOptions = {
|
|
346
|
+
/** The DoenetML source of the document. */
|
|
347
|
+
doenetML: string;
|
|
348
|
+
/** The variant to run, numbered from 1. Defaults to 1. */
|
|
349
|
+
variantIndex?: number;
|
|
350
|
+
/** Viewer flags, as `DoenetViewer` takes them. */
|
|
351
|
+
flags?: Record<string, unknown>;
|
|
352
|
+
/**
|
|
353
|
+
* A saved state to start from: a `reportScoreAndState` payload, as the
|
|
354
|
+
* viewer reported it. A core applies it as it is; checking that it
|
|
355
|
+
* belongs to this document and variant is the caller's job.
|
|
356
|
+
*/
|
|
357
|
+
savedState?: HeadlessSavedState | null;
|
|
358
|
+
};
|
|
359
|
+
|
|
360
|
+
export declare type HeadlessDocumentCredit = {
|
|
361
|
+
/**
|
|
362
|
+
* The document's credit if every answer were submitted now. `NaN` when
|
|
363
|
+
* the document weighs nothing (no scored part, or every weight 0), or
|
|
364
|
+
* when a `<problem>` or other aggregating section in it has no scored
|
|
365
|
+
* part (each divides by the weight of what it holds, with no guard for
|
|
366
|
+
* none).
|
|
367
|
+
*/
|
|
368
|
+
creditAchievedIfSubmit: number;
|
|
369
|
+
/** The document's credit from the stored credit of its parts. */
|
|
370
|
+
stored: {
|
|
371
|
+
creditAchieved: number;
|
|
372
|
+
};
|
|
373
|
+
};
|
|
374
|
+
|
|
375
|
+
export declare class HeadlessError extends Error {
|
|
376
|
+
readonly code: HeadlessErrorCode;
|
|
377
|
+
constructor(code: HeadlessErrorCode, message: string);
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/**
|
|
381
|
+
* Why `@doenet/doenetml-headless` refused something.
|
|
382
|
+
*
|
|
383
|
+
* - `invalidState`: the saved state is not a viewer state report.
|
|
384
|
+
* - `dataFormatVersion`: the saved state's `data_format_version` is not the
|
|
385
|
+
* one the core reads.
|
|
386
|
+
* - `documentMismatch`: the saved state was written for a different document
|
|
387
|
+
* source (its `cid`).
|
|
388
|
+
* - `variantMismatch`, `attemptMismatch`: the saved state was written for a
|
|
389
|
+
* different variant or attempt than the one asked for.
|
|
390
|
+
* - `notFound`: no component answers to the target.
|
|
391
|
+
* - `noStableKey`: the target names a component, but not uniquely from the
|
|
392
|
+
* document root, so it has no stable key and cannot be driven.
|
|
393
|
+
* - `unsupportedTarget`: the target is not a component type `setValue` sets.
|
|
394
|
+
* - `targetDisabled`: the input or the choice is disabled, the input is fixed,
|
|
395
|
+
* or the point cannot be moved, so it would ignore the value; or the value
|
|
396
|
+
* was sent and not taken, because what the target is bound to or extends
|
|
397
|
+
* is fixed (or, for a point, has a fixed location).
|
|
398
|
+
* - `invalidValue`: the value does not fit the target.
|
|
399
|
+
*/
|
|
400
|
+
export declare type HeadlessErrorCode = "invalidState" | "dataFormatVersion" | "documentMismatch" | "variantMismatch" | "attemptMismatch" | "notFound" | "noStableKey" | "unsupportedTarget" | "targetDisabled" | "invalidValue";
|
|
401
|
+
|
|
402
|
+
export declare type HeadlessPathResolution = {
|
|
403
|
+
status: "resolved";
|
|
404
|
+
component: HeadlessComponent;
|
|
405
|
+
}
|
|
406
|
+
/** Nothing in the document answers to the path. */
|
|
407
|
+
| {
|
|
408
|
+
status: "notFound";
|
|
409
|
+
}
|
|
410
|
+
/**
|
|
411
|
+
* More than one component answers to some step of the path, so the path
|
|
412
|
+
* is not a stable key for anything.
|
|
413
|
+
*/
|
|
414
|
+
| {
|
|
415
|
+
status: "notUnique";
|
|
416
|
+
};
|
|
417
|
+
|
|
418
|
+
/**
|
|
419
|
+
* A saved state: the payload the viewer delivers through
|
|
420
|
+
* `reportScoreAndState` (and `SPLICE.reportScoreAndState`). Opaque except for
|
|
421
|
+
* the fields named here, which are the ones a caller checks before using it.
|
|
422
|
+
*/
|
|
423
|
+
export declare type HeadlessSavedState = {
|
|
424
|
+
data_format_version?: unknown;
|
|
425
|
+
cid?: unknown;
|
|
426
|
+
coreInfo?: unknown;
|
|
427
|
+
coreState?: unknown;
|
|
428
|
+
attemptNumber?: unknown;
|
|
429
|
+
onSubmission?: unknown;
|
|
430
|
+
[key: string]: unknown;
|
|
431
|
+
};
|
|
432
|
+
|
|
433
|
+
declare type InfoRecord = BaseDiagnosticRecord & {
|
|
434
|
+
type: "info";
|
|
435
|
+
};
|
|
436
|
+
|
|
437
|
+
/**
|
|
438
|
+
* The environment variable that names a different resolver WASM file, for a
|
|
439
|
+
* host that keeps it somewhere other than beside this package's code.
|
|
440
|
+
*/
|
|
441
|
+
export declare const RESOLVER_WASM_ENV = "DOENET_HEADLESS_RESOLVER_WASM";
|
|
442
|
+
|
|
443
|
+
/** The component types `setValue` sets: the inputs it knows, and `<point>`. */
|
|
444
|
+
export declare const SETTABLE_COMPONENT_TYPES: readonly ["mathInput", "textInput", "booleanInput", "choiceInput", "fractionInput", "matrixInput", "point"];
|
|
445
|
+
|
|
446
|
+
/**
|
|
447
|
+
* Give an input or a point a raw value, with the actions its renderer would
|
|
448
|
+
* send, and wait for the document to settle.
|
|
449
|
+
*
|
|
450
|
+
* Refuses, with a `HeadlessError`, a target with no stable key (`noStableKey`)
|
|
451
|
+
* or that names nothing (`notFound`), a component of a type it does not know
|
|
452
|
+
* (`unsupportedTarget`, never a guess), a disabled or fixed input, a point that
|
|
453
|
+
* cannot be moved, or a disabled choice (`targetDisabled`), and a value of the wrong
|
|
454
|
+
* shape (`invalidValue`). Refuses as `targetDisabled`, too, a value that was
|
|
455
|
+
* sent and not taken: an input bound to a fixed component keeps its value,
|
|
456
|
+
* and a point that extends one with a fixed location stays put. A value the
|
|
457
|
+
* target already has is not refused for coming from a fixed source. Where the
|
|
458
|
+
* document refuses part of the
|
|
459
|
+
* change, the rest of it may have been made. Not caught: a value the document
|
|
460
|
+
* turns into exactly the value the input already has is refused, and a point
|
|
461
|
+
* whose coordinates come from a fixed point stays put without a refusal (see
|
|
462
|
+
* the README).
|
|
463
|
+
*/
|
|
464
|
+
export declare function setValue(core: HeadlessCore, target: ValueTarget, value: ValueToSet): Promise<void>;
|
|
465
|
+
|
|
466
|
+
/**
|
|
467
|
+
* Submit an answer, a `<pretzel>`, or everything under a section-wide check
|
|
468
|
+
* work (any component with a check-work button for what is inside it: a
|
|
469
|
+
* `<section>`, the `<document>`, and so on), as its check-work button does.
|
|
470
|
+
* `target` is a path from the root, with the same stable-key rule as
|
|
471
|
+
* `setValue`.
|
|
472
|
+
*/
|
|
473
|
+
export declare function submit(core: HeadlessCore, target: string): Promise<void>;
|
|
474
|
+
|
|
475
|
+
/**
|
|
476
|
+
* What `setValue` drives: either a path from the document root (`"x"`,
|
|
477
|
+
* `"$r[3].g.mi"`), or an answer's path and the position of one of the
|
|
478
|
+
* answer's own inputs, numbered from 1. The second form reaches an input that
|
|
479
|
+
* has no name of its own, such as the one `<answer name="ans">x</answer>`
|
|
480
|
+
* makes for itself.
|
|
481
|
+
*
|
|
482
|
+
* Either way the path must reach exactly one component from the root, each
|
|
483
|
+
* step resolving uniquely from the one before: that is the component's stable
|
|
484
|
+
* key. A name that is not unique from the root is no key, so its component
|
|
485
|
+
* cannot be driven, and neither can an input of an answer that has none.
|
|
486
|
+
*/
|
|
487
|
+
export declare type ValueTarget = string | {
|
|
488
|
+
answer: string;
|
|
489
|
+
position: number;
|
|
490
|
+
};
|
|
491
|
+
|
|
492
|
+
/**
|
|
493
|
+
* The raw value `setValue` gives a component, by its type: what a student
|
|
494
|
+
* enters or drags to, not the response an answer makes of it.
|
|
495
|
+
*
|
|
496
|
+
* - `mathInput`: the LaTeX typed, a string.
|
|
497
|
+
* - `textInput`: the text, a string.
|
|
498
|
+
* - `booleanInput`: a boolean.
|
|
499
|
+
* - `choiceInput`: the selected choices' positions, numbered from 1 (an array,
|
|
500
|
+
* or one number), in the order the reader sees the choices: one unless the
|
|
501
|
+
* input has `selectMultiple`, each at most once, none of a disabled choice.
|
|
502
|
+
* A list of choices selects them in increasing position, as its checkboxes
|
|
503
|
+
* do; an inline one in the order given, as its dropdown keeps the order
|
|
504
|
+
* they were picked.
|
|
505
|
+
* - `fractionInput`: `{ numerator, denominator }`, each the LaTeX typed.
|
|
506
|
+
* - `matrixInput`: the LaTeX of each cell, as an array of rows; its shape must
|
|
507
|
+
* be the matrix's.
|
|
508
|
+
* - `point`: its coordinates, `[x, y]` or `[x, y, z]` as the point has,
|
|
509
|
+
* moved as a drag does.
|
|
510
|
+
*/
|
|
511
|
+
export declare type ValueToSet = string | boolean | number | number[] | string[][] | {
|
|
512
|
+
numerator: string;
|
|
513
|
+
denominator: string;
|
|
514
|
+
};
|
|
515
|
+
|
|
516
|
+
declare type WarningRecord = BaseDiagnosticRecord & {
|
|
517
|
+
type: "warning";
|
|
518
|
+
};
|
|
519
|
+
|
|
520
|
+
export { }
|