@blueprint-ts/core 1.2.0 → 3.0.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 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)
+
+
+### Features
+
+* Cache resolved route resources for child routes db70b77
 ## v1.2.0 - 2026-01-25
 
 # [1.2.0](/compare/v1.1.2...v1.2.0) (2026-01-25)

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/docs/vue/requests/route-resource-binding.md

@@ -1,4 +1,4 @@
-# Route Model Binding
+# Route Resource Binding
 
 When using `vue-router`, you can automatically bind route parameters to resources, similar to how Laravel's route model binding works.
 
@@ -7,60 +7,228 @@ When using `vue-router`, you can automatically bind route parameters to resource
 To enable the router to load resources automatically, install the route injection plugin when initializing your router:
 
 ```ts
+import { installRouteInjection } from '@blueprint-ts/core'
+
 installRouteInjection(router)
 ```
 
-### Defining Routes
+## Defining Routes
 
 Use the `defineRoute` helper to define your routes and specify which parameters should be resolved into resources:
 
 ```ts
-defineRoute<{
+import { defineRoute, RouteResourceRequestResolver } from '@blueprint-ts/core'
+import ProductDetailPage from '@/pages/ProductDetailPage.vue'
+
+export default defineRoute<{
     product: ProductResource
 }>()({
     path: ':productId',
     name: 'products.show',
     component: ProductDetailPage,
-    meta: {
-        inject: {
-            product: {
-                from: 'productId',
-                resolve: (productId: string) => {
-                    return new RouteModelRequestResolver(
-                        new ProductShowRequest(productId)
-                    )
-                }
+    inject: {
+        product: {
+            from: 'productId',
+            resolve: (productId: string) => {
+                return new RouteResourceRequestResolver(
+                    new ProductShowRequest(productId)
+                )
             }
         }
     }
 })
 ```
 
-The `beforeResolve` navigation guard will automatically fetch the `ProductResource` using the `ProductShowRequest` and the `productId` from the route.
+Navigation is **non-blocking** — the route navigates immediately while resources resolve in the background. Cached values are reused when navigating between child routes with unchanged parameters.
 
 ## Usage in Components
 
-Your component can then directly access the resolved resource via props:
+Your component can directly access the resolved resource via props:
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{
+    product: ProductResource
+}>()
+</script>
+```
+
+## Handling Loading & Error States
+
+### Using `RouteResourceBoundView`
+
+`RouteResourceBoundView` is a drop-in replacement for `<RouterView>` that automatically handles loading and error states. Define error and loading components directly in the route:
+
+```ts
+import { defineRoute, RouteResourceRequestResolver } from '@blueprint-ts/core'
+import ProductDetailPage from '@/pages/ProductDetailPage.vue'
+import GenericErrorPage from '@/pages/GenericErrorPage.vue'
+import LoadingSpinner from '@/components/LoadingSpinner.vue'
+
+export default defineRoute<{
+    product: ProductResource
+}>()({
+    path: ':productId',
+    name: 'products.show',
+    component: ProductDetailPage,
+    errorComponent: GenericErrorPage,
+    loadingComponent: LoadingSpinner,
+    inject: {
+        product: {
+            from: 'productId',
+            resolve: (productId: string) => {
+                return new RouteResourceRequestResolver(
+                    new ProductShowRequest(productId)
+                )
+            }
+        }
+    }
+})
+```
+
+Then replace `<RouterView>` with `<RouteResourceBoundView>` in your layout:
+
+```vue
+<template>
+  <RouteResourceBoundView />
+</template>
+
+<script setup lang="ts">
+import { RouteResourceBoundView } from '@blueprint-ts/core'
+</script>
+```
+
+The `errorComponent` receives `error` and `refresh` as props. The `refresh` function retries all failed resources:
+
+```vue
+<!-- GenericErrorPage.vue -->
+<template>
+  <div>
+    <p>{{ error.message }}</p>
+    <button @click="refresh">Try Again</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+    error: Error
+    refresh: () => Promise<void>
+}>()
+</script>
+```
+
+#### Using Scoped Slots
+
+`RouteResourceBoundView` supports the same `v-slot` pattern as `<RouterView>`:
+
+```vue
+<RouteResourceBoundView v-slot="{ Component, route }">
+  <component
+    :is="Component"
+    v-if="Component"
+  />
+  <EmptyState v-else />
+</RouteResourceBoundView>
+```
+
+When no `errorComponent` or `loadingComponent` is defined on the route, you can use named slots as fallbacks:
 
 ```vue
+<RouteResourceBoundView>
+  <template #default="{ Component, route }">
+    <component :is="Component" v-if="Component" />
+  </template>
+
+  <template #loading>
+    <LoadingSpinner />
+  </template>
+
+  <template #error="{ error, refresh }">
+    <div>
+      <p>{{ error.message }}</p>
+      <button @click="refresh">Retry</button>
+    </div>
+  </template>
+</RouteResourceBoundView>
+```
+
+### Using `useRouteResource` (Manual Handling)
+
+If you prefer to handle loading and error states inside the component itself, set `lazy: false` on the route. This renders the component immediately while resources resolve in the background:
+
+```ts
+export default defineRoute<{
+    product: ProductResource
+}>()({
+    path: ':productId',
+    name: 'products.show',
+    component: ProductDetailPage,
+    lazy: false,
+    inject: {
+        product: {
+            from: 'productId',
+            resolve: (productId: string) => {
+                return new RouteResourceRequestResolver(
+                    new ProductShowRequest(productId)
+                )
+            }
+        }
+    }
+})
+```
+
+Then use the `useRouteResource` composable inside your component:
+
+```vue
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="error">
+    <p>{{ error.message }}</p>
+    <button @click="refresh">Retry</button>
+  </div>
+  <div v-else>
+    <h1>{{ product.name }}</h1>
+  </div>
+</template>
+
 <script setup lang="ts">
+import { useRouteResource } from '@blueprint-ts/core'
+
 const props = defineProps<{
     product: ProductResource
 }>()
+
+const { refresh, isLoading, error } = useRouteResource('product')
 </script>
 ```
 
-## Handling Loading States
+`useRouteResource` returns:
+
+| Property    | Type                      | Description                              |
+|-------------|---------------------------|------------------------------------------|
+| `isLoading` | `ComputedRef<boolean>`    | `true` while the resource is resolving   |
+| `error`     | `ComputedRef<Error\|null>` | The error if resolution failed, else `null` |
+| `refresh`   | `(options?: { silent?: boolean }) => Promise<void>` | Re-fetches the resource. Pass `{ silent: true }` to suppress the loading state. |
+
+#### Silent Refresh
 
-You can handle the loading state of the request by using the event system of the request class:
+By default, calling `refresh()` sets `isLoading` to `true` while the resource is being re-fetched, which causes `RouteResourceBoundView` to show the loading component. If you want to refresh the resource in the background without triggering the loading state (e.g. polling or optimistic updates), pass `{ silent: true }`:
 
 ```ts
-resolve: (productId: string) => {
-    return new RouteModelRequestResolver(
-        new ProductShowRequest(productId).on<boolean>(RequestEvents.LOADING, (loading: boolean) => {
-          const loadingStore = useLoadingStore()
-          loadingStore.setLoading(loading)
-        })
-    )
-}
-```
+const { refresh } = useRouteResource('product')
+
+// Normal refresh — triggers loading state
+await refresh()
+
+// Silent refresh — does not trigger loading state
+await refresh({ silent: true })
+```
+
+A silent refresh still updates the `error` state if the request fails.
+
+### Lazy vs Non-Lazy
+
+| Option          | Behavior                                                                                      |
+|-----------------|-----------------------------------------------------------------------------------------------|
+| `lazy: true` (default) | `RouteResourceBoundView` intercepts loading/error states and shows the appropriate component |
+| `lazy: false`   | The target component renders immediately; use `useRouteResource()` for manual state handling  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-ts/core",
-  "version": "1.2.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')
       }
     }