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

package/specs/suma-contract-listing.md

@@ -0,0 +1,295 @@
+# Feature Specification: SUMA Phase 2 — Contract Listing Page
+
+**Feature Branch**: `feat/suma-listing`
+
+**Created**: 2026-06-17
+
+**Status**: Done
+
+**Parent spec**: `specs/001-suma-phase-2/spec.md` (User Stories 1 & 2)
+
+**Depends on**: `feat/suma-infra` — feature flag, route registration, `listAttachedContractsService`
+
+---
+
+## Business Context
+
+### Problem
+
+When the `suma` feature flag is enabled, the account homepage (`org-unit-details`) must be replaced by a dedicated Contract Listing page. Currently there is no such page. Without it, users with multiple contracts have no way to view, distinguish, or select their contracts under the SUMA Phase 2 flow.
+
+The listing page is the entry point of the new flow: it shows all contracts available to the user's Organizational Unit, highlights the default contract, and supports multi-contract selection via keyboard shortcuts to enable future bulk admin actions (add/remove — implemented in a later task).
+
+### Goals
+
+- Replace `org-unit-details` as the account homepage when `featureFlags.suma === true`.
+- Display all contracts for the Organizational Unit with clear visual hierarchy.
+- Highlight the default contract (`isDefault === true`) with a visual badge.
+- Support multi-select with keyboard shortcuts (Cmd/Ctrl+A, Cmd/Ctrl+Click, Shift+Click).
+- Handle the single-contract edge case: hide removal actions when only one contract exists.
+
+### Out of Scope
+
+- Contract switching (Profile page as Contract Information) — separate task (`specs/suma-contract-switching.md`).
+
+---
+
+## User Scenarios & Testing
+
+### User Story 1 — View Contract Listing as Homepage (Priority: P1)
+
+When the `suma` flag is on, a buyer navigating to the account homepage lands on the Contract Listing page instead of `org-unit-details`.
+
+**Acceptance Scenarios**:
+
+1. **Given** the `suma` feature flag is `true` and the user opens the account homepage, **When** the page loads, **Then** the Contract Listing page is displayed showing all contracts for the user's Organizational Unit.
+2. **Given** the `suma` feature flag is `false`, **When** the user opens the account homepage, **Then** the original `org-unit-details` page is shown with no regression.
+3. **Given** the loader is fetching contracts, **When** the data is pending, **Then** a loading skeleton is displayed.
+4. **Given** the loader fails, **When** the page renders, **Then** the existing `ErrorTabsLayout` is shown.
+
+---
+
+### User Story 2 — Default Contract Highlighted (Priority: P1)
+
+The contract with `isDefault === true` is visually distinguished from other contracts.
+
+**Acceptance Scenarios**:
+
+1. **Given** a contract has `isDefault: true`, **When** the listing renders, **Then** a "Default" badge is displayed on that contract's row.
+2. **Given** no contract has `isDefault: true`, **When** the listing renders, **Then** no badge is shown and all rows look equal.
+
+---
+
+### User Story 3 — Multi-Select with Keyboard Shortcuts (Priority: P2)
+
+A buyer on the Contract Listing page can select multiple contracts using keyboard shortcuts.
+
+**Acceptance Scenarios**:
+
+1. **Given** a buyer is on the Contract Listing page, **When** they press Cmd+A (Mac) or Ctrl+A (Windows/Linux), **Then** all contracts are selected without navigating anywhere.
+2. **Given** a buyer is on the Contract Listing page, **When** they Cmd+Click / Ctrl+Click a contract, **Then** that contract is toggled in the selection without navigating to its detail.
+3. **Given** a buyer has selected one contract and Shift+Clicks another, **Then** all contracts between the two are added to the selection as a range.
+4. **Given** one or more contracts are selected, **When** the buyer clicks a contract without a modifier key, **Then** the selection is cleared and the click proceeds as normal.
+5. **Given** contracts are selected, **When** the selection count is > 0, **Then** a bulk action toolbar appears showing the count and available actions.
+
+---
+
+### User Story 4 — Single-Contract State (Priority: P1)
+
+When the Organizational Unit has exactly one contract, removal actions are hidden.
+
+**Acceptance Scenarios**:
+
+1. **Given** an Organizational Unit has exactly 1 contract, **When** the listing renders, **Then** no "Remove" button or bulk remove action is displayed.
+2. **Given** an Organizational Unit has 2+ contracts, **When** contracts are selected, **Then** the bulk toolbar includes a "Remove" action.
+
+---
+
+### Key Scenarios
+
+| Scenario | Pre-condition | Steps | Expected result |
+|----------|--------------|-------|----------------|
+| **Happy path** | Flag on, unit has 3 contracts, 1 is default | Load page | All 3 contracts listed; default has badge; no selection |
+| **Single contract** | Flag on, unit has 1 contract | Load page | 1 contract shown; no remove action visible |
+| **Cmd+A select all** | Flag on, 3 contracts | Press Cmd+A | All 3 highlighted; bulk toolbar shows count=3 |
+| **Shift+Click range** | Flag on, 3 contracts | Click row 1, Shift+Click row 3 | Rows 1–3 highlighted |
+| **Flag off** | Flag `suma=false` | Load account homepage | `org-unit-details` renders normally |
+| **Load error** | Service throws | Page render | `ErrorTabsLayout` shown |
+| **Empty list** | Unit has 0 contracts | Load page | Empty state shown |
+
+---
+
+## Requirements
+
+### Functional
+
+- **FR-001**: Display all contracts from `listAttachedContractsService` for the current `orgUnitId`.
+- **FR-002**: Show a "Default" badge on the contract where `isDefault === true`.
+- **FR-003**: Show a loading skeleton while the loader is pending.
+- **FR-004**: Show `ErrorTabsLayout` when the loader fails.
+- **FR-005**: Show an empty state when the contract list is empty.
+- **FR-006**: Support Cmd+A / Ctrl+A to select all contracts (no navigation).
+- **FR-007**: Support Cmd+Click / Ctrl+Click to toggle individual contract selection (no navigation).
+- **FR-008**: Support Shift+Click to select a contiguous range.
+- **FR-009**: Show a bulk action toolbar (contract count) when `selectedIds.size > 0`.
+- **FR-010**: Include a "Remove" action in the bulk toolbar only when `contracts.length > 1`.
+- **FR-011**: Hide the "Remove" action entirely when `contracts.length === 1`.
+- **FR-012**: Preserve existing `org-unit-details` behavior when `featureFlags.suma` is `false`.
+
+### Non-functional
+
+- Page must pass `make lint` and `make typecheck` (zero new errors).
+- All new hooks and pure functions must have unit tests.
+
+---
+
+## Arch Decisions
+
+### Decision 1 — Data source
+
+**Use `listAttachedContractsService`** (from `feat/suma-infra`, calls `GET units/{orgUnitId}/contracts/attached?details=true`) rather than the existing `getContractsByOrgUnitIdService`.
+
+**Rationale**: The confirmed BFF v1.0.2 endpoint for SUMA is `/contracts/attached`. The old endpoint (`/contracts`) is used by the legacy flow and should not be conflated with the new one.
+
+**Fallback**: If `listAttachedContractsService` returns null (error), render `ErrorTabsLayout`.
+
+---
+
+### Decision 2 — Selection state in a hook
+
+**`useContractSelection`** manages `selectedIds: Set<string>` as local React state. It exposes `isSelected(id)`, `handleSelectAll(allIds)`, `handleModifierClick(id)`, `handleShiftClick(id, allIds)`, `clearSelection()`.
+
+**Rationale**: Self-contained hook keeps the layout lean and allows unit testing without rendering. No global/shared state needed — selection is local to the listing page session.
+
+**Cross-platform**: Uses `event.metaKey || event.ctrlKey` to detect Cmd/Ctrl on Mac and Windows/Linux.
+
+---
+
+### Decision 3 — Page structure mirrors `org-unit-details`
+
+The new `contracts.tsx` page follows the exact same loader pattern as `org-unit-details.tsx`:
+- `withLoaderErrorBoundary` wrapping a `withAuthLoader` callback
+- Fetches `orgUnit`, `contracts`, and `user` in parallel
+- Renders a layout component; passes error to `ErrorTabsLayout`
+
+**Rationale**: Consistency with existing page structure. Reduces cognitive overhead for the team. Reuses `OrgUnitDetailsNavbar` and `OrgUnitBreadcrumb` for navigation continuity.
+
+---
+
+### Decision 4 — Single-contract gate at layout level
+
+The `isSingleContract` flag (`contracts.length <= 1`) is computed in `ContractListingLayout` and passed as a prop to `ContractSelectionList` and (later) to remove-action components. This mirrors how `OrgUnitsDetailsLayout` handles the same condition today.
+
+---
+
+## Technical Contract
+
+### New Files
+
+```
+src/
+├── pages/
+│   └── contracts.tsx                              # NEW page
+│
+└── features/contracts/
+    ├── hooks/
+    │   └── useContractSelection.ts                # NEW hook
+    │
+    ├── components/
+    │   ├── ContractListItem/
+    │   │   └── ContractListItem.tsx               # NEW component
+    │   └── ContractSelectionList/
+    │       └── ContractSelectionList.tsx          # NEW component
+    │
+    └── layouts/
+        └── ContractListingLayout/
+            └── ContractListingLayout.tsx          # NEW layout
+```
+
+---
+
+### `contracts.tsx` — Page
+
+```typescript
+// Loader data shape
+type ContractsPageData = {
+  data: {
+    orgUnit: OrgUnitBasicData;
+    contracts: ContractData[];      // from listAttachedContractsService
+    user: UserData | null;
+  };
+  context: { clientContext: ClientContext };
+  hasError?: boolean;
+  error?: ErrorBoundaryProps;
+};
+
+// Loader: parallel fetch of orgUnit, contracts, user
+// Renders ContractListingLayout or ErrorTabsLayout
+```
+
+Route: `/pvt/organization-account/contracts/[orgUnitId]` (registered in `plugin.config.js` via infra task).
+
+---
+
+### `useContractSelection` — Hook
+
+```typescript
+type UseContractSelectionReturn = {
+  selectedIds: Set<string>;
+  isSelected: (id: string) => boolean;
+  handleSelectAll: (allIds: string[]) => void;
+  handleModifierClick: (id: string) => void;        // Cmd/Ctrl+Click
+  handleShiftClick: (id: string, allIds: string[]) => void;
+  clearSelection: () => void;
+};
+```
+
+Internal state: `selectedIds: Set<string>`, `lastSelectedIndex: number`.
+
+---
+
+### `ContractListItem` — Component
+
+```typescript
+type ContractListItemProps = {
+  contract: ContractData;          // includes isDefault?: boolean
+  isSelected: boolean;
+  onModifierClick: (id: string, event: React.MouseEvent) => void;
+  onShiftClick: (id: string, event: React.MouseEvent) => void;
+};
+```
+
+Renders: contract name (fallback to email), "Default" badge when `isDefault === true`, selection highlight when `isSelected === true`.
+
+Click behaviour:
+- Plain click → no-op (activation TBD)
+- Cmd/Ctrl+Click → calls `onModifierClick`
+- Shift+Click → calls `onShiftClick`
+
+---
+
+### `ContractSelectionList` — Component
+
+```typescript
+type ContractSelectionListProps = {
+  contracts: ContractData[];
+  isSingleContract: boolean;
+  selectedIds: Set<string>;
+  onKeyDown: (event: React.KeyboardEvent) => void;  // for Cmd+A
+  onModifierClick: (id: string, event: React.MouseEvent) => void;
+  onShiftClick: (id: string, event: React.MouseEvent) => void;
+};
+```
+
+Renders the full list of `ContractListItem` components. Attaches `onKeyDown` for Cmd+A detection. Shows bulk toolbar when `selectedIds.size > 0` — toolbar includes remove button gated by `!isSingleContract`.
+
+---
+
+### `ContractListingLayout` — Layout
+
+```typescript
+type ContractListingLayoutProps = {
+  data: {
+    orgUnit: OrgUnitBasicData;
+    contracts: ContractData[];
+    user: UserData | null;
+  };
+  loading?: boolean;
+};
+```
+
+Structure:
+1. `GlobalLayout` wrapper
+2. `OrgUnitDetailsNavbar` (reused from org-units)
+3. `OrgUnitBreadcrumb` in `HeaderInside`
+4. `ContractSelectionList` with `useContractSelection` wired in
+
+---
+
+### Modified Files
+
+| File | Change |
+|------|--------|
+| `src/features/contracts/components/index.ts` | Export `ContractListItem`, `ContractSelectionList` |
+| `src/features/contracts/hooks/index.ts` | Export `useContractSelection` |
+| `src/features/contracts/layouts/index.ts` | Export `ContractListingLayout` |

package/specs/suma-contract-switching.md

@@ -0,0 +1,201 @@
+# Feature Specification: SUMA Phase 2 — Contract Switching & Profile (Contract Information)
+
+**Feature Branch**: `feat/suma-switching`
+
+**Created**: 2026-06-18
+
+**Status**: Done
+
+**Parent spec**: `specs/001-suma-phase-2/spec.md` (User Stories 3 & 4)
+
+**Depends on**:
+- `feat/suma-infra` — feature flag, routes, BFF service layer
+- `feat/suma-listing` — Contract Listing page (provides the entry point for this flow)
+
+> **Terminology**: In SUMA, **Contract Information** means the existing **Profile** page — route `/pvt/organization-account/profile/[orgUnitId]/[contractId]` (`buyerPortalRoutes.profileDetails`). After switching contracts, the buyer lands on Profile to operate under the selected contract. The separately registered `/contract-information` route is **not** the switch destination.
+
+---
+
+## Business Context
+
+### Problem
+
+SUMA Phase 2 enables the same user to belong to multiple contracts (accounts). After the
+Contract Listing page is in place, users need to switch into a specific contract's
+context and manage it. Switching requires updating the session token via the BFF, then
+landing on the Profile page (Contract Information) for that contract.
+
+### SUMA Mental Model
+
+Switching contracts updates the **active commercial context** for the session. A plain
+click on a contract row:
+
+1. Calls the BFF `switch-properties` endpoint (`changeContractToken`) with the target contract id.
+2. Clears persisted host session state so SSR re-runs under the new cookie.
+3. Full-navigates to the **Profile page** (`buyerPortalRoutes.profileDetails`) for that contract.
+4. Broadcasts to other tabs so open listing pages refresh.
+
+### Goals
+
+- Enable click-through from the listing to the Profile page (Contract Information) for each contract.
+- Show a loading overlay while the BFF switch and navigation are in progress.
+- Surface an error toast on the listing when the switch fails (user stays on listing).
+- Synchronize open tabs via `BroadcastChannel` so the listing refreshes when the user
+  switches or removes a contract in another tab.
+
+### Out of Scope
+
+- The `/contract-information` dedicated route as a switch destination (Profile is canonical).
+- Propagate-to-children on remove (deferred).
+
+---
+
+## User Scenarios & Testing
+
+### User Story 1 — Switch to Profile (Contract Information) (Priority: P1)
+
+A buyer clicks a contract row in the listing to enter that contract's context.
+
+**Acceptance Scenarios**:
+
+1. **Given** the Contract Listing page is displayed, **When** the user clicks a contract row (no modifier key), **Then** a loading overlay appears, the BFF switch-properties call runs, and on success the browser navigates to the Profile page (`/profile/[orgUnitId]/[contractId]`) for that contract.
+2. **Given** the BFF switch fails, **When** the request errors, **Then** the user remains on the Contract Listing and an error toast is shown.
+3. **Given** the user clicks with Cmd/Ctrl, **Then** the multi-select toggle fires (no navigation) — existing listing behaviour is unchanged.
+4. **Given** the switch succeeds, **When** the BroadcastChannel message is sent, **Then** all other open tabs showing the listing reload.
+
+---
+
+### User Story 2 — Profile Page (Contract Information) (Priority: P1)
+
+The Profile page shows the contract's identity, basic details, and navigation under the new session context.
+
+**Acceptance Scenarios**:
+
+1. **Given** the user lands on `/pvt/organization-account/profile/[orgUnitId]/[contractId]` after a successful switch, **When** the page loads, **Then** the contract name and profile details are displayed under the selected contract context.
+2. **Given** the user is on a SUMA org page with the sidebar visible, **When** they use the "Back to contracts" link, **Then** they are navigated back to the Contract Listing page.
+3. **Given** the user clicks a contract-scoped tab (Addresses, Payment methods, etc.), **Then** the browser navigates to the corresponding existing buyer portal route for that contract.
+
+---
+
+### User Story 3 — Remove Contract (Priority: P1)
+
+Contract removal is handled from the **Contract Listing** page (bulk toolbar and per-row dots menu). See `specs/suma-remove-contracts.md`.
+
+---
+
+### User Story 4 — Error Handling on Switch (Priority: P1)
+
+When the BFF switch fails, the user stays on the listing with feedback.
+
+**Acceptance Scenarios**:
+
+1. **Given** the BFF switch-properties call fails, **When** the error is caught, **Then** the loading overlay clears and an error toast appears on the Contract Listing page.
+2. **Given** the Contract Listing page mounts with `?error=contract-load-failed` (legacy redirect param), **Then** an auto-dismissing toast fires with the message "Failed to load contract information." and the query param is removed.
+
+---
+
+### User Story 5 — Tab Synchronisation (Priority: P2)
+
+State changes in one tab propagate to other open tabs.
+
+**Acceptance Scenarios**:
+
+1. **Given** the user is on the listing in Tab 1 and Tab 2 switches to a contract (Profile page), **Then** Tab 1 reloads to reflect the current state.
+2. **Given** the user removes a contract in Tab 2, **Then** Tab 1's listing refreshes and the removed contract no longer appears.
+3. **Given** the browser does not support `BroadcastChannel`, **Then** the app degrades gracefully — no crash, just no cross-tab sync.
+
+---
+
+### Key Scenarios
+
+| Scenario | Pre-condition | Action | Expected result |
+|----------|--------------|--------|----------------|
+| **Happy path — switch** | Listing, 3 contracts | Click row | Loading overlay → BFF switch → Profile page loads |
+| **Switch failure** | BFF returns error | Click row | Toast on listing; overlay clears; no navigation |
+| **Tab sync — switch** | Listing open in Tab 1 | Tab 2 switches contract | Tab 1 reloads |
+| **Tab sync — remove** | Listing open in Tab 1 | Tab 2 removes a contract | Tab 1 reloads; row gone |
+| **Modifier click** | Listing page | Cmd+Click row | Multi-select toggled; no navigation |
+| **Error toast not replayed** | Listing with `?error=…` | Reload page | No second toast |
+
+---
+
+## Requirements
+
+### Functional
+
+- **FR-001**: Plain click on `ContractRow` calls `useSwitchContract` → BFF `changeContractToken` → navigates to `buyerPortalRoutes.profileDetails({ orgUnitId, contractId })`.
+- **FR-002**: Cmd/Ctrl click and Shift+Click preserve existing multi-select behaviour (no switch).
+- **FR-003**: On successful switch, fire `BroadcastChannel` message `{ type: 'contract-activated', contractId }`.
+- **FR-004**: A loading overlay (`ContractSwitchOverlay`) MUST cover the row while the switch is in progress.
+- **FR-005**: On switch failure, show an error toast on the listing; user MUST remain on the listing.
+- **FR-006**: Profile page renders under the new session context after full navigation.
+- **FR-007**: Listing reads `?error=contract-load-failed` on mount (legacy), shows toast, removes query param from URL.
+- **FR-008**: `BroadcastChannel` listener in listing calls `router.reload()` on any incoming message.
+- **FR-009**: `BroadcastChannel` usage is guarded by `typeof BroadcastChannel !== 'undefined'`.
+
+### Non-functional
+
+- Zero new TypeScript errors (pre-existing baseline errors excluded).
+- Page must pass `make lint`.
+- New hooks and pure functions must have unit tests.
+
+---
+
+## Arch Decisions
+
+### Decision 1 — BFF switch + Profile navigation
+
+**Chosen approach**: Plain click on `ContractRow` calls `useSwitchContract`, which:
+
+1. POSTs to BFF `switch-properties` via `changeContractToken(contractId)`.
+2. Clears persisted host session state (`clearPersistedSessionState`).
+3. Broadcasts `{ type: 'contract-activated', contractId }` to other tabs.
+4. Full-navigates to `buyerPortalRoutes.profileDetails({ orgUnitId, contractId })`.
+
+A loading overlay covers the row until navigation completes. On failure, the overlay clears and an error toast is shown on the listing.
+
+**Rationale**: Switching contracts requires updating the session cookie so SSR and store context reflect the selected commercial agreement. The Profile page is the canonical Contract Information destination in the buyer portal.
+
+**Failure path**: Toast on listing; previous contract context remains active.
+
+---
+
+### Decision 2 — BroadcastChannel for tab sync
+
+**Chosen approach**: `useContractSwitchChannel` wraps `BroadcastChannel` with channel name `'buyer-portal-active-contract'`. Listing subscribes and calls `router.reload()` on any message.
+
+**Message shapes**:
+```typescript
+type ChannelMessage = { type: 'contract-activated'; contractId: string };
+```
+
+**Who sends**: `useSwitchContract` after a successful BFF switch.
+
+**Who listens**: `ContractListingLayout`.
+
+---
+
+## Technical Contract
+
+### Key implementation files
+
+```
+src/features/contracts/
+├── hooks/
+│   ├── useSwitchContract.ts          # BFF switch + profile navigation
+│   └── useContractSwitchChannel.ts   # BroadcastChannel wrapper
+├── components/
+│   └── ContractSwitchOverlay/        # Loading overlay during switch
+└── utils/
+    ├── changeContractToken.ts        # BFF switch-properties call
+    └── clearPersistedSessionState.ts # Clear host session after switch
+
+src/pages/profile.tsx                 # Contract Information destination
+```
+
+### Modified files
+
+| File | Change |
+|------|--------|
+| `ContractListItem.tsx` | Plain click → `useSwitchContract`; loading overlay; error toast on failure |
+| `ContractListingLayout.tsx` | Subscribe to BroadcastChannel → `router.reload()`; legacy `?error` toast handling |