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

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## v4.0.0-beta.1 - 2026-02-26 (beta)
+
+# [4.0.0-beta.1](/compare/v3.0.1...v4.0.0-beta.1) (2026-02-26)
+
+
+### Features
+
+* Added abortBatch to VueRequestBatchLoader; Improved documentation for loading 9701045
+* Added multiple exceptions; Improved request error handling docs a6e4559
+* Improved BaseForm fdda88c
+* Improved documentation for supprt and helpers; Moved helpers into support namespace f92edef
+* Improved Laravel docs; Removed obsolte code 415273c
+* Improved laravel documentation; Moved laravel code outside of service directory bb9a708
+* Improved pagination docs; Refactored paginator ee1b901
+* Improved state class ffe3b03
+* Removed service namespace and moved core items directly under core namespace 3def966
+* Updated docs and introduced minor changes 2d51524
+## v3.0.1 - 2026-02-21
+
+## [3.0.1](/compare/v3.0.0...v3.0.1) (2026-02-21)
 ## v3.0.0 - 2026-02-19
 
 # [3.0.0](/compare/v2.0.0...v3.0.0) (2026-02-19)

package/README.md

@@ -1 +1,25 @@
-Docs: https://hank-it.github.io/ui/latest
+# @blueprint-ts/core
+
+A core library for TypeScript projects, providing a robust foundation for building modern web applications. It offers a suite of utilities for form management, API requests, pagination, and seamless Vue integration.
+
+## Documentation
+
+Full documentation is available at [https://hank-it.github.io/blueprint-ts-core/](https://hank-it.github.io/blueprint-ts-core/).
+
+## Installation
+
+Install the package via npm:
+
+```bash
+npm i @blueprint-ts/core
+```
+
+Package details can be found on [npm](https://www.npmjs.com/package/@blueprint-ts/core).
+
+## Support
+
+Only the latest version of `@blueprint-ts/core` is supported. I recommend keeping your project updated to the latest version.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/docs/.vitepress/config.ts

@@ -1,10 +1,10 @@
 import { defineConfig } from 'vitepress'
 
 export default defineConfig({
-  title: '@hank-it/ui',
-  description: 'Documentation for the @hank-it/ui library',
+  title: '@blueprint-ts/core',
+  description: 'Documentation for the @blueprint-ts/core library',
 
-  base: process.env['DOCS_BASE'] || '/ui/latest/',
+  base: process.env['DOCS_BASE'] || '/blueprint-ts-core/',
 
   themeConfig: {
     sidebar: [
@@ -16,50 +16,107 @@ export default defineConfig({
         text: 'Services',
         collapsed: false,
         items: [
-          { text: 'Requests', link: '/services/requests' },
-          //{ text: 'Pagination', link: '/services/pagination' },
-          //{ text: 'Support', link: '/services/support' },
-          //{ text: 'Persistence Drivers', link: '/services/persistence-drivers' },
           {
-            text: 'Laravel Integration',
-            collapsed: true,
+            text: 'Requests',
+            items: [
+              { text: 'Getting Started', link: '/services/requests/getting-started' },
+              { text: 'Loading', link: '/services/requests/loading' },
+              { text: 'Drivers', link: '/services/requests/drivers' },
+              { text: 'Responses', link: '/services/requests/responses' },
+              { text: 'Request Bodies', link: '/services/requests/request-bodies' },
+              { text: 'Headers', link: '/services/requests/headers' },
+              { text: 'Aborting Requests', link: '/services/requests/abort-requests' },
+              { text: 'Events', link: '/services/requests/events' },
+              { text: 'Bulk Requests', link: '/services/requests/bulk-requests' },
+              { text: 'Error Handling', link: '/services/requests/error-handling' }
+            ]
+          },
+          {
+            text: 'Pagination',
+            items: [
+              { text: 'Overview', link: '/services/pagination/' },
+              { text: 'Page-Aware', link: '/services/pagination/page-aware' },
+              { text: 'Infinite Scroller', link: '/services/pagination/infinite-scroller' },
+              { text: 'State/Cursor', link: '/services/pagination/state-pagination' },
+              { text: 'Updating Rows', link: '/services/pagination/updating-rows' }
+            ]
+          },
+          {
+            text: 'Support',
             items: [
-              { text: 'Laravel Requests', link: '/services/laravel/requests' },
-              { text: 'Laravel Pagination', link: '/services/laravel/pagination' }
+              { text: 'Overview', link: '/services/support/' },
+              { text: 'Helpers', link: '/services/support/helpers' },
+              { text: 'DeferredPromise', link: '/services/support/deferred-promise' }
             ]
+          },
+          {
+            text: 'Persistence',
+            link: '/services/persistence/'
           }
         ]
       },
+      {
+        text: 'Laravel',
+        collapsed: false,
+        items: [
+          { text: 'Requests', link: '/laravel/requests' },
+          { text: 'Pagination', link: '/laravel/pagination' }
+        ]
+      },
       {
         text: 'Vue',
         collapsed: false,
         items: [
           { text: 'State', link: '/vue/state/' },
+          {
+            text: 'Composables',
+            items: [
+              { text: 'useConfirmDialog', link: '/vue/composables/use-confirm-dialog' },
+              { text: 'useGlobalCheckbox', link: '/vue/composables/use-global-checkbox' },
+              { text: 'useIsEmpty', link: '/vue/composables/use-is-empty' },
+              { text: 'useIsOpen', link: '/vue/composables/use-is-open' },
+              { text: 'useIsOpenFromVar', link: '/vue/composables/use-is-open-from-var' },
+              { text: 'useModelWrapper', link: '/vue/composables/use-model-wrapper' },
+              { text: 'useOnOpen', link: '/vue/composables/use-on-open' }
+            ]
+          },
           {
             text: 'Forms',
-            link: '/vue/forms'
+            items: [
+              { text: 'Overview', link: '/vue/forms/' },
+              { text: 'State And Properties', link: '/vue/forms/state-and-properties' },
+              { text: 'Validation', link: '/vue/forms/validation' },
+              { text: 'Building Payloads', link: '/vue/forms/payloads' },
+              { text: 'Errors', link: '/vue/forms/errors' },
+              { text: 'Persistence', link: '/vue/forms/persistence' },
+              { text: 'Arrays', link: '/vue/forms/arrays' },
+              { text: 'Utilities', link: '/vue/forms/utilities' }
+            ]
           },
           {
             text: 'Requests',
             items: [
-              /*{ text: 'Usage with Composition API', link: '/vue/requests/composition' },
-              { text: 'Loading States', link: '/vue/requests/loading' },
-              { text: 'Error Handling', link: '/vue/requests/errors' },*/
-              { text: 'Route Resource Binding', link: '/vue/requests/route-resource-binding' }
+              { text: 'Loading', link: '/vue/requests/loading' }
             ]
+          },
+          {
+            text: 'Router',
+            items: [{ text: 'Route Resource Binding', link: '/vue/router/route-resource-binding' }]
           }
         ]
-      }
-      /*{
-        text: 'Helpers',
+      },
+      {
+        text: 'Upgrading',
         items: [
-          { text: 'Utility Functions', link: '/helpers/' }
+          { text: 'v1 to v2', link: '/upgrading/v1-to-v2' },
+          { text: 'v2 to v3', link: '/upgrading/v2-to-v3' },
+          { text: 'v3 to v4', link: '/upgrading/v3-to-v4' }
         ]
-      }*/
+      }
     ],
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'GitHub', link: 'https://github.com/Hank-IT/ui' }
+      { text: 'GitHub', link: 'https://github.com/Hank-IT/blueprint-ts-core' }
     ]
   }
-})
+})

package/docs/index.md

@@ -1,70 +1,13 @@
 # Getting Started
 
-This library can be integrated with any frontend framework. It comes with built-in support for Vue 3, which is assumed
-throughout the documentation.
+This library may be integrated with any frontend framework. It comes with built-in support for Vue 3, which is assumed
+throughout the documentation. It also has features which are Vue-specific, such as form handling and validation.
 
 ````bash
-npm install @hank-it/ui --save
+npm install @blueprint-ts/core --save
 ````
 
-## Request Handling
+## Versioning
 
-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 '@hank-it/ui/service/requests' and initialize
-the driver as shown:
-
-```typescript
-import { BaseRequest, FetchDriver } from '@hank-it/ui/service/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')
-```
+Blueprint TS follows [Semantic Versioning](https://semver.org/). Upgrading from one major version to another may require
+some changes to your code, which will be documented in the Upgrading section of this documentation.

package/docs/{services/laravel → laravel}/pagination.md

@@ -1,11 +1,18 @@
 # Working with Laravel Pagination
 The `PaginationJsonBaseRequest` class extends the functionality to handle Laravel's pagination response format.
 
+## RequestDriver
+
+Use the Laravel `RequestDriver` to turn a `PaginationJsonBaseRequest` into a pagination data driver for the core
+paginator classes.
+
 ## Example: Paginated Users List
 
 ````typescript
-import { PaginationJsonBaseRequest } from '@hank-it/ui/service/laravel/requests'
-import { PaginationResponse } from '@hank-it/ui/service/laravel/requests/responses'
+import { PaginationJsonBaseRequest } from '@blueprint-ts/core/laravel/requests'
+import { PaginationResponse } from '@blueprint-ts/core/laravel/requests/responses'
+import { RequestDriver } from '@blueprint-ts/core/laravel/pagination'
+import { PageAwarePaginator } from '@blueprint-ts/core/pagination'
 
 export interface UserListParams {
   search?: string
@@ -38,17 +45,23 @@ And now we send the request using the paginator:
 ````typescript
 const request = new UserIndexRequest()
 
-const paginator = new Paginator(new RequestDriver(request))
+const paginator = new PageAwarePaginator(new RequestDriver(request))
 
 // Fetch the initial data
-paginator.init(1, 10)
+paginator.load(1)
 
 // Get current page data
 paginator.getPageData()
 
 // Change page
-paginator.setPageSize(value)
+await paginator.setPageSize(value).load()
 
 // Get current page size
 paginator.getPageSize()
-````
+````
+
+## Types
+
+For stricter typing, the Laravel pagination package also exports:
+
+- `PaginationResponseBodyContract` for the expected pagination response body shape

package/docs/{services/laravel → laravel}/requests.md

@@ -9,7 +9,7 @@ The `JsonBaseRequest` class is designed to work with Laravel's JSON responses, a
 We assume that Laravel's resources are used which output the requested data on the `data` json key.
 
 ````typescript
-import { JsonBaseRequest } from '@hank-it/ui/service/laravel/requests'
+import { JsonBaseRequest } from '@blueprint-ts/core/laravel/requests'
 
 export interface LaravelErrorResponse {
   message: string;
@@ -59,4 +59,4 @@ const request = new UserShowRequest()
 const response: JsonResponse<UserResource> = await request.send()
 
 const data: UserResource[] = response.getData()
-```
+```

package/docs/services/pagination/index.md

@@ -0,0 +1,46 @@
+# Pagination
+
+Pagination is built around three parts:
+
+1. **Data drivers** fetch pages and return a `PaginationDataDto`.
+2. **View drivers** store pagination state (page, size, total) and expose page data.
+3. **Paginators** orchestrate loading and state updates.
+
+## Drivers
+
+Pagination uses two kinds of drivers:
+
+- **Data drivers** fetch pages and return a `PaginationDataDto`.
+- **View drivers** store pagination state (page, size, total) and expose page data.
+
+You can implement your own drivers by following these contracts:
+
+- `PaginationDataDriverContract` or `StatePaginationDataDriverContract` for data drivers
+- `ViewDriverFactoryContract` or `BaseViewDriverFactoryContract` for view drivers
+
+If you are using Vue, the library provides `VuePaginationDriverFactory` and `VueBaseViewDriverFactory`.
+
+### Built-in Data Drivers
+
+- `ArrayDriver`: paginate an in-memory array.
+- `RequestDriver`: paginate using a request. See the Laravel pagination integration for usage details.
+
+## Paginators
+
+- [Page-Aware Pagination](./page-aware)
+- [Infinite Scroll](./infinite-scroller)
+- [State/Cursor Pagination](./state-pagination)
+
+## Load Options
+
+`load()` accepts `PaginatorLoadDataOptions`:
+
+- `flush`: clears existing data before applying the next page
+- `replace`: replaces existing data instead of appending (useful for infinite scroll)
+
+`updateRows` is available on all paginators. See [Updating Rows](./updating-rows).
+
+## Using Laravel Pagination
+
+If you use Laravel pagination responses, see the Laravel pagination docs for the `PaginationJsonBaseRequest` and
+`RequestDriver` integration.

package/docs/services/pagination/infinite-scroller.md

@@ -0,0 +1,19 @@
+# Infinite Scroll
+
+Use `InfiniteScroller` when you want to append pages to the existing list:
+
+```typescript
+import { InfiniteScroller } from '@blueprint-ts/core/pagination'
+
+const scroller = new InfiniteScroller(dataDriver, 1, 10)
+
+await scroller.load()
+await scroller.toNextPage()
+```
+
+`InfiniteScroller` uses the same view driver factory as `PageAwarePaginator`. You can pass `{ flush: true }` or
+`{ replace: true }` to `load()` or `setPageNumber()` to control how data is merged.
+
+## Scroll Detection Helper
+
+See the Support Helpers docs for `isAtBottom` usage.

package/docs/services/pagination/page-aware.md

@@ -0,0 +1,46 @@
+# Page-Aware Pagination
+
+Use `PageAwarePaginator` for classic page/size pagination. It requires a view driver factory:
+
+```typescript
+import { PageAwarePaginator, ArrayDriver, type ViewDriverFactoryContract } from '@blueprint-ts/core/pagination'
+
+class MyViewDriverFactory implements ViewDriverFactoryContract {
+    public make<ResourceInterface>(pageNumber: number, pageSize: number) {
+        // Return a ViewDriverContract<ResourceInterface[]> implementation.
+        throw new Error('Not implemented')
+    }
+}
+
+PageAwarePaginator.setViewDriverFactory(new MyViewDriverFactory())
+
+const dataDriver = new ArrayDriver(users)
+const paginator = new PageAwarePaginator(dataDriver, 1, 10)
+
+await paginator.load()
+
+const pageData = paginator.getPageData()
+const total = paginator.getTotal()
+const pages = paginator.getPages()
+```
+
+`dataDriver` must implement `PaginationDataDriverContract` and return a `PaginationDataDto`.
+If you are using Vue, the library provides `VuePaginationDriverFactory`.
+
+## Changing Page or Page Size
+
+`setPageNumber()` and `setPageSize()` only update state. Call `load()` to fetch data:
+
+```typescript
+await paginator.setPageNumber(2).load()
+
+await paginator.setPageSize(25).load()
+```
+
+Page navigation helpers (`toNextPage`, `toPreviousPage`, `toFirstPage`, `toLastPage`) update the page number and load
+the new page in one call.
+
+
+## Updating Rows
+
+`updateRows` is available on all paginators. See [Updating Rows](./updating-rows) for details.

package/docs/services/pagination/state-pagination.md

@@ -0,0 +1,77 @@
+# State/Cursor Pagination
+
+Use `StatePaginator` for cursor-based APIs that return a next-state token. It requires a base view driver factory:
+
+```typescript
+import { StatePaginator, type BaseViewDriverFactoryContract } from '@blueprint-ts/core/pagination'
+
+class MyBaseViewDriverFactory implements BaseViewDriverFactoryContract {
+    public make<ResourceInterface>() {
+        // Return a BaseViewDriverContract<ResourceInterface[]> implementation.
+        throw new Error('Not implemented')
+    }
+}
+
+StatePaginator.setViewDriverFactory(new MyBaseViewDriverFactory())
+
+const paginator = new StatePaginator(dataDriver)
+
+await paginator.load()
+await paginator.loadNext()
+```
+
+`dataDriver` must implement `StatePaginationDataDriverContract` and return a `StatePaginationDataDto`.
+If you are using Vue, the library provides `VueBaseViewDriverFactory`.
+
+## Example Driver
+
+```typescript
+import { type StatePaginationDataDriverContract, StatePaginationDataDto } from '@blueprint-ts/core/pagination'
+import { type MailListResource } from '@/types/MailListResource.ts'
+import { MailIndexRequest, type MailIndexRequestRequestParams } from '@/requests/MailIndexRequest.ts'
+import { RequestEvents } from '@blueprint-ts/core/requests'
+
+export class MailPaginationDataDriver implements StatePaginationDataDriverContract<MailListResource[]> {
+    public constructor(
+        protected accountId: string,
+        protected filters?: MailIndexRequestRequestParams['filter']
+    ) {}
+
+    public get(state?: string | null): Promise<StatePaginationDataDto<MailListResource[]>> {
+        const request = new MailIndexRequest(this.accountId)
+
+        request.setParams({
+            state: state || undefined,
+            filter: this.filters
+        })
+
+        return request
+            .send()
+            .then((response) => {
+                const data = response.getData() || []
+                const body = response.getBody() as unknown as { meta?: { state?: string; total?: number } }
+                const nextState = body.meta?.state || null
+                const total = body.meta?.total || data.length
+
+                return new StatePaginationDataDto(data, total, nextState)
+            })
+    }
+}
+
+const paginator = new StatePaginator(new MailPaginationDataDriver(props.accountId))
+
+function loadMails() {
+    paginator.flush()
+    paginator.load().catch((error) => {
+        console.error(error)
+    })
+}
+
+function loadMoreMails() {
+    if (!paginator.hasNextPage()) return
+
+    paginator.loadNext().catch((error) => {
+        console.error(error)
+    })
+}
+```

package/docs/services/pagination/updating-rows.md

@@ -0,0 +1,36 @@
+# Updating Rows
+
+All paginators (including `InfiniteScroller`) inherit `updateRows` from `BasePaginator`. It lets you update items in the
+current page data without reloading.
+
+## Usage
+
+`updateRows` accepts:
+
+- a predicate to select rows
+- an updater to mutate or replace them
+
+```typescript
+// Mark a single item as selected
+paginator.updateRows(
+    (row) => row.id === targetId,
+    (row) => {
+        row.selected = true
+    }
+)
+
+// Replace matching items with new objects
+paginator.updateRows(
+    (row) => row.status === 'draft',
+    (row) => ({ ...row, status: 'published' })
+)
+```
+
+It returns the number of rows updated:
+
+```typescript
+const updated = paginator.updateRows(
+    (row) => row.id === targetId,
+    (row) => ({ ...row, updatedAt: new Date().toISOString() })
+)
+```

package/docs/services/persistence/index.md

@@ -0,0 +1,46 @@
+# Persistence
+
+This service provides simple persistence drivers that implement a common `PersistenceDriver` interface. It is used by `BaseForm`, but can also be used directly.
+
+## Available Drivers
+
+- `NonPersistentDriver` — no persistence (default for `BaseForm`)
+- `SessionStorageDriver` — uses `sessionStorage`
+- `LocalStorageDriver` — uses `localStorage`
+
+All drivers are exported from `@blueprint-ts/core/persistenceDrivers`.
+
+## Using A Driver
+
+```ts
+import { LocalStorageDriver } from '@blueprint-ts/core/persistenceDrivers'
+
+const driver = new LocalStorageDriver('optional-suffix')
+
+driver.set('my-key', { value: 123 })
+const value = driver.get<{ value: number }>('my-key')
+```
+
+## Implementing A Custom Driver
+
+Implement the `PersistenceDriver` interface:
+
+```ts
+import { type PersistenceDriver } from '@blueprint-ts/core/persistenceDrivers'
+
+export class MemoryDriver implements PersistenceDriver {
+  private store = new Map<string, unknown>()
+
+  get<T>(key: string): T | null {
+    return (this.store.get(key) as T) ?? null
+  }
+
+  set<T>(key: string, state: T): void {
+    this.store.set(key, state)
+  }
+
+  remove(key: string): void {
+    this.store.delete(key)
+  }
+}
+```

package/docs/services/requests/abort-requests.md

@@ -0,0 +1,25 @@
+# Aborting Requests
+
+Requests can be aborted by passing an `AbortSignal` to the request.
+
+## Using AbortController
+
+```typescript
+const controller = new AbortController()
+
+const request = new ExpenseIndexRequest()
+  .setAbortSignal(controller.signal)
+
+const promise = request.send()
+
+// Later, when you want to abort:
+controller.abort()
+```
+
+## Bulk Requests
+
+`BulkRequestSender` internally manages an `AbortController` for its requests. You can abort the entire bulk operation:
+
+```typescript
+bulkRequestSenderInstance.abort()
+```