@longsightgroup/qti3-player 0.2.1 → 0.3.0

package/src/content/content-dom.ts

@@ -0,0 +1,274 @@
+import type { QtiContentNode, QtiValue } from "@longsightgroup/qti3-core";
+
+const htmlContentElements = new Set([
+  "a",
+  "abbr",
+  "b",
+  "bdi",
+  "bdo",
+  "blockquote",
+  "br",
+  "caption",
+  "cite",
+  "code",
+  "dd",
+  "dfn",
+  "div",
+  "dl",
+  "dt",
+  "em",
+  "figcaption",
+  "figure",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "hr",
+  "i",
+  "img",
+  "kbd",
+  "li",
+  "ol",
+  "p",
+  "pre",
+  "q",
+  "rb",
+  "rbc",
+  "rp",
+  "rt",
+  "rtc",
+  "ruby",
+  "samp",
+  "small",
+  "span",
+  "strong",
+  "sub",
+  "sup",
+  "table",
+  "tbody",
+  "td",
+  "tfoot",
+  "th",
+  "thead",
+  "tr",
+  "ul",
+  "var",
+]);
+
+export const unsafeContentElements = new Set(["script", "style"]);
+
+const mathMlElements = new Set([
+  "math",
+  "maction",
+  "maligngroup",
+  "malignmark",
+  "menclose",
+  "merror",
+  "mfenced",
+  "mfrac",
+  "mglyph",
+  "mi",
+  "mlabeledtr",
+  "mlongdiv",
+  "mmultiscripts",
+  "mn",
+  "mo",
+  "mover",
+  "mpadded",
+  "mphantom",
+  "mroot",
+  "mrow",
+  "ms",
+  "mscarries",
+  "mscarry",
+  "msgroup",
+  "msline",
+  "mspace",
+  "msqrt",
+  "msrow",
+  "mstack",
+  "mstyle",
+  "msub",
+  "msubsup",
+  "msup",
+  "mtable",
+  "mtd",
+  "mtext",
+  "mtr",
+  "munder",
+  "munderover",
+  "semantics",
+]);
+
+export function contentElementName(qtiName: string): string | undefined {
+  if (qtiName === "qti-content-body" || qtiName === "qti-prompt") return undefined;
+  if (htmlContentElements.has(qtiName) || mathMlElements.has(qtiName)) return qtiName;
+  if (qtiName === "object") return "object";
+  if (qtiName === "qti-rubric-block") return "section";
+  if (qtiName === "qti-template-block") return "div";
+  if (qtiName === "qti-template-inline") return "span";
+  return undefined;
+}
+
+export function createContentElement(name: string): HTMLElement | MathMLElement {
+  if (mathMlElements.has(name)) {
+    return document.createElementNS("http://www.w3.org/1998/Math/MathML", name) as MathMLElement;
+  }
+  return document.createElement(name);
+}
+
+export function copySafeAttributes(element: Element, attributes: Record<string, string>): void {
+  for (const [name, value] of Object.entries(attributes)) {
+    if (!isSafeContentAttribute(name, value)) continue;
+    element.setAttribute(name, value);
+    if (name === "xml:lang" && !Object.hasOwn(attributes, "lang")) {
+      element.setAttribute("lang", value);
+    }
+  }
+  applySharedAccessibilityVocabulary(element, attributes);
+}
+
+export function applySharedAccessibilityVocabulary(
+  element: Element,
+  attributes: Record<string, string>,
+): void {
+  for (const [name, value] of Object.entries(attributes)) {
+    const ariaName = qtiAriaAttributeName(name);
+    if (!ariaName || hasAttributeName(attributes, ariaName)) continue;
+    element.setAttribute(ariaName, value);
+  }
+
+  const suppressTts = attributeValue(attributes, "data-qti-suppress-tts");
+  if (
+    suppressesScreenReaderSpeech(suppressTts) &&
+    !hasAttributeName(attributes, "aria-hidden") &&
+    !hasAttributeName(attributes, "data-qti-aria-hidden")
+  ) {
+    element.setAttribute("aria-hidden", "true");
+  }
+}
+
+function qtiAriaAttributeName(name: string): string | undefined {
+  const normalizedName = name.toLowerCase();
+  const prefix = "data-qti-aria-";
+  if (!normalizedName.startsWith(prefix)) return undefined;
+  const suffix = normalizedName.slice(prefix.length);
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(suffix)) return undefined;
+  return `aria-${suffix}`;
+}
+
+function attributeValue(attributes: Record<string, string>, name: string): string | undefined {
+  const normalizedName = name.toLowerCase();
+  const entry = Object.entries(attributes).find(
+    ([attributeName]) => attributeName.toLowerCase() === normalizedName,
+  );
+  return entry?.[1];
+}
+
+function hasAttributeName(attributes: Record<string, string>, name: string): boolean {
+  return attributeValue(attributes, name) !== undefined;
+}
+
+function suppressesScreenReaderSpeech(value: string | undefined): boolean {
+  if (!value) return false;
+  const tokens = value
+    .toLowerCase()
+    .split(/[\s,]+/)
+    .filter(Boolean);
+  return tokens.includes("all") || tokens.includes("screen-reader");
+}
+
+function isSafeContentAttribute(name: string, value: string): boolean {
+  const normalizedName = name.toLowerCase();
+  if (normalizedName.startsWith("on")) return false;
+  if (normalizedName === "style") return false;
+  if (normalizedName === "href" || normalizedName === "src" || normalizedName === "data") {
+    return isSafeUrl(value);
+  }
+  return (
+    normalizedName === "alt" ||
+    normalizedName === "class" ||
+    normalizedName === "colspan" ||
+    normalizedName === "dir" ||
+    normalizedName === "headers" ||
+    normalizedName === "height" ||
+    normalizedName === "id" ||
+    normalizedName === "lang" ||
+    normalizedName === "role" ||
+    normalizedName === "rowspan" ||
+    normalizedName === "scope" ||
+    normalizedName === "title" ||
+    normalizedName === "type" ||
+    normalizedName === "width" ||
+    normalizedName === "xml:lang" ||
+    mathMlAttributeNames.has(normalizedName) ||
+    normalizedName.startsWith("aria-") ||
+    normalizedName.startsWith("data-")
+  );
+}
+
+const mathMlAttributeNames = new Set([
+  "accent",
+  "accentunder",
+  "align",
+  "columnalign",
+  "display",
+  "fence",
+  "largeop",
+  "lspace",
+  "mathbackground",
+  "mathcolor",
+  "mathsize",
+  "mathvariant",
+  "movablelimits",
+  "rowalign",
+  "rspace",
+  "separator",
+  "stretchy",
+]);
+
+export function isSafeUrl(value: string): boolean {
+  return (
+    value.startsWith("#") ||
+    value.startsWith("/") ||
+    value.startsWith("./") ||
+    value.startsWith("../") ||
+    value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    value.startsWith("data:image/") ||
+    value.startsWith("data:audio/") ||
+    value.startsWith("data:video/")
+  );
+}
+
+export function isResolvableAssetUrl(value: string): boolean {
+  return (
+    !value.startsWith("#") &&
+    !value.startsWith("data:") &&
+    !value.startsWith("blob:") &&
+    !value.startsWith("http://") &&
+    !value.startsWith("https://")
+  );
+}
+
+export function formatPrintedValue(value: QtiValue, format?: string): string {
+  if (value === null || value === undefined) return "";
+  const numericValue =
+    typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+  if (Number.isFinite(numericValue) && format) {
+    const fixed = /^%\.(\d+)f$/.exec(format);
+    if (fixed) return numericValue.toFixed(Number(fixed[1]));
+    if (format === "%d" || format === "%i") return String(Math.trunc(numericValue));
+  }
+  if (Array.isArray(value)) return value.map((item) => String(item)).join(", ");
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
+
+export function contentNodeText(node: QtiContentNode): string {
+  if (node.kind === "text") return node.text;
+  if ("children" in node) return node.children.map(contentNodeText).join("");
+  return "";
+}

package/src/content/content-renderer.ts

@@ -0,0 +1,114 @@
+import type { QtiContentNode, QtiInteraction, QtiValue } from "@longsightgroup/qti3-core";
+import {
+  contentElementName,
+  copySafeAttributes,
+  createContentElement,
+  formatPrintedValue,
+  unsafeContentElements,
+} from "./content-dom.js";
+
+export interface PlayerContentContext {
+  interactionAt(index: number): QtiInteraction | undefined;
+  renderBlockInteraction(interaction: QtiInteraction): HTMLElement;
+  renderEmbeddedInteraction(interaction: QtiInteraction): HTMLElement;
+  currentVariableValue(identifier: string): QtiValue;
+  mathTemplateValue(node: Extract<QtiContentNode, { kind: "element" }>): string | undefined;
+  isFeedbackVisible(node: Extract<QtiContentNode, { kind: "feedback" }>): boolean;
+  isTemplateContentVisible(element: HTMLElement): boolean;
+}
+
+export function renderContentNodes(nodes: QtiContentNode[], context: PlayerContentContext): Node[] {
+  return nodes.flatMap((node) => renderContentNode(node, context));
+}
+
+export function renderContentNode(node: QtiContentNode, context: PlayerContentContext): Node[] {
+  if (node.kind === "text") return [document.createTextNode(node.text)];
+  if (node.kind === "interaction") {
+    const interaction = context.interactionAt(node.interactionIndex);
+    if (!interaction) return [];
+    if (interaction.type === "inlineChoice" || interaction.type === "textEntry") {
+      return [context.renderEmbeddedInteraction(interaction)];
+    }
+    return [context.renderBlockInteraction(interaction)];
+  }
+  if (node.kind === "printedVariable") {
+    return [renderPrintedVariable(node.identifier, node.format, context)];
+  }
+  if (node.kind === "feedback") return renderFeedbackContent(node, context);
+  if (node.qtiName === "qti-template-block" || node.qtiName === "qti-template-inline") {
+    return [renderTemplateContent(node, context)];
+  }
+  if (node.qtiName === "qti-position-object-stage") {
+    return renderContentNodes(
+      node.children.filter(
+        (child) => !("qtiName" in child) || (child.qtiName !== "object" && child.qtiName !== "img"),
+      ),
+      context,
+    );
+  }
+  if (node.qtiName === "qti-prompt") {
+    const prompt = document.createElement("p");
+    copySafeAttributes(prompt, node.attributes);
+    prompt.classList.add("qti3-item-prompt");
+    prompt.append(...renderContentNodes(node.children, context));
+    return [prompt];
+  }
+
+  if (unsafeContentElements.has(node.qtiName)) return [];
+  const elementName = contentElementName(node.qtiName);
+  if (!elementName) return renderContentNodes(node.children, context);
+  const element = createContentElement(elementName);
+  copySafeAttributes(element, node.attributes);
+  const mathTemplateValue = context.mathTemplateValue(node);
+  if (mathTemplateValue === undefined) {
+    element.append(...renderContentNodes(node.children, context));
+  } else {
+    element.textContent = mathTemplateValue;
+  }
+  return [element];
+}
+
+function renderTemplateContent(
+  node: Extract<QtiContentNode, { kind: "element" }>,
+  context: PlayerContentContext,
+): HTMLElement {
+  const element = document.createElement(node.qtiName === "qti-template-block" ? "div" : "span");
+  copySafeAttributes(element, node.attributes);
+  element.classList.add(
+    node.qtiName === "qti-template-block" ? "qti3-template-block" : "qti3-template-inline",
+  );
+  element.dataset.templateIdentifier = node.attributes["template-identifier"] ?? "";
+  element.dataset.templateValueIdentifier = node.attributes.identifier ?? "";
+  element.dataset.showHide = node.attributes["show-hide"] === "hide" ? "hide" : "show";
+  element.hidden = !context.isTemplateContentVisible(element);
+  element.append(...renderContentNodes(node.children, context));
+  return element;
+}
+
+function renderPrintedVariable(
+  identifier: string,
+  format: string | undefined,
+  context: PlayerContentContext,
+): HTMLElement {
+  const output = document.createElement("output");
+  output.className = "qti3-printed-variable";
+  output.dataset.identifier = identifier;
+  if (format) output.dataset.format = format;
+  output.value = formatPrintedValue(context.currentVariableValue(identifier), format);
+  output.textContent = output.value;
+  return output;
+}
+
+function renderFeedbackContent(
+  node: Extract<QtiContentNode, { kind: "feedback" }>,
+  context: PlayerContentContext,
+): Node[] {
+  const element = document.createElement(node.feedbackType === "block" ? "section" : "span");
+  element.className = `qti3-feedback-${node.feedbackType}`;
+  element.dataset.feedbackIdentifier = node.identifier;
+  element.dataset.outcomeIdentifier = node.outcomeIdentifier;
+  element.dataset.showHide = node.showHide;
+  element.hidden = !context.isFeedbackVisible(node);
+  element.append(...renderContentNodes(node.children, context));
+  return [element];
+}

package/src/controls/remove-button.ts

@@ -0,0 +1,13 @@
+import { trashIcon } from "../icons.js";
+import type { QtiPlayerMessages } from "../player-messages.js";
+
+export function removeButton(label: string | null, messages: QtiPlayerMessages): HTMLButtonElement {
+  const safeLabel = label?.trim() || messages.remove();
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "qti3-icon-button qti3-remove-button";
+  button.title = messages.remove();
+  button.setAttribute("aria-label", messages.removePair({ label: safeLabel }));
+  button.append(trashIcon());
+  return button;
+}

package/src/icons.ts

@@ -0,0 +1,47 @@
+export type IconPath = string | { d: string; fill?: string; stroke?: string };
+
+export function inlineIcon(className: string, paths: IconPath[]): SVGSVGElement {
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("xmlns", "http://www.w3.org/2000/svg");
+  svg.setAttribute("width", "24");
+  svg.setAttribute("height", "24");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("stroke", "currentColor");
+  svg.setAttribute("stroke-width", "2");
+  svg.setAttribute("stroke-linecap", "round");
+  svg.setAttribute("stroke-linejoin", "round");
+  svg.setAttribute("aria-hidden", "true");
+  svg.setAttribute("focusable", "false");
+  svg.setAttribute("class", className);
+
+  for (const entry of paths) {
+    const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+    if (typeof entry === "string") {
+      path.setAttribute("d", entry);
+    } else {
+      path.setAttribute("d", entry.d);
+      if (entry.stroke) {
+        path.setAttribute("stroke", entry.stroke);
+        path.style.stroke = entry.stroke;
+      }
+      if (entry.fill) {
+        path.setAttribute("fill", entry.fill);
+        path.style.fill = entry.fill;
+      }
+    }
+    svg.append(path);
+  }
+  return svg;
+}
+
+export function trashIcon(): SVGSVGElement {
+  return inlineIcon("qti3-trash-icon", [
+    { d: "M0 0h24v24H0z", stroke: "none", fill: "none" },
+    "M4 7l16 0",
+    "M10 11l0 6",
+    "M14 11l0 6",
+    "M5 7l1 12a2 2 0 0 0 2 2h8a2 2 0 0 0 2 -2l1 -12",
+    "M9 7v-3a1 1 0 0 1 1 -1h4a1 1 0 0 1 1 1v3",
+  ]);
+}