Real-time Collaboration: Add collaborators presence UI

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 { useActiveUsers } from './hooks/use-post-editor-awareness-state';
 import { lock } from './lock-unlock';
 
 export const privateApis = {};
 lock( privateApis, {
 	useEntityRecordsWithPermissions,
 	RECEIVE_INTERMEDIATE_RESULTS,
+	useActiveUsers,
 } );

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

@@ -0,0 +1,55 @@
+import './styles/avatar.scss';
+
+type AvatarSize = 'small' | 'medium';
+
+/**
+ * Renders a circular avatar bubble for a user with an optional border.
+ * @param root0
+ * @param root0.userInfo
+ * @param root0.userInfo.name
+ * @param root0.userInfo.color
+ * @param root0.userInfo.avatar_urls
+ * @param root0.showUserColorBorder
+ * @param root0.size
+ */
+export function Avatar( {
+	userInfo,
+	showUserColorBorder,
+	size = 'small',
+}: {
+	userInfo: {
+		name: string;
+		color: string;
+		avatar_urls?: Record< string, string >;
+	};
+	showUserColorBorder?: boolean;
+	size?: AvatarSize;
+} ) {
+	const className = [
+		'editor-collaborators-presence__avatar',
+		`editor-collaborators-presence__avatar--${ size }`,
+		showUserColorBorder &&
+			'editor-collaborators-presence__avatar--with-color-border',
+	]
+		.filter( Boolean )
+		.join( ' ' );
+
+	const avatarUrl =
+		userInfo.avatar_urls?.[ 48 ] ||
+		userInfo.avatar_urls?.[ 96 ] ||
+		userInfo.avatar_urls?.[ 24 ];
+
+	const avatarStyles: React.CSSProperties &
+		Record< `--${ string }`, string > = {
+		'--avatar-url': `url(${ avatarUrl })`,
+		'--user-color': userInfo.color,
+	};
+
+	return (
+		<div
+			className={ className }
+			style={ avatarStyles }
+			aria-hidden="true"
+		/>
+	);
+}

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

@@ -0,0 +1,100 @@
+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 './styles/collaborators-presence.scss';
+
+const { useActiveUsers } = unlock( privateApis );
+
+interface UserInfo {
+	name: string;
+	color: string;
+	avatar_urls?: Record< string, string >;
+}
+
+interface UserState {
+	clientId: string;
+	isMe: boolean;
+	userInfo: UserInfo;
+}
+
+interface AvatarsProps {
+	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 root0
+ * @param root0.postId
+ * @param root0.postType
+ */
+export function CollaboratorsPresence( { postId, postType }: AvatarsProps ) {
+	const activeUsers = useActiveUsers( postId, postType ) as UserState[];
+
+	// 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
+	);
+
+	if ( otherActiveUsers.length === 0 ) {
+		// Hide avatars when there are no other users
+		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.map( ( user ) => ( {
+						clientId: user.clientId,
+						isConnected: true,
+						userInfo: user.userInfo,
+					} ) ) }
+					popoverAnchor={ popoverAnchor }
+					setIsPopoverVisible={ setIsPopoverVisible }
+				/>
+			) }
+		</div>
+	) : null;
+}

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

@@ -0,0 +1,88 @@
+// import { speak } from '@wordpress/a11y';
+import { Popover, Button } from '@wordpress/components';
+import { close } from '@wordpress/icons';
+
+import { Avatar } from './avatar';
+
+import './styles/collaborators-list.scss';
+
+interface CollaboratorsListProps {
+	activeUsers: {
+		clientId: string;
+		isConnected: boolean;
+		userInfo: {
+			name: string;
+			color: string;
+			avatar_urls?: Record< string, string >;
+		};
+	}[];
+	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 root0
+ * @param root0.activeUsers
+ * @param root0.popoverAnchor
+ * @param root0.setIsPopoverVisible
+ */
+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"
+							onClick={ () => {} }
+							disabled={ ! userState.isConnected }
+							aria-label="Clicking scrolls to cursor position in the editor"
+							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;
+		}
+	}
+}