Card: updates labeling and internal testId support (#2859)

## Summary:
When integrating Cards into the frontend repo, I ran into a few complications that I wanted to fix:
- The labeling requirements made it difficult to create wrapped Cards
- The labeling was also required for scenarios where it doesn't need to be -- not all sections or figures need accessible names. So I made these optional
- The dismiss button was missing a testId or way to create one, so existing tests failed

Issue: FEI-6310

Related `frontend` PR: Khan/frontend#5283

## Test plan:
1. Review typing to ensure it makes sense
2. Ensure tests pass

Author: marcysutton

Reviewers: jandrade, marcysutton, beaesguerra

Required Reviewers:

Approved By: beaesguerra

Checks: ✅ 12 checks were successful, ⏭️  3 checks have been skipped

Pull Request URL: #2859

Author: marcysutton

.changeset/thin-plants-decide.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-card": minor
+---
+
+Updates labeling requirements and adds testId to dismiss button

__docs__/wonder-blocks-card/accessibility.mdx

@@ -4,19 +4,28 @@ import {Meta} from "@storybook/addon-docs/blocks";
 
 # Card Accessibility
 
-- When using `tag="section"` or `tag="figure"`, the `labels.cardAriaLabel` prop is required to provide an accessible name for the card.
-- When the `onDismiss` prop is provided, a dismiss button will be rendered. In this case, the `labels.dismissButtonAriaLabel` prop is required to provide an accessible label for the dismiss button.
-- Cards cannot be interactive elements themselves (e.g. buttons or links), but they can contain interactive elements as children.
+Cards cannot be interactive elements themselves (e.g. buttons or links), but they can contain interactive elements as children.
 
 ## HTML Semantics
 
 By default, cards render as `<div>` elements. However, you can specify a different semantic element using the `tag` prop:
 
-- `tag="section"` - Use when the card represents a distinct section of content. Requires an accessible name via `labels.cardAriaLabel`.
+- `tag="section"` - Use when the card represents a distinct section of content. Accepts an accessible name via `labels.cardAriaLabel`.
 - `tag="figure"` - Use when the card contains media or illustrated content. Accepts an accessible name via `labels.cardAriaLabel`.
 - `tag="article"` - Use when the card represents standalone content
 - `tag="li"` - Use when cards are part of a list (see notes about `inert` below)
 
+## Labeling cards
+
+When using semantic tags like `tag="section"` or `tag="figure"`, you should provide an accessible name for the Card using one of the following (in order of preference):
+
+ 1. `labels.cardAriaLabel`: preferred for translatable strings. It automatically applies to the `aria-label` attribute. See the Dismiss Button section below for dismiss button labeling requirements.
+ 2. `aria-labelledby`: for ID references to existing elements.
+
+Only one labeling mechanism can be used at a time. Refer to the [Accessible Name Computation specification](https://www.w3.org/TR/accname-1.2/#computation-steps) to understand how this is standardized.
+
+When the `onDismiss` prop is provided, a dismiss button will be rendered. In this case, the `labels.dismissButtonAriaLabel` prop is required to provide a translatable, accessible label for the dismiss button.
+
 ## Dismiss Button
 
 When `onDismiss` is provided, an accessible dismiss button is automatically added:
@@ -37,10 +46,10 @@ See the In a Stack story for an example of disabling cards while keeping them pa
 
 ## Best Practices
 
-- Ensure cards have a logical heading structure when they contain headings
-- If cards are part of a collection, consider using appropriate container semantics (`<ul>`, `<ol>`, or `role="list"`)
-- When cards are dismissible, ensure focus is moved to an appropriate element after dismissal
-- Use meaningful accessible names for semantic card tags (`section`, `figure`)
+- Ensure cards have a logical heading structure when they contain headings.
+- If cards are part of a collection, consider wrapping them with appropriate container semantics (`<ul>`, `<ol>`, or `role="list"`).
+- When cards are dismissible, ensure focus is moved to an appropriate element after dismissal.
+- When applicable, use meaningful accessible names for semantic landmark tags (`section`, `figure`) so they show in the VoiceOver Rotor and NVDA Elements List.
 
 ## References
 

packages/wonder-blocks-card/src/__tests__/components/card.test.tsx

@@ -94,6 +94,42 @@ describe("Card", () => {
         });
     });
 
+    describe("Test IDs", () => {
+        it("should apply a custom testId for card", () => {
+            // Arrange
+            render(
+                <Card testId="my-card">
+                    <div>Content</div>
+                </Card>,
+            );
+
+            // Act
+            const card = screen.getByTestId("my-card");
+
+            // Assert
+            expect(card).toBeInTheDocument();
+        });
+
+        it("should append -dismiss-button to testId for dismiss button", () => {
+            // Arrange
+            render(
+                <Card
+                    testId="my-card"
+                    onDismiss={() => {}}
+                    labels={{dismissButtonAriaLabel: "Close"}}
+                >
+                    <div>Content</div>
+                </Card>,
+            );
+
+            // Act
+            const dismissButton = screen.getByTestId("my-card-dismiss-button");
+
+            // Assert
+            expect(dismissButton).toBeInTheDocument();
+        });
+    });
+
     describe("Accessibility", () => {
         it("should pass custom aria-label to dismiss button", () => {
             // Arrange
@@ -131,7 +167,7 @@ describe("Card", () => {
             expect(section).toBeInTheDocument();
         });
 
-        it("should apply labels.cardAriaLabel for a custom tag", () => {
+        it("should apply labels.cardAriaLabel for a custom tag (preferred)", () => {
             // Arrange
             render(
                 <Card
@@ -152,6 +188,50 @@ describe("Card", () => {
             expect(section).toBeInTheDocument();
         });
 
+        it("should apply aria-labelledby for a custom tag", () => {
+            // Arrange
+            render(
+                <div>
+                    <h2 id="card-heading">My Card Title</h2>
+                    <Card tag="section" aria-labelledby="card-heading">
+                        <p>Description</p>
+                    </Card>
+                </div>,
+            );
+
+            // Act
+            const section = screen.getByRole("region", {
+                name: "My Card Title",
+            });
+
+            // Assert
+            expect(section).toBeInTheDocument();
+        });
+
+        it("should only apply aria-labelledby", () => {
+            // Arrange
+            render(
+                <div>
+                    <h2 id="card-heading">My Card Title</h2>
+                    <Card
+                        tag="section"
+                        aria-labelledby="card-heading"
+                        aria-label="Fallback label"
+                    >
+                        <p>Description</p>
+                    </Card>
+                </div>,
+            );
+
+            // Act
+            const section = screen.getByRole("region", {
+                name: "My Card Title",
+            });
+
+            // Assert
+            expect(section).toBeInTheDocument();
+        });
+
         it("should apply the inert attribute", () => {
             // Arrange
             render(

packages/wonder-blocks-card/src/__tests__/components/card.typestest.tsx

@@ -102,18 +102,52 @@ import Card from "../../components/card";
     Content
 </Card>;
 
-// @ts-expect-error - section tag requires cardAriaLabel
+<Card tag="section" aria-label="Card section">
+    Content
+</Card>;
+
+<Card tag="figure" aria-label="Card figure">
+    Content
+</Card>;
+
+<Card tag="section" aria-labelledby="someId">
+    <h2 id="someId">Card title</h2>
+</Card>;
+
+<Card tag="figure" aria-labelledby="someId2">
+    <h2 id="someId2">Card title</h2>
+</Card>;
+
+// @ts-expect-error - aria-labelledby cannot be used with labels.cardAriaLabel
+<Card
+    tag="figure"
+    aria-labelledby="someId2"
+    labels={{cardAriaLabel: "preferred label"}}
+>
+    <h2 id="someId2">Card title</h2>
+</Card>;
+
+// @ts-expect-error - aria-labelledby cannot be used with labels.cardAriaLabel
+<Card
+    tag="section"
+    aria-labelledby="someId2"
+    labels={{cardAriaLabel: "preferred label"}}
+>
+    <h2 id="someId2">Card title</h2>
+</Card>;
+
+<Card tag="figure" aria-labelledby="someId2" aria-label="fallback label">
+    <h2 id="someId2">Card title</h2>
+</Card>;
+
 <Card tag="section">Content</Card>;
 
-// @ts-expect-error - figure tag requires cardAriaLabel
 <Card tag="figure">Content</Card>;
 
-// @ts-expect-error - section tag requires cardAriaLabel in labels
 <Card tag="section" labels={{}}>
     Content
 </Card>;
 
-// @ts-expect-error - figure tag requires cardAriaLabel in labels
 <Card tag="figure" labels={{}}>
     Content
 </Card>;
@@ -132,10 +166,6 @@ import Card from "../../components/card";
     Content
 </Card>;
 
-/**
- * Card with dismiss and section tag (complex case)
- */
-
 <Card
     tag="section"
     onDismiss={() => {}}
@@ -152,6 +182,8 @@ import Card from "../../components/card";
  */
 
 <Card
+    aria-busy={true}
+    aria-roledescription="A custom card"
     background="base-subtle"
     borderRadius="medium"
     paddingSize="medium"
@@ -169,6 +201,7 @@ import Card from "../../components/card";
         dismissButton: {top: 10, right: 10},
     }}
     ref={React.createRef<HTMLElement>()}
+    role="status"
 >
     <div>Complex content</div>
 </Card>;

packages/wonder-blocks-card/src/components/card.tsx

@@ -2,6 +2,7 @@ import * as React from "react";
 
 import {StyleSheet} from "aphrodite";
 import {StyleType, View} from "@khanacademy/wonder-blocks-core";
+import type {AriaProps} from "@khanacademy/wonder-blocks-core";
 
 import {
     boxShadow,
@@ -39,6 +40,9 @@ type BaseCardProps = {
     inert?: boolean;
     /**
      * The test ID used to locate this component in automated tests.
+     *
+     * The test ID will also be passed to the dismiss button as
+     * `{testId}-dismiss-button` if the `onDismiss` prop is provided.
      */
     testId?: string;
 } & StyleProps;
@@ -61,28 +65,51 @@ type DismissProps =
       };
 
 /**
- * Provide a specific HTML tag that overrides the default (`div`).
- *
- * Notes:
- * - When `tag="section"` or `"figure"`, `cardAriaLabel` is required for accessibility.
- * - `button` and `a` tags are not allowed - use Wonder Blocks Button and Link components as children instead.
  * Valid HTML tags for the Card component.
  * Excludes button and anchor tags which should use Wonder Blocks Button and Link components instead.
  */
-type ValidCardTags = Exclude<keyof JSX.IntrinsicElements, "button" | "a">;
 
-type TagProps =
+/**
+ * Accessibility props for the Card.
+ *
+ * Labeling methods (in order of preference):
+ * 1. `labels.cardAriaLabel` - For translatable strings, automatically applied to `aria-label`
+ * 2. `aria-labelledby` - For ID references to existing elements
+ *
+ * Only one labeling mechanism can be used at a time. The type system enforces this
+ * by using discriminated unions.
+ */
+type LabelingProps =
     | {
-          // Section and figure require an aria-label
-          tag: "section" | "figure";
-          labels: {cardAriaLabel: string} & Record<string, any>;
+          /** Translatable label string for aria-label */
+          labels?: {
+              cardAriaLabel?: string;
+              dismissButtonAriaLabel?: string;
+          };
+          "aria-labelledby"?: never;
       }
     | {
-          // All other valid tags except button and a
-          tag?: Exclude<ValidCardTags, "section" | "figure">;
-          labels?: Record<string, any>;
+          /** ID reference for aria-labelledby */
+          "aria-labelledby"?: string;
+          labels?: {
+              cardAriaLabel?: never;
+              dismissButtonAriaLabel?: string;
+          };
       };
 
+type AccessibilityProps = LabelingProps & {
+    "aria-busy"?: AriaProps["aria-busy"];
+    "aria-roledescription"?: AriaProps["aria-roledescription"];
+    role?: AriaProps["role"];
+};
+
+/**
+ * Tag and accessibility props combined.
+ */
+type TagProps = {
+    tag?: Exclude<keyof JSX.IntrinsicElements, "button" | "a">;
+} & AccessibilityProps;
+
 type StyleProps = {
     /**
      * The background style of the card, as a string identifier that matches a semanticColor token.
@@ -152,7 +179,11 @@ type CardProps = BaseCardProps & TagProps & DismissProps;
  * </Card>
  * ```
  *
- * When the `onDismiss` prop is provided, a dismiss button will be rendered. In this case, the `labels.dismissButtonAriaLabel` prop is required to provide an accessible label for the dismiss button.
+ * ### Accessibility
+ *
+ * When the `onDismiss` prop is provided, a dismiss button will be rendered.
+ * In this case, the `labels.dismissButtonAriaLabel` prop is required to provide
+ * a translatable screen reader label for the dismiss button.
  *
  * See additional Accessibility docs.
  */
@@ -173,6 +204,9 @@ const Card = React.forwardRef(function Card(
         children,
         onDismiss,
         inert,
+        "aria-labelledby": ariaLabelledBy,
+        "aria-busy": ariaBusy,
+        role,
     } = props;
 
     const isBackgroundToken =
@@ -186,7 +220,9 @@ const Card = React.forwardRef(function Card(
 
     return (
         <View
+            aria-busy={ariaBusy}
             aria-label={labels?.cardAriaLabel}
+            aria-labelledby={ariaLabelledBy}
             style={[
                 componentStyles.root,
                 !isBackgroundToken && {
@@ -196,6 +232,7 @@ const Card = React.forwardRef(function Card(
                 styles?.root,
             ]}
             ref={ref}
+            role={role}
             tag={tag}
             testId={testId}
             {...{inert: inert ? "" : undefined}}
@@ -204,6 +241,7 @@ const Card = React.forwardRef(function Card(
                 <DismissButton
                     aria-label={labels?.dismissButtonAriaLabel || "Close"}
                     onClick={(e) => onDismiss?.(e)}
+                    testId={testId && `${testId}-dismiss-button`}
                 />
             ) : null}
             {children}

packages/wonder-blocks-card/src/components/dismiss-button.tsx

@@ -13,21 +13,10 @@ type Props = {
     "aria-label"?: string;
     /** Optional custom styles. */
     style?: StyleType;
-    /**
-     * Test ID used for e2e testing.
-     *
-     * In this case, this component is internal, so `testId` is composed with
-     * the `testId` passed down from the Dialog variant + a suffix to scope it
-     * to this component.
-     *
-     * @example
-     * For testId="some-random-id"
-     * The result will be: `some-random-id-modal-panel`
-     */
+    /** Test ID used for e2e testing, passed down from its parent card.*/
     testId?: string;
 };
 
-// TODO[WB-2090]: Update to shared CloseButton component
 export const DismissButton = (props: Props) => {
     const {onClick, style, testId} = props;
     return (