@htlkg/components 0.0.11 → 0.0.13

package/src/patterns/DASHBOARD_PAGE.md

@@ -0,0 +1,642 @@
+# Dashboard Page Pattern
+
+Display key metrics, statistics, and charts with date range filtering and tabbed navigation.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ AdminLayout                                                  │
+├─────────────────────────────────────────────────────────────┤
+│ Page Header (title + breadcrumbs)                           │
+├─────────────────────────────────────────────────────────────┤
+│ Date Range Filter (right-aligned)                           │
+├─────────────────────────────────────────────────────────────┤
+│ Tabs (Overview | Campaigns | Revenue | Contacts | ...)      │
+├─────────────────────────────────────────────────────────────┤
+│ Stats Grid (1-4 columns)                                    │
+│ ├── Stat 1: Active Campaigns   │ Stat 2: Total Contacts    │
+│ └── Stat 3: Reservations       │ Stat 4: Revenue           │
+├─────────────────────────────────────────────────────────────┤
+│ Section Title (e.g., "Email Performance")                   │
+├─────────────────────────────────────────────────────────────┤
+│ Stats Grid (Secondary metrics)                              │
+│ ├── Email Delivered │ Open Rate │ CTR │ Deliverability     │
+├─────────────────────────────────────────────────────────────┤
+│ Charts Grid (2 columns)                                     │
+│ ├── Chart 1: Database Growth   │ Chart 2: Database Health  │
+│ └── Chart 3: Engagement        │ Chart 4: Revenue          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## CRM Template Reference
+
+Based on: `ui/src/components/Templates/CRM/Dashboard.vue`
+
+```vue
+<!-- CRM Template Structure (raw @hotelinking/ui) -->
+<uiWrapper :sidebar :topbar>
+  <uiViewHeader :pages="pages" title="Dashboard - Overview" :loading="loadingHeader" />
+
+  <!-- Date Range Filter -->
+  <div class="flex justify-end items-center mb-4 w-full">
+    <uiDateRange
+      id="charts-date-range"
+      :literals="{ from: 'From', to: 'To', search: 'Search' }"
+      :values="dateRangeValues"
+      :loading="loadingDateRange"
+      @uiDateRangeButtonClicked="handleDateRangeSearch"
+    />
+  </div>
+
+  <!-- Tabs -->
+  <uiTabs :tabs="tabs" @tabClicked="handleTabClick" />
+
+  <!-- Primary Stats Grid -->
+  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 my-8">
+    <uiStats
+      v-for="(stat, index) in stats"
+      :key="stat.id"
+      :item="stat"
+      :loading="loadingStats[index]"
+      @statClick="handleStatClick"
+    />
+  </div>
+
+  <!-- Section Title -->
+  <uiSectionTitle title="Email Performance Overview" />
+
+  <!-- Secondary Stats Grid -->
+  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 mb-8">
+    <uiStats
+      v-for="(stat, index) in emailStats"
+      :key="stat.id"
+      :item="stat"
+      :loading="loadingEmailStats[index]"
+    />
+  </div>
+
+  <!-- Charts Grid -->
+  <div class="grid grid-cols-1 lg:grid-cols-2 gap-4">
+    <uiChart
+      id="database-growth"
+      title="Database Growth"
+      type="area"
+      :series="series"
+      :options="options"
+      :loading="loadingChart"
+    />
+    <!-- More charts... -->
+  </div>
+</uiWrapper>
+```
+
+## Enhanced Pattern (with @htlkg/*)
+
+### Astro Page
+
+```astro
+---
+// src/pages/[brandId]/admin/dashboard.astro
+import Layout from '@/layouts/Layout.astro';
+import DashboardView from '@/components/admin/DashboardView.vue';
+import { getDashboardData } from '@/services/dashboard';
+
+export const prerender = false;
+
+const { brandId } = Astro.params;
+const initialData = await getDashboardData(brandId);
+
+const layoutProps = {
+  title: 'Dashboard',
+  breadcrumbs: [
+    { name: 'Dashboard', current: true },
+  ],
+};
+---
+
+<Layout {...layoutProps}>
+  <DashboardView client:load brandId={brandId} initialData={initialData} />
+</Layout>
+```
+
+### Vue Component with useStats
+
+```vue
+<!-- src/components/admin/DashboardView.vue -->
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { Chart } from '@htlkg/components/data';
+import { DateRange } from '@htlkg/components/forms';
+import { useStats, useTabs, countStat, sumStat, percentageStat } from '@htlkg/components/composables';
+import { uiStats, uiSectionTitle } from '@hotelinking/ui';
+import {
+  MegaphoneIcon,
+  UsersIcon,
+  CalendarIcon,
+  CurrencyDollarIcon,
+  EnvelopeIcon,
+  EyeIcon,
+  CursorArrowRaysIcon,
+  CheckCircleIcon,
+} from '@heroicons/vue/24/outline';
+
+interface DashboardData {
+  campaigns: Campaign[];
+  contacts: Contact[];
+  reservations: Reservation[];
+  emailStats: EmailStats;
+}
+
+interface Props {
+  brandId: string;
+  initialData: DashboardData;
+}
+
+const props = defineProps<Props>();
+
+// Date range state
+const dateRange = ref({
+  from: '',
+  to: new Date().toISOString().slice(0, 16),
+});
+
+// Tabs
+const { tabs, activeTab, setActiveTab } = useTabs({
+  tabs: [
+    { id: 'overview', label: 'Overview' },
+    { id: 'campaigns', label: 'Campaigns' },
+    { id: 'revenue', label: 'Revenue' },
+    { id: 'contacts', label: 'Contacts' },
+    { id: 'insights', label: 'Insights' },
+  ],
+  initialTab: 'overview',
+});
+
+// Data refs (would come from data hooks in real app)
+const campaigns = ref(props.initialData.campaigns);
+const contacts = ref(props.initialData.contacts);
+const reservations = ref(props.initialData.reservations);
+const loading = ref(false);
+
+// Primary Stats with useStats
+const { statsWithLoading: primaryStats } = useStats({
+  data: computed(() => ({
+    campaigns: campaigns.value,
+    contacts: contacts.value,
+    reservations: reservations.value,
+  })),
+  loading,
+  definitions: [
+    {
+      id: 'active-campaigns',
+      name: 'Active Campaigns',
+      icon: MegaphoneIcon,
+      color: 'green',
+      compute: (data) => data.campaigns.filter(c => c.status === 'active').length,
+      computeChange: () => '+12.5%',
+      computeChangeType: () => 'increase',
+      showFooter: true,
+      actionText: 'View all',
+    },
+    {
+      id: 'total-contacts',
+      name: 'Total Contacts',
+      icon: UsersIcon,
+      color: 'green',
+      compute: (data) => data.contacts.length,
+      computeChange: () => '+8.2%',
+      computeChangeType: () => 'increase',
+      showFooter: true,
+      actionText: 'View all',
+    },
+    {
+      id: 'active-reservations',
+      name: 'Active Reservations',
+      icon: CalendarIcon,
+      color: 'green',
+      compute: (data) => data.reservations.filter(r => r.status === 'active').length,
+      computeChange: () => '-3.1%',
+      computeChangeType: () => 'decrease',
+      showFooter: true,
+      actionText: 'View all',
+    },
+    {
+      id: 'revenue-month',
+      name: 'Revenue This Month',
+      icon: CurrencyDollarIcon,
+      color: 'green',
+      compute: (data) => {
+        const total = data.reservations.reduce((sum, r) => sum + r.amount, 0);
+        return `$${total.toLocaleString()}`;
+      },
+      computeChange: () => '+20.1%',
+      computeChangeType: () => 'increase',
+    },
+  ],
+  staggerDelay: 100,
+});
+
+// Email Stats
+const emailStats = ref([
+  {
+    id: 'emails-delivered',
+    name: 'Emails Delivered',
+    stat: '2.4M',
+    icon: EnvelopeIcon,
+    color: 'green',
+    change: '+156K this month',
+    changeType: 'increase',
+  },
+  {
+    id: 'average-open-rate',
+    name: 'Average Open Rate',
+    stat: '24.8%',
+    icon: EyeIcon,
+    color: 'green',
+    change: '+2.1% vs last month',
+    changeType: 'increase',
+  },
+  {
+    id: 'average-ctr',
+    name: 'Average CTR',
+    stat: '3.2%',
+    icon: CursorArrowRaysIcon,
+    color: 'green',
+    change: '+0.4% vs last month',
+    changeType: 'increase',
+  },
+  {
+    id: 'deliverability-rate',
+    name: 'Deliverability Rate',
+    stat: '98.1%',
+    icon: CheckCircleIcon,
+    color: 'green',
+    change: '+0.3% vs last month',
+    changeType: 'increase',
+  },
+]);
+
+// Chart data
+const databaseGrowthSeries = ref([
+  {
+    name: 'Total Contacts',
+    data: [1200, 1350, 1500, 1680, 1850, 2100, 2350, 2600, 2850, 3100, 3350, 3600],
+  },
+  {
+    name: 'Active Users',
+    data: [800, 920, 1050, 1180, 1320, 1500, 1680, 1850, 2020, 2200, 2380, 2550],
+  },
+]);
+
+const chartOptions = {
+  xaxis: {
+    categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
+  },
+};
+
+// Handlers
+function handleDateRangeChange(dates: { from: string; to: string }) {
+  dateRange.value = dates;
+  // Refetch data with new date range
+  fetchDashboardData();
+}
+
+function handleStatClick(statId: string) {
+  if (statId === 'active-campaigns') {
+    window.location.href = `/${props.brandId}/admin/campaigns`;
+  } else if (statId === 'total-contacts') {
+    window.location.href = `/${props.brandId}/admin/contacts`;
+  } else if (statId === 'active-reservations') {
+    window.location.href = `/${props.brandId}/admin/reservations`;
+  }
+}
+
+async function fetchDashboardData() {
+  loading.value = true;
+  try {
+    // Fetch data with date range
+    const data = await getDashboardData(props.brandId, dateRange.value);
+    campaigns.value = data.campaigns;
+    contacts.value = data.contacts;
+    reservations.value = data.reservations;
+  } finally {
+    loading.value = false;
+  }
+}
+</script>
+
+<template>
+  <!-- Date Range Filter -->
+  <div class="flex justify-end items-center mb-4 w-full">
+    <DateRange
+      id="dashboard-date-range"
+      :values="dateRange"
+      :loading="loading"
+      @search="handleDateRangeChange"
+    />
+  </div>
+
+  <!-- Tabs -->
+  <div class="border-b border-gray-200 mb-4">
+    <nav class="-mb-px flex space-x-8">
+      <button
+        v-for="tab in tabs"
+        :key="tab.id"
+        :class="[
+          'py-4 px-1 border-b-2 font-medium text-sm',
+          activeTab === tab.id
+            ? 'border-indigo-500 text-indigo-600'
+            : 'border-transparent text-gray-500 hover:text-gray-700 hover:border-gray-300'
+        ]"
+        @click="setActiveTab(tab.id)"
+      >
+        {{ tab.label }}
+      </button>
+    </nav>
+  </div>
+
+  <!-- Primary Stats Grid -->
+  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 my-8">
+    <uiStats
+      v-for="stat in primaryStats"
+      :key="stat.id"
+      :item="stat"
+      :loading="stat.loading"
+      @statClick="handleStatClick"
+    />
+  </div>
+
+  <!-- Email Performance Section -->
+  <uiSectionTitle title="Email Performance Overview" />
+
+  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4 mb-8">
+    <uiStats
+      v-for="stat in emailStats"
+      :key="stat.id"
+      :item="stat"
+      :loading="loading"
+    />
+  </div>
+
+  <!-- Charts Grid -->
+  <div class="grid grid-cols-1 lg:grid-cols-2 gap-4">
+    <Chart
+      id="database-growth"
+      title="Database Growth"
+      type="area"
+      :series="databaseGrowthSeries"
+      :options="chartOptions"
+      :loading="loading"
+    />
+    <Chart
+      id="database-status"
+      title="Database Health"
+      type="bar"
+      :series="databaseStatusSeries"
+      :options="chartOptions"
+      :stacked="true"
+      :loading="loading"
+    />
+    <Chart
+      id="monthly-engagement"
+      title="Monthly Engagement Metrics"
+      type="area"
+      :series="monthlyEngagementSeries"
+      :options="chartOptions"
+      :loading="loading"
+    />
+    <Chart
+      id="revenue-booking"
+      title="Revenue and Booking Performance"
+      type="area"
+      :series="revenueBookingSeries"
+      :options="chartOptions"
+      :loading="loading"
+    />
+  </div>
+</template>
+```
+
+## Key Components
+
+### useStats Composable
+
+Derives statistics from reactive data with staggered loading animation.
+
+```typescript
+import { useStats, countStat, sumStat, percentageStat } from '@htlkg/components/composables';
+
+const { stats, loadingStates, statsWithLoading, allLoaded, refreshAnimation, getStat } = useStats({
+  // Reactive data source
+  data: campaigns,
+  // Loading state
+  loading: campaignsLoading,
+  // Stat definitions
+  definitions: [
+    {
+      id: 'active',
+      name: 'Active Campaigns',
+      icon: CheckCircleIcon,
+      color: 'green',
+      compute: (items) => items.filter(c => c.status === 'active').length,
+      computeChange: (items, prev) => `+${items.length - (prev?.length ?? 0)}`,
+      computeChangeType: () => 'increase',
+      showFooter: true,
+      actionText: 'View all',
+    },
+  ],
+  // Animation settings
+  staggerDelay: 100,     // Delay between each stat reveal
+  initialDelay: 0,       // Delay before first stat reveals
+  // Optional: Previous data for computing changes
+  previousData: previousCampaigns,
+});
+```
+
+### Stat Definition Helpers
+
+```typescript
+// Simple count stat
+countStat<Campaign>(
+  'active',
+  'Active Campaigns',
+  CheckCircleIcon,
+  (c) => c.status === 'active',
+  { color: 'green' }
+);
+
+// Sum stat
+sumStat<Campaign>(
+  'total-sent',
+  'Total Emails Sent',
+  PaperAirplaneIcon,
+  (c) => c.sentCount,
+  { color: 'blue', format: (val) => val.toLocaleString() }
+);
+
+// Percentage stat
+percentageStat<Contact>(
+  'active-rate',
+  'Active Rate',
+  ChartBarIcon,
+  (c) => c.status === 'active',
+  { color: 'green', decimals: 1 }
+);
+
+// Average stat
+averageStat<Campaign>(
+  'avg-open-rate',
+  'Avg Open Rate',
+  EyeIcon,
+  (c) => c.openRate,
+  { color: 'blue', decimals: 1, suffix: '%' }
+);
+```
+
+### Stat Item Interface
+
+```typescript
+interface StatItem {
+  id: string;
+  name: string;
+  stat: string | number;
+  icon: Component;
+  color: 'green' | 'red' | 'yellow' | 'blue' | 'gray' | 'purple' | 'orange' | 'pink';
+  change?: string;            // e.g., "+12.5%", "+156K this month"
+  changeType?: 'increase' | 'decrease' | 'neutral';
+  showFooter?: boolean;
+  actionText?: string;        // e.g., "View all"
+}
+```
+
+### Chart Component
+
+```vue
+<Chart
+  id="unique-chart-id"
+  title="Chart Title"
+  type="area"              // area, bar, line, donut
+  :series="chartSeries"
+  :options="chartOptions"
+  :stacked="false"         // For bar charts
+  :loading="loading"
+/>
+```
+
+### DateRange Component
+
+```vue
+<DateRange
+  id="date-range-id"
+  :values="{ from: '', to: '' }"
+  :loading="loading"
+  @search="handleDateRangeSearch"
+/>
+```
+
+## Grid Layouts
+
+### Stats Grid
+
+```vue
+<!-- 4 columns on large screens, 2 on medium, 1 on mobile -->
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
+  <uiStats v-for="stat in stats" :key="stat.id" :item="stat" />
+</div>
+```
+
+### Charts Grid
+
+```vue
+<!-- 2 columns on large screens, 1 on smaller -->
+<div class="grid grid-cols-1 lg:grid-cols-2 gap-4">
+  <Chart ... />
+  <Chart ... />
+</div>
+```
+
+## Staggered Loading Pattern
+
+The CRM template shows staggered loading where each stat reveals after a delay:
+
+```typescript
+// Manual approach (from CRM template)
+const loadingStats = ref([true, true, true, true]);
+setTimeout(() => loadingStats.value[0] = false, 300);
+setTimeout(() => loadingStats.value[1] = false, 400);
+setTimeout(() => loadingStats.value[2] = false, 500);
+setTimeout(() => loadingStats.value[3] = false, 600);
+
+// Enhanced approach with useStats (automatic)
+const { statsWithLoading } = useStats({
+  data: campaigns,
+  loading: campaignsLoading,
+  definitions: [...],
+  staggerDelay: 100, // 100ms between each stat
+});
+
+// statsWithLoading includes `loading` property for each stat
+<uiStats
+  v-for="stat in statsWithLoading"
+  :key="stat.id"
+  :item="stat"
+  :loading="stat.loading"
+/>
+```
+
+## Tab-Based Views
+
+For dashboards with multiple views (Overview, Campaigns, Revenue, etc.):
+
+```vue
+<script setup>
+import { useTabs } from '@htlkg/components/composables';
+
+const { tabs, activeTab, setActiveTab } = useTabs({
+  tabs: [
+    { id: 'overview', label: 'Overview' },
+    { id: 'campaigns', label: 'Campaigns' },
+    { id: 'revenue', label: 'Revenue' },
+  ],
+  initialTab: 'overview',
+  onTabChange: (tabId) => {
+    // Load tab-specific data
+    fetchTabData(tabId);
+  },
+});
+</script>
+
+<template>
+  <!-- Overview Tab Content -->
+  <div v-if="activeTab === 'overview'">
+    <!-- Stats and charts -->
+  </div>
+
+  <!-- Campaigns Tab Content -->
+  <div v-else-if="activeTab === 'campaigns'">
+    <!-- Campaign-specific metrics -->
+  </div>
+
+  <!-- Revenue Tab Content -->
+  <div v-else-if="activeTab === 'revenue'">
+    <!-- Revenue-specific charts -->
+  </div>
+</template>
+```
+
+## Checklist
+
+- [ ] Astro page with layout
+- [ ] Vue component with stats and charts
+- [ ] `useStats` composable for derived statistics
+- [ ] Staggered loading animation
+- [ ] Date range filter
+- [ ] Tab navigation (if multiple views)
+- [ ] Stats grid (4 columns)
+- [ ] Section titles for grouping
+- [ ] Charts grid (2 columns)
+- [ ] Chart types: area, bar, line, donut
+- [ ] Stat click handlers for navigation
+- [ ] Loading states for all components
+- [ ] Responsive grid layouts