@markuplint/html-spec 4.15.0 → 4.16.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.
Files changed (4) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +257 -96
  3. package/index.json +463 -570
  4. package/package.json +5 -5
package/CHANGELOG.md CHANGED
@@ -3,6 +3,21 @@
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.1](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.16.0...@markuplint/html-spec@4.16.1) (2025-11-05)
7
+
8
+ **Note:** Version bump only for package @markuplint/html-spec
9
+
10
+
11
+
12
+
13
+
14
+ # [4.16.0](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.15.0...@markuplint/html-spec@4.16.0) (2025-08-24)
15
+
16
+ ### Features
17
+
18
+ - **html-spec:** implement link type definitions for rel attributes ([0bfa05f](https://github.com/markuplint/markuplint/commit/0bfa05fa39fbcff99e237eb628e89ea2090abd92))
19
+ - **html-spec:** update element references for new MDN URL structure ([452eebb](https://github.com/markuplint/markuplint/commit/452eebb9a4e7d75aca9ff15ee023935206ae237e))
20
+
6
21
  # [4.15.0](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.14.2...@markuplint/html-spec@4.15.0) (2025-08-13)
7
22
 
8
23
  ### Bug Fixes
package/README.md CHANGED
@@ -2,161 +2,293 @@
2
2
 
3
3
  [![npm version](https://badge.fury.io/js/%40markuplint%2Fhtml-spec.svg)](https://www.npmjs.com/package/@markuplint/html-spec)
4
4
 
5
- This package is the canonical dataset of the HTML Schema for markuplint — HTML element specifications
6
- (structure, attributes, ARIA, and content models).
5
+ **Canonical HTML Living Standard dataset provider with automated external data enrichment.**
7
6
 
8
- ### What’s in this package
7
+ This package provides the consolidated HTML element specification data for markuplint, including:
9
8
 
10
- - Built output consumed by markuplint:
11
- - `index.json`
12
- - Sources (do not edit generated files):
13
- - `src/spec-*.json` (element specs and common data)
14
- - Build script: `build.mjs` (invokes `@markuplint/spec-generator`)
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
15
14
 
16
- For the common schema shapes (JSON Schema), generation workflow, and spec-merging behavior, see
17
- `@markuplint/ml-spec` README.
15
+ This package serves as the data layer in markuplint's specification system, depending on `@markuplint/ml-spec` for type definitions and structural schemas.
18
16
 
19
- ### Editing workflow (HTML spec data)
17
+ ## Package Architecture
20
18
 
21
- 1. Edit sources
19
+ This package serves as the data layer in markuplint's specification system:
22
20
 
23
- - Element specs: add or edit files under `src/spec-*.json` (e.g. `src/spec.a.json`)
24
- - Common data shared across elements:
25
- - Attributes: `src/spec-common.attributes.json`
26
- - Content models: `src/spec-common.contents.json`
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
27
60
 
28
- 2. Regenerate the built dataset
61
+ ## Data Structure
29
62
 
30
- From the repository root (recommended):
63
+ The generated `index.json` follows this structure:
31
64
 
32
- ```bash
33
- yarn up:gen
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
+ }
34
76
  ```
35
77
 
36
- or only for this package:
78
+ ### Element Specification Format
37
79
 
38
- ```bash
39
- yarn workspace @markuplint/html-spec run gen
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
+ }
40
99
  ```
41
100
 
42
- This runs the local build script (`build.mjs`) which invokes `@markuplint/spec-generator` and writes
43
- `index.json`, then formats it with Prettier.
101
+ ## Relationship to @markuplint/ml-spec
102
+
103
+ **@markuplint/ml-spec** provides the foundation:
44
104
 
45
- #### What `yarn up:gen` does exactly
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
46
109
 
47
- From the repository root, it executes:
110
+ **@markuplint/html-spec** (this package) provides:
48
111
 
49
- 1. Change directory into this package
50
- - `cd packages/@markuplint/html-spec/`
51
- 2. Run the local `gen` script, which is an alias of:
52
- - `node build.mjs` (generate `index.json`)
53
- - `npx prettier --write index.json` (format the output)
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
54
116
 
55
- Inside `build.mjs`, the generator is called with the following inputs:
117
+ This separation enables:
56
118
 
57
- - Output: `index.json`
58
- - HTML spec sources: `src/spec.*.json`
59
- - Common attributes: `src/spec-common.attributes.json`
60
- - Common content models: `src/spec-common.contents.json`
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
61
122
 
62
- No other files are modified. This command does not publish anything.
123
+ ## Development Workflow
63
124
 
64
- ### What the generator actually does
125
+ ### Adding or Editing HTML Elements
65
126
 
66
- The builder (`@markuplint/spec-generator`) produces a single Extended Spec JSON (`index.json`) by:
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`
67
131
 
68
- - Reading every `src/spec.*.json` and inferring the element name from the filename
69
- - Example: `src/spec.a.json` → name `a`
70
- - Scraping MDN for each element to enrich missing metadata
71
- - Fills/updates: `cite` (MDN URL), `description`, `categories`, `omission` (tag omission hints),
72
- and known attribute metadata (deprecated/obsolete/experimental/nonStandard)
73
- - Your fields in `src/spec.*.json` take precedence when both exist (manual beats scraped)
74
- - Injecting obsolete elements not present in sources (WHATWG obsolete list + deprecated SVG)
75
- - Loading shared data
76
- - Global attribute sets: `src/spec-common.attributes.json`
77
- - Content model macros: `src/spec-common.contents.json` (its `models`)
78
- - Building ARIA definitions by scraping WAI-ARIA and HTML-ARIA
79
- - Populates `def['#aria']` with roles, properties and graphics-ARIA per version (1.1/1.2/1.3)
80
- - Emitting the Extended Spec object `{ cites, def: { #globalAttrs, #aria, #contentModels }, specs: [...] }`
81
- and formatting to `index.json`
132
+ 2. **Regenerate the dataset**
82
133
 
83
- The output is consumed by markuplint and can be merged with other framework specs.
134
+ ```bash
135
+ # From repository root (recommended)
136
+ yarn up:gen
84
137
 
85
- ### How to edit `src/spec.*.json`
138
+ # Or for this package only
139
+ yarn workspace @markuplint/html-spec run gen
140
+ ```
86
141
 
87
- Each file describes one HTML element. Only specify what differs from the defaults or what you want
88
- to override from MDN. Recognized top-level keys include:
142
+ 3. **Verify output**
143
+ - Check `index.json` for expected changes
144
+ - Ensure no unintended modifications to other elements
89
145
 
90
- - `contentModel`: allowed children pattern; see `@markuplint/ml-spec` content-model schema
91
- - `globalAttrs`: enable global attribute sets or list specific ones per category
92
- - `attributes`: element-specific attributes and their types/options
93
- - `aria`: implicit role, permitted roles, and ARIA property constraints for this element
94
- - `omission`: start/end tag omission rules (when applicable)
146
+ ### Element Specification Guide
95
147
 
96
- Minimal example (anchor element):
148
+ **Minimal element specification**:
97
149
 
98
150
  ```json
99
151
  {
100
152
  "contentModel": {
101
- "contents": [{ "transparent": ":not(:model(interactive), a, [tabindex])" }]
153
+ "contents": [{ "require": "#phrasing" }]
102
154
  },
103
155
  "globalAttrs": {
104
156
  "#HTMLGlobalAttrs": true,
105
- "#GlobalEventAttrs": true,
106
- "#ARIAAttrs": true,
107
- "#HTMLLinkAndFetchingAttrs": ["href", "target", "rel"]
157
+ "#ARIAAttrs": true
108
158
  },
109
159
  "attributes": {
110
- "download": { "type": "Any" }
160
+ "custom-attr": { "type": "String" }
111
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
+ {
112
200
  "aria": {
113
201
  "implicitRole": "link",
114
202
  "permittedRoles": ["button", "menuitem"],
115
203
  "conditions": {
116
- ":not([href])": { "implicitRole": "generic", "namingProhibited": true }
204
+ ":not([href])": {
205
+ "implicitRole": "generic",
206
+ "namingProhibited": true
207
+ }
117
208
  }
118
209
  }
119
210
  }
120
211
  ```
121
212
 
122
- Attribute entries follow the shape from `@markuplint/ml-spec` (`attributes.schema.json`):
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
123
243
 
124
- - Common fields: `type`, `defaultValue`, `required`, `requiredEither`, `noUse`, `condition`,
125
- `ineffective`, `animatable`, `experimental`, `deprecated`, `obsolete`, `nonStandard`
126
- - Types come from `@markuplint/types` (`types.schema.json`)
244
+ 4. **Output generation**:
245
+ - Writes consolidated `index.json`
246
+ - Formats with Prettier
247
+ - Validates structural integrity
127
248
 
128
- When to change shared files:
249
+ ### External Data Sources
129
250
 
130
- - Add/edit global attribute categories or items → `src/spec-common.attributes.json`
131
- - Add/edit reusable content model macros → `src/spec-common.contents.json`
251
+ **MDN Web Docs** (`developer.mozilla.org`):
132
252
 
133
- #### File naming conventions
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
134
257
 
135
- - HTML elements: `src/spec.<tag>.json` (lowercase), e.g. `spec.a.json`, `spec.dialog.json`
136
- - SVG elements: `src/spec.svg_<local>.json`, e.g. `spec.svg_text.json` → element name `svg:text`
137
- - The generator infers the element name from the filename; do not add a `name` field manually
258
+ **W3C ARIA Specifications**:
138
259
 
139
- #### Common editing recipes
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/`
140
264
 
141
- - Add a new element
142
- - Create `src/spec.<tag>.json` (or `src/spec.svg_<local>.json`)
143
- - Define `contentModel`, `globalAttrs`, minimal `attributes`, and `aria`
144
- - Run `yarn up:gen` and verify `index.json`
265
+ **HTML Living Standard** (`https://html.spec.whatwg.org/`):
145
266
 
146
- - Tighten an attribute type
147
- - Update the attribute entry under `attributes` with the desired `type`
148
- - If a new value type is needed, extend `@markuplint/types` first, then regenerate this package
267
+ - Obsolete element definitions
268
+ - Semantic category classifications
269
+ - Content model specifications
149
270
 
150
- - Mark an attribute unstable
151
- - Set `experimental: true`, `deprecated: true`, or `obsolete: true`
152
- - Manual flags override MDN if the scraper disagrees
271
+ ### Caching and Performance
153
272
 
154
- - Restrict ARIA usage for an element
155
- - Use `aria.properties`/`aria.permittedRoles` or add `aria.conditions` for context-specific rules
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)
156
276
 
157
- 3. Do not edit generated files
277
+ ## File Naming Conventions
158
278
 
159
- - Do not modify `index.json` directly. Always update the files under `src/` and regenerate.
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
160
292
 
161
293
  ## Install
162
294
 
@@ -172,3 +304,32 @@ $ yarn add @markuplint/html-spec
172
304
  ```
173
305
 
174
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