@12-apps/ui 3.0.0 → 3.2.0

package/src/components/form/DateRangePicker/DateRangePicker.quick.ts

@@ -0,0 +1,97 @@
+/**
+ * The quick-pick column's default list, and how to relabel it.
+ *
+ * These are DOMAIN-FREE on purpose: every one of them is derivable from "today"
+ * and the calendar, so the design system can ship them without knowing what the
+ * range is for. A product's own periods (a fiscal quarter, "since the store
+ * opened", the last closed month) are a `quickRanges` array the caller passes —
+ * the prop exists so that list never has to be smuggled in here.
+ *
+ * "Last N days" INCLUDES today, which is the reading every dashboard in the
+ * wild uses: on the 10th, "last 7 days" is the 4th through the 10th, not the
+ * 3rd through the 9th.
+ */
+import {
+  shiftDay,
+  startOfMonthDay,
+  startOfQuarterDay,
+  startOfWeekDay,
+  startOfYearDay,
+} from './DateRangePicker.dates';
+import type { QuickRange, QuickRangeContext } from './DateRangePicker.types';
+
+/**
+ * The ids the built-in list uses. Stable API: a caller keys off these to map a
+ * quick pick onto something of its own (a stored preset, an event name), and
+ * renaming one is a breaking change in a way that renaming a label is not.
+ */
+export const QUICK_RANGE_IDS = [
+  'today',
+  'yesterday',
+  'this-week',
+  'last-7-days',
+  'this-month',
+  'last-30-days',
+  'this-quarter',
+  'this-year',
+  'last-365-days',
+] as const;
+
+export type QuickRangeId = (typeof QUICK_RANGE_IDS)[number];
+
+/** English defaults. Every one is replaceable through {@link createQuickRanges}. */
+export const DEFAULT_QUICK_RANGE_LABELS: Record<QuickRangeId, string> = {
+  today: 'Today',
+  yesterday: 'Yesterday',
+  'this-week': 'This week',
+  'last-7-days': 'Last 7 days',
+  'this-month': 'This month',
+  'last-30-days': 'Last 30 days',
+  'this-quarter': 'This quarter',
+  'this-year': 'This year',
+  'last-365-days': 'Last 365 days',
+};
+
+/** A window that ends today and reaches back `days` days, today included. */
+const trailing =
+  (days: number) =>
+  ({ today }: QuickRangeContext) => ({ from: shiftDay(today, 1 - days), to: today });
+
+/** A window from the start of some period through today. */
+const sinceStartOf =
+  (start: (context: QuickRangeContext) => string) => (context: QuickRangeContext) => ({
+    from: start(context),
+    to: context.today,
+  });
+
+const RESOLVERS: Record<QuickRangeId, QuickRange['resolve']> = {
+  today: trailing(1),
+  yesterday: ({ today }) => ({ from: shiftDay(today, -1), to: shiftDay(today, -1) }),
+  'this-week': sinceStartOf(({ today, weekStartsOn }) => startOfWeekDay(today, weekStartsOn)),
+  'last-7-days': trailing(7),
+  'this-month': sinceStartOf(({ today }) => startOfMonthDay(today)),
+  'last-30-days': trailing(30),
+  'this-quarter': sinceStartOf(({ today }) => startOfQuarterDay(today)),
+  'this-year': sinceStartOf(({ today }) => startOfYearDay(today)),
+  'last-365-days': trailing(365),
+};
+
+/**
+ * The built-in quick ranges, optionally relabelled.
+ *
+ * Relabelling rather than rebuilding is the point: a Portuguese host wants
+ * "Este mês" over the same month-to-date arithmetic, and re-deriving the dates
+ * to get the word is how two lists that claim the same thing start disagreeing.
+ */
+export function createQuickRanges(
+  labels: Partial<Record<QuickRangeId, string>> = {},
+): QuickRange[] {
+  return QUICK_RANGE_IDS.map((id) => ({
+    id,
+    label: labels[id] ?? DEFAULT_QUICK_RANGE_LABELS[id],
+    resolve: RESOLVERS[id],
+  }));
+}
+
+/** The list a picker uses when the caller says nothing. */
+export const DEFAULT_QUICK_RANGES: QuickRange[] = createQuickRanges();

package/src/components/form/DateRangePicker/DateRangePicker.range.ts

@@ -0,0 +1,105 @@
+/**
+ * Judging a draft, and saying so in words.
+ *
+ * The picker never repairs what it is given. A reversed pair is not silently
+ * swapped and an over-long one is not clipped to the cap: both are reported,
+ * because a control that returns a different range from the one on screen is
+ * indistinguishable from one that ignored you. The caller reads
+ * {@link DateRangeStatus} and keeps its own confirm button shut.
+ */
+import { isoToBr } from '../../data-display/DataViews/data-views-day-input';
+
+import { dayCount, isAfterDay } from './DateRangePicker.dates';
+import type {
+  DateRangePickerMessages,
+  DateRangeDraft,
+  DateRangeStatus,
+  QuickRange,
+  QuickRangeContext,
+  ResolvedQuickRange,
+} from './DateRangePicker.types';
+
+/**
+ * Whether a draft is a window this picker will hand over.
+ *
+ * Exported because the caller needs the same verdict the picker shows: a dialog
+ * disabling its "Apply" button must not re-derive "is this legal" from the two
+ * strings, or the two answers drift and the button ends up enabled over a
+ * message saying the range is impossible.
+ */
+export function resolveDayRange(
+  draft: DateRangeDraft,
+  maxRangeDays?: number,
+): DateRangeStatus {
+  const { from, to } = draft;
+  if (!from || !to) return { ok: false, problem: 'incomplete', days: 0 };
+  if (isAfterDay(from, to)) return { ok: false, problem: 'reversed', days: 0 };
+
+  const days = dayCount(from, to);
+  if (maxRangeDays !== undefined && days > maxRangeDays) {
+    return { ok: false, problem: 'over-max', days };
+  }
+  return { ok: true, window: { from, to }, days };
+}
+
+/**
+ * The English defaults.
+ *
+ * The summary prints the days in the SAME `dd/mm/aaaa` the two fields are
+ * masked to, rather than in the host locale's order. One control cannot show
+ * the same date two ways: an `en-US` host formatting the summary as `08/05`
+ * over a field reading `05/08` leaves the reader to work out which of the two
+ * is lying. A host that wants its own order replaces `messages.summary`, which
+ * moves both halves of the decision to the same place.
+ */
+export function defaultMessages(): DateRangePickerMessages {
+  return {
+    from: 'Start date',
+    to: 'End date',
+    quickRanges: 'Quick ranges',
+    incomplete: 'Choose both dates.',
+    reversed: 'The end date must be on or after the start date.',
+    overMax: ({ maxRangeDays }) => `Choose a range of at most ${maxRangeDays} days.`,
+    summary: ({ from, to }) => `${isoToBr(from)} – ${isoToBr(to)}`,
+  };
+}
+
+/** The line under the fields: the chosen window, or why there isn't one. */
+export function statusMessage(
+  status: DateRangeStatus,
+  messages: DateRangePickerMessages,
+  maxRangeDays: number | undefined,
+): string {
+  if (status.ok) return messages.summary(status.window);
+  if (status.problem === 'incomplete') return messages.incomplete;
+  if (status.problem === 'reversed') return messages.reversed;
+  return messages.overMax({ maxRangeDays: maxRangeDays ?? status.days, days: status.days });
+}
+
+/** Every quick range with its window, its length, and whether it is over cap. */
+export function resolveQuickRanges(
+  quickRanges: QuickRange[],
+  context: QuickRangeContext,
+  maxRangeDays: number | undefined,
+): ResolvedQuickRange[] {
+  return quickRanges.map((quickRange) => {
+    const window = quickRange.resolve(context);
+    const days = dayCount(window.from, window.to);
+    return {
+      ...quickRange,
+      window,
+      days,
+      overMax: maxRangeDays !== undefined && days > maxRangeDays,
+    };
+  });
+}
+
+/** The quick range the draft currently IS, if it is exactly one of them. */
+export function activeQuickRangeId(
+  options: ResolvedQuickRange[],
+  draft: DateRangeDraft,
+): string | undefined {
+  return options.find(
+    (option) => option.window.from === draft.from && option.window.to === draft.to,
+  )?.id;
+}

package/src/components/form/DateRangePicker/DateRangePicker.tsx

@@ -0,0 +1,250 @@
+'use client';
+
+/**
+ * Three views of ONE range: a calendar, a quick-pick column, and two typed
+ * dates. Change any and the other two follow.
+ *
+ * WHY IT EXISTS: a range calendar alone makes "this quarter" cost two clicks,
+ * a month of paging, and a mental note of which day a quarter starts on; a list
+ * of presets alone cannot express "the 3rd to the 19th"; and typed fields alone
+ * make you spell out a window you can see. Each of the three is the fastest
+ * route to a different range, so the control offers all three over one value
+ * rather than picking a favourite.
+ *
+ * WHAT IT DOES NOT KNOW: anything about the data behind the range. No preset
+ * list of a product's own, no ceiling of its own, no notion of whose clock
+ * "today" runs on — `quickRanges`, `maxRangeDays` and `timeZone` are props, and
+ * a consumer that needs its own periods passes them rather than teaching this
+ * file about its domain. The calendar is `Calendar` in `selectionMode="range"`,
+ * not a second implementation of one.
+ *
+ * The value is a DRAFT (`{ from, to }`, either end possibly null) rather than a
+ * finished window, so a half-picked or impossible range has somewhere to live
+ * while it is being fixed. Every `onChange` carries the verdict with it.
+ */
+import { Box, Paper, useMediaQuery } from '@mui/material';
+import type { SxProps, Theme } from '@mui/material';
+import React from 'react';
+
+import { Calendar } from '../Calendar';
+
+import { toLocalDay } from './DateRangePicker.dates';
+import { useDateRangePicker } from './DateRangePicker.hooks';
+import { DEFAULT_QUICK_RANGES } from './DateRangePicker.quick';
+import type { DateRangeDraft, DateRangePickerProps, WeekStart } from './DateRangePicker.types';
+import { DateRangeFields } from './DateRangePickerFields';
+import { DateRangeQuickList } from './DateRangePickerQuickList';
+
+const CALENDAR_CLASS = 'date-range-picker__calendar';
+
+/** Below this the picker is a phone layout. MUI's own `md`, written out. */
+const NARROW_QUERY = '(max-width:899.95px)';
+
+const ROOT_SX: SxProps<Theme> = {
+  display: 'inline-flex',
+  flexDirection: 'column',
+  gap: 2,
+  p: 2,
+  maxWidth: '100%',
+  // `Calendar` renders its own `Paper` with 24px of padding. Nested in this one
+  // that reads as a box inside a box, so the inner frame is flattened here
+  // through the className hook the component exposes for exactly this.
+  [`& .${CALENDAR_CLASS}`]: {
+    p: 0,
+    boxShadow: 'none',
+    backgroundColor: 'transparent',
+    backgroundImage: 'none',
+  },
+};
+
+const BODY_SX: SxProps<Theme> = {
+  display: 'flex',
+  // The quick column sits BESIDE the calendar on a wide screen. Narrow, it
+  // moves ABOVE it — `column-reverse`, so the DOM order stays calendar-then-
+  // list (the calendar is the primary control and should be reached first by a
+  // screen reader and by Tab) while the eye meets the quick ranges first, which
+  // is the order the phone mock asks for and the order a thumb wants: nine
+  // one-tap answers before a grid of thirty.
+  //
+  // A side column at 390px would squeeze the day grid to roughly half its width
+  // and make the numbers unreadable. Checked at 390px.
+  flexDirection: { xs: 'column-reverse', md: 'row' },
+  alignItems: { xs: 'stretch', md: 'flex-start' },
+  gap: 2,
+  maxWidth: '100%',
+};
+
+/**
+ * The rule between the calendar and the quick ranges.
+ *
+ * Two lists of dates side by side with only whitespace between them read as one
+ * ragged thing; the rule says which numbers belong to which control. It turns
+ * with the layout — a vertical rule when the list is a column beside the
+ * calendar, a horizontal one when it has moved above it — because a divider
+ * that keeps its axis while the flex direction flips ends up separating nothing.
+ */
+const QUICK_DIVIDER_SX: SxProps<Theme> = {
+  borderColor: 'divider',
+  borderStyle: 'solid',
+  borderWidth: 0,
+  borderLeftWidth: { xs: 0, md: '1px' },
+  borderBottomWidth: { xs: '1px', md: 0 },
+  pl: { xs: 0, md: 2 },
+  pb: { xs: 2, md: 0 },
+  alignSelf: 'stretch',
+};
+
+/** And the rule above the typed pair, which is a third way in, not a caption. */
+const FIELDS_DIVIDER_SX: SxProps<Theme> = {
+  borderTop: '1px solid',
+  borderColor: 'divider',
+  pt: 2,
+};
+
+type Picker = ReturnType<typeof useDateRangePicker>;
+
+/**
+ * How many months to draw.
+ *
+ * A month grid has a floor: seven columns that must stay legible, which is
+ * about 280px. Two of them need 580, so on a phone the consumer's
+ * `numberOfMonths` is not a preference that can be honoured — it is a request
+ * for a layout that does not fit. Capped here rather than left to the consumer,
+ * because the consumer chooses for its own reason (the reports dialog wants two
+ * because a period often crosses a month boundary) and has no way to know the
+ * picker is currently 390px wide.
+ *
+ * A media query rather than an `sx` breakpoint: this decides what to RENDER,
+ * and CSS cannot un-render a second month.
+ *
+ * The query is a LITERAL, not `theme.breakpoints.down('md')`. The callback form
+ * reads the theme from context and throws on a null one, so a consumer that
+ * mounts this outside a `ThemeProvider` would crash — which the unit tests here
+ * do, and which is a fair thing for a consumer to do.
+ */
+function useMonthCount(requested: number | undefined): number | undefined {
+  const narrow = useMediaQuery(NARROW_QUERY);
+  return narrow ? 1 : requested;
+}
+
+/** The grid, in range mode — `Calendar`, never a second implementation of one. */
+function RangeCalendar({
+  picker,
+  value,
+  locale,
+  weekStartsOn,
+  months,
+  maxRangeDays,
+}: {
+  picker: Picker;
+  value: DateRangeDraft;
+  locale: string;
+  weekStartsOn: WeekStart;
+  months: number | undefined;
+  maxRangeDays: number | undefined;
+}): React.JSX.Element {
+  return (
+    <Calendar
+      key={picker.viewNonce}
+      className={CALENDAR_CLASS}
+      selectionMode="range"
+      locale={locale}
+      // One prop drives the grid's first column AND the day "this week" starts
+      // on, so a highlighted week can never begin mid-row.
+      firstDayOfWeek={weekStartsOn}
+      numberOfMonths={months}
+      range={{ start: toLocalDay(value.from), end: toLocalDay(value.to) }}
+      // BOTH callbacks, and the intermediate one does the work: the other fires
+      // only on the click that CLOSES a range, so a picker wired to it alone
+      // would not repaint after the first click.
+      onIntermediateRangeChange={picker.pickOnCalendar}
+      onRangeChange={picker.pickOnCalendar}
+      // The same ceiling the quick list is judged against, so the calendar
+      // cannot hand back a window the control has just called too long.
+      maxRangeLength={maxRangeDays}
+    />
+  );
+}
+
+/** The quick ranges, inside the rule that separates them from the grid. */
+function QuickColumn({
+  picker,
+  maxRangeDays,
+  dataTestId,
+}: {
+  picker: Picker;
+  maxRangeDays: number | undefined;
+  dataTestId: string;
+}): React.JSX.Element | null {
+  if (picker.options.length === 0) return null;
+  return (
+    <Box sx={QUICK_DIVIDER_SX}>
+      <DateRangeQuickList
+        options={picker.options}
+        activeId={picker.activeId}
+        onPick={picker.pickQuick}
+        reasonFor={(option) =>
+          picker.copy.overMax({ maxRangeDays: maxRangeDays ?? option.days, days: option.days })
+        }
+        label={picker.copy.quickRanges}
+        dataTestId={dataTestId}
+      />
+    </Box>
+  );
+}
+
+export function DateRangePicker({
+  value,
+  onChange,
+  timeZone,
+  now,
+  maxRangeDays,
+  weekStartsOn = 0,
+  quickRanges = DEFAULT_QUICK_RANGES,
+  locale = 'en-US',
+  numberOfMonths,
+  messages,
+  dataTestId = 'date-range-picker',
+  className,
+}: DateRangePickerProps): React.JSX.Element {
+  const picker = useDateRangePicker({
+    value,
+    onChange,
+    timeZone,
+    now,
+    maxRangeDays,
+    weekStartsOn,
+    quickRanges,
+    messages,
+  });
+  const months = useMonthCount(numberOfMonths);
+
+  return (
+    <Paper className={className} data-testid={dataTestId} sx={ROOT_SX}>
+      <Box sx={BODY_SX}>
+        <RangeCalendar
+          picker={picker}
+          value={value}
+          locale={locale}
+          weekStartsOn={weekStartsOn}
+          months={months}
+          maxRangeDays={maxRangeDays}
+        />
+        <QuickColumn picker={picker} maxRangeDays={maxRangeDays} dataTestId={dataTestId} />
+      </Box>
+      <Box sx={FIELDS_DIVIDER_SX}>
+        <DateRangeFields
+          value={value}
+          status={picker.status}
+          messages={picker.copy}
+          maxRangeDays={maxRangeDays}
+          onEdit={picker.editBound}
+          statusId={picker.statusId}
+          dataTestId={dataTestId}
+        />
+      </Box>
+    </Paper>
+  );
+}
+
+export default DateRangePicker;

package/src/components/form/DateRangePicker/DateRangePicker.types.ts

@@ -0,0 +1,193 @@
+/**
+ * The vocabulary of a two-ended day range. Everything here is CIVIL — a day on
+ * a stated clock, never an instant — because that is what a range picker picks:
+ * "1 August" is the same day in every zone, and only the question "which day is
+ * TODAY" needs a zone to answer.
+ */
+import type { DateRange } from '../Calendar';
+
+/** One inclusive calendar day as `AAAA-MM-DD`. Sorts lexicographically. */
+export type DayString = string;
+
+/** A complete range: two INCLUSIVE calendar days, `from` on or before `to`. */
+export interface DayWindow {
+  from: DayString;
+  to: DayString;
+}
+
+/**
+ * A range being edited, which may be half-chosen, reversed or too long.
+ *
+ * This — not {@link DayWindow} — is the picker's `value`: a control whose value
+ * could only hold a legal range would have nowhere to put a reader who typed
+ * the end date first, and would have to either discard the keystrokes or lie
+ * about what is on screen. {@link resolveDayRange} says whether a draft is a
+ * usable window.
+ */
+export interface DateRangeDraft {
+  from: DayString | null;
+  to: DayString | null;
+}
+
+/** Why a draft is not a usable window. */
+export type DateRangeProblem =
+  /** One end is missing. */
+  | 'incomplete'
+  /** `from` is after `to`. */
+  | 'reversed'
+  /** Longer than `maxRangeDays`. */
+  | 'over-max';
+
+/** A draft judged against the picker's constraints. `days` is 0 when unknown. */
+export type DateRangeStatus =
+  | { ok: true; window: DayWindow; days: number }
+  | { ok: false; problem: DateRangeProblem; days: number };
+
+/** 0 = Sunday … 6 = Saturday, matching `Date.prototype.getDay`. */
+export type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/** What a quick range resolves against. No `Date`, no zone — the day is done. */
+export interface QuickRangeContext {
+  /** Today, already read on the picker's stated clock. */
+  today: DayString;
+  /** The same week start the calendar grid renders with. */
+  weekStartsOn: WeekStart;
+}
+
+/**
+ * One entry in the quick-pick column.
+ *
+ * `resolve` is a function rather than a stored window so the list survives
+ * midnight and can be defined once at module scope; `id` is stable and is what
+ * a caller matches on when a particular quick range means something to it
+ * (a saved preset, an analytics event) — never the label, which is copy.
+ */
+export interface QuickRange {
+  id: string;
+  label: string;
+  resolve: (context: QuickRangeContext) => DayWindow;
+}
+
+/** A quick range with everything the list needs to draw it. */
+export interface ResolvedQuickRange extends QuickRange {
+  window: DayWindow;
+  /** Inclusive day count of {@link window}. */
+  days: number;
+  /** Longer than the cap: offered, announced, and refused rather than clamped. */
+  overMax: boolean;
+}
+
+/**
+ * Every string the picker renders, so a host in another language replaces copy
+ * instead of forking the component. Defaults are English.
+ */
+export interface DateRangePickerMessages {
+  /** Label of the `from` field. */
+  from: string;
+  /** Label of the `to` field. */
+  to: string;
+  /** Accessible name of the quick-pick group. */
+  quickRanges: string;
+  /** Shown while only one end is chosen. */
+  incomplete: string;
+  /** Shown when the start is after the end. */
+  reversed: string;
+  /** Shown when the range — typed or quick-picked — exceeds the cap. */
+  overMax: (info: { maxRangeDays: number; days: number }) => string;
+  /** The chosen window, in words. */
+  summary: (window: DayWindow) => string;
+}
+
+/** Which of the three views moved the range, and what it moved it to. */
+export interface DateRangeChangeMeta {
+  source: 'quick' | 'calendar' | 'from' | 'to';
+  /** Set only when `source` is `quick`: the {@link QuickRange.id} clicked. */
+  quickRangeId?: string;
+  /** The new draft, already judged — so a caller needs no second validator. */
+  status: DateRangeStatus;
+}
+
+export interface DateRangePickerProps {
+  /** The range being edited. Controlled: the picker keeps no copy of it. */
+  value: DateRangeDraft;
+  onChange: (next: DateRangeDraft, meta: DateRangeChangeMeta) => void;
+  /**
+   * IANA zone (or offset, e.g. `-03:00`) the quick ranges read TODAY on.
+   *
+   * Civil days are zone-free, but "today", "this month" and "this quarter" are
+   * not: at 21:30 on 31 July in São Paulo it is already 1 August in UTC, so a
+   * quarter resolved on the host's clock can name a period the reader's store
+   * has not reached. Defaults to the host's own zone, which is right for a
+   * picker whose data belongs to whoever is looking at it and wrong for one
+   * that reports on somewhere else — pass the zone in that case.
+   */
+  timeZone?: string;
+  /**
+   * The instant TODAY is read from. Defaults to the real clock; a story or a
+   * test freezes it here rather than mocking `Date`.
+   */
+  now?: Date;
+  /**
+   * Longest range the picker will call usable, in inclusive days.
+   *
+   * A quick range longer than this is rendered `aria-disabled` with the reason,
+   * never silently shortened: returning eleven months for a control labelled
+   * "This year" is worse than refusing.
+   */
+  maxRangeDays?: number;
+  /**
+   * First column of the calendar grid AND the day "this week" starts on — one
+   * prop, because a grid that starts on Sunday beside a "this week" that starts
+   * on Monday shows a highlighted block that begins mid-row.
+   *
+   * Defaults to 0 (Sunday), which is what a `pt-BR` calendar renders
+   * (`D S T Q Q S S`) and what Brazilian merchants read. Do not "fix" it to
+   * Monday for the ISO week without changing the locale that goes with it.
+   */
+  weekStartsOn?: WeekStart;
+  /** Replaces the built-in list wholesale. Empty array: no quick column. */
+  quickRanges?: QuickRange[];
+  /** BCP-47 tag for month names, weekday initials and the summary sentence. */
+  locale?: string;
+  /** Months side by side. Defaults to 2, the range calendar's own default. */
+  numberOfMonths?: number;
+  /** Copy overrides, merged over the English defaults. */
+  messages?: Partial<DateRangePickerMessages>;
+  /** Root test id; every part derives from it (`-from`, `-quick-today`, …). */
+  dataTestId?: string;
+  className?: string;
+}
+
+/**
+ * What `useDateRangePicker` reads — the picker's own props, minus the ones that
+ * only decide how it LOOKS (locale, month count, test id, class name).
+ */
+export interface UseDateRangePickerArgs {
+  value: DateRangeDraft;
+  onChange: DateRangePickerProps['onChange'];
+  timeZone: string | undefined;
+  now: Date | undefined;
+  maxRangeDays: number | undefined;
+  weekStartsOn: WeekStart;
+  quickRanges: QuickRange[];
+  messages: Partial<DateRangePickerMessages> | undefined;
+}
+
+/** Everything the component renders from, and every way the range can move. */
+export interface DateRangePickerState {
+  /** Copy with the caller's overrides already merged over the defaults. */
+  copy: DateRangePickerMessages;
+  /** Every quick range resolved against today, with its length and verdict. */
+  options: ResolvedQuickRange[];
+  /** The quick range the draft currently IS, if it is exactly one of them. */
+  activeId: string | undefined;
+  /** The current draft, judged. */
+  status: DateRangeStatus;
+  /** Id of the status line; the two fields point at it. */
+  statusId: string;
+  /** Changes only when the calendar should FOLLOW the range. */
+  viewNonce: number;
+  pickQuick: (option: ResolvedQuickRange) => void;
+  editBound: (which: 'from' | 'to', bound: DayString | null) => void;
+  pickOnCalendar: (range: DateRange) => void;
+}