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

package/docs/services/requests/getting-started.md

@@ -1,201 +0,0 @@
-# Getting Started
-
-Each API endpoint is represented as a separate class that extends `BaseRequest`. This class specifies the HTTP Method,
-URL, and the expected request/response types.
-
-## Request Handling
-
-The library leverages a fetch-based driver to perform HTTP requests. The following sections explain how to initialize
-the request driver and define custom requests.
-
-## Initializing the Request Driver
-
-Before making any requests, you must initialize the appropriate request driver. This is done during your application's
-boot process by using the static `setRequestDriver` method.
-
-### Using the Fetch Driver
-
-To set up the fetch driver, import `BaseRequest` and `FetchDriver` from '@blueprint-ts/core/requests' and initialize
-the driver as shown:
-
-```typescript
-import { BaseRequest, FetchDriver } from '@blueprint-ts/core/requests'
-
-BaseRequest.setRequestDriver(new FetchDriver())
-```
-
-### Enabling Credential Support
-
-If your requests need to include credentials (e.g., cookies for cross-origin requests), enable credential support as
-follows:
-
-```typescript
-BaseRequest.setRequestDriver(new FetchDriver({
-    corsWithCredentials: true,
-}))
-```
-
-### Adding Global Headers
-
-To include headers such as a CSRF token with every request, define them globally:
-
-```typescript
-BaseRequest.setRequestDriver(new FetchDriver({
-    headers: {
-        'X-XSRF-TOKEN': "<token>",
-    },
-}))
-```
-
-Sometimes you want to refetch the header when the request is sent. You may specify a callback for this:
-
-```typescript
-BaseRequest.setRequestDriver(new FetchDriver({
-    headers: {
-        'X-XSRF-TOKEN': () => getCookie('XSRF-TOKEN')
-    },
-}))
-```
-
-### Specifying a Base URL
-
-In case your backend lives on a separate domain, you may specify a default base url, which is prepended to every request url:
-
-```typescript
-BaseRequest.setDefaultBaseUrl('https://example.com')
-```
-
-## Example: Expense Index Request
-
-The following example demonstrates how to define a GET request to the `/api/v1/expenses` endpoint:
-
-```typescript
-import { BaseRequest, RequestMethodEnum, JsonResponse } from '@blueprint-ts/core/requests'
-
-export interface GenericResponseErrorInterface {
-    message: string
-}
-
-export interface ExpenseIndexRequestParams {
-    filter?: {
-        search_text?: string
-    };
-}
-
-export interface ExpenseResource {
-    id: string;
-    // other data fields
-}
-
-export interface ExpenseIndexRequestResponseBody {
-    data: ExpenseResource[]
-}
-
-export class ExpenseIndexRequest extends BaseRequest<
-        boolean, // Generic RequestLoaderLoadingType
-        GenericResponseErrorInterface, // Generic ResponseErrorBody
-        ExpenseIndexRequestResponseBody, // Generic ResponseBodyInterface
-        JsonResponse<ExpenseIndexRequestResponseBody>, // Generic ResponseClass
-        undefined, // Generic RequestBodyInterface
-        ExpenseIndexRequestParams // RequestParamsInterface
-> {
-    public method(): RequestMethodEnum {
-        return RequestMethodEnum.GET
-    }
-
-    public url(): string {
-        return '/api/v1/expenses'
-    }
-}
-```
-
-### Explanation
-
-- **HTTP Method**: Uses `GET` to retrieve data from the `/api/v1/expenses` endpoint.
-- **Error Handling**: On failure (4XX/5XX status codes), the response will conform to `GenericResponseErrorInterface`.
-- **Success Response**: A successful response is expected to follow the `ExpenseIndexRequestResponseBody` interface.
-- **Response Format**: The response is of type JSON, as indicated by `JsonResponse`.
-- **Request Body**: Since this is a GET request, the body is `undefined`.
-- **Query Parameters**: Accepts query parameters that match the `ExpenseIndexRequestParams` interface.
-
-### Sending the Request
-
-Once the request is defined, you can send it using the following code:
-
-```typescript
-const request = new ExpenseIndexRequest()
-
-// The response type and body are inferred automatically.
-const response: JsonResponse<ExpenseIndexRequestResponseBody> = await request.send()
-
-const body = response.getBody() // Type: ExpenseIndexRequestResponseBody
-```
-
-## Example: Create Expense Request (POST)
-
-This example demonstrates a POST request that sends a JSON body by overriding `getRequestBodyFactory()`:
-
-```typescript
-import {
-    BaseRequest,
-    RequestMethodEnum,
-    JsonResponse,
-    JsonBodyFactory
-} from '@blueprint-ts/core/requests'
-
-export interface CreateExpensePayload {
-    title: string
-    amount: number
-}
-
-export interface CreateExpenseResponseBody {
-    id: string
-}
-
-export class CreateExpenseRequest extends BaseRequest<
-        boolean,
-        GenericResponseErrorInterface,
-        CreateExpenseResponseBody,
-        JsonResponse<CreateExpenseResponseBody>,
-        CreateExpensePayload
-> {
-    public method(): RequestMethodEnum {
-        return RequestMethodEnum.POST
-    }
-
-    public url(): string {
-        return '/api/v1/expenses'
-    }
-
-    public getResponse(): JsonResponse<CreateExpenseResponseBody> {
-        return new JsonResponse<CreateExpenseResponseBody>()
-    }
-
-    public override getRequestBodyFactory() {
-        return new JsonBodyFactory<CreateExpensePayload>()
-    }
-}
-```
-
-### Explanation
-
-- **HTTP Method**: Uses `POST` to create a new expense.
-- **Error Handling**: On failure (4XX/5XX status codes), the response will conform to `GenericResponseErrorInterface`.
-- **Success Response**: A successful response is expected to follow the `CreateExpenseResponseBody` interface.
-- **Response Format**: The response is of type JSON, as indicated by `JsonResponse`.
-- **Request Body**: Uses `JsonBodyFactory` to send JSON with `Content-Type: application/json`.
-
-### Sending the Request
-
-```typescript
-const request = new CreateExpenseRequest()
-
-const response = await request.setBody({
-    title: 'Office supplies',
-    amount: 42
-}).send()
-
-const body = response.getBody() // Type: CreateExpenseResponseBody
-```
-
-Note: If you use Laravel or an API that wraps payloads under a `data` key, consider using `JsonBaseRequest` from the Laravel integration.

package/docs/services/requests/headers.md

@@ -1,40 +0,0 @@
-# Headers
-
-Requests assemble headers from multiple sources before sending:
-
-1. **Driver defaults** (global headers set on the driver)
-2. **Request headers** returned by `requestHeaders()`
-3. **Body headers** from the request body factory (e.g., `Content-Type`)
-
-Later sources override earlier ones. Header values can be strings or callbacks that resolve at send time.
-
-## Global Headers (Driver)
-
-Set headers once when you configure the driver:
-
-```typescript
-BaseRequest.setRequestDriver(new FetchDriver({
-    headers: {
-        'X-XSRF-TOKEN': () => getCookie('XSRF-TOKEN')
-    },
-}))
-```
-
-## Per-Request Headers
-
-Override `requestHeaders()` on a request to add headers per request:
-
-```typescript
-import { type HeadersContract } from '@blueprint-ts/core/requests'
-
-public override requestHeaders(): HeadersContract {
-    return {
-        Authorization: `Bearer ${this.accessToken}`
-    }
-}
-```
-
-## Body Headers
-
-Request body factories can set headers such as `Content-Type`. For example, `JsonBodyFactory` sets
-`Content-Type: application/json`.

package/docs/services/requests/loading.md

@@ -1,63 +0,0 @@
-# Loading
-
-Requests can expose loading state through a request loader. You register a loader factory once, and each `BaseRequest`
-instance will ask the factory for a loader.
-
-Note: For Vue apps, the library provides `VueRequestLoader` and `VueRequestLoaderFactory` in `@blueprint-ts/core/vue/requests`.
-
-## Registering a Loader Factory
-
-Use `BaseRequest.setRequestLoaderFactory()` to register a factory that implements `RequestLoaderFactoryContract` and
-returns a `RequestLoaderContract`:
-
-```typescript
-import {
-    BaseRequest,
-    type RequestLoaderContract,
-    type RequestLoaderFactoryContract
-} from '@blueprint-ts/core/requests'
-
-class BooleanLoader implements RequestLoaderContract<boolean> {
-    private loading = false
-
-    public isLoading(): boolean {
-        return this.loading
-    }
-
-    public setLoading(value: boolean): void {
-        this.loading = value
-    }
-}
-
-class BooleanLoaderFactory implements RequestLoaderFactoryContract<boolean> {
-    public make(): RequestLoaderContract<boolean> {
-        return new BooleanLoader()
-    }
-}
-
-BaseRequest.setRequestLoaderFactory(new BooleanLoaderFactory())
-```
-
-## Reading Loading State
-
-Once a loader factory is registered, every request created from `BaseRequest` can read loading state:
-
-```typescript
-const request = new ExpenseIndexRequest()
-
-request.send()
-
-const isLoading = request.isLoading()
-```
-
-## Override Loader
-
-You can override the loader per request with `setRequestLoader`:
-
-```typescript
-const request = new ExpenseIndexRequest()
-
-request.setRequestLoader(customLoader)
-```
-
-This lets you create or share a loader before the request exists, which is useful when loading state must be wired up ahead of time.

package/docs/services/requests/request-bodies.md

@@ -1,61 +0,0 @@
-# Request Bodies
-
-Request body factories control how outgoing request bodies are serialized and which `Content-Type` header is sent.
-They are separate from response parsing (response classes control `Accept` and how the response body is parsed).
-
-## How It Works
-
-When you call `send()`, `BaseRequest` uses the request body factory to build a `BodyContract`:
-
-- `getRequestBodyFactory()` returns a `BodyFactoryContract`
-- `BodyFactoryContract.make()` returns a `BodyContract`
-- `BodyContract.getHeaders()` provides headers (like `Content-Type`)
-- `BodyContract.getContent()` provides the serialized body
-
-If you call `setBody(...)` without providing a body factory, the body is not sent.
-
-## JSON Bodies
-
-Use `JsonBodyFactory` to send JSON and set `Content-Type: application/json`:
-
-```typescript
-import { BaseRequest, JsonBodyFactory, RequestMethodEnum } from '@blueprint-ts/core/requests'
-
-class CreateExpenseRequest extends BaseRequest<boolean, GenericResponseErrorInterface, ExpenseResource, JsonResponse<ExpenseResource>, CreateExpensePayload> {
-    public method(): RequestMethodEnum {
-        return RequestMethodEnum.POST
-    }
-
-    public url(): string {
-        return '/api/v1/expenses'
-    }
-
-    public getResponse(): JsonResponse<ExpenseResource> {
-        return new JsonResponse<ExpenseResource>()
-    }
-
-    public override getRequestBodyFactory() {
-        return new JsonBodyFactory<CreateExpensePayload>()
-    }
-}
-```
-
-If you are using the Laravel integration, `JsonBaseRequest` already configures the JSON body factory for you.
-
-## FormData Bodies
-
-Use `FormDataFactory` for multipart requests (uploads, mixed fields):
-
-```typescript
-import { FormDataFactory } from '@blueprint-ts/core/requests'
-
-public override getRequestBodyFactory() {
-    return new FormDataFactory<FormPayload>()
-}
-```
-
-If you want to show upload progress for multipart file uploads, see [File Uploads](/services/requests/file-uploads).
-
-## Custom Body Factories
-
-You can implement your own body factory by returning a `BodyContract` with custom headers and serialization logic.

package/docs/services/requests/responses.md

@@ -1,34 +0,0 @@
-# Responses
-
-Requests return a response class that controls the `Accept` header and how the body is parsed.
-
-## JsonResponse
-
-Use `JsonResponse<T>` for JSON APIs. It sets `Accept: application/json` and parses the body with `response.json()`:
-
-```typescript
-import { JsonResponse } from '@blueprint-ts/core/requests'
-
-// In your request generic parameters:
-// JsonResponse<ExpenseIndexRequestResponseBody>
-```
-
-## PlainTextResponse
-
-Use `PlainTextResponse` for endpoints that return plain text. It sets `Accept: text/plain` and parses the body with
-`response.text()`:
-
-```typescript
-import { PlainTextResponse } from '@blueprint-ts/core/requests'
-```
-
-## BlobResponse
-
-Use `BlobResponse` for binary responses like files. It sets `Accept` to the provided MIME type (default
-`application/octet-stream`) and parses the body with `response.blob()`:
-
-```typescript
-import { BlobResponse } from '@blueprint-ts/core/requests'
-
-const response = new BlobResponse('application/pdf')
-```

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

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

@@ -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.