@12-apps/ui 6.22.0 → 6.24.0

package/dist/types-native/components/data-display/FleetMap/FleetMap.metrics.d.ts

@@ -0,0 +1,76 @@
+/**
+ * THE NUMBERS BOTH `FleetMap` RENDERERS DRAW WITH.
+ *
+ * `FleetRoster.tsx` / `FleetMap.tsx` (web, MUI `sx`) and `FleetRoster.native.tsx`
+ * / `FleetMap.native.tsx` (React Native) read this one table. The web hands the
+ * spacing UNITS to `theme.spacing()` and the radius MULTIPLES to `sx`; native
+ * multiplies the units by the theme's own spacing step and the multiples by
+ * `shape.borderRadius`.
+ *
+ * Nothing here imports a renderer, a theme or a colour: a freshness dot's
+ * COLOUR is the theme's (`success.main`, `warning.main`, `text.disabled`), and
+ * the two sides reach the same palette through different doors.
+ *
+ * ## Why the radii are MULTIPLES and never pixels
+ *
+ * MUI's `sx` reads a bare number for `borderRadius` as a multiple of
+ * `theme.shape.borderRadius`, so a value that already had the theme's radius
+ * divided out of it is applied twice. Measured: `theme.shape.borderRadius / 4`
+ * drew 4px on the default theme — which is why it looked right — and 36px on a
+ * host that sets its own radius to 12. In a package whose whole premise is
+ * being re-themed, only the multiple is portable, and it is the multiple that
+ * both renderers store here.
+ */
+/** `theme.spacing(n)` for the panel's own stack. */
+export declare const FLEET_PANEL: {
+    /** Between the heading, the status region and the body. */
+    readonly gapUnits: 1.5;
+};
+/** The roster list box. */
+export declare const FLEET_ROSTER: {
+    /** Between rows. */
+    readonly gapUnits: 0.5;
+    /** `:focus-visible` ring on the web; a device has no focus ring to draw. */
+    readonly focusRingWidth: 2;
+    readonly focusRingOffset: 2;
+};
+/** One roster row. */
+export declare const FLEET_ROW: {
+    /** Between the dot, the text block and the badge. */
+    readonly gapUnits: 1.5;
+    /** `theme.spacing(y, x)`. */
+    readonly paddingYUnits: 1;
+    readonly paddingXUnits: 1.5;
+    /** A MULTIPLE of `theme.shape.borderRadius` — see the note above. */
+    readonly radiusMultiple: 1;
+};
+/**
+ * The freshness dot.
+ *
+ * A perfect circle, so the radius is half the box on both sides rather than
+ * the web's `50%`: React Native resolves a percentage radius against the box
+ * it is given, and a square box makes the two spellings agree.
+ */
+export declare const FLEET_DOT: {
+    readonly size: 10;
+};
+/** What stands in for the roster before any unit has landed. */
+export declare const FLEET_SKELETON: {
+    /** Three bars, the height of a row with its padding. */
+    readonly rows: 3;
+    readonly height: 44;
+    /** A MULTIPLE, for the same reason the row's is. */
+    readonly radiusMultiple: 1;
+    readonly gapUnits: 1;
+};
+/**
+ * How long a fix stays `live`, and then `lagging`, when the caller says nothing.
+ *
+ * Ninety seconds and five minutes: sized for a phone reporting every twenty
+ * seconds, which is the densest cadence a battery tolerates all day. They are
+ * DEFAULTS and not a rule — a fleet on five-minute trackers passes its own, and
+ * the props exist so it can.
+ */
+export declare const FLEET_DEFAULT_LAGGING_AFTER_SECONDS = 90;
+export declare const FLEET_DEFAULT_STALE_AFTER_SECONDS = 300;
+//# sourceMappingURL=FleetMap.metrics.d.ts.map

package/dist/types-native/components/data-display/FleetMap/FleetMap.metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FleetMap.metrics.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/FleetMap/FleetMap.metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,oDAAoD;AACpD,eAAO,MAAM,WAAW;IACtB,2DAA2D;;CAEnD,CAAC;AAEX,2BAA2B;AAC3B,eAAO,MAAM,YAAY;IACvB,oBAAoB;;IAEpB,4EAA4E;;;CAGpE,CAAC;AAEX,sBAAsB;AACtB,eAAO,MAAM,SAAS;IACpB,qDAAqD;;IAErD,6BAA6B;;;IAG7B,qEAAqE;;CAE7D,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;CAEZ,CAAC;AAEX,gEAAgE;AAChE,eAAO,MAAM,cAAc;IACzB,wDAAwD;;;IAGxD,oDAAoD;;;CAG5C,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC,KAAK,CAAC;AACtD,eAAO,MAAM,iCAAiC,MAAM,CAAC"}

package/dist/types-native/components/data-display/FleetMap/FleetMap.native.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import type { FleetMapProps } from './FleetMap.types.native';
+/**
+ * FleetMap on React Native — where a set of tracked units is right now.
+ *
+ * Product-free by construction: it draws a labelled row with a freshness, and
+ * every word — the heading, the three freshness states, how a duration and a
+ * distance are written — arrives through `copy`. Couriers, service vans and
+ * field engineers are all the same list.
+ *
+ * ## What this renderer does NOT draw, and why
+ *
+ * There is no map. `MapPreview` — 2,200 lines that project, tile and decorate
+ * their own surface — has no React Native build, and porting it is its own
+ * change with its own consumers. What that costs is smaller than it sounds,
+ * because the web half already calls this list "the accessible representation,
+ * not a sidebar": every fact a pin carries — who, how recently, how precisely,
+ * what they are carrying — is on a row, in an order the map cannot express. So
+ * a native board is the half a screen reader was always given, and a device
+ * gets the same answers a dispatcher asks for. The gap is stated in
+ * `NATIVE-NOTES.md` rather than claimed away, and it is where the map goes when
+ * `MapPreview` is ported.
+ *
+ * The consequence for the API is one line in `FleetMap.types.native.ts`: the
+ * native copy interface has no `map` and no `mapLabel`, because a caller should
+ * not be asked to name controls nothing renders.
+ */
+export declare const FleetMap: React.FC<FleetMapProps>;
+export default FleetMap;
+//# sourceMappingURL=FleetMap.native.d.ts.map

package/dist/types-native/components/data-display/FleetMap/FleetMap.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FleetMap.native.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/FleetMap/FleetMap.native.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAW/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAsD7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,aAAa,CA+E5C,CAAC;AAeF,eAAe,QAAQ,CAAC"}

package/dist/types-native/components/data-display/FleetMap/FleetMap.types.native.d.ts

@@ -0,0 +1,36 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { FleetMapBaseProps, FleetMapCopyBase } from './FleetMap.base';
+/**
+ * The REACT NATIVE half of `FleetMap`'s contract.
+ *
+ * Everything platform-neutral is re-exported from `FleetMap.base.ts` unchanged.
+ * What differs is at both ends of the file: there is no `map` copy and no
+ * `mapLabel`, because there is no map — `MapPreview` has no native build, and
+ * the roster is this component's own stated "accessible representation, not a
+ * sidebar", which is exactly the half that ports. And `style` stands where the
+ * web takes `className`, which is the ordinary `sx`/`style` split.
+ */
+export type { FleetFreshness, FleetMapBaseProps, FleetMapCopyBase, FleetUnit, } from './FleetMap.base';
+/**
+ * Every word the native board prints.
+ *
+ * An alias rather than an empty `extends`, so that the day `MapPreview` is
+ * ported this becomes an interface with the map's words in it and no consumer
+ * import has to move.
+ */
+export type FleetMapCopy = FleetMapCopyBase;
+/** Props for the native {@link FleetMap} board. */
+export interface FleetMapProps extends FleetMapBaseProps {
+    copy: FleetMapCopy;
+    /**
+     * A ceiling for the roster, so a fleet of thirty scrolls inside the panel
+     * rather than pushing everything below it off the screen.
+     *
+     * A NUMBER of pixels, where the web takes any CSS length: React Native has no
+     * `calc`, no viewport units and no `%` that resolves against a parent which
+     * has not sized itself.
+     */
+    maxHeight?: number;
+    style?: StyleProp<ViewStyle>;
+}
+//# sourceMappingURL=FleetMap.types.native.d.ts.map

package/dist/types-native/components/data-display/FleetMap/FleetMap.types.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FleetMap.types.native.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/FleetMap/FleetMap.types.native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE3E;;;;;;;;;GASG;AACH,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE5C,mDAAmD;AACnD,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,IAAI,EAAE,YAAY,CAAC;IACnB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC9B"}

package/dist/types-native/components/data-display/FleetMap/FleetRoster.native.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { FleetKeyEvent } from './FleetMap.hooks';
+import type { FleetMapCopy, FleetUnit } from './FleetMap.types.native';
+export interface FleetRosterProps {
+    units: readonly FleetUnit[];
+    copy: FleetMapCopy;
+    selectedId: string | null | undefined;
+    onSelect: (id: string) => void;
+    laggingAfterSeconds: number;
+    staleAfterSeconds: number;
+    loading: boolean;
+    maxHeight: number | undefined;
+    testId: string;
+    onKeyDown: (event: FleetKeyEvent) => void;
+}
+export declare function FleetRoster({ units, copy, selectedId, onSelect, laggingAfterSeconds, staleAfterSeconds, loading, maxHeight, testId, onKeyDown, }: FleetRosterProps): React.JSX.Element;
+//# sourceMappingURL=FleetRoster.native.d.ts.map

package/dist/types-native/components/data-display/FleetMap/FleetRoster.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FleetRoster.native.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/FleetMap/FleetRoster.native.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAe/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAkB,YAAY,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAsQvF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACtC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC3C;AAED,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,IAAI,EACJ,UAAU,EACV,QAAQ,EACR,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,SAAS,EACT,MAAM,EACN,SAAS,GACV,EAAE,gBAAgB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAiEtC"}

package/dist/types-native/components/data-display/FleetMap/index.native.d.ts

@@ -0,0 +1,4 @@
+export { FleetMap, default } from './FleetMap.native';
+export { FleetRoster } from './FleetRoster.native';
+export type { FleetFreshness, FleetMapBaseProps, FleetMapCopy, FleetMapCopyBase, FleetMapProps, FleetUnit, } from './FleetMap.types.native';
+//# sourceMappingURL=index.native.d.ts.map

package/dist/types-native/components/data-display/FleetMap/index.native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.native.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/FleetMap/index.native.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,SAAS,GACV,MAAM,yBAAyB,CAAC"}

package/dist/types-native/platform/aria.d.ts

@@ -27,6 +27,19 @@ export interface WebAria {
      * it expands is a listbox — which is what the web's own trigger carries.
      */
     'aria-haspopup'?: 'listbox' | 'menu' | 'dialog' | 'true';
+    /**
+     * Which option a composite widget's single tab stop is currently on — the
+     * listbox pattern, where the LIST holds focus and the selection moves inside
+     * it. React Native has no equivalent because it has no roving focus to
+     * describe: a device selects by touching the row.
+     *
+     * Note the interaction with `aria-atomic` documented on {@link webAria}:
+     * react-native-web reads THIS value when it means the atomic flag, so a
+     * component that sets both gets the descendant id emitted as `aria-atomic`.
+     * Nothing here sets both, and a component that needs to should pass its own
+     * atomic flag directly rather than through this helper.
+     */
+    'aria-activedescendant'?: string;
 }
 /**
  * `attrs` as something JSX can spread onto a react-native element without

package/dist/types-native/platform/aria.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aria.d.ts","sourceRoot":"","sources":["../../../src/platform/aria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAO;IACtB,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;CAC1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAErD;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,GAAG,MAAM,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,CAExE"}
+{"version":3,"file":"aria.d.ts","sourceRoot":"","sources":["../../../src/platform/aria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAO;IACtB,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IACzD;;;;;;;;;;;OAWG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAG9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAErD;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,GAAG,MAAM,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,CAExE"}

package/dist/user-avatar.js

@@ -1,13 +1,13 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-ZKR5B6YJ.js";
+} from "./chunk-ZRPGVHTR.js";
 import "./chunk-UDQSIRAP.js";
-import "./chunk-7BYFC2MR.js";
-import "./chunk-3ZVUNSFF.js";
-import "./chunk-4SQFO4GW.js";
-import "./chunk-FAITHWIO.js";
+import "./chunk-JUHUKZGU.js";
+import "./chunk-NA7MIEG6.js";
 import "./chunk-XRMZMBE3.js";
+import "./chunk-FAITHWIO.js";
+import "./chunk-3ZVUNSFF.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";
 import "./chunk-AIRWM7KK.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.22.0",
+  "version": "6.24.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",
@@ -204,6 +204,14 @@
       "types": "./dist/types/components/data-display/EmptyState/index.d.ts",
       "default": "./dist/data-display/EmptyState.js"
     },
+    "./data-display/FleetMap": {
+      "react-native": {
+        "types": "./dist/types-native/components/data-display/FleetMap/index.native.d.ts",
+        "default": "./dist/native/data-display/FleetMap.js"
+      },
+      "types": "./dist/types/components/data-display/FleetMap/index.d.ts",
+      "default": "./dist/data-display/FleetMap.js"
+    },
     "./data-display/SectionOnboarding": {
       "types": "./dist/types/components/data-display/SectionOnboarding/index.d.ts",
       "default": "./dist/data-display/SectionOnboarding.js"

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

@@ -0,0 +1,96 @@
+import Box from '@mui/material/Box/index.js';
+import Stack from '@mui/material/Stack/index.js';
+import React from 'react';
+
+import { FleetCanvas } from './FleetCanvas';
+import type { FleetMapState } from './FleetMap.hooks';
+import type { FleetMapCopy } from './FleetMap.types';
+import { FleetRoster } from './FleetRoster';
+
+export interface FleetBodyProps
+  extends Pick<FleetMapState, 'ordered' | 'centre' | 'markers' | 'select' | 'onKeyDown'> {
+  copy: FleetMapCopy;
+  selectedId: string | null | undefined;
+  laggingAfterSeconds: number;
+  staleAfterSeconds: number;
+  height: string;
+  loading: boolean;
+  testId: string;
+}
+
+/**
+ * The two halves side by side: the roster that reads the fleet, and the map.
+ *
+ * A component rather than JSX inside {@link import('./FleetMap').FleetMap}
+ * because the layout is where every responsive decision lives, and keeping it
+ * here is what leaves the exported component short enough to read in one
+ * screen — which the complexity ledger enforces rather than merely suggests.
+ */
+export function FleetBody({
+  ordered,
+  centre,
+  markers,
+  select,
+  onKeyDown,
+  copy,
+  selectedId,
+  laggingAfterSeconds,
+  staleAfterSeconds,
+  height,
+  loading,
+  testId,
+}: FleetBodyProps): React.JSX.Element {
+  return (
+    <Stack
+      direction={{ xs: 'column', md: 'row' }}
+      spacing={2}
+      // `aria-busy` belongs on the halves that are actually reloading, NOT on
+      // the panel root — the live region announcing the reload is a sibling up
+      // there, and a live region inside a busy subtree is exactly what
+      // `aria-busy` tells assistive tech to hold back. Marking the root busy
+      // would have silenced the announcement for the whole of the only window
+      // in which it has anything to say. `CepField` splits them the same way.
+      aria-busy={loading || undefined}
+      data-testid={`${testId}-body`}
+      sx={{ alignItems: 'stretch', minWidth: 0 }}
+    >
+      {/* The roster reads first on a phone and sits beside the map from md up.
+          It keeps a ceiling so thirty units scroll rather than push the map off
+          the screen.
+
+          It also WIDENS with the viewport rather than staying at its md width.
+          Held at 280px, a desktop gave the map 1600px for three pins while the
+          roster stayed too narrow for its own meta line — `Lagging · 2 min ago ·
+          ±180 m` wrapped, at 1920px of all widths. The rungs below are the ones
+          the six-width pass was taken at. */}
+      <Box
+        sx={{
+          flexBasis: { md: '280px', lg: '320px', xl: '380px' },
+          flexShrink: 0,
+          minWidth: 0,
+          maxHeight: height,
+          display: 'flex',
+        }}
+      >
+        <FleetRoster
+          units={ordered}
+          copy={copy}
+          selectedId={selectedId}
+          onSelect={select}
+          laggingAfterSeconds={laggingAfterSeconds}
+          staleAfterSeconds={staleAfterSeconds}
+          loading={loading}
+          testId={testId}
+          onKeyDown={onKeyDown}
+        />
+      </Box>
+      <FleetCanvas
+        copy={copy}
+        centre={centre}
+        markers={markers}
+        height={height}
+        testId={testId}
+      />
+    </Stack>
+  );
+}

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.base.ts

@@ -0,0 +1,144 @@
+/**
+ * THE CONTRACT BOTH `FleetMap` RENDERERS HONOUR — and nothing else.
+ *
+ * This file imports no MUI and no react-native, on purpose: it ships in BOTH
+ * declaration outputs (`dist/types` and `dist/types-native`), and a native
+ * consumer has no `@mui/material` to resolve a type import against.
+ *
+ * What is NOT here is as deliberate as what is. `map` (the map control bar's
+ * six words) lives on the web copy alone, because the map half is web-only
+ * until `MapPreview` is ported — see `NATIVE-NOTES.md`. A native caller that
+ * had to supply words for a bar no renderer draws would be asked to describe
+ * something it cannot see.
+ */
+
+/**
+ * One tracked unit's newest position, as the caller resolved it.
+ *
+ * Deliberately says nothing about WHAT is being tracked. A courier, a service
+ * van, a field engineer — the component draws a labelled dot with a freshness,
+ * and every word that names the domain arrives through the copy object.
+ */
+export interface FleetUnit {
+  id: string;
+  /** The name a human reads, on the pin and in the roster. */
+  label: string;
+  latitude: number;
+  longitude: number;
+  /**
+   * The fix's accuracy radius in metres, when the platform reported one.
+   *
+   * Kept because it is what separates a rooftop GPS fix from a cell-tower guess
+   * three blocks wide, and a map that draws both identically tells its reader
+   * something false.
+   */
+  accuracyM?: number | null;
+  /**
+   * Seconds since the fix was ACCEPTED, on the server's clock.
+   *
+   * The caller computes it, and the distinction matters: a device whose own
+   * clock is an hour slow would otherwise report itself as an hour stale while
+   * reporting perfectly.
+   */
+  staleSeconds: number;
+  /** A short pre-formatted badge beside the name, e.g. `"2 entregas"`. */
+  badge?: string;
+}
+
+/** How current a unit's newest fix is, derived from the thresholds below. */
+export type FleetFreshness = 'live' | 'lagging' | 'stale';
+
+/**
+ * Every word the board prints, and the two it FORMATS — minus the map's own.
+ *
+ * `lastSeen` and `accuracy` are functions rather than strings because a
+ * duration and a distance are locale rules, and this package holds the same
+ * line `StatCard` does: presentation only, the caller owns the formatting. A
+ * `lastSeenMinutes: string` template would have made "há 2 min" the only
+ * shape any consumer could ever render.
+ */
+export interface FleetMapCopyBase {
+  /** The panel's heading. */
+  title: string;
+  /** What the roster says when nobody is reporting. */
+  emptyTitle: string;
+  emptyDescription?: string;
+  /** The roster list's accessible name — it is the map's readable half. */
+  rosterLabel: string;
+  /**
+   * What a screen reader hears while the roster reloads, e.g. "Atualizando a
+   * frota". OPTIONAL, and silence is the honest default: the busy state marks
+   * the region stale without uttering anything, the skeletons are hidden from
+   * the reader, and this component cannot invent the sentence in the reader's
+   * language. Set it and the panel announces politely; leave it and it stays
+   * quiet.
+   *
+   * Announced on a TRANSITION into loading. A board mounted already loading is
+   * silent — as any live region is at mount, since there is no change for a
+   * reader to observe.
+   */
+  loading?: string;
+  /** The three freshness words, as a reader sees them on a row. */
+  freshness: Record<FleetFreshness, string>;
+  /** `(seconds) => "há 2 min"`. */
+  lastSeen: (staleSeconds: number) => string;
+  /** `(metres) => "±12 m"`. A unit with no accuracy renders none. */
+  accuracy: (metres: number) => string;
+}
+
+/**
+ * The props both renderers take.
+ *
+ * `height` and `className` are NOT here: the first is a CSS length the web
+ * gives the map, and the second is a DOM class. Each side declares its own
+ * layout escape hatch beside its own extras.
+ */
+export interface FleetMapBaseProps {
+  /** Everyone currently reporting. An empty array renders the empty state. */
+  units: readonly FleetUnit[];
+  /**
+   * Which unit is highlighted: the roster marks it selected, and on the web the
+   * map centres on it. `null` selects nobody.
+   *
+   * PASSING IT AT ALL IS THE DECISION. Present on the first render — `null`
+   * included — and the board is controlled for life: it renders what you pass
+   * and never moves the selection itself. Absent on the first render and it
+   * keeps its own, reporting each change through {@link onSelect}. The mode is
+   * latched on that first render, the way React latches an `<input>`, so the
+   * component cannot change its own semantics halfway through a session.
+   *
+   * A controlled board reads `undefined` as "nobody is selected", so
+   * `useState<string>()` in the caller behaves: clearing it clears the roster.
+   */
+  selectedId?: string | null;
+  /**
+   * A click or press on a row, and each arrow-key move on the web.
+   *
+   * Passing {@link selectedId} WITHOUT this is a selection nothing can move:
+   * the arrow keys then decline to act and leave the page to scroll, rather
+   * than swallowing a keypress that would do nothing.
+   */
+  onSelect?: (id: string) => void;
+  /**
+   * Seconds after which a unit stops reading as `live`, and then as `lagging`.
+   *
+   * Both carry a GENERIC default (90s and 300s, sized for a phone reporting
+   * every twenty seconds) and no domain one, because the answer is entirely a
+   * property of the fleet's own ping cadence: a phone reporting every twenty
+   * seconds is late at ninety, and a tracker reporting every five minutes is
+   * not. A component that picked one would be picking it for every consumer.
+   */
+  laggingAfterSeconds?: number;
+  staleAfterSeconds?: number;
+  /**
+   * While true the roster is marked busy, and renders skeletons IF no units
+   * have landed yet — a poll over a populated roster keeps the list, because
+   * unmounting it throws away the focus inside it.
+   *
+   * It only ANNOUNCES if the copy's `loading` sentence is set: busy is a state,
+   * not an utterance.
+   */
+  loading?: boolean;
+  /** Test id for the panel root; every child id is derived from it. */
+  dataTestId?: string;
+}

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',
+  },
+];