@webwriter/quiz 1.1.3 → 2.0.0

package/src/widgets/order/webwriter-order-item.ts

@@ -0,0 +1,243 @@
+import { msg } from "@lit/localize";
+import SlIconButton from "@shoelace-style/shoelace/dist/components/icon-button/icon-button.component.js";
+import SlIcon from "@shoelace-style/shoelace/dist/components/icon/icon.component.js";
+import { LitElementWw } from "@webwriter/lit";
+import { css, html, nothing } from "lit";
+import { customElement } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import GripHorizontalIcon from "../../../assets/icons/grip-horizontal.svg";
+import GripVerticalIcon from "../../../assets/icons/grip-vertical.svg";
+import { DraggableGridItem } from "../../lib/draggable-grid";
+import { HintPopup } from "../../lib/hint-popup";
+import { commonStyles } from "../../lib/utils";
+import { WebwriterOrder } from "./webwriter-order";
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"webwriter-order-item": WebwriterOrderItem;
+	}
+}
+
+const ROMAN_NUMERALS_TABLE: [number, string][] = [
+	[1000, "M"],
+	[900, "CM"],
+	[500, "D"],
+	[400, "CD"],
+	[100, "C"],
+	[90, "XC"],
+	[50, "L"],
+	[40, "XL"],
+	[10, "X"],
+	[9, "IX"],
+	[5, "V"],
+	[4, "IV"],
+	[1, "I"],
+];
+
+/**
+ * A single item of a `<webwriter-order>`.
+ *
+ * It must be assigned to the default slot of its parent element. An optional
+ * `<webwriter-quiz-hint>` may be assigned to its `hint` slot.
+ */
+@customElement("webwriter-order-item")
+export class WebwriterOrderItem extends LitElementWw implements DraggableGridItem {
+	static styles = [
+		commonStyles,
+		css`
+			:host {
+				display: contents !important;
+			}
+
+			slot {
+				display: block;
+			}
+
+			.order-item {
+				background-color: var(--sl-color-neutral-0);
+			}
+
+			.layout-list {
+				display: grid !important;
+				grid-column: 1 / -1;
+				grid-template-columns: subgrid;
+
+				> * {
+					padding: var(--sl-spacing-2x-small) 0;
+				}
+			}
+
+			.actions,
+			hint-popup::part(empty) {
+				opacity: 0;
+			}
+
+			:is(.ww-dragging, :host(:hover)) .actions {
+				opacity: 1;
+			}
+
+			:is(.ww-dragging, :host(.ww-selected-text-within), :host(:hover)) hint-popup::part(empty) {
+				opacity: 1;
+			}
+
+			.layout-tiles {
+				border: 1px solid var(--sl-input-border-color);
+				border-radius: var(--sl-border-radius-large);
+				padding: var(--sl-spacing-small);
+				box-sizing: border-box;
+
+				display: grid !important;
+				grid-template-columns: auto 1fr max-content max-content;
+				grid-template-rows: auto 1fr;
+				grid-template-areas: "position . hint grab" "content content content content";
+				position: relative;
+				aspect-ratio: 1 / 1;
+
+				.position {
+					grid-area: position;
+				}
+
+				.content {
+					grid-area: content;
+				}
+
+				hint-popup {
+					grid-area: hint;
+				}
+
+				.grip {
+					grid-area: grab;
+				}
+
+				.actions {
+					position: absolute;
+				}
+
+				.actions {
+					position: absolute;
+					background: var(--sl-color-neutral-0);
+					border: 1px solid var(--sl-input-border-color);
+					border-radius: var(--sl-border-radius-pill);
+					top: 0;
+					left: 50%;
+					translate: -50% -50%;
+					padding: 0 var(--sl-spacing-x-small);
+					box-sizing: border-box;
+				}
+			}
+
+			:host(:not([contenteditable="true"]):not([contenteditable=""])) {
+				.order-item:hover .grip {
+					color: var(--sl-color-primary-600);
+				}
+
+				.order-item.ww-dragging .grip {
+					color: var(--sl-color-primary-700);
+				}
+			}
+
+			.grip,
+			.position {
+				padding-right: var(--sl-spacing-small);
+			}
+
+			.position {
+				font-variant-numeric: tabular-nums;
+				font-weight: bold;
+
+				&.numbering-numeric {
+					text-align: right;
+				}
+
+				&.numbering-none {
+					padding: 0;
+				}
+			}
+
+			.actions,
+			.grip {
+				height: 1lh;
+				display: flex;
+				align-items: center;
+			}
+
+			[data-drag-handle] {
+				cursor: grab;
+				touch-action: none;
+			}
+		`,
+	];
+
+	/** @internal */
+	get draggableElement(): HTMLElement {
+		return this.shadowRoot?.querySelector(".order-item") as HTMLElement;
+	}
+
+	/** @internal */
+	static scopedElements = {
+		"sl-icon": SlIcon,
+		"hint-popup": HintPopup,
+		"sl-icon-button": SlIconButton,
+	};
+
+	/** @internal */
+	getPositionText(): string {
+		const parent = this.parentElement as WebwriterOrder | undefined;
+		if (!parent) return "";
+
+		let index = parent.items.indexOf(this);
+		if (index === -1) return "";
+
+		if (parent.direction === "descending") index = parent.items.length - 1 - index;
+
+		switch (parent.numberingStyle) {
+			case "numeric":
+				return (index + 1).toString() + ".";
+			case "alphabetic":
+				let result = "";
+				do {
+					result = String.fromCharCode((index % 26) + 65) + result;
+					index = Math.floor(index / 26) - 1;
+				} while (index >= 0);
+				return result + ".";
+			case "roman":
+				return (
+					ROMAN_NUMERALS_TABLE.reduce((acc, [value, numeral]) => {
+						while (index + 1 >= value) {
+							acc += numeral;
+							index -= value;
+						}
+						return acc;
+					}, "") + "."
+				);
+			default:
+			case "none":
+				return "";
+		}
+	}
+
+	render() {
+		const parent = this.parentElement as WebwriterOrder | undefined;
+		if (!parent) return nothing;
+
+		const gripIcon = parent.layout === "list" ? GripVerticalIcon : GripHorizontalIcon;
+
+		return html`
+			<div
+				class=${classMap({
+					"order-item": true,
+					[`layout-${parent.layout}`]: true,
+				})}
+				?data-drag-handle=${!this.isContentEditable}
+			>
+				${this.isContentEditable ? html`<div></div>` : html`<sl-icon class="grip" src=${gripIcon}></sl-icon>`}
+				<div class="position numbering-${parent.numberingStyle}">${this.getPositionText()}</div>
+				<slot class="content" style=${`--ww-placeholder: "${msg("Option")}"`}></slot>
+				<div class="actions author-only">
+					<sl-icon-button ?data-drag-handle=${this.isContentEditable} src=${gripIcon}></sl-icon-button>
+				</div>
+				<hint-popup position="start" data-drag-no-handle><slot name="hint"></slot></hint-popup>
+			</div>
+		`;
+	}
+}

package/src/widgets/order/webwriter-order.ts

@@ -0,0 +1,282 @@
+import { msg } from "@lit/localize";
+import SlIcon from "@shoelace-style/shoelace/dist/components/icon/icon.component.js";
+import { action, LitElementWw, type OptionDeclaration } from "@webwriter/lit";
+import ArrowDownUpIcon from "bootstrap-icons/icons/arrow-down-up.svg";
+import PlusIcon from "bootstrap-icons/icons/plus.svg";
+import { css, html, nothing, PropertyValues } from "lit";
+import { customElement, property, queryAssignedElements } from "lit/decorators.js";
+import LOCALIZE from "../../../localization/generated";
+import { name as packageId } from "../../../package.json";
+import { IWebWriterQuizType, registerQuizType } from "../../api";
+import { DraggableGrid, DraggableGridReorderEvent } from "../../lib/draggable-grid";
+import { encryptedProperty, encryptPlaintextAttributes } from "../../lib/encrypted-property";
+import { commonStyles, randomizeArray } from "../../lib/utils";
+import { mutateWithStableSelection, registerAsEnterCreatesNew } from "../../lib/webwriter-quirks";
+import type { WebwriterOrderItem } from "./webwriter-order-item";
+
+declare global {
+	interface HTMLElementTagNameMap {
+		"webwriter-order": WebwriterOrder;
+	}
+}
+
+export type OrderLayout = "list" | "tiles";
+export type OrderDirection = "ascending" | "descending";
+export type OrderNumberingStyle = "none" | "numeric" | "alphabetic" | "roman";
+export type OrderGradingMethod = "pass-fail" | "partial-position" | "partial-sequence";
+export type OrderSolution = string[];
+
+registerQuizType({
+	packageId,
+	widgetPosition: 20,
+	id: "webwriter-order",
+	getName: () => msg("Order"),
+	icon: ArrowDownUpIcon,
+	createInstance: () => document.createElement("webwriter-order"),
+});
+
+/**
+ * An answer where learners drag items into the correct order.
+ *
+ * The items must be `<webwriter-order-item>` elements assigned to the default
+ * slot.
+ */
+@customElement("webwriter-order")
+export class WebwriterOrder extends LitElementWw implements IWebWriterQuizType {
+	/** @internal */
+	get dynamicOptions(): Record<string, OptionDeclaration> {
+		return {
+			"layout": {
+				type: "select",
+				label: { _: msg("Layout") },
+				options: [
+					{ value: "list", label: { _: msg("List") } },
+					{ value: "tiles", label: { _: msg("Tiles") } },
+				],
+				description: { _: msg("The layout variant to use.") },
+			},
+			"direction": {
+				type: "select",
+				label: { _: msg("Direction") },
+				options: [
+					{ value: "ascending", label: { _: msg("Ascending") } },
+					{ value: "descending", label: { _: msg("Descending") } },
+				],
+				description: { _: msg("The order direction to use.") },
+			},
+			"numbering-style": {
+				type: "select",
+				label: { _: msg("Numbering") },
+				options: [
+					{ value: "none", label: { _: msg("None") } },
+					{ value: "numeric", label: { _: msg("Numeric") } },
+					{ value: "alphabetic", label: { _: msg("Alphabetic") } },
+					{ value: "roman", label: { _: msg("Roman") } },
+				],
+				description: { _: msg("The numbering style to use.") },
+			},
+			"grading-method": {
+				type: "select",
+				label: { _: msg("Grading") },
+				options: [
+					{ value: "pass-fail", label: { _: msg("Pass/Fail") } },
+					{ value: "partial-position", label: { _: msg("Partial (Position)") } },
+					{ value: "partial-sequence", label: { _: msg("Partial (Sequence)") } },
+				],
+				description: { _: msg("The grading method to use.") },
+			},
+		};
+	}
+
+	/** @internal */
+	localize = LOCALIZE;
+
+	/** @internal */
+	static scopedElements = {
+		"draggable-grid": DraggableGrid,
+		"sl-icon": SlIcon,
+	};
+
+	static styles = [
+		commonStyles,
+		css`
+			.container-list {
+				display: grid;
+				grid-template-columns: max-content max-content minmax(0, 1fr) max-content max-content;
+			}
+
+			.container-tiles {
+				display: grid;
+				grid-template-columns: repeat(auto-fill, minmax(130px, 1fr));
+				gap: var(--sl-spacing-medium);
+
+				.add-option {
+					aspect-ratio: 1 / 1;
+
+					border: 1px dashed var(--sl-color-neutral-300);
+					border-radius: var(--sl-border-radius-medium);
+					box-sizing: border-box;
+					color: var(--sl-color-neutral-500);
+					cursor: pointer;
+
+					display: flex;
+					align-items: center;
+					justify-content: center;
+					gap: 0.5rem;
+
+					&:hover {
+						background-color: var(--sl-color-primary-50);
+						border-color: var(--sl-color-primary-300);
+						color: var(--sl-color-primary-700);
+					}
+				}
+			}
+		`,
+	];
+
+	/**
+	 * How the items are arranged.
+	 *
+	 * - `list`: One item per row.
+	 * - `tiles`: A responsive grid of equally sized tiles.
+	 */
+	@property({ type: String, attribute: "layout", reflect: true })
+	accessor layout: OrderLayout = "list";
+
+	/**
+	 * The direction in which the items are numbered.
+	 *
+	 * - `ascending`: The first item carries the lowest position.
+	 * - `descending`: The first item carries the highest position.
+	 */
+	@property({ type: String, attribute: "direction", reflect: true })
+	accessor direction: OrderDirection = "ascending";
+
+	/**
+	 * How the position of each item is labelled.
+	 *
+	 * - `none`: No position is shown.
+	 * - `numeric`: Arabic numerals (1., 2., 3., ...).
+	 * - `alphabetic`: Latin letters (A., B., C., ...).
+	 * - `roman`: Roman numerals (I., II., III., ...).
+	 */
+	@property({ type: String, attribute: "numbering-style", reflect: true })
+	accessor numberingStyle: OrderNumberingStyle = "numeric";
+
+	/**
+	 * How the score of this answer is calculated.
+	 *
+	 * - `pass-fail`: Full score only if every item is in its correct position.
+	 * - `partial-position`: Credit for each item in its correct position.
+	 * - `partial-sequence`: Credit for each pair of adjacent items in the correct order.
+	 */
+	@property({ type: String, attribute: "grading-method", reflect: true })
+	accessor gradingMethod: OrderGradingMethod = "pass-fail";
+
+	/**
+	 * The IDs of the items in their correct order. It is obfuscated in the markup so that learners cannot read it directly.
+	 */
+	@property({ type: Array, attribute: true, reflect: true, converter: encryptedProperty })
+	accessor solution: OrderSolution = [];
+
+	/** @internal */
+	@queryAssignedElements()
+	accessor items!: WebwriterOrderItem[];
+
+	protected updated(changed: PropertyValues): void {
+		super.updated(changed);
+
+		if (changed.has("layout") || changed.has("numberingStyle") || changed.has("direction")) {
+			this.refreshItems();
+		}
+	}
+
+	private randomizeItems() {
+		this.append(...randomizeArray(this.items));
+	}
+
+	checkValidity(): boolean {
+		return true;
+	}
+
+	reset(): void {
+		this.randomizeItems();
+	}
+
+	checkAnswer(detailedFeedback: boolean): number {
+		// TODO: Show detailed feedback if requested
+
+		switch (this.gradingMethod) {
+			case "pass-fail":
+				return this.items.every((item, index) => item.id === this.solution[index]) ? 1 : 0;
+			case "partial-position":
+				const correctPositions = this.items.filter((item, index) => item.id === this.solution[index]).length;
+				return correctPositions / this.items.length;
+			case "partial-sequence":
+				let correctSequenceCount = 0;
+				for (let i = 0; i < this.items.length - 1; i++) {
+					const currentIndexInSolution = this.solution.indexOf(this.items[i].id);
+					const nextIndexInSolution = this.solution.indexOf(this.items[i + 1].id);
+
+					if (currentIndexInSolution + 1 === nextIndexInSolution) correctSequenceCount++;
+				}
+				return correctSequenceCount / (this.items.length - 1);
+			default:
+				return 0;
+		}
+	}
+
+	protected firstUpdated(changed: PropertyValues): void {
+		super.firstUpdated(changed);
+		encryptPlaintextAttributes(this);
+		if (!this.isContentEditable) {
+			this.randomizeItems();
+		} else {
+			this.solution = this.items.map(item => item.id);
+		}
+	}
+
+	private refreshItems() {
+		this.items.forEach(item => item?.requestUpdate?.());
+	}
+
+	connectedCallback() {
+		super.connectedCallback();
+		registerAsEnterCreatesNew("webwriter-order-item");
+	}
+
+	private handleReorder({ detail }: DraggableGridReorderEvent) {
+		mutateWithStableSelection(detail.item, () => this.insertBefore(detail.item, detail.before));
+	}
+
+	@action({ label: { _: msg("Add Option") } })
+	private addOption() {
+		this.appendChild(document.createElement("webwriter-order-item"));
+	}
+
+	private AddOptionButton() {
+		if (this.layout !== "tiles" || !this.isContentEditable) return nothing;
+		return html`
+			<div class="add-option" @click=${this.addOption} id="add-option" data-not-draggable>
+				<sl-icon src=${PlusIcon}></sl-icon>
+				${msg("Add Option")}
+			</div>
+		`;
+	}
+
+	render() {
+		return html`<draggable-grid
+			class="container-${this.layout}"
+			?vertical=${this.layout === "list"}
+			@reorder=${this.handleReorder}
+		>
+			<slot
+				@slotchange=${() => {
+					this.refreshItems();
+					if (this.isContentEditable) this.solution = this.items.map(item => item.id);
+				}}
+			></slot>
+			${this.AddOptionButton()}
+		</draggable-grid>`;
+	}
+}

package/src/widgets/pairing/webwriter-pairing-item.ts

@@ -0,0 +1,46 @@
+import { msg } from "@lit/localize";
+import { LitElementWw } from "@webwriter/lit";
+import { css, html } from "lit";
+import { customElement } from "lit/decorators.js";
+import { styleMap } from "lit/directives/style-map.js";
+
+/**
+ * A single item of a `<webwriter-pairing>`.
+ *
+ * It must be a child of its parent element.
+ */
+@customElement("webwriter-pairing-item")
+export class WebwriterPairing extends LitElementWw {
+	static styles = css`
+		:host {
+			display: block;
+			aspect-ratio: 1 / 1;
+			width: 100%;
+			overflow: hidden;
+			box-sizing: border-box;
+		}
+
+		slot {
+			display: grid;
+			align-items: center;
+			text-align: center;
+			height: 100%;
+
+			padding: var(--sl-spacing-x-small);
+			box-sizing: border-box;
+		}
+
+		::slotted(p) {
+			min-width: 0;
+			overflow-wrap: anywhere;
+		}
+	`;
+
+	render() {
+		return html`<slot
+			style=${styleMap({
+				"--ww-placeholder": `"${msg("Item")}"`,
+			})}
+		></slot>`;
+	}
+}