@object-ui/fields 17.5.0 → 17.7.0

package/src/widgets/useRecordQuery.ts

@@ -1,291 +0,0 @@
-/**
- * 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 { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import type { DataSource, QueryParams } from '@object-ui/types';
-
-/**
- * useRecordQuery — the shared record-query kernel behind record pickers.
- *
- * Encapsulates the query/pagination/search/sort loop that was previously
- * duplicated (and independently tuned) inside `RecordPickerDialog.fetchRecords`
- * and `LookupField.fetchLookupData`:
- *
- * - builds the `QueryParams` (`$top`/`$skip`/`$search`/`$searchFields`/
- *   `$orderby`/`$filter`/`$expand`),
- * - issues `dataSource.find(objectName, params)` and normalises the result
- *   (`{ data, total }`, tolerating a bare array),
- * - owns `records`/`loading`/`error`/`total` plus the `page`/`search`/`sort`
- *   controls, with a debounced search path,
- * - clears itself when `enabled` goes false (e.g. a dialog closing).
- *
- * The caller keeps ownership of *selection* state and of record→option mapping;
- * this hook only answers "what records match the current query". It is the
- * reusable core the search-first PeoplePicker (and a future org-tree tier)
- * compose on top of.
- *
- * Effect shape intentionally mirrors the original components to preserve
- * behaviour: the fetch effect keys on page/sort/filter/expand (NOT `search`,
- * which drives its own debounced fetch), and state resets live in a separate
- * `enabled`-keyed effect so they never cascade into a fetch (React #185).
- */
-export interface UseRecordQueryOptions {
-  /** Backing data source. When absent/invalid the hook stays idle. */
-  dataSource?: DataSource | null;
-  /** Object/resource name to query (e.g. `sys_user`). */
-  objectName?: string | null;
-  /**
-   * Gate fetching. When false no request is issued and query state is cleared.
-   * Typically wired to a dialog's `open`, plus any "dependencies satisfied"
-   * guard. Default `true`.
-   */
-  enabled?: boolean;
-  /** `$top` — page size. Default 50. */
-  pageSize?: number;
-  /**
-   * When true, use page-based pagination (`$skip = (page - 1) * pageSize`).
-   * When false (default) a single page of `pageSize` records is fetched.
-   */
-  paginate?: boolean;
-  /**
-   * `$filter` — already merged by the caller (base `lookup_filters`, dependent
-   * lookup chain, candidate hygiene like `banned != true`, …). Compared by
-   * value, so a referentially-new-but-equal object each render will not loop.
-   *
-   * Either the `QueryParams.$filter` record form or a lowered ObjectQL AST node
-   * (an array), since the picker's merge now produces both (#3831). Typed
-   * `unknown` rather than `Record< string, any >` so an array cannot slip
-   * through a type that silently accepts it; emptiness is decided by
-   * {@link hasFilter}, not by `Object.keys`.
-   */
-  filter?: unknown;
-  /** `$expand` — related entities to include (e.g. `['primary_business_unit_id']`). */
-  expand?: string[];
-  /** `$searchFields` — narrow the server searchable set (ADR-0061). */
-  searchFields?: string[];
-  /** Debounce applied to {@link UseRecordQueryResult.setSearch}, in ms. Default 300. */
-  debounceMs?: number;
-}
-
-export interface RecordQuerySort {
-  field: string;
-  direction: 'asc' | 'desc';
-}
-
-export interface UseRecordQueryResult {
-  /** Records returned by the current query. */
-  records: any[];
-  loading: boolean;
-  error: string | null;
-  /** Total matching records (server-reported, else the current page length). */
-  total: number;
-  /** `ceil(total / pageSize)`, at least 1. */
-  totalPages: number;
-  page: number;
-  search: string;
-  sort: RecordQuerySort | null;
-  /** Jump to a page (1-indexed). No-op unless `paginate` is set. */
-  setPage: (page: number) => void;
-  /** Set the search term; debounced, and resets to page 1. */
-  setSearch: (query: string) => void;
-  /** Toggle sort on a field (new field → asc, same field → flip); resets to page 1. */
-  toggleSort: (field: string) => void;
-  /** Set the sort directly (or clear with `null`); resets to page 1. */
-  setSort: (sort: RecordQuerySort | null) => void;
-  /** Clear query state (search/page/sort/records/error). */
-  reset: () => void;
-  /** Imperatively refetch with the current params. */
-  refetch: () => void;
-}
-
-/**
- * Is this filter source worth sending as `$filter` at all?
- *
- * Array-aware on purpose. The picker's merge yields either the
- * `QueryParams.$filter` record form or a lowered ObjectQL AST node (#3831), and
- * `Object.keys` on an array returns its INDICES — so the record-only test read
- * `['0','1','2']` for an AST node and was right only by accident. An empty array
- * is "no filter" for the same reason an empty object is.
- */
-function hasFilter(filter: unknown): boolean {
-  if (filter === null || filter === undefined) return false;
-  if (Array.isArray(filter)) return filter.length > 0;
-  if (typeof filter !== 'object') return false;
-  return Object.keys(filter as object).length > 0;
-}
-
-export function useRecordQuery(options: UseRecordQueryOptions): UseRecordQueryResult {
-  const {
-    dataSource,
-    objectName,
-    enabled = true,
-    pageSize = 50,
-    paginate = false,
-    filter,
-    expand,
-    searchFields,
-    debounceMs = 300,
-  } = options;
-
-  const [records, setRecords] = useState<any[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [total, setTotal] = useState(0);
-  const [page, setPageState] = useState(1);
-  const [search, setSearchState] = useState('');
-  const [sort, setSortState] = useState<RecordQuerySort | null>(null);
-
-  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Stable signatures for object/array inputs so the fetch effect keys on their
-  // *value*, not a fresh reference every render.
-  const filterSignature = useMemo(
-    () => (hasFilter(filter) ? JSON.stringify(filter) : ''),
-    [filter],
-  );
-  const expandSignature = useMemo(() => (expand?.length ? expand.join(',') : ''), [expand]);
-  const searchFieldsSignature = useMemo(
-    () => (searchFields?.length ? searchFields.join(',') : ''),
-    [searchFields],
-  );
-
-  const canQuery =
-    !!enabled && !!dataSource && typeof dataSource.find === 'function' && !!objectName;
-
-  // Core fetch. Takes the controlled inputs as arguments so the debounced
-  // search path and the effect path share one implementation.
-  const runQuery = useCallback(
-    async (searchTerm: string, pageArg: number, sortArg: RecordQuerySort | null) => {
-      if (!canQuery || !dataSource || !objectName) return;
-
-      setLoading(true);
-      setError(null);
-
-      try {
-        const params: QueryParams = { $top: pageSize };
-        if (paginate) params.$skip = (pageArg - 1) * pageSize;
-        if (searchTerm && searchTerm.trim()) params.$search = searchTerm.trim();
-        if (searchFields && searchFields.length > 0) params.$searchFields = searchFields;
-        if (sortArg) params.$orderby = { [sortArg.field]: sortArg.direction };
-        // `QueryParams.$filter` is declared `Record< string, any >`, which the
-        // AST-array form does not describe — the cast is at this ONE assignment
-        // rather than widening a shared type that several other producers
-        // (plugin-list's `buildEffectiveFilter`, plugin-view's ObjectView)
-        // already feed arrays through.
-        if (hasFilter(filter)) params.$filter = filter as Record<string, any>;
-        if (expand && expand.length > 0) params.$expand = expand;
-
-        const result = await dataSource.find(objectName, params);
-        const data: any[] = result?.data ?? (result as any) ?? [];
-
-        setRecords(data);
-        setTotal(result?.total ?? data.length);
-      } catch (err) {
-        setError(err instanceof Error ? err.message : String(err));
-        setRecords([]);
-      } finally {
-        setLoading(false);
-      }
-    },
-    // filter/expand/searchFields are referenced via their signatures below so
-    // this callback stays stable across referentially-new-but-equal props.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [canQuery, dataSource, objectName, pageSize, paginate, filterSignature, expandSignature, searchFieldsSignature],
-  );
-
-  // Fetch on enable and whenever page/sort/filter/expand change. `search` is
-  // intentionally excluded — it has its own debounced path in `setSearch`.
-  useEffect(() => {
-    if (canQuery) {
-      runQuery(search, page, sort);
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [canQuery, page, sort, runQuery]);
-
-  // Reset query state when disabled — separate from the fetch effect so resets
-  // don't re-trigger a fetch (React #185).
-  useEffect(() => {
-    if (!enabled) {
-      setRecords([]);
-      setError(null);
-      setSearchState('');
-      setPageState(1);
-      setSortState(null);
-    }
-  }, [enabled]);
-
-  // Clean up the debounce timer on unmount.
-  useEffect(
-    () => () => {
-      if (debounceTimer.current) clearTimeout(debounceTimer.current);
-    },
-    [],
-  );
-
-  const setSearch = useCallback(
-    (query: string) => {
-      setSearchState(query);
-      setPageState(1);
-      if (debounceTimer.current) clearTimeout(debounceTimer.current);
-      debounceTimer.current = setTimeout(() => {
-        runQuery(query, 1, sort);
-      }, debounceMs);
-    },
-    [runQuery, sort, debounceMs],
-  );
-
-  const setPage = useCallback((next: number) => {
-    setPageState(next);
-  }, []);
-
-  const toggleSort = useCallback((field: string) => {
-    setSortState(prev =>
-      prev && prev.field === field
-        ? { field, direction: prev.direction === 'asc' ? 'desc' : 'asc' }
-        : { field, direction: 'asc' },
-    );
-    setPageState(1);
-  }, []);
-
-  const setSort = useCallback((next: RecordQuerySort | null) => {
-    setSortState(next);
-    setPageState(1);
-  }, []);
-
-  const reset = useCallback(() => {
-    if (debounceTimer.current) clearTimeout(debounceTimer.current);
-    setRecords([]);
-    setError(null);
-    setSearchState('');
-    setPageState(1);
-    setSortState(null);
-  }, []);
-
-  const refetch = useCallback(() => {
-    runQuery(search, page, sort);
-  }, [runQuery, search, page, sort]);
-
-  const totalPages = Math.max(1, Math.ceil(total / Math.max(1, pageSize)));
-
-  return {
-    records,
-    loading,
-    error,
-    total,
-    totalPages,
-    page,
-    search,
-    sort,
-    setPage,
-    setSearch,
-    toggleSort,
-    setSort,
-    reset,
-    refetch,
-  };
-}

package/src/widgets/useUploadingSignal.test.tsx

@@ -1,62 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { renderHook } from '@testing-library/react';
-import { useUploadingSignal } from './useUploadingSignal';
-
-/**
- * useUploadingSignal — surfaces an upload widget's in-progress flips to a host
- * (ActionParamDialog blocks Confirm while a file/image param uploads). It must
- * fire only when `uploading` changes and always call the latest callback.
- */
-describe('useUploadingSignal', () => {
-  it('fires with the initial value on mount', () => {
-    const cb = vi.fn();
-    renderHook(() => useUploadingSignal(false, cb));
-    expect(cb).toHaveBeenCalledTimes(1);
-    expect(cb).toHaveBeenLastCalledWith(false);
-  });
-
-  it('fires again only when `uploading` changes', () => {
-    const cb = vi.fn();
-    const { rerender } = renderHook(({ u }) => useUploadingSignal(u, cb), {
-      initialProps: { u: false },
-    });
-    cb.mockClear();
-
-    rerender({ u: true });
-    expect(cb).toHaveBeenCalledTimes(1);
-    expect(cb).toHaveBeenLastCalledWith(true);
-
-    // Same value → no extra fire.
-    rerender({ u: true });
-    expect(cb).toHaveBeenCalledTimes(1);
-
-    rerender({ u: false });
-    expect(cb).toHaveBeenCalledTimes(2);
-    expect(cb).toHaveBeenLastCalledWith(false);
-  });
-
-  it('always invokes the latest callback (no stale closure)', () => {
-    const first = vi.fn();
-    const second = vi.fn();
-    const { rerender } = renderHook(
-      ({ cb, u }) => useUploadingSignal(u, cb),
-      { initialProps: { cb: first, u: false } },
-    );
-    // Swap the callback without changing `uploading` → no fire yet.
-    rerender({ cb: second, u: false });
-    expect(second).not.toHaveBeenCalled();
-    // Now flip `uploading` → the NEW callback fires, not the old one.
-    rerender({ cb: second, u: true });
-    expect(second).toHaveBeenCalledWith(true);
-    expect(first).not.toHaveBeenCalledWith(true);
-  });
-
-  it('is a no-op when no callback is provided', () => {
-    expect(() => {
-      const { rerender } = renderHook(({ u }) => useUploadingSignal(u), {
-        initialProps: { u: false },
-      });
-      rerender({ u: true });
-    }).not.toThrow();
-  });
-});

package/src/widgets/useUploadingSignal.ts

@@ -1,20 +0,0 @@
-import { useEffect, useRef } from 'react';
-
-/**
- * Notify a parent whenever an upload widget's in-progress state flips. Used by
- * hosts that must block a submit until the presigned upload resolves — e.g.
- * `ActionParamDialog` disables Confirm so a `file`/`image` param can't be
- * submitted mid-upload (the value only becomes the fileId once the upload
- * settles). Fires with the latest callback and only when `uploading` actually
- * changes, so an inline arrow prop doesn't thrash the parent every render.
- */
-export function useUploadingSignal(
-  uploading: boolean,
-  onUploadingChange?: (uploading: boolean) => void,
-): void {
-  const ref = useRef(onUploadingChange);
-  ref.current = onUploadingChange;
-  useEffect(() => {
-    ref.current?.(uploading);
-  }, [uploading]);
-}

package/src/withFieldCarrier.tsx

@@ -1,75 +0,0 @@
-/**
- * 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';
-
-/**
- * Adapt `SchemaRenderer`'s SDUI carrier onto the field-widget contract —
- * objectui#3233, the producer-side half of retiring `schema` from
- * {@link import('./widgets/types').FieldWidgetComponentProps}.
- *
- * ## Why this exists
- *
- * Two kinds of host render a registered field widget, and they name the
- * metadata differently *for good reason*:
- *
- *  - the **form renderer** (`renderFieldComponent` in
- *    `@object-ui/components`), the inline-edit hosts (`FieldEditWidget`) and
- *    the action dialogs pass **`field`** — the field metadata they already
- *    hold;
- *  - **`SchemaRenderer`** (`@object-ui/react`) passes **`schema`** — the
- *    authored node. That key is the UNIVERSAL SDUI contract *every* registered
- *    component receives (`element:*`, `page:*`, `object-grid`,
- *    `ReportRenderer` …). It is not being retired and must not be: it is what
- *    the renderer means by "the node you were rendered from".
- *
- * What WAS wrong is that both keys reached the widget, so ~30 widgets resolved
- * their config as `field || schema` — one concept under two spellings, a second
- * de-facto contract on the widget side (AGENTS.md #0.1) and precisely the shape
- * that lets an AI-written widget pick one spelling and appear to work under one
- * host while reading `undefined` under the other.
- *
- * The translation belongs at the seam, exactly once: here. Downstream `field`
- * is the only carrier, and a widget reading `props.schema` no longer compiles.
- *
- * ## Guarantee
- *
- * Payload-preserving by construction: the node is forwarded **by reference**,
- * so a widget's `field` is the very object it used to read through `schema`.
- * `field` wins when a host supplies both (the form path always does, and it
- * holds the resolved metadata rather than the raw node).
- *
- * `schema` is *consumed* here rather than forwarded — with the key gone from
- * the contract, passing it on would only reach the DOM as a stray attribute
- * through a widget's `...props` spread.
- *
- * ## For widget authors outside this repo
- *
- * Registering a widget raw means `SchemaRenderer` hands it `schema` and no
- * `field`. Wrap it once at registration and the widget only ever implements
- * `FieldWidgetComponentProps`:
- *
- * ```tsx
- * import { withFieldCarrier } from '@object-ui/fields';
- *
- * ComponentRegistry.register('color', withFieldCarrier(ColorPickerField), {
- *   namespace: 'field',
- * });
- * ```
- */
-export function withFieldCarrier<P extends object>(
-  FieldWidget: React.ComponentType<P>,
-): React.FC<Record<string, any>> {
-  const FieldCarrierAdapter: React.FC<Record<string, any>> = ({ schema, field, ...props }) => (
-    <FieldWidget {...(props as unknown as P)} field={field ?? schema} />
-  );
-  FieldCarrierAdapter.displayName = `FieldCarrier(${
-    (FieldWidget as any).displayName || (FieldWidget as any).name || 'Component'
-  })`;
-  return FieldCarrierAdapter;
-}