Use WHATWG IDL instead of Edge IDL

[chicoxyzzy]

I came from microsoft/TypeScript#3027

This IDL is used as de-facto standard for all major browsers
https://dom.spec.whatwg.org/#idl-index

TypeScript should use this IDL to add and ship features from DOM early from Living Standard.

[chicoxyzzy]

Samples showing why current IDL sucks when writing not just for Edge:

• https://www.typescriptlang.org/play/#src=new%20Text(%22test%22)%3B
• https://www.typescriptlang.org/play/#src=document.append('anything')%3B%0Adocument.prepend('anything')%3B

Even if these features are not in any stable browser developers can use polyfills. So it will be great for TypeScript to know about this interfaces

[chicoxyzzy]

According to microsoft/TypeScript#3027 (comment) TSJS generator should parse WhatWG IDL as well as browser-specific IDLs

[mhegazy]

The script used to generate the dom is available here. we would be happy to look at a PR that generates the same output from the dom spec.

[chicoxyzzy]

Sadly I'm not familiar with F# or any ML language at all but i'll take a look into source code.

I think there should be lib.dom.d.ts file which should include references to lib.whatwg.dom.d.ts, lib.edge.dom.d.ts, lib.chrome.d.ts, etc.

[chicoxyzzy]

Is browser.webidl.xml Edge-specific file? I can't find any references to same files for WebKit, Chrome, FireFox, WhatWG.

[mhegazy]

We get this file from the edge team, if there is a similar resource for other browsers we would be happy to include it. We would also be happy to accept any PRs that generates the declaration file form the standard IDL directelly.

[saschanaz]

Not sure but maybe we can use a WebIDL parser and create corresponding webidl.xml file.

[saschanaz]

Not sure but maybe we can use a WebIDL parser and create corresponding webidl.xml file.

I've started making an experimental tool for this here

[dead-claudia]

One other reason to use the WHATWG IDL is that things like Event.AT_TARGET are of a very uselessly broad type. It should really be something like this, which the WHATWG IDL has most of the proper information for:

// IDL
interface Event {
    const unsigned short NONE = 0;
    const unsigned short CAPTURING_PHASE = 1;
    const unsigned short AT_TARGET = 2;
    const unsigned short BUBBLING_PHASE = 3;
    readonly attribute unsigned short eventPhase;
}

// TS equivalent
interface Event {
    readonly eventPhase: 0 | 1 | 2 | 3;
}
declare var Event: {
    readonly NONE: 0;
    readonly CAPTURING_PHASE: 1;
    readonly AT_TARGET: 2;
    readonly BUBBLING_PHASE: 3;
}

// TS best
declare const enum EventPhase {
    NONE = 0;
    CAPTURING_PHASE = 1;
    AT_TARGET = 2;
    BUBBLING_PHASE = 3;
}
interface Event {
    readonly eventPhase: EventPhase;
}
declare var Event: {
    readonly NONE: EventPhase.NONE;
    readonly CAPTURING_PHASE: EventPhase.CAPTURING_PHASE;
    readonly AT_TARGET: EventPhase.AT_TARGET;
    readonly BUBBLING_PHASE: EventPhase.BUBBLING_PHASE;
}

(It'll need a little assistance in linking the types, but that can just be a change to the generator script.)

[dead-claudia]

Optimally, the Event type should really be like this:

// Actual WHATWG IDL excerpt
[Constructor(DOMString type, optional EventInit eventInitDict),
 Exposed=(Window,Worker)]
interface Event {
  readonly attribute DOMString type;
  readonly attribute EventTarget? target;
  readonly attribute EventTarget? currentTarget;
  sequence<EventTarget> composedPath();

  const unsigned short NONE = 0;
  const unsigned short CAPTURING_PHASE = 1;
  const unsigned short AT_TARGET = 2;
  const unsigned short BUBBLING_PHASE = 3;
  readonly attribute unsigned short eventPhase;

  void stopPropagation();
           attribute boolean cancelBubble; // historical alias of .stopPropagation
  void stopImmediatePropagation();

  readonly attribute boolean bubbles;
  readonly attribute boolean cancelable;
  void preventDefault();
  readonly attribute boolean defaultPrevented;
  readonly attribute boolean composed;

  [Unforgeable] readonly attribute boolean isTrusted;
  readonly attribute DOMTimeStamp timeStamp;

  void initEvent(DOMString type, boolean bubbles, boolean cancelable); // historical
};

dictionary EventInit {
  boolean bubbles = false;
  boolean cancelable = false;
  boolean composed = false;
};

// TS declaration translation
declare const enum EventPhase {
    NONE = 0;
    CAPTURING_PHASE = 1;
    AT_TARGET = 2;
    BUBBLING_PHASE = 3;
}

declare class Event<T extends string> {
    constructor(type: T, eventInitDict: EventInit);
    readonly type: T;
    readonly target: EventTarget | null;
    readonly currentTarget: EventTarget | null;
    composedPath(): EventTarget[];

    readonly static NONE: EventPhase.NONE;
    readonly static CAPTURING_PHASE: EventPhase.CAPTURING_PHASE;
    readonly static AT_TARGET: EventPhase.AT_TARGET;
    readonly static BUBBLING_PHASE: EventPhase.BUBBLING_PHASE;
    readonly static eventPhase: EventPhase;

    stopPropagation(): void;
    cancelBubble: boolean; // historical alias of .stopPropagation
    stopImmediatePropagation(): void;

    readonly bubbles: boolean;
    readonly cancelable: boolean;
    preventDefault(): void;
    readonly defaultPrevented: boolean;
    readonly composed: boolean

    readonly isTrusted: boolean;
    readonly timeStamp: DOMTimeStamp;

    initEvent(type: T, bubbles: boolean, cancelable: boolean); // historical
}

interface EventInit {
  bubbles?: boolean;
  cancelable?: boolean;
  composed?: boolean;
}

Getting there looks much easier using the WHATWG IDL, based on looking at what information they have (it's pretty dense).

[HolgerJeromin]

Perhaps the best solution for the whole Typescript infrastructure would be to get IDL from "all" (?) major (?) rendering engines and merge them into one lib.
If an API / Property is not available in one IDL it should be marked as optional ( | undefined) in the final lib.d.ts to "force" a proper feature detection.

[dead-claudia]

@HolgerJeromin Don't think that's practical for anyone to manage. Also, some engines still have missing and/or incomplete support for existing standards. And automation isn't guaranteed to work when each browser has their own ever-evolving private extended attributes and non-standard syntax extensions for everything (ranging from "implemented in JavaScript" and "is iterable" to "allow cross origin access to this method" and "check security").

[saschanaz]

One difficult point when using WebIDL is that it does not contain event object type. For example:

https://html.spec.whatwg.org/multipage/browsers.html#application-cache-api

[Exposed=(Window,SharedWorker)]
interface ApplicationCache : EventTarget {

  // update status
  const unsigned short UNCACHED = 0;
  const unsigned short IDLE = 1;
  const unsigned short CHECKING = 2;
  const unsigned short DOWNLOADING = 3;
  const unsigned short UPDATEREADY = 4;
  const unsigned short OBSOLETE = 5;
  readonly attribute unsigned short status;

  // updates
  void update();
  void abort();
  void swapCache();

  // events
  attribute EventHandler onchecking;
  attribute EventHandler onerror;
  attribute EventHandler onnoupdate;
  attribute EventHandler ondownloading;
  attribute EventHandler onprogress;
  attribute EventHandler onupdateready;
  attribute EventHandler oncached;
  attribute EventHandler onobsolete;
};

Another table is needed to be parsed to get the types, which is not in any standardized format.

[dead-claudia]

@saschanaz Of course there has to be some sort of major hitch to everything... 😕

[saschanaz]

I decided to temporarily get event data from the existing MSEdge file and am actively working on this.

[saschanaz]

Waiting review on #227.

[saschanaz]

#1034

@github-actions close

[github-actions]

Closing because @saschanaz is one of the code-owners of this repository.