@jxsuite/parser 2.0.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -48,8 +48,8 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.4.12",
-    "@jxsuite/schema": "^3.0.0",
+    "@jxsuite/markup": "^0.4.13",
+    "@jxsuite/schema": "^4.0.0",
     "@shikijs/langs": "^4.5.0",
     "@shikijs/themes": "^4.5.0",
     "glob": "^13.0.6",
@@ -66,8 +66,8 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.14.6",
-    "@jxsuite/runtime": "^4.1.0",
+    "@happy-dom/global-registrator": "^21.0.3",
+    "@jxsuite/runtime": "^5.0.0",
     "@types/mdast": "^4.0.4",
     "ajv": "^8.20.0"
   },

package/src/alerts.ts

@@ -21,10 +21,25 @@
  * @docs framework/site/jx-markdown
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+
 import type { MdastNode } from "./types.ts";
 
+/**
+ * Default titles by lower-case alert type: GitHub's five are always present, and the renderer looks
+ * up whatever type an author wrote, so a type a project switched on itself reads as absent.
+ */
+export interface AlertTitles extends Readonly<Record<string, string>> {
+  readonly caution: string;
+  readonly important: string;
+  readonly note: string;
+  readonly tip: string;
+  readonly warning: string;
+}
+
 /** The five alert types GitHub defines, and the title each shows by default. */
-export const DEFAULT_ALERT_TITLES: Readonly<Record<string, string>> = {
+export const DEFAULT_ALERT_TITLES: AlertTitles = {
   caution: "Caution",
   important: "Important",
   note: "Note",
@@ -60,7 +75,7 @@ const TAG_NAME = /^[A-Za-z][\w.-]*$/;
  * Throws on a value that is not a tag name so a typo in `project.json` fails the build where it was
  * written rather than rendering a callout as an unknown element.
  */
-export function normalizeAlerts(config?: unknown, where = "alerts"): AlertSettings | null {
+export function normalizeAlerts(config?: JsonValue, where = "alerts"): AlertSettings | null {
   if (config === false) {
     return null;
   }
@@ -71,7 +86,7 @@ export function normalizeAlerts(config?: unknown, where = "alerts"): AlertSettin
   if (config === undefined || config === true) {
     return { disabled, types };
   }
-  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+  if (!isJsonObject(config)) {
     throw new TypeError(
       `${where}: expected an object mapping alert types to element names, or false`,
     );
@@ -86,7 +101,7 @@ export function normalizeAlerts(config?: unknown, where = "alerts"): AlertSettin
       disabled.add(key);
     } else if (element === true) {
       types.set(key, null);
-    } else if (typeof element === "string" && TAG_NAME.test(element)) {
+    } else if (isString(element) && TAG_NAME.test(element)) {
       types.set(key, element);
     } else {
       throw new TypeError(
@@ -114,7 +129,7 @@ const MARKER = /^\[!([A-Za-z][\w-]*)\][+-]?/;
 export function inlineText(nodes: readonly MdastNode[]): string {
   let out = "";
   for (const node of nodes) {
-    if (typeof node.value === "string") {
+    if (node.value !== undefined) {
       out += node.value;
     } else if (node.children) {
       out += inlineText(node.children);
@@ -139,7 +154,7 @@ const LINE_END = /\r?\n/;
  */
 function markerOf(paragraph: MdastNode): { type: string; rest: string } | null {
   const [first] = paragraph.children ?? [];
-  if (first?.type !== "text" || typeof first.value !== "string") {
+  if (first?.type !== "text" || first.value === undefined) {
     return null;
   }
   const match = MARKER.exec(first.value);
@@ -178,7 +193,7 @@ function splitMarker(
   const take = (node: MdastNode) => {
     if (inTitle && node.type === "break") {
       inTitle = false;
-    } else if (inTitle && node.type === "text" && typeof node.value === "string") {
+    } else if (inTitle && node.type === "text" && node.value !== undefined) {
       const lineEnd = LINE_END.exec(node.value);
       if (lineEnd === null) {
         title.push(node);

package/src/content-data.ts

@@ -0,0 +1,40 @@
+/**
+ * Content-data — how a reader gets entries out of the `content` section's loaded data.
+ *
+ * The section's data is a map of type name to entries, which the content loader's `ContentStore`
+ * may fill on demand (specs/extensions.md §8). This module is the reading side alone, with no Node
+ * imports, because `ContentCollection` and `ContentEntry` (content.ts) are bundled on their own and
+ * must not pull the loader in with them.
+ *
+ * @module @jxsuite/parser/content-data
+ * @docs extending/extensions/project-sections
+ */
+
+import type { ContentLoaderEntry } from "./types.ts";
+
+/**
+ * The `content` section's loaded data as a reader sees it: a map of type name to entries. `load`
+ * and `materialize` are optional so a plain map (one a host or a test built) reads the same way.
+ */
+export interface ContentSectionData extends ReadonlyMap<string, ContentLoaderEntry[]> {
+  /** One type's entries, loading the type first if it has not been. */
+  load?: (name: string) => Promise<ContentLoaderEntry[] | undefined>;
+  /** Give these entries (and the entries they relate to) their bodies before they are returned. */
+  materialize?: (entries: readonly (ContentLoaderEntry | null | undefined)[]) => Promise<void>;
+  /** Load every type and every body, so a synchronous `get` sees the whole section. */
+  complete?: () => Promise<void>;
+}
+
+/**
+ * One type's entries from a section's data, loading the type first when the data loads lazily.
+ *
+ * @param {ContentSectionData | undefined} data - The section's loaded data
+ * @param {string} name - Content type name
+ * @returns {Promise<ContentLoaderEntry[] | undefined>} The entries, or undefined for no such type
+ */
+export async function entriesOf(
+  data: ContentSectionData | undefined,
+  name: string,
+): Promise<ContentLoaderEntry[] | undefined> {
+  return (await data?.load?.(name)) ?? data?.get(name);
+}

package/src/content-links.ts

@@ -30,6 +30,7 @@
  * @docs framework/site/content-collections
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JxElement } from "@jxsuite/schema/types";
 import { routeHref } from "./content-routes.ts";
 import type { ContentNodes } from "./inert.ts";
@@ -102,8 +103,15 @@ function fragmentFor(raw: string): string {
   }
 }
 
+/** The three parts of an href; `query` and `hash` keep their delimiter and are `""` when absent. */
+interface HrefParts {
+  path: string;
+  query: string;
+  hash: string;
+}
+
 /** Split `path?query#fragment` into its three parts (query and fragment keep their delimiter). */
-function splitHref(href: string): { path: string; query: string; hash: string } {
+function splitHref(href: string): HrefParts {
   const hashAt = href.indexOf("#");
   const beforeHash = hashAt === -1 ? href : href.slice(0, hashAt);
   const hash = hashAt === -1 ? "" : href.slice(hashAt);
@@ -288,13 +296,13 @@ function resolveHref(href: string, from: string, index: LinkIndex): Resolution {
 /** What a removed anchor leaves behind: its own content, as inline nodes. */
 function contentOf(anchor: JxElement): ContentNodes {
   if (Array.isArray(anchor.children)) {
-    return anchor.children as ContentNodes;
+    return anchor.children;
   }
-  if (typeof anchor.innerHTML === "string") {
+  if (anchor.innerHTML !== undefined) {
     // Text that holds `${` was made inert as escaped `innerHTML` (inert.ts); it keeps that form.
     return [{ innerHTML: anchor.innerHTML, tagName: "span" }];
   }
-  return typeof anchor.textContent === "string" ? [anchor.textContent] : [];
+  return isString(anchor.textContent) ? [anchor.textContent] : [];
 }
 
 /**
@@ -318,11 +326,11 @@ export function rewriteLinks(
       rewriteLinks(node, from, index, report);
       continue;
     }
-    if (typeof node !== "object" || node === null) {
+    if (!isNonNullObject(node)) {
       continue;
     }
     const href = node.tagName === "a" ? node.attributes?.href : undefined;
-    if (typeof href === "string") {
+    if (isString(href)) {
       const resolution = resolveHref(href, from, index);
       if ("problem" in resolution) {
         report({ href, reason: resolution.problem });
@@ -337,7 +345,7 @@ export function rewriteLinks(
       }
     }
     if (Array.isArray(node.children)) {
-      rewriteLinks(node.children as ContentNodes, from, index, report);
+      rewriteLinks(node.children, from, index, report);
     }
   }
 }