@12-apps/ui 1.0.0

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

@@ -0,0 +1,404 @@
+import {
+  alpha,
+  Box,
+  Card as MuiCard,
+  CardActions as MuiCardActions,
+  CardContent as MuiCardContent,
+  CardHeader as MuiCardHeader,
+  CardMedia as MuiCardMedia,
+  CircularProgress,
+  keyframes,
+  useTheme,
+} from '@mui/material';
+import React from 'react';
+
+import type {
+  CardActionsProps,
+  CardContentProps,
+  CardHeaderProps,
+  CardMediaProps,
+  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) => {
+  const {
+    children,
+    variant = 'elevated',
+    interactive = false,
+    glow = false,
+    pulse = false,
+    borderRadius = 'md',
+    loading = false,
+    onClick,
+    onFocus,
+    onBlur,
+    sx,
+    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,
+    ...restProps
+  } = props;
+
+  // Void unused props to satisfy linter
+  void expandable;
+  void expanded;
+  void onExpandToggle;
+  void entranceAnimation;
+  void animationDelay;
+  void skeleton;
+  void hoverScale;
+
+  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;
+    }
+  };
+
+  return (
+    <MuiCard
+      data-testid={dataTestId || 'card'}
+      onClick={!loading ? onClick : undefined}
+      onFocus={!loading ? onFocus : undefined}
+      onBlur={!loading ? onBlur : undefined}
+      sx={{
+        ...getVariantStyles(),
+        position: 'relative',
+        opacity: loading ? 0.6 : 1,
+        pointerEvents: loading ? 'none' : 'auto',
+        ...sx,
+      }}
+      {...restProps}
+    >
+      {loading && (
+        <Box
+          sx={{
+            position: 'absolute',
+            top: '50%',
+            left: '50%',
+            transform: 'translate(-50%, -50%)',
+            zIndex: 10,
+          }}
+        >
+          <CircularProgress />
+        </Box>
+      )}
+      {children}
+    </MuiCard>
+  );
+};
+
+export const CardHeader: React.FC<CardHeaderProps> = ({
+  title,
+  subtitle,
+  action,
+  avatar,
+  children,
+  dataTestId,
+  ...props
+}) => {
+  if (children) {
+    return <Box sx={{ p: 2 }} data-testid={dataTestId || 'card-header'}>{children}</Box>;
+  }
+
+  return (
+    <MuiCardHeader
+      data-testid={dataTestId || 'card-header'}
+      avatar={avatar}
+      action={action}
+      title={title}
+      subheader={subtitle}
+      titleTypographyProps={{
+        'data-testid': dataTestId ? `${dataTestId}-title` : 'card-title',
+      } as Record<string, unknown>}
+      subheaderTypographyProps={{
+        'data-testid': dataTestId ? `${dataTestId}-subtitle` : 'card-subtitle',
+      } as Record<string, unknown>}
+      {...props}
+    />
+  );
+};
+
+export const CardContent: React.FC<CardContentProps> = ({ children, dense = false, dataTestId, ...props }) => (
+    <MuiCardContent
+      data-testid={dataTestId || 'card-content'}
+      sx={{
+        padding: dense ? 1 : 2,
+        '&:last-child': {
+          paddingBottom: dense ? 1 : 2,
+        },
+      }}
+      {...props}
+    >
+      {children}
+    </MuiCardContent>
+  );
+
+export const CardActions: React.FC<CardActionsProps> = ({
+  children,
+  disableSpacing = false,
+  alignment = 'left',
+  dataTestId,
+  ...props
+}) => {
+  const getJustifyContent = () => {
+    switch (alignment) {
+      case 'center':
+        return 'center';
+      case 'right':
+        return 'flex-end';
+      case 'space-between':
+        return 'space-between';
+      default:
+        return 'flex-start';
+    }
+  };
+
+  return (
+    <MuiCardActions
+      data-testid={dataTestId || 'card-actions'}
+      disableSpacing={disableSpacing}
+      sx={{
+        justifyContent: getJustifyContent(),
+      }}
+      {...props}
+    >
+      {children}
+    </MuiCardActions>
+  );
+};
+
+export const CardMedia: React.FC<CardMediaProps> = ({
+  component = 'div',
+  image,
+  title,
+  height = 200,
+  children,
+  dataTestId,
+  ...props
+}) => (
+    <MuiCardMedia
+      data-testid={dataTestId || 'card-media'}
+      component={component}
+      height={height}
+      image={image}
+      title={title}
+      {...props}
+    >
+      {children}
+    </MuiCardMedia>
+  );

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

@@ -0,0 +1,57 @@
+import type { CardProps as MuiCardProps } from '@mui/material';
+import type { ReactNode } from 'react';
+
+export type CardVariant = 'elevated' | 'outlined' | 'glass' | 'gradient' | 'neumorphic' | 'section';
+export type CardEntranceAnimation = 'fade' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'zoom' | 'grow' | 'none';
+
+export interface CardProps extends Omit<MuiCardProps, 'variant'> {
+  children: ReactNode;
+  variant?: CardVariant;
+  interactive?: boolean;
+  glow?: boolean;
+  pulse?: boolean;
+  borderRadius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+  loading?: boolean;
+  expandable?: boolean;
+  expanded?: boolean;
+  onExpandToggle?: (expanded: boolean) => void;
+  entranceAnimation?: CardEntranceAnimation;
+  animationDelay?: number;
+  skeleton?: boolean;
+  hoverScale?: number;
+  onClick?: React.MouseEventHandler<HTMLDivElement>;
+  onFocus?: React.FocusEventHandler<HTMLDivElement>;
+  onBlur?: React.FocusEventHandler<HTMLDivElement>;
+  dataTestId?: string;
+}
+
+export interface CardHeaderProps {
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  action?: ReactNode;
+  avatar?: ReactNode;
+  children?: ReactNode;
+  dataTestId?: string;
+}
+
+export interface CardContentProps {
+  children: ReactNode;
+  dense?: boolean;
+  dataTestId?: string;
+}
+
+export interface CardActionsProps {
+  children: ReactNode;
+  disableSpacing?: boolean;
+  alignment?: 'left' | 'center' | 'right' | 'space-between';
+  dataTestId?: string;
+}
+
+export interface CardMediaProps {
+  component?: React.ElementType;
+  image?: string;
+  title?: string;
+  height?: number | string;
+  children?: ReactNode;
+  dataTestId?: string;
+}

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

@@ -0,0 +1,8 @@
+export { Card, CardActions, CardContent, CardHeader, CardMedia } from './Card';
+export type {
+  CardActionsProps,
+  CardContentProps,
+  CardHeaderProps,
+  CardMediaProps,
+  CardProps,
+} from './Card.types';

package/src/components/layout/Collapsible/Collapsible.md

@@ -0,0 +1,135 @@
+# Collapsible Component
+
+## Overview
+
+The Collapsible component provides a flexible container that can expand and collapse content with smooth animations. It supports multiple animation variants and includes accessible trigger and content subcomponents.
+
+## Features
+
+- **Multiple Animation Variants**: Default (MUI Collapse), smooth, and spring animations
+- **Customizable Timing**: Configurable duration and easing functions
+- **Accessibility**: Full ARIA support with proper focus management
+- **Composition Pattern**: Separate trigger and content components for flexibility
+- **Performance**: Optional keep-mounted behavior to control DOM presence
+- **Responsive**: Works seamlessly across all screen sizes
+
+## Basic Usage
+
+```tsx
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@/components/layout/Collapsible';
+
+function MyCollapsible() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div>
+      <CollapsibleTrigger 
+        expanded={isOpen}
+        onClick={() => setIsOpen(!isOpen)}
+      >
+        Click to toggle
+      </CollapsibleTrigger>
+      <Collapsible open={isOpen}>
+        <CollapsibleContent>
+          This content can be collapsed and expanded with smooth animations.
+        </CollapsibleContent>
+      </Collapsible>
+    </div>
+  );
+}
+```
+
+## Props
+
+### Collapsible Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | ReactNode | required | Content to show/hide |
+| open | boolean | required | Controls visibility state |
+| variant | 'default' \| 'smooth' \| 'spring' | 'default' | Animation style |
+| duration | number | 300 | Animation duration in milliseconds |
+| easing | string | theme default | CSS easing function |
+| onToggle | (open: boolean) => void | - | Callback when state changes |
+| disabled | boolean | false | Disable all interactions |
+| keepMounted | boolean | false | Keep content in DOM when collapsed |
+| sx | SxProps<Theme> | - | MUI styling system |
+| className | string | - | CSS class name |
+
+### CollapsibleTrigger Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | ReactNode | required | Trigger content |
+| onClick | () => void | - | Click handler |
+| disabled | boolean | false | Disable trigger |
+| expanded | boolean | false | Current expanded state |
+| className | string | - | CSS class name |
+
+### CollapsibleContent Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | ReactNode | required | Content to display |
+| className | string | - | CSS class name |
+
+## Animation Variants
+
+### Default
+Uses MUI's built-in Collapse component with standard Material Design animations.
+
+### Smooth
+Custom implementation with smooth height transitions and customizable easing.
+
+### Spring
+Bouncy spring-like animation with a playful feel using cubic-bezier easing.
+
+## Accessibility
+
+The Collapsible component follows WAI-ARIA guidelines:
+
+- Uses `role="region"` for the collapsible area
+- Implements `aria-expanded` to indicate state
+- Supports `aria-hidden` for collapsed content
+- Provides proper focus management
+- Keyboard navigation support on triggers
+
+## Best Practices
+
+1. **State Management**: Use controlled state for predictable behavior
+2. **Performance**: Set `keepMounted={false}` for large content to improve performance
+3. **Animation**: Choose appropriate variant based on your design system
+4. **Accessibility**: Always provide meaningful trigger labels
+5. **Responsive**: Test across different screen sizes
+
+## Examples
+
+### FAQ Section
+```tsx
+<Collapsible open={faqOpen} variant="smooth">
+  <CollapsibleContent>
+    <Typography variant="body2">
+      Detailed answer to the frequently asked question...
+    </Typography>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Navigation Menu
+```tsx
+<Collapsible open={menuOpen} variant="spring" duration={400}>
+  <CollapsibleContent>
+    <List>
+      <ListItem>Menu Item 1</ListItem>
+      <ListItem>Menu Item 2</ListItem>
+    </List>
+  </CollapsibleContent>
+</Collapsible>
+```
+
+## Integration Notes
+
+- Compatible with MUI theming system
+- Supports all MUI breakpoints for responsive design
+- Works with React 18+ concurrent features
+- TypeScript definitions included for full type safety