fix(a11y): add accessible page overlay labels with keyboard placement hint

Add getPageAriaLabel callback prop to PDFElements which generates
context-aware aria-labels for each page overlay. Labels vary by:
- single vs multi-document envelope (includes doc name and number)
- adding mode vs read-only (includes 'Press Enter or Space' hint)

Unit tests cover all four combinations.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

Author: vitormattos

src/components/PdfEditor/PdfEditor.vue

@@ -8,6 +8,7 @@
 			:init-files="files"
 			:init-file-names="fileNames"
 			:page-count-format="t('libresign', '{currentPage} of {totalPages}')"
+			:page-aria-label="getPageAriaLabel"
 			:auto-fit-zoom="true"
 			:read-only="readOnly"
 			:emit-object-click="true"
@@ -130,6 +131,23 @@ export default {
 	},
 	methods: {
 		t,
+		getPageAriaLabel({ docIndex, docName, totalDocs, pageNumber, totalPages, isAddingMode }) {
+			const docNumber = docIndex + 1
+			if (totalDocs > 1 && isAddingMode) {
+				// TRANSLATORS Accessible label for a PDF page overlay when placing a signature in a multi-document envelope. {docNumber} is the current document number, {totalDocs} is the total number of documents, {docName} is the document file name, {pageNumber} is the current page, {totalPages} is the total pages.
+				return t('libresign', 'Document {docNumber} of {totalDocs} ({docName}), page {pageNumber} of {totalPages}. Press Enter or Space to place the signature here.', { docNumber, totalDocs, docName, pageNumber, totalPages })
+			}
+			if (totalDocs > 1) {
+				// TRANSLATORS Accessible label for a PDF page in a multi-document envelope (read-only mode). {docNumber} is the current document number, {totalDocs} is the total number of documents, {docName} is the document file name, {pageNumber} is the current page, {totalPages} is the total pages.
+				return t('libresign', 'Document {docNumber} of {totalDocs} ({docName}), page {pageNumber} of {totalPages}.', { docNumber, totalDocs, docName, pageNumber, totalPages })
+			}
+			if (isAddingMode) {
+				// TRANSLATORS Accessible label for a PDF page overlay when placing a signature in a single document. {pageNumber} is the current page, {totalPages} is the total number of pages.
+				return t('libresign', 'Page {pageNumber} of {totalPages}. Press Enter or Space to place the signature here.', { pageNumber, totalPages })
+			}
+			// TRANSLATORS Accessible label for a PDF page in a single document (read-only mode). {pageNumber} is the current page, {totalPages} is the total number of pages.
+			return t('libresign', 'Page {pageNumber} of {totalPages}.', { pageNumber, totalPages })
+		},
 		endInit(event) {
 			this.$nextTick(async () => {
 				const shouldAutoFit = this.$refs.pdfElements?.autoFitZoom

src/tests/components/PdfEditor/PdfEditor.spec.ts

@@ -836,6 +836,60 @@ describe('PdfEditor Component - Business Rules', () => {
 		})
 	})
 
+	describe('RULE: getPageAriaLabel accessibility labels', () => {
+		it('single doc, not adding mode: returns plain page label', () => {
+			const label = wrapper.vm.getPageAriaLabel({
+				docIndex: 0,
+				docName: 'contract.pdf',
+				totalDocs: 1,
+				pageNumber: 2,
+				totalPages: 5,
+				isAddingMode: false,
+			})
+
+			expect(label).toBe('Page 2 of 5.')
+		})
+
+		it('single doc, adding mode: includes keyboard placement hint', () => {
+			const label = wrapper.vm.getPageAriaLabel({
+				docIndex: 0,
+				docName: 'contract.pdf',
+				totalDocs: 1,
+				pageNumber: 3,
+				totalPages: 5,
+				isAddingMode: true,
+			})
+
+			expect(label).toBe('Page 3 of 5. Press Enter or Space to place the signature here.')
+		})
+
+		it('multi-doc, not adding mode: includes document context', () => {
+			const label = wrapper.vm.getPageAriaLabel({
+				docIndex: 1,
+				docName: 'annex.pdf',
+				totalDocs: 3,
+				pageNumber: 1,
+				totalPages: 4,
+				isAddingMode: false,
+			})
+
+			expect(label).toBe('Document 2 of 3 (annex.pdf), page 1 of 4.')
+		})
+
+		it('multi-doc, adding mode: includes document context and keyboard placement hint', () => {
+			const label = wrapper.vm.getPageAriaLabel({
+				docIndex: 0,
+				docName: 'main.pdf',
+				totalDocs: 2,
+				pageNumber: 1,
+				totalPages: 10,
+				isAddingMode: true,
+			})
+
+			expect(label).toBe('Document 1 of 2 (main.pdf), page 1 of 10. Press Enter or Space to place the signature here.')
+		})
+	})
+
 	describe('RULE: coordinate system conversion', () => {
 		beforeEach(() => {
 			Object.assign(wrapper.vm.$refs.pdfElements, {