feat(frontend): add Avatar, Breadcrumb, Toggle, and Progress UI components (#1168)

- Add Avatar component with image/initials fallback, size/shape variants, and status indicator
- Add Breadcrumb component with chevron/slash separators and responsive collapsing
- Add Toggle component with controlled/uncontrolled state, keyboard accessibility, and label support
- Add Progress component with size/variant options, label formatters, and ARIA support
- All components include TypeScript types, follow design system tokens, and have Jest/RTL unit tests

Closes #1094
Closes #1095
Closes #1096
Closes #1097

Co-authored-by: openhands <openhands@all-hands.dev>

Author: trinnode

soroscan-frontend/__tests__/ui-avatar.test.tsx

@@ -0,0 +1,96 @@
+import React from "react"
+import { render, screen, fireEvent } from "@testing-library/react"
+import { Avatar } from "@/components/ui/avatar"
+
+describe("Avatar Component", () => {
+  it("renders with fallback initials from alt text", () => {
+    render(<Avatar alt="John Doe" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar")).toBeInTheDocument()
+    expect(screen.getByText("J")).toBeInTheDocument()
+  })
+
+  it("renders with custom fallback prop", () => {
+    render(<Avatar fallback="JD" data-testid="avatar" />)
+    expect(screen.getByText("JD")).toBeInTheDocument()
+  })
+
+  it("renders image when src is provided", () => {
+    render(<Avatar src="/test.jpg" alt="User" data-testid="avatar" />)
+    const img = screen.getByRole("img")
+    expect(img).toHaveAttribute("src", "/test.jpg")
+    expect(img).toHaveAttribute("alt", "User")
+  })
+
+  it("falls back to initials on image error", () => {
+    render(<Avatar src="/broken.jpg" alt="Jane" data-testid="avatar" />)
+    const img = screen.getByRole("img")
+    fireEvent.error(img)
+    expect(screen.getByText("J")).toBeInTheDocument()
+    expect(screen.queryByRole("img")).not.toBeInTheDocument()
+  })
+
+  it("renders size variants with correct classes", () => {
+    const { rerender } = render(<Avatar size="xs" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar")).toHaveClass("h-6", "w-6", "text-[10px]")
+
+    rerender(<Avatar size="xl" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar")).toHaveClass("h-16", "w-16", "text-lg")
+
+    rerender(<Avatar size="2xl" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar")).toHaveClass("h-24", "w-24", "text-2xl")
+  })
+
+  it("renders square shape variant", () => {
+    render(<Avatar shape="square" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar")).toHaveClass("rounded-lg")
+  })
+
+  it("renders circle shape by default", () => {
+    render(<Avatar data-testid="avatar" />)
+    expect(screen.getByTestId("avatar")).toHaveClass("rounded-full")
+  })
+
+  it("renders status indicator when provided", () => {
+    render(<Avatar status="online" data-testid="avatar" />)
+    const indicator = screen.getByTestId("avatar-status-indicator")
+    expect(indicator).toBeInTheDocument()
+    expect(indicator).toHaveClass("bg-green-500")
+    expect(indicator).toHaveAttribute("aria-label", "online")
+  })
+
+  it("renders all status variants", () => {
+    const { rerender } = render(<Avatar status="online" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar-status-indicator")).toHaveClass("bg-green-500")
+
+    rerender(<Avatar status="away" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar-status-indicator")).toHaveClass("bg-yellow-500")
+
+    rerender(<Avatar status="busy" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar-status-indicator")).toHaveClass("bg-red-500")
+
+    rerender(<Avatar status="offline" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar-status-indicator")).toHaveClass("bg-gray-400")
+  })
+
+  it("does not render status indicator when status is not provided", () => {
+    render(<Avatar data-testid="avatar" />)
+    expect(screen.queryByTestId("avatar-status-indicator")).not.toBeInTheDocument()
+  })
+
+  it("applies custom className", () => {
+    render(<Avatar className="custom-class" data-testid="avatar" />)
+    expect(screen.getByTestId("avatar")).toHaveClass("custom-class")
+  })
+
+  it("forwards ref to the root div", () => {
+    const ref = React.createRef<HTMLDivElement>()
+    render(<Avatar ref={ref} />)
+    expect(ref.current).not.toBeNull()
+    expect(ref.current?.tagName).toBe("DIV")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Avatar data-testid="avatar" />)
+    expect(screen.getByTestId("avatar")).toHaveAttribute("data-slot", "avatar")
+  })
+})

soroscan-frontend/__tests__/ui-breadcrumb.test.tsx

@@ -0,0 +1,81 @@
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import { Breadcrumb } from "@/components/ui/breadcrumb"
+
+const defaultItems = [
+  { label: "Home", href: "/" },
+  { label: "Dashboard", href: "/dashboard" },
+  { label: "Events" },
+]
+
+describe("Breadcrumb Component", () => {
+  it("renders all items", () => {
+    render(<Breadcrumb items={defaultItems} data-testid="breadcrumb" />)
+    expect(screen.getByText("Home")).toBeInTheDocument()
+    expect(screen.getByText("Dashboard")).toBeInTheDocument()
+    expect(screen.getByText("Events")).toBeInTheDocument()
+  })
+
+  it("renders links for non-last items with href", () => {
+    render(<Breadcrumb items={defaultItems} />)
+    const homeLink = screen.getByText("Home").closest("a")
+    expect(homeLink).toHaveAttribute("href", "/")
+    const dashLink = screen.getByText("Dashboard").closest("a")
+    expect(dashLink).toHaveAttribute("href", "/dashboard")
+  })
+
+  it("renders last item as plain text with aria-current", () => {
+    render(<Breadcrumb items={defaultItems} />)
+    const lastItem = screen.getByText("Events")
+    expect(lastItem).toHaveAttribute("aria-current", "page")
+    expect(lastItem).toHaveClass("font-medium")
+  })
+
+  it("renders chevron separators by default", () => {
+    const { container } = render(<Breadcrumb items={defaultItems} />)
+    const chevrons = container.querySelectorAll("svg.lucide-chevron-right")
+    expect(chevrons).toHaveLength(2)
+  })
+
+  it("renders slash separators when specified", () => {
+    const { container } = render(<Breadcrumb items={defaultItems} separator="slash" />)
+    const slashes = container.querySelectorAll("svg.lucide-slash")
+    expect(slashes).toHaveLength(2)
+  })
+
+  it("has correct aria-label", () => {
+    render(<Breadcrumb items={defaultItems} />)
+    expect(screen.getByLabelText("Breadcrumb")).toBeInTheDocument()
+  })
+
+  it("collapses items when maxItems is set", () => {
+    const manyItems = [
+      { label: "Home", href: "/" },
+      { label: "Section", href: "/section" },
+      { label: "Category", href: "/category" },
+      { label: "Subcategory", href: "/subcategory" },
+      { label: "Item" },
+    ]
+    render(<Breadcrumb items={manyItems} maxItems={3} />)
+    expect(screen.getByText("Home")).toBeInTheDocument()
+    expect(screen.getByText("...")).toBeInTheDocument()
+    expect(screen.getByText("Item")).toBeInTheDocument()
+  })
+
+  it("applies custom className", () => {
+    render(<Breadcrumb items={defaultItems} className="custom-class" />)
+    expect(screen.getByLabelText("Breadcrumb")).toHaveClass("custom-class")
+  })
+
+  it("forwards ref", () => {
+    const ref = React.createRef<HTMLElement>()
+    render(<Breadcrumb items={defaultItems} ref={ref} />)
+    expect(ref.current).not.toBeNull()
+    expect(ref.current?.tagName).toBe("NAV")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Breadcrumb items={defaultItems} data-testid="breadcrumb" />)
+    expect(screen.getByTestId("breadcrumb")).toHaveAttribute("data-slot", "breadcrumb")
+  })
+})

soroscan-frontend/__tests__/ui-progress.test.tsx

@@ -0,0 +1,104 @@
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import { Progress } from "@/components/ui/progress"
+
+describe("Progress Component", () => {
+  it("renders with role progressbar", () => {
+    render(<Progress value={50} data-testid="progress" />)
+    const el = screen.getByTestId("progress")
+    expect(el).toHaveAttribute("role", "progressbar")
+  })
+
+  it("sets aria-valuenow correctly", () => {
+    render(<Progress value={50} data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveAttribute("aria-valuenow", "50")
+  })
+
+  it("clamps value to min of 0", () => {
+    render(<Progress value={-10} data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveAttribute("aria-valuenow", "0")
+  })
+
+  it("clamps value to max", () => {
+    render(<Progress value={150} max={100} data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveAttribute("aria-valuenow", "100")
+  })
+
+  it("renders with custom max value", () => {
+    render(<Progress value={3} max={10} data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveAttribute("aria-valuemax", "10")
+    expect(screen.getByTestId("progress")).toHaveAttribute("aria-valuenow", "3")
+  })
+
+  it("sets data-value attribute with percentage", () => {
+    render(<Progress value={25} data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveAttribute("data-value", "25")
+  })
+
+  it("renders size variants", () => {
+    const { rerender } = render(<Progress value={50} size="sm" data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveClass("h-1.5")
+
+    rerender(<Progress value={50} size="lg" data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveClass("h-4")
+  })
+
+  it("renders variant colors on inner bar", () => {
+    const { container } = render(<Progress value={50} variant="success" data-testid="progress" />)
+    const bar = container.querySelector('[class*="bg-green-500"]')
+    expect(bar).toBeInTheDocument()
+  })
+
+  it("renders terminal variant", () => {
+    const { container } = render(<Progress value={50} variant="terminal" data-testid="progress" />)
+    const bar = container.querySelector('[class*="bg-terminal-green"]')
+    expect(bar).toBeInTheDocument()
+  })
+
+  it("shows outside label when showLabel is true", () => {
+    render(<Progress value={75} showLabel data-testid="progress" />)
+    expect(screen.getByText("75%")).toBeInTheDocument()
+  })
+
+  it("uses custom label formatter", () => {
+    render(
+      <Progress
+        value={3}
+        max={10}
+        showLabel
+        labelFormatter={(v, m) => `${v}/${m} done`}
+        data-testid="progress"
+      />
+    )
+    expect(screen.getByText("3/10 done")).toBeInTheDocument()
+  })
+
+  it("does not show label by default", () => {
+    render(<Progress value={50} data-testid="progress" />)
+    expect(screen.queryByText("50%")).not.toBeInTheDocument()
+  })
+
+  it("applies custom className", () => {
+    render(<Progress value={50} className="custom-class" data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveClass("custom-class")
+  })
+
+  it("forwards ref", () => {
+    const ref = React.createRef<HTMLDivElement>()
+    render(<Progress value={50} ref={ref} />)
+    expect(ref.current).not.toBeNull()
+    expect(ref.current?.getAttribute("role")).toBe("progressbar")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Progress value={50} data-testid="progress" />)
+    expect(screen.getByTestId("progress")).toHaveAttribute("data-slot", "progress")
+  })
+
+  it("applies correct width percentage to inner bar", () => {
+    const { container } = render(<Progress value={42} data-testid="progress" />)
+    const track = screen.getByTestId("progress")
+    const bar = track.firstChild as HTMLElement
+    expect(bar).toHaveStyle({ width: "42%" })
+  })
+})

soroscan-frontend/__tests__/ui-toggle.test.tsx

@@ -0,0 +1,112 @@
+import React from "react"
+import { render, screen, fireEvent } from "@testing-library/react"
+import { Toggle } from "@/components/ui/toggle"
+
+describe("Toggle Component", () => {
+  it("renders as a switch role", () => {
+    render(<Toggle data-testid="toggle" />)
+    const toggle = screen.getByTestId("toggle")
+    expect(toggle).toHaveAttribute("role", "switch")
+    expect(toggle).toHaveAttribute("aria-checked", "false")
+  })
+
+  it("toggles on click", () => {
+    render(<Toggle data-testid="toggle" />)
+    const toggle = screen.getByTestId("toggle")
+    fireEvent.click(toggle)
+    expect(toggle).toHaveAttribute("aria-checked", "true")
+    fireEvent.click(toggle)
+    expect(toggle).toHaveAttribute("aria-checked", "false")
+  })
+
+  it("toggles on Space key", () => {
+    render(<Toggle data-testid="toggle" />)
+    const toggle = screen.getByTestId("toggle")
+    fireEvent.keyDown(toggle, { key: " " })
+    expect(toggle).toHaveAttribute("aria-checked", "true")
+  })
+
+  it("toggles on Enter key", () => {
+    render(<Toggle data-testid="toggle" />)
+    const toggle = screen.getByTestId("toggle")
+    fireEvent.keyDown(toggle, { key: "Enter" })
+    expect(toggle).toHaveAttribute("aria-checked", "true")
+  })
+
+  it("calls onCheckedChange when toggled", () => {
+    const onChange = jest.fn()
+    render(<Toggle onCheckedChange={onChange} data-testid="toggle" />)
+    fireEvent.click(screen.getByTestId("toggle"))
+    expect(onChange).toHaveBeenCalledWith(true)
+    fireEvent.click(screen.getByTestId("toggle"))
+    expect(onChange).toHaveBeenCalledWith(false)
+  })
+
+  it("respects controlled checked prop", () => {
+    const { rerender } = render(<Toggle checked={true} data-testid="toggle" />)
+    expect(screen.getByTestId("toggle")).toHaveAttribute("aria-checked", "true")
+
+    rerender(<Toggle checked={false} data-testid="toggle" />)
+    expect(screen.getByTestId("toggle")).toHaveAttribute("aria-checked", "false")
+  })
+
+  it("does not toggle when disabled", () => {
+    render(<Toggle disabled data-testid="toggle" />)
+    const toggle = screen.getByTestId("toggle")
+    fireEvent.click(toggle)
+    expect(toggle).toHaveAttribute("aria-checked", "false")
+    expect(toggle).toBeDisabled()
+  })
+
+  it("renders with label", () => {
+    render(<Toggle label="Enable notifications" />)
+    expect(screen.getByText("Enable notifications")).toBeInTheDocument()
+  })
+
+  it("renders label as sr-only when hideLabel is true", () => {
+    render(<Toggle label="Enable notifications" hideLabel data-testid="toggle" />)
+    const label = screen.getByText("Enable notifications")
+    expect(label).toHaveClass("sr-only")
+    expect(screen.getByTestId("toggle")).toHaveAttribute("aria-label", "Enable notifications")
+  })
+
+  it("renders size variants", () => {
+    const { rerender } = render(<Toggle size="sm" data-testid="toggle" />)
+    expect(screen.getByTestId("toggle")).toHaveClass("h-5", "w-9")
+
+    rerender(<Toggle size="lg" data-testid="toggle" />)
+    expect(screen.getByTestId("toggle")).toHaveClass("h-7", "w-14")
+  })
+
+  it("shows checked state styling", () => {
+    render(<Toggle checked={true} data-testid="toggle" />)
+    expect(screen.getByTestId("toggle")).toHaveClass("bg-primary")
+  })
+
+  it("shows unchecked state styling", () => {
+    render(<Toggle checked={false} data-testid="toggle" />)
+    expect(screen.getByTestId("toggle")).toHaveClass("bg-input")
+  })
+
+  it("applies custom className", () => {
+    render(<Toggle className="custom-class" data-testid="toggle" />)
+    expect(screen.getByTestId("toggle")).toHaveClass("custom-class")
+  })
+
+  it("forwards ref", () => {
+    const ref = React.createRef<HTMLButtonElement>()
+    render(<Toggle ref={ref} />)
+    expect(ref.current).not.toBeNull()
+    expect(ref.current?.tagName).toBe("BUTTON")
+  })
+
+  it("has data-slot and data-state attributes", () => {
+    render(<Toggle data-testid="toggle" />)
+    const toggle = screen.getByTestId("toggle")
+    expect(toggle).toHaveAttribute("data-slot", "toggle")
+    expect(toggle).toHaveAttribute("data-state", "unchecked")
+
+    fireEvent.click(toggle)
+    expect(toggle).toHaveAttribute("data-state", "checked")
+  })
+})