Form SmartPaste: add smartPaste method to Form (#30878)

Author: anna-shakhova

packages/devextreme/js/__internal/ui/form/form.ai.utils.ts

@@ -0,0 +1,50 @@
+import { isObject } from '@js/core/utils/type';
+import type { FormItemComponent, SimpleItem } from '@js/ui/form';
+
+const getEditorTypeInfo = (editorType: FormItemComponent | undefined): string => {
+  switch (editorType) {
+    case 'dxDateBox':
+    case 'dxCalendar':
+      return 'date in ISO format';
+    case 'dxDateRangeBox':
+      return 'date range in ISO format, use pattern {start}:::{end}';
+    case 'dxColorBox':
+      return 'color in hex format';
+    case 'dxCheckBox':
+    case 'dxSwitch':
+      return 'boolean value, true or false';
+    case 'dxNumberBox':
+    case 'dxSlider':
+      return 'numeric value';
+    case 'dxRangeSlider':
+      return 'numeric range, use pattern {start}:::{end}';
+    default:
+      return 'text';
+  }
+};
+
+const getItemsAcceptedValuesInfo = (editorOptions: SimpleItem['editorOptions']): string => {
+  if (!editorOptions?.items) {
+    return '';
+  }
+
+  const items = editorOptions.items.map((item: { text?: string } | string) => {
+    if (isObject(item)) {
+      return item.text;
+    }
+
+    return item;
+  });
+
+  const acceptedValues = `, accepted values: ${items.join(', ')}, split values with :::`;
+  const customItemsAllowed = editorOptions?.acceptCustomValue ? ' (custom values are allowed)' : '';
+
+  return `${acceptedValues}${customItemsAllowed}`;
+};
+
+export const getItemFormatInfo = ({ editorType, editorOptions }: SimpleItem): string => {
+  const dataType = getEditorTypeInfo(editorType);
+  const acceptedValues = getItemsAcceptedValuesInfo(editorOptions);
+
+  return `${dataType}${acceptedValues}`;
+};

packages/devextreme/js/__internal/ui/form/form.items_runtime_info.ts

@@ -23,6 +23,7 @@ export type PreparedItem<T = Item> = T & {
 
 export type TabItem = NonNullable<TabbedItem['tabs']>[number];
 export type PreparedTabItem = PreparedItem<TabItem>;
+export type SimpleItemWithDataField = SimpleItem & Required<Pick<SimpleItem, 'dataField'>>;
 
 export interface PreparedGroupedItem extends PreparedItem<GroupItem> {
   _prepareGroupCaptionTemplate?: (captionTemplate?: template | ((
@@ -212,4 +213,35 @@ export default class FormItemsRunTimeInfo {
     });
     filteredKeys.forEach((key) => this.removeItemByKey(key));
   }
+
+  _isEditableItem(item: SimpleItem): boolean {
+    const { visible: itemVisible, editorOptions } = item;
+    const { readOnly, disabled, visible } = editorOptions ?? {};
+
+    return itemVisible !== false && !readOnly && !disabled && visible !== false;
+  }
+
+  _isItemAIEnabled(item: SimpleItem): boolean {
+    // @ts-expect-error
+    return !item.aiOptions?.disabled;
+  }
+
+  _isDataItem(item: PreparedItem): item is SimpleItemWithDataField {
+    return 'dataField' in item;
+  }
+
+  getVisibleItems(): FormItemRuntimeInfo[] {
+    const allItems = Object.values(this._map);
+
+    return allItems.filter(({ $itemContainer }) => $itemContainer?.css('visibility') === 'visible');
+  }
+
+  getItemsForDataExtraction(): SimpleItemWithDataField[] {
+    const visibleItems = this.getVisibleItems().map(({ item }) => item);
+
+    return visibleItems
+      .filter(this._isDataItem)
+      .filter(this._isItemAIEnabled)
+      .filter(this._isEditableItem);
+  }
 }

packages/devextreme/js/__internal/ui/form/form.ts

@@ -2,6 +2,7 @@ import '@js/ui/validation_summary';
 import '@js/ui/validation_group';
 
 import type { EditorStyle } from '@js/common';
+import type { RequestCallbacks, SmartPasteCommandParams, SmartPasteCommandResult } from '@js/common/ai-integration';
 import eventsEngine from '@js/common/core/events/core/events_engine';
 import { triggerResizeEvent, triggerShownEvent } from '@js/common/core/events/visibility_change';
 import messageLocalization from '@js/common/core/localization/message';
@@ -26,7 +27,12 @@ import type { ChangedOptionInfo, EventInfo } from '@js/events';
 import type {
   FieldDataChangedEvent,
   FormItemType,
-  GroupItem, Item, LabelLocation, Properties, SimpleItemTemplateData, TabbedItem,
+  GroupItem,
+  Item,
+  LabelLocation,
+  Properties,
+  SimpleItemTemplateData,
+  TabbedItem,
 } from '@js/ui/form';
 import { current, isMaterial, isMaterialBased } from '@js/ui/themes';
 import type { ValidationResult } from '@js/ui/validation_group';
@@ -37,9 +43,7 @@ import Widget, { FOCUSED_STATE_CLASS } from '@ts/core/widget/widget';
 import type { Button } from '@ts/ui/button/button';
 import { DROP_DOWN_EDITOR_CLASS } from '@ts/ui/drop_down_editor/m_drop_down_editor';
 import Editor from '@ts/ui/editor/editor';
-import {
-  setLabelWidthByMaxLabelWidth,
-} from '@ts/ui/form/components/label';
+import { setLabelWidthByMaxLabelWidth } from '@ts/ui/form/components/label';
 import {
   FIELD_ITEM_CLASS,
   FIELD_ITEM_CONTENT_CLASS,
@@ -58,6 +62,7 @@ import {
   GROUP_COL_COUNT_CLASS,
   ROOT_SIMPLE_ITEM_CLASS,
 } from '@ts/ui/form/constants';
+import { getItemFormatInfo } from '@ts/ui/form/form.ai.utils';
 import type { ItemOptionActionType } from '@ts/ui/form/form.item_options_actions';
 import tryCreateItemOptionAction from '@ts/ui/form/form.item_options_actions';
 import type {
@@ -91,6 +96,21 @@ import TabPanel from '@ts/ui/tab_panel/tab_panel';
 import { TEXTEDITOR_CLASS, TEXTEDITOR_INPUT_CLASS } from '@ts/ui/text_box/m_text_editor.base';
 import { TOOLBAR_CLASS } from '@ts/ui/toolbar/constants';
 
+export type FormAICommandName = 'smartPaste';
+export interface AICommandParamsMap {
+  smartPaste: SmartPasteCommandParams;
+}
+
+export interface AICommandResultMap {
+  smartPaste: SmartPasteCommandResult;
+}
+
+interface AICommandWithParams<T extends FormAICommandName> {
+  command: T;
+  params: AICommandParamsMap[T];
+  callbacks: RequestCallbacks<AICommandResultMap[T]>;
+}
+
 const ITEM_OPTIONS_FOR_VALIDATION_UPDATING = ['items', 'isRequired', 'validationRules', 'visible'];
 
 export interface FormProperties extends Properties {
@@ -104,6 +124,10 @@ export interface FormProperties extends Properties {
 }
 
 class Form extends Widget<FormProperties> {
+  private _abort?: () => void;
+
+  private _currentAICommand?: AICommandWithParams<FormAICommandName> = undefined;
+
   _targetScreenFactor?: ScreenSizeQualifier;
 
   _lastMarkupScreenFactor!: ScreenSizeQualifier;
@@ -1100,6 +1124,11 @@ class Form extends Widget<FormProperties> {
         ValidationEngine.removeGroup(args.previousValue || this);
         this._invalidate();
         break;
+      // @ts-expect-error
+      case 'aiIntegration': {
+        this._processAIIntegrationUpdate();
+        break;
+      }
       default:
         super._optionChanged(args);
     }
@@ -1760,6 +1789,71 @@ class Form extends Widget<FormProperties> {
   getTargetScreenFactor(): ScreenSizeQualifier | undefined {
     return this._targetScreenFactor;
   }
+
+  private _processCommandCompletion(): void {
+    this._abort?.();
+    this._abort = undefined;
+    this._currentAICommand = undefined;
+  }
+
+  private _processAIIntegrationUpdate(): void {
+    if (this._currentAICommand) {
+      const { command, params, callbacks } = this._currentAICommand;
+
+      this._processCommandCompletion();
+      this._executeAICommand(command, params, callbacks);
+    }
+  }
+
+  private _executeAICommand<T extends FormAICommandName>(
+    command: T,
+    params: AICommandParamsMap[T],
+    callbacks: RequestCallbacks<AICommandResultMap[T]>,
+  ): void {
+    // @ts-expect-error
+    const { aiIntegration } = this.option();
+
+    this._currentAICommand = {
+      command,
+      params,
+      callbacks,
+    };
+    this._abort = aiIntegration?.[command](params, callbacks);
+  }
+
+  private _getSmartPasteCommandCallbacks(): RequestCallbacks<SmartPasteCommandResult> {
+    return {
+      onComplete: (fieldsData: SmartPasteCommandResult): void => {
+        this.beginUpdate();
+        fieldsData.forEach(({ name, value }: SmartPasteCommandResult[number]) => {
+          this._updateFieldValue(name, value);
+        });
+        this.endUpdate();
+        this._processCommandCompletion();
+      },
+      onError: (): void => {
+        this._processCommandCompletion();
+      },
+    };
+  }
+
+  async smartPaste(text?: string): Promise<void> {
+    const dataItems = this._itemsRunTimeInfo.getItemsForDataExtraction();
+    const fields = dataItems.map((item) => ({
+      name: item.dataField,
+      format: getItemFormatInfo(item),
+      // @ts-expect-error
+      instruction: item.aiOptions?.instruction,
+    }));
+
+    const smartPasteParams = {
+      text: text ?? await navigator.clipboard.readText(),
+      fields,
+    };
+    const smartPasteCallbacks = this._getSmartPasteCommandCallbacks();
+
+    this._executeAICommand('smartPaste', smartPasteParams, smartPasteCallbacks);
+  }
 }
 
 registerComponent('dxForm', Form);

packages/devextreme/testing/tests/DevExpress.ui.widgets.form/form.ai.utils.tests.js

@@ -0,0 +1,82 @@
+import { getItemFormatInfo } from '__internal/ui/form/form.ai.utils';
+
+const formItemComponents = [
+    'dxAutocomplete',
+    'dxCalendar',
+    'dxCheckBox',
+    'dxColorBox',
+    'dxDateBox',
+    'dxDateRangeBox',
+    'dxDropDownBox',
+    'dxHtmlEditor',
+    'dxLookup',
+    'dxNumberBox',
+    'dxRadioGroup',
+    'dxRangeSlider',
+    'dxSelectBox',
+    'dxSlider',
+    'dxSwitch',
+    'dxTagBox',
+    'dxTextArea',
+    'dxTextBox',
+];
+
+QUnit.module('getItemFormatInfo', () => {
+    formItemComponents.forEach((editorType) => {
+        QUnit.test(`should return correct format for ${editorType}`, function(assert) {
+            const format = getItemFormatInfo({ editorType });
+            const expectedFormats = {
+                dxDateBox: 'date in ISO format',
+                dxCalendar: 'date in ISO format',
+                dxDateRangeBox: 'date range in ISO format, use pattern {start}:::{end}',
+                dxColorBox: 'color in hex format',
+                dxCheckBox: 'boolean value, true or false',
+                dxSwitch: 'boolean value, true or false',
+                dxNumberBox: 'numeric value',
+                dxSlider: 'numeric value',
+                dxRangeSlider: 'numeric range, use pattern {start}:::{end}',
+            };
+
+            assert.strictEqual(format, expectedFormats[editorType] || 'text', `${editorType} format is correct`);
+        });
+    });
+
+    QUnit.test('should list acceptable values if editorOptions.items defined', function(assert) {
+        const format = getItemFormatInfo({
+            editorType: 'dxSelectBox',
+            editorOptions: { items: ['item1', 'item2', 'item3'] },
+        });
+        const expectedFormat = 'text, accepted values: item1, item2, item3, split values with :::';
+
+        assert.strictEqual(format, expectedFormat, 'list of acceptable values is correct');
+    });
+
+    QUnit.test('should list acceptable values if editorOptions.items passed as objects', function(assert) {
+        const format = getItemFormatInfo({
+            editorType: 'dxSelectBox',
+            editorOptions: {
+                items: [
+                    { text: 'item1', value: 1 },
+                    { text: 'item2', value: 2 },
+                    { text: 'item3', value: 3 },
+                ]
+            },
+        });
+        const expectedFormat = 'text, accepted values: item1, item2, item3, split values with :::';
+
+        assert.strictEqual(format, expectedFormat, 'list of acceptable values is correct');
+    });
+
+    QUnit.test('should allow custom values if editorOptions.acceptCustomValue = true', function(assert) {
+        const format = getItemFormatInfo({
+            editorType: 'dxSelectBox',
+            editorOptions: {
+                items: ['item1', 'item2', 'item3'],
+                acceptCustomValue: true,
+            },
+        });
+        const expectedFormat = 'text, accepted values: item1, item2, item3, split values with ::: (custom values are allowed)';
+
+        assert.strictEqual(format, expectedFormat, 'list of acceptable values is correct, custom values are allowed');
+    });
+});