@htlkg/components 0.0.1

package/src/composables/useModal.property.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import * as fc from 'fast-check';
+import { useModal } from './useModal';
+
+/**
+ * Feature: htlkg-modular-architecture, Property 9: Components support v-model
+ * Validates: Requirements 12.2
+ */
+describe('useModal property tests', () => {
+  it('should manage open/close state reactively', () => {
+    fc.assert(
+      fc.property(
+        fc.boolean(),
+        (initialOpen) => {
+          const { isOpen, open, close, toggle } = useModal({ initialOpen });
+
+          // Property: Initial state should match initialOpen
+          expect(isOpen.value).toBe(initialOpen);
+
+          // Property: open() should set isOpen to true
+          open();
+          expect(isOpen.value).toBe(true);
+
+          // Property: close() should set isOpen to false
+          close();
+          expect(isOpen.value).toBe(false);
+
+          // Property: toggle() should flip the state
+          const beforeToggle = isOpen.value;
+          toggle();
+          expect(isOpen.value).toBe(!beforeToggle);
+
+          // Property: toggle() again should return to original state
+          toggle();
+          expect(isOpen.value).toBe(beforeToggle);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should call callbacks when opening and closing', () => {
+    fc.assert(
+      fc.property(
+        fc.boolean(),
+        (initialOpen) => {
+          let openCallCount = 0;
+          let closeCallCount = 0;
+
+          const { open, close, toggle } = useModal({
+            initialOpen,
+            onOpen: () => { openCallCount++; },
+            onClose: () => { closeCallCount++; }
+          });
+
+          const initialOpenCalls = openCallCount;
+          const initialCloseCalls = closeCallCount;
+
+          // Property: open() should call onOpen callback
+          open();
+          expect(openCallCount).toBe(initialOpenCalls + 1);
+
+          // Property: close() should call onClose callback
+          close();
+          expect(closeCallCount).toBe(initialCloseCalls + 1);
+
+          // Property: toggle() should call appropriate callback
+          const beforeToggleOpen = openCallCount;
+          const beforeToggleClose = closeCallCount;
+          toggle(); // Should open
+          expect(openCallCount).toBe(beforeToggleOpen + 1);
+          
+          toggle(); // Should close
+          expect(closeCallCount).toBe(beforeToggleClose + 1);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should maintain state consistency across multiple operations', () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.constantFrom('open', 'close', 'toggle'), { minLength: 1, maxLength: 20 }),
+        (operations) => {
+          const { isOpen, open, close, toggle } = useModal({ initialOpen: false });
+
+          let expectedState = false;
+
+          for (const operation of operations) {
+            switch (operation) {
+              case 'open':
+                open();
+                expectedState = true;
+                break;
+              case 'close':
+                close();
+                expectedState = false;
+                break;
+              case 'toggle':
+                toggle();
+                expectedState = !expectedState;
+                break;
+            }
+
+            // Property: State should always match expected state after operation
+            expect(isOpen.value).toBe(expectedState);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should handle rapid state changes correctly', () => {
+    fc.assert(
+      fc.property(
+        fc.integer({ min: 1, max: 10 }),
+        (toggleCount) => {
+          const { isOpen, toggle } = useModal({ initialOpen: false });
+
+          const initialState = isOpen.value;
+
+          // Property: Toggling an even number of times should return to initial state
+          for (let i = 0; i < toggleCount * 2; i++) {
+            toggle();
+          }
+          expect(isOpen.value).toBe(initialState);
+
+          // Property: Toggling an odd number of times should flip the state
+          toggle();
+          expect(isOpen.value).toBe(!initialState);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should support v-model pattern with reactive updates', () => {
+    fc.assert(
+      fc.property(
+        fc.boolean(),
+        fc.boolean(),
+        (initialState, targetState) => {
+          const { isOpen, open, close } = useModal({ initialOpen: initialState });
+
+          // Property: Directly setting isOpen.value should update state (v-model pattern)
+          isOpen.value = targetState;
+          expect(isOpen.value).toBe(targetState);
+
+          // Property: Methods should still work after direct state change
+          if (targetState) {
+            close();
+            expect(isOpen.value).toBe(false);
+          } else {
+            open();
+            expect(isOpen.value).toBe(true);
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});

package/src/composables/useModal.ts

@@ -0,0 +1,43 @@
+import { ref, type Ref } from 'vue';
+
+export interface UseModalOptions {
+  initialOpen?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+
+export interface UseModalReturn {
+  isOpen: Ref<boolean>;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+}
+
+export function useModal(options: UseModalOptions = {}): UseModalReturn {
+  const isOpen = ref(options.initialOpen ?? false);
+
+  function open() {
+    isOpen.value = true;
+    options.onOpen?.();
+  }
+
+  function close() {
+    isOpen.value = false;
+    options.onClose?.();
+  }
+
+  function toggle() {
+    if (isOpen.value) {
+      close();
+    } else {
+      open();
+    }
+  }
+
+  return {
+    isOpen,
+    open,
+    close,
+    toggle
+  };
+}

package/src/composables/useNotifications.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { useNotifications } from './useNotifications';
+
+describe('useNotifications composable', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('initializes with empty notifications', () => {
+    const { notifications, clearAll } = useNotifications();
+    clearAll(); // Clear any existing notifications
+    expect(notifications.value).toEqual([]);
+  });
+
+  it('adds notification', () => {
+    const { notifications, addNotification, clearAll } = useNotifications();
+    clearAll();
+
+    const id = addNotification({
+      message: 'Test notification',
+      type: 'info'
+    });
+
+    expect(notifications.value).toHaveLength(1);
+    expect(notifications.value[0].id).toBe(id);
+    expect(notifications.value[0].message).toBe('Test notification');
+    expect(notifications.value[0].type).toBe('info');
+  });
+
+  it('generates unique IDs for notifications', () => {
+    const { addNotification, clearAll } = useNotifications();
+    clearAll();
+
+    const id1 = addNotification({ message: 'Test 1', type: 'info' });
+    const id2 = addNotification({ message: 'Test 2', type: 'info' });
+
+    expect(id1).not.toBe(id2);
+  });
+
+  it('removes notification by ID', () => {
+    const { notifications, addNotification, removeNotification, clearAll } = useNotifications();
+    clearAll();
+
+    const id = addNotification({ message: 'Test', type: 'info' });
+    expect(notifications.value).toHaveLength(1);
+
+    removeNotification(id);
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('clears all notifications', () => {
+    const { notifications, addNotification, clearAll } = useNotifications();
+    clearAll();
+
+    addNotification({ message: 'Test 1', type: 'info' });
+    addNotification({ message: 'Test 2', type: 'success' });
+    expect(notifications.value).toHaveLength(2);
+
+    clearAll();
+    expect(notifications.value).toEqual([]);
+  });
+
+  it('auto-removes notification after duration', () => {
+    const { notifications, addNotification, clearAll } = useNotifications();
+    clearAll();
+
+    addNotification({
+      message: 'Test',
+      type: 'info',
+      duration: 3000
+    });
+
+    expect(notifications.value).toHaveLength(1);
+
+    vi.advanceTimersByTime(3000);
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('adds info notification with default duration', () => {
+    const { notifications, info, clearAll } = useNotifications();
+    clearAll();
+
+    info('Info message');
+    expect(notifications.value).toHaveLength(1);
+    expect(notifications.value[0].type).toBe('info');
+    expect(notifications.value[0].message).toBe('Info message');
+
+    vi.advanceTimersByTime(3000);
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('adds success notification with default duration', () => {
+    const { notifications, success, clearAll } = useNotifications();
+    clearAll();
+
+    success('Success message');
+    expect(notifications.value).toHaveLength(1);
+    expect(notifications.value[0].type).toBe('success');
+    expect(notifications.value[0].message).toBe('Success message');
+
+    vi.advanceTimersByTime(3000);
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('adds warning notification with default duration', () => {
+    const { notifications, warning, clearAll } = useNotifications();
+    clearAll();
+
+    warning('Warning message');
+    expect(notifications.value).toHaveLength(1);
+    expect(notifications.value[0].type).toBe('warning');
+    expect(notifications.value[0].message).toBe('Warning message');
+
+    vi.advanceTimersByTime(3000);
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('adds error notification with longer default duration', () => {
+    const { notifications, error, clearAll } = useNotifications();
+    clearAll();
+
+    error('Error message');
+    expect(notifications.value).toHaveLength(1);
+    expect(notifications.value[0].type).toBe('error');
+    expect(notifications.value[0].message).toBe('Error message');
+
+    vi.advanceTimersByTime(5000);
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('allows custom duration for helper methods', () => {
+    const { notifications, info, clearAll } = useNotifications();
+    clearAll();
+
+    info('Custom duration', 1000);
+    expect(notifications.value).toHaveLength(1);
+
+    vi.advanceTimersByTime(1000);
+    expect(notifications.value).toHaveLength(0);
+  });
+
+  it('handles removing non-existent notification gracefully', () => {
+    const { notifications, removeNotification, clearAll } = useNotifications();
+    clearAll();
+
+    expect(() => removeNotification('non-existent-id')).not.toThrow();
+    expect(notifications.value).toEqual([]);
+  });
+
+  it('maintains notification order', () => {
+    const { notifications, addNotification, clearAll } = useNotifications();
+    clearAll();
+
+    addNotification({ message: 'First', type: 'info' });
+    addNotification({ message: 'Second', type: 'success' });
+    addNotification({ message: 'Third', type: 'warning' });
+
+    expect(notifications.value[0].message).toBe('First');
+    expect(notifications.value[1].message).toBe('Second');
+    expect(notifications.value[2].message).toBe('Third');
+  });
+});

package/src/composables/useNotifications.ts

@@ -0,0 +1,81 @@
+import { ref, type Ref } from 'vue';
+
+export interface Notification {
+  id: string;
+  message: string;
+  type: 'info' | 'success' | 'warning' | 'error';
+  duration?: number;
+}
+
+export interface UseNotificationsReturn {
+  notifications: Ref<Notification[]>;
+  addNotification: (notification: Omit<Notification, 'id'>) => string;
+  removeNotification: (id: string) => void;
+  clearAll: () => void;
+  info: (message: string, duration?: number) => string;
+  success: (message: string, duration?: number) => string;
+  warning: (message: string, duration?: number) => string;
+  error: (message: string, duration?: number) => string;
+}
+
+// Global notifications state
+const notifications = ref<Notification[]>([]);
+
+export function useNotifications(): UseNotificationsReturn {
+  function addNotification(notification: Omit<Notification, 'id'>): string {
+    const id = `notification-${Date.now()}-${Math.random()}`;
+    const newNotification: Notification = {
+      ...notification,
+      id
+    };
+
+    notifications.value.push(newNotification);
+
+    // Auto-remove after duration
+    if (notification.duration) {
+      setTimeout(() => {
+        removeNotification(id);
+      }, notification.duration);
+    }
+
+    return id;
+  }
+
+  function removeNotification(id: string) {
+    const index = notifications.value.findIndex(n => n.id === id);
+    if (index !== -1) {
+      notifications.value.splice(index, 1);
+    }
+  }
+
+  function clearAll() {
+    notifications.value = [];
+  }
+
+  function info(message: string, duration = 3000): string {
+    return addNotification({ message, type: 'info', duration });
+  }
+
+  function success(message: string, duration = 3000): string {
+    return addNotification({ message, type: 'success', duration });
+  }
+
+  function warning(message: string, duration = 3000): string {
+    return addNotification({ message, type: 'warning', duration });
+  }
+
+  function error(message: string, duration = 5000): string {
+    return addNotification({ message, type: 'error', duration });
+  }
+
+  return {
+    notifications,
+    addNotification,
+    removeNotification,
+    clearAll,
+    info,
+    success,
+    warning,
+    error
+  };
+}

package/src/composables/useTable.property.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect } from 'vitest';
+import * as fc from 'fast-check';
+import { useTable } from './useTable';
+
+/**
+ * Feature: htlkg-modular-architecture, Property 8: Stateful components manage state
+ * Validates: Requirements 12.1
+ */
+describe('useTable property tests', () => {
+  it('should manage pagination state reactively', () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.record({
+          id: fc.string(),
+          name: fc.string(),
+          value: fc.integer()
+        }), { minLength: 0, maxLength: 100 }),
+        fc.integer({ min: 1, max: 50 }),
+        fc.integer({ min: 1, max: 10 }),
+        (items, pageSize, targetPage) => {
+          const { currentPage, paginatedItems, totalPages, setPage } = useTable({
+            items,
+            pageSize
+          });
+
+          // Property: Setting page should update currentPage
+          const validPage = Math.min(targetPage, totalPages.value);
+          if (validPage >= 1) {
+            setPage(validPage);
+            expect(currentPage.value).toBe(validPage);
+          }
+
+          // Property: Paginated items should not exceed page size
+          expect(paginatedItems.value.length).toBeLessThanOrEqual(pageSize);
+
+          // Property: Total pages should be correct
+          const expectedPages = Math.ceil(items.length / pageSize);
+          expect(totalPages.value).toBe(expectedPages);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should manage sorting state reactively', () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.record({
+          id: fc.string(),
+          name: fc.string(),
+          value: fc.integer()
+        }), { minLength: 2, maxLength: 50 }),
+        fc.constantFrom('id', 'name', 'value'),
+        fc.constantFrom('asc' as const, 'desc' as const),
+        (items, sortField, sortDirection) => {
+          const { sortKey, sortOrder, sortedItems, setSorting } = useTable({
+            items
+          });
+
+          // Property: Setting sorting should update sortKey and sortOrder
+          setSorting(sortField, sortDirection);
+          expect(sortKey.value).toBe(sortField);
+          expect(sortOrder.value).toBe(sortDirection);
+
+          // Property: Sorted items should maintain same length
+          expect(sortedItems.value.length).toBe(items.length);
+
+          // Property: Sorted items should be in correct order
+          if (sortedItems.value.length > 1) {
+            for (let i = 0; i < sortedItems.value.length - 1; i++) {
+              const current = sortedItems.value[i][sortField];
+              const next = sortedItems.value[i + 1][sortField];
+              
+              if (current != null && next != null) {
+                if (sortDirection === 'asc') {
+                  expect(current <= next).toBe(true);
+                } else {
+                  expect(current >= next).toBe(true);
+                }
+              }
+            }
+          }
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should manage selection state reactively', () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.record({
+          id: fc.string(),
+          name: fc.string()
+        }), { minLength: 1, maxLength: 50 }),
+        (items) => {
+          const { selectedItems, selectItem, deselectItem, selectAll, clearSelection, isSelected } = useTable({
+            items
+          });
+
+          // Property: Initially no items selected
+          expect(selectedItems.value.length).toBe(0);
+
+          // Property: Selecting an item should add it to selection
+          const itemToSelect = items[0];
+          selectItem(itemToSelect);
+          expect(isSelected(itemToSelect)).toBe(true);
+          expect(selectedItems.value.length).toBe(1);
+
+          // Property: Deselecting an item should remove it from selection
+          deselectItem(itemToSelect);
+          expect(isSelected(itemToSelect)).toBe(false);
+          expect(selectedItems.value.length).toBe(0);
+
+          // Property: Select all should select all items
+          selectAll();
+          expect(selectedItems.value.length).toBe(items.length);
+          items.forEach(item => {
+            expect(isSelected(item)).toBe(true);
+          });
+
+          // Property: Clear selection should remove all selections
+          clearSelection();
+          expect(selectedItems.value.length).toBe(0);
+          items.forEach(item => {
+            expect(isSelected(item)).toBe(false);
+          });
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should handle filtering with pagination correctly', () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.record({
+          id: fc.string(),
+          name: fc.string(),
+          active: fc.boolean()
+        }), { minLength: 0, maxLength: 100 }),
+        fc.integer({ min: 5, max: 20 }),
+        (items, pageSize) => {
+          const { paginatedItems, totalPages, currentPage } = useTable({
+            items,
+            pageSize
+          });
+
+          // Property: First page should start from index 0
+          if (items.length > 0) {
+            const firstPageItem = paginatedItems.value[0];
+            expect(items.slice(0, pageSize)).toContainEqual(firstPageItem);
+          }
+
+          // Property: Total pages calculation should be consistent
+          const expectedPages = Math.ceil(items.length / pageSize);
+          expect(totalPages.value).toBe(expectedPages);
+
+          // Property: Current page should always be valid
+          expect(currentPage.value).toBeGreaterThanOrEqual(1);
+          expect(currentPage.value).toBeLessThanOrEqual(Math.max(1, totalPages.value));
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+
+  it('should maintain state consistency when changing page size', () => {
+    fc.assert(
+      fc.property(
+        fc.array(fc.record({
+          id: fc.string(),
+          value: fc.integer()
+        }), { minLength: 10, maxLength: 100 }),
+        fc.integer({ min: 5, max: 20 }),
+        fc.integer({ min: 5, max: 30 }),
+        (items, initialPageSize, newPageSize) => {
+          const { currentPage, pageSize, totalPages, setPageSize } = useTable({
+            items,
+            pageSize: initialPageSize
+          });
+
+          const initialTotalPages = totalPages.value;
+
+          // Property: Changing page size should reset to page 1
+          setPageSize(newPageSize);
+          expect(currentPage.value).toBe(1);
+          expect(pageSize.value).toBe(newPageSize);
+
+          // Property: Total pages should update correctly
+          const expectedPages = Math.ceil(items.length / newPageSize);
+          expect(totalPages.value).toBe(expectedPages);
+        }
+      ),
+      { numRuns: 100 }
+    );
+  });
+});