@markuplint/html-spec 4.17.0 → 5.0.0-alpha.0

package/docs/element-spec-format.md

@@ -9,23 +9,23 @@ the shared common files.
 
 ### HTML Elements
 
-Pattern: `src/spec.<tag>.json` (e.g., `spec.div.json`, `spec.table.json`, `spec.input.json`)
+Pattern: `src/spec.<tag>.jsonc` (e.g., `spec.div.jsonc`, `spec.table.jsonc`, `spec.input.jsonc`)
 
 ### SVG Elements
 
-Pattern: `src/spec.svg_<local>.json` (e.g., `spec.svg_text.json`, `spec.svg_circle.json`)
+Pattern: `src/spec.svg_<local>.jsonc` (e.g., `spec.svg_text.jsonc`, `spec.svg_circle.jsonc`)
 
-The local name preserves case (`svg_animateMotion.json`). The element name is inferred
+The local name preserves case (`svg_animateMotion.jsonc`). The element name is inferred
 at runtime as `svg:<local>` (e.g., `svg:text`, `svg:clipPath`).
 
 ### Common Files
 
-- `spec-common.attributes.json` -- Global attribute category definitions (19 categories)
-- `spec-common.contents.json` -- Content model category macros
+- `spec-common.attributes.jsonc` -- Global attribute category definitions (19 categories)
+- `spec-common.contents.jsonc` -- Content model category macros
 
 ### JSON with Comments
 
-All spec files support JavaScript-style comments (`//` and `/* */`) via `strip-json-comments`.
+All spec files use the JSONC format (`.jsonc`) and support JavaScript-style comments (`//` and `/* */`) via `jsonc-parser`.
 Use comments to link to specification URLs at the top of each file:
 
 ```json
@@ -87,7 +87,7 @@ The content model definitions in these JSON files are part of a larger ecosystem
 
 - **Schema validation** -- `@markuplint/ml-spec` provides `content-models.schema.json` which defines the valid structure of content model patterns (`require`, `optional`, `oneOrMore`, `zeroOrMore`, `choice`, `transparent`). Source JSON files are validated against this schema in tests.
 - **TypeScript types** -- `@markuplint/ml-spec` auto-generates `ContentModel`, `PermittedContentPattern`, and `Category` types from the schema (in `types/permitted-structures.ts`), enabling type-safe access throughout the codebase.
-- **Runtime algorithms** -- `@markuplint/ml-spec` provides `getContentModel()` which evaluates conditional content models at runtime, and `contentModelCategoryToTagNames()` which resolves category names (e.g., `#flow`) to concrete element lists using `def["#contentModels"]` from this package's `spec-common.contents.json`.
+- **Runtime algorithms** -- `@markuplint/ml-spec` provides `getContentModel()` which evaluates conditional content models at runtime, and `contentModelCategoryToTagNames()` which resolves category names (e.g., `#flow`) to concrete element lists using `def["#contentModels"]` from this package's `spec-common.contents.jsonc`.
 - **Lint rules** -- `@markuplint/rules` uses these definitions in the `permitted-contents` rule (validates element children against content model patterns) and the `no-empty-palpable-content` rule (uses `#palpable` category data to detect empty palpable elements).
 
 ## Content Model Patterns
@@ -207,7 +207,7 @@ elements that have been fully obsoleted). In practice, `deprecated` attributes u
 still work in browsers, while `obsolete` attributes may not.
 
 **Flag precedence (spec > MDN):** When a flag is set in the manual spec file
-(`src/spec.*.json`), it takes precedence over the MDN-scraped value. This allows you to
+(`src/spec.*.jsonc`), it takes precedence over the MDN-scraped value. This allows you to
 correct cases where MDN data is inaccurate or lagging behind the specification. Flags
 from MDN are used only when the manual spec does not define the attribute or does not
 set that particular flag.
@@ -354,12 +354,12 @@ spec versions. Version overrides can contain their own `conditions` object:
 
 ## Common Files
 
-### spec-common.attributes.json
+### spec-common.attributes.jsonc
 
 Defines the 19 global attribute categories. Each category maps attribute names to
 definitions using the same format described in the attributes section.
 
-### spec-common.contents.json
+### spec-common.contents.jsonc
 
 Defines content model category macros referenced via `:model()`. Structure:
 

package/docs/maintenance.ja.md

@@ -15,15 +15,15 @@
 
 ### 1. 新しいHTML要素の追加
 
-1. `src/spec.<element>.json` を作成（例: `src/spec.dialog.json`）
+1. `src/spec.<element>.jsonc` を作成（例: `src/spec.dialog.jsonc`）
 2. 最低限以下を定義:
    - `contentModel` と `contents`
    - `globalAttrs`（通常 `#HTMLGlobalAttrs`, `#GlobalEventAttrs`, `#ARIAAttrs` を `true` に設定）
    - `attributes`（要素固有属性、空 `{}` でも可）
    - `aria` と `implicitRole`, `permittedRoles`
-3. ファイル先頭に関連仕様URLのコメントを追加（`//` 形式、`strip-json-comments` で処理される）
+3. ファイル先頭に関連仕様URLのコメントを追加（`//` 形式、`jsonc-parser` で処理される）
 4. 要素がいずれかのコンテンツカテゴリ（flow、phrasing 等）に属する場合、
-   `src/spec-common.contents.json` の該当カテゴリに追加する。追加しないと
+   `src/spec-common.contents.jsonc` の該当カテゴリに追加する。追加しないと
    `@markuplint/rules` の `permitted-contents` ルールがそのカテゴリを許可する
    親要素の中で不正な子要素として検出してしまう
 5. `yarn workspace @markuplint/html-spec run gen` を実行
@@ -53,7 +53,7 @@
 
 ### 2. 既存要素の属性変更
 
-1. 該当する `src/spec.<element>.json` を開く
+1. 該当する `src/spec.<element>.jsonc` を開く
 2. `attributes` オブジェクトにエントリを追加・変更
 3. 条件付き属性の場合、CSSセレクタで `condition` フィールドを追加
 4. `yarn workspace @markuplint/html-spec run gen` を実行
@@ -61,7 +61,7 @@
 
 ### 3. SVG要素の追加
 
-1. `src/spec.svg_<localname>.json` を作成（例: `src/spec.svg_circle.json`）
+1. `src/spec.svg_<localname>.jsonc` を作成（例: `src/spec.svg_circle.jsonc`）
 2. ファイル名の `svg_` プレフィックスから、要素名は `svg:<localname>` として自動推論される
 3. SVG固有のグローバル属性カテゴリ（`#SVGCoreAttrs`, `#SVGPresentationAttrs` 等）を使用
 4. ARIAの `permittedRoles` にはAAM参照オブジェクト（`{ "core-aam": true, "graphics-aam": true }`）を使用
@@ -70,7 +70,7 @@
 
 ### 4. グローバル属性カテゴリの変更
 
-1. `src/spec-common.attributes.json` を編集
+1. `src/spec-common.attributes.jsonc` を編集
 2. 各トップレベルキーがカテゴリ（例: `#HTMLGlobalAttrs`, `#SVGCoreAttrs`）
 3. カテゴリ内の属性定義を追加・削除・変更
 4. `yarn workspace @markuplint/html-spec run gen` を実行
@@ -78,7 +78,7 @@
 
 ### 5. コンテンツモデルカテゴリの追加・更新
 
-1. `src/spec-common.contents.json` を編集
+1. `src/spec-common.contents.jsonc` を編集
 2. `models` オブジェクトに新しいエントリを追加、または既存カテゴリに要素を追加
 3. SVG要素には `svg|<name>` プレフィックスを使用
 4. 要素仕様で `:model(newCategory)` として参照
@@ -97,7 +97,7 @@
 
 ### 6. ARIAマッピングの更新
 
-1. 該当する `src/spec.<element>.json` を開く
+1. 該当する `src/spec.<element>.jsonc` を開く
 2. `aria` オブジェクトを変更:
    - `implicitRole` でデフォルトロールを変更
    - `permittedRoles` 配列を更新
@@ -158,7 +158,7 @@ description の表現変更などの表面的な変更は、更新された `ind
 場合、手動仕様ファイルの更新が必要になることがある:
 
 1. 影響を受ける要素を特定する
-2. 該当する `src/spec.*.json` または `src/spec-common.*.json` を新しい仕様に合わせて
+2. 該当する `src/spec.*.jsonc` または `src/spec-common.*.jsonc` を新しい仕様に合わせて
    更新する。まれに `@markuplint/ml-spec` のスキーマや型定義の更新が必要になる
    こともある
 3. 手動仕様の変更を反映するために再生成する:
@@ -168,7 +168,7 @@ description の表現変更などの表面的な変更は、更新された `ind
 4. **冪等性の検証** -- 仕様ファイルの変更が安定した出力を生成することをコミット前に確認する:
    ```bash
    # 仕様ファイルと index.json をステージ
-   git add packages/@markuplint/html-spec/src/spec.*.json packages/@markuplint/html-spec/index.json
+   git add packages/@markuplint/html-spec/src/spec.*.jsonc packages/@markuplint/html-spec/index.json
    # 再生成
    yarn up:gen
    # 変更した属性が diff に出ないことを確認（= 安定した出力）
@@ -214,12 +214,12 @@ description の表現変更などの表面的な変更は、更新された `ind
 
 ### 編集可能なファイル（これらを変更）
 
-| ファイル                          | 説明                                               |
-| --------------------------------- | -------------------------------------------------- |
-| `src/spec.*.json`                 | 要素ごとの仕様（177ファイル）                      |
-| `src/spec-common.attributes.json` | グローバル属性カテゴリ定義（19カテゴリ）           |
-| `src/spec-common.contents.json`   | コンテンツモデルカテゴリマクロ（HTML 10 + SVG 19） |
-| `build.mjs`                       | ビルドスクリプト設定                               |
+| ファイル                           | 説明                                               |
+| ---------------------------------- | -------------------------------------------------- |
+| `src/spec.*.jsonc`                 | 要素ごとの仕様（177ファイル）                      |
+| `src/spec-common.attributes.jsonc` | グローバル属性カテゴリ定義（19カテゴリ）           |
+| `src/spec-common.contents.jsonc`   | コンテンツモデルカテゴリマクロ（HTML 10 + SVG 19） |
+| `build.mjs`                        | ビルドスクリプト設定                               |
 
 ### 生成ファイル（編集不可）
 
@@ -253,14 +253,14 @@ yarn workspace @markuplint/html-spec run test
 
 スキーマテストでは以下のスキーマが使用される:
 
-| スキーマ                        | 対象                              |
-| ------------------------------- | --------------------------------- |
-| `element.schema.json`           | `src/spec.*.json` ファイル        |
-| `global-attributes.schema.json` | `src/spec-common.attributes.json` |
-| `attributes.schema.json`        | 属性定義の部分スキーマ            |
-| `types.schema.json`             | 型定義の部分スキーマ              |
-| `aria.schema.json`              | ARIA定義の部分スキーマ            |
-| `content-models.schema.json`    | コンテンツモデルの部分スキーマ    |
+| スキーマ                        | 対象                               |
+| ------------------------------- | ---------------------------------- |
+| `element.schema.json`           | `src/spec.*.jsonc` ファイル        |
+| `global-attributes.schema.json` | `src/spec-common.attributes.jsonc` |
+| `attributes.schema.json`        | 属性定義の部分スキーマ             |
+| `types.schema.json`             | 型定義の部分スキーマ               |
+| `aria.schema.json`              | ARIA定義の部分スキーマ             |
+| `content-models.schema.json`    | コンテンツモデルの部分スキーマ     |
 
 ## 依存関係管理
 

package/docs/maintenance.md

@@ -16,7 +16,7 @@ This is a practical operations and maintenance guide for contributors working on
 The generation process (`gen`) performs two steps in sequence via `npm-run-all`:
 
 1. **`gen:build`** -- Executes `build.mjs`, which calls the `main()` function from
-   `@markuplint/spec-generator`. This reads all `src/spec.*.json` files, merges them
+   `@markuplint/spec-generator`. This reads all `src/spec.*.jsonc` files, merges them
    with scraped MDN data and the common attribute/content files, appends obsolete
    element stubs, and writes the consolidated output to `index.json`.
 2. **`gen:prettier`** -- Runs Prettier on `index.json` to ensure consistent formatting
@@ -30,19 +30,19 @@ Expect the build to take several minutes on a clean run.
 
 The build script derives element names from file names using a regex replacement:
 
-- `spec.div.json` becomes element name `div`
-- `spec.svg_circle.json` becomes element name `svg_circle`, which is later resolved
+- `spec.div.jsonc` becomes element name `div`
+- `spec.svg_circle.jsonc` becomes element name `svg_circle`, which is later resolved
   to namespace `svg:circle` by `resolveNamespace()`
 - Heading elements (`h1` through `h6`) are mapped to the MDN URL path `Heading_Elements`
 
-This naming convention is critical. Any deviation from the `spec.<name>.json` pattern
+This naming convention is critical. Any deviation from the `spec.<name>.jsonc` pattern
 will cause the element to be silently excluded from the build output.
 
 ## Common Recipes
 
 ### 1. Adding a New HTML Element
 
-1. Create `src/spec.<element>.json` (e.g., `src/spec.dialog.json`)
+1. Create `src/spec.<element>.jsonc` (e.g., `src/spec.dialog.jsonc`)
 2. Define the specification with at minimum:
    - `contentModel` with `contents`
    - `globalAttrs` (typically `#HTMLGlobalAttrs`, `#GlobalEventAttrs`, `#ARIAAttrs` all set to `true`)
@@ -55,7 +55,7 @@ will cause the element to be silently excluded from the build output.
    // https://w3c.github.io/html-aria/#el-<element>
    ```
 4. If the element belongs to any content categories (flow, phrasing, etc.), add it
-   to the appropriate categories in `src/spec-common.contents.json` -- otherwise
+   to the appropriate categories in `src/spec-common.contents.jsonc` -- otherwise
    `@markuplint/rules`' `permitted-contents` rule will not recognize it as valid
    content in parent elements that allow those categories
 5. Run `yarn workspace @markuplint/html-spec run gen`
@@ -63,7 +63,7 @@ will cause the element to be silently excluded from the build output.
 
 ### 2. Modifying an Existing Element's Attributes
 
-1. Open the relevant `src/spec.<element>.json`
+1. Open the relevant `src/spec.<element>.jsonc`
 2. Add or modify entries in the `attributes` object
 3. For conditional attributes, add a `condition` field with a CSS selector:
    ```json
@@ -77,7 +77,7 @@ will cause the element to be silently excluded from the build output.
 
 ### 3. Adding an SVG Element
 
-1. Create `src/spec.svg_<localname>.json` (e.g., `src/spec.svg_circle.json`)
+1. Create `src/spec.svg_<localname>.jsonc` (e.g., `src/spec.svg_circle.jsonc`)
 2. The element name will be inferred as `svg:<localname>` (e.g., `svg:circle`)
 3. Use SVG-specific global attribute categories:
    ```json
@@ -100,7 +100,7 @@ will cause the element to be silently excluded from the build output.
 
 ### 4. Updating Global Attribute Categories
 
-1. Edit `src/spec-common.attributes.json`
+1. Edit `src/spec-common.attributes.jsonc`
 2. Each top-level key is a category (e.g., `#HTMLGlobalAttrs`)
 3. Add, remove, or modify attribute definitions within the category
 4. Run `yarn workspace @markuplint/html-spec run gen`
@@ -108,7 +108,7 @@ will cause the element to be silently excluded from the build output.
 
 ### 5. Adding or Updating Content Model Categories
 
-1. Edit `src/spec-common.contents.json`
+1. Edit `src/spec-common.contents.jsonc`
 2. Add a new entry to the `models` object or add elements to existing categories:
    ```json
    "#newCategory": ["element1", "element2", "svg|element3"]
@@ -131,7 +131,7 @@ will cause the element to be silently excluded from the build output.
 
 ### 6. Updating ARIA Mappings
 
-1. Open the relevant `src/spec.<element>.json`
+1. Open the relevant `src/spec.<element>.jsonc`
 2. Modify the `aria` object:
    - Change `implicitRole` for the default role
    - Update `permittedRoles` array
@@ -197,7 +197,7 @@ If the diff reveals a substantive change to element behavior, ARIA mappings, or
 content models, the manual spec files may need updating:
 
 1. Identify which elements are affected
-2. Update the relevant `src/spec.*.json` or `src/spec-common.*.json` files to
+2. Update the relevant `src/spec.*.jsonc` or `src/spec-common.*.jsonc` files to
    reflect the new specification. In rare cases, `@markuplint/ml-spec` schemas
    or types may also need updating.
 3. Regenerate to incorporate the manual spec changes:
@@ -208,7 +208,7 @@ content models, the manual spec files may need updating:
    output before committing:
    ```bash
    # Stage spec files and index.json
-   git add packages/@markuplint/html-spec/src/spec.*.json packages/@markuplint/html-spec/index.json
+   git add packages/@markuplint/html-spec/src/spec.*.jsonc packages/@markuplint/html-spec/index.json
    # Regenerate
    yarn up:gen
    # Check that the attributes you changed are NOT in the diff (= stable output)
@@ -255,12 +255,12 @@ Obsolete elements automatically get:
 
 ### Editable Files (modify these)
 
-| File                              | Description                            |
-| --------------------------------- | -------------------------------------- |
-| `src/spec.*.json`                 | Per-element specifications (177 files) |
-| `src/spec-common.attributes.json` | Global attribute category definitions  |
-| `src/spec-common.contents.json`   | Content model category macros          |
-| `build.mjs`                       | Build script configuration             |
+| File                               | Description                            |
+| ---------------------------------- | -------------------------------------- |
+| `src/spec.*.jsonc`                 | Per-element specifications (177 files) |
+| `src/spec-common.attributes.jsonc` | Global attribute category definitions  |
+| `src/spec-common.contents.jsonc`   | Content model category macros          |
+| `build.mjs`                        | Build script configuration             |
 
 ### Generated Files (DO NOT EDIT)
 
@@ -283,8 +283,8 @@ The test file `test/structure.spec.mjs` validates:
 
 1. **Structure test**: Ensures all elements can be resolved via `resolveNamespace()` and `getAttrSpecsByNames()`
 2. **Schema tests**: Validates source JSON files against JSON schemas from `@markuplint/ml-spec`:
-   - `spec.*.json` files against `element.schema.json` (with aria, content-models, global-attributes, attributes, and types schemas)
-   - `spec-common.attributes.json` against `global-attributes.schema.json`
+   - `spec.*.jsonc` files against `element.schema.json` (with aria, content-models, global-attributes, attributes, and types schemas)
+   - `spec-common.attributes.jsonc` against `global-attributes.schema.json`
 
 The schema validation uses `ajv` (Another JSON Schema Validator) with multiple
 interrelated schemas loaded together. The element schema references the aria,
@@ -376,14 +376,14 @@ grep -A5 '"accept"' index.json
 **Resolution**:
 
 - Verify the file exists: `src/spec.<element>.json`
-- Check file naming: must match `spec.*.json` glob pattern
-- For SVG: must be `spec.svg_<name>.json`
+- Check file naming: must match `spec.*.jsonc` glob pattern
+- For SVG: must be `spec.svg_<name>.jsonc`
 
 ### JSON Comment Syntax Errors
 
 **Symptom**: Build fails with a JSON parse error.
 **Cause**: Spec files support JavaScript-style comments (`//` and `/* */`) via
-`strip-json-comments`, but other non-standard JSON syntax is not supported.
+`jsonc-parser`, but other non-standard JSON syntax is not supported.
 **Resolution**:
 
 - Ensure trailing commas are not present