@jxsuite/parser 1.0.0 → 1.1.0

package/README.md

@@ -1,115 +1,156 @@
 # `@jxsuite/parser`
 
-> Markdown parser and external class integration for Jx.
+> Content & Markdown extension for Jx — file-based content collections with Markdown and CSV formats.
 
 ## Overview
 
-`@jxsuite/parser` provides the content layer for Jx applications. It exports `MarkdownFile` and `MarkdownCollection` — external classes that satisfy the Jx `$prototype` + `$src` contract — and a `transpile` utility for converting Jx-flavored Markdown directly into Jx component objects.
+`@jxsuite/parser` is the first-party content extension. Its `jx-extension.json` manifest exposes six classes plus project/document schema fragments:
 
-Built on the [`unified`](https://unifiedjs.com/) / remark / rehype pipeline.
+| Class                | Kind            | Purpose                                                                                            |
+| -------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
+| `Markdown`           | Format (`.md`)  | Parse/serialize Jx Markdown documents, load markdown content entries, resolve a file at runtime    |
+| `Csv`                | Format (`.csv`) | Parse local CSV files or remote CSV URLs into typed content entries                                |
+| `Content`            | Project section | Loads the project.json `content` section into `_project.content` and expands `$paths` route params |
+| `ContentCollection`  | Runtime class   | Query a content type with filter, sort, and limit                                                  |
+| `ContentEntry`       | Runtime class   | Fetch a single entry from a content type by ID (or another field)                                  |
+| `MarkdownCollection` | Runtime class   | Glob markdown files into a sorted, filterable array                                                |
 
-## Installation
+Built on the [`unified`](https://unifiedjs.com/) / remark ecosystem.
+
+## Installation & registration
 
 ```bash
 bun add @jxsuite/parser
 ```
 
-## `MarkdownFile`
-
-Parses a single Markdown file into structured data.
+Registration is manifest-based — add the package to `project.json`:
 
 ```json
 {
-  "state": {
-    "post": {
-      "$prototype": "MarkdownFile",
-      "$src": "@jxsuite/parser/MarkdownFile.class.json",
-      "src": "./content/posts/hello-world.md"
-    }
-  }
+  "extensions": ["@jxsuite/parser"]
 }
 ```
 
-**Resolved value:**
+That one entry registers the `.md`/`.csv` formats, the `content` project section, and the classes: `$prototype: "ContentEntry"` (etc.) resolves by name through the project's extension registry — no `$src` or imports wiring. There are no implicit defaults: a project without the extension supports only `.json` documents.
 
-| Property       | Type     | Description                         |
-| -------------- | -------- | ----------------------------------- |
-| `slug`         | `string` | Filename without extension          |
-| `path`         | `string` | Full file path                      |
-| `frontmatter`  | `object` | Parsed YAML frontmatter             |
-| `$body`        | `string` | Rendered HTML body                  |
-| `$excerpt`     | `string` | First paragraph as HTML             |
-| `$toc`         | `array`  | Table of contents (id, text, depth) |
-| `$readingTime` | `number` | Estimated reading time in minutes   |
-| `$wordCount`   | `number` | Word count                          |
+## Content collections
 
-## `MarkdownCollection`
+Declare content types in the `content` section (validated by this package's project schema fragment):
+
+```json
+{
+  "content": {
+    "docs": {
+      "source": "./content/docs",
+      "format": "Markdown",
+      "schema": {
+        "type": "object",
+        "properties": { "title": { "type": "string" }, "date": { "type": "string" } }
+      },
+      "$elements": [{ "$ref": "./components/doc-note.json" }]
+    }
+  }
+}
+```
 
-Globs Markdown files into a sorted, filterable collection.
+Query them from any page or component:
 
 ```json
 {
   "state": {
     "posts": {
-      "$prototype": "MarkdownCollection",
-      "$src": "@jxsuite/parser/MarkdownCollection.class.json",
-      "src": "./content/posts/*.md",
-      "sortBy": "date",
-      "sortOrder": "desc",
+      "$prototype": "ContentCollection",
+      "contentType": "docs",
+      "filter": [{ "field": "draft", "op": "!=", "value": true }],
       "limit": 10
+    },
+    "page": {
+      "$prototype": "ContentEntry",
+      "contentType": "docs",
+      "id": { "$ref": "#/$params/slug" }
     }
   }
 }
 ```
 
-Returns an array of `MarkdownFile` resolved objects.
+`ContentEntry` matches on the entry id (slug) by default; set `field` to match a frontmatter field (e.g. `"sku"`) instead.
 
-| Option      | Type     | Default  | Description                         |
-| ----------- | -------- | -------- | ----------------------------------- |
-| `src`       | `string` | —        | Glob pattern for Markdown files     |
-| `sortBy`    | `string` | `"date"` | Frontmatter field to sort by        |
-| `sortOrder` | `string` | `"desc"` | `"asc"` or `"desc"`                 |
-| `limit`     | `number` | —        | Maximum number of results           |
-| `filter`    | `string` | —        | Frontmatter field filter expression |
+## `Markdown`
 
-## `MarkdownDirective` (remark plugin)
+One class carries every format capability:
 
-Maps `::directive{attrs}` syntax to custom element tags in HTML output. Parameters are encoded as a `data-jx-props` JSON attribute so Jx components can receive them via reactive state.
+- **static `parse`** — Jx Markdown source → Jx document (browser-safe; Studio opens `.md` files with it)
+- **static `serialize`** — Jx document → markdown, `roundtrip` (lossless, default) or `export` (lossy clean markdown)
+- **static `discover` / `load`** — compile-time content access: frontmatter → `data`, source preserved as `body`, parsed `$children`, and `_meta` (excerpt, toc, reading time, word count)
+- **instance `resolve`** — runtime on-demand access for a `$prototype: "Markdown"` state entry
 
-```markdown
-:::my-card{title="Hello" image="/img/hero.png"}
-Card body content here.
-:::
+```json
+{
+  "state": {
+    "post": { "$prototype": "Markdown", "src": "./content/posts/hello-world.md" }
+  }
+}
 ```
 
-Produces:
+**Resolved value** (`MarkdownFileResult`):
 
-```html
-<my-card data-jx-props='{"title":"Hello","image":"/img/hero.png"}'>
-  <p>Card body content here.</p>
-</my-card>
-```
+| Property       | Type     | Description                                 |
+| -------------- | -------- | ------------------------------------------- |
+| `slug`         | `string` | Entry id (path-based under the source root) |
+| `path`         | `string` | Full file path                              |
+| `frontmatter`  | `object` | Parsed YAML frontmatter                     |
+| `$children`    | `array`  | Body as Jx element nodes                    |
+| `$excerpt`     | `string` | First paragraph                             |
+| `$toc`         | `array`  | Table of contents (id, text, depth)         |
+| `$readingTime` | `number` | Estimated reading time in minutes           |
+| `$wordCount`   | `number` | Word count                                  |
+
+### Directives
+
+`:::name{attrs}` container syntax converts directly to Jx element nodes — `:::my-card{title="Hello"}` becomes a `my-card` element with its attributes routed to the right Jx locations (props, `$`-annotations, styles). Capitalized directives (e.g. `:::Array`) become tagName-less `$prototype` nodes. A content type's `$elements` list declares which components its entries may use.
+
+## `Csv`
 
-## `transpileJxMarkdown`
+CSV content format (`documentKinds: ["content"]`; Studio opens `.csv` in grid/source modes).
 
-Converts a Jx-flavored Markdown source string directly into a Jx component object (no file I/O).
+| Option    | Type     | Description                                                       |
+| --------- | -------- | ----------------------------------------------------------------- |
+| `src`     | `string` | Path or http(s) URL to a CSV file (remote sources supported)      |
+| `schema`  | `object` | Per-column type schema for coercion (number, boolean, array)      |
+| `idField` | `string` | Column used as entry id (default chain: id, sku, slug, row index) |
 
-```js
-import { transpileJxMarkdown } from "@jxsuite/parser/transpile";
+## `MarkdownCollection`
+
+Globs markdown files into a sorted array of `MarkdownFileResult`s (runtime alternative to the content section):
 
-const doc = transpileJxMarkdown(markdownString);
-// { tagName: "article", children: [...] }
+```json
+{
+  "state": {
+    "posts": {
+      "$prototype": "MarkdownCollection",
+      "src": "./content/posts/*.md",
+      "sortBy": "frontmatter.date",
+      "sortOrder": "desc",
+      "limit": 10
+    }
+  }
+}
 ```
 
-## Parsing pipeline
+Options: `src` (glob), `sortBy` (dot-path, default `"frontmatter.date"`), `sortOrder` (`"asc"`/`"desc"`), `limit`, `filter` (predicate), `basePath`, `directives`.
+
+## Module exports
 
-1. `remark-parse` — Markdown → MDAST
-2. `remark-frontmatter` + `remark-parse-frontmatter` — YAML extraction
-3. `remark-gfm` — GitHub Flavored Markdown
-4. `remark-directive` — directive syntax
-5. `MarkdownDirective` — directive nodes → custom element tags
-6. `remark-rehype` — MDAST → HAST
-7. `rehype-stringify` — HAST → HTML
+| Export                           | Contents                                                               |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `@jxsuite/parser`                | `processMarkdown`, `Markdown`, `MarkdownCollection`                    |
+| `@jxsuite/parser/markdown`       | The `Markdown` format class (browser-safe parse/serialize)             |
+| `@jxsuite/parser/csv`            | `Csv`, `parseCSV`, `coerceCSVRows`                                     |
+| `@jxsuite/parser/content`        | `ContentCollection`, `ContentEntry`, pure query functions              |
+| `@jxsuite/parser/content-loader` | `Content` project-section loader                                       |
+| `@jxsuite/parser/transpile`      | `transpileJxMarkdown` (markdown source → Jx document), `isJxMarkdown`  |
+| `@jxsuite/parser/serialize`      | `serializeJxMarkdown`, `jxToMdast`, `mdastToJx`, markdown element sets |
+| `@jxsuite/parser/*.class.json`   | The class descriptors named by the manifest                            |
 
 ## License
 

package/dist/content-loader.js

@@ -155,11 +155,13 @@ async function loadContentType(name, contentTypeDef, projectRoot, registry) {
   const files = entry.capabilities.discover ? await entry.call("discover", source, {
     baseDir: projectRoot
   }) : [resolvedSource];
+  const sourceRoot = extname(source) ? undefined : resolvedSource;
   const entries = [];
   for (const filePath of files) {
     entries.push(...await entry.call("load", filePath, {
       directiveOptions,
-      schema
+      schema,
+      ...sourceRoot !== undefined && { sourceRoot }
     }));
   }
   if (schema) {
@@ -225,6 +227,7 @@ function resolveContentTypeRefs(contentTypes, section) {
       }
       const refEntries = contentTypes.get(target);
       if (!refEntries) {
+        console.warn(`Content relationships: "${name}" field "${field}" references unknown content type "${target}"`);
         continue;
       }
       for (const entry of entries) {
@@ -233,9 +236,20 @@ function resolveContentTypeRefs(contentTypes, section) {
           const resolved = refEntries.find((e) => e.id === value);
           if (resolved) {
             entry.data[field] = resolved;
+          } else {
+            console.warn(`Content relationships: "${name}/${entry.id}" field "${field}" references missing "${target}" entry "${value}"`);
           }
         } else if (toMany && Array.isArray(value)) {
-          entry.data[field] = value.map((id) => typeof id === "string" ? refEntries.find((e) => e.id === id) ?? id : id);
+          entry.data[field] = value.map((id) => {
+            if (typeof id !== "string") {
+              return id;
+            }
+            const resolved = refEntries.find((e) => e.id === id);
+            if (!resolved) {
+              console.warn(`Content relationships: "${name}/${entry.id}" field "${field}" references missing "${target}" entry "${id}"`);
+            }
+            return resolved ?? id;
+          });
         }
       }
     }

package/dist/markdown.js

@@ -46180,7 +46180,7 @@ __export(exports_md, {
   Markdown: () => Markdown
 });
 import { readFileSync } from "node:fs";
-import { basename, extname, resolve as resolvePath2 } from "node:path";
+import { basename, extname, relative, resolve as resolvePath2 } from "node:path";
 function visit3(tree, typeOrVisitor, maybeVisitor) {
   const type = typeof typeOrVisitor === "string" ? typeOrVisitor : null;
   const visitor = type ? maybeVisitor : typeOrVisitor;
@@ -46239,6 +46239,19 @@ function extractExcerpt(tree) {
   }
   return mdastToString(firstParagraph);
 }
+function deriveSlug(filePath, sourceRoot) {
+  if (sourceRoot) {
+    const rel = relative(sourceRoot, filePath).split("\\").join("/");
+    if (rel && !rel.startsWith("..") && rel.includes("/")) {
+      let slug = rel.slice(0, rel.length - extname(rel).length);
+      if (slug.endsWith("/index")) {
+        slug = slug.slice(0, -"/index".length);
+      }
+      return slug;
+    }
+  }
+  return basename(filePath, extname(filePath));
+}
 function processMarkdown(source, filePath, config = {}) {
   let processor = unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(import_remark_parse_frontmatter2.default).use(remarkGfm);
   if (config.directives || config.directiveOptions) {
@@ -46253,7 +46266,7 @@ function processMarkdown(source, filePath, config = {}) {
   const plainText = mdastToString(mdTree);
   const toc = extractToc(tree);
   const excerpt = extractExcerpt(tree);
-  const slug = basename(filePath, extname(filePath));
+  const slug = deriveSlug(filePath, config.sourceRoot);
   const bodyNodes = tree.children.filter((n7) => n7.type !== "yaml" && n7.type !== "toml");
   const $children = bodyNodes.map((n7) => mdastNodeToJx(n7)).filter(Boolean);
   return {
@@ -46367,7 +46380,8 @@ class Markdown {
       ...options.directives !== undefined && { directives: options.directives },
       ...options.directiveOptions !== undefined && {
         directiveOptions: options.directiveOptions
-      }
+      },
+      ...options.sourceRoot !== undefined && { sourceRoot: options.sourceRoot }
     });
     const _meta = {};
     if (result.$excerpt != null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -48,8 +48,8 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.2.0",
-    "@jxsuite/schema": "^1.0.0",
+    "@jxsuite/markup": "^0.3.0",
+    "@jxsuite/schema": "^1.1.0",
     "glob": "^13.0.6",
     "mdast-util-to-string": "^4.0.0",
     "remark-directive": "^4.0.0",
@@ -64,7 +64,7 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",
-    "@jxsuite/runtime": "^1.0.0",
+    "@jxsuite/runtime": "^1.1.0",
     "@types/mdast": "^4.0.4",
     "ajv": "^8.20.0"
   },

package/src/Csv.class.json

@@ -17,7 +17,7 @@
 
   "$studio": {
     "icon": "table",
-    "modes": ["source"]
+    "modes": ["grid", "source"]
   },
 
   "$defs": {

package/src/content-loader.ts

@@ -269,12 +269,15 @@ async function loadContentType(
       })) as string[])
     : [resolvedSource];
 
+  // Directory sources pass their resolved root so formats can derive path-based ids for nested files
+  const sourceRoot = extname(source) ? undefined : resolvedSource;
   const entries: ContentLoaderEntry[] = [];
   for (const filePath of files) {
     entries.push(
       ...((await entry.call("load", filePath, {
         directiveOptions,
         schema,
+        ...(sourceRoot !== undefined && { sourceRoot }),
       })) as ContentLoaderEntry[]),
     );
   }
@@ -374,7 +377,7 @@ function refTargetName(ref: string | undefined): string | undefined {
  * field `$ref` is to-one: a blog post's `author: "jane-doe"` with a schema `$ref` of
  * `#/content/authors` gets replaced by the full author entry. An array field whose `items` carry
  * the `$ref` is to-many: each id in the stored array is replaced by its entry. Unresolvable ids are
- * left untouched.
+ * left untouched, with a warning naming the entry and the missing target.
  *
  * @param {Map<string, ContentLoaderEntry[]>} contentTypes - All loaded content types
  * @param {ContentSection} section - The `content` section value the types were loaded from
@@ -403,6 +406,9 @@ export function resolveContentTypeRefs(
       }
       const refEntries = contentTypes.get(target);
       if (!refEntries) {
+        console.warn(
+          `Content relationships: "${name}" field "${field}" references unknown content type "${target}"`,
+        );
         continue;
       }
 
@@ -412,11 +418,24 @@ export function resolveContentTypeRefs(
           const resolved = refEntries.find((e) => e.id === value);
           if (resolved) {
             entry.data[field] = resolved;
+          } else {
+            console.warn(
+              `Content relationships: "${name}/${entry.id}" field "${field}" references missing "${target}" entry "${value}"`,
+            );
           }
         } else if (toMany && Array.isArray(value)) {
-          entry.data[field] = value.map((id) =>
-            typeof id === "string" ? (refEntries.find((e) => e.id === id) ?? id) : id,
-          );
+          entry.data[field] = value.map((id) => {
+            if (typeof id !== "string") {
+              return id;
+            }
+            const resolved = refEntries.find((e) => e.id === id);
+            if (!resolved) {
+              console.warn(
+                `Content relationships: "${name}/${entry.id}" field "${field}" references missing "${target}" entry "${id}"`,
+              );
+            }
+            return resolved ?? id;
+          });
         }
       }
     }

package/src/markdown.ts

@@ -26,6 +26,12 @@ export interface MarkdownLoadOptions {
   directiveOptions?: unknown;
   /** Enable remark-directive parsing. Implied by directiveOptions. */
   directives?: boolean;
+  /**
+   * Resolved content-source root directory. When set, entries in subdirectories get path-based ids
+   * (`studio/canvas` for `studio/canvas.md`, `/index` stripped); files directly at the root keep
+   * basename ids.
+   */
+  sourceRoot?: string;
 }
 
 /**
@@ -83,6 +89,7 @@ export class Markdown {
       ...(options.directiveOptions !== undefined && {
         directiveOptions: options.directiveOptions,
       }),
+      ...(options.sourceRoot !== undefined && { sourceRoot: options.sourceRoot }),
     });
     const _meta: ContentLoaderEntry["_meta"] = {};
     if (result.$excerpt != null) {

package/src/md.ts

@@ -18,7 +18,7 @@ import remarkParseFrontmatter from "remark-parse-frontmatter";
 import remarkGfm from "remark-gfm";
 import remarkDirective from "remark-directive";
 import { readFileSync } from "node:fs";
-import { basename, extname, resolve as resolvePath } from "node:path";
+import { basename, extname, relative, resolve as resolvePath } from "node:path";
 import { globSync } from "glob";
 import { mdastNodeToJx } from "./transpile.ts";
 import type { MarkdownFileResult, MdastNode, TocEntry, UnifiedProcessor } from "./types.ts";
@@ -133,6 +133,30 @@ function extractExcerpt(tree: MdastNode) {
   return mdastToString(firstParagraph);
 }
 
+/**
+ * Derive an entry slug from a file path. Without a source root (or for files directly at the root),
+ * the slug is the basename — the historical behavior every flat collection relies on. Files in
+ * subdirectories of the root get path-based slugs with POSIX separators and a trailing `/index`
+ * stripped, so `studio/canvas.md` and `studio/canvas/index.md` both yield `studio/canvas`.
+ *
+ * @param {string} filePath - Absolute path to the markdown file
+ * @param {string} [sourceRoot] - Resolved content-source root directory
+ * @returns {string} The entry slug
+ */
+function deriveSlug(filePath: string, sourceRoot?: string): string {
+  if (sourceRoot) {
+    const rel = relative(sourceRoot, filePath).split("\\").join("/");
+    if (rel && !rel.startsWith("..") && rel.includes("/")) {
+      let slug = rel.slice(0, rel.length - extname(rel).length);
+      if (slug.endsWith("/index")) {
+        slug = slug.slice(0, -"/index".length);
+      }
+      return slug;
+    }
+  }
+  return basename(filePath, extname(filePath));
+}
+
 /**
  * Process a single markdown source string into a MarkdownFileResult.
  *
@@ -143,6 +167,7 @@ function extractExcerpt(tree: MdastNode) {
  * @param {object} config - Processing options
  * @param {boolean} [config.directives] - Enable directive support
  * @param {unknown} [config.directiveOptions] - Directive plugin options
+ * @param {string} [config.sourceRoot] - Content-source root; files below it get path-based slugs
  * @returns {MarkdownFileResult}
  */
 export function processMarkdown(
@@ -151,6 +176,7 @@ export function processMarkdown(
   config: {
     directives?: boolean;
     directiveOptions?: unknown;
+    sourceRoot?: string;
   } = {},
 ) {
   let processor = (unified as unknown as () => UnifiedProcessor)()
@@ -173,7 +199,7 @@ export function processMarkdown(
   const plainText = mdastToString(mdTree);
   const toc = extractToc(tree);
   const excerpt = extractExcerpt(tree);
-  const slug = basename(filePath, extname(filePath));
+  const slug = deriveSlug(filePath, config.sourceRoot);
 
   const bodyNodes = tree.children!.filter(
     (n: MdastNode) => n.type !== "yaml" && n.type !== "toml",