@12-apps/ui 6.89.2 → 6.91.0

package/src/components/data-display/RegionMap/RegionMap.hooks.ts

@@ -6,16 +6,19 @@ import {
   geometryCache,
   hitRegion,
   projectionAt,
-  viewBoxFor,
   type DrawnRegion,
   type PlaneBox,
+  type Projection,
 } from './RegionMap.helpers';
-import type { RegionMapProps, RegionMapRegion } from './RegionMap.types';
+import type { RegionMapProps } from './RegionMap.types';
+import { centreOf, reachBox, viewWithin } from './RegionMap.view';
 
 /** What the drawing needs, derived from the props. */
 export interface RegionMapModel {
   /** The square shown, or null when there is nothing to centre on. */
   view: PlaneBox | null;
+  /** The projection drawn with, or null when there is nothing to centre on. */
+  projection: Projection | null;
   drawn: DrawnRegion[];
   /** Radii drawn, in metres; empty without circles. */
   radii: number[];
@@ -28,15 +31,6 @@ export interface RegionMapModel {
 /** A tap reaches an area this close: a share of the view (~8 px on a phone). */
 const TOLERANCE_SHARE = 1 / 45;
 
-/** The middle of every area, for a map with no centre of its own. */
-function centreOf(regions: readonly RegionMapRegion[]): { latitude: number; longitude: number } | null {
-  const points = regions.flatMap((r) => r.rings.flat());
-  const lats = extent(points.map(([lat]) => lat));
-  const lngs = extent(points.map(([, lng]) => lng));
-  if (lats === null || lngs === null) return null;
-  return { latitude: (lats.min + lats.max) / 2, longitude: (lngs.min + lngs.max) / 2 };
-}
-
 /** The click, in the drawing's own coordinates — or null where it cannot be read. */
 function svgPoint(event: React.MouseEvent<SVGSVGElement>): { x: number; y: number } | null {
   const svg = event.currentTarget;
@@ -46,16 +40,6 @@ function svgPoint(event: React.MouseEvent<SVGSVGElement>): { x: number; y: numbe
   return { x: point.x, y: point.y };
 }
 
-/** The view: the outermost circle when there is one, else every area's box. */
-function viewOf(outermostMetres: number | null, drawable: () => (PlaneBox | null)[]): PlaneBox | null {
-  if (outermostMetres !== null) return viewBoxFor(outermostMetres, null);
-  const boxes = drawable().filter((box): box is PlaneBox => box !== null);
-  const xs = extent(boxes.flatMap((b) => [b.minX, b.minX + b.spanX]));
-  const ys = extent(boxes.flatMap((b) => [b.minY, b.minY + b.spanY]));
-  if (xs === null || ys === null) return null;
-  return viewBoxFor(null, { minX: xs.min, minY: ys.min, spanX: xs.max - xs.min, spanY: ys.max - ys.min });
-}
-
 /** Which area a click or tap means — see `useRegionMap`. */
 function tappedRegion(
   event: React.MouseEvent<SVGSVGElement>,
@@ -74,16 +58,18 @@ function tappedRegion(
   );
 }
 
-/** The geometry cache for a centre, or null without one. */
-function useGeometry(
-  origin: { latitude: number; longitude: number } | null,
-): ReturnType<typeof geometryCache> | null {
+/** The projection and geometry cache for a centre, or nulls without one. */
+function useGeometry(origin: { latitude: number; longitude: number } | null): {
+  projection: Projection | null;
+  geometryOf: ReturnType<typeof geometryCache> | null;
+} {
   const lat = origin?.latitude ?? null;
   const lng = origin?.longitude ?? null;
-  return React.useMemo(
-    () => (lat === null || lng === null ? null : geometryCache(projectionAt({ latitude: lat, longitude: lng }))),
-    [lat, lng],
-  );
+  return React.useMemo(() => {
+    if (lat === null || lng === null) return { projection: null, geometryOf: null };
+    const projection = projectionAt({ latitude: lat, longitude: lng });
+    return { projection, geometryOf: geometryCache(projection) };
+  }, [lat, lng]);
 }
 
 /**
@@ -101,13 +87,18 @@ export function useRegionMap({
   regions,
   center,
   circles = [],
+  reach,
   onToggle,
-}: Pick<RegionMapProps, 'regions' | 'center' | 'circles' | 'onToggle'>): RegionMapModel {
-  const geometryOf = useGeometry(center ?? centreOf(regions));
+}: Pick<RegionMapProps, 'regions' | 'center' | 'circles' | 'reach' | 'onToggle'>): RegionMapModel {
+  const { projection, geometryOf } = useGeometry(center ?? centreOf(regions));
   const radii = circles.map((c) => c.radiusMetres);
   const outermostMetres = extent(radii)?.max ?? null;
   const view =
-    geometryOf === null ? null : viewOf(outermostMetres, () => regions.map((r) => geometryOf(r.rings).bounds));
+    projection === null || geometryOf === null
+      ? null
+      : viewWithin(outermostMetres, reach === undefined ? null : reachBox(reach, projection), () =>
+          regions.map((r) => geometryOf(r.rings).bounds),
+        );
   const drawn = geometryOf && view ? drawOrder(regions, geometryOf, view) : [];
   const pointerType = React.useRef<string>('mouse');
 
@@ -121,5 +112,5 @@ export function useRegionMap({
     if (hit) onToggle(hit);
   };
 
-  return { view, drawn, radii, outermostMetres, onPointerDown, onClick };
+  return { view, projection, drawn, radii, outermostMetres, onPointerDown, onClick };
 }

package/src/components/data-display/RegionMap/RegionMap.md

@@ -75,6 +75,27 @@ clipped at an edge — the map reads the same at 320 px and at 1600 px. The
 drawing is square; `maxHeight` caps it on a wide screen, and where it sits in a
 wider box is the host's call.
 
+### A host can draw inside it, at its scale
+
+A host often has something of its own to show over the areas — a band served
+past the largest circle, a route, a marker — and laying a second SVG over the
+drawing means copying its view math and losing its frame. So:
+
+- `reach` (`{ radiusMetres }` or `{ bounds }`) is an extent the view must ALSO
+  fit, before the 12% margin. With circles the view stays centred on the centre
+  and grows to the reach's farthest edge, so a ring stays a circle in the
+  middle; without circles the view fits the areas and the reach together. A
+  reach no radius describes — the outlines of some areas — is a box:
+  `boundsOfRings(rings)`. Omit it and the view is exactly what it was.
+- `overlay(layer)` draws inside the SVG with `layer.view` and
+  `layer.projection` (`projectionAt(center)`), over the excluded hatch and
+  under the circles, highlights and centre. It sits in a `pointer-events: none`
+  group, so a tap still reaches the area beneath.
+- `regionMapView(props)` returns the same view for HTML laid over the drawing
+  (a pill on a circle, a note): a point `p` sits at `(p.x - view.minX) /
+  view.spanX` across; with circles the view is centred and its half-side is
+  `view.spanX / 2`.
+
 ## Props
 
 | prop | type | default | what it does |
@@ -82,6 +103,8 @@ wider box is the host's call.
 | `regions` | `readonly RegionMapRegion[]` | — | the areas; drawn when any part is in view |
 | `center` | `{ latitude, longitude } \| null` | — | centre, dot and circles; `null` centres on the areas, no dot |
 | `circles` | `readonly { radiusMetres }[]` | `[]` | dashed circles; the view fits the largest |
+| `reach` | `{ radiusMetres } \| { bounds: { south, west, north, east } }` | — | an extent the view must also fit (margin on top) |
+| `overlay` | `(layer: { view, projection }) => ReactNode` | — | a host layer inside the SVG, under the circles, tap-transparent |
 | `onToggle` | `(id: string) => void` | — | a tap or a list press; omit for read-only |
 | `highlightedIds` | `readonly string[]` | `[]` | areas to point at (a search's hits), outlined and named |
 | `copy` | `RegionMapCopy` | — | every word |
@@ -117,6 +140,10 @@ wider box is the host's call.
   `[latitude, longitude]` points; outlines usually travel this way.
 - `hitRegion(regions, point, tolerance)` and `projectionAt(center)` — the hit
   test and projection the component uses, for a host that draws its own layer.
+- `regionMapView({ regions, center, circles, reach })` — the view the
+  component shows for those props, in projected metres, for HTML laid over it.
+- `boundsOfRings(rings)` — the latitude/longitude box around some outlines,
+  for a `reach` no radius describes.
 
 ## Example
 

package/src/components/data-display/RegionMap/RegionMap.tsx

@@ -29,6 +29,9 @@ const NO_IDS: readonly string[] = [];
  *   is that path. A finger's tap takes the SMALLEST area within a few pixels'
  *   worth of metres (`hitRegion`), so a sliver beside a big area can be hit
  *   from the map; one too thin even for that is still on the list.
+ * - **The host can draw inside it.** `reach` widens the view past the largest
+ *   circle and `overlay` draws a layer in the SVG at the map's own projection,
+ *   tap-transparent; `regionMapView` gives the same view to HTML laid over it.
  * - **A toggle is cheap.** Geometry is projected once per `rings` identity,
  *   and the base layer is memoised, so a tap re-renders the hatch and labels.
  */
@@ -36,6 +39,8 @@ export function RegionMap({
   regions,
   center,
   circles,
+  reach,
+  overlay,
   onToggle,
   highlightedIds = NO_IDS,
   copy,
@@ -46,7 +51,7 @@ export function RegionMap({
   dataTestId = 'region-map',
 }: RegionMapProps): React.JSX.Element | null {
   const theme = useTheme();
-  const model = useRegionMap({ regions, center, circles, onToggle });
+  const model = useRegionMap({ regions, center, circles, reach, onToggle });
   const { view } = model;
   if (view === null && regions.length === 0) return null;
   return (
@@ -55,6 +60,7 @@ export function RegionMap({
         <>
           <RegionMapDrawing
             model={{ ...model, view }}
+            overlay={overlay}
             showCenter={center !== null}
             highlightedIds={highlightedIds}
             maxHeight={maxHeight}

package/src/components/data-display/RegionMap/RegionMap.types.ts

@@ -7,6 +7,10 @@
  * every word arrives through `copy`.
  */
 
+import type React from 'react';
+
+import type { PlaneBox, Projection } from './RegionMap.helpers';
+
 /** A latitude/longitude pair, in that order. */
 export type RegionMapPoint = readonly [latitude: number, longitude: number];
 
@@ -50,6 +54,29 @@ export interface RegionMapCircle {
   radiusMetres: number;
 }
 
+/** A latitude/longitude box, by its four edges in degrees. */
+export interface RegionMapBounds {
+  south: number;
+  west: number;
+  north: number;
+  east: number;
+}
+
+/**
+ * An extent the view must fit besides its circles: a radius around the centre,
+ * or a box — e.g. the bounds of some outlines (`boundsOfRings`), for a reach
+ * no single radius describes.
+ */
+export type RegionMapReach = { radiusMetres: number } | { bounds: RegionMapBounds };
+
+/** What a host overlay is drawn with: the map's own view and projection. */
+export interface RegionMapLayer {
+  /** The SVG viewBox, in projected metres. */
+  view: PlaneBox;
+  /** The projection the map draws with — `projectionAt(center)`. */
+  projection: Projection;
+}
+
 /** Every word the map prints or announces. */
 export interface RegionMapCopy {
   /** The drawing's accessible name (`role="img"`). */
@@ -95,6 +122,20 @@ export interface RegionMapProps {
   center: { latitude: number; longitude: number } | null;
   /** Circles around the centre; the view fits the largest. */
   circles?: readonly RegionMapCircle[];
+  /**
+   * An extent the view must ALSO fit, before its margin — something the host
+   * draws past the largest circle. With circles the view stays centred on the
+   * centre and grows to the reach's farthest edge; without, it fits the areas
+   * and the reach together. Omit it and the view is the circles' (or areas').
+   */
+  reach?: RegionMapReach;
+  /**
+   * A host layer drawn INSIDE the drawing's SVG, over the excluded hatch and
+   * under the circles, highlights and centre, so it shares the map's view,
+   * projection and frame. It is wrapped in `pointer-events: none`: taps go
+   * through it to the areas. Return SVG elements, in projected metres.
+   */
+  overlay?: (layer: RegionMapLayer) => React.ReactNode;
   /**
    * A tap on an area, or a press of its list button. Omit it and the map is
    * read-only: nothing is tappable and the list rows are not buttons.

package/src/components/data-display/RegionMap/RegionMap.view.ts

@@ -0,0 +1,105 @@
+import {
+  extent,
+  planeBounds,
+  projectionAt,
+  projectRings,
+  viewBoxFor,
+  type PlaneBox,
+  type Projection,
+} from './RegionMap.helpers';
+import type {
+  RegionMapBounds,
+  RegionMapCircle,
+  RegionMapReach,
+  RegionMapRegion,
+  RegionMapRing,
+} from './RegionMap.types';
+
+// What `RegionMap` shows: its view, given the circles, the areas and a host's
+// `reach` — pure, so a host laying HTML over the drawing computes the same one.
+
+/** The smallest box holding every given box, or null with none. */
+export function unionBox(boxes: readonly (PlaneBox | null)[]): PlaneBox | null {
+  const real = boxes.filter((box): box is PlaneBox => box !== null);
+  const xs = extent(real.flatMap((b) => [b.minX, b.minX + b.spanX]));
+  const ys = extent(real.flatMap((b) => [b.minY, b.minY + b.spanY]));
+  if (xs === null || ys === null) return null;
+  return { minX: xs.min, minY: ys.min, spanX: xs.max - xs.min, spanY: ys.max - ys.min };
+}
+
+/** The latitude/longitude box around some outlines — a `reach` no radius describes. */
+export function boundsOfRings(rings: readonly RegionMapRing[]): RegionMapBounds | null {
+  const points = rings.flat();
+  const lats = extent(points.map(([latitude]) => latitude));
+  const lngs = extent(points.map(([, longitude]) => longitude));
+  if (lats === null || lngs === null) return null;
+  return { south: lats.min, west: lngs.min, north: lats.max, east: lngs.max };
+}
+
+/** A `reach` as a box in projected metres (a radius is a square around the centre). */
+export function reachBox(reach: RegionMapReach, projection: Projection): PlaneBox | null {
+  if ('radiusMetres' in reach) {
+    const r = reach.radiusMetres;
+    return Number.isFinite(r) && r > 0 ? { minX: -r, minY: -r, spanX: r * 2, spanY: r * 2 } : null;
+  }
+  const { south, west, north, east } = reach.bounds;
+  const a = projection.project([north, west]);
+  const b = projection.project([south, east]);
+  return unionBox([{ minX: a.x, minY: a.y, spanX: 0, spanY: 0 }, { minX: b.x, minY: b.y, spanX: 0, spanY: 0 }]);
+}
+
+/** How far the box reaches from the centre along either axis — the half-side of a centred square holding it. */
+function farthestEdge(box: PlaneBox): number {
+  return Math.max(Math.abs(box.minX), Math.abs(box.minX + box.spanX), Math.abs(box.minY), Math.abs(box.minY + box.spanY));
+}
+
+/**
+ * The view, given what it must fit: the outermost circle and the `reach` with
+ * the margin on top, still centred on the centre; else every area and the
+ * reach together. Without a reach it is exactly `viewBoxFor`'s.
+ */
+export function viewWithin(
+  outermostMetres: number | null,
+  reach: PlaneBox | null,
+  areaBoxes: () => readonly (PlaneBox | null)[],
+): PlaneBox | null {
+  if (outermostMetres !== null) {
+    return viewBoxFor(Math.max(outermostMetres, reach === null ? 0 : farthestEdge(reach)), null);
+  }
+  return viewBoxFor(null, unionBox([...areaBoxes(), reach]));
+}
+
+/** The middle of every area, for a map with no centre of its own. */
+export function centreOf(regions: readonly RegionMapRegion[]): { latitude: number; longitude: number } | null {
+  const bounds = boundsOfRings(regions.flatMap((r) => r.rings));
+  if (bounds === null) return null;
+  return { latitude: (bounds.south + bounds.north) / 2, longitude: (bounds.west + bounds.east) / 2 };
+}
+
+/**
+ * The square `RegionMap` shows for these props, in projected metres around
+ * `center` (or the areas' middle) — for a host that lays its own HTML over the
+ * drawing at the same scale: a point `p` sits at
+ * `(p.x - view.minX) / view.spanX` across. With circles the view is centred,
+ * so its half-side is `view.spanX / 2`.
+ */
+export function regionMapView({
+  regions,
+  center,
+  circles = [],
+  reach,
+}: {
+  regions: readonly RegionMapRegion[];
+  center: { latitude: number; longitude: number } | null;
+  circles?: readonly RegionMapCircle[];
+  reach?: RegionMapReach;
+}): PlaneBox | null {
+  const origin = center ?? centreOf(regions);
+  if (origin === null) return null;
+  const projection = projectionAt(origin);
+  return viewWithin(
+    extent(circles.map((c) => c.radiusMetres))?.max ?? null,
+    reach === undefined ? null : reachBox(reach, projection),
+    () => regions.map((r) => planeBounds(projectRings(r.rings, projection))),
+  );
+}

package/src/components/data-display/RegionMap/RegionMapDrawing.tsx

@@ -8,9 +8,12 @@ import { rem, remPx } from '../../../tokens/relative';
 import { labelPosition, type AreaGeometry, type DrawnRegion, type PlaneBox } from './RegionMap.helpers';
 import type { RegionMapModel } from './RegionMap.hooks';
 import { labelOrder, placeLabels } from './RegionMap.labels';
+import type { RegionMapLayer } from './RegionMap.types';
 
 export interface RegionMapDrawingProps {
   model: RegionMapModel & { view: PlaneBox };
+  /** The host's layer, drawn inside the SVG under the circles (`RegionMapProps.overlay`). */
+  overlay?: (layer: RegionMapLayer) => React.ReactNode;
   showCenter: boolean;
   highlightedIds: readonly string[];
   maxHeight: string | undefined;
@@ -32,6 +35,7 @@ export interface RegionMapDrawingProps {
  */
 export function RegionMapDrawing({
   model,
+  overlay,
   showCenter,
   highlightedIds,
   maxHeight,
@@ -78,6 +82,13 @@ export function RegionMapDrawing({
         <Hatch id={hatchId} pitch={view.spanX / 70} theme={theme} />
         <BaseAreas areas={base} testId={testId} theme={theme} />
         <ExcludedAreas drawn={drawn} hatchId={hatchId} testId={testId} theme={theme} />
+        {overlay && model.projection && (
+          // `pointer-events` is inherited in SVG: nothing the host draws here
+          // takes a tap from the areas beneath.
+          <g pointerEvents="none" data-testid={`${testId}-overlay`}>
+            {overlay({ view, projection: model.projection })}
+          </g>
+        )}
         <Circles radii={model.radii} theme={theme} />
         <Highlights areas={highlighted} testId={testId} theme={theme} />
         {showCenter && (

package/src/components/data-display/RegionMap/index.ts

@@ -1,13 +1,17 @@
 export { RegionMap } from './RegionMap';
 export { decodePolyline, hitRegion, projectionAt } from './RegionMap.helpers';
-export type { AreaGeometry, PlanePoint, PlaneRegion } from './RegionMap.helpers';
+export { boundsOfRings, regionMapView } from './RegionMap.view';
+export type { AreaGeometry, PlaneBox, PlanePoint, PlaneRegion, Projection } from './RegionMap.helpers';
 export type {
+  RegionMapBounds,
   RegionMapCircle,
   RegionMapCopy,
+  RegionMapLayer,
   RegionMapListMode,
   RegionMapListSort,
   RegionMapPoint,
   RegionMapProps,
+  RegionMapReach,
   RegionMapRegion,
   RegionMapRing,
 } from './RegionMap.types';

package/src/components/data-display/RegionMap/tests.md

@@ -6,12 +6,20 @@
 - [x] `__tests__/region-map-helpers.test.ts` — the geometry: even-odd with a
       hole, distance, which area a tap means (hole, smallest, sliver within the
       tolerance even from inside a big neighbour, nothing beyond it), the view,
-      label placement, `extent` on 200k values, the projection and the decoder
+      label placement, `extent` on 200k values, the projection and the decoder;
+      the view with a reach (none is today's view, a radius past the circle
+      grows it centred, a smaller one never shrinks it, a box off to one side
+      by its farthest edge, areas and reach together with no circle, a
+      non-positive radius ignored) and `boundsOfRings`
 - [x] `__tests__/region-map.test.tsx` — what is drawn (areas, hatch + name for
       excluded only, several highlights, nothing with no centre and no areas),
       what a tap reports, read-only, and the list (collapsed by default with its
       count, `aria-expanded`, `aria-pressed`, state in words, outside areas off
-      the list and out of the count, `listed`, sort by name, detail, `none`)
+      the list and out of the count, `listed`, sort by name, detail, `none`),
+      and the reach and overlay (viewBox unchanged without a reach, widened as
+      `regionMapView` says with one, the overlay inside the SVG in a
+      `pointer-events: none` group with the map's view and projection, a tap
+      still reaching the area beneath, no group without an overlay)
 
 ## Storybook Tests Status
 

package/src/components/form/Calendar/Calendar.md

@@ -209,11 +209,26 @@ month/year buttons rather than squeezing them (`SelectorsFitA320Sheet`).
 
 ## Accessibility
 
-- Container month: `role="grid"`, labelled by month/year (e.g., `aria-labelledby="cal-2025-09"`).
+- Container month: `role="grid"`, named by its month and year in `locale`
+  (`aria-label="outubro de 2026"`). It used to point `aria-labelledby` at an id
+  nothing carried, so the grid had no name (FUT-4144).
 - Weekday headers: `role="columnheader"`, short names with `abbr` for SR if needed.
 - Day cells: `role="gridcell"`, `aria-selected` true for selected day(s). For ranges, set `aria-selected="true"` on all in range or use `aria-current="date"` for today.
+- Each visible day is named whole, in `locale`: `aria-label="1 de outubro de 2026"`
+  (`"October 1, 2026"` in en-US). The cell's text is the bare number, which in a
+  two-month range calendar names two different days (FUT-4144).
+- The arrows of the default caption carry `labels.previousMonth`/`nextMonth`
+  when the host passes `labels`; without `labels` they stay as they were.
 - Disabled days: `aria-disabled="true"`.
-- Keyboard support (roving focus within the grid):
+- With `showOutsideDays={false}` an outside day is an inert, `aria-hidden`
+  placeholder: no button, no name, no tab stop. Visible outside days are
+  unchanged.
+- Keyboard support (roving focus within the grid). When a NAVIGATION key is
+  pressed on a day (the reader tabbed or clicked onto it), focus follows the tab
+  stop to the new day in its own month (never its muted copy in the month
+  beside it), across a month change too. Enter, Space, Tab and Escape move no
+  day and never move focus; with focus on the container it stays there, as
+  before:
   - Arrow keys: move by 1 day (left/right) or 1 week (up/down).
   - Home/End: move to start/end of week.
   - PageUp/PageDown: previous/next month (with Shift for year).

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

@@ -1,7 +1,7 @@
 import type { SxProps, Theme } from '@mui/material/styles/index.js';
 import Box from '@mui/material/Box/index.js';
 import Paper from '@mui/material/Paper/index.js';
-import React, { useCallback, useRef } from 'react';
+import React, { useCallback, useEffect, useRef } from 'react';
 
 import { EN_US_UI_LABELS } from '../../../en-US.labels';
 import { rem, sxRem } from '../../../tokens/relative';
@@ -9,6 +9,7 @@ import { resolveLabels } from '../../../utils/resolve-labels';
 
 import { resolveCalendarProps } from './Calendar.helpers';
 import { useCalendar } from './Calendar.hooks';
+import { navigateFocus } from './Calendar.keyboard';
 import { useCalendarPicker } from './Calendar.picker';
 import type { CalendarProps, ResolvedCalendarProps } from './Calendar.types';
 import type { DayCellContext } from './CalendarDayCell';
@@ -32,6 +33,7 @@ type CalendarState = ReturnType<typeof useCalendar>;
 
 const buildDayContext = (props: ResolvedCalendarProps, calendar: CalendarState): DayCellContext => ({
   selectionMode: props.selectionMode,
+  locale: props.locale,
   value: props.value,
   range: props.range,
   showOutsideDays: props.showOutsideDays,
@@ -60,6 +62,45 @@ const useRootRef = (forwarded: React.ForwardedRef<HTMLDivElement>) => {
   return { rootRef, setRoot };
 };
 
+/** The tab stop as a day of its OWN month — side by side, an outside copy of it comes first in the DOM. */
+const OWN_MONTH_STOP = '[role="gridcell"][tabindex="0"][data-in-month="true"]';
+const ANY_STOP = '[role="gridcell"][tabindex="0"]';
+
+/**
+ * Keeps the keyboard's place visible when it is on a DAY.
+ *
+ * The arrows move the grid's one tab stop (`focusedDate`), and that is enough
+ * while the container holds focus. But a reader who tabbed onto a day, or
+ * clicked one, has focus on that day's button: the tab stop moved and focus
+ * stayed behind on a cell that is no longer it, so the ring sat on the old day
+ * and a month change unmounted it under the reader.
+ *
+ * So a NAVIGATION key pressed on a day notes where the tab stop was, and once
+ * it has moved, focus follows it to the day in its own month. Any other key —
+ * Enter, Tab, Escape — clears the note: Enter re-sets the same day and must
+ * leave focus alone, and a stale note would pull focus into the grid on the
+ * next mouse pick.
+ */
+const useFollowDayFocus = (
+  rootRef: React.RefObject<HTMLDivElement | null>,
+  focusedDate: Date,
+  firstDayOfWeek: number,
+) => {
+  const movedFrom = useRef<number | null>(null);
+  useEffect(() => {
+    const from = movedFrom.current;
+    movedFrom.current = null;
+    if (from === null || from === focusedDate.getTime()) return;
+    const root = rootRef.current;
+    (root?.querySelector<HTMLElement>(OWN_MONTH_STOP) ?? root?.querySelector<HTMLElement>(ANY_STOP))?.focus();
+  }, [rootRef, focusedDate]);
+  return (event: React.KeyboardEvent) => {
+    const onDay = (event.target as HTMLElement).getAttribute('role') === 'gridcell';
+    const moves = navigateFocus(event.key, focusedDate, { firstDayOfWeek, shiftKey: event.shiftKey }) !== null;
+    movedFrom.current = onDay && moves ? focusedDate.getTime() : null;
+  };
+};
+
 export const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>((componentProps, ref) => {
   const props = resolveCalendarProps(componentProps);
   const { monthsToShow, locale, renderHeader, renderFooter, className, ariaLabel } = props;
@@ -69,6 +110,8 @@ export const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>((compone
   const bounds = { minDate: props.minDate, maxDate: props.maxDate };
   const picker = useCalendarPicker({ rootRef, bounds, ...calendar });
   const dayContext = buildDayContext(props, calendar);
+  const noteKeyTarget = useFollowDayFocus(rootRef, calendar.focusedDate, props.firstDayOfWeek);
+  const labels = resolveLabels(EN_US_UI_LABELS.calendar, props.labels);
   // The selectors caption always resolves to one month (see the helpers).
   const firstMonth = calendar.monthMatrices[0];
 
@@ -81,7 +124,14 @@ export const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>((compone
       tabIndex={0}
       // The day keys belong to the days: with a month or year grid open there
       // is no focused day on screen to move.
-      onKeyDown={picker.view === 'days' ? calendar.handleKeyDown : undefined}
+      onKeyDown={
+        picker.view === 'days'
+          ? (event) => {
+              noteKeyTarget(event);
+              calendar.handleKeyDown(event);
+            }
+          : undefined
+      }
       data-testid="calendar-container"
       sx={containerSx(monthsToShow)}
     >
@@ -93,7 +143,7 @@ export const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>((compone
             weekdayNames={calendar.weekdayNames}
             dayContext={dayContext}
             bounds={bounds}
-            labels={resolveLabels(EN_US_UI_LABELS.calendar, props.labels)}
+            labels={labels}
             picker={picker}
             onPreviousMonth={() => {
               picker.showDays();
@@ -114,6 +164,9 @@ export const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>((compone
               locale={locale}
               weekdayNames={calendar.weekdayNames}
               renderHeader={renderHeader}
+              // Only a host that passed `labels` gets named arrows: without
+              // them the arrows caption stays exactly as it always was.
+              labels={props.labels ? labels : undefined}
               onPreviousMonth={calendar.goToPreviousMonth}
               onNextMonth={calendar.goToNextMonth}
               dayContext={dayContext}

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

@@ -114,8 +114,11 @@ const dayCellSx = (day: DayRenderArgs, band: DayBand, visible: boolean): SxProps
   color: colorFor(day, visible),
   opacity: !day.inCurrentMonth && visible ? 0.5 : 1,
   fontWeight: day.today || isEndpoint(day) ? 'bold' : 'normal',
-  '&:nth-of-type(7n + 1)': { borderStartStartRadius: BAND_RADIUS, borderEndStartRadius: BAND_RADIUS },
-  '&:nth-of-type(7n)': { borderStartEndRadius: BAND_RADIUS, borderEndEndRadius: BAND_RADIUS },
+  // `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 },
   '&::before': {
     content: '""',
     position: 'absolute',
@@ -140,8 +143,18 @@ const dayCellSx = (day: DayRenderArgs, band: DayBand, visible: boolean): SxProps
   },
 });
 
+/**
+ * A day's spoken name, whole: "1 de outubro de 2026". The cell's text is the
+ * bare number, which a screen reader would read as "1" — in a two-month range
+ * calendar that is two different days.
+ */
+const dayName = (date: Date, locale: string): string =>
+  date.toLocaleDateString(locale, { day: 'numeric', month: 'long', year: 'numeric' });
+
 export interface CalendarDayProps {
   day: DayRenderArgs;
+  /** BCP-47 tag the day's accessible name is written in. Default: en-US. */
+  locale?: string;
   band: DayBand;
   focused: boolean;
   showOutsideDays: boolean;
@@ -153,6 +166,7 @@ export interface CalendarDayProps {
 
 export const CalendarDay: FC<CalendarDayProps> = ({
   day,
+  locale = 'en-US',
   band,
   focused,
   showOutsideDays,
@@ -164,6 +178,20 @@ export const CalendarDay: FC<CalendarDayProps> = ({
   const visible = day.inCurrentMonth || showOutsideDays;
   const state: DayState = { ...day, outside: !day.inCurrentMonth, focused };
 
+  // A day hidden by `showOutsideDays={false}` keeps its place in the grid and
+  // nothing else: no button to click in a blank, no name, no tab stop that
+  // cannot be seen (FUT-4144).
+  if (!visible) {
+    return (
+      <Box
+        component="span"
+        aria-hidden="true"
+        data-testid="calendar-outside-placeholder"
+        sx={{ width: COLUMN_SIZE, maxWidth: '100%', aspectRatio: CELL_RATIO, justifySelf: 'stretch' }}
+      />
+    );
+  }
+
   return (
     <Box
       component="button"
@@ -172,6 +200,8 @@ export const CalendarDay: FC<CalendarDayProps> = ({
       aria-selected={day.selected}
       aria-disabled={day.disabled}
       aria-current={day.today ? 'date' : undefined}
+      aria-label={dayName(day.date, locale)}
+      data-in-month={day.inCurrentMonth}
       className={dayClassNames(state, dayClassName?.(day))}
       data-testid={`calendar-date-${day.date.getDate()}`}
       onClick={() => onSelect(day.date)}
@@ -185,7 +215,7 @@ export const CalendarDay: FC<CalendarDayProps> = ({
       {day.today && (
         <Box component="span" data-testid="calendar-today" sx={{ display: 'none' }} />
       )}
-      {visible ? day.date.getDate() : ''}
+      {day.date.getDate()}
     </Box>
   );
 };