Childish DOM contemplations

[zudov]

When we started using react-basic, we didn't like some aspects of React.Basic.DOM interface. Having to pass HTML children as a { children } didn't map well to conventional thinking about DOM tree, made hard adding properties to elements that didn't have them before and seemed overly verbose. I haven't found any designated discussion of the DOM interface, so I thought I'll open that issue to gather information.

JSX and createElement

I haven't really dealt with React before, so I had to dig around a bit to understand the motivation behind the current design. Some key points:

• React components would often want to contain some DOM that's passed in by their parent. There is a convention to pass it through children property, unless something more advanced is needed.
• JSX syntax provides a nice sugar on top of that convention. When one writes <Foo><h1>Bar</h1></Foo>, { children: <h1>Bar</h1> } would be passed to Foo.
• For reasons unknown to me, React.createElement chooses to do some magic and allows to pass arbitrary amount of extra arguments that are all fitted into an array and passed to component as children prop.
• Despite that the common usecase is that children prop is an array of JSX elements, it's fairly common to have other types there. React doesn't constrain that in any way (and even provides helpers to help dealing with variously typed children).
• purescript-react-basic keeps the React.Basic.createElement straightforward. It simply takes a props record and if it happens to have a children attribute it will be passed to createElement via apply. In other words it unmagics the weird "convinience" that React.createElement provides.

Please complete me here if I skipped some important details/constraints.

React.Basic.DOM

As I learned DOM interface used to take children as argument, but it was changed to children as property.

I don't think there's such thing as perfect, right, or correct HTML DSL since it's largely a matter of usage scenario, style, and taste. There is always room for improvement and innovation (especially as we get new language features). It would be nice if react-basic provided a DOM interface that stands up to the motto ("opinionated and optimized for the most basic use cases") and expose the data needed to generate third-party DOM interfaces for whomever have different needs/opinions.

What needs to be exposed is the const types (we can put it in types.json and standalone codegen could just load it by url from github). Instead of const voids we can import html-void-elements. That would make it easy enough to make third-party libraries with DOM interfaces. Maybe react-basic could also accept merge requests with alternative DOM flavors (or make a -contrib library) as long as their design is concrete and reasoned.

React.Basic.DOM.Childish

To give it a try I tweaked the codegen slightly and generated a different flavor of HTML DSL. For now it's just committed to our codebase and we switched most of the code to use it. It can be found here. The design decisions are outlined in the commit message.

In this issue I wanted to:

• Discuss what should the default DOM DSL looks like. I don't have any concrete demands on that, but I'd really love to hear about the experience of using react-basic for some view-heavy code. It's also interesting to know how did current design emerge and what was the experience of switching from children-as-argument to children-as-property.
• Get a green light to refactor the codegen a bit. I mainly want to move the types dictionary to types.json and make it so that the codegen spews out the whole module (so that it can be regenerated via node codegen/index.js > src/React/Basic/DOM.purs
• Discuss the preferred policy for "third-party DOM DSLs". Do we want to have them in a main repo or-contrib repo? Standalone libraries in random GitHub accounts or GitHub organization that hosts the "maintained" flavors?

[justinwoo]

For reasons unknown to me, React.createElement chooses to do some magic and allows to pass arbitrary amount of extra arguments that are all fitted into an array and passed to component as children prop.

This is a typical JavaScript practice of slicing on arguments in a function, but has continued to drop in popularity because of the endless confusion of using methods of this signature

Despite that the common usecase is that children prop is an array of JSX elements, it's fairly common to have other types there. React doesn't constrain that in any way (and even provides helpers to help dealing with variously typed children).

The alternative of using classy encoding would be too expensive in codegen and awkward to use when you get errors though.

---

I wouldn't want any changes to React.Basic.DOM itself, but the codegen files should export the consts and this would be useful to have published as an npm package.

[f-f]

Note: me and @vapaj are @zudov's teammates, and the above pretty much summarizes our opinion as well (hence the "we" in his excellent analysis).

As he said, we have switched our new project to the children-as-argument style and it's a net UX improvement: looks better, diffs make sense, and it feels more intuitive.

So we should not exclude switching the main API to it (not on the "breakage" argument at least, since soon we'll have in also the API refactor)

[maddie927]

This isn't too far off from how it used to be. You've also already outlined most of what brought us to decide to switch to the property-based approach. Our custom/higher-level components were all using children or child properties rather than an extra argument and it was a little weird to have two ways of doing things. There were also cases where we used unsafeCreateDOMComponent to fill in any gaps or hacks with the DOM module, and those all used a children prop (we use custom elements like lumi-table a lot).

There's also the type of the children argument/property -- in JS React you can pass a single element or an array of elements (and the other patterns you mentioned already). In our own components when we want the type to be JSX instead of Array JSX we usually name the prop child instead. JS React also allows you to specify both a children prop and still pass extra elements or arrays of elements to createElement. With this API that edge case is never something you need to think about. As you said, the specialness of children really just comes from the JSX syntax and we don't use that syntax in PureScript, so it seemed weird to continue supporting it as a special case.

That's most of the background, but before I add one more opinion of my own I just want to validate what you're doing. The React.Basic.DOM module was designed to be replaceable for a number of reasons:

1. We may eventually move it to another package
2. There's nothing blocking the creation of React.Basic.[ReactNative|VR|tvOS|Material|Primatives|your-component-library] packages
3. Someone may prefer the traditional elem [ ...props ] [ ...children ] API or want to try some other variation like you have

(moving the existing React.Basic.DOM modules into their own package would probably make this more clear)

I agree on the code generation bit as well, though it might be easier to have the codegen create React.Basic.DOM.Generated and re-export that from React.Basic.DOM or something, so the non-generated and generated code aren't in the same file.

Ok, so the last opinion I wanted to add is that I don't think the DOM API matters that much (so merging changes here should probably be done by someone else, or if there's strong consensus). Let me explain why though 🙂

What matters is the component API and how easy it is to create and render custom components. The DOM APIs are the raw gritty details of web development. How often do you write a_ or div_ and just want the defaults? In my experience, basically never. You have to add styles, behavior, test id hooks, aria, etc. If that's being done in multiple places, you can't follow a style guide. The DOM element types aren't specific to your app or business. Also, 300 line render functions are difficult to parse meaning from no matter what the DOM API is. Direct DOM usage is as unsafe for design/UX as FFI is for logic.

We try to hide it away in small bits at the edges. For example, I almost never touch div. We have row and column for layout (basically divs but you can visualize the intent as you read the code or the emitted HTML), custom elements for root component nodes (i.e. lumi-select), and React's fragment for the cases where React requires a single element where we want to render many. You also don't need an entire component to isolate some logic. We use functions defined in where a lot to simplify render. Here's an example from our Select component (planning to open source it anyway).

render props =
      createElement _selectBackend
        { ...
        , onChange: props.onChange
        , value: props.value
        , render: \selectState ->
            lumiSelectElement
              { "class": props.className
              , style: props.style
              , children:
                  [ renderInput props selectState
                  , if selectState.isOpen
                      then renderMenu props selectState
                      else empty
                  ]
              , onClick: Events.handler currentTarget \ct -> do
                  selectState.openSelect
                  focusChildInput ct
              , onFocus: Events.handler_ selectState.openSelect
              }
        }
  where
    renderInput props selectState =
      lumiSelectInputElement
        { children:
            [ renderSelectedValues
            , if Array.null props.value
                then empty
                else renderClearButton
            ]
        }
      where
        renderSelectedValues = ...

        renderNativeInput = ...

        renderClearButton = ...

    renderMenu props selectState = ...
        where
          renderOptions options_ = ...

[zudov]

This is a typical JavaScript practice of slicing on arguments in a function, but has continued to drop in popularity because of the endless confusion of using methods of this signature

Yeah, that is true. What I don't understand is why the lowest primitive for constructing React elements has such interface. The elements/components are taking their children through props.children, React.createElement takes props. Why would it take the children as yet another argument? What happens when I do React.createElement("Foo", { children: ["Bar"] }, "Baz")? I find it confusing.

The alternative of using classy encoding would be too expensive in codegen and awkward to use when you get errors though.

Sorry, I didn't imply classy encoding at all, nor do I see why it would be needed. I've just mentioned one of things that is common to do with React and as it is now purescript-react-basic handles it perfectly well.

I think that React.Basic.createElement is very nice interface, because it simply takes { | props }. That props can have children field of any type, or it might not. The implementation would fiddle with extra arguments of React.createElement to pass those children in. There is no type constraints on props.children which allows to work with the most crazy React practices.

I made createChildishElement preserve that property, so even though it takes children as argument it doesn't constrain their type in any way. They should just be of the type that component expects.

[zudov]

I wouldn't want any changes to React.Basic.DOM itself, but the codegen files should export the consts and this would be useful to have published as an npm package.

Not sure if it really needs an npm package that has to be published and then maintained which is a big liability if it's only needed for weird third-party codegens. I would have just put those consts in json files, and if some third-party wants to use them, they can just load them straight from github and use the data.

That said if there will be an npm package that I can just require, I'll be totally happy with that since it'll be less work for me ;D

[natefaubion]

React's createElement API is the way it is purely because it's an exact translation from JSX syntax. The underlying element API is much simpler, but it is technically undocumented and unstable. See purescript-contrib/purescript-react#152 for some background.

[zudov]

@spicydonuts Thanks a lot for a thorough response. Particularly for sharing your practices. It's very helpful for us.

---

I should mention that at first I've went on it a bit differently and just added an Array JSX argument to the React.Basic.createElement. I realized that it brings a lot of trouble and makes the children property very special and forces its type to be Array JSX. Then I truly appreciated the current design of React.Basic.createElement and went into the direction of having a convinience/shortcut function createChildishElement that simply allows to supply a component (that expects children) property with children given through the argument:

createChildishElement
  :: forall children props
   . ReactComponent { children :: children | props }
  -> { | props }
  -> children
  -> JSX

I've implemented createChildishElement on top of createElement, but it would have been more correct to define createElement in terms of createChildishElement since it does less stuff:

exports.createElement_ = function(el, attrs) {
  var children = attrs && attrs.children;
  return React.createElement.apply(null, [el, attrs].concat(children || []));
}

exports.createChildishElement_ = function(el, attrs, children) {
  return React.createElement.apply(null, [el, attrs].concat(children || []));
};

---

The React.Basic.DOM module was designed to be replaceable for a number of reasons

Yes. I loved how easy it was to switch to alternative DOM module, so this is a very nice thing.

Ok, so the last opinion I wanted to add is that I don't think the DOM API matters that much (so merging changes here should probably be done by someone else, or if there's strong consensus).

I mostly agree on that. Over time I've tried at least a dozen purescript/haskell DOM DSLs and I can't really say that any of them were the best or the worse. All had some annoying things, and nice things. But all of them were pretty usable and my real problems were in different matters. The only API with which really cause me big troubles and WTFs was blaze with its unlawful Monad instance 🙀

That said, some APIs caused me more cringing about how to format them nicely, some were harder to use in certain fashion, some were harder to modify. Yet, all those issues were mainly style/naming/formatting/taste unaligments. One way or the other different interfaces might optimize for different styles, but those are hardly ever a show stopper.

---

In my opinion the existing React.Basic.DOM is a simple API that maps to components straightforwardly and keeps everything uniform. It might be good to have that as default API. I like how you've explained and motivated the idea of building more domain-related abstraction on top of DOM API. I think the existing React.Basic.DOM makes a good point at being the basic lowest-level view API. One can build their domain view APIs straight on top on it, or if it seems necessary drop in another middle layer that will provide more convenient DOM API (for their use case).

---

Our project is now at quite interesting point, since we already have a significant amount of view code, but it was written in fairly straightforward way. I think what we'll do next is try refactoring it taking your commentary in account and see how it comes out.

[zudov]

@natefaubion I guess I see the point. Thanks for the link, this lower-level elements API is interesting,

[mb21]

@zudov You linked to the commit where you introduced the childish HTML DOM DSL. Is this available as a package now somewhere?

(I haven't really started using purescript-react-basic, but the thought of having to type children everywhere makes me hesitate to give it a try for my first purescript project.)