Discriminate multiple property in LookupField configuration

Author: mstijak

homedocs/package.json

@@ -9,7 +9,7 @@
     "preview": "astro preview",
     "astro": "astro",
     "prettify": "prettier --write .",
-    "check-types": "tsc --noEmit"
+    "check-types": "npx tsc --noEmit"
   },
   "dependencies": {
     "@astrojs/mdx": "^4.3.13",

homedocs/src/examples/forms/InfiniteLookupListExample.tsx

@@ -51,7 +51,7 @@ const cityDb: City[] = Array.from({ length: 5000 }, (_, i) => ({
 // @model-end
 
 // @controller
-class PageController extends Controller<typeof m> {
+class PageController extends Controller {
   onQueryPage(params: { query: string; pageSize: number; page: number }) {
     let { query, pageSize, page } = params;
     let regex = new RegExp(query, "gi");

homedocs/src/pages/docs/intro/breaking-changes.mdx

@@ -13,10 +13,13 @@ versions of the framework.
 
 ## 26.2.0
 
-### LookupField: `onQueryPage` replaces `onQuery` for infinite mode
+### LookupField: Improved TypeScript discrimination
+
+The `LookupField` component now uses TypeScript discriminated unions based on the `infinite` and `multiple` props. This provides better type inference and catches invalid prop combinations at compile time.
+
+#### `onQueryPage` replaces `onQuery` for infinite mode
 
 When using `LookupField` with `infinite: true`, you must now use the `onQueryPage` prop instead of `onQuery`.
-This change improves TypeScript type inference by providing distinct callback signatures for standard and infinite modes.
 
 **Before:**
 ```tsx
@@ -44,6 +47,17 @@ The `onQuery` prop now only accepts a string query parameter for standard (non-i
 
 **Backwards Compatibility:** The runtime includes a compatibility shim that copies `onQuery` to `onQueryPage` when `infinite: true` is set. This allows existing code to continue working, but TypeScript will report type errors. We recommend updating your code to use the new API.
 
+#### `pageSize` is now exclusive to infinite mode
+
+The `pageSize` prop is now only available when `infinite: true`. If you were using `pageSize` without `infinite`, remove it as it had no effect.
+
+#### Props are now discriminated by `multiple`
+
+- When `multiple: true`: use `records` and/or `values` props
+- When `multiple` is not set or `false`: use `value` and `text` props
+
+TypeScript will now report errors if you mix props from different modes (e.g., using `value` with `multiple: true`).
+
 ## 26.1.0
 
 ### TypeScript Migration

packages/cx/src/widgets/form/LookupField.tsx

@@ -65,23 +65,7 @@ export interface LookupFieldPagedQueryParams {
 }
 
 /** Common LookupField properties shared across all variants */
-interface LookupFieldBaseConfig<TOption = unknown, TRecord = unknown>
-  extends FieldConfig {
-  /** Defaults to `false`. Set to `true` to enable multiple selection. */
-  multiple?: BooleanProp;
-
-  /** Selected value. Used only if `multiple` is set to `false`. */
-  value?: Prop<number | string>;
-
-  /** A list of selected ids. Used only if `multiple` is set to `true`. */
-  values?: Prop<(number | string)[]>;
-
-  /** A list of selected records. Used only if `multiple` is set to `true`. */
-  records?: Prop<TRecord[]>;
-
-  /** Text associated with the selection. Used only if `multiple` is set to `false`. */
-  text?: StringProp;
-
+interface LookupFieldBaseConfig<TOption = unknown> extends FieldConfig {
   /** The opposite of `disabled`. */
   enabled?: BooleanProp;
 
@@ -175,20 +159,12 @@ interface LookupFieldBaseConfig<TOption = unknown, TRecord = unknown>
   /** Allow dropdown enter key events to propagate for form submission. */
   submitOnDropdownEnterKey?: BooleanProp;
 
-  /** Number of items per page. Default is `100`. */
-  pageSize?: number;
-
   /** Allow quick selection of all displayed items on `Ctrl + A` key combination. */
   quickSelectAll?: boolean;
 
   /** Parameters that affect filtering. */
   filterParams?: StructuredProp;
 
-  /** Used in multiple selection lookups to construct display text from multiple fields. */
-  onGetRecordDisplayText?:
-    | ((record: TRecord, instance: Instance) => string)
-    | null;
-
   /** Callback to create a filter function for given filter params. */
   onCreateVisibleOptionsFilter?:
     | string
@@ -210,42 +186,104 @@ interface LookupFieldBaseConfig<TOption = unknown, TRecord = unknown>
       ) => unknown);
 }
 
-/** LookupField with infinite scrolling - uses onQueryPage */
-interface LookupFieldInfiniteConfig<TOption = unknown, TRecord = unknown>
-  extends LookupFieldBaseConfig<TOption, TRecord> {
+// =============================================================================
+// Composable interfaces for discriminated union
+// =============================================================================
+
+/** Props for infinite mode: uses onQueryPage */
+interface LookupFieldInfiniteProps<TOption = unknown> {
   /** Enable infinite scrolling. */
   infinite: true;
-
-  /** Query function for infinite mode - receives paged query params. */
+  /** Number of items per page. Default is `100`. */
+  pageSize?: number;
+  /** Query function for infinite mode. */
   onQueryPage:
     | string
     | ((
         params: LookupFieldPagedQueryParams,
         instance: Instance
       ) => TOption[] | Promise<TOption[]>);
-
-  /** Not available in infinite mode. Use onQueryPage instead. */
+  /** Not available in infinite mode. */
   onQuery?: never;
 }
 
-/** LookupField standard mode - uses onQuery */
-interface LookupFieldStandardConfig<TOption = unknown, TRecord = unknown>
-  extends LookupFieldBaseConfig<TOption, TRecord> {
+/** Props for standard mode: uses onQuery */
+interface LookupFieldStandardProps<TOption = unknown> {
   /** Standard mode (no infinite scrolling). */
   infinite?: false;
-
-  /** Query function for standard mode - receives string query. */
+  /** Not available in standard mode. */
+  pageSize?: never;
+  /** Query function for standard mode. */
   onQuery?:
     | string
     | ((query: string, instance: Instance) => TOption[] | Promise<TOption[]>);
-
-  /** Not available in standard mode. Set infinite: true to use onQueryPage. */
+  /** Not available in standard mode. */
   onQueryPage?: never;
 }
 
+/** Props for multiple selection mode */
+interface LookupFieldMultipleProps<TRecord = unknown> {
+  /** Enable multiple selection. */
+  multiple: true;
+  /** A list of selected ids. */
+  values?: Prop<(number | string)[]>;
+  /** A list of selected records. */
+  records?: Prop<TRecord[]>;
+  /** Custom display text for records. */
+  onGetRecordDisplayText?:
+    | ((record: TRecord, instance: Instance) => string)
+    | null;
+  /** Not available in multiple mode. */
+  value?: never;
+  /** Not available in multiple mode. */
+  text?: never;
+}
+
+/** Props for single selection mode */
+interface LookupFieldSingleProps {
+  /** Single selection (default). */
+  multiple?: false;
+  /** Selected value. */
+  value?: Prop<number | string>;
+  /** Text associated with the selection. */
+  text?: StringProp;
+  /** Not available in single mode. */
+  values?: never;
+  /** Not available in single mode. */
+  records?: never;
+  /** Not available in single mode. */
+  onGetRecordDisplayText?: never;
+}
+
+// =============================================================================
+// 4 Discriminated Union Variants (2 infinite × 2 multiple)
+// =============================================================================
+
+type LookupFieldInfiniteMultipleConfig<TOption = unknown, TRecord = unknown> =
+  LookupFieldBaseConfig<TOption> &
+    LookupFieldInfiniteProps<TOption> &
+    LookupFieldMultipleProps<TRecord>;
+
+type LookupFieldInfiniteSingleConfig<TOption = unknown> =
+  LookupFieldBaseConfig<TOption> &
+    LookupFieldInfiniteProps<TOption> &
+    LookupFieldSingleProps;
+
+type LookupFieldStandardMultipleConfig<TOption = unknown, TRecord = unknown> =
+  LookupFieldBaseConfig<TOption> &
+    LookupFieldStandardProps<TOption> &
+    LookupFieldMultipleProps<TRecord>;
+
+type LookupFieldStandardSingleConfig<TOption = unknown> =
+  LookupFieldBaseConfig<TOption> &
+    LookupFieldStandardProps<TOption> &
+    LookupFieldSingleProps;
+
 export type LookupFieldConfig<TOption = unknown, TRecord = unknown> =
-  | LookupFieldInfiniteConfig<TOption, TRecord>
-  | LookupFieldStandardConfig<TOption, TRecord>;
+  | LookupFieldInfiniteMultipleConfig<TOption, TRecord>
+  | LookupFieldInfiniteSingleConfig<TOption>
+  | LookupFieldStandardMultipleConfig<TOption, TRecord>
+  | LookupFieldStandardSingleConfig<TOption>;
 
 export class LookupField<TOption = unknown, TRecord = unknown> extends Field<
   LookupFieldConfig<TOption, TRecord>