[Controls] Add ESQL control types to options list (elastic#233126)

## Summary

Part of elastic#227062

This adds types for ES|QL control properties and API methods to the
options list control factory in preparation to unify the factories. It
does not actually yet make the control function with ES|QL data sources
or variables, but lays the groundwork for adding this functionality in a
second PR.

- Options list control now optionally accepts all the properties in
`ESQLControlState` as a possible input state. The input state must now
be either `ESQLControlState` or `DefaultDataControlState`.
- The options list control and component APIs now publish `esqlQuery$`,
`esqlVariable$`, and `esqlControlType$`. `esqlVariable$` is an
`ESQLControlVariable` derived from the ES|QL control's
`variableType`/`variableName`, and the other two subjects are simply
renamed properties to reduce ambiguity downstream in the control
factory.
- `esqlVariable$` will publish from the control API and be read by the
control group. This is how current ES|QL controls already publish their
variables and make them available to the dashboard. In this PR, it will
always publish `undefined` and therefore do nothing.
- `esqlControlType$` can be used to determine whether to fetch available
options list suggestions, or to pull them from the `availableOptions`
input state
- `esqlQuery$` can be used to fetch available options if the control
type is `VALUES_FROM_QUERY`
- Options list suggestions data requests to be passed to
`fetchAndValidate` now have types for possible ES|QL requests. See [this
part of the initial draft unification
PR](https://github.com/elastic/kibana/pull/230132/files#diff-338ef52d0d7391e8b3fb6cbd90747d33f3a93b0389a8fa586f4f94e86fbc1916)
for an example of what this enables us to do.
- An ESQL state manager has been added to the options list factory, even
though it's not fully implemented yet. This generates all the needed
publishing subjects and allows the component and control APIs to pass
the new type checks.

### Checklist

- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios

(cherry picked from commit 493cd58)

# Conflicts:
#	src/platform/plugins/shared/controls/common/options_list/types.ts
#	src/platform/plugins/shared/controls/public/controls/data_controls/options_list_control/get_options_list_control_factory.tsx
#	src/platform/plugins/shared/controls/public/controls/data_controls/types.ts
#	src/platform/plugins/shared/controls/public/controls/esql_control/types.ts

Author: Zacqary

src/platform/packages/shared/kbn-alerts-ui-shared/src/alert_filter_controls/constants.ts

@@ -8,7 +8,7 @@
  */
 
 import { ALERT_RULE_NAME, ALERT_STATUS } from '@kbn/rule-data-utils';
-import type { OptionsListControlState } from '@kbn/controls-plugin/public';
+import type { OptionsListDSLControlState } from '@kbn/controls-plugin/public';
 import { i18n } from '@kbn/i18n';
 import type { FilterControlConfig } from './types';
 
@@ -65,7 +65,7 @@ export const TEST_IDS = {
   },
 };
 
-export const COMMON_OPTIONS_LIST_CONTROL_INPUTS: Partial<OptionsListControlState> = {
+export const COMMON_OPTIONS_LIST_CONTROL_INPUTS: Partial<OptionsListDSLControlState> = {
   hideExclude: true,
   hideSort: true,
   placeholder: '',

src/platform/packages/shared/kbn-alerts-ui-shared/src/alert_filter_controls/mocks/data.ts

@@ -9,7 +9,7 @@
 
 import type {
   ControlGroupRuntimeState,
-  OptionsListControlState,
+  OptionsListDSLControlState,
 } from '@kbn/controls-plugin/public';
 import type { Filter } from '@kbn/es-query';
 import { ALERT_DURATION, ALERT_RULE_NAME, ALERT_START, ALERT_STATUS } from '@kbn/rule-data-utils';
@@ -41,7 +41,7 @@ export const sampleOutputData: ControlGroupOutput = {
   ],
 };
 
-export const initialInputData: ControlGroupRuntimeState<OptionsListControlState> = {
+export const initialInputData: ControlGroupRuntimeState<OptionsListDSLControlState> = {
   initialChildControlState: {
     '0': {
       type: 'optionsListControl',

src/platform/packages/shared/kbn-alerts-ui-shared/src/alert_filter_controls/types.ts

@@ -10,7 +10,7 @@
 import type { Filter, Query, TimeRange } from '@kbn/es-query';
 import type {
   ControlGroupRenderer,
-  OptionsListControlState,
+  OptionsListDSLControlState,
   ControlGroupRuntimeState,
   ControlGroupRendererApi,
 } from '@kbn/controls-plugin/public';
@@ -19,7 +19,7 @@ import type { Storage } from '@kbn/kibana-utils-plugin/public';
 export type FilterUrlFormat = Record<
   string,
   Pick<
-    OptionsListControlState,
+    OptionsListDSLControlState,
     'selectedOptions' | 'title' | 'fieldName' | 'existsSelected' | 'exclude'
   >
 >;
@@ -29,7 +29,7 @@ export interface FilterContextType {
   addControl: (controls: FilterControlConfig) => void;
 }
 
-export type FilterControlConfig = Omit<OptionsListControlState, 'dataViewId'> & {
+export type FilterControlConfig = Omit<OptionsListDSLControlState, 'dataViewId'> & {
   /*
    * Determines the presence and order of a control
    * */

src/platform/packages/shared/kbn-alerts-ui-shared/src/alert_filter_controls/utils.ts

@@ -9,7 +9,7 @@
 
 import type {
   ControlGroupRuntimeState,
-  OptionsListControlState,
+  OptionsListDSLControlState,
   ControlPanelState,
 } from '@kbn/controls-plugin/public';
 
@@ -25,7 +25,7 @@ export const getFilterItemObjListFromControlState = (controlState: ControlGroupR
   const panels = getPanelsInOrderFromControlsState(controlState);
   return panels.map((panel) => {
     const { fieldName, selectedOptions, title, existsSelected, exclude, hideActionBar } =
-      panel as ControlPanelState<OptionsListControlState>;
+      panel as ControlPanelState<OptionsListDSLControlState>;
 
     return {
       fieldName: fieldName as string,

src/platform/plugins/shared/controls/common/options_list/index.ts

@@ -13,6 +13,8 @@ export type { OptionsListSearchTechnique } from './suggestions_searching';
 export type { OptionsListSortingType } from './suggestions_sorting';
 export type {
   OptionsListControlState,
+  OptionsListESQLControlState,
+  OptionsListDSLControlState,
   OptionsListDisplaySettings,
   OptionsListFailureResponse,
   OptionsListRequest,

src/platform/plugins/shared/controls/common/options_list/types.ts

@@ -10,10 +10,11 @@
 import { DataView, FieldSpec, RuntimeFieldSpec } from '@kbn/data-views-plugin/common';
 import type { AggregateQuery, BoolQuery, Filter, Query, TimeRange } from '@kbn/es-query';
 
-import { OptionsListSelection } from './options_list_selections';
-import { OptionsListSortingType } from './suggestions_sorting';
-import { DefaultDataControlState } from '../types';
-import { OptionsListSearchTechnique } from './suggestions_searching';
+import type { ESQLControlState } from '@kbn/esql-types';
+import type { OptionsListSelection } from './options_list_selections';
+import type { OptionsListSortingType } from './suggestions_sorting';
+import type { DefaultDataControlState } from '../types';
+import type { OptionsListSearchTechnique } from './suggestions_searching';
 
 /**
  * ----------------------------------------------------------------
@@ -29,17 +30,27 @@ export interface OptionsListDisplaySettings {
   hideSort?: boolean;
 }
 
-export interface OptionsListControlState
-  extends DefaultDataControlState,
-    OptionsListDisplaySettings {
+type OptionsListBaseControlState = OptionsListDisplaySettings & {
   searchTechnique?: OptionsListSearchTechnique;
   sort?: OptionsListSortingType;
   selectedOptions?: OptionsListSelection[];
   existsSelected?: boolean;
   runPastTimeout?: boolean;
   singleSelect?: boolean;
   exclude?: boolean;
-}
+};
+export type OptionsListDSLControlState = DefaultDataControlState & OptionsListBaseControlState;
+export type OptionsListESQLControlState = ESQLControlState & OptionsListBaseControlState;
+
+export type OptionsListControlState = OptionsListDSLControlState | OptionsListESQLControlState;
+
+export const isOptionsListESQLControlState = (
+  state: OptionsListControlState | undefined
+): state is OptionsListESQLControlState =>
+  typeof state !== 'undefined' &&
+  Object.hasOwn(state, 'esqlQuery') &&
+  Object.hasOwn(state, 'controlType') &&
+  !Object.hasOwn(state, 'fieldName');
 
 /**
  * ----------------------------------------------------------------
@@ -92,7 +103,7 @@ export type OptionsListRequest = Omit<
  */
 export interface OptionsListRequestBody
   extends Pick<
-    OptionsListControlState,
+    OptionsListDSLControlState,
     'fieldName' | 'searchTechnique' | 'sort' | 'selectedOptions'
   > {
   runtimeFieldMap?: Record<string, RuntimeFieldSpec>;

src/platform/plugins/shared/controls/public/controls/data_controls/options_list_control/components/options_list_editor_options.tsx

@@ -87,8 +87,8 @@ export const OptionsListEditorOptions = ({
   );
 
   const compatibleSearchTechniques = useMemo(
-    () => getCompatibleSearchTechniques(field.type),
-    [field.type]
+    () => getCompatibleSearchTechniques(field?.type),
+    [field?.type]
   );
 
   const searchOptions = useMemo(() => {

src/platform/plugins/shared/controls/public/controls/data_controls/options_list_control/get_options_list_control_factory.tsx

@@ -25,6 +25,7 @@ import { PublishingSubject } from '@kbn/presentation-publishing';
 
 import { initializeUnsavedChanges } from '@kbn/presentation-containers';
 import { OPTIONS_LIST_CONTROL } from '../../../../common';
+import { isOptionsListESQLControlState } from '../../../../common/options_list/types';
 import type {
   OptionsListControlState,
   OptionsListSortingType,
@@ -73,6 +74,10 @@ export const getOptionsListControlFactory = (): DataControlFactory<
     },
     CustomOptionsComponent: OptionsListEditorOptions,
     buildControl: async ({ initialState, finalizeApi, uuid, controlGroupApi }) => {
+      if (isOptionsListESQLControlState(initialState)) {
+        throw new Error('ES|QL control state handling not yet implemented');
+      }
+
       /** Serializable state - i.e. the state that is saved with the control */
       const editorStateManager = initializeEditorStateManager(initialState);
 
@@ -299,6 +304,9 @@ export const getOptionsListControlFactory = (): DataControlFactory<
           existsSelected: false,
         },
         onReset: (lastSaved) => {
+          if (isOptionsListESQLControlState(lastSaved?.rawState)) {
+            throw new Error('ES|QL control state handling not yet implemented');
+          }
           dataControlManager.reinitializeState(lastSaved?.rawState);
           selectionsManager.reinitializeState(lastSaved?.rawState);
           editorStateManager.reinitializeState(lastSaved?.rawState);

src/platform/plugins/shared/controls/public/controls/data_controls/options_list_control/types.ts

@@ -12,8 +12,6 @@ import { Subject } from 'rxjs';
 import type { PublishesTitle, PublishingSubject } from '@kbn/presentation-publishing';
 import { SubjectsOf, SettersOf } from '@kbn/presentation-publishing/state_manager/types';
 import type {
-  OptionsListControlState,
-  OptionsListDisplaySettings,
   OptionsListSelection,
   OptionsListSortingType,
   OptionsListSuggestions,
@@ -28,32 +26,33 @@ export type OptionsListControlApi = DataControlApi & {
   setSelectedOptions: (options: OptionsListSelection[] | undefined) => void;
 };
 
-export interface OptionsListComponentState
-  extends Omit<OptionsListControlState, keyof OptionsListDisplaySettings> {
-  searchString: string;
-  searchStringValid: boolean;
-  requestSize: number;
-}
-
 interface PublishesOptions {
   availableOptions$: PublishingSubject<OptionsListSuggestions | undefined>;
   invalidSelections$: PublishingSubject<Set<OptionsListSelection>>;
   totalCardinality$: PublishingSubject<number>;
 }
-export type OptionsListState = Pick<DefaultDataControlState, 'fieldName'> &
+
+/**
+ * A type consisting of only the properties that the options list control puts into state managers
+ * and then passes to the UI component. Excludes any managed state properties that don't end up being used
+ * by the component
+ */
+export type OptionsListComponentState = Pick<DefaultDataControlState, 'fieldName'> &
   SelectionsState &
   EditorState &
-  TemporaryState & { sort: OptionsListSortingType | undefined };
+  TemporaryState & {
+    sort: OptionsListSortingType | undefined;
+  };
 
-type PublishesOptionsListState = SubjectsOf<OptionsListState>;
-type OptionsListStateSetters = Partial<SettersOf<OptionsListState>> &
-  SettersOf<Pick<OptionsListState, 'sort' | 'searchString' | 'requestSize' | 'exclude'>>;
+type PublishesOptionsListComponentState = SubjectsOf<OptionsListComponentState>;
+type OptionsListComponentStateSetters = Partial<SettersOf<OptionsListComponentState>> &
+  SettersOf<Pick<OptionsListComponentState, 'sort' | 'searchString' | 'requestSize' | 'exclude'>>;
 
 export type OptionsListComponentApi = PublishesField &
   PublishesOptions &
-  PublishesOptionsListState &
+  PublishesOptionsListComponentState &
   Pick<PublishesTitle, 'title$'> &
-  OptionsListStateSetters & {
+  OptionsListComponentStateSetters & {
     deselectOption: (key: string | undefined) => void;
     makeSelection: (key: string | undefined, showOnlySelected: boolean) => void;
     loadMoreSubject: Subject<void>;

src/platform/plugins/shared/controls/public/controls/data_controls/types.ts

@@ -16,10 +16,10 @@ import {
   PublishingSubject,
 } from '@kbn/presentation-publishing';
 
-import { DefaultDataControlState } from '../../../common';
-import { ControlGroupApi } from '../../control_group/types';
-import { ControlFactory, DefaultControlApi } from '../types';
-import { PublishesAsyncFilters } from './publishes_async_filters';
+import type { DefaultControlState } from '../../../common';
+import type { ControlGroupApi } from '../../control_group/types';
+import type { ControlFactory, DefaultControlApi } from '../types';
+import type { PublishesAsyncFilters } from './publishes_async_filters';
 
 export type DataControlFieldFormatter = FieldFormatConvertFunction | ((toFormat: any) => string);
 
@@ -36,17 +36,17 @@ export type DataControlApi = DefaultControlApi &
   PublishesAsyncFilters;
 
 export interface CustomOptionsComponentProps<
-  State extends DefaultDataControlState = DefaultDataControlState
+  State extends DefaultControlState = DefaultControlState
 > {
   initialState: Partial<State>;
-  field: DataViewField;
+  field?: DataViewField;
   updateState: (newState: Partial<State>) => void;
   setControlEditorValid: (valid: boolean) => void;
   controlGroupApi: ControlGroupApi;
 }
 
 export interface DataControlFactory<
-  State extends DefaultDataControlState = DefaultDataControlState,
+  State extends DefaultControlState = DefaultControlState,
   Api extends DataControlApi = DataControlApi
 > extends ControlFactory<State, Api> {
   isFieldCompatible: (field: DataViewField) => boolean;