blend-native 0.0.1-beta.0 → 0.0.1-beta.2

package/src/components/SankeyChart/SankeyChart.tsx

@@ -0,0 +1,303 @@
+import { forwardRef, useContext, useMemo, useState, useCallback } from 'react'
+import { View } from 'react-native'
+import type { View as RNView, LayoutChangeEvent } from 'react-native'
+import Svg, { Path, Rect, Text as SvgText, G } from 'react-native-svg'
+import type { ChartV2TokensType } from '@juspay/blend-design-system/node'
+import { useNativeTokens } from '../../theme/useNativeTokens'
+import { BlendNativeThemeContext } from '../../theme/BlendNativeProvider'
+import { parseDimension } from '../../adapters/cssStringAdapter'
+import { ChartContainer } from '../Chart'
+import { ChartNoData } from '../Chart'
+import { ChartSkeleton } from '../Chart'
+import {
+    computeSankeyLayout,
+    buildRibbonPath,
+    getFocusSet,
+} from './sankeyChart.utils'
+import type { SankeyChartProps } from './sankeyChart.types'
+
+const DEFAULT_HEIGHT = 400
+const DEFAULT_NODE_WIDTH = 16
+const DEFAULT_NODE_GAP = 12
+const DEFAULT_CURVE_FACTOR = 0.5
+const MIN_NODE_HEIGHT = 4
+const LABEL_MAX_CHARS = 12
+
+/**
+ * SankeyChart — a flow visualization where ribbon width is proportional to
+ * `value`.
+ *
+ * Nodes are arranged in columns (explicit or topologically computed), and
+ * ribbons connect the right edge of a source node to the left edge of a target
+ * node. Tapping a node highlights its flow (in + out ribbons).
+ *
+ * Uses `react-native-svg` (a transitive dep of victory-native) for rendering.
+ * Styled from `CHARTSV2` tokens.
+ */
+const SankeyChart = forwardRef<RNView, SankeyChartProps>(function SankeyChart(
+    {
+        nodes,
+        links,
+        height = DEFAULT_HEIGHT,
+        nodeWidth = DEFAULT_NODE_WIDTH,
+        nodeGap = DEFAULT_NODE_GAP,
+        curveFactor = DEFAULT_CURVE_FACTOR,
+        focusBehavior = 'flow',
+        onPress,
+        selectedId: controlledSelectedId,
+        noData,
+        skeleton,
+        accessibilityLabel,
+        testID,
+        style,
+    },
+    ref
+) {
+    const tokens = useNativeTokens<ChartV2TokensType>('CHARTSV2')
+    const ct = tokens.chart
+    // SvgText does not inherit the RN font context — resolve the body role
+    // explicitly, like Chart.tsx does for Victory labels.
+    const { fontFamily: familyMap } = useContext(BlendNativeThemeContext)
+    const labelFontFamily = familyMap.body ?? undefined
+
+    const [measuredWidth, setMeasuredWidth] = useState<number | undefined>()
+    const onLayout = (event: LayoutChangeEvent) => {
+        const w = event.nativeEvent.layout.width
+        if (w > 0 && w !== measuredWidth) setMeasuredWidth(w)
+    }
+
+    // --- Selected node (controlled or uncontrolled) ----------------------
+    const isControlled = controlledSelectedId !== undefined
+    const [internalSelected, setInternalSelected] = useState<
+        string | undefined
+    >(undefined)
+    const selectedId = isControlled ? controlledSelectedId : internalSelected
+
+    const handleNodePress = useCallback(
+        (nodeId: string) => {
+            if (!isControlled) {
+                setInternalSelected((prev) =>
+                    prev === nodeId ? undefined : nodeId
+                )
+            }
+            onPress?.({ kind: 'node', id: nodeId })
+        },
+        [isControlled, onPress]
+    )
+
+    const handleLinkPress = useCallback(
+        (linkId: string) => {
+            onPress?.({ kind: 'link', id: linkId })
+        },
+        [onPress]
+    )
+
+    // --- Layout -----------------------------------------------------------
+    const layout = useMemo(
+        () =>
+            computeSankeyLayout(nodes, links, {
+                canvasHeight: height,
+                nodeWidth,
+                nodeGap,
+            }),
+        [nodes, links, height, nodeWidth, nodeGap]
+    )
+
+    const { positionedNodes, positionedLinks } = layout
+
+    // --- Focus set --------------------------------------------------------
+    const focusSet = useMemo(() => {
+        if (focusBehavior === 'none' || !selectedId) return null
+        return getFocusSet(selectedId, links, focusBehavior)
+    }, [selectedId, focusBehavior, links])
+
+    const isDimmed = (id: string, linkKey?: string): boolean => {
+        if (!focusSet) return false
+        if (linkKey) return !focusSet.has(linkKey)
+        return !focusSet.has(id)
+    }
+
+    // --- Column X positions -----------------------------------------------
+    const columnCount = useMemo(() => {
+        if (positionedNodes.length === 0) return 0
+        return Math.max(...positionedNodes.map((n) => n.columnIndex)) + 1
+    }, [positionedNodes])
+
+    // --- Skeleton ---------------------------------------------------------
+    if (skeleton?.show) {
+        return (
+            <ChartContainer ref={ref} style={style}>
+                <ChartSkeleton height={height} />
+            </ChartContainer>
+        )
+    }
+
+    // --- No-data ----------------------------------------------------------
+    if (nodes.length === 0 || links.length === 0) {
+        return (
+            <ChartContainer ref={ref} style={style}>
+                <ChartNoData
+                    title={noData?.title ?? 'No data available'}
+                    subtitle={
+                        noData?.subtitle ??
+                        'Data will appear here once available'
+                    }
+                />
+            </ChartContainer>
+        )
+    }
+
+    if (!measuredWidth) {
+        return (
+            <ChartContainer ref={ref} style={style}>
+                <View onLayout={onLayout} style={{ width: '100%', height }} />
+            </ChartContainer>
+        )
+    }
+
+    // Compute X position for each column. Spread columns evenly across the
+    // canvas width, leaving room for labels on the left and right.
+    // Rightmost column gets less label room because its labels go right
+    // (away from the canvas), not left — but we keep it symmetric for now.
+    const labelPadding = 96 // px reserved for labels on each side
+    const drawableWidth = Math.max(0, measuredWidth - labelPadding * 2)
+    const columnSpacing =
+        columnCount > 1 ? drawableWidth / (columnCount - 1) : 0
+
+    const nodeX = (columnIndex: number) =>
+        labelPadding + columnIndex * columnSpacing
+
+    const labelColor = String(ct.xAxis.labels.color)
+    const titleColor = String(ct.xAxis.title.color)
+
+    return (
+        <ChartContainer ref={ref} style={style}>
+            <View
+                onLayout={onLayout}
+                style={{
+                    backgroundColor: String(ct.backgroundColor),
+                }}
+                accessibilityLabel={
+                    accessibilityLabel ??
+                    `Sankey chart with ${nodes.length} nodes and ${links.length} links`
+                }
+                accessibilityRole="summary"
+                testID={testID}
+            >
+                <Svg width={measuredWidth} height={height}>
+                    {/* --- Ribbons --- */}
+                    {positionedLinks.map((link, i) => {
+                        const srcNode = positionedNodes[link.sourceIndex]
+                        const tgtNode = positionedNodes[link.targetIndex]
+                        if (!srcNode || !tgtNode) return null
+
+                        const sx = nodeX(srcNode.columnIndex) + nodeWidth
+                        const tx = nodeX(tgtNode.columnIndex)
+                        const linkKey = `${link.source}→${link.target}`
+                        const dimmed = isDimmed(link.source, linkKey)
+
+                        const path = buildRibbonPath(
+                            sx,
+                            link.sourceY0,
+                            link.sourceY1,
+                            tx,
+                            link.targetY0,
+                            link.targetY1,
+                            curveFactor
+                        )
+
+                        return (
+                            <Path
+                                key={`link-${i}`}
+                                d={path}
+                                fill={link.resolvedColor}
+                                opacity={dimmed ? 0.12 : 0.5}
+                                onPress={
+                                    focusBehavior !== 'none'
+                                        ? () => handleLinkPress(linkKey)
+                                        : undefined
+                                }
+                            />
+                        )
+                    })}
+
+                    {/* --- Nodes --- */}
+                    {positionedNodes.map((node, i) => {
+                        const x = nodeX(node.columnIndex)
+                        const dimmed = isDimmed(node.id)
+                        const isSelected = selectedId === node.id
+
+                        return (
+                            <G key={`node-${i}`}>
+                                <Rect
+                                    x={x}
+                                    y={node.y}
+                                    width={nodeWidth}
+                                    height={Math.max(
+                                        node.height,
+                                        MIN_NODE_HEIGHT
+                                    )}
+                                    rx={2}
+                                    fill={node.color ?? '#2B7FFF'}
+                                    opacity={dimmed ? 0.3 : 1}
+                                    stroke={
+                                        isSelected
+                                            ? (node.color ?? '#2B7FFF')
+                                            : 'none'
+                                    }
+                                    strokeWidth={isSelected ? 2 : 0}
+                                    onPress={
+                                        focusBehavior !== 'none'
+                                            ? () => handleNodePress(node.id)
+                                            : undefined
+                                    }
+                                />
+                                {/* Node label */}
+                                {node.label ? (
+                                    <SvgText
+                                        x={
+                                            node.columnIndex === 0
+                                                ? x - 8
+                                                : x + nodeWidth + 8
+                                        }
+                                        y={
+                                            node.y +
+                                            Math.max(
+                                                node.height,
+                                                MIN_NODE_HEIGHT
+                                            ) /
+                                                2 +
+                                            4
+                                        }
+                                        fontSize={
+                                            parseDimension(
+                                                ct.xAxis.labels.fontSize as
+                                                    | string
+                                                    | number
+                                            ) ?? 11
+                                        }
+                                        fontFamily={labelFontFamily}
+                                        fontWeight={500}
+                                        fill={dimmed ? labelColor : titleColor}
+                                        textAnchor={
+                                            node.columnIndex === 0
+                                                ? 'end'
+                                                : 'start'
+                                        }
+                                    >
+                                        {node.label.length > LABEL_MAX_CHARS
+                                            ? `${node.label.slice(0, LABEL_MAX_CHARS)}…`
+                                            : node.label}
+                                    </SvgText>
+                                ) : null}
+                            </G>
+                        )
+                    })}
+                </Svg>
+            </View>
+        </ChartContainer>
+    )
+})
+
+SankeyChart.displayName = 'SankeyChart'
+export default SankeyChart

package/src/components/SankeyChart/index.ts

@@ -0,0 +1,6 @@
+export { default as SankeyChart } from './SankeyChart'
+export type {
+    SankeyChartProps,
+    SankeyNode,
+    SankeyLink,
+} from './sankeyChart.types'

package/src/components/SankeyChart/sankeyChart.types.ts

@@ -0,0 +1,81 @@
+import type { StyleProp, ViewStyle } from 'react-native'
+import type { SkeletonVariant } from '../Skeleton/Skeleton'
+
+export type SankeyNode = {
+    /** Unique id referenced by links. */
+    id: string
+    /**
+     * Optional column override (0, 1, 2, ...). Without it, computed from
+     * topological sort. Set this when you have a product-meaningful column
+     * layout ('Start' | 'Step 1' | 'Step 2' | 'End').
+     */
+    column?: number
+    /** Display name. Renders next to the node; longer names truncate. */
+    label?: string
+    /** Color override. Defaults per-column palette or per-node cycle. */
+    color?: string
+}
+
+export type SankeyLink = {
+    /** Source node id. */
+    source: string
+    /** Target node id. */
+    target: string
+    /** Ribbon width is proportional to `value`. */
+    value: number
+    /** Color override; defaults to the source node's color. */
+    color?: string
+}
+
+export type SankeyChartProps = {
+    nodes: SankeyNode[]
+    links: SankeyLink[]
+    /** Canvas height. Default 400. Width is measured via onLayout. */
+    height?: number
+    /** Node width in points. Default 16. */
+    nodeWidth?: number
+    /** Gap between nodes within a column, in points. Default 12. */
+    nodeGap?: number
+    /** Ribbon corner curvature (0 = straight, 1 = max curve). Default 0.5. */
+    curveFactor?: number
+    /** Highlight on tap: 'flow' | 'in' | 'out' | 'none'. Default 'flow'. */
+    focusBehavior?: 'flow' | 'in' | 'out' | 'none'
+    /** Callback for a node/ribbon press. */
+    onPress?: (target: { kind: 'node' | 'link'; id: string }) => void
+    /** Selected id (controlled focus). */
+    selectedId?: string
+    /** Empty state. */
+    noData?: { title?: string; subtitle?: string }
+    skeleton?: { show: boolean; variant?: SkeletonVariant }
+    accessibilityLabel?: string
+    testID?: string
+    style?: StyleProp<ViewStyle>
+}
+
+/** A node positioned by the layout step. */
+export type PositionedNode = SankeyNode & {
+    /** Column index (0-based). */
+    columnIndex: number
+    /** Y position of the node's top edge, in points. */
+    y: number
+    /** Node height in points. */
+    height: number
+    /** Total value flowing through this node (max of in/out). */
+    totalValue: number
+}
+
+/** A link positioned by the layout step. */
+export type PositionedLink = SankeyLink & {
+    /** Source node's positioned index. */
+    sourceIndex: number
+    /** Target node's positioned index. */
+    targetIndex: number
+    /** Y offset of the link's top edge at the source node. */
+    sourceY0: number
+    sourceY1: number
+    /** Y offset of the link's top/bottom edges at the target node. */
+    targetY0: number
+    targetY1: number
+    /** Resolved color. */
+    resolvedColor: string
+}

package/src/components/SankeyChart/sankeyChart.utils.ts

@@ -0,0 +1,287 @@
+import { paletteColor } from '../Chart/chart.types'
+import type {
+    SankeyNode,
+    SankeyLink,
+    PositionedNode,
+    PositionedLink,
+} from './sankeyChart.types'
+
+/**
+ * Assign nodes to columns. If a node has an explicit `column` override, use
+ * it; otherwise compute from topology — source nodes get column 0, targets
+ * get max(source column) + 1.
+ */
+export function computeColumns(
+    nodes: SankeyNode[],
+    links: SankeyLink[]
+): Map<string, number> {
+    const columns = new Map<string, number>()
+
+    // Seed from explicit overrides.
+    for (const node of nodes) {
+        if (node.column !== undefined) {
+            columns.set(node.id, node.column)
+        }
+    }
+
+    // Root nodes (no incoming links, no explicit column) get column 0.
+    // This must happen before the topological pass so sources are seeded.
+    for (const node of nodes) {
+        if (!columns.has(node.id)) {
+            const hasIncoming = links.some((l) => l.target === node.id)
+            if (!hasIncoming) {
+                columns.set(node.id, 0)
+            }
+        }
+    }
+
+    // Topological pass: propagate from sources.
+    // Iterate until stable (handles multi-hop chains).
+    let changed = true
+    let iterations = 0
+    const maxIterations = nodes.length + 1
+    while (changed && iterations < maxIterations) {
+        changed = false
+        iterations++
+        for (const link of links) {
+            const srcCol = columns.get(link.source)
+            if (srcCol === undefined) continue
+            const tgtCol = columns.get(link.target)
+            const newCol = srcCol + 1
+            if (tgtCol === undefined || tgtCol < newCol) {
+                columns.set(link.target, newCol)
+                changed = true
+            }
+        }
+    }
+
+    // Fallback: any still-unassigned node gets column 0.
+    for (const node of nodes) {
+        if (!columns.has(node.id)) {
+            columns.set(node.id, 0)
+        }
+    }
+
+    return columns
+}
+
+/** Total value flowing through a node (max of sum-in, sum-out). */
+export function computeNodeValue(nodeId: string, links: SankeyLink[]): number {
+    const inValue = links
+        .filter((l) => l.target === nodeId)
+        .reduce((sum, l) => sum + l.value, 0)
+    const outValue = links
+        .filter((l) => l.source === nodeId)
+        .reduce((sum, l) => sum + l.value, 0)
+    return Math.max(inValue, outValue, 0)
+}
+
+/**
+ * Deterministic Sankey layout.
+ *
+ * Nodes are sorted within a column by descending total value (so wide ribbons
+ * don't collide with narrow ones). Link endpoints are stacked within each
+ * node's height band, proportional to link value.
+ *
+ * Returns positioned nodes and links ready for SVG rendering.
+ */
+export function computeSankeyLayout(
+    nodes: SankeyNode[],
+    links: SankeyLink[],
+    opts: {
+        canvasHeight: number
+        nodeWidth?: number
+        nodeGap?: number
+    }
+): { positionedNodes: PositionedNode[]; positionedLinks: PositionedLink[] } {
+    const { canvasHeight, nodeGap = 12 } = opts
+
+    if (nodes.length === 0 || links.length === 0) {
+        return { positionedNodes: [], positionedLinks: [] }
+    }
+
+    const columns = computeColumns(nodes, links)
+
+    // Group nodes by column.
+    const maxColumn = Math.max(...columns.values())
+    const nodesByColumn: SankeyNode[][] = Array.from(
+        { length: maxColumn + 1 },
+        () => []
+    )
+    for (const node of nodes) {
+        const col = columns.get(node.id) ?? 0
+        nodesByColumn[col]?.push(node)
+    }
+
+    // Compute total value per node, then sort each column by descending value.
+    const nodeValues = new Map<string, number>()
+    for (const node of nodes) {
+        nodeValues.set(node.id, computeNodeValue(node.id, links))
+    }
+
+    for (const col of nodesByColumn) {
+        col.sort(
+            (a, b) => (nodeValues.get(b.id) ?? 0) - (nodeValues.get(a.id) ?? 0)
+        )
+    }
+
+    // Compute total value per column (sum of node values, not link values).
+    const columnTotals = nodesByColumn.map((col) =>
+        col.reduce((sum, n) => sum + (nodeValues.get(n.id) ?? 0), 0)
+    )
+
+    // Max column total drives the scale. All columns share the same scale
+    // so node heights are comparable across columns.
+    const maxColumnTotal = Math.max(...columnTotals, 1)
+
+    // Available height for nodes (subtract gaps).
+    const positionNodes = (): PositionedNode[] => {
+        const result: PositionedNode[] = []
+        for (let colIdx = 0; colIdx < nodesByColumn.length; colIdx++) {
+            const colNodes = nodesByColumn[colIdx]
+            const totalGaps = Math.max(0, colNodes.length - 1) * nodeGap
+            const availableHeight = canvasHeight - totalGaps
+            const scale = availableHeight / maxColumnTotal
+
+            let y = 0
+            for (const node of colNodes) {
+                const value = nodeValues.get(node.id) ?? 0
+                const nodeHeight = Math.max(value * scale, 4) // min 4pt
+                const colorIdx = nodes.indexOf(node)
+                result.push({
+                    ...node,
+                    columnIndex: colIdx,
+                    y,
+                    height: nodeHeight,
+                    totalValue: value,
+                    color: node.color ?? paletteColor(colorIdx),
+                })
+                y += nodeHeight + nodeGap
+            }
+        }
+        return result
+    }
+
+    const positionedNodes = positionNodes()
+
+    // Build a lookup: nodeId → positioned index.
+    const nodeIndex = new Map<string, number>()
+    positionedNodes.forEach((pn, i) => nodeIndex.set(pn.id, i))
+
+    // Position link endpoints within each node's height band.
+    // For each node, stack outgoing links top-to-bottom by value (descending).
+    // Same for incoming links.
+    const positionedLinks: PositionedLink[] = []
+
+    for (const link of links) {
+        const srcIdx = nodeIndex.get(link.source)
+        const tgtIdx = nodeIndex.get(link.target)
+        if (srcIdx === undefined || tgtIdx === undefined) continue
+
+        const srcNode = positionedNodes[srcIdx]
+        const tgtNode = positionedNodes[tgtIdx]
+
+        // Stack outgoing links at the source node.
+        const srcOutgoing = links
+            .filter((l) => l.source === link.source)
+            .sort((a, b) => b.value - a.value)
+        const srcOffset = srcOutgoing.indexOf(link)
+        const srcBefore = srcOutgoing
+            .slice(0, srcOffset)
+            .reduce((sum, l) => sum + l.value, 0)
+        const srcTotal = srcOutgoing.reduce((sum, l) => sum + l.value, 0)
+        const srcScale = srcNode.height / Math.max(srcTotal, 1)
+        const sourceY0 = srcNode.y + srcBefore * srcScale
+        const sourceY1 = srcNode.y + (srcBefore + link.value) * srcScale
+
+        // Stack incoming links at the target node.
+        const tgtIncoming = links
+            .filter((l) => l.target === link.target)
+            .sort((a, b) => b.value - a.value)
+        const tgtOffset = tgtIncoming.indexOf(link)
+        const tgtBefore = tgtIncoming
+            .slice(0, tgtOffset)
+            .reduce((sum, l) => sum + l.value, 0)
+        const tgtTotal = tgtIncoming.reduce((sum, l) => sum + l.value, 0)
+        const tgtScale = tgtNode.height / Math.max(tgtTotal, 1)
+        const targetY0 = tgtNode.y + tgtBefore * tgtScale
+        const targetY1 = tgtNode.y + (tgtBefore + link.value) * tgtScale
+
+        positionedLinks.push({
+            ...link,
+            sourceIndex: srcIdx,
+            targetIndex: tgtIdx,
+            sourceY0,
+            sourceY1,
+            targetY0,
+            targetY1,
+            resolvedColor: link.color ?? srcNode.color ?? paletteColor(srcIdx),
+        })
+    }
+
+    return { positionedNodes, positionedLinks }
+}
+
+/**
+ * Build an SVG cubic-bezier path for a Sankey ribbon.
+ *
+ * The ribbon connects the right edge of the source node to the left edge of
+ * the target node. `curveFactor` controls how far the control points are
+ * pulled horizontally — 0.5 gives the classic S-curve.
+ */
+export function buildRibbonPath(
+    sourceX: number,
+    sourceY0: number,
+    sourceY1: number,
+    targetX: number,
+    targetY0: number,
+    targetY1: number,
+    curveFactor: number
+): string {
+    const dx = Math.abs(targetX - sourceX)
+    const ctrlOffset = dx * curveFactor
+
+    const c1s = sourceX + ctrlOffset
+    const c1e = targetX - ctrlOffset
+
+    return (
+        `M ${sourceX} ${sourceY0} ` +
+        `C ${c1s} ${sourceY0}, ${c1e} ${targetY0}, ${targetX} ${targetY0} ` +
+        `L ${targetX} ${targetY1} ` +
+        `C ${c1e} ${targetY1}, ${c1s} ${sourceY1}, ${sourceX} ${sourceY1} ` +
+        `Z`
+    )
+}
+
+/**
+ * Get the IDs of links and nodes connected to a focused node.
+ * - `flow` = both in and out links + their endpoints
+ * - `in`   = only incoming links + their source endpoints
+ * - `out`  = only outgoing links + their target endpoints
+ */
+export function getFocusSet(
+    focusedNodeId: string,
+    links: SankeyLink[],
+    behavior: 'flow' | 'in' | 'out' = 'flow'
+): Set<string> {
+    const result = new Set<string>()
+    result.add(focusedNodeId)
+
+    for (const link of links) {
+        const isIn = link.target === focusedNodeId
+        const isOut = link.source === focusedNodeId
+        const matches =
+            behavior === 'flow'
+                ? isIn || isOut
+                : behavior === 'in'
+                  ? isIn
+                  : isOut // 'out'
+        if (matches) {
+            result.add(`${link.source}→${link.target}`)
+            result.add(link.source)
+            result.add(link.target)
+        }
+    }
+
+    return result
+}