PhoenixStorybook

https://hexdocs.pm/phoenix_storybook/
Admin
PhoenixStorybook provides a storybook-like UI interface for Phoenix components, enabling developers...
Tokens:10,784
Snippets:96
Trust Score:9.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### JavaScript Bundle for Component Assets

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

An example JavaScript file for bundling 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 };
})();
```

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

### Define a Component Story in Elixir

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

An example of a component story written in Elixir using `PhoenixStorybook.Story`. It defines the function component and its variations with different 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 PhoenixStorybook.Story, :component

  def function, do: &Button.button/1

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

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

### Create Example Story (Elixir)

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook

Demonstrates creating an example story in PhoenixStoryBook. It explains how to use the `mount/3` and `render/1` callbacks, and how to include additional source files using `extra_sources/0`.

```Elixir
defmodule MyAppWeb.Storybook.MyPage do
  use PhoenixStorybook.Story, :example

  def doc, do: "My page description"

  def extra_sources do
    [  "./template.html.heex",
        "./my_page_html.ex"
    ]
  end

  def mount(_, _, socket), do: {:ok, socket}

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

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

### Create Phoenix Storybook Backend Module

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

Defines the storybook backend module using `PhoenixStorybook`. This configuration specifies the OTP app, content path for stories, and asset paths for CSS and JavaScript.

```elixir
defmodule MyAppWeb.Storybook do
  use PhoenixStorybook,
    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
```

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

### Update Dockerfile to Copy Storybook Content

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

This snippet shows how to add a command to your `Dockerfile` to copy the storybook content into your Docker image during deployment.

```dockerfile
COPY storybook storybook
```

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

### Add Phoenix Storybook Dependency to mix.exs

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

This snippet shows how to add the `phoenix_storybook` dependency to your project's `mix.exs` file. Ensure you run `mix deps.get` after adding this.

```elixir
def deps do
  [
    {:phoenix_storybook, "~> 0.9.0"}
  ]
end
```

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

### Configure Router for Phoenix Storybook Access

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

Integrates Phoenix Storybook into your application's router. It includes forwarding requests to the storybook and defining a route for live storybook access using `live_storybook`.

```elixir
use MyAppWeb, :router
import PhoenixStorybook.Router
...
scope "/" do
  storybook_assets()
end

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

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

### Using Registry for Theme Management with Function Strategy

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

Implement theme storage per LiveView process using Elixir's Registry for concurrent user support. Start Registry in Application, register theme in a LiveView hook from user sources like params or session, mount hook in router, and use helper to fetch and assign theme in components. Depends on Registry module; inputs are user theme data, outputs are themed assigns; limitation: raises error if theme not found.

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

```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
```

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

```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
```

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

### JS-Controlled Visibility Example with Templating

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

A component story demonstrating JS-controlled visibility using templating, where a button triggers a JS command to show/hide a modal component.

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

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

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

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

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

### Configure Color Mode Setup in Phoenix Storybook

Source: https://hexdocs.pm/phoenix_storybook/color_modes

Enable color mode support in phoenix_storybook by configuring the PhoenixStorybook module. This adds a color theme picker to the Storybook header and handles sandbox dark class application based on selected mode. Supports dark, light, and system modes with automatic dark class application based on system preferences.

```elixir
use PhoenixStorybook,
  # ...
  color_mode: true
```

```elixir
use PhoenixStorybook,
  # ...
  color_mode_sandbox_dark_class: "my-dark"
```

```css
@custom-variant dark (&:where(.dark, .dark *));
```

```html
<html class="storybook-demo-sandbox dark">
  ...
</html>
```

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

### Define Default Container for Component Story

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

Example of setting a default HTML div container with a CSS class for a component story using PhoenixStorybook.Story.

```elixir
# storybook/my_component.story.exs
defmodule Storybook.MyComponent do
  use PhoenixStorybook.Story, :component
  def container, do: {:div, class: "block"}
end
```

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

### Set Iframe Container for Component Story

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

Example of configuring a component story to render within an iframe, either as a simple iframe or with custom attributes.

```elixir
# storybook/my_component.story.exs
defmodule Storybook.MyComponent do
  use PhoenixStorybook.Story, :component
  def container, do: :iframe
  # or def container, do: {:iframe, style: "display: inline; ..."}
end
```

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

### Define Variation Group Template (Single Wrapper)

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

Example of defining a single template to wrap all variations within a variation group, useful for consistent outer markup.

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

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

### Render Local Icon with CSS Classes

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

Shows how to use a locally defined icon in Phoenix Storybook, specifying the icon name and any additional Tailwind CSS classes for styling. The example renders a span tag with the provided class names.

```elixir
```elixir
{:local, "my-icon", "psb:w-2 psb:h-2"}
```
```

```html
```html
<span class="my-icon psb:w-2 psb:h-2"></span>
```
```

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

### Configure FontAwesome Kit ID in Phoenix Storybook

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

Example of configuring FontAwesome integration in Phoenix Storybook by setting the `font_awesome_kit_id` and optionally `font_awesome_plan`. Ensure your FontAwesome kit is set to 'Web Fonts' & 'CSS Only'.

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

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

### Create Page Story (Elixir)

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook

Illustrates creating a story for a page in PhoenixStoryBook. It demonstrates the render function and optional navigation function, including tab-based sub-navigation.

```Elixir
defmodule MyAppWeb.Storybook.MyPage do
  use PhoenixStorybook.Story, :page

  def doc, do: "My page description"

  def navigation do
    [  {:tab_one, "Tab One", {:fa, "book"}},
        {:tab_two, "Tab Two", {:fa, "cake", :solid}}
    ]
  end

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

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

### Create Live Component Story (Elixir)

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook

Shows how to create a story for a Phoenix LiveComponent.  It explains the difference in required functions compared to regular components, specifically using `component/0` instead of `function/0`.

```Elixir
defmodule MyAppWeb.Storybook.MyLiveComponent do
  use PhoenixStorybook.Story, :live_component

  # required
  def component, do: MyAppWeb.MyLiveComponent

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

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

### Create Component Story (Elixir)

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook

Demonstrates creating a story for a Phoenix component. It outlines the required function and attributes for a component story, including rendering options for source code display.

```Elixir
defmodule MyAppWeb.Storybook.MyComponent do
  use PhoenixStorybook.Story, :component

  # required
  def function, do: &MyAppWeb.MyComponent.my_component/1

  # By default (`:module` value), it will render the full component's mode source code.
  # - when set on `:function`, it will render only function's source code
  # - when set on `false`, the source tab will be unavailable
  def render_source, do: :function

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

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

### Inject shared JS context for PhoenixStorybook using JavaScript

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

Creates a JavaScript file that imports Hooks, Params, and Uploaders, then exposes them via window.storybook. This file is loaded before the storybook script and referenced with the js_path option in storybook.ex.

```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 };
})();
```

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

### Configuring Theming Strategies in storybook.ex

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

Define theming strategies in the PhoenixStorybook use declaration to apply themes via CSS class on sandbox, assigns, or custom function. The sandbox_class strategy adds a prefixed class to the container; assign passes theme as a socket assign; function calls a module for theme registration. Default is sandbox_class with 'theme' prefix if undefined. Requires PhoenixStorybook dependency.

```elixir
use PhoenixStorybook,
  themes_strategies: [
    sandbox_class: "prefix", # will set a class prefixed by `prefix-` on the sandbox container
    assign: :theme,
    function: {MyApp.ThemeHelper, :register_theme}
  ]
```

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

### LiveView Blocks, Slots & Let (Elixir)

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

Illustrates the usage of LiveView's block, slot, and let features within Storybook variations.  Slots allow for dynamic content injection, while `let` enables data passing to default blocks. Let syntax can also be used with named slots.

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

```elixir
%Variation{
  id: :list,
  attributes: %{stories: ~w(apple banana cherry)},
  let: :entry,
  slots: [\n    "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\">\n      <%= user.first_name %>\n    </:col>\n    """
    """<:col :let={user} label=\"Last name\">\n      <%= user.last_name %>\n    </:col>\n    """
  ]
}
```

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

### Control Story Layout (Elixir)

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

Explains how to configure story rendering layout using the `layout/0` function in Story components or live components.

```elixir
defmodule Storybook.Components.Breadcrumb do
  use PhoenixStorybook.Story, :component

  def layout, do: :one_column

  # ...
end
```

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

### Define Component Story with Default Template

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

Shows how to define a default HTML template for all variations of a component story, where the variation content is injected into the `<.psb-variation/>` placeholder.

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

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

### Define Button Component for Phoenix Storybook (Elixir)

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

This Elixir module defines a Button component for use with Phoenix Storybook. It aliases the actual Button component and uses `PhoenixStorybook.Story` to register it. The `function/0` defines how the component is rendered, and `container/0` specifies the rendering environment.

```elixir
defmodule MyAppWeb.Storybook.Components.Button do
 alias MyAppWeb.Components.Button
 use PhoenixStorybook.Story, :component

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

 # ...
end
```

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

### Render HeroIcons in Phoenix Storybook

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Components

Component for rendering HeroIcons. Requires the `:heroicons` mix dependency. Supports different icon styles and allows for CSS class customization.

```elixir
<.hero_icon name="cake" class="w-2 h-2"/>
<.hero_icon name="cake" style={:mini}/>
```

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

### Define scoped TailwindCSS styles for the sandbox using CSS

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

Creates a stylesheet that imports TailwindCSS and scopes all component styles under the custom sandbox class, applying utility classes to elements like headings and global font settings.

```CSS
/* assets/css/storybook.css */
@import "tailwindcss";

.my-app-sandbox {
  * {
    font-family: "MyComponentsFont";
    @apply text-slate-600;
  }

  h1 {
    @apply text-2xl font-bold text-slate-700 mt-2 mb-6;
  }

  h2 {
    @apply text-xl font-bold text-slate-700 mt-2 mb-4;
  }
}
```

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

### Render Source Code (Elixir)

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

Describes how to control source code rendering for components, choosing to display the entire module or only the function source code with `render_source/0`.

```elixir
defmodule Storybook.Components.Breadcrumb do
  use PhoenixStorybook.Story, :component

  def render_source, do: :function

  # ...
end
```

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

### Phoenix Storybook Icon Type Definitions

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Components

Defines the types used for icon providers and icon configurations within the phoenix_storybook project. `icon_provider()` specifies the source of the icon, while `t()` provides a flexible structure for defining icons with their names, styles, and optional classes.

```elixir
@type icon_provider() :: :fa | :hero | :local

@type t() ::
  {icon_provider(), String.t()}
  | {icon_provider(), String.t(), atom()}
  | {icon_provider(), String.t(), atom(), String.t()}
```

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

### Elixir Controlled Visibility

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

Demonstrates how to manage component visibility using `psb-assign` and `psb-toggle`  events in Elixir. This approach allows external assigns to control component state without direct JS commands.

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

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

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

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

### Configure Doc Chunks for Production Release

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

Configuration for Elixir releases to ensure documentation chunks are not stripped out, which is essential for Phoenix Storybook to display component documentation in production.

```elixir
releases:
  my_app_web: [
    strip_beams: [
      keep: ["Docs"]
    ]
  ]
]
```

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

### Add Heroicons Elixir Dependency

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

Instructions to add the `heroicons` Elixir package as a dependency in your `mix.exs` file to utilize HeroIcons within your Phoenix Storybook project.

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

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

### Add Heroicons CSS Dependency for Tailwind CSS

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

Adds the `heroicons` package as a dependency for use with Tailwind CSS. This configuration fetches the icons directly from the GitHub repository and compiles them for use as CSS resources.

```elixir
```elixir
defp deps do
  [
    {
      :heroicons,
      github: "tailwindlabs/heroicons",
      tag: "v2.2.0",
      sparse: "optimized",
      app: false,
      compile: false,
      depth: 1
    }
  ]
end
```
```

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

### Single Story Endpoint for Visual Regression Testing

Source: https://hexdocs.pm/phoenix_storybook/testing

This endpoint allows you to render a specific component story for visual regression testing. It outputs the story without the main Storybook UI.

```APIDOC
## GET /storybook/visual_tests/:component/:story

### Description
Retrieves a single component story for visual regression testing, excluding the main Storybook UI.

### Method
GET

### Endpoint
`https://localhost:4000/storybook/visual_tests/buttons/button`

### Parameters
#### Path Parameters
- **component** (string) - Required - The name of the component.
- **story** (string) - Required - The name of the story within the component.

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- The rendered HTML of the specified component story.

#### Response Example
(HTML content of the component story)
```

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

### Define imports callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the imports callback which returns a list of tuples with atoms and their arities. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback imports() :: [{atom(), [{atom(), integer()}]}]
```

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

### Configure Aliases and Imports for Nested Components

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

Demonstrates how to define custom aliases and imports within a component story to simplify referencing nested components and helper functions, improving code readability.

```elixir
defmodule NestedComponent do
  use PhoenixStorybook.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>\n<.\"nested phx-click={JSHelpers.toggle()}\">world</.nested>"
        ]
      }
    ]
  end
end
```

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

### Applying CSS Themes to Elements

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

Use theme-specific CSS classes like 'theme-colorful' on the body and elements to apply styles based on the current theme. This allows styling raw HTML and component containers consistently across the application. No dependencies beyond standard CSS; inputs are theme classes, outputs are styled elements.

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

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

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

### Create VariationGroup with Multiple Variations

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Stories

Shows how to define a variation group containing multiple similar variations that render together in a single preview block. Each variation can have different attributes while sharing the same component structure.

```elixir
def variations do
  [
    %VariationGroup{
      id: :colors,
      description: "Different color buttons",
      note: "Note that every button has a different color.",
      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
```

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

### Unified Icon Rendering in Phoenix Storybook

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Components

A versatile component that renders icons from different providers (FontAwesome, HeroIcons, local). It accepts an icon configuration tuple specifying the provider, icon name, and optional style and classes. Supports global HTML attributes.

```elixir
<.user_icon icon={:fa, "book"}/>
<.user_icon icon={:fa, "book", :thin}/>
<.user_icon icon={:fa, "book", :duotone, "fa-fw"} class="text-indigo-400"/>

<.user_icon icon={:hero, "cake"}/>
<.user_icon icon={:hero, "cake", :mini}/>
<.user_icon icon={:hero, "cake", :mini, "w-2 h-2"} class="text-indigo-400"/>

<.user_icon icon={:local, "hero-cake"}/>
<.user_icon icon={:local, "hero-cake-mini", "w-2 h-2"} class="text-indigo-400"/>
```

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

### Define layout callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the layout callback which returns an atom. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback layout() :: atom()
```

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

### Configure custom sandbox class in PhoenixStorybook using Elixir

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

Sets the sandbox_class option in the PhoenixStorybook module to isolate component styles within a dedicated CSS namespace, preventing styling conflicts between the storybook and application components.

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

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

### Apply sandbox CSS class to the application layout using HTML

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

Adds the custom sandbox class to the body element in the root layout template, enabling the scoped CSS rules to affect components rendered inside the storybook.

```HTML
<!-- lib/my_app/templates/layout/root.html.heex -->
<html>
  <body class="my-app-sandbox">
    <!-- ... -->
  </body>
</html>
```

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

### Define render_source callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the render_source callback which returns an atom. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback render_source() :: atom()
```

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

### Define template callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the template callback which returns a string. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback template() :: String.t()
```

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

### Range Story Endpoint for Visual Regression Testing

Source: https://hexdocs.pm/phoenix_storybook/testing

This endpoint allows you to render multiple component stories within a specified range for visual regression testing. It's useful for testing a set of components or stories.

```APIDOC
## GET /storybook/visual_tests

### Description
Retrieves multiple component stories within a specified alphabetical range for visual regression testing, excluding the main Storybook UI.

### Method
GET

### Endpoint
`https://localhost:4000/storybook/visual_tests?start=a&end=e`

### Parameters
#### Query Parameters
- **start** (string) - Required - The starting letter (inclusive) for the story names to render.
- **end** (string) - Required - The ending letter (inclusive) for the story names to render.

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- The rendered HTML of all component stories whose names start between the specified `start` and `end` letters.

#### Response Example
(HTML content of multiple component stories)
```

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

### Define container callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the container callback which returns an atom. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback container() :: atom()
```

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

### Reference Heroicons Tailwind Plugin in CSS

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

Demonstrates how to import the generated Heroicons Tailwind CSS plugin into your main CSS file, allowing you to use the icon classes defined in the plugin.

```css
```css
@plugin "../js/tailwind_heroicons.js";
```
```

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

### Define slots callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the slots callback which returns a list of slot types. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback slots() :: [PhoenixStorybook.Stories.Slot.t()]
```

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

### Template Code Preview

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

Shows how to hide surrounding template markup in the code preview using the `psb-code-hidden` attribute. This allows developers to focus solely on the variation markup itself.

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

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

### Define aliases callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the aliases callback which returns a list of atoms. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback aliases() :: [atom()]
```

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

### Define component callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the component callback which returns an atom. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback component() :: atom()
```

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

### Render FontAwesome Icons in Phoenix Storybook

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Components

Component for rendering FontAwesome icons. It accepts an icon name, style, and plan, along with CSS classes for customization. Requires FontAwesome assets to be available.

```elixir
<.fa_icon name="book" class="text-blue-400"/>
<.fa_icon name="book" style={:duotone} plan={:pro}/>
```

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

### Define attributes callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the attributes callback which returns a list of attribute types. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback attributes() :: [PhoenixStorybook.Stories.Attr.t()]
```

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

### Tailwind CSS Plugin for Heroicons

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

A JavaScript Tailwind CSS plugin that generates CSS variables and mask properties for Heroicons. It reads SVG files from the `deps/heroicons/optimized` directory and makes them available as Tailwind CSS classes.

```javascript
```javascript
const plugin = require("tailwindcss/plugin")
const fs = require("fs")
const path = require("path")

module.exports = plugin(function({matchComponents, theme}) {
  let iconsDir = path.join(__dirname, "../../deps/heroicons/optimized")
  let values = {}
  let icons = [
    ["", "/24/outline"],
    ["-solid", "/24/solid"],
    ["-mini", "/20/solid"],
    ["-micro", "/16/solid"]
  ]
  icons.forEach(([suffix, dir]) => {
    fs.readdirSync(path.join(iconsDir, dir)).forEach(file => {
      let name = path.basename(file, ".svg") + suffix
      values[name] = {name, fullPath: path.join(iconsDir, dir, file)}
    })
  })
  matchComponents({
    "hero": ({name, fullPath}) => {
      let content = fs.readFileSync(fullPath).toString().replace(/\r?\n|\r/g, "")
      content = encodeURIComponent(content)
      let size = theme("spacing.6")
      if (name.endsWith("-mini")) {
        size = theme("spacing.5")
      } else if (name.endsWith("-micro")) {
        size = theme("spacing.4")
      }
      return {
        [`--hero-${name}`]: `url('data:image/svg+xml;utf8,${content}')`,
        "-webkit-mask": `var(--hero-${name})`,
        "mask": `var(--hero-${name})`,
        "mask-repeat": "no-repeat",
        "background-color": "currentColor",
        "vertical-align": "middle",
        "display": "inline-block",
        "width": size,
        "height": size
      }
    }
  }, {values})
})
```
```

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

### Render Local Icons in Phoenix Storybook

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Components

Component for rendering local SVG icons. It takes an icon name and allows for additional CSS classes to be applied.

```elixir
<.local_icon name="hero-cake" />
<.local_icon name="hero-cake" class="text-blue-400"/>
```

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

### Late Evaluation (Elixir)

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

Shows how to use late evaluation for attributes, deferring evaluation until runtime while displaying the original expression in the code preview.

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

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

### Add Notes to Variations (Elixir)

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

Demonstrates adding notes to variations or variation groups for providing additional information or context within Storybook.

```elixir
%Variation{
  id: :some_special_case,
  note: """\nIn some *rare cases*, you might want to use these special attributes to customize the component\n to serve some specific use case.\n\nThe `primary_color` attribute allows you to make the component potentially look weird.\n**Use with care!**\n""",
  attributes: %{ \n    "primary_color" => "red"\n    "radius" => :very_large\n  }
}
```

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

### Declare Icon Structure in Phoenix Storybook

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

Defines the standard tuple structure for specifying icons in Phoenix Storybook, including icon provider, name, optional style, and additional CSS classes. Supports FontAwesome, HeroIcons, and local icons.

```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, "psb:px-2"}
{:hero, "cake"} # for all HeroIcons
{:hero, "cake", :outline} # same than previous one, :outline is the default style
{:hero, "cake", :outline, "psb:w-2 psb:h-2"}
{:local, "hero-cake"} # for custom or core-component-generated icons
{:local, "hero-cake", "psb:w-2 psb:h-2"}, # styles are not supported: 3rd elem is custom css
```
```

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

### Use Placeholder Attributes in Templates

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

Illustrates passing extra HTML attributes to the variation placeholder within a template, such as form attributes for form components.

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

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

### Define variations callback in LiveComponentBehaviour

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Story

Specifies the variations callback which returns a list of variation or variation group types. This is part of the LiveComponentBehaviour requirements for live component stories.

```elixir
@callback variations() :: [
  PhoenixStorybook.Stories.Variation.t()
  | PhoenixStorybook.Stories.VariationGroup.t()
]
```

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

### VariationGroup Type Definition

Source: https://hexdocs.pm/phoenix_storybook/PhoenixStorybook.Stories

Type definition for VariationGroup struct showing all available fields including id, description, note, template, and variations array. Uses PhoenixStorybook type for variations.

```elixir
@type t() :: %PhoenixStorybook.Stories.VariationGroup{
  description: String.t() | nil,
  id: atom(),
  note: String.t() | nil,
  template: :unset | String.t() | nil | false,
  variations: [PhoenixStorybook.Stories.Variation.t()]
}
```
Tokens:
Raw