@burdenoff/microfe-movethewheels 2026.1031.3 → 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/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`;
 }
 
 /**

package/src/movethewheels/utils/moduleSettings.ts

@@ -0,0 +1,224 @@
+/**
+ * Module settings — client side of wspace-movethewheels-svc's workspace
+ * operational defaults (BOFF-10488).
+ *
+ * The service owns validation and storage; this module holds the GraphQL
+ * documents, the platform defaults (used until the settings load), the
+ * picker options and the mapping between the service's order priorities and
+ * the order form's. Kept free of React so the contract can be unit-tested.
+ */
+import type { FormatPreferences } from './formatters';
+
+export type MtwDistanceUnit = 'KM' | 'MI';
+export type MtwWeightUnit = 'KG' | 'LB';
+export type MtwOrderPriority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'CRITICAL';
+
+export interface MtwModuleSettings {
+  workspaceId: string;
+  defaultCurrency: string;
+  distanceUnit: MtwDistanceUnit;
+  weightUnit: MtwWeightUnit;
+  /** IANA zone; null shows each viewer their own local time. */
+  timezone: string | null;
+  defaultOrderPriority: MtwOrderPriority;
+  defaultDeliveryWindowHours: number;
+  isCustomized: boolean;
+  updatedAt: string | null;
+  updatedBy: string | null;
+}
+
+export type MtwModuleSettingsInput = Partial<
+  Pick<
+    MtwModuleSettings,
+    | 'defaultCurrency'
+    | 'distanceUnit'
+    | 'weightUnit'
+    | 'timezone'
+    | 'defaultOrderPriority'
+    | 'defaultDeliveryWindowHours'
+  >
+>;
+
+/** Mirrors the service range for the default delivery window. */
+export const DELIVERY_WINDOW_MIN_HOURS = 1;
+export const DELIVERY_WINDOW_MAX_HOURS = 720;
+
+/** The service's platform defaults, shown until the workspace's settings load. */
+export function platformDefaults(workspaceId = ''): MtwModuleSettings {
+  return {
+    workspaceId,
+    defaultCurrency: 'USD',
+    distanceUnit: 'KM',
+    weightUnit: 'KG',
+    timezone: null,
+    defaultOrderPriority: 'MEDIUM',
+    defaultDeliveryWindowHours: 24,
+    isCustomized: false,
+    updatedAt: null,
+    updatedBy: null,
+  };
+}
+
+const SETTINGS_FIELDS = `
+  workspaceId
+  defaultCurrency
+  distanceUnit
+  weightUnit
+  timezone
+  defaultOrderPriority
+  defaultDeliveryWindowHours
+  isCustomized
+  updatedAt
+  updatedBy
+`;
+
+export const MTW_MODULE_SETTINGS_QUERY = `
+  query MtwModuleSettings {
+    mtwModuleSettings {
+      ${SETTINGS_FIELDS}
+    }
+  }
+`;
+
+export const UPDATE_MTW_MODULE_SETTINGS_MUTATION = `
+  mutation UpdateMtwModuleSettings($input: UpdateMtwModuleSettingsInput!) {
+    updateMtwModuleSettings(input: $input) {
+      ${SETTINGS_FIELDS}
+    }
+  }
+`;
+
+/** What the formatters need from the settings. */
+export function toFormatPreferences(settings: MtwModuleSettings): FormatPreferences {
+  return {
+    currency: settings.defaultCurrency,
+    distanceUnit: settings.distanceUnit,
+    weightUnit: settings.weightUnit,
+    timeZone: settings.timezone,
+  };
+}
+
+export const DISTANCE_UNIT_OPTIONS: ReadonlyArray<{ value: MtwDistanceUnit; label: string }> = [
+  { value: 'KM', label: 'Kilometres (km)' },
+  { value: 'MI', label: 'Miles (mi)' },
+];
+
+export const WEIGHT_UNIT_OPTIONS: ReadonlyArray<{ value: MtwWeightUnit; label: string }> = [
+  { value: 'KG', label: 'Kilograms (kg)' },
+  { value: 'LB', label: 'Pounds (lb)' },
+];
+
+export const ORDER_PRIORITY_OPTIONS: ReadonlyArray<{ value: MtwOrderPriority; label: string }> = [
+  { value: 'LOW', label: 'Low' },
+  { value: 'MEDIUM', label: 'Normal' },
+  { value: 'HIGH', label: 'High' },
+  { value: 'URGENT', label: 'Urgent' },
+  { value: 'CRITICAL', label: 'Critical' },
+];
+
+/** The order form's four priorities for a service priority (CRITICAL shows as urgent). */
+export function orderFormPriority(
+  priority: MtwOrderPriority
+): 'low' | 'normal' | 'high' | 'urgent' {
+  switch (priority) {
+    case 'LOW':
+      return 'low';
+    case 'HIGH':
+      return 'high';
+    case 'URGENT':
+    case 'CRITICAL':
+      return 'urgent';
+    default:
+      return 'normal';
+  }
+}
+
+/** Commonly used currencies first, then every other code the browser knows. */
+const PREFERRED_CURRENCIES = ['USD', 'EUR', 'GBP', 'INR', 'AED', 'SGD', 'AUD', 'CAD', 'JPY', 'CNY'];
+
+function supportedValues(key: 'currency' | 'timeZone'): string[] {
+  // Older browsers lack Intl.supportedValuesOf; the pickers then offer the
+  // preferred list plus the saved value.
+  return typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf(key) : [];
+}
+
+export function currencyOptions(current?: string): string[] {
+  const all = new Set([...PREFERRED_CURRENCIES, ...supportedValues('currency')]);
+  if (current) all.add(current);
+  const rest = [...all].filter((code) => !PREFERRED_CURRENCIES.includes(code)).sort();
+  return [...PREFERRED_CURRENCIES, ...rest];
+}
+
+export function currencyLabel(code: string): string {
+  try {
+    const name = new Intl.DisplayNames(['en'], { type: 'currency' }).of(code);
+    return name && name !== code ? `${code} — ${name}` : code;
+  } catch {
+    return code;
+  }
+}
+
+export function timeZoneOptions(current?: string | null): string[] {
+  const zones = new Set(['UTC', ...supportedValues('timeZone')]);
+  if (current) zones.add(current);
+  return [...zones].sort((a, b) => (a === 'UTC' ? -1 : b === 'UTC' ? 1 : a.localeCompare(b)));
+}
+
+/** The browser's own zone, for the "viewer's local time" option label. */
+export function browserTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  } catch {
+    return 'UTC';
+  }
+}
+
+/** Client-side check of the delivery window before it is sent. */
+export function deliveryWindowError(value: string): string | null {
+  const hours = Number(value);
+  if (
+    !value.trim() ||
+    !Number.isInteger(hours) ||
+    hours < DELIVERY_WINDOW_MIN_HOURS ||
+    hours > DELIVERY_WINDOW_MAX_HOURS
+  ) {
+    return `Enter a whole number of hours between ${DELIVERY_WINDOW_MIN_HOURS} and ${DELIVERY_WINDOW_MAX_HOURS}.`;
+  }
+  return null;
+}
+
+/** Only the fields that differ from the saved settings. */
+export function changedSettings(
+  saved: MtwModuleSettings,
+  draft: MtwModuleSettingsInput
+): MtwModuleSettingsInput {
+  const changes: MtwModuleSettingsInput = {};
+  if (draft.defaultCurrency !== undefined && draft.defaultCurrency !== saved.defaultCurrency)
+    changes.defaultCurrency = draft.defaultCurrency;
+  if (draft.distanceUnit !== undefined && draft.distanceUnit !== saved.distanceUnit)
+    changes.distanceUnit = draft.distanceUnit;
+  if (draft.weightUnit !== undefined && draft.weightUnit !== saved.weightUnit)
+    changes.weightUnit = draft.weightUnit;
+  if (draft.timezone !== undefined && draft.timezone !== saved.timezone)
+    changes.timezone = draft.timezone;
+  if (
+    draft.defaultOrderPriority !== undefined &&
+    draft.defaultOrderPriority !== saved.defaultOrderPriority
+  )
+    changes.defaultOrderPriority = draft.defaultOrderPriority;
+  if (
+    draft.defaultDeliveryWindowHours !== undefined &&
+    draft.defaultDeliveryWindowHours !== saved.defaultDeliveryWindowHours
+  )
+    changes.defaultDeliveryWindowHours = draft.defaultDeliveryWindowHours;
+  return changes;
+}
+
+/** A `datetime-local` value `hours` from `from`, in the viewer's clock. */
+export function deliveryWindowValue(hours: number, from: Date = new Date()): string {
+  const target = new Date(from.getTime() + hours * 3600 * 1000);
+  const pad = (value: number) => String(value).padStart(2, '0');
+  return `${target.getFullYear()}-${pad(target.getMonth() + 1)}-${pad(target.getDate())}T${pad(
+    target.getHours()
+  )}:${pad(target.getMinutes())}`;
+}