@markuplint/react-spec 4.5.21 → 4.5.23

package/ARCHITECTURE.ja.md

@@ -0,0 +1,84 @@
+# @markuplint/react-spec
+
+## 概要
+
+`@markuplint/react-spec` は、markuplint に React 固有の JSX 属性定義を提供する仕様拡張パッケージです。グローバル JSX 属性（`key`、`ref`、`dangerouslySetInnerHTML`、ハイドレーション/contentEditable 警告抑制フラグなど）と、React の制御/非制御フォームコンポーネント（`input`、`select`、`textarea`）の要素レベル属性オーバーライドを登録する単一の `ExtendedSpec` オブジェクトをエクスポートします。
+
+このパッケージにはパースロジックは含まれません。純粋なデータ定義であり、`@markuplint/ml-spec` が基本 HTML 仕様を React 固有の属性で拡張するために使用されます。
+
+## ExtendedSpec の内容
+
+### グローバル属性
+
+グローバル属性は `def['#globalAttrs']['#extends']` の下に定義され、すべての JSX 要素で利用可能です:
+
+| 属性名                           | 型        | 説明                                                                     |
+| -------------------------------- | --------- | ------------------------------------------------------------------------ |
+| `key`                            | `Any`     | リストレンダリング用の特殊属性。React が変更された項目を識別するのに使用 |
+| `ref`                            | `Any`     | 子コンポーネントのインスタンスや DOM 要素にアクセスするための属性        |
+| `dangerouslySetInnerHTML`        | `Any`     | ブラウザ DOM で `innerHTML` を使用する代わりの React の手段              |
+| `suppressContentEditableWarning` | `Boolean` | 子要素を持つ要素が `contentEditable` の場合の警告を抑制                  |
+| `suppressHydrationWarning`       | `Boolean` | React のハイドレーションミスマッチ警告を抑制                             |
+
+### 要素固有のオーバーライド
+
+要素固有の属性は `specs[]` 配列に定義されます。各エントリは特定の HTML 要素を名前で指定します:
+
+| 要素       | 属性名           | 型        | 条件                              | 説明                                     |
+| ---------- | ---------------- | --------- | --------------------------------- | ---------------------------------------- |
+| `input`    | `defaultChecked` | `Boolean` | `[type=checkbox]`, `[type=radio]` | 初期チェック状態の非制御コンポーネント版 |
+| `input`    | `defaultValue`   | `Any`     | --                                | 初期値の非制御コンポーネント版           |
+| `select`   | `value`          | `Any`     | --                                | 制御コンポーネントの値                   |
+| `select`   | `defaultValue`   | `Any`     | --                                | 初期値の非制御コンポーネント版           |
+| `textarea` | `value`          | `Any`     | --                                | 制御コンポーネントの値                   |
+| `textarea` | `defaultValue`   | `Any`     | --                                | 初期値の非制御コンポーネント版           |
+
+`caseSensitive: true` を持つ属性は大文字小文字の完全一致が必要です（例: `defaultchecked` ではなく `defaultChecked`）。`condition` フィールドは CSS セレクタ構文を使用して、属性が有効な場合を制限します。
+
+## ディレクトリ構成
+
+```
+src/
+└── index.ts    — React 固有の属性を持つ ExtendedSpec オブジェクトをエクスポート
+```
+
+## 主要ソースファイル
+
+| ファイル   | 用途                                                          |
+| ---------- | ------------------------------------------------------------- |
+| `index.ts` | `ExtendedSpec` オブジェクトをデフォルトエクスポートとして定義 |
+
+## 統合ポイント
+
+```mermaid
+flowchart LR
+    subgraph upstream ["上流"]
+        htmlSpec["@markuplint/html-spec\n(基本 HTML 仕様)"]
+    end
+
+    subgraph pkg ["@markuplint/react-spec"]
+        spec["ExtendedSpec\n(React 属性)"]
+    end
+
+    subgraph downstream ["下流"]
+        mlSpec["@markuplint/ml-spec\n(仕様解決)"]
+        mlCore["@markuplint/ml-core\n(リントエンジン)"]
+    end
+
+    htmlSpec -->|"基本仕様"| mlSpec
+    spec -->|"拡張"| mlSpec
+    mlSpec -->|"解決済み仕様"| mlCore
+```
+
+### 上流
+
+- **`@markuplint/ml-spec`** -- このパッケージが実装する `ExtendedSpec` 型を提供
+
+### 下流
+
+- **`@markuplint/ml-spec`** -- `ExtendedSpec` オブジェクトを使用して、React 固有の属性を解決済み仕様にマージ
+- **`@markuplint/ml-core`** -- リント時に解決済み仕様（React 拡張を含む）を使用
+
+## ドキュメントマップ
+
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、ExtendedSpec 型リファレンス

package/ARCHITECTURE.md

@@ -0,0 +1,84 @@
+# @markuplint/react-spec
+
+## Overview
+
+`@markuplint/react-spec` is a spec extension package that provides React-specific JSX attribute definitions for markuplint. It exports a single `ExtendedSpec` object that registers global JSX attributes (such as `key`, `ref`, `dangerouslySetInnerHTML`, and hydration/contentEditable warning suppression flags) and element-level attribute overrides for React's controlled and uncontrolled form components (`input`, `select`, `textarea`).
+
+This package contains no parsing logic -- it is purely a data definition consumed by `@markuplint/ml-spec` to extend the base HTML specification with React-specific attributes.
+
+## ExtendedSpec Content
+
+### Global Attributes
+
+Global attributes are defined under `def['#globalAttrs']['#extends']` and are available on every JSX element:
+
+| Attribute                        | Type      | Description                                                               |
+| -------------------------------- | --------- | ------------------------------------------------------------------------- |
+| `key`                            | `Any`     | Special attribute for list rendering to help React identify changed items |
+| `ref`                            | `Any`     | Attribute for accessing child component instances and DOM elements        |
+| `dangerouslySetInnerHTML`        | `Any`     | React's replacement for using `innerHTML` in the browser DOM              |
+| `suppressContentEditableWarning` | `Boolean` | Suppresses the warning when an element with children is `contentEditable` |
+| `suppressHydrationWarning`       | `Boolean` | Suppresses React hydration mismatch warnings for attributes and content   |
+
+### Element-Specific Overrides
+
+Element-specific attributes are defined in the `specs[]` array. Each entry targets a specific HTML element by name:
+
+| Element    | Attribute        | Type      | Condition                         | Description                                       |
+| ---------- | ---------------- | --------- | --------------------------------- | ------------------------------------------------- |
+| `input`    | `defaultChecked` | `Boolean` | `[type=checkbox]`, `[type=radio]` | Uncontrolled equivalent for initial checked state |
+| `input`    | `defaultValue`   | `Any`     | --                                | Uncontrolled equivalent for initial value         |
+| `select`   | `value`          | `Any`     | --                                | Controlled component value                        |
+| `select`   | `defaultValue`   | `Any`     | --                                | Uncontrolled equivalent for initial value         |
+| `textarea` | `value`          | `Any`     | --                                | Controlled component value                        |
+| `textarea` | `defaultValue`   | `Any`     | --                                | Uncontrolled equivalent for initial value         |
+
+Attributes with `caseSensitive: true` require exact case matching (e.g., `defaultChecked` not `defaultchecked`). The `condition` field uses CSS selector syntax to restrict when the attribute is valid.
+
+## Directory Structure
+
+```
+src/
+└── index.ts    — Exports the ExtendedSpec object with React-specific attributes
+```
+
+## Key Source Files
+
+| File       | Purpose                                                             |
+| ---------- | ------------------------------------------------------------------- |
+| `index.ts` | Defines and exports the `ExtendedSpec` object as the default export |
+
+## Integration Points
+
+```mermaid
+flowchart LR
+    subgraph upstream ["Upstream"]
+        htmlSpec["@markuplint/html-spec\n(Base HTML spec)"]
+    end
+
+    subgraph pkg ["@markuplint/react-spec"]
+        spec["ExtendedSpec\n(React attributes)"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlSpec["@markuplint/ml-spec\n(Spec resolution)"]
+        mlCore["@markuplint/ml-core\n(Linting engine)"]
+    end
+
+    htmlSpec -->|"Base spec"| mlSpec
+    spec -->|"Extends"| mlSpec
+    mlSpec -->|"Resolved spec"| mlCore
+```
+
+### Upstream
+
+- **`@markuplint/ml-spec`** -- Provides the `ExtendedSpec` type that this package implements
+
+### Downstream
+
+- **`@markuplint/ml-spec`** -- Consumes the `ExtendedSpec` object to merge React-specific attributes into the resolved specification
+- **`@markuplint/ml-core`** -- Uses the resolved spec (including React extensions) during linting
+
+## Documentation Map
+
+- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and ExtendedSpec 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/react-spec@4.5.20...@markuplint/react-spec@4.5.21) (2025-08-24)
+## [4.5.23](https://github.com/markuplint/markuplint/compare/@markuplint/react-spec@4.5.22...@markuplint/react-spec@4.5.23) (2026-02-10)
 
 **Note:** Version bump only for package @markuplint/react-spec
 
+## [4.5.22](https://github.com/markuplint/markuplint/compare/@markuplint/react-spec@4.5.21...@markuplint/react-spec@4.5.22) (2025-11-05)
 
+**Note:** Version bump only for package @markuplint/react-spec
 
+## [4.5.21](https://github.com/markuplint/markuplint/compare/@markuplint/react-spec@4.5.20...@markuplint/react-spec@4.5.21) (2025-08-24)
 
+**Note:** Version bump only for package @markuplint/react-spec
 
 ## [4.5.20](https://github.com/markuplint/markuplint/compare/@markuplint/react-spec@4.5.19...@markuplint/react-spec@4.5.20) (2025-08-13)
 

package/SKILL.md

@@ -0,0 +1,100 @@
+---
+description: Maintenance tasks for @markuplint/react-spec
+globs:
+  - packages/@markuplint/react-spec/src/**/*.ts
+alwaysApply: false
+---
+
+# react-spec-maintenance
+
+Perform maintenance tasks for `@markuplint/react-spec`: add global attributes,
+add element-specific overrides, and modify the ExtendedSpec object.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                   | Description                                    |
+| ---------------------- | ---------------------------------------------- |
+| `add-global-attribute` | Add a new global attribute to the ExtendedSpec |
+| `add-element-override` | Add an element-specific attribute override     |
+
+If omitted, defaults to `add-global-attribute`.
+
+## 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` -- ExtendedSpec object definition (source of truth)
+
+## Task: add-global-attribute
+
+Add a new global attribute available on every JSX element. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Identify the attribute
+
+1. Determine the attribute name, type (`Any`, `Boolean`, or a specific type), and description
+2. Check the React documentation to confirm the attribute is a valid global JSX attribute
+
+### Step 2: Add the attribute
+
+1. Read `src/index.ts`
+2. Add a new entry under `def['#globalAttrs']['#extends']`:
+   ```ts
+   attributeName: {
+       type: 'Any', // or 'Boolean'
+   },
+   ```
+3. Add a JSDoc comment above the entry describing its purpose
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/react-spec`
+2. Confirm the attribute appears in the exported spec object
+
+## Task: add-element-override
+
+Add an element-specific attribute override. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Identify the element and attribute
+
+1. Determine the target element name (e.g., `input`, `select`, `textarea`)
+2. Determine the attribute name, type, and optional conditions
+
+### Step 2: Add the override
+
+1. Read `src/index.ts`
+2. Find the element in the `specs[]` array, or add a new entry:
+   ```ts
+   {
+       name: 'elementName',
+       attributes: {
+           attributeName: {
+               type: 'Any',
+           },
+       },
+   },
+   ```
+3. If the attribute has conditions (e.g., only for certain input types), add a `condition` array:
+   ```ts
+   condition: ['[type=checkbox]', '[type=radio]'],
+   ```
+4. If the attribute is case-sensitive, add `caseSensitive: true`
+5. Add a JSDoc comment above the entry describing its purpose
+
+### Step 3: Verify
+
+1. Build: `yarn build --scope @markuplint/react-spec`
+2. Confirm the attribute appears in the exported spec object
+
+## Rules
+
+1. **Only export an ExtendedSpec object** -- this package contains no parsing logic.
+2. **Global attributes go under `def['#globalAttrs']['#extends']`** -- they apply to all elements.
+3. **Element overrides go under `specs[]` array** -- each entry targets a specific HTML element by name.
+4. **Each attribute needs at minimum a `type` field** -- valid types include `Any`, `Boolean`, and specific type strings.
+5. **Add JSDoc comments** to all new attribute entries describing their purpose.

package/docs/maintenance.ja.md

@@ -0,0 +1,114 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                    | 説明                   |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/react-spec` | このパッケージをビルド |
+| `yarn dev --scope @markuplint/react-spec`   | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/react-spec` | ビルド成果物を削除     |
+
+## テスト
+
+このパッケージには専用のテストスイートはありません。`ExtendedSpec` オブジェクトは、`@markuplint/ml-spec` の `ExtendedSpec` 型に対する TypeScript 型チェックにより、ビルド時に検証されます。エクスポートされたオブジェクトが型に適合しない場合、ビルドが失敗します。
+
+統合テストは下流で行われます:
+
+- `@markuplint/ml-spec` が拡張仕様を解決し、基本 HTML 仕様とマージ
+- `@markuplint/ml-core` がリント時に解決済み仕様を使用し、属性定義を実行
+
+変更を検証するには、パッケージをビルドして下流のテストを実行します:
+
+```shell
+yarn build --scope @markuplint/react-spec
+yarn test --scope @markuplint/ml-spec --scope @markuplint/ml-core
+```
+
+## レシピ
+
+### 1. グローバル属性の追加
+
+グローバル属性はすべての JSX 要素で利用可能です。
+
+1. `src/index.ts` を開く
+2. `def['#globalAttrs']['#extends']` の下に新しいエントリを追加:
+   ```ts
+   /** 属性の説明 */
+   attributeName: {
+       type: 'Any', // または 'Boolean'
+   },
+   ```
+3. 適切な型を選択:
+   - `'Any'` -- 任意の値を受け付ける（文字列、式など）
+   - `'Boolean'` -- ブール属性（存在が `true` を意味する）
+4. ビルド: `yarn build --scope @markuplint/react-spec`
+
+### 2. 要素固有のオーバーライドの追加
+
+要素オーバーライドは、特定の HTML 要素でのみ利用可能な属性を定義します。
+
+1. `src/index.ts` を開く
+2. `specs[]` 配列で対象の要素を探す。存在しない場合は新しいエントリを追加:
+   ```ts
+   {
+       name: 'elementName',
+       attributes: {
+           /** 属性の説明 */
+           attributeName: {
+               type: 'Any',
+           },
+       },
+   },
+   ```
+3. 要素が既に存在する場合は、その `attributes` オブジェクトに新しい属性を追加
+4. ビルド: `yarn build --scope @markuplint/react-spec`
+
+### 3. 条件付き属性の追加
+
+条件付き属性は、要素が CSS セレクタ条件に一致する場合にのみ有効です。
+
+1. `src/index.ts` を開く
+2. `specs[]` 配列で要素エントリを見つけるか作成
+3. `condition` 配列を持つ属性を追加:
+   ```ts
+   attributeName: {
+       type: 'Boolean',
+       caseSensitive: true,
+       condition: ['[type=checkbox]', '[type=radio]'],
+   },
+   ```
+4. `condition` 配列は CSS 属性セレクタ構文を使用
+5. 複数の条件は OR として扱われる -- いずれかの条件に一致すれば属性は有効
+6. 属性名の大文字小文字を区別する必要がある場合は `caseSensitive: true` を設定（React JSX 属性では一般的）
+7. ビルド: `yarn build --scope @markuplint/react-spec`
+
+## ExtendedSpec 型リファレンス
+
+`ExtendedSpec` 型（`@markuplint/ml-spec` から）は、このパッケージに関連する以下の構造を持ちます:
+
+```ts
+interface ExtendedSpec {
+  def?: {
+    '#globalAttrs'?: {
+      '#extends': Record<string, AttributeSpec>;
+    };
+  };
+  specs?: Array<{
+    name: string;
+    attributes: Record<string, AttributeSpec>;
+  }>;
+}
+```
+
+### AttributeSpec のフィールド
+
+| フィールド      | 型         | 必須   | 説明                                    |
+| --------------- | ---------- | ------ | --------------------------------------- |
+| `type`          | `string`   | はい   | 属性値の型（`'Any'`、`'Boolean'` など） |
+| `caseSensitive` | `boolean`  | いいえ | 属性名の大文字小文字を区別するかどうか  |
+| `condition`     | `string[]` | いいえ | 属性が適用される CSS セレクタ条件       |
+
+### 型の値
+
+- `'Any'` -- 属性は任意の値を受け付ける
+- `'Boolean'` -- 属性はブール値（存在が `true` を示す）

package/docs/maintenance.md

@@ -0,0 +1,114 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                     | Description            |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/react-spec` | Build this package     |
+| `yarn dev --scope @markuplint/react-spec`   | Watch mode build       |
+| `yarn clean --scope @markuplint/react-spec` | Remove build artifacts |
+
+## Testing
+
+This package has no dedicated test suite. The `ExtendedSpec` object is validated at build time through TypeScript type checking against the `ExtendedSpec` type from `@markuplint/ml-spec`. If the exported object does not conform to the type, the build will fail.
+
+Integration testing occurs downstream:
+
+- `@markuplint/ml-spec` resolves the extended spec and merges it with the base HTML spec
+- `@markuplint/ml-core` uses the resolved spec during linting, which exercises the attribute definitions
+
+To verify changes, build the package and run downstream tests:
+
+```shell
+yarn build --scope @markuplint/react-spec
+yarn test --scope @markuplint/ml-spec --scope @markuplint/ml-core
+```
+
+## Recipes
+
+### 1. Adding a Global Attribute
+
+Global attributes are available on every JSX element.
+
+1. Open `src/index.ts`
+2. Add a new entry under `def['#globalAttrs']['#extends']`:
+   ```ts
+   /** Description of the attribute */
+   attributeName: {
+       type: 'Any', // or 'Boolean'
+   },
+   ```
+3. Choose the appropriate type:
+   - `'Any'` -- accepts any value (strings, expressions, etc.)
+   - `'Boolean'` -- boolean attribute (presence means `true`)
+4. Build: `yarn build --scope @markuplint/react-spec`
+
+### 2. Adding an Element-Specific Override
+
+Element overrides define attributes available only on specific HTML elements.
+
+1. Open `src/index.ts`
+2. Find the target element in the `specs[]` array. If it does not exist, add a new entry:
+   ```ts
+   {
+       name: 'elementName',
+       attributes: {
+           /** Description of the attribute */
+           attributeName: {
+               type: 'Any',
+           },
+       },
+   },
+   ```
+3. If the element already exists, add the new attribute to its `attributes` object
+4. Build: `yarn build --scope @markuplint/react-spec`
+
+### 3. Adding a Conditional Attribute
+
+Conditional attributes are only valid when the element matches a CSS selector condition.
+
+1. Open `src/index.ts`
+2. Find or create the element entry in the `specs[]` array
+3. Add the attribute with a `condition` array:
+   ```ts
+   attributeName: {
+       type: 'Boolean',
+       caseSensitive: true,
+       condition: ['[type=checkbox]', '[type=radio]'],
+   },
+   ```
+4. The `condition` array uses CSS attribute selector syntax
+5. Multiple conditions are treated as an OR -- the attribute is valid if any condition matches
+6. Set `caseSensitive: true` if the attribute name must be case-sensitive (typical for React JSX attributes)
+7. Build: `yarn build --scope @markuplint/react-spec`
+
+## ExtendedSpec Type Reference
+
+The `ExtendedSpec` type (from `@markuplint/ml-spec`) has the following structure relevant to this package:
+
+```ts
+interface ExtendedSpec {
+  def?: {
+    '#globalAttrs'?: {
+      '#extends': Record<string, AttributeSpec>;
+    };
+  };
+  specs?: Array<{
+    name: string;
+    attributes: Record<string, AttributeSpec>;
+  }>;
+}
+```
+
+### AttributeSpec Fields
+
+| Field           | Type       | Required | Description                                            |
+| --------------- | ---------- | -------- | ------------------------------------------------------ |
+| `type`          | `string`   | Yes      | The attribute value type (`'Any'`, `'Boolean'`, etc.)  |
+| `caseSensitive` | `boolean`  | No       | Whether the attribute name is case-sensitive           |
+| `condition`     | `string[]` | No       | CSS selector conditions for when the attribute applies |
+
+### Type Values
+
+- `'Any'` -- The attribute accepts any value
+- `'Boolean'` -- The attribute is a boolean (presence indicates `true`)

package/lib/index.d.ts

@@ -1,3 +1,21 @@
+/**
+ * @module @markuplint/react-spec
+ *
+ * Provides React-specific extended specifications for markuplint.
+ * Defines React's JSX global attributes (such as `key`, `ref`,
+ * `dangerouslySetInnerHTML`, and hydration/contentEditable warning
+ * suppression flags) as well as element-level attribute overrides
+ * for controlled and uncontrolled form components (`input`, `select`,
+ * `textarea`).
+ */
 import type { ExtendedSpec } from '@markuplint/ml-spec';
+/**
+ * The React framework extended specification.
+ *
+ * Registers global JSX attributes available on every element and
+ * provides per-element attribute definitions for React's controlled
+ * and uncontrolled form component patterns (`defaultChecked`,
+ * `defaultValue`, `value`).
+ */
 declare const spec: ExtendedSpec;
 export default spec;

package/lib/index.js

@@ -1,3 +1,21 @@
+/**
+ * @module @markuplint/react-spec
+ *
+ * Provides React-specific extended specifications for markuplint.
+ * Defines React's JSX global attributes (such as `key`, `ref`,
+ * `dangerouslySetInnerHTML`, and hydration/contentEditable warning
+ * suppression flags) as well as element-level attribute overrides
+ * for controlled and uncontrolled form components (`input`, `select`,
+ * `textarea`).
+ */
+/**
+ * The React framework extended specification.
+ *
+ * Registers global JSX attributes available on every element and
+ * provides per-element attribute definitions for React's controlled
+ * and uncontrolled form component patterns (`defaultChecked`,
+ * `defaultValue`, `value`).
+ */
 const spec = {
     def: {
         '#globalAttrs': {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/react-spec",
-	"version": "4.5.21",
+	"version": "4.5.23",
 	"description": "Extended specification for tags and attributes in React",
 	"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"
 }