@blueprint-ts/core 1.0.0

package/docs/vue/requests/route-model-binding.md

@@ -0,0 +1,66 @@
+# Route Model Binding
+
+When using `vue-router`, you can automatically bind route parameters to resources, similar to how Laravel's route model binding works.
+
+## Setup
+
+To enable the router to load resources automatically, install the route injection plugin when initializing your router:
+
+```ts
+installRouteInjection(router)
+```
+
+### Defining Routes
+
+Use the `defineRoute` helper to define your routes and specify which parameters should be resolved into resources:
+
+```ts
+defineRoute<{
+    product: ProductResource
+}>()({
+    path: ':productId',
+    name: 'products.show',
+    component: ProductDetailPage,
+    meta: {
+        inject: {
+            product: {
+                from: 'productId',
+                resolve: (productId: string) => {
+                    return new RouteModelRequestResolver(
+                        new ProductShowRequest(productId)
+                    )
+                }
+            }
+        }
+    }
+})
+```
+
+The `beforeResolve` navigation guard will automatically fetch the `ProductResource` using the `ProductShowRequest` and the `productId` from the route.
+
+## Usage in Components
+
+Your component can then directly access the resolved resource via props:
+
+```vue
+<script setup lang="ts">
+const props = defineProps<{
+    product: ProductResource
+}>()
+</script>
+```
+
+## Handling Loading States
+
+You can handle the loading state of the request by using the event system of the request class:
+
+```ts
+resolve: (productId: string) => {
+    return new RouteModelRequestResolver(
+        new ProductShowRequest(productId).on<boolean>(RequestEvents.LOADING, (loading: boolean) => {
+          const loadingStore = useLoadingStore()
+          loadingStore.setLoading(loading)
+        })
+    )
+}
+```

package/docs/vue/state.md

@@ -0,0 +1,293 @@
+# State Management
+
+## Overview
+The `State` class provides a reactive, type-safe state management system with rich features like change detection, nested property watching, persistence, and more. It's designed to make state management in Vue applications clean and flexible.
+
+## Core Features
+- **Type-safe state**: Fully typed with TypeScript generics
+- **Reactive properties**: Seamless integration with Vue's reactivity system
+- **Nested property watching**: Track changes to deeply nested properties
+- **Persistence options**: Optional state persistence between sessions
+- **Change subscriptions**: React to state changes with optional debouncing
+- **Deep object watching**: Special handling for nested objects
+- **Efficient equality checking**: Smart comparison of state values
+- **State export/import**: Easily serialize and deserialize state
+- **Reset capability**: Revert to initial state when needed
+
+## Usage Guide
+### Creating a State Class
+Create a new state by extending the base class and defining your interface:
+
+```typescript
+// Define your state interface
+interface UserStateInterface {
+  name: string;
+  email: string;
+  preferences: {
+    darkMode: boolean;
+    notifications: boolean;
+  };
+}
+
+// Create your state class
+class UserState extends State<UserStateInterface> {
+  constructor() {
+    super(
+      {
+        name: '',
+        email: '',
+        preferences: {
+          darkMode: false,
+          notifications: true
+        }
+      }, 
+      {
+        persist: true // Enable persistence
+      }
+    );
+  }
+  
+  // Optional: Override persistence method
+  protected override getPersistenceDriver(): PersistenceDriver {
+    return new LocalStorageDriver();
+  }
+}
+
+// Create an instance
+export const userState = new UserState();
+```
+
+### Accessing State
+
+````typescript
+// Read
+const userName = userState.state.name;
+
+// Write
+userState.state.name = 'John Doe';
+````
+
+### Subscribing to Changes
+Listen for changes to specific properties using the method: `subscribe`
+
+#### Basic subscription to a single property
+````typescript
+// Subscribe to changes on a top-level property
+userState.subscribe(
+  'name',
+  (newValue, oldValue) => {
+    console.log(`Name changed from ${oldValue} to ${newValue}`);
+  }
+);
+````
+
+#### Subscribing to nested properties
+
+````typescript
+// Subscribe to a nested property using dot notation
+userState.subscribe(
+  'preferences.darkMode',
+  (newValue, oldValue) => {
+    console.log(`Dark mode changed from ${oldValue} to ${newValue}`);
+    // Update UI theme
+  }
+);
+````
+
+#### Debounced subscriptions
+
+````typescript
+// Debounce the handler to avoid frequent updates
+userState.subscribe(
+  'email',
+  (newValue, oldValue) => {
+    // This will only execute after 300ms of stability
+    validateEmail(newValue);
+  },
+  { debounce: 300 }
+);
+````
+
+#### Watching multiple properties
+````typescript
+// Subscribe to multiple properties at once
+userState.subscribe(
+  ['name', 'email'],
+  (changedPath, state) => {
+    console.log(`Property ${changedPath} changed`);
+    console.log('Current state:', state);
+  }
+);
+````
+
+### State Persistence
+Enable state persistence by passing `persist: true` in the constructor options. Override the method `getPersistenceDriver` to use different storage mechanisms:
+
+````typescript
+// Examples of different persistence drivers:
+protected override getPersistenceDriver(): PersistenceDriver {
+  // Session storage (lasts until browser tab is closed)
+  return new SessionStorageDriver();
+  
+  // Local storage (persists between sessions)
+  // return new LocalStorageDriver();
+  
+  // Non-persistent (for testing or when persistence not needed)
+  // return new NonPersistentDriver();
+}
+````
+
+### Importing and Exporting State
+
+Export the current state to a plain object or import values:
+
+````typescript
+// Export current state as a plain object
+const stateSnapshot = userState.export();
+console.log(stateSnapshot);
+
+// Import partial state
+userState.import({
+  name: 'Jane Doe',
+  preferences: {
+    darkMode: true
+  }
+});
+
+// Import with hook suppression (doesn't trigger change handlers)
+userState.import(
+  { 
+    name: 'Jane Doe'
+  },
+  true // suppress hooks
+);
+````
+
+### Resetting State
+Reset the state to its initial values:
+
+````typescript
+// Reset to initial values
+userState.reset();
+````
+
+````
+userState.subscribe(
+  'name',
+  (newValue, oldValue) => {
+    console.log(`Name reset from ${oldValue} to ${newValue}`);
+  },
+  { executeOnReset: true }
+);
+````
+
+## Advanced Features
+### Deep Object Watching
+When you modify nested properties, the system automatically detects these changes and triggers appropriate callbacks:
+
+````typescript
+// Both of these will trigger the 'preferences.darkMode' subscription
+userState.state.preferences.darkMode = true;
+userState.state.preferences = { darkMode: true, notifications: false };
+````
+
+### Type-Safe Path Access
+The state system enforces type safety for property paths:
+
+````typescript
+// TypeScript will error on invalid paths
+userState.subscribe(
+  'preferences.invalidProperty', // Type error!
+  (newValue, oldValue) => {
+    // ...
+  }
+);
+````
+
+### Smart Comparison
+The system performs deep equality checks before triggering change handlers, ensuring callbacks are only called when values actually change:
+
+````typescript
+// This won't trigger change handlers if the values are deeply equal
+userState.state.preferences = { darkMode: false, notifications: true };
+````
+
+## Example: Complete Workflow
+
+````typescript
+// 1. Define state interface
+interface FormState {
+  username: string;
+  password: string;
+  validation: {
+    usernameValid: boolean;
+    passwordValid: boolean;
+  };
+}
+
+// 2. Create state class
+class FormStateManager extends State<FormState> {
+  constructor() {
+    super({
+      username: '',
+      password: '',
+      validation: {
+        usernameValid: false,
+        passwordValid: false
+      }
+    });
+  }
+  
+  // Helper methods can be added to state classes
+  public validateForm(): boolean {
+    return this.state.validation.usernameValid && 
+           this.state.validation.passwordValid;
+  }
+}
+
+// 3. Create instance
+const formState = new FormStateManager();
+
+// 4. Set up subscriptions
+formState.subscribe(
+  'username',
+  (username) => {
+    // Validate username
+    const valid = username.length >= 3;
+    formState.state.validation.usernameValid = valid;
+  },
+  { debounce: 300 }
+);
+
+formState.subscribe(
+  'password',
+  (password) => {
+    // Validate password
+    const valid = password.length >= 8;
+    formState.state.validation.passwordValid = valid;
+  },
+  { debounce: 300 }
+);
+
+// 5. Watch form validity
+formState.subscribe(
+  ['validation.usernameValid', 'validation.passwordValid'],
+  (_, state) => {
+    const submitButton = document.getElementById('submit');
+    if (formState.validateForm()) {
+      submitButton.disabled = false;
+    } else {
+      submitButton.disabled = true;
+    }
+  }
+);
+
+// 6. Use the state
+formState.state.username = 'john_doe';
+formState.state.password = 'securePassword123';
+
+// 7. Reset when needed
+document.getElementById('reset').addEventListener('click', () => {
+  formState.reset();
+});
+````

package/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/eslint.config.js

@@ -0,0 +1,15 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import pluginVue from 'eslint-plugin-vue';
+
+import {
+  defineConfigWithVueTs,
+  vueTsConfigs,
+} from '@vue/eslint-config-typescript'
+
+export default defineConfigWithVueTs(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  ...pluginVue.configs['flat/recommended'],
+  vueTsConfigs.recommended,
+)

package/examples/index.html

@@ -0,0 +1,14 @@
+<!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

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

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

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

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

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

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

@@ -0,0 +1,54 @@
+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
+    }
+}