US: Add library team member

[gviedma-aulasneo]

As a Library Admin, I want to add one or more users to a library, so that I can onboard contributors quickly.

Figma: https://www.figma.com/design/q3Knq0BKoVTBbtaxb81n9R/RBAC---Console---Wireframes?node-id=2749-4312&t=71PeX22gyABqxnHu-4

Acceptance criteria

• Placement
  Top right action + New Team Member in the Team Members tab header.

• Access
  Visible and usable only for users with manage team permission.

• Modal
  Users input accepts one or more usernames or emails, comma separated.
  Role selector lists available library roles for this scope.
  Controls: Close, Cancel, Save.

• Behavior
  Save validates each entry, trims spaces, deduplicates within the input.
  If a user exists and is not in the team, add them with the selected role.
  If a user exists and is already in the team without that role, add the role.
  If a user already has that role, do nothing.
  If an entry does not match a user, show an error for that specific entry in the modal, but complete the rest.
  On success, close the modal, refresh the Team Members list, and show a toast.

• States and feedback
  While saving, disable inputs and show a saving state.
  Success toast for multiple entries, "x users added".
  Errors are shown as an error message in the modal, design to be defined.

Notes, out of scope for this card

• Filtering, sorting, and page size are separate stories.

• API and detailed error views are defined in separate cards.

Test Cases

Setup

• Users, Admin A with manage team, Member M without manage team.
• Target library exists.
• Candidate accounts, user.new@example.com not on team, user.member@example.com on team without the target role, user.role@example.com on team with the target role, unknown@example.com does not exist.
• Start on Libraries → Library Team Management → Team Members.

Scenarios

• 1) Action is visible only to users with manage team
  Given: I am logged in as Admin A
  When: I view the Team Members tab header
  Then: I see + New Team Member
  Given: I am logged in as Member M without manage team
  When: I view the Team Members tab header
  Then: I do not see + New Team Member

• 2) Open modal and see required controls
  Given: I am logged in as Admin A
  When: I click + New Team Member
  Then: I see a modal with a Users input for emails or usernames, comma separated, a Role selector, and Close, Cancel, Save controls

• 3) Save is disabled until input and role are provided
  Given: the Add team member modal is open
  When: the Users input is empty or the Role selector is not chosen
  Then: the Save button is disabled

• 4) Add one new user who is not on the team
  Given: the modal is open and a role is selected
  When: I enter user.new@example.com and click Save
  Then: the Save button disables while the request runs
  And: when the request succeeds
  Then: the modal closes, the Team Members list refreshes, and I see a success toast

• 5) Add multiple new users, all valid
  Given: the modal is open and a role is selected
  When: I enter user1@example.com, user2@example.com with extra spaces and click Save
  Then: spaces are trimmed and duplicates are collapsed
  And: when the request succeeds
  Then: the modal closes, the list refreshes, and a success toast reflects multiple additions

• 6) Existing team member without the selected role gets that role
  Given: the modal is open and role Editor is selected
  When: I enter user.member@example.com and click Save
  Then: the Save button disables while the request runs
  And: when the request succeeds
  Then: the modal closes, the list refreshes, and I see a success toast

• 7) Existing team member with the same role results in no change
  Given: the modal is open and role Viewer is selected
  When: I enter user.role@example.com and click Save
  Then: the request completes with no change to roles
  And: the modal may remain open or close according to design, a success toast is not required

• 8) Mixed result, subtract successes and keep failures
  Given: the modal is open and a role is selected
  When: I enter user.new@example.com, unknown@example.com and click Save
  Then: the request completes with a mixed result
  And: the modal stays open
  And: user.new@example.com is removed from the Users input
  And: unknown@example.com remains in the Users input for correction
  And: a single summary toast states how many were added and how many failed

• 9) Validation failure shows toast without Retry
  Given: the modal is open and a role is selected
  When: I enter unknown@example.com and click Save
  Then: a toast appears that says the user was not found, without a Retry button
  And: the modal remains open with the entered value intact

• 10) Transient failure shows toast with Retry, modal stays open
  Given: the modal is open and a role is selected
  When: I click Save and the request fails with a transient error, for example 500 or timeout
  Then: a toast appears with a Retry button
  And: the modal remains open
  And: when I click Retry
  Then: a single retry is sent and the Retry button disables while running

• 11) Trim and deduplicate within the Users input
  Given: the modal is open and a role is selected
  When: I enter user.new@example.com, user.new@example.com with extra spaces and click Save
  Then: only one request is sent for that user
  And: when the request succeeds
  Then: the modal closes and the list refreshes

• 12) Cancel closes the modal without changes
  Given: the modal is open with values in the Users input
  When: I click Cancel
  Then: the modal closes and no changes are made to the Team Members list

[dcoa]

@gviedma-aulasneo I just want to clarify this

If an entry does not match a user, show an error for that specific entry in the modal, but complete the rest.

That means, the modal keeps open display the error for the specific user and displays a toast for the rest of the successful entries?

[gviedma-aulasneo]

@dcoa

https://www.figma.com/design/q3Knq0BKoVTBbtaxb81n9R/RBAC---Console---Wireframes?node-id=3057-7416&t=IJ4YzVVKEKqjVEZA-4

These are the designs for the error handling.

I was expecting to create a new issue based on the designs provided by María de los Ángeles. Are you aligned with the proposal, or do you have a suggestion about this topic?

[gviedma-aulasneo]

@MaferMazu, do you have any questions about the behavior of this section? I'm particularly interested in the error handling when you add lists

[dcoa]

@gviedma-aulasneo I think for the scope of the MVP we are good with the design for the error handle, thank you @maguilarUXUI

[MaferMazu]

@MaferMazu, do you have any questions about the behavior of this section? I'm particularly interested in the error handling when you add lists

It is okay because the API should respond with the correct status code and message, allowing the frontend to display the error correctly.

Reference for the API communication: #16 (comment)

Btw, this US is okay 👍

[dcoa]

Mock data for creating the view

PUT /api/authz/v1/roles/users?scope=libraryId

{
  "users": ["jdoe", "alice@example.com", "mjordan23", "bob@example.com", "unknown_user"],
  "role": "editor"
}

Response 207

{
  "completed": [
    {
      "user": "jdoe",
      "status": "role_added"
    },
    {
      "user": "alice@example.com",
      "status": "already_has_role"
    },
    {
      "user": "mjordan23",
      "status": "added_to_team"
    }
  ],
  "errors": [
    {
      "user": "bob@example.com",
      "error": "user_not_found"
    },
    {
      "user": "unknown_user",
      "error": "user_not_found"
    }
  ]
}

[bmtcril]

@dcoa I'm not sure why we're using the query string for the scope here. I can see it for the GET request, but I don't think it makes sense for PUT.

[dcoa]

@bmtcril thank you for the feedback, should we instead add a key in the request scope or object that indicates what library is targeted?