@behivetech/atoms.card 0.0.0-stage → 0.4.2

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# Card
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A surface container with configurable padding and an optional header (icon + title + an `action` slot).
+
+## Usage
+
+```jsx
+import { Card } from "@behivetech/atoms.card";
+
+function Example() {
+  const onClose = () => alert("closed");
+  return (
+    <>
+      <Card padding="md">Content</Card>
+
+      <Card title="Settings" padding="md">
+        Content
+      </Card>
+
+      <Card
+        icon="🧩"
+        title="Block"
+        action={<button onClick={onClose}>✕</button>}
+        padding="md"
+      >
+        Content
+      </Card>
+    </>
+  );
+}
+```
+
+The `action` slot is freeform — pass a close button, a menu, multiple buttons, or nothing. If `icon`, `title`, and `action` are all omitted, no header is rendered and `children` render directly in the card (unchanged from a plain `Card`). When a header is present, `padding` applies to the body instead of the whole card, so the header can span edge-to-edge with its own fixed padding.
+
+## Heading level
+
+`title` renders inside an `h1`–`h6` tag (not a `span`) so it takes its correct place in the page's heading outline — set via `headingLevel`, which defaults to `3`. The default assumes the common case: a page's own `h1`, sections within it titled `h2`, and a `Card` nested inside one of those sections landing at `h3`. Override it when a card sits at a different depth — e.g. `headingLevel={2}` for a card used directly under a page's `h1` with no intervening section:
+
+```jsx
+<Card title="Settings" headingLevel={2} padding="md">
+  Content
+</Card>
+```
+
+## Root element
+
+The root renders as a `<section>`, labelled by `title` via `aria-labelledby`, whenever a `title` is given — an HTML5 `<section>` should have an accessible heading, and `title` is exactly that. With no `title` (a bare surface, or a header made up of just `icon`/`action`), the root stays a plain `<div>`, since an unlabelled `<section>` isn't a meaningful landmark.
+
+## Interactive (clickable) cards
+
+Pass `onSelect` to turn the body into a real `<button>` — hover/focus affordance plus a centered, stacked content layout — for tile/action-card patterns like a component picker grid:
+
+```jsx
+import { Card } from "@behivetech/atoms.card";
+import { Icon } from "@behivetech/atoms.icon";
+
+function Example() {
+  const item = { name: "Hero banner" };
+  const handleSelect = (selected) => alert(selected.name);
+  return (
+    <Card padding="md" onSelect={() => handleSelect(item)}>
+      <Icon name="box" size="lg" />
+      <span>{item.name}</span>
+    </Card>
+  );
+}
+```
+
+This is the same job MUI's `CardActionArea` does, folded into `Card` itself rather than a separate component — `children` must stay to phrasing content (text, spans, icons), since a native `<button>` can't contain block-level elements like `<div>`. `onSelect` is deliberately distinct from `onClick`: `onClick` is the plain pass-through to the root element (e.g. to stop click propagation on a whole panel), while `onSelect` specifically drives the interactive-body behavior described here.
+
+## Overriding surface styling
+
+`background`/`border`/`border-radius` read from `--card-background`/`--card-border`/`--card-radius` custom properties (falling back to the design tokens above). A consumer embedding a `Card` for a different context — a docked panel with no elevation, a modal with a larger radius — can set these on its own wrapping class instead of fighting CSS-module specificity:
+
+```scss
+.my-docked-panel {
+  --card-border: none;
+  --card-radius: 0;
+}
+```
+
+## Props
+
+| Prop             | Type                                   | Default | Description                                                                                   |
+| ---------------- | -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `padding`        | `none \| sm \| md \| lg`               | `none`  | Internal padding — applies to the body when a header is present                               |
+| `icon`           | `ReactNode`                            | —       | Optional icon rendered before the title                                                       |
+| `title`          | `ReactNode`                            | —       | Optional header title                                                                         |
+| `headingLevel`   | `1 \| 2 \| 3 \| 4 \| 5 \| 6`           | `3`     | Which heading tag wraps `title`                                                               |
+| `action`         | `ReactNode`                            | —       | Optional content rendered at the end of the header                                            |
+| `onSelect`       | `MouseEventHandler<HTMLButtonElement>` | —       | Makes the body a clickable `<button>` with hover/focus affordance and a centered stack layout |
+| `scrollableBody` | `boolean`                              | `false` | Keeps the header fixed and scrolls only the body; for cards with a bounded height             |
+| `children`       | `ReactNode`                            | —       | Card content                                                                                  |
+| `className`      | `string`                               | —       | Additional class names                                                                        |

package/card.example.tsx

@@ -0,0 +1,48 @@
+import { Card } from "./card.js";
+
+export const DefaultCard = () => (
+  <Card padding="md">Default card with md padding</Card>
+);
+
+export const NoPaddingCard = () => (
+  <Card padding="none">Card with no padding</Card>
+);
+
+export const SmallPaddingCard = () => (
+  <Card padding="sm">Card with sm padding</Card>
+);
+
+export const LargePaddingCard = () => (
+  <Card padding="lg">Card with lg padding</Card>
+);
+
+export const CardWithHeader = () => (
+  <Card title="Settings" padding="md">
+    Card body content
+  </Card>
+);
+
+export const CardWithIconAndAction = () => (
+  <Card
+    icon="🧩"
+    title="Block"
+    action={<button onClick={() => {}}>✕</button>}
+    padding="md"
+  >
+    Card body content
+  </Card>
+);
+
+export const InteractiveCard = () => (
+  <Card padding="md" onSelect={() => {}}>
+    <span>🧩</span>
+    <span>Click me</span>
+  </Card>
+);
+
+export const CardAsPageLevelSection = () => (
+  <Card title="Settings" headingLevel={2} padding="md">
+    Used directly under a page&rsquo;s h1, with no intervening section — its
+    title takes the h2 slot instead of the h3 default.
+  </Card>
+);

package/card.module.scss

@@ -0,0 +1,178 @@
+// Material Design 3 outlined card.
+//
+// Modal and Drawer render their panels as a Card and re-theme it through the
+// `--card-background` / `--card-border` / `--card-radius` custom properties
+// rather than by reaching into these classes, so those three stay the only
+// public styling hooks. Each color falls back to the pre-MD3 `--color-*` name,
+// which `cms.base-styles` aliases to the matching MD3 role.
+
+.BHT__Card {
+  background: var(
+    --card-background,
+    var(--md-sys-color-surface, var(--color-surface))
+  );
+  color: var(--md-sys-color-on-surface, var(--color-on-surface));
+  border: var(
+    --card-border,
+    1px solid var(--md-sys-color-outline-variant, var(--color-border))
+  );
+  border-radius: var(--card-radius, var(--md-sys-shape-corner-medium, 12px));
+  // Grid/flex items default to their content's min-content width, not their
+  // track/basis minimum — without this, a Card holding wide content (a long
+  // stat value, an action row) forces its container wider instead of shrinking.
+  min-width: 0;
+
+  &__header {
+    padding: var(--spacing-4) var(--spacing-6);
+    border-bottom: 1px solid
+      var(--md-sys-color-outline-variant, var(--color-border));
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--spacing-4);
+  }
+
+  &__heading {
+    display: flex;
+    align-items: center;
+    gap: var(--spacing-2);
+    min-width: 0;
+  }
+
+  &__icon {
+    display: inline-flex;
+    line-height: 1;
+  }
+
+  &__title {
+    margin: 0;
+    font-family: var(--md-sys-typescale-title-medium-font, var(--font-heading));
+    font-size: var(--md-sys-typescale-title-medium-size, 1rem);
+    font-weight: var(--md-sys-typescale-title-medium-weight, 500);
+    line-height: var(--md-sys-typescale-title-medium-line-height, 1.5rem);
+    letter-spacing: var(--md-sys-typescale-title-medium-tracking, 0.0094em);
+    color: var(--md-sys-color-on-surface, var(--color-text-heading));
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__action {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--spacing-2);
+    flex-shrink: 0;
+  }
+
+  &__body-padding {
+    /* Resets so this works whether it renders as a <div> (static) or a
+       <button> (interactive) — the button UA defaults are what actually
+       need overriding here. */
+    display: block;
+    width: 100%;
+    padding: 0;
+    margin: 0;
+    background: none;
+    border: none;
+    font: inherit;
+    color: inherit;
+    text-align: inherit;
+  }
+
+  &--interactive {
+    &.BHT__Card {
+      overflow: hidden;
+    }
+
+    .BHT__Card {
+      &__body-padding {
+        position: relative;
+        isolation: isolate;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: var(--spacing-2);
+        text-align: center;
+        cursor: pointer;
+
+        // State layer: a veil of the content color, as on Button, so hover and
+        // press follow the palette instead of swapping to a fixed surface.
+        &::after {
+          content: "";
+          position: absolute;
+          inset: 0;
+          background: currentColor;
+          opacity: 0;
+          pointer-events: none;
+          transition: opacity var(--md-sys-motion-duration-short-2, 100ms)
+            var(--md-sys-motion-easing-standard, ease);
+        }
+
+        &:hover::after {
+          opacity: var(--md-sys-state-hover-opacity, 0.08);
+        }
+
+        &:focus-visible::after {
+          opacity: var(--md-sys-state-focus-opacity, 0.1);
+        }
+
+        &:active::after {
+          opacity: var(--md-sys-state-pressed-opacity, 0.1);
+        }
+
+        // Inset rather than the usual +2px offset: the root's `overflow:
+        // hidden` (needed to clip the state layer to the corners) would cut
+        // off a ring drawn outside the body.
+        &:focus-visible {
+          outline: 3px solid
+            var(--md-sys-color-secondary, var(--color-border-focus));
+          outline-offset: -3px;
+        }
+      }
+    }
+  }
+
+  // Header stays put; only the body scrolls when content exceeds the card's
+  // height — for cards given a bounded height (a modal or drawer panel).
+  &--scrollable-body {
+    &.BHT__Card {
+      display: flex;
+      flex-direction: column;
+      overflow: hidden;
+    }
+
+    .BHT__Card {
+      &__body-padding {
+        overflow-y: auto;
+        flex: 1;
+        min-height: 0;
+      }
+    }
+  }
+
+  // &--padding-none needs no rule — &__body-padding already resets padding to 0 above.
+
+  &--padding-sm {
+    .BHT__Card {
+      &__body-padding {
+        padding: var(--spacing-3);
+      }
+    }
+  }
+
+  &--padding-md {
+    .BHT__Card {
+      &__body-padding {
+        padding: var(--spacing-5);
+      }
+    }
+  }
+
+  &--padding-lg {
+    .BHT__Card {
+      &__body-padding {
+        padding: var(--spacing-8);
+      }
+    }
+  }
+}

package/card.tsx

@@ -0,0 +1,116 @@
+import {
+  useId,
+  type HTMLAttributes,
+  type MouseEventHandler,
+  type ReactNode,
+} from "react";
+import { getClassName } from "@bht-component-registry/class-names";
+import styles from "./card.module.scss";
+
+export type CardPadding = "none" | "sm" | "md" | "lg";
+export type CardHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export interface CardProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "title" | "onSelect"
+> {
+  /** Controls internal padding; defaults to none so consumers opt in. Applies to the body when a header is present. */
+  padding?: CardPadding;
+  /** Optional icon rendered before the title in the header */
+  icon?: ReactNode;
+  /** Optional header title; omit along with `icon`/`action` to render no header */
+  title?: ReactNode;
+  /**
+   * Which heading tag (`h1`–`h6`) wraps `title`, so the card's title takes its
+   * correct place in the page's heading outline. Defaults to `3`, matching a
+   * card nested one level below a page's `h1` title and a `section`'s `h2` —
+   * override per-instance when a card sits at a different depth.
+   */
+  headingLevel?: CardHeadingLevel;
+  /** Optional content rendered at the end of the header (buttons, menus, a close control, etc.) */
+  action?: ReactNode;
+  /**
+   * Makes the body a real `<button>` — hover/focus affordance plus a centered,
+   * stacked content layout — for tile/action-card patterns (a picker grid,
+   * for example) instead of a static surface. Distinct from `onClick` (a plain
+   * pass-through to the root element, e.g. for stopping click propagation).
+   * Omit for a plain, non-interactive card.
+   */
+  onSelect?: MouseEventHandler<HTMLButtonElement>;
+  /**
+   * Keeps the header fixed and scrolls only the body when content exceeds the
+   * card's height. Only meaningful when the card has a bounded height (a
+   * modal or drawer panel, for example).
+   */
+  scrollableBody?: boolean;
+  /** Additional class names to merge with the component root element */
+  className?: string;
+  /** Card body content */
+  children?: ReactNode;
+}
+
+export const Card = ({
+  padding = "none",
+  icon,
+  title,
+  headingLevel = 3,
+  action,
+  onSelect,
+  scrollableBody = false,
+  className,
+  children,
+  ...rest
+}: CardProps) => {
+  const generatedTitleId = useId();
+  const hasHeader =
+    icon !== undefined || title !== undefined || action !== undefined;
+  const hasTitle = title !== undefined;
+  const interactive = onSelect !== undefined;
+  const HeadingTag = `h${headingLevel}` as React.ElementType;
+  // A section with no accessible name is not a meaningful landmark, so only
+  // use <section> when there's an actual heading (title) to name it with.
+  const RootTag = (hasTitle ? "section" : "div") as React.ElementType;
+  const titleId = hasTitle ? `${generatedTitleId}-title` : undefined;
+
+  const [rootClass, getChildClass] = getClassName({
+    className,
+    rootClass: "BHT__Card",
+    modifiers: {
+      [`padding-${padding}`]: true,
+      interactive,
+      "scrollable-body": scrollableBody,
+    },
+    styles,
+  });
+
+  const BodyTag = (interactive ? "button" : "div") as React.ElementType;
+
+  return (
+    <RootTag {...rest} className={rootClass} aria-labelledby={titleId}>
+      {hasHeader && (
+        <div className={getChildClass("header")}>
+          <span className={getChildClass("heading")}>
+            {icon !== undefined && (
+              <span className={getChildClass("icon")}>{icon}</span>
+            )}
+            {hasTitle && (
+              <HeadingTag id={titleId} className={getChildClass("title")}>
+                {title}
+              </HeadingTag>
+            )}
+          </span>
+          {action !== undefined && (
+            <span className={getChildClass("action")}>{action}</span>
+          )}
+        </div>
+      )}
+      <BodyTag
+        type={interactive ? "button" : undefined}
+        onClick={onSelect}
+        className={getChildClass("body-padding")}
+      >
+        {children}
+      </BodyTag>
+    </RootTag>
+  );
+};

package/dist/index.cjs

@@ -0,0 +1,219 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// ../../../../node_modules/.pnpm/classnames@2.5.1/node_modules/classnames/index.js
+var require_classnames = __commonJS({
+  "../../../../node_modules/.pnpm/classnames@2.5.1/node_modules/classnames/index.js"(exports2, module2) {
+    "use strict";
+    (function() {
+      "use strict";
+      var hasOwn = {}.hasOwnProperty;
+      function classNames() {
+        var classes = "";
+        for (var i = 0; i < arguments.length; i++) {
+          var arg = arguments[i];
+          if (arg) {
+            classes = appendClass(classes, parseValue(arg));
+          }
+        }
+        return classes;
+      }
+      function parseValue(arg) {
+        if (typeof arg === "string" || typeof arg === "number") {
+          return arg;
+        }
+        if (typeof arg !== "object") {
+          return "";
+        }
+        if (Array.isArray(arg)) {
+          return classNames.apply(null, arg);
+        }
+        if (arg.toString !== Object.prototype.toString && !arg.toString.toString().includes("[native code]")) {
+          return arg.toString();
+        }
+        var classes = "";
+        for (var key in arg) {
+          if (hasOwn.call(arg, key) && arg[key]) {
+            classes = appendClass(classes, key);
+          }
+        }
+        return classes;
+      }
+      function appendClass(value, newClass) {
+        if (!newClass) {
+          return value;
+        }
+        if (value) {
+          return value + " " + newClass;
+        }
+        return value + newClass;
+      }
+      if (typeof module2 !== "undefined" && module2.exports) {
+        classNames.default = classNames;
+        module2.exports = classNames;
+      } else if (typeof define === "function" && typeof define.amd === "object" && define.amd) {
+        define("classnames", [], function() {
+          return classNames;
+        });
+      } else {
+        window.classNames = classNames;
+      }
+    })();
+  }
+});
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  Card: () => Card
+});
+module.exports = __toCommonJS(index_exports);
+
+// card.tsx
+var import_react = require("react");
+
+// ../../../../packages/registry/class-names/dist/index.js
+var import_classnames = __toESM(require_classnames(), 1);
+var getClassName = ({
+  className,
+  modifiers = {},
+  rootClass,
+  styles = {}
+}) => {
+  function getModifiers() {
+    const updatedModifiers = {};
+    const modifierKeys = Object.keys(modifiers);
+    if (modifierKeys.length) {
+      modifierKeys.forEach((modKey) => {
+        const classKey = `${rootClass}--${modKey}`;
+        const newClassName = styles[classKey] || classKey;
+        updatedModifiers[newClassName] = modifiers[modKey] ?? false;
+      });
+    }
+    return updatedModifiers;
+  }
+  function getChildClass(childClassName) {
+    const classKey = `${rootClass}__${childClassName}`;
+    return styles[classKey] || classKey;
+  }
+  function getRootStyles() {
+    return (0, import_classnames.default)(
+      className,
+      {
+        ...getModifiers()
+      },
+      styles[rootClass] || rootClass
+    );
+  }
+  return [getRootStyles(), getChildClass];
+};
+
+// card.module.scss
+var card_module_default = {
+  "BHT__Card": "BHT__Card",
+  "BHT__Card__header": "BHT__Card__header",
+  "BHT__Card__heading": "BHT__Card__heading",
+  "BHT__Card__icon": "BHT__Card__icon",
+  "BHT__Card__title": "BHT__Card__title",
+  "BHT__Card__action": "BHT__Card__action",
+  "BHT__Card__body-padding": "BHT__Card__body-padding",
+  "BHT__Card--interactive": "BHT__Card--interactive",
+  "BHT__Card--scrollable-body": "BHT__Card--scrollable-body",
+  "BHT__Card--padding-sm": "BHT__Card--padding-sm",
+  "BHT__Card--padding-md": "BHT__Card--padding-md",
+  "BHT__Card--padding-lg": "BHT__Card--padding-lg"
+};
+
+// card.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var Card = ({
+  padding = "none",
+  icon,
+  title,
+  headingLevel = 3,
+  action,
+  onSelect,
+  scrollableBody = false,
+  className,
+  children,
+  ...rest
+}) => {
+  const generatedTitleId = (0, import_react.useId)();
+  const hasHeader = icon !== void 0 || title !== void 0 || action !== void 0;
+  const hasTitle = title !== void 0;
+  const interactive = onSelect !== void 0;
+  const HeadingTag = `h${headingLevel}`;
+  const RootTag = hasTitle ? "section" : "div";
+  const titleId = hasTitle ? `${generatedTitleId}-title` : void 0;
+  const [rootClass, getChildClass] = getClassName({
+    className,
+    rootClass: "BHT__Card",
+    modifiers: {
+      [`padding-${padding}`]: true,
+      interactive,
+      "scrollable-body": scrollableBody
+    },
+    styles: card_module_default
+  });
+  const BodyTag = interactive ? "button" : "div";
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(RootTag, { ...rest, className: rootClass, "aria-labelledby": titleId, children: [
+    hasHeader && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: getChildClass("header"), children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { className: getChildClass("heading"), children: [
+        icon !== void 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: getChildClass("icon"), children: icon }),
+        hasTitle && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(HeadingTag, { id: titleId, className: getChildClass("title"), children: title })
+      ] }),
+      action !== void 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: getChildClass("action"), children: action })
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      BodyTag,
+      {
+        type: interactive ? "button" : void 0,
+        onClick: onSelect,
+        className: getChildClass("body-padding"),
+        children
+      }
+    )
+  ] });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Card
+});
+/*! Bundled license information:
+
+classnames/index.js:
+  (*!
+  	Copyright (c) 2018 Jed Watson.
+  	Licensed under the MIT License (MIT), see
+  	http://jedwatson.github.io/classnames
+  *)
+*/

package/dist/index.css

@@ -0,0 +1,111 @@
+@charset "UTF-8";
+
+/* esbuild-sass-plugin:css-chunkcard.module.scss */
+.BHT__Card {
+  background: var(--card-background, var(--md-sys-color-surface, var(--color-surface)));
+  color: var(--md-sys-color-on-surface, var(--color-on-surface));
+  border: var(--card-border, 1px solid var(--md-sys-color-outline-variant, var(--color-border)));
+  border-radius: var(--card-radius, var(--md-sys-shape-corner-medium, 12px));
+  min-width: 0;
+}
+.BHT__Card__header {
+  padding: var(--spacing-4) var(--spacing-6);
+  border-bottom: 1px solid var(--md-sys-color-outline-variant, var(--color-border));
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-4);
+}
+.BHT__Card__heading {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  min-width: 0;
+}
+.BHT__Card__icon {
+  display: inline-flex;
+  line-height: 1;
+}
+.BHT__Card__title {
+  margin: 0;
+  font-family: var(--md-sys-typescale-title-medium-font, var(--font-heading));
+  font-size: var(--md-sys-typescale-title-medium-size, 1rem);
+  font-weight: var(--md-sys-typescale-title-medium-weight, 500);
+  line-height: var(--md-sys-typescale-title-medium-line-height, 1.5rem);
+  letter-spacing: var(--md-sys-typescale-title-medium-tracking, 0.0094em);
+  color: var(--md-sys-color-on-surface, var(--color-text-heading));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.BHT__Card__action {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  flex-shrink: 0;
+}
+.BHT__Card__body-padding {
+  display: block;
+  width: 100%;
+  padding: 0;
+  margin: 0;
+  background: none;
+  border: none;
+  font: inherit;
+  color: inherit;
+  text-align: inherit;
+}
+.BHT__Card--interactive.BHT__Card {
+  overflow: hidden;
+}
+.BHT__Card--interactive .BHT__Card__body-padding {
+  position: relative;
+  isolation: isolate;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--spacing-2);
+  text-align: center;
+  cursor: pointer;
+}
+.BHT__Card--interactive .BHT__Card__body-padding::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: currentColor;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity var(--md-sys-motion-duration-short-2, 100ms) var(--md-sys-motion-easing-standard, ease);
+}
+.BHT__Card--interactive .BHT__Card__body-padding:hover::after {
+  opacity: var(--md-sys-state-hover-opacity, 0.08);
+}
+.BHT__Card--interactive .BHT__Card__body-padding:focus-visible::after {
+  opacity: var(--md-sys-state-focus-opacity, 0.1);
+}
+.BHT__Card--interactive .BHT__Card__body-padding:active::after {
+  opacity: var(--md-sys-state-pressed-opacity, 0.1);
+}
+.BHT__Card--interactive .BHT__Card__body-padding:focus-visible {
+  outline: 3px solid var(--md-sys-color-secondary, var(--color-border-focus));
+  outline-offset: -3px;
+}
+.BHT__Card--scrollable-body.BHT__Card {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.BHT__Card--scrollable-body .BHT__Card__body-padding {
+  overflow-y: auto;
+  flex: 1;
+  min-height: 0;
+}
+.BHT__Card--padding-sm .BHT__Card__body-padding {
+  padding: var(--spacing-3);
+}
+.BHT__Card--padding-md .BHT__Card__body-padding {
+  padding: var(--spacing-5);
+}
+.BHT__Card--padding-lg .BHT__Card__body-padding {
+  padding: var(--spacing-8);
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode, MouseEventHandler } from 'react';
+
+type CardPadding = "none" | "sm" | "md" | "lg";
+type CardHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, "title" | "onSelect"> {
+    /** Controls internal padding; defaults to none so consumers opt in. Applies to the body when a header is present. */
+    padding?: CardPadding;
+    /** Optional icon rendered before the title in the header */
+    icon?: ReactNode;
+    /** Optional header title; omit along with `icon`/`action` to render no header */
+    title?: ReactNode;
+    /**
+     * Which heading tag (`h1`–`h6`) wraps `title`, so the card's title takes its
+     * correct place in the page's heading outline. Defaults to `3`, matching a
+     * card nested one level below a page's `h1` title and a `section`'s `h2` —
+     * override per-instance when a card sits at a different depth.
+     */
+    headingLevel?: CardHeadingLevel;
+    /** Optional content rendered at the end of the header (buttons, menus, a close control, etc.) */
+    action?: ReactNode;
+    /**
+     * Makes the body a real `<button>` — hover/focus affordance plus a centered,
+     * stacked content layout — for tile/action-card patterns (a picker grid,
+     * for example) instead of a static surface. Distinct from `onClick` (a plain
+     * pass-through to the root element, e.g. for stopping click propagation).
+     * Omit for a plain, non-interactive card.
+     */
+    onSelect?: MouseEventHandler<HTMLButtonElement>;
+    /**
+     * Keeps the header fixed and scrolls only the body when content exceeds the
+     * card's height. Only meaningful when the card has a bounded height (a
+     * modal or drawer panel, for example).
+     */
+    scrollableBody?: boolean;
+    /** Additional class names to merge with the component root element */
+    className?: string;
+    /** Card body content */
+    children?: ReactNode;
+}
+declare const Card: ({ padding, icon, title, headingLevel, action, onSelect, scrollableBody, className, children, ...rest }: CardProps) => react.JSX.Element;
+
+export { Card, type CardHeadingLevel, type CardPadding, type CardProps };

package/dist/index.js

@@ -0,0 +1,207 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// ../../../../node_modules/.pnpm/classnames@2.5.1/node_modules/classnames/index.js
+var require_classnames = __commonJS({
+  "../../../../node_modules/.pnpm/classnames@2.5.1/node_modules/classnames/index.js"(exports, module) {
+    "use strict";
+    (function() {
+      "use strict";
+      var hasOwn = {}.hasOwnProperty;
+      function classNames() {
+        var classes = "";
+        for (var i = 0; i < arguments.length; i++) {
+          var arg = arguments[i];
+          if (arg) {
+            classes = appendClass(classes, parseValue(arg));
+          }
+        }
+        return classes;
+      }
+      function parseValue(arg) {
+        if (typeof arg === "string" || typeof arg === "number") {
+          return arg;
+        }
+        if (typeof arg !== "object") {
+          return "";
+        }
+        if (Array.isArray(arg)) {
+          return classNames.apply(null, arg);
+        }
+        if (arg.toString !== Object.prototype.toString && !arg.toString.toString().includes("[native code]")) {
+          return arg.toString();
+        }
+        var classes = "";
+        for (var key in arg) {
+          if (hasOwn.call(arg, key) && arg[key]) {
+            classes = appendClass(classes, key);
+          }
+        }
+        return classes;
+      }
+      function appendClass(value, newClass) {
+        if (!newClass) {
+          return value;
+        }
+        if (value) {
+          return value + " " + newClass;
+        }
+        return value + newClass;
+      }
+      if (typeof module !== "undefined" && module.exports) {
+        classNames.default = classNames;
+        module.exports = classNames;
+      } else if (typeof define === "function" && typeof define.amd === "object" && define.amd) {
+        define("classnames", [], function() {
+          return classNames;
+        });
+      } else {
+        window.classNames = classNames;
+      }
+    })();
+  }
+});
+
+// card.tsx
+import {
+  useId
+} from "react";
+
+// ../../../../packages/registry/class-names/dist/index.js
+var import_classnames = __toESM(require_classnames(), 1);
+var getClassName = ({
+  className,
+  modifiers = {},
+  rootClass,
+  styles = {}
+}) => {
+  function getModifiers() {
+    const updatedModifiers = {};
+    const modifierKeys = Object.keys(modifiers);
+    if (modifierKeys.length) {
+      modifierKeys.forEach((modKey) => {
+        const classKey = `${rootClass}--${modKey}`;
+        const newClassName = styles[classKey] || classKey;
+        updatedModifiers[newClassName] = modifiers[modKey] ?? false;
+      });
+    }
+    return updatedModifiers;
+  }
+  function getChildClass(childClassName) {
+    const classKey = `${rootClass}__${childClassName}`;
+    return styles[classKey] || classKey;
+  }
+  function getRootStyles() {
+    return (0, import_classnames.default)(
+      className,
+      {
+        ...getModifiers()
+      },
+      styles[rootClass] || rootClass
+    );
+  }
+  return [getRootStyles(), getChildClass];
+};
+
+// card.module.scss
+var card_module_default = {
+  "BHT__Card": "BHT__Card",
+  "BHT__Card__header": "BHT__Card__header",
+  "BHT__Card__heading": "BHT__Card__heading",
+  "BHT__Card__icon": "BHT__Card__icon",
+  "BHT__Card__title": "BHT__Card__title",
+  "BHT__Card__action": "BHT__Card__action",
+  "BHT__Card__body-padding": "BHT__Card__body-padding",
+  "BHT__Card--interactive": "BHT__Card--interactive",
+  "BHT__Card--scrollable-body": "BHT__Card--scrollable-body",
+  "BHT__Card--padding-sm": "BHT__Card--padding-sm",
+  "BHT__Card--padding-md": "BHT__Card--padding-md",
+  "BHT__Card--padding-lg": "BHT__Card--padding-lg"
+};
+
+// card.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var Card = ({
+  padding = "none",
+  icon,
+  title,
+  headingLevel = 3,
+  action,
+  onSelect,
+  scrollableBody = false,
+  className,
+  children,
+  ...rest
+}) => {
+  const generatedTitleId = useId();
+  const hasHeader = icon !== void 0 || title !== void 0 || action !== void 0;
+  const hasTitle = title !== void 0;
+  const interactive = onSelect !== void 0;
+  const HeadingTag = `h${headingLevel}`;
+  const RootTag = hasTitle ? "section" : "div";
+  const titleId = hasTitle ? `${generatedTitleId}-title` : void 0;
+  const [rootClass, getChildClass] = getClassName({
+    className,
+    rootClass: "BHT__Card",
+    modifiers: {
+      [`padding-${padding}`]: true,
+      interactive,
+      "scrollable-body": scrollableBody
+    },
+    styles: card_module_default
+  });
+  const BodyTag = interactive ? "button" : "div";
+  return /* @__PURE__ */ jsxs(RootTag, { ...rest, className: rootClass, "aria-labelledby": titleId, children: [
+    hasHeader && /* @__PURE__ */ jsxs("div", { className: getChildClass("header"), children: [
+      /* @__PURE__ */ jsxs("span", { className: getChildClass("heading"), children: [
+        icon !== void 0 && /* @__PURE__ */ jsx("span", { className: getChildClass("icon"), children: icon }),
+        hasTitle && /* @__PURE__ */ jsx(HeadingTag, { id: titleId, className: getChildClass("title"), children: title })
+      ] }),
+      action !== void 0 && /* @__PURE__ */ jsx("span", { className: getChildClass("action"), children: action })
+    ] }),
+    /* @__PURE__ */ jsx(
+      BodyTag,
+      {
+        type: interactive ? "button" : void 0,
+        onClick: onSelect,
+        className: getChildClass("body-padding"),
+        children
+      }
+    )
+  ] });
+};
+export {
+  Card
+};
+/*! Bundled license information:
+
+classnames/index.js:
+  (*!
+  	Copyright (c) 2018 Jed Watson.
+  	Licensed under the MIT License (MIT), see
+  	http://jedwatson.github.io/classnames
+  *)
+*/

package/docs.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://github.com/behivetech/bht-component-registry/docs.schema.json",
+  "version": 2,
+  "generatedAt": "2026-10-20T05:49:42.170Z",
+  "docs": [
+    {
+      "displayName": "Card",
+      "description": "",
+      "extendsNative": true,
+      "props": [
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional content rendered at the end of the header (buttons, menus, a close control, etc.)"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Card body content"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Additional class names to merge with the component root element"
+        },
+        {
+          "name": "headingLevel",
+          "type": "1 | 2 | 3 | 4 | 5 | 6",
+          "required": false,
+          "defaultValue": "3",
+          "description": "Which heading tag (`h1`–`h6`) wraps `title`, so the card's title takes its\ncorrect place in the page's heading outline. Defaults to `3`, matching a\ncard nested one level below a page's `h1` title and a `section`'s `h2` —\noverride per-instance when a card sits at a different depth."
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional icon rendered before the title in the header"
+        },
+        {
+          "name": "onSelect",
+          "type": "MouseEventHandler<HTMLButtonElement>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Makes the body a real `<button>` — hover/focus affordance plus a centered,\nstacked content layout — for tile/action-card patterns (a picker grid,\nfor example) instead of a static surface. Distinct from `onClick` (a plain\npass-through to the root element, e.g. for stopping click propagation).\nOmit for a plain, non-interactive card."
+        },
+        {
+          "name": "padding",
+          "type": "\"none\" | \"sm\" | \"md\" | \"lg\"",
+          "required": false,
+          "defaultValue": "none",
+          "description": "Controls internal padding; defaults to none so consumers opt in. Applies to the body when a header is present."
+        },
+        {
+          "name": "scrollableBody",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Keeps the header fixed and scrolls only the body when content exceeds the\ncard's height. Only meaningful when the card has a bounded height (a\nmodal or drawer panel, for example)."
+        },
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional header title; omit along with `icon`/`action` to render no header"
+        }
+      ]
+    }
+  ],
+  "functions": []
+}

package/index.ts

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

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@behivetech/atoms.card",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.2",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./dist/index.css"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "index.ts",
+    "card.tsx",
+    "card.module.scss",
+    "*.example.tsx",
+    "docs.json"
+  ],
+  "registry": {
+    "status": "stable",
+    "tags": []
+  },
+  "peerDependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "esbuild-sass-plugin": "^3.7.0",
+    "eslint": "^9.39.5",
+    "postcss-modules": "^9.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@bht-component-registry/class-names": "0.0.6",
+    "@bht-component-registry/env": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/behivetech/bht-galaxy.git",
+    "directory": "registry/behivetech/atoms/card"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup && bht-registry-docgen",
+    "dev": "tsup --watch",
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }