Some concerns and ideas on the OCaml syntax

[glennsl]

I love the idea of a proper lightweight OCaml syntax for React. And I really like how the current syntax looks, at least after the minor improvements I suggested in #105. Unfortunately the looks are quite deceiving, because what looks like ordinary functions are actually rewritten into something entirely different, which breaks my mental model in more or less subtle ways.

More concretely, the issues I see are:

1. The rewriting is scoped to an entire file. Everything in the file that matches a non-trivial pattern is rewritten into something entirely different, which can cause a number of surprising errors in surprising locations.
2. Related to the previous point, I understand the pattern to be instances of function application where the function name is a tag name from a list of more than 100 tags, many of which are very short and very common words.
3. These rewritten functions don't follow normal scoping rules (or any scoping rules really), which means you won't be able to open a module locally to use any of these very short and very common identifiers. Consider for example em 42 in a DSL for CSS.
4. The errors produced by trying to do so is very confusing. Currently em 42 will produce the error prop '' isn't a valid prop for a 'em'. This can, and soon probably will, be improved (Unintuitive error message from PPX: prop '' is not a valid prop for 'foo' #109), but I don't think the problem is sufficiently addressable because it is inherently difficult to understand the context when the rules of the language are broken to this extent.
5. Does not directly support custom elements (web components) (OCaml syntax: support for custom elements (i.e. web components) #111).
6. Or custom attributes (Allow data-* attributes #93).

Then I've also done some thinking, and have come up with two ideas that I think solves all these issues, albeit not without introducing a few issues of its own. But I think it's a good start at least, and hope we can evolve it into something useful. So here goes.

HyperScript notation

HyperScript is a JavaScript library for creating trees of HTML elements declaratively, much like JSX, but without any special syntax. It's just one function named h, which takes the tag name as first argument, then a props object and a list of children E.g:

var h = require('hyperscript')
h('ul', { style: {'background-color': '#f22'} },
  h('li', 'one'),
  h('li', 'two'),
  h('li', 'three'))),

We could do something very similar in OCaml, and it would barely require any changes to the current PPX I think:

React.Fragment.make
  [ h "a" ~href:"https://github.com/jihchi/jsoo-react-realworld-example-app" ~target:"_blank"
      [ h "i" ~className:"ion-social-github" []
      ; React.string "Fork on GitHub"
      ]
  ; h "footer" 
      [ h "div" ~className:"container" 
          [ Link.make ~onClick:(Link.location Link.home) ~className:"logo-font" 
              [ React.string "conduit" ]
          ; h "span" ~className:"attribution" 
              [ React.string "An interactive learning project from "
              ; h "a" ~href:"https://thinkster.io" [ React.string "Thinkster" ]
              ; React.string ". Code & design licensed under MIT."
              ] 
          ]
      ]
  ]

We could also adopt its short-hand syntax for id and className (but still allow it to be passed separately as well):

React.Fragment.make
  [ h "a" ~href:"https://github.com/jihchi/jsoo-react-realworld-example-app" ~target:"_blank"
      [ h "i.ion-social-github" []
      ; React.string "Fork on GitHub"
      ]
  ; h "footer" 
      [ h ".container" 
          [ Link.make ~onClick:(Link.location Link.home) ~className:"logo-font" 
              [ React.string "conduit" ]
          ; h "span.attribution" 
              [ React.string "An interactive learning project from "
              ; h "a" ~href:"https://thinkster.io" [ React.string "Thinkster" ]
              ; React.string ". Code & design licensed under MIT."
              ] 
          ]
      ]
  ]

For the sake of comparison, this is what the current syntax would look like with #105 implemented:

React.Fragment.make
  [ a ~href:"https://github.com/jihchi/jsoo-react-realworld-example-app" ~target:"_blank"
      [ i ~className:"ion-social-github" []
      ; React.string "Fork on GitHub"
      ]
  ; footer 
      [ div ~className:"container" 
          [ Link.make ~onClick:(Link.location Link.home) ~className:"logo-font" 
              [ React.string "conduit" ]
          ; span ~className:"attribution" 
              [ React.string "An interactive learning project from "
              ; a ~href:"https://thinkster.io" [ React.string "Thinkster" ]
              ; React.string ". Code & design licensed under MIT."
              ] 
          ]
      ]
  ]

Pros:

• Reduces the number of identifiers matched for to 1, which is about a hundred-fold improvement and essentially solves point 2, and by extension also 3 and 4.
• Allows the instantiation of custom elements, solving point 5.
• Short-hand for id and className

Cons:

• Does not solve custom attributes, which is quite essential to web components and makes support for custom elements alone quite moot (but see the next section for a solution to that.)
• Is arguably noisier (although syntax highlighting can make the element names stand out better, making the structure as a whole easier to scan.)
• Requires slightly more editing to migrate from Reason

Props syntax extension

It seems to me that the reason we need a PPX for elements is not so much that we need to rewrite the elements as a whole, but for the most part just the props. Even with the current syntax we could have separate constructor functions for each element, e.g. let div props children = React.Dom.createDOMElementVariadic ~props ~children (). The main problem seems to be how to construct the JavaScript object for props both efficiently and ergonomically. So perhaps we should have a go at solving that separately.

If we're still doing global rewriting, we could perhaps do something like this:

div 
  [ href = "https://..." (* normal prop, typechecked as usual*)
  ; "custom-prop" = "foo" (* custom attribute, must be a string *)
  ; "@onwhatever" = fun e -> ... (* custom event, must be a function `event -> unit` *) 
  ]
  [ ... ]

Or if we want to limit it to an extension point:

div 
  [%props
    href = "https://...", (* normal prop, type checked as usual*)
    "custom-prop" = "foo", (* custom attribute, must be a string *)
    "@onwhatever" = fun e -> ..., (* custom event, must be a function `event -> unit` *) 
  ]
  [ ... ]

Pros:

• Allows custom attributes, and even custom events (although that would require some more runtime support as well)
• Allows the use of ordinary functions for elements, solving points 1, 2, 3 and 4.

Cons:

• Noisier
• Less familiar syntax
• User-defined (upper-case) components will use a different syntax for props
• Significantly more editing needed to migrate from Reason

Conclusion

Together, these two ideas would solve all the issues mentioned in the introduction, although with a noticeable cost in syntactic noise and infamiliarity. But I also don't think these ideas are fully-formed, there may very well be room for further improvement here.

Finally, to illustrate how it could look put together, first if we accept h being a globally rewritten "special" function:

React.Fragment.make
  [ h "a"
      [ href = "https://github.com/jihchi/jsoo-react-realworld-example-app"
      ; target = "_blank"
      ]
      [ h "i.ion-social-github" (* It should be possible to omit props and children if empty since we it's not curried and we know all the forms it can take *)
      ; React.string "Fork on GitHub"
      ]
  ; h "footer" 
      [ h ".container" 
          [ Link.make ~onClick:(Link.location Link.home) ~className:"logo-font"  (* User-defined components will of course need to use a different syntax for props *)
              [ React.string "conduit" ]
          ; h "span.attribution" 
              [ React.string "An interactive learning project from "
              ; h "a" [ href:"https://thinkster.io" ] [ React.string "Thinkster" ]
              ; React.string ". Code & design licensed under MIT."
              ] 
          ]
      ]
  ]

Alternatively, if we make props an extension point we could make h an ordinary function and limit the rewriting and potential for confusing situations to a much smaller area:

React.Fragment.make
  [ h "a"
      [%props
        href = "https://github.com/jihchi/jsoo-react-realworld-example-app",
        target = "_blank",
      ]
      [ h "i.ion-social-github"
      ; React.string "Fork on GitHub"
      ]
  ; h "footer" 
      [ h ".container" 
          [ Link.make ~onClick:(Link.location Link.home) ~className:"logo-font"
              [ React.string "conduit" ]
          ; h "span.attribution" 
              [ React.string "An interactive learning project from "
              ; h "a" [%props href:"https://thinkster.io" ] [ React.string "Thinkster" ]
              ; React.string ". Code & design licensed under MIT."
              ] 
          ]
      ]
  ]

[jchavarri]

@glennsl thanks so much for such detailed description of the concerns and ideas. In general, I agree with your concerns, and I think there should be a less intrusive way to solve lowercase elements creation, hopefully without losing too much ergonomics in the way.

It seems to me that the reason we need a PPX for elements is not so much that we need to rewrite the elements as a whole, but for the most part just the props. Even with the current syntax we could have separate constructor functions for each element, e.g. let div props children = React.Dom.createDOMElementVariadic ~props ~children (). The main problem seems to be how to construct the JavaScript object for props both efficiently and ergonomically. So perhaps we should have a go at solving that separately.

I think you nailed in this paragraph the crux of the issue. Essentially using plain functions with labelled arguments is not an option because given the amount of attributes that each element has (even if there was a separate function for each element), the number of zeroes in the optional params that are erased would have a lot of impact on the resulting bundle size.

This is the exact same problem that happens with React.Dom.Style.make, documented in #112. Although in that case the problem is more in some corner of the library, while the issue discussed here is really pervasive, as it affects any element.

I like the idea of using h or some other function as single entry point. Probably the most maintainable proposal is the one with [%props] extension. But I am not sure about the ergonomics 😬 One minor note is that the payload of the extension has to be valid OCaml syntax, so it should be either records, tuples, etc. e.g.:

let t = h "a" [%props { href = "https://foo.com"; target = "_blank" }]

let t = h "a" [%props [ href, "https://foo.com"; target, "_blank" ]]

i think it can also be a sequence of tuples...quite the hack 😄

let t =
  h "a"
    [%props
      href, "https://foo.com";
      target, "_blank"]

---

In any case, any of the suggested solutions (except the last one) would still require the ppx to check every function application ast node (Pexp_apply), which is still abusing the pre-processing system. And the last one still requires preprocessing the ast nodes for the props extension.

For completion, there's an additional approach that could be to use functions all the way down. And for props, pass a list where each prop is created with another small helper function, e.g. [ className "container" ].

For custom elements, there could be a custom constructor: [ custom "custom-prop" "foo" ].

That way, at least for OCaml syntax, the only preprocessing required would be to define uppercase components. This has a lot of upsides on the maintainability and error handling side, as you well mentioned.

Below is the snippet used in the proposal, with the "only functions" approach. The api is inspired from bucklescript-tea.

let t =
  React.Fragment.make
    [
      a
        [ href "https://github.com/jihchi/jsoo-react-realworld-example-app"; target "_blank" ]
        [ i [ className "ion-social-github" ] []; React.string "Fork on GitHub" ];
      footer
        [
          div
            [ className "container" ]
            [
              Link.make ~onClick:(Link.location Link.home) ~className:"logo-font" [ React.string "conduit" ];
              span
                [ className "attribution" ]
                [
                  React.string "An interactive learning project from ";
                  a [ href "https://thinkster.io" ] [ React.string "Thinkster" ];
                  React.string ". Code & design licensed under MIT.";
                ];
            ];
        ];
    ]

I don't think that for a first version we should cover all elements. For example, bucklescript-tea has around 25. Then you can fall back to generic constructor.
We would not need any kind of type checking for the props (we could allow any known attribute on any element, like we do now).

The cons of this proposal are shared with some of the ones mentioned in "Props syntax extension":

• User-defined (upper-case) components will use a different syntax for props
• Significantly more editing needed to migrate from Reason

But I believe this syntax would be more familiar for users, and it's less noisy.

What do you think?

[jchavarri]

One extra thing about skipping ppx usage is that things like documentation would become trivial, which I know @davesnx has been fighting with as part of #95 explorations.

[jchavarri]

Here's a small proof of concept, seems to work fine: #115.

[glennsl]

For completion, there's an additional approach that could be to use functions all the way down. And for props, pass a list where each prop is created with another small helper function, e.g. [ className "container" ].

Wow, that's so much simpler! And seems really obvious in retrospect, but then that's how these things usually go isn't it. There's still a few more downsides with this that I think is worth mentioning for a proper comparison though:

• Using a list means it has to be converted into a an array, adding a tiny bit of overhead. This could be addressed by using an array instead of course, e.g, div [| className "foo" |] [ ... ]
• It will pollute (that is, introduce a lot of names into) the namespace, and there's a significant risk of collisions between element and attribute names, especially with SVG (which has both an element and attribute named style, for example). Fortunately, as these are proper scope-respecting functions, they can be namespaced. And with OCaml's excellent ability to control scope, we can do something like Html.(div Props.[ className "foo" ] []).
• It's not possible to omit empty attributes and children, which in some cases could become quite noisy. It is possible to label the prrops argument though, like in TyXML for example: Html.(a ~a:[a_href "ocaml.org"] [txt "OCaml!"]).
• It will require quite a lot of code to cover all the elements and attributes, especially if we include SVG. Not sure about the potential for inlining and what this means for bundle size.

[glennsl]

I don't think that for a first version we should cover all elements. For example, bucklescript-tea has around 25. Then you can fall back to generic constructor.

I think that's reasonable, since it would be very easy to define your own, and then upstream them gradually.

We would not need any kind of type checking for the props (we could allow any known attribute on any element, like we do now).

I think that's absolutely fine too, yeah.

[glennsl]

One minor note is that the payload of the extension has to be valid OCaml syntax

With some minor fixes, it actually is valid. You can use a tuple directly in extension points. See https://astexplorer.net/#/gist/844f0950b7ddb4ba13f4ff2e45946e96/730abae12847cb04af0bfa9b7d5a0f675d255145

[jchavarri]

Some comments:

Using a list means it has to be converted into a an array, adding a tiny bit of overhead. This could be addressed by using an array instead of course, e.g, div [| className "foo" |] [ ... ]

Actually this could be seen as an advantage 😄 . Yesterday, when looking at the element tree I realized it was hard to differentiate between children and props. By using an array, the distinction is (visually) much more obvious without the need of using noisier solutions (like adding labelled argument ~attrs), e.g.

let%component make () =
  Fragment.make
    [
      a
        [|
          href "https://github.com/jihchi/jsoo-react-realworld-example-app";
          target "_blank";
        |]
        [
          i [| className "ion-social-github" |] [];
          React.string "Fork on GitHub";
        ];
      footer [||]
        [
          div
            [| className "container" |]
            [
              span
                [| className "attribution" |]
                [
                  React.string "An interactive learning project from ";
                  a
                    [| href "https://thinkster.io" |]
                    [ React.string "Thinkster" ];
                  React.string ". Code & design licensed under MIT.";
                ];
            ];
        ];
    ]

It will pollute (that is, introduce a lot of names into) the namespace, and there's a significant risk of collisions between element and attribute names, especially with SVG (which has both an element and attribute named style, for example). Fortunately, as these are proper scope-respecting functions, they can be namespaced. And with OCaml's excellent ability to control scope, we can do something like Html.(div Props.[ className "foo" ] []).

Yeah. We can go more or less granular as we want (e.g. one module with everything, subset by html or svg, etc). Probably when using it we will realize more what's needed and what's a reasonable way to split them. I think a module with "everything inside" will always be useful, the over time it can be polished as needed.

It's not possible to omit empty attributes and children, which in some cases could become quite noisy. It is possible to label the prrops argument though, like in TyXML for example: Html.(a ~a:[a_href "ocaml.org"] [txt "OCaml!"]).

Yeah, we can do that, but it would add noise to all cases. I wonder if in these cases it'd be easier to just redefine functions (initially in user land) by using let div = div [] and such.

Another thing is that for 1-attribute-elements we would create a list or array unnecessarily. In e.g. bonsai they solve this using Attrs.many function, or just passing single attr. We could have a value no_props when nothing needs to be passed (to avoid creating lists unnecessarily). But these are optimizations for the future.

It will require quite a lot of code to cover all the elements and attributes, especially if we include SVG.

I think it is becoming clear from your thoughts that it might make sense to split Html and Svg in separate modules.

Not sure about the potential for inlining and what this means for bundle size.

The inlining concern is a really good one. I will try to test, including latest changes in jsoo about inlining.

[glennsl]

I think a module with "everything inside" will always be useful, the over time it can be polished as needed.

If we put them into separate modules (Html, Html.Props, Svg, Svg.Props) we can still offer something like a Prelude module which includes everything. Then consumers have full control over the granularity of scoping, and in the case of ambiguities can manually disambiguate by qualifying it with the appropriate module.

For example:

open Svg

style [| className "foo"; Props.style "bar" |] [ ... ]

Yeah, we can do that, but it would add noise to all cases. I wonder if in these cases it'd be easier to just redefine functions (initially in user land) by using let div = div [] and such.

I've seen other libraries (in languages that don't have labeled arguments) define separate prop-less functions using a trailing underscore as the convention. E.g. let div_ = div [||]. I'm not a big fan of that though, as it's a somewhat hidden convention you need to know about and it effectively doubles the API surface for very little gain.

I'd go with the simplest option for now, just leaving it as a mandatory unlabeled argument, as it seems like premature optimization at this point. If over time we find that it's too noisy or that there's to much overhead to creating lots of empty arrays, we can revisit. It should be fairly easy to migrate if we use the array syntax for props.

It's good to get all these considerations and alternatives on the table early though, so we can keep them in the back of our minds as we try this out.

I think it is becoming clear from your thoughts that it might make sense to split Html and Svg in separate modules.

Yes, but even more important to split props and elements I think, as those are considered separate namespaces, more likely to be used together and to need qualification to disambiguate. As mentioned above I think Html, Html.Props, Svg and Svg.Props is a good design, with an optional Prelude module to import everything. Then you still have the possibility to disambiguate when things conflict.

[glennsl]

I did some experiments myself on top of your POC, by the way. If you want to have a look, it's here.

[wokalski]

This post makes a good point - PPXes without intuitive semantics is one of the reasons why they are frowned upon. I like the idea of hyperscript. If we turn it into an extension point we can arrive at an API that's both lightweight, works well with autoformatting and supports non-standard props. I borrowed @glennsl 's example and tweaked it a little bit.

Here's how it looks like auto formatted with ocamlformat.

let x =
  React.Fragment.make
    [
      [%h a] ~href:"https://github.com/jihchi/jsoo-react-realworld-example-app"
        ("whatever" = "whatever")
        ("@onwhatever" = fun _e -> ())
        ~target:"_blank"
        [ [%h i] ~className:"ion-social-github"; "Fork on GitHub" ];
      [%h footer]
        [
          [%h div] ~className:"container"
            [
              Link.make ~onClick:(Link.location Link.home)
                ~className:"logo-font" [ "conduit" ];
              [%h span] ~className:"attribution"
                [
                  "An interactive learning project from ";
                  [%h a] ~href:"https://thinkster.io" [ "Thinkster" ];
                  ". Code & design licensed under MIT.";
                ];
            ];
        ];
    ]

PS: Sorry, I had to rewrite my post, got syntaxes mixed up.

[glennsl]

Nice one! I considered making %h a PPX as well, but encapsulating the whole expression, not just the tag name. And figured then I might as well limit it to just the props instead. But this looks much better! And it has some other benefits (shown in your example), like distinguishing the parameter based on its "shape" and being able to omit empty props and children. You can also wrap string literals in React.string automatically.

It's also possible to use the form {%h|div|}, where the contents can be any string literal (equivalent to [%h "div"]), so we could also have the short-hand for className and id, {%h|div.my-class|}. Here's a smaller example using those forms:

{%h|span.attribution|}
  [
    "An interactive learning project from ";
    {%h|a|} ~href:"https://thinkster.io" [ "Thinkster" ];
    ". Code & design licensed under MIT.";
  ]

[%h "span.attribution"]
  [
    "An interactive learning project from ";
    [%h "a"] ~href:"https://thinkster.io" [ "Thinkster" ];
    ". Code & design licensed under MIT.";
  ]

This all comes at a cost of course. More magic means more convenience, but also makes it harder to parse. To sum it up:

Pros:

• Supports custom elements.
• Supports custom props.
• No namespace collisions between props and element names.
• Allows for short-hand forms of id and className (with no performance overhead).
• Empty props and children can be omitted (which also means their allocation can be avoided.)
• List brackets can be omitted for passing a single child.
• String literals don't need React.string.
• Unified syntax, using upper-case identifiers for user-defined components, e.g. [%h MyComponent].

Cons:

• It's magic, which means it's harder to understand what's going on. And the more convenient magic we add, the harder it becomes. But the magic is at least very localized.

Personally, I like the id and className short-hand and the ability to omit props and children if empty. More magic than that seems to be going too far, but still I'm unsure if the cognitive cost of the magic and the maintenance cost of the PPX is worth the added convenience.

[glennsl]

It's also possible to use the form {%h|div|}, where the contents can be any string literal (equivalent to [%h "div"])

Actually, we could accept both [%h a] and [%h "a"] and just use the latter form when needed, for adding id and className.

[glennsl]

I also think I'd prefer using (href = "https://...") for known props as well, just for consistency.

A full example fairly close to my ideal would be:

let x =
  [%h Fragment]
    [
      [%h a] (href = "https://github.com/jihchi/jsoo-react-realworld-example-app")
        ("whatever" = "whatever")
        ("@onwhatever" = fun _e -> ())
        (target = "_blank")
        [ [%h "i.ion-social-github"]; "Fork on GitHub" ];
      [%h footer]
        [
          [%h "div.container"]
            [
              [%h "Link.logo-font"] (onClick = (Link.location Link.home)) [ "conduit" ];
              [%h "span.attribution"]
                [
                  "An interactive learning project from ";
                  [%h a] (href = "https://thinkster.io") [ "Thinkster" ];
                  ". Code & design licensed under MIT.";
                ];
            ];
        ];
    ]

[wokalski]

btw two things: my personal bias is that I don't consider ppx maintenance as something high cost, at the end of the day PPXes tend to be very simple and testable. Also, it's a bit hard for me think about any of this in terms of magic. The react API we're wrapping is very far from any of the proposals. For the end user convenience (especially during debugging) I'd be in favor of optimizing for the compiled output so that it's as easy to debug as possible.

[glennsl]

What I mean by "magic" is that this doesn't just introduce new rules to a new game. It changes the rules of the game we're already playing. And it's made even worse because we're mixing old and new rules. We're taking code that already has a meaning, and expecting some parts of it to be interpreted with the original meaning and other parts to be interpreted with some new meaning. So care needs to be taken to make the rules few, simple and easily distinguishable.

The maintenance burden might be overblown though, especially since I understand we're going to need a PPX for user-defined components anyway. But I've never maintained a PPX, so I don''t really have an opinion on it, just parroting what others have mentioned.

I personally like the idea of ~standardProp. It's simply less characters, allows punning etc

Good point about punning. I suppose we could also use ~custom:("whatever", "whatever") for custom props. It'll look a bit weird to have several of them, but this won't be a very common use case anyway. No reason to optimize for the 1% scenario.

I really like the ideas around class/id. It's perfect for tailwind for example.

It just occurred to me that [%h div#foo.bar] is syntactically valid as well. It's just object and record access. No strings needed!

[glennsl]

It just occurred to me that [%h div#foo.bar] is syntactically valid as well. It's just object and record access. No strings needed!

[%h i.ion-social-club] is not valid though (well, technically it is I guess, but not easy to parse, and will probably format badly)... Strings needed after all, but perhaps just for those cases.

[davesnx]

Talking exclusively about [%h "span.attribution"]. I can't see the bigger benefit of this. It introduces a slightly complex parsing mechanism at the cost of a cute syntax and a learning curve; otherwise using regular the className prop hasn't been any issue for me.

[glennsl]

It greatly improves readability IMO. The tag name and class name is usually very closely related and together describe an element's purpose (and if not, I think it should). It also puts the class name in a predictable location. This makes it much easier to scan an element tree for a specific element, and much easier to get an overview at a glance of what an entire element tree does.

[jchavarri]

PPXes without intuitive semantics is one of the reasons why they are frowned upon.
I don't consider ppx maintenance as something high cost, at the end of the day PPXes tend to be very simple and testable

I have a very different opinion. In my experience, ppxs add all kinds of issues, and can cause problems in toolchain related parts, e.g. IDE integration, compiler upgrades, docs, etc. They are not easy to test either, for example, locations testing is not straight forward imo, but it's essential to PPX development. And you can't easily test cases where you need full compiler output (see #90, where I was not able to find a way to test easily).

I would suggest to proceed in two steps:

Step 1

Come up with a ppx-less solution for element creation for OCaml syntax, that we could build upon, similar to what was suggested above. For two reasons:

• It is desirable to limit the impact of ppx magic in jsoo-react apps, and keep it limited to component definitions. For OCaml syntax case, jsoo-react would only require ppx in the let%component side, which I find very interesting for maintenance and user experience reasons.
• We could leverage this ppx-less APIs to generate code from Reason syntax (the [@JSX] elements), which would ease the implementation and help with some problems we had with documentation on hovering etc.

Step 2

Explore solutions to use PPX at element creation time like the ones above this comment. This would help to make the element hierarchies less verbose, more ergonomic, avoid React.string, etc. This step does not necessarily need to be developed as part of the jsoo-react library first, it could be done in other repositories (as long as there is a stable API to target with the ppx, which also makes step 1 more relevant).

@glennsl @wokalski @davesnx what do you think?

[wokalski]

It makes sense! I'm only slightly worried about:

1. (hypothesis) we're just moving the complexity from compile time to runtime
2. the compiled output quality (not sure how important it is from your experience)

I should note that I'm not a user of jsoo-react (yet?) so I'm commenting as an enthusiast only.

[glennsl]

Sounds good!

I want to experiment with using jsoo-react for production code next week, and the plain function API would be a good way to get going quickly by gradually building out the API in user-space as I go. At the end of the week I'll probably have something I can upstream.

[jchavarri]

I'm only slightly worried about:

(hypothesis) we're just moving the complexity from compile time to runtime
the compiled output quality (not sure how important it is from your experience)

@wokalski this is interesting, I am also curious about it. I will try to do some checks this week, using the PoC branch that @glennsl and I have been working on.

I want to experiment with using jsoo-react for production code next week, and the plain function API would be a good way to get going quickly by gradually building out the API in user-space as I go. At the end of the week I'll probably have something I can upstream.

@glennsl This sounds super exciting :) I am currently focused on finishing some jsoo-react demo app so that I can do some proper bundle size measurements comparing it to Rescript, and test some of the most recent functionality like bindings to JS components. But once that is done I can prob help with anything related to this new API.

[davesnx]

Agree with most of the points made here, the transformation isn't obvious from what it looks like functions but aren't functions. If we want to make the OCaml syntax lightweight I'm more balanced into a "just functions" approach and avoid all ppx transformations here.

The pros have been written before but let me add a few:

• Documentation (we can have all dom/svg elements documented nicely with ocaml.doc and autocomplete thought https://github.com/ml-in-barcelona/jsoo-react/blob/main/ppx/html.ml)
• Can solve relatively "cute" the ~customProp issue. Adding an extra prop where users can inject any Jsoo.Object
• Works automatically with ocamlformat

The biggest downside for me is runtime performance and bundle size.

[jchavarri]

For the record, I updated the Conduit demo app to use the latest version of jsoo-react with the changes that we started discussing here, and the bundle size went down a little a bit, from 118351 bytes to 117881.

I did not see noticeable changes in generated JS code.

jchavarri/jsoo-react-realworld-example-app#1

[jchavarri]

I am glad we did not make a public release before shipping this change though 😆 it was quite cumbersome to update existing ml components to the new api.

[glennsl]

I can imagine. Looks really nice though! Did you encounter any significant ergonomics issues along the way?

[jchavarri]

Looks really nice though!

Yeah it does! A lot of noise gets removed by getting rid of children labelled arg. The API differences between lower and upper components does not look that bad to me yet, but I'd like to test it more.

Did you encounter any significant ergonomics issues along the way?

Not really, it was very straightforward process:

• Replace props as labelled args with array of funs
• Remove ~children
• Replace Fragment.make with fragment

A few things maybe worth mentioning:

• Elements without children or props still require both the empty array and list (example)
• Punned props required to namespace the prop make function to work, e.g.

  - img ~src ~children:[] ()
  + img [| Prop.src src; |] []

• or to rename the prop, e.g.

  - img ~src ~children:[] ()
  + img [| src src_ |]

• Because of the way Dom_html includes Prop, and style being both the React prop and the DOM element, I had to namespace all style prop creation functions with Prop. (example)

I am not sure if we should do anything about this yet... would be nice to gather more feedback from other use cases / app examples.