Forms rendering

​

Files

​

Endpoints

export interface FormDetail {
  id: string;
  status: 'PENDING' | 'COMPLETED' | 'CANCELLED';
  formVersion: number;
  template: { id: string; name: string; type: string; description: string | null };
  schema: FormSchema;
}

export interface FormSchema {
  schemaVersion: 2;
  fields: FormFieldDef[];
  settings: {
    submitLabel?: string;
    successMessage?: string;
    displayName?: string;
    rtl: boolean;
    pages?: FormPageMeta[];
    thankYou?: { richText: RichSpan[] };
  };
}

export type FormAnswers = Record<string, unknown>;

​

Query hooks

​

How a form is reached

• Home card. PendingFormsCard (classic home) lists every item from useFormsList() and pushes /forms/:id. It refetches on every tab focus, and renders nothing when user.planFrozen is true or the list is empty. The three themed home screens read the same list through useHomeModel().pendingForms and call openForm(formId). See Home screen.
• Launch reminder. PendingFormPrompt is mounted once in src/app/(app)/_layout.tsx. usePendingFormPrompt filters the list to status === 'PENDING', sorts forms with a dueAt first (soonest first), and opens PendingFormDialog for the first one. A module-scope flag promptedThisLaunch limits it to once per cold start. It waits until useStartupPrompts reports settled and never opens while a workout session is started. Tapping outside or the later button dismisses it.
• Push notification. src/lib/notificationRouting.ts handles a notification whose data has target: 'form'. With an assignmentId it pushes /forms/[id], otherwise it pushes /home. See Notifications.

​

FormScreen

​

Hydration

​

Merged answers

​

Pages

​

Layout

​

FieldRenderer

type Props = {
  field: FormFieldDef;
  value: unknown;
  error?: string | null;
  foodCatalog?: FoodCatalog;
  foodCatalogLoading?: boolean;
  upload?: FieldUpload;
  onChange: (value: unknown) => void;
  onPickUpload: (source: UploadSource) => void;
  onRetryUpload: () => void;
  inputRef?: RefCallback<TextInput>;
  onFocus?: () => void;
  onBlur?: () => void;
  onDragChange?: (dragging: boolean) => void;
};

• value is answers[field.key], the raw value and not the merged one.
• error is passed only when the field is flagged.
• inputRef registers the text input with the stepper.
• onFocus and onChange call navigation.markActive(field.id). Picker-style fields receive onFocus as onOpenPicker.
• onBlur marks the field as visited.
• onDragChange sets sliderDragging.

​

Locked exit

• The route sets gestureEnabled: false, so the iOS back swipe is off.
• On Android, a BackHandler listener registered in useFocusEffect returns true for hardwareBackPress, which swallows the hardware back button.
• closeForm() calls flushFormDrafts(), then router.back() when possible, otherwise router.replace('/home').
• The thank-you dialog has no backdrop dismissal. Its only button and Android back both call closeForm, guarded by a ref so a double tap cannot pop two screens.

​

Validation

​

Blocking on unanswered fields

• missingFields(fields, errors) returns the fields that still fail validation. Optional empty fields never fail.
• isPageComplete is true when nothing is missing.
• flaggedFields(fields, errors, visited, isUploading) returns missing fields the trainee has already left, excluding any field whose upload is still running. Only flagged fields get the red outline and an inline error.
• nextMissingField(fields, errors, currentIndex) returns the first missing field after the cursor, or the first missing field on the page.

​

Submit flow

​

Upload fields

export type FieldUploadStatus = 'uploading' | 'failed' | 'tooLarge' | 'done';

export type FieldUpload = UploadSource & {
  status: FieldUploadStatus;
  progress: number;
};

1. Bumps a per-key run counter. Results from an older run are ignored, so picking a new file while one is uploading is safe.
2. Sets the entry to uploading with progress: 0 and an empty uri, and clears the field answer with setValue(key, undefined).
3. Awaits prepareImageForUpload(source). If it produced a new file, that local uri becomes the preview. If the source came back unchanged, the preview uri stays empty.
4. Calls uploadFile(...) with an onProgress callback. Progress is rounded to 1 percent steps before it reaches state.
5. On success sets done and stores fileUrl as the answer.
6. On error sets tooLarge when isPayloadTooLarge(error) is true, otherwise failed.