@htlkg/components 0.0.1 → 0.0.2

package/src/composables/useTable.md

@@ -0,0 +1,350 @@
+# useTable Composable
+
+Enhanced table state management composable that integrates seamlessly with the hotelinking/ui `uiTable` component.
+
+## Features
+
+- ✅ **Pagination**: Full pagination support with page size control
+- ✅ **Sorting**: Multi-column sorting with asc/desc order
+- ✅ **Selection**: Row selection with select all/page functionality
+- ✅ **Filtering**: Smart filters with multiple operators (contains, is, >, <, etc.)
+- ✅ **Column Visibility**: Show/hide columns dynamically
+- ✅ **Event Handlers**: Pre-built handlers for all uiTable events
+
+## Basic Usage
+
+```typescript
+import { useTable } from '@htlkg/components/composables';
+
+const table = useTable({
+  items: myData,
+  pageSize: 10,
+  sortKey: 'name',
+  sortOrder: 'asc',
+  idKey: 'id', // optional, defaults to 'id'
+});
+```
+
+## Integration with uiTable
+
+```vue
+<template>
+  <Table
+    :header="tableColumns"
+    :items="table.paginatedItems.value"
+    :loading="loading"
+    :current-page="table.currentPage.value"
+    :total-pages="table.totalPages.value"
+    :total-items="table.totalItems.value"
+    :page-size="table.pageSize.value"
+    :ordered-by="table.sortKey.value"
+    :order-direction="table.sortOrder.value"
+    :hidden-columns="table.hiddenColumns.value"
+    :reset-selected="table.resetSelected.value"
+    :smart-filter-categories="filterCategories"
+    :select-all-items-modal="selectAllModal"
+    @change-page="table.handlePageChange"
+    @change-page-size="table.handlePageSizeChange"
+    @order-by="table.handleOrderBy"
+    @smart-filters-sent="table.handleSmartFiltersApplied"
+    @smart-filters-cleared="table.handleSmartFiltersCleared"
+    @smart-filter-deleted="table.handleSmartFilterDeleted"
+    @columns-visibility-changed="table.handleColumnsVisibilityChanged"
+    @modal-action="table.handleModalAction"
+  />
+</template>
+
+<script setup lang="ts">
+import { useTable } from '@htlkg/components/composables';
+import { Table } from '@htlkg/components/data';
+
+const table = useTable({
+  items: myData,
+  pageSize: 10,
+  sortKey: 'name',
+  sortOrder: 'asc',
+});
+</script>
+```
+
+## API Reference
+
+### Options
+
+```typescript
+interface UseTableOptions<T> {
+  items: T[];              // Array of items to display
+  pageSize?: number;       // Items per page (default: 10)
+  sortKey?: string;        // Initial sort column
+  sortOrder?: 'asc' | 'desc'; // Initial sort order
+  idKey?: string;          // Property to use as unique ID (default: 'id')
+}
+```
+
+### Return Value
+
+```typescript
+interface UseTableReturn<T> {
+  // State - Pagination
+  currentPage: Ref<number>;
+  pageSize: Ref<number>;
+  totalPages: ComputedRef<number>;
+  totalItems: ComputedRef<number>;
+  paginatedItems: ComputedRef<T[]>;
+  
+  // State - Sorting
+  sortKey: Ref<string>;
+  sortOrder: Ref<'asc' | 'desc'>;
+  sortedItems: ComputedRef<T[]>;
+  
+  // State - Selection
+  selectedItems: Ref<T[]>;
+  selectedItemIds: Ref<Set<string | number>>;
+  allSelected: ComputedRef<boolean>;
+  someSelected: ComputedRef<boolean>;
+  
+  // State - Filtering
+  activeFilters: Ref<SmartFilter[]>;
+  filteredItems: ComputedRef<T[]>;
+  
+  // State - Column visibility
+  hiddenColumns: Ref<number[]>;
+  
+  // State - Reset
+  resetSelected: Ref<boolean>;
+  
+  // Methods - Pagination
+  setPage: (page: number) => void;
+  setPageSize: (size: number) => void;
+  handlePageChange: (page: number) => void;
+  handlePageSizeChange: (size: number | string) => void;
+  
+  // Methods - Sorting
+  setSorting: (key: string, order?: 'asc' | 'desc') => void;
+  handleOrderBy: (event: { value: string; orderDirection: 'asc' | 'desc' }) => void;
+  
+  // Methods - Selection
+  selectItem: (item: T) => void;
+  deselectItem: (item: T) => void;
+  selectAll: () => void;
+  selectAllOnPage: () => void;
+  clearSelection: () => void;
+  isSelected: (item: T) => boolean;
+  
+  // Methods - Filtering
+  applyFilters: (filters: SmartFilter[]) => void;
+  clearFilters: () => void;
+  removeFilter: (index: number) => void;
+  handleSmartFiltersApplied: (filters: SmartFilter[]) => void;
+  handleSmartFiltersCleared: () => void;
+  handleSmartFilterDeleted: (index: number) => void;
+  
+  // Methods - Column visibility
+  toggleColumn: (index: number) => void;
+  showColumn: (index: number) => void;
+  hideColumn: (index: number) => void;
+  handleColumnsVisibilityChanged: (event: { index: number; hidden: boolean }) => void;
+  
+  // Methods - Modal actions
+  handleModalAction: (event: { modal: string; action: string }) => void;
+}
+```
+
+### Smart Filters
+
+```typescript
+interface SmartFilter {
+  category: string;  // Field name to filter on
+  operator: string;  // Filter operator: 'contains', 'is', '>', '<', '>=', '<='
+  value: any;        // Filter value
+}
+```
+
+Supported operators:
+- `contains`: String contains (case-insensitive)
+- `is` or `=`: Exact match
+- `>` or `greater`: Greater than (numeric)
+- `<` or `less`: Less than (numeric)
+- `>=` or `greaterOrEqual`: Greater than or equal (numeric)
+- `<=` or `lessOrEqual`: Less than or equal (numeric)
+
+## Examples
+
+### Basic Table with Pagination
+
+```typescript
+const table = useTable({
+  items: accounts,
+  pageSize: 25,
+});
+
+// Use in template
+table.paginatedItems.value // Current page items
+table.currentPage.value    // Current page number
+table.totalPages.value     // Total pages
+```
+
+### With Sorting
+
+```typescript
+const table = useTable({
+  items: accounts,
+  sortKey: 'created_at',
+  sortOrder: 'desc',
+});
+
+// Programmatic sorting
+table.setSorting('name', 'asc');
+
+// Or use the event handler
+@order-by="table.handleOrderBy"
+```
+
+### With Filtering
+
+```typescript
+const table = useTable({
+  items: accounts,
+});
+
+// Apply filters programmatically
+table.applyFilters([
+  { category: 'name', operator: 'contains', value: 'hotel' },
+  { category: 'status', operator: 'is', value: 'active' },
+]);
+
+// Or use the event handlers
+@smart-filters-sent="table.handleSmartFiltersApplied"
+@smart-filters-cleared="table.handleSmartFiltersCleared"
+```
+
+### With Selection
+
+```typescript
+const table = useTable({
+  items: accounts,
+  idKey: 'account_id', // Use custom ID field
+});
+
+// Check selection state
+table.selectedItems.value      // Array of selected items
+table.selectedItemIds.value    // Set of selected IDs
+table.allSelected.value        // All items selected?
+table.someSelected.value       // Some items selected?
+
+// Programmatic selection
+table.selectItem(account);
+table.selectAll();
+table.clearSelection();
+```
+
+### Complete Example
+
+```vue
+<template>
+  <div>
+    <!-- Stats -->
+    <div class="stats">
+      <div>Total: {{ table.totalItems.value }}</div>
+      <div>Selected: {{ table.selectedItems.value.length }}</div>
+    </div>
+
+    <!-- Table -->
+    <Table
+      :header="columns"
+      :items="tableItems"
+      :current-page="table.currentPage.value"
+      :total-pages="table.totalPages.value"
+      :total-items="table.totalItems.value"
+      :page-size="table.pageSize.value"
+      :ordered-by="table.sortKey.value"
+      :order-direction="table.sortOrder.value"
+      :hidden-columns="table.hiddenColumns.value"
+      :reset-selected="table.resetSelected.value"
+      :smart-filter-categories="filterCategories"
+      @change-page="table.handlePageChange"
+      @change-page-size="table.handlePageSizeChange"
+      @order-by="table.handleOrderBy"
+      @smart-filters-sent="table.handleSmartFiltersApplied"
+      @smart-filters-cleared="table.handleSmartFiltersCleared"
+      @smart-filter-deleted="table.handleSmartFilterDeleted"
+      @columns-visibility-changed="table.handleColumnsVisibilityChanged"
+      @modal-action="table.handleModalAction"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useTable } from '@htlkg/components/composables';
+import { Table } from '@htlkg/components/data';
+
+// Your data
+const accounts = ref([...]);
+
+// Initialize table
+const table = useTable({
+  items: accounts.value,
+  pageSize: 10,
+  sortKey: 'name',
+  sortOrder: 'asc',
+  idKey: 'id',
+});
+
+// Transform data for display
+const tableItems = computed(() => {
+  return table.paginatedItems.value.map(account => ({
+    id: account.id,
+    row: [
+      account.name,
+      { content: account.status, type: 'tag', color: 'green' },
+      account.created_at,
+    ],
+  }));
+});
+
+// Table configuration
+const columns = [
+  { name: 'Name', value: 'name' },
+  { name: 'Status', value: 'status' },
+  { name: 'Created', value: 'created_at' },
+];
+
+const filterCategories = [
+  {
+    id: 'name',
+    name: 'Name',
+    componentType: 'uiInput',
+    defaultProps: { placeholder: 'Search...' },
+  },
+];
+</script>
+```
+
+## Best Practices
+
+1. **Use computed for items**: Pass reactive data to `useTable` for automatic updates
+2. **Transform data separately**: Keep raw data in `useTable`, transform for display in computed
+3. **Custom ID keys**: Use `idKey` option when your items don't have an `id` property
+4. **Event handlers**: Use the built-in `handle*` methods for seamless uiTable integration
+5. **Filter logic**: The composable handles AND logic by default; customize if needed
+
+## Migration from Manual State
+
+Before:
+```typescript
+const currentPage = ref(1);
+const pageSize = ref(10);
+const sortKey = ref('name');
+// ... lots of manual state management
+```
+
+After:
+```typescript
+const table = useTable({
+  items: myData,
+  pageSize: 10,
+  sortKey: 'name',
+});
+// All state and handlers included!
+```