Simplified API (open to discussion) about modular-ui-roadmap

[danielnarey]

Here's a somewhat final list of exposed functions:

---

Create and Render

• element
• render

Build

Using a single argument...

to set the id attribute

• setId

to add a class, style, or other attribute

• addClass
• addStyle
• addAttribute

to add an event listener

• addAction
• addInputHandler
• addChangeHandler
• addToggleHandler

to append or prepend internal text

• appendText
• prependText

to append or prepend a child element

• appendChild
• prependChild

Using a list argument...

to add a list of classes, styles, or other attributes

• addClassList
• addStyleList
• addAttributeList

to append or prepend a list of child elements

• appendChildList
• prependChildList

you can also supply a list of Html nodes

• appendNodeList
• prependNodeList

or a keyed list for performance optimization

• setChildListWithKeys
• setNodeListWithKeys

Using a conditional parameter...

when adding a class, style, or other attribute

• addClassCondtional
• addStyleConditional
• addAttributeConditional

when adding a list of classes, styles, or other attributes

• addClassListConditional
• addStyleListConditional
• addAttributeListConditional

when adding an event listener for an action

• addActionConditional

when appending or prepending internal text

• appendTextConditional
• prependTextConditional

when appending or prepending child elements

• appendChildConditional
• appendChildListConditional
• prependChildConditional
• prependChildListConditional

Modify

Removing all instances of a single name or key

• removeClass
• removeStyle
• removeListener

Replacing the existing list of classes, styles, or other attributes

• replaceClassList
• replaceStyleList
• replaceAttributeList

Replacing the existing text

• replaceText
• replaceTextConditional

Replacing the existing descendant tree

• replaceChildList
• replaceChildListConditional
• replaceNodeList

Advanced Usage

Setting an element's HTML/XML tag and namespace

• setTag
• setNamespace

Customizing event handling...

by transforming input values

• addInputHandlerWithParser
• addChangeHandlerWithParser

by using a custom decoder

• addListener
• addListenerConditional

by using custom handler options

stop propagation

• addActionStopPropagation
• addListenerStopPropagation

prevent default

• addActionPreventDefault
• addListenerPreventDefault

both

• addActionStopAndPrevent
• addListenerStopAndPrevent

Debug

• getData

[carolineartz]

Thanks for the ping. Gonna dive into the above this week and I'll follow up.

[arsduo]

tl;dr: this makes a ton of sense. I'm excited for the next update.

Semantics of record updates

These make a ton of sense.

remove__ = delete a value or key from the current list contained in a field

Are there ever cases in which a key could exist multiple times? For instance if you've added multiple event handlers for the same action? In that case would the library remove both (seems sensible)?

Should I name it Ui.elm or something different?

I like Ui. It's descriptive, it doesn't conflict with anything, and it's easy to refererence.

Should the record be exposed or hidden behind an opaque type? Does exposing it make it easier for the user to understand what's happening behind the scenes, or does it simplify learning to not have access to internals?

That's a really good question. I can see arguments both ways. As far as I remember, we've never needed to look at (or change) fields on the record directly in our code. (Have you?) It's sometimes been useful to dump the record to the console, but you can still do that with an opaque type (AFAIK).

The risk of making it opaque is that people might run into situations that can't be handled by the existing methods, in which case new framework methods would be needed.

The risk of exposing it is that people might write code that depends on implementation details, making it either painful or impossible to change the implementation later.

Personally, I think the risks of exposing the details are much greater. Modular UI lives on top of Virtual Dom, whose implementation could change in ways that might be best handled by changing the data structure; if that's opaque, it's easy, whereas if it's been exposed that could potentially cause a lot of pain.

Compared to that, having to add methods occasionally doesn't seem to bad. One way to make sure that people don't get stuck could be to make it possible to give a node raw Html Msg objects as children. That way if someone did run into a situation they couldn't solve, they could fall back. (The downside would be people might use it too much, but ideally they'd switch over because Modular UI is just better.)

Constructor for element records

👍

In the previous version, "modifier" had a specific meaning pertaining to style classes that modify a base class. In the new version, I want to use "modifier" to mean any function that takes an existing element record, updates some of its internal data, and returns the updated element record. I'd like to call these "modifier functions" instead of "update functions" to make clear that they are just part of the view code and don't have anything to do with the Elm program's update function.

I think this is really sensible terminology that'll make the library clearer.

addAttribute

Would it make sense to have a removeAttribute method? Or does that get into a confusing situation where an attribute can be added twice with different values and it's not clear what would get removed?

Text is rendered to VirtualDom as the first child node, containing plain HTML text. Helper functions for styling text that were included in the previous version will be moved to a separate package.

👍

addChild : Element msg -> Element msg -> Element msg

To make sure I understand how this would work, would it be

myNode
|> Ui.addChild parentNode
-- return an updated parentNode?

That works for me. It would still be possible to write code like

myNode
|> Ui.addChild (Ui.element "div")
|> Ui.addClass "foo"

It's a little more verbose (I can't promise we wouldn't create Ui.Extra.container in our own codebase), but I think it's a good, clean move for the base library.

[danielnarey]

Thanks for your input, @arsduo.
Here's my response:

1. Implementation of remove__

Are there ever cases in which a key could exist multiple times? For instance if you've added multiple event handlers for the same action? In that case would the library remove both (seems sensible)?

VirtualDom handles duplicate keys in an appropriate way, so my approach has been to preserve duplicates and hand them over to VirtualDom. It makes sense where the list is preserved in an Element record that if you remove a key it should remove all instances, so this is something I will implement.

2. Package / core module name

See #4. Also: I'd like to avoid confusion with mdgriffith/elm-ui. Alternative suggestions welcome.

3. Exposed vs. opaque type

As far as I remember, we've never needed to look at (or change) fields on the record directly in our code. ... Personally, I think the risks of exposing the details are much greater. ... One way to make sure that people don't get stuck could be to make it possible to give a node raw Html Msg objects as children. That way if someone did run into a situation they couldn't solve, they could fall back.

I agree with this reasoning, and I think we can guarantee that there will be a modifier function for anything useful you could do with basic record updates. I do think it makes sense to include functions for adding child nodes fromHtml msg / VirtualDom.Node msg objects.

4. Removing a generic attribute

Would it make sense to have a removeAttribute method? Or does that get into a confusing situation where an attribute can be added twice with different values and it's not clear what would get removed?

I would need to be convinced that this capability is really useful to have. I think it will make the package easier to learn if generic attributes (i.e., not classes, styles, actions) are added via Html.Attribute functions, rather than a specialized syntax. But that means that the attribute keys will not be accessible when working with Element records, so there will be no way to remove an attribute by key. An alternative to removing an attribute would be to use addAttributeConditional: if the condition becomes false when the program updates, the attribute will not be added when the next view is rendered.

5. Adding child nodes

To make sure I understand how this would work, would it be

myNode
|> Ui.addChild parentNode
-- return an updated parentNode?

I think you might have this backwards. I intended it to be:

parentNode
  |> addChild childNode

or

parentNode
  |> addChildList 
    [ child1
    , child2
    , child3
    ]

Now I am also thinking that the append__ vs. prepend__ option should be available for child nodes. So make it:

parentNode
  |> appendChild childNode

etc.

[danielnarey]

Started assembling the module here.

[arsduo]

That covers everything I can think of. It certainly should be enough for me to reimplement the drag-and-drop functionality, as well as everything we've done at eSpark. Looking forward to the new API!

[carolineartz]

wow this is going to be fantastic. SUPER excited for this release!!! Sorry if i missed this somehwere but will this be tied with or integrated by default with Bulma?

[danielnarey]

@carolineartz

Sorry if i missed this somehwere but will this be tied with or integrated by default with Bulma?

No, I'm taking a different approach here. After considering what seemed to be most useful out of my earlier attempts, I started to see the end goal differently. The new package is intended to be a basic set of utilities for UI development in Elm, which will not be tied to a specific CSS framework or component library. In other words, instead of creating components for others to use, my aim is to provide utilities that make it easier for users to build the customized components they need. At the same time, I want to support other package developers in creating libraries of reusable components, so my secondary goal is to make this package a comprehensive and reliable base for those efforts.

That said, some of the functionality of the previous Modular UI package may be incorporated into new packages in the future, so let me know if there are other parts you have found particularly useful that are not included here.

[danielnarey]

@arsduo @carolineartz

The new package is published under visotype/elm-dom! I'm releasing it under my organization name to differentiate it from my more experimental personal projects. The docs are here: https://package.elm-lang.org/packages/visotype/elm-dom/latest/

[arsduo]

Awesome! We're at ElmConf now, funnily enough, so I'll take look soon :)

…

On Wed, Sep 26, 2018, 12:48 Daniel Narey ***@***.***> wrote: @arsduo <https://github.com/arsduo> @carolineartz <https://github.com/carolineartz> The new package is published under visotype/elm-dom! I'm releasing it under my organization name to differentiate it from my more experimental personal projects. The docs are here: https://package.elm-lang.org/packages/visotype/elm-dom/latest/ — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAC8xcybMFudw-HbeY3ccxw68FXT-rcBks5ue73agaJpZM4Wdg1U> .

[carolineartz]

ohhhhhh awesome!! can't wait to check it out. Was hoping you'd be at Elm Conf!