@jxsuite/parser 1.0.0 → 1.2.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;
+          });
         }
       }
     }