@jxsuite/parser 1.4.0 → 1.5.0

package/src/serialize.ts

@@ -19,7 +19,7 @@
  */
 
 import { unified } from "unified";
-import { isRef } from "@jxsuite/schema/guards";
+import { isRef, tagNameCandidates } from "@jxsuite/schema/guards";
 import remarkStringify from "remark-stringify";
 import remarkDirective from "remark-directive";
 import remarkGfm from "remark-gfm";
@@ -494,7 +494,7 @@ function convertJxNode(
     return null;
   }
 
-  const tag = el.tagName ?? "div";
+  const tag = serializableTag(el.tagName) || "div";
 
   // Not markdown-native or carries Jx-specific props → directive
   if (!allowlist.has(tag) || hasJxProps(el)) {
@@ -690,6 +690,31 @@ const JX_DOLLAR_KEYS = new Set([
   "$elements",
 ]);
 
+/**
+ * The tag, for a serializer that must write ONE name.
+ *
+ * A markdown directive is named by a literal, so a tag chosen at creation cannot round-trip through
+ * this format: picking a candidate would silently rewrite the author's document into one branch of
+ * it, which is the failure the tag-name pattern was added to stop. Content documents do not carry
+ * chosen tags today — the construct is an element-document (component) feature — so this refuses
+ * rather than guesses, and says which candidates it saw.
+ *
+ * @param {unknown} tagName
+ * @returns {string} The literal tag, or "" when none is declared
+ */
+function serializableTag(tagName: unknown): string {
+  if (typeof tagName === "string") {
+    return tagName;
+  }
+  if (tagName == null) {
+    return "";
+  }
+  throw new Error(
+    `Markdown cannot express a tag chosen at creation (candidates: ` +
+      `${tagNameCandidates(tagName).join(", ")}). Keep this element in a JSON component.`,
+  );
+}
+
 /**
  * `$prototype` element types that serialize as a directive named after the prototype (no tagName),
  * e.g. `:::Array`. Mirrors the set in transpile.ts.
@@ -898,7 +923,7 @@ function nodeToMdast(
     return expandArray(node, ctx, scope);
   }
 
-  const tag = node.tagName ?? "div";
+  const tag = serializableTag(node.tagName) || "div";
   const text = resolveText(node.textContent, ctx, scope);
 
   // InnerHTML — convert HTML content to mdast

package/src/transpile.ts

@@ -725,18 +725,35 @@ export function transpileJxMarkdown(source: string) {
 // ─── Heading anchors ─────────────────────────────────────────────────────────
 
 /**
- * Slugify a heading's text into an anchor id: lowercase, punctuation stripped, spaces collapsed to
- * single hyphens. The one algorithm behind rendered heading `id`s, `$toc` entries, and search deep
- * links (specs/parser.md).
+ * Slugify a heading's text into an anchor id: normalized, lowercased, punctuation stripped, spaces
+ * collapsed to single hyphens. The one algorithm behind rendered heading `id`s, `$toc` entries, and
+ * search deep links (specs/parser.md).
+ *
+ * **NFC first, and that is the whole point of the change** (UAX #15). "Café" typed on macOS is `e`
+ * + U+0301; the same word typed on Windows, or pasted from a web page, is U+00E9. They look
+ * identical, they compare unequal, and they produced two different anchors — so a link written
+ * against one heading silently stopped working when someone re-typed the heading. Normalizing puts
+ * both spellings in one form before anything else looks at them.
+ *
+ * **`toLowerCase`, never `toLocaleLowerCase`.** Locale-sensitive casing would make the same heading
+ * produce different anchors in different projects — Turkish maps `I` to `ı`, not `i` — and an
+ * anchor is a URL, which belongs to the document rather than to the reader's locale.
+ *
+ * **`_` stays in the character class deliberately.** The old class was `\w`, which is
+ * `[A-Za-z0-9_]`; `\p{L}\p{N}` is the Unicode-aware replacement and does **not** include `_`.
+ * Keeping it means this function is **byte-identical on every pure-ASCII heading**, so no existing
+ * anchor on an English site moves — `tests/transpile.test.ts` asserts exactly that against a
+ * corpus. What changes is only headings that were being mangled anyway.
  *
  * @param {string} text
  * @returns {string}
  */
 export function slugifyHeading(text: string) {
   return text
+    .normalize("NFC")
     .toLowerCase()
-    .replaceAll(/[^\w\s-]/g, "")
-    .replaceAll(/\s+/g, "-")
+    .replaceAll(/[^\p{L}\p{N}_\s-]/gu, "")
+    .replaceAll(/\s+/gu, "-")
     .replaceAll(/-+/g, "-")
     .replaceAll(/^-|-$/g, "");
 }
@@ -780,7 +797,9 @@ export function assignHeadingIds(children?: (JxElement | string)[]): TocEntry[]
       if (typeof node !== "object" || node === null) {
         continue;
       }
-      const tag = node.tagName;
+      // Heading extraction reads a literal tag; a chosen one is never a heading (every candidate
+      // Would have to be, and the construct exists to vary a WRAPPER), so it is simply not one.
+      const tag = typeof node.tagName === "string" ? node.tagName : "";
       if (tag && HEADING_TAGS.has(tag)) {
         const text = jxNodeText(node).trim();
         let id = typeof node.id === "string" && node.id.length > 0 ? node.id : "";