Expanding the Dom API

[Richard Feldman]

Expanding the Dom API

So! Virtual DOM is a great foundation, but some DOM interactions - for example, setting and clearing focus - don't play well with Virtual DOM. I talked with Evan about putting together a list of APIs to add to elm-lang/dom, to cover some interactions that currently require Ports. The goal of this thread is to decide what to put on that list.

Design Guidelines

We can always expand this list in the future, but I want to start small in order to avoid regrettable additions that would break peoples' code if removed later. Here are the design guidelines I want to stick to for this pass:

1. Replace workarounds. Speculatively valuable additions are how APIs get bloated! To make it into this draft of the API, the functionality in question must be so indispensable that someone is currently using a workaround to get it. (If a workaround was absolutely impossible for some reason, that's fair game, but please explain why it was impossible.)
2. Avoid bad interactions with Virtual DOM. For example, an API to directly remove elements by ID would easily mess up vdom.
3. Don't introduce a dependency on Virtual DOM. "Play nice with it, but don't depend on it."

I began the list with focus, blur, and text/bounds measurement. These are all things we've used Ports to work around not having at NRI. I also included getting and setting scroll position, as Dreamwriter autosaves your last editor scroll position and restores it on load, which currently requires a Port.

All of these are (1) replacing workarounds, they (2) have no bad interactions with Virtual DOM, and they (3) don't depend on it.

Discussion Focus

Open-ended discussions have a tendency to drift, so I want to be clear about the purpose of this thread. Let's keep our comments to the following:

• Problems with the proposed API (e.g. "as written, this might throw a runtime exception")
• A proposed addition that fits 3 out of 3 of the design guidelines above
• A suggested simplification to the proposed API, including (especially!) by removing something

Let's explicitly avoid the following:

• Comments about what to name things. Good names are very important, but tangents about naming are among the leading causes of death for API discussions. Let's focus on the API at this stage.
• Comments about other topics, however related. Starting another thread for things like that is easy!
• Debating the design guidelines. The scope is narrow on purpose! It's easy to expand the API in a future pass, but painful to remove things.

Current API

I'll edit this gist as the discussion evolves:

https://gist.github.com/rtfeldman/5f015adbdfbba541c7e7e1409b6efeef

Thanks for reading!

[Irakli Gozalishvili]

Hi Richard,

I am really glad focus management issue has being looked at. I would really like if selection management  API was also considered. Right now I use same kind of workarounds for it as as with focus management. Do you want me to propose API for that ?

I am also not sure if you'd like feedback on proposed API in here or gist, so I'll post my feedback in gist as everyone else did.

Regards

[Richard Feldman]

This has been open for about a week, so I want to summarize the discussion thus far.

1. There seems consensus that having access to the following (in some API form) would provide nice access to things that people are currently using workarounds to implement:

focus, blur, measureText, bounds, getScrollTop, setScrollTop, getScrollLeft, setScrollLeft

2. Implementing the "setters" as Tasks makes more sense than implementing them as vdom elements, because the semantics of the latter would be unclear.

3. However, implementing either getters or setters as Tasks can potentially cause race conditions based on how people would be using these APIs. It's possible that these also fall into the category of events that require effects to happen in the same clock tick, not because of JS library API constraints, but in order to avoid race conditions.

4. Irakli has expressed concern that although the querySelector API may be the easiest to implement, using it requires error-prone manual namespace maintenance. Dremora seconded this.

5. There is demand for a text selection API, but that can happen in a future pass.

Did I miss anything?

[Søren Debois]

Disagree on 2: I think the discussion bore out that the semantics of setters is no less clear than the current `value` attribute for `input`; it's just that you have to be aware that user-input may happen subsequently. I also feel I had some support that the `value`-like declarative API was preferable, both in its own right and as an alternative to query-selectors (4). 

I also want to re-iterate how awesome it's going to be finally getting this! 

[Richard Feldman]

Fair enough Søren - thanks for the follow-up!

--
You received this message because you are subscribed to the Google Groups "elm-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elm-dev+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elm-dev/02b8a85f-426d-44f4-a0cf-e5e2c69a4c68%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[sylvain....@gmail.com]

While it works well with value, you have to be careful with scrollTop for example.

With value, you may "mirror" (update to the field updates the model, the model updates the view/DOM), correctly and it's fast enough. But I tested (in 0.16) a scrollTop property and it caused problems when you update the model with the current scroll position and update the view from the model. In FF, it "micro-scroll" one pixel at a time. In Chrome, it jump-around back and forth. The scroll event is really fast and you should not mess with scrollTop property at the same time.

I finally made a scrollToBottom function (Native) for my project with the id of the element in parameter.

[Søren Debois]

@richard: Thanks, appreciate it!

@sylvain: Actually, that's a great point. I'd end up doing what the Task-based API does anyway to avoid that. So maybe for scroll properties, the declarative API is not so hot. 

[Richard Feldman]

Also worth noting value isn't fast enough either! :)