fix(many): only reference rendered messages via aria-describedby

Address PR review feedback on the form-field messages work:

- The aria-describedby wiring referenced a messages element even when the message had no
  text. FormField (via FormFieldLayout) only renders messages that have text, so this left
  a dangling reference — e.g. DateTimeInput passes an empty-text error message to its
  sub-inputs just to force the invalid styling. Gate the wiring on messages that actually
  render (`messages.some(m => !!m.text)`). Checkbox is unchanged here: it renders messages
  via FormFieldMessages on `length > 0`, so its reference always resolves.
- Drop the now-unnecessary type casts around the aria-* reads in Checkbox, TextArea,
  NumberInput and RangeInput.
- TextInput: expand the comment to explain why messages must be kept out of the name.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: git-nandor

packages/ui-checkbox/src/Checkbox/v2/index.tsx

@@ -349,16 +349,12 @@ class Checkbox extends Component<CheckboxProps, CheckboxState> {
             // Keep messages in the description so the accessible name contains only the label.
             aria-labelledby={
               this.hasMessages
-                ? ((props as Record<string, unknown>)[
-                    'aria-labelledby'
-                  ] as string) || this._labelId
-                : ((props as Record<string, unknown>)['aria-labelledby'] as
-                    | string
-                    | undefined)
+                ? props['aria-labelledby'] || this._labelId
+                : props['aria-labelledby']
             }
             aria-describedby={
               [
-                (props as Record<string, unknown>)['aria-describedby'],
+                props['aria-describedby'],
                 this.hasMessages ? this._messagesId : null
               ]
                 .filter(Boolean)

packages/ui-number-input/src/NumberInput/v2/index.tsx

@@ -124,7 +124,9 @@ const NumberInput = forwardRef<NumberInputHandle, NumberInputProps>(
     // via `aria-describedby` and point the accessible name at the label text
     // only via `aria-labelledby`, so the messages are announced as a
     // description rather than as part of the control's name.
-    const hasMessages = !!messages && messages.length > 0
+    // Only when a message actually renders (has text); FormField skips
+    // empty-text messages, so otherwise aria-describedby would dangle.
+    const hasMessages = !!messages?.some((m) => !!m.text)
     const messagesId = id ? `${id}-messages` : undefined
     const labelId = id ? `${id}-label` : undefined
 
@@ -328,7 +330,9 @@ const NumberInput = forwardRef<NumberInputHandle, NumberInputProps>(
 
     const label = callRenderProp(renderLabel)
 
-    const passedProps = passthroughProps(rest)
+    // `passthroughProps` is typed with `unknown` values; widen once here so the
+    // aria-* reads below don't each need a cast.
+    const passedProps = passthroughProps(rest) as Record<string, any>
 
     // Don't render until we have an ID
     if (!id) {
@@ -366,8 +370,8 @@ const NumberInput = forwardRef<NumberInputHandle, NumberInputProps>(
               }
               aria-labelledby={
                 hasMessages
-                  ? (passedProps['aria-labelledby'] as string) || labelId
-                  : (passedProps['aria-labelledby'] as string | undefined)
+                  ? passedProps['aria-labelledby'] || labelId
+                  : passedProps['aria-labelledby']
               }
               id={id}
               type={allowStringValue ? 'text' : 'number'}

packages/ui-range-input/src/RangeInput/v2/index.tsx

@@ -186,16 +186,15 @@ class RangeInput extends Component<RangeInputProps, RangeInputState> {
   render() {
     const { formatValue, disabled, readOnly, messages } = this.props
 
-    const props = omitProps(this.props, RangeInput.allowedProps) as Record<
-      string,
-      unknown
-    >
+    const props = omitProps(this.props, RangeInput.allowedProps)
 
     // Messages live inside the wrapping <label>. Reference them from the input
     // via `aria-describedby` and point the accessible name at the label text
     // only via `aria-labelledby`, so the messages are announced as a
     // description rather than as part of the control's name.
-    const hasMessages = !!messages && messages.length > 0
+    // Only when a message actually renders (has text); FormField skips
+    // empty-text messages, so otherwise aria-describedby would dangle.
+    const hasMessages = !!messages?.some((m) => !!m.text)
     const messagesId = `${this.id}-messages`
     const labelId = `${this.id}-label`
 
@@ -231,8 +230,8 @@ class RangeInput extends Component<RangeInputProps, RangeInputState> {
             }
             aria-labelledby={
               hasMessages
-                ? (props['aria-labelledby'] as string) || labelId
-                : (props['aria-labelledby'] as string | undefined)
+                ? props['aria-labelledby'] || labelId
+                : props['aria-labelledby']
             }
           />
           {this.renderValue()}

packages/ui-text-area/src/TextArea/v2/index.tsx

@@ -132,7 +132,9 @@ const TextArea = forwardRef<TextAreaElement, TextAreaProps>((props, ref) => {
   // via `aria-describedby` and point the accessible name at the label text only
   // via `aria-labelledby`, so the messages are announced as a description
   // rather than as part of the control's name.
-  const hasMessages = !!messages && messages.length > 0
+  // Only when a message actually renders (has text); FormField skips empty-text
+  // messages, so otherwise aria-describedby would dangle.
+  const hasMessages = !!messages?.some((m) => !!m.text)
   const messagesId = `${id}-messages`
   const labelId = `${id}-label`
 
@@ -402,20 +404,14 @@ const TextArea = forwardRef<TextAreaElement, TextAreaProps>((props, ref) => {
       aria-required={required}
       aria-invalid={isInvalid ? 'true' : undefined}
       aria-describedby={
-        [
-          (rest as Record<string, unknown>)['aria-describedby'],
-          hasMessages ? messagesId : null
-        ]
+        [rest['aria-describedby'], hasMessages ? messagesId : null]
           .filter(Boolean)
           .join(' ') || undefined
       }
       aria-labelledby={
         hasMessages
-          ? ((rest as Record<string, unknown>)['aria-labelledby'] as string) ||
-            labelId
-          : ((rest as Record<string, unknown>)['aria-labelledby'] as
-              | string
-              | undefined)
+          ? rest['aria-labelledby'] || labelId
+          : rest['aria-labelledby']
       }
       disabled={disabled}
       readOnly={readOnly}

packages/ui-text-input/src/TextInput/v2/index.tsx

@@ -160,7 +160,12 @@ class TextInput extends Component<TextInputProps> {
   }
 
   get hasMessages() {
-    return !!this.props.messages && this.props.messages.length > 0
+    // FormField only renders messages that have text, so only treat the field
+    // as having messages then. Otherwise the input's `aria-describedby` would
+    // reference a messages element that was never rendered — e.g. DateTimeInput
+    // passes an empty-text error message to its sub-inputs just to force the
+    // invalid styling.
+    return !!this.props.messages?.some((m) => !!m.text)
   }
 
   get invalid() {
@@ -233,12 +238,15 @@ class TextInput extends Component<TextInputProps> {
     if (props['aria-describedby']) {
       descriptionIds = `${props['aria-describedby']}`
     }
-    // When there are messages, associate them with the input as its description
-    // (they are rendered by FormField with `id={this._messagesId}`) and point
-    // the accessible name at the label text only via `aria-labelledby`. This
-    // keeps the messages — which live inside the wrapping <label> — out of the
-    // control's name while preserving the click-on-label focus behavior.
-    // Any consumer-provided `aria-labelledby` takes precedence.
+    // FormField renders this control and its `messages` inside a single wrapping
+    // <label>, so by default the messages' text becomes part of the control's
+    // accessible *name* (e.g. "Password Password must be at least 6 characters"),
+    // which is confusing and repeats on every announcement. Messages should be
+    // the field's *description* instead. So when there are messages, reference
+    // them via `aria-describedby` and pin the name to the label text only via
+    // `aria-labelledby`. Keeping the messages inside the <label> preserves the
+    // native click-on-label focus behavior. A consumer-provided `aria-labelledby`
+    // takes precedence.
     let labelledById = props['aria-labelledby'] as string | undefined
     if (this.hasMessages) {
       descriptionIds = [descriptionIds, this._messagesId]