@react-platform/mdx 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Elemental Design System
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @react-platform/mdx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build-time MDX 3 compilation for renderer-independent React documents. This package owns YAML frontmatter, named metadata exports, source maps, and an optional esbuild integration. It does not own a player, slide separators, speaker notes, UI components, or any design renderer.
+
+```ts
+import { compileMDX } from '@react-platform/mdx';
+const result = await compileMDX(source, { filePath: 'article.mdx' });
+// result.code: an ESM module exporting the React component and frontmatter
+// result.map: a JSON source map string
+// result.frontmatter: parsed, JSON-serializable YAML metadata
+```
+
+Leading YAML is parsed with gray-matter and yaml. Nested mappings, arrays, numbers and booleans are supported; malformed YAML and non-mapping metadata fail. `frontmatter` is a reserved named export and available in authored expressions. `frontmatter: false` preserves a leading Markdown rule and exports empty metadata. `parseMDX` returns metadata plus content padded with blank lines to preserve source line numbers.
+
+```mdx
+---
+title: Portable documents
+---
+
+# {frontmatter.title}
+
+A **shared** document.
+
+---
+
+This is a horizontal rule, not a new slide.
+```
+
+The output uses the automatic React JSX runtime and accepts an MDX `components` map. Native and design consumers map Markdown tags to their own primitives; imported custom components must use the selected host too. Explicit lowercase JSX bypasses the map. The compiler runs on Node at build time; bundle or precompile its output before loading it on React Native. It does not ship a runtime evaluator or a Metro transformer. Rendering authored MDX executes its expressions and imports, so use trusted source.
+
+## Bundling
+
+```ts
+import { build } from 'esbuild';
+import { mdx } from '@react-platform/mdx/esbuild';
+await build({ entryPoints: ['article.mdx'], bundle: true, plugins: [mdx()] });
+```
+
+The optional `/esbuild` entry loads `.md` and `.mdx`, passes through source maps, watches source files, and preserves relative import resolution. The root compiler does not import esbuild, React, DOM/native APIs or design libraries. Install esbuild only if using that entry. The host controls TSX, dependency resolution and target aliases; program output with the automatic JSX runtime is required by the bundler plugin.
+
+`MDXCompileOptions` extends MDX's `CompileOptions`: remark/rehype plugins, JSX import source, development output and other upstream options pass through. Metadata injection runs after the caller's remark plugins. A final rehype pass removes whitespace-only block children that otherwise become unintended text nodes on native/design hosts; code and inline spaces are preserved.
+
+## Ownership and validation
+
+`mdx-slides` retains top-level thematic-break splitting, shared deck imports, slide IDs/titles, notes, presentation themes/players and PDF output. Its compiler delegates document compilation to this package. React Designapp's `examples/mdx-figma` demonstrates a single MDX document using the existing `react-strict-dom-figma` host. Frame-per-slide Figma export remains a future mdx-slides feature.
+
+Run `pnpm check` from React Platform, or build/test this package with `pnpm --filter @react-platform/mdx build` and `pnpm --filter @react-platform/mdx test`. Tests exercise YAML validation, source positions/maps, component mapping, relative TSX imports and ordinary horizontal rules. These are compiler/bundler checks, not native-device validation.
+
+The sibling consumers use local `link:` dependencies while the package is unpublished. Build this package before invoking consumers; their provided scripts do so. A release should replace local links with matching published version ranges.

package/dist/esbuild.d.ts

@@ -0,0 +1,5 @@
+import type { Plugin } from 'esbuild';
+import { type MDXCompileOptions } from './index.js';
+/** Build-time only. Host aliases and TSX transformation remain the bundler's job. */
+export declare function mdx(options?: MDXCompileOptions): Plugin;
+//# sourceMappingURL=esbuild.d.ts.map

package/dist/esbuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild.d.ts","sourceRoot":"","sources":["../src/esbuild.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEhE,qFAAqF;AACrF,wBAAgB,GAAG,CAAC,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAgB3D"}

package/dist/esbuild.js

@@ -0,0 +1,22 @@
+import { readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { compileMDX } from './index.js';
+/** Build-time only. Host aliases and TSX transformation remain the bundler's job. */
+export function mdx(options = {}) {
+    if (options.jsx || options.outputFormat === 'function-body') {
+        throw new Error('The bundler requires program output with the automatic JSX runtime');
+    }
+    return {
+        name: 'react-platform-mdx',
+        setup(api) {
+            api.onLoad({ filter: /\.mdx?$/ }, async (args) => {
+                const result = await compileMDX(await readFile(args.path, 'utf8'), {
+                    ...options, filePath: args.path, format: args.path.endsWith('.md') ? 'md' : 'mdx',
+                });
+                const sourceMap = result.map ? `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(result.map).toString('base64')}` : '';
+                return { contents: result.code + sourceMap, loader: 'js', resolveDir: dirname(args.path), watchFiles: [args.path] };
+            });
+        },
+    };
+}
+//# sourceMappingURL=esbuild.js.map

package/dist/esbuild.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esbuild.js","sourceRoot":"","sources":["../src/esbuild.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,UAAU,EAA0B,MAAM,YAAY,CAAC;AAEhE,qFAAqF;AACrF,MAAM,UAAU,GAAG,CAAC,UAA6B,EAAE;IACjD,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,YAAY,KAAK,eAAe,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IACD,OAAO;QACL,IAAI,EAAE,oBAAoB;QAC1B,KAAK,CAAC,GAAG;YACP,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,KAAK,EAAC,IAAI,EAAC,EAAE;gBAC7C,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE;oBACjE,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK;iBAClF,CAAC,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,uDAAuD,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxI,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACtH,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { type CompileOptions } from '@mdx-js/mdx';
+export type Metadata = Record<string, unknown>;
+export interface MDXCompileOptions extends CompileOptions {
+    /** Parse leading YAML and inject a named frontmatter export. Default true. */
+    frontmatter?: boolean;
+    filePath?: string;
+}
+export interface ParsedMDX {
+    content: string;
+    frontmatter: Metadata;
+}
+export interface CompiledMDX {
+    code: string;
+    map?: string;
+    frontmatter: Metadata;
+}
+export declare function parseMDX(source: string, options?: Pick<MDXCompileOptions, 'frontmatter'>): ParsedMDX;
+/** Compile a document to React JSX-runtime code without selecting a renderer. */
+export declare function compileMDX(source: string, options?: MDXCompileOptions): Promise<CompiledMDX>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAQ5E,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC/C,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,8EAA8E;IAC9E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,SAAS;IAAG,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,QAAQ,CAAA;CAAE;AACrE,MAAM,WAAW,WAAW;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,QAAQ,CAAA;CAAE;AAElF,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAM,GAAG,SAAS,CAcxG;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC,CAiBtG"}

package/dist/index.js

@@ -0,0 +1,52 @@
+import { compile, createProcessor } from '@mdx-js/mdx';
+import matter from 'gray-matter';
+import { parseDocument } from 'yaml';
+import { SourceMapGenerator } from 'source-map';
+export function parseMDX(source, options = {}) {
+    const parsed = options.frontmatter === false ? { content: source, data: {} } : matter(source, {
+        engines: { yaml: (value) => {
+                const document = parseDocument(value, { schema: 'core', uniqueKeys: true });
+                if (document.errors.length)
+                    throw document.errors[0];
+                return document.toJS({ maxAliasCount: 100 });
+            } },
+    });
+    if (parsed.data === null || typeof parsed.data !== 'object' || Array.isArray(parsed.data)) {
+        throw new TypeError('MDX frontmatter must be a YAML mapping');
+    }
+    const frontmatter = JSON.parse(JSON.stringify(parsed.data));
+    const removed = source.slice(0, source.length - parsed.content.length);
+    return { frontmatter, content: '\n'.repeat((removed.match(/\n/g) || []).length) + parsed.content };
+}
+/** Compile a document to React JSX-runtime code without selecting a renderer. */
+export async function compileMDX(source, options = {}) {
+    const { filePath = 'document.mdx', frontmatter = true, remarkPlugins = [], rehypePlugins = [], ...rest } = options;
+    const parsed = parseMDX(source, { frontmatter });
+    const metadataNode = createProcessor().parse(`export const frontmatter = JSON.parse(${JSON.stringify(JSON.stringify(parsed.frontmatter))})`).children[0];
+    const injectMetadata = () => root => {
+        if (root.children.some(node => node.type === 'mdxjsEsm' && /\bfrontmatter\b/.test(node.value))) {
+            throw new Error('The frontmatter binding is reserved; use a different name in MDX imports/exports');
+        }
+        root.children.unshift(structuredClone(metadataNode));
+    };
+    const file = await compile({ value: parsed.content, path: filePath }, {
+        ...rest, SourceMapGenerator,
+        remarkPlugins: [...(remarkPlugins ?? []), injectMetadata],
+        rehypePlugins: [...(rehypePlugins ?? []), removeBlockWhitespace],
+    });
+    if (file.map)
+        file.map.sourcesContent = [source];
+    return { code: String(file), map: file.map ? JSON.stringify(file.map) : undefined, frontmatter: parsed.frontmatter };
+}
+// Whitespace between block nodes becomes unwanted Text children on native/design hosts.
+const removeBlockWhitespace = () => root => {
+    function visit(node) {
+        if (node.type === 'root' || (node.type === 'element' && ['ul', 'ol', 'blockquote'].includes(node.tagName))) {
+            node.children = node.children.filter(child => child.type !== 'text' || child.value.trim());
+        }
+        if ('children' in node && node.tagName !== 'pre')
+            node.children.forEach(visit);
+    }
+    visit(root);
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@react-platform/mdx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Renderer-independent MDX compilation, YAML metadata and bundler integration.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./esbuild": {
+      "types": "./dist/esbuild.d.ts",
+      "import": "./dist/esbuild.js"
+    }
+  },
+  "dependencies": {
+    "@mdx-js/mdx": "^3.1.0",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.8.0",
+    "source-map": "^0.7.6",
+    "@types/hast": "^3.0.0",
+    "@types/mdast": "^4.0.0",
+    "unified": "^11.0.0"
+  },
+  "peerDependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/node": "^22.0.0",
+    "esbuild": "0.25.11",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test tests/*.test.mjs"
+  }
 }