@object-ui/fields 11.2.0 → 11.4.0

package/src/widgets/PersonRow.tsx

@@ -0,0 +1,117 @@
+/**
+ * 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 React, { useEffect, useRef } from 'react';
+import { Avatar, AvatarFallback, AvatarImage, cn } from '@object-ui/components';
+import { Check } from 'lucide-react';
+import {
+  getPersonName,
+  getPersonInitials,
+  getPersonSubtitle,
+  getPersonAvatarUrl,
+  matchRanges,
+} from './personDisplay';
+
+/**
+ * A rich, single-line candidate row for the search-first PeoplePicker:
+ * avatar (image with initials fallback) + name + subtitle (department · email).
+ * The subtitle is what lets search stand in for an org tree — it disambiguates
+ * same-named people inline. The typed query is highlighted in both lines.
+ * Selectable/toggleable; a Check marks the selected state, and `active` reflects
+ * the keyboard cursor (scrolls itself into view).
+ */
+export interface PersonRowProps {
+  record: any;
+  displayField?: string;
+  subtitleFields?: string[];
+  avatarField?: string;
+  selected?: boolean;
+  /** Keyboard cursor is on this row — highlight + scroll into view. */
+  active?: boolean;
+  /** Typed search term; matches are highlighted in name + subtitle. */
+  highlightQuery?: string;
+  onSelect?: (record: any) => void;
+  className?: string;
+}
+
+/** Wrap literal matches of `query` in a subtle highlight. */
+function Highlighted({ text, query }: { text: string; query?: string }): React.ReactElement {
+  const ranges = query ? matchRanges(text, query) : [];
+  if (ranges.length === 0) return <>{text}</>;
+  const out: React.ReactNode[] = [];
+  let cursor = 0;
+  ranges.forEach(([start, end], i) => {
+    if (start > cursor) out.push(text.slice(cursor, start));
+    out.push(
+      <mark key={i} className="rounded-[2px] bg-primary/20 px-px text-inherit">
+        {text.slice(start, end)}
+      </mark>,
+    );
+    cursor = end;
+  });
+  if (cursor < text.length) out.push(text.slice(cursor));
+  return <>{out}</>;
+}
+
+export function PersonRow({
+  record,
+  displayField = 'name',
+  subtitleFields,
+  avatarField = 'image',
+  selected = false,
+  active = false,
+  highlightQuery,
+  onSelect,
+  className,
+}: PersonRowProps) {
+  const name = getPersonName(record, displayField);
+  const subtitle = getPersonSubtitle(record, subtitleFields);
+  const avatarUrl = getPersonAvatarUrl(record, avatarField);
+  const initials = getPersonInitials(name);
+
+  const ref = useRef<HTMLButtonElement>(null);
+  useEffect(() => {
+    // Optional-call the method too — jsdom doesn't implement scrollIntoView.
+    if (active) ref.current?.scrollIntoView?.({ block: 'nearest' });
+  }, [active]);
+
+  return (
+    <button
+      ref={ref}
+      type="button"
+      tabIndex={-1}
+      onClick={() => onSelect?.(record)}
+      aria-pressed={selected}
+      data-testid="person-row"
+      data-active={active || undefined}
+      className={cn(
+        'flex w-full items-center gap-3 rounded-md px-2 py-1.5 text-left transition-colors',
+        'hover:bg-accent focus-visible:outline-none',
+        selected && 'bg-accent',
+        active && 'bg-accent ring-1 ring-inset ring-ring',
+        className,
+      )}
+    >
+      <Avatar className="size-9 shrink-0">
+        {avatarUrl && <AvatarImage src={avatarUrl} alt={name} />}
+        <AvatarFallback className="text-xs">{initials}</AvatarFallback>
+      </Avatar>
+      <div className="min-w-0 flex-1">
+        <div className="truncate text-sm font-medium">
+          {name ? <Highlighted text={name} query={highlightQuery} /> : '—'}
+        </div>
+        {subtitle && (
+          <div className="truncate text-xs text-muted-foreground">
+            <Highlighted text={subtitle} query={highlightQuery} />
+          </div>
+        )}
+      </div>
+      {selected && <Check className="size-4 shrink-0 text-primary" aria-hidden />}
+    </button>
+  );
+}

package/src/widgets/RecordPickerDialog.tsx

@@ -37,8 +37,9 @@ import {
   SlidersHorizontal,
   X,
 } from 'lucide-react';
-import type { DataSource, QueryParams, LookupColumnDef, LookupFilterDef } from '@object-ui/types';
+import type { DataSource, LookupColumnDef, LookupFilterDef } from '@object-ui/types';
 import { useFieldTranslation } from './useFieldTranslation';
+import { useRecordQuery } from './useRecordQuery';
 
 /** Default page size for the Record Picker dialog */
 const DEFAULT_PAGE_SIZE = 10;
@@ -260,6 +261,15 @@ export interface RecordPickerDialogProps {
    */
   lookupFilters?: LookupFilterDef[];
 
+  /**
+   * Hard filter constraints applied to every query, in QueryParams.$filter
+   * record form. Unlike `lookupFilters`, entries here never surface in the
+   * filter bar and cannot be overridden by user filter input — used for the
+   * dependent (cascading) lookup chain, where the parent field's value MUST
+   * scope the candidate set (#2215).
+   */
+  baseFilter?: Record<string, any>;
+
   /**
    * Cell renderer resolver function.
    * When provided, columns with a `type` property will be rendered using the
@@ -332,23 +342,16 @@ export function RecordPickerDialog({
   onSelect,
   onSelectRecords,
   lookupFilters,
+  baseFilter,
   cellRenderer,
   filterColumns,
   renderFilterBar,
   renderGrid,
 }: RecordPickerDialogProps) {
   const { t } = useFieldTranslation();
-  const [records, setRecords] = useState<any[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [totalCount, setTotalCount] = useState(0);
-  const [searchQuery, setSearchQuery] = useState('');
-  const [currentPage, setCurrentPage] = useState(1);
-  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Column sorting state
-  const [sortField, setSortField] = useState<string | null>(null);
-  const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
+
+  // Query state (records/loading/error/total + page/search/sort) lives in the
+  // shared useRecordQuery kernel — instantiated after mergedFilter below.
 
   // For multi-select, track pending selections before confirming
   const [pendingSelection, setPendingSelection] = useState<Set<any>>(new Set());
@@ -422,79 +425,49 @@ export function RecordPickerDialog({
     return undefined;
   }, [filterColumns, lookupFilters]);
 
-  // Merge base lookup_filters with user filter bar values
+  // Merge base lookup_filters with user filter bar values. The hard
+  // `baseFilter` constraint (dependent-lookup chain, #2215) is spread LAST so
+  // user filter-bar input can never widen it back out.
   const mergedFilter = useMemo<Record<string, any> | undefined>(() => {
-    const baseFilter = lookupFilters?.length
+    const lookupBase = lookupFilters?.length
       ? lookupFiltersToRecord(lookupFilters)
       : {};
     const userFilter = effectiveFilterColumns?.length
       ? filterValuesToRecord(filterValues, effectiveFilterColumns)
       : {};
-    const combined = { ...baseFilter, ...userFilter };
+    const combined = { ...lookupBase, ...userFilter, ...(baseFilter ?? {}) };
     return Object.keys(combined).length > 0 ? combined : undefined;
-  }, [lookupFilters, effectiveFilterColumns, filterValues]);
-
-  const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
-
-  // Fetch records
-  const fetchRecords = useCallback(
-    async (search?: string, page = 1, sort?: { field: string; direction: 'asc' | 'desc' } | null, customFilter?: Record<string, any>) => {
-      if (!dataSource || !objectName) return;
-
-      setLoading(true);
-      setError(null);
-
-      try {
-        const params: QueryParams = {
-          $top: pageSize,
-          $skip: (page - 1) * pageSize,
-        };
-        if (search && search.trim()) {
-          params.$search = search.trim();
-        }
-        if (sort) {
-          params.$orderby = { [sort.field]: sort.direction };
-        }
-        // Inject filters (lookup_filters + filter bar values)
-        const effectiveFilter = customFilter !== undefined ? customFilter : mergedFilter;
-        if (effectiveFilter && Object.keys(effectiveFilter).length > 0) {
-          params.$filter = effectiveFilter;
-        }
-
-        const result = await dataSource.find(objectName, params);
-        const data: any[] = result?.data ?? result ?? [];
-
-        setRecords(data);
-        setTotalCount(result?.total ?? data.length);
-        setFocusedRow(-1);
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        setError(msg);
-        setRecords([]);
-      } finally {
-        setLoading(false);
-      }
-    },
-    [dataSource, objectName, pageSize, mergedFilter],
-  );
-
-  // Build current sort object for passing to fetchRecords
-  const currentSort = useMemo(
-    () => sortField ? { field: sortField, direction: sortDirection } : null,
-    [sortField, sortDirection],
-  );
-
-  // Reset state when dialog closes — separate from the fetch effect so that
-  // resetting currentPage / sortField (which are fetch-effect deps) does not
-  // re-trigger the fetch effect and cause cascading re-renders (React #185).
+  }, [lookupFilters, effectiveFilterColumns, filterValues, baseFilter]);
+
+  // Shared query kernel: builds params, fetches, and owns records/loading/error/
+  // total plus the page/search/sort controls. Selection state stays local (above).
+  const query = useRecordQuery({
+    dataSource,
+    objectName,
+    enabled: open,
+    pageSize,
+    paginate: true,
+    filter: mergedFilter,
+  });
+  // Preserve the previous local names so the handlers and render below are
+  // unchanged (the migration is a pure refactor).
+  const { records, loading, error } = query;
+  const totalCount = query.total;
+  const totalPages = query.totalPages;
+  const searchQuery = query.search;
+  const currentPage = query.page;
+  const sortField = query.sort?.field ?? null;
+  const sortDirection: 'asc' | 'desc' = query.sort?.direction ?? 'asc';
+  const setCurrentPage = query.setPage;
+  const handleSort = query.toggleSort;
+  const handleSearchChange = query.setSearch;
+
+  // Reset non-query UI/selection state when the dialog closes. Query state
+  // (search/page/sort/records) is cleared by useRecordQuery when `enabled`
+  // (== open) goes false, kept separate so resets never cascade into a fetch
+  // (React #185).
   useEffect(() => {
     if (!open) {
-      setSearchQuery('');
-      setCurrentPage(1);
-      setError(null);
-      setRecords([]);
-      setSortField(null);
-      setSortDirection('asc');
       setFocusedRow(-1);
       setFilterBarOpen(false);
       setFilterValues({});
@@ -510,17 +483,6 @@ export function RecordPickerDialog({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open]);
 
-  // Fetch when dialog is open and pagination / sort / filter deps change
-  useEffect(() => {
-    if (open) {
-      fetchRecords(searchQuery || undefined, currentPage, currentSort);
-    }
-    // `fetchRecords` and `searchQuery` are intentionally excluded:
-    // fetchRecords is stable (useCallback), searchQuery triggers its own
-    // debounced fetch in handleSearchChange.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [open, currentPage, currentSort, mergedFilter]);
-
   // Initialize pending selection when dialog opens
   useEffect(() => {
     if (open && multiple) {
@@ -528,44 +490,11 @@ export function RecordPickerDialog({
     }
   }, [open, multiple, value]);
 
-  // Debounced search
-  const handleSearchChange = useCallback(
-    (query: string) => {
-      setSearchQuery(query);
-      setCurrentPage(1);
-
-      if (debounceTimer.current) {
-        clearTimeout(debounceTimer.current);
-      }
-      debounceTimer.current = setTimeout(() => {
-        fetchRecords(query || undefined, 1, currentSort);
-      }, 300);
-    },
-    [fetchRecords, currentSort],
-  );
-
-  // Clean up debounce timer
+  // Reset keyboard focus whenever the result set changes (previously done
+  // inline at the end of fetchRecords).
   useEffect(() => {
-    return () => {
-      if (debounceTimer.current) {
-        clearTimeout(debounceTimer.current);
-      }
-    };
-  }, []);
-
-  // Column sort handler
-  const handleSort = useCallback((field: string) => {
-    setSortField(prev => {
-      if (prev === field) {
-        // Toggle direction
-        setSortDirection(d => d === 'asc' ? 'desc' : 'asc');
-        return field;
-      }
-      setSortDirection('asc');
-      return field;
-    });
-    setCurrentPage(1);
-  }, []);
+    setFocusedRow(-1);
+  }, [records]);
 
   // Get record id
   const getRecordId = useCallback(
@@ -626,12 +555,12 @@ export function RecordPickerDialog({
 
   // Page navigation
   const handlePrevPage = useCallback(() => {
-    setCurrentPage(p => Math.max(1, p - 1));
-  }, []);
+    setCurrentPage(Math.max(1, currentPage - 1));
+  }, [setCurrentPage, currentPage]);
 
   const handleNextPage = useCallback(() => {
-    setCurrentPage(p => Math.min(totalPages, p + 1));
-  }, [totalPages]);
+    setCurrentPage(Math.min(totalPages, currentPage + 1));
+  }, [setCurrentPage, currentPage, totalPages]);
 
   // Page jump handler
   const handlePageJump = useCallback(
@@ -978,7 +907,7 @@ export function RecordPickerDialog({
             <Button
               variant="outline"
               size="sm"
-              onClick={() => fetchRecords(searchQuery || undefined, currentPage, currentSort)}
+              onClick={() => query.refetch()}
               type="button"
             >
               {t('lookup.retry')}

package/src/widgets/SelectionTray.tsx

@@ -0,0 +1,110 @@
+/**
+ * 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 React from 'react';
+import { Avatar, AvatarFallback, AvatarImage, cn } from '@object-ui/components';
+import { X } from 'lucide-react';
+import {
+  getPersonName,
+  getPersonInitials,
+  getPersonAvatarUrl,
+  getPersonId,
+} from './personDisplay';
+
+/**
+ * "Selected" transfer-box area (穿梭框式已选区): live echo of the current
+ * multi-selection as removable avatar chips. Reusable kernel — the future
+ * org-tree tier composes the same tray beside its right-hand list. Purely
+ * presentational: it takes the resolved records + an onRemove callback, and
+ * accepts already-translated `label`/`emptyText` so it stays i18n-agnostic.
+ */
+export interface SelectionTrayProps {
+  /** Full record objects for the current selection. */
+  records: any[];
+  /** Remove a selected record by its id. */
+  onRemove: (id: any) => void;
+  displayField?: string;
+  avatarField?: string;
+  idField?: string;
+  /** Header label, e.g. "Selected (3)" — omit to hide the header. */
+  label?: string;
+  /** When provided, a "Clear all" action shows in the header while non-empty. */
+  onClear?: () => void;
+  /** Localized "Clear all" text (i18n-agnostic — caller passes it). */
+  clearLabel?: string;
+  /** Shown when the selection is empty. */
+  emptyText?: string;
+  className?: string;
+}
+
+export function SelectionTray({
+  records,
+  onRemove,
+  displayField = 'name',
+  avatarField = 'image',
+  idField = 'id',
+  label,
+  onClear,
+  clearLabel,
+  emptyText,
+  className,
+}: SelectionTrayProps) {
+  const showHeader = !!label || (!!onClear && records.length > 0);
+  return (
+    <div className={cn('flex flex-col gap-1.5', className)} data-testid="selection-tray">
+      {showHeader && (
+        <div className="flex items-center justify-between">
+          {label && <div className="text-xs font-medium text-muted-foreground">{label}</div>}
+          {onClear && records.length > 0 && (
+            <button
+              type="button"
+              onClick={onClear}
+              className="text-xs text-muted-foreground transition-colors hover:text-foreground"
+              data-testid="selection-clear"
+            >
+              {clearLabel ?? 'Clear all'}
+            </button>
+          )}
+        </div>
+      )}
+      {records.length === 0 ? (
+        <div className="text-xs text-muted-foreground">{emptyText ?? ''}</div>
+      ) : (
+        <div className="flex flex-wrap gap-1.5">
+          {records.map(record => {
+            const id = getPersonId(record, idField);
+            const name = getPersonName(record, displayField);
+            const avatarUrl = getPersonAvatarUrl(record, avatarField);
+            const initials = getPersonInitials(name);
+            return (
+              <span
+                key={String(id)}
+                data-testid="selection-chip"
+                className="inline-flex items-center gap-1.5 rounded-full border bg-background py-0.5 pl-0.5 pr-1.5 text-sm"
+              >
+                <Avatar className="size-6 shrink-0">
+                  {avatarUrl && <AvatarImage src={avatarUrl} alt={name} />}
+                  <AvatarFallback className="text-[10px]">{initials}</AvatarFallback>
+                </Avatar>
+                <span className="max-w-[10rem] truncate">{name || '—'}</span>
+                <button
+                  type="button"
+                  onClick={() => onRemove(id)}
+                  aria-label={`Remove ${name}`}
+                  className="rounded-full p-0.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+                >
+                  <X className="size-3.5" aria-hidden />
+                </button>
+              </span>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/widgets/UserField.tsx

@@ -14,7 +14,21 @@ import { LookupField } from './LookupField';
  *
  * Table-cell display (avatars / initials) is handled separately by
  * `UserCellRenderer`; this is the form/editor widget.
+ *
+ * By default the user picker is the search-first {@link PeoplePicker}
+ * (`picker: 'search'`) with a department·email subtitle, avatar, and banned
+ * users excluded from candidates. Authors can override any of these, or opt
+ * back to the classic table dialog with `picker: 'default'`.
  */
+
+/** Exclude deactivated (`banned`) users unless the author already filters on it. */
+function withBannedFilter(filters?: any[]): any[] {
+  const base = Array.isArray(filters) ? filters : [];
+  return base.some(f => f?.field === 'banned')
+    ? base
+    : [...base, { field: 'banned', operator: 'ne', value: true }];
+}
+
 export function UserField(props: FieldWidgetProps<any>) {
   const raw = (props.field || (props as any).schema) as any;
 
@@ -26,11 +40,16 @@ export function UserField(props: FieldWidgetProps<any>) {
   const meta = metaIsNested ? raw.field : raw;
 
   // Ensure the picker always targets sys_user (even if the author omitted an
-  // explicit reference) and presents user names by default.
+  // explicit reference), presents user names by default, and defaults to the
+  // search-first PeoplePicker with sensible person display + candidate hygiene.
   const normalized = {
     ...(meta || {}),
     reference: meta?.reference || meta?.reference_to || 'sys_user',
     display_field: meta?.display_field || meta?.displayField || meta?.reference_field || 'name',
+    picker: meta?.picker ?? 'search',
+    subtitle: meta?.subtitle ?? ['primary_business_unit_id.name', 'email'],
+    avatar_field: meta?.avatar_field ?? meta?.avatarField ?? 'image',
+    lookup_filters: withBannedFilter(meta?.lookup_filters ?? meta?.lookupFilters),
   };
 
   const fieldProp = metaIsNested ? { ...raw, field: normalized } : normalized;

package/src/widgets/UserFieldPicker.test.tsx

@@ -0,0 +1,78 @@
+/**
+ * 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 { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { UserField } from './UserField';
+
+const USERS = [
+  { id: 'u1', name: 'Amy Lin', email: 'amy@x.io', image: 'http://x/amy.png', primary_business_unit_id: { name: 'Sales' } },
+  { id: 'u2', name: 'Bob Wu', email: 'bob@x.io', primary_business_unit_id: { name: 'Eng' } },
+];
+
+function makeDataSource() {
+  return {
+    find: vi.fn(async (_obj: string, params: any = {}) => {
+      const idIn = params?.$filter?.id?.$in as any[] | undefined;
+      if (idIn) {
+        const s = new Set(idIn.map(String));
+        const data = USERS.filter(u => s.has(String(u.id)));
+        return { data, total: data.length };
+      }
+      const search: string | undefined = params?.$search;
+      const data = search
+        ? USERS.filter(u => u.name.toLowerCase().includes(search.toLowerCase()))
+        : USERS;
+      return { data, total: data.length };
+    }),
+  } as any;
+}
+
+beforeEach(() => {
+  Object.defineProperty(window, 'innerWidth', { writable: true, configurable: true, value: 1280 });
+  window.matchMedia = ((query: string) => ({
+    matches: window.innerWidth < 768,
+    media: query,
+    onchange: null,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+    dispatchEvent: () => false,
+  })) as any;
+  try {
+    window.localStorage.clear();
+  } catch {
+    /* ignore */
+  }
+});
+
+describe('UserField — search-first entry (P0)', () => {
+  it('opens the PeoplePicker from the primary trigger (no separate browse-all button)', async () => {
+    const ds = makeDataSource();
+    render(<UserField field={{ type: 'user' } as any} dataSource={ds} value={null} onChange={vi.fn()} />);
+
+    // The redundant "browse all" icon is not rendered for search-first fields.
+    expect(screen.queryByTestId('browse-all-records')).toBeNull();
+
+    // Primary click opens the rich PeoplePicker (its search box appears).
+    fireEvent.click(screen.getByTestId('lookup-trigger'));
+    await waitFor(() => expect(screen.getByTestId('people-picker-search')).toBeTruthy());
+  });
+
+  it('renders the current selection as avatar chips', async () => {
+    const ds = makeDataSource();
+    render(
+      <UserField field={{ type: 'user', multiple: true } as any} dataSource={ds} value={['u1']} onChange={vi.fn()} />,
+    );
+    await waitFor(() => expect(screen.getByTestId('people-field-chip')).toBeTruthy());
+    expect(screen.getByText('Amy Lin')).toBeTruthy();
+    // Initials fallback renders (image does not load in jsdom).
+    expect(screen.getByText('AL')).toBeTruthy();
+  });
+});

package/src/widgets/deriveLookupColumns.test.ts

@@ -71,4 +71,29 @@ describe('deriveLookupColumns', () => {
     const cols = deriveLookupColumns(schema, { displayField: 'name' });
     expect(cols.map((c) => c.field)).toEqual(['name', 'region']);
   });
+
+  it('prefers ADR-0085 highlightFields over the declaration-order walk', () => {
+    const schema = {
+      fields: {
+        name: { type: 'text', label: 'Name' },
+        code: { type: 'text', label: 'Code' },
+        region: { type: 'select', label: 'Region' },
+        notes: { type: 'text', label: 'Notes' },
+      },
+      highlightFields: ['region', 'code'],
+    };
+    const cols = deriveLookupColumns(schema, { displayField: 'name', max: 4 });
+    // Display field leads, then highlightFields in order — not the raw field walk.
+    expect(cols.map((c) => c.field)).toEqual(['name', 'region', 'code']);
+  });
+
+  it('lets highlightFields win over legacy displayFields when both are present', () => {
+    const schema = {
+      fields: { name: { type: 'text' }, code: { type: 'text' }, region: { type: 'select' } },
+      highlightFields: ['region'],
+      displayFields: ['code'],
+    };
+    const cols = deriveLookupColumns(schema, { displayField: 'name' });
+    expect(cols.map((c) => c.field)).toEqual(['name', 'region']);
+  });
 });