@canmingir/link 1.2.60 → 1.2.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canmingir/link",
-  "version": "1.2.60",
+  "version": "1.2.62",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {

package/src/components/nav-section/mini/nav-list.jsx

@@ -40,7 +40,7 @@ export default function NavList({ data, depth, slotProps }) {
         open={openMenu}
         onMouseEnter={handleOpenMenu}
         onMouseLeave={handleCloseMenu}
-        title={data.title}
+        title={data.compactTitle ?? data.title}
         path={data.path}
         icon={data.icon}
         info={data.info}

package/src/config/schemas.js

@@ -55,6 +55,7 @@ export const MenuConfigSchema = Joi.object({
           .items(
             Joi.object({
               title: Joi.string().required(),
+              compactTitle: Joi.string().optional(),
               icon: Joi.string().required(),
               path: Joi.string().required(),
               external: Joi.boolean().optional().default(false),

package/src/lib/Flow/core/Flow.jsx

@@ -1,21 +1,32 @@
 import { Box, alpha } from "@mui/material";
-import React, { useMemo, useState } from "react";
+import React, { forwardRef, useMemo, useState } from "react";
 import { assertLinkedGraph, buildTreeFromLinked } from "../utils/flowUtils";
 
 import FlowNode from "./FlowNode";
 import { useGraphOperations } from "../hooks/useGraphOperations";
 
-export const Flow = ({
-  data,
-  variant = "simple",
-  style,
-  plugin,
-  editable = false,
-  onChange,
-  height,
-  initialZoom,
-  centered = false,
-}) => {
+export const Flow = forwardRef(function Flow(
+  {
+    data,
+    variant = "simple",
+    style,
+    plugin,
+    editable = false,
+    onChange,
+    height,
+    initialZoom,
+    centered = false,
+    minZoom,
+    maxZoom,
+    fitViewPadding,
+    fitViewMaxZoom,
+    fitViewOnMount,
+    fitViewOnResize,
+    fitViewOnNodesChange,
+    onInit,
+  },
+  ref,
+) {
   const [floatingNodes, setFloatingNodes] = useState([]);
 
   const { nodesById, roots } = useMemo(() => assertLinkedGraph(data), [data]);
@@ -79,6 +90,7 @@ export const Flow = ({
       }}
     >
       <FlowNode
+        ref={ref}
         node={treeData}
         variant={variant}
         style={style}
@@ -92,9 +104,17 @@ export const Flow = ({
         height={height}
         initialZoom={initialZoom}
         centered={centered}
+        minZoom={minZoom}
+        maxZoom={maxZoom}
+        fitViewPadding={fitViewPadding}
+        fitViewMaxZoom={fitViewMaxZoom}
+        fitViewOnMount={fitViewOnMount}
+        fitViewOnResize={fitViewOnResize}
+        fitViewOnNodesChange={fitViewOnNodesChange}
+        onInit={onInit}
       />
     </Box>
   );
-};
+});
 
 export default Flow;

package/src/lib/Flow/core/FlowBoard.jsx

@@ -1,20 +1,31 @@
-import React, { useMemo } from "react";
+import React, { forwardRef, useMemo } from "react";
 
 import FlowBoardItem from "./FlowBoardItem";
 import FlowViewport from "./FlowViewport";
 import { SelectionProvider } from "../selection/SelectionContext";
 import { getBaseStyleForVariant } from "../styles";
 
-export const FlowBoard = ({
-  flows = [],
-  variant = "simple",
-  style,
-  plugin,
-  initialZoom = 1,
-  height = "100vh",
-  gap = 480,
-  onFlowPositionChange,
-}) => {
+export const FlowBoard = forwardRef(function FlowBoard(
+  {
+    flows = [],
+    variant = "simple",
+    style,
+    plugin,
+    initialZoom = 1,
+    height = "100vh",
+    gap = 480,
+    onFlowPositionChange,
+    minZoom,
+    maxZoom,
+    fitViewPadding,
+    fitViewMaxZoom,
+    fitViewOnMount,
+    fitViewOnResize,
+    fitViewOnNodesChange,
+    onInit,
+  },
+  ref,
+) {
   const baseStyle = getBaseStyleForVariant(variant);
   const selectionColor = baseStyle.selectionColor ?? "#64748b";
 
@@ -44,6 +55,7 @@ export const FlowBoard = ({
   return (
     <SelectionProvider>
       <FlowViewport
+        ref={ref}
         selectionColor={selectionColor}
         nodesById={mergedNodesById}
         variant={variant}
@@ -51,6 +63,14 @@ export const FlowBoard = ({
         plugin={plugin}
         height={height}
         initialZoom={initialZoom}
+        minZoom={minZoom}
+        maxZoom={maxZoom}
+        fitViewPadding={fitViewPadding}
+        fitViewMaxZoom={fitViewMaxZoom}
+        fitViewOnMount={fitViewOnMount}
+        fitViewOnResize={fitViewOnResize}
+        fitViewOnNodesChange={fitViewOnNodesChange}
+        onInit={onInit}
       >
         {positionedFlows.map(({ flow, id, position }) => (
           <FlowBoardItem
@@ -73,6 +93,6 @@ export const FlowBoard = ({
       </FlowViewport>
     </SelectionProvider>
   );
-};
+});
 
 export default FlowBoard;

package/src/lib/Flow/core/FlowNode.jsx

@@ -1,26 +1,37 @@
 import FlowNodeView from "../nodes/FlowNodeView";
 import FlowViewport from "./FlowViewport";
-import React from "react";
+import React, { forwardRef } from "react";
 import { SelectionProvider } from "../selection/SelectionContext";
 import { getBaseStyleForVariant } from "../styles";
 
-const FlowNode = ({
-  isRoot = false,
-  onAddNode,
-  variant,
-  nodesById,
-  onPaste,
-  onCut,
-  onConnect,
-  floatingNodes,
-  style,
-  plugin,
-  node,
-  height,
-  initialZoom,
-  centered,
-  ...props
-}) => {
+const FlowNode = forwardRef(function FlowNode(
+  {
+    isRoot = false,
+    onAddNode,
+    variant,
+    nodesById,
+    onPaste,
+    onCut,
+    onConnect,
+    floatingNodes,
+    style,
+    plugin,
+    node,
+    height,
+    initialZoom,
+    centered,
+    minZoom,
+    maxZoom,
+    fitViewPadding,
+    fitViewMaxZoom,
+    fitViewOnMount,
+    fitViewOnResize,
+    fitViewOnNodesChange,
+    onInit,
+    ...props
+  },
+  ref,
+) {
   if (!isRoot) {
     if (!node) return null;
     return (
@@ -42,6 +53,7 @@ const FlowNode = ({
   return (
     <SelectionProvider>
       <FlowViewport
+        ref={ref}
         selectionColor={selectionColor}
         nodesById={nodesById}
         onPaste={onPaste}
@@ -54,6 +66,14 @@ const FlowNode = ({
         height={height}
         initialZoom={initialZoom}
         centered={centered}
+        minZoom={minZoom}
+        maxZoom={maxZoom}
+        fitViewPadding={fitViewPadding}
+        fitViewMaxZoom={fitViewMaxZoom}
+        fitViewOnMount={fitViewOnMount}
+        fitViewOnResize={fitViewOnResize}
+        fitViewOnNodesChange={fitViewOnNodesChange}
+        onInit={onInit}
       >
         {node && (
           <FlowNodeView
@@ -69,6 +89,6 @@ const FlowNode = ({
       </FlowViewport>
     </SelectionProvider>
   );
-};
+});
 
 export default FlowNode;

package/src/lib/Flow/core/FlowViewport.jsx

@@ -1,28 +1,55 @@
-import React, { useEffect, useRef, useState } from "react";
+import {
+  DEFAULT_FIT_VIEW_PADDING,
+  DEFAULT_MAX_ZOOM,
+  DEFAULT_MIN_ZOOM,
+  clampZoomValue,
+  computeFitViewState,
+} from "../utils/viewportUtils";
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "react";
 
 import { Box } from "@mui/material";
 import FloatingGraph from "../graph/FloatingGraph";
 import SelectionOverlay from "../selection/SelectionOverlay";
 import { useSelection } from "../selection/SelectionContext";
 
-const FlowViewport = ({
-  children,
-  selectionColor = "#64748b",
-  nodesById,
-  onPaste,
-  onCut,
-  onConnect,
-  floatingNodes = [],
-  variant,
-  style,
-  plugin,
-  height = "100vh",
-  initialZoom = 1,
-  centered = false,
-  sx = {},
-  ...rest
-}) => {
-  const clampZoom = (zoom) => Math.min(2.5, Math.max(0.25, zoom));
+const FlowViewport = forwardRef(function FlowViewport(
+  {
+    children,
+    selectionColor = "#64748b",
+    nodesById,
+    onPaste,
+    onCut,
+    onConnect,
+    floatingNodes = [],
+    variant,
+    style,
+    plugin,
+    height = "100vh",
+    initialZoom = 1,
+    centered = false,
+    minZoom = DEFAULT_MIN_ZOOM,
+    maxZoom = DEFAULT_MAX_ZOOM,
+    fitViewPadding = DEFAULT_FIT_VIEW_PADDING,
+    fitViewMaxZoom = 1,
+    fitViewOnMount = false,
+    fitViewOnResize = false,
+    fitViewOnNodesChange = false,
+    onInit,
+    sx = {},
+    ...rest
+  },
+  ref,
+) {
+  const clampZoom = (z) => clampZoomValue(z, minZoom, maxZoom);
+
+  const usesFitView = fitViewOnMount || fitViewOnResize || fitViewOnNodesChange;
 
   const [offset, setOffset] = useState({ x: 0, y: 0 });
   const [zoom, setZoom] = useState(initialZoom);
@@ -46,7 +73,7 @@ const FlowViewport = ({
   } = useSelection();
 
   useEffect(() => {
-    if (centered) return;
+    if (centered || usesFitView) return;
 
     const container = containerRef.current;
     const inner = innerRef.current;
@@ -67,7 +94,123 @@ const FlowViewport = ({
     observer.observe(container);
 
     return () => observer.disconnect();
-  }, [centered]);
+  }, [centered, usesFitView]);
+
+  const runFitView = useCallback(
+    (options = {}) => {
+      const fit = computeFitViewState(containerRef.current, {
+        zoom,
+        offset,
+        padding: options.padding ?? fitViewPadding,
+        minZoom: options.minZoom ?? minZoom,
+        maxZoom: options.maxZoom ?? fitViewMaxZoom,
+      });
+      if (!fit) return;
+      setZoom(fit.zoom);
+      setOffset(fit.offset);
+    },
+    [zoom, offset, fitViewPadding, minZoom, fitViewMaxZoom],
+  );
+
+  const zoomIn = useCallback(
+    (step = 1.2) => setZoom((z) => clampZoom(z * step)),
+    [minZoom, maxZoom],
+  );
+
+  const zoomOut = useCallback(
+    (step = 1.2) => setZoom((z) => clampZoom(z / step)),
+    [minZoom, maxZoom],
+  );
+
+  const setZoomPublic = useCallback(
+    (z) => setZoom(clampZoom(z)),
+    [minZoom, maxZoom],
+  );
+
+  const setCenter = useCallback(
+    (x, y, options = {}) => {
+      const targetZoom = clampZoom(options.zoom ?? zoom);
+      setZoom(targetZoom);
+      setOffset({ x: -targetZoom * x, y: -targetZoom * y });
+    },
+    [zoom, minZoom, maxZoom],
+  );
+
+  const getZoom = useCallback(() => zoom, [zoom]);
+
+  const runFitViewRef = useRef(runFitView);
+  useEffect(() => {
+    runFitViewRef.current = runFitView;
+  }, [runFitView]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      fitView: runFitView,
+      zoomIn,
+      zoomOut,
+      setZoom: setZoomPublic,
+      setCenter,
+      getZoom,
+    }),
+    [runFitView, zoomIn, zoomOut, setZoomPublic, setCenter, getZoom],
+  );
+
+  useEffect(() => {
+    if (!fitViewOnMount) return;
+    runFitView();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    if (!fitViewOnResize) return;
+
+    const container = containerRef.current;
+    if (!container) return;
+
+    let frame = null;
+    let isFirstCallback = true;
+    const observer = new ResizeObserver(() => {
+      if (isFirstCallback) {
+        isFirstCallback = false;
+        return;
+      }
+      if (frame) cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => runFitViewRef.current());
+    });
+
+    observer.observe(container);
+
+    return () => {
+      if (frame) cancelAnimationFrame(frame);
+      observer.disconnect();
+    };
+  }, [fitViewOnResize]);
+
+  const nodeCount = nodesById ? Object.keys(nodesById).length : 0;
+  const previousNodeCountRef = useRef(nodeCount);
+
+  useEffect(() => {
+    if (!fitViewOnNodesChange) return;
+
+    if (previousNodeCountRef.current !== nodeCount) {
+      previousNodeCountRef.current = nodeCount;
+      const frame = requestAnimationFrame(() => runFitViewRef.current());
+      return () => cancelAnimationFrame(frame);
+    }
+  }, [fitViewOnNodesChange, nodeCount]);
+
+  useEffect(() => {
+    onInit?.({
+      fitView: runFitView,
+      zoomIn,
+      zoomOut,
+      setZoom: setZoomPublic,
+      setCenter,
+      getZoom,
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
 
   useEffect(() => {
     const handleMouseMove = (e) => {
@@ -313,11 +456,19 @@ const FlowViewport = ({
           height: height,
           display: "flex",
           alignItems: "center",
-          justifyContent: centered || shouldCenter ? "center" : "flex-start",
+          justifyContent:
+            centered || (!usesFitView && shouldCenter)
+              ? "center"
+              : "flex-start",
           transition: isDragging ? "none" : "transform 0.1s ease-out",
           pointerEvents: "auto",
           position: "relative",
-          pl: centered ? 0 : variant === "horizontal" ? 4 : 0,
+          pl:
+            centered || (!usesFitView && shouldCenter)
+              ? 0
+              : variant === "horizontal"
+                ? 4
+                : 0,
         }}
       >
         {children}
@@ -340,6 +491,6 @@ const FlowViewport = ({
       </Box>
     </Box>
   );
-};
+});
 
 export default FlowViewport;

package/src/lib/Flow/utils/viewportUtils.js

@@ -0,0 +1,81 @@
+export const DEFAULT_MIN_ZOOM = 0.25;
+export const DEFAULT_MAX_ZOOM = 2.5;
+export const DEFAULT_FIT_VIEW_PADDING = 40;
+
+export const clampZoomValue = (zoom, minZoom, maxZoom) =>
+  Math.min(maxZoom, Math.max(minZoom, zoom));
+
+export const computeFitTransform = ({
+  bounds,
+  containerWidth,
+  containerHeight,
+  padding = DEFAULT_FIT_VIEW_PADDING,
+  minZoom = DEFAULT_MIN_ZOOM,
+  maxZoom = DEFAULT_MAX_ZOOM,
+}) => {
+  const availableWidth = Math.max(0, containerWidth - 2 * padding);
+  const availableHeight = Math.max(0, containerHeight - 2 * padding);
+
+  const scaleX = bounds.width > 0 ? availableWidth / bounds.width : Infinity;
+  const scaleY = bounds.height > 0 ? availableHeight / bounds.height : Infinity;
+  const rawZoom = Math.min(scaleX, scaleY);
+
+  const zoom = clampZoomValue(rawZoom, minZoom, maxZoom);
+
+  const centerX = bounds.x + bounds.width / 2;
+  const centerY = bounds.y + bounds.height / 2;
+
+  return {
+    zoom,
+    offset: {
+      x: -zoom * centerX,
+      y: -zoom * centerY,
+    },
+  };
+};
+
+export const computeContentBounds = (containerEl, { zoom, offset }) => {
+  if (!containerEl) return null;
+
+  const nodeEls = containerEl.querySelectorAll("[data-node-id]");
+  if (nodeEls.length === 0) return null;
+
+  const containerRect = containerEl.getBoundingClientRect();
+  const originX = containerRect.left + containerRect.width / 2;
+  const originY = containerRect.top + containerRect.height / 2;
+
+  const toContentX = (screenX) => (screenX - originX - offset.x) / zoom;
+  const toContentY = (screenY) => (screenY - originY - offset.y) / zoom;
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  nodeEls.forEach((el) => {
+    const rect = el.getBoundingClientRect();
+    minX = Math.min(minX, toContentX(rect.left));
+    maxX = Math.max(maxX, toContentX(rect.right));
+    minY = Math.min(minY, toContentY(rect.top));
+    maxY = Math.max(maxY, toContentY(rect.bottom));
+  });
+
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+};
+
+export const computeFitViewState = (
+  containerEl,
+  { zoom, offset, padding, minZoom, maxZoom },
+) => {
+  const bounds = computeContentBounds(containerEl, { zoom, offset });
+  if (!bounds) return null;
+
+  return computeFitTransform({
+    bounds,
+    containerWidth: containerEl.clientWidth,
+    containerHeight: containerEl.clientHeight,
+    padding,
+    minZoom,
+    maxZoom,
+  });
+};

package/src/stories/FlowFitView.stories.jsx

@@ -0,0 +1,173 @@
+import { Button, Stack } from "@mui/material";
+import React, { useRef, useState } from "react";
+
+import { Flow } from "../lib/Flow";
+
+const treeToLinked = (tree) => {
+  if (!tree) return { nodes: {}, roots: [] };
+
+  const nodes = {};
+  const roots = [];
+
+  const walk = (node, parentId = null) => {
+    if (!node || !node.id) return;
+
+    const { children, ...rest } = node;
+    if (!nodes[node.id]) {
+      nodes[node.id] = { ...rest, id: node.id };
+    }
+
+    const kids = Array.isArray(children) ? children : [];
+    const nextIds = kids.map((c) => c.id).filter(Boolean);
+
+    if (nextIds.length === 1) {
+      nodes[node.id].next = nextIds[0];
+    } else if (nextIds.length > 1) {
+      nodes[node.id].next = nextIds;
+    }
+
+    if (parentId) {
+      nodes[node.id].previous = parentId;
+    } else if (!roots.includes(node.id)) {
+      roots.push(node.id);
+    }
+
+    kids.forEach((child) => walk(child, node.id));
+  };
+
+  walk(tree);
+  return { nodes, roots };
+};
+
+export default {
+  title: "Components/FlowFitView",
+  component: Flow,
+  parameters: {
+    layout: "fullscreen",
+  },
+};
+
+const wideTree = {
+  id: "root",
+  label: "Root",
+  children: [
+    {
+      id: "branch1",
+      label: "Branch 1",
+      children: [
+        { id: "leaf1-1", label: "Leaf 1.1", children: [] },
+        { id: "leaf1-2", label: "Leaf 1.2", children: [] },
+      ],
+    },
+    {
+      id: "branch2",
+      label: "Branch 2",
+      children: [
+        { id: "leaf2-1", label: "Leaf 2.1", children: [] },
+        { id: "leaf2-2", label: "Leaf 2.2", children: [] },
+        { id: "leaf2-3", label: "Leaf 2.3", children: [] },
+      ],
+    },
+    {
+      id: "branch3",
+      label: "Branch 3",
+      children: [{ id: "leaf3-1", label: "Leaf 3.1", children: [] }],
+    },
+  ],
+};
+
+export const FitViewDemo = {
+  render: () => {
+    const flowRef = useRef(null);
+    const data = treeToLinked(wideTree);
+
+    return (
+      <Stack sx={{ height: "100vh" }}>
+        <Stack direction="row" spacing={1} sx={{ p: 1 }}>
+          <Button
+            variant="contained"
+            onClick={() => flowRef.current?.fitView()}
+          >
+            Fit View
+          </Button>
+          <Button variant="outlined" onClick={() => flowRef.current?.zoomIn()}>
+            Zoom In
+          </Button>
+          <Button
+            variant="outlined"
+            onClick={() => flowRef.current?.zoomOut()}
+          >
+            Zoom Out
+          </Button>
+        </Stack>
+        <Flow
+          ref={flowRef}
+          data={data}
+          variant="simple"
+          height="calc(100vh - 56px)"
+          minZoom={0.25}
+          maxZoom={2.5}
+          fitViewPadding={60}
+          fitViewMaxZoom={1}
+          fitViewOnMount
+        />
+      </Stack>
+    );
+  },
+};
+
+export const FitViewOnNodesChangeDemo = {
+  render: () => {
+    const flowRef = useRef(null);
+    const [tree, setTree] = useState(wideTree);
+    const data = treeToLinked(tree);
+
+    const addLeafToBranch1 = () => {
+      setTree((prev) => {
+        const branch1 = prev.children.find((c) => c.id === "branch1");
+        const nextIndex = branch1.children.length + 1;
+        const newLeaf = {
+          id: `leaf1-${nextIndex}-${Date.now()}`,
+          label: `Leaf 1.${nextIndex}`,
+          children: [],
+        };
+        return {
+          ...prev,
+          children: prev.children.map((c) =>
+            c.id === "branch1"
+              ? { ...c, children: [...c.children, newLeaf] }
+              : c,
+          ),
+        };
+      });
+    };
+
+    return (
+      <Stack sx={{ height: "100vh" }}>
+        <Stack direction="row" spacing={1} sx={{ p: 1 }}>
+          <Button variant="contained" onClick={addLeafToBranch1}>
+            Add Node
+          </Button>
+          <Button
+            variant="outlined"
+            onClick={() => flowRef.current?.fitView()}
+          >
+            Fit View
+          </Button>
+        </Stack>
+        <Flow
+          ref={flowRef}
+          data={data}
+          variant="simple"
+          height="calc(100vh - 56px)"
+          minZoom={0.25}
+          maxZoom={2.5}
+          fitViewPadding={60}
+          fitViewMaxZoom={1}
+          fitViewOnMount
+          fitViewOnNodesChange
+        />
+      </Stack>
+    );
+  },
+};