[Card]: Spike 1 - Analyse the current implementation

[makafsal]

The problem

Review the current Card implementation after introducing Header, Footer, and the horizontal variant to ensure the architecture is scalable, composable, and aligned with the proposed design before implementing additional features.

The solution

Tasks

• Review all primitive components (Body,Header, Footer, etc.) for consistency, composability, and implementation quality.
• Validate the current API against the original proposal and identify opportunities for simplification or improvement.
• Review the component architecture for scalability, extensibility, and maintainability.
• Verify that the Card follows composability best practices and does not introduce unnecessary coupling.
• Identify any architectural, API, accessibility, or DX improvements.
• Create follow-up issues for improvements that are outside the scope of this spike.
• Document architectural decisions if any changes to the proposal are made.

Acceptance Criteria

1. The current architecture has been reviewed.
2. Any gaps or improvements are documented.
3. Follow-up issues are created for non-blocking improvements.
4. A decision is made whether the architecture is ready for the next phase of implementation.

Design link

No response

Links to other materials

No response

Owner/main maintainer(s)

Carbon for IBM Products

Second/backup maintainer(s)

No response

Product/offering

No response

Business priority

High Priority = pressing release

Code of Conduct

• I agree to follow this project's Code of Conduct
• I checked the current issues for duplicate issues

[makafsal]

Card (next) — React.Children Spike

Problems & Solutions

1 — child.type compared against a displayName string

Files: CardHeader.tsx, Card.tsx

CardHeader detects Card.TitleMedia and Card.Media by comparing
child.type?.['displayName'] to a hardcoded string. A string is fragile.

Fix: Compare child.type directly to the imported component. A reference
is a unique JavaScript object — it can never collide.

// Before
child.type?.['displayName'] === 'Card.TitleMedia'

// After
import { CardTitleMedia } from './CardTitleMedia';
child.type === CardTitleMedia

---

2 — Card.Label and Card.Caption force CardHeader to scan children

File: CardHeader.tsx

CardHeader runs two loops on every render to find and bucket Card.Label
and Card.Caption into the correct DOM positions. This is layout work that
Card.Title should own itself.

Fix: Remove Card.Label and Card.Caption. Add label and description
as optional props on Card.Title — it renders them in the correct positions
internally. CardHeader no longer needs to scan for them.

// Card.Title gains two optional props
label?: ReactNode;       // renders above the title
description?: ReactNode; // renders below the title

// Usage
<Card.Title label="Category" description="Real-time metrics">
  Dashboard
</Card.Title>

---

3 — CardActions reads 3 levels deep into CardAction's internals

File: CardActions.tsx

To populate the overflow menu label, CardActions digs 3 levels into the
internal prop structure of CardAction:

child.props.children.props.label    // 3 levels deep

This breaks silently if CardAction's internal structure changes.

Fix: Card.Actions is designed for Button and IconButton as the only
direct children of Card.Action. Add an optional label prop to CardAction
as an explicit override. If not provided, resolve the label automatically from
the button's own props — one level deep only.

// CardAction gains an optional prop
label?: string; // explicit overflow menu label — used if provided

// CardActions — label resolution order
const button = (child.props as CardActionProps).children;
const buttonProps = (button as any)?.props;

const label =
  (child.props as CardActionProps).label  // explicit override on CardAction
  ?? buttonProps?.label                   // IconButton
  ?? buttonProps?.iconDescription         // Button with hasIconOnly
  ?? (typeof buttonProps?.children === 'string'
      ? buttonProps.children              // Button with text child
      : `Action ${index + 1}`);           // fallback

const id = `${label}-${index}`;           // stable ID derived from resolved label

Usage:

// label auto-resolved from IconButton.label
<Card.Action>
  <IconButton label="Edit" onClick={handleEdit}><Edit /></IconButton>
</Card.Action>

// label auto-resolved from Button's text child
<Card.Action>
  <Button onClick={handleView}>View report</Button>
</Card.Action>

// explicit override — useful when overflow label should differ from button text
<Card.Action label="Edit record">
  <IconButton label="Edit" onClick={handleEdit}><Edit /></IconButton>
</Card.Action>

---

4 — Loops run on every render even when children haven't changed

Files: CardHeader.tsx, CardActions.tsx

CardHeader runs two separate passes over children on every render.
CardActions rebuilds the full action list on every render. Neither result is
cached.

Fix: Wrap both in useMemo([children]) so the work only runs when
children actually change. Also collapse CardHeader's two passes into one
single pass.

---

Summary

Problem	Fix
displayName string comparison	Compare child.type to the imported component directly
Scanning children to find Label and Caption	Remove Card.Label + Card.Caption; add label + description props on Card.Title
3-level prop introspection for overflow label	Optional label on Card.Action; auto-resolve from button props one level deep
Unstable action IDs	Derive ID from resolved label — \${label}-${index}``
Loops re-run on every render	Wrap in useMemo([children])