# MonthField

```ts
import { MonthField } from 'cx/widgets';
```

The `MonthField` widget is used for selecting months or month ranges. It displays a dropdown with a month picker for easy selection.

```tsx
import { createModel } from "cx/data";
import { bind, LabelsTopLayout } from "cx/ui";
import { MonthField } from "cx/widgets";

interface Model {
  month: string;
  from: string;
  to: string;
  placeholder: string;
}

const m = createModel<Model>();

export default (
  <LabelsTopLayout columns={2}>
    <MonthField label="Single Month" value={bind(m.month, "2024-06-01")} />
    <MonthField
      label="Month Range"
      range
      from={bind(m.from, "2024-03-01")}
      to={bind(m.to, "2024-06-01")}
    />
    <MonthField
      label="Placeholder"
      value={m.placeholder}
      placeholder="Select a month..."
    />
    <MonthField label="Disabled" value={m.month} disabled />
  </LabelsTopLayout>
);

```

## Range Selection

In range mode, the month picker provides quick selection options:

- **Click on a year** (e.g., "2024") to select the entire year (Jan - Dec)
- **Click on a quarter** (Q1, Q2, Q3, Q4) to select all three months in that quarter
- **Drag across months** to select a custom range, similar to selecting text

## Configuration

### Core Properties

| Property      | Type      | Default      | Description                                                   |
| ------------- | --------- | ------------ | ------------------------------------------------------------- |
| `value`       | `string`  | `null`       | Selected month (for single mode). Accepts Date or ISO string  |
| `range`       | `boolean` | `false`      | Enable range selection mode                                   |
| `from`        | `string`  |              | Start of selected range (when `range` is `true`)              |
| `to`          | `string`  |              | End of selected range (when `range` is `true`)                |
| `inclusiveTo` | `boolean` | `false`      | Whether the `to` date is included in the range                |
| `placeholder` | `string`  |              | Placeholder text when no value is selected                    |
| `disabled`    | `boolean` | `false`      | Disables the field                                            |
| `readOnly`    | `boolean` | `false`      | Makes the field read-only                                     |
| `icon`        | `string`  | `"calendar"` | Icon displayed on the left side of the input                  |

### Date Constraints

| Property       | Type      | Default | Description                                           |
| -------------- | --------- | ------- | ----------------------------------------------------- |
| `minValue`     | `string`  |         | Minimum selectable month                              |
| `minExclusive` | `boolean` | `false` | If `true`, the minimum month itself is not selectable |
| `maxValue`     | `string`  |         | Maximum selectable month                              |
| `maxExclusive` | `boolean` | `false` | If `true`, the maximum month itself is not selectable |

### Appearance

| Property          | Type      | Default | Description                                        |
| ----------------- | --------- | ------- | -------------------------------------------------- |
| `showClear`       | `boolean` | `true`  | Shows a clear button when value is present         |
| `hideClear`       | `boolean` | `false` | Hides the clear button (opposite of `showClear`)   |
| `alwaysShowClear` | `boolean` | `false` | Shows clear button even when field is required     |
| `inputStyle`      | `object`  |         | CSS styles for the input element                   |
| `inputClass`      | `string`  |         | CSS class for the input element                    |

### Validation

| Property               | Type     | Default                          | Description                                       |
| ---------------------- | -------- | -------------------------------- | ------------------------------------------------- |
| `minValueErrorText`    | `string` | `"Select {0:d} or later."`       | Error message when value is before minimum        |
| `minExclusiveErrorText`| `string` | `"Select a date after {0:d}."`   | Error message when value equals exclusive minimum |
| `maxValueErrorText`    | `string` | `"Select {0:d} or before."`      | Error message when value is after maximum         |
| `maxExclusiveErrorText`| `string` | `"Select a date before {0:d}."`  | Error message when value equals exclusive maximum |
| `inputErrorText`       | `string` | `"Invalid date entered"`         | Error message for invalid input                   |

### Behavior

| Property            | Type      | Default        | Description                                           |
| ------------------- | --------- | -------------- | ----------------------------------------------------- |
| `autoFocus`         | `boolean` | `false`        | Automatically focuses the field on mount              |
| `reactOn`           | `string`  | `"enter blur"` | Events that trigger value update                      |
| `encoding`          | `function`|                | Custom function to encode Date objects before storing |
| `dropdownOptions`   | `object`  |                | Additional configuration for the dropdown             |
| `monthPickerOptions`| `object`  |                | Configuration options for the MonthPicker in dropdown |