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

package/docs/services/support/helpers.md

@@ -1,77 +0,0 @@
-# Helpers
-
-## isAtBottom
-
-Detect whether a scroll container is at the bottom:
-
-```typescript
-import { isAtBottom } from '@blueprint-ts/core/support'
-
-const atBottom = isAtBottom(scrollHeight, scrollTop, clientHeight)
-```
-
-Example with a scroll container:
-
-```html
-<nav class="overflow-y-auto" @scroll="handleScroll">
-  <!-- content -->
-</nav>
-```
-
-```typescript
-import { isAtBottom } from '@blueprint-ts/core/support'
-
-function handleScroll(event: Event): void {
-    if (!(event.target instanceof Element)) {
-        return
-    }
-
-    const atBottom = isAtBottom(event.target.scrollHeight, event.target.scrollTop, event.target.clientHeight)
-
-    if (atBottom) {
-        loadMore()
-    }
-}
-```
-
-## getCookie
-
-Read a cookie value by name:
-
-```typescript
-import { getCookie } from '@blueprint-ts/core/support'
-
-const token = getCookie('XSRF-TOKEN')
-```
-
-## isObject
-
-Check if a value is a non-array object:
-
-```typescript
-import { isObject } from '@blueprint-ts/core/support'
-
-if (isObject(value)) {
-    // value is an object (not null, not an array)
-}
-```
-
-## mergeDeep
-
-Deep-merge plain objects:
-
-```typescript
-import { mergeDeep } from '@blueprint-ts/core/support'
-
-const result = mergeDeep({}, defaults, overrides)
-```
-
-## getDisplayablePages
-
-Generate a window of page numbers for pagination UI:
-
-```typescript
-import { getDisplayablePages } from '@blueprint-ts/core/support'
-
-const pages = getDisplayablePages(currentPage, totalPages, displayPages)
-```

package/docs/services/support/index.md

@@ -1,6 +0,0 @@
-# Support
-
-The Support utilities include helper functions and small primitives used across the library.
-
-- [Helpers](./helpers)
-- [DeferredPromise](./deferred-promise)

package/docs/upgrading/v1-to-v2.md

@@ -1,64 +0,0 @@
-## Upgrading from v1 to v2
-
-### Route Resource Binding
-
-Commit `db70b77` introduced significant changes to the route resource binding system to support better caching, parent-to-child inheritance, and non-blocking navigation.
-
-#### Non-blocking Navigation (Breaking Change)
-
-In v1, navigation was blocked until all resources were resolved in the `beforeResolve` guard. In v2, navigation proceeds immediately, and resources are loaded in the background.
-
-This means that your components will now render **before** the resources are available (they will be `undefined` initially).
-
-**How to upgrade:**
-
-1.  **Use `RouteResourceBoundView`**: Replace `<RouterView>` with `<RouteResourceBoundView>`. This component automatically manages loading and error states for you.
-    ```vue
-    <script setup lang="ts">
-    import { RouteResourceBoundView } from '@blueprint-ts/core'
-    </script>
-
-    <template>
-      <RouteResourceBoundView />
-    </template>
-    ```
-
-2.  **Define Loading/Error Components**: You can now define these directly in your `defineRoute` call to be used by `RouteResourceBoundView`:
-    ```ts
-    defineRoute<{ product: ProductResource }>()({
-        path: ':productId',
-        component: ProductDetailPage,
-        loadingComponent: MyLoadingSpinner,
-        errorComponent: MyErrorPage,
-        inject: {
-            product: { from: 'productId', resolve: ... }
-        }
-    })
-    ```
-
-3.  **Manual Handling**: If you want your component to handle its own loading state, set `lazy: false` in the route definition and use the updated `useRouteResource` composable.
-
-#### `useRouteResource` API Changes (Breaking Change)
-
-The `useRouteResource` composable has been updated to support multiple resources and provide reactive state.
-
-*   **v1**: `const { refresh } = useRouteResource()`
-*   **v2**: `const { refresh, isLoading, error } = useRouteResource('resourceName')`
-
-The `refresh` function no longer takes the resource name as an argument. It now accepts an optional options object for silent refreshes.
-
-```ts
-// v1
-const { refresh } = useRouteResource()
-await refresh('product')
-
-// v2
-const { refresh, isLoading, error } = useRouteResource('product')
-await refresh() // Triggers loading state
-await refresh({ silent: true }) // Background refresh
-```
-
-#### New Features: Caching and Inheritance
-
-*   **Caching**: Resources are now cached based on the route parameter value. Navigating between child routes that share the same parameter will no longer trigger redundant requests.
-*   **Inheritance**: Child routes now automatically inherit resources defined on parent routes. You can define a resource once on a parent route and it will be available to all children through props or `useRouteResource`.

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

@@ -1,52 +0,0 @@
-## Upgrading from v2 to v3
-
-### BaseForm
-
-#### Omission of fields with `undefined` values (Breaking Change)
-
-Commit `26c0d0e` changed how `BaseForm.buildPayload()` handles `undefined` values returned by transformers (getters).
-
-In v2, returning `undefined` from a getter would still include the key in the resulting payload object. In v3, the field is **omitted** entirely from the payload.
-
-This applies to:
-- **Field Getters**: `getFieldName(value)`
-- **Composite Getters**: `getParentFieldNestedField(value)`
-- **Appended Fields**: Getters for fields defined in the `append` array.
-- **Nested Objects/Arrays**: Recursive transformation of nested data structures.
-
-**How to upgrade:**
-If you previously relied on a field being present with an `undefined` value in the JS object, you should now return `null` if you want the field to be included in the request payload.
-
-```ts
-// v2: payload was { name: undefined }
-// v3: payload is {}
-protected getName(value: string) {
-  return value ? value : undefined
-}
-
-// v3: if you want the field to be included
-protected getName(value: string) {
-  return value ? value : null // payload is { name: null }
-}
-```
-
-#### Removal of Suggestions (Breaking Change)
-
-The suggestions feature has been removed from `BaseForm` in commit `f21d6ce`.
-
-**Changes:**
-- Removed `fillSuggestions()` method from `BaseForm`.
-- Removed `suggestions` property from the `properties` tree (e.g., `form.properties.email.suggestions` is no longer available).
-- Removed `suggestions` from `PropertyAwareField` and `PropertyAware` types.
-
-**How to upgrade:**
-If you were using the suggestions feature, you should now manage suggestions independently of the form state, for example, by using a separate reactive object or a dedicated composable.
-
-#### File Upload Support and Form Data Handling
-
-Commit `d765cae` introduced native support for `File` and `Blob` objects in `BaseForm`.
-
-**Changes:**
-- `BaseForm` now detects if the payload contains `File` or `Blob` objects.
-- When sending a request with a `File` or `Blob` in the payload, the library will automatically use `FormData` and set the appropriate `Content-Type` header (multipart/form-data).
-- `File` values are kept intact during the transformation process and are not converted into plain objects.

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