@micha.bigler/ui-core-micha 2.18.0 → 2.20.0

package/work-orders/MSG-3e.md

@@ -0,0 +1,164 @@
+# MSG-3e — per-candidate scope in `DirectMessageLauncher`
+
+Status: planned · Tier 2 · Target repo: `ui-core-micha` (main)
+
+---
+
+## Part A — Envelope (2026-08-02)
+
+### Goal
+
+Let a host present **one flat direct-message picker whose candidates live in different messaging
+scopes**. Today `DirectMessageLauncher` takes a single `scope` prop and applies it to every candidate,
+so a host with people spread across several scopes must either render one launcher per scope or
+re-implement the component.
+
+### Why now
+
+jg-ferien MSG-6 turns `/messages` into a global inbox across **all** of a user's events. In jg's model a
+direct conversation is scoped to an event, so a flat "everyone I may DM" list carries a **different
+scope per person** — the operator's explicit requirement ("DM über alle, Gruppen pro Event"). Without
+this seam jg would have to copy ~90 lines of this component locally, which AGENTS.md's
+reuse-before-reimplement rule exists to prevent. The need is generic: any host whose people span
+multiple scopes hits it.
+
+### Expected outcome
+
+`candidates[n].scope` (optional) takes precedence over the `scope` prop **for the selected candidate
+only**. Precisely:
+
+| selected candidate's `scope` | `scope` prop | scope sent to `createDirectConversation` |
+|---|---|---|
+| present | present | the candidate's |
+| present | absent | the candidate's |
+| absent | present | the prop's (today's behaviour) |
+| absent | absent | no `scope` key in the payload at all (today's behaviour) |
+
+Strictly additive and backward compatible: a host that passes no per-candidate scope sees byte-identical
+behaviour. Note the last row — the current code omits the key entirely rather than sending
+`scope: null`, and that must not change; dcm distinguishes the two.
+
+### Scope / non-goals
+
+In scope: `src/messaging/DirectMessageLauncher.jsx` and its test file.
+
+Explicit non-goals — do **not**:
+- change the dialog's layout, copy, i18n keys, or a11y semantics;
+- add grouping, sectioning, or per-candidate secondary text (a scope is not a label — jg groups its
+  *group* picker by event locally, and that stays a host concern);
+- touch `MessagingProvider`'s `openDirectConversation` signature or any other component;
+- validate or interpret the scope value — it is an opaque host-supplied identifier, passed through.
+
+### Tier
+
+Tier 2. Shared-core (`ui-core-micha`) is excluded from the Tier-1 fast path by AGENTS.md regardless of
+diff size, so this one-line-of-logic change gets a WO, Codex-first, and a mandatory independent review.
+
+### Tests to WRITE (scoped — run only these)
+
+Extend `tests/messagingDirectMessageLauncher.test.jsx`:
+
+1. **per-candidate scope wins** — candidates `[{id: 2, display_name: 'Alex', scope: 'scope-a'}, {id: 3,
+   display_name: 'Sam', scope: 'scope-b'}]`, launcher `scope="scope-prop"`; select Sam, start; assert
+   `createDirectConversation` called with `{target_user_id: 3, scope: 'scope-b'}`.
+2. **fallback to the prop** (regression) — a candidate without its own `scope` in the same mixed list
+   still sends the prop's scope.
+3. **neither present** — no `scope` key in the payload (`expect(Object.keys(payload)).toEqual(
+   ['target_user_id'])` or equivalent — asserting absence, not `undefined`).
+
+The three existing tests in that file must keep passing unchanged; they are the backward-compatibility
+proof and must not be edited to accommodate the change.
+
+Command: `pnpm vitest run tests/messagingDirectMessageLauncher.test.jsx`
+
+### Release
+
+One version bump `2.19.0` → **`2.20.0`** (minor: additive, backward-compatible) + npm publish at WO end.
+jg-ferien MSG-6 pins this version, so the publish is the precondition for that WO's final test run.
+Per `reference_dcm_ucm_publish_topology`: publish-from-main, and the target version must be verified
+live on the registry before jg bumps its pin.
+
+### Risks
+
+Low. The one real trap is the "absent/absent" row above — a naive `scope: candidate.scope ?? scope`
+inside the object literal would start sending `scope: undefined`, which serialises differently and
+changes an existing contract. Build the payload conditionally, as the current code already does.
+
+### Execution directive
+
+**If you are the implementer reading this as your own spec, this section is not addressed to you — it
+tells the Orchestrator how to invoke you. You ARE that invocation: do not shell out to `codex exec`.**
+
+Orchestrator: implement through `codex exec` in the background, invoked **directly via Bash** (never the
+`debugger`/`*_coder` Agent wrappers), with **both** flags `--skip-git-repo-check` and
+`--dangerously-bypass-approvals-and-sandbox`, the WO passed as a positional argument from this committed
+file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit; if the
+fallback is used the Orchestrator becomes author and an independent `reviewer` is mandatory.
+
+### Mini-handover (pastable)
+
+Orchestrator: implement `work-orders/MSG-3e.md` in `ui-core-micha` (main). `git pull` first, read the WO,
+then follow `orchestrate-codex` (Codex-first, own independent review, publish 2.20.0 at WO end).
+
+---
+
+## Part B — Implementation map (Orchestrator)
+
+**Single chunk.** **Target repo working directory:** `C:\Users\Micha Bigler\Documents\webapps\ui-core-micha`
+(repo root). Work from this package; open only the named files to verify.
+
+### The one file that changes
+
+`src/messaging/DirectMessageLauncher.jsx` — 96 lines, whole file is in scope but only `start()` and one
+derivation change.
+
+Current state (verified while scoping, do not re-derive):
+
+- `:25` — `export function DirectMessageLauncher({ candidates = [], scope, onOpen })`.
+- `:31` — the component tracks **only** `selectedId`, never the selected candidate object. A lookup is
+  therefore needed; mirror the pattern jg already uses in its own `AllGroupsLauncher`
+  (`jg-ferien/frontend/src/pages/messaging/AllGroupsLauncher.jsx:40-44`):
+  `const selectedCandidate = useMemo(() => candidates.find((c) => c.id === selectedId) || null,
+  [candidates, selectedId]);` — `useMemo` is not yet imported in this file (`:1` imports `useId, useState`).
+- `:44-60` — `start()`; the payload is built at `:49-52`:
+  ```js
+  const conversation = await openDirectConversation({
+    target_user_id: selectedId,
+    ...(scope == null ? {} : { scope }),
+  });
+  ```
+  This spread-or-nothing shape is the invariant the third test pins: when there is no scope the key is
+  **absent**, not `undefined`. Keep the shape; only the value fed into it changes:
+  `const effectiveScope = selectedCandidate?.scope ?? scope;` then `...(effectiveScope == null ? {} :
+  { scope: effectiveScope })`. `??` (not `||`) so a falsy-but-valid scope id survives.
+- `:75-82` — the `ListItemButton` render loop; **do not** change it. Candidate rendering already falls
+  back through `display_name || name || label || id` and the scope must not appear in the UI.
+
+### Invariants / do-not-touch
+
+- `extractApiErrorMessage` error path (`:55-59`) and the `starting` guard stay exactly as they are.
+- `openDirectConversation` comes from `useMessaging()` (`:19, :27`) — its signature is dcm's contract,
+  unchanged.
+- `src/index.js:72` already exports the component; no export change.
+- No new i18n keys (`MessagingDirect.*` set is complete for this change).
+
+### Docs
+
+`docs/messaging-deviations.md` currently has zero BLOCKED entries (MSG-3d closed them) — this WO adds no
+deviation and must not add a row. If the repo carries a prop-level API note for this component, update it;
+if not, do not invent a docs file.
+
+### Progress contract
+
+Emit a `PLAN: …` line first, then a single-line `PROGRESS: [n/total] <action>` before every relevant
+action and `… done` on completion, no gap > ~2 min, unbuffered stdout, and exactly one final
+`RESULT: DONE|BLOCKED <reason>`.
+
+### Constraints for the implementer
+
+The WO text is the COMPLETE spec. Read `AGENTS.md` and `.codex/skills/frontend-engineering` only for
+conventions. Stay in scope. Do not touch the Core-Behaviour approval surfaces. Do not update `MEMORY.md`.
+Do **not** `git add/commit/push` — leave the diff for the Orchestrator's review. Do **not** bump the
+version or publish — the Orchestrator owns the release. WRITE the three tests above and RUN ONLY that one
+test file; no full suite, no self-review — the Orchestrator owns the authoritative run and the
+independent review, and those are the gate.