Real-time Collaboration: Add collaborators presence UI

packages/core-data/src/hooks/use-post-editor-awareness-state.ts

@@ -96,7 +96,7 @@ function usePostEditorAwarenessState(
  * @param  postType - The type of the post.
  * @return {ActiveUser[]} The active users.
  */
-export function useActiveUsers(
+export function useActiveCollaborators(
 	postId: number | null,
 	postType: string | null
 ): ActiveUser[] {

packages/core-data/src/private-apis.js

@@ -3,10 +3,12 @@
  */
 import { useEntityRecordsWithPermissions } from './hooks/use-entity-records';
 import { RECEIVE_INTERMEDIATE_RESULTS } from './utils';
+import { useActiveCollaborators } from './hooks/use-post-editor-awareness-state';
 import { lock } from './lock-unlock';
 
 export const privateApis = {};
 lock( privateApis, {
 	useEntityRecordsWithPermissions,
 	RECEIVE_INTERMEDIATE_RESULTS,
+	useActiveCollaborators,
 } );

packages/editor/src/components/collaborators-presence/avatar.tsx

@@ -0,0 +1,50 @@
+import { clsx } from 'clsx';
+import { type PostEditorAwarenessState } from '../../../../core-data/src/awareness/types';
+import './styles/avatar.scss';
+
+type AvatarSize = 'small' | 'medium';
+
+interface AvatarProps {
+	userInfo: PostEditorAwarenessState[ 'userInfo' ];
+	showUserColorBorder?: boolean;
+	size?: AvatarSize;
+}
+
+/**
+ * Renders a circular avatar bubble for a user with an optional border.
+ *
+ * @param {Object}  props                     Component props.
+ * @param {Object}  props.userInfo            User information.
+ * @param {boolean} props.showUserColorBorder Whether to show the user color border.
+ * @param {string}  props.size                Size of the avatar.
+ */
+export function Avatar( {
+	userInfo,
+	showUserColorBorder,
+	size = 'small',
+}: AvatarProps ) {
+	const className = clsx(
+		'editor-collaborators-presence__avatar',
+		`editor-collaborators-presence__avatar--${ size }`,
+		showUserColorBorder &&
+			'editor-collaborators-presence__avatar--with-color-border'
+	);
+
+	const avatarUrl =
+		userInfo.avatar_urls?.[ 48 ] ||
+		userInfo.avatar_urls?.[ 96 ] ||
+		userInfo.avatar_urls?.[ 24 ];
+
+	const avatarStyles = {
+		'--avatar-url': `url(${ avatarUrl })`,
+		'--user-color': userInfo.color,
+	} as React.CSSProperties;
+
+	return (
+		<div
+			className={ className }
+			style={ avatarStyles }
+			aria-hidden="true"
+		/>
+	);
+}

packages/editor/src/components/collaborators-presence/index.tsx

@@ -0,0 +1,94 @@
+import { Button } from '@wordpress/components';
+import { useState } from '@wordpress/element';
+import { privateApis } from '@wordpress/core-data';
+
+import { Avatar } from './avatar';
+import { CollaboratorsList } from './list';
+import { unlock } from '../../lock-unlock';
+import { type PostEditorAwarenessState } from '../../../../core-data/src/awareness/types';
+
+import './styles/collaborators-presence.scss';
+
+const { useActiveCollaborators } = unlock( privateApis );
+
+interface CollaboratorsPresenceProps {
+	postId: number | null;
+	postType: string | null;
+}
+
+/**
+ * Renders a list of avatars for the active users, with a maximum of 3 visible avatars.
+ * Shows a popover with all users on hover.
+ *
+ * @param {Object} props          CollaboratorsPresence component props
+ * @param {number} props.postId   ID of the post
+ * @param {string} props.postType Type of the post
+ */
+export function CollaboratorsPresence( {
+	postId,
+	postType,
+}: CollaboratorsPresenceProps ) {
+	const activeUsers = useActiveCollaborators(
+		postId,
+		postType
+	) as PostEditorAwarenessState[];
+
+	// Filter out current user - we never show ourselves in the list
+	const otherActiveUsers = activeUsers.filter( ( user ) => ! user.isMe );
+
+	const [ isPopoverVisible, setIsPopoverVisible ] = useState( false );
+	const [ popoverAnchor, setPopoverAnchor ] = useState< HTMLElement | null >(
+		null
+	);
+
+	// When there are no other collaborators, this component should not render
+	// at all. This will always be the case when collaboration is not enabled, but
+	// also when the current user is the only editor with the post open.
+	if ( otherActiveUsers.length === 0 ) {
+		return null;
+	}
+
+	const visibleUsers = otherActiveUsers.slice( 0, 3 );
+	const remainingUsers = otherActiveUsers.slice( 3 );
+	const remainingUsersText = remainingUsers
+		.map( ( { userInfo } ) => userInfo.name )
+		.join( ', ' );
+
+	return visibleUsers.length > 0 ? (
+		<div className="editor-collaborators-presence">
+			<Button
+				__next40pxDefaultSize
+				className="editor-collaborators-presence__button"
+				onClick={ () => setIsPopoverVisible( ! isPopoverVisible ) }
+				isPressed={ isPopoverVisible }
+				ref={ setPopoverAnchor }
+				aria-label={ `Collaborators list, ${ otherActiveUsers.length } online` }
+			>
+				{ visibleUsers.map( ( userState ) => (
+					<Avatar
+						key={ userState.clientId }
+						userInfo={ userState.userInfo }
+						showUserColorBorder={ false }
+						size="small"
+					/>
+				) ) }
+
+				{ remainingUsers.length > 0 && (
+					<div
+						className="editor-collaborators-presence__remaining"
+						title={ remainingUsersText }
+					>
+						+{ remainingUsers.length }
+					</div>
+				) }
+			</Button>
+			{ isPopoverVisible && (
+				<CollaboratorsList
+					activeUsers={ otherActiveUsers }
+					popoverAnchor={ popoverAnchor }
+					setIsPopoverVisible={ setIsPopoverVisible }
+				/>
+			) }
+		</div>
+	) : null;
+}

packages/editor/src/components/collaborators-presence/list.tsx

@@ -0,0 +1,79 @@
+import { __ } from '@wordpress/i18n';
+import { Popover, Button } from '@wordpress/components';
+import { close } from '@wordpress/icons';
+
+import { Avatar } from './avatar';
+
+import './styles/collaborators-list.scss';
+import { type PostEditorAwarenessState } from '../../../../core-data/src/awareness/types';
+
+interface CollaboratorsListProps {
+	activeUsers: PostEditorAwarenessState[];
+	popoverAnchor?: HTMLElement | null;
+	setIsPopoverVisible: ( isVisible: boolean ) => void;
+}
+
+/**
+ * Renders a list showing all active collaborators with their details.
+ * Note: activeUsers should already exclude the current user (filtered by parent component).
+ * @param props                     Component props
+ * @param props.activeUsers         List of active users
+ * @param props.popoverAnchor       Anchor element for the popover
+ * @param props.setIsPopoverVisible Callback to set the visibility of the popover
+ */
+export function CollaboratorsList( {
+	activeUsers,
+	popoverAnchor,
+	setIsPopoverVisible,
+}: CollaboratorsListProps ) {
+	return (
+		<Popover
+			anchor={ popoverAnchor }
+			placement="bottom"
+			offset={ 8 }
+			className="editor-collaborators-presence__list"
+			onClose={ () => setIsPopoverVisible( false ) }
+		>
+			<div className="editor-collaborators-presence__list-content">
+				<div className="editor-collaborators-presence__list-header">
+					<div className="editor-collaborators-presence__list-header-title">
+						{ __( 'Collaborators' ) }
+						<span> { activeUsers.length } </span>
+					</div>
+					<div className="editor-collaborators-presence__list-header-action">
+						<Button
+							__next40pxDefaultSize
+							icon={ close }
+							iconSize={ 16 }
+							label={ __( 'Close Collaborators List' ) }
+							onClick={ () => setIsPopoverVisible( false ) }
+						/>
+					</div>
+				</div>
+				<div className="editor-collaborators-presence__list-items">
+					{ activeUsers.map( ( userState ) => (
+						<button
+							key={ userState.clientId }
+							className="editor-collaborators-presence__list-item"
+							disabled
+							style={ {
+								opacity: userState.isConnected ? 1 : 0.5,
+							} }
+						>
+							<Avatar
+								userInfo={ userState.userInfo }
+								showUserColorBorder
+								size="medium"
+							/>
+							<div className="editor-collaborators-presence__list-item-info">
+								<div className="editor-collaborators-presence__list-item-name">
+									{ userState.userInfo.name }
+								</div>
+							</div>
+						</button>
+					) ) }
+				</div>
+			</div>
+		</Popover>
+	);
+}

packages/editor/src/components/collaborators-presence/styles/avatar.scss

@@ -0,0 +1,31 @@
+@use "@wordpress/base-styles/colors" as *;
+@use "@wordpress/base-styles/variables" as *;
+
+.editor-collaborators-presence__avatar {
+	background-image: var(--avatar-url);
+	background-size: cover;
+	background-position: center;
+	border-radius: $grid-unit-05 + 2;
+	border-width: 1.5px;
+	border-style: solid;
+	border-color: $gray-300;
+	font-size: 0;
+
+	&--small {
+		width: $button-size-small;
+		height: $button-size-small;
+		border-radius: $grid-unit-05 + 2;
+	}
+
+	&--medium {
+		width: $button-size-compact;
+		height: $button-size-compact;
+		border-radius: $grid-unit-10;
+	}
+
+	&--with-color-border {
+		border-color: var(--user-color);
+		box-shadow: inset 0 0 0 1px rgba($white, 0.7);
+		background-clip: padding-box;
+	}
+}

packages/editor/src/components/collaborators-presence/styles/collaborators-list.scss

@@ -0,0 +1,96 @@
+@use "@wordpress/base-styles/colors" as *;
+@use "@wordpress/base-styles/variables" as *;
+
+.editor-collaborators-presence__list.components-popover {
+	// Popover wrapper styles
+	.components-popover__content {
+		border: 1px solid $gray-300;
+		border-width: 1px 0 0 1px;
+		border-radius: $radius-large;
+		background: $white;
+		box-shadow: $elevation-small;
+	}
+
+	.editor-collaborators-presence__list-content {
+		min-width: 280px;
+	}
+
+	// Header with title and action button
+	.editor-collaborators-presence__list-header {
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+		padding: 0 $grid-unit-20;
+
+		&-title {
+			font-size: $font-size-medium;
+			font-weight: $font-weight-medium;
+			text-transform: uppercase;
+			line-height: $font-line-height-small;
+			padding: 14px 0;
+
+			span {
+				color: $gray-700;
+			}
+		}
+
+		&-action {
+			padding: $grid-unit-10 0;
+
+			button {
+				color: $gray-900;
+				height: $button-size-small;
+				width: $button-size-small;
+				padding: 0;
+			}
+		}
+	}
+
+	// List of collaborators
+	.editor-collaborators-presence__list-items {
+		display: flex;
+		flex-direction: column;
+		padding: 0 10px $grid-unit-20;
+	}
+
+	.editor-collaborators-presence__list-item {
+		// Reset button styles
+		all: unset;
+		box-sizing: border-box;
+
+		// Layout styles
+		display: flex;
+		align-items: center;
+		padding: $grid-unit-05 + 2;
+		gap: $grid-unit-10;
+		border-radius: $radius-large + $grid-unit-05;
+		width: 100%;
+		cursor: pointer;
+		transition: background-color 0.2s ease;
+
+		&:hover:not(:disabled) {
+			background-color: rgba($black, 0.05);
+		}
+
+		&:active:not(:disabled) {
+			background-color: rgba($black, 0.08);
+		}
+
+		&:focus-visible {
+			outline: 2px solid var(--wp-admin-theme-color, #007cba);
+			outline-offset: -2px;
+		}
+
+		&:disabled {
+			cursor: default;
+		}
+
+		&-info {
+			display: flex;
+			flex-direction: column;
+			flex: 1;
+			line-height: $font-line-height-x-small;
+			font-size: $font-size-small;
+		}
+	}
+}