Debating the idom.html.* interface

[Archmonger]

With the release of IDOM v3.0.0a1, there has been a lengthy discussion on

1. Should the idom.html.* interface change?
2. If so, what should it look like?

I had proposed some guidelines on what could be considered a good interface and have been frequently updating a demonstration gist containing feasible design choices.

The guidelines comment also contains some details on which interfaces are in violation.

Given the new constraints/goals/guidelines, my personal rankings are:

1. Dict Attributes (Old Interface)
   • Pro
     • It has no real guideline violations.
     • Manipulating a dict directly has some added convenience and efficiency due to the pipe operator
     • Feels like ReactJS Props
   • Con
     • The attribute dict often times adds additional indentation.
     • When formatted with black, additional vertical space is also added as a whole LOC is taken up by opening/closing brackets
     • Support for auto-complete and hover-over descriptions on TypeDict keys isn't robust in some editors
     • Might feel weird to Python developers
2. Parentheses Children
   • Pro
     • Seems like a good balance between shortened syntax and visual clarity for attributes
     • Thanks to VSCode bracket-pair coloring, this feels easy to read.
     • Alternative to Bracket Children that won't generate confusion around children lists
   • Con
     • Dynamically manipulating HTML attributes requires creating a dict then unpacking it. This is inefficient.
     • In editors without bracket-pair coloring, it could potentially get confusing which parenthesis belong to attributes, and which belong to children.
3. Bracket Children / User Tagged Bracket Children
   • Pro
     • Same as Parenthesis Children
   • Con
     • Same as Parenthesis Children
     • The brackets can potentially visually clash with children lists
4. Children Function
   • Pro
     • This somehow feels both pythonic and javascripty.
   • Con
     • Adding a children keyword could be additional noise
5. Everything else

cc: @rmorshea @numpde

[rmorshea]

I think I'm in favor of keeping the old interface as well. In addition to the cons mentioned above, many of the proposed interfaces will be more complex to implement than the old one which incurs extra maintenance and performance costs.

[Archmonger]

Before moving forward, are there any of the other examples you'd like me to write down pros/cons for?

[rmorshea]

I can't really think of anything else right now.

[numpde]

Related: possibility for hints for props.
Although, with AI code completion, this may be redundant.

[Archmonger]

@rmorshea I think the one change we should make for v1.0.0 is the location where key=... is declared.

Right now, it is a kwarg. But if we're comparing the idom.html API to JSX equivalent, that's visually not where keys should be declared.

It would be more proper to declare key=... within the VdomAttributes dict.

html.div(
   {"key": 123, "class_name": "example"},
   html.button(),
)

Given we've had a lot of type hint issues surrounding idom.component type hints, we might also want to think about the @component decorator and how they get keys.

Maybe a ComponentAttributes dict should be considered? Would leave room for us to add more options in the future.

@component
def my_component(arg1: str):
   return arg1

html.div(
   {"key": 123, "class_name": "example"},
   my_component(
      {"key": 666},
      "demo",
   ),
   html.button(),
)

[rmorshea]

I think this is a good change to make. Very easy to make a deprecation warning for this too.

[Archmonger]

Should we consider repurposing the update_html_usages CLI to auto fix this?

[rmorshea]

I am seeing some movement towards context manager interfaces for defining UIs - textual just released their own version of this and reacton the jupyter widget based react-like solution is doing the same. At this point, I'm not sure I want to rewrite everything again, but I'd be open to creating an additional way to do this. Wouldn't be too difficult to make something like this possible:

v = View()

with v.div(class_name="this”):
    with v(my_component, some_kwarg=“that”):
        v.button(on_click=...)

return v

There is the problem of multiple context managers with a, b: but I think this is sort of an edge case, and technically this doesn't break anything. Technically this is effectively declaring that b is a child of a since a gets invoked first. Both the aforementioned libraries use a fairly magical syntax that requires mildly fewer characters, but I think having this View object is more straightforward to implement/maintain - fewer chances for weird side effects.

[Archmonger]

Context managers do look neat, but storing VDOM snippets into variables becomes really awkward.

I think our function API is good enough, with JSX syntax being the more appropriate long term solution.

[rmorshea]

I don’t actually think you’d need the with x as y: syntax - as per the example above you have the view representation in v already.

[rmorshea]

Anything else you’d need it for would imply the use of imperative mutations that we’d want to discourage anyway.