webref

Each event object returned by listAll() contains the following properties:

• type: The name of the event.
• interface: The Web IDL interface used by the event.
• targets: A non-empty list of objects describing where the event may fire. Each target object includes:
  • target: The name of the interface.
  • bubbles: (Optional) A boolean indicating if the event bubbles. This is only set for interfaces belonging to a bubbling tree (e.g., DOM, IndexedDB, Serial API, Web Bluetooth).
  • bubblingPath: (Optional) A list of core interfaces on which the event can theoretically bubble. This is only set when the event effectively bubbles.
• href: (Optional) A URL to the event's definition in a specification.
• src: (Optional) A description of where the extraction first detected the event in the spec.

Note on Bubbling: The bubblingPath contains core interfaces like ["Node", "Document", "Window"]. While an event might fire on a specific element like HTMLSelectElement, the path represents the theoretical bubbling hierarchy. Actual bubbling behavior depends on the inheritance of the target interface.

const events = require('@webref/events');

events.listAll().then(all => {
  for (const event of all) {
    console.log(`Event type=${event.type}
      interface=${event.interface}
      targets=${event.targets
        .map(t => t.target + (t.bubbles === undefined ? '' : ` (bubbles: ${t.bubbles})`))
        .join(', ')}`);
  }
});

Webref provides curated extracts of web platform definitions (Web IDL, CSS, Elements, Events, and CDDL) with specific quality guarantees. Consumers can rely on these guarantees to ensure the data is syntactically valid, uniquely defined, and correctly linked to official specifications.

Web IDL extracts

• Parsable by the version of webidl2.js in package.json.
• Passes WebIDL2.validate (except for the [LegacyNoInterfaceObject] rule).
• All types and extended attributes are defined by a specification.
• No duplicate top-level definitions, mismatched types in inheritance, or conflicts in mixins/partials.

CSS extracts

Note: Since @webref/css version 7, CSS data is provided via a single consolidated ed/css.json file rather than per-spec extracts.

• All syntax values are parsable by the CSSTree version in peerDependencies.
• Feature names (name keys) are unique per type (considering the for key).
• All features targeted by for, legacyAliasOf, longhands, and resetLonghands are guaranteed to exist.
• Every feature includes an href key targeting the base CSS specification.
• All URLs in href and extended keys are guaranteed to exist in the web-specs version used during extraction.

Elements extracts

• All Web IDL interfaces referenced by elements exist in the Web IDL extracts.
• All elements link back to their definition in the specification.

Events extracts

Provided via the consolidated ed/events.json in the @webref/events package:

• type matches the event name.
• interface describes the actual Web IDL interface (not a mixin) and exists in the latest @webref/idl version at release.
• targets is a non-empty list of target interfaces (actual interfaces, not mixins) existing in the latest @webref/idl.
• bubbles is a boolean for target interfaces in a bubbling tree (DOM, IndexedDB, etc.) and is only set for such interfaces.
• bubblingPath is only set if the event actually bubbles on that interface.
• targets contains the top-most interface in an inheritance chain (unless bubbling differs) and the deepest interface in a bubbling tree on which the event may fire.

CDDL extracts

• All CDDL files pass analysis by the Strudy version in package.json (parsable by cddlparser).
• Note: CDDL extracts are not currently released as an NPM package.

The @webref/idl package provides several technical guarantees regarding the quality and consistency of the scraped Web IDL definitions:

Parsing Guarantees

• All IDL files are guaranteed to be parsable by the version of webidl2.js specified in the package's peerDependencies.
• WebIDL2.validate passes for all files, with the single exception of the no-nointerfaceobject rule (due to the wide use of [LegacyNoInterfaceObject]).

Structural Guarantees

• All types and extended attributes are defined by a specification.
• There are no duplicate top-level definitions or members.
• Inheritance chains contain no missing or mismatched types.
• There are no conflicts when applying mixins and partials.

Limitations (What is NOT guaranteed)

• Extended attribute values are not validated.
• No other guarantees are provided beyond those enforced by the package's internal tests.

The @webref/css package provides several structural and parsing guarantees:

• CSSTree Compatibility: All values in the CSS files can be parsed by the version of CSSTree specified in the package's peerDependencies.
• Uniqueness: No duplicate definitions of entries (properties, at-rules, selectors, types, or functions) exist in the CSS files, provided that delta specs (files ending in -n.json) are not included.
• Base Definitions: CSS extracts contain base definitions for all properties; other definitions that extend these will use the newValues key.
• Traceability: Most entries under properties[], properties[].values[], selectors[], atrules[], and values[] include an href key containing an absolute URL with a fragment pointing to the original specification definition.

Exceptions to Traceability:

• Properties that have a newValues key.
• At-rules that lack both a prose and a value key.
• Definitions from a delta spec that completely override a previous level's definition.