@rakeyshgidwani/roger-ui-bank-theme-jeremy 0.5.3

package/src/components/ui/layout/container.tsx

@@ -0,0 +1,312 @@
+/**
+ * Container Component
+ * Implements Phase 2 container max-widths and content width system
+ *
+ * Container Max-Widths:
+ * - xs: 100%, sm: 640px, md: 768px, lg: 1024px, xl: 1280px, 2xl: 1536px, 3xl: 1792px
+ *
+ * Content Width Patterns:
+ * - narrow: Optimal for reading content (65ch-75ch)
+ * - standard: General content (80%-90% width)
+ * - wide: Data/dashboards (90%-100% width)
+ */
+
+'use client'
+
+import * as React from 'react';
+
+export interface ContainerProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  children: React.ReactNode;
+
+  // Container type determines max-width behavior
+  type?: 'container' | 'content' | 'fluid';
+
+  // Content width patterns
+  width?: 'narrow' | 'standard' | 'wide' | 'full';
+
+  // Custom max-widths per breakpoint
+  maxWidths?: {
+    xs?: string;
+    sm?: string;
+    md?: string;
+    lg?: string;
+    xl?: string;
+    '2xl'?: string;
+    '3xl'?: string;
+  };
+
+  // Padding configuration
+  padding?: {
+    xs?: string;
+    sm?: string;
+    md?: string;
+    lg?: string;
+    xl?: string;
+    '2xl'?: string;
+    '3xl'?: string;
+  };
+
+  // Center container content
+  centered?: boolean;
+
+  // Allow content to break out of container on small screens
+  breakout?: boolean;
+
+  // Character-based width constraints (for reading content)
+  characterWidth?: {
+    min?: string; // e.g., '65ch'
+    max?: string; // e.g., '75ch'
+    optimal?: string; // e.g., '70ch'
+  };
+
+  // Component polymorphism
+  as?: keyof JSX.IntrinsicElements;
+}
+
+// Default container max-widths (from implementation plan)
+const DEFAULT_CONTAINER_MAX_WIDTHS = {
+  xs: '100%',
+  sm: '640px',
+  md: '768px',
+  lg: '1024px',
+  xl: '1280px',
+  '2xl': '1536px',
+  '3xl': '1792px'
+} as const;
+
+// Default content width patterns (from implementation plan)
+const CONTENT_WIDTH_PATTERNS = {
+  narrow: {
+    xs: '100%',
+    sm: '100%',
+    md: '65ch',
+    lg: '70ch',
+    xl: '75ch',
+    '2xl': '75ch',
+    '3xl': '75ch'
+  },
+  standard: {
+    xs: '100%',
+    sm: '100%',
+    md: '90%',
+    lg: '85%',
+    xl: '80%',
+    '2xl': '80%',
+    '3xl': '80%'
+  },
+  wide: {
+    xs: '100%',
+    sm: '100%',
+    md: '100%',
+    lg: '95%',
+    xl: '90%',
+    '2xl': '90%',
+    '3xl': '90%'
+  },
+  full: {
+    xs: '100%',
+    sm: '100%',
+    md: '100%',
+    lg: '100%',
+    xl: '100%',
+    '2xl': '100%',
+    '3xl': '100%'
+  }
+} as const;
+
+// Default padding configuration
+const DEFAULT_PADDING = {
+  xs: 'var(--cs-spacing-scale-md)',
+  sm: 'var(--cs-spacing-scale-lg)',
+  md: 'var(--cs-spacing-scale-xl)',
+  lg: 'var(--cs-spacing-scale-2xl)',
+  xl: 'var(--cs-spacing-scale-2xl)',
+  '2xl': 'var(--cs-spacing-scale-3xl)',
+  '3xl': 'var(--cs-spacing-scale-3xl)'
+} as const;
+
+export const Container: React.FC<ContainerProps> = ({
+  children,
+  type = 'container',
+  width = 'standard',
+  maxWidths: customMaxWidths,
+  padding: customPadding,
+  centered = true,
+  breakout = false,
+  characterWidth,
+  className = '',
+  style: userStyle,
+  as: Component = 'div',
+  ...restProps
+}) => {
+  const testId = (restProps as any)['data-testid'] || 'container';
+  // Determine max-widths based on type and width
+  const maxWidths = React.useMemo(() => {
+    if (customMaxWidths) {
+      return customMaxWidths;
+    }
+
+    switch (type) {
+      case 'container':
+        return DEFAULT_CONTAINER_MAX_WIDTHS;
+      case 'content':
+        return CONTENT_WIDTH_PATTERNS[width];
+      case 'fluid':
+        return CONTENT_WIDTH_PATTERNS.full;
+      default:
+        return DEFAULT_CONTAINER_MAX_WIDTHS;
+    }
+  }, [type, width, customMaxWidths]);
+
+  // Determine padding
+  const padding = customPadding || DEFAULT_PADDING;
+
+  // Build CSS custom properties
+  const containerStyle = React.useMemo(() => {
+    const style: React.CSSProperties & Record<string, any> = {};
+
+    // Set max-width configurations
+    Object.entries(maxWidths).forEach(([breakpoint, maxWidth]) => {
+      style[`--container-max-width-${breakpoint}`] = maxWidth;
+    });
+
+    // Set padding configurations
+    Object.entries(padding).forEach(([breakpoint, paddingValue]) => {
+      style[`--container-padding-${breakpoint}`] = paddingValue;
+    });
+
+    // Set character width constraints
+    if (characterWidth) {
+      if (characterWidth.min) {
+        style['--container-character-width-min'] = characterWidth.min;
+      }
+      if (characterWidth.max) {
+        style['--container-character-width-max'] = characterWidth.max;
+      }
+      if (characterWidth.optimal) {
+        style['--container-character-width-optimal'] = characterWidth.optimal;
+      }
+    }
+
+    return style;
+  }, [maxWidths, padding, characterWidth]);
+
+  // Build CSS classes
+  const containerClasses = React.useMemo(() => {
+    const baseClass = 'container';
+    const typeClass = `container--${type}`;
+    const widthClass = width !== 'standard' ? `container--width-${width}` : '';
+    const centeredClass = centered ? 'container--centered' : '';
+    const breakoutClass = breakout ? 'container--breakout' : '';
+    const characterWidthClass = characterWidth ? 'container--character-width' : '';
+
+    return [baseClass, typeClass, widthClass, centeredClass, breakoutClass, characterWidthClass, className]
+      .filter(Boolean)
+      .join(' ');
+  }, [type, width, centered, breakout, characterWidth, className]);
+
+  // Merge user styles with container styles
+  const mergedStyle = React.useMemo(() => ({
+    ...containerStyle,
+    ...userStyle
+  }), [containerStyle, userStyle]);
+
+  return (
+    <Component
+      className={containerClasses}
+      style={mergedStyle}
+      data-testid={testId}
+      {...(restProps as any)}
+    >
+      {children}
+    </Component>
+  );
+};
+
+// Content Container - Specialized for reading content
+export interface ContentContainerProps extends Omit<ContainerProps, 'type' | 'width'> {
+  // Reading optimization
+  lineLength?: 'short' | 'optimal' | 'long'; // Maps to character widths
+  textAlign?: 'left' | 'center' | 'justify';
+}
+
+export const ContentContainer: React.FC<ContentContainerProps> = ({
+  children,
+  lineLength = 'optimal',
+  textAlign = 'left',
+  characterWidth: customCharacterWidth,
+  style: userStyle,
+  ...props
+}) => {
+  // Map line length to character widths
+  const characterWidth = React.useMemo(() => {
+    if (customCharacterWidth) {
+      return customCharacterWidth;
+    }
+
+    switch (lineLength) {
+      case 'short':
+        return { min: '45ch', max: '65ch', optimal: '55ch' };
+      case 'optimal':
+        return { min: '65ch', max: '75ch', optimal: '70ch' };
+      case 'long':
+        return { min: '75ch', max: '85ch', optimal: '80ch' };
+      default:
+        return { min: '65ch', max: '75ch', optimal: '70ch' };
+    }
+  }, [lineLength, customCharacterWidth]);
+
+  const mergedStyle = React.useMemo(() => ({
+    textAlign: textAlign,
+    ...userStyle
+  }), [textAlign, userStyle]);
+
+  return (
+    <Container
+      type="content"
+      width="narrow"
+      characterWidth={characterWidth}
+      style={mergedStyle}
+      {...props}
+    >
+      {children}
+    </Container>
+  );
+};
+
+// Section Container - For page sections with full-width backgrounds
+export interface SectionContainerProps extends ContainerProps {
+  // Background behavior
+  fullWidthBackground?: boolean;
+  backgroundVariant?: 'default' | 'muted' | 'accent' | 'inverse';
+}
+
+export const SectionContainer: React.FC<SectionContainerProps> = ({
+  children,
+  fullWidthBackground = false,
+  backgroundVariant = 'default',
+  className = '',
+  ...props
+}) => {
+  const sectionClasses = React.useMemo(() => {
+    const baseClass = 'section-container';
+    const backgroundClass = fullWidthBackground ? 'section-container--full-width-bg' : '';
+    const variantClass = backgroundVariant !== 'default' ? `section-container--${backgroundVariant}` : '';
+
+    return [baseClass, backgroundClass, variantClass, className]
+      .filter(Boolean)
+      .join(' ');
+  }, [fullWidthBackground, backgroundVariant, className]);
+
+  return (
+    <Container
+      className={sectionClasses}
+      as="section"
+      {...props}
+    >
+      {children}
+    </Container>
+  );
+};
+
+export default Container;

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

@@ -0,0 +1,10 @@
+/**
+ * Layout Components Index
+ * Exports all layout components for Phase 2 implementation
+ */
+
+export { ResponsiveGrid, ResponsiveGridItem } from './responsive-grid';
+export type { ResponsiveGridProps, ResponsiveGridItemProps } from './responsive-grid';
+
+export { Container, ContentContainer, SectionContainer } from './container';
+export type { ContainerProps, ContentContainerProps, SectionContainerProps } from './container';

package/src/components/ui/layout/responsive-grid.tsx

@@ -0,0 +1,286 @@
+/**
+ * Responsive Grid Component
+ * Implements Phase 2 responsive grid system as defined in the implementation plan
+ *
+ * Grid Progression:
+ * - xs: 1 column (Single column mobile)
+ * - sm: 2 columns (2 columns small tablet)
+ * - md: 2 columns (2 columns tablet)
+ * - lg: 3 columns (3 columns desktop)
+ * - xl: 4 columns (4 columns large desktop)
+ * - 2xl: 4 columns (4 columns ultra-wide)
+ * - 3xl: 5 columns (5 columns large displays)
+ *
+ * Gap Progression:
+ * - xs: 16px, sm: 20px, md: 24px, lg: 28px, xl: 32px, 2xl: 36px, 3xl: 40px
+ */
+
+'use client'
+
+import * as React from 'react';
+
+export interface ResponsiveGridProps {
+  children: React.ReactNode;
+
+  // Column configuration per breakpoint
+  columns?: {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    '2xl'?: number;
+    '3xl'?: number;
+  };
+
+  // Gap configuration per breakpoint
+  gaps?: {
+    xs?: string;
+    sm?: string;
+    md?: string;
+    lg?: string;
+    xl?: string;
+    '2xl'?: string;
+    '3xl'?: string;
+  };
+
+  // Pre-defined grid patterns
+  pattern?: 'default' | 'content' | 'dashboard' | 'gallery' | 'cards';
+
+  // Layout behavior
+  autoFit?: boolean; // Use auto-fit instead of fixed columns
+  minItemWidth?: string; // Minimum width for auto-fit
+
+  // Alignment
+  alignItems?: 'start' | 'center' | 'end' | 'stretch';
+  justifyItems?: 'start' | 'center' | 'end' | 'stretch';
+
+  // Accessibility
+  'aria-label'?: string;
+  'data-testid'?: string;
+
+  // Styling
+  className?: string;
+}
+
+// Pre-defined grid patterns
+const GRID_PATTERNS = {
+  default: {
+    columns: { xs: 1, sm: 2, md: 2, lg: 3, xl: 4, '2xl': 4, '3xl': 5 },
+    gaps: { xs: '16px', sm: '20px', md: '24px', lg: '28px', xl: '32px', '2xl': '36px', '3xl': '40px' }
+  },
+  content: {
+    columns: { xs: 1, sm: 1, md: 2, lg: 2, xl: 3, '2xl': 3, '3xl': 4 },
+    gaps: { xs: '16px', sm: '20px', md: '24px', lg: '28px', xl: '32px', '2xl': '36px', '3xl': '40px' }
+  },
+  dashboard: {
+    columns: { xs: 1, sm: 2, md: 3, lg: 4, xl: 5, '2xl': 6, '3xl': 7 },
+    gaps: { xs: '12px', sm: '16px', md: '20px', lg: '24px', xl: '28px', '2xl': '32px', '3xl': '36px' }
+  },
+  gallery: {
+    columns: { xs: 2, sm: 3, md: 4, lg: 5, xl: 6, '2xl': 7, '3xl': 8 },
+    gaps: { xs: '8px', sm: '12px', md: '16px', lg: '20px', xl: '24px', '2xl': '28px', '3xl': '32px' }
+  },
+  cards: {
+    columns: { xs: 1, sm: 1, md: 2, lg: 3, xl: 3, '2xl': 4, '3xl': 4 },
+    gaps: { xs: '20px', sm: '24px', md: '28px', lg: '32px', xl: '36px', '2xl': '40px', '3xl': '44px' }
+  }
+} as const;
+
+export const ResponsiveGrid: React.FC<ResponsiveGridProps> = ({
+  children,
+  columns: customColumns,
+  gaps: customGaps,
+  pattern = 'default',
+  autoFit = false,
+  minItemWidth = '250px',
+  alignItems = 'stretch',
+  justifyItems = 'stretch',
+  'aria-label': ariaLabel,
+  'data-testid': testId = 'responsive-grid',
+  className = '',
+}) => {
+  // Get pattern configuration
+  const patternConfig = GRID_PATTERNS[pattern];
+
+  // Use custom configuration or fall back to pattern
+  const columns = customColumns || patternConfig.columns;
+  const gaps = customGaps || patternConfig.gaps;
+
+  // Build CSS custom properties for responsive grid
+  const gridStyle = React.useMemo(() => {
+    const style: React.CSSProperties & Record<string, any> = {};
+
+    // Set column configurations
+    Object.entries(columns).forEach(([breakpoint, columnCount]) => {
+      style[`--responsive-grid-columns-${breakpoint}`] = columnCount;
+    });
+
+    // Set gap configurations
+    Object.entries(gaps).forEach(([breakpoint, gapValue]) => {
+      style[`--responsive-grid-gap-${breakpoint}`] = gapValue;
+    });
+
+    // Set alignment
+    style['--responsive-grid-align-items'] = alignItems;
+    style['--responsive-grid-justify-items'] = justifyItems;
+
+    // Set auto-fit configuration
+    if (autoFit) {
+      style['--responsive-grid-min-item-width'] = minItemWidth;
+    }
+
+    return style;
+  }, [columns, gaps, alignItems, justifyItems, autoFit, minItemWidth]);
+
+  // Build CSS classes
+  const gridClasses = React.useMemo(() => {
+    const baseClass = 'responsive-grid';
+    const patternClass = `responsive-grid--${pattern}`;
+    const autoFitClass = autoFit ? 'responsive-grid--auto-fit' : '';
+
+    return [baseClass, patternClass, autoFitClass, className]
+      .filter(Boolean)
+      .join(' ');
+  }, [pattern, autoFit, className]);
+
+  return (
+    <div
+      className={gridClasses}
+      style={gridStyle}
+      aria-label={ariaLabel}
+      data-testid={testId}
+    >
+      {children}
+    </div>
+  );
+};
+
+// Grid Item Component for explicit control
+export interface ResponsiveGridItemProps {
+  children: React.ReactNode;
+
+  // Spanning configuration
+  colSpan?: {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    '2xl'?: number;
+    '3xl'?: number;
+  };
+
+  rowSpan?: {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    '2xl'?: number;
+    '3xl'?: number;
+  };
+
+  // Position configuration
+  colStart?: {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    '2xl'?: number;
+    '3xl'?: number;
+  };
+
+  rowStart?: {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+    '2xl'?: number;
+    '3xl'?: number;
+  };
+
+  // Alignment (overrides grid defaults)
+  alignSelf?: 'auto' | 'start' | 'center' | 'end' | 'stretch';
+  justifySelf?: 'auto' | 'start' | 'center' | 'end' | 'stretch';
+
+  // Styling
+  className?: string;
+  'data-testid'?: string;
+}
+
+export const ResponsiveGridItem: React.FC<ResponsiveGridItemProps> = ({
+  children,
+  colSpan,
+  rowSpan,
+  colStart,
+  rowStart,
+  alignSelf = 'auto',
+  justifySelf = 'auto',
+  className = '',
+  'data-testid': testId = 'responsive-grid-item',
+}) => {
+  // Build CSS custom properties for grid item
+  const itemStyle = React.useMemo(() => {
+    const style: React.CSSProperties & Record<string, any> = {};
+
+    // Set column span configurations
+    if (colSpan) {
+      Object.entries(colSpan).forEach(([breakpoint, span]) => {
+        style[`--responsive-grid-item-col-span-${breakpoint}`] = span;
+      });
+    }
+
+    // Set row span configurations
+    if (rowSpan) {
+      Object.entries(rowSpan).forEach(([breakpoint, span]) => {
+        style[`--responsive-grid-item-row-span-${breakpoint}`] = span;
+      });
+    }
+
+    // Set column start configurations
+    if (colStart) {
+      Object.entries(colStart).forEach(([breakpoint, start]) => {
+        style[`--responsive-grid-item-col-start-${breakpoint}`] = start;
+      });
+    }
+
+    // Set row start configurations
+    if (rowStart) {
+      Object.entries(rowStart).forEach(([breakpoint, start]) => {
+        style[`--responsive-grid-item-row-start-${breakpoint}`] = start;
+      });
+    }
+
+    // Set alignment
+    style['--responsive-grid-item-align-self'] = alignSelf;
+    style['--responsive-grid-item-justify-self'] = justifySelf;
+
+    return style;
+  }, [colSpan, rowSpan, colStart, rowStart, alignSelf, justifySelf]);
+
+  // Build CSS classes
+  const itemClasses = React.useMemo(() => {
+    const baseClass = 'responsive-grid-item';
+    const spanClass = colSpan || rowSpan ? 'responsive-grid-item--has-span' : '';
+    const positionClass = colStart || rowStart ? 'responsive-grid-item--has-position' : '';
+
+    return [baseClass, spanClass, positionClass, className]
+      .filter(Boolean)
+      .join(' ');
+  }, [colSpan, rowSpan, colStart, rowStart, className]);
+
+  return (
+    <div
+      className={itemClasses}
+      style={itemStyle}
+      data-testid={testId}
+    >
+      {children}
+    </div>
+  );
+};
+
+export default ResponsiveGrid;