# rn-dummy-data-generator
URL: /docs/native/docyrus/dummy-data-generator

Inline three-step wizard (Configure → Preview → Result) that generates realistic sample records per field type with a seeded generator, previews them with the value renderers, exports CSV / Excel / JSON / Markdown through the share sheet, and saves them to a data source. API-aligned with the web DummyDataGenerator.

## Installation

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

**Dependencies:**
- [expo-file-system (optional)](https://www.npmjs.com/package/expo-file-system)
- [expo-sharing (optional)](https://www.npmjs.com/package/expo-sharing)

`expo-file-system` and `expo-sharing` are **optional peers** that only the preview step's **Export** menu uses (through [`useDataExport`](/docs/native/hooks/use-data-export)). Without them, the export writes nothing.

`DummyDataGenerator` is the **presentational** wizard: every piece of state comes in through props, and the generator libs are pure (no React, no fetches). To connect it to a Docyrus data source (schema, generation, batch insert), use [`useDocyrusDummyDataGeneratorWizard`](/docs/native/hooks/use-docyrus-dummy-data-generator-wizard), which returns a ready `wizard` element.

## Usage

```tsx
import { useState } from 'react';

import {
  DummyDataGenerator,
  buildInitialStrategyMap,
  generateDummyRows,
  type DummyDataGeneratorStep
} from '@/components/docyrus-native/dummy-data-generator';

export function SampleRows({ fields }: { fields: DocyrusFieldLike[] }) {
  const [step, setStep] = useState<DummyDataGeneratorStep>('configure');
  const [count, setCount] = useState(20);
  const [strategies, setStrategies] = useState(() => buildInitialStrategyMap(fields));
  const [rows, setRows] = useState<Array<Record<string, unknown>>>([]);

  const generate = (seed = Date.now()) => setRows(generateDummyRows({ fields, strategies, count, seed }));

  return (
    <DummyDataGenerator
      step={step}
      onStepChange={setStep}
      targetFields={fields}
      count={count}
      onCountChange={setCount}
      strategies={strategies}
      onStrategiesChange={setStrategies}
      generatedRows={rows}
      onRegenerate={() => generate()}
      isGenerating={false}
      isCreating={false}
      generationError={null}
      result={null}
      previewOnly
      onConfirmConfigure={() => {
        generate();
        setStep('preview');
      }}
      onStartGeneration={() => setStep('configure')}
      onReset={() => setStep('configure')} />
  );
}
```

## Wizard steps

| Step | Purpose |
|------|---------|
| **Configure** | Record count (up to `maxCount`), a summary of enabled / auto-skipped fields, and one collapsible card per supported field. Each card has an enable switch (required fields stay on) and per-type controls: text shape or static value, number mode / range / integers / fixed value, currency, phone country code, date mode / window / range span, truth ratio, enum pool and mode, items per row, user pool, and a random-null ratio. Unsupported and system fields are listed as skipped. |
| **Preview** | The first `previewRowCount` rows in a horizontally scrolling table rendered with the value renderers, plus **Regenerate sample** and an **Export** action sheet (CSV, Excel, JSON, Markdown). Exports include a label column and an `… ID` column for user and relation fields. |
| **Result** | Created / failed / generated tiles and a per-row error list, with **Generate more**. |

The primary action is **Preview rows** on the configure step. On the preview step it is **Save to data source**, or **Finish** when `previewOnly` is set.

## API Reference

### DummyDataGeneratorProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `step` | `DummyDataGeneratorStep` | — | Current step (required). |
| `onStepChange` | `(next: DummyDataGeneratorStep) => void` | — | Step setter, used by **Back** (required). |
| `targetFields` | `ReadonlyArray<DocyrusFieldLike>` | — | Fields the user can populate (required). |
| `requiredFieldSlugs` | `ReadonlyArray<string>` | `[]` | Slugs that must stay enabled. |
| `count` | `number` | — | Number of records to generate (required). |
| `onCountChange` | `(next: number) => void` | — | Count setter (required). |
| `maxCount` | `number` | `1000` | Hard cap for `count`. |
| `strategies` | `DummyStrategyMap` | — | Per-field generation knobs (required). |
| `onStrategiesChange` | `(next: DummyStrategyMap) => void` | — | Strategy setter (required). |
| `generatedRows` | `ReadonlyArray<Record<string, unknown>>` | — | Rows shown in the preview (required). |
| `onRegenerate` | `() => void` | — | Re-roll the seed and regenerate (required). |
| `isGenerating` | `boolean` | — | Generation in progress (required). |
| `isCreating` | `boolean` | — | Insert in progress (required). |
| `generationError` | `Error \| null` | — | Error shown on the result step (required). |
| `result` | `DummyGenerationResult \| null` | — | Insert result (required). |
| `previewRowCount` | `number` | `10` | Rows shown in the preview step. |
| `exportFileName` | `string` | `'dummy-data'` | File name (without extension) for exports. |
| `onConfirmConfigure` | `() => void` | — | Configure step primary action (required). |
| `onStartGeneration` | `() => void` | — | Preview step primary action (required). |
| `onReset` | `() => void` | — | **Generate more** on the result step (required). |
| `previewOnly` | `boolean` | `false` | Hide **Save to data source**; the preview step ends with **Finish**. |
| `users` | `ReadonlyArray<DummyUserOption>` | — | User pool for user fields. |
| `relationOptionsByFieldSlug` | `Record<string, ReadonlyArray<DummyRelationOption>>` | — | Relation pools, also used to print relation labels in exports. |
| `title` | `ReactNode` | `t('ui.dummyDataGenerator.title', 'Generate dummy data')` | Header title. |
| `description` | `ReactNode` | `t('ui.dummyDataGenerator.description', …)` | Header description. |
| `icon` | `string` | `'fal sparkles'` | `DocyrusIcon` in the header. |
| `className` | `string` | — | Root card classes. |

### DummyFieldStrategy

| Field | Type | Description |
|-------|------|-------------|
| `enabled` | `boolean` | Include the field in generated rows. |
| `emptyRatio` | `number` | 0..1 chance of leaving the value empty. |
| `textMode` | `TextStrategyMode` | `'word' \| 'words' \| 'sentence' \| 'paragraph' \| 'firstName' \| 'lastName' \| 'fullName' \| 'company' \| 'jobTitle' \| 'static'`. |
| `staticText` | `string` | Value for `textMode: 'static'`. |
| `numberMode` | `NumberStrategyMode` | `'random' \| 'sequence' \| 'fixed'`. |
| `min` / `max` / `step` | `number` | Numeric bounds and sequence step. |
| `integer` | `boolean` | Integers only. |
| `staticNumber` | `number` | Value for `numberMode: 'fixed'`. |
| `dateMode` | `DateStrategyMode` | `'past' \| 'future' \| 'recent' \| 'now' \| 'random'`. |
| `daysWindow` | `number` | ± days from now. |
| `rangeMaxDays` | `number` | Maximum span for date ranges (default 14). |
| `truthRatio` | `number` | 0..1 share of `true` for booleans (default 0.5). |
| `countryCode` | `string` | Phone default country code (for example `+90`). |
| `currencyCode` | `string` | Money currency (for example `USD`). |
| `enumMode` | `EnumStrategyMode` | `'random' \| 'cycle' \| 'static'`. |
| `staticEnumId` | `string` | Option id for `enumMode: 'static'`. |
| `selectedOptionIds` | `ReadonlyArray<string>` | Restrict enums to these options. |
| `multiMin` / `multiMax` | `number` | Items per row for multi-selects. |
| `selectedUserIds` | `ReadonlyArray<string>` | Restrict users to these ids. |
| `selectedRelationIds` | `ReadonlyArray<string>` | Restrict relations to these ids. |

### DummyGenerationResult

| Field | Type | Description |
|-------|------|-------------|
| `totalGenerated` | `number` | Rows generated. |
| `totalCreated` | `number` | Rows inserted. |
| `totalFailed` | `number` | Rows that failed. |
| `errors` | `ReadonlyArray<{ rowIndex: number; message: string }>` | Per-row errors. |

`DummyUserOption` accepts `id` / `value`, `name` / `display_name` / `displayName` / `label`, `email` and `avatar_url` / `avatarUrl`. `DummyRelationOption` is `{ id, name }`.

## Components

| Component | Description |
|-----------|-------------|
| `DummyDataGenerator` | Inline card: header, `Stepper`, step body, footer. |
| `ConfigureStep` | Count and per-field strategy cards. |
| `PreviewStep` | Value-renderer preview table and export menu. |
| `ProgressStep` | Insert progress and result tiles. |

## Helpers

| Export | Description |
|--------|-------------|
| `buildInitialStrategyMap(fields)` | Default strategy for every supported, non-system field. |
| `inferStrategyForField(field)` | Default strategy for one field. |
| `isSupportedFieldType(type)` / `isSystemFieldSlug(slug)` | Field filters. |
| `SYSTEM_FIELD_SLUGS` | Slugs that are never generated. |
| `generateDummyRows(context)` | Pure, seeded row generator (`DummyGenerationContext`). |
| `createRng(seed)` | Mulberry32 seeded RNG. |
| `DUMMY_DATA_GENERATOR_STEPS` | `['configure', 'preview', 'progress', 'result']`. |

## Native differences

- The wizard is an inline card. Wrap it in an `AwesomeDialog` or a sheet for modal use.
- Field strategies are collapsible cards instead of a table.
- The web preview downloads CSV and Excel. Native adds JSON and Markdown and hands every file to the share sheet through `useDataExport` (optional `expo-file-system` + `expo-sharing`). Excel is written by the zero-dependency writer in the internal `lib/native-export`.

## Translation keys

`ui.dummyDataGenerator.*`: `title`, `description`, `steps.*`, `actions.*`, `configure.*`, `preview.*`, `progress.*` and `result.*` (same keys as web).

## Type Exports

| Type | Description |
|------|-------------|
| `DummyDataGeneratorProps` | Component props. |
| `DummyDataGeneratorStep` | `'configure' \| 'preview' \| 'progress' \| 'result'`. |
| `DummyFieldStrategy` / `DummyStrategyMap` | Per-field knobs and the map keyed by slug. |
| `DummyGenerationContext` | Input of `generateDummyRows`. |
| `DummyGenerationResult` | Insert result. |
| `DummyUserOption` / `DummyRelationOption` | Pools for user and relation fields. |
| `TextStrategyMode` / `NumberStrategyMode` / `DateStrategyMode` / `EnumStrategyMode` | Strategy modes. |