refactor(client): render capability-driven form fields from descriptors

Three sections were hand-wiring the same three calls per field — a capability
gate, a required lookup, and an explainer — and the commodity dimensions
repeated all three once per side. CapabilityFields takes that wiring once and
resolves it from the profile.

The renderer lives in packages/shared but never imports a field component. The
inputs live in apps/web, and a shared package reaching for them would invert the
dependency and force every app to carry every other app's fields, so a
descriptor supplies its own input through a render callback.

ruleField exists because a rule names the thing an operator thinks about rather
than the input. The dimension rule names `commodities`, and length, width and
height all answer to it while keeping distinct form paths.

An unresolved profile shows gated fields rather than hiding them: a form that
renders empty and then sprouts inputs once a query settles is worse than briefly
showing a field the profile turns out not to want. This matches what
isCapabilitySectionVisible already did.

General information, service details, the billing field group and the commodity
dialog are converted. Move details is not: it is a field array of move cards
driving an edit dialog, with no flat field list to describe, and forcing it
through a flat renderer would produce worse code than it replaces. The BOL field
also stays hand-written — its required state comes from the customer's billing
profile, not the mode profile.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01559YzTFTKd3vV6eJWmSDzi

Author: claude

client/apps/web/src/routes/shipment/_components/shipment-billing-details.tsx

@@ -6,11 +6,16 @@ import {
 import { NumberField } from "@/components/fields/number-field";
 import { Alert, AlertDescription, AlertTitle } from "@trenova/shared/components/ui/alert";
 import { Badge } from "@trenova/shared/components/ui/badge";
-import { FormControl, FormGroup, FormSection } from "@trenova/shared/components/ui/form";
+import {
+  CapabilityFields,
+  type FieldDescriptor,
+} from "@trenova/shared/components/capability-form-section";
+import { FormSection } from "@trenova/shared/components/ui/form";
 import { Separator } from "@trenova/shared/components/ui/separator";
 import { TextShimmer } from "@trenova/shared/components/ui/text-shimmer";
 import { useShipmentTotalsPreview } from "@/hooks/use-shipment-totals-preview";
 import { queries } from "@/lib/queries";
+import { getProfile } from "@trenova/shared/lib/capability";
 import { cn, formatCurrency } from "@trenova/shared/lib/utils";
 import type { CreditStatus } from "@trenova/shared/types/customer";
 import type { GetPreviousRatesRequest, Shipment } from "@trenova/shared/types/shipment";
@@ -256,6 +261,70 @@ export default function ShipmentBillingDetails() {
     fuelSurchargeChange,
     resolveFuelSurchargeChange,
   } = useShipmentTotalsPreview();
+  const { data: shipmentUIPolicy } = useQuery({ ...queries.shipment.uiPolicy() });
+
+  const profile = getProfile(shipmentUIPolicy);
+
+  const descriptors: FieldDescriptor[] = [
+    {
+      name: "orderId",
+      render: () => (
+        <OrderAutocompleteField
+          control={control}
+          name="orderId"
+          label="Order"
+          placeholder="Select Order"
+          description="Optionally group this shipment under a commercial order for the same customer. Set on creation; use the order's Add Legs afterwards."
+          disabled={!customerId}
+          extraSearchParams={customerId ? { customerId, attachableOnly: "true" } : undefined}
+        />
+      ),
+    },
+    {
+      name: "customerId",
+      render: () => (
+        <CustomerAutocompleteField
+          control={control}
+          name="customerId"
+          rules={{ required: true }}
+          label="Customer"
+          placeholder="Select Customer"
+          description="Choose the customer who requested this shipment."
+        />
+      ),
+    },
+    {
+      name: "formulaTemplateId",
+      cols: "full",
+      render: () => (
+        <FormulaTemplateAutocompleteField
+          control={control}
+          name="formulaTemplateId"
+          label="Rating Method"
+          placeholder="Select Rating Method"
+          description="Select how the shipment charges are calculated (e.g., per mile, per stop, flat rate)."
+          rules={{ required: true }}
+        />
+      ),
+    },
+    {
+      name: "baseRate",
+      cols: "full",
+      render: () => (
+        <NumberField
+          decimalScale={4}
+          thousandSeparator
+          control={control}
+          rules={{ required: true }}
+          name="baseRate"
+          label="Base Rate"
+          placeholder="Enter Base Rate"
+          description="Per-unit rate used by the formula template to calculate freight charges."
+          sideText="USD"
+        />
+      ),
+    },
+  ];
 
   return (
     <Inner>
@@ -265,52 +334,7 @@ export default function ShipmentBillingDetails() {
       />
       {customerId && <CreditHoldAlert customerId={customerId} />}
       {shipmentId && <ProfitabilitySummary shipmentId={shipmentId} />}
-      <FormGroup cols={2}>
-        <FormControl>
-          <OrderAutocompleteField
-            control={control}
-            name="orderId"
-            label="Order"
-            placeholder="Select Order"
-            description="Optionally group this shipment under a commercial order for the same customer. Set on creation; use the order's Add Legs afterwards."
-            disabled={!customerId}
-            extraSearchParams={customerId ? { customerId, attachableOnly: "true" } : undefined}
-          />
-        </FormControl>
-        <FormControl>
-          <CustomerAutocompleteField
-            control={control}
-            name="customerId"
-            rules={{ required: true }}
-            label="Customer"
-            placeholder="Select Customer"
-            description="Choose the customer who requested this shipment."
-          />
-        </FormControl>
-        <FormControl cols="full">
-          <FormulaTemplateAutocompleteField
-            control={control}
-            name="formulaTemplateId"
-            label="Rating Method"
-            placeholder="Select Rating Method"
-            description="Select how the shipment charges are calculated (e.g., per mile, per stop, flat rate)."
-            rules={{ required: true }}
-          />
-        </FormControl>
-        <FormControl cols="full">
-          <NumberField
-            decimalScale={4}
-            thousandSeparator
-            control={control}
-            rules={{ required: true }}
-            name="baseRate"
-            label="Base Rate"
-            placeholder="Enter Base Rate"
-            description="Per-unit rate used by the formula template to calculate freight charges."
-            sideText="USD"
-          />
-        </FormControl>
-      </FormGroup>
+      <CapabilityFields descriptors={descriptors} profile={profile} />
 
       <ChargeSummary isCalculating={isCalculating} error={totalsError} />
       <RatingBreakdownCard />

client/apps/web/src/routes/shipment/_components/shipment-commodities.tsx

@@ -26,9 +26,12 @@ import {
   CAPABILITIES,
   getProfile,
   isCapabilitySectionVisible,
-  isFieldRequired,
 } from "@trenova/shared/lib/capability";
 import { describeCommodityDimensions } from "@trenova/shared/lib/permit";
+import {
+  CapabilityFields,
+  type FieldDescriptor,
+} from "@trenova/shared/components/capability-form-section";
 import { apiService } from "@/services/api";
 import type { Commodity } from "@trenova/shared/types/commodity";
 import type { ResolvedModeProfile, Shipment } from "@trenova/shared/types/shipment";
@@ -71,7 +74,35 @@ function CommodityDialog({
   const { control, setValue, getValues, setError, clearErrors } = useFormContext<Shipment>();
   const [saving, setSaving] = useState(false);
   const showDimensions = isCapabilitySectionVisible(profile, CAPABILITIES.dimensionalCargo);
-  const dimensionsRequired = isFieldRequired(profile, "commodities");
+
+  // The three sides share one rule, one capability gate and one explainer, so
+  // they are described once and rendered by the shared renderer rather than
+  // hand-wired three times.
+  const dimensionDescriptors: FieldDescriptor[] = (
+    [
+      ["lengthFeet", "Length"],
+      ["widthFeet", "Width"],
+      ["heightFeet", "Height"],
+    ] as const
+  ).map(([field, label]) => ({
+    name: `commodities.${index}.${field}`,
+    // The mode profile's dimension rule names `commodities`, not the individual
+    // sides, so that is what resolves the required state.
+    ruleField: "commodities",
+    capability: CAPABILITIES.dimensionalCargo,
+    // One explainer under the group rather than three identical popovers.
+    hideExplainer: true,
+    render: ({ required }) => (
+      <NumberField
+        control={control}
+        name={`commodities.${index}.${field}`}
+        label={label}
+        placeholder="0"
+        sideText="ft"
+        rules={{ required }}
+      />
+    ),
+  }));
 
   function handleCommoditySelected(option: Commodity | null) {
     setValue(`commodities.${index}.commodity`, option ?? undefined);
@@ -178,43 +209,8 @@ function CommodityDialog({
             />
           </FormControl>
         </FormGroup>
-        {showDimensions && (
-          <FormGroup cols={3}>
-            <FormControl>
-              <NumberField
-                control={control}
-                name={`commodities.${index}.lengthFeet`}
-                label="Length"
-                placeholder="0"
-                sideText="ft"
-                rules={{ required: dimensionsRequired }}
-              />
-            </FormControl>
-            <FormControl>
-              <NumberField
-                control={control}
-                name={`commodities.${index}.widthFeet`}
-                label="Width"
-                placeholder="0"
-                sideText="ft"
-                rules={{ required: dimensionsRequired }}
-              />
-            </FormControl>
-            <FormControl>
-              <NumberField
-                control={control}
-                name={`commodities.${index}.heightFeet`}
-                label="Height"
-                placeholder="0"
-                sideText="ft"
-                rules={{ required: dimensionsRequired }}
-              />
-            </FormControl>
-            <FormControl cols="full">
-              <CapabilityExplainer profile={profile} field="commodities" />
-            </FormControl>
-          </FormGroup>
-        )}
+        <CapabilityFields descriptors={dimensionDescriptors} profile={profile} cols={3} />
+        {showDimensions && <CapabilityExplainer profile={profile} field="commodities" />}
         <DialogFooter>
           <Button type="button" variant="outline" onClick={onCancel} disabled={saving}>
             Cancel

client/apps/web/src/routes/shipment/_components/shipment-general-information.tsx

@@ -1,13 +1,11 @@
 import { InputField } from "@/components/fields/input-field";
 import { NumberField } from "@/components/fields/number-field";
-import { CapabilityExplainer } from "@trenova/shared/components/capability-explainer";
-import { FormControl, FormGroup, FormSection } from "@trenova/shared/components/ui/form";
 import {
-  CAPABILITIES,
-  getProfile,
-  isFieldRequired,
-  isCapabilitySectionVisible,
-} from "@trenova/shared/lib/capability";
+  CapabilityFields,
+  type FieldDescriptor,
+} from "@trenova/shared/components/capability-form-section";
+import { FormControl, FormGroup, FormSection } from "@trenova/shared/components/ui/form";
+import { CAPABILITIES, getProfile } from "@trenova/shared/lib/capability";
 import { ApiRequestError } from "@trenova/shared/lib/api";
 import { queries } from "@/lib/queries";
 import { apiService } from "@/services/api";
@@ -33,45 +31,49 @@ export default function ShipmentGeneralInformation() {
   const { data: shipmentUIPolicy } = useQuery({ ...queries.shipment.uiPolicy() });
 
   const profile = getProfile(shipmentUIPolicy);
-  const showTemperature = isCapabilitySectionVisible(
-    profile,
-    CAPABILITIES.temperatureControl,
-  );
-  const temperatureRequired = isFieldRequired(profile, "temperatureMin");
+
+  const descriptors: FieldDescriptor[] = [
+    {
+      name: "temperatureMin",
+      capability: CAPABILITIES.temperatureControl,
+      render: ({ required }) => (
+        <NumberField
+          control={control}
+          name="temperatureMin"
+          description="The minimum temperature for the shipment."
+          label="Temperature Min"
+          placeholder="Enter Temperature Min"
+          sideText="°F"
+          rules={{ required }}
+        />
+      ),
+    },
+    {
+      name: "temperatureMax",
+      capability: CAPABILITIES.temperatureControl,
+      render: ({ required }) => (
+        <NumberField
+          control={control}
+          name="temperatureMax"
+          label="Temperature Max"
+          description="The maximum temperature for the shipment."
+          placeholder="Enter Temperature Max"
+          sideText="°F"
+          rules={{ required }}
+        />
+      ),
+    },
+  ];
 
   return (
     <Inner>
+      {/* The BOL field stays outside the descriptor list: its required state
+          comes from the customer's billing profile, not from the mode profile,
+          so it has nothing for the renderer to resolve. */}
       <FormGroup cols={2}>
         <BOLField />
-        {showTemperature && (
-          <>
-            <FormControl>
-              <NumberField
-                control={control}
-                name="temperatureMin"
-                description="The minimum temperature for the shipment."
-                label="Temperature Min"
-                placeholder="Enter Temperature Min"
-                sideText="°F"
-                rules={{ required: temperatureRequired }}
-              />
-              <CapabilityExplainer profile={profile} field="temperatureMin" />
-            </FormControl>
-            <FormControl>
-              <NumberField
-                control={control}
-                name="temperatureMax"
-                label="Temperature Max"
-                description="The maximum temperature for the shipment."
-                placeholder="Enter Temperature Max"
-                sideText="°F"
-                rules={{ required: isFieldRequired(profile, "temperatureMax") }}
-              />
-              <CapabilityExplainer profile={profile} field="temperatureMax" />
-            </FormControl>
-          </>
-        )}
       </FormGroup>
+      <CapabilityFields descriptors={descriptors} profile={profile} />
     </Inner>
   );
 }
@@ -120,7 +122,14 @@ export function BOLField() {
     return () => {
       if (bolCheckTimer.current != null) clearTimeout(bolCheckTimer.current);
     };
-  }, [bol, shipmentId, shipmentUIPolicy?.checkForDuplicateBols, setError, clearErrors, getFieldState]);
+  }, [
+    bol,
+    shipmentId,
+    shipmentUIPolicy?.checkForDuplicateBols,
+    setError,
+    clearErrors,
+    getFieldState,
+  ]);
 
   const bolRequired = billingProfile?.enforceCustomerBillingReq && billingProfile?.requireBOLNumber;