@12-apps/ui 6.90.0 → 6.92.0

package/dist/types/components/data-display/ScheduleGrid/schedule-header-host.styles.d.ts

@@ -0,0 +1,16 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+/**
+ * The header row's host figures (FUT-3882): a day's adornment under its label
+ * and the corner above the names. Their own module to keep the grid's styles
+ * under the file-size budget.
+ */
+/** A day's adornment: under its label, the column's full width, in the secondary ink unless the host says otherwise. */
+export declare const headerAdornmentSx: SxProps<Theme>;
+/**
+ * The cell above the names. It is the pinned mask over the names column (the
+ * grid's sticky rule): it must stay a stretched grid item, the header row's
+ * full height, or a day scrolled sideways shows above the names. Its words sit
+ * inside it on the days' label line (the prototype's "Movimento, 11h–23h").
+ */
+export declare const cornerSx: SxProps<Theme>;
+//# sourceMappingURL=schedule-header-host.styles.d.ts.map

package/dist/types/components/data-display/ScheduleGrid/schedule-header-host.styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-header-host.styles.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/ScheduleGrid/schedule-header-host.styles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAKpE;;;;GAIG;AAEH,wHAAwH;AACxH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,KAAK,CAK5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAO,CAAC,KAAK,CASnC,CAAC"}

package/dist/user-avatar.js

@@ -1,13 +1,13 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-BV2LOTMC.js";
+} from "./chunk-Q3SILZTQ.js";
 import "./chunk-DQ22UKMZ.js";
 import "./chunk-UDQSIRAP.js";
-import "./chunk-7YJYIMWP.js";
-import "./chunk-3ZVUNSFF.js";
+import "./chunk-4QR7LM5F.js";
 import "./chunk-EOQ6EKTS.js";
 import "./chunk-6ZZGK5DT.js";
+import "./chunk-3ZVUNSFF.js";
 import "./chunk-MTEQEPNY.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.90.0",
+  "version": "6.92.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",

package/src/components/data-display/DayRuler/DayRuler.en-US.ts

@@ -8,4 +8,5 @@ export const EN_US_DAY_RULER_LABELS: DayRulerLabels = {
   refused: "It cannot go further",
   notMovable: "This shift cannot be changed here",
   loading: "Loading the day",
+  footerMarked: "short of people",
 };

package/src/components/data-display/DayRuler/DayRuler.labels.ts

@@ -25,6 +25,8 @@ export interface DayRulerLabels {
   notMovable: string;
   /** The ruler's busy state. */
   loading: string;
+  /** Said after a group footer's marked hour when the host gives it no `title` (FUT-3882). */
+  footerMarked: string;
 }
 
 /**

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

@@ -47,6 +47,7 @@ Times are **hours from the day's midnight**, fractions included: `20.75` is 20:4
 | `now` | `number?` | The "agora" line, when on the ruler. |
 | `coverage` | `number[]?` | People per hour, index 0 = `from…from+1`. |
 | `coverageLabel` | `string?` | Beside the counts ("Na escala, por hora"). |
+| `groupFooter` | `(group) => DayRulerFooterRow[]?` | Lines under a group's rows, on the tracks' columns (FUT-3882), for the group titled `group` (`undefined` for rows with no group). A row is `{ id, label, cells }` — one `{ text, marked?, title? }` per hour from `from`, a `marked` hour drawn in the warning ink (deepened to read at 4.5:1 on the page) inside a `warning.main` outline ("O movimento pede", an hour short of people). A marked hour's `title` is also said as visually hidden text; without one, it reads "20:00 · 2 · " + `labels.footerMarked`. An unmarked hour's default title is "20:00 · 2", or just the hour when it says nothing — or `{ id, label, trend }`, one value (or `null`) per hour drawn as a line in the primary colour, the highest near the top ("Média de pedidos/hora"; the drawing is `aria-hidden` and its figures are said as visually hidden text, "11:00 4 · 12:00 6"). A row `{ id, label, note, marked? }` says a sentence across the track instead ("Pouco histórico: menos de 4 semanas com pedidos na cozinha."); `marked` draws it in the readable warning ink behind a warning bar (a shape, not colour alone) and flags it `data-marked` ("Faltam 2, 20h–22h"). Not drawn in a phone-sized pane, like the coverage row. Called for every group on each render: keep it cheap (derive the rows once, outside, and look them up). A host drawing these usually leaves out `coverage`: the same counts would show twice. |
 | `tickHours` | `number` (default 4) | An axis label every this many hours (HH:MM). |
 | `snapMinutes` | `number` (default 15) | |
 | `createHours` | `number` (default 4) | What a click alone creates. |
@@ -55,8 +56,8 @@ Times are **hours from the day's midnight**, fractions included: `20.75` is 20:4
 | `onCreate` / `onMove` / `onResize` / `onBlockClick` | see Gestures | Each is offered only when its handler is given. |
 | `loading` / `error` / `empty` | `boolean` / node / node | Skeleton rows with `aria-busy`; the host's error; the host's empty sentence. |
 | `aria-label` | `string?` | The region's name. |
-| `labels` | `Partial<DayRulerLabels>` | `createTrack(row)`, `moved(block, range)`, `resized(block, range)`, `refused`, `loading`. Default: the English pack; pt-BR: `DAY_RULER_LABELS['pt-BR']` from `@12-apps/ui/data-display/DayRuler`. |
-| `dataTestId` | `string?` (default `day-ruler`) | Parts: `-coverage`, `-axis`, `-row-${rowId}`, `-track-${rowId}`, `-block-${blockId}`, `-handle-l/-r-${blockId}`, `-break-${blockId}`, `-actual-${rowId}`, `-now`, `-preview`, `-live`, `-loading`. |
+| `labels` | `Partial<DayRulerLabels>` | `createTrack(row)`, `moved(block, range)`, `resized(block, range)`, `refused`, `loading`, `footerMarked`. Default: the English pack; pt-BR: `DAY_RULER_LABELS['pt-BR']` from `@12-apps/ui/data-display/DayRuler`. |
+| `dataTestId` | `string?` (default `day-ruler`) | Parts: `-coverage`, `-axis`, `-footer-${footerRowId}`, `-row-${rowId}`, `-track-${rowId}`, `-block-${blockId}`, `-handle-l/-r-${blockId}`, `-break-${blockId}`, `-actual-${rowId}`, `-now`, `-preview`, `-live`, `-loading`. |
 
 Tones are `ScheduleGrid`'s; on the ruler a `plan` block is a dashed outline over a faint ground.
 

package/src/components/data-display/DayRuler/DayRuler.parts.tsx

@@ -7,6 +7,7 @@ import type { RulerAbilities, RulerScale } from './DayRuler.keyboard';
 import { DAY_RULER_METRICS as M } from './DayRuler.metrics';
 import { useTextFits } from './useTextFits';
 import { formatHour, formatRange, percentOf, ticksOf } from './day-ruler-model';
+import { SR_ONLY_SX } from '../ScheduleGrid/ScheduleGrid.styles';
 import {
   actionsSx,
   actualLabelSx,
@@ -17,15 +18,18 @@ import {
   coverageCellSx,
   coverageLabelSx,
   coverageSx,
+  footerCellSx,
+  footerNoteSx,
   handleSx,
   lineSx,
   nowSx,
   rowSx,
   trackSx,
+  trendSx,
   whoSx,
   type Span,
 } from './DayRuler.styles';
-import type { DayRulerBlock, DayRulerRow, RulerHour } from './DayRuler.types';
+import type { DayRulerBlock, DayRulerFooterCell, DayRulerFooterRow, DayRulerRow, RulerHour } from './DayRuler.types';
 import type { RulerDrag, RulerDragApi } from './useRulerDrag';
 
 export const spanOf = (start: RulerHour, end: RulerHour, scale: RulerScale): Span => {
@@ -254,6 +258,121 @@ export function Coverage(props: { coverage: readonly number[]; label?: string; s
   );
 }
 
+/** The points of a trend over the hours' centres, in a 100 × 40 box: the highest value near the top, `null` breaks nothing (it is skipped). */
+export function trendPoints(values: readonly (number | null)[], hours: number): string {
+  const present = values.slice(0, hours).filter((value): value is number => value !== null);
+  const max = Math.max(0, ...present);
+  return values
+    .slice(0, hours)
+    .flatMap((value, index) => {
+      if (value === null) return [];
+      const x = ((index + 0.5) * 100) / hours;
+      const y = max > 0 ? 38 - (value / max) * 34 : 38;
+      return [`${x.toFixed(2)},${y.toFixed(2)}`];
+    })
+    .join(' ');
+}
+
+/** One hour's default words: "20:00 · 4"; just the hour when it says nothing. */
+const hourWords = (hour: RulerHour, text: string): string => (text ? `${formatHour(hour)} · ${text}` : formatHour(hour));
+
+/** What a reader hears for a marked hour: the host's `title`, else the hour, its count and that it is short. */
+function markedWords(cell: DayRulerFooterCell, hour: RulerHour, marked: string): string {
+  return cell.title ?? `${hourWords(hour, cell.text)} · ${marked}`;
+}
+
+interface FooterContext {
+  hours: number;
+  from: RulerHour;
+  /** `labels.footerMarked`. */
+  marked: string;
+}
+
+function FooterCells({ cells, ctx }: { cells: readonly DayRulerFooterCell[]; ctx: FooterContext }): React.JSX.Element {
+  return (
+    <Box sx={coverageSx(ctx.hours)}>
+      {Array.from({ length: ctx.hours }, (_, index) => {
+        const cell = cells[index] ?? { text: '' };
+        const hour = ctx.from + index;
+        return (
+          <Box
+            key={index}
+            component="span"
+            sx={footerCellSx(Boolean(cell.marked))}
+            title={cell.marked ? markedWords(cell, hour, ctx.marked) : (cell.title ?? hourWords(hour, cell.text))}
+            data-marked={cell.marked ? '' : undefined}
+          >
+            {/* A marked hour is said in words too, not only by its outline and a tooltip touch never shows. */}
+            {cell.marked ? (
+              <>
+                <span aria-hidden>{cell.text}</span>
+                <Box component="span" sx={SR_ONLY_SX}>
+                  {markedWords(cell, hour, ctx.marked)}
+                </Box>
+              </>
+            ) : (
+              cell.text
+            )}
+          </Box>
+        );
+      })}
+    </Box>
+  );
+}
+
+/** A trend's figures in words, for the reader the drawn line does not reach: "11:00 4 · 12:00 6". */
+function trendWords(values: readonly (number | null)[], ctx: FooterContext): string {
+  return values
+    .slice(0, ctx.hours)
+    .flatMap((value, index) => (value === null ? [] : [`${formatHour(ctx.from + index)} ${Math.round(value * 10) / 10}`]))
+    .join(' · ');
+}
+
+function FooterFigures({ row, ctx }: { row: DayRulerFooterRow; ctx: FooterContext }): React.JSX.Element {
+  if (row.trend) {
+    return (
+      <Box component="span" sx={{ display: 'block', minWidth: 0 }}>
+        <Box component="svg" viewBox="0 0 100 40" preserveAspectRatio="none" sx={trendSx} aria-hidden>
+          <polyline fill="none" stroke="currentColor" strokeWidth={1.5} vectorEffect="non-scaling-stroke" points={trendPoints(row.trend, ctx.hours)} />
+        </Box>
+        <Box component="span" sx={SR_ONLY_SX}>
+          {trendWords(row.trend, ctx)}
+        </Box>
+      </Box>
+    );
+  }
+  if (row.note !== undefined) {
+    return (
+      <Box component="span" sx={footerNoteSx(Boolean(row.marked))} data-marked={row.marked ? '' : undefined}>
+        {row.note}
+      </Box>
+    );
+  }
+  return <FooterCells cells={row.cells ?? []} ctx={ctx} />;
+}
+
+/**
+ * A group's lines under its rows (FUT-3882): counts per hour, a trend, or a
+ * sentence, on the tracks' columns. `marked` is `labels.footerMarked`.
+ */
+export function GroupFooter(props: { rows: readonly DayRulerFooterRow[]; scale: RulerScale; testId: string; marked: string }): React.JSX.Element {
+  const { rows, scale, testId } = props;
+  const ctx: FooterContext = { hours: scale.to - scale.from, from: scale.from, marked: props.marked };
+  return (
+    <>
+      {rows.map((row) => (
+        <Box key={row.id} sx={lineSx} data-testid={`${testId}-footer-${row.id}`}>
+          <Box component="span" sx={coverageLabelSx}>
+            {row.label}
+          </Box>
+          <FooterFigures row={row} ctx={ctx} />
+          <span />
+        </Box>
+      ))}
+    </>
+  );
+}
+
 /** The hour labels under the coverage row. */
 export function Axis({ scale, testId }: { scale: RulerScale; testId: string }): React.JSX.Element {
   return (

package/src/components/data-display/DayRuler/DayRuler.pt-BR.ts

@@ -8,4 +8,5 @@ export const PT_BR_DAY_RULER_LABELS: DayRulerLabels = {
   refused: "Não dá para ir além",
   notMovable: "Este turno não muda por aqui",
   loading: "Carregando o dia",
+  footerMarked: "falta gente",
 };

package/src/components/data-display/DayRuler/DayRuler.styles.ts

@@ -2,7 +2,7 @@ import { alpha, type CSSObject, type SxProps, type Theme } from '@mui/material/s
 
 import { FIELD_BORDER_WIDTH } from '../../../tokens/field-height.core';
 import { rem, sxRem } from '../../../tokens/relative';
-import { actualBarColor, blockToneStyles, breakHatch } from '../ScheduleGrid/schedule-tones';
+import { actualBarColor, blockToneStyles, breakHatch, signalInk } from '../ScheduleGrid/schedule-tones';
 import type { ScheduleBlockTone } from '../ScheduleGrid/ScheduleGrid.types';
 import { DAY_RULER_METRICS as M } from './DayRuler.metrics';
 
@@ -301,3 +301,52 @@ export const skeletonNameSx: SxProps<Theme> = (theme: Theme) => ({
   borderRadius: rem(theme, M.skeletonNameRadius),
   backgroundColor: theme.palette.action.hover,
 });
+
+/**
+ * A marked footer's words (FUT-3882): the warning ink deepened until it reads
+ * at 4.5:1 on the page — `warning.main` is 3.1:1 on white. The outline keeps
+ * `warning.main`: a non-text mark needs 3:1.
+ */
+export function footerInk(theme: Theme, marked: boolean, plain: string): string {
+  return marked ? signalInk(theme, 'warning', theme.palette.background.default) : plain;
+}
+
+/** A group's count line (FUT-3882): plain counts on the hours' columns, a marked hour outlined in the warning ink. */
+export function footerCellSx(marked: boolean): SxProps<Theme> {
+  return (theme: Theme) => ({
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    fontSize: rem(theme, M.coverage.font),
+    borderRadius: rem(theme, M.coverage.radius),
+    color: footerInk(theme, marked, theme.palette.text.primary),
+    fontWeight: marked ? 500 : 400,
+    // The hairline is always there, transparent when unmarked, so a mark never shifts a count.
+    border: `1px solid ${marked ? theme.palette.warning.main : 'transparent'}`,
+    minWidth: 0,
+    overflow: 'hidden',
+  });
+}
+
+/**
+ * A footer line's sentence; when the host marks it ("Faltam 2, 20h–22h"), in
+ * the readable warning ink with a warning bar before it — a shape, so colour
+ * is never the only signal.
+ */
+export function footerNoteSx(marked: boolean): SxProps<Theme> {
+  return (theme: Theme) => ({
+    fontSize: rem(theme, M.meta),
+    color: footerInk(theme, marked, theme.palette.text.secondary),
+    fontWeight: marked ? 500 : 400,
+    ...(marked ? { borderLeft: `${rem(theme, 3)} solid ${theme.palette.warning.main}`, paddingLeft: rem(theme, 6) } : {}),
+  });
+}
+
+/** A group's trend line: as tall as the coverage row, drawn in the primary colour. */
+export const trendSx: SxProps<Theme> = (theme: Theme) => ({
+  display: 'block',
+  width: '100%',
+  height: rem(theme, M.coverage.height + M.coverage.height / 2),
+  color: theme.palette.primary.main,
+  overflow: 'visible',
+});

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

@@ -9,7 +9,7 @@ import { useAnnouncer } from '../ScheduleGrid/useAnnouncer';
 import { handleBlockKey, keyCreateSpan, type RulerAbilities, type RulerScale } from './DayRuler.keyboard';
 import { EN_US_DAY_RULER_LABELS } from './DayRuler.en-US';
 import { DAY_RULER_METRICS as M } from './DayRuler.metrics';
-import { Axis, Coverage, RulerRow, type RowContext } from './DayRuler.parts';
+import { Axis, Coverage, GroupFooter, RulerRow, type RowContext } from './DayRuler.parts';
 import { groupTitleSx, rootSx, rowSx, skeletonNameSx, skeletonTrackSx } from './DayRuler.styles';
 import type { DayRulerProps, DayRulerRow } from './DayRuler.types';
 import { useRulerDrag } from './useRulerDrag';
@@ -40,6 +40,14 @@ function abilitiesOf(props: DayRulerProps): RulerAbilities {
   return { create: open && Boolean(props.onCreate), move: open && Boolean(props.onMove), resize: open && Boolean(props.onResize) };
 }
 
+/** A group's lines under its rows, when the host gives any (`groupFooter`). */
+function FooterOf({ props, group, ctx }: { props: DayRulerProps; group: string | undefined; ctx: RowContext }): React.JSX.Element | null {
+  const rows = props.groupFooter?.(group);
+  if (!rows || rows.length === 0) return null;
+  const marked = props.labels?.footerMarked ?? EN_US_DAY_RULER_LABELS.footerMarked;
+  return <GroupFooter rows={rows} scale={ctx.scale} testId={ctx.testId} marked={marked} />;
+}
+
 /** The groups and their rows — or the skeleton, the host's error, or the host's empty state. */
 function RulerBody({ props, ctx }: { props: DayRulerProps; ctx: RowContext }): React.JSX.Element {
   if (props.error) return <>{props.error}</>;
@@ -68,6 +76,7 @@ function RulerBody({ props, ctx }: { props: DayRulerProps; ctx: RowContext }): R
           {group.rows.map((row) => (
             <RulerRow key={row.id} row={row} ctx={ctx} />
           ))}
+          <FooterOf props={props} group={group.title} ctx={ctx} />
         </Box>
       ))}
     </>

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

@@ -66,6 +66,29 @@ export interface DayRulerRow {
   labelAccessible?: string;
 }
 
+/** One hour of a group's count line: what it says, and whether the host marks it (an hour short of people). */
+export interface DayRulerFooterCell {
+  /** What the hour says ("4", "—"). Empty draws nothing. */
+  text: string;
+  /** Drawn in the warning ink inside a warning outline. Never the only signal: say it in `title` too. */
+  marked?: boolean;
+  /** The hour's tooltip and accessible words ("20h · o movimento pede 4, a escala tem 2"). Default: the hour and `text`. */
+  title?: string;
+}
+
+/**
+ * A line under a group's rows, on the tracks' columns (FUT-3882): one count
+ * per hour (`cells`, index 0 = `from…from+1`) — "Na escala, por hora",
+ * "O movimento pede" —, a trend drawn as a line (`trend`, one value per hour,
+ * `null` for none) — "Média de pedidos/hora" —, or a sentence across the
+ * track where the figures would be (`note`) — "Pouco histórico: …", or,
+ * `marked`, in the warning ink: "Faltam 2, 20h–22h".
+ */
+export type DayRulerFooterRow =
+  | { id: string; label: string; cells: readonly DayRulerFooterCell[]; trend?: undefined; note?: undefined }
+  | { id: string; label: string; trend: readonly (number | null)[]; cells?: undefined; note?: undefined }
+  | { id: string; label: string; note: string; marked?: boolean; cells?: undefined; trend?: undefined };
+
 export interface DayRulerProps {
   rows: readonly DayRulerRow[];
   /** The ruler's first hour (default 6, 06:00). */
@@ -78,6 +101,12 @@ export interface DayRulerProps {
   coverage?: readonly number[];
   /** Beside the coverage row ("Na escala, por hora"). */
   coverageLabel?: string;
+  /**
+   * Lines under a group's rows, on the tracks' columns, for the group titled
+   * `group` (`undefined` for rows with no group). Like the coverage row they
+   * are not drawn in a phone-sized pane, where the host says it its own way.
+   */
+  groupFooter?: (group: string | undefined) => readonly DayRulerFooterRow[] | undefined;
   /** An axis label every this many hours (default 4). */
   tickHours?: number;
   /** Every gesture snaps to this (default 15 minutes). */
@@ -99,7 +128,7 @@ export interface DayRulerProps {
   /** The component's own words. Default: the English pack. */
   labels?: Partial<DayRulerLabels>;
   /**
-   * Base test id (default `day-ruler`). Parts: `-coverage`, `-axis`, `-row-${rowId}`,
+   * Base test id (default `day-ruler`). Parts: `-coverage`, `-axis`, `-footer-${footerRowId}`, `-row-${rowId}`,
    * `-track-${rowId}`, `-block-${blockId}`, `-handle-l-${blockId}`, `-handle-r-${blockId}`, `-break-${blockId}`,
    * `-actual-${rowId}`, `-now`, `-preview`, `-live`, `-loading`.
    */

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

@@ -2,6 +2,8 @@ export { DayRuler } from './DayRuler';
 export type {
   DayRulerActual,
   DayRulerBlock,
+  DayRulerFooterCell,
+  DayRulerFooterRow,
   DayRulerProps,
   DayRulerRow,
   RulerHour,

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.