@bridge-ui/vue 0.0.8 → 0.0.10

package/docs/components/Select.md

@@ -108,6 +108,17 @@ Use the default slot with `ListSection` / `ListItem` to build the dropdown list
 </Select>
 ```
 
+### Overlay
+
+```vue
+<Select overlay="auto" label="Country" :options="countries" />
+
+<Select label="Country" overlay="drawer" :options="countries" />
+```
+
+Default `overlay` is `auto`: `menu` on desktop and bottom `drawer` on mobile.
+When unset, `showFooter` defaults to `true` on mobile (`false` on desktop). Selection stays draft until Apply.
+
 ### customProps
 
 ```vue
@@ -126,25 +137,27 @@ Use the default slot with `ListSection` / `ListItem` to build the dropdown list
 
 ### Select-specific
 
-| Prop                | Type                  | Default       | Description                                                                                             |
-| ------------------- | --------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
-| `asyncData`         | `SelectAsyncData`     | —             | Remote data source. Implies `searchable`.                                                               |
-| `clearable`         | `boolean`             | `true`        | Whether the value can be cleared.                                                                       |
-| `defaultValue`      | `SelectModel`         | —             | Initial value when uncontrolled.                                                                        |
-| `disableMaxHeight`  | `boolean`             | `false`       | When true, the dropdown options list is not height-limited. Forwarded to the internal `Listbox`.        |
-| `emptyMessage`      | `string`              | "No options"  | Message when the filtered list is empty.                                                                |
-| `flipOptions`       | `boolean`             | `false`       | Inverts the visual order of options.                                                                    |
-| `hideEmptyMessage`  | `boolean`             | `false`       | Hides the empty-state message.                                                                          |
-| `loading`           | `boolean`             | —             | External or async loading state.                                                                        |
-| `maxHeight`         | `string`              | "max-h-60"    | Tailwind max-height class for the dropdown options area. Forwarded to the internal `Listbox`.           |
-| `minItemsForSearch` | `number`              | 11            | Minimum option count before search UI is enabled.                                                       |
-| `multiple`          | `boolean`             | `false`       | Whether multiple values can be selected.                                                                |
-| `optionDescription` | `string`              | "description" | Key used to read the description from option objects.                                                   |
-| `optionLabel`       | `string`              | "label"       | Key used to read the label from option objects.                                                         |
-| `options`           | `ListboxOptionsInput` | —             | Options to display. May include section groups (`{ title, options, sticky? }`) mixed with flat options. |
-| `optionValue`       | `string`              | "value"       | Key used to read the value from option objects.                                                         |
-| `placeholder`       | `string`              | —             | Placeholder shown when no value is selected.                                                            |
-| `searchable`        | `boolean`             | `false`       | Whether options can be filtered via the trigger input.                                                  |
+| Prop                | Type                  | Default                               | Description                                                                                             |
+| ------------------- | --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `asyncData`         | `SelectAsyncData`     | —                                     | Remote data source. Implies `searchable`.                                                               |
+| `clearable`         | `boolean`             | `true`                                | Whether the value can be cleared.                                                                       |
+| `defaultValue`      | `SelectModel`         | —                                     | Initial value when uncontrolled.                                                                        |
+| `disableMaxHeight`  | `boolean`             | `false`                               | When true, the dropdown options list is not height-limited. Forwarded to the internal `Listbox`.        |
+| `emptyMessage`      | `string`              | "No options"                          | Message when the filtered list is empty.                                                                |
+| `flipOptions`       | `boolean`             | `false`                               | Inverts the visual order of options.                                                                    |
+| `hideEmptyMessage`  | `boolean`             | `false`                               | Hides the empty-state message.                                                                          |
+| `loading`           | `boolean`             | —                                     | External or async loading state.                                                                        |
+| `maxHeight`         | `string`              | "max-h-60"                            | Tailwind max-height class for the dropdown options area. Forwarded to the internal `Listbox`.           |
+| `minItemsForSearch` | `number`              | 11                                    | Minimum option count before search UI is enabled.                                                       |
+| `multiple`          | `boolean`             | `false`                               | Whether multiple values can be selected.                                                                |
+| `optionDescription` | `string`              | "description"                         | Key used to read the description from option objects.                                                   |
+| `optionLabel`       | `string`              | "label"                               | Key used to read the label from option objects.                                                         |
+| `options`           | `ListboxOptionsInput` | —                                     | Options to display. May include section groups (`{ title, options, sticky? }`) mixed with flat options. |
+| `optionValue`       | `string`              | "value"                               | Key used to read the value from option objects.                                                         |
+| `overlay`           | `FieldOverlayMode`    | `"auto"`                              | Overlay shell: `menu`, `modal`, `drawer`, or `auto`.                                                    |
+| `placeholder`       | `string`              | —                                     | Placeholder shown when no value is selected.                                                            |
+| `searchable`        | `boolean`             | `false`                               | Whether options can be filtered via the trigger input.                                                  |
+| `showFooter`        | `boolean`             | `false` (`true` on mobile when unset) | Shows Cancel / Apply on the nested listbox. Selection stays draft until Apply.                          |
 
 ### v-model
 
@@ -166,16 +179,17 @@ See [FormField](./FormField.md) (building-block chrome). Field tokens live on `c
 
 ## Events
 
-| Event           | Payload                  | Description                                           |
-| --------------- | ------------------------ | ----------------------------------------------------- |
-| `v-on:change`   | `(value: SelectModel)`   | Emitted when the selection changes.                   |
-| `v-on:clear`    | —                        | Emitted when the value is cleared.                    |
-| `v-on:close`    | —                        | Emitted when the menu closes.                         |
-| `v-on:deselect` | `(option: SelectOption)` | Emitted when an option is deselected (multiple mode). |
-| `v-on:open`     | —                        | Emitted when the menu opens.                          |
-| `v-on:search`   | `(query: string)`        | Emitted when the search query changes.                |
-| `v-on:select`   | `(option: SelectOption)` | Emitted when an option is selected.                   |
+| Event           | Payload                  | Description                                                          |
+| --------------- | ------------------------ | -------------------------------------------------------------------- |
+| `v-on:cancel`   | —                        | Emitted when Cancel is pressed on the listbox footer (`showFooter`). |
+| `v-on:change`   | `(value: SelectModel)`   | Emitted when the selection changes.                                  |
+| `v-on:clear`    | —                        | Emitted when the value is cleared.                                   |
+| `v-on:close`    | —                        | Emitted when the menu closes.                                        |
+| `v-on:deselect` | `(option: SelectOption)` | Emitted when an option is deselected (multiple mode).                |
+| `v-on:open`     | —                        | Emitted when the menu opens.                                         |
+| `v-on:search`   | `(query: string)`        | Emitted when the search query changes.                               |
+| `v-on:select`   | `(option: SelectOption)` | Emitted when an option is selected.                                  |
 
 ## Related components
 
-Menu, List, ListItem, ListSection, FormField
+Menu, Modal, Drawer, FieldOverlay, List, ListItem, ListSection, FormField

package/docs/components/TimeField.md

@@ -0,0 +1,81 @@
+# TimeField
+
+Form field that opens a `TimePicker` in an overlay (`auto` by default: `menu` on desktop, bottom `drawer` on mobile). Extends FormField props. Uses the semantic `clock` icon by default.
+
+## Import
+
+```ts
+import { TimeField } from "@bridge-ui/vue/Components/TimeField";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<TimeField label="Start time" />
+
+<TimeField ampm label="Meeting" :interval="5" v-model="time" />
+
+<TimeField error label="Time" error-message="Pick a valid time." />
+```
+
+Supports the same `overlay` prop as DateField (`menu` | `modal` | `drawer` | `auto`).
+
+### customProps
+
+```vue
+<TimeField
+  label="Time"
+  :custom-props="{
+    input: { name: 'time' },
+    timePicker: { root: { 'data-testid': 'time-picker' } },
+  }"
+/>
+```
+
+## Props
+
+### TimeField-specific
+
+| Prop           | Type                   | Default                               | Description                                          |
+| -------------- | ---------------------- | ------------------------------------- | ---------------------------------------------------- |
+| `ampm`         | `boolean`              | `false`                               | Uses a 12-hour clock with an AM/PM column.           |
+| `classes`      | `TimeFieldClasses`     | —                                     | Classes for field / input regions.                   |
+| `clearable`    | `boolean`              | `true`                                | Whether the value can be cleared.                    |
+| `customProps`  | `TimeFieldCustomProps` | —                                     | Extra props for internal parts.                      |
+| `defaultValue` | `Date \| null`         | `null`                                | Uncontrolled initial value.                          |
+| `disableTimes` | `Date[]`               | —                                     | Times that cannot be selected.                       |
+| `interval`     | `number`               | `1`                                   | Minute step between options.                         |
+| `maxTime`      | `Date`                 | —                                     | Latest selectable time.                              |
+| `minTime`      | `Date`                 | —                                     | Earliest selectable time.                            |
+| `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.           |
+| `showSeconds`  | `boolean`              | `false`                               | Shows seconds in the panel and formatted value.      |
+| `slots`        | `TimeFieldSlots`       | —                                     | Named slots (`FormField` slots).                     |
+| `timeZone`     | `string`               | —                                     | IANA time zone.                                      |
+| `value`        | `Date \| null`         | —                                     | Controlled value.                                    |
+
+### v-model
+
+| Prop / Event        | Type                            | Default | Description                           |
+| ------------------- | ------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `Date \| null`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: Date \| null) => void` | —       | Emitted when `v-model` should update. |
+
+### Inherited from FormField
+
+See [FormField](./FormField.md).
+
+## Events
+
+| Event         | Payload                 | Description                        |
+| ------------- | ----------------------- | ---------------------------------- |
+| `v-on:change` | `(value: Date \| null)` | Emitted when the time 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
+
+TimePicker, FormField, DateTimeField

package/docs/components/TimePanel.md

@@ -0,0 +1,56 @@
+# TimePanel
+
+Scrollable hour / minute (/ AM·PM) columns for selecting a wall-clock time. Building block for time pickers.
+
+## Import
+
+```ts
+import { TimePanel } from "@bridge-ui/vue/Components/TimePanel";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<TimePanel v-model="time" />
+
+<TimePanel ampm :interval="5" v-model="time" />
+```
+
+## Props
+
+| Prop           | Type                   | Default     | Description                                     |
+| -------------- | ---------------------- | ----------- | ----------------------------------------------- |
+| `ampm`         | `boolean`              | `false`     | Uses a 12-hour clock with an AM/PM column.      |
+| `classes`      | `TimePanelClasses`     | —           | Classes for panel regions.                      |
+| `color`        | `CalendarColor`        | `"primary"` | Accent color for time tiles.                    |
+| `customProps`  | `TimePanelCustomProps` | —           | Extra props for internal parts.                 |
+| `disabled`     | `boolean`              | `false`     | Disables the entire panel.                      |
+| `disableTimes` | `Date[]`               | —           | Times that cannot be selected.                  |
+| `interval`     | `number`               | `1`         | Minute step between options.                    |
+| `maxTime`      | `Date`                 | —           | Latest selectable time.                         |
+| `minTime`      | `Date`                 | —           | Earliest selectable time.                       |
+| `readOnly`     | `boolean`              | `false`     | Prevents selection.                             |
+| `rounded`      | `CalendarRounded`      | `"md"`      | Border radius of time tiles.                    |
+| `showSeconds`  | `boolean`              | `false`     | Shows seconds in the panel and formatted value. |
+| `timeZone`     | `string`               | —           | IANA time zone.                                 |
+| `tokens`       | `TimePanelTokens`      | —           | Token overrides.                                |
+| `value`        | `Date \| null`         | —           | Selected time (`Date` wall clock).              |
+
+### v-model
+
+| Prop / Event        | Type                            | Default | Description                           |
+| ------------------- | ------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `Date \| null`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: Date \| null) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event         | Payload                 | Description                    |
+| ------------- | ----------------------- | ------------------------------ |
+| `v-on:change` | `(value: Date \| null)` | Emitted when the time changes. |
+
+## Related components
+
+TimePicker, TimeField, DateTimePicker

package/docs/components/TimePicker.md

@@ -0,0 +1,61 @@
+# TimePicker
+
+Inline time picker built on `TimePanel`. Value is a `Date` carrying wall-clock hours/minutes.
+
+## Import
+
+```ts
+import { TimePicker } from "@bridge-ui/vue/Components/TimePicker";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<TimePicker />
+
+<TimePicker v-model="time" />
+
+<TimePicker ampm :interval="15" show-footer v-model="time" />
+```
+
+## Props
+
+| Prop           | Type                    | Default     | Description                                           |
+| -------------- | ----------------------- | ----------- | ----------------------------------------------------- |
+| `ampm`         | `boolean`               | `false`     | Uses a 12-hour clock with an AM/PM column.            |
+| `classes`      | `TimePickerClasses`     | —           | Classes for picker regions.                           |
+| `color`        | `CalendarColor`         | `"primary"` | Accent color.                                         |
+| `customProps`  | `TimePickerCustomProps` | —           | Extra props for internal parts.                       |
+| `defaultValue` | `Date \| null`          | `null`      | Uncontrolled initial value.                           |
+| `disabled`     | `boolean`               | `false`     | Disables the picker.                                  |
+| `disableTimes` | `Date[]`                | —           | Times that cannot be selected.                        |
+| `interval`     | `number`                | `1`         | Minute step between options.                          |
+| `maxTime`      | `Date`                  | —           | Latest selectable time.                               |
+| `minTime`      | `Date`                  | —           | Earliest selectable time.                             |
+| `readOnly`     | `boolean`               | `false`     | Prevents selection.                                   |
+| `rounded`      | `CalendarRounded`       | `"md"`      | Border radius of time tiles and chrome.               |
+| `showFooter`   | `boolean`               | `false`     | Shows Cancel / Apply. Selection is draft until Apply. |
+| `showSeconds`  | `boolean`               | `false`     | Shows seconds in the panel and formatted value.       |
+| `timeZone`     | `string`                | —           | IANA time zone.                                       |
+| `tokens`       | `TimePickerTokens`      | —           | Token overrides.                                      |
+| `value`        | `Date \| null`          | —           | Controlled value.                                     |
+
+### v-model
+
+| Prop / Event        | Type                            | Default | Description                           |
+| ------------------- | ------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `Date \| null`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: Date \| null) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event         | Payload                 | Description                                                             |
+| ------------- | ----------------------- | ----------------------------------------------------------------------- |
+| `v-on:cancel` | `()`                    | Emitted when Cancel is pressed.                                         |
+| `v-on:change` | `(value: Date \| null)` | Emitted when Apply is pressed (`showFooter`) or when the value commits. |
+
+## Related components
+
+TimePanel, TimeField, DateTimePicker

package/docs/components/TimeRangeField.md

@@ -0,0 +1,79 @@
+# TimeRangeField
+
+Form field that opens a `TimeRangePicker` in an overlay (`auto` by default: `menu` on desktop, bottom `drawer` on mobile). Extends FormField props.
+
+## Import
+
+```ts
+import { TimeRangeField } from "@bridge-ui/vue/Components/TimeRangeField";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<TimeRangeField label="Hours" />
+
+<TimeRangeField ampm label="Shift" v-model="range" />
+```
+
+Supports the same `overlay` prop as DateField (`menu` | `modal` | `drawer` | `auto`).
+
+### customProps
+
+```vue
+<TimeRangeField
+  label="Hours"
+  :custom-props="{
+    input: { name: 'hours' },
+    timeRangePicker: { root: { 'data-testid': 'tr-picker' } },
+  }"
+/>
+```
+
+## Props
+
+### TimeRangeField-specific
+
+| Prop           | Type                        | Default                               | Description                                          |
+| -------------- | --------------------------- | ------------------------------------- | ---------------------------------------------------- |
+| `ampm`         | `boolean`                   | `false`                               | Uses a 12-hour clock with an AM/PM column.           |
+| `classes`      | `TimeRangeFieldClasses`     | —                                     | Classes for field / input regions.                   |
+| `clearable`    | `boolean`                   | `true`                                | Whether the value can be cleared.                    |
+| `customProps`  | `TimeRangeFieldCustomProps` | —                                     | Extra props for internal parts.                      |
+| `defaultValue` | `TimeRangeValue \| null`    | `null`                                | Uncontrolled initial value.                          |
+| `disableTimes` | `Date[]`                    | —                                     | Times that cannot be selected.                       |
+| `interval`     | `number`                    | `1`                                   | Minute step between options.                         |
+| `maxTime`      | `Date`                      | —                                     | Latest selectable time.                              |
+| `minTime`      | `Date`                      | —                                     | Earliest selectable time.                            |
+| `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.           |
+| `showSeconds`  | `boolean`                   | `false`                               | Shows seconds in the panel and formatted value.      |
+| `slots`        | `TimeRangeFieldSlots`       | —                                     | Named slots (`FormField` slots).                     |
+| `timeZone`     | `string`                    | —                                     | IANA time zone.                                      |
+| `value`        | `TimeRangeValue \| null`    | —                                     | Controlled value.                                    |
+
+### v-model
+
+| Prop / Event        | Type                                      | Default | Description                           |
+| ------------------- | ----------------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `TimeRangeValue \| null`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: TimeRangeValue \| null) => void` | —       | Emitted when `v-model` should update. |
+
+### Inherited from FormField
+
+See [FormField](./FormField.md).
+
+## Events
+
+| Event         | Payload                           | Description                        |
+| ------------- | --------------------------------- | ---------------------------------- |
+| `v-on:change` | `(value: TimeRangeValue \| 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
+
+TimeRangePicker, FormField, TimeField

package/docs/components/TimeRangePicker.md

@@ -0,0 +1,64 @@
+# TimeRangePicker
+
+Inline dual `TimePanel` picker for a time range (`[start, end]`).
+
+## Import
+
+```ts
+import { TimeRangePicker } from "@bridge-ui/vue/Components/TimeRangePicker";
+```
+
+## Examples
+
+### Usage
+
+```vue
+<TimeRangePicker />
+
+<TimeRangePicker v-model="range" />
+
+<TimeRangePicker ampm :interval="15" v-model="range" />
+```
+
+## Props
+
+| Prop           | Type                         | Default        | Description                                           |
+| -------------- | ---------------------------- | -------------- | ----------------------------------------------------- |
+| `ampm`         | `boolean`                    | `false`        | Uses a 12-hour clock with an AM/PM column.            |
+| `classes`      | `TimeRangePickerClasses`     | —              | Classes for picker regions.                           |
+| `color`        | `CalendarColor`              | `"primary"`    | Accent color.                                         |
+| `customProps`  | `TimeRangePickerCustomProps` | —              | Extra props for internal parts.                       |
+| `defaultValue` | `TimeRangeValue \| null`     | `null`         | Uncontrolled initial value.                           |
+| `disabled`     | `boolean`                    | `false`        | Disables the picker.                                  |
+| `disableTimes` | `Date[]`                     | —              | Times that cannot be selected.                        |
+| `endTitle`     | `string`                     | `"End time"`   | Label above the end time panel.                       |
+| `interval`     | `number`                     | `1`            | Minute step between options.                          |
+| `maxTime`      | `Date`                       | —              | Latest selectable time.                               |
+| `minTime`      | `Date`                       | —              | Earliest selectable time.                             |
+| `orientation`  | `"horizontal" \| "vertical"` | `"horizontal"` | Layout of start / end time panels.                    |
+| `readOnly`     | `boolean`                    | `false`        | Prevents selection.                                   |
+| `rounded`      | `CalendarRounded`            | `"md"`         | Border radius of time tiles and chrome.               |
+| `showFooter`   | `boolean`                    | `false`        | Shows Cancel / Apply. Selection is draft until Apply. |
+| `showSeconds`  | `boolean`                    | `false`        | Shows seconds in the panel and formatted value.       |
+| `startTitle`   | `string`                     | `"Start time"` | Label above the start time panel.                     |
+| `timeZone`     | `string`                     | —              | IANA time zone.                                       |
+| `tokens`       | `TimeRangePickerTokens`      | —              | Token overrides.                                      |
+| `value`        | `TimeRangeValue \| null`     | —              | Controlled value (`[start, end]`).                    |
+
+### v-model
+
+| Prop / Event        | Type                                      | Default | Description                           |
+| ------------------- | ----------------------------------------- | ------- | ------------------------------------- |
+| `modelValue`        | `TimeRangeValue \| null`                  | —       | Bound with `v-model`.                 |
+| `update:modelValue` | `(value: TimeRangeValue \| null) => void` | —       | Emitted when `v-model` should update. |
+
+## Events
+
+| Event         | Payload                           | Description                                                             |
+| ------------- | --------------------------------- | ----------------------------------------------------------------------- |
+| `v-on:cancel` | `()`                              | Emitted when Cancel is pressed.                                         |
+| `v-on:change` | `(value: TimeRangeValue \| null)` | Emitted when Apply is pressed (`showFooter`) or when the value commits. |
+
+## Related components
+
+TimePanel, TimeRangeField, TimePicker