@htlkg/components 0.0.11 → 0.0.13

package/src/patterns/FORM_PAGE.md

@@ -0,0 +1,439 @@
+# Form Page Pattern
+
+Create or edit entity data using JsonSchemaForm for automatic form generation and validation.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ AdminLayout                                                  │
+├─────────────────────────────────────────────────────────────┤
+│ Page Header (title + breadcrumbs)                           │
+├─────────────────────────────────────────────────────────────┤
+│ Optional: Back Button                                        │
+├─────────────────────────────────────────────────────────────┤
+│ Form Container (lg:w-2/3 xl:w-1/2)                          │
+│ ├── Section Title                                           │
+│ ├── Input Fields (auto-generated from schema)               │
+│ ├── Section Title                                           │
+│ ├── More Fields...                                          │
+│ └── Submit Button                                           │
+├─────────────────────────────────────────────────────────────┤
+│ Optional: Unsaved Changes Warning                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## CRM Template Reference
+
+Based on: `ui/src/components/Templates/CRM/SettingsGeneral.vue`
+
+```vue
+<!-- CRM Template Structure (raw @hotelinking/ui) -->
+<uiWrapper :sidebar :topbar>
+  <uiViewHeader :pages="pages" title="Hotel Group Information" />
+
+  <div class="lg:w-2/3 xl:w-1/2">
+    <uiInput label="Group Name" :value="formData.groupName"
+      @inputChanged="handleInputChange('groupName', $event)" />
+
+    <uiTextArea label="Description" :value="formData.description"
+      @inputChanged="handleInputChange('description', $event)" />
+
+    <uiSectionTitle title="Corporate Headquarters"
+      description="Main office location." />
+
+    <div class="grid gap-x-4 md:grid-cols-2">
+      <uiInput label="City" :value="formData.city" />
+      <uiSelectV2 label="Country" :items="countries" />
+    </div>
+
+    <uiButton class="my-8">Save Changes</uiButton>
+  </div>
+</uiWrapper>
+```
+
+## Enhanced Pattern (with @htlkg/*)
+
+### Astro Page
+
+```astro
+---
+// src/pages/[brandId]/admin/config.astro
+import Layout from '@/layouts/Layout.astro';
+import BrandConfigForm from '@/components/admin/BrandConfigForm.vue';
+import { getBrand } from '@/services/brand';
+
+export const prerender = false;
+
+const { brandId } = Astro.params;
+const brand = await getBrand(Number(brandId));
+
+const layoutProps = {
+  title: 'Brand Configuration',
+  breadcrumbs: [
+    { name: 'Brands', href: '/admin/brands' },
+    { name: brand.name, href: `/${brandId}/admin` },
+    { name: 'Configuration', current: true },
+  ],
+};
+---
+
+<Layout {...layoutProps}>
+  <BrandConfigForm client:load initialData={brand} brandId={brandId} />
+</Layout>
+```
+
+### Vue Component with JsonSchemaForm
+
+```vue
+<!-- src/components/admin/BrandConfigForm.vue -->
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { JsonSchemaForm } from '@htlkg/components/forms';
+import { useJsonForm, useConfirmation, useNotifications } from '@htlkg/components/composables';
+import { uiButton, uiSectionTitle } from '@hotelinking/ui';
+
+interface Props {
+  initialData: Brand;
+  brandId: string;
+}
+
+const props = defineProps<Props>();
+const emit = defineEmits<{
+  saved: [data: Brand];
+}>();
+
+// Form state with useJsonForm
+const { formRef, values, isDirty, validate, reset, setValues } = useJsonForm({
+  initialValues: props.initialData,
+  confirmOnLeave: true,
+});
+
+// Confirmation dialog for reset
+const resetConfirmation = useConfirmation();
+
+// Notifications
+const { notify } = useNotifications();
+
+// JSON Schema for the form
+const schema = {
+  type: 'object',
+  title: 'Brand Configuration',
+  properties: {
+    name: {
+      type: 'string',
+      title: 'Brand Name',
+      minLength: 1,
+    },
+    description: {
+      type: 'string',
+      title: 'Description',
+      minLength: 100,  // Will use textarea
+    },
+    type: {
+      type: 'string',
+      title: 'Brand Type',
+      enum: ['hotel', 'resort', 'boutique', 'chain'],
+    },
+    totalProperties: {
+      type: 'number',
+      title: 'Total Properties',
+      minimum: 0,
+    },
+    totalRooms: {
+      type: 'number',
+      title: 'Total Rooms',
+      minimum: 0,
+    },
+    // Corporate section
+    headquartersAddress: {
+      type: 'string',
+      title: 'Headquarters Address',
+    },
+    city: {
+      type: 'string',
+      title: 'City',
+    },
+    country: {
+      type: 'string',
+      title: 'Country',
+      enum: ['US', 'UK', 'ES', 'FR', 'DE'],
+    },
+    corporatePhone: {
+      type: 'string',
+      title: 'Corporate Phone',
+    },
+    corporateEmail: {
+      type: 'string',
+      title: 'Corporate Email',
+      format: 'email',
+    },
+    website: {
+      type: 'string',
+      title: 'Website',
+      format: 'uri',
+    },
+    // Regional settings
+    timezone: {
+      type: 'string',
+      title: 'Timezone',
+      enum: ['UTC', 'EST', 'PST', 'CET'],
+    },
+    language: {
+      type: 'string',
+      title: 'Language',
+      enum: ['en', 'es', 'fr', 'de'],
+    },
+    currency: {
+      type: 'string',
+      title: 'Currency',
+      enum: ['USD', 'EUR', 'GBP'],
+    },
+  },
+  required: ['name', 'type'],
+};
+
+// UI Schema for customization
+const uiSchema = {
+  description: {
+    'ui:widget': 'textarea',
+    'ui:placeholder': 'Enter brand description...',
+  },
+  corporatePhone: {
+    'ui:placeholder': '+1 (000) 000-0000',
+  },
+  website: {
+    'ui:placeholder': 'https://www.example.com',
+  },
+};
+
+// Submit handler
+async function handleSubmit(formData: Brand) {
+  try {
+    const response = await saveBrand(props.brandId, formData);
+    notify({ type: 'success', message: 'Configuration saved successfully' });
+    setValues(response); // Update initial values after save
+    emit('saved', response);
+  } catch (error) {
+    notify({ type: 'error', message: 'Failed to save configuration' });
+  }
+}
+
+// Reset handler with confirmation
+function handleReset() {
+  resetConfirmation.confirm(
+    'Are you sure you want to reset all changes?',
+    () => {
+      reset();
+      notify({ type: 'info', message: 'Form reset to original values' });
+    }
+  );
+}
+
+// Loading state
+const isLoading = ref(false);
+</script>
+
+<template>
+  <div class="lg:w-2/3 xl:w-1/2">
+    <!-- Unsaved changes indicator -->
+    <div v-if="isDirty" class="mb-4 p-3 bg-yellow-50 border border-yellow-200 rounded-lg">
+      <p class="text-sm text-yellow-800">You have unsaved changes</p>
+    </div>
+
+    <!-- Basic Information Section -->
+    <uiSectionTitle
+      class="mb-4"
+      title="Basic Information"
+      description="Brand identification and details."
+    />
+
+    <JsonSchemaForm
+      ref="formRef"
+      v-model="values"
+      :schema="schema"
+      :ui-schema="uiSchema"
+      :loading="isLoading"
+      @submit="handleSubmit"
+    >
+      <!-- Custom actions slot -->
+      <template #actions>
+        <div class="flex gap-4 pt-6 border-t">
+          <uiButton
+            type="button"
+            color="gray"
+            :disabled="!isDirty"
+            @click="handleReset"
+          >
+            Reset
+          </uiButton>
+          <uiButton
+            type="submit"
+            color="primary"
+            :loading="isLoading"
+            :disabled="!isDirty"
+          >
+            Save Changes
+          </uiButton>
+        </div>
+      </template>
+    </JsonSchemaForm>
+
+    <!-- Reset Confirmation Modal -->
+    <Modal
+      :open="resetConfirmation.isOpen.value"
+      title="Reset Form"
+      @close="resetConfirmation.cancel"
+    >
+      <p>{{ resetConfirmation.message.value }}</p>
+      <template #actions>
+        <uiButton color="gray" @click="resetConfirmation.cancel">Cancel</uiButton>
+        <uiButton color="red" @click="resetConfirmation.execute">Reset</uiButton>
+      </template>
+    </Modal>
+  </div>
+</template>
+```
+
+## Key Components
+
+### JsonSchemaForm
+
+The primary form component that auto-generates UI from JSON Schema.
+
+```typescript
+import { JsonSchemaForm } from '@htlkg/components/forms';
+```
+
+**Props:**
+- `schema` - JSON Schema definition
+- `modelValue` - Form data (v-model)
+- `uiSchema` - UI customizations
+- `loading` - Loading state
+
+**Events:**
+- `submit` - Form submitted with valid data
+- `validation-error` - Validation failed
+
+**Exposed Methods:**
+- `validate()` - Trigger validation
+- `reset()` - Reset form
+
+### useJsonForm Composable
+
+Wraps JsonSchemaForm with additional features.
+
+```typescript
+import { useJsonForm } from '@htlkg/components/composables';
+
+const {
+  formRef,    // Ref to JsonSchemaForm instance
+  values,     // Form data (reactive)
+  isDirty,    // Has unsaved changes
+  validate,   // Trigger validation
+  reset,      // Reset to initial values
+  setValues,  // Update initial values (after save)
+} = useJsonForm({
+  initialValues: props.data,
+  confirmOnLeave: true,  // Warn before leaving with unsaved changes
+});
+```
+
+### JSON Schema Field Types
+
+```typescript
+const schema = {
+  properties: {
+    // Text input
+    name: { type: 'string', title: 'Name', minLength: 1 },
+
+    // Email input (auto-detected from format)
+    email: { type: 'string', title: 'Email', format: 'email' },
+
+    // URL input
+    website: { type: 'string', title: 'Website', format: 'uri' },
+
+    // Number input
+    count: { type: 'number', title: 'Count', minimum: 0, maximum: 100 },
+
+    // Select dropdown (from enum)
+    status: { type: 'string', title: 'Status', enum: ['active', 'inactive'] },
+
+    // Boolean toggle
+    enabled: { type: 'boolean', title: 'Enabled' },
+
+    // Textarea (auto for minLength > 100)
+    description: { type: 'string', title: 'Description', minLength: 100 },
+
+    // Password (via uiSchema)
+    password: { type: 'string', title: 'Password' },
+
+    // Array of strings
+    tags: { type: 'array', title: 'Tags', items: { type: 'string' } },
+  },
+  required: ['name', 'email'],  // Required fields
+};
+```
+
+### UI Schema Customizations
+
+```typescript
+const uiSchema = {
+  password: { 'ui:widget': 'password' },
+  description: { 'ui:widget': 'textarea' },
+  volume: { 'ui:widget': 'slider' },
+  field: {
+    'ui:placeholder': 'Enter value...',
+    'ui:autocomplete': 'email',
+  },
+};
+```
+
+## Form Sections
+
+For long forms, use section titles to group related fields:
+
+```vue
+<template>
+  <div class="lg:w-2/3 xl:w-1/2">
+    <!-- Section 1 -->
+    <uiSectionTitle title="Basic Info" description="..." />
+    <!-- Fields -->
+
+    <!-- Section 2 -->
+    <uiSectionTitle title="Contact" description="..." class="mt-8" />
+    <!-- Fields -->
+
+    <!-- Submit -->
+    <uiButton class="my-8">Save</uiButton>
+  </div>
+</template>
+```
+
+## Grid Layouts for Fields
+
+Use Tailwind grid for side-by-side fields:
+
+```vue
+<div class="grid gap-x-4 md:grid-cols-2 mb-4">
+  <!-- Two columns on medium+ screens -->
+</div>
+
+<div class="grid gap-x-4 md:grid-cols-3 mb-4">
+  <!-- Three columns on medium+ screens -->
+</div>
+```
+
+## Checklist
+
+- [ ] Astro page with server-side data fetch
+- [ ] Vue component with `JsonSchemaForm`
+- [ ] JSON Schema with validation rules
+- [ ] UI Schema for customizations (if needed)
+- [ ] `useJsonForm` for isDirty, confirmOnLeave
+- [ ] Section titles for grouped fields
+- [ ] Grid layouts for field arrangement
+- [ ] Submit and Reset buttons
+- [ ] `useConfirmation` for reset dialog
+- [ ] `useNotifications` for success/error messages
+- [ ] Loading states during save