@mui/x-charts-pro 8.20.0 → 8.21.0

package/SankeyChart/d3Sankey/sankey.types.d.ts

@@ -0,0 +1,344 @@
+/**
+ * A helper interface as an extension reference for user-provided properties of
+ * nodes and links in the graph, which are not required or calculated by
+ * the Sankey layout Generator
+ */
+export interface SankeyExtraProperties {
+  [key: string]: any;
+}
+/**
+ * Helper interface to define the properties of Sankey Nodes. Calculated properties may only be defined,
+ * once the layout(...) method of the Sankey layout generator has been invoked.
+ *
+ * The first generic N refers to user-defined properties contained in the node data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyNodeMinimal interface.
+ *
+ * The second generic L refers to user-defined properties contained in the link data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyLinkMinimal interface.
+ */
+export interface SankeyNodeMinimal<N extends SankeyExtraProperties, L extends SankeyExtraProperties> {
+  /**
+   * Array of outgoing links which have this node as their source.
+   * This property is calculated internally by the Sankey layout generator.
+   */
+  sourceLinks?: Array<SankeyLink<N, L>> | undefined;
+  /**
+   * Array of incoming links which have this node as their target.
+   * This property is calculated internally by the Sankey layout generator.
+   */
+  targetLinks?: Array<SankeyLink<N, L>> | undefined;
+  /**
+   * Node's value calculated by Sankey layout Generator;
+   * the sum of link.value for the node's incoming links.
+   */
+  value?: number | undefined;
+  /**
+   * Node's fixedValue (user-defined)
+   */
+  fixedValue?: number | undefined;
+  /**
+   * Node's zero-based index within the array of nodes calculated by Sankey layout generator.
+   */
+  index?: number | undefined;
+  /**
+   * Node's zero-based graph depth, derived from the graph topology calculated by Sankey layout generator.
+   */
+  depth?: number | undefined;
+  /**
+   * Node's zero-based graph height, derived from the graph topology calculated by Sankey layout generator.
+   */
+  height?: number | undefined;
+  /**
+   * Node's minimum horizontal position (derived from the node.depth) calculated by Sankey layout generator.
+   */
+  x0?: number | undefined;
+  /**
+   * Node's maximum horizontal position (node.x0 + sankey.nodeWidth) calculated by Sankey layout generator.
+   */
+  x1?: number | undefined;
+  /**
+   * Node's minimum vertical position calculated by Sankey layout generator.
+   */
+  y0?: number | undefined;
+  /**
+   * Node's maximum vertical position (node.y1 - node.y0 is proportional to node.value) calculated by Sankey layout generator.
+   */
+  y1?: number | undefined;
+  /**
+   * Link's layer in case of layered layout, calculated by Sankey layout generator.
+   */
+  layer?: number | undefined;
+}
+/**
+ * Sankey Node type including both user-defined node data elements as well as those
+ * calculated once the layout(...) method of the Sankey layout generators has been invoked.
+ *
+ * The first generic N refers to user-defined properties contained in the node data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyNodeMinimal interface.
+ *
+ * The second generic L refers to user-defined properties contained in the link data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyLinkMinimal interface.
+ */
+export type SankeyNode<N extends SankeyExtraProperties, L extends SankeyExtraProperties> = N & SankeyNodeMinimal<N, L>;
+/**
+ * Helper interface to define the properties of Sankey Links. Calculated properties may only be defined,
+ * once the layout(...) method of the Sankey layout generator has been invoked.
+ *
+ * The first generic N refers to user-defined properties contained in the node data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyNodeMinimal interface.
+ *
+ * The second generic L refers to user-defined properties contained in the link data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyLinkMinimal interface.
+ */
+export interface SankeyLinkMinimal<N extends SankeyExtraProperties, L extends SankeyExtraProperties> {
+  /**
+   * Link's source node. For convenience, when initializing a Sankey layout using the default node id accessor,
+   * source may be the zero-based index of the corresponding node in the nodes array
+   * returned by the nodes accessor of the Sankey layout generator rather than object references. Alternatively,
+   * the Sankey layout can be configured with a custom node ID accessor to resolve the source node of the link upon initialization.
+   *
+   * Once the Sankey generator is invoked to return the Sankey graph object,
+   * the numeric index will be replaced with the corresponding source node object.
+   */
+  source: number | string | SankeyNode<N, L>;
+  /**
+   * Link's target node. For convenience, when initializing a Sankey layout using the default node id accessor,
+   * target may be the zero-based index of the corresponding node in the nodes array
+   * returned by the nodes accessor of the Sankey layout generator rather than object references. Alternatively,
+   * the Sankey layout can be configured with a custom node ID accessor to resolve the target node of the link upon initialization.
+   *
+   * Once the Sankey generator is invoked to return the Sankey graph object,
+   * the numeric index will be replaced with the corresponding target node object.
+   */
+  target: number | string | SankeyNode<N, L>;
+  /**
+   * Link's numeric value
+   */
+  value: number;
+  /**
+   * Link's vertical starting position (at source node) calculated by Sankey layout generator.
+   */
+  y0?: number | undefined;
+  /**
+   * Link's vertical end position (at target node) calculated by Sankey layout generator.
+   */
+  y1?: number | undefined;
+  /**
+   * Link's width (proportional to its value) calculated by Sankey layout generator.
+   */
+  width?: number | undefined;
+  /**
+   * Link's zero-based index within the array of links calculated by Sankey layout generator.
+   */
+  index?: number | undefined;
+}
+/**
+ * Sankey Link type including both user-defined link data elements, those required by the Sankey layout generator,
+ *  as well as those calculated once the layout(...) method of the layout generator has been invoked.
+ *
+ * The first generic N refers to user-defined properties contained in the node data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyNodeMinimal interface.
+ *
+ * The second generic L refers to user-defined properties contained in the link data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyLinkMinimal interface.
+ */
+export type SankeyLink<N extends SankeyExtraProperties, L extends SankeyExtraProperties> = L & SankeyLinkMinimal<N, L>;
+/**
+ * A Sankey Graph Object which contains the computed layout information for nodes and links.
+ *
+ * The first generic N refers to user-defined properties contained in the node data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyNodeMinimal interface.
+ *
+ * The second generic L refers to user-defined properties contained in the link data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyLinkMinimal interface.
+ */
+export interface SankeyGraph<N extends SankeyExtraProperties, L extends SankeyExtraProperties> {
+  /**
+   * Array of Sankey diagram nodes
+   */
+  nodes: Array<SankeyNode<N, L>>;
+  /**
+   * Array of Sankey diagram links
+   */
+  links: Array<SankeyLink<N, L>>;
+}
+/**
+ * A Sankey layout generator.
+ *
+ * The first generic Data refers to the data type of the first argument passed in when invoking the
+ * Sankey layout generator and internally the configured nodes/links accessor functions.
+ *
+ * The second generic N refers to user-defined properties contained in the node data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyNodeMinimal interface.
+ *
+ * The third generic L refers to user-defined properties contained in the link data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyLinkMinimal interface.
+ */
+export interface SankeyLayout<Data, N extends SankeyExtraProperties, L extends SankeyExtraProperties> {
+  /**
+   * Computes the node and link positions for the given arguments, returning a graph representing the Sankey layout.
+   *
+   * @param data Data object being passed as the first argument to the nodes and links accessor functions. Additional arguments will also be passed
+   * to the accessor functions.
+   */
+  (data: Data, ...args: any[]): SankeyGraph<N, L>;
+  /**
+   * Recomputes the specified graph's links' positions, updating the following properties of each link:
+   *
+   * - link.sy: the link's vertical starting position (at source node)
+   * - link.ty: the link's vertical end position (at target node)
+   *
+   * This method is intended to be called after computing the initial Sankey layout, for example when the diagram is repositioned interactively.
+   *
+   * @param graph A previously initialized Sankey graph for which the link positions should be re-calculated
+   */
+  update(graph: SankeyGraph<N, L>): SankeyGraph<N, L>;
+  /**
+   * Return the current nodes accessor function, which defaults to a function returning the "nodes" property of the
+   * first argument it is invoked with.
+   */
+  nodes(): (data: Data, ...args: any[]) => Array<SankeyNode<N, L>>;
+  /**
+   * Set the Sankey generator's nodes accessor to a function returning the specified array of objects and returns this Sankey layout generator.
+   *
+   * @param nodes Array of nodes.
+   */
+  nodes(nodes: Array<SankeyNode<N, L>>): this;
+  /**
+   * Set the Sankey generator's nodes accessor to the specified function and returns this Sankey layout generator.
+   *
+   * @param nodes A nodes accessor function. The function is invoked when the Sankey layout is generated, being passed any arguments passed to the Sankey generator.
+   * This function must return an array of nodes.
+   */
+  nodes(nodes: (data: Data, ...args: any[]) => Array<SankeyNode<N, L>>): this;
+  /**
+   * Return the current links accessor function, which defaults to a function returning the "links" property of the
+   * first argument it is invoked with.
+   */
+  links(): (data: Data, ...args: any[]) => Array<SankeyLink<N, L>>;
+  /**
+   * Set the Sankey generator's links accessor to a function returning the specified array of objects and returns this Sankey layout generator.
+   *
+   * @param links Array of links.
+   */
+  links(links: Array<SankeyLink<N, L>>): this;
+  /**
+   * Set the Sankey generator's links accessor to the specified function and returns this Sankey layout generator.
+   *
+   * @param links A links accessor function. The function is invoked when the Sankey layout is generated, being passed any arguments passed to the Sankey generator.
+   * This function must return an array of links.
+   */
+  links(links: (data: Data, ...args: any[]) => Array<SankeyLink<N, L>>): this;
+  /**
+   * Return the current node id accessor.
+   * The default accessor is a function being passed in a Sankey layout node and returning its numeric node.index.
+   */
+  nodeId(): (node: SankeyNode<N, L>) => string | number;
+  /**
+   * Set the node id accessor to the specified function and return this Sankey layout generator.
+   *
+   * The default accessor is a function being passed in a Sankey layout node and returning its numeric node.index.
+   * The default id accessor allows each link's source and target to be specified as a zero-based index into the nodes array.
+   *
+   * @param nodeId A node id accessor function being passed a node in the Sankey graph and returning its id.
+   */
+  nodeId(nodeId: (node: SankeyNode<N, L>) => string | number): this;
+  /**
+   * Return the current node alignment method, which defaults to d3.sankeyJustify.
+   */
+  nodeAlign(): (node: SankeyNode<N, L>, n: number) => number;
+  /**
+   * Set the node alignment method the specified function and return this Sankey layout generator.
+   *
+   * @param nodeAlign A node alignment function which is evaluated for each input node in order,
+   * being passed the current node and the total depth n of the graph (one plus the maximum node.depth),
+   * and must return an integer between 0 and n - 1 that indicates the desired horizontal position of the node in the generated Sankey diagram.
+   */
+  nodeAlign(nodeAlign: (node: SankeyNode<N, L>, n: number) => number): this;
+  /**
+   * Return the current node width, which defaults to 24.
+   */
+  nodeWidth(): number;
+  /**
+   * Set the node width to the specified number and return this Sankey layout generator.
+   *
+   * @param width Width of node in pixels, which defaults to 24.
+   */
+  nodeWidth(width: number): this;
+  /**
+   * Return the current node padding, which defaults to 8.
+   *
+   * Node padding refers to the vertical space between nodes which occupy the same horizontal space.
+   */
+  nodePadding(): number;
+  /**
+   * Set the vertical separation between nodes at each column to the specified number and return this Sankey layout generator.
+   *
+   * @param padding Node padding, i.e. vertical separation between nodes at each column, in pixels, which defaults to 8.
+   */
+  nodePadding(padding: number): this;
+  /**
+   * Return the current extent which defaults to [[0, 0], [1, 1]].
+   */
+  extent(): [[number, number], [number, number]];
+  /**
+   * Set the extent of the Sankey layout to the specified bounds and returns this Sankey layout generator.
+   *
+   * @param extent Extent bounds for the layout. The extent bounds are specified as an array [[x0, y0], [x1, y1]],
+   * where x0 is the left side of the extent, y0 is the top, x1 is the right and y1 is the bottom. The default is [[0, 0], [1, 1]].
+   */
+  extent(extent: [[number, number], [number, number]]): this;
+  /**
+   * Return the current layout size in pixels. The size is a two element array of [width, height] which defaults to [1, 1].
+   */
+  size(): [number, number];
+  /**
+   * Set the size of the layout and return this Sankey layout generator.
+   * This convenience method is equivalent to using extent([[0, 0], [width, height]]).
+   *
+   * @param size A two element array of [width, height] in pixels which defaults to [1, 1].
+   */
+  size(size: [number, number]): this;
+  /**
+   * Return the current number of relaxation iterations, which defaults to 32.
+   */
+  iterations(): number;
+  /**
+   * Set the number of relaxation iterations when generating the layout and return this Sankey layout generator.
+   *
+   * @param iterations Number of relaxation iterations, which defaults to 32.
+   */
+  iterations(iterations: number): this;
+  /**
+   * Returns the node comparison function which defaults to undefined.
+   */
+  nodeSort(): ((a: SankeyNode<N, L>, b: SankeyNode<N, L>) => number) | undefined | null;
+  /**
+   * Set the node comparison function and return this Sankey layout generator.
+   *
+   * @param compare Node comparison function. If `null`, the order is fixed by the input.
+   */
+  nodeSort(compare: ((a: SankeyNode<N, L>, b: SankeyNode<N, L>) => number) | undefined | null): this;
+  /**
+   * Returns the link comparison function which defaults to undefined.
+   */
+  linkSort(): ((a: SankeyLink<N, L>, b: SankeyLink<N, L>) => number) | undefined | null;
+  /**
+   * Set the link comparison function and return this Sankey layout generator.
+   *
+   * @param compare Link comparison function. If `null`, the order is fixed by the input.
+   */
+  linkSort(compare: ((a: SankeyLink<N, L>, b: SankeyLink<N, L>) => number) | undefined | null): this;
+}

package/SankeyChart/d3Sankey/sankey.types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/SankeyChart/d3Sankey/sankeyLinkHorizontal.d.ts

@@ -0,0 +1,22 @@
+import { type Link } from '@mui/x-charts-vendor/d3-shape';
+import type { SankeyExtraProperties, SankeyLink } from "./sankey.types.js";
+/**
+ * Get a horizontal link shape suitable for a Sankey diagram.
+ * Source and target accessors are pre-configured and work with the
+ * default x- and y- accessors of the link shape generator.
+ */
+export declare function sankeyLinkHorizontal(): Link<any, SankeyLink<{}, {}>, [number, number]>;
+/**
+ * Get a horizontal link shape suitable for a Sankey diagram.
+ * Source and target accessors are pre-configured and work with the
+ * default x- and y- accessors of the link shape generator.
+ *
+ * The first generic N refers to user-defined properties contained in the node data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyNodeMinimal interface.
+ *
+ * The second generic L refers to user-defined properties contained in the link data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyLinkMinimal interface.
+ */
+export declare function sankeyLinkHorizontal<N extends SankeyExtraProperties, L extends SankeyExtraProperties>(): Link<any, SankeyLink<N, L>, [number, number]>;

package/SankeyChart/d3Sankey/sankeyLinkHorizontal.js

@@ -0,0 +1,37 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.sankeyLinkHorizontal = sankeyLinkHorizontal;
+var _d3Shape = require("@mui/x-charts-vendor/d3-shape");
+function horizontalSource(d) {
+  return [d.source.x1, d.y0];
+}
+function horizontalTarget(d) {
+  return [d.target.x0, d.y1];
+}
+
+/**
+ * Get a horizontal link shape suitable for a Sankey diagram.
+ * Source and target accessors are pre-configured and work with the
+ * default x- and y- accessors of the link shape generator.
+ */
+
+/**
+ * Get a horizontal link shape suitable for a Sankey diagram.
+ * Source and target accessors are pre-configured and work with the
+ * default x- and y- accessors of the link shape generator.
+ *
+ * The first generic N refers to user-defined properties contained in the node data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyNodeMinimal interface.
+ *
+ * The second generic L refers to user-defined properties contained in the link data passed into
+ * Sankey layout generator. These properties are IN EXCESS to the properties explicitly identified in the
+ * SankeyLinkMinimal interface.
+ */
+
+function sankeyLinkHorizontal() {
+  return (0, _d3Shape.linkHorizontal)().source(horizontalSource).target(horizontalTarget);
+}

package/SankeyChart/sankey.types.d.ts

@@ -1,6 +1,6 @@
 import type { HighlightScope, SeriesId } from '@mui/x-charts/internals';
 import type { DefaultizedProps, MakeRequired } from '@mui/x-internals/types';
-import type { SankeyLink as D3SankeyLink, SankeyNode as D3SankeyNode } from '@mui/x-charts-vendor/d3-sankey';
+import type { SankeyLink as D3SankeyLink, SankeyNode as D3SankeyNode } from "./d3Sankey/index.js";
 import type { SankeyLinkHighlightScope, SankeyNodeHighlightScope } from "./sankey.highlight.types.js";
 export type SankeyNodeId = string | number;
 export interface SankeyNode {

package/SankeyChart/seriesConfig/index.js

@@ -1,19 +1,34 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.sankeySeriesConfig = void 0;
 var _getSeriesWithDefaultValues = require("./getSeriesWithDefaultValues");
 var _tooltipGetter = require("./tooltipGetter");
+var _calculateSankeyLayout = require("../calculateSankeyLayout");
+var _tooltipPosition = _interopRequireDefault(require("./tooltipPosition"));
 // Simple passthrough functions for sankey chart
 const seriesProcessor = series => series;
 const colorProcessor = series => series;
 const legendGetter = () => [];
+const seriesLayout = (series, drawingArea) => {
+  if (series.seriesOrder.length === 0) {
+    return {};
+  }
+  return {
+    [series.seriesOrder[0]]: {
+      sankeyLayout: (0, _calculateSankeyLayout.calculateSankeyLayout)(series.series[series.seriesOrder[0]], drawingArea)
+    }
+  };
+};
 const sankeySeriesConfig = exports.sankeySeriesConfig = {
   seriesProcessor,
+  seriesLayout,
   colorProcessor,
   legendGetter,
   tooltipGetter: _tooltipGetter.tooltipGetter,
+  tooltipItemPositionGetter: _tooltipPosition.default,
   getSeriesWithDefaultValues: _getSeriesWithDefaultValues.getSeriesWithDefaultValues
 };

package/SankeyChart/seriesConfig/tooltipPosition.d.ts

@@ -0,0 +1,3 @@
+import type { TooltipItemPositionGetter } from '@mui/x-charts/internals';
+declare const tooltipItemPositionGetter: TooltipItemPositionGetter<'sankey'>;
+export default tooltipItemPositionGetter;

package/SankeyChart/seriesConfig/tooltipPosition.js

@@ -0,0 +1,96 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+const tooltipItemPositionGetter = params => {
+  const {
+    series,
+    seriesLayout,
+    identifier,
+    placement
+  } = params;
+  if (!identifier) {
+    return null;
+  }
+  const seriesItem = series.sankey?.series[identifier.seriesId];
+  const layout = seriesLayout.sankey?.[identifier.seriesId]?.sankeyLayout;
+  if (seriesItem == null || layout == null) {
+    return null;
+  }
+  if (identifier.subType === 'node') {
+    const node = layout.nodes.find(n => n.id === identifier.nodeId);
+    if (!node) {
+      return null;
+    }
+    const {
+      x0 = 0,
+      x1 = 0,
+      y0 = 0,
+      y1 = 0
+    } = node;
+    switch (placement) {
+      case 'bottom':
+        return {
+          x: (x1 + x0) / 2,
+          y: y1
+        };
+      case 'left':
+        return {
+          x: x0,
+          y: (y1 + y0) / 2
+        };
+      case 'right':
+        return {
+          x: x1,
+          y: (y1 + y0) / 2
+        };
+      case 'top':
+      default:
+        return {
+          x: (x1 + x0) / 2,
+          y: y0
+        };
+    }
+  }
+  if (identifier.subType === 'link') {
+    const link = layout.links.find(l => l.source.id === identifier.sourceId && l.target.id === identifier.targetId);
+    if (!link) {
+      return null;
+    }
+    const {
+      y0: yStart = 0,
+      y1: yEnd = 0
+    } = link;
+    const y0 = Math.min(yStart, yEnd) - link.width / 2;
+    const y1 = Math.max(yStart, yEnd) + link.width / 2;
+    const x0 = Math.min(link.source.x1 ?? 0, link.target.x1 ?? 0);
+    const x1 = Math.max(link.source.x0 ?? 0, link.target.x0 ?? 0);
+    switch (placement) {
+      case 'bottom':
+        return {
+          x: (x1 + x0) / 2,
+          y: y1
+        };
+      case 'left':
+        return {
+          x: x0,
+          y: (y1 + y0) / 2
+        };
+      case 'right':
+        return {
+          x: x1,
+          y: (y1 + y0) / 2
+        };
+      case 'top':
+      default:
+        return {
+          x: (x1 + x0) / 2,
+          y: y0
+        };
+    }
+  }
+  return null;
+};
+var _default = exports.default = tooltipItemPositionGetter;

package/SankeyChart/utils.d.ts

@@ -1,3 +1,3 @@
-import { sankeyLeft } from '@mui/x-charts-vendor/d3-sankey';
+import { sankeyJustify } from "./d3Sankey/index.js";
 import type { SankeyNodeOptions } from "./sankey.types.js";
-export declare const getNodeAlignFunction: (align: SankeyNodeOptions["align"]) => typeof sankeyLeft;
+export declare const getNodeAlignFunction: (align: SankeyNodeOptions["align"]) => typeof sankeyJustify;

package/SankeyChart/utils.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.getNodeAlignFunction = void 0;
-var _d3Sankey = require("@mui/x-charts-vendor/d3-sankey");
+var _d3Sankey = require("./d3Sankey");
 const getNodeAlignFunction = align => {
   switch (align) {
     case 'left':