newspack-components 4.2.0 → 4.3.0

package/dist/esm/wizard/components/WizardSnackbar.js

@@ -0,0 +1,64 @@
+/**
+ * Snackbar.
+ */
+
+/**
+ * WordPress dependencies.
+ */
+import { Snackbar as BaseComponent } from '@wordpress/components';
+import { useDispatch } from '@wordpress/data';
+
+/**
+ * Internal dependencies.
+ */
+import { WIZARD_STORE_NAMESPACE } from '../store';
+import './style.scss';
+
+/**
+ * External dependencies.
+ */
+import classnames from 'classnames';
+
+/**
+ * WizardSnackbar component.
+ *
+ * @param {Object}      props          - The component props.
+ * @param {Object[]}    props.actions  - The actions to display in the snackbar.
+ * @param {JSX.Element} props.children - The component children.
+ * @param {Object}      props.props    - The component props. See: https://wordpress.github.io/gutenberg/?path=/docs/components-snackbar--docs
+ * @param {string}      props.position - The snackbar position.
+ * @param {string}      props.type     - The snackbar type: 'info', 'success', 'warning', or 'error'.
+ * @return {JSX.Element} The component.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+const WizardSnackbar = ({
+  children,
+  position = 'bottom-left',
+  type = 'info',
+  actions = [],
+  ...props
+}) => {
+  const className = classnames('newspack-wizard__snackbar', props.className, `newspack-wizard__snackbar--${position}`, `newspack-wizard__snackbar--${type}`);
+  const {
+    removeNotice,
+    resetNotices
+  } = useDispatch(WIZARD_STORE_NAMESPACE);
+  const onRemove = () => {
+    if (props.onRemove) {
+      props.onRemove();
+    }
+    if (props.id) {
+      removeNotice(props.id);
+    } else {
+      resetNotices();
+    }
+  };
+  return /*#__PURE__*/_jsx(BaseComponent, {
+    className: className,
+    ...props,
+    onRemove: onRemove,
+    actions: actions,
+    children: children
+  });
+};
+export default WizardSnackbar;

package/dist/esm/wizard/components/style.scss

@@ -0,0 +1,48 @@
+.newspack-wizard {
+	&__snackbar {
+		border-bottom: 2px solid transparent;
+		bottom: 16px;
+		left: 16px;
+		max-width: calc(100vw - 32px);
+		position: fixed;
+		z-index: 99999;
+		&--success {
+			border-color: var(--newspack-ui-color-success-60);
+		}
+		&--error {
+			border-color: var(--newspack-ui-color-error-60);
+		}
+		&--warning {
+			border-color: var(--newspack-ui-color-warning-40);
+		}
+		@media screen and ( min-width: 783px ) {
+			left: calc(36px + 16px); /* 36px for admin menu bar */
+		}
+		@media screen and ( min-width: 960px ) {
+			left: calc(160px + 16px); /* 160px for admin menu bar */
+		}
+		&.newspack-wizard__snackbar--bottom-right,
+		&.newspack-wizard__snackbar--top-right {
+			left: auto;
+			right: calc(16px);
+		}
+		&.newspack-wizard__snackbar--top-left,
+		&.newspack-wizard__snackbar--top-right {
+			bottom: auto;
+			top: calc(16px + 46px); /* 46px for admin bar */
+			@media screen and ( min-width: 783px ) {
+				top: calc(16px + 32px); /* 32px for admin bar */
+			}
+		}
+		a,
+		.components-button.is-link {
+			color: var(--newspack-ui-color-neutral-0);
+			cursor: pointer;
+			margin-left: 16px;
+			&:hover,
+			&:focus {
+				color: var(--newspack-ui-color-neutral-10);
+			}
+		}
+	}
+}

package/dist/esm/wizard/index.js

@@ -6,17 +6,19 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies.
  */
-import { useSelect } from '@wordpress/data';
-import { useState, forwardRef } from '@wordpress/element';
+import { DropdownMenu, MenuItem } from '@wordpress/components';
+import { useDispatch, useSelect } from '@wordpress/data';
+import { useEffect, useState, forwardRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
-import { category } from '@wordpress/icons';
+import { category, moreVertical } from '@wordpress/icons';
 
 /**
  * Internal dependencies
  */
-import { Footer, Notice, Button, NewspackIcon, TabbedNavigation, PluginInstaller, HandoffMessage } from '../';
+import { Footer, Notice, Button, NewspackIcon, TabbedNavigation, PluginInstaller, SectionHeader, HandoffMessage } from '../';
 import Router from '../proxied-imports/router';
 import registerStore, { WIZARD_STORE_NAMESPACE } from './store';
+import WizardSnackbar from './components/WizardSnackbar';
 import WizardError from './components/WizardError';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 registerStore();
@@ -24,9 +26,24 @@ const {
   HashRouter,
   Redirect,
   Route,
-  Switch
+  Switch,
+  useLocation
 } = Router;
 
+/**
+ * Reset the header data when a new section is rendered.
+ */
+const ResetHeaderData = () => {
+  const location = useLocation();
+  const {
+    resetHeaderData
+  } = useDispatch(WIZARD_STORE_NAMESPACE);
+  useEffect(() => {
+    resetHeaderData();
+  }, [location.pathname, resetHeaderData]);
+  return null;
+};
+
 /**
  * @typedef  {Object}     WizardProps
  * @property {string}     headerText                The header text.
@@ -52,15 +69,31 @@ const Wizard = ({
   sections = [],
   headerText,
   apiSlug,
+  sharedProps = {},
   subHeaderText,
   hasSimpleFooter,
   className,
   renderAboveSections,
   requiredPlugins = [],
-  isInitialFetchTriggered = true
+  isInitialFetchTriggered = true,
+  fixedHeader = false
 }, ref) => {
   const isLoading = useSelect(select => select(WIZARD_STORE_NAMESPACE).isLoading());
   const isQuietLoading = useSelect(select => select(WIZARD_STORE_NAMESPACE).isQuietLoading());
+  const headerData = useSelect(select => select(WIZARD_STORE_NAMESPACE).getHeaderData());
+  const notices = useSelect(select => select(WIZARD_STORE_NAMESPACE).getNotices());
+  const {
+    actions,
+    backNav,
+    badges,
+    sectionDescription,
+    sectionName,
+    sectionTitle,
+    sectionPrimaryAction,
+    sectionSecondaryAction
+  } = headerData;
+  const mainActions = actions?.filter(action => action.type === 'primary' || action.type === 'secondary');
+  const moreActions = actions?.filter(action => action.type === 'more');
 
   // Trigger initial data fetch. Some sections might not use the wizard data,
   // but for consistency, fetching is triggered regardless of the section.
@@ -82,17 +115,18 @@ const Wizard = ({
   const urlWithoutHash = window.location.href.split('#')[0];
   return /*#__PURE__*/_jsxs("div", {
     ref: ref,
-    children: [/*#__PURE__*/_jsx("div", {
+    children: [/*#__PURE__*/_jsxs("div", {
       className: classnames(isLoading ? 'newspack-wizard__is-loading' : 'newspack-wizard__is-loaded', {
-        'newspack-wizard__is-loading-quiet': isQuietLoading
+        'newspack-wizard__is-loading-quiet': isQuietLoading,
+        'newspack-wizard__fixed-header': fixedHeader
       }),
-      children: /*#__PURE__*/_jsxs(HashRouter, {
+      children: [/*#__PURE__*/_jsxs(HashRouter, {
         hashType: "slash",
         children: [newspack_aux_data.is_debug_mode && /*#__PURE__*/_jsx(Notice, {
           debugMode: true
-        }), /*#__PURE__*/_jsx("div", {
-          className: "bg-white",
-          children: /*#__PURE__*/_jsx("div", {
+        }), /*#__PURE__*/_jsxs("div", {
+          className: "newspack-wizard__header",
+          children: [/*#__PURE__*/_jsx("div", {
             className: "newspack-wizard__header__inner",
             children: /*#__PURE__*/_jsxs("div", {
               className: "newspack-wizard__title",
@@ -109,34 +143,81 @@ const Wizard = ({
               }) : /*#__PURE__*/_jsx(NewspackIcon, {
                 size: 36
               }), /*#__PURE__*/_jsxs("div", {
-                children: [headerText && /*#__PURE__*/_jsx("h2", {
-                  children: headerText
+                children: [headerText && /*#__PURE__*/_jsxs("h2", {
+                  className: "newspack-wizard__header__title",
+                  children: [headerText, sectionName && /*#__PURE__*/_jsxs("span", {
+                    className: "newspack-wizard__header__section",
+                    children: [/*#__PURE__*/_jsx("span", {
+                      className: "newspack-wizard__header__section__separator",
+                      children: " / "
+                    }), " ", sectionName]
+                  })]
                 }), subHeaderText && /*#__PURE__*/_jsx("span", {
                   children: subHeaderText
                 })]
               })]
             })
-          })
+          }), actions?.length > 0 && /*#__PURE__*/_jsxs("div", {
+            className: "newspack-wizard__header__actions",
+            children: [mainActions.map((action, index) => /*#__PURE__*/_jsx(Button, {
+              icon: action.icon,
+              variant: action.type,
+              onClick: action.action,
+              disabled: action.disabled || false,
+              isDestructive: action.destructive || false,
+              children: action.label
+            }, index)), moreActions.length > 0 && /*#__PURE__*/_jsx(DropdownMenu, {
+              icon: moreVertical,
+              label: __('More', 'newspack-plugin'),
+              children: () => moreActions.map((action, index) => /*#__PURE__*/_jsx(MenuItem, {
+                icon: action.icon,
+                onClick: action.action,
+                disabled: action.disabled || false,
+                isDestructive: action.destructive || false,
+                children: action.label
+              }, index))
+            })]
+          })]
         }), displayedSections.length > 1 && /*#__PURE__*/_jsx(TabbedNavigation, {
           items: displayedSections,
           children: /*#__PURE__*/_jsx(WizardError, {})
-        }), /*#__PURE__*/_jsx(HandoffMessage, {}), /*#__PURE__*/_jsxs(Switch, {
-          children: [displayedSections.map((section, index) => {
+        }), /*#__PURE__*/_jsx(HandoffMessage, {}), sections.length > 1 && /*#__PURE__*/_jsx(ResetHeaderData, {}), /*#__PURE__*/_jsxs(Switch, {
+          children: [sections.map((section, index) => {
             var _section$exact;
             const SectionComponent = section.render;
+            const sectionProps = section.props || {};
             return /*#__PURE__*/_jsx(Route, {
               exact: (_section$exact = section.exact) !== null && _section$exact !== void 0 ? _section$exact : false,
               path: section.path,
-              children: /*#__PURE__*/_jsxs("div", {
+              render: routerProps => /*#__PURE__*/_jsxs("div", {
                 className: classnames('newspack-wizard__content', className),
-                children: ['function' === typeof renderAboveSections ? renderAboveSections() : null, /*#__PURE__*/_jsx(SectionComponent, {})]
+                children: ['function' === typeof renderAboveSections ? renderAboveSections() : null, (sectionTitle || section.title) && /*#__PURE__*/_jsx(SectionHeader, {
+                  className: "newspack-wizard__section-header",
+                  backNav: backNav || section.backNav,
+                  title: sectionTitle || section.title,
+                  description: sectionDescription || section.description,
+                  badges: badges || section.badges,
+                  primaryAction: sectionPrimaryAction || section.primaryAction,
+                  secondaryAction: sectionSecondaryAction || section.secondaryAction,
+                  heading: 1,
+                  noMargin: true
+                }), /*#__PURE__*/_jsx(SectionComponent, {
+                  ...routerProps,
+                  ...sectionProps,
+                  ...sharedProps
+                })]
               })
             }, index);
           }), /*#__PURE__*/_jsx(Redirect, {
             to: displayedSections[0].path
           })]
         })]
-      })
+      }), notices?.length > 0 && notices.map((notice, index) => /*#__PURE__*/_jsx(WizardSnackbar, {
+        type: notice.type,
+        id: notice.id,
+        actions: notice.actions,
+        children: notice.message
+      }, notice.id || index))]
     }), !isLoading && /*#__PURE__*/_jsx(Footer, {
       simple: hasSimpleFooter
     })]

package/dist/esm/wizard/store/index.js

@@ -13,9 +13,18 @@ import { createReduxStore, register, dispatch, select } from '@wordpress/data';
 import { createAction } from './utils.js';
 export const WIZARD_STORE_NAMESPACE = 'newspack/wizards';
 const DEFAULT_STATE = {
+  headerData: {
+    actions: [],
+    backNav: '',
+    badges: [],
+    sectionDescription: '',
+    sectionName: '',
+    sectionTitle: ''
+  },
   isLoading: false,
   isQuietLoading: false,
   apiData: {},
+  notices: [],
   error: null
 };
 
@@ -30,6 +39,21 @@ const reducer = (state = DEFAULT_STATE, {
   payload = {}
 }) => {
   switch (type) {
+    case 'SET_HEADER_DATA':
+      return {
+        ...state,
+        headerData: {
+          ...state.headerData,
+          ...payload
+        }
+      };
+    case 'RESET_HEADER_DATA':
+      return {
+        ...state,
+        headerData: {
+          ...DEFAULT_STATE.headerData
+        }
+      };
     case 'START_LOADING_DATA':
       if (payload.isQuietLoading) {
         return {
@@ -51,22 +75,42 @@ const reducer = (state = DEFAULT_STATE, {
       return set(clone(state), ['apiData', payload.slug], payload.data);
     case 'UPDATE_WIZARD_SETTINGS':
       return set(clone(state), ['apiData', payload.slug, ...payload.path], payload.value);
+    case 'ADD_NOTICE':
+      return {
+        ...state,
+        notices: [...state.notices, payload]
+      };
+    case 'REMOVE_NOTICE':
+      return {
+        ...state,
+        notices: state.notices.filter(notice => notice.id !== payload)
+      };
     case 'SET_ERROR':
       return {
         ...state,
         error: payload
       };
+    case 'RESET_NOTICES':
+      return {
+        ...state,
+        notices: DEFAULT_STATE.notices
+      };
     default:
       return state;
   }
 };
 const actions = {
   // Regular actions.
+  setHeaderData: createAction('SET_HEADER_DATA'),
+  resetHeaderData: createAction('RESET_HEADER_DATA'),
   startLoadingData: createAction('START_LOADING_DATA'),
   finishLoadingData: createAction('FINISH_LOADING_DATA'),
   fetchFromAPI: createAction('FETCH_FROM_API'),
   setAPIDataForWizard: createAction('SET_API_DATA'),
   updateWizardSettings: createAction('UPDATE_WIZARD_SETTINGS'),
+  addNotice: createAction('ADD_NOTICE'),
+  removeNotice: createAction('REMOVE_NOTICE'),
+  resetNotices: createAction('RESET_NOTICES'),
   setError: createAction('SET_ERROR'),
   // Async actions. These will not show up in Redux devtools.
   *saveWizardSettings({
@@ -109,6 +153,7 @@ const actions = {
   }
 };
 const selectors = {
+  getHeaderData: state => state.headerData,
   isLoading: state => state.isLoading,
   isQuietLoading: state => state.isQuietLoading,
   getWizardAPIData: (state, slug) => state.apiData[slug] || {},
@@ -116,6 +161,7 @@ const selectors = {
     var _state$apiData$slug;
     return (_state$apiData$slug = state.apiData[slug]) !== null && _state$apiData$slug !== void 0 ? _state$apiData$slug : {};
   },
+  getNotices: state => state.notices,
   getError: state => state.error
 };
 const store = createReduxStore(WIZARD_STORE_NAMESPACE, {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "newspack-components",
-	"version": "4.2.0",
+	"version": "4.3.0",
 	"description": "Newspack design system components",
 	"author": "Automattic",
 	"license": "GPL-2.0-or-later",
@@ -23,16 +23,15 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@wordpress/base-styles": "^5.0.0",
-		"@wordpress/components": "^28.0.0",
+		"@wordpress/base-styles": "^6.0.0",
+		"@wordpress/components": "^32.0.0",
 		"@wordpress/element": "^6.0.0",
-		"@wordpress/i18n": "^5.0.0",
-		"@wordpress/icons": "^10.0.0",
+		"@wordpress/i18n": "^6.0.0",
+		"@wordpress/icons": "^11.0.0",
 		"classnames": "^2.3.1",
 		"lodash": "^4.17.21",
 		"moment-range": "^3.1.1",
 		"qs": "^6.10.1",
-		"react-daterange-picker": "^2.0.1",
 		"react-router-dom": "^5.3.4"
 	},
 	"devDependencies": {

package/shared/author-context.js

@@ -0,0 +1,26 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext } from '@wordpress/element';
+
+/**
+ * Window global key used by newspack-blocks to expose the shared AuthorContext.
+ *
+ * @type {string}
+ */
+export const AUTHOR_CONTEXT_KEY = 'NewspackAuthorContext';
+
+/**
+ * Fallback context that always returns null.
+ * Used when the shared AuthorContext from newspack-blocks is not available.
+ */
+const FallbackAuthorContext = createContext( null );
+
+/**
+ * Get the shared AuthorContext from newspack-blocks if available, otherwise use fallback.
+ * Resolved at render time (not module load) so it works regardless of script load order.
+ *
+ * @return {Object} React context object.
+ */
+export const getSharedAuthorContext = () =>
+	typeof window !== 'undefined' && window[ AUTHOR_CONTEXT_KEY ] ? window[ AUTHOR_CONTEXT_KEY ] : FallbackAuthorContext;

package/shared/hooks/use-coauthors.js

@@ -0,0 +1,220 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect } from '@wordpress/data';
+import { useState, useEffect, useMemo } from '@wordpress/element';
+import { store as coreStore } from '@wordpress/core-data';
+import apiFetch from '@wordpress/api-fetch';
+
+/**
+ * CoAuthors Plus store name.
+ */
+const CAP_STORE = 'cap/authors';
+const COAUTHORS_ENDPOINT = '/coauthors/v1/coauthors';
+
+// Module-level cache for guest author avatar URLs, keyed by user_nicename.
+// Prevents duplicate REST requests when components re-mount or when
+// multiple avatar blocks in a Query Loop share the same guest authors.
+const guestAvatarCache = {};
+
+// In-flight request promises, keyed by user_nicename.
+// Prevents duplicate concurrent requests when multiple block instances
+// mount simultaneously (e.g. Query Loop) and all check the cache before
+// any fetch has completed.
+const inflightRequests = {};
+
+/**
+ * Fetch a single coauthor's avatar URLs, deduplicating concurrent requests.
+ *
+ * @param {string} nicename Author nicename (slug).
+ * @return {Promise} Resolves when the fetch completes (result is stored in guestAvatarCache).
+ */
+function fetchCoauthorAvatar( nicename ) {
+	if ( nicename in guestAvatarCache ) {
+		return Promise.resolve();
+	}
+	if ( inflightRequests[ nicename ] ) {
+		return inflightRequests[ nicename ];
+	}
+	inflightRequests[ nicename ] = apiFetch( {
+		path: `${ COAUTHORS_ENDPOINT }/${ encodeURIComponent( nicename ) }`,
+	} )
+		.then( result => {
+			guestAvatarCache[ nicename ] = result?.avatar_urls || false;
+		} )
+		.catch( () => {
+			guestAvatarCache[ nicename ] = false;
+		} )
+		.finally( () => {
+			delete inflightRequests[ nicename ];
+		} );
+	return inflightRequests[ nicename ];
+}
+
+/**
+ * Reset the module-level guest avatar cache. Exposed for testing only.
+ */
+export function resetGuestAvatarCacheForTests() {
+	Object.keys( guestAvatarCache ).forEach( key => delete guestAvatarCache[ key ] );
+	Object.keys( inflightRequests ).forEach( key => delete inflightRequests[ key ] );
+}
+
+/**
+ * Extract user_nicename from an author archive URL.
+ *
+ * @param {string} link Author archive URL (e.g. /author/jane/).
+ * @return {string|undefined} Extracted nicename, or undefined.
+ */
+function extractNicenameFromLink( link ) {
+	if ( ! link ) {
+		return undefined;
+	}
+	const cleaned = link.split( '?' )[ 0 ].split( '#' )[ 0 ].replace( /\/$/, '' );
+	const segments = cleaned.split( '/' );
+	const slug = segments.pop();
+	// Require a parent path segment so root URLs and plain permalinks are rejected.
+	const parent = segments[ segments.length - 1 ];
+	if ( ! slug || ! parent ) {
+		return undefined;
+	}
+	return slug;
+}
+
+/**
+ * Hook to get CoAuthors Plus authors from the CAP store or REST API.
+ *
+ * For the currently-edited post, it uses CAP's JS store for real-time updates.
+ * For Query Loop posts, it uses REST API data since CAP's store only works for the
+ * currently-edited post.
+ *
+ * @param {number}  postId   Post ID to get authors for.
+ * @param {string}  postType Post type (default: 'post').
+ * @param {boolean} skip     Skip fetching (default: false).
+ * @return {Object} Authors array and availability state.
+ */
+export function useCoAuthors( postId, postType = 'post', skip = false ) {
+	// Return raw store references from useSelect to avoid creating new objects
+	// on every render (which triggers useSelect memoization warnings).
+	// The .map() transformations happen in useMemo below.
+	const { capAuthors, restAuthors, isCapAvailable } = useSelect(
+		select => {
+			if ( skip ) {
+				return { capAuthors: null, restAuthors: null, isCapAvailable: false };
+			}
+
+			const capStore = select( CAP_STORE );
+			const isCapStoreAvailable = Boolean( capStore && typeof capStore.getAuthors === 'function' );
+
+			const editorStore = select( 'core/editor' );
+			const currentPostId = editorStore?.getCurrentPostId?.();
+			const isQueryLoopContext = postId && currentPostId && postId !== currentPostId;
+
+			// For the currently-edited post, use CAP's store for real-time updates.
+			if ( isCapStoreAvailable && ! isQueryLoopContext ) {
+				const rawCapAuthors = postId ? capStore.getAuthors( postId ) : null;
+				return { capAuthors: rawCapAuthors, restAuthors: null, isCapAvailable: true };
+			}
+
+			// For Query Loop context, try to get coauthors from REST API.
+			// If REST author data exists, treat CAP as available (matching original behavior)
+			// since the server-side plugin provided the data even if the JS store isn't loaded.
+			if ( isQueryLoopContext && postId ) {
+				const { getEntityRecord } = select( coreStore );
+				const post = getEntityRecord( 'postType', postType, postId );
+				const restData = post?.newspack_author_info || null;
+				return { capAuthors: null, restAuthors: restData, isCapAvailable: restData ? true : isCapStoreAvailable };
+			}
+
+			return { capAuthors: null, restAuthors: null, isCapAvailable: isCapStoreAvailable };
+		},
+		[ postId, postType, skip ]
+	);
+
+	// Map raw store data to our normalized author format.
+	const authors = useMemo( () => {
+		// CAP store authors: { id, label, display, value, userType }
+		if ( capAuthors && capAuthors.length > 0 ) {
+			return capAuthors.map( author => ( {
+				id: author.id,
+				display_name: author.display || author.value || author.label,
+				user_nicename: author.value,
+				isGuest: author.userType === 'guest-author',
+			} ) );
+		}
+
+		// REST API authors from newspack_author_info.
+		if ( restAuthors && Array.isArray( restAuthors ) && restAuthors.length > 0 ) {
+			return restAuthors.map( author => ( {
+				id: author.id,
+				display_name: author.display_name,
+				author_link: author.author_link,
+				user_nicename: author.user_nicename || extractNicenameFromLink( author.author_link ),
+				...( typeof author.is_guest === 'boolean' ? { isGuest: author.is_guest } : {} ),
+				...( author.avatar_urls ? { avatar_urls: author.avatar_urls } : {} ),
+			} ) );
+		}
+
+		return [];
+	}, [ capAuthors, restAuthors ] );
+
+	// Fetch avatar URLs from the CAP REST API for authors that need it.
+	// The CAP store strips avatar data via formatAuthorData(), so we need
+	// to fetch the raw REST response to get the avatar URL (especially for
+	// guest authors whose avatars come from featured images).
+	//
+	// Fetches per-author (by nicename) instead of per-post so that avatars
+	// resolve immediately when a guest author is added — before the post is saved.
+	//
+	// For currently-edited post authors, isGuest is explicitly true/false.
+	// For Query Loop authors, isGuest is undefined (we can't distinguish from
+	// REST data alone), so we fetch for all of them and let the consumer
+	// (hooks.js) prefer WP user data when available.
+	const [ avatarMap, setAvatarMap ] = useState( {} );
+
+	// Build a stable key from author nicenames to control effect re-runs.
+	// isGuest !== false: includes guest authors (true) and Query Loop authors (undefined),
+	// but excludes known WP users from the currently-edited post (false).
+	const authorsNeedingAvatars = authors.filter( author => author.isGuest !== false && author.user_nicename && ! author.avatar_urls );
+	const avatarNicenames = authorsNeedingAvatars.map( author => author.user_nicename ).join( ',' );
+
+	useEffect( () => {
+		if ( skip || ! isCapAvailable || ! avatarNicenames ) {
+			return;
+		}
+
+		let cancelled = false;
+		Promise.all( authorsNeedingAvatars.map( a => fetchCoauthorAvatar( a.user_nicename ) ) ).then( () => {
+			if ( cancelled ) {
+				return;
+			}
+			const map = {};
+			authorsNeedingAvatars.forEach( a => {
+				if ( guestAvatarCache[ a.user_nicename ] ) {
+					map[ a.id ] = guestAvatarCache[ a.user_nicename ];
+				}
+			} );
+			setAvatarMap( map );
+		} );
+
+		return () => {
+			cancelled = true;
+		};
+	}, [ skip, isCapAvailable, avatarNicenames ] );
+
+	// Merge avatar URLs into guest authors.
+	// Check both the async avatarMap (populated by the effect) and the
+	// synchronous guestAvatarCache (populated by previous fetches) so that
+	// cached avatars render immediately without waiting for an effect cycle.
+	const authorsWithAvatars = authors.map( author => {
+		if ( author.isGuest === false || ! author.user_nicename ) {
+			return author;
+		}
+		const urls = avatarMap[ author.id ] || guestAvatarCache[ author.user_nicename ];
+		if ( ! urls ) {
+			return author;
+		}
+		return { ...author, avatar_urls: urls };
+	} );
+
+	return { authors: authorsWithAvatars, isCapAvailable };
+}