@markuplint/html-spec 4.14.2 → 4.15.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.15.0](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.14.2...@markuplint/html-spec@4.15.0) (2025-08-13)
+
+### Bug Fixes
+
+- **html-spec:** format attribute value types with proper spacing ([b726ab9](https://github.com/markuplint/markuplint/commit/b726ab97faeee186e0f05f6690de338d7182a060))
+- **html-spec:** update img src/srcset attributes to be mutually required ([1a9a611](https://github.com/markuplint/markuplint/commit/1a9a61102468407ef254e970c2903a69d9ec6465))
+
+### Features
+
+- **html-spec:** add compact attribute to dl element ([936aa24](https://github.com/markuplint/markuplint/commit/936aa24ebc4f1e6122a167466ccd4c63025e8ca2))
+- **html-spec:** add compact attribute to menu element ([d4c16f8](https://github.com/markuplint/markuplint/commit/d4c16f89fe1f3a8acb08e3e83cb23e260c017ec6))
+- **html-spec:** add compact attribute to ol element ([a19785b](https://github.com/markuplint/markuplint/commit/a19785b2af45b6ceb65a66b8ef1162b385b15684))
+- **html-spec:** add fetchpriority attribute to SVG script element ([2669d23](https://github.com/markuplint/markuplint/commit/2669d238e0496c5c57b2ca9182685db420312103))
+- **html-spec:** add mask-type attribute to SVG mask element ([9e27e27](https://github.com/markuplint/markuplint/commit/9e27e27eae2166e99cb124725a299c317a1736d9))
+- **html-spec:** remove form attribute from meter element ([1cee2cb](https://github.com/markuplint/markuplint/commit/1cee2cb54f18e38c8ec652ddfd5f382e757eb1b4))
+- **html-spec:** remove the `cursor` SVG element ([43d224f](https://github.com/markuplint/markuplint/commit/43d224f598a0735da95f5754bb1c5577eb091b2a))
+- **html-spec:** remove the `khern` SVG element ([4c05a01](https://github.com/markuplint/markuplint/commit/4c05a010f33100d912d851731eb689b938b0be99))
+- **html-spec:** remove the `missing` SVG element ([c66f316](https://github.com/markuplint/markuplint/commit/c66f316210e0fc185be8c1fe3d33798ed0492b4d))
+- **html-spec:** remove the `tref` SVG element ([520c81f](https://github.com/markuplint/markuplint/commit/520c81f4e391486feea574e99e163faf3b129601))
+- **html-spec:** remove the `vkern` SVG element ([aadd4cc](https://github.com/markuplint/markuplint/commit/aadd4cc91bb6622c64bcb1b1d5beff9759bdbbb6))
+- **html-spec:** update accessibleNameRequired for specific roles ([4e79515](https://github.com/markuplint/markuplint/commit/4e79515a86bd488cb2a8156ad11fcb9a9967453e))
+- **html-spec:** update descriptions for specific roles ([f018270](https://github.com/markuplint/markuplint/commit/f018270b0d3a301899a7a66c22d4c7ed9c1199fe))
+- **html-spec:** update tree role required owned elements based on ARIA spec change ([0e681bb](https://github.com/markuplint/markuplint/commit/0e681bb686869c01e33a67dd65445ff4dc0c1b1c))
+
 ## [4.14.2](https://github.com/markuplint/markuplint/compare/@markuplint/html-spec@4.14.1...@markuplint/html-spec@4.14.2) (2025-04-13)
 
 **Note:** Version bump only for package @markuplint/html-spec

package/README.md

@@ -2,6 +2,162 @@
 
 [![npm version](https://badge.fury.io/js/%40markuplint%2Fhtml-spec.svg)](https://www.npmjs.com/package/@markuplint/html-spec)
 
+This package is the canonical dataset of the HTML Schema for markuplint — HTML element specifications
+(structure, attributes, ARIA, and content models).
+
+### What’s in this package
+
+- Built output consumed by markuplint:
+  - `index.json`
+- Sources (do not edit generated files):
+  - `src/spec-*.json` (element specs and common data)
+  - Build script: `build.mjs` (invokes `@markuplint/spec-generator`)
+
+For the common schema shapes (JSON Schema), generation workflow, and spec-merging behavior, see
+`@markuplint/ml-spec` README.
+
+### Editing workflow (HTML spec data)
+
+1. Edit sources
+
+- Element specs: add or edit files under `src/spec-*.json` (e.g. `src/spec.a.json`)
+- Common data shared across elements:
+  - Attributes: `src/spec-common.attributes.json`
+  - Content models: `src/spec-common.contents.json`
+
+2. Regenerate the built dataset
+
+From the repository root (recommended):
+
+```bash
+yarn up:gen
+```
+
+or only for this package:
+
+```bash
+yarn workspace @markuplint/html-spec run gen
+```
+
+This runs the local build script (`build.mjs`) which invokes `@markuplint/spec-generator` and writes
+`index.json`, then formats it with Prettier.
+
+#### What `yarn up:gen` does exactly
+
+From the repository root, it executes:
+
+1. Change directory into this package
+   - `cd packages/@markuplint/html-spec/`
+2. Run the local `gen` script, which is an alias of:
+   - `node build.mjs` (generate `index.json`)
+   - `npx prettier --write index.json` (format the output)
+
+Inside `build.mjs`, the generator is called with the following inputs:
+
+- Output: `index.json`
+- HTML spec sources: `src/spec.*.json`
+- Common attributes: `src/spec-common.attributes.json`
+- Common content models: `src/spec-common.contents.json`
+
+No other files are modified. This command does not publish anything.
+
+### What the generator actually does
+
+The builder (`@markuplint/spec-generator`) produces a single Extended Spec JSON (`index.json`) by:
+
+- Reading every `src/spec.*.json` and inferring the element name from the filename
+  - Example: `src/spec.a.json` → name `a`
+- Scraping MDN for each element to enrich missing metadata
+  - Fills/updates: `cite` (MDN URL), `description`, `categories`, `omission` (tag omission hints),
+    and known attribute metadata (deprecated/obsolete/experimental/nonStandard)
+  - Your fields in `src/spec.*.json` take precedence when both exist (manual beats scraped)
+- Injecting obsolete elements not present in sources (WHATWG obsolete list + deprecated SVG)
+- Loading shared data
+  - Global attribute sets: `src/spec-common.attributes.json`
+  - Content model macros: `src/spec-common.contents.json` (its `models`)
+- Building ARIA definitions by scraping WAI-ARIA and HTML-ARIA
+  - Populates `def['#aria']` with roles, properties and graphics-ARIA per version (1.1/1.2/1.3)
+- Emitting the Extended Spec object `{ cites, def: { #globalAttrs, #aria, #contentModels }, specs: [...] }`
+  and formatting to `index.json`
+
+The output is consumed by markuplint and can be merged with other framework specs.
+
+### How to edit `src/spec.*.json`
+
+Each file describes one HTML element. Only specify what differs from the defaults or what you want
+to override from MDN. Recognized top-level keys include:
+
+- `contentModel`: allowed children pattern; see `@markuplint/ml-spec` content-model schema
+- `globalAttrs`: enable global attribute sets or list specific ones per category
+- `attributes`: element-specific attributes and their types/options
+- `aria`: implicit role, permitted roles, and ARIA property constraints for this element
+- `omission`: start/end tag omission rules (when applicable)
+
+Minimal example (anchor element):
+
+```json
+{
+  "contentModel": {
+    "contents": [{ "transparent": ":not(:model(interactive), a, [tabindex])" }]
+  },
+  "globalAttrs": {
+    "#HTMLGlobalAttrs": true,
+    "#GlobalEventAttrs": true,
+    "#ARIAAttrs": true,
+    "#HTMLLinkAndFetchingAttrs": ["href", "target", "rel"]
+  },
+  "attributes": {
+    "download": { "type": "Any" }
+  },
+  "aria": {
+    "implicitRole": "link",
+    "permittedRoles": ["button", "menuitem"],
+    "conditions": {
+      ":not([href])": { "implicitRole": "generic", "namingProhibited": true }
+    }
+  }
+}
+```
+
+Attribute entries follow the shape from `@markuplint/ml-spec` (`attributes.schema.json`):
+
+- Common fields: `type`, `defaultValue`, `required`, `requiredEither`, `noUse`, `condition`,
+  `ineffective`, `animatable`, `experimental`, `deprecated`, `obsolete`, `nonStandard`
+- Types come from `@markuplint/types` (`types.schema.json`)
+
+When to change shared files:
+
+- Add/edit global attribute categories or items → `src/spec-common.attributes.json`
+- Add/edit reusable content model macros → `src/spec-common.contents.json`
+
+#### File naming conventions
+
+- HTML elements: `src/spec.<tag>.json` (lowercase), e.g. `spec.a.json`, `spec.dialog.json`
+- SVG elements: `src/spec.svg_<local>.json`, e.g. `spec.svg_text.json` → element name `svg:text`
+  - The generator infers the element name from the filename; do not add a `name` field manually
+
+#### Common editing recipes
+
+- Add a new element
+  - Create `src/spec.<tag>.json` (or `src/spec.svg_<local>.json`)
+  - Define `contentModel`, `globalAttrs`, minimal `attributes`, and `aria`
+  - Run `yarn up:gen` and verify `index.json`
+
+- Tighten an attribute type
+  - Update the attribute entry under `attributes` with the desired `type`
+  - If a new value type is needed, extend `@markuplint/types` first, then regenerate this package
+
+- Mark an attribute unstable
+  - Set `experimental: true`, `deprecated: true`, or `obsolete: true`
+  - Manual flags override MDN if the scraper disagrees
+
+- Restrict ARIA usage for an element
+  - Use `aria.properties`/`aria.permittedRoles` or add `aria.conditions` for context-specific rules
+
+3. Do not edit generated files
+
+- Do not modify `index.json` directly. Always update the files under `src/` and regenerate.
+
 ## Install
 
 [`markuplint`](https://www.npmjs.com/package/markuplint) package includes this package.

package/index.d.ts

@@ -1,7 +1,13 @@
 import type { Cites, ElementSpec, SpecDefs } from '@markuplint/ml-spec';
 
-export { Attribute } from '@markuplint/ml-spec';
+declare namespace json {
+	export { Attribute } from '@markuplint/ml-spec';
+}
 
-export const cites: Cites;
-export const def: SpecDefs;
-export const specs: ElementSpec[];
+declare const json: {
+	cites: Cites;
+	def: SpecDefs;
+	specs: ElementSpec[];
+};
+
+export = json;

package/index.js

@@ -1,4 +1,4 @@
-/* eslint-disable no-restricted-globals, unicorn/prefer-module */
+/* eslint-disable @typescript-eslint/no-require-imports, no-restricted-globals, unicorn/prefer-module */
 
 const json = require('./index.json');
 module.exports = json;