@conduction/nextcloud-vue
Shared Vue 2 component library for Conduction Nextcloud apps — higher-level UI, OpenRegister integration, and NL Design System support
---
`@conduction/nextcloud-vue` is an npm component library that sits on top of `@nextcloud/vue` and provides higher-level, opinionated components for building Nextcloud apps. It handles the repetitive patterns — schema-driven tables, CRUD dialogs, paginated lists, faceted search — so each app only writes the domain-specific parts.
Used internally by [Pipelinq](https://github.com/ConductionNL/pipelinq), [Dossiq](https://github.com/ConductionNL/dossiq), [Larpinq](https://github.com/ConductionNL/larpinq), and other Conduction Nextcloud apps.
> **Requires:** Vue 2.7, Pinia 2, @nextcloud/vue 8
## Features
### Layout & Page Components
| Component | Description |
|-----------|-------------|
| `CnIndexPage` | Zero-config index page with table/card views, built-in CRUD dialogs, pagination, mass actions, and faceted search |
| `CnPageHeader` | Page header with icon, title, and description |
| `CnActionsBar` | Action bar with add button, mass action triggers, view toggle (table/grid), and search |
| `CnIndexSidebar` | Sidebar for index pages |
### Data Display
| Component | Description |
|-----------|-------------|
| `CnDataTable` | Sortable table with multi-select, schema-driven columns, loading states, and empty states |
| `CnCardGrid` | Responsive card grid for object summaries |
| `CnObjectCard` | Single object card with title, metadata, and actions |
| `CnCellRenderer` | Type-aware cell formatter for strings, numbers, dates, objects, arrays, and booleans |
| `CnFacetSidebar` | Faceted filter sidebar with aggregated count buckets |
| `CnPagination` | Full pagination with page numbers, size selector, and "go to page" |
| `CnFilterBar` | Search input with filter controls |
| `CnKpiGrid` | KPI metric cards for statistics dashboards |
### Single-Object Dialogs
| Component | Description |
|-----------|-------------|
| `CnFormDialog` | Schema-driven form dialog for create and edit; auto-generates fields from JSON Schema |
| `CnDeleteDialog` | Delete confirmation with two-phase confirm/result pattern |
| `CnCopyDialog` | Copy dialog with naming pattern selector |
### Mass-Action Dialogs
| Component | Description |
|-----------|-------------|
| `CnMassDeleteDialog` | Bulk delete confirmation |
| `CnMassCopyDialog` | Bulk copy with per-item naming |
| `CnMassExportDialog` | Export selected items (JSON, CSV, …) |
| `CnMassImportDialog` | Bulk import with file upload and format detection |
### Settings & Config
| Component | Description |
|-----------|-------------|
| `CnSettingsCard` | Collapsible settings card with save state |
| `CnSettingsSection` | Container for grouping settings |
| `CnConfigurationCard` | Configuration card with status indicator |
| `CnVersionInfoCard` | Version information display |
| `CnStatsBlock` | Statistics block with count and breakdown |
| `CnRegisterMapping` | Register-to-field mapping configuration |
### State Management
| Export | Description |
|--------|-------------|
| `useObjectStore(id)` | Generic Pinia store for OpenRegister CRUD — pagination, search, caching |
| `createObjectStore(id)` | Factory for custom-scoped object stores |
| `createSubResourcePlugin(name)` | Plugin factory for sub-resource management |
| `auditTrailsPlugin` | Adds audit trail state and getters |
| `relationsPlugin` | Manages object relations/associations |
| `filesPlugin` | Handles file attachments and uploads |
| `lifecyclePlugin` | Tracks lifecycle states (draft, published, archived) |
| `registerMappingPlugin` | Manages register-to-field mappings |
### Composables
| Composable | Description |
|------------|-------------|
| `useListView(options)` | Manages list view state: search debounce, filter state, sort, pagination |
| `useDetailView(options)` | Manages detail view: load, edit, delete, validation |
| `useSubResource(options)` | Manages sub-resource operations |
### Schema Utilities
| Function | Description |
|----------|-------------|
| `columnsFromSchema(schema)` | Auto-generate data table column definitions from JSON Schema |
| `fieldsFromSchema(schema)` | Auto-generate form field definitions from JSON Schema |
| `filtersFromSchema(schema)` | Auto-generate filter definitions from JSON Schema |
| `formatValue(value, format)` | Type-aware cell value formatter |
## Architecture
```mermaid
graph TD
A[Nextcloud App] -->|imports| B[@conduction/nextcloud-vue]
B --> C[Components]
B --> D[useObjectStore]
B --> E[Composables]
B --> F[Schema Utils]
D -->|CRUD| G[OpenRegister REST API]
C -->|styles via| H[Nextcloud CSS Variables]
C -->|NL Design tokens| I[--nldesign-* CSS vars]
```
### Two-Phase Dialog Pattern
All dialogs follow a predictable confirm/result flow that keeps parent components in control of API calls:
```js
// 1. Dialog emits @confirm with user input
// 2. Parent handles API call
// 3. Parent calls dialog.setResult(response) via $ref
// 4. Dialog shows toast and auto-closes
```
### Schema-Driven Components
Pass a JSON Schema and get a fully working table or form with zero configuration:
```vue
```
## Installation
```bash
npm install @conduction/nextcloud-vue
```
Import the CSS alongside your component imports:
```js
import '@conduction/nextcloud-vue/dist/nextcloud-vue.css'
import { CnIndexPage, useObjectStore } from '@conduction/nextcloud-vue'
```
### Markdown sanitization (CnRoadmapItem / CnSuggestFeatureModal)
The Features & Roadmap component family (`CnRoadmapItem`, `CnSuggestFeatureModal`) renders untrusted markdown coming from GitHub issue bodies and user input. Both components pipe the markdown through [`marked`](https://www.npmjs.com/package/marked) and then through [`DOMPurify`](https://www.npmjs.com/package/dompurify) using the exported `SAFE_MARKDOWN_DOMPURIFY_CONFIG` constant — `