@burdenoff/microfe-movethewheels 2026.1031.2 → 2026.1031.4

package/src/movethewheels/providers/ModuleSettingsProvider.tsx

@@ -0,0 +1,133 @@
+/**
+ * Module settings provider (BOFF-10488).
+ *
+ * Loads the workspace's MoveTheWheels operational defaults once per workspace
+ * and applies them to the shared formatters, so amounts, distances, weights
+ * and dates across every page follow the workspace's currency, units and time
+ * zone. Until the settings load — or if they cannot be read — the platform
+ * defaults apply, which is exactly what the formatters showed before.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type FC,
+  type PropsWithChildren,
+} from 'react';
+import { useMoveTheWheels } from './MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import { setFormatPreferences } from '../utils/formatters';
+import {
+  MTW_MODULE_SETTINGS_QUERY,
+  UPDATE_MTW_MODULE_SETTINGS_MUTATION,
+  platformDefaults,
+  toFormatPreferences,
+  type MtwModuleSettings,
+  type MtwModuleSettingsInput,
+} from '../utils/moduleSettings';
+
+interface ModuleSettingsContextValue {
+  settings: MtwModuleSettings;
+  /** True once the workspace's settings were read (or the read failed). */
+  isLoaded: boolean;
+  error: Error | null;
+  save: (input: MtwModuleSettingsInput) => Promise<MtwModuleSettings>;
+  reload: () => void;
+}
+
+const ModuleSettingsContext = createContext<ModuleSettingsContextValue | null>(null);
+
+export const ModuleSettingsProvider: FC<PropsWithChildren> = ({ children }) => {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  const graphQLOptions = useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+  const [settings, setSettings] = useState<MtwModuleSettings>(() =>
+    platformDefaults(workspaceId ?? '')
+  );
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [reloadKey, setReloadKey] = useState(0);
+
+  const apply = useCallback((next: MtwModuleSettings) => {
+    setFormatPreferences(toFormatPreferences(next));
+    setSettings(next);
+  }, []);
+
+  useEffect(() => {
+    if (!graphQLOptions.workspaceId) return;
+    let cancelled = false;
+    executeGraphQL<{ mtwModuleSettings: MtwModuleSettings }>(
+      graphQLOptions,
+      MTW_MODULE_SETTINGS_QUERY
+    )
+      .then((data) => {
+        if (cancelled) return;
+        apply(data.mtwModuleSettings);
+        setError(null);
+      })
+      .catch((caught: unknown) => {
+        if (cancelled) return;
+        // Keep the platform defaults: a failed read must not blank any page.
+        apply(platformDefaults(graphQLOptions.workspaceId ?? ''));
+        setError(caught instanceof Error ? caught : new Error('Could not load settings'));
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoaded(true);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [graphQLOptions, reloadKey, apply]);
+
+  const save = useCallback(
+    async (input: MtwModuleSettingsInput) => {
+      const data = await executeGraphQL<{ updateMtwModuleSettings: MtwModuleSettings }>(
+        graphQLOptions,
+        UPDATE_MTW_MODULE_SETTINGS_MUTATION,
+        { input }
+      );
+      apply(data.updateMtwModuleSettings);
+      setError(null);
+      return data.updateMtwModuleSettings;
+    },
+    [graphQLOptions, apply]
+  );
+
+  const reload = useCallback(() => setReloadKey((key) => key + 1), []);
+
+  const value = useMemo(
+    () => ({ settings, isLoaded, error, save, reload }),
+    [settings, isLoaded, error, save, reload]
+  );
+
+  return <ModuleSettingsContext.Provider value={value}>{children}</ModuleSettingsContext.Provider>;
+};
+
+/**
+ * The workspace's MoveTheWheels defaults. Outside the provider (stories,
+ * isolated component tests) it returns the platform defaults read-only.
+ */
+export function useModuleSettings(): ModuleSettingsContextValue {
+  const context = useContext(ModuleSettingsContext);
+  if (context) return context;
+  return {
+    settings: platformDefaults(),
+    isLoaded: true,
+    error: null,
+    save: () => Promise.reject(new Error('Module settings are not available here')),
+    reload: () => undefined,
+  };
+}

package/src/movethewheels/utils/entityImport.ts

@@ -0,0 +1,239 @@
+/**
+ * Entity import — client side of wspace-movethewheels-svc's bulk import (BOFF-3990).
+ *
+ * The service owns parsing and validation; this module only picks the right
+ * mutation for an entity, detects the file format, builds CSV templates from
+ * the server's column specification and shapes the result for display.
+ * Kept free of React so the contract can be unit-tested.
+ */
+
+export const MTW_IMPORT_ENTITIES = [
+  { entityType: 'CUSTOMER', label: 'Customers', noun: 'customer', field: 'importMtwCustomers' },
+  { entityType: 'VEHICLE', label: 'Vehicles', noun: 'vehicle', field: 'importMtwVehicles' },
+  { entityType: 'DRIVER', label: 'Drivers', noun: 'driver', field: 'importMtwDrivers' },
+  { entityType: 'WAREHOUSE', label: 'Warehouses', noun: 'warehouse', field: 'importMtwWarehouses' },
+  { entityType: 'CARGO_ITEM', label: 'Products', noun: 'product', field: 'importMtwCargoItems' },
+] as const;
+
+export type MtwImportEntityType = (typeof MTW_IMPORT_ENTITIES)[number]['entityType'];
+export type MtwImportFormat = 'CSV' | 'JSON';
+export type MtwImportStatus = 'DRY_RUN' | 'COMPLETED' | 'PARTIAL' | 'REJECTED';
+
+/** Mirrors the service limits so an oversized file is refused before upload. */
+export const MTW_IMPORT_MAX_BYTES = 2 * 1024 * 1024;
+export const MTW_IMPORT_MAX_ROWS = 1000;
+
+export function isImportEntityType(value: string | null | undefined): value is MtwImportEntityType {
+  return MTW_IMPORT_ENTITIES.some((entity) => entity.entityType === value);
+}
+
+export function importEntity(entityType: MtwImportEntityType) {
+  const entity = MTW_IMPORT_ENTITIES.find((candidate) => candidate.entityType === entityType);
+  if (!entity) throw new Error(`Unknown import entity ${entityType}`);
+  return entity;
+}
+
+// One static document per entity so graphql-schema-drift can validate each
+// against the subgraph schema; the selection sets are identical.
+export const IMPORT_MUTATIONS: Record<MtwImportEntityType, string> = {
+  CUSTOMER: `
+    mutation ImportMtwCustomers($input: MtwImportInput!) {
+      importMtwCustomers(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+  VEHICLE: `
+    mutation ImportMtwVehicles($input: MtwImportInput!) {
+      importMtwVehicles(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+  DRIVER: `
+    mutation ImportMtwDrivers($input: MtwImportInput!) {
+      importMtwDrivers(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+  WAREHOUSE: `
+    mutation ImportMtwWarehouses($input: MtwImportInput!) {
+      importMtwWarehouses(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+  CARGO_ITEM: `
+    mutation ImportMtwCargoItems($input: MtwImportInput!) {
+      importMtwCargoItems(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+};
+
+/** The mutation document for one entity's import. */
+export function importMutation(entityType: MtwImportEntityType): string {
+  return IMPORT_MUTATIONS[importEntity(entityType).entityType];
+}
+
+export const MTW_IMPORT_SPEC_QUERY = `
+  query MtwImportSpec {
+    mtwImportSpec {
+      entityType
+      keyColumn
+      columns {
+        name
+        type
+        required
+        description
+        allowedValues
+        maxLength
+        min
+        max
+      }
+    }
+  }
+`;
+
+export interface MtwImportColumn {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string;
+  allowedValues: string[] | null;
+  maxLength: number | null;
+  min: number | null;
+  max: number | null;
+}
+
+export interface MtwImportEntitySpec {
+  entityType: MtwImportEntityType;
+  keyColumn: string | null;
+  columns: MtwImportColumn[];
+}
+
+export interface MtwImportRowError {
+  row: number;
+  field: string | null;
+  message: string;
+}
+
+export interface MtwImportResult {
+  entityType: MtwImportEntityType;
+  status: MtwImportStatus;
+  dryRun: boolean;
+  totalRows: number;
+  validRows: number;
+  importedRows: number;
+  failedRows: number;
+  createdIds: string[];
+  errorsTruncated: boolean;
+  errors: MtwImportRowError[];
+}
+
+/** Picks the format from the file name, falling back to the MIME type. */
+export function detectImportFormat(fileName: string, mimeType = ''): MtwImportFormat | null {
+  const lower = fileName.toLowerCase();
+  if (lower.endsWith('.csv')) return 'CSV';
+  if (lower.endsWith('.json')) return 'JSON';
+  if (mimeType.includes('csv')) return 'CSV';
+  if (mimeType.includes('json')) return 'JSON';
+  return null;
+}
+
+function csvCell(value: string): string {
+  return /[",\r\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+
+/** A CSV template: the header row, required columns first, then optional ones. */
+export function buildCsvTemplate(spec: MtwImportEntitySpec): string {
+  const ordered = [
+    ...spec.columns.filter((column) => column.required),
+    ...spec.columns.filter((column) => !column.required),
+  ];
+  return `${ordered.map((column) => csvCell(column.name)).join(',')}\n`;
+}
+
+/** One-line summary of an import result for the status banner. */
+export function summariseImport(result: MtwImportResult, noun: string): string {
+  const rows = (count: number) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+  switch (result.status) {
+    case 'DRY_RUN':
+      return result.failedRows === 0
+        ? `All ${rows(result.totalRows)} are valid. Nothing was imported yet.`
+        : `${result.validRows} of ${rows(result.totalRows)} are valid; ${result.failedRows} need fixing. Nothing was imported.`;
+    case 'COMPLETED':
+      return `Imported ${rows(result.importedRows)}.`;
+    case 'PARTIAL':
+      return `Imported ${rows(result.importedRows)}; ${result.failedRows} row${result.failedRows === 1 ? '' : 's'} failed.`;
+    case 'REJECTED':
+      return `Nothing was imported: ${result.failedRows} of ${result.totalRows} rows have problems. Fix them, or allow a partial import.`;
+  }
+}

package/src/movethewheels/utils/formatters.ts

@@ -4,6 +4,46 @@
 
 import type { Address } from '../types';
 
+/**
+ * Workspace display preferences (BOFF-10488). The module settings provider
+ * applies the workspace's saved MoveTheWheels defaults here once they load,
+ * so every formatter below honours them without each call site passing them.
+ * Until then the platform defaults apply.
+ */
+export interface FormatPreferences {
+  /** ISO 4217 code for amounts that carry no currency of their own. */
+  currency: string;
+  distanceUnit: 'KM' | 'MI';
+  weightUnit: 'KG' | 'LB';
+  /** IANA zone; null formats in the viewer's own local time. */
+  timeZone: string | null;
+}
+
+export const DEFAULT_FORMAT_PREFERENCES: Readonly<FormatPreferences> = {
+  currency: 'USD',
+  distanceUnit: 'KM',
+  weightUnit: 'KG',
+  timeZone: null,
+};
+
+let preferences: FormatPreferences = { ...DEFAULT_FORMAT_PREFERENCES };
+
+export function setFormatPreferences(next: FormatPreferences): void {
+  preferences = { ...next };
+}
+
+export function getFormatPreferences(): Readonly<FormatPreferences> {
+  return preferences;
+}
+
+/** The workspace time zone for Intl options; undefined means the viewer's local zone. */
+function zone(): { timeZone?: string } {
+  return preferences.timeZone ? { timeZone: preferences.timeZone } : {};
+}
+
+const KM_PER_MILE = 1.609344;
+const KG_PER_POUND = 0.45359237;
+
 /**
  * Format an address object into a readable string.
  */
@@ -19,12 +59,13 @@ export function formatAddress(address: Partial<Address>): string {
 }
 
 /**
- * Format a number as currency.
+ * Format a number as currency. Amounts without their own currency use the
+ * workspace default currency.
  */
-export function formatCurrency(amount: number, currency = 'USD'): string {
+export function formatCurrency(amount: number, currency?: string): string {
   return new Intl.NumberFormat('en-US', {
     style: 'currency',
-    currency,
+    currency: currency || preferences.currency,
     minimumFractionDigits: 2,
     maximumFractionDigits: 2,
   }).format(amount);
@@ -50,6 +91,7 @@ export function formatDate(
       hour: 'numeric',
       minute: '2-digit',
       hour12: true,
+      ...zone(),
     }).format(d);
   }
 
@@ -62,6 +104,7 @@ export function formatDate(
       hour: 'numeric',
       minute: '2-digit',
       hour12: true,
+      ...zone(),
     }).format(d);
   }
 
@@ -70,6 +113,7 @@ export function formatDate(
     year: 'numeric',
     month: 'short',
     day: 'numeric',
+    ...zone(),
   }).format(d);
 }
 
@@ -85,6 +129,7 @@ export function formatDateTime(date: Date | string): string {
     hour: 'numeric',
     minute: '2-digit',
     hour12: true,
+    ...zone(),
   }).format(d);
 }
 
@@ -97,6 +142,7 @@ export function formatTime(date: Date | string): string {
     hour: 'numeric',
     minute: '2-digit',
     hour12: true,
+    ...zone(),
   }).format(d);
 }
 
@@ -144,24 +190,37 @@ export function formatPercentage(value: number, decimals = 1): string {
   return `${value.toFixed(decimals)}%`;
 }
 
+const twoDecimals = new Intl.NumberFormat('en-US', { maximumFractionDigits: 2 });
+const oneDecimal = new Intl.NumberFormat('en-US', { maximumFractionDigits: 1 });
+
 /**
- * Format weight with appropriate units.
+ * Format a weight given in kilograms, in the workspace weight unit: kg (and
+ * tonnes from 1,000 kg) or lb.
  */
 export function formatWeight(kg: number): string {
-  if (kg >= 1000) {
-    return `${(kg / 1000).toFixed(2)} tonnes`;
+  if (preferences.weightUnit === 'LB') {
+    return `${twoDecimals.format(kg / KG_PER_POUND)} lb`;
   }
-  return `${kg.toFixed(2)} kg`;
+  if (Math.abs(kg) >= 1000) {
+    return `${twoDecimals.format(kg / 1000)} tonnes`;
+  }
+  return `${twoDecimals.format(kg)} kg`;
 }
 
 /**
- * Format distance with appropriate units.
+ * Format a distance given in kilometres, in the workspace distance unit: km
+ * (metres below 1 km) or mi (feet below 0.1 mi).
  */
 export function formatDistance(km: number): string {
-  if (km < 1) {
+  if (preferences.distanceUnit === 'MI') {
+    const miles = km / KM_PER_MILE;
+    if (Math.abs(miles) < 0.1) return `${Math.round(miles * 5280)} ft`;
+    return `${oneDecimal.format(miles)} mi`;
+  }
+  if (Math.abs(km) < 1) {
     return `${Math.round(km * 1000)} m`;
   }
-  return `${km.toFixed(1)} km`;
+  return `${oneDecimal.format(km)} km`;
 }
 
 /**