@finema/finework-layer 0.2.50 → 0.2.52

package/COMPONENT_EXAMPLES.md

@@ -0,0 +1,893 @@
+# Component Examples & Usage Guide
+
+## 📚 Table of Contents
+
+1. [StatusBox Component](#statusbox-component)
+2. [InfoItemList Component](#infoitemlist-component)
+3. [Button Components](#button-components)
+4. [Layout Components](#layout-components)
+5. [Form Patterns](#form-patterns)
+6. [Data Loading Patterns](#data-loading-patterns)
+
+---
+
+## StatusBox Component
+
+### Basic Usage
+
+```vue
+<template>
+  <StatusBox :status="loader.status.value" :data="loader.data.value">
+    <template #default="{ data }">
+      <Card>
+        <h1>{{ data.title }}</h1>
+        <p>{{ data.description }}</p>
+      </Card>
+    </template>
+  </StatusBox>
+</template>
+
+<script setup lang="ts">
+interface Project {
+  id: string
+  title: string
+  description: string
+}
+
+const loader = useObjectLoader<Project>({
+  method: 'GET',
+  url: '/api/projects/123',
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(() => loader.run())
+</script>
+```
+
+### With Skip Condition
+
+```vue
+<template>
+  <StatusBox 
+    :status="loader.status.value" 
+    :data="loader.data.value"
+    :skip="!shouldLoad"
+  >
+    <template #default="{ data }">
+      <!-- Content -->
+    </template>
+  </StatusBox>
+</template>
+
+<script setup lang="ts">
+const shouldLoad = ref(true)
+</script>
+```
+
+### States Handled
+
+1. **Loading State** - Shows spinner
+2. **Error State** - Shows error message with icon
+3. **Not Found State** - Shows "ไม่พบข้อมูล" message
+4. **Success State** - Renders slot content
+
+---
+
+## InfoItemList Component
+
+### Basic Two-Column Layout
+
+```vue
+<template>
+  <InfoItemList
+    :items="[
+      { label: 'ชื่อโครงการ', value: project.name },
+      { label: 'รหัสโครงการ', value: project.code },
+      { label: 'สถานะ', value: project.status },
+      { label: 'วันที่เริ่มต้น', value: project.start_date, type: 'date' }
+    ]"
+  />
+</template>
+```
+
+### Vertical Layout
+
+```vue
+<template>
+  <InfoItemList
+    :items="items"
+    :vertical="true"
+  />
+</template>
+```
+
+### Inline Layout
+
+```vue
+<template>
+  <InfoItemList
+    :items="[
+      { label: 'Status:', value: 'Active' },
+      { label: 'Count:', value: '42' }
+    ]"
+    :inline="true"
+  />
+</template>
+```
+
+### With Text Truncation
+
+```vue
+<template>
+  <InfoItemList
+    :items="[
+      { 
+        label: 'Description', 
+        value: longDescription,
+        max: 200  // Truncate at 200 characters
+      }
+    ]"
+  />
+</template>
+```
+
+### With Custom Components
+
+```vue
+<template>
+  <InfoItemList
+    :items="[
+      { 
+        label: 'Status',
+        component: Badge,
+        props: {
+          label: project.status,
+          color: getStatusColor(project.status)
+        }
+      },
+      {
+        label: 'Actions',
+        component: Button,
+        props: {
+          label: 'Edit',
+          icon: 'ph:pencil-simple',
+          onClick: handleEdit
+        }
+      }
+    ]"
+  />
+</template>
+
+<script setup lang="ts">
+import { Badge, Button } from '#components'
+
+const getStatusColor = (status: string) => {
+  return status === 'active' ? 'success' : 'neutral'
+}
+
+const handleEdit = () => {
+  console.log('Edit clicked')
+}
+</script>
+```
+
+### With Slots
+
+```vue
+<template>
+  <InfoItemList :items="items">
+    <template #status-item="{ value }">
+      <Badge 
+        :label="value" 
+        :color="value === 'active' ? 'success' : 'error'"
+      />
+    </template>
+    
+    <template #actions-item>
+      <div class="flex gap-2">
+        <Button label="Edit" size="sm" />
+        <Button label="Delete" size="sm" color="error" />
+      </div>
+    </template>
+  </InfoItemList>
+</template>
+
+<script setup lang="ts">
+const items = [
+  { label: 'Name', value: 'John Doe' },
+  { label: 'Status', value: 'active', key: 'status' },
+  { label: 'Actions', key: 'actions' }
+]
+</script>
+```
+
+### All Item Types
+
+```vue
+<template>
+  <InfoItemList
+    :items="[
+      { label: 'Text', value: 'Sample text', type: 'text' },
+      { label: 'Number', value: 42, type: 'number' },
+      { label: 'Currency', value: 1500.50, type: 'currency' },
+      { label: 'Date', value: '2025-11-07', type: 'date' },
+      { label: 'DateTime', value: '2025-11-07T10:30:00', type: 'date_time' },
+      { label: 'Active', value: true, type: 'boolean' }
+    ]"
+  />
+</template>
+```
+
+### Conditional Display
+
+```vue
+<template>
+  <InfoItemList
+    :items="[
+      { label: 'Name', value: user.name },
+      { label: 'Email', value: user.email },
+      { 
+        label: 'Admin Email', 
+        value: user.admin_email,
+        hide: !user.is_admin  // Conditionally hide
+      }
+    ]"
+  />
+</template>
+```
+
+---
+
+## Button Components
+
+### ActionIcon
+
+```vue
+<template>
+  <div class="flex gap-2">
+    <!-- Edit button -->
+    <ButtonActionIcon
+      icon="ph:pencil-simple"
+      color="primary"
+      @click="handleEdit"
+    />
+    
+    <!-- Delete button -->
+    <ButtonActionIcon
+      icon="ph:trash"
+      color="error"
+      @click="handleDelete"
+    />
+    
+    <!-- View button with navigation -->
+    <ButtonActionIcon
+      icon="ph:eye"
+      color="neutral"
+      :to="`/view/${id}`"
+    />
+    
+    <!-- Loading state -->
+    <ButtonActionIcon
+      icon="ph:check"
+      color="success"
+      :loading="isSubmitting"
+      :disabled="isSubmitting"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+const isSubmitting = ref(false)
+
+const handleEdit = () => {
+  console.log('Edit')
+}
+
+const handleDelete = async () => {
+  isSubmitting.value = true
+  await deleteItem()
+  isSubmitting.value = false
+}
+</script>
+```
+
+### Back Button
+
+```vue
+<template>
+  <div class="space-y-4">
+    <!-- Default back button -->
+    <ButtonBack />
+    
+    <!-- Custom label -->
+    <ButtonBack label="กลับไปหน้ารายการ" />
+    
+    <!-- With route -->
+    <ButtonBack 
+      label="กลับไปหน้าหลัก"
+      :to="routes.home.to"
+    />
+    
+    <!-- With custom handler -->
+    <ButtonBack 
+      label="ยกเลิก"
+      @click="handleCancel"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+const handleCancel = () => {
+  // Custom logic before going back
+  if (confirm('Are you sure?')) {
+    navigateTo(-1)
+  }
+}
+</script>
+```
+
+---
+
+## Layout Components
+
+### Admin Layout
+
+```vue
+<template>
+  <LayoutAdmin
+    label="PMO Admin"
+    :items="navigationItems"
+  >
+    <!-- Page Header -->
+    <template #page-header>
+      <div class="flex items-center justify-between">
+        <h1 class="text-2xl font-bold">Dashboard</h1>
+        <Button label="New Project" icon="ph:plus" />
+      </div>
+    </template>
+
+    <!-- Main Content -->
+    <div class="space-y-6">
+      <Card>
+        <h2>Statistics</h2>
+        <!-- Content -->
+      </Card>
+    </div>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+import type { NavigationMenuItem } from '@nuxt/ui'
+
+const navigationItems: NavigationMenuItem[] = [
+  {
+    label: 'Dashboard',
+    icon: 'i-heroicons-home',
+    to: '/admin/dashboard'
+  },
+  {
+    label: 'Projects',
+    icon: 'i-heroicons-folder',
+    children: [
+      { label: 'All Projects', to: '/admin/projects' },
+      { label: 'Active Projects', to: '/admin/projects/active' },
+      { label: 'Archived', to: '/admin/projects/archived' }
+    ]
+  },
+  {
+    label: 'Users',
+    icon: 'i-heroicons-users',
+    to: '/admin/users'
+  },
+  {
+    label: 'Settings',
+    icon: 'i-heroicons-cog',
+    to: '/admin/settings'
+  }
+]
+</script>
+```
+
+### User Layout
+
+```vue
+<template>
+  <LayoutUser>
+    <div class="container mx-auto px-4 py-8">
+      <h1>My Projects</h1>
+      
+      <StatusBox :status="projects.status.value" :data="projects.data.value">
+        <template #default="{ data }">
+          <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+            <Card v-for="project in data" :key="project.id">
+              <h3>{{ project.name }}</h3>
+              <p>{{ project.description }}</p>
+            </Card>
+          </div>
+        </template>
+      </StatusBox>
+    </div>
+  </LayoutUser>
+</template>
+
+<script setup lang="ts">
+const projects = useListLoader({
+  method: 'GET',
+  url: '/api/my-projects',
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(() => projects.run())
+</script>
+```
+
+---
+
+## Form Patterns
+
+### Basic Form with Validation
+
+```vue
+<template>
+  <form @submit="onSubmit">
+    <div class="space-y-4">
+      <FormField name="name" label="Project Name">
+        <Input v-model="form.values.name" />
+        <FormError name="name" />
+      </FormField>
+
+      <FormField name="description" label="Description">
+        <Textarea v-model="form.values.description" />
+        <FormError name="description" />
+      </FormField>
+
+      <FormField name="status" label="Status">
+        <Select 
+          v-model="form.values.status"
+          :options="statusOptions"
+        />
+        <FormError name="status" />
+      </FormField>
+
+      <div class="flex gap-2">
+        <Button 
+          type="submit" 
+          label="Save"
+          :loading="form.isSubmitting.value"
+        />
+        <ButtonBack />
+      </div>
+    </div>
+  </form>
+</template>
+
+<script setup lang="ts">
+import * as v from 'valibot'
+import { toTypedSchema } from '@vee-validate/valibot'
+
+const form = useForm({
+  validationSchema: toTypedSchema(
+    v.object({
+      name: v.pipe(
+        v.string('Name is required'),
+        v.minLength(3, 'Name must be at least 3 characters')
+      ),
+      description: v.optional(v.string(), ''),
+      status: v.pipe(
+        v.string('Status is required'),
+        v.picklist(['active', 'inactive', 'pending'])
+      )
+    })
+  )
+})
+
+const statusOptions = [
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' },
+  { label: 'Pending', value: 'pending' }
+]
+
+const onSubmit = form.handleSubmit(async (values) => {
+  const loader = useObjectLoader({
+    method: 'POST',
+    url: '/api/projects',
+    getRequestOptions: useRequestOptions().auth
+  })
+  
+  await loader.run({ data: values })
+  
+  if (loader.status.value.isSuccess) {
+    navigateTo('/projects')
+  }
+})
+</script>
+```
+
+### Form with Date Range
+
+```vue
+<template>
+  <form @submit="onSubmit">
+    <FormField name="date_range" label="Date Range">
+      <DatePicker 
+        v-model="form.values.date_range"
+        range
+      />
+      <FormError name="date_range" />
+    </FormField>
+  </form>
+</template>
+
+<script setup lang="ts">
+import * as v from 'valibot'
+import { toTypedSchema } from '@vee-validate/valibot'
+
+const form = useForm({
+  validationSchema: toTypedSchema(
+    v.object({
+      date_range: v.nullish(
+        v.object({
+          start: v.union([v.date(), v.string()]),
+          end: v.union([v.date(), v.string()])
+        })
+      )
+    })
+  )
+})
+</script>
+```
+
+---
+
+## Data Loading Patterns
+
+### Single Object Loading
+
+```vue
+<template>
+  <StatusBox :status="project.status.value" :data="project.data.value">
+    <template #default="{ data }">
+      <Card>
+        <InfoItemList
+          :items="[
+            { label: 'Name', value: data.name },
+            { label: 'Code', value: data.code },
+            { label: 'Status', value: data.status }
+          ]"
+        />
+      </Card>
+    </template>
+  </StatusBox>
+</template>
+
+<script setup lang="ts">
+interface Project {
+  id: string
+  name: string
+  code: string
+  status: string
+}
+
+const route = useRoute()
+const projectId = route.params.id as string
+
+const project = useObjectLoader<Project>({
+  method: 'GET',
+  url: `/api/projects/${projectId}`,
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(() => project.run())
+</script>
+```
+
+### List Loading with Pagination
+
+```vue
+<template>
+  <div class="space-y-4">
+    <!-- Filters -->
+    <Card>
+      <form @submit.prevent="handleFilter">
+        <div class="flex gap-2">
+          <Input 
+            v-model="filters.q" 
+            placeholder="Search..."
+          />
+          <Button type="submit" label="Search" />
+        </div>
+      </form>
+    </Card>
+
+    <!-- List -->
+    <StatusBox :status="projects.status.value" :data="projects.data.value">
+      <template #default="{ data }">
+        <Card>
+          <Table :rows="data.items" :columns="columns" />
+          
+          <Pagination
+            v-model="page"
+            :total="data.total"
+            :per-page="perPage"
+            @update:model-value="loadProjects"
+          />
+        </Card>
+      </template>
+    </StatusBox>
+  </div>
+</template>
+
+<script setup lang="ts">
+const page = ref(1)
+const perPage = ref(10)
+const filters = reactive({
+  q: '',
+  status: ''
+})
+
+const projects = useListLoader({
+  method: 'GET',
+  url: '/api/projects',
+  getRequestOptions: useRequestOptions().auth
+})
+
+const loadProjects = () => {
+  projects.run({
+    params: {
+      page: page.value,
+      per_page: perPage.value,
+      ...filters
+    }
+  })
+}
+
+const handleFilter = () => {
+  page.value = 1
+  loadProjects()
+}
+
+onMounted(() => loadProjects())
+
+const columns = [
+  { key: 'name', label: 'Name' },
+  { key: 'code', label: 'Code' },
+  { key: 'status', label: 'Status' }
+]
+</script>
+```
+
+### Multiple Parallel Requests
+
+```vue
+<template>
+  <div class="space-y-4">
+    <StatusBox :status="user.status.value" :data="user.data.value">
+      <template #default="{ data: userData }">
+        <Card>
+          <h2>User: {{ userData.name }}</h2>
+        </Card>
+      </template>
+    </StatusBox>
+
+    <StatusBox :status="projects.status.value" :data="projects.data.value">
+      <template #default="{ data: projectsData }">
+        <Card>
+          <h2>Projects ({{ projectsData.length }})</h2>
+        </Card>
+      </template>
+    </StatusBox>
+  </div>
+</template>
+
+<script setup lang="ts">
+const user = useObjectLoader({
+  method: 'GET',
+  url: '/api/user/123',
+  getRequestOptions: useRequestOptions().auth
+})
+
+const projects = useListLoader({
+  method: 'GET',
+  url: '/api/user/123/projects',
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(async () => {
+  // Load in parallel
+  await Promise.all([
+    user.run(),
+    projects.run()
+  ])
+})
+</script>
+```
+
+### Dependent Requests
+
+```vue
+<script setup lang="ts">
+const user = useObjectLoader({
+  method: 'GET',
+  url: '/api/user/123',
+  getRequestOptions: useRequestOptions().auth
+})
+
+const projects = useListLoader({
+  method: 'GET',
+  url: computed(() => `/api/teams/${user.data.value?.team_id}/projects`),
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(async () => {
+  // Load user first
+  await user.run()
+  
+  // Then load projects based on user's team
+  if (user.status.value.isSuccess && user.data.value?.team_id) {
+    await projects.run()
+  }
+})
+</script>
+```
+
+---
+
+## Complete Page Example
+
+```vue
+<template>
+  <LayoutAdmin label="Projects" :items="navItems">
+    <div class="space-y-6">
+      <!-- Page Header -->
+      <div class="flex items-center justify-between">
+        <div>
+          <h1 class="text-2xl font-bold">Projects</h1>
+          <p class="text-gray-600">Manage your projects</p>
+        </div>
+        <Button 
+          label="New Project" 
+          icon="ph:plus"
+          :to="routes.pmo.project.new.to"
+        />
+      </div>
+
+      <!-- Filters -->
+      <Card>
+        <form @submit.prevent="handleFilter">
+          <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
+            <FormField name="q" label="Search">
+              <Input v-model="form.values.q" placeholder="Search..." />
+            </FormField>
+            
+            <FormField name="status" label="Status">
+              <Select 
+                v-model="form.values.status"
+                :options="statusOptions"
+              />
+            </FormField>
+            
+            <div class="flex items-end gap-2">
+              <Button type="submit" label="Filter" />
+              <Button 
+                type="button" 
+                label="Reset" 
+                variant="outline"
+                @click="handleReset"
+              />
+            </div>
+          </div>
+        </form>
+      </Card>
+
+      <!-- Projects List -->
+      <StatusBox :status="projects.status.value" :data="projects.data.value">
+        <template #default="{ data }">
+          <Card>
+            <Table 
+              :rows="data.items" 
+              :columns="columns"
+            >
+              <template #actions="{ row }">
+                <div class="flex gap-2">
+                  <ButtonActionIcon
+                    icon="ph:eye"
+                    :to="`/projects/${row.id}`"
+                  />
+                  <ButtonActionIcon
+                    icon="ph:pencil-simple"
+                    color="primary"
+                    :to="`/projects/${row.id}/edit`"
+                  />
+                </div>
+              </template>
+            </Table>
+            
+            <Pagination
+              v-model="page"
+              :total="data.total"
+              :per-page="perPage"
+            />
+          </Card>
+        </template>
+      </StatusBox>
+    </div>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+import * as v from 'valibot'
+import { toTypedSchema } from '@vee-validate/valibot'
+
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['pmo:USER', 'pmo:ADMIN']
+  }
+})
+
+const page = ref(1)
+const perPage = ref(10)
+
+const form = useForm({
+  validationSchema: toTypedSchema(
+    v.object({
+      q: v.optional(v.string(), ''),
+      status: v.optional(v.string(), '')
+    })
+  )
+})
+
+const projects = useListLoader({
+  method: 'GET',
+  url: '/api/projects',
+  getRequestOptions: useRequestOptions().auth
+})
+
+const loadProjects = () => {
+  projects.run({
+    params: {
+      page: page.value,
+      per_page: perPage.value,
+      ...form.values
+    }
+  })
+}
+
+const handleFilter = () => {
+  page.value = 1
+  loadProjects()
+}
+
+const handleReset = () => {
+  form.resetForm()
+  handleFilter()
+}
+
+watch(page, () => loadProjects())
+
+onMounted(() => loadProjects())
+
+const columns = [
+  { key: 'name', label: 'Name' },
+  { key: 'code', label: 'Code' },
+  { key: 'status', label: 'Status' },
+  { key: 'actions', label: 'Actions' }
+]
+
+const statusOptions = [
+  { label: 'All', value: '' },
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' }
+]
+
+const navItems = [
+  { label: 'Dashboard', to: '/admin', icon: 'i-heroicons-home' },
+  { label: 'Projects', to: '/admin/projects', icon: 'i-heroicons-folder' }
+]
+</script>
+```
+
+---
+
+**Last Updated:** 2025-11-07
+