jfs-components 0.1.23 → 0.1.28

package/src/components/FormUpload/FormUpload.tsx

@@ -0,0 +1,313 @@
+import React, { useMemo, useCallback } from 'react'
+import { View, Text, type StyleProp, type ViewStyle, type TextStyle } from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
+import { useFormContext } from '../Form/Form'
+import SupportText from '../SupportText/SupportText'
+import Additem, { type AdditemProps, type PickedAsset } from './Additem'
+import type { Modes } from '../../design-tokens'
+
+export type FormUploadAttachment = PickedAsset
+
+export type FormUploadProps = {
+  /** Label rendered above the upload row. */
+  label?: string
+  /**
+   * Helper text rendered below the upload row. When `errorMessage` is provided,
+   * it replaces the support text and renders in the error status.
+   */
+  supportText?: string
+  /**
+   * Field name. When used inside `<Form>`, this is the key used to look up
+   * server-side `validationErrors`.
+   */
+  name?: string
+  /**
+   * Controlled list of attachments. Each item maps to an `Additem` cell:
+   * render attachments as `'preview'` cells and leave the last slot as the
+   * `'empty'` upload trigger.
+   */
+  attachments?: FormUploadAttachment[]
+  /**
+   * Maximum number of attachments allowed. When omitted, the component renders
+   * a single empty upload trigger. Once `attachments.length` reaches `maxCount`,
+   * the empty trigger is hidden.
+   */
+  maxCount?: number
+  /**
+   * Called when the attachment list should change (add or remove). The parent
+   * is responsible for updating the `attachments` array.
+   */
+  onAttachmentsChange?: (attachments: FormUploadAttachment[]) => void
+  /**
+   * Optional picker injected by the parent. This keeps the component free of
+   * native-library dependencies while still providing real upload behaviour on
+   * iOS/Android. The picker should wrap `react-native-image-picker`,
+   * `expo-image-picker`, `react-native-document-picker`, etc.
+   */
+  picker?: AdditemProps['picker']
+  /**
+   * Error message shown below the row. When provided inside `<Form>`, the form
+   * context error is used automatically unless this prop is set explicitly.
+   */
+  errorMessage?: string
+  /** Marks the field as invalid. Also set automatically by `<Form>` errors. */
+  isInvalid?: boolean
+  /** Disables all upload interaction. */
+  isDisabled?: boolean
+  /**
+   * Custom children/slot rendered in place of the generated `Additem` cells.
+   * Useful when the consumer wants full control over the upload row. `modes`
+   * cascade into slot children automatically.
+   */
+  children?: React.ReactNode
+  /** Modes for design-token resolution. */
+  modes?: Modes
+  /** Style overrides for the outermost wrapper. */
+  style?: StyleProp<ViewStyle>
+  /** Style overrides for the upload row container. */
+  rowStyle?: StyleProp<ViewStyle>
+  /** Accessibility label. Defaults to `label`. */
+  accessibilityLabel?: string
+  /** Test identifier. */
+  testID?: string
+}
+
+function toNumber(value: unknown, fallback: number): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const parsed = parseFloat(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return fallback
+}
+
+function toFontWeight(value: unknown, fallback: TextStyle['fontWeight']): TextStyle['fontWeight'] {
+  if (typeof value === 'number') return value.toString() as TextStyle['fontWeight']
+  if (typeof value === 'string' && value.length > 0) return value as TextStyle['fontWeight']
+  return fallback
+}
+
+interface FormUploadTokens {
+  gap: number
+  rowGap: number
+  labelColor: string
+  labelFontFamily: string
+  labelFontSize: number
+  labelLineHeight: number
+  labelFontWeight: TextStyle['fontWeight']
+}
+
+function resolveFormUploadTokens(modes: Modes): FormUploadTokens {
+  const gap = toNumber(getVariableByName('formField/input/gap', modes), 8)
+  const rowGap = toNumber(getVariableByName('formField/gap', modes), 8)
+
+  const labelColor = getVariableByName('formField/label/color', modes) as string
+  const labelFontFamily = getVariableByName('formField/label/fontFamily', modes) as string
+  const labelFontSize = toNumber(getVariableByName('formField/label/fontSize', modes), 14)
+  const labelLineHeight = toNumber(getVariableByName('formField/label/lineHeight', modes), 17)
+  const labelFontWeight = toFontWeight(getVariableByName('formField/label/fontWeight', modes), '500')
+
+  return {
+    gap,
+    rowGap,
+    labelColor,
+    labelFontFamily,
+    labelFontSize,
+    labelLineHeight,
+    labelFontWeight,
+  }
+}
+
+function firstError(error: string | string[] | undefined): string | undefined {
+  if (!error) return undefined
+  if (Array.isArray(error)) return error[0]
+  return error
+}
+
+/** Figma defaults for the remove `IconCapsule` on filled preview cells. Overridable via `modes`. */
+const FORM_UPLOAD_PREVIEW_ICON_CAPSULE_MODES: Modes = {
+  AppearanceBrand: 'Neutral',
+  Emphasis: 'Medium',
+  'Icon Capsule Size': 'XS',
+}
+
+/**
+ * `FormUpload` — a form-aware upload row built from reusable `Additem` cells.
+ *
+ * The component mirrors the Figma "FormUpload" design: a label, a horizontal
+ * row of upload/preview cells, and support text. It integrates with the
+ * existing `<Form>` context so server-side validation errors automatically
+ * show below the row, and it clears those errors when attachments change.
+ *
+ * Upload behaviour is provided through the `picker` prop so the library stays
+ * free of native image-picker dependencies. Pass any picker that returns the
+ * `AdditemPickerResult` shape and the empty cell becomes a real upload trigger
+ * on both iOS and Android.
+ */
+function FormUpload({
+  label,
+  supportText,
+  name,
+  attachments = [],
+  maxCount,
+  onAttachmentsChange,
+  picker,
+  errorMessage,
+  isInvalid = false,
+  isDisabled = false,
+  children,
+  modes: propModes = EMPTY_MODES,
+  style,
+  rowStyle,
+  accessibilityLabel,
+  testID,
+}: FormUploadProps) {
+  const formCtx = useFormContext()
+  const formError = name && formCtx ? firstError(formCtx.validationErrors[name]) : undefined
+  const resolvedIsInvalid = isInvalid || Boolean(formError)
+  const resolvedErrorMessage = errorMessage ?? formError
+
+  const { modes: globalModes } = useTokens()
+  const baseModes = useMemo(
+    () =>
+      globalModes === EMPTY_MODES && propModes === EMPTY_MODES
+        ? EMPTY_MODES
+        : { ...globalModes, ...propModes },
+    [globalModes, propModes],
+  )
+
+  const modes = useMemo(
+    () => ({
+      ...baseModes,
+      'FormField States': resolvedIsInvalid ? 'Error' : 'Idle',
+      Status: resolvedIsInvalid ? 'Error' : 'Auto',
+    }),
+    [baseModes, resolvedIsInvalid],
+  )
+
+  // Empty cells rely on `Additem`'s built-in Neutral / Low / S defaults for the
+  // add icon. Preview cells use the tighter remove-icon treatment from Figma.
+  const previewAdditemModes = useMemo(
+    () => ({ ...FORM_UPLOAD_PREVIEW_ICON_CAPSULE_MODES, ...modes }),
+    [modes],
+  )
+
+  const tokens = useMemo(() => resolveFormUploadTokens(modes), [modes])
+
+  const handleAssetsPicked = useCallback(
+    (assets: PickedAsset[]) => {
+      if (isDisabled) return
+      const next = [...attachments, ...assets]
+      if (maxCount != null && next.length > maxCount) {
+        next.length = maxCount
+      }
+      onAttachmentsChange?.(next)
+      if (name && formCtx) {
+        formCtx.onFieldChange(name)
+      }
+    },
+    [attachments, maxCount, onAttachmentsChange, isDisabled, name, formCtx],
+  )
+
+  const handleRemove = useCallback(
+    (index: number) => {
+      if (isDisabled) return
+      const next = attachments.filter((_, i) => i !== index)
+      onAttachmentsChange?.(next)
+      if (name && formCtx) {
+        formCtx.onFieldChange(name)
+      }
+    },
+    [attachments, onAttachmentsChange, isDisabled, name, formCtx],
+  )
+
+  const containerStyle: ViewStyle = useMemo(
+    () => ({
+      gap: tokens.gap,
+      opacity: isDisabled ? 0.5 : 1,
+    }),
+    [tokens.gap, isDisabled],
+  )
+
+  const rowStyleResolved: ViewStyle = useMemo(
+    () => ({
+      flexDirection: 'row',
+      flexWrap: 'wrap',
+      gap: tokens.rowGap,
+      alignItems: 'flex-start',
+    }),
+    [tokens.rowGap],
+  )
+
+  const labelStyle: TextStyle = useMemo(
+    () => ({
+      color: tokens.labelColor,
+      fontFamily: tokens.labelFontFamily,
+      fontSize: tokens.labelFontSize,
+      lineHeight: tokens.labelLineHeight,
+      fontWeight: tokens.labelFontWeight,
+    }),
+    [tokens],
+  )
+
+  const resolvedA11yLabel = accessibilityLabel ?? label ?? 'Attachment upload'
+
+  const canAddMore = maxCount == null || attachments.length < maxCount
+
+  const renderContent = () => {
+    if (children) {
+      return cloneChildrenWithModes(children, modes)
+    }
+
+    return (
+      <>
+        {attachments.map((attachment, index) => (
+          <Additem
+            key={`${attachment.uri}-${index}`}
+            state="preview"
+            imageSource={attachment.uri}
+            onRemove={() => handleRemove(index)}
+            modes={previewAdditemModes}
+            isDisabled={isDisabled}
+            accessibilityLabel={attachment.name ?? `Attachment ${index + 1}`}
+            testID={`${testID}-item-${index}`}
+          />
+        ))}
+        {canAddMore && (
+          <Additem
+            state="empty"
+            picker={picker}
+            onAssetsPicked={handleAssetsPicked}
+            modes={modes}
+            isDisabled={isDisabled}
+            testID={`${testID}-add`}
+          />
+        )}
+      </>
+    )
+  }
+
+  const supportLabel = resolvedIsInvalid && resolvedErrorMessage ? resolvedErrorMessage : supportText
+  const supportStatus = resolvedIsInvalid ? 'Error' : 'Neutral'
+
+  return (
+    <View
+      style={[containerStyle, style]}
+      accessibilityRole="none"
+      accessibilityLabel={resolvedA11yLabel}
+      testID={testID}
+    >
+      {label != null && label !== '' && <Text style={labelStyle}>{label}</Text>}
+
+      <View style={[rowStyleResolved, rowStyle]}>{renderContent()}</View>
+
+      {supportLabel != null && supportLabel !== '' && (
+        <SupportText label={supportLabel} status={supportStatus} modes={modes} />
+      )}
+    </View>
+  )
+}
+
+export default React.memo(FormUpload)

package/src/components/Grid/Grid.tsx

@@ -0,0 +1,368 @@
+import React, { useMemo } 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, cloneChildrenWithModes, flattenChildren } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
+
+export type GridJustifyContent = 'start' | 'stretch' | 'space-between'
+export type GridAlignItems = 'start' | 'stretch' | 'center'
+
+export type GridProps = {
+  /**
+   * Number of columns per row. Defaults to `1`. Children flow left-to-right,
+   * top-to-bottom into this many columns.
+   */
+  columns?: number
+  /**
+   * Fixed row count. When set, the grid always renders `columns × rows` cells.
+   * Missing cells render as empty placeholders so the geometry stays stable.
+   * When omitted, the row count is derived from the number of children.
+   */
+  rows?: number
+  /**
+   * Fractional column track weights — the React Native equivalent of CSS
+   * `grid-template-columns: 1fr 2fr 1fr`. Each value becomes a `flex` grow
+   * weight on the matching column. Shorter arrays repeat the last weight;
+   * omitted values default to equal `1fr` columns.
+   */
+  columnFrs?: readonly number[]
+  /**
+   * Fractional row track weights. When provided, each row container receives
+   * a matching `flexGrow` weight. Useful when the grid should fill a fixed
+   * height and rows should share space proportionally.
+   */
+  rowFrs?: readonly number[]
+  /** Override the resolved column gap token. */
+  columnGap?: number
+  /** Override the resolved row gap token. */
+  rowGap?: number
+  /**
+   * Shorthand gap override applied when `columnGap` / `rowGap` are not set
+   * individually. Falls back to the `Grid/gap` token.
+   */
+  gap?: number
+  /** Uniform padding override for all sides. */
+  padding?: number
+  paddingHorizontal?: number
+  paddingVertical?: number
+  paddingTop?: number
+  paddingBottom?: number
+  paddingLeft?: number
+  paddingRight?: number
+  /**
+   * How cells are distributed along each row.
+   * - `'stretch'` (default) — cells expand using `columnFrs`.
+   * - `'start'` — cells hug the leading edge; trailing space stays empty.
+   * - `'space-between'` — leftover space is distributed between cells
+   *   (first cell flush-left, last cell flush-right).
+   */
+  justifyContent?: GridJustifyContent
+  /** Cross-axis alignment applied to every cell wrapper. Defaults to `'stretch'`. */
+  alignItems?: GridAlignItems
+  /**
+   * Slot content. Each child becomes one grid cell. `modes` cascade into all
+   * slot children automatically.
+   */
+  children?: React.ReactNode
+  /** Design token modes (e.g. `{ 'Slot gap': 'M' }`). */
+  modes?: Modes
+  /** Style override for the outer container. */
+  style?: StyleProp<ViewStyle>
+  /** Style override for the inner rows wrapper. */
+  contentStyle?: StyleProp<ViewStyle>
+  /** Style applied to every cell wrapper. */
+  cellStyle?: StyleProp<ViewStyle>
+  /** Accessibility label for the grid container. */
+  accessibilityLabel?: string
+  testID?: string
+}
+
+function toNumber(value: unknown, fallback: number): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const parsed = parseFloat(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return fallback
+}
+
+interface GridTokens {
+  backgroundColor: string
+  columnGap: number
+  rowGap: number
+  paddingTop: number
+  paddingBottom: number
+  paddingLeft: number
+  paddingRight: number
+}
+
+function resolveGridTokens(modes: Modes): GridTokens {
+  const gapFallback = toNumber(getVariableByName('Grid/gap', modes), 8)
+  const columnGap = toNumber(getVariableByName('Grid/column/gap', modes), gapFallback)
+  const rowGap = toNumber(getVariableByName('Grid/row/gap', modes), gapFallback)
+
+  const paddingHorizontal = toNumber(getVariableByName('Grid/padding/horizontal', modes), 8)
+  const paddingVertical = toNumber(getVariableByName('Grid/padding/vertical', modes), 8)
+  const paddingTop = toNumber(getVariableByName('Grid/padding/top', modes), paddingVertical)
+  const paddingBottom = toNumber(getVariableByName('Grid/padding/bottom', modes), paddingVertical)
+  const paddingLeft = toNumber(getVariableByName('Grid/padding/left', modes), paddingHorizontal)
+  const paddingRight = toNumber(getVariableByName('Grid/padding/right', modes), paddingHorizontal)
+
+  const backgroundColor =
+    (getVariableByName('Grid/background/color', modes) as string | null) ?? 'transparent'
+
+  return {
+    backgroundColor,
+    columnGap,
+    rowGap,
+    paddingTop,
+    paddingBottom,
+    paddingLeft,
+    paddingRight,
+  }
+}
+
+function normalizeFrs(frs: readonly number[] | undefined, count: number): number[] {
+  if (!frs || frs.length === 0) {
+    return Array.from({ length: count }, () => 1)
+  }
+  return Array.from({ length: count }, (_, index) => {
+    const value = frs[index] ?? frs[frs.length - 1] ?? 1
+    return value > 0 ? value : 1
+  })
+}
+
+function resolveAlignSelf(alignItems: GridAlignItems): ViewStyle['alignSelf'] {
+  if (alignItems === 'center') return 'center'
+  if (alignItems === 'start') return 'flex-start'
+  return 'stretch'
+}
+
+function resolveRowJustifyContent(justifyContent: GridJustifyContent): ViewStyle['justifyContent'] {
+  if (justifyContent === 'space-between') return 'space-between'
+  if (justifyContent === 'start') return 'flex-start'
+  return 'flex-start'
+}
+
+function buildCellStyle(
+  columnFr: number,
+  justifyContent: GridJustifyContent,
+  alignItems: GridAlignItems,
+): ViewStyle {
+  const alignSelf = resolveAlignSelf(alignItems)
+
+  if (justifyContent === 'space-between' || justifyContent === 'start') {
+    return {
+      flexGrow: 0,
+      flexShrink: 1,
+      flexBasis: 'auto',
+      minWidth: 0,
+      alignSelf,
+    }
+  }
+
+  return {
+    flex: columnFr,
+    minWidth: 0,
+    alignSelf,
+  }
+}
+
+/**
+ * `Grid` — a token-driven layout grid for React Native.
+ *
+ * Mirrors the Figma "Grid" component: a padded container with configurable
+ * columns, rows, fractional column tracks (`columnFrs`), and gap tokens.
+ * Each slot child maps to one cell — no separate `GridItem` wrapper is needed.
+ *
+ * @component
+ */
+function Grid({
+  columns = 1,
+  rows,
+  columnFrs,
+  rowFrs,
+  columnGap: columnGapProp,
+  rowGap: rowGapProp,
+  gap: gapProp,
+  padding: paddingProp,
+  paddingHorizontal: paddingHorizontalProp,
+  paddingVertical: paddingVerticalProp,
+  paddingTop: paddingTopProp,
+  paddingBottom: paddingBottomProp,
+  paddingLeft: paddingLeftProp,
+  paddingRight: paddingRightProp,
+  justifyContent = 'stretch',
+  alignItems = 'stretch',
+  children,
+  modes: propModes = EMPTY_MODES,
+  style,
+  contentStyle,
+  cellStyle,
+  accessibilityLabel,
+  testID,
+}: GridProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = useMemo(
+    () =>
+      globalModes === EMPTY_MODES && propModes === EMPTY_MODES
+        ? EMPTY_MODES
+        : { ...globalModes, ...propModes },
+    [globalModes, propModes],
+  )
+
+  const tokens = useMemo(() => resolveGridTokens(modes), [modes])
+
+  const resolvedColumnGap = columnGapProp ?? gapProp ?? tokens.columnGap
+  const resolvedRowGap = rowGapProp ?? gapProp ?? tokens.rowGap
+
+  const resolvedPadding = useMemo(
+    () => ({
+      paddingTop: paddingTopProp ?? paddingVerticalProp ?? paddingProp ?? tokens.paddingTop,
+      paddingBottom: paddingBottomProp ?? paddingVerticalProp ?? paddingProp ?? tokens.paddingBottom,
+      paddingLeft: paddingLeftProp ?? paddingHorizontalProp ?? paddingProp ?? tokens.paddingLeft,
+      paddingRight: paddingRightProp ?? paddingHorizontalProp ?? paddingProp ?? tokens.paddingRight,
+    }),
+    [
+      paddingTopProp,
+      paddingBottomProp,
+      paddingLeftProp,
+      paddingRightProp,
+      paddingHorizontalProp,
+      paddingVerticalProp,
+      paddingProp,
+      tokens,
+    ],
+  )
+
+  const safeColumns = Math.max(1, Math.floor(columns))
+
+  const processedChildren = useMemo(
+    () => cloneChildrenWithModes(flattenChildren(children), modes),
+    [children, modes],
+  )
+
+  const cellNodes = useMemo(() => {
+    const nodes = [...processedChildren]
+    if (rows != null) {
+      const targetCount = safeColumns * Math.max(1, Math.floor(rows))
+      while (nodes.length < targetCount) {
+        nodes.push(null)
+      }
+      if (nodes.length > targetCount) {
+        nodes.length = targetCount
+      }
+    }
+    return nodes
+  }, [processedChildren, rows, safeColumns])
+
+  const gridRows = useMemo(() => {
+    const result: React.ReactNode[][] = []
+    for (let index = 0; index < cellNodes.length; index += safeColumns) {
+      result.push(cellNodes.slice(index, index + safeColumns))
+    }
+    return result
+  }, [cellNodes, safeColumns])
+
+  const normalizedColumnFrs = useMemo(
+    () => normalizeFrs(columnFrs, safeColumns),
+    [columnFrs, safeColumns],
+  )
+
+  const normalizedRowFrs = useMemo(
+    () => (rowFrs ? normalizeFrs(rowFrs, gridRows.length) : null),
+    [rowFrs, gridRows.length],
+  )
+
+  const containerStyle = useMemo<ViewStyle>(
+    () => ({
+      backgroundColor: tokens.backgroundColor,
+      ...resolvedPadding,
+      width: '100%',
+    }),
+    [tokens.backgroundColor, resolvedPadding],
+  )
+
+  const rowsContainerStyle = useMemo<ViewStyle>(
+    () => ({
+      gap: resolvedRowGap,
+      width: '100%',
+    }),
+    [resolvedRowGap],
+  )
+
+  const rowStyle = useMemo<ViewStyle>(
+    () => ({
+      flexDirection: 'row',
+      columnGap: resolvedColumnGap,
+      justifyContent: resolveRowJustifyContent(justifyContent),
+      alignItems: alignItems === 'stretch' ? 'stretch' : alignItems === 'center' ? 'center' : 'flex-start',
+      width: '100%',
+    }),
+    [resolvedColumnGap, justifyContent, alignItems],
+  )
+
+  const defaultAccessibilityLabel =
+    accessibilityLabel ??
+    `Grid, ${safeColumns} column${safeColumns === 1 ? '' : 's'}, ${gridRows.length} row${
+      gridRows.length === 1 ? '' : 's'
+    }`
+
+  return (
+    <View
+      style={[containerStyle, style]}
+      accessibilityRole="none"
+      accessibilityLabel={defaultAccessibilityLabel}
+      testID={testID}
+    >
+      <View style={[rowsContainerStyle, contentStyle]}>
+        {gridRows.map((row, rowIndex) => {
+          const rowFr = normalizedRowFrs?.[rowIndex]
+          const spacersNeeded =
+            justifyContent === 'space-between' && row.length < safeColumns
+              ? safeColumns - row.length
+              : 0
+
+          return (
+            <View
+              key={`grid-row-${rowIndex}`}
+              style={rowFr != null ? [rowStyle, { flexGrow: rowFr }] : rowStyle}
+            >
+              {row.map((cell, columnIndex) => {
+                const absoluteIndex = rowIndex * safeColumns + columnIndex
+                const cellFlexStyle = buildCellStyle(
+                  normalizedColumnFrs[columnIndex] ?? 1,
+                  justifyContent,
+                  alignItems,
+                )
+
+                return (
+                  <View
+                    key={`grid-cell-${absoluteIndex}`}
+                    style={[cellFlexStyle, cellStyle]}
+                  >
+                    {cell}
+                  </View>
+                )
+              })}
+              {spacersNeeded > 0 &&
+                Array.from({ length: spacersNeeded }, (_, spacerIndex) => (
+                  <View
+                    key={`grid-spacer-${rowIndex}-${spacerIndex}`}
+                    style={buildCellStyle(
+                      normalizedColumnFrs[row.length + spacerIndex] ?? 1,
+                      justifyContent,
+                      alignItems,
+                    )}
+                  />
+                ))}
+            </View>
+          )
+        })}
+      </View>
+    </View>
+  )
+}
+
+export default React.memo(Grid)

package/src/components/ListItem/ListItem.tsx

@@ -322,9 +322,16 @@ function ListItemImpl({
   const renderSupportContent = () => {
     if (processedSupportSlot) return processedSupportSlot
 
-    // Default support text:
-    //  - vertical layout: main text (line-broken on spaces)
-    //  - horizontal layout: secondary line (clamped to 2 lines)
+    // Default support text — ONE `<Text>` hard-clamped to 2 lines via
+    // `numberOfLines={2}`, the only mechanism React Native actually enforces
+    // on iOS/Android (native has no `white-space: nowrap` equivalent, so any
+    // style-based trick cannot stop a too-wide word from wrapping).
+    //
+    //  - vertical layout: line-broken on spaces so each word gets its own line
+    //    ("Split Payments" → "Split" / "Payments"). If a word is still wider
+    //    than the cell (or there are 3+ words), RN cuts it off at line 2 with
+    //    a trailing ellipsis instead of ever spilling onto a third line.
+    //  - horizontal layout: natural wrapping, same 2-line clamp.
     const displayText = layout === 'Vertical'
       ? supportText.replace(/ /g, '\n')
       : supportText
@@ -336,7 +343,7 @@ function ListItemImpl({
             ? [tokens.supportTextStyle, verticalSupportTextOverride]
             : tokens.supportTextStyle
         }
-        {...resolveTruncation(disableTruncation, layout === 'Horizontal' ? 2 : undefined)}
+        {...resolveTruncation(disableTruncation, 2, 'tail')}
       >
         {displayText}
       </Text>