@lindaui/blocks 0.4.2 → 0.5.0

package/src/compat-chat/message-composer.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import { Button, Spinner, TextArea } from "@lindaui/ui/compound";
+import { Mic, Send } from "lucide-react";
+import { useCallback } from "react";
+
+export interface MessageComposerProps { disabled?: boolean; isSending?: boolean; onSend: () => void; onValueChange: (value: string) => void; placeholder?: string; value: string; }
+/** Controlled glass composer; Enter sends and Shift+Enter retains a newline. */
+export function MessageComposer({ value, onValueChange, onSend, isSending = false, placeholder, disabled = false }: MessageComposerProps) {
+  const hasText = value.trim().length > 0;
+  const handleChange = useCallback((e: React.ChangeEvent<HTMLTextAreaElement>) => onValueChange(e.target.value), [onValueChange]);
+  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
+    if (e.key === "Enter" && !e.shiftKey && !isSending) {
+      e.preventDefault();
+      if (hasText) onSend();
+    }
+  }, [hasText, isSending, onSend]);
+  return <div className="absolute inset-x-0 bottom-0 flex justify-center px-4 py-3">
+    <div className="flex w-full items-end gap-2 rounded-3xl border border-white/30 bg-white/60 px-4 py-2 shadow-2xl backdrop-blur-2xl backdrop-saturate-200 transition-all lg:w-[70%] dark:border-white/15 dark:bg-slate-800/40">
+      <TextArea aria-label={placeholder} className="field-sizing-content max-h-30 min-h-0 flex-1 resize-none overflow-y-auto border-none bg-transparent py-1 text-foreground shadow-none dark:text-white" disabled={disabled || isSending} onChange={handleChange} onKeyDown={handleKeyDown} placeholder={placeholder} rows={1} value={value} />
+      <Button className="rounded-full bg-[#00a884] text-white" isDisabled={disabled || isSending} isIconOnly isPending={isSending} onPress={hasText ? onSend : undefined} size="sm" variant="primary">
+        {({ isPending }) => isPending ? <Spinner color="current" size="sm" /> : hasText ? <Send className="h-4 w-4" /> : <Mic className="h-4 w-4" />}
+      </Button>
+    </div>
+  </div>;
+}

package/src/compat-chat/time-divider.tsx

@@ -0,0 +1,5 @@
+import { cn } from "@lindaui/ui/cn";
+
+export function TimeDivider({ label, className }: { className?: string; label: string }) {
+  return <div className={cn("sticky top-0 z-10 bg-background/80 px-4 py-2 backdrop-blur-sm", className)}><span className="font-medium text-[11px] text-muted">{label}</span></div>;
+}

package/src/compat-chat/time-grouping.ts

@@ -0,0 +1,19 @@
+import dayjs from "dayjs";
+
+export type TimeGroup = "Hoy" | "Ayer" | "Esta semana" | "Este mes" | "Más antiguos";
+export const TIME_GROUP_ORDER = ["Hoy", "Ayer", "Esta semana", "Este mes", "Más antiguos"] as const satisfies readonly TimeGroup[];
+export function getTimeGroup(date: string | Date): TimeGroup {
+  const now = dayjs();
+  const target = dayjs(date);
+  if (target.isSame(now, "day")) return "Hoy";
+  if (target.isSame(now.subtract(1, "day"), "day")) return "Ayer";
+  if (target.isAfter(now.subtract(7, "day"))) return "Esta semana";
+  if (target.isAfter(now.subtract(30, "day"))) return "Este mes";
+  return "Más antiguos";
+}
+export function groupByTime<T>(items: T[], getDate: (item: T) => string | Date): Record<TimeGroup, T[]> {
+  const grouped = {} as Record<TimeGroup, T[]>;
+  for (const group of TIME_GROUP_ORDER) grouped[group] = [];
+  items.forEach((item) => grouped[getTimeGroup(getDate(item))].push(item));
+  return grouped;
+}

package/src/compat-chat/types.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+
+/** Presentation-only types: map domain data in the consumer. */
+export type MessageSide = "center" | "left" | "right";
+export type MessageMediaKind = "audio" | "image" | "pdf";
+export interface GenericMessageMedia { kind: MessageMediaKind; label?: string; url: string; }
+export interface GenericMessage {
+  authorTag?: string;
+  id: string;
+  media?: GenericMessageMedia;
+  side: MessageSide;
+  text: string;
+  timestamp: Date | string;
+}
+export interface ConversationSummary {
+  avatarUrl?: string;
+  badge?: ReactNode;
+  id: string;
+  isSelected?: boolean;
+  preview?: string;
+  subtitle?: string;
+  timestamp?: Date | string;
+  title: string;
+  unreadCount?: number;
+}
+export interface ConversationThreadLabels {
+  errorLoading: string;
+  loading: string;
+  noMessages: string;
+  pollingFallback?: string;
+}

package/src/compat-chat/whatsapp-audio-player.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+export interface WhatsAppAudioPlayerProps { isBot?: boolean; src: string; }
+
+/** URL-seeded waveform: deterministic across renders and server/client. */
+function generateWaveform(seed: string, count = 60): number[] {
+  let h = 0;
+  for (let i = 0; i < seed.length; i += 1) h = (Math.imul(31, h) + seed.charCodeAt(i)) | 0;
+  return Array.from({ length: count }, () => {
+    h = (Math.imul(1_664_525, h) + 1_013_904_223) | 0;
+    return 0.12 + ((h >>> 0) / 4_294_967_295) * 0.88;
+  });
+}
+function formatSeconds(s: number): string {
+  if (!Number.isFinite(s) || s < 0) return "0:00";
+  return `${Math.floor(s / 60)}:${Math.floor(s % 60).toString().padStart(2, "0")}`;
+}
+function MicIcon({ color }: { color: string }) {
+  return <svg aria-hidden="true" fill={color} focusable="false" height="18" role="img" viewBox="0 0 24 24" width="18" xmlns="http://www.w3.org/2000/svg"><title>Micrófono</title><path d="M12 1a4 4 0 0 1 4 4v7a4 4 0 0 1-8 0V5a4 4 0 0 1 4-4zm0 2a2 2 0 0 0-2 2v7a2 2 0 1 0 4 0V5a2 2 0 0 0-2-2zm-7 8a1 1 0 0 1 .993.883L6 12a6 6 0 0 0 11.996.2L18 12a1 1 0 0 1 2 0 8 8 0 0 1-7 7.938V21h2a1 1 0 0 1 0 2H9a1 1 0 0 1 0-2h2v-1.062A8 8 0 0 1 4 12a1 1 0 0 1 1-1z" /></svg>;
+}
+function PlayIcon({ color }: { color: string }) { return <svg aria-hidden="true" fill={color} focusable="false" height="16" role="img" viewBox="0 0 24 24" width="16"><title>Reproducir</title><path d="M8 5.14v14l11-7-11-7z" /></svg>; }
+function PauseIcon({ color }: { color: string }) { return <svg aria-hidden="true" fill={color} focusable="false" height="16" role="img" viewBox="0 0 24 24" width="16"><title>Pausar</title><rect height="14" rx="1.5" width="4" x="6" y="5" /><rect height="14" rx="1.5" width="4" x="14" y="5" /></svg>; }
+function SpinnerIcon({ color }: { color: string }) { return <svg aria-hidden="true" className="animate-spin" fill="none" focusable="false" height="16" role="img" stroke={color} strokeWidth="2.5" viewBox="0 0 24 24" width="16"><title>Cargando</title><circle className="opacity-25" cx="12" cy="12" r="10" stroke={color} /><path className="opacity-75" d="M4 12a8 8 0 018-8" stroke={color} /></svg>; }
+function ButtonIcon({ isLoading, isPlaying, color }: { isLoading: boolean; isPlaying: boolean; color: string }) {
+  if (isLoading) return <SpinnerIcon color={color} />;
+  return isPlaying ? <PauseIcon color={color} /> : <PlayIcon color={color} />;
+}
+
+/** Voice-note playback, buffering, duration tracking and click-to-seek. */
+export function WhatsAppAudioPlayer({ src, isBot = false }: WhatsAppAudioPlayerProps) {
+  const audioRef = useRef<HTMLAudioElement>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [progress, setProgress] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const bars = useMemo(() => generateWaveform(src), [src]);
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    const onTimeUpdate = () => { setCurrentTime(audio.currentTime); setProgress(audio.duration > 0 ? audio.currentTime / audio.duration : 0); };
+    const onDurationChange = () => { if (Number.isFinite(audio.duration)) setDuration(audio.duration); };
+    const onEnded = () => { setIsPlaying(false); setProgress(0); setCurrentTime(0); audio.currentTime = 0; };
+    const onWaiting = () => setIsLoading(true);
+    const onCanPlay = () => setIsLoading(false);
+    const onPlay = () => setIsPlaying(true);
+    const onPause = () => setIsPlaying(false);
+    audio.addEventListener("timeupdate", onTimeUpdate);
+    audio.addEventListener("durationchange", onDurationChange);
+    audio.addEventListener("loadedmetadata", onDurationChange);
+    audio.addEventListener("ended", onEnded);
+    audio.addEventListener("waiting", onWaiting);
+    audio.addEventListener("canplay", onCanPlay);
+    audio.addEventListener("play", onPlay);
+    audio.addEventListener("pause", onPause);
+    return () => {
+      audio.removeEventListener("timeupdate", onTimeUpdate);
+      audio.removeEventListener("durationchange", onDurationChange);
+      audio.removeEventListener("loadedmetadata", onDurationChange);
+      audio.removeEventListener("ended", onEnded);
+      audio.removeEventListener("waiting", onWaiting);
+      audio.removeEventListener("canplay", onCanPlay);
+      audio.removeEventListener("play", onPlay);
+      audio.removeEventListener("pause", onPause);
+    };
+  }, []);
+  const togglePlay = useCallback(async () => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    if (isPlaying) audio.pause();
+    else await audio.play();
+  }, [isPlaying]);
+  const handleWaveformClick = useCallback((e: React.MouseEvent<HTMLButtonElement>) => {
+    const audio = audioRef.current;
+    if (!audio || !Number.isFinite(audio.duration)) return;
+    const rect = e.currentTarget.getBoundingClientRect();
+    const ratio = Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width));
+    audio.currentTime = ratio * audio.duration;
+    setProgress(ratio);
+  }, []);
+  const colors = isBot ? {
+    barPlayed: "rgba(255,255,255,0.9)", barUnplayed: "rgba(255,255,255,0.32)", btnBg: "rgba(0,0,0,0.15)", btnIcon: "#ffffff", micBg: "rgba(0,0,0,0.12)", micIcon: "rgba(255,255,255,0.85)", timer: "rgba(255,255,255,0.7)",
+  } : {
+    barPlayed: "#00a884", barUnplayed: "#c8d3d8", btnBg: "#00a884", btnIcon: "#ffffff", micBg: "#d9fdd3", micIcon: "#00a884", timer: "#8696a0",
+  };
+  const displayTime = isPlaying || progress > 0 ? currentTime : duration;
+  return <div className="flex w-full items-center gap-2 py-0.5 sm:min-w-[440px]">
+    <audio preload="metadata" ref={audioRef} src={src} />
+    <div aria-hidden="true" className="flex h-10 w-10 shrink-0 items-center justify-center rounded-full" style={{ backgroundColor: colors.micBg }}><MicIcon color={colors.micIcon} /></div>
+    <button aria-label={isPlaying ? "Pausar audio" : "Reproducir audio"} className="flex h-9 w-9 shrink-0 cursor-pointer items-center justify-center rounded-full transition-opacity hover:opacity-80 active:scale-95 focus:outline-none focus:ring-2 focus:ring-offset-1" onClick={togglePlay} style={{ backgroundColor: colors.btnBg }} type="button"><ButtonIcon color={colors.btnIcon} isLoading={isLoading} isPlaying={isPlaying} /></button>
+    <div className="flex min-w-0 flex-1 flex-col gap-1">
+      <button aria-label="Cambiar posición del audio" className="flex h-8 w-full items-center gap-[2px] focus:outline-none" onClick={handleWaveformClick} type="button">
+        {bars.map((height, i) => <span className="rounded-full transition-colors duration-75" key={i} style={{ backgroundColor: i / bars.length < progress ? colors.barPlayed : colors.barUnplayed, flex: "1", height: `${Math.round(height * 28)}px`, maxHeight: "28px", minHeight: "3px", width: "2px" }} />)}
+      </button>
+      <span className="select-none text-[10px] leading-none tabular-nums" style={{ color: colors.timer }}>{formatSeconds(displayTime)}</span>
+    </div>
+  </div>;
+}

package/src/compat.ts

@@ -0,0 +1,8 @@
+/** Legacy presentation API isolated from the existing lindaui entry points. */
+export * from "@lindaui/ui/compat";
+export { KPICard } from "./legacy-kpi-card";
+export type { KPICardProps, KPICardColor } from "./legacy-kpi-card";
+export { StatusFilters } from "./status-filters";
+export type { StatusFiltersProps } from "./status-filters";
+export { DateDivider } from "./compat-chat/date-divider";
+export type { DateDividerProps } from "./compat-chat/date-divider";

package/src/confirm-dialog.tsx

@@ -0,0 +1,85 @@
+"use client";
+import type { ReactNode } from "react";
+import { Dialog } from "@lindaui/ui/dialog";
+import { Button } from "@lindaui/ui/button";
+
+export interface ConfirmDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onConfirm: () => void;
+  title: ReactNode;
+  description?: ReactNode;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  icon?: ReactNode;
+  /** Acción irreversible: botón de confirmar en rojo + icon box destructivo. */
+  destructive?: boolean;
+  /** Chip del actor responsable (ej. firmante) bajo la descripción. */
+  identity?: { name: string };
+}
+
+function getInitials(name: string): string {
+  return name
+    .split(" ")
+    .filter((p) => p.length > 0)
+    .map((p) => p[0])
+    .join("")
+    .slice(0, 2)
+    .toUpperCase();
+}
+
+export function ConfirmDialog({
+  open,
+  onOpenChange,
+  onConfirm,
+  title,
+  description,
+  confirmLabel = "Confirmar",
+  cancelLabel = "Cancelar",
+  icon,
+  destructive = false,
+  identity,
+}: ConfirmDialogProps) {
+  return (
+    <Dialog
+      open={open}
+      onClose={() => onOpenChange(false)}
+      title={title}
+      footer={
+        <div className="flex flex-col-reverse gap-2 w-full sm:flex-row sm:justify-end sm:w-auto">
+          <Button variant="ghost" onPress={() => onOpenChange(false)} className="w-full sm:w-auto">
+            {cancelLabel}
+          </Button>
+          <Button
+            variant={destructive ? "danger" : "primary"}
+            onPress={onConfirm}
+            className="w-full sm:w-auto"
+          >
+            {confirmLabel}
+          </Button>
+        </div>
+      }
+    >
+      {icon && (
+        <div
+          className={`w-10 h-10 rounded-[10px] grid place-items-center mb-3.5 ${
+            destructive ? "bg-destructive/10 text-destructive" : "bg-primary/10 text-primary"
+          }`}
+        >
+          {icon}
+        </div>
+      )}
+      {description && (
+        <p className="text-sm text-muted-foreground">{description}</p>
+      )}
+      {identity && (
+        <div className="mt-4 px-3.5 py-3 rounded-[calc(var(--radius)-2px)] bg-muted flex items-center gap-2.5">
+          <div className="w-8 h-8 rounded-full bg-secondary text-secondary-foreground grid place-items-center text-xs font-semibold shrink-0">
+            {getInitials(identity.name)}
+          </div>
+          <span className="text-xs font-semibold">{identity.name}</span>
+        </div>
+      )}
+    </Dialog>
+  );
+}

package/src/connection-panel/connected-panel.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import { Button, Modal, Spinner } from "@lindaui/ui/compound";
+import { useRef, useState, type ReactNode } from "react";
+
+export interface ConnectionDetail {
+  id: string;
+  label: ReactNode;
+  value: ReactNode;
+  valueClassName?: string;
+  dateTime?: string;
+}
+
+export interface ConnectedPanelLabels {
+  disconnectHint: ReactNode;
+  disconnect: ReactNode;
+  disconnecting: ReactNode;
+  disconnectError: ReactNode;
+  confirmTitle: ReactNode;
+  confirmDescription: ReactNode;
+  cancel: ReactNode;
+}
+
+export interface ConnectedPanelProps {
+  details: readonly ConnectionDetail[];
+  labels: ConnectedPanelLabels;
+  error?: ReactNode;
+  onDisconnect: () => Promise<void>;
+}
+
+/** Connection metadata and an async, non-dismissable-while-pending confirmation. */
+export function ConnectedPanel({ details, labels, error: connectionError, onDisconnect }: ConnectedPanelProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<ReactNode>(null);
+  const pending = useRef(false);
+
+  async function disconnect() {
+    if (pending.current) return;
+    pending.current = true;
+    setIsPending(true);
+    setError(null);
+    try {
+      await onDisconnect();
+      setIsOpen(false);
+    } catch {
+      setError(labels.disconnectError);
+    } finally {
+      pending.current = false;
+      setIsPending(false);
+    }
+  }
+
+  return (
+    <div className="space-y-6">
+      <dl className="divide-y divide-border/60 text-sm">
+        {details.map(({ id, label, value, valueClassName, dateTime }) => (
+          <div className="flex flex-col gap-1 py-4 sm:flex-row sm:justify-between sm:gap-6" key={id}>
+            <dt className="text-muted">{label}</dt>
+            <dd className={valueClassName}>
+              {dateTime ? <time dateTime={dateTime}>{value}</time> : value}
+            </dd>
+          </div>
+        ))}
+      </dl>
+      <div className="flex flex-col items-start gap-3 border-border/60 border-t pt-5 sm:flex-row sm:items-center sm:justify-between sm:gap-6">
+        <p className="max-w-sm text-muted text-xs leading-relaxed">{labels.disconnectHint}</p>
+        <Button
+          className="min-h-11 shrink-0"
+          onPress={() => { setError(null); setIsOpen(true); }}
+          variant="danger-soft"
+        >
+          {labels.disconnect}
+        </Button>
+      </div>
+      {connectionError && !isOpen && <p className="text-danger text-sm" role="alert">{connectionError}</p>}
+      <Modal.Backdrop
+        isDismissable={!isPending}
+        isKeyboardDismissDisabled={isPending}
+        isOpen={isOpen}
+        onOpenChange={(open) => { if (!pending.current) setIsOpen(open); }}
+      >
+        <Modal.Container>
+          <Modal.Dialog className="sm:max-w-md" role="alertdialog">
+            <Modal.Header>
+              <Modal.Heading>{labels.confirmTitle}</Modal.Heading>
+            </Modal.Header>
+            <Modal.Body>
+              <p className="text-muted text-sm leading-relaxed">{labels.confirmDescription}</p>
+              {error && <p className="mt-3 text-danger text-sm" role="alert">{error}</p>}
+            </Modal.Body>
+            <Modal.Footer>
+              <Button autoFocus isDisabled={isPending} onPress={() => setIsOpen(false)} variant="tertiary">
+                {labels.cancel}
+              </Button>
+              <Button isPending={isPending} onPress={disconnect} variant="danger">
+                {isPending && <Spinner color="current" size="sm" />}
+                {isPending ? labels.disconnecting : labels.disconnect}
+              </Button>
+            </Modal.Footer>
+          </Modal.Dialog>
+        </Modal.Container>
+      </Modal.Backdrop>
+    </div>
+  );
+}

package/src/connection-panel/disconnected-panel.tsx

@@ -0,0 +1,48 @@
+import { Button, Spinner } from "@lindaui/ui/compound";
+import type { ReactNode } from "react";
+import type { ConnectionPanelLabels } from "../connection-panel";
+import { ConnectionInstructions } from "./instructions";
+
+interface DisconnectedPanelProps {
+  generating: boolean;
+  pending: boolean;
+  labels: ConnectionPanelLabels;
+  error?: ReactNode;
+  onConnect: () => Promise<void>;
+}
+
+export function DisconnectedPanel({ generating, pending, labels, error, onConnect }: DisconnectedPanelProps) {
+  return (
+    <>
+      {generating && (
+        <div className="space-y-3" role="status">
+          <div className="mx-auto flex size-48 items-center justify-center rounded-xl bg-surface-secondary">
+            <Spinner size="lg" />
+          </div>
+          <p className="text-muted text-sm">{labels.generating}</p>
+        </div>
+      )}
+      <div className="space-y-5">
+        <p className="max-w-md text-muted text-sm leading-relaxed">{labels.disconnectedDescription}</p>
+        <ConnectionInstructions items={labels.disconnectedInstructions} />
+      </div>
+      {error && <p className="text-danger text-sm" role="alert">{error}</p>}
+      {!generating && (
+        <Button
+          className="mt-2 min-h-11 w-full whitespace-nowrap sm:w-auto"
+          isPending={pending}
+          onPress={onConnect}
+          size="lg"
+          variant="secondary"
+        >
+          {({ isPending }) => (
+            <>
+              {isPending && <Spinner color="current" size="sm" />}
+              {labels.connect}
+            </>
+          )}
+        </Button>
+      )}
+    </>
+  );
+}

package/src/connection-panel/instructions.tsx

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react";
+
+export function ConnectionInstructions({ items }: { items: readonly ReactNode[] }) {
+  return (
+    <ol className="mx-auto w-fit list-inside list-decimal space-y-2 text-left text-muted text-sm">
+      {items.map((item, index) => <li key={index}>{item}</li>)}
+    </ol>
+  );
+}

package/src/connection-panel/qr-panel.tsx

@@ -0,0 +1,62 @@
+import { Button, Spinner } from "@lindaui/ui/compound";
+import { RefreshCw } from "lucide-react";
+import type { ReactNode } from "react";
+import type { ConnectionPanelLabels } from "../connection-panel";
+import { ConnectionInstructions } from "./instructions";
+
+interface QRPanelProps {
+  qrCode: ReactNode;
+  qrFormat?: "ascii" | "image";
+  labels: ConnectionPanelLabels;
+  timeRemaining: number;
+  isRefreshing: boolean;
+  error?: ReactNode;
+  onRefresh: () => Promise<void>;
+}
+
+function formatTime(seconds: number) {
+  return `${Math.floor(seconds / 60)}:${(seconds % 60).toString().padStart(2, "0")}`;
+}
+
+export function QRPanel({ qrCode, qrFormat, labels, timeRemaining, isRefreshing, error, onRefresh }: QRPanelProps) {
+  return (
+    <>
+      <div className="flex justify-center">
+        <div
+          className={qrFormat === "ascii"
+            ? "relative overflow-hidden rounded-xl bg-white p-2 shadow-md ring-1 ring-black/5"
+            : "relative flex aspect-square w-48 items-center justify-center rounded-xl bg-white p-3 shadow-md ring-1 ring-black/5"}
+        >
+          {qrCode}
+          {timeRemaining <= 10 && (
+            <div className="absolute inset-0 flex items-center justify-center rounded-xl bg-black/60 backdrop-blur-sm">
+              <div className="text-center">
+                <p className="font-bold text-2xl text-white">{formatTime(timeRemaining)}</p>
+                <p className="text-white/80 text-xs">{labels.expiresSoon}</p>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+      <div className="space-y-2 text-center">
+        <div className="flex items-center justify-center gap-2 text-muted" role="status">
+          <Spinner color="current" size="sm" />
+          <span className="font-medium text-sm">{labels.waiting}</span>
+        </div>
+        <p className="text-muted text-xs">{labels.expiresIn(formatTime(timeRemaining))}</p>
+      </div>
+      <div className="border-border/60 border-t pt-5">
+        <ConnectionInstructions items={labels.instructions} />
+      </div>
+      {error && <p className="text-danger text-sm" role="alert">{error}</p>}
+      <Button className="min-h-11 w-full sm:w-auto" isPending={isRefreshing} onPress={onRefresh} variant="tertiary">
+        {({ isPending }) => (
+          <>
+            {isPending ? <Spinner color="current" size="sm" /> : <RefreshCw className="h-4 w-4" />}
+            {labels.refresh}
+          </>
+        )}
+      </Button>
+    </>
+  );
+}

package/src/connection-panel/use-qr-refresh.ts

@@ -0,0 +1,52 @@
+import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+
+interface QRRefreshOptions {
+  enabled: boolean;
+  expirySeconds: number;
+  error?: ReactNode;
+  errorLabel: ReactNode;
+  onRefresh: () => Promise<void>;
+}
+
+/** Pause hidden challenges and never overlap refreshes or automatically retry failures. */
+export function useQRRefresh({ enabled, expirySeconds, error, errorLabel, onRefresh }: QRRefreshOptions) {
+  const [timeRemaining, setTimeRemaining] = useState(expirySeconds);
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const [actionError, setActionError] = useState<ReactNode>(null);
+  const pending = useRef(false);
+
+  const refresh = useCallback(async () => {
+    if (pending.current) return;
+    pending.current = true;
+    setIsRefreshing(true);
+    setActionError(null);
+    try {
+      await onRefresh();
+      setTimeRemaining(expirySeconds);
+    } catch {
+      setActionError(errorLabel);
+    } finally {
+      pending.current = false;
+      setIsRefreshing(false);
+    }
+  }, [onRefresh, expirySeconds, errorLabel]);
+
+  useEffect(() => {
+    if (!enabled) {
+      setTimeRemaining(expirySeconds);
+      return;
+    }
+    if (isRefreshing || error || actionError) return;
+    const timer = setInterval(() => setTimeRemaining((value) => Math.max(0, value - 1)), 1000);
+    return () => clearInterval(timer);
+  }, [enabled, expirySeconds, isRefreshing, error, actionError]);
+
+  useEffect(() => {
+    if (enabled && timeRemaining === 0 && !error && !actionError && !isRefreshing) {
+      setTimeRemaining(expirySeconds);
+      void refresh();
+    }
+  }, [enabled, timeRemaining, expirySeconds, error, actionError, isRefreshing, refresh]);
+
+  return { timeRemaining, isRefreshing, actionError, setActionError, refresh };
+}