@spunto/design-system 0.28.0 → 0.30.0

package/src/components/tasks/task-attachments.tsx

@@ -0,0 +1,475 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState, type ClipboardEvent, type DragEvent } from "react"
+import { createPortal } from "react-dom"
+import { DownloadIcon, Loader2Icon, PaperclipIcon, XIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import { useOverlayContainer } from "../spunto-provider"
+import { MAX_FILES_PER_TURN, MAX_TURN_BYTES, fileKind, filesFrom, formatBytes, isPreviewable, prepareFile } from "./attachments"
+import type { AttachmentUrl, DraftFile, TaskFileRef } from "./types"
+
+/**
+ * Files in a delegated conversation (RFC 0022) — both directions, in one file, because they are
+ * the same object seen from two sides: what you are about to send, and what is already there.
+ *
+ * Two rules run through all of it:
+ *
+ *  1. **An attachment is never bigger than the thing it explains.** On the timeline a screenshot
+ *     is a thumbnail on the rail, the size of a paragraph, and clicking it opens it full — a
+ *     transcript where every tool answer is a full-bleed picture stops being a transcript.
+ *  2. **Only images are pictures.** Everything else is a row with a name, a size and a download,
+ *     because that is all a browser should be asked to do with bytes it was handed (the API
+ *     refuses to serve anything but four raster formats inline, for the same reason).
+ */
+
+// ── Sending ───────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The files a composer is holding, and the three ways they arrive: the button, a paste, a drop.
+ *
+ * Paste is the one that carries the feature — a screenshot lives on the clipboard, and any path
+ * that makes someone save it to a file first is a path they will not take.
+ *
+ * Preparation (shrink, encode) is async and shows as a count, because a 4K paste takes a beat and
+ * a composer that looks like nothing happened invites a second paste.
+ */
+export function useAttachmentDraft() {
+  const [files, setFiles] = useState<DraftFile[]>([])
+  const [preparing, setPreparing] = useState(0)
+  const [error, setError] = useState<string | null>(null)
+  const [draggingOver, setDraggingOver] = useState(false)
+  // `dragenter`/`dragleave` fire for every child the pointer crosses, so a boolean flickers off
+  // the moment the cursor passes over the textarea inside the zone. Counting entries and exits is
+  // the standard fix: the zone is "entered" until as many leaves as enters have come back.
+  const depth = useRef(0)
+
+  // Object URLs outlive the render that made them, so they are revoked when the draft lets go of
+  // them and once more when the component unmounts with files still in hand.
+  const live = useRef<DraftFile[]>([])
+  live.current = files
+  useEffect(() => () => live.current.forEach(revoke), [])
+
+  const add = useCallback(async (incoming: File[]) => {
+    if (incoming.length === 0) return
+    setError(null)
+    setPreparing((n) => n + incoming.length)
+    try {
+      for (const file of incoming) {
+        const prepared = await prepareFile(file)
+        if (!prepared) {
+          setError(`${file.name || "That file"} could not be attached — it is empty, or over 10 MB.`)
+          continue
+        }
+        let refused: string | null = null
+        setFiles((prev) => {
+          if (prev.length >= MAX_FILES_PER_TURN) {
+            refused = `Up to ${MAX_FILES_PER_TURN} files per message.`
+            return prev
+          }
+          // The per-turn budget, so ten files at the ceiling is not a 100 MB request — the API
+          // enforces the same thing, this just says so before the round trip.
+          const total = prev.reduce((n, f) => n + f.bytes, 0)
+          if (total + prepared.bytes > MAX_TURN_BYTES) {
+            refused = `That would take this message over ${formatBytes(MAX_TURN_BYTES)} in total.`
+            return prev
+          }
+          return [...prev, prepared]
+        })
+        if (refused) {
+          revoke(prepared)
+          setError(refused)
+        }
+      }
+    } finally {
+      setPreparing((n) => Math.max(0, n - incoming.length))
+    }
+  }, [])
+
+  const remove = useCallback((key: string) => {
+    setFiles((prev) => {
+      const gone = prev.find((f) => f.key === key)
+      if (gone) revoke(gone)
+      return prev.filter((f) => f.key !== key)
+    })
+  }, [])
+
+  /** Drop the draft and free its thumbnails — abandoning it, not sending it. */
+  const clear = useCallback(() => {
+    setFiles((prev) => {
+      prev.forEach(revoke)
+      return []
+    })
+    setError(null)
+  }, [])
+
+  /**
+   * Empty the draft while **handing the object URLs on** to whoever takes the turn from here.
+   *
+   * The difference with `clear` is the whole point: a sent message is drawn optimistically from
+   * these very URLs until its own event comes back, so revoking them on submit blanks the picture
+   * in the bubble the instant it appears — which reads as the send having failed.
+   */
+  const release = useCallback(() => {
+    setFiles([])
+    setError(null)
+  }, [])
+
+  /** What goes in the request body — the local-only fields stay local. */
+  const payload = useCallback(
+    () => files.map(({ name, mediaType, data }) => ({ filename: name, mediaType, data })),
+    [files],
+  )
+
+  return {
+    files,
+    preparing,
+    error,
+    add,
+    remove,
+    clear,
+    release,
+    payload,
+    draggingOver,
+    /** Wire onto a textarea: a screenshot on the clipboard is the common case, not a fallback. */
+    onPaste: (e: ClipboardEvent) => {
+      const dropped = filesFrom(e.clipboardData?.items ?? null)
+      if (dropped.length === 0) return
+      // Only once there *is* a file: a plain text paste must go through untouched.
+      e.preventDefault()
+      void add(dropped)
+    },
+    /**
+     * Spread onto whatever should accept a drop — in practice the whole composer, not just the
+     * textarea. Dropping a file onto a reply box is something people try before they look for a
+     * button, so the target has to be the box they can see, and it has to light up.
+     */
+    dropZone: {
+      onDragEnter: (e: DragEvent) => {
+        if (!e.dataTransfer?.types.includes("Files")) return
+        depth.current += 1
+        setDraggingOver(true)
+      },
+      onDragLeave: () => {
+        depth.current = Math.max(0, depth.current - 1)
+        if (depth.current === 0) setDraggingOver(false)
+      },
+      // Without this the browser navigates to the dropped file instead of handing it over.
+      onDragOver: (e: DragEvent) => {
+        if (e.dataTransfer?.types.includes("Files")) e.preventDefault()
+      },
+      onDrop: (e: DragEvent) => {
+        depth.current = 0
+        setDraggingOver(false)
+        const dropped = filesFrom(e.dataTransfer?.files ?? null)
+        if (dropped.length === 0) return
+        e.preventDefault()
+        void add(dropped)
+      },
+    },
+  }
+}
+
+function revoke(file: DraftFile): void {
+  if (file.previewUrl) URL.revokeObjectURL(file.previewUrl)
+}
+
+export type AttachmentDraft = ReturnType<typeof useAttachmentDraft>
+
+/**
+ * The attach control — a hidden file input behind a button you can actually find.
+ *
+ * A **paperclip**, not a picture frame: the glyph every messaging and mail client uses for "put
+ * something in this message", and now literally true, since it takes any file.
+ *
+ * Sized and placed like one too. The first cut of this was a 28px borderless icon tucked into the
+ * composer's 10px hint bar, next to the text — technically present, and missed entirely by the
+ * first person who went looking for it. Attaching is not a footnote about the box, it is one of
+ * the two things you do with it, so it sits **at the edge of the writing area**, at a size a
+ * pointer aims at without care.
+ */
+export function AttachFileButton({
+  onFiles,
+  disabled,
+  className,
+  size = "md",
+  label,
+}: {
+  onFiles: (files: File[]) => void
+  disabled?: boolean
+  className?: string
+  size?: "md" | "lg"
+  /** Spelled out instead of icon-only — for a form, which has the room a composer doesn't. */
+  label?: string
+}) {
+  const input = useRef<HTMLInputElement>(null)
+  return (
+    <>
+      {/* No `accept`: the platform stores bytes and hands the agent a path, so narrowing the
+          picker would only hide files it is perfectly able to carry. */}
+      <input
+        ref={input}
+        type="file"
+        multiple
+        className="hidden"
+        onChange={(e) => {
+          onFiles(filesFrom(e.target.files))
+          // Cleared so picking the same file twice in a row still fires a change.
+          e.target.value = ""
+        }}
+      />
+      <button
+        type="button"
+        disabled={disabled}
+        onClick={() => input.current?.click()}
+        aria-label={label ?? "Attach files"}
+        title="Attach files — or paste, or drop them in"
+        className={cn(
+          "flex shrink-0 touch-manipulation items-center gap-1.5 rounded-lg border border-border/80 bg-background text-muted-foreground transition-colors hover:border-primary/40 hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-40",
+          label ? "px-2.5 py-1.5 text-xs" : size === "lg" ? "h-10 w-10 justify-center rounded-full" : "h-8 w-8 justify-center",
+          className,
+        )}
+      >
+        <PaperclipIcon className={size === "lg" && !label ? "h-[18px] w-[18px]" : "h-4 w-4"} />
+        {label}
+      </button>
+    </>
+  )
+}
+
+/**
+ * What a drag over the composer looks like. Drawn over the whole box rather than as a border
+ * tint: the question in a reader's head at that moment is "will this land?", and only something
+ * unambiguous answers it.
+ */
+export function FileDropOverlay() {
+  return (
+    <div className="pointer-events-none absolute inset-0 z-10 flex items-center justify-center rounded-lg border-2 border-dashed border-primary/60 bg-primary/[0.08] backdrop-blur-[1px]">
+      <span className="flex items-center gap-2 text-xs font-medium text-primary">
+        <PaperclipIcon className="h-4 w-4" />
+        Drop files to attach them
+      </span>
+    </div>
+  )
+}
+
+/** What is about to be sent. Tiles, not a gallery: the words are still the message. */
+export function AttachmentDraftStrip({ draft }: { draft: AttachmentDraft }) {
+  if (draft.files.length === 0 && draft.preparing === 0 && !draft.error) return null
+  return (
+    <div className="px-2 pt-2">
+      {draft.error && <p className="mb-1.5 text-[11px] text-destructive">{draft.error}</p>}
+      <div className="flex flex-wrap gap-1.5">
+        {draft.files.map((file) => (
+          <div
+            key={file.key}
+            className="group/att relative flex h-14 items-center overflow-hidden rounded-md border bg-muted"
+            title={`${file.name} · ${formatBytes(file.bytes)}`}
+          >
+            {file.previewUrl ? (
+              <img src={file.previewUrl} alt={file.name} className="h-14 w-14 object-cover" />
+            ) : (
+              // A file with no picture still has to be identifiable at a glance, so it shows the
+              // two things that identify it: what kind it is, and what it is called.
+              <div className="flex h-full max-w-48 items-center gap-2 bg-background px-2.5">
+                <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded bg-muted text-[9px] font-semibold text-muted-foreground">
+                  {fileKind(file.name, file.mediaType)}
+                </span>
+                <span className="min-w-0">
+                  <span className="block truncate text-[11px] font-medium">{file.name}</span>
+                  <span className="block text-[10px] text-muted-foreground">{formatBytes(file.bytes)}</span>
+                </span>
+              </div>
+            )}
+            <button
+              type="button"
+              onClick={() => draft.remove(file.key)}
+              aria-label={`Remove ${file.name}`}
+              className="absolute right-0.5 top-0.5 flex h-4 w-4 items-center justify-center rounded-full bg-background/90 text-muted-foreground opacity-0 transition-opacity hover:text-foreground group-hover/att:opacity-100 focus-visible:opacity-100"
+            >
+              <XIcon className="h-3 w-3" />
+            </button>
+          </div>
+        ))}
+        {draft.preparing > 0 && (
+          <div className="flex h-14 w-14 items-center justify-center rounded-md border border-dashed text-muted-foreground">
+            <Loader2Icon className="h-4 w-4 animate-spin" />
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ── Reading ───────────────────────────────────────────────────────────────────────────────────
+
+export function fileRefs(value: unknown): TaskFileRef[] {
+  if (!Array.isArray(value)) return []
+  return value.filter(
+    (v): v is TaskFileRef => !!v && typeof v === "object" && typeof (v as TaskFileRef).id === "string",
+  )
+}
+
+/**
+ * The attachments of one event, on the timeline.
+ *
+ * Fetched by id from a route whose answer never changes, so a stream polling every two seconds
+ * asks for each one exactly once however many times the event is re-rendered — which is the whole
+ * reason the bytes are not in the payload. `loading="lazy"` because a long session scrolled to its
+ * end has no business downloading the screenshots of an hour ago.
+ *
+ * Images get a thumbnail and a lightbox; everything else gets a row that downloads. That split is
+ * not a rendering preference — the API will not serve anything else with its own content type, so
+ * there is nothing else to draw.
+ */
+export function TaskFiles({
+  files,
+  attachmentUrl,
+  className,
+}: {
+  files: TaskFileRef[]
+  attachmentUrl: AttachmentUrl
+  className?: string
+}) {
+  const [open, setOpen] = useState<TaskFileRef | null>(null)
+  if (files.length === 0) return null
+  const images = files.filter((f) => isPreviewable(f.mediaType))
+  const others = files.filter((f) => !isPreviewable(f.mediaType))
+
+  return (
+    <>
+      {images.length > 0 && (
+        <div className={cn("mt-2 flex flex-wrap gap-2", className)}>
+          {images.map((file) => (
+            <button
+              key={file.id}
+              type="button"
+              onClick={() => setOpen(file)}
+              className="group/img block max-w-full overflow-hidden rounded-lg border bg-muted/40 transition-colors hover:border-primary/40"
+            >
+              <img
+                src={attachmentUrl(file.id)}
+                alt={file.filename ?? "Attached image"}
+                loading="lazy"
+                // Capped rather than full-bleed: on the rail a picture is a paragraph, not a page.
+                className="max-h-56 w-auto max-w-full object-contain"
+              />
+            </button>
+          ))}
+        </div>
+      )}
+
+      {others.length > 0 && (
+        <div className={cn("mt-2 flex flex-col gap-1.5", className)}>
+          {others.map((file) => (
+            <a
+              key={file.id}
+              href={attachmentUrl(file.id)}
+              // The API answers these with `Content-Disposition: attachment`, so this saves rather
+              // than navigates; the attribute is what gives the browser the name to save under
+              // before it has seen a single header.
+              download={file.filename ?? undefined}
+              className="group/file flex max-w-sm items-center gap-2.5 rounded-lg border bg-card px-2.5 py-2 transition-colors hover:border-primary/40 hover:bg-muted/50"
+            >
+              <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded bg-muted text-[9px] font-semibold text-muted-foreground">
+                {fileKind(file.filename ?? "", file.mediaType)}
+              </span>
+              <span className="min-w-0 flex-1">
+                <span className="block truncate text-xs font-medium">{file.filename ?? "Attachment"}</span>
+                <span className="block text-[10px] text-muted-foreground">{formatBytes(file.bytes)}</span>
+              </span>
+              <DownloadIcon className="h-3.5 w-3.5 shrink-0 text-muted-foreground/60 transition-colors group-hover/file:text-foreground" />
+            </a>
+          ))}
+        </div>
+      )}
+
+      {open && (
+        <FileLightbox
+          src={attachmentUrl(open.id)}
+          name={open.filename}
+          bytes={open.bytes}
+          onClose={() => setOpen(null)}
+        />
+      )}
+    </>
+  )
+}
+
+/**
+ * Full size, over everything.
+ *
+ * Deliberately not the `Dialog` primitive: this has no title, no description and no actions — it
+ * is one picture, and everything a dialog would frame it with is chrome between the reader and
+ * the thing they clicked. Escape and a click anywhere close it, which is what every viewer has
+ * trained for.
+ *
+ * **Portalled to `body`, and that is not a detail.** The timeline is virtualized, so every row
+ * sits under a `transform: translateY(…)` — and a transformed ancestor becomes the containing
+ * block of its `position: fixed` descendants. Rendered in place, "over everything" turned out to
+ * mean "over that one row", which is exactly what it looked like: a postage stamp inside the
+ * transcript. Mounted on the body there is no ancestor left to be trapped by.
+ */
+function FileLightbox({
+  src,
+  name,
+  bytes,
+  onClose,
+}: {
+  src: string
+  name: string | null
+  bytes: number
+  onClose: () => void
+}) {
+  const container = useOverlayContainer()
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose()
+    window.addEventListener("keydown", onKey)
+    return () => window.removeEventListener("keydown", onKey)
+  }, [onClose])
+
+  // Into the SpuntoProvider's overlay container when there is one (themed tree), `body` otherwise.
+  // Above `z-[120]`: the phone cockpit is itself a layer at that height.
+  //
+  // No "is this the client yet?" guard: nothing renders this until someone clicks a thumbnail, so
+  // it never exists during SSR or on the hydrating render, and `document` is always there by then.
+  return createPortal(
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={name ?? "Attached image"}
+      onClick={onClose}
+      className="fixed inset-0 z-[140] flex items-center justify-center bg-background/90 p-4 backdrop-blur-sm"
+    >
+      <img
+        src={src}
+        alt={name ?? "Attached image"}
+        onClick={(e) => e.stopPropagation()}
+        className="max-h-full max-w-full rounded-lg object-contain shadow-lg"
+      />
+      <div className="absolute right-3 top-3 flex items-center gap-2">
+        <span className="max-w-xs truncate rounded-full bg-background/80 px-2 py-1 text-[11px] text-muted-foreground">
+          {name ? `${name} · ${formatBytes(bytes)}` : formatBytes(bytes)}
+        </span>
+        <a
+          href={src}
+          target="_blank"
+          rel="noreferrer"
+          onClick={(e) => e.stopPropagation()}
+          className="rounded-full bg-background/80 px-2 py-1 text-[11px] text-muted-foreground hover:text-foreground"
+        >
+          Open
+        </a>
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label="Close"
+          className="flex h-7 w-7 items-center justify-center rounded-full bg-background/80 text-muted-foreground hover:text-foreground"
+        >
+          <XIcon className="h-4 w-4" />
+        </button>
+      </div>
+    </div>,
+    container ?? document.body,
+  )
+}