@readme/markdown 13.8.5 → 14.1.0

package/dist/processor/transform/mdxish/components/inline-html.d.ts

@@ -0,0 +1,22 @@
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+/**
+ * Transform inline html nodes with expression attributes
+ * inside paragraphs into `mdxJsxTextElement`s.
+ *
+ * Runs after `mdxishComponentBlocks`, which skips paragraph-parented html
+ * nodes and leaves them for this pass. Two producers put html nodes inside
+ * paragraphs:
+ *   1. The `mdxComponent` text tokenizer, for lowercase tags with `{…}`
+ *      attribute expressions (e.g. `<a href={url}>here</a>`).
+ *   2. CommonMark's built-in html-text tokenizer, for PascalCase components
+ *      (e.g. a single html node for self-closing `<C />`).
+ *
+ * Eligibility mirrors `mdxishComponentBlocks`: lowercase tags only promote
+ * when they carry an expression attribute; plain inline HTML like
+ * `<a href="x">` stays as an html node for rehype-raw.
+ */
+declare const mdxishInlineMdxHtmlBlocks: Plugin<[{
+    safeMode?: boolean;
+}?], Root>;
+export default mdxishInlineMdxHtmlBlocks;

package/dist/processor/transform/mdxish/{mdxish-inline-components.d.ts → components/inline-mdx-blocks.d.ts}

@@ -1,11 +1,11 @@
 import type { Parent } from 'mdast';
 import type { Plugin } from 'unified';
 /**
- * Transforms inline html component nodes (e.g. <Anchor>) into proper MDAST phrasing content.
+ * Transforms inline MDX blocks inside html nodes (e.g. <Anchor>) into proper MDAST phrasing content.
  *
  * Inline components are excluded from mdxishComponentBlocks (which only handles block-level
  * elements), so they remain as scattered html/text/html sibling nodes inside a paragraph.
  * This plugin merges them into a single typed MDAST node.
  */
-declare const mdxishInlineComponents: Plugin<[], Parent>;
-export default mdxishInlineComponents;
+declare const mdxishInlineMdxComponents: Plugin<[], Parent>;
+export default mdxishInlineMdxComponents;

package/dist/processor/transform/mdxish/components/mdx-blocks.d.ts

@@ -0,0 +1,34 @@
+import type { Parent } from 'mdast';
+import type { Plugin } from 'unified';
+export { parseAttributes, parseTag } from '../../../../lib/utils/mdxish/mdxish-component-tag-parser';
+/**
+ * Transform PascalCase HTML nodes into mdxJsxFlowElement nodes.
+ *
+ * Remark parses unknown/custom component tags as raw HTML nodes.
+ * These are the custom readme MDX syntax for components.
+ * This transformer identifies these patterns and converts them to proper MDX JSX elements so they
+ * can be accurately recognized and rendered later with their component definition code.
+ *
+ * The mdx-component micromark tokenizer ensures that multi-line components are captured
+ * as single HTML nodes, so this transformer only needs to handle two cases:
+ *
+ * ### 1. Self-closing tags
+ * ```
+ * <Component />
+ * ```
+ * Parsed as: `html: "<Component />"`
+ *
+ * ### 2. Self-contained blocks (entire component in single HTML node)
+ * ```
+ * <Component>
+ *   content
+ * </Component>
+ * ```
+ * Parsed as: `html: "<Component>\n  content\n</Component>"`
+ * The opening tag, content, and closing tag are all captured in one HTML node
+ * (guaranteed by the mdx-component tokenizer).
+ */
+declare const mdxishMdxComponentBlocks: Plugin<[{
+    safeMode?: boolean;
+}?], Parent>;
+export default mdxishMdxComponentBlocks;

package/dist/processor/transform/mdxish/components/utils.d.ts

@@ -0,0 +1,29 @@
+import type { Html, PhrasingContent } from 'mdast';
+import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxTextElement } from 'mdast-util-mdx-jsx';
+export type MdxAttributes = (MdxJsxAttribute | MdxJsxExpressionAttribute)[];
+/**
+ * Shared unified processor for re-parsing the body of an MDX-ish component.
+ * Used by both the block and inline-block transformers so a nested component
+ * (e.g. `<Anchor>text with <b>bold</b></Anchor>`) goes through the same
+ * tokenizer chain as the top-level parse.
+ */
+export declare const inlineMdProcessor: import("unified").Processor<import("mdast").Root, undefined, undefined, undefined, undefined>;
+/**
+ * True when a tag name starts with an uppercase letter — ReadMe's marker for
+ * a custom MDX component (vs a lowercase HTML tag).
+ */
+export declare const isPascalCase: (tag: string) => boolean;
+/**
+ * True when the attribute list contains at least one JSX expression value
+ * (e.g. `href={url}`). The `mdxComponent` tokenizer only claims lowercase
+ * tags when they carry one of these; both block transformers use the same
+ * signal to decide eligibility.
+ */
+export declare const hasExpressionAttr: (attributes: MdxAttributes) => boolean;
+/**
+ * Factory for the `mdxJsxTextElement` node shape. `position` is optional
+ * because the two call sites differ: the tokenized-tag path carries the
+ * original html node's position forward, while the sibling-merge path
+ * composes children from pre-existing nodes with no outer position.
+ */
+export declare const toMdxJsxTextElement: (name: string, attributes: MdxAttributes, children: PhrasingContent[], position?: Html["position"]) => MdxJsxTextElement;

package/dist/processor/transform/mdxish/evaluate-expressions.d.ts

@@ -1,11 +1,11 @@
 import type { Root } from 'mdast';
 import type { Plugin } from 'unified';
-import { type JSXContext } from './preprocess-jsx-expressions';
 /**
- * AST transformer to evaluate MDX expressions using the provided context.
+ * AST transformer to evaluate MDX expressions.
  * Replaces mdxFlowExpression and mdxTextExpression nodes with their evaluated values.
+ * Runs with no scope, so only self-contained expressions resolve
+ * (e.g. `{1+1}`, `{"hi".toUpperCase()}`); anything that references an external
+ * identifier falls through to the error branch and is kept as literal `{...}` text.
  */
-declare const evaluateExpressions: Plugin<[{
-    context?: JSXContext;
-}], Root>;
+declare const evaluateExpressions: Plugin<[], Root>;
 export default evaluateExpressions;

package/dist/processor/transform/mdxish/normalize-mdx-jsx-nodes.d.ts

@@ -0,0 +1,15 @@
+import type { Root } from 'hast';
+import type { Plugin } from 'unified';
+/**
+ * Rewrite `mdx-jsx` nodes (stitched through rehypeRaw untouched) into standard
+ * `element` nodes so rehype-react and downstream element-walking plugins handle
+ * them normally. Non-primitive attribute values — objects, arrays, numbers —
+ * stay as real JS values here because they never went through parse5.
+ *
+ * Tag names that match a standard HTML element are lowercased to match what
+ * parse5 used to produce during the rehypeRaw round-trip (e.g. `<Table>` that
+ * slipped past the mdxishTables transformer still ends up as `<table>`).
+ * PascalCase custom component names are left alone for `rehypeMdxishComponents`.
+ */
+declare const normalizeMdxJsxNodes: Plugin<[], Root>;
+export default normalizeMdxJsxNodes;

package/dist/processor/transform/mdxish/preprocess-jsx-expressions.d.ts

@@ -1,26 +1,6 @@
 export declare function base64Decode(str: string): string;
-export declare const JSON_VALUE_MARKER = "__MDXISH_JSON__";
 export declare const HTML_BLOCK_CONTENT_START = "<!--RDMX_HTMLBLOCK:";
 export declare const HTML_BLOCK_CONTENT_END = ":RDMX_HTMLBLOCK-->";
-/**
- * Pre-processes JSX-like expressions before markdown parsing.
- * Converts href={'value'} to href="value", evaluates {expressions}, etc.
- */
-export type JSXContext = Record<string, unknown>;
-/**
- * Evaluates a JavaScript expression using context variables.
- *
- * @param expression
- * @param context
- * @returns The evaluated result
- * @example
- * ```typescript
- * const context = { baseUrl: 'https://example.com', path: '/api' };
- * evaluateExpression('baseUrl + path', context)
- * // Returns: 'https://example.com/api'
- * ```
- */
-export declare function evaluateExpression(expression: string, context: JSXContext): any;
 /**
  * Removes JSX-style comments (e.g., { /* comment *\/ }) from content.
  *
@@ -34,11 +14,13 @@ export declare function evaluateExpression(expression: string, context: JSXConte
  */
 export declare function removeJSXComments(content: string): string;
 /**
- * Preprocesses JSX-like expressions in markdown before parsing.
- * Inline expressions are handled separately; attribute expressions are processed here.
+ * Preprocesses JSX-like markdown content before parsing.
+ *
+ * JSX attribute expressions (`href={baseUrl}`) are no longer rewritten here —
+ * they flow through the tokenizer as `mdxJsxAttributeValueExpression` nodes
+ * and are evaluated at the hast handler step.
  *
  * @param content
- * @param context
  * @returns Preprocessed content ready for markdown parsing
  */
-export declare function preprocessJSXExpressions(content: string, context?: JSXContext): string;
+export declare function preprocessJSXExpressions(content: string): string;

package/dist/processor/transform/mdxish/restore-snake-case-component-name.d.ts

@@ -1,4 +1,4 @@
-import type { SnakeCaseMapping } from './mdxish-snake-case-components';
+import type { SnakeCaseMapping } from './components/snake-case-components';
 import type { Parent } from 'mdast';
 import type { Plugin } from 'unified';
 interface Options {

package/dist/processor/utils.d.ts

@@ -2,6 +2,20 @@ import type { Root as HastRoot } from 'hast';
 import type { Node, Root as MdastRoot, Root } from 'mdast';
 import type { MdxJsxFlowElement, MdxJsxTextElement, MdxjsEsm } from 'mdast-util-mdx';
 import type { MdxJsxAttribute } from 'mdast-util-mdx-jsx';
+/**
+ * Evaluate a JavaScript expression source and return its value.
+ *
+ * Wrapping in parens lets object literals (`{color: 'red'}`) parse as
+ * expressions. Runs with no scope, so only self-contained literals resolve.
+ *
+ * > ☢️ **Danger**: this `eval`s JavaScript. Only call when safeMode is off —
+ * > safeMode's contract is that expression syntax is never evaluated, and the
+ * > pipeline guards against reaching this path by keeping attribute expressions
+ * > as literal strings and skipping the expression transformer entirely.
+ *
+ * Throws on parse/runtime error; callers decide the fallback.
+ */
+export declare function evaluate(source: string): any;
 /**
  * Formats the hProperties of a node as a string, so they can be compiled back into JSX/MDX.
  * This currently sets all the values to a string since we process/compile the MDX on the fly

package/package.json

@@ -2,7 +2,7 @@
   "name": "@readme/markdown",
   "description": "ReadMe's React-based Markdown parser",
   "author": "Rafe Goldberg <rafe@readme.io>",
-  "version": "13.8.5",
+  "version": "14.1.0",
   "main": "dist/main.node.js",
   "types": "dist/index.d.ts",
   "browser": "dist/main.js",

package/styles/gfm.scss

@@ -209,14 +209,14 @@
 
   ol ol,
   ul ol {
-    list-style-type: lower-roman;
+    list-style-type: lower-alpha;
   }
 
   ol ol ol,
   ol ul ol,
   ul ol ol,
   ul ul ol {
-    list-style-type: lower-alpha;
+    list-style-type: lower-roman;
   }
 
   dd {

package/types.d.ts

@@ -1,5 +1,5 @@
 import type { NodeTypes } from './enums';
-import type { Element } from 'hast';
+import type { Element, ElementContent, Properties } from 'hast';
 import type {
   Code,
   Data,
@@ -19,6 +19,31 @@ import type { MdxJsxFlowElementHast } from 'mdast-util-mdx-jsx';
 import type { MDXModule } from 'mdx/types';
 import type { Position } from 'unist';
 
+/**
+ * Custom hast node emitted by `mdxJsxElementHandler` for every MDX JSX element.
+ * Registered with hast below so the unified/unist tooling (remark-rehype handlers,
+ * unist-util-visit, rehype-raw's passThrough) recognizes it as a first-class
+ * hast node. `properties` intentionally widens `hast`'s `Properties` type because
+ * attribute expressions evaluate to real JS values (objects, arrays, numbers)
+ * which don't fit hast's HTML-attribute-oriented `PropertyValue` union.
+ */
+export interface MdxJsx {
+  children: ElementContent[];
+  position?: Position;
+  properties: Properties;
+  tagName: string;
+  type: 'mdx-jsx';
+}
+
+declare module 'hast' {
+  interface RootContentMap {
+    'mdx-jsx': MdxJsx;
+  }
+  interface ElementContentMap {
+    'mdx-jsx': MdxJsx;
+  }
+}
+
 export type Callout = Omit<Blockquote, 'children' | 'type'> & {
   children: BlockContent[];
   data: Data & {

package/dist/processor/transform/mdxish/constants.d.ts

@@ -1,5 +0,0 @@
-/**
- * Inline component tags handled by mdxish-inline-components.ts.
- * Also excluded from block-level handling in mdxish-component-blocks.ts.
- */
-export declare const INLINE_COMPONENT_TAGS: Set<string>;

package/dist/processor/transform/mdxish/mdxish-component-blocks.d.ts

@@ -1,69 +0,0 @@
-import type { Parent } from 'mdast';
-import type { MdxJsxAttribute } from 'mdast-util-mdx-jsx';
-import type { Plugin } from 'unified';
-/**
- * Convert raw attribute string into mdxJsxAttribute entries.
- * Handles both key-value attributes (theme="info") and boolean attributes (empty).
- */
-export declare const parseAttributes: (raw: string) => MdxJsxAttribute[];
-/**
- * Transform PascalCase HTML nodes into mdxJsxFlowElement nodes.
- *
- * Remark parses unknown/custom component tags as raw HTML nodes.
- * These are the custom readme MDX syntax for components.
- * This transformer identifies these patterns and converts them to proper MDX JSX elements so they
- * can be accurately recognized and rendered later with their component definition code.
- * Though for some tags, we need to handle them specially
- *
- * ## Supported HTML Structures
- *
- * ### 1. Self-closing tags
- * ```
- * <Component />
- * ```
- * Parsed as: `html: "<Component />"`
- *
- * ### 2. Self-contained blocks (entire component in single HTML node)
- * ```
- * <Button>Click me</Button>
- * ```
- * ```
- * <Component>
- *   <h2>Title</h2>
- *   <p>Content</p>
- * </Component>
- * ```
- * Parsed as: `html: "<Component>\n  <h2>Title</h2>\n  <p>Content</p>\n</Component>"`
- * The opening tag, content, and closing tag are all captured in one HTML node.
- *
- * ### 3. Multi-sibling components (closing tag in a following sibling)
- * Handles various structures where the closing tag is in a later sibling, such as:
- *
- * #### 3a. Block components (closing tag in sibling paragraph)
- * ```
- * <Callout>
- * Some **markdown** content
- * </Callout>
- * ```
- *
- * #### 3b. Multi-paragraph components (closing tag several siblings away)
- * ```
- * <Callout>
- *
- * First paragraph
- *
- * Second paragraph
- * </Callout>
- * ```
- *
- * #### 3c. Nested components split by blank lines (closing tag embedded in HTML sibling)
- * ```
- * <Outer>
- *   <Inner>content</Inner>
- *
- *   <Inner>content</Inner>
- * </Outer>
- * ```
- */
-declare const mdxishComponentBlocks: Plugin<[], Parent>;
-export default mdxishComponentBlocks;