@erudit-js/prose 3.0.0-dev.25

package/dist/elements/problem/problemContent.js

@@ -0,0 +1,236 @@
+//
+// <>
+//     <ProblemDescription>
+//     <ProblemHint>
+//     <...>
+//     <ProblemNote>
+//         <ProblemSection>
+//         <...>
+//     <ProblemSolution>
+//         <ProblemSection>
+//         <...>
+//     <ProblemAnswer>
+//         <ProblemSection>
+//         <...>
+//     <ProblemCheck>
+//     <...>
+// </>
+//
+import { defineRegistryItem, defineSchema, ensureTagChildren, ensureTagNoChildren, isRawElement, ProseError } from "@jsprose/core";
+import { defineEruditTag } from "../../tag.js";
+import { defineEruditProseCoreElement } from "../../coreElement.js";
+import { uppercaseFirst } from "../../utils/case.js";
+import { tryParagraphWrap } from "../../shared/paragraphWrap.js";
+//
+// Description
+//
+export const problemDescriptionSchema = defineSchema({
+	name: "problemDescription",
+	type: "block",
+	linkable: false
+})();
+export const ProblemDescription = defineEruditTag({
+	tagName: "ProblemDescription",
+	schema: problemDescriptionSchema
+})(({ element, tagName, children }) => {
+	ensureTagChildren(tagName, children);
+	element.children = children;
+	const paragraphWrap = tryParagraphWrap(children);
+	if (paragraphWrap) {
+		element.children = paragraphWrap;
+	}
+});
+export const problemDescriptionRegistryItem = defineRegistryItem({
+	schema: problemDescriptionSchema,
+	tags: [ProblemDescription]
+});
+export const problemDescriptionCoreElement = defineEruditProseCoreElement({ registryItem: problemDescriptionRegistryItem });
+//
+// Hint
+//
+export const problemHintSchema = defineSchema({
+	name: "problemHint",
+	type: "block",
+	linkable: false
+})();
+export const ProblemHint = defineEruditTag({
+	tagName: "ProblemHint",
+	schema: problemHintSchema
+})(({ element, tagName, children }) => {
+	ensureTagChildren(tagName, children);
+	element.children = children;
+	const paragraphWrap = tryParagraphWrap(children);
+	if (paragraphWrap) {
+		element.children = paragraphWrap;
+	}
+});
+export const problemHintRegistryItem = defineRegistryItem({
+	schema: problemHintSchema,
+	tags: [ProblemHint]
+});
+export const problemHintCoreElement = defineEruditProseCoreElement({ registryItem: problemHintRegistryItem });
+//
+// Section
+//
+export const problemSectionSchema = defineSchema({
+	name: "problemSection",
+	type: "block",
+	linkable: false
+})();
+export const ProblemSection = defineEruditTag({
+	tagName: "ProblemSection",
+	schema: problemSectionSchema
+})(({ element, tagName, props, children }) => {
+	ensureTagChildren(tagName, children);
+	element.children = children;
+	const paragraphWrap = tryParagraphWrap(children);
+	if (paragraphWrap) {
+		element.children = paragraphWrap;
+	}
+	const title = props.title.trim();
+	if (!title) {
+		throw new ProseError(`${tagName} title prop must be a non-empty string.`);
+	}
+	element.data = title;
+});
+export const problemSectionRegistryItem = defineRegistryItem({
+	schema: problemSectionSchema,
+	tags: [ProblemSection]
+});
+export const problemSectionCoreElement = defineEruditProseCoreElement({ registryItem: problemSectionRegistryItem });
+function defineProblemSectionContainer(name) {
+	const schema = defineSchema({
+		name: `problem${uppercaseFirst(name)}`,
+		type: "block",
+		linkable: false
+	})();
+	const tag = defineEruditTag({
+		tagName: `Problem${uppercaseFirst(name)}`,
+		schema
+	})(({ element, tagName, children }) => {
+		ensureTagChildren(tagName, children);
+		const sectionChildren = [];
+		const nonSectionChildren = [];
+		let seenSection = false;
+		for (const child of children) {
+			if (isRawElement(child, problemSectionSchema)) {
+				sectionChildren.push(child);
+				seenSection = true;
+			} else {
+				if (seenSection) {
+					throw new ProseError(`${tagName} non-section children must appear before any <ProblemSection> child.`);
+				}
+				nonSectionChildren.push(child);
+			}
+		}
+		const paragraphWrap = tryParagraphWrap(nonSectionChildren);
+		const wrappedNonSectionChildren = paragraphWrap ?? nonSectionChildren;
+		element.children = [...wrappedNonSectionChildren, ...sectionChildren];
+	});
+	const registryItem = defineRegistryItem({
+		schema,
+		tags: [tag]
+	});
+	const coreElement = defineEruditProseCoreElement({ registryItem });
+	return {
+		schema,
+		tag,
+		registryItem,
+		coreElement
+	};
+}
+//
+// Section Containers
+//
+export const problemNote = defineProblemSectionContainer("note");
+export const problemSolution = defineProblemSectionContainer("solution");
+export const problemAnswer = defineProblemSectionContainer("answer");
+export const problemCheckSchema = defineSchema({
+	name: "problemCheck",
+	type: "block",
+	linkable: false
+})();
+export const ProblemCheck = defineEruditTag({
+	tagName: "ProblemCheck",
+	schema: problemCheckSchema
+})(({ element, tagName, props, children }) => {
+	ensureTagNoChildren(tagName, children);
+	if (props.answer !== undefined) {
+		element.data = {
+			...element.data,
+			answers: [String(props.answer)]
+		};
+	} else if (props.answers !== undefined) {
+		element.data = {
+			...element.data,
+			answers: props.answers.map(String)
+		};
+	} else if (props.script !== undefined) {
+		element.data = {
+			...element.data,
+			script: props.script
+		};
+	}
+	if (props.label !== undefined) {
+		element.data = {
+			...element.data,
+			label: props.label
+		};
+	}
+	if (props.hint !== undefined) {
+		element.data = {
+			...element.data,
+			hint: props.hint
+		};
+	}
+	if (props.placeholder !== undefined) {
+		element.data = {
+			...element.data,
+			placeholder: props.placeholder
+		};
+	}
+});
+export const problemCheckRegistryItem = defineRegistryItem({
+	schema: problemCheckSchema,
+	tags: [ProblemCheck]
+});
+export const problemCheckCoreElement = defineEruditProseCoreElement({ registryItem: problemCheckRegistryItem });
+export function validateProblemContent(source, children) {
+	ensureTagChildren(source, children, [
+		problemDescriptionSchema,
+		problemHintSchema,
+		problemNote.schema,
+		problemSolution.schema,
+		problemAnswer.schema,
+		problemCheckSchema
+	]);
+	const uniques = [
+		{
+			schema: problemDescriptionSchema,
+			label: "ProblemDescription"
+		},
+		{
+			schema: problemSolution.schema,
+			label: "ProblemSolution"
+		},
+		{
+			schema: problemAnswer.schema,
+			label: "ProblemAnswer"
+		}
+	];
+	const found = new Set();
+	for (const child of children) {
+		for (const { schema, label } of uniques) {
+			if (isRawElement(child, schema)) {
+				if (found.has(label)) {
+					throw new ProseError(`
+Invalid problem content at ${source}:
+It can contain only one <${label}>!
+                        `.trim());
+				}
+				found.add(label);
+				break;
+			}
+		}
+	}
+}

package/dist/elements/problem/problemScript.d.ts

@@ -0,0 +1,26 @@
+import { type AnySchema, type AnyUnique, type AutoUnique, type LinkableTag, type RawElement, type Unique, type WrapSchemas } from '@jsprose/core';
+import { type ProblemSeed, Random } from './rng.js';
+import { type CheckFunction, type ProblemContentChild } from './problemContent.js';
+export declare function insertProblemScriptId(scriptSrc: string, code: string): string;
+export interface ProblemScriptDefinition {
+    uniques?: Record<string, LinkableTag>;
+    isGenerator?: boolean;
+}
+export declare function defineProblemScript<const TDefinition extends ProblemScriptDefinition>(scriptSrcOrDefinition?: string | TDefinition, maybeDefinition?: TDefinition): (problemContentFn: (args: (TDefinition["uniques"] extends Record<string, LinkableTag> ? {
+    uniques: { [K in keyof NonNullable<TDefinition["uniques"]>]: Unique<NonNullable<TDefinition["uniques"]>[K]>; };
+} : {}) & (TDefinition["isGenerator"] extends true ? {
+    initial: boolean;
+    random: Random;
+} : {})) => RawElement<AnySchema> | {
+    problemContent: RawElement<AnySchema>;
+    check?: CheckFunction;
+}) => (...args: TDefinition["uniques"] extends Record<string, LinkableTag> ? [uniquesMapping: (() => AutoUnique) | { [K in keyof NonNullable<TDefinition["uniques"]>]: Unique<NonNullable<TDefinition["uniques"]>[K]> | (() => AutoUnique); }] : []) => ProblemScriptInstance;
+export interface ProblemScriptInstance {
+    scriptSrc: string;
+    uniques: Record<string, AnyUnique>;
+    isGenerator: boolean;
+    generate: (seed?: ProblemSeed) => {
+        problemContent: WrapSchemas<'raw-prose', ProblemContentChild>[];
+        check?: CheckFunction;
+    };
+}

package/dist/elements/problem/problemScript.js

@@ -0,0 +1,79 @@
+import { isRawElement, ProseError } from "@jsprose/core";
+import { DEFAULT_SEED, Random } from "./rng.js";
+import { validateProblemContent } from "./problemContent.js";
+//
+// Problem Script Src
+//
+export function insertProblemScriptId(scriptSrc, code) {
+	// Match: export default defineProblemScript(...)
+	return code.replace(/\bdefineProblemScript\(([\s\S]*?)\)/g, (fullMatch, argsContent) => {
+		const trimmed = argsContent.trim();
+		// If the first argument already looks like a string literal, skip.
+		if (/^['"`]/.test(trimmed)) {
+			return fullMatch;
+		}
+		const needsNoSpace = /^\s*\n/.test(argsContent);
+		const comma = needsNoSpace ? "," : ", ";
+		const newArgs = `'${scriptSrc}'${comma}${argsContent}`;
+		return `defineProblemScript(${newArgs})`;
+	});
+}
+export function defineProblemScript(scriptSrcOrDefinition, maybeDefinition) {
+	let scriptSrc;
+	let definition;
+	if (typeof scriptSrcOrDefinition === "string") {
+		scriptSrc = scriptSrcOrDefinition;
+		definition = maybeDefinition;
+	} else {
+		throw new ProseError(`Problem script requires script ID to be manually specified or inserted at transform time!`);
+	}
+	function defineProblemContent(problemContentFn) {
+		function createProblemScriptInstance(...args) {
+			const finalizedUniques = {};
+			if (definition.uniques) {
+				const uniquesMapping = args[0];
+				if (typeof uniquesMapping === "function") {
+					for (const key in definition.uniques) {
+						finalizedUniques[key] = uniquesMapping();
+					}
+				} else {
+					for (const key in uniquesMapping) {
+						const mapping = uniquesMapping[key];
+						if (typeof mapping === "function") {
+							finalizedUniques[key] = mapping();
+						} else {
+							finalizedUniques[key] = mapping;
+							// @ts-expect-error
+							delete finalizedUniques[key].rawElement;
+							// @ts-expect-error
+							delete finalizedUniques[key].tag;
+						}
+					}
+				}
+			}
+			return {
+				scriptSrc,
+				uniques: finalizedUniques,
+				isGenerator: definition.isGenerator ?? false,
+				generate: (seed) => {
+					const finalizedSeed = seed ?? DEFAULT_SEED;
+					const problemContentResult = problemContentFn({
+						uniques: finalizedUniques,
+						...definition.isGenerator ? {
+							initial: finalizedSeed === DEFAULT_SEED,
+							random: new Random(finalizedSeed)
+						} : {}
+					});
+					const problemContent = isRawElement(problemContentResult) ? problemContentResult : problemContentResult.problemContent;
+					validateProblemContent("[Problem Script]", problemContent.children);
+					return {
+						problemContent: problemContent.children,
+						check: !isRawElement(problemContentResult) ? problemContentResult.check : undefined
+					};
+				}
+			};
+		}
+		return createProblemScriptInstance;
+	}
+	return defineProblemContent;
+}

package/dist/elements/problem/problems.d.ts

@@ -0,0 +1,212 @@
+import { type AnyUnique, type BlockSchema, type TagChildren } from '@jsprose/core';
+import { type ProblemContentChild } from './problemContent.js';
+import { type ProblemInfo } from './shared.js';
+import { type ProblemScriptStorage } from './storage.js';
+import { type ProblemScriptInstance } from './problemScript.js';
+export interface SubProblemData {
+    label?: string;
+    scriptUniques?: Record<string, AnyUnique>;
+}
+export declare const subProblemSchema: {
+    name: "subProblem";
+    type: "block";
+    linkable: false;
+    Data: SubProblemData;
+    Storage: ProblemScriptStorage;
+    Children: ProblemContentChild[];
+};
+export declare const SubProblem: import("@jsprose/core").Tag<"SubProblem", {
+    name: "subProblem";
+    type: "block";
+    linkable: false;
+    Data: SubProblemData;
+    Storage: ProblemScriptStorage;
+    Children: ProblemContentChild[];
+}, ({
+    label?: string;
+} & {
+    children: {};
+    script?: undefined;
+}) | ({
+    label?: string;
+} & {
+    script: ProblemScriptInstance;
+    children?: undefined;
+})>;
+export declare const subProblemRegistryItem: import("@jsprose/core").RegistryItem<{
+    name: "subProblem";
+    type: "block";
+    linkable: false;
+    Data: SubProblemData;
+    Storage: ProblemScriptStorage;
+    Children: ProblemContentChild[];
+}, {
+    SubProblem: import("@jsprose/core").Tag<"SubProblem", {
+        name: "subProblem";
+        type: "block";
+        linkable: false;
+        Data: SubProblemData;
+        Storage: ProblemScriptStorage;
+        Children: ProblemContentChild[];
+    }, ({
+        label?: string;
+    } & {
+        children: {};
+        script?: undefined;
+    }) | ({
+        label?: string;
+    } & {
+        script: ProblemScriptInstance;
+        children?: undefined;
+    })>;
+}, undefined>;
+export declare const subProblemCoreElement: {
+    registryItem: import("@jsprose/core").RegistryItem<{
+        name: "subProblem";
+        type: "block";
+        linkable: false;
+        Data: SubProblemData;
+        Storage: ProblemScriptStorage;
+        Children: ProblemContentChild[];
+    }, {
+        SubProblem: import("@jsprose/core").Tag<"SubProblem", {
+            name: "subProblem";
+            type: "block";
+            linkable: false;
+            Data: SubProblemData;
+            Storage: ProblemScriptStorage;
+            Children: ProblemContentChild[];
+        }, ({
+            label?: string;
+        } & {
+            children: {};
+            script?: undefined;
+        }) | ({
+            label?: string;
+        } & {
+            script: ProblemScriptInstance;
+            children?: undefined;
+        })>;
+    }, undefined>;
+};
+export declare const problemsSchema: {
+    name: "problems";
+    type: "block";
+    linkable: true;
+    Data: ProblemInfo;
+    Storage: undefined;
+    Children: (BlockSchema | {
+        name: "subProblem";
+        type: "block";
+        linkable: false;
+        Data: SubProblemData;
+        Storage: ProblemScriptStorage;
+        Children: ProblemContentChild[];
+    })[];
+};
+export declare const Problems: import("@jsprose/core").Tag<"Problems", {
+    name: "problems";
+    type: "block";
+    linkable: true;
+    Data: ProblemInfo;
+    Storage: undefined;
+    Children: (BlockSchema | {
+        name: "subProblem";
+        type: "block";
+        linkable: false;
+        Data: SubProblemData;
+        Storage: ProblemScriptStorage;
+        Children: ProblemContentChild[];
+    })[];
+}, {
+    title: string;
+    level: import("./shared.js").ProblemLevel;
+    attributes?: (import("./shared.js").ProblemAttribute | import("./shared.js").ProblemCustomAttribute)[];
+} & {
+    pretty?: true | undefined;
+    applied?: true | undefined;
+    method?: true | undefined;
+    inter?: true | undefined;
+} & TagChildren & import("../../toc.js").ObjPropToc & import("../../snippet.js").ObjPropSnippet & import("../../snippet.js").ObjPropSearch & import("../../snippet.js").ObjPropQuick & import("../../snippet.js").ObjPropSeo>;
+export declare const problemsRegistryItem: import("@jsprose/core").RegistryItem<{
+    name: "problems";
+    type: "block";
+    linkable: true;
+    Data: ProblemInfo;
+    Storage: undefined;
+    Children: (BlockSchema | {
+        name: "subProblem";
+        type: "block";
+        linkable: false;
+        Data: SubProblemData;
+        Storage: ProblemScriptStorage;
+        Children: ProblemContentChild[];
+    })[];
+}, {
+    Problems: import("@jsprose/core").Tag<"Problems", {
+        name: "problems";
+        type: "block";
+        linkable: true;
+        Data: ProblemInfo;
+        Storage: undefined;
+        Children: (BlockSchema | {
+            name: "subProblem";
+            type: "block";
+            linkable: false;
+            Data: SubProblemData;
+            Storage: ProblemScriptStorage;
+            Children: ProblemContentChild[];
+        })[];
+    }, {
+        title: string;
+        level: import("./shared.js").ProblemLevel;
+        attributes?: (import("./shared.js").ProblemAttribute | import("./shared.js").ProblemCustomAttribute)[];
+    } & {
+        pretty?: true | undefined;
+        applied?: true | undefined;
+        method?: true | undefined;
+        inter?: true | undefined;
+    } & TagChildren & import("../../toc.js").ObjPropToc & import("../../snippet.js").ObjPropSnippet & import("../../snippet.js").ObjPropSearch & import("../../snippet.js").ObjPropQuick & import("../../snippet.js").ObjPropSeo>;
+}, undefined>;
+export declare const problemsCoreElement: {
+    registryItem: import("@jsprose/core").RegistryItem<{
+        name: "problems";
+        type: "block";
+        linkable: true;
+        Data: ProblemInfo;
+        Storage: undefined;
+        Children: (BlockSchema | {
+            name: "subProblem";
+            type: "block";
+            linkable: false;
+            Data: SubProblemData;
+            Storage: ProblemScriptStorage;
+            Children: ProblemContentChild[];
+        })[];
+    }, {
+        Problems: import("@jsprose/core").Tag<"Problems", {
+            name: "problems";
+            type: "block";
+            linkable: true;
+            Data: ProblemInfo;
+            Storage: undefined;
+            Children: (BlockSchema | {
+                name: "subProblem";
+                type: "block";
+                linkable: false;
+                Data: SubProblemData;
+                Storage: ProblemScriptStorage;
+                Children: ProblemContentChild[];
+            })[];
+        }, {
+            title: string;
+            level: import("./shared.js").ProblemLevel;
+            attributes?: (import("./shared.js").ProblemAttribute | import("./shared.js").ProblemCustomAttribute)[];
+        } & {
+            pretty?: true | undefined;
+            applied?: true | undefined;
+            method?: true | undefined;
+            inter?: true | undefined;
+        } & TagChildren & import("../../toc.js").ObjPropToc & import("../../snippet.js").ObjPropSnippet & import("../../snippet.js").ObjPropSearch & import("../../snippet.js").ObjPropQuick & import("../../snippet.js").ObjPropSeo>;
+    }, undefined>;
+};

package/dist/elements/problem/problems.js

@@ -0,0 +1,74 @@
+import { defineRegistryItem, defineSchema, ensureTagBlockChildren, isRawElement, ProseError } from "@jsprose/core";
+import { validateProblemContent } from "./problemContent.js";
+import { defineEruditTag } from "../../tag.js";
+import { problemProps2Info } from "./shared.js";
+import { defineEruditProseCoreElement } from "../../coreElement.js";
+import { problemScriptStorageKey } from "./storage.js";
+import "./problemScript.js";
+export const subProblemSchema = defineSchema({
+	name: "subProblem",
+	type: "block",
+	linkable: false
+})();
+export const SubProblem = defineEruditTag({
+	tagName: "SubProblem",
+	schema: subProblemSchema
+})(({ element, tagName, props, children }) => {
+	element.data = {};
+	const label = props.label?.trim();
+	if (label) {
+		element.data.label = label;
+	}
+	if (props.script && children) {
+		throw new ProseError(`<${tagName}> cannot have both script and children!`);
+	}
+	if (props.script) {
+		element.data.scriptUniques = props.script.uniques;
+		element.storageKey = problemScriptStorageKey(props.script.scriptSrc);
+		element.children = props.script.generate().problemContent;
+	} else {
+		validateProblemContent(tagName, children);
+		element.children = children;
+	}
+});
+export const subProblemRegistryItem = defineRegistryItem({
+	schema: subProblemSchema,
+	tags: [SubProblem]
+});
+export const subProblemCoreElement = defineEruditProseCoreElement({ registryItem: subProblemRegistryItem });
+//
+// Problems
+//
+export const problemsSchema = defineSchema({
+	name: "problems",
+	type: "block",
+	linkable: true
+})();
+export const Problems = defineEruditTag({
+	tagName: "Problems",
+	schema: problemsSchema
+})(({ element, tagName, props, children, registry }) => {
+	ensureTagBlockChildren(tagName, children, registry);
+	const subProblemChildren = [];
+	const otherChildren = [];
+	for (const child of children) {
+		if (isRawElement(child, subProblemSchema)) {
+			subProblemChildren.push(child);
+		} else {
+			otherChildren.push(child);
+		}
+	}
+	if (subProblemChildren.length === 0) {
+		throw new ProseError(`<${tagName}> must have at least one <SubProblem> child!`);
+	}
+	element.children = [...otherChildren, ...subProblemChildren];
+	element.data = problemProps2Info(props);
+	element.title = element.data.title;
+	element.snippet = {};
+	element.toc = { add: true };
+});
+export const problemsRegistryItem = defineRegistryItem({
+	schema: problemsSchema,
+	tags: [Problems]
+});
+export const problemsCoreElement = defineEruditProseCoreElement({ registryItem: problemsRegistryItem });

package/dist/elements/problem/rng.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Static seed not random for SEO reasons.
+ * It ensures that initial problem content is always the same on each build, helping search engines to index initial problem content consistently.
+ */
+export declare const DEFAULT_SEED = "3141592653";
+export type ProblemSeed = string | number;
+export declare function normalizeSeed(seed: ProblemSeed): number;
+export declare class Random {
+    private _rng;
+    constructor(seed: ProblemSeed);
+    rng(): number;
+    boolean(): boolean;
+    integer(min: number, max: number): number;
+    float(min: number, max: number, decimals: number): number;
+    shuffle<T>(arr: T[]): T[];
+    arrayElement<T>(arr: T[]): T | undefined;
+    arrayElements<T>(arr: T[], count: number, unique?: boolean): T[];
+}