@vtex/faststore-plugin-buyer-portal 1.3.86 → 2.0.0

package/.github/workflows/release.yaml

@@ -41,11 +41,12 @@ jobs:
       - name: Update npm to latest
         run: npm install -g npm@latest
 
-      - name: Generate CHANGELOG and update Version Const
-        run: yarn release
+      # Temporarily disabled for v2.0.0 major release — restore after publish with [skip ci]
+      # - name: Generate CHANGELOG and update Version Const
+      #   run: yarn release
 
-      - name: Update version to patch
-        run: yarn version --patch
+      # - name: Update version to patch
+      #   run: yarn version --patch
 
       - name: Publish
         run: npm publish

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - Unreleased
+
+### Breaking Changes
+
+- Requires **FastStore v4** (`@faststore/core` and `@faststore/ui` >= 4.x) — stores on v3 must pin a `1.x` version
+
+## [1.3.87] - 2026-05-21
+
+### Fixed
+
+- Assortments page: use consistent "Assortments" title during loading and after page load by updating `routeLayoutMapping` and replacing the custom header with `HeaderInside`, aligning title position with other Contract settings pages
+
 ## [1.3.86] - 2026-05-19
 
 ### Added
@@ -640,7 +652,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add CHANGELOG file
 - Add README file
 
-[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/1.3.86...HEAD
+[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.87...HEAD
 [1.3.55]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.54...v1.3.55
 [1.3.54]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.53...v1.3.54
 [1.3.53]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.52...v1.3.53
@@ -725,4 +737,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [1.3.70]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.69...v1.3.70
 [1.3.85]: https://github.com/vtex/faststore-plugin-buyer-portal/releases/tag/1.3.85
 
+[1.3.87]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.86...v1.3.87
 [1.3.86]: https://github.com/vtex/faststore-plugin-buyer-portal/releases/tag/1.3.86

package/cypress/integration/product-assortment.test.ts

@@ -6,7 +6,7 @@ function visitProductAssortmentPage() {
 
   // Navigate to product assortment page
   cy.get("[data-fs-vertical-nav-menu-item]")
-    .contains("Product assortment")
+    .contains("Assortments")
     .click({ timeout: TEST_CONFIG.TIMEOUTS.PAGE_LOAD });
 
   cy.wait(1000);
@@ -58,7 +58,7 @@ describe(
 
       // Wait for product assortment section to be visible
       cy.get("[data-fs-bp-header-inside-title]")
-        .contains("Product assortment")
+        .contains("Assortments")
         .should("be.visible");
 
       // Wait for product assortment table to be loaded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore-plugin-buyer-portal",
-  "version": "1.3.86",
+  "version": "2.0.0",
   "description": "A plugin for faststore with buyer portal",
   "main": "index.js",
   "scripts": {

package/specs/assortments-page-fixes.md

@@ -0,0 +1,222 @@
+# Assortments Page Fixes
+
+> **Status**: Approved
+> **Created**: 2026-05-19
+
+## 1. Business Context
+
+### Problem Statement
+
+The **Assortments** page was recently released in the Buyer Portal (Contract settings), but manual testing revealed two UX inconsistencies compared to sibling pages in the same group (Profile, Addresses, Payment methods, Credit cards):
+
+1. **Unstable title during loading** — when navigating via the sidebar, users temporarily see "Product Assortment", and after the page finishes loading the title changes to "Assortments".
+2. **Incorrect title vertical position** — the "Assortments" title appears higher on the page than on sibling pages.
+
+These issues affect B2B administrators who manage organizational units and need to select the correct product assortment for each unit.
+
+### Goals
+
+- Ensure the title "Assortments" is displayed consistently during and after page load.
+- Align the page header positioning and typography with other Contract settings pages.
+
+### User Stories
+
+#### US-1: Consistent title during navigation
+
+- **Story**: As a contract administrator, I want the page title to remain "Assortments" while the page loads, so that I am not confused by a temporary, incorrect label.
+- **Acceptance Criteria**:
+  - **Given** I am on any Contract settings page, **when** I click "Assortments" in the sidebar, **then** the loading state shows the title "Assortments" (not "Product Assortment" or "Product assortment").
+  - **Given** the Assortments page finishes loading, **when** the content is rendered, **then** the title remains "Assortments" with no visible title swap.
+
+#### US-2: Header aligned with sibling pages
+
+- **Story**: As a contract administrator, I want the Assortments page header to match Profile, Addresses, and Payment methods, so that the portal feels cohesive.
+- **Acceptance Criteria**:
+  - **Given** I open Assortments and any other Contract settings page (e.g. Addresses), **when** I compare the page title position, **then** both titles share the same vertical offset from the top of the content area.
+  - **Given** the Assortments page is loaded, **when** I view the header, **then** it uses the shared `HeaderInside` component and styling used by sibling pages.
+  - **Given** the Assortments page is loaded, **when** I read the descriptive text below the title, **then** the subtitle "Select the product assortment that users in this organizational unit should access" is still visible.
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected Result |
+|---|---|---|---|
+| Happy path — list and selection | Contract with assortments; one assortment enabled | Open Assortments → select a different assortment | Title stays "Assortments"; all assortments listed; selection saves with success toast |
+| Error case — failed selection save | User on Assortments page; API PUT fails | Select a different assortment | Radio reverts to previous selection; error toast "Failed to save assortment" |
+| Edge case — loading transition | User on Profile page | Click "Assortments" in sidebar | Loading skeleton shows `HeaderInside` with title "Assortments"; no flicker to a different label after load |
+
+### Functional Requirements
+
+- FR-1: The assortments route `pageTitle` in `routeLayoutMapping.ts` must be `"Assortments"`.
+- FR-2: `ProductAssortmentLayout` must use `HeaderInside title="Assortments"` instead of the custom header (`h1` + custom styles).
+- FR-3: The descriptive subtitle must remain below `HeaderInside`, with scoped styles in the page section.
+- FR-4: Radio selection behavior and persistence via `useSetAssortment` remain unchanged.
+- FR-5: The listing must display all assortments returned by the API in a single request (maximum of 20 per contract — pagination is not required).
+
+### Non-Functional Requirements
+
+- Maintain plugin boundary compatibility — changes limited to `src/features/product-assortment/` and existing shared utilities.
+- Pass `make lint`, `make typecheck`, and `make test`.
+- Update Cypress tests only where the title or navigation label changed to "Assortments".
+
+### Out of Scope
+
+- **Pagination** — a contract supports at most 20 assortments; the API returns all of them in a single response, making pagination controls unnecessary.
+- Add/remove assortment drawer functionality (present in legacy Cypress tests, absent from the current implementation).
+- Name search/filter (the hook already accepts `search`, but it is not part of this fix).
+- Changes to the API logic that places the enabled assortment at the top.
+- Renaming routes or paths (`/product-assortment/...` remains unchanged).
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+Fix the two UX bugs by aligning the Assortments page header with other Contract settings pages, reusing `HeaderInside` and unifying the title via `routeLayoutMapping`.
+
+### Architecture Overview
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant LoadingTabsLayout
+    participant ProductAssortmentLayout
+    participant useGetProductAssortment
+    participant API
+
+    User->>LoadingTabsLayout: Click "Assortments"
+    LoadingTabsLayout->>User: HeaderInside title="Assortments" (from routeLayoutMapping)
+    LoadingTabsLayout->>ProductAssortmentLayout: Route loaded
+    ProductAssortmentLayout->>useGetProductAssortment: orgUnitId, contractId
+    useGetProductAssortment->>API: GET .../assortments/available
+    API-->>ProductAssortmentLayout: items (up to 20)
+    ProductAssortmentLayout->>User: HeaderInside + table
+```
+
+### Root Cause Analysis
+
+| Bug | Root cause (original code) |
+|---|---|
+| Title flicker | `LoadingTabsLayout` reads `pageTitle: "Product assortment"` from `routeLayoutMapping.ts` and renders it via `HeaderInside` (with `text-transform: capitalize` → "Product Assortment"). After load, `ProductAssortmentLayout` renders a custom `h1` with text "Assortments". |
+| Title position | `ProductAssortmentLayout` does not use `HeaderInside`; it uses `[data-fs-bp-assortments-header]` with `padding: var(--fs-spacing-3) 0` and custom typography, unlike `[data-fs-bp-header-inside]` (`padding: var(--fs-bp-padding-4/8/9) 0`). |
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| A. Unified `HeaderInside` + `routeLayoutMapping` | Consistent with sibling pages; fixes flicker and position | Requires subtitle adjustment below the header | **Accepted** |
+| B. Keep custom header and only adjust padding | Minimal diff | Still diverges from `HeaderInside` typography/responsiveness; does not fix flicker alone | Rejected |
+| C. Server-side pagination | Supports large lists | Unnecessary — maximum of 20 assortments per contract | Rejected |
+| D. Remove subtitle to match Profile | Less markup | Loses useful context for the user; subtitle is a product requirement | Rejected |
+
+### Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| Legacy Cypress tests fail | Med | High | Update only title and navigation label expectations; leave legacy drawer/filter scenarios unchanged |
+| Contract assortment limit increases in the future | Low | Low | Re-evaluate pagination if the business limit changes |
+
+### Key Decisions
+
+#### Decision 1: Unify title via `routeLayoutMapping` + `HeaderInside`
+
+- **Status**: Accepted
+- **Context**: Loading and loaded states use different title mechanisms.
+- **Decision**: Change `pageTitle` to `"Assortments"` and migrate the loaded layout to `HeaderInside title="Assortments"`.
+- **Consequences**: `LoadingTabsLayout`, `ErrorTabsLayout`, and the loaded page all display the same title. Removes the custom `[data-fs-bp-assortments-title]`.
+
+#### Decision 2: No pagination
+
+- **Status**: Accepted
+- **Context**: Contracts support at most 20 assortments; the API returns all of them in a single response.
+- **Decision**: Do not implement pagination, `useUrlPaginatedSearch`, or a `page` query param.
+- **Consequences**: Simpler layout; single fetch via `useGetProductAssortment` without lazy/router sync.
+
+#### Decision 3: Keep subtitle as a separate element
+
+- **Status**: Accepted
+- **Context**: No sibling page has a subtitle, but Assortments needs explanatory text.
+- **Decision**: Render `<p data-fs-bp-assortments-subtitle>` immediately below `HeaderInside`, keeping existing scoped styles.
+- **Consequences**: Title position aligns with sibling pages; subtitle sits below without affecting the `h1` offset.
+
+### Implementation Plan
+
+1. **Consistent title**
+   - Edit `src/features/shared/utils/routeLayoutMapping.ts`: `pageTitle: "Assortments"`.
+
+2. **Aligned header**
+   - Refactor `ProductAssortmentLayout.tsx`:
+     - Import and use `HeaderInside title="Assortments"`.
+     - Remove `div[data-fs-bp-assortments-header]` and the custom `h1`.
+     - Keep the subtitle below the header.
+   - Remove obsolete `[data-fs-bp-assortments-title]` and header styles from `product-assortment-layout.scss`; preserve subtitle styles.
+
+3. **Tests**
+   - Update `cypress/integration/product-assortment.test.ts` only where the title or navigation label changed to "Assortments".
+
+4. **Verification**
+   - Run `make check`.
+   - Manual test against a linked host store: navigate to Assortments, confirm stable title, visual alignment vs Addresses, and full assortment listing.
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+No changes to existing types in `src/features/product-assortment/types/index.ts`. The API response may include `paging`, but the frontend does not consume pagination in this scope.
+
+### Interfaces
+
+#### API — GET assortments (consumed by the plugin)
+
+| Field | Type | Notes |
+|---|---|---|
+| Path | `GET /customers/{contractId}/units/{unitId}/assortments/available` | Existing |
+| Query `name` | `string` (optional) | Existing, out of scope |
+| Response `items[]` | `{ id, name, enabled }` | Rendered in full (up to 20) |
+
+#### `useGetProductAssortment`
+
+```typescript
+useGetProductAssortment({
+  contractId: string;
+  orgUnitId: string;
+  search?: string;
+  options?: QueryOptions<...>;
+})
+// Returns: { data: { items, paging }, isProductAssortmentLoading, ... }
+```
+
+Single fetch on mount — no `page`, no `lazy`, no URL sync.
+
+#### Component boundaries
+
+| Module | Responsibility |
+|---|---|
+| `routeLayoutMapping.ts` | Loading/error title: `"Assortments"` |
+| `ProductAssortmentLayout` | Header, data fetch, empty state |
+| `ProductAssortmentTable` | Table rendering + radio selection |
+| `useSetAssortment` | PUT selection (unchanged) |
+
+### Integration Points
+
+- **LoadingTabsLayout / ErrorTabsLayout** — read `pageTitle` via `getTabsLayoutConfigFromRoute`; fixed indirectly by the `routeLayoutMapping` change.
+- **BFF/API** — `assortments/available` endpoint returns all contract assortments (max. 20).
+- **Host store** — no changes to `plugin.config.js` (route already registered).
+
+### Invariants & Constraints
+
+- The sidebar menu continues to display **"Assortments"** (`getContractSettingsLinks.ts` — already correct).
+- The loaded, loading, and error page title must always be **"Assortments"**.
+- The assortment with `enabled: true` remains selected via radio; the API is responsible for placing it at the top when applicable.
+- No new cross-domain dependencies — only `shared` (`HeaderInside`).
+
+### Files to Change
+
+| File | Change |
+|---|---|
+| `src/features/shared/utils/routeLayoutMapping.ts` | `pageTitle` → `"Assortments"` |
+| `src/features/product-assortment/layouts/ProductAssortmentLayout/ProductAssortmentLayout.tsx` | `HeaderInside`, simple fetch |
+| `src/features/product-assortment/layouts/ProductAssortmentLayout/product-assortment-layout.scss` | Remove custom title styles; keep subtitle |
+| `cypress/integration/product-assortment.test.ts` | Update title and navigation label to "Assortments" |

package/src/features/product-assortment/layouts/ProductAssortmentLayout/ProductAssortmentLayout.tsx

@@ -1,4 +1,4 @@
-import { EmptyState } from "../../../shared/components/EmptyState/EmptyState";
+import { EmptyState, HeaderInside } from "../../../shared/components";
 import { useBuyerPortal } from "../../../shared/hooks";
 import { ContractTabsLayout, GlobalLayout } from "../../../shared/layouts";
 import { ProductAssortmentTable } from "../../components/ProductAssortmentTable/ProductAssortmentTable";
@@ -19,7 +19,8 @@ export const ProductAssortmentLayout = ({
       orgUnitId,
     });
 
-  const isEmpty = productAssortmentData.items.length === 0;
+  const isEmpty =
+    !isProductAssortmentLoading && productAssortmentData.items.length === 0;
 
   return (
     <GlobalLayout>
@@ -31,15 +32,14 @@ export const ProductAssortmentLayout = ({
         pageName="Contract"
       >
         <section data-fs-bp-product-assortment-container>
-          <div data-fs-bp-assortments-header>
-            <h1 data-fs-bp-assortments-title>Assortments</h1>
-            <p data-fs-bp-assortments-subtitle>
-              Select the product assortment that users in this organizational
-              unit should access
-            </p>
-          </div>
+          <HeaderInside title="Assortments" />
 
-          {!isProductAssortmentLoading && isEmpty ? (
+          <p data-fs-bp-assortments-subtitle>
+            Select the product assortment that users in this organizational unit
+            should access
+          </p>
+
+          {isEmpty ? (
             <EmptyState
               iconName="Shapes"
               title="No product assortments found."

package/src/features/product-assortment/layouts/ProductAssortmentLayout/product-assortment-layout.scss

@@ -5,23 +5,6 @@
 
   width: 100%;
 
-  [data-fs-bp-assortments-header] {
-    display: flex;
-    flex-direction: column;
-    gap: var(--fs-spacing-1);
-    padding: var(--fs-spacing-3) 0;
-  }
-
-  [data-fs-bp-assortments-title] {
-    font-family: Inter;
-    font-weight: var(--fs-text-weight-semibold);
-    font-size: calc(var(--fs-text-size-0) * 2);
-    line-height: calc(var(--fs-text-size-base) * 2);
-    letter-spacing: -0.04em;
-    color: #1f1f1f;
-    margin: 0;
-  }
-
   [data-fs-bp-assortments-subtitle] {
     font-family: Inter;
     font-weight: var(--fs-text-weight-regular);
@@ -31,35 +14,6 @@
     margin: 0;
   }
 
-  [data-fs-bp-product-assortment-layout] {
-    display: flex;
-    flex-direction: column;
-    gap: calc(var(--fs-spacing-3) + var(--fs-spacing-0));
-  }
-
-  [data-fs-bp-product-assortment-paginator] {
-    display: flex;
-    align-items: center;
-    justify-content: flex-start;
-    margin-top: var(--fs-bp-margin-1);
-    padding: var(--fs-bp-padding-3) 0;
-    gap: var(--fs-bp-gap-4);
-
-    [data-fs-bp-paginator-counter] {
-      margin-left: var(--fs-bp-margin-auto);
-    }
-
-    [data-fs-paginator-next-page-button]:disabled {
-      cursor: not-allowed;
-      color: var(--fs-bp-color-neutral-6);
-      
-      &:hover {
-        color: var(--fs-bp-color-neutral-6);
-        background-color: transparent;
-      }
-    }
-  }
-
   [data-fs-empty-state-section] {
     gap: var(--fs-bp-gap-3);
 

package/src/features/shared/utils/constants.ts

@@ -22,7 +22,7 @@ export const SCOPE_KEYS = {
   CREDIT_CARDS: "creditCards",
 } as const;
 
-export const CURRENT_VERSION = "1.3.86";
+export const CURRENT_VERSION = "2.0.0";
 
 export const CHANGES_TIMEOUT_MESSAGE =
   "Changes may take up to 10 minutes to apply.";

package/src/features/shared/utils/routeLayoutMapping.ts

@@ -40,7 +40,7 @@ export const ROUTE_TABS_LAYOUT_MAPPING: Record<string, RouteTabsLayoutConfig> =
     "/pvt/organization-account/product-assortment/[orgUnitId]/[contractId]": {
       layout: "ContractTabsLayout",
       pageName: "Contract",
-      pageTitle: "Product assortment",
+      pageTitle: "Assortments",
     },
     "/pvt/organization-account/po-numbers/[orgUnitId]/[contractId]": {
       layout: "ContractTabsLayout",