@jxsuite/parser 1.6.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "1.6.0",
+  "version": "1.8.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.8",
-    "@jxsuite/schema": "^2.0.0",
+    "@jxsuite/markup": "^0.4.10",
+    "@jxsuite/schema": "^2.2.0",
     "@shikijs/langs": "^4.4.3",
     "@shikijs/themes": "^4.4.3",
     "glob": "^13.0.6",
@@ -63,11 +63,11 @@
     "shiki": "^4.4.3",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.8",
-    "@jxsuite/runtime": "^3.0.0",
+    "@happy-dom/global-registrator": "^20.14.5",
+    "@jxsuite/runtime": "^4.0.0",
     "@types/mdast": "^4.0.4",
     "ajv": "^8.20.0"
   },

package/src/Content.class.json

@@ -16,7 +16,7 @@
 
   "$studio": {
     "settings": {
-      "icon": "sp-icon-view-grid",
+      "icon": "grid-four",
       "label": "Content Types",
       "order": 50,
       "layout": "map",

package/src/Csv.class.json

@@ -115,6 +115,37 @@
         "returnType": { "$ref": "#/$defs/returnTypes/ContentLoaderEntries" },
         "description": "Parse CSV text into typed content entries (pure, browser-safe)"
       },
+      "rewrite": {
+        "role": "rewrite",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "static",
+        "identifier": "rewrite",
+        "timing": ["compiler", "server", "client"],
+        "parameters": [
+          {
+            "identifier": "source",
+            "type": { "type": "string" },
+            "description": "Raw CSV text"
+          },
+          {
+            "identifier": "edits",
+            "type": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "from": { "type": "string" },
+                  "to": { "type": "string" }
+                }
+              }
+            },
+            "description": "Authored cell values to replace, matched whole against a data cell"
+          }
+        ],
+        "returnType": { "type": "string" },
+        "description": "Replace authored cell values in CSV source text, preserving every other byte"
+      },
       "discover": {
         "role": "discover",
         "$prototype": "Function",

package/src/csv.ts

@@ -2,10 +2,15 @@
  * Csv — CSV content format for Jx
  *
  * RFC 4180-style CSV parsing with schema-driven type coercion, packaged as a Jx
- * format-extension class. `parse` is pure and browser-safe; `discover`, `load`, and
+ * format-extension class. `parse` and `rewrite` are pure and browser-safe; `discover`, `load`, and
  * instance `resolve` touch the filesystem (or fetch remote URLs) and dynamically
  * import node modules so the module itself stays importable in the browser.
  *
+ * There is no `serialize`, and there will not be one: a collection is a data source entries are
+ * loaded FROM, and re-emitting one would mean choosing a quoting style, a line ending and a column
+ * order the author already chose. `rewrite` is the narrower promise that covers the case that
+ * actually needed it — a rename repairing a reference a row names (specs/extensions.md §8).
+ *
  * @module @jxsuite/parser/csv
  * @license MIT
  */
@@ -90,6 +95,164 @@ export function parseCSV(csv: string): Record<string, string>[] {
   return rows;
 }
 
+// ─── Cell-level rewriting ────────────────────────────────────────────────────
+
+/** One authored value to replace, wherever a data cell holds exactly it. */
+export interface CsvEdit {
+  /** The cell value as `parse` produced it — unquoted and trimmed. */
+  from: string;
+  /** What to write in its place. */
+  to: string;
+}
+
+/** One field of a CSV source: where its bytes are, and what {@link parseCSV} made of it. */
+interface CsvField {
+  /** Row index in the source. Row 0 is the header. */
+  row: number;
+  /** Offsets of the field's raw text within the source, delimiting commas excluded. */
+  start: number;
+  end: number;
+  /** The value {@link parseCSV} produces for it — unquoted and trimmed. */
+  value: string;
+}
+
+/**
+ * Row spans, splitting on newlines that are not inside quotes.
+ *
+ * A deliberate mirror of {@link parseCSV}'s first pass, offsets instead of text: the two must agree
+ * on where a row ends or a rewrite would splice into the wrong cell. The accumulated text there is
+ * exactly `source.slice(start, end)` here, because the only characters that pass are contiguous.
+ */
+function scanRows(csv: string): { start: number; end: number }[] {
+  const rows: { start: number; end: number }[] = [];
+  let start = 0;
+  let inQuotes = false;
+  for (let i = 0; i < csv.length; i++) {
+    const ch = csv[i];
+    if (ch === '"') {
+      if (inQuotes && csv[i + 1] === '"') {
+        i += 1;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if ((ch === "\n" || (ch === "\r" && csv[i + 1] === "\n")) && !inQuotes) {
+      rows.push({ end: i, start });
+      if (ch === "\r") {
+        i += 1;
+      }
+      start = i + 1;
+    }
+  }
+  // The same test {@link parseCSV} applies to its final accumulated row, which is exactly this
+  // Slice: a trailing newline leaves whitespace behind, and that is not a row.
+  if (csv.slice(start).trim()) {
+    rows.push({ end: csv.length, start });
+  }
+  return rows;
+}
+
+/** Field spans within one row, mirroring {@link parseCSV}'s second pass. */
+function scanRowFields(csv: string, row: number, span: { start: number; end: number }): CsvField[] {
+  const line = csv.slice(span.start, span.end);
+  const fields: CsvField[] = [];
+  let fieldStart = 0;
+  let value = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        value += '"';
+        i += 1;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if (ch === "," && !inQuotes) {
+      fields.push({
+        end: span.start + i,
+        row,
+        start: span.start + fieldStart,
+        value: value.trim(),
+      });
+      value = "";
+      fieldStart = i + 1;
+    } else {
+      value += ch;
+    }
+  }
+  fields.push({ end: span.end, row, start: span.start + fieldStart, value: value.trim() });
+  return fields;
+}
+
+/** Every field of a CSV source in document order, with the offsets a splice needs. */
+function scanFields(csv: string): CsvField[] {
+  return scanRows(csv).flatMap((span, row) => scanRowFields(csv, row, span));
+}
+
+/**
+ * Write `value` into the space a field's raw text occupied, keeping that field's own conventions.
+ *
+ * Padding survives because it is the author's, and quoting survives for the same reason — a column
+ * written `"a","b"` stays quoted even when the new value would not need it. A value that WOULD be
+ * misread unquoted (a comma, a quote, a newline, or padding of its own) is quoted regardless, which
+ * is the only case where the output style is not simply the input's.
+ */
+function encodeField(raw: string, value: string): string {
+  const lead = raw.slice(0, raw.length - raw.trimStart().length);
+  const trail = raw.slice(raw.trimEnd().length);
+  const core = raw.trim();
+  const wasQuoted = core.length >= 2 && core.startsWith('"') && core.endsWith('"');
+  const mustQuote = /["\r\n,]/.test(value) || value.trim() !== value;
+  return lead + (wasQuoted || mustQuote ? `"${value.replaceAll('"', '""')}"` : value) + trail;
+}
+
+/**
+ * Replace authored cell values in CSV source text, preserving every other byte.
+ *
+ * The `rewrite` capability (specs/extensions.md §8), and deliberately narrower than `serialize`. A
+ * CSV collection is a data source entries are loaded FROM, not a document Jx round-trips, so it has
+ * no serializer and never will — quoting style, line endings and column order are the author's and
+ * the loader has no opinion about any of them. But the rename refactor does not need a document
+ * back; it needs one cell's text changed. Without that, renaming a file a CSV row names updated
+ * every other reference and reported this one as a remainder the author had to repair by hand
+ * (issue 246).
+ *
+ * Matching is on the WHOLE cell value as {@link parseCSV} produced it, never on a substring:
+ * `hero.jpg` must not rewrite the middle of `my-hero.jpg`. The HEADER row is never touched — it
+ * names columns rather than files, `parse` does not expose it as a value, and an edit derived from
+ * `parse` output therefore cannot legitimately name it.
+ *
+ * @param source — the CSV file's original text
+ * @param edits — authored values to replace
+ * @returns The source with exactly those cells rewritten
+ */
+export function rewriteCSV(source: string, edits: readonly CsvEdit[]): string {
+  const replacements = new Map<string, string>();
+  for (const edit of edits) {
+    if (edit.from !== edit.to) {
+      replacements.set(edit.from, edit.to);
+    }
+  }
+  if (replacements.size === 0) {
+    return source;
+  }
+  let out = "";
+  let cursor = 0;
+  for (const field of scanFields(source)) {
+    if (field.row === 0) {
+      continue;
+    }
+    const to = replacements.get(field.value);
+    if (to === undefined) {
+      continue;
+    }
+    out += source.slice(cursor, field.start);
+    out += encodeField(source.slice(field.start, field.end), to);
+    cursor = field.end;
+  }
+  return out + source.slice(cursor);
+}
+
 // ─── Type coercion ───────────────────────────────────────────────────────────
 
 export interface CsvOptions {
@@ -171,6 +334,18 @@ export class Csv {
     return coerceCSVRows(parseCSV(source), options.schema, options.idField);
   }
 
+  /**
+   * Replace authored cell values, preserving every other byte (pure, browser-safe).
+   *
+   * The `rewrite` capability. Csv declares it and deliberately declares no `serialize`: rows are
+   * loaded, not round-tripped, so there is no document to write back — but one cell's text can be
+   * changed without inventing an opinion about quoting, line endings or column order. See
+   * {@link rewriteCSV}.
+   */
+  static rewrite(source: string, edits: readonly CsvEdit[] = []): string {
+    return rewriteCSV(source, edits);
+  }
+
   /** List .csv entry files for a content-type source (file path or directory). */
   static async discover(source: string, options: { baseDir?: string } = {}): Promise<string[]> {
     const { existsSync, readdirSync } = await import("node:fs");

package/src/transpile.ts

@@ -136,7 +136,14 @@ export function collapseDotPaths(obj: Record<string, unknown>) {
   return result;
 }
 
-/** CSS pseudo-class / pseudo-element names (keys that become `:` prefixed in style objects). */
+/**
+ * CSS pseudo-CLASS names — keys that become `:` prefixed in style objects.
+ *
+ * `before` and `after` are pseudo-_elements_ and belong in the set below on the modern spelling,
+ * but they have been written with one colon since this file existed and CSS still accepts that
+ * form. Moving them would rewrite every `.md` component in the repo for no behaviour change, so
+ * they stay here; {@link CSS_PSEUDO_ELEMENTS} is for names that have never had a one-colon form.
+ */
 const CSS_PSEUDO_NAMES = new Set([
   "hover",
   "focus",
@@ -156,8 +163,24 @@ const CSS_PSEUDO_NAMES = new Set([
   "selection",
   "before",
   "after",
+  // The overlay states. Without these an author could declare a popover in a `.md` component and
+  // Have no way to style it open — `style.popover-open.opacity` fell through unmapped, and
+  // `collectStyles` then read the bare key as a DESCENDANT TYPE SELECTOR, emitting
+  // `#panel popover-open { … }`: a rule that matches nothing, with nothing to say it does not.
+  "popover-open",
+  "open",
+  "modal",
 ]);
 
+/**
+ * CSS pseudo-ELEMENT names — keys that become `::` prefixed.
+ *
+ * A separate set because the prefix is different, not because the concept is. `backdrop` is the
+ * only member today and it is the one a popover needs: there is no one-colon form of it, so the
+ * single-colon set above could not have carried it.
+ */
+const CSS_PSEUDO_ELEMENTS = new Set(["backdrop"]);
+
 /**
  * Apply CSS pseudo-class and media query key mapping to a style object's top-level keys.
  *
@@ -171,7 +194,9 @@ const CSS_PSEUDO_NAMES = new Set([
 export function applyStyleKeyMapping(styleObj: Record<string, unknown>) {
   const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(styleObj)) {
-    if (CSS_PSEUDO_NAMES.has(key)) {
+    if (CSS_PSEUDO_ELEMENTS.has(key)) {
+      result[`::${key}`] = value;
+    } else if (CSS_PSEUDO_NAMES.has(key)) {
       result[`:${key}`] = value;
     } else if (key.startsWith("--")) {
       result[`@${key}`] = value;
@@ -208,7 +233,11 @@ export function collapseStylePaths(styleObj: Record<string, unknown>) {
   const normalized: Record<string, unknown> = {};
 
   for (const [key, value] of Object.entries(styleObj)) {
-    if (key.startsWith(":") && CSS_PSEUDO_NAMES.has(key.slice(1))) {
+    /* `::` before `:`, or a pseudo-element would match the pseudo-class arm on its second colon
+       and be re-emitted with one colon. */
+    if (key.startsWith("::") && CSS_PSEUDO_ELEMENTS.has(key.slice(2))) {
+      normalized[key.slice(2)] = value;
+    } else if (key.startsWith(":") && CSS_PSEUDO_NAMES.has(key.slice(1))) {
       normalized[key.slice(1)] = value;
     } else if (key.startsWith("@--")) {
       normalized[key.slice(1)] = value;
@@ -730,10 +759,11 @@ export function transpileJxMarkdown(source: string) {
  * 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.
+ *
+ * - 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