From d3d8ba66015ae56ff094cdeff0d92208cf7762e5 Mon Sep 17 00:00:00 2001 From: Bashamega Date: Wed, 24 Dec 2025 17:22:28 +0200 Subject: [PATCH 1/4] Enhance README.md with KDL patching guidelines and documentation --- inputfiles/README.md | 63 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/inputfiles/README.md b/inputfiles/README.md index cf25bc504..13b79651e 100644 --- a/inputfiles/README.md +++ b/inputfiles/README.md @@ -4,6 +4,67 @@ Some files in this directory are generated. Please do not edit them. This specifically includes: * `idl/*` -* `mdn/*` Feel free to send a pull request with changes to any other files. +Note It is recommended to add your patch use KDL format, continue reading to find out more. + +## Documentation for `patches/` KDL Folder + +The `patches/` directory only contains `.kdl` files that specify modifications ("patches") to the default Web IDL or related specifications, using the [KDL format](https://kdl.dev/). +These modifications are integrated into the build system (see [`src/build/patches.ts`](../src/build/patches.ts) for implementation details). + +### Purpose + +- Fix errors or omissions in upstream IDL data. +- Add or override or remove interfaces, mixins, and enums. +- Apply project-specific features or changes. + +### Editing Policy + +It is **recommended** to document and comment your patch files and their intent. +This helps keep the integration clear and maintainable. + +### Patch File Naming Policy + +When naming a KDL file, use the exact name of the main interface or dictionary as it appears in the official Web IDL specification. For reference and consistency, we recommend verifying names using [https://respec.org/xref/](https://respec.org/xref/). + + +### Structure & Parsing + +- All `.kdl` files in this folder are read and parsed at build time. +- Their structure typically mirrors major Web IDL concepts: + - `enum` + - `interface` + - `interface-mixin` + - `dictionary` + - Members like `event`, `property`, and `method`. + +#### Example Patch File (`patches/tuoach-events.kdl`) +```kdl +interface-mixin GlobalEventHandlers { + // Touch event handlers are intentionally hidden in non-mobile web browsers. + // See w3c.github.io/touch-events#dfn-expose-legacy-touch-event-apis. + property ontouchcancel optional=#true + property ontouchend optional=#true + property ontouchmove optional=#true + property ontouchstart optional=#true +} + +``` + +### How It Works + +The builder (see `src/build/patches.ts`): + +- Locates all KDL files in the `patches/` directory. +- Parses and type-checks them. +- Merges their contents and applies structural transformations over the main IDL dataset. + +See the source or comments in `patches.ts` for precise KDL syntax and advanced features. + +### Notes + +- You can split patches into multiple `.kdl` files if desired. +- All the data in the json and jsonc files will be eventually transformed to KDL, so if possible submit patches to KDL. +- When in doubt, consult `/src/build/patches.ts` for details on supported KDL structure and merging logic. +- If there is a feature that is missing from the KDL parser, feel free to implement it yourself or ping @bashamega to help implement that feature in [this issue](https://github.com/microsoft/TypeScript-DOM-lib-generator/issues/2053), or just add it to the jsonc files. From 4d2df03348ec9fa609f2d0dec3b2a65c833b46a9 Mon Sep 17 00:00:00 2001 From: Kagami Sascha Rosylight Date: Wed, 24 Dec 2025 16:25:30 +0100 Subject: [PATCH 2/4] Update README to include mdn.json file Added mention of 'mdn.json' to README. --- inputfiles/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/inputfiles/README.md b/inputfiles/README.md index 13b79651e..140ef5e20 100644 --- a/inputfiles/README.md +++ b/inputfiles/README.md @@ -4,6 +4,7 @@ Some files in this directory are generated. Please do not edit them. This specifically includes: * `idl/*` +* `mdn.json` Feel free to send a pull request with changes to any other files. Note It is recommended to add your patch use KDL format, continue reading to find out more. From 2b384f1b3d4436d0d87b56c15b922a766057b8ee Mon Sep 17 00:00:00 2001 From: Kagami Sascha Rosylight Date: Wed, 24 Dec 2025 17:07:26 +0100 Subject: [PATCH 3/4] Revise README for KDL patches documentation * Merged notes, structure/parsing and how-to section. Note that we don't "parse KDL" here but rather convert the result. We use third party library for parsing. * Revised the purpose and split it into when-to and when-not-to. * Removed mentions of json/jsonc, I think it should be clear from this doc that we want patches in KDL and not in other ways. --- inputfiles/README.md | 59 ++++++++++++++------------------------------ 1 file changed, 18 insertions(+), 41 deletions(-) diff --git a/inputfiles/README.md b/inputfiles/README.md index 140ef5e20..3c75cb851 100644 --- a/inputfiles/README.md +++ b/inputfiles/README.md @@ -9,38 +9,33 @@ This specifically includes: Feel free to send a pull request with changes to any other files. Note It is recommended to add your patch use KDL format, continue reading to find out more. -## Documentation for `patches/` KDL Folder +## Patches -The `patches/` directory only contains `.kdl` files that specify modifications ("patches") to the default Web IDL or related specifications, using the [KDL format](https://kdl.dev/). -These modifications are integrated into the build system (see [`src/build/patches.ts`](../src/build/patches.ts) for implementation details). +The `patches/` directory contains `.kdl` files that specify modifications ("patches") on top of the Web IDL from web specifications, using the [KDL format](https://kdl.dev/). +These patches are applied by [`patches.ts`](../src/build/patches.ts). -### Purpose +### When to add a patch -- Fix errors or omissions in upstream IDL data. -- Add or override or remove interfaces, mixins, and enums. -- Apply project-specific features or changes. +- Add extra types to the generated types, e.g. type parameters. +- Make types more strict, e.g. replacing a string type into a string literal type. +- Remove features that are not widely supported by web browsers, in case it's not automatically removed. -### Editing Policy +### When not to add a patch -It is **recommended** to document and comment your patch files and their intent. -This helps keep the integration clear and maintainable. +- When the type is incorrect, and that's from an upstream spec. It's recommended to file a bug in the corresponding spec, and when the fix happens, it will be applied here automatically. -### Patch File Naming Policy +### How to write a patch -When naming a KDL file, use the exact name of the main interface or dictionary as it appears in the official Web IDL specification. For reference and consistency, we recommend verifying names using [https://respec.org/xref/](https://respec.org/xref/). +- Try to add a new patch file when the newly desired patch is big, e.g. as long as a whole page. If it's just a few lines then it can usually go into one of the existing files. +- Files are named per their originating web specification. https://respec.org/xref/ helps you search the specifications. If there's no existing patch with that name, you should add one even if the patch will be very small. +- Please add code comment about the intent for the patch, e.g. a feature is removed as it's only implemented in one browser. +- You can largely follow the Web IDL structure but in KDL syntax: + - Most top level types e.g. `enum`, `interface`, or `dictionary` have the same names, but multi-word names like `interface mixin` are hyphened as `interface-mixin`. + - Attributes and operations are called `property` and `method` respectively to follow TypeScript convention. +- If in doubt, feel free to file an issue or request help in [Discord dom-lib-generator channel](https://discord.gg/kRYw84uG). +#### Example (`patches/touch-events.kdl`) -### Structure & Parsing - -- All `.kdl` files in this folder are read and parsed at build time. -- Their structure typically mirrors major Web IDL concepts: - - `enum` - - `interface` - - `interface-mixin` - - `dictionary` - - Members like `event`, `property`, and `method`. - -#### Example Patch File (`patches/tuoach-events.kdl`) ```kdl interface-mixin GlobalEventHandlers { // Touch event handlers are intentionally hidden in non-mobile web browsers. @@ -50,22 +45,4 @@ interface-mixin GlobalEventHandlers { property ontouchmove optional=#true property ontouchstart optional=#true } - ``` - -### How It Works - -The builder (see `src/build/patches.ts`): - -- Locates all KDL files in the `patches/` directory. -- Parses and type-checks them. -- Merges their contents and applies structural transformations over the main IDL dataset. - -See the source or comments in `patches.ts` for precise KDL syntax and advanced features. - -### Notes - -- You can split patches into multiple `.kdl` files if desired. -- All the data in the json and jsonc files will be eventually transformed to KDL, so if possible submit patches to KDL. -- When in doubt, consult `/src/build/patches.ts` for details on supported KDL structure and merging logic. -- If there is a feature that is missing from the KDL parser, feel free to implement it yourself or ping @bashamega to help implement that feature in [this issue](https://github.com/microsoft/TypeScript-DOM-lib-generator/issues/2053), or just add it to the jsonc files. From e1a009dc2fbc54520ba9faf88a1e52e912ab938d Mon Sep 17 00:00:00 2001 From: Kagami Sascha Rosylight Date: Wed, 24 Dec 2025 17:31:23 +0100 Subject: [PATCH 4/4] Move some code description into patches.ts --- src/build/patches.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/build/patches.ts b/src/build/patches.ts index eea32a0de..fb3bbc06d 100644 --- a/src/build/patches.ts +++ b/src/build/patches.ts @@ -1,3 +1,8 @@ +//! This file: +//! - Locates all KDL files in the `patches/` directory. +//! - Parses and type-checks them. +//! - Merges their contents and applies structural transformations over the main IDL dataset. + import { parse, type Value, type Node, Document } from "kdljs"; import type { Enum,