Create Callout component for displaying splash over the Deployments route

[p-jackson]

DES-52

Proposed Changes

Adds the <Callout> component to dashboard/components/.
dhW7zYBamXJIeJIE3wy5f4-fi-3510_117161

Also adds a callout to the Deployments page on the /v2 dashboard when the site doesn't have the necessary plan.

This PR only implements the callout features necessary for the hosting dashboard callouts. The design system also has a full-bleed image variation, but none of the dashboard mockups use it.
Seems best to implement things once we have a use case for them.

The blurred background (<CalloutOverlay>) is kept separate from <Callout>. I think this is best because the exact way we need to obscure the page content depends heavily on the specifics of our app's page layout. Other users of the callout design pattern may be embedding it directly within content without any overlay. It's just presented as a generic card in the DS spec.

Since the deployment page is empty as of now, the easiest way to test focus management is in The CalloutOverlay storybook. The reason I haven't reused the <Modal> component is because this isn't really a modal. You can tab from the nav bars into the callout and back again.

CleanShot.2025-05-21.at.21.08.28.mp4

Why are these changes being made?

Rather than hiding menus when a site doesn't have the necessary plan, this call-out pattern gives the user some impression of what the feature looks like (behind a blurred background) and provides instructions on next steps if they're interested.

Testing Instructions

To check storybook run yarn storybook:start in the wp-calypso directory.

To test the dashboard

• calypso.localhost:3000/v2
• in the site grid choose a free site (one that doesn't have the necessary plan for GitHub deployments)
• drill in to the deployments screen
• observe the call-out in action

When testing focus management, you should open the accessibility tree in the dev tools and confirm that the content under the overlay disappears from the a11y tree when it is covered.

Pre-merge Checklist

• Has the general commit checklist been followed? (PCYsg-hS-p2)
• Have you written new tests for your changes?
• Have you tested the feature in Simple (P9HQHe-k8-p2), Atomic (P9HQHe-jW-p2), and self-hosted Jetpack sites (PCYsg-g6b-p2)?
• Have you checked for TypeScript, React or other console errors?
• Have you used memoizing on expensive computations? More info in Memoizing with create-selector and Using memoizing selectors and Our Approach to Data
• Have we added the "[Status] String Freeze" label as soon as any new strings were ready for translation (p4TIVU-5Jq-p2)?
  • For UI changes, have we tested the change in various languages (for example, ES, PT, FR, or DE)? The length of text and words vary significantly between languages.
• For changes affecting Jetpack: Have we added the "[Status] Needs Privacy Updates" label if this pull request changes what data or activity we track or use (p4TIVU-aUh-p2)?

[github-actions]

Calypso Live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-145470

Jetpack Cloud live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-145470&env=jetpack

Automattic for Agencies live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-145470&env=a8c-for-agencies

[matticbot]

Here is how your PR affects size of JS and CSS bundles shipped to the user's browser:

App Entrypoints (~169 bytes added 📈 [gzipped])

name                    parsed_size           gzip_size
entry-dashboard-dotcom       +359 B  (+0.0%)     +143 B  (+0.0%)
entry-dashboard-a4a          +359 B  (+0.0%)     +143 B  (+0.0%)
entry-subscriptions          +296 B  (+0.0%)     +117 B  (+0.0%)
entry-stepper                +296 B  (+0.0%)     +117 B  (+0.0%)
entry-reauth-required        +296 B  (+0.0%)     +117 B  (+0.0%)
entry-main                   +296 B  (+0.0%)     +117 B  (+0.0%)
entry-login                  +296 B  (+0.0%)     +117 B  (+0.0%)
entry-domains-landing        +296 B  (+0.0%)     +117 B  (+0.1%)
entry-browsehappy            +296 B  (+0.1%)     +117 B  (+0.2%)

Common code that is always downloaded and parsed every time the app is loaded, no matter which route is used.

Legend

What is parsed and gzip size?

Parsed Size: Uncompressed size of the JS and CSS files. This much code needs to be parsed and stored in memory.
Gzip Size: Compressed size of the JS and CSS files. This much data needs to be downloaded over network.

Generated by performance advisor bot at iscalypsofastyet.com.

[p-jackson]

@jameskoster @jasmussen I'm starting to implement DES-52. This PR is super early, but I definitely have some component-library type questions already.

Lego's focus is definitely getting the hosting dashboard off the ground, not necessarily fully implementing every permutation of the CallOut. Specifically the hosting dashboard doesn't have a need for the "full bleed" or "highlighted" variants right now. But I still want to make sure what I do implement is good enough to go in the blessed set of @automattic/ components.

[p-jackson]

I originally had separate props for description, actions, etc. This works for the example used in the CallOut design spec.

However the dashboard mockups use two paragraphs.

So that means there are two <Text> elements.

Since all elements on the left are vertically stacked, with the same gap between each, does it make more sense to just take an arbitrary children prop, and let the consumer use <Text> and <Button> elements as they please? The VStack makes sure they'll be arranged correctly.

[aduth]

I think using children this way seems like a reasonable choice, especially with wanting to reinforce a consistent vertical gap.

A couple alternatives that came to mind, but don't seem like great fits either:

• description prop and expecting the consumer to render their own HStack if needing multiple paragraphs. Hard to enforce consistency.
• description accepting an array of either <Text> elements or strings. Arrays of elements aren't very ergonomic since they require keys, and arrays of strings might not support the type of flexibility we want in content (links, emphasis, etc.)

[ntsekouras]

Why not have description with ReactNode? The consumer could still pass multiple items with <> and get the spacing from the internal VStack, and it's a bit more specific to where the content goes IMO.

[p-jackson]

Why not have description with ReactNode?

IMO that basically is a children prop, except with a children you don't need to wrap in <> when you've got multiple.

Perhaps an explicit prop name is better for enforcing consistent usage of the component though?

[aduth]

I think to @ntsekouras 's point, when using children it should be obvious where those children would be rendered, and I'm not sure it's inherently obvious that it'd be rendered below the heading and above the actions.

Although I think it's the obvious place if you think about it for more than a few seconds, just not immediately obvious. So a soft opinion from me on children vs. description, anyways.

[p-jackson]

it should be obvious where those children would be rendered

I think that's a fair point. I'll try adding two separate description and actions for the sake of making the props explanatory.

[p-jackson]

Choosing heading level feels fraught. How will I know in the context which level is correct?
On the other hand, having screen readers treat it as regular paragraph text also doesn't seem right.

[aduth]

Choosing heading level feels fraught. How will I know in the context which level is correct? On the other hand, having screen readers treat it as regular paragraph text also doesn't seem right.

Maybe this should be a required prop provided when rendered by a consumer? (e.g. headingLevel)

Though on the semantics of how a call-out would be used, I wonder if it's something where the content isn't necessarily part of the document structure, but rather more like an <aside>, that can associate the callout heading using aria-labelledby. I don't feel entirely confident that this wouldn't still be most appropriate to mark up as a heading.

Separately, I wonder if the <Heading> component from @wordpress/components could manage React context so that we could assign a heading level relative to the closest heading (e.g. + 1 from the current ancestor heading level). I see that it internally does have some context behaviors, so maybe it is possible? (or at least could be extended to support)

[p-jackson]

I thought about the <aside> and aria-labelledby idea, but I think semantically heading is still correct. In the case of the v2 dashboard, when the user focuses in to an area covered by a call-out, it should just appear to be that the call-out message is the main/only content of the area. You wouldn't expect to have an <aside> be the main content, just a heading and a paragraph telling you that this nav area needs a purchase.

It'd be cool if internally <Heading> could automatically set the correct level. Without that I think h6 is probably a good bet and I've added an optional headingLevel prop if a particularly assiduous developer would like to set a more correct one.

[p-jackson]

The design spec has guidance for showing 4 or 6 column wide call outs. Are these column widths encoded anywhere yet?

Should CallOut have a cols prop which sets a max width?

[p-jackson]

@youknowriad This PR is still early, but I just wanted to point out to you where I was placing the CallOut in the React tree.

[p-jackson]

I've added the CallOut directly to the PageLayout. I'd prefer to experiment with call outs before wrapping them into any sort of official layout. However it needs the CallOut needs to render over the page heading, and this is where the heading gets rendered.

[p-jackson]

I'm not using a modal to implement the "sneeze guard". It looks like a modal, but it's a bit different. For example pressing escape doesn't navigate you away from the page.

This sort of call out will need special focus management though, to ensure the user doesn't tab into the content behind the "sneeze guard". I'll see if there's anything I can commandeer from core for this.

[jasmussen]

Specifically the hosting dashboard doesn't have a need for the "full bleed" or "highlighted" variants right now

Sounds good to me, I like to start with as little as possible and grow in variants/densities either when it becomes necessary or when there's a clearly identified future need.

[aduth]

Choosing heading level feels fraught. How will I know in the context which level is correct? On the other hand, having screen readers treat it as regular paragraph text also doesn't seem right.

Maybe this should be a required prop provided when rendered by a consumer? (e.g. headingLevel)

Though on the semantics of how a call-out would be used, I wonder if it's something where the content isn't necessarily part of the document structure, but rather more like an <aside>, that can associate the callout heading using aria-labelledby. I don't feel entirely confident that this wouldn't still be most appropriate to mark up as a heading.

Separately, I wonder if the <Heading> component from @wordpress/components could manage React context so that we could assign a heading level relative to the closest heading (e.g. + 1 from the current ancestor heading level). I see that it internally does have some context behaviors, so maybe it is possible? (or at least could be extended to support)

[aduth]

I think using children this way seems like a reasonable choice, especially with wanting to reinforce a consistent vertical gap.

A couple alternatives that came to mind, but don't seem like great fits either:

• description prop and expecting the consumer to render their own HStack if needing multiple paragraphs. Hard to enforce consistency.
• description accepting an array of either <Text> elements or strings. Arrays of elements aren't very ergonomic since they require keys, and arrays of strings might not support the type of flexibility we want in content (links, emphasis, etc.)

[aduth]

With how we're using the call-out as a modal-like element not part of the layout's VStack, could we render it adjacent to the page layout rather than inside it? To limit prop overload on PageLayout.

e.g.

Suggested change

	return (
	<PageLayout title={ __( 'Deployments' ) } callOut={ showCallOut && <DeploymentsCallOut /> } />
	);
	return (
	<>
	<PageLayout title={ __( 'Deployments' ) } />
	{ showCallOut && <DeploymentsCallOut /> }
	</>
	);

[jameskoster]

From an a11y perspective I suppose the Callout will need to be outside because PageLayout contents will need to be inert or aria-hidden="true".

I guess it will also need to trap focus inside the 'modal' too, but still provide access back to the main nav.

Alternatively we could just use an actual modal dialog. I suspect this would be much simpler 😅

[youknowriad]

I'm actually not sure we'll have any content outside the callout, most endpoints ... will fail unless the user actually has the right plans... so the content outside the callout probably needs to be "fake". We might need a system for that.

[p-jackson]

That's a good point, I prefer this.
The downside is the call-out will no longer have access to the page layout's height, which it can use to ensure all the components on the page get covered, without resorting to position: fixed.

[fushar]

Forgive me for this very nitpicky comment, feel free to ignore, but is it Callout or CallOut? I believe we have been inconsistently using both terms in discussions (Figma and GH)

[p-jackson]

The DS figma uses CallOut so I've been trying to do the same. I'm using call-out for lowercase file paths and trying to use "call out" or "call-out" in English conversations like this. It can be a bit cumbersome since callout just rolls off the tongue 🙂

CallOut is good though IMO. "Callout" reminds me of a verb. Like a .callout() method nae. But "Call Out" feels like a noun.

[matticbot]

This PR modifies the release build for the following Calypso Apps:

For info about this notification, see here: PCYsg-OT6-p2

• help-center
• notifications
• wpcom-block-editor

To test WordPress.com changes, run install-plugin.sh $pluginSlug add/call-out-component-deployments on your sandbox.

[jasmussen]

No strong opinions on Callout or CallOut, though I found this:

In design systems and UI libraries (like Material UI, Fluent, Carbon, etc.), component names typically use PascalCase (e.g., Button, Alert, Card, Callout). In PascalCase, each word is capitalized, but compound words like "Callout" are usually written as a single word, not split.

[fushar]

On smaller screen, should we stack the text and the illustration vertically?

[fushar]

Based on my understanding reading various DS PRs, I think we're supposed to prefix the classname with a8c-components-. See e.g. #102998 (comment)

[jameskoster]

Yes I think so. Can it be built into the component as a container query, using the $break-mobile breakpoint (480px)?

[mirka]

Great work here!

We just discussed in the Design Systems call last week that we'd like to defer adding components to @automattic/components itself until it really has an actual use case outside of the initial local use case. This is to prevent spending too much time on premature abstractions, and to avoid the huge increase in technical maintenance cost once it lands in the package. The rest of the process will remain largely the same, such as involving the DS team from the early stages, and keeping it visible as a proposed addition to the DS. We just want to keep the implementation local until it really needs to be elevated to the actual package. Would that be the case here?

[mirka]

Note that level also changes the semantic heading level as well as the visual, so simply exposing this prop without the ability to override the semantic level is problematic. If anything you probably want to hardcode the level and expose the as prop so only the semantics can be changed.

[p-jackson]

exposing this prop without the ability to override the semantic level is problematic

I don't understand, the reason I'm exposing this prop is specially to allow the level to be set semantically. The <Heading> component doesn't change visually, so this is just for the semantics.
We could expose an as, but it feels appropriate that we force the title to be a heading.

[mirka]

Oh, I see you're overriding the font size in CSS. The Heading component was apparently intended to provide the typography sizing scale ("Heading renders headings and titles using the library's typography system"), but since that scale is neither aligned with the current WP sizing scale nor are we even trying to leverage here, there's probably no reason to use that component. In fact we are actively discouraging style overrides like this.

Perhaps we might as well directly accept h2 thru h6 elements for the title? The default h6 is quite arbitrary and I can see consumers forgetting to change it.

[jameskoster]

I don't have the full context or a sense of urgency, but I've had conversations with designers about using this component outside of the host dashboard project. cc @nuriapenya and @marina.matijaca1 for input. Where are y'all planning to use Callout, is it needed soon?

[p-jackson]

@fushar @jameskoster when the content is stacked vertically and the image takes on it's natural height it just dominates.

The design spec actually calls for the content to stay presented horizontally, but it's demo content is much shorter. The two paragraphs worth of copy really makes it look wrong presented horizontally.

I looks a bit dry, but I think the fix on small screens might just be to hide the illustration.

[p-jackson]

@ellatrix I've just rebased your fancy view-transitions.scss changes into this PR. Transitions appear to mess with the blur effect that should be obscuring the page header. Check PR description for what it's supposed to look like.

After rebasing the <h1> looks crisp instead of blurry.

It makes sense that transitions wouldn't be compatible with overlapping elements. Does it make sense to you that we should disable the transitions when the page the user is coming from or going to has an overlay? Have you got any ideas for how we could add a test to the selectors in view-transitions.scss that could detect whether an overlay was visible?

[jameskoster]

when the content is stacked vertically and the image takes on it's natural height it just dominates

Yeah that does look quite heavy. Maybe it's okay for the layout to remain horizontal. What do you think @matt-west?

I'm going to cc @annchichi too since you've been looking at this component recently; did you have any feelings about how the layout would adapt as the container shrinks?

[matt-west]

I'm tempted to drop the graphic on mobile. In the hosting dashboard, the graphic is complimentary to the main content, but not really essential. That might not always be the case though if the graphic is used to show a specific feature/animation.

[p-jackson]

@jameskoster @matt-west This is what it looks like horizontal on an iPhone 12 Pro if I also decrease the card's padding and column gap to grid-20 on $break-small screens.

(ignore misalignment along the right, the dashboard appears to have a layout bug on small screens)

I don't think it looks that bad. Although this graphic just happens to crop really well at this aspect ratio. The staging site illustration wouldn't work as well

[jasmussen]

I'm tempted to drop the graphic on mobile. In the hosting dashboard, the graphic is complimentary to the main content, but not really essential. That might not always be the case though if the graphic is used to show a specific feature/animation.

I'm skeptical of that, not because the idea is bad, but because ideally we think in generic components, meaning if we decide to drop the graphic from mobile, we're essentially doing that for all callouts going forward. We just need to be sure that's what we want.

[matt-west]

@jasmussen That's fair.

[fushar]

@ellatrix could you help with this comment? #103414 (comment) Thanks!

[fushar]

@p-jackson I think the CleanShot images are broken in your comments

[fushar]

The condition seems to be different from the original logic in v1:

wp-calypso/client/sites/components/site-preview-pane/dotcom-preview-pane.tsx

Line 67 in 9eca4fc

const isActiveAtomicSite = isAtomicSite && ! isPlanExpired;

showCallout should be the inverse of the above condition. 🤔

[p-jackson]

Interesting, I think it's sort of annoying when an atomic site can't see the atomic features. But that might just be a dev thing 😃 It makes sense to copy v1 business logic unless making an explicit proposal to change it.

[fushar]

IIRC the "features" in the wpcom backend code is tied to plans, not the atomic state.

We can iterate on it later when we actually implement the Deployments screen.

[fushar]

I'm not sure how this works. Shouldn't the content of main depends on showCallout? As in, if showCallout is true, we should render a blurred placeholder content here; otherwise, we render the real component (the real Deployments page). How would we handle that?

[p-jackson]

Oooh that's an interesting point. I was imagining the placeholder content would use the same elements as the real page, and it would be the data that was swapped out for dummy data. But I see now that the placeholder content could be totally different elements.

I like the way that in this situation the placeholder is using the same elements as the live data. But shall we wait until we have some placeholder components before we settle on what the right abstraction is? The main thing about this PR is that the CalloutOverlay needs to own the placeholder elements so that it can correctly blur them.

[fushar]

I see now that the placeholder content could be totally different elements.

Yeah, this is what I imagine, too:

• Deployments renders deployment list with many rows of fake data
• Monitoring renders fake graphs

placeholder content would use the same elements as the real page, and it would be the data that was swapped out for dummy data.

Not sure but I think it's harder to pass around the showCallout state to various downstream components, instead of just coming up with a fake static content in the first place.

---

Not a blocker though, we can change the logic later, just wanted to call out (pun slightly intended)!

[jameskoster]

Maybe we introduce a property to allow consumers to hide the illustration at a certain size?

[p-jackson]

I think this PR is in a good place to merge.

• There's an conversation about the callout mobile layout. I'm not a fan of adding a prop to decide whether the image should be hidden on mobile, I'd rather we decide to always design copy and images in such a way that they'll look good on narrow screens to. But for the purposes of this PR I'm happy implementing it to the spec. And then continuing the conversation about whether the spec should change 😃
• The abstraction for how placeholder components are rendered might not be right. But I think we need a concrete example we can work with before we settle on the correct abstraction.
• Page transitions have introduced an issued a bug in the blurred background. We can address that in a follow up.

[p-jackson]

I've summarised the mobile layout issues in DES-52

[a8ci18n]

This Pull Request is now available for translation here: https://translate.wordpress.com/deliverables/17505574

Some locales (Hebrew) have been temporarily machine-translated due to translator availability. All other translations are usually ready within a few days. Untranslated and machine-translated strings will be sent for translation next Monday and are expected to be completed by the following Friday.

Thank you @p-jackson for including a screenshot in the description! This is really helpful for our translators.