@sidvishnoi/imd 0.0.1

package/README.md

@@ -0,0 +1,108 @@
+# @sidvishnoi/imd
+
+A tiny inline-markdown renderer for small strings, with support for React, Preact, DOM, and HTML strings.
+
+## Why
+
+i18n strings often need a bit of inline formatting (a bold word, a link), but pulling in a full markdown parser for that is overkill, and hand-splitting strings around `<a>` tags in every component is repetitive and easy to get wrong across languages. `imd` gives translators a tiny, predictable syntax to write in, and gives you one `md()` call per rendering target that turns their string into real elements, with full control over how each piece (a link, a button, a custom tag) actually renders.
+
+## Usage
+
+Install the package (`npm i -S @sidvishnoi/imd`), then import the backend for whatever you're rendering to. Each module exports the same shape: `md(text, renderers?)`.
+
+### React
+
+```tsx
+import { md } from '@sidvishnoi/imd/react';
+
+const TEXT = 'Please review our [terms of service](/terms) before continuing.';
+
+{md(TEXT, { link: (children, url) => (<a href={url} className="link">{children}</a>) })}
+// Renders: Please review our <a href="/terms" class="link">terms of service</a> before continuing.
+```
+
+### Preact
+
+```tsx
+import { md } from '@sidvishnoi/imd/preact';
+
+const TEXT = 'Your changes are *saved* automatically.';
+
+{md(TEXT, { bold: (children) => <strong class="font-bold">{children}</strong> })}
+// Renders: Your changes are <strong class="font-bold">saved</strong> automatically.
+```
+
+### DOM
+
+Returns `Node[]`; insert with `container.replaceChildren(...)`.
+
+```ts
+import { md } from '@sidvishnoi/imd/dom';
+
+const TEXT = "This can't be undone. <button>Delete account</button>";
+
+el.replaceChildren(
+  ...md(TEXT, {
+    button: (children) => {
+      const btn = document.createElement('button');
+      btn.className = 'btn-danger';
+      btn.append(...children);
+      return btn;
+    },
+  }),
+);
+// el's markup is now:
+// This can't be undone. <button class="btn-danger">Delete account</button>
+```
+
+### HTML string
+
+Returns a `string`; children arrive already joined, so you can interpolate them directly.
+
+```ts
+import { md } from '@sidvishnoi/imd/html';
+
+const TEXT = 'Enter your <mark>API key</mark> to continue.';
+
+const markup = md(TEXT, {
+  html: ({ tag, children }) => `<${tag} class="highlight">${children}</${tag}>`,
+});
+// markup:
+// 'Enter your <mark class="highlight">API key</mark> to continue.'
+```
+
+Every renderer above is optional. Anything you don't override falls back to a plain element (`<a href="…">`, `<strong>`, `<em>`) with no attributes added, so `md(text)` with no second argument always works. Renderers just let you attach classes, handlers, or a11y attributes at the call site.
+
+Bold, italics and hyperlinks have a simple to use syntax:
+
+```
+*bold*       -> bold(children) => <strong>{children}</strong>
+_italic_     -> italic(children) => <em>{children}</em>
+[text](url)  -> link(children, url) => <a href="{url}">{children}</a>
+```
+
+For every raw-HTML string, use the `html` renderer to attach custom handlers:
+
+```
+<tag attr="…">…</tag>  -> html({ tag, children, attrs }) => <tag {...attrs}>{children}</tag>
+```
+
+
+For more examples (custom tags, `button`, the `html` catch-all, edge cases in parsing), see [`./tests`](./tests); each source module has a matching test file.
+
+## How it works
+
+`md()` does two things under the hood.
+
+First it parses: the string is scanned left to right for the four patterns above (link, bold, italic, custom tag). At each position the earliest match wins, and if two rules could match at the same spot, link beats bold beats italic beats a custom tag. This ordering is what gives the syntax its known quirks (see Caveats).
+
+Then it renders: the resulting tree is walked node by node. For each element, it tries your renderer for that tag (`link`/`bold`/`italic`/`button`) first, then your generic `html` catch-all if you passed one, then falls back to a plain default element. The first one that doesn't return `undefined` wins.
+
+All of this parsing and rendering logic lives once in a framework-agnostic core. `react`, `preact`, `dom`, and `html` are each just a few lines telling it how to construct an element, a text node, and how to combine a list of children for that target.
+
+## Caveats
+
+- There are no lists, headings, code blocks, or block-level anything, so this isn't CommonMark. It's just enough syntax for a translator to write `click *here*` or `see [our terms](url)` inside a single string.
+- Custom tags can't nest and can't self-close, and attribute values must be quoted; there's no escaping syntax either. This is a fixed grammar, not an extensible one.
+- Because matching is regex and position based rather than a real parser, delimiters are naive: `2 * 3 *` reads as bold, and `a_b_c` reads as italic. That's fine for short, authored UI copy, but reword or restructure the source string if you hit it.
+- Treat these strings as authored content, not user input. This is meant for text your team or translators write, not text submitted by end users.

package/dist/core.d.ts

@@ -0,0 +1,30 @@
+export type MdNode = string | MdElement;
+export interface MdElement {
+    tag: string;
+    attrs: Record<string, string>;
+    children: MdNode[];
+}
+export interface Renderers<T, C = T[]> {
+    bold?: (children: C) => T | undefined;
+    italic?: (children: C) => T | undefined;
+    link?: (children: C, url: string) => T | undefined;
+    button?: (children: C, attrs: Record<string, string>) => T | undefined;
+    html?: (node: {
+        tag: string;
+        attrs: Record<string, string>;
+        children: C;
+    }) => T | undefined;
+}
+export interface Backend<T, C = T[]> {
+    element(tag: string, attrs: Record<string, string>, children: C): T;
+    /** Wrap a plain-text run. */
+    text(value: string): T;
+    /** Combine a rendered sibling list into the value passed as `children`. */
+    combine(nodes: T[]): C;
+    /** Optional: tag an array item (e.g. assign React/Preact keys). */
+    key?(node: T, index: number): T;
+}
+/** Parse a string into a plain node tree */
+export declare function parse(text: string): MdNode[];
+/** Bind an `md(text, renderers)` function to a rendering backend. */
+export declare function createMarkdown<T, C = T[]>(backend: Backend<T, C>): (text: string | null | undefined, renderers?: Renderers<T, C>) => C;

package/dist/core.js

@@ -0,0 +1,92 @@
+// Framework-agnostic core: parse strings into a node tree, then render that
+// tree through a small backend. No runtime dependencies.
+//
+// Syntax (a deliberately tiny engine, not CommonMark):
+//   *bold*                -> strong
+//   _italic_              -> em
+//   [text](url)           -> a (href)
+//   <tag attr="…">…</tag>  any paired inline tag (valid XML-like: no nesting,
+//                          no self-closing, quoted attribute values)
+const ATTR = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+function parseAttrs(raw) {
+    const attrs = {};
+    for (const m of raw.matchAll(ATTR)) {
+        attrs[m[1]] = m[2] ?? m[3];
+    }
+    return attrs;
+}
+const RULES = [
+    {
+        re: /\[([^\]]+)\]\(([^)]*)\)/,
+        parse: (m) => ({ tag: 'a', attrs: { href: m[2] }, inner: m[1] }),
+    },
+    {
+        re: /\*([^*\n]+?)\*/,
+        parse: (m) => ({ tag: 'strong', attrs: {}, inner: m[1] }),
+    },
+    {
+        re: /_([^_\n]+?)_/,
+        parse: (m) => ({ tag: 'em', attrs: {}, inner: m[1] }),
+    },
+    {
+        re: /<([a-zA-Z][\w-]*)((?:\s+[\w-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*>([^<]*)<\/\1\s*>/,
+        parse: (m) => ({ tag: m[1], attrs: parseAttrs(m[2]), inner: m[3] }),
+    },
+];
+/** Parse a string into a plain node tree */
+export function parse(text) {
+    const nodes = [];
+    let rest = text;
+    while (rest) {
+        // Earliest match wins; ties favour rule order (link > bold > italic > tag).
+        let best = null;
+        for (const rule of RULES) {
+            const m = rule.re.exec(rest);
+            if (m && (best === null || m.index < best.m.index))
+                best = { rule, m };
+        }
+        if (best === null) {
+            nodes.push(rest);
+            break;
+        }
+        const { rule, m } = best;
+        if (m.index > 0)
+            nodes.push(rest.slice(0, m.index));
+        const { tag, attrs, inner } = rule.parse(m);
+        nodes.push({ tag, attrs, children: parse(inner) });
+        rest = rest.slice(m.index + m[0].length);
+    }
+    return nodes;
+}
+function renderElement(el, children, b, r) {
+    const { tag, attrs } = el;
+    let out;
+    switch (tag) {
+        case 'a':
+            out = r.link?.(children, attrs.href ?? '');
+            break;
+        case 'strong':
+            out = r.bold?.(children);
+            break;
+        case 'em':
+            out = r.italic?.(children);
+            break;
+        case 'button':
+            out = r.button?.(children, attrs);
+            break;
+    }
+    if (out === undefined)
+        out = r.html?.({ tag, attrs, children });
+    return out === undefined ? b.element(tag, attrs, children) : out;
+}
+function renderList(nodes, b, r) {
+    const items = nodes.map((node) => typeof node === 'string'
+        ? b.text(node)
+        : renderElement(node, renderList(node.children, b, r), b, r));
+    const { key } = b;
+    return b.combine(key ? items.map((n, i) => key(n, i)) : items);
+}
+/** Bind an `md(text, renderers)` function to a rendering backend. */
+export function createMarkdown(backend) {
+    return (text, renderers = {}) => renderList(parse(text ?? ''), backend, renderers);
+}

package/dist/dom.d.ts

@@ -0,0 +1,3 @@
+import { type Renderers } from './core.js';
+export declare const md: (text: string | null | undefined, renderers?: Renderers<Node, Node[]>) => Node[];
+export type { Renderers };

package/dist/dom.js

@@ -0,0 +1,14 @@
+import { createMarkdown } from './core.js';
+const backend = {
+    element: (tag, attrs, children) => {
+        const el = document.createElement(tag);
+        for (const name in attrs)
+            el.setAttribute(name, attrs[name]);
+        for (const child of children)
+            el.appendChild(child);
+        return el;
+    },
+    text: (value) => document.createTextNode(value),
+    combine: (nodes) => nodes,
+};
+export const md = createMarkdown(backend);

package/dist/html.d.ts

@@ -0,0 +1,3 @@
+import { type Renderers } from './core.js';
+export declare const md: (text: string | null | undefined, renderers?: Renderers<string, string>) => string;
+export type { Renderers };

package/dist/html.js

@@ -0,0 +1,17 @@
+import { createMarkdown } from './core.js';
+const ESC_TEXT = { '&': '&amp;', '<': '&lt;', '>': '&gt;' };
+const ESC_ATTR = { '&': '&amp;', '"': '&quot;' };
+const escapeText = (s) => s.replace(/[&<>]/g, (c) => ESC_TEXT[c]);
+const escapeAttr = (s) => s.replace(/[&"]/g, (c) => ESC_ATTR[c]);
+// C = string: children arrive already joined, so `${children}` just works.
+const backend = {
+    element: (tag, attrs, children) => {
+        const a = Object.keys(attrs)
+            .map((k) => ` ${k}="${escapeAttr(attrs[k])}"`)
+            .join('');
+        return `<${tag}${a}>${children}</${tag}>`;
+    },
+    text: (value) => escapeText(value),
+    combine: (nodes) => nodes.join(''),
+};
+export const md = createMarkdown(backend);

package/dist/preact.d.ts

@@ -0,0 +1,4 @@
+import { type ComponentChild } from 'preact';
+import { type Renderers } from './core.js';
+export declare const md: (text: string | null | undefined, renderers?: Renderers<ComponentChild, ComponentChild[]>) => ComponentChild[];
+export type { Renderers };

package/dist/preact.js

@@ -0,0 +1,13 @@
+import { cloneElement, h, isValidElement } from 'preact';
+import { createMarkdown } from './core.js';
+const backend = {
+    element: (tag, attrs, children) => h(tag, attrs, children.length ? children : null),
+    text: (value) => value,
+    combine: (nodes) => nodes,
+    // Stringify: Preact's cloneElement does `props.key || vnode.key`, so a
+    // falsy numeric key (index 0) is silently dropped otherwise.
+    key: (node, index) => isValidElement(node) && node.key == null
+        ? cloneElement(node, { key: String(index) })
+        : node,
+};
+export const md = createMarkdown(backend);

package/dist/react.d.ts

@@ -0,0 +1,4 @@
+import { type ReactNode } from 'react';
+import { type Renderers } from './core.js';
+export declare const md: (text: string | null | undefined, renderers?: Renderers<ReactNode, ReactNode[]>) => ReactNode[];
+export type { Renderers };

package/dist/react.js

@@ -0,0 +1,9 @@
+import { cloneElement, createElement, isValidElement } from 'react';
+import { createMarkdown } from './core.js';
+const backend = {
+    element: (tag, attrs, children) => createElement(tag, attrs, children.length ? children : undefined),
+    text: (value) => value,
+    combine: (nodes) => nodes,
+    key: (node, index) => isValidElement(node) && node.key == null ? cloneElement(node, { key: index }) : node,
+};
+export const md = createMarkdown(backend);

package/package.json

@@ -0,0 +1,86 @@
+{
+	"name": "@sidvishnoi/imd",
+	"version": "0.0.1",
+	"description": "Tiny inline-markdown renderer for i18n strings, with pluggable backends.",
+	"keywords": [
+		"markdown",
+		"i18n",
+		"inline",
+		"react",
+		"preact",
+		"dom",
+		"html"
+	],
+	"license": "MIT",
+	"type": "module",
+	"sideEffects": false,
+	"engines": {
+		"node": ">=24"
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"exports": {
+		"./core": {
+			"types": "./dist/core.d.ts",
+			"default": "./dist/core.js"
+		},
+		"./react": {
+			"types": "./dist/react.d.ts",
+			"default": "./dist/react.js"
+		},
+		"./preact": {
+			"types": "./dist/preact.d.ts",
+			"default": "./dist/preact.js"
+		},
+		"./dom": {
+			"types": "./dist/dom.d.ts",
+			"default": "./dist/dom.js"
+		},
+		"./html": {
+			"types": "./dist/html.d.ts",
+			"default": "./dist/html.js"
+		}
+	},
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"check": "biome check .",
+		"typecheck": "tsc --noEmit",
+		"format": "biome format --write .",
+		"lint": "biome lint .",
+		"lint:fix": "biome lint --write .",
+		"clean": "rm -rf dist",
+		"build": "tsc -p tsconfig.build.json",
+		"prepublishOnly": "pnpm clean && pnpm build"
+	},
+	"peerDependencies": {
+		"preact": ">=10",
+		"react": ">=18"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"preact": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.3",
+		"@types/jsdom": "^28.0.3",
+		"@types/react": "^19.0.0",
+		"@types/react-dom": "^19.2.3",
+		"jsdom": "^29.1.1",
+		"preact": "^10.29.7",
+		"react": "^19.2.7",
+		"react-dom": "^19.2.7",
+		"typescript": "^7.0.2",
+		"vitest": "^4.1.10"
+	},
+	"packageManager": "pnpm@11.13.0",
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/core.ts

@@ -0,0 +1,147 @@
+// Framework-agnostic core: parse strings into a node tree, then render that
+// tree through a small backend. No runtime dependencies.
+//
+// Syntax (a deliberately tiny engine, not CommonMark):
+//   *bold*                -> strong
+//   _italic_              -> em
+//   [text](url)           -> a (href)
+//   <tag attr="…">…</tag>  any paired inline tag (valid XML-like: no nesting,
+//                          no self-closing, quoted attribute values)
+
+export type MdNode = string | MdElement;
+
+export interface MdElement {
+	tag: string;
+	attrs: Record<string, string>;
+	children: MdNode[];
+}
+
+// Per-element render overrides. Return `undefined` to fall through.
+//
+// `T` is one rendered node; `C` is how a run of children is combined for a
+// backend (an array for React/Preact/DOM, a joined string for HTML).
+export interface Renderers<T, C = T[]> {
+	bold?: (children: C) => T | undefined;
+	italic?: (children: C) => T | undefined;
+	link?: (children: C, url: string) => T | undefined;
+	button?: (children: C, attrs: Record<string, string>) => T | undefined;
+	html?: (node: { tag: string; attrs: Record<string, string>; children: C }) => T | undefined;
+}
+
+// Turns tag/attrs/children into target-specific nodes. One per framework.
+export interface Backend<T, C = T[]> {
+	element(tag: string, attrs: Record<string, string>, children: C): T;
+	/** Wrap a plain-text run. */
+	text(value: string): T;
+	/** Combine a rendered sibling list into the value passed as `children`. */
+	combine(nodes: T[]): C;
+	/** Optional: tag an array item (e.g. assign React/Preact keys). */
+	key?(node: T, index: number): T;
+}
+
+interface Parsed {
+	tag: string;
+	attrs: Record<string, string>;
+	inner: string;
+}
+
+interface Rule {
+	re: RegExp;
+	parse: (m: RegExpExecArray) => Parsed;
+}
+
+const ATTR = /([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+function parseAttrs(raw: string): Record<string, string> {
+	const attrs: Record<string, string> = {};
+	for (const m of raw.matchAll(ATTR)) {
+		attrs[m[1]] = m[2] ?? m[3];
+	}
+	return attrs;
+}
+
+const RULES: Rule[] = [
+	{
+		re: /\[([^\]]+)\]\(([^)]*)\)/,
+		parse: (m) => ({ tag: 'a', attrs: { href: m[2] }, inner: m[1] }),
+	},
+	{
+		re: /\*([^*\n]+?)\*/,
+		parse: (m) => ({ tag: 'strong', attrs: {}, inner: m[1] }),
+	},
+	{
+		re: /_([^_\n]+?)_/,
+		parse: (m) => ({ tag: 'em', attrs: {}, inner: m[1] }),
+	},
+	{
+		re: /<([a-zA-Z][\w-]*)((?:\s+[\w-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*>([^<]*)<\/\1\s*>/,
+		parse: (m) => ({ tag: m[1], attrs: parseAttrs(m[2]), inner: m[3] }),
+	},
+];
+
+/** Parse a string into a plain node tree */
+export function parse(text: string): MdNode[] {
+	const nodes: MdNode[] = [];
+	let rest = text;
+
+	while (rest) {
+		// Earliest match wins; ties favour rule order (link > bold > italic > tag).
+		let best: { rule: Rule; m: RegExpExecArray } | null = null;
+		for (const rule of RULES) {
+			const m = rule.re.exec(rest);
+			if (m && (best === null || m.index < best.m.index)) best = { rule, m };
+		}
+
+		if (best === null) {
+			nodes.push(rest);
+			break;
+		}
+
+		const { rule, m } = best;
+		if (m.index > 0) nodes.push(rest.slice(0, m.index));
+		const { tag, attrs, inner } = rule.parse(m);
+		nodes.push({ tag, attrs, children: parse(inner) });
+		rest = rest.slice(m.index + m[0].length);
+	}
+
+	return nodes;
+}
+
+function renderElement<T, C>(el: MdElement, children: C, b: Backend<T, C>, r: Renderers<T, C>): T {
+	const { tag, attrs } = el;
+
+	let out: T | undefined;
+	switch (tag) {
+		case 'a':
+			out = r.link?.(children, attrs.href ?? '');
+			break;
+		case 'strong':
+			out = r.bold?.(children);
+			break;
+		case 'em':
+			out = r.italic?.(children);
+			break;
+		case 'button':
+			out = r.button?.(children, attrs);
+			break;
+	}
+
+	if (out === undefined) out = r.html?.({ tag, attrs, children });
+	return out === undefined ? b.element(tag, attrs, children) : out;
+}
+
+function renderList<T, C>(nodes: MdNode[], b: Backend<T, C>, r: Renderers<T, C>): C {
+	const items = nodes.map((node) =>
+		typeof node === 'string'
+			? b.text(node)
+			: renderElement(node, renderList(node.children, b, r), b, r),
+	);
+	const { key } = b;
+	return b.combine(key ? items.map((n, i) => key(n, i)) : items);
+}
+
+/** Bind an `md(text, renderers)` function to a rendering backend. */
+export function createMarkdown<T, C = T[]>(backend: Backend<T, C>) {
+	return (text: string | null | undefined, renderers: Renderers<T, C> = {}): C =>
+		renderList(parse(text ?? ''), backend, renderers);
+}

package/src/dom.ts

@@ -0,0 +1,15 @@
+import { type Backend, createMarkdown, type Renderers } from './core.js';
+
+const backend: Backend<Node> = {
+	element: (tag, attrs, children) => {
+		const el = document.createElement(tag);
+		for (const name in attrs) el.setAttribute(name, attrs[name]);
+		for (const child of children) el.appendChild(child);
+		return el;
+	},
+	text: (value) => document.createTextNode(value),
+	combine: (nodes) => nodes,
+};
+
+export const md = createMarkdown(backend);
+export type { Renderers };

package/src/html.ts

@@ -0,0 +1,21 @@
+import { type Backend, createMarkdown, type Renderers } from './core.js';
+
+const ESC_TEXT: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;' };
+const ESC_ATTR: Record<string, string> = { '&': '&amp;', '"': '&quot;' };
+const escapeText = (s: string) => s.replace(/[&<>]/g, (c) => ESC_TEXT[c]);
+const escapeAttr = (s: string) => s.replace(/[&"]/g, (c) => ESC_ATTR[c]);
+
+// C = string: children arrive already joined, so `${children}` just works.
+const backend: Backend<string, string> = {
+	element: (tag, attrs, children) => {
+		const a = Object.keys(attrs)
+			.map((k) => ` ${k}="${escapeAttr(attrs[k])}"`)
+			.join('');
+		return `<${tag}${a}>${children}</${tag}>`;
+	},
+	text: (value) => escapeText(value),
+	combine: (nodes) => nodes.join(''),
+};
+
+export const md = createMarkdown(backend);
+export type { Renderers };

package/src/preact.ts

@@ -0,0 +1,17 @@
+import { type ComponentChild, cloneElement, h, isValidElement, type VNode } from 'preact';
+import { type Backend, createMarkdown, type Renderers } from './core.js';
+
+const backend: Backend<ComponentChild> = {
+	element: (tag, attrs, children) => h(tag, attrs, children.length ? children : null),
+	text: (value) => value,
+	combine: (nodes) => nodes,
+	// Stringify: Preact's cloneElement does `props.key || vnode.key`, so a
+	// falsy numeric key (index 0) is silently dropped otherwise.
+	key: (node, index) =>
+		isValidElement(node) && (node as VNode).key == null
+			? cloneElement(node as VNode, { key: String(index) })
+			: node,
+};
+
+export const md = createMarkdown(backend);
+export type { Renderers };

package/src/react.ts

@@ -0,0 +1,14 @@
+import { cloneElement, createElement, isValidElement, type ReactNode } from 'react';
+import { type Backend, createMarkdown, type Renderers } from './core.js';
+
+const backend: Backend<ReactNode> = {
+	element: (tag, attrs, children) =>
+		createElement(tag, attrs, children.length ? children : undefined),
+	text: (value) => value,
+	combine: (nodes) => nodes,
+	key: (node, index) =>
+		isValidElement(node) && node.key == null ? cloneElement(node, { key: index }) : node,
+};
+
+export const md = createMarkdown(backend);
+export type { Renderers };