@pie-players/pie-default-tool-loaders 1.0.0-beta.0 → 1.0.0-beta.2

package/README.md

@@ -17,6 +17,7 @@ capability id. A support id is the tool id a profile grants.
 | `PACKAGED_TOOL_TAG_MAP` | Which custom element each one renders as |
 | `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` | Where they appear and in what order |
 | `createUniversalPersonalNeedsProfile`, `createEmptyPersonalNeedsProfile` | Which of them the program grants to everyone, or to no one |
+| `createPersonalNeedsProfileFromAfa` | Which of them a student's AfA PNP 3.0 record grants, prohibits and turns on at start, and with which settings |
 | `DEFAULT_TOOL_MODULE_LOADERS` | When each one's bundle loads |
 | `CONTENT_ALTERNATE_REGISTRATIONS` | Which of them carry an authored alternate that renders as a region; the print player mounts these |
 
@@ -159,6 +160,25 @@ An assessment carrying no profile is left alone. `pnpEnforcement`
 auto-detection engages only on host policy material, so with no profile,
 placement alone decides which tools appear.
 
+## AfA profiles
+
+`createPersonalNeedsProfileFromAfa(record)` builds a fresh profile from a
+student's AfA PNP 3.0 record, held as JSON keyed by the spec's terms. Features
+become support ids in the packaged set's names, the activation sets fill
+`activateAtInit` and `prohibitedSupports`, and the settings the packaged tools
+read become `toolParameters`: read-aloud speed, pitch and volume, the calculator
+type and the sign language. The toolkit's PNP configuration guide gives each AfA
+feature's disposition.
+
+```ts
+import { createPersonalNeedsProfileFromAfa } from "@pie-players/pie-default-tool-loaders";
+
+sectionPlayer.assessment = {
+	...authoredAssessment,
+	personalNeedsProfile: createPersonalNeedsProfileFromAfa(afaRecord),
+};
+```
+
 ## Packaged capability composition
 
 The exports are projections of one internal composition. Each packaged

package/dist/afa-profile.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The AfA PNP 3.0 adapter: an AfA record, as JSON keyed by the spec's
+ * kebab-case terms, becomes the toolkit's personal-needs profile.
+ *
+ * Each feature the record names is a support id, the term camelCased, except
+ * where a packaged tool carries the capability under an id of its own
+ * (`TOOL_REGISTRY.md`, Support ids). `spoken` resolves by its `reading-type`:
+ * `computer-read-aloud` is `textToSpeech`, and `screen-reader`, AfA's default,
+ * is `screenReader` (ADR 0004). `extensions` and the resource-matching
+ * preferences name no support and are skipped.
+ *
+ * A feature at the record's root or in `activate-as-option-set` is granted, one
+ * in `activate-at-initialization-set` is granted and on at start, and one in
+ * `prohibit-set` is prohibited, which withdraws it from both. The settings of
+ * a feature a packaged tool reads become that tool's `toolParameters`.
+ */
+import type { PersonalNeedsProfile } from "@pie-players/pie-players-shared/types";
+/** `spoken`'s settings, in AfA's units. */
+export interface AfaSpoken {
+    "reading-type"?: "screen-reader" | "computer-read-aloud";
+    /** Words per minute; AfA's default is 180. */
+    "speech-rate"?: number;
+    /** 0–1; AfA's default is 0.5. */
+    pitch?: number;
+    /** 0–1; AfA's default is 0.5. */
+    volume?: number;
+    [setting: string]: unknown;
+}
+/** A set's features: empty elements keyed by feature, or the feature names. */
+export type AfaFeatureSet = Readonly<Record<string, unknown>> | readonly string[];
+/** An AfA PNP 3.0 record in JSON. A feature is present unless absent, `null` or `false`. */
+export interface AfaPnpRecord {
+    spoken?: AfaSpoken;
+    "calculator-on-screen"?: {
+        "calculator-type"?: string;
+        [setting: string]: unknown;
+    };
+    "sign-language"?: {
+        language?: string;
+        [setting: string]: unknown;
+    };
+    "activate-at-initialization-set"?: AfaFeatureSet;
+    "activate-as-option-set"?: AfaFeatureSet;
+    "prohibit-set"?: AfaFeatureSet;
+    [feature: string]: unknown;
+}
+/** A fresh profile carrying `record`'s grants, prohibitions and settings, ids sorted. */
+export declare function createPersonalNeedsProfileFromAfa(record: AfaPnpRecord): PersonalNeedsProfile;

package/dist/afa-profile.js

@@ -0,0 +1,117 @@
+/**
+ * The AfA PNP 3.0 adapter: an AfA record, as JSON keyed by the spec's
+ * kebab-case terms, becomes the toolkit's personal-needs profile.
+ *
+ * Each feature the record names is a support id, the term camelCased, except
+ * where a packaged tool carries the capability under an id of its own
+ * (`TOOL_REGISTRY.md`, Support ids). `spoken` resolves by its `reading-type`:
+ * `computer-read-aloud` is `textToSpeech`, and `screen-reader`, AfA's default,
+ * is `screenReader` (ADR 0004). `extensions` and the resource-matching
+ * preferences name no support and are skipped.
+ *
+ * A feature at the record's root or in `activate-as-option-set` is granted, one
+ * in `activate-at-initialization-set` is granted and on at start, and one in
+ * `prohibit-set` is prohibited, which withdraws it from both. The settings of
+ * a feature a packaged tool reads become that tool's `toolParameters`.
+ */
+const RENAMED_FEATURES = {
+    "calculator-on-screen": "calculator",
+    "answer-masking": "answerEliminator",
+    "dictionary-on-screen": "dictionary",
+};
+/**
+ * Keys that name no support: the sets, `extensions`, and the preferences that
+ * select among adapted resources by metadata PIE content does not carry. The
+ * interface language is the host's `locale`.
+ */
+const NON_SUPPORT_KEYS = new Set([
+    "activate-at-initialization-set",
+    "activate-as-option-set",
+    "prohibit-set",
+    "extensions",
+    "access-mode-required",
+    "adaptation-type-required",
+    "at-interoperable",
+    "educational-complexity-of-adaptation",
+    "hazard-avoidance",
+    "input-requirements",
+    "language-of-adaptation",
+    "language-of-interface",
+    "adaptation-detail-required",
+    "adaptation-media-required",
+    "educational-level-of-adaptation",
+]);
+/** AfA's `standard` calculator has no PIE type, so it keeps the tool's default. */
+const CALCULATOR_TYPES = new Set(["basic", "scientific", "graphing"]);
+/** AfA's default `speech-rate`, which PIE's normal speed 1 stands for. */
+const AFA_NORMAL_SPEECH_RATE = 180;
+const isPresent = (value) => value !== undefined && value !== null && value !== false;
+const finiteNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+const camelCase = (term) => term.replace(/-([a-z0-9])/g, (_, next) => next.toUpperCase());
+function featureNames(set) {
+    if (!set)
+        return [];
+    const names = Array.isArray(set)
+        ? set.filter((name) => typeof name === "string")
+        : Object.entries(set)
+            .filter(([, value]) => isPresent(value))
+            .map(([name]) => name);
+    return names.filter((name) => !NON_SUPPORT_KEYS.has(name));
+}
+function spokenParameters(spoken) {
+    const speechRate = finiteNumber(spoken["speech-rate"]);
+    const pitch = finiteNumber(spoken.pitch);
+    const volume = finiteNumber(spoken.volume);
+    return {
+        ...(speechRate !== undefined && speechRate > 0
+            ? { rate: speechRate / AFA_NORMAL_SPEECH_RATE }
+            : {}),
+        ...(pitch !== undefined ? { pitch: pitch * 2 } : {}),
+        ...(volume !== undefined ? { volume } : {}),
+    };
+}
+/** A fresh profile carrying `record`'s grants, prohibitions and settings, ids sorted. */
+export function createPersonalNeedsProfileFromAfa(record) {
+    const spoken = typeof record.spoken === "object" && record.spoken !== null
+        ? record.spoken
+        : {};
+    const readAloud = spoken["reading-type"] === "computer-read-aloud";
+    const supportId = (feature) => feature === "spoken"
+        ? readAloud
+            ? "textToSpeech"
+            : "screenReader"
+        : (RENAMED_FEATURES[feature] ?? camelCase(feature));
+    // PIE cannot withhold a screen reader, so a prohibited `spoken` withholds
+    // the spoken presentation PIE makes, read-aloud.
+    const prohibited = new Set(featureNames(record["prohibit-set"]).map((feature) => feature === "spoken" ? "textToSpeech" : supportId(feature)));
+    const admitted = (ids) => [...new Set(ids)].filter((id) => !prohibited.has(id)).sort();
+    const activateAtInit = admitted(featureNames(record["activate-at-initialization-set"]).map(supportId));
+    const supports = admitted([
+        ...featureNames(record).map(supportId),
+        ...featureNames(record["activate-as-option-set"]).map(supportId),
+        ...activateAtInit,
+    ]);
+    const toolParameters = {};
+    if (readAloud) {
+        const speech = spokenParameters(spoken);
+        if (Object.keys(speech).length > 0) {
+            toolParameters.textToSpeech = speech;
+        }
+    }
+    const calculatorType = record["calculator-on-screen"]?.["calculator-type"];
+    if (calculatorType && CALCULATOR_TYPES.has(calculatorType)) {
+        toolParameters.calculator = {
+            type: calculatorType,
+        };
+    }
+    const signLang = record["sign-language"]?.language;
+    if (typeof signLang === "string" && signLang.length > 0) {
+        toolParameters.signLanguage = { signLang };
+    }
+    return {
+        supports,
+        prohibitedSupports: [...prohibited].sort(),
+        ...(activateAtInit.length > 0 ? { activateAtInit } : {}),
+        ...(Object.keys(toolParameters).length > 0 ? { toolParameters } : {}),
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { PackagedToolRegistryOptions } from "./packaged-capability-composition.js";
 export { createEmptyPersonalNeedsProfile, createPackagedToolRegistry, createUniversalPersonalNeedsProfile, DEFAULT_TOOL_MODULE_LOADERS, PACKAGED_TOOL_REGISTRATIONS, PACKAGED_TOOL_TAG_MAP, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./packaged-capability-composition.js";
+export { type AfaFeatureSet, type AfaPnpRecord, type AfaSpoken, createPersonalNeedsProfileFromAfa, } from "./afa-profile.js";
 export { CONTENT_ALTERNATE_REGISTRATIONS } from "./content-alternates.js";
 export { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
 export { AUDIO_TRANSCRIPT_FEATURE_ID, AUDIO_TRANSCRIPT_REGION_CLASS, AUDIO_TRANSCRIPT_REGION_LABEL, audioTranscriptRegistration, CONTENT_LEAD_SURFACE, resolveAudioTranscript, type ResolvedAudioTranscript, } from "./registrations/audio-transcript.js";

package/dist/index.js

@@ -1,4 +1,6 @@
 export { createEmptyPersonalNeedsProfile, createPackagedToolRegistry, createUniversalPersonalNeedsProfile, DEFAULT_TOOL_MODULE_LOADERS, PACKAGED_TOOL_REGISTRATIONS, PACKAGED_TOOL_TAG_MAP, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./packaged-capability-composition.js";
+// A profile from an AfA PNP 3.0 record, in the packaged set's support ids.
+export { createPersonalNeedsProfileFromAfa, } from "./afa-profile.js";
 // The authored-alternate subset, for a renderer that shows alternates and no
 // toolbar — importable without the packaged composition's tool loaders.
 export { CONTENT_ALTERNATE_REGISTRATIONS } from "./content-alternates.js";

package/dist/registrations/interaction-tools.d.ts

@@ -9,6 +9,6 @@ import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools
  * Answer Eliminator tool registration
  *
  * Allows students to strike through incorrect answer choices.
- * Only appears on multiple-choice style questions.
+ * Only appears on items with an element that supports answer masking.
  */
 export declare const answerEliminatorToolRegistration: ToolRegistration;

package/dist/registrations/interaction-tools.js

@@ -4,12 +4,40 @@
  * Registers tools for interacting with question content:
  * - Answer Eliminator (strike through answer choices)
  */
-import { hasChoiceInteraction } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { elementSupports } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { createToolElement, } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { resolveOverlayElement } from "./overlay-element-cache.js";
 /** The policy parameters' `strategy`, defaulting to strikethrough. */
 const normalizeEliminationStrategy = (value) => value === "mask" ? "mask" : "strikethrough";
+/** The AfA PNP 3.0 support term an element declares to take the eliminator. */
+const ANSWER_MASKING = "answer-masking";
+/**
+ * pie-item contract compatibility: legacy pie-elements, and pie-elements-ng
+ * releases from before elements declared their supports, render the markup the
+ * eliminator's built-in adapters read for these two. An element that declares
+ * its supports is decided by its declaration, these two included.
+ */
+const UNDECLARED_ANSWER_MASKING_ELEMENTS = new Set(["multiple-choice", "ebsr"]);
+// Content names one element several ways: `multiple-choice`,
+// `pie-multiple-choice`, `pie-element-multiple-choice`, a runtime `--version-*`
+// tag, or any tag the item's `elements` map binds to `@pie-element/multiple-choice`.
+function isUndeclaredAnswerMaskingElement(tag, packageSpec) {
+    const name = tag
+        .toLowerCase()
+        .replace(/--version-[0-9a-z-]+$/, "")
+        .replace(/^pie-(element-)?/, "");
+    if (UNDECLARED_ANSWER_MASKING_ELEMENTS.has(name))
+        return true;
+    const packageName = packageSpec?.match(/^@pie-element\/([^@]+)/)?.[1];
+    return !!packageName && UNDECLARED_ANSWER_MASKING_ELEMENTS.has(packageName);
+}
+/** Whether an element of the context supports answer masking. */
+function supportsAnswerMasking(context) {
+    return elementSupports(context).some(({ supports, tag, packageSpec }) => supports
+        ? supports.includes(ANSWER_MASKING)
+        : isUndeclaredAnswerMaskingElement(tag, packageSpec));
+}
 /** The state-store key of each PIE element in the item, by model id. */
 function resolveElementStateKeys(context, toolbarContext) {
     const keys = {};
@@ -29,7 +57,7 @@ function resolveElementStateKeys(context, toolbarContext) {
  * Answer Eliminator tool registration
  *
  * Allows students to strike through incorrect answer choices.
- * Only appears on multiple-choice style questions.
+ * Only appears on items with an element that supports answer masking.
  */
 export const answerEliminatorToolRegistration = {
     toolId: "answerEliminator",
@@ -40,21 +68,22 @@ export const answerEliminatorToolRegistration = {
     icon: "strikethrough",
     supportedLevels: ["item"],
     /**
-     * Pass 2: Answer eliminator is relevant only for choice-based questions
+     * Pass 2: relevant where an element supports answer masking. An element
+     * declares it on its class, and the answer eliminator's README says what the
+     * element then supplies.
      */
     isVisibleInContext(context) {
-        return hasChoiceInteraction(context);
+        return supportsAnswerMasking(context);
     },
     /**
      * Pass 3: the same question, asked as a capability. Elimination controls are
-     * rendered per choice, so an item with no choice interaction gives this tool
-     * nothing to act on — `placement-ordering`, `categorize` and
-     * `drag-in-the-blank` included, whose `choices` hold draggables the
-     * eliminator cannot reach. Answering the relevance gate alone left the button
-     * on those items for any learner whose profile grants answer masking.
+     * rendered per choice, so an item none of whose elements supports answer
+     * masking gives this tool nothing to act on. Answering the relevance gate
+     * alone left the button on such items for any learner whose profile grants
+     * answer masking.
      */
     isApplicableToContent(context) {
-        return hasChoiceInteraction(context);
+        return supportsAnswerMasking(context);
     },
     renderToolbar(context, toolbarContext) {
         const visibility = createScopedVisibilityBinding(this.toolId, toolbarContext);

package/dist/registrations/tts.js

@@ -11,6 +11,7 @@ import { resolveOverlayElement } from "./overlay-element-cache.js";
 // This package owns the server adapter's import, so the toolkit never names it
 // and a bundler building the toolkit alone has nothing to resolve.
 const loadServerTTSProvider = async () => (await import("@pie-players/tts-client-server")).ServerTTSProvider;
+const numberOrUndefined = (value) => typeof value === "number" ? value : undefined;
 /**
  * Text-to-Speech tool registration
  *
@@ -80,6 +81,11 @@ export const ttsToolRegistration = {
             element.speedOptions = resolveElementSpeedOptions();
             element.showSingleSpeedOption =
                 resolveRuntimeSettings().showSingleSpeedOption === true;
+            // The element range-checks these; a non-number means the default.
+            const speech = toolbarContext.getToolParameters?.("textToSpeech");
+            element.baseRate = numberOrUndefined(speech?.rate);
+            element.pitch = numberOrUndefined(speech?.pitch);
+            element.volume = numberOrUndefined(speech?.volume);
         };
         applyAttributes();
         const hostLayout = resolveTTSHostToolbarLayout(resolveRuntimeSettings());

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-default-tool-loaders",
-	"version": "1.0.0-beta.0",
+	"version": "1.0.0-beta.2",
 	"type": "module",
 	"description": "Composition layer for the packaged PIE assessment tools: registrations, tag map, placement preset, universal and empty profiles, and lazy module loaders",
 	"repository": {
@@ -33,25 +33,25 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@pie-players/pie-assessment-toolkit": "1.0.0-beta.0",
-		"@pie-players/pie-calculator": "1.0.0-beta.0",
-		"@pie-players/pie-calculator-cortex": "1.0.0-beta.0",
-		"@pie-players/pie-calculator-desmos": "1.0.0-beta.0",
-		"@pie-players/pie-calculator-geogebra": "1.0.0-beta.0",
-		"@pie-players/pie-players-shared": "1.0.0-beta.0",
-		"@pie-players/pie-tool-annotation-toolbar": "1.0.0-beta.0",
-		"@pie-players/pie-tool-answer-eliminator": "1.0.0-beta.0",
-		"@pie-players/pie-tool-calculator-shared": "1.0.0-beta.0",
-		"@pie-players/pie-tool-dictionary": "1.0.0-beta.0",
-		"@pie-players/pie-tool-graph": "1.0.0-beta.0",
-		"@pie-players/pie-tool-line-reader": "1.0.0-beta.0",
-		"@pie-players/pie-tool-periodic-table": "1.0.0-beta.0",
-		"@pie-players/pie-tool-picture-dictionary": "1.0.0-beta.0",
-		"@pie-players/pie-tool-protractor": "1.0.0-beta.0",
-		"@pie-players/pie-tool-ruler": "1.0.0-beta.0",
-		"@pie-players/pie-tool-theme": "1.0.0-beta.0",
-		"@pie-players/pie-tool-tts-inline": "1.0.0-beta.0",
-		"@pie-players/tts-client-server": "1.0.0-beta.0"
+		"@pie-players/pie-assessment-toolkit": "1.0.0-beta.2",
+		"@pie-players/pie-calculator": "1.0.0-beta.2",
+		"@pie-players/pie-calculator-cortex": "1.0.0-beta.2",
+		"@pie-players/pie-calculator-desmos": "1.0.0-beta.2",
+		"@pie-players/pie-calculator-geogebra": "1.0.0-beta.2",
+		"@pie-players/pie-players-shared": "1.0.0-beta.2",
+		"@pie-players/pie-tool-annotation-toolbar": "1.0.0-beta.2",
+		"@pie-players/pie-tool-answer-eliminator": "1.0.0-beta.2",
+		"@pie-players/pie-tool-calculator-shared": "1.0.0-beta.2",
+		"@pie-players/pie-tool-dictionary": "1.0.0-beta.2",
+		"@pie-players/pie-tool-graph": "1.0.0-beta.2",
+		"@pie-players/pie-tool-line-reader": "1.0.0-beta.2",
+		"@pie-players/pie-tool-periodic-table": "1.0.0-beta.2",
+		"@pie-players/pie-tool-picture-dictionary": "1.0.0-beta.2",
+		"@pie-players/pie-tool-protractor": "1.0.0-beta.2",
+		"@pie-players/pie-tool-ruler": "1.0.0-beta.2",
+		"@pie-players/pie-tool-theme": "1.0.0-beta.2",
+		"@pie-players/pie-tool-tts-inline": "1.0.0-beta.2",
+		"@pie-players/tts-client-server": "1.0.0-beta.2"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.15",