rn-inputforge 0.4.0 → 0.5.0

package/src/components/FieldFlowTypeahead/FieldFlowTypeahead.tsx

@@ -0,0 +1,261 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import {
+  ActivityIndicator,
+  FlatList,
+  Pressable,
+  StyleSheet,
+  Text,
+  TextInput,
+  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, FieldFlowOption, FieldFlowTheme } from '../../types';
+
+export type FieldFlowTypeaheadFetcher = (
+  query: string,
+) => Promise<FieldFlowOption[]> | FieldFlowOption[];
+
+export interface FieldFlowTypeaheadProps {
+  value?: string | null;
+  /** Selected option label for display when value is set. */
+  displayValue?: string;
+  onChange: (value: string | null, option?: FieldFlowOption) => void;
+  /**
+   * Async (or sync) option loader. Debounced by `debounceMs`.
+   * Return [] when nothing matches.
+   */
+  fetchOptions: FieldFlowTypeaheadFetcher;
+  /** Optional static fallback options used when query is empty. */
+  defaultOptions?: FieldFlowOption[];
+  label?: string;
+  placeholder?: string;
+  helperText?: string;
+  errorText?: string;
+  disabled?: boolean;
+  required?: boolean;
+  debounceMs?: number;
+  minChars?: number;
+  emptyText?: string;
+  /** Custom dropdown row. Call `select()` to commit. */
+  renderOption?: (ctx: {
+    option: FieldFlowOption;
+    selected: boolean;
+    select: () => void;
+  }) => React.ReactNode;
+  /** Custom empty / no-results state. */
+  renderEmpty?: (ctx: { query: string; loading: boolean }) => React.ReactNode;
+  containerStyle?: ViewStyle;
+  labelStyle?: TextStyle;
+  theme?: DeepPartial<FieldFlowTheme>;
+  testID?: string;
+}
+
+export function FieldFlowTypeahead({
+  value,
+  displayValue,
+  onChange,
+  fetchOptions,
+  defaultOptions = [],
+  label,
+  placeholder = 'Search…',
+  helperText,
+  errorText,
+  disabled,
+  required,
+  debounceMs = 300,
+  minChars = 1,
+  emptyText = 'No results',
+  renderOption,
+  renderEmpty,
+  containerStyle,
+  labelStyle,
+  theme: themeOverride,
+  testID,
+}: FieldFlowTypeaheadProps) {
+  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 [query, setQuery] = useState(displayValue ?? '');
+  const [options, setOptions] = useState<FieldFlowOption[]>(defaultOptions);
+  const [open, setOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const gen = useRef(0);
+
+  useEffect(() => {
+    if (displayValue != null) setQuery(displayValue);
+  }, [displayValue]);
+
+  useEffect(() => {
+    if (!open) return;
+    const q = query.trim();
+    if (q.length < minChars) {
+      setOptions(defaultOptions);
+      setLoading(false);
+      return;
+    }
+
+    const id = setTimeout(async () => {
+      const token = ++gen.current;
+      setLoading(true);
+      try {
+        const result = await fetchOptions(q);
+        if (token === gen.current) setOptions(result);
+      } finally {
+        if (token === gen.current) setLoading(false);
+      }
+    }, debounceMs);
+
+    return () => clearTimeout(id);
+  }, [query, open, debounceMs, minChars, fetchOptions, defaultOptions]);
+
+  return (
+    <View style={[styles.wrap, containerStyle]} testID={testID}>
+      {label ? (
+        <Text style={[styles.label, labelStyle]}>
+          {label}
+          {required ? ' *' : ''}
+        </Text>
+      ) : null}
+
+      <View style={styles.field}>
+        {renderFieldFlowIcon('search', theme.colors.icon, 16)}
+        <TextInput
+          style={styles.input}
+          value={query}
+          editable={!disabled}
+          placeholder={placeholder}
+          placeholderTextColor={theme.colors.placeholder}
+          onFocus={() => setOpen(true)}
+          onChangeText={text => {
+            setQuery(text);
+            setOpen(true);
+            if (value != null) onChange(null);
+          }}
+        />
+        {loading ? <ActivityIndicator size="small" color={theme.colors.borderFocused} /> : null}
+        {query ? (
+          <Pressable
+            onPress={() => {
+              setQuery('');
+              onChange(null);
+              setOptions(defaultOptions);
+            }}
+            hitSlop={8}
+          >
+            {renderFieldFlowIcon('clear', theme.colors.icon, 14)}
+          </Pressable>
+        ) : null}
+      </View>
+
+      {open && !disabled ? (
+        <View style={styles.dropdown}>
+          <FlatList
+            keyboardShouldPersistTaps="handled"
+            data={options}
+            keyExtractor={item => item.value}
+            ListEmptyComponent={
+              loading
+                ? null
+                : renderEmpty
+                  ? <>{renderEmpty({ query, loading })}</>
+                  : <Text style={styles.empty}>{emptyText}</Text>
+            }
+            renderItem={({ item }) => {
+              const select = () => {
+                setQuery(item.label);
+                onChange(item.value, item);
+                setOpen(false);
+              };
+              if (renderOption) {
+                return (
+                  <>
+                    {renderOption({
+                      option: item,
+                      selected: item.value === value,
+                      select,
+                    })}
+                  </>
+                );
+              }
+              return (
+                <Pressable
+                  style={styles.option}
+                  disabled={item.disabled}
+                  onPress={select}
+                >
+                  <Text style={styles.optionLabel}>{item.label}</Text>
+                  {item.description ? (
+                    <Text style={styles.optionDesc}>{item.description}</Text>
+                  ) : null}
+                </Pressable>
+              );
+            }}
+            style={{ maxHeight: 200 }}
+          />
+        </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, zIndex: 2 },
+    label: {
+      fontSize: theme.typography.labelFontSize,
+      marginBottom: theme.spacing.gap / 1.5,
+      color: hasError ? theme.colors.error : theme.colors.label,
+      fontWeight: '500',
+    },
+    field: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: 8,
+      borderWidth: hasError ? theme.spacing.borderWidthFocused : theme.spacing.borderWidth,
+      borderColor: hasError ? theme.colors.borderError : theme.colors.border,
+      borderRadius: theme.spacing.borderRadius,
+      paddingHorizontal: theme.spacing.paddingHorizontal,
+      backgroundColor: theme.colors.background,
+      minHeight: theme.spacing.paddingVertical * 2 + theme.typography.fontSize + 6,
+    },
+    input: {
+      flex: 1,
+      fontSize: theme.typography.fontSize,
+      color: theme.colors.text,
+      paddingVertical: theme.spacing.paddingVertical,
+    },
+    dropdown: {
+      marginTop: 4,
+      borderWidth: theme.spacing.borderWidth,
+      borderColor: theme.colors.border,
+      borderRadius: theme.spacing.borderRadius,
+      backgroundColor: theme.colors.background,
+      overflow: 'hidden',
+    },
+    option: {
+      paddingHorizontal: 14,
+      paddingVertical: 12,
+      borderBottomWidth: StyleSheet.hairlineWidth,
+      borderBottomColor: theme.colors.border,
+    },
+    optionLabel: { color: theme.colors.text, fontSize: theme.typography.fontSize },
+    optionDesc: { color: theme.colors.label, fontSize: theme.typography.helperFontSize, marginTop: 2 },
+    empty: { padding: 14, color: theme.colors.placeholder, textAlign: 'center' },
+    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/FieldFlowTypeahead/index.ts

@@ -0,0 +1,2 @@
+export { FieldFlowTypeahead } from './FieldFlowTypeahead';
+export type { FieldFlowTypeaheadProps, FieldFlowTypeaheadFetcher } from './FieldFlowTypeahead';

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

@@ -9,7 +9,38 @@ export type {
   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,
+  };
+}