@xsynaptic/rehype-wrap-cjk 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Synaptic
+
+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,96 @@
+# @xsynaptic/rehype-wrap-cjk
+
+This package is a [unified][]/[rehype][] plugin that wraps [CJK character][cjk-wiki] sequences in an element (defaulting to `span`) with a configurable attribute and value, useful for applying different CSS styling rules in multilingual contexts.
+
+By default it emits `<span class="cjk">...</span>` as a pure styling hook. To emit semantic `lang` tags instead, pass `attribute: 'lang'` together with a `value` such as `'zh'`, `'ja'`, or `'ko'`. Custom attribute names (e.g. `data-lang`) are also supported.
+
+_Note_: this package is ESM-only. It was formerly published unscoped as `rehype-wrap-cjk`; the default export has been removed in favor of the named `rehypeWrapCjk` export.
+
+## Install
+
+```sh
+npm install @xsynaptic/rehype-wrap-cjk
+```
+
+## Use
+
+A typical pipeline transforming Markdown into HTML with [remark][] and [rehype][]:
+
+```ts
+import rehypeSanitize from 'rehype-sanitize';
+import rehypeStringify from 'rehype-stringify';
+import { rehypeWrapCjk } from '@xsynaptic/rehype-wrap-cjk';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import { unified } from 'unified';
+
+export function processMarkdown(markdownContent: string): string {
+	const htmlOutput = unified()
+		.use(remarkParse)
+		.use(remarkRehype)
+		.use(rehypeWrapCjk)
+		.use(rehypeSanitize)
+		.use(rehypeStringify)
+		.processSync(markdownContent);
+
+	return String(htmlOutput);
+}
+```
+
+Example plain text input:
+
+```text
+Sample text with CJK characters (中日韓字符) interspersed. 中文 can appear anywhere in the text and will be appropriately wrapped.
+```
+
+Example HTML output (default `class="cjk"` styling hook):
+
+```html
+Sample text with CJK characters (<span class="cjk">中日韓字符</span>) interspersed.
+<span class="cjk">中文</span> can appear anywhere in the text and will be appropriately wrapped.
+```
+
+Example CSS rules (for you to implement in your own projects):
+
+```css
+.cjk {
+	font-style: normal !important;
+	text-decoration: none !important;
+	word-break: keep-all !important;
+}
+```
+
+## Options
+
+Pass options as the second argument to `.use(rehypeWrapCjk, { ... })`.
+
+- `element` (default `'span'`): wrapper element name.
+- `attribute` (default `'class'`): attribute written to the wrapper. Use `'lang'` for semantic language tagging, `'class'` for a styling hook, or any other attribute name (e.g. `'data-lang'`).
+- `value` (default `'cjk'`): value written to `attribute`. Also selects a preset regex when set to `'zh'`, `'ja'`, `'ko'`, or `'cjk'`.
+- `regex` (default derived from `value`): custom pattern. The `g` flag is added if missing.
+- `skipTags` (default `['code', 'pre', 'kbd', 'samp', 'script', 'style']`): elements whose descendants are left alone. Pass `[]` to disable.
+
+Text inside any ancestor that already carries the target `attribute`/`value` is not re-wrapped.
+
+## Reference
+
+- [CJK Unified Ideographs][cjk-unified-ideographs]
+- [CJK Ideographs in Unicode][cjk-ideographs-in-unicode]
+- [Halfwidth and Fullwidth Forms][halfwidth-and-fullwidth-forms]
+- [HTMLElement lang property][html-element-lang-property]
+- [word-break CSS property][wordbreak-css-property]
+
+## License
+
+[MIT][mit-license]
+
+[cjk-wiki]: https://en.wikipedia.org/wiki/CJK_characters
+[cjk-unified-ideographs]: https://en.wikipedia.org/wiki/CJK_Unified_Ideographs
+[cjk-ideographs-in-unicode]: https://en.wikipedia.org/wiki/Template:CJK_ideographs_in_Unicode
+[halfwidth-and-fullwidth-forms]: https://en.wikipedia.org/wiki/Halfwidth_and_Fullwidth_Forms_(Unicode_block)
+[html-element-lang-property]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/lang
+[mit-license]: https://opensource.org/licenses/MIT
+[rehype]: https://github.com/rehypejs/rehype
+[remark]: https://github.com/remarkjs/remark
+[unified]: https://github.com/unifiedjs/unified
+[wordbreak-css-property]: https://developer.mozilla.org/en-US/docs/Web/CSS/word-break

package/dist/index.d.mts

@@ -0,0 +1,34 @@
+import { Root } from "hast";
+import { Plugin } from "unified";
+
+//#region src/index.d.ts
+interface RehypeWrapCjkOptions {
+  element?: string;
+  attribute?: string;
+  value?: string;
+  regex?: RegExp;
+  skipTags?: Array<string>;
+}
+/**
+ * Script-based ranges using Unicode Script Extensions property
+ * Authoritative and auto-updates with the JS engine's Unicode version
+ */
+declare const zhScriptRange: string;
+declare const jaScriptRange: string;
+declare const koScriptRange: string;
+declare const cjkScriptRange: string;
+/**
+ * Full-width ASCII variants (FF01-FF5E): digits,letters, punctuation
+ * Not covered by script extensions but sometimes used in CJK contexts
+ */
+declare const fullwidthAsciiRange: string;
+declare const cjkRegexPresets: {
+  zh: RegExp;
+  ja: RegExp;
+  ko: RegExp;
+  cjk: RegExp;
+};
+declare const rehypeWrapCjk: Plugin<[RehypeWrapCjkOptions?], Root>;
+//#endregion
+export { RehypeWrapCjkOptions, cjkRegexPresets, cjkScriptRange, fullwidthAsciiRange, jaScriptRange, koScriptRange, rehypeWrapCjk, zhScriptRange };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,83 @@
+import { h } from "hastscript";
+import { visitParents } from "unist-util-visit-parents";
+//#region src/index.ts
+const defaultSkipTags = [
+	"code",
+	"pre",
+	"kbd",
+	"samp",
+	"script",
+	"style"
+];
+function isAncestorWrapped(ancestor, attribute, value) {
+	if (attribute === "class" || attribute === "className") {
+		const classes = ancestor.properties.className;
+		if (Array.isArray(classes)) return classes.includes(value);
+		if (typeof classes === "string") return classes.split(/\s+/).includes(value);
+		return false;
+	}
+	return ancestor.properties[attribute] === value;
+}
+/**
+* Script-based ranges using Unicode Script Extensions property
+* Authoritative and auto-updates with the JS engine's Unicode version
+*/
+const zhScriptRange = String.raw`\p{scx=Han}\p{scx=Bopomofo}`;
+const jaScriptRange = String.raw`\p{scx=Hiragana}\p{scx=Katakana}\p{scx=Han}`;
+const koScriptRange = String.raw`\p{scx=Hangul}\p{scx=Han}`;
+const cjkScriptRange = String.raw`\p{scx=Han}\p{scx=Hiragana}\p{scx=Katakana}\p{scx=Hangul}\p{scx=Bopomofo}`;
+/**
+* Full-width ASCII variants (FF01-FF5E): digits,letters, punctuation
+* Not covered by script extensions but sometimes used in CJK contexts
+*/
+const fullwidthAsciiRange = String.raw`\uFF01-\uFF5E`;
+const cjkRegexPresets = {
+	zh: new RegExp(`[${zhScriptRange}${fullwidthAsciiRange}]+`, "gu"),
+	ja: new RegExp(`[${jaScriptRange}${fullwidthAsciiRange}]+`, "gu"),
+	ko: new RegExp(`[${koScriptRange}${fullwidthAsciiRange}]+`, "gu"),
+	cjk: new RegExp(`[${cjkScriptRange}${fullwidthAsciiRange}]+`, "gu")
+};
+const rehypeWrapCjk = (options) => {
+	const settings = {
+		element: options?.element ?? "span",
+		attribute: options?.attribute ?? "class",
+		value: options?.value ?? "cjk",
+		regex: options?.regex,
+		skipTags: options?.skipTags ?? defaultSkipTags
+	};
+	const baseRegex = settings.regex ?? (settings.value in cjkRegexPresets ? cjkRegexPresets[settings.value] : cjkRegexPresets.cjk);
+	const flags = baseRegex.flags.includes("g") ? baseRegex.flags : baseRegex.flags + "g";
+	const regex = new RegExp(baseRegex.source, flags);
+	function transformer(tree) {
+		visitParents(tree, "text", function visitor(node, ancestors) {
+			const parent = ancestors.at(-1);
+			if (!parent || !("children" in parent) || typeof node.value !== "string") return;
+			if (ancestors.some((ancestor) => ancestor.type === "element" && settings.skipTags.includes(ancestor.tagName))) return;
+			if (ancestors.some((ancestor) => ancestor.type === "element" && isAncestorWrapped(ancestor, settings.attribute, settings.value))) return;
+			const index = parent.children.indexOf(node);
+			if (index === -1) return;
+			const parts = [];
+			let lastIndex = 0;
+			for (const match of node.value.matchAll(regex)) {
+				const matchIndex = match.index;
+				if (matchIndex > lastIndex) parts.push({
+					type: "text",
+					value: node.value.slice(lastIndex, matchIndex)
+				});
+				parts.push(h(settings.element, { [settings.attribute]: settings.value }, [match[0]]));
+				lastIndex = matchIndex + match[0].length;
+			}
+			if (lastIndex < node.value.length) parts.push({
+				type: "text",
+				value: node.value.slice(lastIndex)
+			});
+			parent.children.splice(index, 1, ...parts);
+		});
+		return tree;
+	}
+	return transformer;
+};
+//#endregion
+export { cjkRegexPresets, cjkScriptRange, fullwidthAsciiRange, jaScriptRange, koScriptRange, rehypeWrapCjk, zhScriptRange };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Element, Root, Text } from 'hast';\nimport type { Plugin, Transformer } from 'unified';\n\nimport { h } from 'hastscript';\nimport { visitParents } from 'unist-util-visit-parents';\n\nexport interface RehypeWrapCjkOptions {\n\telement?: string;\n\tattribute?: string;\n\tvalue?: string;\n\tregex?: RegExp;\n\tskipTags?: Array<string>;\n}\n\nconst defaultSkipTags = ['code', 'pre', 'kbd', 'samp', 'script', 'style'];\n\nfunction isAncestorWrapped(ancestor: Element, attribute: string, value: string): boolean {\n\tif (attribute === 'class' || attribute === 'className') {\n\t\tconst classes = ancestor.properties.className;\n\n\t\tif (Array.isArray(classes)) return classes.includes(value);\n\n\t\tif (typeof classes === 'string') return classes.split(/\\s+/).includes(value);\n\n\t\treturn false;\n\t}\n\treturn ancestor.properties[attribute] === value;\n}\n\n/**\n * Script-based ranges using Unicode Script Extensions property\n * Authoritative and auto-updates with the JS engine's Unicode version\n */\nexport const zhScriptRange = String.raw`\\p{scx=Han}\\p{scx=Bopomofo}`;\nexport const jaScriptRange = String.raw`\\p{scx=Hiragana}\\p{scx=Katakana}\\p{scx=Han}`;\nexport const koScriptRange = String.raw`\\p{scx=Hangul}\\p{scx=Han}`;\nexport const cjkScriptRange = String.raw`\\p{scx=Han}\\p{scx=Hiragana}\\p{scx=Katakana}\\p{scx=Hangul}\\p{scx=Bopomofo}`;\n\n/**\n * Full-width ASCII variants (FF01-FF5E): digits,letters, punctuation\n * Not covered by script extensions but sometimes used in CJK contexts\n */\nexport const fullwidthAsciiRange = String.raw`\\uFF01-\\uFF5E`;\n\nexport const cjkRegexPresets = {\n\tzh: new RegExp(`[${zhScriptRange}${fullwidthAsciiRange}]+`, 'gu'),\n\tja: new RegExp(`[${jaScriptRange}${fullwidthAsciiRange}]+`, 'gu'),\n\tko: new RegExp(`[${koScriptRange}${fullwidthAsciiRange}]+`, 'gu'),\n\tcjk: new RegExp(`[${cjkScriptRange}${fullwidthAsciiRange}]+`, 'gu'),\n};\n\nexport const rehypeWrapCjk: Plugin<[RehypeWrapCjkOptions?], Root> = (options) => {\n\tconst settings = {\n\t\telement: options?.element ?? 'span',\n\t\tattribute: options?.attribute ?? 'class',\n\t\tvalue: options?.value ?? 'cjk',\n\t\tregex: options?.regex,\n\t\tskipTags: options?.skipTags ?? defaultSkipTags,\n\t};\n\n\tconst baseRegex =\n\t\tsettings.regex ??\n\t\t(settings.value in cjkRegexPresets\n\t\t\t? cjkRegexPresets[settings.value as keyof typeof cjkRegexPresets]\n\t\t\t: cjkRegexPresets.cjk);\n\n\t// always clone so a caller-supplied global regex never carries its lastIndex into matchAll\n\tconst flags = baseRegex.flags.includes('g') ? baseRegex.flags : baseRegex.flags + 'g';\n\tconst regex = new RegExp(baseRegex.source, flags);\n\n\tfunction transformer(tree: Root) {\n\t\tvisitParents(tree, 'text', function visitor(node, ancestors) {\n\t\t\tconst parent = ancestors.at(-1);\n\t\t\tif (!parent || !('children' in parent) || typeof node.value !== 'string') return;\n\n\t\t\t// Skip text inside excluded tags (code, pre, script, etc.)\n\t\t\tif (\n\t\t\t\tancestors.some(\n\t\t\t\t\t(ancestor) => ancestor.type === 'element' && settings.skipTags.includes(ancestor.tagName),\n\t\t\t\t)\n\t\t\t)\n\t\t\t\treturn;\n\n\t\t\t// Skip if any ancestor is already wrapped\n\t\t\tif (\n\t\t\t\tancestors.some(\n\t\t\t\t\t(ancestor) =>\n\t\t\t\t\t\tancestor.type === 'element' &&\n\t\t\t\t\t\tisAncestorWrapped(ancestor, settings.attribute, settings.value),\n\t\t\t\t)\n\t\t\t)\n\t\t\t\treturn;\n\n\t\t\tconst index = parent.children.indexOf(node);\n\t\t\tif (index === -1) return;\n\n\t\t\tconst parts: Array<Element | Text> = [];\n\t\t\tlet lastIndex = 0;\n\n\t\t\tfor (const match of node.value.matchAll(regex)) {\n\t\t\t\tconst matchIndex = match.index;\n\n\t\t\t\tif (matchIndex > lastIndex) {\n\t\t\t\t\tparts.push({\n\t\t\t\t\t\ttype: 'text',\n\t\t\t\t\t\tvalue: node.value.slice(lastIndex, matchIndex),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tparts.push(h(settings.element, { [settings.attribute]: settings.value }, [match[0]]));\n\t\t\t\tlastIndex = matchIndex + match[0].length;\n\t\t\t}\n\n\t\t\tif (lastIndex < node.value.length) {\n\t\t\t\tparts.push({ type: 'text', value: node.value.slice(lastIndex) });\n\t\t\t}\n\n\t\t\tparent.children.splice(index, 1, ...parts);\n\t\t});\n\n\t\treturn tree;\n\t}\n\n\treturn transformer satisfies Transformer<Root>;\n};\n"],"mappings":";;;AAcA,MAAM,kBAAkB;CAAC;CAAQ;CAAO;CAAO;CAAQ;CAAU;AAAO;AAExE,SAAS,kBAAkB,UAAmB,WAAmB,OAAwB;CACxF,IAAI,cAAc,WAAW,cAAc,aAAa;EACvD,MAAM,UAAU,SAAS,WAAW;EAEpC,IAAI,MAAM,QAAQ,OAAO,GAAG,OAAO,QAAQ,SAAS,KAAK;EAEzD,IAAI,OAAO,YAAY,UAAU,OAAO,QAAQ,MAAM,KAAK,CAAC,CAAC,SAAS,KAAK;EAE3E,OAAO;CACR;CACA,OAAO,SAAS,WAAW,eAAe;AAC3C;;;;;AAMA,MAAa,gBAAgB,OAAO,GAAG;AACvC,MAAa,gBAAgB,OAAO,GAAG;AACvC,MAAa,gBAAgB,OAAO,GAAG;AACvC,MAAa,iBAAiB,OAAO,GAAG;;;;;AAMxC,MAAa,sBAAsB,OAAO,GAAG;AAE7C,MAAa,kBAAkB;CAC9B,IAAI,IAAI,OAAO,IAAI,gBAAgB,oBAAoB,KAAK,IAAI;CAChE,IAAI,IAAI,OAAO,IAAI,gBAAgB,oBAAoB,KAAK,IAAI;CAChE,IAAI,IAAI,OAAO,IAAI,gBAAgB,oBAAoB,KAAK,IAAI;CAChE,KAAK,IAAI,OAAO,IAAI,iBAAiB,oBAAoB,KAAK,IAAI;AACnE;AAEA,MAAa,iBAAwD,YAAY;CAChF,MAAM,WAAW;EAChB,SAAS,SAAS,WAAW;EAC7B,WAAW,SAAS,aAAa;EACjC,OAAO,SAAS,SAAS;EACzB,OAAO,SAAS;EAChB,UAAU,SAAS,YAAY;CAChC;CAEA,MAAM,YACL,SAAS,UACR,SAAS,SAAS,kBAChB,gBAAgB,SAAS,SACzB,gBAAgB;CAGpB,MAAM,QAAQ,UAAU,MAAM,SAAS,GAAG,IAAI,UAAU,QAAQ,UAAU,QAAQ;CAClF,MAAM,QAAQ,IAAI,OAAO,UAAU,QAAQ,KAAK;CAEhD,SAAS,YAAY,MAAY;EAChC,aAAa,MAAM,QAAQ,SAAS,QAAQ,MAAM,WAAW;GAC5D,MAAM,SAAS,UAAU,GAAG,EAAE;GAC9B,IAAI,CAAC,UAAU,EAAE,cAAc,WAAW,OAAO,KAAK,UAAU,UAAU;GAG1E,IACC,UAAU,MACR,aAAa,SAAS,SAAS,aAAa,SAAS,SAAS,SAAS,SAAS,OAAO,CACzF,GAEA;GAGD,IACC,UAAU,MACR,aACA,SAAS,SAAS,aAClB,kBAAkB,UAAU,SAAS,WAAW,SAAS,KAAK,CAChE,GAEA;GAED,MAAM,QAAQ,OAAO,SAAS,QAAQ,IAAI;GAC1C,IAAI,UAAU,IAAI;GAElB,MAAM,QAA+B,CAAC;GACtC,IAAI,YAAY;GAEhB,KAAK,MAAM,SAAS,KAAK,MAAM,SAAS,KAAK,GAAG;IAC/C,MAAM,aAAa,MAAM;IAEzB,IAAI,aAAa,WAChB,MAAM,KAAK;KACV,MAAM;KACN,OAAO,KAAK,MAAM,MAAM,WAAW,UAAU;IAC9C,CAAC;IAEF,MAAM,KAAK,EAAE,SAAS,SAAS,GAAG,SAAS,YAAY,SAAS,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACpF,YAAY,aAAa,MAAM,EAAE,CAAC;GACnC;GAEA,IAAI,YAAY,KAAK,MAAM,QAC1B,MAAM,KAAK;IAAE,MAAM;IAAQ,OAAO,KAAK,MAAM,MAAM,SAAS;GAAE,CAAC;GAGhE,OAAO,SAAS,OAAO,OAAO,GAAG,GAAG,KAAK;EAC1C,CAAC;EAED,OAAO;CACR;CAEA,OAAO;AACR"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@xsynaptic/rehype-wrap-cjk",
+  "version": "3.0.0",
+  "description": "Rehype plugin for wrapping CJK character sequences in an HTML element with a configurable attribute for styling or language tagging.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alexander Synaptic <x@synapticism.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xsynaptic/astro-lab.git",
+    "directory": "packages/rehype-wrap-cjk"
+  },
+  "homepage": "https://github.com/xsynaptic/astro-lab/tree/main/packages/rehype-wrap-cjk#readme",
+  "bugs": {
+    "url": "https://github.com/xsynaptic/astro-lab/issues"
+  },
+  "keywords": [
+    "unified",
+    "rehype",
+    "rehype-plugin",
+    "cjk"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@types/hast": "^3.0.4",
+    "hastscript": "^9.0.1",
+    "unist-util-visit-parents": "^6.0.2"
+  },
+  "peerDependencies": {
+    "unified": "^11.0.0"
+  },
+  "devDependencies": {
+    "rehype-parse": "^9.0.1",
+    "rehype-stringify": "^10.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit"
+  }
+}