@blueprint-ts/core 3.0.0 → 4.0.0-beta.1

package/docs/services/support/deferred-promise.md

@@ -0,0 +1,63 @@
+# DeferredPromise
+
+`DeferredPromise` exposes a Promise along with `resolve`, `reject`, and a `state` property you can inspect.
+
+```typescript
+import { DeferredPromise } from '@blueprint-ts/core/support'
+
+const deferred = new DeferredPromise<string>()
+
+deferred.then((value) => {
+    console.log(value)
+})
+
+deferred.resolve('Done')
+```
+
+State values:
+
+- `pending`
+- `fulfilled`
+- `rejected`
+
+## Example: Defer Component Rendering
+
+Use a `DeferredPromise` to delay rendering of a Vue component until the slideover is opened and has received the props as non undefined:
+
+```vue
+<template>
+  <SlideOver v-model="isOpen">
+    <template v-if="resolvedresource">
+      <UpdateForm :options="options" :resource="resolvedresource" />
+    </template>
+  </SlideOver>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { DeferredPromise } from '@blueprint-ts/core/support'
+
+const props = defineProps<{ resource?: Resource }>()
+const isOpen = defineModel<boolean>('isOpen', { default: false })
+
+const readyPromise = new DeferredPromise<Resource>()
+const resolvedresource = ref<Resource>(undefined)
+let options: UpdateFormOptionsContract | undefined
+
+readyPromise.then((contract) => {
+  options = new UpdateFormOptions(contract)
+})
+
+onMounted(() => {
+  readyPromise.then((resource: Resource) => {
+      resolvedresource.value = resource
+  })
+})
+
+watch(isOpen, (open) => {
+  if (open && props.resource) {
+    readyPromise.resolve(props.resource)
+  }
+})
+</script>
+```

package/docs/services/support/helpers.md

@@ -0,0 +1,77 @@
+# 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

@@ -0,0 +1,6 @@
+# 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

@@ -0,0 +1,64 @@
+## 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

@@ -0,0 +1,52 @@
+## 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

@@ -0,0 +1,171 @@
+# 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.
+
+## 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
+  }
+}
+```
+
+## 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'
+```

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

@@ -0,0 +1,96 @@
+# `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

@@ -0,0 +1,73 @@
+# `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

@@ -0,0 +1,26 @@
+# `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

@@ -0,0 +1,32 @@
+# `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

@@ -0,0 +1,28 @@
+# `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