safe-mdx 0.0.5 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Holocron
+
+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

@@ -10,9 +10,9 @@
 
 ## Features
 
--   Render MDX without `eval` on the server, so you can render MDX in Cloudflare Workers and Vercel Edge
--   Works with React Server Components
--   Supports custom MDX components
+- Render MDX without `eval` on the server, so you can render MDX in Cloudflare Workers and Vercel Edge
+- Works with React Server Components
+- Supports custom MDX components
 
 ## Why
 
@@ -22,9 +22,9 @@ For example in an hypothetical platform similar to Notion, where users can write
 
 Some use cases for this package are:
 
--   Render MDX in Cloudflare Workers and Vercel Edge
--   Safely render dynamically generated MDX code, like inside a ChatGPT like interface
--   Render user generated MDX, like in a multi-tenant SaaS app
+- Render MDX in Cloudflare Workers and Vercel Edge
+- Safely render dynamically generated MDX code, like inside a ChatGPT like interface
+- Render user generated MDX, like in a multi-tenant SaaS app
 
 <br>
 
@@ -78,12 +78,12 @@ If you want to use custom MDX plugins, you can pass your own MDX processed ast.
 
 By default `safe-mdx` already has support for
 
--   frontmatter
--   gfm
+- frontmatter
+- gfm
 
 ```tsx
 import { SafeMdxRenderer } from 'safe-mdx'
-import { remark } from 'remark'
+import { remark, Root } from 'remark'
 import remarkMdx from 'remark-mdx'
 
 const code = `
@@ -94,9 +94,16 @@ This is a paragraph
 <Heading>Custom component</Heading>
 `
 
-const parser = remark().use(remarkMdx)
+const parser = remark()
+    .use(remarkMdx)
+    .use(() => {
+        return (tree, file) => {
+            file.data.ast = tree
+        }
+    })
 
-const mdast = parser.parse(code)
+const file = parser.processSync(code)
+const mdast = file.data.ast as Root
 
 export function Page() {
     return <SafeMdxRenderer code={code} mdast={mdast} />
@@ -139,6 +146,31 @@ export function Page() {
 }
 ```
 
+## Override code block component
+
+It's not pratical to override the code block component using `code` as a component override, because it will also be used for inline code blocks. It also does not have access to meta string and language.
+
+Instead you can use `customTransformer` to return some jsx for a specific mdast node:
+
+```tsx
+<SafeMdxRenderer
+    customTransformer={(node, transform) => {
+        if (node.type === 'code') {
+            const language = node.lang || ''
+            const meta = parseMetaString(node.meta)
+
+            return (
+                <CodeBlock {...meta} lang={language}>
+                    <Pre>
+                        <ShikiRenderer code={node.value} language={language} />
+                    </Pre>
+                </CodeBlock>
+            )
+        }
+    }}
+/>
+```
+
 ## Handling errors
 
 `safe-mdx` ignores missing components or expressions, to show a message to the user in case of these errors you can use `MdastToJsx` directly
@@ -170,7 +202,7 @@ This is ok if you render your MDX in isolation from each tenant, for example on
 
 These features are not supported yet:
 
--   expressions with dynamic values or values defined with `export`
--   importing components or data from other files
+- expressions or values defined with `export`
+- importing components or data from other files
 
-To overcome these limitations you can define custom logic in your components and pass them to `SafeMdxRenderer`. This will also make your MDX files cleaner and easier to read.
+To overcome these limitations you can define custom logic in your components and pass them to `SafeMdxRenderer` `components` prop. This will also make your MDX files cleaner and easier to read.

package/dist/safe-mdx.d.ts

@@ -3,15 +3,21 @@ import { Root } from 'mdast';
 import { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx-jsx';
 import { ReactNode } from 'react';
 type MyRootContent = RootContent | Root;
-export declare function SafeMdxRenderer({ components, code, mdast, }: {
-    components: any;
+export declare function mdxParse(code: string): Root;
+declare module 'mdast' {
+    interface Data {
+        hProperties?: {
+            id?: string;
+        };
+    }
+}
+export type CustomTransformer = (node: MyRootContent, transform: (node: MyRootContent) => ReactNode) => ReactNode | undefined;
+export declare function SafeMdxRenderer({ components, code, mdast, customTransformer, }: {
+    components?: ComponentsMap;
     code?: string;
-    mdast?: any;
+    mdast?: MyRootContent;
+    customTransformer?: CustomTransformer;
 }): any;
-declare const nativeTags: readonly ["blockquote", "strong", "em", "del", "hr", "a", "b", "br", "button", "div", "form", "h1", "h2", "h3", "h4", "head", "iframe", "img", "input", "label", "li", "link", "ol", "p", "path", "picture", "script", "section", "source", "span", "sub", "sup", "svg", "table", "tbody", "td", "tfoot", "th", "thead", "tr", "ul", "video", "code", "pre"];
-type ComponentsMap = {
-    [k in (typeof nativeTags)[number]]?: any;
-};
 export declare class MdastToJsx {
     mdast: MyRootContent;
     str: string;
@@ -20,10 +26,12 @@ export declare class MdastToJsx {
     errors: {
         message: string;
     }[];
-    constructor({ code, mdast, components, }: {
+    customTransformer?: CustomTransformer;
+    constructor({ code, mdast, components, customTransformer, }: {
         code?: string;
-        mdast?: any;
+        mdast?: MyRootContent;
         components?: ComponentsMap;
+        customTransformer?: (node: MyRootContent, transform: (node: MyRootContent) => ReactNode) => ReactNode | undefined;
     });
     mapMdastChildren(node: any): any;
     mapJsxChildren(node: any): any;
@@ -35,5 +43,21 @@ export declare function getJsxAttrs(node: MdxJsxFlowElement | MdxJsxTextElement,
     message: string;
 }) => void): [string, any][];
 export declare function mdastBfs(node: Parent | Node, cb?: (node: Node | Parent) => any): any[];
+declare const nativeTags: readonly ["blockquote", "strong", "em", "del", "hr", "a", "b", "br", "button", "div", "form", "h1", "h2", "h3", "h4", "head", "iframe", "img", "input", "label", "li", "link", "ol", "p", "path", "picture", "script", "section", "source", "span", "sub", "sup", "svg", "table", "tbody", "td", "tfoot", "th", "thead", "tr", "ul", "video", "code", "pre", "figure", "canvas", "details", "dl", "dt", "dd", "fieldset", "footer", "header", "legend", "main", "mark", "nav", "progress", "summary", "time"];
+type ComponentsMap = {
+    [k in (typeof nativeTags)[number]]?: any;
+} & {
+    [key: string]: any;
+};
+/**
+ * https://github.com/mdx-js/mdx/blob/b3351fadcb6f78833a72757b7135dcfb8ab646fe/packages/mdx/lib/plugin/remark-mark-and-unravel.js
+ * A tiny plugin that unravels `<p><h1>x</h1></p>` but also
+ * `<p><Component /></p>` (so it has no knowledge of "HTML").
+ *
+ * It also marks JSX as being explicitly JSX, so when a user passes a `h1`
+ * component, it is used for `# heading` but not for `<h1>heading</h1>`.
+ *
+ */
+export declare function remarkMarkAndUnravel(): (tree: Root) => void;
 export {};
 //# sourceMappingURL=safe-mdx.d.ts.map

package/dist/safe-mdx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe-mdx.d.ts","sourceRoot":"","sources":["../src/safe-mdx.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAGjD,OAAO,EAAE,IAAI,EAAQ,MAAM,OAAO,CAAA;AAClC,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAKzE,OAAO,EAAY,SAAS,EAAE,MAAM,OAAO,CAAA;AAE3C,KAAK,aAAa,GAAG,WAAW,GAAG,IAAI,CAAA;AASvC,wBAAgB,eAAe,CAAC,EAC5B,UAAU,EACV,IAAS,EACT,KAAmB,GACtB;;;;CAAA,OAIA;AAED,QAAA,MAAM,UAAU,8VA6CN,CAAA;AAEV,KAAK,aAAa,GAAG;KAAG,CAAC,IAAI,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG;CAAE,CAAA;AAEjE,qBAAa,UAAU;IACnB,KAAK,EAAE,aAAa,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAK;IACnB,CAAC,EAAE,aAAa,CAAA;IAChB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAK;gBACtB,EACR,IAAS,EACT,KAAwB,EACxB,UAAgC,GACnC;;;;KAAA;IAaD,gBAAgB,CAAC,IAAI,EAAE,GAAG;IAiB1B,cAAc,CAAC,IAAI,EAAE,GAAG;IAiBxB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS;IAsC9C,GAAG;IAQH,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS;CAwOnD;AAED,wBAAgB,WAAW,CACvB,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,EAC3C,OAAO,GAAE,CAAC,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,IAAoB,mBAoE9D;AAcD,wBAAgB,QAAQ,CACpB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,KAAK,GAAG,SAiBpC"}
+{"version":3,"file":"safe-mdx.d.ts","sourceRoot":"","sources":["../src/safe-mdx.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAMjD,OAAO,EAAE,IAAI,EAAQ,MAAM,OAAO,CAAA;AAClC,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAKzE,OAAO,EAAY,SAAS,EAAE,MAAM,OAAO,CAAA;AAE3C,KAAK,aAAa,GAAG,WAAW,GAAG,IAAI,CAAA;AAEvC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAET,IAAI,CAC/B;AAED,OAAO,QAAQ,OAAO,CAAC;IACnB,UAAiB,IAAI;QACjB,WAAW,CAAC,EAAE;YACV,EAAE,CAAC,EAAE,MAAM,CAAA;SACd,CAAA;KACJ;CACJ;AAED,MAAM,MAAM,iBAAiB,GAAG,CAC5B,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,SAAS,KAC5C,SAAS,GAAG,SAAS,CAAA;AAE1B,wBAAgB,eAAe,CAAC,EAC5B,UAAU,EACV,IAAS,EACT,KAAmB,EACnB,iBAAiB,GACpB,EAAE;IACC,UAAU,CAAC,EAAE,aAAa,CAAA;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CACxC,OASA;AAED,qBAAa,UAAU;IACnB,KAAK,EAAE,aAAa,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAK;IACnB,CAAC,EAAE,aAAa,CAAA;IAChB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAK;IAClC,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;gBAEzB,EACR,IAAS,EACT,KAAwB,EACxB,UAAgC,EAChC,iBAAiB,GACpB,EAAE;QACC,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,KAAK,CAAC,EAAE,aAAa,CAAA;QACrB,UAAU,CAAC,EAAE,aAAa,CAAA;QAC1B,iBAAiB,CAAC,EAAE,CAChB,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,SAAS,KAC5C,SAAS,GAAG,SAAS,CAAA;KAC7B;IAcD,gBAAgB,CAAC,IAAI,EAAE,GAAG;IAiB1B,cAAc,CAAC,IAAI,EAAE,GAAG;IAiBxB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS;IAsC9C,GAAG;IAQH,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS;CAiTnD;AAED,wBAAgB,WAAW,CACvB,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,EAC3C,OAAO,GAAE,CAAC,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,IAAoB,mBAmE9D;AAcD,wBAAgB,QAAQ,CACpB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,KAAK,GAAG,SAiBpC;AAUD,QAAA,MAAM,UAAU,+eA6DN,CAAA;AA2RV,KAAK,aAAa,GAAG;KAAG,CAAC,IAAI,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG;CAAE,GAAG;IAChE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACrB,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,KACf,MAAM,IAAI,UAqE9B"}