mdast-util-sub 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# mdast-util-sub
+
+[mdast](https://github.com/syntax-tree/mdast) utilities for inline substitution (`:sub[INITIAL]{REPLACEMENT}`).
+
+Inline substitution enables progressive disclosure — show brief content initially, reveal full content on activation. This package provides the mdast utilities; for a complete solution, use [`remark-sub`](https://www.npmjs.com/package/remark-sub).
+
+## Install
+
+```bash
+npm install mdast-util-sub
+```
+
+## Usage
+
+```javascript
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { toMarkdown } from 'mdast-util-to-markdown'
+import { sub } from 'micromark-extension-sub'
+import { subFromMarkdown, subToMarkdown } from 'mdast-util-sub'
+
+// Parse
+const tree = fromMarkdown(':sub[initial]{replacement}', {
+  extensions: [sub()],
+  mdastExtensions: [subFromMarkdown()]
+})
+
+// Stringify
+const md = toMarkdown(tree, {
+  extensions: [subToMarkdown()]
+})
+```
+
+## AST
+
+### `Sub`
+
+```javascript
+interface Sub extends Parent {
+  type: 'sub'
+  children: PhrasingContent[]      // Empty at this layer
+  data: {
+    replacement: PhrasingContent[] // Empty at this layer
+    rawInitial: string             // Raw INITIAL text (escapes processed)
+    rawReplacement: string         // Raw REPLACEMENT text (escapes processed)
+  }
+}
+```
+
+At the mdast-util layer, raw content is stored in `rawInitial` and `rawReplacement`. The `children` and `replacement` arrays are populated later by [`remark-sub`](https://www.npmjs.com/package/remark-sub), which re-parses the raw content as inline Markdown.
+
+## Escaping
+
+When serializing to markdown:
+- Unbalanced `]` in INITIAL is escaped as `\]`
+- Unbalanced `}` in REPLACEMENT is escaped as `\}`
+- Balanced brackets/braces don't need escaping
+
+## License
+
+MIT

package/dist/from-markdown.d.ts

@@ -0,0 +1,18 @@
+import type { Extension } from 'mdast-util-from-markdown';
+import type { PhrasingContent } from 'mdast';
+export interface Sub {
+    type: 'sub';
+    children: PhrasingContent[];
+    data: {
+        replacement: PhrasingContent[];
+        rawInitial: string;
+        rawReplacement: string;
+    };
+}
+declare module 'mdast' {
+    interface PhrasingContentMap {
+        sub: Sub;
+    }
+}
+export declare function subFromMarkdown(): Extension;
+//# sourceMappingURL=from-markdown.d.ts.map

package/dist/from-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-markdown.d.ts","sourceRoot":"","sources":["../src/from-markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,SAAS,EAAS,MAAM,0BAA0B,CAAA;AAChF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA;AAE5C,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,KAAK,CAAA;IACX,QAAQ,EAAE,eAAe,EAAE,CAAA;IAC3B,IAAI,EAAE;QACJ,WAAW,EAAE,eAAe,EAAE,CAAA;QAC9B,UAAU,EAAE,MAAM,CAAA;QAClB,cAAc,EAAE,MAAM,CAAA;KACvB,CAAA;CACF;AAED,OAAO,QAAQ,OAAO,CAAC;IACrB,UAAU,kBAAkB;QAC1B,GAAG,EAAE,GAAG,CAAA;KACT;CACF;AAED,wBAAgB,eAAe,IAAI,SAAS,CAgD3C"}

package/dist/from-markdown.js

@@ -0,0 +1,51 @@
+export function subFromMarkdown() {
+    let initialRaw = '';
+    let replacementRaw = '';
+    return {
+        enter: {
+            sub: enterSub,
+            subInitialData: enterSubInitialData,
+            subReplacementData: enterSubReplacementData
+        },
+        exit: {
+            subInitialData: exitSubInitialData,
+            subReplacementData: exitSubReplacementData,
+            sub: exitSub
+        }
+    };
+    function enterSub(token) {
+        // @ts-expect-error: sub is a custom node type
+        this.enter({ type: 'sub', children: [], data: { replacement: [], rawInitial: '', rawReplacement: '' } }, token);
+    }
+    function enterSubInitialData() {
+        initialRaw = '';
+    }
+    function exitSubInitialData(token) {
+        initialRaw = processEscapes(this.sliceSerialize(token), 'initial');
+    }
+    function enterSubReplacementData() {
+        replacementRaw = '';
+    }
+    function exitSubReplacementData(token) {
+        replacementRaw = processEscapes(this.sliceSerialize(token), 'replacement');
+    }
+    function exitSub(token) {
+        // @ts-expect-error: accessing custom node
+        const node = this.stack[this.stack.length - 1];
+        // Store raw text for later re-parsing by the remark plugin
+        node.data.rawInitial = initialRaw;
+        node.data.rawReplacement = replacementRaw;
+        this.exit(token);
+    }
+}
+function processEscapes(input, context) {
+    if (context === 'initial') {
+        // In INITIAL: \] -> ], \[ -> [, \\ -> \
+        return input.replace(/\\([\[\]\\])/g, '$1');
+    }
+    else {
+        // In REPLACEMENT: \} -> }, \{ -> {, \\ -> \
+        return input.replace(/\\([\{\}\\])/g, '$1');
+    }
+}
+//# sourceMappingURL=from-markdown.js.map

package/dist/from-markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-markdown.js","sourceRoot":"","sources":["../src/from-markdown.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,eAAe;IAC7B,IAAI,UAAU,GAAG,EAAE,CAAA;IACnB,IAAI,cAAc,GAAG,EAAE,CAAA;IAEvB,OAAO;QACL,KAAK,EAAE;YACL,GAAG,EAAE,QAAQ;YACb,cAAc,EAAE,mBAAmB;YACnC,kBAAkB,EAAE,uBAAuB;SAC5C;QACD,IAAI,EAAE;YACJ,cAAc,EAAE,kBAAkB;YAClC,kBAAkB,EAAE,sBAAsB;YAC1C,GAAG,EAAE,OAAO;SACb;KACF,CAAA;IAED,SAAS,QAAQ,CAAuB,KAAY;QAClD,8CAA8C;QAC9C,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,CAAA;IACjH,CAAC;IAED,SAAS,mBAAmB;QAC1B,UAAU,GAAG,EAAE,CAAA;IACjB,CAAC;IAED,SAAS,kBAAkB,CAAuB,KAAY;QAC5D,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAA;IACpE,CAAC;IAED,SAAS,uBAAuB;QAC9B,cAAc,GAAG,EAAE,CAAA;IACrB,CAAC;IAED,SAAS,sBAAsB,CAAuB,KAAY;QAChE,cAAc,GAAG,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,CAAA;IAC5E,CAAC;IAED,SAAS,OAAO,CAAuB,KAAY;QACjD,0CAA0C;QAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAQ,CAAA;QAErD,2DAA2D;QAC3D,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QACjC,IAAI,CAAC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAA;QAEzC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAClB,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAa,EAAE,OAAkC;IACvE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,wCAAwC;QACxC,OAAO,KAAK,CAAC,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC,CAAA;IAC7C,CAAC;SAAM,CAAC;QACN,4CAA4C;QAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC,CAAA;IAC7C,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { subFromMarkdown, type Sub } from './from-markdown.js';
+export { subToMarkdown } from './to-markdown.js';
+//# 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,EAAE,eAAe,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { subFromMarkdown } from './from-markdown.js';
+export { subToMarkdown } from './to-markdown.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAY,MAAM,oBAAoB,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/to-markdown.d.ts

@@ -0,0 +1,3 @@
+import type { Options } from 'mdast-util-to-markdown';
+export declare function subToMarkdown(): Options;
+//# sourceMappingURL=to-markdown.d.ts.map

package/dist/to-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-markdown.d.ts","sourceRoot":"","sources":["../src/to-markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,wBAAwB,CAAA;AAGlE,wBAAgB,aAAa,IAAI,OAAO,CAcvC"}

package/dist/to-markdown.js

@@ -0,0 +1,96 @@
+export function subToMarkdown() {
+    return {
+        handlers: {
+            // @ts-expect-error: sub is a custom node type
+            sub: handleSub
+        },
+        unsafe: [
+            {
+                character: ':',
+                after: 'sub\\[',
+                inConstruct: ['phrasing']
+            }
+        ]
+    };
+}
+function handleSub(node, _parent, state, info) {
+    // Serialize children (INITIAL) back to markdown
+    const initialContent = state.containerPhrasing(node, {
+        ...info,
+        before: '[',
+        after: ']'
+    });
+    // Serialize replacement back to markdown
+    // Create a temporary parent node for the replacement content
+    const replacementContent = state.containerPhrasing({ type: 'paragraph', children: node.data.replacement }, {
+        ...info,
+        before: '{',
+        after: '}'
+    });
+    return ':sub[' + escapeInitial(initialContent) + ']{' + escapeReplacement(replacementContent) + '}';
+}
+function escapeInitial(value) {
+    // Only escape unbalanced ] that would close the construct prematurely
+    let result = '';
+    let bracketDepth = 0;
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        // Handle escape sequences - pass through as-is
+        if (char === '\\' && i + 1 < value.length) {
+            result += char + value[i + 1];
+            i++;
+            continue;
+        }
+        if (char === '[') {
+            bracketDepth++;
+            result += char;
+        }
+        else if (char === ']') {
+            if (bracketDepth > 0) {
+                bracketDepth--;
+                result += char;
+            }
+            else {
+                // Unbalanced, must escape
+                result += '\\]';
+            }
+        }
+        else {
+            result += char;
+        }
+    }
+    return result;
+}
+function escapeReplacement(value) {
+    // Only escape unbalanced } that would close the construct prematurely
+    let result = '';
+    let braceDepth = 0;
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        // Handle escape sequences - pass through as-is
+        if (char === '\\' && i + 1 < value.length) {
+            result += char + value[i + 1];
+            i++;
+            continue;
+        }
+        if (char === '{') {
+            braceDepth++;
+            result += char;
+        }
+        else if (char === '}') {
+            if (braceDepth > 0) {
+                braceDepth--;
+                result += char;
+            }
+            else {
+                // Unbalanced, must escape
+                result += '\\}';
+            }
+        }
+        else {
+            result += char;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=to-markdown.js.map

package/dist/to-markdown.js.map

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "mdast-util-sub",
+  "version": "1.0.0",
+  "description": "mdast utility to parse and serialize inline substitution (:sub[...]{...})",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "echo 'Tests run via remark-sub package'",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "mdast-util-from-markdown": "^2.0.0",
+    "mdast-util-to-markdown": "^2.0.0",
+    "micromark-extension-sub": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.16"
+  },
+  "keywords": ["mdast", "substitution", "inline", "toggle"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/weavepage/remark-sub.git",
+    "directory": "packages/mdast-util-sub"
+  }
+}