@htlkg/components 0.0.1

package/src/data/Table.md

@@ -0,0 +1,588 @@
+# Table Component
+
+A comprehensive data table component with pagination, sorting, filtering, selection, and column management. Wraps `@hotelinking/ui`'s `uiTable` component with advanced state management.
+
+## Features
+
+- **Pagination**: Configurable page sizes with navigation
+- **Sorting**: Column-based sorting with ascending/descending order
+- **Selection**: Multi-select with bulk actions
+- **Smart Filters**: Advanced filtering with multiple criteria
+- **Column Management**: Show/hide columns dynamically
+- **Empty States**: Customizable no-data and no-results states
+- **Loading States**: Skeleton loading indicators
+- **Actions**: Dropdown actions and custom action buttons
+- **Refresh**: Optional data refresh functionality
+- **Responsive**: Mobile-friendly design
+
+## Import
+
+```typescript
+import { Table } from '@htlkg/components';
+// or
+import { Table } from '@htlkg/components/data';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `T[]` | required | Array of data items to display |
+| `columns` | `Column[]` | required | Column definitions |
+| `loading` | `boolean` | `false` | Show loading state |
+| `currentPage` | `number` | `1` | Current page number (v-model) |
+| `totalPages` | `number` | `1` | Total number of pages |
+| `totalItems` | `number` | `0` | Total number of items |
+| `itemsPerPage` | `number` | `10` | Items per page (v-model) |
+| `orderedBy` | `string` | `''` | Current sort column (v-model) |
+| `orderDirection` | `'asc' \| 'desc'` | `'asc'` | Sort direction (v-model) |
+| `actions` | `Array<{name: string, id: string}>` | `[]` | Bulk action options |
+| `selectAllItemsModal` | `UiModalInterface` | - | Modal for select all confirmation |
+| `availableCategories` | `FilterCategory[]` | `[]` | Smart filter categories |
+| `filterLiterals` | `FilterLiterals` | - | Filter UI text labels |
+| `tableActionsDropdown` | `{items: UiDropdownItemType[], loading?: boolean}` | - | Custom actions dropdown |
+| `tableActionButtons` | `any[]` | `[]` | Custom action buttons |
+| `noResults` | `NoResultsConfig` | - | Custom no results configuration |
+| `showRefresh` | `boolean` | `false` | Show refresh action |
+| `showFilters` | `boolean` | `true` | Show filter section |
+| `showPagination` | `boolean` | `true` | Show pagination controls |
+
+### Column Interface
+
+```typescript
+interface Column {
+  name: string;      // Display name
+  value: string;     // Property key in data
+  tooltip?: string;  // Optional tooltip
+}
+```
+
+### FilterCategory Interface
+
+```typescript
+interface FilterCategory {
+  name: string;
+  label: string;
+  componentType: 'uiInput' | 'uiSelect';
+  defaultProps: any;
+}
+```
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:currentPage` | `number` | Page changed |
+| `update:itemsPerPage` | `number` | Page size changed |
+| `update:selected` | `T[]` | Selected items changed |
+| `update:orderedBy` | `string` | Sort column changed |
+| `update:orderDirection` | `'asc' \| 'desc'` | Sort direction changed |
+| `refresh:data` | - | Refresh requested |
+| `table-action` | `{action: string, items: Array<string \| number>}` | Bulk action triggered |
+| `table-action-selected` | `any` | Single item action |
+| `table-action-button-clicked` | `{id: string, text: string}` | Action button clicked |
+| `smart-filters-sent` | `any` | Filters applied |
+| `smart-filters-cleared` | - | Filters cleared |
+| `smart-filter-deleted` | `number` | Single filter removed |
+| `custom-emit` | `any` | Custom event from table |
+| `modal-action` | `{modal: string, action: string}` | Modal action |
+| `select-all-items` | - | All items selected |
+| `deselect-all-items` | - | All items deselected |
+| `no-results-action` | `string` | No results action clicked |
+| `no-results-option-selected` | `any` | No results option selected |
+| `order-changed` | `string, 'asc' \| 'desc'` | Sort changed |
+| `page-changed` | `number` | Page changed |
+| `items-per-page-changed` | `number` | Page size changed |
+| `multiple-filters-applied` | `any` | Multiple filters applied |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `actions` | Custom action buttons in filter section |
+
+## Exposed Methods
+
+| Method | Description |
+|--------|-------------|
+| `clearSelection()` | Clear all selected items |
+| `getHiddenColumns()` | Get array of hidden column indices |
+| `getSelectedItems()` | Get array of selected item IDs |
+
+## Usage Examples
+
+### Basic Table
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const columns = [
+  { name: 'ID', value: 'id' },
+  { name: 'Name', value: 'name' },
+  { name: 'Email', value: 'email' },
+  { name: 'Status', value: 'status' }
+];
+
+const items = [
+  { id: 1, name: 'John Doe', email: 'john@example.com', status: 'active' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'inactive' },
+  { id: 3, name: 'Bob Johnson', email: 'bob@example.com', status: 'active' }
+];
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+  />
+</template>
+```
+
+### Table with Pagination
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const currentPage = ref(1);
+const itemsPerPage = ref(10);
+const totalItems = ref(100);
+const totalPages = ref(10);
+
+const columns = [
+  { name: 'ID', value: 'id' },
+  { name: 'Name', value: 'name' }
+];
+
+const items = ref([]);
+
+const loadPage = async (page: number) => {
+  // Fetch data for page
+  const response = await fetchUsers(page, itemsPerPage.value);
+  items.value = response.data;
+};
+
+const handlePageChange = (page: number) => {
+  currentPage.value = page;
+  loadPage(page);
+};
+
+const handlePageSizeChange = (size: number) => {
+  itemsPerPage.value = size;
+  currentPage.value = 1;
+  loadPage(1);
+};
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+    v-model:currentPage="currentPage"
+    v-model:itemsPerPage="itemsPerPage"
+    :totalItems="totalItems"
+    :totalPages="totalPages"
+    @page-changed="handlePageChange"
+    @items-per-page-changed="handlePageSizeChange"
+  />
+</template>
+```
+
+### Table with Sorting
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const orderedBy = ref('name');
+const orderDirection = ref<'asc' | 'desc'>('asc');
+
+const columns = [
+  { name: 'Name', value: 'name' },
+  { name: 'Email', value: 'email' },
+  { name: 'Created', value: 'createdAt' }
+];
+
+const items = ref([]);
+
+const handleSort = (field: string, direction: 'asc' | 'desc') => {
+  orderedBy.value = field;
+  orderDirection.value = direction;
+  
+  // Sort items or fetch sorted data
+  items.value = sortItems(items.value, field, direction);
+};
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+    v-model:orderedBy="orderedBy"
+    v-model:orderDirection="orderDirection"
+    @order-changed="handleSort"
+  />
+</template>
+```
+
+### Table with Selection and Bulk Actions
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const selectedItems = ref([]);
+
+const columns = [
+  { name: 'Name', value: 'name' },
+  { name: 'Email', value: 'email' }
+];
+
+const items = ref([
+  { id: 1, name: 'John Doe', email: 'john@example.com' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+]);
+
+const actions = [
+  { name: 'Delete', id: 'delete' },
+  { name: 'Export', id: 'export' },
+  { name: 'Archive', id: 'archive' }
+];
+
+const handleBulkAction = ({ action, items: itemIds }) => {
+  if (action === 'delete') {
+    deleteItems(itemIds);
+  } else if (action === 'export') {
+    exportItems(itemIds);
+  } else if (action === 'archive') {
+    archiveItems(itemIds);
+  }
+};
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+    :actions="actions"
+    v-model:selected="selectedItems"
+    @table-action="handleBulkAction"
+  />
+</template>
+```
+
+### Table with Smart Filters
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const columns = [
+  { name: 'Name', value: 'name' },
+  { name: 'Status', value: 'status' },
+  { name: 'Role', value: 'role' }
+];
+
+const items = ref([]);
+
+const availableCategories = [
+  {
+    name: 'name',
+    label: 'Name',
+    componentType: 'uiInput',
+    defaultProps: { placeholder: 'Search by name' }
+  },
+  {
+    name: 'status',
+    label: 'Status',
+    componentType: 'uiSelect',
+    defaultProps: {
+      items: [
+        { id: 'active', name: 'Active' },
+        { id: 'inactive', name: 'Inactive' }
+      ]
+    }
+  }
+];
+
+const filterLiterals = {
+  filters: 'Smart Filters',
+  contains: 'contains',
+  is: 'is',
+  and: 'and',
+  or: 'or',
+  deleteAll: 'Delete All',
+  filter: 'Filter'
+};
+
+const handleFiltersApplied = (filters) => {
+  // Apply filters to data
+  items.value = applyFilters(items.value, filters);
+};
+
+const handleFiltersClear = () => {
+  // Reset to original data
+  items.value = originalItems;
+};
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+    :availableCategories="availableCategories"
+    :filterLiterals="filterLiterals"
+    @smart-filters-sent="handleFiltersApplied"
+    @smart-filters-cleared="handleFiltersClear"
+  />
+</template>
+```
+
+### Table with Loading State
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+import { Table } from '@htlkg/components';
+
+const loading = ref(true);
+const items = ref([]);
+
+const columns = [
+  { name: 'Name', value: 'name' },
+  { name: 'Email', value: 'email' }
+];
+
+onMounted(async () => {
+  loading.value = true;
+  items.value = await fetchUsers();
+  loading.value = false;
+});
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+    :loading="loading"
+  />
+</template>
+```
+
+### Table with Custom Empty State
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const columns = [
+  { name: 'Name', value: 'name' }
+];
+
+const items = ref([]);
+
+const noResults = {
+  title: 'No users found',
+  message: 'Get started by creating your first user',
+  actions: [
+    { action: 'create', text: 'Create User' }
+  ]
+};
+
+const handleNoResultsAction = (action) => {
+  if (action === 'create') {
+    // Navigate to create user page
+    router.push('/users/create');
+  }
+};
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+    :noResults="noResults"
+    @no-results-action="handleNoResultsAction"
+  />
+</template>
+```
+
+### Table with Refresh
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const columns = [
+  { name: 'Name', value: 'name' }
+];
+
+const items = ref([]);
+
+const refreshData = async () => {
+  items.value = await fetchUsers();
+};
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+    :showRefresh="true"
+    @refresh:data="refreshData"
+  />
+</template>
+```
+
+### Table with Custom Actions Slot
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const columns = [
+  { name: 'Name', value: 'name' }
+];
+
+const items = ref([]);
+
+const exportData = () => {
+  // Export logic
+};
+
+const importData = () => {
+  // Import logic
+};
+</script>
+
+<template>
+  <Table
+    :items="items"
+    :columns="columns"
+  >
+    <template #actions>
+      <button @click="exportData" class="btn btn-primary">
+        Export
+      </button>
+      <button @click="importData" class="btn btn-secondary">
+        Import
+      </button>
+    </template>
+  </Table>
+</template>
+```
+
+### Programmatic Control
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import { Table } from '@htlkg/components';
+
+const tableRef = ref();
+
+const clearSelection = () => {
+  tableRef.value?.clearSelection();
+};
+
+const getSelected = () => {
+  const selected = tableRef.value?.getSelectedItems();
+  console.log('Selected items:', selected);
+};
+
+const getHidden = () => {
+  const hidden = tableRef.value?.getHiddenColumns();
+  console.log('Hidden columns:', hidden);
+};
+</script>
+
+<template>
+  <div>
+    <button @click="clearSelection">Clear Selection</button>
+    <button @click="getSelected">Get Selected</button>
+    <button @click="getHidden">Get Hidden Columns</button>
+    
+    <Table
+      ref="tableRef"
+      :items="items"
+      :columns="columns"
+    />
+  </div>
+</template>
+```
+
+## Best Practices
+
+### Performance
+
+- Use pagination for large datasets (>100 items)
+- Implement server-side sorting and filtering for very large datasets
+- Debounce filter inputs to reduce API calls
+- Use virtual scrolling for extremely large tables
+
+### Accessibility
+
+- Provide meaningful column names
+- Use tooltips for abbreviated headers
+- Ensure keyboard navigation works
+- Add ARIA labels for screen readers
+
+### UX Guidelines
+
+- Show loading states during data fetches
+- Provide clear empty states with actionable next steps
+- Use appropriate page sizes (10, 25, 50, 100)
+- Reset to page 1 when filters or page size changes
+- Clear selection when sorting or paginating
+- Provide feedback for bulk actions
+
+## Design System Integration
+
+This component wraps `@hotelinking/ui`'s `uiTable`, `uiPagination`, `uiDropdown`, `uiSmartFilterMultipleV2`, and `uiNoResults` components, providing:
+
+- Unified state management for pagination, sorting, and selection
+- Smart filter integration with multiple criteria
+- Column visibility management
+- Empty state handling
+- Event normalization and consolidation
+- Consistent API with other data components
+
+## Related Components
+
+- **DataList**: For simpler list displays
+- **SearchableSelect**: For searchable dropdown selections
+- **JsonSchemaForm**: For form-based data entry
+
+## Demo
+
+See the [Table demo page](/components/table) for interactive examples.
+
+## TypeScript Support
+
+```typescript
+import type { Column } from '@htlkg/components';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  status: 'active' | 'inactive';
+}
+
+const columns: Column[] = [
+  { name: 'Name', value: 'name' },
+  { name: 'Email', value: 'email' },
+  { name: 'Status', value: 'status' }
+];
+
+const items = ref<User[]>([]);
+```