A4A MSD: address overview cards review feedback

- Use the Heading component for the card titles.
- Rename useRouterLink to shouldUseRouterLink; the prefix read as a hook.
- Lock the earning cards for members without the referrals capability,
  which also gates the WooPayments routes today.
- Stop counting attached licenses without a blog as a store.
- Keep the store-count queries from refetching on focus, matching the
  WooPayments dashboard, and describe the de-duplication accurately.
- Hide the event card once the event's end date passes.
- Let SummaryButton accept target and rel, and replace the helpful-links
  click interception with real new-tab anchors.
- Note why the earning cards don't render through OverviewCard.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: yashwin

client/dashboard/agency/overview/event-card.tsx

@@ -1,5 +1,6 @@
 import {
 	Button,
+	__experimentalHeading as Heading,
 	__experimentalHStack as HStack,
 	__experimentalVStack as VStack,
 } from '@wordpress/components';
@@ -15,7 +16,7 @@ interface EventCardProps {
 }
 
 export default function EventCard( { recordTracksEvent }: EventCardProps ) {
-	if ( ! FEATURED_EVENT ) {
+	if ( ! FEATURED_EVENT || new Date() >= new Date( FEATURED_EVENT.endsAt ) ) {
 		return null;
 	}
 
@@ -31,9 +32,9 @@ export default function EventCard( { recordTracksEvent }: EventCardProps ) {
 							<Text variant="muted" size={ 11 } weight={ 500 } lineHeight="16px" upperCase>
 								{ when }
 							</Text>
-							<Text size={ 15 } weight={ 500 } lineHeight="20px" as="h2">
+							<Heading level={ 2 } size={ 15 } weight={ 500 } lineHeight="20px">
 								{ title }
-							</Text>
+							</Heading>
 							<Text variant="muted" size={ 12 } lineHeight="16px">
 								{ subtitle }
 							</Text>

client/dashboard/agency/overview/events.ts

@@ -16,13 +16,15 @@ export interface FeaturedEvent {
 	description: string[];
 	ctaLabel: string;
 	url: string;
+	/** ISO date the card stops showing itself, typically the day after the event. */
+	endsAt: string;
 }
 
 /**
  * The event promoted on the agency overview, curated by hand.
  *
- * Replace the whole object when the next event comes round, and set it to `null`
- * in between — the card hides itself rather than advertising a past event. The
+ * Replace the whole object when the next event comes round — the card hides
+ * itself once `endsAt` passes rather than advertising a past event. The
  * legacy list lives in client/a8c-for-agencies/sections/overview/body/events.
  */
 export const FEATURED_EVENT: FeaturedEvent | null = {
@@ -42,4 +44,5 @@ export const FEATURED_EVENT: FeaturedEvent | null = {
 	],
 	ctaLabel: __( 'Get your spot!' ),
 	url: 'https://us.wordcamp.org/2026/',
+	endsAt: '2026-08-20',
 };

client/dashboard/agency/overview/helpful-links-card.tsx

@@ -8,7 +8,7 @@ export interface HelpfulLink {
 	id: string;
 	label: string;
 	href?: string;
-	/** Opens in a new tab. `SummaryButton` has no `target`, so the click is handled here. */
+	/** Opens the link in a new tab. */
 	isExternal?: boolean;
 	onClick?: () => void;
 }
@@ -32,23 +32,13 @@ export default function HelpfulLinksCard( { links, recordTracksEvent }: HelpfulL
 						)
 					}
 					href={ link.href }
+					target={ link.isExternal ? '_blank' : undefined }
+					rel={ link.isExternal ? 'noreferrer' : undefined }
 					showArrow={ false }
-					onClick={ ( event ) => {
+					onClick={ () => {
 						recordTracksEvent?.( 'calypso_a4a_overview_helpful_link_click', {
 							link_id: link.id,
 						} );
-						// Leave modifier clicks to the browser so they keep their native
-						// new-tab and new-window behavior.
-						if (
-							link.isExternal &&
-							link.href &&
-							! event.metaKey &&
-							! event.ctrlKey &&
-							! event.shiftKey
-						) {
-							event.preventDefault();
-							window.open( link.href, '_blank', 'noreferrer' );
-						}
 						link.onClick?.();
 					} }
 				/>

client/dashboard/agency/overview/index.tsx

@@ -68,6 +68,7 @@ export default function AgencyOverview() {
 				tierId={ agency.tier?.id }
 				influencedRevenue={ agency.influenced_revenue ?? 0 }
 				approvalStatus={ approvalStatus }
+				capabilities={ agency.user?.capabilities }
 				links={ {
 					tiers: '/agency/tiers',
 					referrals: '/earn/referrals',

client/dashboard/agency/overview/overview-content.tsx

@@ -11,6 +11,10 @@ import type { HelpfulLink } from './helpful-links-card';
 import type { AgencyTierType, RecordTracksEvent } from '../tiers/types';
 import type { AgencyApprovalStatus } from '@automattic/api-core';
 
+// The WooPayments routes gate on the referrals capability too (see
+// a8c-for-agencies/lib/permission.ts), so one capability locks both earning cards.
+const REFERRALS_CAPABILITY = 'a4a_read_referrals';
+
 export interface AgencyOverviewLinks {
 	tiers: string;
 	referrals: string;
@@ -25,8 +29,10 @@ export interface AgencyOverviewContentProps {
 	influencedRevenue: number;
 	/** Agencies predating the field report an empty string and are treated as approved. */
 	approvalStatus?: AgencyApprovalStatus | '';
+	/** The current user's agency capabilities; the earning cards lock without referrals access. */
+	capabilities?: string[];
 	links: AgencyOverviewLinks;
-	useRouterLink?: boolean;
+	shouldUseRouterLink?: boolean;
 	onScheduleCall?: () => void;
 	isSchedulingCall?: boolean;
 	onRelaunchTour?: () => void;
@@ -43,8 +49,9 @@ export default function AgencyOverviewContent( {
 	tierId,
 	influencedRevenue,
 	approvalStatus,
+	capabilities,
 	links,
-	useRouterLink,
+	shouldUseRouterLink,
 	onScheduleCall,
 	isSchedulingCall,
 	onRelaunchTour,
@@ -54,8 +61,9 @@ export default function AgencyOverviewContent( {
 	const spacing = isSmallViewport ? 4 : 6;
 	const isPending = approvalStatus === 'pending';
 	const isRejected = approvalStatus === 'rejected';
+	const canAccessEarnings = ! capabilities || capabilities.includes( REFERRALS_CAPABILITY );
 	// A rejection is already spelled out by the tier card, so only pending accounts get the note.
-	const isLocked = isPending || isRejected;
+	const isLocked = isPending || isRejected || ! canAccessEarnings;
 	const lockedNote = isPending ? __( 'Unlocks when your account is activated' ) : undefined;
 
 	return (
@@ -73,7 +81,7 @@ export default function AgencyOverviewContent( {
 						tierId={ tierId }
 						influencedRevenue={ influencedRevenue }
 						tiersHref={ links.tiers }
-						useRouterLink={ useRouterLink }
+						shouldUseRouterLink={ shouldUseRouterLink }
 						onScheduleCall={ onScheduleCall }
 						isSchedulingCall={ isSchedulingCall }
 						recordTracksEvent={ recordTracksEvent }
@@ -84,15 +92,15 @@ export default function AgencyOverviewContent( {
 					locked={ isLocked }
 					lockedNote={ lockedNote }
 					referralsHref={ links.referrals }
-					useRouterLink={ useRouterLink }
+					shouldUseRouterLink={ shouldUseRouterLink }
 					recordTracksEvent={ recordTracksEvent }
 				/>
 				<WooPaymentsRevenueCard
 					agencyId={ agencyId }
 					locked={ isLocked }
 					lockedNote={ lockedNote }
 					woopaymentsHref={ links.woopayments }
-					useRouterLink={ useRouterLink }
+					shouldUseRouterLink={ shouldUseRouterLink }
 					recordTracksEvent={ recordTracksEvent }
 				/>
 			</VStack>

client/dashboard/agency/overview/overview-link-button.tsx

@@ -12,7 +12,7 @@ interface OverviewLinkButtonProps {
 	 * Set to false in apps without the dashboard's TanStack Router, so the button
 	 * renders a plain anchor for the host app's own router to pick up.
 	 */
-	useRouterLink?: boolean;
+	shouldUseRouterLink?: boolean;
 }
 
 export default function OverviewLinkButton( {
@@ -21,9 +21,9 @@ export default function OverviewLinkButton( {
 	variant,
 	size,
 	onClick,
-	useRouterLink = true,
+	shouldUseRouterLink = true,
 }: OverviewLinkButtonProps ) {
-	if ( useRouterLink ) {
+	if ( shouldUseRouterLink ) {
 		return (
 			<RouterLinkButton to={ href } variant={ variant } size={ size } onClick={ onClick }>
 				{ children }

client/dashboard/agency/overview/referral-earnings-card.tsx

@@ -3,6 +3,7 @@ import { formatCurrency, formatNumber } from '@automattic/number-formatters';
 import { Badge } from '@automattic/ui';
 import { useQuery } from '@tanstack/react-query';
 import {
+	__experimentalHeading as Heading,
 	__experimentalHStack as HStack,
 	__experimentalVStack as VStack,
 } from '@wordpress/components';
@@ -21,28 +22,28 @@ interface ReferralEarningsCardProps {
 	locked?: boolean;
 	lockedNote?: string;
 	referralsHref: string;
-	useRouterLink?: boolean;
+	shouldUseRouterLink?: boolean;
 	recordTracksEvent?: RecordTracksEvent;
 }
 
 function ReferralEarningsEmptyState( {
 	locked,
 	lockedNote,
 	referralsHref,
-	useRouterLink,
+	shouldUseRouterLink,
 	recordTracksEvent,
 }: {
 	locked?: boolean;
 	lockedNote?: string;
 	referralsHref: string;
-	useRouterLink?: boolean;
+	shouldUseRouterLink?: boolean;
 	recordTracksEvent?: RecordTracksEvent;
 } ) {
 	return (
 		<VStack spacing={ 4 }>
-			<Text size={ 15 } weight={ 500 } lineHeight="20px" as="h2">
+			<Heading level={ 2 } size={ 15 } weight={ 500 } lineHeight="20px">
 				{ __( 'Referral earnings' ) }
-			</Text>
+			</Heading>
 			<Text variant="muted" lineHeight="20px">
 				{ __(
 					'Earn 20% recurring commissions on hosting and 50% on plugins when you refer clients through your dashboard.'
@@ -59,7 +60,7 @@ function ReferralEarningsEmptyState( {
 						size="compact"
 						variant="secondary"
 						href={ referralsHref }
-						useRouterLink={ useRouterLink }
+						shouldUseRouterLink={ shouldUseRouterLink }
 						onClick={ () =>
 							recordTracksEvent?.( 'calypso_a4a_overview_referrals_make_referral_click' )
 						}
@@ -72,12 +73,14 @@ function ReferralEarningsEmptyState( {
 	);
 }
 
+// Not OverviewCard: it renders the whole card as a single link, while this card
+// needs inline actions and non-interactive stat rows.
 export default function ReferralEarningsCard( {
 	agencyId,
 	locked,
 	lockedNote,
 	referralsHref,
-	useRouterLink,
+	shouldUseRouterLink,
 	recordTracksEvent,
 }: ReferralEarningsCardProps ) {
 	const { data: referrals = [], isLoading: isLoadingReferrals } = useQuery( {
@@ -102,7 +105,7 @@ export default function ReferralEarningsCard( {
 						locked={ locked }
 						lockedNote={ lockedNote }
 						referralsHref={ referralsHref }
-						useRouterLink={ useRouterLink }
+						shouldUseRouterLink={ shouldUseRouterLink }
 						recordTracksEvent={ recordTracksEvent }
 					/>
 				</CardBody>
@@ -118,9 +121,9 @@ export default function ReferralEarningsCard( {
 		<Card>
 			<CardBody>
 				<VStack spacing={ 4 }>
-					<Text size={ 15 } weight={ 500 } lineHeight="20px" as="h2">
+					<Heading level={ 2 } size={ 15 } weight={ 500 } lineHeight="20px">
 						{ __( 'Referral earnings' ) }
-					</Text>
+					</Heading>
 					<HStack spacing={ 2 } justify="flex-start" alignment="baseline" expanded={ false }>
 						<Text size={ 20 } weight={ 500 } lineHeight="24px">
 							{ isLoading ? (
@@ -152,7 +155,7 @@ export default function ReferralEarningsCard( {
 							size="compact"
 							variant="secondary"
 							href={ referralsHref }
-							useRouterLink={ useRouterLink }
+							shouldUseRouterLink={ shouldUseRouterLink }
 							onClick={ () =>
 								recordTracksEvent?.( 'calypso_a4a_overview_referrals_view_details_click' )
 							}

client/dashboard/agency/overview/tier-overview-card.tsx

@@ -17,7 +17,7 @@ interface TierOverviewCardProps {
 	tierId?: AgencyTierType;
 	influencedRevenue: number;
 	tiersHref: string;
-	useRouterLink?: boolean;
+	shouldUseRouterLink?: boolean;
 	onScheduleCall?: () => void;
 	isSchedulingCall?: boolean;
 	recordTracksEvent?: RecordTracksEvent;
@@ -51,7 +51,7 @@ export default function TierOverviewCard( {
 	tierId,
 	influencedRevenue,
 	tiersHref,
-	useRouterLink,
+	shouldUseRouterLink,
 	onScheduleCall,
 	isSchedulingCall,
 	recordTracksEvent,
@@ -72,7 +72,7 @@ export default function TierOverviewCard( {
 			heading={ tier.name }
 			description={ content.description }
 			link={ tiersHref }
-			useRouterLink={ useRouterLink }
+			shouldUseRouterLink={ shouldUseRouterLink }
 			tracksId="agency-overview-tier"
 			bottom={
 				<VStack spacing={ 4 }>

client/dashboard/agency/overview/use-woopayments-store-count.ts

@@ -6,21 +6,27 @@ import {
 import { useQuery } from '@tanstack/react-query';
 
 /**
- * Counts the agency's WooPayments stores the way the WooPayments dashboard does:
- * attached WooPayments licenses plus sites running the plugin, de-duplicated by blog.
+ * Counts the agency's WooPayments stores: attached WooPayments licenses plus
+ * sites running the plugin, de-duplicated by blog — matching the site list the
+ * WooPayments dashboard renders.
  */
 export default function useWooPaymentsStoreCount( agencyId: number, enabled = true ) {
 	const isEnabled = !! agencyId && enabled;
 
 	const { data: licenseBlogIds, isLoading: isLoadingLicenses } = useQuery( {
 		...wooPaymentsLicensesQuery( agencyId ),
 		enabled: isEnabled,
-		select: ( licenses ) => licenses.map( ( license ) => license.blog_id ?? 0 ),
+		refetchOnWindowFocus: false,
+		// A license can be attached without a blog; folding nulls into a
+		// placeholder id would count a phantom store.
+		select: ( licenses ) =>
+			licenses.flatMap( ( license ) => ( license.blog_id ? [ license.blog_id ] : [] ) ),
 	} );
 
 	const { data: pluginBlogIds, isLoading: isLoadingSites } = useQuery( {
 		...agencySitesWithPluginsQuery( agencyId, [ WOOPAYMENTS_PLUGIN ] ),
 		enabled: isEnabled,
+		refetchOnWindowFocus: false,
 		select: ( sites ) => sites.map( ( site ) => site.blog_id ),
 	} );