jfs-components 0.1.2 → 0.1.8

package/lib/module/components/Slider/Slider.js

@@ -0,0 +1,468 @@
+"use strict";
+
+import React, { forwardRef, useCallback, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { View, Text, PanResponder, Platform } from 'react-native';
+import Svg, { Path } from 'react-native-svg';
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver';
+import { EMPTY_MODES } from '../../utils/react-utils';
+
+/**
+ * Imperative handle exposed via `ref`. The primary way to read a slider's value
+ * is still the controlled `value` + `onChange` pair (each `<Slider />` reports
+ * its own value, so multiple sliders are disambiguated by their own handlers).
+ * The ref is a convenience for reading the latest value on demand (e.g. on a
+ * button press) or imperatively nudging an uncontrolled slider.
+ *
+ * @example
+ * const slider = useRef<SliderHandle>(null)
+ * slider.current?.setValue(50)
+ * const v = slider.current?.getValue()
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const clamp = (n, min, max) => Math.min(Math.max(n, min), max);
+const asNum = (raw, fallback) => {
+  const n = typeof raw === 'number' ? raw : parseFloat(raw);
+  return Number.isFinite(n) ? n : fallback;
+};
+const asStr = (raw, fallback) => raw != null ? String(raw) : fallback;
+
+// The unfilled track is rendered at a lighter emphasis in the design.
+const TRACK_EMPHASIS = {
+  Emphasis: 'Low'
+};
+
+/**
+ * Slider — Figma node 5373:446 ("Slider").
+ *
+ * A horizontal, single-thumb slider driven entirely by design tokens. It maps a
+ * numeric range (`minValue`–`maxValue`) onto a track with a filled indicator, a
+ * draggable handle, a value bubble pinned above the handle, and optional min/max
+ * labels beneath the track. Built on `PanResponder` so the one code path works
+ * on iOS, Android and the web.
+ *
+ * The design only labels the range bounds, but a slider's purpose is to bind a
+ * value — so the live value is surfaced through the bubble (formatted via
+ * `formatOptions` / `formatValue`) and reported through `onChange` /
+ * `onChangeEnd`. Supports controlled and uncontrolled usage, web keyboard
+ * control, and an imperative {@link SliderHandle} `ref` for on-demand reads.
+ */
+const Slider = /*#__PURE__*/forwardRef(function Slider({
+  value: controlledValue,
+  defaultValue,
+  onChange,
+  onChangeEnd,
+  minValue = 0,
+  maxValue = 100,
+  step = 1,
+  isDisabled = false,
+  formatOptions,
+  locale,
+  formatValue,
+  renderTooltip,
+  alwaysShowTooltip = true,
+  showLabels = true,
+  minLabel,
+  maxLabel,
+  width = '100%',
+  modes = EMPTY_MODES,
+  style,
+  accessibilityLabel
+}, ref) {
+  const tokens = useMemo(() => resolveTokens(modes), [modes]);
+  const isControlled = controlledValue !== undefined;
+  const [internalValue, setInternalValue] = useState(() => clamp(defaultValue ?? minValue, minValue, maxValue));
+  const rawValue = isControlled ? controlledValue : internalValue;
+  const currentValue = clamp(rawValue, minValue, maxValue);
+  const [trackWidth, setTrackWidth] = useState(0);
+  const [tooltipWidth, setTooltipWidth] = useState(0);
+  const [isDragging, setIsDragging] = useState(false);
+  const [isHovered, setIsHovered] = useState(false);
+  const quantize = useCallback(v => {
+    if (!step || step <= 0) return clamp(v, minValue, maxValue);
+    const stepped = Math.round((v - minValue) / step) * step + minValue;
+    // Round away float dust introduced by the division (e.g. 0.30000000000004).
+    const decimals = (String(step).split('.')[1] || '').length;
+    const fixed = decimals > 0 ? Number(stepped.toFixed(decimals)) : stepped;
+    return clamp(fixed, minValue, maxValue);
+  }, [minValue, maxValue, step]);
+
+  // Keep the latest interactive config in a ref so the PanResponder (created
+  // once) always reads fresh values without being recreated mid-gesture.
+  const interaction = useRef({
+    trackWidth,
+    minValue,
+    maxValue,
+    isDisabled,
+    isControlled,
+    quantize,
+    onChange,
+    onChangeEnd
+  });
+  interaction.current = {
+    trackWidth,
+    minValue,
+    maxValue,
+    isDisabled,
+    isControlled,
+    quantize,
+    onChange,
+    onChangeEnd
+  };
+  const lastValueRef = useRef(currentValue);
+  lastValueRef.current = currentValue;
+  const commit = useCallback((next, isFinal) => {
+    const {
+      isControlled: ctrl,
+      onChange: change,
+      onChangeEnd: changeEnd
+    } = interaction.current;
+    const changed = next !== lastValueRef.current;
+    lastValueRef.current = next;
+    if (changed) {
+      if (!ctrl) setInternalValue(next);
+      change?.(next);
+    }
+    if (isFinal) changeEnd?.(next);
+  }, []);
+  const valueFromX = useCallback(x => {
+    const {
+      trackWidth: w,
+      minValue: min,
+      maxValue: max,
+      quantize: q
+    } = interaction.current;
+    if (w <= 0) return lastValueRef.current;
+    const ratio = clamp(x / w, 0, 1);
+    return q(min + ratio * (max - min));
+  }, []);
+  const panResponder = useRef(PanResponder.create({
+    onStartShouldSetPanResponder: () => !interaction.current.isDisabled,
+    onMoveShouldSetPanResponder: () => !interaction.current.isDisabled,
+    onPanResponderGrant: e => {
+      if (interaction.current.isDisabled) return;
+      setIsDragging(true);
+      commit(valueFromX(e.nativeEvent.locationX), false);
+    },
+    onPanResponderMove: e => {
+      if (interaction.current.isDisabled) return;
+      commit(valueFromX(e.nativeEvent.locationX), false);
+    },
+    onPanResponderRelease: e => {
+      setIsDragging(false);
+      if (interaction.current.isDisabled) return;
+      commit(valueFromX(e.nativeEvent.locationX), true);
+    },
+    onPanResponderTerminate: () => {
+      setIsDragging(false);
+      if (interaction.current.isDisabled) return;
+      commit(lastValueRef.current, true);
+    }
+  })).current;
+
+  // Keyboard support (web). Arrow/Page keys nudge, Home/End jump to bounds.
+  const handleKeyDown = useCallback(e => {
+    if (isDisabled) return;
+    const big = Math.max(step, (maxValue - minValue) / 10);
+    let next = null;
+    switch (e.key) {
+      case 'ArrowRight':
+      case 'ArrowUp':
+        next = quantize(currentValue + step);
+        break;
+      case 'ArrowLeft':
+      case 'ArrowDown':
+        next = quantize(currentValue - step);
+        break;
+      case 'PageUp':
+        next = quantize(currentValue + big);
+        break;
+      case 'PageDown':
+        next = quantize(currentValue - big);
+        break;
+      case 'Home':
+        next = minValue;
+        break;
+      case 'End':
+        next = maxValue;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault?.();
+    commit(next, true);
+  }, [isDisabled, step, minValue, maxValue, currentValue, quantize, commit]);
+  const handleAccessibilityAction = useCallback(event => {
+    if (isDisabled) return;
+    const name = event.nativeEvent.actionName;
+    if (name === 'increment') commit(quantize(currentValue + step), true);else if (name === 'decrement') commit(quantize(currentValue - step), true);
+  }, [isDisabled, step, currentValue, quantize, commit]);
+  useImperativeHandle(ref, () => ({
+    getValue: () => lastValueRef.current,
+    setValue: v => commit(quantize(v), true),
+    increment: by => commit(quantize(lastValueRef.current + (by ?? step)), true),
+    decrement: by => commit(quantize(lastValueRef.current - (by ?? step)), true)
+  }), [quantize, commit, step]);
+  const defaultFormat = useCallback(v => {
+    try {
+      return new Intl.NumberFormat(locale, formatOptions).format(v);
+    } catch {
+      return String(v);
+    }
+  }, [locale, formatOptions]);
+  const format = formatValue ?? defaultFormat;
+  const ratio = maxValue > minValue ? (currentValue - minValue) / (maxValue - minValue) : 0;
+  const percent = clamp(ratio, 0, 1) * 100;
+  const handleSize = tokens.handleSize;
+  // The bubble floats (absolutely positioned, no reserved layout space). When
+  // `alwaysShowTooltip` is false it only appears while interacting: dragging on
+  // any platform, or hovering on web. Lifting the finger clears `isDragging`,
+  // so the bubble disappears immediately on touch release.
+  const showTooltip = alwaysShowTooltip || isDragging || isHovered;
+  const onTrackLayout = useCallback(e => {
+    setTrackWidth(e.nativeEvent.layout.width);
+  }, []);
+  const onTooltipLayout = useCallback(e => {
+    setTooltipWidth(e.nativeEvent.layout.width);
+  }, []);
+  const valueText = format(currentValue);
+  const tooltipNode = showTooltip ? /*#__PURE__*/_jsxs(View, {
+    onLayout: onTooltipLayout,
+    style: [styles.tooltip, {
+      backgroundColor: tokens.tooltipBackground,
+      paddingHorizontal: tokens.tooltipPaddingH,
+      paddingVertical: tokens.tooltipPaddingV,
+      borderRadius: tokens.tooltipRadius,
+      maxWidth: tokens.tooltipMaxWidth,
+      bottom: handleSize + tokens.tooltipWrapGap,
+      // Pinned to the value point on the full-width track area (not
+      // the tiny handle-width thumb). An absolute child with only
+      // `left` set is clamped by Yoga to `parentWidth - left`, so
+      // parenting it to the 20px thumb collapsed the text to ~0px
+      // and rendered an empty bubble on device. Centre via translate.
+      left: `${percent}%`,
+      transform: [{
+        translateX: -tooltipWidth / 2
+      }]
+    }],
+    pointerEvents: "none",
+    children: [renderTooltip ? renderTooltip(currentValue) : /*#__PURE__*/_jsx(Text, {
+      style: tokens.tooltipLabel,
+      numberOfLines: 1,
+      children: valueText
+    }), /*#__PURE__*/_jsx(View, {
+      style: [styles.tip, {
+        bottom: -tokens.tipHeight
+      }],
+      pointerEvents: "none",
+      children: /*#__PURE__*/_jsx(Svg, {
+        width: tokens.tipWidth,
+        height: tokens.tipHeight,
+        viewBox: `0 0 ${tokens.tipWidth} ${tokens.tipHeight}`,
+        children: /*#__PURE__*/_jsx(Path, {
+          d: `M0 0 L${tokens.tipWidth / 2} ${tokens.tipHeight} L${tokens.tipWidth} 0 Z`,
+          fill: tokens.tooltipBackground
+        })
+      })
+    })]
+  }) : null;
+  return /*#__PURE__*/_jsxs(View, {
+    style: [{
+      width,
+      gap: tokens.gap,
+      paddingTop: tokens.paddingTop,
+      paddingBottom: tokens.paddingBottom,
+      paddingLeft: tokens.paddingLeft,
+      paddingRight: tokens.paddingRight,
+      opacity: isDisabled ? 0.5 : 1
+    }, style],
+    accessibilityLabel: accessibilityLabel,
+    children: [/*#__PURE__*/_jsxs(View, {
+      ...panResponder.panHandlers,
+      onLayout: onTrackLayout,
+      style: [styles.trackArea, {
+        height: handleSize
+      }],
+      accessible: true,
+      accessibilityRole: "adjustable",
+      accessibilityLabel: accessibilityLabel,
+      accessibilityValue: {
+        min: minValue,
+        max: maxValue,
+        now: currentValue,
+        text: valueText
+      },
+      accessibilityState: {
+        disabled: isDisabled
+      },
+      accessibilityActions: [{
+        name: 'increment'
+      }, {
+        name: 'decrement'
+      }],
+      onAccessibilityAction: handleAccessibilityAction,
+      focusable: !isDisabled,
+      ...(Platform.OS === 'web' ? {
+        onKeyDown: handleKeyDown,
+        tabIndex: isDisabled ? -1 : 0,
+        onMouseEnter: () => !isDisabled && setIsHovered(true),
+        onMouseLeave: () => setIsHovered(false)
+      } : {}),
+      children: [/*#__PURE__*/_jsx(View, {
+        style: {
+          height: tokens.trackHeight,
+          borderRadius: tokens.trackRadius,
+          backgroundColor: tokens.trackBackground
+        }
+      }), /*#__PURE__*/_jsx(View, {
+        pointerEvents: "none",
+        style: {
+          position: 'absolute',
+          left: 0,
+          top: (handleSize - tokens.indicatorHeight) / 2,
+          height: tokens.indicatorHeight,
+          width: `${percent}%`,
+          borderRadius: tokens.indicatorRadius,
+          backgroundColor: tokens.indicatorBackground
+        }
+      }), /*#__PURE__*/_jsx(View, {
+        pointerEvents: "none",
+        style: {
+          position: 'absolute',
+          top: 0,
+          left: `${percent}%`,
+          width: handleSize,
+          height: handleSize,
+          transform: [{
+            translateX: -handleSize / 2
+          }]
+        },
+        children: /*#__PURE__*/_jsx(View, {
+          style: {
+            width: handleSize,
+            height: handleSize,
+            borderRadius: tokens.handleRadius,
+            backgroundColor: tokens.handleBackground
+          }
+        })
+      }), tooltipNode]
+    }), showLabels ? /*#__PURE__*/_jsxs(View, {
+      style: styles.labelWrap,
+      children: [/*#__PURE__*/_jsx(Text, {
+        style: tokens.label,
+        children: minLabel ?? format(minValue)
+      }), /*#__PURE__*/_jsx(Text, {
+        style: tokens.label,
+        children: maxLabel ?? format(maxValue)
+      })]
+    }) : null]
+  });
+});
+function resolveTokens(modes) {
+  // NOTE: token names are passed as string literals DIRECTLY to
+  // getVariableByName so the `extract-component-tokens` script can statically
+  // collect them for the generated docs. Do not refactor into a helper that
+  // receives the name as a variable.
+  const gap = asNum(getVariableByName('slider/gap', modes), 16);
+  const paddingTop = asNum(getVariableByName('slider/padding/top', modes), 8);
+  const paddingBottom = asNum(getVariableByName('slider/padding/bottom', modes), 0);
+  const paddingLeft = asNum(getVariableByName('slider/padding/left', modes), 0);
+  const paddingRight = asNum(getVariableByName('slider/padding/right', modes), 0);
+  const trackHeight = asNum(getVariableByName('slider/track/height', modes), 4);
+  const trackRadius = asNum(getVariableByName('slider/track/radius', modes), 999);
+  // The unfilled track uses a lighter emphasis in the design; consumer modes
+  // still win over the baked-in `Emphasis: Low`.
+  const trackBackground = asStr(getVariableByName('slider/track/background', {
+    ...TRACK_EMPHASIS,
+    ...modes
+  }), '#fde8c9');
+  const indicatorHeight = asNum(getVariableByName('slider/indicator/height', modes), 4);
+  const indicatorRadius = asNum(getVariableByName('slider/indicator/radius', modes), 999);
+  const indicatorBackground = asStr(getVariableByName('slider/indicator/background', modes), '#f7ab21');
+  const handleSize = asNum(getVariableByName('slider/handle/size', modes), 20);
+  const handleRadius = asNum(getVariableByName('slider/handle/radius', modes), 999999);
+  const handleBackground = asStr(getVariableByName('slider/handle/background', modes), '#f7ab21');
+  const tooltipWrapGap = asNum(getVariableByName('slider/tooltipWrap/gap', modes), 12);
+  const tooltipBackground = asStr(getVariableByName('tooltip/background', modes), '#0f0d0a');
+  const tooltipPaddingH = asNum(getVariableByName('tooltip/padding/horizontal', modes), 12);
+  const tooltipPaddingV = asNum(getVariableByName('tooltip/padding/vertical', modes), 8);
+  const tooltipRadius = asNum(getVariableByName('radius', modes), 8);
+  const tooltipMaxWidth = asNum(getVariableByName('maxWidth', modes), 280);
+  const tipWidth = asNum(getVariableByName('tooltip/tipItem/width', modes), 16);
+  const tipHeight = asNum(getVariableByName('tooltip/tipItem/height', modes), 8);
+  const tooltipLabelColor = asStr(getVariableByName('tooltip/label/color', modes), '#ffffff');
+  const tooltipLabelSize = asNum(getVariableByName('tooltip/label/fontSize', modes), 14);
+  const tooltipLabelFamily = asStr(getVariableByName('tooltip/lable/fontFamily', modes), 'JioType Var');
+  const tooltipLabelLineHeight = asNum(getVariableByName('tooltip/label/lineHeight', modes), 18);
+  const tooltipLabelWeight = asStr(getVariableByName('tooltip/label/fontWeight', modes), '500');
+  const labelColor = asStr(getVariableByName('text/foreground', modes), '#000000');
+  const labelSize = asNum(getVariableByName('text/fontSize', modes), 14);
+  const labelFamily = asStr(getVariableByName('text/fontFamily', modes), 'JioType Var');
+  const labelLineHeight = asNum(getVariableByName('text/lineHeight', modes), 20);
+  const labelWeight = asStr(getVariableByName('text/fontWeight', modes), '500');
+  const labelLetterSpacing = asNum(getVariableByName('text/letterSpacing', modes), -0.5);
+  return {
+    gap,
+    paddingTop,
+    paddingBottom,
+    paddingLeft,
+    paddingRight,
+    trackHeight,
+    trackRadius,
+    trackBackground,
+    indicatorHeight,
+    indicatorRadius,
+    indicatorBackground,
+    handleSize,
+    handleRadius,
+    handleBackground,
+    tooltipWrapGap,
+    tooltipBackground,
+    tooltipPaddingH,
+    tooltipPaddingV,
+    tooltipRadius,
+    tooltipMaxWidth,
+    tooltipLineHeight: tooltipLabelLineHeight,
+    tipWidth,
+    tipHeight,
+    tooltipLabel: {
+      color: tooltipLabelColor,
+      fontSize: tooltipLabelSize,
+      fontFamily: tooltipLabelFamily,
+      lineHeight: tooltipLabelLineHeight,
+      fontWeight: tooltipLabelWeight,
+      includeFontPadding: false
+    },
+    label: {
+      color: labelColor,
+      fontSize: labelSize,
+      fontFamily: labelFamily,
+      lineHeight: labelLineHeight,
+      fontWeight: labelWeight,
+      letterSpacing: labelLetterSpacing,
+      includeFontPadding: false
+    }
+  };
+}
+const styles = {
+  trackArea: {
+    width: '100%',
+    justifyContent: 'center',
+    position: 'relative'
+  },
+  labelWrap: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'flex-start',
+    width: '100%'
+  },
+  tooltip: {
+    position: 'absolute',
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  tip: {
+    position: 'absolute',
+    alignSelf: 'center'
+  }
+};
+export default Slider;

package/lib/module/components/TextInput/TextInput.js

@@ -1,10 +1,10 @@
 "use strict";
 
-import React, { useRef, useState } from 'react';
+import React, { forwardRef, useRef, useState } from 'react';
 import { Platform, Pressable, View, TextInput as RNTextInput } from 'react-native';
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver';
 import Icon from '../../icons/Icon';
-import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils';
+import { EMPTY_MODES, cloneChildrenWithModes, mergeRefs } from '../../utils/react-utils';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * TextInput component that mirrors the Figma "textInput" component.
@@ -95,7 +95,7 @@ function makePlaceholderColor(color, opacity = 0.5) {
   // Fallback: return original color
   return color;
 }
-function TextInput({
+const TextInputBase = /*#__PURE__*/forwardRef(function TextInput({
   placeholder = '',
   value = '',
   onChangeText,
@@ -110,7 +110,7 @@ function TextInput({
   accessibilityLabel,
   accessibilityHint,
   ...rest
-}) {
+}, ref) {
   // Track focus state to hide placeholder when focused
   const [isFocused, setIsFocused] = useState(false);
   const [isHovered, setIsHovered] = useState(false);
@@ -225,7 +225,7 @@ function TextInput({
       importantForAccessibility: "no",
       children: processedLeading
     }), /*#__PURE__*/_jsx(RNTextInput, {
-      ref: inputRef,
+      ref: mergeRefs(inputRef, ref),
       accessibilityLabel: undefined,
       accessibilityHint: accessibilityHint,
       placeholder: displayPlaceholder,
@@ -258,7 +258,7 @@ function TextInput({
     style: containerStyleArray,
     children: inner
   });
-}
+});
 
 /**
  * TextInput.Search component that mirrors the Figma "textInput.search" component.
@@ -280,7 +280,7 @@ function TextInput({
  * @param {Object} [props.rest] - Additional props passed to the underlying TextInput
  */
 
-function TextInputSearch({
+const TextInputSearch = /*#__PURE__*/forwardRef(function TextInputSearch({
   placeholder = 'Search',
   value = '',
   onChangeText,
@@ -293,7 +293,7 @@ function TextInputSearch({
   onFocus,
   onBlur,
   ...rest
-}) {
+}, ref) {
   // Resolve icon tokens for default search icon
   const iconColor = getVariableByName('textInput/icon/color', modes) || '#24262b';
   const iconSize = getVariableByName('textInput/icon/size', modes) || 18;
@@ -330,10 +330,15 @@ function TextInputSearch({
     textInputProps.accessibilityHint = accessibilityHint;
   }
   return /*#__PURE__*/_jsx(TextInput, {
+    ref: ref,
     ...textInputProps
   });
-}
+});
+
+// Attach Search as a property of TextInput using namespace pattern. The base
+// component is created via forwardRef, so we compose the static onto a typed
+// alias to keep `TextInput.Search` strongly typed.
 
-// Attach Search as a property of TextInput using namespace pattern
+const TextInput = TextInputBase;
 TextInput.Search = TextInputSearch;
 export default TextInput;

package/lib/module/components/TextSegment/TextSegment.js

@@ -0,0 +1,113 @@
+"use strict";
+
+import React, { useMemo } from 'react';
+import { Text as RNText } from 'react-native';
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver';
+import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils';
+
+/**
+ * A single coloured run inside a {@link TextSegment}. Each run can carry its own
+ * `modes`, so individual fragments of the same paragraph can resolve different
+ * design tokens (most commonly a different `text/foreground` colour) while still
+ * flowing — and wrapping — inline as one continuous line of text.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+const TEXT_ALIGN_MAP = {
+  Left: 'left',
+  Center: 'center'
+};
+
+/**
+ * Resolves the `text/*` design tokens for a given modes object into an RN
+ * `TextStyle`. Shared by the outer paragraph and every inline run so a run that
+ * only overrides colour still inherits the family/size/weight/spacing.
+ */
+function resolveTextStyle(modes) {
+  return {
+    color: getVariableByName('text/foreground', modes) ?? '#000000',
+    fontFamily: getVariableByName('text/fontFamily', modes) ?? 'JioType',
+    fontSize: getVariableByName('text/fontSize', modes) ?? 14,
+    fontWeight: String(getVariableByName('text/fontWeight', modes) ?? '500'),
+    lineHeight: getVariableByName('text/lineHeight', modes) ?? 20,
+    letterSpacing: getVariableByName('text/letterSpacing', modes) ?? -0.5
+  };
+}
+
+/**
+ * TextSegment — composes several differently-styled text runs into a single
+ * paragraph that wraps as one continuous line.
+ *
+ * On the web you would reach for `<span>`s inside a `<p>`; the React Native
+ * equivalent is nesting `<Text>` inside a parent `<Text>`. That nesting is the
+ * whole trick: sibling `<View>`s would lay out as flex blocks and break onto
+ * rigid rows, but nested `<Text>` nodes flow inline and wrap naturally at word
+ * boundaries — exactly like a real paragraph — while each nested run keeps its
+ * own colour/weight resolved from its own `modes`.
+ *
+ * Two equivalent ways to author content:
+ *  - **`segments` prop** — declarative array of `{ text, modes }` runs.
+ *  - **`children`** — pass library `Text` elements (or strings); the parent
+ *    `modes` cascade down and each child may override its own.
+ *
+ * @example Data-driven
+ * ```tsx
+ * <TextSegment
+ *   segments={[
+ *     { text: 'Upsell message ' },
+ *     { text: 'JioFinance+', modes: { 'Text Appearance': 'Primary' } },
+ *   ]}
+ * />
+ * ```
+ *
+ * @example Compositional
+ * ```tsx
+ * <TextSegment numberOfLines={2}>
+ *   <Text>Pay with </Text>
+ *   <Text modes={{ 'Text Appearance': 'Primary' }}>JioFinance+</Text>
+ *   <Text> and earn rewards on every transaction.</Text>
+ * </TextSegment>
+ * ```
+ */
+function TextSegment({
+  segments,
+  children,
+  textAlign = 'Left',
+  numberOfLines,
+  modes = EMPTY_MODES,
+  style
+}) {
+  const baseStyle = useMemo(() => ({
+    ...resolveTextStyle(modes),
+    textAlign: TEXT_ALIGN_MAP[textAlign]
+  }), [modes, textAlign]);
+
+  // children win over `segments` so the compositional API can always override.
+  const hasChildren = children !== undefined && children !== null && children !== false;
+  const renderedSegments = useMemo(() => {
+    if (hasChildren || !segments?.length) return null;
+    return segments.map((run, index) => {
+      // Parent modes first, then the run's own modes override them — mirrors the
+      // merge order used by `cloneChildrenWithModes` for the children API.
+      const runModes = run.modes ? {
+        ...modes,
+        ...run.modes
+      } : modes;
+      const runStyle = run.modes ? resolveTextStyle(runModes) : undefined;
+      return /*#__PURE__*/_jsx(RNText, {
+        style: [runStyle, run.style],
+        children: run.text
+      }, index);
+    });
+  }, [segments, hasChildren, modes]);
+
+  // The cascade: every child (and its descendants) receives the parent modes so
+  // nested library `Text` runs resolve their tokens against the same baseline,
+  // while still honouring any per-child `modes` override.
+  const content = hasChildren ? cloneChildrenWithModes(children, modes) : renderedSegments;
+  return /*#__PURE__*/_jsx(RNText, {
+    style: [baseStyle, style],
+    numberOfLines: numberOfLines,
+    children: content
+  });
+}
+export default /*#__PURE__*/React.memo(TextSegment);