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

package/docs/vue/forms.md

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

package/examples/index.html

@@ -1,14 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" class="h-full">
-<head>
-    <meta charset="UTF-8">
-    <title>Hank-IT UI</title>
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-</head>
-<body class="h-full">
-
-<div id="app" class="w-full h-full"></div>
-
-<script type="module" src="/js/app.js"></script>
-</body>
-</html>

package/examples/js/app.js

@@ -1,8 +0,0 @@
-import { createApp } from 'vue'
-import App from './view/App.vue'
-import Router from './router'
-
-const app = createApp(App)
-    .use(Router)
-
-app.mount('#app')

package/examples/js/router.js

@@ -1,22 +0,0 @@
-import { createWebHistory, createRouter } from 'vue-router'
-
-const routes = [
-    {
-        path: '/pagination/:component?',
-        component: () => import('@view/pagination/Pagination.vue'),
-        name: 'pagination',
-        props: true,
-    },
-    {
-        path: '/requests/:component?',
-        component: () => import('@view/requests/Requests.vue'),
-        name: 'requests',
-        props: true,
-    }
-]
-
-
-export default createRouter({
-    history: createWebHistory(),
-    routes, // short for `routes: routes`,
-})

package/examples/js/view/App.vue

@@ -1,49 +0,0 @@
-<template>
-    <div class="container">
-        <div class="sidebar">
-            <ul>
-                <li><RouterLink :to="{ name: 'requests' }">Requests</RouterLink></li>
-                <li><RouterLink :to="{ name: 'pagination' }">Pagination</RouterLink></li>
-            </ul>
-        </div>
-        <div class="content">
-            <RouterView />
-        </div>
-    </div>
-</template>
-
-<script setup>
-
-</script>
-
-<style>
-body {
-    margin: 0;
-    padding:0;
-}
-
-.container {
-    display: flex;
-    flex-direction: row;
-}
-
-.sidebar,
-.content {
-    display: flex;
-    flex-direction: column;
-    color: black;
-    min-height: 500px;
-    border-radius: 4px;
-    margin: 10px;
-}
-
-.sidebar {
-    flex-grow: 1;
-    min-width: 300px;
-}
-
-.content {
-    flex-grow: 5;
-    min-width: 630px;
-}
-</style>

package/examples/js/view/layout/DemoPage.vue

@@ -1,28 +0,0 @@
-<template>
-    <select v-model="selectedComponentKey">
-        <RouterLink
-            v-for="(component, key) in components"
-            :key="key"
-            :to="component.route"
-            custom
-            v-slot="{ isActive, href, navigate }"
-        >
-            <option @click="navigate" :value="key">
-                {{ component.name }}
-            </option>
-        </RouterLink>
-    </select>
-
-    <component v-if="selectedComponentKey" :is="components[selectedComponentKey].component" />
-</template>
-
-<script setup lang="ts">
-import {ref} from 'vue'
-
-const props = defineProps({
-    components: {},
-    component: String,
-})
-
-const selectedComponentKey = ref(props.component)
-</script>

package/examples/js/view/pagination/Pagination.vue

@@ -1,28 +0,0 @@
-<template>
-    <DemoPage :components="components" />
-</template>
-
-<script setup lang="ts">
-import TablePagination from './components/tablePagination/TablePagination.vue'
-import ErrorPagination from './components/errorPagination/ErrorPagination.vue'
-import InfiniteScrolling from './components/infiniteScrolling/InfiniteScrolling.vue'
-import DemoPage from '../layout/DemoPage.vue'
-
-const components = {
-    'table-pagination': {
-        name: 'Paginated table',
-        component: TablePagination,
-        route: { name: 'pagination', params: { component: 'table-pagination' } },
-    },
-    'error-pagination': {
-        name: 'Pagination with error',
-        component: ErrorPagination,
-        route: { name: 'pagination', params: { component: 'error-pagination' } },
-    },
-    'infinite-scrolling': {
-        name: 'Infinite scrolling',
-        component: InfiniteScrolling,
-        route: { name: 'pagination', params: { component: 'infinite-scrolling' } },
-    },
-}
-</script>

package/examples/js/view/pagination/components/errorPagination/ErrorPagination.vue

@@ -1,71 +0,0 @@
-<template>
-    <table>
-        <tr>
-            <th>ID</th>
-            <th>Title</th>
-            <th>Description</th>
-        </tr>
-        <tr v-for="row in paginator.getPageData()">
-            <td>{{ row.id }}</td>
-            <td>{{ row.title }}</td>
-            <td>{{ row.description }}</td>
-        </tr>
-    </table>
-
-    Current page: {{ paginator.getCurrentPage() }}
-    <br>
-    Pages: {{ paginator.getPages() }}
-    <br>
-    Page Size: <input v-model="pageSize" />
-    <br>
-    Back Page <button @click="paginator.toPreviousPage()">Back</button>
-    <br>
-    Next Page <button @click="paginator.toNextPage()">Next</button>
-    <br>
-    Showing {{ paginator.getFromItemNumber() }} to {{ paginator.getToItemNumber() }} of {{ paginator.getTotal() }} items.
-
-    {{ displayablePages }}
-</template>
-
-<script setup lang="ts">
-import {BaseRequest, FetchDriver, VueLoaderDriverFactory} from "@hank-it/ui/service/requests"
-import {Paginator, RequestDriver, VuePaginationDriverFactory} from "@hank-it/ui/service/pagination";
-import {getDisplayablePages} from '@hank-it/ui/service/helpers'
-import {GetProductsRequest} from "./GetProductsRequest";
-import {computed} from 'vue'
-
-/* Booting */
-BaseRequest.setRequestDriver(new FetchDriver)
-BaseRequest.setLoaderStateFactory(new VueLoaderDriverFactory)
-Paginator.setViewDriverFactory(new VuePaginationDriverFactory())
-
-/* component */
-const getProductsRequest = new GetProductsRequest
-
-const paginator = new Paginator(new RequestDriver(getProductsRequest))
-
-paginator.init(1, 10).catch(paginationErrorHandler)
-
-function paginationErrorHandler(response) {
-    console.log(response.getError())
-}
-
-const pageSize = computed({
-    set(value) {
-        paginator.setPageSize(value)
-    },
-    get() {
-        return paginator.getPageSize()
-    }
-})
-
-const displayablePages = computed(() => {
-    console.log(paginator.getPages())
-
-    return getDisplayablePages(paginator.getPages().length, paginator.getCurrentPage())
-})
-</script>
-
-<style scoped>
-
-</style>

package/examples/js/view/pagination/components/errorPagination/GetProductsRequest.ts

@@ -1,54 +0,0 @@
-import {BaseRequest, type Paginatable, JsonResponse } from '@hank-it/ui/service/requests'
-import type {PaginationResponseContract} from '@hank-it/ui/service/pagination'
-
-export interface ProductResource {
-    id: number
-    title: string
-    description: string
-}
-
-export interface ProductPaginationResource {
-    products: ProductResource[]
-    total: number
-    limit: number
-    skip: number
-}
-
-export class GetProductsRequestResponse extends JsonResponse implements PaginationResponseContract {
-    public getData() {
-        return this.data
-    }
-
-    public getTotal(): number {
-        return this.body.total
-    }
-
-    public dataHandler(data) {
-        return data.products
-    }
-}
-
-export class GetProductsRequest extends BaseRequest implements Paginatable {
-    method() {
-        return 'GET'
-    }
-
-    url() {
-        return 'https://dummyjson.com/http/500'
-    }
-
-    public setPaginationParams(page: number, size: number): BaseRequest {
-        return this.withParams({
-            skip: (page - 1) * size,
-            limit: size,
-        })
-    }
-
-    public getCorsWithCredentials(): boolean {
-        return false
-    }
-
-    protected getResponse() {
-        return new GetProductsRequestResponse
-    }
-}

package/examples/js/view/pagination/components/infiniteScrolling/GetProductsRequest.ts

@@ -1,50 +0,0 @@
-import {BaseRequest, type Paginatable, JsonResponse } from '@hank-it/ui/service/requests'
-import type {PaginationResponseContract} from '@hank-it/ui/service/pagination'
-
-export interface ProductResource {
-    id: number
-    title: string
-    description: string
-}
-
-export interface ProductPaginationResource {
-    products: ProductResource[]
-    total: number
-    limit: number
-    skip: number
-}
-
-export class GetProductsRequestResponse extends JsonResponse implements PaginationResponseContract {
-    public getData() {
-        return this.data
-    }
-
-    public getTotal(): number {
-        return this.body.total
-    }
-
-    public dataHandler(data) {
-        return data.products
-    }
-}
-
-export class GetProductsRequest extends BaseRequest implements Paginatable {
-    method() {
-        return 'GET'
-    }
-
-    url() {
-        return 'https://dummyjson.com/products'
-    }
-
-    public setPaginationParams(page: number, size: number): BaseRequest {
-        return this.withParams({
-            skip: (page - 1) * size,
-            limit: size,
-        })
-    }
-
-    protected getResponse() {
-        return new GetProductsRequestResponse
-    }
-}