# Collaboration Policy

## Content

This manual describes the behavior and usage policies in SpreadJS Collaboration. These mechanisms control how real-time synchronization works between multiple clients in a shared workbook environment.

### Purpose

* Ensure developers understand when and how changes are synchronized across clients.
* Define the correct way to modify styles, print settings, or other nested objects.
* Explain the rules governing formula calculation, synchronization, and behavior during iteration.

## Feature Description

### 1\. Nested Object Modification Synchronization

#### Core Concept

* **Direct local modifications to nested objects are not synchronized** across clients.
* To synchronize updates, the entire object must be **reset or reassigned** via a setter method.

#### Example Cases

| Scenario | Local Effect | Synchronization Behavior | Recommended Action |
| -------- | ------------ | ------------------------ | ------------------ |
| Modify properties of an object returned by `getStyle(row, column)` | Local style updates are visible only on that client | Changes are **not** broadcast to other clients | Use `setStyle(row, column, style)` to replace the entire object |
| Modify nested properties of `printInfo` (e.g., `printInfo.pageHeaderFooter.left()`) | Affects only local view | Not synchronized | Reassign print settings using full setter (e.g., `sheet.printInfo = new PrintInfo()`) |

#### Synchronization Strategy

To trigger proper synchronization:

1. Retrieve the object you want to modify.
2. Update it locally.
3. Call a **setter** to reapply the entire updated object to the worksheet or workbook.

**Example:**

```auto
// Incorrect – Not synchronized
let s = sheet.getStyle(1, 1);
s.backColor = "yellow"; // local only
// Correct – Synchronized
let style = sheet.getStyle(1, 1);
style.backColor = "yellow";
sheet.setStyle(1, 1, style); // triggers collaboration synchronization
```

***

### 2\. Formula Collaboration Behavior

Formulas behave differently under collaboration. Each client independently performs calculation and maintains its own local state based on shared formula definitions.

#### Snapshot Storage

* Only the **formula expressions** are stored in snapshots.
* **Formula results** are never stored or synchronized between clients.

#### Formula Recalculation

* When a workbook loads, each client independently recalculates formulas.
* The recalculation result may temporarily differ due to execution order or iterative calculation variations.

#### Synchronization Scope

* The collaboration service synchronizes formula editing actions (insertions, deletions, edits).
* Calculation results (numerical outputs) are not transmitted or synchronized.

#### CalculationMode Policy

* Each client maintains its own `CalculationMode` (Manual or Automatic).
* Changes to one client’s calculation mode do **not** affect other clients or the server.

Follow these principles:

1. Write formulas as usual (e.g., `=A1 + B1`).
2. Avoid relying on stored results—each client recalculates independently.
3. Be careful when using iterative or volatile functions (`RAND`, `NOW`, etc.), as their outcomes may differ across clients.

#### Iterative Calculation Behavior

| Category | Description | Formula Example | Synchronization Behavior |
| -------- | ----------- | --------------- | ------------------------ |
| **Self-Converging** | Iterates until a stable result is reached (identical on all clients) | Interdependent department cost allocation | Consistent across clients and refreshes |
| **Non-Converging** | Iterates infinitely or non-stably | `=A1 + 1` | Differ by client; resets after refresh |
| **Auto-Data-Entry (One-Time)** | Performs one-time iteration (e.g., timestamp) | `=IF(A1="","", IF(B1="", NOW(), B1))` | Independent timestamp per client; resets after refresh |

***

### 3\. Workbook Collaboration State

If the user registers a change set listener through **[workbook.collaboration.onChangeSet](/spreadjs/api/classes/GC.Spread.Sheets.Collaboration.Collaboration#onchangeset)**, SpreadJS will be considered to be in collaboration state.
When SpreadJS is in collaboration mode, some APIs become invalid (take no effect) due to the data synchronization mechanism of collaboration.

| `API Location` | `API Name` |
| ------------ | -------- |
| `Workbook` | `fromJSON` |
| `Workbook` | `import` |
| `Workbook` | `open` |
| `Worksheet` | `reset` |