feat: hide comment field, phone pattern validation, file persistence, alignment fix

- Add hide_comment_field BooleanField to WorkflowStage to control
  comment visibility on approval forms per stage.
- Add HTML5 pattern attribute to phone fields for immediate browser
  validation; country code prefixes (+1, +44) accepted.
- Save uploaded files eagerly before validation so they survive
  validation failures. Persist files with drafts. Carry forward
  existing file metadata on resubmit when no new file is uploaded.
- Group consecutive third/fourth-width fields in ApprovalStepForm
  into a single Row with align-items-start for consistent alignment.

Bump version to 0.63.0.

Author: matteius

CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.63.0] - 2026-04-02
+
+### Added
+- **`hide_comment_field` on WorkflowStage** — new boolean field allows hiding
+  the public "Decision Comment" textarea from approvers on a per-stage basis.
+  Useful for stages with no submitter notifications or where the comment is
+  not meaningful.
+- **Phone field HTML5 pattern validation** — phone fields now include a
+  `pattern` attribute so browsers provide immediate visual feedback (like email
+  fields do). Rejects non-phone text such as "test" at input time. Country
+  code prefixes (`+1`, `+44`, etc.) are accepted.
+
+### Fixed
+- **File uploads preserved on validation failure** — uploaded files are now
+  saved to storage eagerly before form validation. On a validation-failure
+  re-render the form shows "Previously uploaded: filename" and the field
+  becomes optional, preventing file loss.
+- **File uploads saved with drafts** — clicking "Save Draft" now persists
+  any uploaded files alongside the draft form data.
+- **File carry-forward on resubmit** — when no new file is uploaded,
+  previously-stored file metadata is carried forward instead of being
+  discarded.
+- **Field vertical alignment in approval step forms** — consecutive
+  third/fourth-width fields are now grouped into a single row with
+  `align-items-start`, matching the main form's behaviour and preventing
+  misaligned labels/inputs.
+
 ## [0.62.1] - 2026-04-02
 
 ### Fixed

django_forms_workflows/admin.py

@@ -496,7 +496,7 @@ class WorkflowStageInline(nested_admin.NestedStackedInline):
         ("assignee_form_field", "assignee_lookup_type"),
         "validate_assignee_group",
         ("allow_reassign", "allow_send_back"),
-        "allow_edit_form_data",
+        ("allow_edit_form_data", "hide_comment_field"),
         "trigger_conditions",
     )
 
@@ -958,6 +958,8 @@ def clone_forms(self, request, queryset):
                                 validate_assignee_group=stage.validate_assignee_group,
                                 allow_reassign=stage.allow_reassign,
                                 allow_send_back=stage.allow_send_back,
+                                allow_edit_form_data=stage.allow_edit_form_data,
+                                hide_comment_field=stage.hide_comment_field,
                             )
                             for sag in StageApprovalGroup.objects.filter(
                                 stage=stage
@@ -1591,14 +1593,11 @@ class WorkflowStageAdmin(nested_admin.NestedModelAdmin):
             },
         ),
         (
-            "Editable Form Data",
+            "Approver UI Options",
             {
                 "classes": ("collapse",),
-                "description": (
-                    "When enabled, approvers at this stage can edit the original "
-                    "submission data instead of viewing it read-only."
-                ),
-                "fields": ("allow_edit_form_data",),
+                "description": ("Control what approvers see and can do at this stage."),
+                "fields": ("allow_edit_form_data", "hide_comment_field"),
             },
         ),
         (

django_forms_workflows/forms.py

@@ -223,11 +223,23 @@ class DynamicForm(forms.Form):
     - Draft saving
     """
 
-    def __init__(self, form_definition, user=None, initial_data=None, *args, **kwargs):
+    def __init__(
+        self,
+        form_definition,
+        user=None,
+        initial_data=None,
+        stashed_files=None,
+        *args,
+        **kwargs,
+    ):
         super().__init__(*args, **kwargs)
         self.form_definition = form_definition
         self.user = user
         self.initial_data = initial_data or {}
+        # File metadata saved eagerly before validation so file uploads
+        # survive a validation-failure re-render (browsers don't re-send
+        # files).  Also used to carry forward draft / resubmit file data.
+        self.stashed_files = stashed_files or {}
 
         # Build form fields from definition
         # Exclude fields scoped to a workflow stage - those are for approvers only
@@ -430,6 +442,25 @@ def _get_choices_from_prefill_source(self, field_def):
         source = DatabaseDataSource()
         return source.execute_choices_query(query_key)
 
+    def _get_existing_file_info(self, field_name):
+        """Return previously-uploaded file metadata for *field_name*, if any.
+
+        Checks ``stashed_files`` (validation-failure recovery) first, then
+        falls back to ``initial_data`` (draft / resubmit).  Returns ``None``
+        if no file info is found.
+        """
+        info = self.stashed_files.get(field_name)
+        if info and isinstance(info, dict) and info.get("filename"):
+            return info
+        if info and isinstance(info, list):
+            return info
+        info = (self.initial_data or {}).get(field_name)
+        if info and isinstance(info, dict) and info.get("filename"):
+            return info
+        if info and isinstance(info, list):
+            return info
+        return None
+
     def add_field(self, field_def, initial_data):
         """Add a field to the form based on field definition"""
 
@@ -471,8 +502,14 @@ def add_field(self, field_def, initial_data):
                 {
                     "type": "tel",
                     "inputmode": "tel",
+                    "pattern": r"\+?[\d()\- .]{7,25}",
+                    "title": (
+                        "Enter a valid phone number, e.g. 2065551234, "
+                        "(206) 555-1234, or +1 (206) 555-1234"
+                    ),
                     "placeholder": widget_attrs.get(
-                        "placeholder", "e.g. 2065551234 or (206) 555-1234"
+                        "placeholder",
+                        "e.g. 2065551234, (206) 555-1234, or +1 2065551234",
                     ),
                 }
             )
@@ -606,6 +643,19 @@ def add_field(self, field_def, initial_data):
                     if e.strip()
                 )
                 accept_attrs["accept"] = exts
+
+            # Check for a previously-uploaded file (stashed on validation
+            # failure, saved with a draft, or carried from a resubmission).
+            existing_file = self._get_existing_file_info(field_def.field_name)
+            if existing_file:
+                fname = existing_file.get("filename", "file")
+                extra_help = f"Previously uploaded: <strong>{fname}</strong>. Leave blank to keep it."
+                base_help = field_args.get("help_text", "") or ""
+                field_args["help_text"] = (
+                    f"{base_help} {extra_help}" if base_help else extra_help
+                )
+                field_args["required"] = False
+
             self.fields[field_def.field_name] = forms.FileField(
                 validators=file_validators,
                 widget=forms.ClearableFileInput(attrs=accept_attrs)
@@ -615,10 +665,22 @@ def add_field(self, field_def, initial_data):
             )
 
         elif field_def.field_type == "multifile":
+            existing_file = self._get_existing_file_info(field_def.field_name)
+            required = field_def.required
+            help_text = field_def.help_text
+            if existing_file:
+                names = (
+                    ", ".join(f.get("filename", "file") for f in existing_file)
+                    if isinstance(existing_file, list)
+                    else existing_file.get("filename", "file")
+                )
+                extra = f"Previously uploaded: <strong>{names}</strong>. Leave blank to keep."
+                help_text = f"{help_text} {extra}" if help_text else extra
+                required = False
             self.fields[field_def.field_name] = MultipleFileField(
-                required=field_def.required,
+                required=required,
                 label=field_def.field_label,
-                help_text=field_def.help_text,
+                help_text=help_text,
             )
 
         elif field_def.field_type == "calculated":
@@ -1441,8 +1503,14 @@ def _create_field(self, field_def, field_args, widget_attrs, is_editable):
                 {
                     "type": "tel",
                     "inputmode": "tel",
+                    "pattern": r"\+?[\d()\- .]{7,25}",
+                    "title": (
+                        "Enter a valid phone number, e.g. 2065551234, "
+                        "(206) 555-1234, or +1 (206) 555-1234"
+                    ),
                     "placeholder": widget_attrs.get(
-                        "placeholder", "e.g. 2065551234 or (206) 555-1234"
+                        "placeholder",
+                        "e.g. 2065551234, (206) 555-1234, or +1 2065551234",
                     ),
                 }
             )
@@ -1716,6 +1784,7 @@ def _build_layout_fields(self, field_defs):
                                 Field(next_field.field_name),
                                 css_class=f"col-md-6 field-wrapper field-{next_field.field_name}",
                             ),
+                            css_class="align-items-start",
                         )
                     )
                     i += 2
@@ -1727,22 +1796,31 @@ def _build_layout_fields(self, field_defs):
                         )
                     )
                     i += 1
-            elif field.width == "third":
-                layout_fields.append(
-                    Div(
-                        Row(Column(Field(field.field_name), css_class="col-md-4")),
-                        css_class=f"field-wrapper field-{field.field_name}",
-                    )
-                )
-                i += 1
-            elif field.width == "fourth":
+            elif field.width in ("third", "fourth"):
+                # Collect consecutive same-width fields into a single Row.
+                col_class = "col-md-4" if field.width == "third" else "col-md-3"
+                max_per_row = 3 if field.width == "third" else 4
+                group = []
+                while (
+                    i < len(fields)
+                    and len(group) < max_per_row
+                    and fields[i].width == field.width
+                    and fields[i].field_type != "section"
+                ):
+                    group.append(fields[i])
+                    i += 1
                 layout_fields.append(
-                    Div(
-                        Row(Column(Field(field.field_name), css_class="col-md-3")),
-                        css_class=f"field-wrapper field-{field.field_name}",
+                    Row(
+                        *[
+                            Div(
+                                Field(f.field_name),
+                                css_class=f"{col_class} field-wrapper field-{f.field_name}",
+                            )
+                            for f in group
+                        ],
+                        css_class="align-items-start",
                     )
                 )
-                i += 1
             else:
                 layout_fields.append(
                     Div(

django_forms_workflows/migrations/0089_workflowstage_hide_comment_field.py

@@ -0,0 +1,21 @@
+# Generated by Django 6.0.3 on 2026-04-02 18:45
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0088_notificationrule_body_template_and_events"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="workflowstage",
+            name="hide_comment_field",
+            field=models.BooleanField(
+                default=False,
+                help_text="Hide the public decision comment field from approvers at this stage. Useful for stages where no notifications are sent to the submitter or where the comment would not be meaningful.",
+            ),
+        ),
+    ]

django_forms_workflows/models.py

@@ -1226,6 +1226,14 @@ class WorkflowStage(models.Model):
             "approver approves the submission."
         ),
     )
+    hide_comment_field = models.BooleanField(
+        default=False,
+        help_text=(
+            "Hide the public decision comment field from approvers at this stage. "
+            "Useful for stages where no notifications are sent to the submitter "
+            "or where the comment would not be meaningful."
+        ),
+    )
 
     change_history = GenericRelation(
         "django_forms_workflows.ChangeHistory",

django_forms_workflows/templates/django_forms_workflows/approve.html

@@ -345,6 +345,7 @@ <h5 class="mb-0"><i class="bi bi-pencil-square"></i> {% if current_step_number %
 
                     <!-- Decision Section inline -->
                     <h6 class="mb-3"><i class="bi bi-clipboard-check"></i> Your Decision</h6>
+                    {% if not hide_comment_field %}
                     <div class="mb-3">
                         <label for="comments" class="form-label">
                             Decision Comment
@@ -358,6 +359,7 @@ <h6 class="mb-3"><i class="bi bi-clipboard-check"></i> Your Decision</h6>
                             This comment is <strong>visible to the submitter</strong> and appears on the public submission record.
                         </div>
                     </div>
+                    {% endif %}
                     <div class="d-grid gap-2 d-md-block">
                         <button type="submit" name="decision" value="approve" class="btn btn-success btn-lg">
                             <i class="bi bi-check-circle"></i> {{ approve_label|default:"Approve" }}
@@ -596,6 +598,7 @@ <h5 class="mb-0"><i class="bi bi-clipboard-check"></i> Your Decision</h5>
             <div class="card-body">
                 <form method="post" data-loading-message="Processing your decision...">
                     {% csrf_token %}
+                    {% if not hide_comment_field %}
                     <div class="mb-3">
                         <label for="comments" class="form-label">
                             Decision Comment
@@ -609,6 +612,7 @@ <h5 class="mb-0"><i class="bi bi-clipboard-check"></i> Your Decision</h5>
                             This comment is <strong>visible to the submitter</strong> and appears on the public submission record.
                         </div>
                     </div>
+                    {% endif %}
                     <div class="d-grid gap-2 d-md-block">
                         <button type="submit" name="decision" value="approve" class="btn btn-success btn-lg">
                             <i class="bi bi-check-circle"></i> {{ approve_label|default:"Approve" }}