npm package: @finema/finework-layer
Description: A comprehensive Nuxt Layer providing reusable components, composables, layouts, and utilities for Finework applications.
Latest version: 1.0.39

# @finema/finework-layer

A comprehensive Nuxt Layer providing reusable components, composables, layouts, and utilities for Finework applications.

[![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)

## 📚 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 add @finema/finework-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,
    },
  },
});
```

### 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>
```

## 🏗️ Project Structure

```
@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
```

## 🎨 Key Components

### StatusBox

Handles loading, error, and empty states automatically.

```vue
<StatusBox :status="loader.status.value" :data="loader.data.value">
  <template #default="{ data }">
    <!-- Your content -->
  </template>
</StatusBox>
```

### InfoItemList

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' },
  ]"
/>
```

### Layouts

Pre-built layouts for admin and user interfaces.

```vue
<LayoutAdmin label="Admin Panel" :items="navigationItems">
  <!-- Your content -->
</LayoutAdmin>
```

## 🔐 Authentication

Built-in authentication system with permission management.

```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
}
```

## 🛠️ Development

### 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
```

### 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
# Start playground
pnpm dev
```

## 📝 Publishing

```bash
# Update version and create changelog
pnpm release

# Or manually
npm publish --access public
```

## 🤝 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