Language Service: Implement @herb-tools/language-service package

README.md

@@ -56,6 +56,7 @@ The Herb ecosystem offers multiple tools that integrate seamlessly into editors,
 | [Herb Parser](https://herb-tools.dev/projects/parser) | Fast, portable, HTML-aware ERB parser written in C. |
 | [Herb Linter](https://herb-tools.dev/projects/linter) | Static analysis to enforce best practices and identify common mistakes. |
 | [Herb Formatter](https://herb-tools.dev/projects/formatter) | Automatic, consistent formatting for HTML+ERB files. *(experimental)* |
+| [Herb Language Service](https://herb-tools.dev/projects/language-service) | HTML+ERB language service with ActionView tag helper support. |
 | [Herb Language Server](https://herb-tools.dev/projects/language-server) | Rich editor integration for VS Code, Zed, Neovim, and more. |
 | [Herb Engine](https://herb-tools.dev/projects/engine) | HTML-aware ERB rendering engine, API-compatible with Erubi. |
 | [Herb Dev Tools](https://herb-tools.dev/projects/dev-tools) | In-browser dev tools for inspecting and debugging templates, shipped with ReActionView. |

javascript/packages/language-service/README.md

@@ -1,10 +1,14 @@
-# Herb Language Service <Badge type="info" text="coming soon" />
+# Herb Language Service
 
 **Package:** [`@herb-tools/language-service`](https://www.npmjs.com/package/@herb-tools/language-service)
 
 ---
 
-HTML+ERB language service built on the Herb parser, providing a compatible API with [`vscode-html-languageservice`](https://github.com/microsoft/vscode-html-languageservice) but with HTML+ERB template understanding.
+HTML+ERB language service built on the Herb parser, providing a compatible API with [`vscode-html-languageservice`](https://github.com/microsoft/vscode-html-languageservice) but with full HTML+ERB template understanding, including ActionView tag helpers.
+
+::: tip
+This package is intended for tooling developers building language servers, editor extensions, or other developer tools on top of Herb. If you're looking to use Herb in your editor, see the [Herb Language Server](/integrations/editors) instead.
+:::
 
 ## Installation
 
@@ -28,19 +32,126 @@ bun add @herb-tools/language-service
 
 ## Features
 
-- **Native HTML+ERB Support**: Built specifically for HTML+ERB templates with deep understanding of Rails ActionView helpers.
-- **Compatible API**: Drop-in replacement for [`vscode-html-languageservice`](https://github.com/microsoft/vscode-html-languageservice) with the same interface.
-- **Custom Data Providers**: Supports extensible HTML data providers for framework-specific attributes.
+- Drop-in replacement for [`vscode-html-languageservice`](https://github.com/microsoft/vscode-html-languageservice) with the same API
+- Parses HTML+ERB using the Herb parser instead of a plain HTML scanner
+- ActionView tag helpers like `<%= tag.div data: { controller: "scroll" } %>` are treated as `<div data-controller="scroll">` for completions and diagnostics
+- Extensible via `IHTMLDataProvider` for framework-specific attributes and values
+- Token list support for space-separated attributes (`class`, `data-controller`, etc.)
+- Falls back to the upstream HTML parser when Herb is not available
+
+## Migrating from `vscode-html-languageservice`
+
+```diff
+- import { getLanguageService } from "vscode-html-languageservice"
++ import { Herb } from "@herb-tools/node-wasm"
++ import { getLanguageService } from "@herb-tools/language-service"
+
++ await Herb.load()
+
+  const service = getLanguageService({
++   herb: Herb,
+    customDataProviders: [myDataProvider],
+  })
+```
+
+All types and functions from `vscode-html-languageservice` are re-exported, so no other import changes are needed.
 
 ## Usage
 
-Replace your import to get enhanced HTML+ERB support with no code changes:
+Pass a Herb instance to get HTML+ERB support:
 
-```diff
-- import { getLanguageService } from 'vscode-html-languageservice'
-+ import { getLanguageService } from '@herb-tools/language-service'
+```typescript
+import { Herb } from "@herb-tools/node-wasm"
+import { getLanguageService } from "@herb-tools/language-service"
+
+await Herb.load()
+
+const service = getLanguageService({
+  herb: Herb,
+  customDataProviders: [myDataProvider],
+})
+
+const document = service.parseHTMLDocument(textDocument)
+const completions = service.doComplete(textDocument, position, document)
+```
+
+### Without Herb (HTML-only)
+
+When no Herb instance is provided, the service falls back to the upstream `vscode-html-languageservice` parser:
+
+```typescript
+import { getLanguageService } from "@herb-tools/language-service"
+
+const service = getLanguageService({
+  customDataProviders: [myDataProvider],
+})
 ```
 
+### Custom Data Providers
+
+Custom data providers let you add framework-specific tags, attributes, and values to the completion and hover engines. The interface is the same [`IHTMLDataProvider`](https://github.com/microsoft/vscode-html-languageservice/blob/main/src/htmlLanguageTypes.ts) from `vscode-html-languageservice`:
+
+```typescript
+import { getLanguageService, type IHTMLDataProvider } from "@herb-tools/language-service"
+
+const stimulusProvider: IHTMLDataProvider = {
+  getId: () => "stimulus",
+  isApplicable: () => true,
+
+  provideTags: () => [],
+
+  provideAttributes: (tag) => [
+    { name: "data-controller" },
+    { name: "data-action" },
+  ],
+
+  provideValues: (tag, attribute) => {
+    if (attribute === "data-controller") {
+      return [{ name: "scroll" }, { name: "search" }]
+    }
+
+    return []
+  },
+}
+
+const service = getLanguageService({
+  herb: Herb,
+  customDataProviders: [stimulusProvider],
+  tokenListAttributes: ["data-controller", "data-action"],
+})
+```
+
+Multiple providers can be composed. The language service queries all applicable providers and merges their results.
+
+### Token List Attributes
+
+Some attributes contain space-separated token lists (e.g., `class="foo bar"` or `data-controller="scroll search"`). Pass `tokenListAttributes` so the language service can provide per-token completions and accurate per-token diagnostic ranges:
+
+```typescript
+const service = getLanguageService({
+  herb: Herb,
+  tokenListAttributes: ["data-controller", "data-action"],
+})
+```
+
+The defaults from `@herb-tools/core`'s `TOKEN_LIST_ATTRIBUTES` (including `class`) are always included.
+
 ## API Compatibility
 
-This package provides the same API as [`vscode-html-languageservice`](https://github.com/microsoft/vscode-html-languageservice).
+This package provides the same `LanguageService` interface as [`vscode-html-languageservice`](https://github.com/microsoft/vscode-html-languageservice):
+
+- `parseHTMLDocument(document)`
+- `doComplete(document, position, htmlDocument)`
+- `doHover(document, position, htmlDocument)`
+- `format(document, range, options)`
+- `findDocumentHighlights(document, position, htmlDocument)`
+- `findDocumentLinks(document, documentContext)`
+- `findDocumentSymbols(document, htmlDocument)`
+- `getFoldingRanges(document, context)`
+- `getSelectionRanges(document, positions)`
+- `doRename(document, position, newName, htmlDocument)`
+- `findMatchingTagPosition(document, position, htmlDocument)`
+- `findLinkedEditingRanges(document, position, htmlDocument)`
+- `createScanner(input, initialOffset)`
+- `setDataProviders(useDefault, providers)`
+- `setCompletionParticipants(participants)`

javascript/packages/language-service/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@herb-tools/language-service",
+  "version": "0.9.2",
+  "description": "HTML+ERB language service built on the Herb parser, providing a compatible API with vscode-html-languageservice",
+  "license": "MIT",
+  "homepage": "https://herb-tools.dev",
+  "bugs": "https://github.com/marcoroth/herb/issues/new?title=Package%20%60@herb-tools/language-service%60:%20",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marcoroth/herb.git",
+    "directory": "javascript/packages/language-service"
+  },
+  "main": "./dist/herb-language-service.cjs",
+  "module": "./dist/herb-language-service.esm.js",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "build": "yarn clean && rollup -c",
+    "dev": "rollup -c -w",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "prepublishOnly": "yarn clean && yarn build && yarn test"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/herb-language-service.esm.js",
+      "require": "./dist/herb-language-service.cjs",
+      "default": "./dist/herb-language-service.esm.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "vscode-html-languageservice": "^5.1.0",
+    "vscode-languageserver-textdocument": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@herb-tools/core": "0.9.2",
+    "vscode-html-languageservice": "^5.1.0",
+    "vscode-languageserver-textdocument": "^1.0.0"
+  },
+  "files": [
+    "package.json",
+    "README.md",
+    "dist/",
+    "src/"
+  ]
+}

javascript/packages/language-service/project.json

@@ -0,0 +1,28 @@
+{
+  "name": "@herb-tools/language-service",
+  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "javascript/packages/language-service/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "build"
+      },
+      "dependsOn": ["@herb-tools/core:build"]
+    },
+    "test": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "test"
+      }
+    },
+    "clean": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "clean"
+      }
+    }
+  },
+  "tags": []
+}

javascript/packages/language-service/rollup.config.mjs

@@ -0,0 +1,48 @@
+import typescript from "@rollup/plugin-typescript"
+import { nodeResolve } from "@rollup/plugin-node-resolve"
+
+const external = [
+  "@herb-tools/core",
+  "@herb-tools/node-wasm",
+  "@herb-tools/browser",
+  "vscode-html-languageservice",
+  "vscode-languageserver-textdocument",
+]
+
+export default [
+  {
+    input: "src/index.ts",
+    output: {
+      file: "dist/herb-language-service.esm.js",
+      format: "esm",
+      sourcemap: true,
+    },
+    external,
+    plugins: [
+      nodeResolve(),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        declaration: true,
+        declarationDir: "./dist/types",
+        rootDir: "src/",
+      }),
+    ],
+  },
+
+  {
+    input: "src/index.ts",
+    output: {
+      file: "dist/herb-language-service.cjs",
+      format: "cjs",
+      sourcemap: true,
+    },
+    external,
+    plugins: [
+      nodeResolve(),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        rootDir: "src/",
+      }),
+    ],
+  },
+]