@finema/finework-layer 0.2.50 → 0.2.51

package/API_REFERENCE.md

@@ -0,0 +1,780 @@
+# API Reference
+
+## 🎯 Composables
+
+### useAuth()
+
+Authentication and authorization composable.
+
+```typescript
+const auth = useAuth()
+```
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `token` | `Ref<string \| undefined>` | Authentication token (cookie-based) |
+| `isAuthenticated` | `ComputedRef<boolean>` | Whether user is authenticated |
+| `me.value` | `IUser \| null` | Current user object |
+| `me.timestamp` | `number \| null` | Last fetch timestamp |
+| `isSuperAdmin` | `ComputedRef<boolean>` | Whether user is super admin |
+| `menusNavbar` | `ComputedRef<MenuItem[]>` | Navigation menu items |
+
+#### Methods
+
+##### `loginSlack()`
+Redirect to Slack OAuth login.
+
+```typescript
+auth.loginSlack()
+```
+
+##### `loginMs()`
+Redirect to Microsoft OAuth login.
+
+```typescript
+auth.loginMs()
+```
+
+##### `fetchMe.run()`
+Fetch current user data.
+
+```typescript
+await auth.fetchMe.run()
+
+// Access data
+if (auth.fetchMe.status.value.isSuccess) {
+  console.log(auth.me.value)
+}
+```
+
+##### `updateMe.run(data)`
+Update current user profile.
+
+```typescript
+await auth.updateMe.run({
+  data: {
+    display_name: 'New Name',
+    position: 'Senior Developer'
+  }
+})
+```
+
+##### `hasPermission(module, ...permissions)`
+Check if user has specific permissions.
+
+```typescript
+// Single permission
+auth.hasPermission(UserModule.PMO, Permission.ADMIN)
+
+// Multiple permissions (OR logic)
+auth.hasPermission(UserModule.PMO, Permission.ADMIN, Permission.SUPER)
+```
+
+**Parameters:**
+- `module`: `UserModule` - The module to check
+- `permissions`: `Permission[]` - One or more permissions
+
+**Returns:** `boolean`
+
+---
+
+### useRequestOptions()
+
+HTTP request configuration provider.
+
+```typescript
+const { auth, base, mock, file } = useRequestOptions()
+```
+
+#### Methods
+
+##### `auth()`
+Returns authenticated request configuration.
+
+```typescript
+const options = auth()
+// {
+//   baseURL: 'https://api.example.com',
+//   headers: {
+//     Authorization: 'Bearer <token>'
+//   }
+// }
+```
+
+##### `base()`
+Returns base request configuration (no auth).
+
+```typescript
+const options = base()
+// {
+//   baseURL: 'https://api.example.com'
+// }
+```
+
+##### `mock()`
+Returns mock API configuration.
+
+```typescript
+const options = mock()
+// {
+//   baseURL: 'http://localhost:3000/api/mock'
+// }
+```
+
+##### `file()`
+Returns file upload configuration.
+
+```typescript
+const options = file()
+// {
+//   baseURL: 'https://api.example.com/uploads',
+//   headers: {
+//     Authorization: 'Bearer <token>'
+//   }
+// }
+```
+
+---
+
+### useApp()
+
+Application-level utilities (from @finema/core).
+
+```typescript
+const app = useApp()
+```
+
+#### Methods
+
+##### `definePage(options)`
+Define page metadata.
+
+```typescript
+app.definePage({
+  title: 'Projects',
+  breadcrumbs: [
+    { label: 'Home', to: '/' },
+    { label: 'Projects', to: '/projects' }
+  ]
+})
+```
+
+---
+
+### useObjectLoader<T>()
+
+Single object data loader (from @finema/core).
+
+```typescript
+const loader = useObjectLoader<T>({
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  url: string,
+  getRequestOptions: () => AxiosRequestConfig
+})
+```
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `Ref<T \| null>` | Loaded data |
+| `status` | `Ref<IStatus>` | Request status |
+| `status.value.isLoading` | `boolean` | Loading state |
+| `status.value.isSuccess` | `boolean` | Success state |
+| `status.value.isError` | `boolean` | Error state |
+| `status.value.errorData` | `any` | Error details |
+
+#### Methods
+
+##### `run(options?)`
+Execute the request.
+
+```typescript
+// GET request
+await loader.run()
+
+// POST/PUT/PATCH with data
+await loader.run({
+  data: { name: 'Project Name' }
+})
+
+// With query params
+await loader.run({
+  params: { id: '123' }
+})
+```
+
+---
+
+### useListLoader<T>()
+
+List/pagination data loader (from @finema/core).
+
+```typescript
+const loader = useListLoader<T>({
+  method: 'GET',
+  url: string,
+  getRequestOptions: () => AxiosRequestConfig
+})
+```
+
+#### Properties
+
+Same as `useObjectLoader`, but `data.value` has structure:
+
+```typescript
+{
+  items: T[],
+  total: number,
+  page: number,
+  per_page: number
+}
+```
+
+#### Methods
+
+##### `run(options?)`
+
+```typescript
+await loader.run({
+  params: {
+    page: 1,
+    per_page: 10,
+    q: 'search term',
+    status: 'active'
+  }
+})
+```
+
+---
+
+### useForm()
+
+Form handling with validation (from @finema/core).
+
+```typescript
+import * as v from 'valibot'
+import { toTypedSchema } from '@vee-validate/valibot'
+
+const form = useForm({
+  validationSchema: toTypedSchema(
+    v.object({
+      name: v.pipe(v.string(), v.minLength(3)),
+      email: v.pipe(v.string(), v.email())
+    })
+  ),
+  initialValues: {
+    name: '',
+    email: ''
+  }
+})
+```
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `values` | `Ref<FormValues>` | Current form values |
+| `errors` | `Ref<FormErrors>` | Validation errors |
+| `isSubmitting` | `Ref<boolean>` | Submission state |
+| `isValid` | `Ref<boolean>` | Validation state |
+
+#### Methods
+
+##### `handleSubmit(callback)`
+Create submit handler.
+
+```typescript
+const onSubmit = form.handleSubmit(async (values) => {
+  // values are validated
+  await saveData(values)
+})
+```
+
+##### `setFieldValue(field, value)`
+Set single field value.
+
+```typescript
+form.setFieldValue('name', 'John Doe')
+```
+
+##### `setValues(values)`
+Set multiple field values.
+
+```typescript
+form.setValues({
+  name: 'John Doe',
+  email: 'john@example.com'
+})
+```
+
+##### `resetForm()`
+Reset form to initial values.
+
+```typescript
+form.resetForm()
+```
+
+##### `setErrors(errors)`
+Set validation errors manually.
+
+```typescript
+form.setErrors({
+  name: 'Name is required',
+  email: 'Invalid email'
+})
+```
+
+---
+
+## 🎨 Components
+
+### StatusBox
+
+Loading/error/empty state handler.
+
+```vue
+<StatusBox 
+  :status="IStatus" 
+  :data="T | null"
+  :skip="boolean"
+>
+  <template #default="{ data: T }">
+    <!-- Content -->
+  </template>
+</StatusBox>
+```
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `status` | `IStatus` | Yes | Request status object |
+| `data` | `T \| null` | Yes | Data to display |
+| `skip` | `boolean` | No | Skip status checking |
+
+#### Slots
+
+| Slot | Props | Description |
+|------|-------|-------------|
+| `default` | `{ data: T }` | Content when data loaded |
+
+---
+
+### InfoItemList
+
+Key-value information display.
+
+```vue
+<InfoItemList
+  :items="InfoItem[]"
+  :vertical="boolean"
+  :inline="boolean"
+  :customClass="string"
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `InfoItem[]` | Required | Items to display |
+| `vertical` | `boolean` | `false` | Stack vertically |
+| `inline` | `boolean` | `false` | Inline label/value |
+| `customClass` | `string` | `''` | Additional CSS classes |
+
+#### InfoItem Interface
+
+```typescript
+interface InfoItem {
+  label: string                    // Display label
+  value?: any                      // Display value
+  component?: Component            // Custom component
+  props?: Record<string, any>      // Component props
+  max?: number                     // Truncate length
+  key?: string                     // Slot key
+  type?: 'text' | 'number' | 'currency' | 'date' | 'date_time' | 'boolean'
+  customClass?: string             // Item CSS classes
+  hide?: boolean                   // Conditional hide
+}
+```
+
+#### Slots
+
+Dynamic slots based on item `key`:
+
+```vue
+<template #[key]-item="{ value, item, row, label }">
+  <!-- Custom rendering -->
+</template>
+```
+
+---
+
+### ButtonActionIcon
+
+Icon-only action button.
+
+```vue
+<ButtonActionIcon
+  :icon="string"
+  :color="'neutral' | 'error' | 'primary' | 'success' | 'warning' | 'info'"
+  :disabled="boolean"
+  :loading="boolean"
+  :to="string"
+  @click="handler"
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `string` | Required | Icon name |
+| `color` | `string` | `'neutral'` | Button color |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `loading` | `boolean` | `false` | Loading state |
+| `to` | `string` | - | Navigation target |
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | - | Click handler |
+
+---
+
+### ButtonBack
+
+Back navigation button.
+
+```vue
+<ButtonBack
+  :label="string"
+  :to="string"
+  @click="handler"
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | `'กลับ'` | Button label |
+| `to` | `string` | - | Navigation target |
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | - | Click handler |
+
+---
+
+### LayoutAdmin
+
+Admin layout with sidebar.
+
+```vue
+<LayoutAdmin
+  :label="string"
+  :items="NavigationMenuItem[]"
+  :isGroup="boolean"
+>
+  <!-- Content -->
+</LayoutAdmin>
+```
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `label` | `string` | Yes | Layout title |
+| `items` | `NavigationMenuItem[]` | Yes | Navigation items |
+| `isGroup` | `boolean` | No | Group navigation |
+
+#### NavigationMenuItem Interface
+
+```typescript
+interface NavigationMenuItem {
+  label: string
+  icon?: string
+  to?: string
+  children?: NavigationMenuItem[]
+  badge?: string | number
+  disabled?: boolean
+}
+```
+
+---
+
+### LayoutUser
+
+User-facing layout.
+
+```vue
+<LayoutUser>
+  <!-- Content -->
+</LayoutUser>
+```
+
+No props required.
+
+---
+
+## 📊 Types & Interfaces
+
+### IUser
+
+```typescript
+interface IUser {
+  id: string
+  email: string
+  full_name: string
+  display_name: string
+  position: string
+  team: ITeam
+  team_code: string
+  avatar_url: string
+  company: string
+  access_level: IUserAccessLevel
+  is_active: boolean
+  joined_date: string
+  slack_id: string
+  created_at: string
+  updated_at: string
+}
+```
+
+### ITeam
+
+```typescript
+interface ITeam {
+  id: string
+  name: string
+  code: string
+  color: string
+  description?: string
+  working_start_at: string
+  working_end_at: string
+  users: IUser[] | null
+  created_at: string
+  updated_at: string
+}
+```
+
+### IUserAccessLevel
+
+```typescript
+interface IUserAccessLevel {
+  used_id: string
+  pmo: Permission.USER | Permission.ADMIN | Permission.SUPER
+  clockin: Permission.USER | Permission.ADMIN
+  timesheet: Permission.USER | Permission.ADMIN
+  setting: Permission.USER | Permission.SUPER
+}
+```
+
+### IStatus
+
+```typescript
+interface IStatus {
+  isLoading: boolean
+  isSuccess: boolean
+  isError: boolean
+  errorData?: {
+    code?: string
+    message?: string
+    [key: string]: any
+  }
+}
+```
+
+---
+
+## 🔐 Enums
+
+### Permission
+
+```typescript
+enum Permission {
+  USER = 'USER',
+  ADMIN = 'ADMIN',
+  SUPER = 'SUPER',
+  NONE = 'NONE'
+}
+```
+
+### UserModule
+
+```typescript
+enum UserModule {
+  CHECKIN = 'clockin',
+  PMO = 'pmo',
+  TIMESHEET = 'timesheet',
+  SETTING = 'setting'
+}
+```
+
+---
+
+## 🛣️ Constants
+
+### routes
+
+All application routes.
+
+```typescript
+const routes = {
+  home: { label: 'หน้าแรก', to: '/' },
+  login: { label: 'เลือก', to: '/login' },
+  logout: { label: 'Log out', to: '/api/auth/logout' },
+  
+  account: {
+    profile: { label: 'โปรไฟล์', to: '/account/profile', icon: 'mage:user' }
+  },
+  
+  clockin: {
+    home: { label: 'Clock-In', icon: 'i-heroicons-outline:location-marker', to: '/clockin' }
+  },
+  
+  timesheet: {
+    home: { label: 'Timesheet', icon: 'mage:dashboard', to: '/timesheet' }
+  },
+  
+  pmo: {
+    project: {
+      projects: { 
+        label: 'โครงการของฉัน', 
+        to: '/pmo/projects', 
+        icon: 'lucide:layers',
+        permissions: ['pmo:USER', 'pmo:ADMIN', 'pmo:SUPER']
+      }
+    }
+  },
+  
+  admin: {
+    users: { label: 'จัดการผู้ใช้งาน', icon: 'hugeicons:user-circle-02', to: '/admin/users' }
+  }
+} as const
+```
+
+Usage:
+
+```typescript
+navigateTo(routes.pmo.project.projects.to)
+```
+
+---
+
+## 🎯 Middleware
+
+### auth
+
+Requires authentication.
+
+```typescript
+definePageMeta({
+  middleware: 'auth'
+})
+```
+
+**Behavior:**
+- Redirects to login if not authenticated
+- Fetches user data if needed
+- Checks if user is active
+- Redirects to team selection if no team
+
+### permissions
+
+Permission-based access control.
+
+```typescript
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['pmo:ADMIN', 'pmo:SUPER'],
+    redirectTo: '/unauthorized'  // Optional
+  }
+})
+```
+
+**Behavior:**
+- Checks if user has any of the specified permissions
+- Redirects to `redirectTo` or returns 403
+
+### guest
+
+Guest-only routes.
+
+```typescript
+definePageMeta({
+  middleware: 'guest'
+})
+```
+
+**Behavior:**
+- Redirects authenticated users to home
+
+### common
+
+Common pre-route logic.
+
+```typescript
+definePageMeta({
+  middleware: 'common'
+})
+```
+
+**Behavior:**
+- Fetches user data if authenticated and needed
+- Runs on all routes
+
+---
+
+## 🎨 App Config
+
+```typescript
+// app/app.config.ts
+export default defineAppConfig({
+  core: {
+    is_thai_year: boolean,
+    is_thai_month: boolean,
+    date_format: string,
+    month_format: string,
+    date_time_format: string,
+    color: string,
+    limit_per_page: number,
+    locale: string
+  },
+  ui: {
+    // Nuxt UI customization
+  }
+})
+```
+
+Access in components:
+
+```typescript
+const appConfig = useAppConfig()
+console.log(appConfig.core.date_format)
+```
+
+---
+
+## 🔧 Runtime Config
+
+```typescript
+const config = useRuntimeConfig()
+
+config.public.baseAPI      // API base URL
+config.public.baseAPIMock  // Mock API URL
+```
+
+---
+
+**Last Updated:** 2025-11-07  
+**Version:** 0.2.50
+