@conduction/nextcloud-vue 2.61.0 → 2.63.0

package/src/components/CnAppRoot/CnAppRoot.vue

@@ -509,7 +509,7 @@
 					:resume="walkthroughResume"
 					:translate="translate"
 					@complete="onWalkthroughComplete"
-					@dismiss="onWalkthroughComplete" />
+					@progress="onWalkthroughProgress" />
 			</slot>
 			<!--
 			  User-settings modal. Always mounted so descendants can
@@ -554,12 +554,27 @@
 						<p class="cn-app-root__walkthrough-hint">
 							{{ restartWalkthroughHint }}
 						</p>
-						<NcButton variant="secondary" @click="restartWalkthroughFromSettings">
-							<template #icon>
-								<Restart :size="20" />
-							</template>
-							{{ restartWalkthroughLabel }}
-						</NcButton>
+						<div class="cn-app-root__walkthrough-actions">
+							<NcButton
+								v-if="walkthroughProgressValue"
+								variant="primary"
+								data-testid="cn-walkthrough-continue"
+								@click="continueWalkthroughFromSettings">
+								<template #icon>
+									<Play :size="20" />
+								</template>
+								{{ continueWalkthroughLabel }}
+							</NcButton>
+							<NcButton
+								variant="secondary"
+								data-testid="cn-walkthrough-restart"
+								@click="restartWalkthroughFromSettings">
+								<template #icon>
+									<Restart :size="20" />
+								</template>
+								{{ walkthroughProgressValue ? startOverWalkthroughLabel : restartWalkthroughLabel }}
+							</NcButton>
+						</div>
 					</NcAppSettingsSection>
 				</slot>
 				<!--
@@ -638,11 +653,13 @@
 import { getCurrentUser } from '@nextcloud/auth'
 import axios from '@nextcloud/axios'
 import { loadState } from '@nextcloud/initial-state'
+import { translate as t } from '@nextcloud/l10n'
 import { generateUrl } from '@nextcloud/router'
 import { NcAppContent, NcAppSettingsDialog, NcAppSettingsSection, NcButton, NcContent, NcEmptyContent, NcLoadingIcon, NcNoteCard } from '@nextcloud/vue'
 import { computed, reactive, shallowRef, watch } from 'vue'
 import DatabaseSearchOutline from 'vue-material-design-icons/DatabaseSearchOutline.vue'
 import OpenInNew from 'vue-material-design-icons/OpenInNew.vue'
+import Play from 'vue-material-design-icons/Play.vue'
 import Restart from 'vue-material-design-icons/Restart.vue'
 import CnAiCompanion from '../CnAiCompanion/CnAiCompanion.vue'
 import CnAppLoading from '../CnAppLoading/CnAppLoading.vue'
@@ -667,9 +684,12 @@ import { useSupportDialog } from '../../composables/useSupportDialog.js'
 import { provideTenantContext } from '../../composables/useTenantContext.js'
 import { useUserPreferences } from '../../composables/useUserPreferences.js'
 import {
+	loadWalkthroughProgress,
 	loadWalkthroughSeenVersion,
 	normaliseSeenVersion,
+	persistWalkthroughProgress,
 	persistWalkthroughSeenVersion,
+	readLocalWalkthroughProgress,
 	readLocalWalkthroughSeenVersion,
 	useWalkthrough,
 } from '../../composables/useWalkthrough.js'
@@ -749,6 +769,7 @@ export default {
 		NcNoteCard,
 		DatabaseSearchOutline,
 		OpenInNew,
+		Play,
 		Restart,
 		CnAppNav,
 		CnAppLoading,
@@ -1776,6 +1797,15 @@ export default {
 			 * @type {string}
 			 */
 			walkthroughSeenVersionValue: readLocalWalkthroughSeenVersion(this.appId),
+			/**
+			 * Where the user is in an unfinished tour (`{ tourId, stepId,
+			 * index, version }`), or null. Seeded from the local mirror, then
+			 * replaced by the per-user `<completionConfigKey>-progress`
+			 * preference. The tour resumes at this step on the next visit.
+			 *
+			 * @type {object|null}
+			 */
+			walkthroughProgressValue: readLocalWalkthroughProgress(this.appId),
 			/**
 			 * Whether `walkthroughSeenVersionValue` is settled. Starts `true`
 			 * when the manifest declares no `completionConfigKey` (the local
@@ -2529,13 +2559,15 @@ export default {
 			try {
 				const p = new URLSearchParams(window.location.search)
 				const tourId = p.get('cn_resume_tour')
-				if (!tourId) {
-					return null
+				if (tourId) {
+					return { tourId, stepId: p.get('cn_resume_step') || '' }
 				}
-				return { tourId, stepId: p.get('cn_resume_step') || '' }
 			} catch {
-				return null
+				// No URL token; fall through to the remembered progress.
 			}
+			// An unfinished tour continues at the step the user reached.
+			const progress = this.walkthroughProgressValue
+			return progress ? { tourId: progress.tourId, stepId: progress.stepId } : null
 		},
 
 		phase() {
@@ -2778,6 +2810,24 @@ export default {
 			return this.translate('Restart walkthrough')
 		},
 
+		/**
+		 * Label for continuing an unfinished tour at the remembered step.
+		 *
+		 * @return {string}
+		 */
+		continueWalkthroughLabel() {
+			return t('nextcloud-vue', 'Continue where you left off')
+		},
+
+		/**
+		 * Label for restarting an unfinished tour from the first step.
+		 *
+		 * @return {string}
+		 */
+		startOverWalkthroughLabel() {
+			return t('nextcloud-vue', 'Start over')
+		},
+
 		/**
 		 * Resolve the active modal's Vue component from the registry.
 		 * Returns null when no modal is open or the key no longer resolves.
@@ -3281,10 +3331,12 @@ export default {
 				return
 			}
 			try {
-				this.walkthroughSeenVersionValue = await loadWalkthroughSeenVersion(
-					this.appId,
-					this.walkthroughConfigKey,
-				)
+				const [seen, progress] = await Promise.all([
+					loadWalkthroughSeenVersion(this.appId, this.walkthroughConfigKey),
+					loadWalkthroughProgress(this.appId, this.walkthroughConfigKey),
+				])
+				this.walkthroughSeenVersionValue = seen
+				this.walkthroughProgressValue = progress
 			} finally {
 				this.walkthroughSeenResolved = true
 			}
@@ -3308,12 +3360,68 @@ export default {
 			// Fire-and-forget: the loader never rejects and the local mirror is
 			// already written, so a failed PUT must not surface as an error.
 			persistWalkthroughSeenVersion(this.appId, this.walkthroughConfigKey, v)
+			// A finished or skipped tour has nothing to continue.
+			if (this.walkthroughProgressValue) {
+				this.walkthroughProgressValue = null
+				persistWalkthroughProgress(this.appId, this.walkthroughConfigKey, null)
+			}
 			/**
 			 * @event walkthrough-complete Emitted when the walkthrough finishes or is dismissed.
 			 */
 			this.$emit('walkthrough-complete')
 		},
 
+		/**
+		 * Remember where the user is in the tour, so a reload or a restart
+		 * entry continues there (local mirror + per-user preference).
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @param {object} progress `{ tourId, stepId, index }` from CnWalkthrough.
+		 * @return {void}
+		 */
+		onWalkthroughProgress(progress) {
+			if (!progress || !progress.tourId) {
+				return
+			}
+			// The first step of a fresh tour is where a restart lands anyway,
+			// so it costs no request.
+			if (progress.index === 0 && !this.walkthroughProgressValue) {
+				return
+			}
+			const value = {
+				tourId: progress.tourId,
+				stepId: progress.stepId || '',
+				index: progress.index || 0,
+				version: String((this.manifest && this.manifest.version) || ''),
+			}
+			this.walkthroughProgressValue = value
+			persistWalkthroughProgress(this.appId, this.walkthroughConfigKey, value)
+		},
+
+		/**
+		 * Continue an unfinished tour from the user-settings dialog: show a
+		 * paused tour again, or start the remembered tour at its step.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @return {void}
+		 */
+		continueWalkthroughFromSettings() {
+			this.userSettingsOpen = false
+			if (!this.walkthroughEnabled) {
+				return
+			}
+			setTimeout(() => {
+				const wt = useWalkthrough(this.appId, this.manifest)
+				if (wt.resumePaused()) {
+					return
+				}
+				const progress = this.walkthroughProgressValue
+				if (progress) {
+					wt.resumeAt(progress.tourId, progress.stepId)
+				}
+			}, 50)
+		},
+
 		/**
 		 * Replay the product tour from the user-settings dialog. Closes the
 		 * dialog first, then restarts the first declared tour on the next tick
@@ -3646,6 +3754,12 @@ export default {
 	color: var(--color-text-maxcontrast);
 }
 
+.cn-app-root__walkthrough-actions {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 8px;
+}
+
 .cn-app-root__integrations-hint {
 	margin-bottom: 12px;
 	color: var(--color-text-maxcontrast);

package/src/components/CnBannerWidget/CnBannerWidget.vue

@@ -36,6 +36,16 @@
 			</component>
 		</div>
 	</section>
+	<!-- The count could not be read. One quiet line, not the card and not an
+	     alarm: hidden would read as "nothing to report", which is not known. -->
+	<p
+		v-else-if="checkFailed"
+		class="cn-banner-widget cn-banner-widget--unchecked"
+		:title="failureTooltip"
+		data-testid="cn-banner-widget-unchecked">
+		<span class="cn-banner-widget__unchecked-text">{{ uncheckedText }}</span>
+		<span class="cn-banner-widget__unchecked-reason">{{ failureTooltip }}</span>
+	</p>
 	<div v-else-if="visible" class="cn-banner-widget">
 		<NcNoteCard :type="resolvedVariant" class="cn-banner-widget__card">
 			<component
@@ -52,6 +62,7 @@
 </template>
 
 <script>
+import { translate as t } from '@nextcloud/l10n'
 import { NcNoteCard } from '@nextcloud/vue'
 import { followLinkClick, resolveHref } from '../../utils/linkNavigation.js'
 import { safeHref } from '../../utils/safeHref.js'
@@ -97,6 +108,12 @@ const MAX_ACTIONS = 2
  * condition evaluates true — a failed fetch never breaks (or spams) a
  * dashboard.
  *
+ * An attention card (`layout: "attention"`) whose `visibleWhen` request
+ * FAILS renders one quiet line instead, "Could not check", with the reason as
+ * a tooltip. A hidden card reads as "nothing needs attention", and a failed
+ * count does not know that. A request that succeeds with a value that does
+ * not meet the condition still renders nothing.
+ *
  * `layout: "attention"` turns the banner into an attention card: a card with
  * a coloured edge by severity, a `kicker` label, a `title`, a `reason` line
  * and up to two `actions` (the first is the primary one unless an action says
@@ -238,7 +255,9 @@ export default {
 		 * the banner renders from this verdict instead of fetching again —
 		 * no duplicate request and no hidden-until-self-evaluated flash —
 		 * and `value` feeds the `{value}` text placeholder. `null` (the
-		 * default) keeps the banner self-evaluating.
+		 * default) keeps the banner self-evaluating. A host whose request
+		 * failed passes `{ met: false, value: null, failed: true, reason }`,
+		 * and an attention card then says it could not check.
 		 *
 		 * @type {object|null}
 		 */
@@ -259,6 +278,13 @@ export default {
 		'action',
 	],
 
+	/**
+	 * The banner's own state: the evaluated condition, the value it read,
+	 * and whether the request for it failed.
+	 *
+	 * @return {object} The state.
+	 * @spec openspec/changes/live-check-follow-ups/specs/live-check-follow-ups/spec.md#requirement-an-attention-card-says-when-it-could-not-check
+	 */
 	data() {
 		return {
 			/** Id that ties the attention card's region to its title. */
@@ -271,6 +297,10 @@ export default {
 			 * the text wherever it says `{value}`.
 			 */
 			conditionValue: null,
+			/** Whether the visibleWhen request itself failed (not: answered "no"). */
+			conditionFailed: false,
+			/** Why it failed, as the request reported it. */
+			conditionFailureReason: '',
 		}
 	},
 
@@ -419,6 +449,52 @@ export default {
 			return this.conditionMet === true
 		},
 
+		/**
+		 * Whether to say the check failed: an attention card, with words to
+		 * show, whose `visibleWhen` request failed. A plain banner stays
+		 * hidden on failure, as it always did.
+		 *
+		 * @return {boolean}
+		 * @spec openspec/changes/live-check-follow-ups/specs/live-check-follow-ups/spec.md#requirement-an-attention-card-says-when-it-could-not-check
+		 */
+		checkFailed() {
+			const title = this.title || (this.content && this.content.title) || ''
+			return this.isAttention
+				&& !!this.resolvedVisibleWhen
+				&& this.conditionFailed
+				&& (title !== '' || this.resolvedText !== '')
+		},
+
+		/**
+		 * The one line shown when the check failed. It names the card by its
+		 * title, unless the title needs the value that could not be read.
+		 *
+		 * @return {string}
+		 * @spec openspec/changes/live-check-follow-ups/specs/live-check-follow-ups/spec.md#requirement-an-attention-card-says-when-it-could-not-check
+		 */
+		uncheckedText() {
+			const title = this.title || (this.content && this.content.title) || this.resolvedText
+			if (!title || title.includes('{value}')) {
+				return t('nextcloud-vue', 'Could not check')
+			}
+			// `escape: false`: the result is rendered through `{{ }}`, which escapes.
+			return t('nextcloud-vue', 'Could not check: {subject}', { subject: title }, undefined, { escape: false })
+		},
+
+		/**
+		 * The reason the check failed, for the tooltip and for assistive
+		 * technology.
+		 *
+		 * @return {string}
+		 * @spec openspec/changes/live-check-follow-ups/specs/live-check-follow-ups/spec.md#requirement-an-attention-card-says-when-it-could-not-check
+		 */
+		failureTooltip() {
+			if (!this.conditionFailureReason) {
+				return t('nextcloud-vue', 'The check failed.')
+			}
+			return t('nextcloud-vue', 'The check failed: {reason}', { reason: this.conditionFailureReason }, undefined, { escape: false })
+		},
+
 		/** Whether the banner navigates on click (route set + router present). */
 		clickable() {
 			return !!this.resolvedRoute && !!this.$router
@@ -493,27 +569,36 @@ export default {
 		 * modes — the Wave-1 banner shape is the canonical one, extracted to
 		 * `utils/visibleWhen.js` in Wave 3 so manifest actions reuse it),
 		 * keeping the read VALUE for the `{value}` text placeholder.
-		 * Fail-safe: any fetch/shape error leaves the banner hidden.
+		 * Fail-safe: any fetch/shape error leaves the banner hidden. The
+		 * failure is kept (`conditionFailed`, with its reason) so an
+		 * attention card can say it could not check.
 		 *
 		 * @return {Promise<void>}
+		 * @spec openspec/changes/live-check-follow-ups/specs/live-check-follow-ups/spec.md#requirement-an-attention-card-says-when-it-could-not-check
 		 */
 		async evaluateCondition() {
 			const outcome = this.resolvedConditionOutcome
 			if (outcome) {
 				this.conditionMet = outcome.met === true
 				this.conditionValue = outcome.value !== undefined ? outcome.value : null
+				this.conditionFailed = outcome.failed === true
+				this.conditionFailureReason = outcome.failed === true && typeof outcome.reason === 'string' ? outcome.reason : ''
 				return
 			}
 			const cond = this.resolvedVisibleWhen
 			if (!cond) {
 				this.conditionMet = null
 				this.conditionValue = null
+				this.conditionFailed = false
+				this.conditionFailureReason = ''
 				return
 			}
 			try {
 				const value = await readVisibleWhenValue(cond)
 				this.conditionValue = value
 				this.conditionMet = compareVisibleWhen(value, cond.op || 'eq', cond.value)
+				this.conditionFailed = false
+				this.conditionFailureReason = ''
 			} catch (error) {
 				// Still hidden: a banner that cannot tell whether it applies
 				// should not claim attention. But not silently, because a
@@ -522,6 +607,8 @@ export default {
 				console.warn('[CnBannerWidget] visibleWhen could not be evaluated, banner hidden:', error?.message || error)
 				this.conditionMet = false
 				this.conditionValue = null
+				this.conditionFailed = true
+				this.conditionFailureReason = typeof error?.message === 'string' ? error.message : String(error ?? '')
 			}
 		},
 
@@ -557,6 +644,30 @@ export default {
 	color: inherit;
 }
 
+/* The check failed. Muted text, no fill, no severity colour: it is a note
+   that something is not known, not a warning. */
+.cn-banner-widget--unchecked {
+	box-sizing: border-box;
+	margin: 0;
+	padding: 8px 12px;
+	color: var(--color-text-maxcontrast);
+	font-size: 0.9em;
+	cursor: help;
+}
+
+/* The reason, for assistive technology; sighted readers get the tooltip. */
+.cn-banner-widget__unchecked-reason {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	margin: -1px;
+	padding: 0;
+	overflow: hidden;
+	clip-path: inset(50%);
+	white-space: nowrap;
+	border: 0;
+}
+
 /* Attention card. The severity edge is an inset shadow, so it takes no width. */
 .cn-banner-widget--attention {
 	--cn-banner-accent: var(--color-primary-element);

package/src/components/CnBrandStripe/CnBrandStripe.md

@@ -20,3 +20,19 @@ Down the side of a panel, with `orientation="vertical"`:
   <span>Content beside the stripe</span>
 </div>
 ```
+
+A theme whose motif is not three bands names an image. Here the canal of a school: a blue line, its bank and the water:
+
+```vue
+<div style="--cn-brand-stripe-image: linear-gradient(to bottom, #1f4fd8 0 4px, transparent 4px 7px, #1fb5a8 7px 9px); --cn-brand-stripe-height: 9px">
+  <CnBrandStripe />
+</div>
+```
+
+On a dark band, such as a footer, `variant="inverse"` draws the theme's `--cn-brand-stripe-image-inverse`, else the one image, else the bands:
+
+```vue
+<div style="background: #14338f; padding-bottom: 16px; --cn-brand-stripe-image: linear-gradient(to bottom, #1f4fd8 0 4px, transparent 4px 7px, #1fb5a8 7px 9px); --cn-brand-stripe-image-inverse: linear-gradient(to bottom, #1f4fd8 0 4px, #ffffff 4px 7px, #1fb5a8 7px 9px); --cn-brand-stripe-height: 9px">
+  <CnBrandStripe variant="inverse" />
+</div>
+```

package/src/components/CnBrandStripe/CnBrandStripe.vue

@@ -5,7 +5,10 @@
 <template>
 	<div
 		class="cn-brand-stripe"
-		:class="{ 'cn-brand-stripe--vertical': orientation === 'vertical' }"
+		:class="{
+			'cn-brand-stripe--vertical': orientation === 'vertical',
+			'cn-brand-stripe--inverse': variant === 'inverse',
+		}"
 		aria-hidden="true"
 		data-testid="cn-brand-stripe">
 		<span class="cn-brand-stripe__band cn-brand-stripe__band--1" />
@@ -17,7 +20,8 @@
 <script>
 /**
  * CnBrandStripe draws the organisation's brand stripe: up to three coloured
- * bands next to each other, for the top of a page, a card or a sidebar.
+ * bands next to each other, or the organisation's own motif, for the top of a
+ * page, a card or a sidebar.
  *
  * The theme decides what it looks like, through the library's own custom
  * properties: `--cn-brand-stripe-color-1/2/3` (the colours, start to end),
@@ -26,6 +30,12 @@
  * tokens onto these; the library never reads a theme's tokens. Without them the
  * stripe is one band in the Nextcloud primary colour, 4px high.
  *
+ * A theme whose motif is not three bands (hanging twigs, a canal and its bank,
+ * a slanted cut) names it in `--cn-brand-stripe-image`, any background-image
+ * value; the stripe then draws that image in the same box instead of the
+ * bands. `--cn-brand-stripe-image-inverse` is the same motif for a dark band;
+ * the `inverse` variant draws it, else the one image, else the bands.
+ *
  * The stripe is decoration: it carries no meaning and is hidden from
  * assistive technology.
  *
@@ -49,6 +59,19 @@ export default {
 			default: 'horizontal',
 			validator: (v) => ['horizontal', 'vertical'].includes(v),
 		},
+
+		/**
+		 * The ground the stripe sits on: `default` (a light surface) or
+		 * `inverse` (a dark band such as a footer), which draws the theme's
+		 * `--cn-brand-stripe-image-inverse` when it names one.
+		 *
+		 * @type {'default'|'inverse'}
+		 */
+		variant: {
+			type: String,
+			default: 'default',
+			validator: (v) => ['default', 'inverse'].includes(v),
+		},
 	},
 }
 </script>
@@ -56,19 +79,52 @@ export default {
 <!--
   The stripe reads the library's own `--cn-brand-stripe-*` properties, each
   with a Nextcloud fallback. A theming app sets them from its own tokens.
+
+  THE ROOT PAINTS, NOT THE BANDS. The three bands are one background on the
+  root, a gradient with hard stops computed from the ratios, so a theme's
+  motif image can take its place with one `var()` fallback. A band painted on
+  its own element could not be switched off by the presence of an image: CSS
+  cannot ask whether a custom property is set. The band elements stay, empty,
+  so markup and tests that count them keep working.
 -->
 <style scoped>
 .cn-brand-stripe {
+	--cn-brand-stripe-first: var(--cn-brand-stripe-ratio-1, 1);
+	--cn-brand-stripe-second: var(--cn-brand-stripe-ratio-2, 1);
+	--cn-brand-stripe-total: calc(
+		var(--cn-brand-stripe-first) + var(--cn-brand-stripe-second) + var(--cn-brand-stripe-ratio-3, 1)
+	);
+	--cn-brand-stripe-stop-1: calc(var(--cn-brand-stripe-first) / var(--cn-brand-stripe-total) * 100%);
+	--cn-brand-stripe-stop-2: calc(
+		(var(--cn-brand-stripe-first) + var(--cn-brand-stripe-second)) / var(--cn-brand-stripe-total) * 100%
+	);
+	--cn-brand-stripe-direction: to right;
+	--cn-brand-stripe-bands: linear-gradient(
+		var(--cn-brand-stripe-direction),
+		var(--cn-brand-stripe-color-1, var(--color-primary-element)) 0 var(--cn-brand-stripe-stop-1),
+		var(--cn-brand-stripe-color-2, var(--color-primary-element)) var(--cn-brand-stripe-stop-1) var(--cn-brand-stripe-stop-2),
+		var(--cn-brand-stripe-color-3, var(--color-primary-element)) var(--cn-brand-stripe-stop-2) 100%
+	);
 	display: flex;
 	flex: none;
 	width: 100%;
 	height: var(--cn-brand-stripe-height, 4px);
+	background-image: var(--cn-brand-stripe-image, var(--cn-brand-stripe-bands));
+	background-repeat: repeat-x;
+	background-size: auto 100%;
+}
+
+.cn-brand-stripe--inverse {
+	background-image: var(--cn-brand-stripe-image-inverse, var(--cn-brand-stripe-image, var(--cn-brand-stripe-bands)));
 }
 
 .cn-brand-stripe--vertical {
+	--cn-brand-stripe-direction: to bottom;
 	flex-direction: column;
 	width: var(--cn-brand-stripe-height, 4px);
 	height: 100%;
+	background-repeat: repeat-y;
+	background-size: 100% auto;
 }
 
 .cn-brand-stripe__band {
@@ -78,17 +134,14 @@ export default {
 
 .cn-brand-stripe__band--1 {
 	flex-grow: var(--cn-brand-stripe-ratio-1, 1);
-	background-color: var(--cn-brand-stripe-color-1, var(--color-primary-element));
 }
 
 .cn-brand-stripe__band--2 {
 	flex-grow: var(--cn-brand-stripe-ratio-2, 1);
-	background-color: var(--cn-brand-stripe-color-2, var(--color-primary-element));
 }
 
 .cn-brand-stripe__band--3 {
 	flex-grow: var(--cn-brand-stripe-ratio-3, 1);
-	background-color: var(--cn-brand-stripe-color-3, var(--color-primary-element));
 }
 
 @media print {

package/src/components/CnChoiceCards/CnChoiceCards.vue

@@ -15,39 +15,51 @@
 		</NcNoteCard>
 
 		<div v-else class="cn-choice-cards__grid" :style="gridStyle">
-			<label
+			<!-- One cell per option: the card's label, and below it whatever the
+			     `#option-actions` slot adds. The slot sits OUTSIDE the label on
+			     purpose: a button inside a label is interactive content inside
+			     interactive content, and a click on it would toggle the radio. -->
+			<div
 				v-for="option in normalizedOptions"
 				:key="String(option.value)"
-				class="cn-choice-cards__option"
-				:class="{ 'cn-choice-cards__option--selected': isSelected(option) }">
-				<!-- A REAL, VISIBLE input, not a styled div with a click handler.
-				     It carries the checked state to assistive technology and to
-				     Windows high-contrast mode for free, and it keeps the
-				     selection perceivable without colour (WCAG 1.4.1) — the
-				     card's active border alone would not be. -->
-				<input
-					class="cn-choice-cards__input"
-					:type="multiple ? 'checkbox' : 'radio'"
-					:name="groupName"
-					:value="String(option.value)"
-					:checked="isSelected(option)"
-					:disabled="disabled"
-					@change="onToggle(option)">
-				<CnCard
-					class="cn-choice-cards__card"
-					:title="option.label"
-					titleTag="span"
-					:description="option.description"
-					:stats="option.stats || []"
-					:tags="option.tags || []"
-					:active="isSelected(option)"
-					activeVariant="primary"
-					:descriptionLines="descriptionLines">
-					<template v-if="option.icon" #icon>
-						<CnIcon :name="option.icon" :size="20" />
-					</template>
-				</CnCard>
-			</label>
+				class="cn-choice-cards__cell">
+				<label
+					class="cn-choice-cards__option"
+					:class="{ 'cn-choice-cards__option--selected': isSelected(option) }">
+					<!-- A REAL, VISIBLE input, not a styled div with a click handler.
+					     It carries the checked state to assistive technology and to
+					     Windows high-contrast mode for free, and it keeps the
+					     selection perceivable without colour (WCAG 1.4.1) — the
+					     card's active border alone would not be. -->
+					<input
+						class="cn-choice-cards__input"
+						:type="multiple ? 'checkbox' : 'radio'"
+						:name="groupName"
+						:value="String(option.value)"
+						:checked="isSelected(option)"
+						:disabled="disabled"
+						@change="onToggle(option)">
+					<CnCard
+						class="cn-choice-cards__card"
+						:title="option.label"
+						titleTag="span"
+						:description="option.description"
+						:stats="option.stats || []"
+						:tags="option.tags || []"
+						:active="isSelected(option)"
+						activeVariant="primary"
+						:descriptionLines="descriptionLines">
+						<template v-if="option.icon" #icon>
+							<CnIcon :name="option.icon" :size="20" />
+						</template>
+					</CnCard>
+				</label>
+				<div v-if="$slots['option-actions']" class="cn-choice-cards__actions">
+					<!-- @slot option-actions Content below one card, outside its label
+					     (e.g. a per-option Load button). Scope: `{ option, selected }`. -->
+					<slot name="option-actions" :option="option" :selected="isSelected(option)" />
+				</div>
+			</div>
 		</div>
 	</fieldset>
 </template>
@@ -298,6 +310,19 @@ export default {
 	padding: 12px;
 }
 
+.cn-choice-cards__cell {
+	display: flex;
+	flex-direction: column;
+	gap: 8px;
+	min-inline-size: 0;
+}
+
+.cn-choice-cards__actions {
+	display: flex;
+	flex-direction: column;
+	gap: 4px;
+}
+
 .cn-choice-cards__option {
 	position: relative;
 	display: block;