@burdenoff/microfe-movethewheels 2026.1016.2 → 2026.1016.3

package/src/movethewheels/components/freight-cost/FreightCommercialEditor.tsx

@@ -0,0 +1,236 @@
+import { useState } from 'react';
+import { OptionalFields } from '@burdenoff/fe-libs/ui';
+import {
+  FreightCommercialLegsDocument,
+  type FreightCommercialLegsQuery,
+} from '../../../generated/freight-cost-operations';
+import { useConditionQuery } from '../../hooks/useContainerCondition';
+import {
+  commercialSlots,
+  commercialCanonical,
+  newCommercialEditor,
+  type CommercialEditorState,
+} from '../../utils/freightCommercial';
+import { FreightCommercialFactEditor } from './FreightCommercialFactEditor';
+import { Button } from '../ui';
+import { ReuseState } from '../ReuseControls';
+import type { SelectedEvidence } from '../ContainerEvidencePicker';
+
+export function FreightCommercialEditor({
+  value,
+  onChange,
+  shipmentId,
+  evidence,
+}: {
+  value: CommercialEditorState | null;
+  onChange: (value: CommercialEditorState | null) => void;
+  shipmentId: string;
+  evidence: SelectedEvidence[];
+}) {
+  return (
+    <OptionalFields
+      title="Commercial context (optional)"
+      description="Source declarations only. Off by default; no quote acceptance or completeness is inferred."
+      defaultOpen={false}
+    >
+      <label className="flex min-h-11 items-center gap-2">
+        <input
+          type="checkbox"
+          checked={value !== null}
+          onChange={(event) => onChange(event.target.checked ? newCommercialEditor() : null)}
+        />
+        Include commercial context
+      </label>
+      {value && (
+        <CommercialFields
+          value={value}
+          onChange={onChange}
+          shipmentId={shipmentId}
+          evidence={evidence}
+        />
+      )}
+    </OptionalFields>
+  );
+}
+function CommercialFields({
+  value,
+  onChange,
+  shipmentId,
+  evidence,
+}: {
+  value: CommercialEditorState;
+  onChange: (value: CommercialEditorState) => void;
+  shipmentId: string;
+  evidence: SelectedEvidence[];
+}) {
+  const [revision, setRevision] = useState(0);
+  const [offset, setOffset] = useState(0);
+  const legs = useConditionQuery<FreightCommercialLegsQuery>(
+    FreightCommercialLegsDocument,
+    { shipmentId, pagination: { limit: 25, offset } },
+    revision
+  );
+  const current = legs.data?.shipment?.id === shipmentId ? legs.data.shipment.legs : undefined;
+  // Only this page is loaded. Off-page pins retain their original revisions; the server checks all selected pins.
+  const matching =
+    !!current &&
+    current.every(
+      (leg) =>
+        leg.shipmentId === shipmentId &&
+        !value.selectedLegs.some(
+          (pin) => pin.id === leg.id && pin.expectedUpdatedAt !== leg.updatedAt
+        )
+    );
+  const changePage = (next: number) => {
+    onChange({ ...value, reviewed: null });
+    setOffset(next);
+  };
+  return (
+    <div className="min-w-0 space-y-5">
+      <p className="text-sm">
+        All eight facts start Unknown: “Not recorded for this cost version”. Edit that explanation
+        when useful. Sourced and not-applicable declarations require explicit provenance; shipment
+        details are never copied into these facts.
+      </p>
+      <section className="space-y-3 rounded border p-3">
+        <h3 className="font-semibold">Review selected shipment legs</h3>
+        <p className="text-sm">
+          Select only the legs covered by this source. No selection does not mean all legs. Review
+          the loaded selection explicitly before saving.
+        </p>
+        <ReuseState loading={legs.loading} error={legs.error} />
+        {current?.map((leg) => {
+          const selected = value.selectedLegs.some((pin) => pin.id === leg.id);
+          return (
+            <label key={leg.id} className="flex min-h-11 items-center gap-2">
+              <input
+                type="checkbox"
+                checked={selected}
+                disabled={!selected && value.selectedLegs.length >= 16}
+                onChange={() =>
+                  onChange({
+                    ...value,
+                    reviewed: null,
+                    selectedLegs: selected
+                      ? value.selectedLegs.filter((pin) => pin.id !== leg.id)
+                      : [...value.selectedLegs, { id: leg.id, expectedUpdatedAt: leg.updatedAt }],
+                  })
+                }
+              />
+              <span>
+                Leg {leg.legNumber} — {leg.mode}; carrier {leg.carrierName ?? 'not recorded'};
+                updated {leg.updatedAt}
+              </span>
+            </label>
+          );
+        })}
+        {current?.length === 0 && <p>No legs on this loaded page.</p>}
+        <p className="text-sm">
+          Leg page {Math.floor(offset / 25) + 1}; at most 25 records per page. Off-page selections
+          keep their original revisions.
+        </p>
+        <div className="flex flex-wrap gap-3">
+          <Button
+            type="button"
+            variant="outline"
+            disabled={offset === 0 || legs.loading}
+            onClick={() => changePage(Math.max(0, offset - 25))}
+          >
+            Previous leg page
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            disabled={legs.loading || !!legs.error || current?.length !== 25}
+            onClick={() => changePage(offset + 25)}
+          >
+            Next leg page
+          </Button>
+        </div>
+        {value.selectedLegs.map((pin) => (
+          <div key={pin.id} className="flex flex-wrap items-center gap-2 break-all text-sm">
+            <p>
+              Selected leg {pin.id}; pinned revision {pin.expectedUpdatedAt}.
+            </p>
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() =>
+                onChange({
+                  ...value,
+                  reviewed: null,
+                  selectedLegs: value.selectedLegs.filter((row) => row.id !== pin.id),
+                })
+              }
+            >
+              Remove selected leg {pin.id}
+            </Button>
+          </div>
+        ))}
+        <p>{value.selectedLegs.length} of 16 legs selected.</p>
+        {!matching && value.selectedLegs.length > 0 && (
+          <p role="alert">
+            A selected leg on this page changed or the page does not match this shipment. Explicitly
+            remove it and review the current selection; no revision is rebound automatically.
+          </p>
+        )}
+        <div className="flex flex-wrap gap-3">
+          <Button
+            type="button"
+            variant="outline"
+            onClick={() => {
+              onChange({ ...value, reviewed: null });
+              setRevision((n) => n + 1);
+            }}
+          >
+            Refresh legs for review
+          </Button>
+          <Button
+            type="button"
+            variant="outline"
+            disabled={legs.loading || !!legs.error || !matching}
+            onClick={() =>
+              onChange({ ...value, reviewed: commercialCanonical(value.selectedLegs) })
+            }
+          >
+            I reviewed this leg selection
+          </Button>
+        </div>
+        {value.reviewed === commercialCanonical(value.selectedLegs) && matching && (
+          <p role="status">
+            This explicit selection of IDs and revisions is reviewed. The server checks every
+            selected leg on save, including off-page pins.
+          </p>
+        )}
+      </section>
+      {(
+        [
+          ['origin', 'destination'],
+          ['carrier', 'service', 'cargo'],
+          ['weight', 'volume', 'equipment'],
+        ] as const
+      ).map((group, index) => (
+        <section key={group[0]} className="space-y-3">
+          <h3 className="font-semibold">
+            {['Locations', 'Carrier, service and cargo', 'Measurements and equipment'][index]}
+          </h3>
+          <div className="grid min-w-0 gap-3 md:grid-cols-2">
+            {group.map((slot) => (
+              <FreightCommercialFactEditor
+                key={slot}
+                slot={slot}
+                value={value.facts[slot]}
+                evidence={evidence}
+                onChange={(fact) => onChange({ ...value, facts: { ...value.facts, [slot]: fact } })}
+              />
+            ))}
+          </div>
+        </section>
+      ))}
+      <p className="text-sm">
+        {commercialSlots.length} declared facts. Owner shipment and leg snapshots are recorded
+        separately by the server.
+      </p>
+    </div>
+  );
+}

package/src/movethewheels/components/freight-cost/FreightCommercialFactEditor.tsx

@@ -0,0 +1,258 @@
+import { useState } from 'react';
+import { Button } from '../ui';
+import { FreightSelect, FreightText } from './FreightFields';
+import { freightInstant, freightLocalTime } from '../../utils/freightDraft';
+import {
+  newCommercialFact,
+  type CommercialSlot,
+  type CommercialFactDraft,
+} from '../../utils/freightCommercial';
+import type { SelectedEvidence } from '../ContainerEvidencePicker';
+
+export function FreightCommercialFactEditor({
+  slot,
+  value,
+  onChange,
+  evidence,
+}: {
+  slot: CommercialSlot;
+  value: CommercialFactDraft;
+  onChange: (value: CommercialFactDraft) => void;
+  evidence: SelectedEvidence[];
+}) {
+  const [editingReason, setEditingReason] = useState(false);
+  const label = slot[0].toUpperCase() + slot.slice(1);
+  const patch = (values: Partial<CommercialFactDraft>) => onChange({ ...value, ...values });
+  return (
+    <fieldset className="min-w-0 space-y-3 rounded border p-3">
+      <legend className="px-1 font-semibold">{label}</legend>
+      <FreightSelect
+        label={`${label} status`}
+        value={value.status}
+        onChange={(status) => {
+          if (status === 'UNKNOWN' || status === 'SOURCED' || status === 'NOT_APPLICABLE') {
+            setEditingReason(false);
+            onChange(newCommercialFact(status));
+          }
+        }}
+      >
+        <option value="UNKNOWN">Unknown — not recorded</option>
+        <option value="SOURCED">Sourced</option>
+        <option value="NOT_APPLICABLE">Not applicable</option>
+      </FreightSelect>
+      {value.status === 'UNKNOWN' && !editingReason && (
+        <div className="flex flex-wrap items-center gap-2">
+          <p>{value.reason}</p>
+          <Button type="button" variant="outline" onClick={() => setEditingReason(true)}>
+            Edit {label.toLowerCase()} reason
+          </Button>
+        </div>
+      )}
+      {(value.status === 'NOT_APPLICABLE' || (value.status === 'UNKNOWN' && editingReason)) && (
+        <FreightText
+          label={`${label} reason`}
+          value={value.reason}
+          required
+          onChange={(reason) => patch({ reason })}
+        />
+      )}
+      {value.status === 'SOURCED' && (
+        <CommercialFactValue slot={slot} label={label} value={value} patch={patch} />
+      )}
+      {value.status !== 'UNKNOWN' && (
+        <CommercialFactSource label={label} value={value} patch={patch} evidence={evidence} />
+      )}
+    </fieldset>
+  );
+}
+
+interface FactFieldsProps {
+  label: string;
+  value: CommercialFactDraft;
+  patch: (values: Partial<CommercialFactDraft>) => void;
+}
+function CommercialFactValue({
+  slot,
+  label,
+  value,
+  patch,
+}: FactFieldsProps & { slot: CommercialSlot }) {
+  return (
+    <>
+      {(slot === 'origin' || slot === 'destination') && (
+        <>
+          <FreightSelect
+            label={`${label} label kind`}
+            value={value.kind}
+            onChange={(kind) => patch({ kind })}
+          >
+            <option value="">Choose a label kind</option>
+            {[
+              'ADDRESS_LABEL',
+              'PORT_LABEL',
+              'TERMINAL_LABEL',
+              'POSTCODE_LABEL',
+              'CUSTOM_LABEL',
+            ].map((kind) => (
+              <option key={kind} value={kind}>
+                {kind.replaceAll('_', ' ').toLowerCase()}
+              </option>
+            ))}
+          </FreightSelect>
+          <FreightText
+            label={`${label} jurisdiction label (optional)`}
+            value={value.jurisdiction}
+            onChange={(jurisdiction) => patch({ jurisdiction })}
+          />
+        </>
+      )}
+      {slot === 'carrier' && (
+        <FreightText
+          label="Carrier reference"
+          value={value.reference}
+          required
+          onChange={(reference) => patch({ reference })}
+        />
+      )}
+      {slot !== 'weight' && slot !== 'volume' && (
+        <FreightText
+          label={
+            slot === 'cargo'
+              ? 'Cargo classification label'
+              : slot === 'equipment'
+                ? 'Equipment type label'
+                : `${label} label`
+          }
+          value={value.label}
+          required
+          onChange={(label) => patch({ label })}
+        />
+      )}
+      {slot === 'cargo' && (
+        <FreightText
+          label="Cargo description"
+          value={value.description}
+          required
+          onChange={(description) => patch({ description })}
+        />
+      )}
+      {(slot === 'weight' || slot === 'volume') && (
+        <>
+          <FreightText
+            label={`${label} amount`}
+            value={value.amount}
+            required
+            onChange={(amount) =>
+              patch({ amount, zeroReason: amount === '0' ? value.zeroReason : '' })
+            }
+          />
+          <FreightSelect
+            label={`${label} recorded unit`}
+            value={value.unit}
+            onChange={(unit) => patch({ unit })}
+          >
+            <option value="">Choose a unit</option>
+            {(slot === 'weight' ? ['KG', 'TONNE', 'LB'] : ['M3', 'FT3']).map((unit) => (
+              <option key={unit} value={unit}>
+                {unit}
+              </option>
+            ))}
+          </FreightSelect>
+          {value.amount === '0' && (
+            <FreightText
+              label={`${label} recorded zero reason`}
+              value={value.zeroReason}
+              required
+              onChange={(zeroReason) => patch({ zeroReason })}
+            />
+          )}
+          <p className="text-sm">Record the source unit. No conversion is inferred.</p>
+        </>
+      )}
+      {slot === 'equipment' && (
+        <FreightText
+          label="Equipment count"
+          value={value.count}
+          required
+          onChange={(count) => patch({ count })}
+        />
+      )}
+    </>
+  );
+}
+function CommercialFactSource({
+  label,
+  value,
+  patch,
+  evidence,
+}: FactFieldsProps & { evidence: SelectedEvidence[] }) {
+  return (
+    <>
+      <h4 className="font-medium">{label} source declaration</h4>
+      <FreightText
+        label={`${label} source reference`}
+        value={value.sourceReference}
+        required
+        onChange={(sourceReference) => patch({ sourceReference })}
+      />
+      <FreightText
+        label={`${label} source revision`}
+        value={value.sourceRevision}
+        required
+        onChange={(sourceRevision) => patch({ sourceRevision })}
+      />
+      <FreightText
+        label={`${label} observed at (local time, optional)`}
+        type="datetime-local"
+        value={value.observedAt ? freightLocalTime(value.observedAt) : ''}
+        onChange={(time) => patch({ observedAt: time ? freightInstant(time) : '' })}
+      />
+      <p className="text-sm">
+        Blank observation time is recorded as Unknown. No date is inferred from the upload or file
+        check.
+      </p>
+      <p className="text-sm">
+        Choose 1–2 versions from the evidence selected below for this record. This declares the
+        source; it does not verify its authority.
+      </p>
+      {evidence.map((item) => {
+        const selected = value.evidenceLinks.some(
+          (link) => link.fileId === item.fileId && link.versionId === item.versionId
+        );
+        return (
+          <label
+            key={item.versionId}
+            className="flex min-h-11 items-center gap-2 break-words text-sm"
+          >
+            <input
+              type="checkbox"
+              checked={selected}
+              disabled={!selected && value.evidenceLinks.length >= 2}
+              onChange={() =>
+                patch({
+                  evidenceLinks: selected
+                    ? value.evidenceLinks.filter(
+                        (link) =>
+                          !(link.fileId === item.fileId && link.versionId === item.versionId)
+                      )
+                    : [...value.evidenceLinks, { fileId: item.fileId, versionId: item.versionId }],
+                })
+              }
+            />
+            {item.label}
+          </label>
+        );
+      })}
+      {!evidence.length && <p>Select an exact Files version in Evidence for this record.</p>}
+      {value.evidenceLinks.some(
+        (link) =>
+          !evidence.some((item) => item.fileId === link.fileId && item.versionId === link.versionId)
+      ) && (
+        <p role="alert">
+          A linked evidence version was removed. Select the fact status again and review its source
+          links before saving.
+        </p>
+      )}
+    </>
+  );
+}

package/src/movethewheels/components/freight-cost/FreightCommercialHistory.tsx

@@ -0,0 +1,90 @@
+import type { FreightCommercialVersionQuery } from '../../../generated/freight-cost-operations';
+import { commercialSlots } from '../../utils/freightCommercial';
+import { freightLabel } from '../../utils/freightDraft';
+
+export function FreightCommercialHistory({
+  capture,
+}: {
+  capture: FreightCommercialVersionQuery['mtwFreightEstimateVersion']['commercialCapture'];
+}) {
+  if (capture === undefined)
+    return <p role="alert">Commercial context is unavailable in this reply.</p>;
+  if (capture === null) return <p>Commercial context was not captured with this version.</p>;
+  return (
+    <section className="min-w-0 space-y-4 break-words rounded border p-4">
+      <h3 className="font-semibold">
+        Recorded commercial context — schema {capture.schemaVersion}
+      </h3>
+      <p className="text-sm">
+        These are source declarations, not quote acceptance, verified authority or a complete
+        commercial checklist.
+      </p>
+      <div className="grid min-w-0 gap-3 md:grid-cols-2">
+        {commercialSlots.map((slot) => {
+          const fact = capture[slot];
+          return (
+            <article key={slot} className="space-y-2 rounded border p-3">
+              <h4 className="font-medium">
+                {freightLabel(slot)} — {freightLabel(fact.status)}
+              </h4>
+              {fact.reason && <p>{fact.reason}</p>}
+              {typeof fact.value === 'string' ? (
+                <p>{fact.value}</p>
+              ) : (
+                fact.value && (
+                  <dl>
+                    {Object.entries(fact.value)
+                      .filter(([key]) => key !== '__typename')
+                      .map(([key, value]) => (
+                        <div key={key}>
+                          <dt className="inline font-medium">{key}: </dt>
+                          <dd className="inline">
+                            {value === null || value === undefined ? 'Not recorded' : String(value)}
+                          </dd>
+                        </div>
+                      ))}
+                  </dl>
+                )
+              )}
+              {fact.provenance && (
+                <div className="text-sm">
+                  <p>
+                    Declared source {fact.provenance.sourceReference} /{' '}
+                    {fact.provenance.sourceRevision}; observed{' '}
+                    {fact.provenance.observedAt ?? 'Unknown'}.
+                  </p>
+                  {fact.provenance.evidenceLinks.map((link) => (
+                    <p key={JSON.stringify([link.fileId, link.versionId])}>
+                      Exact Files link: {link.fileId}; version {link.versionId}.
+                    </p>
+                  ))}
+                </div>
+              )}
+            </article>
+          );
+        })}
+      </div>
+      <section className="space-y-2">
+        <h4 className="font-medium">
+          Server-recorded owner context (separate from declared facts)
+        </h4>
+        <p>
+          Shipment {capture.ownerShipment.shipmentId}; revision at {capture.ownerShipment.updatedAt}
+          ; mode {capture.ownerShipment.primaryMode}.
+        </p>
+        {capture.ownerLegs.length === 0 && (
+          <p>No legs selected for this capture. This does not mean the shipment has no legs.</p>
+        )}
+        {capture.ownerLegs.map((leg) => (
+          <p key={leg.id}>
+            Leg {leg.legNumber} ({leg.id}) / {leg.mode}; revision {leg.updatedAt}; carrier{' '}
+            {leg.carrierName ?? 'Not recorded'} ({leg.carrierId ?? 'No carrier reference'}); weight{' '}
+            {leg.weightKg ?? 'Not recorded'} kg; volume {leg.volumeCbm ?? 'Not recorded'} m³;
+            equipment {leg.containerType ?? 'Not recorded'} × {leg.containerCount ?? 'Not recorded'}
+            .
+          </p>
+        ))}
+      </section>
+    </section>
+  );
+}

package/src/movethewheels/components/freight-cost/FreightDraftForm.tsx

@@ -1,4 +1,7 @@
 import { useRef, useState } from 'react';
+import type { CommercialCapture, CommercialEditorState } from '../../utils/freightCommercial';
+import { commercialCaptureInput, commercialCanonical } from '../../utils/freightCommercial';
+import { FreightCommercialEditor } from './FreightCommercialEditor';
 import type {
   MtwFreightFactsInput,
   PreviewFreightCostsQuery,
@@ -18,15 +21,22 @@ import {
 } from '../../utils/freightDraft';
 export function FreightDraftForm({
   disabled,
+  shipmentId,
   onPreview,
   onSave,
 }: {
   disabled: boolean;
+  shipmentId: string;
   onPreview: (
     facts: MtwFreightFactsInput
   ) => Promise<PreviewFreightCostsQuery['previewMtwFreightTotal']>;
-  onSave: (facts: MtwFreightFactsInput, evidence: SelectedEvidence[]) => Promise<void>;
+  onSave: (
+    facts: MtwFreightFactsInput,
+    evidence: SelectedEvidence[],
+    commercialCapture?: CommercialCapture
+  ) => Promise<void>;
 }) {
+  const [commercial, setCommercial] = useState<CommercialEditorState | null>(null);
   const [facts, setFacts] = useState(newFreightFacts);
   const [evidence, setEvidence] = useState<SelectedEvidence[]>([]);
   const [preview, setPreview] = useState<{
@@ -65,9 +75,22 @@ export function FreightDraftForm({
           return;
         }
         setError(null);
-        void onSave(structuredClone(facts), structuredClone(evidence)).catch((failure) =>
-          setError(failure instanceof Error ? failure.message : 'Unable to save this cost record.')
-        );
+        try {
+          if (commercial && commercial.reviewed !== commercialCanonical(commercial.selectedLegs))
+            throw new Error('Explicitly review the commercial leg selection before saving.');
+          const capture = commercial
+            ? commercialCaptureInput(commercial.facts, commercial.selectedLegs, evidence)
+            : undefined;
+          void onSave(structuredClone(facts), structuredClone(evidence), capture).catch((failure) =>
+            setError(
+              failure instanceof Error ? failure.message : 'Unable to save this cost record.'
+            )
+          );
+        } catch (failure) {
+          setError(
+            failure instanceof Error ? failure.message : 'Review commercial facts before saving.'
+          );
+        }
       }}
     >
       <fieldset disabled={disabled || previewing} className="space-y-5">
@@ -194,6 +217,12 @@ export function FreightDraftForm({
           )}
           <FreightFxEditor value={facts.fx} onChange={(fx) => patch({ fx })} />
         </details>
+        <FreightCommercialEditor
+          value={commercial}
+          onChange={setCommercial}
+          shipmentId={shipmentId}
+          evidence={evidence}
+        />
         <ContainerEvidencePicker
           value={evidence}
           onChange={setEvidence}

package/src/movethewheels/components/freight-cost/FreightHistory.tsx

@@ -1,10 +1,11 @@
-import type { FreightVersionQuery } from '../../../generated/freight-cost-operations';
+import { FreightCommercialHistory } from './FreightCommercialHistory';
+import type { FreightCommercialVersionQuery } from '../../../generated/freight-cost-operations';
 import { FreightTotals } from './FreightTotals';
 import { freightLabel, freightMoney } from '../../utils/freightDraft';
 export function FreightHistory({
   record,
 }: {
-  record: FreightVersionQuery['mtwFreightEstimateVersion'];
+  record: FreightCommercialVersionQuery['mtwFreightEstimateVersion'];
 }) {
   return (
     <article className="min-w-0 space-y-4 break-words rounded border p-4">
@@ -28,6 +29,7 @@ export function FreightHistory({
         Price at {record.facts.pricingAt}; recorded {record.recordedAt} by {record.createdBy} (
         {freightLabel(record.actorProvenance)}).
       </p>
+      <FreightCommercialHistory capture={record.commercialCapture} />
       <FreightTotals value={record.totals} currency={record.facts.reportingCurrency} />
       <details>
         <summary className="min-h-11 cursor-pointer font-medium">