@markuplint/html-spec 4.14.2 → 4.16.0
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/CHANGELOG.md +36 -0
- package/README.md +317 -0
- package/index.d.ts +10 -4
- package/index.js +1 -1
- package/index.json +592 -771
- package/package.json +7 -8
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,42 @@
|
|
|
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
|
+
# [4.16.0](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.15.0...@markuplint/html-spec@4.16.0) (2025-08-24)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
### Features
|
|
10
|
+
|
|
11
|
+
* **html-spec:** implement link type definitions for rel attributes ([0bfa05f](https://github.com/markuplint/markuplint/commit/0bfa05fa39fbcff99e237eb628e89ea2090abd92))
|
|
12
|
+
* **html-spec:** update element references for new MDN URL structure ([452eebb](https://github.com/markuplint/markuplint/commit/452eebb9a4e7d75aca9ff15ee023935206ae237e))
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
# [4.15.0](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.14.2...@markuplint/html-spec@4.15.0) (2025-08-13)
|
|
19
|
+
|
|
20
|
+
### Bug Fixes
|
|
21
|
+
|
|
22
|
+
- **html-spec:** format attribute value types with proper spacing ([b726ab9](https://github.com/markuplint/markuplint/commit/b726ab97faeee186e0f05f6690de338d7182a060))
|
|
23
|
+
- **html-spec:** update img src/srcset attributes to be mutually required ([1a9a611](https://github.com/markuplint/markuplint/commit/1a9a61102468407ef254e970c2903a69d9ec6465))
|
|
24
|
+
|
|
25
|
+
### Features
|
|
26
|
+
|
|
27
|
+
- **html-spec:** add compact attribute to dl element ([936aa24](https://github.com/markuplint/markuplint/commit/936aa24ebc4f1e6122a167466ccd4c63025e8ca2))
|
|
28
|
+
- **html-spec:** add compact attribute to menu element ([d4c16f8](https://github.com/markuplint/markuplint/commit/d4c16f89fe1f3a8acb08e3e83cb23e260c017ec6))
|
|
29
|
+
- **html-spec:** add compact attribute to ol element ([a19785b](https://github.com/markuplint/markuplint/commit/a19785b2af45b6ceb65a66b8ef1162b385b15684))
|
|
30
|
+
- **html-spec:** add fetchpriority attribute to SVG script element ([2669d23](https://github.com/markuplint/markuplint/commit/2669d238e0496c5c57b2ca9182685db420312103))
|
|
31
|
+
- **html-spec:** add mask-type attribute to SVG mask element ([9e27e27](https://github.com/markuplint/markuplint/commit/9e27e27eae2166e99cb124725a299c317a1736d9))
|
|
32
|
+
- **html-spec:** remove form attribute from meter element ([1cee2cb](https://github.com/markuplint/markuplint/commit/1cee2cb54f18e38c8ec652ddfd5f382e757eb1b4))
|
|
33
|
+
- **html-spec:** remove the `cursor` SVG element ([43d224f](https://github.com/markuplint/markuplint/commit/43d224f598a0735da95f5754bb1c5577eb091b2a))
|
|
34
|
+
- **html-spec:** remove the `khern` SVG element ([4c05a01](https://github.com/markuplint/markuplint/commit/4c05a010f33100d912d851731eb689b938b0be99))
|
|
35
|
+
- **html-spec:** remove the `missing` SVG element ([c66f316](https://github.com/markuplint/markuplint/commit/c66f316210e0fc185be8c1fe3d33798ed0492b4d))
|
|
36
|
+
- **html-spec:** remove the `tref` SVG element ([520c81f](https://github.com/markuplint/markuplint/commit/520c81f4e391486feea574e99e163faf3b129601))
|
|
37
|
+
- **html-spec:** remove the `vkern` SVG element ([aadd4cc](https://github.com/markuplint/markuplint/commit/aadd4cc91bb6622c64bcb1b1d5beff9759bdbbb6))
|
|
38
|
+
- **html-spec:** update accessibleNameRequired for specific roles ([4e79515](https://github.com/markuplint/markuplint/commit/4e79515a86bd488cb2a8156ad11fcb9a9967453e))
|
|
39
|
+
- **html-spec:** update descriptions for specific roles ([f018270](https://github.com/markuplint/markuplint/commit/f018270b0d3a301899a7a66c22d4c7ed9c1199fe))
|
|
40
|
+
- **html-spec:** update tree role required owned elements based on ARIA spec change ([0e681bb](https://github.com/markuplint/markuplint/commit/0e681bb686869c01e33a67dd65445ff4dc0c1b1c))
|
|
41
|
+
|
|
6
42
|
## [4.14.2](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.14.1...@markuplint/html-spec@4.14.2) (2025-04-13)
|
|
7
43
|
|
|
8
44
|
**Note:** Version bump only for package @markuplint/html-spec
|
package/README.md
CHANGED
|
@@ -2,6 +2,294 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@markuplint/html-spec)
|
|
4
4
|
|
|
5
|
+
**Canonical HTML Living Standard dataset provider with automated external data enrichment.**
|
|
6
|
+
|
|
7
|
+
This package provides the consolidated HTML element specification data for markuplint, including:
|
|
8
|
+
|
|
9
|
+
- **HTML Living Standard elements** with complete attribute definitions
|
|
10
|
+
- **WAI-ARIA mappings** (implicit roles, permitted roles, ARIA properties)
|
|
11
|
+
- **Content model definitions** for each element
|
|
12
|
+
- **MDN-enriched metadata** (descriptions, compatibility, experimental status)
|
|
13
|
+
- **Automated external data integration** from authoritative sources
|
|
14
|
+
|
|
15
|
+
This package serves as the data layer in markuplint's specification system, depending on `@markuplint/ml-spec` for type definitions and structural schemas.
|
|
16
|
+
|
|
17
|
+
## Package Architecture
|
|
18
|
+
|
|
19
|
+
This package serves as the data layer in markuplint's specification system:
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
@markuplint/ml-spec (Foundation Layer)
|
|
23
|
+
↓ provides types, algorithms, schemas
|
|
24
|
+
@markuplint/html-spec (Data Layer) ← YOU ARE HERE
|
|
25
|
+
↓ provides HTML specification data
|
|
26
|
+
Framework-specific specs (Extension Layer)
|
|
27
|
+
↓ provide framework extensions
|
|
28
|
+
Core packages (Application Layer)
|
|
29
|
+
↓ consume specifications for validation
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Package Contents
|
|
33
|
+
|
|
34
|
+
### Generated Output (DO NOT EDIT)
|
|
35
|
+
|
|
36
|
+
- **`index.json`** - Consolidated specification data (48K+ lines)
|
|
37
|
+
- All HTML elements with complete specifications
|
|
38
|
+
- Global attribute definitions (`#HTMLGlobalAttrs`, `#ARIAAttrs`)
|
|
39
|
+
- ARIA role and property definitions (`#aria`)
|
|
40
|
+
- Content model macros (`#contentModels`)
|
|
41
|
+
- Citation references to authoritative sources
|
|
42
|
+
|
|
43
|
+
### Source Files (EDIT THESE)
|
|
44
|
+
|
|
45
|
+
- **`src/spec-*.json`** - Individual element specifications
|
|
46
|
+
- `src/spec.div.json` → `<div>` element specification
|
|
47
|
+
- `src/spec.table.json` → `<table>` element specification
|
|
48
|
+
- `src/spec.svg_text.json` → `<svg:text>` element specification
|
|
49
|
+
- **`src/spec-common.attributes.json`** - Shared attribute definitions
|
|
50
|
+
- **`src/spec-common.contents.json`** - Reusable content model macros
|
|
51
|
+
|
|
52
|
+
### Build Process
|
|
53
|
+
|
|
54
|
+
- **`build.mjs`** - Generation script that invokes `@markuplint/spec-generator`
|
|
55
|
+
- **External data sources**:
|
|
56
|
+
- **MDN Web Docs** - Element descriptions, compatibility data, attribute metadata
|
|
57
|
+
- **W3C ARIA specifications** - Role definitions, property mappings (1.1/1.2/1.3)
|
|
58
|
+
- **HTML Living Standard** - Obsolete element definitions
|
|
59
|
+
- **SVG specifications** - SVG element definitions and categories
|
|
60
|
+
|
|
61
|
+
## Data Structure
|
|
62
|
+
|
|
63
|
+
The generated `index.json` follows this structure:
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
{
|
|
67
|
+
cites: Cites; // Reference citations to external specs
|
|
68
|
+
def: { // Global definitions
|
|
69
|
+
"#HTMLGlobalAttrs": GlobalAttributes;
|
|
70
|
+
"#ARIAAttrs": ARIAAttributes;
|
|
71
|
+
"#aria": ARIASpecification;
|
|
72
|
+
"#contentModels": ContentModelMacros;
|
|
73
|
+
};
|
|
74
|
+
specs: ElementSpec[]; // Individual element specifications
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Element Specification Format
|
|
79
|
+
|
|
80
|
+
Each element specification includes:
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
{
|
|
84
|
+
name: string; // Element name (e.g., "table", "tr")
|
|
85
|
+
cite: string; // MDN reference URL
|
|
86
|
+
description: string; // Human-readable description
|
|
87
|
+
categories: string[]; // Content categories (flow, phrasing, etc.)
|
|
88
|
+
contentModel: ContentModel; // Permitted child elements
|
|
89
|
+
globalAttrs: GlobalAttrSets; // Applicable global attributes
|
|
90
|
+
attributes: AttributeSpecs; // Element-specific attributes
|
|
91
|
+
aria: { // ARIA integration
|
|
92
|
+
implicitRole: string | null; // Default ARIA role
|
|
93
|
+
permittedRoles: string[] | boolean; // Allowed ARIA roles
|
|
94
|
+
namingProhibited?: boolean; // Accessible name constraints
|
|
95
|
+
conditions?: ConditionalARIA; // Context-specific ARIA rules
|
|
96
|
+
};
|
|
97
|
+
omission?: TagOmissionRules; // Start/end tag omission rules
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Relationship to @markuplint/ml-spec
|
|
102
|
+
|
|
103
|
+
**@markuplint/ml-spec** provides the foundation:
|
|
104
|
+
|
|
105
|
+
- **Type definitions** (`ElementSpec`, `ExtendedSpec`, `MLMLSpec`) that structure this data
|
|
106
|
+
- **JSON schemas** that validate the specification format
|
|
107
|
+
- **Algorithms** that process and compute values from this specification data
|
|
108
|
+
- **Runtime utilities** that consume this consolidated specification data
|
|
109
|
+
|
|
110
|
+
**@markuplint/html-spec** (this package) provides:
|
|
111
|
+
|
|
112
|
+
- **Canonical HTML data** following the type definitions from `@markuplint/ml-spec`
|
|
113
|
+
- **External data enrichment** from MDN and W3C specifications
|
|
114
|
+
- **Build automation** that keeps data synchronized with external sources
|
|
115
|
+
- **Single consolidated dataset** optimized for runtime consumption
|
|
116
|
+
|
|
117
|
+
This separation enables:
|
|
118
|
+
|
|
119
|
+
- **Independent data updates** without affecting type definitions or algorithms
|
|
120
|
+
- **Algorithm improvements** without requiring data regeneration
|
|
121
|
+
- **Framework extensions** that can augment this base HTML data
|
|
122
|
+
|
|
123
|
+
## Development Workflow
|
|
124
|
+
|
|
125
|
+
### Adding or Editing HTML Elements
|
|
126
|
+
|
|
127
|
+
1. **Edit source specifications**
|
|
128
|
+
- Add new file: `src/spec.<element>.json` (e.g., `src/spec.dialog.json`)
|
|
129
|
+
- Edit existing: Update relevant `src/spec-*.json` file
|
|
130
|
+
- For SVG elements: Use pattern `src/spec.svg_<local>.json`
|
|
131
|
+
|
|
132
|
+
2. **Regenerate the dataset**
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
# From repository root (recommended)
|
|
136
|
+
yarn up:gen
|
|
137
|
+
|
|
138
|
+
# Or for this package only
|
|
139
|
+
yarn workspace @markuplint/html-spec run gen
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
3. **Verify output**
|
|
143
|
+
- Check `index.json` for expected changes
|
|
144
|
+
- Ensure no unintended modifications to other elements
|
|
145
|
+
|
|
146
|
+
### Element Specification Guide
|
|
147
|
+
|
|
148
|
+
**Minimal element specification**:
|
|
149
|
+
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"contentModel": {
|
|
153
|
+
"contents": [{ "require": "#phrasing" }]
|
|
154
|
+
},
|
|
155
|
+
"globalAttrs": {
|
|
156
|
+
"#HTMLGlobalAttrs": true,
|
|
157
|
+
"#ARIAAttrs": true
|
|
158
|
+
},
|
|
159
|
+
"attributes": {
|
|
160
|
+
"custom-attr": { "type": "String" }
|
|
161
|
+
},
|
|
162
|
+
"aria": {
|
|
163
|
+
"implicitRole": "button",
|
|
164
|
+
"permittedRoles": ["link", "tab"]
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**Key principles**:
|
|
170
|
+
|
|
171
|
+
- Only specify what differs from defaults or overrides MDN data
|
|
172
|
+
- Use references to global attribute sets when possible
|
|
173
|
+
- Define content models using semantic categories (`#flow`, `#phrasing`)
|
|
174
|
+
- Include ARIA specifications following HTML-ARIA mapping guidelines
|
|
175
|
+
|
|
176
|
+
### Common Editing Patterns
|
|
177
|
+
|
|
178
|
+
**Adding element-specific attributes**:
|
|
179
|
+
|
|
180
|
+
```json
|
|
181
|
+
{
|
|
182
|
+
"attributes": {
|
|
183
|
+
"href": {
|
|
184
|
+
"type": "URL",
|
|
185
|
+
"required": false,
|
|
186
|
+
"description": "Target URL for navigation"
|
|
187
|
+
},
|
|
188
|
+
"download": {
|
|
189
|
+
"type": "String",
|
|
190
|
+
"experimental": true
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
**Conditional ARIA rules**:
|
|
197
|
+
|
|
198
|
+
```json
|
|
199
|
+
{
|
|
200
|
+
"aria": {
|
|
201
|
+
"implicitRole": "link",
|
|
202
|
+
"permittedRoles": ["button", "menuitem"],
|
|
203
|
+
"conditions": {
|
|
204
|
+
":not([href])": {
|
|
205
|
+
"implicitRole": "generic",
|
|
206
|
+
"namingProhibited": true
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
**Complex content models**:
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"contentModel": {
|
|
218
|
+
"contents": [{ "transparent": ":not(:model(interactive), a, [tabindex])" }]
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Build Process Details
|
|
224
|
+
|
|
225
|
+
### What `yarn up:gen` does
|
|
226
|
+
|
|
227
|
+
1. **Invokes spec-generator** with inputs:
|
|
228
|
+
- HTML spec sources: `src/spec-*.json`
|
|
229
|
+
- Common attributes: `src/spec-common.attributes.json`
|
|
230
|
+
- Common content models: `src/spec-common.contents.json`
|
|
231
|
+
|
|
232
|
+
2. **External data enrichment**:
|
|
233
|
+
- **MDN scraping**: Fetches descriptions, categories, attribute metadata
|
|
234
|
+
- **ARIA integration**: Downloads W3C ARIA specifications (1.1/1.2/1.3)
|
|
235
|
+
- **Obsolete elements**: Adds deprecated elements from HTML Living Standard
|
|
236
|
+
- **SVG specifications**: Includes SVG element definitions and categories
|
|
237
|
+
|
|
238
|
+
3. **Data consolidation**:
|
|
239
|
+
- Merges manual specifications with fetched data
|
|
240
|
+
- Resolves conflicts (manual data takes precedence)
|
|
241
|
+
- Validates against JSON schemas from `@markuplint/ml-spec`
|
|
242
|
+
- Generates citations and references
|
|
243
|
+
|
|
244
|
+
4. **Output generation**:
|
|
245
|
+
- Writes consolidated `index.json`
|
|
246
|
+
- Formats with Prettier
|
|
247
|
+
- Validates structural integrity
|
|
248
|
+
|
|
249
|
+
### External Data Sources
|
|
250
|
+
|
|
251
|
+
**MDN Web Docs** (`developer.mozilla.org`):
|
|
252
|
+
|
|
253
|
+
- Element descriptions and usage guidance
|
|
254
|
+
- Compatibility tables and browser support
|
|
255
|
+
- Attribute metadata (deprecated, experimental, obsolete)
|
|
256
|
+
- Tag omission rules and semantic information
|
|
257
|
+
|
|
258
|
+
**W3C ARIA Specifications**:
|
|
259
|
+
|
|
260
|
+
- **ARIA 1.1**: `https://www.w3.org/TR/wai-aria-1.1/`
|
|
261
|
+
- **ARIA 1.2**: `https://www.w3.org/TR/wai-aria-1.2/`
|
|
262
|
+
- **ARIA 1.3**: `https://w3c.github.io/aria/`
|
|
263
|
+
- **HTML-ARIA**: `https://www.w3.org/TR/html-aria/`
|
|
264
|
+
|
|
265
|
+
**HTML Living Standard** (`https://html.spec.whatwg.org/`):
|
|
266
|
+
|
|
267
|
+
- Obsolete element definitions
|
|
268
|
+
- Semantic category classifications
|
|
269
|
+
- Content model specifications
|
|
270
|
+
|
|
271
|
+
### Caching and Performance
|
|
272
|
+
|
|
273
|
+
- **External fetches are cached** to prevent unnecessary network requests during development
|
|
274
|
+
- **CI/CD builds** refresh external data to stay current with specification changes
|
|
275
|
+
- **Generated output is optimized** for runtime consumption (single file, pre-resolved references)
|
|
276
|
+
|
|
277
|
+
## File Naming Conventions
|
|
278
|
+
|
|
279
|
+
**HTML elements**: `src/spec.<tag>.json`
|
|
280
|
+
|
|
281
|
+
- Examples: `spec.div.json`, `spec.table.json`, `spec.input.json`
|
|
282
|
+
|
|
283
|
+
**SVG elements**: `src/spec.svg_<local>.json`
|
|
284
|
+
|
|
285
|
+
- Examples: `spec.svg_text.json`, `spec.svg_circle.json`
|
|
286
|
+
- Element name inferred as `svg:<local>` (e.g., `svg:text`)
|
|
287
|
+
|
|
288
|
+
**Special files**:
|
|
289
|
+
|
|
290
|
+
- `spec-common.attributes.json` - Global attribute category definitions
|
|
291
|
+
- `spec-common.contents.json` - Reusable content model macros
|
|
292
|
+
|
|
5
293
|
## Install
|
|
6
294
|
|
|
7
295
|
[`markuplint`](https://www.npmjs.com/package/markuplint) package includes this package.
|
|
@@ -16,3 +304,32 @@ $ yarn add @markuplint/html-spec
|
|
|
16
304
|
```
|
|
17
305
|
|
|
18
306
|
</details>
|
|
307
|
+
|
|
308
|
+
## Important Notes
|
|
309
|
+
|
|
310
|
+
### Do Not Edit Generated Files
|
|
311
|
+
|
|
312
|
+
- **Never modify `index.json` directly** - it will be overwritten
|
|
313
|
+
- Always update source files in `src/` and regenerate
|
|
314
|
+
|
|
315
|
+
### Manual Data Takes Precedence
|
|
316
|
+
|
|
317
|
+
- Your specifications in `src/spec-*.json` override scraped MDN data
|
|
318
|
+
- Use this to correct inaccuracies or add missing information
|
|
319
|
+
- External data fills gaps but doesn't override manual specifications
|
|
320
|
+
|
|
321
|
+
### Specification Compliance
|
|
322
|
+
|
|
323
|
+
- ARIA mappings should follow W3C HTML-ARIA mapping guidelines
|
|
324
|
+
- Content models should align with HTML Living Standard definitions
|
|
325
|
+
- Attribute types should reference `@markuplint/types` definitions
|
|
326
|
+
|
|
327
|
+
### Framework Integration
|
|
328
|
+
|
|
329
|
+
- This package provides base HTML specifications
|
|
330
|
+
- Framework-specific packages (Vue, React, Svelte) extend this base data
|
|
331
|
+
- Extensions are merged at runtime using `@markuplint/ml-spec` utilities
|
|
332
|
+
|
|
333
|
+
## License
|
|
334
|
+
|
|
335
|
+
MIT
|
package/index.d.ts
CHANGED
|
@@ -1,7 +1,13 @@
|
|
|
1
1
|
import type { Cites, ElementSpec, SpecDefs } from '@markuplint/ml-spec';
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
declare namespace json {
|
|
4
|
+
export { Attribute } from '@markuplint/ml-spec';
|
|
5
|
+
}
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
7
|
+
declare const json: {
|
|
8
|
+
cites: Cites;
|
|
9
|
+
def: SpecDefs;
|
|
10
|
+
specs: ElementSpec[];
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
export = json;
|
package/index.js
CHANGED