@12-apps/ui 6.97.1 → 6.98.0

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

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

@@ -45,6 +45,13 @@ interface DateRangePickerProps {
   messages?: Partial<DateRangePickerMessages>;
   dataTestId?: string;                      // default 'date-range-picker'
   className?: string;
+  // Opt-in, for a picker laid out IN a page (all off by default):
+  fieldsPlacement?: 'below' | 'beside';     // default 'below'
+  renderFields?: (args: { placement: 'beside' | 'below'; disabled: boolean }) => ReactNode;
+  openEnd?: boolean;                        // a start with no end is an answer
+  disabled?: boolean;                       // shown, not changeable (default false)
+  label?: string;                           // the disabled group's name (default: calendarLabel)
+  calendarLabels?: Partial<CalendarLabels>; // names for the month arrows
 }
 ```
 
@@ -144,8 +151,14 @@ 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.
+So the grid follows the range's **start** — or its **end** when only the end is
+chosen. Picking "This year" in August moves it to January, because that is
+where the range now begins.
+
+A consumer that owns the draft may complete a tap into a different draft than
+the one the picker handed it (keeping an end the tap would have dropped). That
+is still the tap's own result: the grid stays on its month and focus stays on
+the tapped day. Only a change that drops a bound the tap chose moves the grid.
 
 ## Layout
 
@@ -158,6 +171,68 @@ 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.
 
+## A picker laid out in a page
+
+The defaults above are a popover's: one framed block, fields underneath, a
+summary line. A form that shows the range ALWAYS OPEN among its other fields
+needs four more things, each opt-in so no existing screen changes:
+
+- **`fieldsPlacement="beside"`** — the months get their own outlined frame and
+  the typed half sits on the page: in a column BESIDE the frame when the
+  picker's own width holds both, under it when it does not, and with one month
+  instead of two when two would not fit either. Measured on the picker
+  (`ResizeObserver`), never the viewport: a form column beside a preview is
+  narrow on the widest screen. The root carries `data-fields-placement`.
+- **`renderFields({ placement, disabled })`** — the consumer's OWN fields instead of the
+  built-in pair, for a form whose fields carry rules this picker does not (a
+  half-typed date kept until submit, its own messages). The summary line goes
+  with the built-in pair: beside fields that say their own refusals it would
+  only repeat them. The calendar follows the value whenever the consumer moves
+  it, as it follows a typed date — never on a click in the grid.
+- **`openEnd`** — a start with no end is a finished answer ("from this day
+  on"), and the summary says `messages.openEnded` (default `No end date.`)
+  instead of asking for the end. It does not repeat the date: the field beside
+  it shows it. `resolveDayRange` is unchanged; what an open end means is the
+  caller's.
+- **`calendarLabels`** — names for the calendar's month arrows
+  (`PT_BR_UI_LABELS.calendar` in Portuguese); without them they stay unnamed,
+  as before. `PT_BR_UI_LABELS.dateRangePicker.openEnded` is the Portuguese
+  `openEnded`.
+- **`disabled`** — the period is shown but cannot be changed now (a consumer
+  that cannot place its days, FUT-4482). Every day is disabled and a tap
+  writes nothing, the quick ranges are not offered, the built-in boxes are
+  disabled, `renderFields` receives `disabled: true` so the consumer's fields
+  follow, and the root is a `group` named by `label` (default: the calendar
+  label) carrying `aria-disabled`. The month arrows are disabled and today's
+  ring takes the disabled ink. The days INSIDE a shown range keep the
+  secondary ink (`text.secondary`), so the period stays legible on the band
+  (the disabled ink there was 1.56:1). That is the locked picker only: on a
+  live one, a day `isDateDisabled` blocks inside the range keeps the disabled
+  ink. The control cannot say why: say it beside the
+  picker, and make that sentence your fields' `aria-describedby`. **In a
+  popover the consumer disables its own trigger** — the button or field that
+  opens the popover is the consumer's, and this prop cannot reach it.
+- **`showOutsideDays`, `todayIndicator`, `allowSameDayRange`** — `Calendar`'s
+  own options, passed through: hide the neighbouring months' days, ring today
+  (`'ring'`), or refuse one day as a whole range (a second tap on the start day
+  then does nothing). Defaults unchanged: drawn, bold, allowed.
+
+Under the fields' row (`placement="below"`) the frame is as wide as its months
+and centred, never stretched across the page around one month.
+
+- **`fullWidth`** (with `fieldsPlacement="beside"`) — the frame's edges are the
+  picker's: under the fields it spans the picker, beside them it takes what the
+  fields' column leaves (never less than its months at full size), and that
+  column stops at 320 design px. The calendar's seven columns spread across the
+  frame; the day faces keep their 40 design px, and the rows stay 40 tall. Under
+  the fields the frame trims its side padding before a column drops under 40
+  design px (a phone's tap target). For a picker laid into a form section whose
+  heading and fields the frame must line up with. Ignored in the default
+  (popover) layout. Default off.
+- **The in-page frame** is a card on the page: the raised surface role
+  (`surfaces(theme).raised`, `background.paper` unless the host states one) and the
+  default `Card`'s radius.
+
 ## Accessibility
 
 - The quick entries are native `<button>`s with `aria-pressed`; the active one

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

@@ -64,6 +64,7 @@ export function defaultMessages(): DateRangePickerMessages {
     to: 'End date',
     quickRanges: 'Quick ranges',
     incomplete: 'Choose both dates.',
+    openEnded: EN_US_UI_LABELS.dateRangePicker.openEnded,
     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 }) => `${isoToMasked(from, dayMask)} – ${isoToMasked(to, dayMask)}`,
@@ -72,14 +73,21 @@ export function defaultMessages(): DateRangePickerMessages {
   };
 }
 
-/** The line under the fields: the chosen window, or why there isn't one. */
+/**
+ * The line under the fields: the chosen window, or why there isn't one. With
+ * `openEnd`, a start with no end is an answer of its own and is said as one.
+ */
 export function statusMessage(
   status: DateRangeStatus,
   messages: DateRangePickerMessages,
   maxRangeDays: number | undefined,
+  openEnd: { enabled: boolean; draft: DateRangeDraft } = { enabled: false, draft: { from: null, to: null } },
 ): string {
   if (status.ok) return messages.summary(status.window);
-  if (status.problem === 'incomplete') return messages.incomplete;
+  if (status.problem === 'incomplete') {
+    const openEnded = openEnd.enabled && openEnd.draft.from !== null && openEnd.draft.to === null;
+    return openEnded ? (messages.openEnded ?? messages.incomplete) : messages.incomplete;
+  }
   if (status.problem === 'reversed') return messages.reversed;
   return messages.overMax({ maxRangeDays: maxRangeDays ?? status.days, days: status.days });
 }

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

@@ -27,34 +27,27 @@ import Paper from '@mui/material/Paper/index.js';
 import useMediaQuery from '@mui/material/useMediaQuery/index.js';
 import { useTheme } from '@mui/material/styles/index.js';
 import type { SxProps, Theme } from '@mui/material/styles/index.js';
-import React from 'react';
+import React, { useRef } from 'react';
 
+import type { CalendarLabels } from '../../../copy/labels';
 import { Calendar } from '../Calendar';
 
 import { toLocalDay } from './DateRangePicker.dates';
 import { useDateRangePicker } from './DateRangePicker.hooks';
+import { CALENDAR_CLASS, FLAT_CALENDAR, fieldsColumnSx, frameSx } from './DateRangePicker.frame';
+import { besideLayout, useMeasuredWidth, type FieldsPlacement } from './DateRangePicker.layout';
 import { DEFAULT_QUICK_RANGES } from './DateRangePicker.quick';
 import type { DateRangeDraft, DateRangePickerProps, WeekStart } from './DateRangePicker.types';
 import { DateRangeFields } from './DateRangePickerFields';
 import { DateRangeQuickList } from './DateRangePickerQuickList';
 
-const CALENDAR_CLASS = 'date-range-picker__calendar';
-
 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',
-  },
+  ...FLAT_CALENDAR,
 };
 
 const BODY_SX: SxProps<Theme> = {
@@ -132,6 +125,15 @@ function useMonthCount(requested: number | undefined): number | undefined {
 }
 
 /** The grid, in range mode — `Calendar`, never a second implementation of one. */
+/** The calendar options a picker passes through untouched. */
+type CalendarDisplay = Pick<
+  DateRangePickerProps,
+  'showOutsideDays' | 'todayIndicator' | 'allowSameDayRange' | 'fullWidth' | 'disabled'
+>;
+
+/** Every day, for a picker that is `disabled`. */
+const EVERY_DAY = (): boolean => true;
+
 function RangeCalendar({
   calendarLabel,
   picker,
@@ -140,7 +142,11 @@ function RangeCalendar({
   weekStartsOn,
   months,
   maxRangeDays,
+  labels,
+  display,
 }: {
+  labels: Partial<CalendarLabels> | undefined;
+  display: CalendarDisplay;
   picker: Picker;
   value: DateRangeDraft;
   locale: string;
@@ -169,6 +175,12 @@ function RangeCalendar({
       // 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}
+      {...(labels ? { labels } : {})}
+      showOutsideDays={display.showOutsideDays}
+      todayIndicator={display.todayIndicator}
+      allowSameDayRange={display.allowSameDayRange}
+      fullWidth={display.fullWidth}
+      {...(display.disabled === true ? { isDateDisabled: EVERY_DAY, navigationDisabled: true } : {})}
     />
   );
 }
@@ -200,59 +212,167 @@ function QuickColumn({
   );
 }
 
-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 {
+/** The typed half: the consumer's own fields, or the built-in pair and its line. */
+function TypedHalf({
+  props,
+  picker,
+  placement,
+}: {
+  props: DateRangePickerProps;
+  picker: Picker;
+  placement: FieldsPlacement;
+}): React.JSX.Element {
+  const disabled = props.disabled === true;
+  if (props.renderFields) return <>{props.renderFields({ placement, disabled })}</>;
+  return (
+    <DateRangeFields
+      value={props.value}
+      status={picker.status}
+      messages={picker.copy}
+      maxRangeDays={props.maxRangeDays}
+      onEdit={picker.editBound}
+      statusId={picker.statusId}
+      dataTestId={props.dataTestId ?? 'date-range-picker'}
+      openEnd={props.openEnd ?? false}
+      stacked={placement === 'beside'}
+      disabled={disabled}
+    />
+  );
+}
+
+/**
+ * How many months, and where the typed half goes. The default layout counts
+ * months by the viewport, as it always did; `beside` measures the picker.
+ */
+function usePickerLayout(props: DateRangePickerProps): {
+  root: React.RefObject<HTMLDivElement | null>;
+  months: number | undefined;
+  placement: FieldsPlacement;
+} {
+  const theme = useTheme();
+  const viewportMonths = useMonthCount(props.numberOfMonths);
+  const root = useRef<HTMLDivElement>(null);
+  const beside = props.fieldsPlacement === 'beside';
+  const width = useMeasuredWidth(root, beside);
+  if (!beside || width === null) return { root, months: viewportMonths, placement: 'below' };
+  const layout = besideLayout(width, props.numberOfMonths ?? 2, theme);
+  return { root, months: layout.months, placement: layout.placement };
+}
+
+/** The `beside` layout: the months in their own frame, the fields on the page. */
+function InPageLayout({
+  props,
+  picker,
+  layout,
+  body,
+}: {
+  props: DateRangePickerProps;
+  picker: Picker;
+  layout: ReturnType<typeof usePickerLayout>;
+  body: React.ReactNode;
+}): React.JSX.Element {
+  const sideBySide = layout.placement === 'beside';
+  return (
+    <Box
+      ref={layout.root}
+      className={props.className}
+      data-testid={props.dataTestId ?? 'date-range-picker'}
+      data-fields-placement={layout.placement}
+      {...disabledGroup(props, picker)}
+      sx={{
+        display: 'flex',
+        flexDirection: sideBySide ? 'row' : 'column',
+        alignItems: sideBySide ? 'flex-start' : 'stretch',
+        gap: sideBySide ? 4 : 2,
+        width: '100%',
+        minWidth: 0,
+      }}
+    >
+      <Paper variant="outlined" sx={frameSx(sideBySide, props.fullWidth === true, layout.months ?? 1)}>
+        {body}
+      </Paper>
+      <Box sx={fieldsColumnSx(sideBySide, props.fullWidth === true)}>
+        <TypedHalf props={props} picker={picker} placement={layout.placement} />
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * A disabled picker's root is a named GROUP (review round 6): `aria-disabled`
+ * is only valid on an element with a role, and the name says what is off.
+ * Enabled, the root carries neither, as it always did.
+ */
+function disabledGroup(props: DateRangePickerProps, picker: Picker) {
+  if (props.disabled !== true) return {};
+  return { role: 'group', 'aria-label': props.label ?? picker.copy.calendarLabel, 'aria-disabled': true } as const;
+}
+
+/** The default layout: one framed block, the typed half under the months. */
+function PopoverLayout({
+  props,
+  picker,
+  body,
+}: {
+  props: DateRangePickerProps;
+  picker: Picker;
+  body: React.ReactNode;
+}): React.JSX.Element {
+  const typed = <TypedHalf props={props} picker={picker} placement="below" />;
+  return (
+    <Paper
+      className={props.className}
+      data-testid={props.dataTestId ?? 'date-range-picker'}
+      {...disabledGroup(props, picker)}
+      sx={ROOT_SX}
+    >
+      {body}
+      {props.renderFields ? typed : <Box sx={FIELDS_DIVIDER_SX}>{typed}</Box>}
+    </Paper>
+  );
+}
+
+export function DateRangePicker(props: DateRangePickerProps): React.JSX.Element {
+  const { value, maxRangeDays, weekStartsOn = 0, locale = 'en-US', dataTestId = 'date-range-picker' } = props;
   const picker = useDateRangePicker({
     value,
-    onChange,
-    timeZone,
-    now,
+    onChange: props.onChange,
+    timeZone: props.timeZone,
+    now: props.now,
     maxRangeDays,
     weekStartsOn,
-    quickRanges,
-    messages,
+    quickRanges: props.quickRanges ?? DEFAULT_QUICK_RANGES,
+    messages: props.messages,
+    followValue: props.renderFields !== undefined,
   });
-  const months = useMonthCount(numberOfMonths);
+  const layout = usePickerLayout(props);
 
-  return (
-    <Paper className={className} data-testid={dataTestId} sx={ROOT_SX}>
-      <Box sx={BODY_SX}>
-        <RangeCalendar
-          calendarLabel={picker.copy.calendarLabel}
-          picker={picker}
-          value={value}
-          locale={locale}
-          weekStartsOn={weekStartsOn}
-          months={months}
-          maxRangeDays={maxRangeDays}
-        />
+  const body = (
+    <Box sx={BODY_SX}>
+      <RangeCalendar
+        calendarLabel={picker.copy.calendarLabel}
+        picker={picker}
+        value={value}
+        locale={locale}
+        weekStartsOn={weekStartsOn}
+        months={layout.months}
+        maxRangeDays={maxRangeDays}
+        labels={props.calendarLabels}
+        // `fullWidth` fills the in-page frame; the popover's frame is as wide
+        // as its months, and a filling calendar in it spread past the quick
+        // column and the typed pair (FUT-4156, round 3).
+        display={{ ...props, fullWidth: props.fieldsPlacement === 'beside' && props.fullWidth === true }}
+      />
+      {props.disabled === true ? null : (
         <QuickColumn picker={picker} maxRangeDays={maxRangeDays} dataTestId={dataTestId} />
-      </Box>
-      <Box sx={FIELDS_DIVIDER_SX}>
-        <DateRangeFields
-          value={value}
-          status={picker.status}
-          messages={picker.copy}
-          maxRangeDays={maxRangeDays}
-          onEdit={picker.editBound}
-          statusId={picker.statusId}
-          dataTestId={dataTestId}
-        />
-      </Box>
-    </Paper>
+      )}
+    </Box>
   );
+
+  if (props.fieldsPlacement === 'beside') {
+    return <InPageLayout props={props} picker={picker} layout={layout} body={body} />;
+  }
+  return <PopoverLayout props={props} picker={picker} body={body} />;
 }
 
 export default DateRangePicker;