@theseus.run/jsx-md 0.1.1 → 0.2.0

package/src/context.ts

@@ -1,13 +1,38 @@
 /**
- * Minimal synchronous context API for jsx-md.
+ * Synchronous context API for jsx-md — matches the React context shape.
  *
- * Uses a module-level stack map so context values are available synchronously
- * during the render() traversal. Not safe for async or concurrent rendering.
+ * createContext(defaultValue) returns a Context object with a Provider
+ * component. Wrap a render() call with <Ctx.Provider value={...}> and read
+ * the value anywhere in the tree with useContext(Ctx).
+ *
+ * Uses a module-level stack map so values are available synchronously during
+ * the render() traversal. Not safe for async or concurrent rendering.
  */
 
+import { render } from './render.ts';
+import type { VNode } from './jsx-runtime.ts';
+
 export interface Context<T> {
   readonly _id: symbol;
   readonly _default: T;
+  /**
+   * JSX provider component — identical usage to React's Context.Provider.
+   *
+   * Return type is `string` (not `VNode`) because `render()` always returns `string`
+   * and this is the honest, precise type. This means `Provider` is not directly
+   * assignable to `Component<P>` without a cast, even though `string extends VNode`.
+   *
+   * React solves this by typing `Provider` as `ProviderExoticComponent` — a distinct
+   * type with a `$$typeof: symbol` discriminant — rather than a plain function component.
+   * That approach deliberately prevents `Provider` from being used as a generic
+   * `Component` argument, and it returns `ReactNode` (broad) rather than a precise type.
+   *
+   * We keep `=> string` because: (a) no code in this codebase passes `Provider` as a
+   * `Component`-typed value, (b) precision is more useful than assignability here,
+   * and (c) the exotic-component indirection would be engineering for a non-problem.
+   * If that higher-order pattern ever becomes necessary, change this to `=> VNode`.
+   */
+  readonly Provider: (props: { value: T; children?: VNode }) => string;
 }
 
 /**
@@ -18,7 +43,24 @@ export interface Context<T> {
 const stack = new Map<symbol, unknown[]>();
 
 export function createContext<T>(defaultValue: T): Context<T> {
-  return { _id: Symbol(), _default: defaultValue };
+  const _id = Symbol();
+
+  function Provider({ value, children }: { value: T; children?: VNode }): string {
+    let s = stack.get(_id);
+    if (!s) {
+      s = [];
+      stack.set(_id, s);
+    }
+    s.push(value as unknown);
+    try {
+      return render(children ?? null);
+    } finally {
+      s.pop();
+      if (s.length === 0) stack.delete(_id);
+    }
+  }
+
+  return { _id, _default: defaultValue, Provider };
 }
 
 export function useContext<T>(ctx: Context<T>): T {
@@ -40,5 +82,6 @@ export function withContext<T>(ctx: Context<T>, value: T, fn: () => string): str
     return fn();
   } finally {
     s.pop();
+    if (s.length === 0) stack.delete(ctx._id);
   }
 }

package/src/escape.ts

@@ -2,21 +2,35 @@
  * Escapes `&`, `"`, `<`, `>` — for use in XML/HTML attribute values.
  * Escapes for double-quoted HTML/XML attribute values. Single quotes are not
  * escaped — do not use this in single-quoted attribute contexts.
+ *
+ * Single-pass via a lookup map — avoids four sequential .replace() calls.
  */
+const HTML_ATTR_MAP: Record<string, string> = {
+  '&': '&amp;',
+  '"': '&quot;',
+  '<': '&lt;',
+  '>': '&gt;',
+};
+const HTML_ATTR_RE = /[&"<>]/g;
+
 export function escapeHtmlAttr(s: string): string {
-  return s
-    .replace(/&/g, '&amp;')
-    .replace(/"/g, '&quot;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+  return s.replace(HTML_ATTR_RE, (c) => HTML_ATTR_MAP[c]!);
 }
 
-/** Escapes `&`, `<`, `>` — for use in HTML/XML text content (not attributes). */
+/**
+ * Escapes `&`, `<`, `>` — for use in HTML/XML text content (not attributes).
+ *
+ * Single-pass via a lookup map.
+ */
+const HTML_CONTENT_MAP: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+};
+const HTML_CONTENT_RE = /[&<>]/g;
+
 export function escapeHtmlContent(s: string): string {
-  return s
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+  return s.replace(HTML_CONTENT_RE, (c) => HTML_CONTENT_MAP[c]!);
 }
 
 /**
@@ -24,7 +38,7 @@ export function escapeHtmlContent(s: string): string {
  * Markdown link syntax `[text](url)`.
  */
 export function encodeLinkUrl(url: string): string {
-  return url.replace(/[()]/g, (c) => encodeURIComponent(c));
+  return url.replace(/\(/g, '%28').replace(/\)/g, '%29');
 }
 
 /**
@@ -34,3 +48,47 @@ export function encodeLinkUrl(url: string): string {
 export function encodeLinkLabel(text: string): string {
   return text.replace(/[[\]]/g, (c) => encodeURIComponent(c));
 }
+
+/**
+ * Escapes all CommonMark ASCII punctuation metacharacters in a string so that
+ * user-supplied content is treated as literal text by any markdown renderer.
+ *
+ * Useful when interpolating variable strings — filenames, user input, code
+ * identifiers, etc. — into markdown prose where unintended formatting must be
+ * suppressed:
+ *
+ *   <P>File: <Escape>{untrustedFilename}</Escape></P>
+ *   <P>File: {escapeMarkdown(untrustedFilename)}</P>
+ *
+ * Escaped characters: \ ` * _ [ ] ( ) # + - . ! | ~ < >
+ * These cover all CommonMark inline and block trigger characters.
+ * HTML entities (&amp; etc.) are intentionally not escaped here — use
+ * escapeHtmlContent for HTML attribute / tag contexts.
+ */
+const MARKDOWN_ESCAPE_RE = /[\\`*_[\]()#+\-.!|~<>]/g;
+
+export function escapeMarkdown(s: string): string {
+  return s.replace(MARKDOWN_ESCAPE_RE, '\\$&');
+}
+
+/**
+ * Returns the minimum backtick fence length needed to safely wrap `content`
+ * as a CommonMark inline code span or fenced code block.
+ *
+ * CommonMark rule: the fence must be a run of N backticks where N is strictly
+ * greater than the longest run of consecutive backticks in the content.
+ * Minimum is 1 for inline code, 3 for fenced code blocks.
+ */
+export function backtickFenceLength(content: string, minimum: number = 1): number {
+  let maxRun = 0;
+  let currentRun = 0;
+  for (const ch of content) {
+    if (ch === '`') {
+      currentRun++;
+      if (currentRun > maxRun) maxRun = currentRun;
+    } else {
+      currentRun = 0;
+    }
+  }
+  return Math.max(minimum, maxRun + 1);
+}

package/src/index.ts

@@ -9,6 +9,9 @@ export { render } from './render.ts';
 export { createContext, useContext, withContext } from './context.ts';
 export type { Context } from './context.ts';
 
+// Escape utilities
+export { escapeMarkdown } from './escape.ts';
+
 // Primitive components
 export {
   H1, H2, H3, H4, H5, H6,
@@ -18,6 +21,7 @@ export {
   Blockquote,
   Li, Ul, Ol,
   Bold, Code, Italic, Strikethrough, Link, Img,
+  Br, Sup, Sub, Kbd, Escape,
   Md,
   Table, Tr, Th, Td,
   TaskList, Task,
@@ -26,4 +30,4 @@ export {
   Details,
 } from './primitives.tsx';
 
-export type { CalloutType } from './primitives.tsx';
+export type { CalloutType, ColAlign } from './primitives.tsx';

package/src/jsx-runtime.ts

@@ -8,21 +8,34 @@
  * Call `render(node)` from `./render.ts` to produce the final markdown string.
  * All markdown primitives live in primitives.tsx as named components.
  *
- * Fragment circular-dep resolution: Fragment needs render() to flatten children,
- * but render.ts imports types from this file. We use _render-registry.ts as a
- * shared side-channel: render.ts calls registerRender(render) on module init,
- * Fragment defers to callRender(). Any entry point that imports render will
- * register it before rendering starts.
+ * Fragment is a Symbol. render.ts imports this Symbol and handles it explicitly,
+ * keeping the dependency one-way: render.ts → jsx-runtime.ts (no cycle).
  */
 
-import { callRender } from './_render-registry.ts';
-
 // ---------------------------------------------------------------------------
 // VNode types
 // ---------------------------------------------------------------------------
 
+/**
+ * The concrete runtime shape of a JSX element — what the `jsx()` factory always produces.
+ *
+ * Useful for structural inspection of a VNode tree (e.g. testing whether a node is an
+ * element rather than a string, null, or array). The `isVNodeElement` predicate in
+ * render.ts narrows to this type.
+ *
+ * @remarks **Do not use as a component return-type annotation.** TypeScript infers
+ * `JSX.Element` (= `VNode`) as the return type of JSX expressions, not `VNodeElement`.
+ * Annotating a component as `(): VNodeElement` causes TS2322 because `VNode` (the
+ * inferred type) is not assignable to the narrower `VNodeElement`. Use `VNode` instead:
+ * ```ts
+ * // Wrong — TS2322
+ * function MyComp(): VNodeElement { return <P>hi</P>; }
+ * // Correct
+ * function MyComp(): VNode { return <P>hi</P>; }
+ * ```
+ */
 export type VNodeElement = {
-  readonly type: Component | string;
+  readonly type: Component | string | typeof Fragment;
   readonly props: Record<string, unknown>;
 };
 
@@ -36,7 +49,7 @@ export type VNode =
   | ReadonlyArray<VNode>;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type Component<P = any> = (props: P) => string;
+type Component<P = any> = (props: P) => VNode;
 
 // ---------------------------------------------------------------------------
 // JSX namespace
@@ -45,10 +58,10 @@ type Component<P = any> = (props: P) => string;
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace JSX {
   /**
-   * JSX.Element is VNode (not just VNodeElement) so that string-returning
-   * components pass TypeScript's component return-type check. The jsx() factory
-   * always produces VNodeElement at runtime; the wider union here is only needed
-   * to satisfy TypeScript's component-validity check.
+   * JSX.Element is VNode so that components returning any valid VNode
+   * (string, VNodeElement, Fragment, null, etc.) satisfy TypeScript's
+   * component return-type check. The jsx() factory always produces
+   * VNodeElement at runtime; the wider union is only for type-checking.
    */
   export type Element = VNode;
 
@@ -63,12 +76,16 @@ export namespace JSX {
 }
 
 // ---------------------------------------------------------------------------
-// Render registration (avoids circular dep with render.ts)
+// Fragment symbol
 // ---------------------------------------------------------------------------
 
-// Registration and dispatch are handled by _render-registry.ts.
-// render.ts calls registerRender(render) on module init.
-// Fragment calls callRender() to evaluate children.
+/**
+ * Fragment — a unique Symbol used as the `type` of JSX fragment VNodes.
+ * render.ts detects this Symbol and renders children directly, with no wrapper.
+ * Using a Symbol (rather than a function) eliminates the circular dependency
+ * that previously required _render-registry.ts.
+ */
+export const Fragment = Symbol('Fragment');
 
 // ---------------------------------------------------------------------------
 // JSX factory
@@ -77,18 +94,16 @@ export namespace JSX {
 /**
  * JSX factory — called by Bun's compiled JSX. Builds VNode tree; no evaluation.
  *
- * `type` is a function component or a string tag name. String tags are rendered
- * as XML blocks by render.ts: `<tag attrs>\ncontent\n</tag>\n` (or self-closing
- * when the inner content is empty).
+ * `type` is a function component, a string tag name, or the Fragment symbol.
+ * String tags are rendered as XML blocks by render.ts: `<tag attrs>\ncontent\n</tag>\n`
+ * (or self-closing when the inner content is empty).
  */
-export function jsx(type: Component | string, props: Record<string, unknown>): VNodeElement {
+export function jsx(
+  type: Component | string | typeof Fragment,
+  props: Record<string, unknown>,
+): VNodeElement {
   return { type, props };
 }
 
 /** jsxs — same as jsx, used when there are multiple children (children is array) */
 export const jsxs = jsx;
-
-/** Fragment — renders children. Defers to _render-registry to avoid circular imports. */
-export function Fragment({ children }: { children?: VNode }): string {
-  return callRender(children ?? null);
-}