Move help text above all form fields (#10302)

* Move all help text above fields
* Adjust vertical spacing of form fields and panels
* Move the page title’s help text below the field
* Release notes

CHANGELOG.txt

@@ -30,6 +30,7 @@ Changelog
  * Re-implement styleguide icons list as an auto-generated sequence of tables (Thibaud Colas)
  * Switch styleguide navigation to use panel components and minimap (Thibaud Colas)
  * Explicitly specify `MenuItem.name` for Snippets, Reports, and Settings menu items (Sage Abdullah)
+ * Move the help text of fields and blocks directly below their label for easier reading (Thibaud Colas)
  * Fix: Ensure `label_format` on StructBlock gracefully handles missing variables (Aadi jindal)
  * Fix: Adopt a no-JavaScript and more accessible solution for the 'Reset to default' switch to Gravatar when editing user profile (Loveth Omokaro)
  * Fix: Ensure `Site.get_site_root_paths` works on cache backends that do not preserve Python objects (Jaap Roes)

client/scss/components/_panel.scss

@@ -19,7 +19,7 @@ $header-gap: theme('spacing.1');
 .w-panel__header {
   display: flex;
   align-items: center;
-  margin-bottom: theme('spacing.3');
+  margin-bottom: theme('spacing.[0.5]');
   margin-inline-start: -1 * $mobile-nice-padding;
 
   @include media-breakpoint-up(sm) {

client/scss/components/forms/_field.scss

@@ -40,7 +40,7 @@
 .w-field__label {
   @apply w-label-3;
   display: block;
-  margin-bottom: theme('spacing.3');
+  margin-bottom: 0;
 }
 
 .w-field__wrapper {
@@ -58,6 +58,7 @@
 
 .w-field__input {
   position: relative;
+  padding-top: theme('spacing.[2.5]');
   // This padding gives room for widgets such as comments beside of inputs
   padding-inline-end: calc($comment-button-size + $comment-button-space);
 }

client/scss/components/forms/_help.scss

@@ -1,4 +1,4 @@
 .help {
   @apply w-help-text;
-  margin-top: theme('spacing.[1.5]');
+  margin-top: theme('spacing.[0.5]');
 }

client/scss/components/forms/_title.scss

@@ -23,6 +23,15 @@
     }
   }
 
+  .w-field {
+    display: grid;
+  }
+
+  // Force the help text after the field as the field also visually acts as page heading.
+  .w-field__help {
+    order: 2;
+  }
+
   input,
   textarea,
   .Draftail-Editor .public-DraftEditor-content {

client/src/components/StreamField/blocks/FieldBlock.js

@@ -23,10 +23,10 @@ export class FieldBlock {
           <div class="w-field__errors" id="${prefix}-errors" data-field-errors>
             <svg class="icon icon-warning w-field__errors-icon" aria-hidden="true" hidden><use href="#icon-warning"></use></svg>
           </div>
+          <div id="${prefix}-helptext" data-field-help></div>
           <div class="w-field__input" data-field-input>
             <div data-streamfield-widget></div>
           </div>
-          <div id="${prefix}-helptext" data-field-help></div>
         </div>
       </div>
     `);

client/src/components/StreamField/blocks/__snapshots__/FieldBlock.test.js.snap

@@ -6,10 +6,10 @@ exports[`telepath: wagtail.blocks.FieldBlock catches widget render errors it ren
           <div class=\\"w-field__errors\\" id=\\"the-prefix-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-warning\\"></use></svg>
           <p class=\\"error-message\\"><span>This widget failed to render, please check the console for details</span></p></div>
+          <div id=\\"the-prefix-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <div data-streamfield-widget=\\"\\"></div>
           </div>
-          <div id=\\"the-prefix-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>"
 `;
@@ -20,10 +20,10 @@ exports[`telepath: wagtail.blocks.FieldBlock it renders correctly 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-helptext\\" data-field-help=\\"\\"><p class=\\"help\\">drink <em>more</em> water</p></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix\\" id=\\"the-prefix\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-helptext\\" data-field-help=\\"\\"><p class=\\"help\\">drink <em>more</em> water</p></div>
         </div>
       </div>"
 `;
@@ -34,10 +34,10 @@ exports[`telepath: wagtail.blocks.FieldBlock setError() renders errors 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-warning\\"></use></svg>
           <p class=\\"error-message\\"><span>Field must not contain the letter E</span><span>Field must contain a story about kittens</span></p></div>
+          <div id=\\"the-prefix-helptext\\" data-field-help=\\"\\"><p class=\\"help\\">drink <em>more</em> water</p></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix\\" id=\\"the-prefix\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-helptext\\" data-field-help=\\"\\"><p class=\\"help\\">drink <em>more</em> water</p></div>
         </div>
       </div>"
 `;
@@ -48,10 +48,10 @@ exports[`telepath: wagtail.blocks.FieldBlock with comments enabled it renders co
           <div class=\\"w-field__errors\\" id=\\"the-prefix-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-helptext\\" data-field-help=\\"\\"><p class=\\"help\\">drink <em>more</em> water</p></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix\\" id=\\"the-prefix\\">The widget</p>
           <button type=\\"button\\" aria-label=\\"Add Comment\\" data-comment-add=\\"\\" class=\\"w-field__comment-button w-field__comment-button--add u-hidden\\"><svg class=\\"icon icon-comment-add \\" aria-hidden=\\"true\\"><use href=\\"#icon-comment-add\\"></use></svg><svg class=\\"icon icon-comment-add-reversed \\" aria-hidden=\\"true\\"><use href=\\"#icon-comment-add-reversed\\"></use></svg></button></div>
-          <div id=\\"the-prefix-helptext\\" data-field-help=\\"\\"><p class=\\"help\\">drink <em>more</em> water</p></div>
         </div>
       </div>"
 `;

client/src/components/StreamField/blocks/__snapshots__/ListBlock.test.js.snap

@@ -62,10 +62,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be duplicated 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -124,10 +124,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be duplicated 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -186,10 +186,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be duplicated 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-2-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-2-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-2-value\\" id=\\"the-prefix-2-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-2-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -262,10 +262,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be reordered downward 1`]
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -324,10 +324,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be reordered downward 1`]
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -400,10 +400,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be reordered upward 1`] =
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -462,10 +462,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be reordered upward 1`] =
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -538,10 +538,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be split 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -600,10 +600,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be split 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-2-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-2-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-2-value\\" id=\\"the-prefix-2-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-2-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -662,10 +662,10 @@ exports[`telepath: wagtail.blocks.ListBlock blocks can be split 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -738,10 +738,10 @@ exports[`telepath: wagtail.blocks.ListBlock deleteBlock() deletes a block 1`] =
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -800,10 +800,10 @@ exports[`telepath: wagtail.blocks.ListBlock deleteBlock() deletes a block 1`] =
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -876,10 +876,10 @@ exports[`telepath: wagtail.blocks.ListBlock it renders correctly 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -938,10 +938,10 @@ exports[`telepath: wagtail.blocks.ListBlock it renders correctly 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -1014,10 +1014,10 @@ exports[`telepath: wagtail.blocks.ListBlock setError passes error messages to ch
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -1076,10 +1076,10 @@ exports[`telepath: wagtail.blocks.ListBlock setError passes error messages to ch
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-warning\\"></use></svg>
           <p class=\\"error-message\\"><span>Not as good as the first one</span></p></div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -1152,10 +1152,10 @@ exports[`telepath: wagtail.blocks.ListBlock setError renders non-block errors 1`
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -1214,10 +1214,10 @@ exports[`telepath: wagtail.blocks.ListBlock setError renders non-block errors 1`
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">The widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>

client/src/components/StreamField/blocks/__snapshots__/StreamBlock.test.js.snap

@@ -63,10 +63,10 @@ exports[`telepath: wagtail.blocks.StreamBlock blocks can be duplicated 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">Block A widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -127,10 +127,10 @@ exports[`telepath: wagtail.blocks.StreamBlock blocks can be duplicated 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">Block B widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -191,10 +191,10 @@ exports[`telepath: wagtail.blocks.StreamBlock blocks can be duplicated 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-2-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-2-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-2-value\\" id=\\"the-prefix-2-value\\">Block B widget</p>
           </div>
-          <div id=\\"the-prefix-2-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -270,10 +270,10 @@ exports[`telepath: wagtail.blocks.StreamBlock blocks can be reordered downward 1
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">Block B widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -334,10 +334,10 @@ exports[`telepath: wagtail.blocks.StreamBlock blocks can be reordered downward 1
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">Block A widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -413,10 +413,10 @@ exports[`telepath: wagtail.blocks.StreamBlock blocks can be reordered upward 1`]
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">Block B widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -477,10 +477,10 @@ exports[`telepath: wagtail.blocks.StreamBlock blocks can be reordered upward 1`]
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">Block A widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -556,10 +556,10 @@ exports[`telepath: wagtail.blocks.StreamBlock it renders correctly 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">Block A widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -620,10 +620,10 @@ exports[`telepath: wagtail.blocks.StreamBlock it renders correctly 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">Block B widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -699,10 +699,10 @@ exports[`telepath: wagtail.blocks.StreamBlock it renders menus on opening 1`] =
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">Block A widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -763,10 +763,10 @@ exports[`telepath: wagtail.blocks.StreamBlock it renders menus on opening 1`] =
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">Block B widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -842,10 +842,10 @@ exports[`telepath: wagtail.blocks.StreamBlock setError renders error messages 1`
           <div class=\\"w-field__errors\\" id=\\"the-prefix-0-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-0-value\\" id=\\"the-prefix-0-value\\">Block A widget</p>
           </div>
-          <div id=\\"the-prefix-0-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>
@@ -906,10 +906,10 @@ exports[`telepath: wagtail.blocks.StreamBlock setError renders error messages 1`
           <div class=\\"w-field__errors\\" id=\\"the-prefix-1-value-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-warning\\"></use></svg>
           <p class=\\"error-message\\"><span>Not as good as the first one</span></p></div>
+          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-1-value\\" id=\\"the-prefix-1-value\\">Block B widget</p>
           </div>
-          <div id=\\"the-prefix-1-value-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div>

client/src/components/StreamField/blocks/__snapshots__/StructBlock.test.js.snap

@@ -15,10 +15,10 @@ exports[`telepath: wagtail.blocks.StructBlock it renders correctly 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-heading_text-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-heading_text-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-heading_text\\" id=\\"the-prefix-heading_text\\">Heading widget</p>
           </div>
-          <div id=\\"the-prefix-heading_text-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div><div data-contentpath=\\"size\\">
@@ -28,10 +28,10 @@ exports[`telepath: wagtail.blocks.StructBlock it renders correctly 1`] = `
           <div class=\\"w-field__errors\\" id=\\"the-prefix-size-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-size-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-size\\" id=\\"the-prefix-size\\">Size widget</p>
           </div>
-          <div id=\\"the-prefix-size-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div></div>"
@@ -52,10 +52,10 @@ exports[`telepath: wagtail.blocks.StructBlock setError passes error messages to
           <div class=\\"w-field__errors\\" id=\\"the-prefix-heading_text-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-heading_text-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-heading_text\\" id=\\"the-prefix-heading_text\\">Heading widget</p>
           </div>
-          <div id=\\"the-prefix-heading_text-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div><div data-contentpath=\\"size\\">
@@ -65,10 +65,10 @@ exports[`telepath: wagtail.blocks.StructBlock setError passes error messages to
           <div class=\\"w-field__errors\\" id=\\"the-prefix-size-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-warning\\"></use></svg>
           <p class=\\"error-message\\"><span>This is too big</span></p></div>
+          <div id=\\"the-prefix-size-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-size\\" id=\\"the-prefix-size\\">Size widget</p>
           </div>
-          <div id=\\"the-prefix-size-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div></div>"
@@ -89,10 +89,10 @@ exports[`telepath: wagtail.blocks.StructBlock setError shows non-block errors 1`
           <div class=\\"w-field__errors\\" id=\\"the-prefix-heading_text-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-heading_text-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-heading_text\\" id=\\"the-prefix-heading_text\\">Heading widget</p>
           </div>
-          <div id=\\"the-prefix-heading_text-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div><div data-contentpath=\\"size\\">
@@ -102,10 +102,10 @@ exports[`telepath: wagtail.blocks.StructBlock setError shows non-block errors 1`
           <div class=\\"w-field__errors\\" id=\\"the-prefix-size-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-size-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-size\\" id=\\"the-prefix-size\\">Size widget</p>
           </div>
-          <div id=\\"the-prefix-size-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
           </div></div>"
@@ -119,10 +119,10 @@ exports[`telepath: wagtail.blocks.StructBlock with formTemplate it renders corre
           <div class=\\"w-field__errors\\" id=\\"the-prefix-heading_text-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-heading_text-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-heading_text\\" id=\\"the-prefix-heading_text\\">Heading widget</p>
           </div>
-          <div id=\\"the-prefix-heading_text-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
         <p>and here is the second:</p>
@@ -131,10 +131,10 @@ exports[`telepath: wagtail.blocks.StructBlock with formTemplate it renders corre
           <div class=\\"w-field__errors\\" id=\\"the-prefix-size-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"the-prefix-size-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"the-prefix-size\\" id=\\"the-prefix-size\\">Size widget</p>
           </div>
-          <div id=\\"the-prefix-size-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div>
       </div>"

client/src/entrypoints/contrib/table_block/__snapshots__/table.test.js.snap

@@ -5,34 +5,34 @@ exports[`telepath: wagtail.widgets.TableInput it renders correctly 1`] = `
       <div classname=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <label class=\\"w-field__label\\" for=\\"the-id-handsontable-header\\">Row header</label>
         <div class=\\"w-field w-field--boolean_field w-field--checkbox_input\\" data-field=\\"\\">
-          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
-            <input type=\\"checkbox\\" id=\\"the-id-handsontable-header\\" name=\\"handsontable-header\\" aria-describedby=\\"the-id-handsontable-header-helptext\\">
-          </div>
           <div id=\\"the-id-handsontable-header-helptext\\" data-field-help=\\"\\">
             <div class=\\"help\\">Display the first row as a header.</div>
           </div>
+          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
+            <input type=\\"checkbox\\" id=\\"the-id-handsontable-header\\" name=\\"handsontable-header\\" aria-describedby=\\"the-id-handsontable-header-helptext\\">
+          </div>
         </div>
       </div>
       <div classname=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <label class=\\"w-field__label\\" for=\\"the-id-handsontable-col-header\\">Column header</label>
         <div class=\\"w-field w-field--boolean_field w-field--checkbox_input\\" data-field=\\"\\">
-          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
-            <input type=\\"checkbox\\" id=\\"the-id-handsontable-col-header\\" name=\\"handsontable-col-header\\" aria-describedby=\\"the-id-handsontable-col-header-helptext\\">
-          </div>
           <div id=\\"the-id-handsontable-col-header-helptext\\" data-field-help=\\"\\">
             <div class=\\"help\\">Display the first column as a header.</div>
           </div>
+          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
+            <input type=\\"checkbox\\" id=\\"the-id-handsontable-col-header\\" name=\\"handsontable-col-header\\" aria-describedby=\\"the-id-handsontable-col-header-helptext\\">
+          </div>
         </div>
       </div>
       <div classname=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <label class=\\"w-field__label\\" for=\\"the-id-handsontable-col-caption\\">Table caption</label>
         <div class=\\"w-field w-field--char_field w-field--text_input\\" data-field=\\"\\">
-          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
-            <input type=\\"text\\" id=\\"the-id-handsontable-col-caption\\" name=\\"handsontable-col-caption\\" aria-describedby=\\"the-id-handsontable-col-caption-helptext\\">
-          </div>
           <div id=\\"the-id-handsontable-col-caption-helptext\\" data-field-help=\\"\\">
             <div class=\\"help\\">A heading that identifies the overall topic of the table, and is useful for screen reader users</div>
           </div>
+          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
+            <input type=\\"text\\" id=\\"the-id-handsontable-col-caption\\" name=\\"handsontable-col-caption\\" aria-describedby=\\"the-id-handsontable-col-caption-helptext\\">
+          </div>
         </div>
       </div>
       <div id=\\"the-id-handsontable-container\\"></div>
@@ -45,34 +45,34 @@ exports[`telepath: wagtail.widgets.TableInput translation 1`] = `
       <div classname=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <label class=\\"w-field__label\\" for=\\"the-id-handsontable-header\\">En-tête de ligne</label>
         <div class=\\"w-field w-field--boolean_field w-field--checkbox_input\\" data-field=\\"\\">
-          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
-            <input type=\\"checkbox\\" id=\\"the-id-handsontable-header\\" name=\\"handsontable-header\\" aria-describedby=\\"the-id-handsontable-header-helptext\\">
-          </div>
           <div id=\\"the-id-handsontable-header-helptext\\" data-field-help=\\"\\">
             <div class=\\"help\\">Affichez la première ligne sous forme d'en-tête.</div>
           </div>
+          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
+            <input type=\\"checkbox\\" id=\\"the-id-handsontable-header\\" name=\\"handsontable-header\\" aria-describedby=\\"the-id-handsontable-header-helptext\\">
+          </div>
         </div>
       </div>
       <div classname=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <label class=\\"w-field__label\\" for=\\"the-id-handsontable-col-header\\">En-tête de colonne</label>
         <div class=\\"w-field w-field--boolean_field w-field--checkbox_input\\" data-field=\\"\\">
-          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
-            <input type=\\"checkbox\\" id=\\"the-id-handsontable-col-header\\" name=\\"handsontable-col-header\\" aria-describedby=\\"the-id-handsontable-col-header-helptext\\">
-          </div>
           <div id=\\"the-id-handsontable-col-header-helptext\\" data-field-help=\\"\\">
             <div class=\\"help\\">Affichez la première colonne sous forme d'en-tête.</div>
           </div>
+          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
+            <input type=\\"checkbox\\" id=\\"the-id-handsontable-col-header\\" name=\\"handsontable-col-header\\" aria-describedby=\\"the-id-handsontable-col-header-helptext\\">
+          </div>
         </div>
       </div>
       <div classname=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <label class=\\"w-field__label\\" for=\\"the-id-handsontable-col-caption\\">Légende du tableau</label>
         <div class=\\"w-field w-field--char_field w-field--text_input\\" data-field=\\"\\">
-          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
-            <input type=\\"text\\" id=\\"the-id-handsontable-col-caption\\" name=\\"handsontable-col-caption\\" aria-describedby=\\"the-id-handsontable-col-caption-helptext\\">
-          </div>
           <div id=\\"the-id-handsontable-col-caption-helptext\\" data-field-help=\\"\\">
             <div class=\\"help\\">Un en-tête qui identifie le sujet général du tableau et qui est utile pour les utilisateurs de lecteurs d'écran</div>
           </div>
+          <div classname=\\"w-field__input\\" data-field-input=\\"\\">
+            <input type=\\"text\\" id=\\"the-id-handsontable-col-caption\\" name=\\"handsontable-col-caption\\" aria-describedby=\\"the-id-handsontable-col-caption-helptext\\">
+          </div>
         </div>
       </div>
       <div id=\\"the-id-handsontable-container\\"></div>

client/src/entrypoints/contrib/table_block/table.js

@@ -191,34 +191,34 @@ class TableInput {
       <div className="w-field__wrapper" data-field-wrapper>
         <label class="w-field__label" for="${id}-handsontable-header">${this.strings['Row header']}</label>
         <div class="w-field w-field--boolean_field w-field--checkbox_input" data-field>
-          <div className="w-field__input" data-field-input>
-            <input type="checkbox" id="${id}-handsontable-header" name="handsontable-header" aria-describedby="${id}-handsontable-header-helptext" />
-          </div>
           <div id="${id}-handsontable-header-helptext" data-field-help>
             <div class="help">${this.strings['Display the first row as a header.']}</div>
           </div>
+          <div className="w-field__input" data-field-input>
+            <input type="checkbox" id="${id}-handsontable-header" name="handsontable-header" aria-describedby="${id}-handsontable-header-helptext" />
+          </div>
         </div>
       </div>
       <div className="w-field__wrapper" data-field-wrapper>
         <label class="w-field__label" for="${id}-handsontable-col-header">${this.strings['Column header']}</label>
         <div class="w-field w-field--boolean_field w-field--checkbox_input" data-field>
-          <div className="w-field__input" data-field-input>
-            <input type="checkbox" id="${id}-handsontable-col-header" name="handsontable-col-header" aria-describedby="${id}-handsontable-col-header-helptext" />
-          </div>
           <div id="${id}-handsontable-col-header-helptext" data-field-help>
             <div class="help">${this.strings['Display the first column as a header.']}</div>
           </div>
+          <div className="w-field__input" data-field-input>
+            <input type="checkbox" id="${id}-handsontable-col-header" name="handsontable-col-header" aria-describedby="${id}-handsontable-col-header-helptext" />
+          </div>
         </div>
       </div>
       <div className="w-field__wrapper" data-field-wrapper>
         <label class="w-field__label" for="${id}-handsontable-col-caption">${this.strings['Table caption']}</label>
         <div class="w-field w-field--char_field w-field--text_input" data-field>
-          <div className="w-field__input" data-field-input>
-            <input type="text" id="${id}-handsontable-col-caption" name="handsontable-col-caption" aria-describedby="${id}-handsontable-col-caption-helptext" />
-          </div>
           <div id="${id}-handsontable-col-caption-helptext" data-field-help>
             <div class="help">${this.strings['A heading that identifies the overall topic of the table, and is useful for screen reader users']}</div>
           </div>
+          <div className="w-field__input" data-field-input>
+            <input type="text" id="${id}-handsontable-col-caption" name="handsontable-col-caption" aria-describedby="${id}-handsontable-col-caption-helptext" />
+          </div>
         </div>
       </div>
       <div id="${id}-handsontable-container"></div>

client/src/entrypoints/contrib/typed_table_block/__snapshots__/typed_table_block.test.js.snap

@@ -27,20 +27,20 @@ exports[`wagtail.contrib.typed_table_block.blocks.TypedTableBlock it renders cor
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-0-0-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-0-0-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-0-0\\" id=\\"mytable-cell-0-0\\">Block A widget</p>
           </div>
-          <div id=\\"mytable-cell-0-0-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td><div class=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <div class=\\"w-field w-field--char_field w-field--admin_auto_height_text_input\\" data-field=\\"\\">
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-0-1-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-0-1-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-0-1\\" id=\\"mytable-cell-0-1\\">Block B widget</p>
           </div>
-          <div id=\\"mytable-cell-0-1-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td class=\\"control-cell\\"><input type=\\"hidden\\" name=\\"mytable-row-0-order\\" value=\\"0\\"><button type=\\"button\\" class=\\"button button-secondary button-small button--icon text-replace no delete-row\\" aria-label=\\"Delete row\\" title=\\"Delete row\\">
         <svg class=\\"icon icon-bin icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-bin\\"></use></svg>
@@ -51,20 +51,20 @@ exports[`wagtail.contrib.typed_table_block.blocks.TypedTableBlock it renders cor
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-1-0-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-1-0-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-1-0\\" id=\\"mytable-cell-1-0\\">Block A widget</p>
           </div>
-          <div id=\\"mytable-cell-1-0-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td><div class=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <div class=\\"w-field w-field--char_field w-field--admin_auto_height_text_input\\" data-field=\\"\\">
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-1-1-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-1-1-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-1-1\\" id=\\"mytable-cell-1-1\\">Block B widget</p>
           </div>
-          <div id=\\"mytable-cell-1-1-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td class=\\"control-cell\\"><input type=\\"hidden\\" name=\\"mytable-row-1-order\\" value=\\"1\\"><button type=\\"button\\" class=\\"button button-secondary button-small button--icon text-replace no delete-row\\" aria-label=\\"Delete row\\" title=\\"Delete row\\">
         <svg class=\\"icon icon-bin icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-bin\\"></use></svg>
@@ -117,20 +117,20 @@ exports[`wagtail.contrib.typed_table_block.blocks.TypedTableBlock setError passe
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-0-0-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-0-0-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-0-0\\" id=\\"mytable-cell-0-0\\">Block A widget</p>
           </div>
-          <div id=\\"mytable-cell-0-0-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td><div class=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <div class=\\"w-field w-field--char_field w-field--admin_auto_height_text_input w-field--error\\" data-field=\\"\\">
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-0-1-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-warning\\"></use></svg>
           <p class=\\"error-message\\"><span>This is not enough cheese</span></p></div>
+          <div id=\\"mytable-cell-0-1-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-0-1\\" id=\\"mytable-cell-0-1\\">Block B widget</p>
           </div>
-          <div id=\\"mytable-cell-0-1-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td class=\\"control-cell\\"><input type=\\"hidden\\" name=\\"mytable-row-0-order\\" value=\\"0\\"><button type=\\"button\\" class=\\"button button-secondary button-small button--icon text-replace no delete-row\\" aria-label=\\"Delete row\\" title=\\"Delete row\\">
         <svg class=\\"icon icon-bin icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-bin\\"></use></svg>
@@ -141,20 +141,20 @@ exports[`wagtail.contrib.typed_table_block.blocks.TypedTableBlock setError passe
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-1-0-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-1-0-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-1-0\\" id=\\"mytable-cell-1-0\\">Block A widget</p>
           </div>
-          <div id=\\"mytable-cell-1-0-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td><div class=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <div class=\\"w-field w-field--char_field w-field--admin_auto_height_text_input\\" data-field=\\"\\">
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-1-1-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-1-1-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-1-1\\" id=\\"mytable-cell-1-1\\">Block B widget</p>
           </div>
-          <div id=\\"mytable-cell-1-1-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td class=\\"control-cell\\"><input type=\\"hidden\\" name=\\"mytable-row-1-order\\" value=\\"1\\"><button type=\\"button\\" class=\\"button button-secondary button-small button--icon text-replace no delete-row\\" aria-label=\\"Delete row\\" title=\\"Delete row\\">
         <svg class=\\"icon icon-bin icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-bin\\"></use></svg>
@@ -207,20 +207,20 @@ exports[`wagtail.contrib.typed_table_block.blocks.TypedTableBlock setError shows
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-0-0-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-0-0-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-0-0\\" id=\\"mytable-cell-0-0\\">Block A widget</p>
           </div>
-          <div id=\\"mytable-cell-0-0-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td><div class=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <div class=\\"w-field w-field--char_field w-field--admin_auto_height_text_input\\" data-field=\\"\\">
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-0-1-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-0-1-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-0-1\\" id=\\"mytable-cell-0-1\\">Block B widget</p>
           </div>
-          <div id=\\"mytable-cell-0-1-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td class=\\"control-cell\\"><input type=\\"hidden\\" name=\\"mytable-row-0-order\\" value=\\"0\\"><button type=\\"button\\" class=\\"button button-secondary button-small button--icon text-replace no delete-row\\" aria-label=\\"Delete row\\" title=\\"Delete row\\">
         <svg class=\\"icon icon-bin icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-bin\\"></use></svg>
@@ -231,20 +231,20 @@ exports[`wagtail.contrib.typed_table_block.blocks.TypedTableBlock setError shows
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-1-0-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-1-0-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-1-0\\" id=\\"mytable-cell-1-0\\">Block A widget</p>
           </div>
-          <div id=\\"mytable-cell-1-0-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td><div class=\\"w-field__wrapper\\" data-field-wrapper=\\"\\">
         <div class=\\"w-field w-field--char_field w-field--admin_auto_height_text_input\\" data-field=\\"\\">
           <div class=\\"w-field__errors\\" id=\\"mytable-cell-1-1-errors\\" data-field-errors=\\"\\">
             <svg class=\\"icon icon-warning w-field__errors-icon\\" aria-hidden=\\"true\\" hidden=\\"\\"><use href=\\"#icon-warning\\"></use></svg>
           </div>
+          <div id=\\"mytable-cell-1-1-helptext\\" data-field-help=\\"\\"></div>
           <div class=\\"w-field__input\\" data-field-input=\\"\\">
             <p name=\\"mytable-cell-1-1\\" id=\\"mytable-cell-1-1\\">Block B widget</p>
           </div>
-          <div id=\\"mytable-cell-1-1-helptext\\" data-field-help=\\"\\"></div>
         </div>
       </div></td><td class=\\"control-cell\\"><input type=\\"hidden\\" name=\\"mytable-row-1-order\\" value=\\"1\\"><button type=\\"button\\" class=\\"button button-secondary button-small button--icon text-replace no delete-row\\" aria-label=\\"Delete row\\" title=\\"Delete row\\">
         <svg class=\\"icon icon-bin icon\\" aria-hidden=\\"true\\"><use href=\\"#icon-bin\\"></use></svg>

docs/releases/5.0.md

@@ -48,6 +48,7 @@ Support for adding custom validation logic to StreamField blocks has been formal
  * Re-implement styleguide icons list as an auto-generated sequence of tables (Thibaud Colas)
  * Switch styleguide navigation to use panel components and minimap (Thibaud Colas)
  * Explicitly specify `MenuItem.name` for Snippets, Reports, and Settings menu items (Sage Abdullah)
+ * Move the help text of fields and blocks directly below their label for easier reading (Thibaud Colas)
 
 ### Bug fixes
 

wagtail/admin/templates/wagtailadmin/shared/field.html

@@ -49,6 +49,13 @@
             {% endif %}
         </div>
 
+        <div class="w-field__help" {% if help_text_id %}id="{{ help_text_id }}"{% endif %} data-field-help>
+            {% firstof help_text field.help_text as help_text_value %}
+            {% if help_text_value %}
+                <div class="help">{{ help_text_value }}</div>
+            {% endif %}
+        </div>
+
         {# Separate container for the widget with prefix icon and suffix comment button #}
         <div class="w-field__input" data-field-input>
             {% if icon %}
@@ -72,12 +79,5 @@
                 </button>
             {% endif %}
         </div>
-
-        <div {% if help_text_id %}id="{{ help_text_id }}"{% endif %} data-field-help>
-            {% firstof help_text field.help_text as help_text_value %}
-            {% if help_text_value %}
-                <div class="help">{{ help_text_value }}</div>
-            {% endif %}
-        </div>
     </div>
 </div>