Development

CLAUDE.md

@@ -224,6 +224,7 @@ See `examples/manifest-demo/manifest.json` for a fuller reference and `docs/migr
 5. **Run `npm test` before submitting changes**
 6. **CSS class prefix**: All classes use `cn-` prefix to avoid collisions
 7. **Theming**: Use Nextcloud CSS variables only (`var(--color-primary-element)`, `var(--color-border)`, etc.). Do NOT reference `--nldesign-*` variables — the nldesign app overrides Nextcloud's own variables, so theming works automatically.
+8. **Always update docs when you add, rename, or remove a prop, event, or slot** — edit `docs/components/cn-<component>.md` in the same change. The CI `check:docs` step (run via `npm run check:docs`) verifies both that a doc file exists AND that every SFC prop and named slot appears in it. Run it locally before committing to catch gaps.
 
 ## Adding New Components
 

docs/components/cn-advanced-form-dialog.md

@@ -35,7 +35,7 @@ The dialog uses the same **two-phase pattern** as other CRUD dialogs: after the
 |------|------|---------|-------------|
 | `schema` | Object | `null` | JSON Schema used to derive property list, types, and labels (e.g. `schema.properties`, `schema.required`, `schema.title`) |
 | `item` | Object | `null` | Existing object for edit mode; `null` for create mode |
-| `dialogTitle` | String | `''` | Override dialog title; default is "Create {schemaTitle}" or "Edit {schemaTitle}" |
+| `dialogTitle` | String | `''` | Override dialog title; default is "Create \{schemaTitle\}" or "Edit \{schemaTitle\}" |
 | `nameField` | String | `'title'` | Property used as display name (e.g. in breadcrumbs or other UI) |
 | `successText` | String | `''` | Message shown in result phase on success; default "\{schemaTitle\} saved successfully." |
 | `cancelLabel` | String | `'Cancel'` | Label for cancel button in form phase |
@@ -66,11 +66,11 @@ The dialog uses the same **two-phase pattern** as other CRUD dialogs: after the
 
 | Slot | Scope | Description |
 |------|-------|-------------|
-| `#form` | formData, updateField, objectProperties, jsonData, updateJsonFromExternal, isValidJson | Replace the entire form content (all tabs). Use for fully custom UI while still using the dialog chrome and confirm/close flow. |
+| `#form` | formData, updateField, objectProperties, jsonData, updateJson, isValidJson | Replace the entire form content (all tabs). Use for fully custom UI while still using the dialog chrome and confirm/close flow. |
 | `#register-schema-selection` | proceed | Optional step before the main tabs (e.g. choose register/schema). When this slot is provided, the main tabs are not shown until the consumer calls `proceed()`. |
 | `#tab-properties` | formData, updateField, objectProperties, selectedProperty, handleRowClick, getPropertyDisplayName, getPropertyValidationClass, isPropertyEditable, validationDisplay | Override the Properties tab content. Default is the built-in properties table. |
 | `#tab-metadata` | item, formData | Override the Metadata tab content. Default is a table with ID, Created, Updated. |
-| `#tab-data` | jsonData, updateJsonFromExternal, isValid, formatJSON | Override the Data (JSON) tab content. Default is CodeMirror + "Format JSON" button. |
+| `#tab-data` | jsonData, updateJson, isValid, formatJSON | Override the Data (JSON) tab content. Default is CodeMirror + "Format JSON" button. |
 | `#actions-left` | — | Content to the left of the Cancel/Close button in the dialog footer |
 | `#actions-right` | — | Content to the right of the primary Confirm button in the dialog footer |
 
@@ -188,9 +188,9 @@ async onConfirm(payload) {
 
 ```vue
 <CnAdvancedFormDialog :schema="schema" :item="item" @confirm="onConfirm" @close="close">
-  <template #form="{ formData, updateField, jsonData, updateJsonFromExternal, isValidJson }">
+  <template #form="{ formData, updateField, jsonData, updateJson, isValidJson }">
     <MyCustomForm :data="formData" @update="updateField" />
-    <MyJsonEditor :value="jsonData" :valid="isValidJson" @input="updateJsonFromExternal" />
+    <MyJsonEditor :value="jsonData" :valid="isValidJson" @input="updateJson" />
   </template>
 </CnAdvancedFormDialog>
 ```

docs/components/cn-color-picker.md

@@ -1,6 +1,6 @@
 # CnColorPicker
 
-Themed wrapper around vue-color's `Chrome` picker. Forwards all props and events to the underlying component, so the full vue-color API stays available — this component only exists to remap the picker's hardcoded light-mode palette to Nextcloud CSS variables so it follows the active theme (light, dark, or nldesign).
+A color swatch button that opens a themed `Chrome` color picker (vue-color) in a popover. Clicking the swatch square toggles the picker. The active color is shown in the swatch (with a checker pattern behind it so alpha values render correctly). Remaps the picker's hardcoded light-mode palette to Nextcloud CSS variables so it follows the active theme (light, dark, or nldesign).
 
 ## Usage
 
@@ -30,22 +30,18 @@ export default {
 
 ## Props & events
 
-All props and listeners are forwarded to vue-color's `Chrome` component. The most commonly used:
-
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `value` | `string \| object` | — | Current color (string like `'#abcdef'`, `'rgba(...)'`, `'hsl(...)'`, or a vue-color color object). |
-| `disabled` | `Boolean` | `false` | Disables the swatch trigger and prevents the popover from opening. |
+| `value` | `string \| object` | `null` | Current color (string like `'#abcdef'`, `'rgba(...)'`, `'hsl(...)'`, or a vue-color color object). `null`/empty renders a transparent swatch. |
+| `disabled` | `Boolean` | `false` | Disables the swatch button and prevents the popover from opening. |
 | `mode` | `'hex' \| 'rgb' \| 'hsl' \| null` | `null` | Lock the numeric-input fields to a single mode and hide the toggle. `null` lets the user switch. The shown fields include alpha when `disable-alpha` is `false` (so `'rgb'` becomes RGBA, `'hsl'` becomes HSLA). |
-| `disable-alpha` | `Boolean` | `false` | Forwarded to `Chrome`. Hides the alpha bar and the alpha numeric field. |
-| `disable-fields` | `Boolean` | `false` | Forwarded to `Chrome`. Hides the hex/RGB/HSL numeric fields entirely. |
+
+Additional props (e.g. `disable-alpha`, `disable-fields`) are forwarded via `$attrs` to the underlying `Chrome` picker. See vue-color's [`Chrome` component](https://github.com/linx4200/vue-color) for the full prop surface.
 
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `input` | `{ hex, hex8, rgba, hsl, hsv, a, source }` | Fires whenever the user changes the color via any control. |
 
-See vue-color's [`Chrome` component](https://github.com/linx4200/vue-color) for the full prop and event surface.
-
 ## Theming
 
 This component remaps the following Chrome internals to Nextcloud variables:
@@ -64,7 +60,6 @@ Consumers don't need to add any CSS overrides themselves.
 
 ## Notes
 
-- This is purely the picker UI. It does not include a swatch trigger, popover, text input, or format conversion — wire those at the call site if you need them.
 - `vue-color` is a direct dependency of this library, so the picker is always available.
 
 ## Related

docs/components/cn-configuration-card.md

@@ -14,24 +14,16 @@ Configuration card with title, actions, and status indicator. Used for feature t
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `title` | String | `''` | Card title |
-| `description` | String | `''` | Card description |
-| `status` | String | `null` | `'active'`, `'inactive'`, `'error'`, `'warning'` |
-| `statusLabel` | String | `''` | Override status display text |
-| `loading` | Boolean | `false` | Loading state |
-
-## Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `action` | `actionName` | Action button clicked |
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
 | `default` | Card content |
-| `#actions` | Action buttons |
+| `#icon` | Icon displayed in the card header |
+| `#actions` | Action buttons in the card header |
 | `#status` | Custom status indicator |
+| `#footer` | Footer content below the card body |
 
 ## Usage
 

docs/components/cn-dashboard-page.md

@@ -98,6 +98,8 @@ const { widgets, layout, loading, onLayoutChange } = useDashboardView({
 | `type` | String | `'custom'` (default) or `'tile'` |
 | `iconUrl` | String | Header icon image URL |
 | `iconClass` | String | Header icon CSS class |
+| `titleIconPosition` | String | Position of the `widget-{id}-title-icon` slot: `'left'` (before title) or `'right'` (after actions, default) |
+| `titleIconColor` | String | CSS color applied to the title-icon slot container (e.g. `'#e74c3c'`) |
 | `buttons` | Array | Footer buttons: `[{ text, link }]` |
 | `itemApiVersions` | Number[] | NC Dashboard API versions — triggers auto-rendering |
 | `reloadInterval` | Number | Auto-refresh interval in seconds (NC widgets) |
@@ -129,4 +131,5 @@ const { widgets, layout, loading, onLayoutChange } = useDashboardView({
 | `header-actions` | — | Extra buttons in the page header (right side) |
 | `widget-{widgetId}` | `{ item, widget }` | Custom content for a specific widget |
 | `widget-{widgetId}-actions` | `{ item, widget }` | Header action buttons for a specific widget |
+| `widget-{widgetId}-title-icon` | `{ item, widget }` | Extra icon in the widget header; position and color controlled by `titleIconPosition` / `titleIconColor` on the widget definition |
 | `empty` | — | Custom empty state when no layout items exist |

docs/components/cn-detail-page.md

@@ -18,6 +18,11 @@ A generic detail/overview page component. The simpler counterpart to CnIndexPage
 | `iconSize` | Number | `28` | Icon size in pixels |
 | `loading` | Boolean | `false` | Loading state |
 | `loadingLabel` | String | `'Loading...'` | Message shown during loading |
+| `sidebar` | Boolean | `false` | Whether to activate the external `CnObjectSidebar` via the `objectSidebarState` inject |
+| `sidebarOpen` | Boolean | `true` | Whether the sidebar starts open (only relevant when `sidebar` is `true`) |
+| `objectType` | String | `''` | Object type slug passed to the sidebar (e.g. `'pipelinq_lead'`) |
+| `objectId` | String\|Number | `''` | Object ID passed to the sidebar |
+| `sidebarProps` | Object | `{}` | Extra sidebar configuration forwarded to `CnObjectSidebar` (`register`, `schema`, `hiddenTabs`, `title`, `subtitle`) |
 | `error` | Boolean | `false` | Error state |
 | `errorMessage` | String | `'An error occurred'` | Message shown in error state |
 | `onRetry` | Function | `null` | Callback for retry button in error state. If null, no retry button shown. |

docs/components/cn-facet-sidebar.md

@@ -20,6 +20,7 @@ Auto-generated faceted search sidebar from schema. Renders filter controls for p
 | `loading` | Boolean | `false` | Loading state |
 | `title` | String | `'Filters'` | Sidebar title |
 | `clearLabel` | String | `'Clear all'` | Clear all button label |
+| `userIsAdmin` | Boolean | `true` | Whether the current user is an admin. When `false`, schema properties with `adminOnly: true` are hidden from the filter list. |
 
 ## Events
 

docs/components/cn-filter-bar.md

@@ -4,42 +4,39 @@ sidebar_position: 12
 
 # CnFilterBar
 
-The top action bar of a list page. Shows the current result count, view-mode toggle, primary add button, and the bulk Actions menu.
+Search and filter controls row for list views. Renders a text search input, zero or more typed filter controls (select, text, checkbox), and an optional "Clear filters" button.
 
-**Wraps**: NcButton, NcActions, NcActionButton
-
-![CnFilterBar showing Cards/Table toggle, Add button, and Actions menu](/img/screenshots/cn-filter-bar.png)
+**Wraps**: NcTextField, NcSelect, NcButton, NcCheckboxRadioSwitch
 
 ## Anatomy
 
 ```
-+--------------------------------------------------------------------------+
-|  Showing N of N  |  [Cards] [Table]  |  [+ Add Entity]  [··· Actions ▾]  |  [⊞]
-+--------------------------------------------------------------------------+
-        ↑                   ↑                   ↑              ↑              ↑
-   result count        view toggle          primary CTA    bulk actions    sidebar toggle
++------------------------------------------------------------+
+|  [🔍 Search...]  |  [All types ▾]  |  [✓ Active only]  |  [Clear filters]
++------------------------------------------------------------+
+        ↑                   ↑                  ↑                     ↑
+   search input         select filter     checkbox filter        clear all
 ```
 
 | Region | Description |
 |--------|-------------|
-| **Result count** | "Showing N of N" — total visible vs total matched |
-| **View toggle** | Cards / Table radio buttons to switch between `CnCardGrid` and `CnDataTable` |
-| **Add button** | Primary call-to-action — opens CnFormDialog or navigates to create route |
-| **Actions menu** | Bulk-action dropdown — import, export, mass copy, mass delete |
-| **Sidebar toggle** | Icon button that opens/closes the `CnIndexSidebar` |
+| **Search input** | Free-text search; emits `search` on every keystroke. Shows a clear (×) button while text is entered |
+| **Filter controls** | One control per entry in `:filters`. Type `select` renders NcSelect, `text` renders NcTextField, `checkbox` renders NcCheckboxRadioSwitch |
+| **Clear filters** | Appears when any filter or the search term is non-empty (when `showClearAll` is `true`); emits `clear-all` |
 
 ## Usage
 
 ```vue
 <CnFilterBar
-  :result-count="objects.length"
-  :total-count="pagination.totalItems"
-  :view-mode="viewMode"
-  :add-label="t('myapp', 'Add Client')"
-  :actions="bulkActions"
-  @view-change="viewMode = $event"
-  @add="onCreate"
-  @action="onBulkAction" />
+  :search-value="searchTerm"
+  search-placeholder="Search clients..."
+  :filters="[
+    { key: 'type', label: 'All types', type: 'select', options: typeOptions, value: selectedType },
+    { key: 'active', label: 'Active only', type: 'checkbox', value: showActiveOnly },
+  ]"
+  @search="onSearch"
+  @filter-change="onFilterChange"
+  @clear-all="clearFilters" />
 ```
 
 ### Props

docs/components/cn-index-page.md

@@ -18,6 +18,8 @@ The main list page component. Combines a data table (or card grid), filter bar,
 |------|------|---------|-------------|
 | `title` | String | *(required)* | Page title |
 | `description` | String | `''` | Optional subtitle |
+| `showTitle` | Boolean | `false` | Show the page header (icon, title, description) inline above the table. When `false` (default), the title is shown in the sidebar header instead. |
+| `icon` | String | `''` | MDI icon name for the page header. Defaults to `schema.icon` when a schema is provided. |
 | `schema` | Object | `null` | OpenRegister schema for auto-generating columns, filters, and form fields |
 | `objects` | Array | `[]` | Row data |
 | `pagination` | Object | `null` | Pagination state (`\{ currentPage, totalPages, totalItems, pageSize \}`) |

docs/components/cn-index-sidebar.md

@@ -86,6 +86,7 @@ When using `CnIndexPage`, the sidebar is managed internally — you do not need
 | `filtersLabel` | String | `'Filters'` | Heading above the filter controls |
 | `columnsHeading` | String | `'Column Visibility'` | Heading inside the Columns tab |
 | `columnsDescription` | String | `'Select which columns to display in the table'` | Subtitle inside the Columns tab |
+| `userIsAdmin` | Boolean | `true` | Whether the current user is an admin. When `false`, schema properties with `adminOnly: true` are hidden from the filter list in the Search tab. |
 
 ### Events
 

docs/components/cn-mass-copy-dialog.md

@@ -20,8 +20,12 @@ Two-phase mass copy dialog with naming pattern. Allows users to define a naming
 | `dialogTitle` | String | `'Copy items'` | |
 | `patternLabel` | String | `'Naming pattern'` | |
 | `patternPlaceholder` | String | `'\{name\} (copy)'` | |
-| `confirmLabel` | String | `'Copy'` | |
+| `emptyText` | String | `'No items selected for copying.'` | Message shown when all items have been removed from the list |
+| `successText` | String | `'Items successfully copied.'` | Message shown in the result phase on success |
 | `cancelLabel` | String | `'Cancel'` | |
+| `closeLabel` | String | `'Close'` | Label for the close button shown in the result phase |
+| `confirmLabel` | String | `'Copy'` | |
+| `removeLabel` | String | `'Remove from list'` | Tooltip/label for the per-item remove button |
 
 ## Events
 

docs/components/cn-mass-delete-dialog.md

@@ -18,9 +18,13 @@ Two-phase mass delete confirmation dialog. Shows list of items to delete, requir
 | `nameField` | String | `'title'` | Field to display as item name |
 | `nameFormatter` | Function | `null` | Optional function `(item) => string` to format item names. Overrides `nameField` when provided. |
 | `dialogTitle` | String | `'Delete items'` | |
-| `warningText` | String | `''` | Warning message |
-| `confirmLabel` | String | `'Delete'` | |
+| `warningText` | String | `''` | Warning text shown above the item list |
+| `emptyText` | String | `'No items selected for deletion.'` | Message shown when all items have been removed from the list |
+| `successText` | String | `'Items successfully deleted.'` | Message shown in the result phase on success |
 | `cancelLabel` | String | `'Cancel'` | |
+| `closeLabel` | String | `'Close'` | Label for the close button shown in the result phase |
+| `confirmLabel` | String | `'Delete'` | |
+| `removeLabel` | String | `'Remove from list'` | Tooltip/label for the per-item remove button |
 
 ## Events
 

docs/components/cn-mass-export-dialog.md

@@ -14,11 +14,15 @@ Export format selection dialog. Lets users pick a format and triggers export for
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `items` | Array | `[]` | Items to export |
-| `formats` | Array | `['json', 'csv']` | Available export formats |
-| `dialogTitle` | String | `'Export items'` | |
-| `confirmLabel` | String | `'Export'` | |
+| `dialogTitle` | String | `'Export objects'` | |
+| `description` | String | `''` | Optional description text shown above the format selector |
+| `formats` | Array | `[{ id: 'excel', label: 'Excel (.xlsx)' }, { id: 'csv', label: 'CSV (.csv)' }]` | Available export formats as `[{ id, label }]` objects |
+| `defaultFormat` | String | `'excel'` | ID of the format selected by default |
+| `successText` | String | `'Export completed successfully.'` | Message shown in the result phase on success |
+| `formatLabel` | String | `'Export format'` | Label above the format selector |
 | `cancelLabel` | String | `'Cancel'` | |
+| `closeLabel` | String | `'Close'` | Label for the close button shown in the result phase |
+| `confirmLabel` | String | `'Export'` | |
 
 ## Events