@12-apps/ui 6.22.0 → 6.24.0

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

@@ -0,0 +1,85 @@
+import type { FleetFreshness, FleetUnit } from './FleetMap.base';
+
+/**
+ * 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,183 @@
+import React from 'react';
+
+import { mapCentre, nextSelection, rosterOrder, type LatLng } from './FleetMap.helpers';
+import type { FleetUnit } from './FleetMap.base';
+
+/**
+ * The half of a key event this hook reads, spelled structurally.
+ *
+ * NOT `React.KeyboardEvent<HTMLDivElement>`: the native type program is checked
+ * without the DOM lib (`tsconfig.native.json`), so a DOM type here would put
+ * the whole hook out of reach of the React Native renderer that shares it. A
+ * DOM event satisfies this shape, and a handler taking the wider type is
+ * assignable wherever the narrower one is expected — so the web passes its own
+ * `onKeyDown` unchanged.
+ */
+export interface FleetKeyEvent {
+  key: string;
+  altKey?: boolean;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  preventDefault: () => void;
+}
+
+/**
+ * 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: FleetKeyEvent) => void;
+}
+
+/** Which way an arrow moves the selection, or `0` when it is not ours. */
+function stepFor(event: FleetKeyEvent): 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: FleetKeyEvent) => {
+      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,189 @@
+# 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
+
+- **The React Native build has no MAP.** This subpath now carries a
+  `react-native` export condition, and what it renders there is the roster: the
+  heading, the rows with their freshness, the empty state, the skeletons and the
+  reload announcement. `MapPreview` — ~2,200 lines that project, tile and
+  decorate their own surface — is still unported, so the native copy interface
+  has neither `map` nor `mapLabel` and a native board draws no canvas. That is a
+  smaller loss than it sounds for this component in particular, because the
+  roster is already its accessible representation rather than a sidebar: every
+  fact a pin carries is on a row. `NATIVE-NOTES.md` holds the full list of
+  rendering gaps, and `pnpm native:ledger` counts them.
+- **On a device the roster is touch-only.** The arrow keys, the single tab stop
+  and `aria-activedescendant` all reach the list through react-native-web, so a
+  browser still walks it exactly as the web build does; React Native delivers no
+  key events to a `View`, so on a phone the selection is made by touch and every
+  row is its own tab stop.
+- **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.

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

@@ -0,0 +1,81 @@
+/**
+ * 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 const FLEET_PANEL = {
+  /** Between the heading, the status region and the body. */
+  gapUnits: 1.5,
+} as const;
+
+/** The roster list box. */
+export const FLEET_ROSTER = {
+  /** Between rows. */
+  gapUnits: 0.5,
+  /** `:focus-visible` ring on the web; a device has no focus ring to draw. */
+  focusRingWidth: 2,
+  focusRingOffset: 2,
+} as const;
+
+/** One roster row. */
+export const FLEET_ROW = {
+  /** Between the dot, the text block and the badge. */
+  gapUnits: 1.5,
+  /** `theme.spacing(y, x)`. */
+  paddingYUnits: 1,
+  paddingXUnits: 1.5,
+  /** A MULTIPLE of `theme.shape.borderRadius` — see the note above. */
+  radiusMultiple: 1,
+} as const;
+
+/**
+ * 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 const FLEET_DOT = {
+  size: 10,
+} as const;
+
+/** What stands in for the roster before any unit has landed. */
+export const FLEET_SKELETON = {
+  /** Three bars, the height of a row with its padding. */
+  rows: 3,
+  height: 44,
+  /** A MULTIPLE, for the same reason the row's is. */
+  radiusMultiple: 1,
+  gapUnits: 1,
+} as const;
+
+/**
+ * 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 const FLEET_DEFAULT_LAGGING_AFTER_SECONDS = 90;
+export const FLEET_DEFAULT_STALE_AFTER_SECONDS = 300;