@blueprint-ts/core 4.1.0-beta.1 → 4.1.0-beta.3

package/docs/vue/forms/index.md

@@ -1,99 +0,0 @@
-# BaseForm
-
-`BaseForm` is a TypeScript base class for Vue forms that gives you:
-- Type-safe form state
-- Dirty and touched tracking
-- Validation and error mapping
-- Payload transformations
-- Optional persistence
-- Array helpers and file handling
-
-**Getting Started**
-
-Minimal form class:
-
-```ts
-import { BaseForm, type PersistenceDriver, SessionStorageDriver } from '@blueprint-ts/core/vue/forms'
-import { RequiredRule, ValidationMode } from '@blueprint-ts/core/vue/forms/validation'
-
-interface FormState {
-  name: string
-  email: string
-}
-
-interface RequestPayload {
-  name: string
-  email: string
-  timestamp: string
-}
-
-export class MyForm extends BaseForm<RequestPayload, FormState> {
-  protected override append: string[] = ['timestamp']
-  protected override ignore: string[] = []
-  protected override errorMap: { [serverKey: string]: string | string[] } = {}
-
-  public constructor() {
-    super(
-      { name: '', email: '' },
-      { persist: true, persistSuffix: 'optional-suffix' }
-    )
-  }
-
-  protected override getPersistenceDriver(suffix?: string): PersistenceDriver {
-    return new SessionStorageDriver(suffix)
-  }
-
-  protected override defineRules() {
-    return {
-      name: { rules: [new RequiredRule<FormState>('Name is required')] },
-      email: {
-        rules: [new RequiredRule<FormState>('Email is required')],
-        options: { mode: ValidationMode.DEFAULT }
-      }
-    }
-  }
-
-  protected getTimestamp(): string {
-    return new Date().toISOString()
-  }
-}
-```
-
-Component usage:
-
-```vue
-<template>
-  <form @submit.prevent="submitForm">
-    <div>
-      <label>Name</label>
-      <input v-model="form.properties.name.model.value" />
-      <div v-if="form.properties.name.errors.length" class="error">
-        {{ form.properties.name.errors[0] }}
-      </div>
-    </div>
-
-    <div>
-      <label>Email</label>
-      <input v-model="form.properties.email.model.value" />
-      <div v-if="form.properties.email.errors.length" class="error">
-        {{ form.properties.email.errors[0] }}
-      </div>
-    </div>
-
-    <button type="submit" :disabled="!form.isDirty()">Submit</button>
-    <button type="button" @click="form.reset()">Reset</button>
-  </form>
-</template>
-
-<script setup lang="ts">
-import { MyForm } from './MyForm'
-
-const form = new MyForm()
-
-async function submitForm() {
-  if (!form.validate(true)) return
-  const payload = form.buildPayload()
-  await api.submitForm(payload)
-}
-</script>
-```

package/docs/vue/forms/payloads.md

@@ -1,99 +0,0 @@
-# Building Payloads
-
-## Overview
-
-Form fields often need to be transformed before sending them to the server. You can define getters on your form class, and `buildPayload()` will use them to convert values.
-
-`buildPayload()` supports three getter patterns.
-
-## Getters
-
-### Field Getters
-
-Field getters are for fields that directly exist in the form state as top level property. They receive the current field value and return the value that should be sent in the payload.
-
-Naming scheme: `get${upperFirst(camelCase(fieldName))}`. For example, `name` becomes `getName`, `user_id` becomes `getUserId`.
-
-```ts
-protected getName(value: string): string {
-  return value.trim()
-}
-```
-
-If the form stores an object but the API expects an ID:
-
-```ts
-protected getBusinessAssociateId(value: BusinessAssociateResource | null): string | null {
-  return value?.id ?? null
-}
-```
-
-### Composite Getters For Nested Properties
-
-Composite getters are used for nested properties when no top-level field getter exists. They receive the nested value and return the payload value.
-
-Naming scheme: `get${upperFirst(parentFieldKey)}${upperFirst(camelCase(propName))}`.
-
-Example: if `positions` is an array of objects and each entry has a `product` resource, use a composite getter so the returned value is sent instead of the full `ProductResource`.
-
-Before:
-
-```ts
-positions: [
-  {
-    product: {
-      id: '123',
-      name: 'Example'
-    }
-  }
-]
-```
-
-After:
-
-```ts
-positions: [
-  {
-    product: '123'
-  }
-]
-```
-
-```ts
-protected getPositionsProduct(value: ProductResource | null): number | null {
-  return value?.id ?? null
-}
-```
-
-### Appended Fields
-
-Sometimes your server expects fields that don’t exist as a single input in the form. For example, the API may expect a `started_at` datetime, while the form has `start_date` and `start_time` fields. In this case, use an appended field.
-
-Define a getter with the same naming scheme as a field getter. Because the field does not exist in the form state, the getter receives no parameters, but you can access other values via `this.state`. Then add the field name (snake_case) to `append`. `buildPayload()` will call the getter and append the computed value to the payload.
-
-```ts
-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()
-}
-```
-
-## Ignoring Fields
-
-You can exclude fields from the payload using `ignore`:
-
-```ts
-protected override ignore: string[] = ['internal_note']
-```
-
-Ignored fields are never added to the payload. This is especially useful with appended fields, where you can ignore the source fields (`start_date`, `start_time`) after computing a combined value like `started_at`.
-
-## Omitting Fields
-
-Omitting is similar to ignoring, but it is dynamic at runtime. If a getter returns `undefined`, that field is not added to the payload. If you return anything else, the field is included.
-
-## Dates And Files
-
-- `Date` values are treated as scalars and preserved.
-- `File`/`Blob` values are treated as scalars and preserved. Send the payload using a multipart request.

package/docs/vue/forms/persistence.md

@@ -1,19 +0,0 @@
-# Persistence
-
-Persistence is enabled by default. Disable it via `super(defaults, { persist: false })`.
-
-Example:
-
-```ts
-protected override getPersistenceDriver(suffix?: string): PersistenceDriver {
-  return new SessionStorageDriver(suffix)
-}
-```
-
-See the Persistence service for available drivers and custom implementations: [Persistence](/services/persistence/).
-
-Notes:
-- `persistSuffix` is passed to `getPersistenceDriver(suffix)` for namespacing.
-- Persisted state is reused only if the stored `original` matches your current defaults.
-- `persist: false` disables automatic rehydration and background persistence.
-- `File`/`Blob` values are not JSON-serializable and should use `{ persist: false }`.

package/docs/vue/forms/state-and-properties.md

@@ -1,26 +0,0 @@
-# State And Properties
-
-`BaseForm` tracks the original state and the current state of each field.
-
-```ts
-form.isDirty() // any field modified
-form.isDirty('email') // specific field modified
-
-form.touch('email')
-form.isTouched('email')
-```
-
-**Properties**
-
-`properties.<field>` exposes:
-- `model` (a `ComputedRef` compatible with `v-model`)
-- `errors` (array)
-- `dirty` and `touched`
-
-Example:
-
-```vue
-<input v-model="form.properties.email.model.value" />
-<div v-if="form.properties.email.dirty">This field has been changed</div>
-<div v-if="form.properties.email.errors.length">{{ form.properties.email.errors[0] }}</div>
-```

package/docs/vue/forms/utilities.md

@@ -1,27 +0,0 @@
-# Utilities
-
-Update multiple fields at once:
-
-```ts
-form.fillState({ name: 'John Doe', email: 'john@example.com' })
-```
-
-Synchronize a value without marking dirty:
-
-```ts
-form.syncValue('email', 'new@example.com')
-```
-
-Reset the form to its original state:
-
-```ts
-form.reset()
-```
-
-Convert `properties` back to raw data:
-
-```ts
-import { propertyAwareToRaw } from '@blueprint-ts/core/vue/forms'
-
-const raw = propertyAwareToRaw<FormState>(form.properties)
-```

package/docs/vue/forms/validation.md

@@ -1,189 +0,0 @@
-# Validation
-
-Define validation rules by overriding `defineRules()` in your form class.
-
-Validation errors are exposed on `properties.<field>.errors`, as documented in [Errors](/vue/forms/errors).
-
-## Available Rules
-
-- `RequiredRule` — checks that the value is not `null`, `undefined`, or `''`
-- `MinRule` — minimum length for strings/arrays or minimum value for numbers
-- `ConfirmedRule` — validates that two fields match (e.g. password confirmation)
-- `UrlRule` — validates that the value is a valid URL
-- `EmailRule` — validates that the value is a valid email address
-- `JsonRule` — validates that the value is valid JSON
-
-All rules are exported from `@blueprint-ts/core/vue/forms/validation`.
-
-## Validation Modes
-
-Validation modes are bit flags. You can use the presets below or combine flags with `|`.
-
-**Flags**
-
-- `ValidationMode.NEVER` — never validate this field
-- `ValidationMode.INSTANTLY` — validate immediately when the field is evaluated, even if not dirty/touched
-- `ValidationMode.ON_TOUCH` — validate after the field is touched
-- `ValidationMode.ON_DIRTY` — validate when the field becomes dirty
-- `ValidationMode.ON_SUBMIT` — validate on submit
-- `ValidationMode.ON_DEPENDENT_CHANGE` — validate when a dependent field changes
-
-**Presets**
-
-- `ValidationMode.DEFAULT` — `ON_TOUCH | ON_DIRTY | ON_SUBMIT`
-- `ValidationMode.AGGRESSIVE` — `INSTANTLY | ON_TOUCH | ON_DIRTY | ON_SUBMIT`
-- `ValidationMode.PASSIVE` — `ON_SUBMIT`
-
-**Custom Combination**
-
-```ts
-options: { mode: ValidationMode.ON_TOUCH | ValidationMode.ON_SUBMIT }
-```
-
-**Internal vs External**
-
-- Internal means validation runs from within `BaseForm` based on user interaction or dependencies.
-- External means you explicitly trigger validation via `validate(true)`, typically on submit.
-
-- Internal triggers: `INSTANTLY`, `ON_TOUCH`, `ON_DIRTY`, `ON_DEPENDENT_CHANGE`
-- External trigger (`validate(true)`): `ON_SUBMIT` (and `PASSIVE` preset)
-- `NEVER` disables validation entirely
-
-Rules can declare dependencies via `rule.dependsOn = ['otherField']`. Some rules, such as `ConfirmedRule`, automatically set up bidirectional dependencies.
-
-## Externally Triggering Validation
-
-```ts
-const ok = form.validate(true)
-if (!ok) return
-```
-
-Some modes (notably `PASSIVE` / `ON_SUBMIT`) only validate when you trigger validation manually.
-
-### How `validate(isSubmitting)` Behaves
-
-- `validate(true)` enables `ON_SUBMIT` rules. Fields with `PASSIVE` mode will validate only here.
-- `validate(false)` still validates fields that are currently dirty, touched, or set to `INSTANTLY`.
-- `ValidationMode.NEVER` prevents validation in all cases, even during submit.
-
-## Typing `defineRules`
-
-Use `ValidationRules<FormBody>` for a concise, strongly-typed return type:
-
-```ts
-import { type ValidationRules } from '@blueprint-ts/core/vue/forms/validation'
-
-protected override defineRules(): ValidationRules<MyFormBody> {
-  return {
-    // ...
-  }
-}
-```
-
-## Custom Rules
-
-Create your own rules by extending `BaseRule`:
-
-```ts
-import { BaseRule } from '@blueprint-ts/core/vue/forms/validation'
-
-export class MaxRule<FormBody extends object> extends BaseRule<FormBody> {
-  public constructor(
-    protected max: number,
-    protected message: string = 'Value is too large'
-  ) {
-    super()
-  }
-
-  public validate(value: unknown): boolean {
-    if (value === null || value === undefined) {
-      return true
-    }
-
-    if (typeof value === 'string') {
-      return value.length <= this.max
-    }
-
-    if (typeof value === 'number') {
-      return value <= this.max
-    }
-
-    if (Array.isArray(value)) {
-      return value.length <= this.max
-    }
-
-    return false
-  }
-
-  public getMessage(): string {
-    return this.message
-  }
-}
-```
-
-If a rule depends on other fields, set `dependsOn` or implement bidirectional validation:
-
-```ts
-import { BaseRule } from '@blueprint-ts/core/vue/forms/validation'
-import { type BidirectionalRule } from '@blueprint-ts/core/vue/forms/validation'
-
-export class MatchesOtherRule<FormBody extends object> extends BaseRule<FormBody> implements BidirectionalRule {
-  public dependsOn: Array<keyof FormBody> = ['other']
-
-  public validate(value: unknown, state: FormBody): boolean {
-    return value === state['other' as keyof FormBody]
-  }
-
-  public getMessage(): string {
-    return 'Values do not match'
-  }
-
-  public getBidirectionalFields(): string[] {
-    return ['other']
-  }
-}
-```
-
-## Example
-
-```ts
-import { BaseForm } from '@blueprint-ts/core/vue/forms'
-import { ConfirmedRule, MinRule, RequiredRule, type ValidationRules } from '@blueprint-ts/core/vue/forms/validation'
-
-export interface PinUpdateFormBody {
-  current_pin: string
-  new_pin: string
-  new_pin_confirmation: string
-}
-
-export class PinUpdateForm extends BaseForm<PinUpdateFormBody, PinUpdateFormBody> {
-  public constructor() {
-    super({
-      current_pin: '',
-      new_pin: '',
-      new_pin_confirmation: ''
-    })
-  }
-
-  protected override defineRules(): ValidationRules<PinUpdateFormBody> {
-    return {
-      current_pin: {
-        rules: [
-          new RequiredRule('This field is required.'),
-          new MinRule(4, 'This field must be at least 4 characters long.')
-        ]
-      },
-      new_pin: {
-        rules: [
-          new RequiredRule('This field is required.'),
-          new MinRule(4, 'This field must be at least 4 characters long.'),
-          new ConfirmedRule('new_pin_confirmation', 'This field must match the confirmation.')
-        ]
-      },
-      new_pin_confirmation: {
-        rules: [new RequiredRule('This field is required.')]
-      }
-    }
-  }
-}
-```

package/docs/vue/requests/loading.md

@@ -1,51 +0,0 @@
-# Loading
-
-For Vue apps, the library includes `VueRequestLoader`, `VueRequestLoaderFactory`, and `VueRequestBatchLoader`, which
-use Vue refs to track loading state.
-
-## Registering the Vue Loader Factory
-
-```typescript
-import { BaseRequest } from '@blueprint-ts/core/requests'
-import { VueRequestLoaderFactory } from '@blueprint-ts/core/vue/requests'
-
-BaseRequest.setRequestLoaderFactory(new VueRequestLoaderFactory())
-```
-
-## Reading Loading State
-
-```typescript
-const request = new ExpenseIndexRequest()
-
-request.send()
-
-const isLoading = request.isLoading()
-// isLoading is a Ref<boolean> when using VueRequestLoaderFactory
-```
-
-## Batch Loading
-
-`VueRequestBatchLoader` can track the loading state of multiple requests. Use it when you want a single loading ref to
-reflect a batch of requests.
-
-```typescript
-import { VueRequestBatchLoader } from '@blueprint-ts/core/vue/requests'
-
-const batchLoader = new VueRequestBatchLoader(2)
-batchLoader.startBatch(2)
-
-const requestA = new ExpenseIndexRequest().setRequestLoader(batchLoader)
-const requestB = new ExpenseIndexRequest().setRequestLoader(batchLoader)
-
-requestA.send()
-requestB.send()
-
-const isLoading = batchLoader.isLoading()
-```
-
-If the batch will not complete (for example, when a chained request fails), call `abortBatch()` to stop waiting for the
-remaining requests:
-
-```typescript
-batchLoader.abortBatch()
-```