@12-apps/ui 6.89.1 → 6.90.0

package/src/components/data-display/DataViews/data-views-range-bounds.tsx

@@ -0,0 +1,223 @@
+'use client';
+
+/**
+ * The `De`/`Até` pair of a range filter, its preset chips, the line under it
+ * and — for a day range — the calendar under that (FUT-4144). Shared by the
+ * pill's popover, the slide-in panel and the "Mais" sheet, so the three cannot
+ * drift on what a bound accepts or how it clears.
+ */
+import Box from '@mui/material/Box/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import React, { useState } from 'react';
+
+import { useDataViewsCopy } from './data-views-copy-context';
+import { DayBoundInput } from './data-views-day-input';
+import { NumberBoundInput } from './data-views-number-input';
+import { RangePresets } from './data-views-preset-chips';
+import { DayRangeCalendar } from './data-views-range-calendar';
+import { presetsFor } from './data-views-range-presets';
+import { useOutsideResetKey } from './data-views-range-reset';
+import { isRangeInverted } from './data-views-range-values';
+import type { RangeFieldConfig, RangeValue } from './data-views-types';
+import { sxRem } from '../../../tokens/relative';
+
+/**
+ * One end of the range. A day keeps its `AAAA-MM-DD` string verbatim (the form
+ * both the field and the backend speak) and is typed through the masked
+ * `dd/mm/aaaa` field rather than a native date input — see
+ * {@link DayBoundInput} for why. A number parses, and an unparseable/blank
+ * entry CLEARS the bound rather than writing `NaN`.
+ */
+function BoundField<T extends Record<string, unknown>>({
+  field,
+  label,
+  value,
+  onChange,
+  testId,
+  fill,
+}: {
+  field: RangeFieldConfig<T>;
+  label: string;
+  value: number | string | undefined;
+  onChange: (bound: number | string | undefined) => void;
+  testId: string;
+  /** A number box takes its cell's width; a day box always does. */
+  fill: boolean;
+}): React.JSX.Element {
+  const copy = useDataViewsCopy();
+  if (field.kind === 'day') {
+    return (
+      <DayBoundInput
+        fill
+        mask={copy.filters.dayMask}
+        invalidMessage={copy.filters.dayInvalid}
+        label={label}
+        value={value == null ? undefined : String(value)}
+        onChange={onChange}
+        testId={testId}
+      />
+    );
+  }
+  return (
+    <NumberBoundInput
+      fill={fill}
+      label={label}
+      value={value}
+      unit={field.unit}
+      onChange={onChange}
+      testId={testId}
+    />
+  );
+}
+
+
+/** One box of the pair: an equal share of the row for a day, as it was for a number. */
+function BoundCell({ grow, children }: { grow: boolean; children: React.ReactNode }): React.JSX.Element {
+  if (!grow) return <>{children}</>;
+  return <Box sx={{ flex: '1 1 0', minWidth: 0 }}>{children}</Box>;
+}
+
+/**
+ * The line under the pair: why an inverted window matches nothing, or — for a
+ * day range — that BOTH days are in the result. Saying so is FUT-668's other
+ * half: the bounds compare as ISO strings precisely so `até` keeps its whole
+ * day, and nothing on screen would otherwise tell the merchant that.
+ */
+function RangeNote({
+  day,
+  inverted,
+  testId,
+}: {
+  day: boolean;
+  inverted: boolean;
+  testId: string;
+}): React.JSX.Element | null {
+  const copy = useDataViewsCopy();
+  if (inverted) {
+    return (
+      <Typography
+        component="p"
+        data-testid={`${testId}-inverted`}
+        sx={{ mt: 0.75, fontSize: sxRem(12), color: 'error.main' }}
+      >
+        {copy.filters.rangeInvalid}
+      </Typography>
+    );
+  }
+  if (!day) return null;
+  return (
+    <Typography
+      component="p"
+      data-testid={`${testId}-inclusive`}
+      // `text.secondary`, not `disabled`: the note is read, and disabled grey
+      // at 12px is 2.68:1 (FUT-4144 UI review).
+      sx={{ mt: { xs: 0.25, sm: 0.75 }, fontSize: sxRem(12), color: 'text.secondary' }}
+    >
+      {copy.filters.rangeInclusiveNote}
+    </Typography>
+  );
+}
+
+/** Props of {@link RangeBounds}. */
+interface RangeBoundsProps<T extends Record<string, unknown>> {
+  field: RangeFieldConfig<T>;
+  value: RangeValue;
+  onChange: (range: RangeValue) => void;
+  testId: string;
+  /**
+   * Months the day calendar shows side by side (FUT-4144). Two where the
+   * popover has the room; one, with the month/year selectors, on a phone and
+   * in the panels.
+   */
+  calendarMonths?: 1 | 2;
+  /**
+   * Whether the day calendar is mounted. A host that keeps the pair mounted
+   * while hidden (the slide-in panel) passes its open state, so a closed panel
+   * holds no calendar of its own.
+   */
+  showCalendar?: boolean;
+  /**
+   * A NUMBER pair splits the row equally too, as a day pair always does. Set
+   * by the panels, whose width is the row's; the pill's popover sizes itself to
+   * its content and keeps the boxes' own width.
+   */
+  fillRow?: boolean;
+}
+
+/**
+ * The `De`/`Até` pair for a range — shared by the pill's popover and the
+ * slide-in panel's day fields, so the two surfaces cannot drift on what a bound
+ * accepts or how it clears.
+ */
+export function RangeBounds<T extends Record<string, unknown>>({
+  field,
+  value,
+  onChange,
+  testId,
+  calendarMonths = 1,
+  showCalendar = true,
+  fillRow = false,
+}: RangeBoundsProps<T>): React.JSX.Element {
+  const copy = useDataViewsCopy();
+  const { key, emitted } = useOutsideResetKey(value);
+  // Moves the calendar to a TYPED day. A typed write is the fields' own, so
+  // the outside key above does not see it; a tap on the calendar moves
+  // neither, which is what keeps it still under the finger.
+  const [typed, setTyped] = useState(0);
+  const typedChange = (range: RangeValue) => {
+    setTyped((n) => n + 1);
+    onChange(emitted(range));
+  };
+  const day = field.kind === 'day';
+  return (
+    <Box data-testid={`${testId}-panel`}>
+      {/* Above the inputs, not below: the presets are the answer for most
+          merchants, and the two date pickers are the escape hatch. */}
+      <Box sx={{ '&:not(:empty)': { mb: { xs: 1, sm: 1.5 } } }}>
+        <RangePresets presets={presetsFor(field, copy)} value={value} onChange={onChange} testId={testId} />
+      </Box>
+      {/* Top-aligned: a day that does not exist grows ITS field by a message
+          line, and centring would push the other box half a line down. The two
+          boxes are one height, so with no message this is the same row. */}
+      <Box sx={{ display: 'flex', alignItems: 'flex-start', gap: 1.5 }}>
+        {/* A day pair shares the row equally, so it spans the calendar under
+            it; a number pair keeps its own widths. */}
+        <BoundCell grow={day || fillRow}>
+          <BoundField
+            key={`min-${key}`}
+            field={field}
+            label={copy.filters.rangeStart}
+            value={value.min}
+            onChange={(min) => typedChange({ ...value, min })}
+            testId={`${testId}-min`}
+            fill={fillRow}
+          />
+        </BoundCell>
+        <BoundCell grow={day || fillRow}>
+          <BoundField
+            key={`max-${key}`}
+            field={field}
+            label={copy.filters.rangeEnd}
+            value={value.max}
+            onChange={(max) => typedChange({ ...value, max })}
+            testId={`${testId}-max`}
+            fill={fillRow}
+          />
+        </BoundCell>
+      </Box>
+      <RangeNote day={day} inverted={isRangeInverted(value)} testId={testId} />
+      {/* Under the boxes and the note, with no button to reach it: the typed
+          path stays as short as it was, and a period is two taps (FUT-4144). */}
+      {day && showCalendar && (
+        <DayRangeCalendar
+          fieldLabel={field.label}
+          value={value}
+          onChange={(range) => onChange(emitted(range))}
+          months={calendarMonths}
+          viewKey={`${key}-${typed}`}
+          testId={testId}
+        />
+      )}
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/data-views-range-calendar.tsx

@@ -0,0 +1,185 @@
+'use client';
+
+/**
+ * The range calendar under a day filter's `De`/`Até` boxes (FUT-4144).
+ *
+ * The owner picked it ALWAYS OPEN (option B of the prototype): a period is
+ * three taps — open the filter, the first day, the last day — against five for
+ * a calendar button in each box and four for a link to a separate sheet. It
+ * sits BELOW the boxes, with no button of its own, so the typed path is not one
+ * keystroke longer than it was.
+ *
+ * The boxes and the calendar are two views of ONE range: a tap writes the
+ * boxes, a typed day moves and repaints the calendar, an impossible typed day
+ * (which writes nothing) leaves it alone, and "Limpar" empties both.
+ *
+ * It is `Calendar` in `selectionMode="range"`, the same one `DateRangePicker`
+ * mounts — not a second calendar. Its own rule picks the period: the first tap
+ * starts it, the second closes it, and a second tap BEFORE the first swaps the
+ * two, so the boxes never show a period backwards.
+ */
+import Box from '@mui/material/Box/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import React from 'react';
+
+import { EN_US_DATA_VIEWS_COPY } from '../../../en-US.data-display';
+import type { Theme } from '@mui/material/styles/index.js';
+import { rem, sxRem } from '../../../tokens/relative';
+import { Calendar, type DateRange } from '../../form/Calendar';
+import { toDayString, toLocalDay } from '../../form/DateRangePicker/DateRangePicker.dates';
+import type { DataViewsDayCalendarCopy } from './data-views-copy';
+import { useDataViewsCopy } from './data-views-copy-context';
+import type { RangeValue } from './data-views-types';
+
+const CALENDAR_CLASS = 'data-views-range-calendar';
+
+/**
+ * `Calendar` draws its own `Paper` with 24px of padding and a shadow. Inside
+ * the filter's popover that reads as a card inside a card, so the inner frame
+ * is flattened through the class hook the component offers for this — the
+ * same thing `DateRangePicker` does.
+ */
+const ROOT_SX = (theme: Theme) => ({
+  mt: { xs: 1, sm: 1.5 },
+  // Below `sm` the caption and the weekday row give up their bottom margins,
+  // so the whole popover fits a 320×568 screen under its pill (FUT-4144).
+  '& :has(> * > [data-testid="calendar-month-select"])': { mb: { xs: 0.5, sm: 2 } },
+  '& :has(> [role="columnheader"])': { mb: { xs: 0, sm: 1 } },
+  '& [role="columnheader"]': { height: { xs: rem(theme, 24), sm: rem(theme, 32) } },
+  // The days carry no column gap of their own (`Calendar`, FUT-4162), so the
+  // seven columns are what a day's 40px target is carved from below `sm`; the
+  // range band and its round endpoints are the Calendar's, untouched here.
+  // The month/year caption on ONE row at 320: the selectors give up the slack
+  // around their text before the arrows are pushed onto a second row.
+  '& [data-testid="calendar-month-select"], & [data-testid="calendar-year-select"]': { px: 0.5, minWidth: 0 },
+  [`& .${CALENDAR_CLASS}`]: {
+    p: 0,
+    boxShadow: 'none',
+    backgroundColor: 'transparent',
+    backgroundImage: 'none',
+    // A tapped day already rings itself; the whole grid framed in the primary
+    // colour after every tap is noise in a popover. The frame stays for the
+    // keyboard reaching the grid itself.
+    '&:focus-within': { outline: 'none' },
+    '&:focus-visible': {
+      outline: (theme: Theme) => `${rem(theme, 2)} solid`,
+      outlineColor: 'primary.main',
+      outlineOffset: sxRem(2),
+    },
+  },
+});
+
+/** The two ends of a range, as `Calendar` reads them. */
+function rangeOf(value: RangeValue): DateRange {
+  return {
+    start: toLocalDay(typeof value.min === 'string' ? value.min : null),
+    end: toLocalDay(typeof value.max === 'string' ? value.max : null),
+  };
+}
+
+/**
+ * What a tap on the calendar makes of the range.
+ *
+ * `Calendar` reports the period it holds after the tap: a fresh start (`end`
+ * null) or a closed one, already in order. The one case it cannot see is a
+ * range with only `Até` — typed, or left by a saved view — where its first tap
+ * would drop that `Até`. A first day on or before it keeps it, so "até 15/10"
+ * plus one tap on the 3rd is 03/10–15/10, as the prototype does.
+ */
+export function rangeFromCalendar(previous: RangeValue, picked: DateRange): RangeValue {
+  const min = dayOf(picked.start);
+  const max = dayOf(picked.end) ?? keptEnd(previous, min);
+  return { ...(min ? { min } : {}), ...(max ? { max } : {}) };
+}
+
+const dayOf = (date: Date | null | undefined): string | undefined => (date ? toDayString(date) : undefined);
+
+/** The `Até` of a range that has ONLY one, when the new first day is on or before it. */
+function keptEnd(previous: RangeValue, min: string | undefined): string | undefined {
+  if (previous.min != null || typeof previous.max !== 'string') return undefined;
+  return min && min <= previous.max ? previous.max : undefined;
+}
+
+/**
+ * The month the calendar opens on while `De` is empty. With `De` set it opens
+ * on De's month, which `Calendar` does by itself.
+ *
+ * With two months the current month sits on the RIGHT (setembro | outubro), so
+ * the days a filter usually asks about — the ones just past — are on screen;
+ * with only `Até` set, its month takes that place.
+ */
+function openingMonth(value: RangeValue, months: number): Date | undefined {
+  const end = toLocalDay(typeof value.max === 'string' ? value.max : null);
+  const anchor = end ?? new Date();
+  return new Date(anchor.getFullYear(), anchor.getMonth() - (months > 1 ? 1 : 0), 1);
+}
+
+/** Props of {@link DayRangeCalendar}. */
+export interface DayRangeCalendarProps {
+  /** The filter's own label ("Data"), which names the calendar. */
+  fieldLabel: string;
+  value: RangeValue;
+  /** Called with the range a tap leaves; never for a typed day. */
+  onChange: (range: RangeValue) => void;
+  /**
+   * Months side by side. Two read as a period at a glance where there is room;
+   * one, with the month/year selectors, where there is not.
+   */
+  months: 1 | 2;
+  /**
+   * Changes when the range moved from OUTSIDE the calendar (typed, a preset,
+   * "Limpar"), so the calendar re-opens on it. Never for its own taps: a
+   * calendar that jumped under the finger picking in it would be unusable.
+   */
+  viewKey: string;
+  testId: string;
+}
+
+export function DayRangeCalendar({
+  fieldLabel,
+  value,
+  onChange,
+  months,
+  viewKey,
+  testId,
+}: DayRangeCalendarProps): React.JSX.Element {
+  const copy: DataViewsDayCalendarCopy =
+    useDataViewsCopy().filters.dayCalendar ?? (EN_US_DATA_VIEWS_COPY.filters.dayCalendar as DataViewsDayCalendarCopy);
+  const range = rangeOf(value);
+  const pick = (picked: DateRange) => onChange(rangeFromCalendar(value, picked));
+  const waitingForEnd = Boolean(range.start && !range.end);
+
+  return (
+    <Box sx={ROOT_SX} data-testid={`${testId}-calendar`}>
+      <Calendar
+        key={viewKey}
+        ariaLabel={copy.label(fieldLabel)}
+        className={CALENDAR_CLASS}
+        selectionMode="range"
+        locale={copy.locale}
+        labels={copy.caption}
+        // Sunday first, as a pt-BR calendar reads (`D S T Q Q S S`) and as the
+        // presets' "Esta semana" counts.
+        firstDayOfWeek={0}
+        numberOfMonths={months}
+        // Side by side, a day of the next month in this one is the same day
+        // twice; one month alone keeps them, muted, as a six-week frame.
+        showOutsideDays={months === 1}
+        captionLayout={months > 1 ? 'arrows' : 'selectors'}
+        defaultMonth={openingMonth(value, months)}
+        range={range}
+        // The intermediate callback does the work: the other fires only on the
+        // tap that CLOSES a period, so the first tap would write nothing.
+        onIntermediateRangeChange={pick}
+      />
+      <Typography
+        component="p"
+        aria-live="polite"
+        data-testid={`${testId}-calendar-hint`}
+        sx={{ mt: { xs: 0.25, sm: 1 }, fontSize: sxRem(12), color: 'text.secondary' }}
+      >
+        {waitingForEnd ? copy.pickEnd : copy.pickStart}
+      </Typography>
+    </Box>
+  );
+}