@erudit-js/prose 4.0.1 → 4.1.0

package/dist/elements/link/step.js

@@ -0,0 +1,36 @@
+import { isRawElement } from "@jsprose/core";
+import { defineResolveStep } from "../../resolveStep.js";
+import { dependencySchema, depSchema } from "./dependency/core.js";
+import { referenceSchema, refSchema } from "./reference/core.js";
+export const contentLinkStep = defineResolveStep(({ rawElement, proseElement }) => {
+	if (!proseElement.id || !rawElement.storageKey) {
+		return;
+	}
+	const checks = [
+		{
+			schema: depSchema,
+			key: "Dep"
+		},
+		{
+			schema: dependencySchema,
+			key: "Dependency"
+		},
+		{
+			schema: refSchema,
+			key: "Ref"
+		},
+		{
+			schema: referenceSchema,
+			key: "Reference"
+		}
+	];
+	for (const { schema, key } of checks) {
+		if (isRawElement(rawElement, schema)) {
+			return {
+				storageKey: rawElement.storageKey,
+				label: rawElement.data.label.trim(),
+				type: key
+			};
+		}
+	}
+});

package/dist/elements/link/storage.d.ts

@@ -2,7 +2,7 @@ import type { TopicPart } from '@erudit-js/core/content/topic';
 import type { ContentType } from '@erudit-js/core/content/type';
 import type { PreviewRequest } from '@erudit-js/core/preview/request';
 import type { LinkToProp } from './core.js';
-export type LinkStorageType = 'direct' | 'contentItem' | 'unique';
+export type LinkStorageType = 'external' | 'contentItem' | 'unique';
 interface LinkStorageBase {
     type: LinkStorageType;
     resolvedHref: string;
@@ -16,8 +16,8 @@ export type LinkStorageContent = {
 } | {
     contentType: Exclude<ContentType, 'topic'>;
 });
-export interface DirectLinkStorage extends LinkStorageBase {
-    type: 'direct';
+export interface ExternalLinkStorage extends LinkStorageBase {
+    type: 'external';
 }
 export interface ContentItemLinkStorage extends LinkStorageBase {
     type: 'contentItem';
@@ -29,6 +29,10 @@ export interface UniqueLinkStorage extends LinkStorageBase {
     elementTitle?: string;
     content: LinkStorageContent;
 }
-export type LinkStorage = DirectLinkStorage | ContentItemLinkStorage | UniqueLinkStorage;
-export declare function createLinkStorageKey(to: LinkToProp, tagName: string): string;
+export interface ErrorLinkStorage {
+    type: 'error';
+    error: string;
+}
+export type LinkStorage = ExternalLinkStorage | ContentItemLinkStorage | UniqueLinkStorage | ErrorLinkStorage;
+export declare function createLinkStorageKey(to: LinkToProp): string;
 export {};

package/dist/elements/link/storage.js

@@ -1,7 +1,7 @@
-import { isUnique, ProseError } from "@jsprose/core";
+import { isUnique } from "@jsprose/core";
 import { parseDocumentId } from "@erudit-js/core/prose/documentId";
 import { getGlobalContentPath, isGlobalContent } from "@erudit-js/core/content/global";
-export function createLinkStorageKey(to, tagName) {
+export function createLinkStorageKey(to) {
 	if (isUnique(to)) {
 		const documentId = parseDocumentId(to.documentId);
 		if (documentId.type === "contentPage") {
@@ -14,7 +14,7 @@ export function createLinkStorageKey(to, tagName) {
 		return `<link:global>/${getGlobalContentPath(to)}`;
 	}
 	if (typeof to === "string") {
-		return `<link:direct>/${to}`;
+		return `<link:external>/${to}`;
 	}
-	throw new ProseError(`<${tagName}> is unable to resolve "to" prop value!`);
+	return `<link:unknown>/${JSON.stringify(to)}`;
 }

package/dist/elements/math/_global.d.ts

@@ -43,6 +43,9 @@ export const M = '_tag_';
  *
  * Use `freeze` prop to prevent line breaks in the rendered math (scrollbars will appear if the content overflows).
  *
+ * You can also create flexible "breaking" gaps between expressions using `>>`, `>>{0|small|big|100px}` delimiters.
+ * Also you can specify the vertical aligment of such gaps using `>>{top|center|bottom}`.
+ *
  * @title Block Math
  * @layout block
  * @example
@@ -54,6 +57,10 @@ export const M = '_tag_';
  * <BlockMath freeze>{math`
  *   \lim\limits_{x \to \infty} \frac{1}{x} = 0
  * `}</BlockMath>
+ *
+ * <BlockMath>{math`
+ *   a^2 >> b^2 >>{big} c^2 >>{top} \sqrt{a^2 + b^2} >>{small}{bottom} \frac{a^2 + b^2}{c^2}
+ * `}</BlockMath>
  * ```
  */
 export const BlockMath = '_tag_';

package/dist/elements/math/block.d.ts

@@ -1,6 +1,7 @@
 import { type TagChildren } from '@jsprose/core';
 export declare const mathGroupTypes: readonly ["0", "small", "normal", "big"];
 export type MathGroupGapType = (typeof mathGroupTypes)[number] | 'custom';
+export type MathGroupAlignItems = 'top' | 'center' | 'bottom';
 export interface MathGroupGapTemplate {
     type: MathGroupGapType;
 }
@@ -24,6 +25,7 @@ export type MathGroupGap = MathGroupGapZero | MathGroupGapSmall | MathGroupGapNo
 export type MathGroupPart = string | MathGroup;
 export interface MathGroup {
     gap: MathGroupGap;
+    alignItems?: MathGroupAlignItems;
     parts: MathGroupPart[];
 }
 export declare function resolveMathGroups(katex: string, isTopLevel?: boolean): Promise<MathGroup | string>;

package/dist/elements/math/block.js

@@ -7,71 +7,84 @@ export const mathGroupTypes = [
 	"normal",
 	"big"
 ];
-function gapFromString(strGap) {
-	if (mathGroupTypes.includes(strGap)) {
-		return { type: strGap };
+const alignValues = [
+	"top",
+	"center",
+	"bottom"
+];
+function isAlignValue(value) {
+	return alignValues.includes(value);
+}
+function gapFromString(str) {
+	if (mathGroupTypes.includes(str)) {
+		return { type: str };
 	}
 	return {
 		type: "custom",
-		size: strGap
+		size: str
 	};
 }
 function gapsEqual(gap1, gap2) {
-	if (gap1.type !== gap2.type) {
-		return false;
-	}
+	if (gap1.type !== gap2.type) return false;
 	if (gap1.type === "custom" && gap2.type === "custom") {
 		return gap1.size === gap2.size;
 	}
 	return true;
 }
 export async function resolveMathGroups(katex, isTopLevel = true) {
-	// If whole string does not contain any groups, return default group with rendered math
 	if (!katex.includes(">>")) {
 		const rendered = await latexToHtml(katex, "block");
 		if (isTopLevel) {
-			// Only top-level should return a group
 			return {
 				gap: { type: "normal" },
 				parts: [rendered]
 			};
 		}
-		// Recursive left side should return a plain string
 		return rendered;
 	}
-	// Find the rightmost delimiter and its gap specification
-	const delimiterRegex = />>(?:\{([^}]+)\})?/g;
+	const delimiterRegex = />>(?:\{([^}]+)\})?(?:\{([^}]+)\})?/g;
 	let match;
-	let lastDelimiterMatch;
+	let last;
 	while ((match = delimiterRegex.exec(katex)) !== null) {
-		lastDelimiterMatch = match;
+		last = match;
+	}
+	const raw1 = last[1];
+	const raw2 = last[2];
+	let gap = { type: "normal" };
+	let alignItems;
+	// ---- Resolution rules ----
+	if (raw1 && raw2) {
+		// >>{gap}{align}
+		gap = gapFromString(raw1);
+		if (isAlignValue(raw2)) alignItems = raw2;
+	} else if (raw1) {
+		// >>{something}
+		if (isAlignValue(raw1)) {
+			// >>{center}
+			alignItems = raw1;
+		} else {
+			// >>{small} or custom gap
+			gap = gapFromString(raw1);
+		}
 	}
-	// Extract gap
-	const gap = gapFromString(lastDelimiterMatch[1] || "normal");
-	// Calculate positions
-	const lastDelimiterPos = lastDelimiterMatch.index;
-	const lastDelimiterLen = lastDelimiterMatch[0].length;
-	// Split the katex string
-	const leftPart = katex.slice(0, lastDelimiterPos);
-	const rightPart = katex.slice(lastDelimiterPos + lastDelimiterLen);
-	// Pushing rendered right part
-	const parts = [await latexToHtml(rightPart, "block")];
-	// Resolving left part
-	const leftGroup = await resolveMathGroups(leftPart, false);
+	const delimiterPos = last.index;
+	const delimiterLen = last[0].length;
+	const left = katex.slice(0, delimiterPos);
+	const right = katex.slice(delimiterPos + delimiterLen);
+	const parts = [await latexToHtml(right, "block")];
+	const leftGroup = await resolveMathGroups(left, false);
 	if (typeof leftGroup === "string") {
 		parts.unshift(leftGroup);
 	} else {
-		// Left part is a group, meaning it contains gaps
 		if (gapsEqual(leftGroup.gap, gap)) {
-			// If gaps are equal, we can merge the two groups into (current) one
 			parts.unshift(...leftGroup.parts);
 		} else {
-			// Gaps are different, we need to keep the left group as is
 			parts.unshift(leftGroup);
 		}
 	}
 	return {
 		gap,
+		...alignItems ? { alignItems } : {},
 		parts
 	};
 }

package/dist/elements/math/components/MathGroup.vue

@@ -7,7 +7,7 @@ const { mathGroup } = defineProps<{
   freeze: boolean;
 }>();
 
-const columnGap = (() => {
+const gap = (() => {
   switch (mathGroup.gap.type) {
     case '0':
       return '0px';
@@ -21,12 +21,29 @@ const columnGap = (() => {
       return mathGroup.gap.size;
   }
 })();
+
+const alignItems = (() => {
+  switch (mathGroup.alignItems ?? 'center') {
+    case 'top':
+      return 'flex-start';
+    case 'bottom':
+      return 'flex-end';
+    case 'center':
+    default:
+      return 'center';
+  }
+})();
 </script>
 
 <template>
   <div
-    :style="{ columnGap }"
-    class="flex flex-wrap items-center justify-center gap-y-(--mathRowGap)"
+    :style="{
+      '--mathGroupGap': gap,
+      gap: 'var(--mathGroupGap)',
+      rowGap: 'calc(var(--mathGroupGap)/2)',
+      alignItems,
+    }"
+    class="flex flex-wrap justify-center"
   >
     <template v-for="part of mathGroup.parts">
       <Katex

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

@@ -1,16 +1,21 @@
 import type { ProblemCustomAttribute as PAC } from './shared.js';
+import type { ProblemRandom as _ProblemRandom } from './rng.js';
 
 /**
  * Problems are used to present exercises and questions to the reader.
- * See the example for a full breakdown of the sub-elements available.
  *
- * All problems are added to TOC and search by default (can be disabled via tag properties).
+ * Allowed children inside `<Problem>`:
+ * - `<ProblemDescription>`
+ * - `<ProblemCheck>` (repeatable)
+ * - `<ProblemHint>` (repeatable)
+ * - `<ProblemAnswer>` (optionally with `<ProblemSection>`)
+ * - `<ProblemSolution>` (optionally with `<ProblemSection>`)
+ * - `<ProblemNote>` (optionally with `<ProblemSection>`)
  *
  * @title Problem
  * @layout block
  * @example
  * ```tsx
- * // Static problem
  * <Problem title="Find the square" level="easy">
  *   <ProblemDescription>
  *     <P>What is the square of 2?</P>
@@ -40,52 +45,162 @@ import type { ProblemCustomAttribute as PAC } from './shared.js';
  *   </ProblemAnswer>
  *
  *   <ProblemCheck label="The square of 2 is" answer={4} />
- *   // More checks...
  *
  *   <ProblemNote>
  *     In fact, you can find the square of any number by multiplying it by itself!
  *   </ProblemNote>
  * </Problem>
- *
- * // Script problem
- * export const fooScript = defineProblemScript({
- *   isGenerator: true,
- * })(({ initial, random }) => {
- *   const a = initial.nextInt(1, 10);
- *   const b = initial.nextInt(1, 10);
- *
- *   return (
- *     <>
- *       <ProblemDescription>
- *         What is <M>{a} + {b}</M>?
- *       </ProblemDescription>
- *       <ProblemAnswer>
- *         <M>{a + b}</M>
- *       </ProblemAnswer>
- *       <ProblemCheck label="The answer is" answer={a + b} />
- *     </>
- *   );
- * });
- *
- * <Problem title="Addition Problem" level="medium" script={fooScript} />
  * ```
  */
 export const Problem = '_tag_';
+
+/**
+ * Problem description.
+ *
+ * Can be used inside `<Problem>` or `<SubProblem>`.
+ *
+ * @title ProblemDescription
+ * @layout block
+ * @example
+ * ```tsx
+ * <ProblemDescription>
+ *   <P>State the problem in your own words.</P>
+ * </ProblemDescription>
+ * ```
+ */
 export const ProblemDescription = '_tag_';
+
+/**
+ * A hint for the problem. Multiple hints can be provided.
+ *
+ * Can be used inside `<Problem>` or `<SubProblem>`.
+ *
+ * @title ProblemHint
+ * @layout block
+ * @example
+ * ```tsx
+ * <ProblemHint>
+ *   <P>Try rewriting the expression in a simpler form.</P>
+ * </ProblemHint>
+ * ```
+ */
 export const ProblemHint = '_tag_';
+
+/**
+ * A titled section used inside `<ProblemSolution>` or `<ProblemAnswer>`.
+ *
+ * @title ProblemSection
+ * @layout block
+ * @example
+ * ```tsx
+ * <ProblemSection title="Method">
+ *   <P>Show the steps.</P>
+ * </ProblemSection>
+ * ```
+ */
 export const ProblemSection = '_tag_';
+
+/**
+ * The problem solution.
+ *
+ * Can contain plain content and `<ProblemSection>` blocks.
+ * Can be used inside `<Problem>` or `<SubProblem>`.
+ *
+ * @title ProblemSolution
+ * @layout block
+ * @example
+ * ```tsx
+ * <ProblemSolution>
+ *   <P>Start with the key idea.</P>
+ *
+ *   <ProblemSection title="Details">
+ *     <P>Then provide the full derivation.</P>
+ *   </ProblemSection>
+ * </ProblemSolution>
+ * ```
+ */
 export const ProblemSolution = '_tag_';
+
+/**
+ * The final answer (usually concise).
+ *
+ * Can contain plain content and `<ProblemSection>` blocks.
+ * Can be used inside `<Problem>` or `<SubProblem>`.
+ *
+ * @title ProblemAnswer
+ * @layout block
+ * @example
+ * ```tsx
+ * <ProblemAnswer>
+ *   <P><M>42</M></P>
+ * </ProblemAnswer>
+ * ```
+ */
 export const ProblemAnswer = '_tag_';
+
+/**
+ * A note shown after the checks/solution.
+ *
+ * Can be used inside `<Problem>` or `<SubProblem>`.
+ *
+ * @title ProblemNote
+ * @layout block
+ * @example
+ * ```tsx
+ * <ProblemNote>
+ *   Remember to double-check units.
+ * </ProblemNote>
+ * ```
+ */
 export const ProblemNote = '_tag_';
+
+/**
+ * Defines an answer check for a problem.
+ *
+ * Can be used inside `<Problem>` or `<SubProblem>`.
+ *
+ * Validator props (exactly one per `<ProblemCheck>`):
+ * - `yes`: boolean-like answer, validated via locale yes/no patterns.
+ * - `no`: boolean-like answer, validated via locale yes/no patterns.
+ * - `answer`: exact expected value.
+ *   - `number` -> numeric equality
+ *   - `string` -> exact string match
+ *   - `RegExp` -> `test()` match
+ *   - `undefined` -> expects an empty answer
+ * - `answers`: multi-part answer (split by `separator`, default `,`, unordered by default).
+ *   - Use `{ ordered, separator, values }` to configure matching.
+ *   - Each position in `values` can be a single expected value or an array of expected values (any-of).
+ * - `script`: named script validator.
+ *
+ * You can nest `<ProblemCheck>` inside another `<ProblemCheck>` to group multiple checks.
+ *
+ * @title ProblemCheck
+ * @layout block
+ * @example
+ * ```tsx
+ * <ProblemCheck label="2 is even" yes />
+ * <ProblemCheck label="Enter nothing" answer={undefined} />
+ * <ProblemCheck label="The square of 2 is" answer={4} />
+ * <ProblemCheck
+ *   label="Enter roots"
+ *   answers={{ ordered: false, separator: ',', values: [2, [-2, /-?2/]] }}
+ * />
+ * <ProblemCheck script="myCustomValidator" />
+ *
+ * <ProblemCheck label="Grouped checks" yes>
+ *   <ProblemCheck label="Also accept 42" answer={42} />
+ * </ProblemCheck>
+ * ```
+ */
 export const ProblemCheck = '_tag_';
 
 /**
  * Problem set is a collection of related problems presented together.
- * `<Problems>` tag contains general problem information and insude can have multiple `<SubProblem>` tags.
  *
- * Each `<SubProblem>` contains the same problem content tags as single `<Problem>` tag.
+ * Allowed children inside `<Problems>`:
+ * - `<SubProblem>` (repeatable)
  *
- * All problems are added to TOC and search by default (can be disabled via tag properties).
+ * Each `<SubProblem>` can contain the same child tags as `<Problem>`.
  *
  * @title Problems
  * @layout block
@@ -104,9 +219,39 @@ export const ProblemCheck = '_tag_';
  * ```
  */
 export const Problems = '_tag_';
+
+/**
+ * A single problem inside a `<Problems>` set.
+ *
+ * Allowed children inside `<SubProblem>`:
+ * - `<ProblemDescription>`
+ * - `<ProblemHint>` (repeatable)
+ * - `<ProblemSolution>` (optionally with `<ProblemSection>`)
+ * - `<ProblemAnswer>` (optionally with `<ProblemSection>`)
+ * - `<ProblemCheck>` (repeatable)
+ * - `<ProblemNote>`
+ *
+ * @title SubProblem
+ * @layout block
+ * @example
+ * ```tsx
+ * <SubProblem label="A">
+ *   <ProblemDescription>
+ *     <P>Solve for <M>x</M>.</P>
+ *   </ProblemDescription>
+ *
+ *   <ProblemCheck answer={42} />
+ * </SubProblem>
+ * ```
+ */
 export const SubProblem = '_tag_';
 
 /**
  * Typeguard for creating custom problem attributes.
  */
 export type ProblemCustomAttribute = PAC;
+
+/**
+ * Typeguard for problem RNG.
+ */
+export type ProblemRandom = _ProblemRandom;

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

@@ -5,13 +5,6 @@ declare const _default: (import("../../app/appElement.js").AppElement<{
     Data: import("./problem.js").ProblemData;
     Storage: import("./storage.js").ProblemScriptStorage;
     Children: import("./problemContent.js").ProblemContentChild[];
-}> | import("../../app/appElement.js").AppElement<{
-    name: "subProblem";
-    type: "block";
-    linkable: false;
-    Data: import("./problems.js").SubProblemData;
-    Storage: import("./storage.js").ProblemScriptStorage;
-    Children: import("./problemContent.js").ProblemContentChild[];
 }> | import("../../app/appElement.js").AppElement<{
     name: "problems";
     type: "block";
@@ -26,5 +19,12 @@ declare const _default: (import("../../app/appElement.js").AppElement<{
         Storage: import("./storage.js").ProblemScriptStorage;
         Children: import("./problemContent.js").ProblemContentChild[];
     })[];
+}> | import("../../app/appElement.js").AppElement<{
+    name: "subProblem";
+    type: "block";
+    linkable: false;
+    Data: import("./problems.js").SubProblemData;
+    Storage: import("./storage.js").ProblemScriptStorage;
+    Children: import("./problemContent.js").ProblemContentChild[];
 }>)[];
 export default _default;

package/dist/elements/problem/app.js

@@ -1,27 +1,28 @@
 import { defineEruditProseAppElement } from "../../app/appElement.js";
 import { problemSchema } from "./problem.js";
 import { problemsSchema, subProblemSchema } from "./problems.js";
+const icon = () => import("./assets/icon.svg?raw");
 export default [
 	defineEruditProseAppElement({
 		schema: problemSchema,
 		component: () => import("./components/Problem.vue"),
+		icon,
 		languages: {
-			en: () => import("./languages/en.js"),
-			ru: () => import("./languages/ru.js")
-		},
-		icon: () => import("./assets/icon.svg?raw")
-	}),
-	defineEruditProseAppElement({
-		schema: subProblemSchema,
-		component: () => import("./components/SubProblem.vue")
+			en: () => import("./languages/problem/en.js"),
+			ru: () => import("./languages/problem/ru.js")
+		}
 	}),
 	defineEruditProseAppElement({
 		schema: problemsSchema,
 		component: () => import("./components/Problems.vue"),
+		icon,
 		languages: {
-			en: () => import("./languages/en.js"),
-			ru: () => import("./languages/ru.js")
-		},
-		icon: () => import("./assets/icon.svg?raw")
+			en: () => import("./languages/problems/en.js"),
+			ru: () => import("./languages/problems/ru.js")
+		}
+	}),
+	defineEruditProseAppElement({
+		schema: subProblemSchema,
+		component: () => import("./components/SubProblem.vue")
 	})
 ];