jfs-components 0.0.72 → 0.0.74

package/src/components/RangeTrack/RangeTrack.tsx

@@ -0,0 +1,394 @@
+import React, { useCallback, useState } 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 } from '../../utils/react-utils'
+import MetricLegendItem from '../MetricLegendItem/MetricLegendItem'
+import SegmentedTrack, {
+    type SegmentedTrackSegmentData,
+} from '../SegmentedTrack/SegmentedTrack'
+import Tabs from '../Tabs/Tabs'
+import TabItem from '../Tabs/TabItem'
+
+/**
+ * One row of data inside a `RangeTrack` tab.
+ *
+ * Each item drives BOTH a `SegmentedTrack` segment and the matching
+ * `MetricLegendItem` row, so the segment color and legend indicator
+ * always share the same color by construction (same `Emphasis / DataViz`
+ * cascade as the standalone `SegmentedTrack`).
+ */
+export type RangeTrackItem = {
+    /** Stable React key. Falls back to the item label / index. */
+    key?: React.Key
+    /** The descriptive label rendered next to the indicator dot. */
+    label?: React.ReactNode
+    /**
+     * The data point — drives the segment's proportional width. Same
+     * semantics as `SegmentedTrackSegmentData.value`. When the legend's
+     * right-side text is shown, the resolution order is:
+     * `displayValue` → `formatValue(value)` → hide.
+     */
+    value: number
+    /**
+     * Optional override for the legend row's right-side text. Falls
+     * back to `formatValue(value)` if a parent-level `formatValue` is
+     * provided; otherwise the value slot is hidden (matches the
+     * `data` boolean toggle on `MetricLegendItem`). Pass `null` or
+     * `false` to explicitly hide on a per-item basis.
+     */
+    displayValue?: React.ReactNode
+    /**
+     * Hard-override the shared color used for both the segment and the
+     * legend indicator. Bypasses `dataViz/bg` token resolution.
+     */
+    color?: string
+    /**
+     * Per-item design token mode overrides. Merged on top of parent
+     * `modes` and the per-index `Emphasis / DataViz` defaults
+     * (`High`, `Medium`, `Low`, then cycles).
+     */
+    modes?: Record<string, any>
+    /** Accessibility label for the segment + legend row pairing. */
+    accessibilityLabel?: string
+}
+
+/**
+ * One tab inside a `RangeTrack`. Each tab carries its own `items`
+ * array, which is the single source of truth for both the
+ * `SegmentedTrack` segments AND the `MetricLegendItem` legend rows
+ * rendered for that tab.
+ */
+export type RangeTrackTab = {
+    /** Stable React key. Falls back to the tab label / index. */
+    key?: React.Key
+    /** The label shown inside the `TabItem` at the top of the component. */
+    label: string
+    /**
+     * Data-driven rows. Each entry produces one `SegmentedTrack`
+     * segment AND one matching `MetricLegendItem` legend row — the
+     * count of legend rows is locked in step with the count of segments
+     * by construction.
+     */
+    items: RangeTrackItem[]
+    /**
+     * Per-tab accessibility label for the tab item button. Falls back
+     * to `label`.
+     */
+    accessibilityLabel?: string
+}
+
+export type RangeTrackProps = {
+    /**
+     * Tabs to render across the top. Each tab carries its own `items`
+     * array, which is the single source of truth for that tab's
+     * segments and legend rows. Switching tabs swaps both the segments
+     * and the legend together.
+     */
+    tabs: RangeTrackTab[]
+    /**
+     * Optional formatter applied to each item's numeric `value` when
+     * the item does not provide an explicit `displayValue`. Useful for
+     * the common "format every weight the same way" case
+     * (e.g. `(v) => `${v}%``). Applies to the legend rows of the
+     * currently active tab.
+     */
+    formatValue?: (value: number) => React.ReactNode
+    /**
+     * Controlled active tab index. When provided, the component is
+     * fully controlled and `onTabChange` should be wired up. When
+     * `undefined`, the component manages the active tab internally
+     * starting from `defaultActiveTabIndex`.
+     */
+    activeTabIndex?: number
+    /**
+     * Initial active tab index when the component is uncontrolled.
+     * Ignored if `activeTabIndex` is provided.
+     * @default 0
+     */
+    defaultActiveTabIndex?: number
+    /**
+     * Fired when the user taps a tab. Receives the new index and the
+     * matching `RangeTrackTab` from the `tabs` array.
+     */
+    onTabChange?: (index: number, tab: RangeTrackTab) => void
+    /**
+     * When true, the tab row scrolls horizontally — useful when there
+     * are many tabs.
+     * @default false
+     */
+    scrollableTabs?: boolean
+    /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+    modes?: Record<string, any>
+    /** Override the outer container styles. */
+    style?: StyleProp<ViewStyle>
+    /** Override the tab row styles. */
+    tabsStyle?: StyleProp<ViewStyle>
+    /** Override the `SegmentedTrack` styles. */
+    trackStyle?: StyleProp<ViewStyle>
+    /** Override the legend list container styles. */
+    legendStyle?: StyleProp<ViewStyle>
+    /** Accessibility label announced for the whole component. */
+    accessibilityLabel?: string
+}
+
+const DEFAULT_EMPHASIS_CYCLE = ['High', 'Medium', 'Low'] as const
+
+const DEFAULT_TABS: RangeTrackTab[] = [
+    {
+        label: 'Tab item',
+        items: [
+            { label: 'Large cap', value: 1, displayValue: '25%' },
+            { label: 'Mid cap', value: 1, displayValue: '25%' },
+            { label: 'Small cap', value: 1, displayValue: '25%' },
+        ],
+    },
+    {
+        label: 'Tab item',
+        items: [
+            { label: 'Large cap', value: 1, displayValue: '25%' },
+            { label: 'Mid cap', value: 1, displayValue: '25%' },
+            { label: 'Small cap', value: 1, displayValue: '25%' },
+        ],
+    },
+    {
+        label: 'Tab item',
+        items: [
+            { label: 'Large cap', value: 1, displayValue: '25%' },
+            { label: 'Mid cap', value: 1, displayValue: '25%' },
+            { label: 'Small cap', value: 1, displayValue: '25%' },
+        ],
+    },
+]
+
+const defaultEmphasisFor = (index: number) =>
+    DEFAULT_EMPHASIS_CYCLE[index % DEFAULT_EMPHASIS_CYCLE.length]
+
+/**
+ * Resolve the shared color for an item. Honors any explicit `color`
+ * override, then falls back to `dataViz/bg` for the merged mode set,
+ * then to the Figma reference value.
+ *
+ * Mirrors the cascade used by `SegmentedTrack` (per-index `Emphasis /
+ * DataViz` defaults of `High` → `Medium` → `Low`, cycling) so the
+ * pre-computed color we pass to both the segment and the legend
+ * indicator matches what the `SegmentedTrack` would have computed on
+ * its own. This is what keeps segments and legend rows in sync by
+ * construction.
+ */
+function resolveItemColor(
+    parentModes: Record<string, any>,
+    item: RangeTrackItem,
+    index: number
+): string {
+    if (item.color) return item.color
+    const itemModes = {
+        ...parentModes,
+        'Emphasis / DataViz': defaultEmphasisFor(index),
+        ...(item.modes || {}),
+    }
+    return (
+        (getVariableByName('dataViz/bg', itemModes) as string | null) ?? '#cea15a'
+    )
+}
+
+/**
+ * Resolve what to render in the legend row's right-side slot. The
+ * order of precedence is:
+ *   1. `item.displayValue` if explicitly provided (including `null` /
+ *      `false`, which the underlying `MetricLegendItem` treats as
+ *      "hide the value slot").
+ *   2. `formatValue(item.value)` when a parent-level formatter exists.
+ *   3. `undefined` — the value slot is hidden.
+ */
+function resolveLegendValue(
+    item: RangeTrackItem,
+    formatValue: ((value: number) => React.ReactNode) | undefined
+): React.ReactNode {
+    if (item.displayValue !== undefined) return item.displayValue
+    if (formatValue) return formatValue(item.value)
+    return undefined
+}
+
+/**
+ * `RangeTrack` pairs a tab row with a `SegmentedTrack` and a vertical
+ * stack of `MetricLegendItem` rows. Each tab carries its own `items`
+ * array which is the **single source of truth** for both the segments
+ * and the legend rows of that tab — every segment has exactly one
+ * legend row and they share the same color through the same
+ * `Emphasis / DataViz` cascade as the standalone `SegmentedTrack`.
+ *
+ * Switching tabs swaps the segments and the legend together so the
+ * two visualizations can never drift out of sync.
+ *
+ * The default 3-item layout per tab receives per-index
+ * `Emphasis / DataViz` defaults (item 1 → `High`, 2 → `Medium`, 3 →
+ * `Low`, then cycles). Override `Appearance / DataViz` on the parent
+ * `modes` to retheme the whole component, or set `modes` per item to
+ * remix.
+ *
+ * The component supports both **controlled** and **uncontrolled**
+ * tab selection — pass `activeTabIndex` + `onTabChange` for the
+ * controlled mode, or omit them and the component will manage the
+ * selection internally starting from `defaultActiveTabIndex`.
+ *
+ * @component
+ * @param {RangeTrackProps} props
+ *
+ * @example
+ * ```tsx
+ * <RangeTrack
+ *   tabs={[
+ *     {
+ *       label: 'Sectoral',
+ *       items: [
+ *         { label: 'Large cap', value: 50, displayValue: '50%' },
+ *         { label: 'Mid cap',   value: 30, displayValue: '30%' },
+ *         { label: 'Small cap', value: 20, displayValue: '20%' },
+ *       ],
+ *     },
+ *     {
+ *       label: 'Geography',
+ *       items: [
+ *         { label: 'India', value: 70, displayValue: '70%' },
+ *         { label: 'US',    value: 20, displayValue: '20%' },
+ *         { label: 'Other', value: 10, displayValue: '10%' },
+ *       ],
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+function RangeTrack({
+    tabs,
+    formatValue,
+    activeTabIndex,
+    defaultActiveTabIndex = 0,
+    onTabChange,
+    scrollableTabs = false,
+    modes: propModes = EMPTY_MODES,
+    style,
+    tabsStyle,
+    trackStyle,
+    legendStyle,
+    accessibilityLabel,
+}: RangeTrackProps) {
+    const { modes: globalModes } = useTokens()
+    const modes = { ...globalModes, ...propModes }
+
+    const resolvedTabs = tabs && tabs.length > 0 ? tabs : DEFAULT_TABS
+
+    const [internalIndex, setInternalIndex] = useState(() =>
+        clampIndex(defaultActiveTabIndex, resolvedTabs.length)
+    )
+
+    const isControlled = activeTabIndex !== undefined
+    const rawIndex = isControlled ? activeTabIndex : internalIndex
+    const safeIndex = clampIndex(rawIndex, resolvedTabs.length)
+
+    const handleTabPress = useCallback(
+        (index: number) => {
+            const nextTab = resolvedTabs[index]
+            if (!nextTab) return
+            if (!isControlled) setInternalIndex(index)
+            onTabChange?.(index, nextTab)
+        },
+        [isControlled, onTabChange, resolvedTabs]
+    )
+
+    const containerGap =
+        (getVariableByName('rangeTrack/gap', modes) as number | null) ?? 28
+    // Vertical gap between legend rows is not exposed as its own token —
+    // the Figma design uses 8px between rows, mirroring the
+    // `donutChartSummary/legend/gap` default. Keep the value in step
+    // with `DonutChartSummary` so the two summary components feel
+    // cohesive when stacked.
+    const legendRowGap = 8
+
+    const activeTab = resolvedTabs[safeIndex]
+    const activeItems = activeTab?.items ?? []
+
+    const segments: SegmentedTrackSegmentData[] = activeItems.map(
+        (item, index) => ({
+            key: item.key ?? `segment-${index}`,
+            value: item.value,
+            color: resolveItemColor(modes, item, index),
+            accessibilityLabel: item.accessibilityLabel,
+        })
+    )
+
+    return (
+        <View
+            accessibilityRole="summary"
+            accessibilityLabel={accessibilityLabel}
+            style={[
+                {
+                    width: '100%',
+                    flexDirection: 'column',
+                    alignItems: 'flex-start',
+                    gap: containerGap,
+                },
+                style,
+            ]}
+        >
+            <Tabs
+                modes={modes}
+                scrollable={scrollableTabs}
+                style={tabsStyle}
+            >
+                {resolvedTabs.map((tab, index) => (
+                    <TabItem
+                        key={tab.key ?? tab.label ?? `tab-${index}`}
+                        label={tab.label}
+                        active={index === safeIndex}
+                        onPress={() => handleTabPress(index)}
+                        accessibilityLabel={tab.accessibilityLabel ?? tab.label}
+                    />
+                ))}
+            </Tabs>
+
+            <SegmentedTrack
+                modes={modes}
+                segments={segments}
+                style={trackStyle}
+                accessibilityLabel={activeTab?.accessibilityLabel ?? activeTab?.label}
+            />
+
+            <View
+                style={[
+                    {
+                        width: '100%',
+                        flexDirection: 'column',
+                        alignItems: 'flex-start',
+                        gap: legendRowGap,
+                    },
+                    legendStyle,
+                ]}
+            >
+                {activeItems.map((item, index) => (
+                    <MetricLegendItem
+                        key={item.key ?? `legend-${index}`}
+                        label={item.label}
+                        value={resolveLegendValue(item, formatValue)}
+                        indicatorColor={resolveItemColor(modes, item, index)}
+                        modes={modes}
+                    />
+                ))}
+            </View>
+        </View>
+    )
+}
+
+/**
+ * Clamp a tab index into `[0, length)`. Negative or out-of-bounds
+ * values fall back to `0` to avoid rendering an undefined tab.
+ */
+function clampIndex(index: number, length: number): number {
+    if (length <= 0) return 0
+    if (!Number.isFinite(index)) return 0
+    if (index < 0) return 0
+    if (index >= length) return length - 1
+    return Math.floor(index)
+}
+
+export default RangeTrack

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