Editor: Polish real-time collaboration presence UI and move Avatar to editor package

[dabowman]

What?

Polishes the real-time collaboration (RTC) presence UI — the collaborator button, list popover, and block highlight labels — and moves the Avatar and AvatarGroup components from @wordpress/components private APIs into the @wordpress/editor package where they are consumed.

Why?

Follow-up to #75595. That PR introduced the collaborator overlay with cursor and block highlight rendering. This PR refines the visual design of the presence UI to match the Figma spec and addresses component ownership:

• Avatar belongs in editor, not components — The Avatar component is tightly coupled to the RTC collaboration feature and is not yet general-purpose. Keeping it in @wordpress/components as a private API adds unnecessary coupling and prevents the editor package from owning its own styling (e.g. $components-color-accent is restricted to the components package by stylelint).
• Presence button needed polish — Background color states (resting, hover, pressed) and max avatar count didn't match the design.
• List popover didn't match spec — Layout, typography, hover states, and header design were out of sync with the Figma design.
• Block highlight labels were missing — The collaborator block highlight outline needed an avatar badge label positioned above it to identify who selected the block.

How?

Avatar component changes (badge → variant, status → dimmed)

• Replaced badge boolean prop with variant: 'badge' enum (extensible for future variants)
• Replaced status string prop with dimmed boolean (simpler API for the single use case)
• Added contrast-aware badge text color using colord — automatically switches to dark text when borderColor is light
• Moved background-color from root to .is-badge so non-badge avatars don't show a colored background behind the white ring

Move to editor package

• Moved Avatar and AvatarGroup from packages/components/src/avatar{,-group}/ to packages/editor/src/components/collaborators-presence/avatar{,-group}/
• Removed from @wordpress/components private APIs (private-apis.ts) and style.scss
• Consumers import directly (import Avatar from './avatar') instead of using unlock()
• Added colord to editor package.json
• Uses var(--wp-admin-theme-color, #3858e9) instead of $components-color-accent (which is restricted by stylelint outside the components package)
• Component types use Props & Omit<React.HTMLAttributes<HTMLDivElement>, keyof Props> instead of WordPressComponentProps (not publicly exported)

Presence button polish

• Container handles background color (resting $gray-100, hover/pressed $gray-200); inner Button stays transparent in all states
• AvatarGroup max={4} to match design
• Overflow count has margin-inline-end for right padding

Collaborators list popover

• Full-width list items with no border-radius, $grid-unit-15 $grid-unit-20 padding
• Header: normal-case title + count, closeSmall icon at 24px
• Name: $font-size-medium / $font-weight-medium
• Hover: theme-tinted rgba(#3858e9, 0.04)

Block highlight avatar labels

• Each highlighted block now shows an Avatar badge (variant="badge", size="small") at its top-left corner
• Positioned 8px above the outline via transform: translateY(calc(-100% - 8px))
• Label expands on hover to show the collaborator's name
• useBlockHighlighting refactored to return BlockHighlightData[] (same pattern as useRenderCursors)

Overlay inline styles

• Updated compiled Avatar CSS in COLLABORATORS_OVERLAY_STYLES to stay in sync with the SCSS source
• Dimmed/status-indicator styles intentionally omitted (not used in overlay)

Testing Instructions

Note: RTC collaboration features require a collaborative editing environment with multiple users connected to the same post via the sync provider.

1. Open a post in the editor with RTC/collaboration enabled
2. Have a second user connect to the same post
3. Presence button: Verify the collaborator avatars appear in the header toolbar, stacked with a +N overflow count when > 4 users. Check hover/pressed background states match surrounding toolbar items.
4. Collaborators list: Click the avatar group to open the popover. Verify:
   • Header shows "Collaborators" with count and close button
   • Each row shows avatar with colored border and user name
   • Rows highlight on hover with a subtle tint
5. Cursor labels: Move the second user's cursor within a block. Verify the pill-shaped avatar badge appears at the cursor position and expands on hover to show the name.
6. Block highlight labels: Have the second user select an entire block. Verify:
   • The block gets a colored outline
   • An avatar badge appears above the top-left corner of the outline
   • The badge expands on hover to show the collaborator's name
7. For users without a custom Gravatar, verify initials are shown instead of a placeholder image.

Keyboard testing

1. Tab to the collaborator avatars button in the header toolbar
2. Press Enter/Space to open the popover
3. Verify focus moves into the popover
4. Press Escape to close — verify focus returns to the trigger button

Screenshots or screencast

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @claude.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: claude.

Co-authored-by: dabowman <davidabowman@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: maxschmeling <maxschmeling@git.wordpress.org>
Co-authored-by: chriszarate <czarate@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[ciampo]

Thank you for working on this! I left some initial comments.

In general, I'd prefer smaller PRs that focused on single tasks — for example, one PR that moves the code to the editor package, and one or more follow-up PRs that apply the rest of the changes (as grouped under the "How" section in the PR description)

[jasmussen]

Thanks for the ping. In general I ihave some trust that this can move forward on a dev heavy side while it's still relatively exotic, but if you need any visual reviews, are you able to provide screenshots? It can be a bit tricky to review this particular feature.

[dabowman]

@jasmussen here's a screenshot of the current state of the UI with a bunch of collaborators in a session. You can also see the same colors being used between notes and the collab components.

[dabowman]

@ciampo I tried to make that big css string a bit more friendly. I split it into two dedicated files. One for the avatar component and one for the rest of the overlay styling. I also added a file of variables that maps to the scss variables we'd like to reference but can't. That way the css is at least pulling what it can from a shared file that we can map to the system and try to keep in sync. The core issue is that we can't really add a lot of styles to the iframe without putting stuff in the block-editor package or adding some plumbing to allow us to enqueue styles from here to get compiled with the rest of the block-editor styles. It's a bit janky but hopefully this makes it a bit more sustainable until folks have time to build out a more permanent solution.

[jasmussen]

Looks good!

[Copilot]

Pull request overview

This PR refines the real-time collaboration (RTC) presence UI in the editor (presence button + list popover + block highlight labels) and relocates the RTC-specific Avatar/AvatarGroup components from @wordpress/components private APIs into @wordpress/editor, including updating iframe-injected overlay styles.

Changes:

• Move Avatar and AvatarGroup into packages/editor and update consumers to import them directly (removing unlock( componentsPrivateApis ) usage).
• Polish presence button + collaborators list popover styling and update avatar rendering API (variant="badge", dimmed).
• Extend the overlay to render avatar badge labels for whole-block selections, with updated iframe CSS injection.

Reviewed changes

Copilot reviewed 20 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/editor/src/style.scss	Includes new Avatar/AvatarGroup SCSS in editor bundle.
packages/editor/src/components/collaborators-presence/styles/collaborators-presence.scss	Updates presence button container/pressed styling behavior.
packages/editor/src/components/collaborators-presence/styles/collaborators-list.scss	Restyles collaborators list popover (layout/typography/hover/focus).
packages/editor/src/components/collaborators-presence/list.tsx	Switches to editor-owned Avatar and uses dimmed state.
packages/editor/src/components/collaborators-presence/index.tsx	Switches to editor-owned Avatar/AvatarGroup and adjusts max avatars.
packages/editor/src/components/collaborators-presence/avatar/types.ts	Updates Avatar public props (variant, dimmed) and IconType import.
packages/editor/src/components/collaborators-presence/avatar/styles.scss	Adds editor-scoped Avatar styles + badge + dimmed styling.
packages/editor/src/components/collaborators-presence/avatar/index.ts	Re-exports Avatar component and types.
packages/editor/src/components/collaborators-presence/avatar/component.tsx	New Avatar implementation (contrast-aware badge text via colord).
packages/editor/src/components/collaborators-presence/avatar-group/types.ts	Defines AvatarGroup props in editor package.
packages/editor/src/components/collaborators-presence/avatar-group/styles.scss	Adds editor-scoped AvatarGroup styles (overlap + overflow).
packages/editor/src/components/collaborators-presence/avatar-group/index.ts	Re-exports AvatarGroup component and types.
packages/editor/src/components/collaborators-presence/avatar-group/component.tsx	New AvatarGroup implementation for editor package.
packages/editor/src/components/collaborators-overlay/use-block-highlighting.ts	Refactors highlighting hook to return highlight label render data.
packages/editor/src/components/collaborators-overlay/overlay.tsx	Injects new iframe CSS strings and renders block highlight avatar labels.
packages/editor/src/components/collaborators-overlay/overlay-iframe-styles.ts	New overlay positioning CSS for iframe injection.
packages/editor/src/components/collaborators-overlay/collaborator-styles.ts	Centralizes compiled design-token constants used in injected CSS.
packages/editor/src/components/collaborators-overlay/avatar-iframe-styles.ts	New injected CSS for editor-owned Avatar inside iframe.
packages/editor/src/components/collab-sidebar/utils.js	Updates deterministic avatar border color palette.
packages/editor/package.json	Adds colord dependency for contrast-aware color logic.
packages/components/src/style.scss	Removes Avatar/AvatarGroup SCSS from components bundle.
packages/components/src/private-apis.ts	Removes Avatar/AvatarGroup from components private API surface.
packages/components/src/avatar/component.tsx	Removes components-owned Avatar implementation.
package-lock.json	Locks new colord dependency.

Comments suppressed due to low confidence (1)

packages/editor/src/components/collaborators-presence/avatar-group/component.tsx:38

• The overflow indicator’s aria-label string ("${overflowCount} more") is not localized. Since this is user-facing for screen readers, it should use @wordpress/i18n (and ideally include context like “more collaborators”).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Mamaduka]

Not sure if this was already reported, but new avatars doesn't seem to be work with Safari.

Screeenshot

[maxschmeling]

Is it necessary to run the rerenderAfterDelay when it changes? Having a useEffect where the function is also the dependency seems strange.

[dabowman]

that makes sense, I refactored.

[chriszarate]

Use of getBoundingClientRect() in render. No need for action on this david, just flagging for @alecgeatches

[dabowman]

@chriszarate @maxschmeling I think this is ready to go. No merge conflicts. Tests are passing. I addressed all feedback from @ciampo and fixed that weird Safari rendering issue with the avatars. I think we're all set.

[ciampo]

@chriszarate @maxschmeling @dabowman just wanted to flag that this PR is merged, but not backported to wp/7.0. I don't know if you intented to backport it at all, but flagging just in case.

[chriszarate]

@chriszarate @maxschmeling @dabowman just wanted to flag that this PR is merged, but not backported to wp/7.0. I don't know if you intented to backport it at all, but flagging just in case.

Thanks, backported

[github-actions]

There was a conflict while trying to cherry-pick the commit to the wp/7.0 branch. Please resolve the conflict manually and create a PR to the wp/7.0 branch.

PRs to wp/7.0 are similar to PRs to trunk, but you should base your PR on the wp/7.0 branch instead of trunk.

# Checkout the wp/7.0 branch instead of trunk.
git checkout wp/7.0

# Create a new branch for your PR.
git checkout -b my-branch

# Cherry-pick the commit.
git cherry-pick 2bb53b10ce353e4785574f8267076639cadff48b

# Check which files have conflicts.
git status

# Resolve the conflict...
# Add the resolved files to the staging area.
git status
git add .
git cherry-pick --continue

# Push the branch to the repository
git push origin my-branch

# Create a PR and set the base to the wp/7.0 branch.
# See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.