@handled-ai/design-system 0.17.1 → 0.18.1

package/dist/signal-priority-popover-DQ_VuHac.d.ts

@@ -0,0 +1,390 @@
+import * as React from 'react';
+import { FeedbackChipTree, FeedbackSubmitData } from './components/feedback-primitives.js';
+import { SidebarNavSection } from './components/quick-action-sidebar-nav.js';
+import { ScoreFactor } from './components/score-breakdown.js';
+import { SuggestedContact, SuggestedAction } from './components/suggested-actions.js';
+import { SourceDef } from './components/detail-view.js';
+import { InboxFilterCategory } from './components/inbox-toolbar.js';
+import { DataTableFilterCategory } from './components/data-table-filter.js';
+import { DataRow } from './components/data-table.js';
+import { MetricCardProps } from './components/metric-card.js';
+import { PipelineStage, PipelineStageMetrics, PipelineStageTiming } from './charts/pipeline-overview.js';
+import { TimelineEvent } from './components/timeline-activity.js';
+import { ApprovalState } from './components/signal-feedback-inline.js';
+import { LucideIcon } from 'lucide-react';
+
+interface PrototypeBrandConfig {
+    name: string;
+    logo?: string;
+    assistantName?: string;
+}
+interface QueueItem {
+    id: string;
+    title: string;
+    details: string;
+    statusColor: string;
+    time: string;
+    company: string;
+    tag1: string;
+}
+type SignalScoreUrgencyLabel = "Low" | "Medium" | "High" | "Urgent";
+interface SignalScoreExplanationSignal {
+    id?: string;
+    label: string;
+    description?: string;
+    source?: string;
+    time?: string;
+    metric?: string;
+    /** Signal type name (e.g., "treasury_liquidation"). Used for combined signal component identification. */
+    signalTypeName?: string;
+    /** Primary display value (e.g., "-$1,724,310.11"). */
+    primaryValue?: string;
+    /** Qualifier text (e.g., "100% of balance"). */
+    qualifier?: string;
+    /** Counterparty / destination (e.g., "-> JPMorgan Chase --6042"). */
+    counterparty?: string;
+    /** Component breakdown for combined signals. */
+    components?: Array<{
+        type: string;
+        count: number;
+    }>;
+}
+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[];
+    /** Lucide icon name for the bucket type (e.g., "trending-down"). */
+    icon?: string;
+    /** Tonal styling hint for the bucket. */
+    tone?: "alert" | "warn" | "info";
+}
+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;
+    }>;
+    /** Priority factors for the popover breakdown. */
+    priorityFactors?: PriorityFactor[];
+    /** Negative feedback chip tree for the priority popover. */
+    priorityFeedbackChips?: FeedbackChipTree[];
+    /** Callback when user submits priority-level feedback. */
+    onPriorityFeedback?: (data: FeedbackSubmitData) => void;
+    /** Callback when user submits bucket-level feedback. */
+    onBucketFeedback?: (bucketKey: string, data: FeedbackSubmitData) => void;
+    /** AI-generated signal brief text. When present, rendered in a dedicated section. */
+    signalBrief?: string;
+    /** Compact label for time-remaining chip (e.g., "13 days left"). */
+    timeChipLabel?: string;
+    /** Expanded detail for time chip popover (e.g., "Day 2 of 14 · Event detected on May 1"). */
+    timeChipDetail?: string;
+}
+interface InboxSortOption {
+    id: string;
+    label: string;
+}
+/** Controls the visual prominence of the signal brief section. */
+type BriefStyleVariant = "default" | "prominent";
+interface InboxDetailSections {
+    signalBrief?: boolean;
+    suggestedActions?: boolean;
+    timeline?: boolean;
+}
+interface InboxViewConfig {
+    items: QueueItem[];
+    filterCategories?: InboxFilterCategory[];
+    detailSections?: InboxDetailSections;
+    accountContacts?: SuggestedContact[];
+    buildAccountContacts?: (item: QueueItem) => SuggestedContact[];
+    emailSignature?: string | React.ReactNode;
+    buildSuggestedActions?: (item: QueueItem) => SuggestedAction[];
+    buildSourceItems?: (item: QueueItem) => SourceDef[];
+    getSignalScore?: (company: string, item?: QueueItem) => SignalScoreData;
+    getTimelineEvents?: (item: QueueItem) => TimelineEvent[];
+    iconMap?: Record<string, string>;
+    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;
+    accountDetailsLabel?: string;
+    onSignalApprove?: (item: QueueItem) => void | Promise<boolean>;
+    getSignalApprovalState?: (item: QueueItem) => ApprovalState | undefined;
+    signalLabels?: {
+        approveButton?: string;
+        dismissButton?: string;
+        approvedStatus?: string;
+        dismissedStatus?: string;
+        opportunityCreated?: string;
+        confirmPrompt?: string;
+        creatingStatus?: string;
+    };
+    /** When true, the approve/create-opportunity button is hidden but the dismiss button remains. */
+    hideApproveButton?: boolean;
+    /**
+     * Override the copy used in the detail panel "Signal brief" section.
+     * Useful when the prototype represents an internal ops inbox rather than
+     * an outbound sales signal — the default heading and intro line are
+     * written for the latter.
+     */
+    signalBriefCopy?: {
+        /** Section heading (default: "Signal brief"). Pass an empty string to hide. */
+        heading?: string;
+        /**
+         * Introductory line rendered above the per-item `whyNow` text.
+         * Receives the `QueueItem` so the caller can interpolate the company
+         * name or other fields. Pass `null` (or a function returning `null`)
+         * to suppress the intro line entirely.
+         */
+        intro?: string | ((item: QueueItem) => string | null) | null;
+    };
+    /** Controls the visual prominence of the signal brief section.
+     *  - "default": current styling (muted intro, text-foreground/90 brief)
+     *  - "prominent": standard foreground color, text-base size for the brief
+     */
+    briefStyleVariant?: BriefStyleVariant;
+    /** Render extra content at the end of the detail view, below the suggested actions section. */
+    renderDetailExtra?: (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). */
+    renderAfterScore?: (item: QueueItem) => React.ReactNode;
+    /** Formatted string for "Last activity X ago" in the collapsed timeline header. If omitted, falls back to the first event's time. */
+    lastActivityTime?: string;
+    /** 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;
+    /** Sort options for the inbox. When provided, a sort dropdown is rendered in the split view toolbar. */
+    sortOptions?: InboxSortOption[];
+    /** Currently active sort option id. */
+    activeSortId?: string;
+    /** Callback when the user changes the sort option. */
+    onSortChange?: (sortId: string) => void;
+}
+interface InsightsCustomTab {
+    id: string;
+    label: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    content: React.ReactNode;
+}
+interface InsightsViewConfig {
+    customTabs?: InsightsCustomTab[];
+    tabs?: {
+        overview?: boolean;
+        analytics?: boolean;
+    };
+    coaching?: {
+        enabled?: boolean;
+        message?: string;
+    };
+    metrics?: MetricCardProps[];
+    expandedMetrics?: MetricCardProps[];
+    dashboardCards?: {
+        topTasks?: boolean;
+        upcomingMeetings?: boolean;
+        recentlyCompleted?: boolean;
+        checkIns?: boolean;
+    };
+    analytics?: {
+        pipeline?: {
+            stages: PipelineStage[];
+            stageMetrics: Record<string, PipelineStageMetrics>;
+            stageTimings: (PipelineStageTiming | null)[];
+            filterBreakdowns?: Record<string, Record<string, Record<string, number>>>;
+        };
+        volumeChart?: {
+            data: Record<string, unknown>[];
+            dataKeys: Array<{
+                key: string;
+                color: string;
+            }>;
+            filterOptions?: Array<{
+                label: string;
+                value: string;
+            }>;
+        };
+        donutChart?: {
+            data: Array<{
+                name: string;
+                value: number;
+                color: string;
+            }>;
+            centerLabel?: number;
+        };
+        trendChart?: {
+            data: Record<string, unknown>[];
+            series: Array<{
+                dataKey: string;
+                color: string;
+            }>;
+            xAxisKey?: string;
+            height?: number;
+            toggleOptions?: string[];
+        };
+        barChart?: {
+            data: Record<string, unknown>[];
+            bars: Array<{
+                dataKey: string;
+                color: string;
+                name: string;
+                icon?: LucideIcon;
+            }>;
+        };
+        barList?: {
+            data: Array<{
+                name: string;
+                value: number;
+            }>;
+            valueFormatter?: (v: number) => string;
+        };
+    };
+}
+interface AccountFilterTab {
+    label: string;
+    count?: number;
+    variant?: "default" | "attention" | "ghost";
+}
+interface AccountsViewConfig {
+    filterTabs?: AccountFilterTab[];
+    rows?: DataRow[];
+    filterCategories?: DataTableFilterCategory[];
+    quickViews?: string[];
+    moreQuickViews?: string[];
+    quickViewFilters?: Record<string, (row: DataRow) => boolean>;
+    iconMap?: {
+        salesforce?: string;
+    };
+    entityUrlBuilder?: (row: DataRow) => string;
+    onScoreFactorFeedback?: (account: string, scoreType: string, factorKey: string, type: "up" | "down" | null, detail?: string) => void;
+    onScoreApproveFeedback?: (account: string, scoreType: string, reasons: string[], detail: string) => void;
+    onScoreDismissFeedback?: (account: string, scoreType: string, reasons: string[], detail: string) => void;
+}
+interface WorkQueueViewConfig {
+    [key: string]: unknown;
+}
+interface AdminTab {
+    id: string;
+    label: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    content: React.ReactNode;
+}
+interface AdminViewConfig {
+    /** View title displayed in the header. Defaults to "Admin". */
+    title?: string;
+    /** Icon displayed next to the title. */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    tabs: AdminTab[];
+    /** Which tab is active initially. Defaults to first tab's id. */
+    defaultTab?: string;
+}
+interface EntityPanelSection {
+    type: "details" | "contacts" | "recentActivity" | "connectedApps" | "systemActivity";
+    props?: Record<string, unknown>;
+}
+interface EntityPanelConfig {
+    sections?: EntityPanelSection[];
+    icons?: Record<string, string>;
+}
+interface PrototypeConfig {
+    brand?: PrototypeBrandConfig;
+    sidebar: SidebarNavSection[];
+    views: {
+        inbox?: InboxViewConfig;
+        insights?: InsightsViewConfig;
+        accounts?: AccountsViewConfig;
+        workQueue?: WorkQueueViewConfig;
+        admin?: AdminViewConfig;
+    };
+    defaultView: string;
+    entityPanel?: EntityPanelConfig;
+    /** Sidebar item IDs that trigger view navigation. Defaults to keys of `views`. */
+    navigableViews?: string[];
+}
+
+/**
+ * A single contributing factor in the priority popover.
+ */
+interface PriorityFactor {
+    key: string;
+    label: string;
+    /** Lucide icon name (e.g. "radar", "wallet", "link-2", "message-square"). */
+    icon: string;
+    /** Drives icon background tint. */
+    tone: "alert" | "warn" | "info";
+    /** Explicit semantic label - NOT inferred from score+weight. */
+    direction: "raises" | "lowers" | "neutral";
+    /** 0-100 */
+    score: number;
+    /** Evidence text (e.g. "$3.4M moved in 8h - current treasury balance $0.00"). */
+    rationale: string;
+}
+interface SignalPriorityPopoverProps {
+    score: number;
+    urgencyLabel?: SignalScoreUrgencyLabel;
+    /** Synthesis sentence displayed in the popover head. */
+    urgencyExplanation?: string;
+    factors: PriorityFactor[];
+    /** e.g. "Updated 4m ago - model v3.2" */
+    metaText?: string;
+    /** Negative feedback issue tree. */
+    feedbackChips?: FeedbackChipTree[];
+    onFeedbackSubmit?: (data: FeedbackSubmitData) => void;
+    className?: string;
+}
+declare function SignalPriorityPopover({ score, urgencyLabel: providedLabel, urgencyExplanation, factors, metaText, feedbackChips, onFeedbackSubmit, className, }: SignalPriorityPopoverProps): React.JSX.Element;
+
+export { type AccountFilterTab as A, type BriefStyleVariant as B, type EntityPanelConfig as E, type InboxDetailSections as I, type PriorityFactor as P, type QueueItem as Q, SignalPriorityPopover as S, type WorkQueueViewConfig as W, type AccountsViewConfig as a, type AdminTab as b, type AdminViewConfig as c, type EntityPanelSection as d, type InboxSortOption as e, type InboxViewConfig as f, type InsightsCustomTab as g, type InsightsViewConfig as h, type PrototypeBrandConfig as i, type PrototypeConfig as j, type SignalPriorityPopoverProps as k, type SignalScoreData as l, type SignalScoreExplanationBucket as m, type SignalScoreExplanationSignal as n, type SignalScoreUrgencyLabel as o };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handled-ai/design-system",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "description": "Handled UI component library (shadcn-style, New York)",
   "type": "module",
   "packageManager": "pnpm@9.12.0",

package/src/charts/__tests__/insights-charts.test.tsx

@@ -0,0 +1,62 @@
+import React from "react"
+import { describe, expect, it, vi } from "vitest"
+import { render, screen, fireEvent } from "@testing-library/react"
+
+import { EmptyChartState } from "../empty-chart-state"
+import { PipelineOverview, type PipelineStage, type PipelineStageMetrics } from "../pipeline-overview"
+
+vi.mock("@nivo/sankey", () => ({
+  ResponsiveSankey: ({ data }: { data: { nodes: unknown[]; links: unknown[] } }) => (
+    <div data-testid="mock-sankey">{data.nodes.length}:{data.links.length}</div>
+  ),
+}))
+
+const stages: PipelineStage[] = [
+  { id: "received", label: "Received", count: 100, trend: "+5%", nextConversion: "80%" },
+  { id: "contacted", label: "Contacted", count: 80, trend: "+3%", nextConversion: null },
+]
+
+const metrics: Record<string, PipelineStageMetrics> = {
+  received: { medianTime: "1d", avgTime: "2d", dropOffs: [] },
+  contacted: { medianTime: "2d", avgTime: "3d", dropOffs: [] },
+}
+
+function renderPipeline(variant?: "sankey" | "compact", onFilterChange = vi.fn()) {
+  return render(
+    <PipelineOverview
+      variant={variant}
+      stages={stages}
+      stageMetrics={metrics}
+      stageTimings={[{ median: "1d", avg: "2d" }, null]}
+      filterOptions={["Facility", "Source"]}
+      onFilterChange={onFilterChange}
+    />
+  )
+}
+
+describe("Insights chart primitives", () => {
+  it("EmptyChartState renders defaults and action", () => {
+    const { container } = render(<EmptyChartState action={<button type="button">Reset</button>} />)
+
+    expect(container.querySelector('[data-slot="empty-chart-state"]')).not.toBeNull()
+    expect(screen.getByText("No chart data")).not.toBeNull()
+    expect(screen.getByRole("button", { name: "Reset" })).not.toBeNull()
+  })
+
+  it("PipelineOverview default variant preserves Sankey rendering and callbacks", () => {
+    const onFilterChange = vi.fn()
+    renderPipeline(undefined, onFilterChange)
+
+    expect(screen.getByTestId("mock-sankey")).not.toBeNull()
+    fireEvent.click(screen.getByRole("button", { name: "Source" }))
+    expect(onFilterChange).toHaveBeenCalledWith("Source")
+  })
+
+  it("PipelineOverview compact variant renders compact bars instead of Sankey", () => {
+    const { container } = renderPipeline("compact")
+
+    expect(screen.queryByTestId("mock-sankey")).toBeNull()
+    expect(container.querySelector('[data-slot="pipeline-overview-compact"]')).not.toBeNull()
+    expect(container.querySelectorAll('[data-slot="pipeline-overview-compact-bar"]')).toHaveLength(2)
+  })
+})

package/src/charts/empty-chart-state.tsx

@@ -0,0 +1,44 @@
+import * as React from "react"
+import { BarChart3 } from "lucide-react"
+
+import { cn } from "../lib/utils"
+
+export interface EmptyChartStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  title?: React.ReactNode
+  description?: React.ReactNode
+  icon?: React.ReactNode
+  action?: React.ReactNode
+}
+
+export function EmptyChartState({
+  title = "No chart data",
+  description = "Try adjusting filters or selecting a different time range.",
+  icon,
+  action,
+  className,
+  ...props
+}: EmptyChartStateProps) {
+  return (
+    <div
+      data-slot="empty-chart-state"
+      className={cn(
+        "flex min-h-[240px] flex-col items-center justify-center rounded-xl border border-dashed border-border bg-muted/30 p-8 text-center",
+        className
+      )}
+      {...props}
+    >
+      <div data-slot="empty-chart-state-icon" className="mb-3 text-muted-foreground [&>svg]:h-10 [&>svg]:w-10">
+        {icon ?? <BarChart3 aria-hidden="true" />}
+      </div>
+      <div data-slot="empty-chart-state-title" className="text-sm font-semibold text-foreground">
+        {title}
+      </div>
+      {description ? (
+        <div data-slot="empty-chart-state-description" className="mt-1 max-w-sm text-sm text-muted-foreground">
+          {description}
+        </div>
+      ) : null}
+      {action ? <div data-slot="empty-chart-state-action" className="mt-4">{action}</div> : null}
+    </div>
+  )
+}

package/src/charts/index.ts

@@ -11,3 +11,4 @@ export * from "./volume-analysis-chart"
 export * from "./top-line-metrics"
 export * from "./pipeline-overview"
 export * from "./sankey-chart"
+export * from "./empty-chart-state"

package/src/charts/pipeline-overview.tsx

@@ -125,6 +125,7 @@ function StageHoverCard({
 
 export interface PipelineOverviewProps {
   title?: string
+  variant?: "sankey" | "compact"
   stages: PipelineStage[]
   stageMetrics: Record<string, PipelineStageMetrics>
   stageTimings: (PipelineStageTiming | null)[]
@@ -162,6 +163,7 @@ export interface PipelineOverviewProps {
 
 export function PipelineOverview({
   title = "Pipeline Overview",
+  variant = "sankey",
   stages,
   stageMetrics,
   stageTimings,
@@ -424,8 +426,42 @@ export function PipelineOverview({
         })}
       </div>
 
-      {/* Sankey Chart */}
+      {variant === "compact" ? (
+        <div data-slot="pipeline-overview-compact" className="mt-4 space-y-2">
+          {stages.map((stage, index) => {
+            const maxCount = Math.max(...stages.map((item) => item.count), 1)
+            const width = `${Math.max((stage.count / maxCount) * 100, 4)}%`
+
+            return (
+              <div key={stage.id} className="rounded-lg border border-border bg-background p-3">
+                <div className="mb-2 flex items-center justify-between gap-3">
+                  <div className="min-w-0">
+                    <div className="truncate text-sm font-medium text-foreground">{stage.label}</div>
+                    <div className="text-xs text-muted-foreground">{stage.trend}</div>
+                  </div>
+                  <div className="text-right text-lg font-bold text-foreground">
+                    {stage.count.toLocaleString()}
+                  </div>
+                </div>
+                <div className="h-2 overflow-hidden rounded-full bg-muted">
+                  <div
+                    data-slot="pipeline-overview-compact-bar"
+                    className="h-full rounded-full bg-emerald-600"
+                    style={{ width }}
+                  />
+                </div>
+                {index < stages.length - 1 && stage.nextConversion ? (
+                  <div className="mt-2 text-xs text-muted-foreground">
+                    {stage.nextConversion} to {stages[index + 1]?.label}
+                  </div>
+                ) : null}
+              </div>
+            )
+          })}
+        </div>
+      ) : (
       <div
+        data-slot="pipeline-overview-sankey"
         className="relative mt-4 w-full"
         style={{ height: 400, minWidth: 0 }}
       >
@@ -471,6 +507,7 @@ export function PipelineOverview({
           }}
         />
       </div>
+      )}
     </div>
   )
 }