jfs-components 0.0.72 → 0.0.73

package/src/components/SavingsGoalSummary/SavingsGoalSummary.tsx

@@ -0,0 +1,269 @@
+import React, { useMemo } from 'react'
+import {
+    View,
+    type StyleProp,
+    type ViewStyle,
+    type TextStyle,
+} from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
+import { formatIndianNumber } from '../../utils/number-utils'
+import Title from '../Title/Title'
+import LinearProgress from '../LinearProgress/LinearProgress'
+import MetricLegendItem from '../MetricLegendItem/MetricLegendItem'
+
+/**
+ * A single row in the savings-goal legend (current vs. target).
+ *
+ * `value` is a **numeric amount** (e.g. `240000`). It serves two purposes:
+ *
+ * 1. Display: rendered on the right side of the row using Indian numeric
+ *    notation via {@link formatIndianNumber} and prefixed with `currency`
+ *    (e.g. `240000` → `"₹2.4L"`).
+ * 2. Progress derivation: the bar fills to `current.value / target.value`
+ *    automatically. There is no separate `progress` prop.
+ *
+ * Pass `value: undefined` to render a label-only row (the underlying
+ * {@link MetricLegendItem} hides the right slot in that case).
+ */
+export type SavingsGoalSummaryItem = {
+    /** Label shown next to the indicator dot (e.g. "Current (4 months)"). */
+    label?: React.ReactNode
+    /**
+     * Numeric amount used for both display formatting and progress derivation.
+     * Use `undefined` to render a label-only row.
+     */
+    value?: number
+    /** Override the indicator dot colour. */
+    indicatorColor?: string
+}
+
+export type SavingsGoalSummaryProps = {
+    /**
+     * Currency symbol (e.g. `'₹'`, `'$'`) prefixed to every legend value.
+     * Defaults to `'₹'`. The symbol is rendered as part of the formatted
+     * string — this component does not use `MoneyValue`.
+     */
+    currency?: string
+    /**
+     * "Current" row in the legend. The indicator dot defaults to the
+     * `LinearProgress` indicator colour. Pass `null` to hide the row.
+     *
+     * `current.value` (numeric) drives both the displayed amount and — together
+     * with `target.value` — the progress bar fill.
+     */
+    current?: SavingsGoalSummaryItem | null
+    /**
+     * "Target" / recommended row in the legend. The indicator dot defaults to
+     * the `LinearProgress` track colour. Pass `null` to hide the row.
+     */
+    target?: SavingsGoalSummaryItem | null
+    /**
+     * Custom legend slot. When provided, replaces the default `current`/`target`
+     * rows entirely — pass any number of `MetricLegendItem`s (or any other
+     * nodes) to fully control the legend.
+     *
+     * Note: the progress bar is still derived from `current.value` / `target.value`,
+     * so pass them even when overriding the legend if you want a non-zero bar.
+     */
+    children?: React.ReactNode
+    /**
+     * Design token modes for theming. Defaults to `{ 'LinearProgress Size': 'L' }`
+     * which renders the thicker progress bar from the Figma reference. Caller
+     * modes are merged on top and can override every default key.
+     */
+    modes?: Record<string, any>
+    /** Override container styles. */
+    style?: StyleProp<ViewStyle>
+    /**
+     * Override styles for the auto-generated percentage text. Useful for
+     * tweaking colour or alignment; the value (e.g. `"50%"`) is always
+     * computed from `current` / `target` and cannot be replaced.
+     */
+    titleStyle?: StyleProp<TextStyle>
+    /** Override the inner legend container styles. */
+    legendStyle?: StyleProp<ViewStyle>
+}
+
+const DEFAULT_LEGEND_PADDING = 8
+
+const DEFAULT_MODES: Readonly<Record<string, any>> = Object.freeze({
+    'LinearProgress Size': 'L',
+})
+
+const DEFAULT_CURRENT: SavingsGoalSummaryItem = {
+    label: 'Current (4 months)',
+    value: 240000,
+}
+
+const DEFAULT_TARGET: SavingsGoalSummaryItem = {
+    label: 'Recommended (8 months)',
+    value: 480000,
+}
+
+/**
+ * `SavingsGoalSummary` visualises progress toward a savings goal as:
+ *
+ * 1. A `Title` showing the percentage — **computed automatically** from
+ *    `current.value / target.value`. There is no `progress` prop; the
+ *    component owns the calculation so the title, bar and legend are always
+ *    in sync.
+ * 2. A `LinearProgress` bar driven by the same derived ratio.
+ * 3. A two-row legend comparing **current** vs. **target**, where each numeric
+ *    `value` is auto-formatted with Indian notation
+ *    ({@link formatIndianNumber}) and prefixed with the `currency` symbol.
+ *
+ * The component is intentionally narrow in scope — it is the body of a savings
+ * insight card. Wrap it in `CardInsight` (or any container of your choice) to
+ * add a heading, badge or footer.
+ *
+ * @component
+ * @param {SavingsGoalSummaryProps} props
+ */
+function SavingsGoalSummary({
+    currency = '₹',
+    current = DEFAULT_CURRENT,
+    target = DEFAULT_TARGET,
+    children,
+    modes = EMPTY_MODES,
+    style,
+    titleStyle,
+    legendStyle,
+}: SavingsGoalSummaryProps) {
+    // Merge caller modes on top of the defaults so callers can override
+    // (e.g. switch to `LinearProgress Size: M`) while still receiving the
+    // sensible component-level default.
+    const mergedModes = useMemo(
+        () => (modes === EMPTY_MODES ? DEFAULT_MODES : { ...DEFAULT_MODES, ...modes }),
+        [modes],
+    )
+
+    // Resolve the `LinearProgress` track / indicator colours so the legend
+    // dots automatically stay in sync with the progress bar without callers
+    // needing to plumb through `indicatorColor`.
+    //
+    // The token names AND the merge strategy must match `LinearProgress.tsx`
+    // exactly, otherwise the dot colours can drift from the bar:
+    //   • Token aliases live in the `Emphasis` collection (modes High|Medium|Low),
+    //     NOT `Emphasis / DataViz` — passing the wrong mode key would collapse
+    //     both dots to the same default-mode colour.
+    //   • Defaults are placed *before* `mergedModes` is spread, so callers can
+    //     still override `Emphasis` via the `modes` prop (matches
+    //     `LinearProgress`'s philosophy).
+    const indicatorColorFromTokens =
+        (getVariableByName('linearProgress/indicator/background', {
+            Emphasis: 'High',
+            ...mergedModes,
+        }) as string | null) ?? '#5d00b5'
+    const trackColorFromTokens =
+        (getVariableByName('linearProgress/track/background', {
+            Emphasis: 'Low',
+            ...mergedModes,
+        }) as string | null) ?? '#ede7ff'
+
+    // Single source of truth for the bar fill, the title percentage and the
+    // formatted legend amounts. There is intentionally no consumer-facing
+    // `progress` prop — the only way to change the bar is to change the
+    // numeric `current` / `target` values. This keeps the three views (title,
+    // bar, legend) impossible to desynchronise.
+    const resolvedProgress = useMemo(() => {
+        const cv = current?.value
+        const tv = target?.value
+        if (typeof cv !== 'number' || typeof tv !== 'number' || tv <= 0) {
+            return 0
+        }
+        return Math.min(Math.max(cv / tv, 0), 1)
+    }, [current, target])
+
+    const percentageLabel = `${Math.round(resolvedProgress * 100)}%`
+
+    const gap = (getVariableByName('savingsGoalSummary/gap', mergedModes) as number | null) ?? 23
+    const legendGap =
+        (getVariableByName('savingsGoalSummary/legend/gap', mergedModes) as number | null) ?? 16
+
+    const customLegend = children
+        ? cloneChildrenWithModes(children, mergedModes)
+        : null
+
+    const defaultLegend = !customLegend && (current || target) ? (
+        <>
+            {current && (
+                <MetricLegendItem
+                    modes={mergedModes}
+                    label={current.label}
+                    value={formatLegendValue(current.value, currency)}
+                    indicatorColor={current.indicatorColor ?? indicatorColorFromTokens}
+                />
+            )}
+            {target && (
+                <MetricLegendItem
+                    modes={mergedModes}
+                    label={target.label}
+                    value={formatLegendValue(target.value, currency)}
+                    indicatorColor={target.indicatorColor ?? trackColorFromTokens}
+                />
+            )}
+        </>
+    ) : null
+
+    const legendNode = customLegend ?? defaultLegend
+    const showLegend = legendNode != null
+
+    return (
+        <View
+            style={[
+                {
+                    width: '100%',
+                    gap,
+                    alignItems: 'stretch',
+                },
+                style,
+            ]}
+            accessibilityLabel={`Savings goal progress, ${percentageLabel}`}
+        >
+            <Title
+                title={percentageLabel}
+                modes={mergedModes}
+                style={TITLE_CONTAINER_STYLE}
+                textStyle={titleStyle}
+            />
+
+            <LinearProgress value={resolvedProgress} modes={mergedModes} />
+
+            {showLegend && (
+                <View
+                    style={[
+                        {
+                            width: '100%',
+                            padding: DEFAULT_LEGEND_PADDING,
+                            gap: legendGap,
+                            alignItems: 'stretch',
+                        },
+                        legendStyle,
+                    ]}
+                >
+                    {legendNode}
+                </View>
+            )}
+        </View>
+    )
+}
+
+/**
+ * Format a single legend `value` for display. Returns `undefined` when the
+ * value is missing so the underlying {@link MetricLegendItem} hides the right
+ * slot (matches the Figma `data` toggle = off).
+ */
+function formatLegendValue(value: number | undefined, currency: string): string | undefined {
+    if (typeof value !== 'number') return undefined
+    return formatIndianNumber(value, { prefix: currency })
+}
+
+// Neutralise the `Title` component's default page-level padding so it sits
+// flush inside the summary card (the parent container owns spacing via `gap`).
+const TITLE_CONTAINER_STYLE: ViewStyle = {
+    paddingHorizontal: 0,
+    paddingVertical: 0,
+}
+
+export default SavingsGoalSummary

package/src/components/SegmentedTrack/SegmentedTrack.tsx

@@ -0,0 +1,268 @@
+import React from 'react'
+import {
+    View,
+    type StyleProp,
+    type ViewStyle,
+} from 'react-native'
+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.
+ *
+ * Use `value` for proportional widths (segments share width by their value
+ * relative to the sum). When `value` is omitted, segments share the row
+ * equally (`flex: 1`).
+ *
+ * Use `modes` to override the per-segment design-token mode — typically the
+ * `Appearance / DataViz` mode for color theming, or `Emphasis / DataViz` to
+ * change the emphasis level. The parent already injects per-index defaults
+ * (segment 0 = High, 1 = Medium, 2 = Low, then cycling) so callers only need
+ * to pass `modes` when they want a different result.
+ */
+export type SegmentedTrackSegmentData = {
+    /** Stable React key. */
+    key?: React.Key
+    /**
+     * Optional explicit weight used for proportional width (`flex: value`).
+     * When omitted, the segment uses an equal share of the available row.
+     * Mixing values and undefined is supported — undefined falls back to 1.
+     */
+    value?: number
+    /**
+     * Hard-override the segment color. Bypasses `dataViz/bg` token resolution
+     * entirely.
+     */
+    color?: string
+    /**
+     * Per-segment design token mode overrides. Merged on top of the parent
+     * `modes` and the per-index Emphasis defaults.
+     */
+    modes?: Record<string, any>
+    /** Override individual segment styles. */
+    style?: StyleProp<ViewStyle>
+    /** Per-segment accessibility label. */
+    accessibilityLabel?: string
+}
+
+export type SegmentedTrackProps = {
+    /**
+     * Data-driven segment list. Used when no `children` slot is provided.
+     * Defaults to three equal segments which receive per-index Emphasis
+     * defaults (`High`, `Medium`, `Low`).
+     */
+    segments?: SegmentedTrackSegmentData[]
+    /**
+     * Slot for fully custom segment children. Each top-level child is treated
+     * as one segment. The parent injects per-index Emphasis defaults and the
+     * shared `modes`, while child-level `modes` overrides win.
+     */
+    children?: React.ReactNode
+    /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+    modes?: Record<string, any>
+    /** Override the container styles. */
+    style?: StyleProp<ViewStyle>
+    /** Style applied to every segment (data-driven mode only). */
+    segmentStyle?: StyleProp<ViewStyle>
+    /** Accessibility label announced for the whole distribution row. */
+    accessibilityLabel?: string
+}
+
+type SegmentedTrackSegmentProps = {
+    /**
+     * Optional explicit weight used for proportional width (`flex: value`).
+     * Defaults to 1 (equal share within the parent row).
+     */
+    value?: number | undefined
+    /**
+     * Hard-override the segment color. Bypasses `dataViz/bg` token resolution.
+     */
+    color?: string | undefined
+    /**
+     * Design token modes for the segment. Merged with parent `modes` and the
+     * per-index Emphasis defaults injected by the parent `SegmentedTrack`.
+     */
+    modes?: Record<string, any> | undefined
+    /** Override the segment styles. */
+    style?: StyleProp<ViewStyle> | undefined
+    /** Per-segment accessibility label. */
+    accessibilityLabel?: string | undefined
+}
+
+/**
+ * Default per-index Emphasis modes applied to every segment when the caller
+ * does not provide its own `Emphasis / DataViz` override. Cycles for >3
+ * segments so additional segments fall back to the same High/Medium/Low
+ * rotation.
+ */
+const DEFAULT_EMPHASIS_CYCLE = ['High', 'Medium', 'Low'] as const
+
+const DEFAULT_SEGMENTS: SegmentedTrackSegmentData[] = [
+    {},
+    {},
+    {},
+]
+
+/**
+ * Compute the default `Emphasis / DataViz` mode for a segment at `index`.
+ * Cycles through {@link DEFAULT_EMPHASIS_CYCLE} so any number of segments
+ * gets a sensible default.
+ */
+function defaultEmphasisFor(index: number) {
+    return DEFAULT_EMPHASIS_CYCLE[index % DEFAULT_EMPHASIS_CYCLE.length]
+}
+
+function SegmentedTrackSegment({
+    value = 1,
+    color,
+    modes = EMPTY_MODES,
+    style,
+    accessibilityLabel,
+}: SegmentedTrackSegmentProps) {
+    const resolvedColor =
+        color ?? ((getVariableByName('dataViz/bg', modes) as string | null) ?? '#5d00b5')
+
+    return (
+        <View
+            accessibilityLabel={accessibilityLabel}
+            style={[
+                {
+                    flex: value,
+                    minWidth: 1,
+                    height: '100%',
+                    backgroundColor: resolvedColor,
+                },
+                style,
+            ]}
+        />
+    )
+}
+
+/**
+ * `SegmentedTrack` renders a horizontal pill-shaped row of categorical
+ * segments. Use it for distribution / share-of breakdowns where each
+ * segment is a sibling category (not a directional or temporal progress).
+ *
+ * Defaults to three equal segments tinted at descending Emphasis levels
+ * (`High`, `Medium`, `Low`) so the shape reads as a single concept split
+ * three ways. Consumers can either pass the data-driven `segments` prop or
+ * a fully custom `children` slot of `SegmentedTrack.Segment`s.
+ *
+ * Each segment resolves its color through the `dataViz/bg` token, which
+ * cascades through `Emphasis / DataViz` and `Appearance / DataViz`. Pass
+ * `modes` per segment (or override `Appearance / DataViz` at the parent
+ * level via `modes`) to retheme the row without touching colors directly.
+ *
+ * @component
+ * @param {SegmentedTrackProps} props
+ */
+function SegmentedTrack({
+    segments,
+    children,
+    modes: propModes = EMPTY_MODES,
+    style,
+    segmentStyle,
+    accessibilityLabel,
+}: SegmentedTrackProps) {
+    const { modes: globalModes } = useTokens()
+    const modes = { ...globalModes, ...propModes }
+
+    const trackHeight =
+        (getVariableByName('segmentedTrack/height', modes) as number | null) ?? 24
+    const trackRadius =
+        (getVariableByName('segmentedTrack/radius', modes) as number | null) ?? 999
+
+    const renderedSegments = renderSegments({
+        segments,
+        children,
+        modes,
+        segmentStyle,
+    })
+
+    return (
+        <View
+            accessibilityRole="image"
+            accessibilityLabel={accessibilityLabel}
+            style={[
+                {
+                    flexDirection: 'row',
+                    alignItems: 'stretch',
+                    height: trackHeight,
+                    borderRadius: trackRadius,
+                    overflow: 'hidden',
+                    width: '100%',
+                    backgroundColor: 'transparent',
+                },
+                style,
+            ]}
+        >
+            {renderedSegments}
+        </View>
+    )
+}
+
+/**
+ * Build the slot children. When the caller passes JSX `children`, every
+ * top-level element is treated as one segment and receives merged `modes`
+ * (parent + per-index Emphasis default + the child's own `modes` taking
+ * priority). Otherwise the data-driven `segments` array is rendered.
+ */
+function renderSegments({
+    segments,
+    children,
+    modes,
+    segmentStyle,
+}: {
+    segments: SegmentedTrackSegmentData[] | undefined
+    children: React.ReactNode | undefined
+    modes: Record<string, any>
+    segmentStyle: StyleProp<ViewStyle> | undefined
+}): React.ReactNode[] {
+    if (children !== undefined && children !== null) {
+        const flat = flattenChildren(children)
+        return flat.map((child, index) => {
+            if (!React.isValidElement(child)) {
+                return child
+            }
+            const childProps = (child.props as any) ?? {}
+            const childModes = childProps.modes
+            const mergedModes = {
+                ...modes,
+                'Emphasis / DataViz': defaultEmphasisFor(index),
+                ...(childModes || {}),
+            }
+            return React.cloneElement(child, {
+                ...childProps,
+                modes: mergedModes,
+                key: child.key ?? `segment-${index}`,
+            })
+        })
+    }
+
+    const list = segments && segments.length > 0 ? segments : DEFAULT_SEGMENTS
+    return list.map((segment, index) => {
+        const segmentModes = {
+            ...modes,
+            'Emphasis / DataViz': defaultEmphasisFor(index),
+            ...(segment.modes || {}),
+        }
+        return (
+            <SegmentedTrackSegment
+                key={segment.key ?? `segment-${index}`}
+                value={segment.value ?? 1}
+                color={segment.color}
+                modes={segmentModes}
+                style={[segmentStyle, segment.style]}
+                accessibilityLabel={segment.accessibilityLabel}
+            />
+        )
+    })
+}
+
+SegmentedTrack.Segment = SegmentedTrackSegment
+
+export { SegmentedTrackSegment }
+export type { SegmentedTrackSegmentProps }
+
+export default SegmentedTrack

package/src/components/StatGroup/StatGroup.tsx

@@ -0,0 +1,169 @@
+import React from 'react'
+import { View, type StyleProp, type ViewStyle } from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import {
+  EMPTY_MODES,
+  cloneChildrenWithModes,
+  flattenChildren,
+} from '../../utils/react-utils'
+import StatItem from '../StatItem/StatItem'
+import Divider from '../Divider/Divider'
+
+export type StatGroupItem = {
+  /** Stable key for the item. Falls back to the label / index. */
+  key?: React.Key
+  /** The descriptive label shown beneath the value. */
+  label?: string
+  /** The prominent value shown above the label. */
+  value?: string
+}
+
+export type StatGroupProps = {
+  /**
+   * Array of stat items. Each item is rendered as a centered `StatItem`
+   * (`labelPosition="Bottom"`) with vertical dividers between them.
+   *
+   * Ignored when a `children` slot is provided.
+   */
+  items?: StatGroupItem[]
+  /**
+   * Custom slot content. When provided, the `items` prop is ignored. Each
+   * top-level child is wrapped to take an equal share of the available width
+   * and a vertical `Divider` is auto-inserted between siblings — matching the
+   * Figma `slot` behaviour. `modes` are propagated to all children.
+   */
+  children?: React.ReactNode
+  /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+  modes?: Record<string, any>
+  /** Override container styles. */
+  style?: StyleProp<ViewStyle>
+}
+
+const DEFAULT_ITEMS: StatGroupItem[] = [
+  { label: 'Updates', value: 'Daily' },
+  { label: 'Data range', value: '24 months' },
+  { label: 'Validity', value: '24 months' },
+  { label: 'Stored for', value: '1 month' },
+]
+
+/**
+ * StatGroup renders a card-style container holding a horizontal row of
+ * `StatItem`s separated by vertical dividers. It is typically used to surface
+ * 3–5 short metrics (e.g. validity, data range, storage) at a glance.
+ *
+ * Pass `items` for the simple data-driven case, or use the `children` slot
+ * for full control over the row contents (the component still auto-inserts
+ * vertical dividers between top-level children).
+ *
+ * @component
+ * @param {StatGroupProps} props
+ */
+function StatGroup({
+  items,
+  children,
+  modes = EMPTY_MODES,
+  style,
+}: StatGroupProps) {
+  const background =
+    (getVariableByName('statGroup/background', modes) as string | null) ?? '#ffffff'
+  const strokeColor =
+    (getVariableByName('statGroup/stroke/color', modes) as string | null) ?? '#ebebed'
+  const strokeSize =
+    (getVariableByName('statGroup/stroke/size', modes) as number | null) ?? 1
+  const radius =
+    (getVariableByName('statGroup/radius', modes) as number | null) ?? 12
+  const paddingTop =
+    (getVariableByName('statGroup/padding/top', modes) as number | null) ?? 16
+  const paddingRight =
+    (getVariableByName('statGroup/padding/right', modes) as number | null) ?? 0
+  const paddingBottom =
+    (getVariableByName('statGroup/padding/bottom', modes) as number | null) ?? 12
+  const paddingLeft =
+    (getVariableByName('statGroup/padding/left', modes) as number | null) ?? 0
+
+  const containerStyle: ViewStyle = {
+    backgroundColor: background,
+    borderColor: strokeColor,
+    borderWidth: strokeSize,
+    borderStyle: 'solid',
+    borderRadius: radius,
+    paddingTop,
+    paddingRight,
+    paddingBottom,
+    paddingLeft,
+    overflow: 'hidden',
+  }
+
+  const slotChildren = renderSlotChildren({ items, children, modes })
+
+  return (
+    <View style={[containerStyle, style]} accessibilityRole="summary">
+      <View
+        style={{
+          flexDirection: 'row',
+          alignItems: 'stretch',
+          width: '100%',
+        }}
+      >
+        {slotChildren}
+      </View>
+    </View>
+  )
+}
+
+/**
+ * Build the row of items: render either the supplied children or the
+ * `items` array, wrap each entry so it grows equally, and inject a vertical
+ * `Divider` between siblings.
+ */
+function renderSlotChildren({
+  items,
+  children,
+  modes,
+}: {
+  items?: StatGroupItem[]
+  children?: React.ReactNode
+  modes: Record<string, any>
+}): React.ReactNode[] {
+  let nodes: React.ReactNode[]
+
+  if (children !== undefined && children !== null) {
+    const cloned = cloneChildrenWithModes(children, modes)
+    nodes = flattenChildren(cloned)
+  } else {
+    const list = items && items.length > 0 ? items : DEFAULT_ITEMS
+    nodes = list.map((item, index) => (
+      <StatItem
+        key={item.key ?? `${item.label ?? 'item'}-${index}`}
+        label={item.label}
+        value={item.value}
+        labelPosition="Bottom"
+        modes={modes}
+      />
+    ))
+  }
+
+  const result: React.ReactNode[] = []
+  nodes.forEach((node, index) => {
+    if (index > 0) {
+      result.push(
+        <Divider
+          key={`divider-${index}`}
+          direction="vertical"
+          modes={modes}
+        />
+      )
+    }
+    result.push(
+      <View
+        key={`slot-${index}`}
+        style={{ flex: 1, minWidth: 0, alignSelf: 'center' }}
+      >
+        {node}
+      </View>
+    )
+  })
+  return result
+}
+
+export default StatGroup