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

One-call wiring of a Docyrus data source to the DummyDataGenerator — handles field-aware strategies, deterministic generation, preview, and batch insert in a single guided flow.

## Installation

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

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

This hook is distributed as source. It needs an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusDummyDataGeneratorWizard` is the one-call entry point that wires a Docyrus data source to [`
    
    
  </>
);
```

### Side-by-side with `useDocyrusDataGrid`

Both hooks accept the same `client` + `appSlug` + `dataSourceSlug`. Wire `onGenerated` to the grid's `reload()` so newly inserted rows show up immediately:

```tsx
const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
const seeder = useDocyrusDummyDataGeneratorWizard({
  client,
  appSlug,
  dataSourceSlug,
  collection: grid.collection,         // bulk-insert via collection.createMany when available
  fields: grid.fields,                 // skip duplicate metadata fetch
  users: grid.users,                   // populate field-userSelect strategies
  onGenerated: () => grid.reload()
});

return (
  <>
    {grid.toolbar}
    
    {seeder.wizard}
  </>
);
```

### Preview-only flow (no inserts)

```tsx
const seeder = useDocyrusDummyDataGeneratorWizard({
  client,
  appSlug,
  dataSourceSlug,
  previewOnly: true,
  onGenerated: (_result, rows) => {
    download('seed.json', JSON.stringify(rows, null, 2));
  }
});
```

### Custom batch endpoint

```tsx
const seeder = useDocyrusDummyDataGeneratorWizard({
  client,
  appSlug,
  dataSourceSlug,
  insertRecords: async (rows) => {
    const response = await client.post(`/v1/apps/${appSlug}/data-sources/${dataSourceSlug}/items/bulk`, { records: rows });
    const errors = (response as { errors?: Array<{ index: number; message: string }> }).errors ?? [];

    return { errors: errors.map(e => ({ rowIndex: e.index, message: e.message })) };
  }
});
```

## API Reference

### Parameters

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated client from `@docyrus/api-client`. **Required.** |
| `appSlug` | `string` | — | Target app slug. **Required.** |
| `dataSourceSlug` | `string` | — | Target data source slug. **Required.** |
| `appId` | `string` | — | Optional multi-tenant isolation key. |
| `fields` | `Array<DocyrusFieldLike>` | — | Pre-resolved target fields. When provided, the hook skips its internal data source fetch. |
| `requiredFieldSlugs` | `Array<string>` | `[]` | Slugs locked to `enabled: true`. |
| `defaultCount` | `number` | `10` | Initial row count. |
| `maxCount` | `number` | `1000` | UI hard cap. |
| `previewRowCount` | `number` | `10` | Number of rows shown in the preview step. |
| `collection` | `{ create?, createMany? }` | — | Optional collection wrapper. `createMany` is preferred over per-record `create` for batch inserts. |
| `users` | `Array<DummyUserOption>` | — | Tenant users used for `field-userSelect` / `field-userMultiSelect` strategies. |
| `relationOptionsByFieldSlug` | `Record<string, Array<DummyRelationOption>>` | — | Relation pool keyed by field slug. Without it, relation fields are skipped. |
| `previewOnly` | `boolean` | `false` | When `true` the preview-step CTA is "Finish" — the hook never POSTs anything. |
| `enabled` | `boolean` | `true` | When `false` the hook returns `wizard: null` (use as a feature flag). |
| `onGenerated` | `(result, rows) => void` | — | Called after the progress phase completes. |
| `onError` | `(error: Error, rowIndex: number) => void` | — | Called whenever a per-row insert throws (default `insertRecords` only). |
| `insertRecords` | `(rows) => Promise<{ errors }>` | derived | Override the per-row insert pipeline. |
| `title` / `description` / `icon` | `ReactNode` / `ReactNode` / `string` | translated default | Override the wizard header copy. |
| `exportFileName` | `string` | `<dataSourceSlug>-dummy-data` | File name (without extension) for CSV / XLSX downloads. |

### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `wizard` | `ReactElement \| null` | Inline wizard panel. Render it directly or wrap it in a dialog. `null` when `enabled === false`. |
| `resetWizard` | `() => void` | Reset the wizard back to the configure step (clears generated rows + result). |
| `step` | `DummyDataGeneratorStep` | Current step. |
| `setStep` | `(step) => void` | Move to a step programmatically. |
| `count` / `setCount` | `number` / `(next) => void` | Row count + setter. Setter clamps to `[1, maxCount]`. |
| `strategies` / `setStrategies` | `DummyStrategyMap` / `(next) => void` | Per-field strategies + setter. |
| `generatedRows` | `Array<Record<string, unknown>>` | The rows shown in the preview / saved on the next step. |
| `result` | `DummyGenerationResult \| null` | Final-step summary. |
| `generateAsync` | `() => Array<Record<string, unknown>>` | Imperative generation that returns the rows (skips the wizard UI). |
| `insertAsync` | `(rows) => Promise<DummyGenerationResult>` | Imperative insert (skips the wizard UI). |
| `fields` | `Array<DocyrusFieldLike>` | Resolved target fields (from `fields` prop or `useDocyrusDataViewSelect`). |
| `isGenerating` / `isCreating` | `boolean` | Pending flags. |
| `error` | `Error \| null` | Last insert error. |

## Determinism

Generation uses a Mulberry32 PRNG seeded with a fresh value on every "Regenerate sample" click. Within one click, the preview rows are byte-identical to the rows that get inserted. Pass `seed` directly to `generateDummyRows(ctx)` if you want test-stable output.

## Error Handling

- Per-row insert errors are collected and shown as a per-row error list on the result step. The wizard always reaches the result step — partial failures don't abort the run.
- A thrown `insertRecords` (the override) marks every row as failed and surfaces the message in the per-row list.

## See Also

- [`<DummyDataGenerator>`](/docs/web/components/dummy-data-generator) — the presentational wizard wired by this hook.
- [`useDocyrusDataImportWizard`](/docs/web/hooks/use-docyrus-data-import-wizard) — companion hook for importing real spreadsheets.
- [`useDocyrusFieldComponent`](/docs/web/hooks/use-docyrus-field-component) — the registry that powers preview rendering.
- [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) — companion hook for displaying the inserted records.