@react-fabric/graph 1.0.0-beta.62 → 1.0.1

package/src/types/index.ts

@@ -1,210 +1,164 @@
-import { type GraphOptions } from "graphology-types";
-import { type RefObject } from "react";
-import { type Graph } from "../graph";
-
-interface NodeBadge {
-  position:
-    | "top-left"
-    | "top-right"
-    | "bottom-left"
-    | "bottom-right"
-    | "top"
-    | "left"
-    | "right";
-  type?: "star" | "exclaim" | "thumbUp" | "thumbDown";
-  path?: string;
-  /**
-   * icon color
-   */
-  iconColor?: string;
-  /**
-   * fill color
-   */
-  color?: string;
-}
-export interface NodeAttributes<N = KeyValue> {
-  /**
-   * node label
-   */
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export interface NodeAttributes<N extends KeyValue = KeyValue> {
+  data?: N;
+
+  id: string;
+
+  type?: string;
   label?: string;
-  /**
-   * node shape
-   */
-  type?: "circle" | "rect";
-  /**
-   * node size
-   */
-  size?: number;
-  /**
-   * node weight to apply proportional size
-   */
-  weight?: number;
-  /**
-   * label color
-   */
-  labelColor?: string;
-  /**
-   * border color
-   */
-  borderColor?: string;
-  /**
-   * icon color
-   */
-  iconColor?: string;
-  /**
-   * fill color
-   */
+  icon?: string;
+  image?: string;
+
   color?: string;
-  /**
-   * border width
-   */
   border?: number;
-  /**
-   * hover color
-   */
-  hoverColor?: string;
-  /**
-   * highlighted color
-   */
-  highlightColor?: string;
-  /**
-   * define node type
-   */
-  nodeType?: string;
-  /**
-   * pie colors
-   */
-  pie?: string[];
-  /**
-   * svg path
-   */
-  path?: string;
-  /**
-   * avatar/image url
-   */
-  image?: string;
-  /**
-   * selected state
-   */
-  selected?: boolean;
-  /**
-   * highlighted state
-   */
-  highlight?: boolean;
+  borderColor?: string;
+
+  segments?: string[] | number[] | { [color: string]: number };
 
-  badge?: NodeBadge[];
+  size?: number;
+  shape?: "square" | "circle" | "folder" | "diamond" | "triangle" | "folderOpen";
+
+  visible?: boolean;
 
   x?: number;
   y?: number;
-  hidden?: boolean;
-
-  data?: N;
+  z?: number;
 }
 
-export interface EdgeAttributes<E = KeyValue> {
-  /**
-   * edge shape
-   */
-  type?: "line" | "curved";
-  /**
-   * edge label
-   */
+export interface EdgeAttributes<E extends KeyValue = KeyValue> {
+  data?: E;
+
+  id: string;
+  source: string;
+  target: string;
+
+  type?: string;
   label?: string;
-  /**
-   * edge size
-   */
+  count?: number;
+
   size?: number;
-  /**
-   * edge weight to apply proportional size
-   */
-  weight?: number;
-  /**
-   * edge color
-   */
   color?: string;
-  /**
-   * hover color
-   */
-  hoverColor?: string;
-  /**
-   * highlighted color
-   */
-  highlightColor?: string;
-  /**
-   * define edge type
-   */
-  edgeType?: "curved" | "line";
-  /**
-   * edge arrow head
-   */
-  arrow?: "source" | "target" | "both";
-  /**
-   * edge count
-   */
-  count?: number;
 
-  /**
-   * selected state
-   */
-  selected?: boolean;
-  /**
-   * highlighted state
-   */
-  highlight?: boolean;
+  path?: "straight" | "curved" | "stepCurved" | "curvedS";
+  style?: "solid" | "dashed" | "dotted";
+  head?: "arrow";
+  tail?: "arrow";
 
-  data?: E;
+  visible?: boolean;
+
+  /** Marks a link that was created as a clone during `groupNodes`. Used by `ungroupNodes` to drop clones and revert the originals. */
+  groupEdge?: boolean;
+}
+
+export interface RawGraph<N extends KeyValue = KeyValue, E extends KeyValue = KeyValue> {
+  nodes: NodeAttributes<N>[];
+  edges: EdgeAttributes<E>[];
 }
 
-export interface InternalNodeAttributes<N = KeyValue>
-  extends NodeAttributes<N> {
+export interface InternalNode<N extends KeyValue = KeyValue> extends NodeAttributes<N> {
+  group?: boolean;
+  groupExpanded?: boolean;
+  groupNodes?: string[];
+
+  /** Back-reference to the group node that owns this (hidden) member. Empty for top-level nodes. */
   groupId?: string;
-  isGroup?: boolean;
-  expanded?: boolean;
-  nodeList?: string[];
-  opacity?: number;
-  id?: string;
-  fixed?: boolean;
-  originalEdges?: Array<{
-    key: string;
-    source: string;
-    target: string;
-    attributes?: KeyValue;
-  }>;
+
+  locked?: boolean;
+
+  /** Transient selection state, toggled by `selectNodes` / `unselectNodes`. */
+  selected?: boolean;
+  hilighted?: boolean;
+
+  x?: number;
+  y?: number;
+  z?: number;
+
+  fx?: number;
+  fy?: number;
+  fz?: number;
+
+  pieSize?: number;
+  slice_0?: number;
+  slice_1?: number;
+  slice_2?: number;
+  slice_3?: number;
+  slice_4?: number;
+  slice_5?: number;
+  slice_6?: number;
+  slice_7?: number;
+  slice_8?: number;
+  slice_9?: number;
+  slice_10?: number;
+  slice_11?: number;
+  color_0?: string;
+  color_1?: string;
+  color_2?: string;
+  color_3?: string;
+  color_4?: string;
+  color_5?: string;
+  color_6?: string;
+  color_7?: string;
+  color_8?: string;
+  color_9?: string;
+  color_10?: string;
+  color_11?: string;
 }
-export interface InternalEdgeAttributes<E = KeyValue>
-  extends EdgeAttributes<E> {
-  opacity?: number;
+
+export interface InternalEdge<E extends KeyValue = KeyValue> extends EdgeAttributes<E> {
+  group?: boolean;
+
+  /** Curvature of a `path: "curved"` edge; 0 = straight. Assigned by `assignCurvature` for parallel edges. */
   curvature?: number;
-  id?: string;
-}
 
-export interface RawGraph<N = KeyValue, E = KeyValue> {
-  nodes: Array<{ key: string; attributes?: NodeAttributes<N> }>;
-  edges: Array<{
-    key: string;
-    source: string;
-    target: string;
-    attributes?: EdgeAttributes<E>;
-  }>;
-  attributes?: KeyValue;
-  options?: GraphOptions;
-}
+  /** Dash length for `layerDashed`, in relative edge-length units. Assigned by `assignEdgeDash` from `shape`. */
+  dashSize?: number;
 
-export interface GraphRef<N = KeyValue, E = KeyValue> {
-  graph: Graph<N, E>;
-}
+  /** Dash gap length for `layerDashed`, in relative edge-length units. Assigned by `assignEdgeDash` from `shape`. */
+  gapSize?: number;
 
-export interface GraphProps<N = KeyValue, E = KeyValue> {
-  ref?: RefObject<GraphRef<N, E> | null>;
-  data: RawGraph<N, E> | Graph<N, E>;
-  nodeReducer?: (node: NodeAttributes<N>) => NodeAttributes<N>;
-  edgeReducer?: (edge: EdgeAttributes<E>) => EdgeAttributes<E>;
+  rotation?: number;
 
-  onSelectChange?: (selected: string[]) => void;
+  /** Transient selection state. */
+  selected?: boolean;
 
-  onNodeDoubleClick?: (node: string, attributes: NodeAttributes<N>) => void;
-  onContextMenu?: (
-    type: "canvas" | "node" | "edge",
-    nodesOrEdge?: string | string[],
-  ) => void;
+  /**
+   * The endpoint before it was re-pointed onto a group / merge node. Captured by
+   * `hydrateEdge` when the link is added; read back by `ungroupNode`.
+   */
+  originalSource?: string;
+  originalTarget?: string;
 }
+
+/**
+ * Public, listener-facing node: the node `id` merged with its `data` bag. This is
+ * what every `nodes*` event emits — internal fields (positions, pins, group and
+ * selection state) never leak to listeners.
+ */
+export type PublicNode<N extends KeyValue = KeyValue> = { id: string } & N;
+
+/** Public, listener-facing link: the link `id` merged with its `data` bag. Emitted by `edges*` events. */
+export type PublicEdge<E extends KeyValue = KeyValue> = { id: string } & E;

package/src/utils/edge.ts

@@ -0,0 +1,65 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { DisplayData } from "sigma/types";
+import { DEFAULT_STYLES } from "sigma/types";
+import type { EdgeAttributes } from "../types";
+
+export function edgeReducer(_: unknown, edge: DisplayData, attrs: EdgeAttributes) {
+  // @ts-expect-error ignore
+  if (attrs.path === "curved") edge.curvature = 0.3;
+  if (attrs.style === "dashed") {
+    // @ts-expect-error ignore
+    edge.dashSize = 4;
+    // @ts-expect-error ignore
+    edge.gapSize = 8;
+  }
+  // @ts-expect-error ignore
+  if (attrs.style === "dotted") edge.dashSize = edge.gapSize = edge.size ?? 2;
+  return edge;
+}
+
+export function defaultEdgeStyles(isDark = false) {
+  return [
+    DEFAULT_STYLES.edges as never,
+    {
+      size: { attribute: "size", defaultValue: 1 },
+      path: { attribute: "path", defaultValue: "straight" },
+      color: { attribute: "color", defaultValue: isDark ? "#475569" : "#94a3b8" },
+
+      head: { attribute: "head" },
+      tail: { attribute: "tail" },
+
+      gapSize: 0,
+      dashSize: 0,
+      parallelPath: "curved",
+      dashColor: isDark ? "#181818" : "#fff",
+
+      labelColor: isDark ? "#dedede" : "#545454",
+      labelVisibility: "auto",
+      labelPosition: "auto",
+    } as never,
+  ];
+}

package/src/utils/node.ts

@@ -0,0 +1,105 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { isArray, isObject } from "@react-fabric/utilities";
+import { DEFAULT_STYLES, type DisplayData } from "sigma/types";
+import type { InternalNode } from "../types";
+
+const PIE_PALETTE = ["#2ad4ac", "#ea5353", "#39a1e6", "#f8a850", "#B64E84", "#92c652", "#ac7dc4", "#2c91bd", "#f8d653", "#D16082", "#52c8d7", "#475065"];
+
+export function nodeReducer(_: unknown, node: DisplayData, attrs: InternalNode) {
+  if (isArray(attrs.segments) && attrs.segments?.length) {
+    // @ts-expect-error ignore
+    node.pieSize = 0.25;
+    attrs.segments.forEach((seg, i) => {
+      if (typeof seg === "string") {
+        // @ts-expect-error ignore
+        node[`slice_${i}`] = 1 / attrs.segments.length;
+        // @ts-expect-error ignore
+        node[`color_${i}`] = seg;
+      }
+      if (typeof seg === "number") {
+        // @ts-expect-error ignore
+        node[`slice_${i}`] = seg;
+        // @ts-expect-error ignore
+        node[`color_${i}`] = PIE_PALETTE[i];
+      }
+    });
+  }
+  if (isObject(attrs.segments)) {
+    // @ts-expect-error ignore
+    node.pieSize = 0.25;
+    Object.entries(attrs.segments).forEach(([color, size], i) => {
+      // @ts-expect-error ignore
+      node[`slice_${i}`] = size as number;
+      // @ts-expect-error ignore
+      node[`color_${i}`] = color;
+    });
+  }
+
+  if (attrs.group) {
+    // @ts-expect-error ignore
+    node.shape = "folder";
+  }
+  return node;
+}
+
+export function defaultNodeStyles(isDark = false) {
+  return [
+    DEFAULT_STYLES.nodes,
+    {
+      size: { attribute: "size", defaultValue: 8 },
+      shape: { attribute: "shape", defaultValue: "circle" },
+      color: { attribute: "color", defaultValue: isDark ? "#1e293b" : "#e2e8f0" },
+
+      border: { attribute: "border", defaultValue: 0 },
+      borderColor: { attribute: "borderColor", defaultValue: "#64748b" },
+
+      image: {
+        attribute: "image",
+        defaultValue: "data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==",
+      },
+
+      pieSize: 0,
+      ...Object.assign(
+        {},
+        ...Array.from({ length: 12 })
+          .fill(0)
+          .map((_, i) => ({
+            [`slice_${i}`]: i === 0 ? 1 : 0,
+            [`color_${i}`]: "#888",
+          })),
+      ),
+
+      labelPosition: "below",
+      labelColor: isDark ? "#fff" : "#333",
+
+      fillColor: isDark ? "#111" : "#fff",
+
+      backdropColor: isDark ? "#333" : "#fff",
+      backdropShadowColor: isDark ? "rgba(0, 0, 0, 0.5)" : "rgba(0, 0, 0, 0.3)",
+    },
+  ] as never;
+}

package/src/utils/sdfFolder.ts

@@ -0,0 +1,141 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { GLSL_ROTATE_2D, type SDFShape, type ValueSource } from "sigma/rendering";
+
+/**
+ * Options for the {@link sdfFolder} shape.
+ *
+ * @property cornerRadius - Corner rounding as a fraction of the node size.
+ *    `0` gives sharp corners; larger values round the body and the tab. May
+ *   also be a per-node attribute via `{ attribute, default }`.
+ * @property rotation - Rotation of the folder, in radians, applied before the
+ *   distance field is evaluated. May also be a per-node attribute via
+ *    `{ attribute, default }`.
+ */
+export interface FolderOptions {
+  /**
+   * Corner rounding as a fraction of the node size. Defaults to `0` (sharp
+   * corners).
+   */
+  cornerRadius?: ValueSource<number>;
+  /**
+   * Rotation of the folder, in radians, applied before the distance is
+   * computed. Defaults to `0`.
+   */
+  rotation?: ValueSource<number>;
+}
+
+/**
+ * Resolves a {@link ValueSource} to a plain number, falling back to
+ * `defaultValue` when the value is attribute-sourced or missing.
+ */
+function resolveNumber(value: ValueSource<number> | undefined, defaultValue: number): number {
+  return typeof value === "number" ? value : defaultValue;
+}
+
+/**
+ * Creates a folder SDF shape.
+ *
+ * The outline is the union of two rounded rectangles: a wide **body** and a
+ * smaller **tab** flap that rises above the body's top-left corner — the shape
+ * of a classic manila folder. Each panel is an Inigo Quilez rounded-box
+ * distance field (https://iquilezles.org/articles/distfunctions2d/) and the
+ * union is the closer of the two distances.
+ *
+ * @param options - Configuration for the folder
+ * @returns Folder SDF shape definition
+ *
+ * @example
+ * ```typescript
+ * // Sharp folder with a top-left tab
+ * const folder = sdfFolder();
+ *
+ * // Rounded folder
+ * const rounded = sdfFolder({ cornerRadius: 0.12 });
+ *
+ * // Per-node folder, driven by attributes
+ * const perNode = sdfFolder({
+ *   cornerRadius: { attribute: "folderCorner" },
+ *   rotation: { attribute: "folderRotation" },
+ * });
+ * ```
+ */
+export function sdfFolder(options?: FolderOptions): SDFShape {
+  const { cornerRadius, rotation } = options ?? {};
+  const cornerRadiusValue = resolveNumber(cornerRadius, 0);
+  const rotationValue = resolveNumber(rotation, 0);
+
+  // SDF for a folder: the union of a wide body panel and a top-left tab flap,
+  // each an Inigo Quilez rounded box. The GLSL_ROTATE_2D helper is prepended so
+  // `rotation` can be applied; the framework deduplicates it across shapes.
+  const glsl = `${GLSL_ROTATE_2D}
+float sdf_folder(vec2 uv, float size, float cornerRadius, float rotation) {
+    // Apply rotation if needed
+  vec2 p = uv;
+  if (rotation != 0.0) {
+    p = rotate2D(rotation) * p;
+    }
+
+    // A folder is the union of a wide body panel and a smaller tab flap that
+    // rises above the body's top-left. Each panel is a rounded box; the union is
+    // the closer of the two distances.
+  float s = size;
+  float cr = cornerRadius * s;
+
+    // Body: the main panel, wide and sitting just below the origin.
+  vec2 bodyD = abs(p - vec2(0.0, -0.05 * s)) - vec2(0.72 * s, 0.50 * s) + cr;
+  float body = length(max(bodyD, 0.0)) + min(max(bodyD.x, bodyD.y), 0.0) - cr;
+
+    // Tab: the top-left flap, its top edge poking above the body.
+  vec2 tabD = abs(p - vec2(-0.43 * s, 0.44 * s)) - vec2(0.29 * s, 0.20 * s) + cr;
+  float tab = length(max(tabD, 0.0)) + min(max(tabD.x, tabD.y), 0.0) - cr;
+
+    // Union of the two panels.
+  return min(body, tab);
+}
+`;
+
+  return {
+    name: "folder",
+    glsl,
+    uniforms: [
+      {
+        name: "u_cornerRadius",
+        type: "float",
+        value: cornerRadiusValue,
+      },
+      {
+        name: "u_rotation",
+        type: "float",
+        value: rotationValue,
+      },
+    ],
+    // The outline reaches out to the tab's top-left corner (circumradius
+    // ~0.96 of the node size); SQRT1_2 keeps the bounding quad comfortably
+    // larger, matching the square and diamond shapes.
+    inradiusFactor: Math.SQRT1_2,
+  };
+}