"use client"; import * as React from "react"; import { motion, AnimatePresence, type Transition } from "motion/react"; import { cn } from "@/lib/utils"; import { useReducedMotion, useCopy, formatTimestamp as defaultFormatTimestamp, statusVars, type StatusTone, } from "@/lib/motiq"; /* -------------------------------------------------------------------------- * MessageDeliveryStates — a chat/message list whose differentiator is an honest, * legible DELIVERY-RECEIPT layer. Each message shows its app-supplied lifecycle * (draft · sending · sent · delivered · read · failed · retrying · scheduled · * cancelled · edited) as icon + TEXT (never colour or icon alone), with read * receipts, an associated error + Retry, and Cancel for scheduled sends. * * PRESENTATION ONLY. The component never talks to a network, never invents a * delivery outcome, and never advances a state on its own — the application owns * every transition and passes the next `deliveryState` in. Motion is used only * to COMMUNICATE a transition the app just made (sent→delivered tick draw, →read * recolor, a single failure nudge, retry, edit, cancellation); there is no * perpetual spinner, bouncing dot, or idle typing loop, and reduced-motion users * see every state change instantly. Clean-room original. * ----------------------------------------------------------------------- */ export type DeliveryState = | "draft" | "sending" | "sent" | "delivered" | "read" | "failed" | "retrying" | "scheduled" | "cancelled" | "edited"; /** State of a file/media upload riding along with a message. */ export type AttachmentState = "pending" | "uploading" | "uploaded" | "failed"; export interface MessageAuthor { /** Stable identity — drives keys, avatar hue, and own/other alignment. */ id: string; /** Human name; also the avatar's accessible text. */ name: string; /** Optional avatar image; when absent an initials + hue avatar is generated. */ avatarUrl?: string; /** Optional explicit avatar color (any CSS color). */ color?: string; } /** A person the app reports as having read the message (app-supplied). */ export interface ReadRecipient { id: string; name: string; avatarUrl?: string; color?: string; /** When they read it (used for the accessible label / tooltip). */ readAt?: Date | number | string; } export interface DeliveryMessage { /** Stable id — drives keys and change detection for announcements. */ id: string; /** The message text. Stays selectable. */ body: string; author: MessageAuthor; /** When the message was composed/sent. */ timestamp: Date | number | string; /** App-owned lifecycle state. The component never advances this itself. */ deliveryState: DeliveryState; /** People the app reports as having read this message (drives read receipts). */ readRecipients?: ReadRecipient[]; /** Human-readable failure reason; associated with the message for a11y. */ error?: string; /** When set, the message shows an "Edited" affordance regardless of state. */ edited?: boolean; /** When the edit happened (shown in the accessible edited label). */ editedAt?: Date | number | string; /** For `scheduled` messages: when it will send. */ scheduledFor?: Date | number | string; /** Optional single attachment lifecycle badge. */ attachmentState?: AttachmentState; /** Optional attachment display name (paired with `attachmentState`). */ attachmentName?: string; } export interface MessageDeliveryStatesProps { /** App-owned messages, in order. */ messages: DeliveryMessage[]; /** Whose perspective this is — their messages align right and show receipts. */ currentUserId: string; /** Retry a failed/undelivered message. Rendered as a keyboard-accessible button. */ onRetry?: (message: DeliveryMessage) => void; /** Cancel a scheduled (or in-flight) message before it sends. */ onCancel?: (message: DeliveryMessage) => void; /** Edit a message (the app opens its own composer). */ onEdit?: (message: DeliveryMessage) => void; /** Copy a message body; receives the plain text. */ onCopy?: (message: DeliveryMessage) => void; /** Override timestamp formatting (pass for deterministic output). */ formatTimestamp?: (value: DeliveryMessage["timestamp"], message: DeliveryMessage) => string; /** Reference "now" (ms) for relative timestamps; omit for absolute time. */ now?: number; /** Accessible label for the conversation region. */ label?: string; /** Max height of the scroll region (px). Omit for no scroll cap. */ maxHeight?: number; className?: string; } const EASE: Transition["ease"] = [0.2, 0, 0, 1]; /* -- state vocabulary ---------------------------------------------------- */ interface StateMeta { /** Short label shown next to the icon (always rendered as TEXT). */ label: string; tone: StatusTone; /** Longer phrase for the live region / accessible receipt. */ announce?: (m: DeliveryMessage) => string; } const STATE_META: Record = { draft: { label: "Draft", tone: "neutral" }, sending: { label: "Sending", tone: "info" }, sent: { label: "Sent", tone: "neutral", announce: () => "Message sent" }, delivered: { label: "Delivered", tone: "info", announce: () => "Message delivered" }, read: { label: "Read", tone: "success", announce: () => "Message read" }, failed: { label: "Not delivered", tone: "error", announce: () => "Message failed to send" }, retrying: { label: "Retrying", tone: "warning", announce: () => "Retrying message" }, scheduled: { label: "Scheduled", tone: "info" }, cancelled: { label: "Cancelled", tone: "neutral", announce: () => "Scheduled message cancelled" }, edited: { label: "Edited", tone: "neutral" }, }; /** Transitions the app makes that are worth a single, restrained announcement. */ const ANNOUNCEABLE: ReadonlySet = new Set([ "delivered", "read", "failed", "cancelled", ]); /* -- helpers ------------------------------------------------------------- */ function toMs(value: Date | number | string): number { const d = value instanceof Date ? value : new Date(value); return d.getTime(); } function hueFromString(s: string): number { let h = 0; for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) >>> 0; return h % 360; } function initials(name: string): string { const parts = name.trim().split(/\s+/).filter(Boolean); if (parts.length === 0) return "?"; const first = parts[0][0] ?? ""; const second = parts.length > 1 ? parts[parts.length - 1][0] ?? "" : ""; return (first + second).toUpperCase(); } function joinNames(names: string[]): string { if (names.length === 0) return ""; if (names.length === 1) return names[0]; if (names.length === 2) return `${names[0]} and ${names[1]}`; return `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`; } /* -- avatar -------------------------------------------------------------- */ function Avatar({ author, size = 28, }: { author: { id: string; name: string; avatarUrl?: string; color?: string }; size?: number; }) { const h = hueFromString(author.color ?? author.id + author.name); const bg = author.color ?? `linear-gradient(140deg, hsl(${h} 62% 52%), hsl(${(h + 42) % 360} 66% 42%))`; if (author.avatarUrl) { return ( {author.name}

); } return ( {initials(author.name)} ); } /* -- delivery ticks / state icon ----------------------------------------- */ const svgCommon = { width: 14, height: 14, viewBox: "0 0 24 24", fill: "none", "aria-hidden": true } as const; const stroke = { stroke: "currentColor", strokeWidth: 2.2, strokeLinecap: "round" as const, strokeLinejoin: "round" as const, }; /** * The receipt icon. Delivered/read draw the second tick in (once) so the * transition is felt without any looping animation; every other state is a * static glyph. Reduced motion renders the final frame with no draw. */ function StateIcon({ state, reduce }: { state: DeliveryState; reduce: boolean }) { const draw = reduce ? {} : { initial: { pathLength: 0, opacity: 0 }, animate: { pathLength: 1, opacity: 1 }, transition: { duration: 0.34, ease: EASE } }; switch (state) { case "sent": return ( ); case "delivered": case "read": // Double tick — the trailing tick draws in to signal the advance. return ( ); case "sending": case "retrying": // Static arrow — no perpetual spinner; the label carries the "in progress". return ( ); case "failed": return ( ); case "scheduled": return ( ); case "cancelled": return ( ); case "edited": return ( ); case "draft": default: return ( ); } } /** * The delivery receipt: icon + TEXT label, keyed on state so a state change * remounts it and plays a short entrance (fade/slide). A `failed` state gets a * single horizontal nudge — never a loop. Reduced motion: no entrance, no nudge. */ function DeliveryReceipt({ message, reduce }: { message: DeliveryMessage; reduce: boolean }) { const meta = STATE_META[message.deliveryState]; const v = statusVars(meta.tone); const failed = message.deliveryState === "failed"; const enter = reduce ? { initial: false as const, animate: { opacity: 1 } } : failed ? { initial: { opacity: 0 }, animate: { opacity: 1, x: [0, -3, 3, -2, 2, 0] } } : { initial: { opacity: 0, y: 3 }, animate: { opacity: 1, y: 0 } }; return ( {meta.label} ); } /* -- read receipts ------------------------------------------------------- */ function ReadReceipts({ recipients }: { recipients: ReadRecipient[] }) { if (recipients.length === 0) return null; const names = recipients.map((r) => r.name); return ( Read by {joinNames(names)} {recipients.slice(0, 4).map((r) => ( ))} Read by {names.length > 2 ? `${names[0]} +${names.length - 1}` : joinNames(names)} ); } /* -- attachment badge ---------------------------------------------------- */ const ATTACHMENT_LABEL: Record = { pending: { label: "Attachment queued", tone: "neutral" }, uploading: { label: "Uploading attachment", tone: "info" }, uploaded: { label: "Attachment sent", tone: "success" }, failed: { label: "Attachment failed", tone: "error" }, }; function AttachmentBadge({ state, name }: { state: AttachmentState; name?: string }) { const meta = ATTACHMENT_LABEL[state]; const v = statusVars(meta.tone); return ( {meta.label} {name ? · {name} : null} ); } /* -- action button ------------------------------------------------------- */ function Action({ children, onClick, tone, ...rest }: React.ButtonHTMLAttributes & { tone?: "danger" }) { return ( ); } /* -- single message ------------------------------------------------------ */ function MessageRow({ message, own, reduce, fmt, onRetry, onCancel, onEdit, onCopy, }: { message: DeliveryMessage; own: boolean; reduce: boolean; fmt: (message: DeliveryMessage) => string; onRetry?: MessageDeliveryStatesProps["onRetry"]; onCancel?: MessageDeliveryStatesProps["onCancel"]; onEdit?: MessageDeliveryStatesProps["onEdit"]; onCopy?: MessageDeliveryStatesProps["onCopy"]; }) { const { copied, copy } = useCopy({ onCopy: () => onCopy?.(message) }); const errorId = `${message.id}-error`; const state = message.deliveryState; const isFailed = state === "failed"; const isCancelled = state === "cancelled"; const isScheduled = state === "scheduled"; const isEdited = message.edited || state === "edited"; const timeIso = new Date(toMs(message.timestamp)).toISOString(); return (

{!own ? : null}

{/* header */}

{own ? "You" : message.author.name} {fmt(message)}

{/* bubble — body stays selectable */}

{message.body}

{/* attachment lifecycle */} {message.attachmentState ? ( ) : null} {/* receipt + edited + read receipts */}

{isEdited && state !== "edited" ? ( Edited{message.editedAt ? ` ${fmt({ ...message, timestamp: message.editedAt })}` : ""} ) : null} {isScheduled && message.scheduledFor ? ( Sends {fmt({ ...message, timestamp: message.scheduledFor })} ) : null} {state === "read" && message.readRecipients?.length ? ( ) : null}

{/* error — associated with the message, conveyed as text */} {isFailed && message.error ? (

{message.error}

) : null} {/* actions */}

{isFailed && onRetry ? ( onRetry(message)}> Retry ) : null} {(isScheduled || state === "sending" || state === "retrying") && onCancel ? ( onCancel(message)}> Cancel ) : null} {onEdit && !isCancelled && state !== "sending" && state !== "retrying" ? ( onEdit(message)}>Edit ) : null} {onCopy ? ( void copy(message.body)}>{copied ? "Copied" : "Copy"} ) : null}

); } /* -- root ---------------------------------------------------------------- */ export function MessageDeliveryStates({ messages, currentUserId, onRetry, onCancel, onEdit, onCopy, formatTimestamp, now, label = "Conversation", maxHeight, className, }: MessageDeliveryStatesProps) { const reduce = useReducedMotion(); const fmt = React.useCallback( (message: DeliveryMessage) => { if (formatTimestamp) return formatTimestamp(message.timestamp, message); if (now != null) return defaultFormatTimestamp(message.timestamp, { relative: true, now }); return defaultFormatTimestamp(message.timestamp, {}); }, [formatTimestamp, now], ); /* -- restrained live-region: announce only meaningful state advances --- */ const prevStates = React.useRef>(new Map()); const [liveMessage, setLiveMessage] = React.useState(""); React.useEffect(() => { let announcement = ""; const seen = new Set(); for (const m of messages) { seen.add(m.id); const prev = prevStates.current.get(m.id); if (prev !== undefined && prev !== m.deliveryState && ANNOUNCEABLE.has(m.deliveryState)) { const meta = STATE_META[m.deliveryState]; announcement = meta.announce ? meta.announce(m) : `Message ${meta.label.toLowerCase()}`; } prevStates.current.set(m.id, m.deliveryState); } // Forget messages that were removed so their ids don't leak. for (const id of [...prevStates.current.keys()]) { if (!seen.has(id)) prevStates.current.delete(id); } // Only the latest meaningful change is voiced — never every micro-update. if (announcement) setLiveMessage(announcement); }, [messages]); return (

{messages.length === 0 ? (

No messages yet.

) : (

{messages.map((m) => ( ))}

)}

{/* Restrained polite live region — one meaningful transition at a time. */}

{liveMessage}

); } export default MessageDeliveryStates;