@htlkg/components 0.0.11 → 0.0.13

package/src/patterns/LIST_PAGE.md

@@ -0,0 +1,340 @@
+# List Page Pattern
+
+Display collections of data with filtering, sorting, pagination, and bulk actions.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ AdminLayout                                                  │
+├─────────────────────────────────────────────────────────────┤
+│ Page Header (title + breadcrumbs)                           │
+├─────────────────────────────────────────────────────────────┤
+│ Optional: Tabs (for multiple views)                         │
+├─────────────────────────────────────────────────────────────┤
+│ Optional: Stats Grid (summary metrics)                      │
+├─────────────────────────────────────────────────────────────┤
+│ DataTable                                                    │
+│ ├── Smart Filters                                           │
+│ ├── Column Headers (sortable)                               │
+│ ├── Data Rows (selectable)                                  │
+│ ├── Row Actions                                             │
+│ └── Pagination                                              │
+├─────────────────────────────────────────────────────────────┤
+│ Optional: Modal (for row actions)                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## CRM Template Reference
+
+Based on: `ui/src/components/Templates/CRM/ContactsAll.vue`
+
+```vue
+<!-- CRM Template Structure (raw @hotelinking/ui) -->
+<uiWrapper :sidebar :topbar>
+  <uiViewHeader :pages="pages" title="Contacts" />
+  <uiTabs :tabs="tabs" @tabClicked="handleTabClick" />
+
+  <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mb-8">
+    <uiStats v-for="stat in stats" :item="stat" />
+  </div>
+
+  <uiTable
+    :header="tableHeader"
+    :items="tableItems"
+    :smartFilterCategories="smartFilterCategories"
+    :paginationCurrent="paginationCurrent"
+    @smartFiltersSent="handleSmartFilters"
+    @changePage="handlePageChange"
+  />
+</uiWrapper>
+```
+
+## Enhanced Pattern (with @htlkg/*)
+
+### Astro Page
+
+```astro
+---
+// src/pages/admin/contacts.astro
+import Layout from '@/layouts/Layout.astro';
+import ContactsView from '@/components/admin/ContactsView.vue';
+import { createListPage } from '@htlkg/astro';
+import { $contacts } from '@/stores/contacts';
+
+export const prerender = false;
+
+const { layoutProps, initialState, items } = await createListPage(Astro, {
+  title: 'Contacts',
+  pageId: 'contacts',
+  fetchFn: async () => {
+    // Fetch contacts from API or database
+    return { data: await getContacts() };
+  },
+  store: $contacts,
+  filterableFields: [
+    { key: 'name', type: 'text', graphql: false },
+    { key: 'email', type: 'text', graphql: false },
+    { key: 'status', type: 'select', graphql: false, options: [
+      { id: 'active', name: 'Active' },
+      { id: 'inactive', name: 'Inactive' },
+    ]},
+  ],
+  searchableFields: ['name', 'email'],
+  defaultSort: { key: 'name', order: 'asc' },
+  defaultPageSize: 25,
+});
+---
+
+<Layout {...layoutProps}>
+  <ContactsView client:load initialState={initialState} />
+</Layout>
+```
+
+### Vue Component
+
+```vue
+<!-- src/components/admin/ContactsView.vue -->
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { useStore } from '@nanostores/vue';
+import { DataTable, columns } from '@htlkg/components/data';
+import { Modal } from '@htlkg/components/overlays';
+import { useTable, useModal, useTabs } from '@htlkg/components/composables';
+import { $contacts } from '@/stores/contacts';
+
+interface Props {
+  initialState: {
+    pageSize: number;
+    sortKey: string;
+    sortOrder: 'asc' | 'desc';
+  };
+}
+
+const props = defineProps<Props>();
+
+// Data from store
+const contacts = useStore($contacts);
+
+// Tab state
+const { activeTab, tabs, setActiveTab } = useTabs({
+  tabs: [
+    { id: 'all', label: 'All Contacts' },
+    { id: 'tags', label: 'Tags' },
+    { id: 'segments', label: 'Segments' },
+  ],
+  defaultTab: 'all',
+});
+
+// Table state
+const {
+  items,
+  currentPage,
+  pageSize,
+  totalPages,
+  sortKey,
+  sortOrder,
+  goToPage,
+  setPageSize,
+  setSortBy,
+  setFilter,
+} = useTable({
+  items: contacts,
+  pageSize: props.initialState.pageSize,
+  defaultSort: {
+    key: props.initialState.sortKey,
+    order: props.initialState.sortOrder,
+  },
+});
+
+// Modal for contact details
+const contactModal = useModal<Contact>();
+
+// Table columns
+const tableColumns = computed(() => [
+  columns.link('name', 'Name', {
+    onClick: (row) => contactModal.open(row),
+  }),
+  columns.text('email', 'Email'),
+  columns.text('phone', 'Phone'),
+  columns.text('country', 'Country'),
+  columns.tag('status', 'Status', {
+    colorMap: {
+      active: 'green',
+      inactive: 'gray',
+      vip: 'yellow',
+    },
+  }),
+  columns.tag('loyaltyTier', 'Loyalty Tier'),
+  columns.text('tags', 'Tags'),
+]);
+
+// Stats for header
+const stats = computed(() => [
+  {
+    id: 'total',
+    name: 'Total Contacts',
+    stat: contacts.value.length.toLocaleString(),
+    icon: 'UsersIcon',
+    color: 'green',
+  },
+  {
+    id: 'new',
+    name: 'New This Month',
+    stat: '1.2K',
+    icon: 'PlusIcon',
+    color: 'green',
+  },
+]);
+
+// Row actions
+const rowActions = [
+  { name: 'Edit', id: 'edit' },
+  { name: 'Delete', id: 'delete' },
+];
+
+function handleRowAction(action: string, items: number[]) {
+  if (action === 'delete') {
+    // Handle delete
+  }
+}
+</script>
+
+<template>
+  <!-- Tabs -->
+  <div class="mb-6">
+    <nav class="flex space-x-4">
+      <button
+        v-for="tab in tabs"
+        :key="tab.id"
+        :class="[
+          'px-3 py-2 text-sm font-medium rounded-md',
+          activeTab === tab.id
+            ? 'bg-gray-100 text-gray-900'
+            : 'text-gray-500 hover:text-gray-700'
+        ]"
+        @click="setActiveTab(tab.id)"
+      >
+        {{ tab.label }}
+      </button>
+    </nav>
+  </div>
+
+  <!-- Stats Grid -->
+  <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mb-8">
+    <div
+      v-for="stat in stats"
+      :key="stat.id"
+      class="bg-white rounded-lg border border-gray-200 p-6"
+    >
+      <p class="text-sm font-medium text-gray-500">{{ stat.name }}</p>
+      <p class="mt-1 text-3xl font-semibold text-gray-900">{{ stat.stat }}</p>
+    </div>
+  </div>
+
+  <!-- Data Table -->
+  <DataTable
+    :columns="tableColumns"
+    :items="items"
+    :current-page="currentPage"
+    :page-size="pageSize"
+    :total-pages="totalPages"
+    :sort-key="sortKey"
+    :sort-order="sortOrder"
+    :actions="rowActions"
+    @page-change="goToPage"
+    @page-size-change="setPageSize"
+    @sort-change="setSortBy"
+    @action="handleRowAction"
+  />
+
+  <!-- Contact Detail Modal -->
+  <Modal
+    :open="contactModal.isOpen.value"
+    :title="contactModal.data.value?.name || 'Contact Details'"
+    @close="contactModal.close"
+  >
+    <div v-if="contactModal.data.value" class="space-y-4">
+      <p><strong>Email:</strong> {{ contactModal.data.value.email }}</p>
+      <p><strong>Phone:</strong> {{ contactModal.data.value.phone }}</p>
+      <p><strong>Status:</strong> {{ contactModal.data.value.status }}</p>
+    </div>
+  </Modal>
+</template>
+```
+
+## Key Components
+
+### DataTable
+
+```typescript
+import { DataTable, columns } from '@htlkg/components/data';
+
+// Column helpers
+columns.text('field', 'Label')           // Plain text
+columns.link('field', 'Label', options)  // Clickable link
+columns.tag('field', 'Label', options)   // Tag/badge
+columns.date('field', 'Label', format)   // Formatted date
+columns.currency('field', 'Label')       // Currency formatting
+columns.custom('field', 'Label', render) // Custom render function
+```
+
+### useTable Composable
+
+```typescript
+import { useTable } from '@htlkg/components/composables';
+
+const {
+  items,           // Paginated, sorted, filtered items
+  currentPage,     // Current page number
+  pageSize,        // Items per page
+  totalPages,      // Total page count
+  totalItems,      // Total item count
+  sortKey,         // Current sort field
+  sortOrder,       // 'asc' | 'desc'
+  filters,         // Active filters
+  goToPage,        // Navigate to page
+  setPageSize,     // Change page size
+  setSortBy,       // Change sort
+  setFilter,       // Apply filter
+  clearFilters,    // Clear all filters
+} = useTable(options);
+```
+
+### Smart Filters
+
+```typescript
+const filterableFields = [
+  {
+    key: 'name',
+    type: 'text',      // Text input filter
+    placeholder: 'Search by name...',
+  },
+  {
+    key: 'status',
+    type: 'select',    // Dropdown filter
+    options: [
+      { id: 'active', name: 'Active' },
+      { id: 'inactive', name: 'Inactive' },
+    ],
+  },
+  {
+    key: 'createdAt',
+    type: 'date',      // Date range filter
+  },
+];
+```
+
+## Checklist
+
+- [ ] Astro page with `createListPage` factory
+- [ ] Vue component with `DataTable`
+- [ ] `useTable` composable for state
+- [ ] Column definitions with helpers
+- [ ] Smart filters for searchable fields
+- [ ] Pagination controls
+- [ ] Sort by column headers
+- [ ] Row actions (edit, delete, etc.)
+- [ ] Optional: Tabs for multiple views
+- [ ] Optional: Stats grid at top
+- [ ] Optional: Modal for row details

package/src/patterns/PAGE_PATTERNS.md

@@ -0,0 +1,110 @@
+# Page Patterns Overview
+
+This documentation describes the standard page patterns used in Hotelinking applications. These patterns are based on the CRM template examples in `@hotelinking/ui` but enhanced to use `@htlkg/*` shared packages.
+
+## Pattern Selection Guide
+
+| Pattern | Use When | Example |
+|---------|----------|---------|
+| **List Page** | Displaying collections of data with filtering, sorting, pagination | Contacts, Campaigns, Bookings |
+| **Detail Page** | Showing comprehensive info about a single entity | Booking Details, Contact Profile |
+| **Form Page** | Creating or editing entity data | Settings, Brand Configuration |
+| **Wizard Page** | Multi-step data entry with progress indicator | Campaign Creation, Onboarding |
+| **Dashboard Page** | Displaying metrics, KPIs, and analytics | Overview, Analytics |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Astro Page (.astro)                                         │
+│ - Server-side data fetching                                 │
+│ - Pass data to Vue islands                                  │
+└─────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│ @htlkg/astro Layout (AdminLayout, BrandLayout)             │
+│ - Sidebar navigation                                        │
+│ - Topbar with user menu                                     │
+│ - Page structure                                            │
+└─────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Vue Component (client:load)                                 │
+│ - Interactive UI                                            │
+│ - Uses @htlkg/components                                    │
+│ - Uses composables for state                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## CRM to @htlkg/* Mapping
+
+| CRM Template Component | @htlkg/* Replacement |
+|-----------------------|----------------------|
+| `uiWrapper` | `AdminLayout` from `@htlkg/astro/layouts` |
+| `uiViewHeader` | Built into layout or `PageHeader` component |
+| `uiTable` | `DataTable` from `@htlkg/components/data` + `useTable` |
+| `uiModal` | `Modal` from `@htlkg/components/overlays` + `useModal` |
+| `uiTabs` | `Tabs` from `@htlkg/components/navigation` + `useTabs` |
+| `uiStats` | Stats pattern with grid layout |
+| Manual form state | `JsonSchemaForm` + `useJsonForm` composable |
+| `uiStepsV4` | `Stepper` from `@htlkg/components/navigation` + `useWizard` |
+
+## Key Composables
+
+| Composable | Purpose | Import |
+|------------|---------|--------|
+| `useTable` | Table state (sort, filter, pagination) | `@htlkg/components/composables` |
+| `useModal` | Modal visibility and data context | `@htlkg/components/composables` |
+| `useJsonForm` | Form state with isDirty, confirmOnLeave | `@htlkg/components/composables` |
+| `useConfirmation` | Delete/reset confirmation dialogs | `@htlkg/components/composables` |
+| `useTabs` | Tab navigation state | `@htlkg/components/composables` |
+| `useWizard` | Multi-step wizard navigation | `@htlkg/components/composables` |
+| `useNotifications` | Toast notifications | `@htlkg/components/composables` |
+
+## Pattern Documentation
+
+- [LIST_PAGE.md](./LIST_PAGE.md) - List/table page pattern
+- [DETAIL_PAGE.md](./DETAIL_PAGE.md) - Detail page pattern
+- [FORM_PAGE.md](./FORM_PAGE.md) - Form page pattern
+- [WIZARD_PAGE.md](./WIZARD_PAGE.md) - Multi-step wizard pattern
+- [DASHBOARD_PAGE.md](./DASHBOARD_PAGE.md) - Dashboard page pattern
+
+## Common Structure
+
+All patterns follow this basic structure:
+
+```astro
+---
+// 1. Imports
+import Layout from '@/layouts/Layout.astro';
+import MyComponent from '@/components/MyComponent.vue';
+
+// 2. Server-side data fetching
+const data = await fetchData();
+
+// 3. Page metadata
+const title = 'Page Title';
+const breadcrumbs = [
+  { name: 'Home', href: '/' },
+  { name: 'Current', current: true }
+];
+---
+
+<!-- 4. Layout wrapper -->
+<Layout title={title} breadcrumbs={breadcrumbs}>
+  <!-- 5. Vue island for interactivity -->
+  <MyComponent client:load initialData={data} />
+</Layout>
+```
+
+## Best Practices
+
+1. **Data Fetching**: Always fetch data server-side in Astro frontmatter
+2. **Hydration**: Use `client:load` for interactive components
+3. **State**: Use composables from `@htlkg/components/composables`
+4. **Forms**: Use `JsonSchemaForm` for all forms except very simple ones
+5. **Modals**: Use `useModal` composable with data context
+6. **Tables**: Use `DataTable` with `useTable` for consistent behavior
+7. **Validation**: Let JsonSchemaForm handle validation via JSON Schema