feat: contribute Messages product surface

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@govoplan/mail-webui",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@govoplan/mail-webui",
-      "version": "0.1.23",
+      "version": "0.1.25",
       "peerDependencies": {
         "@govoplan/core-webui": "^0.1.18",
         "lucide-react": "^1.23.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govoplan/mail-webui",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": true,
   "type": "module",
   "main": "webui/src/index.ts",

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-mail"
-version = "0.1.23"
+version = "0.1.25"
 description = "GovOPlaN mail module with backend and WebUI integration."
 readme = "README.md"
 requires-python = ">=3.12"

src/govoplan_mail/backend/manifest.py

@@ -32,7 +32,9 @@ from govoplan_core.core.modules import (
     ModuleManifest,
     NavItem,
     PermissionDefinition,
+    ProductAvailabilityExplanation,
     ProductAreaContribution,
+    ProductSurfaceContribution,
     QuickAccessTool,
     RoleTemplate,
 )
@@ -445,7 +447,7 @@ POP3_PROVIDER = ExternalProviderDeclaration(
 manifest = ModuleManifest(
     id="mail",
     name="Mail",
-    version="0.1.23",
+    version="0.1.25",
     required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
     optional_dependencies=("campaigns", "addresses", "calendar", "postbox", "search"),
     provides_interfaces=(
@@ -562,6 +564,39 @@ manifest = ModuleManifest(
                 order=40,
             ),
         ),
+        product_surfaces=(
+            ProductSurfaceContribution(
+                id="communication.messages",
+                module_id="mail",
+                label="i18n:govoplan-core.product_surface.messages",
+                description="i18n:govoplan-core.product_surface.messages_description",
+                icon="mail",
+                entry_path="/messages",
+                route_path="/mail",
+                surface_ids=("mail.nav.mail", "mail.route.mail"),
+                presentations=("task", "reader"),
+                search_source_ids=("mail.mailbox_messages",),
+                help_context_ids=("mail.quick_access.messages",),
+                documentation_topic_ids=("mail.quick-access-and-product-area",),
+                required_any=("mail:mailbox:read",),
+                aliases=("/inbox",),
+                order=10,
+                unavailable=ProductAvailabilityExplanation(
+                    reason="authorization",
+                    title="i18n:govoplan-core.product_surface.messages_unavailable",
+                    description="i18n:govoplan-core.product_surface.messages_unavailable_description",
+                    resolution="i18n:govoplan-core.product_surface.messages_unavailable_resolution",
+                    responsible_role="i18n:govoplan-core.access_administrator",
+                ),
+                degraded=ProductAvailabilityExplanation(
+                    reason="provider_degraded",
+                    title="i18n:govoplan-core.product_surface.messages_degraded",
+                    description="i18n:govoplan-core.product_surface.messages_degraded_description",
+                    resolution="i18n:govoplan-core.product_surface.messages_degraded_resolution",
+                    responsible_role="i18n:govoplan-core.integration_operator",
+                ),
+            ),
+        ),
         quick_access_tools=(
             QuickAccessTool(
                 id="mail.messages",
@@ -893,6 +928,9 @@ manifest = ModuleManifest(
             body=(
                 "Mail contributes its full mailbox to Communication. When Quick Access is enabled, its compact provider surface "
                 "appears inside the shared Messages drawer alongside independent Postbox and future chat contributions. "
+                "Mail also contributes to the stable Messages product entry: `/messages` and its migration alias `/inbox` open "
+                "Mail only when its mailbox route is currently authorized and visible in the effective View; otherwise another "
+                "available Messages owner is selected or the shell explains how access can be restored. "
                 "Recent entries open the exact authorized profile, folder, and message; Drafts resolves the configured or "
                 "provider-detected Drafts folder, and the full Mail page keeps the versioned Quick Access return context. "
                 "When an active Case requests a selection, choosing a recent message returns only its tenant-bound profile, "
@@ -914,6 +952,9 @@ manifest = ModuleManifest(
                     "body": (
                         "Mail ordnet das vollständige Postfach Kommunikation zu. Ist der Schnellzugriff aktiviert, erscheint die kompakte "
                         "Mail-Oberfläche gemeinsam mit unabhängigen Beiträgen aus Postbox und künftig Chat unter Nachrichten. "
+                        "Mail trägt außerdem zum stabilen Produkteinstieg Nachrichten bei: `/messages` und der Migrationsalias `/inbox` "
+                        "öffnen Mail nur, wenn die Postfachroute aktuell berechtigt und in der wirksamen View sichtbar ist. Andernfalls "
+                        "wählt die Shell einen anderen verfügbaren Nachrichten-Eigentümer oder erklärt die Wiederherstellung des Zugriffs. "
                         "Aktuelle Einträge öffnen das genaue berechtigte Profil, den Ordner und die Nachricht; Entwürfe verwendet "
                         "den konfigurierten oder vom Anbieter erkannten Entwurfsordner. Die vollständige Mail-Seite erhält den "
                         "versionierten Rücksprungkontext. Verfassen öffnet bewusst die konfigurierte Mail-Anwendung des Benutzers, "

webui/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@govoplan/mail-webui",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@govoplan/mail-webui",
-      "version": "0.1.23",
+      "version": "0.1.25",
       "devDependencies": {
         "typescript": "^5.7.2"
       },

webui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govoplan/mail-webui",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "private": true,
   "type": "module",
   "main": "src/index.ts",

webui/src/features/mail/MailProfileManagement.tsx

@@ -1495,7 +1495,7 @@ function ProfileForm({
       {editTarget.kind === "credentials" &&
       <FormGrid columns={2} gap="small" collapseAt="workspace" className="">
         {creatingCredential &&
-        <FormField label="Reusable credential" documentation={MAIL_PROFILE_WORKFLOW_DOCUMENTATION}>
+        <FormField label="Reusable credential" documentation={MAIL_PROFILE_WORKFLOW_DOCUMENTATION} helpContextId="mail.profiles" helpModuleId="mail">
           <select value={reuseCredentialId} disabled={credentialDisabled} onChange={(event) => setReuseCredentialId(event.target.value)}>
             <option value="">Create a new credential</option>
             {availableCredentials.map((credential) =>
@@ -1509,13 +1509,13 @@ function ProfileForm({
         {creatingCredential && <div />}
         {!reuseCredentialId &&
         <>
-          <FormField label="Credential name" documentation={MAIL_PROFILE_DOCUMENTATION}>
+          <FormField label="Credential name" documentation={MAIL_PROFILE_DOCUMENTATION} helpContextId="mail.profiles" helpModuleId="mail">
             <input value={draft.credentialName} disabled={credentialDisabled} onChange={(event) => setDraft({ ...draft, credentialName: event.target.value })} />
           </FormField>
           <FormField label="Description">
             <input value={draft.credentialDescription} disabled={credentialDisabled} onChange={(event) => setDraft({ ...draft, credentialDescription: event.target.value })} />
           </FormField>
-          <FormField label="Available to modules" help="Choose installed modules. Keep Mail selected to use this credential here.">
+          <FormField label="Available to modules" help="Choose installed modules. Keep Mail selected to use this credential here." helpContextId="mail.profiles" helpModuleId="mail">
             <ReferenceMultiSelect
               values={commaValues(draft.credentialAllowedModules)}
               onChange={(values) => setDraft({ ...draft, credentialAllowedModules: values.join(", ") })}
@@ -1527,7 +1527,9 @@ function ProfileForm({
           </FormField>
           <FormField
             label="Limited to servers"
-            help="Choose an announced server or enter a module-qualified reference. Leave blank for every permitted server.">
+            help="Choose an announced server or enter a module-qualified reference. Leave blank for every permitted server."
+            helpContextId="mail.profiles"
+            helpModuleId="mail">
             <ReferenceMultiSelect
               values={commaValues(draft.credentialAllowedServerRefs)}
               onChange={(values) => setDraft({ ...draft, credentialAllowedServerRefs: values.join(", ") })}
@@ -1540,6 +1542,8 @@ function ProfileForm({
           </FormField>
           <ToggleSwitch
             checked={draft.credentialIsDefault}
+            helpContextId="mail.profiles"
+            helpModuleId="mail"
             disabled={credentialDisabled}
             onChange={(checked) => setDraft({ ...draft, credentialIsDefault: checked })}
             label={`Default credential for this ${editTarget.protocol.toUpperCase()} server`} />

webui/src/module.ts

@@ -1,5 +1,5 @@
 import { createElement, lazy } from "react";
-import type { MailDevMailboxUiCapability, MailProfilesUiCapability, PlatformWebModule, QuickAccessToolsUiCapability } from "@govoplan/core-webui";
+import { messagesProductSurfaceTranslations, type MailDevMailboxUiCapability, type MailProfilesUiCapability, type PlatformWebModule, type QuickAccessToolsUiCapability } from "@govoplan/core-webui";
 import { MailProfilePolicyEditor, MailProfileScopeManager } from "./features/mail/MailProfileManagement";
 import { validateMailPolicy } from "./features/mail/mailPolicyValidation";
 import { mailCredentialReferenceSelectors } from "./features/mail/mailReferenceProviders";
@@ -14,8 +14,8 @@ const mailboxRead = ["mail:mailbox:read"];
 const bounceRead = ["mail:bounce:read", "mail:bounce:manage"];
 const legacyImportAccess = ["mail:pop3:import", "mail:pop3:manage"];
 const translations = {
-  en: generatedTranslations.en,
+  en: { ...generatedTranslations.en, ...messagesProductSurfaceTranslations.en },
-  de: generatedTranslations.de
+  de: { ...generatedTranslations.de, ...messagesProductSurfaceTranslations.de }
 };
 const mailQuickAccessTools: QuickAccessToolsUiCapability = {
   tools: [