Enciphered.Blazor.UIComponents/docs/components/form-inputs.md

# Form Inputs

All input components extend a shared `InputBase<T>` class that provides consistent styling, htmx validation integration, and parameter unification. When placed inside an `HtmxForm` with a `FormField`, inputs automatically attach `hx-post`, `hx-trigger="blur"`, and `hx-target` attributes for real-time per-field validation.

---

## TextInput

A standard text input for strings. Supports all HTML input types (`text`, `email`, `password`, `search`, etc.).

```razor
<FormField Label="Full Name" For="name">
    <TextInput Id="name" Name="name" Placeholder="Jane Doe" />
</FormField>

<FormField Label="Email" For="email">
    <TextInput Id="email" Name="email" Type="email" Placeholder="jane@example.com" />
</FormField>

<FormField Label="Password" For="password">
    <TextInput Id="password" Name="password" Type="password" Placeholder="••••••••" />
</FormField>
```

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `Type` | `string` | `"text"` | HTML input type |
| `Id` | `string?` | — | Input element ID |
| `Name` | `string?` | — | Form field name (submitted to the server) |
| `Value` | `string?` | — | Current value |
| `Placeholder` | `string?` | — | Placeholder text |
| `Disabled` | `bool` | `false` | Disables the input |
| `ReadOnly` | `bool` | `false` | Makes the input read-only |
| `Class` | `string?` | — | Additional CSS classes |

---

## NumberInput

A numeric input with built-in increment/decrement stepper buttons. Hides the browser's native spinner.

```razor
<FormField Label="Age" For="age">
    <NumberInput Id="age" Name="age" Placeholder="25" Min="0" Max="150" />
</FormField>

<FormField Label="Quantity" For="quantity">
    <NumberInput Id="quantity" Name="quantity" Value="1" Min="1" Max="99" Step="1" />
</FormField>
```

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `Min` | `string?` | — | Minimum allowed value |
| `Max` | `string?` | — | Maximum allowed value |
| `Step` | `string?` | — | Step increment |
| `Value` | `double?` | — | Current numeric value |

Inherits all parameters from `InputBase<double?>` (`Id`, `Name`, `Placeholder`, `Disabled`, `ReadOnly`, `Class`).

The stepper buttons are disabled when the value reaches `Min` or `Max`. They are hidden when `Disabled` or `ReadOnly` is true.

---

## DateInput

A date picker that combines a hidden `<input type="date">` with a popover calendar. Users select dates through the calendar UI — the native date picker chrome is hidden.

```razor
<FormField Label="Birth Date" For="birthdate">
    <DateInput Id="birthdate" Name="birthdate" Placeholder="Select your birth date" />
</FormField>
```

### How it works

1. A hidden `<input type="date">` holds the actual form value in `yyyy-MM-dd` format
2. A styled button trigger shows the selected date (or placeholder)
3. Clicking the trigger opens a `Popover` containing a `Calendar` component
4. Selecting a day updates the hidden input and closes the popover

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `Value` | `DateOnly?` | — | Currently selected date |
| `Min` | `string?` | — | Minimum date |
| `Max` | `string?` | — | Maximum date |
| `Placeholder` | `string?` | `"Select date"` | Trigger button placeholder |

Inherits all parameters from `InputBase<DateOnly?>`.

---

## TimeInput

A time picker that combines a hidden `<input type="time">` with a popover time picker. Features scrollable hour/minute columns and AM/PM toggle.

```razor
<FormField Label="Preferred Time" For="preferredtime">
    <TimeInput Id="preferredtime" Name="preferredtime" />
</FormField>
```

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `Value` | `TimeOnly?` | — | Currently selected time |
| `Step` | `string?` | — | Minute step interval |
| `Use12Hour` | `bool` | `true` | 12-hour format with AM/PM |
| `Placeholder` | `string?` | `"Select time"` | Trigger button placeholder |

Inherits all parameters from `InputBase<TimeOnly?>`.

---

## DateTimeInput

Combines a date picker and time picker side by side for selecting both date and time. Internally manages a hidden `<input type="datetime-local">` plus two helper hidden inputs for the date and time parts.

```razor
<FormField Label="Appointment" For="appointment">
    <DateTimeInput Id="appointment" Name="appointment" />
</FormField>
```

### How it works

1. A hidden `<input type="datetime-local">` holds the combined value in `yyyy-MM-ddTHH:mm` format
2. Two helper hidden inputs hold the date-part and time-part separately
3. Two popover triggers (calendar + time picker) are displayed side by side
4. The `forms.js` module automatically combines the date-part and time-part values into the main hidden input

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `Value` | `DateTime?` | — | Currently selected date and time |
| `Min` | `string?` | — | Minimum datetime |
| `Max` | `string?` | — | Maximum datetime |
| `Step` | `string?` | — | Minute step interval |
| `Placeholder` | `string?` | `"Select date"` | Date trigger placeholder |

Inherits all parameters from `InputBase<DateTime?>`.

---

## FormField

Wraps an input with a label, description, and error placeholder. The error element is used by htmx to display server-side validation messages.

```razor
<FormField Label="Email" For="email" Description="We'll never share your email.">
    <TextInput Id="email" Name="email" Type="email" />
</FormField>
```

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `Label` | `string?` | — | Label text rendered as `<label>` |
| `For` | `string?` | — | Links the label to the input, and identifies the field for validation errors |
| `Description` | `string?` | — | Helper text below the input |
| `Error` | `string?` | — | Pre-set error message (for server-rendered errors) |
| `Class` | `string?` | — | Additional CSS classes on the wrapper |
| `LabelClass` | `string?` | — | Additional CSS classes on the label |

### How validation errors are displayed

`FormField` renders a `<p data-field-error="fieldname">` element. When htmx receives a validation response, it swaps this element with the server's HTML fragment (which includes or hides the error message). This is the core mechanism for per-field validation.

---

## InputBase

All input components inherit from `InputBase<TValue>`, which provides:

- **Common parameters**: `Id`, `Name`, `Value`, `Placeholder`, `Disabled`, `ReadOnly`, `Class`
- **Computed CSS**: A consistent input style using Tailwind classes
- **htmx auto-wiring**: When `ValidationEndpoint` and `FieldName` cascading values are present (provided by `HtmxForm` and `FormField`), the input automatically gets:
  - `hx-post` pointing to the validation endpoint
  - `hx-trigger="blur"` for on-blur validation
  - `hx-target="next [data-field-error]"` to update the error element
  - `hx-swap="outerHTML"` for full element replacement
  - `hx-include="this"` to send only this input's value
  - `hx-vals='{"_field": "fieldname"}'` to identify which field is being validated