@n8n/frontend-module-inbox 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,88 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- Content of branches other than the main branch (i.e. "master") are not licensed.
+- Source code files that contain ".ee." in their filename or ".ee" in their dirname are NOT licensed under
+  the Sustainable Use License.
+  To use source code files that contain ".ee." in their filename or ".ee" in their dirname you must hold a
+	valid n8n Enterprise License specifically allowing you access to such source code files and as defined
+	in "LICENSE_EE.md".
+- All third party components incorporated into the n8n Software are licensed under the original license
+  provided by the owner of the applicable component.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use
+  License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @n8n/frontend-module-inbox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared Inbox lists workflow reviews. Review details, comments, and decisions live in `src/reviews`. The editor supplies only the workflow diff renderer through the SDK component registry. Backend services keep their existing access rules and actions.
+
+Open has two groups: Waiting for review and Authored by you. Each group has its
+own cursor, Load more button, and retry.
+Closed is a flat list with infinite scroll. Group collapse state persists per user.
+
+Review decisions update the loaded rows and counts in place. Approving a selected
+review opens the Closed tab, as before.
+
+Frontend feature module. Consumed from source by the editor-ui shell through
+`src/app/modules.manifest.ts`; there is no build step and no `dist`.
+
+Read the full guide at `packages/@n8n/module-cli/frontend-module-guide.md`. It gives the
+descriptor contract, the registration points and the known problems. This README gives a
+summary only.
+
+```bash
+pnpm turbo typecheck --filter=@n8n/frontend-module-inbox
+pnpm turbo lint --filter=@n8n/frontend-module-inbox
+pnpm turbo lint:styles --filter=@n8n/frontend-module-inbox
+pnpm turbo test --filter=@n8n/frontend-module-inbox
+```
+
+Go through turbo, not `pnpm --filter <pkg> typecheck`: this package is consumed
+from source, and on a cold tree its platform dependencies have not been built
+yet. Turbo builds them first; the bare pnpm form does not.
+
+## Import rules
+
+- Depend on foundation and platform packages only (`@n8n/design-system`,
+  `@n8n/stores`, `@n8n/composables`, `@n8n/i18n`, `@n8n/rest-api-client`,
+  `@n8n/api-types`, `@n8n/permissions`, `@n8n/frontend-constants`, `n8n-workflow`,
+  `@n8n/frontend-module-sdk`). Never import another
+  `@n8n/frontend-module-*`, and never import `@/…` from the shell.
+- `@n8n/stores` and `@n8n/composables` are **subpath-only** — import
+  `@n8n/stores/settings.store`, not `@n8n/stores`.
+- The no-cross-module rule is currently a convention: the shared tsconfig base
+  omits sibling modules from `paths`, which blocks an accidental import but not
+  a deliberate one (declaring the dependency makes it typecheck clean). The
+  ESLint rule that actually enforces it is CAT-3692.
+
+## Adding UI
+
+`vite.config.ts` already carries the three plugins a design-system consumer
+needs, so a `.vue` file compiles in tests without further setup:
+
+- `@vitejs/plugin-vue` — single-file components.
+- `unplugin-icons` — the `~icons/lucide/*` virtual modules behind `N8nIcon`.
+- `vite-svg-loader` — design-system's `custom/*.svg` icon components. Without
+  it an `.svg` import is a data-URI string, which Vue renders as a tag name.
+
+`src/__tests__/design-system-icons.test.ts` renders one icon of each kind, so a
+plugin dropped from `vite.config.ts` fails this package's own suite. Keep that
+test while the module renders any design-system component.
+
+SCSS goes in a scoped `<style lang="scss">` block, with tokens from
+design-system — `stylelint.config.mjs` holds this package to the same rules the
+shell uses. Route components must load lazily.

package/biome.jsonc

@@ -0,0 +1,4 @@
+{
+	"$schema": "../../../../node_modules/@biomejs/biome/configuration_schema.json",
+	"extends": ["../../../../biome.jsonc"]
+}

package/eslint.config.mjs

@@ -0,0 +1,4 @@
+import { defineConfig } from 'eslint/config';
+import { frontendConfig } from '@n8n/eslint-config/frontend';
+
+export default defineConfig(frontendConfig);

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@n8n/frontend-module-inbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@n8n/api-types": "1.44.0",
+    "@n8n/composables": "1.34.0",
+    "@n8n/design-system": "2.43.0",
+    "@n8n/frontend-module-sdk": "0.14.0",
+    "@n8n/i18n": "2.44.0",
+    "@n8n/rest-api-client": "2.44.0",
+    "@n8n/stores": "2.44.0",
+    "n8n-workflow": "2.44.0",
+    "pinia": "^2.2.4",
+    "vue": "^3.5.13",
+    "vue-router": "^4.5.0",
+    "@n8n/frontend-constants": "0.10.0",
+    "@vueuse/core": "^14.3.0",
+    "lodash": "4.18.1",
+    "vue-i18n": "^11.4.4"
+  },
+  "devDependencies": {
+    "@iconify/json": "^2.2.488",
+    "@n8n/eslint-config": "0.0.1",
+    "@n8n/frontend-test-utils": "0.1.0",
+    "@n8n/frontend-vite-config": "0.1.0",
+    "@n8n/playwright-janitor": "0.1.0",
+    "@n8n/stylelint-config": "0.0.1",
+    "@n8n/typescript-config": "1.12.0",
+    "@n8n/vitest-config": "1.24.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/vue": "^8.1.0",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "eslint": "9.29.0",
+    "stylelint": "^16.23.0",
+    "typescript": "6.0.2",
+    "unplugin-icons": "^23.0.1",
+    "vite": "^8.0.2",
+    "vite-svg-loader": "5.1.0",
+    "vitest": "5.0.1",
+    "vue-tsc": "^2.2.8",
+    "@pinia/testing": "^0.1.6",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/lodash": "4.17.17",
+    "@n8n/utils": "1.51.0"
+  },
+  "license": "LicenseRef-n8n-sustainable-use",
+  "scripts": {
+    "clean": "rimraf .turbo",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "test:changed": "janitor test-scoped",
+    "test:dev": "vitest",
+    "lint": "eslint src --quiet",
+    "lint:fix": "eslint src --fix",
+    "lint:styles": "stylelint \"src/**/*.{scss,sass,vue}\" --cache --allow-empty-input",
+    "lint:styles:fix": "stylelint \"src/**/*.{scss,sass,vue}\" --fix --cache --allow-empty-input",
+    "format": "biome format --write . && prettier --write . --ignore-path ../../../../.prettierignore",
+    "format:check": "biome ci . && prettier --check . --ignore-path ../../../../.prettierignore"
+  }
 }

package/src/__tests__/design-system-icons.test.ts

@@ -0,0 +1,24 @@
+import { N8nIcon } from '@n8n/design-system';
+import { render } from '@testing-library/vue';
+
+/**
+ * A build-config test, not a feature test. `@n8n/design-system` is consumed from source, so its
+ * two icon mechanisms are this package's problem, and each package carries its own
+ * `vite.config.ts`. Both cases fail loudly when a plugin goes missing from that file:
+ *
+ *   - `box` comes from `~icons/lucide/box`, which only `unplugin-icons` resolves.
+ *   - `webhook` comes from `custom/webhook.svg`, which only `svgLoader` turns into a component.
+ *     Without it the import is a data-URI string, which Vue renders as a tag name.
+ *
+ * Keep this test while the module renders any design-system component.
+ */
+describe('design-system icons', () => {
+	it.each([
+		['a lucide icon', 'box'],
+		['a custom svg icon', 'webhook'],
+	])('renders %s', (_case, icon) => {
+		const { container } = render(N8nIcon, { props: { icon } });
+
+		expect(container.querySelector('svg')).not.toBeNull();
+	});
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,4 @@
+// The shared frontend test harness: the jsdom environment, english messages, and a fresh pinia
+// per test. It lives in `@n8n/frontend-test-utils` rather than in `@n8n/vitest-config`, because
+// `@n8n/i18n` devDepends on the latter and importing i18n there closes a cycle in the turbo graph.
+import '@n8n/frontend-test-utils/setup';

package/src/components/InboxEmptyState.vue

@@ -0,0 +1,86 @@
+<script setup lang="ts">
+import { N8nEmptyState, N8nLoading, type EmptyStateIconCards } from '@n8n/design-system';
+import { useI18n } from '@n8n/i18n';
+import { storeToRefs } from 'pinia';
+import { computed } from 'vue';
+
+import { useInboxStore } from '../inbox.store';
+
+const store = useInboxStore();
+const {
+	activeTab,
+	hasItems,
+	loading,
+	initialLoadFailed,
+	partial,
+	isEmpty,
+	openCount,
+	closedCount,
+} = storeToRefs(store);
+const i18n = useI18n();
+const alertIcon = { type: 'icon', value: 'circle-alert' } as const;
+const inboxIcon: EmptyStateIconCards = {
+	type: 'cards',
+	center: 'message-square-text',
+	sides: ['file-diff', 'git-branch', 'circle-check', 'list', 'message-square'],
+};
+const noSelectionHeading = computed(() => {
+	const count = activeTab.value === 'closed' ? closedCount.value : openCount.value;
+	if (count === null) return i18n.baseText(`inbox.items.${activeTab.value}`);
+	return i18n.baseText(`inbox.noSelection.title.${activeTab.value}`, {
+		adjustToNumber: count,
+		interpolate: { count: String(count) },
+	});
+});
+</script>
+
+<template>
+	<N8nLoading v-if="loading" :loading="true" :rows="3" />
+	<div v-else :class="$style.emptyStateWrapper">
+		<N8nEmptyState
+			v-if="initialLoadFailed && !hasItems"
+			:class="$style.emptyState"
+			:icon="alertIcon"
+			:heading="i18n.baseText('workflowReviews.error.load')"
+			:button-text="i18n.baseText('generic.retry')"
+			@click:button="store.fetchActiveTab()"
+		/>
+		<N8nEmptyState
+			v-else-if="partial && !hasItems"
+			:class="$style.emptyState"
+			:icon="alertIcon"
+			:heading="i18n.baseText('inbox.partial')"
+			:button-text="i18n.baseText('generic.retry')"
+			@click:button="store.refreshListAndSummary()"
+		/>
+		<N8nEmptyState
+			v-else-if="isEmpty"
+			:class="$style.emptyState"
+			:icon="inboxIcon"
+			:heading="i18n.baseText(activeTab === 'open' ? 'inbox.empty.open' : 'inbox.empty.closed')"
+			:description="i18n.baseText(`inbox.empty.body.${activeTab}`)"
+			data-test-id="inbox-empty"
+		/>
+		<N8nEmptyState
+			v-else-if="hasItems"
+			:class="$style.emptyState"
+			:icon="inboxIcon"
+			:heading="noSelectionHeading"
+			:description="i18n.baseText('inbox.noSelection.body')"
+		/>
+	</div>
+</template>
+
+<style lang="scss" module>
+.emptyStateWrapper {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	height: 100%;
+}
+
+.emptyStateWrapper .emptyState {
+	border: none;
+	padding: 0;
+}
+</style>

package/src/components/InboxList.test.ts

@@ -0,0 +1,229 @@
+import type { InboxWorkflowReviewItem } from '@n8n/api-types';
+import { createComponentRenderer } from '@n8n/frontend-test-utils';
+import { useUsersStore } from '@n8n/stores/users.store';
+import { fireEvent, within } from '@testing-library/vue';
+import { useIntersectionObserver } from '@vueuse/core';
+
+import InboxList from './InboxList.vue';
+import type { InboxListSection } from './InboxListSection.vue';
+
+vi.mock('@vueuse/core', async (importOriginal) => ({
+	...(await importOriginal<typeof import('@vueuse/core')>()),
+	useIntersectionObserver: vi.fn(),
+}));
+
+function section(
+	key: InboxListSection['key'],
+	props: Partial<InboxListSection> = {},
+): InboxListSection {
+	return {
+		key,
+		items: [],
+		loading: false,
+		loadingMore: false,
+		hasMore: false,
+		error: null,
+		failedRequest: null,
+		partial: false,
+		...props,
+	};
+}
+function review(): InboxWorkflowReviewItem {
+	return {
+		type: 'workflow_review',
+		id: 'review',
+		state: 'open',
+		decision: 'pending',
+		projectId: 'project',
+		title: 'Review my workflow',
+		workflowName: 'My workflow',
+		workflowVersionId: null,
+		requester: null,
+		authors: [],
+		reviewers: [],
+		createdAt: '2026-01-01T00:00:00.000Z',
+		updatedAt: '2026-01-01T00:00:00.000Z',
+	};
+}
+const renderComponent = createComponentRenderer(InboxList, {
+	props: {
+		sections: [section('waiting'), section('authored')],
+		activeTab: 'open',
+		selectedKey: null,
+		openCount: null,
+		closedCount: null,
+	},
+});
+beforeEach(() => localStorage.clear());
+function intersect(isIntersecting = true) {
+	const onIntersect = vi.mocked(useIntersectionObserver).mock.calls.at(-1)![1];
+	onIntersect([{ isIntersecting } as IntersectionObserverEntry], {} as IntersectionObserver);
+}
+
+it('shows one initial skeleton without empty group headers', () => {
+	const { getAllByTestId, queryByTestId } = renderComponent({
+		props: {
+			sections: [section('waiting', { loading: true }), section('authored', { loading: true })],
+		},
+	});
+	expect(getAllByTestId('inbox-list-skeleton')).toHaveLength(1);
+	expect(queryByTestId('inbox-section-header')).not.toBeInTheDocument();
+});
+it('offers one retry when the first load fails without rows', () => {
+	const { getAllByRole, queryByTestId, emitted } = renderComponent({
+		props: {
+			sections: [
+				section('waiting', { error: new Error('Request failed'), failedRequest: 'list' }),
+				section('authored', { error: new Error('Request failed'), failedRequest: 'list' }),
+			],
+		},
+	});
+	const buttons = getAllByRole('button', { name: 'Retry' });
+	expect(buttons).toHaveLength(1);
+	buttons[0].click();
+	expect(emitted('retryActiveTab')).toEqual([[]]);
+	expect(queryByTestId('inbox-section-header')).not.toBeInTheDocument();
+});
+it('retries the failed page after all loaded rows leave the list', () => {
+	const { getByRole, emitted } = renderComponent({
+		props: {
+			sections: [
+				section('waiting', {
+					hasMore: true,
+					error: new Error('Page failed'),
+					failedRequest: 'loadMore',
+				}),
+				section('authored'),
+			],
+		},
+	});
+	getByRole('button', { name: 'Retry' }).click();
+	expect(emitted('retry')).toEqual([['waiting']]);
+	expect(emitted('retryActiveTab')).toBeUndefined();
+	expect(getByRole('button', { name: 'Waiting for your review' })).toBeInTheDocument();
+});
+it('keeps healthy rows visible beside a failed group', () => {
+	const { queryByRole, getByRole, emitted } = renderComponent({
+		props: {
+			sections: [
+				section('waiting', { items: [review()] }),
+				section('authored', { error: new Error('Request failed') }),
+			],
+		},
+	});
+	expect(getByRole('option')).toHaveTextContent('Review my workflow');
+	getByRole('button', { name: 'Retry' }).click();
+	expect(emitted('retry')).toEqual([['authored']]);
+	expect(queryByRole('button', { name: 'Load more' })).not.toBeInTheDocument();
+});
+it('hides settled empty group headers', () => {
+	const { queryByTestId } = renderComponent();
+	expect(queryByTestId('inbox-section-header')).not.toBeInTheDocument();
+});
+it('keeps a partial empty group visible with its own retry', () => {
+	const { getByRole, emitted } = renderComponent({
+		props: { sections: [section('waiting', { partial: true }), section('authored')] },
+	});
+	expect(getByRole('button', { name: 'Waiting for your review' })).toBeInTheDocument();
+	getByRole('button', { name: 'Retry' }).click();
+	expect(emitted('refreshSection')).toEqual([['waiting']]);
+});
+it('collapses groups without requesting more data', async () => {
+	const { getByRole, queryByRole, emitted } = renderComponent({
+		props: { sections: [section('waiting', { items: [review()] })] },
+	});
+	const header = getByRole('button', { name: 'Waiting for your review' });
+	await fireEvent.click(header);
+	expect(header).toHaveAttribute('aria-expanded', 'false');
+	expect(queryByRole('option')).not.toBeInTheDocument();
+	await fireEvent.click(header);
+	expect(getByRole('option')).toHaveTextContent('Review my workflow');
+	expect(emitted('loadMore')).toBeUndefined();
+});
+it('uses the impersonal waiting label for administrators', () => {
+	vi.spyOn(useUsersStore(), 'isAdminOrOwner', 'get').mockReturnValue(true);
+	const { getByRole } = renderComponent({
+		props: { sections: [section('waiting', { items: [review()] })] },
+	});
+	expect(getByRole('button', { name: 'Waiting for review' })).toBeInTheDocument();
+});
+it('keeps loading open groups explicit and identifies the group', () => {
+	const { emitted, getByRole } = renderComponent({
+		props: { sections: [section('authored', { hasMore: true })] },
+	});
+	intersect();
+	expect(emitted('loadMore')).toBeUndefined();
+	getByRole('button', { name: 'Load more' }).click();
+	expect(emitted('loadMore')).toEqual([['authored']]);
+});
+it('loads Closed at the bottom without group headers or a Load more button', () => {
+	const { emitted, queryByRole, queryByTestId } = renderComponent({
+		props: { activeTab: 'closed', sections: [section('closed', { hasMore: true })] },
+	});
+	intersect(false);
+	expect(emitted('loadMore')).toBeUndefined();
+	intersect();
+	expect(emitted('loadMore')).toEqual([['closed']]);
+	expect(queryByRole('button', { name: 'Load more' })).not.toBeInTheDocument();
+	expect(queryByTestId('inbox-section-header')).not.toBeInTheDocument();
+});
+it.each([{ loading: true }, { loadingMore: true }, { hasMore: false }])(
+	'does not automatically load Closed with %o',
+	(props) => {
+		const { emitted } = renderComponent({
+			props: { activeTab: 'closed', sections: [section('closed', { hasMore: true, ...props })] },
+		});
+		intersect();
+		expect(emitted('loadMore')).toBeUndefined();
+	},
+);
+it('waits for Retry after a failed Closed page and removes the sentinel on Open', async () => {
+	const closed = section('closed', { hasMore: true, items: [{ ...review(), state: 'closed' }] });
+	const { rerender, emitted } = renderComponent({
+		props: { activeTab: 'closed', sections: [closed] },
+	});
+	const target = vi.mocked(useIntersectionObserver).mock.calls.at(-1)![0];
+	expect(target).not.toHaveProperty('value', null);
+	intersect();
+	await rerender({ sections: [{ ...closed, loadingMore: true }] });
+	expect(target).toHaveProperty('value', null);
+	intersect();
+	expect(emitted('loadMore')).toHaveLength(1);
+	await rerender({
+		sections: [{ ...closed, error: new Error('Page failed') }],
+	});
+	expect(target).toHaveProperty('value', null);
+	intersect();
+	expect(emitted('loadMore')).toHaveLength(1);
+	await rerender({ sections: [closed] });
+	expect(target).not.toHaveProperty('value', null);
+	intersect();
+	expect(emitted('loadMore')).toHaveLength(2);
+	await rerender({ activeTab: 'open', sections: [section('waiting')] });
+	expect(target).toHaveProperty('value', null);
+});
+it('separates partial-source recovery from a failed page retry', () => {
+	const { getByTestId, emitted } = renderComponent({
+		props: { sections: [section('waiting', { partial: true, error: new Error('Page failed') })] },
+	});
+	within(getByTestId('inbox-partial')).getByRole('button', { name: 'Retry' }).click();
+	expect(emitted('refreshSection')).toEqual([['waiting']]);
+	expect(emitted('retry')).toBeUndefined();
+	within(getByTestId('inbox-list-error')).getByRole('button', { name: 'Retry' }).click();
+	expect(emitted('retry')).toEqual([['waiting']]);
+});
+
+it('keeps review selection and keyboard activation across the extracted row', async () => {
+	const item = review();
+	const { getByRole, emitted } = renderComponent({
+		props: {
+			selectedKey: `${item.type}:${item.id}`,
+			sections: [section('waiting', { items: [item] })],
+		},
+	});
+	const row = getByRole('option', { selected: true });
+	expect(row).toHaveTextContent(item.title);
+	await fireEvent.keyDown(row, { key: 'Enter' });
+	await fireEvent.keyDown(row, { key: ' ' });
+	expect(emitted('select')).toEqual([[item], [item]]);
+});