rn-inputforge 0.4.0 → 0.5.1

package/src/a11y/audit.ts

@@ -0,0 +1,99 @@
+export type FieldFlowA11ySeverity = 'error' | 'warn' | 'info';
+
+export interface FieldFlowA11yIssue {
+  id: string;
+  severity: FieldFlowA11ySeverity;
+  message: string;
+  field?: string;
+}
+
+export interface FieldFlowA11yFieldSnapshot {
+  name: string;
+  label?: string;
+  hasError?: boolean;
+  errorText?: string;
+  required?: boolean;
+  /** Approximate hit target height in px (optional). */
+  hitHeight?: number;
+  /** True if accessibilityLabel / labelledBy is set. */
+  hasAccessibilityLabel?: boolean;
+  placeholderOnly?: boolean;
+}
+
+export interface FieldFlowA11yAuditInput {
+  fields: FieldFlowA11yFieldSnapshot[];
+  /** Form uses Reduce Motion–aware animations. */
+  respectsReducedMotion?: boolean;
+  /** Min touch target. Default: 44. */
+  minHitTarget?: number;
+}
+
+/**
+ * Dev-time accessibility audit for FieldFlow forms.
+ * Call in `__DEV__` and log / render via `FieldFlowA11yAudit`.
+ */
+export function runA11yAudit(input: FieldFlowA11yAuditInput): FieldFlowA11yIssue[] {
+  const minHit = input.minHitTarget ?? 44;
+  const issues: FieldFlowA11yIssue[] = [];
+
+  for (const field of input.fields) {
+    if (!field.label && !field.hasAccessibilityLabel) {
+      issues.push({
+        id: `label-${field.name}`,
+        severity: 'error',
+        field: field.name,
+        message: `Field "${field.name}" has no visible label or accessibilityLabel`,
+      });
+    }
+    if (field.placeholderOnly && !field.label) {
+      issues.push({
+        id: `placeholder-${field.name}`,
+        severity: 'warn',
+        field: field.name,
+        message: `Field "${field.name}" relies on placeholder as the only label`,
+      });
+    }
+    if (field.required && field.label && !/\*|required/i.test(field.label) && !field.hasAccessibilityLabel) {
+      issues.push({
+        id: `required-${field.name}`,
+        severity: 'info',
+        field: field.name,
+        message: `Required field "${field.name}" — ensure required state is announced`,
+      });
+    }
+    if (field.hasError && !field.errorText) {
+      issues.push({
+        id: `error-text-${field.name}`,
+        severity: 'error',
+        field: field.name,
+        message: `Field "${field.name}" is in error state without errorText for screen readers`,
+      });
+    }
+    if (field.hitHeight != null && field.hitHeight < minHit) {
+      issues.push({
+        id: `hit-${field.name}`,
+        severity: 'warn',
+        field: field.name,
+        message: `Field "${field.name}" hit target ~${field.hitHeight}px (min ${minHit})`,
+      });
+    }
+  }
+
+  if (input.respectsReducedMotion === false) {
+    issues.push({
+      id: 'reduced-motion',
+      severity: 'warn',
+      message: 'Animations may not respect Reduce Motion — use motion={false} or useReducedMotion',
+    });
+  }
+
+  if (input.fields.length === 0) {
+    issues.push({
+      id: 'empty',
+      severity: 'info',
+      message: 'No fields registered for audit',
+    });
+  }
+
+  return issues;
+}

package/src/a11y/index.ts

@@ -0,0 +1,7 @@
+export { runA11yAudit } from './audit';
+export type {
+  FieldFlowA11ySeverity,
+  FieldFlowA11yIssue,
+  FieldFlowA11yFieldSnapshot,
+  FieldFlowA11yAuditInput,
+} from './audit';

package/src/adapters/index.ts

@@ -0,0 +1,9 @@
+export {
+  FieldFlowController,
+  FieldFlowTagsController,
+  mapRhfToFieldFlowProps,
+} from './reactHookForm';
+export type {
+  FieldFlowControllerProps,
+  FieldFlowTagsControllerProps,
+} from './reactHookForm';

package/src/adapters/reactHookForm.tsx

@@ -0,0 +1,152 @@
+import React from 'react';
+import type { TextInput } from 'react-native';
+import {
+  Controller,
+  type Control,
+  type ControllerProps,
+  type FieldPath,
+  type FieldValues,
+  type RegisterOptions,
+} from 'react-hook-form';
+import { FieldFlowInput, type FieldFlowInputProps } from '../components/FieldFlowInput';
+import { FieldFlowTags, type FieldFlowTagsProps } from '../components/FieldFlowTags';
+
+type InputPassthrough = Omit<
+  FieldFlowInputProps,
+  | 'value'
+  | 'defaultValue'
+  | 'onChangeText'
+  | 'onBlur'
+  | 'onFocus'
+  | 'errorText'
+  | 'hasError'
+  | 'rules'
+>;
+
+export interface FieldFlowControllerProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> extends InputPassthrough {
+  control: Control<TFieldValues>;
+  name: TName;
+  /** react-hook-form register/controller rules. */
+  rules?: RegisterOptions<TFieldValues, TName>;
+  defaultValue?: ControllerProps<TFieldValues, TName>['defaultValue'];
+  /** When true, show the field error message from RHF. Default: true. */
+  showError?: boolean;
+}
+
+/**
+ * Drop-in `Controller` wrapper that renders a themed `FieldFlowInput`
+ * wired to react-hook-form. Requires the optional `react-hook-form` peer.
+ *
+ * @example
+ * const { control, handleSubmit } = useForm({ defaultValues: { email: '' } });
+ *
+ * <FieldFlowController
+ *   control={control}
+ *   name="email"
+ *   type="email"
+ *   label="Email"
+ *   rules={{ required: 'Email is required' }}
+ *   suggestions
+ * />
+ */
+export function FieldFlowController<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({
+  control,
+  name,
+  rules,
+  defaultValue,
+  showError = true,
+  ...inputProps
+}: FieldFlowControllerProps<TFieldValues, TName>) {
+  return (
+    <Controller
+      control={control}
+      name={name}
+      rules={rules}
+      defaultValue={defaultValue}
+      render={({ field, fieldState }) => (
+        <FieldFlowInput
+          {...inputProps}
+          ref={field.ref as React.Ref<TextInput>}
+          value={field.value == null ? '' : String(field.value)}
+          onChangeText={field.onChange}
+          onBlur={field.onBlur}
+          errorText={showError ? fieldState.error?.message : undefined}
+          hasError={showError ? Boolean(fieldState.error) : undefined}
+        />
+      )}
+    />
+  );
+}
+
+type TagsPassthrough = Omit<FieldFlowTagsProps, 'value' | 'onChange' | 'errorText' | 'hasError'>;
+
+export interface FieldFlowTagsControllerProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> extends TagsPassthrough {
+  control: Control<TFieldValues>;
+  name: TName;
+  rules?: RegisterOptions<TFieldValues, TName>;
+  defaultValue?: ControllerProps<TFieldValues, TName>['defaultValue'];
+  showError?: boolean;
+}
+
+/**
+ * RHF `Controller` for `FieldFlowTags` (string[] values).
+ */
+export function FieldFlowTagsController<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({
+  control,
+  name,
+  rules,
+  defaultValue,
+  showError = true,
+  ...tagsProps
+}: FieldFlowTagsControllerProps<TFieldValues, TName>) {
+  return (
+    <Controller
+      control={control}
+      name={name}
+      rules={rules}
+      defaultValue={defaultValue}
+      render={({ field, fieldState }) => (
+        <FieldFlowTags
+          {...tagsProps}
+          value={Array.isArray(field.value) ? field.value : []}
+          onChange={field.onChange}
+          errorText={showError ? fieldState.error?.message : undefined}
+          hasError={showError ? Boolean(fieldState.error) : undefined}
+        />
+      )}
+    />
+  );
+}
+
+/**
+ * Map an RHF `field` + `fieldState` onto common FieldFlow input props.
+ * Useful when you need a custom render or a non-input FieldFlow component.
+ */
+export function mapRhfToFieldFlowProps(args: {
+  value: unknown;
+  onChange: (...event: any[]) => void;
+  onBlur: () => void;
+  errorMessage?: string;
+  showError?: boolean;
+}): Pick<FieldFlowInputProps, 'value' | 'onChangeText' | 'onBlur' | 'errorText' | 'hasError'> {
+  const { value, onChange, onBlur, errorMessage, showError = true } = args;
+  return {
+    value: value == null ? '' : String(value),
+    onChangeText: onChange,
+    onBlur,
+    errorText: showError ? errorMessage : undefined,
+    hasError: showError ? Boolean(errorMessage) : undefined,
+  };
+}

package/src/autofill/index.ts

@@ -0,0 +1,10 @@
+export {
+  getAutofillProps,
+  autofillRoleFromFieldType,
+  autofillProfiles,
+} from './profiles';
+export type {
+  FieldFlowAutofillRole,
+  FieldFlowAutofillProps,
+  FieldFlowAutofillProfileName,
+} from './profiles';

package/src/autofill/profiles.ts

@@ -0,0 +1,224 @@
+import type { TextInputProps } from 'react-native';
+
+/**
+ * Semantic autofill roles — map to platform `autoComplete` + iOS `textContentType`.
+ * Pass as `autofill="email"` on `FieldFlowInput`, or use a profile bundle.
+ */
+export type FieldFlowAutofillRole =
+  | 'off'
+  | 'name'
+  | 'givenName'
+  | 'familyName'
+  | 'email'
+  | 'username'
+  | 'password'
+  | 'newPassword'
+  | 'oneTimeCode'
+  | 'tel'
+  | 'streetAddress'
+  | 'postalCode'
+  | 'addressCity'
+  | 'addressState'
+  | 'country'
+  | 'ccNumber'
+  | 'ccExp'
+  | 'ccCsc'
+  | 'ccName'
+  | 'organization'
+  | 'url'
+  | 'birthdate';
+
+export type FieldFlowAutofillProps = Pick<
+  TextInputProps,
+  'autoComplete' | 'textContentType' | 'importantForAutofill' | 'autoCorrect' | 'autoCapitalize'
+>;
+
+const ROLE_MAP: Record<FieldFlowAutofillRole, FieldFlowAutofillProps> = {
+  off: {
+    autoComplete: 'off',
+    textContentType: 'none',
+    importantForAutofill: 'no',
+  },
+  name: {
+    autoComplete: 'name',
+    textContentType: 'name',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'words',
+  },
+  givenName: {
+    autoComplete: 'given-name',
+    textContentType: 'givenName',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'words',
+  },
+  familyName: {
+    autoComplete: 'family-name',
+    textContentType: 'familyName',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'words',
+  },
+  email: {
+    autoComplete: 'email',
+    textContentType: 'emailAddress',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'none',
+    autoCorrect: false,
+  },
+  username: {
+    autoComplete: 'username',
+    textContentType: 'username',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'none',
+    autoCorrect: false,
+  },
+  password: {
+    autoComplete: 'password',
+    textContentType: 'password',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'none',
+    autoCorrect: false,
+  },
+  newPassword: {
+    autoComplete: 'password-new',
+    textContentType: 'newPassword',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'none',
+    autoCorrect: false,
+  },
+  oneTimeCode: {
+    autoComplete: 'sms-otp',
+    textContentType: 'oneTimeCode',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'none',
+    autoCorrect: false,
+  },
+  tel: {
+    autoComplete: 'tel',
+    textContentType: 'telephoneNumber',
+    importantForAutofill: 'yes',
+  },
+  streetAddress: {
+    autoComplete: 'street-address',
+    textContentType: 'fullStreetAddress',
+    importantForAutofill: 'yes',
+  },
+  postalCode: {
+    autoComplete: 'postal-code',
+    textContentType: 'postalCode',
+    importantForAutofill: 'yes',
+  },
+  addressCity: {
+    autoComplete: 'postal-address-locality',
+    textContentType: 'addressCity',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'words',
+  },
+  addressState: {
+    autoComplete: 'postal-address-region',
+    textContentType: 'addressState',
+    importantForAutofill: 'yes',
+  },
+  country: {
+    autoComplete: 'country',
+    textContentType: 'countryName',
+    importantForAutofill: 'yes',
+  },
+  ccNumber: {
+    autoComplete: 'cc-number',
+    textContentType: 'creditCardNumber',
+    importantForAutofill: 'yes',
+  },
+  ccExp: {
+    autoComplete: 'cc-exp',
+    textContentType: 'creditCardExpiration',
+    importantForAutofill: 'yes',
+  },
+  ccCsc: {
+    autoComplete: 'cc-csc',
+    textContentType: 'creditCardSecurityCode',
+    importantForAutofill: 'yes',
+  },
+  ccName: {
+    autoComplete: 'cc-name',
+    textContentType: 'creditCardName',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'words',
+  },
+  organization: {
+    autoComplete: 'organization',
+    textContentType: 'organizationName',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'words',
+  },
+  url: {
+    autoComplete: 'url',
+    textContentType: 'URL',
+    importantForAutofill: 'yes',
+    autoCapitalize: 'none',
+    autoCorrect: false,
+  },
+  birthdate: {
+    autoComplete: 'birthdate-full',
+    textContentType: 'none',
+    importantForAutofill: 'yes',
+  },
+};
+
+/** Resolve platform autofill props for a semantic role. */
+export function getAutofillProps(role: FieldFlowAutofillRole): FieldFlowAutofillProps {
+  return ROLE_MAP[role] ?? ROLE_MAP.off;
+}
+
+/** Infer a sensible autofill role from FieldFlow `type` when no explicit role is set. */
+export function autofillRoleFromFieldType(
+  type?: string,
+): FieldFlowAutofillRole | undefined {
+  switch (type) {
+    case 'email':
+      return 'email';
+    case 'phone':
+      return 'tel';
+    case 'password':
+      return 'password';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Named screen profiles — spread onto multiple fields.
+ * Example: `autofillProfiles.signup.email` → role `'email'`.
+ */
+export const autofillProfiles = {
+  login: {
+    email: 'email' as const,
+    username: 'username' as const,
+    password: 'password' as const,
+  },
+  signup: {
+    name: 'name' as const,
+    email: 'email' as const,
+    password: 'newPassword' as const,
+    phone: 'tel' as const,
+  },
+  shipping: {
+    name: 'name' as const,
+    street: 'streetAddress' as const,
+    city: 'addressCity' as const,
+    state: 'addressState' as const,
+    postalCode: 'postalCode' as const,
+    country: 'country' as const,
+    phone: 'tel' as const,
+  },
+  payment: {
+    name: 'ccName' as const,
+    number: 'ccNumber' as const,
+    expiry: 'ccExp' as const,
+    cvc: 'ccCsc' as const,
+  },
+  otp: {
+    code: 'oneTimeCode' as const,
+  },
+} as const;
+
+export type FieldFlowAutofillProfileName = keyof typeof autofillProfiles;

package/src/components/FieldFlowA11yAudit/FieldFlowA11yAudit.tsx

@@ -0,0 +1,112 @@
+import React, { useMemo } from 'react';
+import { StyleSheet, Text, View, type ViewStyle } from 'react-native';
+import { runA11yAudit, type FieldFlowA11yAuditInput, type FieldFlowA11yIssue } from '../../a11y';
+import { useFieldFlowTheme, mergeDeep } from '../../theme/ThemeProvider';
+import { defaultTheme } from '../../theme/defaultTheme';
+import type { DeepPartial, FieldFlowTheme } from '../../types';
+
+export interface FieldFlowA11yAuditProps {
+  /** Audit input — or pass precomputed `issues`. */
+  audit?: FieldFlowA11yAuditInput;
+  issues?: FieldFlowA11yIssue[];
+  /** Only render in __DEV__ when true (default). */
+  devOnly?: boolean;
+  title?: string;
+  containerStyle?: ViewStyle;
+  theme?: DeepPartial<FieldFlowTheme>;
+  testID?: string;
+}
+
+/**
+ * Dev overlay listing accessibility issues for the current form.
+ * No-ops in production when `devOnly` is true.
+ */
+export function FieldFlowA11yAudit({
+  audit,
+  issues: issuesProp,
+  devOnly = true,
+  title = 'FieldFlow a11y audit',
+  containerStyle,
+  theme: themeOverride,
+  testID,
+}: FieldFlowA11yAuditProps) {
+  // Prefer RN `__DEV__`; fall back without assuming Node `process` types.
+  const isDev =
+    typeof __DEV__ !== 'undefined'
+      ? __DEV__
+      : typeof process !== 'undefined' &&
+        typeof process.env !== 'undefined' &&
+        process.env.NODE_ENV !== 'production';
+
+  const issues = useMemo(() => {
+    if (issuesProp) return issuesProp;
+    if (audit) return runA11yAudit(audit);
+    return [];
+  }, [audit, issuesProp]);
+
+  const contextTheme = useFieldFlowTheme();
+  const theme = useMemo(
+    () => (themeOverride ? mergeDeep(contextTheme ?? defaultTheme, themeOverride) : contextTheme ?? defaultTheme),
+    [contextTheme, themeOverride],
+  );
+  const styles = useMemo(() => createStyles(theme), [theme]);
+
+  if (devOnly && !isDev) return null;
+  if (issues.length === 0) {
+    return (
+      <View style={[styles.wrap, styles.ok, containerStyle]} testID={testID}>
+        <Text style={styles.title}>{title}</Text>
+        <Text style={styles.okText}>No issues found</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={[styles.wrap, containerStyle]} testID={testID}>
+      <Text style={styles.title}>
+        {title} ({issues.length})
+      </Text>
+      {issues.map(issue => (
+        <Text
+          key={issue.id}
+          style={[
+            styles.item,
+            issue.severity === 'error' && styles.error,
+            issue.severity === 'warn' && styles.warn,
+          ]}
+        >
+          [{issue.severity}] {issue.field ? `${issue.field}: ` : ''}
+          {issue.message}
+        </Text>
+      ))}
+    </View>
+  );
+}
+
+function createStyles(theme: FieldFlowTheme) {
+  return StyleSheet.create({
+    wrap: {
+      marginVertical: 8,
+      padding: 12,
+      borderRadius: 8,
+      borderWidth: 1,
+      borderColor: theme.colors.borderError,
+      backgroundColor: theme.colors.background,
+    },
+    ok: { borderColor: theme.colors.borderSuccess },
+    title: {
+      fontWeight: '700',
+      marginBottom: 6,
+      color: theme.colors.text,
+      fontSize: theme.typography.helperFontSize + 1,
+    },
+    item: {
+      fontSize: theme.typography.helperFontSize,
+      color: theme.colors.label,
+      marginBottom: 4,
+    },
+    error: { color: theme.colors.error },
+    warn: { color: '#B45309' },
+    okText: { color: theme.colors.success, fontSize: theme.typography.helperFontSize },
+  });
+}

package/src/components/FieldFlowA11yAudit/index.ts

@@ -0,0 +1,2 @@
+export { FieldFlowA11yAudit } from './FieldFlowA11yAudit';
+export type { FieldFlowA11yAuditProps } from './FieldFlowA11yAudit';