@12-apps/ui 1.0.0

package/src/components/data-display/Banner/Banner.tsx

@@ -0,0 +1,350 @@
+import { 
+  CheckCircle, 
+  Close,
+  Error, 
+  Info, 
+  Warning, 
+} from '@mui/icons-material';
+import {
+  alpha,
+  Box,
+  Button,
+  IconButton,
+  keyframes,
+  Typography,
+} from '@mui/material';
+import type { Theme } from '@mui/material/styles';
+import { styled } from '@mui/material/styles';
+import React from 'react';
+
+import type { BannerProps, BannerVariant } from './Banner.types';
+
+// Animations
+const fadeInSlide = keyframes`
+  from {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+`;
+
+const pulseAnimation = keyframes`
+  0% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 0.7;
+  }
+  70% {
+    box-shadow: 0 0 0 8px currentColor;
+    opacity: 0;
+  }
+  100% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 0;
+  }
+`;
+
+const getVariantIcon = (variant: BannerVariant) => {
+  const iconMap: Record<BannerVariant, React.ReactNode> = {
+    info: <Info />,
+    success: <CheckCircle />,
+    warning: <Warning />,
+    critical: <Error />,
+  };
+  return iconMap[variant];
+};
+
+const getVariantColor = (theme: Theme, variant: BannerVariant) => {
+  const colorMap = {
+    info: theme.palette.info,
+    success: theme.palette.success,
+    warning: theme.palette.warning,
+    critical: theme.palette.error,
+  };
+  return colorMap[variant];
+};
+
+const StyledBanner = styled(Box, {
+  shouldForwardProp: (prop) => !['variant', 'sticky', 'fullWidth'].includes(prop as string),
+})<{
+  variant: BannerVariant;
+  sticky: boolean;
+  fullWidth: boolean;
+}>(({ theme, variant, sticky, fullWidth }) => {
+  const colorPalette = getVariantColor(theme, variant);
+
+  return {
+    display: 'flex',
+    alignItems: 'flex-start',
+    gap: theme.spacing(1.5),
+    padding: theme.spacing(1.5, 2),
+    borderRadius: theme.spacing(1),
+    backgroundColor: alpha(colorPalette.main, 0.1),
+    border: `1px solid ${alpha(colorPalette.main, 0.2)}`,
+    color: colorPalette.main,
+    position: sticky ? 'sticky' : 'relative',
+    top: sticky ? 0 : 'auto',
+    zIndex: sticky ? theme.zIndex.appBar : 'auto',
+    width: fullWidth ? '100vw' : '100%',
+    marginLeft: fullWidth ? '50%' : 0,
+    transform: fullWidth ? 'translateX(-50%)' : 'none',
+    animation: `${fadeInSlide} 0.3s ease-out`,
+    transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+
+    // Enhanced accessibility and focus styles
+    '&:focus-within': {
+      outline: `3px solid ${alpha(colorPalette.main, 0.5)}`,
+      outlineOffset: '2px',
+    },
+
+    // Icon container
+    '.banner-icon': {
+      flexShrink: 0,
+      marginTop: theme.spacing(0.25),
+      color: colorPalette.main,
+      fontSize: '1.25rem',
+      display: 'flex',
+      alignItems: 'center',
+      position: 'relative',
+
+      '&::before': {
+        content: '""',
+        position: 'absolute',
+        inset: -4,
+        borderRadius: '50%',
+        background: alpha(colorPalette.main, 0.1),
+        animation: `${pulseAnimation} 3s infinite`,
+      },
+    },
+
+    // Content area
+    '.banner-content': {
+      flex: 1,
+      minWidth: 0, // Prevents flex item overflow
+    },
+
+    // Title styles
+    '.banner-title': {
+      fontWeight: 600,
+      fontSize: '1rem',
+      lineHeight: 1.4,
+      marginBottom: theme.spacing(0.5),
+      color: colorPalette.dark || colorPalette.main,
+    },
+
+    // Description styles  
+    '.banner-description': {
+      fontSize: '0.875rem',
+      lineHeight: 1.5,
+      opacity: 0.9,
+      color: 'inherit',
+    },
+
+    // Actions area
+    '.banner-actions': {
+      display: 'flex',
+      flexShrink: 0,
+      gap: theme.spacing(1),
+      alignItems: 'center',
+      marginTop: theme.spacing(1),
+
+      [theme.breakpoints.up('sm')]: {
+        marginTop: 0,
+        marginLeft: theme.spacing(2),
+      },
+    },
+
+    // Dismiss button
+    '.banner-dismiss': {
+      color: 'inherit',
+      opacity: 0.7,
+      marginLeft: theme.spacing(1),
+      flexShrink: 0,
+
+      '&:hover': {
+        opacity: 1,
+        backgroundColor: alpha(colorPalette.main, 0.1),
+        transform: 'rotate(90deg)',
+      },
+
+      '&:focus': {
+        opacity: 1,
+        outline: `2px solid ${colorPalette.main}`,
+        outlineOffset: '2px',
+      },
+    },
+
+    // Responsive layout
+    [theme.breakpoints.down('sm')]: {
+      flexDirection: 'column',
+      alignItems: 'stretch',
+      gap: theme.spacing(1),
+      
+      '.banner-content': {
+        order: 1,
+      },
+
+      '.banner-actions': {
+        order: 2,
+        justifyContent: 'flex-start',
+        marginTop: theme.spacing(1),
+        marginLeft: 0,
+      },
+    },
+
+    // Glass effect variant (optional enhancement)
+    '&.banner-glass': {
+      backgroundColor: alpha(theme.palette.background.paper, 0.1),
+      backdropFilter: 'blur(20px)',
+      border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+      color: theme.palette.text.primary,
+      
+      '.banner-icon': {
+        color: colorPalette.main,
+      },
+    },
+  };
+});
+
+export const Banner = React.forwardRef<HTMLDivElement, BannerProps>(
+  (
+    {
+      variant = 'info',
+      title,
+      description,
+      icon,
+      dismissible = false,
+      onDismiss,
+      actions,
+      sticky = false,
+      fullWidth = false,
+      className,
+      children,
+      'data-testid': dataTestId = 'banner',
+      ...props
+    },
+    ref,
+  ) => {
+    const [visible, setVisible] = React.useState(true);
+
+    const handleDismiss = React.useCallback(() => {
+      setVisible(false);
+      onDismiss?.();
+    }, [onDismiss]);
+
+    const displayIcon = icon || getVariantIcon(variant);
+
+    // Determine appropriate ARIA role based on variant
+    const ariaRole = variant === 'warning' || variant === 'critical' ? 'alert' : 'status';
+    const ariaLive = variant === 'critical' ? 'assertive' : 'polite';
+
+    if (!visible) {
+      return null;
+    }
+
+    return (
+      <StyledBanner
+        ref={ref}
+        variant={variant}
+        sticky={sticky}
+        fullWidth={fullWidth}
+        className={className}
+        role={ariaRole}
+        aria-live={ariaLive}
+        aria-atomic="true"
+        tabIndex={0}
+        data-testid={dataTestId}
+        {...props}
+      >
+        {/* Icon */}
+        {displayIcon && (
+          <Box className="banner-icon" aria-hidden="true" data-testid={dataTestId ? `${dataTestId}-icon` : 'banner-icon'}>
+            {displayIcon}
+          </Box>
+        )}
+
+        {/* Main content */}
+        <Box className="banner-content">
+          {title && (
+            <Typography className="banner-title" variant="subtitle2" component="div" data-testid={dataTestId ? `${dataTestId}-title` : 'banner-title'}>
+              {title}
+            </Typography>
+          )}
+          {description && (
+            <Typography className="banner-description" variant="body2" component="div" data-testid={dataTestId ? `${dataTestId}-message` : 'banner-message'}>
+              {description}
+            </Typography>
+          )}
+          {children}
+        </Box>
+
+        {/* Actions and dismiss button container */}
+        <Box display="flex" alignItems="center" gap={1}>
+          {/* Action buttons */}
+          {actions && actions.length > 0 && (
+            <Box className="banner-actions">
+              {actions.map((action, index) => (
+                <Button
+                  key={index}
+                  size="small"
+                  variant={action.variant === 'primary' ? 'contained' : 'outlined'}
+                  onClick={action.onClick}
+                  data-testid={dataTestId ? `${dataTestId}-action` : 'banner-action'}
+                  sx={(theme) => ({
+                    minWidth: 'auto',
+                    px: 1.5,
+                    py: 0.5,
+                    fontSize: '0.8125rem',
+                    fontWeight: 500,
+                    borderRadius: 1,
+                    
+                    ...(action.variant === 'primary' && {
+                      backgroundColor: getVariantColor(theme, variant).main,
+                      color: theme.palette.getContrastText(getVariantColor(theme, variant).main),
+                      
+                      '&:hover': {
+                        backgroundColor: getVariantColor(theme, variant).dark || getVariantColor(theme, variant).main,
+                        transform: 'translateY(-1px)',
+                      },
+                    }),
+                    
+                    ...(action.variant === 'secondary' && {
+                      borderColor: getVariantColor(theme, variant).main,
+                      color: getVariantColor(theme, variant).main,
+                      
+                      '&:hover': {
+                        backgroundColor: alpha(getVariantColor(theme, variant).main, 0.1),
+                        borderColor: getVariantColor(theme, variant).main,
+                        transform: 'translateY(-1px)',
+                      },
+                    }),
+                  })}
+                >
+                  {action.label}
+                </Button>
+              ))}
+            </Box>
+          )}
+
+          {/* Dismiss button */}
+          {dismissible && (
+            <IconButton
+              className="banner-dismiss"
+              size="small"
+              onClick={handleDismiss}
+              aria-label="Dismiss banner"
+              data-testid={dataTestId ? `${dataTestId}-close` : 'banner-close'}
+              sx={{ transition: 'all 0.2s ease' }}
+            >
+              <Close fontSize="small" />
+            </IconButton>
+          )}
+        </Box>
+      </StyledBanner>
+    );
+  },
+);
+
+Banner.displayName = 'Banner';

package/src/components/data-display/Banner/Banner.types.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+
+export type BannerVariant = 'info' | 'success' | 'warning' | 'critical';
+
+export type BannerActionVariant = 'primary' | 'secondary';
+
+export interface BannerAction {
+  /** Button label text */
+  label: string;
+  /** Click handler function */
+  onClick: () => void;
+  /** Visual style variant */
+  variant?: BannerActionVariant;
+}
+
+export interface BannerProps {
+  /** Message severity type */
+  variant?: BannerVariant;
+  /** Main message title text */
+  title?: string;
+  /** Additional description text */
+  description?: string;
+  /** Custom icon React node */
+  icon?: ReactNode;
+  /** Whether banner can be dismissed */
+  dismissible?: boolean;
+  /** Callback when banner is dismissed */
+  onDismiss?: () => void;
+  /** Array of action buttons */
+  actions?: BannerAction[];
+  /** Affix banner to top on scroll */
+  sticky?: boolean;
+  /** Span container or full viewport width */
+  fullWidth?: boolean;
+  /** Custom CSS class name */
+  className?: string;
+  /** Children content */
+  children?: ReactNode;
+  /** Test ID for component testing */
+  'data-testid'?: string;
+}

package/src/components/data-display/Banner/banner.md

@@ -0,0 +1,141 @@
+# Banner Component
+
+**Purpose:** Page-level notification bar for system messages.
+
+```ts
+interface BannerProps {
+  variant?: 'info' | 'success' | 'warning' | 'critical';
+  title?: string;
+  description?: string;
+  icon?: React.ReactNode;
+  dismissible?: boolean;
+  onDismiss?: () => void;
+  actions?: Array<{ label: string; onClick: () => void; variant?: 'primary' | 'secondary' }>;
+  sticky?: boolean; // affix to top on scroll
+  fullWidth?: boolean; // span container or viewport
+  className?: string;
+  'data-testid'?: string;
+}
+```
+
+**Features**
+
+- Strong visual hierarchy by variant; optional sticky behavior.
+- Inline actions (primary/secondary) and dismiss control.
+- Supports compact and spacious density via CSS modifiers.
+
+**A11y**
+
+- `role="status"` for info/success; `role="alert"` for warning/critical.
+- If `dismissible`, the close button has `aria-label="Dismiss"`.
+- Do not auto-focus; rely on live regions for screen readers.
+
+**Stories / Tests**
+
+- Variants; With/without actions; Dismissible; Sticky; Responsive.
+
+## Testing
+
+### Test IDs
+
+The Banner component includes `data-testid` attributes for reliable testing:
+
+| Test ID | Element | Description |
+|---------|---------|-------------|
+| `banner` or `{dataTestId}` | Main container | Root StyledBanner element (default: 'banner') |
+| `banner-icon` or `{dataTestId}-icon` | Icon container | Box wrapping the variant icon or custom icon |
+| `banner-title` or `{dataTestId}-title` | Title text | Typography element for the banner title |
+| `banner-message` or `{dataTestId}-message` | Message text | Typography element for the banner description/message |
+| `banner-action` or `{dataTestId}-action` | Action button | Individual action button (same testId for all actions) |
+| `banner-close` or `{dataTestId}-close` | Dismiss button | IconButton for dismissing the banner |
+
+### Testing Best Practices
+
+**Wait for Banner to Render:**
+```typescript
+// Use async queries to wait for the banner
+const banner = await canvas.findByTestId('banner');
+expect(banner).toBeInTheDocument();
+
+// Check variant styling
+expect(banner).toHaveAttribute('role', 'status'); // for info/success
+expect(banner).toHaveAttribute('aria-live', 'polite');
+```
+
+**Test Variant Rendering:**
+```typescript
+// Test critical variant
+const criticalBanner = await canvas.findByTestId('banner');
+expect(criticalBanner).toHaveAttribute('role', 'alert');
+expect(criticalBanner).toHaveAttribute('aria-live', 'assertive');
+
+// Verify icon is present
+const icon = await canvas.findByTestId('banner-icon');
+expect(icon).toBeInTheDocument();
+```
+
+**Test Content Display:**
+```typescript
+// Test title and message
+const title = await canvas.findByTestId('banner-title');
+expect(title).toHaveTextContent('Important Update');
+
+const message = await canvas.findByTestId('banner-message');
+expect(message).toHaveTextContent('System maintenance scheduled');
+```
+
+**Test Actions:**
+```typescript
+// Test action button (Note: all action buttons share the same testId)
+const actionButton = await canvas.findByTestId('banner-action');
+await userEvent.click(actionButton);
+expect(mockOnClick).toHaveBeenCalledTimes(1);
+
+// When multiple actions exist, use getAllByTestId
+const actionButtons = await canvas.findAllByTestId('banner-action');
+expect(actionButtons).toHaveLength(2);
+await userEvent.click(actionButtons[0]); // Click first action
+await userEvent.click(actionButtons[1]); // Click second action
+```
+
+**Test Dismissible Behavior:**
+```typescript
+// Test dismiss button
+const closeButton = await canvas.findByTestId('banner-close');
+expect(closeButton).toBeInTheDocument();
+expect(closeButton).toHaveAttribute('aria-label', 'Dismiss banner');
+
+// Click dismiss and verify callback
+await userEvent.click(closeButton);
+expect(mockOnDismiss).toHaveBeenCalledTimes(1);
+
+// Verify banner is removed from DOM
+await waitFor(() => {
+  expect(canvas.queryByTestId('banner')).not.toBeInTheDocument();
+}, { timeout: 1000 });
+```
+
+**Test Custom Test IDs:**
+```typescript
+// Use custom data-testid
+render(<Banner data-testid="custom-banner" title="Test" />);
+
+const customBanner = await canvas.findByTestId('custom-banner');
+expect(customBanner).toBeInTheDocument();
+
+const customIcon = await canvas.findByTestId('custom-banner-icon');
+expect(customIcon).toBeInTheDocument();
+```
+
+### Common Test Scenarios
+
+1. **Variant Rendering** - Test all variants (info, success, warning, critical) with correct colors and icons
+2. **Content Display** - Verify title, description, and children render correctly
+3. **Actions** - Test primary and secondary action buttons with click handlers
+4. **Dismissible** - Test dismiss functionality and onDismiss callback
+5. **Sticky Behavior** - Verify sticky positioning and z-index
+6. **Full Width** - Test fullWidth prop styling
+7. **Custom Icons** - Verify custom icon rendering
+8. **Responsive Layout** - Test mobile/tablet viewports and layout changes
+9. **Accessibility** - Verify ARIA roles, live regions, and keyboard navigation
+10. **Animations** - Check fade-in animation and pulse effects on icon

package/src/components/data-display/Banner/index.ts

@@ -0,0 +1,2 @@
+export { Banner } from './Banner';
+export type { BannerAction, BannerActionVariant, BannerProps, BannerVariant } from './Banner.types';