@blueprint-ts/core 1.0.0

package/docs/.vitepress/theme/components/VersionSelector.vue

@@ -0,0 +1,64 @@
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const versions = ref<string[]>([])
+const currentVersion = ref(getVersionFromPath() || 'latest')
+
+function getVersionFromPath() {
+  if (typeof window === 'undefined') return null
+  return window.location.pathname.split('/')[2] || 'latest'
+}
+
+// Modified to load versions.json from the correct path
+onMounted(async () => {
+  try {
+    // Use relative path to current location
+    const res = await fetch('./versions.json', { cache: 'no-store' })
+
+    if (!res.ok) {
+      throw new Error(`Failed to fetch versions: ${res.status}`)
+    }
+
+    versions.value = await res.json()
+  } catch (e) {
+    console.error('Failed to load versions:', e)
+    versions.value = ['latest']
+  }
+})
+
+function onSelect(event: Event) {
+  const selected = (event.target as HTMLSelectElement).value
+  // Preserve the path after the version segment
+  const pathParts = window.location.pathname.split('/')
+  const rest = pathParts.slice(3).join('/') // after /ui/<version>/
+  let newUrl = `/ui/${selected}/`
+  if (rest) newUrl += rest
+  newUrl += window.location.search + window.location.hash
+  window.location.href = newUrl
+}
+</script>
+
+<template>
+  <div class="version-selector">
+    <select :value="currentVersion" @change="onSelect" class="version-select">
+      <option v-for="ver in versions" :key="ver" :value="ver">{{ ver }}</option>
+    </select>
+  </div>
+</template>
+
+<style scoped>
+.version-selector {
+  display: inline-flex;
+  align-items: center;
+  margin-right: 0.5em;
+}
+
+.version-select {
+  padding: 0.25em 0.5em;
+  border-radius: 4px;
+  border: 1px solid var(--vp-c-divider);
+  background-color: var(--vp-c-bg);
+  color: var(--vp-c-text-1);
+  font-size: 0.9em;
+}
+</style>

package/docs/.vitepress/theme/index.js

@@ -0,0 +1,13 @@
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+import VersionSelector from './components/VersionSelector.vue'
+import Layout from './Layout.vue'
+
+export default {
+  extends: DefaultTheme,
+  Layout,
+  enhanceApp({ app }) {
+    // Register global components
+    app.component('VersionSelector', VersionSelector)
+  }
+}

package/docs/index.md

@@ -0,0 +1,70 @@
+# 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.
+
+````bash
+npm install @hank-it/ui --save
+````
+
+## 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 '@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')
+```

package/docs/services/laravel/pagination.md

@@ -0,0 +1,54 @@
+# Working with Laravel Pagination
+The `PaginationJsonBaseRequest` class extends the functionality to handle Laravel's pagination response format.
+
+## Example: Paginated Users List
+
+````typescript
+import { PaginationJsonBaseRequest } from '@hank-it/ui/service/laravel/requests'
+import { PaginationResponse } from '@hank-it/ui/service/laravel/requests/responses'
+
+export interface UserListParams {
+  search?: string
+  sort_by?: string
+  sort_direction?: 'asc' | 'desc'
+  page?: number
+  per_page?: number
+}
+
+// Paginated GET request to list users
+export class UserIndexRequest extends PaginationJsonBaseRequest<
+  boolean, // Loading indicator type
+  LaravelErrorResponse, // Laravel-style error response
+  UserResource, // The resource type being paginated
+  undefined, // No request body for GET
+  UserListParams // Query parameters including pagination
+> {
+  public method(): RequestMethodEnum {
+    return RequestMethodEnum.GET
+  }
+
+  public url(): string {
+    return '/api/users'
+  }
+}
+````
+
+And now we send the request using the paginator:
+
+````typescript
+const request = new UserIndexRequest()
+
+const paginator = new Paginator(new RequestDriver(request))
+
+// Fetch the initial data
+paginator.init(1, 10)
+
+// Get current page data
+paginator.getPageData()
+
+// Change page
+paginator.setPageSize(value)
+
+// Get current page size
+paginator.getPageSize()
+````

package/docs/services/laravel/requests.md

@@ -0,0 +1,62 @@
+# Laravel Request Integration
+The Laravel integration provides specialized request classes that work seamlessly with Laravel backend APIs, handling common Laravel-specific response formats and features like pagination.
+
+## Using JsonBaseRequest
+The `JsonBaseRequest` class is designed to work with Laravel's JSON responses, automatically handling content negotiation and response parsing. 
+
+### Example: User API Request
+
+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'
+
+export interface LaravelErrorResponse {
+  message: string;
+  errors?: Record<string, string[]>
+}
+
+export interface UserResource {
+  id: number
+  name: string
+  email: string
+  created_at: string
+}
+
+export interface UserRequestParams {
+  include?: string[]
+}
+
+// Simple GET request to fetch a user
+export class UserShowRequest extends JsonBaseRequest<
+  boolean, // Loading indicator type
+  LaravelErrorResponse, // Laravel-style error response
+  UserResource, // Response data structure
+  undefined, // No request body for GET
+  UserRequestParams // Query parameters
+> {
+  constructor(private userId: number) {
+    super()
+  }
+
+  public method(): RequestMethodEnum {
+    return RequestMethodEnum.GET
+  }
+
+  public url(): string {
+    return `/api/users/${this.userId}`
+  }
+}
+````
+
+## Sending the Request
+
+Once the request is defined, you can send it using the following code:
+
+```typescript
+const request = new UserShowRequest()
+
+const response: JsonResponse<UserResource> = await request.send()
+
+const data: UserResource[] = response.getData()
+```

package/docs/services/requests/index.md

@@ -0,0 +1,74 @@
+# Defining Requests
+
+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.
+
+## 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 '@hank-it/ui/service/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
+```
+
+This completes the setup and usage of the request driver and custom requests. You can now use these patterns to create additional requests as needed.

package/docs/vue/forms.md

@@ -0,0 +1,326 @@
+# BaseForm Documentation
+
+## Overview
+
+`BaseForm` is a powerful and flexible TypeScript class for handling form state, validation, and submission in Vue
+applications. It provides a comprehensive solution for managing form data with features like:
+
+- Type-safe form state management
+- Dirty state tracking for individual fields
+- Error handling and field validation
+- Form persistence between page reloads
+- Support for complex nested objects and arrays
+- Automatic transformation of form values to API payloads
+
+## Key Features
+
+### 1. Type-Safe Form Management
+
+The `BaseForm` is a generic class that takes two type parameters:
+
+- `RequestBody`: The shape of the data that will be sent to the server
+- `FormBody`: The shape of the form's internal state, which can differ from the request payload
+
+````typescript
+class MyForm extends BaseForm<MyRequestPayload, MyFormState> {
+    // ...
+}
+````
+
+### 2. Form State Persistence
+
+Forms can automatically save their state to browser storage (session, local, etc.), allowing users to navigate away and
+return without losing their input.
+
+````typescript
+protected override getPersistenceDriver(): PersistenceDriver
+{
+    return new SessionStorageDriver() // Or LocalStorageDriver, etc.
+}
+````
+
+### 3. Transformations and Getters
+
+Transform form values before they are sent to the server using getter methods:
+
+````typescript
+protected getStartedAt(): string {
+    return DateTime.fromFormat(`${this.state.start_date} ${this.state.start_time}`, 'dd.MM.yyyy HH:mm').toISO()
+}
+````
+
+### 4. Error Handling and Validation
+
+Map server-side validation errors to specific form fields, with support for nested fields:
+
+````typescript
+protected override errorMap: { [serverKey: string]: string | string[] } = {
+    started_at: ['start_date', 'start_time'],
+    ended_at: ['end_date', 'end_time']
+}
+````
+
+### 5. Array Management
+
+Special support for arrays with the class `PropertyAwareArray`, enabling reactive updates to array items:
+
+````typescript
+public addPosition(): void {
+    this.addToArrayProperty('positions', {
+        index: this.properties.positions.length + 1,
+        gross_amount: null,
+        vat_rate: VatRateEnum.VAT_RATE_19,
+        booking_account_category_id: null
+    })
+}
+````
+
+## Core Concepts
+
+### State and Dirty Tracking
+
+`BaseForm` tracks the original state and current state of each form field, automatically computing "dirty" status for
+fields that have been changed.
+
+````typescript
+// Check if any field in the form has been modified
+form.isDirty()
+````
+
+### The Properties Object
+
+The `properties` getter provides access to each form field with its model, errors, and dirty status:
+
+````html
+
+<template>
+    <input v-model="form.properties.email.model.value" />
+    <div v-if="form.properties.email.dirty">This field has been changed</div>
+    <div v-if="form.properties.email.errors.length">{{ form.properties.email.errors[0] }}</div>
+</template>
+````
+
+### Form Submission
+
+Build a payload for API submission with:
+
+````typescript
+const payload = form.buildPayload()
+````
+
+## How to Use
+
+### 1. Create a Form Class
+
+````typescript
+import { BaseForm, type PersistenceDriver, SessionStorageDriver } from '@hank-it/ui/vue/forms'
+
+interface MyFormState {
+    name: string
+    email: string
+}
+
+interface MyRequestPayload {
+    name: string
+    email: string
+    timestamp: string // Added field not in the form
+}
+
+class MyForm extends BaseForm<MyRequestPayload, MyFormState> {
+    // Fields to add to the final payload that aren't in the form state
+    protected override append: string[] = ['timestamp']
+
+    // Fields to exclude from the final payload
+    protected override ignore: string[] = []
+
+    // Map server error keys to form field names
+    protected override errorMap: { [serverKey: string]: string | string[] } = {}
+
+    public constructor() {
+        super({
+          name: '',
+          email: ''
+        }, { persist: true, persistSuffix: 'optional-suffix' })
+    }
+
+    // Use session storage for persistence
+    protected override getPersistenceDriver(): PersistenceDriver {
+        return new SessionStorageDriver()
+    }
+
+    // Generate a timestamp for the request
+    protected getTimestamp(): string {
+        return new Date().toISOString()
+    }
+}
+````
+
+### 2. Use in Components
+
+````vue
+<template>
+  <form @submit.prevent="submitForm">
+    <div>
+      <label>Name</label>
+      <input v-model="form.properties.name.model.value" />
+      <div v-if="form.properties.name.errors.length" class="error">
+        {{ form.properties.name.errors[0] }}
+      </div>
+    </div>
+    
+    <div>
+      <label>Email</label>
+      <input v-model="form.properties.email.model.value" />
+      <div v-if="form.properties.email.errors.length" class="error">
+        {{ form.properties.email.errors[0] }}
+      </div>
+    </div>
+    
+    <button type="submit" :disabled="!form.isDirty()">Submit</button>
+    <button type="button" @click="form.reset()">Reset</button>
+  </form>
+</template>
+
+<script setup>
+import { MyForm } from './MyForm'
+
+const form = new MyForm({
+  name: '',
+  email: ''
+})
+
+async function submitForm() {
+  try {
+    const payload = form.buildPayload()
+    await api.submitForm(payload)
+    // Success handling
+  } catch (error) {
+    if (error.response?.data?.errors) {
+      form.fillErrors(error.response.data.errors)
+    }
+  }
+}
+</script>
+````
+
+## Working with Arrays
+The `PropertyAwareArray` class enables special handling for array items. Each value of objects in the PropertyAwareArray will receive a v-model, errors, etc.:
+
+````typescript
+import { BaseForm, PropertyAwareArray } from '@hank-it/ui/vue/forms'
+
+export interface FormWithPositions {
+  // ...other fields
+  positions: PositionItem[]
+}
+
+export class MyComplexForm extends BaseForm<RequestType, FormWithPositions> {
+  constructor() {
+    super({
+      // ...other defaults
+      positions: new PropertyAwareArray([
+        { id: 1, value: '' }
+      ])
+    })
+  }
+  
+  // Add a new position to the array
+  public addPosition(): void {
+    this.addToArrayProperty('positions', {
+      id: this.properties.positions.length + 1,
+      value: ''
+    })
+  }
+  
+  // Remove a position by id
+  public removePosition(id: number): void {
+    this.state.positions = new PropertyAwareArray(
+      this.state.positions.filter(position => position.id !== id)
+    )
+    this.resetPositionIds()
+  }
+  
+  // Reset the sequential IDs after removing items
+  protected resetPositionIds(): void {
+    let count = 1
+    this.state.positions.forEach(position => {
+      position.id = count
+      count++
+    })
+  }
+}
+
+const form = new MyComplexForm()
+const id = form.properties.positions[0].id.model.value
+````
+
+## Advanced Features
+### 1. Form Reset
+Revert all changes to the original state:
+
+````typescript
+form.reset()
+````
+
+### 2. Error Handling
+Fill form with validation errors from a server response:
+
+````typescript
+try {
+  await submitForm(form.buildPayload())
+} catch (error) {
+  form.fillErrors(error.response.data.errors)
+}
+````
+
+The `fileErrors` method currently only supports the Laravel style dot notation errors.
+
+### 3. Filling Form State
+Update multiple form fields at once, preserving the dirty state:
+
+````typescript
+form.fillState({
+  name: 'John Doe',
+  email: 'john@example.com'
+})
+````
+
+### 4. Synchronizing Values Without Marking Dirty
+Update both the current and original state, keeping the field "clean":
+
+````typescript
+form.syncValue('email', 'new@example.com')
+````
+
+## Real-World Examples
+### 1. Date/Time Handling
+
+````typescript
+export class TimeTrackingEntryCreateUpdateForm extends BaseForm<RequestPayload, FormState> {
+  protected override append: string[] = ['started_at', 'ended_at']
+  protected override ignore: string[] = ['start_date', 'start_time', 'end_date', 'end_time']
+  
+  protected getStartedAt(): string {
+    return DateTime.fromFormat(`${this.state.start_date} ${this.state.start_time}`, 'dd.MM.yyyy HH:mm').toISO()
+  }
+  
+  protected getEndedAt(): string {
+    return DateTime.fromFormat(`${this.state.end_date} ${this.state.end_time}`, 'dd.MM.yyyy HH:mm').toISO()
+  }
+}
+````
+
+### 2. Complex Object Handling
+
+````typescript
+export class IncomingVoucherCreateUpdateForm extends BaseForm<RequestPayload, FormState> {
+  // Extract IDs from related objects
+  protected getBusinessAssociateId(value: BusinessAssociateResource): string | null {
+    return value?.id
+  }
+  
+  protected getFileId(value: FileResource): string | null {
+    return value?.id
+  }
+}
+````