panelui-native 0.99.0 → 0.101.0

package/lib/typescript/src/components/mirror-area-chart/index.d.ts

@@ -0,0 +1,263 @@
+/**
+ * MirrorAreaChart — two readings of one timeline, one above a baseline and one
+ * below it.
+ *
+ * ```tsx
+ * <MirrorAreaChart data={load} xDataKey="time">
+ *   <MirrorAreaChart.Grid />
+ *   <MirrorAreaChart.Area dataKey="jobs" label="jobs" muted />
+ *   <MirrorAreaChart.Area dataKey="high" label="high priority" />
+ *   <MirrorAreaChart.Area dataKey="share" label="% high" side="bottom" />
+ *   <MirrorAreaChart.Baseline />
+ *   <MirrorAreaChart.Tooltip />
+ * </MirrorAreaChart>
+ * ```
+ *
+ * ## Two scales, one timeline
+ *
+ * Each half has its own scale, because the two readings are usually in
+ * different units — a count above and a percentage below, or requests above
+ * and errors below. Both grow away from the baseline, so a peak in one lines
+ * up with whatever the other did at the same moment, and neither is squeezed
+ * into the other's range.
+ *
+ * Areas on the same side overlay in the order they are declared. Declare the
+ * whole first and the part of it second, so the part is drawn inside the whole.
+ */
+import { type ReactNode } from 'react';
+import { type ViewProps } from 'react-native';
+import { type ChartAccessibilityProps } from '../../primitives/chart-accessibility.js';
+import { type ChartCurve, type SeriesColorIndex } from '../../utils/chart.js';
+type Layer = 'svg' | 'series' | 'overlay' | 'header';
+export type MirrorAreaChartStatus = 'loading' | 'ready';
+export type MirrorAreaChartSide = 'top' | 'bottom';
+export type MirrorAreaChartDatum = Record<string, string | number | null | undefined>;
+/** The row under the crosshair, for a header or a readout outside the chart. */
+export declare function useMirrorAreaChart(): {
+    activeIndex: number;
+    activePoint: MirrorAreaChartDatum | null;
+    xDataKey: string;
+};
+export interface MirrorAreaChartProps extends ViewProps, ChartAccessibilityProps<MirrorAreaChartDatum> {
+    className?: string;
+    /** The rows. Each one is a point along the x-axis. */
+    data: MirrorAreaChartDatum[];
+    /** Key holding the x label. Used by the axis and the readout. */
+    xDataKey?: string;
+    /**
+     * How much of the plot's height sits above the baseline, from `0` to `1`.
+     * Give the half you want read first the larger share.
+     */
+    split?: number;
+    /**
+     * Fix the top half's scale instead of deriving it from the data. Only the
+     * upper end is used: the baseline is always zero.
+     */
+    topDomain?: [number, number];
+    /** Fix the bottom half's scale. Only the upper end is used. */
+    bottomDomain?: [number, number];
+    /** `monotone` never overshoots between points; `linear` joins them straight. */
+    curve?: ChartCurve;
+    /**
+     * `loading` holds the bands flat on the baseline and grows them out when it
+     * turns `ready`. Add a `MirrorAreaChart.Skeleton` to show something meanwhile.
+     */
+    status?: MirrorAreaChartStatus;
+    /** Width ÷ height. */
+    aspectRatio?: number;
+    /** Milliseconds for the bands to grow out on mount. */
+    animationDuration?: number;
+    /** Milliseconds for either scale to settle after the data changes. */
+    domainDuration?: number;
+    /**
+     * The point under the crosshair as it moves, and `-1`/`null` when it lifts.
+     * Fires when the index changes, not per frame.
+     */
+    onActiveIndexChange?: (index: number, datum: MirrorAreaChartDatum | null) => void;
+    /** Drop the axis padding so the bands reach the edges, for a sparkline. */
+    compact?: boolean;
+    children?: ReactNode;
+}
+/** Imperative handle: re-run the reveal on demand, for a "replay" control. */
+export interface MirrorAreaChartHandle {
+    replay: () => void;
+}
+export interface MirrorAreaChartGridProps {
+    /** `dots` is a field of points; `lines` is dashed rules across each half. */
+    variant?: 'dots' | 'lines';
+    /** Distance between dots, or how many rules each half gets. */
+    spacing?: number;
+    color?: string;
+    opacity?: number;
+}
+/**
+ * The texture behind the bands. Dots by default, which mark the plot's extent
+ * without drawing lines that compete with the baseline.
+ */
+declare function MirrorAreaChartGrid({ variant, spacing, color, opacity }: MirrorAreaChartGridProps): import("react").JSX.Element;
+declare namespace MirrorAreaChartGrid {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface MirrorAreaChartBaselineProps {
+    color?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/**
+ * The line both halves grow away from. Declare it after the areas so it is
+ * drawn over their bases.
+ */
+declare function MirrorAreaChartBaseline({ color, strokeWidth, opacity }: MirrorAreaChartBaselineProps): import("react").JSX.Element;
+declare namespace MirrorAreaChartBaseline {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface MirrorAreaChartAreaProps {
+    /** Column in the data holding this series' values. */
+    dataKey: string;
+    /** Which half it is drawn in. */
+    side?: MirrorAreaChartSide;
+    /** The name shown by the readout and the legend. Defaults to `dataKey`. */
+    label?: string;
+    /** Explicit colour. Defaults to the `--color-chart-*` token for `colorIndex`. */
+    color?: string;
+    /** Which of the five chart tokens to take. */
+    colorIndex?: SeriesColorIndex;
+    /**
+     * Draw it in the muted foreground colour instead, for a total that the
+     * coloured areas are parts of.
+     */
+    muted?: boolean;
+    /** Opacity of the fill at the band's outer edge. */
+    fillOpacity?: number;
+    /** Opacity of the fill at the baseline. Defaults to `fillOpacity`, a flat fill. */
+    gradientToOpacity?: number;
+    /** Draw the line along the band's outer edge. */
+    showLine?: boolean;
+    /** Thickness of that line. */
+    strokeWidth?: number;
+}
+/**
+ * One band, growing away from the baseline on its side. Areas on one side
+ * overlay in declaration order, so a whole declared first is drawn behind a
+ * part of it declared second.
+ */
+declare function MirrorAreaChartArea({ dataKey, side, label, color, colorIndex, muted, fillOpacity, gradientToOpacity, showLine, strokeWidth, }: MirrorAreaChartAreaProps): import("react").JSX.Element;
+declare namespace MirrorAreaChartArea {
+    var displayName: string;
+    var layer: Layer;
+    var area: true;
+}
+export interface MirrorAreaChartSkeletonProps {
+    /** Milliseconds for one pass of the sweep. */
+    duration?: number;
+    color?: string;
+}
+/**
+ * The loading state: a low band either side of the baseline with a highlight
+ * travelling across it. Flat, so it says where the bands will be and nothing
+ * about their shape.
+ */
+declare function MirrorAreaChartSkeleton({ duration, color }: MirrorAreaChartSkeletonProps): import("react").JSX.Element | null;
+declare namespace MirrorAreaChartSkeleton {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface MirrorAreaChartXAxisProps {
+    ticks?: number;
+    format?: (datum: MirrorAreaChartDatum, index: number) => string;
+    className?: string;
+}
+/** The x labels. Real text, so they follow the theme's font and text scaling. */
+declare function MirrorAreaChartXAxis({ ticks, format, className }: MirrorAreaChartXAxisProps): import("react").JSX.Element;
+declare namespace MirrorAreaChartXAxis {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface MirrorAreaChartYAxisProps {
+    /** Format a value in the top half. */
+    formatTop?: (value: number) => string;
+    /** Format a value in the bottom half. */
+    formatBottom?: (value: number) => string;
+    className?: string;
+}
+/**
+ * Three labels down the side: the top half's maximum, zero on the baseline,
+ * and the bottom half's maximum. Two scales need two labels, and a column of
+ * evenly spaced numbers would suggest one.
+ */
+declare function MirrorAreaChartYAxis({ formatTop, formatBottom, className }: MirrorAreaChartYAxisProps): import("react").JSX.Element;
+declare namespace MirrorAreaChartYAxis {
+    var displayName: string;
+    var layer: Layer;
+    var axis: "y";
+}
+export interface MirrorAreaChartTooltipProps {
+    /** Colour of the crosshair and the dot. Defaults to the foreground token. */
+    color?: string;
+    /** Format one series' value. Defaults to a compact number. */
+    formatValue?: (value: number, key: string) => string;
+    /** Format the readout's heading from the row. Defaults to the value at xDataKey. */
+    formatX?: (datum: MirrorAreaChartDatum) => string;
+    /**
+     * One line to show instead of a row per series — "1,120 jobs · 78% high".
+     * Use it when the series only make sense read together.
+     */
+    formatSummary?: (datum: MirrorAreaChartDatum) => string;
+    className?: string;
+}
+/**
+ * A dashed crosshair, a dot on the outer edge of the top half, and a readout
+ * beside them. The hit area is the whole plot.
+ */
+declare function MirrorAreaChartTooltip({ color, formatValue, formatX, formatSummary, className, }: MirrorAreaChartTooltipProps): import("react").JSX.Element | null;
+declare namespace MirrorAreaChartTooltip {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface MirrorAreaChartLegendProps extends ViewProps {
+    className?: string;
+}
+/** A swatch and a name per area, top half first. */
+declare function MirrorAreaChartLegend({ className, ...props }: MirrorAreaChartLegendProps): import("react").JSX.Element | null;
+declare namespace MirrorAreaChartLegend {
+    var displayName: string;
+    var layer: Layer;
+}
+export interface MirrorAreaChartHeaderProps extends ViewProps {
+    className?: string;
+    /** Small line above the value — what the chart is of. */
+    title?: string;
+    /** The readout. The largest thing on the card, and the first thing read. */
+    value?: string;
+    /** One muted line under the value — a period, a comparison, a total. */
+    caption?: string;
+    /** Draw a swatch and a name per area along the trailing edge. */
+    legend?: boolean;
+    /** Trailing slot — a control, a badge, a range picker. Wins over `legend`. */
+    children?: ReactNode;
+}
+/**
+ * The strip above the plot: what the chart is of and what it currently reads.
+ * The value is not derived here — pass the formatted string, from
+ * `onActiveIndexChange` if it follows the finger.
+ */
+declare function MirrorAreaChartHeader({ className, title, value, caption, legend, children, ...props }: MirrorAreaChartHeaderProps): import("react").JSX.Element;
+declare namespace MirrorAreaChartHeader {
+    var displayName: string;
+    var layer: Layer;
+}
+export declare const MirrorAreaChart: import("react").ForwardRefExoticComponent<MirrorAreaChartProps & import("react").RefAttributes<MirrorAreaChartHandle>> & {
+    Header: typeof MirrorAreaChartHeader;
+    Grid: typeof MirrorAreaChartGrid;
+    Area: typeof MirrorAreaChartArea;
+    Baseline: typeof MirrorAreaChartBaseline;
+    Skeleton: typeof MirrorAreaChartSkeleton;
+    XAxis: typeof MirrorAreaChartXAxis;
+    YAxis: typeof MirrorAreaChartYAxis;
+    Tooltip: typeof MirrorAreaChartTooltip;
+    Legend: typeof MirrorAreaChartLegend;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/components/mirror-area-chart/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/mirror-area-chart/index.tsx"],"names":[],"mappings":"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"}

package/lib/typescript/src/components/sankey-chart/index.d.ts

@@ -0,0 +1,307 @@
+/**
+ * SankeyChart — where a quantity came from and where it ended up.
+ *
+ * ```tsx
+ * <SankeyChart nodes={stages} links={flows}>
+ *   <SankeyChart.Header title="Traffic" value="128,400" />
+ *   <SankeyChart.Links />
+ *   <SankeyChart.Nodes />
+ *   <SankeyChart.Labels />
+ *   <SankeyChart.Tooltip />
+ * </SankeyChart>
+ * ```
+ *
+ * ## What it answers that the other charts do not
+ *
+ * Every other chart here takes one set of things and measures them. This one
+ * takes two and says how much of the first became the second. A treemap cuts a
+ * total into its parts, a funnel counts what survived each step, a waterfall
+ * carries a balance from one figure to another — none of them can say that
+ * *this* source fed *that* destination, because none of them draws a thing that
+ * has two ends.
+ *
+ * So the question to bring to it is a routing question. Which campaigns
+ * produced which signups; which budget lines paid for which departments; what
+ * the traffic that arrived on the landing page went on to do. If the answer
+ * does not need a source *and* a target, one of the simpler charts will read
+ * better at the same size.
+ *
+ * ## The ribbon is the reading
+ *
+ * A ribbon's thickness is its value, on one scale shared by the whole diagram,
+ * so a ribbon twice as thick is twice as much wherever it is on the page. That
+ * is the only quantity here: the horizontal distance a ribbon travels is the
+ * number of columns between its ends and means nothing else, and the vertical
+ * order within a column is chosen to keep the ribbons from crossing rather than
+ * to rank anything.
+ *
+ * A node's height is what passes through it — the larger of what arrives and
+ * what leaves, which are the same number unless some of it went nowhere. Where
+ * they differ, give the node an explicit `value` to pin it; the diagram cannot
+ * infer a loss it was never told about.
+ *
+ * ## Columns are the flow's, not the caller's
+ *
+ * Nothing about the order of the `nodes` array decides where a node is drawn. A
+ * node that receives from another has to be drawn after it or its ribbon would
+ * run backwards, so the columns come out of the links. `align` only settles the
+ * cases the flow leaves open, and the default pushes every node that feeds
+ * nothing into the last column, so the diagram ends on a straight edge of
+ * destinations instead of a ragged one.
+ *
+ * ## Bad rows are dropped rather than fatal
+ *
+ * Flow data is nearly always joined together from somewhere nobody in the room
+ * owns, and it arrives with rows that name a node that is not there, carry a
+ * zero, or close a loop. A loop in particular has no left-to-right reading at
+ * all. All of them are dropped and counted, and `onDropLinks` reports how many
+ * — so a screen can say "3 rows could not be drawn" instead of going blank or
+ * quietly showing less than it was given.
+ */
+import { type ReactNode } from 'react';
+import { type ViewProps } from 'react-native';
+import { type ChartAccessibilityProps } from '../../primitives/chart-accessibility.js';
+import { type SankeyAlign } from './sankey-layout.js';
+export type { SankeyAlign } from './sankey-layout.js';
+export type SankeyChartStatus = 'loading' | 'ready';
+export interface SankeyNode {
+    /** Stable key the links name. Must be unique; a repeat is ignored. */
+    id: string;
+    /** Name drawn beside the bar. Defaults to the id. */
+    label?: string;
+    /** Explicit colour, instead of the node's place in the palette. */
+    color?: string;
+    /**
+     * Pins what passes through the node, for a stage that loses some of what it
+     * received to somewhere the links do not describe. Left unset the node is
+     * worth the larger of what arrives and what leaves.
+     */
+    value?: number;
+}
+export interface SankeyLink {
+    /** `id` of the node it leaves. */
+    source: string;
+    /** `id` of the node it reaches. */
+    target: string;
+    /** How much travels. Zero, negative and non-finite rows are dropped. */
+    value: number;
+    /** Explicit colour, instead of taking the source node's. */
+    color?: string;
+}
+/** The selected node and what runs through it, for something drawn inside the chart. */
+export declare function useSankeyChart(): {
+    activeId: string | null;
+    activeNode: SankeyNode | null;
+    /** What passes through it — what the bar's height is drawn from. */
+    activeValue: number;
+    /** What arrives. Zero at a node the flow starts from. */
+    incoming: number;
+    /** What leaves. Zero at a node the flow ends at. */
+    outgoing: number;
+};
+export interface SankeyChartProps extends ViewProps, ChartAccessibilityProps<SankeyNode> {
+    className?: string;
+    /** The stages. Order does not decide position — the links do. */
+    nodes: SankeyNode[];
+    /** What travels between them. */
+    links: SankeyLink[];
+    /**
+     * How tall the diagram is drawn, in points.
+     *
+     * The width is the card's, but nothing in a flow says how deep it should be:
+     * a diagram of four nodes and one of forty are the same data at two heights,
+     * and which of them is right is a question about the screen.
+     */
+    height?: number;
+    /** How thick a node's bar is, in points. */
+    nodeWidth?: number;
+    /**
+     * The gap between two nodes in a column, in points.
+     *
+     * A maximum rather than a promise. A crowded column gives its spacing up
+     * before it gives up the height of its bars, because the bar is the reading.
+     */
+    nodePadding?: number;
+    /** Which column a node goes in where the flow leaves a choice. */
+    align?: SankeyAlign;
+    /** Relaxation rounds spent untangling the ribbons. */
+    iterations?: number;
+    /** How far a ribbon bends, `0` for a straight diagonal and `0.5` for an S. */
+    curve?: number;
+    /** The first hue. The rest of the palette follows from the theme's tokens. */
+    color?: string;
+    /** Milliseconds for one column to draw itself. */
+    animationDuration?: number;
+    /** Milliseconds between one column starting and the next. `0` for all at once. */
+    staggerDelay?: number;
+    /** `loading` draws a plain placeholder until the data arrives. */
+    status?: SankeyChartStatus;
+    /** Selected node. Leave unset to let the chart track it. */
+    activeId?: string | null;
+    /** Fires with the selected node's id, or `null` when the selection is cleared. */
+    onActiveIdChange?: (id: string | null) => void;
+    /**
+     * Fires with how many link rows could not be drawn — ones naming a node that
+     * is not there, carrying nothing, or closing a loop. `0` after a clean render,
+     * so a banner can be shown and taken away from the same signal.
+     */
+    onDropLinks?: (count: number) => void;
+    children?: ReactNode;
+}
+/** Imperative handle: re-run the entrance, for a "replay" control. */
+export interface SankeyChartHandle {
+    replay: () => void;
+}
+export interface SankeyChartLinksProps {
+    /** A ribbon's opacity at rest. */
+    opacity?: number;
+    /** A ribbon's opacity when its node is selected. */
+    activeOpacity?: number;
+    /** And when something else is. */
+    dimOpacity?: number;
+}
+/**
+ * The ribbons.
+ *
+ * Drawn before the bars so a bar sits on top of the flows that meet it, which
+ * is what gives a node a clean edge to arrive at instead of a fringe of ribbon
+ * ends poking through it.
+ *
+ * Translucent at rest, and that is not decoration. Ribbons cross — that is the
+ * shape of routed data — and an opaque one hides whatever passes under it, so
+ * the reader loses the smaller of every pair. At this opacity a crossing reads
+ * as two ribbons rather than as one with a notch in it.
+ */
+declare function SankeyChartLinks({ opacity, activeOpacity, dimOpacity, }: SankeyChartLinksProps): import("react").JSX.Element | null;
+declare namespace SankeyChartLinks {
+    var displayName: string;
+    var slot: "svg";
+}
+export interface SankeyChartNodesProps {
+    /** Corner radius on a node's bar, in points. */
+    radius?: number;
+    /** A bar's opacity when something else is selected. */
+    dimOpacity?: number;
+}
+/**
+ * The bars the ribbons run between.
+ *
+ * Solid where the ribbons are translucent, because a node is the one thing on
+ * the diagram that is not crossing anything else — it is the edge the flow
+ * arrives at, and it reads as an edge only if nothing shows through it.
+ */
+declare function SankeyChartNodes({ radius, dimOpacity }: SankeyChartNodesProps): import("react").JSX.Element | null;
+declare namespace SankeyChartNodes {
+    var displayName: string;
+    var slot: "svg";
+}
+export interface SankeyChartLabelsProps {
+    className?: string;
+    /** Format the figure beside a name. Defaults to a compact number. */
+    formatValue?: (value: number, node: SankeyNode) => string;
+    /** Show the figure under the name. */
+    showValue?: boolean;
+    /**
+     * Hide the name on a bar shorter than this, in points.
+     *
+     * A diagram of forty nodes has bars a few points tall, and forty names at
+     * that spacing overlap into a grey band that hides the flow behind it. The
+     * names that are dropped are the smallest ones, which is where the tooltip
+     * takes over.
+     */
+    minHeight?: number;
+}
+/**
+ * The names, and the press targets that go with them.
+ *
+ * Outside the bars rather than on them. A node's bar is as thick as it was
+ * asked to be — ten points by default — and no name fits inside ten points, so
+ * putting the name on the bar means widening every bar to suit the longest
+ * label and losing the width the ribbons need.
+ *
+ * Which side a name goes on is decided by the column: the last column reads
+ * inwards from the right edge, everything else outwards to the right. So the
+ * names stay inside the chart's box at both ends, instead of the leftmost and
+ * rightmost ones being clipped.
+ *
+ * The target is the label's row, not the bar. A node worth one percent of the
+ * flow is a two-point sliver and cannot be hit; the row it sits in can, and it
+ * is padded out to a proper target where the sliver is smaller than one.
+ */
+declare function SankeyChartLabels({ className, formatValue, showValue, minHeight, }: SankeyChartLabelsProps): import("react").JSX.Element | null;
+declare namespace SankeyChartLabels {
+    var displayName: string;
+    var slot: "overlay";
+}
+export interface SankeyChartTooltipProps {
+    className?: string;
+    /** Format the figures. Defaults to a compact number. */
+    formatValue?: (value: number) => string;
+}
+/**
+ * What the selected node carries: the total through it, and what that total is
+ * made of at each end.
+ *
+ * In and out are shown separately because they are the two readings a flow
+ * diagram is for, and they are only the same number when nothing was lost. A
+ * node where they differ is the interesting one on the whole chart, and a
+ * single total would hide exactly that.
+ *
+ * Anchored beside the node and clamped to the plot, so it never leaves the box
+ * it belongs to — a card half off the edge of a phone is a card nobody can read.
+ */
+declare function SankeyChartTooltip({ className, formatValue }: SankeyChartTooltipProps): import("react").JSX.Element | null;
+declare namespace SankeyChartTooltip {
+    var displayName: string;
+    var slot: "overlay";
+}
+export interface SankeyChartSkeletonProps {
+    color?: string;
+}
+/**
+ * The loading state: a few plain bars and the ribbons between them, carrying no
+ * values.
+ *
+ * Every bar the same height and every ribbon the same thickness, deliberately.
+ * A placeholder with varied thicknesses would be an invented routing, and a
+ * reader cannot tell an invented one from a real one until it changes under
+ * them — which is worse than showing nothing, because it is showing something
+ * wrong.
+ */
+declare function SankeyChartSkeleton({ color }: SankeyChartSkeletonProps): import("react").JSX.Element | null;
+declare namespace SankeyChartSkeleton {
+    var displayName: string;
+    var slot: "svg";
+}
+export interface SankeyChartHeaderProps extends ViewProps {
+    className?: string;
+    /** Small line above the value — what the flow is of. */
+    title?: string;
+    /** The readout. The largest thing on the card, and the first thing read. */
+    value?: string;
+    /** One muted line under the value — a period, a comparison, a caveat. */
+    caption?: string;
+    /** Trailing slot — a control, a badge, a range picker. */
+    children?: ReactNode;
+}
+/**
+ * The strip above the diagram: what the flow is of and what it totals.
+ *
+ * The value is not derived even though there are sources to add up, because the
+ * formatting is not the chart's to guess: 128400 is a count, a currency or a
+ * rate depending on what was routed.
+ */
+declare function SankeyChartHeader({ className, title, value, caption, children, ...props }: SankeyChartHeaderProps): import("react").JSX.Element;
+declare namespace SankeyChartHeader {
+    var displayName: string;
+    var slot: "header";
+}
+export declare const SankeyChart: import("react").ForwardRefExoticComponent<SankeyChartProps & import("react").RefAttributes<SankeyChartHandle>> & {
+    Header: typeof SankeyChartHeader;
+    Links: typeof SankeyChartLinks;
+    Nodes: typeof SankeyChartNodes;
+    Labels: typeof SankeyChartLabels;
+    Tooltip: typeof SankeyChartTooltip;
+    Skeleton: typeof SankeyChartSkeleton;
+};
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/components/sankey-chart/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/sankey-chart/index.tsx"],"names":[],"mappings":"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"}