cannot appear in one and be missing from the other. Adding a component means

  adding an entry here and a matching `component_demo/1` clause in

  `ComponentsLive`; `ComponentsLive` has a test that asserts every slug here

  resolves to a page.

  resolves to a page, and `ComponentCatalogTest` asserts the catalog covers

  every public function component in the modules it claims to document.

  Two component sets ship in this repo and they are catalogued separately:

    * `OpenAgentsWeb.CoreComponents` — the Phoenix-generated set, styled with

      DaisyUI. Imported by `use OpenAgentsWeb, :live_view`.

    * `OpenAgentsWeb.SarahUI` — the Sarah interface primitives, imported

      separately via `sarah_html_helpers`. `button`, `input`, and `icon` exist

      in both sets, which is why the SarahUI slugs are prefixed `sarah-`.

  Icon names are drawn from the vendored Apps SDK set (`OpenAgentsWeb.Icons`).

  """

        }

      ]

    },

    %{

      title: "Sarah UI",

      items: [

        %{

          slug: "sarah-button",

          title: "Button",

          icon: "cube",

          source: "OpenAgentsWeb.SarahUI.button/1",

          summary: "Eight variants, four sizes, and a danger tone."

        },

        %{

          slug: "sarah-text-button",

          title: "Text button",

          icon: "text",

          source: "OpenAgentsWeb.SarahUI.text_button/1",

          summary: "Borderless action for inline and secondary affordances."

        },

        %{

          slug: "sarah-input",

          title: "Input",

          icon: "square-text",

          source: "OpenAgentsWeb.SarahUI.input/1",

          summary: "Bare text input primitive, unwrapped by a form field."

        },

        %{

          slug: "sarah-textarea",

          title: "Textarea",

          icon: "text",

          source: "OpenAgentsWeb.SarahUI.textarea/1",

          summary: "Multi-line text primitive."

        },

        %{

          slug: "sarah-label",

          title: "Label",

          icon: "tag",

          source: "OpenAgentsWeb.SarahUI.label/1",

          summary: "Form label bound to a control by id."

        },

        %{

          slug: "sarah-field",

          title: "Field",

          icon: "file-document",

          source: "OpenAgentsWeb.SarahUI.field/1",

          summary: "Wrapper that stacks a label and its control."

        },

        %{

          slug: "sarah-alert",

          title: "Alert",

          icon: "warning",

          source: "OpenAgentsWeb.SarahUI.alert/1",

          summary: "Four variants across box, row, and notice appearances."

        },

        %{

          slug: "sarah-badge",

          title: "Badge",

          icon: "tag",

          source: "OpenAgentsWeb.SarahUI.badge/1",

          summary: "Status pill in six variants."

        },

        %{

          slug: "sarah-card",

          title: "Card",

          icon: "square-image",

          source: "OpenAgentsWeb.SarahUI.card/1",

          summary: "Content container with an optional corner frame and danger variant."

        },

        %{

          slug: "sarah-avatar",

          title: "Avatar",

          icon: "user",

          source: "OpenAgentsWeb.SarahUI.avatar/1",

          summary: "Image or initials fallback in three sizes."

        },

        %{

          slug: "sarah-item",

          title: "Item",

          icon: "dot",

          source: "OpenAgentsWeb.SarahUI.item/1",

          summary: "Status, label, and detail row for activity lists."

        },

        %{

          slug: "sarah-event-header",

          title: "Event header",

          icon: "info",

          source: "OpenAgentsWeb.SarahUI.event_header/1",

          summary: "Titled event row with status, timestamp, and chip slot."

        },

        %{

          slug: "sarah-empty",

          title: "Empty state",

          icon: "circle",

          source: "OpenAgentsWeb.SarahUI.empty/1",

          summary: "Placeholder for lists and panels with nothing to show."

        },

        %{

          slug: "sarah-kbd",

          title: "Keyboard key",

          icon: "keyboard",

          source: "OpenAgentsWeb.SarahUI.kbd/1",

          summary: "Rendered keycap for shortcut documentation."

        },

        %{

          slug: "sarah-menu",

          title: "Menu",

          icon: "menu",

          source: "OpenAgentsWeb.SarahUI.menu/1",

          summary: "Popover menu surface used by the account control."

        },

        %{

          slug: "sarah-frame",

          title: "Frame",

          icon: "grid",

          source: "OpenAgentsWeb.SarahUI.frame/1",

          summary: "Corner-bracket decoration around arbitrary content."

        },

        %{

          slug: "sarah-status-indicator",

          title: "Status indicator",

          icon: "check-circle",

          source: "OpenAgentsWeb.SarahUI.status_indicator/1",

          summary: "Labelled state dot, optionally decorative."

        },

        %{

          slug: "sarah-audio-player",

          title: "Audio player",

          icon: "play",

          source: "OpenAgentsWeb.SarahUI.audio_player/1",

          summary: "Labelled audio element for recordings."

        },

        %{

          slug: "sarah-icon",

          title: "Icon",

          icon: "sparkle",

          source: "OpenAgentsWeb.SarahUI.icon/1",

          summary: "Apps SDK glyph with an optional accessible label."

        }

      ]

    },

    %{

      title: "Layout",

      items: [

          icon: "moon",

          source: "OpenAgentsWeb.Layouts.theme_toggle/1",

          summary: "System, light, and dark. The same control sits in the site header."

        },

        %{

          slug: "command-bar",

          title: "Command bar",

          icon: "compass",

          source: "OpenAgentsWeb.Layouts.command_bar/1",

          summary: "Top bar with brand lockup, control slot, and account menu."

        },

        %{

          slug: "account-control",

          title: "Account control",

          icon: "user",

          source: "OpenAgentsWeb.Layouts.account_control/1",

          summary: "Avatar trigger and popover menu for the signed-in user."

        }

      ]

    },

  @doc "Look up one item by slug. Returns nil when the slug is unknown."

  def fetch(slug), do: Enum.find(items(), &(&1.slug == slug))

  @doc """

  The modules this catalog claims to document, and the components in each that

  are deliberately not given a page.

  `OpenAgentsWeb.Layouts.app/1` and `flash_group/1` wrap the catalog page

  itself, so they cannot be demoed inside it.

  """

  def documented_modules do

    %{

      OpenAgentsWeb.CoreComponents => [],

      OpenAgentsWeb.SarahUI => [],

      OpenAgentsWeb.Layouts => [:app, :flash_group]

    }

  end

end

  """

  def theme_toggle(assigns) do

    ~H"""

    <div class="card relative flex flex-row items-center border-2 border-base-300 bg-base-300 rounded-full">

    <%!-- w-24 is load-bearing: the three buttons are w-1/3, so without an explicit

    width this stretches to fill any block-level parent and the segments stretch

    with it. 24 (6rem) is the natural content width: 3 buttons x (p-2 + size-4). --%>

    <div class="card relative flex flex-row items-center w-24 shrink-0 border-2 border-base-300 bg-base-300 rounded-full">

      <div class="absolute w-1/3 h-full rounded-full border-1 border-base-200 bg-base-100 brightness-200 left-0 [[data-theme=light]_&]:left-1/3 [[data-theme=dark]_&]:left-2/3 [[data-theme-source=system]_&]:!left-0 transition-[left]" />

      <button

  use OpenAgentsWeb, :live_view

  alias OpenAgentsWeb.ComponentCatalog

  alias OpenAgentsWeb.SarahUI, as: UI

  @sample_rows [

    %{id: 1, owner: "OpenAgentsInc", repo: "openagents.com", state: "open"},

    hero-arrow-path hero-sun-micro hero-moon-micro hero-computer-desktop-micro

  )

  # SarahUI.icon/1 renders the vendored Apps SDK set, not heroicons.

  @sarah_icons ~w(sparkle compass folder document user bell play star)

  # account_control/1 and command_bar/1 read three fields off the current user.

  # A plain map is enough and keeps the catalog page free of database access.

  @demo_user %{

    github_login: "openagents-demo",

    github_name: "Demo Account",

    github_avatar_url: nil

  }

  @impl true

  def mount(_params, _session, socket) do

    form =

     socket

     |> assign(:form, form)

     |> assign(:rows, @sample_rows)

     |> assign(:icons, @icons)}

     |> assign(:icons, @icons)

     |> assign(:sarah_icons, @sarah_icons)

     |> assign(:demo_user, @demo_user)}

  end

  @impl true

    <div id="components-index" class="max-w-3xl">

      <h1 class="text-3xl font-semibold mb-4">Component library</h1>

      <p class="text-base-content/70 mb-8 text-pretty max-w-[68ch]">

        Live examples of every reusable function component in this repository.

        These controls come from <code>OpenAgentsWeb.CoreComponents</code>

        and <code>OpenAgentsWeb.Layouts</code>, styled with DaisyUI. Planned

        GitHub-shaped components are listed in <code>docs/component-library.md</code>.

        Live examples of every reusable function component in this repository, drawn from

        <code>OpenAgentsWeb.CoreComponents</code>

        (the Phoenix set, styled with DaisyUI), <code>OpenAgentsWeb.SarahUI</code>

        (the Sarah interface primitives), and <code>OpenAgentsWeb.Layouts</code>. <code>button</code>, <code>input</code>, and

        <code>icon</code>

        exist in both component sets, so the SarahUI entries are listed separately.

        A test asserts this page covers every public component in those modules.

        Planned GitHub-shaped components are listed in <code>docs/component-library.md</code>.

      </p>

      <section :for={section <- ComponentCatalog.sections()} class="mb-10">

  attr :form, :any, default: nil

  attr :rows, :list, default: []

  attr :icons, :list, default: []

  attr :sarah_icons, :list, default: []

  attr :demo_user, :map, default: nil

  defp component_demo(%{item: %{slug: "button"}} = assigns) do

    ~H"""

    />

    """

  end

  # --- Sarah UI -------------------------------------------------------------

  # SarahUI is imported by `sarah_html_helpers`, not by `:live_view`, so these

  # are called with the full module prefix. That also documents provenance on a

  # page whose whole job is showing where a component comes from.

  defp component_demo(%{item: %{slug: "sarah-button"}} = assigns) do

    ~H"""

    <div class="space-y-4">

      <div class="flex flex-wrap items-center gap-3">

        <UI.button

          :for={v <- ~w(primary secondary outline ghost destructive chip notched link)a}

          variant={v}

        >

          {v |> Atom.to_string() |> String.capitalize()}

        </UI.button>

      </div>

      <div class="flex flex-wrap items-center gap-3">

        <UI.button :for={sz <- ~w(xs sm default lg)a} size={sz}>{sz}</UI.button>

      </div>

      <div class="flex flex-wrap items-center gap-3">

        <UI.button tone={:danger}>Danger tone</UI.button>

        <UI.button disabled>Disabled</UI.button>

      </div>

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-text-button"}} = assigns) do

    ~H"""

    <div class="flex flex-wrap items-center gap-4">

      <UI.text_button>Default</UI.text_button>

      <UI.text_button tone={:danger}>Danger</UI.text_button>

      <UI.text_button disabled>Disabled</UI.text_button>

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-input"}} = assigns) do

    ~H"""

    <div class="space-y-3 max-w-sm">

      <UI.input id="sarah-input-demo" name="demo" value="Ship the catalog" />

      <UI.input id="sarah-input-demo-empty" name="demo_empty" placeholder="Placeholder text" />

      <UI.input id="sarah-input-demo-disabled" name="demo_disabled" value="Disabled" disabled />

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-textarea"}} = assigns) do

    ~H"""

    <div class="max-w-sm">

      <UI.textarea

        id="sarah-textarea-demo"

        name="demo_body"

        value="Multi-line text primitive."

        rows="4"

      />

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-label"}} = assigns) do

    ~H"""

    <div class="space-y-2 max-w-sm">

      <UI.label for="sarah-label-target">Repository name</UI.label>

      <UI.input id="sarah-label-target" name="repo" value="openagents.com" />

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-field"}} = assigns) do

    ~H"""

    <div class="max-w-sm space-y-4">

      <UI.field>

        <UI.label for="sarah-field-title">Title</UI.label>

        <UI.input id="sarah-field-title" name="title" value="Ship the component catalog" />

      </UI.field>

      <UI.field>

        <UI.label for="sarah-field-body">Body</UI.label>

        <UI.textarea id="sarah-field-body" name="body" rows="3" />

      </UI.field>

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-alert"}} = assigns) do

    ~H"""

    <div class="space-y-6">

      <div class="space-y-3">

        <p class="text-sm text-base-content/60">Variants (box appearance)</p>

        <UI.alert :for={v <- ~w(info success warning danger)a} variant={v} label={Atom.to_string(v)}>

          A {v} alert in the default box appearance.

        </UI.alert>

      </div>

      <div class="space-y-3">

        <p class="text-sm text-base-content/60">Appearances</p>

        <UI.alert

          :for={a <- ~w(box row notice)a}

          appearance={a}

          variant={:info}

          label={Atom.to_string(a)}

        >

          The {a} appearance.

        </UI.alert>

      </div>

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-badge"}} = assigns) do

    ~H"""

    <div class="flex flex-wrap items-center gap-3">

      <UI.badge :for={v <- ~w(default info success warning danger dim)a} variant={v}>

        {v}

      </UI.badge>

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-card"}} = assigns) do

    ~H"""

    <div class="grid gap-4 sm:grid-cols-2">

      <UI.card id="sarah-card-default">

        <p class="font-medium">Default</p>

        <p class="text-sm text-base-content/70">A plain content container.</p>

      </UI.card>

      <UI.card id="sarah-card-corners" frame={:corners}>

        <p class="font-medium">Corner frame</p>

        <p class="text-sm text-base-content/70">With bracket decoration.</p>

      </UI.card>

      <UI.card id="sarah-card-danger" variant={:danger}>

        <p class="font-medium">Danger</p>

        <p class="text-sm text-base-content/70">For destructive context.</p>

      </UI.card>

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-avatar"}} = assigns) do

    ~H"""

    <div class="flex flex-wrap items-end gap-6">

      <UI.avatar :for={sz <- ~w(sm default lg)a} size={sz} fallback="OA" label={"size #{sz}"} />

      <UI.avatar tone={:accent} fallback="AC" label="accent tone" />

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-item"}} = assigns) do

    ~H"""

    <div class="space-y-2">

      <UI.item status="ok" label="Fleet node 1" detail="converged" />

      <UI.item status="pending" label="Fleet node 2" detail="rolling" />

      <UI.item status="error" label="Fleet node 3" detail="unreachable" />

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-event-header"}} = assigns) do

    ~H"""

    <UI.event_header

      id="sarah-event-header-demo"

      status="ok"

      title="repo_commit_push"

      status_note="completed"

      timestamp={~U[2026-08-19 21:51:00Z]}

    >

      <:chips>

        <UI.badge variant={:dim}>tool</UI.badge>

      </:chips>

      <p class="text-sm text-base-content/70">Pushed 3 files to the forge.</p>

    </UI.event_header>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-empty"}} = assigns) do

    ~H"""

    <UI.empty id="sarah-empty-demo" title="No delegations yet">

      Work you delegate to a paired machine will appear here.

    </UI.empty>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-kbd"}} = assigns) do

    ~H"""

    <p class="flex flex-wrap items-center gap-2 text-sm">

      Press

      <UI.kbd>⌘</UI.kbd>

      <UI.kbd>K</UI.kbd>

      to open the command bar, or

      <UI.kbd>Esc</UI.kbd>

      to dismiss it.

    </p>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-menu"}} = assigns) do

    ~H"""

    <div class="space-y-3">

      <UI.button popovertarget="sarah-demo-menu" popovertargetaction="toggle">

        Open menu

      </UI.button>

      <UI.menu id="sarah-demo-menu" label="Demo menu">

        <UI.text_button>Profile</UI.text_button>

        <UI.text_button>Settings</UI.text_button>

        <UI.text_button tone={:danger}>Sign out</UI.text_button>

      </UI.menu>

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-frame"}} = assigns) do

    ~H"""

    <UI.frame>

      <div class="p-6">

        <p class="font-medium">Framed content</p>

        <p class="text-sm text-base-content/70">Corner brackets wrap arbitrary children.</p>

      </div>

    </UI.frame>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-status-indicator"}} = assigns) do

    ~H"""

    <div class="flex flex-wrap items-center gap-6">

      <UI.status_indicator state="ok" label="Healthy" />

      <UI.status_indicator state="pending" label="Converging" />

      <UI.status_indicator state="error" label="Degraded" />

      <UI.status_indicator state="ok" label="Decorative" decorative />

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-audio-player"}} = assigns) do

    ~H"""

    <div class="space-y-2">

      <UI.audio_player

        id="sarah-audio-demo"

        src="/audio/does-not-exist.wav"

        label="Voice recording (demo source, nothing to play)"

      />

      <p class="text-sm text-base-content/60">

        The src is intentionally a dead path; this page has no recording to serve.

      </p>

    </div>

    """

  end

  defp component_demo(%{item: %{slug: "sarah-icon"}} = assigns) do

    ~H"""

    <ul id="sarah-demo-icons" role="list" class="flex flex-wrap gap-4">

      <li :for={name <- @sarah_icons} class="flex flex-col items-center gap-2 w-28">

        <UI.icon name={name} class="size-6" />

        <p class="text-center text-sm text-base-content/70">{name}</p>

      </li>

    </ul>

    """

  end

  # --- Layout ---------------------------------------------------------------

  defp component_demo(%{item: %{slug: "command-bar"}} = assigns) do

    ~H"""

    <Layouts.command_bar aria_label="Demo command bar" current_user={@demo_user}>

      <:lockup>

        <UI.badge variant={:dim}>demo</UI.badge>

      </:lockup>

      <:controls>

        <UI.text_button>Controls slot</UI.text_button>

      </:controls>

    </Layouts.command_bar>

    """

  end

  defp component_demo(%{item: %{slug: "account-control"}} = assigns) do

    ~H"""

    <div class="space-y-4">

      <div class="space-y-2">

        <p class="text-sm text-base-content/60">Bar context</p>

        <Layouts.account_control current_user={@demo_user} context={:bar} />

      </div>

      <p class="text-sm text-base-content/60 max-w-[68ch]">

        Only one instance is shown. <code>account_control/1</code>

        hard-codes the ids <code>account-menu</code>, <code>account-menu-trigger</code>, <code>logout-form</code>, and <code>logout</code>, so it can be rendered at most

        once per page — rendering the <code>:row</code>

        context alongside this one produces duplicate ids. That is fine for a layout,

        which has a single account control, but it is a real constraint on reuse.

      </p>

    </div>

    """

  end

end

defmodule OpenAgentsWeb.ComponentCatalogTest do

  @moduledoc """

  Guards the catalog against silently falling behind the code.

  The catalog was originally hand-written and drifted: nineteen SarahUI

  components shipped without ever appearing on the components page. This test

  makes that failure mode loud — adding a public function component to a

  documented module fails the suite until it is catalogued or explicitly

  excluded.

  """

  use ExUnit.Case, async: true

  alias OpenAgentsWeb.ComponentCatalog

  test "slugs are unique" do

    slugs = ComponentCatalog.slugs()

    assert length(slugs) == length(Enum.uniq(slugs))

  end

  test "every catalog entry names a module and function that actually exist" do

    for item <- ComponentCatalog.items() do

      {module, function} = parse_source(item.source)

      assert Code.ensure_loaded?(module),

             "#{item.slug} names a module that does not exist: #{inspect(module)}"

      assert function_exported?(module, function, 1),

             "#{item.slug} names #{inspect(module)}.#{function}/1, which is not exported"

    end

  end

  test "the catalog covers every public function component in the documented modules" do

    for {module, excluded} <- ComponentCatalog.documented_modules() do

      catalogued =

        ComponentCatalog.items()

        |> Enum.map(&parse_source(&1.source))

        |> Enum.filter(fn {m, _f} -> m == module end)

        |> Enum.map(fn {_m, f} -> f end)

        |> MapSet.new()

      missing =

        module

        |> function_components()

        |> Enum.reject(&(&1 in excluded))

        |> Enum.reject(&(&1 in catalogued))

      assert missing == [],

             """

             #{inspect(module)} has public function components with no catalog entry:

             #{inspect(missing)}

             Add them to OpenAgentsWeb.ComponentCatalog with a matching

             component_demo/1 clause in OpenAgentsWeb.ComponentsLive, or add them

             to the exclusion list in ComponentCatalog.documented_modules/0 with a

             reason.

             """

    end

  end

  # `__components__/0` registers every component the compiler saw attrs for,

  # including `defp` ones (Layouts.openagents_command_bar/1 is private). A

  # private component cannot be called from a catalog page, so intersect with

  # the module's actual exports rather than carrying dead exclusion entries.

  defp function_components(module) do

    Code.ensure_loaded!(module)

    exported =

      module.__info__(:functions)

      |> Enum.filter(fn {_name, arity} -> arity == 1 end)

      |> Enum.map(&elem(&1, 0))

      |> MapSet.new()

    if function_exported?(module, :__components__, 0) do

      module.__components__()

      |> Map.keys()

      |> Enum.filter(&(&1 in exported))

      |> Enum.sort()

    else

      exported

      |> Enum.reject(&String.starts_with?(Atom.to_string(&1), "__"))

      |> Enum.sort()

    end

  end

  defp parse_source(source) do

    [path, arity_part] = String.split(source, "/", parts: 2)

    ^arity_part = "1"

    segments = String.split(path, ".")

    {function, module_segments} = List.pop_at(segments, -1)

    {Module.concat(module_segments), String.to_atom(function)}

  end

end