# Surface

[![Build Status](](

Surface is a **server-side rendering** component library that allows developers to
build **rich interactive user-interfaces**, writing minimal custom Javascript.

Built on top of [Phoenix LiveView]( and its component API,
Surface leverages the amazing Phoenix Framework to provide a **fast** and **productive** solution
to build modern web applications.

Full documentation and live examples can be found at [](

### Example

# Defining the component

defmodule Hello do
  use Surface.Component

  @doc "Someone to say hello to"
  prop name, :string, required: true

  def render(assigns) do
    Hello, {@name}!

# Using the component

defmodule Example do
  use Surface.Component

  def render(assigns) do
    <Hello name="John Doe"/>

## Features

  * **An HTML-centric** templating language, designed specifically to improve development experience.

  * **Components as modules** - they can be stateless, stateful, renderless or compile-time.

  * **Declarative properties** - explicitly declare the inputs (properties and events) of each component.

  * **Slots** - placeholders declared by a component that you can fill up with **custom content**.

  * **Contexts** - allows a parent component to share data with its children without passing them as properties.

  * **Compile-time checking** of the template structure, components' properties, slots, events and more.

  * **Integration with editor/tools** for warnings/errors, syntax highlighting, jump-to-definition,
    auto-completion (soon!) and more.

## Installation

Phoenix v1.7 comes with built-in support for LiveView apps. You can create a new phoenix application with:

mix my_app

> **Note:** In case you want to add Surface to an existing Phoenix application that doesn't have
LiveView properly installed, please see Phoenix Liveview's installation instructions at

Add `surface` to the list of dependencies in `mix.exs`:

def deps do
    {:surface, "~> 0.11.0"}

## Configuring the project using `mix surface.init`

After fetching the dependencies with `mix deps.get`, you can run the `surface.init` task to
update the necessary files in your project.

In case you want the task to also generate a sample component for you, use can use the `--demo` option.
A liveview using the component will be available at the `/demo` route.

Additionally, the task can also set up a [Surface Catalogue](
for your project using the `--catalogue` option. The catalogue will be available at `/catalogue`.

> **Note:** When using the `--demo` and `--catalogue` options together, the task also generates two
> catalogue examples and a playground for the sample component.

mix surface.init --demo --catalogue

Start the Phoenix server with:

mix phx.server

That's it! You can now access your application at http://localhost:4000.

You can see the full list of options provided by `surface.init` by running:

mix help surface.init

For further information regarding installation, including how to install Surface manually,
please visit the [Getting Started]( guide.

## Migrating from previous versions

Please see the [Migration Guide]( for details.

## Tooling

  * [Surface Formatter]( - A code formatter for Surface.
  * [Surface package for VS Code]( - Syntax highlighting support for Surface/Elixir.

## License

Copyright (c) 2020, Marlus Saraiva.

Surface source code is licensed under the [MIT License](