feat(SplitterLayout): introduceonResize event

Author: Lukas742

packages/main/src/components/Splitter/index.tsx

@@ -5,15 +5,19 @@ import horizontalGripIcon from '@ui5/webcomponents-icons/dist/horizontal-grip.js
 import verticalGripIcon from '@ui5/webcomponents-icons/dist/vertical-grip.js';
 import { useCurrentTheme, useI18nBundle, useIsRTL, useSyncRef, useStylesheet } from '@ui5/webcomponents-react-base';
 import { forwardRef, useEffect, useRef, useState } from 'react';
+import type { KeyboardEventHandler, PointerEventHandler } from 'react';
 import { PRESS_ARROW_KEYS_TO_MOVE } from '../../i18n/i18n-defaults.js';
 import type { CommonProps } from '../../types/index.js';
-import { Button, Icon } from '../../webComponents/index.js';
+import { Button } from '../../webComponents/Button/index.js';
+import { Icon } from '../../webComponents/Icon/index.js';
+import type { SplitterLayoutPropTypes } from '../SplitterLayout/types.js';
 import { classNames, styleData } from './Splitter.module.css.js';
 
 export interface SplitterPropTypes extends CommonProps {
   height: string | number;
   width: string | number;
   vertical: boolean;
+  onResize: SplitterLayoutPropTypes['onResize'] | undefined;
 }
 
 const verticalPositionInfo = {
@@ -39,7 +43,7 @@ const horizontalPositionInfo = {
 };
 
 const Splitter = forwardRef<HTMLDivElement, SplitterPropTypes>((props, ref) => {
-  const { vertical } = props;
+  const { vertical, onResize } = props;
   const i18nBundle = useI18nBundle('@ui5/webcomponents-react');
   const [componentRef, localRef] = useSyncRef<HTMLDivElement>(ref);
   const isRtl = useIsRTL(localRef);
@@ -58,6 +62,38 @@ const Splitter = forwardRef<HTMLDivElement, SplitterPropTypes>((props, ref) => {
   const [isDragging, setIsDragging] = useState<boolean | string>(false);
   const [isSiblings, setIsSiblings] = useState(['previousSibling', 'nextSibling']);
 
+  const animationFrameIdRef = useRef(null);
+  function fireOnResize(prevSibling: HTMLElement, nextSibling: HTMLElement) {
+    if (animationFrameIdRef.current) {
+      cancelAnimationFrame(animationFrameIdRef.current);
+    }
+    if (typeof onResize !== 'function') {
+      return;
+    }
+    animationFrameIdRef.current = requestAnimationFrame(() => {
+      const logicalPrevSibling = isRtl ? nextSibling : prevSibling;
+      const logicalNextSibling = isRtl ? prevSibling : nextSibling;
+      const splitterWidth = localRef.current.getBoundingClientRect()[positionKeys.size];
+      onResize({
+        areas: [
+          {
+            size: logicalPrevSibling.getBoundingClientRect()?.[positionKeys.size] + splitterWidth,
+            area: logicalPrevSibling,
+          },
+          {
+            // last element doesn't have splitter
+            size:
+              logicalNextSibling.getBoundingClientRect()?.[positionKeys.size] +
+              (logicalNextSibling.nextElementSibling !== null ? splitterWidth : 0),
+            area: logicalNextSibling,
+          },
+        ],
+        splitter: localRef.current,
+      });
+      animationFrameIdRef.current = null;
+    });
+  }
+
   const handleSplitterMove = (e) => {
     const offset = resizerClickOffset.current;
     const previousSibling = localRef.current[isSiblings[0]] as HTMLDivElement;
@@ -71,10 +107,10 @@ const Splitter = forwardRef<HTMLDivElement, SplitterPropTypes>((props, ref) => {
 
     const move = () => {
       previousSibling.style.flex = `0 0 ${previousSiblingSize.current + sizeDiv}px`;
-
       if (nextSibling.nextSibling && previousSiblingSize.current + sizeDiv > 0) {
         nextSibling.style.flex = `0 0 ${nextSiblingSize.current - sizeDiv}px`;
       }
+      fireOnResize(previousSibling, nextSibling);
     };
 
     if (
@@ -126,6 +162,7 @@ const Splitter = forwardRef<HTMLDivElement, SplitterPropTypes>((props, ref) => {
           (nextSiblingRect?.[positionKeys.size] as number) + prevSiblingRect?.[positionKeys.size]
         }px`;
       }
+      fireOnResize(prevSibling, nextSibling);
     }
 
     // right
@@ -142,10 +179,12 @@ const Splitter = forwardRef<HTMLDivElement, SplitterPropTypes>((props, ref) => {
           (prevSiblingRect?.[positionKeys.size] as number) + nextSiblingRect?.[positionKeys.size]
         }px`;
       }
+
+      fireOnResize(prevSibling, nextSibling);
     }
   };
 
-  const handleMoveSplitterStart = (e) => {
+  const handleMoveSplitterStart: PointerEventHandler<HTMLDivElement> = (e) => {
     if (e.type === 'pointerdown' && e.pointerType !== 'touch') {
       return;
     }
@@ -175,7 +214,7 @@ const Splitter = forwardRef<HTMLDivElement, SplitterPropTypes>((props, ref) => {
     start.current = e[`client${positionKeys.position}`];
   };
 
-  const onHandleKeyDown = (e) => {
+  const onHandleKeyDown: KeyboardEventHandler<HTMLDivElement> = (e) => {
     const keyEventProperties = e.code ?? e.key;
     if (
       keyEventProperties === 'ArrowRight' ||
@@ -203,6 +242,12 @@ const Splitter = forwardRef<HTMLDivElement, SplitterPropTypes>((props, ref) => {
         const secondSiblingSize = secondSibling.getBoundingClientRect()?.[positionKeys.size] as number;
         secondSibling.style.flex = `0 0 ${secondSiblingSize - tickSize}px`;
         firstSibling.style.flex = `0 0 ${firstSiblingSize + tickSize}px`;
+
+        if (keyEventProperties === 'ArrowLeft' || keyEventProperties === 'ArrowUp') {
+          fireOnResize(secondSibling, firstSibling);
+        } else {
+          fireOnResize(firstSibling, secondSibling);
+        }
       }
     }
   };

packages/main/src/components/SplitterElement/index.tsx

@@ -20,6 +20,8 @@ export interface SplitterElementPropTypes extends CommonProps {
   /**
    * Defines the initial size of the `SplitterElement`.
    *
+   * __Note:__ In order to preserve the intended design, at least one `SplitterElement` should have a dynamic `size`.
+   *
    * @default `"auto"`
    */
   size?: CSSProperties['width'] | CSSProperties['height'];

packages/main/src/components/SplitterLayout/index.tsx

@@ -20,9 +20,11 @@ import { useConcatSplitterElements } from './useConcatSplitterElements.js';
  * can be set.
  * The splitter bars are focusable to enable resizing of the content areas via keyboard. The size of the content areas
  * can be manipulated when the splitter bar is focused and Left/Down/Right/Up are pressed.
+ *
+ * __Note:__ In order to preserve the intended design, at least one `SplitterElement` should have a dynamic `size`.
  */
 const SplitterLayout = forwardRef<HTMLDivElement, SplitterLayoutPropTypes>((props, ref) => {
-  const { vertical, children, title, style, className, options, ...rest } = props;
+  const { vertical, children, title, style, className, options, onResize, ...rest } = props;
   const [componentRef, sLRef] = useSyncRef(ref);
   const [reset, setReset] = useState(undefined);
   const prevSize = useRef({ width: undefined, height: undefined });
@@ -34,6 +36,7 @@ const SplitterLayout = forwardRef<HTMLDivElement, SplitterLayoutPropTypes>((prop
     width: style?.width,
     height: style?.height,
     vertical,
+    onResize,
   });
 
   useStylesheet(styleData, SplitterLayout.displayName);

packages/main/src/components/SplitterLayout/types.ts

@@ -21,6 +21,21 @@ interface SplitterLayoutOptions {
 
 type SplitterLayoutChild = ReactElement<SplitterElementPropTypes> | undefined | false | null;
 
+interface ResizeArea {
+  size: number;
+  area: HTMLElement;
+}
+interface OnResizeParam {
+  /**
+   * The `SplitterElement`s that are being resized.
+   * The first element is the previous sibling of the splitter bar, the second element is the next sibling.
+   *
+   * __Note:__ The array reflects the logical position of the `SplitterElement`s.
+   */
+  areas: [ResizeArea, ResizeArea];
+  splitter: HTMLElement;
+}
+
 export interface SplitterLayoutPropTypes extends CommonProps {
   /**
    * Controls if a vertical or horizontal `SplitterLayout` is rendered.
@@ -34,4 +49,12 @@ export interface SplitterLayoutPropTypes extends CommonProps {
    * Defines options to customize the behavior of the SplitterLayout.
    */
   options?: SplitterLayoutOptions;
+  /**
+   * Fired when contents are resized.
+   *
+   * __Note:__
+   * - Resize events can fire many times in quick succession, it’s therefore strongly recommended to debounce your handler if you’re updating React state or causing other expensive operations.
+   * - The `areas` array reflects the logical position of the `SplitterElement`s relative to the "Splitter".
+   */
+  onResize?: (e: OnResizeParam) => void;
 }

packages/main/src/components/SplitterLayout/useConcatSplitterElements.tsx

@@ -9,6 +9,7 @@ interface ConcatSplitterElements {
   width: CSSProperties['width'];
   height: CSSProperties['height'];
   vertical: boolean;
+  onResize: SplitterLayoutPropTypes['onResize'] | undefined;
 }
 
 export const useConcatSplitterElements = (concatSplitterElements: ConcatSplitterElements) => {
@@ -42,6 +43,7 @@ export const useConcatSplitterElements = (concatSplitterElements: ConcatSplitter
             height={concatSplitterElements?.height}
             width={concatSplitterElements?.width}
             vertical={concatSplitterElements?.vertical}
+            onResize={concatSplitterElements?.onResize}
           />,
         );
         // -1 => prev element