fix(fields): consistent image-field rendering + click-to-zoom (#2836) (#2837)

Resolve a bare `sys_file` id to the stable download URL so edit-form and
inline-edit thumbnails no longer render broken; route file-backed types
through their upload widgets in inline edit instead of a raw-URL text input;
localize ImageField strings; add an ImageLightbox for click-to-enlarge with
single/multiple support.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: baozhoutao

.changeset/image-field-display-zoom.md

@@ -0,0 +1,29 @@
+---
+"@object-ui/fields": patch
+"@object-ui/plugin-detail": patch
+"@object-ui/i18n": patch
+---
+
+fix(fields): render `image` fields consistently and add click-to-zoom (#2836)
+
+An `image` field rendered differently — and wrongly — on three surfaces:
+
+- **Edit form showed broken thumbnails.** A record read back its `image` value
+  as a bare `sys_file` id (the reference form), but `readFileValue` returned an
+  id with no URL — the comment assumed the read path expands it, which the
+  edit-form data path does not. The result was `<img src="">`. `file-value` now
+  derives the stable download URL (`/api/v1/storage/files/:id`, which
+  302-redirects to a signed URL and works directly as `<img src>`) for a bare
+  id or an id-only object, so every widget and cell renderer resolves one.
+- **Inline edit leaked the raw storage URL.** `InlineFieldInput` had no branch
+  for file-backed types and fell through to a plain text input showing
+  `/api/v1/storage/files/…`. It now renders the same upload widgets the form
+  uses (`image`/`avatar`/`signature`/`file`/`video`/`audio`).
+- **Hard-coded English.** `ImageField`'s upload/crop/remove/alt strings now go
+  through `t('fields.image.*')` (en + zh added).
+
+Also adds an `ImageLightbox` — click a read-only thumbnail (detail or list cell)
+to open a full-screen preview; multiple images get prev/next navigation, a
+position counter and arrow-key support, a single image just the image. In a
+grid cell the click is `stopPropagation`-guarded so enlarging doesn't also open
+the row.

packages/fields/src/index.tsx

@@ -303,6 +303,8 @@ import { PercentField } from './widgets/PercentField';
 import { PasswordField } from './widgets/PasswordField';
 import { FileField } from './widgets/FileField';
 import { ImageField } from './widgets/ImageField';
+import { ImageLightbox } from './widgets/ImageLightbox';
+import { readFileValues } from './widgets/file-value';
 import { LocationField } from './widgets/LocationField';
 import { FormulaField } from './widgets/FormulaField';
 import { SummaryField } from './widgets/SummaryField';
@@ -1268,50 +1270,88 @@ export function FileCellRenderer({ value, field }: CellRendererProps): React.Rea
 }
 
 /**
- * Image field cell renderer (with thumbnails)
+ * Image field cell renderer (with thumbnails + click-to-zoom).
+ *
+ * An image value may be a plain URL string, an object ({ url | src | href … }),
+ * a bare `sys_file` id, or an array of any of those. Normalising through
+ * `readFileValues` (which resolves a bare id to its stable download URL) means
+ * a string-URL field, a CDN link, and an unexpanded reference all render a
+ * thumbnail instead of a broken `<img src="">` placeholder.
+ *
+ * Clicking a thumbnail opens a full-screen lightbox (single or gallery). The
+ * click is `stopPropagation`-guarded so, inside a grid row, enlarging an image
+ * doesn't also trigger row navigation.
  */
 export function ImageCellRenderer({ value }: CellRendererProps): React.ReactElement {
-  if (!value) return <EmptyValue />;
+  const { t } = useObjectTranslation();
+  const [lightboxIndex, setLightboxIndex] = React.useState<number | null>(null);
+
+  const imgs = React.useMemo(
+    () =>
+      readFileValues(value, 'Image')
+        .filter((v) => v.url)
+        .map((v) => ({ url: v.url as string, name: v.name })),
+    [value],
+  );
 
-  // An image value may be a plain URL string, an object ({ url | src | href }),
-  // or an array of either. Normalize so a string-URL field (common — e.g. a
-  // `cover` seeded with a CDN link) renders a thumbnail instead of a broken
-  // <img src=""> placeholder.
-  const urlOf = (v: any): string =>
-    typeof v === 'string' ? v : (v?.url || v?.src || v?.href || v?.thumbnailUrl || '');
-  const nameOf = (v: any, fallback: string): string =>
-    (v && typeof v === 'object' && (v.name || v.original_name)) || fallback;
+  if (!value || imgs.length === 0) return <EmptyValue />;
 
-  if (Array.isArray(value)) {
-    const imgs = value.map((v) => ({ url: urlOf(v), name: nameOf(v, 'Image') })).filter((i) => i.url);
-    if (imgs.length === 0) return <EmptyValue />;
+  const imageAlt = (idx: number, name?: string) =>
+    name || t('fields.image.imageAlt', { index: idx + 1 });
+  const open = (idx: number) => (e: React.MouseEvent) => {
+    e.stopPropagation();
+    setLightboxIndex(idx);
+  };
+  const multiple = imgs.length > 1;
+
+  const lightbox = lightboxIndex !== null && (
+    <ImageLightbox
+      images={imgs}
+      index={lightboxIndex}
+      open
+      onOpenChange={(o) => !o && setLightboxIndex(null)}
+      onIndexChange={setLightboxIndex}
+    />
+  );
+
+  if (multiple) {
     return (
-      <div className="flex -space-x-2">
-        {imgs.slice(0, 3).map((img, idx) => (
-          <img
-            key={idx}
-            src={img.url}
-            alt={img.name || `Image ${idx + 1}`}
-            className="size-8 rounded-md border-2 border-white object-cover"
-          />
-        ))}
-        {imgs.length > 3 && (
-          <div className="size-8 rounded-md border-2 border-white bg-gray-100 flex items-center justify-center text-xs font-medium text-gray-600">
-            +{imgs.length - 3}
-          </div>
-        )}
-      </div>
+      <>
+        <div className="flex -space-x-2">
+          {imgs.slice(0, 3).map((img, idx) => (
+            <img
+              key={idx}
+              src={img.url}
+              alt={imageAlt(idx, img.name)}
+              onClick={open(idx)}
+              className="size-8 cursor-zoom-in rounded-md border-2 border-background object-cover transition-transform hover:scale-110 hover:z-10"
+            />
+          ))}
+          {imgs.length > 3 && (
+            <button
+              type="button"
+              onClick={open(3)}
+              className="size-8 rounded-md border-2 border-background bg-muted flex items-center justify-center text-xs font-medium text-muted-foreground hover:bg-muted/80"
+            >
+              +{imgs.length - 3}
+            </button>
+          )}
+        </div>
+        {lightbox}
+      </>
     );
   }
 
-  const url = urlOf(value);
-  if (!url) return <EmptyValue />;
   return (
-    <img
-      src={url}
-      alt={nameOf(value, 'Image')}
-      className="size-10 rounded-md object-cover"
-    />
+    <>
+      <img
+        src={imgs[0].url}
+        alt={imageAlt(0, imgs[0].name)}
+        onClick={open(0)}
+        className="size-10 cursor-zoom-in rounded-md object-cover transition-transform hover:scale-105"
+      />
+      {lightbox}
+    </>
   );
 }
 

packages/fields/src/widgets/ImageField.tsx

@@ -1,8 +1,10 @@
 import React, { useRef, useState, useCallback, lazy, Suspense } from 'react';
 import { Button, EmptyValue } from '@object-ui/components';
 import { useUpload } from '@object-ui/providers';
-import { Upload, X, Image as ImageIcon, Crop as CropIcon, Loader2 } from 'lucide-react';
+import { useObjectTranslation } from '@object-ui/i18n';
+import { X, Image as ImageIcon, Crop as CropIcon, Loader2 } from 'lucide-react';
 import { FieldWidgetProps } from './types';
+import { ImageLightbox } from './ImageLightbox';
 import { useUploadingSignal } from './useUploadingSignal';
 import {
   fileValueForSubmit,
@@ -32,7 +34,9 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
    */
   const cropEnabled = imageField?.crop !== false;
   const [cropTarget, setCropTarget] = useState<{ index: number; src: string; name: string } | null>(null);
+  const [lightboxIndex, setLightboxIndex] = useState<number | null>(null);
   const { upload } = useUpload();
+  const { t } = useObjectTranslation();
   const [uploading, setUploading] = useState(false);
   // Display details of just-uploaded images, keyed by their new `sys_file` id.
   // Submitting the reference form means the field value no longer carries the
@@ -83,20 +87,41 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
     [views],
   );
 
+  const lightboxImages = views.filter((v) => v.url).map((v) => ({ url: v.url as string, name: v.name }));
+
   if (readonly) {
-    if (!value) return <EmptyValue />;
+    if (!value || lightboxImages.length === 0) return <EmptyValue />;
 
     return (
-      <div className="flex flex-wrap gap-2">
-        {views.map((img, idx) => (
-          <img
-            key={idx}
-            src={img.url || ''}
-            alt={img.name || `Image ${idx + 1}`}
-            className="size-20 rounded-md object-cover border border-gray-200"
+      <>
+        <div className="flex flex-wrap gap-2">
+          {lightboxImages.map((img, idx) => (
+            <button
+              key={idx}
+              type="button"
+              onClick={() => setLightboxIndex(idx)}
+              className="group relative overflow-hidden rounded-md border border-border focus:outline-none focus:ring-2 focus:ring-ring"
+              aria-label={t('fields.image.enlarge', { name: img.name || t('fields.image.imageAlt', { index: idx + 1 }) })}
+            >
+              <img
+                src={img.url}
+                alt={img.name || t('fields.image.imageAlt', { index: idx + 1 })}
+                className="size-20 object-cover transition-transform duration-150 group-hover:scale-105"
+              />
+              <span className="pointer-events-none absolute inset-0 bg-black/0 transition-colors group-hover:bg-black/10" />
+            </button>
+          ))}
+        </div>
+        {lightboxIndex !== null && (
+          <ImageLightbox
+            images={lightboxImages}
+            index={lightboxIndex}
+            open
+            onOpenChange={(o) => !o && setLightboxIndex(null)}
+            onIndexChange={setLightboxIndex}
           />
-        ))}
-      </div>
+        )}
+      </>
     );
   }
 
@@ -153,7 +178,7 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
               <div key={idx} className="relative group">
                 <img
                   src={img.url || ''}
-                  alt={img.name || `Image ${idx + 1}`}
+                  alt={img.name || t('fields.image.imageAlt', { index: idx + 1 })}
                   className="size-20 rounded-md object-cover border border-gray-200"
                 />
                 <div className="absolute top-1 right-1 flex gap-1 opacity-0 group-hover:opacity-100 transition-opacity">
@@ -164,7 +189,7 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
                       size="sm"
                       onClick={() => openCropper(idx)}
                       className="h-6 w-6 p-0"
-                      aria-label={`Crop image ${idx + 1}`}
+                      aria-label={t('fields.image.crop', { index: idx + 1 })}
                       data-testid={`image-field-crop-${idx}`}
                     >
                       <CropIcon className="size-3" />
@@ -176,6 +201,7 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
                     size="sm"
                     onClick={() => handleRemove(idx)}
                     className="h-6 w-6 p-0"
+                    aria-label={t('fields.image.remove', { index: idx + 1 })}
                   >
                     <X className="size-3" />
                   </Button>
@@ -198,7 +224,11 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
           ) : (
             <ImageIcon className="size-4 mr-2" />
           )}
-          {uploading ? 'Uploading…' : images.length > 0 ? 'Add More Images' : 'Upload Image'}
+          {uploading
+            ? t('fields.image.uploading')
+            : images.length > 0
+              ? t('fields.image.addMore')
+              : t('fields.image.upload')}
         </Button>
       </div>
 

packages/fields/src/widgets/ImageLightbox.test.tsx

@@ -0,0 +1,52 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { I18nProvider } from '@object-ui/i18n';
+import { ImageLightbox, type ImageLightboxProps } from './ImageLightbox';
+
+const imgs = [
+  { url: '/api/v1/storage/files/a', name: 'a.png' },
+  { url: '/api/v1/storage/files/b', name: 'b.png' },
+  { url: '/api/v1/storage/files/c', name: 'c.png' },
+];
+
+const renderLightbox = (props: ImageLightboxProps) =>
+  render(
+    <I18nProvider config={{ defaultLanguage: 'en', detectBrowserLanguage: false }}>
+      <ImageLightbox {...props} />
+    </I18nProvider>,
+  );
+
+describe('ImageLightbox', () => {
+  it('renders the image at the requested index', () => {
+    renderLightbox({ images: imgs, index: 1, open: true, onOpenChange: () => {} });
+    const img = screen.getByRole('img') as HTMLImageElement;
+    expect(img.src).toContain('/api/v1/storage/files/b');
+  });
+
+  it('shows navigation and a position counter for multiple images', () => {
+    renderLightbox({ images: imgs, index: 0, open: true, onOpenChange: () => {} });
+    expect(screen.getByText('1 / 3')).toBeInTheDocument();
+    expect(screen.getByLabelText('Next image')).toBeInTheDocument();
+    expect(screen.getByLabelText('Previous image')).toBeInTheDocument();
+  });
+
+  it('omits navigation for a single image', () => {
+    renderLightbox({ images: [imgs[0]], index: 0, open: true, onOpenChange: () => {} });
+    expect(screen.queryByLabelText('Next image')).not.toBeInTheDocument();
+    expect(screen.queryByText('1 / 1')).not.toBeInTheDocument();
+  });
+
+  it('advances to the next image and wraps around', () => {
+    const seen: number[] = [];
+    renderLightbox({ images: imgs, index: 2, open: true, onOpenChange: () => {}, onIndexChange: (i) => seen.push(i) });
+    fireEvent.click(screen.getByLabelText('Next image'));
+    expect(seen).toEqual([0]); // wrapped 2 -> 0
+  });
+
+  it('steps to the previous image and wraps around', () => {
+    const seen: number[] = [];
+    renderLightbox({ images: imgs, index: 0, open: true, onOpenChange: () => {}, onIndexChange: (i) => seen.push(i) });
+    fireEvent.click(screen.getByLabelText('Previous image'));
+    expect(seen).toEqual([2]); // wrapped 0 -> 2
+  });
+});