@conduction/nextcloud-vue 1.0.0-beta.18 → 1.0.0-beta.19

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@conduction/nextcloud-vue",
-	"version": "1.0.0-beta.18",
+	"version": "1.0.0-beta.19",
 	"description": "Shared Vue component library for Conduction Nextcloud apps — complements @nextcloud/vue with higher-level components, OpenRegister integration, and NL Design System support",
 	"license": "EUPL-1.2",
 	"author": "Conduction B.V. <info@conduction.nl>",

package/src/components/CnIndexPage/CnIndexPage.md

@@ -371,6 +371,7 @@ export default {
 | `excludeFields` | Array | `[]` | Field keys to exclude from the form dialog |
 | `includeFields` | Array | `null` | Field keys to include in the form dialog (whitelist) |
 | `fieldOverrides` | Object | `{}` | Per-field config overrides passed to `CnFormDialog` |
+| `customComponents` | Object | `null` | Custom-component / handler registry. When set, takes precedence over the injected `cnCustomComponents` from CnAppRoot. Used to resolve `actions[].handler` registry names declared in the manifest (manifest-actions-dispatch). |
 | `showViewToggle` | Boolean | `true` | Whether to show the Cards/Table view toggle |
 | `refreshing` | Boolean | `false` | Whether a refresh is currently in progress |
 | `refreshDisabled` | Boolean | `false` | Whether the refresh button is disabled |

package/src/components/CnIndexPage/CnIndexPage.vue

@@ -215,7 +215,7 @@
 							<CnRowActions
 								:actions="mergedActions"
 								:row="row"
-								@action="$emit('action', $event)" />
+								@action="onRowAction" />
 						</slot>
 					</template>
 				</CnDataTable>
@@ -257,7 +257,7 @@
 							<CnRowActions
 								:actions="mergedActions"
 								:row="object"
-								@action="$emit('action', $event)" />
+								@action="onRowAction" />
 						</slot>
 					</template>
 				</CnCardGrid>
@@ -267,7 +267,7 @@
 					:open.sync="contextMenuOpen"
 					:actions="mergedActions"
 					:target-item="contextMenuRow"
-					@action="$emit('action', $event)"
+					@action="onRowAction"
 					@close="closeContextMenu" />
 
 				<!-- Pagination -->
@@ -433,14 +433,20 @@ export default {
 		CnIndexSidebar,
 	},
 
+	/**
+	 * Inject the customComponents registry from a CnAppRoot ancestor.
+	 * Used by:
+	 * - REQ-MAD-3 / REQ-MAD-8 (manifest-actions-dispatch): resolves
+	 *   `actions[].handler` registry names to functions called on
+	 *   row-action click.
+	 * - The cardComponent + form-dialog override paths: when set, the
+	 *   prop-level `customComponents` wins, but the inject is the
+	 *   default. See `effectiveCustomComponents`.
+	 *
+	 * Falls back to an empty object so `CnIndexPage` works standalone
+	 * (unit tests, isolated mount) without `CnAppRoot`.
+	 */
 	inject: {
-		/**
-		 * Custom-component registry provided by `CnAppRoot`. Falls back
-		 * to an empty object so `CnIndexPage` works when mounted
-		 * without `CnAppRoot` (e.g. in unit tests). The explicit
-		 * `customComponents` prop wins when set — see
-		 * `effectiveCustomComponents`.
-		 */
 		cnCustomComponents: { default: () => ({}) },
 	},
 
@@ -783,6 +789,11 @@ export default {
 		 * `cnCustomComponents`. Provided primarily so unit tests can
 		 * pass a registry without mounting `CnAppRoot`.
 		 *
+		 * Used by:
+		 * - `cardComponent` resolution (REQ-MCI from manifest-card-index)
+		 * - `actions[].handler` registry name resolution (REQ-MAD-3 from
+		 *   manifest-actions-dispatch — handler funcs called on row-action click)
+		 *
 		 * @type {object|null}
 		 */
 		customComponents: {
@@ -887,9 +898,56 @@ export default {
 			return builtIn
 		},
 
-		/** Merged actions: app-provided first, then built-in defaults */
+		/**
+		 * Effective customComponents registry — explicit prop wins over
+		 * the injected ancestor registry. Used to:
+		 * - Resolve `actions[].handler` registry names (REQ-MAD-3,
+		 *   manifest-actions-dispatch).
+		 * - Resolve the `cardComponent` name for card-grid view (REQ-MCI,
+		 *   manifest-card-index).
+		 *
+		 * @return {object}
+		 */
+		effectiveCustomComponents() {
+			return this.customComponents ?? this.cnCustomComponents ?? {}
+		},
+
+		/**
+		 * Merged actions: app-provided first, then built-in defaults.
+		 *
+		 * REQ-MAD-3 / REQ-MAD-4 / REQ-MAD-5 / REQ-MAD-6 / REQ-MAD-7
+		 * (manifest-actions-dispatch) — for any action whose `handler`
+		 * is a string, resolve it through `resolveHandler()` so
+		 * `CnRowActions` sees the same `{ handler: fn }` shape it does
+		 * for built-in defaults. Function-typed handlers (the existing
+		 * runtime path) pass through untouched.
+		 */
 		mergedActions() {
-			return [...this.actions, ...this.defaultActions]
+			const dispatched = this.actions.map((action) => {
+				if (typeof action.handler === 'function') {
+					// Back-compat: programmatic function handler — keep as-is.
+					return action
+				}
+				if (typeof action.handler !== 'string' || action.handler.length === 0) {
+					// No handler → emit-only path (existing default).
+					return action
+				}
+				const isNone = action.handler === 'none'
+				const resolved = this.resolveHandler(action)
+				if (resolved) {
+					// `none` returns a sentinel no-op handler AND must
+					// suppress the `@action` emit; flag it so onRowAction
+					// can drop the bubbled event.
+					return isNone
+						? { ...action, handler: resolved, _dispatchSuppress: true }
+						: { ...action, handler: resolved }
+				}
+				// Either reserved keyword "emit" / unknown name / non-function
+				// registry entry → page emits @action only; no handler call.
+				const { handler, ...rest } = action
+				return rest
+			})
+			return [...dispatched, ...this.defaultActions]
 		},
 
 		hasRowActions() {
@@ -937,17 +995,6 @@ export default {
 			return (this.sidebar && this.sidebar.search) || {}
 		},
 
-		/**
-		 * Effective customComponents registry used to resolve the
-		 * `cardComponent` name. Explicit prop wins, inject falls back,
-		 * empty object is the last resort.
-		 *
-		 * @return {object}
-		 */
-		effectiveCustomComponents() {
-			return this.customComponents ?? this.cnCustomComponents ?? {}
-		},
-
 		/**
 		 * Resolved card component for card-grid view mode. Returns
 		 * `null` when `cardComponent` is empty OR when the name is not
@@ -984,6 +1031,89 @@ export default {
 	},
 
 	methods: {
+		/**
+		 * REQ-MAD-3 / REQ-MAD-4 / REQ-MAD-5 / REQ-MAD-6 / REQ-MAD-7
+		 * (manifest-actions-dispatch) — Resolve a manifest-declared
+		 * action's `handler` string into a `(row) => void` invocation
+		 * function. Returns null when the action should fall back to
+		 * the page's `@action`-event-only path.
+		 *
+		 *   - Reserved keyword `"navigate"` → push the configured route
+		 *     with `params: { id: row[rowKey] }`.
+		 *   - Reserved keyword `"emit"` → null (page still bubbles
+		 *     `@action`; explicit no-op).
+		 *   - Reserved keyword `"none"` → returns a no-op function that
+		 *     suppresses both the handler and the `@action` emit. The
+		 *     suppression happens via the special `_dispatchSuppress`
+		 *     flag on the cloned action; see mergedActions for the
+		 *     detail.
+		 *   - Registry name → look up in `effectiveCustomComponents`;
+		 *     when it's a function, wrap as
+		 *     `(row) => fn({ actionId: action.id, item: row })`. When
+		 *     it's a non-function, console.warn and return null.
+		 *   - Unknown registry name → silent fall-through (null).
+		 *
+		 * @param {object} action The manifest-shaped action object.
+		 * @return {Function|null}
+		 */
+		resolveHandler(action) {
+			const name = action.handler
+			if (typeof name !== 'string' || name.length === 0) return null
+			if (name === 'navigate') {
+				const route = action.route
+				if (typeof route !== 'string' || route.length === 0) {
+					// eslint-disable-next-line no-console
+					console.warn(
+						`[CnIndexPage] action "${action.id}" declares handler:"navigate" `
+						+ 'but route is missing; falling back to @action-only.',
+					)
+					return null
+				}
+				return (row) => {
+					this.$router.push({
+						name: route,
+						params: { id: row[this.rowKey] },
+					})
+				}
+			}
+			if (name === 'emit') return null
+			if (name === 'none') {
+				// Returns a sentinel that CnRowActions will treat as a
+				// no-op; we additionally short-circuit @action emit in
+				// `onRowAction` via the action's id.
+				return () => {}
+			}
+			const fn = this.effectiveCustomComponents[name]
+			if (typeof fn === 'function') {
+				return (row) => fn({ actionId: action.id, item: row })
+			}
+			if (fn !== undefined) {
+				// eslint-disable-next-line no-console
+				console.warn(
+					`[CnIndexPage] action.handler "${name}" resolved to a non-function in `
+					+ 'customComponents — components belong to slot overrides; falling '
+					+ 'back to @action-only.',
+				)
+			}
+			return null
+		},
+
+		/**
+		 * REQ-MAD-6 (manifest-actions-dispatch) — `handler: "none"`
+		 * blocks the `@action` emit entirely. CnRowActions emits
+		 * `@action` with `{ action: action.label, row }` and the page
+		 * forwards via `@action="$emit('action', $event)"`. This handler
+		 * intercepts so the `none`-flagged action is dropped before
+		 * re-emit.
+		 *
+		 * @param {{action: string, row: object}} payload The CnRowActions emit.
+		 */
+		onRowAction(payload) {
+			const matched = this.mergedActions.find((a) => a.label === payload.action)
+			if (matched && matched._dispatchSuppress) return
+			this.$emit('action', payload)
+		},
+
 		/**
 		 * Handle row click — emits row-click event for the parent to handle navigation.
 		 * @param {object} row The clicked row object

package/src/schemas/app-manifest.schema.json

@@ -315,6 +315,15 @@
 					"type": "boolean",
 					"default": false,
 					"description": "When true the consumer SHOULD show a confirmation dialog before invoking the action. Useful for destructive actions; defaults to false."
+				},
+				"handler": {
+					"type": "string",
+					"description": "Optional dispatch target for the action. Either (a) one of the reserved keywords \"navigate\" / \"emit\" / \"none\", or (b) a registry name resolving to a function in the customComponents map passed to CnAppRoot. When the registry name resolves to a function, CnIndexPage / CnDetailPage call it with `{ actionId, item }` on row-action click. The reserved keywords short-circuit the registry lookup: \"navigate\" calls `$router.push({ name: action.route, params: { id: row[rowKey] } })`; \"emit\" emits `@action` only (semantic-explicit no-op); \"none\" disables the click entirely. When unset (the default), the action only emits `@action` and the page-level listener decides the side-effect — preserves v1.2 behaviour. Added in schema 1.3.0.",
+					"pattern": "^(navigate|emit|none|[A-Za-z][A-Za-z0-9_]*)$"
+				},
+				"route": {
+					"type": "string",
+					"description": "Vue-router route name dispatched when `handler === \"navigate\"`. Required for the navigate keyword; ignored for other handler values. CnIndexPage uses it as `$router.push({ name: action.route, params: { id: row[rowKey] } })`. Added in schema 1.3.0."
 				}
 			}
 		},

package/src/utils/validateManifest.js

@@ -563,9 +563,34 @@ function validateActionsArray(cfg, pathSlash, pathBracket, errors) {
 		if (typeof action.label !== 'string' || action.label.length === 0) {
 			errors.push(`${actionPath}/label: must be a non-empty string`)
 		}
+		// REQ-MAD-1 / REQ-MAD-2 — `handler` (string, registry name OR
+		// reserved keyword `navigate`/`emit`/`none`) and the matching
+		// `navigate` requirement on `route`. Schema 1.3.0+.
+		if (action.handler !== undefined) {
+			if (typeof action.handler !== 'string') {
+				errors.push(`${actionPath}/handler: must be a string when set`)
+			} else if (!HANDLER_PATTERN.test(action.handler)) {
+				errors.push(
+					`${actionPath}/handler: "${action.handler}" must match `
+					+ '"navigate" | "emit" | "none" | [A-Za-z][A-Za-z0-9_]*',
+				)
+			}
+			if (action.handler === 'navigate'
+				&& (typeof action.route !== 'string' || action.route.length === 0)) {
+				errors.push(`${actionPath}/route: required when handler is "navigate"`)
+			}
+		}
 	})
 }
 
+/**
+ * REQ-MAD-1 — Allowed shapes for `actions[].handler`. Either a
+ * reserved keyword (`navigate` | `emit` | `none`) or a JS-identifier
+ * registry name (alphanumeric + underscore, leading letter). Mirrors
+ * the schema's `pattern` on the `handler` property.
+ */
+const HANDLER_PATTERN = /^(navigate|emit|none|[A-Za-z][A-Za-z0-9_]*)$/
+
 /**
  * Validate `config.widgets[]` for dashboard page type
  * (`manifest-config-refs` REQ-MCR). Each entry MUST be an object with