@burdenoff/microfe-movethewheels 2026.1016.2 → 2026.1016.4

package/src/movethewheels/pages/FreightInvoicePage.tsx

@@ -0,0 +1,477 @@
+import { useState } from 'react';
+import { useSearchParams } from 'react-router';
+import { FileText } from 'lucide-react';
+import { PermissionProvider } from '@burdenoff/fe-libs/shared/providers/shell';
+import { PageLayout } from '../components/PageLayout';
+import { Button } from '../components/ui';
+import { PinnedSelect, ReusePager, ReuseState, reuseCard } from '../components/ReuseControls';
+import { FreightText } from '../components/freight-cost/FreightFields';
+import { InvoiceForm } from '../components/freight-invoice/InvoiceForm';
+import { InvoiceHistoryRecord } from '../components/freight-invoice/InvoiceResults';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { useShipmentPermissions } from '../hooks/useShipmentPermissions';
+import { useConditionApi, useConditionQuery } from '../hooks/useContainerCondition';
+import {
+  useInvoiceComparisonRecovery,
+  useInvoiceComparisonScope,
+} from '../hooks/useInvoiceComparisonRecovery';
+import {
+  InvoiceShipmentsDocument,
+  InvoiceEstimatePageDocument,
+  InvoiceEstimateVersionDocument,
+  InvoiceComparisonHistoryDocument,
+  InvoiceComparisonExactDocument,
+  InvoiceStructuralPreviewDocument,
+  type InvoiceShipmentsQuery,
+  type InvoiceEstimatePageQuery,
+  type InvoiceEstimateVersionQuery,
+  type InvoiceComparisonHistoryQuery,
+  type InvoiceComparisonExactQuery,
+  type InvoiceReceiptFragment,
+  type InvoiceStructuralPreviewQuery,
+} from '../../generated/freight-invoice-operations';
+import {
+  sameInvoiceScope,
+  type InvoiceIntent,
+  type InvoiceScope,
+} from '../utils/invoiceComparison';
+
+export default function FreightInvoicePage() {
+  const owner = useMoveTheWheels();
+  return (
+    <PageLayout
+      title="Freight invoice comparisons"
+      subtitle="Compare manually reported source facts with one immutable estimate version."
+      icon={<FileText aria-hidden="true" />}
+    >
+      <PermissionProvider
+        key={`${owner.workspaceId}:${owner.tenantId}:${owner.currentUser?.id}:${owner.apiGatewayUrl}`}
+        scopeId={owner.workspaceId ?? null}
+        gateway="workspace"
+      >
+        <InvoiceAccess />
+      </PermissionProvider>
+    </PageLayout>
+  );
+}
+function InvoiceAccess() {
+  const access = useShipmentPermissions(),
+    scope = useInvoiceComparisonScope(access.canRead),
+    actions = useInvoiceComparisonRecovery(scope, () => access.allows('update'));
+  return (
+    <>
+      {!access.canRead && (
+        <p role="status">
+          {access.loading
+            ? 'Checking shipment read permission…'
+            : access.failed
+              ? 'Shipment permissions are unavailable. Reload to inspect them.'
+              : 'Shipment read permission in the current workspace is required.'}
+        </p>
+      )}
+      <InvoiceWorkbench key={actions.scopeKey} access={access} scope={scope} actions={actions} />
+    </>
+  );
+}
+function InvoiceWorkbench({
+  access,
+  scope,
+  actions,
+}: {
+  access: ReturnType<typeof useShipmentPermissions>;
+  scope: ReturnType<typeof useInvoiceComparisonScope>;
+  actions: ReturnType<typeof useInvoiceComparisonRecovery>;
+}) {
+  const request = useConditionApi(),
+    [params, setParams] = useSearchParams();
+  const [shipment, setShipment] = useState(
+      () => params.get('invoiceShipment')?.slice(0, 255) ?? ''
+    ),
+    [shipmentOffset, setShipmentOffset] = useState(0),
+    [estimateOffset, setEstimateOffset] = useState(0);
+  const [estimateId, setEstimateId] = useState(''),
+    [started, setStarted] = useState(false),
+    [correction, setCorrection] = useState<InvoiceReceiptFragment | null>(null);
+  const [identity, setIdentity] = useState(
+      () => params.get('invoiceIdentity')?.slice(0, 255) ?? ''
+    ),
+    [identityEntry, setIdentityEntry] = useState(identity),
+    [historyOffset, setHistoryOffset] = useState(0),
+    [selectedId, setSelectedId] = useState('');
+  const [known, setKnown] = useState<InvoiceReceiptFragment | null>(null),
+    [error, setError] = useState<string | null>(null);
+  const enabled = !!scope && access.canRead,
+    paused = actions.busy || actions.uncertain;
+  const shipments = useConditionQuery<InvoiceShipmentsQuery>(
+    InvoiceShipmentsDocument,
+    enabled ? { pagination: { limit: 25, offset: shipmentOffset } } : null,
+    actions.revision
+  );
+  const estimates = useConditionQuery<InvoiceEstimatePageQuery>(
+    InvoiceEstimatePageDocument,
+    enabled && shipment
+      ? { shipmentId: shipment, pagination: { limit: 25, offset: estimateOffset } }
+      : null,
+    actions.revision
+  );
+  const exact = useConditionQuery<InvoiceEstimateVersionQuery>(
+    InvoiceEstimateVersionDocument,
+    enabled && shipment && estimateId ? { shipmentId: shipment, id: estimateId } : null,
+    actions.revision
+  );
+  const history = useConditionQuery<InvoiceComparisonHistoryQuery>(
+    InvoiceComparisonHistoryDocument,
+    enabled && shipment && identity
+      ? {
+          shipmentId: shipment,
+          invoiceIdentityId: identity,
+          pagination: { limit: 10, offset: historyOffset },
+        }
+      : null,
+    actions.revision
+  );
+  const comparison = useConditionQuery<InvoiceComparisonExactQuery>(
+    InvoiceComparisonExactDocument,
+    enabled && shipment && selectedId ? { shipmentId: shipment, id: selectedId } : null,
+    actions.revision
+  );
+  const record = comparison.data?.mtwFreightInvoiceComparison ?? known;
+  const updateHistory = (row: InvoiceReceiptFragment) => {
+    setShipment(row.shipmentId);
+    setKnown(row);
+    setSelectedId(row.id);
+    setIdentity(row.invoiceIdentityId);
+    setIdentityEntry(row.invoiceIdentityId);
+    setHistoryOffset(0);
+    setStarted(false);
+    setCorrection(null);
+    setParams(
+      (previous) => {
+        const next = new URLSearchParams(previous);
+        next.set('invoiceShipment', row.shipmentId);
+        next.set('invoiceIdentity', row.invoiceIdentityId);
+        return next;
+      },
+      { replace: true }
+    );
+  };
+  const options =
+    shipments.data?.shipments.map((s) => ({
+      id: s.id,
+      label: `${s.shipmentNumber} — ${s.primaryMode} — ${s.status}`,
+    })) ?? [];
+  if (shipment && !options.some((s) => s.id === shipment))
+    options.unshift({ id: shipment, label: 'Selected shipment outside this loaded page' });
+  const shipmentPage = shipments.data
+    ? {
+        total: shipments.data.shipmentsCount,
+        limit: 25,
+        offset: shipmentOffset,
+        hasMore: shipmentOffset + shipments.data.shipments.length < shipments.data.shipmentsCount,
+        nextOffset: shipmentOffset + 25,
+      }
+    : undefined;
+  const selected = exact.data?.mtwFreightEstimateVersion;
+  return (
+    <div className="min-w-0 space-y-6 break-words">
+      <p className="rounded border p-4 text-sm">
+        Record only what the supplier source reports. Unknown is not zero. This comparison
+        establishes no quote acceptance, liability, invoice approval or payment. Corrections append
+        a new immutable revision.
+      </p>
+      {actions.uncertain && (
+        <InvoiceRequestRecovery
+          pending={actions.pending}
+          scope={scope}
+          busy={actions.busy}
+          canReconcile={actions.canReconcile}
+          onRead={() =>
+            void actions.reconcile().then((row) => {
+              if (row) updateHistory(row);
+            })
+          }
+        />
+      )}
+      {actions.feedback && (
+        <p role={actions.feedback.error ? 'alert' : 'status'}>{actions.feedback.message}</p>
+      )}
+      {enabled && (
+        <>
+          <section className={reuseCard}>
+            <h2 className="text-lg font-semibold">Choose the exact recorded estimate</h2>
+            <PinnedSelect
+              label="Invoice shipment"
+              value={shipment}
+              disabled={paused || started}
+              options={options}
+              onChange={(id) => {
+                setShipment(id);
+                setEstimateId('');
+                setEstimateOffset(0);
+                setIdentity('');
+                setIdentityEntry('');
+                setSelectedId('');
+                setKnown(null);
+                setCorrection(null);
+                setStarted(false);
+                setParams(
+                  (previous) => {
+                    const next = new URLSearchParams(previous);
+                    next.set('invoiceShipment', id);
+                    next.delete('invoiceIdentity');
+                    return next;
+                  },
+                  { replace: true }
+                );
+              }}
+            />
+            <ReuseState loading={shipments.loading} error={shipments.error} />
+            <ReusePager
+              page={shipmentPage}
+              busy={paused || started || shipments.loading}
+              offset={shipmentOffset}
+              onChange={setShipmentOffset}
+            />
+            {shipment && (
+              <>
+                <PinnedSelect
+                  label="Exact estimate version"
+                  value={estimateId}
+                  disabled={paused || started}
+                  options={
+                    estimates.data?.mtwFreightEstimatePage.items.map((v) => ({
+                      id: v.id,
+                      label: `${v.estimateReference} / version ${v.version} / ${v.facts.kind} / ${v.facts.title}`,
+                    })) ?? []
+                  }
+                  onChange={(id) => setEstimateId(id)}
+                />
+                <ReuseState loading={estimates.loading} error={estimates.error} />
+                <ReusePager
+                  page={estimates.data?.mtwFreightEstimatePage}
+                  busy={paused || started || estimates.loading}
+                  offset={estimateOffset}
+                  onChange={setEstimateOffset}
+                />
+              </>
+            )}
+            <ReuseState loading={exact.loading} error={exact.error} />
+            {selected && (
+              <p>
+                Pinned {selected.facts.kind}: {selected.estimateReference} version{' '}
+                {selected.version}. Source {selected.facts.sourceReference}/
+                {selected.facts.sourceRevision}; source validity {selected.validityAtRead}. This
+                does not establish acceptance.
+              </p>
+            )}
+            <div className="flex flex-wrap gap-3">
+              <Button
+                type="button"
+                disabled={
+                  paused ||
+                  !selected ||
+                  selected.shipmentId !== shipment ||
+                  exact.loading ||
+                  !!exact.error
+                }
+                onClick={() => {
+                  setStarted(true);
+                  setError(null);
+                }}
+              >
+                {correction
+                  ? `Start correction draft after revision ${correction.revision}`
+                  : 'Start manual invoice draft'}
+              </Button>
+              {started && (
+                <Button
+                  type="button"
+                  variant="outline"
+                  disabled={paused}
+                  onClick={() => {
+                    setStarted(false);
+                    setCorrection(null);
+                  }}
+                >
+                  Discard unsent draft
+                </Button>
+              )}
+              <Button
+                type="button"
+                variant="outline"
+                disabled={actions.busy}
+                onClick={actions.refresh}
+              >
+                Refresh recorded data
+              </Button>
+            </div>
+          </section>
+          {started && selected && selected.shipmentId === shipment && (
+            <InvoiceForm
+              key={`${selected.id}:${correction?.id ?? 'first'}`}
+              estimate={selected}
+              previous={correction}
+              disabled={paused || exact.loading || !!exact.error}
+              canRecord={access.canUpdate}
+              onPreview={async (input) => {
+                const result = await request<InvoiceStructuralPreviewQuery>(
+                  InvoiceStructuralPreviewDocument,
+                  { input }
+                );
+                return result.previewMtwFreightInvoice;
+              }}
+              onSave={async (input, pin) => {
+                const result = await actions.run(input, pin);
+                if (result) updateHistory(result);
+                return result;
+              }}
+            />
+          )}
+          {error && <p role="alert">{error}</p>}
+          {shipment && (
+            <section className={reuseCard}>
+              <h2 className="text-lg font-semibold">Recorded invoice history</h2>
+              <p>
+                A confirmed save opens its invoice history here. Bookmark this page to return to it.
+                Complete invoice browsing is not available in this view. A missing page never proves
+                that an unresolved save had no effect.
+              </p>
+              <details>
+                <summary className="min-h-11 cursor-pointer">
+                  Advanced: open a known receipt identity
+                </summary>
+                <FreightText
+                  label="Known invoice identity ID"
+                  value={identityEntry}
+                  disabled={actions.busy}
+                  onChange={setIdentityEntry}
+                />
+                <Button
+                  type="button"
+                  variant="outline"
+                  disabled={actions.busy || !identityEntry.trim()}
+                  onClick={() => {
+                    setIdentity(identityEntry.trim());
+                    setHistoryOffset(0);
+                    setSelectedId('');
+                    setKnown(null);
+                    setParams(
+                      (previous) => {
+                        const next = new URLSearchParams(previous);
+                        next.set('invoiceShipment', shipment);
+                        next.set('invoiceIdentity', identityEntry.trim());
+                        return next;
+                      },
+                      { replace: true }
+                    );
+                  }}
+                >
+                  Read identity history
+                </Button>
+              </details>
+              {identity && (
+                <>
+                  <ReuseState loading={history.loading} error={history.error} />
+                  {history.data?.mtwFreightInvoiceComparisonPage.items.map((row) => (
+                    <Button
+                      key={row.id}
+                      className="h-auto max-w-full whitespace-normal break-words text-left"
+                      type="button"
+                      variant="outline"
+                      onClick={() => {
+                        setSelectedId(row.id);
+                        setKnown(null);
+                      }}
+                    >
+                      {row.facts.supplierLabel ?? row.facts.supplierReference} / invoice{' '}
+                      {row.facts.invoiceReference}, revision {row.revision} / {row.recordedAt}
+                    </Button>
+                  ))}
+                  <ReusePager
+                    page={history.data?.mtwFreightInvoiceComparisonPage}
+                    busy={history.loading || actions.busy}
+                    offset={historyOffset}
+                    onChange={setHistoryOffset}
+                  />
+                </>
+              )}
+            </section>
+          )}
+          <ReuseState loading={comparison.loading} error={comparison.error} />
+          {record && record.shipmentId === shipment && (
+            <>
+              <InvoiceHistoryRecord record={record} />
+              <Button
+                type="button"
+                disabled={
+                  paused ||
+                  !access.canUpdate ||
+                  !history.data ||
+                  history.data.mtwFreightInvoiceComparisonPage.items[0]?.id !== record.id ||
+                  historyOffset !== 0
+                }
+                onClick={() => {
+                  setEstimateId(record.estimate.id);
+                  setCorrection(record);
+                  setStarted(false);
+                  setError(null);
+                }}
+              >
+                Prepare correction to this latest revision
+              </Button>
+              <p>
+                Refresh the first history page to pin its latest revision before correcting. The
+                server checks the exact predecessor again.
+              </p>
+            </>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+/** Retain the unresolved intent across context changes without displaying another context's source facts. */
+export function InvoiceRequestRecovery({
+  pending,
+  scope,
+  busy,
+  canReconcile,
+  onRead,
+}: {
+  pending: InvoiceIntent | null;
+  scope: InvoiceScope | null;
+  busy: boolean;
+  canReconcile: boolean;
+  onRead: () => void;
+}) {
+  return (
+    <section className={reuseCard} aria-label="Original invoice request recovery">
+      <h2 className="font-semibold">Original save is unresolved</h2>
+      {pending && sameInvoiceScope(pending.scope, scope) ? (
+        <>
+          <p>
+            Invoice {pending.input.facts.invoiceReference ?? 'reference unknown'}; exact{' '}
+            {pending.estimate.kind.toLowerCase()} {pending.estimate.estimateReference}, version{' '}
+            {pending.estimate.version}. No automatic resend or new request is allowed.
+          </p>
+          <Button type="button" disabled={!canReconcile || busy} onClick={onRead}>
+            Read original request receipt
+          </Button>
+          <details>
+            <summary className="min-h-11 cursor-pointer">Retained original source intent</summary>
+            <pre className="max-w-full whitespace-pre-wrap break-all text-xs">
+              {JSON.stringify(pending.input, null, 2)}
+            </pre>
+          </details>
+        </>
+      ) : (
+        <p>
+          {pending
+            ? 'The original request is retained in another or unavailable context. Return to the original account, organization, workspace and project with read permission; its source facts remain hidden here.'
+            : 'The saved intent is malformed or unavailable. It remains blocked; do not discard it or start another request as proof of no effect.'}
+        </p>
+      )}
+    </section>
+  );
+}

package/src/movethewheels/utils/driverLicenseExpiry.ts

@@ -0,0 +1,25 @@
+/** The expiry control is explicitly UTC, independent of the browser timezone. */
+export const driverLicenseExpiryInput = (recorded: Date | undefined): string =>
+  recorded ? recorded.toISOString().slice(0, -1) : '';
+
+/** Empty means unrecorded; never substitute noon, end of day or the current time. */
+export const parseDriverLicenseExpiry = (value: string): string | null => {
+  if (value === '') return null;
+  const match = /^(\d{4}-\d\d-\d\dT\d\d:\d\d)(?::(\d\d)(?:\.(\d{1,3}))?)?$/.exec(value);
+  if (!match) throw new Error('Enter a valid licence expiry date and time in UTC.');
+  const canonical = `${match[1]}:${match[2] ?? '00'}.${(match[3] ?? '').padEnd(3, '0')}Z`;
+  const parsed = new Date(canonical);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== canonical) {
+    throw new Error('Enter a valid licence expiry date and time in UTC.');
+  }
+  return canonical;
+};
+
+/** Omit unchanged updates so even server precision beyond this display is retained. */
+export const driverLicenseExpiryUpdate = (
+  value: string,
+  recorded: Date | undefined
+): string | null | undefined => {
+  const next = parseDriverLicenseExpiry(value);
+  return next === (recorded?.toISOString() ?? null) ? undefined : next;
+};

package/src/movethewheels/utils/freightAcknowledgement.ts

@@ -1,3 +1,4 @@
+import { matchesCommercialCapture } from './freightCommercial';
 /** Validate the minimum immutable receipt identity before resolving a retained request. */
 export function matchesFreightAcknowledgement(
   result: unknown,
@@ -26,6 +27,7 @@ export function matchesFreightAcknowledgement(
     input.expectedVersion >= 0 &&
     receipt.version === input.expectedVersion + 1 &&
     'previousVersionId' in receipt &&
-    receipt.previousVersionId === input.expectedPreviousVersionId
+    receipt.previousVersionId === input.expectedPreviousVersionId &&
+    (input.commercialCapture == null || matchesCommercialCapture(receipt, input))
   );
 }