There was a section added to the guide in 2018 called “Design Considerations” and in this commit, I broke that content out into its own section called Limits so that it is more clearly in the main reading path. I also added some content on the optimization benefits of knowing that code is pure / being able to change the format of generated code. (Getting the small assets in 0.19 was largely possible due to changes in generate code and kernel code that worked better for JS minifiers.)
I also put notes on a bunch of pages about evaluating flags, ports, and custom elements to see if it covers all of your use cases before using Elm in a commercial setting.
Many web components I have come across use CSS Custom Properties to allow styling, if components are being suggested by the guide, I feel like it is even more important that Elm finally supports custom properties (there is a one-line PR to support this).
I added a comment to the PR you mention (to flesh out my 2017 comment on the connected issue) about why it is important to have a second mechanism for variables.
Many changes are one line (like removing this phase of compilation) but such changes often have more complex implications than the line count might suggest. Perhaps you can start a new thread sharing examples of where you think it might be good to have this feature, so others can figure out if there really is no other way to proceed than by adding a 2nd mechanism for variables that lacks type safety or even name checking. That would help me understand this scenario better.
I didn’t mean to suggest that the fix being one-line meant it was trivial, so my apologies for the implication. Please see the linked thread for my explanation of the things that simply can’t be done without CSS Custom Properties.
I like the changes. I think the encouragement that is provided to seriously consider the interop upfront for commercial projects reads humble and honest.
The Limitations part seems mostly written to explain how the interop strategies pertain to packages, but doesn’t address the application side very much.
It would also be nice to produce an Elm specific guide to custom elements (not saying you should write it). Due to the history of how they came to be in browsers, there is a lot of tricky bits that are hard to get practically right and the documentation is mostly confusing. Specifically, I’d like to see someone address:
What parts of the spec are actually useful right now for practical use with Elm. I’ve had a lot of success with the core Custom Elements, but less so with Shadow DOM, HTML Imports, Templates and Slots and other parts of the specs.
Polyfills? Which one do I need? For what browsers?
Bundler compatibility: As custom elements rely on JS Classes, a lot of bundlers break them by compiling to ES5. How do I make it work with popular bundlers?
Attributes vs properties. When to use which? Performance?
DOM upgrading. How to handle if the custom element gets initialised after the Elm application?
Events: How to handle events in a performant way? Overriding addEventListener vs proactively dispatching events and the tradeoffs of both. Using getters for lazily computing stuff from Elm.
A focused webcomponents how-to sounds like a really good idea, I will put that into the backlog for js-integration-examples might be out of scope there but that’s a good topic for a blog post anyway.
Would it make more sense to link to existing resources on web components? Not sure how much you’re looking to include in a how-to. Definitely agree that a blog post would probably be a better fit as web components is a fairly large topic.
I’ll have a look but I haven’t come across anything like this specifically. @gampleman is right in that most webcomponents tutorials/how-tos I’ve seen just lump together everything that’s in the spec with very simple examples for each one because the scope is so huge.
Another one to be aware of is extending built-in components. Currently Safari (Mac and iOS) doesn’t support it without a polyfill (and I’m not sure what the polyfill actually does). Also, elm doesn’t currently support them either. There’s a lot of ongoing debate in the browser communities about the future of this feature.
I know it’s slightly offtopic, but if we’re talking moving the guide forward, it might be helpful to update https://github.com/elm/editor-plugins as it’s linked there.
@evancz can I suggest an addition to this library?
I think it would be extremely helpful to beginners to show what you think is the idiomatic way to do something a bit more challenging with localStorage, such as is someone needs to do a localStorage.getItem() query after the program has begun. Especially if you could show a use-case where one has to query on a couple of different keys, which return different shapes of json.
I know that dealing with these kinds of queries, getting state from objects that necessarily had to be kept on the js side of a port, was difficult for me to work with and reason about, especially when the number of objects grew or working with something a bit more complex like indexedDB, and I would genuinely like to see the way you design that.
Following @Dan_Abrams suggestion for “more challenging examples”, it would be great if the elm community produced a centralized repository of example code for working with auth services like Auth0, AWS Cognito and Netlify Identify through ports, etc. Some of these services published their own Elm guides, but they weren’t updated to 0.19 or to the PKCE code grants that are now advised for SPAs.
Having had my own difficulties implementing it in a combination of Elm and Javascript, I’ve been giving Elixir’s Phoenix framework complete control of my navigation bar (with its login and log out actions), and then passing the current_user in flags to an embedded Elm app. There are examples of this hybrid approach in a Pragmatic Studio course and in Bijan Boustani Leanpub book.
It integrates with localforage (a JS library that simplifies the IndexedDB API.)
It shows how to communicate with JS by treating it as an actor. So, you send it messages and you expect messages from it.
Add a few persons and then filter the list on the name. The filtering happens in JS.
I believe this pattern covers most case. You can send whatever message to JS, handle that message in JS and then send the results back to Elm.
If you need to handle errors from JS in Elm, just serialize the error and send it to Elm.
You will need to write encoders and decoders for the messages sent to JS and messages received from JS.
If you have a webapp and you want the messages routed back to a specific page, make sure to include some hints in the toJS message that could be used by the fromJS message decoder in order to figure out what page needs to receive the answer.
