@astrolabe/player

The <astl-player> element, element base classes, the attempt controller, httpChecker and accessibility helpers. Contains no answer logic.

Classes

abstract AstlElement

Extends

• LitElement

Extended by

• SingleSlotElement

Implements

• PlayerElementApi

Constructors

Constructor

new AstlElement(): AstlElement;

Returns

AstlElement

Overrides

LitElement.constructor

Properties

Property	Modifier	Type	Default value	Description
disabled	public	boolean	undefined	-
feedback	public	| ElementFeedback | null	undefined	Verdicts to show; null clears them. Editing a slot clears its own verdict and the group verdict.
manifest	static	| ComponentManifest | null	null	The element type's manifest: drives the typed attribute getters and the default message namespace.
messages	static	readonly MessageCatalog[]	[]	Catalogs of the manifest's namespace, used until a player attaches its own context.
solution	public	Readonly<Record<string, string>> | null	undefined	Correct answers to show next to the student's; null hides them.

Accessors

context

Get Signature

get context(): ElementContext;

The player's context, or the default English one.

Returns

ElementContext

slotIds

Get Signature

get abstract slotIds(): readonly string[];

Slot ids this element answers, in reading order. Stable after the element connects.

Returns

readonly string[]

Slot ids this element answers, in reading order. Stable after the element connects.

Implementation of

PlayerElementApi.slotIds

Methods

attach()

attach(context): void;

Called by the player once, before the first render. Elements must work with a default context too.

Parameters

Parameter	Type
context	ElementContext

Returns

void

Implementation of

PlayerElementApi.attach

getAnswers()

abstract getAnswers(): Answers;

Answered slots only.

Returns

Answers

Implementation of

PlayerElementApi.getAnswers

setAnswers()

abstract setAnswers(answers): void;

Unknown ids are ignored; '' clears a slot. Does not fire a change event.

Parameters

Parameter	Type
answers	Answers

Returns

void

Implementation of

PlayerElementApi.setAnswers

units()

abstract units(): Units;

Progress units, e.g. 3 of 5 cards placed.

Returns

Units

Implementation of

PlayerElementApi.units

---

AstlPlayer

Extends

• LitElement

Constructors

Constructor

new AstlPlayer(): AstlPlayer;

Returns

AstlPlayer

Overrides

LitElement.constructor

Properties

Property	Type	Description
checker	Checker | null	Grades checks and submits. Default: an HTTP checker for endpoint, if set.
endpoint	string | null	Grading endpoint (protocol 1) of this attempt.
integrity	string | null	Lowercase hex SHA-256 the fetched src must match.
locale	string | null	UI locale; default: the lang attribute, else the browser languages.
persist	boolean	Keep snapshots in localStorage (per view hash) and restore them on load.
policy	AttemptPolicy	-
snapshot	Snapshot | null	Restored on load when its viewHash matches the view (or is null).
src	string | null	URL of a view to fetch when no view is given.
styleTemplate	string | null	The host's default style template (a registered template with the document scope), used when the view's <astl-doc> names none that this player knows.
theme	ThemeSetting | null	-
view	string	View HTML to play (compiled, no answers). Setting it loads it.

Accessors

page

Get Signature

get page(): number;

0-based index of the current page.

Returns

number

state

Get Signature

get state(): AttemptState;

loading, ready, active, checking, submitting, submitted, review or error.

Returns

AttemptState

viewHash

Get Signature

get viewHash(): string | null;

Lowercase hex SHA-256 of the mounted view; null before mounting or without WebCrypto.

Returns

string | null

Methods

check()

check(): Promise<CheckResponse | null>;

Practice: grades the answers and shows verdicts. Failures are shown and emitted, never thrown.

Returns

Promise<CheckResponse | null>

getAnswers()

getAnswers(): Answers;

Returns

Answers

getSnapshot()

getSnapshot(): Snapshot | null;

Returns

Snapshot | null

goTo()

goTo(index): boolean;

Parameters

Parameter	Type
index	number

Returns

boolean

load()

load(input): Promise<void>;

Plays a view. Resolves when it is mounted (astl-ready); rejects with the error code when it cannot.

Parameters

Parameter	Type
input	LoadInput

Returns

Promise<void>

next()

next(): boolean;

Returns

boolean

previous()

previous(): boolean;

Returns

boolean

reset()

reset(): boolean;

Clears answers and results and goes back to the first page (not after submitting).

Returns

boolean

setAnswers()

setAnswers(answers): void;

Sets answers programmatically ('' clears); no change events from elements. The attempt keeps what the elements accept (an unknown option id or a flag other than "true" is dropped), so what is checked and handed in is always what the student sees.

Parameters

Parameter	Type
answers	Answers

Returns

void

submit()

submit(): Promise<
  | SubmitResponse
| null>;

Hands the answers in (final). Failures are shown and emitted, never thrown.

Returns

Promise< | SubmitResponse | null>

---

AttemptController

Constructors

Constructor

new AttemptController(options): AttemptController;

Parameters

Parameter	Type
options	AttemptControllerOptions

Returns

AttemptController

Properties

Property	Modifier	Type	Description
checker	public	Checker	The checker can be swapped at any time (e.g. a host sets it after the view).
pages	readonly	readonly AttemptPage[]	-
policy	readonly	AttemptPolicy	-
restored	readonly	boolean	Whether the snapshot passed in was applied.
viewHash	readonly	string | null	-

Accessors

answers

Get Signature

get answers(): Answers;

Returns

Answers

checks

Get Signature

get checks(): number;

Returns

number

checksLeft

Get Signature

get checksLeft(): number | null;

null = unlimited.

Returns

number | null

page

Get Signature

get page(): number;

0-based index of the current page.

Returns

number

pageCount

Get Signature

get pageCount(): number;

Returns

number

readOnly

Get Signature

get readOnly(): boolean;

Answers cannot change: review, submitting or submitted.

Returns

boolean

response

Get Signature

get response():
  | CheckResponse
  | SubmitResponse
  | null;

The last CheckResponse or SubmitResponse.

Returns

| CheckResponse | SubmitResponse | null

result

Get Signature

get result(): GradeResult | null;

The last result (practice keeps it while the student goes on).

Returns

GradeResult | null

solution

Get Signature

get solution(): Readonly<Record<string, string>> | null;

Returns

Readonly<Record<string, string>> | null

state

Get Signature

get state(): AttemptState;

Returns

AttemptState

Methods

canCheck()

canCheck(): boolean;

Returns

boolean

canGoTo()

canGoTo(index): boolean;

Parameters

Parameter	Type
index	number

Returns

boolean

canSubmit()

canSubmit(): boolean;

Returns

boolean

check()

check(page?): Promise<CheckResponse>;

Practice only. Grades everything, or one view page. A second call while checking joins the first.

Parameters

Parameter	Type
page?	string

Returns

Promise<CheckResponse>

emptySlots()

emptySlots(page?): string[];

Slot ids without an answer, on one page or on all of them.

Parameters

Parameter	Type
page?	number

Returns

string[]

goTo()

goTo(index): boolean;

Parameters

Parameter	Type
index	number

Returns

boolean

next()

next(): boolean;

Returns

boolean

previous()

previous(): boolean;

Returns

boolean

reset()

reset(): boolean;

Clears answers and the last result and goes back to the first page. Not after submitting.

Returns

boolean

restorable()

static restorable(snapshot, viewHash): Snapshot | null;

The snapshot when it is valid and belongs to the view (viewHash null or equal), else null.

Parameters

Parameter	Type
snapshot	unknown
viewHash	string | null

Returns

Snapshot | null

setAnswers()

setAnswers(partial): Answers;

Applies a partial update ('' deletes) and returns the slots that actually changed. Unknown ids are ignored.

Parameters

Parameter	Type
partial	Answers

Returns

Answers

snapshot()

snapshot(ui?): Snapshot;

Parameters

Parameter	Type
ui?	Readonly<Record<string, JsonValue>>

Returns

Snapshot

start()

start(): void;

ready -> active. Called implicitly by the first answer, check or submit.

Returns

void

submit()

submit(): Promise<SubmitResponse>;

Final. Waits for a running check first; a second call while submitting joins the first.

Returns

Promise<SubmitResponse>

subscribe()

subscribe(listener): () => void;

Parameters

Parameter	Type
listener	AttemptListener

Returns

() => void

timeLeft()

timeLeft(): number | null;

Milliseconds to the policy deadline (0 when past it); null without a deadline.

Returns

number | null

---

abstract SingleSlotElement

An element with exactly one slot whose id is the element id (a gap, a single choice, a slider).

Extends

• AstlElement

Constructors

Constructor

new SingleSlotElement(): SingleSlotElement;

Returns

SingleSlotElement

Overrides

AstlElement.constructor

Properties

Property	Modifier	Type	Default value	Description
disabled	public	boolean	undefined	-
feedback	public	| ElementFeedback | null	undefined	Verdicts to show; null clears them. Editing a slot clears its own verdict and the group verdict.
manifest	static	| ComponentManifest | null	null	The element type's manifest: drives the typed attribute getters and the default message namespace.
messages	static	readonly MessageCatalog[]	[]	Catalogs of the manifest's namespace, used until a player attaches its own context.
solution	public	Readonly<Record<string, string>> | null	undefined	Correct answers to show next to the student's; null hides them.

Accessors

context

Get Signature

get context(): ElementContext;

The player's context, or the default English one.

Returns

ElementContext

Inherited from

AstlElement.context

slotIds

Get Signature

get slotIds(): readonly string[];

Slot ids this element answers, in reading order. Stable after the element connects.

Returns

readonly string[]

Slot ids this element answers, in reading order. Stable after the element connects.

Overrides

AstlElement.slotIds

Methods

attach()

attach(context): void;

Called by the player once, before the first render. Elements must work with a default context too.

Parameters

Parameter	Type
context	ElementContext

Returns

void

Inherited from

AstlElement.attach

getAnswers()

getAnswers(): Answers;

Answered slots only.

Returns

Answers

Overrides

AstlElement.getAnswers

setAnswers()

setAnswers(answers): void;

Unknown ids are ignored; '' clears a slot. Does not fire a change event.

Parameters

Parameter	Type
answers	Answers

Returns

void

Overrides

AstlElement.setAnswers

units()

units(): Units;

Progress units, e.g. 3 of 5 cards placed.

Returns

Units

Overrides

AstlElement.units

Interfaces

AttemptControllerOptions

Properties

Property	Modifier	Type	Description
checker	readonly	Checker	-
now?	readonly	() => number	Clock in milliseconds, for deadlines and savedAt. Default Date.now.
pages	readonly	readonly AttemptPage[]	-
policy	readonly	AttemptPolicy	-
snapshot?	readonly	Snapshot | null	Restored when it is valid and its viewHash is null or equals viewHash.
viewHash?	readonly	string | null	Hash of the view the attempt runs on; written into snapshots.

---

AttemptPage

Properties

Property	Modifier	Type	Description
id	readonly	string	View page id.
slotIds	readonly	readonly string[]	Slots answered on this page, in reading order.

---

DefinePlayerOptions

Properties

Property	Modifier	Type	Description
catalogs?	readonly	readonly MessageCatalog[]	More or overriding catalogs (any namespace), e.g. another UI locale.
compileSource?	readonly	SourceCompiler	Enables light-DOM sources (HTML with answers).
elements	readonly	readonly ElementEntry[]	Component elements: a registration is defined right away, a LazyElement the first time a view contains its tag.
registry?	readonly	CustomElementRegistry	Default: the global customElements.
styleTemplates?	readonly	readonly StyleTemplate[]	Looks that exercises can pick with style-template on <astl-doc> or on a component, and hosts with <astl-player style-template> (trusted, like the host's own CSS).
urlPolicy?	readonly	UrlPolicy	Which URLs of a view stay when the player mounts it (links, pictures, url attributes): the same policy as the engine that compiled the views (createEngine({ urlPolicy })), or the player removes what the engine kept. Default isSafeUrl. One policy for every player of the page: the last call that passes one sets it. An address stays only when the policy answers true (one that throws blocks it).

---

ElementRegistration

One component element type for the player: its manifest, element class and message catalogs.

Properties

Property	Modifier	Type
element	readonly	CustomElementConstructor
manifest	readonly	ComponentManifest
messages	readonly	readonly MessageCatalog[]

---

HttpCheckerOptions

Properties

Property	Modifier	Type	Description
credentials?	readonly	RequestCredentials	Fetch credentials mode (cookies). Default: the browser default (same-origin).
endpoint	readonly	string	URL of one attempt, e.g. /api/attempts/123; /check and /submit are appended.
fetch?	readonly	(input, init) => Promise<Response>	Fetch implementation, for tests or instrumented clients. Default: the global fetch.
headers?	readonly	Readonly<Record<string, string>>	Extra request headers, e.g. Authorization.

---

LazyElement

Imported the first time a view mounted by contains tag; resolves to that tag's registration.

Properties

Property	Modifier	Type
load	readonly	() => Promise<ElementRegistration>
tag	readonly	string

---

LoadInput

What load() accepts; omitted fields keep the player's current properties.

Properties

Property	Modifier	Type
checker?	readonly	Checker | null
policy?	readonly	AttemptPolicy
snapshot?	readonly	Snapshot | null
view	readonly	string

---

VerdictOptions

Properties

Property	Modifier	Type	Description
dir?	readonly	"ltr" | "rtl"	-
hiddenWord?	readonly	boolean	Hide the word visually (it stays readable, e.g. through aria-describedby).
id?	readonly	string	id of the word element, for aria-describedby.
lang?	readonly	string	UI language and direction of the word. Pass the context locale: the word is UI text, and inside content of another language it would otherwise be read with the content's voice and bidi rules.
part?	readonly	string	part name of the wrapper.

Type Aliases

AttemptChange

type AttemptChange =
  | {
  previous: AttemptState;
  state: AttemptState;
  type: "state";
}
  | {
  answers: Answers;
  type: "answers";
}
  | {
  index: number;
  previous: number;
  type: "page";
}
  | {
  response:   | CheckResponse
     | SubmitResponse;
  type: "result";
}
  | {
  type: "reset";
};

Union Members

Type Literal

{
  previous: AttemptState;
  state: AttemptState;
  type: "state";
}

---

Type Literal

{
  answers: Answers;
  type: "answers";
}

Only the slots that changed; '' = cleared.

---

Type Literal

{
  index: number;
  previous: number;
  type: "page";
}

---

Type Literal

{
  response:   | CheckResponse
     | SubmitResponse;
  type: "result";
}

---

Type Literal

{
  type: "reset";
}

---

AttemptListener

type AttemptListener = (change) => void;

Parameters

Parameter	Type
change	AttemptChange

Returns

void

---

ElementEntry

type ElementEntry =
  | ElementRegistration
  | LazyElement;

A component element for the player: registered right away, or lazily on first use.

---

Verdict

type Verdict = GroupVerdict;

Slot verdicts (correct, incorrect) are a subset of group verdicts.

Variables

PLAYER_NAMESPACE

const PLAYER_NAMESPACE: "astl.player" = 'astl.player';

i18n namespace of the player chrome and of strings shared by all elements (verdict words).

---

playerMessages

const playerMessages: readonly MessageCatalog[];

---

verdictStyles

const verdictStyles: CSSResult;

Verdict styling. [data-verdict] sets --astl-verdict-color, --astl-verdict-soft and --astl-verdict-border (solid = correct, double = partial, dashed = incorrect, dotted = empty) for borders of the element that carries it.

---

visuallyHidden

const visuallyHidden: CSSResult;

.astl-vh: hidden on screen, still read by screen readers.

Functions

announce()

function announce(region, message): void;

Puts a message into a polite live region. The region is emptied first and filled in a later task, so screen readers also announce a message that repeats the previous one.

Parameters

Parameter	Type
region	HTMLElement
message	string

Returns

void

---

definePlayer()

function definePlayer(options): void;

Defines <astl-player> and the given elements, and registers style templates. Safe to call again: a tag already defined by the same class, a lazy element with the same load, or a template already registered as the same object is skipped. A tag taken by another class, by another loader or by the other kind of entry (eager or lazy), or a template name taken by another template, throws (two copies of a bundle would otherwise mix silently).

Parameters

Parameter	Type
options	DefinePlayerOptions

Returns

void

---

httpChecker()

function httpChecker(options): Checker;

Parameters

Parameter	Type
options	HttpCheckerOptions

Returns

Checker

---

renderVerdict()

function renderVerdict(
   verdict,
   t,
   options?
): TemplateResult;

Icon + word (verdict.* messages, e.g. "Dobrze", "Jeszcze nie") inside a [data-verdict] wrapper.

Parameters

Parameter	Type
verdict	GroupVerdict
t	Translate
options?	VerdictOptions

Returns

TemplateResult

---

seededShuffle()

function seededShuffle<T>(items, seed): T[];

Deterministic Fisher-Yates shuffle: the same seed always gives the same order.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
items	readonly T[]
seed	string

Returns

T[]

---

verdictIcon()

function verdictIcon(verdict): TemplateResult;

A decorative icon per verdict (hidden from assistive technology: the word carries the meaning).

Parameters

Parameter	Type
verdict	GroupVerdict

Returns

TemplateResult