@handled-ai/design-system 0.16.2 → 0.17.1

package/src/prototype/__tests__/detail-view-score-why.test.tsx

@@ -0,0 +1,326 @@
+import "@testing-library/jest-dom/vitest";
+import { describe, it, expect, vi } from "vitest";
+import React from "react";
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { DetailView, type DetailViewProps } from "../prototype-inbox-view";
+import type { QueueItem, SignalScoreData } from "../prototype-config";
+
+const baseItem: QueueItem = {
+  id: "case-1",
+  title: "Test Signal",
+  details: "Some details",
+  statusColor: "green",
+  time: "2h ago",
+  company: "Acme Inc",
+  tag1: "renewal",
+};
+
+function makeSignalScore(overrides: Partial<SignalScoreData> = {}): SignalScoreData {
+  return {
+    score: 82,
+    factors: [
+      { key: "trigger", label: "Trigger strength", score: 70, why: "Strong signal" },
+      { key: "fit", label: "Company fit", score: 55, why: "Good fit" },
+    ],
+    whyNow: "Strong signals detected.",
+    evidence: ["Evidence line 1"],
+    confidence: 80,
+    ...overrides,
+  };
+}
+
+function baseProps(overrides: Partial<DetailViewProps> = {}): DetailViewProps {
+  return {
+    item: baseItem,
+    sections: { signalBrief: true, suggestedActions: false, timeline: false },
+    getSignalScore: () => makeSignalScore(),
+    buildSuggestedActions: () => [],
+    buildSourceItems: () => [],
+    accountContacts: [],
+    emailSignature: "",
+    iconMap: {},
+    ...overrides,
+  };
+}
+
+describe("DetailView corrected compact score WHY UX", () => {
+  it("renders priority in metadata row without the old signal score card", () => {
+    render(<DetailView {...baseProps()} />);
+
+    expect(screen.getByRole("button", { name: /urgent priority/i })).toBeInTheDocument();
+    expect(screen.queryByText("Signal score")).toBeNull();
+    expect(screen.queryByText("82")).toBeNull();
+    expect(screen.queryByText("/100")).toBeNull();
+    expect(screen.queryByText("Select a chip for details")).toBeNull();
+    expect(screen.queryByText("How's this score?")).toBeNull();
+  });
+
+  it("uses provided priority label before fallback thresholds", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () => makeSignalScore({ score: 92, urgencyLabel: "Medium" }),
+        })}
+      />,
+    );
+
+    expect(screen.getByRole("button", { name: /medium priority/i })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /urgent priority/i })).toBeNull();
+  });
+
+  it("opens priority explanation from metadata independently of score feedback", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () =>
+            makeSignalScore({ urgencyExplanation: "Customer activity spiked today." }),
+        })}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /urgent priority/i }));
+
+    expect(screen.getByText("Customer activity spiked today.")).toBeInTheDocument();
+    expect(screen.getByText("Score 82/100")).toBeInTheDocument();
+    expect(screen.getByText("Urgent range: 80-100")).toBeInTheDocument();
+    expect(screen.getByText("Why now")).toBeInTheDocument();
+    const priorityPanel = screen.getByRole("region", { name: /priority explanation/i });
+    expect(within(priorityPanel).getByText("Strong signals detected.")).toBeInTheDocument();
+    expect(screen.getByText("Top factor")).toBeInTheDocument();
+    expect(screen.getAllByText("Strong signal").length).toBeGreaterThan(0);
+    expect(screen.getByText("Trigger strength")).toBeInTheDocument();
+    expect(screen.getByText("Company fit")).toBeInTheDocument();
+    expect(screen.queryByText("How's this score?")).toBeNull();
+  });
+
+  it("keeps signal WHY chips collapsed by default and excludes factor-only buckets", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () =>
+            makeSignalScore({
+              explanationBuckets: [
+                { key: "signal-a", label: "Treasury activity", kind: "signal", primarySignalId: "sig-1", signals: [{ id: "sig-1", label: "Treasury signal" }] },
+                { key: "factor-b", label: "Relationship depth", kind: "factor", rationale: "Relationship rationale", factorKeys: ["fit"] },
+              ],
+            }),
+        })}
+      />,
+    );
+
+    expect(screen.getByText("Treasury activity")).toBeInTheDocument();
+    expect(screen.queryByText("Relationship depth")).toBeNull();
+    expect(screen.queryByRole("region", { name: /treasury activity details/i })).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: /treasury activity/i }));
+    expect(screen.getByRole("region", { name: /treasury activity details/i })).toBeInTheDocument();
+  });
+
+  it("resets selected bucket and priority panel when item id changes", () => {
+    const { rerender } = render(<DetailView {...baseProps()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: /urgent priority/i }));
+    expect(screen.getByRole("region", { name: /priority explanation/i })).toBeInTheDocument();
+
+    rerender(
+      <DetailView
+        {...baseProps({
+          item: { ...baseItem, id: "case-2", title: "Second Signal" },
+        })}
+      />,
+    );
+
+    expect(screen.queryByRole("region", { name: /priority explanation/i })).toBeNull();
+  });
+
+  it("does not render factor-derived WHY chips when no signal buckets are present", () => {
+    render(<DetailView {...baseProps()} />);
+
+    expect(screen.queryByRole("button", { name: /trigger strength/i })).toBeNull();
+    expect(screen.queryByRole("button", { name: /company fit/i })).toBeNull();
+  });
+
+  it("honors an explicit empty explanationBuckets array", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () => makeSignalScore({ explanationBuckets: [] }),
+        })}
+      />,
+    );
+
+    expect(screen.queryByRole("button", { name: /trigger strength/i })).toBeNull();
+    expect(screen.queryByRole("button", { name: /company fit/i })).toBeNull();
+  });
+
+  it("does not render a WHY row when no buckets or legacy factors exist", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () => makeSignalScore({ factors: [], explanationBuckets: [] }),
+        })}
+      />,
+    );
+
+    expect(screen.getByRole("button", { name: /urgent priority/i })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /trigger strength/i })).toBeNull();
+    expect(screen.queryByRole("button", { name: /company fit/i })).toBeNull();
+  });
+
+  it("exposes aria-expanded and aria-controls for priority and bucket triggers", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () =>
+            makeSignalScore({
+              explanationBuckets: [
+                { key: "signal:a/test", label: "Signal A", kind: "signal", signals: [{ id: "sig-a", label: "Signal A event" }] },
+              ],
+            }),
+        })}
+      />,
+    );
+
+    const priorityButton = screen.getByRole("button", { name: /urgent priority/i });
+    expect(priorityButton.getAttribute("aria-expanded")).toBe("false");
+    expect(priorityButton.getAttribute("aria-controls")).toBeTruthy();
+    fireEvent.click(priorityButton);
+    expect(priorityButton.getAttribute("aria-expanded")).toBe("true");
+    expect(document.getElementById(priorityButton.getAttribute("aria-controls")!)).toBeInTheDocument();
+
+    const bucketButton = screen.getByRole("button", { name: /signal a/i });
+    expect(bucketButton.getAttribute("aria-expanded")).toBe("false");
+    expect(bucketButton.getAttribute("aria-controls")).toBeTruthy();
+    fireEvent.click(bucketButton);
+    expect(bucketButton.getAttribute("aria-expanded")).toBe("true");
+    expect(document.getElementById(bucketButton.getAttribute("aria-controls")!)).toBeInTheDocument();
+  });
+
+  it("renders repeated signal groups as one chip with a count and signal-id rows", () => {
+    const onOpenSignalBucket = vi.fn();
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () =>
+            makeSignalScore({
+              explanationBuckets: [
+                { key: "signal-repeat", label: "Treasury activity", kind: "signal", signalCount: 3, signalIds: ["sig-1", "sig-2", "sig-3"] },
+              ],
+            }),
+          onOpenSignalBucket,
+        })}
+      />,
+    );
+
+    expect(screen.getAllByRole("button", { name: /treasury activity/i })).toHaveLength(1);
+    expect(screen.getByText("×3")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: /treasury activity/i }));
+    const matchingSignals = screen.getByRole("list", { name: /matching signals/i });
+    expect(within(matchingSignals).getAllByRole("button", { name: /treasury activity signal/i })).toHaveLength(3);
+    fireEvent.click(within(matchingSignals).getAllByRole("button", { name: /treasury activity signal/i })[1]);
+    expect(onOpenSignalBucket).toHaveBeenCalledWith({
+      item: baseItem,
+      bucketKey: "signal-repeat",
+      signalId: "sig-2",
+    });
+  });
+
+  it("renders designed matching signal rows from bucket signals", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () =>
+            makeSignalScore({
+              explanationBuckets: [
+                {
+                  key: "signals",
+                  label: "Treasury activity",
+                  kind: "signal",
+                  signals: [
+                    {
+                      id: "sig-1",
+                      label: "ACH volume increased",
+                      description: "Payment activity is 40% above baseline.",
+                      source: "Banking data",
+                      time: "Today",
+                      metric: "+40%",
+                    },
+                  ],
+                },
+              ],
+            }),
+        })}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /treasury activity/i }));
+    const matchingSignals = screen.getByRole("list", { name: /matching signals/i });
+    expect(within(matchingSignals).getByText("ACH volume increased")).toBeInTheDocument();
+    expect(within(matchingSignals).getByText("Payment activity is 40% above baseline.")).toBeInTheDocument();
+    expect(within(matchingSignals).getByText("Banking data")).toBeInTheDocument();
+    expect(within(matchingSignals).getByText("+40%")).toBeInTheDocument();
+  });
+
+  it("opens a matching signal row with the selected signal id", () => {
+    const onOpenSignalBucket = vi.fn();
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () =>
+            makeSignalScore({
+              explanationBuckets: [
+                {
+                  key: "with-signals",
+                  label: "With signals",
+                  kind: "signal",
+                  signalCount: 2,
+                  signals: [
+                    { id: "sig-1", label: "Latest signal", description: "Newest signal" },
+                    { id: "sig-2", label: "Older signal", description: "Older signal" },
+                  ],
+                },
+              ],
+            }),
+          onOpenSignalBucket,
+        })}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /with signals/i }));
+    fireEvent.click(screen.getByRole("button", { name: /older signal/i }));
+
+    expect(onOpenSignalBucket).toHaveBeenCalledWith({
+      item: baseItem,
+      bucketKey: "with-signals",
+      signalId: "sig-2",
+    });
+  });
+
+  it("shows factor feedback in the priority panel, not signal WHY panels", () => {
+    const onFactorFeedback = vi.fn();
+    render(
+      <DetailView
+        {...baseProps({
+          getSignalScore: () =>
+            makeSignalScore({
+              onFactorFeedback,
+              initialFactorFeedback: { fit: { type: "down", detail: "Needs review" } },
+              explanationBuckets: [
+                { key: "signal-a", label: "Signal only", kind: "signal", primarySignalId: "sig-1", signals: [{ id: "sig-1", label: "Signal event" }] },
+              ],
+            }),
+        })}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: /signal only/i }));
+    const signalPanel = screen.getByRole("region", { name: /signal only details/i });
+    expect(within(signalPanel).queryByTitle("This factor is accurate")).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: /urgent priority/i }));
+    const priorityPanel = screen.getByRole("region", { name: /priority explanation/i });
+    expect(within(priorityPanel).getAllByTitle("This factor is accurate").length).toBeGreaterThan(0);
+    expect(within(priorityPanel).getByText("Needs review")).toBeInTheDocument();
+  });
+});

package/src/prototype/__tests__/detail-view-title-subtext.test.tsx

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { DetailView, type DetailViewProps } from "../prototype-inbox-view";
+import type { QueueItem, SignalScoreData } from "../prototype-config";
+
+const baseItem: QueueItem = {
+  id: "case-1",
+  title: "QA Placement Churn Risk Signal",
+  details: "Some details",
+  statusColor: "red",
+  time: "2h ago",
+  company: "QA Placement Account",
+  tag1: "Urgent Priority",
+};
+
+function signalScore(): SignalScoreData {
+  return {
+    score: 82,
+    factors: [],
+    whyNow: "Strong signal detected.",
+    evidence: [],
+    confidence: 75,
+  };
+}
+
+function baseProps(overrides: Partial<DetailViewProps> = {}): DetailViewProps {
+  return {
+    item: baseItem,
+    sections: { signalBrief: true, suggestedActions: false, timeline: false },
+    getSignalScore: () => signalScore(),
+    buildSuggestedActions: () => [],
+    buildSourceItems: () => [],
+    accountContacts: [],
+    emailSignature: "",
+    iconMap: {},
+    ...overrides,
+  };
+}
+
+describe("DetailView title slots", () => {
+  it("renders supporting title text below the main title", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          renderTitleSubtext: (item) => (
+            <p data-testid="title-subtext">Full case: {item.title}</p>
+          ),
+        })}
+      />,
+    );
+
+    expect(screen.getByRole("heading", { name: "QA Placement Churn Risk Signal" })).toBeTruthy();
+    expect(screen.getByTestId("title-subtext").textContent).toBe(
+      "Full case: QA Placement Churn Risk Signal",
+    );
+  });
+
+  it("renders title extra content beside the main title", () => {
+    render(
+      <DetailView
+        {...baseProps({
+          renderTitleExtra: () => (
+            <button type="button" data-testid="title-extra">Quick action</button>
+          ),
+        })}
+      />,
+    );
+
+    expect(screen.getByTestId("title-extra").textContent).toBe("Quick action");
+  });
+});

package/src/prototype/prototype-config.ts

@@ -36,16 +36,49 @@ export interface QueueItem {
   tag1: string
 }
 
+export type SignalScoreUrgencyLabel = "Low" | "Medium" | "High" | "Urgent"
+
+export interface SignalScoreExplanationSignal {
+  id?: string
+  label: string
+  description?: string
+  source?: string
+  time?: string
+  metric?: string
+}
+
+export interface SignalScoreExplanationBucket {
+  key: string
+  label: string
+  kind: "signal" | "factor" | "merged"
+  score?: number
+  classification?: string
+  rationale?: string
+  evidence?: string[]
+  signals?: SignalScoreExplanationSignal[]
+  primaryMetricLabel?: string
+  primaryMetricValue?: string
+  signalCount?: number
+  signalIds?: string[]
+  primarySignalId?: string
+  factorKeys?: string[]
+}
+
 export interface SignalScoreData {
   score: number
   factors: ScoreFactor[]
   whyNow: string
   evidence: string[]
   confidence: number
+  urgencyLabel?: SignalScoreUrgencyLabel
+  urgencyExplanation?: string
+  explanationBuckets?: SignalScoreExplanationBucket[]
   onFactorFeedback?: (factorKey: string, type: "up" | "down" | null, detail?: string) => void
+  /** @deprecated The compact score UX no longer renders score-level thumbs by default. */
   onScoreFeedback?: (type: "up" | "down", pills: string[], detail: string) => void
   onApproveFeedback?: (reasons: string[], detail: string) => void
   onDismissFeedback?: (reasons: string[], detail: string, subReason?: string) => void
+  /** @deprecated The compact score UX no longer renders score-level thumbs by default. */
   initialScoreFeedback?: { type: "up" | "down"; pills: string[]; detail: string } | null
   initialFactorFeedback?: Record<string, { type: "up" | "down"; detail: string }>
   /** AI-generated signal brief text. When present, rendered in a dedicated section. */
@@ -89,7 +122,9 @@ export interface InboxViewConfig {
   hideToolbarActions?: boolean
   hideHoverActions?: boolean
   onSuggestedActionFeedback?: (actionId: number | string, feedback: string, actionTitle?: string) => void
+  /** @deprecated The compact score UX no longer renders score-level thumbs by default. */
   onScoreFeedback?: (type: "up" | "down", pills: string[], detail: string) => void
+  onOpenSignalBucket?: (args: { item: QueueItem; bucketKey: string; signalId: string }) => void
   buildEntityChips?: (item: QueueItem) => Array<{ id: string; label: string; avatarLetter: string; onClick?: () => void }>
   quickFilterTabs?: Array<{ id: string; label: string; matchValue?: string; count?: number }>
   hideAccountsButton?: boolean
@@ -131,6 +166,10 @@ export interface InboxViewConfig {
   briefStyleVariant?: BriefStyleVariant
   /** Render extra content at the end of the detail view, below the suggested actions section. */
   renderDetailExtra?: (item: QueueItem) => React.ReactNode
+  /** Render extra content inline with the detail title. */
+  renderTitleExtra?: (item: QueueItem) => React.ReactNode
+  /** Render supporting content below the detail title. */
+  renderTitleSubtext?: (item: QueueItem) => React.ReactNode
   /** Render content between the signal brief text and the signal score bar (e.g. "Signals on Case" chips). */
   renderBeforeScore?: (item: QueueItem) => React.ReactNode
   /** Render content between the signal score section and the activity timeline (e.g. OpportunityPanel). */