@12-apps/ui 2.1.0 → 3.1.0

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

@@ -0,0 +1,149 @@
+/**
+ * Civil-day arithmetic for the range picker.
+ *
+ * Two representations meet here and the boundary between them is the whole
+ * point of the file:
+ *
+ *  - `AAAA-MM-DD` — what the picker's value, the quick ranges and any caller
+ *    speak. A day with no instant attached, so it cannot drift.
+ *  - a LOCAL `Date` at NOON — what `Calendar` deals in. Noon (not midnight) is
+ *    `Calendar.dates.normalizeDate`'s own rule: a daylight-saving jump at
+ *    midnight can move a date across a day boundary, and midday never can.
+ *
+ * The arithmetic itself is `Calendar.dates`' — `addDays` and `startOfWeek` are
+ * imported rather than re-written, so a week here starts on the same day the
+ * grid draws it.
+ *
+ * ONE thing needs a time zone: which day is today. Everything after that is
+ * calendar arithmetic that has no clock in it.
+ */
+import { addDays, startOfWeek } from '../Calendar/Calendar.dates';
+
+import type { DayString, WeekStart } from './DateRangePicker.types';
+
+const NOON = 12;
+const MS_PER_DAY = 86_400_000;
+const MONTHS_PER_QUARTER = 3;
+const DAY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/** `[year, month 1-12, day]`, or null when the text is not a day at all. */
+function dayParts(day: DayString): [number, number, number] | null {
+  const parts = DAY_PATTERN.exec(day);
+  if (!parts) return null;
+  return [Number(parts[1]), Number(parts[2]), Number(parts[3])];
+}
+
+const pad = (value: number): string => String(value).padStart(2, '0');
+
+/** `AAAA-MM-DD` from calendar parts. Month is 1-12. */
+function formatDay(year: number, month: number, day: number): DayString {
+  return `${String(year).padStart(4, '0')}-${pad(month)}-${pad(day)}`;
+}
+
+/** A LOCAL `Date` → the day it falls on, read off the same local getters. */
+export function toDayString(date: Date): DayString {
+  return formatDay(date.getFullYear(), date.getMonth() + 1, date.getDate());
+}
+
+/**
+ * `AAAA-MM-DD` → a LOCAL `Date` at noon, or null when the text is not a real
+ * day.
+ *
+ * Deliberately not `new Date(day)`: the spec reads a bare `AAAA-MM-DD` as UTC
+ * midnight, so west of Greenwich it lands on the day BEFORE and every date in
+ * the picker is off by one. The round-trip check is what rejects `2026-02-31`,
+ * which `Date` would otherwise roll silently into March.
+ */
+export function toLocalDay(day: DayString | null | undefined): Date | null {
+  if (!day) return null;
+  const parts = dayParts(day);
+  if (!parts) return null;
+  const date = new Date(parts[0], parts[1] - 1, parts[2], NOON);
+  return toDayString(date) === day ? date : null;
+}
+
+const civilFormatters = new Map<string, Intl.DateTimeFormat>();
+
+function civilFormatter(timeZone: string): Intl.DateTimeFormat {
+  const cached = civilFormatters.get(timeZone);
+  if (cached) return cached;
+  const created = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  });
+  civilFormatters.set(timeZone, created);
+  return created;
+}
+
+/**
+ * The civil day `now` falls on, on `timeZone`'s clock (the host's when absent).
+ *
+ * Read through `formatToParts` rather than by adding an offset to an epoch: the
+ * zone database already knows about every transition, and reconstructing one by
+ * hand is how a picker ends up a day out for exactly one week of the year.
+ */
+export function todayIn(timeZone: string | undefined, now: Date): DayString {
+  if (!timeZone) return toDayString(now);
+  const parts = civilFormatter(timeZone).formatToParts(now);
+  const read = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((part) => part.type === type)?.value ?? '';
+  return `${read('year')}-${read('month')}-${read('day')}`;
+}
+
+/** The same day `days` later (or earlier). */
+export function shiftDay(day: DayString, days: number): DayString {
+  const date = toLocalDay(day);
+  return date ? toDayString(addDays(date, days)) : day;
+}
+
+/** The 1st of `day`'s month. */
+export function startOfMonthDay(day: DayString): DayString {
+  const parts = dayParts(day);
+  return parts ? formatDay(parts[0], parts[1], 1) : day;
+}
+
+/**
+ * The 1st of `day`'s CALENDAR quarter — Jan/Apr/Jul/Oct. Fiscal quarters are a
+ * different thing and belong in a caller's own quick range, not in a default.
+ */
+export function startOfQuarterDay(day: DayString): DayString {
+  const parts = dayParts(day);
+  if (!parts) return day;
+  const month = parts[1] - ((parts[1] - 1) % MONTHS_PER_QUARTER);
+  return formatDay(parts[0], month, 1);
+}
+
+/** The 1st of January of `day`'s year. */
+export function startOfYearDay(day: DayString): DayString {
+  const parts = dayParts(day);
+  return parts ? formatDay(parts[0], 1, 1) : day;
+}
+
+/** The first day of `day`'s week, on the same week start the grid uses. */
+export function startOfWeekDay(day: DayString, weekStartsOn: WeekStart): DayString {
+  const date = toLocalDay(day);
+  return date ? toDayString(startOfWeek(date, weekStartsOn)) : day;
+}
+
+/**
+ * How many days a window covers, both ends INCLUDED — so a single day is 1.
+ *
+ * Measured on UTC epochs rather than on the local dates: the difference between
+ * two local noons can be 23 or 25 hours across a transition, and dividing that
+ * by a fixed day length is how a 30-day window starts reporting 29.96.
+ */
+export function dayCount(from: DayString, to: DayString): number {
+  const start = dayParts(from);
+  const end = dayParts(to);
+  if (!start || !end) return 0;
+  const startMs = Date.UTC(start[0], start[1] - 1, start[2]);
+  const endMs = Date.UTC(end[0], end[1] - 1, end[2]);
+  return Math.round((endMs - startMs) / MS_PER_DAY) + 1;
+}
+
+/** `AAAA-MM-DD` sorts lexicographically, so this needs no parsing at all. */
+export function isAfterDay(a: DayString, b: DayString): boolean {
+  return a > b;
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Everything the picker derives and every way its range can move, kept out of
+ * the component so that file is a layout and this one is the behaviour — the
+ * same split `Calendar.hooks.ts` uses next door.
+ */
+import { useId, useMemo, useState } from 'react';
+
+import { toDayString, todayIn } from './DateRangePicker.dates';
+import {
+  activeQuickRangeId,
+  defaultMessages,
+  resolveDayRange,
+  resolveQuickRanges,
+} from './DateRangePicker.range';
+import type {
+  DateRangeChangeMeta,
+  DateRangeDraft,
+  DateRangePickerState,
+  UseDateRangePickerArgs,
+} from './DateRangePicker.types';
+
+export function useDateRangePicker({
+  value,
+  onChange,
+  timeZone,
+  now,
+  maxRangeDays,
+  weekStartsOn,
+  quickRanges,
+  messages,
+}: UseDateRangePickerArgs): DateRangePickerState {
+  const statusId = useId();
+  // `Calendar` reads which month to open on from the range it is handed, and
+  // only when it MOUNTS. Bumping this key remounts it, which is how the other
+  // two views move it. It changes for a quick pick and for a typed date and
+  // NEVER for a click inside the grid — a calendar that jumped under the
+  // pointer picking in it would be unusable.
+  const [viewNonce, setViewNonce] = useState(0);
+
+  const copy = useMemo(() => ({ ...defaultMessages(), ...messages }), [messages]);
+  const today = useMemo(() => todayIn(timeZone, now ?? new Date()), [timeZone, now]);
+  const options = useMemo(
+    () => resolveQuickRanges(quickRanges, { today, weekStartsOn }, maxRangeDays),
+    [quickRanges, today, weekStartsOn, maxRangeDays],
+  );
+  const status = useMemo(() => resolveDayRange(value, maxRangeDays), [value, maxRangeDays]);
+
+  const emit = (
+    next: DateRangeDraft,
+    source: DateRangeChangeMeta['source'],
+    quickRangeId?: string,
+  ): void => {
+    onChange(next, {
+      source,
+      ...(quickRangeId ? { quickRangeId } : {}),
+      // Judged here, once. A caller left to re-derive "is this usable" is a
+      // second opinion able to disagree with the message on screen.
+      status: resolveDayRange(next, maxRangeDays),
+    });
+  };
+
+  return {
+    copy,
+    options,
+    activeId: activeQuickRangeId(options, value),
+    status,
+    statusId,
+    viewNonce,
+    pickQuick: (option) => {
+      setViewNonce((nonce) => nonce + 1);
+      emit({ from: option.window.from, to: option.window.to }, 'quick', option.id);
+    },
+    editBound: (which, bound) => {
+      setViewNonce((nonce) => nonce + 1);
+      emit({ ...value, [which]: bound }, which);
+    },
+    pickOnCalendar: (range) => {
+      emit(
+        {
+          from: range.start ? toDayString(range.start) : null,
+          to: range.end ? toDayString(range.end) : null,
+        },
+        'calendar',
+      );
+    },
+  };
+}

package/src/components/form/DateRangePicker/DateRangePicker.md

@@ -0,0 +1,228 @@
+# DateRangePicker
+
+Three views of ONE day range — a range calendar, a quick-pick column, and two
+typed `dd/mm/aaaa` fields. Change any and the other two follow.
+
+## Purpose
+
+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". Typed fields alone make you spell out a
+window you can already see. Each of the three is the fastest route to a
+*different* range, so this control offers all three over one value instead of
+picking a favourite.
+
+It is a design-system control and knows nothing about the data behind the
+range. The quick list, the maximum length and the clock "today" is read on are
+all props — a consumer with its own periods passes them rather than teaching
+this component about its domain.
+
+## Not a fork of Calendar
+
+The calendar half **is** [`Calendar`](../Calendar/Calendar.md) in
+`selectionMode="range"`. The hover preview, the keyboard grid, backwards
+selection and the length check all come from there. This component composes it;
+it does not reimplement it.
+
+The typed fields are `DayBoundInput`, the masked `dd/mm/aaaa` field the data
+views already use — imported from inside the package rather than exported,
+because a second masked date field would mean a second set of rules for what
+backspace does.
+
+## Public API
+
+```ts
+interface DateRangePickerProps {
+  value: DateRangeDraft;                    // { from: string | null; to: string | null }
+  onChange: (next: DateRangeDraft, meta: DateRangeChangeMeta) => void;
+  timeZone?: string;                        // IANA zone (or offset) TODAY is read on
+  now?: Date;                               // freeze the clock (stories, tests)
+  maxRangeDays?: number;                    // longest usable range, inclusive days
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6; // default 0 (Sunday)
+  quickRanges?: QuickRange[];               // default: the nine below; [] hides the column
+  locale?: string;                          // month names / weekday initials
+  numberOfMonths?: number;                  // default 2
+  messages?: Partial<DateRangePickerMessages>;
+  dataTestId?: string;                      // default 'date-range-picker'
+  className?: string;
+}
+```
+
+### The value is a DRAFT, not a window
+
+`value` is `{ from, to }` with either end possibly `null`, and it accepts a pair
+that is reversed or too long. A control whose value could only hold a legal
+range has nowhere to put a reader who typed the end date first, and has to
+either discard the keystrokes or lie about what is on screen.
+
+Every `onChange` carries the verdict with it:
+
+```ts
+interface DateRangeChangeMeta {
+  source: 'quick' | 'calendar' | 'from' | 'to';
+  quickRangeId?: string;      // set only when source is 'quick'
+  status: DateRangeStatus;    // { ok: true, window, days } | { ok: false, problem, days }
+}
+```
+
+`resolveDayRange(draft, maxRangeDays)` is exported so a caller's confirm button
+reads the SAME verdict rather than re-deriving "is this usable" from the two
+strings and drifting from the message on screen.
+
+`quickRangeId` is what lets a caller express a pick as its own thing. The
+reports surface uses it to apply its real `today` preset when "Hoje" is chosen,
+so the period afterwards reads `Hoje` and not `Personalizado…`.
+
+## Quick ranges
+
+Nine built-ins, all derivable from today and the calendar alone:
+
+| id | window |
+|---|---|
+| `today` | today |
+| `yesterday` | the day before today |
+| `this-week` | the `weekStartsOn` day of this week → today |
+| `last-7-days` | today and the 6 days before it |
+| `this-month` | the 1st of this month → today |
+| `last-30-days` | today and the 29 days before it |
+| `this-quarter` | the 1st of this CALENDAR quarter (Jan/Apr/Jul/Oct) → today |
+| `this-year` | 1 January → today |
+| `last-365-days` | today and the 364 days before it |
+
+"Last N days" **includes** today: on the 10th, "last 7 days" is the 4th through
+the 10th. Quarters are calendar quarters; a fiscal quarter is a caller's own
+`quickRanges` entry, not a variant of this one.
+
+`createQuickRanges({ today: 'Hoje', … })` relabels the built-ins without
+re-deriving their arithmetic — which is how two lists that claim the same thing
+start disagreeing. `quickRanges` replaces the list wholesale; `[]` removes the
+column.
+
+## Time zone
+
+Civil days are zone-free; **which day is today is not**. At 21:30 on 31 July in
+São Paulo it is already 1 August in UTC, so "this month" resolved on the host's
+clock can name a period the reader's store has not reached. `timeZone` is read
+for exactly one thing — today — and every quick range hangs off it.
+
+Absent, the host's own zone is used. That is right for a picker over the
+reader's own data and wrong for one reporting on somewhere else.
+
+## Maximum length
+
+`maxRangeDays` is an inclusive day count and is enforced in three places at
+once:
+
+- a quick range longer than it is `aria-disabled`, keeps its place in the tab
+  order, and renders the reason under its label;
+- the calendar is given the same ceiling, so it cannot close a range over it;
+- a typed pair over it is reported as `problem: 'over-max'` with the reason in
+  the status line.
+
+**Nothing is ever clamped.** Handing back eleven months for a control labelled
+"This year" is worse than refusing: the reader gets a number for a period they
+did not ask for and nothing on screen says so.
+
+## When a typed date commits
+
+The moment it is a **whole, real day** — eight digits naming a date that exists.
+
+- Not on every keystroke: `2026` passes through `0002`, `0020` and `0202`, each
+  a legal year, and committing those sends the calendar to the year 20 while the
+  reader is still typing.
+- Not only on blur: someone who types a date and looks at the calendar to check
+  it would see the old month until they clicked somewhere else.
+- Half-typed text stays in the field and changes nothing; leaving the field
+  discards it and shows what the range actually is.
+- Enter needs no special case — by the time it can be pressed, the date has
+  already committed.
+
+## Which month the calendar shows
+
+`Calendar` reads its opening month from the range it is handed, and only when it
+mounts. The picker remounts it when a **quick pick** or a **typed date** moves
+the range, and never when a day inside the grid is clicked — a calendar that
+jumped under the pointer picking in it would be unusable.
+
+So the grid follows the range's **start**. Picking "This year" in August moves
+it to January, because that is where the range now begins.
+
+## Layout
+
+Calendar first, quick column beside it (`md` and up), fields underneath. Below
+`md` the quick entries wrap and stack under the calendar rather than taking a
+column out of the day grid: at 390px a side column squeezes the grid to about
+half its width and the numbers stop being readable.
+
+There is no `size` prop. The day grid has a fixed metric that a size scale would
+not change, and a prop that only altered the padding of the quick entries would
+be a scale in name only.
+
+## Accessibility
+
+- The quick entries are native `<button>`s with `aria-pressed`; the active one
+  is the entry the draft currently equals. (A listbox with `aria-selected` would
+  model this too — the rule is to pick one and use it for every entry.)
+- Over-cap entries are `aria-disabled`, **not** `disabled`: a disabled button is
+  skipped by the tab order, so the reason under it would be unreachable by
+  exactly the reader most likely to need it. They also carry
+  `aria-describedby` pointing at that reason.
+- The status line is `role="status" aria-live="polite"`, so a refusal is spoken
+  when it appears rather than found by someone who goes looking.
+- Both fields point at that line through `aria-describedby`, and are marked
+  `error` when the PAIR is impossible — never merely incomplete, which would
+  make the first click of a two-click control look like a mistake.
+- Keyboard: the quick column is buttons; the grid is `Calendar`'s own roving
+  focus (arrows, `Home`/`End`, `PageUp`/`PageDown`, Enter/Space).
+
+## Copy
+
+Every string is in `messages` and defaults to English. The summary prints days
+in the same `dd/mm/aaaa` the fields are masked to rather than in the host
+locale's order: one control cannot show the same date two ways, and an `en-US`
+summary reading `08/05` over a field reading `05/08` leaves the reader to work
+out which is lying. Replace `messages.summary` to choose another order.
+
+## Test IDs
+
+All derived from `dataTestId` (default `date-range-picker`):
+
+| id | element |
+|---|---|
+| `{root}` | the container |
+| `{root}-quick-list` | the quick group |
+| `{root}-quick-{quickRangeId}` | one quick entry |
+| `{root}-from`, `{root}-to` | the two `<input>`s |
+| `{root}-status` | the summary / refusal line |
+
+The calendar keeps its own ids (`calendar-container`, `calendar-header`,
+`calendar-date-{day}`). **`calendar-date-{day}` is the day of the month only**,
+so with two months on screen every day appears twice; a test that selects days
+by that id should render `numberOfMonths={1}`.
+
+## Usage
+
+```tsx
+const [range, setRange] = useState<DateRangeDraft>({ from: null, to: null });
+const [status, setStatus] = useState<DateRangeStatus>(resolveDayRange(range));
+
+<DateRangePicker
+  value={range}
+  onChange={(next, meta) => {
+    setRange(next);
+    setStatus(meta.status);
+  }}
+  timeZone="America/Sao_Paulo"
+  maxRangeDays={366}
+  locale="pt-BR"
+  numberOfMonths={1}
+/>
+<Button disabled={!status.ok} onClick={() => status.ok && apply(status.window)}>
+  Aplicar
+</Button>
+```
+
+## Related
+
+- [`Calendar`](../Calendar/Calendar.md) — the range grid this composes
+- `DataViews` — where the masked `dd/mm/aaaa` field comes from

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;
+}