Merge pull request #180 from x0k/keyed-array-access

Keyed array access

Author: x0k

.changeset/purple-facts-travel.md

@@ -0,0 +1,5 @@
+---
+"@sjsf/form": minor
+---
+
+Add `keyedArraysMap` form option

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>

packages/form/src/fields/array/context.svelte.ts

@@ -1,6 +1,5 @@
 import { getContext, setContext } from "svelte";
 
-import { createKeyedArray } from "@/lib/keyed-array.svelte.js";
 import {
   getDefaultValueForType,
   getSimpleSchemaType,
@@ -14,6 +13,7 @@ import {
 import {
   AFTER_SUBMITTED,
   createChildId,
+  createKeyedArrayDeriver,
   getDefaultFieldState,
   getErrors,
   ON_ARRAY_CHANGE,
@@ -73,6 +73,7 @@ function createItemsAPI<V extends Validator>(
   ctx: FormInternalContext<V>,
   config: () => Config,
   value: () => SchemaArrayValue | undefined,
+  setValue: (v: SchemaArrayValue) => void,
   itemSchema: () => Schema | undefined
 ) {
   function validate() {
@@ -84,7 +85,7 @@ function createItemsAPI<V extends Validator>(
   }
   const uiOption: UiOption = (opt) => retrieveUiOption(ctx, config(), opt);
 
-  const keyedArray = createKeyedArray(() => value() ?? []);
+  const keyedArray = $derived.by(createKeyedArrayDeriver(ctx, value, setValue));
 
   const errors = $derived(getErrors(ctx, config().id));
 
@@ -176,9 +177,7 @@ export function createArrayContext<V extends Validator>(
   ctx: FormInternalContext<V>,
   config: () => Config,
   value: () => SchemaArrayValue | undefined,
-  // NOTE: It looks like the `undefined` value is always replaced by an array
-  // when calculating default values, so this is unnecessary
-  _: (v: SchemaArrayValue) => void
+  setValue: (v: SchemaArrayValue) => void
 ): ArrayContext<V> {
   const itemSchema: Schema = $derived.by(() => {
     const {
@@ -187,7 +186,7 @@ export function createArrayContext<V extends Validator>(
     return isSchemaObjectValue(items) ? items : {};
   });
 
-  const api = createItemsAPI(ctx, config, value, () => itemSchema);
+  const api = createItemsAPI(ctx, config, value, setValue, () => itemSchema);
 
   const itemUiSchema = $derived.by(() => {
     const {
@@ -267,7 +266,13 @@ export function createTupleContext<V extends Validator>(
     return isSchemaObjectValue(additionalItems) ? additionalItems : undefined;
   });
 
-  const api = createItemsAPI(ctx, config, value, () => schemaAdditionalItems);
+  const api = createItemsAPI(
+    ctx,
+    config,
+    value,
+    setValue,
+    () => schemaAdditionalItems
+  );
 
   const canAdd = $derived.by(
     createCanAdd(

packages/form/src/form/context/array.ts

@@ -0,0 +1,76 @@
+import {
+  SimpleKeyedArray,
+  type KeyedArray2,
+} from "@/lib/keyed-array.svelte.js";
+import type { SchemaArrayValue, Validator } from "@/core/index.js";
+
+import type { FieldValue } from "../model.js";
+
+import type { FormInternalContext } from "./context.js";
+
+class VirtualKeyedArray implements KeyedArray2<number, FieldValue> {
+  constructor(protected readonly setValue: (v: SchemaArrayValue) => void) {}
+
+  key(): number {
+    throw new Error(
+      'Method "key" cannot be called on "VirtualKeyedArray" instance'
+    );
+  }
+
+  push(value: FieldValue): void {
+    this.setValue([value]);
+  }
+
+  swap(): void {
+    throw new Error(
+      'Method "swap" cannot be called on "VirtualKeyedArray" instance'
+    );
+  }
+
+  insert(index: number, value: FieldValue): void {
+    if (index !== 0) {
+      throw new Error(
+        `Method "insert" cannot be called on "VirtualKeyedArray" instance with those args (index=${index}), expected (0)`
+      );
+    }
+    this.setValue([value]);
+  }
+
+  remove(): void {
+    throw new Error(
+      'Method "remove" cannot be called on "VirtualKeyedArray" instance'
+    );
+  }
+
+  splice(start: number, count: number, ...items: FieldValue[]): FieldValue[] {
+    if (start !== 0 || count !== 0) {
+      throw new Error(
+        `Method "splice" cannot be called on "VirtualKeyedArray" instance with those args(start=${start}, count=${count}) expected (0, 0)`
+      );
+    }
+    this.setValue(items);
+    return [];
+  }
+}
+
+export function createKeyedArrayDeriver<V extends Validator>(
+  ctx: FormInternalContext<V>,
+  value: () => SchemaArrayValue | undefined,
+  setValue: (v: SchemaArrayValue) => void
+) {
+  let lastKey = Number.MIN_SAFE_INTEGER;
+  return () => {
+    let stored: KeyedArray2<number, FieldValue> | undefined;
+    const v = value();
+    if (v === undefined) {
+      stored = new VirtualKeyedArray(setValue);
+    } else {
+      stored = ctx.keyedArrays.get(v);
+      if (stored === undefined) {
+        stored = new SimpleKeyedArray(v, () => lastKey++);
+        ctx.keyedArrays.set(v, stored);
+      }
+    }
+    return stored;
+  };
+}

packages/form/src/form/context/context.ts

@@ -21,7 +21,7 @@ import type { Icons } from "../icons.js";
 import type { FormMerger } from "../merger.js";
 import type { Theme } from "../components.js";
 import type { Id, IdOptions } from "../id.js";
-import type { FormValue } from "../model.js";
+import type { FormValue, KeyedArraysMap } from "../model.js";
 import type { ResolveFieldType } from "../fields.js";
 
 /** @deprecated don't use this type */
@@ -32,6 +32,7 @@ export interface FormInternalContext<V extends Validator>
     Readonly<Required<IdOptions>> {
   value: FormValue;
   isChanged: boolean;
+  readonly keyedArrays: KeyedArraysMap;
   readonly rootId: Id;
   readonly fieldsValidationMode: number;
   readonly isSubmitted: boolean;

packages/form/src/form/context/index.ts

@@ -6,3 +6,4 @@ export * from "./event-handlers.svelte.js";
 export * from "./attributes.js";
 export * from "./files.js";
 export * from "./components.js";
+export * from "./array.js";

packages/form/src/form/create-form.svelte.ts

@@ -57,7 +57,7 @@ import {
 } from "./id.js";
 import type { Config } from "./config.js";
 import type { Theme } from "./components.js";
-import type { FormValue, ValueRef } from "./model.js";
+import type { FormValue, KeyedArraysMap, ValueRef } from "./model.js";
 import type { ResolveFieldType } from "./fields.js";
 
 export const DEFAULT_FIELDS_VALIDATION_DEBOUNCE_MS = 300;
@@ -231,6 +231,7 @@ export interface FormOptions<T, V extends Validator>
    */
   onReset?: (e: Event) => void;
   schedulerYield?: SchedulerYield;
+  keyedArraysMap?: KeyedArraysMap;
 }
 
 export interface FormState<T, V extends Validator> {
@@ -454,6 +455,10 @@ export function createForm<T, V extends Validator>(
     ...uiSchema["ui:options"],
   });
 
+  const keyedArrays: KeyedArraysMap = $derived(
+    options.keyedArraysMap ?? new WeakMap()
+  );
+
   const context: FormInternalContext<V> = {
     ...({} as FormContext),
     get rootId() {
@@ -473,6 +478,9 @@ export function createForm<T, V extends Validator>(
     get dataUrlToBlob() {
       return dataUrlToBlob;
     },
+    get keyedArrays() {
+      return keyedArrays;
+    },
     get isSubmitted() {
       return isSubmitted;
     },

packages/form/src/form/model.ts

@@ -1,14 +1,18 @@
+import type { KeyedArray2 } from "@/lib/keyed-array.svelte.js";
 import {
   getSchemaDefinitionByPath,
   type Path,
   type Schema,
+  type SchemaArrayValue,
   type SchemaValue,
 } from "@/core/index.js";
 
 export type FieldValue = SchemaValue | undefined;
 
 export type FormValue = SchemaValue | undefined;
 
+export type KeyedArraysMap = WeakMap<SchemaArrayValue, KeyedArray2<number, FieldValue>>;
+
 export interface ValueRef<T> {
   current: T;
 }