jfs-components 0.0.71 → 0.0.73

package/src/components/CoverageBarComparison/CoverageBarComparison.tsx

@@ -0,0 +1,378 @@
+import React from 'react'
+import {
+  View,
+  Text,
+  type LayoutChangeEvent,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native'
+import Svg, { Rect } from 'react-native-svg'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { EMPTY_MODES } from '../../utils/react-utils'
+import MetricLegendItem from '../MetricLegendItem/MetricLegendItem'
+
+/**
+ * One entry in the {@link CoverageBarComparisonProps.bars} array.
+ *
+ * Each entry carries **both** the bar's data and its legend label, so the
+ * number of bars is intrinsically equal to the number of legend items.
+ * There is no separate `legends` prop — that is by design.
+ */
+export type CoverageBarComparisonItem = {
+  /** Stable React key. */
+  key?: React.Key
+  /**
+   * Numeric value used to scale the bar height proportionally. Bars share
+   * the chart area; the largest value (or {@link CoverageBarComparisonProps.max})
+   * fills the full bar area, smaller bars are proportionally shorter.
+   */
+  value: number
+  /**
+   * Text rendered above the bar (the Figma `Header` slot, e.g. `"₹1L (40%)"`).
+   * Omit to hide the header for this bar.
+   */
+  label?: React.ReactNode
+  /**
+   * Legend label rendered below the chart for this bar. Required: the legend
+   * row always has exactly one item per bar.
+   */
+  legend: React.ReactNode
+  /**
+   * Optional value text shown on the right of the legend (e.g. `"₹12,400"`).
+   * When omitted the legend renders only the colored dot + label.
+   */
+  legendValue?: React.ReactNode
+  /**
+   * Hard-override the bar fill color. Bypasses `valueBar/bar/background`
+   * resolution entirely — and is also used for the legend indicator dot, so
+   * the bar and its legend stay in sync.
+   */
+  color?: string
+  /**
+   * Per-bar design token mode overrides. Merged on top of the parent `modes`
+   * and the per-index `Emphasis / DataViz` defaults injected by the parent.
+   */
+  modes?: Record<string, any>
+  /** Per-bar accessibility label. */
+  accessibilityLabel?: string
+}
+
+export type CoverageBarComparisonProps = {
+  /**
+   * The bars to render. Each entry contains the value, the bar header label
+   * **and** the legend label, so the chart and the legend can never go out of
+   * sync. Defaults to a 2-item "Current vs Recommended" example matching the
+   * Figma reference.
+   */
+  bars?: CoverageBarComparisonItem[]
+  /**
+   * Maximum value used to scale the bars. Defaults to the largest
+   * `bars[i].value`. Pass an explicit `max` when bars represent absolute
+   * numbers and you want a fixed scale (e.g. `max=100` for percentages).
+   */
+  max?: number
+  /**
+   * Total height of the bar visualization area in px (includes the per-bar
+   * header label space). The largest bar fills `height - labelHeight - gap`.
+   * Default: `100`.
+   */
+  height?: number
+  /**
+   * Vertical gap (px) between the chart and the legend row. Default: `12`,
+   * matching the Figma reference.
+   */
+  legendGap?: number
+  /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+  modes?: Record<string, any>
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>
+  /** Style applied to the chart row (the bars container). */
+  chartStyle?: StyleProp<ViewStyle>
+  /** Style applied to the legend row. */
+  legendStyle?: StyleProp<ViewStyle>
+  /** Style applied to every value-label text above the bars. */
+  labelStyle?: StyleProp<TextStyle>
+  /** Accessibility label for the entire component. */
+  accessibilityLabel?: string
+}
+
+/**
+ * Default per-index `Emphasis / DataViz` modes applied when the caller does
+ * not provide its own override. Ascends Low → Medium → High so the natural
+ * "Current vs Recommended" two-bar story matches the Figma reference (left
+ * = lighter / Low, right = darker / High). Cycles for >3 bars.
+ */
+const DEFAULT_EMPHASIS_CYCLE = ['Low', 'Medium', 'High'] as const
+
+function defaultEmphasisFor(index: number, total: number) {
+  if (total <= 1) {
+    return 'High'
+  }
+  if (total === 2) {
+    return index === 0 ? 'Low' : 'High'
+  }
+  return DEFAULT_EMPHASIS_CYCLE[index % DEFAULT_EMPHASIS_CYCLE.length]
+}
+
+const DEFAULT_BARS: CoverageBarComparisonItem[] = [
+  { value: 40, label: '₹1L (40%)', legend: 'Current coverage' },
+  { value: 100, label: '₹2.5L (100%)', legend: 'Recommended coverage' },
+]
+
+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']
+): TextStyle['fontWeight'] => {
+  if (typeof value === 'number') {
+    return String(value) as TextStyle['fontWeight']
+  }
+  if (typeof value === 'string') {
+    return value as TextStyle['fontWeight']
+  }
+  return fallback
+}
+
+type BarShapeProps = {
+  height: number
+  color: string
+  radius: number
+}
+
+/**
+ * Bar shape rendered with `react-native-svg`. The wrapper measures its width
+ * via `onLayout` so the SVG can use concrete dimensions (RN SVG does not
+ * resolve percentage shape attributes when the parent SVG itself has a
+ * percentage `width`).
+ */
+function BarShape({ height, color, radius }: BarShapeProps) {
+  const [width, setWidth] = React.useState(0)
+  const handleLayout = React.useCallback((event: LayoutChangeEvent) => {
+    const next = event.nativeEvent.layout.width
+    setWidth((prev) => (prev === next ? prev : next))
+  }, [])
+
+  if (height <= 0) {
+    return <View onLayout={handleLayout} style={{ width: '100%', height: 0 }} />
+  }
+
+  const safeRadius = Math.max(0, Math.min(radius, width / 2, height / 2))
+
+  return (
+    <View
+      onLayout={handleLayout}
+      style={{ width: '100%', height, minWidth: 1 }}
+    >
+      {width > 0 ? (
+        <Svg width={width} height={height}>
+          <Rect
+            x={0}
+            y={0}
+            width={width}
+            height={height}
+            rx={safeRadius}
+            ry={safeRadius}
+            fill={color}
+          />
+        </Svg>
+      ) : null}
+    </View>
+  )
+}
+
+/**
+ * `CoverageBarComparison` renders a small vertical-bar chart that compares
+ * 2+ values side by side, with a legend row directly below where each item
+ * is intrinsically tied to one bar.
+ *
+ * Cohesiveness guarantees:
+ * - The legend row is **derived** from the same `bars` prop, so the count
+ *   and order can never desynchronise from the chart.
+ * - Each bar's color, its tokenized `Emphasis / DataViz` mode and its
+ *   legend indicator dot are the same value.
+ *
+ * Bars are drawn with `react-native-svg` (`<Rect>` with `rx`), and the
+ * fonts/spacing/colors are sourced from the Figma `valueBar/*` and
+ * `coverageBarComparison/*` tokens.
+ *
+ * @component
+ */
+function CoverageBarComparison({
+  bars = DEFAULT_BARS,
+  max,
+  height = 100,
+  legendGap = 12,
+  modes: propModes = EMPTY_MODES,
+  style,
+  chartStyle,
+  legendStyle,
+  labelStyle,
+  accessibilityLabel,
+}: CoverageBarComparisonProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = React.useMemo(
+    () => ({ ...globalModes, ...propModes }),
+    [globalModes, propModes]
+  )
+
+  const wrapGap = toNumber(getVariableByName('coverageBarComparison/wrap/gap', modes), 6)
+  const valueBarGap = toNumber(getVariableByName('valueBar/gap', modes), 4)
+  const barRadius = toNumber(getVariableByName('valueBar/bar/radius', modes), 10)
+
+  const fontFamily =
+    (getVariableByName('valueBar/fontFamily', modes) as string | null) ?? 'JioType Var'
+  const fontSize = toNumber(getVariableByName('valueBar/fontSize', modes), 12)
+  const lineHeight = toNumber(getVariableByName('valueBar/lineHeight', modes), 16)
+  const fontWeight = toFontWeight(getVariableByName('valueBar/fontWeight', modes), '700')
+  const foreground =
+    (getVariableByName('valueBar/foreground', modes) as string | null) ?? '#000000'
+
+  const labelHeight = lineHeight
+  const barAreaHeight = Math.max(0, height - labelHeight - valueBarGap)
+
+  const total = bars.length
+  const computedMax =
+    max ?? bars.reduce((acc, bar) => Math.max(acc, bar.value), 0)
+  const safeMax = computedMax > 0 ? computedMax : 1
+
+  const resolvedBars = React.useMemo(
+    () =>
+      bars.map((bar, index) => {
+        const barModes = {
+          ...modes,
+          'Emphasis / DataViz': defaultEmphasisFor(index, total),
+          ...(bar.modes || {}),
+        }
+        const ratio = Math.max(0, Math.min(1, bar.value / safeMax))
+        const tokenColor =
+          (getVariableByName('valueBar/bar/background', barModes) as string | null) ??
+          '#c9b7ff'
+        const bgColor = bar.color ?? tokenColor
+        return {
+          original: bar,
+          index,
+          barModes,
+          ratio,
+          bgColor,
+        }
+      }),
+    [bars, modes, safeMax, total]
+  )
+
+  const computedLabelStyle: TextStyle = {
+    color: foreground,
+    fontFamily,
+    fontSize,
+    lineHeight,
+    fontWeight,
+    textAlign: 'center',
+  }
+
+  const defaultAccessibilityLabel =
+    accessibilityLabel ??
+    `Comparison of ${total} bar${total === 1 ? '' : 's'}: ` +
+      bars
+        .map((bar, i) => {
+          const legend = typeof bar.legend === 'string' ? bar.legend : `bar ${i + 1}`
+          return `${legend} ${bar.value}`
+        })
+        .join(', ')
+
+  return (
+    <View
+      accessibilityLabel={defaultAccessibilityLabel}
+      style={[{ width: '100%' }, style]}
+    >
+      <View
+        accessibilityRole="image"
+        style={[
+          {
+            flexDirection: 'row',
+            alignItems: 'flex-end',
+            height,
+            gap: wrapGap,
+            width: '100%',
+          },
+          chartStyle,
+        ]}
+      >
+        {resolvedBars.map(({ original, index, ratio, bgColor }) => {
+          const barHeightPx = Math.max(0, barAreaHeight * ratio)
+          const valueBarTotalHeight = labelHeight + valueBarGap + barHeightPx
+          const hasLabel =
+            original.label !== undefined && original.label !== null && original.label !== false
+
+          return (
+            <View
+              key={original.key ?? `bar-${index}`}
+              accessibilityLabel={original.accessibilityLabel}
+              style={{
+                flex: 1,
+                flexDirection: 'column',
+                alignItems: 'stretch',
+                justifyContent: 'flex-end',
+                height: valueBarTotalHeight,
+                gap: valueBarGap,
+                minWidth: 1,
+              }}
+            >
+              {hasLabel ? (
+                <Text
+                  numberOfLines={1}
+                  style={[computedLabelStyle, labelStyle]}
+                >
+                  {original.label}
+                </Text>
+              ) : null}
+
+              <BarShape height={barHeightPx} color={bgColor} radius={barRadius} />
+            </View>
+          )
+        })}
+      </View>
+
+      <View
+        style={[
+          {
+            marginTop: legendGap,
+            flexDirection: 'row',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            width: '100%',
+          },
+          legendStyle,
+        ]}
+      >
+        {resolvedBars.map(({ original, index, barModes, bgColor }) => {
+          const indicatorOverride = original.color ? bgColor : undefined
+          return (
+            <MetricLegendItem
+              key={original.key ?? `legend-${index}`}
+              label={original.legend}
+              value={original.legendValue}
+              modes={barModes}
+              {...(indicatorOverride !== undefined
+                ? { indicatorColor: indicatorOverride }
+                : {})}
+              style={{ flex: 1, minWidth: 0 }}
+            />
+          )
+        })}
+      </View>
+    </View>
+  )
+}
+
+export default CoverageBarComparison

package/src/components/CoverageRing/CoverageRing.tsx

@@ -0,0 +1,225 @@
+import React from 'react'
+import {
+  View,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
+import Button, { type ButtonProps } from '../Button/Button'
+import CircularProgressBar from '../CircularProgressBar/CircularProgressBar'
+
+type CoverageRingBaseProps = Omit<
+  React.ComponentProps<typeof View>,
+  'children' | 'style'
+>
+
+export type CoverageRingProps = CoverageRingBaseProps & {
+  /**
+   * Current count (numerator). Together with `total`, drives both the ring
+   * progress and the default `valueLabel` (`"{value} of {total}"`). Clamped
+   * to `[0, total]`.
+   */
+  value?: number
+  /**
+   * Maximum count (denominator). Drives the ring fill ratio along with
+   * `value`. Must be greater than 0; a non-positive total collapses to 0%.
+   */
+  total?: number
+  /**
+   * Small caption rendered above the value inside the ring (e.g. "Benefits
+   * availed"). Maps to the Figma `circularProgressBar/supportText/*` tokens.
+   */
+  supportText?: string
+  /**
+   * Optional override for the formatted value rendered inside the ring.
+   * Defaults to `"{value} of {total}"` so the visual matches the Figma
+   * "Coverage Ring" reference.
+   */
+  valueLabel?: string
+  /**
+   * Visible label of the default action button. Ignored when `action` is
+   * provided. Defaults to `"Learn more"` to match the Figma reference.
+   */
+  actionLabel?: string
+  /** Press handler for the default action button. */
+  onActionPress?: () => void
+  /**
+   * Forward extra props to the default action button (e.g. `disabled`,
+   * `accessibilityHint`, `icon`). Use this for tweaks; for a fully custom
+   * action node, pass it as `action` instead.
+   */
+  actionProps?: Partial<ButtonProps>
+  /**
+   * Render-prop slot for the action area. When provided, takes precedence
+   * over `actionLabel`/`onActionPress`/`actionProps` and the default button
+   * is skipped entirely.
+   *
+   * Use `children` instead if you prefer a JSX-style slot — both are
+   * supported and produce identical output.
+   */
+  action?: React.ReactNode
+  /**
+   * Alternative slot for the action area. Identical to `action`; provided
+   * for ergonomic JSX:
+   *
+   * ```tsx
+   * <CoverageRing value={4} total={7} supportText="Benefits availed">
+   *   <CustomCTA />
+   * </CoverageRing>
+   * ```
+   */
+  children?: React.ReactNode
+  /** Design token modes forwarded to token lookups and slot children. */
+  modes?: Record<string, any>
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>
+  /** Override the support-text style inside the ring. */
+  supportTextStyle?: StyleProp<TextStyle>
+  /** Override the value-label style inside the ring. */
+  valueStyle?: StyleProp<TextStyle>
+  /** Accessibility label for the entire component. */
+  accessibilityLabel?: string
+}
+
+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 clamp = (value: number, min: number, max: number) =>
+  Math.min(max, Math.max(min, value))
+
+// The Figma "Coverage Ring" pairs a `circularProgressBar Size: M` ring with a
+// `Button / Size: S` Secondary button. Locking these in as component defaults
+// keeps the visual identical to the Figma reference when the caller supplies
+// only their own brand/theme modes — caller modes are still merged on top so
+// any of these can be overridden per-instance.
+const COMPONENT_DEFAULT_MODES: Readonly<Record<string, any>> = Object.freeze({
+  'circularProgressBar Size': 'M',
+  'Button / Size': 'S',
+})
+
+// Match the Figma source: regardless of the overall AppearanceBrand/Emphasis
+// the caller picks (used to colour the ring), the Coverage Ring CTA renders
+// with the Secondary brand at Medium emphasis — which resolves to the
+// pale-lavender background (`#dbcfff`) + deep-purple foreground (`#5d00b5`)
+// shown in Figma. Mirrors the pattern used by `CardFinancialCondition.tsx`.
+const BUTTON_FORCED_BRAND: Readonly<Record<string, any>> = Object.freeze({
+  AppearanceBrand: 'Secondary',
+  Emphasis: 'Medium',
+})
+
+/**
+ * `CoverageRing` renders a single-purpose insight: how many items out of a
+ * total have been covered (e.g. "4 of 7 benefits availed"), paired with a
+ * call-to-action button below the ring.
+ *
+ * It composes the existing {@link CircularProgressBar} (in its `M` size so
+ * there is room for a caption + value inside the ring) and {@link Button}
+ * (in its `S`, Secondary brand variant) — both driven by the same design
+ * tokens used by the rest of the design system.
+ *
+ * The ring fill is derived from `value / total`, so the percentage, the
+ * displayed `"{value} of {total}"` label and the support caption stay in
+ * sync automatically. There is no separate `progress` prop.
+ *
+ * @component
+ */
+function CoverageRing({
+  value = 4,
+  total = 7,
+  supportText = 'Benefits availed',
+  valueLabel,
+  actionLabel = 'Learn more',
+  onActionPress,
+  actionProps,
+  action,
+  children,
+  modes: propModes = EMPTY_MODES,
+  style,
+  supportTextStyle,
+  valueStyle,
+  accessibilityLabel,
+  ...rest
+}: CoverageRingProps) {
+  const { modes: globalModes } = useTokens()
+
+  // Merge order matches the rest of the design system (see `Gauge.tsx`):
+  // 1. Component-level defaults — the lowest-priority safety net.
+  // 2. Global modes from `JFSThemeProvider` — app-wide theme.
+  // 3. Caller-supplied `propModes` — highest priority, overrides everything.
+  const modes = React.useMemo(
+    () => ({ ...COMPONENT_DEFAULT_MODES, ...globalModes, ...propModes }),
+    [propModes, globalModes]
+  )
+
+  // Force the Secondary brand on the button only; the ring stays on whatever
+  // brand the caller selected. Done via a forcedModes layer so callers can't
+  // accidentally bring back a Primary-coloured CTA through their own modes.
+  const buttonModes = React.useMemo(
+    () => ({ ...modes, ...BUTTON_FORCED_BRAND }),
+    [modes]
+  )
+
+  const safeTotal = total > 0 ? total : 0
+  const clampedValue = clamp(value, 0, safeTotal)
+  const progressPercent = safeTotal > 0 ? (clampedValue / safeTotal) * 100 : 0
+  const computedValueLabel = valueLabel ?? `${clampedValue} of ${safeTotal}`
+
+  const gap = toNumber(getVariableByName('coverageRing/gap', modes), 16)
+
+  const containerStyle: ViewStyle = {
+    alignItems: 'center',
+    gap,
+  }
+
+  // Custom action slot resolution order: explicit `action` prop wins over
+  // `children`. We pass `modes` down via cloneChildrenWithModes so any
+  // token-driven child (e.g. a custom `<Button>`) inherits the parent theme.
+  const customAction = action ?? children
+  const hasCustomAction = customAction !== undefined && customAction !== null
+
+  const defaultAccessibilityLabel =
+    accessibilityLabel ?? `${supportText}, ${computedValueLabel}`
+
+  return (
+    <View
+      accessibilityLabel={defaultAccessibilityLabel}
+      style={[containerStyle, style]}
+      {...rest}
+    >
+      <CircularProgressBar
+        state="Active"
+        value={progressPercent}
+        valueLabel={computedValueLabel}
+        supportText={supportText}
+        supportTextStyle={supportTextStyle}
+        valueStyle={valueStyle}
+        modes={modes}
+        accessibilityLabel={`${supportText}, ${computedValueLabel}`}
+      />
+
+      {hasCustomAction ? (
+        cloneChildrenWithModes(customAction, buttonModes)
+      ) : (
+        <Button
+          label={actionLabel}
+          modes={buttonModes}
+          {...(onActionPress !== undefined ? { onPress: onActionPress } : {})}
+          {...actionProps}
+        />
+      )}
+    </View>
+  )
+}
+
+export default CoverageRing