@htlkg/components 0.0.11 → 0.0.13

package/src/patterns/WIZARD_PAGE.md

@@ -0,0 +1,733 @@
+# Wizard Page Pattern
+
+Multi-step forms for complex entity creation with validation, progress tracking, and step-by-step navigation.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ AdminLayout                                                  │
+├─────────────────────────────────────────────────────────────┤
+│ Page Header (title + breadcrumbs)                           │
+├─────────────────────────────────────────────────────────────┤
+│ Back Button                                                  │
+├─────────────────────────────────────────────────────────────┤
+│ Stepper (progress indicator)                                │
+│ ├── Step 1: Complete ✓                                      │
+│ ├── Step 2: Current →                                       │
+│ ├── Step 3: Upcoming                                        │
+│ └── Step N: Upcoming                                        │
+├─────────────────────────────────────────────────────────────┤
+│ Step Content Container (lg:w-2/3 xl:w-1/2)                  │
+│ ├── Step Title/Description                                  │
+│ ├── Form Fields (JsonSchemaForm or custom)                  │
+│ └── Navigation Buttons (Back / Next / Complete)             │
+├─────────────────────────────────────────────────────────────┤
+│ Final Step: Review & Submit                                  │
+│ ├── Summary Card                                            │
+│ ├── Missing Fields Alert (if any)                           │
+│ └── Create/Submit Button                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## CRM Template Reference
+
+Based on: `ui/src/components/Templates/CRM/CampaignsCreate.vue`
+
+```vue
+<!-- CRM Template Structure (raw @hotelinking/ui) -->
+<uiWrapper :sidebar :topbar>
+  <uiViewHeader :pages="pages" title="Campaigns - Create" />
+
+  <!-- Back Button -->
+  <div class="flex justify-between items-center mb-6">
+    <uiButton :icon="ArrowLeftIcon" @click="handleBack">Back to Campaigns</uiButton>
+  </div>
+
+  <!-- Stepper -->
+  <uiStepsV4
+    :steps="stepsV4"
+    @stepClick="handleStepClick"
+    @stepCompleted="handleStepCompleted"
+    @stepCurrent="handleStepCurrent"
+  />
+
+  <!-- Step Content -->
+  <div v-if="currentStepIndex === 0" class="lg:w-2/3 xl:w-1/2">
+    <uiInput label="Campaign Name" v-model="campaignName" />
+    <uiTextArea label="Description" v-model="description" />
+
+    <!-- Navigation -->
+    <div class="flex justify-end gap-4 mt-8">
+      <uiButton v-if="currentStepIndex > 0" :icon="ArrowLeftIcon" color="gray" @click="goToPreviousStep">
+        Back
+      </uiButton>
+      <uiButton :icon="ArrowRightIcon" color="primary" @click="goToNextStep">
+        Next
+      </uiButton>
+    </div>
+  </div>
+
+  <!-- Review Step -->
+  <div v-else-if="currentStepIndex === lastStepIndex" class="lg:w-2/3 xl:w-1/2">
+    <uiAlert v-if="missingFields.length" title="Missing Fields" type="danger" />
+    <uiStripedCard :title="campaignName" :items="reviewItems" />
+    <uiButton color="primary" @click="handleCreate">Create Campaign</uiButton>
+  </div>
+</uiWrapper>
+```
+
+## Enhanced Pattern (with @htlkg/*)
+
+### Astro Page
+
+```astro
+---
+// src/pages/[brandId]/admin/campaigns/create.astro
+import Layout from '@/layouts/Layout.astro';
+import CampaignWizard from '@/components/admin/CampaignWizard.vue';
+
+export const prerender = false;
+
+const { brandId } = Astro.params;
+
+const layoutProps = {
+  title: 'Create Campaign',
+  breadcrumbs: [
+    { name: 'Campaigns', href: `/${brandId}/admin/campaigns` },
+    { name: 'Create', current: true },
+  ],
+};
+---
+
+<Layout {...layoutProps}>
+  <CampaignWizard client:load brandId={brandId} />
+</Layout>
+```
+
+### Vue Component with useWizard
+
+```vue
+<!-- src/components/admin/CampaignWizard.vue -->
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Stepper } from '@htlkg/components/navigation';
+import { JsonSchemaForm } from '@htlkg/components/forms';
+import { useWizard, useNotifications } from '@htlkg/components/composables';
+import { uiButton, uiAlert, uiStripedCard } from '@hotelinking/ui';
+import {
+  ArrowLeftIcon,
+  ArrowRightIcon,
+  CheckIcon,
+} from '@heroicons/vue/24/outline';
+
+interface CampaignData {
+  name: string;
+  description: string;
+  segments: string[];
+  tags: string[];
+  templateId: string;
+  sendOption: 'immediately' | 'schedule';
+  scheduleDate?: string;
+  subjectLine: string;
+  senderName: string;
+  senderEmail: string;
+}
+
+interface Props {
+  brandId: string;
+}
+
+const props = defineProps<Props>();
+const emit = defineEmits<{
+  back: [];
+  created: [campaign: CampaignData];
+}>();
+
+const { notify } = useNotifications();
+
+// Define wizard steps with JSON Schema for each step
+const steps = [
+  {
+    id: 'details',
+    label: 'Campaign Details',
+    description: 'Basic campaign information',
+    schema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          title: 'Campaign Name',
+          minLength: 1,
+        },
+        description: {
+          type: 'string',
+          title: 'Description',
+          minLength: 100, // Will auto-use textarea
+        },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    id: 'audience',
+    label: 'Audience Selection',
+    description: 'Select target segments and tags',
+    // Custom validation - no schema
+    validate: (data: Partial<CampaignData>) => {
+      return (data.segments?.length ?? 0) > 0 || (data.tags?.length ?? 0) > 0;
+    },
+  },
+  {
+    id: 'template',
+    label: 'Email Design',
+    description: 'Select email template',
+    validate: (data: Partial<CampaignData>) => {
+      return !!data.templateId;
+    },
+  },
+  {
+    id: 'schedule',
+    label: 'Scheduling',
+    description: 'Set send date and time',
+    schema: {
+      type: 'object',
+      properties: {
+        sendOption: {
+          type: 'string',
+          title: 'Send Option',
+          enum: ['immediately', 'schedule'],
+          default: 'schedule',
+        },
+        scheduleDate: {
+          type: 'string',
+          title: 'Schedule Date',
+          format: 'date-time',
+        },
+      },
+      required: ['sendOption'],
+    },
+  },
+  {
+    id: 'sender',
+    label: 'Subject & Sender',
+    description: 'Configure email subject and sender',
+    schema: {
+      type: 'object',
+      properties: {
+        subjectLine: {
+          type: 'string',
+          title: 'Subject Line',
+          minLength: 1,
+        },
+        senderName: {
+          type: 'string',
+          title: 'Sender Name',
+          minLength: 1,
+        },
+        senderEmail: {
+          type: 'string',
+          title: 'Sender Email',
+          format: 'email',
+        },
+      },
+      required: ['subjectLine', 'senderName', 'senderEmail'],
+    },
+  },
+  {
+    id: 'review',
+    label: 'Review & Send',
+    description: 'Review campaign before creating',
+    optional: true, // Review step doesn't need validation
+  },
+];
+
+// Initialize wizard
+const wizard = useWizard<CampaignData>({
+  steps,
+  initialData: {
+    name: '',
+    description: '',
+    segments: [],
+    tags: [],
+    templateId: '',
+    sendOption: 'schedule',
+    subjectLine: '',
+    senderName: '',
+    senderEmail: '',
+  },
+  validateOnNext: true,
+  onComplete: async (data) => {
+    try {
+      await createCampaign(props.brandId, data);
+      notify({ type: 'success', message: 'Campaign created successfully' });
+      emit('created', data as CampaignData);
+    } catch (error) {
+      notify({ type: 'error', message: 'Failed to create campaign' });
+      throw error;
+    }
+  },
+  onStepChange: (from, to, data) => {
+    console.log(`Step changed from ${from} to ${to}`);
+  },
+});
+
+// Review items for final step
+const reviewItems = computed(() => {
+  const data = wizard.data.value;
+  return [
+    { title: 'Campaign Name', text: data.name || 'Not set' },
+    { title: 'Description', text: data.description || 'Not set' },
+    { title: 'Segments', text: data.segments?.join(', ') || 'None selected' },
+    { title: 'Tags', text: data.tags?.join(', ') || 'None selected' },
+    { title: 'Template', text: data.templateId || 'Not selected' },
+    { title: 'Send Option', text: data.sendOption === 'immediately' ? 'Send Now' : `Scheduled: ${data.scheduleDate}` },
+    { title: 'Subject Line', text: data.subjectLine || 'Not set' },
+    { title: 'Sender', text: `${data.senderName} <${data.senderEmail}>` || 'Not set' },
+  ];
+});
+
+// Missing fields for review step
+const missingFields = computed(() => {
+  const missing: string[] = [];
+  const data = wizard.data.value;
+
+  if (!data.name) missing.push('Campaign Name');
+  if ((data.segments?.length ?? 0) === 0 && (data.tags?.length ?? 0) === 0) {
+    missing.push('At least one segment or tag');
+  }
+  if (!data.templateId) missing.push('Email Template');
+  if (!data.subjectLine) missing.push('Subject Line');
+  if (!data.senderName) missing.push('Sender Name');
+  if (!data.senderEmail) missing.push('Sender Email');
+
+  return missing;
+});
+
+// Handle form submission for schema-based steps
+function handleStepSubmit(formData: Partial<CampaignData>) {
+  wizard.updateData(formData);
+  wizard.setStepValid(wizard.currentStep.value.id, true);
+}
+
+// Handle form validation errors
+function handleValidationError(errors: Array<{ field: string; message: string }>) {
+  wizard.setStepValid(wizard.currentStep.value.id, false);
+  if (errors.length > 0) {
+    wizard.setStepError(wizard.currentStep.value.id, errors[0].message);
+  }
+}
+</script>
+
+<template>
+  <!-- Back Button -->
+  <div class="flex justify-between items-center mb-6">
+    <uiButton :icon="ArrowLeftIcon" @click="emit('back')">
+      Back to Campaigns
+    </uiButton>
+  </div>
+
+  <!-- Stepper -->
+  <Stepper
+    :steps="wizard.stepperSteps.value"
+    :current-step="wizard.currentStepIndex.value"
+    @step-click="wizard.goToStep"
+  />
+
+  <!-- Step Content -->
+  <div class="mt-8">
+    <!-- Step 1: Campaign Details -->
+    <div v-if="wizard.currentStep.value.id === 'details'" class="lg:w-2/3 xl:w-1/2">
+      <JsonSchemaForm
+        v-model="wizard.data.value"
+        :schema="wizard.currentStep.value.schema"
+        @submit="handleStepSubmit"
+        @validation-error="handleValidationError"
+      >
+        <template #actions>
+          <div class="flex justify-end gap-4 mt-8">
+            <uiButton
+              :icon="ArrowRightIcon"
+              color="primary"
+              @click="wizard.goToNext"
+            >
+              Next
+            </uiButton>
+          </div>
+        </template>
+      </JsonSchemaForm>
+    </div>
+
+    <!-- Step 2: Audience Selection (Custom UI) -->
+    <div v-else-if="wizard.currentStep.value.id === 'audience'" class="lg:w-2/3 xl:w-1/2">
+      <!-- Segments Checkboxes -->
+      <div class="mb-8">
+        <h3 class="text-lg font-semibold mb-4">Select Segments</h3>
+        <!-- Custom segment selection UI here -->
+      </div>
+
+      <!-- Tags Checkboxes -->
+      <div class="mb-8">
+        <h3 class="text-lg font-semibold mb-4">Select Tags</h3>
+        <!-- Custom tag selection UI here -->
+      </div>
+
+      <!-- Navigation -->
+      <div class="flex justify-end gap-4 mt-8">
+        <uiButton
+          :icon="ArrowLeftIcon"
+          color="gray"
+          @click="wizard.goToPrevious"
+        >
+          Back
+        </uiButton>
+        <uiButton
+          :icon="ArrowRightIcon"
+          color="primary"
+          @click="wizard.goToNext"
+        >
+          Next
+        </uiButton>
+      </div>
+    </div>
+
+    <!-- Step 3: Template Selection (Custom UI) -->
+    <div v-else-if="wizard.currentStep.value.id === 'template'" class="mt-8">
+      <!-- Template Grid -->
+      <div class="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 gap-4 mb-6">
+        <!-- Template cards here -->
+      </div>
+
+      <!-- Navigation -->
+      <div class="flex justify-end gap-4 mt-8">
+        <uiButton
+          :icon="ArrowLeftIcon"
+          color="gray"
+          @click="wizard.goToPrevious"
+        >
+          Back
+        </uiButton>
+        <uiButton
+          :icon="ArrowRightIcon"
+          color="primary"
+          @click="wizard.goToNext"
+        >
+          Next
+        </uiButton>
+      </div>
+    </div>
+
+    <!-- Step 4: Scheduling (JsonSchemaForm) -->
+    <div v-else-if="wizard.currentStep.value.id === 'schedule'" class="lg:w-2/3 xl:w-1/2">
+      <JsonSchemaForm
+        v-model="wizard.data.value"
+        :schema="wizard.currentStep.value.schema"
+        @submit="handleStepSubmit"
+        @validation-error="handleValidationError"
+      >
+        <template #actions>
+          <div class="flex justify-end gap-4 mt-8">
+            <uiButton
+              :icon="ArrowLeftIcon"
+              color="gray"
+              @click="wizard.goToPrevious"
+            >
+              Back
+            </uiButton>
+            <uiButton
+              :icon="ArrowRightIcon"
+              color="primary"
+              @click="wizard.goToNext"
+            >
+              Next
+            </uiButton>
+          </div>
+        </template>
+      </JsonSchemaForm>
+    </div>
+
+    <!-- Step 5: Subject & Sender (JsonSchemaForm) -->
+    <div v-else-if="wizard.currentStep.value.id === 'sender'" class="lg:w-2/3 xl:w-1/2">
+      <JsonSchemaForm
+        v-model="wizard.data.value"
+        :schema="wizard.currentStep.value.schema"
+        @submit="handleStepSubmit"
+        @validation-error="handleValidationError"
+      >
+        <template #actions>
+          <div class="flex justify-end gap-4 mt-8">
+            <uiButton
+              :icon="ArrowLeftIcon"
+              color="gray"
+              @click="wizard.goToPrevious"
+            >
+              Back
+            </uiButton>
+            <uiButton
+              :icon="ArrowRightIcon"
+              color="primary"
+              @click="wizard.goToNext"
+            >
+              Next
+            </uiButton>
+          </div>
+        </template>
+      </JsonSchemaForm>
+    </div>
+
+    <!-- Step 6: Review -->
+    <div v-else-if="wizard.currentStep.value.id === 'review'" class="lg:w-2/3 xl:w-1/2">
+      <!-- Missing Fields Alert -->
+      <uiAlert
+        v-if="missingFields.length > 0"
+        title="Missing Required Fields"
+        type="danger"
+        class="mb-6"
+      >
+        <p class="text-sm mb-2">Please complete the following before creating:</p>
+        <ul class="list-disc list-inside text-sm">
+          <li v-for="field in missingFields" :key="field">{{ field }}</li>
+        </ul>
+      </uiAlert>
+
+      <!-- Review Summary -->
+      <uiStripedCard
+        :title="wizard.data.value.name || 'New Campaign'"
+        :items="reviewItems"
+        class="mb-8"
+      />
+
+      <!-- Navigation -->
+      <div class="flex justify-end gap-4 mt-8">
+        <uiButton
+          :icon="ArrowLeftIcon"
+          color="gray"
+          @click="wizard.goToPrevious"
+        >
+          Back
+        </uiButton>
+        <uiButton
+          :icon="CheckIcon"
+          color="primary"
+          :loading="wizard.isCompleting.value"
+          :disabled="missingFields.length > 0"
+          @click="wizard.complete"
+        >
+          Create Campaign
+        </uiButton>
+      </div>
+    </div>
+  </div>
+
+  <!-- Progress Indicator -->
+  <div class="mt-4 text-sm text-gray-500 text-center">
+    Step {{ wizard.currentStepIndex.value + 1 }} of {{ wizard.stepperSteps.value.length }}
+    ({{ wizard.progress.value }}% complete)
+  </div>
+</template>
+```
+
+## Key Components
+
+### useWizard Composable
+
+```typescript
+import { useWizard } from '@htlkg/components/composables';
+
+const wizard = useWizard<FormData>({
+  // Step definitions
+  steps: [
+    {
+      id: 'step1',
+      label: 'Step Label',
+      description: 'Optional description',
+      schema: jsonSchema,        // JSON Schema for JsonSchemaForm
+      validate: (data) => true,  // Custom validation function
+      optional: false,           // Whether step can be skipped
+    },
+  ],
+
+  // Initial form data
+  initialData: { field1: '', field2: '' },
+
+  // Validation behavior
+  validateOnNext: true,              // Validate before advancing
+  allowBackWithoutValidation: true,  // Allow going back without validation
+
+  // Callbacks
+  onComplete: async (data) => { /* Handle completion */ },
+  onStepChange: (from, to, data) => { /* Handle step change */ },
+});
+
+// Returned state and methods
+wizard.currentStepIndex    // Current step index (ref)
+wizard.currentStep         // Current step object (computed)
+wizard.data                // Form data (ref)
+wizard.isFirstStep         // Is first step (computed)
+wizard.isLastStep          // Is last step (computed)
+wizard.isCompleting        // Is completing (ref)
+wizard.stepperSteps        // Steps for Stepper component (computed)
+wizard.stepValidation      // Validation state per step (ref)
+wizard.currentStepValid    // Is current step valid (computed)
+wizard.allStepsValid       // Are all steps valid (computed)
+wizard.stepErrors          // Error messages per step (ref)
+wizard.progress            // Progress percentage (computed)
+
+// Navigation
+wizard.goToNext()          // Go to next step (validates current)
+wizard.goToPrevious()      // Go to previous step
+wizard.goToStep(index)     // Go to specific step
+wizard.canGoToStep(index)  // Check if navigation is allowed
+
+// Data management
+wizard.updateData(data)           // Update form data
+wizard.updateStepData(stepId, data) // Update data for specific step
+wizard.setStepValid(stepId, valid)  // Set step validation status
+wizard.setStepError(stepId, error)  // Set step error message
+wizard.resetStep(stepId)            // Reset specific step
+wizard.reset()                      // Reset entire wizard
+
+// Completion
+wizard.complete()                   // Validate all and complete
+
+// Utilities
+wizard.getStepIndex(stepId)        // Get step index by ID
+wizard.getStep(stepId)             // Get step by ID
+```
+
+### Step Types
+
+```typescript
+interface WizardStep<T> {
+  /** Unique step identifier */
+  id: string;
+  /** Display label for the step */
+  label: string;
+  /** Optional description */
+  description?: string;
+  /** JSON Schema for JsonSchemaForm (optional) */
+  schema?: JsonSchema;
+  /** Custom validation function (optional) */
+  validate?: (data: T) => boolean | Promise<boolean>;
+  /** Icon component for the step (optional) */
+  icon?: Component;
+  /** Whether step can be skipped */
+  optional?: boolean;
+}
+```
+
+### Step Status
+
+```typescript
+type StepStatus = 'complete' | 'current' | 'upcoming' | 'error';
+```
+
+## Patterns
+
+### Schema-Based Steps
+
+For steps with simple form fields, use JSON Schema:
+
+```typescript
+{
+  id: 'details',
+  label: 'Details',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', title: 'Name', minLength: 1 },
+      email: { type: 'string', title: 'Email', format: 'email' },
+    },
+    required: ['name', 'email'],
+  },
+}
+```
+
+### Custom Validation Steps
+
+For steps with complex UI (grids, cards, custom selections):
+
+```typescript
+{
+  id: 'selection',
+  label: 'Select Items',
+  validate: (data) => data.selectedItems?.length > 0,
+}
+```
+
+### Optional Steps
+
+For steps that can be skipped:
+
+```typescript
+{
+  id: 'extras',
+  label: 'Additional Options',
+  optional: true,
+}
+```
+
+### Review Step
+
+Always add a final review step:
+
+```typescript
+{
+  id: 'review',
+  label: 'Review',
+  optional: true, // No validation needed
+}
+```
+
+## Navigation Buttons Pattern
+
+```vue
+<div class="flex justify-end gap-4 mt-8">
+  <!-- Back Button (hide on first step) -->
+  <uiButton
+    v-if="!wizard.isFirstStep.value"
+    :icon="ArrowLeftIcon"
+    color="gray"
+    @click="wizard.goToPrevious"
+  >
+    Back
+  </uiButton>
+
+  <!-- Next Button (show on non-last steps) -->
+  <uiButton
+    v-if="!wizard.isLastStep.value"
+    :icon="ArrowRightIcon"
+    color="primary"
+    @click="wizard.goToNext"
+  >
+    Next
+  </uiButton>
+
+  <!-- Complete Button (show on last step) -->
+  <uiButton
+    v-else
+    :icon="CheckIcon"
+    color="primary"
+    :loading="wizard.isCompleting.value"
+    :disabled="!wizard.allStepsValid.value"
+    @click="wizard.complete"
+  >
+    Create
+  </uiButton>
+</div>
+```
+
+## Checklist
+
+- [ ] Astro page with layout
+- [ ] Vue component with `useWizard` composable
+- [ ] Step definitions with schemas or custom validation
+- [ ] `Stepper` component for progress visualization
+- [ ] `JsonSchemaForm` for schema-based steps
+- [ ] Custom UI for complex selection steps
+- [ ] Navigation buttons (Back/Next/Complete)
+- [ ] Review step with summary card
+- [ ] Missing fields alert on review step
+- [ ] Loading state during completion
+- [ ] `useNotifications` for success/error messages
+- [ ] Progress indicator (optional)