Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 968dc1e

Browse files
os-warrenclaude
andauthored
feat(types): declare dependsOn on BaseFieldMetadata in the spec's field-level shape; widgets read it through the declared type (objectui#6153) (#8609)
* feat(types): declare `dependsOn` on BaseFieldMetadata in the spec's field-level shape; widgets read it through the declared type `BaseFieldMetadata` gains `dependsOn?: FieldDependsOn`, derived by reference from `@objectstack/spec/data`'s `Field` — an array of controlling field names or `{ field, param }` entries, never a bare string (the installed spec 17.3.0 answers `invalid_type` to one on a field document). The four option widgets read it as `field?.dependsOn ?? dependsOnProp` instead of through `as any`; `LookupField` reads both of its spellings (`depends_on`, then `dependsOn`) through `LookupFieldMetadata`, keeping the snake_case arm for objectui#7357 to retire. Docs for select and lookup document `dependsOn` as a metadata key again; two changesets (`@object-ui/types` minor, `@object-ui/fields` patch). Pins: type-level membership and shape, the installed spec's two-control answer, annotated `SelectFieldMetadata` / `LookupFieldMetadata` literals with no cast, read-site text pins at all five readers, and runtime gate / cascade / `$filter` scoping through the declared type. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jmxdo7bmeqCQHLSfmLVX9w * test(plugin-grid): the copy-set extractor follows annotated aliases of its receiver (objectui#6153 patch round) `relationalMetaCopySet.derivation.test.ts` re-extracts LookupField's reads by scanning for member accesses off the receiver `fieldMeta`. objectui#6153 moved the cascade read through an annotated alias (`const cascadeMeta: LookupFieldMetadata | undefined = fieldMeta;`), so the scanner reported `dependsOn` / `depends_on` as orphans while LookupField still reads both. The reads are real; the scanner's reach was the gap. `memberReads` now also sweeps every `const NAME(: TYPE)? = receiver;` alias, derived from the consumer's source on each run (no alias is listed here), with a positive control for the two keys, an inline-fixture control pinning what the alias rule reaches and what it must not, and the real consumers' alias census (`['fieldMeta', 'cascadeMeta']` / `['meta']`). The copy-set table is untouched: removing the reader entries would have asserted a read that did not stop. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jmxdo7bmeqCQHLSfmLVX9w --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent b1a14f2 commit 968dc1e

16 files changed

Lines changed: 699 additions & 34 deletions
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@object-ui/fields': patch
3+
---
4+
5+
The option widgets and the lookup read `dependsOn` through the declared type.
6+
7+
`SelectField`, `MultiSelectField`, `RadioField` and `CheckboxesField` now read the
8+
cascade key as `field.dependsOn` — `BaseFieldMetadata.dependsOn` — instead of
9+
through an `as any`; `LookupField` reads both of its spellings (`depends_on`, then
10+
`dependsOn`) through `LookupFieldMetadata`. Behaviour is unchanged: a select whose
11+
metadata carries `dependsOn` still gates and prunes its options, a lookup still
12+
scopes its candidate queries, and the metadata key still wins over the `dependsOn`
13+
widget prop. What changed is that a wrong spelling or shape at the read site is now
14+
a compile error rather than a silent no-op. objectui#6153.
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
'@object-ui/types': minor
3+
---
4+
5+
`dependsOn` is now a declared member of the field-metadata face.
6+
7+
`BaseFieldMetadata` gains `dependsOn?: FieldDependsOn`, the spec's field-level
8+
cascade key in the spec's own shape — derived from `@objectstack/spec/data`'s
9+
`Field` by reference: an array of controlling field names, or `{ field, param }`
10+
entries. Every field type inherits it, so an annotated `SelectFieldMetadata` or
11+
`LookupFieldMetadata` literal can now carry the key the running widgets have
12+
honoured all along; before, the excess-property check refused it and the widgets
13+
reached it through an `as any`. A bare parent name is refused at the type, as the
14+
spec refuses it at publish (`invalid_type`) — that shape belongs to the form-level
15+
`FormField.dependsOn` and to the `dependsOn` widget prop. `FieldDependsOn` is
16+
exported.
17+
18+
The snake_case `depends_on` stays declared for now: it is objectui's legacy twin,
19+
never a spec key, and retires on its own card (objectui#7357). Maintainer ruling A
20+
on objectui#6153.

‎content/docs/fields/lookup.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,33 @@ and must never reach authored object metadata
7777
`dataSource` a host injects and the `onCreateNew` callback it passes are widget props,
7878
not metadata.
7979

80+
A **dependent lookup** scopes its candidates by a sibling field's value, declared
81+
with `dependsOn` — the same `BaseFieldMetadata` member the select widgets gate on
82+
([objectui#6153](https://github.com/objectstack-ai/objectui/issues/6153)), in the
83+
spec's field-level shape: an array of controlling field names, or `{ field, param }`
84+
entries when the remote filter parameter differs from the local field name. While
85+
any controlling value is empty the trigger is gated ("Select account first"); once
86+
set, every candidate query — the typeahead popover, the Record Picker and the
87+
people picker — carries the chain as a hard `$filter` no user input can override.
88+
89+
```ts
90+
import type { LookupFieldMetadata } from '@object-ui/types';
91+
92+
const contact: LookupFieldMetadata = {
93+
type: 'lookup',
94+
name: 'contact',
95+
label: 'Contact',
96+
reference_to: 'contacts',
97+
// Filter `contacts` by `account_id` equal to the form's current `account`.
98+
dependsOn: [{ field: 'account', param: 'account_id' }],
99+
};
100+
```
101+
102+
The snake_case `depends_on` is objectui's legacy twin of the same key: still read
103+
by this widget, never a spec key, and retiring under
104+
[objectui#7357](https://github.com/objectstack-ai/objectui/issues/7357) — author
105+
`dependsOn`.
106+
80107
The value being edited, and the `className` / `disabled` a host supplies, are **not**
81108
metadata keys — they are runtime widget props. See [Field Widget Props](/docs/fields/widget-props).
82109

‎content/docs/fields/select.mdx‎

Lines changed: 33 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ cascade-clear propagate down the chain.
8484
`visibleWhen` options are for **small, static dictionaries** (category →
8585
subcategory, a handful of provinces). When the data is large, changes over time,
8686
or is shared across forms (real country/province/city tables, org units, product
87-
catalogs), model each level as a **`lookup`** with `depends_on` instead — the
87+
catalogs), model each level as a **`lookup`** with `dependsOn` instead — the
8888
candidate query is filtered server-side and paginated. See
8989
[Lookup Field](/docs/fields/lookup).
9090

@@ -116,11 +116,38 @@ const status: SelectFieldMetadata = {
116116
};
117117
```
118118

119-
Cascading option lists are driven by a sibling field's value. The widget reads a
120-
camelCase `dependsOn` off the metadata, but no exported metadata type declares it —
121-
`BaseFieldMetadata` declares the snake_case `depends_on` instead — so the two
122-
spellings disagree and the gap is tracked as
123-
[objectui#6153](https://github.com/objectstack-ai/objectui/issues/6153).
119+
Cascading option lists are driven by a sibling field's value, declared with
120+
`dependsOn` — a `BaseFieldMetadata` member every field type inherits
121+
([objectui#6153](https://github.com/objectstack-ai/objectui/issues/6153)), in the
122+
shape `@objectstack/spec` declares at field level: an **array** of controlling
123+
field names, or `{ field, param }` entries when the remote parameter name differs
124+
from the local field name. While any controlling value is empty the widget is
125+
gated; once it is set, each option's `visibleWhen` decides whether it is offered,
126+
and a selection the parent no longer offers is cleared.
127+
128+
```ts
129+
import type { SelectFieldMetadata } from '@object-ui/types';
130+
131+
const province: SelectFieldMetadata = {
132+
type: 'select',
133+
name: 'province',
134+
label: 'Province',
135+
dependsOn: ['country'],
136+
options: [
137+
{ label: 'Zhejiang', value: 'zj', visibleWhen: "record.country == 'cn'" },
138+
{ label: 'California', value: 'ca', visibleWhen: "record.country == 'us'" },
139+
],
140+
};
141+
```
142+
143+
A bare parent name (`dependsOn: "country"`, as in the form schema above) is the
144+
**form-level** shape, `FormField.dependsOn`; on field metadata the spec accepts
145+
only the array, and `SelectFieldMetadata` refuses the string for the same reason.
146+
The metadata key wins over the `dependsOn` widget prop a host may pass. The
147+
snake_case `depends_on` is objectui's legacy twin of the same key — read only by
148+
the lookup widget and retiring under
149+
[objectui#7357](https://github.com/objectstack-ai/objectui/issues/7357); author
150+
`dependsOn`.
124151

125152
The value being edited, and the `className` / `disabled` a host supplies, are **not**
126153
metadata keys — they are runtime widget props. See [Field Widget Props](/docs/fields/widget-props).

‎packages/fields/src/widgets/CheckboxesField.tsx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ export function CheckboxesField({
4040
const groupId = useId();
4141
const fieldName = props.name || config?.name || props.id || '';
4242

43-
const dependsOn = config?.dependsOn ?? dependsOnProp;
43+
// Read through the declared type, not the untyped carrier (objectui#6153) — see SelectField.
44+
const dependsOn = field?.dependsOn ?? dependsOnProp;
4445
const { options, gated, dependsOnFields } = useCascadingOptions<Option>(
4546
rawOptions,
4647
dependsOn,
Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* A lookup whose METADATA carries `dependsOn` scopes its candidates — read
5+
* through the DECLARED type (objectui#6153, instance 1; maintainer ruling A,
6+
* 2026-09-02).
7+
*
8+
* `LookupField.dependsOn.test.tsx` (#2215) proves the gate and the hard
9+
* `$filter` through the legacy `depends_on` spelling on an `as any` literal.
10+
* This file proves the same two facts through the spec's field-level spelling
11+
* on ANNOTATED `LookupFieldMetadata` literals with NO cast — the
12+
* excess-property check refused `dependsOn` on this exact document before the
13+
* declaration landed (compile half), and the widget still gates and scopes on
14+
* it (runtime half). Both spellings stay readable until objectui#7357 retires
15+
* the snake_case twin; that card, not this one, drops the arm.
16+
*/
17+
18+
import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
19+
import { describe, it, expect, vi, beforeEach } from 'vitest';
20+
import type { LookupFieldMetadata } from '@object-ui/types';
21+
import { LookupField } from './LookupField';
22+
23+
const contacts = [
24+
{ id: 'c1', name: 'Nora Field', account: 'a1' },
25+
{ id: 'c2', name: 'Oscar Grant', account: 'a2' },
26+
];
27+
28+
function makeDataSource() {
29+
const find = vi.fn(async (_obj: string, params: { $filter?: Record<string, unknown> } | undefined) => {
30+
const account = params?.$filter?.account ?? params?.$filter?.account_id;
31+
const data = account ? contacts.filter((c) => c.account === account) : contacts;
32+
return { data, total: data.length };
33+
});
34+
return { find } as never;
35+
}
36+
37+
beforeEach(() => {
38+
// jsdom has no matchMedia; the people-picker branch's useIsMobile needs it.
39+
Object.defineProperty(window, 'innerWidth', { writable: true, configurable: true, value: 1280 });
40+
window.matchMedia = ((query: string) => ({
41+
matches: false,
42+
media: query,
43+
onchange: null,
44+
addListener: () => {},
45+
removeListener: () => {},
46+
addEventListener: () => {},
47+
removeEventListener: () => {},
48+
dispatchEvent: () => false,
49+
})) as never;
50+
});
51+
52+
// The literal `content/docs/fields/lookup.mdx` teaches — annotated, uncast.
53+
const contactField: LookupFieldMetadata = {
54+
type: 'lookup',
55+
name: 'contact',
56+
label: 'Contact',
57+
reference_to: 'contacts',
58+
reference_field: 'name',
59+
dependsOn: [{ field: 'account', param: 'account_id' }],
60+
};
61+
62+
const shorthandField: LookupFieldMetadata = {
63+
...contactField,
64+
dependsOn: ['account'],
65+
};
66+
67+
// `dependentValues` is a HOST prop (the form renderer's channel), not metadata.
68+
const host = (dependentValues: Record<string, unknown>) => ({ dependentValues }) as Record<string, unknown>;
69+
70+
describe('LookupField — `dependsOn` off the DECLARED metadata type (objectui#6153)', () => {
71+
it('gates the trigger while the controlling field is empty', () => {
72+
render(
73+
<LookupField
74+
field={contactField}
75+
value={undefined}
76+
onChange={vi.fn()}
77+
readonly={false}
78+
dataSource={makeDataSource()}
79+
{...host({ account: null })}
80+
/>,
81+
);
82+
const trigger = screen.getByTestId('lookup-trigger-gated');
83+
expect(trigger).toBeDisabled();
84+
expect(trigger).toHaveTextContent(/select account first/i);
85+
});
86+
87+
it('scopes the candidate query by the `{ field, param }` entry once the parent is set', async () => {
88+
const ds = makeDataSource();
89+
render(
90+
<LookupField
91+
field={contactField}
92+
value={undefined}
93+
onChange={vi.fn()}
94+
readonly={false}
95+
dataSource={ds}
96+
{...host({ account: 'a1' })}
97+
/>,
98+
);
99+
100+
const trigger = screen.getByRole('button', { name: /select/i });
101+
expect(trigger).not.toBeDisabled();
102+
await act(async () => {
103+
fireEvent.click(trigger);
104+
});
105+
106+
await waitFor(() => {
107+
expect((ds as { find: ReturnType<typeof vi.fn> }).find).toHaveBeenCalledWith(
108+
'contacts',
109+
expect.objectContaining({ $filter: expect.objectContaining({ account_id: 'a1' }) }),
110+
);
111+
});
112+
await waitFor(() => {
113+
expect(screen.getByText('Nora Field')).toBeInTheDocument();
114+
expect(screen.queryByText('Oscar Grant')).not.toBeInTheDocument();
115+
});
116+
});
117+
118+
it('the shorthand `[name]` entry filters by the sibling name itself', async () => {
119+
const ds = makeDataSource();
120+
render(
121+
<LookupField
122+
field={shorthandField}
123+
value={undefined}
124+
onChange={vi.fn()}
125+
readonly={false}
126+
dataSource={ds}
127+
{...host({ account: 'a1' })}
128+
/>,
129+
);
130+
await act(async () => {
131+
fireEvent.click(screen.getByRole('button', { name: /select/i }));
132+
});
133+
await waitFor(() => {
134+
expect((ds as { find: ReturnType<typeof vi.fn> }).find).toHaveBeenCalledWith(
135+
'contacts',
136+
expect.objectContaining({ $filter: expect.objectContaining({ account: 'a1' }) }),
137+
);
138+
});
139+
});
140+
});

‎packages/fields/src/widgets/LookupField.tsx‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import { cn,
1212
import { Search, X, Loader2, AlertCircle, Plus, TableProperties } from 'lucide-react';
1313
import { FieldWidgetComponentProps } from './types.js';
1414
import { toDomProps } from './toDomProps.js';
15-
import type { DataSource, QueryParams, LookupColumnDef } from '@object-ui/types';
15+
import type { DataSource, QueryParams, LookupColumnDef, LookupFieldMetadata } from '@object-ui/types';
1616
import { RecordPickerDialog, lookupFiltersToRecord } from './RecordPickerDialog.js';
1717
import type { RecordPickerFilterColumn } from './RecordPickerDialog.js';
1818
import { PeoplePicker } from './PeoplePicker.js';
@@ -288,24 +288,33 @@ export function LookupField({ value, onChange, field, readonly, error: fieldErro
288288
* Dependent lookups — restrict candidates based on values of *other* fields
289289
* in the same form. Two shapes are accepted:
290290
*
291-
* 1. `depends_on: ['country']` → shorthand. The dependent field value is sent
291+
* 1. `dependsOn: ['country']` → shorthand. The dependent field value is sent
292292
* as both the filter field and the source field (i.e. `country = ${country}`).
293-
* 2. `depends_on: [{ field: 'country', param: 'country_id' }]` → explicit.
293+
* 2. `dependsOn: [{ field: 'country', param: 'country_id' }]` → explicit.
294294
* The remote field name (`param`) can differ from the local field name.
295295
*
296+
* The key is read THROUGH THE DECLARED TYPE (objectui#6153): `dependsOn` is
297+
* `BaseFieldMetadata.dependsOn`, the spec's field-level spelling; `depends_on`
298+
* is objectui's legacy twin, still declared and still honoured until
299+
* objectui#7357 retires it — that card drops the snake_case arm below. Only
300+
* this cascade read goes through `LookupFieldMetadata`; the rest of
301+
* `fieldMeta` stays untyped because its camelCase-fallback family
302+
* (`displayField`, `descriptionField`, …) is objectui#4631's population.
303+
*
296304
* When any dependency is empty, the lookup is gated and the user sees a
297305
* helpful "Select {field} first" hint instead of unfiltered records.
298306
*/
307+
const cascadeMeta: LookupFieldMetadata | undefined = fieldMeta;
299308
const dependsOn = useMemo<Array<{ field: string; param: string }>>(() => {
300-
const raw = fieldMeta?.depends_on ?? fieldMeta?.dependsOn;
301-
if (!raw) return [];
302-
if (Array.isArray(raw)) {
303-
return raw.map((d: any) =>
304-
typeof d === 'string' ? { field: d, param: d } : { field: d.field, param: d.param ?? d.field },
305-
);
306-
}
307-
return [];
308-
}, [fieldMeta?.depends_on, fieldMeta?.dependsOn]);
309+
const raw = cascadeMeta?.depends_on ?? cascadeMeta?.dependsOn;
310+
// A bare parent name is the FORM-level shape (`FormField.dependsOn`), not the
311+
// field-level one the spec declares (array only) — an untyped host handing
312+
// one through still gets no cascade here, exactly as before.
313+
if (!raw || !Array.isArray(raw)) return [];
314+
return raw.map((d) =>
315+
typeof d === 'string' ? { field: d, param: d } : { field: d.field, param: d.param ?? d.field },
316+
);
317+
}, [cascadeMeta?.depends_on, cascadeMeta?.dependsOn]);
309318

310319
/**
311320
* The gate sentence's `{{fields}}` — the controlling fields named the way the

‎packages/fields/src/widgets/MultiSelectField.tsx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,8 @@ export function MultiSelectField({
4141
const selected: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
4242
const fieldName = props.name || config?.name || props.id || '';
4343

44-
const dependsOn = config?.dependsOn ?? dependsOnProp;
44+
// Read through the declared type, not the untyped carrier (objectui#6153) — see SelectField.
45+
const dependsOn = field?.dependsOn ?? dependsOnProp;
4546
const { options, gated, dependsOnFields } = useCascadingOptions<Option>(
4647
rawOptions,
4748
dependsOn,

‎packages/fields/src/widgets/RadioField.tsx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,8 @@ export function RadioField({
3939
const groupId = useId();
4040
const fieldName = props.name || config?.name || props.id || '';
4141

42-
const dependsOn = config?.dependsOn ?? dependsOnProp;
42+
// Read through the declared type, not the untyped carrier (objectui#6153) — see SelectField.
43+
const dependsOn = field?.dependsOn ?? dependsOnProp;
4344
const { options, gated, dependsOnFields } = useCascadingOptions<Option>(
4445
rawOptions,
4546
dependsOn,

0 commit comments

Comments
 (0)