[kbn-grid-layout] Allow rows to be reordered (elastic#213166)

Closes elastic#190381

## Summary

This PR adds the ability to drag and drop rows by their headers in order
to reorder them:

![Mar-12-2025
16-07-04](https://github.com/user-attachments/assets/de6afb8e-f009-4c00-b1dc-4804769e54eb)

It can be a bit confusing dragging section headers around when other
sections are expanded - it is easy to lose track of them, especially
when the expanded sections are very large. I experimented with
auto-collapsing all sections on drag, but this felt extremely
disorienting because you instantly lost all of your context - so, to
improve the UI here, I added a "scroll to" effect on drop like so:



https://github.com/user-attachments/assets/0b519783-a4f5-4590-9a1c-580df66a2f66

Reminder that, to test this feature, you need to run Kibana with
examples via `yarn start --run-examples` and navigate to the grid
examples app via `Analytics > Developer examples > Grid Example`.

### 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
- [x] The PR description includes the appropriate Release Notes section,
and the correct `release_note:*` label is applied per the
[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)

### Identify risks

Collapsible sections are not available on Dashboard yet and so there is
no user-facing risk to this PR.

Author: Heenawter

examples/grid_example/public/app.tsx

@@ -23,8 +23,8 @@ import {
   EuiFlexItem,
   EuiPageTemplate,
   EuiSpacer,
+  UseEuiTheme,
   transparentize,
-  useEuiTheme,
 } from '@elastic/eui';
 import { css } from '@emotion/react';
 import { AppMountParameters } from '@kbn/core-application-browser';
@@ -58,8 +58,6 @@ export const GridExample = ({
   coreStart: CoreStart;
   uiActions: UiActionsStart;
 }) => {
-  const { euiTheme } = useEuiTheme();
-
   const savedState = useRef<MockSerializedDashboardState>(getSerializedDashboardState());
   const [hasUnsavedChanges, setHasUnsavedChanges] = useState<boolean>(false);
   const [currentLayout, setCurrentLayout] = useState<GridLayoutData>(
@@ -90,8 +88,8 @@ export const GridExample = ({
             const currentPanel = panels[panelId];
             const savedPanel = savedState.current.panels[panelId];
             panelsAreEqual = deepEqual(
-              { row: 'first', ...currentPanel.gridData },
-              { row: 'first', ...savedPanel.gridData }
+              { row: 'first', ...currentPanel?.gridData },
+              { row: 'first', ...savedPanel?.gridData }
             );
           }
           const hasChanges = !(panelsAreEqual && deepEqual(rows, savedState.current.rows));
@@ -173,41 +171,6 @@ export const GridExample = ({
     mockDashboardApi.rows$.next(rows);
   }, [mockDashboardApi.panels$, mockDashboardApi.rows$]);
 
-  const customLayoutCss = useMemo(() => {
-    const gridColor = transparentize(euiTheme.colors.backgroundFilledAccentSecondary, 0.2);
-    return css`
-      .kbnGridRow--targeted {
-        background-position: top calc((var(--kbnGridGutterSize) / 2) * -1px) left
-          calc((var(--kbnGridGutterSize) / 2) * -1px);
-        background-size: calc((var(--kbnGridColumnWidth) + var(--kbnGridGutterSize)) * 1px)
-          calc((var(--kbnGridRowHeight) + var(--kbnGridGutterSize)) * 1px);
-        background-image: linear-gradient(to right, ${gridColor} 1px, transparent 1px),
-          linear-gradient(to bottom, ${gridColor} 1px, transparent 1px);
-        background-color: ${transparentize(euiTheme.colors.backgroundFilledAccentSecondary, 0.1)};
-      }
-
-      .kbnGridPanel--dragPreview {
-        border-radius: ${euiTheme.border.radius};
-        background-color: ${transparentize(euiTheme.colors.backgroundFilledAccentSecondary, 0.2)};
-        transition: opacity 100ms linear;
-      }
-
-      .kbnGridPanel--resizeHandle {
-        opacity: 0;
-        transition: opacity 0.2s, border 0.2s;
-        border-radius: 7px 0 7px 0;
-        border-bottom: 2px solid ${euiTheme.colors.accentSecondary};
-        border-right: 2px solid ${euiTheme.colors.accentSecondary};
-        &:hover,
-        &:focus {
-          outline-style: none !important;
-          opacity: 1;
-          background-color: ${transparentize(euiTheme.colors.accentSecondary, 0.05)};
-        }
-      }
-    `;
-  }, [euiTheme]);
-
   return (
     <KibanaRenderContextProvider {...coreStart}>
       <EuiPageTemplate grow={false} offset={0} restrictWidth={false}>
@@ -314,7 +277,7 @@ export const GridExample = ({
             useCustomDragHandle={true}
             renderPanelContents={renderPanelContents}
             onLayoutChange={onLayoutChange}
-            css={customLayoutCss}
+            css={layoutStyles}
           />
         </EuiPageTemplate.Section>
       </EuiPageTemplate>
@@ -330,3 +293,50 @@ export const renderGridExampleApp = (
 
   return () => ReactDOM.unmountComponentAtNode(element);
 };
+
+const layoutStyles = ({ euiTheme }: UseEuiTheme) => {
+  const gridColor = transparentize(euiTheme.colors.backgroundFilledAccentSecondary, 0.2);
+  return css({
+    // background for grid row that is being targetted
+    '.kbnGridRow--targeted': {
+      backgroundPosition: `top calc((var(--kbnGridGutterSize) / 2) * -1px) left calc((var(--kbnGridGutterSize) / 2) * -1px)`,
+      backgroundSize: `calc((var(--kbnGridColumnWidth) + var(--kbnGridGutterSize)) * 1px) calc((var(--kbnGridRowHeight) + var(--kbnGridGutterSize)) * 1px)`,
+      backgroundImage: `linear-gradient(to right, ${gridColor} 1px, transparent 1px), linear-gradient(to bottom, ${gridColor} 1px, transparent 1px)`,
+      backgroundColor: `${transparentize(euiTheme.colors.backgroundFilledAccentSecondary, 0.1)}`,
+    },
+    // styling for the "locked to grid" preview for what the panel will look like when dropped / resized
+    '.kbnGridPanel--dragPreview': {
+      borderRadius: `${euiTheme.border.radius}`,
+      backgroundColor: `${transparentize(euiTheme.colors.backgroundFilledAccentSecondary, 0.2)}`,
+      transition: `opacity 100ms linear`,
+    },
+    // styling for panel resize handle
+    '.kbnGridPanel--resizeHandle': {
+      opacity: '0',
+      transition: `opacity 0.2s, border 0.2s`,
+      borderRadius: `7px 0 7px 0`,
+      borderBottom: `2px solid ${euiTheme.colors.accentSecondary}`,
+      borderRight: `2px solid ${euiTheme.colors.accentSecondary}`,
+      '&:hover, &:focus': {
+        outlineStyle: `none !important`,
+        opacity: 1,
+        backgroundColor: `${transparentize(euiTheme.colors.accentSecondary, 0.05)}`,
+      },
+    },
+    // styling for what the grid row header looks like when being dragged
+    '.kbnGridRowHeader--active': {
+      backgroundColor: euiTheme.colors.backgroundBasePlain,
+      border: `1px solid ${euiTheme.border.color}`,
+      borderRadius: `${euiTheme.border.radius.medium} ${euiTheme.border.radius.medium}`,
+      paddingLeft: '8px',
+      // hide accordian arrow + panel count text when row is being dragged
+      '& .kbnGridRowTitle--button svg, & .kbnGridLayout--panelCount': {
+        display: 'none',
+      },
+    },
+    // styles for the area where the row will be dropped
+    '.kbnGridPanel--rowDragPreview': {
+      backgroundColor: euiTheme.components.dragDropDraggingBackground,
+    },
+  });
+};

src/platform/packages/private/kbn-grid-layout/grid/grid_layout.test.tsx

@@ -117,40 +117,66 @@ describe('GridLayout', () => {
     expect(onLayoutChange).toBeCalledTimes(1);
   });
 
-  it(`'renderPanelContents' is not called during dragging`, () => {
-    renderGridLayout();
-
-    // assert that renderPanelContents has been called ONLY ONCE for each of 10 panels on initial render
-    expect(mockRenderPanelContents).toHaveBeenCalledTimes(expectedInitPanelIdsInOrder.length);
-    jest.clearAllMocks();
+  describe('dragging rows', () => {
+    beforeAll(() => {
+      // scroll into view is not mocked by RTL so we need to add this to prevent these tests from throwing
+      Element.prototype.scrollIntoView = jest.fn();
+    });
 
-    const panelHandle = getPanelHandle('panel1');
-    mouseStartDragging(panelHandle);
-    mouseMoveTo({ clientX: 256, clientY: 128 });
+    it('row gets active when dragged', () => {
+      renderGridLayout();
+      expect(screen.getByTestId('kbnGridRowHeader-second')).not.toHaveClass(
+        'kbnGridRowHeader--active'
+      );
 
-    // assert that renderPanelContents has not been called during dragging
-    expect(mockRenderPanelContents).toHaveBeenCalledTimes(0);
+      const rowHandle = screen.getByTestId(`kbnGridRowHeader-second--dragHandle`);
+      mouseStartDragging(rowHandle);
+      mouseMoveTo({ clientX: 256, clientY: 128 });
+      expect(screen.getByTestId('kbnGridRowHeader-second')).toHaveClass('kbnGridRowHeader--active');
 
-    mouseDrop(panelHandle);
-    // assert that renderPanelContents has not been called after reordering
-    expect(mockRenderPanelContents).toHaveBeenCalledTimes(0);
+      mouseDrop(rowHandle);
+      expect(screen.getByTestId('kbnGridRowHeader-second')).not.toHaveClass(
+        'kbnGridRowHeader--active'
+      );
+    });
   });
 
-  it('panel gets active when dragged', () => {
-    renderGridLayout();
-    const panelHandle = getPanelHandle('panel1');
-    expect(screen.getByLabelText('panelId:panel1').closest('div')).toHaveClass('kbnGridPanel', {
-      exact: true,
+  describe('dragging panels', () => {
+    it(`'renderPanelContents' is not called during dragging`, () => {
+      renderGridLayout();
+
+      // assert that renderPanelContents has been called ONLY ONCE for each of 10 panels on initial render
+      expect(mockRenderPanelContents).toHaveBeenCalledTimes(expectedInitPanelIdsInOrder.length);
+      jest.clearAllMocks();
+
+      const panelHandle = getPanelHandle('panel1');
+      mouseStartDragging(panelHandle);
+      mouseMoveTo({ clientX: 256, clientY: 128 });
+
+      // assert that renderPanelContents has not been called during dragging
+      expect(mockRenderPanelContents).toHaveBeenCalledTimes(0);
+
+      mouseDrop(panelHandle);
+      // assert that renderPanelContents has not beesn called after reordering
+      expect(mockRenderPanelContents).toHaveBeenCalledTimes(0);
     });
-    mouseStartDragging(panelHandle);
-    mouseMoveTo({ clientX: 256, clientY: 128 });
-    expect(screen.getByLabelText('panelId:panel1').closest('div')).toHaveClass(
-      'kbnGridPanel kbnGridPanel--active',
-      { exact: true }
-    );
-    mouseDrop(panelHandle);
-    expect(screen.getByLabelText('panelId:panel1').closest('div')).toHaveClass('kbnGridPanel', {
-      exact: true,
+
+    it('panel gets active when dragged', () => {
+      renderGridLayout();
+      const panelHandle = getPanelHandle('panel1');
+      expect(screen.getByLabelText('panelId:panel1').closest('div')).toHaveClass('kbnGridPanel', {
+        exact: true,
+      });
+      mouseStartDragging(panelHandle);
+      mouseMoveTo({ clientX: 256, clientY: 128 });
+      expect(screen.getByLabelText('panelId:panel1').closest('div')).toHaveClass(
+        'kbnGridPanel kbnGridPanel--active',
+        { exact: true }
+      );
+      mouseDrop(panelHandle);
+      expect(screen.getByLabelText('panelId:panel1').closest('div')).toHaveClass('kbnGridPanel', {
+        exact: true,
+      });
     });
   });
 
@@ -163,6 +189,7 @@ describe('GridLayout', () => {
       await assertTabThroughPanel('panel2');
       await assertTabThroughPanel('panel3');
     });
+
     it('on initializing', () => {
       renderGridLayout();
       expect(getAllThePanelIds()).toEqual(expectedInitPanelIdsInOrder);
@@ -191,6 +218,7 @@ describe('GridLayout', () => {
         'panel10',
       ]);
     });
+
     it('after reordering some panels via touch events', async () => {
       renderGridLayout();
 

src/platform/packages/private/kbn-grid-layout/grid/grid_layout.tsx

@@ -11,7 +11,7 @@ import classNames from 'classnames';
 import deepEqual from 'fast-deep-equal';
 import { cloneDeep } from 'lodash';
 import React, { useEffect, useMemo, useRef, useState } from 'react';
-import { combineLatest, pairwise } from 'rxjs';
+import { combineLatest, pairwise, map, distinctUntilChanged } from 'rxjs';
 
 import { css } from '@emotion/react';
 
@@ -90,6 +90,23 @@ export const GridLayout = ({
         }
       });
 
+    /**
+     * This subscription ensures that rows get re-rendered when their orders change
+     */
+    const rowOrderSubscription = combineLatest([
+      gridLayoutStateManager.proposedGridLayout$,
+      gridLayoutStateManager.gridLayout$,
+    ])
+      .pipe(
+        map(([proposedGridLayout, gridLayout]) =>
+          getRowKeysInOrder(proposedGridLayout ?? gridLayout)
+        ),
+        distinctUntilChanged(deepEqual)
+      )
+      .subscribe((rowKeys) => {
+        setRowIdsInOrder(rowKeys);
+      });
+
     /**
      * This subscription adds and/or removes the necessary class names related to styling for
      * mobile view and a static (non-interactable) grid layout
@@ -115,6 +132,7 @@ export const GridLayout = ({
 
     return () => {
       onLayoutChangeSubscription.unsubscribe();
+      rowOrderSubscription.unsubscribe();
       gridLayoutClassSubscription.unsubscribe();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -160,7 +178,7 @@ const styles = {
     padding: 'calc(var(--kbnGridGutterSize) * 1px)',
   }),
   hasActivePanel: css({
-    '&:has(.kbnGridPanel--active)': {
+    '&:has(.kbnGridPanel--active), &:has(.kbnGridRowHeader--active)': {
       // disable pointer events and user select on drag + resize
       userSelect: 'none',
       pointerEvents: 'none',

src/platform/packages/private/kbn-grid-layout/grid/grid_panel/drag_handle/default_drag_handle.tsx

@@ -47,7 +47,7 @@ const styles = ({ euiTheme }: UseEuiTheme) =>
     border: `1px solid ${euiTheme.border.color}`,
     borderBottom: 'none',
     backgroundColor: euiTheme.colors.backgroundBasePlain,
-    borderRadius: `${euiTheme.border.radius} ${euiTheme.border.radius} 0 0`,
+    borderRadius: `${euiTheme.border.radius.medium} ${euiTheme.border.radius.medium} 0 0`,
     transition: `${euiTheme.animation.slow} opacity`,
     touchAction: 'none',
     '.kbnGridPanel:hover &, .kbnGridPanel:focus-within &, &:active, &:focus': {

src/platform/packages/private/kbn-grid-layout/grid/grid_panel/drag_handle/use_drag_handle_api.tsx

@@ -9,9 +9,9 @@
 
 import { useCallback, useEffect, useRef } from 'react';
 
-import { useGridLayoutEvents } from '../../use_grid_layout_events';
-import { UserInteractionEvent } from '../../use_grid_layout_events/types';
 import { useGridLayoutContext } from '../../use_grid_layout_context';
+import { useGridLayoutPanelEvents } from '../../use_grid_layout_events';
+import { UserInteractionEvent } from '../../use_grid_layout_events/types';
 
 export interface DragHandleApi {
   startDrag: (e: UserInteractionEvent) => void;
@@ -27,7 +27,7 @@ export const useDragHandleApi = ({
 }): DragHandleApi => {
   const { useCustomDragHandle } = useGridLayoutContext();
 
-  const startInteraction = useGridLayoutEvents({
+  const startInteraction = useGridLayoutPanelEvents({
     interactionType: 'drag',
     panelId,
     rowId,

src/platform/packages/private/kbn-grid-layout/grid/grid_panel/grid_panel.tsx

@@ -16,7 +16,7 @@ import { css } from '@emotion/react';
 import { useGridLayoutContext } from '../use_grid_layout_context';
 import { DefaultDragHandle } from './drag_handle/default_drag_handle';
 import { useDragHandleApi } from './drag_handle/use_drag_handle_api';
-import { ResizeHandle } from './resize_handle';
+import { ResizeHandle } from './grid_panel_resize_handle';
 
 export interface GridPanelProps {
   panelId: string;
@@ -50,6 +50,14 @@ export const GridPanel = React.memo(({ panelId, rowId }: GridPanelProps) => {
     `;
   }, [gridLayoutStateManager, rowId, panelId]);
 
+  useEffect(() => {
+    return () => {
+      // remove reference on unmount
+      delete gridLayoutStateManager.panelRefs.current[rowId][panelId];
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   useEffect(
     () => {
       /** Update the styles of the panel via a subscription to prevent re-renders */

src/platform/packages/private/kbn-grid-layout/grid/drag_preview.tsx renamed to src/platform/packages/private/kbn-grid-layout/grid/grid_panel/grid_panel_drag_preview.tsx

@@ -11,9 +11,9 @@ import React, { useEffect, useRef } from 'react';
 import { combineLatest, skip } from 'rxjs';
 
 import { css } from '@emotion/react';
-import { useGridLayoutContext } from './use_grid_layout_context';
+import { useGridLayoutContext } from '../use_grid_layout_context';
 
-export const DragPreview = React.memo(({ rowId }: { rowId: string }) => {
+export const GridPanelDragPreview = React.memo(({ rowId }: { rowId: string }) => {
   const { gridLayoutStateManager } = useGridLayoutContext();
 
   const dragPreviewRef = useRef<HTMLDivElement | null>(null);
@@ -54,4 +54,4 @@ export const DragPreview = React.memo(({ rowId }: { rowId: string }) => {
 
 const styles = css({ display: 'none', pointerEvents: 'none' });
 
-DragPreview.displayName = 'KbnGridLayoutDragPreview';
+GridPanelDragPreview.displayName = 'KbnGridLayoutPanelDragPreview';

src/platform/packages/private/kbn-grid-layout/grid/grid_panel/resize_handle.tsx renamed to src/platform/packages/private/kbn-grid-layout/grid/grid_panel/grid_panel_resize_handle.tsx

@@ -13,10 +13,10 @@ import type { UseEuiTheme } from '@elastic/eui';
 import { css } from '@emotion/react';
 import { i18n } from '@kbn/i18n';
 
-import { useGridLayoutEvents } from '../use_grid_layout_events';
+import { useGridLayoutPanelEvents } from '../use_grid_layout_events';
 
 export const ResizeHandle = React.memo(({ rowId, panelId }: { rowId: string; panelId: string }) => {
-  const startInteraction = useGridLayoutEvents({
+  const startInteraction = useGridLayoutPanelEvents({
     interactionType: 'resize',
     panelId,
     rowId,

src/platform/packages/private/kbn-grid-layout/grid/grid_row/delete_grid_row_modal.tsx

@@ -19,8 +19,8 @@ import {
 } from '@elastic/eui';
 import { i18n } from '@kbn/i18n';
 
-import { deleteRow, movePanelsToRow } from '../utils/row_management';
 import { useGridLayoutContext } from '../use_grid_layout_context';
+import { deleteRow, movePanelsToRow } from '../utils/row_management';
 
 export const DeleteGridRowModal = ({
   rowId,