@12-apps/ui 6.22.0 → 6.24.0

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

@@ -0,0 +1,185 @@
+import * as React from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+
+import { EmptyState } from '../EmptyState/EmptyState.native';
+
+import { useFleetMap } from './FleetMap.hooks';
+import {
+  FLEET_DEFAULT_LAGGING_AFTER_SECONDS,
+  FLEET_DEFAULT_STALE_AFTER_SECONDS,
+  FLEET_PANEL,
+} from './FleetMap.metrics';
+import type { FleetMapProps } from './FleetMap.types.native';
+import { FleetRoster } from './FleetRoster.native';
+import { webAria, webRole } from '../../../platform/aria';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { MUI_FONT_WEIGHT_MEDIUM, muiTypeStyle } from '../../../tokens/mui-type';
+
+/**
+ * The reload announcement, and nothing else.
+ *
+ * A busy region marks itself stale for assistive technology but UTTERS nothing,
+ * and the skeletons beside it are hidden from the reader — 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 exist BEFORE its content changes; a 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 query while announcing nothing. So the region
+ * mounts as soon as the caller offers the copy and merely EMPTIES when idle.
+ *
+ * `role="status"` and `aria-live` reach the DOM through react-native-web; on a
+ * device the announcement is made by `AccessibilityInfo` or not at all, which
+ * is recorded in `NATIVE-NOTES.md` rather than papered over here.
+ */
+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 (
+    <View
+      {...webRole('status')}
+      aria-live="polite"
+      accessibilityLiveRegion="polite"
+      testID={`${testId}-status`}
+      style={styles.srOnly}
+    >
+      <Text>{loading ? announcement : ''}</Text>
+    </View>
+  );
+}
+
+/**
+ * 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 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` made every render look controlled
+    // and the uncontrolled path unreachable.
+    selectedId,
+    onSelect,
+    laggingAfterSeconds = FLEET_DEFAULT_LAGGING_AFTER_SECONDS,
+    staleAfterSeconds = FLEET_DEFAULT_STALE_AFTER_SECONDS,
+    loading = false,
+    maxHeight,
+    style,
+    dataTestId,
+  }) => {
+    const theme = useUiTheme();
+    const testId = dataTestId ?? 'fleet-map';
+    const { ordered, active, select, onKeyDown } = useFleetMap(units, selectedId, onSelect);
+
+    return (
+      <View
+        {...webRole('region')}
+        accessibilityLabel={copy.title}
+        testID={testId}
+        style={[styles.panel, { gap: theme.spacing(FLEET_PANEL.gapUnits) }, style]}
+      >
+        <Text
+          {...webRole('heading')}
+          {...webAria({ 'aria-level': 2 })}
+          testID={`${testId}-title`}
+          style={[
+            muiTypeStyle(theme, 'body1'),
+            { color: theme.palette.text.primary, fontWeight: `${MUI_FONT_WEIGHT_MEDIUM}` },
+          ]}
+        >
+          {copy.title}
+        </Text>
+
+        <FleetStatus announcement={copy.loading} loading={loading} testId={testId} />
+
+        {!loading && ordered.length === 0 ? (
+          <EmptyState
+            variant="minimal"
+            title={copy.emptyTitle}
+            description={copy.emptyDescription}
+            dataTestId={`${testId}-empty`}
+          />
+        ) : (
+          /* The busy marker belongs on the BODY and never on the panel root —
+             the live region announcing the reload is a sibling above, and a
+             live region inside a busy subtree is exactly what busy tells
+             assistive technology to hold back. Marking the root would silence
+             the announcement for the whole of the only window in which it has
+             anything to say. The web half splits them the same way, and the
+             wrapper is also what the shared loading stories address. */
+          <View
+            aria-busy={loading || undefined}
+            accessibilityState={{ busy: loading }}
+            testID={`${testId}-body`}
+            style={styles.body}
+          >
+            <FleetRoster
+              units={ordered}
+              copy={copy}
+              selectedId={active}
+              onSelect={select}
+              laggingAfterSeconds={laggingAfterSeconds}
+              staleAfterSeconds={staleAfterSeconds}
+              loading={loading}
+              maxHeight={maxHeight}
+              testId={testId}
+              onKeyDown={onKeyDown}
+            />
+          </View>
+        )}
+      </View>
+    );
+  },
+);
+
+FleetMap.displayName = 'FleetMap';
+
+const styles = StyleSheet.create({
+  body: { flexShrink: 1, minWidth: 0 },
+  panel: { flexDirection: 'column', minWidth: 0 },
+  /**
+   * Off screen but still in the tree, which is what a live region needs. A
+   * `display: 'none'` view is not announced, and a zero-size one clips its text
+   * on some readers.
+   */
+  srOnly: { height: 1, opacity: 0, overflow: 'hidden', position: 'absolute', width: 1 },
+});
+
+export default FleetMap;

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

@@ -0,0 +1,163 @@
+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 {
+  FLEET_DEFAULT_LAGGING_AFTER_SECONDS,
+  FLEET_DEFAULT_STALE_AFTER_SECONDS,
+  FLEET_PANEL,
+} from './FleetMap.metrics';
+import type { FleetMapProps } from './FleetMap.types';
+
+/** 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 = FLEET_DEFAULT_LAGGING_AFTER_SECONDS,
+    staleAfterSeconds = FLEET_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(FLEET_PANEL.gapUnits), 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.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

@@ -0,0 +1,53 @@
+import type { MapPreviewCopy } from '../../../copy';
+
+import type { FleetMapBaseProps, FleetMapCopyBase } from './FleetMap.base';
+
+/**
+ * The WEB half of `FleetMap`'s contract.
+ *
+ * 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 type {
+  FleetFreshness,
+  FleetMapBaseProps,
+  FleetMapCopyBase,
+  FleetUnit,
+} from './FleetMap.base';
+
+/**
+ * Every word the board prints, plus the map control bar's own six.
+ *
+ * `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 extends FleetMapCopyBase {
+  /**
+   * 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 map control bar's own six names. */
+  map: MapPreviewCopy;
+}
+
+/** Props for the {@link FleetMap} live board. */
+export interface FleetMapProps extends FleetMapBaseProps {
+  copy: FleetMapCopy;
+  /** Map height, any CSS length. */
+  height?: string;
+  className?: string;
+}