Files
kandev/docs/specs/gitlab-mr-status-chip/spec.md
T

1297 lines
76 KiB
Markdown

---
status: draft
created: 2026-08-11
owner: tbd
---
# GitLab MR Status Chip
## Why
A task whose work lives on GitHub shows its pull request's CI, review and
automation state as a chip in the chat status bar, so the user sees it without
leaving the conversation. A task whose work lives on GitLab shows nothing
there. GitLab users have to look up at the topbar button, or open the MR detail
panel, to answer "did my pipeline pass". The GitLab merge-request equivalent of
that chip does not exist.
## What
- A task with at least one **open** linked GitLab merge request SHALL render an
`MRStatusChip` in the chat status bar and in the passthrough status row,
beside the existing GitHub and Azure DevOps chips.
- The chip SHALL show, at a glance: a GitLab merge glyph, a status glyph whose
colour matches the MR's existing status colour everywhere else in the product,
an MR count when more than one open MR is linked, and auto-fix / auto-merge
badges when task MR automation is enabled.
- Hovering the chip on a fine-pointer device SHALL open the existing
`MRCIPopover` body (pass rate, pipeline stage groups, approval row, unresolved
discussions, automation controls, merge action, footer). Tapping it on a
coarse-pointer device SHALL open that same body inside a bottom-sheet drawer.
- The chip SHALL derive its status from the one shared GitLab MR status
derivation, not a new private copy. `getMRStatusColor` in
`apps/web/components/gitlab/mr-task-icon.tsx` remains the single source of MR
status colour, and its output for every input SHALL be byte-identical before
and after this feature.
- The chip SHALL NOT own any recurring fetch, polling, cache-warming or
background-sync responsibility. It issues exactly **four** kinds of request,
all of them existing behaviour it inherits rather than invents:
1. the lazy read of the task's MR automation options, on mount;
2. the GitLab connection-status read that `useGitLabAvailable()` performs on
mount, which the chip needs to source `canLink`. This one has a
cross-surface side effect and is stated in full under Sync and freshness;
3. the MR feedback read that `MRCIPopover` already owns, **only while a
disclosure is open** (this is what the popover's `enabled` prop gates; see
API surface);
4. the link and unlink the user explicitly triggers.
Nothing else: no polling, no interval, no warmer, and specifically no
`useWorkspaceMRs`. See Sync and freshness.
- No file under `apps/web/components/github/` changes. `PRStatusChip`'s
rendered output SHALL be identical before and after.
- All chip copy SHALL go through `t()` into
`apps/web/src/locales/en/gitlab.json`, including accessible labels.
## Data model
No new persistent state. The chip reads the existing `TaskMR` rows
(`gitlab_task_mrs`, typed at `apps/web/lib/types/gitlab.ts`) already cached in
the store at `taskMRs.byWorkspaceId[workspaceId][taskId]`, and the existing
`TaskMRAutomationOptions` cached at `taskMRAutomation.byTaskId[taskId]`.
Fields the chip's own status derivation reads, and only these:
| Field | Type | Used for |
|---|---|---|
| `id` | string | React key, unlink target, final selection tiebreak |
| `state` | `open \| closed \| merged \| locked \| string` | terminal filtering, `merged` / `closed` status |
| `pipeline_state` | `"" \| success \| failure \| pending \| string` | `failed` / `ready` / `running` status |
| `approval_state` | `"" \| approved \| pending \| string` | `ready` / `awaiting_approval` status |
| `draft` | boolean | `draft` status |
| `mr_iid` | number | display, `data-mr-iid`, primary selection tiebreak |
| `project_path` | string | secondary selection tiebreak, automation-state lookup |
| `repository_id` | string? | automation-state lookup |
The chip SHALL NOT read `unresolved_discussions` for status. That field is
documented as populated only for automation-subscribed MRs, so using it would
make the chip report a different status for two otherwise identical MRs
depending on whether automation happens to be on. The popover body's own live
discussion fetch continues to render the unresolved count, unchanged.
The chip SHALL NOT read `merge_status` / `detailed_merge_status` for status.
See Out of scope.
Separately from status, the trigger's `data-mr-ready-to-merge` attribute and the
popover's merge button both come from the existing `isMRReadyToMerge`, which
does read `unresolved_discussions` and `detailed_merge_status` by design and
carries its own documented rationale. That helper is reused unchanged; the
restriction above applies to chip status only, and the two must not be
reconciled by editing `isMRReadyToMerge`.
## API surface
No new endpoints, no new store actions, no new WS events.
Consumed, all existing:
- `useTaskMRs(taskId)` (`apps/web/hooks/domains/gitlab/use-task-mr.ts`) for the
linked MR list.
- `useGitLabAvailable()` for whether "link another merge request" is offered.
- `useTaskMRAutomationOptions(taskId)`
(`apps/web/hooks/domains/gitlab/use-task-mr-automation.ts`) for automation
flags and `mr_states`.
- `findMRAutomationStateForMR` / `autoFixRoundForState`
(`apps/web/lib/gitlab/mr-automation.ts`) for round badges.
- `MRCIPopover` (`apps/web/components/gitlab/mr-ci-popover.tsx`) as the popover
and drawer body, reused as-is with no new variant and no signature change.
Its full prop contract is specified below; every prop it declares gets a
named source, because one of them (`enabled`) decides whether the chip
fetches.
- `TaskMRLinkDialog` (`apps/web/components/gitlab/task-mr-link-dialog.tsx`) for
the link flow, with its existing
`{open, onOpenChange, taskId, workspaceId, taskRepositories, repositories}`
signature unchanged.
- `DELETE` task-MR association via `deleteTaskMR` + the `removeTaskMR` store
action, for the unlink control the popover header already renders.
### `MRCIPopover` prop contract
`MRCIPopover`'s declared signature is
`{mr, taskId, enabled, canLink, onOpenDetailPanel?, onLink, onUnlink}`. The chip
supplies every one of them from a named source:
| Prop | Type | Source |
|---|---|---|
| `mr` | `TaskMR` | the **acted-on** MR: the live selected MR while the disclosure is closed, the frozen MR while it is open. Always the live store row for that id, never a snapshot. See Selection and ordering. |
| `taskId` | `string` | the chip's own `taskId` |
| `enabled` | `boolean` | **the chip's own disclosure-open state** (`popoverOpen` for the hover variant, `drawerOpen` for the drawer variant). `false` whenever the disclosure is closed. |
| `canLink` | `boolean` | `useGitLabAvailable()` |
| `onOpenDetailPanel` | `(() => void)?` | **omitted.** See Out of scope; the popover title then renders as static text. |
| `onLink` | `() => void` | opens this chip's own `TaskMRLinkDialog`. See Link and unlink from the chip. |
| `onUnlink` | `() => void` | a zero-argument closure that calls `useUnlinkTaskMR(workspaceId)` with the **acted-on MR's association `id`** captured from the enclosing render. See Link and unlink from the chip. |
**`enabled` is the load-bearing one.** `MRCIPopover` gates its live MR feedback
read on it (`useMRFeedbackGated(mr, enabled)`), which is the only reason the
"only network effect" clause in What can be stated at all. `MRTopbarButton`
passes `enabled={popoverOpen}` and the chip SHALL do the same for its own
disclosure. Passing a constant `true` is specifically forbidden: it would make
every mounted chip fetch MR feedback on mount, for every session view with a
linked open MR, and the What clause would be false.
Note the arity: the component declares `onUnlink: () => void`, not
`onUnlink(associationId)`. The association id is closed over, not passed as an
argument, and which id gets closed over is fixed by the freeze rule rather than
left to the call site.
New exported helpers in `apps/web/components/gitlab/mr-task-icon.tsx` alongside
`getMRStatusColor` (the file the repo already designates as the single source of
GitLab MR status):
```
type MRChipStatus =
| "merged" | "closed" | "failed" | "draft"
| "ready" | "awaiting_approval" | "running" | "neutral"
mrChipStatus(mr: TaskMR): MRChipStatus
selectChipMR(mrs: TaskMR[]): TaskMR | null
aggregateMRChipStatus(mrs: TaskMR[]): MRChipStatus
```
`getMRStatusColor(mr)` SHALL be re-expressed as a lookup from
`mrChipStatus(mr)`, so exactly one priority table exists.
`aggregateMRChipStatus(mrs)` SHALL be defined as the composition
`mrChipStatus(selectChipMR(mrs))`, returning `neutral` when `selectChipMR`
returns null. It is not an independent derivation and SHALL NOT have a tiebreak
rule of its own. This is what makes the trigger internally consistent: the
status the chip reports is, by construction, the status of the MR the chip
identifies and acts on. See Selection and ordering.
One extraction, in `apps/web/hooks/domains/gitlab/use-task-mr.ts` alongside the
other task-MR hooks:
```
useUnlinkTaskMR(workspaceId: string): (associationId: string) => Promise<void>
```
This is the unlink closure that today lives privately inside `MRTopbarButton`
(`deleteTaskMR` -> `removeTaskMR`, error toast using the existing
`gitlab:failedToUnlinkMergeRequest` and `gitlab:theMergeRequestIsStillLinked`
keys), moved verbatim. Both `MRTopbarButton` and the chip SHALL call it, and
`MRTopbarButton`'s observable unlink behaviour SHALL be unchanged. The chip
SHALL NOT re-implement the closure: `apps/web/eslint.config.mjs` forbids
identical functions and 4+ duplicated strings, so a second copy is a lint
failure, not a style preference.
New testids, forming the chip's observable contract:
| testid | Element |
|---|---|
| `mr-status-chip` | the trigger button (both single and multi) |
| `mr-status-chip-drawer` | coarse-pointer drawer content |
| `mr-status-chip-drawer-close` | drawer close button |
| `mr-status-auto-fix-chip` | auto-fix round badge |
| `mr-status-auto-merge-chip` | auto-merge badge |
| `mr-status-glyph` | the status glyph, carrying `data-status` |
Trigger attributes, and which MR each one describes. This distinction is
load-bearing while the disclosure is open; see Selection and ordering.
| Attribute | Value | Which MR |
|---|---|---|
| `data-status` | the `MRChipStatus` | the **live** selected MR, always |
| `data-mr-count` | number of **open** linked MRs | n/a |
| `data-mr-iid` | `mr_iid` | the **acted-on** MR |
| `data-mr-state` | `state` | the **acted-on** MR |
| `data-mr-ready-to-merge` | `"true"` / `"false"` from the existing `isMRReadyToMerge` | the **acted-on** MR |
| `data-selection-frozen` | `"true"` while the disclosure is open, `"false"` otherwise | n/a |
The **acted-on MR** is the live selected MR while the disclosure is closed, and
the frozen MR while it is open. `data-selection-frozen` exists so that the two
regimes are distinguishable from the DOM rather than inferred; without it a test
cannot tell a frozen attribute from a stale one. All three per-MR attributes
switch regime together, so they always describe the same single MR as each
other and as the popover body.
`data-mr-ready-to-merge` is present on the single and the multi trigger alike,
always describing the acted-on MR. This is a deliberate divergence from
`PRStatusChip`, whose multi trigger omits the attribute: GitLab's chip always
has exactly one acted-on MR, because it has no multi-MR surface, so there is
always a well-defined MR for the attribute to describe.
Badge attributes. These sit on `mr-status-auto-fix-chip`, not on the trigger,
and they complete the observable contract — the tables above are the full
attribute inventory and nothing outside them is asserted by an AC:
| Attribute | Element | Value | Which MR |
|---|---|---|---|
| `data-auto-fix-exhausted` | `mr-status-auto-fix-chip` | `"true"` / `"false"`, from `autoFixRoundForState(...).exhausted` | the **badge-selected** MR |
The **badge-selected MR** is a third selection, distinct from both the live and
the frozen selection: it is the most attention-worthy auto-fix round across the
open MRs (exhausted beats non-exhausted, then higher `current`, then the same
`mr_iid` / `project_path` / `id` order — see Selection and ordering). On a
single-MR chip all three coincide. On a multi-MR chip they need not.
## State machine
`mrChipStatus(mr)` is a total function evaluated in this exact priority order,
first match wins. The colour column is what `getMRStatusColor` returns for that
MR today and MUST continue to return.
| # | Status | Condition | Colour | Glyph |
|---|---|---|---|---|
| 1 | `merged` | `state === "merged"` | `text-purple-500` | filled merge glyph |
| 2 | `closed` | `state === "closed"` or `state === "locked"` | `text-muted-foreground` | filled dot |
| 3 | `failed` | `pipeline_state === "failure"` | `text-red-500` | filled circle-X |
| 4 | `draft` | `draft === true` | `text-muted-foreground` | filled dot |
| 5 | `ready` | `approval_state === "approved"` and `pipeline_state === "success"` | `text-emerald-400` | filled circle-check |
| 6 | `awaiting_approval` | `approval_state === "pending"` | `text-sky-400` | clock |
| 7 | `running` | `pipeline_state === "pending"` | `text-yellow-500` | spinner, 3s per rotation |
| 8 | `neutral` | otherwise | `text-muted-foreground` | filled dot |
The ordering is deliberate and load-bearing. Stated exactly, because the
neighbouring rows are easy to get backwards:
- A failed pipeline outranks `draft` (row 3 before row 4), so a draft MR whose
pipeline broke reads `failed`, not `draft`.
- `ready` requires **both** an approved review and a succeeded pipeline (row 5).
- A pending approval outranks a running pipeline (row 6 before row 7). Row 6
carries **no pipeline condition at all**: an MR with
`approval_state: "pending"` and `pipeline_state: "pending"` is
`awaiting_approval`, not `running`.
This is exactly the order `getMRStatusColor` already evaluates, row for row.
The refactor SHALL NOT reorder it, and where this prose and the table above
could be read as disagreeing, the table governs.
### Rank, and why aggregation has no tiebreak of its own
`MR_CHIP_STATUS_RANK` orders the statuses by how much attention they deserve:
| Status | Rank |
|---|---|
| `failed` | 5 |
| `running` | 4 |
| `awaiting_approval` | 3 |
| `ready` | 2 |
| `merged` | 0 |
| `closed` | 0 |
| `draft` | 0 |
| `neutral` | 0 |
Four statuses share rank 0, so **rank alone does not identify a winner**. The
chip therefore never aggregates by rank directly. `aggregateMRChipStatus(mrs)`
is defined as `mrChipStatus(selectChipMR(mrs))` (`neutral` when `selectChipMR`
returns null), and `selectChipMR` breaks every tie by named field. Two
consequences, both intended:
1. There is no rank-tie ambiguity to resolve, because ties are resolved on MRs
by `mr_iid` / `project_path` / `id`, not on statuses.
2. The trigger's `data-status` cannot disagree with its `data-mr-iid` **while
`data-selection-frozen` is `"false"`**: the reported status is read off the
identified MR. This qualifier is load-bearing and is not a hedge. While a
disclosure is open the freeze rule deliberately holds `data-mr-iid` on the
frozen MR while `data-status` keeps tracking the live selection, so the two
may name different MRs for exactly that window. See "Freezing while the
disclosure is open", which governs. A test asserting the invariant SHALL
scope itself to `data-selection-frozen="false"`.
**`aggregateMRStatusColor` is NOT re-expressed and its body SHALL NOT be
touched.** This is a deliberate decision, not an omission:
- Its existing loop (`bestRank = -1`, strict `>` over colour ranks) is
**first-in-input-order wins** on a tie, so `[merged, closed]` returns purple
while `[closed, merged]` returns muted. That array-order dependence is
observable today on the multi-MR kanban badge.
- The chip requires the opposite property: a selection that does not depend on
array order. The two cannot share one implementation without either changing
`aggregateMRStatusColor`'s output for all-terminal lists, or importing array
ordering into the chip.
- Changing that behaviour is re-tuning the GitLab MR colour priority, which this
spec already excludes (see Out of scope). Leaving the function byte-identical
makes the mandated parity scenario a regression guard rather than a coin flip.
`MR_CHIP_STATUS_RANK` and the existing colour-keyed `STATUS_RANK` therefore
remain two separate tables, keyed on different things and serving different
callers. They are not permitted to drift: a test SHALL assert they are
**order-equivalent** under the status-to-colour map from the table above, i.e.
for any two statuses `a` and `b`,
`MR_CHIP_STATUS_RANK[a] < MR_CHIP_STATUS_RANK[b]` if and only if
`STATUS_RANK[colour(a)] < STATUS_RANK[colour(b)]`. The single-derivation
invariant this spec protects is the **priority table** (`mrChipStatus`, which
`getMRStatusColor` now reads from); it was never a claim that one rank table
serves both callers.
## Selection and ordering
The chip renders one MR inside its popover even when several are linked. That
MR is the **selected MR**, `selectChipMR(mrs)`, chosen deterministically:
1. Restrict to open MRs (the chip only renders when at least one exists). If
none are open, return null.
**"Open" means `state === "open"` exactly.** It is a positive equality test,
never "not one of the terminal states". `TaskMR.state` is typed
`open | closed | merged | locked | string`, so the two readings diverge for
`locked` and for any unrecognised string the backend may emit: under the
equality test a locked MR is not selectable and does not count toward
`data-mr-count`, and an unknown state behaves the same way. This matches the
test `aggregateMRStatusColor` and `isMRReadyToMerge` already apply, so all
three agree on what "open" means. A consequence worth stating: rows 1 and 2
of the status table (`merged`, `closed`) are therefore unreachable through
`selectChipMR`, and remain live only for `getMRStatusColor`'s other callers
and for the rank-parity test.
2. Keep those whose `mrChipStatus` has the maximum `MR_CHIP_STATUS_RANK`.
3. Tiebreak, in order, by **`mr_iid` ascending**, then **`project_path`
ascending** (byte-wise, `<`), then **`id` ascending**. `id` is the
association primary key, so the ordering is total and the selection is
unique for any input.
Array position is explicitly NOT the tiebreak. The store's array order comes
from the backend response order and is not a stable, named property. (This rule
governs the chip only. It does not apply to `aggregateMRStatusColor`, which
keeps its existing array-order behaviour untouched; see State machine.)
### Freezing while the disclosure is open
**Selection is frozen while the popover or drawer is open.** The popover carries
destructive and irreversible actions (unlink, merge), and an action target that
swaps under the pointer mid-interaction is a hazard the aggregate status is not
worth.
What is captured is the **association `id` only, never a copy of the `TaskMR`
object.** The popover body renders the live store row for that id on every
render. So while frozen:
- Which MR the popover acts on does not change.
- That MR's own fields DO stay live: a pipeline that goes from pending to failed
while the popover is open updates the body, and `isMRReadyToMerge` and the
merge button are evaluated against current data, never a snapshot taken at
open. Merging or unlinking on stale fields is the failure this rule exists to
prevent, so a value snapshot is specifically forbidden.
- The trigger's `data-mr-iid`, `data-mr-state` and `data-mr-ready-to-merge`
describe the frozen MR, and `data-selection-frozen` is `"true"`.
- The trigger's `data-status` and glyph continue to track the **live** selected
MR, so a change on a different MR is still visible at a glance. This is the
one window in which `data-status` and `data-mr-iid` may describe different
MRs; it is bounded by `data-selection-frozen="true"` and is the deliberate
cost of not swapping the action target.
- **The automation badges do NOT freeze.** `mr-status-auto-fix-chip` (its text
and its `data-auto-fix-exhausted`) and `mr-status-auto-merge-chip` continue to
track the live badge-selected MR, on the same side of the line as `data-status`
and the glyph.
The rule that decides this is what each surface is *for*, not which MR it
happens to name. The freeze exists to stop an **action target** moving under
the pointer: unlink and merge are destructive, so the MR they operate on is
pinned. The badges are **informational** — nothing in the popover acts on the
badge-selected MR, and no control's meaning changes when the badge changes. A
frozen badge would instead hide exactly the event it exists to report: an MR
exhausting its auto-fix rounds while the user has the popover open.
This means a multi-MR chip may briefly show three different MRs at once —
`data-mr-iid` (frozen, acted-on), `data-status` (live selection), and the
badge (live badge-selection). That is accepted and is bounded by
`data-selection-frozen="true"`. It is not a new hazard: none of the three is
an action target except the frozen one, which is the whole point.
If the held `id` leaves the store, or its row stops being open, the popover or
drawer closes. On close the freeze is released and all attributes return to the
live selection in the same render.
DOM ordering inside both status rows SHALL be: `PRStatusChip`, then
`MRStatusChip`, then `AzureDevOpsTaskPullRequestChip`, then the existing
banners and right-hand controls. This matches the topbar's existing
`PRTopbarButton` then `MRTopbarButton` provider order, so a task linked to both
a PR and an MR presents the two providers in the same order in both places.
Both chips render; neither suppresses the other.
How each leg of that ordering is verified differs, and the difference is
deliberate. The `PRStatusChip` -> `MRStatusChip` leg has an AC, because both
elements carry testids. The `MRStatusChip` -> `AzureDevOpsTaskPullRequestChip`
leg has **no AC** and is a source-order requirement checked by reading the two
mount points.
The reason is a choice, not an impossibility, and an earlier draft overstated
it. It is true that the Azure chip exposes no `data-testid` and that adding one
is outside this card's permitted files. It does **not** follow that the leg is
unobservable: the chip renders a link whose `aria-label` is a hardcoded,
untranslated `` `Azure PR ${pullRequestId}: ...` ``, inside rows that do carry
testids, so a role-and-name locator could reach it without touching any Azure
file. This spec still declines to assert on it, for a different and narrower
reason: that label is an implementation detail of a component this card is
forbidden to modify, so an AC built on it could be broken by an unrelated Azure
change that this card's owner would be unable to fix. Coupling our ACs to
another team's untranslated internal string buys less than it costs. See
Scenarios.
The auto-fix round shown on a multi-MR chip is the most attention-worthy round
across the open MRs: an exhausted round beats a non-exhausted one, then a higher
`current` wins, and remaining ties resolve by the same
`mr_iid` / `project_path` / `id` order above.
## Link and unlink from the chip
`MRCIPopover` requires both `onLink` and `onUnlink`. What activating them does
is part of this contract, not an implementation detail.
**`onUnlink`** — a zero-argument closure over the acted-on MR's association `id`,
matching `MRCIPopover`'s declared `onUnlink: () => void`. It calls the extracted
`useUnlinkTaskMR(workspaceId)` described under API surface, passing the id it
closed over. (An earlier draft wrote this heading as `onUnlink(associationId)`,
which is the exact form the prop contract above says is wrong; the prop contract
governs.) Behaviour is the topbar's, unchanged: on success the row leaves the
store; on failure an error toast is shown and the row stays.
**`onLink()`** opens the existing `TaskMRLinkDialog`, which the chip mounts
itself as a sibling of its trigger. Its props come from the same places
`MRTopbarButton` sources them:
| Prop | Source |
|---|---|
| `open` | the chip's own dialog open state, which it owns per mounted instance |
| `onOpenChange` | sets that same state |
| `taskId` | the chip's own `taskId` |
| `workspaceId` | the active workspace |
| `taskRepositories` | `useTaskById(taskId)?.repositories`, defaulting to a module-level shared empty array |
| `repositories` | `state.repositories.itemsByWorkspaceId[workspaceId]`, defaulting to a module-level shared empty array |
Both defaults MUST be module-level constants, not a fresh `[]` per render, or
the dialog re-renders on every parent render. Both props are required and
non-nullable on `TaskMRLinkDialog`, and the workspace bucket can legitimately be
absent before repositories hydrate, so the fallback is reachable rather than
defensive. A dialog opened with an empty `repositories` list is the existing
component's own behaviour and this spec does not change it.
Ordering when the user activates "link another merge request":
1. The chip closes its own disclosure (popover or drawer) first.
2. Then `TaskMRLinkDialog` opens.
Closing first is required, not cosmetic: the drawer variant is itself a
focus-trapping dialog, and opening a second one inside it strands focus. The
dialog's own lifecycle is unchanged, so a successful link adds the association
to the store and the chip re-renders with the new MR in its input; if that MR
outranks the current selection the trigger updates, subject to the freeze rule
only while a disclosure is open, which by step 1 it is not.
Each mounted chip owns its own dialog instance and its own open state, like its
disclosure. Two chips mounted at once therefore have two dialog instances, both
closed until the user activates link on one of them; activating it opens only
that chip's dialog. The dialog is idempotent with respect to which chip opened
it, because both pass the same `taskId` and `workspaceId`.
**The dialog does not outlive its chip.** Because each chip mounts its own
dialog as a sibling of its trigger, a chip that unmounts takes its dialog with
it. So if the task's last open MR is unlinked from another surface, or goes
terminal, while this chip's link dialog is open, the dialog unmounts mid-edit
and any URL the user had typed is lost. That is the accepted behaviour, not an
oversight: the alternative is hoisting the dialog above the chip's own render
gate, which would leave a dialog on screen belonging to a chip that no longer
exists. The window is small (it needs a concurrent change on another surface)
and the user can reopen the dialog from `MRTopbarButton`, which is not gated on
an open MR existing.
## Failure modes
- **Task MR list never hydrated.** `useTaskMRs` returns the shared empty array
and the chip renders nothing. There is no skeleton and no loading state: an
absent chip and a not-yet-fetched chip are indistinguishable by design, which
is the same contract `PRStatusChip` and `MRTaskIcon` already have.
- **Store holds a non-array value for the task** (possible during partial
hydration). The chip guards with `Array.isArray` and renders nothing, matching
`MRTaskIcon` and `PRStatusChip`.
- **No active workspace, or `taskId` is null.** The chip renders nothing.
- **Popover feedback fetch fails.** `useMRFeedback` already resolves with
partial data and an error string; the popover degrades exactly as it does from
the topbar button. The chip's own trigger status is unaffected, because it is
derived from `TaskMR` fields rather than from the feedback response.
- **Unlink fails.** The existing behaviour is preserved: an error toast is
shown and the association stays in the store. A successful unlink removes the
row; if that was the task's last open MR the chip unmounts on the next render.
- **Two surfaces unlink the same association.** The chip and the topbar read the
same store row. Whichever request succeeds first removes the row; the other
surface's request fails and toasts. The end state is identical either way, so
the outcome does not depend on ordering. The chip does not retry.
- **An open MR transitions to merged/closed while its popover is open.** On the
next store update the chip re-evaluates. If the transitioned MR is the frozen
one, the popover or drawer closes; if another open MR remains the trigger
re-selects it, and if none does the chip unmounts. No stale MR is left
rendered either way.
- **The GitLab connection status has not resolved yet.** `useGitLabAvailable()`
returns `false` until the mount-time `fetchGitLabStatus` resolves (and it
actively clears any cached value first — see Sync and freshness). So `canLink`
is `false` on the chip's first render and may become `true` a moment later
**without a remount**. The chip SHALL treat this as ordinary prop change, not
as a terminal "GitLab unavailable" state: it renders normally, and the
popover's link control simply appears when the status resolves. The chip SHALL
NOT cache the first value, gate its own render on it, or show an error. If the
status request fails, `useGitLabStatus` stores `null`, `canLink` stays `false`,
and the popover renders without the link control — the same as a workspace
with GitLab genuinely not configured, which is the existing behaviour of every
other consumer.
- **The automation-options fetch fails.** `useTaskMRAutomationOptions` stores the
error and its lazy effect is gated on `error`, so it does not retry for the
life of the mount. The chip treats this exactly as options-not-loaded: status
glyph renders, no badges, no error text and no retry affordance on the chip
itself. The topbar's `MRAutomationControls` remains the surface that reports
and retries automation errors.
## Sync and freshness (explicit non-responsibility)
GitHub's `PRStatusChip` is load-bearing for refresh. It calls
`usePRFeedbackBackgroundSync`, and `pr-topbar-button.tsx:162` documents the
topbar button relying on the chip being mounted for that warming. GitLab's
refresh does not work that way and this chip SHALL NOT copy the responsibility:
- MR list hydration is a one-shot `useWorkspaceMRs(workspaceId)` fetch whose
"already fetched" guard is a per-hook-instance ref, so each additional call
site issues its own `GET /task-mrs` per workspace. There are already **four**
production call sites, and the chip SHALL NOT become a fifth:
| Call site | Mounted by |
|---|---|
| `components/gitlab/mr-topbar-button.tsx` | the task topbar |
| `components/kanban-board.tsx` | the kanban board |
| `hooks/domains/gitlab/use-mr-key-to-tasks.ts` | `app/gitlab/gitlab-page-client.tsx` |
| `hooks/domains/workspace/use-external-vcs-file-link.ts` | `useExternalVcsFileLinkHydration` in `components/task/task-page-content.tsx`, gated on the task having a GitLab-provider repository |
The chip SHALL NOT call `useWorkspaceMRs`.
- There is no shared MR feedback cache. `useMRFeedback` is a per-instance
reducer with no store slice, so there is nothing for the chip to warm and
nothing the topbar would inherit from it. The chip SHALL NOT add a warmer.
**Two** fetch triggers are genuinely new, and both are accepted rather than
hidden.
**New trigger 1: the automation options.** The chip calls
`useTaskMRAutomationOptions(taskId)` to render its badges, and that hook lazily
issues a `GET` when the store holds no options for the task. Before this feature
those options were fetched only when the topbar dropdown or popover mounted
`MRAutomationControls`; now they are fetched for any session view that has a
linked open MR.
**New trigger 2: the GitLab connection status, which also has a cross-surface
side effect.** The chip calls `useGitLabAvailable()` to source `canLink`. That
helper (`hooks/domains/gitlab/use-task-mr.ts`) wraps `useGitLabStatus()`, whose
effect (`hooks/domains/gitlab/use-gitlab-status.ts`) runs on **every mount** and
unconditionally does `setStatus(workspaceId, null)` and then
`void loadStatus(workspaceId)` -> `fetchGitLabStatus`. Two consequences, both
stated rather than discovered at Build time:
1. **It is a request, not a cache read.** Despite the hook's "store-cached" doc
comment, the guard is per-hook-instance: a populated store does not
short-circuit the effect. Every chip mount issues one `GET`, and two mounted
chips issue two.
2. **It transiently blanks a value other surfaces read.** Because the effect
clears the status to `null` before refetching, every other
`useGitLabAvailable()` consumer — `hooks/use-nav-availability.ts`,
`components/kanban-external-link-availability.ts`,
`components/task/task-session-sidebar-task-linking.ts`, and
`components/app-sidebar/sections/settings/workspaces-group.tsx` — reads
`false` for the duration of the in-flight request. Mounting the chip
therefore has a brief, observable effect on unrelated navigation UI.
This is **accepted, not fixed here.** The chip is not the first consumer to do
it (`MRTopbarButton` already calls `useGitLabAvailable()` on the same task
route), the window is one request long, and the recovery is automatic when the
status resolves. Removing the blanking means changing `useGitLabStatus` for
every caller, which is its own card (see Out of scope). The chip SHALL NOT work
around it with a local cache, a mount-order guard, or a debounce, and SHALL NOT
read the status slice directly to dodge the hook. What the chip owes here is
only that `canLink` is allowed to be `false` on the first render and become
`true` without a remount — see Failure modes.
The popover's MR feedback read is **not** a new trigger in this sense. It is
`MRCIPopover`'s own existing fetch, it stays gated on that component's `enabled`
prop, and the chip passes its disclosure-open state there (see the prop table
under API surface). So it fires when a user opens the chip's popover or drawer,
exactly as it already fires when a user opens the topbar's, and never on mount.
What that does and does not buy across two mounted chips, stated precisely
because the obvious argument is invalid:
- **Guaranteed.** A chip whose disclosure is closed passes `enabled: false` and
issues no feedback read. A chip that is never opened never fetches feedback.
- **NOT guaranteed.** Two chips mounted for one task may each have an open
disclosure at the same time, and then each issues its own feedback read. An
earlier draft argued they "do not double it, because at most one disclosure is
open per chip" — that is a **non-sequitur** and is retracted: per-*chip*
exclusivity gives no cross-*chip* exclusivity, and one open disclosure on each
of two chips is exactly two concurrent `enabled: true`.
**Simultaneous open across two chips IS permitted.** This is a decision, not an
omission. Each mounted chip owns its own disclosure state (see Accessibility)
and this spec adds **no cross-chip coordinator**, no shared "currently open
chip" context, and no global registry. The state is reachable in practice
because the fine-pointer chip opens on **focus** as well as hover: a keyboard
user can focus chip A open and then hover chip B, leaving both open.
Two doubled feedback reads is the accepted cost. The alternative — a global
mutual-exclusion coordinator — would be new shared state that neither mount
point nor `MRTopbarButton` has today, would have to decide which chip loses,
and would make each chip's behaviour depend on what else is mounted. That is a
worse contract than an occasional duplicate idempotent `GET`. `useMRFeedback` is
per-instance with no store slice, so two concurrent reads cannot corrupt each
other; they resolve independently into their own popovers.
The dedupe this buys, stated precisely rather than optimistically:
- **Guaranteed.** Once options for a task are in the store, any number of
further chip mounts for that task issue **zero** requests. The hook's effect
is gated on `options || loading || error`, and a populated store short-circuits
it on the first render.
- **Guaranteed.** A single chip mount issues at most one request.
- **NOT guaranteed, and not fixed by this card.** Two chips mounted for the same
task in the **same React commit**, with no cached options, may each issue one
request. The hook's guard reads render-captured values, so both effects run
before either re-render observes `loading === true`. This is reachable:
`PassthroughToolbar` has five mount sites and `ChatInputArea` three, several
of them dockview-driven, so nothing structurally prevents two chips for one
task existing at once.
The duplicate is a `GET` with no side effect, and the hook's own request-id
check (`isCurrentAndUnchangedExternally`) means the store converges to one
options object regardless of which response lands last, so the outcome does not
depend on ordering. Adding a shared in-flight guard to
`useTaskMRAutomationOptions` would fix it, but that hook is also used by
`MRAutomationControls` from the topbar, so the change belongs to a card that can
test both callers; it is named in Out of scope. The chip SHALL NOT work around
the gap with a module-level cache of its own.
The same render-captured pattern is present in `useTaskCIAutomationOptions`, so
`PRStatusChip` does not deliver cross-mount dedupe either. Parity with GitHub is
recorded here as an observation, not as evidence that the property holds.
**Hydration ownership, and why this spec pins no outcome for it.** An earlier
draft claimed `MRTopbarButton` was the only mount point for `useWorkspaceMRs`
and derived from that a specific consequence: that an archived task never
hydrates the MR store, so the chip renders nothing there. **Both halves were
wrong** and the claim is retracted. There are four call sites (table above), and
one of them — `useExternalVcsFileLinkHydration` at
`components/task/task-page-content.tsx` — runs on the `/tasks/:id` task page for
any task with a GitLab-provider repository, independently of the topbar and
independently of archived state.
So whether the MR store is hydrated for a given task depends on which surfaces
the session has visited and which route rendered the chip, not on a single
owner. This spec therefore states no archived-task rendering outcome and **no AC
depends on one.** What the chip guarantees is only the conditional already in
Failure modes: if the task's MR list is not hydrated, `useTaskMRs` returns the
shared empty array and the chip renders nothing, exactly as it does for a task
with no MRs. Tests SHALL seed the store rather than rely on any ambient
hydration path, which the E2E decision already requires.
Giving GitLab MR hydration a single provider-level owner is its own card (see
Out of scope). That card is what would make a hydration outcome specifiable;
until it lands, asserting one here would pin a route-history-dependent flake.
## Responsive behaviour
- Disclosure is chosen by pointer precision only, via `useTouchDrawer()`
(`!isFinePointer`): coarse pointer renders the `Drawer` variant, fine pointer
renders the hover `Popover` variant.
- The chip SHALL NOT gate any part of itself on a Tailwind width class
(`sm:`, `md:`, ...). Pairing a width-gated class with the pointer-gated hook
is what leaves 640-767px rendered by neither branch, and the chip has no
width-dependent behaviour to justify the risk.
- The drawer variant carries a translated title, a screen-reader description,
and a close button, and its body scrolls independently.
- **Hover-popover placement is pinned by value**, so two builders cannot diverge
visually while passing every scenario: `align="end"`, `sideOffset={4}`, and a
`w-80` content width — the values `MRTopbarButton` already uses. `side` is
left to Radix's default collision handling, which is what keeps the content on
screen for a chip sitting at the bottom of the viewport; the "bounding box `y`
is greater than or equal to 0" scenario below is the observable consequence of
that and SHALL NOT be satisfied by hard-coding a `side`.
## Accessibility, focus, and duplicate mounts
- The trigger is a `<button type="button">` with `cursor-pointer` and a
translated `aria-label` naming the MR (or the MR count) and its status. The
drawer variant additionally carries `aria-haspopup="dialog"` and
`aria-expanded`.
- **The `aria-label` describes the acted-on MR**, so it follows the same regime
as `data-mr-iid`: the live selected MR while the disclosure is closed, the
frozen MR while it is open. It therefore always agrees with `data-mr-iid` and
always names the MR whose controls the disclosure actually operates on. It
does NOT follow `data-status`'s live tracking, because a label that renamed
the MR under a screen-reader user mid-interaction would describe controls
other than the ones in front of them.
- The fine-pointer hover lifecycle SHALL be the existing
`useHoverPopover({openDelayMs, closeDelayMs, disabled})`
(`apps/web/hooks/domains/github/use-hover-popover.ts` — note it takes a single
options object, not three positional arguments), wired exactly as
`MRTopbarButton` wires it. That wiring is, in full and with nothing omitted —
**thirteen** handlers, not the four-plus-two a reader might assume:
| Element | Event | Handler |
|---|---|---|
| trigger | `onMouseOver` | `onTriggerEnter` |
| trigger | `onMouseEnter` | `onTriggerEnter` |
| trigger | `onMouseMove` | `onTriggerEnter` |
| trigger | `onPointerOver` | `onTriggerEnter` |
| trigger | `onPointerEnter` | `onTriggerEnter` |
| trigger | `onPointerMove` | `onTriggerEnter` |
| trigger | `onFocus` | `onTriggerEnter` |
| trigger | `onMouseLeave` | `onTriggerLeave` |
| trigger | `onPointerLeave` | `onTriggerLeave` |
| trigger | `onBlur` | `onTriggerLeave` |
| content | `onMouseEnter` | `onContentEnter` |
| content | `onMouseMove` | `onContentEnter` |
| content | `onMouseLeave` | `onContentLeave` |
**The redundancy is deliberate and SHALL be reproduced, not tidied.** An
earlier draft of this spec listed only six of these rows while also declaring
the list complete; that was wrong, and a builder who implements six rows ships
a chip that is measurably flakier than the topbar rather than identical to it.
Two of the omitted rows are individually load-bearing:
- **`onMouseMove` on the content.** `use-hover-popover.ts`'s own doc comment
states the reason: "The content also treats mouse-move as 'enter' so a flaky
or missed portal mouseenter can't strand a pending close." This is precisely
the mechanism the "pointer crosses the gap" scenario below depends on.
Without it that scenario does not fail cleanly — it flakes.
- **`onMouseMove` / `onPointerMove` on the trigger.** These re-assert hover for
a pointer that is resting on the trigger without generating a fresh
`mouseenter`, which is the state the closed-trigger click scenario describes.
The remaining aliases (`onMouseOver` / `onPointerOver` / `onPointerEnter`, and
`onPointerLeave`) are defensive duplicates covering browsers and input devices
that dispatch the pointer family but not the mouse family, or vice versa.
`onTriggerEnter` and `onTriggerLeave` are idempotent — they set a boolean ref
and schedule or cancel a timer — so firing them several times for one physical
gesture is harmless by design, and that is what makes the duplication safe.
Because reproducing thirteen rows by hand is exactly the kind of thing that
drifts, the chip SHOULD prefer **exporting and reusing** the existing private
`useMRPopoverInteractions` wrapper (and, if it is convenient, the trigger's
handler-spreading shape) from `mr-topbar-button.tsx` over re-typing the set.
Reuse is the preferred closure of this requirement; hand-copying is permitted
only if every row above is present.
The content handlers are what let the pointer cross the `sideOffset` gap
without closing. `disabled` is `useTouchDrawer()`. `openDelayMs` and
`closeDelayMs` SHALL both be **150**, the values `MRTopbarButton` uses. Those
constants live in a private `useMRPopoverInteractions` wrapper inside
`mr-topbar-button.tsx`, so "wired as the topbar wires it" does not by itself
pin them; they are pinned here by value. The chip MAY either export that
wrapper for reuse or wire `useHoverPopover` directly with the same values.
- **The popover DOES close on blur**, because `onBlur` is wired to
`onTriggerLeave` exactly as the topbar wires it. It also closes on Escape, on
outside interaction (Radix `onOpenChange`), and when the pointer leaves both
the trigger and the content. It opens on keyboard focus of the trigger and
SHALL NOT steal focus when it opens.
This corrects a claim an earlier draft of this spec made. For the record,
because the wrong version is the kind of thing that gets re-derived: it is
true that `useHoverPopover` itself declares no blur handler, but
`MRTopbarButton` wires `onBlur` to the hook's `onTriggerLeave` at the
component level. So wiring blur is what matches the topbar and omitting it is
the divergence. Nor does wiring it re-introduce the portal race:
`onTriggerLeave` does not close anything directly, it calls `scheduleClose`,
which re-checks `overTrigger` and `overContent` at the moment the timer fires
and commits the close only when the pointer is over neither region. That
re-check is precisely the mechanism the hook exists to provide.
Closing on blur does not resurrect the keyboard-operability problem, because
this spec does not claim the popover's controls are Tab-reachable — see the
next bullet, which states the opposite plainly. Focus-to-open makes the
content *readable* by a keyboard user; tabbing away closes it again; the
controls inside it were never Tab-reachable from the trigger in the first
place, so nothing is lost by the close.
- **Scope of the keyboard claim.** Focus-to-open makes the popover's *content
readable* by a keyboard user. It does NOT make the popover's controls
(link, unlink, merge) Tab-reachable: Radix portals the content to the end of
the document and provides no tab bridge from the trigger, so Tab moves past
the chip rather than into it. This spec does not claim otherwise, and does not
fix it. No capability is lost: link and unlink are keyboard-operable today
through `MRTopbarButton`'s click-driven `DropdownMenu`, and on a coarse
pointer the chip's own drawer is a focus-trapping dialog in which every
control is operable. Making `MRCIPopover`'s controls keyboard-reachable from a
hover popover is a pre-existing gap shared with `PRStatusChip` and the topbar,
and is named in Out of scope.
- **Clicking the fine-pointer trigger is a no-op in both states.** While the
popover is open, it stays open and nothing navigates; Radix treats the trigger
as outside the content, so this requires an explicit outside-pointer-down
guard. While the popover is closed, the click also does nothing on its own:
the fine-pointer chip opens on hover and focus only, and there is no
click-to-open path. A user who clicks a closed chip faster than the 150ms
open delay therefore sees the popover open on the hover timer as normal,
because the pointer is still over the trigger; the click neither accelerates
nor suppresses it. This is a deliberate divergence from `MRTopbarButton`,
whose trigger navigates to the MR detail panel on click — the chip has no
detail-panel action at all (see Out of scope), so it has nothing to do with a
click.
- **Closing the drawer returns focus to the trigger when the trigger is still
mounted.** It often will not be: unlinking the task's last open MR from inside
the drawer, or that MR going terminal, unmounts the chip and its trigger in
the same update that closes the drawer. In that case the chip makes no focus
claim and focus falls to `document.body` per browser default. This is a named,
accepted consequence rather than a specified behaviour, it is shared with
`PRStatusChip`, and improving it is listed in Out of scope. No AC asserts a
focus target for the unmounted case.
- The two mount points are alternative surfaces, but nothing guarantees only one
is mounted at a time. Two `mr-status-chip` elements may therefore coexist in
the DOM. Both are correct and identical; E2E selectors SHALL scope to
`chat-status-bar` or `passthrough-status-row` rather than matching the testid
globally, and each mounted chip owns its own disclosure state.
- On a workspace switch the chip does not show the previous workspace's MRs.
**The mechanism is workspace-scoped selection, not a reset of the outgoing
bucket** — an earlier draft of this spec said the opposite and it was wrong.
What actually happens: `useWorkspaceMRs` calls `resetTaskMRs(workspaceId)`
with the **incoming** workspace id (the all-buckets `resetTaskMRs()` runs only
when the workspace goes null), so the outgoing workspace's bucket is left in
the store untouched. The chip reads nothing from it because `useTaskMRs`
selects `byWorkspaceId[activeWorkspaceId]`, and `activeWorkspaceId` is already
the incoming one. The chip therefore unmounts until the incoming workspace's
MRs land.
The correction matters for what it forbids: the chip SHALL NOT add any
outgoing-workspace cleanup of its own, and no AC asserts that the previous
workspace's bucket was cleared.
## Scenarios
Rendering and absence:
- **GIVEN** a task with no linked MRs, **WHEN** its session view renders,
**THEN** no element with testid `mr-status-chip` exists.
- **GIVEN** a task whose only linked MR has `state: "merged"`, **WHEN** its
session view renders, **THEN** no element with testid `mr-status-chip` exists.
- **GIVEN** a task with two linked MRs, both terminal (one `merged`, one
`closed`), **WHEN** its session view renders, **THEN** no element with testid
`mr-status-chip` exists.
- **GIVEN** a task with one open MR and one merged MR, **WHEN** its session view
renders, **THEN** `mr-status-chip` is present with `data-mr-count="1"` and
`data-mr-iid` equal to the open MR's iid.
- **GIVEN** a task with one open MR and no linked PR, **WHEN** the chat status
bar renders, **THEN** `mr-status-chip` is present inside `chat-status-bar`.
- **GIVEN** a task with one open MR, **WHEN** the passthrough toolbar renders,
**THEN** `mr-status-chip` is present inside `passthrough-status-row`.
- **GIVEN** a task linked to **both** an open GitHub PR and an open GitLab MR,
**WHEN** the chat status bar renders, **THEN** both `pr-status-chip` and
`mr-status-chip` are present inside `chat-status-bar`, and `pr-status-chip`
precedes `mr-status-chip` in DOM order.
This is the only ordering assertion. **The Azure DevOps chip is not part of
any assertion**, and the requirement that `MRStatusChip` be rendered *before*
`AzureDevOpsTaskPullRequestChip` (see Selection and ordering) stands as a
source-order requirement on the two mount points, verified by reading the
diff rather than by a test.
That is a deliberate trade, stated honestly rather than dressed up as a
technical limit: the Azure chip has no `data-testid`, and although its
hardcoded `aria-label` would make a role-based locator possible, this spec
declines to build an AC on a string owned by a component this card may not
modify. See Selection and ordering for the full reasoning. A stated
code-review check that everyone can see is better than an AC whose failure
mode is an unrelated team renaming their label.
Status derivation:
- **GIVEN** an open MR with `pipeline_state: "failure"` and `draft: true`,
**WHEN** the chip renders, **THEN** `data-status` is `failed`.
- **GIVEN** an open MR with `draft: true` and `pipeline_state: "pending"`,
**WHEN** the chip renders, **THEN** `data-status` is `draft`.
- **GIVEN** an open MR with `approval_state: "approved"` and `pipeline_state:
"success"`, **WHEN** the chip renders, **THEN** `data-status` is `ready` and
the glyph carries the emerald colour class.
- **GIVEN** an open MR with `approval_state: "pending"` and `pipeline_state:
"success"`, **WHEN** the chip renders, **THEN** `data-status` is
`awaiting_approval`.
- **GIVEN** an open MR with `approval_state: ""` and `pipeline_state: "pending"`,
**WHEN** the chip renders, **THEN** `data-status` is `running`.
- **GIVEN** an open MR with `approval_state: "pending"` and `pipeline_state:
"pending"`, **WHEN** the chip renders, **THEN** `data-status` is
`awaiting_approval`, not `running`, because row 6 carries no pipeline
condition.
- **GIVEN** an open MR with every status field empty, **WHEN** the chip renders,
**THEN** `data-status` is `neutral`.
- **GIVEN** an open MR with `unresolved_discussions: 7` and otherwise `ready`
fields, **WHEN** the chip renders, **THEN** `data-status` is still `ready`,
because unresolved discussions do not feed chip status.
- **GIVEN** any `TaskMR`, **WHEN** `getMRStatusColor` is called before and after
the refactor, **THEN** it returns the identical class string. A table-driven
test SHALL cover every branch of the priority table.
Aggregation and selection:
- **GIVEN** a task with two open MRs, one `running` and one `failed`, **WHEN**
the chip renders, **THEN** `data-status` is `failed`, `data-mr-count` is `2`,
and `data-mr-iid` is the failed MR's iid.
- **GIVEN** a task with two open MRs that are both `failed`, with iids 12 and 7,
**WHEN** the chip renders, **THEN** `data-mr-iid` is `7`.
- **GIVEN** a task with two open MRs that are both `failed`, sharing iid 7
across projects `group/a` and `group/b`, **WHEN** the chip renders, **THEN**
the selected MR is the one in `group/a`.
- **GIVEN** a task with three open MRs whose backend response order is reversed
between two renders, **WHEN** the chip renders each time, **THEN**
`data-mr-iid` is identical both times.
- **GIVEN** a task with two open MRs at rank 0 with different statuses, one
`draft` with iid 9 and one `neutral` with iid 3, **WHEN** the chip renders,
**THEN** `data-mr-iid` is `3` and `data-status` is `neutral` (the status of
the MR the tiebreak selected), for either input array order.
- **GIVEN** any list of MRs, **WHEN** `aggregateMRChipStatus(mrs)` is called,
**THEN** its result equals `mrChipStatus(selectChipMR(mrs))`, or `neutral`
when `selectChipMR(mrs)` is null. A property test SHALL assert this over
shuffled input orders.
- **GIVEN** any two `MRChipStatus` values `a` and `b`, **THEN**
`MR_CHIP_STATUS_RANK[a] < MR_CHIP_STATUS_RANK[b]` if and only if
`STATUS_RANK[colour(a)] < STATUS_RANK[colour(b)]`, asserted by a table-driven
test over all 8 statuses.
- **GIVEN** any list of MRs, **WHEN** `aggregateMRStatusColor` is called before
and after this change, **THEN** it returns the identical class string. This
includes all-terminal lists, where its existing first-in-input-order tie
behaviour is preserved: `[merged, closed]` returns `text-purple-500` and
`[closed, merged]` returns `text-muted-foreground`, both before and after.
Disclosure:
- **GIVEN** a fine-pointer viewport and a task with one open MR, **WHEN** the
user hovers `mr-status-chip`, **THEN** `mr-topbar-popover-inner` becomes
visible and its bounding box `y` is greater than or equal to 0.
- **GIVEN** that popover is open, **WHEN** the pointer crosses the gap between
trigger and content, **THEN** the popover stays open.
- **GIVEN** that popover is open, **WHEN** the user clicks the chip itself,
**THEN** the popover stays open and no navigation occurs.
- **GIVEN** a coarse-pointer viewport and a task with one open MR, **WHEN** the
user taps `mr-status-chip`, **THEN** `mr-status-chip-drawer` becomes visible
and contains `mr-topbar-popover-inner`.
- **GIVEN** the drawer is open, **WHEN** the user activates
`mr-status-chip-drawer-close`, **THEN** the drawer closes and focus returns to
the chip trigger.
- **GIVEN** a coarse-pointer viewport, **WHEN** the chip renders, **THEN** no
hover popover is mounted.
- **GIVEN** a fine-pointer viewport, **WHEN** the user moves keyboard focus onto
the chip trigger, **THEN** the popover opens and focus stays on the trigger.
- **GIVEN** the popover was opened by keyboard focus, **WHEN** focus moves off
the trigger without any pointer entering the trigger or the content, **THEN**
the popover closes, because `onBlur` is wired to `onTriggerLeave` and the
scheduled close finds the pointer over neither region.
- **GIVEN** the popover was opened by keyboard focus and the pointer is then
moved onto the popover content, **WHEN** focus moves off the trigger, **THEN**
the popover stays open, because the scheduled close re-checks both hover
regions at fire time and the pointer is over the content.
- **GIVEN** a fine-pointer viewport and a task with one open MR, **WHEN** the
user clicks the chip trigger while its popover is closed, **THEN** no
navigation occurs and no panel opens; the popover opens only when the 150ms
hover-open delay elapses with the pointer still over the trigger.
- **GIVEN** a fine-pointer viewport and a task with one open MR, **WHEN** the
viewport width is any value from 320px to 1920px, **THEN** exactly one
disclosure branch renders and the chip is never blank. No width between
breakpoints leaves it rendered by neither branch.
Popover content and actions:
- **GIVEN** an open MR with 6 of 10 pipeline jobs passing, **WHEN** its chip
popover opens, **THEN** the pass-rate row reads `6/10 (60%)`.
- **GIVEN** an open MR whose pipeline has not started (`pipeline_jobs_total: 0`
and no fetched jobs), **WHEN** its chip popover opens, **THEN**
`mr-pipeline-empty` is rendered.
- **GIVEN** an open MR and a workspace with GitLab authenticated **whose status
request has already resolved**, **WHEN** its chip popover opens, **THEN**
`mr-popover-link-another` is rendered. (The pre-resolution window is a
separate AC below; the qualifier is what keeps the two from disagreeing.)
- **GIVEN** an open MR and a workspace with GitLab not configured, **WHEN** its
chip popover opens, **THEN** `mr-popover-link-another` is not rendered.
- **GIVEN** an open MR and a workspace with GitLab authenticated, **WHEN** the
chip mounts and its popover is opened before the mount-time GitLab status
request resolves, **THEN** `mr-popover-link-another` is absent at first and
appears once the status resolves, without the chip unmounting or remounting
and without any error being shown.
- **GIVEN** a task with exactly one open MR, **WHEN** the user unlinks it from
the chip popover and the request succeeds, **THEN** the association is removed
from the store and `mr-status-chip` unmounts.
- **GIVEN** the unlink request fails, **WHEN** the user unlinks from the chip
popover, **THEN** an error toast is shown and `mr-status-chip` remains.
- **GIVEN** an MR that satisfies `isMRReadyToMerge`, **WHEN** its chip popover
opens, **THEN** `mr-merge-button` is rendered and `data-mr-ready-to-merge` on
the trigger is `"true"`.
- **GIVEN** a task with two open MRs, **WHEN** the multi chip renders, **THEN**
`data-mr-ready-to-merge` is present on the trigger and equals
`isMRReadyToMerge(acted-on MR)`.
- **GIVEN** a fine-pointer viewport and an open chip popover, **WHEN** the user
activates `mr-popover-link-another`, **THEN** the popover closes and the
task-MR link dialog opens.
- **GIVEN** a coarse-pointer viewport and an open chip drawer, **WHEN** the user
activates `mr-popover-link-another`, **THEN** `mr-status-chip-drawer` is no
longer visible and the task-MR link dialog is open, so the two dialogs are
never nested.
- **GIVEN** the link dialog opened from the chip, **WHEN** the user links a
second open MR that outranks the current selection, **THEN** the dialog
closes, the new association is in the store, and the trigger's
`data-mr-count` and `data-mr-iid` update to include and name it.
- **GIVEN** two independent fixtures of the same task and association — one
where the user unlinks from the chip popover, one where the user unlinks from
`MRTopbarButton` — **WHEN** the request succeeds in each, **THEN** both remove
the same association from the store and neither toasts.
- **GIVEN** those same two independent fixtures, **WHEN** the request fails in
each, **THEN** both show the error toast built from
`gitlab:failedToUnlinkMergeRequest` and
`gitlab:theMergeRequestIsStillLinked`, and both leave the association in the
store.
These are two separate fixtures, not a sequence: the second unlink of one
association would fail for a different reason (the row is already gone) and
would test nothing about parity. Parity holds by construction because both
surfaces call the one extracted `useUnlinkTaskMR` and no second copy of that
closure exists; these ACs pin that the extraction actually happened.
Automation badges:
- **GIVEN** task MR automation with `auto_fix_enabled: false` and
`auto_merge_enabled: false`, **WHEN** the chip renders, **THEN** neither
`mr-status-auto-fix-chip` nor `mr-status-auto-merge-chip` is rendered.
- **GIVEN** `auto_fix_enabled: true`, `auto_fix_max_rounds: 5`, and a lifecycle
state for the selected MR with `auto_fix_round_count: 2`, **WHEN** the chip
renders, **THEN** `mr-status-auto-fix-chip` reads `2/5`.
- **GIVEN** `auto_fix_enabled: true`, `auto_fix_max_rounds: 5`, and **no
lifecycle state at all for the selected MR** (`findMRAutomationStateForMR`
returns `undefined`), **WHEN** the chip renders, **THEN**
`mr-status-auto-fix-chip` IS rendered and reads `0/5`, and carries
`data-auto-fix-exhausted="false"`.
This is the ordinary steady state of an enabled MR that has not needed a fix
yet, so it is the badge's most common appearance and it is pinned rather than
left to inference. The value follows from `autoFixRoundForState`, which is
total: given `undefined` it returns `{current: 0, max, exhausted: false}`.
Hiding the badge until round >= 1 is specifically NOT the behaviour — the badge
communicates that auto-fix is on, which is true at round 0.
- **GIVEN** `auto_fix_enabled: true` and a lifecycle state with
`auto_fix_exhausted_at` set, **WHEN** the chip renders, **THEN**
`mr-status-auto-fix-chip` carries `data-auto-fix-exhausted="true"`.
- **GIVEN** `auto_fix_enabled: true` and `auto_fix_max_rounds` absent or not a
finite number, **WHEN** the chip renders, **THEN** the badge's denominator is
`10`.
- **GIVEN** two open MRs where one is exhausted at round 3 of 5 and the other is
at round 4 of 5, **WHEN** the multi chip renders, **THEN** the badge shows the
exhausted MR's `3/5`.
- **GIVEN** two open MRs whose auto-fix rounds are **fully tied** — neither
exhausted, both at round 2 of 5 — with iids 12 and 7, **WHEN** the multi chip
renders, **THEN** the badge is the one belonging to iid `7`, resolved by the
same `mr_iid` / `project_path` / `id` order that `selectChipMR` uses. This
pins the tiebreak leg of the round-aggregation rule, which the exhausted-beats-
non-exhausted and higher-`current`-wins legs above do not reach.
- **GIVEN** `auto_merge_enabled: true`, **WHEN** the chip renders, **THEN**
`mr-status-auto-merge-chip` is rendered.
- **GIVEN** automation options have not loaded, **WHEN** the chip renders,
**THEN** the chip still renders its status glyph and no badges.
Idempotency and re-render:
- **GIVEN** unchanged store state, **WHEN** the chip re-renders any number of
times, **THEN** its rendered output and `data-*` attributes are identical.
- **GIVEN** the task's MR automation options are already in the store, **WHEN**
the chip mounts, **THEN** no request is issued.
- **GIVEN** the task's MR automation options are absent from the store, **WHEN**
a single chip mounts, **THEN** exactly one options request is issued for that
task.
- **GIVEN** the task's MR automation options are absent from the store, **WHEN**
two chips for the same task mount in the same React commit, **THEN** each may
issue one request, and once both settle the store holds exactly one options
object for that task and both chips render identical badges. Cross-mount
request dedupe is explicitly NOT asserted; see Sync and freshness.
- **GIVEN** the chip is mounted, **WHEN** no user action occurs, **THEN** it
issues no further request: it neither polls nor re-fetches on an interval.
- **GIVEN** the chip's popover is open on a task with two open MRs, **WHEN** a
store update makes the other MR the higher-ranked one, **THEN** the popover
keeps showing the MR it opened with, the trigger's `data-mr-iid` still names
that MR, `data-selection-frozen` is `"true"`, and the trigger's `data-status`
updates to the new live selection's status.
- **GIVEN** that same popover, **WHEN** the user closes it, **THEN** in the
render after close `data-selection-frozen` is `"false"` and `data-mr-iid`
names the new live selection.
- **GIVEN** the chip's popover is open on an MR whose `pipeline_state` is
`"success"`, with `detailed_merge_status: "mergeable"`,
`unresolved_discussions: 0`, `draft: false` — so `isMRReadyToMerge` is true and
the trigger's `data-mr-ready-to-merge` is `"true"` — **WHEN** a store update
sets that same MR's `pipeline_state` to `"failure"`, **THEN**
`data-mr-ready-to-merge` becomes `"false"` and `mr-merge-button` is no longer
rendered in the open popover.
The transition is chosen so the assertion cannot pass vacuously. A
`pending` -> `failure` transition would leave `isMRReadyToMerge` false on both
sides (it requires `pipeline_state === "success"`), so it proves nothing about
liveness; `success` -> `failure` is the smallest change that actually flips the
observed value.
- **GIVEN** that same popover is open on that MR, **WHEN** the same store update
lands, **THEN** the trigger's `data-status` changes from `ready` to `failed`,
confirming the body and the trigger read the same live row.
- **GIVEN** the chip's popover is open, **WHEN** the MR it is showing is
unlinked from another surface, **THEN** the popover closes.
- **GIVEN** the chip's popover is open, **WHEN** the MR it is showing
transitions to `merged` while another open MR remains, **THEN** the popover
closes and the trigger re-selects the remaining open MR.
- **GIVEN** two chips are mounted at once, **WHEN** the user opens one,
**THEN** the other stays closed.
- **GIVEN** two chips are mounted at once for the same task, **WHEN** the user
opens the chat-status-bar chip by keyboard focus and then opens the
passthrough-status-row chip by hover, **THEN** **both** disclosures are open
at the same time, each rendering `mr-topbar-popover-inner`, and neither closes
the other. Simultaneous open is permitted; no cross-chip coordinator exists.
- **GIVEN** those two disclosures are both open, **THEN** each chip issues its
own MR feedback read — two requests for the one task. Cross-chip feedback
dedupe is explicitly NOT asserted; see Sync and freshness.
- **GIVEN** the chip's popover is open on a task with two open MRs, so
`data-selection-frozen` is `"true"`, **WHEN** a store update makes the other
MR the badge-selected one (it becomes exhausted while the frozen MR is not),
**THEN** `mr-status-auto-fix-chip` updates to the newly badge-selected MR's
round and its `data-auto-fix-exhausted` becomes `"true"`, while
`data-mr-iid` still names the frozen MR. The badges do not freeze.
Internationalization:
- **GIVEN** the pseudo-locale is active, **WHEN** the chip and its drawer
render, **THEN** every string this feature adds is pseudo-localized,
including the trigger's `aria-label`, the drawer title, and the drawer's
screen-reader description.
- **GIVEN** the pseudo-locale is active, **WHEN** the chip's popover renders
`MRCIPopover`, **THEN** GitLab-sourced domain data inside it is NOT
pseudo-localized: MR titles, author and reviewer names, `project_path`,
branch names, and pipeline job and stage names render verbatim. Per
`apps/web/CLAUDE.md` these are user/domain data, never UI copy, and this
feature does not change how `MRCIPopover` renders them. The i18n assertion is
scoped to chip-owned copy for exactly this reason.
## Out of scope
Each of these is a deliberate exclusion, not an oversight. Each is its own card.
- **MR conflict / merge-blocked as a distinct chip status.** GitHub's chip has
`conflict` (`mergeable_state: "dirty"`) and `behind` states. GitLab exposes
the equivalent through `detailed_merge_status` / `merge_status`, but
introducing it as a chip status would add a branch to `getMRStatusColor` and
therefore change the kanban card icon and the topbar trigger colour for every
conflicted MR in the product. That is a change to a different surface than
this card's, so `mrChipStatus` deliberately produces no status that alters an
existing colour.
- **Re-tuning the GitLab MR status colour priority.** For example, making a
green pipeline with no approval requirement read green rather than falling to
`neutral`. The chip inherits today's priority table verbatim.
- **A GitLab multi-MR tabbed popover.** GitHub has `MultiPRCIPopover` with
segmented per-PR tabs, backing `PRStatusChipMultiHoverCard` and
`PRStatusChipMultiDrawer`. GitLab has no such component, and
`mr-topbar-button.tsx` already carries this exact exclusion. The multi-MR chip
therefore shows the aggregate status plus a count on the trigger, and exactly
one MR (the selected MR) inside its popover.
- **Reaching a terminal MR from the chip.** Because there is no multi-MR
surface, the chip renders only for open MRs, and a merged or closed
association is not reachable from it. Unlinking a terminal association stays
with the topbar dropdown and the MR detail panel. This is a deliberate
divergence from `PRStatusChip`, which keeps terminal PRs in its multi-PR
surface for exactly that reason.
- **GitLab equivalents of `PRMergedBanner` / `PRClosedBanner`.** GitHub's chip
row shows an archive-prompt banner when a task's PR merges or closes. No
GitLab counterpart is added here.
- **Opening the MR detail panel from the chip popover.** `MRCIPopover`'s
`onOpenDetailPanel` prop is optional and the chip omits it, so the popover
title renders as static text. The dockview-settle logic that makes that open
reliable is owned by the topbar button, which remains the entry point.
- **Giving GitLab MR hydration a single provider-level owner.** It currently has
four independent call sites, each with its own per-instance "already fetched"
ref, so which surfaces a session has visited decides whether a given task's
MRs are in the store. Consolidating them is its own card. Until it lands, this
spec pins no hydration outcome and no AC depends on one. See Sync and
freshness.
- **A shared GitLab MR feedback cache or background sync.** No store slice, no
warmer, no polling is added.
- **Making `useGitLabStatus` cache across mounts, and stopping it blanking the
shared status.** Its effect refetches on every mount and clears the store to
`null` first, so each new consumer costs a request and transiently makes
`useGitLabAvailable()` read `false` everywhere. The chip inherits this rather
than introducing it — `MRTopbarButton` already calls the same helper on the
same route — and cannot fix it locally, because the hook serves navigation,
the kanban board, the settings sidebar and the integrations menu. Fixing it
means a card that can test all of those callers. See Sync and freshness.
- **A cross-chip disclosure coordinator.** Two chips mounted for one task may
both have an open disclosure, and each then issues its own MR feedback read.
Serialising that would require new shared "currently open chip" state that
neither mount point nor `MRTopbarButton` has today, and a rule for which chip
loses. The duplicate is an idempotent `GET` into a per-instance reducer. See
Sync and freshness.
- **A cross-mount in-flight guard for `useTaskMRAutomationOptions`.** Its lazy
fetch gates on render-captured state, so two chips mounted in one React commit
can each issue a `GET`. Fixing it means changing a hook `MRAutomationControls`
also uses from the topbar, so it needs a card that can test both callers. The
duplicate is an idempotent `GET` that converges to one stored object. See
Sync and freshness.
- **Restoring focus when the chip unmounts underneath its own drawer.**
Unlinking the task's last open MR from inside the drawer closes the drawer and
unmounts the trigger in the same update, so there is nothing to return focus
to and it falls to `document.body`. Choosing and moving focus to a surviving
landmark is a shared problem with `PRStatusChip` rather than one this chip
introduces, and fixing it well means deciding a focus target for the whole
status row. See Accessibility.
- **Making `MRCIPopover`'s controls Tab-reachable from a hover popover.** Radix
portals the content with no tab bridge from the trigger, so link, unlink and
merge are pointer- or drawer-only on a fine-pointer device. This gap is
pre-existing and shared with `PRStatusChip` and `MRTopbarButton`; the chip
inherits it rather than creating it, and fixing it would change a component
the topbar also renders. See Accessibility.
- **Changing `aggregateMRStatusColor`'s array-order tie behaviour.** Its
first-in-input-order tie is observable on the multi-MR kanban badge today.
This card freezes it rather than fixing it, because changing it is re-tuning
the colour priority, already excluded above. See State machine.
- **Enriched My-GitLab list badges, per-job checks UI in the detail panel,
mergeability explanation or conflict-fix CTA, merge-method picker, GitLab
webhooks, poller rate limiting, and poller-side watch reconciliation.**
- **Depending on the parent card's `resolvePushRepo` fix.** This feature is
independent in code. Its tests seed MR associations directly through the
existing link endpoint and the GitLab mock provider, never through autolink.
## Constraints
- New files SHALL be at most 600 lines and new components at most 200 lines.
The GitHub original is 634 lines in one file and is not a shape to copy;
the trigger, the glyph, the disclosure variants and the status derivation are
separate units.
- New copy SHALL use a `mrChip*` key prefix in
`apps/web/src/locales/en/gitlab.json`, following the same surface-scoped
prefix convention as the existing `mrPopover*` and `mrAutomation*` keys.
Copy that already exists under `mrPopover*` SHALL be reused rather than
duplicated. `data-testid` values and `data-status` values are identifiers and
SHALL NOT be translated.
- Every new file SHALL be appended to `i18nGuardFiles` in
`apps/web/eslint.i18n.options.mjs` in the same change.
- E2E coverage is required. The page object SHALL mirror the shape of
`apps/web/e2e/pages/session-page.ts` `tapPRStatusChip`, exposing
`mrStatusChip()`, `mrStatusChipDrawer()`, `mrStatusChipDrawerClose()`,
`mrStatusChipPopoverInner()` and `tapMRStatusChip()`.
Mirroring the shape means mirroring its **scoping**, not just its arity.
`prStatusChip()` is not a bare `getByTestId`; it resolves
`activeChat()` -> `chat-status-bar` -> `pr-status-chip`, which is what keeps it
from tripping Playwright's strict-locator check when more than one status row
is mounted. `mrStatusChip()` SHALL do the same for `chat-status-bar`. Because
this feature also has a scenario against the passthrough row, the page object
SHALL additionally expose **`mrStatusChipInPassthrough()`**, scoped to
`passthrough-status-row`. Without it the mandated zero-argument set can reach
only one of the two surfaces this spec requires coverage of. No accessor may
resolve `mr-status-chip` globally or paper over duplicates with `.first()`.
- Unit coverage SHALL include the `getMRStatusColor` and
`aggregateMRStatusColor` parity tables described above, updating
`mr-task-icon.test.ts` and `mr-status-colour-parity.test.tsx`. The
`aggregateMRStatusColor` table SHALL include at least one all-terminal pair in
both input orders, so the preserved array-order tie is pinned rather than
assumed.
- **File boundary.** The rule below governs **production React source only**. It
does not and cannot restrict the supporting files this same section mandates:
the locale catalog `apps/web/src/locales/en/gitlab.json`, the guard list
`apps/web/eslint.i18n.options.mjs`, the page object
`apps/web/e2e/pages/session-page.ts`, new specs under `apps/web/e2e/`, and the
unit tests named above are all required edits and all sit outside
`components/gitlab/`. An earlier draft stated the rule without that carve-out
and so contradicted its own i18n and E2E requirements.
Within production React source: the one permitted change outside
`components/gitlab/` and the two mount points is extracting `useUnlinkTaskMR`
into `apps/web/hooks/domains/gitlab/use-task-mr.ts` and pointing
`MRTopbarButton` at it. `MRTopbarButton`'s rendered output and observable
behaviour SHALL be unchanged, and `components/github/` SHALL NOT be touched at
all. `components/azure-devops/` SHALL NOT be touched either — which is why the
Azure leg of the DOM ordering has no AC.
## Related
- [gitlab-integration](../gitlab-integration/spec.md): the umbrella GitLab
feature this chip sits inside.
- `apps/web/CLAUDE.md`, "GitHub PR status UI": the GitHub-side invariant this
feature's single-derivation requirement mirrors for GitLab.