feat: refactor Sidebar into standalone reusable component (#5663)

🚀!

src/components/Sidebar/Sidebar.scss

@@ -0,0 +1,89 @@
+@import "open-color/open-color";
+@import "../../css/variables.module";
+
+.excalidraw {
+  .layer-ui__sidebar {
+    position: absolute;
+    top: var(--sat);
+    bottom: var(--sab);
+    right: var(--sar);
+    z-index: 5;
+
+    box-shadow: var(--shadow-island);
+    overflow: hidden;
+    border-radius: var(--border-radius-lg);
+    margin: var(--space-factor);
+    width: calc(#{$right-sidebar-width} - var(--space-factor) * 2);
+
+    padding: 0.5rem;
+    box-sizing: border-box;
+
+    .Island {
+      box-shadow: none;
+    }
+
+    .ToolIcon__icon {
+      border-radius: var(--border-radius-md);
+    }
+
+    .ToolIcon__icon__close {
+      .Modal__close {
+        width: calc(var(--space-factor) * 7);
+        height: calc(var(--space-factor) * 7);
+        display: flex;
+        justify-content: center;
+        align-items: center;
+        color: var(--color-text);
+      }
+    }
+
+    .Island {
+      --padding: 0;
+      background-color: var(--island-bg-color);
+      border-radius: var(--border-radius-lg);
+      padding: calc(var(--padding) * var(--space-factor));
+      position: relative;
+      transition: box-shadow 0.5s ease-in-out;
+    }
+  }
+
+  .layer-ui__sidebar__header {
+    display: flex;
+    align-items: center;
+    width: 100%;
+    margin: 2px 0 15px 0;
+    &:empty {
+      margin: 0;
+    }
+    button {
+      // 2px from the left to account for focus border of left-most button
+      margin: 0 2px;
+    }
+  }
+
+  .layer-ui__sidebar__header__buttons {
+    display: flex;
+    align-items: center;
+    margin-left: auto;
+  }
+
+  .layer-ui__sidebar-dock-button {
+    @include toolbarButtonColorStates;
+    margin-right: 0.2rem;
+
+    .ToolIcon_type_floating .ToolIcon__icon {
+      width: calc(var(--space-factor) * 7);
+      height: calc(var(--space-factor) * 7);
+      svg {
+        // mirror
+        transform: scale(-1, 1);
+      }
+    }
+
+    .ToolIcon_type_checkbox {
+      &:not(.ToolIcon_toggle_opaque):checked + .ToolIcon__icon {
+        background-color: var(--color-primary);
+      }
+    }
+  }
+}

src/components/Sidebar/Sidebar.test.tsx

@@ -0,0 +1,355 @@
+import React from "react";
+import { Excalidraw, Sidebar } from "../../packages/excalidraw/index";
+import {
+  act,
+  fireEvent,
+  queryAllByTestId,
+  queryByTestId,
+  render,
+  waitFor,
+  withExcalidrawDimensions,
+} from "../../tests/test-utils";
+
+describe("Sidebar", () => {
+  it("should render custom sidebar", async () => {
+    const { container } = await render(
+      <Excalidraw
+        initialData={{ appState: { openSidebar: "customSidebar" } }}
+        renderSidebar={() => (
+          <Sidebar>
+            <div id="test-sidebar-content">42</div>
+          </Sidebar>
+        )}
+      />,
+    );
+
+    const node = container.querySelector("#test-sidebar-content");
+    expect(node).not.toBe(null);
+  });
+
+  it("should render custom sidebar header", async () => {
+    const { container } = await render(
+      <Excalidraw
+        initialData={{ appState: { openSidebar: "customSidebar" } }}
+        renderSidebar={() => (
+          <Sidebar>
+            <Sidebar.Header>
+              <div id="test-sidebar-header-content">42</div>
+            </Sidebar.Header>
+          </Sidebar>
+        )}
+      />,
+    );
+
+    const node = container.querySelector("#test-sidebar-header-content");
+    expect(node).not.toBe(null);
+    // make sure we don't render the default fallback header,
+    // just the custom one
+    expect(queryAllByTestId(container, "sidebar-header").length).toBe(1);
+  });
+
+  it("should render only one sidebar and prefer the custom one", async () => {
+    const { container } = await render(
+      <Excalidraw
+        initialData={{ appState: { openSidebar: "customSidebar" } }}
+        renderSidebar={() => (
+          <Sidebar>
+            <div id="test-sidebar-content">42</div>
+          </Sidebar>
+        )}
+      />,
+    );
+
+    await waitFor(() => {
+      // make sure the custom sidebar is rendered
+      const node = container.querySelector("#test-sidebar-content");
+      expect(node).not.toBe(null);
+
+      // make sure only one sidebar is rendered
+      const sidebars = container.querySelectorAll(".layer-ui__sidebar");
+      expect(sidebars.length).toBe(1);
+    });
+  });
+
+  it("should always render custom sidebar with close button & close on click", async () => {
+    const onClose = jest.fn();
+    const CustomExcalidraw = () => {
+      return (
+        <Excalidraw
+          initialData={{ appState: { openSidebar: "customSidebar" } }}
+          renderSidebar={() => (
+            <Sidebar className="test-sidebar" onClose={onClose}>
+              hello
+            </Sidebar>
+          )}
+        />
+      );
+    };
+
+    const { container } = await render(<CustomExcalidraw />);
+
+    const sidebar = container.querySelector<HTMLElement>(".test-sidebar");
+    expect(sidebar).not.toBe(null);
+    const closeButton = queryByTestId(sidebar!, "sidebar-close");
+    expect(closeButton).not.toBe(null);
+
+    fireEvent.click(closeButton!.querySelector("button")!);
+    await waitFor(() => {
+      expect(container.querySelector<HTMLElement>(".test-sidebar")).toBe(null);
+      expect(onClose).toHaveBeenCalled();
+    });
+  });
+
+  it("should render custom sidebar with dock (irrespective of onDock prop)", async () => {
+    const CustomExcalidraw = () => {
+      return (
+        <Excalidraw
+          initialData={{ appState: { openSidebar: "customSidebar" } }}
+          renderSidebar={() => (
+            <Sidebar className="test-sidebar">hello</Sidebar>
+          )}
+        />
+      );
+    };
+
+    const { container } = await render(<CustomExcalidraw />);
+
+    // should show dock button when the sidebar fits to be docked
+    // -------------------------------------------------------------------------
+
+    await withExcalidrawDimensions({ width: 1920, height: 1080 }, () => {
+      const sidebar = container.querySelector<HTMLElement>(".test-sidebar");
+      expect(sidebar).not.toBe(null);
+      const closeButton = queryByTestId(sidebar!, "sidebar-dock");
+      expect(closeButton).not.toBe(null);
+    });
+
+    // should not show dock button when the sidebar does not fit to be docked
+    // -------------------------------------------------------------------------
+
+    await withExcalidrawDimensions({ width: 400, height: 1080 }, () => {
+      const sidebar = container.querySelector<HTMLElement>(".test-sidebar");
+      expect(sidebar).not.toBe(null);
+      const closeButton = queryByTestId(sidebar!, "sidebar-dock");
+      expect(closeButton).toBe(null);
+    });
+  });
+
+  it("should support controlled docking", async () => {
+    let _setDockable: (dockable: boolean) => void = null!;
+
+    const CustomExcalidraw = () => {
+      const [dockable, setDockable] = React.useState(false);
+      _setDockable = setDockable;
+      return (
+        <Excalidraw
+          initialData={{ appState: { openSidebar: "customSidebar" } }}
+          renderSidebar={() => (
+            <Sidebar
+              className="test-sidebar"
+              docked={false}
+              dockable={dockable}
+            >
+              hello
+            </Sidebar>
+          )}
+        />
+      );
+    };
+
+    const { container } = await render(<CustomExcalidraw />);
+
+    await withExcalidrawDimensions({ width: 1920, height: 1080 }, async () => {
+      // should not show dock button when `dockable` is `false`
+      // -------------------------------------------------------------------------
+
+      act(() => {
+        _setDockable(false);
+      });
+
+      await waitFor(() => {
+        const sidebar = container.querySelector<HTMLElement>(".test-sidebar");
+        expect(sidebar).not.toBe(null);
+        const closeButton = queryByTestId(sidebar!, "sidebar-dock");
+        expect(closeButton).toBe(null);
+      });
+
+      // should show dock button when `dockable` is `true`, even if `docked`
+      // prop is set
+      // -------------------------------------------------------------------------
+
+      act(() => {
+        _setDockable(true);
+      });
+
+      await waitFor(() => {
+        const sidebar = container.querySelector<HTMLElement>(".test-sidebar");
+        expect(sidebar).not.toBe(null);
+        const closeButton = queryByTestId(sidebar!, "sidebar-dock");
+        expect(closeButton).not.toBe(null);
+      });
+    });
+  });
+
+  it("should support controlled docking", async () => {
+    let _setDocked: (docked?: boolean) => void = null!;
+
+    const CustomExcalidraw = () => {
+      const [docked, setDocked] = React.useState<boolean | undefined>();
+      _setDocked = setDocked;
+      return (
+        <Excalidraw
+          initialData={{ appState: { openSidebar: "customSidebar" } }}
+          renderSidebar={() => (
+            <Sidebar className="test-sidebar" docked={docked}>
+              hello
+            </Sidebar>
+          )}
+        />
+      );
+    };
+
+    const { container } = await render(<CustomExcalidraw />);
+
+    const { h } = window;
+
+    await withExcalidrawDimensions({ width: 1920, height: 1080 }, async () => {
+      const dockButton = await waitFor(() => {
+        const sidebar = container.querySelector<HTMLElement>(".test-sidebar");
+        expect(sidebar).not.toBe(null);
+        const dockBotton = queryByTestId(sidebar!, "sidebar-dock");
+        expect(dockBotton).not.toBe(null);
+        return dockBotton!;
+      });
+
+      const dockButtonInput = dockButton.querySelector("input")!;
+
+      // should not show dock button when `dockable` is `false`
+      // -------------------------------------------------------------------------
+
+      expect(h.state.isSidebarDocked).toBe(false);
+
+      fireEvent.click(dockButtonInput);
+      await waitFor(() => {
+        expect(h.state.isSidebarDocked).toBe(true);
+        expect(dockButtonInput).toBeChecked();
+      });
+
+      fireEvent.click(dockButtonInput);
+      await waitFor(() => {
+        expect(h.state.isSidebarDocked).toBe(false);
+        expect(dockButtonInput).not.toBeChecked();
+      });
+
+      // shouldn't update `appState.isSidebarDocked` when the sidebar
+      // is controlled (`docked` prop is set), as host apps should handle
+      // the state themselves
+      // -------------------------------------------------------------------------
+
+      act(() => {
+        _setDocked(true);
+      });
+
+      await waitFor(() => {
+        expect(dockButtonInput).toBeChecked();
+        expect(h.state.isSidebarDocked).toBe(false);
+        expect(dockButtonInput).toBeChecked();
+      });
+
+      fireEvent.click(dockButtonInput);
+      await waitFor(() => {
+        expect(h.state.isSidebarDocked).toBe(false);
+        expect(dockButtonInput).toBeChecked();
+      });
+
+      // the `appState.isSidebarDocked` should remain untouched when
+      // `props.docked` is set to `false`, and user toggles
+      // -------------------------------------------------------------------------
+
+      act(() => {
+        _setDocked(false);
+        h.setState({ isSidebarDocked: true });
+      });
+
+      await waitFor(() => {
+        expect(h.state.isSidebarDocked).toBe(true);
+        expect(dockButtonInput).not.toBeChecked();
+      });
+
+      fireEvent.click(dockButtonInput);
+      await waitFor(() => {
+        expect(dockButtonInput).not.toBeChecked();
+        expect(h.state.isSidebarDocked).toBe(true);
+      });
+    });
+  });
+
+  it("should toggle sidebar using props.toggleMenu()", async () => {
+    const { container } = await render(
+      <Excalidraw
+        renderSidebar={() => (
+          <Sidebar>
+            <div id="test-sidebar-content">42</div>
+          </Sidebar>
+        )}
+      />,
+    );
+
+    // sidebar isn't rendered initially
+    // -------------------------------------------------------------------------
+    await waitFor(() => {
+      const node = container.querySelector("#test-sidebar-content");
+      expect(node).toBe(null);
+    });
+
+    // toggle sidebar on
+    // -------------------------------------------------------------------------
+    expect(window.h.app.toggleMenu("customSidebar")).toBe(true);
+
+    await waitFor(() => {
+      const node = container.querySelector("#test-sidebar-content");
+      expect(node).not.toBe(null);
+    });
+
+    // toggle sidebar off
+    // -------------------------------------------------------------------------
+    expect(window.h.app.toggleMenu("customSidebar")).toBe(false);
+
+    await waitFor(() => {
+      const node = container.querySelector("#test-sidebar-content");
+      expect(node).toBe(null);
+    });
+
+    // force-toggle sidebar off (=> still hidden)
+    // -------------------------------------------------------------------------
+    expect(window.h.app.toggleMenu("customSidebar", false)).toBe(false);
+
+    await waitFor(() => {
+      const node = container.querySelector("#test-sidebar-content");
+      expect(node).toBe(null);
+    });
+
+    // force-toggle sidebar on
+    // -------------------------------------------------------------------------
+    expect(window.h.app.toggleMenu("customSidebar", true)).toBe(true);
+    expect(window.h.app.toggleMenu("customSidebar", true)).toBe(true);
+
+    await waitFor(() => {
+      const node = container.querySelector("#test-sidebar-content");
+      expect(node).not.toBe(null);
+    });
+
+    // toggle library (= hide custom sidebar)
+    // -------------------------------------------------------------------------
+    expect(window.h.app.toggleMenu("library")).toBe(true);
+
+    await waitFor(() => {
+      const node = container.querySelector("#test-sidebar-content");
+      expect(node).toBe(null);
+
+      // make sure only one sidebar is rendered
+      const sidebars = container.querySelectorAll(".layer-ui__sidebar");
+      expect(sidebars.length).toBe(1);
+    });
+  });
+});

src/components/Sidebar/Sidebar.tsx

@@ -0,0 +1,121 @@
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { Island } from ".././Island";
+import { atom, useAtom } from "jotai";
+import { jotaiScope } from "../../jotai";
+import {
+  SidebarPropsContext,
+  SidebarProps,
+  SidebarPropsContextValue,
+} from "./common";
+
+import { SidebarHeaderComponents } from "./SidebarHeader";
+
+import "./Sidebar.scss";
+import clsx from "clsx";
+import { useExcalidrawSetAppState } from "../App";
+import { updateObject } from "../../utils";
+
+/** using a counter instead of boolean to handle race conditions where
+ * the host app may render (mount/unmount) multiple different sidebar */
+export const hostSidebarCountersAtom = atom({ rendered: 0, docked: 0 });
+
+export const Sidebar = ({
+  children,
+  onClose,
+  onDock,
+  docked,
+  dockable = true,
+  className,
+  __isInternal,
+}: SidebarProps<{
+  // NOTE sidebars we use internally inside the editor must have this flag set.
+  // It indicates that this sidebar should have lower precedence over host
+  // sidebars, if both are open.
+  /** @private internal */
+  __isInternal?: boolean;
+}>) => {
+  const [hostSidebarCounters, setHostSidebarCounters] = useAtom(
+    hostSidebarCountersAtom,
+    jotaiScope,
+  );
+
+  const setAppState = useExcalidrawSetAppState();
+
+  const [isDockedFallback, setIsDockedFallback] = useState(docked ?? false);
+
+  useLayoutEffect(() => {
+    if (docked === undefined) {
+      // ugly hack to get initial state out of AppState without susbcribing
+      // to it as a whole (once we have granular subscriptions, we'll move
+      // to that)
+      //
+      // NOTE this means that is updated `state.isSidebarDocked` changes outside
+      // of this compoent, it won't be reflected here. Currently doesn't happen.
+      setAppState((state) => {
+        setIsDockedFallback(state.isSidebarDocked);
+        // bail from update
+        return null;
+      });
+    }
+  }, [setAppState, docked]);
+
+  useLayoutEffect(() => {
+    if (!__isInternal) {
+      setHostSidebarCounters((s) => ({
+        rendered: s.rendered + 1,
+        docked: isDockedFallback ? s.docked + 1 : s.docked,
+      }));
+      return () => {
+        setHostSidebarCounters((s) => ({
+          rendered: s.rendered - 1,
+          docked: isDockedFallback ? s.docked - 1 : s.docked,
+        }));
+      };
+    }
+  }, [__isInternal, setHostSidebarCounters, isDockedFallback]);
+
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+
+  useEffect(() => {
+    return () => {
+      onCloseRef.current?.();
+    };
+  }, []);
+
+  const headerPropsRef = useRef<SidebarPropsContextValue>({});
+  headerPropsRef.current.onClose = () => {
+    setAppState({ openSidebar: null });
+  };
+  headerPropsRef.current.onDock = (isDocked) => {
+    if (docked === undefined) {
+      setAppState({ isSidebarDocked: isDocked });
+      setIsDockedFallback(isDocked);
+    }
+    onDock?.(isDocked);
+  };
+  // renew the ref object if the following props change since we want to
+  // rerender. We can't pass down as component props manually because
+  // the <Sidebar.Header/> can be rendered upsream.
+  headerPropsRef.current = updateObject(headerPropsRef.current, {
+    docked: docked ?? isDockedFallback,
+    dockable,
+  });
+
+  if (hostSidebarCounters.rendered > 0 && __isInternal) {
+    return null;
+  }
+
+  return (
+    <Island padding={2} className={clsx("layer-ui__sidebar", className)}>
+      <SidebarPropsContext.Provider value={headerPropsRef.current}>
+        <SidebarHeaderComponents.Context>
+          <SidebarHeaderComponents.Component __isFallback />
+          {children}
+        </SidebarHeaderComponents.Context>
+      </SidebarPropsContext.Provider>
+    </Island>
+  );
+};
+
+Sidebar.Header = SidebarHeaderComponents.Component;

src/components/Sidebar/SidebarHeader.tsx

@@ -0,0 +1,95 @@
+import clsx from "clsx";
+import { useContext } from "react";
+import { t } from "../../i18n";
+import { useDevice } from "../App";
+import { SidebarPropsContext } from "./common";
+import { close } from "../icons";
+import { withUpstreamOverride } from "../hoc/withUpstreamOverride";
+import { Tooltip } from "../Tooltip";
+
+const SIDE_LIBRARY_TOGGLE_ICON = (
+  <svg viewBox="0 0 24 24" fill="#ffffff">
+    <path d="M19 22H5a3 3 0 01-3-3V5a3 3 0 013-3h14a3 3 0 013 3v14a3 3 0 01-3 3zm0-18h-9v16h9a1.01 1.01 0 001-1V5a1.01 1.01 0 00-1-1z"></path>
+  </svg>
+);
+
+export const SidebarDockButton = (props: {
+  checked: boolean;
+  onChange?(): void;
+}) => {
+  return (
+    <div className="layer-ui__sidebar-dock-button" data-testid="sidebar-dock">
+      <Tooltip label={t("labels.sidebarLock")}>
+        <label
+          className={clsx(
+            "ToolIcon ToolIcon__lock ToolIcon_type_floating",
+            `ToolIcon_size_medium`,
+          )}
+        >
+          <input
+            className="ToolIcon_type_checkbox"
+            type="checkbox"
+            onChange={props.onChange}
+            checked={props.checked}
+            aria-label={t("labels.sidebarLock")}
+          />{" "}
+          <div className="ToolIcon__icon" tabIndex={0}>
+            {SIDE_LIBRARY_TOGGLE_ICON}
+          </div>{" "}
+        </label>{" "}
+      </Tooltip>
+    </div>
+  );
+};
+
+const _SidebarHeader: React.FC<{
+  children?: React.ReactNode;
+  className?: string;
+}> = ({ children, className }) => {
+  const device = useDevice();
+  const props = useContext(SidebarPropsContext);
+
+  const renderDockButton = !!(device.canDeviceFitSidebar && props.dockable);
+  const renderCloseButton = !!props.onClose;
+
+  return (
+    <div
+      className={clsx("layer-ui__sidebar__header", className)}
+      data-testid="sidebar-header"
+    >
+      {children}
+      {(renderDockButton || renderCloseButton) && (
+        <div className="layer-ui__sidebar__header__buttons">
+          {renderDockButton && (
+            <SidebarDockButton
+              checked={!!props.docked}
+              onChange={() => {
+                document
+                  .querySelector(".layer-ui__wrapper")
+                  ?.classList.add("animate");
+
+                props.onDock?.(!props.docked);
+              }}
+            />
+          )}
+          {renderCloseButton && (
+            <div className="ToolIcon__icon__close" data-testid="sidebar-close">
+              <button
+                className="Modal__close"
+                onClick={props.onClose}
+                aria-label={t("buttons.close")}
+              >
+                {close}
+              </button>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
+const [Context, Component] = withUpstreamOverride(_SidebarHeader);
+
+/** @private */
+export const SidebarHeaderComponents = { Context, Component };

src/components/Sidebar/common.ts

@@ -0,0 +1,22 @@
+import React from "react";
+
+export type SidebarProps<P = {}> = {
+  children: React.ReactNode;
+  /**
+   * Called on sidebar close (either by user action or by the editor).
+   */
+  onClose?: () => void | boolean;
+  /** if not supplied, sidebar won't be dockable */
+  onDock?: (docked: boolean) => void;
+  docked?: boolean;
+  dockable?: boolean;
+  className?: string;
+} & P;
+
+export type SidebarPropsContextValue = Pick<
+  SidebarProps,
+  "onClose" | "onDock" | "docked" | "dockable"
+>;
+
+export const SidebarPropsContext =
+  React.createContext<SidebarPropsContextValue>({});