@12-apps/ui 1.0.0 → 1.3.0

package/src/components/layout/Card/Card.styles.ts

@@ -0,0 +1,182 @@
+import { alpha, keyframes } from '@mui/material';
+import type { CSSObject, Theme } from '@mui/material';
+
+import type { CardProps, CardVariant } from './Card.types';
+
+type BorderRadius = NonNullable<CardProps['borderRadius']>;
+
+// Define pulse animation
+const pulseAnimation = keyframes`
+  0% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 1;
+  }
+  70% {
+    box-shadow: 0 0 0 15px currentColor;
+    opacity: 0;
+  }
+  100% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 0;
+  }
+`;
+
+const borderRadiusFor = (theme: Theme, radius: BorderRadius): number | string => {
+  switch (radius) {
+    case 'none':
+      return 0;
+    case 'sm':
+      return theme.spacing(0.5);
+    case 'lg':
+      return theme.spacing(2);
+    case 'xl':
+      return theme.spacing(3);
+    case 'full':
+      return '50%';
+    default:
+      return theme.spacing(1);
+  }
+};
+
+const pulseSurface = (theme: Theme): CSSObject => ({
+  position: 'relative',
+  overflow: 'visible',
+  '&::after': {
+    content: '""',
+    position: 'absolute',
+    top: '0',
+    left: '0',
+    right: '0',
+    bottom: '0',
+    borderRadius: 'inherit',
+    backgroundColor: theme.palette.primary.main,
+    opacity: 0.3,
+    animation: `${pulseAnimation} 2s infinite`,
+    pointerEvents: 'none',
+    zIndex: -1,
+  },
+});
+
+const neumorphicShadow = (theme: Theme, lifted: boolean): string => {
+  const spread = lifted ? 12 : 8;
+  const blur = spread * 2;
+
+  return theme.palette.mode === 'dark'
+    ? `${spread}px ${spread}px ${blur}px ${alpha(theme.palette.common.black, 0.3)}, -${spread}px -${spread}px ${blur}px ${alpha(theme.palette.common.white, 0.1)}`
+    : `${spread}px ${spread}px ${blur}px ${alpha(theme.palette.grey[400], lifted ? 0.3 : 0.2)}, -${spread}px -${spread}px ${blur}px ${alpha(theme.palette.common.white, lifted ? 0.9 : 0.8)}`;
+};
+
+const sectionBackground = (theme: Theme, lifted: boolean): string => {
+  if (theme.palette.mode === 'dark') {
+    return lifted ? 'rgba(0, 0, 0, 0.25)' : 'rgba(0, 0, 0, 0.2)';
+  }
+  return lifted ? 'rgba(0, 0, 0, 0.04)' : 'rgba(0, 0, 0, 0.02)';
+};
+
+interface Surface {
+  surface: CSSObject;
+  hover: CSSObject;
+}
+
+/**
+ * Each variant contributes a resting surface and whatever it changes on hover.
+ * Only `interactive` cards actually move on hover, so the hover half of every
+ * variant reads back its resting value when `interactive` is off.
+ */
+const VARIANT_SURFACES: Record<CardVariant, (theme: Theme, lifted: boolean) => Surface> = {
+  elevated: (_theme, lifted) => ({
+    surface: { elevation: 4 } as CSSObject,
+    hover: { elevation: lifted ? 8 : 4 } as CSSObject,
+  }),
+  outlined: (theme, lifted) => ({
+    surface: { border: `1px solid ${theme.palette.divider}`, boxShadow: 'none' },
+    hover: { borderColor: lifted ? theme.palette.primary.main : theme.palette.divider },
+  }),
+  glass: (theme, lifted) => ({
+    surface: {
+      backgroundColor: alpha(theme.palette.background.paper, 0.1),
+      backdropFilter: 'blur(20px)',
+      border: `1px solid ${alpha(theme.palette.primary.main, 0.2)}`,
+      boxShadow: `0 8px 32px ${alpha(theme.palette.common.black, 0.1)}`,
+    },
+    hover: {
+      backgroundColor: alpha(theme.palette.background.paper, lifted ? 0.15 : 0.1),
+      border: `1px solid ${alpha(theme.palette.primary.main, 0.3)}`,
+    },
+  }),
+  gradient: (theme, lifted) => ({
+    surface: {
+      background: cardGradient(theme, false),
+      color: theme.palette.primary.contrastText,
+      boxShadow: `0 4px 20px ${alpha(theme.palette.primary.main, 0.3)}`,
+    },
+    hover: { background: cardGradient(theme, lifted) },
+  }),
+  neumorphic: (theme, lifted) => ({
+    surface: {
+      backgroundColor:
+        theme.palette.mode === 'dark' ? theme.palette.grey[800] : theme.palette.grey[100],
+      boxShadow: neumorphicShadow(theme, false),
+      border: 'none',
+    },
+    hover: { boxShadow: neumorphicShadow(theme, lifted) },
+  }),
+  section: (theme, lifted) => ({
+    surface: {
+      backgroundColor: sectionBackground(theme, false),
+      border: 'none',
+      boxShadow: 'none',
+    },
+    hover: { backgroundColor: sectionBackground(theme, lifted) },
+  }),
+};
+
+const cardGradient = (theme: Theme, dark: boolean): string =>
+  dark
+    ? `linear-gradient(135deg, ${theme.palette.primary.dark}, ${theme.palette.secondary.dark})`
+    : `linear-gradient(135deg, ${theme.palette.primary.main}, ${theme.palette.secondary.main})`;
+
+// An unrecognised variant gets the shared base only — no interactive, glow or
+// pulse decoration, as before.
+const variantSurface = (
+  theme: Theme,
+  variant: CardVariant,
+  interactive: boolean,
+): Surface | null => VARIANT_SURFACES[variant]?.(theme, interactive) ?? null;
+
+interface CardStyleArgs {
+  variant: CardVariant;
+  interactive: boolean;
+  glow: boolean;
+  pulse: boolean;
+  borderRadius: BorderRadius;
+}
+
+export const cardStyles = (
+  theme: Theme,
+  { variant, interactive, glow, pulse, borderRadius }: CardStyleArgs,
+): CSSObject => {
+  const base: CSSObject = {
+    borderRadius: borderRadiusFor(theme, borderRadius),
+    transition: theme.transitions.create(
+      ['box-shadow', 'transform', 'border-color', 'background-color'],
+      { duration: theme.transitions.duration.standard },
+    ),
+  };
+
+  const chosen = variantSurface(theme, variant, interactive);
+  if (!chosen) return base;
+
+  return {
+    ...base,
+    ...(interactive && { cursor: 'pointer', '&:active': { transform: 'translateY(0)' } }),
+    ...(glow && { boxShadow: `0 0 20px ${alpha(theme.palette.primary.main, 0.3)}` }),
+    ...(pulse && pulseSurface(theme)),
+    ...chosen.surface,
+    '&:hover': {
+      ...(interactive && { transform: 'translateY(-2px)' }),
+      ...(glow && { boxShadow: `0 0 30px ${alpha(theme.palette.primary.main, 0.4)}` }),
+      ...chosen.hover,
+    },
+  };
+};

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

@@ -1,4 +1,6 @@
-import { Favorite, MoreVert, Share } from '@mui/icons-material';
+import Favorite from '@mui/icons-material/Favorite';
+import MoreVert from '@mui/icons-material/MoreVert';
+import Share from '@mui/icons-material/Share';
 import { Avatar, Box,Button, Chip, IconButton, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, fn,userEvent, waitFor, within } from 'storybook/test';
@@ -538,19 +540,21 @@ export const KeyboardNavigationTest: Story = {
       const firstCard = canvas.getByTestId('interactive-card-1');
       const secondCard = canvas.getByTestId('interactive-card-2');
 
-      // Focus first card
-      firstCard.focus();
-      await expect(firstCard).toHaveFocus();
+      // Tab in from the body rather than calling .focus() — that made the first
+      // assertion a tautology about the DOM honouring focus(), not about this
+      // card being the first tab stop.
+      await userEvent.tab();
+      await waitFor(() => expect(firstCard).toHaveFocus());
 
       // Tab to next card
       await userEvent.tab();
-      await expect(secondCard).toHaveFocus();
+      await waitFor(() => expect(secondCard).toHaveFocus());
     });
 
     await step('Tab navigation backward', async () => {
       await userEvent.tab({ shift: true });
       const firstCard = canvas.getByTestId('interactive-card-1');
-      await expect(firstCard).toHaveFocus();
+      await waitFor(() => expect(firstCard).toHaveFocus());
     });
   },
 };
@@ -813,10 +817,15 @@ export const ScreenReaderTest: Story = {
 
     await step('Keyboard activation', async () => {
       const accessibleCard = canvas.getByTestId('accessible-card');
-      accessibleCard.focus();
+
+      // Tab in rather than calling .focus(), so this covers the card actually
+      // being reachable by keyboard, and assert focus survives Enter — pressing
+      // Enter on a card must not send focus somewhere else.
+      await userEvent.tab();
+      await waitFor(() => expect(accessibleCard).toHaveFocus());
+
       await userEvent.keyboard('{Enter}');
-      // Card should respond to Enter key when focused
-      await expect(accessibleCard).toHaveFocus();
+      await waitFor(() => expect(accessibleCard).toHaveFocus());
     });
   },
 };
@@ -847,23 +856,26 @@ export const FocusManagementTest: Story = {
       const card1 = canvas.getByTestId('focus-card-1');
       const innerButton1 = canvas.getByTestId('inner-button-1');
 
-      // Focus card
-      card1.focus();
-      // In testing environment, focus might immediately move to the button
-      // Check that either the card or its inner button has focus
-      const hasFocus = document.activeElement === card1 || document.activeElement === innerButton1;
-      await expect(hasFocus).toBeTruthy();
+      // Tab in from the body. contains() is true for the node itself, so this
+      // holds whether the card is its own tab stop or focus goes straight to the
+      // button inside it.
+      await userEvent.tab();
+      await waitFor(() => expect(card1.contains(document.activeElement)).toBeTruthy());
 
-      // If card has focus, tab to inner element
-      if (document.activeElement === card1) {
+      // Whether the card is a tab stop of its own is a Card implementation
+      // detail, so step forward only if focus is not already on the button. The
+      // previous version wrapped the assertion itself in that condition, which
+      // meant one of its two paths asserted nothing at all.
+      if (document.activeElement !== innerButton1) {
         await userEvent.tab();
-        await expect(innerButton1).toHaveFocus();
       }
+      await waitFor(() => expect(innerButton1).toHaveFocus());
     });
 
     await step('Focus visibility', async () => {
       const card1 = canvas.getByTestId('focus-card-1');
-      card1.focus();
+      // Focus is already inside card 1 from the previous step.
+      await waitFor(() => expect(card1.contains(document.activeElement)).toBeTruthy());
 
       // Check for focus ring (outline)
       const styles = window.getComputedStyle(card1);
@@ -873,21 +885,15 @@ export const FocusManagementTest: Story = {
     await step('Focus restoration', async () => {
       const card1 = canvas.getByTestId('focus-card-1');
       const card2 = canvas.getByTestId('focus-card-2');
-      const innerButton2 = canvas.getByTestId('inner-button-2');
-
-      // Focus on second card or its button
-      card2.focus();
-      // Check that focus moved to second card area
-      const secondCardHasFocus =
-        document.activeElement === card2 || document.activeElement === innerButton2;
-      await expect(secondCardHasFocus).toBeTruthy();
-
-      // Focus back on first card
-      card1.focus();
-      // Check that focus moved back to first card area
-      const firstCardArea = canvas.getByTestId('focus-card-1');
-      const focusIsInFirstCard = firstCardArea.contains(document.activeElement);
-      await expect(focusIsInFirstCard).toBeTruthy();
+
+      // Continue the journey forward out of card 1 and into card 2...
+      await userEvent.tab();
+      await waitFor(() => expect(card2.contains(document.activeElement)).toBeTruthy());
+
+      // ...then shift-tab back, which is the restoration this step is named for.
+      // Calling .focus() on each card in turn only proved that focus() works.
+      await userEvent.tab({ shift: true });
+      await waitFor(() => expect(card1.contains(document.activeElement)).toBeTruthy());
     });
   },
 };
@@ -1011,7 +1017,6 @@ export const PerformanceTest: Story = {
   },
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    const startTime = Date.now();
 
     await step('Render performance', async () => {
       const container = canvas.getByTestId('performance-container');
@@ -1021,25 +1026,20 @@ export const PerformanceTest: Story = {
       const cards = canvas.getAllByTestId(/^perf-card-/);
       await expect(cards).toHaveLength(50);
 
-      const renderTime = Date.now() - startTime;
-      // Performance metric logged to test report
-
-      // Expect reasonable render time (under 1000ms)
-      await expect(renderTime).toBeLessThan(1000);
+      // No wall-clock budget here: the queries above run against DOM that has
+      // already rendered, so a duration around them measures query time, and any
+      // millisecond threshold is really a bet on how loaded the CI runner is.
     });
 
     await step('Interaction performance', async () => {
       const interactiveCard = canvas.getByTestId('perf-card-0');
-      const interactionStart = Date.now();
 
       await userEvent.hover(interactiveCard);
       await userEvent.unhover(interactiveCard);
 
-      const interactionTime = Date.now() - interactionStart;
-      // Interaction metric logged to test report
-
-      // Expect quick interaction (under 100ms)
-      await expect(interactionTime).toBeLessThan(100);
+      // The card survives a hover/unhover cycle. Timing it was a runner-speed
+      // assertion, not a component one.
+      await expect(interactiveCard).toBeInTheDocument();
     });
 
     await step('Memory efficiency', async () => {

package/src/components/layout/Card/Card.tsx

@@ -1,5 +1,4 @@
 import {
-  alpha,
   Box,
   Card as MuiCard,
   CardActions as MuiCardActions,
@@ -7,11 +6,12 @@ import {
   CardHeader as MuiCardHeader,
   CardMedia as MuiCardMedia,
   CircularProgress,
-  keyframes,
   useTheme,
 } from '@mui/material';
 import React from 'react';
 
+import { resolveCardProps } from './Card.helpers';
+import { cardStyles } from './Card.styles';
 import type {
   CardActionsProps,
   CardContentProps,
@@ -20,31 +20,15 @@ import type {
   CardProps,
 } from './Card.types';
 
-// Define pulse animation
-const pulseAnimation = keyframes`
-  0% {
-    box-shadow: 0 0 0 0 currentColor;
-    opacity: 1;
-  }
-  70% {
-    box-shadow: 0 0 0 15px currentColor;
-    opacity: 0;
-  }
-  100% {
-    box-shadow: 0 0 0 0 currentColor;
-    opacity: 0;
-  }
-`;
-
-export const Card: React.FC<CardProps> = (props) => {
+export const Card: React.FC<CardProps> = (rawProps) => {
   const {
     children,
-    variant = 'elevated',
-    interactive = false,
-    glow = false,
-    pulse = false,
-    borderRadius = 'md',
-    loading = false,
+    variant,
+    interactive,
+    glow,
+    pulse,
+    borderRadius,
+    loading,
     onClick,
     onFocus,
     onBlur,
@@ -52,231 +36,30 @@ export const Card: React.FC<CardProps> = (props) => {
     dataTestId,
     // These props are reserved for future implementation but need to be extracted
     // to prevent them from being passed to the underlying MuiCard
-    expandable,
-    expanded,
-    onExpandToggle,
-    entranceAnimation,
-    animationDelay,
-    skeleton,
-    hoverScale,
+    expandable: _expandable,
+    expanded: _expanded,
+    onExpandToggle: _onExpandToggle,
+    entranceAnimation: _entranceAnimation,
+    animationDelay: _animationDelay,
+    skeleton: _skeleton,
+    hoverScale: _hoverScale,
     ...restProps
-  } = props;
-
-  // Void unused props to satisfy linter
-  void expandable;
-  void expanded;
-  void onExpandToggle;
-  void entranceAnimation;
-  void animationDelay;
-  void skeleton;
-  void hoverScale;
+  } = resolveCardProps(rawProps);
 
   const theme = useTheme();
 
-  const getBorderRadius = () => {
-    switch (borderRadius) {
-      case 'none':
-        return 0;
-      case 'sm':
-        return theme.spacing(0.5);
-      case 'md':
-        return theme.spacing(1);
-      case 'lg':
-        return theme.spacing(2);
-      case 'xl':
-        return theme.spacing(3);
-      case 'full':
-        return '50%';
-      default:
-        return theme.spacing(1);
-    }
-  };
-
-  const getVariantStyles = () => {
-    const baseStyles = {
-      borderRadius: getBorderRadius(),
-      transition: theme.transitions.create(
-        ['box-shadow', 'transform', 'border-color', 'background-color'],
-        {
-          duration: theme.transitions.duration.standard,
-        },
-      ),
-    };
-
-    const interactiveStyles = interactive
-      ? {
-          cursor: 'pointer',
-          '&:hover': {
-            transform: 'translateY(-2px)',
-          },
-          '&:active': {
-            transform: 'translateY(0)',
-          },
-        }
-      : {};
-
-    const glowStyles = glow
-      ? {
-          boxShadow: `0 0 20px ${alpha(theme.palette.primary.main, 0.3)}`,
-          '&:hover': {
-            boxShadow: `0 0 30px ${alpha(theme.palette.primary.main, 0.4)}`,
-          },
-        }
-      : {};
-
-    const pulseStyles = pulse
-      ? {
-          position: 'relative',
-          overflow: 'visible',
-          '&::after': {
-            content: '""',
-            position: 'absolute',
-            top: '0',
-            left: '0',
-            right: '0',
-            bottom: '0',
-            borderRadius: 'inherit',
-            backgroundColor: theme.palette.primary.main,
-            opacity: 0.3,
-            animation: `${pulseAnimation} 2s infinite`,
-            pointerEvents: 'none',
-            zIndex: -1,
-          },
-        }
-      : {};
-
-    switch (variant) {
-      case 'elevated':
-        return {
-          ...baseStyles,
-          ...interactiveStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          elevation: 4,
-          '&:hover': {
-            ...interactiveStyles['&:hover'],
-            ...glowStyles['&:hover'],
-            elevation: interactive ? 8 : 4,
-          },
-        };
-
-      case 'outlined':
-        return {
-          ...baseStyles,
-          ...interactiveStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          border: `1px solid ${theme.palette.divider}`,
-          boxShadow: 'none',
-          '&:hover': {
-            ...interactiveStyles['&:hover'],
-            ...glowStyles['&:hover'],
-            borderColor: interactive ? theme.palette.primary.main : theme.palette.divider,
-          },
-        };
-
-      case 'glass':
-        return {
-          ...baseStyles,
-          ...interactiveStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          backgroundColor: alpha(theme.palette.background.paper, 0.1),
-          backdropFilter: 'blur(20px)',
-          border: `1px solid ${alpha(theme.palette.primary.main, 0.2)}`,
-          boxShadow: `0 8px 32px ${alpha(theme.palette.common.black, 0.1)}`,
-          '&:hover': {
-            ...interactiveStyles['&:hover'],
-            ...glowStyles['&:hover'],
-            backgroundColor: interactive
-              ? alpha(theme.palette.background.paper, 0.15)
-              : alpha(theme.palette.background.paper, 0.1),
-            border: `1px solid ${alpha(theme.palette.primary.main, 0.3)}`,
-          },
-        };
-
-      case 'gradient':
-        return {
-          ...baseStyles,
-          ...interactiveStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          background: `linear-gradient(135deg, ${theme.palette.primary.main}, ${theme.palette.secondary.main})`,
-          color: theme.palette.primary.contrastText,
-          boxShadow: `0 4px 20px ${alpha(theme.palette.primary.main, 0.3)}`,
-          '&:hover': {
-            ...interactiveStyles['&:hover'],
-            ...glowStyles['&:hover'],
-            background: interactive
-              ? `linear-gradient(135deg, ${theme.palette.primary.dark}, ${theme.palette.secondary.dark})`
-              : `linear-gradient(135deg, ${theme.palette.primary.main}, ${theme.palette.secondary.main})`,
-          },
-        };
-
-      case 'neumorphic': {
-        const neumorphicBg =
-          theme.palette.mode === 'dark' ? theme.palette.grey[800] : theme.palette.grey[100];
-
-        return {
-          ...baseStyles,
-          ...interactiveStyles,
-          ...pulseStyles,
-          backgroundColor: neumorphicBg,
-          boxShadow:
-            theme.palette.mode === 'dark'
-              ? `8px 8px 16px ${alpha(theme.palette.common.black, 0.3)}, -8px -8px 16px ${alpha(theme.palette.common.white, 0.1)}`
-              : `8px 8px 16px ${alpha(theme.palette.grey[400], 0.2)}, -8px -8px 16px ${alpha(theme.palette.common.white, 0.8)}`,
-          border: 'none',
-          '&:hover': {
-            ...interactiveStyles['&:hover'],
-            ...glowStyles['&:hover'],
-            boxShadow: interactive
-              ? theme.palette.mode === 'dark'
-                ? `12px 12px 24px ${alpha(theme.palette.common.black, 0.3)}, -12px -12px 24px ${alpha(theme.palette.common.white, 0.1)}`
-                : `12px 12px 24px ${alpha(theme.palette.grey[400], 0.3)}, -12px -12px 24px ${alpha(theme.palette.common.white, 0.9)}`
-              : theme.palette.mode === 'dark'
-                ? `8px 8px 16px ${alpha(theme.palette.common.black, 0.3)}, -8px -8px 16px ${alpha(theme.palette.common.white, 0.1)}`
-                : `8px 8px 16px ${alpha(theme.palette.grey[400], 0.2)}, -8px -8px 16px ${alpha(theme.palette.common.white, 0.8)}`,
-          },
-        };
-      }
-
-      case 'section':
-        return {
-          ...baseStyles,
-          ...interactiveStyles,
-          ...glowStyles,
-          ...pulseStyles,
-          backgroundColor:
-            theme.palette.mode === 'dark' ? 'rgba(0, 0, 0, 0.2)' : 'rgba(0, 0, 0, 0.02)',
-          border: 'none',
-          boxShadow: 'none',
-          '&:hover': {
-            ...interactiveStyles['&:hover'],
-            ...glowStyles['&:hover'],
-            backgroundColor: interactive
-              ? theme.palette.mode === 'dark'
-                ? 'rgba(0, 0, 0, 0.25)'
-                : 'rgba(0, 0, 0, 0.04)'
-              : theme.palette.mode === 'dark'
-                ? 'rgba(0, 0, 0, 0.2)'
-                : 'rgba(0, 0, 0, 0.02)',
-          },
-        };
-
-      default:
-        return baseStyles;
-    }
-  };
+  // A loading card is inert: no handlers fire and pointer events are off, so a
+  // half-rendered card cannot be clicked through.
+  const idle = !loading;
 
   return (
     <MuiCard
       data-testid={dataTestId || 'card'}
-      onClick={!loading ? onClick : undefined}
-      onFocus={!loading ? onFocus : undefined}
-      onBlur={!loading ? onBlur : undefined}
+      onClick={idle ? onClick : undefined}
+      onFocus={idle ? onFocus : undefined}
+      onBlur={idle ? onBlur : undefined}
       sx={{
-        ...getVariantStyles(),
+        ...cardStyles(theme, { variant, interactive, glow, pulse, borderRadius }),
         position: 'relative',
         opacity: loading ? 0.6 : 1,
         pointerEvents: loading ? 'none' : 'auto',