shiki-transformer-fold 0.1.0

package/LICENSE

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

@@ -0,0 +1,74 @@
+# shiki-transformer-fold
+
+<!-- automd:badges color=yellow -->
+
+[![npm version](https://img.shields.io/npm/v/shiki-transformer-fold?color=yellow)](https://npmjs.com/package/shiki-transformer-fold)
+[![npm downloads](https://img.shields.io/npm/dm/shiki-transformer-fold?color=yellow)](https://npm.chart.dev/shiki-transformer-fold)
+
+<!-- /automd -->
+
+Code folding support for shiki.
+
+## Usage
+
+Install the package:
+
+```sh
+# ✨ Auto-detect (supports npm, yarn, pnpm, deno and bun)
+npx nypm install shiki-transformer-fold
+```
+
+Add the transformer
+
+```ts
+import { codeToHtml } from "shiki";
+import {
+  attachFoldToggleListener,
+  transformerRenderHtmlFold,
+} from "shiki-transformer-fold";
+
+const html = await codeToHtml(code, {
+  lang: "html",
+  theme: "nord",
+  transformers: [transformerRenderHtmlFold()],
+});
+
+// attach listeners to allow opening and closing the rendered code
+// need to be called only once
+attachFoldToggleListener();
+```
+
+## Development
+
+<details>
+
+<summary>local development</summary>
+
+- Clone this repository
+- Install latest LTS version of [Node.js](https://nodejs.org/en/)
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
+- Install dependencies using `pnpm install`
+- Run interactive tests using `pnpm dev`
+
+</details>
+
+## License
+
+<!-- automd:contributors license=MIT -->
+
+Published under the [MIT](https://github.com/huang-julien/shiki-transformer-fold/blob/main/LICENSE) license.
+Made by [community](https://github.com/huang-julien/shiki-transformer-fold/graphs/contributors) 💛
+<br><br>
+<a href="https://github.com/huang-julien/shiki-transformer-fold/graphs/contributors">
+<img src="https://contrib.rocks/image?repo=huang-julien/shiki-transformer-fold" />
+</a>
+
+<!-- /automd -->
+
+<!-- automd:with-automd -->
+
+---
+
+_🤖 auto updated with [automd](https://automd.unjs.io)_
+
+<!-- /automd -->

package/dist/index.d.mts

@@ -0,0 +1,43 @@
+import { ShikiTransformer } from "shiki";
+
+//#region src/html.d.ts
+interface TransformerHtmlFoldOptions {
+  /**
+   * Custom class prefix for fold elements
+   * @default 'shiki-fold'
+   */
+  classPrefix?: string;
+}
+interface FoldRegion {
+  startLine: number;
+  endLine: number;
+}
+declare module "shiki" {
+  interface ShikiTransformerContextMeta {
+    /**
+     * Metadata added by transformerHtmlFold fromshiki-transformer-fold
+     */
+    transformerHtmlFold: {
+      /** Map of foldable regions detected in the code */
+      foldRegions: FoldRegion[];
+      /** Map of foldable regions detected in the code */
+      foldStartLines: Map<number, FoldRegion>;
+      __lineIdCounter: number;
+    };
+  }
+}
+/**
+ * Shiki transformer that adds code folding functionality for HTML-like tags.
+ */
+declare function transformerRenderHtmlFold(options?: TransformerHtmlFoldOptions): ShikiTransformer;
+/** Detect foldable regions from raw token arrays */
+//#endregion
+//#region src/listeners.d.ts
+/**
+ * Attach a delegated click listener for fold toggles.
+ * Uses event delegation so it works with dynamically rendered content.
+ * Only needs to be called once.
+ */
+declare function attachFoldToggleListener(classPrefix?: string): void;
+//#endregion
+export { attachFoldToggleListener, transformerRenderHtmlFold };

package/dist/index.mjs

@@ -0,0 +1,165 @@
+//#region src/html.ts
+/** Self-closing/void HTML tags that don't need closing tags */
+const VOID_TAGS = new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"param",
+	"source",
+	"track",
+	"wbr",
+	"path",
+	"circle",
+	"rect",
+	"line",
+	"polyline",
+	"polygon",
+	"ellipse"
+]);
+const OPEN_TAG_REGEX = /<([a-zA-Z][a-zA-Z0-9\-_:.]*)[^>]*(?<!\/)>/g;
+const CLOSE_TAG_REGEX = /<\/([a-zA-Z][a-zA-Z0-9\-_:.]*)\s*>/g;
+const SELF_CLOSING_REGEX = /<([a-zA-Z][a-zA-Z0-9\-_:.]*)[^>]*\/>/g;
+/**
+* Shiki transformer that adds code folding functionality for HTML-like tags.
+*/
+function transformerRenderHtmlFold(options = {}) {
+	const { classPrefix = "shiki-fold" } = options;
+	return {
+		name: "shiki-transformer-html-fold",
+		tokens(lines) {
+			const foldRegions = detectFoldRegions(lines);
+			const foldStartLines = new Map(foldRegions.map((r) => [r.startLine, r]));
+			this.meta.transformerHtmlFold = {
+				foldRegions,
+				foldStartLines,
+				__lineIdCounter: 0
+			};
+			return lines;
+		},
+		pre(element) {
+			element.children.unshift({
+				type: "element",
+				tagName: "style",
+				properties: {},
+				children: [{
+					type: "text",
+					value: getStyles(classPrefix)
+				}]
+			});
+		},
+		line(element, lineNumber) {
+			const { transformerHtmlFold } = this.meta;
+			const lineId = `${classPrefix}-${transformerHtmlFold.__lineIdCounter++}`;
+			element.properties["data-fold-line"] = lineId;
+			const region = transformerHtmlFold.foldStartLines.get(lineNumber);
+			if (region) {
+				const endLineId = `${classPrefix}-${region.endLine - 1}`;
+				element.properties["data-fold-end-id"] = endLineId;
+				element.properties["data-folded"] = "false";
+				element.properties.class = `${element.properties.class || ""} ${classPrefix}-foldable`.trim();
+			}
+			return element;
+		}
+	};
+}
+/** Detect foldable regions from raw token arrays */
+function detectFoldRegions(lines) {
+	const regions = [];
+	const stack = [];
+	for (const [lineIndex, lineTokens] of lines.entries()) {
+		const text = lineTokens.map((t) => t.content).join("");
+		const lineNum = lineIndex + 1;
+		const selfClosingPositions = new Set();
+		for (const match of text.matchAll(SELF_CLOSING_REGEX)) selfClosingPositions.add(match.index);
+		for (const match of text.matchAll(OPEN_TAG_REGEX)) {
+			const [_, tagName] = match;
+			if (!tagName) continue;
+			if (selfClosingPositions.has(match.index)) continue;
+			const tagNameLower = tagName.toLowerCase();
+			if (!VOID_TAGS.has(tagNameLower)) stack.push({
+				tagName: tagNameLower,
+				line: lineNum
+			});
+		}
+		for (const match of text.matchAll(CLOSE_TAG_REGEX)) {
+			const [_, tagName] = match;
+			if (!tagName) continue;
+			const tagNameLower = tagName.toLowerCase();
+			for (let i = stack.length - 1; i >= 0; i--) if (stack[i]?.tagName === tagNameLower) {
+				const startLine = stack[i].line;
+				if (lineNum > startLine) regions.push({
+					startLine,
+					endLine: lineNum
+				});
+				stack.splice(i, 1);
+				break;
+			}
+		}
+	}
+	return regions;
+}
+/** CSS styles for fold functionality */
+function getStyles(classPrefix) {
+	return `
+.shiki code { display: grid; }
+.${classPrefix}-foldable { cursor: pointer; }
+.${classPrefix}-foldable:hover { background: rgba(255, 255, 255, 0.05); }
+.${classPrefix}-hidden { display: none !important; }
+.${classPrefix}-summary {
+  display: inline;
+  opacity: 0.5;
+  font-style: italic;
+  margin-left: 0.5em;
+  user-select: none;
+  pointer-events: none;
+}`.trim();
+}
+
+//#endregion
+//#region src/listeners.ts
+/**
+* Attach a delegated click listener for fold toggles.
+* Uses event delegation so it works with dynamically rendered content.
+* Only needs to be called once.
+*/
+function attachFoldToggleListener(classPrefix = "shiki-fold") {
+	if (typeof document === "undefined") return;
+	const hiddenClass = `${classPrefix}-hidden`;
+	const summaryClass = `${classPrefix}-summary`;
+	document.addEventListener("click", (event) => {
+		const line = event.target.closest(`.${classPrefix}-foldable`);
+		if (!line) return;
+		const endId = line.dataset.foldEndId;
+		if (!endId) return;
+		const isFolded = line.dataset.folded === "true";
+		line.dataset.folded = String(!isFolded);
+		const linesToToggle = [];
+		let sibling = line.nextElementSibling;
+		while (sibling) {
+			const siblingId = sibling.dataset.foldLine;
+			linesToToggle.push(sibling);
+			if (siblingId === endId) break;
+			sibling = sibling.nextElementSibling;
+		}
+		const existingSummary = line.querySelector(`.${summaryClass}`);
+		if (isFolded) existingSummary?.remove();
+		else {
+			const count = linesToToggle.length;
+			const summary = document.createElement("span");
+			summary.className = summaryClass;
+			summary.textContent = `... ${count} line${count > 1 ? "s" : ""} hidden`;
+			line.append(summary);
+		}
+		for (const targetLine of linesToToggle) targetLine.classList.toggle(hiddenClass, !isFolded);
+	});
+}
+
+//#endregion
+export { attachFoldToggleListener, transformerRenderHtmlFold };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "shiki-transformer-fold",
+  "version": "0.1.0",
+  "description": "Shiki transformer to bring code folding support",
+  "repository": "huang-julien/shiki-transformer-fold",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/hast": "^3.0.4",
+    "@types/node": "^24.3.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "automd": "^0.4.0",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.33.0",
+    "eslint-config-unjs": "^0.5.0",
+    "hast": "^1.0.0",
+    "obuild": "^0.2.1",
+    "prettier": "^3.6.2",
+    "shiki": "^3.20.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "obuild",
+    "dev": "vite dev ./playground",
+    "lint": "eslint . && prettier -c .",
+    "lint:fix": "automd && eslint . --fix && prettier -w .",
+    "release": "pnpm test && changelogen --release && npm publish && git push --follow-tags",
+    "test": "pnpm lint && pnpm test:types && vitest run --coverage",
+    "test:types": "tsc --noEmit --skipLibCheck"
+  }
+}