update to add optional Zero Padding to page numbers (Bates Stamping).… (#5612)

… Useful in legal and other professional fields to have page numbers
written with padded 0s of a fixed width. This is also known as bates
stamping.

# Description of Changes

<!--
Another category is added to the add page number tool where it allows
for defining a 0 padded format. If left as 0, it will not added padded
0s and will be the current implementation.
-->

---

## Checklist

### General

- [x] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [x] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [x] 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)
- [x] I have performed a self-review of my own code
- [x] 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)

### Translations (if applicable)

- [ ] I ran
[`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md)

### 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)

- [x] 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.

---------

Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>

app/core/src/main/java/stirling/software/SPDF/controller/api/misc/PageNumbersController.java

@@ -52,9 +52,17 @@ public class PageNumbersController {
         int pageNumber = request.getStartingNumber();
         String pagesToNumber = request.getPagesToNumber();
         String customText = request.getCustomText();
+        int zeroPad = request.getZeroPad();
         float fontSize = request.getFontSize();
         String fontType = request.getFontType();
         String fontColor = request.getFontColor();
+        // compute padded number string where requested
+        String formatN;
+        if (zeroPad > 0) {
+            formatN = String.format("%%0%dd", Math.max(0, zeroPad));
+        } else {
+            formatN = "%d";
+        }
 
         Color color = Color.BLACK;
         if (fontColor != null && !fontColor.trim().isEmpty()) {
@@ -93,9 +101,10 @@ public class PageNumbersController {
                 PDPage page = document.getPage(i);
                 PDRectangle pageSize = page.getMediaBox();
 
+                String nFormatted = String.format(formatN, pageNumber);
                 String text =
                         customText
-                                .replace("{n}", String.valueOf(pageNumber))
+                                .replace("{n}", nFormatted)
                                 .replace("{total}", String.valueOf(document.getNumberOfPages()))
                                 .replace(
                                         "{filename}",

app/core/src/main/java/stirling/software/SPDF/model/api/misc/AddPageNumbersRequest.java

@@ -39,6 +39,13 @@ public class AddPageNumbersRequest extends PDFWithPageNums {
             requiredMode = RequiredMode.NOT_REQUIRED)
     private String fontColor;
 
+    @Schema(
+            description = "Zero-padding width for page numbers (Bates Stamping). Set to 0 to disable padding",
+            minimum = "0",
+            defaultValue = "0",
+            requiredMode = RequiredMode.NOT_REQUIRED)
+    private int zeroPad = 0;
+
     @Schema(
             description =
                     "Position: 1-9 representing positions on the page (1=top-left, 2=top-center,"

frontend/public/locales/en-GB/translation.toml

@@ -219,6 +219,9 @@ pagesAndStarting = "Pages & Starting Number"
 positionAndPages = "Position & Pages"
 preview = "Position Selection"
 previewDisclaimer = "Preview is approximate. Final output may vary due to PDF font metrics."
+zeroPad = "Zero‑pad Width (Bates Stamping)"
+zeroPadTooltip = "Zero‑pad (Bates Stamp) page numbers to this width (e.g., 3 ⇒ 001). Set 0 to disable."
+
 
 [addPageNumbers.selectText]
 1 = "Select PDF file:"

frontend/src/core/components/tools/addPageNumbers/AddPageNumbersAppearanceSettings.tsx

@@ -49,6 +49,16 @@ const AddPageNumbersAppearanceSettings = ({
         />
       </Tooltip>
 
+      <Tooltip content={t('addPageNumbers.zeroPadTooltip', 'Zero-pad (Bates Stamp) page numbers to this width (e.g. 3 => 001). Set 0 to disable.')}>
+        <NumberInput
+          label={t('addPageNumbers.zeroPad', 'Zero-pad Width (Bates Stamping)')}
+          value={parameters.zeroPad}
+          onChange={(v) => onParameterChange('zeroPad', typeof v === 'number' ? v : 0)}
+          min={0}
+          disabled={disabled}
+        />
+      </Tooltip>
+
       <Tooltip content={t('fontTypeTooltip', 'Font family for the page numbers. Choose based on your document style.')}>
         <Select
           label={t('addPageNumbers.fontName', 'Font Type')}

frontend/src/core/components/tools/addPageNumbers/useAddPageNumbersOperation.ts

@@ -13,6 +13,7 @@ export const buildAddPageNumbersFormData = (parameters: AddPageNumbersParameters
   formData.append('startingNumber', String(parameters.startingNumber));
   formData.append('pagesToNumber', parameters.pagesToNumber);
   formData.append('customText', parameters.customText);
+  formData.append('zeroPad', String(parameters.zeroPad));
 
   return formData;
 };

frontend/src/core/components/tools/addPageNumbers/useAddPageNumbersParameters.ts

@@ -9,6 +9,8 @@ export interface AddPageNumbersParameters extends BaseParameters {
   startingNumber: number;
   pagesToNumber: string;
   customText: string;
+  // Number of digits to zero-pad page numbers to. 0 = no padding.
+  zeroPad: number;
 }
 
 export const defaultParameters: AddPageNumbersParameters = {
@@ -19,6 +21,7 @@ export const defaultParameters: AddPageNumbersParameters = {
   startingNumber: 1,
   pagesToNumber: '',
   customText: '',
+  zeroPad: 0,
 };
 
 export type AddPageNumbersParametersHook = BaseParametersHook<AddPageNumbersParameters>;