jfs-components 0.1.2 → 0.1.8

package/src/components/ComparisonBar/ComparisonBar.tsx

@@ -0,0 +1,356 @@
+import React, { useMemo } from 'react'
+import {
+  Pressable,
+  View,
+  type ImageSourcePropType,
+  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 { usePressableWebSupport } from '../../utils/web-platform-utils'
+import Button from '../Button/Button'
+import Image from '../Image/Image'
+import IconCapsule from '../IconCapsule/IconCapsule'
+import type { Modes } from '../../design-tokens'
+
+/**
+ * A single slot in the {@link ComparisonBar}. Each item is either empty (the
+ * "Add" state — a tappable `+` capsule) or filled with an image (the
+ * "Image Added" state — the image plus a dismiss capsule in the corner).
+ *
+ * The presence of {@link ComparisonBarItem.imageSource} is what toggles the
+ * state: provide a source to show the image, leave it `undefined`/`null` to
+ * show the empty add slot. This keeps the component fully controlled — the
+ * `ComparisonBar` never owns the image state itself, so the consumer decides
+ * (e.g. after opening a file/asset picker) when and how an item flips between
+ * the two states.
+ */
+export type ComparisonBarItem = {
+  /**
+   * Stable identifier for this slot. Returned to callbacks so the consumer
+   * can target the exact item that was interacted with. Falls back to the
+   * array index when omitted.
+   */
+  id?: string | number
+  /**
+   * Image to render in the slot. When provided the slot renders in the
+   * "Image Added" state; when omitted/`null` it renders the empty "Add" state.
+   * Accepts the same shapes as the library `Image` component (remote URL
+   * string, `{ uri }`, or a `require()`d asset).
+   */
+  imageSource?: ImageSourcePropType | string | null
+  /** Accessibility label for the slot. Defaults to a generic add/remove label. */
+  accessibilityLabel?: string
+}
+
+export type ComparisonBarProps = {
+  /**
+   * The slots rendered before the Compare button. Each entry controls its own
+   * add/image state via {@link ComparisonBarItem.imageSource}.
+   */
+  items: ComparisonBarItem[]
+  /**
+   * Fired when an empty (Add) slot is tapped. The consumer is expected to react
+   * by opening whatever picker is appropriate and then updating that item's
+   * `imageSource` to flip it into the "Image Added" state — the component does
+   * not know how images are sourced. Receives the item's `id` (or index when no
+   * id was supplied) and the slot index.
+   */
+  onItemPress?: (id: ComparisonBarItem['id'], index: number) => void
+  /**
+   * Fired when a filled slot is tapped. For better mobile ergonomics the
+   * *entire* filled slot is the remove target (the dismiss capsule is just a
+   * visual affordance), so a fingertip anywhere on the item triggers this. The
+   * consumer is expected to clear that item's `imageSource` to return it to the
+   * "Add" state. Receives the item's `id` (or index) and the slot index.
+   */
+  onItemRemove?: (id: ComparisonBarItem['id'], index: number) => void
+  /** Fired when the Compare button is pressed. */
+  onCompare?: () => void
+  /** Label for the trailing action button. Defaults to `"Compare"`. */
+  compareLabel?: string
+  /**
+   * Explicitly controls the Compare button's *functional* disabled state — a
+   * truly disabled button is non-interactive (its `onPress` never fires), not
+   * just dimmed. Note that `modes` only affects appearance, so dimming the
+   * button via tokens does NOT stop taps; that is what this prop is for.
+   *
+   * When provided (a boolean), it always wins over
+   * {@link ComparisonBarProps.disableCompareWhenEmpty}. Leave it `undefined`
+   * to fall back to the auto behavior.
+   */
+  compareDisabled?: boolean
+  /**
+   * When `true` (default) the Compare button is automatically (and truly)
+   * disabled while no slot has an image — there is nothing to compare yet. Set
+   * to `false` to keep it tappable even when empty. Ignored when
+   * {@link ComparisonBarProps.compareDisabled} is set explicitly.
+   */
+  disableCompareWhenEmpty?: boolean
+  /** Mode configuration passed to the token resolver. */
+  modes?: Modes
+  /** Style overrides for the outer floating card. */
+  style?: StyleProp<ViewStyle>
+}
+
+const ITEM_WIDTH = 45
+const ITEM_HEIGHT = 44
+
+interface ComparisonBarTokens {
+  card: ViewStyle
+  item: ViewStyle
+  itemImageState: ViewStyle
+  imageRadius: number
+}
+
+function resolveTokens(modes: Modes): ComparisonBarTokens {
+  const cardGap = (getVariableByName('compareFloatCard/gap', modes) ?? 12) as number
+  const cardPadH = (getVariableByName('compareFloatCard/padding/horizontal', modes) ?? 12) as number
+  const cardPadV = (getVariableByName('compareFloatCard/padding/vertical', modes) ?? 10) as number
+  const cardRadius = (getVariableByName('compareFloatCard/radius', modes) ?? 12) as number
+  const cardBackground = (getVariableByName('compareFloatCard/background', modes) ?? '#ffffff') as string
+  const cardBorderColor = (getVariableByName('compareFloatCard/border/color', modes) ?? '#f5f5f5') as string
+
+  const itemPadH = (getVariableByName('compareCardItem/padding/horizontal', modes) ?? 6) as number
+  const itemPadV = (getVariableByName('compareCardItem/padding/vertical', modes) ?? 8) as number
+  const itemRadius = (getVariableByName('compareCardItem/radius', modes) ?? 8) as number
+  const itemBackground = (getVariableByName('compareCardItem/background', modes) ?? '#ebebed') as string
+
+  const imageRadius = (getVariableByName('image/radius', modes) ?? 8) as number
+
+  return {
+    card: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: cardGap,
+      paddingHorizontal: cardPadH,
+      paddingVertical: cardPadV,
+      borderRadius: cardRadius,
+      borderWidth: 1,
+      borderColor: cardBorderColor,
+      backgroundColor: cardBackground,
+      alignSelf: 'flex-start',
+    },
+    item: {
+      width: ITEM_WIDTH,
+      height: ITEM_HEIGHT,
+      borderRadius: itemRadius,
+      backgroundColor: itemBackground,
+      paddingHorizontal: itemPadH,
+      paddingVertical: itemPadV,
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
+    itemImageState: {
+      paddingHorizontal: itemPadH,
+      paddingVertical: itemPadV,
+    },
+    imageRadius,
+  }
+}
+
+type AdditemProps = {
+  item: ComparisonBarItem
+  index: number
+  tokens: ComparisonBarTokens
+  addCapsuleModes: Modes
+  closeCapsuleModes: Modes
+  onPress?: ComparisonBarProps['onItemPress']
+  onRemove?: ComparisonBarProps['onItemRemove']
+}
+
+/**
+ * Internal slot renderer for {@link ComparisonBar}. Intentionally NOT exported
+ * — it is meaningless outside of a `ComparisonBar` (its layout, sizing and
+ * remove affordance all assume the surrounding card) and is kept private so
+ * the public surface stays a single, cohesive component.
+ */
+function Additem({ item, index, tokens, addCapsuleModes, closeCapsuleModes, onPress, onRemove }: AdditemProps) {
+  const hasImage = item.imageSource != null && item.imageSource !== ''
+  const id = item.id ?? index
+
+  const addWebProps = usePressableWebSupport({
+    restProps: {},
+    onPress: () => onPress?.(id, index),
+    disabled: false,
+    accessibilityLabel: item.accessibilityLabel ?? 'Add item to comparison',
+  })
+
+  const removeWebProps = usePressableWebSupport({
+    restProps: {},
+    onPress: () => onRemove?.(id, index),
+    disabled: false,
+    accessibilityLabel: item.accessibilityLabel ?? 'Remove item from comparison',
+  })
+
+  if (!hasImage) {
+    return (
+      <Pressable
+        style={tokens.item}
+        accessibilityRole="button"
+        accessibilityLabel={item.accessibilityLabel ?? 'Add item to comparison'}
+        onPress={() => onPress?.(id, index)}
+        {...addWebProps}
+      >
+        <IconCapsule iconName="ic_add" modes={addCapsuleModes} style={ADD_CAPSULE_STYLE} />
+      </Pressable>
+    )
+  }
+
+  // Mobile-first: the entire filled slot is the remove target, not just the
+  // tiny close capsule (which a fingertip struggles to hit). The capsule stays
+  // purely as a visual affordance and is marked non-interactive so it never
+  // intercepts the press from the surrounding Pressable.
+  return (
+    <Pressable
+      style={[tokens.item, tokens.itemImageState]}
+      accessibilityRole="button"
+      accessibilityLabel={item.accessibilityLabel ?? 'Remove item from comparison'}
+      onPress={() => onRemove?.(id, index)}
+      {...removeWebProps}
+    >
+      <Image
+        imageSource={item.imageSource as any}
+        width="100%"
+        height="100%"
+        borderRadius={tokens.imageRadius}
+        resizeMode="cover"
+        accessibilityLabel={item.accessibilityLabel ?? 'Comparison item image'}
+      />
+      <View style={CLOSE_CAPSULE_WRAPPER_STYLE} pointerEvents="none">
+        <IconCapsule iconName="ic_close" modes={closeCapsuleModes} />
+      </View>
+    </Pressable>
+  )
+}
+
+// The Add capsule is the transparent IconCapsule variant from Figma (the gray
+// item box is the visible surface); its size/icon come from the resolved
+// `Icon Capsule Size: S` tokens, we only flatten the background/border here.
+const ADD_CAPSULE_STYLE: ViewStyle = {
+  backgroundColor: 'transparent',
+  borderColor: 'transparent',
+}
+
+// Positions the dismiss IconCapsule in the slot's top-right corner. The capsule
+// itself (size/background/icon) is fully token-driven via `closeCapsuleModes`.
+const CLOSE_CAPSULE_WRAPPER_STYLE: ViewStyle = {
+  position: 'absolute',
+  top: 1,
+  right: 1,
+}
+
+// Mode overrides applied on top of the consumer's `modes` for each capsule.
+// These mirror the Figma component's IconCapsule variant selections so the
+// sizing and colours come from design tokens instead of magic numbers.
+const ADD_CAPSULE_MODE_OVERRIDES: Modes = { 'Icon Capsule Size': 'XS' }
+const CLOSE_CAPSULE_MODE_OVERRIDES: Modes = {
+  AppearanceBrand: 'Neutral',
+  Emphasis: 'Medium',
+  'Icon Capsule Size': 'XS',
+}
+
+/**
+ * ComparisonBar — a floating card that lets a user assemble a set of items to
+ * compare, then trigger the comparison.
+ *
+ * Each slot is fully controlled via its `imageSource`: an empty slot shows a
+ * tappable `+` (the "Add" state) and a filled slot shows the image with a
+ * dismiss capsule (the "Image Added" state). The component never sources or
+ * stores images itself — when an empty slot is pressed it fires `onItemPress`
+ * with the item's id/index so the consumer can open whatever picker is
+ * appropriate and then update that item's `imageSource` to flip its state.
+ * Tapping a filled slot (anywhere on it — a mobile-friendly hit target, with
+ * the dismiss capsule as a visual affordance) fires `onItemRemove` so the
+ * consumer can clear the source again.
+ *
+ * @example
+ * ```tsx
+ * const [items, setItems] = useState<ComparisonBarItem[]>([
+ *   { id: 'a' }, { id: 'b' }, { id: 'c' }, { id: 'd' },
+ * ])
+ *
+ * <ComparisonBar
+ *   items={items}
+ *   onItemPress={async (id) => {
+ *     const uri = await openImagePicker()
+ *     setItems(prev => prev.map(it => it.id === id ? { ...it, imageSource: uri } : it))
+ *   }}
+ *   onItemRemove={(id) =>
+ *     setItems(prev => prev.map(it => it.id === id ? { ...it, imageSource: null } : it))
+ *   }
+ *   onCompare={runComparison}
+ * />
+ * ```
+ */
+function ComparisonBar({
+  items,
+  onItemPress,
+  onItemRemove,
+  onCompare,
+  compareLabel = 'Compare',
+  compareDisabled,
+  disableCompareWhenEmpty = true,
+  modes: propModes = EMPTY_MODES,
+  style,
+}: ComparisonBarProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = useMemo(
+    () =>
+      globalModes === EMPTY_MODES && propModes === EMPTY_MODES
+        ? EMPTY_MODES
+        : { ...globalModes, ...propModes },
+    [globalModes, propModes]
+  )
+
+  const tokens = useMemo(() => resolveTokens(modes), [modes])
+
+  // Capsule modes = consumer modes + this component's fixed IconCapsule variant
+  // selections. Memoized so each `Additem`'s `IconCapsule` keeps a stable
+  // `modes` identity and hits the resolver cache.
+  const addCapsuleModes = useMemo(
+    () => ({ ...modes, ...ADD_CAPSULE_MODE_OVERRIDES }),
+    [modes]
+  )
+  const closeCapsuleModes = useMemo(
+    () => ({ ...modes, ...CLOSE_CAPSULE_MODE_OVERRIDES }),
+    [modes]
+  )
+
+  // An explicit `compareDisabled` always wins (functional disable — the tap is
+  // truly blocked, not merely dimmed). Otherwise auto-disable while no slot has
+  // an image, since there is nothing to compare yet.
+  const hasAnyImage = useMemo(
+    () => items.some((it) => it.imageSource != null && it.imageSource !== ''),
+    [items]
+  )
+  const isCompareDisabled =
+    compareDisabled ?? (disableCompareWhenEmpty && !hasAnyImage)
+
+  return (
+    <View style={[tokens.card, style]}>
+      {items.map((item, index) => (
+        <Additem
+          key={item.id ?? index}
+          item={item}
+          index={index}
+          tokens={tokens}
+          addCapsuleModes={addCapsuleModes}
+          closeCapsuleModes={closeCapsuleModes}
+          onPress={onItemPress}
+          onRemove={onItemRemove}
+        />
+      ))}
+      <Button
+        label={compareLabel}
+        modes={modes}
+        disabled={isCompareDisabled}
+        {...(onCompare !== undefined ? { onPress: onCompare } : {})}
+      />
+    </View>
+  )
+}
+
+export default React.memo(ComparisonBar)

package/src/components/DropdownInput/DropdownInput.tsx

@@ -1,6 +1,8 @@
 import React, {
+    forwardRef,
     useCallback,
     useEffect,
+    useImperativeHandle,
     useMemo,
     useRef,
     useState,
@@ -52,6 +54,28 @@ export type DropdownInputOption = {
 
 type Rect = { x: number; y: number; width: number; height: number }
 
+/**
+ * Imperative handle exposed via `ref`. Lets the consumer drive the dropdown
+ * from outside — e.g. close it when an Android hardware/system button is
+ * pressed, or open it programmatically from a sibling control.
+ */
+export type DropdownInputHandle = {
+    /** Opens the options menu (no-op when disabled / read-only). */
+    open: () => void
+    /** Closes the options menu. */
+    close: () => void
+    /** Toggles the options menu open/closed. */
+    toggle: () => void
+    /** Moves focus to the trigger (web). */
+    focus: () => void
+    /** Removes focus from the trigger (web). */
+    blur: () => void
+    /** Measures the trigger in window coordinates. */
+    measureInWindow: (
+        callback: (x: number, y: number, width: number, height: number) => void
+    ) => void
+}
+
 export type DropdownInputProps = {
     /** Label rendered above the input. */
     label?: string
@@ -307,7 +331,7 @@ function collectOptionsFromChildren(
 // Component
 // ---------------------------------------------------------------------------
 
-function DropdownInput({
+const DropdownInput = forwardRef<DropdownInputHandle, DropdownInputProps>(function DropdownInput({
     label,
     placeholder = 'Select an option',
     items,
@@ -338,7 +362,7 @@ function DropdownInput({
     accessibilityHint,
     onFocus,
     onBlur,
-}: DropdownInputProps) {
+}: DropdownInputProps, ref: React.Ref<DropdownInputHandle>) {
     // ---------------- Modes ----------------
     const { modes: globalModes } = useTokens()
     const baseModes = useMemo(
@@ -497,6 +521,34 @@ function DropdownInput({
         [measure]
     )
 
+    // ---------------- Imperative handle ----------------
+    useImperativeHandle(
+        ref,
+        () => ({
+            open: () => {
+                if (isDisabled || isReadOnly) return
+                measure()
+                setOpenState(true)
+            },
+            close: closeMenu,
+            toggle: () => {
+                if (isDisabled || isReadOnly) return
+                measure()
+                toggleMenu()
+            },
+            focus: () => {
+                ;(triggerRef.current as unknown as { focus?: () => void })?.focus?.()
+            },
+            blur: () => {
+                ;(triggerRef.current as unknown as { blur?: () => void })?.blur?.()
+            },
+            measureInWindow: (callback) => {
+                triggerRef.current?.measureInWindow(callback)
+            },
+        }),
+        [isDisabled, isReadOnly, measure, setOpenState, closeMenu, toggleMenu]
+    )
+
     // ---------------- Popup positioning ----------------
     const [menuSize, setMenuSize] = useState<{
         width: number
@@ -863,7 +915,7 @@ function DropdownInput({
             </Modal>
         </View>
     )
-}
+})
 
 const webNoOutline: any = {
     outlineStyle: 'none',

package/src/components/FormField/FormField.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useMemo, useState } from 'react'
+import React, { forwardRef, useCallback, useMemo, useState } from 'react'
 import {
   View,
   Text,
@@ -301,7 +301,7 @@ function firstError(error: string | string[] | undefined): string | undefined {
 // Component
 // ---------------------------------------------------------------------------
 
-function FormField({
+const FormField = forwardRef<RNTextInput, FormFieldProps>(function FormField({
   label,
   placeholder,
   value,
@@ -329,7 +329,7 @@ function FormField({
   accessibilityLabel,
   accessibilityHint,
   testID,
-}: FormFieldProps) {
+}: FormFieldProps, ref: React.Ref<RNTextInput>) {
   // -- Form context integration -------------------------------------------
   const formCtx = useFormContext()
   const formError =
@@ -552,6 +552,7 @@ function FormField({
           </View>
         )}
         <RNTextInput
+          ref={ref}
           style={[inputTextStyles, inputTextStyle]}
           value={value ?? ''}
           onChangeText={handleChangeText}
@@ -590,6 +591,6 @@ function FormField({
       )}
     </View>
   )
-}
+})
 
 export default FormField

package/src/components/InputSearch/InputSearch.tsx

@@ -1,5 +1,5 @@
-import React, { useState } from 'react'
-import { View, Text, Pressable, type StyleProp, type ViewStyle, type TextStyle, type TextInputProps as RNTextInputProps } from 'react-native'
+import React, { forwardRef, useState } from 'react'
+import { View, Text, Pressable, TextInput as RNTextInput, type StyleProp, type ViewStyle, type TextStyle, type TextInputProps as RNTextInputProps } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES } from '../../utils/react-utils'
 import Icon from '../../icons/Icon'
@@ -81,7 +81,7 @@ export type InputSearchProps = {
     accessibilityHint?: string;
 } & Omit<RNTextInputProps, 'style' | 'onChangeText' | 'onFocus' | 'onBlur' | 'placeholder' | 'value'>;
 
-export default function InputSearch({
+const InputSearch = forwardRef<RNTextInput, InputSearchProps>(function InputSearch({
     supportText = true,
     supportTextLabel = "Support Text",
     supportTextIcon = "ic_info",
@@ -96,7 +96,7 @@ export default function InputSearch({
     trailing,
     inputStyle,
     ...rest
-}: InputSearchProps) {
+}: InputSearchProps, ref: React.Ref<RNTextInput>) {
     const [isFocused, setIsFocused] = useState(false)
 
     // Hardcode InputState based on the state prop, ignoring any external InputState passed in modes
@@ -156,6 +156,7 @@ export default function InputSearch({
             gap: formFieldGap,
         }, containerStyle]}>
             <TextInput
+                ref={ref}
                 placeholder={placeholder}
                 value={value || ''}
                 onChangeText={onChangeText || (() => { })}
@@ -178,4 +179,6 @@ export default function InputSearch({
             )}
         </View>
     )
-}
+})
+
+export default InputSearch

package/src/components/NoteInput/NoteInput.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useRef, useEffect } from 'react'
+import React, { forwardRef, useState, useRef } from 'react'
 import {
     View,
     TextInput as RNTextInput,
@@ -11,7 +11,7 @@ import {
     type TextInputProps,
 } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
-import { EMPTY_MODES } from '../../utils/react-utils'
+import { EMPTY_MODES, mergeRefs } from '../../utils/react-utils'
 import type { Modes } from '../../design-tokens'
 
 export type NoteInputProps = {
@@ -35,7 +35,7 @@ export type NoteInputProps = {
  * NoteInput component representing an interactive "Add note" badge style field.
  * Allows the user to click, clears the placeholder text, and shows a blinking cursor when focused.
  */
-export default function NoteInput({
+const NoteInput = forwardRef<RNTextInput, NoteInputProps>(function NoteInput({
     value = '',
     placeholder = 'Add note',
     onChangeText,
@@ -46,7 +46,7 @@ export default function NoteInput({
     onFocus,
     onBlur,
     ...rest
-}: NoteInputProps) {
+}: NoteInputProps, ref: React.Ref<RNTextInput>) {
     const [internalFocused, setInternalFocused] = useState(false)
     const inputRef = useRef<RNTextInput>(null)
 
@@ -120,7 +120,7 @@ export default function NoteInput({
                     {internalFocused ? (value || ' ') : (value || placeholder)}
                 </Text>
                 <RNTextInput
-                    ref={inputRef}
+                    ref={mergeRefs(inputRef, ref)}
                     value={value}
                     onChangeText={onChangeText}
                     placeholder={internalFocused ? '' : placeholder}
@@ -145,4 +145,6 @@ export default function NoteInput({
             </View>
         </Pressable>
     )
-}
+})
+
+export default NoteInput