[ES|QL Controls] Highlight related panels on click

Author: Zacqary

src/platform/packages/private/kbn-controls-renderer/index.ts

@@ -8,4 +8,5 @@
  */
 
 export { ControlsRenderer } from './src/controls_renderer';
+export { ControlLabelTooltip } from './src/components/control_label_tooltip';
 export type { ControlsRendererParentApi, ControlsLayout } from './src/types';

src/platform/packages/private/kbn-controls-renderer/src/components/control_label_tooltip.tsx

@@ -0,0 +1,75 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { EuiToolTip, EuiBadge, type EuiToolTipProps } from '@elastic/eui';
+import { i18n } from '@kbn/i18n';
+import React from 'react';
+
+interface RelatedPanelProps {
+  canIndicateRelatedPanels: boolean;
+  isIndicatingRelatedPanels: boolean;
+  numberOfRelatedPanels?: number;
+}
+// Throw a typescript error if one, but not all, of the related panel props are defined
+// Prevents us from e.g. setting canIndicateRelatedPanels to true and forgetting to pass isIndicatingRelatedPanels
+type AllRelatedPanelPropsOrNone = RelatedPanelProps | { [K in keyof RelatedPanelProps]?: never };
+
+type Props = Partial<EuiToolTipProps> & {
+  panelLabel?: string;
+  panelTooltipLabel?: string;
+  isOpen?: boolean;
+} & AllRelatedPanelPropsOrNone;
+
+export const ControlLabelTooltip: React.FC<Props> = ({
+  canIndicateRelatedPanels,
+  isIndicatingRelatedPanels,
+  numberOfRelatedPanels,
+  panelLabel,
+  panelTooltipLabel,
+  isOpen,
+  ...rest
+}) => {
+  const relatedPanelCountBadge =
+    canIndicateRelatedPanels && numberOfRelatedPanels !== undefined ? (
+      <EuiBadge color="hollow">
+        {i18n.translate('controls.controlGroup.numberOfRelatedPanels', {
+          defaultMessage: '{numberOfRelatedPanels, plural, one {# panel} other {# panels}}',
+          values: { numberOfRelatedPanels },
+        })}
+      </EuiBadge>
+    ) : null;
+
+  const tooltipContent =
+    numberOfRelatedPanels === 0
+      ? i18n.translate('controls.controlGroup.noRelatedPanels', {
+          defaultMessage:
+            // In practice, this message can only appear for ES|QL controls
+            "This control isn't used in any ES|QL visualizations. Update your visualizations to use it.",
+        })
+      : isIndicatingRelatedPanels
+      ? i18n.translate('controls.controlGroup.clickToStopHighlighting', {
+          defaultMessage: 'Click to stop highlighting',
+        })
+      : i18n.translate('controls.controlGroup.clickToHighlight', {
+          defaultMessage: 'Click to highlight',
+        });
+
+  const tooltipProps = canIndicateRelatedPanels
+    ? {
+        title: (
+          <>
+            {panelTooltipLabel ?? panelLabel} {relatedPanelCountBadge}
+          </>
+        ),
+        content: tooltipContent,
+      }
+    : { content: panelTooltipLabel ?? panelLabel };
+
+  return <EuiToolTip {...tooltipProps} {...rest} id={rest.id} />;
+};

src/platform/packages/private/kbn-controls-renderer/src/components/control_panel.tsx

@@ -18,7 +18,7 @@ import {
   EuiFormControlLayout,
   EuiFormLabel,
   EuiFormRow,
-  EuiToolTip,
+  EuiIcon,
   type UseEuiTheme,
 } from '@elastic/eui';
 import { css } from '@emotion/react';
@@ -27,12 +27,17 @@ import { useMemoCss } from '@kbn/css-utils/public/use_memo_css';
 import { EmbeddableRenderer, type DefaultEmbeddableApi } from '@kbn/embeddable-plugin/public';
 import { i18n } from '@kbn/i18n';
 import { useBatchedPublishingSubjects, type PublishingSubject } from '@kbn/presentation-publishing';
-
+import { useIndicateRelatedPanelsSelector } from '@kbn/presentation-util';
+import {
+  apiPublishesTooltipLabel,
+  type PublishesTooltipLabel,
+} from '@kbn/controls-schemas/src/types';
 import type { ControlsRendererParentApi } from '../types';
 import { apiPublishesLabel } from '../utils';
 import { controlWidthStyles } from './control_panel.styles';
 import { DragHandle } from './drag_handle';
 import { FloatingActions } from './floating_actions';
+import { ControlLabelTooltip } from './control_label_tooltip';
 
 export const ControlPanel = ({
   parentApi,
@@ -45,7 +50,9 @@ export const ControlPanel = ({
 }) => {
   const styles = useMemoCss(controlPanelStyles);
 
-  const [api, setApi] = useState<(DefaultEmbeddableApi & Partial<HasCustomPrepend>) | null>(null);
+  const [api, setApi] = useState<
+    (DefaultEmbeddableApi & Partial<HasCustomPrepend> & Partial<PublishesTooltipLabel>) | null
+  >(null);
 
   const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
     id,
@@ -57,9 +64,17 @@ export const ControlPanel = ({
   );
 
   const [panelLabel, setPanelLabel] = useState<string | undefined>();
+  const [panelTooltipLabel, setPanelTooltipLabel] = useState<string | undefined>();
 
   const prependWrapperRef = useRef<HTMLDivElement>(null);
 
+  const {
+    canIndicateRelatedPanels,
+    isIndicatingRelatedPanels,
+    onToggleIndicateRelatedPanels,
+    numberOfRelatedPanels,
+  } = useIndicateRelatedPanelsSelector(api);
+
   useEffect(() => {
     if (!api) return;
 
@@ -72,6 +87,13 @@ export const ControlPanel = ({
         })
       );
     }
+    if (apiPublishesTooltipLabel(api)) {
+      subscriptions.add(
+        api.tooltipLabel$.subscribe((result) => {
+          setPanelTooltipLabel(result);
+        })
+      );
+    }
     return () => {
       subscriptions.unsubscribe();
     };
@@ -94,6 +116,46 @@ export const ControlPanel = ({
   );
 
   const isEditable = viewMode === 'edit';
+  const enableIndicateRelatedPanels = Boolean(canIndicateRelatedPanels && numberOfRelatedPanels);
+  const handleToggleIndicateRelated = useCallback(
+    () => (enableIndicateRelatedPanels ? onToggleIndicateRelatedPanels() : null),
+    [enableIndicateRelatedPanels, onToggleIndicateRelatedPanels]
+  );
+
+  const controlLabel = (
+    <ControlLabelTooltip
+      canIndicateRelatedPanels={canIndicateRelatedPanels}
+      isIndicatingRelatedPanels={isIndicatingRelatedPanels}
+      numberOfRelatedPanels={numberOfRelatedPanels}
+      panelLabel={panelLabel}
+      panelTooltipLabel={panelTooltipLabel}
+      anchorProps={{ className: 'eui-textTruncate', css: styles.tooltipStyles }}
+    >
+      <EuiFormLabel
+        className="controlPanel--label"
+        onClick={handleToggleIndicateRelated}
+        onKeyDown={(e) =>
+          e.key === 'Enter' || e.key === ' ' ? handleToggleIndicateRelated() : null
+        }
+        role={enableIndicateRelatedPanels ? 'button' : undefined}
+        tabIndex={enableIndicateRelatedPanels ? 0 : undefined}
+      >
+        <span css={styles.prependWrapperStyles} ref={prependWrapperRef}>
+          {panelLabel}{' '}
+          {canIndicateRelatedPanels && numberOfRelatedPanels === 0 && (
+            <EuiIcon
+              size="s"
+              aria-label={i18n.translate('controls.controlGroup.warningNoRelatedPanels', {
+                defaultMessage: 'Warning: No related panels',
+              })}
+              type="warning"
+            />
+          )}
+        </span>
+      </EuiFormLabel>
+    </ControlLabelTooltip>
+  );
+
   return (
     <EuiFlexItem
       component="li"
@@ -128,6 +190,7 @@ export const ControlPanel = ({
             fullWidth
             className={classNames('controlFrame__formControlLayout', {
               'controlFrame__formControlLayout--edit': isEditable,
+              'controlFrame__formControlLayout--selected': isIndicatingRelatedPanels,
               type,
             })}
             css={styles.formControl}
@@ -145,24 +208,19 @@ export const ControlPanel = ({
                     <api.CustomPrependComponent />
                   </>
                 ) : (
-                  <DragHandle
-                    isEditable={isEditable}
-                    controlTitle={panelLabel}
-                    className="controlFrame__dragHandle"
-                    {...attributes}
-                    {...listeners}
-                  >
-                    <EuiToolTip
-                      content={panelLabel}
-                      anchorProps={{ className: 'eui-textTruncate', css: styles.tooltipStyles }}
+                  <>
+                    <DragHandle
+                      isEditable={isEditable}
+                      controlTitle={panelLabel}
+                      className="controlFrame__dragHandle"
+                      highContrast={isIndicatingRelatedPanels}
+                      {...attributes}
+                      {...listeners}
                     >
-                      <EuiFormLabel className="controlPanel--label">
-                        <span css={styles.prependWrapperStyles} ref={prependWrapperRef}>
-                          {panelLabel}
-                        </span>
-                      </EuiFormLabel>
-                    </EuiToolTip>
-                  </DragHandle>
+                      {!enableIndicateRelatedPanels && controlLabel}
+                    </DragHandle>
+                    {enableIndicateRelatedPanels && controlLabel}
+                  </>
                 )}
               </>
             }
@@ -217,10 +275,18 @@ const controlPanelStyles = {
           paddingInlineStart: `${euiTheme.size.xxs} !important`, // corrected syntax for skinny icon
         },
       },
+      '&.controlFrame__formControlLayout--selected': {
+        '.euiFormControlLayout__prepend': {
+          backgroundColor: euiTheme.colors.vis.euiColorVis0,
+        },
+      },
       '.controlPanel--label': {
         padding: '0 !important',
         height: '100%',
         maxWidth: '100%',
+        '&[role="button"]': {
+          cursor: 'pointer',
+        },
       },
     }),
 };

src/platform/packages/private/kbn-controls-renderer/src/components/drag_handle.tsx

@@ -16,6 +16,7 @@ import { useMemoCss } from '@kbn/css-utils/public/use_memo_css';
 interface DragHandleProps {
   isEditable: boolean;
   controlTitle?: string;
+  highContrast?: boolean; // If true, set the icon color to higher contrast instead of subdued
   [key: string]: any; // Allows passing additional props (like drag info)
 }
 
@@ -37,12 +38,19 @@ const dragHandleStyles = {
         pointerEvents: 'none', // Prevent label from blocking drag events
       },
     }),
+  dragHandleHighContrast: ({ euiTheme }: UseEuiTheme) =>
+    css({
+      '.euiIcon': {
+        color: euiTheme.colors.textParagraph,
+      },
+    }),
 };
 
 export const DragHandle = ({
   isEditable,
   controlTitle = '',
   children,
+  highContrast,
   ...rest
 }: DragHandleProps) => {
   const styles = useMemoCss(dragHandleStyles);
@@ -56,7 +64,7 @@ export const DragHandle = ({
         defaultMessage: 'Move control {controlTitle}',
         values: { controlTitle },
       })}
-      css={styles.dragHandle}
+      css={[styles.dragHandle, highContrast ? styles.dragHandleHighContrast : null]}
     >
       <EuiIcon type="dragHorizontal" aria-hidden={true} />
       {children}

src/platform/packages/private/kbn-controls-renderer/src/types.ts

@@ -36,7 +36,13 @@ export interface ControlsLayout {
 
 export type ControlsRendererParentApi = Pick<
   PresentationContainer,
-  'children$' | 'addNewPanel' | 'replacePanel' | 'removePanel'
+  | 'children$'
+  | 'addNewPanel'
+  | 'replacePanel'
+  | 'removePanel'
+  | 'setIndicateRelatedPanelsId'
+  | 'indicateRelatedPanelsId$'
+  | 'getRelatedPanelIds$'
 > &
   Partial<PublishesUnifiedSearch> &
   PublishesViewMode &

src/platform/packages/shared/controls/controls-schemas/src/types.ts

@@ -8,6 +8,7 @@
  */
 
 import type React from 'react';
+import type { PublishingSubject } from '@kbn/presentation-publishing';
 
 import type { TypeOf } from '@kbn/config-schema';
 import type { controlTitleSchema, dataControlSchema } from './control_schema';
@@ -58,3 +59,9 @@ export type TimeSliderControlState = TypeOf<typeof timeSliderControlSchema>;
 export interface HasCustomPrepend {
   CustomPrependComponent: React.FC<{}>;
 }
+export interface PublishesTooltipLabel {
+  tooltipLabel$: PublishingSubject<string>;
+}
+
+export const apiPublishesTooltipLabel = (api: unknown): api is PublishesTooltipLabel =>
+  Boolean((api as PublishesTooltipLabel)?.tooltipLabel$);

src/platform/packages/shared/kbn-esql-utils/index.ts

@@ -72,6 +72,7 @@ export {
   getQuerySummary,
   getEsqlControls,
   type ESQLStatsQueryMeta,
+  getVariableNamePrefix,
 } from './src';
 
 export { ENABLE_ESQL, GROUP_NOT_SET_VALUE } from './constants';

src/platform/packages/shared/kbn-esql-utils/src/index.ts

@@ -74,6 +74,7 @@ export {
 export { getProjectRoutingFromEsqlQuery } from './utils/set_instructions_helpers';
 export { isComputedColumn, getQuerySummary } from './utils/get_query_summary';
 export { getEsqlControls } from './utils/get_esql_controls';
+export { getVariableNamePrefix } from './utils/get_variable_name_prefix';
 
 // Callback functions
 export * from './utils/callbacks';

src/platform/packages/shared/kbn-esql-utils/src/utils/get_variable_name_prefix.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { ESQLVariableType, VariableNamePrefix } from '@kbn/esql-types';
+
+export const getVariableNamePrefix = (type: ESQLVariableType) => {
+  switch (type) {
+    case ESQLVariableType.FIELDS:
+    case ESQLVariableType.FUNCTIONS:
+      return VariableNamePrefix.IDENTIFIER;
+    case ESQLVariableType.VALUES:
+    case ESQLVariableType.TIME_LITERAL:
+    case ESQLVariableType.MULTI_VALUES:
+    default:
+      return VariableNamePrefix.VALUE;
+  }
+};

src/platform/packages/shared/presentation/presentation_publishing/index.ts

@@ -201,6 +201,10 @@ export type { PublishesSearchSession } from './interfaces/fetch/publishes_search
 // =============================================
 
 export { apiCanAddNewPanel, type CanAddNewPanel } from './interfaces/containers/can_add_new_panel';
+export {
+  apiCanIndicateRelatedPanels,
+  type CanIndicateRelatedPanels,
+} from './interfaces/containers/can_indicate_related_panels';
 
 export {
   apiHasSerializedChildState,
@@ -226,10 +230,12 @@ export {
   apiCanBeCustomized,
   apiCanBeExpanded,
   apiCanBePinned,
+  apiCanBeSelectedToIndicateRelated,
   type IsDuplicable,
   type IsExpandable,
   type IsCustomizable,
   type IsPinnable,
+  type CanBeRelatedPanelsIndicator,
   type HasPanelCapabilities,
 } from './interfaces/containers/panel_capabilities';