@antv/layout 2.0.0-beta.0 → 2.0.0-beta.1

package/src/algorithm/grid/index.ts

@@ -1,13 +1,13 @@
-import { BaseLayout } from '../base-layout';
-import { LayoutNode, Point } from '../../types';
-import { applySingleNodeLayout, normalizeViewport, parseSize } from '../../util';
-import { formatNumberFn, formatSizeFn } from '../../util/format';
-import { orderByDegree, orderById, orderBySorter } from '../../util/order';
 import type { GraphLib } from '../../model/data';
+import { LayoutNode, NodeData, Point, Sorter } from '../../types';
+import { applySingleNodeLayout, normalizeViewport } from '../../util';
+import { formatFn, formatNodeSizeFn } from '../../util/format';
+import { orderByDegree, orderById, orderBySorter } from '../../util/order';
+import { BaseLayout } from '../base-layout';
 import type {
   GridLayoutOptions,
   IdMapRowAndCol,
-  NormalizedGridLayoutOptions,
+  ParsedGridLayoutOptions,
   RowAndCol,
   RowsAndCols,
   VisitMap,
@@ -15,6 +15,20 @@ import type {
 
 export type { GridLayoutOptions };
 
+const DEFAULT_LAYOUT_OPTIONS: Partial<GridLayoutOptions> = {
+  begin: [0, 0],
+  preventOverlap: true,
+  condense: false,
+  rows: undefined,
+  cols: undefined,
+  position: undefined,
+  sortBy: 'degree',
+  nodeSize: 30,
+  nodeSpacing: 10,
+  width: 300,
+  height: 300,
+};
+
 /**
  * <zh/> 网格布局
  *
@@ -24,26 +38,19 @@ export class GridLayout extends BaseLayout<GridLayoutOptions> {
   id = 'grid';
 
   protected getDefaultOptions(): Partial<GridLayoutOptions> {
-    return {
-      begin: [0, 0],
-      preventOverlap: true,
-      preventOverlapPadding: 10,
-      condense: false,
-      rows: undefined,
-      cols: undefined,
-      position: undefined,
-      sortBy: 'degree',
-      nodeSize: 30,
-      width: 300,
-      height: 300,
-    };
+    return DEFAULT_LAYOUT_OPTIONS;
   }
 
-  private normalizeOptions(
+  private parseOptions(
     options: Partial<GridLayoutOptions> = {},
     model: GraphLib,
-  ): NormalizedGridLayoutOptions {
-    const { rows: propRows, cols: propCols } = options;
+  ): ParsedGridLayoutOptions {
+    const {
+      rows: propRows,
+      cols: propCols,
+      position: propPosition,
+      sortBy: propSortBy,
+    } = options;
 
     const { width, height, center } = normalizeViewport(options);
     let rows = options.rows;
@@ -98,23 +105,20 @@ export class GridLayout extends BaseLayout<GridLayoutOptions> {
       }
     }
 
-    const preventOverlap =
-      options.preventOverlap || options.nodeSpacing !== undefined;
-    const nodeSpacing = formatNumberFn(options.nodeSpacing, 10);
-    const nodeSize = formatSizeFn(options.nodeSize, 30);
+    const sortBy = !propSortBy
+      ? (DEFAULT_LAYOUT_OPTIONS.sortBy as 'degree')
+      : propSortBy === 'degree' || propSortBy === 'id'
+      ? propSortBy
+      : (formatFn(propSortBy, ['nodeA', 'nodeB']) as Sorter<NodeData>);
 
     return {
-      ...options,
-      begin: options.begin || [0, 0],
-      sortBy: options.sortBy || 'degree',
-      preventOverlapPadding: options.preventOverlapPadding ?? 0,
-      preventOverlap,
-      nodeSpacing,
-      nodeSize,
+      ...(options as Required<GridLayoutOptions>),
+      sortBy,
       rcs,
       center,
       width,
       height,
+      position: formatFn(propPosition, ['node']),
     };
   }
 
@@ -126,12 +130,11 @@ export class GridLayout extends BaseLayout<GridLayoutOptions> {
       width,
       height,
       condense,
-      preventOverlapPadding,
       preventOverlap,
       nodeSpacing,
       nodeSize,
       position,
-    } = this.normalizeOptions(this.options, this.model);
+    } = this.parseOptions(this.options, this.model);
 
     const n = this.model.nodeCount();
 
@@ -152,18 +155,14 @@ export class GridLayout extends BaseLayout<GridLayoutOptions> {
     let cellHeight = condense ? 0 : height / rcs.rows;
 
     if (preventOverlap) {
+      const sizeFn = formatNodeSizeFn(
+        nodeSize,
+        nodeSpacing,
+        DEFAULT_LAYOUT_OPTIONS.nodeSize as number,
+        DEFAULT_LAYOUT_OPTIONS.nodeSpacing as number,
+      );
       this.model.forEachNode((node) => {
-        const nodeData = node._original;
-        const [nodeW, nodeH] = parseSize(nodeSize(nodeData) || 30);
-
-        const p =
-          nodeSpacing !== undefined
-            ? nodeSpacing(nodeData)
-            : preventOverlapPadding;
-
-        const w = nodeW + p;
-        const h = nodeH + p;
-
+        const [w, h] = sizeFn(node._original);
         cellWidth = Math.max(cellWidth, w);
         cellHeight = Math.max(cellHeight, h);
       });

package/src/algorithm/grid/types.ts

@@ -1,5 +1,5 @@
+import type { Expr, NodeData, Point, Sorter } from '../../types';
 import type { BaseLayoutOptions } from '../types';
-import type { NodeData, Point, Size } from '../../types';
 
 export interface GridLayoutOptions extends BaseLayoutOptions {
   /**
@@ -21,25 +21,6 @@ export interface GridLayoutOptions extends BaseLayoutOptions {
    * @defaultValue false
    */
   preventOverlap?: boolean;
-  /**
-   * <zh/> 节点大小（直径）。用于防止节点重叠时的碰撞检测
-   *
-   * <en/> Node size (diameter). Used for collision detection when nodes overlap
-   */
-  nodeSize?: Size | ((d?: NodeData) => Size);
-  /**
-   * <zh/> 环与环之间最小间距，用于调整半径
-   *
-   * <en/> Minimum spacing between rings, used to adjust the radius
-   */
-  nodeSpacing?: number | ((d?: NodeData) => number);
-  /**
-   * <zh/> 避免重叠时节点的间距 padding。preventOverlap 为 true 时生效
-   *
-   * <en/> Padding between nodes to prevent overlap. It takes effect when preventOverlap is true
-   * @defaultValue 10
-   */
-  preventOverlapPadding?: number;
   /**
    * <zh/> 为 false 时表示利用所有可用画布空间，为 true 时表示利用最小的画布空间
    *
@@ -67,38 +48,28 @@ export interface GridLayoutOptions extends BaseLayoutOptions {
    * <en/> Specify the basis for sorting (node attribute name). The higher the value, the more the node will be placed in the center. If it is undefined, the degree of the node will be calculated, and the higher the degree, the more the node will be placed in the center
    * @defaultValue undefined
    */
-  sortBy?: 'id' | 'degree' | ((nodeA: NodeData, nodeB: NodeData) => -1 | 0 | 1);
+  sortBy?: 'id' | 'degree' | Expr | Sorter<NodeData>;
   /**
    * <zh/> 指定每个节点所在的行和列
    *
    * <en/> Specify the row and column where each node is located
    * @defaultValue undefined
    */
-  position?: (node: NodeData) => { row?: number; col?: number };
+  position?: Expr | ((node: NodeData) => { row?: number; col?: number });
 }
 
-export interface NormalizedGridLayoutOptions
+export interface ParsedGridLayoutOptions
   extends Omit<
     GridLayoutOptions,
-    | 'begin'
-    | 'nodeSize'
-    | 'nodeSpacing'
-    | 'preventOverlap'
-    | 'preventOverlapPadding'
-    | 'sortBy'
-    | 'rows'
-    | 'cols'
+    'begin' | 'preventOverlap' | 'sortBy' | 'rows' | 'cols'
   > {
   width: number;
   height: number;
   center: Point;
   begin: Point;
   rcs: { rows: number; cols: number };
-  nodeSize: (node?: NodeData) => Size;
-  nodeSpacing: (node?: NodeData) => number;
   preventOverlap: boolean;
-  preventOverlapPadding: number;
-  sortBy: 'id' | 'degree' | ((nodeA: NodeData, nodeB: NodeData) => -1 | 0 | 1);
+  sortBy: 'id' | 'degree' | Sorter<NodeData>;
 }
 
 export type RowsAndCols = {

package/src/algorithm/radial/index.ts

@@ -1,10 +1,10 @@
-import { BaseLayout } from '../base-layout';
-import { runMDS } from '../mds';
-import type { ID, Matrix } from '../../types';
 import type { GraphLib } from '../../model/data';
+import type { ID, Matrix } from '../../types';
 import { getAdjList, johnson, normalizeViewport } from '../../util';
 import { applySingleNodeLayout } from '../../util/common';
-import { formatNodeSizeFn } from '../../util/format';
+import { formatFn, formatNodeSizeFn } from '../../util/format';
+import { BaseLayout } from '../base-layout';
+import { runMDS } from '../mds';
 import {
   radialNonoverlapForce,
   RadialNonoverlapForceOptions,
@@ -22,6 +22,8 @@ const DEFAULTS_LAYOUT_OPTIONS: Partial<RadialLayoutOptions> = {
   sortStrength: 10,
   strictRadial: true,
   unitRadius: null,
+  nodeSize: 10,
+  nodeSpacing: 0,
 };
 
 /**
@@ -126,7 +128,12 @@ export class RadialLayout extends BaseLayout<RadialLayoutOptions> {
 
     // stagger the overlapped nodes
     if (preventOverlap) {
-      const nodeSizeFunc = formatNodeSizeFn(nodeSize, nodeSpacing);
+      const nodeSizeFunc = formatNodeSizeFn(
+        nodeSize,
+        nodeSpacing,
+        DEFAULTS_LAYOUT_OPTIONS.nodeSize as number,
+        DEFAULTS_LAYOUT_OPTIONS.nodeSpacing as number,
+      );
       const nonoverlapForceParams: RadialNonoverlapForceOptions = {
         nodeSizeFunc,
         radiiMap,
@@ -230,7 +237,8 @@ const eIdealDisMatrix = (
 
   const baseLink = (linkDistance + unitRadius) / 2;
   const sortCache = new Map<ID, number>();
-  const sortFn = typeof sortBy === 'function' ? sortBy : null;
+  const sortFn =
+    !sortBy || sortBy === 'data' ? null : formatFn(sortBy, ['node']);
   const isDataSort = sortBy === 'data';
 
   for (let i = 0; i < n; i++) {

package/src/algorithm/radial/radial-nonoverlap-force.ts

@@ -1,6 +1,11 @@
-import type { DisplacementMap, ID, LayoutNode, NodeData, Size } from '../../types';
 import type { GraphLib } from '../../model/data';
-import { parseSize } from '../../util';
+import type {
+  DisplacementMap,
+  ID,
+  LayoutNode,
+  NodeData,
+  STDSize,
+} from '../../types';
 
 const SPEED_DIVISOR = 800;
 
@@ -22,7 +27,7 @@ export type RadialNonoverlapForceOptions = {
   /** Gravity factor pulling nodes towards their target radius */
   gravity?: number;
   /** Function to get the size of a node (includes node self and spacing) */
-  nodeSizeFunc: (node?: NodeData) => Size;
+  nodeSizeFunc: (node: NodeData) => STDSize;
 };
 
 const DEFAULTS_LAYOUT_OPTIONS: Partial<RadialNonoverlapForceOptions> = {
@@ -83,7 +88,7 @@ const getRepulsion = (
   displacements: DisplacementMap,
   k: number,
   radiiMap: Map<ID, number>,
-  nodeSizeFunc: (d?: NodeData) => Size,
+  nodeSizeFunc: (node: NodeData) => STDSize,
 ) => {
   let i = 0;
 
@@ -112,8 +117,8 @@ const getRepulsion = (
         vecy = 0.01 * sign;
       }
 
-      const nodeSizeU = Math.max(...parseSize(nodeSizeFunc(nodeU._original)));
-      const nodeSizeV = Math.max(...parseSize(nodeSizeFunc(nodeV._original)));
+      const nodeSizeU = Math.max(...nodeSizeFunc(nodeU._original));
+      const nodeSizeV = Math.max(...nodeSizeFunc(nodeV._original));
 
       // these two nodes overlap
       if (vecLength < nodeSizeV / 2 + nodeSizeU / 2) {

package/src/algorithm/radial/types.ts

@@ -1,5 +1,5 @@
+import type { Expr, NodeData } from '../../types';
 import type { BaseLayoutOptions } from '../base-layout';
-import type { NodeData, Size } from '../../types';
 
 /**
  * <zh/> Radial 辐射布局的配置项
@@ -41,19 +41,6 @@ export interface RadialLayoutOptions extends BaseLayoutOptions {
    * @defaultValue false
    */
   preventOverlap?: boolean;
-  /**
-   * <zh/> 节点大小（直径）。用于防止节点重叠时的碰撞检测
-   *
-   * <en/> Node size (diameter). Used for collision detection when preventing node overlap
-   */
-  nodeSize?: Size | ((d?: NodeData) => Size);
-  /**
-   * <zh/> preventOverlap 为 true 时生效, 防止重叠时节点边缘间距的最小值。可以是回调函数, 为不同节点设置不同的最小间距
-   *
-   * <en/> Effective when preventOverlap is true. The minimum edge spacing when preventing node overlap. It can be a callback function, and set different minimum spacing for different nodes
-   * @defaultValue 10
-   */
-  nodeSpacing?: number | ((d?: NodeData) => number);
   /**
    * <zh/> 防止重叠步骤的最大迭代次数
    *
@@ -82,7 +69,7 @@ export interface RadialLayoutOptions extends BaseLayoutOptions {
    * <en/> The default is undefined, which means arranging based on the topological structure of the data (the shortest path between nodes). Nodes that are closer in proximity or have a smaller shortest path between them will be arranged as close together as possible. 'data' indicates arranging based on the order of nodes in the data, so nodes that are closer in the data order will be arranged as close together as possible. You can also specify a field name in the node data, such as 'cluster' or 'name' (it must exist in the data of the graph)
    * @defaultValue undefined
    */
-  sortBy?: 'data' | ((d?: NodeData) => number | string);
+  sortBy?: 'data' | ((node: NodeData) => number | string) | Expr;
   /**
    * <zh/> 同层节点根据 sortBy 排列的强度，数值越大，sortBy 指定的方式计算出距离越小的越靠近。sortBy 不为 undefined 时生效
    *

package/src/algorithm/types.ts

@@ -1,11 +1,13 @@
 import type {
   EdgeData,
+  Expr,
   GraphData,
   GraphEdge,
   GraphNode,
   ID,
   NodeData,
   Point,
+  Size,
 } from '../types';
 
 export interface DataOptions<
@@ -63,6 +65,22 @@ export interface BaseLayoutOptions<
    */
   height?: number;
 
+  /**
+   * <zh/> 节点大小（直径）。用于防止节点重叠时的碰撞检测
+   *
+   * <en/> Node size (diameter). Used for collision detection when nodes overlap
+   * @defaultValue 10
+   */
+  nodeSize?: Size | Expr | ((node: NodeData) => Size);
+
+  /**
+   * <zh/> 节点之间的最小间距
+   *
+   * <en/> Minimum spacing between nodes
+   * @defaultValue 0
+   */
+  nodeSpacing?: Size | Expr | ((node: NodeData) => Size);
+
   /**
    * <zh/> 是否启用 WebWorker
    *

package/src/types/common.ts

@@ -1,3 +1,25 @@
 export type PlainObject = Record<string, any>;
 
 export type Matrix = number[][];
+
+/**
+ * String expression evaluated by `@antv/expr`.
+ *
+ * Notes:
+ * - `Expr` is structured-cloneable and can be passed into WebWorkers.
+ * - Function callbacks cannot be structured-cloned; prefer `Expr` when `enableWorker: true`.
+ */
+export type Expr = string;
+
+/**
+ * CallableExpr<(node: NodeData) => number>
+ *
+ * => 'node.degree' | (node: NodeData) => number
+ */
+export type CallableExpr<TData = any, TResult = any> =
+  | Expr
+  | ((data: TData) => TResult);
+
+export type ExprContext = Record<string, any>;
+
+export type Sorter<T = any> = (a: T, b: T) => -1 | 0 | 1;

package/src/types/data.ts

@@ -1,5 +1,5 @@
-import type { EdgeLabelPos } from './edge-label';
 import type { PlainObject } from './common';
+import type { EdgeLabelPos } from './edge-label';
 import type { ID } from './id';
 import type { Point } from './point';
 import type { Size } from './size';

package/src/util/expr.ts

@@ -0,0 +1,26 @@
+import { compile, evaluate } from '@antv/expr';
+import type { ExprContext } from '../types';
+
+/**
+ * Evaluate an expression if (and only if) it's a valid string expression.
+ * - Returns `undefined` when `expression` is not a string, empty, or invalid.
+ *
+ * @example
+ * evaluateExpression('x + y', { x: 10, y: 20 }) // 30
+ */
+export function evaluateExpression(
+  expression: unknown,
+  context: ExprContext,
+): unknown | undefined {
+  if (typeof expression !== 'string') return undefined;
+
+  const source = expression.trim();
+  if (!source) return undefined;
+
+  try {
+    compile(source);
+    return evaluate(source, context);
+  } catch {
+    return undefined;
+  }
+}

package/src/util/format.ts

@@ -1,6 +1,30 @@
-import { isFunction, isNumber, isObject } from '@antv/util';
-import type { NodeData, Size } from '../types';
-import { parseSize } from './size';
+import { isFunction, isNil, isNumber, isString } from '@antv/util';
+import type { Expr, NodeData, Size, STDSize } from '../types';
+import { evaluateExpression } from './expr';
+import { isSize, parseSize } from './size';
+
+/**
+ * Format a value into a callable function when it is a string expression.
+ * - `string` => `(context) => evaluateExpression(string, context)`
+ * - `function` => returned as-is
+ * - other => returned as-is
+ */
+export function formatFn<
+  TContext extends Record<string, any> = Record<string, any>,
+>(value: unknown, argNames: (keyof TContext & string)[]) {
+  if (typeof value === 'function') return value;
+  if (typeof value === 'string') {
+    const expr = value;
+    return (...argv: any[]) => {
+      const ctx = {} as TContext;
+      for (let i = 0; i < argNames.length; i++) {
+        (ctx as any)[argNames[i]] = argv[i];
+      }
+      return evaluateExpression(expr, ctx);
+    };
+  }
+  return () => value;
+}
 
 /**
  * Format value with multiple types into a function that returns a number
@@ -8,10 +32,26 @@ import { parseSize } from './size';
  * @param defaultValue The default value when value is invalid
  * @returns A function that returns a number
  */
-export function formatNumberFn<T = NodeData>(
-  value: number | ((d?: T) => number) | undefined,
+export function formatNumberFn<T extends NodeData = NodeData>(
+  value: number | Expr | ((d: T) => number) | undefined,
   defaultValue: number,
-): (d?: T) => number {
+  type: 'node' | 'edge' | 'combo' = 'node',
+): (d: T) => number {
+  // If value is undefined, return default value function
+  if (isNil(value)) {
+    return () => defaultValue;
+  }
+
+  // If value is an expression, return a function that evaluates the expression
+  if (isString(value)) {
+    const numberFn = formatFn(value, [type]);
+    return (d: T) => {
+      const evaluated = numberFn(d);
+      if (isNumber(evaluated)) return evaluated;
+      return defaultValue;
+    };
+  }
+
   // If value is a function, return it directly
   if (isFunction(value)) {
     return value;
@@ -33,15 +73,26 @@ export function formatNumberFn<T = NodeData>(
  * @param resultIsNumber Whether to return a number (max of width/height) or size array
  * @returns A function that returns a size
  */
-export function formatSizeFn<T extends NodeData>(
-  value?: Size | { width: number; height: number } | ((d?: T) => Size),
+export function formatSizeFn<T extends NodeData = NodeData>(
+  value?: Size | Expr | ((d: T) => Size),
   defaultValue: number = 10,
-): (d?: T) => Size {
+  type: 'node' | 'edge' | 'combo' = 'node',
+): (d: T) => Size {
   // If value is undefined, return default value function
-  if (!value) {
+  if (isNil(value)) {
     return () => defaultValue;
   }
 
+  // If value is an expression, return a function that evaluates the expression
+  if (isString(value)) {
+    const sizeFn = formatFn(value, [type]);
+    return (d: T) => {
+      const evaluated = sizeFn(d);
+      if (isSize(evaluated)) return evaluated;
+      return defaultValue;
+    };
+  }
+
   // If value is a function, return it directly
   if (isFunction(value)) {
     return value;
@@ -57,11 +108,6 @@ export function formatSizeFn<T extends NodeData>(
     return () => value;
   }
 
-  // If value is an object with width and height
-  if (isObject(value) && value.width && value.height) {
-    return () => [value.width, value.height];
-  }
-
   return () => defaultValue;
 }
 
@@ -70,23 +116,21 @@ export function formatSizeFn<T extends NodeData>(
  * @param nodeSize The size of the node
  * @param nodeSpacing The spacing around the node
  * @param defaultNodeSize The default node size when value is invalid
+ * @param defaultNodeSpacing The default node spacing when value is invalid
  * @returns A function that returns the total size (node size + spacing)
  */
 export const formatNodeSizeFn = (
-  nodeSize:
-    | Size
-    | { width: number; height: number }
-    | ((node?: NodeData) => Size)
-    | undefined,
-  nodeSpacing: number | ((node?: NodeData) => number) | undefined,
+  nodeSize?: Size | Expr | ((node: NodeData) => Size),
+  nodeSpacing?: Size | Expr | ((node: NodeData) => Size),
   defaultNodeSize: number = 10,
-): ((node?: NodeData) => number) => {
-  const nodeSpacingFunc = formatNumberFn(nodeSpacing, 0);
+  defaultNodeSpacing: number = 0,
+): ((d: NodeData) => STDSize) => {
+  const nodeSpacingFunc = formatSizeFn(nodeSpacing, defaultNodeSpacing);
   const nodeSizeFunc = formatSizeFn(nodeSize, defaultNodeSize);
 
-  return (node?: NodeData) => {
-    const size = nodeSizeFunc(node);
-    const spacing = nodeSpacingFunc(node);
-    return Math.max(...parseSize(size)) + spacing;
+  return (d: NodeData) => {
+    const [sizeW, sizeH, sizeD] = parseSize(nodeSizeFunc(d));
+    const [spacingW, spacingH, spacingD] = parseSize(nodeSpacingFunc(d));
+    return [sizeW + spacingW, sizeH + spacingH, sizeD + spacingD];
   };
 };

package/src/util/index.ts

@@ -1,5 +1,7 @@
 export * from './array';
 export * from './common';
+export * from './expr';
+export * from './format';
 export * from './math';
 export * from './object';
 export * from './order';

package/src/util/order.ts

@@ -1,11 +1,5 @@
-import type { LayoutNode, NodeData } from '../types';
 import type { GraphLib } from '../model/data';
-
-export type SortComparator<N extends NodeData = NodeData> = (
-  nodeA: LayoutNode<N>,
-  nodeB: LayoutNode<N>,
-  nodes: LayoutNode<N>[],
-) => -1 | 0 | 1;
+import type { LayoutNode, NodeData, Sorter } from '../types';
 
 /**
  * 通用排序核心函数
@@ -29,7 +23,7 @@ export function orderByDegree<N extends NodeData = NodeData>(
   return sort(model, (nodeA, nodeB) => {
     const degreeA = model.degree(nodeA.id);
     const degreeB = model.degree(nodeB.id);
-    if(order === 'asc') {
+    if (order === 'asc') {
       return degreeA - degreeB; // ascending order
     }
     return degreeB - degreeA; // descending order
@@ -59,7 +53,7 @@ export function orderById<N extends NodeData = NodeData>(
  */
 export function orderBySorter<N extends NodeData = NodeData>(
   model: GraphLib<N>,
-  sorter: (a: NodeData, b: NodeData) => -1 | 0 | 1,
+  sorter: Sorter<N>,
 ): GraphLib<N> {
   return sort(model, (nodeA, nodeB) => {
     const a = model.originalNode(nodeA.id);

package/src/util/size.ts

@@ -8,3 +8,11 @@ export function parseSize(size?: Size): STDSize {
   const [x, y = x, z = x] = size;
   return [x, y, z];
 }
+
+export function isSize(value: unknown): value is Size {
+  if (isNumber(value)) return true;
+  if (Array.isArray(value)) {
+    return value.every((item) => isNumber(item));
+  }
+  return false;
+}