jfs-components 0.0.72 → 0.0.73

package/src/components/DonutChart/DonutChart.tsx

@@ -0,0 +1,503 @@
+import React from 'react'
+import {
+    StyleSheet,
+    Text,
+    View,
+    type StyleProp,
+    type TextStyle,
+    type ViewStyle,
+} from 'react-native'
+import Svg, { Circle } from 'react-native-svg'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { EMPTY_MODES, flattenChildren } from '../../utils/react-utils'
+
+/**
+ * Per-segment data definition for the data-driven `segments` prop.
+ *
+ * Each segment renders one arc on the donut ring. `value` controls the
+ * arc's angular share (its weight relative to the sum of all values).
+ * Use `modes` per segment to override the default `Appearance / DataViz`
+ * mode (the parent injects per-index defaults of `Senary`, `Primary`,
+ * `Secondary`, `Tertiary`, `Quaternary`, `Quinary`, then cycles).
+ */
+export type DonutChartSegmentData = {
+    /** Stable React key. */
+    key?: React.Key
+    /** Segment's angular weight (relative to the sum of all segment values). */
+    value: number
+    /** Hard-override the segment color. Bypasses `dataViz/bg` token resolution. */
+    color?: string
+    /**
+     * Per-segment design token mode overrides. Merged on top of parent
+     * `modes` and the per-index `Appearance / DataViz` defaults.
+     */
+    modes?: Record<string, any>
+    /** Per-segment accessibility label. */
+    accessibilityLabel?: string
+}
+
+export type DonutChartProps = {
+    /**
+     * Data-driven segment list. Used when no `children` slot is provided.
+     * Defaults to six equal segments themed across the
+     * `Appearance / DataViz` palette.
+     */
+    segments?: DonutChartSegmentData[]
+    /**
+     * Optional center value text (large/bold). Pass `null`/`false` to hide.
+     * Accepts a string or any `ReactNode` for full control.
+     */
+    value?: React.ReactNode
+    /**
+     * Optional center label text (smaller, beneath the value). Pass
+     * `null`/`false` to hide. Accepts a string or any `ReactNode`.
+     */
+    label?: React.ReactNode
+    /**
+     * Slot for custom center content. When provided, it replaces the
+     * default `value`/`label` text wrap entirely.
+     */
+    children?: React.ReactNode
+    /** Outer diameter in px. Defaults to 194 (matching the Figma reference). */
+    size?: number
+    /**
+     * Ring stroke width in px. Defaults to 18% of `size` so the donut keeps
+     * the same visual proportions across sizes.
+     */
+    strokeWidth?: number
+    /**
+     * Visual gap between adjacent segments expressed in degrees of arc.
+     * Defaults to 0 (segments touch). Use small values (1–4°) for
+     * separation when many segments are present.
+     */
+    gap?: number
+    /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+    modes?: Record<string, any>
+    /** Override container styles. */
+    style?: StyleProp<ViewStyle>
+    /** Override default value text styles. */
+    valueStyle?: StyleProp<TextStyle>
+    /** Override default label text styles. */
+    labelStyle?: StyleProp<TextStyle>
+    /** Accessibility label announced for the whole donut chart. */
+    accessibilityLabel?: string
+}
+
+const DEFAULT_APPEARANCE_CYCLE = [
+    'Senary',
+    'Primary',
+    'Secondary',
+    'Tertiary',
+    'Quaternary',
+    'Quinary',
+] as const
+
+const DEFAULT_SEGMENTS: DonutChartSegmentData[] = [
+    { value: 1 },
+    { value: 1 },
+    { value: 1 },
+    { value: 1 },
+    { value: 1 },
+    { value: 1 },
+]
+
+const STROKE_WIDTH_RATIO = 18 / 194
+
+const toNumber = (value: unknown, fallback: number) => {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : fallback
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value)
+        return Number.isFinite(parsed) ? parsed : fallback
+    }
+    return fallback
+}
+
+const toFontWeight = (value: unknown, fallback: TextStyle['fontWeight']) => {
+    if (typeof value === 'number') {
+        return String(value) as TextStyle['fontWeight']
+    }
+    if (typeof value === 'string') {
+        return value as TextStyle['fontWeight']
+    }
+    return fallback
+}
+
+/**
+ * Compute the default `Appearance / DataViz` mode for a segment at `index`.
+ * Cycles through {@link DEFAULT_APPEARANCE_CYCLE} so any number of segments
+ * gets a sensible default (Senary, Primary, Secondary, Tertiary,
+ * Quaternary, Quinary, then repeats).
+ */
+function defaultAppearanceFor(index: number) {
+    return DEFAULT_APPEARANCE_CYCLE[index % DEFAULT_APPEARANCE_CYCLE.length]
+}
+
+/**
+ * Resolve a single segment's stroke color through the design tokens. Honors
+ * any explicit `color` override, then falls back to `dataViz/bg` for the
+ * supplied `modes`, then to the Figma reference purple.
+ */
+function resolveSegmentColor(
+    color: string | undefined,
+    modes: Record<string, any>
+): string {
+    if (color) return color
+    return ((getVariableByName('dataViz/bg', modes) as string | null) ?? '#5d00b5')
+}
+
+/**
+ * Coerce a slot child into a `DonutChartSegmentData` so the rendering path
+ * is uniform. Reads `value`, `color`, `modes` and `accessibilityLabel`
+ * from the child's props and ignores anything else.
+ */
+function segmentDataFromChild(
+    child: React.ReactElement,
+    fallbackKey: React.Key
+): DonutChartSegmentData {
+    const props = (child.props as any) ?? {}
+    return {
+        key: child.key ?? fallbackKey,
+        value: toNumber(props.value, 1),
+        color: typeof props.color === 'string' ? props.color : undefined,
+        modes: props.modes,
+        accessibilityLabel: props.accessibilityLabel,
+    }
+}
+
+type DonutChartSegmentProps = {
+    /** Angular weight relative to the sum of sibling segment values. */
+    value: number
+    /** Hard-override segment color (bypasses tokens). */
+    color?: string
+    /**
+     * Design token modes for the segment. Merged with parent `modes` and
+     * the per-index `Appearance / DataViz` defaults.
+     */
+    modes?: Record<string, any>
+    /** Per-segment accessibility label. */
+    accessibilityLabel?: string
+}
+
+/**
+ * Inert helper used purely to author donut segments declaratively as
+ * `DonutChart.Segment` slot children. The parent reads its props and
+ * renders the actual SVG arcs — this component never renders anything by
+ * itself.
+ */
+function DonutChartSegment(_: DonutChartSegmentProps) {
+    return null
+}
+
+/**
+ * `DonutChart` renders a circular ring split into categorical segments.
+ * It is the segmented counterpart of `CircularProgressBar`: there is **no
+ * track background** behind the segments — the colored ring *is* the
+ * data, and each slice is a sibling category rather than a directional or
+ * temporal value.
+ *
+ * The default 6-segment layout receives per-index `Appearance / DataViz`
+ * defaults (segment 1 → `Senary`, 2 → `Primary`, 3 → `Secondary`, 4 →
+ * `Tertiary`, 5 → `Quaternary`, 6 → `Quinary`) so the wheel reads as one
+ * concept split into six color-coded categories. Override `modes` per
+ * segment to remix appearances, or set `Emphasis / DataViz` on the
+ * parent `modes` to dim or brighten the whole wheel at once.
+ *
+ * @component
+ * @param {DonutChartProps} props
+ */
+function DonutChart({
+    segments,
+    value,
+    label,
+    children,
+    size = 194,
+    strokeWidth: strokeWidthProp,
+    gap = 0,
+    modes: propModes = EMPTY_MODES,
+    style,
+    valueStyle,
+    labelStyle,
+    accessibilityLabel,
+}: DonutChartProps) {
+    const { modes: globalModes } = useTokens()
+    const modes = { ...globalModes, ...propModes }
+
+    const strokeWidth = Math.max(
+        1,
+        toNumber(strokeWidthProp, Math.max(1, size * STROKE_WIDTH_RATIO))
+    )
+    const radius = Math.max(0, (size - strokeWidth) / 2)
+    const center = size / 2
+    const circumference = 2 * Math.PI * radius
+    const gapLength = (Math.max(0, gap) / 360) * circumference
+
+    const slotChildren = flattenChildren(children).filter((child) =>
+        React.isValidElement(child)
+    ) as React.ReactElement[]
+
+    const slotSegmentChildren = slotChildren.filter(
+        (child) => child.type === DonutChartSegment
+    )
+
+    let resolvedSegments: DonutChartSegmentData[]
+    if (slotSegmentChildren.length > 0) {
+        resolvedSegments = slotSegmentChildren.map((child, index) =>
+            segmentDataFromChild(child, `segment-${index}`)
+        )
+    } else if (segments && segments.length > 0) {
+        resolvedSegments = segments
+    } else {
+        resolvedSegments = DEFAULT_SEGMENTS
+    }
+
+    const totalValue = resolvedSegments.reduce(
+        (sum, segment) => sum + Math.max(0, toNumber(segment.value, 0)),
+        0
+    )
+    const hasData = totalValue > 0 && resolvedSegments.length > 0
+
+    const arcs = hasData
+        ? buildArcs({
+              segments: resolvedSegments,
+              totalValue,
+              circumference,
+              gapLength,
+              modes,
+          })
+        : []
+
+    const customCenterChildren = slotChildren.filter(
+        (child) => child.type !== DonutChartSegment
+    )
+    const hasChildrenSlot = customCenterChildren.length > 0
+
+    const showValueLabel = !hasChildrenSlot && shouldRenderText(value)
+    const showLabel = !hasChildrenSlot && shouldRenderText(label)
+
+    const valueColor =
+        (getVariableByName('donutChart/value/color', modes) as string | null) ??
+        (getVariableByName('value/fg', modes) as string | null) ??
+        '#000000'
+    const valueFontFamily =
+        (getVariableByName('donutChart/value/fontFamily', modes) as string | null) ??
+        (getVariableByName('value/fontFamily', modes) as string | null) ??
+        'JioType Var'
+    const valueFontSize = toNumber(
+        getVariableByName('donutChart/value/fontSize', modes) ??
+            getVariableByName('value/fontSize', modes),
+        29
+    )
+    const valueLineHeight = toNumber(
+        getVariableByName('donutChart/value/lineHeight', modes) ??
+            getVariableByName('value/lineHeight', modes),
+        29
+    )
+    const valueFontWeight = toFontWeight(
+        getVariableByName('donutChart/value/fontWeight', modes) ??
+            getVariableByName('value/fontWeight', modes),
+        '900'
+    )
+
+    const labelColor =
+        (getVariableByName('donutChart/label/color', modes) as string | null) ??
+        (getVariableByName('label/fg', modes) as string | null) ??
+        '#000000'
+    const labelFontFamily =
+        (getVariableByName('donutChart/label/fontFamily', modes) as string | null) ??
+        (getVariableByName('label/fontFamily', modes) as string | null) ??
+        'JioType Var'
+    const labelFontSize = toNumber(
+        getVariableByName('donutChart/label/fontSize', modes) ??
+            getVariableByName('label/fontSize', modes),
+        12
+    )
+    const labelLineHeight = toNumber(
+        getVariableByName('donutChart/label/lineHeight', modes) ??
+            getVariableByName('label/lineHeight', modes),
+        15.6
+    )
+    const labelFontWeight = toFontWeight(
+        getVariableByName('donutChart/label/fontWeight', modes) ??
+            getVariableByName('label/fontWeight', modes),
+        '400'
+    )
+
+    const textWrapGap = toNumber(
+        getVariableByName('donutChart/textWrap/gap', modes) ??
+            getVariableByName('textWrap/gap', modes),
+        7
+    )
+
+    const containerStyle: ViewStyle = {
+        alignItems: 'center',
+        height: size,
+        justifyContent: 'center',
+        position: 'relative',
+        width: size,
+    }
+
+    return (
+        <View
+            accessibilityRole="image"
+            accessibilityLabel={accessibilityLabel}
+            style={[containerStyle, style]}
+        >
+            <Svg width={size} height={size} viewBox={`0 0 ${size} ${size}`}>
+                {arcs.map((arc) => (
+                    <Circle
+                        key={arc.key}
+                        cx={center}
+                        cy={center}
+                        r={radius}
+                        stroke={arc.color}
+                        strokeWidth={strokeWidth}
+                        fill="none"
+                        strokeDasharray={arc.dashArray}
+                        strokeDashoffset={arc.dashOffset}
+                        strokeLinecap="butt"
+                        rotation="-90"
+                        originX={center}
+                        originY={center}
+                    />
+                ))}
+            </Svg>
+
+            {hasChildrenSlot ? (
+                <View pointerEvents="box-none" style={StyleSheet.absoluteFill as ViewStyle}>
+                    <View style={styles.centerSlot}>{customCenterChildren}</View>
+                </View>
+            ) : showValueLabel || showLabel ? (
+                <View
+                    pointerEvents="none"
+                    style={[styles.centerSlot, { gap: textWrapGap }]}
+                >
+                    {showValueLabel ? (
+                        <Text
+                            style={[
+                                {
+                                    color: valueColor,
+                                    fontFamily: valueFontFamily,
+                                    fontSize: valueFontSize,
+                                    lineHeight: valueLineHeight,
+                                    fontWeight: valueFontWeight,
+                                    textAlign: 'center',
+                                },
+                                valueStyle,
+                            ]}
+                            numberOfLines={1}
+                        >
+                            {value}
+                        </Text>
+                    ) : null}
+                    {showLabel ? (
+                        <Text
+                            style={[
+                                {
+                                    color: labelColor,
+                                    fontFamily: labelFontFamily,
+                                    fontSize: labelFontSize,
+                                    lineHeight: labelLineHeight,
+                                    fontWeight: labelFontWeight,
+                                    textAlign: 'center',
+                                },
+                                labelStyle,
+                            ]}
+                            numberOfLines={1}
+                        >
+                            {label}
+                        </Text>
+                    ) : null}
+                </View>
+            ) : null}
+        </View>
+    )
+}
+
+function shouldRenderText(node: React.ReactNode): boolean {
+    return node !== undefined && node !== null && node !== false && node !== ''
+}
+
+type ArcDescriptor = {
+    key: React.Key
+    color: string
+    dashArray: string
+    dashOffset: number
+}
+
+/**
+ * Convert the resolved segment list into a list of stroke-dasharray /
+ * stroke-dashoffset descriptors that can be drawn as SVG `Circle`s. Each
+ * arc's length is its share of `circumference`, and its rotational offset
+ * is the cumulative offset of all preceding segments. Visual gaps are
+ * applied symmetrically — half a gap is shaved from each end of the arc
+ * so the visible separation between two segments equals one full `gap`.
+ */
+function buildArcs({
+    segments,
+    totalValue,
+    circumference,
+    gapLength,
+    modes,
+}: {
+    segments: DonutChartSegmentData[]
+    totalValue: number
+    circumference: number
+    gapLength: number
+    modes: Record<string, any>
+}): ArcDescriptor[] {
+    const arcs: ArcDescriptor[] = []
+    const halfGap = gapLength / 2
+    let cumulativeOffset = 0
+
+    segments.forEach((segment, index) => {
+        const safeValue = Math.max(0, toNumber(segment.value, 0))
+        if (safeValue <= 0) {
+            return
+        }
+
+        const arcLength = (safeValue / totalValue) * circumference
+        const drawnLength = Math.max(0, arcLength - gapLength)
+        const segmentModes = {
+            ...modes,
+            'Appearance / DataViz': defaultAppearanceFor(index),
+            ...(segment.modes || {}),
+        }
+        const color = resolveSegmentColor(segment.color, segmentModes)
+
+        const dashArray = `${drawnLength} ${circumference - drawnLength}`
+        const dashOffset = -cumulativeOffset - halfGap
+
+        arcs.push({
+            key: segment.key ?? `segment-${index}`,
+            color,
+            dashArray,
+            dashOffset,
+        })
+
+        cumulativeOffset += arcLength
+    })
+
+    return arcs
+}
+
+const styles = StyleSheet.create({
+    centerSlot: {
+        alignItems: 'center',
+        bottom: 0,
+        justifyContent: 'center',
+        left: 0,
+        position: 'absolute',
+        right: 0,
+        top: 0,
+    },
+})
+
+DonutChart.Segment = DonutChartSegment
+
+export { DonutChartSegment }
+export type { DonutChartSegmentProps }
+
+export default DonutChart