@blueprint-ts/core 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## v3.0.0 - 2026-02-19
+
+# [3.0.0](/compare/v2.0.0...v3.0.0) (2026-02-19)
+
+
+### Features
+
+* Omit BaseForm fields when transformer returns undefined 26c0d0e
+* Removed suggestions feature from BaseForm.ts f21d6ce
+* Support file uploads in BaseForm and improve form data handling in requests d765cae
 ## v2.0.0 - 2026-02-18
 
 # [2.0.0](/compare/v1.2.0...v2.0.0) (2026-02-18)

package/docs/vue/forms.md

@@ -6,11 +6,12 @@
 applications. It provides a comprehensive solution for managing form data with features like:
 
 - Type-safe form state management
-- Dirty state tracking for individual fields
+- Dirty + touched state tracking for fields
 - Error handling and field validation
 - Form persistence between page reloads
 - Support for complex nested objects and arrays
 - Automatic transformation of form values to API payloads
+- Supports `File`/`Blob` fields for multipart requests (see “Files / Uploads”)
 
 ## Key Features
 
@@ -33,19 +34,85 @@ Forms can automatically save their state to browser storage (session, local, etc
 return without losing their input.
 
 ````typescript
-protected override getPersistenceDriver(): PersistenceDriver
-{
-    return new SessionStorageDriver() // Or LocalStorageDriver, etc.
+protected override getPersistenceDriver(suffix?: string): PersistenceDriver {
+  return new SessionStorageDriver(suffix) // Or LocalStorageDriver(suffix), etc.
 }
 ````
 
+Notes:
+- Persistence is enabled by default. Disable it via `super(defaults, { persist: false })`.
+- `persistSuffix` is passed into `getPersistenceDriver(suffix)` and is typically used to namespace the storage key.
+- Persisted state is only reused if the stored `original` matches your current `defaults`; otherwise it is discarded.
+- `persist: false` disables the automatic rehydration + background persistence, but some explicit mutation helpers (e.g. `fillState()`, `reset()`, `addToArrayProperty()`) still call the driver.
+- `File`/`Blob` values are not JSON-serializable, so persistence is not supported for file inputs. Use `{ persist: false }` for file upload forms.
+
 ### 3. Transformations and Getters
 
-Transform form values before they are sent to the server using getter methods:
+`buildPayload()` supports three “getter” patterns to transform values before sending them to your API.
+
+Special value types:
+- `Date` values are treated as scalars and preserved (not “object-walked”). When sent as JSON they serialize to ISO strings via `JSON.stringify()`, and when sent as multipart `FormData` they are appended as `toISOString()`.
+- `File`/`Blob` values are also treated as scalars and preserved for multipart uploads.
+
+#### A) Field Getter (common)
+If your form `state` contains a field, you can define a getter for that same field name. During `buildPayload()`,
+`BaseForm` will call it with the field’s current value and use the return value in the payload.
+
+Getter name format: `get${upperFirst(camelCase(fieldName))}(value)`
+
+Omitting fields:
+- If a field getter returns `undefined`, the field is **not added** to the payload object.
+- Other values (`null`, `false`, `0`, `''`, empty arrays/objects) are included as-is.
+
+Examples:
+
+````typescript
+// state.name -> payload.name (trimmed)
+protected getName(value: string): string {
+  return value.trim()
+}
+````
+
+This works for arrays too (plain arrays and `PropertyAwareArray`):
+
+````typescript
+// state.positions -> payload.positions (mapped)
+protected getPositions(positions: PositionItem[]): Array<{ id: number }> {
+  return positions.map((p) => ({ id: p.id }))
+}
+````
+
+#### B) Composite Getter for Nested Props (automatic fallback)
+If you do *not* provide a field getter for a given top-level field, `BaseForm` will recursively walk objects/arrays and
+allow transforming nested properties via composite getter names.
+
+Composite getter format: `get${upperFirst(parentFieldKey)}${upperFirst(camelCase(propName))}(value)`
+
+Example (field key `businessAssociate`, prop `id`):
 
 ````typescript
+// state.businessAssociate.id -> payload.businessAssociate.id (replaced with the resource id)
+protected getBusinessAssociateId(value: BusinessAssociateResource | null): string | null {
+  return value?.id ?? null
+}
+````
+
+Notes:
+- This applies to arrays of objects too, because arrays are mapped recursively.
+- The “parent field” part uses the original field key with only the first character uppercased (not camel-cased).
+- Returning `undefined` from a composite getter omits that nested property from the payload object.
+
+#### C) Appended / Computed Payload Fields (advanced)
+If you need payload fields that do not exist in `state`, add their names to `append`. `buildPayload()` will then call a
+zero-argument getter for each appended field.
+
+Example (append key `started_at` → getter `getStartedAt()`):
+
+````typescript
+protected override append: string[] = ['started_at']
+
 protected getStartedAt(): string {
-    return DateTime.fromFormat(`${this.state.start_date} ${this.state.start_time}`, 'dd.MM.yyyy HH:mm').toISO()
+  return DateTime.fromFormat(`${this.state.start_date} ${this.state.start_time}`, 'dd.MM.yyyy HH:mm').toISO()
 }
 ````
 
@@ -60,6 +127,16 @@ protected override errorMap: { [serverKey: string]: string | string[] } = {
 }
 ````
 
+Validation is configured by overriding `defineRules()` and returning per-field rules and an optional validation mode:
+
+- `ValidationMode.DEFAULT` (default): validates on dirty, touch, and submit
+- `ValidationMode.PASSIVE`: only validates on submit
+- `ValidationMode.AGGRESSIVE`: validates immediately and on all triggers
+- `ValidationMode.ON_DEPENDENT_CHANGE`: revalidates when a dependency changes (see below)
+
+Rules can declare dependencies via `rule.dependsOn = ['otherField']`. Some rules (e.g. `ConfirmedRule`) implement
+bidirectional dependencies, so changing either field revalidates the other.
+
 ### 5. Array Management
 
 Special support for arrays with the class `PropertyAwareArray`, enabling reactive updates to array items:
@@ -85,6 +162,18 @@ fields that have been changed.
 ````typescript
 // Check if any field in the form has been modified
 form.isDirty()
+
+// Check if a specific field has been modified
+form.isDirty('email')
+````
+
+### Touched Tracking
+
+Touched indicates user interaction (or programmatic updates via setters/fill methods).
+
+````typescript
+form.touch('email')
+form.isTouched('email')
 ````
 
 ### The Properties Object
@@ -100,6 +189,11 @@ The `properties` getter provides access to each form field with its model, error
 </template>
 ````
 
+`properties.<field>` exposes:
+- `model` (a `ComputedRef` compatible with `v-model`)
+- `errors` (array; empty until validated/filled)
+- `dirty` and `touched`
+
 ### Form Submission
 
 Build a payload for API submission with:
@@ -108,12 +202,21 @@ Build a payload for API submission with:
 const payload = form.buildPayload()
 ````
 
+For validation on submit, call:
+
+````typescript
+const ok = form.validate(true)
+if (!ok) return
+await api.submitForm(form.buildPayload())
+````
+
 ## How to Use
 
 ### 1. Create a Form Class
 
 ````typescript
 import { BaseForm, type PersistenceDriver, SessionStorageDriver } from '@hank-it/ui/vue/forms'
+import { RequiredRule, ValidationMode } from '@hank-it/ui/vue/forms/validation'
 
 interface MyFormState {
     name: string
@@ -144,8 +247,18 @@ class MyForm extends BaseForm<MyRequestPayload, MyFormState> {
     }
 
     // Use session storage for persistence
-    protected override getPersistenceDriver(): PersistenceDriver {
-        return new SessionStorageDriver()
+    protected override getPersistenceDriver(suffix?: string): PersistenceDriver {
+        return new SessionStorageDriver(suffix)
+    }
+
+    protected override defineRules() {
+      return {
+        name: { rules: [new RequiredRule<MyFormState>('Name is required')] },
+        email: {
+          rules: [new RequiredRule<MyFormState>('Email is required')],
+          options: { mode: ValidationMode.DEFAULT }
+        }
+      }
     }
 
     // Generate a timestamp for the request
@@ -184,12 +297,10 @@ class MyForm extends BaseForm<MyRequestPayload, MyFormState> {
 <script setup>
 import { MyForm } from './MyForm'
 
-const form = new MyForm({
-  name: '',
-  email: ''
-})
+const form = new MyForm()
 
 async function submitForm() {
+  if (!form.validate(true)) return
   try {
     const payload = form.buildPayload()
     await api.submitForm(payload)
@@ -234,19 +345,8 @@ export class MyComplexForm extends BaseForm<RequestType, FormWithPositions> {
   
   // Remove a position by id
   public removePosition(id: number): void {
-    this.state.positions = new PropertyAwareArray(
-      this.state.positions.filter(position => position.id !== id)
-    )
-    this.resetPositionIds()
-  }
-  
-  // Reset the sequential IDs after removing items
-  protected resetPositionIds(): void {
-    let count = 1
-    this.state.positions.forEach(position => {
-      position.id = count
-      count++
-    })
+    this.removeArrayItem('positions', (position) => position.id !== id)
+    this.resetArrayCounter('positions', 'id')
   }
 }
 
@@ -273,10 +373,13 @@ try {
 }
 ````
 
-The `fileErrors` method currently only supports the Laravel style dot notation errors.
+`fillErrors` supports:
+- direct field keys (e.g. `email`)
+- array dot notation where the 2nd segment is a numeric index (e.g. `positions.0.value`)
+- remapping via `errorMap` (including mapping one server key to multiple fields)
 
 ### 3. Filling Form State
-Update multiple form fields at once, preserving the dirty state:
+Update multiple form fields at once and recompute dirty/touched accordingly:
 
 ````typescript
 form.fillState({
@@ -292,9 +395,50 @@ Update both the current and original state, keeping the field "clean":
 form.syncValue('email', 'new@example.com')
 ````
 
+### 5. Converting `properties` Back To Data
+If you ever need a plain object from the `properties` tree (e.g. for debugging or integrating with non-`BaseForm` code),
+use `propertyAwareToRaw`:
+
+````typescript
+import { propertyAwareToRaw } from '@hank-it/ui/vue/forms'
+
+const raw = propertyAwareToRaw<MyFormState>(form.properties)
+````
+
+### 6. Checking For Errors
+
+````typescript
+form.hasErrors()
+````
+
+## Files / Uploads (Multipart)
+If your form includes a file, keep it in state as `File | null` and disable persistence:
+
+````typescript
+interface UploadFormBody {
+  name: string
+  file: File | null
+}
+
+class UploadForm extends BaseForm<RequestBody, UploadFormBody> {
+  constructor() {
+    super({ name: '', file: null }, { persist: false })
+  }
+}
+````
+
+`buildPayload()` keeps `File`/`Blob` values intact, so you can send the payload using a multipart `FormData` request body
+(e.g. the request layer’s `FormDataFactory` / `FormDataBody`).
+
+If `file` is `null`, `FormDataBody` encodes it as an empty string (the key stays present). Many backends (e.g. Laravel with
+`ConvertEmptyStringsToNull`) will treat that as `null` again.
+
 ## Real-World Examples
 ### 1. Date/Time Handling
 
+This example shows the “appended/computed fields” pattern: `started_at` and `ended_at` are not part of the form state,
+so they are listed in `append`, and `buildPayload()` calls `getStartedAt()` / `getEndedAt()` (no arguments).
+
 ````typescript
 export class TimeTrackingEntryCreateUpdateForm extends BaseForm<RequestPayload, FormState> {
   protected override append: string[] = ['started_at', 'ended_at']
@@ -312,6 +456,13 @@ export class TimeTrackingEntryCreateUpdateForm extends BaseForm<RequestPayload,
 
 ### 2. Complex Object Handling
 
+If your form state contains nested objects, `buildPayload()` can transform individual nested properties via
+composite getter names of the form `get<ParentField><NestedProp>()`, where:
+- `ParentField` is based on the form field key (first character uppercased, not camel-cased)
+- `NestedProp` is `upperFirst(camelCase(prop))`
+
+Example (field key `businessAssociate`, prop `id`): `getBusinessAssociateId(...)`.
+
 ````typescript
 export class IncomingVoucherCreateUpdateForm extends BaseForm<RequestPayload, FormState> {
   // Extract IDs from related objects
@@ -323,4 +474,4 @@ export class IncomingVoucherCreateUpdateForm extends BaseForm<RequestPayload, Fo
     return value?.id
   }
 }
-````
+````

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/service/requests/bodies/FormDataBody.ts

@@ -22,17 +22,53 @@ export class FormDataBody<RequestBody> implements BodyContract {
       if (Object.prototype.hasOwnProperty.call(data, property)) {
         const formKey = namespace ? namespace + '[' + property + ']' : property
 
-        // if the property is an object, but not a File, use recursivity.
-        if (data[property] instanceof Date) {
-          form.append(formKey, data[property].toISOString())
-        } else if (isObject(data[property]) && !(data[property] instanceof File)) {
-          // @ts-expect-error Problem with property of object
-          this.toFormData(data[property], form, formKey)
-        } else if (data[property] instanceof File || typeof data[property] === 'string') {
-          form.append(formKey, data[property])
-        } else {
+        const value = (data as any)[property]
+
+        // Null is a valid "explicitly empty" value in many APIs.
+        // In multipart FormData we encode it as an empty string so the key is still present.
+        if (value === null) {
+          form.append(formKey, '')
+          continue
+        }
+
+        // Undefined values should not reach the request layer (BaseForm omits them).
+        // Reject explicitly to avoid silently dropping keys.
+        if (value === undefined) {
           throw new Error('Unexpected value')
         }
+
+        if (value instanceof Date) {
+          form.append(formKey, value.toISOString())
+          continue
+        }
+
+        // Support arrays via bracket notation: key[0], key[1], ...
+        if (Array.isArray(value)) {
+          for (let i = 0; i < value.length; i++) {
+            this.toFormData({ [String(i)]: value[i] } as any, form, formKey)
+          }
+          continue
+        }
+
+        // Files/Blobs should be appended directly (File extends Blob)
+        if (typeof Blob !== 'undefined' && value instanceof Blob) {
+          form.append(formKey, value)
+          continue
+        }
+
+        // if the property is an object, use recursivity.
+        if (isObject(value)) {
+          this.toFormData(value as any, form, formKey)
+          continue
+        }
+
+        // Primitives: append as strings
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+          form.append(formKey, String(value))
+          continue
+        }
+
+        throw new Error('Unexpected value')
       }
     }
 

package/src/vue/forms/BaseForm.ts

@@ -115,7 +115,6 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
   private readonly original: FormBody
   private readonly _model: { [K in keyof FormBody]: ComputedRef<FormBody[K]> }
   private _errors: any = reactive({})
-  private _suggestions: any = reactive({})
   private _hasErrors: ComputedRef<boolean>
   protected append: string[] = []
   protected ignore: string[] = []
@@ -673,15 +672,13 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
     }
   }
 
-  public fillSuggestions(suggestionsData: Partial<Record<keyof FormBody, string[] | object[]>>): void {
-    for (const key in suggestionsData) {
-      if (Object.prototype.hasOwnProperty.call(suggestionsData, key)) {
-        this._suggestions[key] = suggestionsData[key]
-      }
-    }
-  }
-
   private transformValue(value: any, parentKey?: string): any {
+    if (value instanceof Date) {
+      return value
+    }
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+      return value
+    }
     if (value instanceof PropertyAwareArray) {
       return [...value].map((item) => this.transformValue(item, parentKey))
     }
@@ -694,12 +691,18 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
         if (parentKey) {
           const compositeMethod = 'get' + upperFirst(parentKey) + upperFirst(camelCase(prop))
           if (typeof (this as any)[compositeMethod] === 'function') {
-            result[prop] = (this as any)[compositeMethod](value[prop])
+            const transformed = (this as any)[compositeMethod](value[prop])
+            if (transformed !== undefined) {
+              result[prop] = transformed
+            }
             continue
           }
         }
         // Pass the parentKey along so that nested objects still use it.
-        result[prop] = this.transformValue(value[prop], parentKey)
+        const transformed = this.transformValue(value[prop], parentKey)
+        if (transformed !== undefined) {
+          result[prop] = transformed
+        }
       }
       return result
     }
@@ -718,9 +721,15 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
       const getterName = 'get' + upperFirst(camelCase(key))
       const typedKey = key as unknown as keyof RequestBody
       if (typeof (this as any)[getterName] === 'function') {
-        payload[typedKey] = (this as any)[getterName](value)
+        const transformed = (this as any)[getterName](value)
+        if (transformed !== undefined) {
+          payload[typedKey] = transformed
+        }
       } else {
-        payload[typedKey] = this.transformValue(value, key)
+        const transformed = this.transformValue(value, key)
+        if (transformed !== undefined) {
+          payload[typedKey] = transformed
+        }
       }
     }
 
@@ -732,7 +741,10 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
 
       const getterName = 'get' + upperFirst(camelCase(fieldName))
       if (typeof (this as any)[getterName] === 'function') {
-        payload[fieldName as keyof RequestBody] = (this as any)[getterName]()
+        const transformed = (this as any)[getterName]()
+        if (transformed !== undefined) {
+          payload[fieldName as keyof RequestBody] = transformed
+        }
       } else {
         console.warn(`Getter method '${getterName}' not found for appended field '${fieldName}' in ${this.constructor.name}.`)
       }
@@ -766,9 +778,6 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
     for (const key in this._errors) {
       delete this._errors[key]
     }
-    for (const key in this._suggestions) {
-      delete this._suggestions[key]
-    }
     driver.set(this.constructor.name, {
       state: toRaw(this.state),
       original: toRaw(this.original),
@@ -881,7 +890,6 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
                   }
                 }),
                 errors: (this._errors[key] && this._errors[key][index] && this._errors[key][index][innerKey]) || [],
-                suggestions: (this._suggestions[key] && this._suggestions[key][index] && this._suggestions[key][index][innerKey]) || [],
                 dirty:
                   Array.isArray(this.dirty[key]) && this.dirty[key][index] && typeof (this.dirty[key] as any[])[index] === 'object'
                     ? (this.dirty[key] as any[])[index][innerKey]
@@ -906,7 +914,6 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
                 }
               }),
               errors: (this._errors[key] && this._errors[key][index]) || [],
-              suggestions: (this._suggestions[key] && this._suggestions[key][index]) || [],
               dirty: Array.isArray(this.dirty[key]) ? (this.dirty[key] as boolean[])[index] : false,
               touched: this.touched[key] || false
             }
@@ -917,7 +924,6 @@ export abstract class BaseForm<RequestBody extends object, FormBody extends obje
         props[key] = {
           model: this._model[key],
           errors: this._errors[key] || [],
-          suggestions: this._suggestions[key] || [],
           dirty: this.dirty[key] || false,
           touched: this.touched[key] || false
         }

package/src/vue/forms/PropertyAwareArray.ts

@@ -6,7 +6,6 @@ import { type WritableComputedRef } from 'vue'
 export interface PropertyAwareField<T> {
   model: WritableComputedRef<T>
   errors: any[]
-  suggestions: any[]
   dirty: boolean
 }
 
@@ -21,7 +20,7 @@ export type PropertyAware<T> = {
  * Extends Array with property awareness.
  * When a form field is defined as an instance of PropertyAwareArray,
  * the BaseForm will transform each element into reactive properties with
- * computed getters/setters, error/suggestion tracking, and dirty flags.
+ * computed getters/setters, error tracking, and dirty flags.
  */
 export class PropertyAwareArray<T = any> extends Array<T> {
   /**

package/tests/service/requests/FormDataBody.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest'
+import { FormDataBody } from '../../../src/service/requests/bodies/FormDataBody'
+
+describe('FormDataBody', () => {
+  it('appends strings and files', () => {
+    const file = new File(['abc'], 'credentials.kdbx', { type: 'application/octet-stream' })
+
+    const body = new FormDataBody({
+      name: 'aerg',
+      type: 'kdbx',
+      password: 'aerg',
+      file,
+    })
+
+    const fd = body.getContent()
+
+    expect(fd.get('name')).toBe('aerg')
+    expect(fd.get('type')).toBe('kdbx')
+    expect(fd.get('password')).toBe('aerg')
+    expect(fd.get('file')).toBe(file)
+  })
+
+  it('encodes null as empty string (key present)', () => {
+    const body = new FormDataBody({
+      name: 'aerg',
+      file: null,
+    })
+
+    const fd = body.getContent()
+    expect(fd.get('name')).toBe('aerg')
+    expect(fd.get('file')).toBe('')
+  })
+
+  it('rejects undefined values (should not be silently dropped)', () => {
+    expect(
+      () =>
+        new FormDataBody({
+          missing: undefined,
+        } as any),
+    ).toThrow()
+  })
+
+  it('stringifies number/boolean values', () => {
+    const body = new FormDataBody({
+      count: 3,
+      enabled: false,
+    })
+
+    const fd = body.getContent()
+    expect(fd.get('count')).toBe('3')
+    expect(fd.get('enabled')).toBe('false')
+  })
+
+  it('supports arrays via bracket notation', () => {
+    const body = new FormDataBody({
+      tags: ['a', 'b'],
+    })
+
+    const fd = body.getContent()
+    expect(fd.get('tags[0]')).toBe('a')
+    expect(fd.get('tags[1]')).toBe('b')
+  })
+})

package/tests/vue/forms/BaseForm.transformers.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest'
+import { BaseForm } from '../../../src/vue/forms/BaseForm'
+
+type PositionsItem = { id: number; internal: string }
+
+interface TestFormState {
+  name: string
+  email: string | null
+  meta: { id: string; secret: string }
+  positions: PositionsItem[]
+  file: File | null
+}
+
+type TestRequestPayload = {
+  name?: string
+  email: string | null
+  meta: { id: string }
+  positions: Array<{ id: number }>
+  file?: File
+  started_at?: string
+}
+
+class TestForm extends BaseForm<TestRequestPayload, TestFormState> {
+  protected override append: string[] = ['started_at']
+
+  public constructor(overrides: Partial<TestFormState> = {}) {
+    super({
+      name: '',
+      email: null,
+      meta: { id: 'm1', secret: 'top-secret' },
+      positions: [
+        { id: 1, internal: 'x' },
+        { id: 2, internal: 'y' },
+      ],
+      file: null,
+      ...overrides,
+    }, { persist: false })
+  }
+
+  // Field getter: omit name if empty by returning undefined.
+  protected getName(value: string): string | undefined {
+    const trimmed = value.trim()
+    return trimmed.length ? trimmed : undefined
+  }
+
+  // Composite getter: omit nested meta.secret by returning undefined.
+  protected getMetaSecret(_value: string): undefined {
+    return undefined
+  }
+
+  // Composite getter: omit positions[].internal by returning undefined.
+  protected getPositionsInternal(_value: string): undefined {
+    return undefined
+  }
+
+  // Appended getter: omit started_at by returning undefined.
+  protected getStartedAt(): undefined {
+    return undefined
+  }
+}
+
+describe('BaseForm transformers / getters', () => {
+  it('omits top-level fields when a field getter returns undefined', () => {
+    const form = new TestForm({ name: '   ' })
+    const payload = form.buildPayload()
+
+    expect(Object.prototype.hasOwnProperty.call(payload, 'name')).toBe(false)
+    expect(payload).toMatchObject({
+      email: null,
+    })
+  })
+
+  it('keeps null values (only undefined omits)', () => {
+    const form = new TestForm({ name: 'Alice', email: null })
+    const payload = form.buildPayload()
+
+    expect(payload).toHaveProperty('name', 'Alice')
+    expect(payload).toHaveProperty('email', null)
+  })
+
+  it('omits nested properties when a composite getter returns undefined', () => {
+    const form = new TestForm({ name: 'Alice' })
+    const payload = form.buildPayload()
+
+    expect(payload.meta).toEqual({ id: 'm1' })
+  })
+
+  it('applies composite omission to arrays of objects', () => {
+    const form = new TestForm({ name: 'Alice' })
+    const payload = form.buildPayload()
+
+    expect(payload.positions).toEqual([{ id: 1 }, { id: 2 }])
+  })
+
+  it('omits appended fields when their getter returns undefined', () => {
+    const form = new TestForm({ name: 'Alice' })
+    const payload = form.buildPayload()
+
+    expect(Object.prototype.hasOwnProperty.call(payload, 'started_at')).toBe(false)
+  })
+
+  it('keeps File values intact (does not transform into a plain object)', () => {
+    const file = new File(['abc'], 'credentials.kdbx', { type: 'application/octet-stream' })
+    const form = new TestForm({ name: 'Alice', file })
+    const payload = form.buildPayload()
+
+    expect(payload.file).toBe(file)
+  })
+})