Proposal/RFC convention that mimics CSS parts and state

js/src/components/account-card/index.js

@@ -51,6 +51,12 @@ const appearanceDict = {
 /**
  * Renders a Card component with account info and status.
  *
+ * ## CSS Parts:
+ * `icon` - area with the icon fetched for respective appearence.
+ * `title` - area with the title fetched for respective appearence.
+ * `indicator` - indicator/action area
+ * `description` - description area
+ *
  * @param {Object} props React props.
  * @param {string} [props.className] Additional CSS class name to be appended.
  * @param {APPEARANCE | {icon, title}} props.appearance Kind of account to indicate the card appearance, or a tuple with icon and title to be used.
@@ -76,12 +82,20 @@ export default function AccountCard( {
 		<Section.Card className={ classnames( 'gla-account-card', className ) }>
 			<Section.Card.Body>
 				<Flex gap={ 4 }>
-					{ ! hideIcon && <FlexItem>{ icon }</FlexItem> }
+					{ ! hideIcon && (
+						<FlexItem className="part--icon">{ icon }</FlexItem>
+					) }
 					<FlexBlock>
-						<Subsection.Title>{ title }</Subsection.Title>
-						<div>{ description }</div>
+						<Subsection.Title className="part--title">
+							{ title }
+						</Subsection.Title>
+						<div className="part--description">{ description }</div>
 					</FlexBlock>
-					{ indicator && <FlexItem>{ indicator }</FlexItem> }
+					{ indicator && (
+						<FlexItem className="part--indicator">
+							{ indicator }
+						</FlexItem>
+					) }
 				</Flex>
 			</Section.Card.Body>
 			{ children }

js/src/components/contact-information/contact-information-preview-card.js

@@ -4,6 +4,7 @@
 import { __ } from '@wordpress/i18n';
 import { Icon, warning as warningIcon } from '@wordpress/icons';
 import { getPath, getQuery } from '@woocommerce/navigation';
+import classNames from 'classnames';
 
 /**
  * Internal dependencies
@@ -43,15 +44,11 @@ export default function ContactInformationPreviewCard( {
 			eventProps={ { path: getPath(), subpath } }
 		/>
 	);
-	let description;
+	let description = content;
 
 	if ( loading ) {
 		description = (
-			<span
-				className="gla-contact-info-preview-card__placeholder"
-				aria-busy="true"
-				title={ __( 'Loading…', 'google-listings-and-ads' ) }
-			></span>
+			<div title={ __( 'Loading…', 'google-listings-and-ads' ) }></div>
 		);
 	} else if ( warning ) {
 		appearance = {
@@ -66,19 +63,16 @@ export default function ContactInformationPreviewCard( {
 				</>
 			),
 		};
-		description = (
-			<span className="gla-contact-info-preview-card__notice-details">
-				{ content }
-			</span>
-		);
-	} else {
-		description = content;
 	}
 
 	return (
 		<AccountCard
 			appearance={ appearance }
-			className="gla-contact-info-preview-card"
+			aria-busy={ loading }
+			className={ classNames( 'gla-contact-info-preview-card', {
+				'state--loading': loading,
+				'state--warning': warning,
+			} ) }
 			description={ description }
 			hideIcon
 			indicator={ editButton }

js/src/components/contact-information/contact-information-preview-card.scss

@@ -1,18 +1,27 @@
+// :host
 .gla-contact-info-preview-card {
 	// Vertically align icon inside the title.
-	.wcdl-subsection-title {
+	// :host::part( title ) - if we use inheritance
+	// account-card::part( title ) - if we use composition
+	.part--title {
 		display: flex;
 		align-items: center;
 	}
-	&__notice-icon {
+
+	// :--warning::part( icon )
+	&.state--warning {
 		fill: $alert-red;
 		margin: calc(var(--main-gap) / -8) 0;
 	}
-	&__notice-details {
+	// :--warning>[slot="description"]
+	// :--warning::part( description )
+	&.state--warning .part--description {
 		color: $gray-700;
 	}
 
-	&__placeholder {
+	// :--loading>[slot="description"]
+	// :--loading::part( description )
+	&.state--loading .part--description {
 		@include placeholder();
 		display: inline-block;
 		width: 18em;

js/src/components/contact-information/phone-number-card/phone-number-card-preview.js

@@ -25,6 +25,9 @@ export function PhoneNumberCardPreview( { editHref, learnMore } ) {
 	const { loaded, data } = useGoogleMCPhoneNumber();
 	let content, warning;
 
+	// Mock invalid data for testing.
+	data.isValid = false;
+
 	if ( loaded ) {
 		if ( data.isValid ) {
 			content = data.display;

js/src/components/contact-information/store-address-card.scss

@@ -1,22 +1,28 @@
+// :host
 .gla-store-address-card {
-	// We could've used `StoreAddressCard'`s selectors,
-	// but the elements are wrapped with `<FlexItem>`,
-	// which does not have accessible semantic selector.
-	// So we have to rely on `<AccountCard>`'s internal implementation details.
-	.components-flex__item {
+
+	// ::part( icon )
+	.part--icon {
 		align-self: start;
 	}
 
-	.components-flex__item:nth-child(3) {
+	// ::part( indicator )
+	.part--indicator {
+		align-self: start;
 		svg {
 			margin-left: 4px;
 		}
 	}
 
-	p {
-		margin: 1em 0;
-	}
-	p:last-child {
-		margin-bottom: 0;
+	// ::part( description )
+	.part--description {
+		display: flex;
+		flex-direction: column;
+		gap: 1em;
+
+		// [slot="description"]
+		> p {
+			margin: 0;
+		}
 	}
 }