` is a region landmark, so it needs
+ * an accessible name via `aria-label` or `aria-labelledby` (the latter
+ * usually points at `Card.Heading`).
+ */
+type SectionCardProps = BaseCardProps & {
+ as: 'section'
+} & ({'aria-label': string} | {'aria-labelledby': string})
+
+export type CardProps = DivCardProps | SectionCardProps
+
type HeadingLevel = 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
type HeadingProps = React.ComponentPropsWithoutRef<'h3'> & {
@@ -33,6 +61,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 +91,30 @@ type ImageProps = React.ComponentPropsWithoutRef<'img'> & {
}
type MenuProps = {
+ /**
+ * Interactive control in the top-right of the card, usually an `IconButton`
+ * or `ActionMenu` trigger. Give the control a label that names the card
+ * (e.g. `"Options for Project Alpha"`, not just `"Options"`) so it's
+ * distinguishable when several cards are on screen.
+ */
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`. Skip `RelativeTime` for now; it has open
+ * accessibility issues.
+ */
children: React.ReactNode
}
-const CardImpl = forwardRef(function Card(
- {children, className, padding = 'normal', borderRadius = 'large', ...rest},
- ref,
-) {
+const CardImpl = forwardRef(function Card(props, ref) {
+ const {children, className, padding = 'normal', borderRadius = 'large', as = 'div', ...rest} = props
+ // Use ElementType so JSX doesn't intersect the intrinsic prop types of
+ // `div` and `section` (which would pin the ref back to `HTMLDivElement`).
+ const Component = as as React.ElementType
+
let icon: React.ReactNode = null
let image: React.ReactNode = null
let heading: React.ReactNode = null
@@ -100,24 +144,44 @@ 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.',
+ )
+
+ warning(
+ as === 'section' && !('aria-label' in props) && !('aria-labelledby' in props),
+ 'The component used with `as="section"` requires either `aria-label` or `aria-labelledby` so screen-reader users can identify the labelled region. Typically `aria-labelledby` should reference the id of the `Card.Heading`.',
+ )
+
+ if (isEmpty) {
+ return null
+ }
+
if (!hasSlotChildren) {
return (
-
{children}
-
+
)
}
return (
- (function Card(
{metadata ?
{metadata}
: null}
{menu}
: null}
-