tembro 2.0.6 → 2.1.0

package/packages/cli/vendor/src/components/data-table/data-table-toolbar.tsx

@@ -87,7 +87,7 @@ function DataTableToolbar({
             </div>
           )}
 
-          {actions && <div className={cn("flex min-w-0 shrink-0 flex-wrap items-center gap-2 xl:justify-end", actionsClassName)}>{actions}</div>}
+          {actions && <div className={cn("flex w-full min-w-0 flex-wrap items-center gap-2 sm:w-auto xl:shrink-0 xl:justify-end", actionsClassName)}>{actions}</div>}
         </div>
       )}
 
@@ -95,10 +95,12 @@ function DataTableToolbar({
         <div className="flex flex-col gap-3 xl:flex-row xl:items-start xl:justify-between">
           <div className="flex min-w-0 flex-1 flex-col gap-3">
             {hasMainControls && (
-              <div className="flex min-w-0 flex-1 flex-col gap-2 lg:flex-row lg:flex-wrap lg:items-center">
-                {search ? <div className={cn("min-w-[16rem] max-w-xl flex-1", searchClassName)}>{search}</div> : null}
-                {filters ? <div className={cn("flex min-w-0 flex-1 flex-wrap items-center gap-2", filtersClassName)}>{filters}</div> : null}
-                {children}
+              <div className="grid min-w-0 flex-1 gap-2 lg:grid-cols-[minmax(14rem,24rem)_minmax(0,1fr)] lg:items-start">
+                {search ? <div className={cn("min-w-0 max-w-full", searchClassName)}>{search}</div> : null}
+                <div className="flex min-w-0 flex-wrap items-center gap-2">
+                  {filters ? <div className={cn("flex min-w-0 flex-1 flex-wrap items-center gap-2 [&>*]:min-w-0", filtersClassName)}>{filters}</div> : null}
+                  {children}
+                </div>
               </div>
             )}
             {summary ? (
@@ -112,7 +114,7 @@ function DataTableToolbar({
           </div>
 
           {hasSelection && (
-            <div data-slot="data-table-selection-bar" className="flex shrink-0 flex-wrap items-center gap-2 rounded-[var(--radius-md)] border border-[color:var(--aui-control-border-strong,var(--border))] bg-[color:var(--aui-control-surface,var(--background))] px-2.5 py-1.5 text-sm shadow-[var(--aui-control-shadow,none)] backdrop-blur">
+            <div data-slot="data-table-selection-bar" className="flex w-full shrink-0 flex-wrap items-center gap-2 rounded-[var(--radius-md)] border border-[color:var(--aui-control-border-strong,var(--border))] bg-[color:var(--aui-control-surface,var(--background))] px-2.5 py-1.5 text-sm shadow-[var(--aui-control-shadow,none)] backdrop-blur sm:w-auto">
               <span className="text-muted-foreground">{selectedLabel(selectedCount, totalCount)}</span>
               {selectionActions}
             </div>

package/packages/cli/vendor/src/components/display/carousel.tsx

@@ -22,8 +22,15 @@ export type CarouselProps = React.ComponentProps<"div"> & {
   pauseOnHover?: boolean
   stopAutoplayOnInteraction?: boolean
   showPlaybackControl?: boolean
+  showStatus?: boolean
+  showThumbnails?: boolean
   playLabel?: string
   pauseLabel?: string
+  statusLabel?: (index: number, total: number) => string
+  renderThumbnail?: (item: React.ReactNode, index: number, active: boolean) => React.ReactNode
+  renderActiveDetail?: (item: React.ReactNode, index: number) => React.ReactNode
+  aspectRatio?: string
+  mouseDrag?: boolean
   onAutoplayChange?: (playing: boolean) => void
   viewportClassName?: string
   controlsClassName?: string
@@ -31,6 +38,7 @@ export type CarouselProps = React.ComponentProps<"div"> & {
   arrowClassName?: string
   dotClassName?: string
   activeDotClassName?: string
+  thumbnailsClassName?: string
 }
 
 export type CarouselItemProps = React.ComponentProps<"div">
@@ -59,8 +67,15 @@ function Carousel({
   pauseOnHover = true,
   stopAutoplayOnInteraction = true,
   showPlaybackControl = false,
+  showStatus = false,
+  showThumbnails = false,
   playLabel = "Start autoplay",
   pauseLabel = "Pause autoplay",
+  statusLabel,
+  renderThumbnail,
+  renderActiveDetail,
+  aspectRatio,
+  mouseDrag = true,
   onAutoplayChange,
   viewportClassName,
   controlsClassName,
@@ -68,6 +83,7 @@ function Carousel({
   arrowClassName,
   dotClassName,
   activeDotClassName,
+  thumbnailsClassName,
   className,
   children,
   ...props
@@ -75,11 +91,13 @@ function Carousel({
   const items = React.Children.toArray(children)
   const [internalIndex, setInternalIndex] = React.useState(defaultIndex)
   const touchStartXRef = React.useRef<number | null>(null)
+  const pointerStartXRef = React.useRef<number | null>(null)
   const [isHovered, setIsHovered] = React.useState(false)
   const [autoplayStopped, setAutoplayStopped] = React.useState(false)
   const [autoplayEnabled, setAutoplayEnabled] = React.useState(autoplay)
   const controlled = index !== undefined
   const activeIndex = clampIndex(controlled ? index : internalIndex, items.length, loop)
+  const activeItem = items[activeIndex]
 
   React.useEffect(() => {
     setAutoplayEnabled(autoplay)
@@ -116,6 +134,21 @@ function Carousel({
     if (deltaX < 0 && canGoNext) setActiveIndex(activeIndex + 1)
   }
 
+  const handlePointerDown: React.PointerEventHandler<HTMLDivElement> = (event) => {
+    if (!mouseDrag || event.pointerType === "touch") return
+    pointerStartXRef.current = event.clientX
+  }
+
+  const handlePointerUp: React.PointerEventHandler<HTMLDivElement> = (event) => {
+    if (!mouseDrag || pointerStartXRef.current == null || items.length <= 1) return
+    const deltaX = event.clientX - pointerStartXRef.current
+    pointerStartXRef.current = null
+
+    if (Math.abs(deltaX) < swipeThreshold) return
+    if (deltaX > 0 && canGoPrevious) setActiveIndex(activeIndex - 1)
+    if (deltaX < 0 && canGoNext) setActiveIndex(activeIndex + 1)
+  }
+
   React.useEffect(() => {
     if (!autoplayEnabled || items.length <= 1 || autoplayStopped) return
     if (pauseOnHover && isHovered) return
@@ -152,9 +185,19 @@ function Carousel({
           event.preventDefault()
           setActiveIndex(activeIndex + 1)
         }
+        if (event.key === "Home") {
+          event.preventDefault()
+          setActiveIndex(0)
+        }
+        if (event.key === "End") {
+          event.preventDefault()
+          setActiveIndex(items.length - 1)
+        }
       }}
       onTouchStart={handleTouchStart}
       onTouchEnd={handleTouchEnd}
+      onPointerDown={handlePointerDown}
+      onPointerUp={handlePointerUp}
       onMouseEnter={() => setIsHovered(true)}
       onMouseLeave={() => setIsHovered(false)}
       {...props}
@@ -164,7 +207,16 @@ function Carousel({
         variant === "hero" && "min-h-72",
         variant === "minimal" && "rounded-[var(--radius-md)] shadow-none"
       , viewportClassName)}>
-        <div className="transition-transform duration-300 ease-out" aria-live="polite">
+        {showStatus ? (
+          <div className="pointer-events-none absolute right-3 top-3 z-10 rounded-full border border-border/70 bg-background/92 px-2.5 py-1 text-[11px] font-medium text-muted-foreground shadow-sm">
+            {statusLabel?.(activeIndex, items.length) ?? `Slide ${activeIndex + 1} / ${items.length}`}
+          </div>
+        ) : null}
+        <div
+          className="transition-transform duration-300 ease-out"
+          aria-live="polite"
+          style={aspectRatio ? { aspectRatio } : undefined}
+        >
           {items[activeIndex]}
         </div>
         {showArrows && items.length > 1 ? (
@@ -228,9 +280,38 @@ function Carousel({
           ) : null}
         </div>
       )}
+      {showThumbnails && items.length > 1 ? (
+        <div className={cn("grid grid-cols-2 gap-2 sm:grid-cols-4", thumbnailsClassName)}>
+          {items.map((item, itemIndex) => {
+            const active = itemIndex === activeIndex
+
+            return (
+              <button
+                key={itemIndex}
+                type="button"
+                aria-current={active ? "true" : undefined}
+                aria-label={`Open slide ${itemIndex + 1}`}
+                className={cn(
+                  "overflow-hidden rounded-[min(var(--radius-xl),16px)] border bg-card text-left transition hover:border-primary/35 hover:shadow-sm",
+                  active ? "border-primary/35 ring-2 ring-primary/15" : "border-border/70"
+                )}
+                onClick={() => setActiveIndex(itemIndex)}
+              >
+                {renderThumbnail
+                  ? renderThumbnail(item, itemIndex, active)
+                  : <div className="line-clamp-2 min-h-16 p-3 text-xs text-muted-foreground">Slide {itemIndex + 1}</div>}
+              </button>
+            )
+          })}
+        </div>
+      ) : null}
+      {renderActiveDetail ? renderActiveDetail(activeItem, activeIndex) : null}
+      <span className="sr-only" aria-live="polite">
+        {statusLabel?.(activeIndex, items.length) ?? `${ariaLabel}: slide ${activeIndex + 1} of ${items.length}`}
+      </span>
     </div>
-  )
-}
+  )
+}
 
 function CarouselItem({ className, ...props }: CarouselItemProps) {
   return <div data-slot="carousel-item" className={cn("min-h-40 p-5 sm:p-6", className)} {...props} />

package/packages/cli/vendor/src/components/display/code-block.tsx

@@ -10,6 +10,7 @@ export type CodeBlockProps = React.ComponentProps<"div"> & {
   showCopy?: boolean
   wrap?: boolean
   lineNumbers?: boolean
+  highlightLines?: number[] | readonly number[]
   maxHeight?: number | string
 }
 
@@ -20,11 +21,13 @@ function CodeBlock({
   showCopy = true,
   wrap = false,
   lineNumbers = false,
+  highlightLines = [],
   maxHeight,
   className,
   ...props
 }: CodeBlockProps) {
   const lines = React.useMemo(() => code.split("\n"), [code])
+  const highlightedLineSet = React.useMemo(() => new Set(highlightLines), [highlightLines])
 
   return (
     <div
@@ -48,14 +51,31 @@ function CodeBlock({
         {lineNumbers ? (
           <code className="grid">
             {lines.map((line, index) => (
-              <span key={`${index}-${line}`} className="grid grid-cols-[auto_1fr] gap-4">
+              <span
+                key={`${index}-${line}`}
+                data-highlighted={highlightedLineSet.has(index + 1) || undefined}
+                className={cn(
+                  "grid grid-cols-[auto_1fr] gap-4 rounded px-1",
+                  highlightedLineSet.has(index + 1) && "bg-primary/10 text-foreground"
+                )}
+              >
                 <span className="select-none text-right text-xs text-muted-foreground/75">{index + 1}</span>
                 <span>{line || " "}</span>
               </span>
             ))}
           </code>
         ) : (
-          <code>{code}</code>
+          <code>
+            {lines.map((line, index) => (
+              <span
+                key={`${index}-${line}`}
+                data-highlighted={highlightedLineSet.has(index + 1) || undefined}
+                className={cn("block rounded px-1", highlightedLineSet.has(index + 1) && "bg-primary/10 text-foreground")}
+              >
+                {line || " "}
+              </span>
+            ))}
+          </code>
         )}
       </pre>
     </div>

package/packages/cli/vendor/src/components/display/delta-badge.tsx

@@ -1,9 +1,10 @@
 import * as React from "react"
 import { ArrowDownIcon, ArrowUpIcon, MinusIcon } from "lucide-react"
 
+import { Badge, type BadgeProps } from "@/components/ui/badge"
 import { cn } from "@/lib/utils"
 
-export type DeltaBadgeProps = React.ComponentProps<"span"> & {
+export type DeltaBadgeProps = Omit<BadgeProps, "children" | "label" | "tone" | "status" | "leftIcon" | "variant" | "size"> & {
   value: React.ReactNode
   trend?: "up" | "down" | "neutral"
   size?: "sm" | "default"
@@ -19,23 +20,22 @@ function DeltaBadge({
   ...props
 }: DeltaBadgeProps) {
   const TrendIcon = trend === "up" ? ArrowUpIcon : trend === "down" ? ArrowDownIcon : MinusIcon
+  const tone = trend === "up" ? "success" : trend === "down" ? "danger" : "muted"
 
   return (
-    <span
+    <Badge
       data-slot="delta-badge"
+      variant="soft"
+      tone={tone}
+      size={size}
+      leftIcon={icon ? <TrendIcon className={cn("shrink-0", size === "sm" ? "size-2.5" : "size-3")} /> : undefined}
+      label={value}
       className={cn(
-        "inline-flex items-center justify-center font-medium",
-        size === "sm" ? "gap-0.5 rounded px-1 py-0.5 text-[10px]" : "gap-1 rounded-full px-1.5 py-0.5 text-xs",
-        trend === "up" && "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400",
-        trend === "down" && "bg-destructive/10 text-destructive",
-        trend === "neutral" && "bg-muted text-muted-foreground",
+        size === "sm" && "min-h-5 px-1.5 text-[10px]",
         className
       )}
       {...props}
-    >
-      {icon && <TrendIcon className={cn("shrink-0", size === "sm" ? "size-2.5" : "size-3")} />}
-      {value}
-    </span>
+    />
   )
 }
 

package/packages/cli/vendor/src/components/display/kanban.tsx

@@ -3,14 +3,15 @@ import * as React from "react"
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
 import { cn } from "@/lib/utils"
 
-export type KanbanCard = {
-  key: string
-  title: React.ReactNode
-  description?: React.ReactNode
-  meta?: React.ReactNode
-  extra?: React.ReactNode
-  disabled?: boolean
-}
+export type KanbanCard = {
+  key: string
+  title: React.ReactNode
+  description?: React.ReactNode
+  meta?: React.ReactNode
+  extra?: React.ReactNode
+  actions?: React.ReactNode
+  disabled?: boolean
+}
 
 export type KanbanColumn = {
   key: string
@@ -22,24 +23,31 @@ export type KanbanColumn = {
 
 export type KanbanBoardProps = React.ComponentProps<"div"> & {
   columns: KanbanColumn[]
-  renderCard?: (card: KanbanCard, column: KanbanColumn) => React.ReactNode
-  onCardClick?: (card: KanbanCard, column: KanbanColumn) => void
-  columnClassName?: string
-  cardClassName?: string
-}
-
-function KanbanBoard({ columns, renderCard, onCardClick, columnClassName, cardClassName, className, ...props }: KanbanBoardProps) {
-  return (
-    <div data-slot="kanban-board" className={cn("grid auto-cols-[minmax(280px,1fr)] grid-flow-col gap-4 overflow-x-auto pb-2", className)} {...props}>
-      {columns.map((column) => (
+  renderCard?: (card: KanbanCard, column: KanbanColumn) => React.ReactNode
+  onCardClick?: (card: KanbanCard, column: KanbanColumn) => void
+  onCardMove?: (card: KanbanCard, fromColumn: KanbanColumn, toColumn: KanbanColumn) => void
+  emptyColumn?: React.ReactNode | ((column: KanbanColumn) => React.ReactNode)
+  columnClassName?: string
+  cardClassName?: string
+}
+
+function KanbanBoard({ columns, renderCard, onCardClick, onCardMove, emptyColumn = "No cards yet.", columnClassName, cardClassName, className, ...props }: KanbanBoardProps) {
+  const columnByKey = React.useMemo(() => new Map(columns.map((column) => [column.key, column])), [columns])
+
+  return (
+    <div data-slot="kanban-board" className={cn("grid auto-cols-[minmax(280px,1fr)] grid-flow-col gap-4 overflow-x-auto pb-2", className)} {...props}>
+      {columns.map((column) => (
         <KanbanColumnView
           key={column.key}
           column={column}
-          renderCard={renderCard}
-          onCardClick={onCardClick}
-          columnClassName={columnClassName}
-          cardClassName={cardClassName}
-        />
+          renderCard={renderCard}
+          onCardClick={onCardClick}
+          onCardMove={onCardMove}
+          columnByKey={columnByKey}
+          emptyColumn={emptyColumn}
+          columnClassName={columnClassName}
+          cardClassName={cardClassName}
+        />
       ))}
     </div>
   )
@@ -47,46 +55,84 @@ function KanbanBoard({ columns, renderCard, onCardClick, columnClassName, cardCl
 
 function KanbanColumnView({
   column,
-  renderCard,
-  onCardClick,
-  columnClassName,
-  cardClassName,
-}: {
-  column: KanbanColumn
-  renderCard?: (card: KanbanCard, column: KanbanColumn) => React.ReactNode
-  onCardClick?: (card: KanbanCard, column: KanbanColumn) => void
-  columnClassName?: string
-  cardClassName?: string
-}) {
-  return (
-    <section data-slot="kanban-column" className={cn("grid min-h-40 content-start gap-3 rounded-lg border bg-muted/35 p-3", columnClassName)}>
+  renderCard,
+  onCardClick,
+  onCardMove,
+  columnByKey,
+  emptyColumn,
+  columnClassName,
+  cardClassName,
+}: {
+  column: KanbanColumn
+  renderCard?: (card: KanbanCard, column: KanbanColumn) => React.ReactNode
+  onCardClick?: (card: KanbanCard, column: KanbanColumn) => void
+  onCardMove?: (card: KanbanCard, fromColumn: KanbanColumn, toColumn: KanbanColumn) => void
+  columnByKey: Map<string, KanbanColumn>
+  emptyColumn: React.ReactNode | ((column: KanbanColumn) => React.ReactNode)
+  columnClassName?: string
+  cardClassName?: string
+}) {
+  return (
+    <section
+      data-slot="kanban-column"
+      className={cn("grid min-h-40 content-start gap-3 rounded-lg border bg-muted/35 p-3", columnClassName)}
+      onDragOver={(event) => {
+        if (onCardMove) event.preventDefault()
+      }}
+      onDrop={(event) => {
+        const cardKey = event.dataTransfer.getData("application/x-tembro-kanban-card")
+        const fromColumnKey = event.dataTransfer.getData("application/x-tembro-kanban-column")
+        const fromColumn = columnByKey.get(fromColumnKey)
+        const card = fromColumn?.cards.find((item) => item.key === cardKey)
+        if (card && fromColumn && fromColumn.key !== column.key) onCardMove?.(card, fromColumn, column)
+      }}
+    >
       <div className="flex items-start justify-between gap-3">
         <div className="grid gap-0.5">
           <h3 className="text-sm font-semibold text-foreground">{column.title}</h3>
           {column.description && <p className="text-xs text-muted-foreground">{column.description}</p>}
         </div>
         <div className="rounded-full bg-background px-2 py-0.5 text-xs text-muted-foreground">{column.count ?? column.cards.length}</div>
-      </div>
-      <div className="grid gap-2">
-        {column.cards.map((card) => (
-          renderCard?.(card, column) ?? (
-            <Card
-              key={card.key}
-              data-slot="kanban-card"
-              className={cn(
-                "transition-colors hover:bg-muted/40",
-                onCardClick && !card.disabled && "cursor-pointer",
-                card.disabled && "pointer-events-none opacity-55",
-                cardClassName
-              )}
-              onClick={() => onCardClick?.(card, column)}
-            >
-              <CardHeader className="p-3 pb-1">
-                <div className="flex items-start justify-between gap-2">
-                  <CardTitle className="text-sm">{card.title}</CardTitle>
-                  {card.extra}
-                </div>
-              </CardHeader>
+      </div>
+      <div className="grid gap-2">
+        {column.cards.length === 0 ? (
+          <div data-slot="kanban-column-empty" className="rounded-md border border-dashed bg-background/60 px-3 py-6 text-center text-sm text-muted-foreground">
+            {typeof emptyColumn === "function" ? emptyColumn(column) : emptyColumn}
+          </div>
+        ) : column.cards.map((card) => (
+          renderCard?.(card, column) ?? (
+            <Card
+              key={card.key}
+              data-slot="kanban-card"
+              role={onCardClick ? "button" : undefined}
+              tabIndex={onCardClick && !card.disabled ? 0 : undefined}
+              draggable={Boolean(onCardMove && !card.disabled)}
+              className={cn(
+                "transition-colors hover:bg-muted/40",
+                onCardClick && !card.disabled && "cursor-pointer",
+                onCardMove && !card.disabled && "cursor-grab active:cursor-grabbing",
+                card.disabled && "pointer-events-none opacity-55",
+                cardClassName
+              )}
+              onDragStart={(event) => {
+                event.dataTransfer.setData("application/x-tembro-kanban-card", card.key)
+                event.dataTransfer.setData("application/x-tembro-kanban-column", column.key)
+                event.dataTransfer.effectAllowed = "move"
+              }}
+              onClick={() => onCardClick?.(card, column)}
+              onKeyDown={(event) => {
+                if ((event.key === "Enter" || event.key === " ") && onCardClick && !card.disabled) {
+                  event.preventDefault()
+                  onCardClick(card, column)
+                }
+              }}
+            >
+              <CardHeader className="p-3 pb-1">
+                <div className="flex items-start justify-between gap-2">
+                  <CardTitle className="text-sm">{card.title}</CardTitle>
+                  {(card.extra || card.actions) && <div className="flex shrink-0 items-center gap-1">{card.extra}{card.actions}</div>}
+                </div>
+              </CardHeader>
               {(card.description || card.meta) && (
                 <CardContent className="grid gap-2 p-3 pt-0 text-xs text-muted-foreground">
                   {card.description}

package/packages/cli/vendor/src/components/display/metric-grid.tsx

@@ -6,17 +6,18 @@ import { cn } from "@/lib/utils"
 export type MetricTone = "default" | "success" | "warning" | "danger" | "info" | "muted"
 export type MetricGridColumn = 1 | 2 | 3 | 4
 
-export type MetricItem = {
+export type MetricItem = {
   key: string
   label: React.ReactNode
   value: React.ReactNode
   description?: React.ReactNode
   icon?: React.ReactNode
   trend?: React.ReactNode
-  tone?: MetricTone
-  hidden?: boolean
-  className?: string
-}
+  tone?: MetricTone
+  hidden?: boolean
+  className?: string
+  loading?: boolean
+}
 
 export type MetricGridProps = React.ComponentProps<"div"> & {
   items: MetricItem[]
@@ -63,14 +64,16 @@ function MetricGrid({
           data-slot="stat-card"
           data-tone={item.tone ?? "default"}
           className={cn("min-w-0 overflow-hidden", toneClassName[item.tone ?? "default"], itemClassName, item.className)}
-        >
-          <CardHeader className={cn("flex flex-row items-start justify-between gap-3 space-y-0", compact ? "p-3 pb-1" : "pb-2")}>
-            <div className="min-w-0 space-y-1">
-              <CardDescription className="truncate">{item.label}</CardDescription>
-              <CardTitle className={cn("truncate", compact ? "text-xl" : "text-2xl")}>{item.value}</CardTitle>
-            </div>
-            {item.icon && <div className="shrink-0 rounded-lg bg-muted p-2 text-muted-foreground [&_svg]:size-4">{item.icon}</div>}
-          </CardHeader>
+        >
+          <CardHeader className={cn("flex flex-row items-start justify-between gap-3 space-y-0", compact ? "p-3 pb-1" : "pb-2")}>
+            <div className="min-w-0 space-y-1">
+              <CardDescription className="truncate">{item.label}</CardDescription>
+              <CardTitle className={cn("truncate", compact ? "text-xl" : "text-2xl")}>
+                {item.loading ? <span className="block h-8 w-24 animate-pulse rounded bg-muted" /> : item.value}
+              </CardTitle>
+            </div>
+            {item.icon && <div className="shrink-0 rounded-lg bg-muted p-2 text-muted-foreground [&_svg]:size-4">{item.icon}</div>}
+          </CardHeader>
           {(item.description || item.trend) && (
             <CardContent className={cn("flex min-w-0 items-center justify-between gap-2", compact ? "p-3 pt-1" : "pt-0")}>
               {item.description && <div className="min-w-0 truncate text-xs text-muted-foreground">{item.description}</div>}

package/packages/cli/vendor/src/components/display/qr-code.tsx

@@ -2,13 +2,14 @@ import * as React from "react"
 
 import { cn } from "@/lib/utils"
 
-export type QRCodeProps = React.ComponentProps<"div"> & {
-  value: string
-  src?: string
-  alt?: string
-  size?: number
-  cells?: number
-}
+export type QRCodeProps = React.ComponentProps<"div"> & {
+  value: string
+  src?: string
+  alt?: string
+  size?: number
+  cells?: number
+  visualOnlyLabel?: React.ReactNode
+}
 
 function hashValue(value: string) {
   let hash = 2166136261
@@ -53,18 +54,19 @@ function QRCodeSvg({ value, cells = 29, title }: { value: string; cells?: number
   )
 }
 
-function QRCode({ value, src, alt, size = 160, cells = 29, className, ...props }: QRCodeProps) {
-  return (
-    <div data-slot="qr-code" className={cn("inline-flex flex-col items-center gap-2 rounded-xl border bg-background p-3", className)} {...props}>
+function QRCode({ value, src, alt, size = 160, cells = 29, visualOnlyLabel = "Visual preview only. Provide src from a certified QR encoder for scan-critical use.", className, ...props }: QRCodeProps) {
+  return (
+    <div data-slot="qr-code" className={cn("inline-flex flex-col items-center gap-2 rounded-xl border bg-background p-3", className)} {...props}>
       <div className="rounded-md bg-white p-2" style={{ width: size, height: size }}>
         {src ? (
           <img src={src} alt={alt ?? value} width={size} height={size} className="size-full rounded-sm object-contain" />
         ) : (
           <QRCodeSvg value={value} cells={cells} title={alt} />
-        )}
-      </div>
-    </div>
-  )
-}
+        )}
+      </div>
+      {!src && visualOnlyLabel && <div className="max-w-48 text-center text-xs text-muted-foreground">{visualOnlyLabel}</div>}
+    </div>
+  )
+}
 
 export { QRCode, QRCodeSvg }