Card

1import {
2  useId,
3  type HTMLAttributes,
4  type MouseEventHandler,
5  type ReactNode,
6} from "react";
7import { getClassName } from "@bht-component-registry/class-names";
8import styles from "./card.module.scss";
9
10export type CardPadding = "none" | "sm" | "md" | "lg";
11export type CardHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
12
13export interface CardProps extends Omit<
14  HTMLAttributes<HTMLDivElement>,
15  "title" | "onSelect"
16> {
17  /** Controls internal padding; defaults to none so consumers opt in. Applies to the body when a header is present. */
18  padding?: CardPadding;
19  /** Optional icon rendered before the title in the header */
20  icon?: ReactNode;
21  /** Optional header title; omit along with `icon`/`action` to render no header */
22  title?: ReactNode;
23  /**
24   * Which heading tag (`h1`–`h6`) wraps `title`, so the card's title takes its
25   * correct place in the page's heading outline. Defaults to `3`, matching a
26   * card nested one level below a page's `h1` title and a `section`'s `h2` —
27   * override per-instance when a card sits at a different depth.
28   */
29  headingLevel?: CardHeadingLevel;
30  /** Optional content rendered at the end of the header (buttons, menus, a close control, etc.) */
31  action?: ReactNode;
32  /**
33   * Makes the body a real `<button>` — hover/focus affordance plus a centered,
34   * stacked content layout — for tile/action-card patterns (a picker grid,
35   * for example) instead of a static surface. Distinct from `onClick` (a plain
36   * pass-through to the root element, e.g. for stopping click propagation).
37   * Omit for a plain, non-interactive card.
38   */
39  onSelect?: MouseEventHandler<HTMLButtonElement>;
40  /**
41   * For a toggle tile (a multi-select picker): sets `aria-pressed` on the body
42   * button. Only meaningful together with `onSelect`; leave undefined for a
43   * plain action card, which then has no `aria-pressed` at all.
44   */
45  pressed?: boolean;
46  /**
47   * Keeps the header fixed and scrolls only the body when content exceeds the
48   * card's height. Only meaningful when the card has a bounded height (a
49   * modal or drawer panel, for example).
50   */
51  scrollableBody?: boolean;
52  /** Additional class names to merge with the component root element */
53  className?: string;
54  /** Card body content */
55  children?: ReactNode;
56}
57
58export const Card = ({
59  padding = "none",
60  icon,
61  title,
62  headingLevel = 3,
63  action,
64  onSelect,
65  pressed,
66  scrollableBody = false,
67  className,
68  children,
69  ...rest
70}: CardProps) => {
71  const generatedTitleId = useId();
72  const hasHeader =
73    icon !== undefined || title !== undefined || action !== undefined;
74  const hasTitle = title !== undefined;
75  const interactive = onSelect !== undefined;
76  const HeadingTag = `h${headingLevel}` as React.ElementType;
77  // A section with no accessible name is not a meaningful landmark, so only
78  // use <section> when there's an actual heading (title) to name it with.
79  const RootTag = (hasTitle ? "section" : "div") as React.ElementType;
80  const titleId = hasTitle ? `${generatedTitleId}-title` : undefined;
81
82  const [rootClass, getChildClass] = getClassName({
83    className,
84    rootClass: "BHT__Card",
85    modifiers: {
86      [`padding-${padding}`]: true,
87      interactive,
88      "scrollable-body": scrollableBody,
89    },
90    styles,
91  });
92
93  const BodyTag = (interactive ? "button" : "div") as React.ElementType;
94
95  return (
96    <RootTag {...rest} className={rootClass} aria-labelledby={titleId}>
97      {hasHeader && (
98        <div className={getChildClass("header")}>
99          <span className={getChildClass("heading")}>
100            {icon !== undefined && (
101              <span className={getChildClass("icon")}>{icon}</span>
102            )}
103            {hasTitle && (
104              <HeadingTag id={titleId} className={getChildClass("title")}>
105                {title}
106              </HeadingTag>
107            )}
108          </span>
109          {action !== undefined && (
110            <span className={getChildClass("action")}>{action}</span>
111          )}
112        </div>
113      )}
114      <BodyTag
115        type={interactive ? "button" : undefined}
116        onClick={onSelect}
117        aria-pressed={interactive ? pressed : undefined}
118        className={getChildClass("body-padding")}
119      >
120        {children}
121      </BodyTag>
122    </RootTag>
123  );
124};

1// Material Design 3 outlined card.
2//
3// Modal and Drawer render their panels as a Card and re-theme it through the
4// `--card-background` / `--card-border` / `--card-radius` custom properties
5// rather than by reaching into these classes, so those three stay the only
6// public styling hooks. Each color falls back to the pre-MD3 `--color-*` name,
7// which `cms.base-styles` aliases to the matching MD3 role.
8
9.BHT__Card {
10  background: var(
11    --card-background,
12    var(--md-sys-color-surface, var(--color-surface))
13  );
14  color: var(--md-sys-color-on-surface, var(--color-on-surface));
15  border: var(
16    --card-border,
17    1px solid var(--md-sys-color-outline-variant, var(--color-border))
18  );
19  border-radius: var(--card-radius, var(--md-sys-shape-corner-medium, 12px));
20  // Grid/flex items default to their content's min-content width, not their
21  // track/basis minimum — without this, a Card holding wide content (a long
22  // stat value, an action row) forces its container wider instead of shrinking.
23  min-width: 0;
24
25  &__header {
26    padding: var(--spacing-4) var(--spacing-6);
27    border-bottom: 1px solid
28      var(--md-sys-color-outline-variant, var(--color-border));
29    display: flex;
30    align-items: center;
31    justify-content: space-between;
32    gap: var(--spacing-4);
33  }
34
35  &__heading {
36    display: flex;
37    align-items: center;
38    gap: var(--spacing-2);
39    min-width: 0;
40  }
41
42  &__icon {
43    display: inline-flex;
44    line-height: 1;
45  }
46
47  &__title {
48    margin: 0;
49    font-family: var(--md-sys-typescale-title-medium-font, var(--font-heading));
50    font-size: var(--md-sys-typescale-title-medium-size, 1rem);
51    font-weight: var(--md-sys-typescale-title-medium-weight, 500);
52    line-height: var(--md-sys-typescale-title-medium-line-height, 1.5rem);
53    letter-spacing: var(--md-sys-typescale-title-medium-tracking, 0.0094em);
54    color: var(--md-sys-color-on-surface, var(--color-text-heading));
55    overflow: hidden;
56    text-overflow: ellipsis;
57    white-space: nowrap;
58  }
59
60  &__action {
61    display: inline-flex;
62    align-items: center;
63    gap: var(--spacing-2);
64    flex-shrink: 0;
65  }
66
67  &__body-padding {
68    /* Resets so this works whether it renders as a <div> (static) or a
69       <button> (interactive) — the button UA defaults are what actually
70       need overriding here. */
71    display: block;
72    width: 100%;
73    padding: 0;
74    margin: 0;
75    background: none;
76    border: none;
77    font: inherit;
78    color: inherit;
79    text-align: inherit;
80  }
81
82  &--interactive {
83    &.BHT__Card {
84      overflow: hidden;
85    }
86
87    .BHT__Card {
88      &__body-padding {
89        position: relative;
90        isolation: isolate;
91        display: flex;
92        flex-direction: column;
93        align-items: center;
94        gap: var(--spacing-2);
95        text-align: center;
96        cursor: pointer;
97
98        // State layer: a veil of the content color, as on Button, so hover and
99        // press follow the palette instead of swapping to a fixed surface.
100        &::after {
101          content: "";
102          position: absolute;
103          inset: 0;
104          background: currentColor;
105          opacity: 0;
106          pointer-events: none;
107          transition: opacity var(--md-sys-motion-duration-short-2, 100ms)
108            var(--md-sys-motion-easing-standard, ease);
109        }
110
111        &:hover::after {
112          opacity: var(--md-sys-state-hover-opacity, 0.08);
113        }
114
115        &:focus-visible::after {
116          opacity: var(--md-sys-state-focus-opacity, 0.1);
117        }
118
119        &:active::after {
120          opacity: var(--md-sys-state-pressed-opacity, 0.1);
121        }
122
123        // Inset rather than the usual +2px offset: the root's `overflow:
124        // hidden` (needed to clip the state layer to the corners) would cut
125        // off a ring drawn outside the body.
126        &:focus-visible {
127          outline: 3px solid
128            var(--md-sys-color-secondary, var(--color-border-focus));
129          outline-offset: -3px;
130        }
131      }
132    }
133  }
134
135  // Header stays put; only the body scrolls when content exceeds the card's
136  // height — for cards given a bounded height (a modal or drawer panel).
137  &--scrollable-body {
138    &.BHT__Card {
139      display: flex;
140      flex-direction: column;
141      overflow: hidden;
142    }
143
144    .BHT__Card {
145      &__body-padding {
146        overflow-y: auto;
147        flex: 1;
148        min-height: 0;
149      }
150    }
151  }
152
153  // &--padding-none needs no rule — &__body-padding already resets padding to 0 above.
154
155  &--padding-sm {
156    .BHT__Card {
157      &__body-padding {
158        padding: var(--spacing-3);
159      }
160    }
161  }
162
163  &--padding-md {
164    .BHT__Card {
165      &__body-padding {
166        padding: var(--spacing-5);
167      }
168    }
169  }
170
171  &--padding-lg {
172    .BHT__Card {
173      &__body-padding {
174        padding: var(--spacing-8);
175      }
176    }
177  }
178}

1export { Card } from "./card.js";
2export type { CardProps, CardPadding, CardHeadingLevel } from "./card.js";

1import { Card } from "./card.js";
2
3export const DefaultCard = () => (
4  <Card padding="md">Default card with md padding</Card>
5);
6
7export const NoPaddingCard = () => (
8  <Card padding="none">Card with no padding</Card>
9);
10
11export const SmallPaddingCard = () => (
12  <Card padding="sm">Card with sm padding</Card>
13);
14
15export const LargePaddingCard = () => (
16  <Card padding="lg">Card with lg padding</Card>
17);
18
19export const CardWithHeader = () => (
20  <Card title="Settings" padding="md">
21    Card body content
22  </Card>
23);
24
25export const CardWithIconAndAction = () => (
26  <Card
27    icon="🧩"
28    title="Block"
29    action={<button onClick={() => {}}>✕</button>}
30    padding="md"
31  >
32    Card body content
33  </Card>
34);
35
36export const InteractiveCard = () => (
37  <Card padding="md" onSelect={() => {}}>
38    <span>🧩</span>
39    <span>Click me</span>
40  </Card>
41);
42
43export const CardAsPageLevelSection = () => (
44  <Card title="Settings" headingLevel={2} padding="md">
45    Used directly under a page&rsquo;s h1, with no intervening section — its
46    title takes the h2 slot instead of the h3 default.
47  </Card>
48);