@finema/finework-layer 0.2.50 → 0.2.52

package/QUICK_START.md

@@ -0,0 +1,678 @@
+# Quick Start Guide
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js 18+ or Bun
+- pnpm (recommended) or npm
+- Basic knowledge of Vue 3 and Nuxt 3
+
+### Installation
+
+#### 1. Install the Layer
+
+```bash
+pnpm add @finema/finework-layer
+```
+
+#### 2. Extend in Your Nuxt Config
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@finema/finework-layer']
+})
+```
+
+#### 3. Configure Runtime Variables
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@finema/finework-layer'],
+  
+  runtimeConfig: {
+    public: {
+      baseAPI: process.env.NUXT_PUBLIC_BASE_API || 'http://localhost:8000',
+      baseAPIMock: process.env.NUXT_PUBLIC_BASE_API_MOCK || 'http://localhost:3000/api/mock'
+    }
+  }
+})
+```
+
+#### 4. Create Environment File
+
+```bash
+# .env
+NUXT_PUBLIC_BASE_API=https://api.yourapp.com
+```
+
+---
+
+## 📝 Your First Page
+
+### 1. Create a Protected Page
+
+```vue
+<!-- pages/projects/index.vue -->
+<template>
+  <LayoutAdmin label="Projects" :items="navItems">
+    <div class="space-y-6">
+      <h1 class="text-2xl font-bold">My Projects</h1>
+      
+      <StatusBox :status="projects.status.value" :data="projects.data.value">
+        <template #default="{ data }">
+          <Card>
+            <div v-for="project in data" :key="project.id" class="p-4 border-b">
+              <h3 class="font-semibold">{{ project.name }}</h3>
+              <p class="text-gray-600">{{ project.description }}</p>
+            </div>
+          </Card>
+        </template>
+      </StatusBox>
+    </div>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+// Define page metadata
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['pmo:USER', 'pmo:ADMIN']
+  }
+})
+
+// Define navigation
+const navItems = [
+  { label: 'Dashboard', to: '/dashboard', icon: 'i-heroicons-home' },
+  { label: 'Projects', to: '/projects', icon: 'i-heroicons-folder' }
+]
+
+// Load data
+interface Project {
+  id: string
+  name: string
+  description: string
+}
+
+const projects = useListLoader<Project>({
+  method: 'GET',
+  url: '/api/projects',
+  getRequestOptions: useRequestOptions().auth
+})
+
+onMounted(() => projects.run())
+</script>
+```
+
+### 2. Create a Form Page
+
+```vue
+<!-- pages/projects/new.vue -->
+<template>
+  <LayoutAdmin label="New Project" :items="navItems">
+    <Card>
+      <form @submit="onSubmit" 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>
+
+        <div class="flex gap-2">
+          <Button 
+            type="submit" 
+            label="Create Project"
+            :loading="form.isSubmitting.value"
+          />
+          <ButtonBack :to="routes.pmo.project.projects.to" />
+        </div>
+      </form>
+    </Card>
+  </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 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(), '')
+    })
+  )
+})
+
+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(routes.pmo.project.projects.to)
+  }
+})
+
+const navItems = [
+  { label: 'Projects', to: '/projects', icon: 'i-heroicons-folder' }
+]
+</script>
+```
+
+---
+
+## 🎯 Common Tasks
+
+### Task 1: Add a New Route
+
+#### Step 1: Define Route Constant
+
+```typescript
+// app/constants/routes.ts (in your project)
+export const myRoutes = {
+  ...routes,  // Extend existing routes
+  
+  myModule: {
+    dashboard: {
+      label: 'Dashboard',
+      to: '/my-module/dashboard',
+      icon: 'i-heroicons-chart-bar'
+    },
+    settings: {
+      label: 'Settings',
+      to: '/my-module/settings',
+      icon: 'i-heroicons-cog'
+    }
+  }
+}
+```
+
+#### Step 2: Create Page
+
+```vue
+<!-- pages/my-module/dashboard.vue -->
+<template>
+  <LayoutAdmin label="My Module" :items="navItems">
+    <h1>Dashboard</h1>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+const navItems = [
+  { label: 'Dashboard', to: myRoutes.myModule.dashboard.to },
+  { label: 'Settings', to: myRoutes.myModule.settings.to }
+]
+</script>
+```
+
+---
+
+### Task 2: Create a Custom Component
+
+```vue
+<!-- components/ProjectCard.vue -->
+<template>
+  <Card class="hover:shadow-lg transition-shadow">
+    <div class="space-y-2">
+      <div class="flex items-center justify-between">
+        <h3 class="text-lg font-semibold">{{ project.name }}</h3>
+        <Badge :label="project.status" :color="statusColor" />
+      </div>
+      
+      <p class="text-gray-600">{{ project.description }}</p>
+      
+      <div class="flex gap-2 pt-4">
+        <ButtonActionIcon
+          icon="ph:eye"
+          :to="`/projects/${project.id}`"
+        />
+        <ButtonActionIcon
+          icon="ph:pencil-simple"
+          color="primary"
+          :to="`/projects/${project.id}/edit`"
+        />
+      </div>
+    </div>
+  </Card>
+</template>
+
+<script setup lang="ts">
+interface Project {
+  id: string
+  name: string
+  description: string
+  status: string
+}
+
+const props = defineProps<{
+  project: Project
+}>()
+
+const statusColor = computed(() => {
+  return props.project.status === 'active' ? 'success' : 'neutral'
+})
+</script>
+```
+
+Usage:
+
+```vue
+<ProjectCard 
+  v-for="project in projects" 
+  :key="project.id"
+  :project="project"
+/>
+```
+
+---
+
+### Task 3: Add Permission Check
+
+```vue
+<template>
+  <div>
+    <!-- Show only to admins -->
+    <Button 
+      v-if="canEdit"
+      label="Edit"
+      @click="handleEdit"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+const auth = useAuth()
+
+const canEdit = computed(() => 
+  auth.hasPermission(UserModule.PMO, Permission.ADMIN, Permission.SUPER)
+)
+
+const handleEdit = () => {
+  // Edit logic
+}
+</script>
+```
+
+---
+
+### Task 4: Handle File Upload
+
+```vue
+<template>
+  <form @submit.prevent="handleUpload">
+    <FormField name="file" label="Upload File">
+      <input 
+        type="file" 
+        @change="handleFileChange"
+        accept=".pdf,.doc,.docx"
+      />
+    </FormField>
+    
+    <Button 
+      type="submit" 
+      label="Upload"
+      :loading="isUploading"
+    />
+  </form>
+</template>
+
+<script setup lang="ts">
+const file = ref<File | null>(null)
+const isUploading = ref(false)
+
+const handleFileChange = (event: Event) => {
+  const target = event.target as HTMLInputElement
+  file.value = target.files?.[0] || null
+}
+
+const handleUpload = async () => {
+  if (!file.value) return
+  
+  isUploading.value = true
+  
+  const formData = new FormData()
+  formData.append('file', file.value)
+  
+  const loader = useObjectLoader({
+    method: 'POST',
+    url: '/api/upload',
+    getRequestOptions: useRequestOptions().file
+  })
+  
+  await loader.run({ data: formData })
+  
+  isUploading.value = false
+  
+  if (loader.status.value.isSuccess) {
+    console.log('Upload successful:', loader.data.value)
+  }
+}
+</script>
+```
+
+---
+
+### Task 5: Implement Search & Filter
+
+```vue
+<template>
+  <div class="space-y-4">
+    <!-- Search Form -->
+    <Card>
+      <form @submit.prevent="handleSearch">
+        <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
+          <Input 
+            v-model="filters.q" 
+            placeholder="Search..."
+          />
+          
+          <Select 
+            v-model="filters.status"
+            :options="statusOptions"
+          />
+          
+          <div class="flex gap-2">
+            <Button type="submit" label="Search" />
+            <Button 
+              type="button" 
+              label="Reset" 
+              variant="outline"
+              @click="handleReset"
+            />
+          </div>
+        </div>
+      </form>
+    </Card>
+
+    <!-- Results -->
+    <StatusBox :status="results.status.value" :data="results.data.value">
+      <template #default="{ data }">
+        <Card>
+          <div v-for="item in data.items" :key="item.id">
+            {{ item.name }}
+          </div>
+          
+          <Pagination
+            v-model="page"
+            :total="data.total"
+            :per-page="perPage"
+          />
+        </Card>
+      </template>
+    </StatusBox>
+  </div>
+</template>
+
+<script setup lang="ts">
+const page = ref(1)
+const perPage = ref(10)
+const filters = reactive({
+  q: '',
+  status: ''
+})
+
+const results = useListLoader({
+  method: 'GET',
+  url: '/api/search',
+  getRequestOptions: useRequestOptions().auth
+})
+
+const loadResults = () => {
+  results.run({
+    params: {
+      page: page.value,
+      per_page: perPage.value,
+      ...filters
+    }
+  })
+}
+
+const handleSearch = () => {
+  page.value = 1
+  loadResults()
+}
+
+const handleReset = () => {
+  filters.q = ''
+  filters.status = ''
+  handleSearch()
+}
+
+watch(page, () => loadResults())
+
+onMounted(() => loadResults())
+
+const statusOptions = [
+  { label: 'All', value: '' },
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' }
+]
+</script>
+```
+
+---
+
+## 🎨 Customization
+
+### Override UI Theme
+
+```typescript
+// app/app.config.ts
+export default defineAppConfig({
+  core: {
+    color: '#FF6B6B',  // Primary color
+    date_format: 'dd/MM/yyyy',
+    locale: 'th'
+  },
+  
+  ui: {
+    button: {
+      defaultVariants: {
+        color: 'primary',
+        variant: 'solid'
+      }
+    },
+    
+    card: {
+      variants: {
+        variant: {
+          custom: {
+            root: 'bg-gradient-to-r from-blue-500 to-purple-500'
+          }
+        }
+      }
+    }
+  }
+})
+```
+
+### Add Custom Middleware
+
+```typescript
+// middleware/analytics.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  // Track page view
+  console.log('Page view:', to.path)
+  
+  // Send to analytics
+  if (import.meta.client) {
+    // Your analytics code
+  }
+})
+```
+
+Use it:
+
+```typescript
+definePageMeta({
+  middleware: ['auth', 'analytics']
+})
+```
+
+---
+
+## 🧪 Testing
+
+### Component Test
+
+```typescript
+// tests/components/ProjectCard.test.ts
+import { mount } from '@nuxt/test-utils'
+import ProjectCard from '~/components/ProjectCard.vue'
+
+describe('ProjectCard', () => {
+  it('renders project name', () => {
+    const wrapper = mount(ProjectCard, {
+      props: {
+        project: {
+          id: '1',
+          name: 'Test Project',
+          description: 'Test Description',
+          status: 'active'
+        }
+      }
+    })
+    
+    expect(wrapper.text()).toContain('Test Project')
+  })
+})
+```
+
+### Integration Test
+
+```typescript
+// tests/pages/projects.test.ts
+import { setup, $fetch } from '@nuxt/test-utils'
+
+describe('Projects Page', () => {
+  await setup({
+    // Test configuration
+  })
+
+  it('loads projects', async () => {
+    const html = await $fetch('/projects')
+    expect(html).toContain('My Projects')
+  })
+})
+```
+
+---
+
+## 📦 Deployment
+
+### Build for Production
+
+```bash
+pnpm build
+```
+
+### Preview Production Build
+
+```bash
+pnpm preview
+```
+
+### Environment Variables
+
+```bash
+# .env.production
+NUXT_PUBLIC_BASE_API=https://api.production.com
+```
+
+---
+
+## 🔍 Debugging
+
+### Enable Nuxt DevTools
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  devtools: {
+    enabled: true
+  }
+})
+```
+
+### Debug Authentication
+
+```typescript
+const auth = useAuth()
+
+console.log('Token:', auth.token.value)
+console.log('User:', auth.me.value)
+console.log('Is Authenticated:', auth.isAuthenticated.value)
+console.log('Permissions:', auth.me.value?.access_level)
+```
+
+### Debug Data Loading
+
+```typescript
+const loader = useObjectLoader({...})
+
+watch(() => loader.status.value, (status) => {
+  console.log('Loading:', status.isLoading)
+  console.log('Success:', status.isSuccess)
+  console.log('Error:', status.isError)
+  console.log('Data:', loader.data.value)
+})
+```
+
+---
+
+## 📚 Next Steps
+
+1. **Read the [LLM Guide](./LLM_GUIDE.md)** - Comprehensive documentation
+2. **Check [Component Examples](./COMPONENT_EXAMPLES.md)** - Real-world examples
+3. **Review [API Reference](./API_REFERENCE.md)** - Detailed API docs
+4. **Study [Architecture](./ARCHITECTURE.md)** - System design
+
+---
+
+## 💡 Tips
+
+1. **Use Auto-imports** - No need to import components, composables, or constants
+2. **Follow Existing Patterns** - Check existing code before creating new patterns
+3. **Type Everything** - Use TypeScript for better DX
+4. **Use StatusBox** - For consistent loading/error states
+5. **Check Permissions** - Always validate user permissions
+6. **Use Route Constants** - Never hardcode routes
+7. **Leverage @finema/core** - Many utilities already exist
+
+---
+
+## 🆘 Getting Help
+
+1. Check existing components and pages for examples
+2. Review the documentation files
+3. Use Nuxt DevTools for debugging
+4. Check browser console for errors
+5. Review network requests in DevTools
+
+---
+
+**Last Updated:** 2025-11-07  
+**Happy Coding! 🚀**
+