@linzjs/windows 1.0.0 → 1.1.0

package/src/panel/Panel.tsx

@@ -0,0 +1,150 @@
+import "./Panel.scss";
+import "@linzjs/lui/dist/scss/base.scss";
+
+import { PanelContext } from "./PanelContext";
+import { PanelInstanceContext, PanelSize } from "./PanelInstanceContext";
+import { PanelPosition, PanelsContext } from "./PanelsContext";
+import { PopoutWindow } from "./PopoutWindow";
+import { ReactElement, ReactNode, useContext, useEffect, useState } from "react";
+import { Rnd } from "react-rnd";
+
+import { LuiButton, LuiIcon } from "@linzjs/lui";
+import { LuiIconName } from "@linzjs/lui/dist/assets/svg-content";
+
+export interface PanelProps {
+  title: string;
+  position?: PanelPosition;
+  size?: PanelSize;
+  children: ReactNode;
+}
+
+export const Panel = ({ title, position, size = { width: 320, height: 200 }, children }: PanelProps): ReactElement => {
+  const { nextStackPosition } = useContext(PanelsContext);
+  const { panelPoppedOut, bounds, zIndex, bringPanelToFront, uniqueId, setTitle } = useContext(PanelInstanceContext);
+
+  const [panelPosition, setPanelPosition] = useState(() => position ?? nextStackPosition());
+  const [panelSize, setPanelSize] = useState(size ?? { width: 320, height: 200 });
+
+  const resizePanel = (newPanelSize: Partial<PanelSize>) => {
+    if (panelPoppedOut) return;
+    const newSize = { ...panelSize, ...newPanelSize };
+    if (newSize.width !== panelSize.width || newSize.height !== panelSize.height) {
+      setPanelSize(newSize);
+    }
+  };
+
+  useEffect(() => {
+    setTitle(title);
+  }, [setTitle, title]);
+
+  //panelClose
+  return (
+    <PanelContext.Provider value={{ resizePanel }}>
+      {panelPoppedOut ? (
+        <PopoutWindow name={uniqueId} title={title} size={panelSize}>
+          <div
+            style={{
+              display: "flex",
+              flexDirection: "column",
+              width: "100%",
+              height: "100%",
+            }}
+          >
+            {children}
+          </div>
+        </PopoutWindow>
+      ) : (
+        <Rnd
+          className={"WindowPanel"}
+          dragHandleClassName={"draggable-handle"}
+          minWidth={100}
+          minHeight={100}
+          position={panelPosition}
+          size={panelSize}
+          style={{ zIndex }}
+          bounds={bounds ?? document.body}
+          onDragStop={(_evt, data) => {
+            setPanelPosition({ x: data.x, y: data.y });
+          }}
+          onResizeStop={(_evt, _dir, ref, _delta, position) => {
+            setPanelPosition(position);
+            setPanelSize({
+              width: parseInt(ref.style.width),
+              height: parseInt(ref.style.height),
+            });
+          }}
+          onMouseDown={bringPanelToFront}
+        >
+          <div
+            style={{
+              display: "flex",
+              flexDirection: "column",
+              width: "100%",
+              height: "100%",
+            }}
+          >
+            {children}
+          </div>
+        </Rnd>
+      )}
+    </PanelContext.Provider>
+  );
+};
+
+export interface PanelHeaderButtonProps {
+  "aria-label": string;
+  icon: LuiIconName;
+  onClick: () => void;
+}
+
+export const PanelHeaderButton = ({ "aria-label": ariaLabel, icon, onClick }: PanelHeaderButtonProps) => (
+  <LuiButton
+    level={"plain-text"}
+    className={"lui-button-icon-only"}
+    size={"sm"}
+    onClick={onClick}
+    buttonProps={{
+      onTouchStart: onClick,
+    }}
+  >
+    <LuiIcon name={icon} alt={ariaLabel} />
+  </LuiButton>
+);
+
+export interface PanelHeaderProps {
+  extraButtons?: ReactNode;
+}
+
+export const PanelHeader = ({ extraButtons }: PanelHeaderProps) => {
+  const { panelClose, panelTogglePopout, panelPoppedOut, title } = useContext(PanelInstanceContext);
+  const [cursor, setCursor] = useState<"grab" | "grabbing">("grab");
+
+  const headerMouseDown = () => {
+    !panelPoppedOut && setCursor("grabbing");
+  };
+
+  return (
+    <div
+      className={"WindowPanel-header draggable-handle"}
+      onMouseDown={headerMouseDown}
+      onMouseUp={() => !panelPoppedOut && setCursor("grab")}
+      style={{ cursor }}
+    >
+      <div className={"WindowPanel-header-title"}>{title}</div>
+      <div className={"LuiFloatingWindow-buttons"}>{extraButtons}</div>
+      <div className={"LuiFloatingWindow-extra-buttons-divider"}>|</div>
+      <div className={"LuiFloatingWindow-buttons"}>
+        <PanelHeaderButton
+          aria-label={panelPoppedOut ? "Pop-in" : "Pop-out"}
+          onClick={panelTogglePopout}
+          icon={panelPoppedOut ? "ic_pop_back" : "ic_launch_new window_open"}
+        />
+        <PanelHeaderButton aria-label={"Close"} onClick={panelClose} icon={"ic_clear"} />
+      </div>
+    </div>
+  );
+};
+
+export const PanelContent = ({ children }: { children: ReactNode }) => {
+  return <div className={"WindowPanel-content"}>{children}</div>;
+};

package/src/panel/PanelContext.ts

@@ -0,0 +1,17 @@
+import { PanelSize } from "./PanelInstanceContext";
+import { createContext } from "react";
+
+export interface PanelContextType {
+  resizePanel: (size: Partial<PanelSize>) => void;
+}
+
+const NoContextError = () => {
+  console.error("Missing PanelContext Provider");
+};
+
+/**
+ * Provides access to closing/popping panels
+ */
+export const PanelContext = createContext<PanelContextType>({
+  resizePanel: NoContextError,
+});

package/src/panel/PanelInstanceContext.ts

@@ -0,0 +1,41 @@
+import { createContext } from "react";
+
+export interface PanelSize {
+  width: number;
+  height: number;
+}
+
+export interface PanelInstanceContextType {
+  title: string;
+  setTitle: (title: string) => void;
+  uniqueId: string;
+  panelName: string;
+  bounds: string | Element | undefined;
+  panelTogglePopout: () => void;
+  panelClose: () => void;
+  setPanelWindow: (w: Window) => void;
+  bringPanelToFront: () => void;
+  panelPoppedOut: boolean;
+  zIndex: number;
+}
+
+const NoContextError = () => {
+  console.error("Missing PanelInstanceContext Provider");
+};
+
+/**
+ * Provides access to closing/popping panels
+ */
+export const PanelInstanceContext = createContext<PanelInstanceContextType>({
+  title: "Missing PanelInstanceContext Provider: title",
+  uniqueId: "Missing PanelInstanceContext Provider: uniqueId",
+  panelName: "Missing PanelInstanceContext Provider: panelName",
+  bounds: document.body,
+  setTitle: NoContextError,
+  panelTogglePopout: NoContextError,
+  panelClose: NoContextError,
+  setPanelWindow: NoContextError,
+  bringPanelToFront: NoContextError,
+  panelPoppedOut: false,
+  zIndex: 0,
+});

package/src/panel/PanelInstanceContextProvider.tsx

@@ -0,0 +1,47 @@
+import { PanelInstanceContext } from "./PanelInstanceContext";
+import { PanelInstance, PanelsContext } from "./PanelsContext";
+import { ReactElement, ReactNode, useContext, useState } from "react";
+
+/**
+ * Provides access to closing/popping panels
+ */
+export const PanelInstanceContextProvider = ({
+  panelInstance,
+  bounds,
+  children,
+}: {
+  bounds: string | Element | undefined;
+  panelInstance: PanelInstance;
+  children: ReactNode;
+}): ReactElement => {
+  const { closePanel, togglePopOut, bringPanelToFront } = useContext(PanelsContext);
+  const [title, setTitle] = useState("");
+
+  return (
+    <PanelInstanceContext.Provider
+      value={{
+        title,
+        setTitle,
+        uniqueId: panelInstance.uniqueId,
+        bounds,
+        panelName: panelInstance.uniqueId,
+        panelClose: () => {
+          panelInstance.window?.close();
+          panelInstance.window = null;
+          closePanel(panelInstance);
+        },
+        panelTogglePopout: () => {
+          togglePopOut(panelInstance);
+        },
+        panelPoppedOut: panelInstance.poppedOut,
+        setPanelWindow: (w: Window) => {
+          panelInstance.window = w;
+        },
+        bringPanelToFront: () => bringPanelToFront(panelInstance),
+        zIndex: panelInstance.zIndex,
+      }}
+    >
+      {children}
+    </PanelInstanceContext.Provider>
+  );
+};

package/src/panel/PanelsContext.tsx

@@ -0,0 +1,36 @@
+import { ReactElement, createContext } from "react";
+
+export interface PanelPosition {
+  x: number;
+  y: number;
+}
+
+export interface PanelInstance {
+  uniqueId: string;
+  componentInstance: ReactElement;
+  zIndex: number;
+  poppedOut: boolean;
+  window: Window | null;
+}
+
+export interface PanelsContextType {
+  openPanels: Set<string>;
+  openPanel: (uniqueId: string, component: () => ReactElement) => void;
+  closePanel: (panelInstance: PanelInstance) => void;
+  togglePopOut: (panelInstance: PanelInstance) => void;
+  bringPanelToFront: (panelInstance: PanelInstance) => void;
+  nextStackPosition: () => PanelPosition;
+}
+
+const NoContext = () => {
+  console.error("Missing PanelContext Provider");
+};
+
+export const PanelsContext = createContext<PanelsContextType>({
+  openPanels: new Set(),
+  openPanel: NoContext,
+  closePanel: NoContext,
+  togglePopOut: NoContext,
+  bringPanelToFront: NoContext,
+  nextStackPosition: () => ({ x: 0, y: 0 }),
+});

package/src/panel/PanelsContextProvider.tsx

@@ -0,0 +1,140 @@
+import { useInterval } from "../util/useInterval";
+import { PanelInstanceContextProvider } from "./PanelInstanceContextProvider";
+import { PanelInstance, PanelPosition, PanelsContext } from "./PanelsContext";
+import { castArray, maxBy, sortBy } from "lodash-es";
+import { Fragment, PropsWithChildren, ReactElement, useCallback, useMemo, useRef, useState } from "react";
+
+export interface PanelsContextProviderProps {
+  baseZIndex?: number;
+  bounds?: string | Element;
+  tilingStart?: PanelPosition;
+  tilingOffset?: PanelPosition;
+  tilingMax?: PanelPosition;
+}
+
+export const PanelsContextProvider = ({
+  bounds,
+  baseZIndex = 500,
+  children,
+  tilingStart = { x: 30, y: 30 },
+  tilingOffset = { x: 30, y: 50 },
+  tilingMax = { x: 200, y: 300 },
+}: PropsWithChildren<PanelsContextProviderProps>): ReactElement => {
+  const stackPositionRef = useRef(tilingStart);
+
+  // Can't use a map here as we need to retain render order for performance
+  const [panelInstances, setPanelInstances] = useState<PanelInstance[]>([]);
+
+  const bringPanelToFront = useCallback(
+    (panelInstance: PanelInstance) => {
+      if (panelInstance.window) {
+        panelInstance.window.focus();
+      } else {
+        const maxZIndexPanelInstance = maxBy(panelInstances, "zIndex");
+        // Prevent unnecessary state updates
+        if (maxZIndexPanelInstance === panelInstance) return;
+        sortBy(panelInstances, (pi) => (panelInstance === pi ? 32768 : pi.zIndex)).forEach(
+          (pi, i) => (pi.zIndex = baseZIndex + i),
+        );
+        setPanelInstances([...panelInstances]);
+      }
+    },
+    [baseZIndex, panelInstances],
+  );
+
+  const openPanel = useCallback(
+    (uniqueId: string, componentFn: () => ReactElement): void => {
+      try {
+        const existingPanelInstance = panelInstances.find((pi) => pi.uniqueId === uniqueId);
+        if (existingPanelInstance) {
+          if (existingPanelInstance.window) {
+            existingPanelInstance.window?.focus();
+          } else {
+            bringPanelToFront(existingPanelInstance);
+          }
+          return;
+        }
+
+        // If there are any exceptions the modal won't show
+        setPanelInstances([
+          ...panelInstances,
+          {
+            uniqueId,
+            componentInstance: componentFn(),
+            zIndex: baseZIndex + panelInstances.length,
+            poppedOut: false,
+            window: null,
+          },
+        ]);
+      } catch (e) {
+        console.error(e);
+      }
+    },
+    [baseZIndex, bringPanelToFront, panelInstances],
+  );
+
+  const closePanel = useCallback(
+    (panelInstance: PanelInstance | PanelInstance[]) => {
+      const panelNames = castArray(panelInstance).map((pi) => pi.uniqueId);
+      const newPanelInstances = panelInstances.filter((pi) => !panelNames.includes(pi.uniqueId));
+      if (panelInstances.length !== newPanelInstances.length) setPanelInstances(newPanelInstances);
+    },
+    [panelInstances],
+  );
+
+  const togglePopOut = useCallback(
+    (panelInstance: PanelInstance) => {
+      panelInstance.poppedOut = !panelInstance.poppedOut;
+      if (!panelInstance.poppedOut) {
+        panelInstance.window = null;
+      }
+      setPanelInstances([...panelInstances]);
+    },
+    [panelInstances],
+  );
+
+  /**
+   * It's not easy to tell the difference between a window closing and a window popping in via events,
+   * so we're periodically checking instead.
+   */
+  useInterval(() => {
+    // close any panels that have a window that is closed
+    closePanel(panelInstances.filter((pi) => pi.window?.closed));
+  }, 500);
+
+  /**
+   * Tile the panel position relative to previous panel
+   */
+  const nextStackPosition = useCallback(() => {
+    const p = { ...stackPositionRef.current };
+    const result = { ...p };
+    p.x += tilingOffset.x;
+    p.y += tilingOffset.y;
+    stackPositionRef.current = p.x > tilingMax.x || p.y > tilingMax.y ? tilingStart : p;
+    return result;
+  }, [tilingMax.x, tilingMax.y, tilingOffset.x, tilingOffset.y, tilingStart]);
+
+  const openPanels = useMemo(() => new Set(panelInstances.map((pi) => pi.uniqueId)), [panelInstances]);
+
+  return (
+    <PanelsContext.Provider
+      value={{
+        openPanels,
+        openPanel,
+        closePanel,
+        togglePopOut,
+        bringPanelToFront,
+        nextStackPosition,
+      }}
+    >
+      <Fragment key={"panels"}>
+        {panelInstances.map((panelInstance) => (
+          <PanelInstanceContextProvider key={panelInstance.uniqueId} panelInstance={panelInstance} bounds={bounds}>
+            {panelInstance.componentInstance}
+          </PanelInstanceContextProvider>
+        ))}
+      </Fragment>
+      <Fragment key={"children"}>{children}</Fragment>
+    </PanelsContext.Provider>
+  );
+};

package/src/panel/PopoutWindow.tsx

@@ -0,0 +1,183 @@
+import { PanelInstanceContext } from "./PanelInstanceContext";
+import { makePopoutId, popoutWindowDivId } from "./generateId";
+import { copyStyleSheets, observeStyleSheetChanges } from "./handleStyleSheetsChanges";
+import createCache from "@emotion/cache";
+import { CacheProvider } from "@emotion/react";
+import { Dispatch, ReactElement, ReactNode, SetStateAction, useContext, useEffect, useRef, useState } from "react";
+import ReactDOM from "react-dom";
+
+export type FloatingWindowSize = { height: number; width: number };
+
+interface PopoutWindowProps {
+  name: string;
+  title?: string; // The title of the popout window
+  children: ReactNode; // what to render inside the window
+  size: FloatingWindowSize;
+
+  //says if we want to watch for any dynamic style changes
+  //only needed when using UI libraries like MUI
+  observeStyleChanges?: boolean;
+
+  /** Testing seam to avoid extensively mocking the window object. */
+  openExternalWindowFn?: () => OpenExternalWindowResponse;
+  className?: string;
+}
+
+type OpenExternalWindowResponse = {
+  externalWindow: Window | null;
+  onCloseExternalWindow: (() => void) | null;
+};
+
+/**
+ * Open and scaffold the new external window.
+ *
+ * The main motivation for extracting these procedures into a function is for testing ease. JSDOM does not mock out the
+ * entire window object, making the PopoutWindow component difficult to unit test without extensive mocking. Instead, we
+ * can avoid mocking most of the window methods entirely by conditionally calling an alternative to `openExternalWindow`
+ * during unit testing by providing a truthy `openExternalWindowFn` prop.
+ */
+const openExternalWindow = ({
+  title,
+  size,
+  setContainerElement,
+  setHeadElement,
+  observeStyleChanges = false,
+  className,
+}: {
+  title: string;
+  size: { width: number; height: number };
+  setContainerElement: Dispatch<SetStateAction<HTMLElement | undefined>>;
+  setHeadElement: Dispatch<SetStateAction<HTMLElement | undefined>>;
+  observeStyleChanges?: boolean;
+  className?: string;
+}): OpenExternalWindowResponse => {
+  const response: OpenExternalWindowResponse = { externalWindow: null, onCloseExternalWindow: null };
+
+  // NOTE:
+  // 1/ Edge ignores the left and top settings
+  // 2/ Chrome has a bug that screws up the window size by a factor dependent on your windows scaling settings
+  // if you open the browser in a window with a scaling and drag it to a window with a different scaling
+  const features =
+    `scrollbars=no,resizable=no,status=no,location=no,toolbar=no,menubar=no,` +
+    `width=${size.width},height=${size.height},left=300,top=200`;
+  response.externalWindow = window.open("", makePopoutId(title), features);
+
+  if (response.externalWindow) {
+    const { externalWindow } = response;
+
+    // Reset the default body style applied by the browser
+    externalWindow.document.body.style.margin = "0";
+    externalWindow.document.body.style.padding = "0";
+
+    // Remove any existing body HTML from this window
+    const existingBodyMountElement = externalWindow.document.body?.firstChild;
+    if (existingBodyMountElement) {
+      externalWindow.document.body.removeChild(existingBodyMountElement);
+    }
+    // Create a new HTML element to hang our rendering off
+    const newMountElement = externalWindow.document.createElement("div");
+    newMountElement.className = `PopoutWindowContainer ${className}`;
+    setContainerElement(newMountElement);
+    externalWindow.document.body.appendChild(newMountElement);
+
+    // Do the same for the head node (where all the styles are added)
+    const existingHeadMountElement = externalWindow.document.head?.firstChild;
+    if (existingHeadMountElement) {
+      externalWindow.document.head.removeChild(existingHeadMountElement);
+    }
+    // and an HTML element to hang our copied styles off
+    const newHeadMountElement = externalWindow.document.createElement("div");
+    externalWindow.document.head.appendChild(newHeadMountElement);
+    setHeadElement(newHeadMountElement);
+
+    // Set External window title
+    externalWindow.document.title = title;
+
+    // Set an id to the external window div to be queried and used by react-modal as parentSelector
+    // so the modal shows up in the popped out window instead the main window
+    newMountElement.id = popoutWindowDivId(title);
+
+    copyStyleSheets(newHeadMountElement);
+
+    let observer: MutationObserver | null = null;
+    if (observeStyleChanges) {
+      observer = observeStyleSheetChanges(newHeadMountElement);
+    }
+
+    externalWindow.onbeforeunload = () => observer?.disconnect();
+
+    response.onCloseExternalWindow = () => {
+      // Make sure the window closes when the component unmounts
+      externalWindow.close();
+    };
+  }
+
+  return response;
+};
+
+export const PopoutWindow = ({
+  name,
+  title = name,
+  size,
+  observeStyleChanges,
+  className,
+  openExternalWindowFn,
+  children,
+}: PopoutWindowProps): ReactElement | null => {
+  const { setPanelWindow } = useContext(PanelInstanceContext);
+
+  const extWindow = useRef<Window | null>(null);
+
+  const [containerElement, setContainerElement] = useState<HTMLElement>();
+  const [headElement, setHeadElement] = useState<HTMLElement>();
+
+  // We only want to update the title when it changes
+  useEffect(() => {
+    if (extWindow.current) {
+      extWindow.current.document.title = title;
+    }
+  }, [title]);
+
+  // When we create this component, open a new window
+  useEffect(
+    () => {
+      const oew = openExternalWindowFn ?? openExternalWindow;
+      const { externalWindow, onCloseExternalWindow } = oew({
+        title,
+        size,
+        setContainerElement,
+        setHeadElement,
+        observeStyleChanges,
+        className,
+      });
+
+      if (!externalWindow) return;
+
+      setPanelWindow(externalWindow);
+
+      const closeExternalWindow = () => {
+        externalWindow.close();
+      };
+
+      // When the main window closes or reloads, close the popout
+      window.addEventListener("beforeunload", closeExternalWindow, { once: true });
+
+      return () => {
+        onCloseExternalWindow?.();
+      };
+    },
+    // These deps MUST be empty
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  // Render this component's children into the root element of the popout window
+  // The `@emotion/react/CacheProvider`provides a cache derived from createCache for inline styles
+  // these will be generated into the `container` and prefixed with the `key` below, ensuring
+  // the styles are in the popout rather than the root window.
+  const myCache = createCache({ key: makePopoutId(name), container: headElement });
+
+  const wrappedChildren = <CacheProvider value={myCache}>{children}</CacheProvider>;
+
+  return containerElement ? ReactDOM.createPortal(wrappedChildren, containerElement) : null;
+};

package/src/panel/generateId.ts

@@ -0,0 +1,23 @@
+/**
+ * The only valid characters for an @emotion key are lower case chars or '-'.
+ * We need to replace any char that is not valid with a substitute.
+ */
+export function makePopoutId(str: string): string {
+  return str
+    .replace(/[/\s_]*/g, "-")
+    .replaceAll("0", "zero")
+    .replaceAll("1", "one")
+    .replaceAll("2", "two")
+    .replaceAll("3", "three")
+    .replaceAll("4", "four")
+    .replaceAll("5", "five")
+    .replaceAll("6", "six")
+    .replaceAll("7", "seven")
+    .replaceAll("8", "eight")
+    .replaceAll("9", "nine")
+    .toLowerCase();
+}
+
+export function popoutWindowDivId(windowTitle: string): string {
+  return `popoutWindow-${makePopoutId(windowTitle)}`;
+}