jfs-components 0.0.72 → 0.0.73

package/lib/module/components/RangeTrack/RangeTrack.js

@@ -0,0 +1,263 @@
+"use strict";
+
+import React, { useCallback, useState } from 'react';
+import { View } 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 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`).
+ */
+
+/**
+ * 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.
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const DEFAULT_EMPHASIS_CYCLE = ['High', 'Medium', 'Low'];
+const DEFAULT_TABS = [{
+  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 => 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, item, index) {
+  if (item.color) return item.color;
+  const itemModes = {
+    ...parentModes,
+    'Emphasis / DataViz': defaultEmphasisFor(index),
+    ...(item.modes || {})
+  };
+  return getVariableByName('dataViz/bg', itemModes) ?? '#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, formatValue) {
+  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
+}) {
+  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 => {
+    const nextTab = resolvedTabs[index];
+    if (!nextTab) return;
+    if (!isControlled) setInternalIndex(index);
+    onTabChange?.(index, nextTab);
+  }, [isControlled, onTabChange, resolvedTabs]);
+  const containerGap = getVariableByName('rangeTrack/gap', modes) ?? 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 = activeItems.map((item, index) => ({
+    key: item.key ?? `segment-${index}`,
+    value: item.value,
+    color: resolveItemColor(modes, item, index),
+    accessibilityLabel: item.accessibilityLabel
+  }));
+  return /*#__PURE__*/_jsxs(View, {
+    accessibilityRole: "summary",
+    accessibilityLabel: accessibilityLabel,
+    style: [{
+      width: '100%',
+      flexDirection: 'column',
+      alignItems: 'flex-start',
+      gap: containerGap
+    }, style],
+    children: [/*#__PURE__*/_jsx(Tabs, {
+      modes: modes,
+      scrollable: scrollableTabs,
+      style: tabsStyle,
+      children: resolvedTabs.map((tab, index) => /*#__PURE__*/_jsx(TabItem, {
+        label: tab.label,
+        active: index === safeIndex,
+        onPress: () => handleTabPress(index),
+        accessibilityLabel: tab.accessibilityLabel ?? tab.label
+      }, tab.key ?? tab.label ?? `tab-${index}`))
+    }), /*#__PURE__*/_jsx(SegmentedTrack, {
+      modes: modes,
+      segments: segments,
+      style: trackStyle,
+      accessibilityLabel: activeTab?.accessibilityLabel ?? activeTab?.label
+    }), /*#__PURE__*/_jsx(View, {
+      style: [{
+        width: '100%',
+        flexDirection: 'column',
+        alignItems: 'flex-start',
+        gap: legendRowGap
+      }, legendStyle],
+      children: activeItems.map((item, index) => /*#__PURE__*/_jsx(MetricLegendItem, {
+        label: item.label,
+        value: resolveLegendValue(item, formatValue),
+        indicatorColor: resolveItemColor(modes, item, index),
+        modes: modes
+      }, item.key ?? `legend-${index}`))
+    })]
+  });
+}
+
+/**
+ * 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, length) {
+  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/lib/module/components/SavingsGoalSummary/SavingsGoalSummary.js

@@ -0,0 +1,175 @@
+"use strict";
+
+import React, { useMemo } from 'react';
+import { View } 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).
+ */
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+const DEFAULT_LEGEND_PADDING = 8;
+const DEFAULT_MODES = Object.freeze({
+  'LinearProgress Size': 'L'
+});
+const DEFAULT_CURRENT = {
+  label: 'Current (4 months)',
+  value: 240000
+};
+const DEFAULT_TARGET = {
+  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
+}) {
+  // 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
+  }) ?? '#5d00b5';
+  const trackColorFromTokens = getVariableByName('linearProgress/track/background', {
+    Emphasis: 'Low',
+    ...mergedModes
+  }) ?? '#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) ?? 23;
+  const legendGap = getVariableByName('savingsGoalSummary/legend/gap', mergedModes) ?? 16;
+  const customLegend = children ? cloneChildrenWithModes(children, mergedModes) : null;
+  const defaultLegend = !customLegend && (current || target) ? /*#__PURE__*/_jsxs(_Fragment, {
+    children: [current && /*#__PURE__*/_jsx(MetricLegendItem, {
+      modes: mergedModes,
+      label: current.label,
+      value: formatLegendValue(current.value, currency),
+      indicatorColor: current.indicatorColor ?? indicatorColorFromTokens
+    }), target && /*#__PURE__*/_jsx(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 /*#__PURE__*/_jsxs(View, {
+    style: [{
+      width: '100%',
+      gap,
+      alignItems: 'stretch'
+    }, style],
+    accessibilityLabel: `Savings goal progress, ${percentageLabel}`,
+    children: [/*#__PURE__*/_jsx(Title, {
+      title: percentageLabel,
+      modes: mergedModes,
+      style: TITLE_CONTAINER_STYLE,
+      textStyle: titleStyle
+    }), /*#__PURE__*/_jsx(LinearProgress, {
+      value: resolvedProgress,
+      modes: mergedModes
+    }), showLegend && /*#__PURE__*/_jsx(View, {
+      style: [{
+        width: '100%',
+        padding: DEFAULT_LEGEND_PADDING,
+        gap: legendGap,
+        alignItems: 'stretch'
+      }, legendStyle],
+      children: legendNode
+    })]
+  });
+}
+
+/**
+ * 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, currency) {
+  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 = {
+  paddingHorizontal: 0,
+  paddingVertical: 0
+};
+export default SavingsGoalSummary;

package/lib/module/components/SegmentedTrack/SegmentedTrack.js

@@ -0,0 +1,166 @@
+"use strict";
+
+import React from 'react';
+import { View } 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.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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'];
+const DEFAULT_SEGMENTS = [{}, {}, {}];
+
+/**
+ * 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) {
+  return DEFAULT_EMPHASIS_CYCLE[index % DEFAULT_EMPHASIS_CYCLE.length];
+}
+function SegmentedTrackSegment({
+  value = 1,
+  color,
+  modes = EMPTY_MODES,
+  style,
+  accessibilityLabel
+}) {
+  const resolvedColor = color ?? getVariableByName('dataViz/bg', modes) ?? '#5d00b5';
+  return /*#__PURE__*/_jsx(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
+}) {
+  const {
+    modes: globalModes
+  } = useTokens();
+  const modes = {
+    ...globalModes,
+    ...propModes
+  };
+  const trackHeight = getVariableByName('segmentedTrack/height', modes) ?? 24;
+  const trackRadius = getVariableByName('segmentedTrack/radius', modes) ?? 999;
+  const renderedSegments = renderSegments({
+    segments,
+    children,
+    modes,
+    segmentStyle
+  });
+  return /*#__PURE__*/_jsx(View, {
+    accessibilityRole: "image",
+    accessibilityLabel: accessibilityLabel,
+    style: [{
+      flexDirection: 'row',
+      alignItems: 'stretch',
+      height: trackHeight,
+      borderRadius: trackRadius,
+      overflow: 'hidden',
+      width: '100%',
+      backgroundColor: 'transparent'
+    }, style],
+    children: renderedSegments
+  });
+}
+
+/**
+ * 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
+}) {
+  if (children !== undefined && children !== null) {
+    const flat = flattenChildren(children);
+    return flat.map((child, index) => {
+      if (! /*#__PURE__*/React.isValidElement(child)) {
+        return child;
+      }
+      const childProps = child.props ?? {};
+      const childModes = childProps.modes;
+      const mergedModes = {
+        ...modes,
+        'Emphasis / DataViz': defaultEmphasisFor(index),
+        ...(childModes || {})
+      };
+      return /*#__PURE__*/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 /*#__PURE__*/_jsx(SegmentedTrackSegment, {
+      value: segment.value ?? 1,
+      color: segment.color,
+      modes: segmentModes,
+      style: [segmentStyle, segment.style],
+      accessibilityLabel: segment.accessibilityLabel
+    }, segment.key ?? `segment-${index}`);
+  });
+}
+SegmentedTrack.Segment = SegmentedTrackSegment;
+export { SegmentedTrackSegment };
+export default SegmentedTrack;