Skip to content

ERMAIN-411: Mac 'pin the add-in' hint for the unpinned/frozen task pane#784

Open
bdart wants to merge 4 commits into
mainfrom
feature/ermain-411-add-in-new-outlook-mac-recover-from-lost-item-context-office
Open

ERMAIN-411: Mac 'pin the add-in' hint for the unpinned/frozen task pane#784
bdart wants to merge 4 commits into
mainfrom
feature/ermain-411-add-in-new-outlook-mac-recover-from-lost-item-context-office

Conversation

@bdart

@bdart bdart commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

Summary

On new Outlook for Mac (desktop), an unpinned add-in task pane stays open (Mac never auto-closes it) but is bound to the message it was opened from and never receives ItemChanged — so the chat silently freezes on that first mail while the user keeps navigating. This adds a Mac-only, self-clearing "pin this add-in" hint that nudges the user to pin (the one thing that makes the pane track), plus a small handler-cleanup fix.

Resolves ERMAIN-411.

Why a hint, and not an automatic fix

This was investigated heavily (see the ticket for the full trail). The short version, all confirmed against current office-js issues / MS docs:

  • You cannot auto-track an unpinned pane. Pinning is the only mechanism that delivers item changes; there is no programmatic way to pin.
  • SupportsMultiSelect does not help. Its Mac auto-pin applies only to the multi-select launch scenario, not single-message navigation (it was prototyped and reverted).
  • You cannot reliably detect the pin state. No isPinned API (office-js #1691); Microsoft acknowledges the exact gap in #4187. On Mac the signals you'd infer it from are broken (getSelectedItemsAsync → 5001, SelectedItemsChanged unreliable).

So the realistic, vendor-consensus mitigation is to teach the user to pin, shown only where the problem exists.

What's in this PR

  • AddinPinHintBanner — dismissible, non-blocking banner ("Pin to follow your mail …"), inline SVGs, theme-warning styling.
  • OutlookMailItemProvider.hasItemChangedFired — drives the self-clear. Set true only when the resolved item identity actually changes (a real navigation, which only a pinned/tracking pane observes). The host's initial same-item bind event is deliberately ignored — otherwise the hint flashed and cleared the instant the first message loaded.
  • AddinChat wiring — banner shows only when platform === "Mac" && !hasItemChangedFired && !pinHintDismissed. platform === "Mac" is the desktop client only (OWA = OfficeOnline, Windows = PC/OfficeOnline), so every unaffected platform is excluded. Dismiss persists in localStorage.
  • Handler-cleanup fixremoveHandlerAsync now receives the registered handler instead of a throwaway () => {} (was a StrictMode leak).
  • i18nofficeAddin.pinHint.* added and translated for de/es/fr/pl (en source filled).

No manifest changes ship in this PR (the SupportsMultiSelect prototype was fully reverted; net manifest diff is zero).

Behavior

Scenario (Mac desktop) Result
Unpinned, reading & switching mail Hint persists (the nudge)
User pins, then navigates First real item change → hint clears
User dismisses (✕) Hidden, persisted per client
Pinned, fresh session Shows until first navigation, then clears
Windows / web / OWA Never shown

Testing

  • typecheck ✅ · lint:strict (max-warnings=0) ✅ · prettier ✅ · i18n:extract:check
  • 9 unit tests ✅ — incl. a regression that a same-item event does not flip hasItemChangedFired (only a different item does), banner render/dismiss, and removeHandlerAsync passing the registered handler.
  • Manually verified on new Outlook for Mac desktop: hint appears unpinned, clears on pin+navigate / dismiss.

Known limitations / follow-ups

  • This is the coarse #1691 heuristic. One Mac edge (#4216: unpinned internetMessageId can come back empty on re-read) could in theory clear it early; fallback would be "show on Mac until dismissed."
  • A pinned user sees it briefly each session until their first navigation (the tracking flag isn't persisted, intentionally, so unpinning is re-detected next session).
  • The de strings could use a native-speaker gut-check.
  • Unrelated: the pin elements had to be edited in two hand-maintained manifests — single-sourcing them is tracked separately.

bdart added 3 commits June 27, 2026 18:18
… (#5575)

Detect the silently-undefined item dead state (prior read item went falsy,
stayed gone past a settle window) and show a dismissible Retry banner; leave
the legitimate contextless state untouched. Also remove the registered
handler (not a throwaway) in mailbox cleanup.
The real symptom is an unpinned pane on new Outlook Mac freezing on the
first-opened mail (no ItemChanged), not the #5575 undefined-item case. Revert
the dead-state detection/banner wiring; keep the removeHandlerAsync cleanup fix
and park the banner for a future 'pin to follow' hint. Add SupportsMultiSelect
so Mac auto-pins (office-js #5921) and tracks mail navigation.
Revert SupportsMultiSelect (Mac auto-pin only applies to a multi-select
launch, not single-message nav). Add AddinPinHintBanner shown only on Outlook
for Mac desktop (platform === 'Mac'), and hidden once the selected item
actually changes to a *different* message — a real navigation, which only a
pinned/tracking pane observes. The host's initial same-item bind event is
ignored (otherwise the hint flashed and cleared the instant the first message
loaded). Dismiss is persisted. No API to pin or detect pin state (office-js
#1691/#4187), so nudging is the only fix.
@bdart bdart self-assigned this Jun 29, 2026
@bdart bdart added the enhancement New feature or request label Jun 29, 2026
…ractionRequiredAuthError ctor

CI installs the add-in with --no-frozen-lockfile, so the ^5.2.0 range floated
to msal-browser 5.15.0 / msal-common 16.10.0, which made AuthError's errorCode +
a new correlationId required (2-8 args) — breaking the untouched entraAuthSource
typecheck. Pin to the installed versions and pass the required correlationId
(detection is instanceof, so the value is cosmetic). Unblocks CI lint.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant