@12-apps/ui 3.0.0 → 3.1.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,146 @@
+'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 } 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 { DateRangePickerProps } from './DateRangePicker.types';
+import { DateRangeFields } from './DateRangePickerFields';
+import { DateRangeQuickList } from './DateRangePickerQuickList';
+
+const CALENDAR_CLASS = 'date-range-picker__calendar';
+
+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 and drops UNDER it when there is
+  // no room for both. At 390px a side column would squeeze the day grid to
+  // roughly half its width and make the numbers unreadable; stacking keeps the
+  // grid whole and costs a scroll. Checked at 390px.
+  flexDirection: { xs: 'column', md: 'row' },
+  alignItems: 'flex-start',
+  gap: 2,
+  maxWidth: '100%',
+  overflowX: 'auto',
+};
+
+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,
+  });
+
+  return (
+    <Paper className={className} data-testid={dataTestId} sx={ROOT_SX}>
+      <Box sx={BODY_SX}>
+        <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={numberOfMonths}
+          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}
+        />
+        {picker.options.length > 0 && (
+          <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>
+      <DateRangeFields
+        value={value}
+        status={picker.status}
+        messages={picker.copy}
+        maxRangeDays={maxRangeDays}
+        onEdit={picker.editBound}
+        statusId={picker.statusId}
+        dataTestId={dataTestId}
+      />
+    </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;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * The two typed ends, and the one line that says what the picker currently has.
+ *
+ * WHEN A TYPED DATE COMMITS: the moment it is a WHOLE, REAL day — eight digits
+ * that name a date that exists. Not on every keystroke (`2026` passes through
+ * `0002`, `0020` and `0202`, each a legal year, and committing those makes the
+ * calendar jump to the year 20 while you are still typing) and not only on blur
+ * (a reader 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.
+ *
+ * The field itself is `DayBoundInput`, the masked `dd/mm/aaaa` control the data
+ * views already use. Same package, imported rather than re-implemented: a
+ * second masked date field is a second set of rules for what backspace does.
+ */
+import { Box, Typography } from '@mui/material';
+import React from 'react';
+
+import { DayBoundInput } from '../../data-display/DataViews/data-views-day-input';
+
+import { statusMessage } from './DateRangePicker.range';
+import type {
+  DateRangePickerMessages,
+  DateRangeDraft,
+  DateRangeStatus,
+  DayString,
+} from './DateRangePicker.types';
+
+export interface DateRangeFieldsProps {
+  value: DateRangeDraft;
+  status: DateRangeStatus;
+  messages: DateRangePickerMessages;
+  maxRangeDays: number | undefined;
+  onEdit: (which: 'from' | 'to', bound: DayString | null) => void;
+  /** Id of the status line, so both fields can point at it. */
+  statusId: string;
+  dataTestId: string;
+}
+
+export function DateRangeFields({
+  value,
+  status,
+  messages,
+  maxRangeDays,
+  onEdit,
+  statusId,
+  dataTestId,
+}: DateRangeFieldsProps): React.JSX.Element {
+  // "Incomplete" is not an error — it is a range that is not finished yet, and
+  // painting it red would make the first click on a two-click control look like
+  // a mistake. The pair being impossible is what gets marked.
+  const rejected = !status.ok && status.problem !== 'incomplete';
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1 }}>
+      <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 2 }}>
+        <DayBoundInput
+          label={messages.from}
+          value={value.from ?? undefined}
+          onChange={(bound) => onEdit('from', bound ?? null)}
+          testId={`${dataTestId}-from`}
+          error={rejected}
+          describedBy={statusId}
+        />
+        <DayBoundInput
+          label={messages.to}
+          value={value.to ?? undefined}
+          onChange={(bound) => onEdit('to', bound ?? null)}
+          testId={`${dataTestId}-to`}
+          error={rejected}
+          describedBy={statusId}
+        />
+      </Box>
+      <Typography
+        id={statusId}
+        // A live region, so the reason a range was refused is spoken when it
+        // appears rather than only being found by someone who goes looking.
+        role="status"
+        aria-live="polite"
+        variant="body2"
+        color={rejected ? 'error.main' : 'text.secondary'}
+        data-testid={`${dataTestId}-status`}
+      >
+        {statusMessage(status, messages, maxRangeDays)}
+      </Typography>
+    </Box>
+  );
+}