shoc-frontend-new/tmp/pr-descriptions/pr9-comment-mentions.md

# PR9 — Work order comment @mentions

## Jira

- [SH-217](https://luby-us.atlassian.net/browse/SH-217) — FE @mention autocomplete / chips
- Related BE: [SH-75](https://luby-us.atlassian.net/browse/SH-75)

## QA residual

- Parcial / Blocked-BE for notification + structured `mentions[]` confirm; token chip polish = P1.

## Summary

- Adds `@` autocomplete to the internal comments composer on work order detail (`/workorders/:id`).
- Encodes selected users as `@[userId:Display Name]` tokens in comment text so mentions stay readable when the backend ignores the optional payload field.
- Sends `mentions: string[]` on `POST workorders/{id}/comments` when the composer contains encoded tokens.
- Highlights mentions in the comment thread using encoded tokens and/or `mentions` returned by the API.

## Out of scope

- Notification Center deep-linking for mention events.
- Backend notification triggers beyond the FE payload.

## BE contract

See `docs/work-orders/pending-be-contract.md` (Comments section):

| Field                                    | Status   |
| ---------------------------------------- | -------- |
| POST `{ text, mentions?: string[] }`     | FE ready |
| Response includes mentions for highlight | FE ready |

Until BE confirms, encoded tokens in `text` preserve highlight behavior client-side.

## Test plan

- [ ] Open a work order detail → Internal tab → type `@` and pick a dispatcher from the list.
- [ ] Submit comment; verify POST body includes `text` with encoded token and `mentions` array.
- [ ] Reload detail; verify mention is highlighted in the thread (token and/or API `mentions`).
- [ ] Type `@` mid-word (e.g. email) — autocomplete should not open.
- [ ] Run `npm run verify`.
feat(work-orders): comment @mentions autocomplete (SH-217) (#91) * docs(work-orders): add pending BE contract checklist for design parity gaps * feat(work-orders): add mentions in work-order comments composer * docs(work-orders): align pr description with jira and qa residuals * refactor(workorders): split work order view page into view components * fix(work-orders): export comment assignment vendor input types for view hook * fix(work-orders): drop preferredContact from vendor update payload Align with WorkOrderVendorUpdatePayload on current dev so the mentions branch typechecks. * fix(work-orders): remove Preferred Contact from WO vendor editor (SH-180) EOF * fix(work-orders): harden comment mentions and clear draft on success * fix(work-orders): harden mention highlight boundary and submit catch [SH-217] * fix(work-orders): keep mention cursor sync on current value [SH-217] * fix(work-orders): keep mention menu open after typing @ Pass live text into syncCursor instead of a render-time valueRef. Add a composer interaction regression for @ autocomplete visibility. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Alexandre Brandizzi <alex_brandizzi@hotmail.com> 2026-08-11 14:07:02 -03:00			`# PR9 — Work order comment @mentions`

			`## Jira`

			`- [SH-217](https://luby-us.atlassian.net/browse/SH-217) — FE @mention autocomplete / chips`
			`- Related BE: [SH-75](https://luby-us.atlassian.net/browse/SH-75)`

			`## QA residual`

			- Parcial / Blocked-BE for notification + structured `mentions[]` confirm; token chip polish = P1.

			`## Summary`

			- Adds `@` autocomplete to the internal comments composer on work order detail (`/workorders/:id`).
			- Encodes selected users as `@[userId:Display Name]` tokens in comment text so mentions stay readable when the backend ignores the optional payload field.
			- Sends `mentions: string[]` on `POST workorders/{id}/comments` when the composer contains encoded tokens.
			- Highlights mentions in the comment thread using encoded tokens and/or `mentions` returned by the API.

			`## Out of scope`

			`- Notification Center deep-linking for mention events.`
			`- Backend notification triggers beyond the FE payload.`

			`## BE contract`

			See `docs/work-orders/pending-be-contract.md` (Comments section):

			`\| Field \| Status \|`
			`\| ---------------------------------------- \| -------- \|`
			\| POST `{ text, mentions?: string[] }` \| FE ready \|
			`\| Response includes mentions for highlight \| FE ready \|`

			Until BE confirms, encoded tokens in `text` preserve highlight behavior client-side.

			`## Test plan`

			- [ ] Open a work order detail → Internal tab → type `@` and pick a dispatcher from the list.
			- [ ] Submit comment; verify POST body includes `text` with encoded token and `mentions` array.
			- [ ] Reload detail; verify mention is highlighted in the thread (token and/or API `mentions`).
			- [ ] Type `@` mid-word (e.g. email) — autocomplete should not open.
			- [ ] Run `npm run verify`.