# useDocyrusDummyDataGeneratorWizard
URL: /docs/native/hooks/use-docyrus-dummy-data-generator-wizard

One-call wiring of a Docyrus data source to the native DummyDataGenerator. Loads the schema, seeds per-field strategies, generates seeded sample rows, previews and exports them, and inserts them into the data source. Returns an inline wizard element plus imperative helpers.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-dummy-data-generator-wizard
```

**Dependencies:**
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [expo-file-system (optional)](https://www.npmjs.com/package/expo-file-system)
- [expo-sharing (optional)](https://www.npmjs.com/package/expo-sharing)

This is a port of the web hook with the same options and result. It needs an authenticated `RestApiClient` and a `QueryClientProvider` above it. It renders [rn-dummy-data-generator](/docs/native/docyrus/dummy-data-generator). `expo-file-system` and `expo-sharing` are optional peers used only by the preview step's export menu.

## How it works

1. **Fields.** Target fields come from [`useDocyrusDataSourceFields`](/docs/native/hooks/use-docyrus-data-source-fields) (cache-first through the shared inventory), unless you pass `fields`. Whenever the field list changes, strategies are rebuilt with `buildInitialStrategyMap`, keeping the ones the user already edited.
2. **Generate.** **Preview rows** generates `count` rows with a fresh random seed through the pure `generateDummyRows`. **Regenerate sample** re-rolls the seed. User fields draw from `users`, and relation fields draw from `relationOptionsByFieldSlug`. The hook does not fetch either pool, so relation fields stay empty without it.
3. **Insert.** **Save to data source** inserts every generated row with, in order of preference, `insertRecords`, `collection.createMany({ records })`, per-row `collection.create(row)`, or per-row `POST /v1/apps/{appSlug}/data-sources/{dataSourceSlug}/items`. Per-row failures are collected into the result. With `previewOnly`, nothing is posted and **Finish** produces a result with `totalCreated: 0`.

## Usage

```tsx
import { useDocyrusClient } from '@docyrus/signin/react-native';

import { AwesomeDialog, AwesomeDialogBody, AwesomeDialogContent } from '@/components/docyrus-native/awesome-dialog';
import { useDocyrusDummyDataGeneratorWizard } from '@/hooks/docyrus-native/use-docyrus-dummy-data-generator-wizard';

export function SeedTasks({ open, onOpenChange, users }: Props) {
  const client = useDocyrusClient();
  const { wizard } = useDocyrusDummyDataGeneratorWizard({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'task',
    requiredFieldSlugs: ['name'],
    defaultCount: 25,
    users,
    enabled: open,
    onGenerated: result => console.log(`${result.totalCreated} created`)
  });

  return (
    
      
    
  );
}
```

The wizard is an inline element, so wrap it in your own dialog or sheet for modal use.

## API Reference

### Options (`UseDocyrusDummyDataGeneratorWizardOptions`)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated REST client (required). |
| `appSlug` | `string` | — | App slug (required). |
| `dataSourceSlug` | `string` | — | Data source slug (required). |
| `appId` | `string` | — | Accepted for web parity (web scopes its saved-view lookup by app id). |
| `fields` | `ReadonlyArray<DocyrusFieldLike>` | — | Pre-resolved target fields. Skips the schema fetch. |
| `requiredFieldSlugs` | `ReadonlyArray<string>` | `[]` | Slugs that must stay enabled. |
| `defaultCount` | `number` | `10` | Initial number of records. |
| `maxCount` | `number` | `1000` | Hard cap for the record count. |
| `previewRowCount` | `number` | `10` | Rows shown in the preview step. |
| `collection` | `{ create?: (input) => Promise<unknown>; createMany?: (input: { records }) => Promise<unknown> }` | — | Collection wrapper. `createMany` is preferred for batch inserts. |
| `users` | `ReadonlyArray<DummyUserOption>` | — | Tenant users for user fields. |
| `relationOptionsByFieldSlug` | `Record<string, ReadonlyArray<DummyRelationOption>>` | — | Relation pools keyed by field slug. Without them, relation fields are not generated. |
| `previewOnly` | `boolean` | `false` | Never POST; the preview step ends with **Finish** (download-only flows). |
| `enabled` | `boolean` | `true` | `false` returns `wizard: null` and skips the schema fetch. |
| `onGenerated` | `(result: DummyGenerationResult, rows: ReadonlyArray<Record<string, unknown>>) => void` | — | Called after the insert (or **Finish**) completes. |
| `onError` | `(error: Error, rowIndex: number) => void` | — | Called when a per-row insert throws. |
| `insertRecords` | `(rows) => Promise<{ errors: ReadonlyArray<{ rowIndex: number; message: string }> }>` | — | Replace the insert logic. |
| `title` | `ReactNode` | — | Wizard header title. |
| `description` | `ReactNode` | — | Wizard header description. |
| `icon` | `string` | — | Wizard header icon. |
| `exportFileName` | `string` | `'<dataSourceSlug>-dummy-data'` | File name (without extension) for exports. |

### Result (`UseDocyrusDummyDataGeneratorWizardResult`)

| Field | Type | Description |
|-------|------|-------------|
| `wizard` | `ReactElement \| null` | The wired inline `DummyDataGenerator`. |
| `resetWizard` | `() => void` | Back to the configure step. Clears the generated rows and the result. |
| `step` | `DummyDataGeneratorStep` | Current step. |
| `setStep` | `(next: DummyDataGeneratorStep) => void` | Change the step. |
| `generateAsync` | `() => ReadonlyArray<Record<string, unknown>>` | Generate rows with a new seed (synchronous) and store them. |
| `insertAsync` | `(rows) => Promise<DummyGenerationResult>` | Insert rows and resolve the result. |
| `fields` | `ReadonlyArray<DocyrusFieldLike>` | Resolved target fields. |
| `strategies` | `DummyStrategyMap` | Current strategies. |
| `setStrategies` | `(next: DummyStrategyMap) => void` | Replace the strategies. |
| `count` | `number` | Current record count. |
| `setCount` | `(next: number) => void` | Change the count. |
| `generatedRows` | `ReadonlyArray<Record<string, unknown>>` | Rows of the latest generation. |
| `result` | `DummyGenerationResult \| null` | Result of the latest insert. |
| `isGenerating` | `boolean` | Always `false`, because generation is synchronous. Kept for web parity. |
| `isCreating` | `boolean` | Insert in progress. |
| `error` | `Error \| null` | Insert error. |

## Differences from web

- Target fields come from the lightweight `useDocyrusDataSourceFields` schema hook instead of `useDocyrusDataViewSelect`.
- The preview step exports CSV, Excel, JSON and Markdown through the share sheet ([`useDataExport`](/docs/native/hooks/use-data-export)) instead of browser downloads.

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusDummyDataGeneratorWizardOptions` | Hook options. |
| `UseDocyrusDummyDataGeneratorWizardResult` | Hook result. |

The generator types (`DummyStrategyMap`, `DummyGenerationResult`, `DummyUserOption`, `DummyRelationOption`, …) are exported from [`dummy-data-generator`](/docs/native/docyrus/dummy-data-generator#type-exports).