@12-apps/ui 6.97.1 → 6.98.1

package/src/components/form/Calendar/CalendarDay.tsx

@@ -20,6 +20,10 @@ const COLUMN_SIZE = sxRem(304 / 7);
 /** 304/7 wide to 40 tall: the day's face is a 40 design px circle at full size. */
 const CELL_RATIO = '38 / 35';
 
+/** Emotion's documented flag for a positional selector known safe here. */
+const NTH_CHILD_IS_SAFE =
+  ' /* emotion-disable-server-rendering-unsafe-selector-warning-please-do-not-use-this-the-warning-exists-for-a-reason */';
+
 interface DayState extends DayRenderArgs {
   outside: boolean;
   focused: boolean;
@@ -66,9 +70,15 @@ const inDirection = (band: Exclude<DayBand, 'none'>, theme: Theme): Exclude<DayB
 const faceBackgroundFor = (day: DayRenderArgs): ((theme: Theme) => string) | string =>
   isEndpoint(day) ? endpointFill : 'transparent';
 
-const colorFor = (day: DayRenderArgs, visible: boolean): string => {
+const colorFor = (day: DayRenderArgs, visible: boolean, locked: boolean): string => {
   if (isEndpoint(day)) return 'primary.contrastText';
-  if (day.disabled) return 'text.disabled';
+  // On a calendar shown LOCKED (`navigationDisabled`, a disabled picker) every
+  // day is disabled, and the ones inside the range are the value the grid
+  // states: on the band the disabled ink was 1.56:1, so they take the secondary
+  // ink (FUT-4482, review round 9). A live range CAN span a blocked day (a
+  // host's `isDateDisabled`: Sundays, holidays); that day keeps the disabled
+  // ink, so it still reads as the one that cannot be picked.
+  if (day.disabled) return locked && day.inRange ? 'text.secondary' : 'text.disabled';
   // Outside days that are switched off still occupy the grid, they just have
   // nothing to show.
   if (!visible) return 'transparent';
@@ -85,13 +95,59 @@ const hoverBackgroundFor = (day: DayRenderArgs): ((theme: Theme) => string) | st
 // is a half-round cap on a cell as tall as it is wide.
 const BAND_RADIUS = '50%';
 
+const capRadius = (side: 'start' | 'end', fill: boolean) => {
+  const radius = fill ? FILL_CAP_RADIUS : BAND_RADIUS;
+  return side === 'start'
+    ? { borderStartStartRadius: radius, borderEndStartRadius: radius }
+    : { borderStartEndRadius: radius, borderEndEndRadius: radius };
+};
+
 /**
  * One cell: the band, painted on the button across its whole column, and the
  * day's round face, a `::before` circle behind the number. The face is a
  * pseudo-element so the button's own content stays the bare day number a host's
  * tests query (`getByText('27')` is the cell, as it always was).
  */
-const dayCellSx = (day: DayRenderArgs, band: DayBand, visible: boolean): SxProps<Theme> => ({
+/**
+ * Today's ring, opt-in (`todayIndicator="ring"`): a hairline-and-a-half inset
+ * on the face, in the primary colour. An endpoint is already filled with that
+ * colour, so it carries none.
+ */
+const todayRingFor = (day: DayRenderArgs, ring: boolean): ((theme: Theme) => string) | undefined =>
+  ring && day.today && !isEndpoint(day)
+    ? // A disabled today keeps its ring in the disabled ink, like its number:
+      // a primary ring on a dead grid reads as the one live day (round 6).
+      (theme: Theme) =>
+        `inset 0 0 0 ${rem(theme, 1.5)} ${day.disabled ? theme.palette.text.disabled : theme.palette.primary.main}`
+    : undefined;
+
+/**
+ * A filling calendar's cell (`fullWidth`): the whole column wide, so a range's
+ * band runs unbroken however far the columns spread, and exactly as tall as the
+ * 40 design px face — the face is as tall as the cell, so it keeps its size
+ * while only the spacing grows. A row's end caps round at half that height
+ * (the radius clamps on a smaller cell) rather than half a wide cell's width.
+ */
+const FILL_CELL_HEIGHT = sxRem(40);
+const FILL_CAP_RADIUS = sxRem(20);
+
+// A filling cell is 40 tall at every width, never a ratio of its column: a
+// tap target under 600 wide is 40 design px each way, and a ratio made a 36px
+// column 33 tall at 320 (FUT-4156, round 3). The frame gives the columns their
+// 40 (`DateRangePicker.frame`).
+const cellSize = (fill: boolean) =>
+  fill
+    ? { width: '100%', maxWidth: '100%', height: FILL_CELL_HEIGHT, justifySelf: 'stretch' }
+    : { width: COLUMN_SIZE, maxWidth: '100%', aspectRatio: CELL_RATIO, justifySelf: 'stretch' };
+
+const dayCellSx = (
+  day: DayRenderArgs,
+  band: DayBand,
+  visible: boolean,
+  ring: boolean,
+  fill: boolean,
+  locked: boolean,
+): SxProps<Theme> => ({
   position: 'relative',
   isolation: 'isolate',
   display: 'flex',
@@ -101,24 +157,27 @@ const dayCellSx = (day: DayRenderArgs, band: DayBand, visible: boolean): SxProps
   // now that the seven columns carry no gap between them; `maxWidth` and the
   // column's `minmax(0, 1fr)` let it give way below that, and the ratio keeps
   // it 40 tall at full size and shrinking with it.
-  width: COLUMN_SIZE,
-  maxWidth: '100%',
-  aspectRatio: CELL_RATIO,
-  justifySelf: 'stretch',
+  ...cellSize(fill),
   boxSizing: 'border-box',
   padding: 0,
   border: 'none',
   background: 'none',
   backgroundImage: band === 'none' ? 'none' : (theme: Theme) => BAND_IMAGE[inDirection(band, theme)](bandColor(theme)),
   cursor: day.disabled ? 'not-allowed' : 'pointer',
-  color: colorFor(day, visible),
+  color: colorFor(day, visible, locked),
   opacity: !day.inCurrentMonth && visible ? 0.5 : 1,
   fontWeight: day.today || isEndpoint(day) ? 'bold' : 'normal',
   // `nth-child`, counting every cell of the week: a hidden outside day is an
   // inert `span` placeholder (FUT-4144), and `nth-of-type` counted only the
   // buttons, so the caps landed mid-week in a month with hidden outside days.
-  '&:nth-child(7n + 1)': { borderStartStartRadius: BAND_RADIUS, borderEndStartRadius: BAND_RADIUS },
-  '&:nth-child(7n)': { borderStartEndRadius: BAND_RADIUS, borderEndEndRadius: BAND_RADIUS },
+  //
+  // Emotion warns on `:nth-child` in development, because a server render can
+  // put its style tag between the cells and shift the count. The calendar is
+  // never server-rendered into that position, and every screen that showed one
+  // printed the warning as a console error (FUT-4156), so the selectors carry
+  // Emotion's own opt-out flag.
+  [`&:nth-child(7n + 1)${NTH_CHILD_IS_SAFE}`]: capRadius('start', fill),
+  [`&:nth-child(7n)${NTH_CHILD_IS_SAFE}`]: capRadius('end', fill),
   '&::before': {
     content: '""',
     position: 'absolute',
@@ -131,12 +190,14 @@ const dayCellSx = (day: DayRenderArgs, band: DayBand, visible: boolean): SxProps
     maxWidth: '100%',
     borderRadius: '50%',
     backgroundColor: faceBackgroundFor(day),
+    boxShadow: todayRingFor(day, ring),
   },
   '&:hover::before': {
     backgroundColor: hoverBackgroundFor(day),
   },
   '&:focus': { outline: 'none' },
-  '&:focus::before': {
+  // Keyboard focus only: a tapped day is already marked by what the tap did.
+  '&:focus-visible::before': {
     outline: (theme: Theme) => `${rem(theme, 2)} solid`,
     outlineColor: 'primary.main',
     outlineOffset: sxRem(1),
@@ -158,6 +219,12 @@ export interface CalendarDayProps {
   band: DayBand;
   focused: boolean;
   showOutsideDays: boolean;
+  /** Ring today's face (`todayIndicator="ring"`). */
+  todayRing?: boolean;
+  /** Fill the column (`CalendarProps.fullWidth`). */
+  fullWidth?: boolean;
+  /** The whole calendar is shown locked (`CalendarProps.navigationDisabled`). */
+  locked?: boolean;
   dayClassName?: (args: DayRenderArgs) => string;
   onSelect: (date: Date) => void;
   onHover: (date: Date) => void;
@@ -170,6 +237,9 @@ export const CalendarDay: FC<CalendarDayProps> = ({
   band,
   focused,
   showOutsideDays,
+  todayRing = false,
+  fullWidth,
+  locked,
   dayClassName,
   onSelect,
   onHover,
@@ -187,7 +257,7 @@ export const CalendarDay: FC<CalendarDayProps> = ({
         component="span"
         aria-hidden="true"
         data-testid="calendar-outside-placeholder"
-        sx={{ width: COLUMN_SIZE, maxWidth: '100%', aspectRatio: CELL_RATIO, justifySelf: 'stretch' }}
+        sx={cellSize(fullWidth === true)}
       />
     );
   }
@@ -195,6 +265,8 @@ export const CalendarDay: FC<CalendarDayProps> = ({
   return (
     <Box
       component="button"
+      // A day picks; it never submits the form a calendar sits in (FUT-4156).
+      type="button"
       role="gridcell"
       tabIndex={focused ? 0 : -1}
       aria-selected={day.selected}
@@ -207,7 +279,7 @@ export const CalendarDay: FC<CalendarDayProps> = ({
       onClick={() => onSelect(day.date)}
       onMouseEnter={() => onHover(day.date)}
       onMouseLeave={onHoverEnd}
-      sx={dayCellSx(day, band, visible)}
+      sx={dayCellSx(day, band, visible, todayRing, fullWidth === true, locked === true)}
     >
       {day.selected && (
         <Box component="span" data-testid="calendar-selected-date" sx={{ display: 'none' }} />

package/src/components/form/Calendar/CalendarDayCell.tsx

@@ -4,7 +4,7 @@ import React from 'react';
 import { bandFor } from './Calendar.band';
 import { isSameDay } from './Calendar.dates';
 import { buildDayArgs } from './Calendar.selection';
-import type { CalendarProps, DateRange, MonthMatrixDay, SelectionMode } from './Calendar.types';
+import type { CalendarProps, CalendarTodayIndicator, DateRange, MonthMatrixDay, SelectionMode } from './Calendar.types';
 import { CalendarDay } from './CalendarDay';
 
 // Everything a cell needs that is the same for every cell in the calendar.
@@ -18,6 +18,16 @@ export interface DayCellContext {
   focusedDate: Date;
   today: Date;
   showOutsideDays: boolean;
+  /** How today is marked (`CalendarProps.todayIndicator`). */
+  todayIndicator: CalendarTodayIndicator;
+  /** Spread the columns across the width (`CalendarProps.fullWidth`). */
+  fullWidth: boolean;
+  /**
+   * The whole calendar is shown locked (`CalendarProps.navigationDisabled`,
+   * which a disabled `DateRangePicker` sets): its in-range days keep the
+   * secondary ink. A live calendar's blocked days keep the disabled ink.
+   */
+  locked: boolean;
   isDisabled: (date: Date) => boolean;
   renderDay?: CalendarProps['renderDay'];
   dayClassName?: CalendarProps['dayClassName'];
@@ -30,6 +40,9 @@ export const CalendarDayCell: FC<DayCellContext & { day: MonthMatrixDay }> = ({
   day,
   focusedDate,
   showOutsideDays,
+  todayIndicator,
+  fullWidth,
+  locked,
   renderDay,
   dayClassName,
   onSelect,
@@ -49,6 +62,9 @@ export const CalendarDayCell: FC<DayCellContext & { day: MonthMatrixDay }> = ({
       band={bandFor({ args, ...context })}
       focused={isSameDay(args.date, focusedDate)}
       showOutsideDays={showOutsideDays}
+      todayRing={todayIndicator === 'ring'}
+      fullWidth={fullWidth}
+      locked={locked}
       dayClassName={dayClassName}
       onSelect={onSelect}
       onHover={onHover}

package/src/components/form/Calendar/CalendarMonth.tsx

@@ -45,6 +45,34 @@ export const MONTH_SX = {
   maxWidth: sxRem(304),
 } as const;
 
+/**
+ * A filling month (`fullWidth`) drops the 304 ceiling and takes its share of
+ * the row; its columns spread, its day faces do not grow (`CalendarDay`).
+ */
+export const monthSx = (fullWidth: boolean) => (fullWidth ? FILL_MONTH_SX : MONTH_SX);
+
+/**
+ * The basis as a theme function: interpolated into a string, `sxRem` is a
+ * function and the whole `flex` value is dropped as invalid CSS. A filling
+ * month's cells have no intrinsic width to fall back on, so it must grow.
+ */
+const FILL_MONTH_SX = {
+  flex: (theme: Theme) => `1 1 ${rem(theme, 280)}`,
+  minWidth: 0,
+  maxWidth: 'none',
+} as const;
+
+/**
+ * The caption as a title: its first letter upper-cased in the calendar's own
+ * language ("novembro de 2026" → "Novembro de 2026"), as a heading reads in
+ * pt-BR; `Intl` writes month names lower-case there. The caption only — the
+ * grid's name and a day's name keep `Intl`'s words, which a sentence quotes.
+ */
+export const captionOf = (monthName: string, locale: string): string => {
+  const [first = '', ...rest] = [...monthName];
+  return `${first.toLocaleUpperCase(locale)}${rest.join('')}`;
+};
+
 /** The two arrows' accessible names; an icon alone names nothing. */
 export type MonthArrowLabels = Pick<CalendarLabels, 'previousMonth' | 'nextMonth'>;
 
@@ -55,9 +83,10 @@ const MonthNavHeader: FC<{
   showPrevious: boolean;
   showNext: boolean;
   labels?: MonthArrowLabels;
+  disabled: boolean;
   onPreviousMonth: () => void;
   onNextMonth: () => void;
-}> = ({ title, showPrevious, showNext, labels, onPreviousMonth, onNextMonth }) => (
+}> = ({ title, showPrevious, showNext, labels, disabled, onPreviousMonth, onNextMonth }) => (
   <Box
     sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', mb: 2 }}
     data-testid="calendar-header"
@@ -65,6 +94,7 @@ const MonthNavHeader: FC<{
     {showPrevious && (
       <IconButton
         onClick={onPreviousMonth}
+        disabled={disabled}
         size="small"
         aria-label={labels?.previousMonth}
         data-testid="calendar-prev-month"
@@ -84,6 +114,7 @@ const MonthNavHeader: FC<{
     {showNext && (
       <IconButton
         onClick={onNextMonth}
+        disabled={disabled}
         size="small"
         aria-label={labels?.nextMonth}
         data-testid="calendar-next-month"
@@ -156,6 +187,8 @@ export interface CalendarMonthProps {
   renderHeader?: CalendarProps['renderHeader'];
   /** The arrows' accessible names. */
   labels?: MonthArrowLabels;
+  /** `CalendarProps.navigationDisabled`. */
+  navigationDisabled?: boolean;
   onPreviousMonth: () => void;
   onNextMonth: () => void;
   dayContext: DayCellContext;
@@ -169,12 +202,14 @@ export const CalendarMonth: FC<CalendarMonthProps> = ({
   weekdayNames,
   renderHeader,
   labels,
+  navigationDisabled = false,
   onPreviousMonth,
   onNextMonth,
   dayContext,
 }) => {
-  const monthName = getMonthName(matrix.month, matrix.year, locale);
-  const title = renderHeader ? renderHeader({ month: matrix.month, year: matrix.year }) : monthName;
+  const title = renderHeader
+    ? renderHeader({ month: matrix.month, year: matrix.year })
+    : captionOf(getMonthName(matrix.month, matrix.year, locale), locale);
 
   return (
     /* The month is addressable by its position, because in a multi-month
@@ -182,12 +217,13 @@ export const CalendarMonth: FC<CalendarMonthProps> = ({
        January's 5th and February's. Without a per-month hook a test can only
        reach a day positionally, which is exactly what the flakiness gate
        refuses. Additive: `calendar-grid` below is unchanged. */
-    <Box sx={MONTH_SX} data-testid={`calendar-month-${monthIndex}`}>
+    <Box sx={monthSx(dayContext.fullWidth)} data-testid={`calendar-month-${monthIndex}`}>
       <MonthNavHeader
         title={title}
         showPrevious={monthIndex === 0}
         showNext={monthIndex === monthsToShow - 1}
         labels={labels}
+        disabled={navigationDisabled}
         onPreviousMonth={onPreviousMonth}
         onNextMonth={onNextMonth}
       />

package/src/components/form/Calendar/CalendarSelectorsMonth.tsx

@@ -10,7 +10,7 @@ import type { MonthMatrix } from './Calendar.types';
 import type { DateBounds } from './Calendar.views';
 import { MONTH_INDEXES, canShiftMonth, isMonthOutOfBounds, isYearOutOfBounds, yearOptions } from './Calendar.views';
 import type { DayCellContext } from './CalendarDayCell';
-import { MONTH_SX, MonthDays } from './CalendarMonth';
+import { MonthDays, monthSx } from './CalendarMonth';
 import type { PickerOption } from './CalendarPickerGrid';
 import { CalendarPickerGrid } from './CalendarPickerGrid';
 import { CalendarSelectorsCaption } from './CalendarSelectorsCaption';
@@ -82,7 +82,7 @@ export const CalendarSelectorsMonth: FC<CalendarSelectorsMonthProps> = ({
   const picking = picker.view !== 'days';
 
   return (
-    <Box sx={MONTH_SX} data-testid="calendar-month-0">
+    <Box sx={monthSx(dayContext.fullWidth)} data-testid="calendar-month-0">
       <CalendarSelectorsCaption
         monthText={getMonthLabel(matrix.month, locale, 'long')}
         monthNames={MONTH_INDEXES.map((index) => getMonthLabel(index, locale, 'long'))}

package/src/components/form/Calendar/index.ts

@@ -2,6 +2,7 @@ export { Calendar,Calendar as default } from './Calendar';
 export type {
   CalendarCaptionLayout,
   CalendarInternalState,
+  CalendarTodayIndicator,
   CalendarProps,
   DateRange,
   DayRenderArgs,

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

@@ -0,0 +1,92 @@
+/**
+ * The months' frame in the in-page (`beside`) layout, and the fields' column
+ * beside it: how wide each is, with and without `fullWidth`. Kept out of the
+ * component so that file stays a layout of parts.
+ */
+import type { Theme } from '@mui/material/styles/index.js';
+
+import { rem, sxRem } from '../../../tokens/relative';
+import { surfaces } from '../../../tokens/surfaces';
+import { CARD_RADIUS_UNITS } from '../../layout/Card/Card.metrics';
+
+import { framedMonthsWidth } from './DateRangePicker.layout';
+
+export const CALENDAR_CLASS = 'date-range-picker__calendar';
+
+// `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.
+export const FLAT_CALENDAR = {
+  [`& .${CALENDAR_CLASS}`]: {
+    p: 0,
+    boxShadow: 'none',
+    backgroundColor: 'transparent',
+    backgroundImage: 'none',
+  },
+};
+
+/**
+ * The months' own frame in the `beside` layout: the picker is part of a page
+ * there, so the frame holds the calendar alone and the fields sit on the page
+ * beside or under it, as the form's other fields do.
+ */
+const BESIDE_FRAME_SX = {
+  p: 2,
+  maxWidth: '100%',
+  minWidth: 0,
+  // A card on the page, as the prototype draws it: the RAISED surface role
+  // (`background.paper` unless the host states one — a host whose paper is its
+  // page ground states a lighter card there) and the default `Card`'s radius,
+  // not a Paper's 4px (FUT-4156, round 3). In-page only: the popover keeps its own.
+  bgcolor: (theme: Theme) => surfaces(theme).raised,
+  borderRadius: (theme: Theme) => theme.spacing(CARD_RADIUS_UNITS.md),
+  ...FLAT_CALENDAR,
+} as const;
+
+/**
+ * Under the fields' row the frame is as wide as its months and centred: a
+ * frame stretched across the page around one month left a third of itself
+ * blank (FUT-4156, 600 and 900 wide).
+ */
+const BELOW_FRAME_SX = {
+  ...BESIDE_FRAME_SX,
+  alignSelf: 'center',
+  width: 'fit-content',
+} as const;
+
+/**
+ * `fullWidth`: the frame's edges are the picker's. Under the fields it spans
+ * the picker; beside them it takes the row the fields' column leaves, and the
+ * months spread across it (FUT-4156: a fitted frame left blank bands of 10 to
+ * 77px each side at 390, 600 and 900 wide).
+ */
+/**
+ * Under the fields the frame gives up its side padding before its columns
+ * drop under 40 design px: seven 40px columns and the hairlines need 282, so
+ * the padding is what is left of the row past that, never more than its 16
+ * (FUT-4156, round 3: at 320 wide the columns were 36). `100%` is the row's
+ * width — padding percentages read the containing block.
+ */
+export const FILL_COLUMN_MIN = 40;
+const sidePadding = (theme: Theme): string =>
+  `clamp(0px, calc((100% - ${rem(theme, 7 * FILL_COLUMN_MIN + 2)}) / 2), ${theme.spacing(2)})`;
+const FILL_BELOW_FRAME_SX = { ...BESIDE_FRAME_SX, alignSelf: 'stretch', px: sidePadding } as const;
+// Never narrower than its months at their full size: the fields' column gives
+// way first, down to the room `besideLayout` chose this placement with.
+const fillBesideFrameSx = (months: number) =>
+  ({ ...BESIDE_FRAME_SX, flex: '1 1 auto', minWidth: sxRem(framedMonthsWidth(months)) }) as const;
+
+/**
+ * The fields' column beside a filling frame stops at 320 design px: at 1920
+ * wide it ran to 694 for a ten-character date, with the room under it blank.
+ */
+const FILL_FIELDS_COLUMN = { flex: '0 1 auto', width: sxRem(320), minWidth: 0 } as const;
+
+export const frameSx = (sideBySide: boolean, fill: boolean, months: number) => {
+  if (fill) return sideBySide ? fillBesideFrameSx(months) : FILL_BELOW_FRAME_SX;
+  return sideBySide ? { ...BESIDE_FRAME_SX, flex: '0 0 auto' } : BELOW_FRAME_SX;
+};
+
+export const fieldsColumnSx = (sideBySide: boolean, fill: boolean) =>
+  fill && sideBySide ? FILL_FIELDS_COLUMN : { flex: 1, minWidth: 0 };
+

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

@@ -3,7 +3,7 @@
  * 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 { useEffect, useId, useMemo, useRef, useState } from 'react';
 
 import { toDayString, todayIn } from './DateRangePicker.dates';
 import {
@@ -19,6 +19,42 @@ import type {
   UseDateRangePickerArgs,
 } from './DateRangePicker.types';
 
+/**
+ * Whether `value` is what the picker last handed out — or that tap's draft
+ * carried on by the consumer: every bound the tap chose kept, a bound it left
+ * open filled in (a consumer that keeps an end the tap would have dropped).
+ * Either way the grid under the pointer must not move, nor lose its focus.
+ */
+function cameFromPicker(value: DateRangeDraft, emitted: DateRangeDraft | null): boolean {
+  if (emitted === null) return false;
+  const kept = (bound: 'from' | 'to'): boolean => emitted[bound] === null || emitted[bound] === value[bound];
+  return kept('from') && kept('to');
+}
+
+/**
+ * Bump the view nonce when the value moves and the picker did not move it —
+ * a consumer's own field committed a day. Skips the mount and the picker's own
+ * emissions, so a click in the grid never remounts the grid under it. An
+ * emission is read once: the change after it is the consumer's own.
+ */
+function useFollowValue(
+  enabled: boolean,
+  value: DateRangeDraft,
+  lastEmitted: { current: DateRangeDraft | null },
+  setViewNonce: (update: (nonce: number) => number) => void,
+): void {
+  const previous = useRef(value);
+  useEffect(() => {
+    const before = previous.current;
+    previous.current = value;
+    if (!enabled || (before.from === value.from && before.to === value.to)) return;
+    const emitted = lastEmitted.current;
+    lastEmitted.current = null;
+    if (cameFromPicker(value, emitted)) return;
+    setViewNonce((nonce) => nonce + 1);
+  }, [enabled, value, lastEmitted, setViewNonce]);
+}
+
 export function useDateRangePicker({
   value,
   onChange,
@@ -28,6 +64,7 @@ export function useDateRangePicker({
   weekStartsOn,
   quickRanges,
   messages,
+  followValue = false,
 }: UseDateRangePickerArgs): DateRangePickerState {
   const statusId = useId();
   // `Calendar` reads which month to open on from the range it is handed, and
@@ -44,12 +81,17 @@ export function useDateRangePicker({
     [quickRanges, today, weekStartsOn, maxRangeDays],
   );
   const status = useMemo(() => resolveDayRange(value, maxRangeDays), [value, maxRangeDays]);
+  // What the picker itself last handed out: a value equal to it came FROM here
+  // (a click in the grid), and must not move the grid under the pointer.
+  const lastEmitted = useRef<DateRangeDraft | null>(null);
+  useFollowValue(followValue, value, lastEmitted, setViewNonce);
 
   const emit = (
     next: DateRangeDraft,
     source: DateRangeChangeMeta['source'],
     quickRangeId?: string,
   ): void => {
+    lastEmitted.current = next;
     onChange(next, {
       source,
       ...(quickRangeId ? { quickRangeId } : {}),

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

@@ -0,0 +1,69 @@
+/**
+ * Where the typed half goes when the consumer asked for it BESIDE the months
+ * (`fieldsPlacement="beside"`), and how many months fit with it.
+ *
+ * Decided from the PICKER's own width, never the viewport's: the same form sits
+ * full width on a computer and in a 3/5 column beside a preview on the same
+ * computer, and only its own box knows which. The numbers are the design px the
+ * month grid is built to (`MONTH_SX` in `CalendarMonth`: 304 wide, 24 apart).
+ */
+import type { Theme } from '@mui/material/styles/index.js';
+import { useLayoutEffect, useState, type RefObject } from 'react';
+
+import { remPx } from '../../../tokens/relative';
+
+/**
+ * The design px the layout is computed from, rendered through the theme
+ * (`remPx`) so a density that shrinks the grid shrinks the thresholds with it.
+ * Framed months: the grid's intrinsic 304 a month and 24 between two
+ * (`MONTH_SX`), plus the frame's 16px padding a side and its hairline. The
+ * column beside: the `gap: 4` to the frame and the 220 a `dd/mm/aaaa` field
+ * and its label read well in.
+ */
+const FRAMED_MONTHS: Readonly<Record<number, number>> = { 1: 338, 2: 666 };
+const BESIDE_COLUMN = 252;
+
+export type FieldsPlacement = 'beside' | 'below';
+
+/** The design px a frame around `months` month grids needs (see FRAMED_MONTHS). */
+export function framedMonthsWidth(months: number): number {
+  return FRAMED_MONTHS[months] ?? (FRAMED_MONTHS[2]! * months) / 2;
+}
+
+/**
+ * The layout for a picker `width` px wide asking for `requested` months, in
+ * order of preference: every month requested with the fields beside, then
+ * under them, then one month beside, then one under. A picker not measured yet
+ * (no `ResizeObserver`, a server render) keeps the default layout.
+ */
+export function besideLayout(
+  width: number | null,
+  requested: number,
+  theme: Theme,
+): { months: number; placement: FieldsPlacement } {
+  if (width === null) return { months: requested, placement: 'below' };
+  const framed = (months: number): number => remPx(theme, framedMonthsWidth(months));
+  const beside = remPx(theme, BESIDE_COLUMN);
+  const counts = requested > 1 ? [requested, 1] : [requested];
+  for (const months of counts) {
+    if (width >= framed(months) + beside) return { months, placement: 'beside' };
+    if (width >= framed(months)) return { months, placement: 'below' };
+  }
+  return { months: 1, placement: 'below' };
+}
+
+/** The element's content width, kept current; null until measured or when disabled. */
+export function useMeasuredWidth(ref: RefObject<HTMLElement | null>, enabled: boolean): number | null {
+  const [width, setWidth] = useState<number | null>(null);
+  useLayoutEffect(() => {
+    const element = ref.current;
+    if (!enabled || element === null || typeof ResizeObserver === 'undefined') return undefined;
+    const observer = new ResizeObserver((entries) => {
+      const measured = entries[0]?.contentRect.width;
+      if (measured) setWidth(Math.round(measured));
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [ref, enabled]);
+  return width;
+}