@jxsuite/parser 1.8.2 → 2.0.0

package/dist/serialize.js

@@ -39288,6 +39288,148 @@ var require_dist2 = __commonJS(function(exports, module) {
   module.exports = plugin;
 });
 
+// src/alerts.ts
+function normalizeAlerts(config, where = "alerts") {
+  if (config === false) {
+    return null;
+  }
+  const types = new Map(Object.keys(DEFAULT_ALERT_TITLES).map((type) => [type, null]));
+  const disabled = new Set;
+  if (config === undefined || config === true) {
+    return { disabled, types };
+  }
+  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+    throw new TypeError(`${where}: expected an object mapping alert types to element names, or false`);
+  }
+  for (const [type, element] of Object.entries(config)) {
+    const key = type.toLowerCase();
+    if (!/^[a-z][\w-]*$/.test(key)) {
+      throw new TypeError(`${where}: "${type}" is not a valid alert type name`);
+    }
+    if (element === false || element === null) {
+      types.delete(key);
+      disabled.add(key);
+    } else if (element === true) {
+      types.set(key, null);
+    } else if (typeof element === "string" && TAG_NAME.test(element)) {
+      types.set(key, element);
+    } else {
+      throw new TypeError(`${where}.${type}: expected an element name such as "doc-note", true or false, got ${JSON.stringify(element)}`);
+    }
+  }
+  return { disabled, types };
+}
+function inlineText(nodes) {
+  let out = "";
+  for (const node of nodes) {
+    if (typeof node.value === "string") {
+      out += node.value;
+    } else if (node.children) {
+      out += inlineText(node.children);
+    }
+  }
+  return out;
+}
+function textNode(value) {
+  return { type: "text", value };
+}
+function markerOf(paragraph) {
+  const [first] = paragraph.children ?? [];
+  if (first?.type !== "text" || typeof first.value !== "string") {
+    return null;
+  }
+  const match = MARKER2.exec(first.value);
+  if (!match) {
+    return null;
+  }
+  const rest = first.value.slice(match[0].length);
+  if (rest !== "" && !/^[ \t\r\n]/.test(rest)) {
+    return null;
+  }
+  return { rest, type: match[1].toLowerCase() };
+}
+function splitMarker(paragraph, settings) {
+  const marker = markerOf(paragraph);
+  if (!marker || !settings.types.has(marker.type)) {
+    return null;
+  }
+  const { type, rest } = marker;
+  const [, ...siblings] = paragraph.children ?? [];
+  const title = [];
+  const body = [];
+  let inTitle = true;
+  const take = (node) => {
+    if (inTitle && node.type === "break") {
+      inTitle = false;
+    } else if (inTitle && node.type === "text" && typeof node.value === "string") {
+      const lineEnd = LINE_END.exec(node.value);
+      if (lineEnd === null) {
+        title.push(node);
+      } else {
+        title.push(textNode(node.value.slice(0, lineEnd.index)));
+        inTitle = false;
+        body.push(textNode(node.value.slice(lineEnd.index + lineEnd[0].length)));
+      }
+    } else {
+      (inTitle ? title : body).push(node);
+    }
+  };
+  take(textNode(rest.replace(/^[ \t]+/, "")));
+  for (const node of siblings) {
+    take(node);
+  }
+  const trimmed = title.filter((node) => !(node.type === "text" && node.value === ""));
+  const text = inlineText(trimmed);
+  return {
+    body: body.filter((node) => !(node.type === "text" && node.value === "")),
+    title: text.trim() === "" ? [] : trimmed,
+    type
+  };
+}
+function transformAlerts(tree, settings, onUnknown) {
+  const { children } = tree;
+  if (!children) {
+    return;
+  }
+  for (const [i, child] of children.entries()) {
+    if (child.type === "blockquote") {
+      const [paragraph, ...rest] = child.children ?? [];
+      const split = paragraph?.type === "paragraph" ? splitMarker(paragraph, settings) : null;
+      if (split) {
+        const bodyParagraph = split.body.length > 0 && inlineText(split.body).trim() !== "" ? [{ children: split.body, type: "paragraph" }] : [];
+        const alert = {
+          alert: split.type,
+          children: [...bodyParagraph, ...rest],
+          element: settings.types.get(split.type) ?? null,
+          titleNodes: split.title.length > 0 ? split.title : null,
+          type: ALERT_NODE
+        };
+        children[i] = alert;
+        transformAlerts(alert, settings, onUnknown);
+        continue;
+      }
+      const unknown = paragraph?.type === "paragraph" ? markerOf(paragraph) : null;
+      if (unknown && !settings.disabled.has(unknown.type)) {
+        onUnknown?.(unknown.type);
+      }
+    }
+    transformAlerts(child, settings, onUnknown);
+  }
+}
+var DEFAULT_ALERT_TITLES, ALERT_NODE = "jxAlert", TAG_NAME, MARKER2, LINE_END;
+var init_alerts = __esm(() => {
+  DEFAULT_ALERT_TITLES = {
+    caution: "Caution",
+    important: "Important",
+    note: "Note",
+    tip: "Tip",
+    warning: "Warning"
+  };
+  TAG_NAME = /^[A-Za-z][\w.-]*$/;
+  MARKER2 = /^\[!([A-Za-z][\w-]*)\][+-]?/;
+  LINE_END = /\r?\n/;
+});
+
 // src/transpile.ts
 function jxKey(key) {
   if (JX_DOLLAR_KEYS.has(key)) {
@@ -39360,6 +39502,9 @@ function mdastNodeToJx(node) {
   if (node.type === "containerDirective" || node.type === "leafDirective" || node.type === "textDirective") {
     return directiveToJx(node);
   }
+  if (node.type === ALERT_NODE) {
+    return alertToJx(node);
+  }
   if (node.type === "text") {
     return node.value ?? null;
   }
@@ -39472,6 +39617,37 @@ function mdastNodeToJx(node) {
   }
   return el;
 }
+function alertToJx(node) {
+  const body = convertChildren(node.children ?? []);
+  if (node.element) {
+    const attributes = { "data-alert": node.alert };
+    if (node.titleNodes) {
+      attributes["data-title"] = inlineText(node.titleNodes).trim();
+    }
+    const el = { attributes, tagName: node.element };
+    if (body.length > 0) {
+      el.children = body;
+    }
+    return el;
+  }
+  const title = { className: "jx-alert-title", tagName: "p" };
+  if (node.titleNodes) {
+    const inline = convertChildren(node.titleNodes);
+    if (inline.length === 1 && typeof inline[0] === "string") {
+      [title.textContent] = inline;
+    } else {
+      title.children = inline;
+    }
+  } else {
+    title.textContent = DEFAULT_ALERT_TITLES[node.alert] ?? `${node.alert.charAt(0).toUpperCase()}${node.alert.slice(1)}`;
+  }
+  return {
+    attributes: { "data-alert": node.alert, role: "note" },
+    children: [title, ...body],
+    className: `jx-alert jx-alert-${node.alert}`,
+    tagName: "div"
+  };
+}
 function directiveToJx(node) {
   if (PROTOTYPE_DIRECTIVE_NAMES.has(node.name)) {
     return prototypeDirectiveToJx(node);
@@ -39665,6 +39841,7 @@ var init_transpile = __esm(() => {
   init_remark_gfm();
   init_remark_directive();
   init_html_to_jx();
+  init_alerts();
   init_html_to_jx();
   import_remark_parse_frontmatter = __toESM(require_dist2(), 1);
   JX_DOLLAR_KEYS = new Set(["prototype", "ref", "component", "props", "switch", "elements"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "1.8.2",
+  "version": "2.0.0",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -48,10 +48,10 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.4.11",
-    "@jxsuite/schema": "^2.3.0",
-    "@shikijs/langs": "^4.4.3",
-    "@shikijs/themes": "^4.4.3",
+    "@jxsuite/markup": "^0.4.12",
+    "@jxsuite/schema": "^3.0.0",
+    "@shikijs/langs": "^4.5.0",
+    "@shikijs/themes": "^4.5.0",
     "glob": "^13.0.6",
     "mdast-util-to-string": "^4.0.0",
     "remark-directive": "^4.0.0",
@@ -60,14 +60,14 @@
     "remark-parse": "^11.0.0",
     "remark-parse-frontmatter": "^1.0.3",
     "remark-stringify": "^11.0.0",
-    "shiki": "^4.4.3",
+    "shiki": "^4.5.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.14.5",
-    "@jxsuite/runtime": "^4.0.2",
+    "@jxsuite/runtime": "^4.0.3",
     "@types/mdast": "^4.0.4",
     "ajv": "^8.20.0"
   },

package/schemas/project.fragment.schema.json

@@ -9,7 +9,7 @@
       "description": "File-based content collections. Each key names a content type; entries are loaded from the named source through the format registry.",
       "type": "object",
       "additionalProperties": {
-        "description": "Content type definition. Defines the source directory, frontmatter schema, and element dependencies.",
+        "description": "Content type definition. Defines the source, how entries are filtered, identified and routed, and their schema and element dependencies.",
         "type": "object",
         "properties": {
           "$elements": {
@@ -19,10 +19,16 @@
               "oneOf": [
                 {
                   "type": "object",
-                  "properties": { "$ref": { "type": "string" } },
+                  "properties": {
+                    "$ref": {
+                      "type": "string"
+                    }
+                  },
                   "required": ["$ref"]
                 },
-                { "type": "string" }
+                {
+                  "type": "string"
+                }
               ]
             }
           },
@@ -34,16 +40,22 @@
             "description": "JSON Schema for validating frontmatter of content type entries.",
             "type": "object",
             "properties": {
-              "type": { "const": "object" },
+              "type": {
+                "const": "object"
+              },
               "properties": {
                 "description": "Field definitions; values are field schemas from the effective project field union.",
                 "type": "object",
-                "additionalProperties": { "$ref": "https://jxsuite.com/schema/project/fields/v2" }
+                "additionalProperties": {
+                  "$ref": "https://jxsuite.com/schema/project/fields/v2"
+                }
               },
               "required": {
                 "description": "Frontmatter fields every entry must provide.",
                 "type": "array",
-                "items": { "type": "string" }
+                "items": {
+                  "type": "string"
+                }
               }
             }
           },
@@ -51,6 +63,126 @@
             "description": "Path to the content directory relative to the project root.",
             "examples": ["./content/blog/", "./content/docs/"],
             "type": "string"
+          },
+          "exclude": {
+            "description": "Glob patterns, relative to the source directory, for files that are never read: `internal/**`, `STYLE.md`, `**/node_modules/**`, `.*/**`. `*` and `?` stop at `/`, `**` crosses directories, `{a,b}` alternates, and dotfiles are ordinary files. A bare name with no extension (`internal`) excludes that folder as well as a file of the name. A pattern cannot climb out of the source (`../`). Excluded files are not parsed, validated, routed, linked to, searched or published, and the collection's asset mount does not serve them either: a note that refers to one gets a warning and the reference is left as written.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "examples": [["internal/**", "STYLE.md", ".*/**", "**/node_modules/**"]]
+          },
+          "where": {
+            "description": "Declarative frontmatter filter: only entries whose frontmatter satisfies every key are kept. A value is a literal to equal (a scalar also matches an array field that contains it; an array or an object with no `$` keys is compared whole) or an operator object: `$eq`, `$ne`, `$in`, `$nin`, `$exists`, `$gt`, `$gte`, `$lt`, `$lte`. Keys combine with AND; there is no OR and nothing is evaluated. A filter that removes every entry is reported. Filtered entries are not validated, routed, linked to, queried or searched, and are not served from the collection's asset mount.",
+            "type": "object",
+            "propertyNames": {
+              "pattern": "^[^$]"
+            },
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "propertyNames": {
+                    "enum": ["$eq", "$ne", "$in", "$nin", "$exists", "$gt", "$gte", "$lt", "$lte"]
+                  },
+                  "minProperties": 1,
+                  "properties": {
+                    "$eq": {},
+                    "$ne": {},
+                    "$in": {
+                      "type": "array"
+                    },
+                    "$nin": {
+                      "type": "array"
+                    },
+                    "$exists": {
+                      "type": "boolean"
+                    },
+                    "$gt": {
+                      "type": ["string", "number"]
+                    },
+                    "$gte": {
+                      "type": ["string", "number"]
+                    },
+                    "$lt": {
+                      "type": ["string", "number"]
+                    },
+                    "$lte": {
+                      "type": ["string", "number"]
+                    }
+                  }
+                },
+                {
+                  "type": ["string", "number", "boolean", "null", "array"]
+                },
+                {
+                  "type": "object",
+                  "propertyNames": {
+                    "pattern": "^[^$]"
+                  }
+                }
+              ]
+            },
+            "examples": [
+              {
+                "publish": true,
+                "status": {
+                  "$ne": "draft"
+                }
+              }
+            ]
+          },
+          "idField": {
+            "description": "Frontmatter field whose value is the entry id, instead of the path-derived id. An entry without the field keeps its path id and is reported.",
+            "type": "string",
+            "minLength": 1,
+            "examples": ["slug"]
+          },
+          "route": {
+            "description": "A site-absolute path template. `{name}` inserts the entry id (`id`), the file's directory (`dir`), its name (`file`) or a frontmatter field (dotted paths allowed); `{name:slug}` slugifies it, and `lower`, `upper` and `raw` are also available.",
+            "examples": ["/kb/{category:slug}/{slug}/"],
+            "type": "string",
+            "pattern": "^/"
+          },
+          "indexRoute": {
+            "description": "The route template for a directory's `README.md` or `index.md`, the file a folder stands for, when it should differ from `route` (a section's page at `/kb/{dir:slug}/` rather than `/kb/{category:slug}/{slug}/`). It takes the same placeholders and transforms as `route`, and needs a `route` for every other entry.",
+            "examples": ["/kb/{dir:slug}/"],
+            "type": "string",
+            "pattern": "^/"
+          },
+          "links": {
+            "description": "How a relative link to an entry that has no page (excluded, filtered out by `where`, unrouted, or missing) is reported. The link renders as plain text in every mode. Relative links are only rewritten for content types that declare a `route`.",
+            "enum": ["warn", "error", "ignore"],
+            "default": "warn"
+          },
+          "alerts": {
+            "description": "How GitHub-style alerts (`> [!NOTE]`) in Markdown entries render. `false` turns callouts off for the whole type; `true`, or leaving the option out, renders NOTE, TIP, IMPORTANT, WARNING and CAUTION as built-in accessible markup. An object maps an alert type (case-insensitive) to the custom element that renders it, e.g. { \"NOTE\": \"doc-note\" }; `true` renders a type with the built-in markup (how a type beyond GitHub's five, such as Obsidian's `info`, is switched on); null or false leaves a type an ordinary blockquote. A well-formed marker of a type that is not enabled is reported when the file loads.",
+            "type": ["object", "boolean"],
+            "propertyNames": {
+              "pattern": "^[A-Za-z][\\w-]*$"
+            },
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "pattern": "^[A-Za-z][\\w.-]*$"
+                },
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "boolean"
+                }
+              ]
+            },
+            "examples": [
+              {
+                "NOTE": "doc-note",
+                "TIP": "doc-tip",
+                "WARNING": "doc-warning"
+              }
+            ]
           }
         }
       }

package/src/Content.class.json

@@ -115,14 +115,17 @@
               "properties": {
                 "data": { "type": "object" },
                 "projectConfig": { "type": "object" },
-                "root": { "type": "string" }
+                "root": { "type": "string" },
+                "locale": { "type": ["string", "null"] },
+                "urlPattern": { "type": "string" },
+                "params": { "type": "array", "items": { "type": "string" } }
               }
             },
-            "description": "Host context: { data, projectConfig, root } where data is the projectData result"
+            "description": "Host context: { data, projectConfig, root, locale, urlPattern, params } where data is the projectData result and urlPattern/params describe the dynamic page being expanded"
           }
         ],
         "returnType": { "$ref": "#/$defs/returnTypes/PathEntries" },
-        "description": "Expand a content-type $paths source into one route-param object per entry (param defaults to \"slug\", field to \"id\")"
+        "description": "Expand a content-type $paths source into one route-param object per entry (param defaults to \"slug\", field to \"id\"); a content type with a route and no param or field derives each entry's parameters from the page's own URL pattern"
       },
       "assets": {
         "role": "assets",

package/src/Markdown.class.json

@@ -233,12 +233,19 @@
             "identifier": "options",
             "type": {
               "type": "object",
-              "properties": { "baseDir": { "type": "string" } }
+              "properties": {
+                "baseDir": { "type": "string" },
+                "exclude": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Glob patterns, relative to the source directory, for files and directories to leave out"
+                }
+              }
             }
           }
         ],
         "returnType": { "type": "array", "items": { "type": "string" } },
-        "description": "List markdown entry files for a content-type source"
+        "description": "List markdown entry files for a content-type source, in sorted order"
       },
       "load": {
         "role": "load",
@@ -259,7 +266,11 @@
               "type": "object",
               "properties": {
                 "directiveOptions": { "type": "object" },
-                "directives": { "type": "boolean" }
+                "directives": { "type": "boolean" },
+                "alerts": {
+                  "description": "GitHub alert type -> custom element name (or false to leave alerts as blockquotes); absent renders the built-in callouts",
+                  "oneOf": [{ "const": false }, { "type": "object" }]
+                }
               }
             }
           }