surface-ui / surface_site Goto Github PK

Using Surface components in plain Phoenix templates is usually not recommended so I think it's better to move the Using Surface on plain Phoenix views (optional) section to its own page and add something like this at the top:

Surface on vanilla LV

Using a Surface component in vanilla Phoenix templates, i.e. using ~L or in *.leex files, is partially supported, however, this approach is limited and mostly not recommended. Keep in mind that Surface extends Liveview, adding extra features like slots and contexts. Since there's no built-in support for them in Phoenix, Surface needs to prepare the LV/Component to make those features work seamlessly.

If you find a Surface component you want to use in your existing phoenix project. You have the following options:

1. [Recommened] Replace the live views (or components) that will use the desired component with their Surface's counterparts, i.e. Surface.LiveView, Surface.LiveComponent and Surface.Component. This requires no extra step and you'll be able to enjoy all its features without any limitation.

2. Follow the steps described in https://surface-ui.org/getting_started#using-surface-on-plain-phoenix-views-(optional) and use ~H or .sface instead of ~L and .leex. This should work fine but some features may require extra work like implementing mount to call Surface.init(socket).

3. [Not Recommened] Inject the component using phoenix's live_component/4 directly in your template. This will work for most simple components as long as they don't make use of slots nor contexts. Other features that may be added in the future might not work with this approach either.

For example:
https://surface-ui.org/builtincomponents/Field

It should show the atom type instead, especially for a changeset.

We should mention at least SurfaceFormatter and SurfaceCatalogue.

SurfaceBootstrap and SurfaceBulma will already have their own links on the menu under "UI Components" as soon as their catalogues are set up. The work for SurfaceBootstrap has already started. See https://github.com/surface-ui/surface_site_bootstrap.

I am using FF86. The issue does not happen with Chrome.

<#Code
  language="elixir"
  module={{ SurfaceSiteWeb.GettingStarted.RenderlessComponent.Example }}
  line_range={{ 2..38 }}
  show_line_numbers
  selected_lines={{ [15] }}
/>

It would be nice if the demo site (http://surface-demo.msaraiva.io/getting_started) was available under https.

Especially as Firefox recently added a https only mode, which shows the following warning on the demo site.

I understand that this doesn't need to have the top priority, but nowadays setting up https is easy and free, using something like let's encrypt.

I apologize for such nitpicking, but I couldn't find in docs how to actually serve components from router (specifically that it should be Surface.LiveView). I guess it's obvious for those who had already bought in complexity of LiveView, but still it would be not that burdensome to mention it, say, under Components Basic section :)

I mean: wouldn't this assignment require the existence of the 'templates' folder in order for the entire rendering to work?

(being an elixir-illiterate, what am I missing?)

How hard would it be to add searching to the site?

Originally reported in surface-ui/surface_bulma#4 and surface-ui/surface#257.

Steps to reproduce:

1. Checkout to master
2. Remove the _build and deps folders
3. Get and compile the dependencies: mix deps.get and mix deps.compile
4. Run the server: iex -S mix phx.server

[I] ➜ iex -S mix phx.server
Erlang/OTP 23 [erts-11.1.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [hipe]

Compiling 79 files (.ex)

== Compilation error in file lib/surface_site_web/live/slots.ex ==
** (SyntaxError) nofile:292: unexpected token: ":" (column 25, code point U+003A)
    (surface 0.3.2) expanding macro: Surface.sigil_H/2
    lib/surface_site_web/live/slots.ex:10: SurfaceSiteWeb.Slots.render/1
    (elixir 1.11.3) lib/kernel/parallel_compiler.ex:314: anonymous fn/4 in Kernel.ParallelCompiler.spawn_workers/7

Remarks: The error does not occur if you checkout on the previous commit: 0db6877 so I suppose we introduced regression when simplyfing the Code component in the last commit: 6004d9d. It's really strange that the CI didn't catch it. (Edit: Ah, there is not CI ^^)

The Context module defines examples that are not present on the website: https://hexdocs.pm/surface/Surface.Components.Context.html#module-examples-1

If the line_range prop is not specified the following error occurs:

== Compilation error in file lib/surface_site_web/live/slots.ex ==
** (MatchError) no match of right hand side value: ["defmodule SurfaceSiteWeb.GettingStarted.RenderlessComponent do", "  defmodule Column do", "    use Surface.Component, slot: \"cols\"", "", "    @doc \"The field to be rendered\"", "    prop field, :string", "  end", "", "  defmodule Grid do", "    use Surface.Component", "", "    @doc \"The list of items to be rendered\"", "    prop items, :list, required: true", "", "    @doc \"The list of columns defining the Grid\"", "    slot cols", "", "    def render(assigns) do", "      ~H\"\"\"", "      <table class=\"table is-bordered is-striped is-hoverable is-fullwidth\">", "        <thead>", "          <tr>", "            <th :for={{ col <- @cols }}>", "              {{ Phoenix.Naming.humanize(col.field) }}", "            </th>", "          </tr>", "        </thead>", "        <tbody>", "          <tr :for={{ item <- @items }} class={{ \"is-selected\": item[:selected] }}>", "            <td :for={{ col <- @cols, field = String.to_atom(col.field) }}>", "              {{ item[field] }}", "            </td>", "          </tr>", "        </tbody>", "      </table>", "      \"\"\"", "    end", "  end", "", "  defmodule Example do", "    use Surface.LiveComponent", "", "    data albums, :list, default: []", "", "    def mount(socket) do", "      albums = [", "        %{name: \"The Dark Side of the Moon\", artist: \"Pink Floyd\", released: \"March 1, 1973\"},", "        %{name: \"OK Computer\", artist: \"Radiohead\", released: \"June 16, 1997\"},", "        %{", "          name: \"Disraeli Gears\",", ...]
    (surface_site 0.1.0) lib/surface_site_web/components/code.ex:90: SurfaceSiteWeb.Components.Code.fix_leading_space/1
    (surface_site 0.1.0) lib/surface_site_web/components/code.ex:29: SurfaceSiteWeb.Components.Code.expand/3
    (surface 0.3.2) lib/surface/compiler.ex:448: Surface.Compiler.convert_node_to_ast/3
    (surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
    (elixir 1.11.3) lib/enum.ex:2193: Enum."-reduce/3-lists^foldl/2-0-"/3
    (surface 0.3.2) lib/surface/compiler.ex:211: Surface.Compiler.to_ast/2
    (surface 0.3.2) lib/surface/compiler.ex:331: Surface.Compiler.convert_node_to_ast/3
    (surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
    (elixir 1.11.3) lib/enum.ex:2193: Enum."-reduce/3-lists^foldl/2-0-"/3
    (surface 0.3.2) lib/surface/compiler.ex:211: Surface.Compiler.to_ast/2
    (surface 0.3.2) lib/surface/compiler.ex:331: Surface.Compiler.convert_node_to_ast/3
    (surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
    (elixir 1.11.3) lib/enum.ex:2193: Enum."-reduce/3-lists^foldl/2-0-"/3
    (surface 0.3.2) lib/surface/compiler.ex:211: Surface.Compiler.to_ast/2
    (surface 0.3.2) lib/surface/compiler.ex:331: Surface.Compiler.convert_node_to_ast/3
    (surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2
    (elixir 1.11.3) lib/enum.ex:2193: Enum."-reduce/3-lists^foldl/2-0-"/3
    (surface 0.3.2) lib/surface/compiler.ex:211: Surface.Compiler.to_ast/2
    (surface 0.3.2) lib/surface/compiler.ex:331: Surface.Compiler.convert_node_to_ast/3
    (surface 0.3.2) lib/surface/compiler.ex:212: anonymous fn/3 in Surface.Compiler.to_ast/2

It is because of the split in the following function that does not match with the pattern

We should fix this to handle a full file without specify the line_range.

This page https://surface-ui.org/usage_with_phoenix_templates (related to #25) seems to not have been updated for the latest Phoenix and makes no mention of HEEX or <MyComponent.render />

Replace all:

<#Raw>
  <div style="color: rgb(212, 212, 212);  ...">...</div>
</#Raw>

with either <#Code> or embedded code in markdown.

Use <#Code> only for cases where the snippet cannot be embedded directly in markdown. For instance, when reading the code from another file.

Examples:

Embedded:

Using <#Code>:

The site documentation seems to be missing the constructs for <For> and <If> (soon to be replaced by new syntax).

Related to surface-ui/surface#192

Hi all, this might just be me but accessing the Getting Started shows Surface version 0.6.0 in the "Installation" section. It seems that the version has been bumped a while ago but is not being properly updated (maybe due to deployment or some other issue). It would be nice if the page can show version 0.7.X since 0.6.X isn't compatible with LiveView 0.17.X.

Update types introduced in surface-ui/surface#297 if necessary.

I am reading the Event section again and again and to be honest I am more an more lost 😅

The purpose of this issue is to list what I find strange in the Event section in order to share my feeling before attacking and validating a possible rewrite. I tried to take the point of view of a beginner and I tried to forget how to use events in Surface.

<Mode Beginner On>

Purpose of the default value

This section is related to the one below, but I was wondering what type should be the "default" option? String? Function?

Use cases

The use cases of the prop click, :event are not clear. We use a quick example that shows how to declare a prop event but we do not know if the event is internal to the component or if we should pass a function to that prop.

  defmodule MyButton do
    use Surface.Component

    @doc "Triggers on click"
    prop click, :event

    def render(assigns) do
      ...
    end
  end

This confusion is accentuated the next examples: Handling events in Surface/LiveView. In these examples, a prop event has not been declared but some handle_event functions have been declared. Moreover, reader also finds this sentence: "always declare event properties as :event" but it is not the case in the example. 😕

Some questions raise in my mind:

• Should we use both?
• If so, when should I declare a prop event?
• Are these use cases not the same one?
• Are the name used in :on-{name} the same as the one used in prop {name}, :event?

Use of the "click" event only

I suggest to add examples with other events (at least one): keyup, keydown, debounce, ...

phx-click is often used with phx-value:

<div phx-click="inc" phx-value-myvar1="val1" phx-value-myvar2="val2">

will send the following map of params to the server (doc):

def handle_event("inc", %{"myvar1" => "val1", "myvar2" => "val2"}, socket) do

In that case, it's not clear in Surface if I should use phx-value-myvar or :on-value-my-var. The last one seems strange to me.

<Mode Beginner Off>

I am wondering if we should rewrite this section to be more explicit and less confusing? For example, we could base the rewriting on the examples in the tests and improve them to show the "flow":

defmodule Button do
    use Surface.LiveComponent

    prop click, :event, default: "click"

    def render(assigns) do
      ~H"""
      <button :on-click={{ @click }}>Click me!</button>
      """
    end

    def handle_event("click", _, socket) do
      {:noreply, socket}
    end
  end

  defmodule Panel do
    use Surface.LiveComponent

    prop buttonClick, :event, default: "click"

    def render(assigns) do
      ~H"""
      <div>
        <Button id="button_id" click={{ @buttonClick }}/>
      </div>
      """
    end

    def handle_event("click", _, socket) do
      {:noreply, socket}
    end
  end

  # Example without default value
  defmodule View do
    use Surface.LiveView

    def render(assigns) do
      ~H"""
      <div>
        <Panel id="panel_id" buttonClick="click"/>
      </div>
      """
    end

    def handle_event("click", _, socket) do
      {:noreply, socket}
    end
  end

  # Example with default value
  defmodule View do
    use Surface.LiveView

    def render(assigns) do
      ~H"""
      <div>
        <Panel id="panel_id" />
      </div>
      """
    end
  end

I believe we should highlight some points:

• the name of the prop is not correlated to the Phoenix Event name
• the list of phoenix live view events is fixed, you cannot create new event
• the prop event could have a default value that is the first argument of the handle_event method you would like to use
• the event you want to pass through the prop follow the same assumption
• you can pass event in nested components
• show an example with a component that has multiple events (cancel and add buttons for example)
• if the event is an "internal" event to the component, you do not have to declare prop name, :event

Feel free to comment and add your feeling about this section. Even if my English level is not perfect, I would be glad to take time to rewrite this section the best I can.

Describe the bug

If you click any button in the official examples fast enough, you can break the expected behavior.

How to reproduce it

Go to https://surface-ui.org/slots

The behavior you expected

The value and the style should be on sync

Your Environment

Surface: v0.X.X
LiveView: v0.X.X
Elixir: v1.X.X

TODO:

• 1. Move project to the surface-ui org
• 2. Add sections about the new testing API and hooks (docs)
• 3. Review components without examples and see if it should add at least one
• 4. Rewiew docs
• 5. Set up deploy and publish to Gigalixir
• 6. Set up surface-ui.org domain
• 7. Move surface to the surface-ui org
• 8. Update Surface to the latest stable version
• 9. Make surface_site public

@lnr0626, @olivermt, @Malian, @miguel-s and @paulstatezny. Since you implemented some of the components we have, feel free to add examples, review the docs or help me with any of the other items you might like. Also, in case you remember anything else, feel free to add more items to the list.

Cheers.

Hi 👋 I'm a self-taught front end developer that recently started learning about Elixir and Phoenix and while I was progressing people kept suggesting Surface and here I am 😄 It's honestly amazing to see the effort that went into creating the library and how much value it has for the community so I'm excited to see it grow in the upcoming times.

When I stepped into https://surface-ui.org/, the UI, for me, didn't feel very modern and attractive and I was wondering if we could do some tweaks to it to boost its looks and make the starting experience of navigating the docs more exciting!

I have two suggestions for the homepage, one with just a simple intro ( v1 ) and another that is more informative and tries to go towards a similar look to other component libraries' websites.

Let me know if this is something that you could be interested in and I can get to work! 😄

The figma file

V1

V2

From surface-ui/surface#302 (comment):

Update the docs to inform that slots are always lists and <slot name="<name>" /> is just a short hand for <slot name="<name>" index="0" />