rn-inputforge 0.3.1 → 0.5.0

package/src/components/FieldFlowUpload/FieldFlowUpload.tsx

@@ -0,0 +1,226 @@
+import React, { useMemo } from 'react';
+import {
+  Image,
+  Pressable,
+  StyleSheet,
+  Text,
+  View,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+import { useFieldFlowTheme, mergeDeep } from '../../theme/ThemeProvider';
+import { defaultTheme } from '../../theme/defaultTheme';
+import { renderFieldFlowIcon } from '../../icons/renderIcon';
+import type { DeepPartial, FieldFlowTheme } from '../../types';
+
+export interface FieldFlowUploadFile {
+  uri: string;
+  name?: string;
+  mimeType?: string;
+  size?: number;
+  /** Optional local preview (same as uri for images). */
+  previewUri?: string;
+}
+
+export type FieldFlowUploadPicker = () => Promise<FieldFlowUploadFile | FieldFlowUploadFile[] | null>;
+
+export interface FieldFlowUploadProps {
+  value?: FieldFlowUploadFile[];
+  onChange: (files: FieldFlowUploadFile[]) => void;
+  /**
+   * Injected picker — keep the library free of native upload deps.
+   * Example: wrap `expo-image-picker` / `expo-document-picker` / `launchImageLibrary`.
+   */
+  pick: FieldFlowUploadPicker;
+  label?: string;
+  helperText?: string;
+  errorText?: string;
+  disabled?: boolean;
+  required?: boolean;
+  /** Max files. Default: 1. */
+  maxFiles?: number;
+  /** Accept hint shown in UI. */
+  acceptHint?: string;
+  /** Show image thumbnails when mime looks like image. Default: true. */
+  showPreviews?: boolean;
+  /** Replace the dashed dropzone chrome. */
+  renderDropzone?: (ctx: {
+    atMax: boolean;
+    fileCount: number;
+    maxFiles: number;
+    disabled: boolean;
+    openPicker: () => void;
+  }) => React.ReactNode;
+  /** Replace each file row. Call `remove` to delete. */
+  renderFile?: (ctx: {
+    file: FieldFlowUploadFile;
+    index: number;
+    remove: () => void;
+  }) => React.ReactNode;
+  containerStyle?: ViewStyle;
+  labelStyle?: TextStyle;
+  theme?: DeepPartial<FieldFlowTheme>;
+  testID?: string;
+}
+
+export function FieldFlowUpload({
+  value = [],
+  onChange,
+  pick,
+  label,
+  helperText,
+  errorText,
+  disabled,
+  required,
+  maxFiles = 1,
+  acceptHint = 'Tap to upload',
+  showPreviews = true,
+  renderDropzone,
+  renderFile,
+  containerStyle,
+  labelStyle,
+  theme: themeOverride,
+  testID,
+}: FieldFlowUploadProps) {
+  const contextTheme = useFieldFlowTheme();
+  const theme = useMemo(
+    () => (themeOverride ? mergeDeep(contextTheme ?? defaultTheme, themeOverride) : contextTheme ?? defaultTheme),
+    [contextTheme, themeOverride],
+  );
+  const styles = useMemo(() => createStyles(theme, Boolean(errorText), Boolean(disabled)), [theme, errorText, disabled]);
+  const atMax = value.length >= maxFiles;
+
+  const handlePick = async () => {
+    if (disabled || atMax) return;
+    const result = await pick();
+    if (!result) return;
+    const incoming = Array.isArray(result) ? result : [result];
+    const room = maxFiles - value.length;
+    onChange([...value, ...incoming.slice(0, room)]);
+  };
+
+  const removeAt = (index: number) => {
+    onChange(value.filter((_, i) => i !== index));
+  };
+
+  return (
+    <View style={[styles.wrap, containerStyle]} testID={testID}>
+      {label ? (
+        <Text style={[styles.label, labelStyle]}>
+          {label}
+          {required ? ' *' : ''}
+        </Text>
+      ) : null}
+
+      {renderDropzone ? (
+        renderDropzone({
+          atMax,
+          fileCount: value.length,
+          maxFiles,
+          disabled: Boolean(disabled),
+          openPicker: () => {
+            void handlePick();
+          },
+        })
+      ) : (
+        <Pressable
+          style={styles.drop}
+          onPress={handlePick}
+          disabled={disabled || atMax}
+          accessibilityRole="button"
+          accessibilityLabel={label ?? 'Upload'}
+        >
+          {renderFieldFlowIcon('plus', theme.colors.borderFocused, 22)}
+          <Text style={styles.dropTitle}>{atMax ? 'Limit reached' : acceptHint}</Text>
+          <Text style={styles.dropMeta}>
+            {value.length}/{maxFiles} file{maxFiles === 1 ? '' : 's'}
+          </Text>
+        </Pressable>
+      )}
+
+      {value.length > 0 ? (
+        <View style={styles.list}>
+          {value.map((file, index) => {
+            if (renderFile) {
+              return (
+                <React.Fragment key={`${file.uri}-${index}`}>
+                  {renderFile({ file, index, remove: () => removeAt(index) })}
+                </React.Fragment>
+              );
+            }
+            const isImage =
+              showPreviews &&
+              (file.mimeType?.startsWith('image/') ||
+                /\.(png|jpe?g|gif|webp)$/i.test(file.name ?? file.uri));
+            return (
+              <View key={`${file.uri}-${index}`} style={styles.item}>
+                {isImage ? (
+                  <Image source={{ uri: file.previewUri ?? file.uri }} style={styles.thumb} />
+                ) : (
+                  <View style={styles.fileIcon}>{renderFieldFlowIcon('file', theme.colors.icon, 18)}</View>
+                )}
+                <Text style={styles.fileName} numberOfLines={1}>
+                  {file.name ?? file.uri.split('/').pop() ?? 'File'}
+                </Text>
+                <Pressable onPress={() => removeAt(index)} hitSlop={8} accessibilityLabel="Remove file">
+                  {renderFieldFlowIcon('trash', theme.colors.error, 16)}
+                </Pressable>
+              </View>
+            );
+          })}
+        </View>
+      ) : null}
+
+      {errorText ? (
+        <Text style={styles.error}>{errorText}</Text>
+      ) : helperText ? (
+        <Text style={styles.helper}>{helperText}</Text>
+      ) : null}
+    </View>
+  );
+}
+
+function createStyles(theme: FieldFlowTheme, hasError: boolean, disabled: boolean) {
+  return StyleSheet.create({
+    wrap: { marginBottom: theme.spacing.gap * 2, opacity: disabled ? 0.6 : 1 },
+    label: {
+      fontSize: theme.typography.labelFontSize,
+      marginBottom: theme.spacing.gap / 1.5,
+      color: hasError ? theme.colors.error : theme.colors.label,
+      fontWeight: '500',
+    },
+    drop: {
+      borderWidth: 1.5,
+      borderStyle: 'dashed',
+      borderColor: hasError ? theme.colors.borderError : theme.colors.border,
+      borderRadius: theme.spacing.borderRadius + 2,
+      paddingVertical: 22,
+      alignItems: 'center',
+      backgroundColor: theme.colors.backgroundDisabled,
+      gap: 6,
+    },
+    dropTitle: { fontSize: theme.typography.fontSize, color: theme.colors.text, fontWeight: '600' },
+    dropMeta: { fontSize: theme.typography.helperFontSize, color: theme.colors.label },
+    list: { marginTop: theme.spacing.gap },
+    item: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: 10,
+      paddingVertical: 8,
+      borderBottomWidth: StyleSheet.hairlineWidth,
+      borderBottomColor: theme.colors.border,
+    },
+    thumb: { width: 40, height: 40, borderRadius: 8 },
+    fileIcon: {
+      width: 40,
+      height: 40,
+      borderRadius: 8,
+      alignItems: 'center',
+      justifyContent: 'center',
+      backgroundColor: theme.colors.backgroundDisabled,
+    },
+    fileName: { flex: 1, color: theme.colors.text, fontSize: theme.typography.helperFontSize + 1 },
+    helper: { marginTop: 6, fontSize: theme.typography.helperFontSize, color: theme.colors.label },
+    error: { marginTop: 6, fontSize: theme.typography.helperFontSize, color: theme.colors.error },
+  });
+}

package/src/components/FieldFlowUpload/index.ts

@@ -0,0 +1,6 @@
+export { FieldFlowUpload } from './FieldFlowUpload';
+export type {
+  FieldFlowUploadProps,
+  FieldFlowUploadFile,
+  FieldFlowUploadPicker,
+} from './FieldFlowUpload';

package/src/hooks/index.ts

@@ -6,7 +6,41 @@ export type {
   UseFieldFlowFormOptions,
   UseFieldFlowFormResult,
   FieldFlowFormRules,
+  AsyncFieldValidator,
+  AsyncFieldValidators,
+  CrossFieldRule,
+  FieldConditionFn,
+  FieldConditionConfig,
+  FieldConditions,
+  FieldVisibilityState,
 } from './useFieldFlowForm';
 
 export { useFieldState } from './useFieldState';
 export type { UseFieldStateOptions } from './useFieldState';
+
+export { useFormIntelligence } from './useFormIntelligence';
+export type { UseFormIntelligenceResult } from './useFormIntelligence';
+
+export { useFieldFlowArray } from './useFieldFlowArray';
+export type { UseFieldFlowArrayOptions, UseFieldFlowArrayResult } from './useFieldFlowArray';
+
+export { useFieldFlowDraft } from './useFieldFlowDraft';
+export type {
+  FieldFlowDraftStorage,
+  FieldFlowDraftPayload,
+  UseFieldFlowDraftOptions,
+  UseFieldFlowDraftResult,
+} from './useFieldFlowDraft';
+
+export { useFieldFlowSteps } from './useFieldFlowSteps';
+export type {
+  FieldFlowStepDefinition,
+  UseFieldFlowStepsOptions,
+  UseFieldFlowStepsResult,
+} from './useFieldFlowSteps';
+
+export { useFieldFlowDirtyGuard } from './useFieldFlowDirtyGuard';
+export type {
+  UseFieldFlowDirtyGuardOptions,
+  UseFieldFlowDirtyGuardResult,
+} from './useFieldFlowDirtyGuard';

package/src/hooks/useFieldFlowArray.ts

@@ -0,0 +1,153 @@
+import { useCallback, useMemo, useState } from 'react';
+
+export interface UseFieldFlowArrayOptions<TItem> {
+  /** Initial rows. Default: `[]`. */
+  initialItems?: TItem[];
+  /** Factory for a blank row when calling `append()` without an argument. */
+  createItem: () => TItem;
+  /** Hard cap on rows. `append` becomes a no-op at the limit. */
+  max?: number;
+  /** Minimum rows. `remove` is blocked when at the floor. Default: 0. */
+  min?: number;
+}
+
+export interface UseFieldFlowArrayResult<TItem> {
+  items: TItem[];
+  /** Number of rows. */
+  length: number;
+  /** True when `max` is set and reached. */
+  isMax: boolean;
+  /** True when at `min` rows. */
+  isMin: boolean;
+  setItems: (items: TItem[] | ((prev: TItem[]) => TItem[])) => void;
+  /** Append a row (or `createItem()`). Returns the new index, or `-1` if blocked. */
+  append: (item?: TItem) => number;
+  /** Remove by index. Returns false if blocked by `min`. */
+  remove: (index: number) => boolean;
+  /** Replace a single row. */
+  update: (index: number, item: TItem | ((prev: TItem) => TItem)) => void;
+  /** Swap two indices. */
+  move: (from: number, to: number) => void;
+  /** Insert at index (clamped). */
+  insert: (index: number, item?: TItem) => void;
+  clear: () => void;
+  reset: () => void;
+}
+
+/**
+ * Manage dynamic / repeatable field groups (addresses, line items, guests, …)
+ * alongside FieldFlow inputs. Pure state — no UI assumptions.
+ *
+ * @example
+ * const guests = useFieldFlowArray({
+ *   createItem: () => ({ name: '', email: '' }),
+ *   min: 1,
+ *   max: 5,
+ * });
+ *
+ * guests.items.map((guest, i) => (
+ *   <FieldFlowInput
+ *     key={i}
+ *     label={`Guest ${i + 1}`}
+ *     value={guest.name}
+ *     onChangeText={name => guests.update(i, g => ({ ...g, name }))}
+ *   />
+ * ));
+ */
+export function useFieldFlowArray<TItem>({
+  initialItems = [],
+  createItem,
+  max,
+  min = 0,
+}: UseFieldFlowArrayOptions<TItem>): UseFieldFlowArrayResult<TItem> {
+  const [items, setItems] = useState<TItem[]>(initialItems);
+  const initialRef = useMemo(() => initialItems, []); // freeze initial for reset
+
+  const isMax = max !== undefined && items.length >= max;
+  const isMin = items.length <= min;
+
+  const append = useCallback(
+    (item?: TItem): number => {
+      let nextIndex = -1;
+      setItems(prev => {
+        if (max !== undefined && prev.length >= max) return prev;
+        const next = [...prev, item ?? createItem()];
+        nextIndex = next.length - 1;
+        return next;
+      });
+      return nextIndex;
+    },
+    [createItem, max],
+  );
+
+  const remove = useCallback(
+    (index: number): boolean => {
+      let removed = false;
+      setItems(prev => {
+        if (prev.length <= min) return prev;
+        if (index < 0 || index >= prev.length) return prev;
+        removed = true;
+        return prev.filter((_, i) => i !== index);
+      });
+      return removed;
+    },
+    [min],
+  );
+
+  const update = useCallback((index: number, item: TItem | ((prev: TItem) => TItem)) => {
+    setItems(prev => {
+      if (index < 0 || index >= prev.length) return prev;
+      const next = [...prev];
+      next[index] = typeof item === 'function' ? (item as (p: TItem) => TItem)(prev[index]) : item;
+      return next;
+    });
+  }, []);
+
+  const move = useCallback((from: number, to: number) => {
+    setItems(prev => {
+      if (from < 0 || to < 0 || from >= prev.length || to >= prev.length || from === to) {
+        return prev;
+      }
+      const next = [...prev];
+      const [row] = next.splice(from, 1);
+      next.splice(to, 0, row);
+      return next;
+    });
+  }, []);
+
+  const insert = useCallback(
+    (index: number, item?: TItem) => {
+      setItems(prev => {
+        if (max !== undefined && prev.length >= max) return prev;
+        const next = [...prev];
+        const at = Math.max(0, Math.min(index, next.length));
+        next.splice(at, 0, item ?? createItem());
+        return next;
+      });
+    },
+    [createItem, max],
+  );
+
+  const clear = useCallback(() => {
+    setItems(min > 0 ? Array.from({ length: min }, () => createItem()) : []);
+  }, [createItem, min]);
+
+  const reset = useCallback(() => {
+    setItems(initialRef);
+  }, [initialRef]);
+
+  return {
+    items,
+    length: items.length,
+    isMax,
+    isMin,
+    setItems,
+    append,
+    remove,
+    update,
+    move,
+    insert,
+    clear,
+    reset,
+  };
+}

package/src/hooks/useFieldFlowDirtyGuard.ts

@@ -0,0 +1,70 @@
+import { useCallback, useEffect } from 'react';
+import { Alert, BackHandler, Platform } from 'react-native';
+
+export interface UseFieldFlowDirtyGuardOptions {
+  /** When true, leaving the screen should confirm. */
+  isDirty: boolean;
+  enabled?: boolean;
+  title?: string;
+  message?: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  /** Android hardware back — intercept when dirty. Default: true. */
+  interceptAndroidBack?: boolean;
+  /** Called when the user confirms discard. */
+  onDiscard?: () => void;
+}
+
+export interface UseFieldFlowDirtyGuardResult {
+  /**
+   * Call before navigating away. Returns true if navigation may proceed.
+   * Shows a confirm alert when the form is dirty.
+   */
+  confirmIfDirty: () => Promise<boolean>;
+}
+
+/**
+ * Warns before leaving a dirty form (Android back + imperative `confirmIfDirty`).
+ * For React Navigation, call `confirmIfDirty` inside a `beforeRemove` listener.
+ */
+export function useFieldFlowDirtyGuard({
+  isDirty,
+  enabled = true,
+  title = 'Discard changes?',
+  message = 'You have unsaved changes. Leave without saving?',
+  confirmLabel = 'Discard',
+  cancelLabel = 'Stay',
+  interceptAndroidBack = true,
+  onDiscard,
+}: UseFieldFlowDirtyGuardOptions): UseFieldFlowDirtyGuardResult {
+  const confirmIfDirty = useCallback((): Promise<boolean> => {
+    if (!enabled || !isDirty) return Promise.resolve(true);
+
+    return new Promise(resolve => {
+      Alert.alert(title, message, [
+        { text: cancelLabel, style: 'cancel', onPress: () => resolve(false) },
+        {
+          text: confirmLabel,
+          style: 'destructive',
+          onPress: () => {
+            onDiscard?.();
+            resolve(true);
+          },
+        },
+      ]);
+    });
+  }, [enabled, isDirty, title, message, confirmLabel, cancelLabel, onDiscard]);
+
+  useEffect(() => {
+    if (!enabled || !interceptAndroidBack || Platform.OS !== 'android') return;
+
+    const sub = BackHandler.addEventListener('hardwareBackPress', () => {
+      if (!isDirty) return false;
+      void confirmIfDirty();
+      return true;
+    });
+    return () => sub.remove();
+  }, [enabled, interceptAndroidBack, isDirty, confirmIfDirty]);
+
+  return { confirmIfDirty };
+}