@cssdoc/codemirror 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+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,42 @@
+# @cssdoc/codemirror
+
+A [CodeMirror 6](https://codemirror.net) extension that highlights cssdoc doc-comment tags inside CSS
+comments — the way TSDoc highlights JSDoc tags. It's the CodeMirror counterpart to
+[`@cssdoc/tmlanguage`](../tmlanguage) (the TextMate/Shiki grammar), sharing the same tag vocabulary.
+
+Matches are found by walking the CSS syntax tree and scanning **comment nodes only**, so real CSS
+at-rules like `@property`, `@scope`, and `@media` are never touched.
+
+## Install
+
+```sh
+npm add @cssdoc/codemirror @codemirror/lang-css
+```
+
+## Use
+
+```ts
+import { cssdocHighlight } from "@cssdoc/codemirror";
+import { css } from "@codemirror/lang-css";
+import { EditorView, basicSetup } from "codemirror";
+
+new EditorView({
+  extensions: [basicSetup, css(), cssdocHighlight()],
+  parent: document.body,
+});
+```
+
+Colours ship as a base theme that follows the editor's light/dark theme, so it works out of the box.
+Override any token by styling its class: `.cm-cssdoc-tag`, `.cm-cssdoc-modifier`, `.cm-cssdoc-part`,
+`.cm-cssdoc-property`, `.cm-cssdoc-link`, `.cm-cssdoc-punct`.
+
+## What it highlights
+
+| Token                 | Example                                      | Class                |
+| --------------------- | -------------------------------------------- | -------------------- |
+| Block and inline tags | `@component`, `@modifier`, `@a11y`, `@link`  | `cm-cssdoc-tag`      |
+| Modifier name         | `-orientation-vertical` after `@modifier`    | `cm-cssdoc-modifier` |
+| Part and slot names   | `.list` after `@part`, `label` after `@slot` | `cm-cssdoc-part`     |
+| Custom properties     | `--tabs-gap`                                 | `cm-cssdoc-property` |
+| Inline link text      | the target inside `{@link …}`                | `cm-cssdoc-link`     |
+| Braces                | `{` and `}` around an inline tag             | `cm-cssdoc-punct`    |

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+import { Extension } from "@codemirror/state";
+
+//#region src/index.d.ts
+/** Semantic token kind a doc-comment span maps to. Each becomes a `cm-cssdoc-<kind>` class. */
+type CssdocTokenType = "tag" | "modifier" | "part" | "property" | "link" | "punct";
+/** A highlighted span within a comment. `from`/`to` are offsets into the scanned comment text. */
+interface CssdocToken {
+  from: number;
+  to: number;
+  type: CssdocTokenType;
+}
+/** Tokenize one CSS comment's text into cssdoc doc-tag spans (offsets are relative to `text`). */
+declare const tokenizeComment: (text: string) => CssdocToken[];
+/** The cssdoc doc-comment highlighter. Add alongside a CSS language: `[css(), cssdocHighlight()]`. */
+declare const cssdocHighlight: () => Extension;
+//#endregion
+export { CssdocToken, CssdocTokenType, cssdocHighlight, cssdocHighlight as default, tokenizeComment };

package/dist/index.mjs

@@ -0,0 +1,153 @@
+import { syntaxTree } from "@codemirror/language";
+import { RangeSetBuilder } from "@codemirror/state";
+import { CSSDOC_TAGS, cssdocTagNamesByArgument, cssdocTagNamesByKind } from "@cssdoc/spec";
+import { Decoration, EditorView, ViewPlugin } from "@codemirror/view";
+//#region src/index.ts
+/**
+* `@cssdoc/codemirror` — a CodeMirror 6 extension that highlights cssdoc doc-comment tags inside CSS
+* comments, the way TSDoc highlights JSDoc tags inside `/** … *\/` comments. It's the CodeMirror
+* counterpart to the TextMate grammar in `@cssdoc/tmlanguage`, sharing the same tag vocabulary:
+* `@component`, `@modifier`, `@part`/`@slot`, `@cssproperty`, `{@link …}`, and custom properties.
+*
+* Matches are found by walking the CSS syntax tree and scanning **comment nodes only**, so real CSS
+* at-rules like `@property`, `@scope`, and `@media` are never touched. Colours ship as a base theme
+* that adapts to the editor's light/dark theme, so it works out of the box and can be overridden.
+*
+* @example
+* ```ts
+* import { cssdocHighlight } from "@cssdoc/codemirror";
+* import { css } from "@codemirror/lang-css";
+* new EditorView({ extensions: [css(), cssdocHighlight()], parent });
+* ```
+*
+* @module @cssdoc/codemirror
+*/
+const alt = (names) => names.join("|");
+const INLINE_TAGS = cssdocTagNamesByKind("inline");
+const MODIFIER_TAGS = cssdocTagNamesByArgument("modifier-name");
+const PART_TAGS = cssdocTagNamesByArgument("part-name");
+const PROPERTY_TAGS = cssdocTagNamesByArgument("custom-property");
+const PLAIN_TAGS = CSSDOC_TAGS.filter((t) => t.kind !== "inline" && !t.argument).map((t) => t.name);
+const TOKEN = new RegExp([
+	`(?<ibrace>\\{)(?<itag>@(?:${alt(INLINE_TAGS)}))\\b[ \\t]*(?<itext>[^}]*)(?<iend>\\})?`,
+	`(?<mtag>@(?:${alt(MODIFIER_TAGS)}))\\b[ \\t]*(?<mname>-[A-Za-z][A-Za-z0-9-]*)?`,
+	`(?<ptag>@(?:${alt(PART_TAGS)}))\\b[ \\t]*(?<pname>\\.?[A-Za-z][A-Za-z0-9_-]*)?`,
+	`(?<rtag>@(?:${alt(PROPERTY_TAGS)}))\\b[ \\t]*(?<rname>--[A-Za-z][A-Za-z0-9-]*)?`,
+	`(?<btag>@(?:${alt(PLAIN_TAGS)}))\\b`,
+	"(?<cprop>(?<![\\w-])--[A-Za-z][A-Za-z0-9-]*)"
+].join("|"), "gd");
+const GROUP_TYPE = {
+	ibrace: "punct",
+	itag: "tag",
+	itext: "link",
+	iend: "punct",
+	mtag: "tag",
+	mname: "modifier",
+	ptag: "tag",
+	pname: "part",
+	rtag: "tag",
+	rname: "property",
+	btag: "tag",
+	cprop: "property"
+};
+const STRUCTURE_TAG = /@structure\b/gu;
+const STRUCTURE_TOKEN = /\.[A-Za-z][\w-]*|[{}]/gu;
+/** Tokenize one CSS comment's text into cssdoc doc-tag spans (offsets are relative to `text`). */
+const tokenizeComment = (text) => {
+	const out = [];
+	for (const m of text.matchAll(TOKEN)) {
+		const groups = m.indices?.groups;
+		if (!groups) continue;
+		for (const key of Object.keys(groups)) {
+			const gi = groups[key];
+			if (gi && gi[0] !== gi[1]) out.push({
+				from: gi[0],
+				to: gi[1],
+				type: GROUP_TYPE[key]
+			});
+		}
+	}
+	for (const m of text.matchAll(STRUCTURE_TAG)) {
+		const start = (m.index ?? 0) + m[0].length;
+		const after = text.slice(start).search(/@[A-Za-z]/u);
+		const end = after === -1 ? text.length : start + after;
+		for (const s of text.slice(start, end).matchAll(STRUCTURE_TOKEN)) {
+			const from = start + (s.index ?? 0);
+			out.push({
+				from,
+				to: from + s[0].length,
+				type: s[0][0] === "." ? "part" : "punct"
+			});
+		}
+	}
+	return out;
+};
+const marks = /* @__PURE__ */ new Map();
+const markFor = (type) => {
+	let mark = marks.get(type);
+	if (!mark) {
+		mark = Decoration.mark({ class: `cm-cssdoc-${type}` });
+		marks.set(type, mark);
+	}
+	return mark;
+};
+const build = (view) => {
+	const found = [];
+	const tree = syntaxTree(view.state);
+	for (const range of view.visibleRanges) tree.iterate({
+		from: range.from,
+		to: range.to,
+		enter(node) {
+			if (node.name !== "Comment") return;
+			const text = view.state.doc.sliceString(node.from, node.to);
+			for (const t of tokenizeComment(text)) found.push({
+				from: node.from + t.from,
+				to: node.from + t.to,
+				type: t.type
+			});
+		}
+	});
+	found.sort((a, b) => a.from - b.from || a.to - b.to);
+	const builder = new RangeSetBuilder();
+	for (const t of found) builder.add(t.from, t.to, markFor(t.type));
+	return builder.finish();
+};
+const baseTheme = EditorView.baseTheme({
+	"&light .cm-cssdoc-tag": {
+		color: "#8250df",
+		fontWeight: "600"
+	},
+	"&dark .cm-cssdoc-tag": {
+		color: "#d2a8ff",
+		fontWeight: "600"
+	},
+	"&light .cm-cssdoc-modifier": { color: "#0550ae" },
+	"&dark .cm-cssdoc-modifier": { color: "#79c0ff" },
+	"&light .cm-cssdoc-part": { color: "#116329" },
+	"&dark .cm-cssdoc-part": { color: "#7ee787" },
+	"&light .cm-cssdoc-property": { color: "#953800" },
+	"&dark .cm-cssdoc-property": { color: "#ffa657" },
+	"&light .cm-cssdoc-link": {
+		color: "#0969da",
+		textDecoration: "underline"
+	},
+	"&dark .cm-cssdoc-link": {
+		color: "#a5d6ff",
+		textDecoration: "underline"
+	},
+	"&light .cm-cssdoc-punct": { color: "#6e7781" },
+	"&dark .cm-cssdoc-punct": { color: "#8b949e" }
+});
+const plugin = ViewPlugin.fromClass(class {
+	decorations;
+	constructor(view) {
+		this.decorations = build(view);
+	}
+	update(u) {
+		if (u.docChanged || u.viewportChanged) this.decorations = build(u.view);
+	}
+}, { decorations: (v) => v.decorations });
+/** The cssdoc doc-comment highlighter. Add alongside a CSS language: `[css(), cssdocHighlight()]`. */
+const cssdocHighlight = () => [plugin, baseTheme];
+//#endregion
+export { cssdocHighlight, cssdocHighlight as default, tokenizeComment };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@cssdoc/codemirror",
+  "version": "0.2.0",
+  "description": "A CodeMirror 6 extension that highlights cssdoc doc-comment tags inside CSS comments, the way TSDoc highlights JSDoc tags.",
+  "keywords": [
+    "codemirror",
+    "codemirror6",
+    "css",
+    "cssdoc",
+    "editor",
+    "syntax-highlighting"
+  ],
+  "homepage": "https://cssdoc.dev",
+  "bugs": "https://github.com/thedannywahl/cssdoc/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedannywahl/cssdoc.git",
+    "directory": "syntaxes/cssdoc/codemirror"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.5.2",
+    "@codemirror/view": "^6.43.6",
+    "@cssdoc/spec": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@vitest/coverage-v8": "4.1.9",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "publint": "publint"
+  }
+}