Phoenix Live Storybook

https://hexdocs.pm/phx_live_storybook/
Admin
Phoenix Live Storybook provides a storybook-like UI interface for exploring, documenting, and...
Tokens:8,329
Snippets:70
Trust Score:9.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### Component Story Example (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/setup

This Elixir script defines a component story for a button. It uses `PhxLiveStorybook.Story` to specify the component function, description, and different variations with attributes.

```elixir
# storybook/components/button.story.exs
defmodule MyAppWeb.Storybook.Components.Button do
  alias MyAppWeb.Components.Button

  # :live_component or :page are also available
  use PhxLiveStorybook.Story, :component

  def function, do: &Button.button/1
  def description, do: "A simple generic button."

  def variations do [
    %Variation{
      id: :default,
      attributes: %{
        label: "A button"
      }
    },
    %Variation{
      id: :green_button,
      attributes: %{
        label: "Still a button",
        color: :green
      }
    }
  ]
  end
end
```

--------------------------------

### Add PhxLiveStorybook Dependency (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/setup

This snippet shows how to add the `phx_live_storybook` dependency to your `mix.exs` file. After adding, run `mix deps.get` to fetch the dependency.

```elixir
def deps do
  [
    {:phx_live_storybook, "~> 0.4.0"}
  ]
end
```

--------------------------------

### Component Assets JavaScript Bundle (JavaScript)

Source: https://hexdocs.pm/phx_live_storybook/setup

This JavaScript code creates a bundle for component assets, including hooks, parameters, and uploaders. This bundle is used by both the application and the storybook.

```javascript
// assets/js/storybook.js

import * as Hooks from "./hooks";
import * as Params from "./params";
import * as Uploaders from "./uploaders";

(function () {
  window.storybook = { Hooks, Params, Uploaders };
})();
```

--------------------------------

### Create Storybook Backend Module (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/setup

This Elixir code defines the storybook backend module. It uses `PhxLiveStorybook` and configures application, content path, and asset paths for CSS and JavaScript.

```elixir
# lib/my_app_web/storybook.ex
defmodule MyAppWeb.Storybook do
  use PhxLiveStorybook,
    otp_app: :my_app,
    content_path: Path.expand("../storybook", __DIR__),
    # assets path are remote path, not local file-system paths
    css_path: "/assets/my_components.css",
    js_path: "/assets/my_components.js"
end
```

--------------------------------

### Configure Router for Storybook Access (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/setup

This Elixir snippet demonstrates how to integrate PhxLiveStorybook into your Phoenix router. It includes `storybook_assets()` and `live_storybook` to define the storybook endpoint.

```elixir
# lib/my_app_web/router.ex
use MyAppWeb, :router
import PhxLiveStorybook.Router
...
scope "/" do
  storybook_assets()
end

scope "/", PhxLiveStorybookSampleWeb do
  pipe_through(:browser)
  ...
  live_storybook "/storybook", backend_module: MyAppWeb.Storybook
end
```

--------------------------------

### Start Theme Registry in Elixir Application

Source: https://hexdocs.pm/phx_live_storybook/theming

This code snippet shows how to start a `Registry` named `ThemeRegistry` with duplicate keys allowed in the `PhoenixStorybook.Application` module. This registry will be used to store theme information linked to specific LiveView PIDs.

```elixir
defmodule PhenixStorybook.Application do
  def start(_type, _args) do
    children = [
      {Registry, keys: :duplicate, name: ThemeRegistry}
    ]
  end
end
```

--------------------------------

### CSS Theming Example

Source: https://hexdocs.pm/phx_live_storybook/theming

Demonstrates how to apply theme-specific CSS classes to HTML elements. The example shows styling for a `body` with `theme-colorful` and nested `h1` elements, enabling visual differentiation based on the active theme.

```css
body.theme-colorful {
  font-family: // ...
}

.theme-colorful h1 {
  font-family: // ...
  font-size: // ...
}
```

--------------------------------

### Define a Page Story in PhxLiveStorybook

Source: https://hexdocs.pm/phx_live_storybook/PhxLiveStorybook

Example of defining a page story. This requires a description, a render function for content, and optionally a navigation function for sub-navigation tabs.

```elixir
# storybook/my_page.exs
defmodule MyAppWeb.Storybook.MyPage do
  use PhxLiveStorybook.Story, :page

  def description, do: "My page description"

  def navigation do
    [
      {:tab_one, "Tab One", "tab-icon"},
      {:tab_two, "Tab Two", "tab-icon"}
    ]
  end

  def render(assigns) do
    ~H"<div>Your HEEX template</div>"
  end
end
```

--------------------------------

### Define a Live Component Story in PhxLiveStorybook

Source: https://hexdocs.pm/phx_live_storybook/PhxLiveStorybook

Example for defining a live component story. This requires a 'component' function pointing to the LiveComponent module, a description, and optional attributes, slots, and variations.

```elixir
# storybook/my_live_component.exs
defmodule MyAppWeb.Storybook.MyLiveComponent do
  use PhxLiveStorybook.Story, :live_component

  # required
  def component, do: MyAppWeb.MyLiveComponent
  def description, do: "My live component description"
  def attributes, do: []
  def slots, do: []
  def variations, do: []
end
```

--------------------------------

### Define a Component Story in PhxLiveStorybook

Source: https://hexdocs.pm/phx_live_storybook/PhxLiveStorybook

Example of how to define a component story. This requires specifying the component function, a description, and optionally attributes, slots, and variations.

```elixir
# storybook/my_component.exs
defmodule MyAppWeb.Storybook.MyComponent do
  use PhxLiveStorybook.Story, :component

  # required
  def function, do: &MyAppWeb.MyComponent.my_component/1
  def description, do: "My component description"

  def attributes, do: []
  def slots, do: []
  def variations, do: []
end
```

--------------------------------

### Inject JS Context for PhxLiveStorybook Components

Source: https://hexdocs.pm/phx_live_storybook/sandboxing

This snippet demonstrates how to inject custom JavaScript Hooks, Params, and Uploaders into the PhxLiveStorybook context. It requires importing necessary modules and assigning them to `window.storybook` before the storybook script loads. This setup is configured in `config.exs` with the `js_path` option.

```javascript
// assets/js/my_components.js
import * as Hooks from "./hooks";
import * as Params from "./params";
import * as Uploaders from "./uploaders";
(function () {
  window.storybook = { Hooks, Params, Uploaders };
})();
```

--------------------------------

### Implement JS-Controlled Visibility for Components in PhxLiveStorybook

Source: https://hexdocs.pm/phx_live_storybook/components

An example of a PhxLiveStorybook component that controls its visibility client-side using JS commands. It includes a button to toggle the modal and defines variations.

```elixir
defmodule Storybook.Components.Modal do
  use PhxLiveStorybook.Story, :component

  def function, do: &Components.Modal.modal/1

  def template do
    """
    <div>
      <button phx-click={Modal.show_modal()}>Open modal</button>
      <.lsb-variation/>
    </div>
    """
  end

  def variations do
    [
      %Variation{
        id: :default_modal,
        slots: ["<:body>hello world</:body>"]
      }
    ]
  end
end
```

--------------------------------

### Declare Custom Icons in PhxLiveStorybook (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/icons

Examples of declaring icons using FontAwesome and HeroIcons providers. Each icon is specified as a tuple with provider, name, optional style, and optional CSS classes. FontAwesome uses :fa prefix, HeroIcons use :hero.

```elixir
{:fa, "book"} # note that the FontAwesome icon name omits the fa- prefix
{:fa, "book", :solid} # same than previous one, :solid is the default style
{:fa, "skull", :duotone} # only for FontAwesome paid users
{:fa, "skull", :duotone, "lsb-px-2"}
{:hero, "cake"} # for all HeroIcons
{:hero, "cake", :outline} # same than previous one, :outline is the default style
{:hero, "cake", :outline, "lsb-w-2 lsb-h-2"}
```

--------------------------------

### Hiding Template Code in PhxLiveStorybook Previews

Source: https://hexdocs.pm/phx_live_storybook/components

This example shows how to use the lsb-code-hidden attribute in a HEEx template to render only the variation markup in code previews, excluding the surrounding template. It includes a button to open a modal via JS. Purpose is to simplify previews for components like modals; no additional dependencies beyond Phoenix LiveView.

```elixir
"""
<div lsb-code-hidden>
  <button phx-click={Modal.show_modal()}>Open modal</button>
  <.lsb-variation/>
</div>
"""
```

--------------------------------

### LiveView Hook for Theme Management

Source: https://hexdocs.pm/phx_live_storybook/theming

Defines a `ThemeHook` module with an `on_mount` callback. This hook fetches the current user's theme, registers it in the `ThemeRegistry` associated with the current LiveView process's PID, and returns control to the LiveView.

```elixir
defmodule ThemeHook do
  def on_mount(:default, params, _session, socket) do
    theme = current_user_theme(socket, params)
    Registry.register(ThemeRegistry, :theme, theme)
    {:cont, socket}
  end
end
```

--------------------------------

### Fetch Theme from Registry Helper Module

Source: https://hexdocs.pm/phx_live_storybook/theming

Provides a `ThemeHelpers` module with a `set_theme` function. This function looks up the theme in `ThemeRegistry` using the current process's PID, merges it into the component's assigns, or raises an error if the theme is not found.

```elixir
defmodule ThemeHelpers do
  def set_theme(assigns) do
    pid_and_themes = Registry.lookup(ThemeRegistry, :theme)

    case find_by_pid(pid_and_themes, self()) do
      {_pid, theme} -> Map.put_new(assigns, :theme, theme)
      _ -> raise("theme not found in registry")
    end
  end

  defp find_by_pid(pid_and_themes, current_pid) do
    Enum.find(pid_and_themes, fn {pid, _} -> pid == current_pid end)
  end
end
```

--------------------------------

### Defining Slots and Let Bindings in PhxLiveStorybook Variations

Source: https://hexdocs.pm/phx_live_storybook/components

These variations illustrate passing HEEx slots to components, including named slots and using let for data binding in default or named slots. For modals, slots define buttons; for lists/tables, let binds iteration data like entries or users. Inputs are attributes like stories or rows; outputs render dynamic content; limitations include needing explicit let declarations for default blocks.

```elixir
%Variation{
  id: :modal,
  slots: [
    """
    <:button>
      <button type="button">Cancel</button>
    </:button>
    """,
    """
    <:button>
      <button type="button">OK</button>
    </:button>
    """
  ]
}
```

```elixir
%Variation{
  id: :list,
  attributes: %{stories: ~w(apple banana cherry)},
  let: :entry,
  slots: [
    "I like <%= entry %>"
  ]
}
```

```elixir
%Variation{
  id: :table,
  attributes: %{
    rows: [
      %{first_name: "Jean", last_name: "Dupont"},
      %{first_name: "Sam", last_name: "Smith"}
    ]
  },
  slots: [
    """
    <:col let={user} label="First name">
      <%= user.first_name %>
    </:col>
    """,
    """
    <:col let={user} label="Last name">
      <%= user.last_name %>
    </:col>
    """
  ]
}
```

--------------------------------

### Configure Component Container in PhxLiveStorybook

Source: https://hexdocs.pm/phx_live_storybook/components

Defines the HTML container for a component within PhxLiveStorybook. The `container/0` function can return a div with custom attributes or simply ':iframe' for sandboxed rendering.

```elixir
defmodule Storybook.MyComponent do
  use PhxLiveStorybook.Story, :component
  def container, do: {:div, class: "block"}
end
```

```elixir
defmodule Storybook.MyComponent do
  use PhxLiveStorybook.Story, :component
  def container, do: :iframe
end
```

--------------------------------

### Define Component Template in PhxLiveStorybook

Source: https://hexdocs.pm/phx_live_storybook/components

Specifies a wrapper template for all variations of a component within PhxLiveStorybook. The `<.lsb-variation/>` placeholder is where the actual variation content is injected.

```elixir
def template do
  """
  <div class="my-custom-wrapper">
    <.lsb-variation/>
  </div>
  """
end
```

--------------------------------

### Mount LiveView Hook in Router

Source: https://hexdocs.pm/phx_live_storybook/theming

Illustrates how to mount the `ThemeHook` within the `live_session` in a Phoenix router configuration. This ensures the hook is active for the specified session, allowing it to manage theme settings.

```elixir
defmodule Router do
  live_session :default, on_mount: [ThemeHook] do
    scope "/" do
      # ...
    end
  end
end
```

--------------------------------

### Apply Templates to Variation Groups in PhxLiveStorybook

Source: https://hexdocs.pm/phx_live_storybook/components

Demonstrates how to apply templates to variation groups in PhxLiveStorybook. Templates can wrap each variation individually or all variations within the group collectively.

```elixir
"""
<div class="one-wrapper-for-each-variation">
  <.lsb-variation/>
</div>
"""
```

```elixir
"""
<div class="a-single-wrapper-for-all">
  <.lsb-variation-group/>
</div>
"""
```

--------------------------------

### Enable iframe Rendering for PhxLiveStorybook Components

Source: https://hexdocs.pm/phx_live_storybook/sandboxing

This Elixir code snippet shows how to enable iframe rendering for a specific component within PhxLiveStorybook. By setting the `container` option to `:iframe` for a story, the component will be rendered in an iframe, which is useful for components that need to bind listeners directly to the `document` or have other global dependencies.

```elixir
# storybook/components/button.exs
defmodule MyAppWeb.Storybook.Components.Button do
 alias MyAppWeb.Components.Button
 use PhxLiveStorybook.Story, :component

def function, do: &Button.button/1
def container, do: :iframe

 # ...
end

```

--------------------------------

### Add HeroIcons Dependency in Mix.exs (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/icons

Add the HeroIcons Elixir dependency to your mix.exs file to enable icon rendering. Ensures heroicons_elixir library is included for full icon functionality.

```elixir
defp deps do
  [
    {:heroicons, "~> 0.5.0"}
  ]
end
```

--------------------------------

### Define Aliases and Imports for Nested Components in PhxLiveStorybook

Source: https://hexdocs.pm/phx_live_storybook/components

Sets up custom aliases and imports for referencing nested components or JS commands within a PhxLiveStorybook story. This simplifies calls to other modules and functions.

```elixir
defmodule NestedComponent do
  use PhxLiveStorybook.Story, :component
  def function, do: &NestedComponent.nested_component/1

  def aliases, do: [MyStorybook.Helpers.JSHelpers]
  def imports, do: [{NestedComponent, nested: 1}]

  def variations do
    [
      %Variation{
        id: :default,
        slots: [
          "<._nested phx-click={JSHelpers.toggle()}>hello</.nested>"
          "<._nested phx-click={JSHelpers.toggle()}>world</.nested>"
        ]
      }
    ]
  end
end
```

--------------------------------

### Elixir-Controlled Visibility in PhxLiveStorybook Stories

Source: https://hexdocs.pm/phx_live_storybook/components

This snippet defines a story module for a Slideover component that uses Phoenix LiveView assigns and events to toggle visibility without relying on JS commands. It includes a template with a button to trigger the show assign and a variation that handles the close event. Dependencies include PhxLiveStorybook and Phoenix JS; inputs are button clicks, outputs update component assigns for visibility.

```elixir
defmodule Storybook.Components.Slideover do
  use PhxLiveStorybook.Story, :component
  def function, do: &Components.Slideover.slideover/1

  def template do
    """
    <div>
      <button phx-click={JS.push("assign", value: %{show: true})}>
        Open slideover
      </button>
      <.lsb-variation/>
    </div>
    """
  end

  def variations do
    [
      %Variation{
        id: :default_slideover,
        attributes: %{
          close_event: JS.push("assign", value: %{variation_id: :default_slideover, show: false})
        },
        slots: ["<:body>Hello world</:body>"]
      }
    ]
  end
end
```

--------------------------------

### Configure PhxLiveStorybook with Custom Sandbox Class

Source: https://hexdocs.pm/phx_live_storybook/sandboxing

This Elixir code configures PhxLiveStorybook to use a custom sandbox class for component styling. This class is used to scope component styles and prevent conflicts with the storybook's styling, particularly when using utility-first CSS frameworks like TailwindCSS.

```elixir
# lib/my_app_web/storybook.ex
defmodule MyAppWeb.Storybook do
  use PhxLiveStorybook,
    ...
    sandbox_class: "my-app-sandbox",

```

--------------------------------

### Pass Placeholder Attributes in PhxLiveStorybook Templates

Source: https://hexdocs.pm/phx_live_storybook/components

Shows how to pass additional HTML attributes to the variation placeholder (`.lsb-variation` or `.lsb-variation-group`) within a PhxLiveStorybook template.

```elixir
"""
<.form_for for={:user} let={f}>
  <.lsb-variation form={f}/>
</.form>
"""
```

--------------------------------

### Configure FontAwesome Icons in PhxLiveStorybook (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/icons

Configure FontAwesome for extended icon sets by specifying the plan and kit ID in the Storybook module. Requires FontAwesome kit ID and appropriate plan configuration.

```elixir
# lib/my_app_web/storybook.ex
defmodule MyAppWeb.Storybook do
  use PhxLiveStorybook,
    otp_app: :my_app,
    font_awesome_plan: :pro, # default value is :free
    font_awesome_kit_id: "foo8b41bar4625",
end
```

--------------------------------

### Apply Scoped Component Styles with TailwindCSS Layers

Source: https://hexdocs.pm/phx_live_storybook/sandboxing

This CSS snippet defines component styles using TailwindCSS's `@layer utilities`. By nesting styles under this layer and ensuring the Tailwind configuration uses the `important` selector with the `sandbox_class`, these styles are effectively scoped to the component's sandbox, preventing global style leaks. It also includes a `:not(i)` selector to avoid overriding icon styles.

```css
/* assets/css/components.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer utilities {
  /* this style will be generated as .my-app-sandbox :not(i) { ... } */
  /* we use :not(i) instead of * because we don't want to override FontAwesome icons styles */
  /* (some icons are indeed rendered with your own sandboxed styles) */
  :not(i) {
    font-family: "MyComponentsFont";
    @apply text-slate-600;
  }

  /* this style will be generated as .my-app-sandbox h1 { ... } */
  h1 {
    @apply text-2xl font-bold text-slate-700 mt-2 mb-6;
  }

  /* this style will be generated as .my-app-sandbox h2 { ... } */
  h2 {
    @apply text-xl font-bold text-slate-700 mt-2 mb-4;
  }
}

```

--------------------------------

### Late Evaluation of Attributes in PhxLiveStorybook Variations

Source: https://hexdocs.pm/phx_live_storybook/components

This variation uses the {:eval, expression} tuple for attributes like JS events to delay evaluation until runtime, preserving the original expression in code previews. It applies to a Modal component's on-open and on-close events. Purpose avoids complex rendered outputs in previews; inputs are JS push events; outputs execute at runtime without altering preview appearance.

```elixir
%Variation{
  attributes: %{
    :"on-open": JS.push("open"),
    :"on-close": {:eval, ~s|JS.push("close")|}
  }
}
```

--------------------------------

### Scope Component Styles with TailwindCSS Sandbox Class

Source: https://hexdocs.pm/phx_live_storybook/sandboxing

This JavaScript configuration for TailwindCSS sets an `important` selector using a custom sandbox class. This ensures that component styles, when nested within the sandbox, gain higher specificity and do not unintentionally override storybook styles. It's used in conjunction with the `sandbox_class` configuration in `config.exs`.

```javascript
// assets/tailwind.config.js
module.exports = {
  // ...
  important: ".my-app-sandbox",
};

```

--------------------------------

### Type Definition for VariationGroup (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/PhxLiveStorybook.Stories

Specifies the structure and types for a VariationGroup. It includes fields for an ID, an optional description, a template, and a list of Variations.

```Elixir
@type t() :: %PhxLiveStorybook.Stories.VariationGroup{
  description: String.t() | nil,
  id: atom(),
  template: :unset | String.t() | nil | false,
  variations: [PhxLiveStorybook.Stories.Variation.t()]
}
```

--------------------------------

### Define Variation Group with Variations (Elixir)

Source: https://hexdocs.pm/phx_live_storybook/PhxLiveStorybook.Stories

Defines a group of similar variations, each with its own ID and attributes, intended to be rendered together. This structure is used to organize different states or configurations of a component for previewing.

```Elixir
def variations do
  [
    %VariationGroup{
      id: :colors,
      description: "Different color buttons",
      variations: [
        %Variation{
          id: :blue_button,
          attributes: %{label: "A button", color: :blue }
        },
        %Variation{
          id: :red_button,
          attributes: %{label: "A button", color: :red }
        },
        %Variation{
          id: :green_button,
          attributes: %{label: "A button", color: :green }
        }
      ]
    }
  ]
end
```
Tokens:
Raw