@vtex/faststore-plugin-buyer-portal 2.0.5 → 2.0.6

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.6] - 2026-06-26
+
+### Changed
+
+- Refactor Add/Edit User form (unified login): replace username-centric fields with a single `login` field that dynamically adapts UI per type (email/phone/username), remove `generateUsernameSuggestion` email→username transform, update User List to show `login` as primary column, and remove the "User identification" section from `AuthSetupDrawer`
+
 ## [2.0.5] - 2026-06-17
 
 ### Fixed
@@ -702,7 +708,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.5...HEAD
+[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.6...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
@@ -788,6 +794,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [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
+[2.0.6]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.5...v2.0.6
 [2.0.5]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.4...v2.0.5
 [2.0.4]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.3...v2.0.4
 [2.0.3]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.2...v2.0.3

package/package.json

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

package/specs/refactor-add-user-form.md

@@ -0,0 +1,371 @@
+# Refactor Add/Edit User Form — Unified Login
+
+> **Status**: Approved
+> **Created**: 2026-05-22
+> **Implementation PR base branch**: `refactor/add-user-form`
+> **Implementation PR labels**: `skip-changelog`
+
+---
+
+## 1. Business Context
+
+### Problem Statement
+
+The add/edit user form in Org Account (flow `enableAlternativeLogin = true`, components `CreateUserDrawerWithUsername` and `UpdateUserDrawerWithUsername`) treats **Username as the mandatory primary identifier**, which contradicts the current model where any credential type (email, phone, username) can be the user's login.
+
+There is also an active bug: when an email address is typed in the "Email" field, a `useEffect` extracts the local-part (everything before `@`) and automatically fills the "Username" field with that value — with no visual indication to the admin. The persisted value is therefore different from what the administrator typed or intended to use as the identifier, causing confusion and potentially breaking access for the registered user.
+
+Other problems stemming from the current model:
+
+- The "User identification" section in `AuthSetupDrawer` shows toggles for Username/Email/Phone, but "Username" is always locked as required — semantically inconsistent with the new unified Login reality.
+- The User List displays "Username" as the primary column and search operates on the `name` field in the backend, not on the user's login identifier.
+- UI fields and behaviours (e.g. "username suggestions", async username uniqueness validation) no longer make sense with the unified Login model.
+
+### Goals
+
+1. Make **Login** the only required field in the add/edit user form; Full Name becomes optional.
+2. Implement **dynamic UI behaviour** based on the detected login type (email / phone / username) without persisting that inference.
+3. Eliminate the **automatic email → username transformation** and any other implicit transformation of the typed value.
+4. Preserve the **exact value typed** in the Login field (no forced lowercase, aggressive trimming, or domain removal).
+5. Update the **User List** to display Login as the primary identifier, with search and sorting operating on that field.
+6. Clean up the **AuthSetupDrawer** by removing the "User identification" section entirely — visual, state, payload field, and type definition.
+
+### User Stories
+
+#### US-1: Create user with email login
+
+- **Story**: As an organisation administrator, I want to register a new user using an email address as login, so that the user can access the portal with their email credentials.
+- **Acceptance Criteria**:
+  - **Given** the "Add User" drawer is open, **when** the admin fills the Login field with a value containing `@` (valid email), **then** the UI displays a "Use this email for transactional notifications" checkbox checked by default.
+  - **Given** the "Use this email for transactional notifications" checkbox is checked, **when** the admin submits the form, **then** the payload sent to the API contains `login = <typed value>` and `transactionalEmail = <same value>`.
+  - **Given** the checkbox is unchecked, **when** the admin does not fill the additional "Transactional Email" field, **then** the submit button remains disabled and an error message is shown in the field.
+  - **Given** the checkbox is unchecked and the "Transactional Email" field was filled with a valid email, **when** the admin submits, **then** the payload contains `login = <typed value>`, `transactionalEmail = <transactional email>`.
+  - **Given** login is email, **when** the UI renders, **then** the "Username" field is **not** displayed.
+  - **Given** login is email, **when** the UI renders, **then** an optional phone field is displayed.
+
+#### US-2: Create user with phone login
+
+- **Story**: As an organisation administrator, I want to register a user using a phone number as login, so that the user can authenticate via SMS/code.
+- **Acceptance Criteria**:
+  - **Given** the Login field contains only digits, `+`, spaces, `(`, `)` or `-` in an E.164-compatible format, **when** the UI detects the type, **then** it classifies as `phone` and displays an optional email field.
+  - **Given** login is phone and no additional email was provided, **when** the UI renders, **then** it displays the warning: _"If no email is provided, only an administrator can recover access (no SMS recovery available)"_.
+  - **Given** login is phone, **when** the UI renders, **then** the optional email field is displayed (not required by default).
+  - **Given** login is phone, **when** the UI renders, **then** the "Additional Phone" field is **not** displayed (login is already the phone).
+
+#### US-3: Create user with username login
+
+- **Story**: As an organisation administrator, I want to register a user with an arbitrary username as login, so that the portal supports identifiers not tied to email or phone.
+- **Acceptance Criteria**:
+  - **Given** the Login field does not contain `@` and does not match the phone pattern, **when** the UI detects the type, **then** it classifies as `username`.
+  - **Given** login is username, **when** the UI renders, **then** it displays an optional email field, an optional phone field, and the recovery warning: _"If no email is provided, only an administrator can recover access (no SMS recovery available)"_.
+  - **Given** login is username, **when** the admin types the value, **then** the value is preserved exactly (no lowercase, no domain removal).
+
+#### US-4: Edit existing user
+
+- **Story**: As an administrator, I want to edit an existing user's data with the same rules as registration, so that the unified Login model is consistent between creation and editing.
+- **Acceptance Criteria**:
+  - **Given** the "Edit User" drawer is open with an existing user's data, **when** Login is displayed, **then** the field is editable and pre-filled with the current value (`login` or legacy `userName` via defensive mapping).
+  - **Given** the admin changes the Login field to a value of a different type (e.g. from email to username), **when** the type changes, **then** the dynamic UI immediately adapts the additional fields displayed.
+  - **Given** the edit form is opened, **when** the current Login is an email, **then** the "Use this email for transactional notifications" checkbox is pre-checked if `transactionalEmail == login`, unchecked otherwise.
+
+#### US-5: List users with Login as primary identifier
+
+- **Story**: As an administrator, I want to see Login as the main column in the user list, so that the identifier with which the user accesses the system is immediately visible.
+- **Acceptance Criteria**:
+  - **Given** the User List is loaded, **when** the table renders, **then** the first column displays the user's `login` field (or `userName` as fallback for legacy records).
+  - **Given** the admin types in the search field, **when** the request is sent to the backend, **then** the search parameter operates on the Login field (`login` parameter confirmed).
+  - **Given** a legacy record without a `login` field in the API response, **when** the User List renders, **then** it displays the `userName` value as fallback without error.
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected result |
+|---|---|---|---|
+| Happy path — email login with default transactional | "Add User" drawer open, flag `enableAlternativeLogin = true` | Fill Login with `joao@empresa.com`, leave checkbox checked, select role, click Add | User created with `login = joao@empresa.com`, `transactionalEmail = joao@empresa.com` |
+| Happy path — email login with different transactional | Drawer open | Fill Login with `joao@empresa.com`, uncheck checkbox, fill Transactional Email with `notif@empresa.com`, select role, click Add | User created with `login = joao@empresa.com`, `transactionalEmail = notif@empresa.com` |
+| Happy path — phone login without email | Drawer open | Fill Login with `+5511999990000`, select role, click Add | User created with `login = +5511999990000`; recovery warning was shown during filling |
+| Happy path — username login | Drawer open | Fill Login with `joao.silva`, select role, click Add | User created with `login = joao.silva`; recovery warning displayed |
+| Error — empty required Login | Drawer open | Click Add without filling Login | Button disabled while Login is empty; error message shown on field touch |
+| Error — invalid Transactional Email | Login is email, checkbox unchecked | Fill Transactional Email with `invalido`, click Add | Invalid format error message; submit blocked |
+| Edge case — type change while typing | Login = `joao@` (incomplete email) | Delete `@`, turning it into `joao` | Type changes to `username`; transactional checkbox disappears; recovery warning appears |
+| Edge case — uppercase value preserved | Drawer open | Fill Login with `JOAO.SILVA` | Value sent to backend is `JOAO.SILVA` (no lowercase) |
+| Edge case — international phone | Drawer open | Fill Login with `+44 20 7946 0958` | Type detected as `phone`; dynamic phone fields displayed |
+| Edge case — legacy user in Edit | Existing user has only `userName` (no `login`) | Open edit drawer | Login field pre-filled with `userName` value; UI functional without error |
+| Edge case — email login, additional Phone field | Login = detected email | UI renders | Optional Phone field visible (email login allows additional phone) |
+| Edge case — phone login, additional Phone field | Login = detected phone | UI renders | Additional Phone field **not** visible (login is already the phone) |
+
+### Functional Requirements
+
+**Fixed fields (always present, in this order):**
+- `Full Name` — free text, optional. Displayed before the Login field.
+- `Login` — required, accepts any non-empty string; dynamic behaviour based on the inferred type.
+
+**Dynamic behaviour — Case A (Login is email):**
+- Display "Use this email for transactional notifications" checkbox (checked by default).
+- If unchecked: display required "Transactional Email" field with format validation.
+- Display optional Phone field.
+- Do not display Username field.
+
+**Dynamic behaviour — Case B (Login is phone):**
+- Display optional Email field.
+- Display warning: _"If no email is provided, only an administrator can recover access (no SMS recovery available)"_.
+- Do not display additional Phone field.
+- The Login field applies a phone mask during typing (e.g. `+1 (555) 123-4567`). The payload sent to the API contains the normalised number: `+` followed by digits only (e.g. `+15551234567`), with no spaces or separators.
+- **Known limitation**: the display mask currently supports the North American format only (`+1 (NXX) NXX-XXXX`). Numbers from other countries are detected and normalised correctly for the payload, but the visual mask may format the country code incorrectly. Multi-country support (i18n) will be implemented in a future task.
+
+**Dynamic behaviour — Case C (Login is username):**
+- Display optional Email field.
+- Display optional Phone field.
+- Display warning: _"If no email is provided, only an administrator can recover access (no SMS recovery available)"_.
+
+**Submission rules:**
+- Submit enabled only when: Login filled + (if unchecked: Transactional Email filled and valid) + at least 1 role selected.
+- Login value sent byte-exact (no UI-layer normalisation), **except when login is of type `phone`**: in that case the payload contains `+` followed by digits only (E.164-like format), removing spaces and separators from the display mask.
+
+**Email → username transformation:**
+- Remove `generateUsernameSuggestion` and the `useEffect` that calls it in `CreateUserDrawerWithUsername`.
+
+**User List:**
+- Primary column changes from `userName` to `login` (with fallback to `userName` for legacy records).
+- Search operates on `login` (parameter confirmed by the backend).
+
+**AuthSetupDrawer:**
+- Remove the "User identification" visual section (Username/Email/Phone checkboxes) and associated state/handlers (`selectedIdentifiers`, `handleIdentifierChange`, username required validation).
+- Remove `userIdentification` from the `OrgUnitSettings` type, from the `PATCH /units/{id}/settings` payload, and from any mock/loading skeleton that previously required the field. The backend no longer requires this field.
+
+### Non-Functional Requirements
+
+- **Reactivity**: the dynamic UI (conditional fields, warnings, checkbox) must re-render synchronously on every keystroke in the Login field, with no debounce.
+- **Accessibility**: warnings and error messages must use `aria-describedby` or `role="alert"` for screen readers. Conditional fields that appear/disappear must keep focus manageable.
+- **i18n readiness**: form strings must be declared as literal constants (no dynamic string concatenation), to ease future extraction to locale files.
+- **Test coverage**: component tests covering the 3 dynamic flows (email / phone / username), the transactional checkbox behaviour, the recovery warnings, and the absence of the email → username transformation. Minimum coverage: Definition of Done scenarios.
+- **No new form library dependency**: keep local `useState` consistent with the current project convention.
+
+### Out of Scope
+
+- Refactoring the legacy `CreateUserDrawer` / `UpdateUserDrawer` flow (flag `enableAlternativeLogin = false`).
+- Real internationalisation of strings (only prepare the structure to ease future translation).
+- Changes to `AuthSetupDrawer` beyond the removal of the "User identification" section.
+- Backend contract changes — this spec documents the expected new payload; backend contract implementation is the responsibility of another team.
+- Removal of the `enableAlternativeLogin` feature flag or the `Selector`.
+- Implementation of async username uniqueness validation (removed along with the field).
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+Rebuild both `CreateUserDrawerWithUsername` and `UpdateUserDrawerWithUsername` drawers keeping local `useState` as the form state mechanism (consistent with the existing project pattern). Login type inference is extracted into a pure utility function `detectLoginType`. The dynamic UI is isolated in small sub-components reusable between create and update.
+
+`CreateUserDrawerSelector` and `UpdateUserDrawerSelector` are not changed — they continue selecting the correct drawer based on the `enableAlternativeLogin` flag.
+
+### Architecture Overview
+
+```mermaid
+flowchart TD
+    Selector[CreateUserDrawerSelector] -->|enableAlternativeLogin=true| Drawer[CreateUserDrawerWithUsername]
+    Drawer --> LoginField[LoginField component]
+    LoginField --> detectLoginType[detectLoginType pure]
+    detectLoginType -->|email| EmailUI[EmailTransactionalSection]
+    detectLoginType -->|phone| RecoveryAlert[Alert WarningCircle warning]
+    detectLoginType -->|username| RecoveryAlert
+    detectLoginType -->|phone| PhoneHidden[no additional Phone]
+    EmailUI --> PhoneOptional[optional Phone]
+    RecoveryAlert --> EmailOptional[optional Email]
+    Drawer --> Submit[Submit handler]
+    Submit --> Payload[payload: login + extras]
+    Payload --> ServiceV2[addUserToOrgUnitV2]
+    ServiceV2 --> APIV2[POST v3/units/orgUnitId/users]
+```
+
+The `UpdateUserDrawerWithUsername` flow is identical, with the difference that fields are pre-filled from the existing user's data (with defensive mapping `login ?? userName`).
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| Three separate forms by login type | Internal simplicity of each form | Poor UX: admin discovers the type only after typing; type change requires reopening the drawer | Rejected |
+| Adopt `react-hook-form` for state and validation management | Less boilerplate, declarative validation | Paradigm shift for the entire project; inflated scope | Rejected — out of scope for this refactoring |
+| Detect login type only at submit time | Simpler implementation | Does not meet the reactive dynamic UI requirement during typing | Rejected |
+| New separate feature flag (e.g. `unifiedLoginForm`) | Gradual rollout without touching the legacy code | Third flag for the same flow; growing complexity | Rejected — replacing `*WithUsername` is sufficient and cleaner |
+
+### Risks & Mitigations
+
+| Risk | Impact | Probability | Mitigation |
+|---|---|---|---|
+| ~~Backend does not yet support `login` field in the payload~~ | ~~High~~ | ~~Medium~~ | `login` field confirmed by the backend for v2 endpoints (create and update). Risk resolved. |
+| Legacy users have no `login` field in the API response | Medium — Login column shows empty in the list | High — all users registered today are legacy | Defensive mapping: `user.login ?? user.userName ?? "-"` in the loader and User List |
+| Removing the "User identification" section in AuthSetupDrawer confuses admins | Low — field was functional but semantically inconsistent | Low | Analytics event recorded; no additional message to the user (silent behaviour, section simply disappears). Backend confirmed to no longer require `userIdentification` in the payload — field removed from type, service and mock. |
+| `detectLoginType` produces false positives on ambiguous strings | Low — only affects dynamic UI, not payload | Low | Conservative threshold: phone regex requires a minimum of 7 digits; `@` always indicates email. Ambiguous cases fall through to `username`. |
+| E2E tests (Cypress) cover only the legacy flow | Medium — no automated coverage for the new flow | High — confirmed by current state | Add component tests (Vitest) for the 3 scenarios as part of this spec's DoD |
+
+### Key Decisions
+
+#### Decision 1: Scope — replace only the `*WithUsername` flow
+
+- **Status**: Accepted
+- **Context**: The repository has two parallel add/edit user flows, controlled by `enableAlternativeLogin`. The legacy flow (`CreateUserDrawer`) treats email as required and will not be changed.
+- **Decision**: Replace the contents of `CreateUserDrawerWithUsername` and `UpdateUserDrawerWithUsername`. The `Selector` and the flag remain intact. The legacy flow is preserved as-is.
+- **Consequences**: Lower risk of regression in the legacy flow. When the flag is eventually disabled, the legacy code can be removed in a separate task.
+
+#### Decision 2: `detectLoginType` as an isolated pure function
+
+- **Status**: Accepted
+- **Context**: Login type inference is used exclusively to control the UI. Mixing it into components makes unit testing and reuse harder.
+- **Decision**: Create `src/features/users/utils/detectLoginType.ts` exporting `detectLoginType(value: string): LoginType`. Logic: presence of `@` → `"email"`; match with E.164-like phone regex (`/^\+?[0-9][0-9\s\-()\u202f.]{5,}$/`) → `"phone"`; fallback → `"username"`. The function is **never** called outside the UI layer.
+- **Consequences**: Testable in isolation (pure function). Does not leak into services, mutation hooks, or the payload.
+
+#### Decision 3: Single `login` field in the API payload
+
+- **Status**: Accepted
+- **Context**: The current v2 backend expects separate `userName`, `email`, `phone` fields. The new model needs a `login` field representing the primary identifier regardless of type.
+- **Decision**: Send `login` as a required field in the payload. The `email` and `phone` fields continue to be sent when filled by the user as additional contact (not derived from login). Include `transactionalEmail` as a separate field when applicable.
+- **Consequences**: Confirmed by the backend. The `addUserToOrgUnitV2` service receives required `login` and optional `transactionalEmail`; the update endpoint accepts `login` as an optional field.
+
+#### Decision 4: "Use this email for transactional notifications" checkbox
+
+- **Status**: Accepted
+- **Context**: When login is an email, it is expected that this email will be used for transactional notifications. But the admin may want to use a different email for notifications.
+- **Decision**: Checkbox checked by default (implies `transactionalEmail = login`). When unchecked, the "Transactional Email" field appears as required. If unchecked and field is empty, submit is blocked.
+- **Consequences**: More explicit UX for a case that was previously opaque. Payload will always include `transactionalEmail` when login is an email.
+
+#### Decision 5: User List — column and search
+
+- **Status**: Accepted
+- **Context**: The User List displays "Username" as the main column. With unified Login, "Login" should be the primary identifier displayed.
+- **Decision**: Change `getTableColumns` in `UsersLayout` to use `nameColumnLabel: "Login"` and `nameColumnKey: "login"`. Render `user.login ?? user.userName ?? "-"` for compatibility with legacy records. API search parameter uses `login` (confirmed by the backend).
+- **Consequences**: Table displays the correct identifier. Legacy records degrade gracefully via fallback.
+
+#### Decision 6: AuthSetupDrawer — complete removal of the "User identification" section
+
+- **Status**: Accepted (revised)
+- **Context**: The "User identification" section has toggles for Username (always required/disabled), Email, and Phone. With unified Login, this section has lost its semantics — any identifier type is accepted. The backend has confirmed it no longer requires the `userIdentification` field in the payload.
+- **Decision**: Remove the section entirely: JSX, `selectedIdentifiers` and `handleIdentifierChange` state/handlers (already done in the visual pass), the `userIdentification` field from `OrgUnitSettings` type, the fixed hardcoded block from `handleConfirmClick`, and any mock/skeleton that referenced the field. The `Identifier` type (dead code left from the original section) is also removed.
+- **Consequences**: Cleaner UI and leaner type surface. No legacy dead fields in the settings payload. Backend contract is maintained because the field is no longer expected by the backend.
+
+#### Decision 7: Edit — Login editable with full dynamic behaviour
+
+- **Status**: Accepted
+- **Context**: In the current flow, Username is readonly in edit if the user already had a username. The new specification requires Login to be editable.
+- **Decision**: Login is always editable in the edit drawer. The dynamic behaviour (conditional fields, checkbox, warnings) is the same as in the create drawer. The initial value is `user.login ?? user.userName`.
+- **Consequences**: Admin can change an existing user's login identifier. This may have authentication implications — the decision to allow or disallow this must be validated with the backend.
+
+### Implementation Plan
+
+The following phases must be implemented in sequence within PRs to the `refactor/add-user-form` branch:
+
+1. **`detectLoginType` utility** — create `src/features/users/utils/detectLoginType.ts` + unit tests covering all types and edge cases.
+2. **Refactor `CreateUserDrawerWithUsername`** — rebuild the create drawer with the new field logic, extracting `LoginField` and `EmailTransactionalSection` as reusable sub-components. The recovery warning is rendered inline via `Alert` with `WarningCircle` icon. Remove `generateUsernameSuggestion` and the associated `useEffect`. Add component tests for the 3 flows.
+3. **Refactor `UpdateUserDrawerWithUsername`** — reuse create sub-components. Implement defensive mapping `login ?? userName` on received data. Add component tests.
+4. **Update User List** — change `UsersLayout` (primary column `login`) and `UsersClient` (search parameter `login` confirmed by the backend).
+5. **Clean up `AuthSetupDrawer`** — remove "User identification" visual section and associated state; ensure fixed payload.
+6. **Regression test** — confirm that the email → username transformation no longer exists anywhere in the code.
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+```typescript
+// New type to represent the login type inference result (UI only)
+export type LoginType = "email" | "phone" | "username";
+
+// Updated UserData (src/features/users/types/UserData.ts)
+export type UserData = {
+  id: string;
+  login: string;        // primary identifier — new field
+  name: string;
+  userName?: string;    // kept for compatibility with legacy records
+  email?: string;
+  phone?: string;
+  transactionalEmail?: string;
+  isActive?: boolean;
+  roles?: string[];
+  orgUnit: {
+    id?: string;
+    name: string;
+  };
+};
+
+// User creation payload (src/features/users/services/add-user-to-org-unit.service.ts)
+export type CreateUserPayload = {
+  orgUnitId: string;
+  login: string;          // required — new field
+  role: number[];         // at least 1
+  name?: string;
+  email?: string;         // only if filled by the admin (never derived from login)
+  phone?: string;         // only if filled by the admin
+  transactionalEmail?: string; // required when login is email
+};
+
+// Update payload (src/features/users/services/update-user.service.ts)
+export type UpdateUserPayload = {
+  orgUnitId: string;
+  userId: string;
+  login?: string;
+  name?: string;
+  email?: string;
+  phone?: string;
+  transactionalEmail?: string;
+  role?: string;
+};
+```
+
+### Interfaces
+
+```typescript
+// src/features/users/utils/detectLoginType.ts
+/**
+ * Infers the login type from the typed value.
+ * Result is used ONLY for UI behaviour — never persisted in the payload.
+ *
+ * Rules:
+ * - Contains "@" → "email"
+ * - Matches E.164-like phone pattern (minimum 7 chars, may have +, spaces, parentheses, hyphens) → "phone"
+ * - Any other value → "username"
+ */
+export function detectLoginType(value: string): LoginType;
+
+// New components (src/features/users/components/)
+// LoginField — login field with label, inline validation and no transformation
+interface LoginFieldProps {
+  value: string;
+  onChange: (value: string) => void;
+  isTouched: boolean;
+  "data-testid"?: string;
+}
+
+// EmailTransactionalSection — displayed when loginType === "email"
+interface EmailTransactionalSectionProps {
+  useLoginAsTransactional: boolean;
+  onCheckboxChange: (checked: boolean) => void;
+  transactionalEmail: string;
+  onTransactionalEmailChange: (value: string) => void;
+  isTouched: boolean;
+}
+
+// Recovery warning — rendered inline via <Alert> with WarningCircle icon
+// (no dedicated component; displayed in UserFormFields when loginType is phone or username)
+```
+
+### Integration Points
+
+| Integration point | Current state | Expected change |
+|---|---|---|
+| `usersClient.addUserToOrgUnitV2` | Receives `{ userName, email?, phone?, name?, role[] }` | Receives `CreateUserPayload` with required `login` (confirmed) |
+| `usersClient.updateUser` | Receives `{ name?, email?, phone?, role?, userName? }` | Receives `UpdateUserPayload` with optional `login?` (confirmed) |
+| `getUsersByOrgUnitIdService` | Returns `UserDataService[]` with `userName` field | Defensive mapping in loader: `login: user.login ?? user.userName`; `transactionalEmail` mapped directly |
+| `UsersClient.getUsersByOrgUnitId` | Search param: `name: search` | Search param: `login: search` (confirmed) |
+| `AuthSetupDrawer → useUpdateOrgUnitSettings` | Sends `userIdentification` based on selected checkboxes | `userIdentification` removed from payload entirely; backend no longer requires the field |
+
+### Invariants & Constraints
+
+1. **Login is never transformed by the UI** (except for phone): for `email` or `username` login types, the payload value is byte-exact with what the user typed — no UI layer should apply `.toLowerCase()`, aggressive `.trim()`, or part removal (e.g. email domain). For the `phone` type, `LoginField` applies a display mask during typing and the payload is normalised to `+` + digits (no spaces or separators), equivalent to E.164 format without length restriction.
+2. **Username is not required**: at no point in the `enableAlternativeLogin = true` flow may a `userName` field be marked as required or block submit when empty.
+3. **Email is never converted to username**: the `generateUsernameSuggestion` function and any `useEffect` that copies part of the email to `userName` must be removed and no equivalent logic may exist.
+4. **`detectLoginType` is UI-exclusive**: the function must not be imported in services, mutation hooks, or any layer that produces API payloads.
+5. **Additional Phone field is invalid when login is phone**: if `detectLoginType(login) === "phone"`, the "Additional Phone" field must not be rendered, and no additional phone value must be sent in the payload.
+6. **`transactionalEmail` required when login is email and checkbox is unchecked**: submit must be blocked if `detectLoginType(login) === "email"` and `useLoginAsTransactional === false` and `transactionalEmail.trim() === ""`.
+7. **Roles required**: at least 1 role must be selected to enable submit (invariant maintained from the current flow).
+8. **Defensive mapping in edit**: when loading a user's data into the edit drawer, the `login` value must be `user.login ?? user.userName ?? ""`. No field may silently be `undefined`.

package/src/features/org-units/components/AuthSetupDrawer/AuthSetupDrawer.tsx

@@ -8,17 +8,12 @@ import {
   BasicDrawer,
   type AuthSettingsFeatureFlags,
   type BasicDrawerProps,
-  ErrorMessage,
   Icon,
 } from "../../../shared/components";
 import { useAnalytics, useBuyerPortal } from "../../../shared/hooks";
 import { CHANGES_TIMEOUT_MESSAGE } from "../../../shared/utils/constants";
 import { useUpdateOrgUnitSettings } from "../../hooks";
-import {
-  AuthenticationMethod,
-  type Identifier,
-  type OrgUnitSettings,
-} from "../../types";
+import { AuthenticationMethod, type OrgUnitSettings } from "../../types";
 
 export type AuthSetupDrawerProps = Omit<BasicDrawerProps, "children"> & {
   id: string;
@@ -27,27 +22,6 @@ export type AuthSetupDrawerProps = Omit<BasicDrawerProps, "children"> & {
   onSuccess?: () => void;
 };
 
-const IDENTIFIERS: Identifier[] = [
-  {
-    id: "userName",
-    name: "Username",
-    disabled: true,
-    defaultChecked: true,
-  },
-  {
-    id: "email",
-    name: "Email",
-    disabled: false,
-    defaultChecked: false,
-  },
-  {
-    id: "phone",
-    name: "Phone",
-    disabled: false,
-    defaultChecked: false,
-  },
-];
-
 type ActiveAuthMethods = Record<AuthenticationMethod, boolean>;
 
 type AuthMethodOption = {
@@ -57,7 +31,7 @@ type AuthMethodOption = {
 };
 
 function getAuthMethodOptions(
-  authSettings?: AuthSettingsFeatureFlags
+  authSettings?: AuthSettingsFeatureFlags | undefined
 ): AuthMethodOption[] {
   const password = authSettings?.password ?? true;
   const sso = authSettings?.sso ?? true;
@@ -89,14 +63,6 @@ function getAuthMethodOptions(
   return options;
 }
 
-const getInitialIdentifiers = (settings: OrgUnitSettings): string[] => {
-  const identifiers: string[] = [];
-  if (settings.userIdentification.userName) identifiers.push("userName");
-  if (settings.userIdentification.email) identifiers.push("email");
-  if (settings.userIdentification.phone) identifiers.push("phone");
-  return identifiers;
-};
-
 const getInitialActiveAuthMethods = (
   settings: OrgUnitSettings
 ): ActiveAuthMethods => {
@@ -144,13 +110,9 @@ export const AuthSetupDrawer = ({
     shouldTrackDefaultTimer: true,
   });
 
-  const [selectedIdentifiers, setSelectedIdentifiers] = useState<string[]>(() =>
-    getInitialIdentifiers(settings)
-  );
   const [activeAuthMethods, setActiveAuthMethods] = useState<ActiveAuthMethods>(
     () => getInitialActiveAuthMethods(settings)
   );
-  const [isTouched, setIsTouched] = useState(false);
 
   const handleSuccess = () => {
     const authMethods = (
@@ -162,7 +124,6 @@ export const AuthSetupDrawer = ({
       org_unit_id: id,
       org_unit_name: name,
       auth_methods: authMethods,
-      identifiers: selectedIdentifiers,
       two_factor_enabled: false,
     });
 
@@ -198,16 +159,6 @@ export const AuthSetupDrawer = ({
       },
     });
 
-  const handleIdentifierChange = (identifierId: string) => {
-    if (identifierId === "userName") return; // Username is always required
-
-    setSelectedIdentifiers((prev) =>
-      prev.includes(identifierId)
-        ? prev.filter((id) => id !== identifierId)
-        : [...prev, identifierId]
-    );
-  };
-
   const handleAuthMethodChange = (method: AuthenticationMethod) => {
     setActiveAuthMethods((prev) => {
       const next = { ...prev, [method]: !prev[method] };
@@ -229,21 +180,7 @@ export const AuthSetupDrawer = ({
   };
 
   const handleConfirmClick = () => {
-    setIsTouched(true);
-
-    if (!selectedIdentifiers.includes("userName")) {
-      return;
-    }
-
-    const emailAllowed = selectedIdentifiers.includes("email");
-    const phoneAllowed = selectedIdentifiers.includes("phone");
-
     const data: OrgUnitSettings = {
-      userIdentification: {
-        userName: true,
-        email: emailAllowed,
-        phone: phoneAllowed,
-      },
       authenticationMethods: {
         method: (
           Object.values(AuthenticationMethod) as AuthenticationMethod[]
@@ -261,49 +198,12 @@ export const AuthSetupDrawer = ({
     });
   };
 
-  const isConfirmButtonEnabled =
-    !isUpdateOrgUnitSettingsLoading && selectedIdentifiers.includes("userName");
+  const isConfirmButtonEnabled = !isUpdateOrgUnitSettingsLoading;
 
   return (
     <BasicDrawer data-fs-bp-auth-setup-drawer close={close} {...props}>
       <BasicDrawer.Heading title="Authentication" onClose={close} />
       <BasicDrawer.Body>
-        <section data-fs-bp-auth-setup-section>
-          <div data-fs-bp-auth-setup-section-header>
-            <h2 data-fs-bp-auth-setup-section-title>User identification</h2>
-          </div>
-          <p data-fs-bp-auth-setup-section-description>
-            Select the identifiers allowed for sign-in
-          </p>
-
-          <div data-fs-bp-auth-setup-identifiers>
-            {IDENTIFIERS.map((identifier) => (
-              <div data-fs-bp-auth-setup-identifier-group-item>
-                <label
-                  key={identifier.id}
-                  data-fs-bp-auth-setup-identifier
-                  data-disabled={identifier.disabled}
-                >
-                  <Checkbox
-                    id={identifier.id}
-                    checked={selectedIdentifiers.includes(identifier.id)}
-                    disabled={identifier.disabled}
-                    onChange={() => handleIdentifierChange(identifier.id)}
-                  />
-                  <span data-fs-bp-auth-setup-identifier-label>
-                    {identifier.name}
-                  </span>
-                </label>
-              </div>
-            ))}
-          </div>
-
-          <ErrorMessage
-            show={isTouched && !selectedIdentifiers.includes("userName")}
-            message="Username is required"
-          />
-        </section>
-
         <section data-fs-bp-auth-setup-section>
           <div data-fs-bp-auth-setup-section-header>
             <h2 data-fs-bp-auth-setup-section-title>Authentication methods</h2>

package/src/features/org-units/types/OrgUnitSettings.ts

@@ -6,11 +6,6 @@ export enum AuthenticationMethod {
 }
 
 export type OrgUnitSettings = {
-  userIdentification: {
-    userName: boolean;
-    email: boolean;
-    phone: boolean;
-  };
   authenticationMethods: {
     method: Array<{
       method: AuthenticationMethod;
@@ -21,10 +16,3 @@ export type OrgUnitSettings = {
     verificationCode: boolean;
   };
 };
-
-export type Identifier = {
-  id: string;
-  name: string;
-  disabled: boolean;
-  defaultChecked?: boolean;
-};

package/src/features/org-units/types/index.ts

@@ -10,4 +10,4 @@ export type {
   OrgUnitSearchResponse,
 } from "./OrgUnitSearch";
 export { AuthenticationMethod } from "./OrgUnitSettings";
-export type { OrgUnitSettings, Identifier } from "./OrgUnitSettings";
+export type { OrgUnitSettings } from "./OrgUnitSettings";

package/src/features/shared/layouts/LoadingTabsLayout/LoadingTabsLayout.tsx

@@ -111,14 +111,14 @@ export const LoadingTabsLayout = ({ children }: LoadingTabsLayoutProps) => {
               },
             },
             settings: {
-              userIdentification: { userName: true, email: true, phone: true },
               authenticationMethods: { method: [] },
               "2FA": { verificationCode: false },
             },
             user: {
+              id: "",
+              login: "",
               name: "",
               roles: [],
-              id: "",
               orgUnit: {
                 id: routeParams.orgUnitId,
                 name: "",