jfs-components 0.1.25 → 0.1.28

package/src/components/FormUpload/Additem.tsx

@@ -0,0 +1,262 @@
+import React, { useMemo } from 'react'
+import { Pressable, View, type StyleProp, type ViewStyle, type ImageSourcePropType } 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 Image from '../Image/Image'
+import IconCapsule from '../IconCapsule/IconCapsule'
+import type { Modes } from '../../design-tokens'
+
+export type PickedAsset = {
+  /** URI to the selected file (image, video, or document). */
+  uri: string
+  /** Original file name, when available. */
+  name?: string
+  /** MIME type, when available. */
+  type?: string
+  /** File size in bytes, when available. */
+  size?: number
+  /** Image/video width in pixels, when available. */
+  width?: number
+  /** Image/video height in pixels, when available. */
+  height?: number
+}
+
+export type AdditemPickerResult = {
+  /** `true` when the user cancelled the picker. */
+  didCancel?: boolean
+  /** Selected assets. Empty when cancelled. */
+  assets: PickedAsset[]
+  /** Native error message, when something went wrong. */
+  error?: string
+}
+
+/**
+ * Callback that opens a platform picker and resolves with the selected assets.
+ * This is the integration point for libraries like `react-native-image-picker`,
+ * `expo-image-picker`, or `react-native-document-picker`.
+ */
+export type AdditemPicker = () => Promise<AdditemPickerResult>
+
+export type AdditemState = 'empty' | 'preview'
+
+export type AdditemProps = {
+  /**
+   * Visual state of the item.
+   * - `'empty'` — shows the add/upload icon (default).
+   * - `'preview'` — shows `imageSource` and a remove icon overlay.
+   */
+  state?: AdditemState
+  /**
+   * Image to preview when `state` is `'preview'`. Accepts the same shapes as
+   * the library's `Image` component (remote URI string, `{ uri }`, or `require()`).
+   */
+  imageSource?: ImageSourcePropType | string | undefined
+  /**
+   * Called when the cell is pressed. In `'empty'` mode this is typically where
+   * the picker is launched; in `'preview'` mode it can open a preview/lightbox.
+   */
+  onPress?: () => void
+  /**
+   * Called when the remove icon overlay is pressed in `'preview'` mode.
+   * Receives the press event so the parent can stop propagation if needed.
+   */
+  onRemove?: () => void
+  /**
+   * Optional picker to invoke when the empty cell is pressed. When provided,
+   * `onPress` is ignored for the empty state and the cell becomes a real
+   * upload trigger that resolves with picked assets via `onAssetsPicked`.
+   */
+  picker?: AdditemPicker
+  /**
+   * Called after a successful picker invocation with the selected assets.
+   */
+  onAssetsPicked?: (assets: PickedAsset[]) => void
+  /**
+   * Modes for design-token resolution. Defaults to Neutral / Low / Icon Capsule
+   * Size S for the inner `IconCapsule` icons; any key supplied here overrides
+   * those defaults.
+   */
+  modes?: Modes
+  /**
+   * Accessibility label. Defaults to a descriptive label based on state.
+   */
+  accessibilityLabel?: string
+  /**
+   * Disables press interaction. Also dims the cell.
+   */
+  isDisabled?: boolean
+  /** Test identifier. */
+  testID?: string
+}
+
+interface AdditemTokens {
+  backgroundColor: string
+  borderRadius: number
+  paddingHorizontal: number
+  paddingVertical: number
+  size: number
+}
+
+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 resolveAdditemTokens(modes: Modes): AdditemTokens {
+  const backgroundColor = getVariableByName('compareCardItem/background', modes) as string
+  const borderRadius = toNumber(getVariableByName('compareCardItem/radius', modes), 8)
+  const paddingHorizontal = toNumber(getVariableByName('compareCardItem/padding/horizontal', modes), 6)
+  const paddingVertical = toNumber(getVariableByName('compareCardItem/padding/vertical', modes), 8)
+  // The Figma design uses a fixed 44 × 44 dp cell. There is no
+  // `compareCardItem/size` token in the variables JSON, so we keep the size
+  // constant to match the design exactly.
+  const size = 44
+
+  return {
+    backgroundColor,
+    borderRadius,
+    paddingHorizontal,
+    paddingVertical,
+    size,
+  }
+}
+
+/** Figma defaults for the inner `IconCapsule` icons. Overridable via `modes`. */
+const ADDITEM_DEFAULT_MODES: Readonly<Record<string, string>> = Object.freeze({
+  AppearanceBrand: 'Neutral',
+  Emphasis: 'Low',
+  'Icon Capsule Size': 'S',
+})
+
+/**
+ * `Additem` — a small, reusable upload/preview cell used inside form uploaders.
+ *
+ * In its default `'empty'` state it shows a centered add/upload icon. In
+ * `'preview'` state it renders a thumbnail with a removable overlay. The
+ * component is intentionally unopinionated about *how* files are picked: pass a
+ * `picker` callback that wraps `react-native-image-picker`,
+ * `expo-image-picker`, `react-native-document-picker`, or any custom selector,
+ * and the cell will invoke it, surface the result via `onAssetsPicked`, and
+ * handle cancellation/errors gracefully.
+ */
+function Additem({
+  state = 'empty',
+  imageSource,
+  onPress,
+  onRemove,
+  picker,
+  onAssetsPicked,
+  modes: propModes = EMPTY_MODES,
+  accessibilityLabel,
+  isDisabled = false,
+  testID,
+}: AdditemProps) {
+  const { modes: globalModes } = useTokens()
+
+  const modes = useMemo(
+    () =>
+      globalModes === EMPTY_MODES && propModes === EMPTY_MODES
+        ? ADDITEM_DEFAULT_MODES
+        : { ...ADDITEM_DEFAULT_MODES, ...globalModes, ...propModes },
+    [globalModes, propModes],
+  )
+
+  const tokens = useMemo(() => resolveAdditemTokens(modes), [modes])
+
+  const handlePress = React.useCallback(async () => {
+    if (isDisabled) return
+
+    if (state === 'empty' && picker) {
+      try {
+        const result = await picker()
+        if (result.didCancel) return
+        if (result.error) {
+          if (__DEV__) {
+            console.warn('[Additem] picker error:', result.error)
+          }
+          return
+        }
+        if (result.assets.length > 0) {
+          onAssetsPicked?.(result.assets)
+        }
+      } catch (err) {
+        if (__DEV__) {
+          console.warn('[Additem] unexpected picker error:', err)
+        }
+      }
+      return
+    }
+
+    onPress?.()
+  }, [isDisabled, onPress, onAssetsPicked, picker, state])
+
+  const handleRemove = React.useCallback(() => {
+    if (!isDisabled) {
+      onRemove?.()
+    }
+  }, [isDisabled, onRemove])
+
+  const resolvedAccessibilityLabel = accessibilityLabel ?? (state === 'empty' ? 'Add attachment' : 'Attachment preview')
+
+  const containerStyle: StyleProp<ViewStyle> = useMemo(
+    () => ({
+      width: tokens.size,
+      height: tokens.size,
+      borderRadius: tokens.borderRadius,
+      backgroundColor: tokens.backgroundColor,
+      paddingHorizontal: tokens.paddingHorizontal,
+      paddingVertical: tokens.paddingVertical,
+      alignItems: 'center',
+      justifyContent: 'center',
+      overflow: 'hidden',
+      opacity: isDisabled ? 0.5 : 1,
+    }),
+    [tokens, isDisabled],
+  )
+
+  const isPreview = state === 'preview'
+
+  return (
+    <Pressable
+      onPress={handlePress}
+      disabled={isDisabled}
+      accessibilityRole="button"
+      accessibilityLabel={resolvedAccessibilityLabel}
+      accessibilityState={{ disabled: isDisabled }}
+      testID={testID}
+      style={containerStyle}
+    >
+      {isPreview ? (
+        <>
+          <Image
+            imageSource={imageSource}
+            width="100%"
+            height={tokens.size - tokens.paddingVertical * 2}
+            resizeMode="cover"
+            borderRadius={tokens.borderRadius - 2}
+          />
+          {onRemove != null && (
+            <View style={{ position: 'absolute', top: 2, right: 2 }}>
+              <IconCapsule
+                iconName="ic_close"
+                modes={modes}
+                onTouchEnd={handleRemove}
+                accessibilityRole="button"
+                accessibilityLabel="Remove attachment"
+              />
+            </View>
+          )}
+        </>
+      ) : (
+        <IconCapsule iconName="ic_add" modes={modes} />
+      )}
+    </Pressable>
+  )
+}
+
+export default React.memo(Additem)

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)