@object-ui/fields 16.0.0 → 17.1.0

package/src/widgets/ImageField.tsx

@@ -1,8 +1,18 @@
 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,
+  readFileValues,
+  uploadResultView,
+  withRecentUploads,
+  type FileValueView,
+} from './file-value';
 
 // Lazy-load the cropper so the dialog (canvas + crop logic) is not in the initial
 // ImageField bundle. Consumers that never crop pay zero cost.
@@ -14,7 +24,7 @@ const ImageCropperDialog = lazy(() =>
  * ImageField - Image upload widget with preview thumbnails
  * Supports single and multiple image uploads with drag-and-drop and preview display
  */
-export function ImageField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
+export function ImageField({ value, onChange, field, readonly, onUploadingChange, ...props }: FieldWidgetProps<any>) {
   const inputRef = useRef<HTMLInputElement>(null);
   const imageField = (field || (props as any).schema) as any;
   const multiple = imageField?.multiple || false;
@@ -24,29 +34,97 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
    */
   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
+  // URL a thumbnail needs; these keep the preview visible until the next read
+  // returns the expanded form. See `file-value`.
+  const [recent, setRecent] = useState<Record<string, FileValueView>>({});
+  useUploadingSignal(uploading, onUploadingChange);
+
+  // Derived value + memoized handlers must run before the readonly early return
+  // so hook order stays stable across renders.
+  const images = value ? (Array.isArray(value) ? value : [value]) : [];
+  const views = withRecentUploads(readFileValues(value, 'Image'), recent);
+
+  const remember = useCallback((result: any, originalName: string) => {
+    const view = uploadResultView(result, originalName);
+    if (view.id) setRecent((prev) => ({ ...prev, [view.id as string]: view }));
+  }, []);
+
+  const handleCropConfirm = useCallback(
+    async (blob: Blob, name: string) => {
+      if (!cropTarget) return;
+      setUploading(true);
+      try {
+        const result = await upload(blob);
+        remember(result, name);
+        const next = fileValueForSubmit(result, name);
+        if (multiple) {
+          const updated = [...images];
+          updated[cropTarget.index] = next;
+          onChange(updated);
+        } else {
+          onChange(next);
+        }
+      } finally {
+        setUploading(false);
+        setCropTarget(null);
+      }
+    },
+    [cropTarget, images, multiple, onChange, upload, remember],
+  );
+
+  const openCropper = useCallback(
+    (index: number) => {
+      const img = views[index];
+      if (!img?.url) return;
+      setCropTarget({ index, src: img.url, name: img.name || `image-${index}.png` });
+    },
+    [views],
+  );
+
+  const lightboxImages = views.filter((v) => v.url).map((v) => ({ url: v.url as string, name: v.name }));
 
   if (readonly) {
-    if (!value) return <EmptyValue />;
-    
-    const images = Array.isArray(value) ? value : [value];
+    if (!value || lightboxImages.length === 0) return <EmptyValue />;
+
     return (
-      <div className="flex flex-wrap gap-2">
-        {images.map((img: any, idx: number) => (
-          <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>
+        )}
+      </>
     );
   }
 
-  const images = value ? (Array.isArray(value) ? value : [value]) : [];
-
   const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
     const selectedFiles = Array.from(e.target.files || []);
     if (selectedFiles.length === 0) return;
@@ -56,13 +134,8 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
       const imageObjects = await Promise.all(
         selectedFiles.map(async (file) => {
           const result = await upload(file);
-          return {
-            name: result.name,
-            original_name: file.name,
-            size: result.size,
-            mime_type: result.mimeType,
-            url: result.url,
-          };
+          remember(result, file.name);
+          return fileValueForSubmit(result, file.name);
         }),
       );
 
@@ -87,43 +160,6 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
     }
   };
 
-  const handleCropConfirm = useCallback(
-    async (blob: Blob, name: string) => {
-      if (!cropTarget) return;
-      setUploading(true);
-      try {
-        const result = await upload(blob);
-        const next = {
-          name: result.name || name,
-          original_name: name,
-          size: result.size,
-          mime_type: result.mimeType,
-          url: result.url,
-        };
-        if (multiple) {
-          const updated = [...images];
-          updated[cropTarget.index] = next;
-          onChange(updated);
-        } else {
-          onChange(next);
-        }
-      } finally {
-        setUploading(false);
-        setCropTarget(null);
-      }
-    },
-    [cropTarget, images, multiple, onChange, upload],
-  );
-
-  const openCropper = useCallback(
-    (index: number) => {
-      const img = images[index];
-      if (!img?.url) return;
-      setCropTarget({ index, src: img.url, name: img.name || `image-${index}.png` });
-    },
-    [images],
-  );
-
   return (
     <div className={props.className}>
       <input
@@ -136,13 +172,13 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
       />
       
       <div className="space-y-2">
-        {images.length > 0 && (
+        {views.length > 0 && (
           <div className="grid grid-cols-4 gap-2">
-            {images.map((img: any, idx: number) => (
+            {views.map((img, idx) => (
               <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">
@@ -153,7 +189,7 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
                       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" />
@@ -165,6 +201,7 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
                     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>
@@ -187,7 +224,11 @@ export function ImageField({ value, onChange, field, readonly, ...props }: Field
           ) : (
             <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>
 

package/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
+  });
+});

package/src/widgets/ImageLightbox.tsx

@@ -0,0 +1,108 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import * as React from 'react';
+import { Dialog, DialogContent, DialogTitle } from '@object-ui/components';
+import { useObjectTranslation } from '@object-ui/i18n';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+
+export interface LightboxImage {
+  url: string;
+  name?: string;
+}
+
+export interface ImageLightboxProps {
+  images: LightboxImage[];
+  /** Index of the image shown when the lightbox opens. */
+  index: number;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Called when the user navigates to another image (prev/next, arrow keys). */
+  onIndexChange?: (index: number) => void;
+}
+
+/**
+ * Full-screen image preview with prev/next navigation for a set of images.
+ *
+ * Controlled: the caller owns `open` and the current `index`. Built on the
+ * shared `Dialog`, so backdrop-click and Escape close it for free; this adds
+ * left/right arrow-key navigation and a position counter for the multi-image
+ * case. A single image simply omits the arrows and counter.
+ */
+export function ImageLightbox({ images, index, open, onOpenChange, onIndexChange }: ImageLightboxProps) {
+  const { t } = useObjectTranslation();
+  const count = images.length;
+  const current = images[index];
+
+  const go = React.useCallback(
+    (delta: number) => {
+      if (count <= 1) return;
+      const next = (index + delta + count) % count;
+      onIndexChange?.(next);
+    },
+    [count, index, onIndexChange],
+  );
+
+  const handleKeyDown = React.useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'ArrowRight') {
+        e.preventDefault();
+        go(1);
+      } else if (e.key === 'ArrowLeft') {
+        e.preventDefault();
+        go(-1);
+      }
+    },
+    [go],
+  );
+
+  if (!current) return null;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        className="max-w-[92vw] sm:max-w-4xl p-0 bg-transparent border-0 shadow-none"
+        onKeyDown={handleKeyDown}
+      >
+        {/* Title is required for a labelled dialog but visually redundant here. */}
+        <DialogTitle className="sr-only">{current.name || t('fields.image.preview')}</DialogTitle>
+        <div className="relative flex items-center justify-center">
+          <img
+            src={current.url}
+            alt={current.name || t('fields.image.imageAlt', { index: index + 1 })}
+            className="max-h-[85vh] max-w-full rounded-md object-contain"
+          />
+
+          {count > 1 && (
+            <>
+              <button
+                type="button"
+                onClick={() => go(-1)}
+                aria-label={t('fields.image.previous')}
+                className="absolute left-2 top-1/2 -translate-y-1/2 flex size-9 items-center justify-center rounded-full bg-black/50 text-white hover:bg-black/70 transition-colors"
+              >
+                <ChevronLeft className="size-5" />
+              </button>
+              <button
+                type="button"
+                onClick={() => go(1)}
+                aria-label={t('fields.image.next')}
+                className="absolute right-2 top-1/2 -translate-y-1/2 flex size-9 items-center justify-center rounded-full bg-black/50 text-white hover:bg-black/70 transition-colors"
+              >
+                <ChevronRight className="size-5" />
+              </button>
+              <div className="absolute bottom-2 left-1/2 -translate-x-1/2 rounded-full bg-black/50 px-2.5 py-1 text-xs font-medium text-white">
+                {t('fields.image.counter', { current: index + 1, total: count })}
+              </div>
+            </>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/widgets/LookupField.hydration.test.tsx

@@ -0,0 +1,136 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Regression (#3108): a multi-value lookup hydrated its committed ids with a
+ * SERIAL `findOne` per id — 41 selected users meant 41 sequential round-trips,
+ * during which the trigger rendered the bare "Select…" placeholder,
+ * indistinguishable from having no value at all.
+ *
+ * Fixed behaviour under test:
+ *  1. unresolved ids are fetched in ONE batched `$in` query (chunked), not
+ *     one findOne per id;
+ *  2. while hydration is in flight the trigger shows a loading indicator and
+ *     the committed-value count instead of the empty placeholder;
+ *  3. the loading state settles (falls back to placeholder) when hydration
+ *     fails, instead of spinning forever.
+ */
+
+import * as React from 'react';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup, waitFor, screen } from '@testing-library/react';
+import { LookupField } from './LookupField';
+
+afterEach(cleanup);
+
+const USERS = [
+  { id: 'u1', name: 'Ada Lovelace' },
+  { id: 'u2', name: 'Grace Hopper' },
+  { id: 'u3', name: 'Margaret Hamilton' },
+];
+
+describe('LookupField — multi-value hydration batches and shows loading (#3108)', () => {
+  it('hydrates several ids with one $in query instead of a findOne per id', async () => {
+    const find = vi.fn(async (_obj: string, params: any) => {
+      const wanted: any[] = params?.$filter?.id?.$in ?? [];
+      return { data: USERS.filter((u) => wanted.includes(u.id)) };
+    });
+    const findOne = vi.fn(async () => null);
+    render(
+      <LookupField
+        value={['u1', 'u2', 'u3']}
+        onChange={() => {}}
+        dataSource={{ find, findOne } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+
+    await waitFor(() => expect(screen.getByText('Ada Lovelace')).toBeTruthy());
+    expect(screen.getByText('Grace Hopper')).toBeTruthy();
+    expect(screen.getByText('Margaret Hamilton')).toBeTruthy();
+
+    // One batched round-trip, zero per-id GETs.
+    expect(findOne).not.toHaveBeenCalled();
+    const hydrationCalls = find.mock.calls.filter((c) => c[1]?.$filter?.id?.$in);
+    expect(hydrationCalls).toHaveLength(1);
+    expect(hydrationCalls[0][1].$filter.id.$in).toEqual(['u1', 'u2', 'u3']);
+  });
+
+  it('shows the committed count + spinner while hydration is in flight, never the empty placeholder', async () => {
+    let resolveFind!: (v: any) => void;
+    const find = vi.fn(
+      () => new Promise((resolve) => { resolveFind = resolve; }),
+    );
+    render(
+      <LookupField
+        value={['u1', 'u2', 'u3']}
+        onChange={() => {}}
+        dataSource={{ find } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+
+    // In-flight: loading indicator + raw committed count, no "Select…".
+    await waitFor(() => expect(screen.getByTestId('lookup-hydrating')).toBeTruthy());
+    expect(screen.queryByText('Select...')).toBeNull();
+    expect(screen.getByText(/3/)).toBeTruthy();
+
+    resolveFind({ data: USERS });
+    await waitFor(() => expect(screen.getByText('Ada Lovelace')).toBeTruthy());
+    expect(screen.queryByTestId('lookup-hydrating')).toBeNull();
+  });
+
+  it('settles (no infinite spinner) when the hydration fetch fails', async () => {
+    const find = vi.fn(async (_obj: string, params: any) => {
+      if (params?.$filter?.id?.$in) throw new Error('boom');
+      return { data: [] };
+    });
+    render(
+      <LookupField
+        value={['u1', 'u2']}
+        onChange={() => {}}
+        dataSource={{ find } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+
+    await waitFor(() => expect(find).toHaveBeenCalled());
+    // The failed attempt is marked settled — the spinner clears instead of
+    // spinning forever (pre-existing fallback: unresolvable ids drop).
+    await waitFor(() => expect(screen.queryByTestId('lookup-hydrating')).toBeNull());
+  });
+
+  it('readonly mode shows the loading count instead of an empty value while hydrating', async () => {
+    let resolveFind!: (v: any) => void;
+    const find = vi.fn(
+      () => new Promise((resolve) => { resolveFind = resolve; }),
+    );
+    render(
+      <LookupField
+        value={['u1', 'u2']}
+        onChange={() => {}}
+        readonly
+        dataSource={{ find } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+
+    await waitFor(() => expect(screen.getByTestId('lookup-hydrating')).toBeTruthy());
+
+    resolveFind({ data: USERS.slice(0, 2) });
+    await waitFor(() => expect(screen.getByText('Ada Lovelace')).toBeTruthy());
+  });
+
+  it('keeps the cheap findOne GET for a single unresolved primary id', async () => {
+    const find = vi.fn(async () => ({ data: [] }));
+    const findOne = vi.fn(async () => ({ id: 'u1', name: 'Ada' }));
+    render(
+      <LookupField
+        value={['u1']}
+        onChange={() => {}}
+        dataSource={{ find, findOne } as never}
+        field={{ reference_to: 'sys_user', multiple: true } as never}
+      />,
+    );
+    await waitFor(() => expect(findOne).toHaveBeenCalledWith('sys_user', 'u1'));
+  });
+});

package/src/widgets/LookupField.idField.test.tsx

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Regression (objectstack #3508): a lookup whose committed value is NOT the
+ * primary id (`id_field: 'name'` — e.g. approval `position` approvers, which
+ * the engine routes by machine name) must hydrate its display label by
+ * FILTERING on that field. The old path always called `findOne(object, value)`
+ * — a primary-id GET — so a stored machine name never resolved and the field
+ * showed an empty placeholder over a real value.
+ */
+
+import * as React from 'react';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup, waitFor } from '@testing-library/react';
+import { LookupField } from './LookupField';
+
+afterEach(cleanup);
+
+describe('LookupField — id_field hydration (#3508)', () => {
+  it('hydrates by filtering on id_field when it is not the primary id', async () => {
+    const find = vi.fn(async () => ({
+      data: [{ id: 'pos_1', name: 'sales_manager', label: 'Sales Manager' }],
+    }));
+    const findOne = vi.fn(async () => null);
+    render(
+      <LookupField
+        value="sales_manager"
+        onChange={() => {}}
+        dataSource={{ find, findOne } as never}
+        field={{
+          reference_to: 'sys_position',
+          id_field: 'name',
+          display_field: 'label',
+          multiple: false,
+        } as never}
+      />,
+    );
+    await waitFor(() => expect(find).toHaveBeenCalled());
+    // The stored machine name is not a primary id — findOne(object, name)
+    // would 404; hydration must go through $filter on the committed field.
+    expect(findOne).not.toHaveBeenCalled();
+    const hydration = find.mock.calls.find(
+      (c) => (c as unknown[])[1] && ((c as never[])[1] as { $filter?: Record<string, unknown> }).$filter?.name === 'sales_manager',
+    );
+    expect(hydration).toBeTruthy();
+  });
+
+  it('keeps findOne hydration for the default primary-id lookup', async () => {
+    const find = vi.fn(async () => ({ data: [] }));
+    const findOne = vi.fn(async () => ({ id: 'u1', name: 'Ada' }));
+    render(
+      <LookupField
+        value="u1"
+        onChange={() => {}}
+        dataSource={{ find, findOne } as never}
+        field={{ reference_to: 'sys_user', multiple: false } as never}
+      />,
+    );
+    await waitFor(() => expect(findOne).toHaveBeenCalledWith('sys_user', 'u1'));
+  });
+});