@vtex/faststore-plugin-buyer-portal 1.3.87 → 1.3.88

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.88] - 2026-07-23
+
+### Removed
+
+- PO Numbers, Cost Centers, and Releases pages, routes, and every dedicated client/hook/service/component (the `custom-fields` feature and the shared `custom-field` building blocks) — the underlying BFF service is discontinued on 2026-07-30
+- Address Locations client, hooks, services, and dedicated components/drawers, and the "Locations" tab from the "Add address" drawer (same discontinued BFF service)
+- PO Number/Cost Center/Release as selectable allocation types in "Add budget allocations" and as criteria presets in "Set order field criteria" (existing budget allocations and buying policy criteria created before this change keep displaying normally)
+- "Add cost center"/"Add PO number"/"Add release" shortcuts in the Org Unit "Add" dropdown (now disabled, no action)
+
+### Added
+
+- A persistent deprecation alert on the Org Unit Details page, explaining that PO Numbers, Cost Centers, and Releases were replaced by Accounting Fields and pointing to the upgrade path (buyer-portal plugin `v2.0.1+`, FastStore `v4`)
+- A persistent deprecation alert on the Address Details page, explaining that Address Locations was replaced by Accounting Fields and pointing to the same upgrade path
+- Support for a disabled, tooltip-carrying state on `VerticalNav.Link`, used to keep the "PO numbers"/"Cost centers"/"Releases" navigation entries visible (but disabled) in the Org Unit Details cards and the Contract-settings sidebar
+- Support for a disabled state on `TabOption`, used to keep the "Locations" tab visible (but disabled) on the Address Details page; the "Add Locations" shortcut in the address actions dropdown is disabled the same way
+
 ## [1.3.87] - 2026-05-21
 
 ### Fixed
@@ -731,5 +747,6 @@ 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.88]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.87...v1.3.88
 [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/constants.ts

@@ -89,14 +89,6 @@ export const TEST_DATA = {
     NEW_ADDRESS_STATE: "RJ",
     NEW_ADDRESS_POSTAL_CODE: "22250-905",
   },
-  LOCATIONS: {
-    LOCATION_ADDRESS_NAME: "LOCATIONS",
-    FIRST_LOCATION: "Location 1",
-    SECOND_LOCATION: "Location 2",
-    THIRD_LOCATION: "Location 3",
-    FOURTH_LOCATION: "Location 4",
-    EDITED_LOCATION: "Edited Location",
-  },
   RECIPIENTS: {
     RECIPIENTS_ADDRESS_NAME: "RECIPIENTS",
     FIRST_RECIPIENT_NAME: "First Recipient",

package/package.json

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

package/plugin.config.js

@@ -40,18 +40,6 @@ module.exports = {
       path: "/pvt/organization-account/product-assortment/[orgUnitId]/[contractId]",
       appLayout: false,
     },
-    "po-numbers": {
-      path: "/pvt/organization-account/po-numbers/[orgUnitId]/[contractId]",
-      appLayout: false,
-    },
-    "cost-centers": {
-      path: "/pvt/organization-account/cost-centers/[orgUnitId]/[contractId]",
-      appLayout: false,
-    },
-    releases: {
-      path: "/pvt/organization-account/releases/[orgUnitId]/[contractId]",
-      appLayout: false,
-    },
     roles: {
       path: "/pvt/organization-account/roles/[orgUnitId]",
       appLayout: false,

package/specs/deprecate-address-locations.md

@@ -0,0 +1,497 @@
+# Deprecate Address Locations (Custom Field)
+
+> **Status**: Done
+> **Created**: 2026-07-23
+> **Updated**: 2026-07-23 — implemented via `/implementing` (all 10 implementation-plan steps landed as commits on PR [#409](https://github.com/vtex/faststore-plugin-buyer-portal/pull/409)); Decision 9 (the `TabOption` unit test) was reverted post-implementation — see Decision 9
+> **Branch**: `feat/deprecate-custom-fields` (continues the work started in `specs/deprecate-custom-fields.md`; no separate branch — this spec, and its implementation, land as additional commits on the same open PR [#409](https://github.com/vtex/faststore-plugin-buyer-portal/pull/409), which had no review/approval yet at the time of this decision, and folds into the still-unpublished `1.3.88` release — confirmed via `npm view` that `1.3.88` has not been published yet, the latest on the `1.3.x` line is `1.3.87`)
+
+## 1. Business Context
+
+### Problem Statement
+
+`specs/deprecate-custom-fields.md` covered PO Numbers, Cost Centers, and Releases — three standalone custom-field pages. **Address Locations is the same underlying custom field type (`Location`)**, but surfaced differently: as a tab inside the Address Details page and inside the "Add address" / "Add Locations" drawers, not as a dedicated page. The BFF's retirement of the custom-fields API on **2026-07-30** (confirmed 2026-07-22, see the prior spec) covers this endpoint too — `LocationsClient` calls the same `custom-fields/location/values` routes that are being discontinued.
+
+This means the `addresses` feature has its own, self-contained slice of now-obsolete code: a client, four hooks, four services, and half a dozen components/drawers dedicated to creating, listing, editing, and deleting "locations" attached to an address. Unlike PO Numbers/Cost Centers/Releases, this slice has no dedicated route/page of its own — it is embedded inside `AddressDetailsLayout` (a tab) and `CreateAddressDrawer` (a tab), plus a quick-add shortcut in `AddressDropdownMenu`.
+
+Following the same pattern already established for the other three custom fields:
+
+- Every piece of code that exists solely to support Locations (client, hooks, services, drawers, components) is removed.
+- The "Locations" **tab** in `CreateAddressDrawer` is removed entirely (drawer keeps only "Details" and "Recipients").
+- The "Locations" **tab** in `AddressDetailsLayout` stays visible, but disabled (matches the "keep the entry visible, don't let it vanish silently" decision from the prior spec) — no tooltip needed here, since a new persistent alert on the same page already explains the deprecation.
+- The "Add Locations" quick-add shortcut in `AddressDropdownMenu` stays visible, but disabled (same native-`disabled` pattern used for the Org Units quick-add shortcuts in the prior spec).
+- The existing `CustomFieldsDeprecationAlert` component is generalized (accepts its message as `children` instead of hardcoded copy) and reused here with Locations-specific copy — and relocated to `shared/components/` since it now has two feature consumers (`org-units` and `addresses`), which the project's plugin boundary/domain rules require ("No domain may import directly from another domain").
+
+### Goals
+
+- Remove the entire Locations custom-field slice from `addresses`: `LocationsClient`, its 4 hooks, its 4 services, and every component/drawer that exists only to support it.
+- Remove the "Locations" tab from `CreateAddressDrawer` (Details + Recipients only).
+- Keep the "Locations" tab visible but disabled in `AddressDetailsLayout`, and stop fetching location data in the page loader.
+- Keep the "Add Locations" shortcut visible but disabled in `AddressDropdownMenu`.
+- Show a persistent deprecation alert on the Address Details page, reusing the generalized `CustomFieldsDeprecationAlert`.
+- Preserve everything shared with Address Recipients untouched (generic list/table/drawer building blocks in `shared/components`, `RecipientsForm`/`RecipientItem`, recipients hooks/services/client).
+- Ship in the same release as `specs/deprecate-custom-fields.md` (still targets the `1.3.x` line, still before 2026-07-30) — no separate version bump; folded into the same patch.
+
+### User Stories
+
+#### US-1: The Locations client/hooks/services/components are removed
+
+- **Story**: As a maintainer, I want `LocationsClient`, its hooks, services, and every dedicated component/drawer removed, since the BFF will no longer serve any of their requests after 2026-07-30.
+- **Acceptance Criteria**:
+  - **Given** the codebase after this change, **when** I search for `LocationsClient`, `useAddLocationsToAddress`, `useAddressLocationList`, `useAddressLocationEdit`, `useAddressLocationDelete`, `AddressLocationsList`, `LocationForm`, `LocationField`, `LocationDrawer`/`LocationsDrawer`, `EditAddressLocationDrawer`, or `DeleteAddressLocationDrawer`, **then** none of them exist anymore.
+  - **Given** the same search, **when** I look at `RecipientsForm`, `RecipientItem`, `AddressRecipientsList`, and their hooks/services/client, **then** all of them are untouched and still work exactly as before.
+
+#### US-2: "Add address" drawer no longer has a Locations tab
+
+- **Story**: As a contract administrator, I want the "Add address" drawer to only show "Details" and "Recipients", since adding locations during address creation is no longer possible.
+- **Acceptance Criteria**:
+  - **Given** I open "Add address", **when** the drawer renders, **then** the tab bar shows only "Details" and "Recipients" — no "Locations" tab.
+  - **Given** I fill in the address details and confirm, **when** the address is created, **then** it succeeds exactly as before (creation never actually sent `locations` to the BFF — confirmed dead field on the create-address payload).
+
+#### US-3: Address Details keeps the Locations tab visible, but disabled, with a page-level deprecation alert
+
+- **Story**: As a contract administrator, I want to still see a "Locations" tab on an address's details page, but visibly disabled, and a clear message explaining that Address Locations were replaced by Accounting Fields and discontinued on 2026-07-30.
+- **Acceptance Criteria**:
+  - **Given** I open an address's details page, **when** I look at the tab bar, **then** "Details" and "Recipients" work normally, and "Locations" appears visually disabled (greyed out, not clickable).
+  - **Given** I click the disabled "Locations" tab, **when** nothing happens, **then** the active tab does not change.
+  - **Given** I navigate directly to the address details page with `?tab=location-tab` in the URL (a link from before this change, or a stale bookmark), **when** the page loads, **then** it falls back to the "Details" tab instead of erroring or trying to render removed components.
+  - **Given** I open the page, **when** it renders, **then** a deprecation alert is visible (no dismiss control), stating Address Locations was replaced by Accounting Fields and discontinued on 2026-07-30, with the upgrade path.
+
+#### US-4: The "Add Locations" quick-add shortcut is disabled
+
+- **Story**: As a contract administrator, I want the "Add Locations" item in an address's actions dropdown to be visibly disabled, so there is no remaining path to create location values.
+- **Acceptance Criteria**:
+  - **Given** I open an address's actions dropdown, **when** the menu renders, **then** "Add Locations" appears visually disabled and produces no action on click.
+  - **Given** the same dropdown, **when** I look at unrelated items ("Edit details", "Add Recipients", "Remove address", "Delete address"), **then** they remain fully functional.
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected Result |
+|---|---|---|---|
+| Happy path — Address Details with disabled Locations tab | Any existing address | Open the address's details page | "Locations" tab renders disabled; "Details"/"Recipients" work normally; deprecation alert visible |
+| Happy path — Create address without Locations | — | Open "Add address", fill Details, go to Recipients, confirm | Address created successfully; no Locations tab was ever shown |
+| Error case — stale deep link to the removed tab | Any existing address | Visit `.../address-details?...&tab=location-tab` directly | Page falls back to the "Details" tab; no crash, no attempt to fetch/render removed location data |
+| Edge case — address created before this change with existing location values | Address has locations attached via the (now-discontinued) BFF endpoint | Open its details page | Page renders normally (no listing call is made anymore); the disabled "Locations" tab and the alert are the only trace of the feature — no data loss, just no more UI to browse/manage it |
+
+### Functional Requirements
+
+- FR-1: Delete `src/features/addresses/clients/LocationsClient.ts`.
+- FR-2: Delete `src/features/addresses/services/locations/**` (`get-address-locations.service.ts`, `add-address-locations.service.ts`, `edit-address-location.service.ts`, `delete-address-location.service.ts`).
+- FR-3: Delete `src/features/addresses/hooks/useAddLocationsToAddress.ts`, `useAddressLocationList.ts`, `useAddressLocationEdit.ts`, `useAddressLocationDelete.ts`, and their exports from `hooks/index.ts`.
+- FR-4: Delete `src/features/addresses/components/LocationsDrawer/**`, `LocationForm/**` (including `LocationField/**`), `AddressLocationsList/**`, `EditAddressLocationDrawer/**`, `DeleteAddressLocationDrawer/**`, and their exports from `components/index.ts`.
+- FR-5: `CreateAddressDrawer.tsx` must remove the "Locations" `TabOption`/`TabContent`, the `locations` state, and the `LocationForm` import/usage. The `locations_count` field in its analytics payload (`address_creation` event) is kept, now hardcoded to `0`, to avoid changing the shape of an existing analytics event for any downstream consumer.
+- FR-6: `TabOption` (`src/features/shared/components/Tab/TabOption.tsx`) must support an optional `disabled` prop; when set, render a native `disabled` `<button>` (no click handler fires, `aria-disabled`, standard disabled styling) instead of the normal clickable option.
+- FR-7: `AddressDetailsLayout.tsx` must keep a "Locations" `TabOption` in the tab bar, marked `disabled`, and reordered to the end (`Details`, `Recipients`, `Locations`) so the two functional tabs stay adjacent and the deprecated one is visually isolated. `"location-tab"` is removed from the set of valid `activeTabId` values (both the initial-state derivation and the query-param sync effect) so a stale `?tab=location-tab` falls back to `"address-tab"`.
+- FR-8: `AddressDetailsLayout.tsx` must remove the `locationsData` prop, the `AddressLocationsList`/`LocationDrawer` imports and their wiring (`openLocationsDrawer`, `isOpenLocationsDrawer`, `addressLocationsListRef`), the `"location-tab"` branch of `renderActionButton`, and the `<TabContent id="location-tab">` block.
+- FR-9: `AddressDetailsLayout.tsx` must render the generalized `CustomFieldsDeprecationAlert` (Locations-specific copy) once, near the top of the page (after `HeaderInside`, before the tab bar / info wrapper).
+- FR-10: `AddressDropdownMenu.tsx` must remove its `LocationDrawer` import and wiring (`openLocationDrawer`, `isOpenLocationDrawer`), and set the native `disabled` prop on the "Add Locations" `DropdownItem` (no `onClick`). Its position in the dropdown stays unchanged (between "Edit details" and "Add Recipients") — unlike the tab bar, a dropdown menu doesn't warrant reordering a single disabled item.
+- FR-11: `src/pages/address-details.tsx` (loader) must stop calling `getAddressLocationService`, drop `locationsData`/`LocationsPageData` from `AddressDetailsPageData`, drop the `searchLocations`/`pageLocations` query fields, and stop passing `locationsData` to `AddressDetailsLayout`.
+- FR-12: `usePageItems.ts` (`src/features/shared/hooks/`) must drop the now-unused `LOCATIONS` entries from the `SEARCH_PARAMS`/`PAGE_PARAMS` enums (no remaining consumer once `AddressLocationsList` is gone).
+- FR-13: `AddressData.ts` (`src/features/addresses/types/`) must drop the Locations-only types (`LocationData`, `LocationResponse`, `LocationParams`, `LocationCreatedResponse`, `ListLocationsParams`, `LocationInput`, `ApiLocationBaseParams`, `LocationsPageData`, `AddLocationsParams`, `EditDeleteLocationParams`) and the dead `locations` field from `AddressData`/`AddressInput` (never sent to, or read from, the address create/edit/list endpoints — confirmed unused outside the removed Locations slice).
+- FR-14: `CustomFieldsDeprecationAlert` must be generalized to accept its message via `children` (instead of hardcoded PO Numbers/Cost Centers/Releases copy) and moved to `src/features/shared/components/CustomFieldsDeprecationAlert/` (+ its `.scss`), since it now has two feature consumers (`org-units`, `addresses`) and cross-domain imports are not allowed by this project's conventions. `OrgUnitsDetailsLayout` is updated to import it from `shared` and pass its existing copy as `children`.
+- FR-15: `AddressDetailsLayout.tsx` renders `CustomFieldsDeprecationAlert` with Address-Locations-specific copy: replaced by Accounting Fields, discontinued 2026-07-30, upgrade path to plugin `v2.0.1+` / FastStore `v4`.
+- FR-16: Remove the now-orphaned `[data-fs-address-details-locations]` / `[data-fs-address-details-location]` dead CSS block and the `&[data-fs-bp-address-location-list]` selector from `address-details-layout.scss` (no longer referenced by any component after FR-4).
+- FR-17: Remove `LOCAL_STORAGE_LOCATION_EDIT_KEY` from `shared/utils/constants.ts` (only consumer was the removed `EditAddressLocationDrawer`).
+- FR-18: Delete the now-orphaned Cypress spec `cypress/integration/locations.test.ts` and the `TEST_DATA.LOCATIONS` block in `cypress/constants.ts`.
+- FR-19: Existing addresses that already have location values (created via the discontinued endpoint before 2026-07-30) must not error or lose data — there is simply no more UI to browse/manage them (see US-3, edge case).
+
+### Non-Functional Requirements
+
+- No feature flag — same rationale as the prior spec: fixed deadline (2026-07-30), targets a specific version line.
+- Pass `make lint`, `make typecheck`, and `make test`.
+- `TabOption`'s new `disabled` behavior ships without an automated unit test (see Decision 9) — verified manually instead, to avoid introducing a component-rendering test toolchain (`react-test-renderer`, `@types/react-test-renderer`, and a `@types/react` `resolutions` pin) for a single test file.
+- Folded into the same `1.3.88` release as `specs/deprecate-custom-fields.md` — no additional version bump; the `CHANGELOG.md` entry for `1.3.88` is extended to mention Address Locations alongside PO Numbers/Cost Centers/Releases.
+- The BFF team's 2026-07-22 confirmation (entire custom-fields API retired on 2026-07-30) already covers the `Location` custom field — no separate confirmation needed.
+
+### Out of Scope
+
+- Any change to the BFF/API.
+- The Accounting Fields feature itself (not backported to this version line).
+- A FeatureHub feature flag.
+- Localization of the new alert copy.
+- Any change to `main` (`v2.0.x`).
+- Data migration or cleanup of existing address location values created via the discontinued endpoint.
+- New Cypress/E2E coverage (removing the orphaned Cypress spec is in scope; adding new Cypress coverage is not).
+- Automated unit test coverage for `TabOption`'s new `disabled` behavior (see Decision 9 — reverted after implementation to avoid a component-testing toolchain for a single test file).
+- Renaming `CustomFieldsDeprecationAlert` — kept as-is (Address Locations is itself a custom field, so the name still fits), only its location and props change.
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+Mirror the approach already accepted in `specs/deprecate-custom-fields.md`: delete every piece of code that exists solely to support Address Locations (client, hooks, services, drawers, components), remove the Locations tab from the creation flow entirely (no more room to create new location values anywhere), and keep the two remaining "entry points" that historically pointed at this feature — the Address Details tab and the dropdown quick-add shortcut — visible but disabled, consistent with how the prior spec treated navigation entries and quick-add shortcuts. Generalize and relocate `CustomFieldsDeprecationAlert` to `shared/components/` so both `org-units` and `addresses` can render it with their own copy, respecting the project's "no cross-domain imports" rule.
+
+### Architecture Overview
+
+```mermaid
+flowchart TB
+  subgraph removed [Removed entirely]
+    Client["LocationsClient"]
+    Hooks["useAddLocationsToAddress, useAddressLocationList,\nuseAddressLocationEdit, useAddressLocationDelete"]
+    Services["services/locations/**"]
+    Components["LocationsDrawer, LocationForm, LocationField,\nAddressLocationsList, EditAddressLocationDrawer,\nDeleteAddressLocationDrawer"]
+    Types["Location*, ListLocationsParams, AddLocationsParams, etc."]
+    E2E["cypress/integration/locations.test.ts"]
+  end
+
+  subgraph createFlow ["CreateAddressDrawer — tab removed"]
+    CAD[CreateAddressDrawer]
+    CAD -->|Details, Recipients only| Tabs1["Tab / TabBar / TabContent"]
+  end
+
+  subgraph detailsFlow ["AddressDetailsLayout — tab disabled"]
+    TO["TabOption\n(+ disabled support)"]
+    ADL[AddressDetailsLayout]
+    Loader["address-details.tsx loader\n(stops fetching locationsData)"]
+    ADL --> TO
+    Loader --> ADL
+  end
+
+  subgraph dropdown ["AddressDropdownMenu — shortcut disabled"]
+    ADM[AddressDropdownMenu]
+  end
+
+  subgraph alert ["Generalized alert, moved to shared/"]
+    CFA["shared/components/CustomFieldsDeprecationAlert\n(children-driven copy)"]
+  end
+
+  ADL --> CFA
+  OUDL[OrgUnitsDetailsLayout] --> CFA
+```
+
+### Root Cause / Context Analysis
+
+| Aspect | Current state | Why it must change |
+|---|---|---|
+| `LocationsClient` | Calls `customers/{contractId}/units/{unitId}/custom-fields/location/values` | Same retiring endpoint family as PO Number/Cost Center/Release — confirmed by BFF |
+| "Locations" tab in `CreateAddressDrawer` | Fully functional; lets users add locations while creating an address | The underlying "add locations" call will fail after 2026-07-30; the field it collects (`locations`) is not even sent by `createNewAddressService`/`AddressesClient.createNewAddress` today — already effectively dead on the create path |
+| "Locations" tab in `AddressDetailsLayout` | Lists, adds, edits, deletes location values for an existing address | Same retiring endpoint; per the established pattern, the entry stays visible-but-disabled rather than vanishing |
+| `AddressDropdownMenu` "Add Locations" shortcut | Opens `LocationDrawer` to add locations to an existing address | Same retiring endpoint; matches how the prior spec disabled Org Units' quick-add shortcuts |
+| `CustomFieldsDeprecationAlert` | Lives in `org-units/components`, hardcoded PO Numbers/Cost Centers/Releases copy | `addresses` needs the same alert with different copy; per this project's Feature-per-Domain principle ("No domain may import directly from another domain"), it must move to `shared/components/` to be a legal import for both |
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| A. Disable the Locations tab's content in place, but keep `AddressLocationsList`/drawers as dead code behind the disabled tab | Smaller diff | Dead code calling a retiring endpoint if ever re-enabled by mistake; contradicts the "delete, don't disable" precedent for CRUD/listing code from the prior spec | Rejected |
+| B. Remove the Locations tab entirely from `AddressDetailsLayout` (not just disable it) | Simplest | User explicitly wants the entry to stay visible so it doesn't look like it "vanished"; also breaks the parallel with how PO Numbers/Cost Centers/Releases nav entries were handled | Rejected |
+| C. Keep `CustomFieldsDeprecationAlert` in `org-units` and let `addresses` import it directly | No file move needed | Violates the project's Feature-per-Domain rule (no direct cross-domain imports); `shared/` is the sanctioned way to share a component between two domains | Rejected |
+| D. Generalize + relocate `CustomFieldsDeprecationAlert` to `shared/components/` (this version) | Respects domain boundaries; single implementation, two copies of content | One extra file move + import update in `org-units` | **Accepted** |
+| E. Add a tooltip to the disabled "Locations" `TabOption`, matching `VerticalNavLink` | Consistent with the nav-link pattern | Redundant — the page already shows a persistent, more detailed alert; per user decision, adds UI noise for no benefit here | Rejected (user decision) |
+
+### Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| Addresses with pre-existing location values break when their details page is opened | Med | Low | The page no longer calls any location-listing endpoint at all — nothing left to fail; confirmed no other code reads `AddressData.locations` |
+| Relocating `CustomFieldsDeprecationAlert` breaks the existing `OrgUnitsDetailsLayout` usage | Med | Low | Update its import path and pass the exact same copy as `children`; no visual/behavioral change expected there |
+| `TabOption`'s new `disabled` prop breaks `CreateAddressDrawer`'s usage (its only other consumer) | Low | Low | `disabled` is optional, defaults to `false`/unset; `CreateAddressDrawer` doesn't pass it and is otherwise only losing its Locations tab, not touching `TabOption` itself |
+| Stale bookmarks/links with `?tab=location-tab` break | Low | Low | `AddressDetailsLayout`'s existing "invalid tab falls back to `address-tab`" logic is extended to treat `location-tab` as invalid (FR-7) |
+| Removing `usePageItems`'s `LOCATIONS` enum entries breaks another consumer | Med | Low | Verified via full-repo search: only `AddressLocationsList` (removed) and `address-details.tsx` (updated) reference them |
+
+### Key Decisions
+
+#### Decision 1: No tooltip on the disabled "Locations" tab — the page alert is enough
+
+- **Status**: Accepted (user decision)
+- **Context**: The prior spec added tooltips to disabled nav links because there was no other explanation on those pages. Here, a persistent alert is added to the same page as the disabled tab.
+- **Decision**: `TabOption`'s `disabled` state is purely visual (greyed out, `aria-disabled`, no click) — no `Tooltip` wrapper.
+- **Consequences**: Simpler `TabOption` implementation; no risk of repeating the clipping/positioning issues seen with `Tooltip` in narrow containers.
+
+#### Decision 2: Stale `?tab=location-tab` deep links fall back to "Details"
+
+- **Status**: Accepted (user decision)
+- **Context**: `AddressDetailsLayout` already has fallback logic for unrecognized tab query params.
+- **Decision**: Remove `"location-tab"` from the `AddressDetailTabId`/`validTabs` list used by that fallback logic, so it's treated exactly like any other invalid value.
+- **Consequences**: No special-casing needed; reuses existing, already-tested logic.
+
+#### Decision 3: "Add Locations" shortcut disabled, not removed
+
+- **Status**: Accepted (user decision)
+- **Context**: Matches the pattern used for the Org Units quick-add shortcuts in the prior spec (native `disabled`, no `onClick`), for consistency across the app.
+- **Decision**: Keep the `DropdownItem` in `AddressDropdownMenu`, set its native `disabled` prop, drop `onClick` and the `LocationDrawer` wiring.
+- **Consequences**: One less special case to remember; consistent visual language for "deprecated action" everywhere in the app.
+
+#### Decision 4: Generalize and relocate `CustomFieldsDeprecationAlert` to `shared/components/`
+
+- **Status**: Accepted
+- **Context**: The component currently lives in `org-units/components` with hardcoded copy. `addresses` needs the same visual treatment with different copy. This project's Feature-per-Domain principle forbids direct cross-domain imports (`org-units` → `addresses` or vice versa); `shared/` is the sanctioned path.
+- **Decision**: Move `CustomFieldsDeprecationAlert.tsx` (+ `.scss`) to `src/features/shared/components/CustomFieldsDeprecationAlert/`, change it to accept `children: ReactNode` for the message instead of hardcoding it, export it from `shared/components/index.ts`, and update `OrgUnitsDetailsLayout` to import it from `shared` and pass its existing copy as `children`. `AddressDetailsLayout` imports the same component from `shared` with its own copy.
+- **Consequences**: Single implementation (icon, alert styling, non-dismissible behavior) shared by both usages; each usage owns its own copy.
+
+#### Decision 5: Locations-only types and the dead `locations` field are removed, not just the client/hooks
+
+- **Status**: Accepted
+- **Context**: `AddressData.locations`/`AddressInput.locations` are never read or sent anywhere outside the removed Locations slice (confirmed via full-repo search — `AddressesClient.createNewAddress`/`editAddress` build an explicit field allowlist that never includes `locations`).
+- **Decision**: Remove the Locations-only types from `AddressData.ts` and drop the `locations` field from `AddressData`/`AddressInput`.
+- **Consequences**: Slightly smaller, more accurate type surface; no behavior change (the field was already write-only/dead).
+
+#### Decision 6: Implementation lands on the same open PR #409, no separate PR/branch
+
+- **Status**: Accepted (user decision, `/grill-me` round)
+- **Context**: PR #409 (branch `feat/deprecate-custom-fields`) was still `OPEN` with no `reviewDecision` at the time of this decision — i.e., unreviewed. Both specs also target the same still-unpublished `1.3.88` release (confirmed via `npm view`: latest published on `1.3.x` is `1.3.87`).
+- **Decision**: Implement this spec as additional commits on top of PR #409, rather than waiting for it to merge and opening a new PR.
+- **Consequences**: One consolidated PR/release for all custom-field deprecations; if #409 review drags on, this feature's rollout is coupled to it. Re-evaluate if #409 gets approved/merged before this spec is implemented.
+
+#### Decision 7: The disabled "Locations" tab moves to the end of the tab bar
+
+- **Status**: Accepted (user decision, `/grill-me` round)
+- **Context**: Current order is Details, Locations, Recipients. Disabling in place would leave a non-interactive tab between two functional ones.
+- **Decision**: Reorder to Details, Recipients, Locations (disabled) in `AddressDetailsLayout.tsx`. The "Add Locations" `DropdownItem` in `AddressDropdownMenu`, by contrast, keeps its current position — a dropdown doesn't carry the same "adjacent functional tabs" concern as a persistent tab bar.
+- **Consequences**: `AddressDetailTabId`/`validTabs` order is cosmetic only (doesn't affect fallback logic); only the JSX order of `<TabOption>` elements changes.
+
+#### Decision 8: `locations_count` analytics field is kept, hardcoded to `0`, not removed
+
+- **Status**: Accepted (user decision, `/grill-me` round)
+- **Context**: `CreateAddressDrawer`'s `address_creation` analytics event includes `locations_count`, computed from the `locations` state being removed. No downstream analytics consumer of this field could be verified from the codebase alone.
+- **Decision**: Keep the field in the event payload, hardcoded to `0`, instead of removing it from the event shape.
+- **Consequences**: Downstream dashboards/queries expecting this field keep working unchanged; the field becomes permanently `0` going forward (acceptable, since it always reflects "no locations creatable here anymore").
+
+#### Decision 9: Add one unit test for `TabOption`'s new `disabled` behavior — later reverted
+
+- **Status**: Superseded (user decision, post-implementation)
+- **Context**: The `addresses` feature has zero existing unit tests, which could justify skipping tests for consistency. However, `TabOption.disabled` is new logic (not a removal), and the project's constitution requires new features/logic to ship with at least one unit test. This was implemented (`TabOption.test.tsx`, using `react-test-renderer`), but pulled in `react-test-renderer`, `@types/react-test-renderer`, a `resolutions` pin for `@types/react` (needed to resolve a duplicate-`@types/react` typecheck conflict introduced by `@types/react-test-renderer`), and an `esbuild.jsx: "automatic"` change to `vitest.config.ts` — all solely to support this one test file.
+- **Decision**: Remove `TabOption.test.tsx` and revert every dependency/config change that existed only to support it: drop `react-test-renderer`, `@types/react-test-renderer`, and the `@types/react` `resolutions` pin from `package.json`; revert `vitest.config.ts`'s `esbuild.jsx: "automatic"` addition. `TabOption`'s `disabled` behavior (FR-6) ships without automated test coverage.
+- **Consequences**: No component-rendering test infrastructure is introduced by this spec; `TabOption`'s `disabled` prop relies on manual verification only. Re-introducing a similar test later would require re-adding the same dependencies (or an equivalent renderer/testing setup) and re-solving the same `@types/react` conflict.
+
+#### Decision 10: The Address Locations alert is non-dismissible, like the Org Units one
+
+- **Status**: Accepted (user decision, `/grill-me` round)
+- **Context**: Unlike the Org Units alert (shown once per org unit), this alert renders on every address's details page, raising a fatigue concern.
+- **Decision**: Keep `CustomFieldsDeprecationAlert` non-dismissible in both usages — no `onDismiss`/close affordance is added.
+- **Consequences**: Consistent behavior between the two usages with a single, simpler component; the short copy mitigates fatigue enough to not warrant the added complexity of a dismiss state (and its own persistence concerns, e.g. per-address dismissal storage).
+
+### Implementation Plan
+
+1. **Generalize and relocate the deprecation alert**
+   - Move `CustomFieldsDeprecationAlert.tsx` (+ `.scss`) from `src/features/org-units/components/` to `src/features/shared/components/CustomFieldsDeprecationAlert/`.
+   - Change its signature to accept `children: ReactNode` instead of hardcoded copy.
+   - Export it from `shared/components/index.ts`; update `OrgUnitsDetailsLayout.tsx`'s import and wrap its existing copy as `children`.
+
+2. **Remove the Locations tab from `CreateAddressDrawer`**
+   - Drop the `location-tab` `TabOption`/`TabContent`, the `locations` state, and the `LocationForm` import/usage. Keep `locations_count` in the analytics payload, hardcoded to `0` (Decision 8).
+
+3. **Add `disabled` support to `TabOption`, disable it in `AddressDetailsLayout`**
+   - `TabOption.tsx`: add optional `disabled` prop; render a native `disabled` `<button>` when set.
+   - `tab.scss`: add disabled-state styling (opacity + `cursor: not-allowed`), matching the project's established disabled-state visual language.
+   - `AddressDetailsLayout.tsx`: mark the "Locations" `TabOption` `disabled` and move it to the end of the tab bar (`Details`, `Recipients`, `Locations` — Decision 7); remove `"location-tab"` from `validTabs`/`AddressDetailTabId`; remove the `locationsData` prop, `AddressLocationsList`/`LocationDrawer` wiring, the `"location-tab"` `renderActionButton` branch, and the `<TabContent id="location-tab">` block; render the (relocated) `CustomFieldsDeprecationAlert` with Address-Locations copy near the top of the page.
+
+4. **Disable the "Add Locations" shortcut in `AddressDropdownMenu`**
+   - Remove `LocationDrawer` import/wiring; set native `disabled` on the "Add Locations" `DropdownItem`. Keep its current position in the menu (Decision 7).
+
+5. **Delete the Locations client/hooks/services/components**
+   - `clients/LocationsClient.ts`; `services/locations/**`; `hooks/useAddLocationsToAddress.ts`, `useAddressLocationList.ts`, `useAddressLocationEdit.ts`, `useAddressLocationDelete.ts`; `components/LocationsDrawer/**`, `LocationForm/**`, `AddressLocationsList/**`, `EditAddressLocationDrawer/**`, `DeleteAddressLocationDrawer/**`; update `hooks/index.ts` and `components/index.ts`.
+
+6. **Update the page loader**
+   - `src/pages/address-details.tsx`: remove the `getAddressLocationService` call, `locationsData`/`LocationsPageData`, and the `searchLocations`/`pageLocations` query fields.
+   - `usePageItems.ts`: remove the `LOCATIONS` entries from `SEARCH_PARAMS`/`PAGE_PARAMS`.
+
+7. **Trim types and dead CSS/constants**
+   - `AddressData.ts`: remove the Locations-only types and the `locations` field from `AddressData`/`AddressInput`.
+   - `get-default-address.service.ts`: drop `locations: []` from the mapped object.
+   - `address-details-layout.scss`: remove the orphaned `[data-fs-address-details-locations]`/`[data-fs-address-details-location]` block and the `&[data-fs-bp-address-location-list]` selector.
+   - `shared/utils/constants.ts`: remove `LOCAL_STORAGE_LOCATION_EDIT_KEY`.
+   - `shared/services/logger/analytics/constants.ts`: remove the now-unused `LOCATION_CREATED`/`LOCATION_EDITED`/`LOCATION_DELETED`/`LOCATION_*_ERROR` events.
+
+8. **Clean up Cypress**
+   - Delete `cypress/integration/locations.test.ts` and the `TEST_DATA.LOCATIONS` block in `cypress/constants.ts`.
+
+9. **Changelog**
+   - Extend the existing `[1.3.88]` `CHANGELOG.md` entry (from `specs/deprecate-custom-fields.md`) to mention Address Locations — no separate version bump (Decision 6: still unpublished, same PR #409).
+
+10. **Verification**
+    - Run `make check` (lint, typecheck, test).
+    - Manually verify against a linked host store: "Add address" shows only Details/Recipients; an address's details page shows a disabled "Locations" tab plus the alert; `?tab=location-tab` falls back to Details; the address actions dropdown's "Add Locations" is disabled; the Org Units alert (relocated component) still renders unchanged.
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+`AddressData` / `AddressInput` (trimmed — `locations` field removed):
+
+```typescript
+export type AddressData = AddressSummaryData &
+  AddressOption & {
+    geoCoordinates: string;
+  };
+
+export type AddressInput = {
+  id?: string;
+  isActive?: boolean;
+  profileId?: string;
+  name: string;
+  streetAddress: string;
+  streetAddress2: string;
+  streetNumber?: string;
+  country: string;
+  countryCode: string;
+  zip: string;
+  state: string;
+  geoCoordinates: string;
+  city: string;
+  types: string[];
+  neighborhood?: string;
+};
+```
+
+Removed entirely from `AddressData.ts`: `LocationData`, `LocationResponse`, `LocationParams`, `LocationCreatedResponse`, `ListLocationsParams`, `LocationInput`, `ApiLocationBaseParams`, `LocationsPageData`, `AddLocationsParams`, `EditDeleteLocationParams`.
+
+### Interfaces
+
+#### `CustomFieldsDeprecationAlert` (generalized, moved to `shared/components/`)
+
+```typescript
+export type CustomFieldsDeprecationAlertProps = {
+  children: ReactNode;
+};
+
+export const CustomFieldsDeprecationAlert = ({
+  children,
+}: CustomFieldsDeprecationAlertProps) => (
+  <Alert
+    data-fs-bp-custom-fields-deprecation-alert
+    icon={
+      <Icon
+        name="Warning"
+        width={20}
+        height={20}
+        data-fs-bp-custom-fields-deprecation-alert-icon
+      />
+    }
+  >
+    {children}
+  </Alert>
+);
+```
+
+Usage in `OrgUnitsDetailsLayout.tsx` (unchanged copy, now passed as `children`):
+
+```tsx
+<CustomFieldsDeprecationAlert>
+  PO Numbers, Cost Centers, and Releases management has been replaced by
+  Accounting Fields and was discontinued on <strong>07/30/2026</strong>.
+  Update to buyer-portal plugin <strong>v2.0.1</strong> or above and
+  FastStore <strong>v4</strong> to keep managing these fields.
+</CustomFieldsDeprecationAlert>
+```
+
+Usage in `AddressDetailsLayout.tsx` (new):
+
+```tsx
+<CustomFieldsDeprecationAlert>
+  Address Locations management has been replaced by Accounting Fields and
+  was discontinued on <strong>07/30/2026</strong>. Update to buyer-portal
+  plugin <strong>v2.0.1</strong> or above and FastStore <strong>v4</strong>{" "}
+  to keep managing locations.
+</CustomFieldsDeprecationAlert>
+```
+
+#### `TabOption` (updated)
+
+```typescript
+export type TabOptionProps = {
+  children?: React.ReactNode;
+  id: string;
+  disabled?: boolean;
+};
+
+export const TabOption = ({ children, id, disabled = false }: TabOptionProps) => {
+  const { setActiveTabId, activeTabId } = useTab();
+
+  return (
+    <button
+      data-fs-bp-tab-option
+      data-fs-bp-tab-option-is-active={activeTabId === id}
+      disabled={disabled}
+      aria-disabled={disabled}
+      onClick={() => setActiveTabId(id)}
+    >
+      {children}
+    </button>
+  );
+};
+```
+
+#### `AddressDetailsLayout` (updated tab set)
+
+```typescript
+type AddressDetailTabId = "address-tab" | "recipient-tab"; // "location-tab" removed
+
+const validTabs: AddressDetailTabId[] = ["address-tab", "recipient-tab"];
+```
+
+`AddressDetailsLayoutProps` drops `locationsData: LocationsPageData`.
+
+#### `address-details.tsx` loader (trimmed)
+
+`AddressDetailsPageData.data` drops `locationsData: LocationsPageData | null`; the loader stops calling `getAddressLocationService` and stops reading `searchLocations`/`pageLocations` from the query.
+
+### Component Boundaries
+
+| Module | Responsibility after this change |
+|---|---|
+| `shared/components/CustomFieldsDeprecationAlert` | Generic, non-dismissible deprecation alert; message supplied by each caller via `children` |
+| `TabOption` (`shared/components/Tab`) | Renders a normal clickable tab, or (when `disabled`) a native-disabled, non-interactive one |
+| `CreateAddressDrawer` | Details + Recipients only; no Locations tab, no `locations` state |
+| `AddressDetailsLayout` | Details/Recipients tabs fully functional; Locations tab visible-but-disabled; renders the deprecation alert; no location data fetching |
+| `AddressDropdownMenu` | Edit details / Add Recipients / Remove / Delete fully functional; "Add Locations" disabled |
+| `OrgUnitsDetailsLayout` | Unchanged behavior; now imports the alert from `shared` instead of `org-units/components` |
+
+### Integration Points
+
+- **BFF** — same retiring custom-fields API as the prior spec; the `Location` field type is covered by the same 2026-07-30 date.
+- **`org-units`** — only affected by the `CustomFieldsDeprecationAlert` relocation (import path change, no behavior change).
+- **Host store** — no route changes; the Address Details page keeps the same URL, just with one fewer valid tab.
+
+### Invariants & Constraints
+
+- The "Locations" tab and the "Add Locations" dropdown item must remain present (label-wise) — only their interactivity changes, matching the precedent set for PO Numbers/Cost Centers/Releases nav entries.
+- No domain may import another domain's components directly — `CustomFieldsDeprecationAlert` must live under `shared/components/`.
+- Existing addresses with pre-existing location values must not error when their details page is loaded.
+- No feature flag gates this behavior.
+
+### Files to Change / Remove
+
+| File | Change |
+|---|---|
+| `src/features/addresses/clients/LocationsClient.ts` | **Remove** |
+| `src/features/addresses/services/locations/**` | **Remove entirely** |
+| `src/features/addresses/hooks/useAddLocationsToAddress.ts`, `useAddressLocationList.ts`, `useAddressLocationEdit.ts`, `useAddressLocationDelete.ts` | **Remove** |
+| `src/features/addresses/hooks/index.ts` | Drop the 4 removed exports |
+| `src/features/addresses/components/LocationsDrawer/**` | **Remove entirely** |
+| `src/features/addresses/components/LocationForm/**` (incl. `LocationField/**`) | **Remove entirely** |
+| `src/features/addresses/components/AddressLocationsList/**` | **Remove entirely** |
+| `src/features/addresses/components/EditAddressLocationDrawer/**` | **Remove entirely** |
+| `src/features/addresses/components/DeleteAddressLocationDrawer/**` | **Remove entirely** |
+| `src/features/addresses/components/index.ts` | Drop `LocationForm`, `LocationDrawer`, `AddressLocationsList` exports |
+| `src/features/addresses/components/CreateAddressDrawer/CreateAddressDrawer.tsx` | Remove Locations tab, `locations` state, `LocationForm` usage; keep `locations_count` analytics field hardcoded to `0` |
+| `src/features/addresses/components/AddressDropdownMenu/AddressDropdownMenu.tsx` | Remove `LocationDrawer` wiring; set native `disabled` on "Add Locations" (position unchanged) |
+| `src/features/addresses/layouts/AddressDetailsLayout/AddressDetailsLayout.tsx` | Disable Locations tab and move it to the end of the tab bar; drop `location-tab` from valid tabs; remove `locationsData`/list/drawer wiring; render the (relocated) alert |
+| `src/features/addresses/layouts/AddressDetailsLayout/address-details-layout.scss` | Remove orphaned Locations CSS blocks |
+| `src/features/addresses/types/AddressData.ts` | Remove Locations-only types; drop `locations` field from `AddressData`/`AddressInput` |
+| `src/features/addresses/services/default-values/get-default-address.service.ts` | Drop `locations: []` from the mapped object |
+| `src/features/shared/components/Tab/TabOption.tsx` | Add `disabled` support |
+| `src/features/shared/components/Tab/tab.scss` | Add disabled-state styling |
+| `src/features/org-units/components/CustomFieldsDeprecationAlert/**` | **Move** to `src/features/shared/components/CustomFieldsDeprecationAlert/**`; generalize to accept `children` |
+| `src/features/shared/components/index.ts` | Export the relocated `CustomFieldsDeprecationAlert` |
+| `src/features/org-units/components/index.ts` | Drop the local `CustomFieldsDeprecationAlert` export |
+| `src/features/org-units/layouts/OrgUnitDetailsLayout/OrgUnitDetailsLayout.tsx` | Update import path; pass existing copy as `children` |
+| `src/features/org-units/layouts/OrgUnitDetailsLayout/org-units-details.scss` | Update the relocated `.scss` import path |
+| `src/pages/address-details.tsx` | Remove `getAddressLocationService` call and `locationsData`/query fields |
+| `src/features/shared/hooks/usePageItems.ts` | Remove `LOCATIONS` entries from `SEARCH_PARAMS`/`PAGE_PARAMS` |
+| `src/features/shared/utils/constants.ts` | Remove `LOCAL_STORAGE_LOCATION_EDIT_KEY` |
+| `src/features/shared/services/logger/analytics/constants.ts` | Remove `LOCATION_*` analytics events |
+| `cypress/integration/locations.test.ts` | **Remove** |
+| `cypress/constants.ts` | Remove `TEST_DATA.LOCATIONS` block |
+| `CHANGELOG.md` | Extend the existing `[1.3.88]` entry to mention Address Locations |
+
+### Explicitly Not Touched
+
+- `RecipientsForm`, `RecipientItem`, `AddressRecipientsList`, their hooks (`useSearchAddressRecipients`, `useAddRecipientsToAddress`, `useDeleteRecipientAddress`, `useEditRecipientsToAddress`), services (`services/recipients/**`), and `RecipientsClient`.
+- Generic `shared/components` used by both Locations (removed) and Recipients (kept): `Table`, `InternalSearch`, `EmptyState`, `Paginator`, `BasicDrawer`, `IconButton`, `Icon`, `InputText` — none of them are Locations-specific.
+- `AddressForm`, `ExistingAddress`, `AddressLine`, `AddressesCard` — confirmed no reference to the removed `locations` field.
+- Everything already covered by `specs/deprecate-custom-fields.md` (PO Numbers, Cost Centers, Releases, `budgets`, `buying-policies`, `org-units` quick-add for those three fields) — unaffected by this spec beyond the `CustomFieldsDeprecationAlert` relocation.
+- Version bump / release mechanics — reuses the `1.3.88` release already planned in the prior spec.