@usefragments/ui 1.0.0

package/src/components/Card/Card.module.scss

@@ -0,0 +1,212 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+.card {
+  @include surface-elevated;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  color: var(--fui-text-primary, $fui-text-primary);
+  background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+  border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
+  border-radius: var(--fui-card-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
+  box-shadow: var(--fui-card-shadow, none);
+  transition:
+    box-shadow var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    background-color var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+}
+
+// Variants
+.default {
+  background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+  border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
+  box-shadow: var(--fui-card-shadow, none);
+}
+
+.outlined {
+  background-color: transparent;
+  border-color: var(
+    --fui-card-outlined-border,
+    var(--fui-card-border, var(--fui-border-strong, #{$fui-border-strong}))
+  );
+  box-shadow: none;
+}
+
+.elevated {
+  background-color: var(--fui-card-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+  border-color: var(--fui-card-border, var(--fui-border, #{$fui-border}));
+  box-shadow: var(--fui-card-elevated-shadow, var(--fui-card-shadow, none));
+}
+
+// Compact metric tile for dashboard grids. It uses the same card radius and
+// hairline model as panels, with a quieter fill so adjacent metric tiles read
+// as one dashboard system rather than separate hero cards.
+.stat {
+  background-color: var(
+    --fui-card-stat-bg,
+    var(
+      --fui-card-bg,
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 2%, transparent)
+    )
+  );
+  border-color: var(
+    --fui-card-stat-border,
+    var(--fui-card-border, var(--fui-border, #{$fui-border}))
+  );
+  box-shadow: var(--fui-card-stat-shadow, var(--fui-card-shadow, none));
+}
+
+// Hairline-bordered panel with no own padding — designed for compound use
+// with `Card.Header divided` + `Card.Body` inside dashboards. Each region
+// owns its spacing so panel headers can be full-bleed with a hairline
+// divider underneath. Uses the same surface-agnostic overlay as `.stat`.
+// Padding is forced to 0 here so the variant works regardless of the
+// `padding` prop — children manage their own spacing inside a panel.
+.panel {
+  background-color: var(
+    --fui-panel-bg,
+    var(
+      --fui-card-bg,
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 2%, transparent)
+    )
+  );
+  border-color: var(--fui-panel-border, var(--fui-card-border, var(--fui-border, #{$fui-border})));
+  box-shadow: var(--fui-card-panel-shadow, var(--fui-card-shadow, none));
+  overflow: hidden;
+  padding: 0;
+}
+
+// Padding
+.paddingNone {
+  padding: 0;
+}
+
+// Canonical spacing scale (shared with Box/Stack/Grid/BentoGrid/List): sm=2 md=3 lg=4
+.paddingSm {
+  padding: var(--fui-space-2, $fui-space-2);
+}
+
+.paddingMd {
+  padding: var(--fui-space-3, $fui-space-3);
+}
+
+.paddingLg {
+  padding: var(--fui-space-4, $fui-space-4);
+}
+
+// Interactive card (when onClick is provided).
+// Card renders as an `article`/`div`/`section` (never a real `<button>`), so
+// applying `button-reset` here was gratuitous — and it was silently wiping
+// out variant-applied borders and backgrounds (the reset sets
+// `border: none; background: transparent`). Keep only the clickable
+// affordances; variants keep their surface and border untouched.
+.interactive {
+  @include interactive-base;
+
+  display: block;
+  width: 100%;
+  text-align: left;
+  cursor: pointer;
+  font: inherit;
+  color: inherit;
+
+  &:hover {
+    background-color: var(--fui-card-hover-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
+    border-color: var(--fui-card-hover-border, var(--fui-border-strong, #{$fui-border-strong}));
+    box-shadow: none;
+  }
+
+  &:active {
+    background-color: var(--fui-card-active-bg, var(--fui-bg-active, $fui-bg-active));
+    box-shadow: var(
+      --fui-card-active-shadow,
+      inset 0 1px 2px color-mix(in srgb, black 12%, transparent)
+    );
+  }
+}
+
+.header {
+  margin-bottom: var(--fui-space-2, $fui-space-2);
+}
+
+// Full-bleed panel-header bar: fixed 40px rail with horizontal padding and a
+// hairline bottom divider. No trailing margin — it sits flush above the
+// panel body, which manages its own padding. Use inside `variant="panel"`.
+.headerDivided {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  min-height: 2.857rem; // 40px
+  padding: 0 var(--fui-space-2, $fui-space-2);
+  margin-bottom: 0;
+  border-bottom: 1px solid var(--fui-border, $fui-border);
+}
+
+.title {
+  margin: 0;
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+}
+
+.description {
+  margin: 0 0 var(--fui-space-1, $fui-space-1) 0;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+
+  &:last-child {
+    margin-bottom: 0;
+  }
+}
+
+.body {
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  margin-top: var(--fui-space-2, $fui-space-2);
+  padding-top: var(--fui-space-2, $fui-space-2);
+  border-top: 1px solid var(--fui-border, $fui-border);
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none;
+  }
+
+  .interactive {
+    &:hover {
+      transform: none;
+    }
+
+    &:active {
+      transform: none;
+    }
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .card {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .footer {
+    border-top-width: 2px;
+  }
+}

package/src/components/Card/Card.stories.tsx

@@ -0,0 +1,144 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Card } from ".";
+import { Progress } from "../Progress";
+import { Stack } from "../Stack";
+import { Text } from "../Text";
+
+/**
+ * Card is a container for grouping related content into a distinct surface. It
+ * is a compound component: compose Card.Header, Card.Title, Card.Description,
+ * Card.Body, and Card.Footer inside the root.
+ */
+const meta = {
+  title: "Layout/Card",
+  component: Card,
+  tags: ["autodocs", "canonical"],
+  parameters: {
+    docs: {
+      description: { component: "Container for grouping related content." },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["default", "outlined", "outline", "elevated", "stat", "panel"],
+      description: "Visual style of the card surface",
+    },
+    padding: {
+      control: "select",
+      options: ["none", "sm", "md", "lg"],
+      description: "Internal padding size",
+    },
+    as: {
+      control: "select",
+      options: ["article", "div", "section"],
+      description: "Semantic HTML element for the card root",
+    },
+  },
+  args: {
+    variant: "default",
+    padding: "md",
+    children: (
+      <>
+        <Card.Header>
+          <Card.Title>Card Title</Card.Title>
+          <Card.Description>A brief description</Card.Description>
+        </Card.Header>
+        <Card.Body>Card content goes here.</Card.Body>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Card>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Card>
+      <Card.Header>
+        <Card.Title>Card Title</Card.Title>
+        <Card.Description>A brief description</Card.Description>
+      </Card.Header>
+      <Card.Body>Card content goes here.</Card.Body>
+    </Card>
+  ),
+};
+
+export const Outlined: Story = {
+  render: () => (
+    <Card variant="outlined">
+      <Card.Header>
+        <Card.Title>Outlined Card</Card.Title>
+      </Card.Header>
+      <Card.Body>Content with border.</Card.Body>
+    </Card>
+  ),
+};
+
+export const Elevated: Story = {
+  render: () => (
+    <Card variant="elevated">
+      <Card.Header>
+        <Card.Title>Featured Item</Card.Title>
+      </Card.Header>
+      <Card.Body>Important content.</Card.Body>
+    </Card>
+  ),
+};
+
+export const Stat: Story = {
+  render: () => (
+    <Card variant="stat" style={{ width: 280 }}>
+      <Stack gap="md">
+        <Stack gap="xs">
+          <Text as="strong" size="2xl" weight="bold" letterSpacing="tighter" tabularNums>
+            94%
+          </Text>
+          <Text as="p" size="sm" color="secondary">
+            Component coverage
+          </Text>
+        </Stack>
+        <Progress value={94} variant="success" size="sm" />
+      </Stack>
+    </Card>
+  ),
+};
+
+export const Panel: Story = {
+  render: () => (
+    <Card variant="panel" padding="none" style={{ width: 360 }}>
+      <Card.Header divided>
+        <Card.Title>System states</Card.Title>
+      </Card.Header>
+      <Card.Body padding="md">
+        <Text as="p" size="sm" color="secondary">
+          Use panel cards for bordered dashboard regions with their own internal header and body
+          rhythm.
+        </Text>
+      </Card.Body>
+    </Card>
+  ),
+};
+
+export const WithFooter: Story = {
+  render: () => (
+    <Card>
+      <Card.Header>
+        <Card.Title>Card with Footer</Card.Title>
+        <Card.Description>Complete card layout</Card.Description>
+      </Card.Header>
+      <Card.Body>Main content area.</Card.Body>
+      <Card.Footer>Footer actions go here</Card.Footer>
+    </Card>
+  ),
+};
+
+export const ContentOnly: Story = {
+  render: () => (
+    <Card>
+      <Card.Body>Just content, no header or footer.</Card.Body>
+    </Card>
+  ),
+};

package/src/components/Card/index.tsx

@@ -0,0 +1,233 @@
+"use client";
+
+import * as React from "react";
+import styles from "./Card.module.scss";
+
+// ============================================
+// Types
+// ============================================
+
+/**
+ * Card container for grouping related content.
+ * @see https://usefragments.com/components/card
+ */
+export interface CardProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+  children: React.ReactNode;
+  /** Visual style variant. `"outline"` is an alias for `"outlined"`.
+   *
+   * - `default` / `outlined` / `elevated`: general-purpose cards.
+   * - `stat`: compact metric tile for dashboard grids — hairline border,
+   *   panel-subtle surface, tight radius, zero shadow.
+   * - `panel`: hairline-bordered panel with zero own padding, designed for
+   *   compound use with `Card.Header divided` + `Card.Body` so each region
+   *   manages its own spacing.
+   * @default "default"
+   * @see https://usefragments.com/components/card#variants */
+  variant?: "default" | "outlined" | "outline" | "elevated" | "stat" | "panel";
+  /** Inner padding.
+   * @default "md" */
+  padding?: "none" | "sm" | "md" | "lg";
+  /** Root element tag.
+   * @default "article" */
+  as?: "article" | "div" | "section";
+}
+
+export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Renders the header as a divided bar: fixed height, horizontal padding,
+   * hairline bottom border, no trailing margin. Used with `variant="panel"`
+   * for dashboard-style panel headers. */
+  divided?: boolean;
+}
+
+export interface CardTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  children: React.ReactNode;
+}
+
+export interface CardDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
+  children: React.ReactNode;
+}
+
+export interface CardBodyProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Inner padding for body-only spacing, useful with `variant="panel"`.
+   * Omit when the card root already owns padding. */
+  padding?: "none" | "sm" | "md" | "lg";
+}
+
+export interface CardFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface CardContextValue {
+  variant: "default" | "outlined" | "elevated" | "stat" | "panel";
+  padding: "none" | "sm" | "md" | "lg";
+  isInteractive: boolean;
+}
+
+const CardContext = React.createContext<CardContextValue | null>(null);
+
+// ============================================
+// Padding Map
+// ============================================
+
+const paddingMap = {
+  none: styles.paddingNone,
+  sm: styles.paddingSm,
+  md: styles.paddingMd,
+  lg: styles.paddingLg,
+};
+
+function composeEventHandlers<E extends { defaultPrevented: boolean }>(
+  userHandler: ((event: E) => void) | undefined,
+  internalHandler: (event: E) => void
+) {
+  return (event: E) => {
+    userHandler?.(event);
+    if (event.defaultPrevented) return;
+    internalHandler(event);
+  };
+}
+
+// ============================================
+// Components
+// ============================================
+
+function CardRoot({
+  children,
+  variant: variantProp = "default",
+  padding = "md",
+  as: Component = "article",
+  className,
+  style,
+  ...htmlProps
+}: CardProps) {
+  // Resolve alias: "outline" → "outlined"
+  const variant = variantProp === "outline" ? "outlined" : variantProp;
+  const { onKeyDown, onKeyUp, role, tabIndex, ...elementProps } = htmlProps;
+
+  const isInteractive = typeof elementProps.onClick === "function";
+  const resolvedRole = isInteractive ? (role ?? "button") : role;
+  const resolvedTabIndex = isInteractive ? (tabIndex ?? 0) : tabIndex;
+
+  const classes = [
+    styles.card,
+    styles[variant],
+    paddingMap[padding],
+    isInteractive && styles.interactive,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const contextValue: CardContextValue = {
+    variant,
+    padding,
+    isInteractive,
+  };
+
+  return (
+    <CardContext.Provider value={contextValue}>
+      <Component
+        {...elementProps}
+        role={resolvedRole}
+        tabIndex={resolvedTabIndex}
+        onKeyDown={
+          isInteractive && resolvedRole === "button"
+            ? composeEventHandlers(onKeyDown, (event: React.KeyboardEvent<HTMLElement>) => {
+                if (event.key === "Enter") {
+                  event.preventDefault();
+                  event.currentTarget.click();
+                }
+                if (event.key === " ") {
+                  event.preventDefault();
+                }
+              })
+            : onKeyDown
+        }
+        onKeyUp={
+          isInteractive && resolvedRole === "button"
+            ? composeEventHandlers(onKeyUp, (event: React.KeyboardEvent<HTMLElement>) => {
+                if (event.key === " ") {
+                  event.preventDefault();
+                  event.currentTarget.click();
+                }
+              })
+            : onKeyUp
+        }
+        className={classes}
+        style={style}
+      >
+        {children}
+      </Component>
+    </CardContext.Provider>
+  );
+}
+
+function CardHeader({ children, divided, className, ...htmlProps }: CardHeaderProps) {
+  const classes = [styles.header, divided && styles.headerDivided, className]
+    .filter(Boolean)
+    .join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
+}
+
+function CardTitle({ children, className, ...htmlProps }: CardTitleProps) {
+  const classes = [styles.title, className].filter(Boolean).join(" ");
+  return (
+    <h3 {...htmlProps} className={classes}>
+      {children}
+    </h3>
+  );
+}
+
+function CardDescription({ children, className, ...htmlProps }: CardDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(" ");
+  return (
+    <p {...htmlProps} className={classes}>
+      {children}
+    </p>
+  );
+}
+
+function CardBody({ children, padding, className, ...htmlProps }: CardBodyProps) {
+  const classes = [styles.body, padding && paddingMap[padding], className]
+    .filter(Boolean)
+    .join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
+}
+
+function CardFooter({ children, className, ...htmlProps }: CardFooterProps) {
+  const classes = [styles.footer, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Card = Object.assign(CardRoot, {
+  Header: CardHeader,
+  Title: CardTitle,
+  Description: CardDescription,
+  Body: CardBody,
+  Footer: CardFooter,
+});
+
+// Re-export individual components for tree-shaking
+export { CardRoot, CardHeader, CardTitle, CardDescription, CardBody, CardFooter };