@handled-ai/design-system 0.16.2 → 0.17.0

package/src/components/contextual-quick-action-launcher.tsx

@@ -0,0 +1,231 @@
+"use client"
+
+import * as React from "react"
+import { ArrowRight, ChevronDown, Zap } from "lucide-react"
+
+import { cn } from "../lib/utils"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "./dropdown-menu"
+
+export interface ContextualQuickActionItem {
+  id: string
+  label: string
+  description?: string
+  icon?: React.ReactNode
+  disabled?: boolean
+  disabledReason?: string
+}
+
+export interface ContextualQuickActionContextLabelProps {
+  contextLabel: string
+  contextSecondary?: string
+  className?: string
+}
+
+export interface ContextualQuickActionLauncherProps {
+  contextLabel: string
+  contextSecondary?: string
+  items: ContextualQuickActionItem[]
+  onSelect: (item: ContextualQuickActionItem) => void
+  onBrowseAll?: () => void
+  showHint?: boolean
+  align?: "start" | "end"
+  className?: string
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+}
+
+function ContextualQuickActionContextLabel({
+  contextLabel,
+  contextSecondary,
+  className,
+}: ContextualQuickActionContextLabelProps) {
+  return (
+    <div
+      data-slot="contextual-quick-action-context-label"
+      className={cn(
+        "-mx-1 -mt-1 mb-1 flex items-center gap-1.5 border-b px-3 py-2 text-[11px] text-muted-foreground",
+        className
+      )}
+    >
+      <Zap className="h-3 w-3 shrink-0" strokeWidth={2.25} aria-hidden="true" />
+      <span>Acting on</span>
+      <strong className="max-w-[180px] truncate font-semibold text-foreground">
+        {contextLabel}
+      </strong>
+      {contextSecondary ? (
+        <span className="min-w-0 truncate text-muted-foreground">
+          · {contextSecondary}
+        </span>
+      ) : null}
+    </div>
+  )
+}
+
+function DefaultActionIcon() {
+  return <Zap className="h-3.5 w-3.5" aria-hidden="true" />
+}
+
+function ContextualQuickActionLauncher({
+  contextLabel,
+  contextSecondary,
+  items,
+  onSelect,
+  onBrowseAll,
+  showHint = false,
+  align = "start",
+  className,
+  open,
+  defaultOpen,
+  onOpenChange,
+}: ContextualQuickActionLauncherProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen ?? false)
+  const isControlled = open !== undefined
+  const isOpen = isControlled ? open : uncontrolledOpen
+
+  const handleOpenChange = React.useCallback(
+    (nextOpen: boolean) => {
+      if (!isControlled) {
+        setUncontrolledOpen(nextOpen)
+      }
+      onOpenChange?.(nextOpen)
+    },
+    [isControlled, onOpenChange]
+  )
+
+  const closeMenu = React.useCallback(() => {
+    handleOpenChange(false)
+  }, [handleOpenChange])
+
+  const handleSelect = React.useCallback(
+    (item: ContextualQuickActionItem, event?: Event) => {
+      if (item.disabled) {
+        event?.preventDefault()
+        return
+      }
+
+      onSelect(item)
+      closeMenu()
+    },
+    [closeMenu, onSelect]
+  )
+
+  const handleBrowseAll = React.useCallback(() => {
+    onBrowseAll?.()
+    closeMenu()
+  }, [closeMenu, onBrowseAll])
+
+  return (
+    <div
+      data-slot="contextual-quick-action-launcher"
+      className={cn("inline-flex items-center gap-2", className)}
+    >
+      <DropdownMenu open={isOpen} onOpenChange={handleOpenChange}>
+        <DropdownMenuTrigger asChild>
+          <button
+            type="button"
+            data-slot="contextual-quick-action-trigger"
+            data-state={isOpen ? "open" : "closed"}
+            className={cn(
+              "inline-flex h-8 items-center gap-2 rounded-lg border border-border bg-background py-1.5 pr-2.5 pl-2 text-xs font-medium text-foreground shadow-sm transition-colors hover:border-muted-foreground/40 hover:bg-muted/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+              "data-[state=open]:border-foreground data-[state=open]:bg-foreground data-[state=open]:text-background data-[state=open]:hover:bg-foreground"
+            )}
+          >
+            <span
+              className={cn(
+                "inline-flex h-[18px] w-[18px] items-center justify-center rounded bg-foreground/[0.04]",
+                isOpen && "bg-background/15"
+              )}
+            >
+              <Zap className="h-3 w-3" strokeWidth={2} aria-hidden="true" />
+            </span>
+            <span className="tracking-[-0.005em]">Quick action</span>
+            <ChevronDown className="h-3 w-3 opacity-60" strokeWidth={2} aria-hidden="true" />
+          </button>
+        </DropdownMenuTrigger>
+
+        <DropdownMenuContent
+          align={align}
+          side="bottom"
+          sideOffset={6}
+          className="pointer-events-auto w-[308px] rounded-[10px] p-1.5 text-[12.5px] shadow-[0_12px_28px_rgba(0,0,0,0.12),0_2px_6px_rgba(0,0,0,0.04)]"
+        >
+          <ContextualQuickActionContextLabel
+            contextLabel={contextLabel}
+            contextSecondary={contextSecondary}
+          />
+
+          {items.map((item) => (
+            <DropdownMenuItem
+              key={item.id}
+              disabled={item.disabled}
+              onSelect={(event) => handleSelect(item, event)}
+              className={cn(
+                "flex cursor-pointer items-center gap-2.5 rounded-md px-2 py-2 text-left outline-none focus:bg-accent data-[disabled]:cursor-not-allowed data-[disabled]:opacity-100",
+                item.disabled && "text-muted-foreground"
+              )}
+            >
+              <span
+                data-slot="contextual-quick-action-item-icon"
+                className={cn(
+                  "flex h-[26px] w-[26px] shrink-0 items-center justify-center rounded-md bg-secondary text-foreground",
+                  item.disabled && "opacity-60"
+                )}
+              >
+                {item.icon ?? <DefaultActionIcon />}
+              </span>
+              <span className="min-w-0 flex-1">
+                <span className="block truncate text-[12.5px] font-medium leading-tight text-current">
+                  {item.label}
+                </span>
+                {item.description ? (
+                  <span className="mt-0.5 block truncate text-[11px] leading-tight text-muted-foreground">
+                    {item.description}
+                  </span>
+                ) : null}
+              </span>
+              {item.disabled && item.disabledReason ? (
+                <span className="ml-auto shrink-0 text-[10.5px] italic text-muted-foreground/80">
+                  {item.disabledReason}
+                </span>
+              ) : null}
+            </DropdownMenuItem>
+          ))}
+
+          <DropdownMenuSeparator className="-mx-1.5 my-1" />
+          <div className="flex items-center justify-between px-2 py-1.5 text-[11px] text-muted-foreground">
+            <button
+              type="button"
+              className="inline-flex items-center gap-1 font-medium text-foreground hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+              onClick={handleBrowseAll}
+            >
+              Browse all actions
+              <ArrowRight className="h-3 w-3" strokeWidth={2} aria-hidden="true" />
+            </button>
+            <span className="inline-flex items-center rounded border border-border px-1 py-0.5 text-[10px] font-medium leading-none text-muted-foreground">
+              ⌘K
+            </span>
+          </div>
+        </DropdownMenuContent>
+      </DropdownMenu>
+
+      {showHint ? (
+        <span className="text-[11px] text-muted-foreground">
+          Or press{" "}
+          <span className="inline-flex items-center rounded border border-border bg-muted/40 px-1 py-0.5 text-[10px] font-medium leading-none">
+            ⌘K
+          </span>{" "}
+          for all actions
+        </span>
+      ) : null}
+    </div>
+  )
+}
+
+export { ContextualQuickActionContextLabel, ContextualQuickActionLauncher }

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"