## `buildState(fn)`

- **fn**: A callback that receives a **builder** (an instance of the `MockStateBuilderMain`).
- Returns an object: `{ builder }`.
  - `builder` is the builder instance with your callback modifications.

**Example:**

```ts
import { buildState } from '@mondaydotcomorg/vulcan-client/testkit';

// Basic usage
buildState(b => b.addBoard({ name: 'Demo Board' }));
```

In the above example:

1. We call `buildState`, passing a callback that receives `b`.
2. Inside that callback, we do `b.addBoard({ name: 'Demo Board' })`.

---

## `builder.sync()`

Commits any changes made to the builder into Vulcan.

- **When to use:**
  - If you do extra building after the initial `buildState` callback.
  - If you turned off the auto-sync in advanced usage (in some cases).

```ts
const { builder } = buildState(
  b => b.addBoard({ name: 'Board in initial callback' }) // auto-synced after callback
);

// Now we add more stuff afterwards
builder.addUser({ name: 'Alice' });

// Must sync manually
builder.sync();
```

By default, `buildState` automatically syncs the data after your callback, but if you call builder methods after that initial callback, you must manually call `builder.sync()` to reflect those changes in Vulcan.

## Adding Entities

### `builder.addUser(userDetails?)`

Adds a user with smart defaults for all fields.

- **userDetails**: An optional partial user object to override default values. Accepts the following properties:

  - `id` (number | string): Unique identifier for the user. Defaults to an auto-generated ID.
  - `name` (string): Full name of the user. Defaults to `"some person"`.
  - `email` (string): Email address of the user. Defaults to `"person@monday.com"`.
  - `phone` (string): Phone number of the user. Defaults to an empty string.
  - `mobile_phone` (null | string): Mobile phone number. Defaults to `null`.
  - `title` (null | string): Title of the user. Defaults to `null`.
  - `is_admin` (boolean): Indicates if the user is an admin. Defaults to `false`.
  - `is_view_only` (boolean): Indicates if the user has view-only access. Defaults to `false`.
  - `is_pending` (boolean): Indicates if the user's account is pending activation. Defaults to `false`.
  - `is_guest` (boolean): Indicates if the user is a guest. Defaults to `false`.
  - `photo_url` (string): URL for the user's profile picture. Defaults to a placeholder image.
  - `photo_url_150` (string): URL for the user's 150px profile picture. Defaults to a placeholder image.
  - `photo_url_original` (string): URL for the user's original profile picture. Defaults to a placeholder image.
  - `disabled` (boolean): Indicates if the user is disabled. Defaults to `false`.
  - `out_of_office` (null): Indicates if the user is out of office. Defaults to `null`.

- **Defaults**:
  All parameters have default values, making it easy to quickly create mock users without specifying every field.

- **Returns**: The root builder for chaining further calls.

#### **Example Usage**

```ts
import { buildState } from '@mondaydotcomorg/vulcan-client/testkit';

// Create a user with default values
buildState(b => b.addUser());

// Create a user with custom values
buildState(b =>
  b.addUser({
    name: 'Alice',
    email: 'alice@example.com',
    is_admin: true,
    photo_url: 'https://example.com/alice-photo.png',
  })
);
```

### `builder.addBoard(boardDetails?)`

Adds a board with smart defaults for all fields.

- **boardDetails**: An optional partial object to override default board values. Accepts the following properties:

  - `id` (number): Unique identifier for the board. Defaults to an auto-generated ID.
  - `name` (string): Name of the board. Defaults to `"Start from scratch"`.
  - `deleted` (boolean): Indicates if the board is deleted. Defaults to `false`.
  - `archived` (boolean): Indicates if the board is archived. Defaults to `false`.
  - `board_folder_id` (number): ID of the folder containing the board. Defaults to `null`.
  - `folderId` (number): Alias for `board_folder_id`.
  - `created_by` (string | number): User ID of the creator. Defaults to the current user.
  - `createdByUserId` (string | number | null): Alias for `created_by`.
  - `board_kind` (string): Type of board. Defaults to `'public'`.
  - `boardKind` (string): Alias for `board_kind`.
  - `workspace_id` (number): ID of the workspace containing the board. Defaults to the default workspace ID.
  - `workspaceId` (number): Alias for `workspace_id`.
  - `parentBoardId` (number): ID of the parent board, if applicable. Defaults to `null`.
  - `userPermissions` (number): User permissions associated with the board. Defaults to `null`.
  - `system_entity` (object): Indicates if the board is a system entity. Defaults to:
    - `is_system_entity` (boolean): Whether this is a system board. Defaults to `false`.
    - `is_deletable` (boolean): Whether this board is deletable. Defaults to `true`.

- **Defaults**:
  All parameters have default values, making it easy to quickly create mock boards without specifying every field.

- **Returns**: The root builder for chaining further calls.

#### **Example Usage**

```ts
import { buildState } from '@mondaydotcomorg/vulcan-client/testkit';

// Create a board with default values
buildState(b => b.addBoard());

// Create a board with custom values
buildState(b =>
  b.addBoard({
    name: 'Project Management Board',
    board_kind: 'private',
    folderId: 123,
    workspaceId: 456,
    archived: true,
  })
);
```

### `builder.addFolder(folderDetails?)`

Adds a folder with smart defaults for all fields.

#### **Parameters**

- **folderDetails** (optional): A partial object to override default folder values. Accepts the following properties:

  - `id` (number | string): Unique identifier for the folder. Defaults to an auto-generated ID.
  - `name` (string): Name of the folder. Defaults to `'Folder'`.
  - `owner_id` (number | string): User ID of the folder's owner. Defaults to `null`.
  - `workspace_id` (number): ID of the workspace containing the folder. Defaults to `-1`.
  - `folder_kind` (`'public' | 'private'`): Specifies whether the folder is public or private. Defaults to `'public'`.
  - `is_collapse` (boolean): Indicates whether the folder is collapsed. Defaults to `false`.
  - `parent_folder_id` (number | string): ID of the parent folder if the folder is nested. Defaults to `null`.
  - `deleted` (boolean): Specifies whether the folder is marked as deleted. Defaults to `false`.

#### **Example Usage**

```ts
import { buildState } from '@mondaydotcomorg/vulcan-client/testkit';

// Create a folder with default values
buildState(b => b.addFolder());

// Create a folder with custom values
buildState(b =>
  b.addFolder({
    name: 'Design Files',
    workspace_id: 123,
    parent_folder_id: 456,
    owner_id: 789,
  })
);
```

---

## Workspace builder methods

### `builder.addWorkspace(workspaceDetails?)`

Adds a workspace with smart defaults for all fields.

- **workspaceDetails**: An optional partial object to override default workspace values. Accepts the following properties:

  - `id` (number): Unique identifier for the workspace. Defaults to an auto-generated ID.
  - `name` (string): Name of the workspace. Defaults to `"Workspace"`.
  - `kind` (WorkspaceKind): The type of workspace. Defaults to `WorkspaceKind.PUBLIC`. Possible values:
    - `WorkspaceKind.PUBLIC`: Public workspace (default).
    - `WorkspaceKind.CLOSED`: Closed workspace.
    - `WorkspaceKind.HIDDEN`: Hidden workspace.
    - `WorkspaceKind.TEMPLATE`: Template workspace.
  - `is_default_workspace` (boolean): Indicates if this is the default workspace. Defaults to `false`.

- **Defaults**:
  All parameters have default values, making it easy to create mock workspaces without specifying every field.

- **Returns**: The root builder for chaining further calls.

#### **Example Usage**

```ts
import { buildState } from '@mondaydotcomorg/vulcan-client/testkit';
import { WorkspaceKind } from '@mondaydotcomorg/vulcan-client';

// Create a workspace with default values
buildState(b => b.addWorkspace());

// Create a workspace with custom values
buildState(b =>
  b.addWorkspace({
    name: 'Engineering Workspace',
    kind: WorkspaceKind.CLOSED,
    is_default_workspace: true,
  })
);
```

### `builder.addTeam(teamDetails?)`

Creates a new team and adds it to the mock state.

- **teamDetails**: Partial team data that overrides default values. Example fields include:
  - `name`: The name of the team (default: "team").
  - `direct_sub_team_ids`: Array of IDs of direct sub-teams.
  - `direct_user_ids`: Array of IDs of users in the team.
  - `direct_owner_ids`: Array of IDs of team owners.
  - `team_subscriptions_count`: Number of subscriptions for the team.
  - `picture_url`: URL of the team's picture.
  - `is_guest`: Boolean indicating whether the team is a guest team.
  - `is_deleted`: Boolean indicating whether the team is deleted.
  - `disabled`: Boolean indicating whether the team is disabled.
  - `photo_url`: URL for the team's photo.
  - `team_active_non_pending_subscriber_ids`: Array of IDs of active, non-pending subscribers.
  - `url`: URL of the team.
  - `data`: Arbitrary data attached to the team.
- **Returns** the builder.

**Example Usage:**

```ts
const { builder } = buildState(b =>
  b.addTeam({
    name: 'Engineering Team',
    direct_user_ids: [101, 102],
    is_guest: false,
  })
);
```

---

## Current Account/User Builder Methods

### `builder.setAccount(accountDetails?)`

Sets the current account.

- **accountDetails**: partial account data, like `{ name: 'My Account' }`.
  - Possible fields: `name`, `slug`, `max_users`, `tier`, etc.
- **Returns** the root builder.

**Example:**

```ts
buildState(b => b.setAccount({ name: 'Acme Co.' }));
```

### `builder.withMyAccount(fn: (accountBuilder) => void)`

A convenience method to directly operate on the account builder.

**Example:**

```ts
builder.withMyAccount(account => account.set({ tier: 'premium' }));
```

### `builder.setMyUser(userDetails?)`

Sets the current user.

- **userDetails**: An optional partial user object to override default values. Accepts the following properties:

  - `id` (number | string): Unique identifier for the user. Defaults to an auto-generated ID.
  - `name` (string): Full name of the user. Defaults to `"some person"`.
  - `email` (string): Email address of the user. Defaults to `"person@monday.com"`.
  - `phone` (string): Phone number of the user. Defaults to an empty string.
  - `mobile_phone` (null | string): Mobile phone number. Defaults to `null`.
  - `title` (null | string): Title of the user. Defaults to `null`.
  - `is_admin` (boolean): Indicates if the user is an admin. Defaults to `false`.
  - `is_view_only` (boolean): Indicates if the user has view-only access. Defaults to `false`.
  - `is_pending` (boolean): Indicates if the user's account is pending activation. Defaults to `false`.
  - `is_guest` (boolean): Indicates if the user is a guest. Defaults to `false`.
  - `photo_url` (string): URL for the user's profile picture. Defaults to a placeholder image.
  - `photo_url_150` (string): URL for the user's 150px profile picture. Defaults to a placeholder image.
  - `photo_url_original` (string): URL for the user's original profile picture. Defaults to a placeholder image.
  - `disabled` (boolean): Indicates if the user is disabled. Defaults to `false`.
  - `out_of_office` (null): Indicates if the user is out of office. Defaults to `null`.

- **Defaults**:
  All parameters have default values, making it easy to quickly create mock users without specifying every field.

- **Returns**: The root builder for chaining further calls.

---

## Board Builder Methods

These are chainable methods that become available once you have a `MockStateBuilderBoard` (e.g. after calling `addBoard`).

### Column Builder Methods

The following methods add different types of columns to a board. Each method returns a `MockStateBuilderColumn` that can be used for further chaining.

#### Common Column Parameters

All column types share these common parameters in their `columnDetails` object:

- `id` (string): Unique identifier for the column. Defaults to an auto-generated ID.
- `title` (string): Title of the column. Each column type has its own default title.
- `width` (number): Width of the column in pixels. Defaults to 200.
- `settings` (object): Additional column settings specific to each column type.

#### `.addNameColumn(columnDetails?)`

Adds a name column to the board. This is typically the first column in a board and is required for all boards.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to name columns:
    - `allow_duplicate_names` (boolean): Whether to allow duplicate item names. Defaults to false.
    - `show_subitems` (boolean): Whether to show subitems in the name column. Defaults to true.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addNameColumn({
      title: 'Task Name',
      width: 250,
      settings: {
        allow_duplicate_names: true,
        show_subitems: true,
      },
    })
  )
);
```

#### `.addPersonColumn(columnDetails?)`

Adds a person column to the board for assigning users.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to person columns:
    - `multiple_persons` (boolean): Whether to allow multiple person selections. Defaults to false.
    - `show_avatars` (boolean): Whether to show user avatars. Defaults to true.
    - `show_titles` (boolean): Whether to show user titles. Defaults to true.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addPersonColumn({
      title: 'Assignee',
      width: 180,
      settings: {
        multiple_persons: true,
        show_avatars: true,
        show_titles: true,
      },
    })
  )
);
```

#### `.addStatusColumn(columnDetails?)`

Adds a status column to the board for tracking progress.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to status columns:
    - `labels` (object): Custom status labels. Defaults to:
      ```ts
      {
        0: 'Working on it',
        1: 'Done',
        2: 'Stuck',
        7: '',
        12: '',
        14: '',
      }
      ```
    - `labelsPositionsV2` (object): Custom label positions. Defaults to:
      ```ts
      {
        0: 0,
        1: 2,
        2: 1,
        5: 6,
        7: 3,
        12: 4,
        14: 5,
      }
      ```
    - `colors` (object): Custom colors for each status. Defaults to standard status colors.
    - `hide_footer` (boolean): Whether to hide the footer. Defaults to false.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addStatusColumn({
      title: 'Progress',
      settings: {
        labels: {
          0: 'Not Started',
          1: 'In Progress',
          2: 'Completed',
        },
        colors: {
          0: '#ff5c5c',
          1: '#ffcb00',
          2: '#00ca72',
        },
        hide_footer: false,
      },
    })
  )
);
```

#### `.addTextColumn(columnDetails?)`

Adds a text column to the board for free-form text input.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to text columns:
    - `rich_text` (boolean): Whether to enable rich text formatting. Defaults to false.
    - `wrap_text` (boolean): Whether to wrap long text. Defaults to true.
    - `max_length` (number): Maximum character length. Defaults to null (unlimited).
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addTextColumn({
      title: 'Description',
      width: 300,
      settings: {
        rich_text: true,
        wrap_text: true,
        max_length: 1000,
      },
    })
  )
);
```

#### `.addNumberColumn(columnDetails?)`

Adds a number column to the board for numeric values.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to number columns:
    - `format` (string): Number format. Defaults to 'number'.
    - `currency` (string): Currency code for currency format. Defaults to 'USD'.
    - `decimal_places` (number): Number of decimal places to show. Defaults to 0.
    - `min_value` (number): Minimum allowed value. Defaults to null.
    - `max_value` (number): Maximum allowed value. Defaults to null.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addNumberColumn({
      title: 'Points',
      width: 100,
      settings: {
        format: 'number',
        decimal_places: 1,
        min_value: 0,
        max_value: 100,
      },
    })
  )
);
```

#### `.addDateColumn(columnDetails?)`

Adds a date column to the board for date values.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to date columns:
    - `format` (string): Date format ('DD/MM/YYYY', 'MM/DD/YYYY', 'YYYY-MM-DD'). Defaults to 'DD/MM/YYYY'.
    - `include_time` (boolean): Whether to include time selection. Defaults to false.
    - `time_format` (string): Time format ('12h', '24h'). Defaults to '12h'.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addDateColumn({
      title: 'Due Date',
      width: 150,
      settings: {
        format: 'YYYY-MM-DD',
        include_time: true,
        time_format: '24h',
      },
    })
  )
);
```

#### `.addTimelineColumn(columnDetails?)`

Adds a timeline column to the board for date ranges.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to timeline columns:
    - `start_date_format` (string): Format for start date. Defaults to 'DD/MM/YYYY'.
    - `end_date_format` (string): Format for end date. Defaults to 'DD/MM/YYYY'.
    - `include_time` (boolean): Whether to include time selection. Defaults to false.
    - `time_format` (string): Time format Defaults to '12h'.
    - `show_duration` (boolean): Whether to show duration between dates. Defaults to true.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addTimelineColumn({
      title: 'Project Timeline',
      width: 300,
      settings: {
        start_date_format: 'YYYY-MM-DD',
        end_date_format: 'YYYY-MM-DD',
        include_time: true,
        time_format: '24h',
        show_duration: true,
      },
    })
  )
);
```

#### `.addFormulaColumn(formula, columnDetails?)`

Adds a formula column to the board for calculated values.

- **formula** (string): The formula to use for calculations. Supports various functions and column references.
- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to formula columns:
    - `format` (string): Output format ('number', 'currency', 'percent', 'date'). Defaults to 'number'.
    - `decimal_places` (number): Number of decimal places to show. Defaults to 2.
    - `currency` (string): Currency code for currency format. Defaults to 'USD'.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addFormulaColumn('SUM({Points})', {
      title: 'Total Points',
      settings: {
        format: 'number',
        decimal_places: 1,
      },
    })
  )
);
```

#### `.addPhoneColumn(columnDetails?)`

Adds a phone column to the board for phone numbers.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to phone columns:
    - `format` (string): Phone number format. Defaults to 'international'.
    - `allow_multiple` (boolean): Whether to allow multiple phone numbers. Defaults to false.
    - `validation` (string): Validation rules. Defaults to 'strict'.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addPhoneColumn({
      title: 'Contact Number',
      width: 150,
      settings: {
        format: 'international',
        allow_multiple: false,
        validation: 'strict',
      },
    })
  )
);
```

#### `.addDropdownColumn(columnDetails?)`

Adds a dropdown column to the board for selecting from predefined options.

- **columnDetails**: Optional configuration object with the following properties:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to dropdown columns:
    - `labels` (array): Array of dropdown options. Defaults to:
      ```ts
      [
        { id: 1, name: 'First Value' },
        { id: 2, name: 'Second Value' },
        { id: 3, name: 'Third Value' },
      ];
      ```
    - `hide_footer` (boolean): Whether to hide the footer. Defaults to false.
    - `allow_multiple` (boolean): Whether to allow multiple selections. Defaults to false.
    - `colors` (object): Custom colors for each option. Defaults to standard colors.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addDropdownColumn({
      title: 'Priority',
      settings: {
        labels: [
          { id: 1, name: 'Low' },
          { id: 2, name: 'Medium' },
          { id: 3, name: 'High' },
        ],
        colors: {
          1: '#00ca72',
          2: '#ffcb00',
          3: '#ff5c5c',
        },
        allow_multiple: false,
        hide_footer: false,
      },
    })
  )
);
```

#### `.addLinkedBoards(title, boardIds, columnDetails?)`

Adds a linked boards column to connect items across multiple boards.

- **title** (string): Title of the column.
- **boardIds** (number[]): Array of board IDs to link to.
- **columnDetails**: Optional configuration object with additional settings:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to linked boards columns:
    - `show_subitems` (boolean): Whether to show subitems in linked boards. Defaults to true.
    - `allow_multiple` (boolean): Whether to allow multiple item links. Defaults to true.
    - `display_limit` (number): Maximum number of items to display. Defaults to 5.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addLinkedBoards('Related Tasks', [123, 456], {
      width: 250,
      settings: {
        show_subitems: true,
        allow_multiple: true,
        display_limit: 3,
      },
    })
  )
);
```

#### `.addMirrorColumn(title, connectColumnId, mappedColumns, columnDetails?)`

Adds a mirror column to display data from another column.

- **title** (string): Title of the column.
- **connectColumnId** (string): ID of the column to connect to.
- **mappedColumns** (object): Mapping of columns to display.
- **columnDetails**: Optional configuration object with additional settings:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to mirror columns:
    - `auto_update` (boolean): Whether to automatically update mirrored values. Defaults to true.
    - `show_empty` (boolean): Whether to show empty values. Defaults to false.
    - `display_format` (string): How to display the mirrored values. Defaults to 'default'.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addMirrorColumn(
      'Mirrored Status',
      'status_1',
      { 123: ['status_cool'] },
      {
        settings: {
          auto_update: true,
          show_empty: false,
          display_format: 'default',
        },
      }
    )
  )
);
```

#### `.addSubitemColumn(columnDetails?)`

Adds a subitem column to the board for managing subitems.

- **columnDetails**: Optional configuration object with additional settings:
  - Common parameters (see above)
  - `settings` (object): Additional settings specific to subitem columns:
    - `show_count` (boolean): Whether to show the count of subitems. Defaults to true.
    - `allow_creation` (boolean): Whether to allow creating new subitems. Defaults to true.
    - `allow_deletion` (boolean): Whether to allow deleting subitems. Defaults to true.
- **Returns**: A `MockStateBuilderColumn` for chaining.

**Example:**

```ts
buildState(b =>
  b.addBoard().with(board =>
    board.addSubitemColumn({
      title: 'Subtasks',
      settings: {
        show_count: true,
        allow_creation: true,
        allow_deletion: true,
      },
    })
  )
);
```

### `.addGroup(title, details?)`

Adds a group to the board.

- **title**: string (required).
- **details**: optional group settings.
  - Possible fields: `id`, `color`, `collapsed`, etc.
- **Returns** a **`MockStateBuilderGroup`**.

**Example:**

```ts
buildState(b => b.addBoard({ name: 'Main Board' }).with(board => board.addGroup('Tasks', { color: '#f2d600' })));
```

### `.addSubitemBoard()`

Creates the sub-board (for subitems) behind the scenes, returning a **`MockStateBuilderBoard`** representing that sub-board.

**Example:**

```ts
board.addSubitemBoard().with(subBoard => subBoard.addGroup('Subitems'));
```

### `.addSubset(subsetDetails?: SubsetInput, ref?: string)`

Creates a subset on the current board.

- **subsetDetails**: an object describing the subset (e.g. `{ name: 'Subset X', filters: {}, isDefault: false }`).
- **ref**: optional reference name to store it (`.addAsRef`).
- **Returns** a **`MockStateBuilderSubset`**.

**Example:**

```ts
board.addSubset({ name: 'Subset: Urgent tasks' }, 'urgentSubset');
```

### `.getFirstItemBuilderOfFirstGroupBuilder()`

Returns the first pulse (item) from the first group in the board. This is useful when you need to reference a specific item, especially when working with linked boards.

- **Returns**: A **`MockStateBuilderPulse`** representing the first item in the first group.

**Example:**

```ts
// Get the first item from the first group
const firstItem = board.getFirstItemBuilderOfFirstGroupBuilder();

// Use it with linkItems to create a connection
pulse.linkItems(linkedBoardsColumnId, [firstItem.id()]);
```

### `.getFirstGroupBuilder()`

Returns the first group in the board. This is useful when you need to reference a specific group or access its items.

- **Returns**: A **`MockStateBuilderGroup`** representing the first group in the board.

**Example:**

```ts
// Get the first group
const firstGroup = board.getFirstGroupBuilder();

// Access its items
const firstItem = firstGroup.getFirstItemBuilder();
```

---

## Group Builder Methods

### `.addPulse(name, pulseDetails?)`

Creates a new pulse (item) under the group.

- **name**: string (title of the pulse).
- **pulseDetails**: optional overrides, e.g. `{ isTemp: true, column_values: {...} }`.
- **Returns** a **`MockStateBuilderPulse`**.

**Example:**

```ts
group.addPulse('My First Task');
group.addPulse('Second Task', { isTemp: true });
```

### `.getFirstItemBuilder()`

Returns the first pulse (item) in the group. This is useful when you need to reference a specific item.

- **Returns**: A **`MockStateBuilderPulse`** representing the first item in the group.

**Example:**

```ts
// Get the first item in the group
const firstItem = group.getFirstItemBuilder();

// Access its properties
const itemId = firstItem.id();
```

---

## Pulse Builder Methods

When you add a pulse, you get a `MockStateBuilderPulse`.

- **`.setName(name: string)`**: change the pulse name.
- **`.setColumnValue(columnId: string, value: any)`**: set any column.
- **`.setPersonColumnValue(columnId: string, persons: (number | string)[] | null | undefined)`**: specifically for Person columns.
- **`.setStatusColumnValue(columnId: string, index: number | null | undefined)`**: specifically for Status columns.
- **`.setDropdownColumnValue(columnId: string, ids: number[])`**: for Dropdown columns.
- **`.setNumberColumnValue(columnId: string, value: number)`**: for Number columns.
- **`.addSubitem(name: string, pulseDetails?: BuildPulseInput)`**: Adds a subitem (child pulse in sub-board) to this pulse.
- **`.linkItems(columnId: string, itemIds: number[])`**: Links this pulse to specific items from linked boards. Used with `addLinkedBoards` to create connections between items across different boards.

**Example:**

```ts
group
  .addPulse('Main Task')
  .with(pulse => pulse.setColumnValue('status_1', { index: 1 }).setName('Main Task (edited)').addSubitem('Child Task'));
```

**Example with linked boards:**

```ts
// Create a board with a linked boards column
const { builder } = buildState(b => {
  // First, declare references we'll need later
  return (
    b
      .declareRefs<{
        sourceBoard: any;
        linkedBoardsColumn: any;
      }>()
      // Create the source board with items
      .addBoard({ name: 'Source Board' })
      .with(board =>
        board
          .addNameColumn()
          .addStatusColumn({ title: 'Status' })
          .addGroup('Tasks')
          .with(g =>
            g
              .addPulse('Task 1')
              .with(p => p.setStatusColumnValue('status_1', 0))
              .addPulse('Task 2')
              .with(p => p.setStatusColumnValue('status_1', 1))
          )
          .addAsRef('sourceBoard')
      )
      // Create the linking board
      .addBoard({ name: 'Linking Board' })
      .with((board, context) =>
        board
          .addNameColumn()
          // Add a linked boards column that connects to the source board
          .addLinkedBoards('Connected Tasks', [context.refs.sourceBoard.id()])
          .createdAsRef('linkedBoardsColumn')
          // Add items to the linking board
          .addGroup('Connections')
          .with(g =>
            g.addPulse('Connection 1').with(p =>
              // Link this item to Task 1 from source board
              p.linkItems(context.refs.linkedBoardsColumn.id(), [
                context.refs.sourceBoard.getFirstItemBuilderOfFirstGroupBuilder().id(),
              ])
            )
          )
      )
  );
});
```

---

## Subset Builder Methods

- **`.addOverview()`**: Creates an overview attached to this subset.
  - Returns a **`MockStateBuilderOverview`**.

**Example:**

```ts
board
  .addSubset({ name: 'High-level subset' })
  .with(subset => subset.addOverview().with(overview => overview.setDataLoadStrategy('lazy')));
```

---

## Overview Builder Methods

Inside an overview (dashboard) builder, you can add sections or references to boards.

- **`.addBoardRef(refName: string)`**: Attaches an existing board reference to this overview.
- **`.addBatterySection(title: string, settings?: any, sectionDetails?: any, ref?: string)`**: Example of adding a battery section.
- **`.addChartSection(title: string, settings?: any, sectionDetails?: any, ref?: string)`**: Example of adding a chart section.
- **`.addListViewSection(...)`, `.addTimelineSection(...)`, etc.**
- **Returns** a **`MockStateBuilderSection`**.

**Example:**

```ts
overview.addChartSection('My Chart', {
  graph_type: 'bar',
  board_ids: [123],
});
```

---

## Shared / Utility Methods

### `.declareRefs<T>()`

Declares typed references. Must be used before `.addAsRef` or `.withRef`. This is purely for TypeScript convenience, letting you define what references exist.

```ts
b.declareRefs<{ mainGroup: MockStateBuilderGroup<any, any>; subBoard: MockStateBuilderBoard<any, any> }>();
```

### `.addAsRef(refName: string)`

Assigns the current builder to a reference name.

**Example:**

```ts
b.addBoard({ name: 'board' }).addAsRef('myBoard');
```

### `.withRef(refName, (builder, context) => {})`

Retrieves that reference for further building.

**Example:**

```ts
b.withRef('myBoard', board => board.addGroup('Extra Group'));
```

### `.createdAsRef(refName: string)`

Like `.addAsRef`, but specifically for the item that was just created in the chain.

### `.with(...)`

Passes the newly created entity's builder to a callback, letting you continue building in a nested scope.

```ts
b.addBoard({ name: 'My Board' }).with(board => board.addGroup('Main'));
```

### `.withTimes(times, (builder, index, context) => {})`

Runs the callback multiple times, each time referencing the same `lastCreated`. This is useful for quickly duplicating sub-items.

**Example:**

```ts
group.addPulse('Parent Task').withTimes(3, (pulse, i) => pulse.addSubitem('Child ' + i));
```

### `.times(times, (builder, index, context) => {})`

Runs the callback multiple times but references the **current** builder, not the last created item.

**Example:**

```ts
board.times(2, (theBoard, i) => theBoard.addGroup('Group ' + i));
```

### `.each(array, (builder, element, index, context) => {})`

Iterates over an array, passing each element to the callback.

**Example:**

```ts
const groupNames = ['Alpha', 'Beta', 'Gamma'];
board.each(groupNames, (theBoard, groupName) => theBoard.addGroup(groupName));
```

### `.withThis(callback)`

Lets you operate on the current builder object, rather than the last created.

**Example:**

```ts
board.withThis(bSelf => bSelf.addNumberColumn({ title: 'Points' }));
```

### `.withMainBuilder(fn)`

Allows you to call a function that receives the **root** builder (`MockStateBuilderMain`). Typically used to merge shared or global mocks.

**Example:**

```ts
const addDefaultBoards = mainBuilder =>
  mainBuilder.addBoard({ name: 'Default Board 1' }).addBoard({ name: 'Default Board 2' });

buildState(b => b.withMainBuilder(addDefaultBoards));
```

---

## Summarized Flow

1. **Create** an item (board, group, pulse, subset, overview, folder, etc.).
2. **Chain** more calls if needed.
3. **Reference** them if you want to manipulate them later.
4. **Sync** or rely on auto-sync from `buildState`.
5. **Use** Vulcan as normal (queries, selectors, etc.).

With these methods, you can build complex Vulcan data structures, ensuring your tests or stories have consistent, realistic data.