@finema/finework-layer 0.2.50 → 0.2.52

package/TROUBLESHOOTING.md

@@ -0,0 +1,646 @@
+# Troubleshooting Guide
+
+## 🔧 Common Issues & Solutions
+
+### Authentication Issues
+
+#### Issue: "Token not found" or "Unauthorized"
+
+**Symptoms:**
+- Redirected to login page repeatedly
+- API requests return 401 errors
+- `auth.token.value` is undefined
+
+**Solutions:**
+
+1. **Check Cookie Configuration**
+```typescript
+// Verify cookie is being set correctly
+const token = useCookie('token', {
+  path: '/',
+  maxAge: 60 * 60 * 24 * 365
+})
+
+console.log('Token:', token.value)
+```
+
+2. **Verify API Response**
+- Backend must set the cookie with correct domain
+- Cookie must be HttpOnly and Secure in production
+- Check browser DevTools > Application > Cookies
+
+3. **Check CORS Settings**
+```typescript
+// Backend must allow credentials
+Access-Control-Allow-Credentials: true
+Access-Control-Allow-Origin: https://your-domain.com
+```
+
+4. **Clear Browser Cookies**
+```javascript
+// In browser console
+document.cookie.split(";").forEach(c => {
+  document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=" + new Date().toUTCString() + ";path=/");
+});
+```
+
+---
+
+#### Issue: User data not loading
+
+**Symptoms:**
+- `auth.me.value` is null
+- Page shows loading state indefinitely
+
+**Solutions:**
+
+1. **Check API Endpoint**
+```typescript
+const auth = useAuth()
+
+// Manually trigger fetch
+await auth.fetchMe.run()
+
+// Check status
+console.log('Status:', auth.fetchMe.status.value)
+console.log('Error:', auth.fetchMe.status.value.errorData)
+```
+
+2. **Verify Middleware Order**
+```typescript
+// Correct order
+definePageMeta({
+  middleware: ['common', 'auth', 'permissions']
+})
+```
+
+3. **Check Cache Timing**
+```typescript
+// Force refresh
+auth.me.setTimestamp(null)
+await auth.fetchMe.run()
+```
+
+---
+
+### Permission Issues
+
+#### Issue: "Access Denied" or 403 errors
+
+**Symptoms:**
+- User redirected to error page
+- Cannot access certain routes
+- Features hidden unexpectedly
+
+**Solutions:**
+
+1. **Verify User Permissions**
+```typescript
+const auth = useAuth()
+
+console.log('Access Level:', auth.me.value?.access_level)
+console.log('Has PMO Admin:', auth.hasPermission(UserModule.PMO, Permission.ADMIN))
+```
+
+2. **Check Route Configuration**
+```typescript
+definePageMeta({
+  middleware: ['auth', 'permissions'],
+  accessGuard: {
+    permissions: ['pmo:USER', 'pmo:ADMIN'],  // OR logic
+    redirectTo: '/unauthorized'
+  }
+})
+```
+
+3. **Debug Permission Check**
+```typescript
+const canAccess = computed(() => {
+  const result = auth.hasPermission(UserModule.PMO, Permission.ADMIN)
+  console.log('Can Access:', result)
+  console.log('User Module:', auth.me.value?.access_level?.pmo)
+  return result
+})
+```
+
+---
+
+### Data Loading Issues
+
+#### Issue: Data not loading or infinite loading
+
+**Symptoms:**
+- StatusBox shows loading spinner forever
+- `loader.data.value` is null
+- No error messages
+
+**Solutions:**
+
+1. **Check Loader Configuration**
+```typescript
+const loader = useObjectLoader({
+  method: 'GET',
+  url: '/api/data',
+  getRequestOptions: useRequestOptions().auth  // Make sure this is correct
+})
+
+// Verify it's being called
+onMounted(() => {
+  console.log('Loading data...')
+  loader.run()
+})
+```
+
+2. **Check API Response**
+```typescript
+// Add error handling
+watch(() => loader.status.value, (status) => {
+  console.log('Loading:', status.isLoading)
+  console.log('Success:', status.isSuccess)
+  console.log('Error:', status.isError)
+  
+  if (status.isError) {
+    console.error('Error Data:', status.errorData)
+  }
+  
+  if (status.isSuccess) {
+    console.log('Data:', loader.data.value)
+  }
+})
+```
+
+3. **Verify API Endpoint**
+```typescript
+// Check full URL
+const config = useRuntimeConfig()
+console.log('Base URL:', config.public.baseAPI)
+console.log('Full URL:', config.public.baseAPI + '/api/data')
+```
+
+4. **Check Network Tab**
+- Open DevTools > Network
+- Look for failed requests
+- Check request headers (Authorization)
+- Verify response status and body
+
+---
+
+#### Issue: Data loads but StatusBox shows error
+
+**Symptoms:**
+- Network request succeeds
+- Data is in response
+- StatusBox shows error state
+
+**Solutions:**
+
+1. **Check Data Structure**
+```typescript
+// StatusBox expects data to be truthy
+// If API returns { data: null }, StatusBox will show error
+
+// Solution: Transform response
+const loader = useObjectLoader({
+  method: 'GET',
+  url: '/api/data',
+  getRequestOptions: useRequestOptions().auth
+})
+
+const transformedData = computed(() => {
+  return loader.data.value?.data || loader.data.value
+})
+```
+
+2. **Check Status Object**
+```typescript
+// Ensure status is properly structured
+console.log('Status:', loader.status.value)
+// Should have: isLoading, isSuccess, isError
+```
+
+---
+
+### Component Issues
+
+#### Issue: Component not found
+
+**Symptoms:**
+- "Component not found" error
+- Component doesn't render
+- Import errors
+
+**Solutions:**
+
+1. **Check Component Location**
+```
+app/components/
+├── MyComponent.vue  ✅ Auto-imported
+├── Button/
+│   └── Custom.vue   ✅ Auto-imported as ButtonCustom
+└── nested/
+    └── Deep.vue     ✅ Auto-imported as NestedDeep
+```
+
+2. **Verify Component Name**
+```vue
+<!-- Correct -->
+<MyComponent />
+<ButtonCustom />
+<NestedDeep />
+
+<!-- Incorrect -->
+<my-component />  ❌
+<Custom />        ❌
+```
+
+3. **Restart Dev Server**
+```bash
+# Sometimes auto-import needs refresh
+pnpm dev
+```
+
+4. **Check nuxt.config.ts**
+```typescript
+export default defineNuxtConfig({
+  components: true  // Should be enabled
+})
+```
+
+---
+
+#### Issue: Props not working
+
+**Symptoms:**
+- Props are undefined
+- Type errors
+- Default values not applied
+
+**Solutions:**
+
+1. **Check Prop Definition**
+```vue
+<script setup lang="ts">
+// ✅ Correct
+interface Props {
+  title: string
+  count?: number
+}
+
+const props = defineProps<Props>()
+
+// ✅ With defaults
+const props = withDefaults(defineProps<Props>(), {
+  count: 0
+})
+
+// ❌ Incorrect
+const props = defineProps(['title', 'count'])  // No types
+</script>
+```
+
+2. **Check Prop Passing**
+```vue
+<!-- ✅ Correct -->
+<MyComponent :title="myTitle" :count="42" />
+
+<!-- ❌ Incorrect -->
+<MyComponent title="myTitle" count="42" />  <!-- Strings, not reactive -->
+```
+
+---
+
+### Routing Issues
+
+#### Issue: Route not found or 404
+
+**Symptoms:**
+- Page shows 404
+- Navigation doesn't work
+- Route constants undefined
+
+**Solutions:**
+
+1. **Check File Structure**
+```
+pages/
+├── index.vue           → /
+├── about.vue           → /about
+├── projects/
+│   ├── index.vue       → /projects
+│   ├── [id].vue        → /projects/:id
+│   └── new.vue         → /projects/new
+```
+
+2. **Verify Route Constant**
+```typescript
+// Check if route exists
+console.log('Routes:', routes)
+console.log('PMO Route:', routes.pmo.project.projects.to)
+
+// Use correct path
+navigateTo(routes.pmo.project.projects.to)  // ✅
+navigateTo('/pmo/projects')                  // ✅
+navigateTo(routes.pmo.projects.to)           // ❌ Wrong path
+```
+
+3. **Check Middleware**
+```typescript
+// Middleware might be blocking
+definePageMeta({
+  middleware: ['auth']  // Remove temporarily to test
+})
+```
+
+---
+
+### Build Issues
+
+#### Issue: Build fails with type errors
+
+**Symptoms:**
+- `pnpm build` fails
+- TypeScript errors
+- Module not found errors
+
+**Solutions:**
+
+1. **Check TypeScript Config**
+```bash
+# Regenerate types
+pnpm dev:prepare
+```
+
+2. **Clear Cache**
+```bash
+# Remove generated files
+rm -rf .nuxt node_modules/.cache
+
+# Reinstall
+pnpm install
+
+# Rebuild
+pnpm build
+```
+
+3. **Check Imports**
+```typescript
+// ✅ Correct - auto-imported
+const auth = useAuth()
+
+// ❌ Incorrect - manual import
+import { useAuth } from '~/composables/useAuth'
+```
+
+---
+
+### Styling Issues
+
+#### Issue: Tailwind classes not working
+
+**Symptoms:**
+- Classes have no effect
+- Styles not applied
+- Custom colors not working
+
+**Solutions:**
+
+1. **Check CSS Import**
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  css: ['~/assets/css/main.css']
+})
+```
+
+```css
+/* assets/css/main.css */
+@import "tailwindcss";
+@import "@nuxt/ui";
+```
+
+2. **Check Class Names**
+```vue
+<!-- ✅ Correct -->
+<div class="flex items-center gap-4">
+
+<!-- ❌ Incorrect -->
+<div class="flex items-center gap-4px">  <!-- Invalid unit -->
+```
+
+3. **Purge Configuration**
+```typescript
+// If using custom Tailwind config
+export default {
+  content: [
+    './components/**/*.{vue,js,ts}',
+    './layouts/**/*.vue',
+    './pages/**/*.vue',
+    './app.vue'
+  ]
+}
+```
+
+---
+
+### Performance Issues
+
+#### Issue: Slow page load or navigation
+
+**Symptoms:**
+- Pages take long to load
+- Navigation is sluggish
+- High memory usage
+
+**Solutions:**
+
+1. **Check Data Fetching**
+```typescript
+// ❌ Bad - Multiple sequential requests
+await loader1.run()
+await loader2.run()
+await loader3.run()
+
+// ✅ Good - Parallel requests
+await Promise.all([
+  loader1.run(),
+  loader2.run(),
+  loader3.run()
+])
+```
+
+2. **Implement Lazy Loading**
+```typescript
+// Lazy load heavy components
+const HeavyChart = defineAsyncComponent(() =>
+  import('~/components/HeavyChart.vue')
+)
+```
+
+3. **Check Cache Settings**
+```typescript
+// Increase cache time if appropriate
+const me = defineStore('auth.me', () => {
+  const isShouldFetch = () => {
+    // Cache for 5 minutes instead of 1
+    return Date.now() - timestamp.value > 1000 * 60 * 5
+  }
+})
+```
+
+4. **Use Pagination**
+```typescript
+// Don't load all data at once
+const loader = useListLoader({
+  method: 'GET',
+  url: '/api/data',
+  getRequestOptions: useRequestOptions().auth
+})
+
+loader.run({
+  params: {
+    page: 1,
+    per_page: 20  // Limit results
+  }
+})
+```
+
+---
+
+## 🐛 Debugging Tools
+
+### 1. Vue DevTools
+
+```bash
+# Install browser extension
+# Chrome: https://chrome.google.com/webstore/detail/vuejs-devtools
+# Firefox: https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/
+```
+
+**Features:**
+- Inspect component tree
+- View component props and state
+- Track events
+- Inspect Pinia stores
+
+### 2. Nuxt DevTools
+
+```typescript
+// Enable in nuxt.config.ts
+export default defineNuxtConfig({
+  devtools: {
+    enabled: true
+  }
+})
+```
+
+**Features:**
+- Component inspector
+- Route analyzer
+- Module inspector
+- Performance metrics
+
+### 3. Console Debugging
+
+```typescript
+// Add strategic console logs
+console.log('🔍 Debug:', {
+  user: auth.me.value,
+  token: auth.token.value,
+  permissions: auth.me.value?.access_level
+})
+
+// Use console.table for arrays
+console.table(projects.data.value)
+
+// Use console.group for organization
+console.group('Data Loading')
+console.log('Status:', loader.status.value)
+console.log('Data:', loader.data.value)
+console.groupEnd()
+```
+
+### 4. Network Debugging
+
+```typescript
+// Log all requests
+const loader = useObjectLoader({
+  method: 'GET',
+  url: '/api/data',
+  getRequestOptions: () => {
+    const options = useRequestOptions().auth()
+    console.log('Request:', options)
+    return options
+  }
+})
+```
+
+---
+
+## 📞 Getting Help
+
+### Before Asking for Help
+
+1. ✅ Check this troubleshooting guide
+2. ✅ Review error messages carefully
+3. ✅ Check browser console for errors
+4. ✅ Verify network requests in DevTools
+5. ✅ Try clearing cache and rebuilding
+6. ✅ Check if issue exists in fresh install
+
+### When Reporting Issues
+
+Include:
+- Error message (full stack trace)
+- Code snippet (minimal reproduction)
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment (Node version, OS, browser)
+- Screenshots if applicable
+
+---
+
+## 🔍 Common Error Messages
+
+### "Cannot read property 'value' of undefined"
+
+**Cause:** Accessing reactive ref before initialization
+
+**Solution:**
+```typescript
+// ❌ Bad
+const data = loader.data.value.items  // loader might be undefined
+
+// ✅ Good
+const data = computed(() => loader.data.value?.items || [])
+```
+
+### "Module not found"
+
+**Cause:** Import path incorrect or module not installed
+
+**Solution:**
+```bash
+# Check if module is installed
+pnpm list @finema/finework-layer
+
+# Reinstall if needed
+pnpm install
+```
+
+### "Hydration mismatch"
+
+**Cause:** Server and client render different content
+
+**Solution:**
+```vue
+<!-- Use ClientOnly for client-specific content -->
+<ClientOnly>
+  <div>{{ new Date().toLocaleString() }}</div>
+</ClientOnly>
+```
+
+---
+
+**Last Updated:** 2025-11-07  
+**Need more help? Check the other documentation files!**
+

package/app/components/Button/Back.vue

@@ -1,6 +1,6 @@
 <template>
   <Button
-    icon="icon-park-outline:left"
+    icon="ph:caret-left"
     variant="outline"
     color="neutral"
     :to="to"

package/app/components/Layout/Admin/Sidebar.vue

@@ -230,10 +230,17 @@ const mappedItems = (items: NavigationMenuItem[]): NavigationMenuItem[] => {
       (p) => normalizePath(route.path) === normalizePath(p),
     )
 
+    const basePath = item.to ? normalizePath(String(item.to)) : ''
+    const currentPath = normalizePath(route.path)
     const selfIsActive = item.to
-      ? normalizePath(route.path) === normalizePath(String(item.to))
-      || (route.path.startsWith(normalizePath(String(item.to)))
-        && !hasExactMatch)
+      ? (
+        currentPath === basePath
+        || (
+          currentPath.startsWith(`${basePath}/`)
+          && !currentPath.slice(basePath.length + 1).includes('/')
+          && !hasExactMatch
+        )
+      )
       : false
 
     const itemIsActive = selfIsActive || isAnyChildActive

package/app/components/Layout/Admin/index.vue

@@ -173,6 +173,7 @@ const props = withDefaults(
     sidebarItems: NavigationMenuItem[]
     isSidebarGroup?: boolean
     fullScreen?: boolean
+    rootAppPath?: string
   }>(),
   {
     fullScreen: true,
@@ -207,18 +208,13 @@ const breadcrumbsItems = computed(() => {
   const list = app.pageMeta.breadcrumbs || []
   if (!list.length) return []
 
-  const [first, ...rest] = list
-  const home = {
-    label: '',
-    icon: 'ph:house-line',
-    to: first?.to,
-  }
-
-  const extra = rest.map((item: any) => ({
-    ...item,
-    icon: '',
-  }))
-
-  return [home, ...extra]
+  return [
+    {
+      label: '',
+      icon: 'ph:house-line',
+      to: props.rootAppPath || '/',
+    },
+    ...list,
+  ]
 })
 </script>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@finema/finework-layer",
   "type": "module",
-  "version": "0.2.50",
+  "version": "0.2.52",
   "main": "./nuxt.config.ts",
   "scripts": {
     "dev": "nuxi dev .playground -o",