@12-apps/ui 6.22.0 → 6.23.0

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

@@ -0,0 +1,169 @@
+import Box from '@mui/material/Box/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import React from 'react';
+
+import { SR_ONLY_SX } from '../../form/Label/Label.styles';
+import { EmptyState } from '../EmptyState/EmptyState';
+
+import { FleetBody } from './FleetBody';
+import { useFleetMap } from './FleetMap.hooks';
+import type { FleetMapProps } from './FleetMap.types';
+
+/**
+ * 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.
+ */
+const DEFAULT_LAGGING_AFTER_SECONDS = 90;
+const DEFAULT_STALE_AFTER_SECONDS = 300;
+
+/** The map's own default height. Overridable, and never a hardcoded viewport. */
+const DEFAULT_HEIGHT = '420px';
+
+/**
+ * The reload announcement, and nothing else.
+ *
+ * `aria-busy` marks the region stale for assistive technology but UTTERS
+ * nothing, and the skeletons beside it are `aria-hidden` — so a screen-reader
+ * user got silence while the roster reloaded. This is the utterance.
+ *
+ * Optional by design: the sentence is in the reader's language, which only the
+ * caller knows, and inventing an English one in a component whose whole premise
+ * is that every word arrives through `copy` would be the bug it exists to
+ * avoid. No `copy.loading`, no region.
+ *
+ * ## The node outlives the text, and that is the whole trick
+ *
+ * A live region has to be in the DOM BEFORE its content changes; a screen
+ * reader watches an existing region for mutations rather than announcing one
+ * that appears already populated. Mounting region-and-text together in a single
+ * commit is the classic silent case — it satisfies a DOM assertion while
+ * announcing nothing. So the region mounts as soon as the caller offers the
+ * copy and merely EMPTIES when idle, which is what `CepField`, `UploadButton`
+ * and `DateRangePickerFields` all do.
+ */
+function FleetStatus({
+  announcement,
+  loading,
+  testId,
+}: {
+  announcement: string | undefined;
+  loading: boolean;
+  testId: string;
+}): React.JSX.Element | null {
+  // No copy, no region at all — the caller has not asked for an announcement.
+  if (announcement === undefined) return null;
+  return (
+    <Box role="status" aria-live="polite" data-testid={`${testId}-status`} sx={SR_ONLY_SX}>
+      {loading ? announcement : ''}
+    </Box>
+  );
+}
+
+/**
+ * FleetMap — where a set of tracked units is right now, as a map beside the
+ * roster that reads it.
+ *
+ * Product-free by construction: it draws labelled dots with a freshness, and
+ * every word — the heading, the three freshness states, how a duration and a
+ * distance are written — arrives through {@link FleetMapProps.copy}. Couriers,
+ * service vans and field engineers are all the same picture.
+ *
+ * ## Three decisions worth knowing before changing it
+ *
+ * **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 gets from a pin — who, how recently,
+ * what they are carrying — is on the row. The map is a NAMED region rather than
+ * an `aria-hidden` one, because its controls are focusable and hiding a
+ * focusable subtree is the `aria-hidden-focus` violation.
+ *
+ * **Nothing here formats.** `lastSeen` and `accuracy` are functions on the copy
+ * object, the same line `StatCard` holds for its `value`: a duration and a
+ * distance are locale rules, and a component that wrote "2 min ago" would have
+ * made English the only language it could ever render.
+ *
+ * **An empty fleet is an empty STATE, not an empty map.** A map with no pins is
+ * indistinguishable from a map that failed to load, and the difference is the
+ * whole question a dispatcher is asking.
+ */
+export const FleetMap: React.FC<FleetMapProps> = React.memo(
+  ({
+    units,
+    copy,
+    // NO default. `undefined` is what tells the hook the caller does not own
+    // the selection; defaulting it to `null` here made every render look
+    // controlled and the uncontrolled path unreachable.
+    selectedId,
+    onSelect,
+    laggingAfterSeconds = DEFAULT_LAGGING_AFTER_SECONDS,
+    staleAfterSeconds = DEFAULT_STALE_AFTER_SECONDS,
+    height = DEFAULT_HEIGHT,
+    loading = false,
+    className,
+    dataTestId,
+  }) => {
+    const theme = useTheme();
+    const testId = dataTestId || 'fleet-map';
+    const headingId = React.useId();
+    const { ordered, active, centre, select, markers, onKeyDown } = useFleetMap(
+      units,
+      selectedId,
+      onSelect,
+    );
+
+    return (
+      <Box
+        role="region"
+        aria-labelledby={headingId}
+        className={className}
+        data-testid={testId}
+        sx={{ display: 'flex', flexDirection: 'column', gap: theme.spacing(1.5), minWidth: 0 }}
+      >
+        <Typography
+          id={headingId}
+          variant="subtitle1"
+          component="h2"
+          data-testid={`${testId}-title`}
+          sx={{ fontWeight: theme.typography.fontWeightMedium }}
+        >
+          {copy.title}
+        </Typography>
+
+        <FleetStatus announcement={copy.loading} loading={loading} testId={testId} />
+
+        {!loading && ordered.length === 0 ? (
+          <EmptyState
+            variant="minimal"
+            title={copy.emptyTitle}
+            description={copy.emptyDescription}
+            dataTestId={`${testId}-empty`}
+          />
+        ) : (
+          <FleetBody
+            ordered={ordered}
+            centre={centre}
+            markers={markers}
+            select={select}
+            onKeyDown={onKeyDown}
+            copy={copy}
+            selectedId={active}
+            laggingAfterSeconds={laggingAfterSeconds}
+            staleAfterSeconds={staleAfterSeconds}
+            height={height}
+            loading={loading}
+            testId={testId}
+          />
+        )}
+      </Box>
+    );
+  },
+);
+
+FleetMap.displayName = 'FleetMap';
+
+export default FleetMap;

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

@@ -0,0 +1,148 @@
+import type { MapPreviewCopy } from '../../../copy';
+
+/**
+ * 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 {@link FleetMapCopy}.
+ */
+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.
+ *
+ * `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 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;
+  /**
+   * The map region's accessible name.
+   *
+   * The map is NOT `aria-hidden`, and that is deliberate rather than an
+   * oversight: it carries focusable controls (zoom, centre, map type), 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. So it is a NAMED region a reader can skip past instead, and the
+   * roster beside it carries every fact a pin does.
+   *
+   * Skipping it does not silence it: `MapPreview` carries its own
+   * `aria-live="polite"` and announces its centre in English on every
+   * 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[];
+  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.tsx

@@ -0,0 +1,321 @@
+import Box from '@mui/material/Box/index.js';
+import Stack from '@mui/material/Stack/index.js';
+import Typography from '@mui/material/Typography/index.js';
+import { useTheme, type SxProps, type Theme } from '@mui/material/styles/index.js';
+import React from 'react';
+
+import { Skeleton } from '../../layout/Skeleton/Skeleton';
+
+import { freshnessOf } from './FleetMap.helpers';
+import type { FleetFreshness, FleetMapCopy, FleetUnit } from './FleetMap.types';
+
+/**
+ * The roster beside the map — and the ACCESSIBLE half of this component.
+ *
+ * A map is a picture of positions and a screen reader cannot read a picture, so
+ * the panel's information is carried by this list. That is not a consolation
+ * prize: the list answers the questions a dispatcher actually asks — who is
+ * reporting, how recently, and what are they carrying — and it answers them in
+ * an order the map cannot express.
+ *
+ * The map beside it is a NAMED LANDMARK rather than an `aria-hidden` one, so a
+ * reader can skip it in one gesture — see `FleetCanvas`, which carries the
+ * reason it must not be hidden.
+ */
+
+/** Each freshness draws from the semantic palette, never a hardcoded hex. */
+function freshnessColor(freshness: FleetFreshness, theme: Theme): string {
+  if (freshness === 'live') return theme.palette.success.main;
+  if (freshness === 'lagging') return theme.palette.warning.main;
+  return theme.palette.text.disabled;
+}
+
+/**
+ * A row's two lines of text — the name, and the one-line summary under it.
+ *
+ * Split out of `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 = useTheme();
+
+  // 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 (
+    <Stack sx={{ minWidth: 0, flexGrow: 1 }}>
+      <Typography
+        variant="body2"
+        component="p"
+        data-testid={`${testId}-label`}
+        sx={{ fontWeight: theme.typography.fontWeightMedium, overflowWrap: 'anywhere' }}
+      >
+        {unit.label}
+      </Typography>
+      <Typography
+        variant="caption"
+        component="p"
+        data-testid={`${testId}-meta`}
+        sx={{ color: theme.palette.text.secondary }}
+      >
+        {meta}
+      </Typography>
+    </Stack>
+  );
+}
+
+/**
+ * Keep the selected row visible INSIDE the roster.
+ *
+ * The roster caps its own height, so a dispatcher arrowing through a fleet of
+ * thirty otherwise walks the selection below the fold with nothing moving —
+ * `aria-activedescendant` follows, and a SIGHTED keyboard user sees no feedback
+ * at all.
+ *
+ * Watches the row's POSITION as well as its selectedness, 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.
+ *
+ * Arithmetic rather than `scrollIntoView({ block: 'nearest' })` because that
+ * walks every scrollable ancestor, the document included, and `nearest` only
+ * spares an ancestor the row is already visible in — which is exactly false
+ * when the panel is off screen. Re-running on every re-sort, it would yank the
+ * whole page back to the map on a timer, and drag it there on mount for any
+ * board rendered below the fold with a selection already set.
+ */
+function useKeptInView(
+  selected: boolean,
+  position: number,
+): React.RefObject<HTMLDivElement | null> {
+  const row = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    const box = row.current;
+    const list = box?.parentElement;
+    if (!selected || !box || !list) return;
+    const top = box.offsetTop - list.offsetTop;
+    if (top < list.scrollTop) {
+      list.scrollTop = top;
+    } else if (top + box.offsetHeight > list.scrollTop + list.clientHeight) {
+      list.scrollTop = top + box.offsetHeight - list.clientHeight;
+    }
+  }, [selected, position]);
+
+  return row;
+}
+
+/**
+ * A row's own box, selected or not.
+ *
+ * Out of line because the hover rule needs the explanation more than the JSX
+ * has room for: hover must never WEAKEN the selection. Written flat as
+ * `'&:hover': { backgroundColor: action.hover }`, the pseudo-class wins on
+ * specificity and repaints the selected row with the hover tint — measured at
+ * `rgba(0,0,0,0.08)` idle against `rgba(0,0,0,0.04)` hovered, so pointing at
+ * the selected row visually DESELECTED it and made it indistinguishable from
+ * any other row under the cursor.
+ */
+function rowSx(theme: Theme, selected: boolean): SxProps<Theme> {
+  const resting = selected ? theme.palette.action.selected : 'transparent';
+  return {
+    display: 'flex',
+    alignItems: 'center',
+    gap: theme.spacing(1.5),
+    padding: theme.spacing(1, 1.5),
+    // `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,
+    cursor: 'pointer',
+    backgroundColor: resting,
+    '&:hover': {
+      backgroundColor: selected ? theme.palette.action.selected : theme.palette.action.hover,
+    },
+  };
+}
+
+interface RowProps {
+  unit: FleetUnit;
+  copy: FleetMapCopy;
+  freshness: FleetFreshness;
+  selected: boolean;
+  onSelect: (id: string) => void;
+  /** The row's DOM id, which `aria-activedescendant` points at. */
+  optionId: string;
+  /** Where the row sits in the re-sorted roster — see the scroll effect. */
+  position: number;
+  testId: string;
+}
+
+function FleetRow({
+  unit,
+  copy,
+  freshness,
+  selected,
+  onSelect,
+  optionId,
+  position,
+  testId,
+}: RowProps): React.JSX.Element {
+  const theme = useTheme();
+  const color = freshnessColor(freshness, theme);
+  const row = useKeptInView(selected, position);
+
+  return (
+    <Box
+      ref={row}
+      role="option"
+      aria-selected={selected}
+      id={optionId}
+      data-testid={testId}
+      data-freshness={freshness}
+      onClick={() => onSelect(unit.id)}
+      sx={rowSx(theme, selected)}
+    >
+      {/* 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. */}
+      <Box
+        aria-hidden="true"
+        data-testid={`${testId}-dot`}
+        sx={{
+          width: 10,
+          height: 10,
+          borderRadius: '50%',
+          flexShrink: 0,
+          backgroundColor: color,
+        }}
+      />
+      <RowText unit={unit} copy={copy} freshness={freshness} testId={testId} />
+      {unit.badge && (
+        <Typography
+          variant="caption"
+          component="span"
+          data-testid={`${testId}-badge`}
+          sx={{ color: theme.palette.text.secondary, flexShrink: 0 }}
+        >
+          {unit.badge}
+        </Typography>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * What stands in for the roster before any unit has landed.
+ *
+ * `aria-hidden`, because three grey bars are not information — the panel's
+ * `aria-busy` and its optional announcement carry that. The radius is the same
+ * MULTIPLE a real row uses rather than a raw pixel count: `Skeleton` forwards
+ * the number into `sx`, where it scales with `theme.shape.borderRadius`, so a
+ * literal `4` drew 16px against the rows' 4px on the default theme and 48px
+ * against 12px on a re-themed host.
+ */
+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>
+  );
+}
+
+export interface FleetRosterProps {
+  units: readonly FleetUnit[];
+  copy: FleetMapCopy;
+  selectedId: string | null | undefined;
+  onSelect: (id: string) => void;
+  laggingAfterSeconds: number;
+  staleAfterSeconds: number;
+  loading: boolean;
+  testId: string;
+  onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+}
+
+export function FleetRoster({
+  units,
+  copy,
+  selectedId,
+  onSelect,
+  laggingAfterSeconds,
+  staleAfterSeconds,
+  loading,
+  testId,
+  onKeyDown,
+}: FleetRosterProps): React.JSX.Element {
+  const theme = useTheme();
+  // Generated, not derived from `dataTestId`: two boards on one page filtered
+  // from the same fleet would otherwise emit duplicate DOM ids and an ambiguous
+  // `aria-activedescendant`. Same reason the heading uses one.
+  const rowIdPrefix = React.useId();
+  const optionId = (id: string): string => `${rowIdPrefix}-${id}`;
+
+  // 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 an element that no
+  // longer renders, which announces nothing and fails an axe audit. `mapCentre`
+  // and `nextSelection` both handle the same case; this is the third place.
+  const active = units.some((unit) => unit.id === selectedId) ? selectedId : null;
+
+  // Only when there is nothing to show yet. Unmounting a populated listbox on
+  // every poll destroys the focus inside it, so a dispatcher arrowing through
+  // the roster is thrown back to the top of the page each time the data
+  // refreshes — and the rows they were reading vanish and return.
+  if (loading && units.length === 0) return <FirstLoad testId={testId} />;
+
+  return (
+    <Box
+      role="listbox"
+      // A single tab stop with arrow keys inside, which is the listbox pattern:
+      // a dispatcher tabbing past a fleet of thirty should not have to press it
+      // thirty times to reach the map.
+      tabIndex={0}
+      aria-label={copy.rosterLabel}
+      aria-activedescendant={active ? optionId(active) : undefined}
+      data-testid={`${testId}-roster`}
+      onKeyDown={onKeyDown}
+      sx={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: theme.spacing(0.5),
+        overflowY: 'auto',
+        minWidth: 0,
+        '&:focus-visible': {
+          outline: `2px solid ${theme.palette.primary.main}`,
+          outlineOffset: 2,
+        },
+      }}
+    >
+      {units.map((unit, index) => (
+        <FleetRow
+          key={unit.id}
+          unit={unit}
+          copy={copy}
+          freshness={freshnessOf(unit.staleSeconds, laggingAfterSeconds, staleAfterSeconds)}
+          selected={unit.id === active}
+          onSelect={onSelect}
+          optionId={optionId(unit.id)}
+          position={index}
+          testId={`${testId}-${unit.id}`}
+        />
+      ))}
+    </Box>
+  );
+}

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

@@ -0,0 +1,9 @@
+export { FleetMap } from './FleetMap';
+export { freshnessOf, mapCentre, nextSelection, rosterOrder } from './FleetMap.helpers';
+export type { LatLng } from './FleetMap.helpers';
+export type {
+  FleetFreshness,
+  FleetMapCopy,
+  FleetMapProps,
+  FleetUnit,
+} from './FleetMap.types';