@12-apps/ui 6.23.0 → 6.24.0

package/src/components/data-display/FleetMap/FleetMap.types.native.ts

@@ -0,0 +1,44 @@
+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>;
+}

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

@@ -1,70 +1,30 @@
 import type { MapPreviewCopy } from '../../../copy';
 
+import type { FleetMapBaseProps, FleetMapCopyBase } from './FleetMap.base';
+
 /**
- * One tracked unit's newest position, as the caller resolved it.
+ * The WEB half of `FleetMap`'s contract.
  *
- * 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 {@link FleetMapCopy}.
+ * Everything platform-neutral lives in `FleetMap.base.ts` and is re-exported
+ * here unchanged, so a consumer's `import type { FleetUnit } from
+ * '@12-apps/ui/data-display/FleetMap'` keeps resolving exactly as it did. What
+ * this file adds is what only the web has: the map.
  */
-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';
+export type {
+  FleetFreshness,
+  FleetMapBaseProps,
+  FleetMapCopyBase,
+  FleetUnit,
+} from './FleetMap.base';
 
 /**
- * Every word the board prints, and the two it FORMATS.
+ * Every word the board prints, plus the map control bar's own six.
  *
- * `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.
+ * `map` is web-only because the map half is: `MapPreview` has no React Native
+ * build yet, so the native copy interface stops at the roster's words rather
+ * than asking a caller to name controls nothing renders. See `NATIVE-NOTES.md`.
  */
-export interface FleetMapCopy {
-  /** 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: `aria-busy` marks the
-   * region stale without uttering anything, the skeletons are `aria-hidden`,
-   * 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;
+export interface FleetMapCopy extends FleetMapCopyBase {
   /**
    * The map region's accessible name.
    *
@@ -80,69 +40,14 @@ export interface FleetMapCopy {
    * re-centre. See `FleetCanvas` for why that is stated rather than fixed here.
    */
   mapLabel: 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 map control bar's own six names. */
   map: MapPreviewCopy;
 }
 
 /** Props for the {@link FleetMap} live board. */
-export interface FleetMapProps {
-  /** Everyone currently reporting. An empty array renders the empty state. */
-  units: readonly FleetUnit[];
+export interface FleetMapProps extends FleetMapBaseProps {
   copy: FleetMapCopy;
-  /**
-   * Which unit is highlighted: the map centres on it and the roster marks it
-   * selected. `null` selects nobody and centres on the whole fleet.
-   *
-   * 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 on a row or a pin, and each arrow-key move. Fires in both modes, so
-   * an uncontrolled board can still be observed.
-   *
-   * 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;
   /** Map height, any CSS length. */
   height?: string;
-  /**
-   * While true the map and roster are marked `aria-busy`, and the roster 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 {@link FleetMapCopy.loading} is set — `aria-busy` is a
-   * state, not an utterance. The panel root is deliberately not the busy
-   * element, so that announcement sits outside the busy subtree.
-   */
-  loading?: boolean;
   className?: string;
-  /** Test id for the panel root; every child id is derived from it. */
-  dataTestId?: string;
 }

package/src/components/data-display/FleetMap/FleetRoster.native.tsx

@@ -0,0 +1,382 @@
+import * as React from 'react';
+import {
+  Pressable,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+  type LayoutChangeEvent,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+} from 'react-native';
+
+import { Skeleton } from '../../layout/Skeleton/Skeleton.native';
+
+import { freshnessOf } from './FleetMap.helpers';
+import type { FleetKeyEvent } from './FleetMap.hooks';
+import { FLEET_DOT, FLEET_ROSTER, FLEET_ROW, FLEET_SKELETON } from './FleetMap.metrics';
+import type { FleetFreshness, FleetMapCopy, FleetUnit } from './FleetMap.types.native';
+import { webAria, webRole } from '../../../platform/aria';
+import { webKeyDown } from '../../../platform/web-keys';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { muiTypeStyle } from '../../../tokens/mui-type';
+import type { UiTheme } from '../../../tokens/theme';
+
+/**
+ * The roster — which on React Native is the WHOLE component, not half of it.
+ *
+ * On the web this list sits beside a map and carries the information a picture
+ * cannot give a screen reader. Here there is no map to sit beside: `MapPreview`
+ * has no React Native build, so the native `FleetMap` renders this and says so
+ * in `NATIVE-NOTES.md`. That is a smaller change than it sounds, because the
+ * web half already treats this list as the component's real content — "the
+ * accessible representation, not a sidebar" — and every fact a pin carries is
+ * on a row here.
+ */
+
+/**
+ * `data-freshness`, as something JSX can spread onto a react-native element.
+ *
+ * Through `dataSet` and NOT as a bare `data-freshness` prop: react-native-web
+ * drops unknown props rather than forwarding them, and special-cases only
+ * `data-testid`. Measured — the attribute was simply absent from the row, so
+ * the shared freshness stories read `null`. `dataSet` is rn-web's documented
+ * channel for custom data attributes and renders `data-freshness`; React Native
+ * ignores it on a device, which is the same trade `webRole` and `webAria` make.
+ *
+ * It is not decoration: the SHARED stories read this attribute to assert which
+ * threshold a row landed on, so without it they cannot run here at all.
+ */
+function webDataFreshness(freshness: FleetFreshness): object {
+  return { dataSet: { freshness } };
+}
+
+/** Each freshness draws from the semantic palette, never a hardcoded hex. */
+function freshnessColor(freshness: FleetFreshness, theme: UiTheme): string {
+  if (freshness === 'live') return theme.palette.success.main;
+  if (freshness === 'lagging') return theme.palette.warning.main;
+  return theme.palette.text.disabled;
+}
+
+/** Where each row sits inside the scrolling content, and what is on screen. */
+interface RosterGeometry {
+  rows: Map<string, { y: number; height: number }>;
+  offset: number;
+  viewport: number;
+}
+
+/**
+ * Keep the selected row visible INSIDE the roster — the same arithmetic the web
+ * does with `scrollTop`, expressed in the only terms React Native has.
+ *
+ * The web reads `box.offsetTop - list.offsetTop` against `list.scrollTop` and
+ * `list.clientHeight`. None of those exist here, so the three numbers are
+ * gathered as they arrive: a row's `onLayout` gives its `y` inside the content
+ * container (already relative to the list, which is what the web computes by
+ * subtraction), the `ScrollView`'s own `onLayout` gives the viewport height,
+ * and `onScroll` gives the offset. The comparison below is then line-for-line
+ * the web's.
+ *
+ * `scrollTo` rather than react-native's `scrollToEnd`/`ScrollView.scrollIntoView`
+ * for the same reason the web refuses `scrollIntoView({ block: 'nearest' })`:
+ * this must move THIS list and nothing else. A native `ScrollView` cannot walk
+ * its ancestors, so the hazard is smaller here — but the arithmetic is shared,
+ * and two renderers agreeing by construction beats two agreeing by coincidence.
+ *
+ * Watches `position` as well as the id, because the roster re-sorts on every
+ * poll: a rider who stays selected while their staleness moves them down the
+ * list would otherwise slide out of view with the effect never re-running.
+ */
+function useKeptInView(
+  scroll: React.RefObject<ScrollView | null>,
+  geometry: React.RefObject<RosterGeometry>,
+  activeId: string | null,
+  position: number,
+): void {
+  React.useEffect(() => {
+    if (activeId === null) return;
+    const { rows, offset, viewport } = geometry.current;
+    const row = rows.get(activeId);
+    // Nothing has laid out yet on the first commit; the next poll re-runs this.
+    if (!row || viewport === 0) return;
+    if (row.y < offset) {
+      scroll.current?.scrollTo({ y: row.y, animated: false });
+    } else if (row.y + row.height > offset + viewport) {
+      scroll.current?.scrollTo({ y: row.y + row.height - viewport, animated: false });
+    }
+  }, [scroll, geometry, activeId, position]);
+}
+
+/**
+ * A row's two lines of text — the name, and the one-line summary under it.
+ *
+ * Split out of {@link FleetRow} to keep that function under the size gate, and
+ * the seam is the natural one: everything here is READ, nothing is interactive.
+ */
+function RowText({
+  unit,
+  copy,
+  freshness,
+  testId,
+}: Pick<RowProps, 'unit' | 'copy' | 'freshness' | 'testId'>): React.JSX.Element {
+  const theme = useUiTheme();
+
+  // Dropped rather than rendered empty: a phone that reports no accuracy radius
+  // would otherwise print a trailing separator with nothing after it.
+  const meta = [
+    copy.freshness[freshness],
+    copy.lastSeen(unit.staleSeconds),
+    unit.accuracyM == null ? null : copy.accuracy(unit.accuracyM),
+  ]
+    .filter((part): part is string => Boolean(part))
+    .join(' · ');
+
+  return (
+    <View style={styles.rowText}>
+      <Text
+        testID={`${testId}-label`}
+        style={[muiTypeStyle(theme, 'body2'), styles.label, { color: theme.palette.text.primary }]}
+      >
+        {unit.label}
+      </Text>
+      <Text
+        testID={`${testId}-meta`}
+        style={[muiTypeStyle(theme, 'caption'), { color: theme.palette.text.secondary }]}
+      >
+        {meta}
+      </Text>
+    </View>
+  );
+}
+
+interface RowProps {
+  unit: FleetUnit;
+  copy: FleetMapCopy;
+  freshness: FleetFreshness;
+  selected: boolean;
+  onSelect: (id: string) => void;
+  onMeasured: (id: string, y: number, height: number) => void;
+  /** The row's own DOM id, which `aria-activedescendant` points at. */
+  optionId: string;
+  testId: string;
+}
+
+/**
+ * One roster row.
+ *
+ * A `Pressable` rather than a `View` with an `onClick`: a press is the input on
+ * a device, and `Pressable` is what gives the row its pressed state and its
+ * accessibility role in one element. The PRESSED wash stands in for the web's
+ * hover — and, as on the web, it must never weaken the selection, so a selected
+ * row keeps `action.selected` whether or not a finger is on it.
+ */
+function FleetRow({
+  unit,
+  copy,
+  freshness,
+  selected,
+  onSelect,
+  onMeasured,
+  optionId,
+  testId,
+}: RowProps): React.JSX.Element {
+  const theme = useUiTheme();
+
+  const measure = React.useCallback(
+    (event: LayoutChangeEvent) => {
+      const { y, height } = event.nativeEvent.layout;
+      onMeasured(unit.id, y, height);
+    },
+    [onMeasured, unit.id],
+  );
+
+  return (
+    <Pressable
+      {...webRole('option')}
+      {...webDataFreshness(freshness)}
+      // Without this the roster's `aria-activedescendant` names an element that
+      // does not exist, which announces nothing and fails an axe audit — worse
+      // than omitting the attribute. Measured: the row carried no id at all.
+      id={optionId}
+      // BOTH, and neither is redundant. `accessibilityState` is what a DEVICE
+      // reads; react-native-web does not turn it into `aria-selected`, so
+      // without the attribute beside it the web build conveys the selection by
+      // background colour alone — which is the one thing this component refuses
+      // to do for freshness, and no more acceptable here.
+      accessibilityState={{ selected }}
+      aria-selected={selected}
+      testID={testId}
+      onPress={() => onSelect(unit.id)}
+      onLayout={measure}
+      style={({ pressed }) => [
+        styles.row,
+        {
+          gap: theme.spacing(FLEET_ROW.gapUnits),
+          paddingVertical: theme.spacing(FLEET_ROW.paddingYUnits),
+          paddingHorizontal: theme.spacing(FLEET_ROW.paddingXUnits),
+          borderRadius: FLEET_ROW.radiusMultiple * theme.radius.md,
+          backgroundColor: selected
+            ? theme.palette.action.selected
+            : pressed
+              ? theme.palette.action.hover
+              : 'transparent',
+        },
+      ]}
+    >
+      {/* The dot repeats what the freshness word beside it already says, so it
+          is hidden rather than read twice — and colour is never the only
+          carrier of the state. */}
+      <View
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+        testID={`${testId}-dot`}
+        style={[styles.dot, { backgroundColor: freshnessColor(freshness, theme) }]}
+      />
+      <RowText unit={unit} copy={copy} freshness={freshness} testId={testId} />
+      {unit.badge !== undefined && unit.badge !== '' && (
+        <Text
+          testID={`${testId}-badge`}
+          style={[
+            muiTypeStyle(theme, 'caption'),
+            styles.badge,
+            { color: theme.palette.text.secondary },
+          ]}
+        >
+          {unit.badge}
+        </Text>
+      )}
+    </Pressable>
+  );
+}
+
+/**
+ * What stands in for the roster before any unit has landed.
+ *
+ * Hidden from the reader, because three grey bars are not information — the
+ * panel's busy state and its optional announcement carry that. The radius is
+ * the same MULTIPLE a real row uses rather than a raw pixel count.
+ */
+function FirstLoad({ testId }: { testId: string }): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <View
+      testID={`${testId}-skeleton`}
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      style={{ gap: theme.spacing(FLEET_SKELETON.gapUnits) }}
+    >
+      {Array.from({ length: FLEET_SKELETON.rows }, (_, row) => (
+        <Skeleton
+          key={row}
+          variant="rectangular"
+          height={FLEET_SKELETON.height}
+          borderRadius={FLEET_SKELETON.radiusMultiple}
+        />
+      ))}
+    </View>
+  );
+}
+
+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 function FleetRoster({
+  units,
+  copy,
+  selectedId,
+  onSelect,
+  laggingAfterSeconds,
+  staleAfterSeconds,
+  loading,
+  maxHeight,
+  testId,
+  onKeyDown,
+}: FleetRosterProps): React.JSX.Element {
+  const theme = useUiTheme();
+  const scroll = React.useRef<ScrollView>(null);
+  const geometry = React.useRef<RosterGeometry>({ rows: new Map(), offset: 0, viewport: 0 });
+
+  // Generated, not derived from `dataTestId`: two boards on one screen filtered
+  // from the same fleet would otherwise emit duplicate ids and an ambiguous
+  // `aria-activedescendant` under react-native-web.
+  const rowIdPrefix = React.useId();
+
+  // The selection is CONTROLLED, so it can name a unit that has since dropped
+  // out of the freshness window — a courier ending their shift mid-poll. The
+  // attribute must then be absent rather than pointing at a row that no longer
+  // renders. `mapCentre` and `nextSelection` both handle the same case.
+  const active = units.some((unit) => unit.id === selectedId) ? (selectedId ?? null) : null;
+  const position = active === null ? -1 : units.findIndex((unit) => unit.id === active);
+
+  const onMeasured = React.useCallback((id: string, y: number, height: number) => {
+    geometry.current.rows.set(id, { y, height });
+  }, []);
+
+  useKeptInView(scroll, geometry, active, position);
+
+  if (loading && units.length === 0) return <FirstLoad testId={testId} />;
+
+  return (
+    <ScrollView
+      ref={scroll}
+      {...webRole('listbox')}
+      // A single tab stop with the arrow keys inside it, which is the listbox
+      // pattern and what `aria-activedescendant` below is for: a dispatcher
+      // tabbing past a fleet of thirty should not press it thirty times. React
+      // Native has no tab order, so this reaches the DOM through
+      // react-native-web and does nothing on a device — where each row is its
+      // own touch target anyway.
+      tabIndex={0}
+      {...webAria({ 'aria-activedescendant': active ? `${rowIdPrefix}-${active}` : undefined })}
+      {...webKeyDown(onKeyDown)}
+      accessibilityLabel={copy.rosterLabel}
+      testID={`${testId}-roster`}
+      style={maxHeight === undefined ? undefined : { maxHeight }}
+      contentContainerStyle={{ gap: theme.spacing(FLEET_ROSTER.gapUnits) }}
+      onLayout={(event: LayoutChangeEvent) => {
+        geometry.current.viewport = event.nativeEvent.layout.height;
+      }}
+      onScroll={(event: NativeSyntheticEvent<NativeScrollEvent>) => {
+        geometry.current.offset = event.nativeEvent.contentOffset.y;
+      }}
+      scrollEventThrottle={16}
+    >
+      {units.map((unit) => (
+        <FleetRow
+          key={unit.id}
+          unit={unit}
+          copy={copy}
+          freshness={freshnessOf(unit.staleSeconds, laggingAfterSeconds, staleAfterSeconds)}
+          selected={unit.id === active}
+          onSelect={onSelect}
+          onMeasured={onMeasured}
+          optionId={`${rowIdPrefix}-${unit.id}`}
+          testId={`${testId}-${unit.id}`}
+        />
+      ))}
+    </ScrollView>
+  );
+}
+
+const styles = StyleSheet.create({
+  badge: { flexShrink: 0 },
+  dot: {
+    borderRadius: FLEET_DOT.size / 2,
+    flexShrink: 0,
+    height: FLEET_DOT.size,
+    width: FLEET_DOT.size,
+  },
+  label: { fontWeight: '500' },
+  row: { alignItems: 'center', flexDirection: 'row' },
+  rowText: { flexGrow: 1, flexShrink: 1, minWidth: 0 },
+});

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

@@ -7,6 +7,7 @@ import React from 'react';
 import { Skeleton } from '../../layout/Skeleton/Skeleton';
 
 import { freshnessOf } from './FleetMap.helpers';
+import { FLEET_DOT, FLEET_ROSTER, FLEET_ROW, FLEET_SKELETON } from './FleetMap.metrics';
 import type { FleetFreshness, FleetMapCopy, FleetUnit } from './FleetMap.types';
 
 /**
@@ -133,15 +134,15 @@ function rowSx(theme: Theme, selected: boolean): SxProps<Theme> {
   return {
     display: 'flex',
     alignItems: 'center',
-    gap: theme.spacing(1.5),
-    padding: theme.spacing(1, 1.5),
+    gap: theme.spacing(FLEET_ROW.gapUnits),
+    padding: theme.spacing(FLEET_ROW.paddingYUnits, FLEET_ROW.paddingXUnits),
     // `1`, not `theme.shape.borderRadius / 4`. MUI's `sx` reads a NUMBER here as
     // a multiple of `theme.shape.borderRadius`, so dividing the theme value out
     // and letting `sx` multiply it back in is quadratic: measured 4px on the
     // default theme — which is why this 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.
-    borderRadius: 1,
+    borderRadius: FLEET_ROW.radiusMultiple,
     cursor: 'pointer',
     backgroundColor: resting,
     '&:hover': {
@@ -195,8 +196,8 @@ function FleetRow({
         aria-hidden="true"
         data-testid={`${testId}-dot`}
         sx={{
-          width: 10,
-          height: 10,
+          width: FLEET_DOT.size,
+          height: FLEET_DOT.size,
           borderRadius: '50%',
           flexShrink: 0,
           backgroundColor: color,
@@ -229,9 +230,14 @@ function FleetRow({
  */
 function FirstLoad({ testId }: { testId: string }): React.JSX.Element {
   return (
-    <Stack spacing={1} data-testid={`${testId}-skeleton`} aria-hidden="true">
-      {[0, 1, 2].map((row) => (
-        <Skeleton key={row} variant="rectangular" height={44} borderRadius={1} />
+    <Stack spacing={FLEET_SKELETON.gapUnits} data-testid={`${testId}-skeleton`} aria-hidden="true">
+      {Array.from({ length: FLEET_SKELETON.rows }, (_, row) => (
+        <Skeleton
+          key={row}
+          variant="rectangular"
+          height={FLEET_SKELETON.height}
+          borderRadius={FLEET_SKELETON.radiusMultiple}
+        />
       ))}
     </Stack>
   );
@@ -294,12 +300,12 @@ export function FleetRoster({
       sx={{
         display: 'flex',
         flexDirection: 'column',
-        gap: theme.spacing(0.5),
+        gap: theme.spacing(FLEET_ROSTER.gapUnits),
         overflowY: 'auto',
         minWidth: 0,
         '&:focus-visible': {
-          outline: `2px solid ${theme.palette.primary.main}`,
-          outlineOffset: 2,
+          outline: `${FLEET_ROSTER.focusRingWidth}px solid ${theme.palette.primary.main}`,
+          outlineOffset: FLEET_ROSTER.focusRingOffset,
         },
       }}
     >

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

@@ -0,0 +1,14 @@
+# FleetMap on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- There is no MAP. `MapPreview` — which projects, tiles and decorates its own surface across ~2,200 lines — has no React Native build, so the native board renders the roster alone and its copy interface has neither `map` nor `mapLabel`: a caller should not be asked to name controls nothing draws. What that costs is smaller than the missing half suggests, because the web already treats this list as the component's real content rather than 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. It is where the map goes when `MapPreview` is ported.
+- Every row is ALSO a tab stop. The list itself carries `tabIndex={0}` and `aria-activedescendant` exactly as the web's listbox does, so the arrow keys work and the selection is announced — but react-native-web additionally gives each `Pressable` its own `tabindex`, which the web half's `Box` rows never had. Measured on the rendered DOM: a fleet of thirty is thirty-one tab stops here against the web's one. Removing them would mean making the rows non-focusable, which would take the press target away on the renderer that has no touch.
+- The arrow keys are web-only. `onKeyDown` reaches the list through react-native-web's DOM events, so a browser still walks the roster with Up and Down, wrapping at both ends, declining a modified arrow and leaving the page to scroll when nothing can move. React Native delivers no key events to a `View`, so on a DEVICE none of it runs and the selection is made by touch.
+- `aria-selected` is passed as the attribute AND as `accessibilityState.selected`, because react-native-web derives neither from the other: without the attribute the web build announced no selection at all and conveyed it by background colour alone, which is the one thing this component refuses to do for freshness.
+- Hover has no touch equivalent, so the pressed wash stands in for it — and, as on the web, it must never WEAKEN the selection: a selected row keeps `action.selected` whether or not a finger is on it, rather than taking the lighter `action.hover`.
+- Keeping the selected row in view is the web's own arithmetic against different numbers. The web reads `offsetTop`/`scrollTop`/`clientHeight`; native gathers the same three from a row's `onLayout`, the `ScrollView`'s `onLayout` and its `onScroll`. So it needs one layout pass before it can act: a board mounted with a selection already set scrolls on the next commit rather than the first, where the web scrolls immediately.
+- The reload announcement is `accessibilityLiveRegion="polite"` plus `aria-live="polite"`. The first is Android's and the second is react-native-web's; iOS has no live region at all, and announcing there needs `AccessibilityInfo.announceForAccessibility`, which this component does not call — a host that must be heard on iOS makes that call itself.
+- A long unbroken label overflows rather than breaking mid-token: the web sets `overflowWrap: 'anywhere'` and React Native has no equivalent style, so a 40-character name with no spaces is clipped by the row instead of wrapped inside it.
+- `maxHeight` is a NUMBER of pixels where the web's `height` is any CSS length: React Native has no `calc`, no viewport units, and no percentage that resolves against a parent which has not sized itself.
+- The title, the row label and the meta line are set in MUI's default `body1`/`body2`/`caption` numbers; a host that re-themes MUI's typography variants moves the web only.