@conduction/nextcloud-vue 2.62.0 → 2.64.0

package/src/components/CnAppNav/CnAppNav.vue

@@ -92,8 +92,23 @@
 					<!-- Decorative beside a name: the name already says whose
 					     app this is, and an alt text would say it twice. A logo
 					     on its own carries the name as its alt text. -->
+					<!-- An emblem (`nav.brand.emblem`) stands in for the logo:
+					     the municipality's mark beside the app name, distinct
+					     from the wordmark in the top bar. `true` draws the
+					     theme's emblem from --nldesign-emblem-url. -->
 					<img
-						v-if="resolvedBrand.logo"
+						v-if="typeof resolvedBrand.emblem === 'string' && resolvedBrand.emblem !== ''"
+						class="cn-app-nav__brand-emblem"
+						data-testid="cn-nav-brand-emblem"
+						:src="resolvedBrand.emblem"
+						:alt="resolvedBrand.name ? '' : resolvedBrand.alt">
+					<span
+						v-else-if="resolvedBrand.emblem === true"
+						class="cn-app-nav__brand-emblem cn-app-nav__brand-emblem--theme"
+						data-testid="cn-nav-brand-emblem"
+						aria-hidden="true" />
+					<img
+						v-else-if="resolvedBrand.logo"
 						class="cn-app-nav__brand-logo"
 						:src="resolvedBrand.logo"
 						:alt="resolvedBrand.name ? '' : resolvedBrand.alt">
@@ -118,17 +133,33 @@
 		     OR nav root). Omitted entirely when neither the slot nor any
 		     resolvable primaryAction is present. -->
 		<slot name="primary-action">
+			<!-- A primary action that carries an `action` runs a page action
+			     (open-form opens the create dialog, navigate pushes a route)
+			     through CnActionButtons, so "New case" can live in the
+			     navigation without a create page. Drawn as one solid,
+			     full-width primary button. -->
+			<div
+				v-if="activePrimaryAction && primaryDispatchEntry"
+				class="app-navigation-new cn-app-nav__primary-action cn-app-nav__primary-action--solid"
+				data-testid="cn-nav-primary-action">
+				<CnActionButtons
+					:actions="[primaryDispatchEntry]"
+					data-testid="cn-nav-primary-action-dispatch"
+					@created="onPrimaryActionCreated" />
+			</div>
 			<!-- A primary action with an href or route is a real link.
 			     NcAppNavigationNew cannot render one, so this mirrors its
-			     wrapper and button. -->
+			     wrapper and button. `solid: true` takes this same solid,
+			     full-width button for an action with neither. -->
 			<div
-				v-if="activePrimaryAction && primaryActionLink"
+				v-else-if="activePrimaryAction && (primaryActionLink || activePrimaryAction.solid === true)"
 				class="app-navigation-new cn-app-nav__primary-action"
+				:class="{ 'cn-app-nav__primary-action--solid': activePrimaryAction.solid === true }"
 				data-testid="cn-nav-primary-action">
 				<NcButton
 					variant="primary"
 					wide
-					v-bind="primaryActionLink"
+					v-bind="primaryActionLink || {}"
 					@click="onPrimaryActionClick">
 					<template #icon>
 						<component :is="primaryActionIconComponent" :size="20" />
@@ -215,7 +246,32 @@
 				</NcAppNavigationItem>
 			</template>
 		</template>
-		<template v-if="footerItems.length > 0 || showSettingsFoldout" #footer>
+		<template v-if="footerItems.length > 0 || showSettingsFoldout || resolvedCard || resolvedHelp" #footer>
+			<!--
+				@slot card
+				@description Replace the card above the footer entries
+				(`nav.card`). Default content: a title, a line of text and one
+				link. Renders nothing when neither the slot nor `nav.card` is set.
+				@binding {object|null} card The resolved card, or null.
+			-->
+			<slot name="card" :card="resolvedCard">
+				<div
+					v-if="resolvedCard"
+					class="cn-app-nav__card"
+					data-testid="cn-nav-card">
+					<strong class="cn-app-nav__card-title">{{ resolvedCard.title }}</strong>
+					<span v-if="resolvedCard.text" class="cn-app-nav__card-text">{{ resolvedCard.text }}</span>
+					<component
+						:is="resolvedCard.linkTag"
+						v-if="resolvedCard.linkTag"
+						class="cn-app-nav__card-link"
+						data-testid="cn-nav-card-link"
+						v-bind="resolvedCard.linkAttrs"
+						@click="onCardLinkClick">
+						{{ resolvedCard.linkLabel }}
+					</component>
+				</div>
+			</slot>
 			<!-- Footer-section entries (Documentation, Features & Roadmap,
 			     About) live in NcAppNavigation's #footer slot — OUTSIDE the
 			     scrollable list — so they stay visible above the settings
@@ -226,7 +282,20 @@
 			     hover highlight are scoped to itself, so they survive being
 			     slotted. The main list's inset comes from NcAppNavigation's
 			     scope, which slot content does not carry. -->
-			<NcAppNavigationList v-if="footerItems.length > 0" class="cn-app-nav__footer-list">
+			<NcAppNavigationList v-if="footerItems.length > 0 || resolvedHelp" class="cn-app-nav__footer-list">
+				<!-- The help entry (`nav.help`): a link to the app's own help
+				     with a help icon, above the footer entries. -->
+				<NcAppNavigationItem
+					v-if="resolvedHelp"
+					:name="resolvedHelp.label"
+					:to="resolvedHelp.to"
+					:href="resolvedHelp.href"
+					:target="resolvedHelp.href ? '_blank' : undefined"
+					data-testid="cn-nav-help">
+					<template #icon>
+						<HelpCircleOutline :size="20" />
+					</template>
+				</NcAppNavigationItem>
 				<NcAppNavigationItem
 					v-for="item in footerItems"
 					:key="item.id"
@@ -360,6 +429,7 @@ import CnMenuItemIcon from '../CnMenuWidget/CnMenuItemIcon.vue'
 import { isAppInstalled } from '../../utils/appInstalled.js'
 import { isSvgPath } from '../../utils/iconUtils.js'
 import { passesContextPredicates } from '../../utils/visibleIfContext.js'
+import { CnActionButtons } from '../CnActionButtons/index.js'
 // The legacy `icon-*` → MDI bridge lives beside CnIcon now, so the menu EDITOR
 // resolves a seeded `icon-comment` the same way this nav does. It used to be a
 // map local to this file, which is why the nav drew a proper glyph and the
@@ -394,6 +464,44 @@ function byManifestOrder(a, b) {
 	return a.order - b.order
 }
 
+/** A `:name` page-path segment: name, optional `(regexp)`, optional modifier. */
+const PARAM_SEGMENT = /^:(\w+)(\([^)]*\))?([?*+])?$/
+
+/**
+ * Whether a `PARAM_SEGMENT` match may be left out (`?` or `*`).
+ *
+ * @param {Array<string>} param The match.
+ * @return {boolean} True for an optional segment.
+ */
+function isOptionalParam(param) {
+	return param[3] === '?' || param[3] === '*'
+}
+
+/**
+ * Whether a route param value fills its segment.
+ *
+ * @param {unknown} value The value.
+ * @return {boolean} False for undefined, null and the empty string.
+ */
+function isFilled(value) {
+	return value !== undefined && value !== null && value !== ''
+}
+
+/**
+ * Decode one percent-encoded path segment, or keep it as is when it is not
+ * valid percent-encoding.
+ *
+ * @param {string} segment The segment.
+ * @return {string} The decoded segment.
+ */
+function decodeSegment(segment) {
+	try {
+		return decodeURIComponent(segment)
+	} catch {
+		return segment
+	}
+}
+
 export default {
 	name: 'CnAppNav',
 
@@ -406,6 +514,7 @@ export default {
 		NcAppNavigationSettings,
 		NcButton,
 		NcCounterBubble,
+		CnActionButtons,
 		CnMenuItemIcon,
 		Cog,
 		HelpCircleOutline,
@@ -452,6 +561,16 @@ export default {
 		 * @type {{ [register: string]: { [schema: string]: number } }}
 		 */
 		cnMenuCounts: { default: () => ({}) },
+		/**
+		 * Provided by CnAppRoot — reactive `{ [menuItemId]: number }` totals
+		 * for every menu entry whose `count` is an object
+		 * (`{ register, schema, filter? }`): the total of that filtered
+		 * list, fetched under the entry's own key so an index page's
+		 * whole-schema total is left alone. Empty outside a CnAppRoot.
+		 *
+		 * @type {{ [itemId: string]: number }}
+		 */
+		cnMenuItemCounts: { default: () => ({}) },
 	},
 
 	props: {
@@ -575,7 +694,7 @@ export default {
 		},
 	},
 
-	emits: ['primary-action', 'primary-action-click'],
+	emits: ['primary-action', 'primary-action-click', 'primary-action-created', 'card-action'],
 
 	/**
 	 * The navigation's own state: which groups are open, and which entry
@@ -636,11 +755,70 @@ export default {
 			const text = (value) => (typeof value === 'string' && value !== '' ? this.effectiveTranslate(value) : '')
 			const brand = {
 				logo: typeof declared.logo === 'string' ? declared.logo : '',
+				// A URL, or `true` for the theme's emblem (--nldesign-emblem-url).
+				emblem: declared.emblem === true ? true : (typeof declared.emblem === 'string' ? declared.emblem : ''),
 				name: text(declared.name),
 				caption: text(declared.caption),
 				alt: text(declared.alt),
 			}
-			return (brand.logo || brand.name || brand.caption) ? brand : null
+			return (brand.logo || brand.emblem || brand.name || brand.caption) ? brand : null
+		},
+
+		/**
+		 * The card above the footer entries (`nav.card`): `{ title, text?,
+		 * link?: { label, route?, params?, href?, action? } }`. Title, text
+		 * and link label go through the translate function. The link is a
+		 * router link for a `route` (with a router), an anchor for an
+		 * `href`, and a button emitting `card-action` with the `action` id
+		 * otherwise. Null without a title.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-the-navigation-carries-a-card-and-a-help-entry
+		 * @return {object|null}
+		 */
+		resolvedCard() {
+			const declared = this.effectiveManifest?.nav?.card
+			if (!declared || typeof declared !== 'object' || typeof declared.title !== 'string' || declared.title === '') {
+				return null
+			}
+			const text = (value) => (typeof value === 'string' && value !== '' ? this.effectiveTranslate(value) : '')
+			const card = { title: text(declared.title), text: text(declared.text), linkTag: '', linkAttrs: {}, linkLabel: '', action: '' }
+			const link = declared.link
+			if (link && typeof link === 'object' && typeof link.label === 'string' && link.label !== '') {
+				card.linkLabel = text(link.label)
+				if (link.route && this.$router) {
+					card.linkTag = 'router-link'
+					card.linkAttrs = { to: { name: link.route, ...(link.params && typeof link.params === 'object' ? { params: link.params } : {}) } }
+				} else if (typeof link.href === 'string' && link.href !== '') {
+					card.linkTag = 'a'
+					card.linkAttrs = { href: link.href }
+				} else if (typeof link.action === 'string' && link.action !== '') {
+					card.linkTag = 'button'
+					card.linkAttrs = { type: 'button' }
+					card.action = link.action
+				}
+			}
+			return card
+		},
+
+		/**
+		 * The help entry (`nav.help`): `{ label, route?, href? }` rendered as
+		 * a footer entry with a help icon. Null without a label or a target.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-the-navigation-carries-a-card-and-a-help-entry
+		 * @return {{label: string, to?: object, href?: string}|null}
+		 */
+		resolvedHelp() {
+			const declared = this.effectiveManifest?.nav?.help
+			if (!declared || typeof declared !== 'object' || typeof declared.label !== 'string' || declared.label === '') {
+				return null
+			}
+			if (declared.route && this.$router) {
+				return { label: this.effectiveTranslate(declared.label), to: { name: declared.route }, href: undefined }
+			}
+			if (typeof declared.href === 'string' && declared.href !== '') {
+				return { label: this.effectiveTranslate(declared.label), to: undefined, href: declared.href }
+			}
+			return null
 		},
 
 		/**
@@ -661,20 +839,30 @@ export default {
 		 *  2. `manifest.nav.primaryAction` as app-wide default
 		 *  3. `null` — no primary-action button renders
 		 *
-		 * Page-scoped declarations always win over the nav-root default.
+		 * Page-scoped declarations always win over the nav-root default. An
+		 * action declaring `permission` or `visibleIf` is gated like a menu
+		 * entry.
 		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-a-navigation-primary-action-runs-a-page-action
 		 * @return {object|null}
 		 */
 		activePrimaryAction() {
 			const pages = this.effectiveManifest?.pages ?? []
 			const routeName = this.$route?.name
+			// The same `permission` / `visibleIf` gate a menu entry has: an
+			// action the reader may not take, or that a condition hides, is
+			// not drawn. A gated-out page action falls back to the nav one.
+			const gated = (action) => (action && this.passesPermission(action) && this.passesVisibleIf(action) ? action : null)
 			if (routeName) {
 				const page = pages.find((p) => p.id === routeName)
 				if (page && page.primaryAction) {
-					return page.primaryAction
+					const pageAction = gated(page.primaryAction)
+					if (pageAction) {
+						return pageAction
+					}
 				}
 			}
-			return this.effectiveManifest?.nav?.primaryAction ?? null
+			return gated(this.effectiveManifest?.nav?.primaryAction ?? null)
 		},
 
 		/**
@@ -688,6 +876,31 @@ export default {
 			return this.mdiIconComponent(this.activePrimaryAction) ?? Plus
 		},
 
+		/**
+		 * The CnActionButtons entry for a primary action that carries an
+		 * `action` (`$defs/action`: open-form, navigate, api-call, ...):
+		 * the action with the primary action's `id`, `label` and `icon`
+		 * folded in and `variant: "primary"`. Null for a plain primary
+		 * action, which keeps its link or button.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-a-navigation-primary-action-runs-a-page-action
+		 * @return {object|null}
+		 */
+		primaryDispatchEntry() {
+			const action = this.activePrimaryAction
+			const inner = action && action.action
+			if (!inner || typeof inner !== 'object' || typeof inner.type !== 'string') {
+				return null
+			}
+			return {
+				icon: action.icon || 'Plus',
+				...inner,
+				id: inner.id || action.id || 'primary-action',
+				label: action.label,
+				variant: 'primary',
+			}
+		},
+
 		/**
 		 * Link props for the primary action's button: an `href` opens in a
 		 * new tab, a `route` is a router link. Null when the action is
@@ -924,7 +1137,9 @@ export default {
 		 * `/expenses/:id`) light up — and auto-expand — their index entry
 		 * even though the detail route name is not in the menu. Longest
 		 * prefix disambiguates nested namespaces (e.g. `/pos` vs
-		 * `/pos/refunds`). Returns null when nothing matches.
+		 * `/pos/refunds`). An entry with `params` matches by its page path
+		 * with those params filled in (see `pageMatchDepth`). Returns null
+		 * when nothing matches.
 		 *
 		 * @return {string|null}
 		 */
@@ -945,20 +1160,15 @@ export default {
 				return routeName ?? null
 			}
 			let best = null
-			let bestLen = -1
+			let bestDepth = 0
 			for (const it of flat) {
 				if (!it.route) {
 					continue
 				}
-				const pagePath = this.pageForItem(it)?.route
-				if (!pagePath || pagePath === '/' || pagePath.includes(':')) {
-					continue
-				}
-				if (path === pagePath || path.startsWith(pagePath + '/')) {
-					if (pagePath.length > bestLen) {
-						best = it.route
-						bestLen = pagePath.length
-					}
+				const depth = this.pageMatchDepth(it, path)
+				if (depth > bestDepth) {
+					best = it.route
+					bestDepth = depth
 				}
 			}
 			return best ?? routeName ?? null
@@ -1007,7 +1217,9 @@ export default {
 		 * that route, else the first in menu order.
 		 *
 		 * Null whenever the existing rule already marks an entry, so a list
-		 * with an entry without a `query` behaves as it did.
+		 * with an entry without a `query` behaves as it did. An entry with
+		 * `params` is a candidate only when the current path sits below its
+		 * own filled-in page path, so another param value is never marked.
 		 *
 		 * @return {object|null} The entry to mark, or null.
 		 * @spec openspec/changes/live-check-follow-ups/specs/live-check-follow-ups/spec.md#requirement-a-page-below-a-list-marks-one-menu-entry
@@ -1017,7 +1229,9 @@ export default {
 			if (!active || this.$route?.name === active) {
 				return null
 			}
-			const entries = this.flatEntries.filter((entry) => !entry.href && entry.route === active)
+			const path = this.$route?.path
+			const entries = this.flatEntries.filter((entry) => !entry.href && entry.route === active
+				&& (!this.hasParams(entry) || this.pageMatchDepth(entry, path) > 0))
 			if (entries.length === 0 || entries.some((entry) => this.isActiveByRule(entry))) {
 				return null
 			}
@@ -1067,6 +1281,8 @@ export default {
 		// stays out of `data()`: a reactive Set mutated inside render would
 		// re-trigger the render effect.
 		this._autoCountWarned = new Set()
+		// Same latch, for warnUnfilledRouteParam() (`itemTo()` runs during render).
+		this._unfilledParamWarned = new Set()
 	},
 
 	methods: {
@@ -1275,7 +1491,19 @@ export default {
 				.sort(byManifestOrder)
 		},
 
+		/**
+		 * The label an entry shows: run through the translate function, or
+		 * as written when the entry sets `translateLabel: false` (a
+		 * user-authored title that may equal a translation key). Every
+		 * place the nav shows an entry's label reads it from here.
+		 *
+		 * @param {object} item Menu entry.
+		 * @return {string} The label to render as text.
+		 */
 		resolveLabel(item) {
+			if (item.translateLabel === false) {
+				return item.label
+			}
 			return this.effectiveTranslate(item.label)
 		},
 
@@ -1286,7 +1514,10 @@ export default {
 		 * work" and "Queue" on one list). The route name alone lit both. An
 		 * entry with a `query` is active only when the address carries that
 		 * query; an entry without one steps back when a sibling's query
-		 * matches, so exactly one of them is marked.
+		 * matches, so exactly one of them is marked. `params` work the
+		 * same way against the route's params, so of several entries on a
+		 * `/items/:slug` route only the one whose `slug` is in the address
+		 * is marked.
 		 *
 		 * On a page below a list where that rule marks nothing, the one
 		 * entry `subRouteParent` picks is active instead.
@@ -1305,9 +1536,9 @@ export default {
 		},
 
 		/**
-		 * The route and query rule on its own, without the fallback for a
-		 * page below a list. `subRouteParent` asks this to see whether the
-		 * rule already marks an entry.
+		 * The route, query and params rule on its own, without the fallback
+		 * for a page below a list. `subRouteParent` asks this to see whether
+		 * the rule already marks an entry.
 		 *
 		 * @param {object} item Menu entry.
 		 * @return {boolean} True when the rule marks the entry.
@@ -1321,17 +1552,155 @@ export default {
 			if (item.route !== this.activeRouteName) {
 				return false
 			}
-			if (item.query && typeof item.query === 'object') {
-				return this.queryMatches(item)
-			}
-			const siblings = []
-			for (const entry of this.visibleItems) {
-				siblings.push(entry, ...this.visibleChildren(entry))
+			if (this.isNarrowed(item)) {
+				return this.narrowingMatches(item)
 			}
-			return !siblings.some((entry) => entry !== item
+			return !this.flatEntries.some((entry) => entry !== item
 				&& entry.route === item.route
-				&& entry.query && typeof entry.query === 'object'
-				&& this.queryMatches(entry))
+				&& this.isNarrowed(entry)
+				&& this.narrowingMatches(entry))
+		},
+
+		/**
+		 * Whether an entry narrows its route with a `query` or `params`.
+		 *
+		 * @param {object} item Menu entry.
+		 * @return {boolean} True when the entry declares either.
+		 */
+		isNarrowed(item) {
+			return Boolean(item.query && typeof item.query === 'object') || this.hasParams(item)
+		},
+
+		/**
+		 * Whether the address carries every `query` key and every `params`
+		 * key the entry declares.
+		 *
+		 * @param {object} item Menu entry that narrows its route.
+		 * @return {boolean} True when everything it declares matches.
+		 */
+		narrowingMatches(item) {
+			const queryOk = !(item.query && typeof item.query === 'object') || this.queryMatches(item)
+			const paramsOk = !this.hasParams(item) || this.paramsMatch(item)
+			return queryOk && paramsOk
+		},
+
+		/**
+		 * Whether an entry declares a non-empty `params` object.
+		 *
+		 * @param {object} item Menu entry.
+		 * @return {boolean} True when it has route params.
+		 */
+		hasParams(item) {
+			return Boolean(item?.params) && typeof item.params === 'object' && Object.keys(item.params).length > 0
+		},
+
+		/**
+		 * Whether the route's params carry every key of an entry's
+		 * `params`. Values are compared as strings.
+		 *
+		 * @param {object} item Menu entry with `params`.
+		 * @return {boolean} True when every declared key matches.
+		 */
+		paramsMatch(item) {
+			const current = this.$route?.params ?? {}
+			return Object.keys(item.params).every((key) => String(current[key] ?? '') === String(item.params[key]))
+		},
+
+		/**
+		 * The segments of an entry's page path with its `params` filled in,
+		 * as plain values. A missing optional `:name?` segment is dropped;
+		 * null when a required one has no param, or without a page.
+		 *
+		 * @param {object} item Menu entry with `params`.
+		 * @return {Array<string>|null} The segments, or null.
+		 */
+		filledPageSegments(item) {
+			const pagePath = this.pageForItem(item)?.route
+			if (!pagePath) {
+				return null
+			}
+			const segments = []
+			for (const part of pagePath.split('/').filter(Boolean)) {
+				const param = PARAM_SEGMENT.exec(part)
+				if (!param) {
+					segments.push(part)
+					continue
+				}
+				const value = item.params?.[param[1]]
+				if (isFilled(value)) {
+					segments.push(String(value))
+				} else if (!isOptionalParam(param)) {
+					return null
+				}
+			}
+			return segments
+		},
+
+		/**
+		 * The required route param the router cannot fill when it resolves
+		 * an entry's link on its manifest page. vue-router fills a named
+		 * link's required params from the current route, then overlays every
+		 * key the entry declares, empty or null included. So a declared key
+		 * decides on its own value, and only an undeclared one falls back
+		 * to the current route. Null without a known page, or when every
+		 * required segment is filled. Reads `$route`, so it follows
+		 * navigation.
+		 *
+		 * @param {object} item Menu entry.
+		 * @return {string|null} The param name, or null.
+		 */
+		unfilledRouteParam(item) {
+			const pagePath = this.pageForItem(item)?.route
+			if (!pagePath) {
+				return null
+			}
+			const declared = item.params && typeof item.params === 'object' ? item.params : {}
+			const current = this.$route?.params ?? {}
+			for (const part of pagePath.split('/')) {
+				const param = PARAM_SEGMENT.exec(part)
+				if (!param || isOptionalParam(param)) {
+					continue
+				}
+				const value = param[1] in declared ? declared[param[1]] : current[param[1]]
+				if (!isFilled(value)) {
+					return param[1]
+				}
+			}
+			return null
+		},
+
+		/**
+		 * How deep a path sits on an entry's page path: the page path's
+		 * segment count when the path is that page or below it, else 0.
+		 * A `/` page path, or one with an unfilled `:name`, never matches.
+		 *
+		 * Without `params` the page path is compared as written. With
+		 * `params`, segments are compared decoded, because the router
+		 * percent-encodes param values in the path and the entry holds them
+		 * plain.
+		 *
+		 * @param {object} item Menu entry.
+		 * @param {string|undefined} path The path to test.
+		 * @return {number} The depth of the match, or 0.
+		 */
+		pageMatchDepth(item, path) {
+			if (!path) {
+				return 0
+			}
+			if (!this.hasParams(item)) {
+				const pagePath = this.pageForItem(item)?.route
+				if (!pagePath || pagePath === '/' || pagePath.includes(':')) {
+					return 0
+				}
+				const below = path === pagePath || path.startsWith(pagePath + '/')
+				return below ? pagePath.split('/').filter(Boolean).length : 0
+			}
+			const segments = this.filledPageSegments(item)
+			if (!segments || segments.length === 0) {
+				return 0
+			}
+			const current = path.split('/').filter(Boolean).map(decodeSegment)
+			return segments.every((segment, index) => current[index] === segment) ? segments.length : 0
 		},
 
 		/**
@@ -1396,6 +1765,9 @@ export default {
 		 * `NcAppNavigationItem`).
 		 *
 		 *  - Literal positive integer in `item.count` → return as-is.
+		 *  - `item.count` is an object (`{ register, schema, filter? }`) →
+		 *    `cnMenuItemCounts[item.id] ?? null`, the filtered total CnAppRoot
+		 *    fetched for this entry.
 		 *  - `item.count === "auto"` → look up the entry's resolved page;
 		 *    when that page is `type: "index"` with a `register`/`schema`
 		 *    in its `config`, return
@@ -1419,6 +1791,11 @@ export default {
 			if (typeof raw === 'number') {
 				return raw > 0 ? raw : null
 			}
+			if (raw && typeof raw === 'object') {
+				// A filtered count: CnAppRoot fetched it per entry id.
+				const value = this.cnMenuItemCounts?.[item.id]
+				return (typeof value === 'number' && value > 0) ? value : null
+			}
 			if (raw !== 'auto') {
 				return null
 			}
@@ -1454,6 +1831,27 @@ export default {
 			console.warn(`[CnAppNav] Menu entry "${item.id}" declares count: "auto" but has no resolvable index-type page with register + schema config — no badge will render.`)
 		},
 
+		/**
+		 * One-shot `console.warn` per menu entry whose link cannot fill a
+		 * required route param. Keyed by `id`, else route and label, so
+		 * entries without an id each get their own warning.
+		 *
+		 * @param {{ id?: string, route: string, label?: string }} item Menu entry descriptor.
+		 * @param {string} param The unfilled param name.
+		 * @return {void}
+		 * @private
+		 */
+		warnUnfilledRouteParam(item, param) {
+			const key = item.id ?? `${item.route}|${item.label ?? ''}`
+			if (this._unfilledParamWarned.has(key)) {
+				return
+			}
+			this._unfilledParamWarned.add(key)
+			const name = item.id ?? item.label ?? item.route
+			// eslint-disable-next-line no-console
+			console.warn(`[CnAppNav] Menu entry "${name}" cannot fill the required route param "${param}" of page "${item.route}" from its params or the current route — the entry renders without a link.`)
+		},
+
 		/**
 		 * Look up an item's resolved page (`pages[]` entry whose `id`
 		 * matches the menu item's `route`) — used to decide whether the
@@ -1476,11 +1874,17 @@ export default {
 		 * items (`action: "user-settings"`) and `href` items return
 		 * `null` so the entry is NOT a vue-router link: action items
 		 * fall through to the click handler, `href` items render a real
-		 * anchor via `itemHref`. Route items return a named route.
+		 * anchor via `itemHref`. Route items return a named route that
+		 * carries the item's `params` and `query` when it declares them.
+		 *
+		 * An item whose manifest page has a required segment that neither
+		 * its `params` nor the current route fill also returns null, with a
+		 * one-time warning: the router throws resolving such a link, which
+		 * would take the whole navigation down rather than that one entry.
 		 *
 		 * @param {object} item Menu item being rendered.
-		 * @return {object|null} A `{ name }` route object, or null for
-		 *   action / href / route-less items.
+		 * @return {object|null} A `{ name, params?, query? }` route object,
+		 *   or null for action / href / route-less / unfillable items.
 		 */
 		itemTo(item) {
 			if (item.action) {
@@ -1492,9 +1896,22 @@ export default {
 			if (!item.route) {
 				return null
 			}
-			// Carry optional query params so a nav entry can deep-link to a
-			// pre-filtered index page (e.g. one entry per case type → Cases?caseType=…).
-			return item.query ? { name: item.route, query: item.query } : { name: item.route }
+			const unfilled = this.unfilledRouteParam(item)
+			if (unfilled) {
+				this.warnUnfilledRouteParam(item, unfilled)
+				return null
+			}
+			const to = { name: item.route }
+			// Params fill a parameterised route (one entry per catalog →
+			// /catalogs/:slug); query deep-links to a pre-filtered index page
+			// (one entry per case type → Cases?caseType=…).
+			if (this.hasParams(item)) {
+				to.params = item.params
+			}
+			if (item.query) {
+				to.query = item.query
+			}
+			return to
 		},
 
 		/**
@@ -1646,6 +2063,11 @@ export default {
 				this.cnReplayWalkthrough(item.tourId)
 				return
 			}
+			// An entry left without a link (see itemTo) renders a `#` anchor;
+			// following it would change the address, so the click goes nowhere.
+			if (!item.href && this.unfilledRouteParam(item) && event && typeof event.preventDefault === 'function') {
+				event.preventDefault()
+			}
 			if (this.visibleChildren(item).length === 0) {
 				return
 			}
@@ -1684,6 +2106,39 @@ export default {
 		 *
 		 * @return {void}
 		 */
+		/**
+		 * Re-emit the object an `open-form` primary action created, so the
+		 * host can refresh a list or open the record.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-a-navigation-primary-action-runs-a-page-action
+		 * @param {object} created The created object.
+		 * @return {void}
+		 */
+		onPrimaryActionCreated(created) {
+			/**
+			 * @event primary-action-created Emitted after an `open-form` primary action saves. Payload: the created object.
+			 */
+			this.$emit('primary-action-created', created)
+		},
+
+		/**
+		 * A card link that is a button (an `action` id) emits `card-action`
+		 * with that id for the host to run; links and anchors navigate on
+		 * their own.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-the-navigation-carries-a-card-and-a-help-entry
+		 * @return {void}
+		 */
+		onCardLinkClick() {
+			const card = this.resolvedCard
+			if (card && card.action) {
+				/**
+				 * @event card-action Emitted when the nav card's link is an action button. Payload: the action id.
+				 */
+				this.$emit('card-action', card.action)
+			}
+		},
+
 		onPrimaryActionClick() {
 			const action = this.activePrimaryAction
 			if (!action) {
@@ -1713,6 +2168,76 @@ export default {
 </script>
 
 <style>
+/* The emblem beside the app name (`nav.brand.emblem`). A theme sets
+   --nldesign-emblem-url for `emblem: true`, and --cn-nav-emblem-size for both. */
+.cn-app-nav__brand-emblem {
+	flex: none;
+	height: var(--cn-nav-emblem-size, 34px);
+	width: auto;
+	object-fit: contain;
+}
+
+.cn-app-nav__brand-emblem--theme {
+	display: inline-block;
+	width: var(--cn-nav-emblem-size, 34px);
+	background: var(--nldesign-emblem-url) center / contain no-repeat;
+}
+
+/* The solid primary action (`solid: true`, or an action that dispatches):
+   one full-width primary button, as the board draws "New case". */
+.cn-app-nav__primary-action--solid .cn-action-buttons,
+.cn-app-nav__primary-action--solid .cn-action-buttons .button-vue,
+.cn-app-nav__primary-action--solid .button-vue {
+	width: 100%;
+	justify-content: center;
+}
+
+/* The card above the footer entries (`nav.card`). Theme hooks:
+   --cn-nav-card-background and --cn-nav-card-radius. */
+.cn-app-nav__card {
+	display: flex;
+	flex-direction: column;
+	gap: calc(2 * var(--default-grid-baseline));
+	margin: calc(2 * var(--default-grid-baseline));
+	padding: calc(4 * var(--default-grid-baseline));
+	border-radius: var(--cn-nav-card-radius, var(--border-radius-large));
+	background: var(--cn-nav-card-background, var(--color-background-hover));
+}
+
+.cn-app-nav__card-title {
+	color: var(--color-main-text);
+	font-weight: 700;
+}
+
+.cn-app-nav__card-text {
+	color: var(--color-text-maxcontrast);
+	line-height: 1.4;
+}
+
+.cn-app-nav__card-link {
+	align-self: flex-start;
+	margin: 0;
+	padding: 0;
+	border: 0;
+	background: none;
+	color: var(--color-primary-element);
+	font: inherit;
+	font-weight: 600;
+	text-decoration: none;
+	cursor: pointer;
+}
+
+.cn-app-nav__card-link:hover,
+.cn-app-nav__card-link:focus-visible {
+	text-decoration: underline;
+}
+
+.cn-app-nav__card-link:focus-visible {
+	outline: 2px solid var(--color-primary-element);
+	outline-offset: 2px;
+	border-radius: var(--border-radius-small, 4px);
+}
+
 /* The brand block at the top of the navigation. */
 .cn-app-nav__brand {
 	align-items: center;