rn-inputforge 0.4.0 → 0.5.1

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/components/KeyboardAwareFormWrapper/KeyboardAwareFormWrapper.tsx

@@ -1,9 +1,10 @@
-import React from 'react';
+import React, { useRef } from 'react';
 import { KeyboardAvoidingView, Platform, ScrollView, StyleSheet, ViewStyle } from 'react-native';
 import type { UseKeyboardManagerResult } from '../../hooks/useKeyboardManager';
 
 export interface KeyboardAwareFormWrapperProps {
-  keyboardManager: Pick<UseKeyboardManagerResult, 'scrollViewRef'>;
+  /** Optional — omit when you only need keyboard-avoiding scroll without Next/Done chaining. */
+  keyboardManager?: Pick<UseKeyboardManagerResult, 'scrollViewRef'>;
   children: React.ReactNode;
   contentContainerStyle?: ViewStyle;
   style?: ViewStyle;
@@ -13,7 +14,7 @@ export interface KeyboardAwareFormWrapperProps {
  * Wrap your form fields in this instead of a plain ScrollView. It automatically
  * keeps the focused field visible above the keyboard and animates smoothly on
  * both iOS and Android; pass it the same `keyboardManager` you got from
- * `useKeyboardManager()`.
+ * `useKeyboardManager()` when you want auto-scroll + Next/Done focus.
  */
 export function KeyboardAwareFormWrapper({
   keyboardManager,
@@ -21,6 +22,9 @@ export function KeyboardAwareFormWrapper({
   contentContainerStyle,
   style,
 }: KeyboardAwareFormWrapperProps) {
+  const fallbackScrollRef = useRef<ScrollView>(null);
+  const scrollRef = keyboardManager?.scrollViewRef ?? fallbackScrollRef;
+
   return (
     <KeyboardAvoidingView
       style={[styles.flex, style]}
@@ -28,7 +32,7 @@ export function KeyboardAwareFormWrapper({
       keyboardVerticalOffset={Platform.OS === 'ios' ? 64 : 0}
     >
       <ScrollView
-        ref={keyboardManager.scrollViewRef}
+        ref={scrollRef}
         keyboardShouldPersistTaps="handled"
         contentContainerStyle={[styles.content, contentContainerStyle]}
         showsVerticalScrollIndicator={false}

package/src/hooks/index.ts

@@ -9,7 +9,55 @@ 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';
+
+export { useFieldFlowCompleteness } from './useFieldFlowCompleteness';
+export type {
+  UseFieldFlowCompletenessOptions,
+  UseFieldFlowCompletenessResult,
+} from './useFieldFlowCompleteness';
+
+export { useFieldFlowSubmitQueue } from './useFieldFlowSubmitQueue';
+export type {
+  FieldFlowSubmitJob,
+  FieldFlowSubmitQueueStorage,
+  UseFieldFlowSubmitQueueOptions,
+  UseFieldFlowSubmitQueueResult,
+} from './useFieldFlowSubmitQueue';
+
+export { useSmartPaste } from './useSmartPaste';
+export type { UseSmartPasteOptions } from './useSmartPaste';