@finema/finework-layer 0.2.49 → 0.2.51

package/EXAMPLES.md

@@ -0,0 +1,597 @@
+# Real-World Examples
+
+This document contains complete, copy-paste ready examples for common use cases.
+
+## 📋 Table of Contents
+
+1. [CRUD Operations](#crud-operations)
+2. [Dashboard Page](#dashboard-page)
+3. [User Management](#user-management)
+4. [Data Export](#data-export)
+5. [File Upload](#file-upload)
+6. [Advanced Filtering](#advanced-filtering)
+
+---
+
+## CRUD Operations
+
+### Complete CRUD Example
+
+#### List Page
+
+```vue
+<!-- pages/products/index.vue -->
+<template>
+  <LayoutAdmin label="Products" :items="navItems">
+    <div class="space-y-6">
+      <!-- Header -->
+      <div class="flex items-center justify-between">
+        <div>
+          <h1 class="text-2xl font-bold">Products</h1>
+          <p class="text-gray-600">Manage your product catalog</p>
+        </div>
+        <Button 
+          label="Add Product" 
+          icon="ph:plus"
+          to="/products/new"
+        />
+      </div>
+
+      <!-- Filters -->
+      <Card>
+        <form @submit.prevent="handleFilter" class="grid grid-cols-1 md:grid-cols-4 gap-4">
+          <Input 
+            v-model="filters.q" 
+            placeholder="Search products..."
+            icon="ph:magnifying-glass"
+          />
+          
+          <Select 
+            v-model="filters.category"
+            :options="categoryOptions"
+            placeholder="Category"
+          />
+          
+          <Select 
+            v-model="filters.status"
+            :options="statusOptions"
+            placeholder="Status"
+          />
+          
+          <div class="flex gap-2">
+            <Button type="submit" label="Filter" class="flex-1" />
+            <Button 
+              type="button" 
+              label="Reset" 
+              variant="outline"
+              @click="handleReset"
+            />
+          </div>
+        </form>
+      </Card>
+
+      <!-- Products Table -->
+      <StatusBox :status="products.status.value" :data="products.data.value">
+        <template #default="{ data }">
+          <Card>
+            <Table :rows="data.items" :columns="columns">
+              <template #name="{ row }">
+                <div class="flex items-center gap-3">
+                  <img 
+                    :src="row.image_url" 
+                    :alt="row.name"
+                    class="w-10 h-10 rounded object-cover"
+                  />
+                  <div>
+                    <p class="font-medium">{{ row.name }}</p>
+                    <p class="text-sm text-gray-500">{{ row.sku }}</p>
+                  </div>
+                </div>
+              </template>
+
+              <template #price="{ row }">
+                {{ NumberHelper.formatCurrency(row.price) }}
+              </template>
+
+              <template #status="{ row }">
+                <Badge 
+                  :label="row.status" 
+                  :color="row.status === 'active' ? 'success' : 'neutral'"
+                />
+              </template>
+
+              <template #actions="{ row }">
+                <div class="flex gap-2">
+                  <ButtonActionIcon
+                    icon="ph:eye"
+                    :to="`/products/${row.id}`"
+                  />
+                  <ButtonActionIcon
+                    icon="ph:pencil-simple"
+                    color="primary"
+                    :to="`/products/${row.id}/edit`"
+                  />
+                  <ButtonActionIcon
+                    icon="ph:trash"
+                    color="error"
+                    @click="handleDelete(row.id)"
+                  />
+                </div>
+              </template>
+            </Table>
+            
+            <div class="mt-4">
+              <Pagination
+                v-model="page"
+                :total="data.total"
+                :per-page="perPage"
+              />
+            </div>
+          </Card>
+        </template>
+      </StatusBox>
+    </div>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['pmo:USER', 'pmo:ADMIN']
+  }
+})
+
+interface Product {
+  id: string
+  name: string
+  sku: string
+  price: number
+  category: string
+  status: string
+  image_url: string
+}
+
+const page = ref(1)
+const perPage = ref(10)
+const filters = reactive({
+  q: '',
+  category: '',
+  status: ''
+})
+
+const products = useListLoader<Product>({
+  method: 'GET',
+  url: '/api/products',
+  getRequestOptions: useRequestOptions().auth
+})
+
+const loadProducts = () => {
+  products.run({
+    params: {
+      page: page.value,
+      per_page: perPage.value,
+      ...filters
+    }
+  })
+}
+
+const handleFilter = () => {
+  page.value = 1
+  loadProducts()
+}
+
+const handleReset = () => {
+  Object.assign(filters, { q: '', category: '', status: '' })
+  handleFilter()
+}
+
+const handleDelete = async (id: string) => {
+  const dialog = useDialog()
+  
+  const confirmed = await dialog.confirm({
+    title: 'Delete Product',
+    description: 'Are you sure you want to delete this product?'
+  })
+  
+  if (!confirmed) return
+  
+  const deleteLoader = useObjectLoader({
+    method: 'DELETE',
+    url: `/api/products/${id}`,
+    getRequestOptions: useRequestOptions().auth
+  })
+  
+  await deleteLoader.run()
+  
+  if (deleteLoader.status.value.isSuccess) {
+    loadProducts()
+  }
+}
+
+watch(page, () => loadProducts())
+
+onMounted(() => loadProducts())
+
+const columns = [
+  { key: 'name', label: 'Product' },
+  { key: 'category', label: 'Category' },
+  { key: 'price', label: 'Price' },
+  { key: 'status', label: 'Status' },
+  { key: 'actions', label: 'Actions' }
+]
+
+const categoryOptions = [
+  { label: 'All Categories', value: '' },
+  { label: 'Electronics', value: 'electronics' },
+  { label: 'Clothing', value: 'clothing' },
+  { label: 'Food', value: 'food' }
+]
+
+const statusOptions = [
+  { label: 'All Status', value: '' },
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' }
+]
+
+const navItems = [
+  { label: 'Dashboard', to: '/dashboard', icon: 'i-heroicons-home' },
+  { label: 'Products', to: '/products', icon: 'i-heroicons-shopping-bag' }
+]
+</script>
+```
+
+#### Create/Edit Form
+
+```vue
+<!-- pages/products/[id]/edit.vue -->
+<template>
+  <LayoutAdmin label="Edit Product" :items="navItems">
+    <StatusBox :status="product.status.value" :data="product.data.value">
+      <template #default="{ data }">
+        <Card>
+          <form @submit="onSubmit" class="space-y-6">
+            <!-- Product Image -->
+            <div>
+              <label class="block text-sm font-medium mb-2">Product Image</label>
+              <div class="flex items-center gap-4">
+                <img 
+                  :src="imagePreview || data.image_url" 
+                  alt="Product"
+                  class="w-32 h-32 rounded object-cover"
+                />
+                <input 
+                  type="file" 
+                  @change="handleImageChange"
+                  accept="image/*"
+                />
+              </div>
+            </div>
+
+            <!-- Basic Info -->
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+              <FormField name="name" label="Product Name">
+                <Input v-model="form.values.name" />
+                <FormError name="name" />
+              </FormField>
+
+              <FormField name="sku" label="SKU">
+                <Input v-model="form.values.sku" />
+                <FormError name="sku" />
+              </FormField>
+
+              <FormField name="category" label="Category">
+                <Select 
+                  v-model="form.values.category"
+                  :options="categoryOptions"
+                />
+                <FormError name="category" />
+              </FormField>
+
+              <FormField name="price" label="Price">
+                <Input 
+                  v-model="form.values.price" 
+                  type="number"
+                  step="0.01"
+                />
+                <FormError name="price" />
+              </FormField>
+
+              <FormField name="stock" label="Stock">
+                <Input 
+                  v-model="form.values.stock" 
+                  type="number"
+                />
+                <FormError name="stock" />
+              </FormField>
+
+              <FormField name="status" label="Status">
+                <Select 
+                  v-model="form.values.status"
+                  :options="statusOptions"
+                />
+                <FormError name="status" />
+              </FormField>
+            </div>
+
+            <!-- Description -->
+            <FormField name="description" label="Description">
+              <Textarea 
+                v-model="form.values.description"
+                rows="4"
+              />
+              <FormError name="description" />
+            </FormField>
+
+            <!-- Actions -->
+            <div class="flex gap-2">
+              <Button 
+                type="submit" 
+                label="Save Changes"
+                :loading="form.isSubmitting.value"
+              />
+              <ButtonBack to="/products" />
+            </div>
+          </form>
+        </Card>
+      </template>
+    </StatusBox>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+import * as v from 'valibot'
+import { toTypedSchema } from '@vee-validate/valibot'
+
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['pmo:ADMIN']
+  }
+})
+
+const route = useRoute()
+const productId = route.params.id as string
+
+const imagePreview = ref<string | null>(null)
+const imageFile = ref<File | null>(null)
+
+// Load product data
+const product = useObjectLoader({
+  method: 'GET',
+  url: `/api/products/${productId}`,
+  getRequestOptions: useRequestOptions().auth
+})
+
+// Form setup
+const form = useForm({
+  validationSchema: toTypedSchema(
+    v.object({
+      name: v.pipe(v.string(), v.minLength(3)),
+      sku: v.pipe(v.string(), v.minLength(3)),
+      category: v.string(),
+      price: v.pipe(v.number(), v.minValue(0)),
+      stock: v.pipe(v.number(), v.minValue(0)),
+      status: v.string(),
+      description: v.optional(v.string(), '')
+    })
+  )
+})
+
+// Load product and populate form
+onMounted(async () => {
+  await product.run()
+  
+  if (product.status.value.isSuccess && product.data.value) {
+    form.setValues(product.data.value)
+  }
+})
+
+const handleImageChange = (event: Event) => {
+  const target = event.target as HTMLInputElement
+  const file = target.files?.[0]
+  
+  if (file) {
+    imageFile.value = file
+    imagePreview.value = URL.createObjectURL(file)
+  }
+}
+
+const onSubmit = form.handleSubmit(async (values) => {
+  // Upload image first if changed
+  let imageUrl = product.data.value?.image_url
+  
+  if (imageFile.value) {
+    const formData = new FormData()
+    formData.append('file', imageFile.value)
+    
+    const uploadLoader = useObjectLoader({
+      method: 'POST',
+      url: '/api/upload',
+      getRequestOptions: useRequestOptions().file
+    })
+    
+    await uploadLoader.run({ data: formData })
+    
+    if (uploadLoader.status.value.isSuccess) {
+      imageUrl = uploadLoader.data.value.url
+    }
+  }
+  
+  // Update product
+  const updateLoader = useObjectLoader({
+    method: 'PUT',
+    url: `/api/products/${productId}`,
+    getRequestOptions: useRequestOptions().auth
+  })
+  
+  await updateLoader.run({
+    data: {
+      ...values,
+      image_url: imageUrl
+    }
+  })
+  
+  if (updateLoader.status.value.isSuccess) {
+    navigateTo('/products')
+  }
+})
+
+const categoryOptions = [
+  { label: 'Electronics', value: 'electronics' },
+  { label: 'Clothing', value: 'clothing' },
+  { label: 'Food', value: 'food' }
+]
+
+const statusOptions = [
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' }
+]
+
+const navItems = [
+  { label: 'Products', to: '/products', icon: 'i-heroicons-shopping-bag' }
+]
+</script>
+```
+
+---
+
+## Dashboard Page
+
+```vue
+<!-- pages/dashboard.vue -->
+<template>
+  <LayoutAdmin label="Dashboard" :items="navItems">
+    <div class="space-y-6">
+      <!-- Stats Cards -->
+      <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
+        <Card v-for="stat in stats" :key="stat.label">
+          <div class="flex items-center justify-between">
+            <div>
+              <p class="text-sm text-gray-600">{{ stat.label }}</p>
+              <p class="text-2xl font-bold mt-1">{{ stat.value }}</p>
+              <p 
+                :class="[
+                  'text-sm mt-1',
+                  stat.change >= 0 ? 'text-success' : 'text-error'
+                ]"
+              >
+                {{ stat.change >= 0 ? '+' : '' }}{{ stat.change }}%
+              </p>
+            </div>
+            <div 
+              :class="[
+                'w-12 h-12 rounded-full flex items-center justify-center',
+                stat.color
+              ]"
+            >
+              <Icon :name="stat.icon" class="text-2xl" />
+            </div>
+          </div>
+        </Card>
+      </div>
+
+      <!-- Charts -->
+      <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        <Card>
+          <h3 class="text-lg font-semibold mb-4">Revenue Overview</h3>
+          <!-- Add your chart component here -->
+        </Card>
+
+        <Card>
+          <h3 class="text-lg font-semibold mb-4">Top Products</h3>
+          <!-- Add your chart component here -->
+        </Card>
+      </div>
+
+      <!-- Recent Activities -->
+      <Card>
+        <h3 class="text-lg font-semibold mb-4">Recent Activities</h3>
+        <StatusBox :status="activities.status.value" :data="activities.data.value">
+          <template #default="{ data }">
+            <div class="space-y-3">
+              <div 
+                v-for="activity in data" 
+                :key="activity.id"
+                class="flex items-center gap-3 p-3 hover:bg-gray-50 rounded"
+              >
+                <Avatar :src="activity.user.avatar_url" />
+                <div class="flex-1">
+                  <p class="font-medium">{{ activity.user.name }}</p>
+                  <p class="text-sm text-gray-600">{{ activity.description }}</p>
+                </div>
+                <p class="text-sm text-gray-500">
+                  {{ formatRelativeTime(activity.created_at) }}
+                </p>
+              </div>
+            </div>
+          </template>
+        </StatusBox>
+      </Card>
+    </div>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  middleware: ['auth']
+})
+
+const stats = ref([
+  {
+    label: 'Total Revenue',
+    value: '$45,231',
+    change: 12.5,
+    icon: 'ph:currency-dollar',
+    color: 'bg-success/10 text-success'
+  },
+  {
+    label: 'Total Orders',
+    value: '1,234',
+    change: 8.2,
+    icon: 'ph:shopping-cart',
+    color: 'bg-primary/10 text-primary'
+  },
+  {
+    label: 'Total Customers',
+    value: '567',
+    change: -2.4,
+    icon: 'ph:users',
+    color: 'bg-warning/10 text-warning'
+  },
+  {
+    label: 'Conversion Rate',
+    value: '3.2%',
+    change: 5.1,
+    icon: 'ph:chart-line',
+    color: 'bg-info/10 text-info'
+  }
+])
+
+const activities = useListLoader({
+  method: 'GET',
+  url: '/api/activities',
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(() => activities.run({ params: { limit: 10 } }))
+
+const formatRelativeTime = (date: string) => {
+  // Implement relative time formatting
+  return new Date(date).toLocaleDateString()
+}
+
+const navItems = [
+  { label: 'Dashboard', to: '/dashboard', icon: 'i-heroicons-home' }
+]
+</script>
+```
+
+---
+
+**More examples available in [COMPONENT_EXAMPLES.md](./COMPONENT_EXAMPLES.md)**
+
+---
+
+**Last Updated:** 2025-11-07
+