From c989d8f1fd1182aee3504a1eb8840f0e28be105e Mon Sep 17 00:00:00 2001
From: James Brunton <james@stirlingpdf.com>
Date: Thu, 14 Aug 2025 14:48:05 +0100
Subject: [PATCH] Improve titles, headers and tooltips in Add Password and
 Change Permissions

---
 .../public/locales/en-GB/translation.json     | 25 +++++------
 .../public/locales/en-US/translation.json     | 19 ++++----
 .../addPassword/AddPasswordSettings.test.tsx  |  6 +--
 .../tools/addPassword/AddPasswordSettings.tsx |  4 +-
 .../ChangePermissionsSettings.test.tsx        | 44 ++++++-------------
 .../ChangePermissionsSettings.tsx             |  4 +-
 .../tooltips/useAddPasswordPermissionsTips.ts | 17 +++++++
 .../components/tooltips/useAddPasswordTips.ts |  4 --
 .../tooltips/useChangePermissionsTips.ts      |  7 ++-
 frontend/src/tools/AddPassword.tsx            |  7 ++-
 frontend/src/tools/ChangePermissions.tsx      |  2 +-
 11 files changed, 67 insertions(+), 72 deletions(-)
 create mode 100644 frontend/src/components/tooltips/useAddPasswordPermissionsTips.ts

diff --git a/frontend/public/locales/en-GB/translation.json b/frontend/public/locales/en-GB/translation.json
index 247162df3..fce197c76 100644
--- a/frontend/public/locales/en-GB/translation.json
+++ b/frontend/public/locales/en-GB/translation.json
@@ -1786,9 +1786,8 @@
     "error": {
       "failed": "An error occurred while encrypting the PDF."
     },
+    "title": "Passwords & Encryption",
     "passwords": {
-      "title": "Passwords",
-      "stepTitle": "Passwords & Encryption",
       "completed": "Passwords configured",
       "user": {
         "label": "User Password",
@@ -1799,13 +1798,9 @@
         "placeholder": "Enter owner password"
       }
     },
-    "permissions": {
-      "stepTitle": "Document Permissions"
-    },
     "encryption": {
-      "title": "Encryption",
       "keyLength": {
-        "label": "Key Length",
+        "label": "Encryption Key Length",
         "40bit": "40-bit (Low)",
         "128bit": "128-bit (Standard)",
         "256bit": "256-bit (High)"
@@ -1831,20 +1826,19 @@
         "bullet2": "128-bit: Standard security, widely supported",
         "bullet3": "256-bit: Maximum security, requires modern viewers"
       },
-      "restrictions": {
-        "title": "Document Restrictions",
-        "text": "These restrictions control what users can do with the PDF. Most effective when combined with an owner password."
+      "permissions": {
+        "text": "These permissions control what users can do with the PDF. Most effective when combined with an owner password."
       }
     }
   },
   "changePermissions": {
     "completed": "Permissions changed",
     "submit": "Change Permissions",
+    "title": "Document Permissions",
     "error": {
       "failed": "An error occurred while changing PDF permissions."
     },
-    "restrictions": {
-      "title": "Document Restrictions",
+    "permissions": {
       "preventAssembly": {
         "label": "Prevent assembly of document"
       },
@@ -1878,8 +1872,11 @@
         "title": "Change Permissions"
       },
       "description": {
-        "title": "Description",
-        "text": "Changes document permissions. Warning: To make these restrictions unchangeable, use the Add Password tool to set an owner password."
+        "text": "Changes document permissions, allowing/disallowing access to different features in PDF readers."
+      },
+      "warning": {
+        "title": "Warning",
+        "text": "To make these permissions unchangeable, use the Add Password tool to set an owner password."
       }
     }
   }
diff --git a/frontend/public/locales/en-US/translation.json b/frontend/public/locales/en-US/translation.json
index 641acf013..887f430d3 100644
--- a/frontend/public/locales/en-US/translation.json
+++ b/frontend/public/locales/en-US/translation.json
@@ -1655,9 +1655,8 @@
       "stepTitle": "Document Permissions"
     },
     "encryption": {
-      "title": "Encryption",
       "keyLength": {
-        "label": "Key Length",
+        "label": "Encryption Key Length",
         "40bit": "40-bit (Low)",
         "128bit": "128-bit (Standard)",
         "256bit": "256-bit (High)"
@@ -1683,20 +1682,19 @@
         "bullet2": "128-bit: Standard security, widely supported",
         "bullet3": "256-bit: Maximum security, requires modern viewers"
       },
-      "restrictions": {
-        "title": "Document Restrictions",
-        "text": "These restrictions control what users can do with the PDF. Most effective when combined with an owner password."
+      "permissions": {
+        "text": "These permissions control what users can do with the PDF. Most effective when combined with an owner password."
       }
     }
   },
   "changePermissions": {
     "completed": "Permissions changed",
     "submit": "Change Permissions",
+    "title": "Document Permissions",
     "error": {
       "failed": "An error occurred while changing PDF permissions."
     },
-    "restrictions": {
-      "title": "Document Restrictions",
+    "permissions": {
       "preventAssembly": {
         "label": "Prevent assembly of document"
       },
@@ -1730,8 +1728,11 @@
         "title": "Change Permissions"
       },
       "description": {
-        "title": "Description",
-        "text": "Changes document permissions. Warning: To make these restrictions unchangeable, use the Add Password tool to set an owner password."
+        "text": "Changes document permissions, allowing/disallowing access to different features in PDF readers."
+      },
+      "warning": {
+        "title": "Warning",
+        "text": "To make these permissions unchangeable, use the Add Password tool to set an owner password."
       }
     }
   }
diff --git a/frontend/src/components/tools/addPassword/AddPasswordSettings.test.tsx b/frontend/src/components/tools/addPassword/AddPasswordSettings.test.tsx
index ac4b000f2..92373f60d 100644
--- a/frontend/src/components/tools/addPassword/AddPasswordSettings.test.tsx
+++ b/frontend/src/components/tools/addPassword/AddPasswordSettings.test.tsx
@@ -63,8 +63,8 @@ describe('AddPasswordSettings', () => {
     );
 
     // Check that main section titles are rendered
-    expect(screen.getByText('mock-addPassword.passwords.title')).toBeInTheDocument();
-    expect(screen.getByText('mock-addPassword.encryption.title')).toBeInTheDocument();
+    expect(screen.getByText('mock-addPassword.passwords.user.label')).toBeInTheDocument();
+    expect(screen.getByText('mock-addPassword.encryption.keyLength.label')).toBeInTheDocument();
   });
 
   test('should call onParameterChange when password fields are modified', () => {
@@ -154,8 +154,6 @@ describe('AddPasswordSettings', () => {
     );
 
     // Verify that translation keys are being called
-    expect(mockT).toHaveBeenCalledWith('addPassword.passwords.title', 'Passwords');
-    expect(mockT).toHaveBeenCalledWith('addPassword.encryption.title', 'Encryption');
     expect(mockT).toHaveBeenCalledWith('addPassword.passwords.user.label', 'User Password');
     expect(mockT).toHaveBeenCalledWith('addPassword.passwords.owner.label', 'Owner Password');
   });
diff --git a/frontend/src/components/tools/addPassword/AddPasswordSettings.tsx b/frontend/src/components/tools/addPassword/AddPasswordSettings.tsx
index 6cce5ef0c..96ce6aad5 100644
--- a/frontend/src/components/tools/addPassword/AddPasswordSettings.tsx
+++ b/frontend/src/components/tools/addPassword/AddPasswordSettings.tsx
@@ -16,7 +16,6 @@ const AddPasswordSettings = ({ parameters, onParameterChange, disabled = false }
     <Stack gap="md">
       {/* Password Settings */}
       <Stack gap="sm">
-        <Text size="sm" fw={500}>{t('addPassword.passwords.title', 'Passwords')}</Text>
         <PasswordInput
           label={t('addPassword.passwords.user.label', 'User Password')}
           placeholder={t('addPassword.passwords.user.placeholder', 'Enter user password')}
@@ -35,9 +34,8 @@ const AddPasswordSettings = ({ parameters, onParameterChange, disabled = false }
 
       {/* Encryption Settings */}
       <Stack gap="sm">
-        <Text size="sm" fw={500}>{t('addPassword.encryption.title', 'Encryption')}</Text>
         <Select
-          label={t('addPassword.encryption.keyLength.label', 'Key Length')}
+          label={t('addPassword.encryption.keyLength.label', 'Encryption Key Length')}
           value={parameters.keyLength.toString()}
           onChange={(value) => {
             if (value) {
diff --git a/frontend/src/components/tools/changePermissions/ChangePermissionsSettings.test.tsx b/frontend/src/components/tools/changePermissions/ChangePermissionsSettings.test.tsx
index 51986266c..d126c7d31 100644
--- a/frontend/src/components/tools/changePermissions/ChangePermissionsSettings.test.tsx
+++ b/frontend/src/components/tools/changePermissions/ChangePermissionsSettings.test.tsx
@@ -23,19 +23,6 @@ describe('ChangePermissionsSettings', () => {
     vi.clearAllMocks();
   });
 
-  test('should render section title', () => {
-    render(
-      <TestWrapper>
-        <ChangePermissionsSettings
-          parameters={defaultParameters}
-          onParameterChange={mockOnParameterChange}
-        />
-      </TestWrapper>
-    );
-
-    expect(screen.getByText('mock-changePermissions.restrictions.title')).toBeInTheDocument();
-  });
-
   test('should render all permission checkboxes', () => {
     render(
       <TestWrapper>
@@ -52,10 +39,10 @@ describe('ChangePermissionsSettings', () => {
     expect(checkboxes).toHaveLength(permissionKeys.length);
 
     // Verify specific permission labels are rendered
-    expect(screen.getByText('mock-changePermissions.restrictions.preventAssembly.label')).toBeInTheDocument();
-    expect(screen.getByText('mock-changePermissions.restrictions.preventPrinting.label')).toBeInTheDocument();
-    expect(screen.getByText('mock-changePermissions.restrictions.preventModify.label')).toBeInTheDocument();
-    expect(screen.getByText('mock-changePermissions.restrictions.preventExtractContent.label')).toBeInTheDocument();
+    expect(screen.getByText('mock-changePermissions.permissions.preventAssembly.label')).toBeInTheDocument();
+    expect(screen.getByText('mock-changePermissions.permissions.preventPrinting.label')).toBeInTheDocument();
+    expect(screen.getByText('mock-changePermissions.permissions.preventModify.label')).toBeInTheDocument();
+    expect(screen.getByText('mock-changePermissions.permissions.preventExtractContent.label')).toBeInTheDocument();
   });
 
   test('should render all permission types with correct labels', () => {
@@ -71,7 +58,7 @@ describe('ChangePermissionsSettings', () => {
     const permissionKeys = Object.keys(defaultParameters) as Array<keyof ChangePermissionsParameters>;
 
     permissionKeys.forEach(permission => {
-      expect(screen.getByText(`mock-changePermissions.restrictions.${permission}.label`)).toBeInTheDocument();
+      expect(screen.getByText(`mock-changePermissions.permissions.${permission}.label`)).toBeInTheDocument();
     });
   });
 
@@ -109,10 +96,10 @@ describe('ChangePermissionsSettings', () => {
     );
 
     // Find specific checkboxes by their labels and verify they are checked
-    const assemblyCheckbox = screen.getByLabelText('mock-changePermissions.restrictions.preventAssembly.label') as HTMLInputElement;
-    const printingCheckbox = screen.getByLabelText('mock-changePermissions.restrictions.preventPrinting.label') as HTMLInputElement;
-    const modifyCheckbox = screen.getByLabelText('mock-changePermissions.restrictions.preventModify.label') as HTMLInputElement;
-    const formCheckbox = screen.getByLabelText('mock-changePermissions.restrictions.preventFillInForm.label') as HTMLInputElement;
+    const assemblyCheckbox = screen.getByLabelText('mock-changePermissions.permissions.preventAssembly.label') as HTMLInputElement;
+    const printingCheckbox = screen.getByLabelText('mock-changePermissions.permissions.preventPrinting.label') as HTMLInputElement;
+    const modifyCheckbox = screen.getByLabelText('mock-changePermissions.permissions.preventModify.label') as HTMLInputElement;
+    const formCheckbox = screen.getByLabelText('mock-changePermissions.permissions.preventFillInForm.label') as HTMLInputElement;
 
     expect(assemblyCheckbox.checked).toBe(true);
     expect(printingCheckbox.checked).toBe(true);
@@ -138,7 +125,7 @@ describe('ChangePermissionsSettings', () => {
       </TestWrapper>
     );
 
-    const assemblyCheckbox = screen.getByLabelText('mock-changePermissions.restrictions.preventAssembly.label');
+    const assemblyCheckbox = screen.getByLabelText('mock-changePermissions.permissions.preventAssembly.label');
     fireEvent.click(assemblyCheckbox);
 
     expect(mockOnParameterChange).toHaveBeenCalledWith('preventAssembly', expectedValue);
@@ -155,8 +142,8 @@ describe('ChangePermissionsSettings', () => {
     );
 
     // Click multiple checkboxes
-    const assemblyCheckbox = screen.getByLabelText('mock-changePermissions.restrictions.preventAssembly.label');
-    const printingCheckbox = screen.getByLabelText('mock-changePermissions.restrictions.preventPrinting.label');
+    const assemblyCheckbox = screen.getByLabelText('mock-changePermissions.permissions.preventAssembly.label');
+    const printingCheckbox = screen.getByLabelText('mock-changePermissions.permissions.preventPrinting.label');
 
     fireEvent.click(assemblyCheckbox);
     fireEvent.click(printingCheckbox);
@@ -196,12 +183,9 @@ describe('ChangePermissionsSettings', () => {
       </TestWrapper>
     );
 
-    // Verify that translation keys are being called
-    expect(mockT).toHaveBeenCalledWith('changePermissions.restrictions.title', 'Document Restrictions');
-
     const permissionKeys = Object.keys(defaultParameters) as Array<keyof ChangePermissionsParameters>;
     permissionKeys.forEach(permission => {
-      expect(mockT).toHaveBeenCalledWith(`changePermissions.restrictions.${permission}.label`, permission);
+      expect(mockT).toHaveBeenCalledWith(`changePermissions.permissions.${permission}.label`, permission);
     });
   });
 
@@ -220,7 +204,7 @@ describe('ChangePermissionsSettings', () => {
       </TestWrapper>
     );
 
-    const checkbox = screen.getByLabelText(`mock-changePermissions.restrictions.${permission}.label`) as HTMLInputElement;
+    const checkbox = screen.getByLabelText(`mock-changePermissions.permissions.${permission}.label`) as HTMLInputElement;
     expect(checkbox.checked).toBe(true);
   });
 });
diff --git a/frontend/src/components/tools/changePermissions/ChangePermissionsSettings.tsx b/frontend/src/components/tools/changePermissions/ChangePermissionsSettings.tsx
index 5f3c2d6a8..1090bd11f 100644
--- a/frontend/src/components/tools/changePermissions/ChangePermissionsSettings.tsx
+++ b/frontend/src/components/tools/changePermissions/ChangePermissionsSettings.tsx
@@ -13,13 +13,11 @@ const ChangePermissionsSettings = ({ parameters, onParameterChange, disabled = f
 
   return (
     <Stack gap="sm">
-      <Text size="sm" fw={500}>{t('changePermissions.restrictions.title', 'Document Restrictions')}</Text>
-
       <Stack gap="xs">
         {(Object.keys(parameters) as Array<keyof ChangePermissionsParameters>).map((key) => (
           <Checkbox
             key={key}
-            label={t(`changePermissions.restrictions.${key}.label`, key)}
+            label={t(`changePermissions.permissions.${key}.label`, key)}
             checked={parameters[key]}
             onChange={(e) => onParameterChange(key, e.target.checked)}
             disabled={disabled}
diff --git a/frontend/src/components/tooltips/useAddPasswordPermissionsTips.ts b/frontend/src/components/tooltips/useAddPasswordPermissionsTips.ts
new file mode 100644
index 000000000..b521e7045
--- /dev/null
+++ b/frontend/src/components/tooltips/useAddPasswordPermissionsTips.ts
@@ -0,0 +1,17 @@
+import { useTranslation } from 'react-i18next';
+import { TooltipContent } from '../../types/tips';
+
+export const useAddPasswordPermissionsTips = (): TooltipContent => {
+  const { t } = useTranslation();
+
+  return {
+    header: {
+      title: t("addPassword.tooltip.permissions.title", "Document Permissions")
+    },
+    tips: [
+      {
+        description: t("addPassword.tooltip.permissions.text", "These permissions control what users can do with the PDF. Most effective when combined with an owner password."),
+      }
+    ]
+  };
+};
diff --git a/frontend/src/components/tooltips/useAddPasswordTips.ts b/frontend/src/components/tooltips/useAddPasswordTips.ts
index c47b8d0ee..ea699152b 100644
--- a/frontend/src/components/tooltips/useAddPasswordTips.ts
+++ b/frontend/src/components/tooltips/useAddPasswordTips.ts
@@ -26,10 +26,6 @@ export const useAddPasswordTips = (): TooltipContent => {
           t("addPassword.tooltip.encryption.bullet3", "256-bit: Maximum security, requires modern viewers")
         ]
       },
-      {
-        title: t("addPassword.tooltip.restrictions.title", "Document Restrictions"),
-        description: t("addPassword.tooltip.restrictions.text", "These restrictions control what users can do with the PDF. Most effective when combined with an owner password."),
-      }
     ]
   };
 };
diff --git a/frontend/src/components/tooltips/useChangePermissionsTips.ts b/frontend/src/components/tooltips/useChangePermissionsTips.ts
index 533a21b84..14f6544a6 100644
--- a/frontend/src/components/tooltips/useChangePermissionsTips.ts
+++ b/frontend/src/components/tooltips/useChangePermissionsTips.ts
@@ -10,8 +10,11 @@ export const useChangePermissionsTips = (): TooltipContent => {
     },
     tips: [
       {
-        title: t("changePermissions.tooltip.description.title", "Description"),
-        description: t("changePermissions.tooltip.description.text", "Changes document permissions. Warning: To make these restrictions unchangeable, use the Add Password tool to set an owner password.")
+        description: t("changePermissions.tooltip.description.text", "Changes document permissions, allowing/disallowing access to different features in PDF readers.")
+      },
+      {
+        title: t("changePermissions.tooltip.warning.title", "Warning"),
+        description: t("changePermissions.tooltip.warning.text", "To make these permissions unchangeable, use the Add Password tool to set an owner password.")
       }
     ]
   };
diff --git a/frontend/src/tools/AddPassword.tsx b/frontend/src/tools/AddPassword.tsx
index 773fb4d1c..e649de72d 100644
--- a/frontend/src/tools/AddPassword.tsx
+++ b/frontend/src/tools/AddPassword.tsx
@@ -18,6 +18,7 @@ import ChangePermissionsSettings from "../components/tools/changePermissions/Cha
 import { useAddPasswordParameters } from "../hooks/tools/addPassword/useAddPasswordParameters";
 import { useAddPasswordOperation } from "../hooks/tools/addPassword/useAddPasswordOperation";
 import { useAddPasswordTips } from "../components/tooltips/useAddPasswordTips";
+import { useAddPasswordPermissionsTips } from "../components/tooltips/useAddPasswordPermissionsTips";
 import { BaseToolProps } from "../types/tool";
 
 const AddPassword = ({ onPreviewFile, onComplete, onError }: BaseToolProps) => {
@@ -30,6 +31,7 @@ const AddPassword = ({ onPreviewFile, onComplete, onError }: BaseToolProps) => {
   const addPasswordParams = useAddPasswordParameters();
   const addPasswordOperation = useAddPasswordOperation();
   const addPasswordTips = useAddPasswordTips();
+  const addPasswordPermissionsTips = useAddPasswordPermissionsTips();
 
   // Endpoint validation
   const { enabled: endpointEnabled, loading: endpointLoading } = useEndpointEnabled(addPasswordParams.getEndpointName());
@@ -104,7 +106,7 @@ const AddPassword = ({ onPreviewFile, onComplete, onError }: BaseToolProps) => {
 
         {/* Passwords & Encryption Step */}
         <ToolStep
-          title={t('addPassword.passwords.stepTitle', 'Passwords & Encryption')}
+          title={t('addPassword.title', 'Passwords & Encryption')}
           isVisible={hasFiles}
           isCollapsed={passwordsCollapsed}
           isCompleted={passwordsCollapsed}
@@ -121,11 +123,12 @@ const AddPassword = ({ onPreviewFile, onComplete, onError }: BaseToolProps) => {
 
         {/* Permissions Step */}
         <ToolStep
-          title={t('addPassword.permissions.stepTitle', 'Document Permissions')}
+          title={t('changePermissions.title', 'Document Permissions')}
           isVisible={hasFiles}
           isCollapsed={permissionsCollapsed}
           isCompleted={permissionsCollapsed}
           onCollapsedClick={hasResults ? handleSettingsReset : () => setCollapsedPermissions(!collapsedPermissions)}
+          tooltip={addPasswordPermissionsTips}
         >
           <ChangePermissionsSettings
             parameters={addPasswordParams.permissions.parameters}
diff --git a/frontend/src/tools/ChangePermissions.tsx b/frontend/src/tools/ChangePermissions.tsx
index 58cb32474..820216ee8 100644
--- a/frontend/src/tools/ChangePermissions.tsx
+++ b/frontend/src/tools/ChangePermissions.tsx
@@ -100,7 +100,7 @@ const ChangePermissions = ({ onPreviewFile, onComplete, onError }: BaseToolProps
 
         {/* Settings Step */}
         <ToolStep
-          title={t('settings.title', 'Settings')}
+          title={t('changePermissions.title', 'Document Permissions')}
           isVisible={hasFiles}
           isCollapsed={settingsCollapsed}
           isCompleted={settingsCollapsed}