react-panel-layout 0.5.2 → 0.6.0

package/src/components/window/PopupLayerPortal.tsx

@@ -0,0 +1,218 @@
+/**
+ * @file Renders floating layers inside a dedicated browser popup window.
+ */
+import * as React from "react";
+import { createPortal } from "react-dom";
+import type { LayerDefinition, PopupWindowOptions, WindowPosition, WindowBounds } from "../../types";
+import { LayerInstanceProvider } from "../../modules/grid/LayerInstanceContext";
+
+const ensureNumericOffset = (value: number | string | undefined, key: keyof WindowPosition, layerId: string): number => {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  throw new Error(`Popup layer "${layerId}" requires a numeric "${key}" value.`);
+};
+
+const resolvePopupAnchor = (position: WindowPosition | undefined, layerId: string): { left: number; top: number } => {
+  if (!position) {
+    throw new Error(`Popup layer "${layerId}" must define position (left/top).`);
+  }
+  return {
+    left: ensureNumericOffset(position.left, "left", layerId),
+    top: ensureNumericOffset(position.top, "top", layerId),
+  };
+};
+
+const numericFeature = (value: number): string => {
+  return `${Math.round(value)}`;
+};
+
+const booleanFeature = (value: boolean | undefined): string | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return value ? "yes" : "no";
+};
+
+const buildWindowFeatures = (
+  layerId: string,
+  position: WindowPosition | undefined,
+  width: number | string | undefined,
+  height: number | string | undefined,
+  options: PopupWindowOptions | undefined,
+): string => {
+  const features: Record<string, string> = {};
+  const anchor = resolvePopupAnchor(position, layerId);
+
+  if (typeof width !== "number" || typeof height !== "number") {
+    throw new Error(`Popup layer "${layerId}" requires numeric width/height.`);
+  }
+  features.width = numericFeature(width);
+  features.height = numericFeature(height);
+  features.left = numericFeature(anchor.left);
+  features.top = numericFeature(anchor.top);
+
+  const overrides = options?.features;
+  if (overrides) {
+    const toolbar = booleanFeature(overrides.toolbar);
+    const menubar = booleanFeature(overrides.menubar);
+    const location = booleanFeature(overrides.location);
+    const status = booleanFeature(overrides.status);
+    const resizable = booleanFeature(overrides.resizable);
+    const scrollbars = booleanFeature(overrides.scrollbars);
+
+    if (toolbar !== undefined) {
+      features.toolbar = toolbar;
+    }
+    if (menubar !== undefined) {
+      features.menubar = menubar;
+    }
+    if (location !== undefined) {
+      features.location = location;
+    }
+    if (status !== undefined) {
+      features.status = status;
+    }
+    if (resizable !== undefined) {
+      features.resizable = resizable;
+    }
+    if (scrollbars !== undefined) {
+      features.scrollbars = scrollbars;
+    }
+  }
+
+  return Object.entries(features)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(",");
+};
+
+const applyBoundsToWindow = (
+  popupWindow: Window,
+  layerId: string,
+  position: WindowPosition | undefined,
+  width: number | string | undefined,
+  height: number | string | undefined,
+) => {
+  const anchor = resolvePopupAnchor(position, layerId);
+  if (typeof width !== "number" || typeof height !== "number") {
+    throw new Error(`Popup layer "${layerId}" requires numeric width/height.`);
+  }
+  popupWindow.moveTo(Math.round(anchor.left), Math.round(anchor.top));
+  popupWindow.resizeTo(Math.round(width), Math.round(height));
+};
+
+type PopupLayerPortalProps = {
+  layer: LayerDefinition;
+};
+
+export const PopupLayerPortal: React.FC<PopupLayerPortalProps> = ({ layer }) => {
+  const floating = layer.floating;
+  if (!floating) {
+    throw new Error(`Layer "${layer.id}" is missing floating configuration required for popup mode.`);
+  }
+  const mode = floating.mode ?? "embedded";
+  if (mode !== "popup") {
+    throw new Error(`PopupLayerPortal received layer "${layer.id}" that is not configured for popup mode.`);
+  }
+
+  const containerRef = React.useRef<HTMLDivElement | null>(null);
+  const popupWindowRef = React.useRef<Window | null>(null);
+  const [isMounted, setIsMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const features = buildWindowFeatures(layer.id, layer.position, layer.width, layer.height, floating.popup);
+    const windowName = floating.popup?.name ?? layer.id;
+    const createdWindow = resolvePopupWindow(
+      windowName,
+      features,
+      {
+        position: layer.position,
+        size: { width: layer.width as number, height: layer.height as number },
+      },
+      floating.popup,
+    );
+
+    if (!createdWindow) {
+      throw new Error(`Failed to open popup window for layer "${layer.id}".`);
+    }
+
+    const openedWindow = createdWindow;
+
+    popupWindowRef.current = openedWindow;
+
+    if (floating.popup?.focus !== false) {
+      openedWindow.focus();
+    }
+
+    if (!openedWindow.document.title) {
+      openedWindow.document.title = layer.id;
+    }
+    openedWindow.document.body.innerHTML = "";
+    const mountNode = openedWindow.document.createElement("div");
+    mountNode.dataset.layerId = layer.id;
+    openedWindow.document.body.appendChild(mountNode);
+    containerRef.current = mountNode;
+    setIsMounted(true);
+
+    applyBoundsToWindow(openedWindow, layer.id, layer.position, layer.width, layer.height);
+
+    const handleBeforeUnload = () => {
+      popupWindowRef.current = null;
+      containerRef.current = null;
+      setIsMounted(false);
+    };
+    openedWindow.addEventListener("beforeunload", handleBeforeUnload);
+
+    return () => {
+      openedWindow.removeEventListener("beforeunload", handleBeforeUnload);
+      if (floating.popup?.closeOnUnmount !== false) {
+        openedWindow.close();
+      }
+      popupWindowRef.current = null;
+      containerRef.current = null;
+      setIsMounted(false);
+    };
+  }, [
+    floating.popup?.closeOnUnmount,
+    floating.popup?.features?.location,
+    floating.popup?.features?.menubar,
+    floating.popup?.features?.resizable,
+    floating.popup?.features?.scrollbars,
+    floating.popup?.features?.status,
+    floating.popup?.features?.toolbar,
+    floating.popup?.focus,
+    floating.popup?.name,
+    layer.id,
+  ]);
+
+  React.useEffect(() => {
+    const popupWindow = popupWindowRef.current;
+    if (!popupWindow) {
+      return;
+    }
+    applyBoundsToWindow(popupWindow, layer.id, layer.position, layer.width, layer.height);
+  }, [layer.position?.left, layer.position?.top, layer.height, layer.width, layer.id]);
+
+  if (!isMounted || !containerRef.current) {
+    return null;
+  }
+
+  return createPortal(<LayerInstanceProvider layerId={layer.id}>{layer.component}</LayerInstanceProvider>, containerRef.current);
+};
+
+const resolvePopupWindow = (
+  windowName: string,
+  features: string,
+  bounds: WindowBounds,
+  options: PopupWindowOptions | undefined,
+): Window | null => {
+  const customFactory = options?.createWindow;
+  if (customFactory) {
+    return customFactory({ name: windowName, features, bounds });
+  }
+  return window.open("", windowName, features);
+};

package/src/config/PanelContentDeclaration.tsx

@@ -0,0 +1,427 @@
+/**
+ * @file PanelContentDeclaration (JSX DSL for content configuration ONLY)
+ *
+ * IMPORTANT: This file declares a JSX DSL to configure panel "content" and layout
+ * tracks. It does NOT implement grid rendering, resizing, dragging, or drawers.
+ * Those behaviors live in the existing layout/rendering modules. Keep this file
+ * limited to declaration and conversion into GridLayout props.
+ *
+ * Usage (content declaration):
+ * <PanelLayout>
+ *   <Config>
+ *     <Rows>...</Rows>
+ *     <Columns>...</Columns>
+ *     <Areas matrix={...}/>
+ *   </Config>
+ *   <Panel type="grid" id="main" area="main">...</Panel>
+ *   <Panel type="floating" id="preview" position={{ left: 0, top: 0 }} width={300} height={200} />
+ *   <Panel type="drawer" id="nav" drawer={{ defaultOpen: true }} position={{ left: 0 }} />
+ * </PanelLayout>
+ */
+import * as React from "react";
+import { GridLayout } from "../components/grid/GridLayout";
+import type { DrawerBehavior, GridTrack, PanelLayoutConfig, WindowPosition } from "../types";
+import type { PanelRoute } from "./panelRouter";
+import { buildLayersFromRoutes } from "./panelRouter";
+
+export type PanelRootProps = {
+  config?: PanelLayoutConfig;
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+};
+
+// Unified child declaration: <Panel type="grid" .../> or <Panel type="floating" .../>...
+type PanelCommonProps = {
+  id: string;
+  visible?: boolean;
+  zIndex?: number;
+  width?: number | string;
+  height?: number | string;
+  pointerEvents?: boolean | "auto" | "none";
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+};
+
+export type PanelProps =
+  | (PanelCommonProps & { type: "grid"; area: string })
+  | (PanelCommonProps & {
+      type: "floating";
+      position: WindowPosition;
+      width: number | string;
+      height: number | string;
+      draggable?: boolean;
+      resizable?: boolean;
+    })
+  | (PanelCommonProps & {
+      type: "drawer";
+      drawer: DrawerBehavior;
+      position?: WindowPosition;
+      backdropStyle?: React.CSSProperties;
+    })
+  | (Omit<PanelCommonProps, "children"> & {
+      type: "pivot";
+      area: string;
+      /** Currently active item ID (controlled mode) */
+      activeId?: string;
+      /** Default active item ID (uncontrolled mode) */
+      defaultActiveId?: string;
+      /** Callback when active item changes */
+      onActiveChange?: (id: string) => void;
+      children?: React.ReactNode;
+    });
+
+export const Panel: React.FC<PanelProps> = () => null;
+
+/**
+ * PivotItem declaration for use inside <Panel type="pivot">
+ */
+export type PivotItemDeclProps = {
+  id: string;
+  label?: string;
+  disabled?: boolean;
+  children?: React.ReactNode;
+};
+
+export const PivotItem: React.FC<PivotItemDeclProps> = () => null;
+
+const isElementOf = <P,>(element: unknown, component: React.FC<P>): element is React.ReactElement<P> => {
+  if (!React.isValidElement<P>(element)) {
+    return false;
+  }
+  return element.type === component;
+};
+
+export const buildRoutesFromChildren = (children: React.ReactNode): PanelRoute[] => {
+  const routes: PanelRoute[] = [];
+
+  const visit = (node: React.ReactNode): void => {
+    if (node === null || node === undefined || typeof node === "boolean") {
+      return;
+    }
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    // Unified <Panel type="..." />
+    if (isElementOf(node, Panel)) {
+      const props = node.props as PanelProps;
+      if (!props.id) {
+        throw new Error("<Panel> requires an 'id' prop.");
+      }
+      if (props.type === "grid") {
+        if (!props.area) {
+          throw new Error(`<Panel id="${props.id}"> requires an explicit 'area' prop when type="grid".`);
+        }
+        routes.push({
+          id: props.id,
+          area: props.area,
+          element: props.children ?? null,
+          visible: props.visible,
+          zIndex: props.zIndex,
+          width: props.width,
+          height: props.height,
+          pointerEvents: props.pointerEvents,
+          style: props.style,
+        });
+        return;
+      }
+      if (props.type === "floating") {
+        if (!props.position) {
+          throw new Error(`<Panel id="${props.id}"> requires a 'position' prop when type="floating".`);
+        }
+        if (props.width === undefined || props.height === undefined) {
+          throw new Error(`<Panel id="${props.id}"> requires 'width' and 'height' when type="floating".`);
+        }
+        routes.push({
+          id: props.id,
+          element: props.children ?? null,
+          visible: props.visible ?? true,
+          positionMode: "absolute",
+          position: props.position,
+          zIndex: props.zIndex,
+          width: props.width,
+          height: props.height,
+          pointerEvents: props.pointerEvents,
+          style: props.style,
+          floating: { mode: "embedded", draggable: props.draggable, resizable: props.resizable },
+        });
+        return;
+      }
+      if (props.type === "drawer") {
+        routes.push({
+          id: props.id,
+          element: props.children ?? null,
+          visible: props.visible ?? true,
+          positionMode: "relative",
+          position: props.position,
+          zIndex: props.zIndex,
+          width: props.width,
+          height: props.height,
+          pointerEvents: props.pointerEvents,
+          style: props.style,
+          drawer: props.drawer,
+          backdropStyle: props.backdropStyle,
+        });
+        return;
+      }
+      if (props.type === "pivot") {
+        if (!props.area) {
+          throw new Error(`<Panel id="${props.id}"> requires an explicit 'area' prop when type="pivot".`);
+        }
+        const pivotItems = collectPivotItems(props.children);
+        if (pivotItems.length === 0) {
+          throw new Error(`<Panel id="${props.id}"> requires at least one <PivotItem> child when type="pivot".`);
+        }
+        routes.push({
+          id: props.id,
+          area: props.area,
+          element: null,
+          visible: props.visible,
+          zIndex: props.zIndex,
+          width: props.width,
+          height: props.height,
+          pointerEvents: props.pointerEvents,
+          style: props.style,
+          pivot: {
+            items: pivotItems,
+            activeId: props.activeId,
+            defaultActiveId: props.defaultActiveId,
+            onActiveChange: props.onActiveChange,
+          },
+        });
+        return;
+      }
+      // unknown type -> error for explicitness
+      throw new Error("<Panel> has unsupported type.");
+    }
+
+    if (React.isValidElement(node)) {
+      if (node.type === React.Fragment) {
+        const el = node as React.ReactElement<{ children?: React.ReactNode }>;
+        visit(el.props.children);
+        return;
+      }
+      // Unknown element: ignore quietly to allow comments/wrappers.
+      return;
+    }
+    // Primitive nodes (string/number) are ignored.
+  };
+
+  visit(children);
+  return routes;
+};
+
+// Root container renamed to PanelLayout to avoid name collision with child <Panel/>
+export const PanelLayout: React.FC<PanelRootProps> = ({ config, style, children }) => {
+  const routes = React.useMemo(() => buildRoutesFromChildren(children), [children]);
+  const layers = React.useMemo(() => buildLayersFromRoutes(routes), [routes]);
+  const derivedConfig = React.useMemo(() => {
+    if (config) {
+      return config;
+    }
+    const built = buildConfigFromChildren(children);
+    if (!built) {
+      throw new Error("Panel requires either 'config' prop or a JSX config (<Config><Rows/><Columns/><Areas/></Config>). ");
+    }
+    return built;
+  }, [children, config]);
+  return <GridLayout config={derivedConfig} layers={layers} style={style} />;
+};
+
+// =============================
+// JSX Config Declarations
+// =============================
+
+export type ConfigProps = {
+  gap?: string;
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+};
+
+export const Config: React.FC<ConfigProps> = () => {
+  return null;
+};
+
+export const Rows: React.FC<{ children?: React.ReactNode }> = () => {
+  return null;
+};
+
+export const Columns: React.FC<{ children?: React.ReactNode }> = () => {
+  return null;
+};
+
+export type RowProps = GridTrack;
+export const Row: React.FC<RowProps> = () => {
+  return null;
+};
+
+export type ColumnProps = GridTrack;
+export const Col: React.FC<ColumnProps> = () => {
+  return null;
+};
+
+export type AreasProps = {
+  matrix: string[][];
+};
+export const Areas: React.FC<AreasProps> = () => {
+  return null;
+};
+
+type CollectedConfig = {
+  gap?: string;
+  style?: React.CSSProperties;
+  rows?: GridTrack[];
+  columns?: GridTrack[];
+  areas?: string[][];
+};
+
+const collectTracks = <P extends GridTrack>(children: React.ReactNode, marker: React.FC<P>): GridTrack[] => {
+  const result: GridTrack[] = [];
+  const visit = (node: React.ReactNode): void => {
+    if (node === null || node === undefined || typeof node === "boolean") {
+      return;
+    }
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (isElementOf(node, marker)) {
+      const props = node.props as P;
+      if (!props.size) {
+        throw new Error("Row/Col requires 'size' property.");
+      }
+      result.push({
+        size: props.size,
+        resizable: props.resizable,
+        minSize: props.minSize,
+        maxSize: props.maxSize,
+      });
+      return;
+    }
+    if (React.isValidElement(node)) {
+      const el = node as React.ReactElement<{ children?: React.ReactNode }>;
+      visit(el.props.children);
+    }
+  };
+  visit(children);
+  return result;
+};
+
+const collectConfigBlock = (children: React.ReactNode): CollectedConfig | null => {
+  const node = findFirst(children, Config);
+  if (!node) {
+    return null;
+  }
+  const props = node.props as ConfigProps;
+  const rows = collectTracks(node.props.children, Row);
+  const columns = collectTracks(node.props.children, Col);
+  const areasNode = findFirst(node.props.children, Areas);
+  const areas = areasNode ? (areasNode.props as AreasProps).matrix : undefined;
+  return {
+    gap: props.gap,
+    style: props.style,
+    rows,
+    columns,
+    areas,
+  };
+};
+
+const findFirst = <P,>(children: React.ReactNode, marker: React.FC<P>): React.ReactElement<P> | null => {
+  const visit = (node: React.ReactNode): React.ReactElement<P> | null => {
+    if (node === null || node === undefined || typeof node === "boolean") {
+      return null;
+    }
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        const found = visit(item);
+        if (found) {
+          return found;
+        }
+      }
+      return null;
+    }
+    if (isElementOf(node, marker)) {
+      return node as React.ReactElement<P>;
+    }
+    if (React.isValidElement(node)) {
+      const el = node as React.ReactElement<{ children?: React.ReactNode }>;
+      return visit(el.props.children);
+    }
+    return null;
+  };
+  return visit(children);
+};
+
+type CollectedPivotItem = {
+  id: string;
+  label?: string;
+  content: React.ReactNode;
+  disabled?: boolean;
+};
+
+const collectPivotItems = (children: React.ReactNode): CollectedPivotItem[] => {
+  const items: CollectedPivotItem[] = [];
+  const visit = (node: React.ReactNode): void => {
+    if (node === null || node === undefined || typeof node === "boolean") {
+      return;
+    }
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (isElementOf(node, PivotItem)) {
+      const props = node.props as PivotItemDeclProps;
+      if (!props.id) {
+        throw new Error("<PivotItem> requires an 'id' prop.");
+      }
+      items.push({
+        id: props.id,
+        label: props.label,
+        content: props.children ?? null,
+        disabled: props.disabled,
+      });
+      return;
+    }
+    if (React.isValidElement(node)) {
+      if (node.type === React.Fragment) {
+        const el = node as React.ReactElement<{ children?: React.ReactNode }>;
+        visit(el.props.children);
+      }
+    }
+  };
+  visit(children);
+  return items;
+};
+
+export const buildConfigFromChildren = (children: React.ReactNode): PanelLayoutConfig | null => {
+  const collected = collectConfigBlock(children);
+  if (!collected) {
+    return null;
+  }
+  if (!collected.rows || collected.rows.length === 0) {
+    throw new Error("Config must include at least one <Row size=...> inside <Config>.");
+  }
+  if (!collected.columns || collected.columns.length === 0) {
+    throw new Error("Config must include at least one <Col size=...> inside <Config>.");
+  }
+  if (!collected.areas || collected.areas.length === 0) {
+    throw new Error("Config must include <Areas matrix={...}> inside <Config>.");
+  }
+
+  const rowCount = collected.areas.length;
+  const colCount = collected.areas[0]?.length ?? 0;
+  if (rowCount !== collected.rows.length) {
+    throw new Error(`Areas row count (${rowCount}) must match Rows count (${collected.rows.length}).`);
+  }
+  if (colCount !== collected.columns.length) {
+    throw new Error(`Areas column count (${colCount}) must match Columns count (${collected.columns.length}).`);
+  }
+
+  return {
+    areas: collected.areas,
+    rows: collected.rows,
+    columns: collected.columns,
+    gap: collected.gap,
+    style: collected.style,
+  } satisfies PanelLayoutConfig;
+};

package/src/config/index.tsx

@@ -0,0 +1,52 @@
+/**
+ * @file Config utilities entry point for JSX-based panel configuration
+ *
+ * This module provides JSX DSL components for declarative panel configuration.
+ * Import from 'react-panel-layout/config' to use these utilities.
+ *
+ * @example
+ * ```tsx
+ * import { PanelLayout, Config, Rows, Row, Columns, Col, Areas, Panel } from 'react-panel-layout/config';
+ *
+ * <PanelLayout>
+ *   <Config>
+ *     <Rows>
+ *       <Row size="1fr" />
+ *       <Row size="2fr" />
+ *     </Rows>
+ *     <Columns>
+ *       <Col size="200px" />
+ *       <Col size="1fr" />
+ *     </Columns>
+ *     <Areas matrix={[
+ *       ['sidebar', 'main'],
+ *       ['sidebar', 'main']
+ *     ]} />
+ *   </Config>
+ *   <Panel type="grid" id="sidebar" area="sidebar">Sidebar</Panel>
+ *   <Panel type="grid" id="main" area="main">Main</Panel>
+ * </PanelLayout>
+ * ```
+ */
+
+export {
+  PanelLayout,
+  Panel,
+  buildRoutesFromChildren,
+  Config,
+  Rows,
+  Row,
+  Columns,
+  Col,
+  Areas,
+  buildConfigFromChildren,
+} from "./PanelContentDeclaration";
+
+export type {
+  PanelRootProps,
+  PanelProps,
+  ConfigProps,
+  RowProps,
+  ColumnProps,
+  AreasProps,
+} from "./PanelContentDeclaration";