Beta to main

.github/workflows/code-quality.yml

@@ -24,6 +24,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Documentation coverage
+        run: npm run check:docs
+
       - name: ESLint
         run: npm run lint
 

.prettierrc

@@ -0,0 +1,38 @@
+{
+  "overrides": [
+    {
+      "files": ["*.json"],
+      "options": {
+        "parser": "json",
+        "printWidth": 120,
+        "tabWidth": 2
+      }
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "options": {
+        "parser": "typescript",
+        "printWidth": 120,
+        "trailingComma": "all",
+        "tabWidth": 2,
+        "singleQuote": false
+      }
+    },
+    {
+      "files": ["*.css", "*.scss"],
+      "options": {
+        "parser": "css",
+        "tabWidth": 2
+      }
+    },
+    {
+      "files": ["conduction.css"],
+      "options": {
+        "parser": "css",
+        "trailingComma": "all",
+        "tabWidth": 2,
+        "printWidth": 150
+      }
+    }
+  ]
+}

.vscode/settings.json

@@ -19,6 +19,9 @@
     "[javascript]": {
         "editor.defaultFormatter": "dbaeumer.vscode-eslint"
     },
+    "[vue]": {
+        "editor.defaultFormatter": "dbaeumer.vscode-eslint"
+    },
     "[css]": {
         "editor.defaultFormatter": "esbenp.prettier-vscode"
     },

CLAUDE.md

@@ -22,10 +22,12 @@ import '@conduction/nextcloud-vue/src/css/index.css'
 
 **Layout & Pages**
 - `CnIndexPage` — Top-level schema-driven index page (table/cards, pagination, mass actions, dialogs)
+- `CnDetailPage` — Generic detail/overview page with stats table and flexible content slots (simpler alternative to CnIndexPage)
 - `CnPageHeader` — Page header with icon, title, description
 - `CnActionsBar` — Action bar with add button, mass actions, view toggle, search
 
 **Data Display**
+- `CnDetailGrid` — Data-driven label-value grid with grid and horizontal layout modes
 - `CnDataTable` — Sortable data table with selection, loading, empty states
 - `CnCardGrid` — Grid of object cards
 - `CnObjectCard` — Single object card
@@ -37,23 +39,35 @@ import '@conduction/nextcloud-vue/src/css/index.css'
 **Single-Object Dialogs** (emit-based, two-phase confirm → result)
 - `CnDeleteDialog` — Single-item delete confirmation
 - `CnCopyDialog` — Single-item copy with naming pattern selector
-- `CnFormDialog` — Schema-driven create/edit form dialog (auto-generates fields, supports slot overrides)
+- `CnFormDialog` — Schema-driven create/edit form dialog (auto-generates fields, supports async select via `enum` function, per-field option slot overrides)
 - `CnAdvancedFormDialog` — Richer create/edit dialog with properties table (click-to-edit), Data (JSON) tab with CodeMirror, optional Metadata tab; optional useObjectStore integration; fixed large size
+- `CnSchemaFormDialog` — Full-featured JSON Schema editor dialog with Properties (sortable table, inline editing), Configuration (composition, field mappings), and Security (RBAC) tabs. Accepts external data as props (availableSchemas, availableRegisters, userGroups, availableTags). Optional action buttons (extend, analyze, validate, delete objects, publish, delete) controlled via boolean props that emit events.
 
 **Mass-Action Dialogs** (emit-based, two-phase confirm → result)
 - `CnMassDeleteDialog` — Bulk delete confirmation
 - `CnMassCopyDialog` — Bulk copy with naming patterns
 - `CnMassExportDialog` — Bulk export with format selection
 - `CnMassImportDialog` — Bulk import with file upload
 
+**Data Viewers**
+- `CnJsonViewer` — Syntax-highlighted code viewer/editor with CodeMirror (supports JSON, XML, HTML, plain text via `language` prop with `'auto'` detection; readOnly mode)
+
 **UI Elements**
 - `CnStatusBadge` — Color-coded status/priority pill badge
+- `CnDetailCard` — Card container with title, icon, collapsible sections
 - `CnRowActions` — Row action buttons (inline + overflow dropdown)
+- `CnContextMenu` — Right-click context menu (wraps NcActions, pair with `useContextMenu` composable)
 - `CnMassActionBar` — Floating bar for mass action triggers
 - `CnIcon` — MDI icon by name
 - `CnKpiGrid` — KPI metric cards grid
+- `CnStatsPanel` — Data-driven statistics panel (sections of stat blocks, list items, and progress bars)
+- `CnProgressBar` — Labeled horizontal progress bars with variant colors for distribution visualizations
 - `CnIndexSidebar` — Index page sidebar
 
+**Object Widgets**
+- `CnObjectDataWidget` — Schema-driven editable data grid widget. Displays object properties in a CSS grid, supports inline editing (click-to-edit with all widget types), dirty tracking, and saves via objectStore. Configurable per-property overrides for order, grid span, visibility, editability, label, and widget type.
+- `CnObjectMetadataWidget` — Read-only metadata display widget. Automatically extracts and formats system metadata from OpenRegister objects (@self block: id, uuid, uri, register, schema, created, updated, owner, etc.). Supports include/exclude filters and extra items.
+
 **Dashboard**
 - `CnDashboardPage` — Top-level dashboard page with GridStack widget grid (the dashboard equivalent of CnIndexPage)
 - `CnDashboardGrid` — Low-level GridStack grid layout engine (drag/drop, resize)
@@ -88,6 +102,7 @@ import '@conduction/nextcloud-vue/src/css/index.css'
 - `useDetailView(options)` — Load, edit, delete state management
 - `useFileSelection(options)` — File upload/drop handling
 - `useDashboardView(options)` — Dashboard state: widget defs, layout, NC widget loading, add/remove/persist
+- `useContextMenu()` — Right-click context menu positioning and state (cursor CSS vars, open/close, action helpers)
 
 ### CnIndexPage Dialog Override System
 
@@ -99,6 +114,7 @@ CnIndexPage has built-in single-object dialogs (Delete, Copy, Form) that are **o
    - `#form-dialog="{ item, schema, close }"` — Replace create/edit dialog (use CnFormDialog or CnAdvancedFormDialog)
 2. **Form content override** — `#form-fields` replaces the form inside the built-in CnFormDialog
 3. **Per-field override** — `#field-{key}` inside CnFormDialog replaces a single field
+4. **Per-field option rendering** — `#field-{key}-option` and `#field-{key}-selected-option` customize dropdown option display for select/multiselect/tags fields
 
 Key events emitted by CnIndexPage:
 - `@create(formData)` — Form dialog create confirmed
@@ -180,17 +196,72 @@ const DEFAULT_LAYOUT = [
 6. Add to `src/index.js` barrel
 7. Write test in `tests/components/`
 8. Use Nextcloud CSS variables only (no `--nldesign-*` references)
+9. **Write a docs page** at `docs/components/cn-my-component.md` — see the next section. The `check:docs` script fails CI when any public export is undocumented.
+
+## Documentation Coverage (enforced)
+
+Every identifier re-exported from `src/index.js` must have corresponding documentation. This is enforced by [scripts/check-docs.js](scripts/check-docs.js), wired up as:
+
+```bash
+npm run check:docs
+```
+
+The script parses `src/index.js`, classifies each named export, and verifies that a matching doc file (or symbol mention) exists under `docs/`. It exits non-zero with a per-category breakdown when anything is missing. Run it before committing any change that adds, renames, or removes a public export.
+
+### Export → doc location mapping
+
+| Category | Match rule | Expected doc |
+|----------|-----------|--------------|
+| Components | `Cn*` PascalCase | `docs/components/<kebab>.md` |
+| Composables | `use*` (not in the store factory list) | `docs/utilities/composables/<kebab>.md` |
+| Store factories | `useObjectStore`, `createObjectStore`, `createCrudStore`, `createSubResourcePlugin` | `docs/store/<stem>.md` — stem strips the leading `use`/`create` verb (→ `object-store.md`, `crud-store.md`, `sub-resource-plugin.md`) |
+| Store plugins | `*Plugin` suffix | `docs/store/plugins/<kebab>.md` (e.g. `auditTrailsPlugin` → `audit-trails.md`) |
+| Store constants | See `STORE_MENTION_ONLY` | Mention-by-name inside an existing `docs/store/*.md` — no standalone file required |
+| Utilities | Any other export | `docs/utilities/<kebab>.md` |
+
+`<kebab>` is the camelCase/PascalCase export name converted to kebab-case by the script's `toKebab()` helper.
+
+### Configuring the script
+
+Three constants at the top of [scripts/check-docs.js](scripts/check-docs.js) control the edge cases — each has an inline JSDoc block explaining its purpose in detail:
+
+- **`EXEMPT`** — Set of export names that don't need a dedicated doc page. Reserved for lifecycle/bootstrap helpers covered by another doc (currently only `registerIcons`, documented as part of the install flow). Exempt exports are skipped entirely and don't count toward any category's totals.
+
+- **`STORE_FACTORY_STEMS`** — Map of store factory/helper identifiers to their doc filename stem under `docs/store/`. Used to override the default kebab-case rule so the docs read as `object-store.md` / `crud-store.md` instead of `use-object-store.md` / `create-crud-store.md`. Multiple identifiers may map to the same stem (e.g. `useObjectStore` and `createObjectStore` both point at `docs/store/object-store.md`).
+
+- **`STORE_MENTION_ONLY`** — Map of export names to the `.md` file (relative to `docs/store/`) that's required to mention them by name. Used for constants and small helpers that belong with a larger API and don't warrant their own page (e.g. `SEARCH_TYPE` is checked inside `docs/store/plugins/search.md`). Coverage passes when the file exists and contains the symbol name as a substring.
+
+When adding a new public export that doesn't fit the default rules:
+
+- If it's one of a small set of helpers for an existing page → add it to `STORE_MENTION_ONLY` and ensure the target doc references it by name.
+- If the default kebab-case → filename mapping produces an awkward stem → add an entry to `STORE_FACTORY_STEMS` (store-related) or extend `classify()` with a new category for other surfaces.
+- If it's truly a non-API export (build-time helper, registration hook) → add it to `EXEMPT`. Use this sparingly.
+
+### Running the check
+
+```bash
+# From nextcloud-vue/
+npm run check:docs      # exits 0 when every export is covered, 1 otherwise
+```
+
+Output is a per-category coverage summary followed by a list of missing exports with the exact file path the script expects, so the fix is always to either create that file or rename an existing one.
 
 ## Project Structure
 
 ```
 src/
-  index.js              # Main barrel export
+  index.js              # Main barrel export — source of truth for public API
   components/           # Vue SFC components (CnPrefixed)
   store/                # Pinia stores
   composables/          # Vue composables
   css/                  # Global CSS modules
   utils/                # Utility functions
+docs/
+  components/           # One .md per component (cn-<kebab>.md)
+  store/                # Store factories + plugins/ subdir
+  utilities/            # Utility functions + composables/ subdir
+scripts/
+  check-docs.js         # Enforces docs coverage for every src/index.js export
 ```
 
 ## Consumer Apps

docs/architecture/customization.md

@@ -44,6 +44,8 @@ CnIndexPage
     ├── slot: #before-fields        ← prepend content to auto-generated fields
     ├── slot: #after-fields         ← append content to auto-generated fields
     ├── slot: #field-{key}          ← replace one specific field
+    ├── slot: #field-{key}-option   ← custom dropdown option rendering for a select field
+    ├── slot: #field-{key}-selected-option ← custom selected display for a select field
     └── slot: #import-fields        ← add extra fields to the import dialog
 ```
 
@@ -97,6 +99,7 @@ CnIndexPage
 | `show-mass-copy` | Boolean | `true` | Show the built-in Copy (mass) button |
 | `show-mass-delete` | Boolean | `true` | Show the built-in Delete (mass) button |
 | `mass-action-name-field` | String | `'title'` | Property used to display item names inside mass-action dialogs |
+| `name-formatter` | Function | `null` | Optional `(item) => string` to format item names in dialogs. Overrides `mass-action-name-field` when provided. |
 | `export-formats` | Array | `[{ id:'excel', label:'Excel (.xlsx)' }, ...]` | Available formats in the export dialog |
 | `import-options` | Array | `[]` | Option checkboxes shown in the import dialog |
 
@@ -482,6 +485,30 @@ The slot scope for `#field-{key}` provides:
 - `error` — current validation error string (empty when valid)
 - `updateField(key, value)` — call this to update the form data
 
+### Custom option rendering for select fields
+
+For select, multiselect, and tags fields, you can customize how dropdown options and selected values are displayed without replacing the entire field. Use `#field-{key}-option` and `#field-{key}-selected-option`:
+
+```vue
+<CnIndexPage title="Clients" :schema="schema" :objects="objects" @create="onCreate">
+  <!-- Custom rendering for the 'category' select dropdown options -->
+  <template #field-category-option="{ label, description, count }">
+    <div class="category-option">
+      <strong>{{ label }}</strong>
+      <span v-if="count" class="count">({{ count }})</span>
+      <p v-if="description">{{ description }}</p>
+    </div>
+  </template>
+
+  <!-- Simpler display when selected -->
+  <template #field-category-selected-option="{ label }">
+    {{ label }}
+  </template>
+</CnIndexPage>
+```
+
+The slot scope receives all properties of the option object. This is especially useful with async select fields where options have rich data beyond just a label. See [CnFormDialog — Async Select](../components/cn-form-dialog.md#async-select) for details.
+
 ### Prepend or append extra fields
 
 Add content before or after the auto-generated fields without replacing any of them:

docs/architecture/schema-driven.md

@@ -79,7 +79,7 @@ const fields = fieldsFromSchema(schema)
 // Result: field definitions with widget types (text, email, select, date...)
 ```
 
-`CnFormDialog` renders these as a complete form with validation.
+`CnFormDialog` renders these as a complete form with validation. Select fields support both static enum arrays and async functions for remote search — see [CnFormDialog — Async Select](../components/cn-form-dialog.md#async-select).
 
 ### 5. All Together in CnIndexPage
 

docs/architecture/slots.md

@@ -0,0 +1,101 @@
+# Slot naming conventions
+
+All components follow a consistent slot naming scheme. This page documents the conventions so consumer apps use the correct slot names.
+
+## Header action slots
+
+All components that have a header area with action buttons use the standard `#actions` slot.
+
+| Slot name | Used by | Purpose |
+|-----------|---------|---------|
+| `#actions` | All page, widget, and card components | Buttons in the component header (right side) |
+
+### Usage
+
+```vue
+<CnIndexPage>
+  <template #actions>
+    <NcButton @click="doSomething">Extra action</NcButton>
+  </template>
+</CnIndexPage>
+```
+
+```vue
+<CnDetailPage>
+  <template #actions>
+    <NcButton @click="save">Save</NcButton>
+  </template>
+</CnDetailPage>
+```
+
+```vue
+<CnWidgetWrapper title="My widget">
+  <template #actions>
+    <NcButton @click="refresh">Refresh</NcButton>
+  </template>
+  <!-- widget content -->
+</CnWidgetWrapper>
+```
+
+```vue
+<CnDetailCard title="Card title">
+  <template #actions>
+    <NcButton @click="doSomething">Action</NcButton>
+  </template>
+</CnDetailCard>
+```
+
+Components using `#actions`: `CnIndexPage`, `CnDetailPage`, `CnDashboardPage`, `CnActionsBar`, `CnWidgetWrapper`, `CnObjectDataWidget`, `CnObjectMetadataWidget`, `CnDetailCard`, `CnCard`, `CnConfigurationCard`, `CnVersionInfoCard`, `CnSettingsSection`, `CnRegisterMapping`, `CnObjectCard`, `CnItemCard`, `CnMassActionBar`
+
+### Per-widget actions on CnDashboardPage (`#widget-{widgetId}-actions`)
+
+`CnDashboardPage` passes per-widget action slots through to each widget's `CnWidgetWrapper#actions`:
+
+```vue
+<CnDashboardPage :widgets="widgets" :layout="layout">
+  <template #widget-my-work="{ item }">
+    <MyWorkList />
+  </template>
+  <template #widget-my-work-actions>
+    <NcButton @click="refreshWork">Refresh</NcButton>
+  </template>
+</CnDashboardPage>
+```
+
+The slot name follows the pattern `widget-{widgetId}-actions` where `widgetId` matches the widget's `id` in the widgets array.
+
+## Row action slots
+
+| Slot name | Used by | Purpose |
+|-----------|---------|---------|
+| `#row-actions` | `CnDataTable`, `CnIndexPage` | Per-row action buttons |
+| `#card-actions` | `CnCardGrid` | Per-card action buttons |
+| `#actions-header` | `CnDataTable` | Column header for the actions column |
+
+## Mass action slots
+
+| Slot name | Used by | Purpose |
+|-----------|---------|---------|
+| `#mass-actions` | `CnActionsBar`, `CnIndexPage` | Extra mass action buttons (scoped: `count`, `selectedIds`) |
+| `#action-items` | `CnActionsBar`, `CnIndexPage` | Extra items in the top action bar |
+
+## Dialog footer slots
+
+| Slot name | Used by | Purpose |
+|-----------|---------|---------|
+| `#actions-left` | `CnAdvancedFormDialog`, `CnTabbedFormDialog` | Left-side footer buttons |
+| `#actions-right` | `CnAdvancedFormDialog`, `CnTabbedFormDialog` | Right-side footer buttons |
+
+## Translation
+
+All label props use `t()` from `@nextcloud/l10n` as defaults (sentence case). Consumer apps can override any label by passing a string prop:
+
+```vue
+<!-- Uses default translated label -->
+<CnDeleteDialog :item="item" />
+
+<!-- Override with custom label -->
+<CnDeleteDialog :item="item" :cancel-label="t('myapp', 'Go back')" />
+```
+
+See [ADR-007](https://github.com/ConductionNL/hydra/blob/development/openspec/architecture/adr-007-i18n.md) for the full i18n specification.