@linzjs/windows 1.0.0 → 1.1.1

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)}`;
+}

package/src/panel/handleStyleSheetsChanges.ts

@@ -0,0 +1,71 @@
+import { throttle } from "lodash-es";
+
+// Copy the app's styles into the new window
+export const copyStyleSheets = (newHeadMountElement: HTMLDivElement) => {
+  const stylesheets = Array.from(document.styleSheets);
+
+  stylesheets.forEach((stylesheet) => {
+    if (stylesheet.href) {
+      const newStyleElement = document.createElement("link");
+      newStyleElement.rel = "stylesheet";
+      newStyleElement.href = stylesheet.href;
+      newHeadMountElement.appendChild(newStyleElement);
+    } else {
+      const css = stylesheet as CSSStyleSheet;
+      if (css && css.cssRules && css.cssRules.length > 0) {
+        const newStyleElement = document.createElement("style");
+        Array.from(css.cssRules).forEach((rule) => {
+          newStyleElement.appendChild(document.createTextNode(rule.cssText));
+        });
+        newHeadMountElement.appendChild(newStyleElement);
+      }
+    }
+  });
+};
+/**
+ * Add listener for dynamic style changes
+ * This works by listening to any changes to the head element
+ * If there are any changes it replaces all the styles in the floating window
+ * at most every 100ms
+ * @param newHeadMountElement
+ */
+export const observeStyleSheetChanges = (newHeadMountElement: HTMLDivElement) => {
+  const targetNode = document.querySelector("head");
+
+  if (!targetNode) {
+    return null;
+  }
+  // Options for the observer (which mutations to observe)
+  const config = { /*attributes: true,*/ childList: true /*, subtree: true */ };
+
+  //throttle the copying of the all the styles at most 100ms
+  const throttleCopyStyleSheets = throttle(() => {
+    copyStyleSheets(newHeadMountElement);
+  }, 100);
+
+  // Callback function to execute when mutations are observed
+  const callback: MutationCallback = function (mutationList) {
+    for (const mutation of mutationList) {
+      if (mutation.type === "childList") {
+        // console.log("A child node has been added or removed.", mutation);
+        //naive way up updating style sheets
+        //the observer tells us what has been added and removed, but syncing the changes with the
+        //floating window is complicated, so the easiest way is to just wait for modifications for finish
+        //updating, then replace them all
+        //we could probably just copy all style on every modification, by that might have a performance hit
+        throttleCopyStyleSheets();
+      } /*else if (mutation.type === "attributes") {
+              //Do we need to handle attribute modifications?
+              // console.log("The " + mutation.attributeName + " attribute was modified.");
+            }*/
+    }
+  };
+
+  // Create an observer instance linked to the callback function
+  const observer = new MutationObserver(callback);
+
+  // Start observing the target node for configured mutations
+  observer.observe(targetNode, config);
+
+  return observer;
+};

package/src/stories/Introduction.mdx

@@ -0,0 +1,18 @@
+# @linzjs/windows
+
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
+
+> Reusable promise based windowing component for LINZ / Toitū te whenua.
+
+Rect state based modals/windows are painful because they require:
+- shared states for open/closed.
+- callbacks/states for return values.
+- inline modal/window includes, which prevent you from closing the invoking component before the modal/window has
+completed.
+
+This module gives you promise based modals/windows which don't require all the state
+based boiler-plate / inline-components.
+
+## Features
+- Async HTML dialog based Modals.
+- Draggable and resizeable, pop-in/out Windows.

package/src/stories/Introduction.stories.tsx

@@ -0,0 +1,8 @@
+import { Meta } from "@storybook/react";
+
+// eslint-disable-next-line storybook/story-exports
+const meta: Meta<typeof Object> = {
+  title: "Introduction",
+};
+
+export default meta;

package/src/stories/modal/Modal.mdx

@@ -1,9 +1,10 @@
+import {getBlocks, blockToString} from "../support.js";
 import {Meta, Source, Story} from "@storybook/blocks";
 import * as ModalStories from "./Modal.stories"
 
 import myModule from './TestModal?raw';
 
-<Meta title="Modal/Primary" of={ModalStories}/>
+<Meta name="Show" of={ModalStories}/>
 # Show Modal
 ## Example
 Click to show the modal:
@@ -11,10 +12,15 @@ Click to show the modal:
 
 ## Code
 <br/>
-{myModule.toString().split("// #").splice(1).map(block => (
+{getBlocks(myModule).map((block) => (
 <>
     <h3>{block.split("\n")[0]}</h3>
-    <Source code={block.split("\n").splice(1).join("\n")} language='typescript'/>
+    <Source code={blockToString(block)} language="typescript"  />
 </>
 ))}
 
+### Example: Mocking Modal response
+
+<Source code={"{ /* Responds with the value 1 */ }\n<ModalContext.Provider value={showModal: async() => 1}>\n" +
+    "... Component under test ...\n" +
+    "</ModalContext.Provider>\n"} language="typescript"/>

package/src/stories/modal/Modal.stories.tsx

@@ -3,7 +3,7 @@ import { TestModalUsage } from "./TestModal";
 import type { Meta, StoryObj } from "@storybook/react";
 
 const meta: Meta<typeof TestModalUsage> = {
-  title: "Modal",
+  title: "Components/Modal",
   component: TestModalUsage,
   argTypes: {
     backgroundColor: { control: "color" },

package/src/stories/modal/PreModal.mdx

@@ -0,0 +1,26 @@
+import {getBlocks, blockToString} from "../support";
+import {Meta, Source, Story} from "@storybook/blocks";
+import * as PreModalStories from "./PreModal.stories"
+
+import myModule from './PreModal?raw';
+
+<Meta name="Show Preset Modal" of={PreModalStories}/>
+# Show Preset Modal
+## Example
+Click to show the modal:
+<Story of={PreModalStories.ShowPreModal}/>
+
+## Code
+<br/>
+{getBlocks(myModule).map((block) => (
+<>
+    <h3>{block.split("\n")[0]}</h3>
+    <Source code={blockToString(block)} language="typescript"  />
+</>
+))}
+
+### Example: Mocking Modal response
+
+<Source code={"{ /* Responds with the value 1 */ }\n<ModalContext.Provider value={showModal: async() => 1}>\n" +
+    "... Component under test ...\n" +
+    "</ModalContext.Provider>\n"} language="typescript"/>

package/src/stories/modal/PreModal.stories.tsx

@@ -0,0 +1,27 @@
+import { ModalContextProvider } from "../../modal/ModalContextProvider";
+import { PreModalUsage } from "./PreModal";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const meta: Meta<typeof PreModalUsage> = {
+  title: "Components/Modal",
+  component: PreModalUsage,
+  argTypes: {
+    backgroundColor: { control: "color" },
+  },
+  decorators: [
+    (Story: any) => (
+      <div>
+        <ModalContextProvider>
+          <Story />
+        </ModalContextProvider>
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const ShowPreModal: Story = {
+  args: {},
+};