From 6751c836e3c8dffe135a309b8d54929e975a312e Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Tue, 10 Dec 2024 14:55:03 -0500
Subject: [PATCH 01/12] Document responsive form layout on Bootstrap 5

---
 .../templates/styleguide/bootstrap5/organisms/forms.html | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/organisms/forms.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/organisms/forms.html
index 604b659a84b0..43d6336dc849 100644
--- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/organisms/forms.html
+++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/organisms/forms.html
@@ -60,9 +60,16 @@ <h2 id="overview">Overview</h2>
     Different parts of HQ use these two approaches, and you should always consider existing context
     when deciding whether to use Crispy Forms or HTML.
   </p>
+  <p>
+    Form layouts are responsive. On wide screens, labels are arranged in a column to the left and input fields are
+    arranged in a wider column to the right. In Bootstrap 5 this is referred to as
+    <a href="https://getbootstrap.com/docs/5.0/forms/layout/#horizontal-form">horizontal form</a> layout. On
+    narrow screens such as mobile devices, the layout automatically collapses to a single column with each label
+    above its corresponding input control.
+  </p>
   <p>
     The benefit of Crispy Forms, and why you should opt for using it over bespoke HTML whenever possible,
-    is that the HTML for each form component is controlled by templates. From HTML is often affected
+    is that the HTML for each form component is controlled by templates. Form HTML is often affected
     during a front-end migration (like Bootstrap). If a bespoke HTML form was used, that HTML needs
     to be re-examined everywhere.
     However, for forms using Crispy Forms, the relevant HTML only has to be changed once in the templates,

From 3552c8f9e1031261b0ef720a681adf2e08b7d625 Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Tue, 10 Dec 2024 14:59:34 -0500
Subject: [PATCH 02/12] B5 crispy horizontal forms

---
 corehq/apps/hqwebapp/crispy.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/corehq/apps/hqwebapp/crispy.py b/corehq/apps/hqwebapp/crispy.py
index fceb944f7fa9..0957bb339719 100644
--- a/corehq/apps/hqwebapp/crispy.py
+++ b/corehq/apps/hqwebapp/crispy.py
@@ -34,7 +34,6 @@ def __init__(self, *args, **kwargs):
             self.label_class = CSS_LABEL_CLASS_BOOTSTRAP5
             self.field_class = CSS_FIELD_CLASS_BOOTSTRAP5
             self.use_bootstrap5 = use_bootstrap5
-            self.form_class = 'form'
 
         if 'autocomplete' not in self.attrs:
             self.attrs.update({

From 1cabe25b161ccd247ffe44bd85d708fc3010db61 Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Tue, 10 Dec 2024 15:26:43 -0500
Subject: [PATCH 03/12] Remove redundant B5 form class assignemnts

---
 corehq/apps/app_execution/forms.py | 1 -
 corehq/apps/domain/forms.py        | 1 -
 corehq/motech/forms.py             | 1 -
 corehq/motech/repeaters/forms.py   | 1 -
 4 files changed, 4 deletions(-)

diff --git a/corehq/apps/app_execution/forms.py b/corehq/apps/app_execution/forms.py
index 317500f3c30e..7e6e40f0d1db 100644
--- a/corehq/apps/app_execution/forms.py
+++ b/corehq/apps/app_execution/forms.py
@@ -57,7 +57,6 @@ def __init__(self, request, *args, **kwargs):
         if self.instance.id:
             self.fields["username"].initial = self.instance.django_user.username
         self.helper = hqcrispy.HQFormHelper()
-        self.helper.form_class = "form-horizontal"
 
         fields = [
             "name",
diff --git a/corehq/apps/domain/forms.py b/corehq/apps/domain/forms.py
index c24ecc4f92d9..51a61cafbc61 100644
--- a/corehq/apps/domain/forms.py
+++ b/corehq/apps/domain/forms.py
@@ -1273,7 +1273,6 @@ def __init__(self, domain, can_edit_eula, *args, user, **kwargs):
             )
 
         self.helper = hqcrispy.HQFormHelper()
-        self.helper.form_class = "form-horizontal"
         self.helper.layout = crispy.Layout(
             crispy.Fieldset(
                 _("Basic Information"),
diff --git a/corehq/motech/forms.py b/corehq/motech/forms.py
index 30e92b2773aa..fda4f35775c3 100644
--- a/corehq/motech/forms.py
+++ b/corehq/motech/forms.py
@@ -144,7 +144,6 @@ def helper(self):
         from corehq.motech.views import ConnectionSettingsListView
 
         helper = hqcrispy.HQFormHelper()
-        helper.form_class = "form-horizontal"
         helper.layout = crispy.Layout(
             crispy.Field('name'),
             crispy.Field('notify_addresses_str'),
diff --git a/corehq/motech/repeaters/forms.py b/corehq/motech/repeaters/forms.py
index 88c3b45e7135..0907c3822153 100644
--- a/corehq/motech/repeaters/forms.py
+++ b/corehq/motech/repeaters/forms.py
@@ -72,7 +72,6 @@ def set_extra_django_form_fields(self):
 
     def _initialize_crispy_layout(self):
         self.helper = hqcrispy.HQFormHelper(self)
-        self.helper.form_class = 'form-horizontal'
 
         self.helper.layout = crispy.Layout(
             crispy.Fieldset(

From 1ac2e1fa390ef1dfbc46b885f0a63c6d6c6877a6 Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Tue, 10 Dec 2024 15:06:40 -0500
Subject: [PATCH 04/12] Adjust column widths for crispy horizontal forms

Make it easier to associate label with field on wide screens.
Restore large-screen (lg) column widths used with Bootstrap 3.
Tweak medium-screen (md) column widths to improve consistency.
---
 corehq/apps/hqwebapp/crispy.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/corehq/apps/hqwebapp/crispy.py b/corehq/apps/hqwebapp/crispy.py
index 0957bb339719..e3a064e2ae89 100644
--- a/corehq/apps/hqwebapp/crispy.py
+++ b/corehq/apps/hqwebapp/crispy.py
@@ -14,9 +14,9 @@
 from crispy_forms.utils import flatatt, get_template_pack, render_field
 
 CSS_LABEL_CLASS = 'col-xs-12 col-sm-4 col-md-4 col-lg-2'
-CSS_LABEL_CLASS_BOOTSTRAP5 = 'col-xs-12 col-sm-4 col-md-4 col-lg-3'
+CSS_LABEL_CLASS_BOOTSTRAP5 = 'col-xs-12 col-sm-4 col-md-3 col-lg-2'
 CSS_FIELD_CLASS = 'col-xs-12 col-sm-8 col-md-8 col-lg-6'
-CSS_FIELD_CLASS_BOOTSTRAP5 = 'col-xs-12 col-sm-8 col-md-8 col-lg-9'
+CSS_FIELD_CLASS_BOOTSTRAP5 = 'col-xs-12 col-sm-8 col-md-9 col-lg-10'
 CSS_ACTION_CLASS = CSS_FIELD_CLASS + ' col-sm-offset-4 col-md-offset-4 col-lg-offset-2'
 
 

From ba970600b7326e79308da3d868510619cc5324ea Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Thu, 12 Dec 2024 11:10:07 -0500
Subject: [PATCH 05/12] Form style extensions to simplify field classes

Should reduce the overhead of future site-wide style changes such as when upgrading Bootstrap.
---
 corehq/apps/hqwebapp/crispy.py                      |  6 +++---
 .../static/hqwebapp/scss/commcarehq/_forms.scss     | 13 +++++++++++++
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/corehq/apps/hqwebapp/crispy.py b/corehq/apps/hqwebapp/crispy.py
index e3a064e2ae89..602ec696c3f6 100644
--- a/corehq/apps/hqwebapp/crispy.py
+++ b/corehq/apps/hqwebapp/crispy.py
@@ -14,9 +14,9 @@
 from crispy_forms.utils import flatatt, get_template_pack, render_field
 
 CSS_LABEL_CLASS = 'col-xs-12 col-sm-4 col-md-4 col-lg-2'
-CSS_LABEL_CLASS_BOOTSTRAP5 = 'col-xs-12 col-sm-4 col-md-3 col-lg-2'
+CSS_LABEL_CLASS_BOOTSTRAP5 = 'field-label'
 CSS_FIELD_CLASS = 'col-xs-12 col-sm-8 col-md-8 col-lg-6'
-CSS_FIELD_CLASS_BOOTSTRAP5 = 'col-xs-12 col-sm-8 col-md-9 col-lg-10'
+CSS_FIELD_CLASS_BOOTSTRAP5 = 'field-control'
 CSS_ACTION_CLASS = CSS_FIELD_CLASS + ' col-sm-offset-4 col-md-offset-4 col-lg-offset-2'
 
 
@@ -76,7 +76,7 @@ class ErrorsOnlyField(Field):
 
 def get_form_action_class():
     """This is only valid for bootstrap 5"""
-    return CSS_LABEL_CLASS_BOOTSTRAP5.replace('col', 'offset') + ' ' + CSS_FIELD_CLASS_BOOTSTRAP5
+    return CSS_FIELD_CLASS_BOOTSTRAP5
 
 
 def _get_offsets(context):
diff --git a/corehq/apps/hqwebapp/static/hqwebapp/scss/commcarehq/_forms.scss b/corehq/apps/hqwebapp/static/hqwebapp/scss/commcarehq/_forms.scss
index 481acf947bd2..2f7aef91a69d 100644
--- a/corehq/apps/hqwebapp/static/hqwebapp/scss/commcarehq/_forms.scss
+++ b/corehq/apps/hqwebapp/static/hqwebapp/scss/commcarehq/_forms.scss
@@ -1,3 +1,16 @@
+.field-label {
+  @extend .col-form-label, .col-12, .col-sm-4, .col-md-3, .col-lg-2;
+}
+
+.field-label + .field-control {
+  @extend .col-12, .col-sm-8, .col-md-9, .col-lg-10;
+}
+
+:not(.field-label) + .field-control,
+.row > .field-control:first-child {
+  @extend .offset-sm-4, .offset-md-3, .offset-lg-2;
+}
+
 .row > div > .form-check:first-child,
 .row > div > .input-group > .form-check:first-child {
   padding-top: add($input-padding-y, $input-border-width);

From af45509d3eff9846ef2c11df5ad4f87beec12872 Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Thu, 12 Dec 2024 11:15:47 -0500
Subject: [PATCH 06/12] Simplify field classes in styleguide examples

---
 .../bootstrap5/examples/basic_form.html       | 23 ++++++-----------
 .../examples/checkbox_horizontal_form.html    | 12 ++++-----
 .../bootstrap5/examples/disabled_fields.html  | 25 ++++++++-----------
 .../bootstrap5/examples/form_invalid.html     | 15 +++++------
 .../bootstrap5/examples/form_valid.html       | 15 +++++------
 .../examples/placeholder_help_text.html       |  5 ++--
 6 files changed, 37 insertions(+), 58 deletions(-)

diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/basic_form.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/basic_form.html
index b8141230cc9d..3adca1f544b0 100644
--- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/basic_form.html
+++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/basic_form.html
@@ -4,15 +4,10 @@
   <fieldset>
     <legend>Basic Information</legend>
     <div class="row mb-3">
-      <!-- Generally, it is best practice to use the {% css_label_class %}
-           template tag below instead of the col-* classes -->
-      <label for="id_first_name"
-             class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+      <label for="id_first_name" class="field-label">
         First Name
       </label>
-      <!-- Generally, it is best practice to use the {% css_field_class %}
-           template tag below instead of the col-* classes -->
-      <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+      <div class="field-control">
         <input type="text"
                name="first_name"
                class="form-control"
@@ -21,11 +16,10 @@
       </div>
     </div>
     <div class="row mb-3">
-      <label for="id_favorite_color"
-             class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+      <label for="id_favorite_color" class="field-label">
         Favorite Color
       </label>
-      <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+      <div class="field-control">
         <select name="favorite_color"
                 class="form-select hqwebapp-select2"
                 id="id_favorite_color">
@@ -36,11 +30,10 @@
       </div>
     </div>
     <div class="row mb-3">
-      <label for="id_hopes"
-             class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+      <label for="id_hopes" class="field-label">
         Hopes and Dreams
       </label>
-      <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+      <div class="field-control">
         <textarea name="hopes"
                   class="form-control vertical-resize"
                   id="id_hopes"></textarea>
@@ -48,9 +41,7 @@
     </div>
   </fieldset>
   <div class="form-actions row">
-    <!-- Generally, it is best practice to use the {% css_action_class %}
-         template tag below instead of offset-* and col-* -->
-    <div class="offset-xs-12 offset-sm-4 offset-md-4 offset-lg-3 col-xs-12 col-sm-8 col-md-8 col-lg-9">
+    <div class="field-control">
       <button class="btn btn btn-primary" type="submit">Save</button>
       <a href="#" class="btn btn-outline-primary">Cancel</a>
     </div>
diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/checkbox_horizontal_form.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/checkbox_horizontal_form.html
index 7b7d95eb7344..a8c27c522f49 100644
--- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/checkbox_horizontal_form.html
+++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/checkbox_horizontal_form.html
@@ -1,17 +1,17 @@
 <form>
   <div class="mb-3 row">
-    <label for="height-input" class="col-sm-3 col-form-label">
+    <label for="height-input" class="field-label">
       Height (cm)
     </label>
-    <div class="col-sm-9">
+    <div class="field-control">
       <input type="text" id="height-input" name="height" class="form-control" />
     </div>
   </div>
   <div class="mb-3 row">
-    <label class="col-sm-3 col-form-label">
+    <label class="field-label">
       Smoking status
     </label>
-    <div class="col-sm-9">
+    <div class="field-control">
       <div class="form-check">
         <input class="form-check-input"
                type="checkbox"
@@ -26,10 +26,10 @@
     </div>
   </div>
   <div class="mb-3 row">
-    <label for="heartRate-input" class="col-sm-3 col-form-label">
+    <label for="heartRate-input" class="field-label">
       Heart Rate (bpm)
     </label>
-    <div class="col-sm-9">
+    <div class="field-control">
       <input type="text" id="heartRate-input" name="heartRate" class="form-control" />
     </div>
   </div>
diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/disabled_fields.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/disabled_fields.html
index ebe5a899bb3e..f453ea0ba52a 100644
--- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/disabled_fields.html
+++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/disabled_fields.html
@@ -3,11 +3,10 @@
     Examples of Disabled Fields
   </legend>
   <div class="row mb-3">
-    <label for="id_first_name_dis"
-           class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+    <label for="id_first_name_dis" class="field-label">
       First Name
     </label>
-    <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+    <div class="field-control">
       <input type="text"
              name="first_name_dis"
              value="Jon"
@@ -19,11 +18,10 @@
     </div>
   </div>
   <div class="row mb-3">
-    <label for="id_favorite_color_dis"
-           class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+    <label for="id_favorite_color_dis" class="field-label">
       Favorite Color
     </label>
-    <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+    <div class="field-control">
       <select name="favorite_color_dis"
               class="form-select hqwebapp-select2"
               id="id_favorite_color_dis"
@@ -36,11 +34,10 @@
     </div>
   </div>
   <div class="row mb-3">
-    <label for="id_hopes_dis"
-           class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+    <label for="id_hopes_dis" class="field-label">
       Hopes and Dreams
     </label>
-    <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+    <div class="field-control">
       <textarea name="hopes_dis"
                 class="form-control vertical-resize"
                 id="id_hopes_dis"
@@ -54,11 +51,10 @@
     Examples of Readonly Fields
   </legend>
   <div class="row mb-3">
-    <label for="id_first_name_ro"
-           class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+    <label for="id_first_name_ro" class="field-label">
       First Name
     </label>
-    <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+    <div class="field-control">
       <input type="text"
              name="first_name_ro"
              value="Jon"
@@ -70,11 +66,10 @@
     </div>
   </div>
   <div class="row mb-3">
-    <label for="id_hopes_ro"
-           class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+    <label for="id_hopes_ro" class="field-label">
       Hopes and Dreams
     </label>
-    <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+    <div class="field-control">
       <textarea name="hopes_ro"
                 id="id_hopes_ro"
                 class="form-control-plaintext"
diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/form_invalid.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/form_invalid.html
index 287bad8b1ebe..c17f6c600f84 100644
--- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/form_invalid.html
+++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/form_invalid.html
@@ -1,9 +1,8 @@
 <div class="row mb-3">
-  <label for="id_first_name"
-         class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+  <label for="id_first_name" class="field-label">
     Full Name
   </label>
-  <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+  <div class="field-control">
 
     <!-- this is how an invalid input is marked with the is-invalid class -->
     <input class="form-control is-invalid"
@@ -23,11 +22,10 @@
   </div>
 </div>
 <div class="row mb-3">
-  <label for="id_favorite_color"
-         class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+  <label for="id_favorite_color" class="field-label">
     Favorite Color
   </label>
-  <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+  <div class="field-control">
     <select name="favorite_color"
             class="form-select hqwebapp-select2 is-invalid"
             id="id_favorite_color">
@@ -41,11 +39,10 @@
   </div>
 </div>
 <div class="row mb-3">
-  <label for="id_hopes"
-         class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+  <label for="id_hopes" class="field-label">
     Hopes and Dreams
   </label>
-  <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+  <div class="field-control">
     <textarea name="hopes"
               class="form-control vertical-resize is-invalid"
               id="id_hopes"></textarea>
diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/form_valid.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/form_valid.html
index 3110e9d9b7c6..4d8030c4d83e 100644
--- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/form_valid.html
+++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/form_valid.html
@@ -1,9 +1,8 @@
 <div class="row mb-3">
-  <label for="id_first_name"
-         class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+  <label for="id_first_name" class="field-label">
     Full Name
   </label>
-  <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+  <div class="field-control">
 
     <!-- this is how a valid input is marked with the is-valid class -->
     <input class="form-control is-valid"
@@ -22,11 +21,10 @@
   </div>
 </div>
 <div class="row mb-3">
-  <label for="id_favorite_color"
-         class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+  <label for="id_favorite_color" class="field-label">
     Favorite Color
   </label>
-  <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+  <div class="field-control">
     <select name="favorite_color"
             class="form-select hqwebapp-select2 is-valid"
             id="id_favorite_color">
@@ -40,11 +38,10 @@
   </div>
 </div>
 <div class="row mb-3">
-  <label for="id_hopes"
-         class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+  <label for="id_hopes" class="field-label">
     Hopes and Dreams
   </label>
-  <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+  <div class="field-control">
     <textarea name="hopes"
               class="form-control vertical-resize is-valid"
               id="id_hopes">Traveling to the stars...</textarea>
diff --git a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/placeholder_help_text.html b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/placeholder_help_text.html
index f5ceb293d9c3..77b81fba0d4f 100644
--- a/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/placeholder_help_text.html
+++ b/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/placeholder_help_text.html
@@ -1,9 +1,8 @@
 <div class="row mb-3">
-  <label for="id_email"
-         class="col-form-label col-xs-12 col-sm-4 col-md-4 col-lg-3">
+  <label for="id_email" class="field-label">
     Email
   </label>
-  <div class="col-xs-12 col-sm-8 col-md-8 col-lg-9">
+  <div class="field-control">
     <!-- note the placeholder attribute has a suggested value filled in that will disappear when you type -->
     <input placeholder="name@example.com"
            type="email"

From 76270014cb0c38ab0190ac9a3eeaf101290ac4df Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Wed, 11 Dec 2024 16:43:12 -0500
Subject: [PATCH 07/12] BootstrapCheckboxInput now optional on Bootstrap 5

It is not longer required to update BooleanFields to use BootstrapCheckboxInput since responsive horizontal forms have been restored. Indeed, when the label value is changed to an empty string (label="") it adds awkward vertical space resulting in odd layout unless the form is also properly updated to use CheckboxField (in many cases this step is missed).

BootstrapCheckboxInput may optionally be used if a (new) label value is added to the left, in addition to moving the previous label value to inline_label in the widget and updating the form layout to use CheckboxField. Otherwise the default BooleanField configuration is preferred.

One form was converted back to the simpler version of BooleanField (as well as restoring proper alignment of form actions) as an example in this commit. Other instances exist and may be converted in the future.
---
 .../utils/bootstrap/changes_guide/crispy.md   |  3 --
 corehq/motech/forms.py                        | 33 +++++++++----------
 2 files changed, 15 insertions(+), 21 deletions(-)

diff --git a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/crispy.md b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/crispy.md
index d0a43896efe3..0bc4db071091 100644
--- a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/crispy.md
+++ b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/crispy.md
@@ -6,9 +6,6 @@ section</a> of the style guide.
 
 A few useful things to know about crispy forms in Bootstrap 5:
 
-* Checkboxes, typically based on a `BooleanField`, need to be updated to use the `BootstrapCheckboxInput` as their
-`widget`, as shown in <a href="https://www.commcarehq.org/styleguide/b5/organisms/forms/#crispy-forms-simple"
-target="_blank">this style guide example</a>.
 * As described in <a href="https://www.commcarehq.org/styleguide/b5/organisms/forms/#crispy-forms-simple"
 target="_blank">this section of the style guide</a>, best practice is to use one of HQ's standard helper classes
 for layout. Doing so means you can delete <code>form_class</code>, <code>label_class</code>,
diff --git a/corehq/motech/forms.py b/corehq/motech/forms.py
index fda4f35775c3..655f5130cb43 100644
--- a/corehq/motech/forms.py
+++ b/corehq/motech/forms.py
@@ -10,7 +10,6 @@
 from crispy_forms import layout as crispy
 
 from corehq.apps.hqwebapp import crispy as hqcrispy
-from corehq.apps.hqwebapp.widgets import BootstrapCheckboxInput
 from corehq.motech.const import (
     AUTH_PRESETS,
     AUTH_TYPES,
@@ -70,12 +69,9 @@ class ConnectionSettingsForm(forms.ModelForm):
         required=False,
     )
     skip_cert_verify = forms.BooleanField(
-        label="",
+        label=_('Skip certificate verification'),
         help_text=_('Do not use in a production environment'),
         required=False,
-        widget=BootstrapCheckboxInput(
-            inline_label=_('Skip certificate verification'),
-        ),
     )
     notify_addresses_str = forms.CharField(
         label=_('Addresses to send notifications'),
@@ -166,20 +162,21 @@ def helper(self):
                 id="div_id_oauth_settings",
             ),
             crispy.Field('skip_cert_verify'),
-            self.test_connection_button,
-
-            twbscrispy.StrictButton(
-                _("Save"),
-                type="submit",
-                css_class="btn btn-primary",
-            ),
-            hqcrispy.LinkButton(
-                _("Cancel"),
-                reverse(
-                    ConnectionSettingsListView.urlname,
-                    kwargs={'domain': self.domain},
+            hqcrispy.FormActions(
+                self.test_connection_button,
+                twbscrispy.StrictButton(
+                    _("Save"),
+                    type="submit",
+                    css_class="btn btn-primary",
+                ),
+                hqcrispy.LinkButton(
+                    _("Cancel"),
+                    reverse(
+                        ConnectionSettingsListView.urlname,
+                        kwargs={'domain': self.domain},
+                    ),
+                    css_class="btn btn-outline-primary",
                 ),
-                css_class="btn btn-outline-primary",
             ),
         )
 

From ec7bad9f54b0845618306560f36fc796484b983f Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Thu, 12 Dec 2024 10:57:11 -0500
Subject: [PATCH 08/12] B3 form style extensions

---
 corehq/apps/hqwebapp/crispy.py                   |  6 +++---
 .../hqwebapp/less/_hq/includes/extensions.less   | 16 ++++++++++++++++
 .../hqwebapp/static/hqwebapp/less/bootstrap.less |  1 +
 3 files changed, 20 insertions(+), 3 deletions(-)
 create mode 100644 corehq/apps/hqwebapp/static/hqwebapp/less/_hq/includes/extensions.less

diff --git a/corehq/apps/hqwebapp/crispy.py b/corehq/apps/hqwebapp/crispy.py
index 602ec696c3f6..9f76b2e7ff30 100644
--- a/corehq/apps/hqwebapp/crispy.py
+++ b/corehq/apps/hqwebapp/crispy.py
@@ -13,11 +13,11 @@
 from crispy_forms.layout import LayoutObject
 from crispy_forms.utils import flatatt, get_template_pack, render_field
 
-CSS_LABEL_CLASS = 'col-xs-12 col-sm-4 col-md-4 col-lg-2'
+CSS_LABEL_CLASS = 'field-label'
 CSS_LABEL_CLASS_BOOTSTRAP5 = 'field-label'
-CSS_FIELD_CLASS = 'col-xs-12 col-sm-8 col-md-8 col-lg-6'
+CSS_FIELD_CLASS = 'field-control'
 CSS_FIELD_CLASS_BOOTSTRAP5 = 'field-control'
-CSS_ACTION_CLASS = CSS_FIELD_CLASS + ' col-sm-offset-4 col-md-offset-4 col-lg-offset-2'
+CSS_ACTION_CLASS = CSS_FIELD_CLASS
 
 
 class HQFormHelper(FormHelper):
diff --git a/corehq/apps/hqwebapp/static/hqwebapp/less/_hq/includes/extensions.less b/corehq/apps/hqwebapp/static/hqwebapp/less/_hq/includes/extensions.less
new file mode 100644
index 000000000000..80394fb674dc
--- /dev/null
+++ b/corehq/apps/hqwebapp/static/hqwebapp/less/_hq/includes/extensions.less
@@ -0,0 +1,16 @@
+.field-label {
+  &:extend(.col-xs-12, .col-sm-4, .col-md-4, .col-lg-2);
+}
+
+.field-label + .field-control {
+  &:extend(.col-xs-12, .col-sm-8, .col-md-8, .col-lg-6);
+}
+
+:not(.field-label) + .field-control,
+.form-actions > .field-control:first-child,
+.form-group > .field-control:first-child {
+  &:extend(
+    .col-sm-offset-4, .col-md-offset-4, .col-lg-offset-2,
+    .col-xs-12, .col-sm-8, .col-md-8, .col-lg-6
+  );
+}
diff --git a/corehq/apps/hqwebapp/static/hqwebapp/less/bootstrap.less b/corehq/apps/hqwebapp/static/hqwebapp/less/bootstrap.less
index 29e6b786ecdd..f801d1b4b988 100644
--- a/corehq/apps/hqwebapp/static/hqwebapp/less/bootstrap.less
+++ b/corehq/apps/hqwebapp/static/hqwebapp/less/bootstrap.less
@@ -9,6 +9,7 @@
 // Core variables and mixins
 @import "_hq/includes/variables.less";
 @import "_hq/includes/mixins.less";
+@import "_hq/includes/extensions.less";
 
 // Reset and dependencies
 @import "../../../../../../node_modules/bootstrap/less/normalize.less";

From b089038236fa418388e90f051093803baebfe9b9 Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Thu, 12 Dec 2024 11:27:43 -0500
Subject: [PATCH 09/12] Remove unneeded B5 branching in crispy helper code

---
 corehq/apps/hqwebapp/crispy.py                | 23 +++----------------
 .../hqwebapp/templatetags/hq_shared_tags.py   | 10 ++------
 2 files changed, 5 insertions(+), 28 deletions(-)

diff --git a/corehq/apps/hqwebapp/crispy.py b/corehq/apps/hqwebapp/crispy.py
index 9f76b2e7ff30..8054d7375a3e 100644
--- a/corehq/apps/hqwebapp/crispy.py
+++ b/corehq/apps/hqwebapp/crispy.py
@@ -1,4 +1,3 @@
-import re
 from contextlib import contextmanager
 from django.forms.widgets import DateTimeInput
 from django.template.loader import render_to_string
@@ -14,9 +13,7 @@
 from crispy_forms.utils import flatatt, get_template_pack, render_field
 
 CSS_LABEL_CLASS = 'field-label'
-CSS_LABEL_CLASS_BOOTSTRAP5 = 'field-label'
 CSS_FIELD_CLASS = 'field-control'
-CSS_FIELD_CLASS_BOOTSTRAP5 = 'field-control'
 CSS_ACTION_CLASS = CSS_FIELD_CLASS
 
 
@@ -28,12 +25,7 @@ class HQFormHelper(FormHelper):
     def __init__(self, *args, **kwargs):
         super(HQFormHelper, self).__init__(*args, **kwargs)
         from corehq.apps.hqwebapp.utils.bootstrap import get_bootstrap_version, BOOTSTRAP_5
-        bootstrap_version = get_bootstrap_version()
-        use_bootstrap5 = bootstrap_version == BOOTSTRAP_5
-        if use_bootstrap5:
-            self.label_class = CSS_LABEL_CLASS_BOOTSTRAP5
-            self.field_class = CSS_FIELD_CLASS_BOOTSTRAP5
-            self.use_bootstrap5 = use_bootstrap5
+        self.use_bootstrap5 = get_bootstrap_version() == BOOTSTRAP_5
 
         if 'autocomplete' not in self.attrs:
             self.attrs.update({
@@ -75,15 +67,7 @@ class ErrorsOnlyField(Field):
 
 
 def get_form_action_class():
-    """This is only valid for bootstrap 5"""
-    return CSS_FIELD_CLASS_BOOTSTRAP5
-
-
-def _get_offsets(context):
-    label_class = context.get('label_class', '')
-    use_bootstrap5 = context.get('use_bootstrap5')
-    return (label_class.replace('col', 'offset') if use_bootstrap5
-            else re.sub(r'(xs|sm|md|lg)-', r'\g<1>-offset-', label_class))
+    return CSS_FIELD_CLASS
 
 
 class FormActions(OriginalFormActions):
@@ -101,11 +85,10 @@ def render(self, form, context, template_pack=None, **kwargs):
                 template_pack=template_pack,
             )
         fields_html = mark_safe(fields_html)  # nosec: just concatenated safe fields
-        offsets = _get_offsets(context)
         context.update({
             'formactions': self,
             'fields_output': fields_html,
-            'offsets': offsets,
+            'offsets': '',
             'field_class': context.get('field_class', '')
         })
         return render_to_string(self.template, context.flatten())
diff --git a/corehq/apps/hqwebapp/templatetags/hq_shared_tags.py b/corehq/apps/hqwebapp/templatetags/hq_shared_tags.py
index 70533be19c8f..c17a36543abc 100644
--- a/corehq/apps/hqwebapp/templatetags/hq_shared_tags.py
+++ b/corehq/apps/hqwebapp/templatetags/hq_shared_tags.py
@@ -246,19 +246,13 @@ def can_use_restore_as(request):
 
 @register.simple_tag
 def css_label_class():
-    from corehq.apps.hqwebapp.crispy import CSS_LABEL_CLASS, CSS_LABEL_CLASS_BOOTSTRAP5
-    from corehq.apps.hqwebapp.utils.bootstrap import get_bootstrap_version, BOOTSTRAP_5
-    if get_bootstrap_version() == BOOTSTRAP_5:
-        return CSS_LABEL_CLASS_BOOTSTRAP5
+    from corehq.apps.hqwebapp.crispy import CSS_LABEL_CLASS
     return CSS_LABEL_CLASS
 
 
 @register.simple_tag
 def css_field_class():
-    from corehq.apps.hqwebapp.crispy import CSS_FIELD_CLASS, CSS_FIELD_CLASS_BOOTSTRAP5
-    from corehq.apps.hqwebapp.utils.bootstrap import get_bootstrap_version, BOOTSTRAP_5
-    if get_bootstrap_version() == BOOTSTRAP_5:
-        return CSS_FIELD_CLASS_BOOTSTRAP5
+    from corehq.apps.hqwebapp.crispy import CSS_FIELD_CLASS
     return CSS_FIELD_CLASS
 
 

From 2f9365ca6998fcc65d20312d4485fca4647f5e86 Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Thu, 12 Dec 2024 19:48:59 +0000
Subject: [PATCH 10/12] "Bootstrap 5 Migration - Rebuilt diffs"

---
 .../imports/forms._forms.style.diff.txt       | 32 ++++++++++++-------
 1 file changed, 20 insertions(+), 12 deletions(-)

diff --git a/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/stylesheets/imports/forms._forms.style.diff.txt b/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/stylesheets/imports/forms._forms.style.diff.txt
index 920cf155f13e..d123abd6edd2 100644
--- a/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/stylesheets/imports/forms._forms.style.diff.txt
+++ b/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/stylesheets/imports/forms._forms.style.diff.txt
@@ -1,20 +1,19 @@
 --- 
 +++ 
-@@ -1,356 +1,7 @@
+@@ -1,356 +1,20 @@
 -// FORM ACTIONS from TWBS 2
 -// ------------
 -
 -[ng\:cloak],[ng-cloak],.ng-cloak{
 -  display:none !important
--}
--
++.field-label {
++  @extend .col-form-label, .col-12, .col-sm-4, .col-md-3, .col-lg-2;
+ }
+ 
 -.form-actions {
 -  padding: (@line-height-base * @font-size-base - 1px) 0px @line-height-base * @font-size-base;
 -  margin-top: @line-height-base * 1em;
-+.row > div > .form-check:first-child,
-+.row > div > .input-group > .form-check:first-child {
-+  padding-top: add($input-padding-y, $input-border-width);
-   margin-bottom: 0;
+-  margin-bottom: 0;
 -  background-color: @navbar-default-bg;
 -  border-top: 1px solid @legend-border-color;
 -  .border-bottom-radius(@border-radius-base);
@@ -31,12 +30,17 @@
 -      margin-left: 0;
 -    }
 -  }
--}
--
++.field-label + .field-control {
++  @extend .col-12, .col-sm-8, .col-md-9, .col-lg-10;
+ }
+ 
 -.form-horizontal .control-label {
 -  text-align: left;     // override bootstrap
--}
--
++:not(.field-label) + .field-control,
++.row > .field-control:first-child {
++  @extend .offset-sm-4, .offset-md-3, .offset-lg-2;
+ }
+ 
 -legend .subtext {
 -  font-size: .8em;
 -  color: lighten(@cc-text, 40%);
@@ -357,10 +361,14 @@
 -
 -.controls-text {
 -  padding-top: 7px;
++.row > div > .form-check:first-child,
++.row > div > .input-group > .form-check:first-child {
++  padding-top: add($input-padding-y, $input-border-width);
++  margin-bottom: 0;
  }
  
  .form-hide-actions .form-actions {
-@@ -361,21 +12,34 @@
+@@ -361,21 +25,34 @@
    .validationMessage {
      display: block;
      padding-top: 8px;

From 8549a39fa58c6a27bb9b6ce0e973e63b19c89efa Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Fri, 13 Dec 2024 09:19:57 -0500
Subject: [PATCH 11/12] Remove unused offsets

---
 corehq/apps/hqwebapp/crispy.py                                | 1 -
 .../templates/hqwebapp/crispy/bootstrap3/form_actions.html    | 2 +-
 .../templates/hqwebapp/crispy/bootstrap5/form_actions.html    | 2 +-
 .../hqwebapp/crispy/form_actions.html.diff.txt                | 4 ++--
 4 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/corehq/apps/hqwebapp/crispy.py b/corehq/apps/hqwebapp/crispy.py
index 8054d7375a3e..f86d05b17762 100644
--- a/corehq/apps/hqwebapp/crispy.py
+++ b/corehq/apps/hqwebapp/crispy.py
@@ -88,7 +88,6 @@ def render(self, form, context, template_pack=None, **kwargs):
         context.update({
             'formactions': self,
             'fields_output': fields_html,
-            'offsets': '',
             'field_class': context.get('field_class', '')
         })
         return render_to_string(self.template, context.flatten())
diff --git a/corehq/apps/hqwebapp/templates/hqwebapp/crispy/bootstrap3/form_actions.html b/corehq/apps/hqwebapp/templates/hqwebapp/crispy/bootstrap3/form_actions.html
index 00f51a85d933..1849503aa48d 100644
--- a/corehq/apps/hqwebapp/templates/hqwebapp/crispy/bootstrap3/form_actions.html
+++ b/corehq/apps/hqwebapp/templates/hqwebapp/crispy/bootstrap3/form_actions.html
@@ -1,5 +1,5 @@
 <div {% if formactions.attrs %} {{ formactions.flat_attrs|safe }}{% endif %} class="form-actions">
-    <div class="{{ offsets }} controls {{ field_class }}">
+    <div class="controls {{ field_class }}">
         {{ fields_output }}
     </div>
 </div>
diff --git a/corehq/apps/hqwebapp/templates/hqwebapp/crispy/bootstrap5/form_actions.html b/corehq/apps/hqwebapp/templates/hqwebapp/crispy/bootstrap5/form_actions.html
index fe52406f6134..1c56acebb3e6 100644
--- a/corehq/apps/hqwebapp/templates/hqwebapp/crispy/bootstrap5/form_actions.html
+++ b/corehq/apps/hqwebapp/templates/hqwebapp/crispy/bootstrap5/form_actions.html
@@ -1,5 +1,5 @@
 <div class="form-actions{% if 'form-horizontal' in form_class %} row{% endif %}" {% if formactions.attrs %} {{ formactions.flat_attrs|safe }}{% endif %}>
-  <div class="{{ offsets }} {{ field_class }}">
+  <div class="{{ field_class }}">
     {{ fields_output }}
   </div>
 </div>
diff --git a/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/hqwebapp/crispy/form_actions.html.diff.txt b/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/hqwebapp/crispy/form_actions.html.diff.txt
index ffe8bfd29c8e..c719c0d4debd 100644
--- a/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/hqwebapp/crispy/form_actions.html.diff.txt
+++ b/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/hqwebapp/crispy/form_actions.html.diff.txt
@@ -2,11 +2,11 @@
 +++ 
 @@ -1,5 +1,5 @@
 -<div {% if formactions.attrs %} {{ formactions.flat_attrs|safe }}{% endif %} class="form-actions">
--    <div class="{{ offsets }} controls {{ field_class }}">
+-    <div class="controls {{ field_class }}">
 -        {{ fields_output }}
 -    </div>
 +<div class="form-actions{% if 'form-horizontal' in form_class %} row{% endif %}" {% if formactions.attrs %} {{ formactions.flat_attrs|safe }}{% endif %}>
-+  <div class="{{ offsets }} {{ field_class }}">
++  <div class="{{ field_class }}">
 +    {{ fields_output }}
 +  </div>
  </div>

From 3ad244e86bccc78da040dabd7bc3914661600cbf Mon Sep 17 00:00:00 2001
From: Daniel Miller <dmiller@dimagi.com>
Date: Fri, 13 Dec 2024 09:46:29 -0500
Subject: [PATCH 12/12] Preserve horizontal forms in B5 change guides

---
 .../bootstrap/changes_guide/css-form-group.md      | 14 +++++++-------
 .../utils/bootstrap/changes_guide/css-has-error.md |  8 +++++---
 .../bootstrap/changes_guide/css-has-success.md     |  8 +++++---
 3 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-form-group.md b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-form-group.md
index 7b6ac9575df2..b16cdcaa9098 100644
--- a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-form-group.md
+++ b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-form-group.md
@@ -1,10 +1,10 @@
 `form-group` has been dropped. Use grid utilities instead.
 
-Since we are opting for vertical forms (where the label is directly above the field), take the following actions:
+Take the following actions:
 * Remove the `div` wrapper from the `form-group`'s first child, which contains the field's label.
-* Remove the column classes (`col-lg-2`, etc.) from the `form-group`'s first child, usually a `<label>`,
-which contains the field's label. Most often, this will leave the label with just the `form-label` class.
-* Remove the column classes (`col-lg-2`, etc.) from the `form-group`'s second child, which contains the field
-control (the actual input, which will often use the `form-control` class).  Frequently, this will leave the `<div>`
-without any other classes. If so, and if it has no other attributes, it can be removed.
-* Replace `form-group` with `mb-3`.
+* Replace the column classes (`col-lg-2`, etc.) from the `form-group`'s first child, usually a `<label>`,
+with the `field-label` class. If the first child is a control container such as form actions, do not add
+`field-label`, and instead apply the next step to the first child.
+* Replace the column classes (`col-lg-2`, etc.) of the `form-group`'s second child with `field-control`.
+This `div` should contain the field control (the actual input, which will often use the `form-control` class).
+* Replace `form-group` with `row mb-3`.
diff --git a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-has-error.md b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-has-error.md
index 2863565f0e6b..1b1a074f134c 100644
--- a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-has-error.md
+++ b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-has-error.md
@@ -22,11 +22,13 @@ Previously:
 Now:
 ```
     <div class="row mb-3">
-      <label for="id_error_input" class="form-label">
+      <label for="id_error_input" class="form-label field-label">
         Error Input
       </label>
-      <input type="text" name="error_input" class="form-control is-invalid" id="id_error_input" />
-      <div class='invalid-feedback'>This is an error message.</div>
+      <div class="field-control">
+        <input type="text" name="error_input" class="form-control is-invalid" id="id_error_input" />
+        <div class='invalid-feedback'>This is an error message.</div>
+      </div>
     </div>
 ```
 
diff --git a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-has-success.md b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-has-success.md
index 2750b719c6ea..8f634729276c 100644
--- a/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-has-success.md
+++ b/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-has-success.md
@@ -22,11 +22,13 @@ Previously:
 Now:
 ```
     <div class="row mb-3">
-      <label for="id_happy_input" class="form-label">
+      <label for="id_happy_input" class="form-label field-label">
         Happy Input
       </label>
-      <input type="text" name="happy_input" class="form-control is-valid" id="id_happy_input" />
-      <div class='valid-feedback'>Look at what a good job you did.</div>
+      <div class="field-control">
+        <input type="text" name="happy_input" class="form-control is-valid" id="id_happy_input" />
+        <div class='valid-feedback'>Look at what a good job you did.</div>
+      </div>
     </div>
 ```