@conduction/nextcloud-vue 2.63.0 → 2.65.0

package/l10n/en.json

@@ -48,6 +48,8 @@
     "No integrations available yet.": "No integrations available yet.",
     "This integration is not available.": "This integration is not available.",
     "Integrations": "Integrations",
+    "View": "View",
+    "current step": "current step",
     "{app} not available": "{app} not available",
     "{app} not configured": "{app} not configured",
     "This integration is not available or not configured yet.": "This integration is not available or not configured yet.",

package/l10n/nl.json

@@ -48,6 +48,8 @@
     "No integrations available yet.": "Nog geen integraties beschikbaar.",
     "This integration is not available.": "Deze integratie is niet beschikbaar.",
     "Integrations": "Integraties",
+    "View": "Weergave",
+    "current step": "huidige stap",
     "{app} not available": "{app} niet beschikbaar",
     "{app} not configured": "{app} niet geconfigureerd",
     "This integration is not available or not configured yet.": "Deze integratie is nog niet beschikbaar of niet geconfigureerd.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/nextcloud-vue",
-  "version": "2.63.0",
+  "version": "2.65.0",
   "description": "Shared Vue component library for Conduction Nextcloud apps — complements @nextcloud/vue with higher-level components, OpenRegister integration, and NL Design System support",
   "homepage": "https://github.com/ConductionNL/nextcloud-vue#readme",
   "bugs": {

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 || showsHelp" #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,24 @@
 			     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 || showsHelp"
+				class="cn-app-nav__footer-list"
+				:class="{ 'cn-app-nav__footer-list--after-settings': settingsFirst }">
+				<!-- The help entry (`nav.help`): a link to the app's own help
+				     with a help icon, above the footer entries (or after them,
+				     when a declared `nav.footer` names it last). -->
+				<NcAppNavigationItem
+					v-if="showsHelp && !helpAfterItems"
+					: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"
@@ -249,6 +322,17 @@
 							:active="isActive(item)" />
 					</template>
 				</NcAppNavigationItem>
+				<NcAppNavigationItem
+					v-if="showsHelp && helpAfterItems"
+					: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>
 			</NcAppNavigationList>
 			<!-- Settings foldout (section: "settings" items). NC-native
 			     gear-icon button that slides open a panel; the first entry
@@ -257,6 +341,7 @@
 			<NcAppNavigationSettings
 				v-if="showSettingsFoldout"
 				:name="settingsFoldoutLabel"
+				:class="{ 'cn-app-nav__settings--first': settingsFirst }"
 				data-testid="cn-nav-settings">
 				<ul class="cn-app-nav__settings-list">
 					<NcAppNavigationItem
@@ -360,6 +445,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
@@ -444,6 +530,7 @@ export default {
 		NcAppNavigationSettings,
 		NcButton,
 		NcCounterBubble,
+		CnActionButtons,
 		CnMenuItemIcon,
 		Cog,
 		HelpCircleOutline,
@@ -490,6 +577,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: {
@@ -613,7 +710,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
@@ -674,11 +771,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
 		},
 
 		/**
@@ -699,20 +855,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)
 		},
 
 		/**
@@ -726,6 +892,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
@@ -783,17 +974,113 @@ export default {
 		 * Documentation, Features & Roadmap, About.
 		 */
 		footerItems() {
-			return this.visibleItems.filter((item) => item.section === 'footer')
+			const footer = this.visibleItems.filter((item) => item.section === 'footer')
+			const declared = this.declaredFooter
+			if (declared === null) {
+				return footer
+			}
+			// A declared footer (`nav.footer`) keeps only the entries it names,
+			// in the order it names them.
+			return declared
+				.map((id) => footer.find((item) => item.id === id))
+				.filter(Boolean)
+		},
+
+		/**
+		 * The footer the manifest declares (`nav.footer`): an ordered list of
+		 * menu entry ids plus the reserved ids `help` (the `nav.help` entry)
+		 * and `settings` (the settings foldout). Null when the manifest
+		 * declares none, which keeps today's footer: the help entry, then
+		 * every `section: "footer"` entry, then the foldout.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps-2/specs/zuiddrecht-pixel-gaps-2/spec.md#requirement-the-navigation-footer-can-be-declared
+		 * @return {Array<string>|null}
+		 */
+		declaredFooter() {
+			const declared = this.effectiveManifest?.nav?.footer
+			if (!Array.isArray(declared)) {
+				return null
+			}
+			return declared.filter((id) => typeof id === 'string' && id !== '')
+		},
+
+		/**
+		 * Footer-section entries a declared footer leaves out. They move into
+		 * the settings foldout rather than disappearing, so a page such as
+		 * Store or Reports stays reachable. Empty without `nav.footer`.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps-2/specs/zuiddrecht-pixel-gaps-2/spec.md#requirement-the-navigation-footer-can-be-declared
+		 * @return {Array<object>}
+		 */
+		undeclaredFooterItems() {
+			const declared = this.declaredFooter
+			if (declared === null) {
+				return []
+			}
+			return this.visibleItems.filter((item) => item.section === 'footer' && !declared.includes(item.id))
+		},
+
+		/**
+		 * Whether the help entry renders: whenever it resolves, unless a
+		 * declared footer leaves `help` out.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps-2/specs/zuiddrecht-pixel-gaps-2/spec.md#requirement-the-navigation-footer-can-be-declared
+		 * @return {boolean}
+		 */
+		showsHelp() {
+			if (!this.resolvedHelp) {
+				return false
+			}
+			return this.declaredFooter === null || this.declaredFooter.includes('help')
+		},
+
+		/**
+		 * Whether the help entry goes AFTER the footer entries. Only a declared
+		 * footer that names an entry before `help` puts it there; by default
+		 * it leads the list.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps-2/specs/zuiddrecht-pixel-gaps-2/spec.md#requirement-the-navigation-footer-can-be-declared
+		 * @return {boolean}
+		 */
+		helpAfterItems() {
+			const declared = this.declaredFooter
+			if (declared === null) {
+				return false
+			}
+			const help = declared.indexOf('help')
+			return this.footerItems.some((item) => declared.indexOf(item.id) < help)
+		},
+
+		/**
+		 * Whether the settings foldout goes ABOVE the footer list: only when a
+		 * declared footer names `settings` before every other entry
+		 * (`["settings", "help"]`, the board's "Instellingen" then "Hulp en
+		 * uitleg"). Done with CSS `order` on the two siblings, so the markup
+		 * of both stays as it is.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps-2/specs/zuiddrecht-pixel-gaps-2/spec.md#requirement-the-navigation-footer-can-be-declared
+		 * @return {boolean}
+		 */
+		settingsFirst() {
+			const declared = this.declaredFooter
+			return declared !== null && declared.indexOf('settings') === 0
 		},
 
 		/**
 		 * Items that render INSIDE the NcAppNavigationSettings foldout
 		 * (section: "settings"). The foldout is the NC-native gear-icon
 		 * button that slides a panel open; these entries are app-level
-		 * configuration pages (Forms, Pipelines, Automations, …).
+		 * configuration pages (Forms, Pipelines, Automations, …). A declared
+		 * footer (`nav.footer`) adds the footer entries it leaves out.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps-2/specs/zuiddrecht-pixel-gaps-2/spec.md#requirement-the-navigation-footer-can-be-declared
+		 * @return {Array<object>}
 		 */
 		settingsItems() {
-			return this.visibleItems.filter((item) => item.section === 'settings')
+			return [
+				...this.visibleItems.filter((item) => item.section === 'settings'),
+				...this.undeclaredFooterItems,
+			]
 		},
 
 		/**
@@ -1590,6 +1877,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
@@ -1613,6 +1903,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
 			}
@@ -1923,6 +2218,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) {
@@ -1952,6 +2280,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;
@@ -2008,6 +2406,21 @@ export default {
 	padding: calc(var(--default-grid-baseline, 4px) * 2);
 }
 
+/*
+ * The primary action never shrinks out of sight. NcAppNavigation renders it in
+ * `.app-navigation__body`, a flex child with `overflow-y: scroll` (so its
+ * minimum height is 0) beside a list of `height: 100%` and the footer. With a
+ * card and footer entries below the list, the column overflows and the body
+ * gives up its share of the shrink: "New case" showed as a 24px sliver of a
+ * 42px button. All three forms carry `.app-navigation-new` (the solid and
+ * link wrappers mirror NcAppNavigationNew's class), and the rule is scoped to
+ * this component's navigation, so a navigation without a primary action lays
+ * out exactly as before.
+ */
+.app-navigation[data-testid="cn-nav"] .app-navigation__body:has(> .app-navigation-new) {
+	flex-shrink: 0;
+}
+
 /*
  * Footer-section items (section: "footer") render in NcAppNavigation's
  * #footer slot, outside the scroll container, so they stay visible above
@@ -2031,6 +2444,20 @@ export default {
 	overflow: visible !important;
 }
 
+/*
+ * A declared footer that names `settings` first (`nav.footer`) puts the
+ * foldout above the footer list. The two are siblings in NcAppNavigation's
+ * flex column, so `order` moves them without changing either's markup; the
+ * card above keeps order 0 and stays first.
+ */
+.cn-app-nav__settings--first {
+	order: 1;
+}
+
+.cn-app-nav__footer-list--after-settings {
+	order: 2;
+}
+
 /*
  * Align the settings foldout's items with the main/footer list items,
  * whose icons sit at a 16px inset. The foldout's items live in a bare

package/src/components/CnAppRoot/CnAppRoot.md

@@ -203,3 +203,7 @@ Static-manifest apps use `useAppManifest('myapp', bundledManifest)`, which fetch
 | `softDependencyNotices` | Boolean | `false` | **Deprecated.** Restores the in-shell orange notices, one per unresolved optional dependency. Off by default: they stacked one per optional leaf and pushed the app's own content below the fold, for an audience who cannot act on them. Mount `CnLeafDependencySettings` in admin settings instead. Slated for removal. |
 
 `unresolvedSoftDependencies` is unchanged and still exposed, so an app rendering its own surface from it keeps working.
+
+### Without a navigation (`hideMenu`)
+
+`hideMenu` (default `false`) renders neither the default CnAppNav nor the `#menu` slot, so the content starts at the left edge.