Use Bootstrap form-text and keep form-hint as a deprecated alias (#3059)

.changeset/form-hint-bootstrap.md

@@ -0,0 +1,7 @@
+---
+"@tabler/core": patch
+"@tabler/preview": patch
+"@tabler/docs": patch
+---
+
+Renamed `.form-hint` to Bootstrap's `.form-text`, with `.form-hint` kept as a deprecated alias.

core/scss/_extends.scss

@@ -97,3 +97,12 @@
     @extend [data-bs-theme='dark'];
   }
 }
+
+// `.form-hint` is deprecated, use `.form-text` instead
+// (from `bootstrap/forms/_form-text.scss`).
+.form-hint {
+  @extend .form-text;
+
+  // Kept from the old rule, so an inline element still gets the top margin.
+  display: block;
+}

core/scss/_variables.scss

@@ -2317,9 +2317,6 @@ $callout-padding-x: 1rem !default;
 
 // Form layout
 $form-label-required-gap: 0.25rem !default;
-$form-hint-margin-top: 0.25rem !default;
-$form-hint-label-offset: -0.25rem !default;
-$form-hint-control-margin-top: 0.5rem !default;
 $form-footer-margin-top: 2rem !default;
 $form-fieldset-padding: 1rem !default;
 $form-fieldset-margin-bottom: 1rem !default;

core/scss/ui/_forms.scss

@@ -31,37 +31,6 @@ Form label
   color: $form-secondary-color;
 }
 
-/**
-Form hint
- */
-.form-hint {
-  --form-hint-margin-top: #{$form-hint-margin-top};
-  --form-hint-label-offset: #{$form-hint-label-offset};
-  --form-hint-control-margin-top: #{$form-hint-control-margin-top};
-
-  display: block;
-  color: $form-secondary-color;
-
-  &:last-child {
-    margin-bottom: 0;
-  }
-
-  + .form-control {
-    margin-top: var(--form-hint-margin-top);
-  }
-
-  .form-label + & {
-    margin-top: var(--form-hint-label-offset);
-  }
-
-  .input-group + &,
-  .form-control + &,
-  .form-select + & {
-    margin-top: var(--form-hint-control-margin-top);
-    color: $form-secondary-color;
-  }
-}
-
 /**
 Form select
  */

docs/content/ui/forms/helpers.mdx

@@ -6,7 +6,7 @@ summary: "Form helpers add information around a field: a help popover, a require
 description: Add help icons, hints, and required field markers to forms to give users extra guidance and reduce input errors.
 related: [/ui/forms/elements, /ui/components/popover]
 ---
-import FormHint from '@ui/FormHint.astro';
+import FormText from '@ui/FormText.astro';
 import Example from '@components/Example.astro';
 
 ## Input help
@@ -44,17 +44,17 @@ Use the `.required` class to indicate that a field is required. It will add a re
 
 ## Form hint
 
-Use a form hint to provide users with additional information about a form element. The text will appear below the input field. To add a form hint, use the `.form-hint` class. Give the hint an `id` and point the field at it with `aria-describedby`, so the hint is read together with the field.
+Use helper text to give the user more information about a form element. The text appears below the field. To add it, use the `.form-text` class. The older `.form-hint` class still works as a deprecated alias. Give the hint an `id` and point the field at it with `aria-describedby`, so the hint is read together with the field.
 
 ```html
-<div class="form-hint">We'll never share your email with anyone else.</div>
+<div class="form-text">We'll never share your email with anyone else.</div>
 ```
 
 <Example column>
 <div>
   <label class="form-label" for="helper-email">Email address</label>
   <input type="email" id="helper-email" class="form-control" placeholder="Enter your email address" aria-describedby="helper-email-hint" />
-  <FormHint id="helper-email-hint">We'll never share your email with anyone else.</FormHint>
+  <FormText id="helper-email-hint">We'll never share your email with anyone else.</FormText>
 </div>
 </Example>
 

docs/content/ui/forms/strength.mdx

@@ -144,7 +144,7 @@ document.getElementById('meter').addEventListener('change.bs.strength', (event)
 - The segments are marked `aria-hidden`, so a screen reader reads the level once instead of counting bars.
 - The label under the meter is announced politely, and only when the level changes, so typing does not flood a screen reader.
 - Colour alone does not carry the result: the label says the same thing in words, and the number of filled segments repeats it.
-- A meter says how strong the password is, not which rules a form enforces. Put the rules in `strength-text`, where they show until the first letter, or in a `form-hint` when they have to stay visible the whole time.
+- A meter says how strong the password is, not which rules a form enforces. Put the rules in `strength-text`, where they show until the first letter, or in a `form-text` when they have to stay visible the whole time.
 
 ## Translations
 

docs/content/ui/plugins/color-picker.mdx

@@ -169,7 +169,7 @@ Use the picker like any other form field: a label, the input, and a hint below i
     <div class="mb-0">
       <label class="form-label" for="colorpicker-form">Brand color</label>
       <input type="text" class="form-control d-block" id="colorpicker-form" value="#d6336c" />
-      <small class="form-hint">This color is used for buttons and links.</small>
+      <div class="form-text">This color is used for buttons and links.</div>
     </div>
   </div>
 </div>

shared/components/cards/form/Layout.astro

@@ -1,5 +1,5 @@
 ---
-import FormHint from '@ui/FormHint.astro'
+import FormText from '@ui/FormText.astro'
 import CardTitle from '@ui/CardTitle.astro'
 
 interface Props {
@@ -23,7 +23,7 @@ const idSuffix = horizontal ? '-horizontal' : ''
       <label class={`${labelClass} required`} for={`form-layout-email${idSuffix}`}>Email address</label>
       <div class={horizontal ? 'col' : undefined}>
         <input type="email" id={`form-layout-email${idSuffix}`} class="form-control" aria-describedby={`form-layout-email-hint${idSuffix}`} aria-required="true" placeholder="Enter email" autocomplete="email" />
-        <FormHint as="small" id={`form-layout-email-hint${idSuffix}`}>We'll never share your email with anyone else.</FormHint>
+        <FormText id={`form-layout-email-hint${idSuffix}`}>We'll never share your email with anyone else.</FormText>
       </div>
     </div>
 
@@ -31,7 +31,7 @@ const idSuffix = horizontal ? '-horizontal' : ''
       <label class={`${labelClass} required`} for={`form-layout-password${idSuffix}`}>Password</label>
       <div class={horizontal ? 'col' : undefined}>
         <input type="password" id={`form-layout-password${idSuffix}`} class="form-control" aria-describedby={`form-layout-password-hint${idSuffix}`} aria-required="true" placeholder="Password" />
-        <FormHint as="small" id={`form-layout-password-hint${idSuffix}`}> Your password must be 8-20 characters long, contain letters and numbers, and must not contain spaces, special characters, or emoji. </FormHint>
+        <FormText id={`form-layout-password-hint${idSuffix}`}> Your password must be 8-20 characters long, contain letters and numbers, and must not contain spaces, special characters, or emoji. </FormText>
       </div>
     </div>
 

shared/components/cards/form/Payment.astro

@@ -1,5 +1,5 @@
 ---
-import FormHint from '@ui/FormHint.astro'
+import FormText from '@ui/FormText.astro'
 import CardSubtitle from '@ui/CardSubtitle.astro'
 import Button from '@ui/Button.astro'
 import ButtonList from '@ui/ButtonList.astro'
@@ -20,7 +20,7 @@ import FormGroup from '@ui/FormGroup.astro'
       <div class="col-8">
         <FormGroup label="Card Number" for="payment-form-number">
           <input type="text" id="payment-form-number" class="form-control" placeholder="1234 5678 9012 3456" autocomplete="cc-number" aria-describedby="payment-form-number-hint" />
-          <FormHint as="small" id="payment-form-number-hint">Enter your 16-digit number.</FormHint>
+          <FormText id="payment-form-number-hint">Enter your 16-digit number.</FormText>
         </FormGroup>
       </div>
       <div class="col-4">

shared/components/demo/ThemeSettings.astro

@@ -1,6 +1,6 @@
 ---
 // Offcanvas behavior script lives in BaseLayout (after global scripts).
-import FormHint from '@ui/FormHint.astro'
+import FormText from '@ui/FormText.astro'
 import Icon from '@ui/Icon.astro'
 import Illustration from '@ui/Illustration.astro'
 import Subheader from '@ui/Subheader.astro'
@@ -117,9 +117,9 @@ const tileSvg = (key: string, value: string): string => {
                   <div class="form-label mb-1" id={`theme-setting-${setting.key}`}>
                     {setting.legend}
                   </div>
-                  <FormHint as="p" class="mb-3">
+                  <FormText class="mb-3">
                     {setting.hint}
-                  </FormHint>
+                  </FormText>
 
                   {setting.control === 'color' ? (
                     <div class="row g-2">

shared/ui/FormGroup.astro

@@ -1,9 +1,9 @@
 ---
-// Form group: label (.form-label) + control slot + optional hint (.form-hint).
+// Form group: label (.form-label) + control slot + optional hint (.form-text).
 // When `for` is omitted and associate is true (default), the control is nested
 // inside the label for implicit association. Set associate={false} for groups
 // with multiple controls.
-import FormHint from './FormHint.astro'
+import FormText from './FormText.astro'
 
 interface Props {
   label?: string
@@ -11,7 +11,7 @@ interface Props {
   required?: boolean
   /** .form-label-description at the inline end of the label */
   description?: string
-  /** .form-hint under the control */
+  /** .form-text under the control */
   hint?: string
   /** for attribute of the label — must match the slotted control's id */
   for?: string
@@ -76,5 +76,5 @@ const wrapLabel = Boolean(label && !htmlFor && associate)
       </div>
     )
   }
-  {hint && <FormHint id={hintId}>{hint}</FormHint>}
+  {hint && <FormText id={hintId}>{hint}</FormText>}
 </div>

shared/ui/FormText.astro

@@ -1,19 +1,19 @@
 ---
 import type { HTMLTag } from 'astro/types'
 
-// Form hint text (.form-hint).
+// Helper text under a form control (.form-text).
 
 type PolymorphicProps = { as?: HTMLTag }
 
 interface Props extends PolymorphicProps {
   class?: string
-  /** id so a control can reference the hint via aria-describedby */
+  /** id so a control can reference the text via aria-describedby */
   id?: string | undefined
 }
 
 const { as: Tag = 'div', class: className, id }: Props = Astro.props
 ---
 
-<Tag class:list={['form-hint', className]} {...id ? { id } : {}}>
+<Tag class:list={['form-text', className]} {...id ? { id } : {}}>
   <slot />
 </Tag>