Merge pull request #14 from rescript-lang/extract-event-target

Extract reusable functions in inheritance

Author: nojaf

docs/content/docs/contributing/api-modelling.mdx

@@ -1,7 +1,7 @@
 ---
 title: API Modelling
 description: Learn more about the API modelling process of @rescript/webapi.
-slug: "04-api-modelling"
+slug: "05-api-modelling"
 ---
 
 import { Aside, Code, Icon } from "@astrojs/starlight/components";

docs/content/docs/contributing/module-structure.mdx renamed to docs/content/docs/contributing/api-module-structure.mdx

@@ -1,7 +1,7 @@
 ---
-title: Module Structure
-description: Learn more about the module structure of @rescript/webapi.
-slug: "02-module-structure"
+title: API Module Structure
+description: Learn more about the API module structure of @rescript/webapi.
+slug: "02-api-module-structure"
 ---
 
 import { Aside } from "@astrojs/starlight/components";

docs/content/docs/contributing/code-generation.mdx

@@ -1,7 +1,7 @@
 ---
 title: Code Generation
 description: Learn more about the code generation process for @rescript/webapi.
-slug: "03-code-generation"
+slug: "04-code-generation"
 ---
 
 The original bindings were generated using a modified version of [TypeScript-DOM-lib-generator](https://github.com/microsoft/TypeScript-DOM-lib-generator).

docs/content/docs/contributing/documentation.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Documentation"
 description: Learn more about the relevance of adding documentation to @rescript/webapi.
-slug: "06-documentation"
+slug: "07-documentation"
 ---
 
 After the bindings are generated, all you got was a link to the MDN documentation.  

docs/content/docs/contributing/module-type-structure.mdx

@@ -0,0 +1,86 @@
+---
+title: Module Type Structure
+description: Learn more about the module structure of @rescript/webapi.
+slug: "03-module-type-structure"
+---
+
+import { Aside, FileTree, Code } from "@astrojs/starlight/components";
+
+Every interface in a Web API module can potentially contain methods. These methods are modeled in a separate module named after the interface.
+
+The primary reason for this separation is to handle method overloads.
+As explained in the [Design Philosophy](../design-philosophy) section, ReScript does not permit records to define the same properties more than once.
+Therefore, methods with overloads cannot be modeled within the same record type.
+
+## Bindings
+
+Another advantage of having a separate file is that these bindings can utilize all types defined in the API module.
+Under normal circumstances, the type module only contains `@send` bindings where the type is the first parameter.
+
+<FileTree>
+
+- DOMAPI
+  - HTMLButtonElement.res
+
+</FileTree>
+
+```ReScript
+/**
+Returns whether a form will validate when it is submitted, without having to submit it.
+[Read more on MDN](
+  https://developer.mozilla.org/docs/Web/API/HTMLButtonElement/checkValidity)
+*/
+@send
+external checkValidity: htmlButtonElement => bool = "checkValidity"
+```
+
+## Inheritance
+
+When an interface inherits from another interface, the base interface methods can be [included](https://rescript-lang.org/syntax-lookup#include) into the inheriting interface.  
+All methods from [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement#instance_methods) should also be available on [HTMLButtonElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement#instance_methods).
+
+export const htmlElementModule = `
+open DOMAPI
+
+// A concrete type for \`T.t\` is passed later using the \`include\` keyword.
+module Impl = (T: { type t }) => {
+
+/**
+[Read more on MDN](https://developer.mozilla.org/docs/Web/API/HTMLElement/focus)
+*/
+@send
+external focus: (T.t, ~options: focusOptions=?) => unit = "focus"
+
+}
+
+include Impl({ type t = htmlElement })
+`;
+
+<Code
+  code={htmlElementModule}
+  title="DOMAPI/HTMLElement.res"
+  lang="ReScript"
+></Code>
+
+export const buttonModule = `
+open DOMAPI
+
+// Include all the methods from HTMLElement
+include HTMLElement.Impl({ type t = htmlButtonElement })
+
+// Add additional methods specific to HTMLButtonElement:
+
+/**
+Returns whether a form will validate when it is submitted, without having to submit it.
+[Read more on MDN](
+  https://developer.mozilla.org/docs/Web/API/HTMLButtonElement/checkValidity)
+*/
+@send
+external checkValidity: htmlButtonElement => bool = "checkValidity"
+`;
+
+<Code
+  code={buttonModule}
+  title="DOMAPI/HTMLButtonElement.res"
+  lang="ReScript"
+></Code>

docs/content/docs/contributing/testing.mdx

@@ -1,7 +1,7 @@
 ---
 title: Testing
 description: Learn more about testing the bindings for @rescript/webapi.
-slug: "05-testing"
+slug: "06-testing"
 ---
 
 import { Aside, FileTree } from "@astrojs/starlight/components";

src/CSSFontLoadingAPI/FontFaceSet.js

@@ -1,85 +1,9 @@
 open EventAPI
 open CSSFontLoadingAPI
 
-external asEventTarget: fontFaceSet => eventTarget = "%identity"
-/**
-Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
-
-The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.
-
-When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.
-
-When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
-
-When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.
-
-If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.
-
-The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener)
-*/
-@send
-external addEventListener: (
-  fontFaceSet,
-  ~type_: eventType,
-  ~callback: eventListener<'event>,
-  ~options: addEventListenerOptions=?,
-) => unit = "addEventListener"
-
-/**
-Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
-
-The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.
-
-When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.
-
-When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
-
-When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.
-
-If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.
-
-The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener)
-*/
-@send
-external addEventListener2: (
-  fontFaceSet,
-  ~type_: eventType,
-  ~callback: eventListener<'event>,
-  ~options: bool=?,
-) => unit = "addEventListener"
-
-/**
-Removes the event listener in target's event listener list with the same type, callback, and options.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener)
-*/
-@send
-external removeEventListener: (
-  fontFaceSet,
-  ~type_: eventType,
-  ~callback: eventListener<'event>,
-  ~options: eventListenerOptions=?,
-) => unit = "removeEventListener"
-
-/**
-Removes the event listener in target's event listener list with the same type, callback, and options.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener)
-*/
-@send
-external removeEventListener2: (
-  fontFaceSet,
-  ~type_: eventType,
-  ~callback: eventListener<'event>,
-  ~options: bool=?,
-) => unit = "removeEventListener"
-
-/**
-Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent)
-*/
-@send
-external dispatchEvent: (fontFaceSet, event) => bool = "dispatchEvent"
+include EventTarget.Impl({
+  type t = fontFaceSet
+})
 
 /**
 [Read more on MDN](https://developer.mozilla.org/docs/Web/API/FontFaceSet/add)

src/CSSFontLoadingAPI/FontFaceSet.res

@@ -9,85 +9,9 @@ open FileAPI
 @new
 external make: (~width: int, ~height: int) => offscreenCanvas = "OffscreenCanvas"
 
-external asEventTarget: offscreenCanvas => eventTarget = "%identity"
-/**
-Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
-
-The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.
-
-When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.
-
-When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
-
-When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.
-
-If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.
-
-The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener)
-*/
-@send
-external addEventListener: (
-  offscreenCanvas,
-  ~type_: eventType,
-  ~callback: eventListener<'event>,
-  ~options: addEventListenerOptions=?,
-) => unit = "addEventListener"
-
-/**
-Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
-
-The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.
-
-When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.
-
-When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
-
-When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.
-
-If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.
-
-The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener)
-*/
-@send
-external addEventListener2: (
-  offscreenCanvas,
-  ~type_: eventType,
-  ~callback: eventListener<'event>,
-  ~options: bool=?,
-) => unit = "addEventListener"
-
-/**
-Removes the event listener in target's event listener list with the same type, callback, and options.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener)
-*/
-@send
-external removeEventListener: (
-  offscreenCanvas,
-  ~type_: eventType,
-  ~callback: eventListener<'event>,
-  ~options: eventListenerOptions=?,
-) => unit = "removeEventListener"
-
-/**
-Removes the event listener in target's event listener list with the same type, callback, and options.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener)
-*/
-@send
-external removeEventListener2: (
-  offscreenCanvas,
-  ~type_: eventType,
-  ~callback: eventListener<'event>,
-  ~options: bool=?,
-) => unit = "removeEventListener"
-
-/**
-Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.
-[Read more on MDN](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent)
-*/
-@send
-external dispatchEvent: (offscreenCanvas, event) => bool = "dispatchEvent"
+include EventTarget.Impl({
+  type t = offscreenCanvas
+})
 
 /**
 Returns an object that exposes an API for drawing on the OffscreenCanvas object. contextId specifies the desired API: "2d", "bitmaprenderer", "webgl", or "webgl2". options is handled by that API.