@bridge-ui/vue 0.0.8 → 0.0.9

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

package/docs/examples/date-date-fns.ts

@@ -0,0 +1,286 @@
+/**
+ * Example date-fns date adapter for `@bridge-ui/vue`.
+ * Copy into your app or wire via `BridgeUIProvider` / `createBridgeUI` `global.dates`.
+ * Not published as an npm package.
+ *
+ * Requires `date-fns`. Values stay as native `Date` (date-fns default).
+ * For IANA zones, prefer the Luxon or Day.js samples.
+ */
+
+// ** External Imports
+import {
+  addDays,
+  addMonths,
+  addYears,
+  endOfMonth,
+  format as formatDate,
+  getDate,
+  getDay,
+  getHours,
+  getMinutes,
+  getMonth,
+  getSeconds,
+  getYear,
+  isAfter,
+  isBefore,
+  isSameDay,
+  isSameMonth,
+  isSameYear,
+  isValid,
+  parse,
+  parseISO,
+  setDate,
+  setHours,
+  setMinutes,
+  setMonth,
+  setSeconds,
+  setYear,
+  startOfDay,
+  startOfMonth,
+} from "date-fns";
+import { clamp, isNil, isString, range } from "es-toolkit/compat";
+
+// ** Core Imports
+import type {
+  DateAdapter,
+  DateAdapterContext,
+  DateAdapterTimeOptions,
+} from "@bridge-ui/core";
+
+/**
+ * Options for {@link createDateFnsDateAdapter}.
+ */
+export type DateFnsDateAdapterOptions = {
+  /**
+   * Default locale when context omits `locale`.
+   *
+   * @default undefined
+   */
+  locale?: string;
+
+  /**
+   * Default IANA time zone when context omits `timeZone`.
+   * Used for `format` / `formatTime` via `Intl` (date-fns itself is local).
+   *
+   * @default undefined
+   */
+  timeZone?: string;
+};
+
+/**
+ * Builds a date-fns-backed {@link DateAdapter} (`TDate = Date`) for Bridge calendars.
+ */
+export function createDateFnsDateAdapter(
+  options: DateFnsDateAdapterOptions = {},
+): DateAdapter<Date> {
+  const resolveLocale = (context?: DateAdapterContext) => {
+    return context?.locale ?? options.locale;
+  };
+
+  const resolveTimeZone = (context?: DateAdapterContext) => {
+    return context?.timeZone ?? options.timeZone;
+  };
+
+  const isValidDate = (date: Date) => {
+    return date instanceof Date && isValid(date);
+  };
+
+  const adapter: DateAdapter<Date> = {
+    now: () => new Date(),
+
+    getDay: (date) => getDay(date),
+
+    getDate: (date) => getDate(date),
+
+    getYear: (date) => getYear(date),
+
+    getMonth: (date) => getMonth(date),
+
+    getHours: (date) => getHours(date),
+
+    isSameDay: (a, b) => isSameDay(a, b),
+
+    getMinutes: (date) => getMinutes(date),
+
+    getSeconds: (date) => getSeconds(date),
+
+    isSameYear: (a, b) => isSameYear(a, b),
+
+    startOfDay: (date) => startOfDay(date),
+
+    endOfMonth: (date) => endOfMonth(date),
+
+    isSameMonth: (a, b) => isSameMonth(a, b),
+
+    startOfMonth: (date) => startOfMonth(date),
+
+    setDate: (date, day) => setDate(date, day),
+
+    setYear: (date, year) => setYear(date, year),
+
+    setMonth: (date, month) => setMonth(date, month),
+
+    addDays: (date, amount) => addDays(date, amount),
+
+    addYears: (date, amount) => addYears(date, amount),
+
+    addMonths: (date, amount) => addMonths(date, amount),
+
+    isAfter: (a, b) => isAfter(startOfDay(a), startOfDay(b)),
+
+    isBefore: (a, b) => isBefore(startOfDay(a), startOfDay(b)),
+
+    setHours: (date, hours) => setHours(date, clamp(hours, 0, 23)),
+
+    setMinutes: (date, minutes) => setMinutes(date, clamp(minutes, 0, 59)),
+
+    setSeconds: (date, seconds) => setSeconds(date, clamp(seconds, 0, 59)),
+
+    parseTime: (value, context, timeOptions) => {
+      return parseTimeWithDateFns({
+        value,
+        adapter,
+        context,
+        timeOptions,
+      });
+    },
+
+    isSameTime: (a, b) => {
+      return (
+        getHours(a) === getHours(b) &&
+        getMinutes(a) === getMinutes(b) &&
+        getSeconds(a) === getSeconds(b)
+      );
+    },
+
+    getMonthNames: (context) => {
+      const locale = resolveLocale(context);
+
+      return range(12).map((month) => {
+        return new Intl.DateTimeFormat(locale, { month: "long" }).format(
+          new Date(2021, month, 1),
+        );
+      });
+    },
+
+    getWeekdayNames: (context) => {
+      const locale = resolveLocale(context);
+      const formatter = new Intl.DateTimeFormat(locale, { weekday: "short" });
+      const sunday = new Date(2021, 0, 3);
+
+      return range(7).map((index) => {
+        const day = new Date(sunday);
+
+        day.setDate(sunday.getDate() + index);
+
+        return formatter.format(day);
+      });
+    },
+
+    parse: (value) => {
+      if (!isString(value) || value.trim() === "") {
+        return null;
+      }
+
+      const trimmed = value.trim();
+      const iso = parseISO(trimmed);
+
+      if (isValid(iso) && /^\d{4}-\d{2}-\d{2}/.test(trimmed)) {
+        return startOfDay(iso);
+      }
+
+      const parsed = new Date(trimmed);
+
+      return isValidDate(parsed) ? startOfDay(parsed) : null;
+    },
+
+    format: (date, context) => {
+      if (!isValidDate(date)) {
+        return "";
+      }
+
+      const locale = resolveLocale(context);
+      const timeZone = resolveTimeZone(context);
+
+      if (!isNil(timeZone) || !isNil(locale)) {
+        return new Intl.DateTimeFormat(locale, {
+          timeZone,
+          day: "2-digit",
+          year: "numeric",
+          month: "2-digit",
+        }).format(date);
+      }
+
+      return formatDate(date, "P");
+    },
+
+    getCalendarDays: (view, startOfWeek, context) => {
+      const monthStart = adapter.startOfMonth(view, context);
+      const weekday = adapter.getDay(monthStart, context);
+      const normalizedStart = ((startOfWeek % 7) + 7) % 7;
+      const leading = (weekday - normalizedStart + 7) % 7;
+      const gridStart = adapter.addDays(monthStart, -leading, context);
+
+      return range(42).map((index) => {
+        return adapter.addDays(gridStart, index, context);
+      });
+    },
+
+    formatTime: (date, context, timeOptions) => {
+      if (!isValidDate(date)) {
+        return "";
+      }
+
+      const locale = resolveLocale(context);
+      const timeZone = resolveTimeZone(context);
+      const ampm = timeOptions?.ampm === true;
+      const showSeconds = timeOptions?.showSeconds === true;
+
+      return new Intl.DateTimeFormat(locale, {
+        timeZone,
+        hour12: ampm,
+        hour: "2-digit",
+        minute: "2-digit",
+        ...(showSeconds ? { second: "2-digit" as const } : {}),
+      }).format(date);
+    },
+  };
+
+  return adapter;
+}
+
+function parseTimeWithDateFns(input: {
+  adapter: DateAdapter<Date>;
+  context?: DateAdapterContext;
+  timeOptions?: DateAdapterTimeOptions;
+  value: string;
+}): Date | null {
+  const { value, adapter, context, timeOptions } = input;
+
+  if (!isString(value) || value.trim() === "") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  const ampm = timeOptions?.ampm === true;
+  const showSeconds = timeOptions?.showSeconds === true;
+  const pattern = ampm
+    ? showSeconds
+      ? "h:mm:ss a"
+      : "h:mm a"
+    : showSeconds
+      ? "H:mm:ss"
+      : "H:mm";
+  const parsed = parse(trimmed, pattern, adapter.now(context));
+
+  if (!isValid(parsed)) {
+    return null;
+  }
+
+  const base = adapter.now(context);
+
+  return setSeconds(
+    setMinutes(setHours(base, getHours(parsed)), getMinutes(parsed)),
+    showSeconds ? getSeconds(parsed) : 0,
+  );
+}