Component Stories

Why Stories?

Building components (like Cards, Modals, or Counters) often requires running the full application to see them. SwapStories gives you a dedicated dashboard to view your components in isolation.

It's like Storybook, but native to ASP.NET Core and Swap.Htmx.

---

🚀 Setup

1. Enable Middleware

In your Program.cs, add app.UseSwapStories() only in Development.

if (app.Environment.IsDevelopment())
{
    app.UseSwapStories(); // Serves dashboard at /_swap/stories
}

2. Define Stories

Add the [SwapStory] attribute to any controller action. Ideally, create a dedicated StoriesController.

using Swap.Htmx.Stories;

public class StoriesController : SwapController
{
    [SwapStory("Product Card", "Shop", Description = "A standard product preview")]
    public IActionResult ProductCard()
    {
        var mockProduct = new Product(1, "Super Gadget", 99.99m);
        return PartialView("_ProductCard", mockProduct);
    }

    [SwapStory("Cart Modal (Open)", "Shop", Width = 400, Height = 600)]
    public IActionResult CartModal()
    {
        return PartialView("_CartModal", new CartViewModel());
    }
}

---

🎛 The Dashboard

Navigate to /_swap/stories.

You will see a sidebar with your categories ("Shop", etc.). Clicking a story renders it in an isolated iframe.

Features

• Zero Config: Auto-scans your controllers for [SwapStory].
• Viewport Testing: Define Width and Height to test responsiveness.
• Hot Reload: Works perfectly with dotnet watch. Change your partial, and refresh the frame.

---

Tips

• Return Views or Partials: Stories can return PartialView or View. If your partial requires external scripts (like HTMX or specific CSS), consider using a _StoryLayout or returning a full View.
• Interactive Components: Since it's a real controller action, you can include buttons that trigger HTMX requests. They will work inside the iframe!