SurfaceFormatter - A code formatter for Surface, the component-based library for Phoenix LiveView

paulstatezny

Hello everyone, I’ve just released a new library called SurfaceFormatter.

A special thanks to @msaraiva for his help and collaboration!

What is it?

SurfaceFormatter is a code formatter (like mix format) for Surface code.

If you’re not familiar with Surface, you can find it on Hex, GitHub, or the original ElixirForum post.

Why did I create it?

So that Surface developers can focus on building things without sacrificing valuable time and attention to make the code nicely formatted.

How does it work?

Add it to a Surface project, and run mix surface.format. That’s it!

Where can I find it?

https://github.com/surface-ui/surface_formatter

A short example

Surface code that looks like this:

 <RootComponent with_many_attributes={{ true }} causing_this_line_to_wrap={{ true}} because_it_is_too_long={{ "yes" }}>
   <!-- An HTML comment -->
   {{#An Elixir comment}}



   <div :if={{@show_div}}
   class="container">
       <p> Text inside paragraph    </p>
    <span>Text touching parent tags</span>
   </div>

<Child  items={{[%{name: "Option 1", key: 1}, %{name: "Option 2", key:  2},    %{name: "Option 3", key: 3}, %{name: "Option 4", key: 4}]}}>
  Contents
</Child>
</RootComponent>

will be formatted like this:

<RootComponent
  with_many_attributes
  causing_this_line_to_wrap
  because_it_is_too_long="yes, this line is long enough to wrap"
>
  {{ # An Elixir comment }}

  <div :if={{ @show_div }} class="container">
    <p>
      Text inside paragraph
    </p>
    <span>Text touching parent tags</span>
  </div>

  <Child items={{[
    %{name: "Option 1", key: 1},
    %{name: "Option 2", key: 2},
    %{name: "Option 3", key: 3},
    %{name: "Option 4", key: 4}
  ]}}>
    Contents
  </Child>
</RootComponent>

5 comments

/phoenix #library #liveview #livecomponents #surface #surface_formatter

18 2166 5

2021-11-25 00:26:26 UTC

First 5 of 5 Posts

Eiji

Does this comment disappear? Looks like just a tiny in your example …

Post #1

harmon25

This is amazing, been needing exactly this!

Thank you!

Post #2

paulstatezny

@Eiji Great observation

Yes, the parsing library from Surface itself (which SurfaceFormatter uses under the hood) does not expose those comments, so we lose them. However, you can replace them with interpolated Elixir comments instead.

{{ # Some comment }}

I think it would be great to be able to keep HTML comments. If there is enough interest, perhaps the Surface parser can be modified to expose them.

In the meantime, I have added a more thorough explanation in that section of the docs to hopefully make the “why” more clear: https://hexdocs.pm/surface_formatter/Surface.Code.html#format_string!/2-html-comments

Post #3

paulstatezny

SurfaceFormatter v0.2.1 has been released.

Previous versions didn’t allow inline elements to stay on the same line among text nodes, for example:

<p>
  I want <strong>this text</strong> to all stay on <em>one line</em>.
</p>

The previous rules were that each node (HTML element, text, or interpolation) would always be moved to a separate line. Therefore, this represents a pretty generous “relaxing” of the formatter. If anyone finds that it has become “too relaxed” in any scenarios, please post here and let me know!

Post #4

paulstatezny

SurfaceFormatter v0.7.0 was released. It comes packaged with a Formatter Plugin (available in Elixir 1.13) so that you can now run

$ mix format

to format both Elixir and Surface code in one command.

Special thanks to José Valim for adding Formatter Plugins to mix format! And to Marlus Saraiva for his part in it as well!

The next steps for SurfaceFormatter are:

To merge it into Surface so that formatting works with even less setup out of the box.
To attempt porting it into a HEEx formatter. As I understand it, formatting HEEx comes with some unique/extra technical challenges compared with Surface. We’ll see what happens.