@vtex/faststore-plugin-buyer-portal 2.0.15 → 2.0.16

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.16] - 2026-07-28
+
+### Added
+
+- Custom roles now appear in the role selector alongside native roles in every create/edit user flow, with no client-side whitelist filtering the BFF's role list (`RoleData.isCustom?: boolean`)
+- New `RolesMultiSelect` component: a searchable multi-select combobox (removable chips, inline search, keyboard navigation, minimum-one-role guard, above/below flip positioning) replacing the static role checkbox list in `UserFormFields`, `CreateUserDrawer`, and `UpdateUserDrawer`; custom roles are marked with a "Custom" tag in the dropdown
+
+### Fixed
+
+- Role checkbox/list ids were generated with `.replace(" ", "-")`, which only replaced the first space and could produce malformed or colliding ids for role names with multiple spaces or special characters (e.g. merchant-defined custom roles); id generation now uses a global regex
+
 ## [2.0.15] - 2026-07-27
 
 ### Fixed
@@ -792,7 +803,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/v2.0.15...HEAD
+[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.16...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
@@ -890,6 +901,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [2.0.10]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.9...v2.0.10
 [2.0.9]: https://github.com/vtex/faststore-plugin-buyer-portal/releases/tag/2.0.9
 
+[2.0.16]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.15...v2.0.16
 [2.0.15]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.14...v2.0.15
 [2.0.14]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.13...v2.0.14
 [2.0.13]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.12...v2.0.13

package/package.json

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

package/specs/custom-roles-selector.md

@@ -0,0 +1,337 @@
+# Custom Roles in the Role Selector (Organization Account)
+
+> **Status**: Done
+> **Created**: 2026-07-22
+> **References**: Jira [B2BTEAM-3388](https://vtex-dev.atlassian.net/browse/B2BTEAM-3388) (this ticket) · Epic [B2BTEAM-3385](https://vtex-dev.atlassian.net/browse/B2BTEAM-3385) (BFF `buyer-portal-graphql`) · BFF PR `vtex/buyer-portal-graphql#303` · Design Handoff & Prototype (Google Drive, linked from B2BTEAM-3388)
+
+---
+
+## 1. Business Context
+
+### Problem Statement
+
+Merchants can now define **custom roles** in Identity (Storefront Roles) alongside VTEX's native roles. The Organization Account BFF (`buyer-portal-graphql`) already exposes these dynamically through its existing roles endpoints — the frontend in this repo has never hardcoded a role whitelist, so nothing is technically blocking custom roles from appearing. What's missing is:
+
+1. The `RoleData` type doesn't carry the `isCustom` flag the BFF will start returning, so the UI has no way to tell native and custom roles apart.
+2. The role picker itself is a plain static checkbox list (`@faststore/components` `CheckboxField`), which the design team has explicitly superseded with a searchable multi-select combobox (chips + inline search + dropdown) — the handoff states this component **replaces** the current role list in Organization Account's create/edit user flows.
+3. A longstanding id-generation bug (`role.roleName.toLowerCase().replace(" ", "-")`, non-global) silently produces malformed DOM ids for any role name with more than one space — a near-certainty for merchant-authored custom role names.
+
+Without this work, a Buyer Admin who has configured a custom role in Identity has no way to assign it to a user from the Organization Account portal.
+
+### Goals
+
+1. Let Buyer Admins see and assign **any** role the BFF returns — native or custom — with zero client-side name filtering.
+2. Ship the multi-select combobox role selector specified in the design handoff (chips, inline search, dropdown listbox), replacing the static checkbox list across every create/edit user entry point in Organization Account.
+3. Visually distinguish custom roles from native ones in the picker.
+4. Fix the id/key generation bug so role names with any spacing or special characters render and behave correctly.
+5. Preserve the existing role-assignment payload contract (`{ userId, roles: [{ roleName, isActive }] }`) — no BFF or contract changes originate from this spec.
+
+### User Stories
+
+#### US-1: Assign a custom role when creating a user
+
+- **Story**: As a Buyer Admin, I want to select a merchant-defined custom role while creating a user, so that the user gets the exact permission set my organization configured.
+- **Acceptance Criteria**:
+  - **Given** the "Create User" drawer is open and the BFF returned at least one role with `isCustom: true`, **when** the role field is opened, **then** the custom role appears in the dropdown alongside native roles, with no code-level filtering by name.
+  - **Given** the dropdown is open, **when** the Buyer Admin clicks a custom role's row, **then** it becomes selected, appears as a chip in the field, and remains selected if the dropdown is reopened.
+  - **Given** at least one custom role is selected, **when** the form is submitted, **then** the created user's role assignment includes that role's `roleName`.
+
+#### US-2: Assign a custom role when editing a user
+
+- **Story**: As a Buyer Admin, I want to add a custom role to an existing user, so that I can grant new permissions without recreating the user.
+- **Acceptance Criteria**:
+  - **Given** the "Edit User" drawer is open for a user with only native roles, **when** the Buyer Admin selects a custom role and saves, **then** the update payload includes `{ roleName: "<custom role>", isActive: true }`.
+  - **Given** the update succeeds, **when** the drawer is reopened (or the page reloads) for that same user, **then** the custom role appears pre-selected (as a chip) reflecting the persisted state.
+
+#### US-3: Unassign a custom role
+
+- **Story**: As a Buyer Admin, I want to remove a custom role from a user, so that I can revoke permissions that are no longer needed.
+- **Acceptance Criteria**:
+  - **Given** a user currently has a custom role assigned, **when** the Buyer Admin removes its chip (or unchecks it in the dropdown) and saves, **then** the update payload includes `{ roleName: "<custom role>", isActive: false }`.
+  - **Given** the removal is saved, **when** the drawer is reopened, **then** the custom role no longer appears selected.
+  - **Given** a user has only one role selected, **when** the Buyer Admin attempts to remove it (via chip or dropdown row), **then** the removal is blocked — at least one role must always remain selected.
+
+#### US-4: Distinguish custom vs. native roles at a glance
+
+- **Story**: As a Buyer Admin, I want to tell which roles are merchant-defined vs. native VTEX roles, so that I understand what I'm assigning.
+- **Acceptance Criteria**:
+  - **Given** the dropdown is open, **when** a role has `isCustom: true`, **then** its row shows a small "Custom" tag next to the role name.
+  - **Given** a role has `isCustom: false` or the field is absent (native roles, or an older BFF response), **when** the row renders, **then** no "Custom" tag is shown.
+  - **Given** a custom role is selected, **when** it renders as a chip in the field, **then** the chip shows the role name only (no "Custom" tag on chips).
+
+#### US-5: Search/filter a long role list
+
+- **Story**: As a Buyer Admin managing an organization with many custom roles, I want to search the role list, so that I can find a specific role quickly instead of scrolling.
+- **Acceptance Criteria**:
+  - **Given** the role field is focused, **when** the Buyer Admin types text, **then** the dropdown filters to roles whose name (or description, when present) contains the typed text, case-insensitive, updating on every keystroke.
+  - **Given** the typed text matches no role, **when** the dropdown renders, **then** it shows a "No matches" state instead of an empty list.
+  - **Given** the Buyer Admin clears the search text, **when** the dropdown re-renders, **then** the full role list is restored.
+
+#### US-6: Legacy flow parity
+
+- **Story**: As a Buyer Admin on a merchant still using the legacy (non-username) login flow, I want the same custom-role support, so that I'm not blocked from using custom roles just because my organization hasn't migrated to the newer login flow.
+- **Acceptance Criteria**:
+  - **Given** `featureFlags.enableAlternativeLogin` is `false`, **when** the legacy `CreateUserDrawer` or `UpdateUserDrawer` is opened, **then** the same multi-select combobox (with custom-role support) is used — not the old inline checkbox list.
+  - **Given** the legacy flow, **when** a role name contains multiple spaces or special characters, **then** it renders and is selectable without generating a malformed DOM id.
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected Result |
+|---|---|---|---|
+| Happy path — assign native + custom together | Create User drawer open; BFF returns 2 native + 1 custom role | Select "Buyer" (native), then "Report Viewer" (custom) | Both appear as chips; submit payload includes both roleNames |
+| Happy path — search narrows results | Edit User drawer open; 8 roles available | Type "appro" in the field | Dropdown shows only "Order Approver"-like matches; other rows hidden |
+| Error/guard — cannot remove the last role | User has exactly 1 role selected | Click that role's chip remove button, or click its dropdown row | Chip's remove control is hidden/disabled; dropdown row is visually muted and non-interactive; role stays selected |
+| Edge case — multi-space custom role name | BFF returns a custom role named `"Regional  Sales  Lead"` (double spaces) | Open dropdown, select the role, inspect generated DOM id/key | Renders correctly, is selectable, and produces a well-formed id (no literal space in the id string) |
+| Edge case — role with no description | BFF returns a custom role with `roleName` and `roleId` only (no description field, as is the current real contract) | Open dropdown | Row renders with name only; no blank/broken second line, no console error |
+| Edge case — dropdown flip near drawer bottom | Field is positioned near the bottom of a scrolled drawer | Open the dropdown | Dropdown flips to open above the field instead of overflowing the drawer |
+| Edge case — legacy flow with `enableAlternativeLogin=false` | Legacy CreateUserDrawer, custom role available | Open role field, select custom role, submit | Same behavior as the new-flow drawers; role assigned correctly |
+
+### Functional Requirements
+
+**Data source**
+- The role list is read exclusively from `getRolesAndPermissionsIds` (`GET .../roles/ids`) — no hardcoded role name list or whitelist filters the result at any point.
+- `RoleData` gains an optional `isCustom?: boolean`. Its absence (older BFF response, or a native role that omits it) must be treated as "not custom" — never as an error.
+
+**Component anatomy** (per design handoff)
+- A field with a floating "Roles" label; the entire field is clickable; no trailing icons.
+- Selected roles render as removable chips inside the field.
+- An inline search input shares the same field, to the right of the last chip.
+- A dropdown listbox anchored to the field, opened on click/focus/Tab.
+
+**Behavior**
+- Opening: clicking anywhere in the field opens the dropdown and focuses the search input; Tab into the field also opens it.
+- Filtering: case-insensitive, matches role name (and description when present); updates live as the user types; keeps selected chips visible while filtering; restores the full list when the search is cleared.
+- Selection: clicking a dropdown row toggles that role; the dropdown stays open after a selection so multiple roles can be picked in one interaction.
+- Minimum-selection rule: at least one role must always stay selected. When exactly one role is selected, that role's chip-remove control and its dropdown row both become non-interactive (visually muted).
+- Removal: via chip remove button, via clicking the already-selected dropdown row, or via Backspace when the search input is empty (removes the most recently selected role; only when more than one role is selected).
+- Keyboard: ArrowDown/ArrowUp move the highlighted row; Enter toggles the highlighted row; Escape closes the dropdown, clears the search text, and returns focus to the field; current selections are preserved on close.
+- Positioning: dropdown opens below the field by default, flips above when there isn't enough room, and stays fully within the drawer's viewport (recalculated on open and on resize/scroll) — not the full browser window, since this field lives inside a side drawer.
+- "Custom" indicator: a small tag next to the role name, in the dropdown row only, shown when `isCustom` is `true`. Not shown on chips.
+- Missing description: if a role has no description, its dropdown row renders with the name only — no blank line, no layout shift, no error.
+
+**Assignment payload**
+- Unchanged: `updateRoles` continues to send `{ userId, roles: [{ roleName, isActive }] }`. This spec does not alter the BFF contract.
+
+**id/key generation**
+- Any DOM id or React key derived from a role name must use a global replace (e.g. `/[^a-z0-9]+/gi` or at minimum `/ /g`) so role names with multiple spaces or special characters never produce a malformed id or a key collision.
+
+**Scope of replacement**
+- The new component replaces the existing checkbox-based role UI in all three integration points in this repo:
+  1. `UserFormFields` (shared by `CreateUserDrawerWithUsername` and `UpdateUserDrawerWithUsername`)
+  2. `CreateUserDrawer` (legacy flow)
+  3. `UpdateUserDrawer` (legacy flow)
+
+### Non-Functional Requirements
+
+- **Accessibility**: dropdown exposed as a listbox; options announced with their selection state; chip-remove buttons individually focusable and announced; role descriptions available to assistive technology as supplementary (not primary) content; full keyboard operability (Tab, Escape, ArrowUp/Down, Enter, Backspace).
+- **Resilience**: the component must never crash or blank-render when `isCustom` or a description is absent from the API response — both are optional and must degrade gracefully.
+- **Test coverage**: unit/component tests for the id-generation fix (multi-space and special-character role names), the "Custom" tag rendering (present/absent), and the component's core behavior (selection, minimum-one-role guard, keyboard navigation, search filtering) — using mocked `RoleData`, with no dependency on a live BFF or a real Identity-configured custom role.
+- **No new feature flag**: the change ships unconditionally. The BFF contract change is additive (more list items + an optional field), so there's no unsafe state for merchants without custom roles configured.
+- **No new localization key**: the "Custom" tag and the field's "Roles" label are hardcoded English strings for this iteration; they do not go through the CMS-backed `t()` localization system (see Key Decision 6).
+
+### Out of Scope
+
+- Any BFF/backend changes — covered by Epic B2BTEAM-3385 / PR `vtex/buyer-portal-graphql#303`, assumed merged and available.
+- Contract Manager / Admin UI (`vtex/contracts-management` repo, Jira B2BTEAM-3386) — separate repository, separate ticket, different design system (Shoreline).
+- Creating roles or permissions in Identity.
+- Displaying a custom role's resources/permissions in the role-details page (`RolesLayout` / `RoleDetailsLayout`) — unchanged by this spec; a candidate for a future, separate task.
+- Cypress e2e coverage — would require a real custom role seeded via Identity in `b2bfaststoredev.store`, which is outside this repo's control; manual QA against a real merchant remains the validation path for the ticket's "Validação" checklist.
+- The hardcoded `USER_ROLES.SUPER_USER = "Super Buyer Admin"` check in `OrgUnitBreadcrumb.tsx` — a pre-existing, unrelated coupling to a role name (breadcrumb hierarchy visibility, not role selection). Left untouched; noted as a related risk.
+- Adding `isCustom` awareness to the already-existing role-name `<Tag>` pills in `UsersLayout.tsx` / `UserDetailsLayout.tsx` (which show a user's *already-assigned* roles) — those views only have role names today, not `RoleData`; out of scope for this ticket.
+- Adding a real CMS localization entry for the new "Custom"/"Roles" strings.
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+Build one new shared component — a role multi-select field — in `src/features/users/components/`, and use it from all three integration points (`UserFormFields`, `CreateUserDrawer`, `UpdateUserDrawer`), replacing their respective `CheckboxField`/inline-checkbox blocks. Rather than building the combobox from scratch, extend this repo's existing `AutocompleteDropdown` (which already implements the open/close, keyboard nav, and above/below flip-positioning logic needed) into a multi-select variant, and reuse `@faststore/components`'s `Tag` (which already supports a removable-chip pattern via `onClose`) for the selected-role chips. The "Custom" indicator reuses this repo's own lightweight `Tag` (`src/features/shared/components/Tag`), already used elsewhere for role-name pills.
+
+`RoleData` gains `isCustom?: boolean`. Selection state stays `roleId`-based (`number[]`), matching the existing `UserFormState.roles` shape — no change to how the assignment payload is built downstream (`roleId → roleName` translation already happens before submit).
+
+### Architecture Overview
+
+```mermaid
+flowchart TD
+    BFF["BFF: GET .../roles/ids\n{ roleId, roleName, isCustom? }"] --> Hook[useGetRolesOptions]
+    Hook --> RoleData["RoleData[] (rolesOptions)"]
+
+    RoleData --> UFF[UserFormFields]
+    RoleData --> CUD[CreateUserDrawer legacy]
+    RoleData --> UUD[UpdateUserDrawer legacy]
+
+    UFF --> RS1[RolesMultiSelect]
+    CUD --> RS2[RolesMultiSelect]
+    UUD --> RS3[RolesMultiSelect]
+
+    RS1 --> Chips["Selected chips (Tag + onClose)"]
+    RS1 --> Dropdown["Dropdown listbox (checkbox + name + optional description + Custom tag)"]
+    Dropdown --> Position[useAutocompletePosition-style flip/positioning]
+
+    RS1 -->|"onChange(roleId[])"| FormState["UserFormState.roles: number[]"]
+    FormState --> Submit["roleId -> roleName translation (existing)"]
+    Submit -->|"{ userId, roles: [{ roleName, isActive }] }"| UpdateRoles["POST .../users/roles"]
+```
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| Minimal patch: keep the checkbox list, just add an `isCustom` text suffix and fix the id bug | Smallest possible diff; lowest risk | Directly contradicts the design handoff, which explicitly states the new component *replaces* the current role list; ships a UI the design/product side didn't ask for | Rejected |
+| Adopt a third-party combobox library (e.g. `downshift`, `react-select`) | Less code to write and maintain in-house; battle-tested a11y | New dependency with bundle-size cost; doesn't out-of-the-box solve drawer-scoped positioning/flip; this repo already has a working in-house pattern (`AutocompleteDropdown`) that solves the hard parts | Rejected |
+| Extend `AutocompleteDropdown` in place to support multi-select natively (add a `multiple` prop) | Single source of truth for all dropdown-style fields in the repo | `AutocompleteDropdown` is used elsewhere for single-select (e.g. `OrgUnitInputSearch`); overloading it with chip-rendering and a different selection model risks regressing existing single-select consumers | Rejected — build a sibling component that reuses the same positioning/keyboard building blocks instead of overloading the existing one |
+| New shared `RolesMultiSelect` composing existing primitives (`AutocompleteDropdown`'s positioning approach + `Tag`) | Reuses proven positioning/keyboard logic; isolated blast radius; matches design handoff scope exactly | One more component in the tree | **Accepted** |
+
+### Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| BFF PR `#303` not yet merged/available when this ships | High — no custom roles to test against in a live environment | Medium | Contract is additive; `isCustom` is optional and code treats its absence as "native." Development/testing can proceed against mocked `RoleData` regardless of BFF deploy timing. |
+| New interactive component (keyboard nav, chip removal, positioning) ships with only unit/component test coverage, no e2e | Medium — real-environment regressions (positioning inside the actual drawer, real screen readers) could slip through | Medium | Thorough component tests per the Non-Functional Requirements; the ticket's "Validação" checklist is run manually against a merchant with a real custom role before considering the ticket done. |
+| Legacy drawer flow (`enableAlternativeLogin=false`) regresses since it's touched alongside the newer flow | Medium — some merchants still run this flow | Low–Medium | Both legacy drawers are explicitly in scope (US-6) and get the same component and the same test coverage as the new flow. |
+| Hardcoded "Custom"/"Roles" strings ship without localization | Low — cosmetic, English-only for non-English storefronts | High (accepted trade-off) | Explicitly scoped out of this iteration (Key Decision 6); flagged here so it isn't mistaken for an oversight. |
+| `USER_ROLES.SUPER_USER` hardcoded role-name check elsewhere in the codebase remains unaddressed | Low–Medium — a merchant renaming/removing that specific native role could silently break unrelated breadcrumb visibility logic | Low | Explicitly out of scope; documented here as a known, pre-existing risk unrelated to this spec's changes. |
+
+### Key Decisions
+
+#### Decision 1: No role-level "description" from the BFF — render gracefully without it
+
+- **Status**: Accepted
+- **Context**: The design handoff's dropdown row shows an optional description under the role name. The confirmed BFF contract (`getRolesAndPermissionsIds` → `{ roleId, roleName, isCustom? }`) carries no description field, and `getRolesAndPermissions`'s `RolePermission.description` describes a *permission*, not a role.
+- **Decision**: Render dropdown rows with name-only for now; the description slot is supported by the component (single line, truncated) but simply won't render until/unless the BFF adds a role-level description field in a future iteration.
+- **Consequences**: Matches the current real contract exactly; no risk of ever rendering a blank second line or throwing on `undefined.description`. Revisit once/if the BFF adds this field.
+
+#### Decision 2: "Custom" indicator only in the dropdown row, not on chips
+
+- **Status**: Accepted
+- **Context**: The design prototype's own mock data (`ROLE_OPTIONS`) has no concept of `isCustom` at all — the handoff doesn't specify where this indicator goes.
+- **Decision**: Show a small "Custom" tag next to the role name in the dropdown row when `isCustom` is `true`. Selected chips remain name-only to keep the field visually uncluttered.
+- **Consequences**: Keeps the always-visible chip row simple; the distinction is available at the moment a Buyer Admin is choosing roles, which is when it matters most.
+
+#### Decision 3: One shared component replaces all three duplicated integration points
+
+- **Status**: Accepted
+- **Context**: Today, role-checkbox rendering is duplicated three ways: `UserFormFields` (shared by the two `*WithUsername` drawers) and separately inlined in each of the two legacy drawers.
+- **Decision**: Build a single new component and use it from all three call sites, rather than adding a fourth slightly-different implementation or patching each of the three independently.
+- **Consequences**: Eliminates ongoing duplication instead of adding to it; a future behavior change (e.g. adding the description field once the BFF supports it) only needs to happen in one place.
+
+#### Decision 4: Ship unconditionally — no new feature flag
+
+- **Status**: Accepted
+- **Context**: This repo has an established feature-flag pipeline (FeatureHub → BFF → type → normalization) used for flags like `enableAlternativeLogin`.
+- **Decision**: This change ships without a new flag. The BFF contract change is additive (more list items, one optional field), so there's no unsafe intermediate state — merchants without custom roles configured simply never see `isCustom: true` entries.
+- **Consequences**: Faster rollout, less pipeline overhead. If a rollback is ever needed, it's a standard revert rather than a flag flip.
+
+#### Decision 5: Unit/component tests only — no new Cypress e2e coverage
+
+- **Status**: Accepted
+- **Context**: The ticket's "Validação" checklist (custom role appears in selector, persists after reload, combines with native roles, special-character names work) reads as manual QA steps against a real merchant with a custom role configured via Identity.
+- **Decision**: Add unit/component tests for the component's own logic (selection, keyboard nav, minimum-role guard, id-gen fix, `isCustom` rendering) using mocked data. Do not add Cypress e2e for the custom-role scenarios, since that would require seeding a real custom role in `b2bfaststoredev.store` via Identity — outside this repo's control.
+- **Consequences**: The manual "Validação" checklist remains the acceptance gate for true end-to-end custom-role behavior; automated coverage protects the component's own logic against regressions.
+
+#### Decision 6: Hardcode new UI strings; skip the `t()` localization system for this iteration
+
+- **Status**: Accepted
+- **Context**: This repo's `t(key, interpolations?)` localization function resolves labels from a remote CMS-backed catalog and has no fallback-string parameter — a missing key renders the raw key string (e.g., literally `"roles.labels.custom"`) rather than degrading gracefully.
+- **Decision**: Hardcode the English strings "Custom" and "Roles" directly in the component rather than routing them through `t()`, since the corresponding CMS keys don't exist yet and there's no safe fallback mechanism to lean on.
+- **Consequences**: These two strings won't be localized until a follow-up adds the CMS keys and switches the calls to `t()`. Documented explicitly so it isn't mistaken for an oversight.
+
+#### Decision 7: `USER_ROLES.SUPER_USER` hardcoded check is out of scope
+
+- **Status**: Accepted
+- **Context**: `src/features/users/types/UserRoles.ts` hardcodes `SUPER_USER = "Super Buyer Admin"`, checked in `OrgUnitBreadcrumb.tsx` to grant full hierarchy visibility — a real hardcoded-role-name dependency, but unrelated to the role *selector* this spec targets.
+- **Decision**: Leave it untouched. This spec's "no hardcoded role name" requirement applies to the role list/selector data path, not to this separate breadcrumb-visibility feature.
+- **Consequences**: The risk (a merchant renaming/removing that specific role could silently affect breadcrumb visibility) persists and is documented in the Risks table above for future consideration.
+
+### Implementation Plan
+
+1. **Type update** — add `isCustom?: boolean` to `RoleData` (`src/features/roles/types/RolesData.ts`).
+2. **Build the shared component** — new `RolesMultiSelect`-style component (naming finalized during implementation) composing selected-role chips (`@faststore/components` `Tag` + `onClose`), an inline search input, and a dropdown listbox reusing this repo's existing flip/positioning approach (`AutocompleteDropdown`/`useAutocompletePosition` as the base pattern). Include the "Custom" tag (this repo's `Tag`) in dropdown rows and the corrected global-regex id/key generation.
+3. **Wire into `UserFormFields`** — replace its `CheckboxField`-based block with the new component (serves both `CreateUserDrawerWithUsername` and `UpdateUserDrawerWithUsername`).
+4. **Wire into the legacy drawers** — replace the inlined checkbox JSX in `CreateUserDrawer` and `UpdateUserDrawer` with the same new component.
+5. **Unit/component tests** — id-generation edge cases (multi-space, special characters), `isCustom` tag presence/absence, missing-description graceful rendering, selection/keyboard/minimum-role-guard behavior.
+6. **Manual QA** — run the ticket's "Validação" checklist against a merchant with a real custom role configured via Identity (native + custom combination, link/unlink + reload, long/special-character custom role name).
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+```typescript
+// src/features/roles/types/RolesData.ts
+export interface RoleData {
+  roleName: string;
+  roleId: number;
+  isCustom?: boolean; // NEW — optional; absence means "not custom"
+}
+
+// Unchanged
+export interface RolePermission {
+  label: string;
+  description: string;
+  inRole: boolean;
+}
+
+export interface UserRoles {
+  roleName: string;
+  isActive: boolean;
+}
+
+export interface UpdateUserRoles {
+  userId: string;
+  roles: UserRoles[];
+}
+
+// Unchanged — src/features/users/components/UserFormFields/UserFormFields.tsx
+export type UserFormState = {
+  login: string;
+  name: string;
+  email: string;
+  phone: string;
+  transactionalEmail: string;
+  useLoginAsTransactional: boolean;
+  roles: number[]; // roleId[] — no shape change
+};
+```
+
+### Interfaces
+
+```typescript
+// New shared component (path/name finalized during implementation,
+// e.g. src/features/users/components/RolesMultiSelect/RolesMultiSelect.tsx)
+interface RolesMultiSelectProps {
+  /** Full list of assignable roles for this account, from getRolesAndPermissionsIds. */
+  options: RoleData[] | null;
+  /** Currently selected role ids. */
+  selected: number[];
+  /** Called with the full next selection whenever a role is toggled or removed. */
+  onChange: (roleIds: number[]) => void;
+  /** Shows skeleton placeholders while `options`/`selected` are loading. */
+  isLoading?: boolean;
+  /** Distinguishes create vs edit for existing data-fs-bp-* test-id conventions. */
+  mode: "create" | "edit";
+}
+```
+
+### Integration Points
+
+| Integration point | Current state | Expected change |
+|---|---|---|
+| `UserFormFields` | Renders `rolesOptions.map(...)` as `CheckboxField` rows, non-global id regex | Renders `<RolesMultiSelect options={rolesOptions} selected={form.roles} onChange={...} />` |
+| `CreateUserDrawer` (legacy) | Inlines its own checkbox JSX, non-global id regex | Renders the same `RolesMultiSelect` component |
+| `UpdateUserDrawer` (legacy) | Inlines its own checkbox JSX, non-global id regex | Renders the same `RolesMultiSelect` component |
+| `getRolesAndPermissionsIds` client/service/hook (`RolesClient.ts`, `get-roles-ids.service.ts`, `useGetRolesOptions.ts`) | Returns `RoleData[]` without `isCustom` | No code change required — additive BFF field flows through automatically once the type is updated |
+| `updateRoles` (`useUpdateRoles`, `update-roles.service.ts`) | Sends `{ userId, roles: [{ roleName, isActive }] }` | **Unchanged** — this spec does not touch the assignment payload |
+| `RolesLayout` / `RoleDetailsLayout` | Renders roles map dynamically, correct global-regex slugging already | **Unchanged** by this spec |
+
+### Invariants & Constraints
+
+1. **No client-side role filtering**: the role list rendered in the selector must be exactly what `getRolesAndPermissionsIds` returns — no name-based whitelist, blacklist, or hardcoded set may filter it.
+2. **`isCustom` absence means native**: any code reading `role.isCustom` must treat `undefined` the same as `false`. Never assume the field is always present.
+3. **Minimum one role always selected**: `onChange` must never be called with an empty array through the component's own UI affordances (chip remove, dropdown row click, Backspace) — the last remaining role's removal controls are disabled/non-interactive instead.
+4. **Assignment payload is `roleName`-keyed and unchanged**: `{ userId, roles: [{ roleName, isActive }] }` — this spec introduces no new payload shape; `roleId → roleName` translation happens exactly where it does today, before submit.
+5. **No crash on missing description**: the component must render correctly whether or not a role object carries a description-like field; a future BFF addition of a description must not require this invariant to change.
+6. **id/key generation is collision-safe and space-safe**: any derived DOM id or list key must use a global replace over the full role name (not a first-match-only replace), so names with multiple spaces or special characters never collide or contain literal illegal characters.
+7. **This spec makes no BFF/contract changes**: all endpoint behavior described here (the additive `isCustom` field, more list items) is assumed already delivered by Epic B2BTEAM-3385 / PR `#303`; this repo only consumes it.

package/src/features/roles/types/RolesData.ts

@@ -17,4 +17,5 @@ export interface UpdateUserRoles {
 export interface RoleData {
   roleName: string;
   roleId: number;
+  isCustom?: boolean;
 }

package/src/features/shared/components/AutocompleteDropdown/AutocompleteDropdown.tsx

@@ -15,6 +15,7 @@ import { Icon } from "../Icon";
 import { InputText } from "../InputText/InputText";
 
 import { AutocompleteDropdownItem } from "./AutocompleteDropdownItem";
+import { useDropdownFlipPosition } from "./useDropdownFlipPosition";
 
 export type AutocompleteDropdownContextProps = {
   focusedItemIndex: number;
@@ -70,7 +71,6 @@ export const AutocompleteDropdown = <T,>({
   const [isOpened, setIsOpened] = useState(false);
 
   const [focusedItemIndex, setFocusedItemIndex] = useState(0);
-  const [position, setPosition] = useState<"top" | "bottom">("bottom");
 
   const autocompleteMenuRef = useRef<HTMLDivElement>(null);
   const wrapperAutocompleteRef = useRef<HTMLDivElement>(null);
@@ -79,6 +79,11 @@ export const AutocompleteDropdown = <T,>({
     isOpened,
     wrapperAutocompleteRef
   );
+  const position = useDropdownFlipPosition(
+    isOpened,
+    wrapperAutocompleteRef,
+    autocompleteMenuRef
+  );
   const handleClick = () => {
     if (!disabled && !shouldCloseOnSelect) {
       setIsOpened((old) => !old);
@@ -194,26 +199,6 @@ export const AutocompleteDropdown = <T,>({
     }
   }, [value]);
 
-  useEffect(() => {
-    if (
-      !isOpened ||
-      !autocompleteMenuRef.current ||
-      !wrapperAutocompleteRef.current
-    ) {
-      return;
-    }
-
-    const { bottom, top } =
-      wrapperAutocompleteRef.current.getBoundingClientRect();
-    const dropdownHeight = autocompleteMenuRef.current.offsetHeight + 4; // --fs-spacing-0: 4px
-
-    const spaceBelow = window.innerHeight - bottom;
-
-    setPosition(
-      spaceBelow < dropdownHeight && top > dropdownHeight ? "top" : "bottom"
-    );
-  }, [isOpened]);
-
   return (
     <AutocompleteDropdownContext.Provider
       value={{

package/src/features/shared/components/AutocompleteDropdown/useDropdownFlipPosition.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState, type RefObject } from "react";
+
+/**
+ * Decides whether a dropdown menu should open below ("bottom") or above
+ * ("top") its trigger, based on available viewport space. Shared by
+ * AutocompleteDropdown and RolesMultiSelect so the flip calculation isn't
+ * duplicated between them.
+ */
+export const useDropdownFlipPosition = (
+  isOpen: boolean,
+  triggerRef: RefObject<HTMLElement>,
+  menuRef: RefObject<HTMLElement>,
+  deps: unknown[] = []
+): "top" | "bottom" => {
+  const [position, setPosition] = useState<"top" | "bottom">("bottom");
+
+  useEffect(() => {
+    if (!isOpen || !menuRef.current || !triggerRef.current) return;
+
+    const { bottom, top } = triggerRef.current.getBoundingClientRect();
+    const dropdownHeight = menuRef.current.offsetHeight + 4; // --fs-spacing-0: 4px
+    const spaceBelow = window.innerHeight - bottom;
+
+    setPosition(
+      spaceBelow < dropdownHeight && top > dropdownHeight ? "top" : "bottom"
+    );
+    // triggerRef/menuRef are stable refs; isOpen plus caller-supplied deps
+    // (e.g. filtered item count) are what should trigger a recompute.
+  }, [isOpen, ...deps]);
+
+  return position;
+};

package/src/features/shared/components/index.ts

@@ -9,6 +9,7 @@ export {
   type AutocompleteDropdownProps,
 } from "./AutocompleteDropdown/AutocompleteDropdown";
 export { useAutocompletePosition } from "./AutocompleteDropdown/useAutocompletePosition";
+export { useDropdownFlipPosition } from "./AutocompleteDropdown/useDropdownFlipPosition";
 export { BasicCard, type BasicCardProps } from "./BasicCard/BasicCard";
 export { BasicDrawer, type BasicDrawerProps } from "./BasicDrawer/BasicDrawer";
 export {

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

@@ -22,4 +22,4 @@ export const SCOPE_KEYS = {
   CREDIT_CARDS: "creditCards",
 } as const;
 
-export const CURRENT_VERSION = "2.0.15";
+export const CURRENT_VERSION = "2.0.16";

package/src/features/users/components/CreateUserDrawer/CreateUserDrawer.tsx

@@ -23,6 +23,7 @@ import {
   normalizePhoneNumber,
 } from "../../../shared/utils/phoneNumber";
 import { useAddUserToOrgUnit } from "../../hooks";
+import { RolesMultiSelect } from "../RolesMultiSelect/RolesMultiSelect";
 
 export type CreateUserDrawerProps = Omit<BasicDrawerProps, "children"> & {
   onCreate?: () => void;
@@ -287,37 +288,12 @@ export const CreateUserDrawer = ({
                 />
 
                 <div data-fs-bp-create-user-roles>
-                  <span data-fs-bp-create-user-roles-label>
-                    {t("users.forms.roles")}
-                  </span>
-
-                  {rolesOptions &&
-                    rolesOptions.map((role) => {
-                      const id = `role-${role.roleName
-                        .toLowerCase()
-                        .replace(" ", "-")}`;
-                      return (
-                        <span
-                          data-fs-bp-create-user-role-wrapper
-                          key={role.roleName}
-                        >
-                          <input
-                            type="checkbox"
-                            key={role.roleName}
-                            value={role.roleName}
-                            id={id}
-                            checked={roles?.includes(role.roleId)}
-                            onChange={(event) => {
-                              const newRoles = event.target.checked
-                                ? [...(roles ?? []), role.roleId]
-                                : roles?.filter((r) => r !== role.roleId) ?? [];
-                              updateField("roles", newRoles);
-                            }}
-                          />
-                          <label htmlFor={id}>{role.roleName}</label>
-                        </span>
-                      );
-                    })}
+                  <RolesMultiSelect
+                    mode="create"
+                    options={rolesOptions}
+                    selected={roles ?? []}
+                    onChange={(newRoles) => updateField("roles", newRoles)}
+                  />
                 </div>
               </>
             )}

package/src/features/users/components/CreateUserDrawer/create-user-drawer.scss

@@ -3,7 +3,7 @@
 [data-fs-bp-create-user-drawer] {
   @import "../../../shared/components/InputText/input-text.scss";
   @import "../../../shared/components/ErrorMessage/error-message.scss";
-  @import "@faststore/ui/src/components/molecules/CheckboxField/styles.scss";
+  @import "../RolesMultiSelect/roles-multi-select.scss";
 
   [data-fs-bp-create-user-drawer-back-icon] {
     vertical-align: middle;
@@ -13,29 +13,8 @@
   }
 
   [data-fs-bp-create-user-roles] {
-    display: flex;
-    flex-direction: column;
-    gap: var(--fs-spacing-2);
     margin-bottom: var(--fs-spacing-6);
     margin-top: var(--fs-spacing-5);
-
-    [data-fs-bp-create-user-roles-label] {
-      font-weight: var(--fs-text-weight-regular);
-      font-size: var(--fs-text-size-1);
-      line-height: var(--fs-text-size-3);
-    }
-
-    [data-fs-bp-create-user-role-wrapper] {
-      input {
-        margin-right: var(--fs-spacing-1);
-      }
-
-      label {
-        font-weight: var(--fs-text-weight-regular);
-        font-size: var(--fs-text-size-1);
-        line-height: var(--fs-text-size-3);
-      }
-    }
   }
 
   [data-fs-bp-roles-error-container] {