cx 26.0.11 → 26.0.13

package/src/widgets/form/LookupField.spec.tsx

@@ -0,0 +1,93 @@
+import { createAccessorModelProxy } from "../../data/createAccessorModelProxy";
+import { LookupField } from "./LookupField";
+
+interface User {
+   id: number;
+   name: string;
+   email: string;
+}
+
+interface SelectedUser {
+   id: number;
+   name: string;
+}
+
+interface Model {
+   users: User[];
+   selectedUsers: SelectedUser[];
+   selectedUserId: number;
+}
+
+describe("LookupField", () => {
+   it("infers TOption from AccessorChain<T[]> in options prop", () => {
+      const model = createAccessorModelProxy<Model>();
+
+      // TOption should be inferred as User from model.users (AccessorChain<User[]>)
+      let widget = (
+         <cx>
+            <LookupField
+               options={model.users}
+               onQuery={(query, instance) => {
+                  // Should return User[]
+                  return [] as User[];
+               }}
+               onCreateVisibleOptionsFilter={(params, instance) => (option) => {
+                  // option should be typed as User
+                  const id: number = option.id;
+                  const name: string = option.name;
+                  const email: string = option.email;
+                  return true;
+               }}
+            />
+         </cx>
+      );
+   });
+
+   it("infers TRecord from AccessorChain<T[]> in records prop", () => {
+      const model = createAccessorModelProxy<Model>();
+
+      // TRecord should be inferred as SelectedUser from model.selectedUsers
+      let widget = (
+         <cx>
+            <LookupField
+               multiple
+               records={model.selectedUsers}
+               onGetRecordDisplayText={(record, instance) => {
+                  // record should be typed as SelectedUser
+                  const id: number = record.id;
+                  const name: string = record.name;
+                  return record.name;
+               }}
+            />
+         </cx>
+      );
+   });
+
+   it("infers both TOption and TRecord from accessor chains", () => {
+      const model = createAccessorModelProxy<Model>();
+
+      let widget = (
+         <cx>
+            <LookupField
+               multiple
+               options={model.users}
+               records={model.selectedUsers}
+               onQuery={(query) => {
+                  // Should return User[]
+                  return [] as User[];
+               }}
+               onCreateVisibleOptionsFilter={(params) => (option) => {
+                  // option should be User
+                  const email: string = option.email;
+                  return true;
+               }}
+               onGetRecordDisplayText={(record) => {
+                  // record should be SelectedUser
+                  const name: string = record.name;
+                  return name;
+               }}
+            />
+         </cx>
+      );
+   });
+});

package/src/widgets/form/LookupField.tsx

@@ -40,7 +40,7 @@ import { AccessorChain, isAccessorChain } from "../../data/createAccessorModelPr
 import type { CxChild, RenderingContext } from "../../ui/RenderingContext";
 import type { DropdownInstance, Instance } from "../../ui/Instance";
 import { FieldConfig } from "./Field";
-import { Prop, BooleanProp, StringProp, DataRecord } from "../../ui/Prop";
+import { Prop, BooleanProp, StringProp, StructuredProp, DataRecord } from "../../ui/Prop";
 
 export interface LookupBinding {
    local: string;
@@ -48,60 +48,155 @@ export interface LookupBinding {
    key?: boolean;
 }
 
-export interface LookupFieldConfig extends FieldConfig {
+export interface LookupFieldConfig<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)[]>;
-   records?: Prop<Record<string, any>[]>;
+
+   /** 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;
+
+   /** The opposite of `disabled`. */
    enabled?: BooleanProp;
+
+   /** Defaults to `false`. Used to make the field read-only. */
+   readOnly?: BooleanProp;
+
+   /** Default text displayed when the field is empty. */
    placeholder?: StringProp;
-   options?: Prop<Record<string, any>[]>;
+
+   /** A list of available options. */
+   options?: Prop<TOption[]>;
+
+   /** Set to `true` to hide the clear button. Default value is `false`. */
    hideClear?: boolean;
+
+   /** Set to `false` to hide the clear button. Default value is `true`. */
    showClear?: boolean;
+
+   /** Set to `true` to display the clear button even if `required` is set. Default is `false`. */
    alwaysShowClear?: boolean;
+
+   /** Base CSS class to be applied to the field. Defaults to `lookupfield`. */
    baseClass?: string;
+
+   /** Name or configuration of the icon to be put on the left side of the input. */
+   icon?: StringProp | Record<string, any>;
+
+   /** Additional config to be applied to all items. */
    itemConfig?: any;
+
+   /** An array of objects describing the mapping of option data to store data. */
    bindings?: LookupBinding[];
+
+   /** A delay in milliseconds between typing stop and query. Default is `150`. */
    queryDelay?: number;
+
+   /** Minimal number of characters required before query is made. */
    minQueryLength?: number;
+
+   /** Set to `true` to hide the search field. */
    hideSearchField?: boolean;
+
+   /** Number of options required to show search field. Defaults to `7`. */
    minOptionsForSearchField?: number;
+
+   /** Text to display while data is being loaded. */
    loadingText?: string;
+
+   /** Error message displayed if server query throws an exception. */
    queryErrorText?: string;
+
+   /** Message to be displayed if no entries match the user query. */
    noResultsText?: string;
+
+   /** Name of the field which holds the id of the option. Default is `id`. */
    optionIdField?: string;
+
+   /** Name of the field which holds the display text of the option. Default is `text`. */
    optionTextField?: string;
+
+   /** Name of the field to store id of selected value in multiple mode. Default is `id`. */
    valueIdField?: string;
+
+   /** Name of the field to store display text of selected value. Default is `text`. */
    valueTextField?: string;
+
+   /** `onQuery` will be called once to fetch all options; filtering occurs client-side. */
    fetchAll?: boolean;
+
+   /** When set with `fetchAll`, fetched options are cached for widget lifetime. */
    cacheAll?: boolean;
+
+   /** Close the dropdown after selection. Default is `true`. */
    closeOnSelect?: boolean;
+
+   /** Message displayed if the entered search query is too short. */
    minQueryLengthMessageText?: string;
+
+   /** Query function called to fetch options. */
    onQuery?:
       | string
       | ((
            query: string | { query: string; page: number; pageSize: number },
            instance: Instance,
-        ) => Record<string, any>[] | Promise<Record<string, any>[]>);
+        ) => TOption[] | Promise<TOption[]>);
+
+   /** Set to `true` to sort dropdown options. */
    sort?: boolean;
+
+   /** Additional list options, such as grouping configuration, custom sorting, etc. */
    listOptions?: Record<string, any>;
+
+   /** Show dropdown immediately after component mount; useful for cell editing. */
    autoOpen?: BooleanProp;
+
+   /** Allow enter key events to propagate; useful for forms or grid cell editors. */
    submitOnEnterKey?: BooleanProp;
+
+   /** Allow dropdown enter key events to propagate for form submission. */
    submitOnDropdownEnterKey?: BooleanProp;
+
+   /** Number of additional items loaded in `infinite` mode. Default is `100`. */
    pageSize?: number;
+
+   /** Set to `true` to enable loading additional options when scroll reaches end. */
    infinite?: boolean;
+
+   /** Allow quick selection of all displayed items on `Ctrl + A` key combination. */
    quickSelectAll?: boolean;
-   onGetRecordDisplayText?: ((record: Record<string, any>, instance: Instance) => string) | null;
+
+   /** 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
-      | ((filterParams: unknown, instance: Instance) => (option: Record<string, any>) => boolean);
+      | ((filterParams: unknown, instance: Instance) => (option: TOption) => boolean);
 
-   /** Additional configuration to be passed to the dropdown. */
+   /** Additional configuration to be passed to the dropdown, such as `style`, `positioning`, etc. */
    dropdownOptions?: Partial<DropdownConfig>;
+
+   /** Custom validation function. */
+   onValidate?:
+      | string
+      | ((value: number | string, instance: Instance, validationParams: Record<string, unknown>) => unknown);
 }
 
-export class LookupField<Config extends LookupFieldConfig = LookupFieldConfig> extends Field<Config> {
+export class LookupField<TOption = unknown, TRecord = unknown> extends Field<
+   LookupFieldConfig<TOption, TRecord>
+> {
    declare public baseClass: string;
    declare public multiple: boolean;
    declare public hideClear?: boolean;

package/src/widgets/form/MonthField.tsx

@@ -122,6 +122,11 @@ export interface MonthFieldConfig extends FieldConfig {
 
    /** Optional configuration options for the MonthPicker component rendered within the dropdown. */
    monthPickerOptions?: Config;
+
+   /** Custom validation function. */
+   onValidate?:
+      | string
+      | ((value: string | Date, instance: Instance, validationParams: Record<string, unknown>) => unknown);
 }
 
 export class MonthField<Config extends MonthFieldConfig = MonthFieldConfig> extends Field<Config, MonthFieldInstance> {

package/src/widgets/form/NumberField.tsx

@@ -57,6 +57,9 @@ export interface NumberFieldConfig extends FieldConfig {
    inputErrorText?: string;
    scale?: number;
    offset?: number;
+
+   /** Custom validation function. */
+   onValidate?: string | ((value: number, instance: Instance, validationParams: Record<string, unknown>) => unknown);
 }
 
 export class NumberField<Config extends NumberFieldConfig = NumberFieldConfig> extends Field<Config> {

package/src/widgets/form/Radio.tsx

@@ -34,6 +34,11 @@ export interface RadioConfig extends FieldConfig {
 
    /** Set to `true` to make the radio initially selected. */
    default?: boolean;
+
+   /** Custom validation function. */
+   onValidate?:
+      | string
+      | ((value: number | string | boolean, instance: Instance, validationParams: Record<string, unknown>) => unknown);
 }
 
 export class Radio extends Field<RadioConfig> {

package/src/widgets/form/Select.tsx

@@ -34,6 +34,11 @@ export interface SelectConfig extends FieldConfig {
    multiple?: boolean;
    convertValues?: boolean;
    nullString?: string;
+
+   /** Custom validation function. */
+   onValidate?:
+      | string
+      | ((value: number | string, instance: Instance, validationParams: Record<string, unknown>) => unknown);
 }
 
 export class Select<Config extends SelectConfig = SelectConfig> extends Field<Config> {

package/src/widgets/form/Slider.tsx

@@ -17,6 +17,7 @@ import {
    type TooltipConfig,
 } from "../overlay/tooltip-ops";
 import { Field, FieldConfig, FieldInstance, getFieldTooltip } from "./Field";
+import type { Instance } from "../../ui/Instance";
 
 export interface SliderConfig extends FieldConfig {
    /** Low value of the slider range. */
@@ -75,6 +76,9 @@ export interface SliderConfig extends FieldConfig {
 
    /** Set to `true` to make the slider read-only. */
    readOnly?: BooleanProp;
+
+   /** Custom validation function. */
+   onValidate?: string | ((value: number, instance: Instance, validationParams: Record<string, unknown>) => unknown);
 }
 
 export class Slider extends Field<SliderConfig, FieldInstance<Slider>> {

package/src/widgets/form/Switch.tsx

@@ -38,6 +38,9 @@ export interface SwitchConfig extends FieldConfig {
 
    /** Determines if button should receive focus on mousedown event. Default is `false`. */
    focusOnMouseDown?: boolean;
+
+   /** Custom validation function. */
+   onValidate?: string | ((value: boolean, instance: Instance, validationParams: Record<string, unknown>) => unknown);
 }
 
 export class Switch extends Field<SwitchConfig> {

package/src/widgets/form/TextField.tsx

@@ -6,30 +6,92 @@ import { BooleanProp, NumberProp, Prop, StringProp } from "../../ui/Prop";
 import { Instance } from "../../ui/Instance";
 
 export interface TextFieldConfig extends FieldConfig {
+   /** Textual value of the input field. */
    value?: Prop<any>;
+
+   /** Default text displayed when the field is empty. */
    placeholder?: StringProp;
+
+   /** Defaults to `false`. Set to `true` to disable the field. */
    disabled?: BooleanProp;
+
+   /** The opposite of `disabled`. */
+   enabled?: BooleanProp;
+
+   /** Defaults to `false`. Used to make the field read-only. */
    readOnly?: BooleanProp;
+
+   /** Defaults to `false`. Used to make the field required. */
    required?: BooleanProp;
+
+   /** Minimal length of the input text. */
    minLength?: NumberProp;
+
+   /** Maximal length of the input text. */
    maxLength?: NumberProp;
+
+   /** Regular expression used to validate the user's input. */
    validationRegExp?: Prop<RegExp>;
+
+   /** Error message displayed upon validation failure. */
    validationErrorText?: StringProp;
+
+   /** Error message displayed when input text is too short. */
    minLengthValidationErrorText?: StringProp;
+
+   /** Error message displayed when input text is too long. */
    maxLengthValidationErrorText?: StringProp;
+
+   /** Event triggering value updates. Possible values are `input` (default), `enter`, or `blur`. Multiple values can be separated by space. */
    reactOn?: StringProp;
+
+   /** Input type. Defaults to `text`. Other common value is `password`. */
    inputType?: StringProp;
+
+   /** Base CSS class to be applied to the field. Defaults to `textfield`. */
+   baseClass?: string;
+
+   /** Keyboard shortcut used to focus the field. */
    keyboardShortcut?: StringProp;
+
+   /** Set to `true` to remove leading and trailing whitespace. Default is `false`. */
    trim?: BooleanProp;
+
+   /** Set to `true` to hide the clear button. Default value is `false`. */
    hideClear?: BooleanProp;
+
+   /** Set to `false` to hide the clear button. Default value is `true`. */
    showClear?: BooleanProp;
+
+   /** Set to `true` to display the clear button even if `required` is set. Default is `false`. */
    alwaysShowClear?: BooleanProp;
+
+   /** Name or configuration of the icon to be put on the left side of the input. */
    icon?: Prop<any>;
+
+   /** Additional attributes to be passed to the input element. */
    inputAttrs?: Prop<any>;
+
+   /** If `trackFocus` is set, this value will be set when the field receives or loses focus. */
+   focused?: BooleanProp;
+
+   /** Callback invoked when the value changes. */
    onChange?: string | ((value: any, instance: Instance) => void);
+
+   /** Callback invoked on each input event. */
    onInput?: string | ((value: any, instance: Instance) => void);
+
+   /** Callback invoked when the field receives focus. */
    onFocus?: string | ((e: FocusEvent, instance: Instance) => void);
+
+   /** Callback invoked when the field loses focus. */
    onBlur?: string | ((e: FocusEvent, instance: Instance) => void);
+
+   /** Handler triggered on key down events. Return `false` to prevent default behavior. */
+   onKeyDown?: string | ((e: KeyboardEvent, instance: Instance) => boolean | void);
+
+   /** Custom validation function. */
+   onValidate?: string | ((value: string, instance: Instance, validationParams: any) => string | undefined | false);
 }
 
 // Legacy alias for backward compatibility

package/src/widgets/form/TimeList.tsx

@@ -1,4 +1,3 @@
-/** @jsxImportSource react */
 import { ContentResolver } from "../../ui/ContentResolver";
 import { DataProxy } from "../../ui/DataProxy";
 import { List } from "../List";
@@ -10,85 +9,97 @@ import { Culture } from "../../ui/Culture";
 import { isString } from "../../util/isString";
 import { isFunction } from "../../util/isFunction";
 import { bind } from "../../ui/bind";
-import { Widget } from "../../ui/Widget";
 import type { Instance } from "../../ui/Instance";
-import { HtmlElement } from "../HtmlElement";
 
-interface TimeListProps {
+export interface TimeListProps {
+   /** Selected time value. Should be a Date object or a valid date string. */
    value?: unknown;
+
+   /** Time step in minutes. Default is `15`. */
    step?: number;
+
+   /** Time format string. Default is `datetime;HHmm`. */
    format?: string;
+
+   /** Function to encode the Date object before storing. */
    encoding?: (date: Date) => unknown;
+
+   /** Callback invoked when a time is selected. */
    onSelect?: string | ((e: React.MouseEvent, instance: Instance, date: Date) => void);
+
+   /** Additional properties passed to the underlying component. */
    [key: string]: unknown;
 }
 
-export const TimeList = createFunctionalComponent(({ value, step, format, encoding, onSelect, ...props }: TimeListProps) => {
-   return Widget.create({
-      type: ContentResolver,
-      params: { step, format, dummy: true },
-      onResolve: ({ step, format }: { step?: number; format?: string }) => {
-         let max = 24 * 60;
-         if (!step) step = 15;
-         if (step < 1) step = 1;
-         let times = [];
-         let today = zeroTime(new Date()).valueOf();
-         for (let m = 0; m < max; m += step) {
-            let time = m * 60 * 1000;
-            times.push({
-               id: m * 60 * 1000,
-               text: Format.value(today + time, format || "datetime;HHmm"),
-            });
-         }
-         let stepMs = step * 60 * 1000;
-         return Widget.create({
-            type: DataProxy,
-            data: { $value: value },
-            immutable: true,
-            children: Widget.create({
-               type: DataProxy,
-               data: {
-                  $selection: {
-                     get: ({ $value }: { $value?: unknown }) => {
-                        if ($value == null) return null;
-                        let selectionDate = new Date($value as any);
-                        let selectionTime = selectionDate.valueOf() - zeroTime(selectionDate).valueOf();
-                        return (Math.round(selectionTime / stepMs) * stepMs) % 86400000;
-                     },
-                     set: (value: unknown, instance: Instance) => {
-                        let { store } = instance;
-                        let $value = store.get("$value");
-                        let copy = $value ? new Date($value as any) : new Date();
-                        let today = zeroTime(new Date()).valueOf();
-                        let date = new Date(today + (value as number));
-                        copy.setHours(date.getHours());
-                        copy.setMinutes(date.getMinutes());
-                        copy.setSeconds(date.getSeconds());
-                        copy.setMilliseconds(0);
-                        let encode = encoding || Culture.getDefaultDateEncoding();
-                        store.set("$value", encode(copy));
-                     },
-                  },
-               },
-               children: Widget.create({
-                  type: List,
-                  records: times,
-                  recordAlias: "$time",
-                  selection: {
-                     type: KeySelection,
-                     selection: { bind: "$selection" },
-                  },
-                  ...props,
-                  onItemClick: (e: React.MouseEvent, instance: Instance) => {
-                     if (!onSelect) return;
-                     let date = new Date(instance.store.get('$value') as any);
-                     if (isString(onSelect)) instance.invokeControllerMethod(onSelect, e, instance, date);
-                     else if (isFunction(onSelect)) onSelect(e, instance, date);
-                  },
-                  children: HtmlElement.create("div", { text: bind("$time.text") }),
-               }),
-            }),
-         });
-      },
-   });
-});
+export const TimeList = createFunctionalComponent(
+   ({ value, step, format, encoding, onSelect, ...props }: TimeListProps) => (
+      <cx>
+         <ContentResolver
+            params={{ step, format, dummy: true }}
+            onResolve={({ step, format }: { step?: number; format?: string }) => {
+               let max = 24 * 60;
+               if (!step) step = 15;
+               if (step < 1) step = 1;
+               let times = [];
+               let today = zeroTime(new Date()).valueOf();
+               for (let m = 0; m < max; m += step) {
+                  let time = m * 60 * 1000;
+                  times.push({
+                     id: m * 60 * 1000,
+                     text: Format.value(today + time, format || "datetime;HHmm"),
+                  });
+               }
+               let stepMs = step * 60 * 1000;
+               return (
+                  <cx>
+                     <DataProxy data={{ $value: value }} immutable>
+                        <DataProxy
+                           data={{
+                              $selection: {
+                                 get: ({ $value }: { $value?: unknown }) => {
+                                    if ($value == null) return null;
+                                    let selectionDate = new Date($value as any);
+                                    let selectionTime =
+                                       selectionDate.valueOf() - zeroTime(selectionDate).valueOf();
+                                    return (Math.round(selectionTime / stepMs) * stepMs) % 86400000;
+                                 },
+                                 set: (value: unknown, instance: Instance) => {
+                                    let { store } = instance;
+                                    let $value = store.get("$value");
+                                    let copy = $value ? new Date($value as any) : new Date();
+                                    let today = zeroTime(new Date()).valueOf();
+                                    let date = new Date(today + (value as number));
+                                    copy.setHours(date.getHours());
+                                    copy.setMinutes(date.getMinutes());
+                                    copy.setSeconds(date.getSeconds());
+                                    copy.setMilliseconds(0);
+                                    let encode = encoding || Culture.getDefaultDateEncoding();
+                                    store.set("$value", encode(copy));
+                                 },
+                              },
+                           }}
+                        >
+                           <List
+                              records={times}
+                              recordAlias="$time"
+                              selection={{ type: KeySelection, selection: bind("$selection") }}
+                              {...props}
+                              onItemClick={(e, instance) => {
+                                 if (!onSelect) return;
+                                 let date = new Date(instance.store.get("$value") as any);
+                                 if (isString(onSelect))
+                                    instance.invokeControllerMethod(onSelect, e, instance, date);
+                                 else if (isFunction(onSelect)) onSelect(e, instance, date);
+                              }}
+                           >
+                              <div text={bind("$time.text")} />
+                           </List>
+                        </DataProxy>
+                     </DataProxy>
+                  </cx>
+               );
+            }}
+         />
+      </cx>
+   ),
+);