Generic Shipment Options UI for Carrier-Specific Fields

[ChrisNolan]

Generic Shipment Options UI for Carrier-Specific Fields

Summary

The dashboard currently supports only a subset of shipment options in a consistent way across create-label flows. Carrier-specific options are not surfaced uniformly, which makes valid provider options (for example FedEx customer reference-related fields like fedex_po_number) harder to populate from UI.

This proposal adds a generic, metadata-driven shipment options UI so any carrier option exposed by API references can be configured from the dashboard without one-off form work.

This came about after #1089

Problem

• Shipment options are the correct payload surface for carrier request behavior, but UI coverage is incomplete.
• The three create-label flows have inconsistent option rendering behavior:
  • packages/core/modules/Labels/create_labels.tsx includes typed dynamic rendering.
  • packages/core/modules/Shipments/create_label.tsx and packages/core/modules/Orders/create_label.tsx are more limited and not fully generic.
• Result: valid carrier options exist in API but are not discoverable/editable consistently in UI.

Goals

• Provide one reusable, generic UI renderer for shipment options.
• Support common carrier option types from references metadata (boolean, string, number, enum, list).
• Keep options in shipment.options with canonical keys.
• Reuse existing references metadata and active connection filtering.
• Avoid adding provider-specific hardcoded fields for each carrier.

Non-Goals

• Changing carrier SDK behavior or option semantics.
• Moving carrier request fields into metadata.
• Redesigning all shipment form UX in this pass.

Proposed Approach

1. Extract a shared component (for example CarrierShipmentOptionsForm) in packages/ui.
2. Feed component with:
   • active carrier option keys from useConnections().carrierOptions
   • option metadata from useAPIMetadata().references.options
   • current shipment.options
3. Render fields by metadata type:
   • boolean -> checkbox
   • string -> text input
   • number -> numeric input
   • enum -> select
   • list -> multi-select/token input (or staged fallback to comma-separated input)
4. Keep all writes flat in shipment.options[optionKey].
5. Replace duplicated carrier option sections in:
   • packages/core/modules/Shipments/create_label.tsx
   • packages/core/modules/Orders/create_label.tsx
   • packages/core/modules/Labels/create_labels.tsx
6. Preserve the existing fixed "Common Options" section for high-frequency fields, but keep it bound to the same shipment.options object.

UX Notes

• Group by carrier with collapsible sections.
• Show human label from references metadata, fallback to formatted key.
• Show helper text/placeholder when available.
• Keep advanced options collapsed by default.

Acceptance Criteria

• A user can set fedex_po_number from all create-label flows.
• Carrier-specific options render consistently across all three flows.
• Option values are persisted into shipment.options and included in purchase payload.
• Existing fixed options continue to work.
• No regression in shipment create/purchase workflows.

Testing Plan

• Unit tests for option renderer type mapping.
• UI interaction tests for boolean/string/enum updates.
• Manual verification with at least one carrier exposing multiple option types.
• Smoke test create-label flows for Shipments, Orders, and Labels modules.

Risks

• Metadata quality may vary across carriers (missing types/labels).
• List/enum handling may need graceful fallbacks.
• Slight UX complexity increase in advanced section.

Mitigations

• Use robust fallback rendering for unknown/missing metadata.
• Keep advanced options collapsed.
• Instrument and monitor option usage before broad UX expansion.

Rollout

• Phase 1: shared renderer + Shipments flow.
• Phase 2: Orders and Labels flows.
• Phase 3: polish and option-type enhancements based on feedback.

[ChrisNolan]

When working with #1095 and doing more options this came up again. The above was a bit too strict -- there is some ability atm in the create_labels for example where it does way to render carrierOptions in the list of shipping options -- but it only handle's boolean options and not the other types.

It also wasn't immediately clear when the 'carrierOptions' was populated because the shipping options show right away, but you don't select the carrier until later. Also in that case, how does it handle you entering options for one carrier, then changing to another carrier, and maybe switching back again in the UI 🤔