Form Field Wrapper

1/**
2 * FormFieldWrapper Component
3 *
4 * Unified wrapper for form controls with label, validation states, and messages.
5 * Eliminates code duplication across InputGlass, SliderGlass, ComboBoxGlass, etc.
6 *
7 * Handles:
8 * - Label with optional required indicator
9 * - Error messages (highest priority, red)
10 * - Success messages (green, shown if no error)
11 * - Consistent spacing and typography
12 */
13 
14import { forwardRef, type ReactNode, type HTMLAttributes } from 'react';
15import { cn } from '@/lib/utils';
16 
17/**
18 * Props for the FormFieldWrapper component
19 */
20export interface FormFieldWrapperProps extends HTMLAttributes<HTMLDivElement> {
21  /**
22   * Label text displayed above the field
23   */
24  label?: string;
25 
26  /**
27   * Error message - takes priority over success
28   * Displays in red below the field
29   */
30  error?: string;
31 
32  /**
33   * Success message - displays in green if no error
34   * Displays below the field
35   */
36  success?: string;
37 
38  /**
39   * ID to link label with input via htmlFor
40   * Should match the input's id attribute
41   */
42  htmlFor?: string;
43 
44  /**
45   * Shows red asterisk (*) next to label
46   * @default false
47   */
48  required?: boolean;
49 
50  /**
51   * The form control element(s) to wrap
52   */
53  children: ReactNode;
54}
55 
56/**
57 * FormFieldWrapper component
58 *
59 * Provides consistent structure for form fields with labels and validation messages.
60 * Used by InputGlass, SliderGlass, and other form components.
61 *
62 * @example
63 * ```tsx
64 * // Basic usage
65 * <FormFieldWrapper label="Email" htmlFor="email-input">
66 *   <input id="email-input" type="email" />
67 * </FormFieldWrapper>
68 *
69 * // With validation
70 * <FormFieldWrapper
71 *   label="Username"
72 *   error="Username is required"
73 *   required
74 *   htmlFor="username"
75 * >
76 *   <input id="username" />
77 * </FormFieldWrapper>
78 *
79 * // Success state
80 * <FormFieldWrapper
81 *   label="Password"
82 *   success="Strong password"
83 *   htmlFor="password"
84 * >
85 *   <input id="password" type="password" />
86 * </FormFieldWrapper>
87 * ```
88 */
89export const FormFieldWrapper = forwardRef<HTMLDivElement, FormFieldWrapperProps>(
90  (
91    {
92      label,
93      error,
94      success,
95      htmlFor,
96      required,
97      className,
98      children,
99      ...props
100    },
101    ref
102  ) => {
103    return (
104      <div
105        ref={ref}
106        className={cn('flex flex-col gap-1 md:gap-1.5', className)}
107        {...props}
108      >
109        {label && (
110          <label
111            htmlFor={htmlFor}
112            className="text-xs md:text-sm font-medium"
113// … truncated