@pyreweb/fabric 1.2.6

package/src/composables/README.md

@@ -0,0 +1,233 @@
+# Composables Fabric
+
+Les composables Fabric exposent la logique métier des composants "organismes" sous forme de fonctions réutilisables basées sur l'API de Composition de Vue.
+
+## Vue d'ensemble
+
+Les composables permettent de:
+- **Séparer les préoccupations**: Isoler la logique d'état de la logique de présentation
+- **Améliorer la réutilisabilité**: Réutiliser la logique dans des composants personnalisés
+- **Faciliter les tests**: Tester la logique métier de manière isolée
+
+## Composables disponibles
+
+### `useDataTableState`
+
+Gère l'état et la logique d'un tableau de données avec recherche, tri, pagination et sélection.
+
+#### Exemple d'utilisation
+
+```typescript
+import { useDataTableState } from '@pyreweb/fabric';
+
+export default {
+  name: 'MyCustomTable',
+  setup(props, { emit }) {
+    const tableState = useDataTableState(
+      {
+        data: props.data,
+        columns: props.columns,
+        perPage: 10,
+        paginated: true,
+        defaultSortKey: 'name'
+      },
+      emit
+    );
+
+    return {
+      ...tableState
+    };
+  }
+};
+```
+
+#### Options
+
+- `data` (Array, required): Tableau de données à afficher
+- `columns` (Array, required): Définitions des colonnes
+- `rowKey` (String, default: 'id'): Propriété unique dans les objets de données
+- `initialPage` (Number, default: 1): Numéro de page initial
+- `perPage` (Number, default: 10): Éléments par page
+- `paginated` (Boolean, default: true): Activer la pagination
+- `virtual` (Boolean, default: false): Activer la virtualisation (désactive la pagination)
+- `defaultSortKey` (String, default: null): Clé de tri par défaut
+- `defaultSortDirection` (String, default: 'asc'): Direction de tri par défaut ('asc' | 'desc')
+- `serverMode` (Boolean, default: false): Mode serveur (récupération externe des données)
+- `totalItems` (Number, default: null): Total d'éléments pour la pagination côté serveur
+- `selected` (Array, default: []): Clés de lignes initialement sélectionnées
+
+#### Valeurs retournées
+
+**État:**
+- `searchQuery`: Query de recherche (Ref<string>)
+- `sortKey`: Clé de tri actuelle (Ref<string | null>)
+- `sortDirection`: Direction de tri (Ref<'asc' | 'desc'>)
+- `internalPage`: Page actuelle (Ref<number>)
+- `selectedKeys`: Clés des lignes sélectionnées (Ref<any[]>)
+- `selectedItems`: Items sélectionnés (ComputedRef<any[]>)
+- `isAllSelected`: Toutes les lignes sont-elles sélectionnées (ComputedRef<boolean>)
+
+**Données traitées:**
+- `filteredData`: Données filtrées (ComputedRef<any[]>)
+- `sortedData`: Données triées (ComputedRef<any[]>)
+- `processedData`: Données traitées (ComputedRef<any[]>)
+- `paginatedData`: Données paginées (ComputedRef<any[]>)
+- `totalPages`: Nombre total de pages (ComputedRef<number>)
+- `paginationInfo`: Texte d'info de pagination (ComputedRef<string>)
+
+**Méthodes:**
+- `getCellValue(row, key)`: Obtenir la valeur d'une cellule
+- `getRowKey(row, index?)`: Obtenir la clé d'une ligne
+- `handleSort(key)`: Gérer le tri
+- `isRowSelected(row)`: Vérifier si une ligne est sélectionnée
+- `handleRowSelect(row, checked)`: Gérer la sélection d'une ligne
+- `handleSelectAll(checked)`: Sélectionner/désélectionner toutes les lignes
+- `clearSelection()`: Effacer la sélection
+
+---
+
+### `useSidebarState`
+
+Gère l'état et la logique d'une barre latérale de navigation avec sous-menus.
+
+#### Exemple d'utilisation
+
+```typescript
+import { useSidebarState } from '@pyreweb/fabric';
+
+export default {
+  name: 'MyCustomSidebar',
+  setup(props, { emit }) {
+    const sidebarState = useSidebarState(
+      {
+        items: props.items,
+        activeRoute: '/dashboard',
+        initialCollapsed: false
+      },
+      emit
+    );
+
+    // Initialiser les sous-menus ouverts basés sur la route active
+    sidebarState.initializeOpenSubmenus();
+
+    return {
+      ...sidebarState
+    };
+  }
+};
+```
+
+#### Options
+
+- `items` (Array, required): Configuration des éléments de navigation
+- `initialCollapsed` (Boolean, default: false): État initial réduit
+- `activeRoute` (String, default: ''): Chemin de route actif actuel
+
+#### Valeurs retournées
+
+**État:**
+- `collapsed`: État réduit de la sidebar (Ref<boolean>)
+- `openSubmenus`: Liste des sous-menus ouverts (Ref<string[]>)
+- `navigationItems`: Éléments de navigation filtrés (ComputedRef<NavigationItem[]>)
+
+**Méthodes:**
+- `toggleCollapsed()`: Basculer l'état réduit
+- `isSubmenuOpen(item)`: Vérifier si un sous-menu est ouvert
+- `toggleSubmenu(item)`: Basculer l'état d'un sous-menu
+- `isItemActive(item)`: Vérifier si un élément est actif
+- `hasActiveChild(item)`: Vérifier si un élément a un enfant actif
+- `initializeOpenSubmenus()`: Initialiser les sous-menus ouverts basés sur la route active
+
+---
+
+### `useFormValidation`
+
+Gère la validation et la soumission de formulaires avec gestion d'état.
+
+#### Exemple d'utilisation
+
+```typescript
+import { useFormValidation } from '@pyreweb/fabric';
+
+export default {
+  name: 'MyCustomForm',
+  setup(props, { emit }) {
+    const formState = useFormValidation(
+      {
+        initialData: {
+          name: '',
+          email: ''
+        }
+      },
+      emit
+    );
+
+    const onSubmit = async (event) => {
+      await formState.handleSubmit(event, async (data) => {
+        // Validation personnalisée
+        if (!data.email.includes('@')) {
+          formState.setFieldError('email', 'Email invalide');
+          return;
+        }
+        
+        // Soumettre au serveur
+        await api.submitForm(data);
+      });
+    };
+
+    return {
+      ...formState,
+      onSubmit
+    };
+  }
+};
+```
+
+#### Options
+
+- `initialData` (Object, default: {}): Données initiales du formulaire
+
+#### Valeurs retournées
+
+**État:**
+- `formData`: Données du formulaire (Ref<Record<string, any>>)
+- `errors`: Erreurs de validation (Ref<Record<string, string>>)
+- `isValid`: Le formulaire est-il valide (Ref<boolean>)
+- `isSubmitting`: Le formulaire est-il en cours de soumission (Ref<boolean>)
+
+**Méthodes:**
+- `handleSubmit(event, callback?)`: Gérer la soumission du formulaire
+- `setFieldValue(field, value)`: Définir la valeur d'un champ
+- `setFieldError(field, error)`: Définir l'erreur d'un champ
+- `clearFieldError(field)`: Effacer l'erreur d'un champ
+- `clearErrors()`: Effacer toutes les erreurs
+- `reset()`: Réinitialiser le formulaire à l'état initial
+- `validate()`: Valider le formulaire (peut être étendu avec une logique personnalisée)
+
+## Compatibilité
+
+Les composables sont compatibles avec:
+- Vue 2.7 (avec API de Composition)
+- Vue 3.x
+
+## Tests
+
+Tous les composables sont testés de manière exhaustive avec 73 tests unitaires:
+- `useDataTableState`: 33 tests
+- `useSidebarState`: 23 tests
+- `useFormValidation`: 17 tests
+
+Pour exécuter les tests:
+```bash
+npm test -- src/composables
+```
+
+## Notes d'implémentation
+
+Les composables sont des fonctions pures qui:
+1. Acceptent des options et une fonction `emit` comme paramètres
+2. Retournent un objet contenant l'état réactif et les méthodes
+3. Utilisent l'API de Composition de Vue (`ref`, `computed`, `watch`)
+4. Sont complètement typés avec TypeScript
+
+Les composants existants de la librairie (FForm, FDataTable, FNavigationSidebar) continuent d'utiliser l'API Options pour la compatibilité avec le build toolchain.

package/src/composables/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Composables for Fabric component library
+ *
+ * These composables extract the core logic from organism components
+ * and make it reusable across applications and custom components.
+ */
+
+export { useDataTableState } from './useDataTableState';
+export type {
+	DataTableStateOptions,
+	DataTableState
+} from './useDataTableState';
+
+export { useSidebarState } from './useSidebarState';
+export type {
+	NavigationItem,
+	SidebarStateOptions,
+	SidebarState
+} from './useSidebarState';
+
+export { useFormValidation } from './useFormValidation';
+export type {
+	FormValidationOptions,
+	FormValidationState
+} from './useFormValidation';

package/src/composables/useDataTableState.test.ts

@@ -0,0 +1,378 @@
+import { describe, it, expect, vi } from 'vitest';
+import { useDataTableState } from './useDataTableState';
+
+describe('useDataTableState', () => {
+	const columns = [
+		{ key: 'name', label: 'Name' },
+		{ key: 'email', label: 'Email' },
+		{ key: 'role', label: 'Role' }
+	];
+
+	const data = [
+		{ id: 1, name: 'Alice', email: 'alice@test.com', role: 'Admin' },
+		{ id: 2, name: 'Bob', email: 'bob@test.com', role: 'User' },
+		{ id: 3, name: 'Charlie', email: 'charlie@test.com', role: 'User' },
+		{ id: 4, name: 'David', email: 'david@test.com', role: 'Manager' }
+	];
+
+	it('initializes with default state', () => {
+		const emit = vi.fn();
+		const state = useDataTableState({ data, columns }, emit);
+
+		expect(state.searchQuery.value).toBe('');
+		expect(state.sortKey.value).toBe(null);
+		expect(state.sortDirection.value).toBe('asc');
+		expect(state.internalPage.value).toBe(1);
+		expect(state.selectedKeys.value).toEqual([]);
+	});
+
+	it('initializes with custom options', () => {
+		const emit = vi.fn();
+		const state = useDataTableState(
+			{
+				data,
+				columns,
+				initialPage: 2,
+				defaultSortKey: 'name',
+				defaultSortDirection: 'desc',
+				selected: [1, 2]
+			},
+			emit
+		);
+
+		expect(state.internalPage.value).toBe(2);
+		expect(state.sortKey.value).toBe('name');
+		expect(state.sortDirection.value).toBe('desc');
+		expect(state.selectedKeys.value).toEqual([1, 2]);
+	});
+
+	describe('getCellValue', () => {
+		it('gets direct property value', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+			const value = state.getCellValue(data[0], 'name');
+			expect(value).toBe('Alice');
+		});
+
+		it('gets nested property value', () => {
+			const emit = vi.fn();
+			const nestedData = [{ user: { profile: { name: 'Test' } } }];
+			const state = useDataTableState({ data: nestedData, columns }, emit);
+			const value = state.getCellValue(nestedData[0], 'user.profile.name');
+			expect(value).toBe('Test');
+		});
+	});
+
+	describe('getRowKey', () => {
+		it('gets row key using default rowKey prop', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+			const key = state.getRowKey(data[0]);
+			expect(key).toBe(1);
+		});
+
+		it('uses index when row key is missing', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+			const key = state.getRowKey({}, 5);
+			expect(key).toBe(5);
+		});
+
+		it('uses custom rowKey', () => {
+			const emit = vi.fn();
+			const customData = [{ customId: 'abc', name: 'Test' }];
+			const state = useDataTableState(
+				{ data: customData, columns, rowKey: 'customId' },
+				emit
+			);
+			const key = state.getRowKey(customData[0]);
+			expect(key).toBe('abc');
+		});
+	});
+
+	describe('filtering', () => {
+		it('filters data based on search query', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			expect(state.filteredData.value.length).toBe(4);
+
+			state.searchQuery.value = 'alice';
+			expect(state.filteredData.value.length).toBe(1);
+			expect(state.filteredData.value[0].name).toBe('Alice');
+		});
+
+		it('filters across multiple columns', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.searchQuery.value = 'test.com';
+			expect(state.filteredData.value.length).toBe(4);
+		});
+
+		it('is case insensitive', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.searchQuery.value = 'ALICE';
+			expect(state.filteredData.value.length).toBe(1);
+		});
+
+		it('does not filter in server mode', () => {
+			const emit = vi.fn();
+			const state = useDataTableState(
+				{ data, columns, serverMode: true },
+				emit
+			);
+
+			state.searchQuery.value = 'alice';
+			expect(state.filteredData.value.length).toBe(4);
+		});
+
+		it('resets to first page when search changes', async () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.internalPage.value = 2;
+			state.searchQuery.value = 'alice';
+			// Wait for watcher to trigger
+			await new Promise((resolve) => setTimeout(resolve, 0));
+			expect(state.internalPage.value).toBe(1);
+		});
+	});
+
+	describe('sorting', () => {
+		it('sorts data in ascending order', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.handleSort('name');
+			expect(state.sortedData.value[0].name).toBe('Alice');
+			expect(state.sortedData.value[3].name).toBe('David');
+		});
+
+		it('sorts data in descending order', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.handleSort('name');
+			state.handleSort('name');
+			expect(state.sortedData.value[0].name).toBe('David');
+			expect(state.sortedData.value[3].name).toBe('Alice');
+		});
+
+		it('emits sort event', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.handleSort('name');
+			expect(emit).toHaveBeenCalledWith('sort', {
+				key: 'name',
+				direction: 'asc'
+			});
+		});
+
+		it('does not sort in server mode', () => {
+			const emit = vi.fn();
+			const state = useDataTableState(
+				{ data, columns, serverMode: true },
+				emit
+			);
+
+			state.handleSort('name');
+			expect(state.sortedData.value).toEqual(data);
+		});
+
+		it('handles null and undefined values', () => {
+			const emit = vi.fn();
+			const dataWithNulls = [
+				{ id: 1, name: 'Alice' },
+				{ id: 2, name: null },
+				{ id: 3, name: 'Bob' }
+			];
+			const state = useDataTableState({ data: dataWithNulls, columns }, emit);
+
+			state.handleSort('name');
+			// Nulls should be sorted to the end
+			expect(state.sortedData.value[2].name).toBe(null);
+		});
+	});
+
+	describe('pagination', () => {
+		it('calculates total pages correctly', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns, perPage: 2 }, emit);
+
+			expect(state.totalPages.value).toBe(2);
+		});
+
+		it('paginates data correctly', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns, perPage: 2 }, emit);
+
+			expect(state.paginatedData.value.length).toBe(2);
+			expect(state.paginatedData.value[0].name).toBe('Alice');
+
+			state.internalPage.value = 2;
+			expect(state.paginatedData.value.length).toBe(2);
+			expect(state.paginatedData.value[0].name).toBe('Charlie');
+		});
+
+		it('generates pagination info text', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns, perPage: 2 }, emit);
+
+			expect(state.paginationInfo.value).toBe('1 - 2 sur 4');
+
+			state.internalPage.value = 2;
+			expect(state.paginationInfo.value).toBe('3 - 4 sur 4');
+		});
+
+		it('disables pagination when virtual mode is enabled', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns, virtual: true }, emit);
+
+			expect(state.effectivePaginated.value).toBe(false);
+			expect(state.paginatedData.value.length).toBe(4);
+		});
+
+		it('emits page change events', async () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.internalPage.value = 2;
+			// Wait for watcher to trigger
+			await new Promise((resolve) => setTimeout(resolve, 0));
+			expect(emit).toHaveBeenCalledWith('update:page', 2);
+		});
+	});
+
+	describe('selection', () => {
+		it('selects a single row', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.handleRowSelect(data[0], true);
+			expect(state.selectedKeys.value).toContain(1);
+			expect(emit).toHaveBeenCalledWith('select', {
+				row: data[0],
+				selected: true
+			});
+		});
+
+		it('deselects a row', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns, selected: [1] }, emit);
+
+			state.handleRowSelect(data[0], false);
+			expect(state.selectedKeys.value).not.toContain(1);
+		});
+
+		it('checks if row is selected', () => {
+			const emit = vi.fn();
+			const state = useDataTableState(
+				{ data, columns, selected: [1, 2] },
+				emit
+			);
+
+			expect(state.isRowSelected(data[0])).toBe(true);
+			expect(state.isRowSelected(data[2])).toBe(false);
+		});
+
+		it('selects all rows on current page', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns, perPage: 2 }, emit);
+
+			state.handleSelectAll(true);
+			expect(state.selectedKeys.value).toContain(1);
+			expect(state.selectedKeys.value).toContain(2);
+			expect(state.selectedKeys.value).not.toContain(3);
+		});
+
+		it('deselects all rows on current page', () => {
+			const emit = vi.fn();
+			const state = useDataTableState(
+				{ data, columns, perPage: 2, selected: [1, 2] },
+				emit
+			);
+
+			state.handleSelectAll(false);
+			expect(state.selectedKeys.value).toEqual([]);
+		});
+
+		it('determines if all rows are selected', () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns, perPage: 2 }, emit);
+
+			expect(state.isAllSelected.value).toBe(false);
+
+			state.handleSelectAll(true);
+			expect(state.isAllSelected.value).toBe(true);
+		});
+
+		it('clears selection', () => {
+			const emit = vi.fn();
+			const state = useDataTableState(
+				{ data, columns, selected: [1, 2, 3] },
+				emit
+			);
+
+			state.clearSelection();
+			expect(state.selectedKeys.value).toEqual([]);
+		});
+
+		it('emits selection change events', async () => {
+			const emit = vi.fn();
+			const state = useDataTableState({ data, columns }, emit);
+
+			state.selectedKeys.value = [1];
+			// Wait for next tick for watcher to trigger
+			await new Promise((resolve) => setTimeout(resolve, 0));
+			expect(emit).toHaveBeenCalledWith('update:selected', [1]);
+		});
+
+		it('provides selected items', () => {
+			const emit = vi.fn();
+			const state = useDataTableState(
+				{ data, columns, selected: [1, 3] },
+				emit
+			);
+
+			expect(state.selectedItems.value.length).toBe(2);
+			expect(state.selectedItems.value[0].name).toBe('Alice');
+			expect(state.selectedItems.value[1].name).toBe('Charlie');
+		});
+	});
+
+	describe('server mode', () => {
+		it('uses external total items for pagination', () => {
+			const emit = vi.fn();
+			const state = useDataTableState(
+				{
+					data: data.slice(0, 2),
+					columns,
+					serverMode: true,
+					totalItems: 100,
+					perPage: 2
+				},
+				emit
+			);
+
+			expect(state.computedTotalItems.value).toBe(100);
+			expect(state.totalPages.value).toBe(50);
+		});
+
+		it('does not filter or sort in server mode', () => {
+			const emit = vi.fn();
+			const state = useDataTableState(
+				{ data, columns, serverMode: true },
+				emit
+			);
+
+			state.searchQuery.value = 'alice';
+			state.handleSort('name');
+
+			expect(state.processedData.value).toEqual(data);
+		});
+	});
+});