[docs] Add info about direct array modification

Author: x0k

apps/docs2/src/content/docs/form/options.mdx

@@ -50,7 +50,7 @@ export interface FormOptions<T, V extends Validator>
   idPseudoSeparator?: string;
   //
   value?: [() => T, (v: T) => void];
-  initialValue?: Partial<T>;
+  initialValue?: InitialValue<T>;
   initialErrors?: InitialErrors<V>;
   /**
    * @default waitPrevious
@@ -143,5 +143,6 @@ export interface FormOptions<T, V extends Validator>
    */
   onReset?: (e: Event) => void;
   schedulerYield?: SchedulerYield;
+  keyedArraysMap?: KeyedArraysMap;
 }
 ```

apps/docs2/src/content/docs/form/state.mdx

@@ -38,4 +38,48 @@ export interface FormState<T, V extends Validator> {
   submit(e: SubmitEvent): void;
   reset(e: Event): void;
 }
-```
+```
+
+## Direct modification of form state
+
+If you are using a [controlled form](../../guides/quickstart/#controlled-form), 
+you should consider the following aspects:
+
+### Initialization
+
+It is recommended to initialize the state as follows:
+
+```ts
+let value = $state(
+  merger.mergeFormDataAndSchemaDefaults(initialValue, schema)
+);
+```
+
+### Arrays
+
+To modify arrays, use one of the following methods:
+
+1. Reassign
+
+```ts
+value.array = value.array.concat(123)
+```
+
+2. Use `KeyedArray` API
+
+```ts
+import { createForm, type KeyedArraysMap } from "@sjsf/form";
+
+const keyedArraysMap: KeyedArraysMap = new WeakMap()
+let value = $state({ array: [] })
+const form = createForm({
+  keyedArraysMap,
+  value: [() => value, (v) => (value = v)],
+  // ...otherOptions
+})
+
+const api = keyedArraysMap.get(value.array)
+if (api) {
+  api.push(123)
+}
+```

apps/docs2/src/content/docs/guides/quickstart.mdx

@@ -105,6 +105,12 @@ so here is a list of situations in which this approach can be used
 
 :::
 
+:::caution
+
+Before using, please read the section - [Direct modification of form state](../../form/state/#direct-modification-of-form-state)
+
+:::
+
 <Code code={controlledFormCode} lang="svelte" />
 
 <FormCard>