@bridge-ui/vue 0.0.8 → 0.0.9

package/docs/components/CalendarDate.md

@@ -0,0 +1,71 @@
+# CalendarDate
+
+Date-grid panel (weekdays + day tiles). Building block used by `Calendar` and `CalendarRange`.
+
+## Import
+
+```ts
+import { CalendarDate } from "@bridge-ui/vue/Components/CalendarDate";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<CalendarDate v-model="date" />
+
+<CalendarDate
+  range
+  v-model="range"
+  :view-date="month"
+  @view-date-change="month = $event"
+/>
+```
+
+## Props
+
+| Prop              | Type                      | Default     | Description                                       |
+| ----------------- | ------------------------- | ----------- | ------------------------------------------------- |
+| `classes`         | `CalendarDateClasses`     | —           | Classes for calendar regions.                     |
+| `color`           | `CalendarColor`           | `"primary"` | Accent color for day tiles.                       |
+| `customProps`     | `CalendarDateCustomProps` | —           | Extra props for internal parts.                   |
+| `defaultValue`    | `DatePickerModel`         | `null`      | Uncontrolled initial value.                       |
+| `disabled`        | `boolean`                 | `false`     | Disables the entire calendar.                     |
+| `disableDates`    | `Date[]`                  | —           | Dates that cannot be selected.                    |
+| `disableMonths`   | `number[]`                | —           | Month indexes that cannot be selected.            |
+| `disableYears`    | `number[]`                | —           | Years that cannot be selected.                    |
+| `hideOutsideDays` | `boolean`                 | `false`     | Hides days that fall outside the displayed month. |
+| `hideWeekdays`    | `boolean`                 | `false`     | Hides the weekday header row.                     |
+| `maxDate`         | `Date`                    | —           | Latest selectable date.                           |
+| `minDate`         | `Date`                    | —           | Earliest selectable date.                         |
+| `multiple`        | `boolean`                 | `false`     | Allows selecting multiple dates.                  |
+| `previewDate`     | `Date \| null`            | —           | Hovered date used for incomplete-range preview.   |
+| `range`           | `boolean`                 | `false`     | Selects a start/end range.                        |
+| `readOnly`        | `boolean`                 | `false`     | Prevents selection.                               |
+| `rounded`         | `CalendarRounded`         | `"md"`      | Border radius of day tiles.                       |
+| `slots`           | `{ day?: … }`             | —           | Named slots (`day`).                              |
+| `startOfWeek`     | `StartOfWeek`             | `0`         | First day of the week.                            |
+| `timeZone`        | `string`                  | —           | IANA time zone.                                   |
+| `tokens`          | `CalendarDateTokens`      | —           | Token overrides.                                  |
+| `value`           | `DatePickerModel`         | —           | Controlled selection model.                       |
+| `viewDate`        | `Date`                    | —           | Month currently displayed in the grid.            |
+
+### v-model
+
+| Prop / Event        | Type                               | Default | Description                           |
+| ------------------- | ---------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `DatePickerModel`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: DatePickerModel) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event                      | Payload                    | Description                                        |
+| -------------------------- | -------------------------- | -------------------------------------------------- |
+| `v-on:change`              | `(value: DatePickerModel)` | Emitted when the selection model changes.          |
+| `v-on:preview-date-change` | `(date: Date \| null)`     | Emitted when the range-preview hover date changes. |
+| `v-on:view-date-change`    | `(date: Date)`             | Emitted when the displayed month should change.    |
+
+## Related components
+
+Calendar, CalendarMonth, CalendarYear, CalendarRange

package/docs/components/CalendarMonth.md

@@ -0,0 +1,52 @@
+# CalendarMonth
+
+Month-grid panel (`0`–`11`). Building block used by `Calendar` and `CalendarRange`.
+
+## Import
+
+```ts
+import { CalendarMonth } from "@bridge-ui/vue/Components/CalendarMonth";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<CalendarMonth :year="2026" v-model="month" />
+```
+
+## Props
+
+| Prop            | Type                       | Default      | Description                                          |
+| --------------- | -------------------------- | ------------ | ---------------------------------------------------- |
+| `classes`       | `CalendarMonthClasses`     | —            | Classes for calendar regions.                        |
+| `color`         | `CalendarColor`            | `"primary"`  | Accent color for month tiles.                        |
+| `customProps`   | `CalendarMonthCustomProps` | —            | Extra props for internal parts.                      |
+| `disabled`      | `boolean`                  | `false`      | Disables the entire month grid.                      |
+| `disableMonths` | `number[]`                 | —            | Month indexes that cannot be selected.               |
+| `maxDate`       | `Date`                     | —            | Latest selectable date (bounds months for `year`).   |
+| `minDate`       | `Date`                     | —            | Earliest selectable date (bounds months for `year`). |
+| `readOnly`      | `boolean`                  | `false`      | Prevents selection.                                  |
+| `rounded`       | `CalendarRounded`          | `"md"`       | Border radius of month tiles.                        |
+| `timeZone`      | `string`                   | —            | IANA time zone.                                      |
+| `tokens`        | `CalendarMonthTokens`      | —            | Token overrides.                                     |
+| `value`         | `number`                   | —            | Selected month (`0`–`11`).                           |
+| `year`          | `number`                   | current year | Year context for min/max month disabling.            |
+
+### v-model
+
+| Prop / Event        | Type                      | Default | Description                           |
+| ------------------- | ------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `number`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: number) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event         | Payload           | Description                                  |
+| ------------- | ----------------- | -------------------------------------------- |
+| `v-on:change` | `(month: number)` | Emitted when a month is selected (`0`–`11`). |
+
+## Related components
+
+Calendar, CalendarDate, CalendarYear

package/docs/components/CalendarRange.md

@@ -0,0 +1,83 @@
+# CalendarRange
+
+Dual-month calendar for selecting a date range. Shared year/month selectors with
+two date panels (`orientation="horizontal"` side-by-side, or `"vertical"` stacked).
+
+## Import
+
+```ts
+import { CalendarRange } from "@bridge-ui/vue/Components/CalendarRange";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<CalendarRange />
+
+<CalendarRange v-model="range" />
+
+<CalendarRange orientation="vertical" />
+
+<CalendarRange v-model="range" :min-date="min" :max-date="max" />
+```
+
+### customProps
+
+```vue
+<CalendarRange
+  :custom-props="{
+    panels: { class: 'gap-4' },
+    root: { 'data-testid': 'calendar-range' },
+  }"
+/>
+```
+
+## Props
+
+| Prop              | Type                         | Default        | Description                                                 |
+| ----------------- | ---------------------------- | -------------- | ----------------------------------------------------------- |
+| `classes`         | `CalendarRangeClasses`       | —              | Classes for calendar range regions.                         |
+| `color`           | `CalendarColor`              | `"primary"`    | Accent color for tiles.                                     |
+| `customProps`     | `CalendarRangeCustomProps`   | —              | Extra props for internal parts.                             |
+| `defaultValue`    | `DateRangeValue \| null`     | `null`         | Uncontrolled initial value.                                 |
+| `disabled`        | `boolean`                    | `false`        | Disables the calendar range.                                |
+| `disableDates`    | `Date[]`                     | —              | Dates that cannot be selected.                              |
+| `disableMonths`   | `number[]`                   | —              | Month indexes that cannot be selected.                      |
+| `disableYears`    | `number[]`                   | —              | Years that cannot be selected.                              |
+| `hideMonths`      | `boolean`                    | `false`        | Hides the shared month selector and month panel.            |
+| `hideOutsideDays` | `boolean`                    | `false`        | Hides days outside the displayed month on both date panels. |
+| `hideWeekdays`    | `boolean`                    | `false`        | Hides weekday labels on both date panels.                   |
+| `hideYears`       | `boolean`                    | `false`        | Hides the shared year selector and year panel.              |
+| `maxDate`         | `Date`                       | —              | Latest selectable date.                                     |
+| `minDate`         | `Date`                       | —              | Earliest selectable date.                                   |
+| `orientation`     | `"horizontal" \| "vertical"` | `"horizontal"` | Dual calendar layout: side-by-side or stacked.              |
+| `previewDate`     | `Date \| null`               | —              | Controlled range-preview hover date.                        |
+| `readOnly`        | `boolean`                    | `false`        | Prevents selection.                                         |
+| `rounded`         | `CalendarRounded`            | `"md"`         | Border radius of tiles and chrome.                          |
+| `slots`           | `CalendarRangeSlots`         | —              | Named slots (`day`, optional `startAside` / `endAside`).    |
+| `startOfWeek`     | `StartOfWeek`                | `0`            | First day of the week.                                      |
+| `timeZone`        | `string`                     | —              | IANA time zone.                                             |
+| `tokens`          | `CalendarRangeTokens`        | —              | Token overrides.                                            |
+| `value`           | `DateRangeValue \| null`     | —              | Controlled range value (`[start, end]`).                    |
+| `viewDate`        | `Date`                       | —              | Controlled start (left) displayed month.                    |
+
+### v-model
+
+| Prop / Event        | Type                                      | Default | Description                           |
+| ------------------- | ----------------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `DateRangeValue \| null`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: DateRangeValue \| null) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event                      | Payload                           | Description                                        |
+| -------------------------- | --------------------------------- | -------------------------------------------------- |
+| `v-on:change`              | `(value: DateRangeValue \| null)` | Emitted when the range changes.                    |
+| `v-on:preview-date-change` | `(date: Date \| null)`            | Emitted when the range preview hover date changes. |
+| `v-on:view-date-change`    | `(date: Date)`                    | Emitted when the start displayed month changes.    |
+
+## Related components
+
+Calendar, CalendarDate, DateRangePicker, DateRangeField

package/docs/components/CalendarYear.md

@@ -0,0 +1,53 @@
+# CalendarYear
+
+Year-grid panel with paging. Building block used by `Calendar` and `CalendarRange`.
+
+## Import
+
+```ts
+import { CalendarYear } from "@bridge-ui/vue/Components/CalendarYear";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<CalendarYear v-model="year" :page-size="15" />
+```
+
+## Props
+
+| Prop           | Type                      | Default     | Description                      |
+| -------------- | ------------------------- | ----------- | -------------------------------- |
+| `classes`      | `CalendarYearClasses`     | —           | Classes for calendar regions.    |
+| `color`        | `CalendarColor`           | `"primary"` | Accent color for year tiles.     |
+| `customProps`  | `CalendarYearCustomProps` | —           | Extra props for internal parts.  |
+| `disabled`     | `boolean`                 | `false`     | Disables the entire year grid.   |
+| `disableYears` | `number[]`                | —           | Years that cannot be selected.   |
+| `maxDate`      | `Date`                    | —           | Latest selectable date.          |
+| `minDate`      | `Date`                    | —           | Earliest selectable date.        |
+| `pageSize`     | `number`                  | `15`        | How many years to show per page. |
+| `readOnly`     | `boolean`                 | `false`     | Prevents selection.              |
+| `rounded`      | `CalendarRounded`         | `"md"`      | Border radius of year tiles.     |
+| `startYear`    | `number`                  | —           | First year of the visible page.  |
+| `timeZone`     | `string`                  | —           | IANA time zone.                  |
+| `tokens`       | `CalendarYearTokens`      | —           | Token overrides.                 |
+| `value`        | `number`                  | —           | Selected year.                   |
+
+### v-model
+
+| Prop / Event        | Type                      | Default | Description                           |
+| ------------------- | ------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `number`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: number) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event         | Payload          | Description                      |
+| ------------- | ---------------- | -------------------------------- |
+| `v-on:change` | `(year: number)` | Emitted when a year is selected. |
+
+## Related components
+
+Calendar, CalendarDate, CalendarMonth

package/docs/components/DateField.md

@@ -0,0 +1,103 @@
+# DateField
+
+Form field that opens a `DatePicker` in an overlay (`auto` by default: `menu` on desktop, bottom `drawer` on mobile). Extends FormField props.
+
+## Import
+
+```ts
+import { DateField } from "@bridge-ui/vue/Components/DateField";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<DateField label="Start date" />
+
+<DateField
+  label="Birthday"
+  v-model="date"
+  description="Stored as a local calendar date."
+/>
+
+<DateField error label="Date" error-message="Pick a valid date." />
+```
+
+### Range
+
+```vue
+<DateField range label="Trip" v-model="range" />
+```
+
+### Overlay
+
+```vue
+<DateField label="Date" overlay="auto" />
+
+<DateField label="Date" overlay="drawer" />
+
+<DateField
+  label="Date"
+  overlay="modal"
+  :custom-props="{
+    modal: { size: 'sm', transition: 'none' },
+  }"
+/>
+```
+
+Default `overlay` is `auto`: `menu` on desktop and bottom `drawer` on mobile.
+When unset, `showFooter` defaults to `true` on mobile (`false` on desktop).
+
+## Props
+
+### DateField-specific
+
+| Prop              | Type                   | Default                               | Description                                                                           |
+| ----------------- | ---------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- |
+| `classes`         | `DateFieldClasses`     | —                                     | Classes for field / input regions.                                                    |
+| `clearable`       | `boolean`              | `true`                                | Whether the value can be cleared.                                                     |
+| `customProps`     | `DateFieldCustomProps` | —                                     | Extra props for internal parts (`input`, `menu`, `modal`, `drawer`, `datePicker`, …). |
+| `defaultValue`    | `DatePickerModel`      | `null`                                | Uncontrolled initial value.                                                           |
+| `defaultView`     | `CalendarView`         | `"date"`                              | Initial calendar panel view.                                                          |
+| `disableDates`    | `Date[]`               | —                                     | Dates that cannot be selected.                                                        |
+| `disableMonths`   | `number[]`             | —                                     | Month indexes that cannot be selected.                                                |
+| `disableYears`    | `number[]`             | —                                     | Years that cannot be selected.                                                        |
+| `hideMonths`      | `boolean`              | `false`                               | Hides month navigation / panel.                                                       |
+| `hideOutsideDays` | `boolean`              | `false`                               | Hides days that fall outside the displayed month.                                     |
+| `hideWeekdays`    | `boolean`              | `false`                               | Hides weekday labels.                                                                 |
+| `hideYears`       | `boolean`              | `false`                               | Hides year navigation / panel.                                                        |
+| `maxDate`         | `Date`                 | —                                     | Latest selectable date.                                                               |
+| `minDate`         | `Date`                 | —                                     | Earliest selectable date.                                                             |
+| `multiple`        | `boolean`              | `false`                               | Allows selecting multiple dates.                                                      |
+| `overlay`         | `FieldOverlayMode`     | `"auto"`                              | Overlay shell: `menu`, `modal`, `drawer`, or `auto`.                                  |
+| `range`           | `boolean`              | `false`                               | Selects a date range.                                                                 |
+| `showFooter`      | `boolean`              | `false` (`true` on mobile when unset) | Shows Cancel / Apply on the nested picker.                                            |
+| `slots`           | `DateFieldSlots`       | —                                     | Named slots (`FormField` slots + calendar `day`).                                     |
+| `startOfWeek`     | `StartOfWeek`          | `0`                                   | First day of the week.                                                                |
+| `timeZone`        | `string`               | —                                     | IANA time zone.                                                                       |
+| `value`           | `DatePickerModel`      | —                                     | Controlled value.                                                                     |
+
+### v-model
+
+| Prop / Event        | Type                               | Default | Description                           |
+| ------------------- | ---------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `DatePickerModel`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: DatePickerModel) => void` | —       | Emitted when `v-model` should update. |
+
+### Inherited from FormField
+
+See [FormField](./FormField.md).
+
+## Events
+
+| Event         | Payload                    | Description                               |
+| ------------- | -------------------------- | ----------------------------------------- |
+| `v-on:change` | `(value: DatePickerModel)` | Emitted when the selection model changes. |
+| `v-on:clear`  | `()`                       | Emitted when the value is cleared.        |
+| `v-on:close`  | `()`                       | Emitted when the menu closes.             |
+| `v-on:open`   | `()`                       | Emitted when the menu opens.              |
+
+## Related components
+
+DatePicker, FormField, DateRangeField

package/docs/components/DatePicker.md

@@ -0,0 +1,80 @@
+# DatePicker
+
+Inline calendar picker for a single date, multiple dates, or a range. Optional Cancel / Apply footer.
+
+## Import
+
+```ts
+import { DatePicker } from "@bridge-ui/vue/Components/DatePicker";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<DatePicker />
+
+<DatePicker v-model="date" />
+
+<DatePicker range show-footer v-model="range" @cancel="() => {}" />
+```
+
+### customProps
+
+```vue
+<DatePicker
+  :custom-props="{
+    root: { 'data-testid': 'date-picker' },
+    applyButton: { type: 'button' },
+  }"
+/>
+```
+
+## Props
+
+| Prop              | Type                    | Default     | Description                                           |
+| ----------------- | ----------------------- | ----------- | ----------------------------------------------------- |
+| `classes`         | `DatePickerClasses`     | —           | Classes for picker regions.                           |
+| `color`           | `CalendarColor`         | `"primary"` | Accent color.                                         |
+| `customProps`     | `DatePickerCustomProps` | —           | Extra props for internal parts.                       |
+| `defaultValue`    | `DatePickerModel`       | `null`      | Uncontrolled initial value.                           |
+| `defaultView`     | `CalendarView`          | `"date"`    | Initial calendar panel view.                          |
+| `disabled`        | `boolean`               | `false`     | Disables the picker.                                  |
+| `disableDates`    | `Date[]`                | —           | Dates that cannot be selected.                        |
+| `disableMonths`   | `number[]`              | —           | Month indexes that cannot be selected.                |
+| `disableYears`    | `number[]`              | —           | Years that cannot be selected.                        |
+| `hideMonths`      | `boolean`               | `false`     | Hides month navigation / panel.                       |
+| `hideOutsideDays` | `boolean`               | `false`     | Hides days that fall outside the displayed month.     |
+| `hideWeekdays`    | `boolean`               | `false`     | Hides weekday labels.                                 |
+| `hideYears`       | `boolean`               | `false`     | Hides year navigation / panel.                        |
+| `maxDate`         | `Date`                  | —           | Latest selectable date.                               |
+| `minDate`         | `Date`                  | —           | Earliest selectable date.                             |
+| `multiple`        | `boolean`               | `false`     | Allows selecting multiple dates.                      |
+| `range`           | `boolean`               | `false`     | Selects a date range.                                 |
+| `readOnly`        | `boolean`               | `false`     | Prevents selection.                                   |
+| `rounded`         | `CalendarRounded`       | `"md"`      | Border radius of calendar tiles and chrome.           |
+| `showFooter`      | `boolean`               | `false`     | Shows Cancel / Apply. Selection is draft until Apply. |
+| `slots`           | `CalendarDateSlots`     | —           | Named slots forwarded to `Calendar` (`day`).          |
+| `startOfWeek`     | `StartOfWeek`           | `0`         | First day of the week.                                |
+| `timeZone`        | `string`                | —           | IANA time zone.                                       |
+| `tokens`          | `DatePickerTokens`      | —           | Token overrides.                                      |
+| `value`           | `DatePickerModel`       | —           | Controlled value.                                     |
+
+### v-model
+
+| Prop / Event        | Type                               | Default | Description                           |
+| ------------------- | ---------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `DatePickerModel`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: DatePickerModel) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event         | Payload                    | Description                                                             |
+| ------------- | -------------------------- | ----------------------------------------------------------------------- |
+| `v-on:cancel` | `()`                       | Emitted when Cancel is pressed.                                         |
+| `v-on:change` | `(value: DatePickerModel)` | Emitted when Apply is pressed (`showFooter`) or when the value commits. |
+
+## Related components
+
+Calendar, DateField, DateRangePicker

package/docs/components/DateRangeField.md

@@ -0,0 +1,88 @@
+# DateRangeField
+
+Form field that opens a `DateRangePicker` in an overlay (`auto` by default: `menu` on desktop, bottom `drawer` on mobile). Extends FormField props.
+
+## Import
+
+```ts
+import { DateRangeField } from "@bridge-ui/vue/Components/DateRangeField";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<DateRangeField label="Stay" />
+
+<DateRangeField label="Trip" v-model="range" />
+
+<DateRangeField error label="Dates" error-message="Select a valid range." />
+```
+
+Supports the same `overlay` prop as DateField (`menu` | `modal` | `drawer` | `auto`).
+On mobile, `drawer` / `modal` overlays use vertical dual-calendar layout when
+`orientation` is unset.
+
+### customProps
+
+```vue
+<DateRangeField
+  label="Stay"
+  :custom-props="{
+    input: { name: 'stay' },
+    dateRangePicker: { root: { 'data-testid': 'range-picker' } },
+  }"
+/>
+```
+
+## Props
+
+### DateRangeField-specific
+
+| Prop              | Type                         | Default                               | Description                                                                       |
+| ----------------- | ---------------------------- | ------------------------------------- | --------------------------------------------------------------------------------- |
+| `classes`         | `DateRangeFieldClasses`      | —                                     | Classes for field / input regions.                                                |
+| `clearable`       | `boolean`                    | `true`                                | Whether the value can be cleared.                                                 |
+| `customProps`     | `DateRangeFieldCustomProps`  | —                                     | Extra props for internal parts.                                                   |
+| `defaultValue`    | `DateRangeValue \| null`     | `null`                                | Uncontrolled initial value.                                                       |
+| `disableDates`    | `Date[]`                     | —                                     | Dates that cannot be selected.                                                    |
+| `disableMonths`   | `number[]`                   | —                                     | Month indexes that cannot be selected.                                            |
+| `disableYears`    | `number[]`                   | —                                     | Years that cannot be selected.                                                    |
+| `hideMonths`      | `boolean`                    | `false`                               | Hides month navigation / panel.                                                   |
+| `hideOutsideDays` | `boolean`                    | `false`                               | Hides days that fall outside the displayed month.                                 |
+| `hideWeekdays`    | `boolean`                    | `false`                               | Hides weekday labels.                                                             |
+| `hideYears`       | `boolean`                    | `false`                               | Hides year navigation / panel.                                                    |
+| `maxDate`         | `Date`                       | —                                     | Latest selectable date.                                                           |
+| `minDate`         | `Date`                       | —                                     | Earliest selectable date.                                                         |
+| `orientation`     | `"horizontal" \| "vertical"` | `"horizontal"`                        | Dual calendar layout. Mobile `drawer` / `modal` default to `vertical` when unset. |
+| `overlay`         | `FieldOverlayMode`           | `"auto"`                              | Overlay shell: `menu`, `modal`, `drawer`, or `auto`.                              |
+| `showFooter`      | `boolean`                    | `false` (`true` on mobile when unset) | Shows Cancel / Apply on the nested picker.                                        |
+| `slots`           | `DateRangeFieldSlots`        | —                                     | Named slots (`FormField` slots + calendar `day`).                                 |
+| `startOfWeek`     | `StartOfWeek`                | `0`                                   | First day of the week.                                                            |
+| `timeZone`        | `string`                     | —                                     | IANA time zone.                                                                   |
+| `value`           | `DateRangeValue \| null`     | —                                     | Controlled value.                                                                 |
+
+### v-model
+
+| Prop / Event        | Type                                      | Default | Description                           |
+| ------------------- | ----------------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `DateRangeValue \| null`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: DateRangeValue \| null) => void` | —       | Emitted when `v-model` should update. |
+
+### Inherited from FormField
+
+See [FormField](./FormField.md).
+
+## Events
+
+| Event         | Payload                           | Description                        |
+| ------------- | --------------------------------- | ---------------------------------- |
+| `v-on:change` | `(value: DateRangeValue \| null)` | Emitted when the range changes.    |
+| `v-on:clear`  | `()`                              | Emitted when the value is cleared. |
+| `v-on:close`  | `()`                              | Emitted when the menu closes.      |
+| `v-on:open`   | `()`                              | Emitted when the menu opens.       |
+
+## Related components
+
+DateRangePicker, FormField, DateField

package/docs/components/DateRangePicker.md

@@ -0,0 +1,70 @@
+# DateRangePicker
+
+Inline dual-month picker for an inclusive date range (`[start, end]`). The header
+exposes year, start month, and end month selectors in one row.
+
+## Import
+
+```ts
+import { DateRangePicker } from "@bridge-ui/vue/Components/DateRangePicker";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<DateRangePicker />
+
+<DateRangePicker v-model="range" />
+
+<DateRangePicker orientation="vertical" />
+
+<DateRangePicker show-footer v-model="range" @cancel="() => {}" />
+```
+
+## Props
+
+| Prop              | Type                         | Default        | Description                                           |
+| ----------------- | ---------------------------- | -------------- | ----------------------------------------------------- |
+| `classes`         | `DateRangePickerClasses`     | —              | Classes for picker regions.                           |
+| `color`           | `CalendarColor`              | `"primary"`    | Accent color.                                         |
+| `customProps`     | `DateRangePickerCustomProps` | —              | Extra props for internal parts.                       |
+| `defaultValue`    | `DateRangeValue \| null`     | `null`         | Uncontrolled initial value.                           |
+| `disabled`        | `boolean`                    | `false`        | Disables the picker.                                  |
+| `disableDates`    | `Date[]`                     | —              | Dates that cannot be selected.                        |
+| `disableMonths`   | `number[]`                   | —              | Month indexes that cannot be selected.                |
+| `disableYears`    | `number[]`                   | —              | Years that cannot be selected.                        |
+| `hideMonths`      | `boolean`                    | `false`        | Hides month navigation / panel.                       |
+| `hideOutsideDays` | `boolean`                    | `false`        | Hides days that fall outside the displayed month.     |
+| `hideWeekdays`    | `boolean`                    | `false`        | Hides weekday labels.                                 |
+| `hideYears`       | `boolean`                    | `false`        | Hides year navigation / panel.                        |
+| `maxDate`         | `Date`                       | —              | Latest selectable date.                               |
+| `minDate`         | `Date`                       | —              | Earliest selectable date.                             |
+| `orientation`     | `"horizontal" \| "vertical"` | `"horizontal"` | Dual calendar layout: side-by-side or stacked.        |
+| `readOnly`        | `boolean`                    | `false`        | Prevents selection.                                   |
+| `rounded`         | `CalendarRounded`            | `"md"`         | Border radius of calendar tiles and chrome.           |
+| `showFooter`      | `boolean`                    | `false`        | Shows Cancel / Apply. Selection is draft until Apply. |
+| `slots`           | `CalendarDateSlots`          | —              | Named slots forwarded to `CalendarRange` (`day`).     |
+| `startOfWeek`     | `StartOfWeek`                | `0`            | First day of the week.                                |
+| `timeZone`        | `string`                     | —              | IANA time zone.                                       |
+| `tokens`          | `DateRangePickerTokens`      | —              | Token overrides.                                      |
+| `value`           | `DateRangeValue \| null`     | —              | Controlled value (`[start, end]`).                    |
+
+### v-model
+
+| Prop / Event        | Type                                      | Default | Description                           |
+| ------------------- | ----------------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `DateRangeValue \| null`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: DateRangeValue \| null) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event         | Payload                           | Description                                                             |
+| ------------- | --------------------------------- | ----------------------------------------------------------------------- |
+| `v-on:cancel` | `()`                              | Emitted when Cancel is pressed.                                         |
+| `v-on:change` | `(value: DateRangeValue \| null)` | Emitted when Apply is pressed (`showFooter`) or when the value commits. |
+
+## Related components
+
+CalendarRange, DateRangeField, DatePicker