@markuplint/alpine-parser 4.6.22 → 5.0.0-alpha.0

package/CHANGELOG.md

@@ -3,13 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.6.22](https://github.com/markuplint/markuplint/compare/@markuplint/alpine-parser@4.6.21...@markuplint/alpine-parser@4.6.22) (2025-11-05)
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
 
-**Note:** Version bump only for package @markuplint/alpine-parser
+### Features
+
+- **alpine-parser:** support loop blocks ([d92c53c](https://github.com/markuplint/markuplint/commit/d92c53ce7337a2b39f78cbc43edbe1aba2232bae))
+- delete htmx-parser, simplify alpine-parser, add migration guide and tests ([f8dbb09](https://github.com/markuplint/markuplint/commit/f8dbb090707d8cfbf3d859a9b868b2087064f89b))
 
+## [4.6.23](https://github.com/markuplint/markuplint/compare/@markuplint/alpine-parser@4.6.22...@markuplint/alpine-parser@4.6.23) (2026-02-10)
 
+**Note:** Version bump only for package @markuplint/alpine-parser
 
+## [4.6.22](https://github.com/markuplint/markuplint/compare/@markuplint/alpine-parser@4.6.21...@markuplint/alpine-parser@4.6.22) (2025-11-05)
 
+**Note:** Version bump only for package @markuplint/alpine-parser
 
 ## [4.6.21](https://github.com/markuplint/markuplint/compare/@markuplint/alpine-parser@4.6.20...@markuplint/alpine-parser@4.6.21) (2025-08-24)
 

package/README.md

@@ -14,7 +14,7 @@ $ yarn add -D @markuplint/alpine-parser
 
 ## Usage
 
-Add `parser` and `spec` option to your [configuration](https://markuplint.dev/configuration/#properties/parser).
+Add `parser` and `specs` option to your [configuration](https://markuplint.dev/configuration/#properties/parser).
 
 ```json
 {
@@ -22,7 +22,7 @@ Add `parser` and `spec` option to your [configuration](https://markuplint.dev/co
     "\\.html$": "@markuplint/alpine-parser"
   },
   "specs": {
-    "\\.html$": "@markuplint/alpine-parser/spec"
+    "\\.html$": "@markuplint/alpine-spec"
   }
 }
 ```

package/lib/index.d.ts

@@ -1 +1,7 @@
+/**
+ * @module @markuplint/alpine-parser
+ * Markuplint parser plugin for Alpine.js templates. Extends the standard HTML parser
+ * to recognize Alpine.js directives (e.g., x-data, x-bind, x-on) and treat them
+ * appropriately during linting.
+ */
 export { parser } from './parser.js';

package/lib/index.js

@@ -1 +1,7 @@
+/**
+ * @module @markuplint/alpine-parser
+ * Markuplint parser plugin for Alpine.js templates. Extends the standard HTML parser
+ * to recognize Alpine.js directives (e.g., x-data, x-bind, x-on) and treat them
+ * appropriately during linting.
+ */
 export { parser } from './parser.js';

package/lib/parser.d.ts

@@ -1,11 +1,30 @@
-import type { Token } from '@markuplint/parser-utils';
+import type { MLASTNodeTreeItem } from '@markuplint/ml-ast';
 import { HtmlParser } from '@markuplint/html-parser';
+/**
+ * Parser for Alpine.js templates that extends the standard HTML parser.
+ *
+ * Converts `<template x-for="...">` elements into preprocessor-specific
+ * blocks so that markuplint understands the iteration semantics.
+ *
+ * Attribute-level directive resolution (x-bind, x-on, @, :, etc.) is
+ * handled declaratively via `directivePatterns` in `@markuplint/alpine-spec`.
+ */
 declare class AlpineParser extends HtmlParser {
-    visitAttr(token: Token, options: Parameters<HtmlParser['visitAttr']>[1]): (import("packages/@markuplint/ml-ast/lib/types.js").MLASTHTMLAttr & {
-        __rightText?: string;
-    }) | (import("packages/@markuplint/ml-ast/lib/types.js").MLASTSpreadAttr & {
-        __rightText?: string;
-    });
+    /**
+     * Overrides the base element visitor to convert `<template x-for="...">` elements
+     * into preprocessor-specific blocks with `blockBehavior: { type: 'each' }`.
+     * The matching closing tag receives `{ type: 'end' }`. Non-template elements
+     * and templates without `x-for` are passed through unchanged.
+     *
+     * @param token - The element token with tag metadata
+     * @param childNodes - The child AST nodes within the element
+     * @param options - Options forwarded to the base `visitElement`
+     * @returns An array of markuplint node tree items, with `x-for` templates replaced by psblock nodes
+     */
+    visitElement(token: Parameters<HtmlParser['visitElement']>[0], childNodes: Parameters<HtmlParser['visitElement']>[1], options: Parameters<HtmlParser['visitElement']>[2]): readonly MLASTNodeTreeItem[];
 }
+/**
+ * Singleton Alpine.js parser instance for use by the markuplint engine.
+ */
 export declare const parser: AlpineParser;
 export {};

package/lib/parser.js

@@ -1,188 +1,53 @@
 import { HtmlParser } from '@markuplint/html-parser';
+/**
+ * Parser for Alpine.js templates that extends the standard HTML parser.
+ *
+ * Converts `<template x-for="...">` elements into preprocessor-specific
+ * blocks so that markuplint understands the iteration semantics.
+ *
+ * Attribute-level directive resolution (x-bind, x-on, @, :, etc.) is
+ * handled declaratively via `directivePatterns` in `@markuplint/alpine-spec`.
+ */
 class AlpineParser extends HtmlParser {
-    visitAttr(token, options) {
-        const attr = super.visitAttr(token, options);
-        if (attr.type === 'spread') {
-            return attr;
-        }
-        const name = attr.name.raw;
-        switch (name) {
-            /**
-             * @see https://alpinejs.dev/directives/data
-             */
-            case 'x-data': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/init
-             */
-            case 'x-init': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/show
-             */
-            case 'x-show': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/text
-             */
-            case 'x-text': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/html
-             */
-            case 'x-html': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * {@link ./spec.ts} Treat as a normal attribute and allow only in template elements as defined in `spec`.
-             *
-             * @see https://alpinejs.dev/directives/model
-             */
-            case 'x-model': {
-                return attr;
-            }
-            /**
-             * @see https://alpinejs.dev/directives/modelable
-             */
-            case 'x-modelable': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * {@link ./spec.ts} Treat as a normal attribute and allow only in template elements as defined in `spec`.
-             *
-             * @see https://alpinejs.dev/directives/for
-             */
-            case 'x-for': {
-                return attr;
-            }
-            /**
-             * @see https://alpinejs.dev/directives/effect
-             */
-            case 'x-effect': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/ignore
-             */
-            case 'x-ignore': {
-                return {
-                    ...attr,
-                    valueType: 'boolean',
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/ref
-             */
-            case 'x-ref': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/cloak
-             */
-            case 'x-cloak': {
-                return {
-                    ...attr,
-                    valueType: 'boolean',
-                    isDirective: true,
-                };
-            }
-            /**
-             * {@link ./spec.ts} Treat as a normal attribute and allow only in template elements as defined in `spec`.
-             *
-             * @see https://alpinejs.dev/directives/teleport
-             */
-            case 'x-teleport': {
-                return attr;
-            }
-            /**
-             * {@link ./spec.ts} Treat as a normal attribute and allow only in template elements as defined in `spec`.
-             *
-             * @see https://alpinejs.dev/directives/if
-             */
-            case 'x-if': {
-                return attr;
-            }
-            /**
-             * @see https://alpinejs.dev/directives/id
-             */
-            case 'x-id': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-        }
-        /**
-         * @see https://alpinejs.dev/directives/bind
-         */
-        if (name.startsWith('x-bind:') || name.startsWith(':')) {
-            const potentialName = (attr.name.raw.match(/^(x-bind:|:)([^.]+)(?:\.([^.]+))?$/i) ?? [])[2];
-            if (!potentialName) {
-                return attr;
-            }
-            return {
-                ...attr,
-                potentialName,
-                valueType: 'code',
-                isDuplicatable: ['class', 'style'].includes(potentialName),
-                isDynamicValue: true,
-            };
-        }
-        /**
-         * @see https://alpinejs.dev/directives/on
-         */
-        if (name.startsWith('x-on:') || name.startsWith('@')) {
-            const potentialName = (attr.name.raw.match(/^(x-on:|@)([^.]+)(\..+)?$/i) ?? [])[2];
-            if (!potentialName) {
-                return attr;
-            }
-            return {
-                ...attr,
-                potentialName: `on${potentialName.toLowerCase()}`,
-                // TODO: Postpone due to inability to distinguish between custom and native events
-                isDirective: true,
-                isDynamicValue: true,
-            };
-        }
-        /**
-         * @see https://alpinejs.dev/directives/transition
-         */
-        if (/^x-transition(?:$|:|\.)/.test(name)) {
-            return {
-                ...attr,
-                isDirective: true,
+    /**
+     * Overrides the base element visitor to convert `<template x-for="...">` elements
+     * into preprocessor-specific blocks with `blockBehavior: { type: 'each' }`.
+     * The matching closing tag receives `{ type: 'end' }`. Non-template elements
+     * and templates without `x-for` are passed through unchanged.
+     *
+     * @param token - The element token with tag metadata
+     * @param childNodes - The child AST nodes within the element
+     * @param options - Options forwarded to the base `visitElement`
+     * @returns An array of markuplint node tree items, with `x-for` templates replaced by psblock nodes
+     */
+    visitElement(token, childNodes = [], options) {
+        return super.visitElement(token, childNodes, options).map(node => {
+            if (node.type !== 'starttag' && node.type !== 'endtag') {
+                return node;
+            }
+            if (node.nodeName.toLowerCase() !== 'template') {
+                return node;
+            }
+            const attrs = node.type === 'starttag' ? node.attributes : node.pairNode.attributes;
+            if (!attrs.some(attr => attr.nodeName.toLowerCase() === 'x-for')) {
+                return node;
+            }
+            const forBlock = {
+                isFragment: false,
+                childNodes: [],
+                ...node,
+                type: 'psblock',
+                blockBehavior: {
+                    type: node.type === 'starttag' ? 'each' : 'end',
+                    expression: node.raw,
+                },
+                isBogus: false,
             };
-        }
-        return attr;
+            return forBlock;
+        });
     }
 }
+/**
+ * Singleton Alpine.js parser instance for use by the markuplint engine.
+ */
 export const parser = new AlpineParser();

package/lib/spec.d.ts

@@ -1,3 +1,11 @@
 import type { ExtendedSpec } from '@markuplint/ml-spec';
+/**
+ * Extended specification for Alpine.js directive attributes.
+ *
+ * Defines which Alpine.js-specific attributes are allowed on which HTML elements,
+ * their expected value types, and any element-level conditions. This enables
+ * markuplint to validate Alpine.js attributes as if they were part of the
+ * standard HTML spec.
+ */
 declare const spec: ExtendedSpec;
 export default spec;

package/lib/spec.js

@@ -1,4 +1,6 @@
 /**
+ * Attribute specification for the Alpine.js `x-model` directive.
+ *
  * > `x-model` works with the following input elements:
  * > - `<input type="text">`
  * > - `<textarea>`
@@ -13,6 +15,14 @@ const xModel = {
     type: 'NoEmptyAny',
     description: 'The x-model directive is used to bind a variable to a form input.',
 };
+/**
+ * Extended specification for Alpine.js directive attributes.
+ *
+ * Defines which Alpine.js-specific attributes are allowed on which HTML elements,
+ * their expected value types, and any element-level conditions. This enables
+ * markuplint to validate Alpine.js attributes as if they were part of the
+ * standard HTML spec.
+ */
 const spec = {
     specs: [
         {

package/package.json

@@ -1,19 +1,18 @@
 {
 	"name": "@markuplint/alpine-parser",
-	"version": "4.6.22",
+	"version": "5.0.0-alpha.0",
 	"description": "Alpine.js parser for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
 	"type": "module",
 	"exports": {
 		".": {
 			"import": "./lib/index.js",
 			"types": "./lib/index.d.ts"
-		},
-		"./spec": {
-			"import": "./lib/spec.js",
-			"types": "./lib/spec.d.ts"
 		}
 	},
 	"publishConfig": {
@@ -25,11 +24,10 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "4.6.22"
+		"@markuplint/html-parser": "5.0.0-alpha.0"
 	},
 	"devDependencies": {
-		"@markuplint/ml-spec": "4.10.1",
-		"@markuplint/parser-utils": "4.8.10"
+		"@markuplint/parser-utils": "5.0.0-alpha.0"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
 }