Skip to content

Beautiful Open-Source Form Builder

Remove stale PDF field mappings and notify users (#1295)

Julien Nahum2a1120ef8044
diff --git a/README.md b/README.md
index 4faec7600..851356829 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,10 @@ Run the browser suite against the running worktree with:
./scripts/codex-worktree-test-e2e.sh
```
+## PDF template fields
+
+The PDF editor removes zones linked to deleted fields and lists them before you continue. Save the template to keep the cleanup. Mappings retain field names when created or saved, so deleted fields can still be identified. Older mappings without a saved name appear as “Deleted field” with their page number.
+
## Support & Community
If you need help or have questions, please join our [Discord community](https://discord.gg/YTSjU2a9TS). For more information and assistance, check out the following resources:
diff --git a/api/app/Service/Pdf/PdfFormFieldRenderer.php b/api/app/Service/Pdf/PdfFormFieldRenderer.php
index a76a00510..d54c7a10d 100644
--- a/api/app/Service/Pdf/PdfFormFieldRenderer.php
+++ b/api/app/Service/Pdf/PdfFormFieldRenderer.php
@@ -96,7 +96,7 @@ class PdfFormFieldRenderer
// Value zone
$zoneHeight = $this->getFieldZoneHeight($type, $field);
- $this->addFieldValueZone($fieldId, $zoneHeight);
+ $this->addFieldValueZone($fieldId, $zoneHeight, $name);
// Spacing before next field
$this->cursorY += self::FIELD_SPACING;
@@ -119,7 +119,7 @@ class PdfFormFieldRenderer
$this->cursorY += $height;
}
- private function addFieldValueZone(string $fieldId, float $height): void
+ private function addFieldValueZone(string $fieldId, float $height, string $fieldName): void
{
$this->zones[] = [
'id' => (string) Str::uuid(),
@@ -130,6 +130,7 @@ class PdfFormFieldRenderer
'width' => 100 - (2 * self::MARGIN_X),
'height' => $height,
'field_id' => $fieldId,
+ 'field_name' => $fieldName,
'font_size' => self::DEFAULT_FONT_SIZE,
'font_color' => '#111827',
];
diff --git a/api/tests/Feature/Integrations/Pdf/PdfTemplateTest.php b/api/tests/Feature/Integrations/Pdf/PdfTemplateTest.php
index 940056636..65b9d0e18 100644
--- a/api/tests/Feature/Integrations/Pdf/PdfTemplateTest.php
+++ b/api/tests/Feature/Integrations/Pdf/PdfTemplateTest.php
@@ -169,6 +169,8 @@ describe('PDF Template Create from Scratch', function () {
->toArray();
foreach ($inputFields as $fieldId) {
expect($zoneFieldIds)->toContain($fieldId);
+ $zone = collect($template->zone_mappings)->firstWhere('field_id', $fieldId);
+ expect($zone['field_name'])->toBe(collect($form->properties)->firstWhere('id', $fieldId)['name']);
}
// Every zone must reference a valid page_id from the manifest
diff --git a/client/components/open/pdf-editor/PdfObsoleteFieldZonesModal.vue b/client/components/open/pdf-editor/PdfObsoleteFieldZonesModal.vue
new file mode 100644
index 000000000..bfbad7ef7
--- /dev/null
+++ b/client/components/open/pdf-editor/PdfObsoleteFieldZonesModal.vue
@@ -0,0 +1,79 @@
+<template>
+ <UModal
+ v-model:open="isOpen"
+ title="Some fields were removed"
+ description="These fields no longer exist in your form. Their PDF zones have been removed. Add any replacements to the template."
+ :close="false"
+ :ui="{ content: 'sm:max-w-lg' }"
+ >
+ <template #title>
+ <div class="flex items-center gap-3">
+ <span class="flex size-10 shrink-0 items-center justify-center rounded-full bg-amber-50 text-amber-600 dark:bg-amber-950 dark:text-amber-400">
+ <Icon name="i-heroicons-document-minus" class="size-5" aria-hidden="true" />
+ </span>
+ <span>Some fields were removed</span>
+ </div>
+ </template>
+
+ <template #body>
+ <ul class="max-h-64 divide-y divide-neutral-100 overflow-y-auto rounded-lg border border-neutral-200 dark:divide-neutral-800 dark:border-neutral-700">
+ <li
+ v-for="(zone, index) in zones"
+ :key="zone.id"
+ class="flex items-center gap-3 px-4 py-3 text-sm"
+ >
+ <span class="flex size-7 shrink-0 items-center justify-center rounded-md bg-neutral-100 dark:bg-neutral-700">
+ <UIcon name="i-heroicons-at-symbol" class="size-4 text-neutral-500 dark:text-neutral-300" aria-hidden="true" />
+ </span>
+ <span class="min-w-0 flex-1 break-words font-medium text-neutral-900 dark:text-white">
+ {{ getZoneLabel(zone, index) }}
+ </span>
+ <span class="shrink-0 text-xs text-neutral-500 dark:text-neutral-400">
+ Page {{ zone.page }}
+ </span>
+ </li>
+ </ul>
+ <p class="mt-3 text-xs text-neutral-500 dark:text-neutral-400">
+ Save the template to keep these changes.
+ </p>
+ </template>
+
+ <template #footer>
+ <div class="flex w-full justify-end">
+ <UButton color="primary" @click="close">
+ Got it
+ </UButton>
+ </div>
+ </template>
+ </UModal>
+</template>
+
+<script setup>
+const props = defineProps({
+ open: {
+ type: Boolean,
+ default: false,
+ },
+ zones: {
+ type: Array,
+ default: () => [],
+ },
+})
+
+const emit = defineEmits(['update:open'])
+
+const isOpen = computed({
+ get: () => props.open,
+ set: value => emit('update:open', value),
+})
+
+const getZoneLabel = (zone, index) => {
+ const label = [zone.field_name, zone.field_label, zone.label]
+ .find(value => typeof value === 'string' && value.trim())
+ return label?.trim() || `Deleted field ${index + 1}`
+}
+
+const close = () => {
+ isOpen.value = false
+}
+</script>
diff --git a/client/pages/forms/[slug]/pdf-editor/[templateId].vue b/client/pages/forms/[slug]/pdf-editor/[templateId].vue
index 376593da2..734cb4c00 100644
--- a/client/pages/forms/[slug]/pdf-editor/[templateId].vue
+++ b/client/pages/forms/[slug]/pdf-editor/[templateId].vue
@@ -24,6 +24,11 @@
<!-- Editor Layout (only when loaded) -->
<template v-else>
+ <PdfObsoleteFieldZonesModal
+ v-model:open="isObsoleteZonesModalOpen"
+ :zones="removedObsoleteFieldZones"
+ />
+
<PdfEditorNavbar
@go-back="goBack"
@save-pdf-template="saveTemplate"
@@ -53,6 +58,7 @@
<script setup>
import { usePdfTemplates } from '~/composables/query/forms/usePdfTemplates'
import PdfEditorNavbar from '~/components/open/pdf-editor/PdfEditorNavbar.vue'
+import PdfObsoleteFieldZonesModal from '~/components/open/pdf-editor/PdfObsoleteFieldZonesModal.vue'
import PdfLeftSidebar from '~/components/open/pdf-editor/PdfLeftSidebar.vue'
import PdfRightSidebar from '~/components/open/pdf-editor/PdfRightSidebar.vue'
import PdfZoneEditor from '~/components/open/pdf-editor/PdfZoneEditor.vue'
@@ -89,15 +95,26 @@ const updateTemplate = update(
)
const isLoading = computed(() => formLoading.value || templateLoading.value)
+const isObsoleteZonesModalOpen = ref(false)
+const removedObsoleteFieldZones = ref([])
+const hasCheckedObsoleteZones = ref(false)
// Initialize store from template and form
-watch([() => templateData.value?.data, form], ([t, f]) => {
+watch([() => templateData.value?.data, form, isLoading], ([t, f, loading]) => {
if (t) {
pdfStore.set(t)
}
if (f) {
pdfStore.setForm(f)
}
+ if (!loading && t && f && !hasCheckedObsoleteZones.value) {
+ hasCheckedObsoleteZones.value = true
+ removedObsoleteFieldZones.value = pdfStore.obsoleteFieldZones.map(zone => ({ ...zone }))
+ if (removedObsoleteFieldZones.value.length) {
+ pdfStore.removeObsoleteFieldZones()
+ isObsoleteZonesModalOpen.value = true
+ }
+ }
}, { immediate: true })
// Cleanup on unmount
diff --git a/client/stores/working_pdf.js b/client/stores/working_pdf.js
index 5569911b6..8fe157059 100644
--- a/client/stores/working_pdf.js
+++ b/client/stores/working_pdf.js
@@ -108,6 +108,20 @@ export const useWorkingPdfStore = defineStore("working_pdf", {
return [...formOptions, ...computedOptions, ...specialOptions]
},
+ obsoleteFieldZones() {
+ const activeFieldIds = new Set([
+ ...this.formFields,
+ ...this.computedVariables,
+ ...this.specialFields,
+ ].map(field => field.id))
+
+ return (this.content?.zone_mappings || []).filter((zone) => {
+ if (zone.static_text !== undefined || zone.static_image !== undefined) return false
+ if (typeof zone.field_id !== 'string' || !zone.field_id.trim()) return false
+ return !activeFieldIds.has(zone.field_id)
+ })
+ },
+
defaultFilenamePattern() {
return DEFAULT_FILENAME_PATTERN
}
@@ -195,6 +209,18 @@ export const useWorkingPdfStore = defineStore("working_pdf", {
}
},
+ removeObsoleteFieldZones() {
+ if (!this.content?.zone_mappings) return
+
+ const obsoleteZoneIds = new Set(this.obsoleteFieldZones.map(zone => zone.id))
+ if (!obsoleteZoneIds.size) return
+
+ this.content.zone_mappings = this.content.zone_mappings.filter(zone => !obsoleteZoneIds.has(zone.id))
+ if (obsoleteZoneIds.has(this.selectedZoneId)) {
+ this.selectedZoneId = null
+ }
+ },
+
addZoneWithField(field = null, staticFieldKey = null) {
const currentEntry = this.pageManifest[this.currentPage - 1]
if (!currentEntry) return
@@ -210,7 +236,7 @@ export const useWorkingPdfStore = defineStore("working_pdf", {
font_size: 12,
font_color: '#000000',
}
- const newZone = field ? { ...baseZone, field_id: field.id } : { ...baseZone, [staticFieldKey]: '' }
+ const newZone = field ? { ...baseZone, field_id: field.id, field_name: field.name } : { ...baseZone, [staticFieldKey]: '' }
this.addZone(newZone)
this.selectedZoneId = newZone.id
this.lastAddedZoneId = newZone.id
@@ -374,7 +400,12 @@ export const useWorkingPdfStore = defineStore("working_pdf", {
if (!this.content) return null
return {
name: this.content.name,
- zone_mappings: this.content.zone_mappings,
+ zone_mappings: this.content.zone_mappings.map((zone) => {
+ if (zone.static_text !== undefined || zone.static_image !== undefined) return zone
+ const field = [...(this.form?.properties || []), ...this.computedVariables, ...this.specialFields]
+ .find(field => field.id === zone.field_id)
+ return field ? { ...zone, field_name: field.name } : zone
+ }),
filename_pattern: this.content.filename_pattern,
remove_branding: this.content.remove_branding,
page_count: this.pageManifest.length,
diff --git a/client/test/nuxt/pdf-obsolete-field-zones-modal.spec.ts b/client/test/nuxt/pdf-obsolete-field-zones-modal.spec.ts
new file mode 100644
index 000000000..41d5cb11f
--- /dev/null
+++ b/client/test/nuxt/pdf-obsolete-field-zones-modal.spec.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { mount } from '@vue/test-utils'
+import PdfObsoleteFieldZonesModal from '~/components/open/pdf-editor/PdfObsoleteFieldZonesModal.vue'
+
+const zones = [
+ { id: 'account-number', page: 1, field_id: 'deleted_account_number', field_name: 'Account Number' },
+ { id: 'routing-number', page: 2, field_id: '3b8362f4-41f9-4a39-8d3d-a122697b7216' },
+]
+
+function createWrapper(props = {}) {
+ return mount(PdfObsoleteFieldZonesModal, {
+ props: {
+ open: true,
+ zones,
+ ...props,
+ },
+ global: {
+ stubs: {
+ UModal: {
+ props: ['open', 'ui', 'description'],
+ emits: ['update:open'],
+ template: '<div class="modal"><slot name="title" /><p>{{ description }}</p><slot name="body" /><slot name="footer" /></div>',
+ },
+ UButton: {
+ emits: ['click'],
+ template: '<button @click="$emit(\'click\')"><slot /></button>',
+ },
+ },
+ },
+ })
+}
+
+describe('PdfObsoleteFieldZonesModal', () => {
+ it('lists every obsolete zone with its page and available label', () => {
+ const wrapper = createWrapper()
+
+ expect(wrapper.text()).toContain('Account Number')
+ expect(wrapper.text()).toContain('Page 1')
+ expect(wrapper.text()).toContain('Deleted field 2')
+ expect(wrapper.text()).not.toContain(zones[1].field_id)
+ expect(wrapper.text()).toContain('Page 2')
+ })
+
+ it('closes when the acknowledgement is clicked without emitting a removal action', async () => {
+ const wrapper = createWrapper()
+
+ expect(wrapper.text()).toContain('have been removed')
+ expect(wrapper.findAll('button')).toHaveLength(1)
+ expect(wrapper.get('button').text()).toBe('Got it')
+
+ await wrapper.get('button').trigger('click')
+
+ expect(wrapper.emitted('update:open')).toEqual([[false]])
+ expect(wrapper.emitted('remove')).toBeUndefined()
+ })
+})
diff --git a/client/test/unit/working-pdf-store.test.ts b/client/test/unit/working-pdf-store.test.ts
index 5afa917ac..838e06336 100644
--- a/client/test/unit/working-pdf-store.test.ts
+++ b/client/test/unit/working-pdf-store.test.ts
@@ -163,3 +163,77 @@ describe('working_pdf store - computed variables', () => {
expect(store.getZoneLabel(store.content.zone_mappings[0])).toBe('Yes No')
})
})
+
+describe('working_pdf store - obsolete field mappings', () => {
+ beforeEach(() => {
+ setActivePinia(createPinia())
+ })
+
+ it('identifies only field zones that no longer map to an active field, variable, or special field', () => {
+ const store = useWorkingPdfStore()
+ store.set(createTemplateFixture({
+ page_count: 2,
+ zone_mappings: [
+ { id: 'active-field', page: 1, field_id: 'email' },
+ { id: 'computed-variable', page: 1, field_id: 'total' },
+ { id: 'special-field', page: 1, field_id: 'submission_id' },
+ { id: 'obsolete-field', page: 2, field_id: 'deleted_account_number', field_name: 'Account Number' },
+ { id: 'blank-field', page: 2, field_id: ' ' },
+ { id: 'static-text', page: 2, field_id: 'deleted_text', static_text: 'Text' },
+ { id: 'static-image', page: 2, field_id: 'deleted_image', static_image: 'image.png' },
+ ],
+ }))
+ store.setForm({
+ properties: [{ id: 'email', name: 'Email', type: 'email' }],
+ computed_variables: [{ id: 'total', name: 'Total', formula: '1 + 1' }],
+ })
+
+ expect(store.obsoleteFieldZones).toEqual([
+ expect.objectContaining({ id: 'obsolete-field', field_id: 'deleted_account_number' }),
+ ])
+ })
+
+ it('removes obsolete field zones and clears a removed selection without marking the template saved', () => {
+ const store = useWorkingPdfStore()
+ store.set(createTemplateFixture({
+ page_count: 1,
+ zone_mappings: [
+ { id: 'obsolete', page: 1, field_id: 'deleted_field' },
+ { id: 'active', page: 1, field_id: 'name' },
+ ],
+ }))
+ store.setForm({
+ properties: [{ id: 'name', name: 'Name', type: 'text' }],
+ })
+ store.setSelectedZone('obsolete')
+
+ store.removeObsoleteFieldZones()
+
+ expect(store.content.zone_mappings).toEqual([
+ expect.objectContaining({ id: 'active', field_id: 'name' }),
+ ])
+ expect(store.selectedZoneId).toBeNull()
+ expect(store.hasUnsavedChanges).toBe(true)
+ })
+})
+
+
+describe('working_pdf store - field names', () => {
+ it('saves the current name after remapping and keeps it when the field is deleted', () => {
+ setActivePinia(createPinia())
+ const store = useWorkingPdfStore()
+ store.set(createTemplateFixture())
+ store.setForm({ properties: [
+ { id: 'name', name: 'Full name', type: 'text' },
+ { id: 'account', name: 'Account number', type: 'text' },
+ ] })
+ store.addZoneWithField({ id: 'name', name: 'Full name' })
+ store.content.zone_mappings[0].field_id = 'account'
+ const saved = store.getSaveData()
+ expect(saved.zone_mappings[0].field_name).toBe('Account number')
+
+ store.set({ ...createTemplateFixture(), ...saved })
+ store.setForm({ properties: [] })
+ expect(store.obsoleteFieldZones[0].field_name).toBe('Account number')
+ })
+})