@markuplint/html-spec 4.17.0 → 5.0.0-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ARCHITECTURE.ja.md +25 -25
- package/ARCHITECTURE.md +29 -23
- package/CHANGELOG.md +22 -0
- package/README.md +4 -4
- package/SKILL.md +21 -21
- package/docs/build-pipeline.ja.md +9 -9
- package/docs/build-pipeline.md +9 -9
- package/docs/element-spec-format.ja.md +22 -22
- package/docs/element-spec-format.md +10 -10
- package/docs/maintenance.ja.md +24 -24
- package/docs/maintenance.md +24 -24
- package/index.json +17855 -4291
- package/package.json +9 -5
package/ARCHITECTURE.ja.md
CHANGED
|
@@ -10,12 +10,12 @@
|
|
|
10
10
|
|
|
11
11
|
```
|
|
12
12
|
src/
|
|
13
|
-
├── spec.a.
|
|
14
|
-
├── spec.abbr.
|
|
13
|
+
├── spec.a.jsonc # <a> 要素の仕様
|
|
14
|
+
├── spec.abbr.jsonc # <abbr> 要素の仕様
|
|
15
15
|
├── ... (計 177 個の要素仕様ファイル)
|
|
16
|
-
├── spec.svg_text.
|
|
17
|
-
├── spec-common.attributes.
|
|
18
|
-
└── spec-common.contents.
|
|
16
|
+
├── spec.svg_text.jsonc # <svg:text> 要素の仕様
|
|
17
|
+
├── spec-common.attributes.jsonc # 19 個のグローバル属性カテゴリ定義
|
|
18
|
+
└── spec-common.contents.jsonc # HTML 10 + SVG 19 のコンテンツモデルカテゴリ定義
|
|
19
19
|
|
|
20
20
|
build.mjs # @markuplint/spec-generator を呼び出すビルドスクリプト
|
|
21
21
|
index.json # 生成出力（48K 行以上、編集不可）
|
|
@@ -30,9 +30,9 @@ test/
|
|
|
30
30
|
```mermaid
|
|
31
31
|
flowchart TD
|
|
32
32
|
subgraph sources ["ソースデータ"]
|
|
33
|
-
specFiles["src/spec.*.
|
|
34
|
-
commonAttrs["src/spec-common.attributes.
|
|
35
|
-
commonContents["src/spec-common.contents.
|
|
33
|
+
specFiles["src/spec.*.jsonc\n(177 個の要素仕様)"]
|
|
34
|
+
commonAttrs["src/spec-common.attributes.jsonc\n(19 グローバル属性カテゴリ)"]
|
|
35
|
+
commonContents["src/spec-common.contents.jsonc\n(HTML 10 + SVG 19 コンテンツモデル)"]
|
|
36
36
|
end
|
|
37
37
|
|
|
38
38
|
subgraph build ["ビルドパイプライン"]
|
|
@@ -112,18 +112,18 @@ export = json;
|
|
|
112
112
|
|
|
113
113
|
## 主要コンポーネント
|
|
114
114
|
|
|
115
|
-
| コンポーネント | ファイル
|
|
116
|
-
| -------------- |
|
|
117
|
-
| ソース仕様 | `src/spec.*.
|
|
118
|
-
| 共通定義 | `src/spec-common.*.
|
|
119
|
-
| ビルドシステム | `build.mjs`
|
|
120
|
-
| 生成出力 | `index.json`
|
|
121
|
-
| 型宣言 | `index.d.ts`
|
|
122
|
-
| スキーマ検証 | `test/structure.spec.mjs`
|
|
115
|
+
| コンポーネント | ファイル | 説明 |
|
|
116
|
+
| -------------- | --------------------------------------- | ------------------------------------------------------------- |
|
|
117
|
+
| ソース仕様 | `src/spec.*.jsonc`（177 ファイル） | 要素ごとの仕様定義（コンテンツモデル、属性、ARIA マッピング） |
|
|
118
|
+
| 共通定義 | `src/spec-common.*.jsonc`（2 ファイル） | グローバル属性カテゴリとコンテンツモデルマクロの共有定義 |
|
|
119
|
+
| ビルドシステム | `build.mjs` | `@markuplint/spec-generator` の `main()` を呼び出すエントリー |
|
|
120
|
+
| 生成出力 | `index.json` | 統合データセット（48K 行以上、直接編集不可） |
|
|
121
|
+
| 型宣言 | `index.d.ts` | `@markuplint/ml-spec` からの型を再エクスポート |
|
|
122
|
+
| スキーマ検証 | `test/structure.spec.mjs` | Ajv ベースの JSON スキーマ検証テスト |
|
|
123
123
|
|
|
124
124
|
## 要素仕様のフォーマット
|
|
125
125
|
|
|
126
|
-
各 `src/spec.*.
|
|
126
|
+
各 `src/spec.*.jsonc` ファイルは以下の構造を持ちます（例: `spec.a.jsonc`）。
|
|
127
127
|
|
|
128
128
|
```jsonc
|
|
129
129
|
// https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element
|
|
@@ -162,7 +162,7 @@ export = json;
|
|
|
162
162
|
|
|
163
163
|
## 共通定義ファイル
|
|
164
164
|
|
|
165
|
-
### `spec-common.attributes.
|
|
165
|
+
### `spec-common.attributes.jsonc`
|
|
166
166
|
|
|
167
167
|
19 個のグローバル属性カテゴリを定義します。カテゴリキーは `#` プレフィックスで参照されます。
|
|
168
168
|
|
|
@@ -173,7 +173,7 @@ export = json;
|
|
|
173
173
|
| `#ARIAAttrs` | `aria-*` 属性群 |
|
|
174
174
|
| `#HTMLLinkAndFetchingAttrs` | `href`, `target`, `download` 等のリンク関連属性 |
|
|
175
175
|
|
|
176
|
-
### `spec-common.contents.
|
|
176
|
+
### `spec-common.contents.jsonc`
|
|
177
177
|
|
|
178
178
|
コンテンツモデルカテゴリのマクロ定義です。
|
|
179
179
|
|
|
@@ -190,15 +190,15 @@ import { main } from '@markuplint/spec-generator';
|
|
|
190
190
|
|
|
191
191
|
await main({
|
|
192
192
|
outputFilePath: path.resolve(import.meta.dirname, 'index.json'),
|
|
193
|
-
htmlFilePattern: path.resolve(import.meta.dirname, 'src', 'spec.*.
|
|
194
|
-
commonAttrsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.attributes.
|
|
195
|
-
commonContentsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.contents.
|
|
193
|
+
htmlFilePattern: path.resolve(import.meta.dirname, 'src', 'spec.*.jsonc'),
|
|
194
|
+
commonAttrsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.attributes.jsonc'),
|
|
195
|
+
commonContentsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.contents.jsonc'),
|
|
196
196
|
});
|
|
197
197
|
```
|
|
198
198
|
|
|
199
199
|
ビルドプロセスの流れ:
|
|
200
200
|
|
|
201
|
-
1. `src/spec.*.
|
|
201
|
+
1. `src/spec.*.jsonc` と `src/spec-common.*.jsonc` を読み込む
|
|
202
202
|
2. MDN、W3C ARIA（1.1/1.2/1.3）、HTML Living Standard、SVG 仕様から外部データをフェッチ
|
|
203
203
|
3. 手動仕様と外部データをマージ（手動データが優先）
|
|
204
204
|
4. 統合された `index.json` を出力
|
|
@@ -222,8 +222,8 @@ yarn gen:prettier
|
|
|
222
222
|
|
|
223
223
|
1. **構造テスト**: 全要素仕様に対して `resolveNamespace()` と `getAttrSpecsByNames()` を呼び出し、属性仕様の整合性を確認
|
|
224
224
|
2. **スキーマ検証**: Ajv を使用して各ソース JSON ファイルが `@markuplint/ml-spec` の JSON スキーマに適合することを検証
|
|
225
|
-
- `spec.*.
|
|
226
|
-
- `spec-common.attributes.
|
|
225
|
+
- `spec.*.jsonc` → `element.schema.json`（+ 関連スキーマ）
|
|
226
|
+
- `spec-common.attributes.jsonc` → `global-attributes.schema.json`
|
|
227
227
|
|
|
228
228
|
## 外部依存パッケージ
|
|
229
229
|
|
package/ARCHITECTURE.md
CHANGED
|
@@ -4,18 +4,18 @@
|
|
|
4
4
|
|
|
5
5
|
`@markuplint/html-spec` is the canonical HTML Living Standard dataset provider for markuplint. It is a pure data package with no TypeScript source code. It contains 177 per-element JSON specification files and 2 common definition files that are processed by `@markuplint/spec-generator` to produce a single consolidated `index.json` (48K+ lines, 1.4MB).
|
|
6
6
|
|
|
7
|
-
During the build, `@markuplint/spec-generator` fetches live data from MDN, W3C ARIA specifications (1.1, 1.2, 1.3), the HTML Living Standard, and SVG specifications, then merges that external data with the hand-authored JSON files. Manual specifications always take precedence over fetched data, ensuring stable, curated definitions while still benefiting from automated enrichment.
|
|
7
|
+
During the build, `@markuplint/spec-generator` fetches live data from MDN, W3C ARIA specifications (1.1, 1.2, 1.3), Graphics ARIA, DPub ARIA, HTML-ARIA mappings, the HTML Living Standard, and SVG specifications, then merges that external data with the hand-authored JSON files. Manual specifications always take precedence over fetched data, ensuring stable, curated definitions while still benefiting from automated enrichment.
|
|
8
8
|
|
|
9
9
|
## Directory Structure
|
|
10
10
|
|
|
11
11
|
```
|
|
12
12
|
src/
|
|
13
|
-
├── spec.a.
|
|
14
|
-
├── spec.abbr.
|
|
13
|
+
├── spec.a.jsonc # <a> element specification
|
|
14
|
+
├── spec.abbr.jsonc # <abbr> element specification
|
|
15
15
|
├── ... (177 element specification files total)
|
|
16
|
-
├── spec.svg_text.
|
|
17
|
-
├── spec-common.attributes.
|
|
18
|
-
└── spec-common.contents.
|
|
16
|
+
├── spec.svg_text.jsonc # <svg:text> element specification
|
|
17
|
+
├── spec-common.attributes.jsonc # 19 global attribute category definitions
|
|
18
|
+
└── spec-common.contents.jsonc # 10 HTML + 19 SVG content model category definitions
|
|
19
19
|
|
|
20
20
|
build.mjs # Build script invoking @markuplint/spec-generator
|
|
21
21
|
index.json # Generated output (48K+ lines, DO NOT EDIT)
|
|
@@ -30,9 +30,9 @@ test/
|
|
|
30
30
|
```mermaid
|
|
31
31
|
flowchart TD
|
|
32
32
|
subgraph sources ["Source Layer"]
|
|
33
|
-
elemSpecs["177 element specs\n(src/spec.*.
|
|
34
|
-
commonAttrs["spec-common.attributes.
|
|
35
|
-
commonContents["spec-common.contents.
|
|
33
|
+
elemSpecs["177 element specs\n(src/spec.*.jsonc)"]
|
|
34
|
+
commonAttrs["spec-common.attributes.jsonc\n(19 global attribute categories)"]
|
|
35
|
+
commonContents["spec-common.contents.jsonc\n(10 HTML + 19 SVG content models)"]
|
|
36
36
|
end
|
|
37
37
|
|
|
38
38
|
subgraph build ["Build Pipeline"]
|
|
@@ -43,6 +43,9 @@ flowchart TD
|
|
|
43
43
|
subgraph external ["External Data Sources"]
|
|
44
44
|
mdn["MDN Web Docs\n(compatibility, descriptions)"]
|
|
45
45
|
aria["W3C ARIA Specs\n(1.1 / 1.2 / 1.3)"]
|
|
46
|
+
graphicsAria["Graphics ARIA"]
|
|
47
|
+
dpubAria["DPub ARIA"]
|
|
48
|
+
htmlAria["HTML-ARIA Mappings"]
|
|
46
49
|
htmlLS["HTML Living Standard\n(elements, attributes)"]
|
|
47
50
|
svg["SVG Specification\n(elements, attributes)"]
|
|
48
51
|
end
|
|
@@ -64,6 +67,9 @@ flowchart TD
|
|
|
64
67
|
|
|
65
68
|
mdn --> specGen
|
|
66
69
|
aria --> specGen
|
|
70
|
+
graphicsAria --> specGen
|
|
71
|
+
dpubAria --> specGen
|
|
72
|
+
htmlAria --> specGen
|
|
67
73
|
htmlLS --> specGen
|
|
68
74
|
svg --> specGen
|
|
69
75
|
|
|
@@ -86,11 +92,11 @@ A sorted list of all URLs fetched during generation. This provides traceability
|
|
|
86
92
|
|
|
87
93
|
Global definitions shared across all element specifications.
|
|
88
94
|
|
|
89
|
-
| Key | Description
|
|
90
|
-
| ---------------- |
|
|
91
|
-
| `#globalAttrs` | 19 global attribute categories defining attributes available on all or specific groups of elements
|
|
92
|
-
| `#aria` | ARIA role and property definitions per specification version (1.1, 1.2, 1.3)
|
|
93
|
-
| `#contentModels` | Content model category macros mapping category names to their member elements
|
|
95
|
+
| Key | Description |
|
|
96
|
+
| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
97
|
+
| `#globalAttrs` | 19 global attribute categories defining attributes available on all or specific groups of elements |
|
|
98
|
+
| `#aria` | ARIA role and property definitions per specification version (1.1, 1.2, 1.3), plus Graphics ARIA and DPub ARIA roles |
|
|
99
|
+
| `#contentModels` | Content model category macros mapping category names to their member elements |
|
|
94
100
|
|
|
95
101
|
**Global Attribute Categories** (`#globalAttrs`):
|
|
96
102
|
|
|
@@ -127,14 +133,14 @@ An array of element specifications. Each entry defines a single HTML or SVG elem
|
|
|
127
133
|
|
|
128
134
|
## Core Components
|
|
129
135
|
|
|
130
|
-
| Component | Files
|
|
131
|
-
| --------------------- |
|
|
132
|
-
| Source Specifications | 177 `src/spec.*.
|
|
133
|
-
| Common Definitions | `spec-common.attributes.
|
|
134
|
-
| Build System | `build.mjs`
|
|
135
|
-
| Generated Output | `index.json`
|
|
136
|
-
| Type Declarations | `index.d.ts`
|
|
137
|
-
| Schema Validation | `test/structure.spec.mjs`
|
|
136
|
+
| Component | Files | Purpose |
|
|
137
|
+
| --------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
|
|
138
|
+
| Source Specifications | 177 `src/spec.*.jsonc` files | Per-element definitions: content models, attributes, ARIA mappings |
|
|
139
|
+
| Common Definitions | `spec-common.attributes.jsonc`, `spec-common.contents.jsonc` | Shared global attribute categories and content model category macros |
|
|
140
|
+
| Build System | `build.mjs` | Invokes `@markuplint/spec-generator` to merge sources with external data |
|
|
141
|
+
| Generated Output | `index.json` | Single consolidated dataset consumed by downstream packages |
|
|
142
|
+
| Type Declarations | `index.d.ts` | Re-exports `Cites`, `ElementSpec`, `SpecDefs` from `@markuplint/ml-spec` |
|
|
143
|
+
| Schema Validation | `test/structure.spec.mjs` | Ajv-based validation of generated output against `@markuplint/ml-spec` schemas |
|
|
138
144
|
|
|
139
145
|
## External Dependencies
|
|
140
146
|
|
|
@@ -181,7 +187,7 @@ flowchart LR
|
|
|
181
187
|
### Upstream
|
|
182
188
|
|
|
183
189
|
- **`@markuplint/ml-spec`** provides the TypeScript type definitions (`MLMLSpec`, `ElementSpec`, `SpecDefs`) and JSON schemas used to validate the generated output. The `index.d.ts` re-exports these types.
|
|
184
|
-
- **`@markuplint/spec-generator`** is the build tool invoked by `build.mjs`. It reads the source JSON files, fetches live data from MDN Web Docs, W3C ARIA specifications (versions 1.1, 1.2, 1.3), the HTML Living Standard, and SVG specifications, then merges everything into `index.json`.
|
|
190
|
+
- **`@markuplint/spec-generator`** is the build tool invoked by `build.mjs`. It reads the source JSON files, fetches live data from MDN Web Docs, W3C ARIA specifications (versions 1.1, 1.2, 1.3), Graphics ARIA, DPub ARIA, HTML-ARIA mappings, the HTML Living Standard, and SVG specifications, then merges everything into `index.json`.
|
|
185
191
|
|
|
186
192
|
### Downstream
|
|
187
193
|
|
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,28 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
5
|
|
|
6
|
+
# [5.0.0-alpha.1](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.0...v5.0.0-alpha.1) (2026-02-22)
|
|
7
|
+
|
|
8
|
+
### Features
|
|
9
|
+
|
|
10
|
+
- **html-spec:** add conditional aside role mapping for ARIA 1.3 ([f3315b7](https://github.com/markuplint/markuplint/commit/f3315b7352d17308c8d6edfc0831da3cb33a0922))
|
|
11
|
+
|
|
12
|
+
# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
|
|
13
|
+
|
|
14
|
+
### Bug Fixes
|
|
15
|
+
|
|
16
|
+
- **html-spec:** add aria-valuenow restrictions and missing alt fields ([b5af2b5](https://github.com/markuplint/markuplint/commit/b5af2b57238e40c4bf807fb968b4309871709046)), closes [#3214](https://github.com/markuplint/markuplint/issues/3214) [#2465](https://github.com/markuplint/markuplint/issues/2465)
|
|
17
|
+
- **html-spec:** add missing dpub-aria source URL to generated spec data ([0797e83](https://github.com/markuplint/markuplint/commit/0797e832a4b1c6ce80b1dc32529228db5a3e07cb))
|
|
18
|
+
- **html-spec:** fix optgroup selector and remove stale comment ([f6bcd7f](https://github.com/markuplint/markuplint/commit/f6bcd7f7036516e236117c34349085986efacfc3))
|
|
19
|
+
- **html-spec:** mark input switch attribute as non-standard ([5b28f44](https://github.com/markuplint/markuplint/commit/5b28f447b31f38420b8e0cc91827f66e0fe4331d))
|
|
20
|
+
- **html-spec:** update ARIA role descriptions for combobox, tab, and tabpanel ([4b8e5cc](https://github.com/markuplint/markuplint/commit/4b8e5cc69c9e2bd1c83b8dbf0a991324263a7156))
|
|
21
|
+
- **html-spec:** update as attribute enum values based on WHATWG spec changes ([f10bd77](https://github.com/markuplint/markuplint/commit/f10bd77e647d37b41a0ee99b1adfe4fd0cb42831)), closes [whatwg/html#10212](https://github.com/whatwg/html/issues/10212) [whatwg/html#11981](https://github.com/whatwg/html/issues/11981) [#1987](https://github.com/markuplint/markuplint/issues/1987)
|
|
22
|
+
|
|
23
|
+
### Features
|
|
24
|
+
|
|
25
|
+
- **html-spec:** add 41 DPub ARIA roles to generated spec data ([a98b9e5](https://github.com/markuplint/markuplint/commit/a98b9e53b5d96b700e66291dd643534f7df5cbaf))
|
|
26
|
+
- **html-spec:** require href or imagesrcset on link element ([e6a2631](https://github.com/markuplint/markuplint/commit/e6a26318ed8e4be9ba4e81884eb0b879a816efb5)), closes [#717](https://github.com/markuplint/markuplint/issues/717)
|
|
27
|
+
|
|
6
28
|
# [4.17.0](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.16.1...@markuplint/html-spec@4.17.0) (2026-02-10)
|
|
7
29
|
|
|
8
30
|
### Bug Fixes
|
package/README.md
CHANGED
|
@@ -35,14 +35,14 @@ Core packages (Application Layer)
|
|
|
35
35
|
|
|
36
36
|
### Source Files (EDIT THESE)
|
|
37
37
|
|
|
38
|
-
- **`src/spec.*.
|
|
39
|
-
- **`src/spec-common.attributes.
|
|
40
|
-
- **`src/spec-common.contents.
|
|
38
|
+
- **`src/spec.*.jsonc`** - Individual element specifications (177 files)
|
|
39
|
+
- **`src/spec-common.attributes.jsonc`** - Global attribute category definitions (19 categories)
|
|
40
|
+
- **`src/spec-common.contents.jsonc`** - Content model category macros (HTML 10 + SVG 19 categories)
|
|
41
41
|
|
|
42
42
|
### Build System
|
|
43
43
|
|
|
44
44
|
- **`build.mjs`** - Generation script that invokes `@markuplint/spec-generator`
|
|
45
|
-
- Fetches live data from MDN, W3C ARIA specs,
|
|
45
|
+
- Fetches live data from MDN, W3C ARIA specs, Graphics ARIA, DPub ARIA, HTML-ARIA mappings, HTML Living Standard, and SVG specs
|
|
46
46
|
|
|
47
47
|
## Relationship to @markuplint/ml-spec
|
|
48
48
|
|
package/SKILL.md
CHANGED
|
@@ -77,9 +77,9 @@ content models:
|
|
|
77
77
|
|
|
78
78
|
1. Identify the affected elements
|
|
79
79
|
2. Determine which source files need updating:
|
|
80
|
-
- `src/spec.<element>.
|
|
81
|
-
- `src/spec-common.contents.
|
|
82
|
-
- `src/spec-common.attributes.
|
|
80
|
+
- `src/spec.<element>.jsonc` for element-specific changes
|
|
81
|
+
- `src/spec-common.contents.jsonc` for content model category changes
|
|
82
|
+
- `src/spec-common.attributes.jsonc` for global attribute changes
|
|
83
83
|
- In rare cases, `@markuplint/ml-spec` schemas or types may need updating
|
|
84
84
|
3. Make the changes, referencing the authoritative specification:
|
|
85
85
|
- HTML Living Standard: https://html.spec.whatwg.org/multipage/
|
|
@@ -93,13 +93,13 @@ content models:
|
|
|
93
93
|
|
|
94
94
|
### Step 3b: Idempotency verification (when spec files are modified)
|
|
95
95
|
|
|
96
|
-
When you modify `src/spec.*.
|
|
96
|
+
When you modify `src/spec.*.jsonc` files, verify that your changes produce stable output
|
|
97
97
|
before committing. This ensures the generated `index.json` does not contain unintended
|
|
98
98
|
drift:
|
|
99
99
|
|
|
100
100
|
```bash
|
|
101
101
|
# 1. Stage spec files and index.json
|
|
102
|
-
git add packages/@markuplint/html-spec/src/spec.*.
|
|
102
|
+
git add packages/@markuplint/html-spec/src/spec.*.jsonc packages/@markuplint/html-spec/index.json
|
|
103
103
|
|
|
104
104
|
# 2. Regenerate
|
|
105
105
|
yarn up:gen
|
|
@@ -128,15 +128,15 @@ Stage and commit `index.json` and any modified `src/` files.
|
|
|
128
128
|
|
|
129
129
|
Add a new HTML element specification. Follow recipe #1 in `docs/maintenance.md`.
|
|
130
130
|
|
|
131
|
-
1. Read `src/spec.a.
|
|
132
|
-
2. Create `src/spec.<name>.
|
|
131
|
+
1. Read `src/spec.a.jsonc` as a reference for a typical element
|
|
132
|
+
2. Create `src/spec.<name>.jsonc` with required fields:
|
|
133
133
|
- `contentModel` with `contents`
|
|
134
134
|
- `globalAttrs` (`#HTMLGlobalAttrs`, `#GlobalEventAttrs`, `#ARIAAttrs` set to `true`)
|
|
135
135
|
- `attributes` (element-specific, can be `{}`)
|
|
136
136
|
- `aria` with `implicitRole` and `permittedRoles`
|
|
137
137
|
3. Add spec URL comments at the top (`//` format)
|
|
138
138
|
4. **Cross-package step**: If the element belongs to content categories (flow, phrasing, etc.),
|
|
139
|
-
add it to the appropriate categories in `src/spec-common.contents.
|
|
139
|
+
add it to the appropriate categories in `src/spec-common.contents.jsonc`.
|
|
140
140
|
Without this, `@markuplint/rules`' `permitted-contents` rule will flag the element
|
|
141
141
|
as invalid content in parent elements that allow those categories.
|
|
142
142
|
5. Regenerate: `yarn workspace @markuplint/html-spec run gen`
|
|
@@ -147,8 +147,8 @@ Add a new HTML element specification. Follow recipe #1 in `docs/maintenance.md`.
|
|
|
147
147
|
|
|
148
148
|
Add a new SVG element specification. Follow recipe #3 in `docs/maintenance.md`.
|
|
149
149
|
|
|
150
|
-
1. Read `src/spec.svg_circle.
|
|
151
|
-
2. Create `src/spec.svg_<name>.
|
|
150
|
+
1. Read `src/spec.svg_circle.jsonc` as a reference for a typical SVG element
|
|
151
|
+
2. Create `src/spec.svg_<name>.jsonc` (the `svg_` prefix maps to namespace `svg:<name>`)
|
|
152
152
|
3. Use SVG-specific global attribute categories (`#SVGCoreAttrs`, `#SVGPresentationAttrs`)
|
|
153
153
|
4. For ARIA, use AAM references: `{ "core-aam": true, "graphics-aam": true }`
|
|
154
154
|
5. Regenerate: `yarn workspace @markuplint/html-spec run gen`
|
|
@@ -158,14 +158,14 @@ Add a new SVG element specification. Follow recipe #3 in `docs/maintenance.md`.
|
|
|
158
158
|
|
|
159
159
|
Add an attribute to an element. Follow recipe #2 in `docs/maintenance.md`.
|
|
160
160
|
|
|
161
|
-
1. Open `src/spec.<element>.
|
|
161
|
+
1. Open `src/spec.<element>.jsonc`
|
|
162
162
|
2. Add the attribute entry to the `attributes` object. See `docs/element-spec-format.md`
|
|
163
163
|
for the full attribute definition format. Common patterns:
|
|
164
164
|
- Simple typed attribute: `"href": { "type": "URL" }`
|
|
165
165
|
- Conditional attribute: `"accept": { "type": ..., "condition": "[type='file' i]" }`
|
|
166
166
|
- Boolean attribute: `"disabled": { "type": "Boolean" }`
|
|
167
167
|
3. For a **global** attribute (applies to all elements), edit
|
|
168
|
-
`src/spec-common.attributes.
|
|
168
|
+
`src/spec-common.attributes.jsonc` instead, adding the attribute to the
|
|
169
169
|
appropriate category (e.g., `#HTMLGlobalAttrs`)
|
|
170
170
|
4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
|
|
171
171
|
5. Verify the attribute appears in `index.json` with correct metadata
|
|
@@ -175,9 +175,9 @@ Add an attribute to an element. Follow recipe #2 in `docs/maintenance.md`.
|
|
|
175
175
|
|
|
176
176
|
Remove an attribute from an element's manual specification.
|
|
177
177
|
|
|
178
|
-
1. Open `src/spec.<element>.
|
|
178
|
+
1. Open `src/spec.<element>.jsonc`
|
|
179
179
|
2. Remove the attribute entry from the `attributes` object
|
|
180
|
-
3. For a **global** attribute, edit `src/spec-common.attributes.
|
|
180
|
+
3. For a **global** attribute, edit `src/spec-common.attributes.jsonc` instead
|
|
181
181
|
4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
|
|
182
182
|
5. Verify the attribute no longer appears in `index.json` for the element.
|
|
183
183
|
**Note**: If the attribute also exists in MDN data, it will still appear in
|
|
@@ -195,7 +195,7 @@ There are two approaches:
|
|
|
195
195
|
Add the element name to the `obsoleteList` array in
|
|
196
196
|
`packages/@markuplint/spec-generator/src/html-elements.ts`
|
|
197
197
|
- **Via manual spec file**: Set `"obsolete": true` in the element's
|
|
198
|
-
`src/spec.<element>.
|
|
198
|
+
`src/spec.<element>.jsonc`
|
|
199
199
|
|
|
200
200
|
Obsolete elements automatically get:
|
|
201
201
|
|
|
@@ -213,7 +213,7 @@ After making the change:
|
|
|
213
213
|
|
|
214
214
|
Mark an attribute as deprecated in an element's specification.
|
|
215
215
|
|
|
216
|
-
1. Open `src/spec.<element>.
|
|
216
|
+
1. Open `src/spec.<element>.jsonc`
|
|
217
217
|
2. Add `"deprecated": true` to the attribute definition:
|
|
218
218
|
```json
|
|
219
219
|
"align": {
|
|
@@ -222,7 +222,7 @@ Mark an attribute as deprecated in an element's specification.
|
|
|
222
222
|
```
|
|
223
223
|
If the attribute already has other fields (`type`, `condition`, etc.),
|
|
224
224
|
simply add `"deprecated": true` alongside them.
|
|
225
|
-
3. For a **global** attribute, edit `src/spec-common.attributes.
|
|
225
|
+
3. For a **global** attribute, edit `src/spec-common.attributes.jsonc` instead
|
|
226
226
|
4. Regenerate: `yarn workspace @markuplint/html-spec run gen`
|
|
227
227
|
5. Verify the attribute shows `"deprecated": true` in `index.json`
|
|
228
228
|
6. Run tests: `yarn workspace @markuplint/html-spec run test`
|
|
@@ -239,7 +239,7 @@ These boolean flags indicate the standardization status of an attribute:
|
|
|
239
239
|
| `deprecated` | The attribute is obsolete and should not be used |
|
|
240
240
|
| `nonStandard` | The attribute is not part of any standard |
|
|
241
241
|
|
|
242
|
-
1. Open `src/spec.<element>.
|
|
242
|
+
1. Open `src/spec.<element>.jsonc` (or `src/spec-common.attributes.jsonc` for globals)
|
|
243
243
|
2. Add, change, or remove the flag on the target attribute:
|
|
244
244
|
```json
|
|
245
245
|
"attributionsrc": {
|
|
@@ -293,10 +293,10 @@ These boolean flags indicate the standardization status of an attribute:
|
|
|
293
293
|
|
|
294
294
|
Verify cross-package consistency between `@markuplint/html-spec` and related packages.
|
|
295
295
|
|
|
296
|
-
1. **Content model categories**: Verify that category names in `src/spec-common.contents.
|
|
296
|
+
1. **Content model categories**: Verify that category names in `src/spec-common.contents.jsonc`
|
|
297
297
|
match the `Category` enum in `@markuplint/ml-spec/schemas/content-models.schema.json`
|
|
298
298
|
2. **Element membership**: Verify that elements listed in content categories have
|
|
299
|
-
corresponding `src/spec.<element>.
|
|
299
|
+
corresponding `src/spec.<element>.jsonc` files and consistent `contentModel` definitions
|
|
300
300
|
3. **Attribute types**: Check that attribute type references (e.g., `"URL"`, `"<color>"`)
|
|
301
301
|
exist in `@markuplint/types`' definitions registry
|
|
302
302
|
4. **Schema validation**: Run `yarn workspace @markuplint/html-spec run test` to validate
|
|
@@ -340,7 +340,7 @@ Spec data changes propagate to multiple test suites. Always run `yarn test`
|
|
|
340
340
|
## Rules
|
|
341
341
|
|
|
342
342
|
1. **`index.json` is generated -- never edit it directly.** Always modify `src/` files and regenerate.
|
|
343
|
-
2. **Manual spec data takes precedence over MDN data.** Attributes defined in `src/spec.*.
|
|
343
|
+
2. **Manual spec data takes precedence over MDN data.** Attributes defined in `src/spec.*.jsonc` override same-named MDN-sourced attributes. Use this to correct inaccurate MDN data.
|
|
344
344
|
3. **Minor MDN description changes should be committed as-is.** Do not attempt to override cosmetic upstream improvements.
|
|
345
345
|
4. **Content model category membership is critical.** A missing element in a category causes `permitted-contents` rule false positives in downstream linting.
|
|
346
346
|
5. **Always run tests after changes.** Schema validation catches structural errors before they propagate to downstream packages.
|
|
@@ -18,9 +18,9 @@
|
|
|
18
18
|
```mermaid
|
|
19
19
|
flowchart TD
|
|
20
20
|
subgraph inputs ["ソースファイル（html-spec）"]
|
|
21
|
-
specFiles["src/spec.*.
|
|
22
|
-
commonAttrs["src/spec-common.attributes.
|
|
23
|
-
commonContents["src/spec-common.contents.
|
|
21
|
+
specFiles["src/spec.*.jsonc\n（177 要素ファイル）"]
|
|
22
|
+
commonAttrs["src/spec-common.attributes.jsonc\n（19 グローバル属性カテゴリ）"]
|
|
23
|
+
commonContents["src/spec-common.contents.jsonc\n（コンテンツモデルマクロ）"]
|
|
24
24
|
end
|
|
25
25
|
|
|
26
26
|
subgraph build ["ビルド"]
|
|
@@ -60,9 +60,9 @@ import { main } from '@markuplint/spec-generator';
|
|
|
60
60
|
|
|
61
61
|
await main({
|
|
62
62
|
outputFilePath: path.resolve(import.meta.dirname, 'index.json'),
|
|
63
|
-
htmlFilePattern: path.resolve(import.meta.dirname, 'src', 'spec.*.
|
|
64
|
-
commonAttrsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.attributes.
|
|
65
|
-
commonContentsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.contents.
|
|
63
|
+
htmlFilePattern: path.resolve(import.meta.dirname, 'src', 'spec.*.jsonc'),
|
|
64
|
+
commonAttrsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.attributes.jsonc'),
|
|
65
|
+
commonContentsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.contents.jsonc'),
|
|
66
66
|
});
|
|
67
67
|
```
|
|
68
68
|
|
|
@@ -108,7 +108,7 @@ spec-generator の内部アーキテクチャ（スクレイピング、キャ
|
|
|
108
108
|
|
|
109
109
|
- **手動データが常に優先** -- MDN スクレイピングデータを上書きする
|
|
110
110
|
- `attributes` は、手動仕様に同名の属性がない場合のみ MDN データが追加される
|
|
111
|
-
- `contentModel` と `aria` はスクレイピングされない -- `src/spec.*.
|
|
111
|
+
- `contentModel` と `aria` はスクレイピングされない -- `src/spec.*.jsonc` からのみ取得
|
|
112
112
|
- `cite` URL はデフォルトで MDN ページだが、要素ごとにオーバーライド可能
|
|
113
113
|
|
|
114
114
|
**属性マージの詳細動作:**
|
|
@@ -140,9 +140,9 @@ spec-generator の内部アーキテクチャ（スクレイピング、キャ
|
|
|
140
140
|
```
|
|
141
141
|
|
|
142
142
|
- `cites` -- フェッチされた全 URL（トレーサビリティ用）
|
|
143
|
-
- `def["#globalAttrs"]` -- `spec-common.attributes.
|
|
143
|
+
- `def["#globalAttrs"]` -- `spec-common.attributes.jsonc` から
|
|
144
144
|
- `def["#aria"]` -- W3C ARIA 仕様からスクレイピング
|
|
145
|
-
- `def["#contentModels"]` -- `spec-common.contents.
|
|
145
|
+
- `def["#contentModels"]` -- `spec-common.contents.jsonc` から
|
|
146
146
|
- `specs` -- マージ済み要素仕様の配列
|
|
147
147
|
|
|
148
148
|
## ビルドコマンド
|
package/docs/build-pipeline.md
CHANGED
|
@@ -18,9 +18,9 @@ The build is network-dependent because external data is fetched live. Expect sev
|
|
|
18
18
|
```mermaid
|
|
19
19
|
flowchart TD
|
|
20
20
|
subgraph inputs ["Source Files (html-spec)"]
|
|
21
|
-
specFiles["src/spec.*.
|
|
22
|
-
commonAttrs["src/spec-common.attributes.
|
|
23
|
-
commonContents["src/spec-common.contents.
|
|
21
|
+
specFiles["src/spec.*.jsonc\n(177 element files)"]
|
|
22
|
+
commonAttrs["src/spec-common.attributes.jsonc\n(19 global attribute categories)"]
|
|
23
|
+
commonContents["src/spec-common.contents.jsonc\n(content model macros)"]
|
|
24
24
|
end
|
|
25
25
|
|
|
26
26
|
subgraph build ["Build"]
|
|
@@ -60,9 +60,9 @@ import { main } from '@markuplint/spec-generator';
|
|
|
60
60
|
|
|
61
61
|
await main({
|
|
62
62
|
outputFilePath: path.resolve(import.meta.dirname, 'index.json'),
|
|
63
|
-
htmlFilePattern: path.resolve(import.meta.dirname, 'src', 'spec.*.
|
|
64
|
-
commonAttrsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.attributes.
|
|
65
|
-
commonContentsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.contents.
|
|
63
|
+
htmlFilePattern: path.resolve(import.meta.dirname, 'src', 'spec.*.jsonc'),
|
|
64
|
+
commonAttrsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.attributes.jsonc'),
|
|
65
|
+
commonContentsFilePath: path.resolve(import.meta.dirname, 'src', 'spec-common.contents.jsonc'),
|
|
66
66
|
});
|
|
67
67
|
```
|
|
68
68
|
|
|
@@ -108,7 +108,7 @@ Key points:
|
|
|
108
108
|
|
|
109
109
|
- **Manual data always takes precedence** over MDN-scraped data
|
|
110
110
|
- For `attributes`, MDN-scraped attributes are added only when the manual spec does not define that attribute name
|
|
111
|
-
- Content models and ARIA mappings are never scraped -- they come exclusively from your `src/spec.*.
|
|
111
|
+
- Content models and ARIA mappings are never scraped -- they come exclusively from your `src/spec.*.jsonc` files
|
|
112
112
|
- The `cite` URL defaults to the MDN page but can be overridden per element
|
|
113
113
|
|
|
114
114
|
**Attribute merge behavior in detail:**
|
|
@@ -141,9 +141,9 @@ The `index.json` follows the `ExtendedSpec` type from `@markuplint/ml-spec`:
|
|
|
141
141
|
```
|
|
142
142
|
|
|
143
143
|
- `cites` -- all fetched URLs, for traceability
|
|
144
|
-
- `def["#globalAttrs"]` -- from `spec-common.attributes.
|
|
144
|
+
- `def["#globalAttrs"]` -- from `spec-common.attributes.jsonc`
|
|
145
145
|
- `def["#aria"]` -- scraped from W3C ARIA specifications
|
|
146
|
-
- `def["#contentModels"]` -- from `spec-common.contents.
|
|
146
|
+
- `def["#contentModels"]` -- from `spec-common.contents.jsonc`
|
|
147
147
|
- `specs` -- merged element specifications array
|
|
148
148
|
|
|
149
149
|
## Build Commands
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 要素仕様フォーマット
|
|
2
2
|
|
|
3
|
-
`@markuplint/html-spec` パッケージにおける要素仕様 JSON ファイルの包括的なリファレンスガイドです。各 `src/spec.*.
|
|
3
|
+
`@markuplint/html-spec` パッケージにおける要素仕様 JSON ファイルの包括的なリファレンスガイドです。各 `src/spec.*.jsonc` ファイルは 1 つの HTML または SVG 要素の仕様を定義し、コンテンツモデル、属性、ARIA マッピングなどの情報を含みます。
|
|
4
4
|
|
|
5
5
|
## ファイル命名規則
|
|
6
6
|
|
|
@@ -9,38 +9,38 @@
|
|
|
9
9
|
ファイル名パターン: `src/spec.<tag>.json`
|
|
10
10
|
|
|
11
11
|
```
|
|
12
|
-
spec.div.
|
|
13
|
-
spec.table.
|
|
14
|
-
spec.input.
|
|
15
|
-
spec.a.
|
|
16
|
-
spec.p.
|
|
12
|
+
spec.div.jsonc # <div> 要素
|
|
13
|
+
spec.table.jsonc # <table> 要素
|
|
14
|
+
spec.input.jsonc # <input> 要素
|
|
15
|
+
spec.a.jsonc # <a> 要素
|
|
16
|
+
spec.p.jsonc # <p> 要素
|
|
17
17
|
```
|
|
18
18
|
|
|
19
19
|
タグ名はそのままファイル名に使用されます。
|
|
20
20
|
|
|
21
21
|
### SVG 要素
|
|
22
22
|
|
|
23
|
-
ファイル名パターン: `src/spec.svg_<local>.
|
|
23
|
+
ファイル名パターン: `src/spec.svg_<local>.jsonc`
|
|
24
24
|
|
|
25
25
|
```
|
|
26
|
-
spec.svg_text.
|
|
27
|
-
spec.svg_circle.
|
|
28
|
-
spec.svg_rect.
|
|
29
|
-
spec.svg_path.
|
|
26
|
+
spec.svg_text.jsonc # <svg:text> 要素
|
|
27
|
+
spec.svg_circle.jsonc # <svg:circle> 要素
|
|
28
|
+
spec.svg_rect.jsonc # <svg:rect> 要素
|
|
29
|
+
spec.svg_path.jsonc # <svg:path> 要素
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
ファイル名のプレフィックス `svg_` から、要素名は `svg:<local>` として推論されます（例: `spec.svg_text.
|
|
32
|
+
ファイル名のプレフィックス `svg_` から、要素名は `svg:<local>` として推論されます（例: `spec.svg_text.jsonc` は `svg:text` に対応）。
|
|
33
33
|
|
|
34
34
|
### 共通定義ファイル
|
|
35
35
|
|
|
36
|
-
| ファイル
|
|
37
|
-
|
|
|
38
|
-
| `spec-common.attributes.
|
|
39
|
-
| `spec-common.contents.
|
|
36
|
+
| ファイル | 内容 |
|
|
37
|
+
| ------------------------------ | -------------------------------------------------- |
|
|
38
|
+
| `spec-common.attributes.jsonc` | グローバル属性カテゴリ定義（19 カテゴリ） |
|
|
39
|
+
| `spec-common.contents.jsonc` | コンテンツモデルカテゴリマクロ（HTML 10 + SVG 19） |
|
|
40
40
|
|
|
41
41
|
## 要素仕様の構造
|
|
42
42
|
|
|
43
|
-
各仕様ファイルは JSON
|
|
43
|
+
各仕様ファイルは JSON オブジェクトです。JSONC 形式（`.jsonc`）を使用しており、`jsonc-parser` によるコメント（`//` 形式）に対応しています。ファイル先頭に仕様の参照 URL を記載するのが慣例です。
|
|
44
44
|
|
|
45
45
|
トップレベルフィールドは以下の 4 つです。
|
|
46
46
|
|
|
@@ -116,7 +116,7 @@ spec.svg_path.json # <svg:path> 要素
|
|
|
116
116
|
|
|
117
117
|
- **スキーマ検証** -- `@markuplint/ml-spec` の `content-models.schema.json` がコンテンツモデルパターン（`require`、`optional`、`oneOrMore`、`zeroOrMore`、`choice`、`transparent`）の有効な構造を定義しています。テスト時にソース JSON ファイルがこのスキーマに対して検証されます。
|
|
118
118
|
- **TypeScript 型** -- `@markuplint/ml-spec` がスキーマから `ContentModel`、`PermittedContentPattern`、`Category` 等の型を自動生成し（`types/permitted-structures.ts`）、コードベース全体で型安全なアクセスを提供します。
|
|
119
|
-
- **ランタイムアルゴリズム** -- `@markuplint/ml-spec` の `getContentModel()` が条件付きコンテンツモデルを実行時に評価し、`contentModelCategoryToTagNames()` がカテゴリ名（例: `#flow`）を本パッケージの `spec-common.contents.
|
|
119
|
+
- **ランタイムアルゴリズム** -- `@markuplint/ml-spec` の `getContentModel()` が条件付きコンテンツモデルを実行時に評価し、`contentModelCategoryToTagNames()` がカテゴリ名（例: `#flow`）を本パッケージの `spec-common.contents.jsonc` の `def["#contentModels"]` を用いて具体的な要素リストに解決します。
|
|
120
120
|
- **リントルール** -- `@markuplint/rules` の `permitted-contents` ルールが子要素をコンテンツモデルパターンに対して検証し、`no-empty-palpable-content` ルールが `#palpable` カテゴリデータを使用して空のパルパブル要素を検出します。
|
|
121
121
|
|
|
122
122
|
---
|
|
@@ -278,7 +278,7 @@ spec.svg_path.json # <svg:path> 要素
|
|
|
278
278
|
（例: 完全に廃止された要素のレガシーなプレゼンテーション属性）。実際の動作として、
|
|
279
279
|
`deprecated` な属性は通常ブラウザで動作するが、`obsolete` な属性は動作しない場合がある。
|
|
280
280
|
|
|
281
|
-
**フラグの優先順位（仕様ファイル > MDN）:** 手動仕様ファイル（`src/spec.*.
|
|
281
|
+
**フラグの優先順位（仕様ファイル > MDN）:** 手動仕様ファイル（`src/spec.*.jsonc`）で
|
|
282
282
|
フラグを設定した場合、MDN スクレイピングの値よりも優先される。これにより、MDN データが
|
|
283
283
|
不正確または仕様に追いついていない場合を修正できる。MDN のフラグは、手動仕様に属性定義が
|
|
284
284
|
ない場合、または該当フラグが設定されていない場合にのみ使用される。
|
|
@@ -520,7 +520,7 @@ ARIA 仕様のバージョンごとに異なるマッピングを定義できま
|
|
|
520
520
|
|
|
521
521
|
## コンテンツモデルカテゴリ
|
|
522
522
|
|
|
523
|
-
`spec-common.contents.
|
|
523
|
+
`spec-common.contents.jsonc` に定義されるカテゴリマクロです。コンテンツモデルパターンのセレクタで `:model(<category>)` の形式で参照されます。
|
|
524
524
|
|
|
525
525
|
### HTML カテゴリ（10）
|
|
526
526
|
|
|
@@ -563,7 +563,7 @@ ARIA 仕様のバージョンごとに異なるマッピングを定義できま
|
|
|
563
563
|
|
|
564
564
|
## 共通定義ファイル
|
|
565
565
|
|
|
566
|
-
### `spec-common.attributes.
|
|
566
|
+
### `spec-common.attributes.jsonc`
|
|
567
567
|
|
|
568
568
|
19 個のグローバル属性カテゴリの定義ファイルです。各カテゴリはキーに `#` プレフィックス付きの名前を持ち、値は属性名から属性定義へのマッピングです。
|
|
569
569
|
|
|
@@ -603,7 +603,7 @@ ARIA 仕様のバージョンごとに異なるマッピングを定義できま
|
|
|
603
603
|
|
|
604
604
|
要素仕様の `globalAttrs` フィールドでカテゴリ名を参照し、`true`（全属性）、`false`（除外）、または文字列配列（選択的インクルード）で使用方法を指定します。
|
|
605
605
|
|
|
606
|
-
### `spec-common.contents.
|
|
606
|
+
### `spec-common.contents.jsonc`
|
|
607
607
|
|
|
608
608
|
コンテンツモデルカテゴリマクロの定義ファイルです。`models` キーの下にカテゴリ名と所属要素の配列が定義されます。
|
|
609
609
|
|