@handled-ai/design-system 0.16.1 → 0.17.0

package/src/components/score-why-chips.tsx

@@ -0,0 +1,358 @@
+"use client"
+
+import * as React from "react"
+import { Info } from "lucide-react"
+import { ScoreBreakdown, type ScoreFactor } from "./score-breakdown"
+import { cn } from "../lib/utils"
+import type {
+  QueueItem,
+  SignalScoreData,
+  SignalScoreExplanationBucket,
+  SignalScoreExplanationSignal,
+  SignalScoreUrgencyLabel,
+} from "../prototype/prototype-config"
+
+export function getSignalScoreUrgencyLabel(
+  score: number,
+  providedLabel?: SignalScoreUrgencyLabel,
+): SignalScoreUrgencyLabel {
+  if (providedLabel) return providedLabel
+  if (score >= 80) return "Urgent"
+  if (score >= 60) return "High"
+  if (score >= 35) return "Medium"
+  return "Low"
+}
+
+function getUrgencyChipClass(label: SignalScoreUrgencyLabel) {
+  switch (label) {
+    case "Urgent":
+      return "border-red-200 bg-red-50 text-red-700 hover:bg-red-100 dark:border-red-900/50 dark:bg-red-950/30 dark:text-red-300"
+    case "High":
+      return "border-orange-200 bg-orange-50 text-orange-700 hover:bg-orange-100 dark:border-orange-900/50 dark:bg-orange-950/30 dark:text-orange-300"
+    case "Medium":
+      return "border-amber-200 bg-amber-50 text-amber-700 hover:bg-amber-100 dark:border-amber-900/50 dark:bg-amber-950/30 dark:text-amber-300"
+    case "Low":
+      return "border-emerald-200 bg-emerald-50 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-900/50 dark:bg-emerald-950/30 dark:text-emerald-300"
+  }
+}
+
+function classificationForScore(score?: number): string | undefined {
+  if (score == null) return undefined
+  if (score >= 80) return "Urgent"
+  if (score >= 60) return "High"
+  if (score >= 35) return "Medium"
+  return "Low"
+}
+
+function scoreRangeForUrgency(label: SignalScoreUrgencyLabel): string {
+  switch (label) {
+    case "Urgent":
+      return "80-100"
+    case "High":
+      return "60-79"
+    case "Medium":
+      return "35-59"
+    case "Low":
+      return "0-34"
+  }
+}
+
+function makeDomId(...parts: Array<string | undefined>): string {
+  return parts
+    .filter((part): part is string => Boolean(part))
+    .join("-")
+    .replace(/[^A-Za-z0-9_-]+/g, "-")
+}
+
+function scoreFactorToPriorityBucket(factor: ScoreFactor): SignalScoreExplanationBucket {
+  return {
+    key: factor.key,
+    label: factor.label,
+    kind: "factor",
+    score: factor.score ?? undefined,
+    classification: factor.risk ?? classificationForScore(factor.score ?? undefined),
+    rationale: factor.why,
+    factorKeys: [factor.key],
+  }
+}
+
+function bucketHasSignalRows(bucket: SignalScoreExplanationBucket): boolean {
+  return (
+    (bucket.signals?.length ?? 0) > 0 ||
+    (bucket.signalIds?.length ?? 0) > 0 ||
+    Boolean(bucket.primarySignalId)
+  )
+}
+
+function getSignalScoreBuckets(signalData: SignalScoreData): SignalScoreExplanationBucket[] {
+  return (signalData.explanationBuckets ?? []).filter(
+    (bucket) => bucket.kind !== "factor" && bucketHasSignalRows(bucket),
+  )
+}
+
+function getBucketSignals(bucket: SignalScoreExplanationBucket): SignalScoreExplanationSignal[] {
+  if (bucket.signals && bucket.signals.length > 0) return bucket.signals
+
+  const signalIds = bucket.signalIds && bucket.signalIds.length > 0 ? bucket.signalIds : bucket.primarySignalId ? [bucket.primarySignalId] : []
+  const uniqueSignalIds = Array.from(new Set(signalIds))
+
+  return uniqueSignalIds.map((signalId) => ({
+    id: signalId,
+    label: `${bucket.label} signal`,
+  }))
+}
+
+function getPriorityBuckets(signalData: SignalScoreData): SignalScoreExplanationBucket[] {
+  if (signalData.explanationBuckets !== undefined) return signalData.explanationBuckets
+  // Legacy fallback for consumers that still provide score factors but have not
+  // migrated to explanation buckets. WHY chips intentionally do not use this.
+  return signalData.factors.map(scoreFactorToPriorityBucket)
+}
+
+function isSameExplanation(a?: string, b?: string): boolean {
+  return Boolean(a && b && a.trim() === b.trim())
+}
+
+export interface SignalPriorityChipProps {
+  score: number
+  urgencyLabel?: SignalScoreUrgencyLabel
+  isOpen?: boolean
+  controlsId?: string
+  onClick?: () => void
+  className?: string
+}
+
+export function SignalPriorityChip({
+  score,
+  urgencyLabel: providedLabel,
+  isOpen,
+  controlsId,
+  onClick,
+  className,
+}: SignalPriorityChipProps) {
+  const urgencyLabel = getSignalScoreUrgencyLabel(score, providedLabel)
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-expanded={isOpen}
+      aria-controls={controlsId}
+      className={cn(
+        "inline-flex items-center gap-1 rounded-md border px-2.5 py-1 text-xs font-semibold transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        getUrgencyChipClass(urgencyLabel),
+        className,
+      )}
+    >
+      {urgencyLabel} Priority
+      <Info className="h-3 w-3" />
+    </button>
+  )
+}
+
+export interface SignalPriorityPanelProps {
+  signalData: SignalScoreData
+  className?: string
+  id?: string
+}
+
+export function SignalPriorityPanel({ signalData, className, id }: SignalPriorityPanelProps) {
+  const urgencyLabel = getSignalScoreUrgencyLabel(signalData.score, signalData.urgencyLabel)
+  const buckets = React.useMemo(() => getPriorityBuckets(signalData), [signalData])
+  const topBucketRationale = buckets.find((bucket) => bucket.rationale)?.rationale
+  const primaryUrgencyExplanation = signalData.urgencyExplanation ?? signalData.whyNow ?? topBucketRationale
+  const whyNowSection = isSameExplanation(signalData.whyNow, primaryUrgencyExplanation) ? undefined : signalData.whyNow
+  const topFactorSection =
+    isSameExplanation(topBucketRationale, primaryUrgencyExplanation) || isSameExplanation(topBucketRationale, whyNowSection)
+      ? undefined
+      : topBucketRationale
+  const scoreRange = scoreRangeForUrgency(urgencyLabel)
+
+  return (
+    <div id={id} className={cn("rounded-lg border border-border bg-muted/20 p-3 text-xs", className)} role="region" aria-label="Priority explanation">
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div>
+          <p className="font-semibold text-foreground">Why this is {urgencyLabel.toLowerCase()} priority</p>
+          {primaryUrgencyExplanation ? <p className="mt-1 leading-relaxed text-muted-foreground">{primaryUrgencyExplanation}</p> : null}
+        </div>
+        <div className="flex shrink-0 flex-wrap gap-1.5 text-[11px] text-muted-foreground">
+          <span className="rounded-full bg-background px-2 py-0.5">Score {signalData.score}/100</span>
+          <span className="rounded-full bg-background px-2 py-0.5">{urgencyLabel} range: {scoreRange}</span>
+        </div>
+      </div>
+
+      {(whyNowSection || topFactorSection) && (
+        <div className="mt-3 grid gap-2 text-xs text-muted-foreground sm:grid-cols-2">
+          {whyNowSection ? (
+            <div className="rounded-md bg-background/80 p-2">
+              <p className="font-medium text-foreground">Why now</p>
+              <p className="mt-0.5 leading-relaxed">{whyNowSection}</p>
+            </div>
+          ) : null}
+          {topFactorSection ? (
+            <div className="rounded-md bg-background/80 p-2">
+              <p className="font-medium text-foreground">Top factor</p>
+              <p className="mt-0.5 leading-relaxed">{topFactorSection}</p>
+            </div>
+          ) : null}
+        </div>
+      )}
+
+      {signalData.factors.length > 0 ? (
+        <ScoreBreakdown
+          className="mt-3"
+          factors={signalData.factors}
+          onFactorFeedback={signalData.onFactorFeedback}
+          initialFeedback={signalData.initialFactorFeedback}
+        />
+      ) : null}
+    </div>
+  )
+}
+
+export interface ScoreWhyChipsProps {
+  item: QueueItem
+  signalData: SignalScoreData
+  onOpenSignalBucket?: (args: { item: QueueItem; bucketKey: string; signalId: string }) => void
+  className?: string
+}
+
+interface SignalRowProps {
+  item: QueueItem
+  bucketKey: string
+  signal: SignalScoreExplanationSignal
+  onOpenSignalBucket?: ScoreWhyChipsProps["onOpenSignalBucket"]
+}
+
+function SignalRow({ item, bucketKey, signal, onOpenSignalBucket }: SignalRowProps) {
+  const rowContent = (
+    <>
+      <div className="flex items-start justify-between gap-2">
+        <p className="font-medium text-foreground">{signal.label}</p>
+        {signal.time ? <span className="shrink-0 text-[11px] text-muted-foreground/70">{signal.time}</span> : null}
+      </div>
+      {signal.description ? <p className="mt-1 leading-relaxed text-muted-foreground">{signal.description}</p> : null}
+      {(signal.source || signal.metric) && (
+        <div className="mt-1.5 flex flex-wrap gap-1.5 text-[11px] text-muted-foreground/80">
+          {signal.source ? <span className="rounded-full bg-muted px-2 py-0.5">{signal.source}</span> : null}
+          {signal.metric ? <span className="rounded-full bg-muted px-2 py-0.5">{signal.metric}</span> : null}
+        </div>
+      )}
+    </>
+  )
+
+  if (signal.id && onOpenSignalBucket) {
+    return (
+      <button
+        type="button"
+        className="w-full rounded-md bg-background/80 p-2 text-left text-xs transition-colors hover:bg-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+        onClick={() => onOpenSignalBucket({ item, bucketKey, signalId: signal.id! })}
+      >
+        {rowContent}
+      </button>
+    )
+  }
+
+  return <div className="rounded-md bg-background/80 p-2 text-xs">{rowContent}</div>
+}
+
+export function ScoreWhyChips({
+  item,
+  signalData,
+  onOpenSignalBucket,
+  className,
+}: ScoreWhyChipsProps) {
+  const [selectedBucketKey, setSelectedBucketKey] = React.useState<string | null>(null)
+
+  React.useEffect(() => {
+    setSelectedBucketKey(null)
+  }, [item.id])
+
+  const reactId = React.useId()
+  const idPrefix = makeDomId("score-why", reactId, item.id)
+  const buckets = React.useMemo(() => getSignalScoreBuckets(signalData), [signalData])
+  const selectedBucket = buckets.find((bucket) => bucket.key === selectedBucketKey) ?? null
+  const selectedBucketSignals = selectedBucket ? getBucketSignals(selectedBucket) : []
+  const selectedPanelId = selectedBucket ? `${idPrefix}-panel-${makeDomId(selectedBucket.key)}` : undefined
+
+  if (buckets.length === 0) return null
+
+  return (
+    <div className={cn("mt-4", className)}>
+      <div className="mb-2 flex items-center gap-2">
+        <span className="text-[10px] font-bold uppercase tracking-wider text-muted-foreground">Why</span>
+      </div>
+      <div className="flex flex-wrap gap-1.5">
+        {buckets.map((bucket) => {
+          const isSelected = selectedBucketKey === bucket.key
+          const panelId = `${idPrefix}-panel-${makeDomId(bucket.key)}`
+          return (
+            <button
+              key={bucket.key}
+              type="button"
+              onClick={() => setSelectedBucketKey((prev) => (prev === bucket.key ? null : bucket.key))}
+              aria-expanded={isSelected}
+              aria-controls={panelId}
+              className={cn(
+                "inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 text-[11px] font-semibold transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+                isSelected
+                  ? "border-foreground/30 bg-foreground text-background"
+                  : "border-border bg-background text-muted-foreground hover:bg-muted/60 hover:text-foreground",
+              )}
+            >
+              {bucket.label}
+              {bucket.signalCount && bucket.signalCount > 1 ? (
+                <span className={cn("rounded-full px-1.5 py-0 text-[10px]", isSelected ? "bg-background/20" : "bg-muted")}>×{bucket.signalCount}</span>
+              ) : null}
+            </button>
+          )
+        })}
+      </div>
+
+      {selectedBucket && (
+        <div
+          id={selectedPanelId}
+          className="mt-3 rounded-lg border border-border bg-muted/20 p-3"
+          role="region"
+          aria-label={`${selectedBucket.label} details`}
+        >
+          <div className="flex items-start justify-between gap-3">
+            <div>
+              <p className="text-sm font-semibold text-foreground">{selectedBucket.label}</p>
+              <div className="mt-1 flex flex-wrap gap-1.5 text-[11px] text-muted-foreground">
+                <span className="rounded-full bg-background px-2 py-0.5">
+                  {selectedBucket.signalCount ?? selectedBucketSignals.length} signals
+                </span>
+              </div>
+            </div>
+          </div>
+
+          {selectedBucketSignals.length > 0 ? (
+            <ul className="mt-3 space-y-2" aria-label="Matching signals">
+              {selectedBucketSignals.map((signal, index) => (
+                <li key={signal.id ?? `${selectedBucket.key}-signal-${index}`}>
+                  <SignalRow
+                    item={item}
+                    bucketKey={selectedBucket.key}
+                    signal={signal}
+                    onOpenSignalBucket={onOpenSignalBucket}
+                  />
+                </li>
+              ))}
+            </ul>
+          ) : selectedBucket.evidence && selectedBucket.evidence.length > 0 ? (
+            <ul className="mt-3 space-y-1.5" aria-label="Matching signals">
+              {selectedBucket.evidence.map((evidence, index) => (
+                <li key={`${selectedBucket.key}-evidence-${index}`} className="flex gap-2 text-xs text-muted-foreground">
+                  <span className="mt-1.5 h-1 w-1 shrink-0 rounded-full bg-primary" />
+                  <span className="leading-relaxed">{evidence}</span>
+                </li>
+              ))}
+            </ul>
+          ) : null}
+
+        </div>
+      )}
+    </div>
+  )
+}

package/src/index.ts

@@ -23,6 +23,7 @@ export { CollapsibleSection, type CollapsibleSectionProps } from "./components/c
 export * from "./components/compliance-badge"
 export * from "./components/contact-chip"
 export * from "./components/contact-list"
+export * from "./components/contextual-quick-action-launcher"
 export * from "./components/dashboard-cards"
 export * from "./components/data-table"
 export * from "./components/data-table-condition-filter"
@@ -66,6 +67,7 @@ export * from "./components/rich-text-toolbar"
 export * from "./components/score-analysis-modal"
 export * from "./components/score-breakdown"
 export * from "./components/score-feedback"
+export * from "./components/score-why-chips"
 export * from "./components/score-ring"
 export * from "./components/scroll-area"
 export * from "./components/select"