@markuplint/svelte-spec 4.5.21 → 4.5.23

package/ARCHITECTURE.ja.md

@@ -0,0 +1,74 @@
+# @markuplint/svelte-spec
+
+## 概要
+
+`@markuplint/svelte-spec` は markuplint 向けの Svelte 固有の拡張仕様を提供します。Svelte のフォーム要素における双方向バインディング動作に対応するため、要素レベルの属性オーバーライドを定義する `ExtendedSpec` オブジェクトをエクスポートします。具体的には、`<select>` と `<textarea>` 要素の `value` 属性の型を `Any` に拡張し、文字列だけでなく任意の型のバインド変数を許容します。
+
+## ExtendedSpec の内容
+
+パッケージは `specs` 配列に要素固有のオーバーライドを含む単一の `ExtendedSpec` オブジェクトをエクスポートします:
+
+### 要素固有のオーバーライド
+
+| 要素         | 属性    | 型オーバーライド | 理由                                                    |
+| ------------ | ------- | ---------------- | ------------------------------------------------------- |
+| `<select>`   | `value` | `Any`            | Svelte の `bind:value` は文字列だけでなく任意の型を許容 |
+| `<textarea>` | `value` | `Any`            | Svelte の `bind:value` は文字列だけでなく任意の型を許容 |
+
+これらのオーバーライドにより、markuplint が Svelte 固有の属性使用を不正としてフラグ付けすることなく、標準 HTML 仕様を拡張します。
+
+## ディレクトリ構成
+
+```
+src/
+└── index.ts    — Svelte 固有のオーバーライドを含む ExtendedSpec オブジェクトをエクスポート
+```
+
+## 主要ソースファイル
+
+| ファイル       | 用途                                                        |
+| -------------- | ----------------------------------------------------------- |
+| `src/index.ts` | Svelte 用の `ExtendedSpec` オブジェクトを定義・エクスポート |
+
+## 統合ポイント
+
+```mermaid
+flowchart TD
+    subgraph upstream ["上流"]
+        htmlSpec["@markuplint/html-spec\n(ベース HTML 仕様)"]
+        mlSpec["@markuplint/ml-spec\n(ExtendedSpec 型)"]
+    end
+
+    subgraph pkg ["@markuplint/svelte-spec"]
+        spec["ExtendedSpec オブジェクト\n(select, textarea オーバーライド)"]
+    end
+
+    subgraph downstream ["下流"]
+        mlCore["@markuplint/ml-core\n(schemaToSpec で仕様をマージ)"]
+    end
+
+    subgraph paired ["対となるパーサー"]
+        svelteParser["@markuplint/svelte-parser\n(Svelte コンポーネントのパース)"]
+    end
+
+    mlSpec -->|"ExtendedSpec 型"| spec
+    htmlSpec -->|"ベース要素定義"| mlCore
+    spec -->|"Svelte オーバーライド"| mlCore
+    svelteParser -->|"MLASTDocument を生成"| mlCore
+```
+
+### 上流
+
+- **`@markuplint/ml-spec`** -- このパッケージが実装する `ExtendedSpec` 型定義を提供
+
+### 下流
+
+- **`@markuplint/ml-core`** -- `schemaToSpec()` を通じてこの仕様を利用し、Svelte のオーバーライドをベース HTML 仕様にマージ
+
+### 対となるパーサー
+
+- **`@markuplint/svelte-parser`** -- Svelte コンポーネント構文を処理するパーサー。パーサーが Svelte テンプレートを markuplint AST に変換する一方、この spec パッケージはリンティングに必要な属性型情報を提供します。
+
+## ドキュメントマップ
+
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、型リファレンス

package/ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# @markuplint/svelte-spec
+
+## Overview
+
+`@markuplint/svelte-spec` provides Svelte-specific extended specifications for markuplint. It exports an `ExtendedSpec` object that defines element-level attribute overrides to accommodate Svelte's two-way binding behavior on form elements. Specifically, the `<select>` and `<textarea>` elements have their `value` attribute type broadened to `Any`, allowing bound variables of any type rather than only strings.
+
+## ExtendedSpec Content
+
+The package exports a single `ExtendedSpec` object with element-specific overrides in the `specs` array:
+
+### Element-Specific Overrides
+
+| Element      | Attribute | Type Override | Reason                                                  |
+| ------------ | --------- | ------------- | ------------------------------------------------------- |
+| `<select>`   | `value`   | `Any`         | Svelte's `bind:value` allows any type, not just strings |
+| `<textarea>` | `value`   | `Any`         | Svelte's `bind:value` allows any type, not just strings |
+
+These overrides extend the standard HTML spec so that markuplint does not flag Svelte-specific attribute usage as invalid.
+
+## Directory Structure
+
+```
+src/
+└── index.ts    — Exports the ExtendedSpec object with Svelte-specific overrides
+```
+
+## Key Source Files
+
+| File           | Purpose                                                  |
+| -------------- | -------------------------------------------------------- |
+| `src/index.ts` | Defines and exports the `ExtendedSpec` object for Svelte |
+
+## Integration Points
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        htmlSpec["@markuplint/html-spec\n(Base HTML spec)"]
+        mlSpec["@markuplint/ml-spec\n(ExtendedSpec type)"]
+    end
+
+    subgraph pkg ["@markuplint/svelte-spec"]
+        spec["ExtendedSpec object\n(select, textarea overrides)"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(Merges specs via schemaToSpec)"]
+    end
+
+    subgraph paired ["Paired Parser"]
+        svelteParser["@markuplint/svelte-parser\n(Svelte component parsing)"]
+    end
+
+    mlSpec -->|"ExtendedSpec type"| spec
+    htmlSpec -->|"Base element definitions"| mlCore
+    spec -->|"Svelte overrides"| mlCore
+    svelteParser -->|"Produces MLASTDocument"| mlCore
+```
+
+### Upstream
+
+- **`@markuplint/ml-spec`** -- Provides the `ExtendedSpec` type definition that this package implements
+
+### Downstream
+
+- **`@markuplint/ml-core`** -- Consumes this spec via `schemaToSpec()`, merging Svelte overrides with the base HTML spec
+
+### Paired Parser
+
+- **`@markuplint/svelte-parser`** -- The parser counterpart that handles Svelte component syntax. While the parser converts Svelte templates into the markuplint AST, this spec package provides the attribute type information needed for linting.
+
+## Documentation Map
+
+- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and type reference

package/CHANGELOG.md

@@ -3,13 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.5.21](https://github.com/markuplint/markuplint/compare/@markuplint/svelte-spec@4.5.20...@markuplint/svelte-spec@4.5.21) (2025-08-24)
+## [4.5.23](https://github.com/markuplint/markuplint/compare/@markuplint/svelte-spec@4.5.22...@markuplint/svelte-spec@4.5.23) (2026-02-10)
 
 **Note:** Version bump only for package @markuplint/svelte-spec
 
+## [4.5.22](https://github.com/markuplint/markuplint/compare/@markuplint/svelte-spec@4.5.21...@markuplint/svelte-spec@4.5.22) (2025-11-05)
 
+**Note:** Version bump only for package @markuplint/svelte-spec
 
+## [4.5.21](https://github.com/markuplint/markuplint/compare/@markuplint/svelte-spec@4.5.20...@markuplint/svelte-spec@4.5.21) (2025-08-24)
 
+**Note:** Version bump only for package @markuplint/svelte-spec
 
 ## [4.5.20](https://github.com/markuplint/markuplint/compare/@markuplint/svelte-spec@4.5.19...@markuplint/svelte-spec@4.5.20) (2025-08-13)
 

package/SKILL.md

@@ -0,0 +1,99 @@
+---
+description: Maintenance tasks for @markuplint/svelte-spec
+globs:
+  - packages/@markuplint/svelte-spec/src/**/*.ts
+alwaysApply: false
+---
+
+# svelte-spec-maintenance
+
+Perform maintenance tasks for `@markuplint/svelte-spec`: add global attributes,
+add element-specific attribute overrides for Svelte components.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                   | Description                                |
+| ---------------------- | ------------------------------------------ |
+| `add-global-attribute` | Add a new global attribute for Svelte      |
+| `add-element-override` | Add an element-specific attribute override |
+
+If omitted, defaults to `add-element-override`.
+
+## Reference
+
+Before executing any task, read `docs/maintenance.md` (or `docs/maintenance.ja.md`)
+for the full guide. The recipes there are the source of truth for procedures.
+
+Also read:
+
+- `ARCHITECTURE.md` -- Package overview, ExtendedSpec content, and integration points
+- `src/index.ts` -- The single source file (source of truth for the spec object)
+
+## Task: add-global-attribute
+
+Add a new global attribute that applies to all Svelte elements. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Read the current spec
+
+1. Read `src/index.ts` to understand the current `ExtendedSpec` structure
+2. Check if a `def` property with `#globalAttrs` already exists
+
+### Step 2: Add the global attribute
+
+1. If `def` does not exist, add it to the spec object:
+   ```ts
+   def: {
+     '#globalAttrs': {
+       '#extends': {
+         'attribute-name': {
+           type: 'Any',
+         },
+       },
+     },
+   },
+   ```
+2. If `def['#globalAttrs']['#extends']` already exists, add the new attribute to it
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/svelte-spec`
+2. Test: `yarn test --scope @markuplint/svelte-spec`
+
+## Task: add-element-override
+
+Add an element-specific attribute override. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Read the current spec
+
+1. Read `src/index.ts` to understand the current `specs` array
+2. Check if the target element already has an entry
+
+### Step 2: Add the override
+
+1. If the element already exists in `specs`, add the new attribute to its `attributes` object
+2. If the element does not exist, add a new entry to the `specs` array:
+   ```ts
+   {
+     name: 'element-name',
+     attributes: {
+       'attribute-name': {
+         type: 'Any',
+       },
+     },
+   },
+   ```
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/svelte-spec`
+2. Test: `yarn test --scope @markuplint/svelte-spec`
+
+## Rules
+
+1. **Only export an `ExtendedSpec` object** -- this package must not contain any parsing logic.
+2. **Global attributes go under `def['#globalAttrs']['#extends']`** -- not in the `specs` array.
+3. **Element overrides go under the `specs[]` array** -- each entry needs a `name` and `attributes` object.
+4. **Each attribute needs at minimum a `type` field** -- common values are `Any`, `String`, `Boolean`, or an enum object.
+5. **Add JSDoc comments** to any new attribute definitions explaining why the override is needed.

package/docs/maintenance.ja.md

@@ -0,0 +1,127 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                     | 説明                   |
+| -------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/svelte-spec` | このパッケージをビルド |
+| `yarn dev --scope @markuplint/svelte-spec`   | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/svelte-spec` | ビルド成果物を削除     |
+| `yarn test --scope @markuplint/svelte-spec`  | テストを実行           |
+
+## テスト
+
+このパッケージは静的なデータオブジェクトのみをエクスポートするため、デフォルトではテストファイルがありません。検証はビルドステップで行われます（TypeScript の型チェックにより、エクスポートされたオブジェクトが `ExtendedSpec` 型に準拠していることが保証されます）。
+
+下流パッケージとの統合を検証するには:
+
+```shell
+yarn test --scope @markuplint/svelte-parser
+```
+
+## レシピ
+
+### 1. グローバル属性の追加
+
+1. `src/index.ts` を読む
+2. spec オブジェクトに `def` プロパティが存在しない場合、追加する:
+   ```ts
+   const spec: ExtendedSpec = {
+     def: {
+       '#globalAttrs': {
+         '#extends': {
+           'new-attribute': {
+             type: 'Any',
+           },
+         },
+       },
+     },
+     specs: [
+       // 既存のエントリ...
+     ],
+   };
+   ```
+3. `def['#globalAttrs']['#extends']` が既に存在する場合、既存のオブジェクトに新しい属性を追加
+4. ビルド: `yarn build --scope @markuplint/svelte-spec`
+5. 下流パーサーが正常に動作することを確認: `yarn test --scope @markuplint/svelte-parser`
+
+### 2. 要素固有のオーバーライドの追加
+
+1. `src/index.ts` を読む
+2. 対象の要素が `specs` 配列に既にエントリを持っているか確認
+3. 要素が存在する場合、その `attributes` オブジェクトに新しい属性を追加:
+   ```ts
+   {
+     name: 'existing-element',
+     attributes: {
+       existingAttr: { type: 'Any' },
+       newAttr: { type: 'Any' },  // ここに追加
+     },
+   },
+   ```
+4. 要素が存在しない場合、`specs` 配列に新しいエントリを追加:
+   ```ts
+   {
+     name: 'new-element',
+     attributes: {
+       'attribute-name': {
+         type: 'Any',
+       },
+     },
+   },
+   ```
+5. ビルド: `yarn build --scope @markuplint/svelte-spec`
+6. 下流パーサーが正常に動作することを確認: `yarn test --scope @markuplint/svelte-parser`
+
+## ExtendedSpec 型リファレンス
+
+`ExtendedSpec` 型（`@markuplint/ml-spec` から提供）は以下の構造を持ちます:
+
+```ts
+type ExtendedSpec = {
+  readonly cites?: Cites; // 参照 URL
+  readonly def?: Partial<SpecDefs>; // グローバル定義
+  readonly specs?: readonly ExtendedElementSpec[]; // 要素ごとのオーバーライド
+};
+```
+
+### `def` -- グローバル定義
+
+すべての要素に適用される属性に使用:
+
+```ts
+def: {
+  '#globalAttrs': {
+    '#extends': {
+      'attribute-name': {
+        type: 'Any',
+      },
+    },
+  },
+}
+```
+
+### `specs` -- 要素ごとのオーバーライド
+
+`specs` 配列の各エントリは特定の HTML 要素を対象とします:
+
+```ts
+specs: [
+  {
+    name: 'element-name', // HTML タグ名
+    attributes: {
+      'attribute-name': {
+        type: 'Any', // 型オーバーライド
+      },
+    },
+  },
+];
+```
+
+よく使われる属性型の値:
+
+| 型の値      | 意味                               |
+| ----------- | ---------------------------------- |
+| `'Any'`     | 任意の型を許容（バインド値に使用） |
+| `'String'`  | 文字列値のみ許容                   |
+| `'Boolean'` | ブール属性（存在/不在）            |

package/docs/maintenance.md

@@ -0,0 +1,127 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                      | Description            |
+| -------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/svelte-spec` | Build this package     |
+| `yarn dev --scope @markuplint/svelte-spec`   | Watch mode build       |
+| `yarn clean --scope @markuplint/svelte-spec` | Remove build artifacts |
+| `yarn test --scope @markuplint/svelte-spec`  | Run tests              |
+
+## Testing
+
+This package has no test files by default because it exports only a static data object. Verification is done through the build step (TypeScript type checking ensures the exported object conforms to the `ExtendedSpec` type).
+
+To verify integration with downstream packages:
+
+```shell
+yarn test --scope @markuplint/svelte-parser
+```
+
+## Recipes
+
+### 1. Adding a Global Attribute
+
+1. Read `src/index.ts`
+2. If the `def` property does not exist on the spec object, add it:
+   ```ts
+   const spec: ExtendedSpec = {
+     def: {
+       '#globalAttrs': {
+         '#extends': {
+           'new-attribute': {
+             type: 'Any',
+           },
+         },
+       },
+     },
+     specs: [
+       // existing entries...
+     ],
+   };
+   ```
+3. If `def['#globalAttrs']['#extends']` already exists, add the new attribute to the existing object
+4. Build: `yarn build --scope @markuplint/svelte-spec`
+5. Verify the downstream parser still works: `yarn test --scope @markuplint/svelte-parser`
+
+### 2. Adding an Element-Specific Override
+
+1. Read `src/index.ts`
+2. Check if the target element already has an entry in the `specs` array
+3. If the element exists, add the new attribute to its `attributes` object:
+   ```ts
+   {
+     name: 'existing-element',
+     attributes: {
+       existingAttr: { type: 'Any' },
+       newAttr: { type: 'Any' },  // add here
+     },
+   },
+   ```
+4. If the element does not exist, add a new entry to the `specs` array:
+   ```ts
+   {
+     name: 'new-element',
+     attributes: {
+       'attribute-name': {
+         type: 'Any',
+       },
+     },
+   },
+   ```
+5. Build: `yarn build --scope @markuplint/svelte-spec`
+6. Verify the downstream parser still works: `yarn test --scope @markuplint/svelte-parser`
+
+## ExtendedSpec Type Reference
+
+The `ExtendedSpec` type (from `@markuplint/ml-spec`) has the following structure:
+
+```ts
+type ExtendedSpec = {
+  readonly cites?: Cites; // Reference URLs
+  readonly def?: Partial<SpecDefs>; // Global definitions
+  readonly specs?: readonly ExtendedElementSpec[]; // Per-element overrides
+};
+```
+
+### `def` -- Global Definitions
+
+Used for attributes that apply to all elements:
+
+```ts
+def: {
+  '#globalAttrs': {
+    '#extends': {
+      'attribute-name': {
+        type: 'Any',
+      },
+    },
+  },
+}
+```
+
+### `specs` -- Per-Element Overrides
+
+Each entry in the `specs` array targets a specific HTML element:
+
+```ts
+specs: [
+  {
+    name: 'element-name', // HTML tag name
+    attributes: {
+      'attribute-name': {
+        type: 'Any', // Type override
+      },
+    },
+  },
+];
+```
+
+Common attribute type values:
+
+| Type Value  | Meaning                                  |
+| ----------- | ---------------------------------------- |
+| `'Any'`     | Accepts any type (used for bound values) |
+| `'String'`  | Accepts only string values               |
+| `'Boolean'` | Boolean attribute (presence/absence)     |

package/lib/index.d.ts

@@ -1,3 +1,20 @@
+/**
+ * @module @markuplint/svelte-spec
+ *
+ * Provides Svelte-specific extended specifications for markuplint.
+ * Defines element-level attribute overrides for Svelte's two-way
+ * binding behavior on form elements (`<select>` and `<textarea>`),
+ * where the `value` attribute accepts any type to support bound
+ * variables.
+ */
 import type { ExtendedSpec } from '@markuplint/ml-spec';
+/**
+ * The Svelte framework extended specification.
+ *
+ * Provides per-element attribute definitions that accommodate
+ * Svelte's two-way binding (`bind:value`) on `<select>` and
+ * `<textarea>` elements, allowing the `value` attribute to accept
+ * any type rather than only strings.
+ */
 declare const spec: ExtendedSpec;
 export default spec;

package/lib/index.js

@@ -1,3 +1,20 @@
+/**
+ * @module @markuplint/svelte-spec
+ *
+ * Provides Svelte-specific extended specifications for markuplint.
+ * Defines element-level attribute overrides for Svelte's two-way
+ * binding behavior on form elements (`<select>` and `<textarea>`),
+ * where the `value` attribute accepts any type to support bound
+ * variables.
+ */
+/**
+ * The Svelte framework extended specification.
+ *
+ * Provides per-element attribute definitions that accommodate
+ * Svelte's two-way binding (`bind:value`) on `<select>` and
+ * `<textarea>` elements, allowing the `value` attribute to accept
+ * any type rather than only strings.
+ */
 const spec = {
     specs: [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/svelte-spec",
-	"version": "4.5.21",
+	"version": "4.5.23",
 	"description": "Extended specification for tags and attributes in Svelte",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -21,7 +21,7 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-spec": "4.10.0"
+		"@markuplint/ml-spec": "4.10.2"
 	},
-	"gitHead": "ae97eb2d31ecedf4f0800fbbf18588aad4ebca04"
+	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
 }