@vtex/faststore-plugin-buyer-portal 2.0.7 → 2.0.9

package/specs/suma-remove-contracts.md

@@ -0,0 +1,233 @@
+# SUMA: Remove Contracts from Organizational Unit
+
+> **Status**: Done
+> **Created**: 2026-06-23
+
+## 1. Business Context
+
+### Problem Statement
+
+Admins managing a Buyer Organization need to remove contracts that are no longer relevant to an Organizational Unit (OU). Without a remove flow, contracts accumulate on OUs indefinitely — buyers continue to see stale options during store navigation and checkout, and admins have no self-service way to correct the OU's contract pool.
+
+### Goals
+
+- Admins can remove one or more contracts from an OU in a single action.
+- The system prevents removing all contracts from an OU (at least one must always remain).
+- The OU's contract listing reflects removals immediately after confirmation.
+
+### User Stories
+
+#### US-1: Remove Selected Contracts
+
+- **Story**: As an admin, I want to select one or more contracts and remove them from my OU, so that buyers in that unit can no longer access those contracts.
+- **Acceptance Criteria**:
+  - **Given** an admin is on the Contract Listing page with ≥2 contracts, **when** they select one or more contracts and click "Remove" in the selection toolbar, **then** a confirmation drawer opens showing the count and OU name.
+  - **Given** the confirmation drawer is open, **when** the admin clicks "Remove", **then** the selected contracts are removed via parallel BFF calls and disappear from the listing.
+  - **Given** the removal is in progress, **when** the BFF calls are pending, **then** the confirm button shows a loading state and cannot be clicked again.
+  - **Given** the BFF calls succeed, **when** the drawer closes, **then** a success toast appears and the selection is cleared.
+  - **Given** the confirmation drawer is open, **when** the admin clicks "Cancel" or the backdrop, **then** the drawer closes and no BFF call is made.
+
+#### US-2: Guard — Cannot Remove All Contracts
+
+- **Story**: As a system, I must ensure at least one contract always remains on an OU, so that buyers always have a contract available during checkout.
+- **Acceptance Criteria**:
+  - **Given** an OU has exactly N contracts, **when** an admin selects all N contracts and clicks "Remove", **then** instead of the confirmation drawer, the "Unable to remove" drawer opens explaining the constraint.
+  - **Given** the "Unable to remove" drawer is open, **when** the admin clicks "Got it", **then** the drawer closes and no BFF call is made.
+
+#### US-3: BFF Error Handling
+
+- **Story**: As an admin, I want to be informed when a removal fails, so that I can retry or investigate.
+- **Acceptance Criteria**:
+  - **Given** one or more BFF DELETE calls fail, **when** the hook reports an error, **then** the confirmation drawer closes, an error toast appears on the listing page, and the listing is refreshed to reflect any partial changes.
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected Result |
+|---|---|---|---|
+| Happy path — remove single contract | OU has ≥2 contracts; admin selects 1 | Select 1 → click Remove in toolbar → click Remove in drawer | Contract removed; listing refreshes; success toast shown; selection cleared |
+| Happy path — remove multiple contracts | OU has ≥3 contracts; admin selects 2 | Select 2 → click Remove → confirm | 2 contracts removed; listing refreshes; toast: "2 contracts removed successfully" |
+| Guard — attempt to remove all | OU has exactly 2 contracts; admin selects both | Select all → click Remove | "Unable to remove" drawer opens; no BFF call; listing unchanged |
+| BFF error (one fails) | BFF returns 5xx on one DELETE | Select 2 → confirm | Drawer closes; error toast; listing refreshes (partial state reflected) |
+| Cancel before confirm | Admin opens confirm drawer | Click Cancel or backdrop | Drawer closes; no BFF call; listing unchanged; selection preserved |
+| Cmd+A then remove | OU has 3 contracts | Cmd+A → click Remove in toolbar | Guard triggers: "Unable to remove" drawer opens (all selected = all contracts) |
+
+### Functional Requirements
+
+- **FR-1**: The selection toolbar "Remove" button MUST be visible only when `selectedIds.size > 0` and `isSingleContract === false`.
+- **FR-2**: Before opening the confirmation drawer, the layout MUST check if `selectedIds.size === contracts.length`. If true, open the "Unable to remove" drawer instead.
+- **FR-3**: The `ConfirmRemoveDrawer` MUST display the count of contracts being removed and the OU name.
+- **FR-4**: On confirmation, each selected contract ID MUST be removed via a separate `DELETE units/{orgUnitId}/contracts/attached/{contractId}` call, executed in parallel via `Promise.allSettled`.
+- **FR-5**: While removal is in progress, the confirm button MUST show a loading state and be disabled.
+- **FR-6**: On full or partial BFF failure, an error toast MUST appear and the listing MUST refresh.
+- **FR-7**: On success, the selection MUST be cleared and the listing MUST refresh via `router.replace(router.asPath)`.
+- **FR-8**: A success toast MUST appear after successful removal.
+- **FR-9**: The `ErrorRemoveDrawer` ("Unable to remove") MUST explain the ≥1 contract constraint and show only a "Got it" dismiss button.
+
+### Non-Functional Requirements
+
+- Each DELETE call MUST complete within 5 seconds; parallel calls run concurrently.
+- Loading indicator MUST appear within 500ms of clicking "Remove" in the confirmation drawer.
+- TypeScript strict mode: zero `any` usage, zero `tsc --noEmit` errors.
+- The feature MUST be gated behind the `suma` feature flag.
+
+### Out of Scope
+
+- Propagating removal to child OUs (API does not expose a batch/cascade param).
+- Undo / restore after removal.
+- Removing the default contract (the listing already prevents navigating away from the default; removal is allowed — the next contract becomes default after reload).
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+A new `useRemoveContracts` hook wraps parallel `removeContractService` calls via `Promise.allSettled`. The hook is wired into `ContractListingLayout`, which already owns the `ContractSelectionList` and will now also render `ConfirmRemoveDrawer` and `ErrorRemoveDrawer`. The guard logic (can't remove all) lives in the layout's `handleRequestRemove` handler, mirroring the prototype.
+
+### Architecture Overview
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant ContractSelectionList
+  participant ContractListingLayout
+  participant ConfirmRemoveDrawer
+  participant ErrorRemoveDrawer
+  participant useRemoveContracts
+  participant BFF
+
+  User->>ContractSelectionList: selects contracts, clicks Remove
+  ContractSelectionList->>ContractListingLayout: onRemove(selectedIds)
+  alt selectedIds.size === contracts.length
+    ContractListingLayout->>ErrorRemoveDrawer: isOpen=true (validation guard)
+    User->>ErrorRemoveDrawer: clicks Got it
+    ErrorRemoveDrawer->>ContractListingLayout: onDismiss
+  else
+    ContractListingLayout->>ConfirmRemoveDrawer: isOpen=true, count, orgUnitName
+    User->>ConfirmRemoveDrawer: clicks Remove
+    ConfirmRemoveDrawer->>useRemoveContracts: removeContracts(orgUnitId, ids)
+    loop for each id (parallel)
+      useRemoveContracts->>BFF: DELETE /units/{orgUnitId}/contracts/attached/{id}
+    end
+    BFF-->>useRemoveContracts: results (allSettled)
+    alt all succeeded
+      useRemoveContracts-->>ContractListingLayout: onSuccess()
+      ContractListingLayout->>ContractListingLayout: clearSelection + router.replace
+      ContractListingLayout->>User: success toast
+    else any failed
+      useRemoveContracts-->>ContractListingLayout: onError()
+      ContractListingLayout->>User: error toast + router.replace
+    end
+  end
+```
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| Sequential DELETE calls (one at a time) | Simple error attribution | Slow for multi-select | Rejected — parallel is faster and matches prototype behavior |
+| Single batch DELETE endpoint | One round-trip | Does not exist in the current API spec | Rejected — not available |
+| Guard via disabled button (prevent selecting all) | No secondary drawer needed | Poor UX — prevents Cmd+A; not prototype-validated | Rejected — secondary "Unable to remove" drawer is the prototype pattern |
+| Toast instead of ConfirmRemoveDrawer | Fewer interactions | No confirmation for destructive action; does not match prototype | Rejected — confirmation is required for destructive actions |
+
+### Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| Partial failure (some DELETEs succeed, some fail) | Med — inconsistent state | Low | `Promise.allSettled` captures all results; show error toast + refresh listing to reflect actual state |
+| Default contract removed | Med — OU has no default | Low | Listing refresh lets the SSR pick a new default; no special client-side handling needed |
+
+### Key Decisions
+
+#### Decision 1: Parallel Removes via `Promise.allSettled`
+
+- **Status**: Accepted
+- **Context**: The API has no batch DELETE endpoint. Multi-select removal would be sequential otherwise.
+- **Decision**: Call `removeContractService` for each selected ID concurrently using `Promise.allSettled`. Report success only if all resolved; otherwise report error and refresh.
+- **Consequences**: Fast for multi-select. Partial failures are surfaced via error toast; listing reflects actual server state after refresh.
+
+#### Decision 2: Guard Logic in Layout, Not in `useRemoveContracts`
+
+- **Status**: Accepted
+- **Context**: The "can't remove all" constraint is a UI-level rule, not a BFF enforcement (BFF would allow it).
+- **Decision**: `ContractListingLayout.handleRequestRemove` checks `selectedIds.size === contracts.length` before opening the confirmation drawer. If guard triggers, open `ErrorRemoveDrawer` instead.
+- **Consequences**: Guard is co-located with the data it checks (`contracts`). Hook stays pure — only concerns itself with calling the service.
+
+#### Decision 3: Reuse Existing Drawer Components
+
+- **Status**: Accepted
+- **Context**: `ConfirmRemoveDrawer` and `ErrorRemoveDrawer` components already exist as stubs. `ErrorRemoveDrawer` currently has "BFF error" messaging; the prototype uses it for the validation case.
+- **Decision**: Update `ConfirmRemoveDrawer` to accept `count` and render dynamic text. Update `ErrorRemoveDrawer` to match the prototype's "must keep ≥1" messaging (remove retry; add "Got it"). BFF errors surface as a toast (consistent with `AddContractsDrawer`).
+- **Consequences**: `ErrorRemoveDrawer` becomes the validation guard drawer only. BFF error is handled by toast, not a second drawer.
+
+### Implementation Plan
+
+1. Create `useRemoveContracts` hook — parallel `removeContractService` calls via `Promise.allSettled`; expose `{ removeContracts, isLoading }`.
+2. Update `ConfirmRemoveDrawer` — add `count` prop; render dynamic title and body copy.
+3. Update `ErrorRemoveDrawer` — swap messaging to "Unable to remove contracts" / must keep ≥1 constraint / "Got it" button only.
+4. Update `ContractSelectionList` — wire `onRemove` prop to the toolbar "Remove" button.
+5. Wire `ContractListingLayout` — `handleRequestRemove` guard; open `ConfirmRemoveDrawer` / `ErrorRemoveDrawer`; call `useRemoveContracts`; `onSuccess` refreshes listing and clears selection; `onError` shows error toast and refreshes.
+6. Unit test `useRemoveContracts` — full success, partial failure, all-fail cases.
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+```ts
+// No new data models — operates on existing ContractData.id (string)
+```
+
+### Interfaces
+
+```ts
+// useRemoveContracts hook
+interface UseRemoveContractsOptions {
+  onSuccess: () => void
+  onError: () => void
+}
+
+interface UseRemoveContractsReturn {
+  removeContracts: (params: { orgUnitId: string; ids: string[] }) => Promise<void>
+  isLoading: boolean
+}
+
+// Updated ConfirmRemoveDrawer props
+interface ConfirmRemoveDrawerProps extends Omit<BasicDrawerProps, 'children'> {
+  orgUnitName: string
+  count: number           // number of contracts being removed
+  onConfirm: () => void
+  isLoading?: boolean
+}
+
+// Updated ErrorRemoveDrawer props (validation guard only — no retry)
+interface ErrorRemoveDrawerProps extends Omit<BasicDrawerProps, 'children'> {
+  orgUnitName: string
+}
+
+// Updated ContractSelectionList props
+interface ContractSelectionListProps {
+  // ... existing props
+  onRemove: (ids: Set<string>) => void   // called when toolbar Remove is clicked
+}
+```
+
+### Integration Points
+
+| Point | Direction | Details |
+|---|---|---|
+| `removeContractService` | Write | Called once per selected ID; `DELETE units/{orgUnitId}/contracts/attached/{contractId}` |
+| `ContractListingLayout` | Parent | Owns guard logic, drawer states, `onSuccess`/`onError` callbacks |
+| `ContractSelectionList` | Child | Receives `onRemove` prop; fires it on toolbar "Remove" click |
+| `useContractSelection.clearSelection` | Write | Called on success to reset toolbar state |
+| `router.replace(router.asPath)` | Navigation | Refreshes listing SSR data after removal (same as add-contracts pattern) |
+| Feature flag `suma` | Gate | Remove entry point only rendered when `featureFlags.suma === true` |
+
+### Invariants & Constraints
+
+- `contracts.length - selectedIds.size` MUST be ≥ 1 before opening `ConfirmRemoveDrawer`; otherwise open `ErrorRemoveDrawer`.
+- The "Remove" toolbar button MUST only appear when `selectedIds.size > 0` AND `isSingleContract === false`.
+- While `isLoading === true`, the confirm button MUST be disabled and the drawer MUST NOT be dismissible via backdrop click.
+- On `ConfirmRemoveDrawer` cancel (backdrop or Cancel button), no BFF call is made and `selectedIds` is unchanged.
+- `useRemoveContracts` MUST use `Promise.allSettled` — a single failed DELETE MUST NOT abort remaining calls.

package/specs/suma-set-default-contract.md

@@ -0,0 +1,208 @@
+# SUMA: Set Default Contract for Organizational Unit
+
+> **Status**: Done
+> **Created**: 2026-06-23
+
+## 1. Business Context
+
+### Problem Statement
+
+Admins managing a Buyer Organization need to designate one contract as the default for an Organizational Unit (OU). The default contract determines which contract is pre-selected during store navigation and checkout. Without a way to change it, the default is fixed at the time contracts are attached and cannot be updated as the OU's commercial priorities evolve.
+
+### Goals
+
+- Admins can mark any non-default attached contract as the default for their OU in a single action.
+- The listing immediately reflects the new default after the action succeeds.
+- The feature is available from both the Contract Listing page and the Profile page (Contract Information).
+
+### User Stories
+
+#### US-1: Set Default from Contract Listing
+
+- **Story**: As an admin, I want to mark a contract as default from the listing page, so that I can change the OU's default contract without navigating away.
+- **Acceptance Criteria**:
+  - **Given** an OU has ≥2 attached contracts and the admin is on the Contract Listing page, **when** they open the dots menu for a non-default contract and click "Set as default", **then** a BFF PUT call is made and the listing refreshes to show the new default badge.
+  - **Given** the BFF call succeeds, **then** a success toast appears.
+  - **Given** the BFF call fails, **then** an error toast appears and the listing is refreshed to reflect actual server state.
+  - **Given** a contract is already the default (`isDefault === true`), **when** the admin opens its dots menu, **then** the "Set as default" item is disabled (greyed out, not clickable).
+
+#### US-2: Set Default from Profile Page (Contract Information)
+
+- **Story**: As an admin, I want to mark a contract as default from its profile page, so that I can update the default while reviewing the contract's settings.
+- **Acceptance Criteria**:
+  - **Given** the admin is on the Profile page (`/profile/[orgUnitId]/[contractId]`) for a non-default contract, **when** they open the three-dot menu in the sidebar and click "Set as default", **then** a BFF PUT call is made and the page header updates to reflect the new default status.
+  - **Given** the BFF call succeeds, **then** a success toast appears.
+  - **Given** the BFF call fails, **then** an error toast appears.
+  - **Given** the contract is already the default, **when** the admin opens the sidebar menu, **then** "Set as default" is disabled.
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected Result |
+|---|---|---|---|
+| Happy path — set default from listing | OU has ≥2 contracts; target contract is not default | Open dots menu → click "Set as default" | PUT call succeeds; listing refreshes; target contract shows default badge; previous default loses badge; success toast |
+| Happy path — set default from profile | Admin is on Profile page for non-default contract | Open sidebar menu → click "Set as default" | PUT call succeeds; page refreshes; success toast |
+| BFF error | BFF returns 5xx | Open dots menu → click "Set as default" | Error toast; listing refreshed to reflect actual state |
+| Already default — listing | Contract has `isDefault === true` | Open dots menu | "Set as default" item is disabled; no BFF call possible |
+| Already default — profile | Admin is on Profile page for default contract | Open sidebar menu | "Set as default" item is disabled |
+| Single contract | OU has exactly 1 contract | — | `ContractSelectionList` not rendered (single-contract path); feature not exposed |
+
+### Functional Requirements
+
+- **FR-1**: "Set as default" MUST be disabled (visually and functionally) when `contract.isDefault === true`.
+- **FR-2**: On click, a `PUT units/{orgUnitId}/contracts/attached/{contractId}/default` call MUST be made with no request body, only the session cookie in the header.
+- **FR-3**: On success, the listing/page MUST refresh via `router.replace(router.asPath)` to reflect updated `isDefault` values from the BFF.
+- **FR-4**: On success, a success toast MUST appear.
+- **FR-5**: On error, an error toast MUST appear; if on the listing page, the listing MUST refresh to reflect actual server state.
+- **FR-6**: While the mutation is in progress, the dots menu trigger MUST be disabled to prevent double-submit.
+- **FR-7**: The "Set as default" dots menu item MUST use `StarOutline` when the contract is not the default, and `Star` (filled) when it already is the default (disabled state). The default badge in `ContractListItem` MUST use `Star` (filled).
+
+### Non-Functional Requirements
+
+- BFF call MUST complete within 5 seconds.
+- Success/error feedback MUST be visible within 500ms of the response.
+- TypeScript strict mode: zero `any` usage, zero `tsc --noEmit` errors.
+- The feature MUST be accessible only when the `suma` feature flag is active (implicit — the entire contracts feature is gated at route level).
+
+### Out of Scope
+
+- Confirmation drawer before setting default (action is non-destructive; direct action is the chosen UX).
+- Propagating the default change to child OUs.
+- Unsetting the default without replacing it (there must always be a default contract).
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+A new `useSetDefaultContract` hook wraps a `setDefaultContractService` (following the same `withClientErrorBoundary` pattern as `useAddContracts` and `useRemoveContracts`). The hook is wired into both `ContractListingLayout` (via `ContractListItem`) and `ContractInformationLayout`. The "Set as default" dots menu item is enabled only when `!contract.isDefault`, and the action is fire-and-refresh (no drawer).
+
+### Architecture Overview
+
+```mermaid
+sequenceDiagram
+  participant Admin
+  participant ContractListItem / ContractInformationLayout
+  participant useSetDefaultContract
+  participant BFF
+
+  Admin->>ContractListItem / ContractInformationLayout: clicks "Set as default"
+  ContractListItem / ContractInformationLayout->>useSetDefaultContract: setDefaultContract({ orgUnitId, contractId })
+  useSetDefaultContract->>BFF: PUT /units/{orgUnitId}/contracts/attached/{contractId}/default
+  alt success
+    BFF-->>useSetDefaultContract: 200 OK
+    useSetDefaultContract-->>ContractListItem / ContractInformationLayout: onSuccess()
+    ContractListItem / ContractInformationLayout->>ContractListItem / ContractInformationLayout: router.replace(router.asPath)
+    ContractListItem / ContractInformationLayout->>Admin: success toast
+  else error
+    BFF-->>useSetDefaultContract: 4xx / 5xx
+    useSetDefaultContract-->>ContractListItem / ContractInformationLayout: onError(error)
+    ContractListItem / ContractInformationLayout->>Admin: error toast + router.replace
+  end
+```
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| Optimistic update (update `isDefault` client-side before BFF responds) | Instant visual feedback | Risk of stale state if BFF fails; `isDefault` is authoritative on server | Rejected — server refresh is simpler and correct |
+| Confirmation drawer before action | Prevents accidental clicks | Extra interaction for a non-destructive action; prototype calls for direct action | Rejected — direct action is the specified UX |
+
+### Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| Race condition — user sets default while previous request is in-flight | Low — duplicate PUT on same contract | Very Low | Disable dots trigger while `isLoading === true` |
+| BFF returns success but listing refresh shows old data (SSR cache) | Med — visual inconsistency | Low | `router.replace(router.asPath)` forces SSR re-fetch; no client-side cache to bust |
+
+### Key Decisions
+
+#### Decision 1: Direct Action — No Confirmation Drawer
+
+- **Status**: Accepted
+- **Context**: "Set as default" is non-destructive (the previous default is not removed, only demoted). The prototype specifies direct action.
+- **Decision**: Click → BFF call → toast. No intermediate confirmation step.
+- **Consequences**: Simpler UX, fewer components needed. Accidental clicks can be corrected by setting another contract as default.
+
+#### Decision 2: Server Refresh Over Optimistic Update
+
+- **Status**: Accepted
+- **Context**: `isDefault` is authoritative on the BFF. Two contracts in the listing have `isDefault` values that must be swapped atomically from the client's perspective.
+- **Decision**: After success, call `router.replace(router.asPath)` to re-run SSR and get the correct `isDefault` values for all contracts.
+- **Consequences**: Slight latency on visual update (~SSR round-trip). Eliminates risk of client-side state diverging from server.
+
+#### Decision 3: Disable "Set as default" When Already Default
+
+- **Status**: Accepted
+- **Context**: Setting the same contract as default twice is a no-op but could confuse users or generate unnecessary BFF calls.
+- **Decision**: When `contract.isDefault === true`, render the `DropdownItem` with the `disabled` prop. Apply the same logic in `ContractInformationLayout`'s sidebar menu.
+- **Consequences**: Clear visual affordance; no guard needed inside the hook/service.
+
+### Implementation Plan
+
+1. Add `setDefaultContract(orgUnitId, contractId, cookie)` method to `ContractsClient`.
+2. Create `set-default-contract.service.ts` wrapped by `withClientErrorBoundary`.
+3. Create `useSetDefaultContract` hook — same pattern as `useRemoveContracts`.
+4. Enable "Set as default" in `ContractListItem` — pass `onSetDefault` prop; enable/disable based on `isDefault`.
+5. Wire `ContractListingLayout` — pass `onSetDefault` handler to `ContractSelectionList` → `ContractListItem`.
+6. Enable "Set as default" in `ContractInformationLayout` — use `useSetDefaultContract` directly in the layout.
+7. Unit test `useSetDefaultContract` and `setDefaultContractService`.
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+```ts
+// No new data models — operates on existing ContractData.isDefault (boolean)
+// ContractData.isDefault is already optional; after this feature it is always present for attached contracts
+```
+
+### Interfaces
+
+```ts
+// ContractsClient — new method
+setDefaultContract(orgUnitId: string, contractId: string, cookie: string): Promise<unknown>
+
+// setDefaultContractService
+interface SetDefaultContractServiceProps {
+  orgUnitId: string
+  contractId: string
+  cookie: string
+}
+
+// useSetDefaultContract hook
+interface UseSetDefaultContractReturn {
+  setDefaultContract: (params: Omit<SetDefaultContractServiceProps, 'cookie'>) => Promise<void> | undefined
+  isSetDefaultContractLoading: boolean
+}
+
+// ContractListItem — updated props
+interface ContractListItemProps {
+  // ... existing props
+  onSetDefault: () => void  // called when "Set as default" is clicked; disabled when contract.isDefault === true
+}
+
+// ContractSelectionList — updated props
+interface ContractSelectionListProps {
+  // ... existing props
+  onSetDefault: (contractId: string) => void
+}
+```
+
+### Integration Points
+
+| Point | Direction | Details |
+|---|---|---|
+| `ContractsClient.setDefaultContract` | Write | `PUT units/{orgUnitId}/contracts/attached/{contractId}/default` — no body, cookie in header |
+| `ContractListingLayout` | Parent (listing) | Owns `useSetDefaultContract`; passes `onSetDefault` down to `ContractSelectionList` → `ContractListItem` |
+| `ContractInformationLayout` | Parent (info page) | Owns its own `useSetDefaultContract` instance; wires the sidebar dropdown item |
+| `router.replace(router.asPath)` | Navigation | Refreshes SSR data after success or error to sync `isDefault` values |
+
+### Invariants & Constraints
+
+- Exactly one contract per OU MUST be `isDefault === true` at any time (enforced by BFF; client does not validate).
+- "Set as default" MUST be disabled (`disabled` prop on `DropdownItem`) when `contract.isDefault === true`.
+- While `isSetDefaultContractLoading === true`, the dots menu trigger MUST be non-interactive.
+- No BFF call is made when the item is disabled — guard is purely visual via `disabled` prop.