@12-apps/ui 6.22.0 → 6.23.0

package/src/components/data-display/FleetMap/FleetCanvas.tsx

@@ -0,0 +1,80 @@
+import Box from '@mui/material/Box/index.js';
+import React from 'react';
+
+import { MapPreview } from '../MapPreview/MapPreview';
+
+import type { FleetMarker } from './FleetMap.hooks';
+import type { LatLng } from './FleetMap.helpers';
+import type { FleetMapCopy } from './FleetMap.types';
+
+export interface FleetCanvasProps {
+  copy: FleetMapCopy;
+  /** Where to point. `null` renders NOTHING — see the component's note. */
+  centre: LatLng | null;
+  markers: FleetMarker[];
+  height: string;
+  testId: string;
+}
+
+/**
+ * The map half — a NAMED LANDMARK, not an `aria-hidden` one.
+ *
+ * Its controls are focusable, and `aria-hidden` over a focusable subtree is the
+ * `aria-hidden-focus` violation: a keyboard user tabs into something a screen
+ * reader insists is not there. `role="region"` with a name is what puts it in a
+ * screen reader's landmark rotor, so it can be jumped PAST in one gesture;
+ * `role="group"` is not a landmark and would not.
+ *
+ * ## Skipping it does not silence it, and that is not ours to fix here
+ *
+ * `MapPreview` puts `aria-live="polite"` on its own root, with an English
+ * `aria-label` naming the centre coordinates and zoom. So re-centring the map —
+ * which every selection change does — announces something like "Map preview
+ * centered at -23.5505, -46.6333 with zoom level 15", in English, however
+ * thoroughly a reader has skipped the landmark. Two things follow, and neither
+ * is solved by anything this file can do:
+ *
+ *   * a live region announces from wherever the reader is, so the landmark's
+ *     skippability does not suppress it;
+ *   * that string is the one piece of user-facing text in this component that
+ *     does NOT come through `copy`.
+ *
+ * Fixing it means changing `MapPreview`, which every other consumer shares, so
+ * it is stated here rather than quietly claimed away.
+ *
+ * ## No centre, no map
+ *
+ * `mapCentre` answers `null` rather than a coordinate for an empty fleet, and
+ * that refusal has to survive the whole way down. `MapPreview` has no default
+ * centre — it resolves `center || coordinates || { lat: 0, lng: 0 }` — so
+ * forwarding `undefined` sails the map to the Gulf of Guinea and prints
+ * `Lat: 0.000000` under a default pin. That is exactly the render the helper
+ * exists to prevent, and it is reachable: a board that is `loading` with
+ * nothing yet reported skips the empty state by design and lands here.
+ */
+export function FleetCanvas({
+  copy,
+  centre,
+  markers,
+  height,
+  testId,
+}: FleetCanvasProps): React.JSX.Element | null {
+  if (!centre) return null;
+  return (
+    <Box
+      role="region"
+      aria-label={copy.mapLabel}
+      data-testid={`${testId}-canvas`}
+      sx={{ flexGrow: 1, minWidth: 0 }}
+    >
+      <MapPreview
+        copy={copy.map}
+        center={centre}
+        markers={markers}
+        height={height}
+        interactive
+        showControls
+      />
+    </Box>
+  );
+}

package/src/components/data-display/FleetMap/FleetMap.fixtures.ts

@@ -0,0 +1,70 @@
+import { EN_US_MAP_PREVIEW_COPY } from '../../../en-US.data-display';
+
+import type { FleetMapCopy, FleetUnit } from './FleetMap.types';
+
+/**
+ * The copy and the fleet every story and test story shares.
+ *
+ * A module rather than a per-story literal, so a change to the shape breaks in
+ * ONE place rather than in fourteen — and so the test stories assert against
+ * the same words the visual ones render.
+ */
+
+/** English, because stories are developer-facing. A consumer passes its own. */
+export const FLEET_COPY: FleetMapCopy = {
+  title: 'Couriers on the road',
+  emptyTitle: 'Nobody is reporting',
+  emptyDescription: 'A courier appears here once their phone sends its first position.',
+  rosterLabel: 'Couriers, freshest first',
+  mapLabel: 'Map of where the couriers are',
+  freshness: { live: 'Live', lagging: 'Lagging', stale: 'Stale' },
+  lastSeen: (seconds) =>
+    seconds < 60 ? `${seconds}s ago` : `${Math.floor(seconds / 60)} min ago`,
+  // A NON-BREAKING space between the number and its unit. The meta line is
+  // the narrowest text in the component and it wraps at spaces, so a plain
+  // space orphans the `m` onto a line of its own — measured at 900px and
+  // 1920px, where the roster column is at its tightest relative to the map.
+  // Consumers writing their own `accuracy` want the same character.
+  accuracy: (metres) => `±${Math.round(metres)}\u00A0m`,
+  map: EN_US_MAP_PREVIEW_COPY,
+};
+
+/**
+ * Three riders around São Paulo, one in each freshness state.
+ *
+ * Deliberately NOT in staleness order, and the labels deliberately do not agree
+ * with it either. `rosterOrder` sorts on staleness and breaks ties on the
+ * label, so a fixture whose two orders coincide lets the roster's ordering
+ * assertion pass against a LABEL-only sort as readily as the real one — a test
+ * reporting coverage it does not have. Here the three orders are all different:
+ * declared is [ale, ana, bruno], alphabetical is the same, and the correct
+ * answer is [ana, bruno, ale].
+ */
+export const FLEET: FleetUnit[] = [
+  {
+    id: 'ale',
+    label: 'Alessandra Nunes',
+    latitude: -23.5405,
+    longitude: -46.6133,
+    accuracyM: null,
+    staleSeconds: 640,
+  },
+  {
+    id: 'ana',
+    label: 'Ana Ribeiro',
+    latitude: -23.5505,
+    longitude: -46.6333,
+    accuracyM: 12,
+    staleSeconds: 8,
+    badge: '2 deliveries',
+  },
+  {
+    id: 'bruno',
+    label: 'Bruno Alves',
+    latitude: -23.5605,
+    longitude: -46.6533,
+    accuracyM: 180,
+    staleSeconds: 140,
+    badge: '1 delivery',
+  },
+];

package/src/components/data-display/FleetMap/FleetMap.helpers.ts

@@ -0,0 +1,85 @@
+import type { FleetFreshness, FleetUnit } from './FleetMap.types';
+
+/**
+ * How current a fix is, on the two thresholds the caller supplied.
+ *
+ * Inclusive at both boundaries in the direction that reads better on a screen:
+ * a unit exactly at the lagging threshold is already lagging. A boundary has to
+ * fall somewhere, and the conservative side is the one that does not tell a
+ * dispatcher somebody is live when they are on the edge of not being.
+ */
+export function freshnessOf(
+  staleSeconds: number,
+  laggingAfterSeconds: number,
+  staleAfterSeconds: number,
+): FleetFreshness {
+  if (staleSeconds >= staleAfterSeconds) return 'stale';
+  if (staleSeconds >= laggingAfterSeconds) return 'lagging';
+  return 'live';
+}
+
+/** A latitude/longitude pair, as the map wants its centre. */
+export interface LatLng {
+  lat: number;
+  lng: number;
+}
+
+/**
+ * Where the map should point.
+ *
+ * The selected unit when there is one — a dispatcher who clicked a name is
+ * asking to look at them. Otherwise the fleet's own centroid, which keeps
+ * everybody in frame without the caller having to compute a bounding box.
+ *
+ * `null` for an empty fleet rather than a coordinate: (0, 0) is a real place in
+ * the Atlantic, and a map that quietly sails there is worse than one that says
+ * it has nothing to show.
+ */
+export function mapCentre(
+  units: readonly FleetUnit[],
+  selectedId?: string | null,
+): LatLng | null {
+  if (units.length === 0) return null;
+  const selected = selectedId ? units.find((unit) => unit.id === selectedId) : undefined;
+  if (selected) return { lat: selected.latitude, lng: selected.longitude };
+  const sum = units.reduce(
+    (acc, unit) => ({ lat: acc.lat + unit.latitude, lng: acc.lng + unit.longitude }),
+    { lat: 0, lng: 0 },
+  );
+  return { lat: sum.lat / units.length, lng: sum.lng / units.length };
+}
+
+/**
+ * The roster's order: freshest first, then alphabetically.
+ *
+ * Not the caller's order, deliberately. The one question this panel answers is
+ * *who is moving right now*, and a list sorted by anything else buries the
+ * answer under whoever happens to sort first. Ties break on the label so the
+ * list does not reshuffle between polls when two units share a staleness.
+ */
+export function rosterOrder(units: readonly FleetUnit[]): FleetUnit[] {
+  return [...units].sort(
+    (a, b) => a.staleSeconds - b.staleSeconds || a.label.localeCompare(b.label),
+  );
+}
+
+/**
+ * Move the selection by one row, wrapping at both ends.
+ *
+ * Wrapping rather than stopping: this is a short list a dispatcher arrows
+ * through repeatedly, and a selection that sticks at the last row makes the
+ * keyboard path feel broken next to the mouse one.
+ */
+export function nextSelection(
+  units: readonly FleetUnit[],
+  currentId: string | null | undefined,
+  step: 1 | -1,
+): string | null {
+  if (units.length === 0) return null;
+  const index = units.findIndex((unit) => unit.id === currentId);
+  // Nothing selected: Down opens at the top and Up opens at the bottom, which
+  // is what every listbox in the house does.
+  if (index === -1) return (step === 1 ? units[0] : units[units.length - 1])?.id ?? null;
+  const next = (index + step + units.length) % units.length;
+  return units[next]?.id ?? null;
+}

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

@@ -0,0 +1,164 @@
+import React from 'react';
+
+import { mapCentre, nextSelection, rosterOrder, type LatLng } from './FleetMap.helpers';
+import type { FleetUnit } from './FleetMap.types';
+
+/**
+ * Everything the board derives from its props, in one hook.
+ *
+ * Split out of the component so the component is layout and nothing else.
+ *
+ * The memos are honest about what they buy, which is less than it looks. `units`
+ * arrives as a fresh array on every poll, so `ordered` and `markers` are
+ * recomputed on every poll whatever these do — a new array is a new identity.
+ * What they buy is stability across the renders a poll does NOT cause: a parent
+ * re-render, a selection change (which re-runs `centre` but not `ordered`), a
+ * theme flip. Sorting a fleet is cheap either way; this is tidiness, not a
+ * measured win, and it should not be read as one.
+ *
+ * `centre` is the exception, and there it is load-bearing rather than tidy —
+ * see {@link useFleetMap}.
+ *
+ * ## Selection works with, without, or half-way through a handler
+ *
+ * `selectedId` and `onSelect` are both optional, so all four combinations
+ * arrive. Left purely controlled, the two useful ones broke: with neither prop
+ * the roster was a listbox that answered nothing, and arrowing it called
+ * `preventDefault` before a no-op `select`, so the keys did not move a
+ * selection AND did not scroll the page either.
+ *
+ * So the hook keeps its own selection and defers to `selectedId` only when the
+ * caller passes one — the ordinary controlled/uncontrolled split, the same one
+ * an `<input>` makes. `onSelect` still fires either way, so a consumer can
+ * observe the selection without owning it.
+ */
+
+/** One pin, in the shape `MapPreview` takes. */
+export interface FleetMarker {
+  position: LatLng;
+  title: string;
+  onClick: () => void;
+}
+
+export interface FleetMapState {
+  /** The units, freshest first — see {@link rosterOrder}. */
+  ordered: FleetUnit[];
+  /**
+   * The selection in force — the caller's when they own it, this hook's when
+   * they do not. Everything downstream reads THIS and never the raw prop.
+   */
+  active: string | null;
+  /** Where the map points, or `null` when there is nothing to show. */
+  centre: LatLng | null;
+  select: (id: string) => void;
+  markers: FleetMarker[];
+  onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+}
+
+/** Which way an arrow moves the selection, or `0` when it is not ours. */
+function stepFor(event: React.KeyboardEvent<HTMLDivElement>): 1 | -1 | 0 {
+  // A modified arrow is the PAGE's shortcut, not the roster's: Cmd+Down is
+  // "scroll to the end of the document" on macOS, and Shift+Arrow extends a
+  // selection. Capturing them would take a browser gesture away.
+  if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return 0;
+  if (event.key === 'ArrowDown') return 1;
+  if (event.key === 'ArrowUp') return -1;
+  return 0;
+}
+
+/**
+ * Who owns the selection, decided ONCE on the first render.
+ *
+ * Exactly as React decides it for an `<input>`, and for the same reason.
+ * `selectedId` is typed `string | null | undefined`, so `useState<string>()` —
+ * the natural shape for a caller — hands us `undefined` on the first render and
+ * again on every reset. Re-deriving the mode from the prop each time would make
+ * the component change its own semantics mid-life: it starts uncontrolled,
+ * silently becomes controlled the moment the caller's `onSelect` writes a value
+ * back, and then silently un-becomes it when they clear — resurrecting whatever
+ * was selected before the hand-off.
+ *
+ * Latched, `undefined` is unambiguous within each mode: to a controlled board it
+ * is "nobody is selected", so clearing the caller's state clears the roster; to
+ * an uncontrolled one it is simply the prop staying absent. A caller who wants
+ * control passes `string | null` from the first render.
+ */
+function useSelection(
+  selectedId: string | null | undefined,
+  onSelect: ((id: string) => void) | undefined,
+): { active: string | null; select: (id: string) => void; controlled: boolean } {
+  const controlledRef = React.useRef(selectedId !== undefined);
+  const controlled = controlledRef.current;
+  const [own, setOwn] = React.useState<string | null>(null);
+
+  const select = React.useCallback(
+    (id: string) => {
+      if (!controlled) setOwn(id);
+      onSelect?.(id);
+    },
+    [controlled, onSelect],
+  );
+
+  return { active: controlled ? (selectedId ?? null) : own, select, controlled };
+}
+
+export function useFleetMap(
+  units: readonly FleetUnit[],
+  selectedId: string | null | undefined,
+  onSelect: ((id: string) => void) | undefined,
+): FleetMapState {
+  const ordered = React.useMemo(() => rosterOrder(units), [units]);
+  const { active, select, controlled } = useSelection(selectedId, onSelect);
+
+  // Memoised on the COORDINATES and not the object, because `mapCentre` builds
+  // a fresh literal every call and `MapPreview` re-centres from an effect keyed
+  // on `center`'s identity. A poll that changes nothing would otherwise hand it
+  // a new object, and the map would jump back to the centroid — throwing away a
+  // pan the dispatcher had just made, on a timer, for as long as they watch it.
+  //
+  // ROUNDED, because keying on the raw numbers was not enough. `mapCentre`
+  // sums over `ordered`, and floating-point addition is not associative — so
+  // re-sorting the SAME coordinates can change the centroid's last bit.
+  // `rosterOrder` sorts on `staleSeconds`, which moves on every poll, so rank
+  // swaps are the ordinary case for a fleet that is standing still: measured
+  // over 20k random three-rider fleets, a single adjacent swap changed the
+  // centroid 17% of the time. Six decimals is ~11cm, far finer than a map
+  // centre resolves and far coarser than the noise.
+  const raw = mapCentre(ordered, active);
+  const lat = raw === null ? null : Math.round(raw.lat * 1e6) / 1e6;
+  const lng = raw === null ? null : Math.round(raw.lng * 1e6) / 1e6;
+  const centre = React.useMemo(
+    () => (lat === null || lng === null ? null : { lat, lng }),
+    [lat, lng],
+  );
+
+  const onKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      const step = stepFor(event);
+      if (step === 0) return;
+      // Nothing can move a CONTROLLED selection without a handler, so the keys
+      // belong to the page. Swallowing them there left a keyboard user unable to
+      // move the selection and unable to scroll past the roster.
+      if (controlled && !onSelect) return;
+      const next = nextSelection(ordered, active, step);
+      // `preventDefault` only once a move is certain, so the page still scrolls
+      // with the arrow keys when the list is empty and there is nothing to move.
+      if (next === null) return;
+      event.preventDefault();
+      select(next);
+    },
+    [ordered, active, select, controlled, onSelect],
+  );
+
+  const markers = React.useMemo(
+    () =>
+      ordered.map((unit) => ({
+        position: { lat: unit.latitude, lng: unit.longitude },
+        title: unit.label,
+        onClick: () => select(unit.id),
+      })),
+    [ordered, select],
+  );
+
+  return { ordered, active, centre, select, markers, onKeyDown };
+}

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

@@ -0,0 +1,182 @@
+# FleetMap
+
+Where a set of tracked units is **right now**: a map beside the roster that
+reads it.
+
+Product-free by construction. It draws labelled dots with a freshness state, and
+every word — the heading, the three freshness names, how a duration and a
+distance are written — arrives through `copy`. Couriers on motorbikes, service
+vans and field engineers are all the same picture.
+
+## Use cases
+
+- A dispatcher watching a delivery fleet during a shift.
+- A field-service board showing which engineers are moving and which have gone
+  quiet.
+- Any "where is everybody" panel where the answer is a small set of named people
+  with a last-known position and a staleness.
+
+## Three decisions that shape the API
+
+### The roster is the accessible representation, not a sidebar
+
+A map is a picture, and a screen reader cannot read one. So the list carries the
+information: everything a sighted user takes from a pin — who, how recently,
+what they are carrying — is on the row, and the row's freshness is spelled out
+in words rather than carried by the dot's colour.
+
+The map is a **named landmark** (`role="region"` with a label) rather than an
+`aria-hidden` one. Its controls are focusable, and `aria-hidden` over a
+focusable subtree is the `aria-hidden-focus` violation: a keyboard user tabs
+into a region a screen reader insists is not there. The landmark role is what
+puts it in the rotor, so a reader can skip past it in one gesture.
+
+When there is no centre to point at — a fleet that is still loading and has
+reported nothing — the map renders **nothing** rather than falling back to
+`0, 0`, which is a real place in the Gulf of Guinea.
+
+### Nothing here formats
+
+`copy.lastSeen` and `copy.accuracy` are **functions**, not strings. A duration
+and a distance are locale rules, and the same line `StatCard` holds for its
+`value` applies: a component that wrote `"2 min ago"` would have made English
+the only language it could ever render, and a `lastSeenTemplate` string would
+have fixed the shape as well as the words.
+
+### An empty fleet is an empty STATE, never an empty map
+
+A map with no pins is indistinguishable from a map that failed to load, and
+telling those two apart is the entire question a dispatcher is asking.
+
+## Props
+
+| prop | type | default | what it does |
+|---|---|---|---|
+| `units` | `readonly FleetUnit[]` | — | everyone currently reporting; empty renders the empty state |
+| `copy` | `FleetMapCopy` | — | every word, plus the two formatters |
+| `selectedId` | `string \| null` | — | pass it to CONTROL the selection; omit it and the component keeps its own |
+| `onSelect` | `(id: string) => void` | — | a click on a row or a pin, and each arrow-key move |
+| `laggingAfterSeconds` | `number` | `90` | when a unit stops reading as `live` |
+| `staleAfterSeconds` | `number` | `300` | when it stops reading as `lagging` |
+| `height` | `string` | `'420px'` | the map's height, any CSS length |
+| `loading` | `boolean` | `false` | skeletons only before the first units land; `aria-busy` either way |
+| `className` | `string` | — | on the panel root |
+| `dataTestId` | `string` | `'fleet-map'` | every child TEST id derives from it; DOM ids are generated |
+
+### `FleetUnit`
+
+```ts
+{
+  id: string;
+  label: string;            // the name on the pin and the row
+  latitude: number;
+  longitude: number;
+  accuracyM?: number | null; // metres; a row with none renders none
+  staleSeconds: number;      // since the fix was ACCEPTED, on the SERVER's clock
+  badge?: string;            // pre-formatted, e.g. "2 deliveries"
+}
+```
+
+`staleSeconds` is measured against the **server's** clock, and the caller
+computes it. The distinction is not pedantry: a device whose own clock is an
+hour slow would otherwise report itself as an hour absent while reporting
+perfectly.
+
+## Why the thresholds have no domain default
+
+They are props because the answer belongs entirely to the fleet's own ping
+cadence. A phone reporting every twenty seconds is late at ninety; a tracker
+reporting every five minutes is not. The defaults are sized for the first case
+and are a starting point, not a rule — a component that picked one would be
+picking it for every consumer.
+
+## Usage
+
+```tsx
+<FleetMap
+  units={couriers}
+  copy={{
+    title: 'Motoboys na rua',
+    emptyTitle: 'Ninguém reportando',
+    emptyDescription: 'Um motoboy aparece aqui quando o celular envia a primeira posição.',
+    rosterLabel: 'Motoboys, mais recentes primeiro',
+    mapLabel: 'Mapa de onde os motoboys estão',
+    freshness: { live: 'Ao vivo', lagging: 'Atrasado', stale: 'Sem sinal' },
+    lastSeen: (s) => (s < 60 ? `há ${s}s` : `há ${Math.floor(s / 60)} min`),
+    accuracy: (m) => `±${Math.round(m)} m`,
+    map: PT_BR_MAP_PREVIEW_COPY,
+  }}
+  selectedId={selected}
+  onSelect={setSelected}
+/>
+```
+
+## Accessibility
+
+- The panel is a `region` labelled by its heading.
+- The roster is a `listbox` with `option` rows, **one tab stop**, arrow keys
+  moving the selection and wrapping at both ends, and
+  `aria-activedescendant` naming the selected row.
+- Freshness is stated in words on every row; the coloured dot is `aria-hidden`
+  so the state is not read twice, and colour is never the only carrier.
+- The map region is a named landmark rather than hidden — see above.
+- The active option is kept in view as the selection moves, so a keyboard user
+  is not walking it below the fold unseen. The ROSTER's own container is
+  scrolled, never the page: `scrollIntoView` walks every scrollable ancestor
+  including the document, which would drag a dispatcher back to this panel on
+  every poll.
+- `aria-activedescendant` is emitted only when the selected id names a row that
+  is actually rendered: a controlled selection can outlive the unit it names.
+- The active option's scroll effect also watches its POSITION, because the
+  roster re-sorts on every poll and a still-selected row can move under it.
+- While `loading`, the MAP AND ROSTER are marked `aria-busy` and the heading
+  stays, so the layout does not reflow when the data lands. The panel root is
+  deliberately not the busy element: `aria-busy` tells assistive tech to hold
+  back changes inside it, and the announcement region is a SIBLING of the busy
+  half rather than a descendant of it.
+- `aria-busy` is a state and utters nothing, so set `copy.loading` if the reload
+  should be ANNOUNCED — that string goes into a visually hidden `role="status"`.
+  Left unset, the reload is silent. The region is mounted as soon as
+  `copy.loading` is given and only its TEXT changes, because a screen reader
+  watches an existing region rather than announcing one that arrives already
+  populated. That covers a board that starts idle and reloads; a board MOUNTED
+  already loading is silent, as any live region is at mount.
+- Skeletons replace the roster only while there are no units yet. A poll that
+  refreshes a populated list keeps the listbox mounted, because unmounting it
+  throws away the focus inside it.
+- The map is a named landmark, so a reader can jump past it — but it is not
+  silent. `MapPreview` carries its own `aria-live="polite"` and announces its
+  centre coordinates, in English, on every re-centre. That string is the one
+  piece of user-facing text here that does not come through `copy`; fixing it
+  means changing `MapPreview`, which every consumer shares.
+
+## Best practices
+
+- Sort nothing before passing `units`. The component orders freshest first and
+  breaks ties on the label, so a poll does not reshuffle the list.
+- Keep `selectedId` in the consumer's state when something ELSE needs to know
+  the selection — a detail panel beside the board, a URL, a second map. That is
+  what controlling it buys; a click on the map and a click on the row are the
+  same event either way.
+- Otherwise pass neither `selectedId` nor `onSelect` and let the component hold
+  it. Passing `selectedId` alone with no `onSelect` is a selection nothing can
+  move, and the arrow keys then belong to the page rather than the roster.
+- Pre-format `badge`. It is rendered, never parsed.
+
+## Known limits
+
+- **Not ported to React Native.** `@12-apps/ui` ships a native build for 26 of
+  its 141 subpaths; this is not one, and neither is the `MapPreview` it wraps.
+  Being unported is the ordinary state — 115 subpaths are, at the time of
+  writing — and it fails LOUDLY under Metro: an unported subpath resolves to the
+  web file and errors on `@mui/material` at import rather than rendering a blank
+  view. It is also the right call for this
+  component: a fleet board is a dispatcher's screen, and the tracked unit's own
+  device reports a position rather than drawing the fleet.
+- **The map's own `aria-label` is English**, and comes from `MapPreview` rather
+  than from `copy`. Everything `FleetMap` itself renders is injected; that one
+  sentence is not, and a pt-BR consumer's screen reader will read it in English
+  until `MapPreview` takes a copy port.
+- **Pin separation does not scale with zoom.** `MapPreview` places markers at a
+  fixed pixels-per-degree, so units a few hundred metres apart draw within a
+  pixel or two of each other. The roster distinguishes them; the map does not.