@finema/finework-layer 0.2.50 → 0.2.51

package/README.md

@@ -1,73 +1,239 @@
-# Nuxt Layer Starter
+# @finema/finework-layer
 
-Create Nuxt extendable layer with this GitHub template.
+A comprehensive Nuxt Layer providing reusable components, composables, layouts, and utilities for Finework applications.
 
-## Setup
+[![Version](https://img.shields.io/npm/v/@finema/finework-layer.svg)](https://www.npmjs.com/package/@finema/finework-layer)
+[![License](https://img.shields.io/npm/l/@finema/finework-layer.svg)](https://www.npmjs.com/package/@finema/finework-layer)
 
-Make sure to install the dependencies:
+## 📚 Documentation
+
+### For Developers
+
+- **[Quick Start Guide](./QUICK_START.md)** - Get started in 5 minutes
+- **[Component Examples](./COMPONENT_EXAMPLES.md)** - Real-world usage examples
+- **[API Reference](./API_REFERENCE.md)** - Complete API documentation
+- **[Architecture](./ARCHITECTURE.md)** - System design and patterns
+- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions
+
+### For LLM/AI Assistants
+
+- **[LLM Guide](./LLM_GUIDE.md)** - Comprehensive guide for AI code generation
+
+## 🚀 Features
+
+- ✅ **Authentication System** - Complete auth flow with permissions
+- ✅ **Layout Components** - Admin and User layouts
+- ✅ **Data Loading** - Smart loading states with StatusBox
+- ✅ **Form Handling** - Validation with Valibot
+- ✅ **Type Safety** - Full TypeScript support
+- ✅ **Auto-imports** - Components, composables, and constants
+- ✅ **Middleware** - Auth, permissions, and route guards
+- ✅ **UI Components** - Built on @nuxt/ui
+
+## 📦 Installation
 
 ```bash
-pnpm install
+pnpm add @finema/finework-layer
 ```
 
-## Working on your layer
+## 🎯 Quick Start
+
+### 1. Extend the Layer
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ["@finema/finework-layer"],
+
+  runtimeConfig: {
+    public: {
+      baseAPI: process.env.NUXT_PUBLIC_BASE_API,
+    },
+  },
+});
+```
 
-Your layer is at the root of this repository, it is exactly like a regular Nuxt project, except you can publish it on NPM.
+### 2. Create Your First Page
+
+```vue
+<template>
+  <LayoutAdmin label="Dashboard" :items="navItems">
+    <StatusBox :status="data.status.value" :data="data.data.value">
+      <template #default="{ data }">
+        <Card>
+          <h1>Welcome, {{ data.name }}!</h1>
+        </Card>
+      </template>
+    </StatusBox>
+  </LayoutAdmin>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  middleware: ["auth"],
+});
+
+const data = useObjectLoader({
+  method: "GET",
+  url: "/api/dashboard",
+  getRequestOptions: useRequestOptions().auth,
+});
+
+onMounted(() => data.run());
+
+const navItems = [
+  { label: "Dashboard", to: "/dashboard", icon: "i-heroicons-home" },
+];
+</script>
+```
 
-The `.playground` directory should help you on trying your layer during development.
+## 🏗️ Project Structure
 
-Running `pnpm dev` will prepare and boot `.playground` directory, which imports your layer itself.
+```
+@finema/finework-layer/
+├── app/
+│   ├── components/          # Reusable components
+│   │   ├── Button/         # Button variants
+│   │   ├── Layout/         # Layout components
+│   │   ├── InfoItemList.vue
+│   │   └── StatusBox.vue
+│   ├── composables/        # Vue composables
+│   │   ├── useAuth.ts
+│   │   └── useRequestOptions.ts
+│   ├── constants/          # App constants
+│   │   └── routes.ts
+│   ├── middleware/         # Route middleware
+│   │   ├── auth.ts
+│   │   ├── permissions.ts
+│   │   └── guest.ts
+│   └── app.config.ts       # App configuration
+├── .playground/            # Development playground
+└── docs/                   # Documentation
+```
 
-## Distributing your layer
+## 🎨 Key Components
 
-Your Nuxt layer is shaped exactly the same as any other Nuxt project, except you can publish it on NPM.
+### StatusBox
 
-To do so, you only have to check if `files` in `package.json` are valid, then run:
+Handles loading, error, and empty states automatically.
 
-```bash
-npm publish --access public
+```vue
+<StatusBox :status="loader.status.value" :data="loader.data.value">
+  <template #default="{ data }">
+    <!-- Your content -->
+  </template>
+</StatusBox>
 ```
 
-Once done, your users will only have to run:
+### InfoItemList
 
-```bash
-npm install --save your-layer
+Display key-value information in a clean layout.
+
+```vue
+<InfoItemList
+  :items="[
+    { label: 'Name', value: user.name },
+    { label: 'Email', value: user.email },
+    { label: 'Active', value: user.is_active, type: 'boolean' },
+  ]"
+/>
 ```
 
-Then add the dependency to their `extends` in `nuxt.config`:
+### Layouts
+
+Pre-built layouts for admin and user interfaces.
 
-```ts
-defineNuxtConfig({
-  extends: 'your-layer'
-})
+```vue
+<LayoutAdmin label="Admin Panel" :items="navigationItems">
+  <!-- Your content -->
+</LayoutAdmin>
 ```
 
-## Development Server
+## 🔐 Authentication
 
-Start the development server on http://localhost:3000
+Built-in authentication system with permission management.
 
-```bash
-pnpm dev
+```typescript
+const auth = useAuth();
+
+// Check authentication
+if (auth.isAuthenticated.value) {
+  console.log("User:", auth.me.value);
+}
+
+// Check permissions
+if (auth.hasPermission(UserModule.PMO, Permission.ADMIN)) {
+  // User has PMO admin access
+}
 ```
 
-## Production
+## 🛠️ Development
 
-Build the application for production:
+### Setup
 
 ```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Build for production
 pnpm build
+
+# Run linter
+pnpm lint
+
+# Fix linting issues
+pnpm lint:fix
 ```
 
-Or statically generate it with:
+### Working on the Layer
+
+The `.playground` directory is used for development and testing. It imports the layer itself, allowing you to test changes in real-time.
 
 ```bash
-pnpm generate
+# Start playground
+pnpm dev
 ```
 
-Locally preview production build:
+## 📝 Publishing
 
 ```bash
-pnpm preview
+# Update version and create changelog
+pnpm release
+
+# Or manually
+npm publish --access public
 ```
 
-Checkout the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+## 🤝 Contributing
+
+1. Create a feature branch
+2. Make your changes
+3. Run tests and linting
+4. Submit a pull request
+
+## 📄 License
+
+MIT License - see LICENSE file for details
+
+## 🔗 Links
+
+- [Nuxt Documentation](https://nuxt.com)
+- [Nuxt UI Documentation](https://ui.nuxt.com)
+- [@finema/core](https://www.npmjs.com/package/@finema/core)
+
+## 📞 Support
+
+For issues and questions:
+
+1. Check the [Troubleshooting Guide](./TROUBLESHOOTING.md)
+2. Review [Component Examples](./COMPONENT_EXAMPLES.md)
+3. Consult the [API Reference](./API_REFERENCE.md)
+
+---
+
+**Version:** 0.2.50
+**Last Updated:** 2025-11-07
+**Maintained by:** Finema Team