Surface - A component-based library for Phoenix LiveView

msaraiva

Broadway Core Team

Surface is an experimental library built on top of Phoenix LiveView and its new LiveComponent API that aims to provide a more declarative way to express and use components in Phoenix. Some of the main features include:

Components as modules - they can be stateless, stateful, data-only or compile-time
Declarative properties - explicitly declare the inputs (properties) of each component (like React)
An HTML-centric templating language with built-in directives (:for, :if, …) and syntactic sugar for attributes (inspired by Vue.js)
Contexts - allows parent components to share data with its children without passing them as properties
Compile-time checking of components and their properties
Integration with editor/tools for warnings, syntax highlighting, jump-to-definition, auto-completion and more

A work-in-progress live demo with more details is available at surface-demo.msaraiva.io.

Installation instructions and other useful information can be found at github.com/msaraiva/surface.

And finally, a VS Code extension that adds support for syntax highlighting is also available at
marketplace.visualstudio.com.

There’s still a lot of work to do and I hope some of you out there might be willing to help me in this journey. Bear in mind that the LiveView Component API has not reached a stable version yet and it’s currently under development, so although we try to keep track of the latest changes as much as possible, there might be temporary incompatibilities between Surface and Phoenix LiveView until a final version is released.

I’d like to thank @chrismccord and the Phoenix Core Team for buying the idea of reusable components and bringing the necessary basic concepts to the core API.

I also want to thank @josevalim, not only for the many valuable insights during development but also for his inestimable help with the main parser.

Happy coding!

-marlus

214 comments

/phoenix #library #liveview #livecomponents #surface

105 44834 214

2022-12-25 17:36:30 UTC

Showing Posts 1 to 10

Show Best Posts
Show All (oldest first)
Show All (newest first)

msaraiva

Broadway Core Team

How does it look like?

Post #1

mindok

Nice work Marlus! Many gems in there. It sounds silly, but the biggest immediate win for me is likely the css-twiddling - visual indicators of state changes make for lots of messy code currently.

Quick question - is it possible to have a Surface Component embedded in a “traditional” LiveView?

Post #2

haubie

Nice! I wondered how you did it when I saw your preview in Twitter!

Post #3

imartinat

That’s awesome! Thank you very much Marlus for this great library and great documentation.

Post #4

msaraiva

Broadway Core Team

the biggest immediate win for me is likely the css-twiddling - visual indicators of state changes make for lots of messy code currently.

Indeed. This was one of the first things I implemented. It’s quite a simple concept but it turned out to be extremely useful

is it possible to have a Surface Component embedded in a “traditional” LiveView?

Definitely! After translation, which is done at compile-time, the code becomes just an ordinary phoenix template, not different from any code written using the built-in ~L. Just make sure you import Surface so you have ~H available or add it to your lib/my_app_web.ex. Like:

...

  def view do
    quote do
      ...
      import Surface
    end
  end

This way you’ll have it available in any view!

Post #5

eaverdeja

That’s awesome!! I think React and other JS frameworks have very nice mental models (despite the problems that surround actually using these tools in practice).

I’m glad Phoenix (& ecosystem) is a late mover in this space and that there is will to learn and borrow from these mental models. Much love Marlus

Post #6

msaraiva

Broadway Core Team

In case you’re giving Surface a try, please update it to the latest version on master. Updates include:

A new parser that provides much more accurate messages on parsing/translation errors (thanks to José Valim)
Handle void HTML elements like <br> and <hr> without need to self close the tag
Append property info to components’ documentation
More bug fixes

Example - showing component docs on hover with appended property info:

Post #7

niccolox

have you thought about using something like Liquid templates for your syntax?

Post #8

cnck1387

Call me stupid but can someone explain the value in having such an abstraction in practice?

In the Grid example it looks like you could have put the <table> inside of a template in the render function and it would work the same and be more similar to how templates work with EEx.

What wins are there for setting things up like this instead?

Post #9

eaverdeja

Wouldn’t it enable us to build component libraries with thought out APIs and standalone tests? Similar to what material-ui does on the React world. That would be a big win in my book