@object-ui/fields 11.2.0 → 11.4.0

package/src/widgets/deriveLookupColumns.ts

@@ -32,7 +32,14 @@ export interface DeriveColumnsOptions {
 
 interface ObjectSchemaLike {
   fields?: Record<string, { type?: string; label?: string; hidden?: boolean }>;
-  /** Object-level "fields to display in search result cards" (spec metadata). */
+  /**
+   * ADR-0085 semantic role: the object's most important fields. The single
+   * source for "how to list this object" — shared with the detail-page related
+   * list — so a lookup picker and a related list of the same object agree on
+   * columns with zero per-surface config.
+   */
+  highlightFields?: unknown;
+  /** Object-level "fields to display in search result cards" (legacy spec metadata). */
   displayFields?: unknown;
 }
 
@@ -53,9 +60,10 @@ function dedupe(names: string[]): string[] {
  * a lookup field declares no explicit `lookup_columns`.
  *
  * Priority:
- *   1. The referenced object's own `displayFields` ("fields to display in
- *      search result cards") — the author's declared search-card shape.
- *   2. Otherwise the display field plus the next few business fields in
+ *   1. The referenced object's ADR-0085 `highlightFields` — the canonical
+ *      "how to list this object" set, shared with the detail-page related list.
+ *   2. Else the object's legacy `displayFields` search-card shape.
+ *   3. Otherwise the display field plus the next few business fields in
  *      declaration order, skipping system/audit fields and heavy non-tabular
  *      types.
  *
@@ -79,17 +87,23 @@ export function deriveLookupColumns(
 
   if (Object.keys(fields).length === 0) return [];
 
-  // 1. Honour the object's explicit search-card fields when present.
-  const declared = objectSchema?.displayFields;
-  if (Array.isArray(declared) && declared.length > 0) {
-    const names = (declared as unknown[]).filter(
+  // 1 & 2. Honour a declared column list — `highlightFields` (ADR-0085
+  // canonical, shared with the related list) first, then the legacy
+  // `displayFields` search-card list. The display field always leads.
+  const fromDeclaredList = (list: unknown): LookupColumnDef[] | null => {
+    if (!Array.isArray(list) || list.length === 0) return null;
+    const names = (list as unknown[]).filter(
       (n): n is string => typeof n === 'string' && n.length > 0,
     );
     const ordered = dedupe([displayField, ...names.filter((n) => n !== displayField)]);
     return ordered.slice(0, max).map(toCol);
-  }
+  };
+  const fromHighlights = fromDeclaredList(objectSchema?.highlightFields);
+  if (fromHighlights) return fromHighlights;
+  const fromDisplay = fromDeclaredList(objectSchema?.displayFields);
+  if (fromDisplay) return fromDisplay;
 
-  // 2. Derive from the field set in declaration order.
+  // 3. Derive from the field set in declaration order.
   const candidates = Object.keys(fields).filter((name) => {
     if (name === displayField) return false;
     if (SYSTEM_FIELDS.has(name)) return false;

package/src/widgets/personDisplay.test.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 { describe, it, expect } from 'vitest';
+import {
+  resolvePath,
+  getPersonName,
+  getPersonInitials,
+  getPersonSubtitle,
+  getPersonAvatarUrl,
+  getPersonId,
+  matchRanges,
+} from './personDisplay';
+
+describe('personDisplay helpers', () => {
+  describe('resolvePath', () => {
+    it('reads flat and dotted paths', () => {
+      const rec = { name: 'Amy', primary_business_unit_id: { name: 'Sales' } };
+      expect(resolvePath(rec, 'name')).toBe('Amy');
+      expect(resolvePath(rec, 'primary_business_unit_id.name')).toBe('Sales');
+    });
+    it('returns undefined for missing paths or nullish records', () => {
+      expect(resolvePath({ a: {} }, 'a.b.c')).toBeUndefined();
+      expect(resolvePath(null, 'x')).toBeUndefined();
+      expect(resolvePath({ a: 1 }, '')).toBeUndefined();
+    });
+  });
+
+  describe('getPersonName', () => {
+    it('prefers the display field, then common fallbacks', () => {
+      expect(getPersonName({ name: 'Amy' })).toBe('Amy');
+      expect(getPersonName({ full_name: 'Amy Lin' }, 'full_name')).toBe('Amy Lin');
+      expect(getPersonName({ username: 'amy' })).toBe('amy');
+      expect(getPersonName('raw-id')).toBe('raw-id');
+      expect(getPersonName(null)).toBe('');
+    });
+  });
+
+  describe('getPersonInitials', () => {
+    it('takes first+last initial for multi-word latin names', () => {
+      expect(getPersonInitials('John Doe')).toBe('JD');
+      expect(getPersonInitials('mary jane watson')).toBe('MW');
+    });
+    it('takes first two letters for a single latin token', () => {
+      expect(getPersonInitials('John')).toBe('JO');
+    });
+    it('takes the given-name chars for CJK names', () => {
+      expect(getPersonInitials('张三')).toBe('张三');
+      expect(getPersonInitials('王小明')).toBe('小明');
+    });
+    it('falls back to "?" for empty', () => {
+      expect(getPersonInitials('')).toBe('?');
+      expect(getPersonInitials('   ')).toBe('?');
+    });
+  });
+
+  describe('getPersonSubtitle', () => {
+    it('joins non-empty resolved fields with a middot', () => {
+      const rec = { email: 'amy@x.io', primary_business_unit_id: { name: 'Sales' } };
+      expect(getPersonSubtitle(rec, ['primary_business_unit_id.name', 'email'])).toBe(
+        'Sales · amy@x.io',
+      );
+    });
+    it('drops empty segments and returns "" when nothing resolves', () => {
+      expect(getPersonSubtitle({ email: 'amy@x.io' }, ['primary_business_unit_id.name', 'email'])).toBe(
+        'amy@x.io',
+      );
+      expect(getPersonSubtitle({}, ['a', 'b'])).toBe('');
+      expect(getPersonSubtitle({ a: 1 }, undefined)).toBe('');
+    });
+  });
+
+  describe('getPersonAvatarUrl', () => {
+    it('reads the avatar field, undefined when absent', () => {
+      expect(getPersonAvatarUrl({ image: 'http://x/y.png' })).toBe('http://x/y.png');
+      expect(getPersonAvatarUrl({})).toBeUndefined();
+      expect(getPersonAvatarUrl({ photo: 'p' }, 'photo')).toBe('p');
+    });
+  });
+
+  describe('getPersonId', () => {
+    it('tolerates id / _id / custom / primitive', () => {
+      expect(getPersonId({ id: 1 })).toBe(1);
+      expect(getPersonId({ _id: 'a' })).toBe('a');
+      expect(getPersonId({ user_id: 9 }, 'user_id')).toBe(9);
+      expect(getPersonId('plain')).toBe('plain');
+    });
+  });
+});
+
+describe('matchRanges', () => {
+  it('returns no ranges for an empty query or empty text', () => {
+    expect(matchRanges('Amy Lin', '')).toEqual([]);
+    expect(matchRanges('', 'amy')).toEqual([]);
+  });
+
+  it('finds case-insensitive substring ranges', () => {
+    expect(matchRanges('Amy Lin', 'am')).toEqual([[0, 2]]);
+    expect(matchRanges('Sales · amy@x.io', 'amy')).toEqual([[8, 11]]);
+  });
+
+  it('finds every non-overlapping occurrence', () => {
+    expect(matchRanges('banana', 'an')).toEqual([
+      [1, 3],
+      [3, 5],
+    ]);
+  });
+});

package/src/widgets/personDisplay.ts

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+
+/**
+ * Pure display helpers for person (sys_user) records, shared by the
+ * search-first PeoplePicker's rich rows, the SelectionTray chips, and the
+ * read-only user cell renderer. Kept framework-free so they're trivially
+ * unit-testable and reusable by a future org-tree tier.
+ */
+
+/** Resolve a possibly-dotted path (e.g. `primary_business_unit_id.name`) against a record. */
+export function resolvePath(record: any, path: string): any {
+  if (!record || !path) return undefined;
+  if (!path.includes('.')) return record[path];
+  return path.split('.').reduce((acc, key) => (acc == null ? acc : acc[key]), record);
+}
+
+/** Best display name for a person record, tolerating expanded / raw shapes. */
+export function getPersonName(record: any, nameField = 'name'): string {
+  if (record == null) return '';
+  if (typeof record !== 'object') return String(record);
+  return String(record[nameField] ?? record.name ?? record.username ?? record.label ?? '');
+}
+
+/**
+ * Up-to-2-char initials for the avatar fallback.
+ * - "John Doe" → "JD"; "John" → "JO"
+ * - CJK single token → trailing 1–2 chars (given name): "张三" → "张三", "王小明" → "小明"
+ */
+export function getPersonInitials(name: string): string {
+  const trimmed = (name || '').trim();
+  if (!trimmed) return '?';
+  const parts = trimmed.split(/\s+/).filter(Boolean);
+  if (parts.length >= 2) {
+    return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+  }
+  const token = parts[0];
+  if (/[㐀-鿿]/.test(token)) {
+    return token.length <= 2 ? token : token.slice(-2);
+  }
+  return token.slice(0, 2).toUpperCase();
+}
+
+/** Secondary line: resolve each field path, drop empties, join with " · ". */
+export function getPersonSubtitle(record: any, fields?: string[]): string {
+  if (!record || !fields || fields.length === 0) return '';
+  return fields
+    .map(f => resolvePath(record, f))
+    .filter(v => v != null && v !== '')
+    .map(v => String(v))
+    .join(' · ');
+}
+
+/** Avatar image URL (defaults to `sys_user.image`); undefined when absent. */
+export function getPersonAvatarUrl(record: any, avatarField = 'image'): string | undefined {
+  const v = record ? resolvePath(record, avatarField) : undefined;
+  return v ? String(v) : undefined;
+}
+
+/** Record id, tolerating `id` / `_id` / a custom id field. */
+export function getPersonId(record: any, idField = 'id'): any {
+  if (!record || typeof record !== 'object') return record;
+  return record[idField] ?? record.id ?? record._id;
+}
+
+/**
+ * Case-insensitive literal-substring match ranges of `query` in `text`, as
+ * `[start, end)` index pairs. Used to highlight the typed term in candidate
+ * rows — a strong disambiguation aid for same-named people. Pinyin matches are
+ * resolved server-side and won't have client ranges; that's fine, the row still
+ * shows, just without a highlight.
+ */
+export function matchRanges(text: string, query: string): Array<[number, number]> {
+  const t = text ?? '';
+  const q = (query ?? '').trim().toLowerCase();
+  if (!q || !t) return [];
+  const lower = t.toLowerCase();
+  const ranges: Array<[number, number]> = [];
+  let from = 0;
+  for (;;) {
+    const idx = lower.indexOf(q, from);
+    if (idx === -1) break;
+    ranges.push([idx, idx + q.length]);
+    from = idx + q.length;
+  }
+  return ranges;
+}

package/src/widgets/useRecordQuery.test.ts

@@ -0,0 +1,174 @@
+/**
+ * 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 { renderHook, act, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { useRecordQuery } from './useRecordQuery';
+
+function makeDataSource(result: any = { data: [], total: 0 }) {
+  return { find: vi.fn().mockResolvedValue(result) } as any;
+}
+
+describe('useRecordQuery', () => {
+  it('fetches on mount with $top and exposes records/total', async () => {
+    const ds = makeDataSource({ data: [{ id: 1 }], total: 5 });
+    const { result } = renderHook(() =>
+      useRecordQuery({ dataSource: ds, objectName: 'sys_user' }),
+    );
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(ds.find).toHaveBeenCalledWith('sys_user', { $top: 50 });
+    expect(result.current.records).toEqual([{ id: 1 }]);
+    expect(result.current.total).toBe(5);
+  });
+
+  it('tolerates a bare-array response (no { data } envelope)', async () => {
+    const ds = { find: vi.fn().mockResolvedValue([{ id: 1 }, { id: 2 }]) } as any;
+    const { result } = renderHook(() =>
+      useRecordQuery({ dataSource: ds, objectName: 'o' }),
+    );
+
+    await waitFor(() => expect(result.current.records).toHaveLength(2));
+    expect(result.current.total).toBe(2);
+  });
+
+  it('adds $skip only when paginate is set', async () => {
+    const ds = makeDataSource({ data: [], total: 100 });
+    const { result } = renderHook(() =>
+      useRecordQuery({ dataSource: ds, objectName: 'o', pageSize: 10, paginate: true }),
+    );
+
+    await waitFor(() => expect(ds.find).toHaveBeenLastCalledWith('o', { $top: 10, $skip: 0 }));
+    // waitFor: the call firing doesn't guarantee its promise resolved and
+    // setTotal flushed — assert on the settled state, not a bare read.
+    await waitFor(() => expect(result.current.totalPages).toBe(10));
+
+    act(() => result.current.setPage(3));
+    await waitFor(() =>
+      expect(ds.find).toHaveBeenLastCalledWith('o', { $top: 10, $skip: 20 }),
+    );
+  });
+
+  it('debounces setSearch, resets to page 1, and coalesces rapid input', async () => {
+    const ds = makeDataSource();
+    const { result } = renderHook(() =>
+      useRecordQuery({ dataSource: ds, objectName: 'o', debounceMs: 20 }),
+    );
+    await waitFor(() => expect(ds.find).toHaveBeenCalledTimes(1)); // mount fetch
+
+    act(() => {
+      result.current.setSearch('a');
+      result.current.setSearch('ab');
+    });
+
+    await waitFor(() =>
+      expect(ds.find).toHaveBeenLastCalledWith('o', { $top: 50, $search: 'ab' }),
+    );
+    // The superseded 'a' term never reached the server.
+    expect(ds.find).not.toHaveBeenCalledWith('o', { $top: 50, $search: 'a' });
+  });
+
+  it('toggleSort sets $orderby asc then flips to desc', async () => {
+    const ds = makeDataSource();
+    const { result } = renderHook(() =>
+      useRecordQuery({ dataSource: ds, objectName: 'o' }),
+    );
+    await waitFor(() => expect(ds.find).toHaveBeenCalled());
+
+    act(() => result.current.toggleSort('name'));
+    await waitFor(() =>
+      expect(ds.find).toHaveBeenLastCalledWith('o', { $top: 50, $orderby: { name: 'asc' } }),
+    );
+
+    act(() => result.current.toggleSort('name'));
+    await waitFor(() =>
+      expect(ds.find).toHaveBeenLastCalledWith('o', { $top: 50, $orderby: { name: 'desc' } }),
+    );
+  });
+
+  it('passes $filter and refetches when the filter value changes', async () => {
+    const ds = makeDataSource();
+    const { rerender } = renderHook(
+      ({ filter }) => useRecordQuery({ dataSource: ds, objectName: 'o', filter }),
+      { initialProps: { filter: { banned: { $ne: true } } as Record<string, any> } },
+    );
+
+    await waitFor(() =>
+      expect(ds.find).toHaveBeenLastCalledWith('o', {
+        $top: 50,
+        $filter: { banned: { $ne: true } },
+      }),
+    );
+
+    rerender({ filter: { banned: { $ne: true }, active: true } });
+    await waitFor(() =>
+      expect(ds.find).toHaveBeenLastCalledWith('o', {
+        $top: 50,
+        $filter: { banned: { $ne: true }, active: true },
+      }),
+    );
+  });
+
+  it('passes $expand and $searchFields through', async () => {
+    const ds = makeDataSource();
+    renderHook(() =>
+      useRecordQuery({
+        dataSource: ds,
+        objectName: 'sys_user',
+        expand: ['primary_business_unit_id'],
+        searchFields: ['name', 'email'],
+      }),
+    );
+
+    await waitFor(() =>
+      expect(ds.find).toHaveBeenLastCalledWith('sys_user', {
+        $top: 50,
+        $expand: ['primary_business_unit_id'],
+        $searchFields: ['name', 'email'],
+      }),
+    );
+  });
+
+  it('does not fetch while disabled and clears records when re-disabled', async () => {
+    const ds = makeDataSource({ data: [{ id: 1 }], total: 1 });
+    const { result, rerender } = renderHook(
+      ({ enabled }) => useRecordQuery({ dataSource: ds, objectName: 'o', enabled }),
+      { initialProps: { enabled: false } },
+    );
+
+    await new Promise(r => setTimeout(r, 20));
+    expect(ds.find).not.toHaveBeenCalled();
+
+    rerender({ enabled: true });
+    await waitFor(() => expect(result.current.records).toEqual([{ id: 1 }]));
+
+    rerender({ enabled: false });
+    await waitFor(() => expect(result.current.records).toEqual([]));
+  });
+
+  it('captures fetch errors and empties the result set', async () => {
+    const ds = { find: vi.fn().mockRejectedValue(new Error('boom')) } as any;
+    const { result } = renderHook(() =>
+      useRecordQuery({ dataSource: ds, objectName: 'o' }),
+    );
+
+    await waitFor(() => expect(result.current.error).toBe('boom'));
+    expect(result.current.records).toEqual([]);
+    expect(result.current.loading).toBe(false);
+  });
+
+  it('stays idle when no dataSource is provided', async () => {
+    const { result } = renderHook(() =>
+      useRecordQuery({ dataSource: null, objectName: 'o' }),
+    );
+
+    await new Promise(r => setTimeout(r, 10));
+    expect(result.current.loading).toBe(false);
+    expect(result.current.records).toEqual([]);
+  });
+});