@handled-ai/design-system 0.17.2 → 0.18.1

package/src/components/__tests__/insights-primitives.test.tsx

@@ -0,0 +1,117 @@
+import React from "react"
+import { describe, expect, it, vi } from "vitest"
+import { render, screen, fireEvent } from "@testing-library/react"
+
+import { DaysOpenCell, getDaysOpenIntent } from "../days-open-cell"
+import { DetailDrawer } from "../detail-drawer"
+import { InsightsFilterBar } from "../insights-filter-bar"
+import { LinkedEntityCell } from "../linked-entity-cell"
+import { KpiStrip } from "../metric-card"
+import { Pill, StatusPill } from "../pill"
+import { QuickSegment } from "../quick-segment"
+
+describe("Insights primitives", () => {
+  it("renders compact InsightsFilterBar without changing default API", () => {
+    const { container } = render(
+      <InsightsFilterBar
+        variant="compact"
+        filters={[{ id: "status", label: "Status", options: ["All", "Open"], defaultValue: "All" }]}
+        values={{ status: "Open" }}
+        onChange={() => {}}
+        onClearAll={() => {}}
+      />
+    )
+
+    const bar = container.querySelector('[data-slot="insights-filter-bar"]')!
+    expect(bar.className).toContain("p-2")
+    expect(bar.className).toContain("gap-2")
+    expect(screen.getByRole("button", { name: /Status: Open/i }).className).toContain("h-7")
+  })
+
+  it("renders KpiStrip items and changes", () => {
+    const { container } = render(
+      <KpiStrip
+        items={[
+          { label: "New", value: 42, unit: "leads", change: { value: "8%", direction: "up" } },
+          { label: "Aging", value: 12, subtitle: "over SLA", change: { value: "3%", direction: "down", isGood: true } },
+        ]}
+      />
+    )
+
+    expect(container.querySelectorAll('[data-slot="kpi-strip-item"]')).toHaveLength(2)
+    expect(screen.getByText("New")).not.toBeNull()
+    expect(screen.getByText("42")).not.toBeNull()
+    expect(screen.getByText("8%")).not.toBeNull()
+  })
+
+  it("QuickSegment exposes selected state and invokes onSelect", () => {
+    const onSelect = vi.fn()
+    render(<QuickSegment label="At risk" value="risk" count={5} selected onSelect={onSelect} />)
+
+    const button = screen.getByRole("button", { name: /At risk/i })
+    expect(button.getAttribute("aria-pressed")).toBe("true")
+    expect(screen.getByText("5")).not.toBeNull()
+    fireEvent.click(button)
+    expect(onSelect).toHaveBeenCalledWith("risk")
+  })
+
+  it("LinkedEntityCell renders entity links and metadata", () => {
+    const onNavigate = vi.fn()
+    render(
+      <LinkedEntityCell
+        name="Acme Health"
+        href="/accounts/acme"
+        subtitle="Account"
+        meta="Tier 1"
+        onNavigate={onNavigate}
+      />
+    )
+
+    const link = screen.getByRole("link", { name: "Acme Health" })
+    expect(link.getAttribute("href")).toBe("/accounts/acme")
+    expect(screen.getByText(/Tier 1/)).not.toBeNull()
+    fireEvent.click(link)
+    expect(onNavigate).toHaveBeenCalled()
+  })
+
+  it("DaysOpenCell maps thresholds to status intents", () => {
+    expect(getDaysOpenIntent(2, 7, 30)).toBe("success")
+    expect(getDaysOpenIntent(10, 7, 30)).toBe("warning")
+    expect(getDaysOpenIntent(45, 7, 30)).toBe("error")
+
+    render(<DaysOpenCell days={45} />)
+    expect(screen.getByTestId("days-open-pill").getAttribute("data-variant")).toBe("error")
+  })
+
+  it("Pill and StatusPill render wrapper variants", () => {
+    const { container } = render(
+      <div>
+        <Pill variant="info">Info</Pill>
+        <StatusPill status="Blocked" intent="error" />
+      </div>
+    )
+
+    expect(container.querySelector('[data-slot="pill"]')?.getAttribute("data-variant")).toBe("info")
+    expect(container.querySelector('[data-slot="status-pill"]')?.getAttribute("data-variant")).toBe("error")
+    expect(screen.getByText("Blocked")).not.toBeNull()
+  })
+
+  it("DetailDrawer renders title, content, and footer when open", () => {
+    render(
+      <DetailDrawer
+        open
+        onOpenChange={() => {}}
+        title="Referral details"
+        description="A drawer for insights"
+        footer={<button type="button">Done</button>}
+      >
+        <div>Drawer body</div>
+      </DetailDrawer>
+    )
+
+    expect(screen.getByText("Referral details")).not.toBeNull()
+    expect(screen.getByText("A drawer for insights")).not.toBeNull()
+    expect(screen.getByText("Drawer body")).not.toBeNull()
+    expect(screen.getByRole("button", { name: "Done" })).not.toBeNull()
+  })
+})

package/src/components/__tests__/performance-metrics-table.test.tsx

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest"
+import React from "react"
+import { render, screen, within } from "@testing-library/react"
+
+import {
+  PerformanceMetricsTable,
+  type PerformanceMetricsTableRow,
+} from "../performance-metrics-table"
+
+const rows: PerformanceMetricsTableRow[] = [
+  {
+    id: "row-1",
+    label: "Acme Health",
+    avatarFallback: "AH",
+    role: "Coordinator",
+    primaryValue: 10,
+    primaryTarget: 20,
+    ratePercent: 71,
+    metricOne: 5,
+    metricTwo: "1.2h",
+    metricThree: 8,
+    metricFour: 3,
+  },
+]
+
+function renderTable(primaryMetricDisplayMode?: "progress" | "value") {
+  return render(
+    <PerformanceMetricsTable
+      rows={rows}
+      primaryMetricDisplayMode={primaryMetricDisplayMode}
+      roleOptions={["All", "Coordinator"]}
+      viewOptions={["By Entity"]}
+    />,
+  )
+}
+
+describe("PerformanceMetricsTable", () => {
+  it("defaults the primary metric display to progress", () => {
+    renderTable()
+
+    const row = screen.getByText("Acme Health").closest("tr")!
+    expect(within(row).getByText("10/20")).not.toBeNull()
+    expect(within(row).getByText("50%")).not.toBeNull()
+  })
+
+  it("renders the primary metric as a plain value in value mode", () => {
+    renderTable("value")
+
+    const row = screen.getByText("Acme Health").closest("tr")!
+    expect(within(row).getByText("10")).not.toBeNull()
+    expect(within(row).queryByText("10/20")).toBeNull()
+    expect(within(row).queryByText("50%")).toBeNull()
+  })
+})

package/src/components/__tests__/user-display.test.tsx

@@ -0,0 +1,75 @@
+import React from "react"
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+
+import { ActorByline } from "../actor-byline"
+import { UserPill } from "../user-pill"
+
+describe("UserPill", () => {
+  it("renders a display name and derived initials from profile", () => {
+    const { container } = render(
+      <UserPill profile={{ first_name: "Sarah", last_name: "Mitchell", email: "sarah@example.com" }} />
+    )
+
+    expect(container.querySelector('[data-slot="user-pill"]')).not.toBeNull()
+    expect(screen.getByText("Sarah Mitchell")).not.toBeNull()
+    expect(screen.getByText("SM")).not.toBeNull()
+  })
+
+  it("does not require profile and can render direct name/email props with subtitle", () => {
+    render(<UserPill name="Marcus Webb" email="marcus@example.com" subtitle="Account executive" variant="compact" />)
+
+    expect(screen.getByText("Marcus Webb")).not.toBeNull()
+    expect(screen.getByText("Account executive")).not.toBeNull()
+    expect(screen.getByText("MW")).not.toBeNull()
+  })
+
+  it("falls back to email local part and initials from direct email prop", () => {
+    render(<UserPill email="fallback@example.com" />)
+
+    expect(screen.getByText("fallback")).not.toBeNull()
+    expect(screen.getByText("FA")).not.toBeNull()
+  })
+})
+
+describe("ActorByline", () => {
+  it("renders plain byline text with actor name, verb, subject, and string timestamp", () => {
+    const { container } = render(
+      <ActorByline
+        actor={{ first_name: "Cory", last_name: "Pitt", email: "cory@example.com" }}
+        verb="closed"
+        subject="this opportunity"
+        timestamp="3 min ago"
+      />
+    )
+
+    expect(container.querySelector('[data-slot="actor-byline"]')).not.toBeNull()
+    expect(container.textContent).toBe("Cory Pitt closed this opportunity · 3 min ago")
+  })
+
+
+  it("renders Date timestamps deterministically", () => {
+    const { container } = render(
+      <ActorByline
+        actor={{ name: "Cory Pitt", email: "cory@withhandled.com" }}
+        verb="closed"
+        subject="this opportunity"
+        timestamp={new Date("2026-05-24T18:30:00.000Z")}
+      />,
+    )
+
+    expect(container.textContent).toBe("Cory Pitt closed this opportunity · 2026-05-24T18:30:00.000Z")
+  })
+
+  it("omits missing pieces and null timestamp cleanly", () => {
+    const { container } = render(<ActorByline actor={{ name: "Handled AI", email: "agent@handled.ai" }} subject="a task" timestamp={null} />)
+
+    expect(container.textContent).toBe("Handled AI a task")
+  })
+
+  it("falls back through shared user-display rules", () => {
+    const { container } = render(<ActorByline actor={{ first_name: null, last_name: null, name: null, email: "fallback@example.com" }} />)
+
+    expect(container.textContent).toBe("fallback")
+  })
+})

package/src/components/actor-byline.tsx

@@ -0,0 +1 @@
+export { ActorByline, type ActorBylineProps } from "./user-display"

package/src/components/days-open-cell.tsx

@@ -0,0 +1,50 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "../lib/utils"
+import { StatusPill, type PillStatus } from "./pill"
+
+export interface DaysOpenCellProps extends React.HTMLAttributes<HTMLDivElement> {
+  days: number | null | undefined
+  warningAt?: number
+  criticalAt?: number
+  emptyLabel?: string
+  suffix?: string
+}
+
+function getDaysOpenIntent(days: number, warningAt: number, criticalAt: number): PillStatus {
+  if (days >= criticalAt) return "error"
+  if (days >= warningAt) return "warning"
+  return "success"
+}
+
+export function DaysOpenCell({
+  days,
+  warningAt = 7,
+  criticalAt = 30,
+  emptyLabel = "—",
+  suffix = "d open",
+  className,
+  ...props
+}: DaysOpenCellProps) {
+  if (days === null || days === undefined) {
+    return (
+      <div data-slot="days-open-cell" className={cn("text-sm text-muted-foreground", className)} {...props}>
+        {emptyLabel}
+      </div>
+    )
+  }
+
+  const intent = getDaysOpenIntent(days, warningAt, criticalAt)
+
+  return (
+    <div data-slot="days-open-cell" className={cn("inline-flex items-center", className)} {...props}>
+      <StatusPill data-testid="days-open-pill" status={`${days} ${suffix}`} intent={intent}>
+        {days} {suffix}
+      </StatusPill>
+    </div>
+  )
+}
+
+export { getDaysOpenIntent }

package/src/components/detail-drawer.tsx

@@ -0,0 +1,60 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "../lib/utils"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from "./sheet"
+
+export interface DetailDrawerProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  title: React.ReactNode
+  description?: React.ReactNode
+  children: React.ReactNode
+  footer?: React.ReactNode
+  side?: "right" | "left"
+  className?: string
+  contentClassName?: string
+}
+
+export function DetailDrawer({
+  open,
+  onOpenChange,
+  title,
+  description,
+  children,
+  footer,
+  side = "right",
+  className,
+  contentClassName,
+}: DetailDrawerProps) {
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        data-slot="detail-drawer"
+        side={side}
+        className={cn("w-full gap-0 p-0 sm:max-w-xl", className)}
+      >
+        <SheetHeader data-slot="detail-drawer-header" className="border-b border-border p-5">
+          <SheetTitle>{title}</SheetTitle>
+          {description ? <SheetDescription>{description}</SheetDescription> : null}
+        </SheetHeader>
+        <div data-slot="detail-drawer-content" className={cn("flex-1 overflow-y-auto p-5", contentClassName)}>
+          {children}
+        </div>
+        {footer ? (
+          <SheetFooter data-slot="detail-drawer-footer" className="border-t border-border p-5">
+            {footer}
+          </SheetFooter>
+        ) : null}
+      </SheetContent>
+    </Sheet>
+  )
+}

package/src/components/insights-filter-bar.tsx

@@ -23,6 +23,7 @@ export interface FilterDefinition {
 
 export interface InsightsFilterBarProps {
   filters: FilterDefinition[]
+  variant?: "default" | "compact"
   values: Record<string, string>
   onChange: (filterId: string, value: string) => void
   onClearAll?: () => void
@@ -45,6 +46,7 @@ function InsightsFilterBar({
   onChange,
   onClearAll,
   className,
+  variant = "default",
 }: InsightsFilterBarProps) {
   const showClearAll = onClearAll && hasNonDefaultValue(filters, values)
 
@@ -52,11 +54,12 @@ function InsightsFilterBar({
     <div
       data-slot="insights-filter-bar"
       className={cn(
-        "flex flex-wrap items-center gap-3 rounded-md border border-border bg-card p-4 shadow-sm",
+        "flex flex-wrap items-center rounded-md border border-border bg-card shadow-sm",
+        variant === "compact" ? "gap-2 p-2" : "gap-3 p-4",
         className
       )}
     >
-      <div className="flex items-center gap-2">
+      <div className={cn("flex items-center gap-2", variant === "compact" && "sr-only")}>
         <FilterIcon className="h-4 w-4 text-muted-foreground" />
         <span className="text-sm font-medium text-muted-foreground">
           Filters:
@@ -80,7 +83,10 @@ function InsightsFilterBar({
               <Button
                 variant="outline"
                 size="sm"
-                className="h-8 gap-1.5 text-xs font-normal shadow-none"
+                className={cn(
+                  "gap-1.5 text-xs font-normal shadow-none",
+                  variant === "compact" ? "h-7 px-2" : "h-8"
+                )}
               >
                 {IconComp ? (
                   <IconComp className="h-3.5 w-3.5 text-muted-foreground" />
@@ -118,7 +124,10 @@ function InsightsFilterBar({
           <Button
             variant="ghost"
             size="sm"
-            className="h-8 text-xs text-destructive hover:text-destructive"
+            className={cn(
+              "text-xs text-destructive hover:text-destructive",
+              variant === "compact" ? "h-7 px-2" : "h-8"
+            )}
             onClick={onClearAll}
           >
             Clear All

package/src/components/linked-entity-cell.tsx

@@ -0,0 +1,74 @@
+"use client"
+
+import * as React from "react"
+import { ExternalLink } from "lucide-react"
+
+import { cn } from "../lib/utils"
+
+export interface LinkedEntityCellProps extends React.HTMLAttributes<HTMLDivElement> {
+  name: React.ReactNode
+  href?: string
+  subtitle?: React.ReactNode
+  meta?: React.ReactNode
+  icon?: React.ReactNode
+  external?: boolean
+  onNavigate?: () => void
+}
+
+export function LinkedEntityCell({
+  name,
+  href,
+  subtitle,
+  meta,
+  icon,
+  external = false,
+  onNavigate,
+  className,
+  ...props
+}: LinkedEntityCellProps) {
+  const content = (
+    <>
+      <span className="truncate">{name}</span>
+      {external ? <ExternalLink className="h-3 w-3 shrink-0 opacity-60" aria-hidden="true" /> : null}
+    </>
+  )
+
+  return (
+    <div
+      data-slot="linked-entity-cell"
+      className={cn("flex min-w-0 items-center gap-2", className)}
+      {...props}
+    >
+      {icon ? (
+        <span data-slot="linked-entity-cell-icon" className="shrink-0 text-muted-foreground">
+          {icon}
+        </span>
+      ) : null}
+      <div className="min-w-0 flex-1">
+        {href ? (
+          <a
+            data-slot="linked-entity-cell-link"
+            href={href}
+            target={external ? "_blank" : undefined}
+            rel={external ? "noreferrer" : undefined}
+            onClick={onNavigate}
+            className="inline-flex max-w-full items-center gap-1 truncate font-medium text-foreground underline-offset-4 hover:text-primary hover:underline"
+          >
+            {content}
+          </a>
+        ) : (
+          <span data-slot="linked-entity-cell-name" className="block truncate font-medium text-foreground">
+            {name}
+          </span>
+        )}
+        {subtitle || meta ? (
+          <div data-slot="linked-entity-cell-meta" className="mt-0.5 truncate text-xs text-muted-foreground">
+            {subtitle}
+            {subtitle && meta ? <span className="px-1">·</span> : null}
+            {meta}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/src/components/metric-card.tsx

@@ -24,6 +24,88 @@ export interface MetricCardProps {
   showInfo?: boolean
 }
 
+export interface KpiStripItem {
+  id?: string
+  label: React.ReactNode
+  value: React.ReactNode
+  unit?: React.ReactNode
+  subtitle?: React.ReactNode
+  change?: MetricCardProps["change"]
+}
+
+export interface KpiStripProps extends React.HTMLAttributes<HTMLDivElement> {
+  items: KpiStripItem[]
+  columns?: 2 | 3 | 4
+}
+
+export function KpiStrip({ items, columns = 4, className, ...props }: KpiStripProps) {
+  return (
+    <div
+      data-slot="kpi-strip"
+      className={cn(
+        "grid gap-3 rounded-xl border border-border bg-card p-3 shadow-sm",
+        columns === 2 && "sm:grid-cols-2",
+        columns === 3 && "sm:grid-cols-3",
+        columns === 4 && "sm:grid-cols-2 lg:grid-cols-4",
+        className
+      )}
+      {...props}
+    >
+      {items.map((item, index) => {
+        const isGoodDirection = item.change
+          ? item.change.isGood !== undefined
+            ? item.change.isGood
+            : item.change.direction === "up"
+          : false
+        const ChangeIcon = item.change?.direction === "down" ? ArrowDown : ArrowUp
+
+        return (
+          <div
+            key={item.id ?? index}
+            data-slot="kpi-strip-item"
+            className="min-w-0 rounded-lg bg-muted/40 px-3 py-2"
+          >
+            <div data-slot="kpi-strip-label" className="truncate text-xs font-medium text-muted-foreground">
+              {item.label}
+            </div>
+            <div className="mt-1 flex items-baseline gap-1">
+              <span data-slot="kpi-strip-value" className="truncate text-2xl font-bold tracking-tight text-foreground">
+                {item.value}
+              </span>
+              {item.unit ? (
+                <span data-slot="kpi-strip-unit" className="text-sm font-semibold text-muted-foreground">
+                  {item.unit}
+                </span>
+              ) : null}
+            </div>
+            {item.subtitle || item.change ? (
+              <div className="mt-1 flex items-center gap-2 text-xs">
+                {item.change ? (
+                  <span
+                    data-slot="kpi-strip-change"
+                    className={cn(
+                      "inline-flex items-center gap-0.5 font-semibold",
+                      isGoodDirection ? "text-emerald-600" : "text-red-600"
+                    )}
+                  >
+                    <ChangeIcon className="h-3 w-3 stroke-[3]" />
+                    {item.change.value}
+                  </span>
+                ) : null}
+                {item.subtitle ? (
+                  <span data-slot="kpi-strip-subtitle" className="truncate text-muted-foreground">
+                    {item.subtitle}
+                  </span>
+                ) : null}
+              </div>
+            ) : null}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
 export function MetricCard({
   title,
   value,