docs(dom): explain element classifiers

Author: jderochervlk

docs/content/docs/api-surface.mdx

@@ -287,6 +287,33 @@ let element: WebAPI.Element.t = WebAPI.Document.createElement("div")
 let node = element->WebAPI.Element.asNode
 ```
 
+### Classifying DOM values
+
+Event libraries and browser APIs sometimes return a type that is broader than the value present at
+runtime. A React form event target, for example, does not tell ReScript whether the target is an
+input, select, or another element. Calling an input-specific API then requires narrowing that value.
+
+Use `classify` instead of repeating an `instanceof` binding and an unchecked `Obj.magic` cast. The
+classifier performs the runtime check and returns the correctly typed value as an `option`.
+
+```ReScript
+let checkInput = target =>
+  switch target->WebAPI.HTMLInputElement.classify {
+  | Some(input) => input->WebAPI.HTMLInputElement.checkValidity
+  | None => false
+  }
+```
+
+The classifier parameter is polymorphic, so a library-owned target can be passed directly without an
+identity cast to a WebAPI type first. `Element.classify`, `Document.classify`,
+`HTMLElement.classify`, and `HTMLInputElement.classify` follow the same contract. Their matching
+`isInstanceOf` functions are available when only a boolean check is needed.
+
+Classification uses the corresponding constructor from `globalThis`. It returns `None` rather than
+raising when that constructor is unavailable in a server or worker environment. Like JavaScript
+`instanceof`, it only recognizes values created in the current realm; values from another window or
+iframe may not match. Enable the `WebAPI.HTML` feature when using the HTML-specific classifiers.
+
 ## Visual Viewport
 
 `Window.visualViewport` returns a nullable `WebAPI.VisualViewport.t`.

docs/content/docs/philosophy.mdx

@@ -53,4 +53,19 @@ 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.
+Converting in the other direction requires proving the runtime type. Broad DOM values commonly come
+from event libraries, selector APIs, or JavaScript bindings that cannot describe the concrete
+interface statically. Use the destination module's `classify` function for that downcast instead of
+calling `Obj.magic` directly.
+
+```ReScript
+switch target->WebAPI.HTMLInputElement.classify {
+| Some(input) => input->WebAPI.HTMLInputElement.checkValidity
+| None => false
+}
+```
+
+Classifiers return an `option` because a runtime value may not implement the requested interface.
+They also return `None` when the browser constructor is unavailable. The checked cast remains inside
+the binding, so application code handles absence explicitly and receives the concrete public `t`
+type only after a successful check.

src/DOM/Document.res

@@ -28,11 +28,29 @@ Creates an instance of the element for the specified tag.
 @scope("globalThis.document")
 external createElement: (string, ~options: string=?) => Element.t = "createElement"
 
+/**
+`isInstanceOf(value)`
+
+Returns whether `value` is a `Document` created in the current JavaScript realm.
+
+This is a runtime check. It returns `false` when `globalThis.Document` is unavailable, such as in
+some server or worker environments.
+*/
 let isInstanceOf = (_: 'value): bool =>
   %raw(`typeof globalThis.Document === "function" && param instanceof globalThis.Document`)
 
 /**
-Returns the value as a Document when it is a Document in the current realm, and None otherwise.
+`classify(value)`
+
+Safely narrows a value from a broad DOM or library type to `Document.t`.
+
+Use this when a JavaScript binding or union-like API can contain a document but cannot express that
+concrete type statically. Returns `Some(document)` when the value is a `Document` in the current
+realm, and `None` when it is not or when the `Document` constructor is unavailable.
+
+```res
+let document = value->Document.classify
+```
 */
 let classify = (value: 'value): option<t> =>
   if value->isInstanceOf {

src/DOM/Element.res

@@ -30,11 +30,32 @@ Returns true if element has an attribute whose qualified name is qualifiedName,
 
 include Impl({type t = t})
 
+/**
+`isInstanceOf(value)`
+
+Returns whether `value` is an `Element` created in the current JavaScript realm.
+
+This is a runtime check. It returns `false` when `globalThis.Element` is unavailable, such as in
+some server or worker environments.
+*/
 let isInstanceOf = (_: 'value): bool =>
   %raw(`typeof globalThis.Element === "function" && param instanceof globalThis.Element`)
 
 /**
-Returns the value as an Element when it is an Element in the current realm, and None otherwise.
+`classify(value)`
+
+Safely narrows a value from a broad DOM or library type to `Element.t`.
+
+Use this when an event target, JavaScript binding, or union-like API cannot express its concrete DOM
+type statically. Returns `Some(element)` when the value is an `Element` in the current realm, and
+`None` when it is not or when the `Element` constructor is unavailable.
+
+```res
+switch value->Element.classify {
+| Some(element) => element->Element.hasAttribute("data-ready")
+| None => false
+}
+```
 */
 let classify = (value: 'value): option<t> =>
   if value->isInstanceOf {

src/HTML/HTMLElement.res

@@ -54,11 +54,32 @@ module Impl = (
 
 include Impl({type t = t})
 
+/**
+`isInstanceOf(value)`
+
+Returns whether `value` is an `HTMLElement` created in the current JavaScript realm.
+
+This is a runtime check. It returns `false` when `globalThis.HTMLElement` is unavailable, such as in
+some server or worker environments.
+*/
 let isInstanceOf = (_: 'value): bool =>
   %raw(`typeof globalThis.HTMLElement === "function" && param instanceof globalThis.HTMLElement`)
 
 /**
-Returns the value as an HTMLElement when it is an HTMLElement in the current realm, and None otherwise.
+`classify(value)`
+
+Safely narrows a value from a broad DOM or library type to `HTMLElement.t`.
+
+Use this when an event target or element-returning API does not distinguish HTML elements from SVG
+or other element kinds. Returns `Some(element)` for an `HTMLElement` in the current realm, and
+`None` when the value is not an HTML element or when the `HTMLElement` constructor is unavailable.
+
+```res
+switch value->HTMLElement.classify {
+| Some(element) => element->HTMLElement.focus
+| None => ()
+}
+```
 */
 let classify = (value: 'value): option<t> =>
   if value->isInstanceOf {

src/HTML/HTMLInputElement.res

@@ -2,11 +2,32 @@ type t = DOM.htmlInputElement = private {...DOM.htmlInputElement}
 
 include HTMLElement.Impl({type t = t})
 
+/**
+`isInstanceOf(value)`
+
+Returns whether `value` is an `HTMLInputElement` created in the current JavaScript realm.
+
+This is a runtime check. It returns `false` when `globalThis.HTMLInputElement` is unavailable, such
+as in some server or worker environments.
+*/
 let isInstanceOf = (_: 'value): bool =>
   %raw(`typeof globalThis.HTMLInputElement === "function" && param instanceof globalThis.HTMLInputElement`)
 
 /**
-Returns the value as an HTMLInputElement when it is an HTMLInputElement in the current realm, and None otherwise.
+`classify(value)`
+
+Safely narrows a value from a broad event target or element type to `HTMLInputElement.t`.
+
+Use this for values such as React form event targets, which are typed more broadly than the input
+element that emitted the event. Returns `Some(input)` for an `HTMLInputElement` in the current realm,
+and `None` when the value is not an input or when the `HTMLInputElement` constructor is unavailable.
+
+```res
+switch target->HTMLInputElement.classify {
+| Some(input) => input->HTMLInputElement.checkValidity
+| None => false
+}
+```
 */
 let classify = (value: 'value): option<t> =>
   if value->isInstanceOf {