@wordpress/editor 14.41.0 → 14.41.1-next.v.202603102151.0

package/src/components/collaborators-presence/avatar/styles.scss

@@ -0,0 +1,168 @@
+@use "@wordpress/base-styles/colors" as *;
+@use "@wordpress/base-styles/variables" as *;
+
+// Accent color for the avatar. Uses the admin theme color with a hardcoded
+// fallback matching the default WordPress admin blue.
+$-accent-color: var(--wp-admin-theme-color, #3858e9);
+
+.editor-avatar {
+	position: relative;
+	display: inline-flex;
+	align-items: center;
+	border-radius: $radius-full;
+	overflow: hidden;
+	overflow: clip;
+	flex-shrink: 0;
+	box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $white, $elevation-x-small;
+}
+
+.editor-avatar__image {
+	box-sizing: border-box;
+	position: relative;
+	width: $button-size-compact;
+	height: $button-size-compact;
+	border-radius: $radius-full;
+	border: 0;
+	background-color: $-accent-color;
+	overflow: hidden;
+	overflow: clip;
+	flex-shrink: 0;
+	font-size: 0;
+	color: $white;
+
+	.is-small > & {
+		width: $button-size-small;
+		height: $button-size-small;
+	}
+
+	.has-avatar-border-color > & {
+		border: var(--wp-admin-border-width-focus) solid var(--editor-avatar-outline-color);
+		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) $white;
+		background-clip: padding-box;
+	}
+}
+
+// The <img> element, absolutely positioned to fill the __image container.
+// Starts invisible; becomes visible when the image loads (has-src class).
+.editor-avatar__img {
+	position: absolute;
+	inset: 0;
+	width: 100%;
+	height: 100%;
+	object-fit: cover;
+	border-radius: inherit;
+	opacity: 0;
+
+	.has-src > .editor-avatar__image > & {
+		opacity: 1;
+	}
+}
+
+// Initials fallback: show name characters when no image has loaded.
+.editor-avatar:not(.has-src) > .editor-avatar__image {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	font-size: $font-size-x-small;
+	font-weight: $font-weight-medium;
+	border: 0;
+	box-shadow: none;
+	background-clip: border-box;
+}
+
+.editor-avatar:not(.has-src).has-avatar-border-color > .editor-avatar__image {
+	background-color: var(--editor-avatar-outline-color);
+}
+
+.editor-avatar__name {
+	font-size: $font-size-medium;
+	font-weight: $font-weight-medium;
+	line-height: $font-line-height-small;
+	color: var(--editor-avatar-name-color, $white);
+	min-width: 0;
+	padding-bottom: calc($grid-unit-05 / 2);
+	overflow: hidden;
+	opacity: 0;
+	white-space: nowrap;
+	transition: opacity 0.15s cubic-bezier(0.15, 0, 0.15, 1);
+}
+
+// Badge mode: use grid so the name column animates from 0 to natural width.
+// Spacing is on the container (column-gap + padding-inline-end) so it
+// transitions alongside grid-template-columns instead of causing a bump.
+.editor-avatar.is-badge {
+	display: inline-grid;
+	grid-template-columns: min-content 0fr;
+	column-gap: 0;
+	padding-inline-end: 0;
+	background-color: $-accent-color;
+	transition:
+		grid-template-columns 0.3s cubic-bezier(0.15, 0, 0.15, 1),
+		column-gap 0.3s cubic-bezier(0.15, 0, 0.15, 1),
+		padding-inline-end 0.3s cubic-bezier(0.15, 0, 0.15, 1);
+
+	&:hover {
+		grid-template-columns: min-content 1fr;
+		column-gap: $grid-unit-05;
+		padding-inline-end: $grid-unit-10;
+		transition-timing-function: cubic-bezier(0.85, 0, 0.85, 1);
+	}
+
+	&:hover .editor-avatar__name {
+		opacity: 1;
+		transition-timing-function: cubic-bezier(0.85, 0, 0.85, 1);
+	}
+}
+
+.editor-avatar.is-badge.has-avatar-border-color {
+	background-color: var(--editor-avatar-outline-color);
+}
+
+// Dimmed: neutral gray background at 50% opacity. The status indicator is a
+// sibling (outside __image) so it stays at full opacity.
+.editor-avatar.is-dimmed > .editor-avatar__image {
+	opacity: 0.5;
+	background-color: $gray-700;
+}
+
+.editor-avatar.is-dimmed.has-avatar-border-color > .editor-avatar__image {
+	border-color: $gray-700;
+}
+
+// Dimmed images: desaturate via CSS filter instead of mix-blend-mode.
+.editor-avatar.is-dimmed .editor-avatar__img {
+	filter: grayscale(1);
+}
+
+// Status indicator: positioned over the image area, outside __image so it
+// is unaffected by the dimmed opacity.
+.editor-avatar__status-indicator {
+	position: absolute;
+	top: 0;
+	left: 0;
+	width: $button-size-compact;
+	height: $button-size-compact;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	z-index: 1;
+	color: $gray-900;
+	fill: $gray-900;
+
+	.is-small > & {
+		width: $button-size-small;
+		height: $button-size-small;
+	}
+
+	svg {
+		width: 75%;
+		height: 75%;
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.editor-avatar.is-badge,
+	.editor-avatar__name {
+		transition: none;
+	}
+}

package/src/components/collaborators-presence/avatar/test/index.tsx

@@ -0,0 +1,389 @@
+/**
+ * External dependencies
+ */
+import { render, screen, fireEvent } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import Avatar from '..';
+
+/**
+ * In JSDOM, `<img>` elements never fire `load` or `error` events on their
+ * own. We simulate them using `fireEvent` on the `<img>` element, which we
+ * locate via `getByAltText('')` (the `<img>` has `alt=""`).
+ */
+
+describe( 'Avatar', () => {
+	it( 'should render with default props', () => {
+		render( <Avatar data-testid="avatar" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).toBeInTheDocument();
+		expect( avatar.tagName ).toBe( 'DIV' );
+		expect( avatar ).toHaveClass( 'editor-avatar' );
+	} );
+
+	it( 'should set the accessible name from the name prop', () => {
+		render( <Avatar name="Jane Doe" /> );
+		const avatar = screen.getByRole( 'img', { name: 'Jane Doe' } );
+		expect( avatar ).toBeInTheDocument();
+	} );
+
+	it( 'should not set role or aria-label without a name', () => {
+		render( <Avatar data-testid="avatar" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).not.toHaveAttribute( 'role' );
+		expect( avatar ).not.toHaveAttribute( 'aria-label' );
+	} );
+
+	it( 'should render an img element when src is provided', () => {
+		render(
+			<Avatar
+				data-testid="avatar"
+				name="Jane Doe"
+				src="https://example.com/avatar.jpg"
+			/>
+		);
+		// The <img> should be in the DOM (hidden until loaded).
+		const img = screen.getByAltText( '' );
+		expect( img.tagName ).toBe( 'IMG' );
+		expect( img ).toHaveAttribute(
+			'src',
+			'https://example.com/avatar.jpg'
+		);
+	} );
+
+	it( 'should apply has-src class only after image loads', () => {
+		render(
+			<Avatar
+				data-testid="avatar"
+				name="Jane Doe"
+				src="https://example.com/avatar.jpg"
+			/>
+		);
+		const avatar = screen.getByTestId( 'avatar' );
+		// Before load fires, has-src should not be set.
+		expect( avatar ).not.toHaveClass( 'has-src' );
+
+		// Simulate image load.
+		fireEvent.load( screen.getByAltText( '' ) );
+		expect( avatar ).toHaveClass( 'has-src' );
+	} );
+
+	it( 'should apply is-small class for small size', () => {
+		render( <Avatar data-testid="avatar" size="small" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).toHaveClass( 'is-small' );
+	} );
+
+	it( 'should not apply is-small class for default size', () => {
+		render( <Avatar data-testid="avatar" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).not.toHaveClass( 'is-small' );
+	} );
+
+	it( 'should apply border color when provided', () => {
+		render( <Avatar data-testid="avatar" borderColor="#3858e9" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).toHaveClass( 'has-avatar-border-color' );
+		expect(
+			avatar.style.getPropertyValue( '--editor-avatar-outline-color' )
+		).toBe( '#3858e9' );
+	} );
+
+	it( 'should set name color custom property when borderColor is provided', () => {
+		render( <Avatar data-testid="avatar" borderColor="#3858e9" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect(
+			avatar.style.getPropertyValue( '--editor-avatar-name-color' )
+		).toBeTruthy();
+	} );
+
+	it( 'should not have has-src class when src is not provided', () => {
+		render( <Avatar data-testid="avatar" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).not.toHaveClass( 'has-src' );
+	} );
+
+	it( 'should combine custom className with default class', () => {
+		render( <Avatar data-testid="avatar" className="custom" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).toHaveClass( 'editor-avatar' );
+		expect( avatar ).toHaveClass( 'custom' );
+	} );
+
+	it( 'should pass through additional HTML attributes', () => {
+		render( <Avatar data-testid="avatar" data-custom="value" /> );
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).toHaveAttribute( 'data-custom', 'value' );
+	} );
+
+	it( 'should merge style prop with custom properties', () => {
+		render(
+			<Avatar
+				data-testid="avatar"
+				borderColor="#3858e9"
+				style={ { left: '10px' } }
+			/>
+		);
+		const avatar = screen.getByTestId( 'avatar' );
+		expect( avatar ).toHaveStyle( { left: '10px' } );
+		expect(
+			avatar.style.getPropertyValue( '--editor-avatar-outline-color' )
+		).toBe( '#3858e9' );
+	} );
+
+	describe( 'variant: badge', () => {
+		it( 'should not show badge by default', () => {
+			render( <Avatar data-testid="avatar" name="Zoraya" /> );
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).not.toHaveClass( 'is-badge' );
+			expect( screen.queryByText( 'Zoraya' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'should render name span with badge variant', () => {
+			render(
+				<Avatar data-testid="avatar" name="Zoraya" variant="badge" />
+			);
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).toHaveClass( 'is-badge' );
+			expect( screen.getByText( 'Zoraya' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should render name span with borderColor too', () => {
+			render(
+				<Avatar
+					data-testid="avatar"
+					name="Zoraya"
+					borderColor="#3d5eef"
+					variant="badge"
+				/>
+			);
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).toHaveClass( 'is-badge' );
+			expect( screen.getByText( 'Zoraya' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should not show badge when name is missing', () => {
+			render( <Avatar data-testid="avatar" variant="badge" /> );
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).not.toHaveClass( 'is-badge' );
+		} );
+
+		it( 'should still set aria-label even when badge is visible', () => {
+			render( <Avatar name="Zoraya" variant="badge" /> );
+			const avatar = screen.getByRole( 'img', { name: 'Zoraya' } );
+			expect( avatar ).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'label', () => {
+		it( 'should show label text instead of name in the badge', () => {
+			render( <Avatar name="Jane Doe" label="You" variant="badge" /> );
+			expect( screen.getByText( 'You' ) ).toBeInTheDocument();
+			expect( screen.queryByText( 'Jane Doe' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'should keep aria-label as name when label is provided', () => {
+			render( <Avatar name="Jane Doe" label="You" variant="badge" /> );
+			const avatar = screen.getByRole( 'img', { name: 'Jane Doe' } );
+			expect( avatar ).toBeInTheDocument();
+		} );
+
+		it( 'should wrap in tooltip when label differs from name', () => {
+			render( <Avatar name="Jane Doe" label="You" variant="badge" /> );
+			const avatar = screen.getByRole( 'img', { name: 'Jane Doe' } );
+			// The Tooltip's Ariakit.TooltipAnchor makes the element
+			// focusable so the tooltip can be triggered via keyboard.
+			expect( avatar ).toHaveAttribute( 'tabindex', '0' );
+		} );
+	} );
+
+	describe( 'dimmed', () => {
+		it( 'should apply is-dimmed class when dimmed', () => {
+			render( <Avatar data-testid="avatar" dimmed /> );
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).toHaveClass( 'is-dimmed' );
+		} );
+
+		it( 'should not apply is-dimmed class by default', () => {
+			render( <Avatar data-testid="avatar" /> );
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).not.toHaveClass( 'is-dimmed' );
+		} );
+
+		it( 'should render statusIndicator when dimmed', () => {
+			render(
+				<Avatar
+					data-testid="avatar"
+					dimmed
+					statusIndicator={ <span>icon</span> }
+				/>
+			);
+			expect( screen.getByText( 'icon' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should not render statusIndicator when not dimmed', () => {
+			render(
+				<Avatar
+					data-testid="avatar"
+					statusIndicator={ <span>icon</span> }
+				/>
+			);
+			expect( screen.queryByText( 'icon' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'should apply has-src class when dimmed after image loads', () => {
+			render(
+				<Avatar
+					data-testid="avatar"
+					src="https://example.com/avatar.jpg"
+					dimmed
+				/>
+			);
+			fireEvent.load( screen.getByAltText( '' ) );
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).toHaveClass( 'has-src' );
+			expect( avatar ).toHaveClass( 'is-dimmed' );
+		} );
+	} );
+
+	describe( 'initials', () => {
+		it( 'should show initials when no src is provided', () => {
+			render( <Avatar name="Tanner Robinson" /> );
+			expect( screen.getByText( 'TR' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should show single initial for single-word name', () => {
+			render( <Avatar name="Zoraya" /> );
+			expect( screen.getByText( 'Z' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should limit initials to two characters', () => {
+			render( <Avatar name="Jane Marie Doe" /> );
+			expect( screen.getByText( 'JM' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should uppercase initials', () => {
+			render( <Avatar name="jane doe" /> );
+			expect( screen.getByText( 'JD' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should not show initials after image loads', () => {
+			render(
+				<Avatar
+					name="Tanner Robinson"
+					src="https://example.com/avatar.jpg"
+				/>
+			);
+			fireEvent.load( screen.getByAltText( '' ) );
+			expect( screen.queryByText( 'TR' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'should not render initials when name is not provided', () => {
+			render( <Avatar data-testid="avatar" /> );
+			const avatar = screen.getByTestId( 'avatar' );
+			// Without a name, the image span should be empty (no initials).
+			expect( avatar ).not.toHaveTextContent( /.+/ );
+		} );
+	} );
+
+	describe( 'image loading', () => {
+		it( 'should reset to loading state when src changes', () => {
+			const { rerender } = render(
+				<Avatar
+					data-testid="avatar"
+					name="Jane Doe"
+					src="https://example.com/a.jpg"
+				/>
+			);
+			fireEvent.load( screen.getByAltText( '' ) );
+			expect( screen.getByTestId( 'avatar' ) ).toHaveClass( 'has-src' );
+
+			rerender(
+				<Avatar
+					data-testid="avatar"
+					name="Jane Doe"
+					src="https://example.com/b.jpg"
+				/>
+			);
+			// New src should reset to loading — initials visible again.
+			expect( screen.getByTestId( 'avatar' ) ).not.toHaveClass(
+				'has-src'
+			);
+			expect( screen.getByText( 'JD' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should show initials while image is loading', () => {
+			render(
+				<Avatar
+					data-testid="avatar"
+					name="Jane Doe"
+					src="https://example.com/avatar.jpg"
+				/>
+			);
+			const avatar = screen.getByTestId( 'avatar' );
+			// Before load event, initials should show.
+			expect( avatar ).not.toHaveClass( 'has-src' );
+			expect( screen.getByText( 'JD' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should show image after successful load', () => {
+			render(
+				<Avatar
+					data-testid="avatar"
+					name="Jane Doe"
+					src="https://example.com/avatar.jpg"
+				/>
+			);
+
+			fireEvent.load( screen.getByAltText( '' ) );
+
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).toHaveClass( 'has-src' );
+			expect( screen.queryByText( 'JD' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'should fall back to initials when image fails to load', () => {
+			render(
+				<Avatar
+					data-testid="avatar"
+					name="Jane Doe"
+					src="https://example.com/bad.jpg"
+				/>
+			);
+
+			fireEvent.error( screen.getByAltText( '' ) );
+
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).not.toHaveClass( 'has-src' );
+			expect( screen.getByText( 'JD' ) ).toBeInTheDocument();
+		} );
+
+		it( 'should not render img element when no src is provided', () => {
+			render( <Avatar data-testid="avatar" name="Jane Doe" /> );
+			expect( screen.queryByAltText( '' ) ).not.toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'tooltip', () => {
+		it( 'should wrap in tooltip when name is provided without badge', () => {
+			render( <Avatar name="Jane Doe" /> );
+			const avatar = screen.getByRole( 'img', { name: 'Jane Doe' } );
+			expect( avatar ).toHaveAttribute( 'tabindex', '0' );
+		} );
+
+		it( 'should not wrap in tooltip for badge without label', () => {
+			render( <Avatar name="Jane Doe" variant="badge" /> );
+			const avatar = screen.getByRole( 'img', { name: 'Jane Doe' } );
+			// Badge shows the name visibly, so no tooltip needed.
+			expect( avatar ).not.toHaveAttribute( 'tabindex' );
+		} );
+
+		it( 'should not wrap in tooltip when name is not provided', () => {
+			render( <Avatar data-testid="avatar" /> );
+			const avatar = screen.getByTestId( 'avatar' );
+			expect( avatar ).not.toHaveAttribute( 'tabindex' );
+		} );
+	} );
+} );

package/src/components/collaborators-presence/avatar/types.ts

@@ -0,0 +1,66 @@
+import type { IconType } from '@wordpress/components';
+
+export type AvatarProps = {
+	/**
+	 * URL of the avatar image.
+	 *
+	 * When not provided, initials derived from `name` are shown.
+	 */
+	src?: string;
+	/**
+	 * Name of the user. Used as an accessible label and to generate
+	 * initials when no image is provided.
+	 */
+	name?: string;
+	/**
+	 * Visible text shown in the hover badge. When not provided, `name`
+	 * is used instead. Use this to provide contextual labels like "You"
+	 * without affecting the accessible name or initials.
+	 */
+	label?: string;
+	/**
+	 * Specifies the avatar's visual style treatment.
+	 *
+	 * - `'badge'`: Displays a hover-expand pill that reveals the user's
+	 *   name (or `label`) on hover. Requires `name` to be set.
+	 *
+	 * Leave undefined for the default circular avatar.
+	 */
+	variant?: 'badge';
+	/**
+	 * Size of the avatar.
+	 *
+	 * - `'default'`: For standalone avatars and list items where the
+	 *   avatar is a primary visual element (e.g. collaborator lists,
+	 *   user profiles).
+	 * - `'small'`: For inline or compact contexts where space is
+	 *   limited (e.g. cursor labels, toolbars, badges alongside text).
+	 *
+	 * @default 'default'
+	 */
+	size?: 'default' | 'small';
+	/**
+	 * CSS color value for an accent border ring around the avatar.
+	 *
+	 * When not provided, no border is rendered and the hover badge
+	 * uses the admin theme color as its background.
+	 */
+	borderColor?: string;
+	/**
+	 * Whether to dim the avatar to indicate an inactive or away state.
+	 * When true, images are desaturated and faded, and initials are
+	 * reduced in opacity.
+	 *
+	 * @default false
+	 */
+	dimmed?: boolean;
+	/**
+	 * An icon or custom component rendered as a centered overlay on the
+	 * avatar image. Only visible when `dimmed` is true.
+	 *
+	 * Accepts any value supported by the `Icon` component: an icon from
+	 * `@wordpress/icons`, a Dashicon name string, a component, or a
+	 * JSX element.
+	 */
+	statusIndicator?: IconType | null;
+};

package/src/components/collaborators-presence/avatar/use-image-loading-status.ts

@@ -0,0 +1,36 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useState } from '@wordpress/element';
+
+export type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
+
+/**
+ * Tracks the loading status of an image URL. Returns the current status and
+ * `onLoad`/`onError` callbacks to attach to the `<img>` element.
+ *
+ * Unlike a side-channel `new Image()` preloader, this hook relies on the
+ * native `<img>` element's own events, which avoids cross-browser issues
+ * with Safari's privacy features blocking programmatic image requests.
+ *
+ * @param src - The image URL. When falsy, status is `'idle'`.
+ */
+export function useImageLoadingStatus( src?: string ) {
+	const [ prevSrc, setPrevSrc ] = useState( src );
+	const [ status, setStatus ] = useState< ImageLoadingStatus >(
+		src ? 'loading' : 'idle'
+	);
+
+	// Synchronous reset when src changes — runs during render, not after
+	// commit, so a cached image's `load` event cannot sneak in before
+	// the reset and get overwritten.
+	if ( prevSrc !== src ) {
+		setPrevSrc( src );
+		setStatus( src ? 'loading' : 'idle' );
+	}
+
+	const handleLoad = useCallback( () => setStatus( 'loaded' ), [] );
+	const handleError = useCallback( () => setStatus( 'error' ), [] );
+
+	return { status, handleLoad, handleError };
+}