feat: add optional hint prop to form fields

packages/component-library/src/components/form/_internal/mt-field-hint/mt-field-hint.vue

@@ -0,0 +1,41 @@
+<template>
+  <span class="mt-field-hint">
+    <mt-icon
+      class="mt-field-hint__icon"
+      name="solid-info-circle"
+      size="var(--scale-size-12)"
+      color="var(--color-icon-secondary-default)"
+      decorative
+    />
+    <span class="mt-field-hint__text">
+      <slot />
+    </span>
+  </span>
+</template>
+
+<script setup lang="ts">
+import MtIcon from "@/components/icons-media/mt-icon/mt-icon.vue";
+</script>
+
+<style scoped>
+.mt-field-hint {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--scale-size-4);
+  padding: var(--scale-size-3);
+  min-width: 0;
+}
+
+.mt-field-hint__icon {
+  flex-shrink: 0;
+}
+
+.mt-field-hint__text {
+  color: var(--color-text-secondary-default);
+  font-family: var(--font-family-body);
+  font-size: var(--font-size-xs, 14px);
+  font-weight: var(--font-weight-regular);
+  line-height: var(--font-line-height-xs);
+}
+</style>

packages/component-library/src/components/form/mt-colorpicker/mt-colorpicker.vue

@@ -235,6 +235,14 @@
     <template #error>
       <mt-field-error v-if="error" :error="error" />
     </template>
+
+    <template #field-hint>
+      <mt-field-hint v-if="showFieldHint">
+        <slot name="hint">
+          {{ hint }}
+        </slot>
+      </mt-field-hint>
+    </template>
   </mt-base-field>
 </template>
 
@@ -244,6 +252,7 @@ import type { PropType } from "vue";
 import { defineComponent } from "vue";
 import { debounce } from "@/utils/debounce";
 import MtBaseField from "../_internal/mt-base-field/mt-base-field.vue";
+import MtFieldHint from "../_internal/mt-field-hint/mt-field-hint.vue";
 import MtFloatingUi from "../../_internal/mt-floating-ui/mt-floating-ui.vue";
 import MtText from "@/components/content/mt-text/mt-text.vue";
 import { createFocusTrap } from "focus-trap";
@@ -257,6 +266,7 @@ export default defineComponent({
 
   components: {
     "mt-base-field": MtBaseField,
+    "mt-field-hint": MtFieldHint,
     "mt-text": MtText,
     "mt-floating-ui": MtFloatingUi,
     "mt-button": MtButton,
@@ -291,6 +301,15 @@ export default defineComponent({
       default: null,
     },
 
+    /**
+     * Optional caption below the field. The `#hint` slot takes precedence when provided.
+     */
+    hint: {
+      type: String as PropType<string | null>,
+      required: false,
+      default: null,
+    },
+
     /**
      * Change the output value which gets emitted and shown in the field.
      * @values auto, hex, hsl, rgb
@@ -494,6 +513,10 @@ export default defineComponent({
       },
     },
 
+    showFieldHint(): boolean {
+      return !!this.$slots.hint || (this.hint != null && String(this.hint).trim() !== "");
+    },
+
     integerAlpha: {
       get(): number {
         return Math.floor(this.alphaValue * 100);

packages/component-library/src/components/form/mt-email-field/mt-email-field.vue

@@ -101,17 +101,20 @@
       :style="{ gridArea: 'error' }"
     />
 
-    <div v-if="$slots.hint" class="mt-email-field__hint" :style="{ gridArea: 'hint' }">
-      <slot name="hint" />
+    <div v-if="showFieldHint" class="mt-email-field__hint" :style="{ gridArea: 'hint' }">
+      <mt-field-hint>
+        <slot name="hint">{{ hint }}</slot>
+      </mt-field-hint>
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
-import { defineProps, onMounted, ref, useTemplateRef, useId } from "vue";
+import { computed, onMounted, ref, useTemplateRef, useId, useSlots } from "vue";
 import MtFieldError from "../_internal/mt-field-error/mt-field-error.vue";
 import MtFieldLabel from "../_internal/mt-field-label/mt-field-label.vue";
 import MtHelpText from "../mt-help-text/mt-help-text.vue";
+import MtFieldHint from "../_internal/mt-field-hint/mt-field-hint.vue";
 import MtIcon from "../../icons-media/mt-icon/mt-icon.vue";
 import MtTooltip from "@/components/overlay/mt-tooltip/mt-tooltip.vue";
 import MtFieldAffix from "../_internal/mt-field-affix/mt-field-affix.vue";
@@ -125,7 +128,7 @@ const model = defineModel({
   type: String,
 });
 
-defineProps<{
+const props = defineProps<{
   disabled?: boolean;
   required?: boolean;
   modelValue?: string;
@@ -141,8 +144,18 @@ defineProps<{
   small?: boolean;
   isInherited?: boolean;
   isInheritanceField?: boolean;
+  /**
+   * Optional caption below the field. The `#hint` slot takes precedence when provided.
+   */
+  hint?: string | null;
 }>();
 
+const slots = useSlots();
+
+const showFieldHint = computed(
+  () => !!slots.hint || (props.hint != null && String(props.hint).trim() !== ""),
+);
+
 defineEmits(["change", "blur", "focus", "inheritance-restore", "inheritance-remove"]);
 
 const id = useId();

packages/component-library/src/components/form/mt-number-field/mt-number-field.vue

@@ -83,7 +83,11 @@
     </template>
 
     <template #field-hint>
-      <slot name="hint" />
+      <mt-field-hint v-if="showFieldHint">
+        <slot name="hint">
+          {{ hint }}
+        </slot>
+      </mt-field-hint>
     </template>
   </mt-base-field>
 </template>
@@ -94,13 +98,15 @@ import type { PropType } from "vue";
 import { defineComponent } from "vue";
 import MtTextField from "../mt-text-field/mt-text-field.vue";
 import MtIcon from "../../icons-media/mt-icon/mt-icon.vue";
+import MtFieldHint from "../_internal/mt-field-hint/mt-field-hint.vue";
 import { useI18n } from "vue-i18n";
 
 export default defineComponent({
   name: "MtNumberField",
 
   components: {
     "mt-icon": MtIcon,
+    "mt-field-hint": MtFieldHint,
   },
 
   extends: MtTextField,

packages/component-library/src/components/form/mt-password-field/mt-password-field.vue

@@ -63,17 +63,20 @@
     </template>
 
     <template #field-hint>
-      <slot name="hint">
-        {{ hint }}
-      </slot>
+      <mt-field-hint v-if="showFieldHint">
+        <slot name="hint">
+          {{ hint }}
+        </slot>
+      </mt-field-hint>
     </template>
   </mt-base-field>
 </template>
 
 <script setup lang="ts">
-import { ref } from "vue";
+import { ref, computed, useSlots } from "vue";
 import MtBaseField from "../_internal/mt-base-field/mt-base-field.vue";
 import MtFieldError from "../_internal/mt-field-error/mt-field-error.vue";
+import MtFieldHint from "../_internal/mt-field-hint/mt-field-hint.vue";
 import MtIcon from "../../icons-media/mt-icon/mt-icon.vue";
 import { useI18n } from "vue-i18n";
 
@@ -85,7 +88,6 @@ const props = withDefaults(
     placeholder?: string;
     disabled?: boolean;
     error?: { code: number; detail: string } | null;
-    // @deprecated - use slot "hint" instead
     hint?: string | null;
     toggable?: boolean;
     name?: string | undefined;
@@ -103,7 +105,6 @@ const props = withDefaults(
     placeholder: "",
     toggable: true,
     error: null,
-    // @deprecated - use slot "hint" instead
     hint: null,
     required: false,
     helpText: "",
@@ -116,6 +117,12 @@ const props = withDefaults(
   },
 );
 
+const slots = useSlots();
+
+const showFieldHint = computed(
+  () => !!slots.hint || (props.hint != null && String(props.hint).trim() !== ""),
+);
+
 const emit = defineEmits<{
   (e: "change", value: string | undefined): void;
   (e: "submit"): void;

packages/component-library/src/components/form/mt-radio-group/mt-radio-group-root.vue

@@ -25,18 +25,21 @@
 
     <mt-field-error :error="error" :style="{ gridArea: 'error' }" />
 
-    <div v-if="$slots.hint" class="mt-radio-group-root__hint" :style="{ gridArea: 'hint' }">
-      <slot name="hint" />
+    <div v-if="showFieldHint" class="mt-radio-group-root__hint" :style="{ gridArea: 'hint' }">
+      <mt-field-hint>
+        <slot name="hint">{{ hint }}</slot>
+      </mt-field-hint>
     </div>
   </div>
 </template>
 
 <script setup lang="ts">
-import { computed, provide, readonly } from "vue";
+import { computed, provide, readonly, useSlots } from "vue";
 import { useId } from "@/composables/useId";
 import MtFieldLabel from "../_internal/mt-field-label/mt-field-label.vue";
 import MtFieldError from "../_internal/mt-field-error/mt-field-error.vue";
 import MtHelpText from "../mt-help-text/mt-help-text.vue";
+import MtFieldHint from "../_internal/mt-field-hint/mt-field-hint.vue";
 
 const props = withDefaults(
   defineProps<{
@@ -49,6 +52,10 @@ const props = withDefaults(
     error?: {
       detail: string;
     };
+    /**
+     * Optional caption below the field. The `#hint` slot takes precedence when provided.
+     */
+    hint?: string | null;
   }>(),
   {
     modelValue: null,
@@ -58,9 +65,16 @@ const props = withDefaults(
     helpText: "",
     name: undefined,
     error: undefined,
+    hint: null,
   },
 );
 
+const slots = useSlots();
+
+const showFieldHint = computed(
+  () => !!slots.hint || (props.hint != null && String(props.hint).trim() !== ""),
+);
+
 const emit = defineEmits<{
   "update:modelValue": [value: string | number | boolean | null];
 }>();

packages/component-library/src/components/form/mt-select/mt-select.vue

@@ -112,7 +112,11 @@
     </template>
 
     <template #mt-select-hint>
-      <slot name="hint" />
+      <mt-field-hint v-if="showFieldHint">
+        <slot name="hint">
+          {{ hint }}
+        </slot>
+      </mt-field-hint>
     </template>
   </mt-select-base>
 </template>
@@ -124,6 +128,7 @@ import { defineComponent } from "vue";
 import { debounce } from "@/utils/debounce";
 import { getPropertyValue } from "@/utils/object";
 import { isPromise } from "@/utils/promise";
+import MtFieldHint from "../_internal/mt-field-hint/mt-field-hint.vue";
 import MtSelectBase from "../_internal/mt-select-base/mt-select-base.vue";
 import MtSelectResultList from "../_internal/mt-select-base/_internal/mt-select-result-list.vue";
 import MtSelectResult from "../_internal/mt-select-base/_internal/mt-select-result.vue";
@@ -135,6 +140,7 @@ export default defineComponent({
   name: "MtSelect",
 
   components: {
+    "mt-field-hint": MtFieldHint,
     "mt-select-base": MtSelectBase,
     "mt-select-result-list": MtSelectResultList,
     "mt-select-selection-list": MtSelectSelectionList,
@@ -353,6 +359,15 @@ export default defineComponent({
       required: false,
       default: false,
     },
+
+    /**
+     * Optional caption below the field. The `#hint` slot takes precedence when provided.
+     */
+    hint: {
+      type: String as PropType<string | null>,
+      required: false,
+      default: null,
+    },
   },
 
   emits: [
@@ -395,6 +410,10 @@ export default defineComponent({
   },
 
   computed: {
+    showFieldHint(): boolean {
+      return !!this.$slots.hint || (this.hint != null && String(this.hint).trim() !== "");
+    },
+
     visibleValues(): any[] {
       if (
         typeof this.currentValue === "string" ||