@n8n/frontend-module-inbox 0.2.4 → 0.3.0

package/src/promotions/PromotionReviewDetail.test.ts

@@ -0,0 +1,244 @@
+import type { InboxPromotionReviewItem } from '@n8n/api-types';
+import { componentRegistry, type PromotionChangesState } from '@n8n/frontend-module-sdk';
+import { useToast } from '@n8n/composables/useToast';
+import { createComponentRenderer } from '@n8n/frontend-test-utils';
+import { defineComponent } from 'vue';
+import { onTestFinished } from 'vitest';
+import { createTestingPinia } from '@pinia/testing';
+import { createDeferredPromise } from '@n8n/utils/promise/deferred-promise';
+import { waitFor, within } from '@testing-library/vue';
+import userEvent from '@testing-library/user-event';
+
+import PromotionReviewDetail from './PromotionReviewDetail.vue';
+import { approvePromotionReview } from './promotionReviews.api';
+
+vi.mock('./promotionReviews.api');
+vi.mock('@n8n/composables/useToast', () => ({ useToast: vi.fn() }));
+
+const headCommitSha = 'a'.repeat(40);
+
+const item = (props: Partial<InboxPromotionReviewItem> = {}): InboxPromotionReviewItem => ({
+	type: 'promotion_review',
+	id: 'rev-1',
+	state: 'open',
+	reviewState: 'open',
+	reviewType: 'gitlab',
+	title: 'Promote the thing',
+	webUrl: 'https://gitlab.example.com/platform/workflows/-/merge_requests/1',
+	branchName: 'n8n-promotion/1',
+	environmentName: 'To production',
+	requester: { id: 'u1', firstName: 'Ada', lastName: 'Lovelace', email: 'ada@example.com' },
+	approver: null,
+	remoteError: null,
+	headCommitSha,
+	runCommitSha: 'c'.repeat(40),
+	hasConflicts: false,
+	createdAt: '2026-01-01T00:00:00.000Z',
+	updatedAt: '2026-01-01T00:00:00.000Z',
+	...props,
+});
+
+const renderComponent = createComponentRenderer(PromotionReviewDetail);
+
+const showError = vi.fn();
+const onItemChange = vi.fn();
+
+/** What the Changes tab reports. The editor renders it, so the test uses a stub. */
+let shownChanges: PromotionChangesState;
+const ChangesStub = defineComponent({
+	props: { reviewId: { type: String, required: true } },
+	emits: ['state'],
+	mounted() {
+		this.$emit('state', shownChanges);
+	},
+	template: '<div data-test-id="promotion-changes-stub">{{ reviewId }}</div>',
+});
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	createTestingPinia();
+	vi.mocked(useToast).mockReturnValue({ showError } as unknown as ReturnType<typeof useToast>);
+	shownChanges = { status: 'ready', headCommitSha };
+	componentRegistry.register('promotion-changes', ChangesStub);
+	onTestFinished(() => componentRegistry.unregister('promotion-changes'));
+});
+
+async function approveInDialog({ getByRole, getByTestId }: ReturnType<typeof renderComponent>) {
+	await userEvent.click(getByTestId('inbox-promotion-review-approve'));
+	await userEvent.click(
+		within(getByRole('dialog')).getByRole('button', { name: 'Approve and merge' }),
+	);
+}
+
+it('shows the title, state, target, requester, and the link to GitLab', () => {
+	const { getByRole, getByText, queryByText } = renderComponent({
+		props: { item: item(), onItemChange },
+	});
+
+	expect(getByRole('heading', { name: 'Promote the thing' })).toBeInTheDocument();
+	expect(getByText('Open')).toBeInTheDocument();
+	expect(getByRole('link', { name: 'Open in GitLab' })).toHaveAttribute(
+		'href',
+		'https://gitlab.example.com/platform/workflows/-/merge_requests/1',
+	);
+	expect(getByText('To production')).toBeInTheDocument();
+	expect(getByText('Ada Lovelace')).toBeInTheDocument();
+	expect(queryByText('Reviewer')).not.toBeInTheDocument();
+});
+
+it('falls back to the branch name, explains why GitLab did not answer, and shows the approver', () => {
+	const { getByRole, getByTestId, getByText, queryByRole, queryByTestId } = renderComponent({
+		props: {
+			item: item({
+				state: 'closed',
+				reviewState: 'merged',
+				title: null,
+				webUrl: null,
+				remoteError: 'not_found',
+				approver: { id: 'u2', firstName: 'Grace', lastName: 'Hopper', email: 'grace@example.com' },
+			}),
+			onItemChange,
+		},
+	});
+
+	expect(getByRole('heading', { name: 'n8n-promotion/1' })).toBeInTheDocument();
+	expect(getByTestId('inbox-promotion-review-remote-error')).toHaveTextContent(
+		"GitLab can't find this merge request.",
+	);
+	expect(queryByRole('link', { name: 'Open in GitLab' })).not.toBeInTheDocument();
+	expect(getByText('Merged')).toBeInTheDocument();
+	expect(getByText('Grace Hopper')).toBeInTheDocument();
+	expect(queryByTestId('inbox-promotion-review-approve')).not.toBeInTheDocument();
+});
+
+it('approves the review the admin confirmed, and locks the dialog until GitLab answers', async () => {
+	const merged = createDeferredPromise<InboxPromotionReviewItem>();
+	vi.mocked(approvePromotionReview).mockReturnValue(merged.promise);
+	const { getByRole, getByTestId, queryByTestId, rerender } = renderComponent({
+		props: { item: item(), onItemChange },
+	});
+	const dialogButton = (name: string) => within(getByRole('dialog')).getByRole('button', { name });
+	expect(queryByTestId('inbox-promotion-review-approve-reason')).not.toBeInTheDocument();
+
+	await userEvent.click(getByTestId('inbox-promotion-review-approve'));
+	await userEvent.click(dialogButton('Cancel'));
+	expect(approvePromotionReview).not.toHaveBeenCalled();
+
+	await userEvent.click(getByTestId('inbox-promotion-review-approve'));
+	await rerender({ item: item({ id: 'rev-2', headCommitSha: 'b'.repeat(40) }), onItemChange });
+	await userEvent.click(dialogButton('Approve and merge'));
+
+	expect(approvePromotionReview).toHaveBeenCalledWith(expect.anything(), 'rev-1', {
+		headCommitSha,
+	});
+	expect(dialogButton('Cancel')).toBeDisabled();
+
+	merged.resolve(
+		item({ state: 'closed', reviewState: 'merged', updatedAt: '2026-01-02T00:00:00.000Z' }),
+	);
+	await waitFor(() =>
+		expect(onItemChange).toHaveBeenCalledWith({
+			type: 'promotion_review',
+			id: 'rev-1',
+			state: 'closed',
+			updatedAt: '2026-01-02T00:00:00.000Z',
+		}),
+	);
+});
+
+it.each([
+	[
+		'a reviewer requested changes',
+		{ reviewState: 'changes_requested' as const },
+		'A reviewer requested changes. Resolve them on GitLab, then reload the Inbox.',
+	],
+	[
+		'the merge request has conflicts',
+		{ hasConflicts: true },
+		'The merge request has conflicts. Resolve them on GitLab.',
+	],
+	[
+		'GitLab did not answer',
+		{ remoteError: 'unreachable' as const, headCommitSha: null },
+		'GitLab unreachable',
+	],
+	[
+		'GitLab did not report the head commit',
+		{ headCommitSha: null },
+		"GitLab didn't report the latest commit of this merge request. Reload the Inbox and try again.",
+	],
+])('disables approve with the reason when %s', (_case, props, reason) => {
+	const { getByTestId } = renderComponent({ props: { item: item(props), onItemChange } });
+
+	const button = getByTestId('inbox-promotion-review-approve');
+	const text = getByTestId('inbox-promotion-review-approve-reason');
+	expect(button).toBeDisabled();
+	expect(text).toHaveTextContent(reason);
+	expect(button).toHaveAttribute('aria-describedby', text.id);
+});
+
+it('shows the error, reloads the list, and enables approve again when the approval fails', async () => {
+	const error = new Error('GitLab: 405 refused');
+	vi.mocked(approvePromotionReview).mockRejectedValue(error);
+	const rendered = renderComponent({ props: { item: item(), onItemChange } });
+
+	await approveInDialog(rendered);
+
+	expect(showError).toHaveBeenCalledWith(error, "Couldn't approve and merge");
+	expect(onItemChange).toHaveBeenCalledWith({ type: 'promotion_review', id: 'rev-1' });
+	expect(rendered.getByTestId('inbox-promotion-review-approve')).toBeEnabled();
+});
+
+it('shows the changes of the review from the shell', () => {
+	const { getByRole, getByTestId } = renderComponent({ props: { item: item(), onItemChange } });
+
+	expect(getByRole('tab', { name: 'Changes' })).toBeInTheDocument();
+	expect(getByTestId('promotion-changes-stub')).toHaveTextContent('rev-1');
+});
+
+it.each([
+	['the changes still load', { status: 'loading' } as const, null],
+	[
+		'the changes could not be shown',
+		{ status: 'unavailable' } as const,
+		"n8n couldn't show the changes of this review. Review and merge it on GitLab.",
+	],
+])('only approves changes that the admin saw: disabled when %s', async (_case, state, reason) => {
+	shownChanges = state;
+
+	const { getByTestId, findByTestId, queryByTestId } = renderComponent({
+		props: { item: item(), onItemChange },
+	});
+
+	if (reason) {
+		expect(await findByTestId('inbox-promotion-review-approve-reason')).toHaveTextContent(reason);
+	} else {
+		expect(queryByTestId('inbox-promotion-review-approve-reason')).not.toBeInTheDocument();
+	}
+	expect(getByTestId('inbox-promotion-review-approve')).toBeDisabled();
+});
+
+it('reloads the changes when GitLab reports new commits, then approves the new head', async () => {
+	const newHead = 'b'.repeat(40);
+	const rendered = renderComponent({
+		props: { item: item({ headCommitSha: newHead }), onItemChange },
+	});
+	const { getByTestId, findByTestId, getByText } = rendered;
+
+	expect(await findByTestId('inbox-promotion-review-new-commits')).toBeInTheDocument();
+	const approve = getByTestId('inbox-promotion-review-approve');
+	expect(approve).toBeDisabled();
+	// The callout above the changes explains why.
+	expect(approve).toHaveAttribute(
+		'aria-describedby',
+		getByText('The merge request has new commits since these changes loaded.').id,
+	);
+
+	shownChanges = { status: 'ready', headCommitSha: newHead };
+	await userEvent.click(getByTestId('inbox-promotion-review-reload-changes'));
+	await approveInDialog(rendered);
+
+	expect(approvePromotionReview).toHaveBeenCalledWith(expect.anything(), 'rev-1', {
+		headCommitSha: newHead,
+	});
+});

package/src/promotions/PromotionReviewDetail.vue

@@ -0,0 +1,395 @@
+<script setup lang="ts">
+import type { InboxPromotionReviewItem, PromotionReviewState } from '@n8n/api-types';
+import { useToast } from '@n8n/composables/useToast';
+import {
+	N8nAvatar,
+	N8nBadge,
+	N8nButton,
+	N8nCallout,
+	N8nDialog,
+	N8nDialogDescription,
+	N8nDialogFooter,
+	N8nDialogHeader,
+	N8nDialogTitle,
+	N8nExternalLink,
+	N8nHeading,
+	N8nTabs,
+	N8nText,
+	type BadgeVariant,
+} from '@n8n/design-system';
+import { componentRegistry, type PromotionChangesState } from '@n8n/frontend-module-sdk';
+import { useI18n } from '@n8n/i18n';
+import { useRootStore } from '@n8n/stores/useRootStore';
+import { computed, ref, useId, watch } from 'vue';
+
+import type { InboxItemChange } from '../inbox.constants';
+import { formatUserDisplayName, toError } from '../reviews/workflowReviews.utils';
+import { approvePromotionReview } from './promotionReviews.api';
+
+const props = defineProps<{
+	item: InboxPromotionReviewItem;
+	onItemChange: (change: InboxItemChange) => void;
+}>();
+const i18n = useI18n();
+const { showError } = useToast();
+const rootStore = useRootStore();
+const disabledReasonId = useId();
+const newCommitsId = useId();
+
+const stateBadge: Record<PromotionReviewState, BadgeVariant> = {
+	open: 'info',
+	changes_requested: 'warning',
+	merged: 'success',
+	closed: 'subtle',
+};
+
+// The editor renders the changes.
+const PromotionChanges = computed(() => componentRegistry.get('promotion-changes'));
+// One tab for now. The bar matches workflow reviews, which also have an Activity tab.
+const tabOptions = computed(() => [
+	{ label: i18n.baseText('inbox.promotionReview.detail.tabs.changes'), value: 'changes' as const },
+]);
+
+// Approve sends the head of the changes that the reviewer saw. A list refresh can report a newer
+// head, which the reviewer did not see.
+const changes = ref<PromotionChangesState>({ status: 'loading' });
+watch(
+	() => props.item.id,
+	() => (changes.value = { status: 'loading' }),
+);
+
+const hasNewCommits = computed(
+	() =>
+		changes.value.status === 'ready' &&
+		!!props.item.headCommitSha &&
+		changes.value.headCommitSha !== props.item.headCommitSha,
+);
+// A new key mounts the Changes tab again, so it loads the newest head.
+const changesKey = ref(0);
+
+/** What the admin confirms. A later change of the selected row does not change it. */
+const pendingApproval = ref<{ id: string; headCommitSha: string } | null>(null);
+const approving = ref(false);
+
+const disabledReason = computed(() => {
+	const { item } = props;
+	if (item.reviewState === 'changes_requested') {
+		return i18n.baseText('inbox.promotionReview.approve.disabled.changesRequested');
+	}
+	if (item.hasConflicts) return i18n.baseText('inbox.promotionReview.approve.disabled.conflicts');
+	if (item.remoteError) {
+		return i18n.baseText(`inbox.promotionReview.remoteError.${item.remoteError}`);
+	}
+	if (!item.headCommitSha) {
+		return i18n.baseText('inbox.promotionReview.approve.disabled.noHeadCommit');
+	}
+	if (changes.value.status === 'unavailable') {
+		return i18n.baseText('inbox.promotionReview.approve.disabled.changesUnavailable');
+	}
+	return null;
+});
+// Loading and new commits show no reason under Approve: loading is short, and the new commits
+// callout above the changes explains itself. Screen readers get that callout as the reason.
+const approveDisabled = computed(
+	() => !!disabledReason.value || hasNewCommits.value || changes.value.status !== 'ready',
+);
+const approveDescribedBy = computed(() => {
+	if (disabledReason.value) return disabledReasonId;
+	return hasNewCommits.value ? newCommitsId : undefined;
+});
+
+function openApproval() {
+	if (changes.value.status !== 'ready') return;
+	pendingApproval.value = { id: props.item.id, headCommitSha: changes.value.headCommitSha };
+}
+
+// A close cannot stop GitLab, so the dialog stays open until the request ends.
+function closeApproval() {
+	if (!approving.value) pendingApproval.value = null;
+}
+
+async function onApprove() {
+	if (!pendingApproval.value || approving.value) return;
+	const { id, headCommitSha } = pendingApproval.value;
+	// The Inbox can reconcile this result after the viewer selects another item.
+	const onItemChange = props.onItemChange;
+	approving.value = true;
+	try {
+		const { state, updatedAt } = await approvePromotionReview(rootStore.restApiContext, id, {
+			headCommitSha,
+		});
+		onItemChange({ type: 'promotion_review', id, state, updatedAt });
+	} catch (error: unknown) {
+		showError(toError(error), i18n.baseText('inbox.promotionReview.approve.error.title'));
+		// Reload the list, so the next attempt uses the current state from GitLab.
+		onItemChange({ type: 'promotion_review', id });
+	} finally {
+		approving.value = false;
+		pendingApproval.value = null;
+	}
+}
+</script>
+
+<template>
+	<section :class="$style.detail" data-test-id="inbox-promotion-review-detail">
+		<header :class="[$style.header, $style.gutter]">
+			<div :class="$style.titleRow">
+				<!-- Inline, so the state tag follows the last word of a title that wraps. -->
+				<div :class="$style.title">
+					<N8nHeading tag="h2" size="xlarge" bold :class="$style.titleText">
+						{{ item.title ?? item.branchName ?? i18n.baseText('inbox.promotionReview.untitled') }}
+					</N8nHeading>
+					<N8nBadge
+						:variant="stateBadge[item.reviewState]"
+						size="xxsmall"
+						:class="$style.stateBadge"
+					>
+						{{ i18n.baseText(`inbox.promotionReview.state.${item.reviewState}`) }}
+					</N8nBadge>
+				</div>
+				<N8nExternalLink
+					v-if="item.webUrl"
+					:class="$style.gitlabLink"
+					:href="item.webUrl"
+					size="small"
+				>
+					{{ i18n.baseText('inbox.promotionReview.detail.openInGitLab') }}
+				</N8nExternalLink>
+			</div>
+			<div :class="$style.meta">
+				<span v-if="item.environmentName" :class="$style.metaItem">
+					<N8nText size="small" color="text-light">
+						{{ i18n.baseText('inbox.promotionReview.detail.promoteTo') }}
+					</N8nText>
+					<N8nText size="small" bold>{{ item.environmentName }}</N8nText>
+				</span>
+				<span v-if="item.approver" :class="$style.metaItem">
+					<N8nText size="small" color="text-light">
+						{{ i18n.baseText('inbox.promotionReview.detail.reviewer') }}
+					</N8nText>
+					<N8nAvatar
+						:first-name="item.approver.firstName"
+						:last-name="item.approver.lastName"
+						size="xsmall"
+					/>
+					<N8nText size="small">{{ formatUserDisplayName(item.approver) }}</N8nText>
+				</span>
+				<span v-if="item.requester" :class="$style.metaItem">
+					<N8nText size="small" color="text-light">
+						{{ i18n.baseText('inbox.promotionReview.detail.requestedBy') }}
+					</N8nText>
+					<N8nAvatar
+						:first-name="item.requester.firstName"
+						:last-name="item.requester.lastName"
+						size="xsmall"
+					/>
+					<N8nText size="small">{{ formatUserDisplayName(item.requester) }}</N8nText>
+				</span>
+			</div>
+		</header>
+		<N8nCallout
+			v-if="item.remoteError"
+			:class="$style.gutter"
+			theme="warning"
+			data-test-id="inbox-promotion-review-remote-error"
+		>
+			{{ i18n.baseText(`inbox.promotionReview.detail.remoteError.${item.remoteError}`) }}
+		</N8nCallout>
+		<div :class="[$style.tabRow, $style.gutter]">
+			<N8nTabs
+				model-value="changes"
+				:options="tabOptions"
+				variant="modern"
+				data-test-id="inbox-promotion-review-tab-bar"
+			/>
+			<!-- In the tab row, like the Review button of workflow reviews. -->
+			<div v-if="item.state === 'open'" :class="$style.approve">
+				<!-- Visible text, not a tooltip: a disabled button cannot take keyboard focus. -->
+				<N8nText
+					v-if="disabledReason"
+					:id="disabledReasonId"
+					size="small"
+					color="text-light"
+					data-test-id="inbox-promotion-review-approve-reason"
+				>
+					{{ disabledReason }}
+				</N8nText>
+				<N8nButton
+					size="small"
+					:disabled="approveDisabled"
+					:loading="approving"
+					:aria-describedby="approveDescribedBy"
+					data-test-id="inbox-promotion-review-approve"
+					@click="openApproval"
+				>
+					{{ i18n.baseText('inbox.promotionReview.approve.button') }}
+				</N8nButton>
+			</div>
+		</div>
+		<div :class="$style.changesArea">
+			<N8nCallout
+				v-if="hasNewCommits"
+				theme="warning"
+				slim
+				:class="[$style.newCommits, $style.gutter]"
+				data-test-id="inbox-promotion-review-new-commits"
+			>
+				<span :id="newCommitsId">{{
+					i18n.baseText('inbox.promotionReview.changes.newCommits')
+				}}</span>
+				<template #trailingContent>
+					<N8nButton
+						variant="outline"
+						size="small"
+						data-test-id="inbox-promotion-review-reload-changes"
+						@click="changesKey++"
+					>
+						{{ i18n.baseText('inbox.promotionReview.changes.reload') }}
+					</N8nButton>
+				</template>
+			</N8nCallout>
+			<component
+				:is="PromotionChanges"
+				:key="changesKey"
+				:class="$style.changes"
+				:review-id="item.id"
+				@state="changes = $event"
+			/>
+		</div>
+		<N8nDialog
+			:open="!!pendingApproval"
+			size="small"
+			:show-close-button="false"
+			:close-on-overlay-click="!approving"
+			:close-on-escape="!approving"
+			@update:open="closeApproval"
+		>
+			<N8nDialogHeader>
+				<N8nDialogTitle>
+					{{ i18n.baseText('inbox.promotionReview.approve.confirm.title') }}
+				</N8nDialogTitle>
+				<N8nDialogDescription>
+					{{ i18n.baseText('inbox.promotionReview.approve.confirm.description') }}
+				</N8nDialogDescription>
+			</N8nDialogHeader>
+			<N8nDialogFooter>
+				<N8nButton
+					variant="outline"
+					:label="i18n.baseText('generic.cancel')"
+					:disabled="approving"
+					@click="closeApproval"
+				/>
+				<N8nButton
+					:label="i18n.baseText('inbox.promotionReview.approve.button')"
+					:loading="approving"
+					@click="onApprove"
+				/>
+			</N8nDialogFooter>
+		</N8nDialog>
+	</section>
+</template>
+
+<style module lang="scss">
+.detail {
+	display: flex;
+	flex: 1;
+	flex-direction: column;
+	gap: var(--spacing--md);
+	min-height: 0;
+}
+
+.tabRow {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--spacing--sm);
+	/* Holds the active-tab indicator, so the border sits under it. */
+	padding-bottom: var(--review-tab-bar--indicator-overhang);
+	border-bottom: var(--border);
+
+	> :global(.n8n-tabs) {
+		transform: translateY(var(--spacing--sm));
+	}
+}
+
+.changesArea {
+	display: flex;
+	flex: 1;
+	flex-direction: column;
+	min-height: 0;
+	/* The tab row border already separates the changes from the header. */
+	margin-top: calc(-1 * var(--spacing--md));
+}
+
+.newCommits {
+	/* The same space as the warnings of the changes. */
+	margin-top: var(--spacing--sm);
+}
+
+.changes {
+	flex: 1;
+	min-height: 0;
+}
+
+/* The right gutter of workflow reviews, so Approve sits where their Review button does. */
+.gutter {
+	margin-right: var(--spacing--md);
+}
+
+.header {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing--xs);
+}
+
+.titleRow {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing--xs);
+	min-width: 0;
+	/* Matches the title row of workflow reviews, so both headings sit at the same height. */
+	min-height: var(--spacing--xl);
+}
+
+.title {
+	flex: 1;
+	min-width: 0;
+	/* The font of the heading, so the tag lines up with the title text. */
+	font-size: var(--font-size--xl);
+	line-height: var(--line-height--sm);
+}
+
+.titleText {
+	display: inline;
+}
+
+.stateBadge {
+	margin-left: var(--spacing--xs);
+	vertical-align: middle;
+}
+
+.approve {
+	display: flex;
+	flex-shrink: 0;
+	align-items: center;
+	gap: var(--spacing--xs);
+}
+
+.gitlabLink {
+	/* A standalone external link takes the font size around it. The text next to it is smaller. */
+	font-size: var(--font-size--sm);
+	white-space: nowrap;
+}
+
+.meta {
+	display: flex;
+	flex-wrap: wrap;
+	gap: var(--spacing--2xs) var(--spacing--lg);
+}
+
+.metaItem {
+	display: inline-flex;
+	align-items: center;
+	gap: var(--spacing--3xs);
+}
+</style>

package/src/promotions/promotionReviews.api.ts

@@ -0,0 +1,15 @@
+import type { ApprovePromotionReviewDto, InboxPromotionReviewItem } from '@n8n/api-types';
+import { makeRestApiRequest, type IRestApiContext } from '@n8n/rest-api-client';
+
+export async function approvePromotionReview(
+	context: IRestApiContext,
+	reviewId: string,
+	payload: ApprovePromotionReviewDto,
+): Promise<InboxPromotionReviewItem> {
+	return await makeRestApiRequest<InboxPromotionReviewItem>(
+		context,
+		'POST',
+		`/promotions/reviews/${encodeURIComponent(reviewId)}/approve`,
+		{ ...payload },
+	);
+}