= PolymorphicProps<
+ As,
+ 'div',
+ {
+ /** Optional className for the root element. */
+ className?: string
+
+ /** Internal padding. @default 'normal' */
+ padding?: 'none' | 'condensed' | 'normal'
+
+ /** Border radius. @default 'large' */
+ borderRadius?: 'medium' | 'large'
+
+ /**
+ * Card contents. Provide either `Card.*` subcomponents (e.g. `Card.Heading`,
+ * `Card.Description`, `Card.Metadata`) or custom content. Empty cards do not render.
+ */
+ children: React.ReactNode
+ }
+>
type HeadingLevel = 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
@@ -33,6 +42,9 @@ type HeadingProps = React.ComponentPropsWithoutRef<'h3'> & {
}
type DescriptionProps = React.ComponentPropsWithoutRef<'p'> & {
+ /**
+ * Card description. Rendered as a ``, so keep it to flowing text.
+ */
children: React.ReactNode
}
@@ -60,17 +72,40 @@ type ImageProps = React.ComponentPropsWithoutRef<'img'> & {
}
type MenuProps = {
+ /** Interactive control for the top-right corner of the card. */
children: React.ReactNode
}
type MetadataProps = React.ComponentPropsWithoutRef<'div'> & {
+ /**
+ * Metadata row at the bottom of the card. Any content works: text, icons,
+ * a `Label`, an `Octicon`.
+ */
children: React.ReactNode
}
-const CardImpl = forwardRef(function Card(
- {children, className, padding = 'normal', borderRadius = 'large', ...rest},
- ref,
+function CardComponent(
+ props: CardProps,
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ ref: ForwardedRef,
) {
+ const {
+ children,
+ className,
+ padding = 'normal',
+ borderRadius = 'large',
+ as = 'div',
+ ...rest
+ } = props as CardProps
+ const Component = as as React.ElementType
+ const generatedId = useId()
+ const titleId = as === 'section' ? generatedId : undefined
+
+ // Auto-wire aria-labelledby when as="section" unless consumer provides their own
+ if (as === 'section' && !('aria-label' in props) && !('aria-labelledby' in props)) {
+ ;(rest as Record)['aria-labelledby'] = titleId
+ }
+
let icon: React.ReactNode = null
let image: React.ReactNode = null
let heading: React.ReactNode = null
@@ -100,47 +135,71 @@ const CardImpl = forwardRef(function Card(
const hasSlotChildren = icon || image || heading || description || metadata || menu
+ // `React.Children.toArray` already drops `null`/`undefined`/`false`/`true`,
+ // so an empty array means we have nothing to render.
+ const isEmpty = !hasSlotChildren && childArray.length === 0
+
+ warning(
+ isEmpty,
+ 'The component was rendered with no children and will not render. Provide either Card subcomponents (Card.Heading, Card.Description, etc.) or custom content.',
+ )
+
+ if (isEmpty) {
+ return null
+ }
+
if (!hasSlotChildren) {
return (
-
+
+ {children}
+
+
+ )
+ }
+
+ return (
+
+
- {children}
-
- )
- }
-
- return (
-
- {(image || icon) && (
-
{image || icon}
- )}
-
-
- {heading}
- {description}
+ {(image || icon) && (
+
{image || icon}
+ )}
+
+
+ {heading}
+ {description}
+
+ {metadata ?
{metadata}
: null}
- {metadata ?
{metadata}
: null}
-
- {menu ?
{menu}
: null}
-
+ {menu ?
{menu}
: null}
+
+
)
-})
+}
+
+CardComponent.displayName = 'Card'
-const CardIcon = ({icon: IconComponent, 'aria-label': ariaLabel, className}: IconProps) => {
+const CardImpl = fixedForwardRef(CardComponent)
+
+function CardIcon({icon: IconComponent, 'aria-label': ariaLabel, className}: IconProps) {
return (
{
- return 
+function CardImage({src, alt = '', className, ...rest}: ImageProps) {
+ return (
+
+ )
}
CardImage.displayName = 'Card.Image'
+/**
+ * Heading shown at the top of a Card.
+ *
+ * When the parent Card uses `as="section"`, the heading's `id` is
+ * automatically wired to the section's `aria-labelledby`.
+ */
const CardHeading = forwardRef(function CardHeading(
- {as: Component = 'h3', children, className, ...rest},
+ {as: Component = 'h3', children, className, id, ...rest},
ref,
) {
+ const {titleId} = useContext(CardContext)
return (
-
+
{children}
)
})
+CardHeading.displayName = 'Card.Heading'
+
const CardDescription = forwardRef(function CardDescription(
{children, className, ...rest},
ref,
) {
return (
-
+
{children}
)
})
-const CardMenu = ({children}: MenuProps) => {
- return <>{children}
+CardDescription.displayName = 'Card.Description'
+
+/**
+ * Top-right slot for a single interactive control.
+ *
+ * Give the control a label that names the card (e.g. `"More options for
+ * Project Alpha"`, not just `"More options"`) so users can tell which card
+ * the action applies to when several cards are visible.
+ */
+function CardMenu({children}: MenuProps) {
+ return {children}
}
CardMenu.displayName = 'Card.Menu'
@@ -191,12 +276,14 @@ const CardMetadata = forwardRef(function CardMeta
ref,
) {
return (
-
+
{children}
)
})
+CardMetadata.displayName = 'Card.Metadata'
+
export {CardImpl, CardIcon, CardImage, CardHeading, CardDescription, CardMenu, CardMetadata}
export type {HeadingProps as CardHeadingProps}
export type {DescriptionProps as CardDescriptionProps}