@emuanalytics/flow-rdf-ui 4.1.27 → 4.2.0

package/dist/components/calendar/calendar.component.mjs

@@ -1,10 +1,13 @@
 import { html, nothing } from 'lit';
 import { query, state, property } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
-import { DateTime, Info } from 'luxon';
+import { live } from 'lit/directives/live.js';
+import { Interval, DateTime, Info } from 'luxon';
+import { parseDateLimits, endTimeOfRange, atTimeOfDay, parseDateRange, lastDayOfRange } from '../../internal/date-range.mjs';
 import FlowRdfElement from '../../internal/flow-ui-rdf-element.mjs';
 import { isStringFull, isDefined } from '../../internal/type-checks.mjs';
 import { watch } from '../../internal/watch.mjs';
+import { LocalizeController } from '../../utilities/localize.mjs';
 import styles from './calendar.styles.mjs';
 
 var __defProp = Object.defineProperty;
@@ -21,8 +24,13 @@ var __decorateClass = (decorators, target, key, kind) => {
 class FlowUiCalendar extends FlowRdfElement {
   constructor() {
     super(...arguments);
+    this._startTime = { hour: 0, minute: 0, second: 0 };
+    this._endTime = { hour: 24, minute: 0, second: 0 };
+    this.localize = new LocalizeController(this);
     this.displayMode = "date";
+    this.range = false;
     this.size = "medium";
+    this.months = 1;
   }
   connectedCallback() {
     super.connectedCallback();
@@ -30,23 +38,132 @@ class FlowUiCalendar extends FlowRdfElement {
   }
   disconnectedCallback() {
     super.disconnectedCallback();
+    this.clearPendingRange();
+  }
+  /** The number of months shown. Anything other than `2` shows one month. */
+  get monthCount() {
+    return +this.months === 2 ? 2 : 1;
+  }
+  /** Whether the calendar selects a range: a date range, a datetime range or a time range. */
+  get isRangeMode() {
+    return this.range;
+  }
+  /** Whether the calendar selects a datetime range, with start and end times. */
+  get isDateTimeRangeMode() {
+    return this.isRangeMode && this.displayMode === "datetime";
+  }
+  /** Whether the calendar selects a time range: start and end times, with no days. */
+  get isTimeRangeMode() {
+    return this.isRangeMode && this.displayMode === "time";
+  }
+  /** The parsed `min`, `max` and `max-range`, in the calendar's timezone. There are no limits in time display mode. */
+  get limits() {
+    if (this.displayMode === "time") {
+      return {};
+    }
+    return parseDateLimits(this.min, this.max, this.maxRange, { zone: this.timezone, locale: this.locale });
+  }
+  /**
+   * Whether the user can't select `day` (the start of a day): it is outside `min` or `max`, or, while a range is
+   * pending, it would make the range longer than `max-range`.
+   */
+  isDayDisabled(day, limits = this.limits) {
+    const { min, max, maxRange } = limits;
+    if (min && day < min.startOf("day") || max && day > max.startOf("day")) {
+      return true;
+    }
+    if (this.isRangeMode && this._pendingDay && maxRange) {
+      const [first, last] = day < this._pendingDay ? [day, this._pendingDay] : [this._pendingDay, day];
+      return first.plus(maxRange) < last.plus({ days: 1 }).startOf("day");
+    }
+    return false;
+  }
+  /** Clamp a date and time to `min` and `max`, so that the time inputs can't select a time outside the limits. */
+  clampToLimits(date) {
+    const { min, max } = this.limits;
+    if (min && date < min) {
+      return min;
+    }
+    return max && date > max ? max : date;
+  }
+  /** The first and last months the user can navigate to, as the start of each month, if `min` or `max` is set. */
+  get monthLimits() {
+    const { min, max } = this.limits;
+    const first = min?.startOf("month");
+    let last = max?.startOf("month").minus({ months: this.monthCount - 1 });
+    if (first && last && last < first) {
+      last = first;
+    }
+    return { first, last };
+  }
+  /** Clamp a month to the months the user can navigate to. */
+  clampMonth(month) {
+    const { first, last } = this.monthLimits;
+    if (first && month < first) {
+      return first;
+    }
+    return last && month > last ? last : month;
   }
   handleValueChange() {
+    if (this.isRangeMode) {
+      this.handleRangeValueChange();
+      return;
+    }
+    this._selectedRange = void 0;
+    this.clearPendingRange();
     this._selectedDate = this.makeDate(this.value)?.set({ millisecond: 0 });
     if (this._selectedDate) {
       if (this.displayMode === "date") {
         this._selectedDate = this._selectedDate.startOf("day");
       }
-      this._displayDate = this._selectedDate.startOf("month");
+      this.showMonthOf(this._selectedDate);
     } else {
-      this._displayDate = this.makeDate().startOf("month");
+      this.showMonthOf(this.makeDate());
     }
   }
+  handleRangeValueChange() {
+    const range = this.makeRange(this.value);
+    this._selectedDate = void 0;
+    if (range && this._selectedRange && +range.start === +this._selectedRange.start && +range.end === +this._selectedRange.end) {
+      return;
+    }
+    this._selectedRange = range;
+    this.clearPendingRange();
+    this.showMonthOf(range ? range.start : this.makeDate());
+    this._startTime = range ? { hour: range.start.hour, minute: range.start.minute, second: range.start.second } : { hour: 0, minute: 0, second: 0 };
+    this._endTime = range ? endTimeOfRange(range) : { hour: 24, minute: 0, second: 0 };
+  }
+  /**
+   * Show the month of `date` as the first month. In the two-month view, a date in the second month is already shown,
+   * so the display doesn't move.
+   */
+  showMonthOf(date) {
+    const month = date.startOf("month");
+    const isSecondMonth = this.monthCount === 2 && !!this._displayDate?.plus({ months: 1 }).hasSame(month, "month");
+    this._displayDate = isSecondMonth ? month.minus({ months: 1 }) : month;
+  }
   handleTimezoneChange() {
+    this._selectedRange = void 0;
     this.handleValueChange();
     this.updateValue();
   }
+  handleRangeChange() {
+    this._selectedRange = void 0;
+    this.handleValueChange();
+  }
+  handleDisplayModeChange() {
+    if (this.range) {
+      this.handleRangeChange();
+    }
+  }
   dateClicked(val) {
+    if (this.isDayDisabled(this.makeDate(val).startOf("day"))) {
+      return;
+    }
+    if (this.isRangeMode) {
+      this.rangeDateClicked(val);
+      return;
+    }
     const date = this.makeDate(val);
     if (this._selectedDate) {
       this._selectedDate = date.set({
@@ -57,17 +174,111 @@ class FlowUiCalendar extends FlowRdfElement {
     } else {
       this._selectedDate = date;
     }
+    if (this.displayMode === "datetime") {
+      this._selectedDate = this.clampToLimits(this._selectedDate);
+    }
     this.updateValue();
   }
+  /**
+   * Handle a day click in range mode. The first click sets the pending day. The second click completes the range,
+   * whichever order the two days were clicked in, so the user can click the last day first and then go back to the
+   * range start.
+   */
+  rangeDateClicked(val) {
+    const day = this.makeDate(val).startOf("day");
+    if (!this._pendingDay) {
+      if (this.isSingleDayOnly(day)) {
+        this.completeRange(day, day);
+        return;
+      }
+      this._pendingDay = day;
+      this._hoverDate = day;
+      return;
+    }
+    const [first, last] = day < this._pendingDay ? [day, this._pendingDay] : [this._pendingDay, day];
+    this.completeRange(first, last);
+  }
+  /** Whether `max-range` only allows ranges of one day starting on `day`, so that a range is a single day. */
+  isSingleDayOnly(day) {
+    const { maxRange } = this.limits;
+    return !!maxRange && day.plus(maxRange) < day.plus({ days: 2 }).startOf("day");
+  }
+  /** Complete a range from `first` to `last` (both the start of a day) and update the value. */
+  completeRange(first, last) {
+    const range = this.isDateTimeRangeMode ? this.makeDateTimeRange(first, last) : Interval.fromDateTimes(first, last.plus({ days: 1 }).startOf("day"));
+    this.clearPendingRange();
+    if (range.isValid) {
+      this._selectedRange = range;
+      if (this.isDateTimeRangeMode) {
+        this._startTime = { hour: range.start.hour, minute: range.start.minute, second: range.start.second };
+        this._endTime = endTimeOfRange(range);
+      }
+      this.updateValue();
+    }
+  }
+  /**
+   * The datetime range from the start time on `first` to the end time on `last` (both the start of a day), clamped to
+   * `min` and `max`. If the times would make the range empty, for example an end time before the start time on a
+   * single day, the end time is reset to 24:00:00. If the range would be longer than `max-range`, the end is moved
+   * back.
+   */
+  makeDateTimeRange(first, last) {
+    const start = this.clampToLimits(atTimeOfDay(first, this._startTime));
+    let end = this.clampToLimits(atTimeOfDay(last, this._endTime));
+    const { maxRange } = this.limits;
+    if (end <= start) {
+      end = this.clampToLimits(atTimeOfDay(last, { hour: 24, minute: 0, second: 0 }));
+    }
+    if (maxRange && start.plus(maxRange) < end) {
+      end = start.plus(maxRange);
+    }
+    return Interval.fromDateTimes(start, end);
+  }
+  dayHovered(val) {
+    const day = this.makeDate(val).startOf("day");
+    if (this._pendingDay && !this.isDayDisabled(day)) {
+      this._hoverDate = day;
+    }
+  }
+  /**
+   * Discard a pending range, so that the user can click a new range start. The value is unchanged. Returns `true` if a
+   * range was pending.
+   *
+   * @internal
+   */
+  cancelPendingRange() {
+    const wasPending = !!this._pendingDay;
+    this.clearPendingRange();
+    return wasPending;
+  }
+  handleKeyDown(event) {
+    if (event.key === "Escape" && this.cancelPendingRange()) {
+      event.preventDefault();
+      event.stopPropagation();
+    }
+  }
+  clearPendingRange() {
+    this._pendingDay = void 0;
+    this._hoverDate = void 0;
+  }
   stepDisplayDate(duration) {
-    this._displayDate = this._displayDate.plus(duration);
+    this._displayDate = this.clampMonth(this._displayDate.plus(duration));
   }
   /**
-   * Generate a list of years for the year select dropdown
+   * Generate a list of years for the year select dropdown, newest first. With no limits, the years are from next year
+   * to six years ago. With `min` or `max`, the list starts or ends at their years, and always includes the year shown.
    */
-  yearOptionsForDate(date) {
+  yearOptions() {
+    const { min, max } = this.limits;
+    const thisYear = DateTime.now().year;
+    let first = min?.year ?? Math.min(thisYear, max?.year ?? thisYear) - 6;
+    let last = max?.year ?? Math.max(thisYear, min?.year ?? thisYear) + 1;
+    if (min || max) {
+      first = Math.min(first, this._displayDate.year);
+      last = Math.max(last, this._displayDate.year);
+    }
     const years = [];
-    for (let y = date.year + 1; y >= date.year - 6; y--) {
+    for (let y = last; y >= first; y--) {
       years.push(y);
     }
     return years;
@@ -88,8 +299,33 @@ class FlowUiCalendar extends FlowRdfElement {
       return void 0;
     }
   }
+  /**
+   * Parse an ISO8601 interval string. In date mode, the interval is widened to whole days in the calendar's timezone:
+   * the start is rounded down to the start of its day and the end is rounded up to the start of the next day. An
+   * invalid or empty interval gives `undefined`.
+   */
+  makeRange(value) {
+    const wholeDays = this.displayMode === "date";
+    return parseDateRange(value, { zone: this.timezone, locale: this.locale, wholeDays });
+  }
+  /**
+   * The days to highlight in range mode: the hover preview while a range is pending, otherwise the selected range.
+   */
+  highlightedDays() {
+    if (this._pendingDay) {
+      const hover = this._hoverDate ?? this._pendingDay;
+      return hover < this._pendingDay ? { first: hover, last: this._pendingDay } : { first: this._pendingDay, last: hover };
+    }
+    if (this._selectedRange) {
+      return {
+        first: this._selectedRange.start.startOf("day"),
+        last: lastDayOfRange(this._selectedRange)
+      };
+    }
+    return void 0;
+  }
   updateValue(emitEvents = true) {
-    const iso = this._selectedDate?.toISO();
+    const iso = this.isRangeMode ? this._selectedRange?.toISO() : this._selectedDate?.toISO();
     this.value = isDefined(iso) ? iso : "";
     if (emitEvents) {
       this.emit("flow-ui-input");
@@ -98,10 +334,12 @@ class FlowUiCalendar extends FlowRdfElement {
   }
   handleHeaderSelectChange(ev) {
     ev.stopPropagation();
-    this._displayDate = this.makeDate().set({
-      year: +this._yearSelect.value,
-      month: +this._monthSelect.value
-    }).startOf("month");
+    this._displayDate = this.clampMonth(
+      this.makeDate().set({
+        year: +this._yearSelect.value,
+        month: +this._monthSelect.value
+      }).startOf("month")
+    );
   }
   handleTimeChange(ev) {
     ev.stopPropagation();
@@ -111,45 +349,88 @@ class FlowUiCalendar extends FlowRdfElement {
     const target = ev.target;
     const unit = target.getAttribute("name");
     this._selectedDate = this._selectedDate.set({ [unit]: +target.value });
+    if (this.displayMode === "datetime") {
+      this._selectedDate = this.clampToLimits(this._selectedDate);
+    }
     this.updateValue();
   }
-  calendarHeaderTemplate() {
+  /**
+   * Handle a change in the Start or End row of a datetime range or a time range. In a datetime range, the start time
+   * applies to the range start and the end time to the last day. The edited time can't pass the other one, so the range
+   * is never empty.
+   */
+  handleRangeTimeChange(ev, row) {
+    ev.stopPropagation();
+    const target = ev.target;
+    const unit = target.getAttribute("name");
+    const time = { ...row === "start" ? this._startTime : this._endTime, [unit]: +target.value };
+    const endOfDay = { hour: 24, minute: 0, second: 0 };
+    if (row === "start") {
+      this._startTime = time;
+    } else {
+      this._endTime = time.hour >= 24 ? endOfDay : time;
+    }
+    let first;
+    let last;
+    if (this.isTimeRangeMode) {
+      first = last = (this._selectedRange?.start ?? this.makeDate()).startOf("day");
+    } else if (this._selectedRange && !this._pendingDay) {
+      first = this._selectedRange.start.startOf("day");
+      last = lastDayOfRange(this._selectedRange);
+    } else {
+      return;
+    }
+    let start = this.clampToLimits(atTimeOfDay(first, this._startTime));
+    let end = this.clampToLimits(atTimeOfDay(last, this._endTime));
+    if (end <= start) {
+      if (row === "start") {
+        start = end.minus({ seconds: 1 });
+      } else {
+        end = start.plus({ seconds: 1 });
+      }
+    }
+    const { maxRange } = this.limits;
+    if (maxRange && start.plus(maxRange) < end) {
+      if (row === "start") {
+        start = end.minus(maxRange);
+      } else {
+        end = start.plus(maxRange);
+      }
+    }
+    const range = Interval.fromDateTimes(start, end);
+    if (range.isValid) {
+      this._selectedRange = range;
+      this._startTime = { hour: start.hour, minute: start.minute, second: start.second };
+      this._endTime = endTimeOfRange(range);
+      this.updateValue();
+    }
+  }
+  /**
+   * The header for the month at `index`. The first month has the month and year selects and the second month has a
+   * static label. The previous button is on the first month and the next button on the last. In the two-month view, a
+   * hidden button takes the place of each missing button, so the month label stays centered.
+   */
+  calendarHeaderTemplate(month, index) {
     const locale = isStringFull(this.locale) ? this.locale : void 0;
     const monthsShort = Info.months("short", { locale });
+    const isFirst = index === 0;
+    const isLast = index === this.monthCount - 1;
+    const { first, last } = this.monthLimits;
     return html`
       <div class="calendar__header">
         <flow-ui-icon-button
+          class=${classMap({ "calendar__header-button--hidden": !isFirst })}
+          ?disabled=${!!first && this._displayDate <= first}
           name="chevron-left"
           library="system"
           @click=${() => this.stepDisplayDate({ month: -1 })}
         ></flow-ui-icon-button>
-        <flow-ui-select
-          inline
-          sync="width"
-          class="calendar__month-select calendar__header-select"
-          value=${this._displayDate.month}
-          @flow-ui-change=${this.handleHeaderSelectChange}
-        >
-          ${monthsShort.map(
-      (month, index) => html`
-              <flow-ui-option value=${index + 1}>${month}</flow-ui-option>
-            `
-    )}
-        </flow-ui-select>
-        <flow-ui-select
-          inline
-          sync="width"
-          class="calendar__year-select calendar__header-select"
-          value=${this._displayDate.year}
-          @flow-ui-change=${this.handleHeaderSelectChange}
-        >
-          ${this.yearOptionsForDate(DateTime.now()).map(
-      (year) => html`
-              <flow-ui-option value=${year}>${year}</flow-ui-option>
-            `
-    )}
-        </flow-ui-select>
+        ${isFirst ? this.headerSelectsTemplate(monthsShort) : html`
+              <span class="calendar__header-month">${monthsShort[month.month - 1]} ${month.year}</span>
+            `}
         <flow-ui-icon-button
+          class=${classMap({ "calendar__header-button--hidden": !isLast })}
+          ?disabled=${!!last && this._displayDate >= last}
           name="chevron-right"
           library="system"
           @click=${() => this.stepDisplayDate({ month: 1 })}
@@ -157,6 +438,42 @@ class FlowUiCalendar extends FlowRdfElement {
       </div>
     `;
   }
+  headerSelectsTemplate(monthsShort) {
+    return html`
+      <flow-ui-select
+        inline
+        sync="width"
+        class="calendar__month-select calendar__header-select"
+        value=${this._displayDate.month}
+        @flow-ui-change=${this.handleHeaderSelectChange}
+      >
+        ${monthsShort.map(
+      (month, index) => html`
+            <flow-ui-option value=${index + 1} ?disabled=${this.isMonthDisabled(index + 1)}>${month}</flow-ui-option>
+          `
+    )}
+      </flow-ui-select>
+      <flow-ui-select
+        inline
+        sync="width"
+        class="calendar__year-select calendar__header-select"
+        value=${this._displayDate.year}
+        @flow-ui-change=${this.handleHeaderSelectChange}
+      >
+        ${this.yearOptions().map(
+      (year) => html`
+            <flow-ui-option value=${year}>${year}</flow-ui-option>
+          `
+    )}
+      </flow-ui-select>
+    `;
+  }
+  /** Whether a month of the year shown is outside the months the user can navigate to. */
+  isMonthDisabled(month) {
+    const { first, last } = this.monthLimits;
+    const date = this._displayDate.set({ month });
+    return !!first && date < first || !!last && date > last;
+  }
   dayOfWeekGridTemplate() {
     const locale = isStringFull(this.locale) ? this.locale : void 0;
     const days = Info.weekdays("narrow", { locale });
@@ -168,102 +485,162 @@ class FlowUiCalendar extends FlowRdfElement {
     )}
     `;
   }
-  dayGridTemplate() {
-    const today = this.makeDate();
-    const startOfMonth = this._displayDate.startOf("month");
-    const endOfMonth = this._displayDate.endOf("month");
+  /**
+   * The days shown in the grid for a month, including the filler days from the adjacent months that complete the
+   * first and last weeks. In the two-month view, the filler days between the two months are hidden, because the other
+   * month shows them.
+   */
+  daysForMonth(month, hideLeadingFiller = false, hideTrailingFiller = false) {
+    const today = this.makeDate().startOf("day");
+    const highlighted = this.isRangeMode ? this.highlightedDays() : void 0;
+    const limits = this.limits;
+    const startOfMonth = month.startOf("month");
+    const endOfMonth = month.endOf("month");
     const calendarStart = startOfMonth.startOf("week");
     const calendarEnd = endOfMonth.endOf("week");
-    const daysInMonth = this._displayDate.daysInMonth;
     const days = [];
-    for (let date = calendarStart; date < startOfMonth; date = date.plus({ day: 1 })) {
-      days.push({
-        day: date.toFormat("d"),
-        date: date.toISO(),
-        isFiller: true,
-        today: date === today,
-        selected: !!this._selectedDate && date.startOf("day").equals(this._selectedDate.startOf("day"))
-      });
-    }
-    for (let day = 1; day <= daysInMonth; day++) {
-      const date = startOfMonth.plus({ days: day - 1 }).startOf("day");
-      days.push({
-        day: date.toFormat("d"),
-        date: date.toISO(),
-        isFiller: false,
-        today: date.startOf("day").equals(today.startOf("day")),
-        selected: !!this._selectedDate && date.startOf("day").equals(this._selectedDate.startOf("day"))
-      });
-    }
-    for (let date = endOfMonth.plus({ day: 1 }).startOf("day"); date < calendarEnd; date = date.plus({ day: 1 })) {
+    for (let date = calendarStart; date < calendarEnd; date = date.plus({ days: 1 }).startOf("day")) {
+      const column = days.length % 7;
+      const hidden = hideLeadingFiller && date < startOfMonth || hideTrailingFiller && date > endOfMonth;
+      const inRange = !hidden && !!highlighted && date >= highlighted.first && date <= highlighted.last;
       days.push({
         day: date.toFormat("d"),
         date: date.toISO(),
-        isFiller: true,
-        today: date.startOf("day").equals(today.startOf("day")),
-        selected: !!this._selectedDate && date.startOf("day").equals(this._selectedDate.startOf("day"))
+        isFiller: date < startOfMonth || date > endOfMonth,
+        hidden,
+        today: date.equals(today),
+        disabled: this.isDayDisabled(date, limits),
+        selected: !this.isRangeMode && !!this._selectedDate && date.equals(this._selectedDate.startOf("day")),
+        rangeStart: inRange && +date === +highlighted.first,
+        rangeLast: inRange && +date === +highlighted.last,
+        inRange,
+        // The range band also has rounded ends next to the hidden days
+        rowStart: column === 0 || hideLeadingFiller && +date === +startOfMonth,
+        rowEnd: column === 6 || hideTrailingFiller && +date === +endOfMonth.startOf("day")
       });
     }
+    return days;
+  }
+  dayGridTemplate(month, index) {
+    const days = this.daysForMonth(month, index > 0, index < this.monthCount - 1);
     return html`
       ${days.map(
-      (day) => html`
-          <button
-            class=${classMap({
+      (day) => day.hidden ? html`
+              <span class="calendar__day-placeholder"></span>
+            ` : html`
+              <button
+                class=${classMap({
         calendar__day: true,
         "calendar__day--filler": day.isFiller,
         "calendar__day--today": day.today,
-        "calendar__day--selected": day.selected
+        "calendar__day--disabled": day.disabled,
+        "calendar__day--selected": day.selected,
+        "calendar__day--range-start": day.rangeStart,
+        "calendar__day--range-last": day.rangeLast,
+        "calendar__day--in-range": day.inRange,
+        "calendar__day--range-preview": day.inRange && !!this._pendingDay,
+        "calendar__day--row-start": day.rowStart,
+        "calendar__day--row-end": day.rowEnd
       })}
-            value=${day.date}
-            @click=${() => this.dateClicked(day.date)}
-          >
-            ${day.day}
-          </button>
-        `
+                value=${day.date}
+                ?disabled=${day.disabled}
+                @click=${() => this.dateClicked(day.date)}
+                @mouseenter=${() => this.dayHovered(day.date)}
+                @focus=${() => this.dayHovered(day.date)}
+              >
+                ${day.day}
+              </button>
+            `
     )}
     `;
   }
+  monthTemplate(index) {
+    const month = this._displayDate.plus({ months: index });
+    return html`
+      <div class="calendar__month">
+        ${this.calendarHeaderTemplate(month, index)}
+        <div class="calendar__grid" @mouseleave=${this.handleGridMouseLeave}>
+          ${this.dayOfWeekGridTemplate()} ${this.dayGridTemplate(month, index)}
+        </div>
+      </div>
+    `;
+  }
+  handleGridMouseLeave() {
+    if (this._pendingDay) {
+      this._hoverDate = void 0;
+    }
+  }
+  /** The hour, minute and second inputs for `time`. */
+  timeInputsTemplate(time, onChange, maxHour = 23) {
+    const size = this.size === "small" ? "small" : "medium";
+    return html`
+      <flow-ui-input
+        filled
+        type="number"
+        size=${size}
+        name="hour"
+        min="0"
+        max=${maxHour}
+        format="02"
+        class="calendar__time-input"
+        .value=${live(String(time.hour))}
+        @flow-ui-change=${onChange}
+      ></flow-ui-input>
+      <span class="calendar__time-separator">:</span>
+      <flow-ui-input
+        filled
+        type="number"
+        size=${size}
+        name="minute"
+        min="0"
+        max="59"
+        format="02"
+        class="calendar__time-input"
+        .value=${live(String(time.minute))}
+        @flow-ui-change=${onChange}
+      ></flow-ui-input>
+      <span class="calendar__time-separator">:</span>
+      <flow-ui-input
+        filled
+        type="number"
+        size=${size}
+        name="second"
+        min="0"
+        max="59"
+        format="02"
+        class="calendar__time-input"
+        .value=${live(String(time.second))}
+        @flow-ui-change=${onChange}
+      ></flow-ui-input>
+    `;
+  }
+  /**
+   * The time inputs: one row in single mode, or the Start and End rows of a datetime range or a time range. The Start
+   * and End rows are stacked, except in a datetime range in the two-month view.
+   */
   timeTemplate() {
+    if (this.isDateTimeRangeMode || this.isTimeRangeMode) {
+      const isSplit = this.isDateTimeRangeMode && this.monthCount === 2;
+      return html`
+        <div class=${classMap({ "calendar__time-rows": true, "calendar__time-rows--split": isSplit })}>
+          <div class="calendar__time-container calendar__time-container--range">
+            <span class="calendar__time-label">${this.localize.term("rangeStartTime")}</span>
+            ${this.timeInputsTemplate(this._startTime, (ev) => this.handleRangeTimeChange(ev, "start"))}
+          </div>
+          <div class="calendar__time-container calendar__time-container--range">
+            <span class="calendar__time-label">${this.localize.term("rangeEndTime")}</span>
+            ${this.timeInputsTemplate(this._endTime, (ev) => this.handleRangeTimeChange(ev, "end"), 24)}
+          </div>
+        </div>
+      `;
+    }
+    const date = this._selectedDate;
     return html`
       <div class="calendar__time-container">
-        <flow-ui-input
-          filled
-          type="number"
-          size=${this.size === "small" ? "small" : "medium"}
-          name="hour"
-          min="0"
-          max="23"
-          format="02"
-          class="calendar__time-input"
-          value=${this._selectedDate ? this._selectedDate.hour : 0}
-          @flow-ui-change=${this.handleTimeChange}
-        ></flow-ui-input>
-        <span class="calendar__time-separator">:</span>
-        <flow-ui-input
-          filled
-          type="number"
-          size=${this.size === "small" ? "small" : "medium"}
-          name="minute"
-          min="0"
-          max="59"
-          format="02"
-          class="calendar__time-input"
-          value=${this._selectedDate ? this._selectedDate.minute : 0}
-          @flow-ui-change=${this.handleTimeChange}
-        ></flow-ui-input>
-        <span class="calendar__time-separator">:</span>
-        <flow-ui-input
-          filled
-          type="number"
-          size=${this.size === "small" ? "small" : "medium"}
-          name="second"
-          min="0"
-          max="59"
-          format="02"
-          class="calendar__time-input"
-          value=${this._selectedDate ? this._selectedDate.second : 0}
-          @flow-ui-change=${this.handleTimeChange}
-        ></flow-ui-input>
+        ${this.timeInputsTemplate(
+      { hour: date?.hour ?? 0, minute: date?.minute ?? 0, second: date?.second ?? 0 },
+      this.handleTimeChange
+    )}
       </div>
     `;
   }
@@ -273,16 +650,19 @@ class FlowUiCalendar extends FlowRdfElement {
     return html`
       <div
         part="base"
+        @keydown=${this.handleKeyDown}
         class=${classMap({
       calendar: true,
       "calendar--small": this.size === "small",
       "calendar--medium": this.size === "medium",
-      "calendar--large": this.size === "large"
+      "calendar--large": this.size === "large",
+      "calendar--two-months": this.monthCount === 2 && showCalendar
     })}
       >
         ${showCalendar ? html`
-              ${this.calendarHeaderTemplate()}
-              <div class="calendar__grid">${this.dayOfWeekGridTemplate()} ${this.dayGridTemplate()}</div>
+              <div class="calendar__months">
+                ${Array.from({ length: this.monthCount }, (_, index) => this.monthTemplate(index))}
+              </div>
             ` : nothing}
         ${showTime ? this.timeTemplate() : nothing}
       </div>
@@ -302,12 +682,30 @@ __decorateClass([
 __decorateClass([
   state()
 ], FlowUiCalendar.prototype, "_selectedDate", 2);
+__decorateClass([
+  state()
+], FlowUiCalendar.prototype, "_selectedRange", 2);
+__decorateClass([
+  state()
+], FlowUiCalendar.prototype, "_pendingDay", 2);
+__decorateClass([
+  state()
+], FlowUiCalendar.prototype, "_hoverDate", 2);
+__decorateClass([
+  state()
+], FlowUiCalendar.prototype, "_startTime", 2);
+__decorateClass([
+  state()
+], FlowUiCalendar.prototype, "_endTime", 2);
 __decorateClass([
   property({ reflect: true })
 ], FlowUiCalendar.prototype, "value", 2);
 __decorateClass([
   property({ attribute: "display-mode" })
 ], FlowUiCalendar.prototype, "displayMode", 2);
+__decorateClass([
+  property({ type: Boolean, reflect: true })
+], FlowUiCalendar.prototype, "range", 2);
 __decorateClass([
   property()
 ], FlowUiCalendar.prototype, "timezone", 2);
@@ -317,11 +715,29 @@ __decorateClass([
 __decorateClass([
   property()
 ], FlowUiCalendar.prototype, "size", 2);
+__decorateClass([
+  property({ type: Number })
+], FlowUiCalendar.prototype, "months", 2);
+__decorateClass([
+  property()
+], FlowUiCalendar.prototype, "min", 2);
+__decorateClass([
+  property()
+], FlowUiCalendar.prototype, "max", 2);
+__decorateClass([
+  property({ attribute: "max-range" })
+], FlowUiCalendar.prototype, "maxRange", 2);
 __decorateClass([
   watch("value", { waitUntilFirstUpdate: true })
 ], FlowUiCalendar.prototype, "handleValueChange", 1);
 __decorateClass([
   watch(["timezone"], { waitUntilFirstUpdate: true })
 ], FlowUiCalendar.prototype, "handleTimezoneChange", 1);
+__decorateClass([
+  watch("range", { waitUntilFirstUpdate: true })
+], FlowUiCalendar.prototype, "handleRangeChange", 1);
+__decorateClass([
+  watch("displayMode", { waitUntilFirstUpdate: true })
+], FlowUiCalendar.prototype, "handleDisplayModeChange", 1);
 
 export { FlowUiCalendar as default };