@keboola/design 1.0.0

package/src/components/Sidebar/SidebarProvider/SidebarProvider.tsx

@@ -0,0 +1,171 @@
+import { type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
+
+import type { SidebarCollapsible, SidebarMode, SidebarSide, SidebarVariant } from '../types';
+import { calcEffectiveWidths } from '../utils';
+
+import type { SidebarContextValue } from './context';
+import { SidebarContext } from './context';
+import { useSidebarState } from './useSidebarState';
+
+const DEFAULT_SIDEBAR_VARIANT: SidebarVariant = 'none';
+const DEFAULT_SIDEBAR_MODE: SidebarMode = 'expanded';
+const DEFAULT_SIDEBAR_COLLAPSIBLE: SidebarCollapsible = 'off-canvas';
+
+type Props = {
+  children?: ReactNode;
+  // left state
+  defaultLeftMode?: SidebarMode;
+  leftMode?: SidebarMode;
+  onLeftModeChange?: (mode: SidebarMode) => void;
+
+  // right state
+  defaultRightMode?: SidebarMode;
+  rightMode?: SidebarMode;
+  onRightModeChange?: (mode: SidebarMode) => void;
+
+  // left
+  leftVariant?: SidebarVariant;
+  leftWidth?: number;
+  leftCollapsible?: SidebarCollapsible;
+
+  // right
+  rightVariant?: SidebarVariant;
+  rightWidth?: number;
+  rightCollapsible?: SidebarCollapsible;
+
+  // width change callbacks
+  onLeftWidthChange?: (width: number) => void;
+  onRightWidthChange?: (width: number) => void;
+
+  // fill
+  defaultFilledSide?: SidebarSide | null;
+};
+
+export const SidebarProvider = ({
+  children,
+  // left state
+  defaultLeftMode = DEFAULT_SIDEBAR_MODE,
+  leftMode,
+  onLeftModeChange,
+
+  // right state
+  defaultRightMode = DEFAULT_SIDEBAR_MODE,
+  rightMode,
+  onRightModeChange,
+
+  // left
+  leftCollapsible = DEFAULT_SIDEBAR_COLLAPSIBLE,
+  leftVariant = DEFAULT_SIDEBAR_VARIANT,
+  leftWidth,
+
+  // right
+  rightCollapsible = DEFAULT_SIDEBAR_COLLAPSIBLE,
+  rightVariant = DEFAULT_SIDEBAR_VARIANT,
+  rightWidth,
+
+  // width change callbacks
+  onLeftWidthChange,
+  onRightWidthChange,
+
+  // fill
+  defaultFilledSide = null,
+}: Props) => {
+  const [filledSide, setFilledSide] = useState<SidebarSide | null>(defaultFilledSide);
+  const [isLeftDragging, setIsLeftDragging] = useState(false);
+  const [isRightDragging, setIsRightDragging] = useState(false);
+  const [leftDragWidth, setLeftDragWidth] = useState<number | null>(null);
+  const [rightDragWidth, setRightDragWidth] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (leftDragWidth !== null && leftWidth === leftDragWidth) setLeftDragWidth(null);
+  }, [leftWidth, leftDragWidth]);
+
+  useEffect(() => {
+    if (rightDragWidth !== null && rightWidth === rightDragWidth) setRightDragWidth(null);
+  }, [rightWidth, rightDragWidth]);
+
+  const leftState = useSidebarState({
+    defaultMode: defaultLeftMode,
+    mode: leftMode,
+    onModeChange: onLeftModeChange,
+  });
+
+  const rightState = useSidebarState({
+    defaultMode: defaultRightMode,
+    mode: rightMode,
+    onModeChange: onRightModeChange,
+  });
+
+  const toggleLeftFill = useCallback(
+    () => setFilledSide((prev) => (prev === 'left' ? null : 'left')),
+    [],
+  );
+  const toggleRightFill = useCallback(
+    () => setFilledSide((prev) => (prev === 'right' ? null : 'right')),
+    [],
+  );
+
+  const value = useMemo<SidebarContextValue>(
+    () => ({
+      left: {
+        ...leftState,
+        isFill: filledSide === 'left',
+        toggleFill: toggleLeftFill,
+        widths: calcEffectiveWidths({
+          variant: leftVariant,
+          width: leftDragWidth ?? leftWidth,
+          collapsible: leftCollapsible,
+          state: leftState.state,
+          mode: leftState.mode,
+        }),
+        collapsible: leftCollapsible,
+        variant: leftVariant,
+        baseWidth: leftDragWidth ?? leftWidth,
+        onWidthChange: onLeftWidthChange,
+        setDragWidth: setLeftDragWidth,
+        isDragging: isLeftDragging,
+        setIsDragging: setIsLeftDragging,
+      },
+      right: {
+        ...rightState,
+        isFill: filledSide === 'right',
+        toggleFill: toggleRightFill,
+        widths: calcEffectiveWidths({
+          variant: rightVariant,
+          width: rightDragWidth ?? rightWidth,
+          collapsible: rightCollapsible,
+          state: rightState.state,
+          mode: rightState.mode,
+        }),
+        collapsible: rightCollapsible,
+        variant: rightVariant,
+        baseWidth: rightDragWidth ?? rightWidth,
+        onWidthChange: onRightWidthChange,
+        setDragWidth: setRightDragWidth,
+        isDragging: isRightDragging,
+        setIsDragging: setIsRightDragging,
+      },
+    }),
+    [
+      leftState,
+      filledSide,
+      toggleLeftFill,
+      leftVariant,
+      leftWidth,
+      leftDragWidth,
+      leftCollapsible,
+      onLeftWidthChange,
+      isLeftDragging,
+      rightState,
+      toggleRightFill,
+      rightVariant,
+      rightWidth,
+      rightDragWidth,
+      rightCollapsible,
+      onRightWidthChange,
+      isRightDragging,
+    ],
+  );
+
+  return <SidebarContext value={value}>{children}</SidebarContext>;
+};

package/src/components/Sidebar/SidebarProvider/context.ts

@@ -0,0 +1,35 @@
+import { createContext, use } from 'react';
+
+import type { SidebarCollapsible, SidebarSide, SidebarVariant } from '../types';
+import type { calcEffectiveWidths } from '../utils';
+
+import type { useSidebarState } from './useSidebarState';
+
+type SidebarWidths = ReturnType<typeof calcEffectiveWidths>;
+type SidebarState = ReturnType<typeof useSidebarState>;
+
+type SidebarSideValue = SidebarState & {
+  isFill: boolean;
+  toggleFill: () => void;
+  widths: SidebarWidths;
+  collapsible: SidebarCollapsible;
+  variant: SidebarVariant;
+  baseWidth: number | undefined;
+  onWidthChange: ((width: number) => void) | undefined;
+  setDragWidth: (width: number | null) => void;
+  isDragging: boolean;
+  setIsDragging: (dragging: boolean) => void;
+};
+
+export type SidebarContextValue = {
+  left: SidebarSideValue;
+  right: SidebarSideValue;
+};
+
+export const SidebarContext = createContext<SidebarContextValue | null>(null);
+
+export const useSidebar = (side: SidebarSide = 'left'): SidebarSideValue => {
+  const context = use(SidebarContext);
+  if (context === null) throw new Error('useSidebar must be used within a SidebarProvider.');
+  return context[side];
+};

package/src/components/Sidebar/SidebarProvider/index.ts

@@ -0,0 +1,2 @@
+export * from './SidebarProvider';
+export { useSidebar } from './context';

package/src/components/Sidebar/SidebarProvider/useHoverTracking.test.ts

@@ -0,0 +1,199 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useHoverTracking } from './useHoverTracking';
+
+const fireMouseEnter = (element: HTMLElement) => {
+  act(() => element.dispatchEvent(new MouseEvent('mouseenter', { bubbles: false })));
+};
+
+const fireMouseLeave = (element: HTMLElement) => {
+  act(() => element.dispatchEvent(new MouseEvent('mouseleave', { bubbles: false })));
+};
+
+/**
+ * Flush microtasks so jsdom's MutationObserver callbacks execute.
+ * MutationObserver in jsdom fires as a microtask, not synchronously.
+ */
+const flushMicrotasks = async () => {
+  await act(async () => {});
+};
+
+/** Simulates a portal trigger opening inside the sidebar. */
+const addOpenPortalTrigger = (parent: HTMLElement) => {
+  const trigger = document.createElement('button');
+  trigger.setAttribute('aria-haspopup', 'menu');
+  trigger.setAttribute('aria-expanded', 'false');
+  parent.appendChild(trigger);
+
+  const open = async () => {
+    trigger.setAttribute('aria-expanded', 'true');
+    await flushMicrotasks();
+  };
+
+  const close = async () => {
+    trigger.setAttribute('aria-expanded', 'false');
+    await flushMicrotasks();
+  };
+
+  return { trigger, open, close };
+};
+
+describe('useHoverTracking', () => {
+  let element: HTMLDivElement;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    element = document.createElement('div');
+    document.body.appendChild(element);
+  });
+
+  afterEach(() => {
+    element.remove();
+    vi.useRealTimers();
+  });
+
+  describe('basic hover tracking', () => {
+    it('starts as not hovered', () => {
+      const { result } = renderHook(() => useHoverTracking(element));
+      expect(result.current).toBe(false);
+    });
+
+    it('tracks mouseenter', () => {
+      const { result } = renderHook(() => useHoverTracking(element));
+
+      fireMouseEnter(element);
+      expect(result.current).toBe(true);
+    });
+
+    it('tracks mouseleave', () => {
+      const { result } = renderHook(() => useHoverTracking(element));
+
+      fireMouseEnter(element);
+      fireMouseLeave(element);
+      expect(result.current).toBe(false);
+    });
+
+    it('does not attach listeners when element is null', () => {
+      const { result } = renderHook(() => useHoverTracking(null));
+      expect(result.current).toBe(false);
+    });
+  });
+
+  describe('automatic portal-based hover locking', () => {
+    it('ignores mouseleave while a portal trigger is open', async () => {
+      const { result } = renderHook(() => useHoverTracking(element));
+      const portal = addOpenPortalTrigger(element);
+
+      fireMouseEnter(element);
+      await portal.open();
+
+      fireMouseLeave(element);
+      expect(result.current).toBe(true);
+    });
+
+    it('reconciles hover state when portal trigger closes and pointer is outside', async () => {
+      vi.spyOn(element, 'matches').mockReturnValue(false);
+      const { result } = renderHook(() => useHoverTracking(element));
+      const portal = addOpenPortalTrigger(element);
+
+      fireMouseEnter(element);
+      await portal.open();
+      fireMouseLeave(element);
+      expect(result.current).toBe(true);
+
+      await portal.close();
+      act(() => vi.runAllTimers());
+
+      expect(result.current).toBe(false);
+      expect(element.matches).toHaveBeenCalledWith(':hover');
+    });
+
+    it('keeps hover active when portal trigger closes and pointer is still over element', async () => {
+      vi.spyOn(element, 'matches').mockReturnValue(true);
+      const { result } = renderHook(() => useHoverTracking(element));
+      const portal = addOpenPortalTrigger(element);
+
+      fireMouseEnter(element);
+      await portal.open();
+      fireMouseLeave(element);
+
+      await portal.close();
+      act(() => vi.runAllTimers());
+
+      expect(result.current).toBe(true);
+    });
+
+    it('resumes normal mouseleave tracking after portal closes', async () => {
+      vi.spyOn(element, 'matches').mockReturnValue(true);
+      const { result } = renderHook(() => useHoverTracking(element));
+      const portal = addOpenPortalTrigger(element);
+
+      fireMouseEnter(element);
+      await portal.open();
+
+      await portal.close();
+      act(() => vi.runAllTimers());
+
+      fireMouseLeave(element);
+      expect(result.current).toBe(false);
+    });
+
+    it('handles multiple open/close cycles', async () => {
+      vi.spyOn(element, 'matches').mockReturnValue(false);
+      const { result } = renderHook(() => useHoverTracking(element));
+      const portal = addOpenPortalTrigger(element);
+
+      // first cycle
+      fireMouseEnter(element);
+      await portal.open();
+      fireMouseLeave(element);
+      await portal.close();
+      act(() => vi.runAllTimers());
+      expect(result.current).toBe(false);
+
+      // second cycle
+      fireMouseEnter(element);
+      await portal.open();
+      fireMouseLeave(element);
+      expect(result.current).toBe(true);
+
+      await portal.close();
+      act(() => vi.runAllTimers());
+      expect(result.current).toBe(false);
+    });
+
+    it('stays locked when one of multiple portal triggers is still open', async () => {
+      const { result } = renderHook(() => useHoverTracking(element));
+      const portal1 = addOpenPortalTrigger(element);
+      const portal2 = addOpenPortalTrigger(element);
+
+      fireMouseEnter(element);
+      await portal1.open();
+      await portal2.open();
+      fireMouseLeave(element);
+
+      await portal1.close();
+      act(() => vi.runAllTimers());
+
+      // portal2 still open — should stay hovered
+      expect(result.current).toBe(true);
+    });
+
+    it('locks hover immediately when a portal trigger is already open on mount', () => {
+      // Add an already-open portal trigger before the hook mounts.
+      const trigger = document.createElement('button');
+      trigger.setAttribute('aria-haspopup', 'menu');
+      trigger.setAttribute('aria-expanded', 'true');
+      element.appendChild(trigger);
+
+      const { result } = renderHook(() => useHoverTracking(element));
+
+      fireMouseEnter(element);
+      fireMouseLeave(element);
+
+      // Hover should be locked because the trigger was already open at mount time.
+      expect(result.current).toBe(true);
+    });
+  });
+});

package/src/components/Sidebar/SidebarProvider/useHoverTracking.ts

@@ -0,0 +1,72 @@
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * CSS selectors matching portal-based overlay triggers in their open state.
+ *
+ * The sidebar's hover tracking ignores `mouseleave` while any of these selectors
+ * match inside the sidebar DOM — preventing the sidebar from collapsing while the
+ * user interacts with portal content rendered outside the sidebar tree.
+ *
+ * Update this list when changing or adding new components:
+ */
+const PORTAL_OPEN_SELECTORS = [
+  '[aria-haspopup="menu"][aria-expanded=true]', // DropdownMenu
+  '[aria-haspopup="dialog"][aria-expanded=true]', // Popover, Dialogs (Modal, Sheet)
+];
+
+const PORTAL_OPEN_SELECTORS_STRING = PORTAL_OPEN_SELECTORS.join(',');
+
+export const useHoverTracking = (sidebarElement: HTMLElement | null) => {
+  const [isHovered, setIsHovered] = useState(false);
+  const isLockedRef = useRef(false);
+
+  useEffect(() => {
+    if (!sidebarElement) return;
+
+    const handleMouseEnter = () => setIsHovered(true);
+    const handleMouseLeave = () => {
+      if (isLockedRef.current) return;
+      setIsHovered(false);
+    };
+
+    sidebarElement.addEventListener('mouseenter', handleMouseEnter);
+    sidebarElement.addEventListener('mouseleave', handleMouseLeave);
+
+    return () => {
+      sidebarElement.removeEventListener('mouseenter', handleMouseEnter);
+      sidebarElement.removeEventListener('mouseleave', handleMouseLeave);
+    };
+  }, [sidebarElement]);
+
+  useEffect(() => {
+    if (!sidebarElement) return;
+    let animationFrameId: number;
+
+    const observer = new MutationObserver(() => {
+      const hasOpenPortal = sidebarElement.querySelector(PORTAL_OPEN_SELECTORS_STRING) !== null;
+      isLockedRef.current = hasOpenPortal;
+
+      if (hasOpenPortal) return;
+
+      animationFrameId = requestAnimationFrame(() => {
+        setIsHovered(sidebarElement.matches(':hover'));
+      });
+    });
+
+    // Sync lock state immediately in case a portal trigger is already open on mount.
+    isLockedRef.current = sidebarElement.querySelector(PORTAL_OPEN_SELECTORS_STRING) !== null;
+
+    observer.observe(sidebarElement, {
+      attributes: true,
+      attributeFilter: ['aria-expanded'],
+      subtree: true,
+    });
+
+    return () => {
+      cancelAnimationFrame(animationFrameId);
+      observer.disconnect();
+    };
+  }, [sidebarElement]);
+
+  return isHovered;
+};

package/src/components/Sidebar/SidebarProvider/useSidebarState.ts

@@ -0,0 +1,50 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import { useElement } from '../../../hooks/useElement';
+import type { SidebarMode, SidebarState } from '../types';
+
+import { useHoverTracking } from './useHoverTracking';
+
+type Props = {
+  defaultMode?: SidebarMode;
+  mode?: SidebarMode;
+  onModeChange?: (state: SidebarMode) => void;
+};
+
+export const useSidebarState = ({ defaultMode, mode: modeProp, onModeChange }: Props) => {
+  const [sidebarElement, setSidebarElement] = useElement();
+  const isHovered = useHoverTracking(sidebarElement);
+  const [_mode, _setMode] = useState(defaultMode ?? 'expanded');
+  const mode = modeProp ?? _mode;
+
+  const setMode = useCallback(
+    (dispatch: Parameters<typeof _setMode>[0]) => {
+      const newState = typeof dispatch === 'function' ? dispatch(mode) : dispatch;
+      const set = onModeChange ?? _setMode;
+      set(newState);
+    },
+    [onModeChange, mode],
+  );
+
+  const toggle = useCallback(() => {
+    setMode((currState) => (currState === 'expanded' ? 'collapsed' : 'expanded'));
+  }, [setMode]);
+
+  const state: SidebarState = (() => {
+    if (mode === 'expand-on-hover') return isHovered ? 'expanded' : 'collapsed';
+    return mode;
+  })();
+
+  return useMemo(
+    () => ({
+      isHovered,
+      toggle,
+      setMode,
+      mode,
+      state,
+      sidebarElement,
+      setSidebarElement,
+    }),
+    [isHovered, toggle, setMode, mode, state, sidebarElement, setSidebarElement],
+  );
+};