# StepActionForms

Forms for configuring task actions within Employee Lifecycle process steps.

## Structure

All forms use the same **provider / form / content** split (refactor-form skill §11): `provider.tsx` loads data, `form.tsx` is the drawer shell + submit, `content.tsx` is the pure fields. Default export is the provider.

```
StepActionForms/
├── shared/                # Shared components, hooks, schemas, transforms
├── CustomTaskForm/        # Generic task (provider, form, content)
├── SurveyConfigForm/      # Survey task + Form Builder (provider, form, content)
└── DocumentRequestForm/   # Document request task (provider, form, content)
```

## Architecture

```
┌──────────────────┐   ┌──────────────────┐   ┌───────────────────────┐
│  CustomTaskForm  │   │ SurveyConfigForm │   │  DocumentRequestForm  │
│                  │   │                  │   │                       │
│  Basic tasks     │   │  + Survey Block  │   │  + Folder selector    │
│  without survey  │   │  + Form Builder  │   │  + Document list      │
└────────┬─────────┘   └────────┬─────────┘   └──────────┬────────────┘
         │                      │                         │
         └──────────────────────┬─────────────────────────┘
                                ▼
                     ┌──────────────────┐
                     │      shared/     │
                     │                  │
                     │  UI Sections     │
                     │  Hooks           │
                     │  Schemas         │
                     │  Transforms      │
                     └──────────────────┘
```

## Data Flow

Providers get form default values via **useGetFormDefaultValues** (Process/hooks): it returns `defaultValues`, `isLoading`, and `error`. All display data (drawer title, Survey dynamicFormData) comes from `defaultValues`; the hook passes the action to `getDefaultValuesFn` so Survey can set `dynamicFormData` from `action.task`.

```
Backend Action ──► useGetFormDefaultValues (internally convertStepActionToFormValues) ──► defaultValues, isLoading, error
                                                                                    │
                                                                               (user edits)
                                                                                    │
Form Values ──► convertFormValuesToStepAction() ──► Backend Request
```

## Usage

Drawers are opened via **useActionDrawer** (Process/hooks/useActionDrawer), used in StepActionList (menu “new”) and ProcessActionActions (option “Edit”). The hook uses DrawerLayer and renders the form **provider** as content; the form closes itself with `useDrawerLayer().closeDrawer()` (no `onClose` or success/cancel callbacks from the opener).

```tsx
// Opener (e.g. StepActionList or ProcessActionActions): one hook, open by type and optional actionId
const { openDrawer } = useActionDrawer({ processId, stepId, disabled });

openDrawer('CUSTOM');              // create custom task
openDrawer('FORM');                // create survey
openDrawer('DOCUMENT');            // create document request
openDrawer('CUSTOM', actionId);    // edit custom task
openDrawer('FORM', actionId);      // edit survey
openDrawer('DOCUMENT', actionId);  // edit document request
```

The hook internally does `openDrawer({ content: <CustomTaskFormProvider ... /> })` (or SurveyConfigFormProvider) with the right props. Each form’s **provider** loads default values via **useGetFormDefaultValues** and renders the **form** (drawer shell); the form draws Drawer.Header/Body/Actions and renders **content** (pure fields) inside the body, and handles submit/cancel.

```tsx
// Standalone (e.g. tests): render provider directly with optional callbacks
<CustomTaskFormProvider
  formId="create-task"
  processId={processId}
  stepId={stepId}
  onSubmitted={handleSuccess}
  onCancel={handleClose}
/>
```

## Key Differences

| Feature | CustomTaskForm | SurveyConfigForm | DocumentRequestForm |
|---------|---------------|------------------|---------------------|
| Survey Builder | ❌ | ✅ | ❌ |
| Auto-save on builder open | ❌ | ✅ | ❌ |
| Cancel cleanup | ❌ | ✅ (deletes incomplete action) | ❌ |
| Extra provider query | ❌ | ❌ | ✅ (resolves folder name) |
| Dynamic field list | ❌ | ❌ | ✅ (requiredDocuments) |

## See Also

- `shared/README.md` - Shared components and hooks documentation
- `CustomTaskForm/README.md` - CustomTaskForm specifics
- `SurveyConfigForm/README.md` - SurveyConfigForm specifics
- `DocumentRequestForm/README.md` - DocumentRequestForm specifics
