@object-ui/fields 17.5.0 → 17.6.0

package/src/widgets/types.ts

@@ -1,242 +0,0 @@
-import type { AriaAttributes, FocusEventHandler, MouseEventHandler } from 'react';
-import type { DependsOnInput, FieldMetadata } from '@object-ui/types';
-
-/**
- * DOM pass-through: what a widget's `...props` spread may legitimately put on
- * the element it renders.
- *
- * A NAMED type rather than an inline block of {@link FieldWidgetComponentProps}
- * so the compiler can bind it to its runtime executor in BOTH directions
- * (objectui#3291). `toDomProps` asserts:
- *
- *  - every key it forwards is declared on the widget contract — deleting one
- *    here without deleting it there is a compile error;
- *  - every key of THIS type is one it forwards — adding one here without
- *    adding it to `DOM_PASS_THROUGH_KEYS` is a compile error too.
- *
- * The second direction is the one that matters for the failure mode this repo
- * treats as first-class: DECLARED BUT NOT DELIVERED (objectui#3290's
- * `aria-required` that never reached a control, objectui#3222's validation slot
- * nobody produced). Without it, a key added here would type-check, read as
- * supported, and silently never reach the DOM — and the leak test cannot see
- * that class of bug, because it looks for attributes that ARRIVE, not for ones
- * that go missing.
- *
- * `className` and `disabled` are deliberately NOT here. They are DOM-legal and
- * `toDomProps` does forward them, but they are declared on the controlled-input
- * block of {@link FieldWidgetComponentProps} because widgets also INTERPRET
- * them (className is composed with the widget's own classes; disabled is OR-ed
- * with readonly). They are therefore bound in the forward direction only.
- *
- * `AriaAttributes` and the `data-${string}` family are matched by prefix at
- * runtime rather than key-by-key, so they are intersected in separately.
- *
- * Adding a key here is a contract change: say who produces it and who reads it.
- */
-export type FieldWidgetDomProps = {
-  id?: string;
-  /** react-hook-form's field name, spread in by the form renderer. */
-  name?: string;
-  autoFocus?: boolean;
-  tabIndex?: number;
-  onBlur?: FocusEventHandler<HTMLElement>;
-  onFocus?: FocusEventHandler<HTMLElement>;
-  onClick?: MouseEventHandler<HTMLElement>;
-};
-
-/**
- * Props every field widget in this package receives at RUNTIME.
- *
- * Named `FieldWidgetComponentProps`, not `FieldWidgetProps` (objectui#3161,
- * objectstack#4115 ledger batch 7), adopting the name `@object-ui/app-shell`
- * settled on for the same split in objectui#3169: `@objectstack/spec/ui` owns
- * `FieldWidgetProps` for the DECLARED widget-plugin contract — a zod object
- * (`FieldWidgetPropsSchema`) a plugin manifest is validated against, with
- * `field` narrowed to `{ name?, label?, type: <the FieldType enum> }` and
- * `readonly` / `required` carrying `.default()`s. This is the React interface
- * the widgets in this directory actually implement, against
- * `@object-ui/types`'s much richer `FieldMetadata`.
- *
- * The two are NOT interchangeable, but they no longer disagree on the
- * validation slot: this type used to call it `errorMessage` while the spec
- * calls it `error`, so a widget written to the published contract read
- * `undefined` forever. objectui#3222 resolved that in the direction the
- * contract points — the slot below IS the spec's `error`, and the form
- * renderer now produces it (see `error`'s own doc comment). Reading
- * `props.required` off this type is still a compile error rather than a
- * silent `any`; that key is deliberately NOT lowered here (see below).
- *
- * ## Why `required` is still absent, though the spec declares it
- *
- * The required MARKER is drawn exactly once, by the form renderer's
- * `<FormLabel>` (the `*` with `aria-label="required"`, which the label
- * association folds into the control's accessible name). Handing `required`
- * to widgets would give that marker a second possible author, and the very
- * next AI-written widget draws its own asterisk — the same double-display
- * failure that keeps the validation TEXT out of the widget below. The a11y
- * state a widget genuinely could carry is `aria-required` on the input, and
- * that needs no new key at all: `AriaAttributes` is already part of this type
- * and every widget already forwards it to its control. Tracked separately;
- * do not add `required` here to "align" without that decision.
- *
- * ## Why there is no `[key: string]: any` (objectui#3221)
- *
- * This type used to end in an index signature, "load-bearing" for the widgets'
- * `...props` spreads. It was also why every drift above was invisible: **a type
- * that claims to have every key can never be reported as missing one** (the
- * objectstack#4075 mechanism). `props.required` and `props.error` were legal
- * reads typed `any` and always `undefined` at runtime; a misspelled prop
- * (`readOnly` for `readonly`, `onchange` for `onChange`) compiled; and any
- * structural/parity comparison against the type was useless *in principle*,
- * which is why the batch-7 symbol guard was the only detector that could see
- * the collision at all.
- *
- * It is replaced by the CLOSED set below: the controlled-input contract, the
- * host plumbing the form renderer genuinely forwards, and a DOM pass-through
- * allowance. `data-*` is an open family by design (it is open in HTML too) and
- * is expressed as a template-literal index signature, which — unlike
- * `[key: string]` — leaves `keyof` finite, so an undeclared prop still fails.
- *
- * ## Why there is no `schema` (objectui#3233)
- *
- * `schema` used to be declared here as a SECOND carrier for what `field`
- * already means — `SchemaRenderer` handed the SDUI node down as `schema`, the
- * form renderer forwarded `schema={props.field || props.schema || props}`
- * *alongside* `field`, and ~30 widgets resolved their config as
- * `field || schema`. One concept, two keys, two producers: exactly the
- * consumer-side tolerance AGENTS.md #0.1 forbids, and exactly the shape that
- * lets an AI-written widget pick the wrong spelling and still "work" under one
- * host while reading `undefined` under another.
- *
- * v17 converged it at the PRODUCERS. `field` is the only carrier a widget ever
- * sees; the SDUI node → `field` translation happens once, in this package's
- * registry adapter (`withFieldCarrier`), not ~30 times in the widgets. Reading
- * `props.schema` is now a compile error rather than a silent second contract.
- *
- * Adding a key here is a contract change: say who produces it and who reads it.
- */
-export type FieldWidgetComponentProps<T = any> = {
-  /* ── The controlled-input contract every widget implements ─────────────── */
-
-  value: T;
-  onChange: (val: T) => void;
-  /**
-   * The field's metadata, and the SINGLE carrier for it (objectui#3233).
-   *
-   * Deliberately the looser `@object-ui/types` shape rather than the spec's,
-   * to avoid a circular dependency for now.
-   *
-   * Every host produces it: the form renderer's `renderFieldComponent`, the
-   * inline-edit hosts (`FieldEditWidget`), `ActionParamDialog` /
-   * `BulkActionDialog`, and — since #3233 — the registry adapter that adapts
-   * `SchemaRenderer`'s SDUI node onto this contract (`withFieldCarrier` in
-   * `packages/fields/src/withFieldCarrier.tsx`). A widget reads `props.field`
-   * and nothing else; there is no second key to check.
-   */
-  field: FieldMetadata;
-  readonly?: boolean;
-  disabled?: boolean;
-  className?: string;
-  /**
-   * The active validation message for this field, named as
-   * `@objectstack/spec/ui`'s `FieldWidgetPropsSchema` names it (objectui#3222).
-   *
-   * **Producer**: the form renderer, from react-hook-form's
-   * `fieldState.error?.message` (`packages/components/src/renderers/form/
-   * form.tsx`). Before #3222 nothing in the repo produced it under EITHER
-   * spelling, so the seven widgets computing `aria-invalid={!!errorMessage}`
-   * were computing it from a permanent `undefined` — `aria-invalid` was never
-   * once set and a screen reader was never told the field had failed.
-   *
-   * **Consumer**: a widget reads this ONLY to drive `aria-invalid` on the
-   * control it renders. The message TEXT stays with the form renderer's
-   * `<FormMessage/>`; a widget that also renders it double-displays it.
-   */
-  error?: string;
-  /**
-   * Upload widgets (`file`/`image`) fire this when their in-progress state
-   * flips, so a host can block submit until a presigned upload settles. Other
-   * widgets ignore it.
-   */
-  onUploadingChange?: (uploading: boolean) => void;
-
-  /* ── Host plumbing: what a rendering host actually forwards ─────────────── */
-
-  /**
-   * DataSource for widgets that query records (lookup / user / object-ref /
-   * recipient-picker / grid). Injected by the form renderer for the field
-   * types that need it, and passed directly by inline-edit hosts. Option
-   * widgets destructure it purely to keep it off their DOM spread.
-   *
-   * Left structural (`unknown`): `@object-ui/fields` must not depend on a
-   * concrete adapter — every consumer narrows it itself.
-   */
-  dataSource?: unknown;
-  /**
-   * Live sibling-field values driving cascading / role-gated options and
-   * dependent lookups (ADR-0058, #2215/#2284). The form renderer passes the
-   * in-progress record; widgets fall back to `SchemaRendererContext`.
-   */
-  dependentValues?: Record<string, unknown>;
-  /**
-   * Controlling field(s) that gate this field's option list. Normally declared
-   * on the field metadata; accepted as a prop so a host can drive the gate for
-   * a field it synthesised. Field metadata wins when both are present.
-   */
-  dependsOn?: DependsOnInput;
-  /**
-   * Controlling-field name → its human LABEL, for widgets that have to NAME a
-   * sibling field in user-visible copy (the dependent-lookup gate hint).
-   *
-   * Only the form renderer knows a field's label — the widget sees its own
-   * metadata and a `depends_on` list of API names. Without this map the gate
-   * sentence interpolated the raw API name into every locale, `en` included
-   * ("Select crm_account first"), which is an internal identifier leaking into
-   * the UI, not merely an untranslated word (objectstack#5407). This is the
-   * lookup-side counterpart of `emptyHint`, which the form already resolves to
-   * labels for the fixed-option widgets. A name with no entry falls back to
-   * itself, so a host that passes nothing renders exactly what it did before.
-   */
-  dependsOnLabels?: Record<string, string>;
-  /**
-   * Hint shown when an option list cannot be filled — typically a
-   * dependency-gated list still waiting on its controlling field (#2284).
-   * Forwarded by the form renderer, which resolves the controlling fields to
-   * their human LABELS. **When supplied it wins**; the option widgets fall back
-   * to their own translated copy only when a host computed none (objectui#3231
-   * — they used to discard this prop and always render their own hardcoded
-   * English). See `OptionsEmptyState`, the single consumer.
-   */
-  emptyHint?: string;
-  /**
-   * Render as a single-line, borderless control for a grid cell (the inline
-   * editor and the line-item grid set it) instead of the full form layout.
-   */
-  compact?: boolean;
-  /**
-   * Receive the FULL selected record rather than just its id, so a host can
-   * auto-fill sibling fields from it (a line-item grid copying a product's
-   * price). When provided, the host owns the resulting value change.
-   */
-  onSelectRecord?: (record: Record<string, any>) => void;
-  /**
-   * Offer a "create new" affordance in a record picker, carrying whatever the
-   * user had typed. Also declarable on the field metadata.
-   */
-  onCreateNew?: (searchQuery: string) => void;
-
-  /* ── DOM pass-through ───────────────────────────────────────────────────── */
-  //
-  // Lives in the named {@link FieldWidgetDomProps} above, because that is what
-  // lets the compiler bind the declaration to `toDomProps` — its runtime
-  // executor — in BOTH directions (objectui#3291). Add a DOM key THERE, not
-  // here, and the compiler will make you add it to the whitelist too.
-} & FieldWidgetDomProps & AriaAttributes & {
-  /**
-   * Arbitrary `data-*` attributes (test ids, analytics hooks). Open by design,
-   * but a template-literal key — `keyof` stays finite, so this does NOT
-   * reintroduce the index signature objectui#3221 removed: `props.required`
-   * is still an error, `props['data-testid']` is still fine.
-   */
-  [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
-};

package/src/widgets/useCascadingOptions.ts

@@ -1,46 +0,0 @@
-import { useContext, useMemo } from 'react';
-import {
-  resolveCascadingOptions,
-  type CascadingOptions,
-  type OptionLike,
-  type DependsOnInput,
-} from '@object-ui/core';
-import { SchemaRendererContext, usePredicateScope } from '@object-ui/react';
-
-/**
- * Shared per-option cascading / role-gating resolution for the option widgets
- * (`SelectField` single, `MultiSelectField`, `RadioField`) — the client half of
- * ADR-0058 (#2284). Each option may carry a `visibleWhen` CEL predicate; the
- * offered set narrows against the live form record (`record.country == 'cn'`) +
- * the global predicate scope (`'admin' in current_user.positions`). A field
- * declares which sibling fields drive its list via `dependsOn`; while any is
- * empty the list is *gated* — callers surface a "select the parent first" hint
- * rather than an unfiltered set, mirroring the dependent-lookup UX.
- *
- * This is the React wrapper that sources `record` (the live form values) and the
- * predicate scope from context; the actual resolution is the pure
- * {@link resolveCascadingOptions} in `@object-ui/core`, shared with the form
- * renderer so gating/filtering can never drift between them (#2715).
- */
-export type CascadingOptionsResult<T extends OptionLike> = CascadingOptions<T>;
-
-export function useCascadingOptions<T extends OptionLike>(
-  rawOptions: readonly T[],
-  dependsOn: DependsOnInput,
-  dependentValues: Record<string, unknown> | undefined,
-): CascadingOptionsResult<T> {
-  // Live form values for cascading options — injected by the form renderer as
-  // `dependentValues` (same channel dependent lookups use), falling back to the
-  // record on SchemaRendererContext. `current_user` etc. come from the global
-  // predicate scope so role/context predicates resolve too.
-  const ctx = useContext(SchemaRendererContext) as any;
-  const record = useMemo<Record<string, unknown>>(() => {
-    return (dependentValues ?? ctx?.formValues ?? ctx?.data ?? {}) as Record<string, unknown>;
-  }, [dependentValues, ctx?.formValues, ctx?.data]);
-  const predicateScope = usePredicateScope();
-
-  return useMemo(
-    () => resolveCascadingOptions(rawOptions, record, dependsOn, predicateScope),
-    [rawOptions, record, dependsOn, predicateScope],
-  );
-}

package/src/widgets/useFieldTranslation.ts

@@ -1,132 +0,0 @@
-/**
- * Safe translation hook for field widgets.
- * Falls back to English defaults when no I18nProvider is available.
- */
-import { createSafeTranslation } from '@object-ui/i18n';
-
-const FIELD_DEFAULTS: Record<string, string> = {
-  'common.selectOption': 'Select an option',
-  'common.select': 'Select…',
-  'common.loading': 'Loading…',
-  'common.noResults': 'No results found',
-  'common.cancel': 'Cancel',
-  'common.confirm': 'Confirm',
-  'table.selected': '{{count}} selected',
-  'table.search': 'Search…',
-  'lookup.loading': 'Loading…',
-  'lookup.noOptions': 'No options found',
-  'lookup.noRecords': 'No records found',
-  'lookup.recentlyUsed': 'Recently used',
-  'lookup.allResults': 'All results',
-  'lookup.createNew': 'Create new',
-  'lookup.createNamed': 'Create new "{{name}}"',
-  'lookup.showingResults': 'Showing {{shown}} of {{total}} results',
-  'lookup.showAllResults': 'Show all results ({{count}})',
-  'lookup.selectedBadge': 'Selected',
-  'lookup.browseAll': 'Browse all records',
-  'lookup.remove': 'Remove {{label}}',
-  'lookup.selectFirst': 'Select {{fields}} first',
-  'lookup.selectRecord': 'Select record',
-  'lookup.recordCount': '{{count}} records',
-  'lookup.recordCountOne': '1 record',
-  'lookup.pageOf': 'Page {{current}} of {{total}}',
-  'lookup.filters': 'Filters',
-  'lookup.clear': 'Clear',
-  'lookup.yes': 'Yes',
-  'lookup.filterPlaceholder': 'Filter {{label}}',
-  'lookup.prevPage': 'Previous page',
-  'lookup.nextPage': 'Next page',
-  'lookup.jumpToPage': 'Jump to page',
-  'lookup.retry': 'Retry',
-  // objectui#3231 — the empty / dependency-gated state of the fixed-option
-  // widgets (select, multiselect, radio, checkboxes). Only used when the host
-  // supplies no `emptyHint`; the gate sentence shares its key with the form
-  // renderer so both cannot drift apart in a locale.
-  'fields.options.empty': 'No options available',
-  'fields.options.selectFirst': 'Select {{fields}} first',
-  // objectstack#3821 — sharing-rule authoring widgets (object-ref /
-  // recipient-picker / filter-condition). The recipient placeholder is keyed
-  // PER TYPE rather than interpolating the enum value into an English
-  // sentence, which no locale could translate.
-  'fields.objectRef.loading': 'Loading objects…',
-  'fields.objectRef.placeholder': 'Select an object',
-  'fields.objectRef.search': 'Search objects…',
-  'fields.objectRef.empty': 'No objects found',
-  'fields.recipient.selectTypeFirst': 'Select a recipient type first.',
-  'fields.recipient.loading': 'Loading…',
-  'fields.recipient.search': 'Search…',
-  'fields.recipient.empty': 'No matches',
-  'fields.recipient.select': 'Select a recipient',
-  'fields.recipient.selectUser': 'Select a user',
-  'fields.recipient.selectTeam': 'Select a team',
-  'fields.recipient.selectBusinessUnit': 'Select a business unit',
-  'fields.recipient.selectPosition': 'Select a position',
-  'fields.recipient.selectUnitAndSubordinates': 'Select a business unit',
-  'fields.filterCondition.selectObjectFirst': 'Select an object first.',
-  // objectstack#3896 — this used to be 'All records'. An empty criteria never
-  // meant "share everything"; it meant the predicate was missing, and the
-  // sharing evaluator failed open on it. Such a rule is now refused on save
-  // and shares nothing, so say that rather than advertise the old bug.
-  'fields.filterCondition.noCriteria': 'No criteria — this rule shares nothing',
-  'fields.filterCondition.criteriaRequired':
-    'Add at least one condition. A rule with no criteria would share every record, so it cannot be saved.',
-  'fields.filterCondition.invalidJson': 'Invalid JSON — the rule will match no records until fixed.',
-  'fields.filterCondition.jsonOnly': 'This criteria can only be edited as JSON',
-  'fields.filterCondition.editAsJson': 'Edit as JSON',
-  'fields.filterCondition.useVisualBuilder': 'Use visual builder',
-  // objectui#3342 — the tags widget's input hint. Used only when the field
-  // author declared no `placeholder` of their own (author declaration wins).
-  'fields.tags.placeholder': 'Type and press Enter to add…',
-  // objectui#3406 — the accessible name of `TextAreaField`'s character
-  // counter, rendered only when the field declares `maxLength`. The visible
-  // `{n}/{max}` is digits; this sentence is what a screen reader speaks, and
-  // the element is `aria-live`, so before the key existed a non-English
-  // session heard English on every keystroke. Byte-identical to the literal
-  // it replaces, so a no-provider render is unchanged.
-  'fields.textarea.characterCount': 'Character count: {{count}} of {{max}}',
-  // objectui#3408 — the NEAR-LIMIT warning, spoken by the counter's status
-  // region after the typist pauses and only once they are inside the last 10%
-  // (or last 20 characters) of the cap. The sentence above became the field's
-  // `aria-describedby` description in the same change; this one is the only
-  // thing that is ever announced mid-typing, which is why it says what is
-  // LEFT rather than repeating the whole count.
-  //
-  // Colon form, not "You have {{count}} characters remaining": `count` makes
-  // i18next attempt plural lookup (`_one` / `_few` / …) before the base key,
-  // and these packs declare the base key only — the same base-key fallback
-  // `characterCount` already relies on. A sentence whose grammar does not
-  // depend on the number stays correct at 1 without ten plural entries per
-  // pack, and matches the sibling key's shape.
-  'fields.textarea.charactersRemaining': 'Characters remaining: {{count}}',
-  // The fullscreen long-text dialog's copy (objectui#3404) is NOT declared
-  // here any more. It moved with the implementation: `FullscreenFieldEditor` is
-  // a thin wrapper over `FullscreenEditor` in `@object-ui/components`
-  // (objectui#3398), and that primitive carries its own `createSafeTranslation`
-  // defaults for the same `form.fullscreen.*` / `common.cancel` keys — still
-  // the built-in branch's keys, still byte-identical English, so provider-less
-  // rendering is unchanged and the ten locale packs need no edit. Leaving the
-  // entries here would have re-created in the defaults map exactly the
-  // duplication #3398 removed from the components, and this map's own
-  // discipline is that a default is declared where it is read.
-  //
-  // `common.cancel` stays above: `RecordPickerDialog` and `PeoplePicker` read
-  // it independently of anything fullscreen.
-  // objectui#2600 B5 — capability picker scope group headers.
-  'capability.group.platform': 'Platform',
-  'capability.group.org': 'Organization',
-  'capability.group.other': 'Other',
-  // objectui#2600 B5 — curated platform capability labels (registry serves
-  // English; dots in the api-name become underscores in the key).
-  'capability.label.manage_users': 'Manage Users',
-  'capability.label.manage_org_users': 'Manage Organization Users',
-  'capability.label.manage_metadata': 'Manage Metadata',
-  'capability.label.manage_platform_settings': 'Manage Platform Settings',
-  'capability.label.setup_access': 'Setup Access',
-  'capability.label.setup_write': 'Write Settings',
-  'capability.label.studio_access': 'Studio Access',
-};
-
-export const useFieldTranslation = createSafeTranslation(
-  FIELD_DEFAULTS,
-  'common.selectOption',
-);

package/src/widgets/useRecordQuery.test.ts

@@ -1,174 +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 { 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([]);
-  });
-});