Extensibility / Plugin API

[axyz]

I would like to start a conversation to assess how RSD can enable third party extensions. cc @martinbooth

related: #4 (comment)

Contribution to the core have a high friction (for good reasons) given the goal of adhere closely to web standards and avoid performance penalties and breaking changes.

This friction can be a problem when it comes to community adoption where, in many real world scenarios, there is a need for pragmatic short term solutions while long term goal are gradually implemented.

There are several use cases that could benefit the project:

• allow for fast explorations on external packages. Missing capabilities could be implemented even if not fully spec compliant, and competing solutions can develop independently, leading to a higher quality state for a possible future inclusion in core
• escape hatches for immediate needs can be implemented as private extensions instead of requiring forking or patching the core library
• core capabilities can be refactored for better modularity and testability. Having capabilities implemented via an extension API also offer a form of documentation and examples on how to implement other capabilities without having to dig deep into the internals.
• certain capabilities may never make it into web specs, and community extensions could fill the gap in the long run by leveraging the RN ecosystem, while keeping first class interop with RSD
• (ambitious) in theory we could also allow other ways to author style (e.g. other css in js approaches, classes like in nativewind, props like tamagui, etc.), by formalizing the intrmediate style type and treting styles as one of the possible adapters fro authoring to the intermediate style. This is more of a very stretch goal, but could be interesting to explore to allow a wider variety of codebases to migrate to RSD in the future

---

On a high level I'm thinking of an extension API that allow to hook into different phases of the RSD lifcycyle

e.g. syntax extension (e.g. new props or styles) -> transform styles before resolution -> transform after resolution (e.g. after text inheritance, font scaling, interactive states, etc.)

RSD code is already structured in a way that could allow this kind of extensions and that's how certain capabilities work, the main difference would be exposing the API and move to "phases" injection rather than manual addition of the different transformations.

There are also some quick wins we could get in the short term, while gradually enabling more complex types of extensions, for example improving compat.native to support mapped style props, allowing to forward native props to RSD element based on a contract defined by a well scoped extension (e.g. some a11y extension to bridge the existing gaps).

Then subsequent phases can gradually allow things like adding polyfill for html.* elements, polyfill for css features, etc.

---

I'd like to hear your thoughts on this and eventually decide if is worth an exploratory POC, prioritizing quick wins like an improved compat.native and a basic extension registry for simple use cases like forwarding props on a given platform.

[yudin-s]

I like the direction, but I would start with a deliberately narrow extension surface.

The main risk is that a broad plugin API can accidentally make RSD’s invariants optional: spec-aligned behavior, predictable style resolution, low runtime cost, and cross-platform consistency. If extensions can hook every phase freely, core behavior becomes hard to reason about and hard to optimize.

A safer first version could expose only a few stable contracts:

1. prop forwarding
   map/allow platform-specific native props for known elements

2. style prop normalization
   accept extension-owned authoring props and convert them into RSD's intermediate style shape

3. element/component adapters
   map an html.* element or compat.native target to a known native implementation

4. diagnostics
   warn when an extension uses unsupported/spec-divergent behavior

I would avoid exposing “post-resolution mutation” too early unless the resolved style representation is already considered stable. That phase is likely where text inheritance, interaction states, font scaling, and platform differences become subtle.

For a POC, compat.native seems like the right place to begin because it solves a real adoption problem without opening the entire style pipeline:

createStrictDomExtension({
  name: "a11y-native-props",
  nativeProps: {
    html.button: ["accessibilityRole", "accessibilityState"],
  },
  mapStyleProps: {
    // extension-owned props -> standard/intermediate style
  },
})

I would also make extensions explicit at the app boundary, not implicit package side effects:

configureReactStrictDOM({
  extensions: [a11yExtension, nativeInteropExtension],
})

That keeps the behavior auditable and makes it easier to answer “why does this prop/style work in this app?”.

Longer term, an extension registry could be useful, but the first milestone should probably be: one or two core-maintained example extensions, tests proving they cannot break unrelated style resolution, and a clear policy for what is allowed to remain non-spec-compliant.

[axyz]

I made a list of possible use cases for extensions to validate possible approaches.

native interop

extensions are probably not needed here, but a lot can be achieved improving compat.native and possibly adding som utility function to process "strict props" even without compat wrappers. Main use cases are multiple style props, and clear separation of props that are transformed/consumed by RSD and those that are not.

props passthrough

basically an escape hatch to passthrough certain props that are not valid according to web spec, but are needed on the native side. This is likely simple in terms of implementation, but could be quite complex in terms of typing...

• may need a simple API to forward, drop, rename props. Possibly differently per platform (ios, android, web, ++)
• no clue how typing may work.. may need some non ergonomi cinline casting, or some wrapping of the exported react-strict-dom elements... Or possibly (at least in typescript) provide some declare override at registration type. Or maybe have extensions provide a function with a special type that can be spread into strict elements...

svg support

https://github.com/efoken/react-strict-dom-svg is overall a good approach here, alternative approaches can be explored in parallel without affecting each other.

The question is what utilis are missing to make it easier to maintain and behave more correctly?

• improved utilis for native interop could help here allowing to correctly funnel props through the RSD pipeline
• some platform specific prop renaming via prop passthrough API can also be useful
• can be a way to validate the statement "can I process props via RSD on arbitrary components?"

resize observer / intersection observer

Global methods often require to use native refs as arguments (being it the actual DOM node on web or the react-native element ref). For the case of IntersectionObserver the problem is very relevant as it is now an avaialble API in the newe version of RN.

• may need some utility to operate with strict refs, so that global methods can be "polyfilled" even with thin wrappers that handle the refs interoperability.
• in the case of resize Observer (not available in RN) may also have to expose refs methods to work with layout changes

html.dialog

• injecting html.* exports may be complex unless html itself becomes a dynamic provider of components (and likely a typing nightmare). On the other hand we could preemptively allow every valid html component and warn on unimplemented usages, but allow extensions to take over that runtime check with their own implementation
• better compatnative and possible utilities to work on strict props may be enough
• may need a way to decorate refs (for open/close methods and similar)

input type date

kind of similar to dialog, but hooking into available "variants" based on type props. Most pragrmatic approach could be to treat each variant as its own runtime checked component and allow extensions to take over each conditional branch as it it was its own component

Would be nice to avoid the patch and implement such sub-optimal polyfills as small extensions.

• would need extension registration to accept config options (to map font cuts)
• need to mark style props as valid
• need to hook into useStyleProps to replace font-family according to the resolved (including style inheritance for Text) style props

css animations

what if #428 could be done as an extension?

• need to add a css.keyframes function, this is possibly a tricky one, but we could assume that everything supported in stylex could be allowed typewise and warned at runtime when not available (like it happens with some css styles)
• need to hook into and extend the applied style in useStyleProps
• need to mark additional css styles as "valid" (animation styles are already in stylex types but are filtered out by the currently static isAllowedStyleKey
• need to decorate strict refs (to add animation control methods to nodes)

container queries

• also need to mark container queries related styles supported in stylex as "available"
• need to hook into at rules parsing logic
• need a mechanism to inject context providers
• need to hook into useStyleProps where would consume the injected context
• may need some generic onLayout utility in core to subscribe to parent changes?

dogfooding (transitions, interactive states, media queries, etc.)

Ideally the same abstractions used to hook into various phases should be used to implement most of the core capabilities. That would make the code more modular and possibly help with testing and benchmarking in isolation each step with some generic utilities for "extensions"

missing events

Many DOM events are not currently available. Polyfilling them via extensions may be challening, but could be possible if we can inject context providers, allowed props, and hook into different phases. But I'm likely missing many steps and oversimplifying, thise could be a stretch goal and realistically could be simpler to contribute directly to core when possible.

variable font custom polyfill

It may take a long time for RN to support variable fonts. For our use case we are currently patching react-strict-dom to mark the style keys as valid, then intercepting them to map certain typographic combinations to static font cuts (at runtime with a hacky in between component to be used in place of any normal Text like component)

alternative styling layer (classNames, props, etc.)

While RSD is currently highly coupled with stylex, in theory it could benefit in using a intermediate typed representation of "styles". Stylex could be responsible of translating the user style authoring input (css.create) into the intermediate format that RSD is able to transform and use for building cross platform elements.

This could potentially allow to iterate with other css input methods (e.g. classNames with actual css files parsed at built times, tailwind strings like in nativewind, atomic props like in tamagui, etc.)

---

I tried to order those use cases base on complexity of what is missing, it may help identifying smaller scopes to possibly explore, but I'm also curious to hear your thoughts on each one. I can imagine that some of them could instead be better candidates for direct core contributions, or other may also work well as fully isolated packages, but may have to think about the specific details and see if different approaches can be validated against them.

[martinbooth]

Thanks for this list. I was going to suggest putting together a list like this but you've already captured a lot of use-cases here.

FWIW, I think refs to the native elements are already exposed, at least what is required for them to work with IntersectionObserver which is the nativeTag field.. This may not be typed as such and we should find a way to fix that, but I think it'll work if you suppress the type error.

[axyz]

Thanks for this list. I was going to suggest putting together a list like this but you've already captured a lot of use-cases here.

FWIW, I think refs to the native elements are already exposed, at least what is required for them to work with IntersectionObserver which is the nativeTag field.. This may not be typed as such and we should find a way to fix that, but I think it'll work if you suppress the type error.

yes, I saw the strictRef is cloning the prototype to preserve instanceOf at runtime (https://github.com/facebook/react-strict-dom/blob/main/packages/react-strict-dom/src/native/modules/useStrictDOMElement.js#L60-L61 )

but I suspect that would be hard to "fix" in terms of types? consumers would have to cast somewhere right? I suppose could be hidden in a shared hook to work with IntersectionObserver and similar APIs, but would still likely be a "quirk" to document.

Or do you think there may be a way to satisfy the actual type? My understanding is that it won't be possible unless types start to diverge in native vs web, and that would go against the "strict" part of react-strict-dom...

[axyz]

Trying to summarize some possible next steps.

I think for the short term there are some quick wins that would not require a full blown extension API yet:

• improve compat.native to allow multiple style props mapping
• possibly a hook to split native from strict props
• possibly a hook to get resolved style values within a component

cc @martinbooth do you have any input/concern on these thing and/or a specific API in mind? Otherwise I can find some time and make a draft PR to continue the discussion there.

In a next or parallel phase we can explore how to allow / forward additional props to native. I think it could be relatively simple code wise, but It may get a bit tricky in terms of types, so I would prefer exploring it in a separate PR, and wonder if you have any concrete idea.
In typescript an exported type can be extended with a declare module block (to be verified at what point an extension would inject that), but not sure if there is an equivalent for flow types?

For the mid/long term, for a full extension API, I feel we would need more discussions and possibly benchmark some competing approaches, we can use the list above to evaluate what needs what. I was also thinking that instead of allowing fully arbitrary extensions we could for example merge to main placeholder for web specs already and console warn the unimplemented ones, while offering an API to override existing features (unimplemented or not), as long as they respect the typings, this is similar to what happens with unsupported CSS features.

[axyz]

I was also thinking that instead of allowing fully arbitrary extensions we could for example merge to main placeholder for web specs already and console warn the unimplemented ones

Extending a bit on this idea, it could be a good way to avoid typing issues and guardrail extension to be web spec compliant.
The drawback is the validation of the availability of a feature shifts from typing to console logs, that may not be ideal.

An interesting hybrid approach could be:

• maintain a "spec" folder/sub-package in RSD
• when the user import from the spec (e.g. html dialog spec) then html.dialog gets autocomplete and works in code, but warns about not being implemented
• the user can import (or write locally) a package that uses an API to register an override for a given component or css style
• the implementation can be anything, but must respect the types from the spec.

This allow freedom of competing implementation for any feature, guaranteeing that any code can always be swapped to another implementation or a core reference one when available.

something like:

// packages/react-strict-dom/specs/dialog.d.ts

export interface StrictReactDOMDialogProps extends StrictReactDOMProps {
  open?: boolean;
  onClose?: (event: React.SyntheticEvent<HTMLDialogElement>) => void;
  onCancel?: (event: React.SyntheticEvent<HTMLDialogElement>) => void;
}

// Module augmentation: adds 'dialog' to the existing 'html' export in TS
declare module 'react-strict-dom' {
  export namespace html {
    export const dialog: React.ComponentType<StrictReactDOMDialogProps>;
  }
}

// packages/react-strict-dom/specs/dialog.js

const DialogStub = (props: StrictReactDOMDialogProps) => {
  const extension = getExtensionOverride('dialog');
  if (extension != null) {
    return extension.render({ props, ref: props.ref });
  }

  if (__DEV__) {
    warnMsg(
      '<html.dialog> is a standard spec-compliant element, but is unimplemented ' +
        'on this platform. Please import a supporting extension.'
    );
  }
  return null;
};

DialogStub.displayName = 'html.dialog';
registerSpecElement('dialog', DialogStub);
export { DialogStub as Dialog };

and then on extension side:

// @my/rsd-dialog-extension/index.js

import { unstable_registerExtensionOverride } from "react-strict-dom";
import { Modal } from "react-native";

const NativeDialogImplementation = {
  render({ props }) {
    const { open, children, onClose, style, ...restProps } = props;

    return (
      <Modal
        visible={!!open}
        onRequestClose={onClose}
      >
        {/* ... */}
      </Modal>
    );
  }
};

// Registers this implementation in the global RSD registry
unstable_registerExtensionOverride("dialog", NativeDialogImplementation);

and on the consumer side a fully typed:

// index.tsx
import React from "react";

// 1. Enable types and Proxy registration for dialog
import "react-strict-dom/specs/dialog";

// 2. Load the actual native/web runtime override behavior
import "@zds/rsd-dialog-extension";


// ...

<html.dialog><html.h1>Hello</html.h1></html.dialog>

as well as something similar to handle unsupported css features (some of them are already console warning, and may just need a similar way to override the warn with implementations)

This could allow to safely add and iterate on spec compliant types without touching the core types, as well as allowing to create extensions to:

• implement missing features
• use alternative implementation of existing ones
• possibly modularize the core