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

package/docs/upgrading/v3-to-v4.md

@@ -1,214 +0,0 @@
-# Upgrading v3 to v4
-
-This guide covers breaking changes when upgrading from v3 to v4.
-
-## Bulk Request Sender Is Now Generic
-
-`BulkRequestSender` is now a generic class, and `setRequests()` expects wrappers with matching type parameters. If you
-instantiated the sender without generics, TypeScript may report type errors when passing typed request wrappers.
-
-### What Changed
-
-- `BulkRequestSender` is now generic over:
-  - `RequestLoaderLoadingType`
-  - `RequestBodyInterface`
-  - `ResponseClass`
-  - `RequestParamsInterface`
-- `setRequests()` is now typed to accept wrappers with the same generics.
-
-### How to Fix
-
-Add generics when creating the sender so it matches your wrapper types:
-
-```typescript
-const bulkRequestSenderInstance = new BulkRequestSender<
-    RequestLoaderLoadingType,
-    RequestBodyInterface,
-    ResponseClass,
-    RequestParamsInterface
->([], bulkRequestExecutionMode, retryCount)
-```
-
-If you already have typed wrappers, TypeScript will infer the rest once the sender is typed.
-
-## Paginator `init()` Was Removed
-
-Pagination now marks a paginator as initialized only after the first successful load. The `init()` method was removed
-in favor of `load()`.
-
-### What Changed
-
-- `isInitialized()` now becomes `true` only after a successful data load.
-- `init()` no longer exists.
-
-### How to Fix
-
-Replace `init(...)` with `load(...)`:
-
-```typescript
-await paginator.load()
-```
-
-## Paginator `refresh()` Was Removed
-
-`refresh()` was removed in favor of `load()` to make the first load more intuitive.
-
-### How to Fix
-
-Replace `refresh(...)` with `load(...)`:
-
-```typescript
-await paginator.load()
-```
-
-## Pagination Setters No Longer Trigger Loads
-
-`setPageNumber()` and `setPageSize()` now only update state. Call `load()` to fetch data:
-
-```typescript
-await paginator.setPageNumber(2).load()
-await paginator.setPageSize(50).load()
-```
-
-`setPage()` was renamed to `setPageNumber()`.
-Page navigation helpers (`toNextPage`, `toPreviousPage`, `toFirstPage`, `toLastPage`) still load the new page in one call.
-
-## PaginationParamsContract Was Removed
-
-`PaginationParamsContract` was removed from the Laravel pagination exports because it was unused. Define your own params
-interface in your app instead.
-
-## Deprecated `Paginator` alias removed
-
-`Paginator` (and the related `PaginatorOptions` alias) was an old alias for `PageAwarePaginator`. The alias file has been removed, so importing `Paginator` or `PaginatorOptions` now results in a build error.
-
-### How to Fix
-
-- Replace `import { Paginator } from '@blueprint-ts/core/pagination'` with:
-
-```typescript
-import { PageAwarePaginator } from '@blueprint-ts/core/pagination'
-```
-
-- Replace `import { type PaginatorOptions } from '@blueprint-ts/core/pagination'` with:
-
-```typescript
-import { type PageAwarePaginatorOptions } from '@blueprint-ts/core/pagination'
-```
-
-## Core Modules Moved out of `service/`
-
-Core (non-framework) modules moved from `@blueprint-ts/core/service/*` to `@blueprint-ts/core/*`.
-
-### How to Fix
-
-Replace:
-
-```typescript
-import { BaseRequest } from '@blueprint-ts/core/service/requests'
-import { PageAwarePaginator } from '@blueprint-ts/core/service/pagination'
-import { DeferredPromise } from '@blueprint-ts/core/service/support'
-import { BulkRequestSender } from '@blueprint-ts/core/service/bulkRequests'
-import { LocalStorageDriver } from '@blueprint-ts/core/service/persistenceDrivers'
-```
-
-with:
-
-```typescript
-import { BaseRequest } from '@blueprint-ts/core/requests'
-import { PageAwarePaginator } from '@blueprint-ts/core/pagination'
-import { DeferredPromise } from '@blueprint-ts/core/support'
-import { BulkRequestSender } from '@blueprint-ts/core/bulkRequests'
-import { LocalStorageDriver } from '@blueprint-ts/core/persistenceDrivers'
-```
-
-## Helpers Moved to Support
-
-Helpers are now exported from `@blueprint-ts/core/support`. The `@blueprint-ts/core/helpers` export was removed.
-
-### How to Fix
-
-Replace:
-
-```typescript
-import { isAtBottom } from '@blueprint-ts/core/helpers'
-```
-
-with:
-
-```typescript
-import { isAtBottom } from '@blueprint-ts/core/support'
-```
-
-## ConfirmDialogSeverity Is Now an Enum
-
-`ConfirmDialogSeverity` was changed from a string union type to an enum. Update any `getSeverity()` implementations to return the enum value.
-
-### How to Fix
-
-Replace:
-
-```typescript
-import { type ConfirmDialogOptions } from '@blueprint-ts/core/vue'
-
-export class MyConfirmOptions implements ConfirmDialogOptions {
-  getSeverity() {
-    return 'warning'
-  }
-}
-```
-
-with:
-
-```typescript
-import { type ConfirmDialogOptions, ConfirmDialogSeverity } from '@blueprint-ts/core/vue'
-
-export class MyConfirmOptions implements ConfirmDialogOptions {
-  getSeverity() {
-    return ConfirmDialogSeverity.WARNING
-  }
-}
-```
-
-## BaseRequestContract Requires `setConcurrency`
-
-`BaseRequestContract` now includes `setConcurrency(...)` so requests can opt into concurrency handling (e.g., latest-wins or replace-latest).
-If you implemented `BaseRequestContract` directly (instead of extending `BaseRequest`), TypeScript will now require this method.
-
-### How to Fix
-
-Add the method to your custom request implementation:
-
-```typescript
-setConcurrency(options?: RequestConcurrencyOptions): this {
-  // no-op by default; use options if your implementation needs them
-  return this
-}
-```
-
-## Laravel Packages Moved
-
-Laravel modules moved from `@blueprint-ts/core/service/laravel/*` to `@blueprint-ts/core/laravel/*`.
-
-### How to Fix
-
-Replace:
-
-```typescript
-import { JsonBaseRequest } from '@blueprint-ts/core/service/laravel/requests'
-```
-
-with:
-
-```typescript
-import { JsonBaseRequest } from '@blueprint-ts/core/laravel/requests'
-```
-
-## BaseForm `state` is now protected
-
-`BaseForm.state` was public in previous versions, but it is now `protected readonly`. That means external consumers can no longer import form instances and access `form.state`. Subclasses can still read/write state internally, so any code that depended on reading it from outside the form must switch to supported accessors such as `form.properties`.
-
-### How to Fix
-
-- Replace direct `form.state` usage with the public helpers (`form.properties`, getters, or explicit payload builders).
-- If you were creating helpers that accessed `state` from outside the form, move those helpers inside the form class so they can rely on the protected field.

package/docs/vue/composables/use-confirm-dialog.md

@@ -1,96 +0,0 @@
-# `useConfirmDialog`
-
-`useConfirmDialog` mounts a confirmation dialog component on demand and returns an `openConfirmDialog` function that resolves to `true` or `false`.
-
-## Requirements
-
-- Call `useConfirmDialog` inside a `setup()` function.
-- The dialog component must expose an `open()` method via `defineExpose`.
-- `open()` must return a `Promise<boolean>`.
-- The component receives an `options` prop that matches `ConfirmDialogOptions`.
-
-## Example
-
-```vue
-<template>
-  <button @click.prevent="click">
-    <slot />
-  </button>
-</template>
-
-<script setup lang="ts">
-import { useConfirmDialog, type ConfirmDialogOptions } from '@blueprint-ts/core/vue'
-import ConfirmDialog from '@/ConfirmDialog.vue'
-
-const props = defineProps<{
-  confirmation?: ConfirmDialogOptions
-}>()
-
-const { openConfirmDialog } = useConfirmDialog(ConfirmDialog)
-
-async function click() {
-  if (props.confirmation) {
-    const confirmed = await openConfirmDialog(props.confirmation)
-
-    if (confirmed) {
-        const request = new Request()
-        
-        request.send()
-    }
-  }
-}
-</script>
-```
-
-## ConfirmDialogOptions
-
-The options object must implement the following contract:
-
-```ts
-import { ConfirmDialogSeverity } from '@blueprint-ts/core/vue'
-
-export interface ConfirmDialogOptions {
-  getMessage(): string
-  getSeverity(): ConfirmDialogSeverity
-  getTitle(): string
-  getOkText(): string
-  getCancelText(): string
-}
-```
-
-The available severities are:
-
-```ts
-export enum ConfirmDialogSeverity {
-  INFO = 'info',
-  WARNING = 'warning',
-  DANGER = 'danger'
-}
-```
-
-## Dialog Component Contract
-
-The dialog component must expose `open()` using `defineExpose`:
-
-```vue
-<script setup lang="ts">
-import { type ConfirmDialogOptions } from '@blueprint-ts/core/vue'
-
-const props = defineProps<{ options: ConfirmDialogOptions }>()
-
-async function open(): Promise<boolean> {
-  // open dialog and resolve with true or false
-  return true
-}
-
-defineExpose({ open })
-</script>
-```
-
-## Mount Target
-
-`useConfirmDialog` accepts an optional second parameter to control where the dialog is mounted:
-
-```ts
-const { openConfirmDialog } = useConfirmDialog(ConfirmDialog, '#dialog-root')
-```

package/docs/vue/composables/use-global-checkbox.md

@@ -1,73 +0,0 @@
-# `useGlobalCheckbox`
-
-`useGlobalCheckbox` helps you implement “select all” behavior across a paginated data set. It manages:
-
-- selected rows
-- indeterminate/checked state
-- a dialog to choose between selecting the current page or all rows
-
-## Requirements
-
-- Call `useGlobalCheckbox` inside a `setup()` function.
-- Provide a dialog component that exposes an `open()` method via `defineExpose`.
-- `open()` must return a `Promise<boolean>`.
-- The dialog receives `checked` and `indeterminate` props.
-
-## Example
-
-```ts
-const { selectedRows, indeterminate, checked, handleGlobalCheckboxChange } =
-  useGlobalCheckbox<CredentialListResource>(BulkSelectDialog, {
-    getAll: async () => {
-      isLoadingAllElements.value = true
-
-      try {
-        const response = await request.withParams(buildParams()).send()
-        return response.getData()
-      } catch (error) {
-        console.error(error)
-        return []
-      } finally {
-        isLoadingAllElements.value = false
-      }
-    },
-    getPage: () => paginator.getPageData(),
-    totalCount: () => paginator.getTotal()
-  })
-```
-
-In the template, bind the handler to your global checkbox:
-
-```vue
-<input
-  type="checkbox"
-  :checked="checked"
-  :indeterminate="indeterminate"
-  @change="handleGlobalCheckboxChange"
-/>
-```
-
-## Dialog Component Contract
-
-Your dialog component should accept `checked` and `indeterminate` props and expose `open()`:
-
-```vue
-<script setup lang="ts">
-const props = defineProps<{ checked: boolean; indeterminate: boolean }>()
-
-async function open(): Promise<boolean> {
-  // true = select all entries, false = select current page / discard
-  return true
-}
-
-defineExpose({ open })
-</script>
-```
-
-## Mount Target
-
-You can pass a third argument to control where the dialog is mounted:
-
-```ts
-const { handleGlobalCheckboxChange } = useGlobalCheckbox(BulkSelectDialog, options, '#dialog-root')
-```

package/docs/vue/composables/use-is-empty.md

@@ -1,26 +0,0 @@
-# `useIsEmpty`
-
-`useIsEmpty` provides small helpers to check whether a value should be treated as empty.
-
-## What It Considers Empty
-
-- `undefined`, `null`, and `''`
-- arrays with `length === 0`
-- plain objects with no keys (checked via `lodash-es` `isEmpty`)
-
-Everything else is treated as not empty.
-
-## Example
-
-```ts
-import { useIsEmpty } from '@blueprint-ts/core/vue'
-
-const { isEmpty, isNotEmpty } = useIsEmpty()
-
-isEmpty(null) // true
-isEmpty('') // true
-isEmpty([]) // true
-isEmpty({}) // true
-
-isNotEmpty('Hello') // true
-```

package/docs/vue/composables/use-is-open-from-var.md

@@ -1,32 +0,0 @@
-# `useIsOpenFromVar`
-
-`useIsOpenFromVar` ties a “selected value” to open/close state. When `fromVar` is set to a non-empty value, `isOpenFromVar` becomes `true`. When the modal closes, `fromVar` resets after a delay so exit animations can finish.
-
-## Example
-
-```ts
-const { fromVar: selectedItem, isOpenFromVar: isDialogOpen, isOpenFromVarKey: dialogKey } =
-  useIsOpenFromVar<Resource>()
-```
-
-Use it like this:
-
-- set `selectedItem.value = item` to open the modal
-- set `isDialogOpen.value = false` to close and reset `fromVar`
-
-In the template:
-
-```vue
-<BulkEditDialog
-  :key="dialogKey"
-  v-model="isDialogOpen"
-  :item="selectedItem"
-/>
-```
-
-## Options
-
-`useIsOpenFromVar` accepts two optional parameters:
-
-- `defaultValue` (default `undefined`): value assigned to `fromVar` after close
-- `delay` (default `500`): delay in milliseconds before resetting `fromVar` and bumping `isOpenFromVarKey`, so exit animations can finish

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

@@ -1,28 +0,0 @@
-# `useIsOpen`
-
-`useIsOpen` manages a boolean open state and an `isOpenKey` that increments whenever the state is closed. This is useful for forcing re-mounts after a close animation.
-
-## Example
-
-```ts
-import { useIsOpen } from '@blueprint-ts/core/vue'
-
-const { isOpen, isOpenKey } = useIsOpen((value) => {
-  if (!value) {
-    // closed
-  }
-})
-```
-
-In a template, bind `isOpenKey` to force a re-mount when closing:
-
-```vue
-<Modal :key="isOpenKey" v-model="isOpen" />
-```
-
-## Options
-
-`useIsOpen` accepts two optional parameters:
-
-- `callback` (default `() => {}`): called whenever `isOpen` changes
-- `delay` (default `500`): delay in milliseconds before incrementing `isOpenKey` on close so exit animations can finish

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