refactor: clean up public owners and singleton APIs

README.md

@@ -1,9 +1,11 @@
 [![NPM Version](https://img.shields.io/npm/v/@rescript/webapi/experimental)](https://www.npmjs.com/package/@rescript/webapi)
 
-# experimental-rescript-webapi
+# ReScript WebAPI
 
 Experimental successor to [rescript-webapi](https://github.com/TheSpyder/rescript-webapi)
 
+This package requires ReScript 13, which is currently in alpha.
+
 ## Getting started
 
 Install the package using your favorite package manager:
@@ -12,22 +14,56 @@ Install the package using your favorite package manager:
 npm i @rescript/webapi@experimental
 ```
 
-and add `@rescript/webapi` to your `rescript.json`:
+and add `@rescript/webapi` to your `rescript.json` with the features your app uses:
 
 ```json
 {
   "dependencies": [
-    "@rescript/webapi"
+    {
+      "name": "@rescript/webapi",
+      "features": ["WebAPI.Crypto", "WebAPI.Location"]
+    }
   ]
 }
 ```
 
+You can also open the namespace globally if you prefer global access to modules such as `Location` instead of using `WebAPI.Location`. Another option is to use `open WebAPI` when working with the `WebAPI` namespace.
+
+```json
+{
+  "compiler-flags": ["-open WebAPI"]
+}
+```
+
 ## Usage
 
+The package exposes browser APIs under the `WebAPI` namespace. Use the module that owns the
+browser interface, access record fields with `.`, and call global singleton methods directly.
+
+```rescript
+let location = WebAPI.Location.current
+let href = location.href
+
+WebAPI.Location.reload()
+```
+
+With `"-open WebAPI"`, the same code can be written without the `WebAPI.` prefix:
+
 ```rescript
-let location = WebAPI.Window.current->WebAPI.Window.location
+let location = Location.current
 let href = location.href
-location->WebAPI.Location.reload
+
+Location.reload()
+```
+
+Object-owned APIs still use the value as the receiver. For example, if you also enable
+`WebAPI.DOM`, you can work with document and element values like this:
+
+```rescript
+let document = WebAPI.Window.current->WebAPI.Window.document
+let button = document->WebAPI.Document.createElement("button")
+
+button->WebAPI.Element.setAttribute(~qualifiedName="type", ~value="button")
 ```
 
 ## Documentation

docs/content/docs/api-surface.mdx

@@ -4,24 +4,44 @@ description: A practical summary of how to use the public @rescript/webapi modul
 slug: "api-surface"
 ---
 
-The package exposes browser APIs under the `WebAPI` namespace. In normal application code,
-add the package to `rescript.json`:
+The package exposes browser APIs under the `WebAPI` namespace. It requires ReScript 13,
+which is currently in alpha.
+
+In normal application code, add the package to `rescript.json` with the features your app
+uses:
+
+```json
+{
+  "dependencies": [
+    {
+      "name": "@rescript/webapi",
+      "features": ["WebAPI.Crypto", "WebAPI.Location"]
+    }
+  ]
+}
+```
+
+The `features` list controls which Web API source groups are available to your project. Add
+each feature you use, for example `WebAPI.DOM`, `WebAPI.Fetch`, `WebAPI.Crypto`, or
+`WebAPI.Location`.
+
+You can optionally open the namespace globally if you prefer unqualified module names:
 
 ```json
 {
-  "dependencies": ["@rescript/webapi"]
+  "compiler-flags": ["-open WebAPI"]
 }
 ```
 
-Use `WebAPI.Window.current` for the browser `window`. Interface-specific methods live on
-public modules such as `WebAPI.Window`, `WebAPI.Location`, `WebAPI.Document`,
-`WebAPI.Element`, `WebAPI.Request`, and `WebAPI.Response`.
+Global singleton APIs such as `Location`, `Crypto`, and `Performance` expose direct
+functions and properties. Object-owned APIs still use the value as the receiver.
 
 ```ReScript
-let location = WebAPI.Window.current->WebAPI.Window.location
-let href = location.href
+let href = WebAPI.Location.href
+let location = WebAPI.Location.current
+let sameHref = location.href
 
-location->WebAPI.Location.reload
+WebAPI.Location.reload()
 ```
 
 ## Public module shape
@@ -32,11 +52,17 @@ helper modules.
 ```ReScript
 let req: WebAPI.Request.t = WebAPI.Request.fromURL("https://example.com")
 let headers = WebAPI.Headers.make()
-let document = WebAPI.Window.current->WebAPI.Window.document
-let element = document->WebAPI.Document.createElement("button")
+let element: WebAPI.Element.t = WebAPI.Document.createElement("button")
 ```
 
-Generated implementation modules such as `DomTypes`, `FetchTypes`, `EventTypes`, and
+With `"-open WebAPI"`, the same modules can be referenced without the `WebAPI.` prefix:
+
+```ReScript
+let location = Location.current
+let id = Crypto.randomUUID()
+```
+
+Generated implementation modules such as `DOMTypes`, `FetchTypes`, `EventTypes`, and
 `UiEventsTypes` are internal. If you need to name a public type, use the public interface
 module's `t` type when it has one, or use a dedicated public type module. Otherwise, let
 the value type be inferred from constructors and accessors.
@@ -240,29 +266,24 @@ let redirect = WebAPI.Response.redirect(~url="/login", ~status=302)
 
 ## DOM
 
-DOM values are operated on through public interface modules.
+Common document entry points are exposed directly on `WebAPI.Document`, bound to
+`globalThis.document`. DOM object properties use dot syntax, and instance methods stay
+receiver-based through the owner module. When you need to name an element type explicitly,
+use `WebAPI.Element.t`.
 
 ```ReScript
-let document = WebAPI.Window.current->WebAPI.Window.document
-
-let maybeButton = document
-->WebAPI.Document.querySelector("button")
-->Null.toOption
-
-switch maybeButton {
-| Some(button) =>
-  switch button->WebAPI.Element.getAttribute("data-user-id") {
-  | Null.Value(id) => Console.log(id)
-  | Null => Console.log("anonymous")
-  }
-| None => Console.log("button not found")
-}
+let button: WebAPI.Element.t = WebAPI.Document.createElement("button")
+button.id = "save"
+button.className = "primary"
+button.innerHTML = "Save"
+button->WebAPI.Element.setAttribute(~qualifiedName="data-state", ~value="ready")
+let maybeButton = WebAPI.Document.querySelector("#save")->Null.toOption
 ```
 
 Use conversion helpers when moving between related DOM interface types.
 
 ```ReScript
-let element = document->WebAPI.Document.createElement("div")
+let element: WebAPI.Element.t = WebAPI.Document.createElement("div")
 let node = element->WebAPI.Element.asNode
 ```
 

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

@@ -61,13 +61,18 @@ type rec node = {
   // ... more properties
 }
 
-and element = {
-  // duplicated property from node
-  nodeName: string
-  // ... more properties
-}
+and element = Base__Element.t
 ```
 
+Public interface modules own their public `t` type. For example, `Element.res` exposes
+`Element.t`, `Document.res` exposes `Document.t`, and `Location.res` exposes `Location.t`.
+These public `t` types are the names consumers should use in annotations.
+
+When an interface needs a shared structural owner across APIs or inheritance chains, keep
+that shared shape in a base module such as `Base__Element.t`. The public interface module
+then aliases the base shape as its own `t`. Other modules should reference that owner type,
+such as `Element.t`, or the base owner directly only when needed to break structural cycles.
+
 ## Auxiliary Types
 
 Auxiliary types are used to represent types that are not directly related to the Web API but are used in the bindings.

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

@@ -75,3 +75,31 @@ external checkValidity: htmlButtonElement => bool = "checkValidity"
 `;
 
 <Code code={buttonModule} title="DOMAPI/HTMLButtonElement.res" lang="ReScript"></Code>
+
+## Shared Object Bases
+
+Public interface modules expose their own `t` type even when the underlying shape is shared.
+For a shared DOM object base, keep the structural owner in a base module and make the public
+interface module a same-type alias of that base:
+
+```ReScript
+// Base__Element.res
+type t = private {}
+
+// Element.res
+type t = Base__Element.t = private {...Base__Element.t}
+```
+
+This keeps `Element.t` as the public type name while still allowing structural
+types to share the same object identity through the base owner. `Element.Impl` remains reusable for element subtypes,
+and subtype modules should continue to include the nearest base method implementation:
+
+```ReScript
+// HTMLElement.res
+include Element.Impl({type t = HTMLElement.t})
+
+// HTMLButtonElement.res
+include HTMLElement.Impl({type t = DOMTypes.htmlButtonElement})
+```
+
+Use `asElement` when a subtype needs to be passed to a function that expects `Element.t`.

docs/content/docs/index.mdx

@@ -34,30 +34,45 @@ Install the package using your favorite package manager:
   </TabItem>
 </Tabs>
 
-and add `@rescript/webapi` to your `rescript.json`:
+This package requires ReScript 13, which is currently in alpha.
+
+Add `@rescript/webapi` to your `rescript.json` with the features your app uses:
 
 export const rescriptJson = `
 {
   "dependencies": [
-    "@rescript/webapi"
+    {
+      "name": "@rescript/webapi",
+      "features": ["WebAPI.Crypto", "WebAPI.Location"]
+    }
   ]
 }
 `;
 
-<Code lang="json" code={rescriptJson} ins={[3]}></Code>
+<Code lang="json" code={rescriptJson} ins={[4, 5, 6, 7]}></Code>
+
+You can optionally open the namespace globally if you prefer unqualified module names:
+
+export const openWebAPIJson = `
+{
+  "compiler-flags": ["-open WebAPI"]
+}
+`;
+
+<Code lang="json" code={openWebAPIJson}></Code>
 
 ## Usage
 
-After installing the package , you can use bindings for the various Web APIs as defined in [MDN](https://developer.mozilla.org/en-US/docs/Web/API).
+After installing the package, you can use bindings for the various Web APIs as defined in [MDN](https://developer.mozilla.org/en-US/docs/Web/API).
 
 export const rescriptSample = `
-let location = WebAPI.Window.current->WebAPI.Window.location
+let location = WebAPI.Location.current
 
 // Access properties using \`.\`
 let href = location.href
 
-// Invoke methods using the \`->TypeModule.method\`
-location->WebAPI.Location.reload
+// Invoke global singleton methods directly
+WebAPI.Location.reload()
 `;
 
 export const compiledSample = `

docs/content/docs/philosophy.mdx

@@ -6,9 +6,10 @@ slug: "design-philosophy"
 
 The core idea of these ReScript bindings is that each interface is modeled as a record type. Where possible, inheritance is represented using record spreading, and methods are modeled as functions in a separate module. This design allows for greater familiarity with the underlying JavaScript APIs, making it more friendly for newcomers.
 
-## ReScript v12
+## ReScript 13
 
-These bindings utilize new features introduced in ReScript v12; thus, they are not compatible with older versions of ReScript.
+These bindings use feature-gated package dependencies and source groups from ReScript 13,
+which is currently in alpha. They are not compatible with older versions of ReScript.
 
 ## Web APIs
 
@@ -19,11 +20,14 @@ In other words, if you are searching for a specific JavaScript binding, begin yo
 The bindings are exposed under the `WebAPI` namespace with the same flat module structure as the original package.
 
 ```ReScript
-open WebAPI.DOM
-
-let myElement: WebAPI.Element.t = document->WebAPI.Document.createElement("div")
+let myElement: WebAPI.Element.t = WebAPI.Document.createElement("div")
+let id = myElement.id
 ```
 
+Consumers can also configure `rescript.json` with `"compiler-flags": ["-open WebAPI"]`
+when they want to use modules such as `Document`, `Element`, and `Location` without the
+`WebAPI.` prefix.
+
 ## Interfaces
 
 Since ReScript does not have the concept of classes or interfaces, the bindings represent the interfaces as record types. These record types can inherit properties from a "base" type through spreading. This can only be done if there are no circular references in the inheritance chain. If circular references exist, spreading is avoided, and the base properties are duplicated instead.
@@ -34,6 +38,8 @@ Methods are modeled as functions in a separate module. The idea is that these wi
 
 Inherited methods are duplicated in the inheriting module to eliminate the need to cast the type to the base type.
 
+For DOM elements, `WebAPI.Element.t` is the public element type and `WebAPI.Element` is the method module. Most code does not need to annotate the type because functions such as `Document.createElement` and `Document.querySelector` already return it.
+
 ### Overloads
 
 JavaScript supports function overloads, where a function can have multiple signatures. In ReScript, this is not possible, and a method can have multiple bindings with slightly different names. By entering the correct name, tooling should detect all variations of the method.
@@ -43,10 +49,8 @@ JavaScript supports function overloads, where a function can have multiple signa
 In some cases, type conversion will be required. Subtypes can safely be cast to their base type using conversion helpers within their module.
 
 ```ReScript
-open WebAPI.DOM
-
-let element: WebAPI.Element.t = document->WebAPI.Document.createElement("div")
-let node: WebAPI.Node.t = element->WebAPI.Element.asNode
+let element: WebAPI.Element.t = WebAPI.Document.createElement("div")
+let node = element->WebAPI.Element.asNode
 ```
 
 Any other conversions should be treated as unsafe casts and used with caution, because the type system cannot guarantee they are valid at runtime.

docs/content/docs/project-status.mdx

@@ -6,6 +6,7 @@ slug: "project-status"
 
 This project is highly experimental and subject to change.  
 It is a work in progress and might not cover every API.  
+It currently requires ReScript 13, which is also still in alpha.  
 The core idea is to prioritize ground coverage based on community needs.  
 We aim to focus on the most used APIs first and then expand from there.