DOM Node APIs by Freddy03h · Pull Request #844 · rescript-react-native/rescript-react-native

Freddy03h · 2026-03-10T15:27:40Z

Blog Post : Starting from React Native 0.82, native components will provide DOM-like nodes via refs.
Documentation : Nodes from refs

I tried to follow the approach used in experimental-rescript-webapi but I hope this rescript feature for tagged variants can be addressed soon, as it would provide a better DX.

In the meantime, I added a NodeTypeHelper module to help with type conversions.
I know it doesn’t follow the zero-runtime binding rule, but while experimenting with experimental-rescript-webapi, I found this kind of helper quite useful, and it would otherwise have to be reimplemented in every project.

Freddy03h · 2026-03-10T15:55:30Z

Migration should be easy if the rescript feature for tagged variants is accepted.

Example with the current PR

let textData = switch element.childNodes
->DOMApi.NodeList.item(0)
->Null.map(node => node->DOMApi.NodeTypeHelper.findNodeType) {
| Null.Value(Text(text)) => text.data
| _ => "not a text node"
}

Example with the rescript feature for tagged variants.

let textData = switch element.childNodes->DOMApi.NodeList.item(0) {
| Null.Value(Text(text)) => text.data
| _ => "not a text node"
}

cknitt · 2026-03-18T07:24:40Z

src/types/DOMAPI.res

+
+module Document = {
+  include Node.Impl({
+    type t = element


Shouldn't that be

Suggested change

type t = element

type t = document

?

cknitt · 2026-03-18T07:24:43Z

src/types/DOMAPI.res

+    | Document(document)
+    | Unknown
+
+  let findNodeType = (node: node) =>


This could be called classify like similar functions in the stdlib. And the module could be NodeType. So that you would have NodeType.classify returning a NodeType.t.

cknitt · 2026-03-18T11:46:12Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9c58b72837

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-18T11:52:39Z

src/elements/NativeElement.res

  type t = element
 })
+
+include DOMAPI.Element.Impl({


Do not expose DOM ref APIs to supported 0.81 apps

NativeElement now includes the new DOM-style methods on every ref, but this package still advertises react-native >=0.81.0 support. React Native only started returning DOM-like nodes from refs in 0.82, so an app that is still on 0.81 can compile against these bindings and then hit undefined is not a function at runtime as soon as it calls one of the newly exposed methods.

Useful? React with 👍 / 👎.

It will be done before release

chatgpt-codex-connector · 2026-03-18T11:52:39Z

src/types/DOMAPI.res

+    @send
+    external compareDocumentPosition: (T.t, node) => int = "compareDocumentPosition"
+    @send external contains: (T.t, node) => bool = "contains"
+    @send external getRootNode: T.t => T.t = "getRootNode"


Return a node from getRootNode

getRootNode() is typed as returning T.t, but for mounted element and text nodes the root is the document node, not another element/text node. The current signature is only correct for the detached-node case mentioned in the React Native docs, so common mounted calls will be typed as element/text and let callers use subtype-specific fields on a document object at runtime.

Useful? React with 👍 / 👎.

Should be node

chatgpt-codex-connector · 2026-03-18T11:52:39Z

src/types/DOMAPI.res

+    type t = document
+  })
+
+  @send external getElementById: (document, string) => element = "getElementById"


Make getElementById nullable

getElementById() can legitimately miss when no native component has the requested id/nativeID, but this binding models it as always returning element. That makes the absence case impossible to express in ReScript and turns a normal lookup miss into a null dereference when consumers immediately access fields or methods on the result.

Useful? React with 👍 / 👎.

good catch, I'll also open a PR on webapi

chatgpt-codex-connector · 2026-03-18T11:52:39Z

src/types/DOMAPI.res

+    type t = text
+  })
+
+  @send external substringData: (text, ~offset: int, ~count: int) => unit = "substringData"


Return the substring from Text.substringData

substringData() returns the extracted text, but the external is declared as unit. As written, the new Text-node binding silently discards React Native's return value, so callers cannot actually read any substring from a text node through this API.

Useful? React with 👍 / 👎.

cknitt · 2026-03-18T14:14:30Z

@Freddy03h I think Codex has some good points here, can you check them?

Freddy03h · 2026-03-19T19:15:54Z

I have a concern:

// NativeElement.res
type element = DOMAPI.element

// ScrollViewElement.res
type element

If I change ScrollView’s element to DOMAPI.element, it means we could use a ScrollView method on a View.
Is there a way to prevent that? Thanks.

cknitt · 2026-03-20T08:18:38Z

That is a good point.

I think we need to keep the element types abstract to avoid this issue, and offer "casts" using %identity, like

scrollViewElement->ScrollViewElement.asNativeElement->NativeElement.asDOMElement

and/or directly

scrollViewElement->ScrollViewElement.asDOMElement

cknitt · 2026-04-06T07:11:23Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7346c82edd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-06T07:19:35Z

src/elements/NativeElement.res

+  include DOMAPI.Element.Impl({
+    type t = element


Gate DOM node APIs to React Native 0.82+

NativeElement.Impl now mixes in DOMAPI.Element.Impl for every native ref, which makes DOM node fields/methods available in all consuming apps even though this package still declares support for React Native >=0.81. The DOM node API was introduced in 0.82, so 0.81 consumers can compile calls like nodeType/childNodes from these bindings and then hit undefined at runtime. Please either raise the minimum supported RN version in this change set or expose these bindings behind a 0.82-specific surface.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-04-06T07:19:35Z

src/types/DOMAPI.res

+  parentElement: Js.Null.t<'element>,
+  parentNode: Js.Null.t<'node>,
+  previousSibling: Js.Null.t<'node>,
+  textContent: string,


Make Node.textContent nullable in DOM node bindings

readOnlyNode.textContent is typed as non-null string, but these bindings are explicitly modeled as web-compatible Node APIs, and Document nodes can return null for textContent. With the current type, callers may treat document.textContent as always present and crash when RN returns null. This field should be Js.Null.t<string> (or equivalent) to match runtime behavior.

Useful? React with 👍 / 👎.

According to the TypeScript types, it shouldn’t be null, but in my React Native tests it was indeed null for document.

cknitt · 2026-04-06T07:56:23Z

We need to make clear that this is a breaking change. I tested the bindings against a project of ours and had to make some adjustments to get it to compile, as it contained bindings for other React Native libs where I was directly using NativeElement.ref, for example.

Also, see the hint from Codex regarding node.textContent.

cknitt · 2026-04-06T07:57:06Z

I think we should release a beta version for broader testing first before doing a release version.

Freddy03h · 2026-04-06T16:23:56Z

What about adding this in NativeElement?

@deprecated(
  "Bindings maintainers: please use NativeElement.Impl instead of accessing the types directly."
)
include Impl({
  type t = DOMAPI.anyElement
})

I’m not sure if deprecation will work in this situation. Maybe we could just keep the existing code and mark each type as deprecated?

cknitt · 2026-04-06T17:15:51Z

I’m not sure if deprecation will work in this situation. Maybe we could just keep the existing code and mark each type as deprecated?

If you add that, I can retest to see if my project can build without any changes then.

Something else, about all those

external asButtonElement: DOMAPI.anyElement => element = "%identity"

etc. - these are actually unsafe (as not every element is a button element). So maybe these should be called unsafeAsButtonElement etc.?

But actually, couldn't this be part of NativeElement.Impl as unsafeFromAnyElement (or something like that)?

cknitt · 2026-04-07T06:03:48Z

Nice! Retested, now the breaking changes for native element handling are gone.

Not really related to this PR, but there is one remaining change that was breaking for me, the change of the return type of AppRegistry.registerComponent to string.
This function just returns the app key that was passed in which does not bring much value, I am wondering if we should revert this change to the binding.

src/elements/NativeElement.res

Freddy03h · 2026-04-07T14:42:00Z

Okay! But did you see the deprecation warning for NativeElement.ref?

cknitt · 2026-04-10T06:32:43Z

No, didn't get the warnings.

fhammerschmidt requested a review from cknitt March 12, 2026 16:36

cknitt reviewed Mar 18, 2026

View reviewed changes

chatgpt-codex-connector bot reviewed Mar 18, 2026

View reviewed changes

Freddy03h marked this pull request as ready for review March 18, 2026 19:15

cknitt previously approved these changes Mar 19, 2026

View reviewed changes

cknitt mentioned this pull request Mar 19, 2026

Codex Review Findings #845

Closed

Freddy03h dismissed cknitt’s stale review via 6ee7907 April 4, 2026 15:13

Freddy03h added 5 commits April 4, 2026 17:15

DOM Node APIs

37af4af

fix ci

589652e

fix type and rename NodeType

ea50e5e

codex review

951414a

dom api phantom-specialized type for element

7346c82

Freddy03h force-pushed the dom-node-api branch from 6ee7907 to 7346c82 Compare April 4, 2026 15:28

Freddy03h requested a review from cknitt April 4, 2026 15:29

chatgpt-codex-connector bot reviewed Apr 6, 2026

View reviewed changes

node textContent could be null

7fb4aba

Freddy03h added 2 commits April 6, 2026 21:20

bring back NativeElement.ref as deprecated

a5887c2

dom api: unsafe conversion helper for elements

70d7e8e

cknitt reviewed Apr 7, 2026

View reviewed changes

src/elements/NativeElement.res Show resolved Hide resolved

fix deprecated for NativeElement.element

56afdd7

Freddy03h requested a review from cknitt April 10, 2026 08:24

change depreated message

a36c34f

cknitt approved these changes Apr 10, 2026

View reviewed changes

Freddy03h merged commit e5bebc6 into main Apr 10, 2026
2 checks passed

Freddy03h deleted the dom-node-api branch April 10, 2026 09:09

Uh oh!

Conversation

Freddy03h commented Mar 10, 2026

Uh oh!

Freddy03h commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cknitt Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

cknitt Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

cknitt commented Mar 18, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Freddy03h Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Freddy03h Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Freddy03h Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

cknitt commented Mar 18, 2026

Uh oh!

Freddy03h commented Mar 19, 2026

Uh oh!

cknitt commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cknitt commented Apr 6, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Freddy03h Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

cknitt commented Apr 6, 2026

Uh oh!

cknitt commented Apr 6, 2026

Uh oh!

Freddy03h commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cknitt commented Apr 6, 2026

Uh oh!

cknitt commented Apr 7, 2026

Uh oh!

Uh oh!

Freddy03h commented Apr 7, 2026

Uh oh!

cknitt commented Apr 10, 2026

Uh oh!

Uh oh!

Reviewers

Freddy03h commented Mar 10, 2026 •

edited

Loading

cknitt commented Mar 20, 2026 •

edited

Loading

Freddy03h commented Apr 6, 2026 •

edited

Loading