npm package: @gzl10/nexus-ui
Description: Vue 3 Admin Panel Framework para nexus-backend
Author: Gonzalo Díez
Latest version: 0.21.0

# @gzl10/nexus-ui

[![pipeline status](https://gitlab.gzl10.com/oss/nexus/badges/main/pipeline.svg)](https://gitlab.gzl10.com/oss/nexus/-/pipelines)
[![npm version](https://img.shields.io/npm/v/@gzl10/nexus-ui.svg)](https://www.npmjs.com/package/@gzl10/nexus-ui)
[![npm downloads](https://img.shields.io/npm/dm/@gzl10/nexus-ui.svg)](https://www.npmjs.com/package/@gzl10/nexus-ui)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Vue 3](https://img.shields.io/badge/Vue-3.5-4FC08D.svg)](https://vuejs.org/)

> **Warning**: This project is currently in testing/experimental phase. Use at your own risk.

Vue 3 Admin Panel Framework for nexus-backend. Pre-built components and stores for authentication, users, modules, and storage management.

**Repository**: [https://gitlab.gzl10.com/oss/nexus](https://gitlab.gzl10.com/oss/nexus)

## Installation

```bash
pnpm add @gzl10/nexus-ui
```

> Note: `@gzl10/nexus-client` and `@gzl10/nexus-sdk` are bundled dependencies.

## Usage

```typescript
// main.ts
import { bootstrap } from '@gzl10/nexus-ui'
import '@gzl10/nexus-ui/style.css'

const app = await bootstrap({
  apiUrl: '/api/v1',
  base: '/'
})
app.mount('#app')
```

### Custom Routes

```typescript
const app = await bootstrap({
  apiUrl: '/api/v1',
  routes: [
    { path: '/custom', component: () => import('./pages/CustomPage.vue') }
  ]
})
app.mount('#app')
```

## Features

| Feature | Description |
| ------- | ----------- |
| Authentication | Login, logout, token refresh, session management |
| OTP Challenge | Email verification after failed login attempts |
| Password Reset | Email-based password recovery with OTP |
| Users Management | CRUD users, roles, permissions |
| Modules Explorer | Dynamic module introspection and browsing |
| Storage Browser | File upload, download, preview |
| Theme System | Light/dark mode with Naive UI |
| Internationalization | Built-in i18n support (en, es) |
| Real-time | WebSocket integration with socket.io-client |
| GDPR Compliance | Consent pages, legal content management |

## Exported Components

### Display Components

| Component | Description |
| --------- | ----------- |
| `DynamicForm` | Auto-generated form from field definitions |
| `TableDisplay` | Data table display with sorting/filtering |
| `ListDisplay` | List display |
| `MasonryDisplay` | Masonry grid display |
| `DescriptionsDisplay` | Key-value descriptions |
| `ActionDisplay` | Action buttons display |

### Card Components

| Component | Description |
| --------- | ----------- |
| `ModuleCard` | Module display card |
| `EntityCard` | Entity display card |
| `PluginCard` | Plugin display card |

### Common Components

| Component | Description |
| --------- | ----------- |
| `AppShell` | Root app shell with sidebar/header |
| `AppHeader` | Header with logo, theme toggle, user menu |
| `AppSidebar` | Collapsible sidebar navigation |
| `AppFooter` | Footer with links |
| `CookieConsent` | GDPR cookie consent banner |
| `AuthCardHeader` | Auth page card header with logo |
| `LegalPageLayout` | Layout for legal pages (terms, privacy) |

### Input Components (Dual-Mode)

All input components support two presentation modes:

- `mode="control"` - Editable input for forms (default)
- `mode="display"` - Read-only rendering for tables/lists

| Component | Type | Description |
| --------- | ---- | ----------- |
| `TextInput` | text/email/password | Text input with password toggle |
| `NumberInput` | number | Numeric input |
| `TextareaInput` | textarea | Multi-line text |
| `MarkdownInput` | markdown | Markdown editor (MdEditor) |
| `SelectInput` | select | Single select dropdown |
| `MultiselectInput` | multiselect | Multiple select dropdown |
| `CheckboxInput` | checkbox | Boolean toggle (icon in display) |
| `DateInput` | date | Date picker |
| `DatetimeInput` | datetime | Date and time picker |
| `TagsInput` | tags | Dynamic tags input |
| `IconInput` | icon | Icon picker with preview |
| `FileInput` | file/fileArray | File upload |
| `ImageInput` | image/imageArray | Image upload with thumbnails |

## Exported Layouts

| Layout | Description |
| ------ | ----------- |
| `AdminLayout` | Main admin layout with sidebar and header |
| `AuthLayout` | Layout for auth pages (login, register) |
| `PublicLayout` | Layout for public pages (landing, legal) |
| `SettingsLayout` | Layout for settings/profile pages |
| `ErrorLayout` | Layout for error pages (403, 404) |

## Exported Pages

### Auth Pages

| Page | Description |
| ---- | ----------- |
| `LoginPage` | Login form with OTP challenge support |
| `RegisterPage` | User registration with OTP verification |
| `ForgotPasswordPage` | Password reset flow (email → OTP → new password) |
| `ChangePasswordPage` | Password change form |

### Legal Pages

| Page | Description |
| ---- | ----------- |
| `ConsentPage` | GDPR consent collection |
| `TermsOfServicePage` | Terms of service display |
| `PrivacyPolicyPage` | Privacy policy display |
| `CookiePolicyPage` | Cookie policy display |

### System Pages

| Page | Description |
| ---- | ----------- |
| `LandingPage` | Public landing page |
| `DashboardPage` | Admin dashboard |
| `ForbiddenPage` | 403 Forbidden page |
| `SystemPage` | System modules overview |
| `ModulePage` | Module CRUD management |
| `EntityEditPage` | Entity create/edit page |

## Exported Stores (Pinia)

| Store | Description |
| ----- | ----------- |
| `useAuthStore` | Authentication state, login/logout, abilities |
| `useNotificationsStore` | Notifications state and actions |
| `useSocketStore` | WebSocket connection, auto-connects with auth |

## Exported Composables

| Composable | Description |
| ---------- | ----------- |
| `useTheme` | Theme toggle (dark/light), currentLogo |
| `useFormData` | Form data initialization by field type |
| `buildFieldRules` | Form validation rules builder |
| `isFileType`, `isArrayFileType` | File type detection helpers |
| `useSelectOptions` | Load select options from API/static |
| `useLocalized` | Resolve LocalizedString values |
| `useLocalizedInput` | Multi-language input editing (TextInput, MarkdownInput) |
| `useApiError` | Parse API errors to user messages |
| `useDisplayFormat` | Format values for display components |
| `useLegalContent` | Load legal content from compliance API |
| `useSidebar` | Sidebar collapsed state, modules loading |
| `useModuleData` | Module entity data, sorting, filtering, CRUD |
| `useOtpFlow` | OTP challenge state and handlers |

## Exported Configuration

| Export | Description |
| ------ | ----------- |
| `colors`, `brand`, `neutrals` | Color palette |
| `lightThemeOverrides`, `darkThemeOverrides` | Naive UI theme overrides |
| `entityTypeConfigs`, `getEntityTypeConfig` | Entity type icons/colors |
| `moduleTypeConfigs`, `getModuleTypeConfig` | Module type icons/colors |
| `displayComponents`, `getDisplayComponent` | Display mode to component mapping |

## Exported Utilities

| Export | Description |
| ------ | ----------- |
| `formatBytes`, `formatDuration` | Formatting helpers |
| `getSingularLabel` | Pluralization helper |
| `isFieldVisible`, `filterSubmitData` | Form field visibility |
| `getEntityRoutePrefix`, `getEntityKey` | Module routing helpers |
| `createConfirmPasswordRule` | Password confirmation validation |
| `handleOtpChallenge` | OTP error detection |

## Re-exported from @gzl10/nexus-client

| Export | Description |
| ------ | ----------- |
| `configureClient` | Configure singleton client |
| `getClient` | Get configured client instance |
| `resetClient` | Reset client (logout/testing) |
| `createNexusClient` | Factory for multiple instances |
| `createAbility` | CASL ability factory |
| `getDeviceId`, `getDeviceName` | Device fingerprinting |
| `LoginOptions`, `RegisterInput` | Auth input types |
| `RoleWithPermissions`, `RolePermission` | Role types |
| `NexusSocket`, `NexusSocketEvents` | Socket.IO types |

## Re-exported from @gzl10/nexus-sdk

| Export | Description |
| ------ | ----------- |
| `ModuleDTO`, `EntityDefinitionDTO` | Module/entity types |
| `FieldDefinitionDTO` | Field definition type |
| `EntityType`, `Category` | Enum types |
| `LocalizedString`, `PaginatedResult` | Common types |
| `resolveLocalized`, `getCountLabel` | Localization helpers |
| `CATEGORIES`, `CATEGORY_ORDER` | Category constants |

## Re-exported Types

| Type | Description |
| ---- | ----------- |
| `User`, `Role` | User/role aliases (from client) |
| `UserWithRoles` | User with roles included |
| `ApiResponse` | Generic API response wrapper |

## Internationalization (i18n)

Built-in support for English and Spanish. Uses `vue-i18n` with auto-detection:

```typescript
import { useI18n } from 'vue-i18n'

const { t, locale } = useI18n()

// Use translations
t('auth.login')        // "Sign In" / "Iniciar Sesión"
t('auth.otpSent')      // "Verification code sent to your email"
t('validation.emailRequired')

// Switch language
locale.value = 'es'
```

Available namespaces: `auth`, `validation`, `common`, `errors`, `modules`, `consent`, `legal`.

## Configuration Options (BootstrapOptions)

| Option | Description | Default |
| ------ | ----------- | ------- |
| `apiUrl` | Backend API URL | `/api/v1` |
| `base` | Router base path (must match Vite base) | `/` |
| `loginPath` | Login redirect path | `/login` |
| `routes` | Additional user routes | `[]` |
| `stores` | Additional Pinia stores | `[]` |
| `components` | Global components to register | `{}` |
| `el` | Root element selector | `#app` |
| `onMounted` | Callback after mounting | - |
| `disableBaseRoutes` | Disable built-in routes | `false` |

## Peer Dependencies

```json
{
  "vue": "^3.5.0",
  "vue-router": "^4.6.0",
  "pinia": "^3.0.0",
  "naive-ui": "^2.43.0",
  "@iconify/vue": "^5.0.0",
  "vue-i18n": "^11.0.0"
}
```

## Development

```bash
pnpm dev           # Start dev server
pnpm build         # Build app + library
pnpm build:lib     # Build library only
pnpm typecheck     # Type check
pnpm lint          # Linting
pnpm test          # Run tests
```

## Stack

- **Vue 3** - Composition API + `<script setup>`
- **Naive UI** - Component library
- **Pinia** - State management
- **Vue Router** - Routing
- **Iconify** - Icons
- **Vite** - Build tool
- **Vitest** - Testing

## Support

<a href="https://www.buymeacoffee.com/gzl10g" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>

## License

MIT