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

package/docs/vue/composables/use-model-wrapper.md

@@ -1,29 +0,0 @@
-# `useModelWrapper`
-
-`useModelWrapper` is a small helper to implement `v-model` in components. It returns a computed ref that proxies the model value and emits the update event.
-
-Deprecated: In Vue 3.4+, prefer `defineModel()` where possible. `useModelWrapper` remains available for legacy usage or when you need a callback on update.
-
-## Example
-
-```vue
-<script setup lang="ts">
-import { useModelWrapper } from '@blueprint-ts/core/vue'
-
-const props = defineProps<{ modelValue: boolean }>()
-const emit = defineEmits<{ (event: 'update:modelValue', value: boolean): void }>()
-
-const model = useModelWrapper<boolean, typeof emit>(props, emit)
-</script>
-```
-
-Using a custom model name:
-
-```ts
-const model = useModelWrapper<boolean, typeof emit>(props, emit, { name: 'open' })
-```
-
-## Options
-
-- `name` (default `modelValue`): the model prop/event name
-- `callback` (optional): invoked with the new value after emitting the update event

package/docs/vue/composables/use-on-open.md

@@ -1,26 +0,0 @@
-# `useOnOpen`
-
-`useOnOpen` lets you register callbacks that run when a boolean ref toggles from closed to open or vice versa.
-
-## Example
-
-```ts
-import { useOnOpen } from '@blueprint-ts/core/vue'
-import { ref } from 'vue'
-
-const isOpen = ref(false)
-const { onOpen, onClose } = useOnOpen(isOpen)
-
-onOpen(() => {
-  // opened
-})
-
-onClose(() => {
-  // closed
-})
-```
-
-## Notes
-
-Callbacks are executed on the next tick after the value changes.
-You can register multiple callbacks for both `onOpen` and `onClose`.

package/docs/vue/forms/arrays.md

@@ -1,102 +0,0 @@
-# Arrays
-
-## PropertyAwareArray
-
-Use `PropertyAwareArray` for arrays with per-item `v-model`, errors, and dirty state when your array contains objects.
-
-```ts
-import { BaseForm, PropertyAwareArray } from '@blueprint-ts/core/vue/forms'
-
-export interface FormWithPositions {
-  positions: PositionItem[]
-}
-
-export class MyComplexForm extends BaseForm<RequestType, FormWithPositions> {
-  constructor() {
-    super({
-      positions: new PropertyAwareArray([{ id: 1, value: '' }])
-    })
-  }
-
-  public addPosition(): void {
-    this.addToArrayProperty('positions', {
-      id: this.properties.positions.length + 1,
-      value: ''
-    })
-  }
-
-  public removePosition(id: number): void {
-    this.removeArrayItem('positions', (position) => position.id !== id)
-    this.resetArrayCounter('positions', 'id')
-  }
-}
-```
-
-Example component usage:
-
-```vue
-<template>
-  <div v-for="(position, index) in form.properties.positions" :key="index">
-    <input v-model="position.value.model.value" />
-    <div v-if="position.value.errors.length">{{ position.value.errors[0] }}</div>
-    <div v-if="position.value.dirty">Changed</div>
-  </div>
-</template>
-```
-
-Nested error keys like `positions.0.value` map into `position.value.errors`.
-
-## propertyAwareToRaw
-
-`propertyAwareToRaw` converts a property-aware object (each field wrapped in `{ model: { value } }`) into a plain object by unwrapping every field's `model.value`. It is purely a transformation: metadata such as `errors`, `dirty`, and `touched` is dropped, while arrays and nested objects are processed recursively. Keys starting with `_` are omitted from the result, and arrays are mapped element-by-element via the same unwrapping.
-
-### Input shape (property-aware)
-
-```ts
-const propertyAwarePosition = {
-  id: {
-    model: { value: 'pos-1' },
-    errors: [],
-    dirty: false,
-    touched: false
-  },
-  sort_order: {
-    model: { value: 10 },
-    errors: [],
-    dirty: false,
-    touched: false
-  },
-  description: {
-    model: { value: 'Service' },
-    errors: [],
-    dirty: false,
-    touched: false
-  },
-  net_amount: {
-    model: { value: 100 },
-    errors: [],
-    dirty: false,
-    touched: false
-  }
-}
-```
-
-Note that this is only an example of how the input shape looks When used in a form the model is a WritableComputedRef.
-
-### Output shape (raw)
-
-```ts
-const rawPosition = {
-  id: 'pos-1',
-  sort_order: 10,
-  description: 'Service',
-  net_amount: 100
-}
-```
-
-### Notes
-
-- Arrays are mapped element-by-element.
-- Nested objects are unwrapped recursively.
-- Any keys starting with `_` are ignored.
-- Only the `model.value` remains; form metadata is dropped.

package/docs/vue/forms/errors.md

@@ -1,52 +0,0 @@
-# Errors
-
-`BaseForm` maps validation errors to fields and exposes them on `properties.<field>.errors`.
-
-## Filling External Errors
-
-`fillErrors` is intended for server-side validation responses.
-It overwrites any existing client-side validation errors.
-
-### Expected Error Format
-
-`fillErrors` expects an object where each key is a field path and each value is an array of messages. For example:
-
-```json
-{
-  "email": ["The email field is required."],
-  "positions.0.value": ["The value is invalid."]
-}
-```
-
-If you provide a single string instead of an array, it will be assigned as-is, but the UI helpers assume arrays.
-This format matches Laravel's validation error response and is currently the only supported format.
-
-```ts
-form.fillErrors(error.response.data.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)
-
-## Checking For Errors
-
-```ts
-form.hasErrors()
-```
-
-## Advanced Usage
-
-### Mapping Server Errors
-
-This is especially useful for appended fields that do not exist in your form state. See [Building Payloads – Appended Fields](/vue/forms/payloads#appended-fields).
-
-Map server error keys to your form fields with `errorMap`:
-
-```ts
-protected override errorMap: { [serverKey: string]: string | string[] } = {
-  started_at: ['start_date', 'start_time'],
-  ended_at: ['end_date', 'end_time']
-}
-```

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.')]
-      }
-    }
-  }
-}
-```