From eada9e43ec6e6cf57f238d72f4b3e273ad08008a Mon Sep 17 00:00:00 2001
From: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>
Date: Wed, 20 Aug 2025 14:12:12 +0100
Subject: [PATCH] tooltip (#4242)

# Description of Changes

<!--
Please provide a summary of the changes, including:

- What was changed
- Why the change was made
- Any challenges encountered

Closes #(issue_number)
-->

---

## Checklist

### General

- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.
---
 .../public/locales/en-GB/translation.json     | 44 +++++++++++-
 .../public/locales/en-US/translation.json     | 67 ++++++++++++++++++-
 .../tooltips/usePageSelectionTips.tsx         | 62 +++++++++++++++++
 3 files changed, 171 insertions(+), 2 deletions(-)
 create mode 100644 frontend/src/components/tooltips/usePageSelectionTips.tsx

diff --git a/frontend/public/locales/en-GB/translation.json b/frontend/public/locales/en-GB/translation.json
index 333f6ca8b..64cd9408d 100644
--- a/frontend/public/locales/en-GB/translation.json
+++ b/frontend/public/locales/en-GB/translation.json
@@ -1011,7 +1011,49 @@
     "submit": "Change"
   },
   "removePages": {
-    "tags": "Remove pages,delete pages"
+    "tags": "Remove pages,delete pages",
+    "title": "Remove Pages",
+    "pageNumbers": "Pages to Remove",
+    "pageNumbersPlaceholder": "e.g. 1,3,5-7",
+    "pageNumbersHelp": "Enter page numbers separated by commas, or ranges like 1-5. Example: 1,3,5-7",
+    "filenamePrefix": "pages_removed",
+    "files": {
+      "placeholder": "Select a PDF file in the main view to get started"
+    },
+    "settings": {
+      "title": "Page Selection"
+    },
+    "error": {
+      "failed": "An error occurred whilst removing pages."
+    },
+    "results": {
+      "title": "Page Removal Results"
+    },
+    "submit": "Remove Pages"
+  },
+  "pageSelection": {
+    "tooltip": {
+      "header": {
+        "title": "Page Selection Guide"
+      },
+      "basic": {
+        "title": "Basic Usage",
+        "text": "Select specific pages from your PDF document using simple syntax.",
+        "bullet1": "Individual pages: 1,3,5",
+        "bullet2": "Page ranges: 3-6 or 10-15",
+        "bullet3": "All pages: all"
+      },
+      "advanced": {
+        "title": "Advanced Features"
+      },
+      "tips": {
+        "title": "Tips",
+        "text": "Keep these guidelines in mind:",
+        "bullet1": "Page numbers start from 1 (not 0)",
+        "bullet2": "Spaces are automatically removed",
+        "bullet3": "Invalid expressions are ignored"
+      }
+    }
   },
   "compressPdfs": {
     "tags": "squish,small,tiny"
diff --git a/frontend/public/locales/en-US/translation.json b/frontend/public/locales/en-US/translation.json
index 0638d78d3..358ccd53a 100644
--- a/frontend/public/locales/en-US/translation.json
+++ b/frontend/public/locales/en-US/translation.json
@@ -738,7 +738,72 @@
     "submit": "Change"
   },
   "removePages": {
-    "tags": "Remove pages,delete pages"
+    "tags": "Remove pages,delete pages",
+    "title": "Remove Pages",
+    "pageNumbers": "Pages to Remove",
+    "pageNumbersPlaceholder": "e.g. 1,3,5-7",
+    "pageNumbersHelp": "Enter page numbers separated by commas, or ranges like 1-5. Example: 1,3,5-7",
+    "filenamePrefix": "pages_removed",
+    "files": {
+      "placeholder": "Select a PDF file in the main view to get started"
+    },
+    "settings": {
+      "title": "Page Selection"
+    },
+    "error": {
+      "failed": "An error occurred while removing pages."
+    },
+    "results": {
+      "title": "Page Removal Results"
+    },
+    "submit": "Remove Pages"
+  },
+  "pageSelection": {
+    "tooltip": {
+      "header": {
+        "title": "Page Selection Guide"
+      },
+      "basic": {
+        "title": "Basic Usage",
+        "text": "Select specific pages from your PDF document using simple syntax.",
+        "bullet1": "Individual pages: 1,3,5",
+        "bullet2": "Page ranges: 3-6 or 10-15",
+        "bullet3": "All pages: all"
+      },
+      "advanced": {
+        "title": "Advanced Features",
+        "expandText": "▶ Show advanced options",
+        "collapseText": "▼ Hide advanced options",
+        "mathematical": {
+          "title": "Mathematical Functions",
+          "text": "Use mathematical expressions to select page patterns:",
+          "bullet1": "2n - all even pages (2, 4, 6, 8...)",
+          "bullet2": "2n+1 - all odd pages (1, 3, 5, 7...)",
+          "bullet3": "3n - every 3rd page (3, 6, 9, 12...)",
+          "bullet4": "4n-1 - pages 3, 7, 11, 15..."
+        },
+        "ranges": {
+          "title": "Open-ended Ranges",
+          "text": "Select from a starting point to the end:",
+          "bullet1": "5- selects pages 5 to end of document",
+          "bullet2": "10- selects pages 10 to end"
+        },
+        "combinations": {
+          "title": "Complex Combinations",
+          "text": "Combine different selection methods:",
+          "bullet1": "1,3-5,8,2n - pages 1, 3-5, 8, and all even pages",
+          "bullet2": "10-,2n+1 - pages 10 to end plus all odd pages",
+          "bullet3": "1-5,15-,3n - pages 1-5, 15 to end, and every 3rd page"
+        }
+      },
+      "tips": {
+        "title": "Tips",
+        "text": "Keep these guidelines in mind:",
+        "bullet1": "Page numbers start from 1 (not 0)",
+        "bullet2": "Spaces are automatically removed",
+        "bullet3": "Invalid expressions are ignored"
+      }
+    }
   },
   "compressPdfs": {
     "tags": "squish,small,tiny"
diff --git a/frontend/src/components/tooltips/usePageSelectionTips.tsx b/frontend/src/components/tooltips/usePageSelectionTips.tsx
new file mode 100644
index 000000000..d51034992
--- /dev/null
+++ b/frontend/src/components/tooltips/usePageSelectionTips.tsx
@@ -0,0 +1,62 @@
+import { useTranslation } from 'react-i18next';
+import { TooltipContent } from '../../types/tips';
+
+/**
+ * Reusable tooltip for page selection functionality.
+ * Can be used by any tool that uses the GeneralUtils.parsePageList syntax.
+ */
+export const usePageSelectionTips = (): TooltipContent => {
+  const { t } = useTranslation();
+
+  return {
+    header: {
+      title: t("pageSelection.tooltip.header.title", "Page Selection Guide")
+    },
+    tips: [
+      {
+        description: t("pageSelection.tooltip.description", "Choose which pages to use for the operation. Supports single pages, ranges, formulas, and the all keyword.")
+      },
+      {
+        title: t("pageSelection.tooltip.individual.title", "Individual Pages"),
+        description: t("pageSelection.tooltip.individual.description", "Enter numbers separated by commas."),
+        bullets: [
+          t("pageSelection.tooltip.individual.bullet1", "<strong>1,3,5</strong> → selects pages 1, 3, 5"),
+          t("pageSelection.tooltip.individual.bullet2", "<strong>2,7,12</strong> → selects pages 2, 7, 12")
+        ]
+      },
+      {
+        title: t("pageSelection.tooltip.ranges.title", "Page Ranges"),
+        description: t("pageSelection.tooltip.ranges.description", "Use - for consecutive pages."),
+        bullets: [
+          t("pageSelection.tooltip.ranges.bullet1", "<strong>3-6</strong> → selects pages 3–6"),
+          t("pageSelection.tooltip.ranges.bullet2", "<strong>10-15</strong> → selects pages 10–15"),
+          t("pageSelection.tooltip.ranges.bullet3", "<strong>5-</strong> → selects pages 5 to end")
+        ]
+      },
+      {
+        title: t("pageSelection.tooltip.mathematical.title", "Mathematical Functions"),
+        description: t("pageSelection.tooltip.mathematical.description", "Use n in formulas for patterns."),
+        bullets: [
+		  t("pageSelection.tooltip.mathematical.bullet2", "<strong>2n-1</strong> → all odd pages (1, 3, 5…)"),
+          t("pageSelection.tooltip.mathematical.bullet1", "<strong>2n</strong> → all even pages (2, 4, 6…)"),
+          t("pageSelection.tooltip.mathematical.bullet3", "<strong>3n</strong> → every 3rd page (3, 6, 9…)"),
+          t("pageSelection.tooltip.mathematical.bullet4", "<strong>4n-1</strong> → pages 3, 7, 11, 15…")
+        ]
+      },
+      {
+        title: t("pageSelection.tooltip.special.title", "Special Keywords"),
+        bullets: [
+          t("pageSelection.tooltip.special.bullet1", "<strong>all</strong> → selects all pages"),
+        ]
+      },
+      {
+        title: t("pageSelection.tooltip.complex.title", "Complex Combinations"),
+        description: t("pageSelection.tooltip.complex.description", "Mix different types."),
+        bullets: [
+          t("pageSelection.tooltip.complex.bullet1", "<strong>1,3-5,8,2n</strong> → pages 1, 3–5, 8, plus evens"),
+          t("pageSelection.tooltip.complex.bullet2", "<strong>10-,2n-1</strong> → from page 10 to end + odd pages")
+        ]
+      }
+    ]
+  };
+};
\ No newline at end of file