@stigmer/react 3.9.0 → 3.11.0

package/src/attachment/AttachmentChipList.tsx

@@ -1,9 +1,12 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useState } from "react";
 import { cn } from "@stigmer/theme";
 import type { AttachmentEntry } from "./useAttachments.js";
 import { formatFileSize } from "./attachment-utils.js";
+import { useObjectUrl } from "./useObjectUrl.js";
+import { AttachmentImageLightbox } from "./AttachmentImageLightbox.js";
+import { UNSTYLED_BUTTON } from "../internal/form-primitives.js";
 
 /** Props for {@link AttachmentChipList}. */
 export interface AttachmentChipListProps {
@@ -13,15 +16,27 @@ export interface AttachmentChipListProps {
   readonly onRemove: (id: string) => void;
   /** Retry callback for failed uploads (by entry ID). */
   readonly onRetry: (id: string) => void;
-  /** Disables remove and retry actions. */
+  /**
+   * Called when the user clicks an image chip's preview target. When
+   * provided, it **replaces** the built-in lightbox — platform builders
+   * route the click to their own viewer. Omit for the default behavior:
+   * a full-size image lightbox over the locally-held file bytes.
+   */
+  readonly onPreview?: (entry: AttachmentEntry) => void;
+  /** Disables remove and retry actions. Preview stays active — it is read-only. */
   readonly disabled?: boolean;
   /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
 
 /**
- * Renders a horizontal list of compact attachment chips showing
- * filename, size, upload status, and remove/retry actions.
+ * Renders a horizontal list of attachment chips: image attachments as
+ * preview-only thumbnail tiles (the image IS the chip — no filename
+ * text; visible from the moment of paste, through upload, and on error
+ * — stigmer/stigmer#371, #372), other files as compact filename chips.
+ * Filename, size, and upload status stay available on every chip via
+ * the tooltip and the accessible label; clicking an image tile opens
+ * the full image.
  *
  * Designed to sit between the context chips and toolbar in
  * {@link SessionComposer}, but usable standalone by platform builders
@@ -48,82 +63,216 @@ export function AttachmentChipList({
   entries,
   onRemove,
   onRetry,
+  onPreview,
   disabled,
   className,
 }: AttachmentChipListProps) {
+  // The built-in lightbox tracks the previewed entry by ID (direct identity,
+  // never object reference), and the entry itself is derived from `entries`
+  // on render — so removing an attachment while its preview is open closes
+  // the lightbox without any effect-based synchronization.
+  const [previewId, setPreviewId] = useState<string | null>(null);
+  const previewEntry =
+    previewId !== null ? (entries.find((e) => e.id === previewId) ?? null) : null;
+
   if (entries.length === 0) return null;
 
   return (
-    <div
-      className={cn("flex flex-wrap gap-1.5", className)}
-      role="list"
-      aria-label="Attached files"
-    >
-      {entries.map((entry) => (
-        <AttachmentChip
-          key={entry.id}
-          entry={entry}
-          onRemove={() => onRemove(entry.id)}
-          onRetry={() => onRetry(entry.id)}
-          disabled={disabled}
+    <>
+      {/* items-center is load-bearing: image tiles (h-14) and file chips
+          (~h-6) share this row, and flexbox's default stretch alignment
+          would balloon the file chips to tile height. */}
+      <div
+        className={cn("stg:flex stg:flex-wrap stg:items-center stg:gap-1.5", className)}
+        role="list"
+        aria-label="Attached files"
+      >
+        {entries.map((entry) => (
+          <AttachmentChip
+            key={entry.id}
+            entry={entry}
+            onRemove={() => onRemove(entry.id)}
+            onRetry={() => onRetry(entry.id)}
+            onPreview={
+              onPreview
+                ? () => onPreview(entry)
+                : () => setPreviewId(entry.id)
+            }
+            disabled={disabled}
+          />
+        ))}
+      </div>
+      {/* The lightbox mounts OUTSIDE the role="list" container (and outside
+          any chip): a <dialog> is not valid inside the chips' <span>
+          elements, and a non-listitem child inside the list would break its
+          accessibility ownership. One instance serves the whole list. */}
+      {previewEntry && (
+        <ChipPreviewLightbox
+          entry={previewEntry}
+          onClose={() => setPreviewId(null)}
         />
-      ))}
-    </div>
+      )}
+    </>
   );
 }
 
 // ---------------------------------------------------------------------------
-// Individual chip
+// Individual chip — dispatches on content type
 // ---------------------------------------------------------------------------
 
 function AttachmentChip({
   entry,
   onRemove,
   onRetry,
+  onPreview,
+  disabled,
+}: {
+  readonly entry: AttachmentEntry;
+  readonly onRemove: () => void;
+  readonly onRetry: () => void;
+  readonly onPreview: () => void;
+  readonly disabled?: boolean;
+}) {
+  return entry.contentType.startsWith("image/") ? (
+    <ImageAttachmentChip
+      entry={entry}
+      onRemove={onRemove}
+      onRetry={onRetry}
+      onPreview={onPreview}
+      disabled={disabled}
+    />
+  ) : (
+    <FileAttachmentChip
+      entry={entry}
+      onRemove={onRemove}
+      onRetry={onRetry}
+      disabled={disabled}
+    />
+  );
+}
+
+/** Shared accessible name: filename, size, and upload status. */
+function chipAriaLabel(entry: AttachmentEntry): string {
+  const isUploading = entry.phase === "uploading";
+  const isError = entry.phase === "error";
+  return `${entry.file.name}, ${formatFileSize(entry.file.size)}${isUploading ? ", uploading" : ""}${isError ? ", upload failed" : ""}`;
+}
+
+// ---------------------------------------------------------------------------
+// Image chip — a preview-only thumbnail tile (#371, #372)
+// ---------------------------------------------------------------------------
+
+/**
+ * The preview-only image tile: the thumbnail IS the chip. No filename
+ * text, no size caption — the image is its own identity (the grammar
+ * users know from Cursor/ChatGPT attachment tiles), while filename,
+ * size, and upload status stay one hover away in the tooltip and are
+ * always in the accessible label.
+ *
+ * The tile is alive through every upload phase (the spinner overlays
+ * the image during upload, never replaces it — the bytes are local, so
+ * the preview never waits on the network) and is one large click
+ * target that opens the full image. Remove is an always-visible corner
+ * badge — never hover-revealed, so it exists on touch devices and is
+ * discoverable without a pointer.
+ *
+ * On upload error the tile stays loud: destructive ring, dimmed image,
+ * and a centered Retry pill — failure never hides behind hover.
+ *
+ * If the file claims `image/*` but the browser can't decode it (corrupt,
+ * zero-byte), the chip degrades to the compact file-chip treatment — a
+ * generic icon and no preview affordance, never a broken-image glyph.
+ */
+function ImageAttachmentChip({
+  entry,
+  onRemove,
+  onRetry,
+  onPreview,
   disabled,
 }: {
   readonly entry: AttachmentEntry;
   readonly onRemove: () => void;
   readonly onRetry: () => void;
+  readonly onPreview: () => void;
   readonly disabled?: boolean;
 }) {
+  const url = useObjectUrl(entry.file);
+  const [loadFailed, setLoadFailed] = useState(false);
+
+  if (loadFailed) {
+    return (
+      <FileAttachmentChip
+        entry={entry}
+        onRemove={onRemove}
+        onRetry={onRetry}
+        disabled={disabled}
+      />
+    );
+  }
+
   const isError = entry.phase === "error";
   const isUploading = entry.phase === "uploading";
 
   return (
+    // The remove badge and retry pill are SIBLINGS of the preview button,
+    // absolutely positioned over it — buttons cannot nest inside buttons.
     <span
       role="listitem"
-      aria-label={`${entry.file.name}, ${formatFileSize(entry.file.size)}${isUploading ? ", uploading" : ""}${isError ? ", upload failed" : ""}`}
-      className={cn(
-        "inline-flex max-w-[200px] items-center gap-1 rounded-md px-2 py-0.5 text-xs",
-        isError
-          ? "border border-destructive/30 bg-destructive-subtle text-destructive"
-          : "bg-muted-subtle text-foreground",
-        isUploading && "opacity-70",
-      )}
+      aria-label={chipAriaLabel(entry)}
+      title={entry.file.name}
+      className="stg:relative stg:inline-flex"
     >
-      {isUploading && <ChipSpinner />}
-      {isError && <ErrorDot />}
-      {!isUploading && !isError &&
-        (entry.contentType.startsWith("image/") ? (
-          <ChipThumbnail file={entry.file} />
+      {/* The whole tile is the preview target. Preview stays enabled while
+          `disabled` (that prop gates the mutating remove/retry actions) and
+          in every phase: the object URL wraps in-memory bytes, no fetch.
+          UNSTYLED_BUTTON adds the pointer cursor — the image tile carries
+          no other clickability cue. */}
+      <button
+        type="button"
+        onClick={onPreview}
+        aria-label={`Preview ${entry.file.name}`}
+        className={cn(
+          UNSTYLED_BUTTON,
+          "stg:relative stg:block stg:h-14 stg:w-14 stg:overflow-hidden stg:rounded-md stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
+          isError && "stg:ring-1 stg:ring-destructive",
+        )}
+      >
+        {url ? (
+          <img
+            src={url}
+            alt=""
+            aria-hidden="true"
+            onError={() => setLoadFailed(true)}
+            className={cn(
+              "stg:h-full stg:w-full stg:object-cover",
+              (isUploading || isError) && "stg:opacity-50",
+            )}
+          />
         ) : (
-          <FileIcon />
-        ))}
-
-      <span className="truncate">{entry.file.name}</span>
-
-      <span className="shrink-0 text-[0.6rem] tabular-nums text-muted-foreground">
-        {formatFileSize(entry.file.size)}
-      </span>
+          // One-frame placeholder until the object-URL effect runs; same
+          // footprint as the image, so no layout shift.
+          <span
+            className="stg:block stg:h-full stg:w-full stg:animate-pulse stg:bg-muted"
+            aria-hidden="true"
+          />
+        )}
+        {isUploading && (
+          <span className="stg:absolute stg:inset-0 stg:flex stg:items-center stg:justify-center">
+            <ChipSpinner size={16} />
+          </span>
+        )}
+      </button>
 
       {isError && (
         <button
           type="button"
           onClick={onRetry}
           disabled={disabled}
-          className="shrink-0 text-[0.6rem] font-medium text-destructive underline hover:text-destructive-muted disabled:pointer-events-none"
           aria-label={`Retry uploading ${entry.file.name}`}
+          className={cn(
+            UNSTYLED_BUTTON,
+            "stg:absolute stg:left-1/2 stg:top-1/2 stg:-translate-x-1/2 stg:-translate-y-1/2 stg:rounded-full stg:bg-destructive stg:px-1.5 stg:py-0.5 stg:text-[0.6rem] stg:font-medium stg:leading-none stg:text-destructive-foreground stg:shadow-sm stg:hover:bg-destructive-hover stg:disabled:pointer-events-none",
+          )}
         >
           Retry
         </button>
@@ -133,8 +282,14 @@ function AttachmentChip({
         type="button"
         onClick={onRemove}
         disabled={disabled}
-        className="ml-0.5 shrink-0 text-muted-foreground hover:text-destructive disabled:pointer-events-none"
         aria-label={`Remove ${entry.file.name}`}
+        className={cn(
+          UNSTYLED_BUTTON,
+          // The established corner-badge geometry (ContextPopover,
+          // ComposerToolbar). Solid bg + border keep it legible over any
+          // image without opacity-modified tokens (Dont-Do #4).
+          "stg:absolute stg:-right-1.5 stg:-top-1.5 stg:flex stg:h-4 stg:w-4 stg:items-center stg:justify-center stg:rounded-full stg:border stg:border-border stg:bg-background stg:text-muted-foreground stg:shadow-sm stg:hover:text-destructive stg:disabled:pointer-events-none",
+        )}
       >
         <XIcon />
       </button>
@@ -143,39 +298,130 @@ function AttachmentChip({
 }
 
 // ---------------------------------------------------------------------------
-// Image thumbnail — a #284 ask: a pasted screenshot's chip shows the image,
-// not a generic file glyph
+// File chip — the compact treatment for non-image attachments
 // ---------------------------------------------------------------------------
 
-/**
- * Tiny preview of an image attachment, driven by an object URL over the
- * locally-held `File` (no fetch — the bytes are already in memory).
- *
- * The URL is created in an effect, not a memo: StrictMode double-invokes
- * memos and would leak the first URL without a revoke. The effect cleanup
- * revokes on removal, unmount, and file change. Until the effect runs (or
- * if it never gets a URL) the generic icon renders instead.
- *
- * `aria-hidden`: the chip's own `aria-label` already names the file; a
- * 16px thumbnail adds nothing for screen readers.
- */
-function ChipThumbnail({ file }: { readonly file: File }) {
-  const [url, setUrl] = useState<string | null>(null);
+function FileAttachmentChip({
+  entry,
+  onRemove,
+  onRetry,
+  disabled,
+}: {
+  readonly entry: AttachmentEntry;
+  readonly onRemove: () => void;
+  readonly onRetry: () => void;
+  readonly disabled?: boolean;
+}) {
+  const isError = entry.phase === "error";
+  const isUploading = entry.phase === "uploading";
+
+  return (
+    <span
+      role="listitem"
+      aria-label={chipAriaLabel(entry)}
+      className={cn(
+        "stg:inline-flex stg:max-w-[200px] stg:items-center stg:gap-1 stg:rounded-md stg:px-2 stg:py-0.5 stg:text-xs",
+        isError
+          ? "stg:border stg:border-destructive/30 stg:bg-destructive-subtle stg:text-destructive"
+          : "stg:bg-muted-subtle stg:text-foreground",
+        isUploading && "stg:opacity-70",
+      )}
+    >
+      {isUploading && <ChipSpinner />}
+      {isError && <ErrorDot />}
+      {!isUploading && !isError && <FileIcon />}
 
-  useEffect(() => {
-    const objectUrl = URL.createObjectURL(file);
-    setUrl(objectUrl);
-    return () => URL.revokeObjectURL(objectUrl);
-  }, [file]);
+      <span className="stg:truncate">{entry.file.name}</span>
 
-  if (!url) return <FileIcon />;
+      <span className="stg:shrink-0 stg:text-[0.6rem] stg:tabular-nums stg:text-muted-foreground">
+        {formatFileSize(entry.file.size)}
+      </span>
 
+      {isError && <RetryButton filename={entry.file.name} onRetry={onRetry} disabled={disabled} />}
+      <RemoveButton filename={entry.file.name} onRemove={onRemove} disabled={disabled} />
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Shared chip actions
+// ---------------------------------------------------------------------------
+
+function RetryButton({
+  filename,
+  onRetry,
+  disabled,
+}: {
+  readonly filename: string;
+  readonly onRetry: () => void;
+  readonly disabled?: boolean;
+}) {
   return (
-    <img
-      src={url}
-      alt=""
-      aria-hidden="true"
-      className="h-4 w-4 shrink-0 rounded-sm object-cover"
+    <button
+      type="button"
+      onClick={onRetry}
+      disabled={disabled}
+      className={cn(
+        UNSTYLED_BUTTON,
+        "stg:shrink-0 stg:text-[0.6rem] stg:font-medium stg:text-destructive stg:underline stg:hover:text-destructive-muted stg:disabled:pointer-events-none",
+      )}
+      aria-label={`Retry uploading ${filename}`}
+    >
+      Retry
+    </button>
+  );
+}
+
+function RemoveButton({
+  filename,
+  onRemove,
+  disabled,
+}: {
+  readonly filename: string;
+  readonly onRemove: () => void;
+  readonly disabled?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onRemove}
+      disabled={disabled}
+      className={cn(
+        UNSTYLED_BUTTON,
+        "stg:ml-0.5 stg:shrink-0 stg:text-muted-foreground stg:hover:text-destructive stg:disabled:pointer-events-none",
+      )}
+      aria-label={`Remove ${filename}`}
+    >
+      <XIcon />
+    </button>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Built-in lightbox mount
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridges the previewed entry to the dumb {@link AttachmentImageLightbox}:
+ * mounted only while a preview is open, so its object URL is created on
+ * open and revoked on close (independent of the chip's own URL, whose
+ * lifetime tracks the chip).
+ */
+function ChipPreviewLightbox({
+  entry,
+  onClose,
+}: {
+  readonly entry: AttachmentEntry;
+  readonly onClose: () => void;
+}) {
+  const src = useObjectUrl(entry.file);
+
+  return (
+    <AttachmentImageLightbox
+      src={src}
+      filename={entry.file.name}
+      open
+      onClose={onClose}
     />
   );
 }
@@ -184,17 +430,17 @@ function ChipThumbnail({ file }: { readonly file: File }) {
 // Inline SVG icons — kept minimal and consistent with SessionComposer icons
 // ---------------------------------------------------------------------------
 
-function ChipSpinner() {
+function ChipSpinner({ size = 10 }: { readonly size?: number }) {
   return (
     <svg
-      width="10"
-      height="10"
+      width={size}
+      height={size}
       viewBox="0 0 16 16"
       fill="none"
       stroke="currentColor"
       strokeWidth="2.5"
       strokeLinecap="round"
-      className="shrink-0 animate-spin text-muted-foreground"
+      className="stg:shrink-0 stg:animate-spin stg:text-muted-foreground"
       aria-hidden="true"
     >
       <path d="M8 2a6 6 0 1 0 6 6" />
@@ -205,7 +451,7 @@ function ChipSpinner() {
 function ErrorDot() {
   return (
     <span
-      className="inline-block h-1.5 w-1.5 shrink-0 rounded-full bg-destructive"
+      className="stg:inline-block stg:h-1.5 stg:w-1.5 stg:shrink-0 stg:rounded-full stg:bg-destructive"
       aria-hidden="true"
     />
   );
@@ -222,7 +468,7 @@ function FileIcon() {
       strokeWidth="1.5"
       strokeLinecap="round"
       strokeLinejoin="round"
-      className="shrink-0 text-muted-foreground"
+      className="stg:shrink-0 stg:text-muted-foreground"
       aria-hidden="true"
     >
       <path d="M8 1H4C3.45 1 3 1.45 3 2V12C3 12.55 3.45 13 4 13H10C10.55 13 11 12.55 11 12V4L8 1Z" />

package/src/attachment/AttachmentImageLightbox.tsx

@@ -0,0 +1,154 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+import { cn } from "@stigmer/theme";
+
+/** Props for {@link AttachmentImageLightbox}. */
+export interface AttachmentImageLightboxProps {
+  /**
+   * Image source URL. `null` for the first-paint frame before the caller's
+   * object URL exists — the lightbox shows a pulse placeholder, never a
+   * broken-image glyph.
+   */
+  readonly src: string | null;
+  /** Filename shown in the header and used as the image alt text. */
+  readonly filename: string;
+  /** Controls visibility. `true` opens the dialog via `showModal()`. */
+  readonly open: boolean;
+  /** Called when the lightbox should close (Escape, backdrop click, close button). */
+  readonly onClose: () => void;
+  /** Additional CSS classes for the dialog element. */
+  readonly className?: string;
+}
+
+/**
+ * Full-size image preview in a native `<dialog>` — the click-to-open target
+ * for composer attachment chips (stigmer/stigmer#371).
+ *
+ * A thin modal shell following the SDK's established dialog pattern
+ * ({@link ArtifactPreviewModal}): `showModal()`/`close()` driven by the
+ * `open` prop, Escape via the intercepted `cancel` event, focus trap and
+ * top layer native — no portal plumbing, no `@base-ui/react` dependency.
+ * Backdrop click closes via the canonical `e.target === dialog` check
+ * (clicks on content children never match the dialog element itself).
+ *
+ * Deliberately dumb (`src` + `filename`, no attachment types): liftable to
+ * `internal/` unchanged if other image surfaces (e.g. tool-output
+ * screenshots in `ResultView`) later want in-app preview instead of
+ * open-in-new-tab.
+ *
+ * The backdrop uses the `--stgm-backdrop` theme token ("modal backdrop
+ * overlay behind dialogs") rather than the `bg-black/50` hardcode found in
+ * older dialogs — the token is the designed value (Dont-Do #3).
+ */
+export function AttachmentImageLightbox({
+  src,
+  filename,
+  open,
+  onClose,
+  className,
+}: AttachmentImageLightboxProps) {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+
+    if (open && !dialog.open) {
+      dialog.showModal();
+    } else if (!open && dialog.open) {
+      dialog.close();
+    }
+  }, [open]);
+
+  // Escape arrives as the native `cancel` event; intercept it so the
+  // caller's `open` prop stays the single source of truth for visibility.
+  const handleCancel = useCallback(
+    (e: React.SyntheticEvent) => {
+      e.preventDefault();
+      onClose();
+    },
+    [onClose],
+  );
+
+  const handleBackdropClick = useCallback(
+    (e: React.MouseEvent<HTMLDialogElement>) => {
+      if (e.target === dialogRef.current) {
+        onClose();
+      }
+    },
+    [onClose],
+  );
+
+  return (
+    <dialog
+      ref={dialogRef}
+      onCancel={handleCancel}
+      onClick={handleBackdropClick}
+      aria-label={`Preview ${filename}`}
+      className={cn(
+        "stg:fixed stg:inset-0 stg:m-auto stg:max-h-[85vh] stg:max-w-[85vw] stg:rounded-lg stg:border stg:border-border stg:bg-background stg:p-0 stg:text-foreground stg:shadow-lg stg:outline-none",
+        "stg:backdrop:bg-backdrop",
+        className,
+      )}
+    >
+      {open && (
+        <div className="stg:flex stg:flex-col">
+          <div className="stg:flex stg:items-center stg:gap-2 stg:px-3 stg:py-2">
+            <span
+              className="stg:min-w-0 stg:flex-1 stg:truncate stg:text-xs stg:font-semibold stg:text-foreground"
+              title={filename}
+            >
+              {filename}
+            </span>
+            <button
+              type="button"
+              onClick={onClose}
+              aria-label="Close image preview"
+              className="stg:shrink-0 stg:cursor-pointer stg:rounded stg:p-0.5 stg:text-muted-foreground stg:transition-colors stg:hover:text-foreground stg:focus-visible:outline-none stg:focus-visible:ring-1 stg:focus-visible:ring-ring"
+            >
+              <CloseIcon />
+            </button>
+          </div>
+          <div className="stg:min-h-0 stg:overflow-auto stg:border-t stg:border-border">
+            {src ? (
+              <img
+                src={src}
+                alt={filename}
+                className="stg:block stg:max-h-[75vh] stg:max-w-full stg:object-contain"
+              />
+            ) : (
+              <div
+                className="stg:h-48 stg:w-72 stg:animate-pulse stg:bg-muted"
+                aria-hidden="true"
+              />
+            )}
+          </div>
+        </div>
+      )}
+    </dialog>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons (SDK pattern: no external icon dependency)
+// ---------------------------------------------------------------------------
+
+function CloseIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M3 3L11 11" />
+      <path d="M11 3L3 11" />
+    </svg>
+  );
+}